faberun 0.30.0 → 0.31.0

package/src/plan/preflight.mjs

@@ -1,17 +1,93 @@
 /**
- * The ask `faberun plan` makes before its first stage.
+ * What `faberun plan` decides before it spends anything: the refusals it
+ * returns before the first stage is dispatched -- which runtimes a planning run
+ * will spend, and what counts as one of them not answering -- and the
+ * deterministic checks a plan passes before any semantic review grades it.
  *
- * It lives beside the pipeline rather than inside it because asking is its own
- * concern -- which runtimes a planning run will spend, and what counts as one
- * of them not answering -- and because `pipeline.mjs` sits 45 lines from this
- * tree's 800-line ceiling.
+ * Both halves live beside the pipeline rather than inside it because asking
+ * and checking are their own concerns, and because `pipeline.mjs` sits close
+ * to this tree's 800-line ceiling.
  */
+import { join } from "node:path";
 import { preflightRuntimes } from "../engine/live-preflight.mjs";
 import { liveSilenceCause } from "../engine/live-silence.mjs";
 import { harnessCapabilities } from "../harnesses/index.mjs";
+import { validateContract } from "../contract/index.mjs";
 import { assertRuntimeExecutesCommands, validateRuntime } from "../contract/runtime.mjs";
 import { effectiveProvider } from "../contract/provider.mjs";
 import { SAME_VENDOR_REVIEW_MODE, sameVendorTierRefusal } from "../contract/judge-independence.mjs";
