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

# tenant-engine source registration

`AUDIT-WP-0010` · intake `AUDIT-IN-0002` · statute §9.6

Registration inputs for `tenant-engine` as an attributive audit source.
Owner-side record, entirely non-secret. No sender token appears here, in Git,
in State Hub, or in a workplan.

## Declaration

| Field | Value |
| --- | --- |
| Sender name | `tenant-engine` |
| Permitted `source` | `tenant-engine` (exact; no wildcard) |
| `evidence_kind` | **`attributive`** — declared by the emitter, and the declaration is the emitter's to make |
| `completeness_trade` | **declared**: the outbox drains after commit rather than inside the mutation transaction (`tenant-engine/docs/evidence-emission.md`) |
| `may_write` | true |
| `may_read` | false |
| `secret_policy` | `redact` |
| `tenants` | `["*"]` — justified below, not inherited |
| Retention | no expiry set; recoverable history is the platform `data.backup` window, 30 days, `measured` |
| Custody class | `operational` |

### Why the tenant scope is a wildcard, and why that is not a shrug

`senders.py` requires a missing tenant restriction to be justified per sender,
so: `tenant-engine` is the tenant lifecycle engine. Its events carry the
*affected* `tenant_id`, and the set of affected tenants is every tenant that
exists, including ones created after this registration was written. An explicit
list would have to be edited on every tenant creation, and would fail closed at
exactly the moment a new tenant is provisioned — dead-lettering the creation
evidence of the tenant whose creation it is. That is a worse failure than the
breadth it buys.

This is the same justification `user-engine` carries and a different one from
`approval-engine` and `informed-decision`, which are single-tenant by
construction and are therefore scoped exactly.

The exposure the wildcard leaves is real and worth naming: a compromised
`tenant-engine` credential can attribute an event to any tenant. `source` is
still pinned exactly, so it cannot impersonate another engine.

### The attributive trade, recorded here and not only in the emitter

§9.6 permits attributive evidence to trade away emission atomicity **provided
the trade is declared and completeness is never claimed**. `tenant-engine`
declared it properly and in advance. Recorded on this side per the statute's
requirement that the trade travel with the trail:

| Step | Atomic with the mutation? |
| --- | --- |
| local `events` row | yes |
| local `audit_outbox` row | yes |
| drain to audit-core | **no** — after commit |

So a mutation can exist here without its event, and audit-core will never know.
Nothing in this archive detects that, and no reading of the chain changes it.
`completeness_claimed` is `false` for this source, as it is for every source.

If a control ever starts branching on these events, the class must be raised to
load-bearing **before** that ships — and the scope overlay is deliberately
built so it can raise the kind but never lower it.

## Blocking finding: the envelope does not match — events would be rejected

**`tenant-engine` cannot deliver a single event today, and admitting the sender
would not change that.** This is the correction `AUDIT-IN-0002` invited rather
than a refusal.

`tenant_engine.audit_core.envelope_for` emits a shape the receiver does not
accept. `normalize()` requires eight fields; the envelope supplies three of them
under the required names and omits one entirely.

| Receiver requires | `tenant-engine` sends | Result |
| --- | --- | --- |
| `id` | `event_id` | missing |
| `type` | `action` | missing |
| `subject` | `resource` | missing |
| `occurred_at` | `observed_at` | missing |
| `data` | `details` | missing |
| `correlation_id` | — | **absent entirely** |
| `source` | `source` | ok |
| `tenant` | `tenant` | ok |

Verified by running the real envelope through the real `normalize()`, not by
reading: it raises `invalid_event`. Every event would return **400** and be
dead-lettered.

**Why this is worse than a normal integration bug.** `tenant-engine`'s drain
treats 400 as terminal (`400/409 dead-letter`, `docs/evidence-emission.md`).
So the outbox row is marked handled while audit-core holds only a dead letter —
which is not chained and is not custody. The event is lost on both sides, and
because the drain is non-blocking and attributive, nothing fails loudly. A
silent total loss of the stream, presenting as a working integration.

`schema_version: audit-core.event.v1alpha1` selects nothing at this receiver.
There is no version negotiation; the name gave a false impression of a contract.

**Whose fault this is: ours, mostly.** The accepted envelope was documented
nowhere a sender could read it. `docs/audit-backend-contract.md` describes the
stored record, and a sender reading it would reasonably infer the field names
that `tenant-engine` used. The contract is now published at
`docs/event-envelope.md`, and that gap is the actual root cause.

**What is needed:** `tenant-engine` maps `envelope_for` onto the eight required
fields and supplies a `correlation_id` (it has a natural one — the request or
operation that caused the mutation). audit-core is **not** relaxing
`normalize()` to accept the alternate names: a receiver that guesses which key
means what would be inventing the mapping, and a record whose field meanings the
archive chose is not the sender's assertion any more. `correlation_id` in
particular cannot be synthesized — a made-up one is worse than none.

A regression test (`tests/test_tenant_engine_envelope.py`) pins the mismatch, so
it becomes visible the moment the emitter is corrected rather than being
rediscovered in production.

## 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-tenant-engine-ingress` |
| Declared trade | `SenderIdentity.completeness_trade`, carried through the overlay |
| Wire contract | `docs/event-envelope.md` |

Inert until the token exists: the overlay applies only to a sender the Secret
already carries.

The ingress rule ANDs namespace and pod label in one peer. Attributive rather
than load-bearing changes what may be claimed of the stream, not how narrow its
reachability should be — a weaker evidence class is not a reason for a wider
network rule. `user-engine`'s policy is unchanged.

## Still owed

| Input | Owner | Note |
| --- | --- | --- |
| Envelope correction | **`tenant-engine`** | Blocking. Nothing lands until this is fixed |
| Sender token, custody via `warden route` | OpenBao (`railiance-platform`) | audit-core never holds or transports it |
| Protected registry entry with explicit `secret_policy` | `railiance-platform` | The overlay does not override it |
| Applying the manifests | operator | audit-core does not apply cluster changes unprompted |
| Live positive-path evidence under `docs/evidence/` | audit-core, after the above | `AUDIT-WP-0010-T05` |

## What Audit Core will and will not claim about this stream

**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 a mutation occurred, or that absence
proves it did not — and here that bound is sharper than usual, because the
declared trade means a committed mutation can legitimately have no event at all.