Plan: Transactional Idempotency Claims — Inbox + HTTP Ingress

#1178 — craig_mq::inbox::handle_idempotently (crates/craig-mq/src/inbox.rs:153) commits its claim, the handler’s effects, and processed_at as three separate autocommit statements, with an unlocked redelivery read. Real semantics: at-least-once with idempotency delegated per handler — which reporting (quality issues: fresh UUIDv7, no natural key) and security (plain audit insert) lack.

#1182 — the HTTP idempotency middleware (crates/craig-api/src/idempotency/) is a lease-based, unfenced 30 s claim, carrying the #1194 500-window — and is opt-in with ZERO senders (BFF, CLI, SDKs, e2e, k6 never send idempotency-key).

The 2026-07-31 handler-by-handler audit (two independent contextless explorers; verdicts in §R) found 30 non-create routes with stale-replay hazards (including two narrow/mild variants), 4 event-dup-only routes, one TOCTOU race (update_icpc_request), and `convert_report’s post-commit auto-link retry-LOST.

States pending→stored→promoted[→superseded], pending→failed(reaped_no_blob | digest_mismatch | target_gone), stored→failed(target_gone) (finalize-time discovery — the target vanished after the blob landed; the finalize tx rolls back whole, then the failing CAS + event land in their own tx), failed(reaped_no_blob | digest_mismatch)→pending re-open with generation++ and key rotation (a late zombie put fills only an abandoned g{n} key — swept idempotently while listed; a put landing AFTER its sweep is an untracked, unpromotable, harmless orphan). Every transition is a status+generation CAS; module crates/craig-store/src/attempts.rs owns the exact statements + sha256_hex + key derivation ({kind_prefix}/{target_path}/{attempt_id}/g{n}/{safe_name}; never name a variable gen — edition-2024).

One shared finalizer per target kind (an #[async_trait] AttemptFinalizer) runs identically from the handler and the reconciler: finalize tx = attempt CAS stored→promoted + entity INSERT (append kinds: contact/report/icpc/home attachments) or fenced pointer flip (replace kinds: court_orders.current_attempt_id
(created_at,id)-ordered winner — the pointer never NULLs, never regresses; exports flip current_export_attempt_id/export_generation) + the uploaded event — events atomic with READINESS on every path. The tx1 events + compensation paths in today’s four handlers are deleted.

Replay decision table keyed on the tombstone row (31 d retention ≥ every horizon): equal intent ⇒ drive remaining steps / fetch result (promoted ⇒ 200 with the entity; superseded ⇒ 200 with the newer current doc); different ⇒ 422 pre-write (the loser touches NOTHING); failed(reaped/mismatch) ⇒ re-open CAS; failed(target_gone) ⇒ 404; past-prune ⇒ documented fresh-attempt boundary; foreign created_by ⇒ 403.

UploadAttemptReconciler (1 h grace, 5 min interval, batch 100) replaces the AttachmentScanner semantics: digest-verified promotion (fixes promote-on-bare-exists()), reap CAS + failure event in ONE tx, abandoned-key sweeps, terminal-row pruning; scanner entity targets retire after a drain window (SU8).

Placement home_documents inverts blob-first and placement gains its FIRST reconciler worker (worker exact-set update). Exports: generated_on pinned in intent at first claim; bytes/filename never use now(); retry across a date change reproduces the byte-identical artifact; source drift ⇒ 409 export-source-changed (a new id ⇒ new generation supersedes; the old artifact is retained — federal evidence).

Multipart wire: uploads gain REQUIRED text fields client_request_id + file_sha256 (breaking ×5, CHANGELOG’d; there is NO existing JSON metadata part — the shared helper collects file + flat text fields, crates/craig-api/src/multipart.rs:43); exports take an optional JSON-body id. The court-order variant has NO attachment entity — tx1 is a fenced pending-flip on the court_orders row, entity_id = the court-order id.

Crash matrix + the six mandated race tests: scanner/put race (both orders), wrong existing digest, two concurrent court uploads, export retry across date/source change, late-put-after-reap, duplicate suppression.

Residue: devstack Garage put_create — VERIFIED in SU1 (2026-08-02, wire probe + the committed garage_put_create canary): Garage IGNORES If-None-Match: * PERMANENTLY BY DESIGN (CRDT, no consensus — upstream known-issue, not roadmap), so the prescribed fallback is IN the substrate: store_blob_create prechecks via read-back digest verify before put_create, and the residual precheck→put window is convergent by construction (every legitimate writer of a key passed the declared-digest gate against the same immutable claim row — the horizon table’s "puts converge by digest+generation" IS the correctness anchor; the conditional put is defense-in-depth on honoring backends). Remaining residues: post-31 d id reuse; failure-event latency = grace; the entity-delete orphan-blob window is PRE-EXISTING (#1274).

G1 cases (as built): update_person (IDF row-change gate over the plaintext columns + the two DETERMINISTIC hmac siblings — ciphertext is randomized and cannot IDF; verification reset only when ssn_full_hmac IS DISTINCT FROM, superseding ADR-051’s every-write-resets — named in ADR-062 §Supersessions; SUP; the zero-row no-op returns the locked row), attest_ssn (AND ssn_verified=false; zero-row disambiguates under the row lock: 404 / MISSING_SSN / STALE_ATTESTATION / same-digest-verified ⇒ 200 no-op / moved-concurrently ⇒ 409), revoke_ssn_verification (AND ssn_verified=true + SUP), clear_ssn (value-bound widened to ssn IS NOT NULL OR ssn_last_four IS NOT NULL so the remedy still clears a standalone last-four; SUP), update_allegation (version CAS in the body; version BIGINT column + response field), update_investigation (status pin ALWAYS armed so the closure gate is exact; event only on a real transition; IDF over the non-status fields; zero-row ⇒ 409 unless the current row already embodies every requested field ⇒ 200 no-op), update_case (status AND assigned-worker pins always armed; case.closed/case.updated only on an actual status change; assignment event exact under the pin), update_case_plan / update_task (IDF + SUP; update_task additionally gains the fleet-standard AND active = true its delete already had — soft-deleted tasks were mutable), update_contact / update_court_order (AND active=true + REQUIRED If-Match version CAS — missing 400, stale 409, deleted 404; version bumped every write and exposed in responses).

G2 placement + exchange: update_foster_home (version CAS via REQUIRED If-Match, not the originally-drafted expected-license-status pin — the named kill-target is the active→suspended→active ABA cycle, and a client-carried expected-STATUS re-matches after the cycle so it cannot block the replay re-suspension; only the monotonic foster_homes.version counter distinguishes the replay, and same→same transitions are already 400 by matrix so the plain retry was never the live hazard; G1 contacts/court-orders wire semantics: missing 400 / stale 409 / bump every write), update_training (IDF
the fleet-standard AND active=true its delete already had — soft-deleted training was mutable) / update_kinship_option / update_education / update_health (IDF no-op gates; education/health additionally SUP — their unconditional education.updated/health.updated staging was 2 of the audit’s 5 event-dups; kinship/training stage no events), exchange update_partner (version CAS via REQUIRED If-Match — kills the deactivated-partner resurrection; delete_partner’s deactivation ALSO bumps `version, else a pre-delete If-Match would still match post-delete and resurrect through the window), delete_partner (AND active=true; double-DELETE now 404 per the fleet convention — previously 204 forever re-stamping updated_at), update_agreement (approved_by/ approved_by_name/approved_at all FWW COALESCE(col,$) — one approval stamp, first wins; always-armed AND status=$expected CAS; the store fn’s fetch_one 500-on-missing bug becomes a clean 404 in passing), update_icpc_request (AND status=$expected — closes the TOCTOU; the staged icpc.status_changed from_status is now proven by the pin, SUP).

