@deksden-com/dd-flow-cli 0.9.0-beta.145 → 0.9.0-beta.149

package/dist/services/diagnostic-work-registration.js

@@ -0,0 +1,101 @@
+import { AppError } from "../shared/errors.js";
+import { isDiagnosticFlow } from "../domain/diagnostic-flows.js";
+import { requireProjectByRoot } from "./projects.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { readFlowRunExecutionBundle, assertPreparedRunBundleSqlAuthority } from "./runs.js";
+import { readDescriptorStageInput } from "./descriptor-stage-coordinator.js";
+import { readDescriptorRootWork } from "./descriptor-root-work.js";
+import { diagnosticSnapshotPaths, readDiagnosticSnapshot, readDiagnosticSnapshotCustody } from "./diagnostic-snapshot.js";
+import { readAcceptedStageData } from "./stage-report-renderer.js";
+import { validateDiagnosticStageResult } from "./diagnostic-stage-results.js";
+import { diagnosticWorkBatch } from "./diagnostic-work-batch.js";
+import { addWorkBatch, prepareWorkBatch, readWorkBatchCustody } from "./work-registry.js";
+import { stageGraphScope } from "./stage-work-graph.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { appendAudit } from "./audit.js";
+const event = "diagnostic.work_registration";
+function refuse(reason) { throw new AppError("diagnostic_work_registration_invalid", "Diagnostic graph lacks its assigned stage authority", 2, { reason, effect: "no_effect" }); }
+/** SQL-only reader. An explicitly registered empty graph is distinct from no graph. */
+export function readRegisteredDiagnosticGraph(context, scope) {
+    const graph = stageGraphScope(context, scope.projectId, scope.runId, scope.stage);
+    const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type=? AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.stage')=? AND json_extract(payload_json,'$.attempt')=? LIMIT 2", [scope.projectId, event, scope.runId, scope.stage, graph.attempt]);
+    if (!rows.length)
+        return null;
+    if (rows.length !== 1 || Buffer.byteLength(rows[0].payload_json) > 2 * 1024 * 1024)
+        refuse("ambiguous_registration");
+    const receipt = JSON.parse(rows[0].payload_json);
+    if (receipt.schema_id !== "dd-flow/diagnostic-work-registration@1" || receipt.run_id !== scope.runId
+        || receipt.stage !== scope.stage || receipt.attempt !== graph.attempt || !receipt.work_ids
+        || receipt.input.run_id !== scope.runId || receipt.input.stage !== scope.stage
+        || receipt.input.input_sha256 !== receipt.input_sha256)
+        refuse("foreign_registration");
+    const batch = diagnosticWorkBatch(receipt.input);
+    if (receipt.batch_sha256 !== hybridDigest(batch.works) || batch.works.length !== Object.keys(receipt.work_ids).length
+        || new Set(Object.values(receipt.work_ids)).size !== batch.works.length)
+        refuse("changed_batch");
+    for (const item of batch.works) {
+        const id = receipt.work_ids[item.key];
+        if (!id)
+            refuse("missing_work");
+        const custody = readWorkBatchCustody(context, id);
+        if (custody.item_key !== item.key || custody.batch_sha256 !== receipt.batch_sha256
+            || hybridDigest(custody.work_ids) !== hybridDigest(receipt.work_ids)
+            || hybridDigest(custody.scope) !== hybridDigest({ ...graph, stage: scope.stage,
+                parent_work_id: receipt.parent_work_id, request_key: "diagnostic-graph" }))
+            refuse("changed_work_custody");
+    }
+    return receipt;
+}
+/** The registered handler calls this only after generic Stage entry. Applicability
+ * and candidates come from the accepted predecessor, not a caller-owned batch. */
+export function registerDiagnosticStageGraph(context, input) {
+    const bundle = readFlowRunExecutionBundle(context, input), project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    if (!bundle || !isDiagnosticFlow(bundle.manifest.flow_id) || !["audit", "analyze", "review"].includes(input.stage))
+        refuse("diagnostic_stage_required");
+    const flowId = bundle.manifest.flow_id, frozen = bundle.execution.snapshot().scope;
+    const scope = { projectId: project.id, runId: input.runId, stage: input.stage };
+    const selection = readDescriptorStageInput(context, scope, bundle), root = readDescriptorRootWork(context, scope, bundle);
+    const snapshotSelection = { projectId: project.id, projectRoot: frozen.projectRoot, sourceRoot: frozen.projectRoot, requestId: frozen.requestId, flowId };
+    const snapshot = readDiagnosticSnapshot(context, snapshotSelection, input.runId);
+    if (!snapshot || snapshot.root !== frozen.workspace)
+        refuse("snapshot_required");
+    const previousStage = input.stage === "review" ? flowId === "mb-audit" ? "audit" : "analyze" : "preflight";
+    if (selection.input.predecessor?.stage !== previousStage)
+        refuse("predecessor_required");
+    const previousScope = { ...scope, stage: previousStage };
+    const accepted = readAcceptedStageData(context, previousScope), previousInput = readDescriptorStageInput(context, previousScope, bundle, true, true);
+    const previous = validateDiagnosticStageResult(accepted.bytes, bundle.descriptor.stageBlob(previousStage, "result_schema"), {
+        flowId, runId: input.runId, stage: previousStage, inputSha256: previousInput.inputSha256,
+        snapshotRoot: diagnosticSnapshotPaths(context, snapshot, input.runId).root, snapshotSha256: snapshot.source_sha256,
+        predecessors: previousInput.input.predecessor ? [{ stage: previousInput.input.predecessor.stage,
+                path: previousInput.input.predecessor.result.path, sha256: previousInput.input.predecessor.result.sha256 }] : []
+    });
+    const workInput = { flow_id: flowId, run_id: input.runId, stage: input.stage,
+        input_sha256: selection.inputSha256, snapshot_sha256: snapshot.source_sha256,
+        instruction: bundle.descriptor.stageBlob(input.stage, "instruction").toString("utf8"),
+        coverage: previous.details.coverage, candidates: input.stage === "review" ? previous.details.findings : [],
+        support: bundle.manifest.inventory.filter(ref => ref.path.startsWith("support/")).map(ref => ({ path: `execution-bundle/${ref.path}`, sha256: ref.sha256 })) };
+    const batch = diagnosticWorkBatch(workInput), batchInput = { parentWorkId: root.workId, stage: input.stage, requestKey: "diagnostic-graph", value: batch };
+    const prepared = batch.works.length ? prepareWorkBatch(context, batchInput) : [];
+    return context.db.writeTransaction(() => {
+        assertPreparedRunBundleSqlAuthority(context, scope, bundle);
+        if (hybridDigest(readDiagnosticSnapshotCustody(context, snapshotSelection, input.runId)) !== hybridDigest(snapshot)
+            || hybridDigest(readDescriptorStageInput(context, scope, bundle)) !== hybridDigest(selection)
+            || hybridDigest(readAcceptedStageData(context, previousScope)) !== hybridDigest(accepted)
+            || readDescriptorRootWork(context, scope, bundle).workId !== root.workId)
+            refuse("stage_authority_changed");
+        const expected = { schema_id: "dd-flow/diagnostic-work-registration@1", run_id: input.runId, stage: input.stage,
+            attempt: selection.attempt, parent_work_id: root.workId, bundle_sha256: bundle.sha256,
+            input_sha256: selection.inputSha256, input: workInput, batch_sha256: hybridDigest(batch.works) };
+        const prior = readRegisteredDiagnosticGraph(context, scope);
+        if (prior) {
+            if (hybridDigest({ ...prior, work_ids: undefined }) !== hybridDigest(expected))
+                refuse("registration_changed");
+            return prior;
+        }
+        const workIds = batch.works.length ? addWorkBatch(context, { ...batchInput, prepared }).work_ids : {};
+        const receipt = { ...expected, work_ids: workIds };
+        appendAudit(context, { projectId: project.id, eventType: event, payload: receipt });
+        return readRegisteredDiagnosticGraph(context, scope);
+    });
+}

