informed-decision/docs/specs/LifecycleHTTPContract.md

Lifecycle HTTP adapter — initial subset

2026-10-04; INFD-WP-0007-T04, in progress. LifecycleAPI is an unmounted WSGI adapter over LifecycleService. It starts no listener and adds no route to the existing browser app or public ingress.

Method and path	Input	Result
GET /v1/decisions/{id}	Optional positive integer version	Existing Memo JSON for the current or specified revision
GET /v1/decisions/{id}/events	Optional after sequence cursor, limit 1–100	{"events": [...]} ordered by sequence; use last returned sequence for next page
POST /v1/decisions/{id}/comments	{"version": 1, "body": {"text": "...", "locator": "optional"}}	Durable event receipt
POST /v1/decisions/{id}/sources	version and source body per LifecycleFoundationContract	Durable event receipt
POST /v1/decisions/{id}/evaluations	version and evaluation body per LifecycleFoundationContract	Durable event receipt

Ids are 1–256 ASCII letters/digits or ., _, :, -. POST requires exact Content-Type: application/json, a declared byte length up to 256 KiB and a nonempty Idempotency-Key up to 256 characters. Mutation receipts are HTTP 200 for both first submission and replay, with event_id, memo_id, version. Unknown fields, duplicate JSON/query keys, non-finite JSON values, boolean revision numbers and truncated bodies are rejected. Version-one registration, revision, search, publication and disposition routes are not yet exposed.

Authentication runs before routing or reading a mutation body. The composition must explicitly supply a bearer-token verifier returning an authenticated Caller. There is no default or testing fallback. Cookies are not credentials for this adapter; its future human browser integration must provide a separately reviewed session/CSRF boundary or admitted bearer identity. Neither the intake SA audience nor the browser's approval-engine access token is implicitly admitted.

Every handled command invokes the shared policy-consuming service. Clients cannot supply tenant, actor or policy evidence in the body. Reads and retries receive fresh checks. Denied existing/missing record reads return the same policy-denied response. No new authorization verdict or approval mutation is produced here.

Responses are JSON with Cache-Control: no-store and nosniff. Errors are bounded {"error": "code"} envelopes: 400 invalid request, 401 missing/failed/expired identity, 403 policy denial, 404 unavailable record/route, 405 unsupported method, 409 conflict, 413 oversized body, 415 unsupported media type, 503 unavailable service or unusable policy evidence. Raw exception text and credentials are never returned. Upstream raw diagnostics are not forwarded.

T04 remains in progress: complete closed memo mutation schemas, canonical URLs, search/publication contracts, admitted authenticators and runtime wiring. Current tests use the real service/repository/PolicyClient with synthetic authenticator and PDP transport; they establish adapter behavior, not live identity admission. Runtime must not expose this adapter before lifecycle policy and independent event-delivery contracts are accepted and readiness can be satisfied.