rad-experiment 0.1.0

package/dist/cob/state.js

@@ -0,0 +1,97 @@
+// State evaluation: applies actions to build Experiment state.
+// Mirrors the Rust from_root / apply_action / op logic in lib.rs.
+//
+// Actions arrive with snake_case field names (matching Rust serde).
+// State output uses camelCase field names (matching Experiment struct serde).
+/** Build an Author from a raw public key string. */
+function authorFromKey(key) {
+    const id = key.startsWith("did:key:") ? key : `did:key:${key}`;
+    return { id };
+}
+function snakeToCamel(s) {
+    return s.replace(/_([a-z0-9])/g, (_, c) => c.toUpperCase());
+}
+/**
+ * Read a field from an action object, trying snake_case first then camelCase.
+ * Handles both Rust-created (snake_case) and legacy TS-created (camelCase) COBs.
+ */
+function field(action, snakeCase) {
+    if (snakeCase in action)
+        return action[snakeCase];
+    return action[snakeToCamel(snakeCase)];
+}
+function rawActions(op) {
+    return op.actions;
+}
+/** Apply a single action to an experiment (mutates in place). */
+function applyAction(exp, action, author, timestamp) {
+    if (action.type !== "reproduce")
+        return;
+    exp.reproductions.push({
+        verdict: action.verdict,
+        runnerClass: (field(action, "runner_class") ?? ""),
+        baseline: action.baseline,
+        candidate: action.candidate,
+        deltaPctX100: (field(action, "delta_pct_x100") ?? 0),
+        author: authorFromKey(author),
+        timestamp,
+    });
+}
+/** Create an Experiment from the root operation. Mirrors Experiment::from_root. */
+export function fromRoot(op) {
+    const actions = [...rawActions(op)];
+    const first = actions.shift();
+    if (!first || first.type !== "publish") {
+        throw new Error("the first action must be of type `publish`");
+    }
+    const description = first.description;
+    const secondaryMetrics = (field(first, "secondary_metrics") ?? []);
+    const exp = {
+        ...(description != null ? { description } : {}),
+        base: first.base,
+        oid: first.oid,
+        metricName: (field(first, "metric_name") ?? ""),
+        metricUnit: (field(first, "metric_unit") ?? ""),
+        direction: first.direction,
+        runnerClass: (field(first, "runner_class") ?? ""),
+        os: (first.os ?? ""),
+        cpu: (first.cpu ?? ""),
+        baseline: first.baseline,
+        candidate: first.candidate,
+        deltaPctX100: (field(first, "delta_pct_x100") ?? 0),
+        buildOk: (field(first, "build_ok") ?? true),
+        testsOk: (field(first, "tests_ok") ?? true),
+        sanitizersOk: (field(first, "sanitizers_ok") ?? false),
+        agentSystem: (field(first, "agent_system") ?? ""),
+        agentModel: (field(first, "agent_model") ?? ""),
+        ...(secondaryMetrics.length > 0 ? { secondaryMetrics } : {}),
+        reproductions: [],
+        author: authorFromKey(op.author),
+        createdAt: op.timestamp,
+    };
+    for (const action of actions) {
+        applyAction(exp, action, op.author, op.timestamp);
+    }
+    return exp;
+}
+/** Apply a subsequent operation to an existing experiment. */
+export function applyOp(exp, op) {
+    for (const action of rawActions(op)) {
+        applyAction(exp, action, op.author, op.timestamp);
+    }
+}
+/** Process an OpMessage from Radicle's external COB protocol. */
+export function handleOpMessage(msg) {
+    let exp;
+    if (msg.value == null || (typeof msg.value === "object" && Object.keys(msg.value).length === 0)) {
+        exp = fromRoot(msg.op);
+    }
+    else {
+        exp = msg.value;
+        applyOp(exp, msg.op);
+    }
+    for (const cop of msg.concurrent) {
+        applyOp(exp, cop);
+    }
+    return exp;
+}

