Claims Processing — Gap Analysis

Audience: Product, engineering, implementation leadership. Status: As of 2026-11-09 — identifies gaps between current implementation and target claims processing capability. Method: Audit of existing SurrealDB strata, BFF routes, Kestra components, Camel routes, seeds, and tests against the target claims processing design described in this document set.

1. What Exists (Current State)

1.1 Strata Deployed

1.2 API Routes (agent-bff)

23 paths / 24 operations across claims-lifecycle, claims-governance, and claims-compose tags. All routes fail closed, validate inputs, return honest errors. Tests exist in apps/agent-bff/__tests__/processing-claim-routes.test.js.

1.3 Kestra Components

claim-create, claim-search, claim-resolve-pointer, claim-update, claim-aggregate, claims-sla-timeout workflows.

1.4 Seeds

• Kenya & Tanzania claim routing seed (construction, agriculture, health, land sectors)
• Materra claims seeds (policy claims)
• CNS claim builder templates
• Various claim type seeds across strata

1.5 Documentation

• Claims Plane — Processing Claims, Guarded Transitions, and Declarative Packs — Claims plane documentation
• D-05 — Playbook Registry (Sellable Repeatable Business Processes) — P-04 Claims Engine, P-05 Claims Packs
• Generic Processing Claims API (cross-vertical) — OpenAPI 1.2.0 — OpenAPI 1.2.0 reference
• claims-processing-system.md — Project plan (references docs/claims-platform/ which does not exist)

2. Significant Gaps

2.1 Industry-Specific Claim Type CNS Registrations (HIGH)

Gap: While the Kenya/Tanzania claim routing seed registers claim types for construction, agriculture, health, and land sectors, there is no comprehensive CNS type hierarchy for the industries described in this document set (real estate, healthcare, government, commerce, construction, insurance).

Impact: New industries cannot deploy claims without manually creating CNS types and lookup values. No declarative registration path exists for industry-specific claim types beyond what is seeded.

Required: Create database/seeds/cns/cns_type_catalog_claims_<industry>.surql files for each industry, and register them via scripts/seed-nats-kv-declarative.mjs.

2.2 Industry-Specific Lookup Values (HIGH)

Gap: Guard policies, quorum bands, SLA windows, panel roles, and intake maps exist conceptually in the API documentation but are not seeded as declarative NATS KV values for industry-specific claim types.

Impact: When a new industry deploys claims, the guard engine fails closed (missing values refuse with service error) — no claims can be processed until lookups are manually configured.

Required: Create NATS KV lookup seed files for each industry vertical and claim type.

2.3 Multi-Party Settlement Integration (HIGH)

Gap: Escrow hold/disburse/rollback functions exist (s206_claim_dependency_cascade) but there is no integration with payment rails for actual settlement. No Stripe, M-Pesa, bank transfer, or ERPNext payment integration exists.

Impact: Claims can reach "settled" state in the FSM but no actual money moves. Settlement is a data state, not a financial event.

Required: Implement payment adapter classes (opaque references per D-07 mandate) and integrate with existing ERPNext/Camel egress gateway.

2.4 Fraud Detection Layer (MEDIUM)

Gap: The claims-processing-system.md plan mentions Dify.ai for fraud audits, but no Dify hook bindings exist for claims fraud detection. No fraud scoring, anomaly detection, or duplicate claim detection is implemented.

Impact: Claims can be processed without fraud screening. Duplicate claims, inflated estimates, and organized fraud rings are not detected.

Required: Implement Dify.ai workflow bindings for fraud audit hooks, duplicate claim detection, and anomaly scoring.

2.5 ACORD Standards Mapping (MEDIUM)

Gap: The claims-processing-system.md plan references ACORD standards, but no ACORD mapping exists in the codebase. No ACORD XML/JSON schemas, no EDI 837/835 templates beyond Camel route placeholders.

