rad-experiment 0.1.0

package/README.md

@@ -0,0 +1,87 @@
+# rad-experiment (TypeScript)
+
+A TypeScript implementation of the `rad-experiment` CLI and Radicle COB helper for AI-generated optimization experiments. Drop-in replacement for the Rust `rad-experiment` crate — produces byte-identical COBs and is fully cross-compatible.
+
+## Architecture
+
+The implementation provides two binaries that plug into Radicle's external COB system:
+
+```
+rad-experiment publish ...
+        │
+        ▼
+   rad cob create ──stdin──▶ rad-cob-experiment ──stdout──▶ new state
+        │                    (external COB helper)
+        ▼
+   git refs/cobs/cc.experiment/<oid>
+```
+
+### `rad-cob-experiment` — External COB helper
+
+Radicle's [external COB protocol](https://radicle.xyz) delegates state evaluation to a helper binary named `rad-cob-{type}`. When any `rad cob` command operates on a `cc.experiment` COB, Radicle spawns `rad-cob-experiment` and communicates via JSON Lines on stdin/stdout:
+
+1. Radicle sends `{ value, op, concurrent }` on stdin
+2. Helper applies the operation to the current state
+3. Helper writes the new state as a JSON Line to stdout
+4. Repeat for each operation, then exit 0
+
+This is the only binary that Radicle itself invokes. It has no CLI flags.
+
+### `rad-experiment` — User-facing CLI
+
+Thin wrapper that shells out to `rad cob create/update/list/show`. All COB storage, signing, and replication are handled by Radicle — this CLI just constructs the right action JSON and formats output.
+
+**Commands:**
+
+| Command            | What it does                                                           |
+|--------------------|------------------------------------------------------------------------|
+| `publish`          | Create a new experiment COB with benchmark results                     |
+| `list`             | List all experiments (optional `--reproduced`/`--unverified` filters)  |
+| `show <id>`        | Display experiment details (text or `--json`)                          |
+| `reproduce <id>`   | Add an independent verification to an experiment                       |
+
+## Source files
+
+```
+src/
+├── rad-experiment.ts        CLI entry point — arg routing and dispatch
+├── rad-cob-experiment.ts    COB helper entry point — stdin/stdout JSON Lines protocol
+├── types.ts                 Shared type definitions (Experiment, Action, Op, etc.)
+├── cob/                     COB domain logic (used by both entry points)
+│   ├── actions.ts           Builds Publish/Reproduce action JSON
+│   └── state.ts             Replays actions into Experiment state
+└── cli/                     Everything specific to the rad-experiment CLI
+    ├── helpers.ts            Arg parsing helpers (die, requireArg, buildMeasurement, etc.)
+    ├── format.ts             Display formatting (deltaDisplay, measurementDisplay, etc.)
+    ├── rad.ts                Wrappers around rad CLI commands (cobCreate, cobShow, etc.)
+    └── commands/
+        ├── publish.ts        rad-experiment publish
+        ├── list.ts           rad-experiment list
+        ├── show.ts           rad-experiment show
+        └── reproduce.ts      rad-experiment reproduce
+```
+
+## Field naming conventions
+
+The Rust serde serialization produces mixed naming that this implementation matches exactly:
+
+| Layer                                   | Convention  | Example                          |
+|-----------------------------------------|-------------|----------------------------------|
+| **Action fields** (stored in COB)       | snake_case  | `metric_name` , `delta_pct_x100` |
+| **Measurement fields** (nested struct)  | camelCase   | `medianX1000`, `stdX1000`        |
+| **Experiment state** (helper output)    | camelCase   | `metricName`, `deltaPctX100`     |
+
+The helper accepts both conventions when reading actions for backward compatibility.
+
+## Build and install
+
+```sh
+npm install
+npm run build
+
+# Symlink both binaries onto PATH
+ln -s "$(pwd)/dist/rad-experiment.js" ~/.local/bin/rad-experiment
+ln -s "$(pwd)/dist/rad-cob-experiment.js" ~/.local/bin/rad-cob-experiment
+```
+
+Both binaries must be on `$PATH`. Radicle finds `rad-cob-experiment` by name.

