A-02 — Runbooks (step-by-step recovery)

How to tell it's broken → what to do. Use real command surfaces only; nothing here invents a green status.

R-01 — Outbox relay stalls / pending depth stays high

Symptom: [BFF] Platform outbox relay failed: Error: Cannot perform subtraction with 'outbox:...' and 'NONE' every 15s, or GET /v1/claims/processing/readiness shows surreal up but zero check on the claims path stays dark; pending depth (SELECT count() AS c FROM nats_outbox WHERE status='pending' GROUP ALL;) never drops.

Cause (proven 2026-11-09): two relay bugs. (a) bare sqlString built mark_outbox_published(outbox:01a...) — the id is parsed as arithmetic on its tuple segments. (b) recordOutboxFailure was itself unguarded, so one bad mark aborted the whole sweep forever.

Fix (already shipped): nats-outbox-relay.js now uses sqlText for outbox ids and wraps failure-recording in per-row try/catch. If you fork the code again, never build fn args from bare sqlString — use sqlText for any string value (route or relay alike).

Drain a stuck queue fast (temp instance only):

$env:PLATFORM_OUTBOX_SUBJECT_PREFIXES='claims.lifecycle'  # skip unrelated subjects
node src/index.js   # from apps/agent-bff with DEV_SKIP_AUTH=1
# verify becomes: node scripts/verify-claims-event-consumer-live.mjs

R-02 — Transition returns 500 / "Unknown function"

Symptom: POST /v1/claims/processing/:claimId/transition returns 500 with Unknown function 'array::some'.

Cause: SurrealDB 3.0.5 doesn't ship array::some. Membership check is $x IN $arr. Strata edits: re-import with surreal import --endpoint http://127.0.0.1:8000 --ns africa --db community_os --user root --pass root database/schema/strata/s282_processing_claim.surql and confirm idempotency.

General rule: BEFORE trusting a stratum function on the live plane, exercise it. The claims plane's dry-run routes hide broken Surreal fns.

R-03 — No outbox rows for a transition

Symptom: transition OK 200, then no nats_outbox row for the claim, consumer silent.

Checklist (in order):

Response outbox.ok — the route returns honest status; outbox_persist_failed means the sink failed (e.g. payload type error — payload must be an OBJECT literal: use sqlObjectLiteral, null → NONE).
subject/claim-type: envelopes with claim_type: null fall to default subjects and get refused by the consumer (pack_not_found). Ensure the transition fn returns claim_type (s282 does since the fix; body-supplied claim_type is a fallback).
The envelope must be the payload: build envelopes through buildLifecycleEnvelope only; consumers read envelope.claim_id/claim_type/correlation_id.
Relay liveness: [BFF] Platform outbox relay: ticks logged; depth query as R-01.

R-04 — Relay not started at boot

Symptom: [BFF] Platform outbox relay not started: await is only valid in async functions… — a require-time error inside nats-outbox-relay.js killed the module.

Fix: every helper used in string building is synchronous; every fetch function that awaits is async. Verify after edits: node --check apps/agent-bff/src/nats-outbox-relay.js.

R-05 — Camel routes missing

Symptom: claimgen intake/extgate silently absent; readiness camel probe may still be green.

Cause: the claims Camel routes load only with CLAIMGEN_CAMEL=1 in the compose include env. Rebuild the image after env changes (docker compose -f docker/compose.microservices.yml --profile compliance). End-to-end proof is the round-trip script, never /q/health alone.

R-06 — Kestra flow registration

Symptom: claims.sla_timeout enforcement unverified (file exists at workflows/kestra/claims-sla-timeout.yaml).

Check: open the Kestra UI on :8180 and search the claims namespace — file presence is not registration. (Open item from the retrospective — REVIEW-06.)

R-07 — `:3030` predates new routes

Symptom: new endpoints 404 on the shared BFF while temp ports work.

Rule: after shipping routes, either restart :3030 (coordinate with the other agent) or verify on a temp port (PORT=3071, DEV_SKIP_AUTH=1) and note it.

R-08 — Stale function after a stratum edit

DEFINE FUNCTION via HTTP returns "NotAllowed"; surreal import is reliable for table/field/index but can silently drop function bodies — re-import + spot-check the fn (RETURN fn::x::y(...) echo) before relying on it.