package/dist/rad-cob-experiment.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/rad-cob-experiment.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+// rad-cob-experiment: External COB helper for the Radicle external COB protocol.
+//
+// Protocol (JSON Lines on stdin/stdout):
+//   1. Read one JSON Line: { value, op, concurrent }
+//   2. Apply op (and concurrent ops) to value -> new state
+//   3. Write new state as JSON Line to stdout
+//   4. Repeat until stdin closes
+//   5. Exit 0 on success, non-zero on failure
+import { createInterface } from "node:readline";
+import { handleOpMessage } from "./cob/state.js";
+function fatal(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`rad-cob-experiment: ${msg}\n`);
+    process.exit(1);
+}
+async function main() {
+    const rl = createInterface({ input: process.stdin });
+    for await (const line of rl) {
+        const trimmed = line.trim();
+        if (trimmed === "")
+            continue;
+        try {
+            const msg = JSON.parse(trimmed);
+            const newState = handleOpMessage(msg);
+            process.stdout.write(JSON.stringify(newState) + "\n");
+        }
+        catch (err) {
+            fatal(err);
+        }
+    }
+}
+main().catch(fatal);

package/dist/rad-experiment.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/rad-experiment.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+// rad-experiment CLI — thin wrapper around rad cob commands.
+// Subcommands live in cli/commands/; shared helpers in cli/helpers.ts.
+import { CliError } from "./cli/helpers.js";
+import { cmdPublish } from "./cli/commands/publish.js";
+import { cmdList } from "./cli/commands/list.js";
+import { cmdShow } from "./cli/commands/show.js";
+import { cmdReproduce } from "./cli/commands/reproduce.js";
+const COMMANDS = {
+    publish: cmdPublish,
+    list: cmdList,
+    show: cmdShow,
+    reproduce: cmdReproduce,
+};
+function usage() {
+    console.error(`Usage: rad-experiment [--repo <repo_path>] <command> [options]
+
+Commands:
+  publish     Publish a new optimization experiment
+  list        List all experiments
+  show        Show experiment details
+  reproduce   Add a reproduction to an experiment`);
+    process.exit(1);
+}
+function main() {
+    const rawArgs = process.argv.slice(2);
+    // Extract global --repo/-r before subcommand.
+    let globalRepo;
+    const subArgs = [];
+    let foundCommand = false;
+    for (let i = 0; i < rawArgs.length; i++) {
+        if (!foundCommand && (rawArgs[i] === "--repo" || rawArgs[i] === "-r")) {
+            globalRepo = rawArgs[++i];
+            continue;
+        }
+        if (!foundCommand && rawArgs[i] in COMMANDS) {
+            foundCommand = true;
+            subArgs.push(rawArgs[i]);
+            continue;
+        }
+        subArgs.push(rawArgs[i]);
+    }
+    if (subArgs.length === 0)
+        usage();
+    const command = subArgs.shift();
+    const handler = COMMANDS[command];
+    if (!handler)
+        usage();
+    if (globalRepo && !subArgs.includes("--repo") && !subArgs.includes("-r")) {
+        subArgs.unshift("--repo", globalRepo);
+    }
+    handler(subArgs);
+}
+try {
+    main();
+}
+catch (err) {
+    // CliError: validation failures from die() — print and exit 1.
+    if (err instanceof CliError) {
+        process.stderr.write(`error: ${err.message}\n`);
+        process.exit(1);
+    }
+    // execFileSync errors: child process failures from rad CLI.
+    if (err instanceof Error && "status" in err) {
+        const execErr = err;
+        const stderr = execErr.stderr?.toString().trim();
+        process.stderr.write(`error: ${stderr || err.message}\n`);
+        process.exit(1);
+    }
+    // Unexpected errors.
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`error: ${msg}\n`);
+    process.exit(1);
+}

package/dist/types.d.ts

@@ -0,0 +1,102 @@
+export interface Measurement {
+    n: number;
+    medianX1000: number;
+    stdX1000: number;
+    samplesX1000?: number[];
+}
+export type Verdict = "confirmed" | "failed" | "inconclusive";
+export interface MetricValue {
+    name: string;
+    unit: string;
+    baseline: Measurement;
+    candidate: Measurement;
+    deltaPctX100: number;
+    regressed: boolean;
+}
+export interface Reproduction {
+    verdict: Verdict;
+    runnerClass: string;
+    baseline: Measurement;
+    candidate: Measurement;
+    deltaPctX100: number;
+    author: Author;
+    timestamp: number;
+}
+export interface Author {
+    id: string;
+}
+export interface Experiment {
+    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[];
+    reproductions: Reproduction[];
+    author: Author;
+    createdAt: number;
+}
+export interface PublishAction {
+    type: "publish";
+    description?: string;
+    base: string;
+    oid: string;
+    metric_name: string;
+    metric_unit: string;
+    direction: string;
+    runner_class: string;
+    os?: string;
+    cpu?: string;
+    baseline: Measurement;
+    candidate: Measurement;
+    delta_pct_x100: number;
+    build_ok: boolean;
+    tests_ok: boolean;
+    sanitizers_ok: boolean;
+    agent_system: string;
+    agent_model: string;
+    secondary_metrics?: MetricValue[];
+}
+export interface ReproduceAction {
+    type: "reproduce";
+    verdict: Verdict;
+    runner_class: string;
+    baseline: Measurement;
+    candidate: Measurement;
+    delta_pct_x100: number;
+    build_ok: boolean;
+    tests_ok: boolean;
+    notes?: string;
+}
+export type Action = PublishAction | ReproduceAction;
+export interface Manifest {
+    typeName: string;
+    version: number;
+}
+export interface Op {
+    id: string;
+    actions: Action[];
+    author: string;
+    timestamp: number;
+    parents: string[];
+    related: string[];
+    identity: string | null;
+    manifest: Manifest;
+}
+export interface OpMessage {
+    value: Record<string, unknown>;
+    op: Op;
+    concurrent: Op[];
+}

