tegwick
871f5e05e8
Assistant: codex Assistant-Model: gpt-6-astra Assistant-Session: 01a10780-6d41-7952-9718-dfbc1f41236f
168 lines
11 KiB
Markdown
168 lines
11 KiB
Markdown
# Decision lifecycle service
|
|
|
|
Status: product direction requested by the founder on 2026-10-04; architecture
|
|
and API below are proposed delivery contracts, not shipped endpoints.
|
|
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.
|
|
|
|
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.
|