informed-decision/docs/specs/UseCaseCatalog.md

Use Case Catalog

Repo: informed-decision Workplan task: INFD-WP-0001-T04 Status: draft, pending review Companion specs: ProductRequirementsDocument.md (Stage 1 scope), ArchitectureBlueprint.md, EvidenceModel.md

---

Why this catalog exists

Scale invariance is the thesis of this repository: one object model from a ten-second login to a multi-party instrument. A thesis stated in a vision document is decoration. This catalog exists to make it testable — every case below must map onto the single Decision Memo schema with no level-specific object.

Only UC-30 is in Stage 1 build scope. The rest are here to constrain the schema now, so it cannot fork later when they arrive.

The test this catalog applies to every case: can it be expressed with the fields in decision-memo.schema.json plus values, or does it need a new field? A new field is permitted only if it is also expressible for UC-00 — the login banner, the shallowest case. A field that only makes sense at L4 is a fork.

---

Depth spectrum overview

Case	L	Act	Binding	Counterparty	Stage
UC-00	L0	Informed login	acknowledgment / organizational	key-cape	2
UC-10	L1	JIT privilege elevation	organizational	key-cape, secrets-engine	2
UC-20	L2	Formal ADR accept	organizational / AES	estate decision records	2
UC-30	L3	Approval entry	organizational	approval-engine	1
UC-40	L4	Contract / instrument	AES / QES	external counterparty	horizon
UC-50	L5	Multi-party instrument	QES per party	multiple	horizon

---

UC-00 — Informed login (L0)

Actor: any principal signing in. Trigger: authentication at a system boundary. Question: "Sign in to Payroll-Prod as Bernd Worsch?" Requested act: login.

Binding slice (signed): which identity (ordinary vs break-glass), which scope/tenant/system, privileges granted at the gate, monitoring and consent terms.

Awareness slice (shown, hashed, not signed): the role you will wear after login and where that default came from (last_used | system_default | policy | explicit); other roles available inside the bound scope; other tenants you support; last session summary.

Verbs: acknowledge (completes), decline, discuss. Not accept — this is Kenntnisnahme.

Post-bind: configure(hat) for non-elevating roles only, while session.status = active. Switching to a tenant with requires_new_bind opens a child memo, never a silent scope change.

Evidence: presentation with both hashes; session.hat_selected events that do not rewrite view_hash.

Why it constrains the schema: UC-00 is the shallowest case and therefore the strictest constraint. It forced the pre-sign/post-sign split that now applies at every level — see INTENT.md principle 11. Any field proposed for a deeper case must be expressible here or be justified as genuinely level-specific.

---

UC-10 — JIT privilege elevation (L1)

Actor: an operator needing elevated privilege for a bounded task. Question: "Elevate to Payroll Admin on ACME/Payroll-Prod for 60 minutes?" Requested act: elevate.

Binding slice: the privilege, the scope, the validity window, the stated justification, the monitoring terms. Awareness slice: current role, what the elevation adds, prior elevations.

Verbs: acknowledge or accept depending on whether the elevation is self-service-with-record or requires a co-signer; decline; escalate where the operator's own mandate is insufficient.

Counterparty: key-cape for identity; secrets-engine if the elevation materialises credentials — which this repository never does itself.

Constraint contributed: an elevating role can never be reached by configure. It requires either promotion into the binding slice with a new memo version, or its own elevation memo. Guard G_HAT.

---

UC-20 — Formal ADR accept (L2)

Actor: an architect or owner with the mandate to accept a decision record. Question: "Accept ADR-0042 — Adopt the local outbox pattern?" Requested act: accept_adr.

Binding slice: the ADR id and version, the decision statement, consequences, the accepting role. Packet: the ADR document, plus any superseded record. Highlights: the consequences section, typically required_ack: true.

Verbs: the full set. return with coded reasons is the common path and is the point — an ADR sent back for a clearer consequences section is the surface working.

Constraint contributed: "accepted" must stop being a Git status and become an identity act. The evidence must answer who accepted it, in what role, having seen which version. This is the case that most directly tests whether view_hash carries enough to be useful.

Note: the estate's own decision records (GH-DEC-*, FLEX-DEC-*, APPROVAL-*) are the natural first real consumer of UC-20. Stage 2.

---

UC-30 — Approval entry (L3) — Stage 1

Actor: a human approver holding the mandate, authenticated by key-cape. Trigger: an approval exists in approval-engine in state requested, awaiting an authenticated approval entry. Question: "Approve rotation of the production database credential for task T-1183?" Requested act: approve.

Binding slice: the approval id; the action and target it authorizes; the actor who may use it and the principal on whose behalf; the purpose; the validity window; the approving identity and tenant.

Awareness slice: the approver's current role; other approvals pending for them (orientation only — see PRD open question 1); prior related approvals.

Packet: the change or task the approval is for, and any policy citation supplied by the requester. Highlights: the target and the validity window, typically required_ack: true — these are the two fields whose misreading is most costly.

Verbs: accept (submits the approval entry), decline, return with coded reasons, discuss, forward, escalate, comment.

Only accept reaches the engine. approval-engine models entries against an approval object and knows nothing of memo dispositions. accept becomes a POST /v1/approvals/{id}/entries; return, discuss, escalate and the rest are memo-level and must not be represented in that engine at all. This is the correct separation, and it means the approval object alone does not show that a human sent the question back — see EvidenceModel.md §8 and PRD L-06.

Routes used: GET /v1/approvals/{id} and GET /v1/approvals/{id}/claim (scope approval:read), POST /v1/approvals/{id}/entries (scope approval:approve). Never /consume. Any path containing check or ending in /authorize returns 404 by design — there is no "may this person approve" surface to call.

