@haiyangbg/buildbeat 1.21.0 → 2.0.0-beta.2

package/src/v2/domain/model.js

@@ -0,0 +1,61 @@
+// v2 domain constants. Source of truth: docs/v2/RFC-0002-domain-model.md and
+// docs/v2/SPEC-0001-events-v1.md (FROZEN; additive-only evolution).
+
+export const WORK_STATES = ["OPEN", "COMPLETED", "CANCELLED"];
+
+export const RUN_STATES = [
+  "CREATED",
+  "QUEUED",
+  "RUNNING",
+  "WAITING_HUMAN",
+  "BLOCKED",
+  "SUCCEEDED",
+  "FAILED",
+  "CANCELLED",
+  "SUPERSEDED",
+];
+
+export const TERMINAL_RUN_STATES = ["SUCCEEDED", "FAILED", "CANCELLED", "SUPERSEDED"];
+
+export const STEP_STATES = [
+  "PENDING",
+  "READY",
+  "RUNNING",
+  "SUCCEEDED",
+  "FAILED",
+  "SKIPPED",
+  "CANCELLED",
+];
+
+export const GATE_RESULTS = ["PASS", "RETRY", "ROUTE", "WAIT_HUMAN", "BLOCK", "UNVERIFIED"];
+
+export const ACTOR_KINDS = ["kernel", "worker", "human", "adapter", "provider"];
+
+export const POLICY_PHASES = ["pre", "post", "transition", "action"];
+
+export const STEP_FINISH_STATUSES = [
+  "succeeded",
+  "failed",
+  "blocked",
+  "invalid-output",
+  "timeout",
+  "crashed",
+];
+
+export const BUDGET_KINDS = ["attempts", "tokens", "cost", "time"];
+
+export const EVIDENCE_STATUSES = ["passed", "failed", "unverified"];
+
+export const EVIDENCE_GRADES = ["L0", "L1", "L2", "L3", "L4"];
+
+export const DECISION_VALUES = ["approved", "rejected"];
+
+// observe v0 per docs/v2/RFC-0003-workflow-policy.md §8 (frozen shape):
+// bands are exactly three fixed levels; triage actions are a closed set.
+export const OBSERVE_BAND_LEVELS = ["log", "diagnose", "intent"];
+
+export const OBSERVE_SEVERITIES = ["info", "warn", "error", "critical"];
+
+export const TRIAGE_ACTIONS = ["fix_now", "schedule", "dismiss"];
+
+export const INTENT_DRAFT_STATES = ["draft", "accepted", "scheduled", "dismissed"];

package/src/v2/engine/reducer.js

