Generic Processing Claims API (cross-vertical) — OpenAPI 1.2.0

<!-- GENERATED by scripts/render-platform-map-api-docs.mjs — do not hand-edit; edit apps/agent-bff/openapi/<spec>.json and re-run. --> Scope: The published reference for Generic Processing Claims API (cross-vertical). 23 paths — the measured spec-vs-implementation coverage lives in the complete API inventory. Status: rendered 2026-11-09 from the OpenAPI source for Generic Processing Claims API (cross-vertical) — regenerate with node scripts/render-platform-map-api-docs.mjs. See also: the OpenAPI spec index.

Servers

Tags

Paths — 23 paths / 24 operations

Operations

POST /v1/claims/processing

Summary: Create a processing claim Description: Creates a governed processing claim for any claim_type. claim_id, claim_type and subject_id are required. Optionally starts a PoCE session (start_poc_session + poc_path_spec_id) and binds a scope.

Tags: claims-lifecycle Operation ID: createProcessingClaim Request body:

Content type: application/json

Responses:

GET /v1/claims/processing

Summary: List processing claims Description: Lists claims with optional filters. All filters are optional; unknown filter combinations return an empty list, never an error.

Tags: claims-lifecycle Operation ID: listProcessingClaims

Parameters:

Responses:

GET /v1/claims/processing/stats

Summary: Aggregate claim statistics

Tags: claims-lifecycle Operation ID: getProcessingClaimStats

Parameters:

Responses:

POST /v1/claims/processing/poc/require

Summary: Declare PoCE gating for a scope + claim_type Description: Marks a (scope_id, claim_type) pair as PoCE-gated so governed transitions demand a proof receipt. Declaration only — execution happens on the governance engine.

Tags: claims-governance Operation ID: requirePocForScope Request body:

Content type: application/json

Responses:

POST /v1/claims/processing/guard-check

Summary: Dry-run a guarded transition (no state change) Description: Evaluates the declarative guard bundle for a transition request without applying it. Missing policy fails closed unless the pack declares governance.none.

Tags: claims-governance Operation ID: guardCheckProcessingClaim Responses:

POST /v1/claims/processing/scenario-packs/{scenarioId}/soft-apply

Summary: Soft apply a claims scenario pack (validate + plan, zero writes) Description: Resolves a scenario pack from the declarative scenario store and validates every referenced lookup, rule name, intake map and CNS type. Plan only: no writes, and live_gate_met is never reported.

Tags: claims-governance Operation ID: softApplyClaimsScenarioPack

Parameters:

Responses:

GET /v1/claims/processing/{claimId}

Summary: Read a claim with its timeline

Tags: claims-lifecycle Operation ID: getProcessingClaim

Parameters:

Responses:

POST /v1/claims/processing/{claimId}/transition

Summary: Guarded transition to a new lifecycle state Description: Requests a state transition. The transition is guarded by declarative governance policy (gate / quorum / separation-of-duties / evidence / external verdicts) loaded from lookups — never by hardcoded per-type stage lists. Illegal transitions and failed guards are refused (4xx), never Soft-advanced.

Tags: claims-governance Operation ID: transitionProcessingClaim

Parameters:

Request body:

Content type: application/json

Responses:

POST /v1/claims/processing/{claimId}/finalize

Summary: Finalize a claim with its proof receipt Description: Finalizes a claim against a PoCE receipt (result claim + result hash). Finalization is refused when the proof receipt does not verify.

Tags: claims-governance Operation ID: finalizeProcessingClaim

Parameters:

Request body:

Content type: application/json

Responses:

GET /v1/claims/processing/readiness

Summary: LIVE-readiness probe from real network checks Description: Probes every required dependency for real on this request — typed read of the claim store, message-fabric round-trip, protocol-gateway health, workflow-engine reachability, external-solver health. infra_ready (formerly live_gate_met, still present as a deprecated alias for older readers) is earned only when every required probe genuinely passes; any failure yields blocking[] with the failing keys. rollout_enabled records whether the claims pilot is rolled out live (operator-set env; default off) — infra-ready is not product live. Solver is informational unless require_solver=1.

