informed-decision/docs/specs/EvidenceModel.md

Evidence Model

Repo: informed-decision Workplan task: INFD-WP-0001-T06 Status: draft, pending review Companions: ProductRequirementsDocument.md, UseCaseCatalog.md, ArchitectureBlueprint.md (gated on INFD-WP-0001-T02) Normative algorithm: history/20260909-initial-exploration/canonicalize.md Governed implementation: informed_decision/canonicalize.py Tests: tests/test_canonicalize.py

---

1. What this model claims

This person, in this role, was shown this view, and bound this act.

Not "the file was signed". The difference is the whole product. A signature over a document proves a key was used on some bytes; it does not establish what the signer was looking at when they decided, which is the question an auditor actually asks and the question no e-signature product answers.

The mechanism is dynamic linking: the human-readable content actually presented is canonicalized and its digest is bound into the act.

2. What this model does not claim

Stated first, because an evidence model that oversells is worse than none.

E-01 — It does not prove the person understood. It proves what was presented and what was explicitly acknowledged. Comprehension is not observable and this model does not pretend to observe it.

E-02 — It does not prove the person read anything. Deliberately. Evidence of informedness is the hash of the presented view plus explicit acknowledgment — never dwell time, scroll depth, or attention telemetry. That choice trades a weaker claim for the absence of surveillance, and the trade is intentional (INTENT.md principle 12, PR-70/PR-71).

E-03 — It does not survive a compromised surface. view_hash is computed by the same component that renders. A compromised surface can present X and attest Y. This is structurally the same residual approval-engine names for adversarial omission at a compromised source, and it is not closed here, not closable at this layer, and never to be described as closed.

E-04 — A hash chain proves records were not altered or truncated after arrival. It cannot prove a record was never sent. Carried over from approval-engine's reasoning rather than rediscovered: a suppressed event leaves the chain perfectly intact and verification reports intact. Completeness is a separate obligation met by cadence, not by chaining.

E-05 — Stage 1 binding is organizational only. No AES, no QES. The object carries binding_level so higher levels are expressible without a schema change; nothing above organizational is implemented or claimed.

E-06 — A Stage 1 escalation is an assertion, not a verified claim. Without the mandate graph, guard G_ESC cannot be fully evaluated. The bundle records what the approver asserted and marks it unverified.

3. The two hashes

	view_hash	awareness_hash
Over	the binding document	the awareness document
Signed	yes, from organizational level up	no
Purpose	what the person committed to	what they were oriented with
In AES/QES signed attributes	yes	no, unless promotion ran

Binding allow-list: memo_id, memo_version, question, requested_act, binding_level, brief, locale, ui_release, normalized packet, normalized highlights, binding, and optionally awareness_promoted.

Awareness allow-list: proposed hat and its source, available hats and scopes, last session, situation note.

Profile: JCS-inspired restricted JSON — UTF-8, keys sorted by code unit, no insignificant whitespace, integers only, unknown keys stripped, nulls dropped.

canonical = dumps(document)
hash      = SHA-256(UTF-8(canonical))

Why the split exists

The login case forced it and it now applies everywhere. Defaulting a role to last-used is required for situational awareness — an operator who cannot see which hat they are about to wear is less safe, not more — and is forbidden from silently entering the signed payload. A person must not be bound to orientation material they did not commit to.

Promotion is the only bridge: moving a field from awareness into binding creates a new memo version, invalidates outstanding presentations, and copies the named fields into awareness_promoted where view_hash covers them (guard G_PROMOTE).

4. The four isolation properties

These are the model. Each is a test in tests/test_canonicalize.py and each must stay green; a failure means view_hash no longer means what §1 claims.

#	Property	Protects	Test
1	Shuffling object keys does not change either hash	Any verifier, in any language, agrees with us	test_key_order_does_not_change_*
2	Editing an awareness field does not change view_hash	The person is bound only to what they committed to	test_editing_awareness_does_not_change_view_hash
3	Changing binding.target does change view_hash	Positive control — without it, 2 could pass vacuously	test_changing_binding_target_changes_view_hash
4	Selecting a hat after login does not rewrite view_hash	Post-bind session state is a different object	test_post_bind_hat_selection_does_not_change_view_hash

Property 3 is not decorative. Properties 1, 2 and 4 are all negative — they assert that things do not change the hash. A canonicalizer that returned a constant would pass all three. Property 3, plus the per-field variants over question, requested_act, binding_level and packet, is what makes the suite meaningful.

Published vectors reproduce byte for byte and are asserted in CI:

login       view_hash       492d9d31…1b06b8
login       awareness_hash  2be77429…4fe05d1
ADR-0042    view_hash       1c89ec07…e91f202

