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

package/dist/services/setup.js

@@ -0,0 +1,377 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { hybridDigest, validateHybridShape } from "./hybrid-contracts.js";
+import { admitReleaseManifest } from "./release-manifest.js";
+import { validateReleasePayloadIdentity } from "./release-payload.js";
+import { publishReleaseCache, verifyPublishedReleaseCache } from "./release-cache.js";
+import { acquireInstallationLock } from "./installation-lock.js";
+import { authenticateReleaseEnvelope } from "./release-envelope.js";
+import { prepareOperatorProfile, validateProfileCreationIntent, commitProfileCreation, readOperatorProfiles } from "./operator-profiles.js";
+/** Production ingress authenticates the source before constructing any installation authority. */
+export function installAuthenticatedRelease(home, input) {
+    const authenticated = authenticateReleaseEnvelope(input.envelope, input.trustedProducers, input.compatibility);
+    return installRelease(home, { requestId: input.requestId, action: input.action,
+        manifest: authenticated.manifest, manifestBytes: authenticated.manifestBytes, authority: authenticated.authority,
+        canonArchive: input.canonArchive, engineArchive: input.engineArchive,
+        ...(input.executor !== undefined ? { executor: input.executor } : {}),
+        ...(input.profileCreation !== undefined ? { profileCreation: input.profileCreation } : {}),
+        ...(input.deferredOnboarding ? { deferredOnboarding: true } : {}),
+        ...(input.onCheckpoint ? { onCheckpoint: input.onCheckpoint } : {}) });
+}
+function refuse(reason, effect = "no_effect") {
+    throw new AppError("setup_conflict", "Setup request cannot proceed", 1, { reason, phase: "setup", effect, help: "setup", next_action: "dd-flow setup status --json" });
+}
+const bytesDigest = (bytes) => createHash("sha256").update(bytes).digest("hex");
+function manifestFromBytes(bytes) {
+    try {
+        return JSON.parse(bytes.toString("utf8"));
+    }
+    catch {
+        return refuse("invalid_manifest_bytes");
+    }
+}
+function regularJson(file) {
+    if (!fs.lstatSync(file).isFile())
+        refuse("unsafe_setup_file");
+    try {
+        return JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        return refuse("invalid_setup_file");
+    }
+}
+function atomicJson(file, value) {
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    const fd = fs.openSync(temporary, "wx", 0o600);
+    try {
+        try {
+            fs.writeFileSync(fd, JSON.stringify(value));
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        fs.renameSync(temporary, file);
+    }
+    finally {
+        if (fs.existsSync(temporary))
+            fs.unlinkSync(temporary);
+    }
+}
+function readSetupRequest(file) {
+    const value = regularJson(file);
+    const required = ["schema_id", "request_id", "identity", "previous_selection", "phase", "installation"];
+    if (!value || typeof value !== "object" || Array.isArray(value)
+        || required.some(key => !Object.hasOwn(value, key))
+        || Object.keys(value).some(key => ![...required, "executor", "profileCreation", "deferredOnboarding"].includes(key)))
+        refuse("invalid_request_record");
+    const request = value;
+    if (Object.hasOwn(request, "deferredOnboarding") && (request.deferredOnboarding !== true || Object.hasOwn(request, "executor") || Object.hasOwn(request, "profileCreation")))
+        refuse("invalid_deferred_onboarding");
+    if (request.schema_id !== "dd-flow/setup-request@1"
+        || typeof request.request_id !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$/.test(request.request_id)
+        || typeof request.identity !== "string" || !/^[a-f0-9]{64}$/.test(request.identity)
+        || request.previous_selection !== null && (typeof request.previous_selection !== "string" || !/^[a-f0-9]{64}$/.test(request.previous_selection))
+        || !["prepared", "canon_cached", "engine_cached", "profiles_saved", "committed"].includes(request.phase)
+        || !request.installation || typeof request.installation !== "object" || Array.isArray(request.installation))
+        refuse("invalid_request_record");
+    if (Object.hasOwn(request, "executor") && request.executor !== null) {
+        try {
+            prepareOperatorProfile(request.executor);
+        }
+        catch {
+            refuse("invalid_request_executor");
+        }
+    }
+    if (Object.hasOwn(request, "profileCreation")) {
+        try {
+            validateProfileCreationIntent(request.profileCreation);
+        }
+        catch {
+            refuse("invalid_request_profile_creation");
+        }
+        if (!request.executor || hybridDigest(request.executor) !== hybridDigest(request.profileCreation.profile))
+            refuse("request_profile_executor_mismatch");
+    }
+    return request;
+}
+/** Read retained executor consent for an exact retry, without installation or profile effects.
+ * Full source/installation request identity is still checked by installRelease.
+ */
+export function readRetainedSetupExecutor(home, requestId) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$/.test(requestId))
+        refuse("invalid_request");
+    const root = path.resolve(home), directory = path.join(root, "setup-requests");
+    for (const candidate of [root, directory])
+        if (fs.existsSync(candidate) && !fs.lstatSync(candidate).isDirectory())
+            refuse("unsafe_setup_directory");
+    const file = path.join(directory, `${requestId}.json`);
+    if (!fs.existsSync(file))
+        return null;
+    const request = readSetupRequest(file);
+    if (request.request_id !== requestId)
+        refuse("request_identity_conflict");
+    if (!Object.hasOwn(request, "executor"))
+        return null;
+    return { executor: structuredClone(request.executor ?? null),
+        ...(request.profileCreation ? { profileCreation: structuredClone(request.profileCreation) } : {}) };
+}
+/** A deferred request is immutable installation consent, not an implicit skip. */
+export function hasDeferredSetupOnboarding(home, requestId) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$/.test(requestId))
+        refuse("invalid_request");
+    const root = path.resolve(home), directory = path.join(root, "setup-requests");
+    for (const candidate of [root, directory])
+        if (fs.existsSync(candidate) && !fs.lstatSync(candidate).isDirectory())
+            refuse("unsafe_setup_directory");
+    const file = path.join(directory, `${requestId}.json`);
+    if (!fs.existsSync(file))
+        return false;
+    const request = readSetupRequest(file);
+    if (request.request_id !== requestId)
+        refuse("request_identity_conflict");
+    return request.deferredOnboarding === true;
+}
+function deferredRequest(home, requestId) {
+    if (!hasDeferredSetupOnboarding(home, requestId))
+        refuse("onboarding_not_deferred");
+    const request = readSetupRequest(path.join(path.resolve(home), "setup-requests", `${requestId}.json`));
+    if (request.phase !== "committed")
+        refuse("installation_not_committed");
+    return request;
+}
+/** Retained consent allows recovery without asking again or importing current defaults. */
+export function readSetupOnboarding(home, requestId) {
+    const request = deferredRequest(home, requestId);
+    const directory = path.join(path.resolve(home), "setup-onboarding");
+    if (fs.existsSync(directory) && !fs.lstatSync(directory).isDirectory())
+        refuse("unsafe_onboarding_directory");
+    const file = path.join(directory, `${requestId}.json`);
+    if (!fs.existsSync(file))
+        return null;
+    const receipt = regularJson(file);
+    if (!receipt || typeof receipt !== "object" || Array.isArray(receipt)
+        || Object.keys(receipt).some(key => !["schema_id", "request_id", "installation_identity", "phase", "executor", "profileCreation"].includes(key))
+        || receipt.schema_id !== "dd-flow/setup-onboarding@1" || receipt.request_id !== requestId
+        || receipt.installation_identity !== request.identity || !["selected", "committed"].includes(receipt.phase)
+        || !Object.hasOwn(receipt, "executor"))
+        refuse("invalid_onboarding_receipt");
+    try {
+        if (receipt.executor !== null)
+            prepareOperatorProfile(receipt.executor);
+        if (receipt.profileCreation !== undefined) {
+            validateProfileCreationIntent(receipt.profileCreation);
+            if (!receipt.executor || hybridDigest(receipt.executor) !== hybridDigest(receipt.profileCreation.profile))
+                refuse("onboarding_profile_mismatch");
+        }
+    }
+    catch {
+        refuse("invalid_onboarding_receipt");
+    }
+    return structuredClone(receipt);
+}
+/** Persist human consent before profile effects; replay never restores later profile edits. */
+export function commitSetupOnboarding(home, requestId, selection) {
+    const request = deferredRequest(home, requestId), root = path.resolve(home);
+    const executor = selection.executor === null ? null : prepareOperatorProfile(selection.executor);
+    if (selection.profileCreation) {
+        validateProfileCreationIntent(selection.profileCreation);
+        if (!executor || hybridDigest(executor) !== hybridDigest(selection.profileCreation.profile))
+            refuse("onboarding_profile_mismatch");
+    }
+    const candidate = { schema_id: "dd-flow/setup-onboarding@1", request_id: requestId,
+        installation_identity: request.identity, phase: "selected", executor,
+        ...(selection.profileCreation ? { profileCreation: selection.profileCreation } : {}) };
+    const lease = acquireInstallationLock(path.join(root, "setup.lock"), hybridDigest({ request_id: requestId, identity: request.identity }));
+    let failure, result;
+    try {
+        const retained = readSetupOnboarding(root, requestId);
+        if (retained && hybridDigest({ ...retained, phase: "selected" }) !== hybridDigest(candidate))
+            refuse("onboarding_selection_conflict");
+        if (retained?.phase === "committed")
+            result = retained;
+        else {
+            if (hybridDigest(readSetupStatus(root).installation) !== hybridDigest(request.installation))
+                refuse("onboarding_installation_changed");
+            const directory = path.join(root, "setup-onboarding");
+            fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+            const file = path.join(directory, `${requestId}.json`);
+            if (!retained)
+                atomicJson(file, candidate);
+            if (candidate.profileCreation)
+                commitProfileCreation(root, candidate.profileCreation);
+            result = { ...candidate, phase: "committed" };
+            atomicJson(file, result);
+        }
+    }
+    catch (error) {
+        failure = error instanceof AppError ? error : new AppError("setup_onboarding_interrupted", "Installed release is retained; executor onboarding requires reconciliation", 1, { phase: "executor_onboarding", effect: "unknown", request_id: requestId, help: "setup", next_action: "Replay the exact setup request" });
+    }
+    finally {
+        try {
+            lease.release();
+        }
+        catch {
+            if (failure)
+                failure.details.cleanup = "not_confirmed";
+            else
+                failure = new AppError("setup_cleanup_failed", "Onboarding owner cleanup requires reconciliation", 1, { effect: "unknown", cleanup: "not_confirmed", request_id: requestId, help: "setup" });
+        }
+    }
+    if (failure)
+        throw failure;
+    return result;
+}
+/** Read-only global readiness. No SQLite connection, migration, project registration or probes. */
+export function readSetupStatus(home) {
+    const root = path.resolve(home);
+    if (fs.existsSync(root) && !fs.lstatSync(root).isDirectory())
+        refuse("unsafe_setup_home");
+    const file = path.join(root, "installation.json");
+    const installation = fs.existsSync(file) ? regularJson(file) : null;
+    if (installation) {
+        if (!installation.manifest || typeof installation.manifest_bytes_base64 !== "string" || validateHybridShape("release-manifest", installation.manifest).length ||
+            installation.canon_root !== path.join(root, "release-cache", "canon", installation.manifest.canon.version, "payload") ||
+            installation.engine_root !== path.join(root, "release-cache", "engine", installation.manifest.engine.version, "payload"))
+            refuse("invalid_installation_selection");
+        const bytes = Buffer.from(installation.manifest_bytes_base64, "base64");
+        if (bytes.toString("base64") !== installation.manifest_bytes_base64 || bytesDigest(bytes) !== installation.manifest_sha256 ||
+            hybridDigest(manifestFromBytes(bytes)) !== hybridDigest(installation.manifest))
+            refuse("invalid_installation_selection");
+    }
+    let readiness = installation ? "installed" : "not_installed";
+    if (installation) {
+        try {
+            verifyPublishedReleaseCache(path.dirname(installation.canon_root), installation.manifest.canon.archive);
+            verifyPublishedReleaseCache(path.dirname(installation.engine_root), installation.manifest.engine.archive);
+        }
+        catch {
+            readiness = "degraded";
+        }
+    }
+    const existingStorage = fs.existsSync(path.join(root, "db.sqlite"));
+    return { installation, installation_readiness: readiness,
+        storage_readiness: existingStorage ? "unknown_requires_diagnostic" : "not_initialized",
+        runtime_readiness: "unknown_requires_qualification",
+        next_action: !installation ? "dd-flow setup --help" : existingStorage ? "dd-flow migration plan --help" : "dd-flow engine doctor --json",
+        ...(existingStorage ? { storage_continuation: { kind: "storage_admission",
+                status: "requires_diagnostic", reason: "existing_storage_not_inspected",
+                help_command: "dd-flow migration plan --help", automatic_migration: false } } : {}) };
+}
+/** Exact-request installation transaction. Selected immutable caches do not affect existing RUNs. */
+export function installRelease(home, input) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$/.test(input.requestId) || !["install", "update"].includes(input.action))
+        refuse("invalid_request");
+    const executor = input.executor === undefined ? undefined : input.executor === null ? null : prepareOperatorProfile(input.executor);
+    const executorBinding = executor === undefined ? {} : { executor: structuredClone(executor) };
+    if (input.deferredOnboarding !== undefined && (input.deferredOnboarding !== true || executor !== undefined || input.profileCreation !== undefined))
+        refuse("invalid_deferred_onboarding");
+    const onboardingBinding = input.deferredOnboarding ? { deferredOnboarding: true } : {};
+    if (input.profileCreation !== undefined) {
+        validateProfileCreationIntent(input.profileCreation);
+        if (!executor || hybridDigest(executor) !== hybridDigest(input.profileCreation.profile))
+            refuse("profile_executor_mismatch");
+    }
+    const profileBinding = input.profileCreation === undefined ? {} : { profileCreation: structuredClone(input.profileCreation) };
+    const manifest = admitReleaseManifest(input.manifest, input.authority);
+    if (!Buffer.isBuffer(input.manifestBytes) || hybridDigest(manifestFromBytes(input.manifestBytes)) !== hybridDigest(manifest))
+        refuse("manifest_bytes_mismatch");
+    // Both archives must be valid before even creating the home or publishing the first cache.
+    validateReleasePayloadIdentity(manifest, input.canonArchive, input.engineArchive);
+    const root = path.resolve(home), requests = path.join(root, "setup-requests"), lock = path.join(root, "setup.lock");
+    const installation = { manifest, manifest_sha256: bytesDigest(input.manifestBytes), manifest_bytes_base64: input.manifestBytes.toString("base64"),
+        canon_root: path.join(root, "release-cache", "canon", manifest.canon.version, "payload"),
+        engine_root: path.join(root, "release-cache", "engine", manifest.engine.version, "payload") };
+    const identity = hybridDigest({ action: input.action, installation, ...executorBinding, ...profileBinding, ...onboardingBinding });
+    readSetupStatus(root);
+    for (const directory of [root, requests]) {
+        if (fs.existsSync(directory) && !fs.lstatSync(directory).isDirectory())
+            refuse("unsafe_setup_directory");
+    }
+    if (input.profileCreation) {
+        const existingFile = path.join(requests, `${input.requestId}.json`);
+        const retained = fs.existsSync(existingFile) ? readSetupRequest(existingFile) : null;
+        if (retained?.phase !== "committed") {
+            const revision = readOperatorProfiles(root).revision;
+            if (revision !== input.profileCreation.before.revision && revision !== input.profileCreation.after.revision)
+                refuse("profile_selection_changed");
+        }
+    }
+    fs.mkdirSync(requests, { recursive: true, mode: 0o700 });
+    const lease = acquireInstallationLock(lock, hybridDigest({ request_id: input.requestId, identity }));
+    let failure;
+    const perform = () => {
+        const file = path.join(requests, `${input.requestId}.json`);
+        const current = readSetupStatus(root).installation;
+        let request = { schema_id: "dd-flow/setup-request@1", request_id: input.requestId, identity,
+            previous_selection: current ? hybridDigest(current) : null, phase: "prepared", installation, ...executorBinding, ...profileBinding, ...onboardingBinding };
+        if (fs.existsSync(file)) {
+            request = readSetupRequest(file);
+            if (request.schema_id !== "dd-flow/setup-request@1" || request.request_id !== input.requestId || request.identity !== identity || hybridDigest(request.installation) !== hybridDigest(installation))
+                refuse("request_identity_conflict");
+            if (request.deferredOnboarding !== input.deferredOnboarding)
+                refuse("request_onboarding_conflict");
+            if (hybridDigest({ executor: request.executor ?? null, present: Object.hasOwn(request, "executor") }) !==
+                hybridDigest({ executor: executor ?? null, present: executor !== undefined }))
+                refuse("request_executor_conflict");
+            if (hybridDigest({ profileCreation: request.profileCreation ?? null }) !== hybridDigest({ profileCreation: input.profileCreation ?? null }))
+                refuse("request_profile_creation_conflict");
+            if (!["prepared", "canon_cached", "engine_cached", "profiles_saved", "committed"].includes(request.phase))
+                refuse("invalid_request_phase");
+        }
+        // Replay still revalidates retained payload bytes; it never reactivates an older selection.
+        if (request.phase === "committed") {
+            publishReleaseCache(root, "canon", manifest.canon.version, manifest.canon.archive, input.canonArchive);
+            publishReleaseCache(root, "engine", manifest.engine.version, manifest.engine.archive, input.engineArchive);
+            return { ok: true, replayed: true, installation: request.installation, ...executorBinding };
+        }
+        const selectedDigest = current ? hybridDigest(current) : null;
+        if (selectedDigest !== request.previous_selection && selectedDigest !== hybridDigest(installation))
+            refuse("selection_changed_since_request");
+        if (input.action === "install" && current && selectedDigest !== hybridDigest(installation))
+            refuse("existing_installation_requires_update");
+        const checkpoint = (phase) => {
+            request.phase = phase;
+            atomicJson(file, request);
+            input.onCheckpoint?.(phase);
+        };
+        checkpoint("prepared");
+        publishReleaseCache(root, "canon", manifest.canon.version, manifest.canon.archive, input.canonArchive);
+        checkpoint("canon_cached");
+        publishReleaseCache(root, "engine", manifest.engine.version, manifest.engine.archive, input.engineArchive);
+        checkpoint("engine_cached");
+        if (request.profileCreation) {
+            commitProfileCreation(root, request.profileCreation);
+            checkpoint("profiles_saved");
+        }
+        atomicJson(path.join(root, "installation.json"), installation);
+        checkpoint("committed");
+        return { ok: true, replayed: false, installation, ...executorBinding };
+    };
+    let result;
+    try {
+        result = perform();
+    }
+    catch (error) {
+        failure = error instanceof AppError ? error : new AppError("setup_interrupted", "Setup request requires reconciliation", 1, { phase: "setup", effect: "unknown", request_id: input.requestId, next_action: "Replay the exact setup request", help: "setup" });
+    }
+    finally {
+        try {
+            lease.release();
+        }
+        catch {
+            // Cleanup is secondary to the retained operation result. Never leak a
+            // raw filesystem cause or erase the original failure with an unlink error.
+            if (failure)
+                failure.details.cleanup = "not_confirmed";
+            else
+                failure = new AppError("setup_cleanup_failed", "Setup owner cleanup requires reconciliation", 1, { phase: "setup", effect: "unknown", cleanup: "not_confirmed", request_id: input.requestId,
+                    next_action: "Inspect dd-flow setup status --json; replay the exact request after its owner exits", help: "setup" });
+        }
+    }
+    if (failure)
+        throw failure;
+    return result;
+}

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-report-renderer.js

