create-agdf 0.4.9 → 0.6.0

package/lib/control-state/run-state-writer.js

@@ -0,0 +1,96 @@
+import { randomUUID } from "node:crypto";
+import {
+  closeSync,
+  fsyncSync,
+  existsSync,
+  lstatSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname } from "node:path";
+
+import { parseRunState } from "./run-state-parser.js";
+
+function fsyncDirectory(path) {
+  const descriptor = openSync(path, "r");
+  try {
+    fsyncSync(descriptor);
+  } finally {
+    closeSync(descriptor);
+  }
+}
+
+export function atomicWrite(path, content) {
+  if (existsSync(path)) {
+    const destination = lstatSync(path);
+    if (destination.isSymbolicLink() || !destination.isFile()) {
+      throw new Error("AGDF_RUN_PATH_INVALID");
+    }
+  }
+
+  const parent = lstatSync(dirname(path));
+  if (parent.isSymbolicLink() || !parent.isDirectory()) {
+    throw new Error("AGDF_RUN_PATH_INVALID");
+  }
+
+  const temp = `${path}.tmp-${process.pid}-${randomUUID()}`;
+  let descriptor;
+
+  try {
+    descriptor = openSync(temp, "wx");
+    writeFileSync(descriptor, content, "utf8");
+    fsyncSync(descriptor);
+    closeSync(descriptor);
+    descriptor = undefined;
+
+    renameSync(temp, path);
+    fsyncDirectory(dirname(path));
+  } catch (error) {
+    if (descriptor !== undefined) closeSync(descriptor);
+    try {
+      unlinkSync(temp);
+    } catch (cleanupError) {
+      if (cleanupError.code !== "ENOENT") throw cleanupError;
+    }
+    throw error;
+  }
+}
+
+export function writeRun(path, content, expectedRevisionId) {
+  const lockPath = `${path}.lock`;
+  let lockDescriptor;
+  try {
+    lockDescriptor = openSync(lockPath, "wx");
+  } catch (error) {
+    if (error.code === "EEXIST") throw new Error("AGDF_RUN_WRITE_LOCKED");
+    throw error;
+  }
+
+  try {
+    const current = parseRunState(readFileSync(path, "utf8"));
+    if (!current.valid) throw new Error("AGDF_RUN_STATE_INVALID");
+    if (current.meta.revision_id !== expectedRevisionId) {
+      throw new Error("AGDF_STALE_RUN_REVISION");
+    }
+
+    const next = content
+      .replace(
+        /^- revision:\s*.*$/m,
+        `- revision: ${Number(current.meta.revision) + 1}`,
+      )
+      .replace(/^- revision_id:\s*.*$/m, `- revision_id: ${randomUUID()}`);
+    const candidate = parseRunState(next);
+    if (!candidate.valid || candidate.meta.run_id !== current.meta.run_id) {
+      throw new Error("AGDF_RUN_STATE_INVALID");
+    }
+
+    atomicWrite(path, next);
+    return candidate;
+  } finally {
+    closeSync(lockDescriptor);
+    unlinkSync(lockPath);
+  }
+}

package/lib/delivery-path-search/candidate-policy.js

@@ -1,12 +1,37 @@
 import { validateCandidate } from "./contracts.js";
 
 function normalized(value) {
-  return String(value).toLowerCase().replace(/[`*_]/g, "").replace(/\s+/g, " ").trim();
+  return String(value).normalize("NFKC").toLowerCase().replace(/[`*_]/g, "").replace(/[^\p{L}\p{N}\s-]/gu, " ").replace(/\s+/g, " ").trim();
+}
+
+const STOP_WORDS = new Set(["a", "an", "and", "der", "die", "das", "ein", "eine", "the", "to", "und", "zu"]);
+
+function tokens(value) {
+  return new Set(normalized(value).split(/\s+/).filter((item) => item && !STOP_WORDS.has(item)));
+}
+
+function jaccard(left, right) {
+  const union = new Set([...left, ...right]);
+  if (!union.size) return 1;
+  let intersection = 0;
+  for (const item of left) if (right.has(item)) intersection += 1;
+  return intersection / union.size;
+}
+
+function signature(candidate) {
+  return JSON.stringify({
+    gate_action: normalized(candidate.gate_action ?? candidate.action),
+    affected_boundaries: [...(candidate.affected_boundaries ?? [])].map(normalized).sort(),
+    evidence: [...(candidate.expected_evidence ?? [])].map(normalized).sort(),
+    tests: [...(candidate.tests ?? [])].map(normalized).sort(),
+    risk_strategy: normalized(candidate.risk_strategy ?? ""),
+    reversibility: normalized(candidate.reversibility ?? ""),
+  });
 }
 
 export function candidateLegality(candidateValue, input) {
   const candidate = validateCandidate(candidateValue);
-  const action = normalized(candidate.action);
+  const action = normalized(candidate.gate_action ?? candidate.action);
   const forbiddenMatch = input.forbidden_actions.find((item) => {
     const forbidden = normalized(item);
     return forbidden && action === forbidden;
@@ -32,3 +57,43 @@ export function candidatesFromInput(input) {
     parent_id: null,
   }));
 }