G3 security + reporting + rules + financial (as designed from the route audit; the generic "status/version CAS" resolves per route): update_review (always-armed status pin from the validated pre-read + the missing AND active = true — a soft-deleted review was still mutable — + fetch_optional: a lost race was a 500), update_nist_control (status pin + fetch_optional 500 fix), update_admin_unit / update_detection_rule (version CAS via REQUIRED If-Match — no status column exists and a stale replay clobbers reference data / re-enables a disabled detection rule; API/CLI-only surfaces), security update_partner (version CAS via REQUIRED body version — the G1 allegations pattern because a craig-web form drives it; suspension cycles are ABA-vulnerable exactly like exchange partners, so a status pin cannot block the stale re-suspension), update_major_change (the event gates on the actual false→true flip read UNDER the update tx — the old gate re-staged security.major_change.reported on every repeated {reported_to_acf: true} PUT), resolve_issue (AND resolved = false; an already-resolved replay converges to 200 returning the ORIGINAL resolver — attribution is first-write-wins), AFCARS/NCANDS review/approve ×4 + transmit ×2 (always-armed AND status = $expected from the validated pre-read — closes the approved→reviewed pre-read-clobber TOCTOU; transmit events stage only on the guarded row, pinned by an N-concurrent-transmits exactly-one-event invariant test), update_rate (AND active = true — a tombstoned rate was still mutable — + version CAS via REQUIRED If-Match; new rate_tables.version), submit_claim (AND status = 'draft' + SUP — concurrent double-submit double-published financial.claim_submitted; pinned by the payments-suite 8-way-race shape), update_rule_set (revision CAS via REQUIRED If-Match — the trigger-bumped rule_sets.revision mints a fresh token for every write, so a stale replay was LEGITIMIZED into the JDM live cache; the import route arms the same store predicate from a locked in-tx read). Version columns ride one migration per service (security ×3: partners / admin_unit_registry / detection_rules; financial ×1: rate_tables); reporting and rules need none (status-only / revision exists).

