informed-decision/SCOPE.md

# SCOPE

> Implemented-and-first-cut boundary for agents and contributors. Aspirational
> direction belongs in `INTENT.md`; the current stage belongs in `GOAL.md`;
> current work and gates belong in `workplans/`.

## Status — 2026-09-10

**The domain core, browser sign-in shell, Approval Engine HTTP adapter,
durable evidence store and Audit Core delivery adapter are implemented. The approval surface is not deployed.**

What exists and is tested (258 tests, including explicit checks against the
actual Approval Engine and Audit Core implementations with synthetic identities):

- layer and stance declarations — `layer.yaml`, `pep-stance.yaml`,
  `informed_decision/stance.py`, with published-equals-shipped asserted;
- the governed canonicalizer and schema, with the three published vectors
  reproducing byte for byte and all four isolation properties pinned;
- the **domain core**: `memo.py` (the Decision Memo, its versions and the
  binding document), `presentation.py` (the sole writer of `view_hash`),
  `disposition.py` (the verb vocabulary and guards `G_NOAGENT`, `G_STEP`,
  `G_PRES`, `G_ACTOR`, `G_ACK`, `G_REASONS`, `G_SEALED`), `provenance.py` (claim routes,
  A-16), `evidence.py` (the local outbox and commitment records);
- `approval_client.py` — the seam to `approval-engine` plus a fake;
- `oidc.py` and `web.py` — public-client PKCE sign-in, verified human/MFA
  profile, bounded server-side sessions, protected cookies and CSRF sign-out;
- `approval_http.py` and `http_transport.py` — get-by-id and human-entry
  transport, declared-control checks, real entry correlation, no consume route
  or automatic mutation retry. This adapter has no public browser mutation route;
- `store.py` / `records.py` — private durable packet/memo/presentation/
  disposition storage, append-only acknowledgments, transactional outbox and
  submission correlation, safe reservation and backup/restore;
- `audit.py` — idempotent Audit Core delivery, bounded retry/blocked states,
  explicit per-class count/time-basis comparison. Heartbeats are generated
  without hiding undelivered evidence; host scheduling remains pending.

Remaining: admitted policy package/caller and entitlement-before-render
integration, L3 review/acknowledgment/binding UI, policy observation persistence,
visible unresolved-entry recovery, scheduled independent audit delivery and
native deployment/custody proof. The legacy `evidence.Outbox` remains an
in-memory test double; the new `Store` supplies durable atomicity. Browser
sessions are ephemeral, with no approval state.
`/readyz` returns 503 until the protected approval path is connected.
The origin `decisions.coulomb.social` still serves an nginx placeholder.
See [browser-authentication.md](docs/browser-authentication.md) and
[durable-review-evidence.md](docs/durable-review-evidence.md).

`INFD-WP-0001-T08` remains open for the live end-to-end proof, which is gated on
`APPROVAL-WP-0002-T01` and a deployed `approval-engine`.

## One-liner

informed-decision is the presentation and binding surface for decisions: it
renders a Decision Memo to the human who holds the mandate, records what was
shown, and binds their identity to the act — and owns the browser-facing
approver UI that `approval-engine` deliberately does not contain.

## Layer

**PEP-shaped**, ruled by `GH-DEC-2026-012`. Not an Engine. Companion §5 owed,
statute §6.4 in full. Declared in `layer.yaml` in this repository's own voice.

It emits one PIP-like fact — *what was presented* — as a claim, under three
limits that are the substance of the permission rather than caveats on it:

1. the claim carries presentation and nothing else, and must never carry,
   restate, summarise or imply a decision or verdict;
2. the claim must never be an input to the decision it presents for;
3. the evidence copy reaches `audit-core` **independently** of this repository.

Limit 2 is load-bearing: the argument that a renderer attesting its own
rendering is not self-dealing was accepted *because* that limit holds.

## Core Idea

A decision surface is not a workflow engine and not a decision point. This
repository owns the Decision Memo object, the presentation record, the
canonicalization producing `view_hash` / `awareness_hash`, the disposition
vocabulary, and the evidence bundle export. It does not evaluate whether an act
is permitted, does not hold approval current-state, and does not archive the
trail.