package/dist/cli/commands/list.d.ts

@@ -0,0 +1 @@
+export declare function cmdList(args: string[]): void;

package/dist/cli/commands/list.js

@@ -0,0 +1,35 @@
+import { parseArgs } from "node:util";
+import { deltaDisplay, shortId, confirmedCount } from "../format.js";
+import { getRepoId, cobList, cobShow } from "../rad.js";
+export function cmdList(args) {
+    const { values } = parseArgs({
+        args,
+        options: {
+            repo: { type: "string", short: "r" },
+            reproduced: { type: "boolean", default: false },
+            unverified: { type: "boolean", default: false },
+        },
+        strict: true,
+    });
+    const rid = getRepoId(values.repo);
+    const ids = cobList(rid);
+    const experiments = [];
+    for (const id of ids) {
+        experiments.push({ id, exp: cobShow(rid, id) });
+    }
+    experiments.sort((a, b) => b.exp.createdAt - a.exp.createdAt);
+    let count = 0;
+    for (const { id, exp } of experiments) {
+        const reproCount = confirmedCount(exp);
+        if (values.reproduced && reproCount === 0)
+            continue;
+        if (values.unverified && reproCount > 0)
+            continue;
+        count++;
+        const reproLabel = reproCount > 0 ? ` [${reproCount} verified]` : "";
+        console.log(`${shortId(id)} ${exp.metricName} ${deltaDisplay(exp.deltaPctX100)}${reproLabel}`);
+    }
+    if (count === 0) {
+        console.log("No experiments found.");
+    }
+}

package/dist/cli/commands/publish.d.ts

@@ -0,0 +1 @@
+export declare function cmdPublish(args: string[]): void;

package/dist/cli/commands/publish.js

@@ -0,0 +1,63 @@
+import { parseArgs } from "node:util";
+import { buildPublishAction } from "../../cob/actions.js";
+import { MEASUREMENT_OPTIONS, buildMeasurement, parseSecondary, requireArg, requireInt } from "../helpers.js";
+import { deltaDisplay, measurementDisplay } from "../format.js";
+import { getRepoId, cobCreate } from "../rad.js";
+export function cmdPublish(args) {
+    const { values } = parseArgs({
+        args,
+        options: {
+            repo: { type: "string", short: "r" },
+            description: { type: "string", short: "d" },
+            base: { type: "string" },
+            head: { type: "string" },
+            metric: { type: "string" },
+            unit: { type: "string" },
+            direction: { type: "string" },
+            runner: { type: "string" },
+            ...MEASUREMENT_OPTIONS,
+            secondary: { type: "string", multiple: true, default: [] },
+            "agent-system": { type: "string", default: "claude-code" },
+            "agent-model": { type: "string", default: "claude-opus-4-6" },
+            os: { type: "string", default: "" },
+            cpu: { type: "string", default: "" },
+        },
+        strict: true,
+    });
+    const rid = getRepoId(values.repo);
+    const base = requireArg(values, "base");
+    const head = requireArg(values, "head");
+    const metric = requireArg(values, "metric");
+    const unit = requireArg(values, "unit");
+    const direction = requireArg(values, "direction");
+    const runner = requireArg(values, "runner");
+    const delta = requireInt(values, "delta");
+    const baseline = buildMeasurement(values, "baseline");
+    const candidate = buildMeasurement(values, "candidate");
+    const secondaryMetrics = (values.secondary ?? []).map(parseSecondary);
+    const action = buildPublishAction({
+        description: values.description ?? undefined,
+        base,
+        oid: head,
+        metricName: metric,
+        metricUnit: unit,
+        direction,
+        runnerClass: runner,
+        os: values.os ?? "",
+        cpu: values.cpu ?? "",
+        baseline,
+        candidate,
+        deltaPctX100: delta,
+        buildOk: true,
+        testsOk: true,
+        sanitizersOk: false,
+        agentSystem: values["agent-system"] ?? "claude-code",
+        agentModel: values["agent-model"] ?? "claude-opus-4-6",
+        secondaryMetrics,
+    });
+    const objectId = cobCreate(rid, [action], "Publish experiment");
+    console.log(`Experiment published: ${objectId}`);
+    console.log(`  metric:    ${metric} ${deltaDisplay(delta)}`);
+    console.log(`  baseline:  ${measurementDisplay(baseline, unit)}`);
+    console.log(`  candidate: ${measurementDisplay(candidate, unit)}`);
+}