package/dist/services/diagnostic-work-results.js

@@ -0,0 +1,93 @@
+import { Ajv2020 } from "ajv/dist/2020.js";
+import { verifyDiagnosticSources, verifyDiagnosticCritic } from "./diagnostic-evidence.js";
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+const refuse = (reason) => {
+    throw new AppError("diagnostic_work_result_invalid", "Diagnostic Work result does not match its assigned task", 2, { reason, effect: "no_effect", ...(reason === "invalid_schema" ? { phase: "prepare", recoverable: true } : {}) });
+};
+/** Accepts semantic data only after the caller has established completed Work,
+ * immutable batch custody and physical Session independence. */
+export function validateDiagnosticWorkResult(bytes, schemaBytes, snapshotRoot, input, assignment) {
+    if (!bytes.length || bytes.length > 1024 * 1024 || schemaBytes.length > 1024 * 1024)
+        refuse("result_exceeds_bound");
+    const validate = (() => {
+        try {
+            const schema = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(schemaBytes));
+            if (schema.$id !== "dd-flow/diagnostic-work-result@1")
+                refuse("frozen_schema_invalid");
+            return new Ajv2020({ strict: false, validateFormats: false }).compile(schema);
+        }
+        catch {
+            return refuse("frozen_schema_invalid");
+        }
+    })();
+    let result;
+    try {
+        result = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        return refuse("invalid_schema");
+    }
+    if (!validate(result))
+        refuse("invalid_schema");
+    if (result.flow_id !== input.flow_id || result.run_id !== input.run_id || result.stage !== input.stage
+        || result.work_id !== assignment.workId || result.aspect_id !== assignment.aspectId)
+        refuse("foreign_assignment");
+    verifyDiagnosticSources(snapshotRoot, result.sources);
+    if (assignment.role === "critic") {
+        if (input.stage !== "review" || result.findings.length)
+            refuse("critic_cannot_replace_candidates");
+        verifyDiagnosticCritic(snapshotRoot, input.candidates, result.decisions);
+    }
+    else {
+        if (input.stage === "review" || result.decisions.length
+            || !input.coverage.some(value => value.id === assignment.aspectId && value.applicability === "applicable"))
+            refuse("foreign_aspect");
+        const ids = new Set();
+        for (const finding of result.findings) {
+            if (ids.has(finding.id) || finding.aspect_id !== assignment.aspectId || !finding.evidence.length)
+                refuse("foreign_or_duplicate_finding");
+            ids.add(finding.id);
+            verifyDiagnosticSources(snapshotRoot, finding.evidence);
+        }
+    }
+    return result;
+}
+/** Work-local IDs are not globally unique. Keep their origin when assigning
+ * stable report IDs, so one author's FIND-1 cannot overwrite another's. */
+export function collectDiagnosticCandidates(results) {
+    const findings = [], origins = [];
+    const seen = new Set();
+    for (const [workIndex, item] of results.entries()) {
+        if (seen.has(item.workId) || item.result.work_id !== item.workId || item.result.stage === "review")
+            refuse("duplicate_or_foreign_work");
+        seen.add(item.workId);
+        for (const [findingIndex, finding] of item.result.findings.entries()) {
+            const id = `FIND-${String(workIndex + 1).padStart(3, "0")}-${String(findingIndex + 1).padStart(3, "0")}`;
+            findings.push({ ...structuredClone(finding), id });
+            origins.push({ id, work_id: item.workId, original_id: finding.id });
+        }
+    }
+    return { findings, origins };
+}
+/** Assign CLI-owned global IDs only to an exact, ordered copy of admitted Work
+ * findings. Any other proposal still goes through the ordinary strict guards. */
+export function sealDiagnosticCandidateIds(bytes, results) {
+    if (!bytes.length || bytes.length > 1024 * 1024)
+        return bytes;
+    let value;
+    try {
+        value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        return bytes;
+    }
+    if (!value || !Array.isArray(value.details?.findings)
+        || hybridDigest(value.details.findings) !== hybridDigest(results.flatMap(item => item.result.findings)))
+        return bytes;
+    const canonical = collectDiagnosticCandidates(results).findings;
+    if (hybridDigest(value.details.findings) === hybridDigest(canonical))
+        return bytes;
+    value.details.findings = canonical;
+    return Buffer.from(JSON.stringify(value));
+}