package/dist/types.js

@@ -0,0 +1,9 @@
+// Types matching the Rust serde serialization exactly.
+//
+// IMPORTANT naming conventions (matching Rust serde):
+//   - Action enum fields: snake_case (enum-level rename_all only affects variant names)
+//   - Measurement struct fields: camelCase (has its own rename_all = "camelCase")
+//   - MetricValue struct fields: camelCase (has its own rename_all = "camelCase")
+//   - Experiment state fields: camelCase (has its own rename_all = "camelCase")
+//   - Reproduction state fields: camelCase (has its own rename_all = "camelCase")
+export {};

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "rad-experiment",
+  "version": "0.1.0",
+  "description": "Radicle COB type for AI-generated optimization experiments (TypeScript)",
+  "type": "module",
+  "bin": {
+    "rad-experiment": "./dist/rad-experiment.js",
+    "rad-cob-experiment": "./dist/rad-cob-experiment.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "tsc",
+    "test": "tsc --noEmit && npx tsx --test src/__tests__/format.test.ts src/__tests__/actions.test.ts src/__tests__/state.test.ts src/__tests__/helpers.test.ts src/__tests__/serialization.test.ts src/__tests__/cob-protocol.test.ts src/__tests__/integration.test.ts",
+    "test:unit": "npx tsx --test src/__tests__/format.test.ts src/__tests__/actions.test.ts src/__tests__/state.test.ts src/__tests__/helpers.test.ts src/__tests__/serialization.test.ts",
+    "test:protocol": "npx tsx --test src/__tests__/cob-protocol.test.ts",
+    "test:integration": "npx tsx --test src/__tests__/integration.test.ts"
+  },
+  "devDependencies": {
+    "@types/node": "^18.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.4.0"
+  },
+  "license": "MIT OR Apache-2.0"
+}

package/src/__tests__/actions.test.ts

