@haiyangbg/buildbeat 1.21.0 → 2.0.0-beta.2

package/src/v2/runtime/run-record.js

@@ -0,0 +1,55 @@
+// Terminal-run compaction per docs/v2/RFC-0002-domain-model.md §6: before any
+// runtime cleanup, a terminal Run must be compacted into an immutable
+// run-record in the Git plane. Long-term audit must never depend on the
+// runtime directory still existing.
+
+import { createHash } from "node:crypto";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join, relative } from "node:path";
+
+import { canonicalJson } from "../storage/event-ledger.js";
+
+const KERNEL = { kind: "kernel", id: "orchestrator" };
+
+export function writeRunRecord({ repoRoot, ledger, ts }) {
+  const state = ledger.state;
+  if (!state.terminal) {
+    throw new Error("run-record requires a terminal run");
+  }
+  const first = ledger.events[0];
+  const last = ledger.events[ledger.events.length - 1];
+  const attempts = {};
+  for (const [step, info] of Object.entries(state.steps)) {
+    attempts[step] = info.attempts;
+  }
+  const record = {
+    run: first.run,
+    work: first.work,
+    terminal: state.terminal,
+    events: { from: first.seq, to: last.seq, lastDigest: last.digest },
+    startedAt: first.ts,
+    finishedAt: last.ts,
+    attempts,
+    budgets: state.budgets,
+    workspaces: state.workspaces,
+    evidence: state.evidence,
+    decisions: state.decisions,
+    approvals: state.approvals,
+    unverified: state.evidence
+      .filter((item) => item.status === "unverified")
+      .map((item) => item.ref),
+  };
+  const recordDir = join(repoRoot, "delivery", "work", first.work, "runs", first.run);
+  mkdirSync(recordDir, { recursive: true });
+  const recordPath = join(recordDir, "run-record.json");
+  writeFileSync(recordPath, `${JSON.stringify(record, null, 2)}\n`, "utf8");
+  const digest = `sha256:${createHash("sha256").update(canonicalJson(record), "utf8").digest("hex")}`;
+  const runRecordRef = relative(repoRoot, recordPath);
+  ledger.append({
+    type: "RUN_COMPACTED",
+    actor: KERNEL,
+    ts,
+    data: { runRecordRef, runRecordDigest: digest },
+  });
+  return { recordPath, runRecordRef, digest };
+}

package/src/v2/storage/event-ledger.js

