informed-decision/docs/specs/LifecycleFoundationContract.md

# Lifecycle foundation: first implementation contract

2026-10-04; `INFD-WP-0007-T02/T03`. This is the internal persistence slice of
`DecisionLifecycleService.md`. The protected application interface built on this
slice is documented in `LifecycleServiceContract.md`; HTTP exposure is pending.

## Implemented boundary

`LifecycleRepository` depends on the existing `Store`, memo and disposition
types. It imports no UI, HTTP runtime or provider client. It registers complete,
unbound version-one memos and creates immutable successor revisions. The existing
Decision Memo is reused without schema changes. Incomplete authoring drafts and
conversion of legacy/approval-bound records remain future work.

Each call carries `Attribution(tenant, Actor(subject, kind))` from its trusted
caller. This is audit attribution, not an authentication assertion. Like `Store`,
the repository is an internal persistence interface: the application/API
layer must authenticate callers and enforce current access-engine authorization
before invoking it. Supplying a tenant string is not an access grant. No route
or runtime configuration exposes these operations in this increment.

## Commands and reads

| Method | Contract |
| --- | --- |
| `register(context, memo, key=...)` | Version 1, no approval binding or seal; rejects ids already present in the memo store; returns durable event id |
| `revise(context, memo, expected_version=..., summary=..., key=...)` | Exact current revision precondition and next version; nonempty change summary; returns durable event id |
| `annotate(context, memo_id, version, kind=..., body=..., key=...)` | Append source/evaluation/comment to an existing exact revision; returns durable event id |
| `retrieve(tenant, memo_id, version=None)` | Retrieve current or historical memo only within its registered tenant |
| `events(tenant, memo_id, after=0, limit=100)` | Ordered cursor page of attributed immutable events, maximum 100 |

Registration returns the memo's existing caller-supplied id through retrieval;
generated public ids and canonical URLs are deferred to the API adapter. Memo ids
remain globally unique because existing review URLs and storage use that key.
An existing imported memo cannot be taken over by registration, even if its bytes
match. A tenant mismatch produces the same unavailable error as a missing record.
This is partition enforcement, not a replacement for per-record authorization.

Idempotency scope is tenant + actor kind/subject + operation + key. A SHA-256 of
canonical command JSON detects content conflicts, including changed revision
preconditions. Exact retries return the original event id even after subsequent
revisions. Different authors must use concurrency preconditions; matching content
alone never makes a stale edit succeed. The command bound is 256 KiB.

All writes use one SQLite transaction for memo content, immutable lifecycle event,
pending-delivery row and idempotency receipt. An event queue failure rolls back
the content mutation. Events contain actor, tenant, server timestamp, record and
revision; they do not record an authorization verdict or approval validity.

## Companion records

* Comment: `text`, optional `locator`. This is discussion, not a disposition.
* Source: `reference`, timezone-qualified `retrieved_at`, SHA-256 `digest`,
  `summary`. These are supplied research provenance, not a claim that the service
  fetched or verified the source. This slice performs no network fetching.
* Evaluation: `assessment`, `source_ids`, `uncertainty`. Referenced source event
  ids must belong to this record, tenant and revision. Up to 100 references are
  accepted. Empty references are allowed for an explicitly uncited assessment.

Fields are closed and text is bounded at 32,768 characters per field. Annotations
cannot silently enter `view_hash`. Promoting evidence into the commitment requires
a new memo revision using the existing packet/binding rules. Research comments
from agents never go through or weaken the human disposition guards.

## Migration, evidence and rollout

Store schema 4 adds `lifecycle_records`, `lifecycle_events`,
`lifecycle_operations` and `lifecycle_pending`; migrations from versions 1–3
preserve existing memo, presentation, disposition and evidence rows. Historic
records are not automatically registered or assigned a tenant. Existing store
backup includes lifecycle content and pending rows. Old code refuses schema 4;
rollback therefore needs restoration of a pre-migration backup and explicit
handling of intervening writes, not simply an old image against the new database.

Memo persistence is extracted into a shared transaction helper without changing
legacy `save_memo` behavior. Existing stale-presentation guards see the same memo
versions. Approval-bound/sealed revision handling requires the later review
integration; this repository refuses those lifecycle revision commands.

Pending lifecycle events are durable local obligations. They are not emitted as
invented Audit Core event types or reported delivered. The existing review audit
queue remains unchanged. Before exposure, T02/T03 must settle receiver admission,
payload/privacy, delivery retries and readiness accounting for the new queue.
Runtime readiness now refuses while lifecycle events remain pending, and the
admin inspection command reports content-free lifecycle counts. No events are
marked delivered without the future admitted receiver adapter.

## Remaining contracts

T02 remains in progress: production identity/policy composition, versioned HTTP schemas,
publication audience policy, incomplete drafts, non-cluster workload identity,
legacy record enrollment, source fetching/retention, independent evidence delivery
and non-approval binding integration. T03 is started with this persistence slice;
it is not complete. T04/T05 continue to own HTTP and UI exposure. Native runtime
intake and admission remain with `INFD-WP-0005`.