@haiyangbg/buildbeat 2.0.0-beta.2 → 2.0.0-beta.4

package/src/v2/domain/event-registry.js

@@ -1,6 +1,8 @@
 // Initial event type registry v1 per docs/v2/SPEC-0001-events-v1.md §4.
 // Semantics are frozen; the registry and per-type data may only grow additively.
 
+import { isAbsolute } from "node:path";
+
 import {
   ACTOR_KINDS,
   BUDGET_KINDS,
@@ -58,6 +60,23 @@ const EVENT_ENUMS = {
   TRIAGE_RECORDED: { action: TRIAGE_ACTIONS },
 };
 
+const REPO_REF_FIELDS = {
+  WORKSPACE_BOUND: ["repo", "worktreePath"],
+  EVIDENCE_RECORDED: ["evidenceRef"],
+  RUN_COMPACTED: ["runRecordRef"],
+  INTENT_DRAFTED: ["intentRef"],
+  TRIAGE_RECORDED: ["intentRef"],
+};
+
+function unsafeRepoRef(value) {
+  return (
+    typeof value !== "string" ||
+    value.length === 0 ||
+    isAbsolute(value) ||
+    /(^|[\\/])\.\.([\\/]|$)/.test(value)
+  );
+}
+
 export class EventInputError extends Error {
   constructor(message) {
     super(message);
@@ -87,6 +106,11 @@ export function validateEventInput(type, actor, data) {
       throw new EventInputError(`event ${type} missing required data field: ${field}`);
     }
   }
+  for (const field of REPO_REF_FIELDS[type] ?? []) {
+    if (unsafeRepoRef(data[field])) {
+      throw new EventInputError(`event ${type} field ${field} must be a repository-relative reference`);
+    }
+  }
   const enums = EVENT_ENUMS[type];
   if (enums) {
     for (const [field, allowed] of Object.entries(enums)) {

package/src/v2/engine/reducer.js

@@ -140,6 +140,11 @@ export function applyEvent(state, event) {
         status: data.status,
         grade: data.grade,
         ...(data.findings ? { findings: data.findings } : {}),
+        ...(data.suppressedFingerprints
+          ? { suppressedFingerprints: data.suppressedFingerprints }
+          : {}),
+        ...(data.cacheKey ? { cacheKey: data.cacheKey } : {}),
+        ...(data.reused ? { reused: data.reused } : {}),
       });
       break;
     }

package/src/v2/engine/workflow.js

@@ -27,7 +27,8 @@ const TOP_FIELDS = new Set([
   "policies",
   "budgets",
 ]);
-const STEP_FIELDS = new Set(["id", "worker", "optional", "requiredWhen", "readonly"]);
+const STEP_FIELDS = new Set(["id", "worker", "optional", "requiredWhen", "readonly", "grade"]);
+const EVIDENCE_GRADES = new Set(["L0", "L1", "L2", "L3", "L4"]);
 const TRANSITION_FIELDS = new Set(["from", "on", "to"]);
 
 function rejectUnknownFields(object, allowed, where) {
@@ -82,6 +83,11 @@ export function parseWorkflow(text) {
     if (raw.readonly !== undefined && typeof raw.readonly !== "boolean") {
       throw new WorkflowError(`step ${id} readonly must be a boolean`);
     }
+    // Evidence grade a step's command evidence is recorded at (iteration 08:
+    // release readbacks run against the real environment and are L4).
+    if (raw.grade !== undefined && !EVIDENCE_GRADES.has(raw.grade)) {
+      throw new WorkflowError(`step ${id} grade must be one of L0-L4`);
+    }
     stepIds.add(id);
     steps.push({
       id,
@@ -89,6 +95,7 @@ export function parseWorkflow(text) {
       optional: raw.optional ?? false,
       requiredWhen: raw.requiredWhen ?? null,
       readonly: raw.readonly ?? false,
+      grade: raw.grade ?? "L2",
     });
   }
 

package/src/v2/evidence/collector.js

@@ -17,21 +17,32 @@ export function collectCommandEvidence({
   kind = "command",
   grade = "L2",
   coverage = null,
+  redact = [],
 }) {
   const logsDir = join(runtimeDir, "runs", runId, "logs");
   mkdirSync(logsDir, { recursive: true });
   const logName = `${step}-${attempt}.log`;
   const logPath = join(logsDir, logName);
+  // Redaction (iteration 08, C6): patterns from the run config are applied
+  // to worker output before it becomes evidence. The digest binds the
+  // redacted text — what is on disk is what was hashed.
+  const scrub = (text) => {
+    let out = String(text ?? "");
+    for (const pattern of redact) {
+      out = out.replace(pattern, "<REDACTED>");
+    }
+    return out;
+  };
   const logBody = [
-    `command: ${execResult.command}`,
+    `command: ${scrub(execResult.command)}`,
     `exitCode: ${execResult.exitCode}`,
     `signal: ${execResult.signal}`,
     `timedOut: ${execResult.timedOut}`,
     `spawnError: ${execResult.spawnError}`,
     "--- stdout ---",
-    execResult.stdout,
+    scrub(execResult.stdout),
     "--- stderr ---",
-    execResult.stderr,
+    scrub(execResult.stderr),
   ].join("\n");
   writeFileSync(logPath, logBody, "utf8");
   const digest = `sha256:${createHash("sha256").update(logBody, "utf8").digest("hex")}`;

package/src/v2/observe/observe.js

@@ -22,6 +22,7 @@ import { collectCommandEvidence } from "../evidence/collector.js";
 import { EventLedger } from "../storage/event-ledger.js";
 import { loadObserveConfig, severityRank } from "./observe-config.js";
 import { OBSERVE_REDUCER } from "./observe-reducer.js";
+import { toRepoRef } from "../runtime/repo-ref.js";
 
 const OBSERVE_IDS = { run: "OBSERVE", work: "OBSERVE" };
 const KERNEL_ACTOR = { kind: "kernel", id: "observe" };
@@ -142,7 +143,7 @@ function recordEvidence({ ledger, config, cycle, provider, execResult, kind, ste
     type: "EVIDENCE_RECORDED",
     actor: { kind: "provider", id: provider.id },
     data: {
-      evidenceRef: record.location,
+      evidenceRef: toRepoRef(config.repoRoot, record.location),
       kind: record.kind,
       subject: record.subject,
       digest: record.digest,
@@ -350,7 +351,13 @@ export function runObserveCycle({ configPath, now = new Date().toISOString() })
     data: { cycle, providersRun: config.providers.length },
     ...OBSERVE_IDS,
   });
-  return { cycle, ledgerPath: ledger.path, results, state: ledger.state };
+  return {
+    cycle,
+    ledgerPath: ledger.path,
+    ledgerRef: toRepoRef(config.repoRoot, ledger.path),
+    results,
+    state: ledger.state,
+  };
 }
 
 export function triageIntent({ repoRoot, intentRef, action, by = "unknown", note, now = new Date().toISOString() }) {

package/src/v2/presets/release-readback.yaml

@@ -0,0 +1,36 @@
+# Release readback lane (iteration 08, C8). The kernel still has no deploy
+# capability (invariant 20): every production action stays a human's. What
+# this lane fixes is the bookkeeping around it — a pilot go-live was
+# ledgered by hand as forty "step N readback" commits. Here each step is a
+# read-only command that proves the world is in the expected state; every
+# failure stops for a human (maxAttempts 1, no fix edge), and evidence is
+# graded L4 because it was read from the real environment.
+#
+# Shape: preflight (before the action) → [human performs the action; the
+# risk preset "release" stops here] → apply-readback (proves it happened) →
+# observe (proves it is healthy) → wait-close (human closes the window).
+kind: workflow
+version: 1
+name: release-readback
+entry: preflight
+steps:
+  - id: preflight
+    worker: readback
+    readonly: true
+    grade: L4
+  - id: apply-readback
+    worker: readback
+    readonly: true
+    grade: L4
+  - id: observe
+    worker: observe
+    readonly: true
+    grade: L4
+  - id: wait-close
+terminal:
+  - wait-close
+budgets:
+  maxAttempts:
+    preflight: 1
+    apply-readback: 1
+    observe: 1

package/src/v2/presets/risk/release.yaml

@@ -0,0 +1,21 @@
+# Release lane (iteration 08, C8): pairs with the release-readback workflow.
+# Automation stops before apply-readback — that pause is where the human
+# performs the production action — and the window may only close behind L4
+# evidence read from the real environment. (No finding floor: the lane has
+# no reviewer step, and a rule that cannot be satisfied is not a gate.)
+kind: risk-preset
+version: 1
+name: release
+stopAt:
+  - apply-readback
+policies:
+  - kind: policy
+    version: 1
+    name: close-evidence-floor
+    type: transition
+    appliesTo: enter-wait-close
+    enforcement: LOCAL_ENFORCED
+    rule:
+      evidence.exists:
+        kind: command
+        minGrade: L4

package/src/v2/presets/software-delivery.yaml

@@ -37,3 +37,8 @@ transitions:
     to: fix
 terminal:
   - wait-merge
+# Review rounds are capped by default (deploy-campaign charter: two review
+# rounds per run, then a human). Override per project via budgets.maxAttempts.
+budgets:
+  maxAttempts:
+    review: 2

package/src/v2/runtime/cache.js

@@ -0,0 +1,124 @@
+// Verification reuse and incremental review (iteration 08, C7).
+//
+// Reuse: a verify step whose input is byte-identical to one that already
+// passed — same tree, same worker command, same envelope — is not re-run; the
+// earlier evidence is referenced and the reuse is visible in the ledger
+// (`reused`) and in status. Only *passed* results are ever reused; a failure
+// always runs again. Real number: the deploy campaign's envelope-side cache
+// cut verify from 25 to 13 minutes per round.
+//
+// Incremental review: a reviewer is told which candidate the last review
+// looked at (when it is an ancestor of the current one) so it can focus on
+// the delta instead of re-reading the whole change every round.
+
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+import { EventLedger } from "../storage/event-ledger.js";
+import { canonicalJson } from "../storage/event-ledger.js";
+
+function git(cwd, args) {
+  return execFileSync("git", ["-C", cwd, ...args], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+  }).trim();
+}
+
+export function treeHash(worktreePath) {
+  return git(worktreePath, ["rev-parse", "HEAD^{tree}"]);
+}
+
+export function cacheKey({ tree, worker, adapterSpec, adapterName, envelopeDigest }) {
+  const body = canonicalJson({
+    tree,
+    worker,
+    adapter: adapterSpec ?? adapterName ?? null,
+    envelope: envelopeDigest ?? null,
+  });
+  return `sha256:${createHash("sha256").update(body, "utf8").digest("hex")}`;
+}
+
+function eachLedger(repoRoot, { excludeRun = null } = {}) {
+  const runsDir = join(repoRoot, ".buildbeat", "runtime", "runs");
+  const out = [];
+  if (!existsSync(runsDir)) {
+    return out;
+  }
+  for (const entry of readdirSync(runsDir).sort()) {
+    if (entry === excludeRun) {
+      continue;
+    }
+    const path = join(runsDir, entry, "events.jsonl");
+    if (!existsSync(path)) {
+      continue;
+    }
+    const ledger = EventLedger.open(path);
+    if (ledger.state.run) {
+      out.push(ledger);
+    }
+  }
+  return out;
+}
+
+// Latest passed command evidence carrying this cache key, across the
+// repository's runs (the current run included: a re-verify after an
+// unrelated fix step on the same tree is the common case).
+export function findReusableEvidence(repoRoot, key) {
+  let best = null;
+  for (const ledger of eachLedger(repoRoot)) {
+    for (const event of ledger.events) {
+      if (
+        event.type === "EVIDENCE_RECORDED" &&
+        event.data.cacheKey === key &&
+        event.data.status === "passed" &&
+        event.data.kind === "command" &&
+        !event.data.reused
+      ) {
+        if (!best || event.ts > best.ts) {
+          best = { run: ledger.state.run.id, evidenceRef: event.data.evidenceRef, digest: event.data.digest, grade: event.data.grade, ts: event.ts };
+        }
+      }
+    }
+  }
+  return best;
+}
+
+// The most recent review evidence for this work whose subject is an ancestor
+// of (and not equal to) the current head — the anchor for an incremental
+// review. Null when there is no such review.
+export function lastReviewedCandidate(repoRoot, workId, worktreePath, head) {
+  let best = null;
+  for (const ledger of eachLedger(repoRoot)) {
+    if (ledger.state.run.work !== workId) {
+      continue;
+    }
+    for (const event of ledger.events) {
+      if (event.type !== "EVIDENCE_RECORDED" || event.data.kind !== "review") {
+        continue;
+      }
+      const subject = event.data.subject;
+      if (!subject || subject === head) {
+        continue;
+      }
+      if (best && event.ts <= best.ts) {
+        continue;
+      }
+      let ancestor = false;
+      try {
+        execFileSync("git", ["-C", worktreePath, "merge-base", "--is-ancestor", subject, head], { stdio: "ignore" });
+        ancestor = true;
+      } catch {
+        ancestor = false;
+      }
+      if (ancestor) {
+        best = { candidate: subject, run: ledger.state.run.id, evidenceRef: event.data.evidenceRef, ts: event.ts };
+      }
+    }
+  }
+  if (!best) {
+    return null;
+  }
+  return { candidate: best.candidate, run: best.run, evidenceRef: best.evidenceRef, range: `${best.candidate}..${head}` };
+}

package/src/v2/runtime/decisions.js

@@ -13,6 +13,7 @@ import { evaluatePolicies, sha256Text } from "../policy/policy.js";
 import { EventLedger } from "../storage/event-ledger.js";
 import { acquireLock, readback, releaseLock } from "../workspace/workspace-manager.js";
 import { writeRunRecord } from "./run-record.js";
+import { resolveRepoRef } from "./repo-ref.js";
 
 const KERNEL = { kind: "kernel", id: "orchestrator" };
 
@@ -68,10 +69,11 @@ export function approveRun(repoRoot, runId, { by = "human", transition, ts, poli
   acquireLock(repoRoot, runId);
   try {
     const bound = ledger.state.workspaces[runId];
-    if (!bound || !existsSync(bound.worktreePath)) {
+    const worktreePath = bound ? resolveRepoRef(repoRoot, bound.worktreePath) : null;
+    if (!bound || !existsSync(worktreePath)) {
       throw new DecisionError(`worktree missing for ${runId}; cannot verify the approval subject`);
     }
-    const tree = readback(bound.worktreePath);
+    const tree = readback(worktreePath);
     const when = ts ?? new Date().toISOString();
     if (tree.dirty || tree.head !== pending.subject.candidate) {
       const lastEvidence = ledger.state.evidence[ledger.state.evidence.length - 1];
@@ -102,8 +104,8 @@ export function approveRun(repoRoot, runId, { by = "human", transition, ts, poli
         state: ledger.state,
         candidate: pending.subject.candidate,
         workDir: join(repoRoot, "delivery", "work", ledger.state.run.work),
-        worktreePath: bound.worktreePath,
-        readWorktree: () => readback(bound.worktreePath),
+        worktreePath,
+        readWorktree: () => readback(worktreePath),
       },
     );
     for (const row of policyRows) {

package/src/v2/runtime/env-contract.js

@@ -0,0 +1,135 @@
+// Environment contract: a run config may declare the binaries (and minimum
+// versions) its frozen envelope silently depends on, and the kernel checks
+// them fail-closed before a run starts. Absorbed from real incidents: a
+// frozen verifier needed `rg` that only a vendored PATH provided, candidate
+// scripts assumed bash >= 4 on a /bin/bash 3.2 host, and a fresh shell
+// resolved Node 14 — each burned runs before anyone saw the real cause.
+
+import { spawnSync } from "node:child_process";
+
+export class EnvContractError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "EnvContractError";
+  }
+}
+
+// Version detection in --version output needs at least major.minor (a bare
+// integer in arbitrary output is too easy to false-match); a declared min
+// may be major-only ("20").
+function parseVersion(text) {
+  const match = String(text).match(/(\d+)\.(\d+)(?:\.(\d+))?/);
+  if (!match) {
+    return null;
+  }
+  return [Number(match[1]), Number(match[2]), Number(match[3] ?? 0)];
+}
+
+function parseMin(value) {
+  const match = String(value).trim().match(/^(\d+)(?:\.(\d+))?(?:\.(\d+))?$/);
+  if (!match) {
+    return null;
+  }
+  return [Number(match[1]), Number(match[2] ?? 0), Number(match[3] ?? 0)];
+}
+
+function compareVersions(left, right) {
+  for (let index = 0; index < 3; index += 1) {
+    if ((left[index] ?? 0) !== (right[index] ?? 0)) {
+      return (left[index] ?? 0) - (right[index] ?? 0);
+    }
+  }
+  return 0;
+}
+
+// Checks every entry and reports all problems at once (a run that dies on
+// the first missing binary hides the second). Non-zero --version exits are
+// tolerated; only a spawn failure means "not runnable".
+export function checkRequires(requires) {
+  const problems = [];
+  const checked = [];
+  for (const entry of requires ?? []) {
+    // Probe entries (iteration 08, C10): an environment fact that is not a
+    // binary version — "Redis answers PING on the target", "python on the
+    // host is >= 3.9" — expressed as a shell command whose exit code (and
+    // optionally output) must match. Absorbed from the first-proof rerun:
+    // Redis < 7 and Python 3.6 on the target burned a window each because
+    // nothing checked them before the run.
+    if (entry && typeof entry === "object" && typeof entry.probe === "string" && entry.probe.length > 0) {
+      const label = entry.name ?? entry.probe;
+      const run = spawnSync("bash", ["-lc", entry.probe], { encoding: "utf8", timeout: entry.timeoutMs ?? 30_000 });
+      if (run.error) {
+        problems.push(`${label}: probe could not run (${run.error.code ?? run.error.message})`);
+        continue;
+      }
+      const output = `${run.stdout ?? ""}\n${run.stderr ?? ""}`;
+      if (run.status !== 0) {
+        problems.push(`${label}: probe exited ${run.status}${output.trim() ? ` — ${output.trim().split("\n").slice(-1)[0].slice(0, 160)}` : ""}`);
+        continue;
+      }
+      if (entry.expect !== undefined) {
+        let matcher;
+        try {
+          matcher = new RegExp(String(entry.expect));
+        } catch {
+          problems.push(`${label}: expect ${JSON.stringify(entry.expect)} is not a valid regular expression`);
+          continue;
+        }
+        if (!matcher.test(output)) {
+          problems.push(`${label}: probe output does not match expect ${JSON.stringify(entry.expect)}`);
+          continue;
+        }
+      }
+      checked.push({ command: label, version: null, probe: true });
+      continue;
+    }
+    if (!entry || typeof entry !== "object" || typeof entry.command !== "string" || entry.command.length === 0) {
+      problems.push(`requires entries need a command name or a probe, got: ${JSON.stringify(entry)}`);
+      continue;
+    }
+    // A generous timeout: a missing binary fails instantly (ENOENT), while a
+    // loaded host must not turn a present binary into a false "not runnable".
+    const probe = spawnSync(entry.command, [entry.versionFlag ?? "--version"], {
+      encoding: "utf8",
+      timeout: 30_000,
+    });
+    if (probe.error) {
+      problems.push(
+        `${entry.command}: not runnable in this environment (${probe.error.code ?? probe.error.message})`,
+      );
+      continue;
+    }
+    const version = parseVersion(`${probe.stdout ?? ""}\n${probe.stderr ?? ""}`);
+    if (entry.min !== undefined) {
+      const min = parseMin(entry.min);
+      if (!min) {
+        problems.push(`${entry.command}: min ${JSON.stringify(entry.min)} is not a version`);
+        continue;
+      }
+      if (!version) {
+        problems.push(
+          `${entry.command}: version undetectable but min ${entry.min} is required (fail closed)`,
+        );
+        continue;
+      }
+      if (compareVersions(version, min) < 0) {
+        problems.push(
+          `${entry.command}: resolves to ${version.join(".")}, below required ${entry.min}`,
+        );
+        continue;
+      }
+    }
+    checked.push({ command: entry.command, version: version ? version.join(".") : null });
+  }
+  return { ok: problems.length === 0, problems, checked };
+}
+
+export function assertRequires(requires) {
+  const result = checkRequires(requires);
+  if (!result.ok) {
+    throw new EnvContractError(
+      `environment contract not satisfied:\n  - ${result.problems.join("\n  - ")}`,
+    );
+  }
+  return result;
+}