@deksden-com/dd-flow-cli 0.9.0-beta.136 → 0.9.0-beta.138

package/dist/services/runs.js

@@ -4,9 +4,10 @@ import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { withProjectionLock } from "../storage/projection-lock.js";
 import { reconcileRunStageReports } from "./stage-report-renderer.js";
-import { formatFullId, isFullEntityId, isShortEntityId, parseFullEntityId } from "../domain/entity-ids.js";
+import { isFullEntityId, isShortEntityId, parseFullEntityId } from "../domain/entity-ids.js";
 import { checksumForFlowFlagValues, isFlowFlagDowngrade, loadCanonicalFlowContract, loadProjectFlowContract, resolveFlowFlags } from "../domain/flow-contract.js";
 import { AppError } from "../shared/errors.js";
+import { nextRunId } from "./ids.js";
 import { ensureDir, canonicalPath, projectRunHome, projectRunJsonPath, resolveProjectRoot } from "../storage/paths.js";
 import { appendAudit } from "./audit.js";
 import { registerProject, requireProjectByRoot } from "./projects.js";
@@ -22,9 +23,11 @@ import { assertSameSessionMerge, loadExecutionRoutingInput, resolveStageTransiti
 import { isLegalVnextTransition, vnextStageDirectory, vnextStages } from "../domain/stage-catalog.js";
 import { publicSessionIdentity } from "./session-identity.js";
 import { flowCommand } from "./stage-pause.js";
+import { RetainedExecutionBundle } from "./execution-bundles.js";
+import { admitBundledFlow, bundledHandlerContext } from "./stage-handlers.js";
+import { hybridDigest } from "./hybrid-contracts.js";
 const runSchemaId = "dd-flow/flow-run@3";
 const runtimeSchemaId = "dd-flow/flow-run@3";
-const runIdType = "RUN";
 const allowedRunFlowKinds = [
     "mb_sdlc",
     "coding",
@@ -231,7 +234,7 @@ function snapshotVnextExecutionProfile(projectRoot, ddFlowHome, routingInput, no
             merge_delivery: profile.merge_delivery,
             merge_cleanup: profile.merge_cleanup,
             stop_target: profile.stop_target,
-            code_bootstrap: profile.code_bootstrap,
+            ...(profile.code_bootstrap ? { code_bootstrap: profile.code_bootstrap } : {}),
             ...(profile.execution ? { execution: profile.execution } : {})
         }
     }, routingInput);
@@ -306,17 +309,19 @@ function loadUpgradeFlowContract(context, projectRoot) {
     }
     return loadCanonicalFlowContract(canon.canon.flow_root);
 }
-export function getFlowRunStatus(context, input) {
+export function getFlowRunStatus(context, input, preparedBundle) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
+    if (preparedBundle)
+        assertPreparedRunBundleSqlAuthority(context, { projectId: project.id, runId: run.id }, preparedBundle);
     const index = authoritativeIndex(run);
     const runtime = readRuntimeSnapshot(run.runtime_path);
-    return { ok: true, run: flowRunSummary(run), index, continuation: runContinuation(context, run, index), ...(runtime ? { runtime } : {}), flow_guidance: guidanceForRun(context, run, index) };
+    return { ok: true, run: flowRunSummary(run), index, continuation: runContinuation(context, run, index, preparedBundle), ...(runtime ? { runtime } : {}), flow_guidance: guidanceForRun(context, run, index) };
 }
 /** A read-only projection of the next legal lifecycle action.
  * It is derived from the persisted RUN/Work facts so controllers never infer a
  * transition from a model's prose or a hard-coded stage array. */
