diff --git a/docs/decision-services-alignment-answer.md b/docs/decision-services-alignment-answer.md new file mode 100644 index 0000000..5e932b5 --- /dev/null +++ b/docs/decision-services-alignment-answer.md @@ -0,0 +1,218 @@ +# Decision services alignment: State Hub owner answer (S3) + +**Date:** 2026-10-31 +**Answers:** hub message 59390db6 (net-kingdom), proposal +`net-kingdom/docs/proposals/2026-10-31-decision-services-alignment-review.md` (commit b764561), +sections 3, 4.4, 5 (S3) and open question 6.4. +**Status:** owner answer; design only. No API, schema or deployment change is made with this +document. Implementation is proposed as `workplans/STATE-WP-0101-decision-evidence-links.md`. + +## 1. Answer in short + +**S3 is accepted, with adaptations.** + +- Hub decisions become the *index* of open questions. Decisions of class C1 or C2 are resolved + only by evidence from informed-decision, never by free text. C0 stays as today. +- **Adaptation 1, transport:** the write-back is carried by State Hub's existing private memo + dispatch worker (STATE-WP-0096), which pulls the decided outcome from informed-decision with its + existing intake-audience token and posts it to one new authenticated hub route. informed-decision + does not get a hub credential, and the hub authenticates exactly one writer. +- **Adaptation 2, authority:** a hub decision's `resolved` status is a projection of evidence held + by informed-decision, approval-engine and audit-core. Nothing may execute on the strength of a + hub decision status. A C2 executor checks the approval object, never the hub. +- **Adaptation 3, retirement:** State Hub is in retirement (`INTENT.md`, `prj-state-hub-retirement`). + The change is kept small and portable so it can move to the decisions owner in hub-core without + reshaping. The decisions capability needs a keep/move disposition in the retirement ledger; this + design does not claim permanent ownership. + +**Answer to 6.4: both, split by purpose.** Typed columns for the fields the hub enforces, constrains +or queries on; one typed `evidence_refs` list for everything else. Details in section 3. + +## 2. What exists today (state-hub evidence) + +- `decisions` (`api/models/decision.py`): `status` open/resolved/escalated/superseded, + `decided_by` free text (100 chars), `rationale`, no link to a memo or approval. +- `POST /decisions/{id}/resolve` accepts `{rationale, decided_by, write_log}` from any caller. The + only gate is a required multi-owner review contract, if one is attached. +- `PATCH /decisions/{id}` can set `status`, `decided_by` and `decided_at` directly, which bypasses + even that gate. `POST /decisions/` can create a decision already `resolved`. +- `api/services/memo_forwarding.py` already contains a resolution ledger (`observe_resolution`, + `run_due_resolution`). It posts the free-text payload above to `/resolve` and recognises its own + earlier resolution by searching the rationale for `memo `. No production caller invokes it; + that is the "disabled" write-back. +- The dispatch worker runs as `system:serviceaccount:state-hub:state-hub`, has no database + credential, and its NetworkPolicy allows egress only to DNS and informed-decision intake on 8081. +- The hub API has no authenticated-caller boundary (STATE-WP-0096 rationale). STATE-WP-0100 adds + claimed write attribution for all writes; its token verification is observe-only by founder + decision of 2026-10-25. + +## 3. Data model (answer to 6.4) + +### 3.1 Columns on `decisions` (enforced, queried) + +| Column | Type | Purpose | +| --- | --- | --- | +| `decision_class` | enum `C0,C1,C2,C3`, nullable | NULL means legacy and behaves as C0. Raise-only once set | +| `memo_id` | text, nullable | informed-decision memo that answers this question. Replaces the rationale search for correlating a 409 | +| `approval_id` | uuid, nullable | approval-engine object; required to resolve C2 | +| `resolution_source` | enum `text,informed_decision`, nullable | how it was resolved | +| `resolution_evidence` | jsonb, nullable | the verified write-back record (section 5), stored as received | + +Constraints (DB CHECK and API): + +- `status = resolved AND decision_class IN (C1,C2)` requires `resolution_source = informed_decision`, + `memo_id` and `resolution_evidence` not null. +- `status = resolved AND decision_class = C2` additionally requires `approval_id`. +- Unique partial index on `memo_id` where not null: one memo answers at most one decision. + +Why columns here: these fields carry rules (who may resolve, what must be present), the conflict +check needs an indexed lookup instead of a text search, and the dashboard and `needs_human` views +filter by class. + +### 3.2 `evidence_refs` (descriptive, not enforced) + +`evidence_refs`: jsonb list, default `[]`, items `{type, ref, digest?}` with a closed `type` +vocabulary validated by the API: `presentation`, `audit_record`, `ccr`, `workplan_task`, `adr`, +`commit`, `document`. Agents may add references to any decision class (for example the CCR or the +workplan task that a decision concerns). They do not resolve anything and have no constraint +attached. The vocabulary grows by owner change, not free form. + +### 3.3 Why not only one of them + +- Only typed refs: the C1/C2 rule becomes "a ref of type X must exist", which a DB constraint + cannot express cleanly, and the 409 correlation stays a scan. +- Only columns: every new evidence kind would be a migration in a retiring service. + +## 4. Resolution rules + +| Path | C0 / legacy (NULL) | C1 | C2 | +| --- | --- | --- | --- | +| `POST /decisions/{id}/resolve` (text) | allowed, as today | 409 `evidence_required` | 409 `evidence_required` | +| `PATCH` setting `status=resolved`, `decided_by`, `decided_at`, `rationale`, `memo_id`, `approval_id`, `resolution_*` | allowed for C0 (as today) | refused | refused | +| `PATCH` changing `decision_class` | may raise | may raise, never lower | never lower | +| `POST /decisions/` with `status=resolved` and class C1/C2 | allowed for C0 | refused | refused | +| Supersede (`DELETE`) | allowed | allowed (withdraws the question; records who and why) | allowed; does **not** revoke the approval object | +| `POST /decisions/{id}/resolve-evidence` (new) | refused (C0 needs no evidence) | authenticated writer only | authenticated writer only, `approval_id` required | +| MCP `resolve_decision` | as today | gets the same 409 from the API | same | + +Who sets the class: the creator, at creation or later by raising it. Doctrine for which class a +question needs comes from gate-house (S5). Until S5, the hub suggests a floor only for the existing +financial/legal auto-escalation keywords (C1 minimum). Linking a decision to a task with +`needs_human: true` does not by itself raise the class. + +The existing review-contract gate keeps applying on both resolve routes. + +## 5. Write-back: who writes, how it authenticates, what informed-decision sends + +### 5.1 Flow (pull through the existing dispatch worker) + +1. A C1/C2 hub decision is posed as a memo through the existing STATE-WP-0096 path. The envelope + already carries `serves: {hub_decision_id, resolves: on-answer}` and the stable idempotency key + `state-hub..`. At enqueue the worker records `memo_id` on the decision + through the new route's link mode (section 5.3), so the hub shows what is waiting where. +2. The founder decides in informed-decision (accept or decline, at the assurance the class needs). +3. The worker reads the outcome of its own submitted memos from informed-decision with its existing + intake-audience token. informed-decision answers only for memos this submitter posed. +4. The worker validates the outcome record (section 5.2) and posts it to + `POST /decisions/{id}/resolve-evidence`. +5. The hub verifies the caller, checks the record against the decision (class, `memo_id`, + `approval_id`, `hub_decision_id`), stores it, sets `resolved`, writes a `decision_resolved` + progress event and publishes `org.statehub.decision.resolved` with the evidence fields added. + +Why pull rather than informed-decision pushing: informed-decision then needs no hub credential and +no egress to the hub; the hub admits one writer it already deploys; the worker already holds the +retry, replay and conflict ledger. If informed-decision prefers push, the same route works with +informed-decision's workload subject allowlisted instead; that is a founder choice (section 8). + +### 5.2 What informed-decision must send (outcome record, `informed-decision.decision-outcome` v1) + +| Field | Required | Notes | +| --- | --- | --- | +| `kind`, `version` | yes | `informed-decision.decision-outcome`, `1` | +| `hub_decision_id` | yes | from the memo's `serves`; must equal the route's id | +| `memo_id`, `memo_revision` | yes | the revision that was shown | +| `verb` | yes | `accept` or `decline` (terminal only; other verbs do not resolve) | +| `option` | C1 with options | the chosen option id | +| `subject` | yes | authenticated human subject: issuer + `sub` from the KeyCape session, not a display name | +| `assurance` | yes | `acr`/aal and authentication time of the deciding session | +| `decided_at` | yes | RFC 3339 UTC | +| `view_hash` | yes | `sha256:<64 hex>` of what was presented | +| `presentation_id` | yes | informed-decision presentation record | +| `approval_id`, `approval_entry_id` | C2 | the approval-engine object and the human entry | +| `audit_ref` | when available | audit-core record id | +| `display_name` | optional | used only to fill `decided_by` for display | +| `note` | optional | bounded human text (max 2 KiB), secret-scanned like memo content | + +Rules: no secrets, no tokens, no packet content; the record is bounded at 8 KiB as the existing +ledger already enforces. A decline resolves the decision with outcome `declined`; it is an answer. + +### 5.3 How the route authenticates (who may resolve with evidence) + +- `POST /decisions/{id}/resolve-evidence` requires a Kubernetes projected ServiceAccount token with + a dedicated audience (`state-hub-decision-writeback`), verified by the API through TokenReview. +- The verified subject must equal an allowlist of exactly one entry: + `system:serviceaccount:state-hub:state-hub` (the dispatch worker's identity, selected by the + founder in STATE-WP-0096). No other caller, no agent and no human browser session can use it. +- The route has two modes: `link` (records `memo_id`, and `approval_id` for C2, while the + decision stays open) and `resolve` (section 5.1 step 5). Both are idempotent on + `(decision_id, memo_id)`; a second resolve with the same memo returns 200, a different memo + returns 409 with the linked `memo_id`. +- `decided_by` is filled from `display_name` (or `subject`) for compatibility, but the authoritative + fields are `resolution_evidence.subject` and `assurance`. The hub records the human subject as + *attested by informed-decision through the authenticated worker*; it does not authenticate the + human itself. +- This is an enforced route, distinct from STATE-WP-0100's claimed, observe-only attribution of + ordinary writes. When STATE-WP-0100 phase 3 lands, the same token verification can be shared. + +Prerequisites outside this repository: TokenReview needs the API's ServiceAccount bound to +`system:auth-delegator` (cluster RBAC, railiance-cluster); the worker needs a second projected +token audience and NetworkPolicy egress to the hub API Service; the API's ingress policy must admit +the worker. If TokenReview RBAC is refused, the alternative is verifying the token signature +against the cluster's service-account issuer JWKS. + +## 6. Migration and backward compatibility + +- One additive Alembic migration: nullable columns, `evidence_refs` defaulting to `[]`, the CHECK + constraints and the partial unique index. Existing rows get `decision_class = NULL` and behave as + C0; no backfill, no reclassification of past decisions. +- `DecisionRead` gains optional fields; existing clients (MCP, dashboard, `statehub`, consistency + checks, recently-on-scope) keep working. `DecisionResolve` is unchanged for C0. +- New refusals apply only to decisions explicitly classed C1 or C2. Agents that resolve C0/legacy + decisions by text see no change. +- `memo_forwarding` resolution ledger: the text payload (`decided_by` + `rationale` search) is + replaced by the outcome record and the `memo_id` column. Its tests are rewritten accordingly. + The rationale-text correlation is retained only for reading pre-migration rows. +- Rollout order: schema and refusals first (inert until a decision is classed); then the route + with its token check; then worker pull and write-back; then classing the first real decisions. + Rollback leaves the columns and stored evidence in place. +- Event envelope `org.statehub.decision.resolved` gains `decision_class`, `memo_id`, `approval_id`, + `resolution_source`; existing attributes are kept. +- For retirement: the column set and the outcome record are the portable contract; hub-core's + decisions owner should adopt them unchanged. + +## 7. What is not changed + +- No public enqueue route and no automatic scanning of decisions: posing a memo for a decision + remains an explicit act, as in STATE-WP-0096. +- The hub does not create, read or consume approvals and gains no approval-engine scopes. +- The hub does not decide class doctrine (gate-house, S5) or present anything (informed-decision). + +## 8. Founder decisions needed + +1. **Pull or push:** the dispatch worker pulls outcomes (recommended) or informed-decision pushes + to the hub with its own workload identity. +2. **First enforced hub route:** admit TokenReview-based enforcement on this one route, ahead of + STATE-WP-0100's observe-only phase 3, including the `system:auth-delegator` binding. +3. **Class floor before S5:** whether the existing financial/legal keyword escalation should set + C1 as a minimum, or classes stay purely declared until gate-house doctrine exists. +4. **Retirement disposition:** confirm the decisions capability is "keep, move to hub-core" so this + work is not stranded. + +## 9. Asks of other owners + +- **informed-decision:** an outcome read for a submitter's own memos returning the record in + section 5.2; treat `serves.hub_decision_id` as the correlation key; keep `resolves: on-answer` + semantics (accept/decline only). +- **approval-engine:** none for S3. The hub only stores `approval_id`. +- **gate-house:** S5 class doctrine, including who may raise a class. +- **net-kingdom / railiance-cluster:** RBAC and NetworkPolicy prerequisites in section 5.3. diff --git a/workplans/STATE-WP-0101-decision-evidence-links.md b/workplans/STATE-WP-0101-decision-evidence-links.md new file mode 100644 index 0000000..c6d7e9e --- /dev/null +++ b/workplans/STATE-WP-0101-decision-evidence-links.md @@ -0,0 +1,87 @@ +--- +id: STATE-WP-0101 +type: workplan +title: "Decision classes, evidence links and informed-decision write-back (S3)" +domain: infotech +repo: state-hub +status: proposed +owner: claude-code +topic_slug: infotech +created: "2026-10-31" +updated: "2026-10-31" +flavor: implementation +related: [STATE-WP-0096, STATE-WP-0100, NK-WP-0056] +--- + +Proposed from hub message 59390db6 (net-kingdom, decision services alignment, S3). Design and +owner answer: `docs/decision-services-alignment-answer.md`. Hub decisions become the index of open +questions; C1/C2 decisions are resolved only by informed-decision evidence carried by the private +memo dispatch worker; C0 and legacy decisions stay as today. Nothing executes on hub decision +status. Kept small and portable because State Hub is in retirement. + +## Founder decisions on the design + +```task +id: STATE-WP-0101-T01 +status: wait +priority: high +``` + +Waiting on the founder: the four questions in section 8 of the design (pull vs push, first +enforced route with TokenReview, class floor before gate-house S5, retirement disposition of the +decisions capability). Record the answers in the design document. + +## Schema, read model and text-resolution refusals + +```task +id: STATE-WP-0101-T02 +status: wait +priority: high +``` + +Prerequisite: T01. Additive Alembic migration (`decision_class`, `memo_id`, `approval_id`, +`resolution_source`, `resolution_evidence`, `evidence_refs`, CHECK constraints, partial unique +index on `memo_id`). Optional fields on `DecisionRead`; typed `evidence_refs` validation. Refuse +text resolution, resolving PATCH fields, class lowering and resolved creation for C1/C2 with 409 +`evidence_required`. Tests for C0/legacy unchanged behaviour and every refusal in section 4. + +## Authenticated evidence route + +```task +id: STATE-WP-0101-T03 +status: wait +priority: high +``` + +Prerequisite: T02 and the RBAC decision in T01. `POST /decisions/{id}/resolve-evidence` with +`link` and `resolve` modes, projected-token verification (audience +`state-hub-decision-writeback`, exact subject allowlist), outcome record validation per section +5.2, idempotency on `(decision_id, memo_id)`, progress event and enriched resolved event. Tests use +a fake token reviewer; no live token. + +## Dispatch worker: outcome pull and write-back + +```task +id: STATE-WP-0101-T04 +status: wait +priority: high +``` + +Prerequisite: T03 and informed-decision's outcome read (owner: informed-decision). Replace the +free-text resolution payload in `memo_forwarding` with the outcome record and `memo_id` +correlation; link at enqueue; pull outcomes for the worker's own memos; keep retry and conflict +ledger. Rewrite `tests/test_memo_forwarding.py` resolution cases. + +## Deployment candidate and first classed decision + +```task +id: STATE-WP-0101-T05 +status: wait +priority: medium +``` + +Prerequisite: T04 and cluster prerequisites (auth-delegator binding, second projected audience, +NetworkPolicy egress worker to API and API ingress from worker). Server dry-run of changed +objects; live rollout is a separate founder-approved change. Acceptance: one real C1 decision +resolved by founder answer in informed-decision with stored evidence, and a text resolve of it +refused.