@@ -0,0 +1,253 @@
+// Deterministic state reducer per docs/v2/SPEC-0001-events-v1.md §5.
+// Same ledger must always reduce to the same state; illegal sequences are
+// reported, never repaired. Unknown event types are skipped (seq still
+// advances) so newer writers stay readable.
+
+export class IllegalEventError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "IllegalEventError";
+  }
+}
+
+export function initialState() {
+  return {
+    seq: 0,
+    run: null,
+    position: null,
+    currentStep: null,
+    steps: {},
+    workspaces: {},
+    evidence: [],
+    policyLog: [],
+    fingerprints: [],
+    consecutiveSameFailure: 0,
+    budgets: {},
+    pendingHuman: null,
+    decisions: [],
+    approvals: [],
+    lastCheckpoint: null,
+    interrupted: null,
+    terminal: null,
+    compacted: null,
+  };
+}
+
+const RUN_STARTABLE_FROM = ["CREATED", "QUEUED", "WAITING_HUMAN", "BLOCKED"];
+
+export function applyEvent(state, event) {
+  if (event.seq !== state.seq + 1) {
+    throw new IllegalEventError(`expected seq ${state.seq + 1}, got ${event.seq}`);
+  }
+  const { type, data } = event;
+  if (!state.run && type !== "RUN_CREATED") {
+    throw new IllegalEventError(`first event must be RUN_CREATED, got ${type}`);
+  }
+  if (state.terminal && type !== "RUN_COMPACTED") {
+    throw new IllegalEventError(
+      `run is terminal (${state.terminal.status}); only RUN_COMPACTED is allowed`,
+    );
+  }
+
+  const next = structuredClone(state);
+  next.seq = event.seq;
+
+  switch (type) {
+    case "RUN_CREATED": {
+      if (state.run) {
+        throw new IllegalEventError("duplicate RUN_CREATED");
+      }
+      next.run = {
+        id: event.run,
+        work: event.work,
+        status: "CREATED",
+        workflowRef: data.workflowRef,
+        workflowDigest: data.workflowDigest,
+        base: data.base,
+        riskPreset: data.riskPreset,
+        entry: data.entry ?? null,
+        planDigest: data.planDigest ?? "UNVERIFIED",
+        intentDigest: data.intentDigest ?? "UNVERIFIED",
+      };
+      break;
+    }
+    case "RUN_STARTED": {
+      if (!RUN_STARTABLE_FROM.includes(state.run.status)) {
+        throw new IllegalEventError(`cannot start run from status ${state.run.status}`);
+      }
+      if (state.pendingHuman) {
+        throw new IllegalEventError("pending human request unresolved");
+      }
+      next.run.status = "RUNNING";
+      break;
+    }
+    case "WORKSPACE_BOUND": {
+      if (state.workspaces[data.workspaceId]) {
+        throw new IllegalEventError(`workspace already bound: ${data.workspaceId}`);
+      }
+      next.workspaces[data.workspaceId] = {
+        repo: data.repo,
+        branch: data.branch,
+        worktreePath: data.worktreePath,
+        base: data.base,
+        candidate: null,
+      };
+      break;
+    }
+    case "STEP_STARTED": {
+      if (state.run.status !== "RUNNING") {
+        throw new IllegalEventError(`cannot start step while run is ${state.run.status}`);
+      }
+      if (!state.workspaces[data.workspaceId]) {
+        throw new IllegalEventError(`unknown workspace: ${data.workspaceId}`);
+      }
+      const expectedAttempt = (state.steps[data.step]?.attempts ?? 0) + 1;
+      if (data.attempt !== expectedAttempt) {
+        throw new IllegalEventError(
+          `step ${data.step} expected attempt ${expectedAttempt}, got ${data.attempt}`,
+        );
+      }
+      next.steps[data.step] = { status: "RUNNING", attempts: data.attempt, detail: null };
+      next.currentStep = data.step;
+      break;
+    }
+    case "STEP_FINISHED": {
+      const step = state.steps[data.step];
+      if (!step || step.status !== "RUNNING" || step.attempts !== data.attempt) {
+        throw new IllegalEventError(
+          `no running attempt ${data.attempt} for step ${data.step} to finish`,
+        );
+      }
+      next.steps[data.step].status = data.status === "succeeded" ? "SUCCEEDED" : "FAILED";
+      next.steps[data.step].detail = data.status;
+      next.currentStep = null;
+      break;
+    }
+    case "CANDIDATE_PINNED": {
+      if (!state.workspaces[data.workspaceId]) {
+        throw new IllegalEventError(`unknown workspace: ${data.workspaceId}`);
+      }
+      next.workspaces[data.workspaceId].base = data.base;
+      next.workspaces[data.workspaceId].candidate = data.candidate;
+      break;
+    }
+    case "EVIDENCE_RECORDED": {
+      next.evidence.push({
+        ref: data.evidenceRef,
+        kind: data.kind,
+        subject: data.subject,
+        digest: data.digest,
+        status: data.status,
+        grade: data.grade,
+        ...(data.findings ? { findings: data.findings } : {}),
+      });
+      break;
+    }
+    case "POLICY_EVALUATED": {
+      next.policyLog.push({ policy: data.policy, phase: data.phase, result: data.result });
+      break;
+    }
+    case "TRANSITION": {
+      next.position = data.to;
+      break;
+    }
+    case "FAILURE_FINGERPRINT": {
+      const key = [data.step, data.command, data.exitCode, data.errorDigest].join("|");
+      const last = state.fingerprints[state.fingerprints.length - 1];
+      next.consecutiveSameFailure = last === key ? state.consecutiveSameFailure + 1 : 1;
+      next.fingerprints.push(key);
+      break;
+    }
+    case "BUDGET_CONSUMED": {
+      const consumed = state.budgets[data.kind]?.consumed ?? 0;
+      next.budgets[data.kind] = { consumed: consumed + data.amount, remaining: data.remaining };
+      break;
+    }
+    case "HUMAN_REQUESTED": {
+      next.pendingHuman = {
+        transition: data.transition,
+        subject: data.subject,
+        reasons: data.reasons,
+        kind: data.kind ?? "boundary",
+      };
+      next.run.status = "WAITING_HUMAN";
+      break;
+    }
+    case "DECISION_RECORDED": {
+      if (!state.pendingHuman || state.pendingHuman.transition !== data.transition) {
+        throw new IllegalEventError(`no pending human request for transition ${data.transition}`);
+      }
+      next.decisions.push({
+        decision: data.decision,
+        transition: data.transition,
+        subject: data.subject,
+        decisionRef: data.decisionRef,
+      });
+      if (data.decision === "approved") {
+        next.approvals.push({
+          decisionRef: data.decisionRef,
+          transition: data.transition,
+          subject: data.subject,
+          stale: false,
+        });
+      }
+      next.pendingHuman = null;
+      break;
+    }
+    case "APPROVAL_STALE": {
+      const index = state.approvals.findIndex(
+        (approval) => approval.decisionRef === data.approvalRef && !approval.stale,
+      );
+      if (index === -1) {
+        throw new IllegalEventError(`no active approval to mark stale: ${data.approvalRef}`);
+      }
+      next.approvals[index].stale = true;
+      next.approvals[index].changed = data.changed;
+      next.pendingHuman = {
+        transition: state.approvals[index].transition,
+        subject: state.approvals[index].subject,
+        reasons: ["APPROVAL_STALE"],
+        kind: "stale",
+      };
+      next.run.status = "WAITING_HUMAN";
+      break;
+    }
+    case "CHECKPOINT": {
+      next.lastCheckpoint = {
+        seq: event.seq,
+        resumePoint: data.resumePoint,
+        workspaceStates: data.workspaceStates,
+      };
+      break;
+    }
+    case "RUN_INTERRUPTED": {
+      next.interrupted = { seq: event.seq, cause: data.cause };
+      break;
+    }
+    case "RUN_TERMINAL": {
+      next.terminal = { status: data.status, reason: data.reason };
+      next.run.status = data.status;
+      break;
+    }
+    case "RUN_COMPACTED": {
+      if (!state.terminal) {
+        throw new IllegalEventError("RUN_COMPACTED requires a terminal run");
+      }
+      next.compacted = { runRecordRef: data.runRecordRef, runRecordDigest: data.runRecordDigest };
+      break;
+    }
+    default:
+      // Unknown type written by a newer version: preserved in the ledger,
+      // skipped here (seq already advanced above).
+      break;
+  }
+  return next;
+}
+
+export function reduceEvents(events) {
+  let state = initialState();
+  for (const event of events) {
+    state = applyEvent(state, event);
+  }
+  return state;
+}

