trace v0: address review — strict shape, metadata hatch, fail-closed write

- Schema top-level is now additionalProperties:false (unknown keys rejected, catches drift);
  additive/experimental fields go under a documented `metadata` object hatch (emitted as {}).
- bean-run fails CLOSED on a trace-write failure: prints the outcome to stderr and exits 3
  (infra/load error, distinct from any convergence outcome) instead of reporting a clean run.
- Conformance asserts metadata present + no unknown top-level keys; docs note the stability
  rules and that sample-trace fixtures belong in test/fixtures/traces/, never under the ignored
  .bean/runs/.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: aid-ninja

CHANGELOG.md

@@ -5,11 +5,14 @@
 - **Trace artifact v0 (emit-only).** Every `bean-run` now writes a stable post-run record to
   `.bean/runs/<run_id>.json`: `schema_version`, `run_id`, `goal`, `started_at`/`ended_at`,
   `status`, `certificate`, `rounds`, `pivot_count`, `blockers_opened`/`blockers_closed`,
-  `verifier_verdicts`, `residuals`, `artifacts_changed`. One file per run (not a rolling file),
-  so future tooling can analyze a corpus of runs without scraping transcripts. Schema:
+  `verifier_verdicts`, `residuals`, `artifacts_changed`, `metadata`. One file per run (not a
+  rolling file), so future tooling can analyze a corpus of runs without scraping transcripts.
+  The top-level shape is **fixed** (`additionalProperties: false`); additive fields go under the
+  `metadata` hatch. Emission **fails closed**: if the trace can't be written, `bean-run` exits
+  with the infra error code (`3`) rather than reporting a clean run. Schema:
   `schemas/trace.schema.json`; docs: `skills/bean/references/trace.md`; conformance asserts the
-  shape is stable. **Scope:** this does NOT make bean learn across tasks — no memory mutation,
-  prompt rewriting, or cross-run optimization. It only emits the artifact.
+  shape is stable (required keys, no unknown top-level keys). **Scope:** this does NOT make bean
+  learn across tasks — no memory mutation, prompt rewriting, or cross-run optimization.
 
 ## 2.0.2 — driver "pivot, don't stop" + review hardening
 

rs/src/bin/bean-run.rs

@@ -482,13 +482,38 @@ fn main() {
         "verifier_verdicts": verifier_verdicts,
         "residuals": residuals,
         "artifacts_changed": Vec::<String>::new(),
+        // documented extension hatch: additive/experimental fields go HERE, so the top-level
+        // shape stays fixed (the schema rejects unknown top-level keys).
+        "metadata": serde_json::Map::new(),
     });
+    // Fail CLOSED on a trace-write failure: the trace is part of bean-run's contract, so we must
+    // not report a clean exit (0/2/4) if we couldn't persist it. Surface the outcome on stderr,
+    // then exit with the infra/load error code (3) — distinct from any convergence outcome.
     let runs_dir = bean_dir.join("runs");
