AuditEnvelope v1 — unified abstract audit message format (Phases B + C + F)

[hanwencheng]

Context

PR #95 (issue #82 ERC-7730 + EIP-712 sign) added signed_intent_text + signed_intent_hash to the audit-row schema, but only for typed-data signs. The rest of the audit surface (scope mutations, device mutations, payments, memory ops, email, K3 epoch advance) still carries the narrow (actor_omni, service_hash, op_type ∈ {0,1,2}, payload_hash) shape that CredentialAudit.sol takes — useless for sign events and orthogonal data classes.

Phase A — the canonical schema + non-break design — landed in PR #95 under arch.md §15.3a. This issue tracks the implementation phases B / C / F.

Phase B — worker + core migration

• Add AuditEnvelope v1 struct to agentkeys-core (CBOR-serializable, deterministic encoding per RFC 8949 §4.2.1).
• Add AuditOpKind u8 + per-kind op_body schemas matching the canonical table in arch.md §15.3a.
• Add GET /v1/audit/envelope/<hash> endpoint to `agentkeys-worker-audit` returning the full envelope.
• Migrate the existing `POST /v1/audit/append` to accept the new envelope shape; keep the old shape on `/v1/audit/append/v1` for one cycle so older callers don't break.
• Update credentials-service + memory-service workers to emit `AuditEnvelope` instead of the legacy 5-field struct.
• Compute `envelope_hash = keccak256(canonical_cbor(envelope))` for chain commitment.
• Test: CBOR encode + decode roundtrip on canonical fixtures per op_kind.

Phase C — contract revision

• Add `appendV2(operatorOmni, actorOmni, opKind, envelopeHash)` to `CredentialAudit.sol` (additive, retain v1).
• Add `appendRootV2(operatorOmni, merkleRoot, opKindBitmap, entryCount)` with `opKindBitmap: bytes32` (each bit = one of 256 possible op_kinds present in the batch — explorers filter without fetching leaves).
• Emit `AuditAppendedV2` + `AuditRootAppendedV2` events with `indexed opKind` topic for fast `eth_getLogs` filtering.
• Forge tests covering both shapes coexist.
• Redeploy on Heima Mainnet via `scripts/heima-bring-up.sh` (idempotent).
• Update `docs/spec/deployed-contracts.md` with new address.

Phase F — extend op_kind coverage

Each row below is a separate PR that touches the arch.md table exactly once (claims a byte) + adds the worker emit-site + the explorer renderer in litentry/subscan-essentials + litentry/subscan-essentials-ui-react.

• `SignEip191` (byte 20) — signer emits via daemon callback after `POST /dev/sign-message`.
• `SignEip712` (byte 21) — signer emits via daemon callback after `POST /dev/sign-typed-data`. Carries the `intent_text` + `intent_commitment` from PR issue #82: ERC-7730 clear-signing + EIP-712 typed-data sign (v2-aligned) #95.
• `ScopeGrant` (byte 40) + `ScopeRevoke` (byte 41) — broker emits when `AgentKeysScope.setScopeWithWebauthn` / `revokeScope` lands.
• `DeviceAdd` (50) + `DeviceRevoke` (51) + `K10Rotate` (52) — SidecarRegistry hook emits.
• `PaymentEscrowRedeem` (30) + `PaymentDirect` (31) — payment-service worker emits (requires §15.5 work).
• `MemoryPut` (10) + `MemoryGet` (11) + `MemoryTeardown` (12) — memory-service worker emits.
• `EmailSend` (60) + `EmailReceive` (61) — email-service worker emits.
• `K3EpochAdvance` (70) — K3EpochCounter hook emits.

Non-break invariants (per arch.md §15.3a)

Every PR landing a new op_kind MUST preserve all 8 invariants:

1. `op_kind` is `u8` not a sealed enum.
2. Envelope-level fields are stable; only `op_body` is op-kind-specific.
3. `version` bumps only on envelope-level changes, never on new op_kinds.
4. Explorer ships a generic `Unknown(byte)` fallback renderer.
5. Worker passes through opaque `op_body` bytes when it doesn't recognize them.
6. Chain contract is op-kind-agnostic.
7. Canonical op_kind table in arch.md — PRs MUST append a row; numbers never reused.
8. Each PR adds 3 tests: worker CBOR roundtrip + explorer fallback render + arch.md row.

Companion issue

Explorer-side work tracked at litentry/subscan-essentials (see linked issue below once it lands).

Acceptance

• Phase B + C ship; Phase F has ≥3 op_kinds wired end-to-end (SignEip712, ScopeGrant, DeviceAdd recommended as the first three since they exercise typed-data + master mutations + registry).
• `harness/v2-stage1-demo.sh` + `v2-stage2-demo.sh` + `v2-stage3-demo.sh` all green.
• Explorer can render at least the three wired op_kinds; the others render with the `Unknown(byte)` fallback.

Related: #82 (closed by #95), #90 (Stage 2 hardening), #91 (worker hardening).

[hanwencheng]

Phase B partially landed in PR #95

Commit 7738166. What shipped:

• ✅ `agentkeys-core::audit` module — `AuditEnvelope` struct, `AuditOpKind` open-enum (18 variants), `AuditResult`, canonical CBOR codec (deterministic per RFC 8949 §4.2.1), `envelope_hash()` = keccak256(canonical_cbor), `commit_intent()` helper.
• ✅ Per-op_kind typed body schemas in `audit::bodies` for all 18 canonical op_kinds.
• ✅ Worker V2 endpoints:
  • `POST /v1/audit/append/v2` — accept envelope JSON, store canonical CBOR, return `envelope_hash`.
  • `GET /v1/audit/envelope/:hash` — return canonical CBOR (200 application/cbor) or 404.