G4 convert_report resumability (as designed from the wiring recon): auto-link
rollup move to a NEW craig-cases consumer of its own case.report_converted on the Track A substrate; the post-commit pipeline call is deleted. (Audit: conversion.rs:82-186 — a response-lost retry short-circuits and the winner dying post-commit skips the pipeline forever.) Mechanics: the event payload gains seed_case_id (the consumer cannot otherwise reproduce the request’s household seed); queue craig-cases.events bound to case.report_converted via the placement A2 subscriber shape (handle_idempotently + tx_handler, Critical events-subscriber worker) — the #1202 broker credential for craig-cases widens to cover craig-cases\.events (definitions.json + the broker_permissions fleet pin + the deployment guide’s rabbitmqctl forms, in lockstep per the amendment). Auth: the consumer mints the CASES SERVICE PRINCIPAL bearer (br.service_token, the financial A4 S2S-inside-handler pattern, rules calls bounded inside the 15 s attempt deadline) replacing the borrowed user header. Atomicity split, stated honestly: per-link inserts keep their OWN #799 link+audit transactions and converge by the report_persons UNIQUE (replay skips); the ROLLUP event alone stages on the claim transaction — exactly-once by the inbox claim. Semantics change (pre-1.0, CHANGELOG’d): convert’s 200 now means "referral committed, links pending"; the synchronous-link battery tests move to bounded polling via the rollup completion oracle; a raw-envelope redelivery leg (the financial placement_ended_void shape) pins the inbox dedup; a degraded pass (rank failures) refuses consumption so transient faults become counted retries. The #799 fault leg became the DEGRADED-PASS leg end-to-end: its outbox trigger self-disarms on read-committed visibility of the claim row’s error_count >= 1 (attempt 1 cannot see its own uncommitted claim; the immediate strike-1 requeue redelivery can), pinning refusal-counted-once
convergence + the per-attempt link/audit atomic pair in one deterministic arc — a PERSISTENT fault cannot converge by design (post-strike-2 resumption is the ADR-022 §D4 admin replay, operator-paced).

Audit-proven CONVERGENT routes receive characterization tests pinning their guards (grouped into the G MRs).

A1: claim+effects+stamp atomicity; deferred CONSTRAINT TRIGGER … INITIALLY DEFERRED commit-failure (built fresh — the #804 row trigger fires at statement time, the wrong point); many-concurrent-all-failing ⇒ the cap stays hard at 5; concurrent duplicate ⇒ one effect; sync-construction panic COUNTED; NULL-hash legacy row ⇒ dedup, not poison; collision path (canonical row untouched, own token); unroutable ⇒ failed_at-NULL + watchdog + replay-after-binding-restore; pg_sleep slow winner ⇒ the duplicate dedups; real-broker ladder (terminal at 5, 6th dedups, byte-identical re-surface absorbed); accounting-commit failure ⇒ not counted; timestamp progression; RED receipt vs the old fn.

A2–A6: per-service truth (#804 rollback-unclaims; security two-writes-atomic; financial S2S-timeout rollback proof + billing e2e; rules audit-in-substrate-tx; reporting zero-partial-issues).

B1b: intent proptests (key order, path, actor, jurisdiction, unicode); barrier collect-all N-same-key ⇒ 1 claim + 1 row + N×200; forced claim rollback; REPLAY_ENTITY_GONE; scope/actor/entity_kind mismatch leak-free; pruner-race single-statement pin.

Per conversion slice: EVERY route instantiated — concurrent create ⇒ one row; replay ⇒ the endpoint’s own success shape; mismatch 409; missing field 422/400 by body shape; commit-then-response-loss replay; same-key-different-path 409; actor separation.

§U (SU7): the six mandated race scenarios.

§G: per-route replay pins (each fixed hazard ⇒ replay converges + no dup event + the audit’s named interleaving reproduced) + characterization tests for all 35 PROVEN routes
drain-by-design pins for archive run/purge.

Bs2: concurrent second-issue; secret non-reexposure; rotate response-loss.

Bc3a/b: fresh-captcha retry replays; JTI re-sign; honeypot stable fake id; multipart proxy field forwarding.