Tags: claims-governance Operation ID: getClaimsReadiness

Parameters:

Responses:

GET /v1/claims/processing/metrics

Summary: Brief metrics computed from real claim events Description: Every number is computed on this request from actual claim rows, step rows, quorum rows, and outbox events. Metrics with zero real samples are null with a reason — never invented. Read-only; never claims a live gate.

Tags: claims-lifecycle Operation ID: getBriefMetrics

Parameters:

Responses:

GET /v1/claims/processing/voyage/{voyageId}

Summary: Voyage projection by correlation id Description: Projects the claim, its steps, PoCE session, sourcing bind, and gate receipts onto one correlation (voyage) id. Empty-ok for unknown ids; timeless records never get a fake timeline.

Tags: claims-lifecycle Operation ID: getClaimVoyage

Parameters:

Responses:

GET /v1/claims/processing/panel/roles

Summary: List provider panel roles for a claim type Description: Reads the declarative panel eligibility values (affiliation status, provider status, customer-signed capability attestation, bounded lease TTLs, role list per claim type). Read-only; grants nothing.

Tags: claims-lifecycle Operation ID: listPanelRoles

Parameters:

Responses:

POST /v1/claims/processing/panel/eligibility

Summary: Resolve panel eligibility for one candidate Description: Reports eligible or ineligible-with-reasons for a provider candidate in a panel role. Capability attestations must be customer-signed; unattested candidates are ineligible. Zero writes.

Tags: claims-lifecycle Operation ID: resolvePanelEligibility Request body:

Content type: application/json

Responses:

GET /v1/claims/processing/sla/policy

Summary: Get the SLA window for a claim type + severity Description: Returns the accept/quote/preauth windows, timeout action (re-dispatch or escalate), escalate target role, and the workflow flow that enforces the timer. Windows are declarative values, never invented.

Tags: claims-lifecycle Operation ID: getSlaPolicy

Parameters:

Responses:

POST /v1/claims/processing/sla/evaluate

Summary: Evaluate an SLA window against a start time Description: Read-only clock arithmetic against the declared window for the claim type and severity. Never sets live_gate_met.

Tags: claims-lifecycle Operation ID: evaluateSla Request body:

Content type: application/json

Responses:

POST /v1/claims/processing/sla/timeout

Summary: Record an SLA timeout with its action Description: Writes the breach plus the declared action (re-dispatch or escalate) as outbox events on the allowlisted lifecycle subjects. Soft-only: this desk never claims live execution.

Tags: claims-lifecycle Operation ID: recordSlaTimeout Request body:

Content type: application/json

Responses:

GET /v1/claims/processing/vas/eligibility

Summary: List value-added service eligibility for a cover Description: Maps a cover to the services it entitles (cover-to-services values with caps and evidence hints). Read-only; the plan grants nothing.

Tags: claims-lifecycle Operation ID: listVasEligibility

Parameters:

Responses:

POST /v1/claims/processing/vas/check

Summary: Check a specific value-added service against a claim Description: Answers whether a value-added service is entitled under the claim's cover. A third-party cover never widens to comprehensive. Returns an entitlement plan; grants nothing by itself.

Tags: claims-lifecycle Operation ID: checkVasEligibility Request body:

Content type: application/json

Responses:

GET /v1/claims/processing/intake/maps

Summary: List field maps for intake and provider upserts Description: Lists the declarative intake field maps (first-notice-of-loss plus per-panel-role provider maps) with their targets. Read-only.

Tags: claims-lifecycle Operation ID: listIntakeMaps

Parameters:

Responses:

POST /v1/claims/processing/intake/maps/{mapId}/preview

Summary: Preview a field map against a payload Description: Soft desk: validates the payload against the map's required fields and claim-type rules. Always zero writes — preview only.

Tags: claims-lifecycle Operation ID: previewIntakeMap

Parameters:

Request body:

Content type: application/json

Responses:

GET /v1/claims/processing/quorum/bands

Summary: List quorum bands for a claim type Description: Returns the ordered amount-range by risk-band quorum templates (named quorum plus approver roles plus minimum approvals). Read-only; bands are declarative values.

