informed-decision/docs/specs/DecisionLifecycleService.md

# Decision lifecycle service

Status: initial audience deployed and human-accepted on 2026-10-05.
This is the product contract, including wider capabilities not yet delivered.
LifecycleHTTPContract.md names the implemented routes and source-only additions;
SCOPE.md and the workplan distinguish current delivery from remaining work.
Workplan: `INFD-WP-0007`; intake prerequisite: `INFD-WP-0005`.

## Outcome and boundaries

Agents and humans use one service to research, retrieve, prepare, evaluate,
register, publish, comment on, refine and accept decisions. The human workspace
is part of `https://decisions.coulomb.social`. Its headless foundation must be
usable without loading a browser or importing UI code.

“Decision” here means the deliberative record and the human's recorded answer.
`access-engine` still decides authorization; `approval-engine` still exclusively
owns approval state; identity comes through the established identity contracts;
`audit-core` receives evidence. Evaluation is advisory analysis, never an
authorization decision. Agents may contribute analysis and comments but may
never complete a human disposition. No change to the layer declaration is made.

## Capabilities

| Operation | Service responsibility | Observable result |
| --- | --- | --- |
| Research | Collect source references, retrieved snapshots or digests, provenance, retrieval time, relevant excerpts and uncertainty | Another reader can inspect the evidence behind a claim; inaccessible or stale sources are visible |
| Retrieve | Search/filter authorized records by text, identifier, status, topic and participant; return paginated revisions and evidence | Stable identifiers and links, without exposing inaccessible titles, snippets or counts |
| Prepare | Create a draft with a question, alternatives, recommendation, consequences, requested act and packet | An agent or human can save and resume without creating an approval |
| Evaluate | Attach assessments of alternatives, criteria, risks, objections and unresolved questions to an exact revision | Attributed analysis with citations; no automatic acceptance or claim of permission |
| Register | Allocate a stable record identity and retain provenance and revision history | Idempotent registration receipt and canonical URL; registration is not approval |
| Publish | Make a selected immutable revision available to an explicit audience for discussion/review | Durable publication receipt, audience and revision link; no implicit anonymous access |
| Comment | Append attributed discussion anchored to a revision or passage | Durable thread; agent contributions are visibly identified |
| Refine | Create a successor revision with a change summary and resolved/open feedback | Earlier content, comments, evaluations and human answers remain reconstructable |
| Accept | Record a human answer against the exact presented revision and required acknowledgments | Existing disposition guards and approval-engine integration apply; stale evidence cannot bind |

Research initially supports source ingestion, retrieval and structured research
requests/results. Automated external research uses explicit adapters with bounded
fetching, source access checks and timeouts. Retrieved text is untrusted data,
not instructions to the service. A universal crawler or a new model provider is
not a prerequisite for the first complete lifecycle.

## Headless foundation and UI

```text
Agent / CLI client ---- authenticated API adapter ---+
                                                    |
Browser UI ----------- human session/API adapter ----+--> application services
                                                          | domain rules
                                                          | storage + outbox
                                                          | external ports
                                                          v
                                      identity / access / approval / audit
```

The domain core holds memo revision and lifecycle rules, presentation evidence
and disposition guards. Application services orchestrate these rules using
storage and external-service ports. HTTP adapters validate envelopes and resolve
verified caller context. The UI renders responses and submits commands; it has
no independent lifecycle logic, authorization fallback or direct store writes.
Presentation creation stays in the foundation, with renderer identity and exact
displayed content supplied through the established presentation contract.

Separation is an import and contract boundary, not a requirement to introduce
multiple repositories or microservices. One initial deployable is acceptable if
the headless suite runs without UI imports and clients share application services.
UI assets may evolve independently of stable versioned API contracts.

Reuse `memo.py`, `presentation.py`, `disposition.py`, `store.py`, `review.py`,
`intake_service.py` and the outbox. Extract orchestration where needed. Do not
fork the governed Decision Memo schema. Research, assessments, publication and
discussion are companion records referencing a memo/revision; material promoted
into the human commitment must enter a new memo revision and presentation hash.
Existing Stage 1 human `comment` dispositions remain unchanged. Agent discussion
uses attributed companion comments, never a bypass of `G_NOAGENT`.

## Runtime data and revision semantics

A registered record has a stable id and immutable revision identifiers. Draft
saves produce revisions with an expected-current-revision precondition so two
authors cannot silently overwrite each other. Publication and human disposition
are separate records: publication can precede an answer, and an accepted revision
can later be republished to an authorized audience without changing the answer.

