# 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 <id> `. 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.<decision_id>.<memo_id>`. 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.