audit-core/docs/approval-engine-source-registration.md

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