Tags: claims-lifecycle Operation ID: listQuorumBands

Parameters:

Responses:

POST /v1/claims/processing/quorum/resolve

Summary: Resolve the quorum template for an amount and risk Description: Resolves (amount, risk) to a named quorum with its minimum approvals. No matching band is a 422 — never an invented default. Read-only.

Tags: claims-lifecycle Operation ID: resolveQuorumTemplate Request body:

Content type: application/json

Responses:

POST /v1/claims/processing/quorum/open

Summary: Open a quorum from a resolved band template Description: Opens a quorum scoped to the resolved band threshold. Refuses when fewer signers than the band minimum are supplied. Advancing stays on the quorum sign route plus the guarded transition.

Tags: claims-governance Operation ID: openQuorumForClaim Request body:

Content type: application/json

Responses:

Compose recipes (x-compose-recipes)

• Adjudicate with sourced providers (any vertical) — Claim needs a provider: publish capability claims, match on the sourcing plane, bind the winner into the governed transition.
• PoCE-gated claims (any vertical) — Declare gating, run governed execution, finalize against the receipt.
• Quorum-gated claims (any vertical) — Multi-party assessment where no single actor may advance the claim.
• Organization-bound claims (any vertical) — Claims owned by organizations, affiliations, and teams.

Full specification — verbatim source of truth

