ADR-065: SSA Benefit-Data Classification, Custody, and Retention

§D1–§D4 record decisions the plan’s settled constraints (SD1–SD14, the plan’s § Settled by the review block) already fix or that this ADR itself proposes (the benefit-fact custody home, §D2); they become Accepted with this ADR.

§D5 (UD2) and §D6 (UD3) were drafted as options and are now DECIDED — both ratified 2026-08-14 as Option 1 (maintainer steer, #1434 note): UD2 = the exchange-only audited CAS may set ssn_verified (the ADR-051 amendment is applied); UD3 = the ADR-057 twin (writes gated, reads open). The option tables remain below as the decision record.

The §D4 retention horizons additionally ride UD4/UD10 (needed by E3, later than UD2/UD3); the retention class assignment itself is decided here.

A2 — the classification’s teeth (#1428). DispatchClass::{Generic, TypedOnly} is a REQUIRED ErasedAdapter method — no default, so a hand-written impl must choose a class rather than inherit Generic by omission (crates/craig-exchange-contracts/src/erased.rs:38-45,105-110). The new typed_only macro arm pins TypedOnly AND makes the erased send_value/audit_value refuse unconditionally with the categorical ErasedAdapterError::TypedOnlyDispatch (kind token only, never payload bytes — erased.rs:136-144,317-373; the canary test at erased.rs:633-668 pins the no-echo property). Above that innermost layer sit three checkpoints, all keyed on the PARTNER-ROW kind via ExchangeRegistries::dispatch_class_of — never resolve(), whose noop:// substitution would mask the kind: send pre-claim 422 (services/craig-exchange/src/api/dispatch_guard.rs:21-38, called at api/transactions.rs:138), retry in-tx pre-restage (an Err rolls back the status flip; dispatch_guard.rs:75-87, called at api/transactions.rs:441), and the worker pre-resolve terminal typed-only-dispatch (services/craig-exchange/src/send_worker.rs:278-284 — terminal, not retryable: a policy refusal can never succeed on retry).

A4 — the digest identifier (#1430, SD12). SsnDigest in crates/craig-cases-contracts/src/ssn_digest.rs: canonical one-string wire form v{n}:{44-char base64} (serde try_from/into String, :51-60); PartialEq IS the subtle::ct_eq constant-time compare over the full canonical bytes — version + digest together, so a rotated-away version is NOT equal and the consumer classifies via .version() (:189-201); redacted Debug (version tag only) and NO Display — {} logging is a compile error (:205-209); categorical value-free parse errors (:106-115); leading-zero version tags refused for canonical uniqueness (:155-165); property tests pin parse-never-panics and byte-identical round-trips (the B1 cohort hash binds to those bytes). Wire-only — no sqlx::Type (B1 decides the column shape), no ToSchema (consuming DTOs annotate value_type = String, the Sha256Hex precedent).

A1 — the value-free adapter (1427, S2/S10). crates/craig-partner-ssa-solq: SsaSolqError is a CLOSED categorical enum — at most the bounded numeric HTTP status; body bytes, transport strings, and serde decode context are DISCARDED at the single mapping boundary (src/error.rs:19-56; src/adapter.rs:61-74 — explicit per-arm mapping, never [from]; canary tests pin no-echo through the full send path). NO in-crate mock or mock feature (a mock SSA endpoint would fabricate benefit-data authority; test fixtures land in C3 behind a production hard-refusal). Field-free #[non_exhaustive] wire placeholders per §D3. The transport-level response byte-CAP deliberately rides B4’s S13 egress controls — the transport hands adapters an already-fully-read Vec<u8>, so A1 alone cannot bound the read (recorded in the crate docs, src/lib.rs:32-40).

A3 — registration, refusal-gated (#1429). GeorgiaBundle registers the factory + audit codec (crates/craig-state-ga/src/lib.rs:105-132; the erased registration is the in-crate impl_erased_adapter!(SsaSolqAdapter, "ssa_solq", typed_only) at crates/craig-partner-ssa-solq/src/adapter.rs:131). PINNED_KINDS 11→12 with the lockstep test asserting generic-path rejection for every member of PINNED_TYPED_ONLY_KINDS (services/craig-exchange/src/adapters/mod.rs:38-47,79-91) — future TypedOnly kinds inherit the rejection proof automatically. Activation refusal: an ACTIVE partner row for any TypedOnly kind is refused 403 FEATURE_DISABLED naming the lift, keyed on dispatch_class_of (never the literal token), covering create, kind-flip-while-active, and PATCH {active: true} resurrection (dispatch_guard.rs:50-67, called at api/partners.rs:174,318); {adapter_kind, active: false} stage-ahead stays legal. The worker checkpoint is proven live by a #1195-style direct-SQL test that CAS-flips a staged row’s partner to the registered kind inside the worker’s poll window and asserts terminal typed-only-dispatch, never dispatch (services/craig-exchange/tests/api/send_worker.rs; ordering inverted vs t1195 because the registered kind 422s at ingress). Seed inventory: a DELIBERATE ABSENCE with the reason committed at the site (tools/craig-seed/src/datagen.rs:1664) — seeded partners are born active, so any seeded ssa_solq row would violate this unit’s own refusal; the B phase seeds the partner when the typed pipeline exists.

ADR-066 (companion, drafted with this ADR) — typed dispatch + pipeline + counterparty model; owns the mechanics §D1 leans on.

ADR-051 — full-SSN custody; §D2 is its anticipated §D5 exception made concrete; §D5 here carries its amendment stub.

ADR-058 — the two retention classes §D4 assigns SSA tables to.

ADR-022 — transport-window invariants; the replay boundary SSA transport rows inherit.

ADR-020 / ADR-048 — the encrypted-PII tier and its cases-only scope.

ADR-049 — blind-index threat model the digest posture inherits; the non-Serialize projection precedent.

ADR-041 — the accepted-plaintext boundary of the operational tier (name plaintext under compensating controls; DOB blind-indexed).

ADR-057 — the UD3 Option-1 writes-gated/reads-open precedent.

ADR-062 — the request_claims/claim-first machinery B3 reuses for run creation.

ADR-032 — the partner registry + erased seam the DispatchClass rides.

Plan: SSA Benefit Verification — SD1–SD14 (§ Settled by the review), the UD table (§ User decisions), § Findings traceability, § Verification matrix.

The production capability gate is a witness type: SolqSendAuthority::Gateway(GatewayProof) in craig-partner-ssa-solq, with a private-field proof struct and NO constructor exported pre-Phase-P — a production binary contains no expression that evaluates to it. Phase P exports the constructor in the same reviewed MR that flips main.rs None → Some (the recorded S4 posture: activation changes CODE, never config). The harness-only NonAuthoritativeStub variant exists solely under the contract-stub feature, enabled only from craig-exchange dev-dependencies; a blocking release-feature-graph lint asserts its absence from release builds (the resolver ≥ 2 assumption — dev-dep features don’t unify into release graphs — is recorded alongside the lint).

The worker’s dispatch_preconditions checks the witness first: None ⇒ pause contract-pending (hyphenated, a recorded deviation from #1479’s contract_pending, matching the existing worker token vocabulary) before any custody read — every pause exit precedes the JIT plaintext release, closing the B4 interim "send happens, response discarded" defect at the seam. Staging stays open pre-contract (a staged run is inert data). Layering: L1 witness (structural), L2 the pause (behavioral), L3 the endpoint-shape activation guard — kept, but demoted to ergonomics and explicitly NOT the custody boundary — L4 egress empty-denies-all.

Pause vs terminal taxonomy: PAUSE = deployment-scoped, operator/Phase-P-remediable, the same job may later send unchanged (contract-pending, gate-disabled, partner-unavailable, dsa-not-active, egress-refused, future auth-unconfigured); TERMINAL = a per-job/member fact no configuration heals (plus new freshness-expired). Post-send failures are never pause-class.

The invalidation_reason CHECK is rebuilt to exactly three tokens: cohort_changed, operator_cancelled, freshness_expired. The one-active slot is released by those three invalidation reasons plus run completion — never permanently consumed.

complete_run_if_final (an idempotent, guarded, converging UPDATE) fires from every member-terminal writer — the B5 outcome tx is one call site of several (the "outcome tx is the only completed writer" reading was review-refuted: B4 paths reach member-terminal with no outcome tx and would have held the slot up to 12 months). Invalidated-and-drained runs complete too — completion = "the pipeline finished draining"; invalidated_at stays the orthogonal witness-void marker. NO third run status; no stored aggregate counters (derive by COUNT — counters would enlarge the mutable-column allowlist for zero read).

Every invalidation writer runs ONE tx: stamp invalidated_at + reason; finalize the run’s paused AND unclaimed pending jobs → failed/run-invalidated with completed_at; terminal affected pending members → cancelled; then complete_run_if_final.

Fork 1 (ADOPTED) — operator run-cancel: an audited, HUMAN-only, cases-relayed endpoint (BOLA-checked, the B3-intent-path pattern) stamps operator_cancelled. Replay posture: one-way predicate idempotency — a second cancel returns a deterministic already-invalidated; the audit event names the actor.

Fork 6 — attempts reset to 0 on resume (#1469’s service-side human-admin live-precondition re-check): pause cycles must not burn the send budget; the ssa.jobs_resumed audit event preserves the pre-reset count; the shared #1185 claim shape is untouched. New paused_at column: pause_job stamps, resume clears.

Fork 2 (RATIFIED) — the freshness no-op: invalidating a completed run past the UD11 12-month horizon is a categorical no-op, expressed as an in-WHERE predicate on the invalidation UPDATE (NOT (status='completed' AND as_of < CURRENT_DATE - INTERVAL '12 months') — DB-side, monotone, never app-side check-then-write). It is information-free (such a run is already not a UD1 witness) and it is what lets runs quiesce for archive; NO current+history split. Rescoped deliberately (the review’s HIGH finding): pending runs stay invalidatable at ANY age — the unqualified refusal would have permanently bricked a stale pending run’s slot.

The §D4 known conflict is resolved WITHIN the UD4 delimitation (classification
≤90 d transport bound stayed closed; row/history mechanics were #1479’s): runs/members stay provenance class under mutation-quiescent-at-eligibility — a scoped ADR-058 amendment (shipping in the same B5 MR as the craig-retention spec.rs insert-only doc-comment rewrite) admits sources where no designed write path can touch a row once archive-ELIGIBLE: (1) monotone writes toward a terminal fixpoint; (2) eligibility predicates admitting only fixpoint rows; (3) writers structurally refusing fixpoint rows (0-row UPDATEs); (4) delete_by_ids_sql re-asserting the fixpoint, converting status-lattice regressions into the existing PruneCountMismatch rollback. Zero craig-retention engine changes. invalidated_at is named as protected SOLELY by the in-WHERE freshness refusal — precondition 4 covers only fixpoint-predicate columns. Rejected: event-sourcing (rewrites B3+B4) and a current+history split (quietly re-classifies runs/members to transport).

Mutable-column allowlist (pinned here; DDL-probe-asserted): runs = status, completed_at, invalidated_at, invalidation_reason; members = status, completed_at (outcome detail lives in the cases-side projection row, so the member allowlist does NOT grow). cohort_revision on runs is insert-time-only; the watermark table is an operational projection outside both retention classes.

Archive floors + residual risk: member fixpoint = terminal statuses with CHECK-paired completed_at; run fixpoint = completed AND past the 12-month quiescence horizon; the 12-month SQL literal is probe-asserted equal to SCREENING_FRESHNESS_MONTHS (never two numbers); the exchange SERVICE archive hot_window_days knob is load()-validated ≥ 365 d (per-engine, not per-table — recorded); purge stays refused pending DFCS (#1480). §D1 residual-risk note extended: to_jsonb archive NDJSON carries ssn_digest/cohort-hash values fetchable via xtask archive-fetch — the ADR-058 D9 store posture (encrypted, least-privilege, versioned bucket; Local refused) is the compensating control; never-log is unchanged.

Fork 4 (option a) — digest-registry version rotation: an operator mass-invalidation xtask as a rotation-runbook step, filed as #1489 (blocked on #1466); the D3 consumption-gate hash recompute stays the backstop. LANDED: cargo xtask ssa-invalidate-stale-cohorts --current-version N [--yes] — device-code OAuth as the human admin, driving the exchange sweep endpoint (POST /v1/exchange/ssa-screening-runs/invalidate-stale-digests), which invokes the B5 invalidate_run writer per run (never raw SQL) + the B6b invalidation event and stages the ssa.stale_cohorts_invalidated operator summary; runbook = operations/ssa-digest-rotation.adoc.

Producer-carried monotonic cohort_revision (cases.screening_cohort_revision, bumped through ONE seam at producer sites P1–P5 — household add, digest-transition update_person with the keyless fallback arm mirrored, clear_ssn, manual-link promotion, and §G4 auto-link promotion with the attempt tx threaded through promote_report_links; P7/P8 have no surface and are pinned as a data-model-page contract, not dead enum variants). Runs carry cohort_revision BIGINT NOT NULL DEFAULT 0 (insert-time); ssa_cohort_watermarks(case_id PK, cohort_revision, updated_at) is the per-case watermark. Revision comparison is order-independent; ABA over-invalidation is the accepted cost, failing toward re-screening. Rejected with recorded reasons: synchronous S2S, reusing case.person_updated (structurally insufficient), hash-compare (unsafe under reordering).

Fork 5 — MINIMAL event payload: ONE PII-free case.screening_cohort_changed outbox event per affected case, staged in the mutation’s own tx — payload = case UUID + cohort_revision + a categorical change token ONLY; no person_id, no digest (person-level tokens are activity-revealing to every queue reader). Exchange consumes on the existing inbox under the ADR-062 attempt tx: watermark GREATEST-upsert → strict one-way cohort_revision < invalidation (bounded by the fork-2 predicate) → the one-tx sweep. Replay no-op; out-of-order commutative; no wall-clock anywhere.

Fork 3 (ADOPTED) — staging auto-supersede: the staging endpoint UPSERTS the watermark (the row lock is the serialization point) inside the claimed tx and branches three ways on the RETURNING value: strictly newer ⇒ invalidate the active run (cohort_changed) + sweep + stage the new run in ONE tx (audited marker + the B6 exchange.screening_run_invalidated event — auto-supersede IS the legitimate recovery mechanism); equal ⇒ 409 SCREENING_RUN_ACTIVE; older ⇒ 409 SCREENING_COHORT_STALE; the supersede 0-row race re-checks/409s, never falls through to the partial-unique 23505. StageScreeningRunRequest grows REQUIRED cohort_revision (the mixed-version deploy window fails closed 4xx — pre-1.0, recorded). The "no active run below its case watermark" invariant is structural; NO reconciliation sweep — a report-only watchdog probes it.

ssa_benefit_facts rest in cases (§D2’s custody home, confirmed), born insert-only: pointer-forward supersession chain (supersedes_id FK KEPT, no-self-supersede CHECK; chain-root + successor unique partial indexes give structural exactly-one-current); the replay key is WIDENED to cover successor inserts (UNIQUE (screening_member_id, benefit_kind, beneficiary_role) WHERE screening_member_id IS NOT NULL); beneficiary_role joins the chain identity. Corrections, terminations, re-grants are all successor rows; the supersession race is insert-23505 → re-read head → retry. Facts are honestly indefinite-hold until DFCS names a schedule; onboarding facts to archive is a recorded future decision. Row types are not Serialize (§D3).

ssa_screening_outcomes (cases) — the review-mandated outcome projection (facts alone cannot distinguish NoMatch/Unmappable/zero-fact-Screened): transaction_id PK, run_id, screening_member_id UNIQUE, person_id, member_outcome, fact_ids, recorded_by, recorded_at — insert-only, provenance class, NO digests; joins the allowlist probe. Replays (in-window or post-prune) re-derive the response from this row with ORIGINAL facts.

Read posture: facts are true statements about (digest, person-binding-as-of-verify), NOT the person unconditionally — the SSN-correction window is the named residual; the UD1/D4 assembly gate is the only sanctioned consumer, and non-assembly fact readers must join run validity.

The provenance handoff relation is ssa_transport_handoffs — one insert-only row per member, written INSIDE the transport prune transaction, snapshotting the audit-relevant facts only the job/transaction rows held (correlation token, partner, attempts, final status, categorical last_error, timing). FK direction honors the migration-recorded rule (provenance never FK-depends on transport): the handoff FKs the MEMBER ON DELETE RESTRICT, which also forces the archive deletion order handoffs → members → runs. The plan’s archive-success precondition is discharged transactionally: the snapshot insert and the transport deletes are ONE atomic commit — no object-store round-trip gates the ≤ 90 d prune, and a crash can never leave a pruned row without its snapshot.

The transport sweep (ssa_retention.rs, worker ssa-transport-sweep) prunes terminal ssa_screening_jobs + their SSA exchange_transactions rows hourly under its own advisory lock, batched, windowed by CRAIG_EXCHANGESSA_SCREENINGTRANSPORT_RETENTION_DAYS (load()-validated 0..=90 naming UD4 — the ratified bound is a CEILING; 0 disables visibly, a devstack/test posture the overrun invariant catches in production, and one the archiver refuses to coexist with at load()). The jobs delete re-asserts the FULL eligibility predicate (terminal + windowed + member-terminal + typed-transaction-row + NOT legal_hold) PLUS a snapshot-exists guard (the handoff row must exist in the same transaction — a hold set→clear flap between the insert’s and the deletes' statement snapshots would otherwise commit a prune with no snapshot); the transactions delete re-asserts the hold
exchange-type legs (its job legs are consumed by the preceding statement). Short delete counts roll the whole batch back, and a mismatch-aborted pass withholds the sweep heartbeat so a persistent wedge alarms as staleness. Claims coordination is structural, pinned by test: no replay path consults transport rows (staging replays re-derive from the run, outcome replays from the projection), so the sweep can never manufacture a REPLAY_ENTITY_GONE.

UD10 legal holds live on ssa_screening_runs.legal_hold (run granularity as ratified; batch-grain holds land with the C1 import tables). The flag is an eligibility-predicate column: every retention statement selects on AND re-asserts NOT legal_hold, so ADR-058 §#1466 precondition 4 covers the sweeper race exactly — a hold committed between select and delete becomes a count-mismatch rollback (row locking makes this exact; no advisory lock). Transitive scope = the run join in every child predicate. The D10 mutable-column allowlist for runs is EXTENDED to status, completed_at, invalidated_at, invalidation_reason, legal_hold (probe updated) — unlike invalidated_at (writer-side-refusal-only), legal_hold is precondition-4-protected. Set/clear = human-admin-only endpoints (POST/DELETE /v1/exchange/ssa-screening-runs/{id}/hold, the fork-6 gate), reason-required both directions, each TRANSITION staging exchange.screening_hold_set/_cleared in the flip transaction (the reason rides the EVENT, never the row — the flag stays a bare boolean, the archive_records precedent). The hold endpoints are writes-gate-EXEMPT (the fork-1 cancel precedent): a hold must be settable on a deployment that has disabled the feature.

The exchange archive engine landed (retention_archive.rs + the archive_ledger migration — the craig-rules ledger shape verbatim, cargo xtask archive-fetch craig-exchange wired): three FK-ordered specs (ssa_transport_handoffs, ssa_screening_members, ssa_screening_runs), each embedding the family fixpoint (run completed AND past the 12-month quiescence horizon AND NOT legal_hold; the months ⇒ 12 SQL literal is probe-asserted equal to SCREENING_FRESHNESS_MONTHS) with NOT EXISTS deletion-order guards in BOTH the select and the delete. The family shares ONE age clock (completed_at = the terminal stamp carried onto the handoff), so the three tables quiesce together. Bookkeep is ledger-only — no fleet-bookkeeping event: unlike rule_evaluations, nothing downstream consumes SSA archival facts (recorded deviation from the rules shape). Consent (D11)
boot-probe (D10) + the ≥ 365 d exchange floor all apply; cases-side logical pointers (ssa_screening_outcomes.run_id etc.) resolve post-prune via the D17 ledger/archive-fetch path. No purge tooling ships (D14 — refused until DFCS names a schedule, #1480); the exchange ledger deliberately has NO legal_hold column until purge tooling exists to honor it — pre-archive holds are the run-row flag, and archived objects cannot be destroyed by any shipped path.

Operational acceptance: ssa_screening_oldest_pending_seconds (per-pass, zero-filled), ssa_screening_job_errors_total{class} + ssa_retry_exhaustion_total (post-commit at the retry choke point), ssa_partner_request_duration_seconds{outcome}, ssa_retention_lag_rows{class=transport|provenance} + ssa_screening_held_runs (hourly, the sweep’s executed pass), and ssa_screening_ready (the minute-cadence ssa-readiness-probe worker re-using live_preconditions, spawned only while the gate is on). Deviation, recorded: the plan’s "readiness degrades on enabled-but-unready" lands on the METRICS plane (gauge + transition-edge warn + runbook alert), not /readyz — the ssa-worker is Observed by recorded decision, and a partner-side condition must never unroute or restart the pod. Two report-only invariants (ssa_transport_retention_overrun, ssa_provenance_hot_window_overrun) watchdog the windows; the operator runbook is operations/ssa-screening-ops.adoc.