Lead scoring and routing you can explain a year later

What it models

A lead is captured, then moves through five explicit actions: record-signal appends an immutable behavioral signal deduped by source key; enrich calls a provider and stores an immutable snapshot with its provenance; score runs a versioned model and writes a ScoreRun plus one contribution per rule; route runs a versioned policy and writes a RoutingRun, one evaluation row per candidate, and an assignment. Qualification and conversion then turn the lead into a Company, a Contact and an Opportunity.

Everything the run touched stays readable afterwards. The snapshot, the signals, the score run and its contributions, the routing run and its per-candidate evaluations, and the assignment history are all separate records with get and list only — there is no public create or update on any of them, so no client can write a score or forge an assignment. Traces are queryable by workflow name (lead.enrich, lead.score, lead.route) and every mutation leaves an audit event.

Eligibility for a routing target is active status, a score band and capacity, where current load is the exact indexed count of active leads assigned to that target. Converting or disqualifying a lead releases its slot. Ties break by priority descending, then load ascending, then key — never by randomness, so the same inputs produce the same assignment every time.

How a coding agent builds it

Providers, scoring models, routing policies and targets are checked-in JavaScript definitions registered through one generated index file. The repository ships that file empty; the starter writes it. Each {name, version} pair persists a deterministic declared-definition fingerprint at startup, in a single transaction, so concurrent boots serialize.

Versions are published, never edited. Editing the source of a registered version stops the application on the next boot rather than silently changing what an old score meant. Rollback is publishing a new version derived from an earlier definition — v3 carrying v1's rules — because git history is not runtime policy versioning.

The fingerprint captures a definition's own source plus its declared config, which is passed frozen to every evaluation. A handler that closes over a mutable outer variable or an out-of-file helper is not captured, so every threshold and tunable belongs in config. Unsupported values there — Date, Map, Set, class instances, BigInt, symbols, NaN, cycles — fail fingerprinting loudly rather than producing a fingerprint that does not describe the definition.

The agent-facing instructions are in the build-lead-intelligence skill, mirrored for other harnesses as docs/LEAD_INTELLIGENCE.md.

What the framework refuses

The provider call happens in the action's prepare phase, outside the write transaction. A provider outage, timeout or out-of-contract payload becomes a stable PROVIDER_FAILED, PROVIDER_TIMEOUT or PROVIDER_INVALID with nothing persisted and an honest failed trace — never a partial snapshot and never an invented value.

Routing refuses an unscored lead with 409 LEAD_NOT_SCORED and an already-assigned one with 409 ALREADY_ASSIGNED. When no target is eligible it falls to the single declared fallback queue with a recorded reason, and if there is no fallback it refuses with 409 NO_ELIGIBLE_TARGET rather than picking someone. Under concurrency across connections exactly one final assignment survives; a race for the last capacity slot never oversubscribes a target.

Enrich, score and record-signal run only from the new and qualified states; route runs only from new. Converted and disqualified leads sit outside the intelligence lifecycle, enforced server-side by declared from-states and merely mirrored by the Admin.

What proves it

tests/lead-intelligence-e2e.test.js drives capture through assignment, including the provider failure modes, the concurrency race for a last capacity slot, and the reproduction of a historical routing decision after the target data has changed. tests/intelligence-contract.test.js holds the definition and fingerprint contract, and the qualification and conversion suites cover the lead's own lifecycle.

The starter application runs three leads end to end and lands them on Enterprise Italy, Spain Sales and the fallback queue respectively — a composed run, not a fixture assertion.

Where it stops

There is no real data vendor, no ranked work queue, no manual reassignment and no capacity calendar. The parts that would make any of those safe — authentication, tenancy and role enforcement — are Production Spine work that has not been done, and the boundary is stated here rather than left for a reader to discover after they have loaded real people into it.