Ridgeline Finance OS — Freight Accrual Engine

Finance Engineer Cup, Round 1. An auditable, gated freight-accrual estimation engine for Ridgeline Foods, built as the first process inside a generalized finance command center.

It estimates April 2026 freight expense from shipment data plus three carrier rate cards, and it beats the predecessor's trailing-3-month average.

Booked accrual (April 2026)	$103,402
90% confidence band	$78,301 to $128,504
Denise's trailing-3mo average	$95,273
Improvement vs baseline	engine lands inside the band every backtested month; Denise missed by $5K to $13K
Carriers	Peak Logistics, Heartland Freight, Coastal Express
Shipments priced	161 (deduped, missing weights inferred)

---

What it is

The screen you land on is not a report. It is a command center for a process that, in the target state, runs itself. A human drops in to review and sign, not to do the math. The work is deterministic by default, agentic by exception: rate math is pure code, the realization factor and confidence band are statistical, and only the exceptions reach a person.

Three operational surfaces plus a configuration tab, all driven by one persisted Process model:

• Monitor — the overseer's check-in. Hero number, 90% band, per-carrier outcomes, the materiality gate queue, the staged journal entry, and the sign-off button.
• Execute — the agent's surface. Every step of the run (ingest, price, calibrate, baseline, estimate, exceptions, gate, post JE, reconcile) shown as Data in, Processing, Outcome.
• Improve — the self-review loop. Forward-replay backtest of this engine vs Denise, mean absolute error by carrier, 90% band coverage, and concrete policy-tuning proposals.
• Setup — the process definition: steps, versioned policies, the tool registry, and the improvement trigger.

The materiality gate sits before the JE posts. If any carrier escalates, the run pauses at awaiting_human with the JE staged but not posted until someone signs off.

---

The accrual approach (why it beats the average)

1. Deterministic pricing [D]. Every shipment is priced against the correct carrier model: Peak per-mile by weight tier with mileage resolution and a $185 floor; Heartland flat zone rate by ZIP prefix with the quarterly volume discount that resets April 1 (Q2 month 1, Tier 1, 0%); Coastal per-pound by region with tiered residential surcharge, 9.5% fuel, and a $32 floor. This produces the contract baseline.
2. Realization factor [A]. Six months of historical invoices teach a per-carrier factor (median of actual-to-contract) that captures what invoices actually land at versus the contract: Peak 1.032, Heartland 1.048, Coastal 1.004.
3. Regime-aware ensemble [A]. An inverse-variance blend of the engine estimate and the trailing baseline, with engine weight lifted when a volume or mix shift is detected (this is exactly the Heartland-tier-reset trap that cost Denise $7,133 in January).
4. Confidence band + gate. A 90% band from the calibration spread. A carrier auto-posts only if its half-band is under the materiality threshold ($1,500) and its CV is under the max (0.15); otherwise it escalates to a human.

Every parameter in steps 2 to 4 is a versioned Policy object, not a magic number in code. The algorithm stays in code; the knobs are data the Improve loop can tune.

---

Stack

