# Architecture Blueprint — Stage 1 **Repo:** informed-decision **Workplan task:** `INFD-WP-0001-T05` **Status:** draft, pending review **Governing ruling:** `GH-DEC-2026-012` (answered `INFD-IN-0001`) **Declarations:** `layer.yaml`, `pep-stance.yaml` **Companions:** `ProductRequirementsDocument.md`, `UseCaseCatalog.md`, `EvidenceModel.md` --- ## 1. What this component is **PEP-shaped**, ruled by `GH-DEC-2026-012`. Browser-facing; causes a protected side effect on the far side of a decision (an approver entry recorded against an approval object). Companion §5 owed, statute §6.4 in full. Not an Engine: it holds no state another layer reads at runtime for a verdict. It also emits a **presentation claim** — one fact, *what was shown* — under the three limits in `layer.yaml`. No second catalog row. **Nothing in this component renders an authorization decision.** No route answers "may this actor do X". --- ## 2. Call graph ``` browser (approver) │ ┌───────────┴────────────┐ │ informed-decision │ PEP-shaped │ (this repository) │ └──┬────┬────┬────────┬──┘ auth-code + PKCE │ │ │ │ presentation records, │ │ │ │ dispositions, stance ▼ │ │ ▼ applications key-cape │ │ audit-core ◄──── independent (identity)│ │ evidence path │ │ (limit L3) ▼ ▼ access-engine approval-engine (decision — (read + entry; consumed, never /consume) never made) ``` ### 2.1 `key-cape` — identity Authorization-code + **S256 PKCE**, public client, exact registered redirect. Access token only; `id_token` is never evidence. Scopes `[openid, approval:read, approval:approve]`. **Never `approval:consume`.** Token must carry `aud=approval-engine`, `principal_type: human`, non-empty `sub` and `scope`, and an `assurance` object. **`assurance` shape is `key-cape`'s**, adopted as published in their `docs/approval-engine-auth-contract.md` — `level` (`aal1|aal2`), `methods`, `mfa`, `source`, `at`. This blueprint **cites** that document rather than restating the shape, so it cannot drift. `at` is authentication time, not token mint time; consumers needing freshness compare `at` rather than assuming it. **Resolved.** `key-cape` implemented registration-bound tenancy on 2026-09-09 (`329e48f`), deliberately correct under both candidate rulings: a declared zone applies where the directory places the user nowhere, agreement passes, and a declared zone **conflicting** with a directory assignment refuses issuance with `403 tenant_binding` rather than relabelling. `GH-DEC-2026-013` then ruled directory-sourced the terminal state and granted the registration-bound shape as a **declared bounded gap** — admissible precisely because its distinguishing case fails closed. **Build to it knowing it is transitional.** Two obligations land here: - **Do not declare a tenant the directory record does not carry** unless prepared to say so in the record. Declaring one asserts a fact about a person on this registration's authority, which the ruling permits only as a gap. - **Record the tenant claim's provenance.** `key-cape` emits `tenant` as a bare string, so a consumer cannot distinguish a directory-asserted tenant from a registration-supplied one. `GH-DEC-2026-013` §5 requires the claim to carry provenance; until it does, this surface records which route the value arrived by rather than storing an undifferentiated string. **And do not use the `tenant` claim as the act-scope.** `binding.target` is the act-scope and is committed in `view_hash`. See `EvidenceModel.md` §8c. ### 2.2 `access-engine` — the decision, consumed A decision is obtained **before an approval is rendered to a person**. A `200` from `approval-engine` is not entitlement; that engine never answers "may this actor do X". Consuming a decision is not rendering one. There is no local fallback: if `access-engine` is unreachable, the stance applies (§5). **Declared gap, `GH-DEC-2026-010`.** Obligation 1 requires the decision be *attributable* to `access-engine`. No consumer can satisfy that today — the envelope is unsigned (`FLEX-WP-0024`). This surface records `decision_attributable: false`. **The decision path is not validated and must not be described as such** while that is open. ### 2.3 `approval-engine` — the object and the entry | Route | Method | Scope | | --- | --- | --- | | `/v1/approvals/{id}` | GET | `approval:read` | | `/v1/approvals/{id}/claim` | GET | `approval:read` | | `/v1/approvals/{id}/entries` | POST | `approval:approve` | | `/v1/approvals/{id}/consume` | POST | **never called** | Paths containing `check` or ending in `/authorize` return 404 by design; there is nothing there to call. `POST /entries` **discards its request body** — approver identity, `assurance` and `evidence_ref` come only from the verified token. So `view_hash` does not ride into the entry. Correlation is `(approval_id, subject, approved_at)`. **No inbox.** Get-by-id only; no list, no search, no "awaiting me". Approval ids arrive from whatever requested the approval. This component must never poll. Only `accept` becomes a `POST …/entries`. `return`, `discuss`, `escalate` and the rest are memo-level and are not represented in that engine at all. ### 2.4 `audit-core` — evidence, on an independent path **Limit L3 is the architectural constraint of this design.** The evidence copy must reach `audit-core` independently of this repository, because here the actor being audited and the evidence source are the same component. The copy that is evidence must not be reachable only through the party it is evidence about. Consequences, binding on implementation: 1. **The claim endpoint and the evidence path are separate.** Serving a presentation record over this component's API does not discharge the evidence obligation, and emitting evidence does not remove the need for a claim. 2. **A reader must be able to obtain the evidence copy without this component's cooperation.** If the only route to a presentation record is an API this component controls, an adversary who controls it controls the evidence about it. 3. **Emission is not best-effort.** A presentation or disposition that can be recorded here while its evidence is lost is a state change that never happened as far as an auditor can tell. `approval-engine`'s local-outbox reasoning applies unchanged and is adopted rather than rediscovered: the queue is local, in the same transaction as the state change, with no synchronous `audit-core` dependency inside it. 4. **Atomicity covers accident, not compromise.** It does not close the residual in `layer.yaml`, and must never be described as doing so. **Cadence is owed**, because `layer.yaml` declares presentation evidence load-bearing (§9.6). The form differs from `approval-engine`'s: their classes are genuinely low-volume, so a heartbeat is the answer. Ours are mixed — presentations are high-volume (one per render), while dispositions and stance applications are low-volume and are the security-relevant ones. Proposed: reconciliation per class as the primary form, plus a heartbeat for the low-volume classes, since a quiet month of dispositions is indistinguishable from suppression by rate alone. Depends on `AUDIT-WP-0009` T04/T06; declared, not claimed operating. What travels is the open question — see `docs/evidence-path-design.md` and O-02. **T08 must not ship without it chosen**, because "we will add the independent path later" is how limit 3 quietly becomes limit 3-in-principle. --- ## 3. Internal shape ``` informed_decision/ ├── canonicalize.py view_hash / awareness_hash (governed, tested) ├── stance.py the shipped unreachable-engine map (tested == published) ├── memo/ Decision Memo object, versions, lifecycle ├── presentation/ presentation records; the only writer of view_hash ├── disposition/ verb legality, guards G_*, thread ├── evidence/ local outbox, bundle export └── clients/ key-cape, access-engine, approval-engine, audit-core ``` **`presentation/` is the only writer of `view_hash`.** One writer, one canonicalizer, one place to audit. A second path that computes a hash is a defect, not an optimisation. **`clients/approval_engine` must not expose a validity cache.** No memoisation of "is this approval valid". The engine is asked. --- ## 4. Storage Stage 1 holds: memos and their versions; presentations with both hashes and acked highlight ids; dispositions with their coded reasons; thread entries; the local outbox; stance applications. Properties required: - **Presentations are append-only.** A presentation is a record of an event that happened. Editing one is falsifying evidence. - **Memo versions are immutable once presented.** A change creates version *n+1* and invalidates outstanding presentations (guard `G_PRES`). - **The outbox is in the same transactional store**, written in the same transaction as the state change it evidences. - **No approval state.** Not cached, not mirrored, not derived. Engine choice is deferred to implementation; the constraint is that it be a single transactional store, so the outbox cannot separate from the mutation. --- ## 5. Failure modes — stance per dependency Default is **fail closed**. Every stance in `pep-stance.yaml` is `fail_closed`, and that is a conclusion: refusing to bind delays a decision, it does not remove a capability anyone needs to keep a system running. There is no continuity argument here of the kind that justifies `fail_open` elsewhere. | Dependency | Unavailable | Surface behaviour | | --- | --- | --- | | `key-cape` | no authentication | No session. Nothing rendered. | | `access-engine` | no decision | **Stance applies: `fail_closed`.** Not rendered, not bound. Recorded as a stance application, never as a decline. | | `approval-engine` 5xx / `503` | no object, or store down | Fail closed. Never present success. | | `audit-core` | evidence destination down | Rendering and binding continue; evidence queues in the **local** outbox. An `audit-core` outage must not block a binding act — the same reasoning that keeps it from blocking a revocation upstream. | **A fail-closed outcome is never rendered as a decline by the approver.** No disposition is recorded, because the human did not make one. Conflating the two would put a refusal in the record that no person authored. Engine response mapping — `409 duplicate_approver` is **success**, `409 conflict` is terminal, `503` is fail-closed — is specified in `PR-06` and is not restated here. --- ## 6. Deployment `approval-engine` has no Ingress and no external origin, which is why it could not own the browser client. **This component has both, and that is the point.** - Public HTTPS origin, TLS terminated at ingress. - Exact registered redirect URI, scheme and path included. Redirects match exactly at `/authorize`, so a near-miss fails closed. - **`client_id` and the callback URI are deployment inputs, not implementation details.** Once chosen they are stable; changing one silently breaks login rather than degrading it. - Outbound to `approval-engine` and `access-engine` on cluster-internal addresses; no public exposure of either is implied by this component's. The concrete origin is fixed in `T07` alongside the client registration, and is gated on the tenant question in §7. --- ## 7. Open and blocking **~~O-01 — Human token tenant.~~ Closed 2026-09-10** by `GH-DEC-2026-013` and `key-cape` `329e48f`. Our binding-versus-awareness argument was accepted and written into the ruling as its §6 — and it did not change the outcome, it sharpened the defect: two different facts (act-scope, and the principal's membership) were sharing one field. The condition we asked for is now in `key-cape`'s `docs/tenant-claim-contract.md`, strengthened from "must be revisited" to **void** if the dynamic-registration exclusion is lifted, and enforced by a test asserting the capability and the exclusion together. See §2.1 for the two obligations that land on us. **O-02 — The independent evidence path.** *Payload ruled: commitment-only granted for Stage 1 by `GH-DEC-2026-014`, on the condition that the record carry an assertion that content exists and where custody sits, so non-production is a finding attributable to us rather than an unremarkable blank. It satisfies non-alteration, not reconstructability, and must not be described otherwise. The registration and cadence remain with `audit-core`.* Design and decision request written: `docs/evidence-path-design.md`, filed as `INFD-IN-0003`. Read independence and the local transactional outbox are settled; the open question is **what travels**, because a presentation record carries the brief and packet material actually shown to a human. Proposal is commitment-only (hashes, principal, timestamps, acks, co-referenced approval id) for Stage 1, with the erasure residual declared rather than papered over. Awaiting `audit-core` on the payload and the sender registration, and `gate-house` only if the content question is doctrine. Must be resolved before T08 ships. **O-03 — Requester identity for an engine-originated memo.** `approval-engine` does not model a requester. Likely the approval's `principal`; needs confirming against the object. **O-04 — `abstain`.** In the state tables and real in Mitzeichnung practice, but with no obvious `approval-engine` counterpart. Stage 1 scope undecided. --- ## 8. What would make this architecture wrong - A route that answers whether an act is permitted. - A validity cache for approvals. - A second writer of `view_hash`. - An evidence path reachable only through this component. - `view_hash` nested inside, or recomputed from, `approval-engine`'s binding digest — co-reference only (`GH-DEC-2026-012` R3). - A polling loop against `approval-engine` synthesising an inbox. - A fail-closed outcome recorded as an approver's decline. - Describing the decision path as validated while `GH-DEC-2026-010` is open. - Describing commitment-only evidence as reconstructability (`GH-DEC-2026-014`). - Using the token's `tenant` claim as the act-scope, or storing it without its provenance (`GH-DEC-2026-013` §5).