## In Scope — first cut (Stage 1)

**Built and tested:**

- Canonicalization of the binding and awareness documents, with the three
  published vectors reproducing byte for byte and all four isolation properties
  pinned (`tests/test_canonicalize.py`).
- The Decision Memo schema and worked examples, governed under `schemas/`.
- The unreachable-engine stance map, built to v0.8 obligation 3, with
  published-equals-shipped asserted by test (`tests/test_layer_conformance.py`).

**Built as domain operations with durable custody; protected HTTP integration remains:**

- The presentation record: what was rendered, to whom, when, in which locale and
  UI release.
- Required-highlight acknowledgment as a precondition of binding.
- The disposition vocabulary and its legality tables. Only `accept` reaches
  `approval-engine`; `return`, `discuss`, `escalate` and the rest are
  memo-level.
- The browser-facing OIDC client: authorization-code + S256 PKCE against
  `key-cape`, scopes `[openid, approval:read, approval:approve]`.

**Specified, not built:**

- An L3 approver surface calling `approval-engine`'s approval-entry mutation.
- The evidence bundle as an offline-verifiable export.

## Out of Scope

- Authorization decisions — `access-engine`, always and only (statute §6).
- The approval object, its state machine, validity and consumption —
  `approval-engine`. Never cached, never inferred, never `approval:consume`.
- Approval doctrine — `gate-house`.
- Identity and authentication — `key-cape`. Imported, never invented. The
  `assurance` shape is `key-cape`'s and is cited, not restated.
- The evidence archive — `audit-core`.
- Credentials materialized after a decision — `secrets-engine`.
- Notification transport, ticketing, general workflow.
- **An approvals inbox.** Foreclosed upstream as well as here:
  `approval-engine` exposes get-by-id only and will not add a list.
- L4/L5, QES, QTSP, qualified archival retention.
- The mandate graph — so a Stage 1 `escalate` is an assertion, not a verified
  claim.

## What this repository does not claim

Stated here because a scope file that only lists capabilities overstates them.

- **The decision path is not validated.** `GH-DEC-2026-010` requires a decision
  be attributable to `access-engine`; no consumer can satisfy that today because
  the envelope is unsigned (`FLEX-WP-0024`). This surface records
  `decision_attributable: false` and must not describe validation as complete.
- **The residual is open.** A compromised surface can present X and attest Y.
  `GH-DEC-2026-012` states it is not closed and does not credit this repository
  with closing it.
- **`view_hash` is not inside the approval entry.** `POST /entries` discards its
  body by design. Correlation is `(approval_id, subject, approved_at)`, so an
  auditor holding only the approval object cannot reach the presentation.
- **Commitment-only evidence is not reconstructability.** `GH-DEC-2026-014`
  granted it for Stage 1 and bounded it: it satisfies non-alteration, and moves
  integrity out of our control while leaving *availability* entirely inside it.
  The party that can withhold the content is the party the evidence is about.
  Narrowed by the required existence assertion; not closed.
- **The registration-bound tenant is a declared bounded gap**, not the terminal
  state. `GH-DEC-2026-013` ruled directory-sourced terminal and admitted
  `key-cape`'s shape because its distinguishing case fails closed. Build to it
  as transitional.
- **Nothing is deployed**, so nothing is observed in production and nothing is
  contained automatically.

## Open

- **Native browser registration and human proof** — T07 supplied the real
  origin and submitted the contract. T08 retains registration rollout and a real
  human login accepted by the deployed Approval Engine.
- **`audit-core` custody and live delivery** — source registration and cadence
  have owner returns (`AUDIT-IN-0003`, `AUDIT-WP-0009` T04/T06/T07); native
  credentials, independent receipt and reconciliation still require proof before
  T08 ships.

*Closed 2026-09-10:* the human token tenant (`GH-DEC-2026-013`, `key-cape`
`329e48f`) and the evidence payload question (`GH-DEC-2026-014`).