AUDIT-WP-0009-T03/T09 — evidence_kind, and approval-engine's registration inputs

T03. §9.6 gives load-bearing and attributive sources different obligations, so
the archive must record which one a source declared rather than infer it from
traffic. evidence_kind and completeness_trade now sit on SenderIdentity, the
AUDIT_CORE_SENDERS schema, and the non-secret scope overlay.

Two asymmetries are deliberate. The default is attributive, because the other
default would have audit-core imply a completeness obligation no source ever
accepted. And the overlay may raise the kind but never lower it — the same
principle that stops an ExternalSecret refresh shrinking user-engine's
tenants: a ConfigMap refresh must not drop a source's atomicity and detection
obligations without anyone deciding to. A load-bearing source may not carry a
completeness trade at all, since §9.6 requires atomicity of it, and
evidence_declaration() reports completeness_claimed: false for both kinds.

T09 (in progress). approval-engine's registration inputs are prepared and
recorded in docs/approval-engine-source-registration.md: scope entry declared
load-bearing, and audit-core-approval-engine-ingress with namespace and pod
label ANDed in one `from` peer — narrower than user-engine's namespace-only
rule, which is left unchanged. The scope entry lands ahead of the credential
because the overlay only applies to senders the Secret already carries, so it
admits nothing until the token exists; a test asserts that rather than
trusting the reading.

Two inputs remain approval-engine's: a confirmed tenant scope, since senders.py
requires a missing tenant restriction be justified per sender and audit-core
cannot justify it on another repo's behalf, and an explicit secret_policy
choice. Applying the manifests is an operator action.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0185wifnLzCxjEY2MT1XbK7L

Assistant: claude-code
Assistant-Model: opus
Assistant-Process: 713962@bnt-lap001
Assistant-Session: 2718d99d-d3ff-478f-83a2-3a30f01a02fc

docs/approval-engine-source-registration.md