+import { assertTimeoutsCoverMeasured, raiseTimeoutsToMeasured } from "./freeze.mjs";
+import { assertFilteredProofsNameTheirTest, declareDirectoryGuards } from "./proof-scope.mjs";
+import { checkPlanProofs } from "./proof-check.mjs";
+
+/** @typedef {import("./template.mjs").PlanOutput} PlanOutput */
+/** @typedef {import("./template.mjs").PlanFindingOutput} PlanFindingOutput */
+/** @typedef {import("../contract/index.mjs").JsonObject} JsonObject */
+/** @typedef {import("./pipeline.mjs").AssembledPlan} AssembledPlan */
+
+/**
+ * What the deterministic checks need: the measured repository facts the freeze
+ * rules read, the cwd and plansDir the contract is assembled against, and the
+ * two closures that render the plan the way `freezePlan` will. They are
+ * supplied rather than imported because they are the pipeline's own assembly
+ * (`pipeline.mjs` imports this module), and taking them as data is what lets
+ * `rounds.mjs` — and a test — run the checks with fakes.
+ *
+ * @typedef {{repoFacts: import("./repo-facts.mjs").RepoFacts, cwd: string, plansDir: string, assembleFrozenNodes: (plan: PlanOutput) => AssembledPlan, frozenContractRaw: (assembly: AssembledPlan) => JsonObject}} PlanCheckContext
+ */
+
+/**
+ * The two mechanically repairable freeze rules, applied, then the freeze
+ * contract itself validated the way `freeze.mjs` and `proof-scope.mjs`
+ * validate it: the rules are imported, never restated, so this cannot drift
+ * from the freeze it stands in front of.
+ *
+ * It does not throw. A plan the checks refuse is a diagnostic for the repair
+ * loop, not a refusal: the refusal is the pre-dispatch half of this module,
+ * and a thrown plan check would spend a round's budget twice — once on the
+ * revise that answers a finding, and once on the error that killed it.
+ *
+ * The failure is returned beside the repaired plan rather than instead of it,
+ * so the caller can hand the plan on to a review (or to the freeze) while
+ * still recording what the freeze would have said.
+ *
+ * @param {PlanOutput} plan
+ * @param {PlanCheckContext} ctx
+ * @returns {{plan: PlanOutput, raised: string[], declared: string[], failure: unknown|null}}
+ */
+export function freezePreflight(plan, ctx) {
+  const timeouts = raiseTimeoutsToMeasured(plan, ctx.repoFacts);
+  const guards = declareDirectoryGuards(timeouts.plan, ctx.repoFacts, ctx.cwd);
+  const candidate = guards.plan;
+  const repaired = { plan: candidate, raised: timeouts.raised, declared: guards.declared };
+  try {
+    const contract = validateContract(ctx.frozenContractRaw(ctx.assembleFrozenNodes(candidate)), join(ctx.plansDir, "contract.json"));
+    assertFilteredProofsNameTheirTest(contract);
+    assertTimeoutsCoverMeasured(contract, ctx.repoFacts);
+    return { ...repaired, failure: null };
+  } catch (error) {
+    return { ...repaired, failure: error };
+  }
+}
+
+/**
+ * The complete deterministic check set a plan passes before any semantic
+ * review begins: `freezePreflight` plus the plan-wide proof scan, whose two
+ * shapes (a name filter that selects no test, a bare grep proving an absence)
+ * no reviewer decides better than a local read. The pipeline runs this once on
+ * the draft and forwards `findings` into the round loop's own repair budget —
+ * the rounds `--review-rounds` already pays for — while the loop runs
+ * `freezePreflight` on every candidate it grades, where the repair it drives
+ * is the answer to whatever the check refused.
+ *
+ * @param {PlanOutput} plan
+ * @param {PlanCheckContext} ctx
+ * @returns {{plan: PlanOutput, raised: string[], declared: string[], findings: PlanFindingOutput[], failure: unknown|null}}
+ */
+export function checkPlanBeforeReview(plan, ctx) {
+  const checks = freezePreflight(plan, ctx);
+  return { ...checks, findings: checkPlanProofs(checks.plan, ctx.repoFacts, ctx.cwd) };
+}
 
 /**
  * The runtimes a planning run will spend, asked once before its first stage.

package/src/plan/progress.mjs

@@ -19,12 +19,24 @@
  * also why `plan --resolve` writes none: it is never detached, so a death
  * there is visible where it happens and a record would only add a second
  * account of something the operator already watched.
+ *
+ * The module also holds the record of what a dead attempt finished:
+ * `writePlanDraftRecord` persists the validated draft plan beside the phase's
+ * plan artifacts, and `resumablePlanDraft` reads it back for a resumed
+ * attempt, because the liveness record says that the attempt died but not
+ * what its death had already paid for. `startDraftPlan` decides, for one
+ * attempt, between adopting that draft and dispatching the draft stage —
+ * dispatching stays the pipeline's verb (it is passed in), but whether to
+ * dispatch at all is this module's question. Same boundary, same reader —
+ * all of it answers a later launch's one question, what did the last attempt
+ * leave behind.
  */