-    let _ = std::fs::create_dir_all(&runs_dir);
-    let _ = std::fs::write(
-        runs_dir.join(format!("{run_id}.json")),
-        serde_json::to_string_pretty(&trace_artifact).unwrap() + "\n",
-    );
+    let trace_path = runs_dir.join(format!("{run_id}.json"));
+    let wrote = std::fs::create_dir_all(&runs_dir).and_then(|_| {
+        std::fs::write(
+            &trace_path,
+            serde_json::to_string_pretty(&trace_artifact).unwrap() + "\n",
+        )
+    });
+    if let Err(e) = wrote {
+        eprintln!(
+            "bean-run: run outcome was {} (cert {}) but the trace could not be persisted",
+            outcome,
+            final_sig
+                .get("certificate")
+                .and_then(|v| v.as_str())
+                .unwrap_or("")
+        );
+        die(
+            3,
+            &format!(
+                "could not write trace artifact {}: {e} — failing closed",
+                trace_path.display()
+            ),
+        );
+    }
 
     let report = serde_json::json!({
         "outcome": outcome,

schemas/trace.schema.json

@@ -2,7 +2,7 @@
 	"$schema": "http://json-schema.org/draft-07/schema#",
 	"$id": "https://github.com/grainulation/bean/schemas/trace.schema.json",
 	"title": "bean run trace artifact (v0)",
-	"description": "Stable post-run record emitted by bean-run to .bean/runs/<run_id>.json. v0 is an EMIT-ONLY artifact: it lets future tooling analyze runs without scraping transcripts. It does NOT make bean learn across tasks — no memory mutation, prompt rewriting, or cross-run optimization.",
+	"description": "Stable post-run record emitted by bean-run to .bean/runs/<run_id>.json. v0 is an EMIT-ONLY artifact: it lets future tooling analyze runs without scraping transcripts. It does NOT make bean learn across tasks — no memory mutation, prompt rewriting, or cross-run optimization. The top-level shape is FIXED: unknown top-level keys are rejected; additive/experimental fields go under `metadata`.",
 	"type": "object",
 	"required": [
 		"schema_version",
@@ -20,7 +20,7 @@
 		"residuals",
 		"artifacts_changed"
 	],
-	"additionalProperties": true,
+	"additionalProperties": false,
 	"properties": {
 		"schema_version": { "const": "trace/v0" },
 		"run_id": {
@@ -89,6 +89,11 @@
 			"type": "array",
 			"description": "Files the run changed, when available. v0 does not track this yet; emitted as [] for shape stability.",
 			"items": { "type": "string" }
+		},
+		"metadata": {
+			"type": "object",
+			"additionalProperties": true,
+			"description": "Documented extension hatch. The top-level shape is fixed; additive or experimental fields go here so adding them never breaks v0 validation. Emitted as {} by default."
 		}
 	}
 }

skills/bean/references/trace.md

@@ -31,6 +31,20 @@ Schema: [`schemas/trace.schema.json`](../../../schemas/trace.schema.json) (`sche
 | `verifier_verdicts`       | The scrubbed verdicts from `.bean/verdicts/`, embedded verbatim.                   |
 | `residuals`               | Claims tagged `residual`, each `{id, reason}` (reason = the claim content).        |
 | `artifacts_changed`       | Files the run changed, when available. v0 does not track this yet → `[]`.          |
+| `metadata`                | Extension hatch (`{}` by default). Additive/experimental fields go here.           |
+
+## Stability rules
+
+- **The top-level shape is fixed.** The schema is `additionalProperties: false` — unknown
+  top-level keys are rejected. This catches drift and typos. Any new field goes under
+  `metadata` (the documented hatch), so adding it never breaks v0 validation. A breaking change
+  to the fixed keys bumps `schema_version`.
+- **Emission fails closed.** If `bean-run` cannot persist the trace, it does NOT report a clean
+  exit. It prints the run outcome to stderr and exits with the infra/load error code (`3`),
+  distinct from any convergence outcome — the trace is part of the run's contract.
+- **Emitted traces are runtime artifacts, not source.** `**/.bean/runs/` (and
+  `**/.bean/verdicts-raw/`) are gitignored. Do not commit emitted traces. Sample traces needed
+  by tests live under `test/fixtures/traces/`, never under a `.bean/runs/` path (which is ignored).
 
 ## What consumes it (later, not now)
 

test/conformance.mjs

@@ -321,7 +321,9 @@ console.log(`${dpass}/3 driver smoke checks pass`);
 	const files = fs.existsSync(runsDir)
 		? fs.readdirSync(runsDir).filter((f) => f.endsWith(".json"))
 		: [];
-	const REQUIRED = [
+	// ALLOWED == the fixed top-level shape. metadata is the only extension hatch; any OTHER
+	// unknown top-level key is drift and must fail (matches schema additionalProperties:false).
+	const ALLOWED = [
 		"schema_version",
 		"run_id",
 		"goal",
@@ -336,24 +338,29 @@ console.log(`${dpass}/3 driver smoke checks pass`);
 		"verifier_verdicts",
 		"residuals",
 		"artifacts_changed",
+		"metadata",
 	];
 	let ok = files.length === 1;
 	let why = ok ? "" : `expected 1 trace file, got ${files.length}`;
 	if (ok) {
 		const t = JSON.parse(fs.readFileSync(path.join(runsDir, files[0]), "utf8"));
-		const missing = REQUIRED.filter((k) => !(k in t));
+		const missing = ALLOWED.filter((k) => !(k in t));
+		const unknown = Object.keys(t).filter((k) => !ALLOWED.includes(k));
 		const shapeOk =
 			t.schema_version === "trace/v0" &&
 			missing.length === 0 &&
+			unknown.length === 0 &&
 			files[0] === `${t.run_id}.json` &&
 			t.status === report.outcome &&
 			Array.isArray(t.verifier_verdicts) &&
 			Array.isArray(t.residuals) &&
-			Array.isArray(t.artifacts_changed);
+			Array.isArray(t.artifacts_changed) &&
+			typeof t.metadata === "object" &&
+			!Array.isArray(t.metadata);
 		ok = shapeOk;
 		why = shapeOk
 			? ""
-			: `schema_version=${t.schema_version} missing=[${missing}] status=${t.status} vs ${report.outcome}`;
+			: `schema_version=${t.schema_version} missing=[${missing}] unknown=[${unknown}] status=${t.status} vs ${report.outcome}`;
 	}
 	if (ok) {
 		console.log("  ok    trace artifact v0 written with stable shape");