@@ -0,0 +1,154 @@
+// Append-only per-run event ledger per docs/v2/SPEC-0001-events-v1.md (FROZEN).
+// The ledger is the only runtime authority; snapshots are disposable. On any
+// chain violation the ledger truncates at the last valid line and refuses
+// further appends — recovery is a human decision, never a silent repair.
+
+import { createHash } from "node:crypto";
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+import { ENVELOPE_VERSION, GENESIS_DIGEST, validateEventInput } from "../domain/event-registry.js";
+import { applyEvent, initialState } from "../engine/reducer.js";
+
+export class LedgerError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "LedgerError";
+  }
+}
+
+export function canonicalJson(value) {
+  if (value === null || typeof value === "boolean" || typeof value === "number") {
+    return JSON.stringify(value);
+  }
+  if (typeof value === "string") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => canonicalJson(item)).join(",")}]`;
+  }
+  if (typeof value === "object") {
+    const keys = Object.keys(value).sort();
+    return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(",")}}`;
+  }
+  throw new TypeError(`unsupported value in event payload: ${typeof value}`);
+}
+
+export function eventDigest(event) {
+  const body = { ...event };
+  delete body.digest;
+  const hex = createHash("sha256").update(canonicalJson(body), "utf8").digest("hex");
+  return `sha256:${hex}`;
+}
+
+// Default reducer is the run reducer; other streams (observe) plug their own
+// reducer while keeping the exact same envelope, chain and corruption rules.
+const RUN_REDUCER = { initialState, applyEvent };
+
+export class EventLedger {
+  #run = null;
+  #work = null;
+  #reducer;
+
+  constructor(filePath, reducer = RUN_REDUCER) {
+    this.path = filePath;
+    this.events = [];
+    this.corruption = null;
+    this.#reducer = reducer;
+    this.state = reducer.initialState();
+    this.lastDigest = GENESIS_DIGEST;
+  }
+
+  static open(filePath, reducer = RUN_REDUCER) {
+    const ledger = new EventLedger(filePath, reducer);
+    if (existsSync(filePath)) {
+      ledger.#load();
+    }
+    return ledger;
+  }
+
+  #fail(atLine, reason) {
+    this.corruption = { atLine, afterSeq: this.state.seq, reason };
+  }
+
+  #load() {
+    const lines = readFileSync(this.path, "utf8")
+      .split("\n")
+      .filter((line) => line.length > 0);
+    for (const [index, line] of lines.entries()) {
+      const atLine = index + 1;
+      let event;
+      try {
+        event = JSON.parse(line);
+      } catch {
+        this.#fail(atLine, "invalid JSON");
+        return;
+      }
+      if (event.v !== ENVELOPE_VERSION) {
+        this.#fail(atLine, `unsupported envelope version: ${event.v}`);
+        return;
+      }
+      if (event.prev !== this.lastDigest) {
+        this.#fail(atLine, "hash chain broken: prev mismatch");
+        return;
+      }
+      if (eventDigest(event) !== event.digest) {
+        this.#fail(atLine, "digest mismatch");
+        return;
+      }
+      if (event.seq !== this.state.seq + 1) {
+        this.#fail(atLine, `sequence gap: expected ${this.state.seq + 1}, got ${event.seq}`);
+        return;
+      }
+      try {
+        this.state = this.#reducer.applyEvent(this.state, event);
+      } catch (error) {
+        this.#fail(atLine, `illegal event sequence: ${error.message}`);
+        return;
+      }
+      this.events.push(event);
+      this.lastDigest = event.digest;
+      this.#run ??= event.run;
+      this.#work ??= event.work;
+    }
+  }
+
+  append({ type, actor, data, ts, run, work }) {
+    if (this.corruption) {
+      throw new LedgerError(
+        `ledger corrupted after seq=${this.corruption.afterSeq} (${this.corruption.reason}); ` +
+          "recovery requires a human decision",
+      );
+    }
+    validateEventInput(type, actor, data);
+    const runId = run ?? this.#run;
+    const workId = work ?? this.#work;
+    if (!runId || !workId) {
+      throw new LedgerError("first event must carry run and work ids");
+    }
+    if ((run && this.#run && run !== this.#run) || (work && this.#work && work !== this.#work)) {
+      throw new LedgerError("run/work id mismatch with ledger identity");
+    }
+    const event = {
+      v: ENVELOPE_VERSION,
+      seq: this.state.seq + 1,
+      ts: ts ?? new Date().toISOString(),
+      run: runId,
+      work: workId,
+      type,
+      actor,
+      data,
+      prev: this.lastDigest,
+    };
+    event.digest = eventDigest(event);
+    const nextState = this.#reducer.applyEvent(this.state, event);
+    mkdirSync(dirname(this.path), { recursive: true });
+    appendFileSync(this.path, `${JSON.stringify(event)}\n`, "utf8");
+    this.events.push(event);
+    this.state = nextState;
+    this.lastDigest = event.digest;
+    this.#run ??= runId;
+    this.#work ??= workId;
+    return event;
+  }
+}

package/src/v2/workspace/workspace-manager.js