package/dist/cli/commands/reproduce.d.ts

@@ -0,0 +1 @@
+export declare function cmdReproduce(args: string[]): void;

package/dist/cli/commands/reproduce.js

@@ -0,0 +1,45 @@
+import { parseArgs } from "node:util";
+import { buildReproduceAction } from "../../cob/actions.js";
+import { MEASUREMENT_OPTIONS, VERDICTS, buildMeasurement, die, requireArg, requireInt } from "../helpers.js";
+import { shortId } from "../format.js";
+import { getRepoId, cobUpdate } from "../rad.js";
+export function cmdReproduce(args) {
+    const { values, positionals } = parseArgs({
+        args,
+        options: {
+            repo: { type: "string", short: "r" },
+            verdict: { type: "string" },
+            runner: { type: "string" },
+            ...MEASUREMENT_OPTIONS,
+            notes: { type: "string" },
+        },
+        allowPositionals: true,
+        strict: true,
+    });
+    if (positionals.length === 0)
+        die("missing experiment ID");
+    const id = positionals[0];
+    const rid = getRepoId(values.repo);
+    const verdictStr = requireArg(values, "verdict").toLowerCase();
+    if (!VERDICTS.includes(verdictStr)) {
+        die(`Invalid verdict: unknown verdict: ${verdictStr}`);
+    }
+    const verdict = verdictStr;
+    const runner = requireArg(values, "runner");
+    const delta = requireInt(values, "delta");
+    const baseline = buildMeasurement(values, "baseline");
+    const candidate = buildMeasurement(values, "candidate");
+    const action = buildReproduceAction({
+        verdict,
+        runnerClass: runner,
+        baseline,
+        candidate,
+        deltaPctX100: delta,
+        buildOk: true,
+        testsOk: true,
+        notes: values.notes ?? undefined,
+    });
+    cobUpdate(rid, id, [action], "Reproduce");
+    console.log(`Reproduction added to ${shortId(id)}`);
+    console.log(`  verdict: ${verdict}`);
+}

package/dist/cli/commands/show.d.ts

@@ -0,0 +1 @@
+export declare function cmdShow(args: string[]): void;

package/dist/cli/commands/show.js