Draft -> published for discussion/review -> human disposition is the common
path, with repeated research/evaluation/refinement at any point. Return requests
another revision; decline and withdrawal remain distinguishable. A successor
to an accepted revision starts a new review and does not inherit acceptance.
Supersession links preserve the old answer and evidence. Neither publication nor
an advisory evaluation alters approval-engine state.

Creation, registration, publication, discussion, refinement and acceptance are
transactional data operations with durable evidence/outbox writes. Every mutation
has an idempotency key, caller attribution and explicit conflict handling.
Idempotency keys are scoped by caller and operation; payload mismatch is a
conflict. External effects retain pending/uncertain states and reconcile receipts
rather than blindly retrying approval creation or human entries.

For an already admitted submitter/class, a new id, revision or packet must need
no image build, Helm release, ConfigMap swap, exact-record policy edit or manual
store load. Ordinary lifecycle metadata is stored as application data. Admission
and authorization remain external policy responsibilities; service data cannot
self-grant access. Changes to trusted submitters/classes are separately governed,
and must not become a hidden per-decision deployment requirement.

## API and exposure contract

Preserve the existing private intake `POST /v1/memos` contract. Introduce a
versioned lifecycle resource, proposed as `/v1/decisions`, with create/list/get,
revisions, sources, evaluations, comments, publications, presentations,
dispositions and event/result retrieval. Concrete schemas, status codes,
pagination, limits, concurrency headers and compatibility rules are T02 work;
these names are not a claim that routes already exist.

Registration and publication return stable ids, revision ids and a URL on
`decisions.coulomb.social`; clients can retrieve a durable answer by id. An outbox
supports reliable result notification using admitted delivery destinations, not
arbitrary caller URLs. Agent polling uses this service's event/result endpoint,
not a polling loop against approval-engine to synthesize an inbox.

The browser reaches human endpoints through the existing origin/session boundary.
Private workload intake remains private. Headless does not mean anonymous or
publicly exposed: network exposure and non-cluster agent identity must be settled
against identity and platform contracts before enabling additional clients.

Every read, search and mutation enforces the caller's current entitlement. Human
and workload credentials are not interchangeable. A record listed as actionable
must open under the same identity when current policy and authentication
requirements still hold; any needed fresh authentication is an explicit step-up
flow, not an opaque dead end. Revocation and changed policy can still deny access.
Presentation evidence must not enter the authorization decision it presents for.

## Acceptance scenarios

1. An admitted agent registers a draft, adds sources and an evaluation, publishes
   it, retrieves comments, refines it and obtains a review URL through the API.
   A human performs the equivalent authoring operations through the UI.
2. A human opens that URL, sees the precise revision and change summary, comments
   or returns it, and later accepts with valid presentation evidence. The agent
   retrieves the confirmed answer and its revision; it cannot submit acceptance.
3. Repeat with another new decision and a successor revision while image digests,
   deployment revisions and policy/config pins remain unchanged. Restart the
   service and retrieve the same records. No operator store load occurs.
4. Concurrent edits yield an explicit conflict; repeated commands do not duplicate
   records or external effects. Lost replies leave recoverable pending outcomes.
5. Revising presented content rejects acceptance using the stale presentation.
   Earlier answers remain attached to their original revisions.
6. Unauthorized callers learn no protected content from lists, search, evidence
   or events. Removed admission, wrong audience and forged human context fail.
7. Foundation tests run without importing UI modules. UI integration exercises the
   same service operations and preserves existing live memo URLs and history.

## Delivery and unresolved contracts

First finish runtime/admission integration through `INFD-WP-0005`; the broader
service must not duplicate that work or obscure its remaining live gates. Build
the independent lifecycle foundation and contract tests while those gates close.
Then deliver API and UI authoring, search, research/evaluation and publication,
followed by the end-to-end acceptance above.

Existing Stage 1 PRD and architecture describe the first approval slice. This
document supersedes their exclusion of agent collaboration and human authoring
for the new increment, while preserving human-only dispositions and the evidence
and engine boundaries. L0 and L2 compatibility remain required.

Initial implementation choices are explicit in `LifecycleAdmissionBoundary.md`:
only the admitted cluster workload, authenticated publication, caller-supplied
research provenance, append-only retention, organizational human approval, and
no optional Hub outcome write-back. External identities, anonymous publication,
source connectors/retention controls and non-approval binding are expansion work
under INFD-WP-0008, not hidden prerequisites or enabled production capabilities.