-function runContinuation(context, run, index) {
+function runContinuation(context, run, index, preparedBundle) {
     if (["done", "failed", "cancelled"].includes(run.status))
         return { kind: "terminal", stage: null, attempt: null, work_id: null, reason: run.status, command: null };
     const control = runControlDirective(context, run.project_id, run.id);
@@ -332,6 +337,15 @@ function runContinuation(context, run, index) {
         return { kind: "paused", stage: index.current_stage ?? null, attempt: null, work_id: null, reason: run.status, command: null };
     if (run.status === "blocked")
         return { kind: "blocked", stage: index.current_stage ?? null, attempt: null, work_id: null, reason: run.status, command: null };
+    if (index.execution_bundle) {
+        const bundle = preparedBundle ?? readFlowRunExecutionBundle(context, { projectRoot: run.project_root, runId: run.id });
+        const next = bundledNextStage(bundle.descriptor, index);
+        if (!next)
+            return { kind: "terminal", stage: null, attempt: null, work_id: null, reason: "flow_complete", command: null };
+        const command = bundle.engine().command(context.ddFlowHome, ["stage", "start", run.id, "--stage", next, "--project-root", run.project_root, "--json"]);
+        return { kind: "start_stage", stage: next, attempt: null, work_id: null, reason: "legal_successor", command,
+            execution: { status: "resolved", ...bundle.execution.stage(next) } };
+    }
     if (run.flow_kind === "vnext_specify" || run.flow_kind === "vnext_protocolize") {
         const completed = index.stage_runs.filter((stage) => stage.status === "done" || stage.status === "skipped").sort((left, right) => right.order - left.order)[0];
         const next = completed ? vnextStages.find((stage) => stage.id === completed.stage)?.next.find((candidate) => candidate !== "plan-review" || index.settings?.plan_review?.mode !== "off") : "specify";
@@ -587,14 +601,18 @@ export function prepareFlowRunStageAttachment(context, input, archive = false) {
     const index = authoritativeIndex(run);
     const status = parseStageStatus(input.status);
     const existing = index.stage_runs.find((item) => item.stage === stage);
-    assertVnextStageStart(run, index, stage, status, existing);
+    const bundle = index.execution_bundle ? readFlowRunExecutionBundle(context, { projectRoot: run.project_root, runId: run.id }) : null;
+    if (bundle)
+        assertBundledStageStart(bundle.descriptor, index, stage, dir, status, existing);
+    else
+        assertVnextStageStart(run, index, stage, status, existing);
     if (archive) {
         const runRoot = runArtifactRoot(run);
         if (fs.existsSync(path.join(runRoot, `.archive-${dir}.json`)) || status === "running" && existing) {
             archiveExistingStageAttempt(context, project.id, run.id, runRoot, dir);
         }
     }
-    return { project, run, index, stage, dir, status, existing, generation, attempt: status === "running" ? nextAttempt(existing) : existing?.attempt ?? "try-001", git: status === "running" ? gitFacts(run.workspace_root) : undefined };
+    return { project, run, index, stage, dir, status, existing, generation, bundle, attempt: status === "running" ? nextAttempt(existing) : existing?.attempt ?? "try-001", git: status === "running" ? gitFacts(run.workspace_root) : undefined };
 }
 export function attachFlowRunStage(context, input, prepared = prepareFlowRunStageAttachment(context, input, true)) {
     // Filesystem archive and Git inspection are preparation, never writer work.
@@ -607,7 +625,13 @@ export function attachFlowRunStage(context, input, prepared = prepareFlowRunStag
         if ((index.runtime_revision ?? 0) !== (prepared.index.runtime_revision ?? 0) || existing?.attempt !== prepared.existing?.attempt) {
             throw new AppError("stage_revision_changed", "Stage changed during start preparation", 1, { run_id: run.id, stage });
         }
-        assertVnextStageStart(latest, index, stage, status, existing);
+        if (prepared.bundle) {
+            if (index.execution_bundle?.manifest_sha256 !== prepared.bundle.sha256)
+                throw new AppError("run_bundle_anchor_invalid", "RUN bundle changed during stage preparation", 1);
+            assertBundledStageStart(prepared.bundle.descriptor, index, stage, dir, status, existing);
+        }
+        else
+            assertVnextStageStart(latest, index, stage, status, existing);
         const now = context.now();
         const stageRun = {
             ...(existing ?? { order: index.stage_runs.length + 1 }),
@@ -652,7 +676,7 @@ export function attachFlowRunStage(context, input, prepared = prepareFlowRunStag
 export function withStageSettlement(context, operation) {
     return context.db.writeTransaction(operation, "stage.settle");
 }
-export function prepareFlowRunStageCompletion(context, input) {
+export function prepareFlowRunStageCompletion(context, input, admittedBundle) {
     for (const [name, value] of Object.entries({ stageReport: input.stageReport, data: input.data, dataSchemaId: input.dataSchemaId, report: input.report })) {
         if (value !== undefined)
             requiredPlain(value, name);
@@ -676,11 +700,37 @@ export function prepareFlowRunStageCompletion(context, input) {
     if (!existing) {
         throw new AppError("not_found", `Run stage is not attached: ${stage}`, 1, { run_id: run.id, stage });
     }
+    // Bound completion must admit the same immutable descriptor/engine authority
+    // as stage entry. Keep filesystem admission outside the SQLite writer.
+    const bundle = admittedBundle === undefined
+        ? readFlowRunExecutionBundle(context, { projectRoot: run.project_root, runId: run.id }) : admittedBundle;
+    if (bundle && !index.execution_bundle)
+        throw new AppError("run_bundle_anchor_invalid", "RUN bundle anchor disappeared after finish admission", 1);
+    if (bundle)
+        assertCompletionBundleAuthority(context, run, index);
+    if (index.execution_bundle && (!bundle || bundle.sha256 !== index.execution_bundle.manifest_sha256
+        || bundle.manifest.descriptor.sha256 !== index.execution_bundle.descriptor_sha256
+        || hybridDigest(bundleAuthority(bundle.admission())) !== index.execution_bundle.admission_sha256)) {
+        throw new AppError("run_bundle_anchor_invalid", "Prepared finish bundle does not match authoritative RUN admission", 1);
+    }
+    if (bundle) {
+        const declared = bundle.descriptor.stage(stage);
+        if (declared.directory !== existing.dir || index.current_stage !== stage) {
+            throw new AppError("flow_stage_completion_invalid", "Completion does not belong to the active descriptor stage", 2, { phase: "prepare", effect: "no_effect", run_id: run.id, stage });
+        }
+    }
     const dataPath = input.data ? path.join(runArtifactRoot(run), existing.dir, input.data) : null;
     const dataSha256 = input.dataSha256 ?? (dataPath && fs.existsSync(dataPath) ? crypto.createHash("sha256").update(fs.readFileSync(dataPath)).digest("hex") : null);
     if (dataSha256 && !/^[a-f0-9]{64}$/.test(dataSha256))
         throw new AppError("validation", "Stage data SHA-256 is invalid", 2);
-    return { project, run, index, stage, status, existing, dataSha256, git: input.git ?? gitFacts(run.workspace_root), generation: ["done", "failed", "skipped"].includes(status) ? assertStageSettlementAllowed(context, project.id, run.id, stage) : assertRunMutationAllowed(context, project.id, run.id) };
+    return { project, run, index, stage, status, existing, bundle, dataSha256, git: input.git ?? gitFacts(run.workspace_root), generation: ["done", "failed", "skipped"].includes(status) ? assertStageSettlementAllowed(context, project.id, run.id, stage) : assertRunMutationAllowed(context, project.id, run.id) };
+}
+/** Raw historical control is not a finish-sealing bypass for a descriptor-bound RUN. */
+export function prepareRawFlowRunStageCompletion(context, input) {
+    const prepared = prepareFlowRunStageCompletion(context, input);
+    if (prepared.bundle)
+        throw new AppError("stage_finish_required", "Descriptor-bound stages must settle through their registered stage finish handler", 2, { phase: "prepare", effect: "no_effect", run_id: prepared.run.id, stage: prepared.stage });
+    return prepared;
 }
 function stageUsageProjection(context, run, stage, startedAt) {
     if (!startedAt)
@@ -705,6 +755,14 @@ export function completeFlowRunStage(context, input, prepared = prepareFlowRunSt
         if (!existing || existing.attempt !== prepared.existing.attempt || index.runtime_revision !== prepared.index.runtime_revision) {
             throw new AppError("stage_revision_changed", "Stage attempt changed during finish preparation", 1, { run_id: run.id, stage, expected_attempt: prepared.existing.attempt, actual_attempt: existing?.attempt ?? null });
         }
+        if (hybridDigest(index.execution_bundle ?? null) !== hybridDigest(prepared.index.execution_bundle ?? null)) {
+            throw new AppError("run_bundle_anchor_invalid", "RUN bundle authority changed during finish preparation", 1);
+        }
+        if (prepared.bundle && (index.current_stage !== stage || existing.dir !== prepared.bundle.descriptor.stage(stage).directory)) {
+            throw new AppError("flow_stage_completion_invalid", "Active descriptor stage changed during finish preparation", 1);
+        }
+        if (prepared.bundle)
+            assertCompletionBundleAuthority(context, latest, index);
         const now = context.now();
         const stageRun = {
             ...existing,
@@ -755,6 +813,42 @@ export function completeFlowRunStage(context, input, prepared = prepareFlowRunSt
     const updatedRun = requireRunById(context, project.id, run.id);
     return { ok: true, run: flowRunSummary(updatedRun), stage_run: completed.stageRun, index: completed.index, flow_guidance: guidanceForRun(context, updatedRun, completed.index) };
 }
+/** Writer-safe readback of independently retained SQL authority; no filesystem admission. */
+function assertCompletionBundleAuthority(context, run, index) {
+    const anchor = index.execution_bundle;
+    if (!anchor)
+        throw new AppError("run_bundle_anchor_invalid", "RUN bundle anchor disappeared during finish", 1);
+    assertRunBundleSqlAuthority(context, { projectId: run.project_id, runId: run.id }, anchor);
+}
+/** Metadata-only fencing shared by lifecycle ownership and the settlement writer.
+ * False means genuine historical authority, never a lost/orphaned bundle anchor.
+ * Physical descriptor/engine admission remains an independent outside-writer check.
+ */
+export function assertRunBundleSqlAuthority(context, scope, anchor) {
+    const hasAuthority = context.db.get("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = 'run_bundle_authorities'");
+    const row = hasAuthority ? context.db.get("SELECT manifest_sha256, admission_json FROM run_bundle_authorities WHERE project_id = ? AND run_id = ?", [scope.projectId, scope.runId]) : undefined;
+    if (!anchor) {
+        if (row)
+            throw new AppError("run_bundle_anchor_invalid", "Retained RUN authority exists without its execution anchor", 1);
+        return false;
+    }
+    if (anchor.schema_id !== "dd-flow/run-execution-bundle@1" || typeof anchor.flow_id !== "string"
+        || [anchor.manifest_sha256, anchor.descriptor_sha256, anchor.admission_sha256].some(hash => typeof hash !== "string" || !/^[a-f0-9]{64}$/.test(hash)))
+        throw new AppError("run_bundle_anchor_invalid", "RUN bundle anchor is invalid", 1);
+    if (!row || row.manifest_sha256 !== anchor.manifest_sha256)
+        throw new AppError("run_bundle_authority_missing", "RUN bundle admission authority disappeared during finish", 1);
+    let valid = false;
+    try {
+        if (Buffer.byteLength(row.admission_json, "utf8") <= 1024 * 1024) {
+            const retained = JSON.parse(row.admission_json);
+            valid = retained.runId === scope.runId && hybridDigest(retained) === anchor.admission_sha256;
+        }
+    }
+    catch { /* Corrupt authority cannot be replaced by a prepared object. */ }
+    if (!valid)
+        throw new AppError("run_bundle_authority_invalid", "RUN bundle admission authority changed during finish", 1);
+    return true;
+}
 /** Pause one live stage without completing it or creating a new attempt. */
 export function pauseFlowRunStage(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
@@ -1016,6 +1110,41 @@ export function completeFlowRun(context, input) {
     const updatedRun = requireRunById(context, project.id, run.id);
     return { ok: true, run: flowRunSummary(updatedRun), index, usage, flow_guidance: guidanceForRun(context, updatedRun, index) };
 }
+/** SQL-only terminal writer for an independently prepared descriptor handler.
+ * This closes runtime state, not semantic or Git acceptance. The caller owns
+ * the outer transaction, root settlement and the handler-specific proof fence.
+ */
+export function completeDescriptorRunState(context, scope, bundle, git) {
+    assertPreparedRunBundleSqlAuthority(context, scope, bundle);
+    assertRunMutationAllowed(context, scope.projectId, scope.runId);
+    const run = requireRunById(context, scope.projectId, scope.runId);
+    const index = authoritativeIndex(run);
+    const terminal = index.stage_runs.at(-1);
+    if (run.status !== "running" || !terminal || terminal.status !== "done"
+        || !bundle.descriptor.descriptor.terminal_stages.includes(terminal.stage)
+        || index.stage_runs.some(stage => ["running", "paused", "waiting_for_user", "blocked", "pending"].includes(stage.status))
+        || context.db.get("SELECT 1 FROM works WHERE project_id=? AND run_id=? AND status IN ('created','running','paused') LIMIT 1", [scope.projectId, scope.runId])
+        || context.db.get("SELECT 1 FROM work_sessions ws JOIN works w ON w.work_id=ws.work_id WHERE w.project_id=? AND w.run_id=? AND ws.status='running' LIMIT 1", [scope.projectId, scope.runId])) {
+        throw new AppError("descriptor_run_settlement_invalid", "Descriptor RUN is not ready for terminal runtime settlement", 1, { effect: "no_effect" });
+    }
+    const project = context.db.get("SELECT * FROM projects WHERE id=?", [scope.projectId]);
+    if (!project)
+        throw new AppError("not_found", "Project is not registered", 1);
+    const now = context.now();
+    index.status = "done";
+    index.verdict = "accepted";
+    index.next_action = null;
+    index.updated_at = now;
+    index.completed_at = now;
+    index.finished_at = now;
+    index.duration_ms = durationMs(index.started_at ?? run.created_at, now);
+    index.execution = { project_root: run.project_root, workspace_root: run.workspace_root, git: { ...git } };
+    persistRunState(context, project, run, index);
+    closeRunOrchestrators(context, scope.projectId, run, "done", now);
+    refreshRunSessionProjection(context, scope.projectId, scope.runId);
+    appendAudit(context, { projectId: scope.projectId, eventType: "flow_run.completed", payload: { run_id: scope.runId, status: "done", verdict: "accepted", next_action: null } });
+    appendRunTimeline(context, scope.projectId, scope.runId, { at: now, type: "run_completed", run_id: scope.runId, status: "done" });
+}
 /** Update a live RUN between stages without manufacturing terminal evidence. */
 export function advanceFlowRun(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
@@ -1524,12 +1653,172 @@ function authoritativeIndex(run) {
         const state = JSON.parse(run.index_json);
         if (!state || typeof state !== "object" || Array.isArray(state) || !Array.isArray(state.stage_runs))
             throw new Error("RUN index must contain stage_runs");
-        return { ...state, schema_id: runSchemaId };
+        const derivedStage = ["vnext_specify", "vnext_protocolize"].includes(run.flow_kind)
+            ? [...state.stage_runs].sort((left, right) => right.order - left.order)[0]?.stage : undefined;
+        return { ...state, schema_id: runSchemaId, ...(state.current_stage === undefined && derivedStage ? { current_stage: derivedStage } : {}) };
     }
     catch (error) {
         throw new AppError("runtime_state_invalid", "RUN mechanical state in SQLite is missing or invalid", 1, { run_id: run.id, cause: String(error) });
     }
 }
+function assertBundleRunIdentity(run, bundle) {
+    const scope = bundle.execution.snapshot().scope;
+    const flowId = bundle.descriptor.descriptor.id;
+    const matchesFlow = flowId === "sdlc" ? ["vnext_specify", "vnext_protocolize"].includes(run.flow_kind) : flowId === run.flow_kind;
+    if (bundle.manifest.run_id !== run.id || scope.projectRoot !== run.project_root || scope.workspace !== run.workspace_root || !matchesFlow) {
+        throw new AppError("run_bundle_identity_invalid", "Execution bundle belongs to another RUN or workspace", 1, { phase: "prepare", effect: "no_effect", run_id: run.id });
+    }
+    const blobs = new Map(bundle.manifest.inventory.map(ref => [ref.path, bundle.blob(ref.path)]));
+    // File-owned handler inventories can never authorize executable code.
+    admitBundledFlow(bundle.blob(bundle.manifest.descriptor.path), bundle.manifest.descriptor.sha256, blobs);
+}
+function bundleAuthority(admission) {
+    const authority = { runId: admission.runId, executionScope: structuredClone(admission.executionScope),
+        receipts: structuredClone([...(admission.receipts ?? [])].sort(([left], [right]) => left.localeCompare(right, "en"))) };
+    for (const key of ["descriptorSha256", "engineChecksum", "engineBindingSha256", "engineManifestSha256", "bundleProjectRoot", "bundleProvenance", "bootstrapIdentity"]) {
+        if (admission[key] !== undefined)
+            Object.assign(authority, { [key]: structuredClone(admission[key]) });
+    }
+    return authority;
+}
+/** Copies the same SQL authority representation used by legacy bundle binding. */
+export function runBundleAuthorityMetadata(bundle) {
+    if (!(bundle instanceof RetainedExecutionBundle))
+        throw new AppError("run_bundle_anchor_invalid", "Bundle must be admitted before RUN allocation", 1);
+    const admissionJson = JSON.stringify(bundleAuthority(bundle.admission())), admissionSha256 = hybridDigest(JSON.parse(admissionJson));
+    if (Buffer.byteLength(admissionJson) > 1024 * 1024)
+        throw new AppError("run_bundle_authority_invalid", "RUN admission exceeds its bound", 1);
+    return { admissionJson, anchor: { schema_id: "dd-flow/run-execution-bundle@1",
+            manifest_sha256: bundle.sha256, descriptor_sha256: bundle.manifest.descriptor.sha256,
+            admission_sha256: admissionSha256, flow_id: bundle.manifest.flow_id } };
+}
+/** Recheck SQL authority and compiled descriptor admission. Schema loading
+ * belongs outside SQL writers; use the explicit SQL-only fence inside them.
+ */
+export function assertPreparedRunBundleAuthority(context, scope, bundle) {
+    const run = assertPreparedRunBundleSqlAuthority(context, scope, bundle);
+    assertBundleRunIdentity(run, bundle);
+}
+/** SQL-only fence after the caller has admitted compiled handlers outside the
+ * writer. Descriptor schema loading is deliberately excluded from this fence.
+ */
+export function assertPreparedRunBundleSqlAuthority(context, scope, bundle) {
+    if (!(bundle instanceof RetainedExecutionBundle))
+        throw new AppError("run_bundle_anchor_invalid", "Prepared bundle is not admitted", 1);
+    const run = context.db.get("SELECT * FROM runs WHERE project_id = ? AND id = ?", [scope.projectId, scope.runId]);
+    if (!run)
+        throw new AppError("not_found", "Prepared bundle RUN is unavailable", 1);
+    const index = authoritativeIndex(run), anchor = index.execution_bundle;
+    if (!assertRunBundleSqlAuthority(context, scope, anchor) || !anchor || anchor.manifest_sha256 !== bundle.sha256
+        || anchor.descriptor_sha256 !== bundle.manifest.descriptor.sha256 || anchor.flow_id !== bundle.manifest.flow_id
+        || anchor.admission_sha256 !== hybridDigest(bundleAuthority(bundle.admission())))
+        throw new AppError("run_bundle_anchor_invalid", "Prepared bundle differs from authoritative RUN", 1);
+    const execution = bundle.execution.snapshot().scope;
+    const flow = bundle.descriptor.descriptor.id;
+    if (bundle.manifest.run_id !== run.id || execution.projectRoot !== run.project_root || execution.workspace !== run.workspace_root
+        || !(flow === "sdlc" ? ["vnext_specify", "vnext_protocolize"].includes(run.flow_kind) : flow === run.flow_kind)) {
+        throw new AppError("run_bundle_identity_invalid", "Execution bundle belongs to another RUN or workspace", 1, { effect: "no_effect", run_id: run.id });
+    }
+    return run;
+}
+export function readFlowRunExecutionBundle(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = resolveRun(context, project.id, input.runId), anchor = authoritativeIndex(run).execution_bundle;
+    if (!anchor) {
+        // Genuine historical RUNs have neither authority nor anchor. Lost new-RUN
+        // metadata must not silently switch their execution to the legacy engine path.
+        const hasAuthority = context.db.get("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = 'run_bundle_authorities'");
+        if (hasAuthority && context.db.get("SELECT 1 FROM run_bundle_authorities WHERE project_id = ? AND run_id = ?", [project.id, run.id])) {
+            throw new AppError("run_bundle_anchor_invalid", "Retained RUN authority exists without its execution anchor", 1);
+        }
+        return null;
+    }
+    if (anchor.schema_id !== "dd-flow/run-execution-bundle@1" || !/^[a-f0-9]{64}$/.test(anchor.manifest_sha256)
+        || !/^[a-f0-9]{64}$/.test(anchor.descriptor_sha256) || !/^[a-f0-9]{64}$/.test(anchor.admission_sha256))
+        throw new AppError("run_bundle_anchor_invalid", "RUN bundle anchor is invalid", 1);
+    const hasAuthority = context.db.get("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = 'run_bundle_authorities'");
+    const row = hasAuthority ? context.db.get("SELECT admission_json, manifest_sha256 FROM run_bundle_authorities WHERE project_id = ? AND run_id = ?", [project.id, run.id]) : undefined;
+    if (!row || row.manifest_sha256 !== anchor.manifest_sha256)
+        throw new AppError("run_bundle_authority_missing", "RUN bundle admission authority is unavailable", 1);
+    if (Buffer.byteLength(row.admission_json) > 1024 * 1024)
+        throw new AppError("run_bundle_authority_invalid", "RUN bundle admission authority exceeds its bound", 1);
+    let retained;
+    try {
+        retained = JSON.parse(row.admission_json);
+    }
+    catch {
+        throw new AppError("run_bundle_authority_invalid", "RUN bundle admission authority is invalid", 1);
+    }
+    if (hybridDigest(retained) !== anchor.admission_sha256 || !Array.isArray(retained.receipts)
+        || input.admission && hybridDigest(bundleAuthority(input.admission)) !== anchor.admission_sha256) {
+        throw new AppError("run_bundle_authority_invalid", "RUN bundle admission authority changed", 1);
+    }
+    const admission = { ...retained, receipts: new Map(retained.receipts), descriptorContext: bundledHandlerContext(new Map()) };
+    const bundle = RetainedExecutionBundle.read(path.join(runArtifactRoot(run), "execution-bundle"), anchor.manifest_sha256, admission);
+    assertBundleRunIdentity(run, bundle);
+    if (bundle.manifest.descriptor.sha256 !== anchor.descriptor_sha256 || bundle.manifest.flow_id !== anchor.flow_id) {
+        throw new AppError("run_bundle_anchor_invalid", "RUN bundle descriptor identity changed", 1);
+    }
+    return bundle;
+}
+/** Freeze once before physical owners exist. Publication precedes the fenced SQLite anchor. */
+export function bindFlowRunExecutionBundle(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = resolveRun(context, project.id, input.runId), index = authoritativeIndex(run);
+    const generation = assertRunMutationAllowed(context, project.id, run.id);
+    assertBundleRunIdentity(run, input.bundle);
+    if (input.bundle.manifest.flow_id !== "sdlc") {
+        throw new AppError("run_bundle_start_required", "Memory RUN and its bundle authority must be allocated together through the request-bound start", 1, { phase: "prepare", effect: "no_effect", run_id: run.id });
+    }
+    if (index.execution_bundle) {
+        if (index.execution_bundle.manifest_sha256 !== input.bundle.sha256)
+            throw new AppError("run_bundle_immutable", "RUN bundle cannot be replaced", 1);
+        readFlowRunExecutionBundle(context, { ...input, admission: input.bundle.admission() });
+        publishRunProjections(context, project.id, run.id);
+        return { changed: false, sha256: input.bundle.sha256 };
+    }
+    const assertUnstarted = (state) => {
+        if (state.status !== "running" || state.stage_runs.length || state.sessions.length
+            || context.db.get("SELECT 1 FROM sessions WHERE project_id = ? AND run_id = ? LIMIT 1", [project.id, run.id])
+            || context.db.get("SELECT 1 FROM works WHERE project_id = ? AND run_id = ? LIMIT 1", [project.id, run.id])) {
+            throw new AppError("run_bundle_active", "Execution bundle must be frozen before stages, Works or Sessions exist", 1);
+        }
+    };
+    assertUnstarted(index);
+    const authority = bundleAuthority(input.bundle.admission());
+    // Hash the JSON representation actually retained, not optional undefined fields.
+    const authorityJson = JSON.stringify(authority), authoritySha256 = hybridDigest(JSON.parse(authorityJson));
+    if (Buffer.byteLength(authorityJson) > 1024 * 1024)
+        throw new AppError("run_bundle_authority_invalid", "RUN bundle admission authority exceeds its bound", 1);
+    input.bundle.materialize(runArtifactRoot(run));
+    try {
+        context.db.writeTransaction(() => {
+            assertRunMutationAllowed(context, project.id, run.id, generation);
+            const latest = resolveRun(context, project.id, run.id), state = authoritativeIndex(latest);
+            assertUnstarted(state);
+            if (state.runtime_revision !== index.runtime_revision || state.execution_bundle || latest.workspace_root !== run.workspace_root
+                || latest.project_root !== run.project_root || latest.flow_kind !== run.flow_kind || latest.run_root !== run.run_root) {
+                throw new AppError("run_revision_changed", "RUN changed during bundle publication", 1);
+            }
+            state.execution_bundle = { schema_id: "dd-flow/run-execution-bundle@1", manifest_sha256: input.bundle.sha256,
+                descriptor_sha256: input.bundle.manifest.descriptor.sha256, admission_sha256: authoritySha256, flow_id: input.bundle.manifest.flow_id };
+            context.db.execSchema(`CREATE TABLE IF NOT EXISTS run_bundle_authorities (
+        project_id TEXT NOT NULL, run_id TEXT NOT NULL, manifest_sha256 TEXT NOT NULL, admission_json TEXT NOT NULL,
+        PRIMARY KEY(project_id, run_id), FOREIGN KEY(project_id, run_id) REFERENCES runs(project_id, id)
+      )`);
+            context.db.run("INSERT INTO run_bundle_authorities (project_id, run_id, manifest_sha256, admission_json) VALUES (?, ?, ?, ?)", [project.id, run.id, input.bundle.sha256, authorityJson]);
+            state.updated_at = context.now();
+            persistRunState(context, project, latest, state);
+        }, "runs.bindExecutionBundle");
+    }
+    catch (error) {
+        throw new AppError("run_bundle_binding_incomplete", "Bundle retained but RUN binding requires recovery", 1, {
+            phase: "publication", effect: "partial", run_id: run.id, sha256: input.bundle.sha256,
+            reason: error instanceof AppError ? error.code : "binding_io_failure",
+        });
+    }
+    return { changed: true, sha256: input.bundle.sha256 };
+}
 function sanitizeTimelineValue(value, key) {
     if (key && /(secret|password|authorization|cookie|api[_-]?key|private[_-]?key|access[_-]?token|refresh[_-]?token|transcript|prompt|tool[_-]?output|document[_-]?content)/i.test(key)) {
         return "[REDACTED]";
@@ -1556,6 +1845,24 @@ function nextAttempt(existing) {
     const number = Number(existing.attempt.replace("try-", ""));
     return `try-${String(Number.isFinite(number) ? number + 1 : 1).padStart(3, "0")}`;
 }
+function bundledNextStage(flow, index) {
+    const completed = index.stage_runs.filter(stage => ["done", "skipped"].includes(stage.status)).sort((left, right) => right.order - left.order)[0];
+    if (!completed)
+        return flow.descriptor.entry_stage;
+    // Optional SDLC review routing remains a flow-specific policy, not a generic stage list.
+    const outcome = flow.descriptor.id === "sdlc" && completed.stage === "plan" && index.settings?.plan_review?.mode === "off" ? "not-applicable" : "accepted";
+    return flow.successor(completed.stage, outcome);
+}
+function assertBundledStageStart(flow, index, stage, dir, status, existing) {
+    const selected = flow.stage(stage);
+    if (selected.directory !== dir)
+        throw new AppError("flow_stage_directory_invalid", "Stage directory differs from the frozen descriptor", 1, { stage });
+    if (status !== "running")
+        return;
+    if (existing || index.stage_runs.some(candidate => !["done", "skipped"].includes(candidate.status)) || bundledNextStage(flow, index) !== stage) {
+        throw new AppError("illegal_stage_transition", "Stage does not follow the frozen descriptor or an attempt already exists", 2, { run_id: index.run_id, stage });
+    }
+}
 function assertVnextStageStart(run, index, stage, status, existing) {
     if (status !== "running" || (run.flow_kind !== "vnext_specify" && run.flow_kind !== "vnext_protocolize"))
         return;
@@ -1614,19 +1921,6 @@ function requireRunById(context, projectId, runId) {
     }
     return run;
 }
-function nextRunId(context, projectId, slug) {
-    const rows = context.db.all("SELECT id FROM runs WHERE project_id = ? AND id LIKE 'RUN-%'", [projectId]);
-    const max = rows.reduce((value, row) => {
-        try {
-            const parsed = parseFullEntityId(row.id);
-            return parsed.type === runIdType ? Math.max(value, Number(parsed.shortId.slice(4))) : value;
-        }
-        catch {
-            return value;
-        }
-    }, 0);
-    return formatFullId(runIdType, max + 1, slug);
-}
 function flowRunSummary(run) {
     return {
         id: run.id,

package/dist/services/stage-context.js

@@ -136,7 +136,15 @@ export function loadExternalStageContext(input) {
     const materializedSha256 = sha256(bytes);
     if (materializedSha256 !== input.expectedSha256)
         throw new AppError("context_checksum_mismatch", "Stage context checksum does not match --context-sha256", 2, { context_file: sourcePath, expected_sha256: input.expectedSha256, actual_sha256: materializedSha256 });
-    const value = prepareJsonText(bytes.toString("utf8"), { file: sourcePath, label: "Stage context" }).value;
+    return loadExternalStageContextBytes({ bytes, sourcePath, stage: input.stage });
+}
+/** The same context contract for independently retained Stage input bytes;
+ * historical readers must not reopen the original mutable source file. */
+export function loadExternalStageContextBytes(input) {
+    if (!(input.bytes instanceof Uint8Array) || !input.bytes.length || input.bytes.length > 1024 * 1024)
+        throw new AppError("validation", "Stage context exceeds its byte bound", 2);
+    const bytes = Buffer.from(input.bytes), sourcePath = input.sourcePath, materializedSha256 = sha256(bytes);
+    const value = prepareJsonText(new TextDecoder("utf-8", { fatal: true }).decode(bytes), { file: sourcePath, label: "Stage context" }).value;
     validateContext(value, input.stage);
     return { value, sourcePath, materializedSha256, bytes };
 }

package/dist/services/stage-handlers.js

@@ -0,0 +1,74 @@
+import { AppError } from "../shared/errors.js";
+import { finishVnextSpecifyStage, launchVnextSpecify } from "./vnext-specify.js";
+import { finishVnextProtocolize, startVnextProtocolize } from "./vnext-protocolize.js";
+import { finishVnextPlan, startVnextPlan } from "./vnext-plan.js";
+import { finishVnextPlanReview, startVnextPlanReview } from "./vnext-plan-review.js";
+import { finishVnextCode, startVnextCode } from "./vnext-code.js";
+import { finishVnextCodeReview, startVnextCodeReview } from "./vnext-code-review.js";
+import { finishVnextMerge, startVnextMerge } from "./vnext-merge.js";
+import { ResolvedFlowDescriptor } from "./flow-descriptors.js";
+import { vnextStages } from "../domain/stage-catalog.js";
+import { sdlcHandlerIdentities as ids } from "../domain/stage-handler-identities.js";
+import { memoryInitStageHandlers } from "./memory-stage-dispatch.js";
+/** Engine-owned code, not a plugin registration surface or executable descriptor expression. */
+export const sdlcStageHandlers = Object.freeze({
+    specify: Object.freeze({ ...ids.specify, entry: launchVnextSpecify, finish: finishVnextSpecifyStage }),
+    protocolize: Object.freeze({ ...ids.protocolize, entry: startVnextProtocolize, finish: finishVnextProtocolize }),
+    plan: Object.freeze({ ...ids.plan, entry: startVnextPlan, finish: finishVnextPlan }),
+    "plan-review": Object.freeze({ ...ids["plan-review"], entry: startVnextPlanReview, finish: finishVnextPlanReview }),
+    code: Object.freeze({ ...ids.code, entry: startVnextCode, finish: finishVnextCode }),
+    "code-review": Object.freeze({ ...ids["code-review"], entry: startVnextCodeReview, finish: finishVnextCodeReview }),
+    merge: Object.freeze({ ...ids.merge, entry: startVnextMerge, finish: finishVnextMerge })
+});
+/** A fresh inventory cannot mutate the registered handler functions. */
+export function bundledHandlerContext(blobs) {
+    return {
+        entryHandlers: new Set([...Object.values(sdlcStageHandlers), ...Object.values(memoryInitStageHandlers)].map(handler => handler.entryId)),
+        finishHandlers: new Set([...Object.values(sdlcStageHandlers), ...Object.values(memoryInitStageHandlers)].map(handler => handler.finishId)), blobs
+    };
+}
+/** Handler identity is also stage/flow scoped: a known CODE handler is not a memory handler. */
+export function admitBundledFlow(input, sha256, blobs) {
+    const flow = ResolvedFlowDescriptor.admit(input, sha256, bundledHandlerContext(blobs));
+    if (flow.descriptor.id === "sdlc") {
+        const edges = vnextStages.flatMap(stage => stage.next.map((to, index) => ({ from: stage.id, to, on: index ? "not-applicable" : "accepted" })));
+        if (flow.descriptor.entry_stage !== "specify" || flow.descriptor.terminal_stages.length !== 1 || flow.descriptor.terminal_stages[0] !== "merge"
+            || flow.descriptor.stages.length !== vnextStages.length
+            || flow.descriptor.stages.some((stage, index) => stage.id !== vnextStages[index].id || stage.directory !== vnextStages[index].directory)
+            || flow.descriptor.edges.length !== edges.length
+            || edges.some(expected => !flow.descriptor.edges.some(edge => edge.from === expected.from && edge.to === expected.to && edge.on === expected.on))) {
+            throw new AppError("flow_handler_scope_invalid", "SDLC handlers require the registered seven-stage layout and transitions", 2, { phase: "prepare", effect: "no_effect" });
+        }
+    }
+    if (flow.descriptor.id === "mb-init") {
+        const stages = Object.keys(memoryInitStageHandlers);
+        const edges = stages.slice(0, -1).map((from, index) => ({ from, to: stages[index + 1], on: "accepted" }));
+        // Historical packs have only accepted transitions; diagnostic VERIFY uses
+        // the same REVIEW handler without granting another route or stage.
+        const requiredEdges = flow.descriptor.edges.filter(edge => !(edge.from === "verify" && edge.to === "review" && edge.on === "needs_repair"));
+        if (flow.descriptor.entry_stage !== "preflight" || flow.descriptor.terminal_stages.length !== 1 || flow.descriptor.terminal_stages[0] !== "finish"
+            || flow.descriptor.stages.length !== stages.length
+            || flow.descriptor.stages.some((stage, index) => stage.id !== stages[index] || stage.directory !== `${String(index + 1).padStart(2, "0")}-${stage.id}`)
+            || requiredEdges.length !== edges.length
+            || edges.some(expected => !flow.descriptor.edges.some(edge => edge.from === expected.from && edge.to === expected.to && edge.on === expected.on))) {
+            throw new AppError("flow_handler_scope_invalid", "Memory init handlers require the registered six-stage layout and transitions", 2, { phase: "prepare", effect: "no_effect" });
+        }
+        for (const stage of flow.descriptor.stages) {
+            let schemaId;
+            try {
+                schemaId = JSON.parse(flow.stageBlob(stage.id, "result_schema").toString("utf8")).$id;
+            }
+            catch { /* Invalid schema cannot authorize this stage handler. */ }
+            if (schemaId !== `dd-flow/mb-init-${stage.id}-result@1`)
+                throw new AppError("flow_handler_scope_invalid", "Memory init stage requires its own registered result schema", 2, { phase: "prepare", effect: "no_effect", stage: stage.id });
+        }
+    }
+    for (const stage of flow.descriptor.stages) {
+        const handlers = flow.descriptor.id === "sdlc" ? Object.values(sdlcStageHandlers) : flow.descriptor.id === "mb-init" ? Object.values(memoryInitStageHandlers) : [];
+        const handler = handlers.find(candidate => candidate.stage === stage.id);
+        if (!handler || stage.entry_handler !== handler.entryId || stage.finish_handler !== handler.finishId) {
+            throw new AppError("flow_handler_scope_invalid", "Registered handlers do not belong to this flow stage", 2, { phase: "prepare", effect: "no_effect", flow_id: flow.descriptor.id, stage: stage.id });
+        }
+    }
+    return flow;
+}

package/dist/services/stage-lifecycle.js

@@ -741,7 +741,8 @@ function buildStageReport(context, view, stage, status, semantic, stageRoot, lin
             next_action: stringValue(semantic.next_action) ?? "Resolve the stage result before continuing.",
             ...(Array.isArray(semantic.questions) ? { questions: semantic.questions } : {}),
             ...(Array.isArray(semantic.reviewer_findings) ? { reviewer_findings: semantic.reviewer_findings } : {}),
-            ...(Array.isArray(semantic.def_outcomes) ? { def_outcomes: semantic.def_outcomes } : {})
+            ...(Array.isArray(semantic.def_outcomes) ? { def_outcomes: semantic.def_outcomes } : {}),
+            ...(semantic.materialization !== undefined ? { materialization: semantic.materialization } : {})
         },
         mechanical: {
             started_at: startedAt,