-import { rmSync } from "node:fs";
+import { existsSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { pidAlive, processStartToken, sameProcessStartToken } from "../run/lock.mjs";
 import { campaignTree } from "../run/paths.mjs";
 import { readJson, writeJsonAtomic } from "../run/store.mjs";
+import { validatePlanOutput } from "./template.mjs";
 
 /** @typedef {{pid?: number, processStartToken?: string|null, at?: string, stage?: string, [key: string]: unknown}} PlanProgressRecord */
 
@@ -99,3 +111,91 @@ export function abandonedPlanProgress(cwd, campaignId, phase) {
 export function clearPlanProgress(cwd, campaignId, phase) {
   rmSync(planProgressPath(cwd, campaignId, phase), { force: true });
 }
+
+/** The file beside a phase's plan artifacts holding the draft a resumed attempt can adopt. */
+const PLAN_DRAFT_FILE = "draft.json";
+
+/**
+ * The validated draft a later attempt can adopt without paying for it again.
+ *
+ * @typedef {{runId: string, at: string, specDigest: string, plan: import("./template.mjs").PlanOutput}} PlanDraftRecord
+ */
+
+/**
+ * Persist the validated draft plan where a later launch of the same phase
+ * finds it: beside the phase's durable plan artifacts, never in the disposable
+ * scratch tree, for the same reason the progress record is there — a record a
+ * later launch has to find cannot live where the next `plan` may wipe. The
+ * record is written once, when the draft validates, and never removed: a
+ * frozen or contested phase writes `plan.json` beside it, and the presence of
+ * that file is what stops a later attempt from adopting anything.
+ *
+ * @param {string} plansDir
+ * @param {PlanDraftRecord} record
+ * @returns {void}
+ */
+export function writePlanDraftRecord(plansDir, record) {
+  writeJsonAtomic(join(plansDir, PLAN_DRAFT_FILE), record);
+}
+
+/**
+ * The dead attempt's draft, when adopting it costs no paid call, or null when
+ * there is nothing to adopt. Two records must agree before anything is
+ * adopted: `abandoned` — the progress record above, sampled by the caller
+ * before its own first liveness write, which would otherwise overwrite the
+ * evidence of the death it is about to resume from — and the draft record
+ * `writePlanDraftRecord` wrote when the dead attempt validated its draft. The
+ * plan in it is exactly the paid work a resumed attempt would otherwise
+ * duplicate. A phase that ever finished, frozen or contested, has a
+ * `plan.json` beside the record: that file, not the record's absence, is
+ * what makes a later deliberate re-plan draft fresh. A record from a
+ * different spec (the operator edited the spec between attempts) or one
+ * whose plan no longer validates is refused the same way.
+ *
+ * @param {{abandoned: PlanProgressRecord|null, plansDir: string, specDigest: string}} options
+ * @returns {{runId: string, plan: import("./template.mjs").PlanOutput}|null}
+ */
+export function resumablePlanDraft({ abandoned, plansDir, specDigest }) {
+  if (abandoned === null) return null;
+  if (existsSync(join(plansDir, "plan.json"))) return null;
+  let record;
+  try {
+    record = /** @type {PlanDraftRecord|unknown} */ (readJson(join(plansDir, PLAN_DRAFT_FILE)));
+  } catch {
+    // An absent record is the ordinary case: a draft still running, or a
+    // death before the draft validated, leaves nothing to adopt.
+    return null;
+  }
+  if (!record || typeof record !== "object" || Array.isArray(record)) return null;
+  const draft = /** @type {PlanDraftRecord} */ (record);
+  if (draft.specDigest !== specDigest || typeof draft.runId !== "string") return null;
+  try {
+    return { runId: draft.runId, plan: validatePlanOutput(draft.plan) };
+  } catch {
+    // The record's plan no longer validates: adopting it would spend the
+    // round budget repairing an unknown shape, so the caller drafts fresh.
+    return null;
+  }
+}
+
+/**
+ * The draft one attempt starts from: the dead attempt's validated plan when
+ * adopting it costs no paid call, or a fresh dispatch of the draft stage.
+ * The adoption is announced as its own stage line — a resumed attempt that
+ * dispatched nothing must still leave the same record a drafting one does.
+ *
+ * @param {{abandoned: PlanProgressRecord|null, plansDir: string, specDigest: string,
+ *   draftStageInput: Record<string, unknown>,
+ *   runStage: (kind: import("./template.mjs").PlanningKind, input: Record<string, unknown>) => Promise<{contract: {id: string}, output: Record<string, unknown>}>,
+ *   logStage: (stage: string, detail: Record<string, unknown>) => void}} options
+ * @returns {Promise<{runId: string, planOutput: unknown, resumed: boolean}>}
+ */
+export async function startDraftPlan({ abandoned, plansDir, specDigest, draftStageInput, runStage, logStage }) {
+  const resumed = resumablePlanDraft({ abandoned, plansDir, specDigest });
+  if (resumed !== null) {
+    logStage("draft-resumed", { runId: resumed.runId, nodeCount: resumed.plan.nodes.length });
+    return { runId: resumed.runId, planOutput: resumed.plan, resumed: true };
+  }
+  const stage = await runStage("draft", draftStageInput);
+  return { runId: stage.contract.id, planOutput: stage.output.plan, resumed: false };
+}