@deksden-com/dd-flow-cli 0.8.0 → 0.9.0-beta.0

package/dist/services/code-checks.js

@@ -3,242 +3,159 @@ import { spawn, spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { AppError } from "../shared/errors.js";
-/**
- * A local CODE gate must not share a mutable database with another checkout.
- * The project command consumes this opaque suffix only for its local/test
- * database target; preview and production-like targets remain unchanged.
- */
-export function codeExecutionEnvironment(workspaceRoot) {
-    const suffix = crypto.createHash("sha256").update(path.resolve(workspaceRoot)).digest("hex").slice(0, 12);
-    return { ...process.env, DD_FLOW_LOCAL_DATABASE_SUFFIX: suffix };
+const profileRelativePath = path.join(".memory-bank", "spec", "engineering", "code-check-profile.json");
+export function codeExecutionEnvironment(workspaceRoot) { const suffix = crypto.createHash("sha256").update(path.resolve(workspaceRoot)).digest("hex").slice(0, 12); return { ...process.env, DD_FLOW_LOCAL_DATABASE_SUFFIX: suffix }; }
+export function readCodeCheckProfile(workspaceRoot) {
+    const file = path.join(workspaceRoot, profileRelativePath);
+    if (!fs.existsSync(file))
+        return { profile: null, hash: null, file };
+    const bytes = fs.readFileSync(file);
+    const value = JSON.parse(bytes.toString("utf8"));
+    if (value.schema_id !== "dd-flow/code-check-profile@5")
+        throw new AppError("invalid_code_check_profile", "CODE check profile has an unsupported schema", 2, { file, schema_id: value.schema_id ?? null, required: "dd-flow/code-check-profile@5" });
+    if (!isStringRecord(value.aliases) || !isStringRecord(value.require_alias_for) || !isGateRecord(value.mandatory_by_gate))
+        throw new AppError("invalid_code_check_profile", "CODE check profile aliases, require_alias_for and mandatory_by_gate are invalid", 2, { file });
+    for (const [gate, aliases] of Object.entries(value.mandatory_by_gate))
+        for (const alias of aliases ?? [])
+            if (!value.aliases[alias])
+                throw new AppError("invalid_code_check_profile", "A mandatory gate references an unknown alias", 2, { file, gate, alias });
+    return { profile: value, hash: crypto.createHash("sha256").update(bytes).digest("hex"), file };
 }
 export function validateCodeCheckCommands(workspaceRoot, commands) {
-    const file = path.join(workspaceRoot, ".memory-bank", "spec", "engineering", "code-check-profile.json");
-    // Keep one resolved command for every declared check. Two declarations may
-    // deliberately share a command while carrying different acceptance roles.
-    if (!fs.existsSync(file))
+    const { profile, file } = readCodeCheckProfile(workspaceRoot);
+    if (!profile)
         return [...commands];
-    const profile = JSON.parse(fs.readFileSync(file, "utf8"));
-    if (profile.schema_id !== "dd-flow/code-check-profile@4")
-        throw new AppError("invalid_code_check_profile", "CODE check profile has an unsupported schema", 2, { file, schema_id: profile.schema_id ?? null });
-    const aliases = profile.aliases && typeof profile.aliases === "object" && !Array.isArray(profile.aliases)
-        ? profile.aliases
-        : {};
-    const required = profile.require_alias_for && typeof profile.require_alias_for === "object" && !Array.isArray(profile.require_alias_for)
-        ? profile.require_alias_for
-        : {};
-    return commands.map((command) => {
-        if (command.startsWith("@check/")) {
-            const template = aliases[command];
-            if (typeof template !== "string" || !template.trim())
-                throw new AppError("unknown_code_check_alias", "CODE check alias is not defined by the project profile", 2, { alias: command, file });
-            return command;
-        }
-        for (const [prefix, alias] of Object.entries(required)) {
-            if (command === prefix || command.startsWith(`${prefix} `)) {
-                throw new AppError("raw_code_check_forbidden", "CODE check must use the project alias instead of a raw guarded command", 2, { command, required_alias: String(alias), file });
-            }
-        }
+    return commands.map((command) => { if (command.startsWith("@check/")) {
+        if (!profile.aliases[command]?.trim())
+            throw new AppError("unknown_code_check_alias", "CODE check alias is not defined by the project profile", 2, { alias: command, file });
         return command;
-    });
-}
-export function resolveCodeCheckCommands(workspaceRoot, runId, commands) {
-    const validated = validateCodeCheckCommands(workspaceRoot, commands);
-    const file = path.join(workspaceRoot, ".memory-bank", "spec", "engineering", "code-check-profile.json");
-    if (!fs.existsSync(file))
-        return validated;
-    const profile = JSON.parse(fs.readFileSync(file, "utf8"));
-    const aliases = profile.aliases && typeof profile.aliases === "object" && !Array.isArray(profile.aliases)
-        ? profile.aliases
-        : {};
-    return validated.map((command) => command.startsWith("@check/")
-        ? String(aliases[command]).replaceAll("{run_id}", runId)
-        : command);
+    } for (const [prefix, alias] of Object.entries(profile.require_alias_for))
+        if (command === prefix || command.startsWith(`${prefix} `))
+            throw new AppError("raw_code_check_forbidden", "CODE check must use the project alias instead of a raw guarded command", 2, { command, required_alias: alias, file }); return command; });
+}
+export function resolveCodeCheckCommands(workspaceRoot, runId, commands) { const validated = validateCodeCheckCommands(workspaceRoot, commands); const { profile } = readCodeCheckProfile(workspaceRoot); return validated.map((command) => command.startsWith("@check/") ? profile.aliases[command].replaceAll("{run_id}", runId) : command); }
+export function projectPolicyCheckDeclarations(workspaceRoot, gate) {
+    const { profile } = readCodeCheckProfile(workspaceRoot);
+    return (profile?.mandatory_by_gate[gate] ?? []).map((alias) => { const ref = `POLICY/${gate}/${alias.slice(7).replace(/[^a-z0-9]+/gi, "-").replace(/^-|-$/g, "").toLowerCase()}`; return { id: ref, canonical_ref: ref, source: "project_policy", command: alias, purpose: `Mandatory project ${gate} gate.`, run_at: gate, availability: "available" }; });
+}
+export function effectiveCheckDeclarations(workspaceRoot, declared, gates) { return gates.flatMap((gate) => [...declared.filter((check) => check.run_at === gate), ...projectPolicyCheckDeclarations(workspaceRoot, gate)]); }
+export function aggregateCheckDeclarations(workspaceRoot) { return projectPolicyCheckDeclarations(workspaceRoot, "code"); }
+export function finalCodeCheckDeclarations(workspaceRoot, declared) { return effectiveCheckDeclarations(workspaceRoot, declared, ["code", "readiness"]); }
+export function checksForRunAt(checks, runAt) { return checks.filter((check) => check.run_at === runAt); }
+export function validateCheckPlacement(workspaceRoot, checks) { const { profile } = readCodeCheckProfile(workspaceRoot); const aggregateCommands = new Set(projectPolicyCheckDeclarations(workspaceRoot, "code").flatMap((check) => [check.command, profile?.aliases[check.command] ?? check.command])); for (const check of checks)
+    if (check.run_at === "work" && aggregateCommands.has(check.command))
+        throw new AppError("aggregate_check_requires_code_gate", "A project aggregate check must run at CODE or readiness, not inside one scoped Work", 2, { check_id: check.id, command: check.command, run_at: check.run_at }); }
+export function validateCheckDeclaration(workspaceRoot, check) {
+    if (check.run_at === "external")
+        return;
+    const { profile } = readCodeCheckProfile(workspaceRoot);
+    if (check.availability === "planned" && check.command.startsWith("@check/") && !profile?.aliases[check.command])
+        throw new AppError("planned_check_not_materialized", "A planned check alias was not materialized by its provider Work", 2, { check_id: check.id, command: check.command, provider: check.provided_by ?? null });
+    validateCodeCheckCommands(workspaceRoot, [check.command]);
+    if (check.command.startsWith("@check/") && check.definition && profile?.aliases[check.command] !== check.definition)
+        throw new AppError("check_definition_drift", "The accepted check alias definition differs from the current project profile", 2, { check_id: check.id, alias: check.command, expected: check.definition, actual: profile?.aliases[check.command] ?? null });
+    if (check.availability !== "planned")
+        return;
+    if (!check.command.startsWith("@check/"))
+        throw new AppError("planned_check_requires_alias", "A planned CODE check must declare a new @check/... alias", 2, { check_id: check.id, command: check.command });
+    if (!check.definition?.trim())
+        throw new AppError("planned_check_definition_missing", "A planned CODE check must declare its exact alias definition", 2, { check_id: check.id, command: check.command });
+    if (!profile?.aliases[check.command])
+        throw new AppError("planned_check_not_materialized", "A planned check alias was not materialized by its provider Work", 2, { check_id: check.id, command: check.command, provider: check.provided_by ?? null });
 }
 export async function runCodeChecks(context, input) {
-    const receipts = [];
     for (const check of input.checks)
         validateCheckDeclaration(input.workspaceRoot, check);
-    const commands = resolveCodeCheckCommands(input.workspaceRoot, input.runId, input.checks.map((check) => check.command));
-    for (let index = 0; index < commands.length; index += 1) {
-        const declaration = input.checks[index];
-        const command = commands[index];
+    const { hash: profileHash } = readCodeCheckProfile(input.workspaceRoot);
+    const resolved = resolveCodeCheckCommands(input.workspaceRoot, input.runId, input.checks.map((check) => check.command));
+    const groups = deduplicate(input.checks, resolved);
+    const receipts = [];
+    for (let index = 0; index < groups.length; index += 1) {
+        const group = groups[index];
         const ordinal = (context.db.get("SELECT COUNT(*) AS count FROM check_receipts WHERE work_id IS ? AND run_id = ?", [input.workId ?? null, input.runId])?.count ?? 0) + 1;
         const localId = `RCP-${String(ordinal).padStart(3, "0")}`;
         const id = `${input.workId ?? input.runId}/${localId}`;
         const directory = path.join(input.runHome, input.artifactDir ?? "05-code", "checks", localId);
-        fs.mkdirSync(directory, { recursive: true });
+        const evidenceDir = path.join(directory, "artifacts");
+        fs.mkdirSync(evidenceDir, { recursive: true });
         const stdoutPath = path.join(directory, "stdout.log");
         const stderrPath = path.join(directory, "stderr.log");
         const receiptPath = path.join(directory, "receipt.json");
-        const evidenceDir = path.join(directory, "artifacts");
-        fs.mkdirSync(evidenceDir, { recursive: true });
+        const before = workspaceState(input.workspaceRoot);
+        const inputHash = crypto.createHash("sha256").update(JSON.stringify({ gate: group.gate, command: group.command, environment: String(codeExecutionEnvironment(input.workspaceRoot).DD_FLOW_LOCAL_DATABASE_SUFFIX), required_artifacts: group.requiredArtifacts })).digest("hex");
+        const epoch = crypto.createHash("sha256").update(`${group.gate}\0${before.fingerprint}`).digest("hex");
         const startedAt = context.now();
-        input.progress?.(`check ${index + 1}/${commands.length} started: ${command}`);
+        input.progress?.(`check ${index + 1}/${groups.length} started: ${group.command}`);
         const stdout = fs.createWriteStream(stdoutPath);
         const stderr = fs.createWriteStream(stderrPath);
-        const result = await runCheck(command, input.workspaceRoot, { ...codeExecutionEnvironment(input.workspaceRoot), DD_FLOW_EVIDENCE_DIR: evidenceDir }, stdout, stderr, (elapsed) => {
-            input.progress?.(`check ${index + 1}/${commands.length} still running (${elapsed}s): ${command}`);
-        });
+        const result = await runCheck(group.command, input.workspaceRoot, { ...codeExecutionEnvironment(input.workspaceRoot), DD_FLOW_EVIDENCE_DIR: evidenceDir }, stdout, stderr, (elapsed) => input.progress?.(`check ${index + 1}/${groups.length} still running (${elapsed}s): ${group.command}`));
         await Promise.all([closeStream(stdout), closeStream(stderr)]);
-        const finishedAt = context.now();
-        const exitCode = result.exitCode;
-        const artifacts = collectRequiredArtifacts(evidenceDir, declaration.required_artifacts ?? []);
-        const status = exitCode === 0 && !result.error && artifacts.complete ? "passed" : "failed";
+        const after = workspaceState(input.workspaceRoot);
+        const mutationPaths = changedPaths(before.files, after.files);
+        const artifacts = collectRequiredArtifacts(evidenceDir, group.requiredArtifacts);
         if (!artifacts.complete)
             fs.appendFileSync(stderrPath, `\nmissing required evidence artifacts: ${artifacts.missing.join(", ")}\n`);
         if (result.error)
             fs.appendFileSync(stderrPath, `\n${result.error}\n`);
-        const receipt = {
-            id,
-            local_id: localId,
-            declaration_id: declaration.id,
-            scope: input.scope,
-            work_id: input.workId ?? null,
-            command,
-            status,
-            exit_code: exitCode,
-            stdout_path: stdoutPath,
-            stderr_path: stderrPath,
-            receipt_path: receiptPath,
-            workspace_fingerprint: workspaceFingerprint(input.workspaceRoot),
-            artifacts: artifacts.items,
-            started_at: startedAt,
-            finished_at: finishedAt
-        };
+        if (mutationPaths.length)
+            fs.appendFileSync(stderrPath, `\ncheck mutated project workspace: ${mutationPaths.join(", ")}\n`);
+        const status = result.aborted ? "aborted" : result.exitCode === 0 && !result.error && artifacts.complete && mutationPaths.length === 0 ? "passed" : "failed";
+        const receipt = { id, local_id: localId, declaration_id: group.declarations[0].id, check_refs: group.declarations.map(checkRef), gate: group.gate, scope: input.scope, work_id: input.workId ?? null, command: group.command, input_hash: inputHash, verification_epoch: epoch, status, exit_code: result.exitCode, stdout_path: stdoutPath, stderr_path: stderrPath, receipt_path: receiptPath, workspace_fingerprint: before.fingerprint, before_fingerprint: before.fingerprint, after_fingerprint: after.fingerprint, profile_hash: profileHash, mutation_paths: mutationPaths, artifacts: artifacts.items, started_at: startedAt, finished_at: context.now() };
         fs.writeFileSync(receiptPath, `${JSON.stringify(receipt, null, 2)}\n`);
-        context.db.run("INSERT INTO check_receipts (id, project_id, run_id, work_id, scope, declaration_id, command, status, exit_code, stdout_path, stderr_path, receipt_path, workspace_fingerprint, artifacts_json, started_at, finished_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)", [id, input.projectId, input.runId, input.workId ?? null, input.scope, declaration.id, command, status, exitCode, stdoutPath, stderrPath, receiptPath, receipt.workspace_fingerprint, JSON.stringify(receipt.artifacts), startedAt, finishedAt]);
+        context.db.run("INSERT INTO check_receipts (id, project_id, run_id, work_id, scope, declaration_id, check_refs_json, gate, command, input_hash, verification_epoch, status, exit_code, stdout_path, stderr_path, receipt_path, workspace_fingerprint, before_fingerprint, after_fingerprint, profile_hash, mutation_paths_json, artifacts_json, started_at, finished_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)", [id, input.projectId, input.runId, input.workId ?? null, input.scope, receipt.declaration_id, JSON.stringify(receipt.check_refs), receipt.gate, receipt.command, receipt.input_hash, receipt.verification_epoch, receipt.status, receipt.exit_code, stdoutPath, stderrPath, receiptPath, receipt.workspace_fingerprint, receipt.before_fingerprint, receipt.after_fingerprint, receipt.profile_hash, JSON.stringify(receipt.mutation_paths), JSON.stringify(receipt.artifacts), receipt.started_at, receipt.finished_at]);
         receipts.push(receipt);
-        input.progress?.(`check ${index + 1}/${commands.length} ${status}: ${command}`);
+        input.progress?.(`check ${index + 1}/${groups.length} ${status}: ${group.command}`);
     }
     return receipts;
 }
-export function aggregateCheckDeclarations(workspaceRoot) {
-    const file = path.join(workspaceRoot, ".memory-bank", "spec", "engineering", "code-check-profile.json");
-    if (!fs.existsSync(file))
-        return [];
-    const profile = JSON.parse(fs.readFileSync(file, "utf8"));
-    if (profile.schema_id !== "dd-flow/code-check-profile@4")
-        throw new AppError("invalid_code_check_profile", "CODE check profile has an unsupported schema", 2, { file, schema_id: profile.schema_id ?? null });
-    if (!Array.isArray(profile.aggregate_commands) || !profile.aggregate_commands.every((command) => typeof command === "string" && command.trim()))
-        throw new AppError("invalid_code_check_profile", "aggregate_commands must be an array of commands", 2, { file });
-    return profile.aggregate_commands.map((command, index) => ({ id: `CHK-POLICY-CODE-${String(index + 1).padStart(3, "0")}`, command, purpose: "Mandatory project-wide policy gate.", run_at: "code", availability: "available" }));
-}
-/**
- * A project-wide gate can observe files owned by more than one CODE Work.
- * Keep it at the CODE/readiness fan-in, where the engine can create a repair
- * Work with the failed receipt and the right project-local repair context.
- */
-export function validateCheckPlacement(workspaceRoot, checks) {
-    const aggregate = new Set(aggregateCheckDeclarations(workspaceRoot).map((check) => check.command));
-    for (const check of checks) {
-        if (check.run_at === "work" && check.availability === "available" && aggregate.has(check.command)) {
-            throw new AppError("aggregate_check_requires_code_gate", "A project aggregate check must run at CODE or readiness, not inside one scoped Work", 2, {
-                check_id: check.id,
-                command: check.command,
-                run_at: check.run_at
-            });
-        }
-    }
-}
-export function checksForRunAt(checks, runAt) {
-    return checks.filter((check) => check.run_at === runAt);
-}
-/** One SSOT for the final CODE gate, reused after CODE-REVIEW repairs. */
-export function finalCodeCheckDeclarations(workspaceRoot, declared) {
-    const selected = [...aggregateCheckDeclarations(workspaceRoot), ...declared.filter((check) => check.run_at === "code" || check.run_at === "readiness")];
-    const unique = new Map();
-    for (const check of selected)
-        if (!unique.has(check.id))
-            unique.set(check.id, check);
-    return [...unique.values()];
-}
-/** Prevent an unchanged failed stage gate from rerunning expensive commands. */
-export function unchangedFinalGateFailures(context, input) {
-    const wanted = new Set(input.declarations.map((check) => check.id));
-    const current = workspaceFingerprint(input.workspaceRoot);
-    const latest = new Map();
-    for (const receipt of checkReceipts(context, { projectId: input.projectId, runId: input.runId }).filter((item) => item.scope === "aggregate" && wanted.has(item.declaration_id)))
-        latest.set(receipt.declaration_id, receipt);
-    return [...latest.values()].filter((receipt) => receipt.status === "failed" && receipt.workspace_fingerprint === current);
-}
-export function validateCheckDeclaration(workspaceRoot, check) {
-    if (check.availability !== "planned") {
-        validateCodeCheckCommands(workspaceRoot, [check.command]);
-        return;
-    }
-    if (!check.command.startsWith("@check/")) {
-        throw new AppError("planned_check_requires_alias", "A planned CODE check must declare a new @check/... alias", 2, { check_id: check.id, command: check.command });
-    }
-    if (!check.definition?.trim()) {
-        throw new AppError("planned_check_definition_missing", "A planned CODE check must declare its exact alias definition", 2, { check_id: check.id, command: check.command });
-    }
-    const file = path.join(workspaceRoot, ".memory-bank", "spec", "engineering", "code-check-profile.json");
-    const profile = fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, "utf8")) : {};
-    const aliases = profile.aliases && typeof profile.aliases === "object" && !Array.isArray(profile.aliases) ? profile.aliases : {};
-    const actual = aliases[check.command];
-    if (typeof actual !== "string")
-        throw new AppError("planned_check_not_materialized", "A planned check alias was not materialized by its provider Work", 2, { check_id: check.id, command: check.command, provider: check.provided_by ?? null });
-    if (check.definition && actual !== check.definition)
-        throw new AppError("planned_check_definition_mismatch", "A planned check alias does not match its declared definition", 2, { check_id: check.id, command: check.command, expected: check.definition, actual });
-}
-function collectRequiredArtifacts(root, required) {
-    const missing = [];
-    const items = required.map((relative) => {
-        if (path.isAbsolute(relative) || relative.split(path.sep).includes(".."))
-            throw new AppError("invalid_evidence_path", "Required evidence paths must be relative to DD_FLOW_EVIDENCE_DIR", 2, { path: relative });
-        const file = path.join(root, relative);
-        if (!fs.existsSync(file) || !fs.statSync(file).isFile()) {
-            missing.push(relative);
-            return null;
-        }
-        return { path: relative, sha256: crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex") };
-    }).filter((item) => item !== null);
-    return { complete: missing.length === 0, missing, items };
-}
-export function workspaceFingerprint(root) {
-    const git = spawnSync("git", ["ls-files", "-co", "--exclude-standard", "-z"], { cwd: root, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
-    const listing = git.status === 0 ? git.stdout.split("\0").filter(Boolean).sort() : listFiles(root);
-    const hash = crypto.createHash("sha256");
-    for (const relative of listing) {
-        const file = path.join(root, relative);
-        hash.update(relative).update("\0");
-        hash.update(fs.existsSync(file) && fs.statSync(file).isFile() ? fs.readFileSync(file) : "<missing>");
-        hash.update("\0");
-    }
-    return hash.digest("hex");
-}
-function listFiles(root, current = root) {
-    return fs.readdirSync(current, { withFileTypes: true }).flatMap((entry) => {
-        if ([".git", "node_modules"].includes(entry.name))
-            return [];
-        const absolute = path.join(current, entry.name);
-        return entry.isDirectory() ? listFiles(root, absolute) : [path.relative(root, absolute)];
-    }).sort();
-}
-function runCheck(command, cwd, environment, stdout, stderr, heartbeat) {
-    return new Promise((resolve) => {
-        const started = Date.now();
-        const child = spawn("/bin/sh", ["-lc", command], { cwd, env: environment, stdio: ["ignore", "pipe", "pipe"] });
-        child.stdout.pipe(stdout, { end: false });
-        child.stderr.pipe(stderr, { end: false });
-        const progress = setInterval(() => heartbeat(Math.floor((Date.now() - started) / 1000)), 15_000);
-        let timedOut = false;
-        const timeout = setTimeout(() => { timedOut = true; child.kill("SIGTERM"); }, 15 * 60 * 1000);
-        let error = null;
-        child.once("error", (value) => { error = value.message; });
-        child.once("close", (exitCode, signal) => {
-            clearInterval(progress);
-            clearTimeout(timeout);
-            resolve({ exitCode, error: error ?? (timedOut ? "timed out after 900 seconds" : signal ? `terminated by ${signal}` : null) });
-        });
-    });
-}
-function closeStream(stream) {
-    return new Promise((resolve, reject) => stream.end((error) => error ? reject(error) : resolve()));
-}
+export function unchangedFinalGateFailures(context, input) { const wanted = new Set(input.declarations.flatMap((check) => [check.id, checkRef(check)])); const current = workspaceFingerprint(input.workspaceRoot); const latest = new Map(); for (const receipt of checkReceipts(context, { projectId: input.projectId, runId: input.runId }).filter((item) => item.scope === "aggregate" && item.check_refs.some((ref) => wanted.has(ref))))
+    for (const ref of receipt.check_refs)
+        latest.set(ref, receipt); return [...new Set(latest.values())].filter((receipt) => receipt.status === "failed" && receipt.before_fingerprint === current); }
 export function checkReceipts(context, input) {
     const where = input.workId ? "project_id = ? AND run_id = ? AND work_id = ?" : "project_id = ? AND run_id = ?";
     const params = input.workId ? [input.projectId, input.runId, input.workId] : [input.projectId, input.runId];
-    return context.db.all(`SELECT id, declaration_id, scope, work_id, command, status, exit_code, stdout_path, stderr_path, receipt_path, workspace_fingerprint, artifacts_json, started_at, finished_at FROM check_receipts WHERE ${where} ORDER BY started_at, id`, params).map((receipt) => ({ ...receipt, local_id: receipt.id.slice(receipt.id.lastIndexOf("/") + 1), artifacts: JSON.parse(receipt.artifacts_json) }));
-}
+    return context.db.all(`SELECT id, declaration_id, check_refs_json, gate, scope, work_id, command, input_hash, verification_epoch, status, exit_code, stdout_path, stderr_path, receipt_path, workspace_fingerprint, before_fingerprint, after_fingerprint, profile_hash, mutation_paths_json, artifacts_json, started_at, finished_at FROM check_receipts WHERE ${where} ORDER BY started_at, id`, params).map((row) => ({ ...row, local_id: row.id.slice(row.id.lastIndexOf("/") + 1), check_refs: parseArray(row.check_refs_json, [row.declaration_id]), mutation_paths: parseArray(row.mutation_paths_json, []), artifacts: JSON.parse(row.artifacts_json) }));
+}
+export function workspaceFingerprint(root) { return workspaceState(root).fingerprint; }
+function deduplicate(checks, commands) { const groups = new Map(); checks.forEach((check, index) => { const artifacts = [...(check.required_artifacts ?? [])].sort(); const key = JSON.stringify([check.run_at, commands[index], artifacts]); const current = groups.get(key); if (current)
+    current.declarations.push(check);
+else
+    groups.set(key, { gate: check.run_at, command: commands[index], declarations: [check], requiredArtifacts: artifacts }); }); return [...groups.values()]; }
+function workspaceState(root) { const git = spawnSync("git", ["ls-files", "-co", "--exclude-standard", "-z"], { cwd: root, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 }); const listing = git.status === 0 ? git.stdout.split("\0").filter(Boolean).sort() : listFiles(root); const files = new Map(); const hash = crypto.createHash("sha256"); for (const relative of listing) {
+    const file = path.join(root, relative);
+    const content = fs.existsSync(file) && fs.statSync(file).isFile() ? fs.readFileSync(file) : Buffer.from("<missing>");
+    const digest = crypto.createHash("sha256").update(content).digest("hex");
+    files.set(relative, digest);
+    hash.update(relative).update("\0").update(digest).update("\0");
+} return { fingerprint: hash.digest("hex"), files }; }
+function changedPaths(before, after) { return [...new Set([...before.keys(), ...after.keys()])].filter((key) => before.get(key) !== after.get(key)).sort(); }
+function checkRef(check) { return check.canonical_ref ?? check.id; }
+function parseArray(value, fallback) { try {
+    const parsed = JSON.parse(value);
+    return Array.isArray(parsed) && parsed.every((item) => typeof item === "string") ? parsed : fallback;
+}
+catch {
+    return fallback;
+} }
+function isStringRecord(value) { return Boolean(value) && typeof value === "object" && !Array.isArray(value) && Object.values(value).every((item) => typeof item === "string" && item.trim().length > 0); }
+function isGateRecord(value) { return Boolean(value) && typeof value === "object" && !Array.isArray(value) && Object.entries(value).every(([gate, aliases]) => ["work", "code", "readiness", "merge", "release", "external"].includes(gate) && Array.isArray(aliases) && aliases.every((item) => typeof item === "string" && item.startsWith("@check/"))); }
+function collectRequiredArtifacts(root, required) { const missing = []; const items = []; for (const relative of required) {
+    if (path.isAbsolute(relative) || relative.split(/[\\/]/).includes(".."))
+        throw new AppError("invalid_evidence_path", "Required evidence paths must be relative to DD_FLOW_EVIDENCE_DIR", 2, { path: relative });
+    const file = path.join(root, relative);
+    if (!fs.existsSync(file) || !fs.statSync(file).isFile()) {
+        missing.push(relative);
+        continue;
+    }
+    items.push({ path: relative, sha256: crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex") });
+} return { complete: missing.length === 0, missing, items }; }
+function listFiles(root, current = root) { return fs.readdirSync(current, { withFileTypes: true }).flatMap((entry) => { if ([".git", "node_modules"].includes(entry.name))
+    return []; const absolute = path.join(current, entry.name); return entry.isDirectory() ? listFiles(root, absolute) : [path.relative(root, absolute)]; }).sort(); }
+function runCheck(command, cwd, environment, stdout, stderr, heartbeat) { return new Promise((resolve) => { const started = Date.now(); const child = spawn("/bin/sh", ["-lc", command], { cwd, env: environment, stdio: ["ignore", "pipe", "pipe"], detached: process.platform !== "win32" }); child.stdout.pipe(stdout, { end: false }); child.stderr.pipe(stderr, { end: false }); const progress = setInterval(() => heartbeat(Math.floor((Date.now() - started) / 1000)), 15_000); let timedOut = false; let error = null; let escalation; const timeout = setTimeout(() => { timedOut = true; terminateProcessGroup(child.pid, "SIGTERM"); escalation = setTimeout(() => terminateProcessGroup(child.pid, "SIGKILL"), 5_000); }, 15 * 60 * 1000); child.once("error", (value) => { error = value.message; }); child.once("close", (exitCode, signal) => { clearInterval(progress); clearTimeout(timeout); if (escalation)
+    clearTimeout(escalation); resolve({ exitCode, error: error ?? (timedOut ? "timed out after 900 seconds" : signal ? `terminated by ${signal}` : null), aborted: timedOut || Boolean(signal) || Boolean(error) }); }); }); }
+function terminateProcessGroup(pid, signal) { if (!pid)
+    return; try {
+    process.kill(process.platform === "win32" ? pid : -pid, signal);
+}
+catch { /* already exited */ } }
+function closeStream(stream) { return new Promise((resolve, reject) => stream.end((error) => error ? reject(error) : resolve())); }

package/dist/services/eval-snapshots.js

@@ -61,9 +61,10 @@ export function createEvalRunSnapshot(context, input) {
         assertStageEntry(status.index.stage_runs ?? [], input.stageEntry);
     else
         throw new AppError("usage", "Snapshot requires exactly one of stageEntry or candidate", 2);
+    const allowedCreatedResultSchema = input.stageEntry ? createdWorkSchemaForStage(input.stageEntry) : null;
     const activeChildren = input.candidate
         ? context.db.get("SELECT COUNT(*) AS count FROM works WHERE project_id = ? AND run_id = ? AND parent_work_id IS NOT NULL AND status IN ('created', 'running', 'paused')", [project.id, input.runId])?.count ?? 0
-        : context.db.get("SELECT COUNT(*) AS count FROM works WHERE project_id = ? AND run_id = ? AND parent_work_id IS NOT NULL AND (status IN ('running', 'paused') OR (status = 'created' AND (? <> 'code' OR COALESCE(result_schema, '') NOT LIKE 'dd-flow/code-work-result@%')))", [project.id, input.runId, input.stageEntry])?.count ?? 0;
+        : context.db.get("SELECT COUNT(*) AS count FROM works WHERE project_id = ? AND run_id = ? AND parent_work_id IS NOT NULL AND (status IN ('running', 'paused') OR (status = 'created' AND (? IS NULL OR COALESCE(result_schema, '') NOT LIKE ?)))", [project.id, input.runId, allowedCreatedResultSchema, allowedCreatedResultSchema ? `${allowedCreatedResultSchema}@%` : ""])?.count ?? 0;
     if (activeChildren > 0)
         throw new AppError("snapshot_not_quiescent", `${input.candidate ? "Candidate" : "Stage-entry"} snapshot requires no active child Work`, 1, { run_id: input.runId, active_children: activeChildren });
     const output = path.resolve(input.output);
@@ -106,6 +107,14 @@ export function createEvalRunSnapshot(context, input) {
     writeJson(path.join(output, "snapshot.json"), manifest);
     return { ok: true, snapshot: output, ...manifest };
 }
+/** A not-yet-started Work packet may be part of the target Stage's entry state. */
+function createdWorkSchemaForStage(stage) {
+    if (stage === "code")
+        return "dd-flow/code-work-result";
+    if (stage === "merge")
+        return "dd-flow/merge-result";
+    return null;
+}
 export function restoreEvalRunSnapshot(context, input) {
     const snapshot = path.resolve(input.snapshot);
     const manifest = readManifest(snapshot);

package/dist/services/harness-adapter.js

@@ -0,0 +1,59 @@
+import { spawn } from "node:child_process";
+import { AppError } from "../shared/errors.js";
+/** Runs one harness command with the lifecycle guarantees shared by agent services. */
+export function runHarnessAdapter(input) {
+    const timeoutMs = input.timeoutMs ?? 120_000;
+    return new Promise((resolve, reject) => {
+        const detached = process.platform !== "win32";
+        const child = spawn(input.executable, input.args, { env: input.env, detached, stdio: ["ignore", "pipe", "pipe"] });
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        let killTimer;
+        const terminate = (signal) => { try {
+            if (detached && child.pid)
+                process.kill(-child.pid, signal);
+            else
+                child.kill(signal);
+        }
+        catch { /* The process already settled. */ } };
+        const heartbeat = input.progress && input.progressMessage ? setInterval(() => input.progress?.(`${input.progressMessage}; waiting for adapter completion`), 15_000) : undefined;
+        const timer = setTimeout(() => { timedOut = true; terminate("SIGTERM"); killTimer = setTimeout(() => terminate("SIGKILL"), 5_000); }, timeoutMs);
+        const evidence = (value) => input.onEvidence?.({ executable: input.executable, args: input.args, ...value, at: new Date().toISOString() });
+        child.stdout.setEncoding("utf8").on("data", (chunk) => { stdout += chunk; });
+        child.stderr.setEncoding("utf8").on("data", (chunk) => { stderr += chunk; });
+        child.once("error", (error) => { clearTimeout(timer); if (heartbeat)
+            clearInterval(heartbeat); if (killTimer)
+            clearTimeout(killTimer); evidence({ status: null, error: error.message }); reject(new AppError("merge_adapter_failed", "Harness adapter call failed", 1, { executable: input.executable, args: input.args.slice(0, 3), error: error.message })); });
+        child.once("close", (status, signal) => {
+            clearTimeout(timer);
+            if (heartbeat)
+                clearInterval(heartbeat);
+            if (killTimer)
+                clearTimeout(killTimer);
+            evidence({ status, signal, timed_out: timedOut, stdout, stderr });
+            if (timedOut)
+                return reject(new AppError("merge_adapter_timeout", "Harness adapter call timed out", 1, { executable: input.executable, args: input.args.slice(0, 3), timeout_ms: timeoutMs }));
+            if (status !== 0)
+                return reject(new AppError("merge_adapter_failed", "Harness adapter call failed", 1, { executable: input.executable, args: input.args.slice(0, 3), status, signal, stderr }));
+            try {
+                resolve(JSON.parse(stdout));
+            }
+            catch {
+                reject(new AppError("merge_adapter_invalid", "Harness adapter returned invalid JSON", 1, { executable: input.executable, stdout }));
+            }
+        });
+    });
+}
+export function adapterSessionId(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    for (const [key, item] of Object.entries(value)) {
+        if (["session_id", "sessionId", "provider_session_id", "providerSessionId", "adapter_session_id", "adapterSessionId", "thread_id", "threadId", "conversation_id"].includes(key) && typeof item === "string")
+            return item;
+        const nested = adapterSessionId(item);
+        if (nested)
+            return nested;
+    }
+    return null;
+}