informed-decision/docs/specs/LifecycleReviewHandoff.md

Revision-specific lifecycle review handoff

2026-10-04; INFD-WP-0007-T02 through T06. Source implementation, not deployed.

Headless contract

POST /v1/decisions/{id}/review-requests accepts version and options, with an Idempotency-Key. Options have exactly submitter, memo_class, review_group and approval_intent (the existing intake action/principal/purpose/target object). A fresh lifecycle.request_review policy observation covers the complete command; context.review_routing exposes these routing/act facts to the PDP. Publication is required for that current revision. Publication itself never initiates review.

The service atomically retains one immutable review_requested event per source revision, its source attribution, and an intake envelope under a fresh review memo id. Retries return the retained request; different commands for the same key or a second request for that revision conflict. This creates neither an approval nor a disposition. The envelope and event fit within 256 KiB. An admitted workload submits the exact returned envelope to the existing private intake. The envelope is also retained in authorized event history for recovery.

The handoff currently supports the platform tenant, English organizational approve memos at the current renderer release, and the intake's nonempty UTF-8 packet profile. Unsupported projections are refused rather than dropping fields. Broader L0/L2 profiles, browser packet authoring and automated forwarding remain live work in T02/T04/T05 and WP-0005. There is no automatic submitter or default workload credential. A caller-selected submitter is a routing request, not identity. The local use of intake's shape validator does not grant admission: intake always reauthenticates the workload and reloads its actual grant and recipient mapping.

Immutable snapshot and uncertainty

The original lifecycle memo remains unchanged. Intake alone assigns the named human and the engine-returned approval pins to the protected review snapshot. The snapshot's local version is one; the immutable request and presentation content link it to the original source id and revision. The human review page shows that source revision. The shared Decision Memo schema and signature rules are unchanged; the source link is provenance, not a new authorization claim.

Before reserving engine creation and before local loading, intake checks exact envelope equality, the designated submitter and source currency. Any change fails closed. Existing durable creating/created receipts retain uncertainty; a lost create reply is never automatically reposted. A revision during creation can leave an engine object with a retained receipt but no reviewable snapshot. This needs existing explicit recovery/reconciliation, not an automatic retry or an inferred revocation. Approval Engine remains the sole approval-state owner.

Direct import and revision of reserved review snapshot ids are refused. Source revisions invalidate subsequent presentation, acknowledgment, disposition and entry reservation. Once an entry is in flight or unresolved, source revision is blocked until the original attempt is resolved. This serializes local mutation against external entry attempts without pretending to make the network atomic. Historical accepted evidence remains available; a successor inherits no answer.

Outcomes and human workspace

GET /v1/decisions/{id}/outcomes?version=N requires a fresh lifecycle.outcomes check. It returns the correlated intake delivery state, source staleness and recorded dispositions with their submission state and confirmation timestamp. These are local evidence and transport states, never cached approval validity. prepared, in_flight and unresolved are not confirmed acceptance.

The workspace displays authorized outcomes and links a ready, current handoff to /review?memo_id=.... That route still requires its independent review PDP checks, verified human identity, fresh presentation and required acknowledgments. Agents can prepare, forward and retrieve; they cannot answer. No lifecycle accept route exists. Audience access and the named human review entitlement are separately checked by their existing policy consumers; a workspace link grants neither.

Evidence and delivery

The request event enters the existing lifecycle commitment queue. Intake posing, presentation, disposition and submission evidence keep their existing independent outboxes and receipt requirements. The integration test creates an approval via the real Approval Engine API, records a signed-fixture human entry, retrieves the confirmed result for source revision two, and delivers lifecycle and review commitments to the real Audit Core receiver. Identity and PDP transport are synthetic. Production grants, private listener/forwarding composition, full release/rollback evidence and separately approved rollout remain outstanding.

Migration and rollback boundary

Opening the store upgrades schema 4 to schema 5 transactionally, adding unique indexes for review snapshot identity and source revision. Existing evidence is preserved. The version change deliberately causes older Store implementations to refuse the database: they do not enforce these source guards. Before activation, retain the normal database backup and image/config pins. An older-image rollback requires a compatible restored database plus reconciliation of any subsequent engine side effects; it cannot safely discard new review/entry evidence. A reviewed forward fix remains preferable once new handoffs have been written.