@uchibeke/gallivant 0.0.0-stage → 0.2.0

package/lib/runtime_node.mjs

@@ -0,0 +1,107 @@
+import { join, isAbsolute } from "node:path";
+import { readJson, writeJsonAtomic, ensureDir } from "./fs.mjs";
+import { acquireRuntimeOwner } from "./daemon.mjs";
+import { makeTick } from "./tick.mjs";
+import { createCoordinator } from "./coordinator.mjs";
+import { deliveryError } from "./task_delivery_contract.mjs";
+import { runtimePinManifest, assertRuntimePin } from "./runtime_state.mjs";
+
+export const NODE_RUNTIME_REQUIREMENTS = Object.freeze({ runtime: "node>=22", store: "durable single-host volume", replicas: 1,
+  dependencies: ["git", "gh", "isolated verification sandbox", "configured provider transports"],
+  pagesRemedy: "Keep Pages for OAuth/MCP/UI. Route authorized operations through an authenticated binding to one Node 22 coordinator with Git/gh, durable volume and external wake-up scheduling. Codex Cloud additionally needs the pinned CLI and its trusted operator account; environment repository verification remains blocked. Evaluate an existing Node-capable runtime or Cloudflare Container before provisioning; do not add a mandatory Worker." });
+
+export function createNodeOwnerStore({ home, durable = false, replicas = 1 }) {
+  if (!isAbsolute(home || "") || !durable || replicas !== 1) throw deliveryError("COORDINATOR_STORE", "Configure an absolute durable volume and exactly one single-host replica; filesystem locks are not distributed leases");
+  ensureDir(home);
+  return { withOwner: async fn => {
+    const lock = acquireRuntimeOwner(home), file = join(home, "coordinator.json");
+    try {
+      const previous = readJson(file, { fence: 0, version: 1 });
+      if (previous.version !== 1) throw deliveryError("COORDINATOR_VERSION", "Stop wake-ups and restore the matching coordinator package/state backup");
+      const fence = previous.fence + 1, instance = lock.owner.instance;
+      writeJsonAtomic(file, { ...previous, version: 1, fence, instance });
+      const owner = { fence, processIdentity: `${lock.owner.pid}:${lock.owner.identity}`, assertCurrent: () => {
+        const current = readJson(file), locked = readJson(join(home, "daemon.lock"));
+        if (current?.fence !== fence || current.instance !== instance || locked?.instance !== instance) throw deliveryError("COORDINATOR_FENCE", "Coordinator ownership changed; stale effects are forbidden");
+      }, checkpoint: () => readJson(file), saveCheckpoint: patch => {
+        owner.assertCurrent(); writeJsonAtomic(file, { ...readJson(file), ...patch, version: 1, fence, instance });
+      } };
+      return await fn(owner);
+    } finally { lock.release(); }
+  } };
+}
+
+// Fence each I/O boundary, including continuations after an await. Store adapters
+// used across machines must enforce fencing in their own atomic transactions.
+function fenced(value, owner) {
+  if (!value || typeof value !== "object") return value;
+  return new Proxy(value, { get(target, key) {
+    const member = target[key];
+    if (typeof member !== "function") return member;
+    return (...args) => { const pending = owner.assertCurrent(); if (pending?.then) throw deliveryError("COORDINATOR_STORE", "The Node adapter requires synchronous fence checks; use its durable single-host owner adapter"); return member.apply(target, args); };
+  } });
+}
+
+export function createNodeCoordinator({ ctx, store, schedule, manifest, maxEntries = 20, maxChains = 10, intervalMs = 10000 }) {
+  manifest = runtimePinManifest(manifest);
+  const validatePin = () => assertRuntimePin({ home: ctx.home, manifest });
+  validatePin();
+  // A delayed callback can outlive an idle migration. Validate under ownership
+  // before the portable envelope schedules or advances any task work.
+  if (typeof store?.withOwner !== "function") throw deliveryError("COORDINATOR_CONFIG", "Inject a durable fenced owner store");
+  const pinnedStore = { withOwner: fn => store.withOwner(async owner => {
+    await owner.assertCurrent();
+    validatePin();
+    return fn(owner);
+  }) };
+  if (!Number.isSafeInteger(maxEntries) || maxEntries < 1 || !Number.isSafeInteger(maxChains) || maxChains < 0) throw deliveryError("COORDINATOR_CONFIG", "Specify bounded entry/chain batches");
+  let lastEntry = null;
+  return createCoordinator({ store: pinnedStore, schedule, clock: ctx.clock || Date, intervalMs, advance: async owner => {
+    // All workflow/review decisions still live in makeTick. Only the bounded
+    // registry window changes; context transports/credentials are injected.
+    const checkpoint = owner.checkpoint?.() || {};
+    const startupReconciliation = checkpoint.processIdentity !== owner.processIdentity;
+    // Ignore legacy numeric offsets: replay from the beginning rather than risk
+    // skipping an entry after removals. New processes also restart the sweep.
+    const after = startupReconciliation && checkpoint.startupProcessIdentity !== owner.processIdentity ? null :
+      Object.hasOwn(checkpoint, "entryCursor") ? checkpoint.entryCursor : lastEntry;
+    const entries = ctx.state.entries().sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+    const window = entries.filter(([id]) => !after || id > after), selected = window.slice(0, maxEntries);
+    const entryCursor = window.length > maxEntries ? selected.at(-1)[0] : null;
+    // Keyset rotation remains fair when earlier chains finish or are cancelled.
+    // Retained history is never eligible for canonical tickChains processing.
+    owner.assertCurrent();
+    const activeChains = ctx.state.chains().filter(([, chain]) => chain.status === "active").sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+    const chainWindow = activeChains.filter(([name]) => !checkpoint.chainCursor || name > checkpoint.chainCursor);
+    const selectedChains = chainWindow.slice(0, maxChains);
+    const chainCursor = maxChains === 0 ? checkpoint.chainCursor ?? null : chainWindow.length > maxChains ? selectedChains.at(-1)[0] : null;
+    const state = fenced(ctx.state, owner);
+    let chainsPolled = false;
+    // Plain makeContext() embedders have not gone through the CLI daemon boot,
+    // which normally resolves this same authenticated identity before makeTick.
+    const ownLogin = ctx.ownLogin || await fenced(ctx.gh, owner).user();
+    owner.assertCurrent();
+    const deps = { ...ctx, ownLogin, startupReconciliation,
+      // Complete an unfinished sweep before waiting; never revisit its prefix.
+      // Otherwise restore makeTick's own review deadline across process wakes.
+      nextChainAt: maxChains === 0 ? Infinity : checkpoint.chainCursor ? 0 : checkpoint.nextChainAt ?? 0,
+      state: new Proxy(state, { get(target, key) {
+      if (key === "entries") return () => { owner.assertCurrent(); return selected; };
+      if (key === "chains") return () => { owner.assertCurrent(); chainsPolled = true; return selectedChains; };
+      return target[key];
+    } }), gh: fenced(ctx.gh, owner), git: fenced(ctx.git, owner), notify: fenced(ctx.notify, owner),
+      credential: (...args) => { owner.assertCurrent(); return ctx.credential(...args); },
+      runnerFor: (...args) => { owner.assertCurrent(); return fenced(ctx.runnerFor(...args), owner); },
+      ...(ctx.executionFor ? { executionFor: (...args) => { owner.assertCurrent(); return fenced(ctx.executionFor(...args), owner); } } : {}),
+    };
+    const tick = makeTick(deps), result = await tick.tick();
+    owner.saveCheckpoint?.({ cursor: 0, entryCursor,
+      ...(chainsPolled ? { chainCursor, nextChainAt: tick.nextChainAt } : {}),
+      startupProcessIdentity: startupReconciliation && entryCursor !== null ? owner.processIdentity : null,
+      // Commit restart completion only after every bounded entry batch ran.
+      ...(!startupReconciliation || entryCursor === null ? { processIdentity: owner.processIdentity } : {}),
+    });
+    lastEntry = entryCursor;
+    return result;
+  } });
+}

