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

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.

Open implementation contracts: workload identity beyond cluster service accounts; publication audience policy and any later anonymous publication; source connector set and retention; non-approval L2 binding integration. T02 must make these explicit before implementation depends on them. None authorizes a production rollout or changes external owners' contracts by declaration.