@@ -0,0 +1,61 @@
+import { parseArgs } from "node:util";
+import { die } from "../helpers.js";
+import { deltaDisplay, measurementDisplay } from "../format.js";
+import { getRepoId, cobShow } from "../rad.js";
+export function cmdShow(args) {
+    const { values, positionals } = parseArgs({
+        args,
+        options: {
+            repo: { type: "string", short: "r" },
+            json: { type: "boolean", default: false },
+        },
+        allowPositionals: true,
+        strict: true,
+    });
+    if (positionals.length === 0)
+        die("missing experiment ID");
+    const id = positionals[0];
+    const rid = getRepoId(values.repo);
+    let exp;
+    try {
+        exp = cobShow(rid, id);
+    }
+    catch {
+        die(`Experiment not found: ${id}`);
+    }
+    if (values.json) {
+        console.log(JSON.stringify(exp, null, 2));
+    }
+    else {
+        console.log(`Experiment ${id}`);
+        if (exp.description) {
+            console.log();
+            console.log(`  ${exp.description}`);
+        }
+        console.log();
+        console.log(`  base:         ${exp.base}`);
+        console.log(`  head:         ${exp.oid}`);
+        console.log();
+        console.log(`  metric:       ${exp.metricName} (${exp.metricUnit})`);
+        console.log(`  direction:    ${exp.direction}`);
+        console.log();
+        console.log(`  baseline:     ${measurementDisplay(exp.baseline, exp.metricUnit)} (n=${exp.baseline.n})`);
+        console.log(`  candidate:    ${measurementDisplay(exp.candidate, exp.metricUnit)} (n=${exp.candidate.n})`);
+        console.log(`  delta:        ${deltaDisplay(exp.deltaPctX100)}`);
+        console.log();
+        console.log(`  runner:       ${exp.runnerClass} (${exp.os}, ${exp.cpu})`);
+        console.log(`  build:        ${exp.buildOk ? "ok" : "FAIL"}`);
+        console.log(`  tests:        ${exp.testsOk ? "ok" : "FAIL"}`);
+        console.log(`  agent:        ${exp.agentSystem}/${exp.agentModel}`);
+        console.log(`  author:       ${exp.author.id}`);
+        if (exp.reproductions && exp.reproductions.length > 0) {
+            console.log();
+            console.log(`  Reproductions (${exp.reproductions.length}):`);
+            for (const r of exp.reproductions) {
+                const sign = r.deltaPctX100 >= 0 ? "+" : "";
+                const abs = Math.abs(r.deltaPctX100 % 100);
+                console.log(`    ${r.verdict} by ${r.author.id} on ${r.runnerClass} (${sign}${Math.trunc(r.deltaPctX100 / 100)}.${String(abs).padStart(2, "0")}%)`);
+            }
+        }
+    }
+}

package/dist/cli/format.d.ts

@@ -0,0 +1,9 @@
+import type { Experiment, Measurement } from "../types.js";
+/** Format delta as "+5.47%" or "-0.78%". */
+export declare function deltaDisplay(deltaPctX100: number): string;
+/** Format measurement as "59.340 ms". */
+export declare function measurementDisplay(m: Measurement, unit: string): string;
+/** First 7 chars of an ID. */
+export declare function shortId(id: string): string;
+/** Confirmed reproduction count. */
+export declare function confirmedCount(exp: Experiment): number;

package/dist/cli/format.js

@@ -0,0 +1,21 @@
+// Display formatting helpers — mirrors the Rust Display impls.
+/** Format delta as "+5.47%" or "-0.78%". */
+export function deltaDisplay(deltaPctX100) {
+    const abs = Math.abs(deltaPctX100);
+    const sign = deltaPctX100 >= 0 ? "+" : "-";
+    return `${sign}${Math.floor(abs / 100)}.${String(abs % 100).padStart(2, "0")}%`;
+}
+/** Format measurement as "59.340 ms". */
+export function measurementDisplay(m, unit) {
+    const whole = Math.floor(m.medianX1000 / 1000);
+    const frac = Math.abs(m.medianX1000 % 1000);
+    return `${whole}.${frac} ${unit}`;
+}
+/** First 7 chars of an ID. */
+export function shortId(id) {
+    return id.substring(0, 7);
+}
+/** Confirmed reproduction count. */
+export function confirmedCount(exp) {
+    return exp.reproductions.filter((r) => r.verdict === "confirmed").length;
+}

package/dist/cli/helpers.d.ts

@@ -0,0 +1,49 @@
+import type { Measurement, MetricValue, Verdict } from "../types.js";
+export declare const VERDICTS: Verdict[];
+export declare const MEASUREMENT_OPTIONS: {
+    "baseline-median": {
+        type: "string";
+    };
+    "baseline-std": {
+        type: "string";
+        default: string;
+    };
+    "baseline-samples": {
+        type: "string";
+        default: string;
+    };
+    "baseline-n": {
+        type: "string";
+    };
+    "candidate-median": {
+        type: "string";
+    };
+    "candidate-std": {
+        type: "string";
+        default: string;
+    };
+    "candidate-samples": {
+        type: "string";
+        default: string;
+    };
+    "candidate-n": {
+        type: "string";
+    };
+    delta: {
+        type: "string";
+    };
+};
+/** Error thrown by die() — caught at the CLI entry point. */
+export declare class CliError extends Error {
+    constructor(message: string);
+}
+export declare function die(msg: string): never;
+export declare function requireArg(values: Record<string, unknown>, name: string): string;
+export declare function requireInt(values: Record<string, unknown>, name: string): number;
+export declare function optionalInt(values: Record<string, unknown>, name: string, defaultVal: number): number;
+export declare function buildMeasurement(values: Record<string, unknown>, prefix: "baseline" | "candidate"): Measurement;
+/**
+ * Parse "name:unit:baseline_x1000:candidate_x1000:delta_x100[:regressed]"
+ * Mirrors parse_secondary in the Rust CLI.
+ */
+export declare function parseSecondary(s: string): MetricValue;

