tegwick
3c2cdcdf79
Registration: attributive, with the declared completeness_trade recorded on the receiver side rather than only in the emitter, per §9.6's requirement that the trade travel with the trail. tenants ["*"] is justified rather than inherited — tenant-engine's events carry the affected tenant, the set is every tenant including ones created later, and an explicit list would fail closed at exactly the moment a tenant is provisioned, dead-lettering the creation evidence of the tenant whose creation it is. source stays pinned exactly. Ingress ANDs namespace and pod label; a weaker evidence class is not a reason for a wider network rule. All inert until the token exists. Then the finding T04 existed to find: tenant-engine cannot deliver a single event today. envelope_for sends five required fields under other names — event_id, action, resource, observed_at, details — and omits correlation_id entirely, so normalize() raises invalid_event. Verified by running the real envelope through the real function, not by reading. Worse than an ordinary integration bug. The drain treats 400 as terminal, so the outbox row is marked handled while audit-core holds only a dead letter, which is not chained and is not custody. Lost on both sides, and since the drain is non-blocking and attributive, nothing fails loudly — a silent total loss of the stream presenting as a working integration. Taking the correction the intake invited rather than accepting a lossy record. normalize() is NOT relaxed to accept the alternate spellings: a receiver that guesses which sender key means which stored field has made the mapping its own, and the record stops being the sender's assertion. correlation_id cannot be synthesized at all — an invented one ties an event to an operation audit-core never observed. Root cause is ours. The accepted envelope was published nowhere a sender could read it; audit-backend-contract.md describes the stored record, and a sender reading it would reasonably infer exactly the names tenant-engine used. schema_version audit-core.event.v1alpha1 selects nothing here and gave a false impression of a negotiated contract. Published docs/event-envelope.md as the wire contract, including the point that a 400 means the event is not in the archive and must be treated as a defect to fix rather than a delivery outcome. T05 moved to wait: nothing to prove end to end until an event can be accepted. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Nb7Q6ZmXppNDkTWytfYqfv Assistant: claude-code Assistant-Model: opus Assistant-Process: 2069992@bnt-lap001 Assistant-Session: 167dd7f8-2a25-4be1-aa46-3b6f1a5f94c6
4.7 KiB
The ingest envelope: what POST /v1/events accepts
AUDIT-WP-0010-T04. Written because it was not written down, and a sender
built against a shape the receiver does not implement.
This is the wire contract for a sender. It is the authority; anything a sender
infers from another sender's code, from docs/audit-backend-contract.md (which
describes the storage record, not the request), or from a schema name, is a
guess.
Request
POST /v1/events
Authorization: Bearer <sender token>
Idempotency-Key: <the event's id — must equal the body's "id">
Content-Type: application/json
Body — all eight fields are required
| Field | Type | Meaning |
|---|---|---|
id |
string | The event id. Must equal the Idempotency-Key header exactly, or the request is rejected idempotency_key_mismatch |
type |
string | The domain event type. Stored as the record's action |
source |
string | The emitting system. Checked against the credential's permitted sources |
subject |
string | What the event is about. Stored as the record's resource |
tenant |
string | The affected tenant. Checked against the credential's permitted tenants by exact string equality |
correlation_id |
string | Ties an event to the request or operation that caused it |
occurred_at |
string | RFC 3339 with an explicit offset. A naive timestamp is rejected — it is ambiguous by up to a day |
data |
object | The event payload. Stored verbatim under details.data, subject to the sender's secret_policy |
Every one of the eight must be present and truthy. An empty string, an
empty object, or null fails the same way a missing key does.
There is no schema_version field. A body carrying one is not rejected for it —
unknown top-level keys are ignored — but it is not stored and it selects
nothing. Do not treat a version string as a contract with this receiver.
Minimal accepted body
{
"id": "a5f3...",
"type": "role.granted",
"source": "tenant-engine",
"subject": "tenant:acme",
"tenant": "tenant:acme",
"correlation_id": "req-9f21",
"occurred_at": "2026-09-10T11:04:12+00:00",
"data": {"role": "admin", "granted_by": "u-1"}
}
What the receiver derives, and a sender must not send
These are set by audit-core and any value a sender supplies for them is ignored. Sending them is harmless but misleading, because it looks like the sender controls them.
| Stored field | Where it comes from |
|---|---|
observed_at |
normalized from occurred_at |
action |
type |
resource |
subject |
scope |
always "tenant" |
outcome |
always "recorded" — this receiver records; it does not adjudicate |
actor |
always null at ingest. If the acting principal matters, put it inside data |
details.redaction |
added when secret_policy removed something |
outcome and actor being fixed is deliberate and worth understanding: an
audit event here is a record that a sender said something, not a finding about
it. A sender that wants an outcome recorded puts it in data, where it reads
as the sender's claim rather than the archive's.
Responses
| Status | Meaning |
|---|---|
202 |
Accepted and stored |
200 |
Duplicate id — already stored, reconciled rather than re-linked. Not an error; do not retry |
400 |
Rejected and dead-lettered. Body carries the reason: invalid_event, idempotency_key_mismatch, source_not_allowed, tenant_not_allowed, secret_shaped_field |
401 |
Unknown or expired token |
403 |
The credential lacks may_write |
A 400 means the event is not in the archive. It is retained in the dead-letter surface with its reason, which is a diagnostic queue, not custody: it is not chained, and it is not what a reviewer reads. A sender whose drain treats 400 as terminal will lose the event on both sides — its outbox marks the row handled and audit-core holds only a dead letter. Treat a 400 as an integration defect to fix, never as a delivery outcome to record and move on from.
Rejection is total, not partial
There is no lossy accept. If a required field is missing the whole event is
rejected — audit-core does not store a partial record with a synthesized
correlation_id or a defaulted timestamp, because a record the archive
partly invented is worse than no record: a reviewer cannot tell which fields
the sender actually asserted.
This is why an envelope mismatch is loud rather than silent, and it is the intended behaviour.
Before you write a drain
Post one event against a non-production receiver and check for 202. Every
field above is checked on the first request, so a single successful post
validates the whole envelope. A sender that first exercises the path in
production discovers the contract through its dead-letter queue.