Entitlement: a 200 from the engine is not a statement that this human may see the approval. access-engine is asked before rendering (PR-05).

No inbox. The engine exposes get-by-id only — no list, no search, no "awaiting me". Approval ids arrive from whatever requested the approval.

Boundary — the part that must not drift:

• The surface calls approval-engine's approval-entry mutation with a token carrying scope approval:approve. It never mutates approval state itself.
• It never requests or performs approval:consume. Consumption is the PEP's, at the moment of use, per GH-DEC-2026-003.
• It never caches or serves approval validity.
• It never answers whether the underlying action is permitted. That is access-engine.

Evidence: presentation record with view_hash, the disposition, and the approval entry id returned by approval-engine, so the entry is reconstructable back to what the approver saw.

Why this is Stage 1: it is the only case currently costing another repository progress. key-cape's KEY-WP-0013-T02 is blocked on a browser client for exactly this flow.

---

UC-40 — Contract or instrument (L4) — horizon

Actor: a signatory with commercial authority. Binding: AES or QES. Identity imported from a QTSP or EUDI Wallet, never issued here. Constraint contributed: the signed attributes carry memo_id, memo_version, disposition.verb and presentation.view_hash — and not awareness_hash unless promotion ran. This is dynamic linking: the human-readable content actually presented is bound into the signature.

Open, not scoped: retention and qualified archive (exploration open question 6).

---

UC-50 — Multi-party international instrument (L5) — horizon

Actors: several parties, each with their own QTSP and jurisdiction. Constraint contributed: parallel Mitzeichnung, per-party signature levels, and per-party presentations of the same memo version. The schema must already tolerate parties[] and multiple presentations per version — which it does.

Explicitly not v1, and named here only so nothing shipped earlier forecloses it.

---

Negative cases

These are as load-bearing as the positive ones. Each protects a named invariant and each must be a test.

NC-01 — accept on a Kenntnisnahme step

Attempt: the approver presses accept on an inform/review/acknowledge step. Required behaviour: the verb is absent from the UI, not present and disabled; an API call attempting it is refused. Invariant protected: Kenntnisnahme is not approval. Collapsing them is how "I saw it" silently becomes "I approved it". state-transitions.md §B2 · PR-31

NC-02 — Bind with unacknowledged required highlights

Attempt: accept while a required_ack highlight is unacked. Required behaviour: fail closed; no disposition created; error names the outstanding highlight ids. Invariant protected: the acknowledgment gate is the only positive evidence of informedness the model has. guard G_ACK · DoD-4 · PR-20

NC-03 — Agent attempts a disposition

Attempt: a principal with actor.kind = agent submits any binding verb. Required behaviour: refused at this repository's API, not merely hidden in the UI. Invariant protected: humans bind, agents draft. guard G_NOAGENT · P-10 · W-"An agent binds"

Corrected 2026-09-09. The first draft implied the refusal was also approval-engine's. It is not: that engine restricts only /consume by principal type, and its approval-engine-operator service client holds approval:approve, so a non-human principal can supply approver evidence there today. Whether it should is gate-house doctrine, not ours.

Two consequences. First, enforcement of P-10 is this surface's own obligation — there is no upstream backstop. Second, it is auditable: schema v4 records the verified entries[].principal_type from the token. Read that field. Never infer the answer from the shape of subject_id, which is a naming convention, not a verified claim; entries predating v4 are null and must not be read as human.

NC-04 — Tenant switch requiring a new bind

Attempt: after an L0/L1 bind, the subject selects a tenant marked requires_new_bind. Required behaviour: scope.rebind_required is set and a child memo is opened. The current session's view_hash is not rewritten. Invariant protected: scope is committed, not configured. guard G_HAT · isolation vector 4

NC-05 — Awareness field edited after presentation

Attempt: the proposed role or last-session summary changes between render and bind. Required behaviour: awareness_hash changes; view_hash does not; the bind remains valid. Invariant protected: the person is bound to what they committed to, not to orientation material. isolation vector 2 · PR-40

NC-06 — Binding target changed

Attempt: binding.target is altered from ACME to Beta. Required behaviour: view_hash changes, invalidating any outstanding presentation. Invariant protected: the binding slice is genuinely covered by the hash — the positive control for NC-05's negative one. isolation vector 3

NC-07 — Bind against a stale memo version

Attempt: a presentation taken at version n is used to bind after the memo advanced to n+1. Required behaviour: version conflict; no silent upgrade. Invariant protected: binding acts reference a presentation of the same version. guard G_PRES · PR-14

NC-08 — return with no coded reason

Attempt: return with free text only. Required behaviour: refused. Invariant protected: return is structured feedback, not a shrug. guard G_REASONS · PR-32

NC-09 — escalate to an equal or lower mandate

Attempt: escalate to a target whose mandate is not strictly higher. Required behaviour: refused as an escalation; offered as forward. Stage 1 caveat: without the mandate graph this guard cannot be fully evaluated. Stage 1 records the asserted intent and marks it unverified rather than pretending the guard passed. guard G_ESC · limitation L-01

NC-10 — Key shuffling

Attempt: serialise the same binding document with object keys in a different order. Required behaviour: identical view_hash. Invariant protected: canonicalization is real; otherwise every hash is an artifact of serialisation order. isolation vector 1

---

Schema pressure — cases that would fork the object

Recorded so a future contributor recognises them as forks rather than features:

• A level-specific status. e.g. awaiting_notarisation for L4. Belongs as a step kind or a route step, never a new memo status.
• Multiple questions per memo. An approval bundling three unrelated acts is three memos. The single-question invariant is what makes view_hash mean something.
• A per-level packet model. L4 attachments are packet items, hashed exactly like an L0 consent text.
• An approvals-inbox object. A list of memos is a query result, not a schema entity. If it acquires state, the product has become a queue.