chainlesschain 0.166.129 → 0.166.131

package/src/lib/goal-verification-command.js

@@ -0,0 +1,221 @@
+import { createHash, randomUUID } from "node:crypto";
+import executionBroker from "./process-execution-broker/index.js";
+import { terminateOwnedProcessTree } from "./process-tree-termination.js";
+import { redactSecrets } from "./secret-scan.js";
+
+const MAX_OUTPUT_BYTES = 128 * 1024;
+const RESULT_PREFIX = "CC_GOAL_CHECK_RESULT ";
+export const GOAL_CHECK_RESULT_SCHEMA = "chainlesschain.goal-check-result/v1";
+
+function checkReceipt(stdout, check, invocationId) {
+  const lines = stdout
+    .toString("utf8")
+    .split(/\r?\n/u)
+    .filter((line) => line.startsWith(RESULT_PREFIX));
+  if (lines.length !== 1 || lines[0].length > 16 * 1024) return null;
+  try {
+    const receipt = JSON.parse(lines[0].slice(RESULT_PREFIX.length));
+    if (
+      !receipt ||
+      typeof receipt !== "object" ||
+      Array.isArray(receipt) ||
+      Object.keys(receipt).some(
+        (key) =>
+          !["schema", "checkId", "invocationId", "requirements"].includes(key),
+      ) ||
+      receipt.schema !== GOAL_CHECK_RESULT_SCHEMA ||
+      receipt.checkId !== check.id ||
+      receipt.invocationId !== invocationId ||
+      !Array.isArray(receipt.requirements) ||
+      receipt.requirements.length !== check.requirements.length
+    )
+      return null;
+    const ids = new Set();
+    for (const entry of receipt.requirements) {
+      if (
+        !entry ||
+        typeof entry !== "object" ||
+        Array.isArray(entry) ||
+        Object.keys(entry).some((key) => !["id", "passed"].includes(key)) ||
+        !check.requirements.includes(entry.id) ||
+        ids.has(entry.id) ||
+        entry.passed !== true
+      )
+        return null;
+      ids.add(entry.id);
+    }
+    return receipt;
+  } catch {
+    return null;
+  }
+}
+export function goalVerificationError(message, reason = "error") {
+  return Object.assign(new Error(message), {
+    code: "CC_GOAL_VERIFICATION_FAILED",
+    goalVerificationFailure: true,
+    subtype: "error_goal_verification",
+    endReason: reason,
+  });
+}
+
+export function checkGoalVerificationCancellation(signal) {
+  if (signal?.aborted)
+    throw goalVerificationError("Goal verification was cancelled", "cancelled");
+}
+
+function outputEvidence(bytes, truncated) {
+  const text = bytes.toString("utf8");
+  const preview =
+    text.length <= 4000
+      ? text
+      : `${text.slice(0, 1980)}\n[... truncated ...]\n${text.slice(-1980)}`;
+  return {
+    bytes: bytes.length,
+    digest: `sha256:${createHash("sha256").update(bytes).digest("hex")}`,
+    truncated,
+    preview: redactSecrets(preview),
+  };
+}
+
+/** Execute a user-selected, frozen acceptance command, never model tool text.
+ * Use argv without a shell and wait for the actual close / cleanup fence.
+ */
+export async function runGoalVerificationCommand(
+  check,
+  { cwd, signal, timeoutMs } = {},
+) {
+  checkGoalVerificationCancellation(signal);
+  return new Promise((resolve, reject) => {
+    const startedAt = Date.now();
+    const invocationId = randomUUID();
+    let child, timer, stopping, stopReason, spawnError;
+    let closed = false,
+      settled = false,
+      exitCode = null,
+      exitSignal = null;
+    const streams = {
+      stdout: { chunks: [], size: 0, truncated: false },
+      stderr: { chunks: [], size: 0, truncated: false },
+    };
+    const finish = (cleanup) => {
+      if (settled || (stopping && cleanup === undefined)) return;
+      settled = true;
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+      if (cleanup && !cleanup.confirmed) {
+        const error = goalVerificationError(
+          "Goal checker process cleanup is unconfirmed; reconcile it before continuing",
+        );
+        error.cleanup = cleanup;
+        error.verification = {
+          checkId: check.id,
+          status: "cleanup-unconfirmed",
+          manualReviewRequired: true,
+          cleanup,
+        };
+        reject(error);
+        return;
+      }
+      if (signal?.aborted || stopReason === "cancelled") {
+        reject(
+          goalVerificationError("Goal verification was cancelled", "cancelled"),
+        );
+        return;
+      }
+      const stdout = Buffer.concat(streams.stdout.chunks);
+      const receipt = checkReceipt(stdout, check, invocationId);
+      resolve({
+        id: check.id,
+        invocationId,
+        command: { executable: check.executable, args: check.args },
+        exitCode: closed && !spawnError ? exitCode : null,
+        signal: exitSignal,
+        status:
+          stopReason ||
+          (spawnError
+            ? "spawn-failed"
+            : exitCode === 0 && !exitSignal
+              ? receipt
+                ? "passed"
+                : "receipt-invalid"
+              : "failed"),
+        receipt,
+        durationMs: Date.now() - startedAt,
+        stdout: outputEvidence(stdout, streams.stdout.truncated),
+        stderr: outputEvidence(
+          Buffer.concat(streams.stderr.chunks),
+          streams.stderr.truncated,
+        ),
+        ...(cleanup ? { cleanup } : {}),
+      });
+    };
+    const stop = (reason) => {
+      if (settled || stopping) return;
+      stopReason = reason;
+      stopping = Promise.resolve().then(() =>
+        terminateOwnedProcessTree(child, { alreadyClosed: closed }),
+      );
+      stopping.then(finish, () => finish({ confirmed: false }));
+    };
+    const onAbort = () => stop("cancelled");
+    try {
+      // Acceptance programs do not inherit provider credentials or Node preload
+      // hooks. They can read the explicitly selected workspace as ordinary tests.
+      const env = Object.fromEntries(
+        Object.entries(process.env).filter(([key]) =>
+          /^(path|systemroot|windir|temp|tmp|home|userprofile|lang|lc_all)$/i.test(
+            key,
+          ),
+        ),
+      );
+      env.CC_GOAL_CHECK_ID = check.id;
+      env.CC_GOAL_CHECK_INVOCATION = invocationId;
+      child = executionBroker.spawn(
+        check.executable === "node" ? process.execPath : check.executable,
+        check.args,
+        {
+          cwd,
+          env,
+          shell: false,
+          windowsHide: true,
+          detached: process.platform !== "win32",
+          stdio: ["ignore", "pipe", "pipe"],
+          origin: "headless-goal:verification",
+          scope: "headless-goal",
+          policy: "allow",
+        },
+      );
+      for (const name of ["stdout", "stderr"])
+        child[name]?.on("data", (chunk) => {
+          const bytes = Buffer.from(chunk),
+            stream = streams[name];
+          const remaining = MAX_OUTPUT_BYTES - stream.size;
+          if (remaining > 0) {
+            const kept = bytes.subarray(0, remaining);
+            stream.chunks.push(kept);
+            stream.size += kept.length;
+          }
+          if (bytes.length > remaining) {
+            stream.truncated = true;
+            stop("output-limit");
+          }
+        });
+      child.once("error", (error) => {
+        spawnError = error;
+      });
+      child.once("close", (code, childSignal) => {
+        closed = true;
+        exitCode = code;
+        exitSignal = childSignal;
+        finish();
+      });
+      timer = setTimeout(() => stop("timed-out"), timeoutMs);
+      signal?.addEventListener("abort", onAbort, { once: true });
+      if (signal?.aborted) onAbort();
+    } catch (error) {
+      spawnError = error;
+      if (child?.pid) stop("spawn-failed");
+      else finish();
+    }
+  });
+}