@@ -0,0 +1,122 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+import { cleanMeasurement, buildPublishAction, buildReproduceAction } from "../cob/actions.js";
+import { makeMeasurement, makeMetricValue } from "./fixtures.js";
+
+describe("cleanMeasurement", () => {
+  it("strips empty samplesX1000", () => {
+    const result = cleanMeasurement({ n: 5, medianX1000: 100, stdX1000: 10, samplesX1000: [] });
+    assert.equal("samplesX1000" in result, false);
+  });
+
+  it("keeps non-empty samplesX1000", () => {
+    const result = cleanMeasurement({ n: 5, medianX1000: 100, stdX1000: 10, samplesX1000: [100, 200] });
+    assert.deepEqual(result.samplesX1000, [100, 200]);
+  });
+
+  it("handles undefined samplesX1000", () => {
+    const result = cleanMeasurement({ n: 5, medianX1000: 100, stdX1000: 10 });
+    assert.equal("samplesX1000" in result, false);
+  });
+});
+
+describe("buildPublishAction", () => {
+  const defaults = {
+    base: "abc", oid: "abc",
+    metricName: "wall_time", metricUnit: "ms", direction: "lower_is_better",
+    runnerClass: "arm64", os: "", cpu: "",
+    baseline: makeMeasurement(), candidate: makeMeasurement(),
+    deltaPctX100: 100, buildOk: true, testsOk: true, sanitizersOk: false,
+    agentSystem: "claude-code", agentModel: "claude-opus-4-6",
+    secondaryMetrics: [],
+  };
+
+  it("sets type to publish", () => {
+    const a = buildPublishAction(defaults) as unknown as Record<string, unknown>;
+    assert.equal(a.type, "publish");
+  });
+
+  it("uses snake_case field names", () => {
+    const a = buildPublishAction(defaults) as unknown as Record<string, unknown>;
+    assert.ok("metric_name" in a);
+    assert.ok("runner_class" in a);
+    assert.ok("delta_pct_x100" in a);
+    assert.ok("build_ok" in a);
+    assert.ok("agent_system" in a);
+    // camelCase versions should NOT be present
+    assert.ok(!("metricName" in a));
+    assert.ok(!("runnerClass" in a));
+  });
+
+  it("omits description when undefined", () => {
+    const a = buildPublishAction(defaults) as unknown as Record<string, unknown>;
+    assert.equal("description" in a, false);
+  });
+
+  it("includes description when provided", () => {
+    const a = buildPublishAction({ ...defaults, description: "test" }) as unknown as Record<string, unknown>;
+    assert.equal(a.description, "test");
+  });
+
+  it("omits os/cpu when empty string", () => {
+    const a = buildPublishAction(defaults) as unknown as Record<string, unknown>;
+    assert.equal("os" in a, false);
+    assert.equal("cpu" in a, false);
+  });
+
+  it("includes os/cpu when set", () => {
+    const a = buildPublishAction({ ...defaults, os: "linux", cpu: "x86" }) as unknown as Record<string, unknown>;
+    assert.equal(a.os, "linux");
+    assert.equal(a.cpu, "x86");
+  });
+
+  it("omits empty secondary_metrics", () => {
+    const a = buildPublishAction(defaults) as unknown as Record<string, unknown>;
+    assert.equal("secondary_metrics" in a, false);
+  });
+
+  it("includes non-empty secondary_metrics", () => {
+    const a = buildPublishAction({ ...defaults, secondaryMetrics: [makeMetricValue()] }) as unknown as Record<string, unknown>;
+    assert.ok("secondary_metrics" in a);
+  });
+
+  it("takes Math.abs of negative delta", () => {
+    const a = buildPublishAction({ ...defaults, deltaPctX100: -500 }) as unknown as Record<string, unknown>;
+    assert.equal(a.delta_pct_x100, 500);
+  });
+
+  it("includes parents field for GC safety", () => {
+    const a = buildPublishAction({ ...defaults, base: "aaa", oid: "bbb" }) as unknown as Record<string, unknown>;
+    assert.deepEqual(a.parents, ["aaa", "bbb"]);
+  });
+});
+
+describe("buildReproduceAction", () => {
+  const defaults = {
+    verdict: "confirmed" as const,
+    runnerClass: "amd64",
+    baseline: makeMeasurement(), candidate: makeMeasurement(),
+    deltaPctX100: 100, buildOk: true, testsOk: true,
+  };
+
+  it("sets type to reproduce", () => {
+    const a = buildReproduceAction(defaults) as unknown as Record<string, unknown>;
+    assert.equal(a.type, "reproduce");
+  });
+
+  it("omits notes when undefined", () => {
+    const a = buildReproduceAction(defaults) as unknown as Record<string, unknown>;
+    assert.equal("notes" in a, false);
+  });
+
+  it("includes notes when provided", () => {
+    const a = buildReproduceAction({ ...defaults, notes: "test" }) as unknown as Record<string, unknown>;
+    assert.equal(a.notes, "test");
+  });
+
+  it("takes Math.abs of negative delta", () => {
+    const a = buildReproduceAction({ ...defaults, deltaPctX100: -300 }) as unknown as Record<string, unknown>;
+    assert.equal(a.delta_pct_x100, 300);
+  });
+});

package/src/__tests__/cob-protocol.test.ts

