story TS-401: implement structured findings and conservative state machine

[veil-chow-fyaic]

Parent: #14. Requirements: FR-CAS-001 through FR-CAS-003. Depends on TS-302 and TS-303.

Outcome

As a caller/reviewer, I receive one persisted, replayable screening result and case whose state, signal, business action, findings, holds, evidence requirements, audit, and outbox event are derived conservatively from the exact immutable intake and versioned deterministic assessment.

In scope

• The sole automated case-state/business-action projection over canonical TS-303 findings.
• Stable screening result and case identities, result hash, version set, finding/evidence/hold graph validation, and initial append-only materialization event.
• One atomic PostgreSQL unit of work integrating the TS-302 idempotency/intake record with screening result, case projection, findings/evidence/holds, command/authorization audit linkage, and a PII-minimal screening.completed outbox envelope.
• Deterministic replay from exact input/source/rule/schema/matcher/model version references.
• An architecture boundary in which evaluators, matchers, models, source adapters, REST, CLI, MCP, and workers cannot write final human dispositions.

Automated projection

• Any open P0 -> ESCALATE, RED, ESCALATE and an active hold.
• Otherwise any missing-material-fact P1 -> INCOMPLETE, YELLOW, REQUEST_EVIDENCE and an active hold.
• Otherwise any other open P1 -> REVIEW_REQUIRED, YELLOW, HOLD and an active hold.
• Otherwise open P2 -> conservative configured review/monitor projection that never releases the named action.
• With no open P0/P1, automation may emit presentation GREEN_CANDIDATE, but persisted state remains non-final/reviewable and business action remains non-release until a later authorized human decision.
• Empty, corrupt, unavailable, contradictory, or incomplete assessment/version evidence cannot select a lower-severity projection.

Exact P2/no-P0/P1 demo behavior is a finite synthetic internal-policy value and must be documented; it is not production legal policy.

Acceptance

• Every canonical finding retains priority, status, fact class, safe summary, evidence/source/rule-evaluation refs, uncertainty, required action, owner role, due point, and deterministic identity.
• Case/result validation requires an exact closed reference graph and exact immutable input/version identities. Missing/orphan/duplicate/cross-tenant/cross-screening references fail closed.
• ScreeningResult.canonical_result_hash() is recomputed on every durable read. Equivalent replay over the exact version set produces the same semantic result hash and graph; altered evidence/version/order is rejected.
• First execution atomically commits one result, one case, one materialization event, exact findings/evidence/holds, one applied audit, and one outbox event. Same TS-302 key/hash returns the original committed graph; different hash conflicts.
• A real two-connection duplicate race and injected failure at every write boundary produce no duplicate/partial case, audit-success, or outbox set. Unknown commit outcomes resolve by exact idempotency/result reread.
• Outbox payload contains only canonical subject references, state/action/signal/result hash and necessary routing metadata—no raw request, party/goods/payment data, finding detail, notes, credentials, or private source values.
• Repository constraints and reads reject UPDATE/DELETE, forged authorization/event links, final-state writes without an authorized human event, invalid state/action/signal combinations, corruption, and cross-tenant references.
• Tests exhaust every automated severity combination, empty/corrupt assessment, expiry/change invalidation entry boundary, and forbidden attempt by evaluator/matcher/model/service/agent code to create HUMAN_CLEARED, HUMAN_BLOCKED, or CLOSED_NO_ACTION.
• Focused and repository-wide statement/branch coverage remain 100%; PostgreSQL 18.4/Compose evidence includes concurrency, rollback, corruption repair, downgrade/re-upgrade, persistence and zero residue.

Explicit boundary

TS-401 materializes the initial conservative case and proves final-state write isolation. TS-402 owns later evidence/finding events. TS-403 owns authorized human disposition commands, four-eyes/completeness/version/rationale/expiry/invalidation and the only repository port capable of recording final dispositions. No model score or transport success is clearance.

Production state/action policy, reviewer ownership, service levels, human authority and maximum expiry remain named human decisions. Synthetic demo policy may proceed without implying legal coverage.

[veil-chow-fyaic]

Planner refinement checkpoint

Execution is split into four review gates:

1. A — conservative projection domain: exhaustive priority/fact/state/signal/action/hold table, deterministic identities, closed graphs, replay hashes, and no final-state transition API.
2. B — application orchestration/reference UoW: exact TS-302 intake/idempotency plus TS-303 assessment, stable result/case/outbox construction, authorization rebinding, exact retries, failure atomicity, and unknown-outcome recovery.
3. C — migration + PostgreSQL 18.4: immutable result/evidence/events, constrained projection, command/authorization/outbox linkage, two-connection race, forgeries/corruption/downgrade evidence.
4. D — synthetic runtime/golden path/contracts/docs/CI: one durable conservative case from the canonical request and exact version set, safe re-read and restart; no REST/MCP adapter yet.

Boundary corrections:

• GREEN_CANDIDATE remains a presentation assessment, not a persisted final case state and never a release action.
• TS-401 does not implement callable human-disposition commands. TS-403 will own the only authorized final-transition repository port; TS-401 locks the schema/architecture so other modules cannot create those states.
• Expiry/relevant-change behavior is represented and negative-tested at the state boundary now, but actual append-only invalidation commands arrive with TS-402/TS-403.

No human gate blocks the synthetic conservative path after TS-303. Production P2/review policy, owners, authority and expiry remain explicit decision gates.