+
+export function generatedCandidatesFromResponse(response, input, existingCandidates = []) {
+  const accepted = [];
+  const rejected = [];
+  for (const proposal of response.proposals) {
+    const candidate = {
+      id: `generated-${proposal.proposal_id}`,
+      action: proposal.intent,
+      source: "generated",
+      gate_action: proposal.gate_action,
+      intent: proposal.intent,
+      expected_evidence: proposal.expected_evidence,
+      tests: proposal.tests,
+      assumptions: proposal.assumptions,
+      affected_boundaries: proposal.affected_boundaries,
+      risk_strategy: proposal.risk_strategy,
+      reversibility: proposal.reversibility,
+      generator_proposal_id: proposal.proposal_id,
+      depth: 0,
+      parent_id: null,
+    };
+    const legality = candidateLegality(candidate, input);
+    if (!legality.legal) {
+      rejected.push({ proposal_id: proposal.proposal_id, reason: legality.reason });
+      continue;
+    }
+    const peers = [...existingCandidates, ...accepted].filter((item) => normalized(item.gate_action ?? item.action) === normalized(candidate.gate_action));
+    const duplicate = peers.find((item) => {
+      const same = normalized(item.intent ?? item.action) === normalized(candidate.intent);
+      const sameDecision = signature(item) === signature(candidate);
+      return same || sameDecision || jaccard(tokens(item.intent ?? item.action), tokens(candidate.intent)) >= 0.8;
+    });
+    if (duplicate) {
+      rejected.push({ proposal_id: proposal.proposal_id, reason: "cosmetic_or_material_duplicate" });
+      continue;
+    }
+    accepted.push(candidate);
+  }
+  return { accepted, rejected };
+}

package/lib/delivery-path-search/contracts.js

@@ -1,4 +1,5 @@
 export const CONTRACT_VERSION = "1";