package/src/v2/engine/risk-preset.js

@@ -0,0 +1,48 @@
+// Risk presets per docs/v2/RFC-0003-workflow-policy.md §7: fast / standard /
+// controlled plus the legacy-four-gates migration preset. A preset is data —
+// human boundaries (stopAt) and a policy set — never kernel-fixed gates.
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { PolicyError, parsePolicyDoc } from "../policy/policy.js";
+import { parseYamlSubset } from "./yaml-subset.js";
+
+const PRESET_DIR = fileURLToPath(new URL("../presets/risk/", import.meta.url));
+const PRESET_FIELDS = new Set(["kind", "version", "name", "stopAt", "policies"]);
+
+export function parseRiskPreset(doc) {
+  if (!doc || typeof doc !== "object" || Array.isArray(doc)) {
+    throw new PolicyError("risk preset must be a map");
+  }
+  for (const key of Object.keys(doc)) {
+    if (!PRESET_FIELDS.has(key)) {
+      throw new PolicyError(`unknown field "${key}" in risk preset ${doc.name ?? "(unnamed)"}`);
+    }
+  }
+  if (doc.kind !== "risk-preset" || doc.version !== 1) {
+    throw new PolicyError("risk preset requires kind: risk-preset and version: 1");
+  }
+  if (typeof doc.name !== "string" || doc.name.length === 0) {
+    throw new PolicyError("risk preset needs a name");
+  }
+  const stopAt = doc.stopAt ?? [];
+  if (!Array.isArray(stopAt) || stopAt.some((step) => typeof step !== "string")) {
+    throw new PolicyError(`risk preset ${doc.name}: stopAt must be a list of step ids`);
+  }
+  const policies = (doc.policies ?? []).map((policy) => parsePolicyDoc(policy));
+  return { name: doc.name, stopAt, policies };
+}
+
+export function loadRiskPreset(name) {
+  if (!/^[a-z0-9-]+$/.test(name)) {
+    throw new PolicyError(`invalid risk preset name: ${name}`);
+  }
+  const text = readFileSync(join(PRESET_DIR, `${name}.yaml`), "utf8");
+  const preset = parseRiskPreset(parseYamlSubset(text));
+  if (preset.name !== name) {
+    throw new PolicyError(`risk preset file ${name}.yaml declares name ${preset.name}`);
+  }
+  return preset;
+}