package/lib/runtime_state.mjs

@@ -0,0 +1,174 @@
+import { join, dirname } from "node:path";
+import { readdirSync, lstatSync, readFileSync, writeFileSync, mkdirSync, existsSync, rmSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { readJson, writeJsonAtomic, canonicalPath } from "./fs.mjs";
+import { acquireRuntimeOwner, acquireTaskMutation } from "./daemon.mjs";
+import { assertCompatible, CORE_VERSION, deliveryError } from "./task_delivery_contract.mjs";
+import { learningStore } from "./learning_store.mjs";
+import { controlPending } from "./control.mjs";
+import { executionLive } from "./execution.mjs";
+import { preparationCancellationPending } from "./task_prepare.mjs";
+import { completionStopsAutomation } from "./task_completion.mjs";
+import { learningDeliveryPending } from "./learning_input.mjs";
+const paths = ["state.json", "learning", "tasks", "prds", "runs", "delivery", "coordinator.json", "runtime-pin.json"];
+const sha = bytes => createHash("sha256").update(bytes).digest("hex");
+// Repository snapshots can contain any of these basenames. Only the layouts
+// written by taskStore, context.executionFor and createDeliveryStore are owned.
+const intakePath = path => /^tasks\/task-[a-f0-9]{24}\/intake\.json$/.test(path);
+const deliveryPath = path => /^delivery\/[a-f0-9]{64}\/delivery\.json$/.test(path);
+const ledgerPath = path => /^runs\/[^/]+\/(?:execution|agents|cloud)\.json$/.test(path);
+const processLockPath = path => /^learning\/operation\.lock(?:\.recovery)?$/.test(path) || /^(?:tasks\/task-[a-f0-9]{24}\/intake|runs\/[^/]+\/(?:execution|publication)|delivery\/[a-f0-9]{64}\/delivery)\.lock(?:\.recovery)?$/.test(path);
+function files(root, prefix = "") {
+  const result = [];
+  for (const name of readdirSync(join(root, prefix))) {
+    const path = join(prefix, name), stat = lstatSync(join(root, path));
+    if (stat.isSymbolicLink()) throw deliveryError("RUNTIME_STATE", "State backup refuses symlinks; inspect the durable volume");
+    if (processLockPath(path)) continue;
+    if (stat.isDirectory()) result.push(...files(root, path));
+    else if (stat.isFile()) result.push(path);
+  }
+  return result;
+}
+function stateFiles(home) {
+  return paths.filter(p => existsSync(join(home, p))).flatMap(path => {
+    const stat = lstatSync(join(home, path));
+    if (stat.isSymbolicLink()) throw deliveryError("RUNTIME_STATE", "State backup refuses symlinks; inspect the durable volume");
+    if (stat.isDirectory()) return files(home, path);
+    if (!stat.isFile()) throw deliveryError("RUNTIME_STATE", "State contains an unsupported filesystem object");
+    return [path];
+  });
+}
+// Capture the process artifact once; never learn its identity from mutable state.
+export function runtimePinManifest(manifest = {}) {
+  assertCompatible(manifest || {});
+  if (manifest.coreVersion !== CORE_VERSION || !/^[a-f0-9]{64}$/.test(manifest.coreSha256 || "")) throw deliveryError("COORDINATOR_PIN", "Supply this package artifact's exact emitted runtime.json; drain active jobs before changing packages");
+  return Object.freeze({ ...manifest });
+}
+export function assertRuntimePin({ home, manifest }) {
+  const pin = readJson(join(home, "runtime-pin.json"));
+  if (pin?.version !== 1 || pin.coreVersion !== manifest.coreVersion || pin.coreSha256 !== manifest.coreSha256) throw deliveryError("COORDINATOR_PIN", "Run task-delivery-state migrate with this package artifact's exact runtime.json before enabling mutations or wake-ups");
+  checkRuntimeState({ home, manifest });
+}
+
+export function checkRuntimeState({ home, manifest }) {
+  assertCompatible(manifest);
+  const state = readJson(join(home, "state.json"), { version: 1, entries: {} });
+  if (state.version !== 1) throw deliveryError("RUNTIME_STATE", "Unsupported registry; restore its matching backup/package before restart");
+  const pin = readJson(join(home, "runtime-pin.json"));
+  // Qualified handoffs and confirmed cancellations retain their registry history.
+  // Unlike scheduling, migration still pins unresolved needs-human work. Pending
+  // controls and live execution pin the artifact independently of registry state.
+  const cancelled = e => e.state === "needs-human" && e.reason === "cancelled" && e.dispatch_stopped &&
+    !controlPending(e.control) && !executionLive(e);
+  let active = Object.values(state.entries).some(e => controlPending(e.control) || executionLive(e) || learningDeliveryPending(e) ||
+    e.state !== "done" && !cancelled(e) && !completionStopsAutomation(e)) || Object.keys(state.starts || {}).length > 0 ||
+    Object.values(state.chains || {}).some(c => !["done", "cancelled"].includes(c.status));
+  for (const rel of stateFiles(home)) {
+      if (intakePath(rel) || ledgerPath(rel) || deliveryPath(rel)) {
+        const record = readJson(join(home, rel));
+        if (record?.version !== 1) throw deliveryError("RUNTIME_STATE", `Unsupported ${rel}; preserve it and migrate with its original package`);
+        if (deliveryPath(rel)) {
+          // Delivery intent can precede intake creation; unfinished scheduling
+          // also belongs to the original artifact, including safety controls.
+          for (const key of ["operations", "cancellations"]) {
+            const receipts = record[key] ?? {};
+            if (typeof receipts !== "object" || Array.isArray(receipts)) throw deliveryError("RUNTIME_STATE", `Unsupported ${rel} receipts; preserve them and recover with their original package`);
+            active ||= Object.values(receipts).some(receipt => receipt?.status !== "acknowledged" || Boolean(receipt.wakePending));
+          }
+        } else if (intakePath(rel)) {
+          const attempts = record.attempts || [];
+          // Intake/readiness can own work before implementation registration,
+          // including blocked attempts whose cancellation is still unresolved.
+          // Successful starts retain historical intent alongside their acknowledged
+          // implementation; only unresolved intent independently pins the intake.
+          const dispatchPending = record.dispatchIntent && (record.status !== "started" || !record.dispatchIntent.id || record.implementation?.id !== record.dispatchIntent.id);
+          active ||= Boolean(dispatchPending) || ["preparing", "validating"].includes(record.status) || record.readiness?.pending === true ||
+            attempts.some(attempt => attempt.settled !== true || attempt.execution && executionLive({ execution: attempt.execution })) ||
+            preparationCancellationPending({ ...record, attempts });
+        } else if (/execution\.json$/.test(rel)) {
+          // Use the canonical liveness rule; unknown acceptance and uncollected
+          // terminal results cannot qualify an idle namespace.
+          active ||= executionLive(record.current) || Object.values(record.operations || {}).some(op => op.acceptance !== "accepted");
+        }
+      }
+  }
+  if (active && (!pin || pin.coreSha256 !== manifest.coreSha256)) throw deliveryError("RUNTIME_ACTIVE_PIN", "Active jobs pin the old artifact. Keep their runtime, stop new intake and drain them; stage the update in another namespace. Do not replace active-job code.");
+  return { compatible: true, active, pinned: pin?.coreSha256 || null, entries: Object.keys(state.entries).length };
+}
+// CLI writes can coexist with the daemon, but maintenance excludes both owners.
+function acquireMaintenance(home) {
+  const runtime = acquireRuntimeOwner(home);
+  try {
+    const task = acquireTaskMutation(home);
+    try {
+      const releaseLearning = learningStore(join(canonicalPath(home), "learning")).lock();
+      return { release() { try { releaseLearning(); } finally { try { task.release(); } finally { runtime.release(); } } } };
+    } catch (error) { task.release(); throw error; }
+  } catch (error) { runtime.release(); throw error; }
+}
+export function migrateRuntimeState({ home, manifest }) {
+  const lock = acquireMaintenance(home);
+  try {
+    const result = checkRuntimeState({ home, manifest });
+    if (!/^[a-f0-9]{64}$/.test(manifest.coreSha256 || "")) throw deliveryError("RUNTIME_STATE", "Use the exact emitted runtime.json with its artifact digest");
+    writeJsonAtomic(join(home, "runtime-pin.json"), { version: 1, coreVersion: manifest.coreVersion, coreSha256: manifest.coreSha256 });
+    return result;
+  } finally { lock.release(); }
+}
+function checkBackupPin(pin, manifest) {
+  if (!/^[a-f0-9]{64}$/.test(manifest.coreSha256 || "")) throw deliveryError("RUNTIME_STATE", "Use the exact emitted runtime.json with its artifact digest");
+  if (pin !== undefined && (pin?.version !== 1 || pin.coreSha256 !== manifest.coreSha256 || pin.coreVersion !== manifest.coreVersion)) {
+    throw deliveryError("RUNTIME_STATE", "Backup and rollback require the currently pinned artifact's runtime.json; use the pre-upgrade manifest, then migrate with the candidate separately");
+  }
+}
+export function backupRuntimeState({ home, out, manifest }) {
+  home = canonicalPath(home); out = canonicalPath(out);
+  if (out === home || out.startsWith(home + "/") || home.startsWith(out + "/")) throw deliveryError("RUNTIME_STATE", "Backup must be outside the durable namespace");
+  const lock = acquireMaintenance(home);
+  try {
+    checkRuntimeState({ home, manifest });
+    const pinPath = join(home, "runtime-pin.json");
+    checkBackupPin(existsSync(pinPath) ? readJson(pinPath) : undefined, manifest);
+    mkdirSync(out, { mode: 0o700 });
+    const hashes = {};
+    for (const rel of stateFiles(home)) {
+      mkdirSync(dirname(join(out, rel)), { recursive: true, mode: 0o700 });
+      const bytes = readFileSync(join(home, rel));
+      writeFileSync(join(out, rel), bytes, { mode: 0o600 }); hashes[rel] = sha(bytes);
+    }
+    writeJsonAtomic(join(out, "backup.json"), { version: 1, coreSha256: manifest.coreSha256, hashes });
+    return { backup: out, files: Object.keys(hashes).length };
+  } finally { lock.release(); }
+}
+export function restoreRuntimeState({ backup, out, manifest }) {
+  if (lstatSync(backup).isSymbolicLink() || lstatSync(join(backup, "backup.json")).isSymbolicLink()) throw deliveryError("RUNTIME_STATE", "Unsafe backup path");
+  const record = readJson(join(backup, "backup.json"));
+  assertCompatible(manifest);
+  if (record?.version !== 1 || record.coreSha256 !== manifest.coreSha256) throw deliveryError("RUNTIME_STATE", "Restore the matching package artifact and backup; never mix state and code");
+  if (!record.hashes || typeof record.hashes !== "object" || Array.isArray(record.hashes)) throw deliveryError("RUNTIME_STATE", "Invalid backup manifest");
+  const validated = [];
+  for (const [path, hash] of Object.entries(record.hashes)) {
+    const parts = path.split("/");
+    if (processLockPath(path) || !paths.some(p => path === p || path.startsWith(p + "/")) || parts.some(p => ["..", ".", ""].includes(p)) || path.includes("\\") || !/^[a-f0-9]{64}$/.test(hash)) throw deliveryError("RUNTIME_STATE", "Unsafe backup path");
+    for (let i = 1; i <= parts.length; i++) {
+      const stat = lstatSync(join(backup, ...parts.slice(0, i)));
+      if (stat.isSymbolicLink() || (i === parts.length ? !stat.isFile() : !stat.isDirectory())) throw deliveryError("RUNTIME_STATE", "Unsafe backup path");
+    }
+    const bytes = readFileSync(join(backup, path));
+    if (sha(bytes) !== hash) throw deliveryError("RUNTIME_STATE", "Backup hash changed; restore the original immutable backup");
+    validated.push([path, bytes]);
+  }
+  // The backup envelope and copied pin must identify the same artifact, even
+  // for idle state (the ordinary state check intentionally allows idle upgrades).
+  const savedPin = validated.find(([path]) => path === "runtime-pin.json");
+  checkBackupPin(savedPin ? JSON.parse(savedPin[1].toString("utf8")) : undefined, manifest);
+  // Validate every file before creating a fresh private namespace.
+  mkdirSync(out, { mode: 0o700 });
+  try {
+    for (const [path, bytes] of validated) {
+      mkdirSync(dirname(join(out, path)), { recursive: true, mode: 0o700 });
+      writeFileSync(join(out, path), bytes, { mode: 0o600 });
+    }
+    return checkRuntimeState({ home: out, manifest });
+  } catch (error) { rmSync(out, { recursive: true, force: true }); throw error; }
+}

package/lib/sources/index.mjs

@@ -0,0 +1,27 @@
+// One gate, many sources. The contract in lib/prd.mjs takes a Request rather than a parsed file:
+//
+//     { id, repo, title, body, harness, status, source: { kind, url, author }, raw }
+//
+// plus the parsed fields the rules read (sections, titles, words, meta). Today the only adapter is the PRD file, and
+// the shape is identical to what `parsePrd` always returned, so nothing about reading a PRD changed. What changed is
+// that the rules no longer reach for a file: `repo` is a field the source supplies, and `source.kind` is what a
+// kind-specific rule is checked against.
+//
+// This registry exists so a second source (a GitHub issue, and later Slack or a ticket) is an adapter plus a place to
+// record its verdict, not a second gate. None of those is built. There is exactly one adapter below.
+import * as prd from "./prd.mjs";
+
+export const ADAPTERS = Object.freeze([prd]);
+
+export const adapterFor = input => ADAPTERS.find(a => a.matches(input)) ?? null;
+
+export const adapterOfKind = kind => ADAPTERS.find(a => a.kind === kind) ?? null;
+
+/** The Request for whatever the operator typed. `deps` carries the dependencies a source needs, `git` for this one. */
+export async function requestFor(input, deps = {}) {
+  const adapter = adapterFor(input);
+  if (!adapter) throw new Error(`nothing can read "${input}": give a path to a PRD file`);
+  return adapter.load(input, deps);
+}
+
+export { prd };

package/lib/sources/prd.mjs

@@ -0,0 +1,50 @@
+// The PRD source: a markdown file in the operator's own checkout.
+//
+// Behaviour is unchanged from before the Request shape existed: parse the frontmatter for `status` and `harness`,
+// take the id from the filename, let the contract read the body's sections, and find the target repository by asking
+// git which checkout the file is in. What is new is that the answer is a field on the Request instead of something
+// `start` works out for itself, so the rest of the pipeline never has to know the brief was a file.
+import { basename, dirname, relative, resolve } from "node:path";
+import { parsePrd } from "../prd.mjs";
+import { readText } from "../fs.mjs";
+import { repositoryPath } from "../repository_files.mjs";
+
+export const kind = "prd";
+
+/**
+ * A filesystem path. `matches` is what the registry uses to pick this source, and it declines anything with a URL
+ * scheme so a future source that reads one is not shadowed by a stray relative path.
+ */
+export const matches = input => typeof input === "string" && input.length > 0 && !/^[a-z][a-z0-9+.-]*:\/\//i.test(input);
+
+/**
+ * The Request for one PRD file.
+ *
+ * `repo` is `owner/name` and comes from the file's own git checkout: a PRD lives inside the repository it describes,
+ * which is how this has always worked. `checkout` and `relPath` come with it, because the brief has to be copied into
+ * the session's fresh clone at the path it has in the operator's tree. A file outside a checkout fails here, with
+ * git's own message, which is the right place for it: the caller never has to hold a half-resolved Request.
+ *
+ * `git` and `gh` are injected. Omit them and you get the parsed Request with `repo` unset, which is what a caller
+ * that only wants to run the contract needs; `gallivant ready` takes that shape through `request` below.
+ */
+export async function load(input, { git = null, gh = null } = {}) {
+  const path = resolve(input);
+  const text = readText(path);
+  if (text === null) throw new Error(`cannot read ${path}`);
+  const req = request(text, path);
+  if (!git || !gh) return req;
+  const checkout = await git.toplevel(dirname(path));
+  repositoryPath(checkout, relative(checkout, path));
+  const { nameWithOwner, defaultBranch } = await gh.repoInfo(checkout);
+  return { ...req, repo: nameWithOwner, defaultBranch, checkout, relPath: relative(checkout, path) };
+}
+
+/**
+ * The Request for PRD text at a path, with no filesystem, git or GitHub access. `parsePrd` already builds it: a
+ * parsed PRD file is a Request whose `source.kind` is "prd".
+ */
+export const request = (text, path) => parsePrd(text, path);
+
+/** The filename, for messages that name the file rather than the id. */
+export const fileOf = req => (req.path ? basename(req.path) : req.id);

package/lib/start_contract.mjs

@@ -0,0 +1,37 @@
+// Shared approval boundary for immediate starts and queued starts. Hash exactly the bytes start will copy.
+import { createHash } from "node:crypto";
+import { check, renderCheck, sourcePathsOf } from "./prd.mjs";
+import { validateContextPaths, parseContextPathsMeta } from "./config.mjs";
+import { readRepositoryText } from "./repository_files.mjs";
+
+export function validateStartRequest(request, config, path) {
+  const verdict = check(request);
+  if (!verdict.ok) throw new Error(`PRD fails the contract; nothing started.\n\n${renderCheck(request, verdict)}`);
+  if (request.status !== "ready") throw new Error(`PRD status is "${request.status}". Run \`gallivant ready ${path}\` first.`);
+  if (!config.harness[request.harness]) throw new Error(`harness "${request.harness}" is not configured in config.json`);
+  const problems = validateContextPaths(parseContextPathsMeta(request.meta?.context_paths), config.home, `${request.id} frontmatter context_paths`);
+  if (problems.length) throw new Error(`PRD frontmatter problems; nothing started.\n  - ${problems.join("\n  - ")}`);
+}
+
+export const contentDigest = text => text === null ? null : createHash("sha256").update(text).digest("hex");
+
+export function captureStartInput(request, base) {
+  const sources = sourcePathsOf(request).map(rel => {
+    const text = readRepositoryText(request.checkout, rel);
+    if (text.includes("\u0000")) throw new Error(`${rel} is not text`);
+    return [rel, text];
+  });
+  const files = [[request.relPath, request.text], ...sources];
+  const digest = contentDigest(JSON.stringify([request.repo.toLowerCase(), request.checkout, base, files]));
+  return { digest, sources, files };
+}
+
+// A carried planning file may override the queued base, but must not revert a newer integrated version.
+export async function checkBaseFiles(input, baseFiles, readFile) {
+  for (const [path, text] of input.files) {
+    const current = contentDigest(await readFile(path));
+    if (current !== baseFiles[path] && current !== contentDigest(text)) {
+      throw Object.assign(new Error(`${path} changed on the base after this chain was approved; refusing to overwrite merged work. Reconcile the local input, then retry with --resnapshot.`), { code: "CHAIN_INPUT_CHANGED" });
+    }
+  }
+}