• Engine — pure Node, no DB dependency, runs live from the CSV data files (services/accrual/*). This is the validated deterministic core.
• Persistence — Prisma + PostgreSQL. Generalized model: Process -> Step / Policy / Tool -> AccrualRun -> StepExecution, plus an append-only LedgerEvent system of record and ObjectVersion for policy versioning.
• Web — Express + EJS, server-side rendered, light mode, CFO-ready.
• MCP — a Model Context Protocol server (mcp/server.js) exposing the whole pipeline as 10 reusable tools so any agent can drive the loop.

---

Setup

Prerequisites: Node 18+, PostgreSQL 14+ running locally.

# 1. Install
npm install

# 2. Configure the database URL
cp .env.example .env
#    edit .env so DATABASE_URL points at your Postgres, e.g.
#    DATABASE_URL=postgresql://<you>@localhost:5432/ridgeline

# 3. Create the database (once)
createdb ridgeline

# 4. Apply schema + seed the process, policies, tools, and load the CSV data
npx prisma migrate deploy        # or: npx prisma db push
npm run seed

# 5. Produce the April run (creates the system-of-record run)
npm run run-accrual

# 6. Start the web app
npm start
#    open http://localhost:3000   (set PORT to change)

You land on the Monitor surface with the April run staged at awaiting_human. Sign off in the UI to post the journal entry.

---

MCP server

The pipeline is exposed as MCP tools so it is reusable from Claude Desktop or any agent.

npm run mcp        # stdio transport

Register it with an MCP client using mcp/claude_desktop_config.example.json (update cwd and DATABASE_URL).

Tools — process-agnostic verbs that operate on ANY process by slug (runs default to the freight accrual process so the demo works without one). There are no process-specific tools.

Tool	What it does	Side effects
run_execute	Run and persist the stepped process	creates a run
run_list	List persisted runs	none
run_get	Full run detail, the audit trail	none
run_sign_off	Post the staged JE (human approval)	posts JE
run_freeze	Lock a run for period close	freezes
run_reconcile	Reconcile a posted run against actuals	writes variance rows
improve_propose	Generate param-targeted improvement proposals	writes proposals
improve_apply	Apply a proposal as a new policy version	bumps version
improve_list_versions	Policy version-audit history	none
process_create	Create a process (blank or clone)	creates a process
process_get_config / process_get_policies	Read a process spec / its versioned policy params	none
process_set_policy	Tune a policy param by key (writes audit row)	bumps version
process_add_step / process_update_step / process_delete_step	Edit the step checklist	mutates config
process_add_policy / process_update_policy / process_delete_policy	Edit policies	mutates config
process_map_tool / process_attach_step_tool (+ unbind/detach)	Bind tools to a process/step	mutates config
process_supervise / process_get_owner_agent / process_provision_owner_agent	Supervision tick + owner agent	tick may run/nudge

30 tools in total across Runs, Improve, Process configuration, and Supervision. See /docs/mcp for the full reference. A REST mirror of the same surface lives at /api/fos/* (/docs/api).

---

Messy-data handling

• Carrier name variants normalized (6 raw forms to 3 canonical).
• Duplicate shipments deduped by id.
• Missing weights inferred from per-carrier median lbs/unit.
• Heartland zones are ZIP-prefix based, not state (Kansas City KS 661xx is Zone 1, the rest of KS is Zone 2).
• Peak missing mileage flagged; out-of-territory destinations (for example Reno) raised as critical exceptions.
• Heartland Q2 reset handled by quarter-to-date cumulative volume tiering.

Each data issue is logged as an Exception with a severity and surfaces in the overseer queue.

---

Controls and auditability

• 90% confidence band on every carrier and the portfolio.
• Materiality times confidence gate decides auto-post vs escalate.
• Critical anomaly flags (out-of-territory, unknown carrier, missing weight).
• Append-only event ledger: every material action with actor and timestamp.
• Runs pin the policy versions they used, so a past run is exactly reproducible.
• Sign-off and freeze produce an immutable system of record.

---

What I would improve next

• Per-shipment accessorial prediction from invoice history instead of the per-carrier accessorial rate, to tighten the band further.
• Wire the Improve loop's process_set_policy proposals to an in-UI approve action so tuning is one click.
• Add a second process (for example a rebate or commission accrual) to prove the model generalizes beyond freight.
• Replace the seeded historical backtest with a rolling monthly close cadence on real invoice arrivals.

---

Repo map

services/accrual/      validated deterministic engine (ingest, rate engine, calibrate, estimate, learn)
services/accrual/runService.js   stepped runner + persistence (gate-before-post)
routes/financeOs.js    SSR surfaces + run actions
routes/fosApi.js       REST API mirror
mcp/server.js          MCP server (10 tools)
views/fos/             Monitor / Execute / Improve / Setup
prisma/schema.prisma   generalized Process model
prisma/seed.js         seeds the process, policies, tools, loads CSV data
data/                  the challenge data files
scripts/run-once.js    produce a run from the CLI