package/src/v2/engine/workflow.js

@@ -0,0 +1,201 @@
+// Minimal workflow parser per docs/v2/RFC-0003-workflow-policy.md §1.
+// The kernel is phase-agnostic: business steps come entirely from the
+// workflow file. Movement combines the declared step order (each step chains
+// to the next on "succeeded") with explicit transitions, which override the
+// default edge for the same (from, on) pair. Unknown fields are rejected.
+
+import { readFileSync } from "node:fs";
+
+import { parseYamlSubset } from "./yaml-subset.js";
+
+export class WorkflowError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "WorkflowError";
+  }
+}
+
+const ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+const TOP_FIELDS = new Set([
+  "kind",
+  "version",
+  "name",
+  "entry",
+  "steps",
+  "transitions",
+  "terminal",
+  "policies",
+  "budgets",
+]);
+const STEP_FIELDS = new Set(["id", "worker", "optional", "requiredWhen", "readonly"]);
+const TRANSITION_FIELDS = new Set(["from", "on", "to"]);
+
+function rejectUnknownFields(object, allowed, where) {
+  for (const key of Object.keys(object)) {
+    if (!allowed.has(key)) {
+      throw new WorkflowError(`unknown field "${key}" in ${where}`);
+    }
+  }
+}
+
+function requireId(value, where) {
+  if (typeof value !== "string" || !ID_PATTERN.test(value)) {
+    throw new WorkflowError(`${where} must be a lowercase id, got: ${JSON.stringify(value)}`);
+  }
+  return value;
+}
+
+export function parseWorkflow(text) {
+  const doc = parseYamlSubset(text);
+  if (!doc || typeof doc !== "object" || Array.isArray(doc)) {
+    throw new WorkflowError("workflow document must be a map");
+  }
+  rejectUnknownFields(doc, TOP_FIELDS, "workflow");
+  if (doc.kind !== "workflow") {
+    throw new WorkflowError(`kind must be "workflow", got: ${JSON.stringify(doc.kind)}`);
+  }
+  if (doc.version !== 1) {
+    throw new WorkflowError(`unsupported workflow version: ${JSON.stringify(doc.version)}`);
+  }
+  const name = requireId(doc.name, "name");
+  if (!Array.isArray(doc.steps) || doc.steps.length === 0) {
+    throw new WorkflowError("steps must be a non-empty list");
+  }
+
+  const steps = [];
+  const stepIds = new Set();
+  for (const raw of doc.steps) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+      throw new WorkflowError("each step must be a map");
+    }
+    rejectUnknownFields(raw, STEP_FIELDS, `step ${JSON.stringify(raw.id)}`);
+    const id = requireId(raw.id, "step id");
+    if (stepIds.has(id)) {
+      throw new WorkflowError(`duplicate step id: ${id}`);
+    }
+    if (raw.worker !== undefined) {
+      requireId(raw.worker, `step ${id} worker`);
+    }
+    if (raw.optional !== undefined && typeof raw.optional !== "boolean") {
+      throw new WorkflowError(`step ${id} optional must be a boolean`);
+    }
+    if (raw.readonly !== undefined && typeof raw.readonly !== "boolean") {
+      throw new WorkflowError(`step ${id} readonly must be a boolean`);
+    }
+    stepIds.add(id);
+    steps.push({
+      id,
+      worker: raw.worker ?? null,
+      optional: raw.optional ?? false,
+      requiredWhen: raw.requiredWhen ?? null,
+      readonly: raw.readonly ?? false,
+    });
+  }
+
+  const entry = requireId(doc.entry, "entry");
+  if (!stepIds.has(entry)) {
+    throw new WorkflowError(`entry references unknown step: ${entry}`);
+  }
+  if (!Array.isArray(doc.terminal) || doc.terminal.length === 0) {
+    throw new WorkflowError("terminal must be a non-empty list");
+  }
+  const terminal = new Set();
+  for (const id of doc.terminal) {
+    if (!stepIds.has(id)) {
+      throw new WorkflowError(`terminal references unknown step: ${id}`);
+    }
+    terminal.add(id);
+  }
+
+  const edges = new Map();
+  const explicit = doc.transitions ?? [];
+  if (!Array.isArray(explicit)) {
+    throw new WorkflowError("transitions must be a list");
+  }
+  for (const raw of explicit) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+      throw new WorkflowError("each transition must be a map");
+    }
+    rejectUnknownFields(raw, TRANSITION_FIELDS, "transition");
+    const from = requireId(raw.from, "transition from");
+    const to = requireId(raw.to, "transition to");
+    if (!stepIds.has(from) || !stepIds.has(to)) {
+      throw new WorkflowError(`transition references unknown step: ${from} -> ${to}`);
+    }
+    if (typeof raw.on !== "string" || raw.on.length === 0) {
+      throw new WorkflowError(`transition ${from} -> ${to} needs a non-empty "on"`);
+    }
+    const key = `${from}|${raw.on}`;
+    if (edges.has(key)) {
+      throw new WorkflowError(`duplicate transition for (${from}, ${raw.on})`);
+    }
+    edges.set(key, to);
+  }
+
+  for (const [index, step] of steps.entries()) {
+    const key = `${step.id}|succeeded`;
+    if (terminal.has(step.id) || edges.has(key)) {
+      continue;
+    }
+    const next = steps[index + 1];
+    if (next) {
+      edges.set(key, next.id);
+    }
+  }
+
+  const outgoing = new Map();
+  for (const [key, to] of edges) {
+    const from = key.split("|")[0];
+    if (!outgoing.has(from)) {
+      outgoing.set(from, []);
+    }
+    outgoing.get(from).push(to);
+  }
+
+  const reachable = new Set([entry]);
+  const queue = [entry];
+  while (queue.length > 0) {
+    const current = queue.pop();
+    for (const to of outgoing.get(current) ?? []) {
+      if (!reachable.has(to)) {
+        reachable.add(to);
+        queue.push(to);
+      }
+    }
+  }
+  const reachesTerminal = new Set(terminal);
+  let grew = true;
+  while (grew) {
+    grew = false;
+    for (const [from, targets] of outgoing) {
+      if (!reachesTerminal.has(from) && targets.some((to) => reachesTerminal.has(to))) {
+        reachesTerminal.add(from);
+        grew = true;
+      }
+    }
+  }
+  for (const id of reachable) {
+    if (!reachesTerminal.has(id)) {
+      throw new WorkflowError(`step "${id}" has no path to a terminal step`);
+    }
+  }
+
+  return {
+    name,
+    entry,
+    steps,
+    stepIds,
+    terminal,
+    edges,
+    policies: doc.policies ?? [],
+    budgets: doc.budgets ?? {},
+  };
+}
+
+export function loadWorkflow(filePath) {
+  return parseWorkflow(readFileSync(filePath, "utf8"));
+}
+
+export function nextStep(workflow, from, outcome) {
+  return workflow.edges.get(`${from}|${outcome}`) ?? null;
+}