Impact: Insurance claims cannot exchange data with ACORD-compliant systems (clearinghouses, TPAs, carriers) without custom integration work.

Required: Create ACORD-compliant Camel YAML routes with Smooks EDI templates for 837 (claims) and 835 (remittance).

2.6 Claims Builder / No-Code Configuration (MEDIUM)

Gap: The claims-processing-system.md plan mentions "zero-code FSM loading" and claims-planner tooling, but no claims builder UI or no-code configuration tool exists. All configuration must be done via NATS KV seed scripts or SurrealQL functions.

Impact: Non-technical users cannot configure claim types, guard policies, or panel roles without engineering support.

Required: Build a claims builder tool that reads/writes NATS KV values declaratively.

2.7 Test Coverage Gaps (MEDIUM)

Gap: Tests exist for claim creation, validation registry, token and claim result, registry operations, truth graph lifecycle, and routing use cases. However:

• No end-to-end test for a full claim lifecycle (create → transition → settle → finalize)
• No test for PoCE receipt verification
• No test for escrow hold/disburse/rollback
• No test for cross-industry claim type deployment
• No test for fail-closed behavior when solver-gateway is down

Required: Add E2E tests for full claim lifecycle, PoCE verification, escrow, and fail-closed scenarios.

2.8 Multi-Party Arbitration (LOW)

Gap: Arbitration override functions exist (s214_claim_arbitration) but are not integrated into the claims API routes. No route exists to create an arbitration override or cast a vote.

Impact: Blocked FSM nodes cannot be resolved through the API — arbitration must be done via direct SurrealQL function calls.

Required: Add API routes for arbitration override creation and voting.

2.9 Cascade Invalidation API (LOW)

Gap: Cascade invalidation functions exist (s206_claim_dependency_cascade) but are not integrated into the claims API routes. No route exists to trigger cascade invalidation or view cascade audit.

Impact: When a claim is revoked, dependent claims are not automatically invalidated through the API.

Required: Add API routes for cascade invalidation and audit viewing.

2.10 Documentation Integration (LOW)

Gap: The docs.jijibora.online documentation site does not include claims processing documentation. Claims docs exist in docs/platform-map/system/ but are not part of the curated documentation set rendered by the site builder.

Impact: Users of the documentation site cannot discover claims processing capabilities.

Required: Add claims processing documents to the curated set (already done via this document set — ensure they are included in docs/platform-map/ so the build system discovers them).

3. Gap Priority Matrix

Priority: HIGH = blocks LIVE deployment for new industries; MEDIUM = important but not blocking; LOW = nice to have.

Effort: S = small (days), M = medium (weeks), L = large (months).

4. Recommendations

Immediate (Next 30 Days)

1. Create industry CNS registration seeds for real estate, healthcare, government, commerce, construction, and insurance.
2. Create industry lookup seed files (guard policies, quorum bands, SLA windows, panel roles, intake maps) for each vertical.
3. Add E2E tests for full claim lifecycle (create → transition → settle → finalize) with PoCE verification.
4. Add claims processing docs to the documentation site (this document set — verify they are discovered by the build system).

Short-Term (Next 90 Days)

5. Implement payment adapter classes for escrow integration (Stripe, M-Pesa, bank transfer).
6. Create ACORD Camel routes with Smooks EDI templates for insurance interoperability.
7. Add fraud detection Dify hooks for duplicate claims and anomaly scoring.
8. Add arbitration and cascade API routes to the claims BFF.

Medium-Term (Next 6 Months)

9. Build claims builder UI for no-code configuration of claim types and guard policies.
10. Implement catastrophe modeling integration for insurance vertical.
11. Add cross-industry claim type deployment validation tests.

5. How to Use This Gap Analysis

• Product: Use the priority matrix to sequence backlog items.
• Engineering: Use the gap descriptions to scope implementation work.
• QA: Use the test coverage gaps to plan test automation.
• Implementation: Use the deployment order in each industry document to plan rollouts.