tegwick
2bd2d19a98
Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a05e2e-805b-7042-a750-71f473bceea2
100 lines
3.9 KiB
Markdown
100 lines
3.9 KiB
Markdown
# Local transactional outbox contract
|
|
|
|
Coordinates with `GH-WP-0002-T02`. Boundary and locality are in `INTENT.md`
|
|
and statute §9.4; this is the wire.
|
|
|
|
An implementer **cannot** satisfy this contract by emitting synchronously to
|
|
`audit-core` inside the state-change transaction. That path is atomic and is
|
|
forbidden: an audit outage would become an inability to revoke.
|
|
|
|
## Rule
|
|
|
|
Every issuance, use, supersession, and revocation **inserts an outbox row in
|
|
the same transaction** that mutates the approval object. The durable queue
|
|
lives in this engine's own store. Drain is asynchronous, at-least-once.
|
|
`audit-core` dedupes on `event_id`; a replay does not fork the chain.
|
|
|
|
If the outbox insert cannot be committed, the mutation does not commit.
|
|
Emit-after-commit is a defect.
|
|
|
|
Heartbeat rows (see [`emission-cadence.md`](emission-cadence.md)) use the
|
|
same table and the same at-least-once drain. They are not coupled to an
|
|
object mutation.
|
|
|
|
## Event classes
|
|
|
|
| Class | When | `audit-core` `action` |
|
|
| --- | --- | --- |
|
|
| `issuance` | object becomes `approved` (threshold met) | `approval.issuance` |
|
|
| `use` | public CAS accepts first `request_digest` and object becomes `consumed` | `approval.use` |
|
|
| `supersession` | object becomes `superseded` | `approval.supersession` |
|
|
| `revocation` | object becomes `revoked` | `approval.revocation` |
|
|
| `heartbeat` | signed *nothing to report* plus counts | `approval.heartbeat` |
|
|
|
|
Expiry is a clock crossing, persisted on observation, and is **not** an
|
|
emitted class. The validity window is already on the object.
|
|
|
|
## Outbox row
|
|
|
|
| Field | Type | Notes |
|
|
| --- | --- | --- |
|
|
| `event_id` | UUID | Stable. Drain retries reuse it. |
|
|
| `class` | enum above | |
|
|
| `approval_id` | UUID or null | Null only for heartbeat. |
|
|
| `payload` | object | The source record adapted to audit-core's HTTP envelope at drain time. |
|
|
| `created_at` | RFC 3339 UTC | |
|
|
| `drained_at` | RFC 3339 UTC or null | Set after a successful audit-core ack. |
|
|
| `attempts` | integer | Delivery attempts, including the successful attempt. |
|
|
| `last_attempt_at` | RFC 3339 UTC or null | Most recent delivery attempt. |
|
|
| `last_error` | class name or null | Bounded failure category; never exception text. |
|
|
|
|
## Payload (audit-core v1alpha1)
|
|
|
|
```json
|
|
{
|
|
"schema_version": "audit-core.event.v1alpha1",
|
|
"event_id": "<same as outbox.event_id>",
|
|
"observed_at": "<created_at>",
|
|
"tenant": "platform",
|
|
"scope": "netkingdom-approvals",
|
|
"source": "approval-engine",
|
|
"actor": "<actor or null for heartbeat>",
|
|
"action": "approval.revocation",
|
|
"resource": "approval:<approval_id>",
|
|
"outcome": "success",
|
|
"reason": null,
|
|
"details": {
|
|
"class": "revocation",
|
|
"approval_id": "<uuid>",
|
|
"binding_digest": "sha256:…",
|
|
"superseded_by": null
|
|
}
|
|
}
|
|
```
|
|
|
|
No secret values. `details` may add non-secret identifiers; it must not add a
|
|
validity verdict for consumers to branch on. `audit-core` MUST NOT expose an
|
|
approval-validity query; this payload does not invite one.
|
|
|
|
## Drain
|
|
|
|
1. Select undrained rows, oldest first.
|
|
2. Adapt it to audit-core's `{id,type,source,subject,tenant,correlation_id,
|
|
occurred_at,data}` envelope, using `event_id` as both `id` and the
|
|
`Idempotency-Key` header.
|
|
3. POST with the mounted sender credential, reread on every attempt.
|
|
4. On `202 accepted` or `200 duplicate`, set `drained_at`.
|
|
5. On failure, leave the row and record only a bounded failure class; retry
|
|
later. **Do not** roll back the object
|
|
mutation — it already committed with the row.
|
|
|
|
An `audit-core` outage therefore cannot block a revocation. This engine's
|
|
own store being unavailable can, and should: the change could not have been
|
|
recorded anyway.
|
|
|
|
## Forbidden shapes
|
|
|
|
- `audit-core` HTTP (or any client) inside `BEGIN` … `COMMIT` of a mutation.
|
|
- Best-effort publish after commit with no row.
|
|
- A second, non-local queue as the durability mechanism.
|
|
- Deduping in this engine instead of relying on `event_id` at `audit-core`.
|