Add trace artifact v0 for bean-run (#2)

bean-run emits a stable post-run artifact to .bean/runs/<run_id>.json (one file per run) so
future tooling can analyze a corpus of runs without scraping transcripts.

- Fixed top-level shape (additionalProperties:false) with a documented `metadata` extension hatch.
- Fails closed: a trace-write failure exits 3 (infra error), never a false clean run.
- schemas/trace.schema.json + skills/bean/references/trace.md + conformance shape assertion.
- Ignores emitted runtime traces (**/.bean/runs/, **/.bean/verdicts-raw/); fixtures stay tracked.

Scope: emit-only. No cross-task learning, memory mutation, prompt rewriting, or optimization.

Author: aid-ninja

.gitignore

@@ -5,6 +5,8 @@ review/
 .farmer-state.json
 bean-stalk.md
 **/.bean/state.json
+**/.bean/runs/
+**/.bean/verdicts-raw/
 
 rs/target/
 /bin/bean-check

CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## Unreleased
+
+- **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`, `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 (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
 
 Adds the "pivot, don't stop" driver discipline, then hardens it: a cross-model (Codex) review

rs/src/bin/bean-run.rs

@@ -21,8 +21,10 @@
 // Exit: 0 = ready, 4 = converged-with-residuals, 2 = budget-exceeded, 5 = stuck, 3 = usage/load.
 
 use serde_json::Value;
+use std::collections::BTreeSet;
 use std::path::{Path, PathBuf};
 use std::process::{exit, Command, Stdio};
+use std::time::{SystemTime, UNIX_EPOCH};
 
 fn die(code: i32, msg: &str) -> ! {
     eprintln!("bean-run: {msg}");
@@ -146,6 +148,30 @@ fn frontier(sig: &Value) -> String {
     fronts.sort();
     format!("{status}\u{1e}{}", fronts.join("\u{1d}"))
 }
+
+// the open-front keys (code:claim) in a compiler signal — used for trace blockers_opened/closed.
+fn blocker_keys(sig: &Value) -> Vec<String> {
+    sig.get("blockers")
+        .and_then(|v| v.as_array())
+        .map(|a| {
+            a.iter()
+                .map(|bl| {
+                    format!(
+                        "{}:{}",
+                        bl.get("code").and_then(|v| v.as_str()).unwrap_or(""),
+                        bl.get("claim").and_then(|v| v.as_str()).unwrap_or("")
+                    )
+                })
+                .collect()
+        })
+        .unwrap_or_default()
+}
+
+fn epoch_ms(t: SystemTime) -> u64 {
+    t.duration_since(UNIX_EPOCH)
+        .map(|d| d.as_millis() as u64)
+        .unwrap_or(0)
+}
 fn is_active(c: &Value) -> bool {
     let st = c.get("status").and_then(|v| v.as_str()).unwrap_or("");
     st != "superseded" && st != "rejected" && st != "resolved"
@@ -309,6 +335,17 @@ fn main() {
     // a different front/approach) before declaring a true "stuck" stop. ALLOWED_PIVOTS=2 means
     // two no-progress rounds are turned into pivots; a third with still no progress is "stuck".
     const ALLOWED_PIVOTS: i32 = 2;
+    // trace artifact v0: stamp the run boundary + accumulate the set of open fronts ever seen.
+    let run_start = SystemTime::now();
+    let started_at = epoch_ms(run_start);
+    let run_id = format!(
+        "run-{}",
+        run_start
+            .duration_since(UNIX_EPOCH)
+            .map(|d| d.as_nanos() as u64)
+            .unwrap_or(0)
+    );
+    let mut blockers_seen: BTreeSet<String> = BTreeSet::new();
     let mut trace: Vec<Value> = vec![];
     // Natural max-rounds exhaustion is the hard round ceiling (budget-exceeded, exit 2), NOT
     // "stuck": bean-check runs with --no-state here, so it never emits budget-exceeded itself —
@@ -326,6 +363,9 @@ fn main() {
             .unwrap_or("")
             .to_string();
         let front = frontier(&sig);
+        for k in blocker_keys(&sig) {
+            blockers_seen.insert(k);
+        }
         let has_blockers = sig
             .get("blockers")
             .and_then(|v| v.as_array())
@@ -383,6 +423,98 @@ fn main() {
     }
 
     let final_sig = compile();
+
+    // ---- trace artifact v0 ----------------------------------------------------------------
+    // Leave behind a stable, useful post-run record so future tooling can analyze runs without
+    // scraping transcripts. This does NOT make bean learn across tasks; it only emits the trace.
+    // One file per run (.bean/runs/<run_id>.json) — cross-task analysis needs accumulated runs.
+    let final_blockers: BTreeSet<String> = blocker_keys(&final_sig).into_iter().collect();
+    let blockers_closed = blockers_seen
+        .iter()
+        .filter(|k| !final_blockers.contains(*k))
+        .count();
+    let pivot_count = trace
+        .iter()
+        .filter(|t| t.get("pivot").and_then(|v| v.as_bool()).unwrap_or(false))
+        .count();
+    let final_claims = read_claims(&bean_dir);
+    let residuals: Vec<Value> = final_claims
+        .iter()
+        .filter(|c| {
+            c.get("tags")
+                .and_then(|v| v.as_array())
+                .map(|a| a.iter().any(|t| t.as_str() == Some("residual")))
+                .unwrap_or(false)
+        })
+        .map(|c| {
+            serde_json::json!({
+                "id": c.get("id").and_then(|v| v.as_str()).unwrap_or(""),
+                "reason": c.get("content").and_then(|v| v.as_str()).unwrap_or(""),
+            })
+        })
+        .collect();
+    let mut verifier_verdicts: Vec<Value> = vec![];
+    if let Ok(rd) = std::fs::read_dir(bean_dir.join("verdicts")) {
+        let mut paths: Vec<PathBuf> = rd
+            .flatten()
+            .map(|e| e.path())
+            .filter(|p| p.extension().map(|x| x == "json").unwrap_or(false))
+            .collect();
+        paths.sort();
+        for p in paths {
+            if let Some(v) = load_value(&p) {
+                verifier_verdicts.push(v);
+            }
+        }
+    }
+    let trace_artifact = serde_json::json!({
+        "schema_version": "trace/v0",
+        "run_id": run_id,
+        "goal": goal,
+        "started_at": started_at,
+        "ended_at": epoch_ms(SystemTime::now()),
+        "status": outcome,
+        "certificate": final_sig.get("certificate").and_then(|v| v.as_str()).unwrap_or(""),
+        "rounds": trace.len(),
+        "pivot_count": pivot_count,
+        "blockers_opened": blockers_seen.len(),
+        "blockers_closed": blockers_closed,
+        "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 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,
         "rounds": trace.len(),

schemas/trace.schema.json

@@ -0,0 +1,99 @@
+{
+	"$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. The top-level shape is FIXED: unknown top-level keys are rejected; additive/experimental fields go under `metadata`.",
+	"type": "object",
+	"required": [
+		"schema_version",
+		"run_id",
+		"goal",
+		"started_at",
+		"ended_at",
+		"status",
+		"certificate",
+		"rounds",
+		"pivot_count",
+		"blockers_opened",
+		"blockers_closed",
+		"verifier_verdicts",
+		"residuals",
+		"artifacts_changed"
+	],
+	"additionalProperties": false,
+	"properties": {
+		"schema_version": { "const": "trace/v0" },
+		"run_id": {
+			"type": "string",
+			"description": "Unique per run, e.g. run-<nanos-since-epoch>."
+		},
+		"goal": {
+			"type": "string",
+			"description": "The run goal (from run.json), or a placeholder."
+		},
+		"started_at": {
+			"type": "integer",
+			"description": "Run start, milliseconds since the Unix epoch."
+		},
+		"ended_at": {
+			"type": "integer",
+			"description": "Run end, milliseconds since the Unix epoch."
+		},
+		"status": {
+			"type": "string",
+			"enum": ["ready", "converged-with-residuals", "budget-exceeded", "stuck"],
+			"description": "Final run outcome."
+		},
+		"certificate": {
+			"type": "string",
+			"description": "Final convergence certificate from bean-check."
+		},
+		"rounds": {
+			"type": "integer",
+			"minimum": 0,
+			"description": "Number of driver rounds executed."
+		},
+		"pivot_count": {
+			"type": "integer",
+			"minimum": 0,
+			"description": "No-progress rounds turned into pivots."
+		},
+		"blockers_opened": {
+			"type": "integer",
+			"minimum": 0,
+			"description": "Distinct open fronts (code:claim) seen across the run."
+		},
+		"blockers_closed": {
+			"type": "integer",
+			"minimum": 0,
+			"description": "Of those, the count not present in the final signal."
+		},
+		"verifier_verdicts": {
+			"type": "array",
+			"description": "The scrubbed verdicts bean-verify deposited under .bean/verdicts/, embedded verbatim.",
+			"items": { "type": "object" }
+		},
+		"residuals": {
+			"type": "array",
+			"description": "Claims tagged residual, with their stated reason (the claim content).",
+			"items": {
+				"type": "object",
+				"required": ["id", "reason"],
+				"properties": {
+					"id": { "type": "string" },
+					"reason": { "type": "string" }
+				}
+			}
+		},
+		"artifacts_changed": {
+			"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

@@ -0,0 +1,53 @@
+# Reference: trace artifact (v0)
+
+Every `bean-run` writes a stable post-run record to **`.bean/runs/<run_id>.json`**. The point is
+to leave behind something a future tool (or a person) can analyze _after_ the run, without
+re-reading the transcript.
+
+> **Scope note (read this).** This artifact does NOT make bean learn across tasks. It only emits
+> a stable trace/certificate so future tooling can analyze runs. No automatic learning, memory
+> mutation, prompt rewriting, or cross-run optimization is part of v0.
+
+One file **per run** (not a single rolling `trace.json`) on purpose: cross-task analysis needs an
+accumulated corpus of runs. Summarizing many runs into memory is a later, separate step — don't
+start there.
+
+## Shape
+
+Schema: [`schemas/trace.schema.json`](../../../schemas/trace.schema.json) (`schema_version: "trace/v0"`).
+
+| Field                     | Meaning                                                                            |
+| ------------------------- | ---------------------------------------------------------------------------------- |
+| `schema_version`          | `"trace/v0"` — bump on any breaking shape change.                                  |
+| `run_id`                  | Unique per run (`run-<nanos-since-epoch>`); also the filename stem.                |
+| `goal`                    | The run goal from `run.json`.                                                      |
+| `started_at` / `ended_at` | Unix epoch milliseconds.                                                           |
+| `status`                  | Final outcome: `ready` / `converged-with-residuals` / `budget-exceeded` / `stuck`. |
+| `certificate`             | Final convergence certificate from `bean-check`.                                   |
+| `rounds`                  | Driver rounds executed.                                                            |
+| `pivot_count`             | No-progress rounds turned into pivots.                                             |
+| `blockers_opened`         | Distinct open fronts (`code:claim`) seen across the run.                           |
+| `blockers_closed`         | Of those, how many are absent from the final signal.                               |
+| `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)
+
+A future hill-climbing loop would read accumulated `runs/*.json` to cluster recurring failure
+modes and propose harness improvements. v0 deliberately stops at "stable, useful artifact" so
+that future work has a fixed format to build on.