• ✅ V1 endpoints retained so existing callers keep working through the migration cycle.
• ✅ 17 audit-module unit tests + 7 V2 worker integration tests. Cargo test --workspace clean.

What's left in Phase B (will land in follow-up PRs against this issue):

• Migrate credentials-service emit site from `/v1/audit/append` (V1) to `/v1/audit/append/v2` (V2).
• Migrate memory-service emit site to V2.
• Persistent envelope storage (S3 `audit/envelopes/.cbor`) — in-memory storage is sufficient for v0 since chain commitment is the durability mechanism.

Phase C (contract revision) and Phase F (new op_kind coverage) remain as documented above.

[hanwencheng]

Phase D — sunset legacy SQLite audit, wire real EvmAuditAnchor

Folding scope picked up while resolving codex review on PR #96 (commit 4243434 retired the mock-server audit_log table that duplicated this story dev-side). The remaining piece is at the broker.

Current state (broker, today)

Three audit write paths coexist, all SQLite-backed:

Path	Where	Status
state.audit.record_mint(...) → legacy AuditLog SQLite	crates/agentkeys-broker-server/src/audit.rs	written from /v1/mint-oidc-jwt + /v1/grant/create
state.registry.audit → SqliteAnchor (plugin_mint_log table)	plugins/audit/sqlite.rs:113	written by the multi-anchor coordinator
state.registry.audit → EvmStubAnchor	plugins/audit/evm.rs:86	STUB only — evm.rs:10: "unit-test-only fixture that simulates the EVM dependency. Production uses the eventual EvmAuditAnchor (deferred…)"

Net result: every mint writes the same row twice to local SQLite and increments an in-memory counter pretending to be a chain anchor. Zero on-chain audit on prod today.

What Phase D delivers

The Phase B/C work in this issue lands the data-plane: AuditEnvelope v1 serializer, worker /v1/audit/append v2 endpoint, CredentialAudit.appendV2 + appendRootV2. Phase D wires the broker to actually use it:

• Replace EvmStubAnchor with EvmAuditAnchor that posts to the audit-worker's new POST /v1/audit/append (envelope-shape) instead of fabricating receipts in-memory. Worker is the broker's submission endpoint, NOT direct chain RPC — keeps the broker pure-policy + lets the worker batch via appendRootV2.
• Demote SqliteAnchor to confirmation cache, not primary durability. Today's plugin_mint_log is the audit ledger; post-Phase-D it becomes a local index pointing at on-chain envelope hashes. Schema gains chain_tx_hash NOT NULL + envelope_hash NOT NULL; the row is written AFTER the chain anchor returns, not before.
• Retire state.audit (legacy AuditLog). Its only callers are /v1/mint-oidc-jwt (oidc.rs:92,115) and /v1/grant/create. Migrate them to the plugin chain (state.registry.audit) so there's one write path, not two. Delete audit.rs::AuditLog + MintRecord + MintOutcome after callers move.
• Tighten the durability invariant. plan §2 rule 7 said "no credential released unless every configured audit anchor wrote Ok" — today that's vacuously true because EvmStubAnchor.anchor() always returns Ok. Phase D makes the multi-anchor coordinator actually short-circuit on a real chain submit failure; add the regression test that proves a worker /v1/audit/append → 5xx blocks the mint response from going out.
• Operator config — gate behind BROKER_AUDIT_ANCHORS=evm_worker (vs current default sqlite,evm_testnet). One config flip, one rollback path.

Sequencing

Phase D requires Phase C contract revision (appendV2) to be deployed on Heima Mainnet first, otherwise the worker has no appendV2 selector to call into. Sequence:

1. Phase B (envelope codec + worker endpoints) ← in-flight on claude/gallant-ride-cec4d7
2. Phase C (contract appendV2 + redeploy)
3. Phase D (this comment) — real EvmAuditAnchor in broker, SQLite demoted to cache, legacy AuditLog removed
4. Phase F (op_kind expansion) — strictly orthogonal to D, can run in parallel

Why this fits inside #97 instead of its own issue

D is the load-bearing answer to "why does SQLite still exist after the on-chain story shipped?" Splitting it into a separate issue invites the same kind of multi-quarter drift that left EvmStubAnchor un-replaced for two contract redeploys. The envelope schema (B) + contract surface (C) + broker wiring (D) are the same architectural unit; treat them as one.

Acceptance

• BROKER_AUDIT_ANCHORS=evm_worker boots clean; /readyz reports tier2/audit_worker_reachable.
• Every mint flow under harness/v2-stage*-demo.sh results in a CredentialAudit.AuditAppendedV2 event on Heima Mainnet matching the local plugin_mint_log row's envelope_hash.
• worker /v1/audit/append → 5xx blocks /v1/mint-oidc-jwt from returning 200 (durability invariant regression test).
• crates/agentkeys-broker-server/src/audit.rs deleted; zero callers of state.audit remain.
• EvmStubAnchor deleted entirely (not just #[cfg(test)]-gated) — it was always a stand-in for the real thing, and once EvmAuditAnchor lands there's no test value in keeping a no-op alongside.