Skip to main content

ADR-0183: Navin Enterprise Claims Management Agent, insurance product layer on top of the Control Plane

  • Status: proposed on 2026-11-04, awaiting user validation (see "Points to validate")
  • Date: 2026-11-04
  • Scope: new project navin-enterprise-assurance-sinistres/ (FastAPI backend navin_sinistres, workers, Navin integration, no frontend of its own: the shared frontend shell of ADR-0180 carries the interface), additive OpenFGA types (deploy/policies/openfga/model.fga, type claims_instance and objects claim, settlement_version, payment_request, expert_mission, claim_closure, claim_document), OPA package eai.assurance_sinistres (deploy/policies/opa/assurance_sinistres.rego, key eai.config.assurance_sinistres of data.json), contracts contracts/v1/assurance-sinistres-action-request.schema.json and contracts/v1/assurance-sinistres-copilot-event.schema.json, Navin Manager agent template prepared but not published (navin-assurance-sinistres-agent)
  • Related documents: ADR-0101, ADR-0103, ADR-0108, ADR-0166, ADR-0173, ADR-0174, ADR-0175, ADR-0176 (Banking Back-Office, reference implementation whose generic modules are copied), ADR-0180, decision of 2026-11-04 (.navin/continuity/DECISIONS.md, one frontend, backend derived by copy), brief agent_uses_cases/01_Assurance_Gestion_des_Sinistres.md

Context​

The client asks for an end-to-end claims agent: declaration and file constitution, triage, coverage verification at the event date against the policy administration system, expertise and evidence, fraud signals, reserves and settlement proposals, payment orders, recoveries and closure, communications, an AI copilot for the handler. The brief requires that the AI never settles, pays, denies, accepts or closes a claim: every effect goes through the Action Gateway with a human in the loop and the confirmation of the source system.

The platform already provides identity and tenant context, the tool gateway with OPA decisions, approvals with separation of duties and idempotency, dated and revocable delegations, mandatory file scanning (quarantine, ClamAV, YARA-X), Mem0 and Cognee memory, knowledge bases and the chained audit. UC-00 (ADR-0176) showed how a product layer sits on these bricks: generic modules copied unchanged, business modules written for the domain.

Decision​

  1. Backend derived by copy: package navin_sinistres takes the generic modules of navin_backoffice unchanged (package name apart); only the business modules and their state machine are written for this product. No frontend: product.manifest.json describes menus, entities, columns, write actions and copilot prompts to the shared shell of ADR-0180.
  2. Fixed identity: product_id assurance-sinistres, prefix /api/v1/assurance-sinistres, development ports web 3473, API 8472, Redis 6393, PostgreSQL schema sinistres, roles navin_sinistres_app and navin_sinistres_worker without BYPASSRLS.
  3. Projection, never system of record: sinistres.policy_versions is a dated projection of the policy administration system (COMMENT ON TABLE); the coverage engine only cites a clause present in the imported version and concludes undetermined when the version at the event date is missing.
  4. Money: numeric(20, 6) and decimal strings everywhere, a float is refused at bind time; one currency per row; never a sum across currencies; the contractual order of operations (retained damage, deductible, ceiling, confirmed advances, already paid) is recorded in every settlement version with a calculation_ref.
  5. Payments: payment_requests becomes confirmed or partially_confirmed only on a re-read of the payment system (external_payment_ref, confirmed_at, confirmed_amount required by constraint); a missing answer gives unknown_pending_confirmation, never a local failure or success; advances are deducted only when confirmed (payment_allocations).
  6. Maker-checker as data: OPA eai.assurance_sinistres reads the delegation matrix of section 15 from data.json (operations, preparing and approving roles, tiers per currency, quorum, urgency); OpenFGA carries can_approve ... but not maker and can_review ... but not uploader; the approver_not_maker constraints of the tables double the rule. The package exposes decision.applies, true for its own actions only.
  7. Fraud signals: timestamped indicators that open a human review, never a decision; never shown to the declarant or the expert.
  8. Documents: same pipeline as UC-00 (quarantine, mandatory ClamAV and YARA-X, Docling, manual review when the extraction is ambiguous); a visual estimate is never retained as an indemnifiable amount (constraint visual_estimate_never_retained).
  9. Copilot: copied runtime (SSE, Last-Event-ID, injection, DLP, budget and figures governance); read tools under RLS, prepare tools through the gateway, side-effect tools after approval by a human other than the run owner; event contract derived from banking-copilot-event with the same envelope.
  10. Connectors: declared capability contracts, deterministic navin-sandbox refused in production mode, never a simulated confirmation presented as the source's.

Consequences​

  • Positive: full reuse of the governed bricks, tenant isolation by RLS on every table, delegation matrix editable without redeployment, complete traceability of calculations and decisions.
  • Negative: the copy of the generic modules creates a synchronisation debt with UC-00 (recorded in KNOWN_LIMITATIONS.md); real connectors (policy administration, payment, expert network) remain to be configured by the client; the template stays unpublished until the artifact pipeline has run.

Points to validate​

  • Amount tiers and quorums per currency of eai.config.assurance_sinistres (starting values, to be adjusted).
  • Branches enabled per instance and per-branch rules.
  • Reconciliation delay of unknown_pending_confirmation payments before an alert.

Alternatives rejected​

  • One frontend per product: refused by the decision of 2026-11-04.
  • A local paid status set at submission: refused, only the source confirms.
  • An LLM-based coverage engine: refused, the engine is deterministic and versioned, the LLM explains.

Delivery plan​

Sub-plan of task t-806252bc (S1 audit and ADR, S2 contracts and policies, S3 foundation, S4 and S5 business modules, S6 state machine, S7 documents, S8 copilot, S9 security, S10 acceptance, S11 manifest and template, S12 docs).