+export const GENERATOR_CONTRACT_VERSION = "1";
 export const SCORING_POLICY_VERSION = "1";
 export const SCORE_DIMENSIONS = [
   "scope_fit",
@@ -25,6 +26,39 @@ function stringArray(value, label) {
   return value.map((item) => item.trim()).filter(Boolean);
 }
 
+function optionalBoundedString(value, label, maxLength = 1000) {
+  if (value === undefined) return undefined;
+  const result = requireString(value, label);
+  if (result.length > maxLength) throw new Error(`${label} must be at most ${maxLength} characters`);
+  return result;
+}
+
+function rejectUnknownKeys(value, allowed, label) {
+  const unknown = Object.keys(value).filter((key) => !allowed.includes(key));
+  if (unknown.length) throw new Error(`${label} contains unknown fields: ${unknown.join(", ")}`);
+}
+
+function generationConfig(value, wholeRunBudgets) {
+  if (value === undefined) return undefined;
+  const generation = requireObject(value, "generation");
+  if (typeof generation.enabled !== "boolean") throw new Error("generation.enabled must be a boolean");
+  const limits = {
+    max_calls: 1,
+    max_proposals: 5,
+    max_duration_ms: 30000,
+    max_cost_units: 5,
+  };
+  for (const [key, maximum] of Object.entries(limits)) {
+    if (!Number.isInteger(generation[key]) || generation[key] < 1 || generation[key] > maximum) {
+      throw new Error(`generation.${key} must be an integer from 1 to ${maximum}`);
+    }
+  }
+  if (generation.max_calls !== 1) throw new Error("generation.max_calls must equal 1 in this contract version");
+  if (generation.max_duration_ms > wholeRunBudgets.max_duration_ms) throw new Error("generation.max_duration_ms cannot exceed budgets.max_duration_ms");
+  if (generation.max_cost_units > wholeRunBudgets.max_cost_units) throw new Error("generation.max_cost_units cannot exceed budgets.max_cost_units");
+  return structuredClone(generation);
+}
+
 export function validateSearchInput(value) {
   const input = requireObject(value, "search input");
   if (input.contract_version !== CONTRACT_VERSION) throw new Error(`unsupported search input contract_version: ${input.contract_version}`);
@@ -43,6 +77,7 @@ export function validateSearchInput(value) {
   for (const key of ["max_candidates", "max_depth", "max_evaluations", "max_duration_ms", "max_cost_units", "stability_window"]) {
     if (!Number.isInteger(budgets[key]) || budgets[key] < 1) throw new Error(`budgets.${key} must be a positive integer`);
   }
+  generationConfig(input.generation, budgets);
   return structuredClone(input);
 }
 
@@ -53,9 +88,101 @@ export function validateCandidate(value) {
   stringArray(candidate.expected_evidence ?? [], "candidate.expected_evidence");
   stringArray(candidate.tests ?? [], "candidate.tests");
   stringArray(candidate.assumptions ?? [], "candidate.assumptions");
+  if (candidate.source !== undefined && !["deterministic", "generated", "expanded"].includes(candidate.source)) {
+    throw new Error("candidate.source must be deterministic, generated or expanded");
+  }
+  optionalBoundedString(candidate.gate_action, "candidate.gate_action");
+  optionalBoundedString(candidate.intent, "candidate.intent");
+  stringArray(candidate.affected_boundaries ?? [], "candidate.affected_boundaries");
+  optionalBoundedString(candidate.risk_strategy, "candidate.risk_strategy");
+  optionalBoundedString(candidate.reversibility, "candidate.reversibility");
+  optionalBoundedString(candidate.generator_proposal_id, "candidate.generator_proposal_id", 200);
   return structuredClone(candidate);
 }
 
+export function validateGeneratorRequest(value) {
+  const request = requireObject(value, "generator request");
+  rejectUnknownKeys(request, ["contract_version", "scope_key", "objective", "scope_summary", "current_gate", "allowed_actions", "forbidden_actions", "artefact_refs", "evidence", "missing_evidence", "risks", "constraints", "enforcement", "budgets"], "generator request");
+  if (request.contract_version !== GENERATOR_CONTRACT_VERSION) throw new Error(`unsupported generator contract_version: ${request.contract_version}`);
+  requireString(request.scope_key, "generator scope_key");
+  optionalBoundedString(request.objective, "generator objective", 2000);
+  optionalBoundedString(request.scope_summary, "generator scope_summary", 2000);
+  requireString(request.current_gate, "generator current_gate");
+  for (const key of ["allowed_actions", "forbidden_actions", "artefact_refs", "evidence", "missing_evidence", "risks", "constraints"]) {
+    const items = stringArray(request[key] ?? [], `generator ${key}`);
+    if (items.length > 20 || items.some((item) => item.length > 500)) throw new Error(`generator ${key} exceeds context bounds`);
+  }
+  validateEnforcement(request.enforcement);
+  const budgets = requireObject(request.budgets, "generator budgets");
+  generationConfig({ enabled: true, ...budgets }, { max_duration_ms: 120000, max_cost_units: 20 });
+  const serialized = JSON.stringify(request);
+  if (/(secret|credential|environment|raw_prompt|hidden_reasoning|source_snapshot)/i.test(serialized)) {
+    throw new Error("generator request contains disallowed context");
+  }
+  return structuredClone(request);
+}
+
+export function validateGeneratorResponse(value) {
+  const response = requireObject(value, "generator response");
+  rejectUnknownKeys(response, ["contract_version", "proposals", "cost_units", "metadata"], "generator response");
+  if (response.contract_version !== GENERATOR_CONTRACT_VERSION) throw new Error(`unsupported generator contract_version: ${response.contract_version}`);
+  if (!Array.isArray(response.proposals) || response.proposals.length > 5) throw new Error("generator proposals must be an array with at most 5 items");
+  if (!Number.isInteger(response.cost_units) || response.cost_units < 0 || response.cost_units > 5) throw new Error("generator cost_units must be an integer from 0 to 5");
+  if (response.metadata !== undefined) {
+    const metadata = requireObject(response.metadata, "generator metadata");
+    rejectUnknownKeys(metadata, ["name", "runtime", "model"], "generator metadata");
+    for (const [key, item] of Object.entries(metadata)) optionalBoundedString(item, `generator metadata.${key}`, 500);
+  }
+  const proposals = response.proposals.map((proposal, index) => {
+    const item = requireObject(proposal, `proposal ${index}`);
+    rejectUnknownKeys(item, ["proposal_id", "gate_action", "intent", "expected_evidence", "tests", "assumptions", "affected_boundaries", "risk_strategy", "reversibility"], `proposal ${index}`);
+    const normalized = {
+      proposal_id: requireString(item.proposal_id, `proposal ${index}.proposal_id`),
+      gate_action: requireString(item.gate_action, `proposal ${index}.gate_action`),
+      intent: requireString(item.intent, `proposal ${index}.intent`),
+      expected_evidence: stringArray(item.expected_evidence ?? [], `proposal ${index}.expected_evidence`),
+      tests: stringArray(item.tests ?? [], `proposal ${index}.tests`),
+      assumptions: stringArray(item.assumptions ?? [], `proposal ${index}.assumptions`),
+      affected_boundaries: stringArray(item.affected_boundaries ?? [], `proposal ${index}.affected_boundaries`),
+      risk_strategy: requireString(item.risk_strategy, `proposal ${index}.risk_strategy`),
+      reversibility: requireString(item.reversibility, `proposal ${index}.reversibility`),
+    };
+    if (JSON.stringify(normalized).length > 5000) throw new Error(`proposal ${index} exceeds size limit`);
+    if (/(^|\s)(rm|sudo|curl|wget|bash|sh|exec)\s/i.test(normalized.intent)) throw new Error(`proposal ${index} contains executable instructions`);
+    return normalized;
+  });
+  return {
+    contract_version: response.contract_version,
+    proposals,
+    cost_units: response.cost_units,
+    metadata: response.metadata ? structuredClone(response.metadata) : {},
+  };
+}
+
+export function generatorOutputSchema() {
+  return {
+    type: "object",
+    additionalProperties: false,
+    required: ["contract_version", "proposals", "cost_units"],
+    properties: {
+      contract_version: { type: "string", const: GENERATOR_CONTRACT_VERSION },
+      cost_units: { type: "integer", minimum: 0, maximum: 5 },
+      proposals: {
+        type: "array", maxItems: 5, items: {
+          type: "object", additionalProperties: false,
+          required: ["proposal_id", "gate_action", "intent", "expected_evidence", "tests", "assumptions", "affected_boundaries", "risk_strategy", "reversibility"],
+          properties: {
+            proposal_id: { type: "string", minLength: 1 }, gate_action: { type: "string", minLength: 1 }, intent: { type: "string", minLength: 1 },
+            expected_evidence: { type: "array", items: { type: "string" } }, tests: { type: "array", items: { type: "string" } },
+            assumptions: { type: "array", items: { type: "string" } }, affected_boundaries: { type: "array", items: { type: "string" } },
+            risk_strategy: { type: "string", minLength: 1 }, reversibility: { type: "string", minLength: 1 },
+          },
+        },
+      },
+    },
+  };
+}
+
 export function validateEvaluation(value, candidateId) {
   const evaluation = requireObject(value, "evaluation");
   if (evaluation.contract_version !== CONTRACT_VERSION) throw new Error(`unsupported evaluator contract_version: ${evaluation.contract_version}`);

package/lib/delivery-path-search/evaluators/claude.js

@@ -1,5 +1,6 @@
 import { execFileSync } from "node:child_process";
 import { evaluatorOutputSchema, validateEvaluation } from "../contracts.js";
+import { guardedExecFileSync } from "../transports/read-only-guard.js";
 
 export function claudeEvaluator(options = {}) {
   const claudeBin = options.claudeBin ?? "claude";
@@ -8,18 +9,6 @@ export function claudeEvaluator(options = {}) {
     runtime = execFileSync(claudeBin, ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
   } catch {}
 
-  function gitState() {
-    try {
-      return execFileSync("git", ["status", "--porcelain=v1", "-z"], {
-        cwd: options.cwd,
-        encoding: "utf8",
-        stdio: ["ignore", "pipe", "ignore"],
-      });
-    } catch {
-      return null;
-    }
-  }
-
   return {
     name: "claude",
     metadata: { name: "claude", runtime, model: options.model ?? "configured-default" },
@@ -41,15 +30,12 @@ export function claudeEvaluator(options = {}) {
       ];
       if (options.model) args.push("--model", options.model);
       args.push(prompt);
-      const before = gitState();
-      const raw = execFileSync(claudeBin, args, {
+      const raw = guardedExecFileSync(claudeBin, args, {
         cwd: options.cwd,
         encoding: "utf8",
         stdio: ["ignore", "pipe", "pipe"],
         timeout: options.timeoutMs ?? 120000,
       });
-      const after = gitState();
-      if (before !== null && after !== before) throw new Error("repository mutation detected during read-only evaluator run");
       const response = JSON.parse(raw);
       if (response.is_error) throw new Error(`claude evaluator returned an error: ${response.result ?? "unknown error"}`);
       return validateEvaluation(JSON.parse(response.result), candidate.id);

package/lib/delivery-path-search/evaluators/codex.js

@@ -3,6 +3,7 @@ import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { evaluatorOutputSchema, validateEvaluation } from "../contracts.js";
+import { guardedExecFileSync } from "../transports/read-only-guard.js";
 
 export function codexEvaluator(options = {}) {
   const codexBin = options.codexBin ?? "codex";
@@ -11,18 +12,6 @@ export function codexEvaluator(options = {}) {
     runtime = execFileSync(codexBin, ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
   } catch {}
 
-  function gitState() {
-    try {
-      return execFileSync("git", ["status", "--porcelain=v1", "-z"], {
-        cwd: options.cwd,
-        encoding: "utf8",
-        stdio: ["ignore", "pipe", "ignore"],
-      });
-    } catch {
-      return null;
-    }
-  }
-
   return {
     name: "codex",
     metadata: { name: "codex", runtime, model: options.model ?? "configured-default" },
@@ -49,15 +38,12 @@ export function codexEvaluator(options = {}) {
         ];
         if (options.model) args.push("--model", options.model);
         args.push(prompt);
-        const before = gitState();
-        execFileSync(codexBin, args, {
+        guardedExecFileSync(codexBin, args, {
           cwd: options.cwd,
           encoding: "utf8",
           stdio: ["ignore", "pipe", "pipe"],
           timeout: options.timeoutMs ?? 120000,
         });
-        const after = gitState();
-        if (before !== null && after !== before) throw new Error("repository mutation detected during read-only evaluator run");
         return validateEvaluation(JSON.parse(readFileSync(outputPath, "utf8")), candidate.id);
       } finally {
         rmSync(temp, { recursive: true, force: true });

package/lib/delivery-path-search/generators/claude.js

@@ -0,0 +1,40 @@
+import { execFileSync } from "node:child_process";
+import { generatorOutputSchema, validateGeneratorRequest, validateGeneratorResponse } from "../contracts.js";
+import { guardedExecFileSync } from "../transports/read-only-guard.js";
+
+export function claudeGenerator(options = {}) {
+  const claudeBin = options.claudeBin ?? "claude";
+  const execute = options.execute ?? guardedExecFileSync;
+  let runtime = options.runtime ?? "claude version unavailable";
+  if (!options.runtime) try { runtime = execFileSync(claudeBin, ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim(); } catch {}
+  return {
+    name: "claude",
+    metadata: { name: "claude", runtime, model: options.model ?? "configured-default" },
+    async generate(requestValue) {
+      const request = validateGeneratorRequest(requestValue);
+      const prompt = [
+        "Generate bounded advisory delivery-path proposals. Do not use tools, execute commands, or modify files.",
+        "Return only JSON matching the supplied schema. Do not include hidden reasoning.",
+        `Normalized request: ${JSON.stringify(request)}`,
+      ].join("\n");
+      const args = ["-p", "--disallowedTools", "Edit,Write,Bash", "--output-format", "json", "--json-schema", JSON.stringify(generatorOutputSchema())];
+      if (options.model) args.push("--model", options.model);
+      args.push(prompt);
+      let raw;
+      try {
+        raw = execute(claudeBin, args, { cwd: options.cwd, timeout: options.timeoutMs ?? request.budgets.max_duration_ms });
+      } catch (error) {
+        const providerOutput = String(error?.stdout ?? "");
+        if (/not logged in|unauthorized|authentication/i.test(providerOutput)) {
+          const authentication = new Error("claude generator authentication failed");
+          authentication.code = "GENERATOR_AUTHENTICATION_FAILED";
+          throw authentication;
+        }
+        throw error;
+      }
+      const response = JSON.parse(raw);
+      if (response.is_error) throw new Error(`claude generator returned an error: ${response.result ?? "unknown error"}`);
+      return validateGeneratorResponse(JSON.parse(response.result));
+    },
+  };
+}

package/lib/delivery-path-search/generators/codex.js

@@ -0,0 +1,38 @@
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { generatorOutputSchema, validateGeneratorRequest, validateGeneratorResponse } from "../contracts.js";
+import { guardedExecFileSync } from "../transports/read-only-guard.js";
+
+export function codexGenerator(options = {}) {
+  const codexBin = options.codexBin ?? "codex";
+  const execute = options.execute ?? guardedExecFileSync;
+  let runtime = options.runtime ?? "codex version unavailable";
+  if (!options.runtime) try { runtime = execFileSync(codexBin, ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim(); } catch {}
+  return {
+    name: "codex",
+    metadata: { name: "codex", runtime, model: options.model ?? "configured-default" },
+    async generate(requestValue) {
+      const request = validateGeneratorRequest(requestValue);
+      const temp = mkdtempSync(join(tmpdir(), "agdf-dps-generator-"));
+      const schemaPath = join(temp, "schema.json");
+      const outputPath = join(temp, "output.json");
+      try {
+        writeFileSync(schemaPath, `${JSON.stringify(generatorOutputSchema(), null, 2)}\n`, "utf8");
+        const prompt = [
+          "Generate bounded advisory delivery-path proposals. Do not use tools, execute commands, or modify files.",
+          "Return only JSON matching the supplied schema. Do not include hidden reasoning.",
+          `Normalized request: ${JSON.stringify(request)}`,
+        ].join("\n");
+        const args = ["exec", "--sandbox", "read-only", "--ephemeral", "--ignore-user-config", "--output-schema", schemaPath, "--output-last-message", outputPath, "--color", "never"];
+        if (options.model) args.push("--model", options.model);
+        args.push(prompt);
+        execute(codexBin, args, { cwd: options.cwd, timeout: options.timeoutMs ?? request.budgets.max_duration_ms });
+        return validateGeneratorResponse(JSON.parse(readFileSync(outputPath, "utf8")));
+      } finally {
+        rmSync(temp, { recursive: true, force: true });
+      }
+    },
+  };
+}

package/lib/delivery-path-search/generators/protocol.js

@@ -0,0 +1,12 @@
+import { validateGeneratorRequest, validateGeneratorResponse } from "../contracts.js";
+
+export function fixtureGenerator(response, metadata = { name: "fixture-generator" }) {
+  return {
+    name: metadata.name,
+    metadata,
+    async generate(request) {
+      validateGeneratorRequest(request);
+      return validateGeneratorResponse(response);
+    },
+  };
+}

package/lib/delivery-path-search/persistence.js

@@ -25,6 +25,11 @@ export function persistSearchResult(targetDir, result) {
     `- recommendation: ${recommendation}`,
     `- stopping_reason: ${safe.stopping_reason}`,
     `- evaluations: ${safe.budgets.evaluations}`,
+    `- generation_status: ${safe.generation?.status ?? "legacy_deterministic"}`,
+    `- generated_candidates: ${safe.generation ? `${safe.generation.accepted}/${safe.generation.returned}` : "0/0"}`,
+    `- generation_cost_units: ${safe.generation?.cost_units ?? 0}`,
+    `- generation_duration_ms: ${safe.generation?.duration_ms ?? 0}`,
+    ...(safe.generation?.failure_code ? [`- generation_failure: ${safe.generation.failure_code}`] : []),
     `- next_gate_action: ${safe.next_gate_action}`,
     "",
     "This summary contains model judgements, not measured facts. Canonical AGDF gate-check remains authoritative.",

package/lib/delivery-path-search/search-engine.js

@@ -1,11 +1,24 @@
 import { CONTRACT_VERSION, SCORING_POLICY_VERSION, validateEvaluation, validateSearchInput } from "./contracts.js";
-import { candidateLegality, candidatesFromInput } from "./candidate-policy.js";
+import { candidateLegality, candidatesFromInput, generatedCandidatesFromResponse } from "./candidate-policy.js";
 import { scoreEvaluation } from "./scoring.js";
+import { generatorRequestFromInput } from "./state-adapter.js";
+
+function generatorFailureCode(error) {
+  if (error?.code === "GENERATOR_MUTATION_DETECTED") return "generator_mutation_detected";
+  if (error?.code === "GENERATOR_TIMEOUT") return "generator_timeout";
+  if (error?.code === "GENERATOR_AUTHENTICATION_FAILED") return "generator_authentication_failed";
+  if (error?.code === "ENOENT") return "generator_unavailable";
+  if (/auth/i.test(error?.message ?? "")) return "generator_authentication_failed";
+  if (/context|disallowed/i.test(error?.message ?? "")) return "generator_context_rejected";
+  if (/budget/i.test(error?.message ?? "")) return "generator_budget_exceeded";
+  return "generator_schema_invalid";
+}
 
 export async function runDeliveryPathSearch(inputValue, evaluator, options = {}) {
   const input = validateSearchInput(inputValue);
   const startedAt = Date.now();
-  const queue = [...(options.candidates ?? candidatesFromInput(input))];
+  const baseline = [...(options.candidates ?? candidatesFromInput(input))];
+  const queue = [...baseline];
   const rejected = [];
   const evaluated = [];
   let evaluations = 0;
@@ -13,6 +26,53 @@ export async function runDeliveryPathSearch(inputValue, evaluator, options = {})
   let lastLeaderId = null;
   let stableComparisons = 0;
   let stoppingReason = "candidate_queue_exhausted";
+  const generation = {
+    status: input.generation?.enabled ? "failed" : "disabled",
+    adapter: options.generator?.metadata ?? null,
+    budgets: input.generation ?? null,
+    returned: 0,
+    accepted: 0,
+    rejected: [],
+    cost_units: 0,
+    duration_ms: 0,
+    failure_code: null,
+  };
+
+  if (input.generation?.enabled) {
+    if (!options.generator) {
+      generation.failure_code = "generator_unavailable";
+    } else {
+      const generationStartedAt = Date.now();
+      try {
+        const response = await options.generator.generate(generatorRequestFromInput(input));
+        const elapsed = Date.now() - generationStartedAt;
+        generation.returned = response.proposals.length;
+        generation.cost_units = response.cost_units;
+        costUnits += response.cost_units;
+        if (elapsed > input.generation.max_duration_ms) {
+          const error = new Error("generator duration budget exceeded");
+          error.code = "GENERATOR_TIMEOUT";
+          throw error;
+        }
+        if (response.cost_units > input.generation.max_cost_units || response.proposals.length > input.generation.max_proposals) {
+          const error = new Error("generator response exceeds configured budget");
+          error.code = "GENERATOR_BUDGET_EXCEEDED";
+          throw error;
+        }
+        const filtered = generatedCandidatesFromResponse(response, input, baseline);
+        generation.accepted = filtered.accepted.length;
+        generation.rejected = filtered.rejected;
+        queue.push(...filtered.accepted.slice(0, input.generation.max_proposals));
+        generation.status = filtered.accepted.length === response.proposals.length ? "success" : "partial";
+        if (!filtered.accepted.length) generation.failure_code = "generator_no_diverse_proposals";
+      } catch (error) {
+        generation.failure_code = generatorFailureCode(error);
+        if (generation.failure_code === "generator_mutation_detected") throw error;
+      } finally {
+        generation.duration_ms = Date.now() - generationStartedAt;
+      }
+    }
+  }
 
   while (queue.length > 0) {
     if (evaluations >= input.budgets.max_evaluations) { stoppingReason = "evaluation_budget_exhausted"; break; }
@@ -46,6 +106,7 @@ export async function runDeliveryPathSearch(inputValue, evaluator, options = {})
             parent_id: candidate.id,
             depth: (candidate.depth ?? 0) + 1,
             action,
+            source: "expanded",
             expected_evidence: [],
             tests: [],
             assumptions: evaluation.assumptions,
@@ -85,6 +146,7 @@ export async function runDeliveryPathSearch(inputValue, evaluator, options = {})
     rejected,
     enforcement: input.enforcement,
     evaluator: evaluator.metadata ?? { name: evaluator.name ?? "unknown" },
+    generation,
     budgets: { configured: input.budgets, evaluations, cost_units: costUnits, stable_comparisons: stableComparisons, duration_ms: Date.now() - startedAt },
     stopping_reason: stoppingReason,
     next_gate_action: "Run canonical AGDF gate-check; search does not grant permission.",