Draft PRD for a unified, versioned audit-event envelope with a
trusted/untrusted field split, canonical JSON + per-writer hash chain,
an append-only JSONL journal as source of truth, a rebuildable SQLite
index for local query, and an initial event registry. Scheduled to land
immediately after the host controller (#468), which becomes its first
producer.

Refs #487

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

@@ -0,0 +125,4 @@
+  "type": "egress.decision",       // dotted event type from the registry
+  "seq": 1287,                     // per-writer monotonic sequence (gap-detectable)
+  "ts": {
+    "wall": "2026-07-26T18:22:04.113Z",  // host wall-clock, RFC3339 UTC (TRUSTED)

@@ -0,0 +126,4 @@
+  "seq": 1287,                     // per-writer monotonic sequence (gap-detectable)
+  "ts": {
+    "wall": "2026-07-26T18:22:04.113Z",  // host wall-clock, RFC3339 UTC (TRUSTED)
+    "mono": 90142.55                      // host monotonic seconds since writer start (ordering)

@@ -0,0 +130,4 @@
+  },
+  "producer": "host-controller",   // TRUSTED: which host component wrote this
+  "trusted": {                     // host-supplied, authoritative
+    "bottle": "amber-fox-12",      // slug from source-IP attribution (may be null for host-level events)

@@ -0,0 +197,4 @@
+required `untrusted` keys so producers and the verifier agree on shape:
+
+- **lifecycle.*** — `lifecycle.bottle_start`, `lifecycle.bottle_stop`,
+  `lifecycle.bottle_crash` (producer: host-controller, #468).

@@ -0,0 +215,4 @@
+
+The envelope constructor enforces a deny-list at write time: a field whose
+key matches known credential shapes (`token`, `secret`, `password`,
+`authorization`, `*_key`, JWT-shaped values) is rejected — the producer

@@ -0,0 +247,4 @@
+  being up. Alternative: one chain *per producer* (independent `seq`/chain
+  head), merged at query time by `(wall, mono)`. Leaning single-writer for
+  v1 (simpler verification, matches the host controller owning lifecycle),
+  with per-producer chains noted as the scaling path. — feedback wanted.

@@ -0,0 +259,4 @@
+  flag, so a producer bug can't drop an event entirely in the field.
+- **Retention interaction with the chain.** When an old journal segment is
+  rotated out, the verifier must still trust the current head. Carry the
+  rotated-out head as the new segment's genesis `prev`? (Tracked with the

@@ -0,0 +197,4 @@
+which is acceptable because the host controller already gates every
+lifecycle transition; per-producer chains are noted only as a future
+scaling path, not built now.
+

@@ -0,0 +247,4 @@
+  `forge.pr_opened`.
+
+New types are additive; adding one does not bump `v`. Removing or
+re-typing a field bumps `v`.

@@ -0,0 +259,4 @@
+   `*_key`) is refused — the producer must pass a reference (a token *id*
+   or `sha256` fingerprint), never the raw value. `auth.token_minted`
+   therefore records the token id and role, not the JWT. This is the
+   primary guard: it is cheap, deterministic, and catches the intended

@@ -0,0 +215,4 @@
+
+### Journal (source of truth) + SQLite index (rebuildable)
+
+- **Journal:** one append-only JSONL file per host (path from `paths.py`,

@@ -0,0 +126,4 @@
+
+  // --- chain / ordering (structural, host-owned) ---
+  "epoch": 7,                      // writer-boot counter, bumped once per host-controller (writer) start
+  "seq": 1287,                     // monotonic sequence within this epoch (gap-detectable)

@@ -0,0 +130,4 @@
+  "prev": "<hex>",                 // hash of the previous record in the chain ("" for genesis)
+  "hash": "<hex>",                 // sha256(prev + canonical(this event with hash=""))
+
+  // --- trusted: everything the *host* established; authoritative ---

@@ -0,0 +125,4 @@
+  "type": "egress.decision",       // dotted event type from the registry
+
+  // --- chain / ordering (structural, host-owned) ---
+  "epoch": 7,                      // writer-boot counter, bumped once per host-controller (writer) start

@@ -0,0 +125,4 @@
+stable top level:
+
+```
+{