Claims Plane — Processing Claims, Guarded Transitions, and Declarative Packs

Audience: Developers creating claims, evaluating guards, or consuming the lifecycle event spine. Status: As of 2026-11-09 — this map records only what the routes, module headers, strata, seeded scenario files, and seeded lookups show; no LIVE readiness claim beyond per-endpoint probes.

Blueprint sources

• Claims route surface and desk headers (claim creation, guarded transition, outbox, spine consumer, guard, policy loader, panel, meter clock, quorum bands, add-on eligibility, intake maps, correlation, voyage, pack, readiness, metrics).
• Processing-claim stratum header and allowed-transition map.
• Six seeded Kenya scenario packs (motor, medical, home, government benefit, government compensation, community ticket).
• Seeded declarative value groups for transition policy, separation, thresholds, evidence, panel, meter clocks, add-on eligibility, outbox subjects, and intake maps.
• Spine consumer live-verification script.

Facts

• The plane is a single generalised processing-claim primitive: the data plane enforces the lifecycle, the runtime resolves declarative policy values from value groups and scenario packs from scenario groups, and the transactional outbox carries lifecycle events to the spine consumer.
• Packs supply values only; the runner never branches on claim type, and swapping a value group changes refusal rules with zero code change. A referenced-but-missing value fails closed, never an invented default.
• Self-check is plan-only: it validates references and produces zero writes with the live gate unmet.

1. Lifecycle state machine — in prose

A claim has eight states. It begins as a draft. From a draft it may be submitted or cancelled. A submitted claim may move to validation, be rejected, or be cancelled. A claim in validation may be approved, rejected, or disputed. An approved claim may settle or be disputed. A rejected claim may be disputed or cancelled. A disputed claim may return to validation or be cancelled. A settled claim and a cancelled claim are both terminal with no outgoing moves.

Every move is recorded as a step with the from-state, to-state, actor, and optional notes. Creation stamps the first step from empty to draft. A move also appends an execution-proof step with input and output digests when an execution session exists, and updates the updated timestamp. Finalisation accepts only approved, settled, or rejected claims and requires an execution session; anything else is refused.

The runtime guarded runner is a second gate in front of the raw move. It evaluates gate, quorum, separation, evidence, and external-verdict stages in order from the declarative transition-policy values and refuses on any failing stage with a validation error, never advancing silently. The dry-run route exposes that runner without mutation.

2. Capability desks — interface catalog

Static routes are registered before parameterised claim routes; ordering matters.

Supporting behaviour: creation stamps one voyage identity with the priority explicit voyage identity, then explicit correlation identity, then a deterministic value derived from the claim identity, type, and subject. Transition and finalise enqueue through the live data-plane adapter. The router tolerates either enveloped or bare result shapes so it does not depend on one envelope.

3. Guard kinds — described behaviourally

Stages evaluate in order and any failing stage refuses the transition.

• Gate stage. Confirms the claim has entered the guarded path with the required execution-proof session.
• Quorum stage. Confirms a multi-signer quorum has reached its threshold for the selected band; too few signers refuses, never invents a signer.
• Separation stage. Confirms the mover is not barred from approving their own claim and that barred pairs do not co-approve. Community tickets use the lenient form that allows the creator; insurance and government lines forbid the creator.
• Evidence stage. Confirms the required evidence references are present for the claim type; motor lines demand photos and authority reports, medical lines demand service codes and clinical reports, government lines demand audit references, community lines demand a triage note.
• Execution-proof stage. Confirms the proof session satisfies the required events and minimum steps.
• External-verdict stage. Confirms the external verdict required by the policy has been recorded.

4. Pack geometries as use cases

Each pack is soft-only with validation-only apply, zero declared writes, and idempotent validation. Soft apply validates references against the value groups and the name catalogue. Market overlay is Kenya shillings and Nairobi time in all six. Advisory intelligence hooks are present but disabled, with suggested type, severity, language, and evidence-completeness hints. Meter-clock binding to the workflow engine is required.

Shared seam: the consumer's default scenario set mirrors exactly these six keys. The panel covers only insurance lines in the seeded values; government and community lines have no panel mesh.

5. Panel, meter clock, quorum bands, add-ons

Panel (composed membership, declarative eligibility). The panel is not a table. Membership composes the canonical organisation, capability and attestation records, and approved affiliations through existing organisation interfaces. The declarative values add the eligibility rules per role and claim type, and the resolver returns eligible versus ineligible-with-reasons with zero writes and the live gate unmet. Four roles exist: broker for intake with recognised intake and distribution capabilities, adjuster for assessment with adjustment and loss-assessment capabilities, garage for repair with motor and body repair capabilities, reinsurer for evidence with reinsurance capability. All roles require an approved affiliation and an active status and require attestation. Lease times are one or eight hours by role. Motor uses all four roles, property uses three, medical uses two, each with the insurer as panel organisation role. Fail-closed: missing values refuse with a service error; unknown type or role refuses with a validation error; a candidate missing affiliation, capability, or attestation is reported ineligible with the explicit reason.

Meter clock (read-only arithmetic, timeout through the outbox). Windows are values per type and severity. The default window is wide for acceptance and two days-plus for quotation and pre-authorisation, escalating to the adjuster role. Urgent motor and property windows are short; litigation windows are longest, escalating to the reinsurer. Medical windows are medium. Every entry binds to the same workflow flow and namespace. Recording writes one breach row plus one action row and always reports the live gate unmet. Missing values refuse with a service error; unknown type or severity refuses with a validation error; a live timeout with no sink refuses rather than inventing.

Quorum bands (amount by risk selects the named quorum). Ordered bands per type map amount range and risk band to a named quorum plus approver roles. High-risk motor claims need three approvals; large amounts need two; mid standard amounts need two; mid low amounts and small amounts need one. Named quorums: one-person standard, two-person, three-person, cross-agency, resolver, and assembly. Resolution performs zero writes and reports the live gate unmet. Missing values refuse; unknown risk, missing or negative amounts, no match, or unresolved quorum reference refuses. Opening refuses when caller signers are below the minimum and never invents signers.

Add-ons and intake. Add-ons map claim type plus cover to entitled services with ceilings and evidence needs; the plane answers eligibility only and never creates subscriptions or billing — the monetisation ceremony is separate. Intake maps target claim creation or provider upsert only; any other target refuses; preview validates against the target contract read-only.

6. Event spine end to end

The live proof runs the consumer end to end: the consumer subscribes on the core bus to the lifecycle subject family in its queue group, validates the subject against the value-group allowlist, resolves the pack by claim type, runs enabled advisory hooks, and publishes a consumed receipt. The platform outbox relay publishes on a short cadence, so receipts may take longer than a single transition; per-claim timeouts are generous. The proof creates two claims — one motor, one ticket — transitions each to submitted, and awaits the per-claim consumed receipts asserting the expected receipt shape. It then runs a negative case: publishing an allowlist-external subject for a ghost identity and waiting, asserting no receipt is produced, proving the allowlist drop. Fixtures remain as real rows marked as fixtures.

Producer honesty: transition and finalise only enqueue outbox rows; they never publish directly — the relay sweep performs the publish and marks the row.

Open items / gaps

• No live billing or live settlement is claimed from this plane; eligibility answers only.
• Government and community lines have no panel mesh in the seeded values; panel roles cover insurance lines only.
• Procurement threshold bands sit alongside the claims threshold values; the seam reads the claims keys explicitly.