rad-experiment 0.1.0

package/src/cli/helpers.ts

@@ -0,0 +1,101 @@
+// Shared CLI helpers for arg parsing and measurement construction.
+
+import type { Measurement, MetricValue, Verdict } from "../types.js";
+
+export const VERDICTS: Verdict[] = ["confirmed", "failed", "inconclusive"];
+
+// Shared parseArgs option specs for baseline/candidate measurement fields.
+export const MEASUREMENT_OPTIONS = {
+  "baseline-median": { type: "string" as const },
+  "baseline-std": { type: "string" as const, default: "0" },
+  "baseline-samples": { type: "string" as const, default: "" },
+  "baseline-n": { type: "string" as const },
+  "candidate-median": { type: "string" as const },
+  "candidate-std": { type: "string" as const, default: "0" },
+  "candidate-samples": { type: "string" as const, default: "" },
+  "candidate-n": { type: "string" as const },
+  delta: { type: "string" as const },
+};
+
+/** Error thrown by die() — caught at the CLI entry point. */
+export class CliError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "CliError";
+  }
+}
+
+export function die(msg: string): never {
+  throw new CliError(msg);
+}
+
+export function requireArg(values: Record<string, unknown>, name: string): string {
+  const val = values[name];
+  if (val == null || val === "") {
+    die(`missing required argument: --${name}`);
+  }
+  return String(val);
+}
+
+export function requireInt(values: Record<string, unknown>, name: string): number {
+  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: Record<string, unknown>, name: string, defaultVal: number): number {
+  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: string): number[] {
+  if (!s || s.trim() === "") return [];
+  return s
+    .split(",")
+    .map((v) => parseInt(v.trim(), 10))
+    .filter((v) => !isNaN(v));
+}
+
+export function buildMeasurement(
+  values: Record<string, unknown>,
+  prefix: "baseline" | "candidate",
+): Measurement {
+  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`] as string) ?? "");
+
+  const m: Measurement = { 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: string): MetricValue {
+  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/src/cli/rad.ts

@@ -0,0 +1,87 @@
+// 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";
+import type { Action, Experiment } from "../types.js";
+
+const COB_TYPE = "cc.experiment";
+
+/** Resolve the RID for a repository path. */
+export function getRepoId(repoPath?: string): string {
+  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: Action[]): string {
+  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: string): void {
+  try {
+    rmSync(dirname(path), { recursive: true });
+  } catch {
+    // ignore
+  }
+}
+
+/** Shared implementation for cobCreate and cobUpdate. */
+function cobExec(
+  rid: string,
+  subcommand: "create" | "update",
+  actions: Action[],
+  message: string,
+  objectId?: string,
+): string {
+  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: string, actions: Action[], message: string): string {
+  return cobExec(rid, "create", actions, message);
+}
+
+/** Update an existing COB. */
+export function cobUpdate(rid: string, objectId: string, actions: Action[], message: string): string {
+  return cobExec(rid, "update", actions, message, objectId);
+}
+
+/** List all COB object IDs for cc.experiment type. */
+export function cobList(rid: string): string[] {
+  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: string, objectId: string): Experiment {
+  const stdout = execFileSync(
+    "rad",
+    ["cob", "show", "--repo", rid, "--type", COB_TYPE, "--object", objectId, "--format", "json"],
+    { encoding: "utf-8" },
+  );
+  return JSON.parse(stdout);
+}

package/src/cob/actions.ts

@@ -0,0 +1,100 @@
+// 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).
+
+import type {
+  Measurement,
+  MetricValue,
+  PublishAction,
+  ReproduceAction,
+  Verdict,
+} from "../types.js";
+
+/** Strip empty samplesX1000 from a Measurement before serialization. */
+export function cleanMeasurement(m: Measurement): Measurement {
+  const result: Measurement = { 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: {
+  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 {
+  // Field order matches Rust struct declaration for consistent JSON output.
+  const action: Record<string, unknown> = { 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 as unknown as PublishAction;
+}
+
+/** Build a Reproduce action matching exact Rust serde output. */
+export function buildReproduceAction(opts: {
+  verdict: Verdict;
+  runnerClass: string;
+  baseline: Measurement;
+  candidate: Measurement;
+  deltaPctX100: number;
+  buildOk: boolean;
+  testsOk: boolean;
+  notes?: string;
+}): ReproduceAction {
+  const action: Record<string, unknown> = { 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 as unknown as ReproduceAction;
+}

package/src/cob/state.ts

@@ -0,0 +1,120 @@
+// 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).
+
+import type {
+  Author,
+  Experiment,
+  Measurement,
+  MetricValue,
+  Op,
+  OpMessage,
+  Verdict,
+} from "../types.js";
+
+type RawAction = Record<string, unknown>;
+
+/** Build an Author from a raw public key string. */
+function authorFromKey(key: string): Author {
+  const id = key.startsWith("did:key:") ? key : `did:key:${key}`;
+  return { id };
+}
+
+function snakeToCamel(s: string): string {
+  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: RawAction, snakeCase: string): unknown {
+  if (snakeCase in action) return action[snakeCase];
+  return action[snakeToCamel(snakeCase)];
+}
+
+function rawActions(op: Op): RawAction[] {
+  return op.actions as unknown as RawAction[];
+}
+
+/** Apply a single action to an experiment (mutates in place). */
+function applyAction(exp: Experiment, action: RawAction, author: string, timestamp: number): void {
+  if (action.type !== "reproduce") return;
+
+  exp.reproductions.push({
+    verdict: action.verdict as Verdict,
+    runnerClass: (field(action, "runner_class") ?? "") as string,
+    baseline: action.baseline as Measurement,
+    candidate: action.candidate as Measurement,
+    deltaPctX100: (field(action, "delta_pct_x100") ?? 0) as number,
+    author: authorFromKey(author),
+    timestamp,
+  });
+}
+
+/** Create an Experiment from the root operation. Mirrors Experiment::from_root. */
+export function fromRoot(op: Op): Experiment {
+  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 as string | undefined;
+  const secondaryMetrics = (field(first, "secondary_metrics") ?? []) as MetricValue[];
+
+  const exp: Experiment = {
+    ...(description != null ? { description } : {}),
+    base: first.base as string,
+    oid: first.oid as string,
+    metricName: (field(first, "metric_name") ?? "") as string,
+    metricUnit: (field(first, "metric_unit") ?? "") as string,
+    direction: first.direction as string,
+    runnerClass: (field(first, "runner_class") ?? "") as string,
+    os: (first.os ?? "") as string,
+    cpu: (first.cpu ?? "") as string,
+    baseline: first.baseline as Measurement,
+    candidate: first.candidate as Measurement,
+    deltaPctX100: (field(first, "delta_pct_x100") ?? 0) as number,
+    buildOk: (field(first, "build_ok") ?? true) as boolean,
+    testsOk: (field(first, "tests_ok") ?? true) as boolean,
+    sanitizersOk: (field(first, "sanitizers_ok") ?? false) as boolean,
+    agentSystem: (field(first, "agent_system") ?? "") as string,
+    agentModel: (field(first, "agent_model") ?? "") as string,
+    ...(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: Experiment, op: Op): void {
+  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: OpMessage): Experiment {
+  let exp: Experiment;
+
+  if (msg.value == null || (typeof msg.value === "object" && Object.keys(msg.value).length === 0)) {
+    exp = fromRoot(msg.op);
+  } else {
+    exp = msg.value as unknown as Experiment;
+    applyOp(exp, msg.op);
+  }
+
+  for (const cop of msg.concurrent) {
+    applyOp(exp, cop);
+  }
+  return exp;
+}

package/src/rad-cob-experiment.ts

@@ -0,0 +1,39 @@
+#!/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";
+import type { OpMessage } from "./types.js";
+
+function fatal(err: unknown): never {
+  const msg = err instanceof Error ? err.message : String(err);
+  process.stderr.write(`rad-cob-experiment: ${msg}\n`);
+  process.exit(1);
+}
+
+async function main(): Promise<void> {
+  const rl = createInterface({ input: process.stdin });
+
+  for await (const line of rl) {
+    const trimmed = line.trim();
+    if (trimmed === "") continue;
+
+    try {
+      const msg: OpMessage = JSON.parse(trimmed);
+      const newState = handleOpMessage(msg);
+      process.stdout.write(JSON.stringify(newState) + "\n");
+    } catch (err: unknown) {
+      fatal(err);
+    }
+  }
+}
+
+main().catch(fatal);

package/src/rad-experiment.ts

@@ -0,0 +1,85 @@
+#!/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: Record<string, (args: string[]) => void> = {
+  publish: cmdPublish,
+  list: cmdList,
+  show: cmdShow,
+  reproduce: cmdReproduce,
+};
+
+function usage(): never {
+  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(): void {
+  const rawArgs = process.argv.slice(2);
+
+  // Extract global --repo/-r before subcommand.
+  let globalRepo: string | undefined;
+  const subArgs: string[] = [];
+  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: unknown) {
+  // 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 as Error & { stderr?: Buffer };
+    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/src/types.ts

@@ -0,0 +1,133 @@
+// 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")
+
+// --- Shared types (camelCase — these structs have rename_all = "camelCase") ---
+
+export interface Measurement {
+  n: number;
+  medianX1000: number;
+  stdX1000: number;
+  samplesX1000?: number[]; // omitted when empty (skip_serializing_if)
+}
+
+export type Verdict = "confirmed" | "failed" | "inconclusive";
+
+export interface MetricValue {
+  name: string;
+  unit: string;
+  baseline: Measurement;
+  candidate: Measurement;
+  deltaPctX100: number;
+  regressed: boolean;
+}
+
+// --- State types (camelCase — Experiment has rename_all = "camelCase") ---
+
+export interface Reproduction {
+  verdict: Verdict;
+  runnerClass: string;
+  baseline: Measurement;
+  candidate: Measurement;
+  deltaPctX100: number;
+  author: Author;
+  timestamp: number;
+}
+
+export interface Author {
+  id: string; // "did:key:z6Mk..."
+}
+
+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;
+}
+
+// --- Action types (snake_case for Action fields, camelCase for nested structs) ---
+// The Rust enum has #[serde(tag = "type", rename_all = "camelCase")] but
+// rename_all on an enum only affects variant names, NOT field names within variants.
+// Field names stay as their Rust snake_case names.
+
+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;     // Measurement itself is camelCase
+  candidate: Measurement;
+  delta_pct_x100: number;
+  build_ok: boolean;
+  tests_ok: boolean;
+  sanitizers_ok: boolean;
+  agent_system: string;
+  agent_model: string;
+  secondary_metrics?: MetricValue[];  // MetricValue itself is camelCase
+}
+
+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;
+
+// --- Op structure matching radicle::cob::Op<Action> serialization ---
+
+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/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "node16",
+    "moduleResolution": "node16",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "declaration": true,
+    "sourceMap": false,
+    "skipLibCheck": true
+  },
+  "include": ["src"],
+  "exclude": ["src/__tests__"]
+}