{
  "openapi": "3.1.0",
  "info": {
    "title": "Generic Processing Claims API (cross-vertical)",
    "version": "1.2.0",
    "description": "Lifecycle API for governed processing claims of ANY claim_type — insurance claim, community request, commerce adjudication, government application, internal approval. There is no vertical-specific lifecycle state in this API: the set of states, transition guards, and evidence requirements are driven by declarative governance policy (lookups + path specs), never by branch code per claim type. Compose with organizations, sourcing, PoCE and quorum surfaces per the compose appendix. Soft≠LIVE: these routes read/write the SoR store; LIVE governed execution requires the governance engine and is never invented by this desk."
  },
  "servers": [
    {
      "url": "https://dev.agent.jijibora.online",
      "description": "Dokku DEV Agent BFF"
    },
    {
      "url": "https://uat.agent.jijibora.online",
      "description": "Dokku UAT Agent BFF"
    },
    {
      "url": "http://127.0.0.1:3030",
      "description": "Local laptop only — not for public codegen"
    }
  ],
  "tags": [
    {
      "name": "claims-lifecycle",
      "description": "Create, list, read, transition, finalize processing claims"
    },
    {
      "name": "claims-governance",
      "description": "PoCE gating declaration + guarded transition/finalize"
    },
    {
      "name": "claims-compose",
      "description": "Compose recipes with orgs, sourcing, PoCE, quorum"
    }
  ],
  "paths": {
    "/v1/claims/processing": {
      "post": {
        "tags": [
          "claims-lifecycle"
        ],
        "summary": "Create a processing claim",
        "description": "Creates a governed processing claim for any claim_type. claim_id, claim_type and subject_id are required. Optionally starts a PoCE session (start_poc_session + poc_path_spec_id) and binds a scope.",
        "operationId": "createProcessingClaim",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "claim_id",
                  "claim_type",
                  "subject_id"
                ],
                "properties": {
                  "claim_id": {
                    "type": "string",
                    "example": "clm:2026:01101"
                  },
                  "claim_type": {
                    "type": "string",
                    "example": "cns://claim/type/community/request",
                    "description": "Any cross-vertical claim type, e.g. cns://claim/type/insurance/motor_claim, cns://claim/type/commerce/adjudication, cns://claim/type/government/application"
                  },
                  "subject_id": {
                    "type": "string",
                    "example": "person:citizen_4812"
                  },
                  "amount": {
                    "type": "number",
                    "example": 12500
                  },
                  "currency": {
                    "type": "string",
                    "example": "KES"
                  },
                  "metadata": {
                    "type": "object",
                    "description": "Pack-declared metadata only; never sealed payloads"
                  },
                  "created_by": {
                    "type": "string",
                    "example": "user:operator-7"
                  },
                  "start_poc_session": {
                    "type": "boolean",
                    "example": true
                  },
                  "poc_path_spec_id": {
                    "type": "string",
                    "example": "path:dde:default_v1"
                  },
                  "scope_id": {
                    "type": "string",
                    "example": "scope:community:nairobi"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Claim created; returns the claim record with lifecycle state and optional PoCE session reference"
          },
          "400": {
            "description": "claim_id, claim_type or subject_id missing"
          },
          "409": {
            "description": "Claim creation failed (e.g. duplicate claim_id)"
          }
        }
      },
      "get": {
        "tags": [
          "claims-lifecycle"
        ],
        "summary": "List processing claims",
        "description": "Lists claims with optional filters. All filters are optional; unknown filter combinations return an empty list, never an error.",
        "operationId": "listProcessingClaims",
        "parameters": [
          {
            "name": "subject_id",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "claim_type",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of claim records (possibly empty)"
          }
        }
      }
    },
    "/v1/claims/processing/stats": {
      "get": {
        "tags": [
          "claims-lifecycle"
        ],
        "summary": "Aggregate claim statistics",
        "operationId": "getProcessingClaimStats",
        "parameters": [
          {
            "name": "subject_id",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "claim_type",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Aggregate counts; empty object when nothing matches"
          }
        }
      }
    },
    "/v1/claims/processing/poc/require": {
      "post": {
        "tags": [
          "claims-governance"
        ],
        "summary": "Declare PoCE gating for a scope + claim_type",
        "description": "Marks a (scope_id, claim_type) pair as PoCE-gated so governed transitions demand a proof receipt. Declaration only — execution happens on the governance engine.",
        "operationId": "requirePocForScope",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "scope_id",
                  "claim_type"
                ],
                "properties": {
                  "scope_id": {
                    "type": "string",
                    "example": "scope:community:nairobi"
                  },
                  "claim_type": {
                    "type": "string",
                    "example": "cns://claim/type/community/request"
                  },
                  "path_spec_id": {
                    "type": "string",
                    "example": "path:dde:default_v1"
                  },
                  "path_spec_version": {
                    "type": "integer",
                    "example": 1
                  },
                  "min_steps": {
                    "type": "integer",
                    "example": 3
                  },
                  "description": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "PoCE gating declaration recorded"
          },
          "400": {
            "description": "scope_id or claim_type missing"
          }
        }
      }
    },
    "/v1/claims/processing/guard-check": {
      "post": {
        "tags": [
          "claims-governance"
        ],
        "summary": "Dry-run a guarded transition (no state change)",
        "description": "Evaluates the declarative guard bundle for a transition request without applying it. Missing policy fails closed unless the pack declares governance.none.",
        "operationId": "guardCheckProcessingClaim",
        "responses": {
          "200": {
            "description": "Guard evaluation result"
          },
          "422": {
            "description": "Guard refused / policy missing"
          }
        }
      }
    },
    "/v1/claims/processing/scenario-packs/{scenarioId}/soft-apply": {
      "post": {
        "tags": [
          "claims-governance"
        ],
        "summary": "Soft apply a claims scenario pack (validate + plan, zero writes)",
        "description": "Resolves a scenario pack from the declarative scenario store and validates every referenced lookup, rule name, intake map and CNS type. Plan only: no writes, and `live_gate_met` is never reported.",
        "operationId": "softApplyClaimsScenarioPack",
        "parameters": [
          {
            "name": "scenarioId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "scenario.claims.motor_ke.v1"
          }
        ],
        "responses": {
          "200": {
            "description": "Validation green with a zero-write plan"
          },
          "404": {
            "description": "scenario_pack_not_found"
          },
          "422": {
            "description": "Broken reference (rule / map / CNS type)"
          },
          "503": {
            "description": "Declarative store or CNS catalog unavailable (fail closed)"
          }
        }
      }
    },
    "/v1/claims/processing/{claimId}": {
      "get": {
        "tags": [
          "claims-lifecycle"
        ],
        "summary": "Read a claim with its timeline",
        "operationId": "getProcessingClaim",
        "parameters": [
          {
            "name": "claimId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Claim record with lifecycle timeline"
          },
          "404": {
            "description": "claim_not_found"
          }
        }
      }
    },
    "/v1/claims/processing/{claimId}/transition": {
      "post": {
        "tags": [
          "claims-governance"
        ],
        "summary": "Guarded transition to a new lifecycle state",
        "description": "Requests a state transition. The transition is guarded by declarative governance policy (gate / quorum / separation-of-duties / evidence / external verdicts) loaded from lookups — never by hardcoded per-type stage lists. Illegal transitions and failed guards are refused (4xx), never Soft-advanced.",
        "operationId": "transitionProcessingClaim",
        "parameters": [
          {
            "name": "claimId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "status"
                ],
                "properties": {
                  "status": {
                    "type": "string",
                    "example": "adjudicating",
                    "description": "Target state per the claim_type's declared lifecycle"
                  },
                  "actor_id": {
                    "type": "string",
                    "example": "user:adjuster-3"
                  },
                  "transition_type": {
                    "type": "string",
                    "example": "assessment"
                  },
                  "notes": {
                    "type": "string"
                  },
                  "input_hash": {
                    "type": "string",
                    "description": "Content hash of transition inputs"
                  },
                  "output_hash": {
                    "type": "string",
                    "description": "Content hash of transition outputs"
                  },
                  "metadata": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Transition applied"
          },
          "400": {
            "description": "Invalid or refused transition (policy guard failed)"
          },
          "404": {
            "description": "E_CLAIM_NOT_FOUND"
          }
        }
      }
    },
    "/v1/claims/processing/{claimId}/finalize": {
      "post": {
        "tags": [
          "claims-governance"
        ],
        "summary": "Finalize a claim with its proof receipt",
        "description": "Finalizes a claim against a PoCE receipt (result claim + result hash). Finalization is refused when the proof receipt does not verify.",
        "operationId": "finalizeProcessingClaim",
        "parameters": [
          {
            "name": "claimId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "result_claim_id": {
                    "type": "string"
                  },
                  "result_hash": {
                    "type": "string"
                  },
                  "issuer_id": {
                    "type": "string",
                    "example": "user:operator-7"
                  },
                  "subject_id": {
                    "type": "string",
                    "example": "person:citizen_4812"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Claim finalized with proof receipt"
          },
          "400": {
            "description": "Proof receipt invalid (E_* error)"
          }
        }
      }
    },
    "/v1/claims/processing/readiness": {
      "get": {
        "tags": [
          "claims-governance"
        ],
        "summary": "LIVE-readiness probe from real network checks",
        "description": "Probes every required dependency for real on this request — typed read of the claim store, message-fabric round-trip, protocol-gateway health, workflow-engine reachability, external-solver health. infra_ready (formerly live_gate_met, still present as a deprecated alias for older readers) is earned only when every required probe genuinely passes; any failure yields blocking[] with the failing keys. rollout_enabled records whether the claims pilot is rolled out live (operator-set env; default off) — infra-ready is not product live. Solver is informational unless require_solver=1.",
        "operationId": "getClaimsReadiness",
        "parameters": [
          {
            "name": "require_solver",
            "in": "query",
            "required": false,
            "description": "Gate on the external solver too ('1' or 'true').",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Readiness verdict with per-service evidence"
          }
        }
      }
    },
    "/v1/claims/processing/metrics": {
      "get": {
        "tags": [
          "claims-lifecycle"
        ],
        "summary": "Brief metrics computed from real claim events",
        "description": "Every number is computed on this request from actual claim rows, step rows, quorum rows, and outbox events. Metrics with zero real samples are null with a reason — never invented. Read-only; never claims a live gate.",
        "operationId": "getBriefMetrics",
        "parameters": [
          {
            "name": "claim_type",
            "in": "query",
            "required": false,
            "description": "Restrict the sample to one claim type.",
            "schema": {
              "type": "string",
              "example": "cns://claim/type/insurance/motor_claim"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Metric bundle (real values or honest nulls)"
          },
          "503": {
            "description": "Store unavailable — fail closed"
          }
        }
      }
    },
    "/v1/claims/processing/voyage/{voyageId}": {
      "get": {
        "tags": [
          "claims-lifecycle"
        ],
        "summary": "Voyage projection by correlation id",
        "description": "Projects the claim, its steps, PoCE session, sourcing bind, and gate receipts onto one correlation (voyage) id. Empty-ok for unknown ids; timeless records never get a fake timeline.",
        "operationId": "getClaimVoyage",
        "parameters": [
          {
            "name": "voyageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Voyage projection (possibly empty)"
          }
        }
      }
    },
    "/v1/claims/processing/panel/roles": {
      "get": {
        "tags": [
          "claims-lifecycle"
        ],
        "summary": "List provider panel roles for a claim type",
        "description": "Reads the declarative panel eligibility values (affiliation status, provider status, customer-signed capability attestation, bounded lease TTLs, role list per claim type). Read-only; grants nothing.",
        "operationId": "listPanelRoles",
        "parameters": [
          {
            "name": "claim_type",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "cns://claim/type/insurance/motor_claim"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Panel roles for the claim type"
          },
          "422": {
            "description": "claim_type required"
          },
          "503": {
            "description": "Panel lookup unavailable"
          }
        }
      }
    },
    "/v1/claims/processing/panel/eligibility": {
      "post": {
        "tags": [
          "claims-lifecycle"
        ],
        "summary": "Resolve panel eligibility for one candidate",
        "description": "Reports eligible or ineligible-with-reasons for a provider candidate in a panel role. Capability attestations must be customer-signed; unattested candidates are ineligible. Zero writes.",
        "operationId": "resolvePanelEligibility",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "claim_type",
                  "role"
                ],
                "properties": {
                  "claim_type": {
                    "type": "string",
                    "example": "cns://claim/type/insurance/motor_claim"
                  },
                  "role": {
                    "type": "string",
                    "example": "garage"
                  },
                  "candidate": {
                    "type": "object",
                    "description": "Provider candidate with affiliation + attestation references"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Eligibility verdict with reasons"
          },
          "422": {
            "description": "Unknown role or candidate ineligible"
          },
          "503": {
            "description": "Panel lookup unavailable"
          }
        }
      }
    },
    "/v1/claims/processing/sla/policy": {
      "get": {
        "tags": [
          "claims-lifecycle"
        ],
        "summary": "Get the SLA window for a claim type + severity",
        "description": "Returns the accept/quote/preauth windows, timeout action (re-dispatch or escalate), escalate target role, and the workflow flow that enforces the timer. Windows are declarative values, never invented.",
        "operationId": "getSlaPolicy",
        "parameters": [
          {
            "name": "claim_type",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "severity",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "SLA window definition"
          },
          "422": {
            "description": "No window for this claim type/severity"
          },
          "503": {
            "description": "SLA lookup unavailable"
          }
        }
      }
    },
    "/v1/claims/processing/sla/evaluate": {
      "post": {
        "tags": [
          "claims-lifecycle"
        ],
        "summary": "Evaluate an SLA window against a start time",
        "description": "Read-only clock arithmetic against the declared window for the claim type and severity. Never sets live_gate_met.",
        "operationId": "evaluateSla",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "started_at",
                  "claim_type"
                ],
                "properties": {
                  "claim_type": {
                    "type": "string"
                  },
                  "severity": {
                    "type": "string"
                  },
                  "started_at": {
                    "type": "string",
                    "format": "date-time"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Window evaluation (inside/breached)"
          },
          "400": {
            "description": "started_at required and valid"
          },
          "503": {
            "description": "SLA lookup unavailable"
          }
        }
      }
    },
    "/v1/claims/processing/sla/timeout": {
      "post": {
        "tags": [
          "claims-lifecycle"
        ],
        "summary": "Record an SLA timeout with its action",
        "description": "Writes the breach plus the declared action (re-dispatch or escalate) as outbox events on the allowlisted lifecycle subjects. Soft-only: this desk never claims live execution.",
        "operationId": "recordSlaTimeout",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "claim_id",
                  "claim_type"
                ],
                "properties": {
                  "claim_id": {
                    "type": "string"
                  },
                  "claim_type": {
                    "type": "string"
                  },
                  "severity": {
                    "type": "string"
                  },
                  "started_at": {
                    "type": "string",
                    "format": "date-time"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Breach + action events recorded"
          },
          "400": {
            "description": "claim_id required"
          },
          "503": {
            "description": "SLA lookup unavailable or no live sink"
          }
        }
      }
    },
    "/v1/claims/processing/vas/eligibility": {
      "get": {
        "tags": [
          "claims-lifecycle"
        ],
        "summary": "List value-added service eligibility for a cover",
        "description": "Maps a cover to the services it entitles (cover-to-services values with caps and evidence hints). Read-only; the plan grants nothing.",
        "operationId": "listVasEligibility",
        "parameters": [
          {
            "name": "claim_type",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cover",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Eligible services for the cover"
          },
          "422": {
            "description": "Unknown claim_type or cover"
          },
          "503": {
            "description": "VAS lookup unavailable"
          }
        }
      }
    },
    "/v1/claims/processing/vas/check": {
      "post": {
        "tags": [
          "claims-lifecycle"
        ],
        "summary": "Check a specific value-added service against a claim",
        "description": "Answers whether a value-added service is entitled under the claim's cover. A third-party cover never widens to comprehensive. Returns an entitlement plan; grants nothing by itself.",
        "operationId": "checkVasEligibility",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "claim_type",
                  "vas_id"
                ],
                "properties": {
                  "claim_type": {
                    "type": "string"
                  },
                  "cover": {
                    "type": "string"
                  },
                  "vas_id": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Entitlement plan"
          },
          "422": {
            "description": "Unknown cover or service"
          },
          "503": {
            "description": "VAS lookup unavailable"
          }
        }
      }
    },
    "/v1/claims/processing/intake/maps": {
      "get": {
        "tags": [
          "claims-lifecycle"
        ],
        "summary": "List field maps for intake and provider upserts",
        "description": "Lists the declarative intake field maps (first-notice-of-loss plus per-panel-role provider maps) with their targets. Read-only.",
        "operationId": "listIntakeMaps",
        "parameters": [
          {
            "name": "target",
            "in": "query",
            "required": false,
            "description": "Filter by map target (processing_create or provider_upsert).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Field maps"
          },
          "503": {
            "description": "Maps lookup unavailable"
          }
        }
      }
    },
    "/v1/claims/processing/intake/maps/{mapId}/preview": {
      "post": {
        "tags": [
          "claims-lifecycle"
        ],
        "summary": "Preview a field map against a payload",
        "description": "Soft desk: validates the payload against the map's required fields and claim-type rules. Always zero writes — preview only.",
        "operationId": "previewIntakeMap",
        "parameters": [
          {
            "name": "mapId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "motor_claim_import/v1"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "payload"
                ],
                "properties": {
                  "payload": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Mapping preview"
          },
          "422": {
            "description": "Required field or type validation failed"
          },
          "503": {
            "description": "Maps lookup unavailable"
          }
        }
      }
    },
    "/v1/claims/processing/quorum/bands": {
      "get": {
        "tags": [
          "claims-lifecycle"
        ],
        "summary": "List quorum bands for a claim type",
        "description": "Returns the ordered amount-range by risk-band quorum templates (named quorum plus approver roles plus minimum approvals). Read-only; bands are declarative values.",
        "operationId": "listQuorumBands",
        "parameters": [
          {
            "name": "claim_type",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Quorum bands"
          },
          "422": {
            "description": "No bands for this claim type"
          },
          "503": {
            "description": "Bands lookup unavailable"
          }
        }
      }
    },
    "/v1/claims/processing/quorum/resolve": {
      "post": {
        "tags": [
          "claims-lifecycle"
        ],
        "summary": "Resolve the quorum template for an amount and risk",
        "description": "Resolves (amount, risk) to a named quorum with its minimum approvals. No matching band is a 422 — never an invented default. Read-only.",
        "operationId": "resolveQuorumTemplate",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "claim_type",
                  "amount"
                ],
                "properties": {
                  "claim_type": {
                    "type": "string"
                  },
                  "amount": {
                    "type": "number"
                  },
                  "risk": {
                    "type": "string",
                    "example": "high"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resolved quorum template"
          },
          "422": {
            "description": "No band matches (amount, risk)"
          },
          "503": {
            "description": "Bands lookup unavailable"
          }
        }
      }
    },
    "/v1/claims/processing/quorum/open": {
      "post": {
        "tags": [
          "claims-governance"
        ],
        "summary": "Open a quorum from a resolved band template",
        "description": "Opens a quorum scoped to the resolved band threshold. Refuses when fewer signers than the band minimum are supplied. Advancing stays on the quorum sign route plus the guarded transition.",
        "operationId": "openQuorumForClaim",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "claim_type",
                  "amount",
                  "name",
                  "signers"
                ],
                "properties": {
                  "claim_type": {
                    "type": "string"
                  },
                  "amount": {
                    "type": "number"
                  },
                  "risk": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "signers": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "minItems": 1
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Quorum opened"
          },
          "422": {
            "description": "Signers below the band minimum, or no band matches"
          },
          "503": {
            "description": "Quorum plane or bands lookup unavailable"
          }
        }
      }
    }
  },
  "x-compose-recipes": [
    {
      "id": "claims-with-sourcing",
      "title": "Adjudicate with sourced providers (any vertical)",
      "summary": "Claim needs a provider: publish capability claims, match on the sourcing plane, bind the winner into the governed transition.",
      "steps": [
        "POST /v1/entities/{entityId}/sourcing/publish — publish sourcable offer (scrubbed) for laborer/org/entity providers",
        "POST /v1/sourcing/tenders/{tenderId}/scatter — scatter the requirement; collect quotes",
        "POST /v1/sourcing/tenders/{tenderId}/reserve — reserve the winning capacity (fencing token)",
        "POST /v1/claims/processing/{claimId}/transition — guarded transition with the binding as evidence",
        "POST /v1/claims/processing/{claimId}/finalize — finalize with the PoCE receipt"
      ]
    },
    {
      "id": "claims-with-poc-e-check",
      "title": "PoCE-gated claims (any vertical)",
      "summary": "Declare gating, run governed execution, finalize against the receipt.",
      "steps": [
        "POST /v1/claims/processing/poc/require — declare (scope, claim_type) as PoCE-gated",
        "POST /v1/governance/path/* — start the governed path execution",
        "POST /v1/claims/processing/{claimId}/transition — guarded transitions",
        "POST /v1/claims/processing/{claimId}/finalize — finalize with proof receipt"
      ]
    },
    {
      "id": "claims-with-quorum",
      "title": "Quorum-gated claims (any vertical)",
      "summary": "Multi-party assessment where no single actor may advance the claim.",
      "steps": [
        "POST /v1/quorum/* — open a quorum assessment over the claim",
        "POST /v1/quorum/vote — cast a vote (separation-of-duties enforced by policy)",
        "POST /v1/claims/processing/{claimId}/transition — transition once quorum policy passes"
      ]
    },
    {
      "id": "claims-with-organizations",
      "title": "Organization-bound claims (any vertical)",
      "summary": "Claims owned by organizations, affiliations, and teams.",
      "steps": [
        "POST /v1/claims/processing — create with scope_id = organization scope",
        "POST /v1/organizations/{orgId}/affiliations — bind partner organizations",
        "POST /v1/claims/processing/{claimId}/transition — guarded transitions under org policy"
      ]
    }
  ],
  "x-generalization": {
    "note": "Every operation above is claim_type-generic. If an implementation needs a branch on a specific vertical claim type, that is a defect — vertical behavior belongs in declarative packs (lookups, path specs, indexability profiles).",
    "claim_type_examples": [
      "cns://claim/type/insurance/motor_claim",
      "cns://claim/type/community/request",
      "cns://claim/type/commerce/adjudication",
      "cns://claim/type/government/application"
    ]
  }
}