informed-decision/docs/specs/ArchitectureBlueprint.md

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).