Implement the engine spine: claim, outbox, machine, API

Contracts first (T02–T04): approval claim schema with issuer, freshness,
and binding digest; local transactional outbox wire; load-bearing cadence
as heartbeat or reconciliation (layer.yaml declared).

Then the object (T06–T08): SQLite closed state machine, CAS supersession,
distinct-approver fail-closed, revocation without holder cooperation,
outbox insert in the same transaction. Tests fail the mutation when
emission fails, and revoke while the drain sink is down.

Introspection GET /v1/approvals/{id}/claim is a PIP fact, not a decision.
No public consume (T05 waits on GH-WP-0002-T06). Canon T-06 coverage for
wrong binding, expiry, revoke, and supersede.

FLEX-WP-0017 T03 is unblocked on this object; T05 remains blocked only on
consumption ordering.

Assistant: grok
Assistant-Session: 01a04ceb-2057-7e20-b0f9-c282964d5dd9

docs/approval-claim.md

@@ -0,0 +1,120 @@
+# Approval claim contract
+
+**Schema:** [`../schemas/approval_claim.schema.json`](../schemas/approval_claim.schema.json)
+**Version:** 0.1
+**Issuer:** `approval-engine`
+**Consumer:** `access-engine` (`flex-auth` until the governed rename)
+
+This is the input claim `access-engine` consumes under statute §6.2. It is a
+fact about an approval object. It is **not a decision**. An implementer can
+satisfy this document without reading this engine's source.
+
+Yields to the Taxonomy request-claim schema (statute §17) when that artifact
+exists and is assented. This local shape is not permanent.
+
+## Fetch
+
+```text
+GET /v1/approvals/{id}/claim
+```
+
+Fail-closed when this engine's store is unavailable (HTTP 503). An `audit-core`
+outage does not affect this read.
+
+There is no `/v1/check`, no `/authorize`, and no field named `effect`,
+`decision`, `allow`, or `deny`. If a response contains those, it is out of
+contract.
+
+## What the claim carries
+
+| Field | Why |
+| --- | --- |
+| `approval_id` | Reconstructable from the decision record. |
+| `binding.digest` | Distinguishes *approved* from *approved for this exact request*. |
+| `binding.pdp_digest` | Optional. When recorded at issue, compare to `NewDecisionBinding.request_digest`. |
+| `issuer` | Always `approval-engine`. |
+| `freshness` | So the PDP can state a deadline for this input class (§9.7.2), not a single fiction covering every source. |
+| `valid_now` | Current-state predicate. Not permission. |
+| `reason_code` | Why `valid_now` is false, when it is. |
+
+`valid_now` is true only when all of:
+
+1. enough distinct authenticated approvers have been recorded;
+2. now is inside `validity.not_before` … `validity.expires_at`;
+3. the object is not consumed, superseded, revoked, or expired.
+
+Holding a claim with `valid_now: true` is not authority to act. It is one
+input the decision point weighs.
+
+## Canonical binding digest
+
+The native digest is:
+
+```text
+sha256: + hex( SHA-256( canonical_json({action, actor, principal, purpose, target}) ) )
+```
+
+`canonical_json` is UTF-8 JSON with sorted keys at every object level and no
+insignificant whitespace (`separators=(',', ':')`). `target` is an object; its
+keys are sorted too.
+
+Wrong-action, wrong-target, and wrong-scope are distinguishable because they
+change that JSON and therefore the digest. A decision rendered against
+approval A for request R cannot be replayed for request R' if the consumer
+compares digests.
+
+### Mapping from a flex-auth CheckRequest
+
+| Claim binding | CheckRequest |
+| --- | --- |
+| `action` | `action` |
+| `target` | `resource` (object) |
+| `actor` | `subject.id` |
+| `principal` | `subject.attributes.principal` if present, else `subject.id` |
+| `purpose` | `context.purpose` |
+
+Go's `json.Marshal` of a `CheckRequest` is **not** this canonical JSON (field
+order and `omitempty` differ). Do not hash a CheckRequest with this function
+and expect it to equal `NewDecisionBinding.request_digest`.
+
+When the issuer recorded the PDP digest at issue time, it is in
+`binding.pdp_digest`. **Prefer that comparison** at decision time:
+
+```text
+claim.binding.pdp_digest == decision.binding.request_digest
+```
+
+and still require `claim.approval_id` to match the approval named on the
+request. Native `binding.digest` remains the identifier of *this engine's*
+binding, and is what T-06 uses when no PDP digest was recorded.
+
+## Freshness
+
+Default TTL is **30 seconds** from `observed_at`. `not_after` is
+`observed_at + ttl_seconds`. A PDP that needs a different deadline for the
+approval input class states it in its own provenance; it must not invent
+freshness this engine did not publish.
+
+A claim used after `freshness.not_after` is stale. Stale is not the same as
+`valid_now: false` — the object may still be valid; the *observation* is old.
+Re-fetch.
+
+## Required verification (consumer)
+
+A production consumer of this claim, before treating it as an input, checks:
+
+1. The claim resolved from this engine; an outage fails the action closed.
+2. `issuer` is `approval-engine`.
+3. `valid_now` is true and `consumed` is false.
+4. `binding.digest` equals the digest of the binding the consumer computed
+   from the proposed action, **or** `binding.pdp_digest` equals the
+   `NewDecisionBinding` digest of that request.
+5. `freshness.not_after` is still in the future.
+6. `reason_code` is `ok`.
+
+Local fixtures, workplan ids, and prose are not this claim.
+
+## Examples
+
+See [`../examples/claim.valid.json`](../examples/claim.valid.json) and
+[`../examples/claim.revoked.json`](../examples/claim.revoked.json).