@@ -4,6 +4,69 @@ import crypto from "node:crypto";
 import { AppError } from "../shared/errors.js";
 import { withProjectionLock } from "../storage/projection-lock.js";
 import { writeJsonAtomic } from "../storage/paths.js";
+import { assertRunBundleSqlAuthority } from "./runs.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+/** Accepted bytes come from SQL receipts, never from the mutable publication.
+ * Stage completion and its independent committed checksum must agree. This is
+ * byte custody, not a substitute for the registered handler's semantic gates.
+ */
+export function readAcceptedStageData(context, scope) {
+    function refuse() { throw new AppError("stage_data_custody_invalid", "Accepted stage data lacks matching committed SQL byte custody", 1, { run_id: scope.runId, stage: scope.stage }); }
+    const run = context.db.get("SELECT index_json, run_root, run_dir FROM runs WHERE project_id = ? AND id = ?", [scope.projectId, scope.runId]);
+    if (!run)
+        refuse();
+    const index = JSON.parse(run.index_json);
+    assertRunBundleSqlAuthority(context, scope, index.execution_bundle);
+    const stage = index.stage_runs?.find((item) => item.stage === scope.stage);
+    const portable = (value) => typeof value === "string" && Boolean(value) && !path.posix.isAbsolute(value) && !path.win32.isAbsolute(value) && !value.includes("\\") && !value.includes("\0") && value.split("/").every(part => Boolean(part) && part !== "." && part !== "..");
+    if (!stage || stage.status !== "done" || !portable(stage.dir) || !portable(stage.data)
+        || typeof stage.attempt !== "string" || !/^try-[0-9]{3,}$/.test(stage.attempt)
+        || typeof stage.data_sha256 !== "string" || !/^[a-f0-9]{64}$/.test(stage.data_sha256))
+        refuse();
+    const root = run.run_root ?? run.run_dir;
+    if (!path.isAbsolute(root))
+        refuse();
+    const relative = `${stage.dir}/${stage.data}`, destination = path.resolve(root, relative);
+    const rows = context.db.all("SELECT event_type, payload_json FROM audit_events WHERE project_id = ? AND event_type IN ('flow_run.stage_packet', 'flow_run.stage_report') AND json_extract(payload_json, '$.run_id') = ? AND json_extract(payload_json, '$.stage') = ? AND json_extract(payload_json, '$.attempt') = ? LIMIT 33", [scope.projectId, scope.runId, scope.stage, stage.attempt]);
+    if (rows.length > 32)
+        refuse();
+    let accepted;
+    for (const row of rows) {
+        if (Buffer.byteLength(row.payload_json) > 8 * 1024 * 1024)
+            refuse();
+        const receipt = JSON.parse(row.payload_json);
+        if (receipt.sha256 !== stage.data_sha256)
+            continue;
+        const locator = row.event_type === "flow_run.stage_packet" ? receipt.file : typeof receipt.root === "string" ? path.join(receipt.root, "stage-report.json") : null;
+        if (typeof locator !== "string" || resolveStagePublicationPath(context, scope.projectId, scope.runId, locator) !== destination)
+            continue;
+        let bytes;
+        if (row.event_type === "flow_run.stage_packet") {
+            if (typeof receipt.base64 !== "string")
+                refuse();
+            bytes = Buffer.from(receipt.base64, "base64");
+            if (bytes.toString("base64") !== receipt.base64)
+                refuse();
+        }
+        else {
+            if (typeof receipt.bytes?.json !== "string")
+                refuse();
+            bytes = Buffer.from(receipt.bytes.json);
+        }
+        if (!bytes.length || bytes.length > 1024 * 1024 || crypto.createHash("sha256").update(bytes).digest("hex") !== stage.data_sha256)
+            refuse();
+        if (accepted && !accepted.equals(bytes))
+            refuse();
+        accepted = bytes;
+    }
+    if (!accepted)
+        refuse();
+    return { bytes: Buffer.from(accepted), result: { path: relative, sha256: stage.data_sha256 },
+        input_sha256: stage.input_sha256, data_schema_id: stage.data_schema_id,
+        authority_sha256: hybridDigest({ scope, attempt: stage.attempt, directory: stage.dir, data: stage.data,
+            input_sha256: stage.input_sha256 ?? null, data_schema_id: stage.data_schema_id ?? null,
+            anchor: index.execution_bundle ?? null, data_sha256: stage.data_sha256 }) };
+}
 /** Deterministic JSON -> Markdown/HTML projection shared by every stage. */
 export function writeStageReport(root, report) {
     const json = path.join(root, "stage-report.json");

package/dist/services/stage-work-graph.js

@@ -7,6 +7,23 @@ export function stageAttempt(context, projectId, runId, stage) {
     return [...stages].reverse().find(item => item.stage === stage)?.attempt ?? "try-001";
 }
 export function bindStageWork(context, input) {
+    context.db.writeTransaction(() => bindStageWorkOwned(context, input), "stage-work.bind");
+}
+function bindStageWorkOwned(context, input) {
+    const run = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [input.projectId, input.runId]);
+    const index = run ? JSON.parse(run.index_json) : null;
+    if (index?.execution_bundle) {
+        // Stage attachment already admitted the frozen descriptor outside the writer.
+        // Membership checks here consume only authoritative SQLite facts.
+        const stage = index.stage_runs.find(item => item.stage === input.stage && item.status === "running");
+        const work = context.db.get("SELECT parent_work_id FROM works WHERE project_id = ? AND run_id = ? AND work_id = ?", [input.projectId, input.runId, input.workId]);
+        const parentOwned = !work?.parent_work_id || context.db.get("SELECT 1 FROM works WHERE project_id = ? AND run_id = ? AND work_id = ?", [input.projectId, input.runId, work.parent_work_id]);
+        const currentStage = index.current_stage ?? (index.execution_bundle.flow_id === "sdlc" ? index.stage_runs.at(-1)?.stage : undefined);
+        if (!stage || currentStage !== input.stage || !work || !parentOwned || input.attempt !== undefined && input.attempt !== (stage.attempt ?? "try-001")
+            || input.cycle !== undefined && input.cycle !== stageCycle(context, input.projectId, input.runId, input.stage)) {
+            throw new AppError("stage_work_scope_invalid", "Work membership does not belong to the active frozen stage scope", 1, { run_id: input.runId, stage: input.stage, work_id: input.workId });
+        }
+    }
     context.db.run("INSERT OR IGNORE INTO stage_work_memberships (project_id, run_id, work_id, stage, attempt, cycle) VALUES (?, ?, ?, ?, ?, ?)", [input.projectId, input.runId, input.workId, input.stage, input.attempt ?? stageAttempt(context, input.projectId, input.runId, input.stage), input.cycle ?? stageCycle(context, input.projectId, input.runId, input.stage)]);
 }
 export function stageCycle(context, projectId, runId, stage) {

package/dist/services/vnext-code.js

@@ -498,7 +498,7 @@ export function prepareVnextCodeRepair(context, input) {
 export function addVnextCodeRepair(context, input, prepared = prepareVnextCodeRepair(context, input)) {
     const { project, run } = prepared;
     if (prepared.kind === "replay")
-        return { ok: true, run_id: run.id, repair_work_id: prepared.previous.work_id, start_command: workStartCommand(context, prepared.previous), reused: true };
+        return { ok: true, run_id: run.id, repair_work_id: prepared.previous.work_id, start_command: workStartCommand(context, prepared.previous, { preview: true }), reused: true };
     const { parentWorkId, items, key, receipt } = prepared;
     const create = () => String(addWorkBatch(context, { parentWorkId, prepared: items, stage: input.stage ?? (input.reviewCycle ? "code-review" : "code"), ...(input.reviewCycle ? { cycle: input.reviewCycle } : {}) }).work_ids[key]);
     const id = input.registrationOwned ? create() : ensureRepairIntent(context, {
@@ -513,7 +513,7 @@ export function addVnextCodeRepair(context, input, prepared = prepareVnextCodeRe
         ...(receipt ? { check_receipt_id: receipt.id } : prepared.input.reviewFindings?.length ? { review_finding_ids: prepared.input.reviewFindings.map((finding) => finding.finding_ref) } : { semantic_unresolved: prepared.input.semanticUnresolved })
     });
     refreshRunWorkProjection(context, project.id, run.id);
-    return { ok: true, run_id: run.id, repair_work_id: id, start_command: workStartCommand(context, work) };
+    return { ok: true, run_id: run.id, repair_work_id: id, start_command: workStartCommand(context, work, { preview: true }) };
 }
 /** Retain the causal declaration for worker context; run_at still records its original gate. */
 export function selectRepairChecks(input) {
@@ -730,7 +730,7 @@ async function ensureCodeWorkspaceReady(context, projectId, run, root, readiness
     const profile = JSON.parse(run.index_json);
     const bootstrap = profile.execution_profile?.settings?.code_bootstrap;
     if (!bootstrap || typeof bootstrap.command !== "string" || typeof bootstrap.policy_ref !== "string") {
-        throw new AppError("execution_profile_invalid", "CODE requires a frozen bootstrap command in the RUN execution profile", 1, { run_id: run.id });
+        throw new AppError("execution_profile_invalid", "CODE requires an evidenced bootstrap command and policy in the frozen RUN profile; configure code_bootstrap before starting a code-ready RUN", 1, { run_id: run.id });
     }
     const receiptPath = path.join(root, "workspace-readiness.json");
     const ownerId = context.env.DD_FLOW_CODE_READINESS_OWNER;

package/dist/services/vnext-execution-profile.js

@@ -93,8 +93,8 @@ export function validateVnextExecutionProfile(value) {
         || profile.merge_delivery?.strategy !== "local"
         || !["retain", "delete_after_success"].includes(String(profile.merge_cleanup?.source))
         || !["code_completed", "code_review_completed", "merge_completed"].includes(String(profile.stop_target))
-        || !profile.code_bootstrap || typeof profile.code_bootstrap.command !== "string" || !profile.code_bootstrap.command.trim()
-        || typeof profile.code_bootstrap.policy_ref !== "string" || !profile.code_bootstrap.policy_ref.trim()
+        || (profile.code_bootstrap !== undefined && (!profile.code_bootstrap || typeof profile.code_bootstrap.command !== "string" || !profile.code_bootstrap.command.trim()
+            || typeof profile.code_bootstrap.policy_ref !== "string" || !profile.code_bootstrap.policy_ref.trim()))
         || (profile.execution === undefined ? profile.schema_id === "dd-flow/project-execution@3" : !isExecutionRouting(profile.execution))) {
         throw new AppError("execution_profile_invalid", "Project execution profile does not match its supported dd-flow schema", 1);
     }