@@ -0,0 +1,122 @@
+# approval-engine source registration
+
+`AUDIT-WP-0009-T09` · intake `AUDIT-IN-0001` · statute §9.4, §9.6
+
+The registration inputs for `approval-engine` as a distinct audit source,
+onboarded under `INTENT.md` principle 4 — declared ownership, retention,
+access, export and evidence policy, not merely events arriving.
+
+This file is the owner-side record. Everything in it is non-secret. No sender
+token appears here, in Git, in State Hub, or in a workplan.
+
+## Declaration
+
+| Field | Value |
+| --- | --- |
+| Sender name | `approval-engine` |
+| Permitted `source` | `approval-engine` (exact; no wildcard) |
+| `evidence_kind` | **`load-bearing`** (§9.4 — a control's soundness depends on the revocation event being present) |
+| `completeness_trade` | none, and none is permitted — §9.6 requires emission atomicity of a load-bearing source |
+| `may_write` | true |
+| `may_read` | false — a source does not gain a read surface by emitting |
+| `secret_policy` | `redact` (estate default; see below) |
+| `tenants` | `["*"]` — **proposed, needs approval-engine's confirmation** |
+| Retention | no expiry set; recoverable history is the platform `data.backup` window, 30 days, `measured` |
+| Custody class | `operational` — never `archive`, never WORM |
+
+### Event classes
+
+The four §9.4 classes, carried as distinct actions on one source:
+
+| Class | Why it matters |
+| --- | --- |
+| issuance | the approval came into being |
+| use | single consumption, a state change owned by `approval-engine` |
+| supersession | the prior approval stopped being current |
+| revocation | **the acute one** — the most valuable event to suppress |
+
+Audit Core stores all four and derives nothing from them. It renders no verdict
+on whether an approval is still valid (§9.4), asserted by test in
+`tests/test_approval_validity_prohibition.py`.
+
+### The `tenants` value is the one input still owed
+
+`["*"]` is proposed because approval issuance is not obviously tenant-
+partitioned, and the alternative — an explicit tenant list — cannot be invented
+here. `audit_core/senders.py` states that omitting a tenant restriction "should
+be justified per sender, not adopted by default", so this needs
+`approval-engine` to either confirm the wildcard with its reasoning or supply
+the list. Tenant identifiers are opaque to Audit Core; their shape is owned by
+the IAM Profile and `tenant-engine`.
+
+### `secret_policy`
+
+`redact` accepts the event and redacts a secret-shaped field, so a legitimate
+event is not lost over one field. For a load-bearing source that trade is worth
+re-examining: `reject` refuses the event instead, which for approvals converts a
+redactable field into a delivery failure the source must retry. `redact` is the
+recommendation — losing a revocation record is worse than storing it with one
+field redacted — but it is `approval-engine`'s call to make explicitly rather
+than inherit.
+
+## Applied in this repository
+
+| Input | Where |
+| --- | --- |
+| Non-secret scope | `deploy/senders-scope.json` + `deploy/senders-scope.yaml` (lockstep) |
+| Receiver ingress | `deploy/networkpolicies.yaml`, `audit-core-approval-engine-ingress` |
+| Evidence kind in the model | `audit_core/senders.py`, `SenderIdentity.evidence_kind` |
+
+The scope overlay only applies to a sender the Secret already carries, so this
+entry is **inert until the token exists**. That is what makes it safe to land
+ahead of the credential rather than in the same change.
+
+The ingress rule is narrower than `user-engine`'s: namespace **and** pod label
+in a single `from` peer, so both are ANDed. A new sender should not inherit an
+older rule's breadth. `user-engine`'s sender and its policy are unchanged.
+
+## Still owed by others
+
+| Input | Owner | Note |
+| --- | --- | --- |
+| Token at `approval-engine/approval-engine-audit`, key `audit-token` | OpenBao (`railiance-platform`), routed via `warden route` | Audit Core never holds or transports it |
+| `tenants` confirmation | `approval-engine` | see above |
+| `secret_policy` confirmation | `approval-engine` | see above |
+| Applying the manifests to `railiance01` | operator | Audit Core does not apply cluster changes unprompted |
+
+## What Audit Core will and will not claim about this stream
+
+Stated here because §9.6 requires the bound to travel with the trail, and
+because a load-bearing source will otherwise be told less than it needs.
+
+**Will:** every event it accepted is stored append-only, and the hash chain
+detects alteration or truncation of what it received.
+
+**Will not:** that the archive proves an approval event occurred, or that the
+absence of one proves it did not. Completeness at the boundary is
+`approval-engine`'s obligation and an archive cannot retrofit it.
+
+### Open gates, and which of them block what
+
+| Gate | Blocks admission? | What it actually bounds |
+| --- | --- | --- |
+| `T02` attestation scheduling | **No** | Evidence *quality*, not custody. See below. |
+| `T04` heartbeat / missing-heartbeat findings | No | Detection of adversarial omission for rare classes — the one that matters most for revocation |
+| `T06` reconciliation counts | No | The source's own ability to detect divergence |
+| `T05` declared cadence | No | Held deliberately on the §17 Taxonomy schema |
+
+**T02 is an evidence-quality gate, not an admission or deployment blocker.**
+Admission depends on identity, scope, ingress and a token. Attestation freshness
+governs what Audit Core may *claim*, not whether it accepts and durably stores.
+The append-only trigger and hash chain operate regardless; what a stale
+attestation removes is detection of a suffix rewrite by someone who owns the
+database. Since `AUDIT-WP-0009-T01`, `/readyz` reports `tamper_evidence: false`
+rather than overclaiming, and will keep doing so until T02 mounts a renewed
+attestation.
+
+It also is not the gate that matters most here. §9.6 is explicit that the acute
+risk for approvals is **omission**, and tamper evidence does not address
+omission at all — T04 does. So a consumer waiting on T02 before trusting
+approval evidence would be waiting on the wrong control. Until T04 and T06
+land, Audit Core cannot detect a suppressed revocation, and no reading of the
+chain, attested or not, changes that.

docs/senders.example.json

@@ -1,30 +1,67 @@
 [
   {
     "name": "user-engine",
-    "tokens": ["replace-with-write-token"],
-    "sources": ["user-engine"],
-    "tenants": ["*"],
+    "tokens": [
+      "replace-with-write-token"
+    ],
+    "sources": [
+      "user-engine"
+    ],
+    "tenants": [
+      "*"
+    ],
     "may_write": true,
     "may_read": false,
-    "secret_policy": "redact"
+    "secret_policy": "redact",
+    "evidence_kind": "attributive",
+    "completeness_trade": "illustrative: emission is after commit, so a crash between the two loses the event"
   },
   {
     "name": "operator",
-    "tokens": ["replace-with-read-token"],
-    "sources": ["user-engine"],
-    "tenants": ["*"],
+    "tokens": [
+      "replace-with-read-token"
+    ],
+    "sources": [
+      "user-engine"
+    ],
+    "tenants": [
+      "*"
+    ],
     "may_write": true,
     "may_read": true,
     "secret_policy": "redact"
   },
   {
     "name": "temporary-evidence-sender",
-    "tokens": ["replace-with-short-lived-token"],
-    "sources": ["whitehat-security"],
-    "tenants": ["tenant:trial:named-fixture"],
+    "tokens": [
+      "replace-with-short-lived-token"
+    ],
+    "sources": [
+      "whitehat-security"
+    ],
+    "tenants": [
+      "tenant:trial:named-fixture"
+    ],
     "may_write": true,
     "may_read": true,
     "secret_policy": "redact",
-    "expires_at": "2026-08-22T18:15:00Z"
+    "expires_at": "2026-08-22T18:15:00Z",
+    "evidence_kind": "attributive"
+  },
+  {
+    "name": "approval-engine",
+    "tokens": [
+      "replace-with-write-token"
+    ],
+    "sources": [
+      "approval-engine"
+    ],
+    "tenants": [
+      "*"
+    ],
+    "may_write": true,
+    "may_read": false,
+    "secret_policy": "redact",
+    "evidence_kind": "load-bearing"
   }
 ]