@@ -0,0 +1,138 @@
+// Tests for the rad-cob-experiment binary as a black-box process.
+// Spawns the helper, pipes JSON Lines to stdin, verifies stdout output.
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+import type { Experiment, OpMessage } from "../types.js";
+import {
+  makeOp,
+  makeRawPublishAction,
+  makeRawReproduceAction,
+} from "./fixtures.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const HELPER = join(__dirname, "..", "rad-cob-experiment.ts");
+const TSX = join(__dirname, "..", "..", "node_modules", ".bin", "tsx");
+
+/** Run the COB helper with input lines, return output lines. */
+function runHelper(inputLines: string[]): string[] {
+  const input = inputLines.join("\n") + "\n";
+  const stdout = execFileSync(TSX, [HELPER], {
+    input,
+    encoding: "utf-8",
+    timeout: 5000,
+  });
+  return stdout.trim().split("\n").filter((l) => l.length > 0);
+}
+
+function makeOpMessage(overrides?: Partial<OpMessage>): OpMessage {
+  return {
+    value: {},
+    op: makeOp(),
+    concurrent: [],
+    ...overrides,
+  };
+}
+
+describe("cob-protocol: single publish (root creation)", () => {
+  it("returns valid Experiment state", () => {
+    const msg = makeOpMessage();
+    const lines = runHelper([JSON.stringify(msg)]);
+    assert.equal(lines.length, 1);
+
+    const exp: Experiment = JSON.parse(lines[0]);
+    assert.equal(exp.metricName, "wall_time");
+    assert.equal(exp.deltaPctX100, 2378);
+    assert.equal(exp.runnerClass, "arm64");
+    assert.deepEqual(exp.reproductions, []);
+    assert.ok(exp.author.id.startsWith("did:key:"));
+  });
+});
+
+describe("cob-protocol: multi-message sequence (publish then reproduce)", () => {
+  it("accumulates reproductions across messages", () => {
+    // Message 1: create experiment
+    const msg1 = makeOpMessage();
+    const line1 = runHelper([JSON.stringify(msg1)]);
+    const state1: Experiment = JSON.parse(line1[0]);
+    assert.equal(state1.reproductions.length, 0);
+
+    // Message 2: add reproduction (value = output of message 1)
+    const msg2 = makeOpMessage({
+      value: state1 as unknown as Record<string, unknown>,
+      op: makeOp({ actions: [makeRawReproduceAction()] }),
+    });
+    const line2 = runHelper([JSON.stringify(msg2)]);
+    const state2: Experiment = JSON.parse(line2[0]);
+    assert.equal(state2.reproductions.length, 1);
+    assert.equal(state2.reproductions[0].verdict, "confirmed");
+    assert.equal(state2.reproductions[0].runnerClass, "amd64");
+  });
+});
+
+describe("cob-protocol: concurrent ops", () => {
+  it("applies concurrent reproductions", () => {
+    const msg = makeOpMessage({
+      concurrent: [
+        makeOp({ actions: [makeRawReproduceAction({ verdict: "confirmed" })] }),
+        makeOp({ actions: [makeRawReproduceAction({ verdict: "failed" })] }),
+      ],
+    });
+    const lines = runHelper([JSON.stringify(msg)]);
+    const exp: Experiment = JSON.parse(lines[0]);
+    assert.equal(exp.reproductions.length, 2);
+  });
+});
+
+describe("cob-protocol: multiple JSON Lines in one session", () => {
+  it("processes each line independently", () => {
+    const msg1 = makeOpMessage();
+    const msg2 = makeOpMessage({
+      op: makeOp({ actions: [makeRawPublishAction({ description: "second" })] }),
+    });
+    const lines = runHelper([JSON.stringify(msg1), JSON.stringify(msg2)]);
+    assert.equal(lines.length, 2);
+
+    const exp1: Experiment = JSON.parse(lines[0]);
+    const exp2: Experiment = JSON.parse(lines[1]);
+    assert.equal(exp1.description, "SIMD vectorization in parser loop");
+    assert.equal(exp2.description, "second");
+  });
+});
+
+describe("cob-protocol: empty lines are skipped", () => {
+  it("only produces output for valid JSON Lines", () => {
+    const msg = makeOpMessage();
+    const lines = runHelper(["", JSON.stringify(msg), "", ""]);
+    assert.equal(lines.length, 1);
+  });
+});
+
+describe("cob-protocol: error handling", () => {
+  it("exits non-zero on invalid JSON", () => {
+    assert.throws(
+      () => runHelper(["not valid json"]),
+      (err: unknown) => {
+        const e = err as { status: number; stderr: Buffer };
+        return e.status !== 0 && e.stderr.toString().includes("rad-cob-experiment:");
+      },
+    );
+  });
+
+  it("exits non-zero when first action is not publish", () => {
+    const msg = makeOpMessage({
+      op: makeOp({ actions: [makeRawReproduceAction()] }),
+    });
+    assert.throws(
+      () => runHelper([JSON.stringify(msg)]),
+      (err: unknown) => {
+        const e = err as { status: number; stderr: Buffer };
+        return e.status !== 0 && e.stderr.toString().includes("publish");
+      },
+    );
+  });
+});