package/dist/cli/helpers.js

@@ -0,0 +1,90 @@
+// Shared CLI helpers for arg parsing and measurement construction.
+export const VERDICTS = ["confirmed", "failed", "inconclusive"];
+// Shared parseArgs option specs for baseline/candidate measurement fields.
+export const MEASUREMENT_OPTIONS = {
+    "baseline-median": { type: "string" },
+    "baseline-std": { type: "string", default: "0" },
+    "baseline-samples": { type: "string", default: "" },
+    "baseline-n": { type: "string" },
+    "candidate-median": { type: "string" },
+    "candidate-std": { type: "string", default: "0" },
+    "candidate-samples": { type: "string", default: "" },
+    "candidate-n": { type: "string" },
+    delta: { type: "string" },
+};
+/** Error thrown by die() — caught at the CLI entry point. */
+export class CliError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CliError";
+    }
+}
+export function die(msg) {
+    throw new CliError(msg);
+}
+export function requireArg(values, name) {
+    const val = values[name];
+    if (val == null || val === "") {
+        die(`missing required argument: --${name}`);
+    }
+    return String(val);
+}
+export function requireInt(values, name) {
+    const val = requireArg(values, name);
+    const n = parseInt(val, 10);
+    if (isNaN(n))
+        die(`invalid integer for --${name}: ${val}`);
+    return n;
+}
+export function optionalInt(values, name, defaultVal) {
+    const val = values[name];
+    if (val == null || val === "")
+        return defaultVal;
+    const n = parseInt(String(val), 10);
+    if (isNaN(n))
+        die(`invalid integer for --${name}: ${val}`);
+    return n;
+}
+function parseSamples(s) {
+    if (!s || s.trim() === "")
+        return [];
+    return s
+        .split(",")
+        .map((v) => parseInt(v.trim(), 10))
+        .filter((v) => !isNaN(v));
+}
+export function buildMeasurement(values, prefix) {
+    const median = requireInt(values, `${prefix}-median`);
+    const std = optionalInt(values, `${prefix}-std`, 0);
+    const n = requireInt(values, `${prefix}-n`);
+    const samples = parseSamples(values[`${prefix}-samples`] ?? "");
+    const m = { n, medianX1000: median, stdX1000: std };
+    if (samples.length > 0)
+        m.samplesX1000 = samples;
+    return m;
+}
+/**
+ * Parse "name:unit:baseline_x1000:candidate_x1000:delta_x100[:regressed]"
+ * Mirrors parse_secondary in the Rust CLI.
+ */
+export function parseSecondary(s) {
+    const parts = s.split(":");
+    if (parts.length < 5) {
+        die(`secondary metric needs at least 5 colon-separated fields: ${s}`);
+    }
+    const baselineMedian = parseInt(parts[2], 10);
+    const candidateMedian = parseInt(parts[3], 10);
+    const delta = parseInt(parts[4], 10);
+    if (isNaN(baselineMedian) || isNaN(candidateMedian) || isNaN(delta)) {
+        die(`secondary metric has non-integer numeric fields: ${s}`);
+    }
+    const regressed = parts[5] === "true";
+    return {
+        name: parts[0],
+        unit: parts[1],
+        baseline: { n: 1, medianX1000: baselineMedian, stdX1000: 0 },
+        candidate: { n: 1, medianX1000: candidateMedian, stdX1000: 0 },
+        deltaPctX100: delta,
+        regressed,
+    };
+}