Provenance is tested. history/20260909-initial-exploration/ is never edited. test_governed_vectors_match_the_preserved_history_copy asserts the governed fixtures have not drifted from the founding copies, so a silent edit to a vector to make a failing test pass is itself a test failure.

5. The presentation record

Every render creates one. It carries:

• memo_id, memo_version
• principal — who it was shown to
• locale, ui_release — both inside view_hash
• rendered_at
• acked_highlight_ids
• view_hash, awareness_hash
• phase — pre_bind | bind | post_bind

A disposition references exactly one presentation, of the same memo version (guard G_PRES). A presentation taken at version n cannot bind after the memo advances to n+1 — no silent upgrade (NC-07).

Because locale is inside view_hash, the same memo read in German and in English produces two different presentations of one binding. Intended, and documented rather than smoothed over (PR-61).

6. The evidence bundle

An export, not a screenshot (INTENT.md principle 7). Contains the memo and all its versions, every presentation with both hashes, every disposition, the thread, the route as executed, and the append-only hash chain.

Requirements:

• Verifies offline. No network, no access to this service. A verifier recomputes view_hash from the bundle's own binding document and compares.
• Detects mutation. Altering any covered field breaks verification.
• States its own bound. The residuals in §2 travel with the bundle as metadata. An auditor must not have to read this document to learn that E-03 exists.
• Marks unverified assertions as such — see E-06.

7. Relationship to audit-core

audit-core holds the archive; this repository holds the operative record and produces the export. This surface emits its transitions there and does not duplicate the archive's role.

Its guarantee is bounded and the bound is inherited, not re-litigated: audit-core is not WORM or object-locked, its tamper evidence is conditional on live preconditions, and stronger custody was decided against in statute §16. This repository must not plan around a stronger archive, and must not imply the bundle is more durable than the archive it reconciles against.

8. Open — view_hash versus the approval binding digest

Unresolved. Filed as INFD-IN-0001 R3 with gate-house.

approval-engine's claim carries "a digest over the same canonical binding the decision point already computes." view_hash is also a digest over "the binding". They cover different material: the approval digest exists with no human in the loop; view_hash additionally covers brief, packet, highlights, locale and UI release.

Until ruled, this repository computes view_hash and asserts no relationship between the two. Three candidate outcomes and their costs are set out in docs/gate-house-decision-request-layer-placement.md §2 R3. The outcome to be avoided is both digests shipping with no stated authority rule, leaving the estate with two canonicalizations of one act.

8b. Where view_hash actually lives (Stage 1)

It is not in the approval entry, by the engine's deliberate design.

POST /v1/approvals/{id}/entries reads the request body and discards it. Approver identity, assurance and evidence_ref come only from the verified token (evidence_ref is jwt-sha256:<digest of the presented token>). The reasoning is sound and we adopt it rather than argue it: a caller-supplied approver field is provenance, not evidence, and that entry is currently the one record containing no caller-supplied data.

Stage 1 arrangement, requiring no change to approval-engine:

1. this repository holds the presentation record and computes both hashes;
2. it emits that record to audit-core as its own evidence;
3. correlation to the approval entry is by (approval_id, subject, approved_at) — all three returned by the engine after a successful entry.

Consequence for an auditor, stated plainly: someone holding only the approval object cannot reach the presentation. They need this surface's record or audit-core as well. GOAL.md DoD-3 — "the approval entry is reconstructable from a view_hash" — is satisfied by the correlation triple, not by a hash stored on the entry.

Putting the binding inside the approval object would be a real change request against approval-engine (an optional, verified-alongside-token view_hash on the entry) and it is doctrine before it is a change request, so it goes to gate-house first. Not raised at Stage 1; recorded here so the option is not lost.

assurance is the only carrier of authentication facts

approval-engine persists the token's assurance claim verbatim and interprets nothing — an empty {} is accepted and evidences nothing. It is therefore the single place where "this was bound under MFA" survives into the approval record. The shape must carry authentication method, acr/amr and auth_time at minimum, and informed-decision and key-cape own it between them. Nothing downstream reconstructs it.

Principal type is verified evidence; subject_id is not

Schema v4 records entries[].principal_type from the verified token. Design principle 10 (humans bind, agents draft) is enforceable from the evidence chain by reading that field. Never infer it from the shape of subject_id — a naming convention is not a verified claim. Entries written before v4 are null and must not be read as human.

9. Signed attributes (L4+, horizon)

When AES/QES arrives, the signed attributes carry memo_id, memo_version, disposition.verb and presentation.view_hash. They do not carry awareness_hash unless promotion ran. Recorded here so nothing built at Stage 1 forecloses it.