docs/emission-cadence.md

@@ -0,0 +1,62 @@
+# Emission cadence — source declaration
+
+Statute §9.6: approval evidence is **load-bearing** and **low-volume**. Rate
+monitoring is the wrong form. A handful of revocations a month has no rate to
+drop below; suppression is indistinguishable from a quiet month.
+
+This file is the source side of `GH-WP-0002-T04`. That task is the detection
+surface; this declaration is what it reads. Machine-readable copy:
+[`../cadence.yaml`](../cadence.yaml).
+
+## Form
+
+**Heartbeat, plus reconciliation counts.** Not a rate.
+
+### Heartbeat
+
+A signed positive claim: *nothing to report*, together with per-class
+transition counts since the previous heartbeat (or since process start on
+the first). The claim can itself go missing, which is the point — silence
+becomes a missing positive rather than a quiet month.
+
+| Field | Value |
+| --- | --- |
+| Class | `heartbeat` |
+| Interval | 24 hours (SHOULD also be emittable on demand) |
+| Assertion | `nothing-to-report` |
+| Counts | `{issuance, use, supersession, revocation}` of committed outbox rows |
+| Missing heartbeat | **finding** |
+
+### Reconciliation
+
+Compare this engine's committed outbox counts per class to `audit-core`'s
+accepted event counts for `source=approval-engine` and the corresponding
+`action`. Divergence is a **finding**, not a log line.
+
+| This engine | `audit-core` `action` |
+| --- | --- |
+| `issuance` | `approval.issuance` |
+| `use` | `approval.use` |
+| `supersession` | `approval.supersession` |
+| `revocation` | `approval.revocation` |
+| `heartbeat` | `approval.heartbeat` |
+
+Undrained local rows are this engine's lag, not yet a divergence. A row
+with `drained_at` set that `audit-core` does not hold is the omission
+case §9.6 names.
+
+## What is a finding
+
+- No heartbeat arrives for more than one interval.
+- `audit-core` count for a class is less than this engine's drained count
+  for that class.
+- Outbox depth or age exceeds the lag bound in `cadence.yaml` (drain stuck).
+
+None of these are rate drops. None of these are informational logs.
+
+## Residual
+
+Atomicity prevents accidental omission (crash between mutation and emit).
+Cadence and reconciliation **detect** adversarial omission after the fact.
+Nothing in the model prevents a compromised source from suppressing. That
+residual is stated, not closed.

docs/flex-auth-handoff.md

@@ -0,0 +1,26 @@
+# Handoff for `access-engine` / `FLEX-WP-0017`
+
+`FLEX-WP-0017` T03 waited on a durable object that was not the State Hub
+`/decisions/{uuid}` shape. That object is this engine.
+
+## What exists
+
+- Claim contract: [`approval-claim.md`](approval-claim.md)
+- Introspection: `GET /v1/approvals/{id}/claim`
+- Object: `POST /v1/approvals`, entries, revoke, supersede
+- Native `binding.digest` plus optional `binding.pdp_digest` for
+  `NewDecisionBinding.request_digest`
+
+T03 is unblocked on the **object**, not on a hub substitute. Validate the
+claim before privileged production actions. Fail closed if this engine is
+unreachable.
+
+## What does not exist yet
+
+Consumption ordering (`GH-WP-0002-T06` / `APPROVAL-WP-0001-T05`). There is
+no public `consume`. `FLEX-WP-0017` T05 stays blocked **only** on that
+contract, not on a missing object or a missing digest.
+
+Canon T-06 against this implementation: `tests/test_t06_replay.py` (wrong
+target, wrong action, later time, revoked, superseded). Consume-side replay
+is out of scope until T05.

docs/outbox-contract.md

@@ -0,0 +1,93 @@
+# 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` | object becomes `consumed` (internal CAS; not a public API until `GH-WP-0002-T06`) | `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 `audit-core.event.v1alpha1` record, ready to POST. |
+| `created_at` | RFC 3339 UTC | |
+| `drained_at` | RFC 3339 UTC or null | Set after a successful audit-core ack. |
+
+## 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. POST each payload to `audit-core`.
+3. On success, set `drained_at`.
+4. On failure, leave the row; 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`.