package/dist/cli/rad.d.ts

@@ -0,0 +1,11 @@
+import type { Action, Experiment } from "../types.js";
+/** Resolve the RID for a repository path. */
+export declare function getRepoId(repoPath?: string): string;
+/** Create a new COB. Returns the ObjectId. */
+export declare function cobCreate(rid: string, actions: Action[], message: string): string;
+/** Update an existing COB. */
+export declare function cobUpdate(rid: string, objectId: string, actions: Action[], message: string): string;
+/** List all COB object IDs for cc.experiment type. */
+export declare function cobList(rid: string): string[];
+/** Show a COB's state as JSON. */
+export declare function cobShow(rid: string, objectId: string): Experiment;

package/dist/cli/rad.js

@@ -0,0 +1,64 @@
+// Wrapper around `rad` CLI commands for COB operations.
+import { execFileSync } from "node:child_process";
+import { writeFileSync, rmSync, mkdtempSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+const COB_TYPE = "cc.experiment";
+/** Resolve the RID for a repository path. */
+export function getRepoId(repoPath) {
+    const args = ["inspect", "--rid"];
+    const opts = repoPath ? { cwd: repoPath } : {};
+    return execFileSync("rad", args, { encoding: "utf-8", ...opts }).trim();
+}
+/** Write actions to a temp JSONL file, return its path. */
+function writeTempActions(actions) {
+    const dir = mkdtempSync(join(tmpdir(), "rad-exp-"));
+    const path = join(dir, "actions.jsonl");
+    const content = actions.map((a) => JSON.stringify(a)).join("\n") + "\n";
+    writeFileSync(path, content);
+    return path;
+}
+/** Clean up a temp file and its parent directory (best-effort). */
+function cleanupTemp(path) {
+    try {
+        rmSync(dirname(path), { recursive: true });
+    }
+    catch {
+        // ignore
+    }
+}
+/** Shared implementation for cobCreate and cobUpdate. */
+function cobExec(rid, subcommand, actions, message, objectId) {
+    const tmpFile = writeTempActions(actions);
+    try {
+        const args = ["cob", subcommand, "--repo", rid, "--type", COB_TYPE];
+        if (objectId)
+            args.push("--object", objectId);
+        args.push("--message", message, tmpFile);
+        return execFileSync("rad", args, { encoding: "utf-8" }).trim();
+    }
+    finally {
+        cleanupTemp(tmpFile);
+    }
+}
+/** Create a new COB. Returns the ObjectId. */
+export function cobCreate(rid, actions, message) {
+    return cobExec(rid, "create", actions, message);
+}
+/** Update an existing COB. */
+export function cobUpdate(rid, objectId, actions, message) {
+    return cobExec(rid, "update", actions, message, objectId);
+}
+/** List all COB object IDs for cc.experiment type. */
+export function cobList(rid) {
+    const stdout = execFileSync("rad", ["cob", "list", "--repo", rid, "--type", COB_TYPE], { encoding: "utf-8" });
+    return stdout
+        .split("\n")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+/** Show a COB's state as JSON. */
+export function cobShow(rid, objectId) {
+    const stdout = execFileSync("rad", ["cob", "show", "--repo", rid, "--type", COB_TYPE, "--object", objectId, "--format", "json"], { encoding: "utf-8" });
+    return JSON.parse(stdout);
+}

package/dist/cob/actions.d.ts

@@ -0,0 +1,35 @@
+import type { Measurement, MetricValue, PublishAction, ReproduceAction, Verdict } from "../types.js";
+/** Strip empty samplesX1000 from a Measurement before serialization. */
+export declare function cleanMeasurement(m: Measurement): Measurement;
+/** Build a Publish action matching exact Rust serde output. */
+export declare function buildPublishAction(opts: {
+    description?: string;
+    base: string;
+    oid: string;
+    metricName: string;
+    metricUnit: string;
+    direction: string;
+    runnerClass: string;
+    os: string;
+    cpu: string;
+    baseline: Measurement;
+    candidate: Measurement;
+    deltaPctX100: number;
+    buildOk: boolean;
+    testsOk: boolean;
+    sanitizersOk: boolean;
+    agentSystem: string;
+    agentModel: string;
+    secondaryMetrics: MetricValue[];
+}): PublishAction;
+/** Build a Reproduce action matching exact Rust serde output. */
+export declare function buildReproduceAction(opts: {
+    verdict: Verdict;
+    runnerClass: string;
+    baseline: Measurement;
+    candidate: Measurement;
+    deltaPctX100: number;
+    buildOk: boolean;
+    testsOk: boolean;
+    notes?: string;
+}): ReproduceAction;

package/dist/cob/actions.js

@@ -0,0 +1,57 @@
+// Action builders — constructs action objects with correct field naming.
+//
+// Actions use snake_case for Action-level fields (matching Rust serde output),
+// but camelCase for nested Measurement/MetricValue fields.
+// Optional/empty fields are omitted (matching Rust skip_serializing_if).
+/** Strip empty samplesX1000 from a Measurement before serialization. */
+export function cleanMeasurement(m) {
+    const result = { n: m.n, medianX1000: m.medianX1000, stdX1000: m.stdX1000 };
+    if (m.samplesX1000 && m.samplesX1000.length > 0) {
+        result.samplesX1000 = m.samplesX1000;
+    }
+    return result;
+}
+/** Build a Publish action matching exact Rust serde output. */
+export function buildPublishAction(opts) {
+    // Field order matches Rust struct declaration for consistent JSON output.
+    const action = { type: "publish" };
+    if (opts.description != null)
+        action.description = opts.description;
+    // Git object dependencies — prevents GC from pruning commits.
+    action.parents = [opts.base, opts.oid];
+    action.base = opts.base;
+    action.oid = opts.oid;
+    action.metric_name = opts.metricName;
+    action.metric_unit = opts.metricUnit;
+    action.direction = opts.direction;
+    action.runner_class = opts.runnerClass;
+    if (opts.os !== "")
+        action.os = opts.os;
+    if (opts.cpu !== "")
+        action.cpu = opts.cpu;
+    action.baseline = cleanMeasurement(opts.baseline);
+    action.candidate = cleanMeasurement(opts.candidate);
+    action.delta_pct_x100 = Math.abs(opts.deltaPctX100);
+    action.build_ok = opts.buildOk;
+    action.tests_ok = opts.testsOk;
+    action.sanitizers_ok = opts.sanitizersOk;
+    action.agent_system = opts.agentSystem;
+    action.agent_model = opts.agentModel;
+    if (opts.secondaryMetrics.length > 0)
+        action.secondary_metrics = opts.secondaryMetrics;
+    return action;
+}
+/** Build a Reproduce action matching exact Rust serde output. */
+export function buildReproduceAction(opts) {
+    const action = { type: "reproduce" };
+    action.verdict = opts.verdict;
+    action.runner_class = opts.runnerClass;
+    action.baseline = cleanMeasurement(opts.baseline);
+    action.candidate = cleanMeasurement(opts.candidate);
+    action.delta_pct_x100 = Math.abs(opts.deltaPctX100);
+    action.build_ok = opts.buildOk;
+    action.tests_ok = opts.testsOk;
+    if (opts.notes != null)
+        action.notes = opts.notes;
+    return action;
+}

package/dist/cob/state.d.ts

@@ -0,0 +1,7 @@
+import type { Experiment, Op, OpMessage } from "../types.js";
+/** Create an Experiment from the root operation. Mirrors Experiment::from_root. */
+export declare function fromRoot(op: Op): Experiment;
+/** Apply a subsequent operation to an existing experiment. */
+export declare function applyOp(exp: Experiment, op: Op): void;
+/** Process an OpMessage from Radicle's external COB protocol. */
+export declare function handleOpMessage(msg: OpMessage): Experiment;