package/src/lib/goal-verification-plan.js

@@ -0,0 +1,372 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { captureGoalWorkspace } from "./goal-workspace-evidence.js";
+import { sameGoalWorkspace } from "./goal-check-evidence.js";
+import {
+  checkGoalVerificationCancellation,
+  goalVerificationError,
+  runGoalVerificationCommand,
+} from "./goal-verification-command.js";
+
+export const GOAL_VERIFICATION_SCHEMA = "chainlesschain.goal-verification/v1";
+const PREPARED_SCHEMA = "chainlesschain.prepared-goal-verification/v1";
+const digest = (value) =>
+  `sha256:${createHash("sha256").update(value).digest("hex")}`;
+const fail = (message) => {
+  throw goalVerificationError(message);
+};
+const fileCall = (file) => ({ tool: "read_file", args: { path: file } });
+
+function fields(value, allowed, label) {
+  if (
+    !value ||
+    typeof value !== "object" ||
+    Array.isArray(value) ||
+    Object.keys(value).some((key) => !allowed.includes(key))
+  )
+    fail(`${label} contains unsupported fields`);
+}
+function text(value, label, maximum = 4096) {
+  if (
+    typeof value !== "string" ||
+    !value.trim() ||
+    value.length > maximum ||
+    /[\0\r\n]/u.test(value)
+  )
+    fail(`${label} is invalid`);
+  return value;
+}
+function list(value, label, maximum) {
+  if (!Array.isArray(value) || value.length === 0 || value.length > maximum)
+    fail(`${label} must contain 1-${maximum} entries`);
+  return value;
+}
+function freeze(value) {
+  if (value && typeof value === "object") {
+    Object.values(value).forEach(freeze);
+    Object.freeze(value);
+  }
+  return value;
+}
+function remaining(deadline) {
+  const ms = deadline - Date.now();
+  if (ms <= 0)
+    fail("Goal verification preparation exceeded its resource limit");
+  return ms;
+}
+async function bindFile(
+  file,
+  signal,
+  deadline,
+  maxFileBytes = 8 * 1024 * 1024,
+) {
+  checkGoalVerificationCancellation(signal);
+  const binding = await captureGoalWorkspace(
+    path.dirname(file),
+    fileCall(path.basename(file)),
+    {
+      signal,
+      limits: {
+        maxFileBytes,
+        maxBytes: maxFileBytes,
+        maxMs: Math.min(15_000, remaining(deadline)),
+      },
+    },
+  );
+  checkGoalVerificationCancellation(signal);
+  if (!binding.verified)
+    fail(`Goal checker input is unavailable (${binding.reason}): ${file}`);
+  return { path: file, binding };
+}
+async function readManifest(file, signal, deadline) {
+  const before = await bindFile(file, signal, deadline, 64 * 1024);
+  const handle = await fs.open(file, "r");
+  let bytes;
+  try {
+    const buffer = Buffer.alloc(64 * 1024 + 1);
+    let size = 0;
+    while (size < buffer.length) {
+      checkGoalVerificationCancellation(signal);
+      const next = await handle.read(buffer, size, buffer.length - size, size);
+      if (next.bytesRead === 0) break;
+      size += next.bytesRead;
+    }
+    if (size > 64 * 1024) fail("Goal verification manifest is too large");
+    bytes = buffer.subarray(0, size);
+  } finally {
+    await handle.close();
+  }
+  const after = await bindFile(file, signal, deadline, 64 * 1024);
+  if (
+    !sameGoalWorkspace(before.binding, after.binding) ||
+    digest(bytes) !== before.binding.artifacts[0].digest
+  )
+    fail("Goal verification manifest changed while it was read");
+  let manifest;
+  try {
+    manifest = JSON.parse(
+      new TextDecoder("utf-8", { fatal: true }).decode(bytes),
+    );
+  } catch {
+    fail("Goal verification manifest must be valid UTF-8 JSON");
+  }
+  return { manifest, input: after };
+}
+
+/** Prepare before any author turn. On resume, the original definition and
+ * checker input identities win; replacing a manifest cannot weaken the goal.
+ */
+export async function prepareGoalVerification(condition, cwd, { signal } = {}) {
+  const deadline = Date.now() + 30_000;
+  const manifestPath = path.resolve(cwd, text(condition.path, "manifest path"));
+  const { manifest, input } = await readManifest(
+    manifestPath,
+    signal,
+    deadline,
+  );
+  fields(
+    manifest,
+    ["schema", "checks", "artifacts"],
+    "Goal verification manifest",
+  );
+  if (manifest.schema !== GOAL_VERIFICATION_SCHEMA)
+    fail("Unknown Goal verification manifest schema");
+  const root = await fs.realpath(path.resolve(cwd));
+  const artifacts = list(manifest.artifacts, "artifacts", 32).map((name) => {
+    const target = path.resolve(root, text(name, "artifact path"));
+    const relative = path.relative(root, target);
+    if (
+      !relative ||
+      relative === ".." ||
+      relative.startsWith(`..${path.sep}`) ||
+      path.isAbsolute(relative)
+    )
+      fail("Goal verification artifacts must be files inside the workspace");
+    return relative.split(path.sep).join("/");
+  });
+  const ids = new Set(),
+    inputs = new Map([[manifestPath, input]]);
+  const checks = [];
+  for (const value of list(manifest.checks, "checks", 8)) {
+    fields(
+      value,
+      ["id", "executable", "args", "checkerFiles", "timeoutMs", "requirements"],
+      "Goal check",
+    );
+    const id = text(value.id, "check id", 80);
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/u.test(id) || ids.has(id))
+      fail("Goal check IDs must be distinct identifiers");
+    ids.add(id);
+    const requirements = list(value.requirements, "requirements", 32).map(
+      (requirement) => text(requirement, "requirement ID", 80),
+    );
+    if (
+      new Set(requirements).size !== requirements.length ||
+      requirements.some(
+        (requirement) => !/^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/u.test(requirement),
+      )
+    )
+      fail("Requirement IDs must be distinct identifiers within each check");
+    const executable = text(value.executable, "checker executable");
+    if (executable !== "node" && !path.isAbsolute(executable))
+      fail("Use node or an absolute checker executable path");
+    if (
+      !Array.isArray(value.args) ||
+      value.args.length > 64 ||
+      value.args.some(
+        (arg) =>
+          typeof arg !== "string" || arg.length > 4096 || arg.includes("\0"),
+      )
+    )
+      fail("Goal checker args must be a bounded string array");
+    const timeoutMs = value.timeoutMs ?? 30_000;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 60_000)
+      fail("Goal checker timeout must be 1-60000ms");
+    const checkerFiles = [];
+    for (const name of list(value.checkerFiles, "checkerFiles", 32)) {
+      const file = path.resolve(
+        path.dirname(manifestPath),
+        text(name, "checker input"),
+      );
+      if (
+        artifacts.some(
+          (artifact) =>
+            path.relative(file, path.resolve(root, artifact)) === "",
+        )
+      )
+        fail("A mutable deliverable cannot also be a frozen checker input");
+      if (!inputs.has(file)) {
+        if (inputs.size >= 65) fail("Too many frozen checker inputs");
+        inputs.set(file, await bindFile(file, signal, deadline));
+      }
+      checkerFiles.push(file);
+    }
+    checks.push({
+      id,
+      executable,
+      args: [...value.args],
+      checkerFiles,
+      timeoutMs,
+      requirements,
+    });
+  }
+  const prepared = {
+    schema: PREPARED_SCHEMA,
+    workspace: root,
+    manifestPath,
+    checks,
+    artifacts,
+    inputs: [...inputs.values()],
+  };
+  const planDigest = digest(JSON.stringify(prepared));
+  if (
+    condition.verification &&
+    (condition.verification.schema !== PREPARED_SCHEMA ||
+      condition.verification.digest !== planDigest)
+  )
+    fail(
+      "The frozen Goal verification definition changed; resume cannot replace its acceptance checks",
+    );
+  return freeze({
+    ...condition,
+    verification: { ...prepared, digest: planDigest },
+  });
+}
+
+async function currentInputs(plan, signal) {
+  const deadline = Date.now() + 30_000;
+  for (const input of plan.inputs) {
+    try {
+      const current = await bindFile(input.path, signal, deadline);
+      if (!sameGoalWorkspace(input.binding, current.binding)) return false;
+    } catch {
+      checkGoalVerificationCancellation(signal);
+      return false;
+    }
+  }
+  return true;
+}
+async function captureInputs(plan, signal) {
+  checkGoalVerificationCancellation(signal);
+  const source = await captureGoalWorkspace(
+    plan.workspace,
+    { tool: "run_shell" },
+    { signal },
+  );
+  const artifacts = [];
+  for (const artifact of plan.artifacts) {
+    checkGoalVerificationCancellation(signal);
+    artifacts.push(
+      await captureGoalWorkspace(plan.workspace, fileCall(artifact), {
+        signal,
+      }),
+    );
+  }
+  checkGoalVerificationCancellation(signal);
+  return {
+    source,
+    artifacts,
+    verified: source.verified && artifacts.every((entry) => entry.verified),
+  };
+}
+function sameInputs(left, right) {
+  return (
+    sameGoalWorkspace(left.source, right.source) &&
+    left.artifacts.length === right.artifacts.length &&
+    left.artifacts.every((entry, index) =>
+      sameGoalWorkspace(entry, right.artifacts[index]),
+    )
+  );
+}
+
+/** All independently declared checks must pass against one unchanged candidate.
+ * The author/model cannot supply the command result or select a passing subset.
+ */
+export async function evaluateGoalVerification(
+  condition,
+  {
+    cwd,
+    signal,
+    deadline = Infinity,
+    runCommand = runGoalVerificationCommand,
+    onCheckStart = () => {},
+  } = {},
+) {
+  checkGoalVerificationCancellation(signal);
+  const plan = condition.verification;
+  if (!plan || plan.schema !== PREPARED_SCHEMA)
+    fail("Goal verification was not prepared before the author turn");
+  if ((await fs.realpath(path.resolve(cwd))) !== plan.workspace)
+    fail("Goal verification workspace changed");
+  const evidence = {
+    kind: "verification",
+    source: "host-prepared-checks",
+    planDigest: plan.digest,
+    manifestPath: plan.manifestPath,
+    requiredChecks: plan.checks.map((check) => check.id),
+    checks: [],
+    checkerInputs: plan.inputs,
+    coverage: { required: plan.checks.length, executed: 0, passed: 0 },
+    manualReviewRequired: false,
+  };
+  const unmet = (reason) => ({ met: false, reason, evidence });
+  if (Date.now() >= deadline)
+    return unmet("Goal time budget exhausted before independent verification");
+  if (!(await currentInputs(plan, signal)))
+    fail(
+      "Frozen Goal checker inputs changed; stop and review the acceptance definition",
+    );
+  const before = await captureInputs(plan, signal);
+  evidence.workspace = before;
+  if (!before.verified)
+    return unmet(
+      "Goal source or required artifact evidence is missing or incomplete",
+    );
+  for (const check of plan.checks) {
+    checkGoalVerificationCancellation(signal);
+    await onCheckStart({
+      met: false,
+      reason: `Independent Goal check ${check.id} is starting`,
+      evidence: { ...structuredClone(evidence), pendingCheckId: check.id },
+    });
+    checkGoalVerificationCancellation(signal);
+    const remainingMs = deadline - Date.now();
+    if (remainingMs <= 0)
+      return unmet(
+        "Goal time budget exhausted before independent verification",
+      );
+    const result = await runCommand(check, {
+      cwd: plan.workspace,
+      signal,
+      timeoutMs: Math.min(check.timeoutMs, remainingMs),
+    });
+    checkGoalVerificationCancellation(signal);
+    evidence.checks.push(result);
+    evidence.coverage.executed++;
+    if (!(await currentInputs(plan, signal)))
+      fail(
+        "Frozen Goal checker inputs changed during verification; stop and review",
+      );
+    const after = await captureInputs(plan, signal);
+    evidence.workspaceCurrent = after.verified && sameInputs(before, after);
+    if (!evidence.workspaceCurrent)
+      return unmet(
+        "Goal source or artifacts changed during independent verification",
+      );
+    if (result?.status !== "passed" || result.exitCode !== 0 || result.signal)
+      return unmet(
+        `Independent Goal check ${check.id} did not pass (${result?.status || "unknown"})`,
+      );
+    evidence.coverage.passed++;
+  }
+  if (Date.now() >= deadline)
+    return unmet("Goal time budget expired before verification settled");
+  checkGoalVerificationCancellation(signal);
+  return {
+    met: true,
+    reason:
+      "All independent Goal checks passed for the current source and required artifacts",
+    evidence,
+  };
+}