@@ -0,0 +1,146 @@
+// Workspace manager per docs/v2/RFC-0002-domain-model.md: every Run works in
+// an isolated git worktree; the candidate is whatever git reads back, never
+// what a worker claims. Locks are mkdir-atomic. Run branches are never
+// deleted here — the pinned candidate must stay reachable for evidence.
+
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+
+export class WorkspaceError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "WorkspaceError";
+  }
+}
+
+function git(cwd, args) {
+  try {
+    return execFileSync("git", ["-C", cwd, ...args], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+    }).trim();
+  } catch (error) {
+    const stderr = error.stderr ? String(error.stderr).trim() : error.message;
+    throw new WorkspaceError(`git ${args.join(" ")} failed: ${stderr}`);
+  }
+}
+
+export function acquireLock(repoRoot, runId) {
+  const lockDir = join(repoRoot, ".buildbeat", "runtime", "locks");
+  mkdirSync(lockDir, { recursive: true });
+  const lockPath = join(lockDir, `${runId}.lock`);
+  try {
+    mkdirSync(lockPath);
+  } catch (error) {
+    if (error.code === "EEXIST") {
+      throw new WorkspaceError(`run ${runId} is already locked (${lockPath})`);
+    }
+    throw error;
+  }
+  return lockPath;
+}
+
+export function releaseLock(repoRoot, runId) {
+  const lockPath = join(repoRoot, ".buildbeat", "runtime", "locks", `${runId}.lock`);
+  rmSync(lockPath, { recursive: true, force: true });
+}
+
+export function createWorkspace({ repoRoot, runId, base, branch, protectPush = true }) {
+  const resolvedBase = git(repoRoot, ["rev-parse", "--verify", `${base}^{commit}`]);
+  const worktreePath = join(repoRoot, ".buildbeat", "worktrees", runId);
+  if (existsSync(worktreePath)) {
+    throw new WorkspaceError(`worktree already exists: ${worktreePath}`);
+  }
+  const branchName = branch ?? `run/${runId}`;
+  const branches = git(repoRoot, ["branch", "--list", branchName]);
+  if (branches !== "") {
+    throw new WorkspaceError(`branch already exists: ${branchName}`);
+  }
+  git(repoRoot, ["worktree", "add", "-b", branchName, worktreePath, resolvedBase]);
+
+  // Protected Actions (B WP4.4): the reliable form of "workers must not
+  // push" is capability removal, not a prompt. Worktree-scoped pushurl
+  // overrides make any push from inside the workspace fail while the main
+  // checkout keeps its remotes untouched.
+  let protectedRemotes = [];
+  if (protectPush) {
+    const remotes = git(repoRoot, ["remote"]).split("\n").filter(Boolean);
+    if (remotes.length > 0) {
+      git(repoRoot, ["config", "extensions.worktreeConfig", "true"]);
+      for (const remote of remotes) {
+        git(worktreePath, [
+          "config",
+          "--worktree",
+          `remote.${remote}.pushurl`,
+          "protected://push-blocked-by-buildbeat",
+        ]);
+      }
+      protectedRemotes = remotes;
+    }
+  }
+  return {
+    workspaceId: runId,
+    repoRoot,
+    worktreePath,
+    branch: branchName,
+    base: resolvedBase,
+    protectedRemotes,
+  };
+}
+
+export function readback(worktreePath) {
+  const head = git(worktreePath, ["rev-parse", "HEAD"]);
+  const status = git(worktreePath, ["status", "--porcelain"]);
+  return { head, dirty: status !== "" };
+}
+
+// Paths changed relative to base: committed diff plus anything dirty in the
+// tree. Rename lines keep only the new path.
+export function listChangedPaths(worktreePath, base) {
+  // core.quotepath=off: git otherwise octal-escapes and quotes non-ASCII
+  // paths, which would defeat the allowedPaths prefix check (real incident:
+  // a Chinese board filename was reported as out of scope).
+  const committed = git(worktreePath, [
+    "-c",
+    "core.quotepath=off",
+    "diff",
+    "--name-only",
+    `${base}..HEAD`,
+  ])
+    .split("\n")
+    .filter(Boolean);
+  const dirty = git(worktreePath, ["-c", "core.quotepath=off", "status", "--porcelain"])
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => {
+      const path = line.slice(3);
+      return path.includes(" -> ") ? path.split(" -> ")[1] : path;
+    });
+  return [...new Set([...committed, ...dirty])];
+}
+
+export function pinCandidate(workspace) {
+  const { head, dirty } = readback(workspace.worktreePath);
+  if (dirty) {
+    throw new WorkspaceError(
+      `worktree is dirty; a candidate must be a committed state (${workspace.worktreePath})`,
+    );
+  }
+  return head;
+}
+
+export function removeWorkspace(workspace, { force = false } = {}) {
+  const { dirty } = readback(workspace.worktreePath);
+  if (dirty && !force) {
+    throw new WorkspaceError(
+      `refusing to remove dirty worktree ${workspace.worktreePath}; debug state is preserved`,
+    );
+  }
+  const args = ["worktree", "remove"];
+  if (force) {
+    args.push("--force");
+  }
+  args.push(workspace.worktreePath);
+  git(workspace.repoRoot, args);
+}