package/dist/services/eval-snapshots.js

@@ -23,12 +23,13 @@ import { localEnvironmentAllowed, projectServicePathFilter } from "./workspace-f
 import { cleanupScopeWriters } from "./scope-writer-cleanup.js";
 import { PreparedInstalledFlowSource } from "./installed-flow-source.js";
 import { readSetupStatus } from "./setup.js";
+import { isDiagnosticFlow } from "../domain/diagnostic-flows.js";
 import { isObservationOperation, nativeInventoryVersion, retainedDaemonOperations } from "./run-control.js";
 /** Capture the only flow boundary which exists before `stage start --bootstrap` creates a RUN. */
 export function prepareEvalBootstrapSnapshot(context, input) {
     let source;
     if (input.flow !== undefined && input.flow !== "sdlc") {
-        if (input.flow !== "mb-init" && input.flow !== "mb-upgrade")
+        if (input.flow !== "mb-init" && input.flow !== "mb-upgrade" && !isDiagnosticFlow(input.flow))
             throw new AppError("snapshot_flow_unsupported", "Bootstrap snapshot flow is not registered", 2, { phase: "prepare", effect: "no_effect" });
         const home = context.env.DD_FLOW_CONFIG_HOME ?? context.ddFlowHome;
         const selected = readSetupStatus(home);
@@ -70,7 +71,7 @@ export function createEvalBootstrapSnapshot(context, input) {
         const manifest = {
             schema_id: source ? "dd-eval/bootstrap-snapshot@2" : "dd-eval/bootstrap-snapshot@1",
             stage: source?.resolveRegisteredFlow().descriptor.stages[0]?.id ?? "specify",
-            ...(source ? { flow: { id: input.flow === "mb-upgrade" ? "mb-upgrade" : "mb-init", source_sha256: source.sha256, descriptor_sha256: source.descriptorReference().sha256 } } : {}),
+            ...(source ? { flow: { id: source.resolveRegisteredFlow().descriptor.id, source_sha256: source.sha256, descriptor_sha256: source.descriptorReference().sha256 } } : {}),
             project_root: projectRoot,
             project_sha256: treeHash(path.join(temporary, "project")),
             project_git: snapshotProjectGit(projectRoot, temporary)
@@ -222,7 +223,7 @@ export function prepareEvalRunSnapshotCreation(context, input) {
         throw new AppError("snapshot_output_inside_project", "Snapshot output must be outside the project and RUN workspace trees", 1, { output });
     prepareOutputFile(output);
     prepareSnapshotProjectGit(projectRoot, recovery && status.run.flow_kind === "mb-init");
-    prepareSnapshotWorkspace(workspaceRoot, projectRoot);
+    prepareSnapshotWorkspace(workspaceRoot, projectRoot, isDiagnosticFlow(status.run.flow_kind));
     return { projectRoot, project, status, recovery, output, workspaceRoot, activeChildren };
 }
 function captureEvalRunSnapshot(context, input) {
@@ -240,7 +241,7 @@ function captureEvalRunSnapshot(context, input) {
         }
     }
     else
-        copyRuntimeTree(context.ddFlowHome, path.join(output, "runtime"), false, [...databaseFiles, ...codexExclusions], grokProviderHomes(context.ddFlowHome), input.observationCuts);
+        copyRuntimeTree(context.ddFlowHome, path.join(output, "runtime"), false, [...databaseFiles, ...codexExclusions, ...(isDiagnosticFlow(status.run.flow_kind) ? [workspaceRoot] : [])], grokProviderHomes(context.ddFlowHome), input.observationCuts);
     for (const [file, cut] of input.journalCuts ?? []) {
         const target = path.join(output, "runtime", path.relative(context.ddFlowHome, file));
         fs.mkdirSync(path.dirname(target), { recursive: true });
@@ -280,7 +281,7 @@ function captureEvalRunSnapshot(context, input) {
         filter: projectPayloadFilter(projectRoot)
     });
     const projectGit = snapshotProjectGit(projectRoot, output, recovery && status.run.flow_kind === "mb-init");
-    const workspace = snapshotWorkspace(workspaceRoot, projectRoot, output);
+    const workspace = snapshotWorkspace(workspaceRoot, projectRoot, output, isDiagnosticFlow(status.run.flow_kind));
     // Accepted Work results are captured in SQLite. Their file representations
     // are retained evidence, not a second authority or a checkpoint gate.
     if (recovery) {
@@ -293,7 +294,7 @@ function captureEvalRunSnapshot(context, input) {
         }
     }
     const manifest = {
-        schema_id: projectGit.state === "unborn" ? "dd-flow/eval-run-snapshot@6" : "dd-flow/eval-run-snapshot@5",
+        schema_id: workspace.kind === "git_repository" ? "dd-flow/eval-run-snapshot@7" : projectGit.state === "unborn" ? "dd-flow/eval-run-snapshot@6" : "dd-flow/eval-run-snapshot@5",
         run_id: input.runId,
         project_id: project.id,
         project_root: projectRoot,
@@ -310,7 +311,7 @@ function captureEvalRunSnapshot(context, input) {
         ...(input.observationCuts ? { observation_cuts: [...input.observationCuts].map(([file, receipt]) => ({ path: path.relative(context.ddFlowHome, file), receipt })) } : {}),
         project_git: projectGit,
         workspace,
-        payload_modes: { project: treeModesHash(path.join(output, "project")), runtime: treeModesHash(path.join(output, "runtime")), ...(workspace.kind === "git_worktree" ? { workspace: treeModesHash(path.join(output, "workspace")) } : {}) },
+        payload_modes: { project: treeModesHash(path.join(output, "project")), runtime: treeModesHash(path.join(output, "runtime")), ...(workspace.kind !== "project" ? { workspace: treeModesHash(path.join(output, "workspace")) } : {}) },
         source_status: status
     };
     writeJson(path.join(output, "snapshot.json"), manifest);
@@ -436,7 +437,7 @@ export function prepareSnapshotOperationalDecision(input) {
 }
 function assertRunRestoreTargets(context, input, snapshot, projectRoot, manifest) {
     assertRestoreTargetSeparation(snapshot, [projectRoot, context.ddFlowHome]);
-    if (manifest.workspace.kind === "git_worktree") {
+    if (manifest.workspace.kind !== "project") {
         const workspaceRoot = restoredWorkspaceRoot(manifest, projectRoot, context.ddFlowHome);
         assertRestoreTargetSeparation(snapshot, [workspaceRoot]);
         if (isInside(physicalPath(projectRoot), physicalPath(workspaceRoot)) || isInside(physicalPath(workspaceRoot), physicalPath(projectRoot)) || physicalPath(workspaceRoot) === physicalPath(context.ddFlowHome))
@@ -760,27 +761,29 @@ function rebaseStructuredValue(value, oldRoot, newRoot, oldWorkspace, newWorkspa
 function rebasePathString(value, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome) { for (const [oldPrefix, newPrefix] of [[oldHome, newHome], [oldWorkspace, newWorkspace], [oldRoot, newRoot]])
     if (value === oldPrefix || value.startsWith(`${oldPrefix}${path.sep}`))
         return `${newPrefix}${value.slice(oldPrefix.length)}`; return value; }
-function prepareSnapshotWorkspace(workspaceRoot, projectRoot) {
+function prepareSnapshotWorkspace(workspaceRoot, projectRoot, allowUnborn = false) {
     if (samePath(workspaceRoot, projectRoot))
         return null;
     const branch = git(workspaceRoot, ["symbolic-ref", "--quiet", "--short", "HEAD"]);
     if (!branch)
         throw new AppError("snapshot_workspace_invalid", "Feature workspace must be on a named Git branch", 1, { workspace_root: workspaceRoot });
     const baseRef = git(workspaceRoot, ["rev-parse", "HEAD"]);
-    if (!baseRef)
+    if (!baseRef && !(allowUnborn && git(workspaceRoot, ['for-each-ref', '--format=%(refname)']) === ''))
         throw new AppError("snapshot_workspace_invalid", "Feature workspace has no readable HEAD", 1, { workspace_root: workspaceRoot });
     return { branch, baseRef };
 }
-function snapshotWorkspace(workspaceRoot, projectRoot, output) {
-    const prepared = prepareSnapshotWorkspace(workspaceRoot, projectRoot);
+function snapshotWorkspace(workspaceRoot, projectRoot, output, independent = false) {
+    const prepared = prepareSnapshotWorkspace(workspaceRoot, projectRoot, independent);
     if (!prepared)
         return { kind: "project" };
     const { branch, baseRef } = prepared;
     const workspace = path.join(output, "workspace");
     const bundle = path.join(output, "workspace.bundle");
     fs.cpSync(workspaceRoot, workspace, { recursive: true, verbatimSymlinks: true, filter: projectPayloadFilter(workspaceRoot) });
-    runGit(projectRoot, ["bundle", "create", bundle, branch]);
-    return { kind: "git_worktree", source_root: workspaceRoot, branch, base_ref: baseRef, sha256: treeHash(workspace), bundle_sha256: fileHash(bundle), ...snapshotIndex(workspaceRoot, output, "workspace") };
+    if (baseRef === null)
+        return { kind: 'git_repository', source_root: workspaceRoot, branch, base_ref: null, bundle_sha256: null, state: 'unborn', sha256: treeHash(workspace), ...snapshotIndex(workspaceRoot, output, 'workspace') };
+    runGit(independent ? workspaceRoot : projectRoot, ["bundle", "create", bundle, branch]);
+    return { kind: independent ? "git_repository" : "git_worktree", source_root: workspaceRoot, branch, base_ref: baseRef, sha256: treeHash(workspace), bundle_sha256: fileHash(bundle), ...snapshotIndex(workspaceRoot, output, "workspace") };
 }
 function restoreWorkspace(snapshot, manifest, projectRoot, ddFlowHome) {
     if (manifest.workspace.kind === "project")
@@ -789,15 +792,28 @@ function restoreWorkspace(snapshot, manifest, projectRoot, ddFlowHome) {
     const bundle = path.join(snapshot, "workspace.bundle");
     if (treeHash(source) !== manifest.workspace.sha256)
         throw new AppError("snapshot_checksum_mismatch", "Snapshot workspace checksum does not match manifest", 1, { snapshot });
-    if (!fs.existsSync(bundle) || fileHash(bundle) !== manifest.workspace.bundle_sha256)
+    if (manifest.workspace.state === 'unborn' ? fs.existsSync(bundle) : !fs.existsSync(bundle) || fileHash(bundle) !== manifest.workspace.bundle_sha256)
         throw new AppError("snapshot_checksum_mismatch", "Snapshot workspace Git bundle does not match manifest", 1, { snapshot });
     const workspaceRoot = restoredWorkspaceRoot(manifest, projectRoot, ddFlowHome);
     if (fs.existsSync(workspaceRoot))
         throw new AppError("snapshot_workspace_target_exists", "Snapshot feature workspace target already exists", 1, { workspace_root: workspaceRoot });
-    runGit(projectRoot, ["fetch", bundle, `+refs/heads/${manifest.workspace.branch}:refs/heads/${manifest.workspace.branch}`]);
-    if (git(projectRoot, ["rev-parse", `refs/heads/${manifest.workspace.branch}`]) !== manifest.workspace.base_ref)
-        throw new AppError("snapshot_workspace_restore_failed", "Snapshot Git bundle did not restore the frozen feature base", 1, { branch: manifest.workspace.branch, expected_base: manifest.workspace.base_ref });
-    runGit(projectRoot, ["worktree", "add", workspaceRoot, manifest.workspace.branch]);
+    if (manifest.workspace.kind === 'git_repository') {
+        fs.mkdirSync(path.dirname(workspaceRoot), { recursive: true });
+        if (manifest.workspace.state === 'unborn') {
+            fs.mkdirSync(workspaceRoot);
+            runGit(workspaceRoot, ['-c', 'init.templateDir=', 'init', '--initial-branch', manifest.workspace.branch]);
+        }
+        else
+            runGit(projectRoot, ['clone', '--no-checkout', '--branch', manifest.workspace.branch, bundle, workspaceRoot]);
+    }
+    else {
+        runGit(projectRoot, ["fetch", bundle, `+refs/heads/${manifest.workspace.branch}:refs/heads/${manifest.workspace.branch}`]);
+        if (git(projectRoot, ["rev-parse", `refs/heads/${manifest.workspace.branch}`]) !== manifest.workspace.base_ref)
+            throw new AppError("snapshot_workspace_restore_failed", "Snapshot Git bundle did not restore the frozen feature base", 1, { branch: manifest.workspace.branch, expected_base: manifest.workspace.base_ref });
+        runGit(projectRoot, ["worktree", "add", workspaceRoot, manifest.workspace.branch]);
+    }
+    if (git(workspaceRoot, ["rev-parse", "HEAD"]) !== manifest.workspace.base_ref)
+        throw new AppError("snapshot_workspace_restore_failed", "Snapshot Git bundle did not restore the frozen workspace base", 1, { branch: manifest.workspace.branch, expected_base: manifest.workspace.base_ref });
     replaceProjectTree(workspaceRoot, source);
     restoreIndex(snapshot, "workspace", manifest.workspace, workspaceRoot);
     return fs.realpathSync(workspaceRoot);
@@ -847,7 +863,7 @@ function restoreProjectGit(snapshot, source, projectRoot) {
     restoreIndex(snapshot, "project", source, projectRoot);
 }
 const mergeStateFiles = ["MERGE_HEAD", "MERGE_MSG", "MERGE_MODE", "ORIG_HEAD", "AUTO_MERGE"];
-function indexEntries(root) {
+function indexEntries(root, includeExclude = true) {
     const entries = Buffer.from(gitBytes(root, ["ls-files", "--stage", "-z"])
         .toString("utf8").split("\0").filter(entry => entry && localEnvironmentAllowed(entry.slice(entry.indexOf("\t") + 1)))
         .map(entry => `${entry}\0`).join(""));
@@ -860,7 +876,22 @@ function indexEntries(root) {
         if (fs.existsSync(resolved))
             merge[name] = fs.readFileSync(resolved).toString("base64");
     }
-    return Buffer.from(JSON.stringify({ entries: entries.toString("base64"), merge }));
+    if (!includeExclude)
+        return Buffer.from(JSON.stringify({ entries: entries.toString("base64"), merge }));
+    const excludePath = git(root, ["rev-parse", "--git-path", "info/exclude"]);
+    if (!excludePath)
+        throw new AppError("snapshot_index_invalid", "Could not locate Git local excludes", 1);
+    const excludeFile = path.resolve(root, excludePath);
+    let exclude = null;
+    if (fs.existsSync(excludeFile)) {
+        const stat = fs.lstatSync(excludeFile);
+        if (!stat.isFile() || stat.size > 1024 * 1024)
+            throw new AppError("snapshot_index_invalid", "Git local excludes must be a bounded regular file", 1);
+        exclude = fs.readFileSync(excludeFile).toString("base64");
+    }
+    // Local excludes affect review-visible inputs, but are not part of a Git
+    // bundle/index. Keep them in the existing hashed, non-executable Git payload.
+    return Buffer.from(JSON.stringify({ entries: entries.toString("base64"), merge, exclude }));
 }
 function snapshotIndex(root, output, name) {
     const bytes = indexEntries(root);
@@ -911,6 +942,8 @@ function restoreIndex(snapshot, name, metadata, root) {
         if (!metadata.index_objects_sha256 || fileHash(pack) !== metadata.index_objects_sha256)
             throw new AppError("snapshot_checksum_mismatch", "Snapshot Git index object checksum does not match", 1);
         const value = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (value.exclude !== undefined && value.exclude !== null && (typeof value.exclude !== "string" || Buffer.byteLength(value.exclude) > 1400000))
+            throw new AppError("snapshot_index_invalid", "Snapshot Git local excludes are invalid", 1);
         gitBytes(root, ["unpack-objects"], fs.readFileSync(pack));
         runGit(root, ["read-tree", "--empty"]);
         gitBytes(root, ["update-index", "-z", "--index-info"], Buffer.from(value.entries, "base64"));
@@ -923,18 +956,36 @@ function restoreIndex(snapshot, name, metadata, root) {
             else
                 fs.rmSync(path.resolve(root, target), { force: true });
         }
+        if (value.exclude !== undefined) {
+            const target = git(root, ["rev-parse", "--git-path", "info/exclude"]);
+            if (!target)
+                throw new AppError("snapshot_index_invalid", "Could not locate restored Git local excludes", 1);
+            const destination = path.resolve(root, target);
+            if (fs.existsSync(destination) && !fs.lstatSync(destination).isFile())
+                throw new AppError("snapshot_index_invalid", "Restored Git local excludes are not a regular file", 1);
+            if (value.exclude === null)
+                fs.rmSync(destination, { force: true });
+            else {
+                fs.mkdirSync(path.dirname(destination), { recursive: true });
+                fs.writeFileSync(destination, Buffer.from(value.exclude, "base64"));
+            }
+        }
         return;
     }
     if (fs.statSync(file).size)
         runGit(root, ["apply", "--cached", "--binary", file]);
 }
+function capturedIndexEntries(snapshot, name, root) {
+    const captured = JSON.parse(fs.readFileSync(path.join(snapshot, `${name}.index.patch`), "utf8"));
+    return indexEntries(root, Object.hasOwn(captured, "exclude"));
+}
 export function verifyRecoverySnapshot(snapshot, input, checkWorkingState = true) {
     const manifest = readManifest(snapshot);
     if (manifest.purpose !== "recovery" || manifest.recovery_id !== input.recoveryId || manifest.run_id !== input.runId)
         throw new AppError("recovery_capture_invalid", "Snapshot does not identify this recovery", 1);
     const entries = [
         { name: "project", root: input.projectRoot, hash: manifest.project_sha256, git: manifest.project_git, head: manifest.project_git.head },
-        ...(manifest.workspace.kind === "git_worktree" ? [{ name: "workspace", root: input.workspaceRoot, hash: manifest.workspace.sha256, git: manifest.workspace, head: manifest.workspace.base_ref }] : [])
+        ...(manifest.workspace.kind !== "project" ? [{ name: "workspace", root: input.workspaceRoot, hash: manifest.workspace.sha256, git: manifest.workspace, head: manifest.workspace.base_ref }] : [])
     ];
     verifySnapshotPayload(snapshot, manifest);
     for (const entry of entries) {
@@ -944,7 +995,7 @@ export function verifyRecoverySnapshot(snapshot, input, checkWorkingState = true
             throw new AppError("recovery_workspace_drift", "Executable file modes changed after recovery capture", 1, { payload: entry.name });
         if (checkWorkingState && (treeHash(entry.root, allowed) !== entry.hash || git(entry.root, ["rev-parse", "--verify", "HEAD"]) !== entry.head
             || entry.head === null && git(entry.root, ["for-each-ref", "--format=%(refname)"]) !== ""
-            || git(entry.root, ["symbolic-ref", "--quiet", "--short", "HEAD"]) !== entry.git.branch || (entry.git.index_sha256 && crypto.createHash("sha256").update(entry.git.index_format === "entries@1" ? indexEntries(entry.root) : indexPatch(entry.root)).digest("hex") !== entry.git.index_sha256)))
+            || git(entry.root, ["symbolic-ref", "--quiet", "--short", "HEAD"]) !== entry.git.branch || (entry.git.index_sha256 && crypto.createHash("sha256").update(entry.git.index_format === "entries@1" ? capturedIndexEntries(snapshot, entry.name, entry.root) : indexPatch(entry.root)).digest("hex") !== entry.git.index_sha256)))
             throw new AppError("recovery_workspace_drift", "Working files or Git state changed after recovery capture", 1, { payload: entry.name });
     }
 }
@@ -964,7 +1015,7 @@ function verifySnapshotPayload(snapshot, manifest) {
     if (treeHash(path.join(snapshot, "runtime")) !== manifest.runtime_sha256)
         throw new AppError("snapshot_checksum_mismatch", "Snapshot runtime checksum does not match", 1);
     verifySnapshotModes(snapshot, manifest);
-    const payloads = [{ name: "project", hash: manifest.project_sha256, git: manifest.project_git }, ...(manifest.workspace.kind === "git_worktree" ? [{ name: "workspace", hash: manifest.workspace.sha256, git: manifest.workspace }] : [])];
+    const payloads = [{ name: "project", hash: manifest.project_sha256, git: manifest.project_git }, ...(manifest.workspace.kind !== "project" ? [{ name: "workspace", hash: manifest.workspace.sha256, git: manifest.workspace }] : [])];
     for (const payload of payloads)
         verifyGitSnapshotPayload(snapshot, payload);
     if (manifest.schema_id === "dd-flow/eval-run-snapshot@6") {
@@ -1433,7 +1484,7 @@ function treeModesHash(root, filtered = false) {
 function verifySnapshotModes(snapshot, manifest) {
     if (!manifest.payload_modes)
         return; // Legacy snapshots did not attest modes.
-    for (const name of ["project", "runtime", ...(manifest.workspace.kind === "git_worktree" ? ["workspace"] : [])]) {
+    for (const name of ["project", "runtime", ...(manifest.workspace.kind !== "project" ? ["workspace"] : [])]) {
         if (treeModesHash(path.join(snapshot, name)) !== manifest.payload_modes[name])
             throw new AppError("snapshot_checksum_mismatch", "Snapshot executable modes do not match manifest", 1, { payload: name });
     }
@@ -1465,7 +1516,7 @@ function readManifest(snapshot) {
     if (!fs.existsSync(file))
         throw new AppError("snapshot_missing", "Snapshot manifest is missing", 1, { snapshot });
     const value = JSON.parse(fs.readFileSync(file, "utf8"));
-    if (!["dd-flow/eval-run-snapshot@5", "dd-flow/eval-run-snapshot@6"].includes(String(value.schema_id)) || !value.run_id || !value.project_root || !value.dd_flow_home || typeof value.purpose !== "string" || !["stage_entry", "candidate", "incomplete", "recovery"].includes(value.purpose) || (value.purpose === "stage_entry" && !value.stage_entry) || (value.purpose !== "stage_entry" && value.stage_entry !== null) || !value.runtime_sha256 || !value.project_sha256 || !value.project_git || !value.workspace)
+    if (!["dd-flow/eval-run-snapshot@5", "dd-flow/eval-run-snapshot@6", "dd-flow/eval-run-snapshot@7"].includes(String(value.schema_id)) || !value.run_id || !value.project_root || !value.dd_flow_home || typeof value.purpose !== "string" || !["stage_entry", "candidate", "incomplete", "recovery"].includes(value.purpose) || (value.purpose === "stage_entry" && !value.stage_entry) || (value.purpose !== "stage_entry" && value.stage_entry !== null) || !value.runtime_sha256 || !value.project_sha256 || !value.project_git || !value.workspace)
         throw new AppError("snapshot_invalid", "Snapshot manifest is invalid", 1, { snapshot });
     if (value.runtime_payload_policy !== undefined && (value.runtime_payload_policy !== "flow-evidence@1" || value.purpose === "recovery"))
         throw new AppError("snapshot_invalid", "Snapshot runtime payload policy is invalid for its purpose", 1, { snapshot });
@@ -1480,8 +1531,13 @@ function readManifest(snapshot) {
             || spawnSync("git", ["check-ref-format", "--branch", value.project_git.branch], { encoding: "utf8" }).status !== 0
         : value.project_git.state !== undefined || !value.project_git.head || !value.project_git.bundle_sha256))
         throw new AppError("snapshot_invalid", "Snapshot project Git metadata is incomplete", 1, { snapshot });
-    if (value.workspace.kind === "git_worktree" && (!value.workspace.branch || !value.workspace.base_ref || !value.workspace.bundle_sha256))
-        throw new AppError("snapshot_invalid", "Snapshot worktree manifest is incomplete", 1, { snapshot });
+    if (!['project', 'git_worktree', 'git_repository'].includes(value.workspace.kind)
+        || (value.schema_id === 'dd-flow/eval-run-snapshot@7') !== (value.workspace.kind === 'git_repository')
+        || value.workspace.kind !== 'project' && (!value.workspace.branch || (value.workspace.state === 'unborn'
+            ? value.workspace.kind !== 'git_repository' || value.workspace.base_ref !== null || value.workspace.bundle_sha256 !== null
+                || value.workspace.index_format !== 'entries@1' || !value.workspace.index_sha256 || !value.workspace.index_objects_sha256
+            : value.workspace.state !== undefined || !value.workspace.base_ref || !value.workspace.bundle_sha256)))
+        throw new AppError("snapshot_invalid", "Snapshot workspace manifest is incomplete or incompatible", 1, { snapshot });
     return value;
 }
 function readBootstrapManifest(snapshot) {
@@ -1490,7 +1546,7 @@ function readBootstrapManifest(snapshot) {
         throw new AppError("snapshot_missing", "Bootstrap snapshot manifest is missing", 1, { snapshot });
     const value = JSON.parse(fs.readFileSync(file, "utf8"));
     const validBoundary = value.schema_id === "dd-eval/bootstrap-snapshot@1" ? value.stage === "specify" && value.flow === undefined
-        : value.schema_id === "dd-eval/bootstrap-snapshot@2" && (value.flow?.id === "mb-init" || value.flow?.id === "mb-upgrade") && value.stage === "preflight"
+        : value.schema_id === "dd-eval/bootstrap-snapshot@2" && (value.flow?.id === "mb-init" || value.flow?.id === "mb-upgrade" || isDiagnosticFlow(value.flow?.id)) && value.stage === "preflight"
             && Object.keys(value.flow).sort().join() === "descriptor_sha256,id,source_sha256"
             && /^[a-f0-9]{64}$/.test(value.flow.source_sha256) && /^[a-f0-9]{64}$/.test(value.flow.descriptor_sha256);
     if (!validBoundary || !value.project_root || !value.project_sha256 || !value.project_git?.branch || !value.project_git.head || !value.project_git.bundle_sha256)

package/dist/services/execution-bundles.js

@@ -9,6 +9,7 @@ import { FrozenGenericExecution } from "./generic-execution.js";
 import { hybridDigest, validateHybridContract, validateHybridShape } from "./hybrid-contracts.js";
 import { readBoundedReleaseFile } from "./release-source.js";
 import { acquireInstallationLock } from "./installation-lock.js";
+import { projectPacketLocators } from "./stage-context.js";
 const hash = (bytes) => crypto.createHash("sha256").update(bytes).digest("hex");
 const limit = 1024 * 1024;
 function refuse(reason, issues) {
@@ -54,7 +55,8 @@ export class RetainedExecutionBundle {
     #blobs;
     #admission;
     #engine;
-    constructor(bytes, manifest, blobs, admission, descriptor, execution) {
+    #engineRelocation;
+    constructor(bytes, manifest, blobs, admission, descriptor, execution, engineRelocation) {
         frozen(manifest);
         this.manifest = manifest;
         this.sha256 = hash(bytes);
@@ -63,9 +65,10 @@ export class RetainedExecutionBundle {
         this.#admission = admission;
         this.descriptor = descriptor;
         this.execution = execution;
+        this.#engineRelocation = engineRelocation && structuredClone(engineRelocation);
         Object.freeze(this);
     }
-    static admit(input, expectedSha256, sourceBlobs, selected) {
+    static admit(input, expectedSha256, sourceBlobs, selected, engineRelocation) {
         if (input.byteLength > limit || !/^[a-f0-9]{64}$/.test(expectedSha256))
             refuse("invalid_bundle_identity");
         const bytes = Buffer.from(input);
@@ -113,12 +116,12 @@ export class RetainedExecutionBundle {
         const snapshot = { schema_id: "dd-flow/frozen-execution@1", scope: admission.executionScope,
             settings: json(blobs.get(manifest.execution_settings.path)), profiles: profiles.profiles };
         const execution = FrozenGenericExecution.restore(snapshot, hybridDigest(snapshot), descriptor, admission.executionScope, admission.receipts);
-        const admitted = new RetainedExecutionBundle(bytes, manifest, blobs, admission, descriptor, execution);
+        const admitted = new RetainedExecutionBundle(bytes, manifest, blobs, admission, descriptor, execution, engineRelocation);
         admitted.engine();
         return admitted;
     }
     /** Read only the retained inventory. Mutable canon/profile sources are never consulted. */
-    static read(root, expectedSha256, admission) {
+    static read(root, expectedSha256, admission, engineRelocation) {
         try {
             directory(root);
             const bytes = readBoundedReleaseFile(path.join(root, "manifest.json"), limit);
@@ -130,7 +133,7 @@ export class RetainedExecutionBundle {
             const manifest = value, blobs = new Map();
             for (const ref of manifest.inventory)
                 blobs.set(ref.path, readBoundedReleaseFile(fileIn(root, ref.path), limit));
-            return RetainedExecutionBundle.admit(bytes, expectedSha256, blobs, admission);
+            return RetainedExecutionBundle.admit(bytes, expectedSha256, blobs, admission, engineRelocation);
         }
         catch (error) {
             if (error instanceof AppError && ["execution_bundle_invalid", "frozen_engine_invalid"].includes(error.code))
@@ -153,8 +156,17 @@ export class RetainedExecutionBundle {
     }
     #admitEngine() {
         const binding = json(this.blob(this.manifest.engine_binding.path));
-        const engine = AdmittedFrozenEngine.admit(binding, this.manifest.engine_manifest.sha256);
-        if (!engine.manifestBytes().equals(this.blob(this.manifest.engine_manifest.path)))
+        const retainedManifest = this.blob(this.manifest.engine_manifest.path), relocation = this.#engineRelocation;
+        if (relocation) {
+            const root = JSON.parse(projectPacketLocators(JSON.stringify({ root: binding.engine.snapshot_root }), relocation.relocations)).root;
+            if (!relocation.relocations.length || root === binding.engine.snapshot_root || root !== relocation.binding.engine.snapshot_root
+                || relocation.binding.run_id !== this.manifest.run_id)
+                refuse("foreign_engine_relocation");
+        }
+        const engine = relocation
+            ? AdmittedFrozenEngine.admitRelocation(binding, retainedManifest, this.manifest.engine_manifest.sha256, relocation.binding)
+            : AdmittedFrozenEngine.admit(binding, this.manifest.engine_manifest.sha256);
+        if (!relocation && !engine.manifestBytes().equals(retainedManifest))
             refuse("engine_manifest_bytes_changed");
         const manifest = engine.manifest(), contracts = new Set(Object.values(manifest.supports_contracts).flat());
         for (const id of ["dd-flow/flow-descriptor@1", "dd-flow/execution-settings@1", "dd-flow/execution-bundle@1"]) {

package/dist/services/flow-catalog.js

@@ -1,6 +1,7 @@
 import { vnextStages } from "../domain/stage-catalog.js";
 import { sdlcHandlerIdentities, memoryInitHandlerIdentities, memoryUpgradeHandlerIdentities } from "../domain/stage-handler-identities.js";
 import { AppError } from "../shared/errors.js";
+import { diagnosticFlowStages } from "../domain/diagnostic-flows.js";
 /** Engine-owned catalog, not descriptor discovery or permission to execute a RUN. */
 export function listBundledFlows() {
     return [
@@ -14,7 +15,11 @@ export function listBundledFlows() {
                 stages: stages.map((handler, index) => ({ id: handler.stage, directory: `${String(index + 1).padStart(2, "0")}-${handler.stage}`, entry_handler: handler.entryId, finish_handler: handler.finishId })),
                 edges: stages.slice(0, -1).flatMap((handler, index) => [{ from: handler.stage, to: stages[index + 1].stage, on: "accepted" },
                     ...(handler.stage === "verify" ? [{ from: handler.stage, to: "review", on: "needs_repair" }] : [])]) };
-        })
+        }),
+        ...Object.entries(diagnosticFlowStages).map(([id, stages]) => ({ id, handler_status: "registered", entry_stage: "preflight", terminal_stages: ["report"],
+            stages: stages.map((stage, index) => ({ id: stage, directory: `${String(index + 1).padStart(2, "0")}-${stage}`,
+                entry_handler: "diagnostic-stage-entry", finish_handler: "diagnostic-stage-finish" })),
+            edges: stages.slice(0, -1).map((from, index) => ({ from, to: stages[index + 1], on: "accepted" })) }))
     ];
 }
 export function showBundledFlow(id) {