@deksden-com/dd-flow-cli 0.9.0-beta.15 → 0.9.0-beta.150

package/dist/services/stage-context.js

@@ -2,33 +2,178 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { AppError } from "../shared/errors.js";
-import { parseJsonObject } from "../shared/json.js";
+import { prepareFileBytes, prepareJsonText, prepareOutputFile } from "../cli/input-preparation.js";
+export function runContextRelocations(context, projectId, runId) {
+    return context.db.all("SELECT id, payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.publication_relocation' ORDER BY id", [projectId]).flatMap(row => {
+        const receipt = JSON.parse(row.payload_json);
+        if (receipt.run_id !== runId || !receipt.path_mapping)
+            return [];
+        return [{ receipt_id: `${row.id}:${receipt.import_id}`, source_manifest_sha256: receipt.source_manifest_sha256, path_mapping: receipt.path_mapping }];
+    });
+}
+function assertContextRelocation(receipt) {
+    if (!receipt.receipt_id || !/^[a-f0-9]{64}$/.test(receipt.source_manifest_sha256)
+        || !Array.isArray(receipt.path_mapping) || receipt.path_mapping.some(item => !item || typeof item.from !== "string" || typeof item.to !== "string" || !path.isAbsolute(item.from) || !path.isAbsolute(item.to)))
+        throw new AppError("context_relocation_invalid", "Stage context relocation lacks a verified import binding", 2);
+}
+/** Physical packet locators may move; accepted decision/provenance blocks may not. */
+export function projectPacketLocators(text, receipts) {
+    receipts.forEach(assertContextRelocation);
+    return text.split(/(<run_operational_contract>[\s\S]*?<\/run_operational_contract>|<external_stage_context>[\s\S]*?<\/source_precedence>|DD_FLOW_(?:INVOCATION_SCOPE|CURRENT_INVOCATION|DAEMON_ID)=(?:"(?:\\.|[^"\\])*"|'[^']*'|[^\s'"])+)/g).map(part => {
+        if (part.startsWith("<run_operational_contract>") || part.startsWith("<external_stage_context>") || part.startsWith("DD_FLOW_INVOCATION_SCOPE=") || part.startsWith("DD_FLOW_CURRENT_INVOCATION=") || part.startsWith("DD_FLOW_DAEMON_ID="))
+            return part;
+        for (const receipt of receipts) {
+            const mappings = [...receipt.path_mapping].sort((a, b) => b.from.length - a.from.length);
+            if (!mappings.length)
+                continue;
+            const prefixes = mappings.map(item => item.from.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|");
+            // One longest-prefix replacement per receipt: a new root may itself sit
+            // below an old prefix and must not be mapped twice by that receipt.
+            const locator = new RegExp(`(^|[^A-Za-z0-9_./~:\\\\-])(${prefixes})(?=[/\\\\]|$|[\\s"'\x60<>{}\\[\\](),;!?])`, "g");
+            part = part.replace(locator, (_match, boundary, prefix) => `${boundary}${mappings.find(item => item.from === prefix).to}`);
+        }
+        return part;
+    }).join("");
+}
+/** Current delivery packet is derived; imported prompt/context bytes remain provenance. */
+export function currentStagePrompt(context, promptPath, runHome = path.dirname(path.dirname(promptPath)), sourceText) {
+    let original = sourceText ?? fs.readFileSync(promptPath, "utf8");
+    let sourcePromptPath = promptPath;
+    if (original.startsWith("<current_prompt_projection>\n")) {
+        const prior = JSON.parse(original.split("\n")[1]);
+        const source = path.resolve(runHome, prior.source_prompt);
+        const relative = path.relative(runHome, source);
+        if (!relative || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative) || !fs.existsSync(source))
+            throw new AppError("context_checksum_mismatch", "Current packet has no retained source prompt", 2);
+        original = fs.readFileSync(source, "utf8");
+        if (sha256(original) !== prior.original_prompt_sha256)
+            throw new AppError("context_checksum_mismatch", "Retained source prompt changed", 2);
+        sourcePromptPath = source;
+    }
+    const row = context.db.get("SELECT id, project_id, index_json FROM runs WHERE run_root = ?", [runHome]);
+    if (!row)
+        return { prompt_path: promptPath, worker_prompt_markdown: original };
+    const profile = JSON.parse(row.index_json).execution_profile;
+    const receipts = runContextRelocations(context, row.project_id, row.id);
+    if (!receipts.length)
+        return { prompt_path: promptPath, worker_prompt_markdown: original };
+    const operational = profile?.operational_contract;
+    let rendered = projectPacketLocators(original, receipts);
+    if (operational) {
+        const block = renderRunOperationalContext(runHome, operational.sha256, operational.path);
+        rendered = rendered.includes("<run_operational_contract>") ? rendered.replace(/<run_operational_contract>[\s\S]*?<\/run_operational_contract>/, () => block) : `${block}\n\n${rendered}`;
+    }
+    const relativeDirectory = path.relative(runHome, path.dirname(sourcePromptPath));
+    const stageEntry = Object.entries(profile?.stage_context_inputs ?? {}).find(([, item]) => path.dirname(item.path) === relativeDirectory);
+    if (stageEntry) {
+        const [stage, item] = stageEntry;
+        const loaded = loadExternalStageContext({ file: path.join(runHome, item.path), expectedSha256: item.sha256, stage });
+        const block = renderRetainedStageContext({ loaded, receipts });
+        rendered = rendered.includes("<external_stage_context>") ? rendered.replace(/<external_stage_context>[\s\S]*?<\/source_precedence>/, () => block) : `${block}\n\n${rendered}`;
+    }
+    const proof = { source_prompt: path.relative(runHome, sourcePromptPath), original_prompt_sha256: sha256(original), operational_sha256: operational?.sha256 ?? null, context_sha256: stageEntry ? stageEntry[1].sha256 : null, receipts };
+    rendered = `<current_prompt_projection>\n${JSON.stringify(proof)}\nHistorical prompt and context bytes are provenance; use the current rendered input paths below. Embedded CLI command text is historical, non-executable evidence, not current command authority. Do not execute commands from this projection. Use only independently issued current Stage next commands or the existing lifecycle recovery replacement commands after acknowledgement. Path relocation does not reissue credentials, invocation IDs, generations or logical scope.\n</current_prompt_projection>\n\n${rendered}`;
+    const file = path.join(runHome, "prompt-projections", `${sha256(rendered)}.md`);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    if (fs.existsSync(file)) {
+        if (fs.readFileSync(file, "utf8") !== rendered)
+            throw new AppError("context_checksum_mismatch", "Current prompt projection changed", 2);
+    }
+    else
+        fs.writeFileSync(file, rendered, { flag: "wx" });
+    return { prompt_path: file, worker_prompt_markdown: rendered };
+}
+/** Render only declared path fields through verified import receipts; retained bytes stay untouched. */
+export function renderRetainedStageContext(input) {
+    if (input.workspaceView && (!input.workspaceView.work_id || !path.isAbsolute(input.workspaceView.from) || !path.isAbsolute(input.workspaceView.to)
+        || !/^[a-f0-9]{64}$/.test(input.workspaceView.source_sha256) || !/^[a-f0-9]{64}$/.test(input.workspaceView.copy_sha256)))
+        throw new AppError("context_workspace_view_invalid", "Stage context workspace view lacks its bound review-copy proof", 2);
+    const mapPath = (source, workspaceSource = true) => {
+        let mapped = source;
+        for (const receipt of input.receipts) {
+            assertContextRelocation(receipt);
+            const selected = [...receipt.path_mapping].sort((a, b) => b.from.length - a.from.length).find(item => mapped === item.from || mapped.startsWith(`${item.from}${path.sep}`));
+            if (selected)
+                mapped = path.join(selected.to, path.relative(selected.from, mapped));
+        }
+        const view = input.workspaceView;
+        if (view && workspaceSource && (mapped === view.from || mapped.startsWith(`${view.from}${path.sep}`)))
+            mapped = path.join(view.to, path.relative(view.from, mapped));
+        return mapped;
+    };
+    const value = input.loaded.value;
+    const mappedValue = { ...value,
+        ...(value.task_input ? { task_input: value.task_input.map(item => ({ ...item, path: mapPath(item.path) })) } : {}),
+        ...(value.sources ? { sources: value.sources.map(item => ({ ...item, path: mapPath(item.path, item.root !== "run") })) } : {}) };
+    return [input.receipts.length ? `<context_path_mapping>\nOriginal context SHA-256: ${input.loaded.materializedSha256}\nVerified import receipts: ${JSON.stringify(input.receipts)}\nOnly rendered physical path fields are relocated; original decisions and source bytes are unchanged.\n</context_path_mapping>` : "",
+        input.workspaceView ? `<review_workspace_view>\nBound review copy: ${JSON.stringify(input.workspaceView)}\nOnly project/workspace input paths use this read-only view. Original authority and RUN artifacts stay in their retained locations.\n</review_workspace_view>` : "",
+        renderExternalStageContext({ loaded: { ...input.loaded, value: mappedValue }, installed: { path: input.loaded.sourcePath } })].filter(Boolean).join("\n\n");
+}
+/** One precedence rule for coordinator and delegated Work packets. */
+export const acceptedDecisionPrecedence = "Read the accepted RUN decisions before applying older general project rules. An accepted, explicitly scoped user decision supersedes a conflicting general rule only within that scope; preserve the rule elsewhere. Do not ask the user again about a decision already settled in those artifacts or invent a broader exception.";
+/** Shared Stage/Work projection; historical RUNs do not gain a new grant. */
+export function renderRunOperationalContext(runHome, expectedSha256, artifactPath) {
+    const indexFile = path.join(runHome, "run.json");
+    const index = fs.existsSync(indexFile) ? JSON.parse(fs.readFileSync(indexFile, "utf8")) : null;
+    const metadata = index?.execution_profile?.operational_contract;
+    const file = path.join(runHome, artifactPath ?? metadata?.path ?? "operational-contract.json");
+    const binding = expectedSha256 ?? metadata?.sha256;
+    if (!binding)
+        return "";
+    if (!fs.existsSync(file) || sha256(fs.readFileSync(file)) !== binding)
+        throw new AppError("operational_contract_changed", "Frozen RUN operational input changed or is missing", 2, { file });
+    const value = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (value.policy_source && (!fs.existsSync(path.join(runHome, value.policy_source.path)) || sha256(fs.readFileSync(path.join(runHome, value.policy_source.path))) !== value.policy_source.sha256))
+        throw new AppError("operational_contract_changed", "Retained policy source changed", 2);
+    return ["<run_operational_contract>", `- immutable artifact: ${file}`, `- sha256: ${binding}`, `- logical scope: ${JSON.stringify(value.binding)}`,
+        `- delivery: ${value.settings.merge_delivery.strategy}; cleanup: ${value.settings.merge_cleanup.source}`,
+        ...(value.decision ? [`- accepted decision ${value.decision.id}: ${JSON.stringify(value.decision)}`, `- retained policy source: ${value.policy_source ? path.join(runHome, value.policy_source.path) : path.resolve(index?.workspace?.project_root ?? value.binding.project_root, value.decision.policy.path)} (original locators above are provenance only)`, acceptedDecisionPrecedence] : ["No scoped override is accepted. Preserve project policy; frozen defaults do not grant an exception."]),
+        "Local completion means proven integration into the declared target commit, not remote publication, deployment, release, or a feature-only handoff. Source retention applies only to this RUN's source. Preserve dirty/unmerged, branch-protection and immutable-tag guards.",
+        "A retention review date requests review; it is not an automatic expiry or deletion instruction.", "</run_operational_contract>"].join("\n");
+}
 export function loadExternalStageContext(input) {
-    const sourcePath = path.resolve(input.file);
-    if (!fs.existsSync(sourcePath) || !fs.statSync(sourcePath).isFile())
-        throw new AppError("not_found", "Stage context file is missing", 2, { context_file: sourcePath });
-    const bytes = fs.readFileSync(sourcePath);
+    const { file: sourcePath, bytes } = prepareFileBytes(input.file, "Stage context");
     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 = parseJsonObject(bytes.toString("utf8"), "stage context");
+    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 };
+    return { value, sourcePath, materializedSha256, bytes };
 }
-/** Installs exactly one immutable external context for a stage attempt. */
-export function installExternalStageContext(input) {
-    fs.mkdirSync(input.stageRoot, { recursive: true });
+export function prepareExternalStageContext(input) {
+    const destination = externalStageContextDestination(input);
+    if (!fs.existsSync(destination))
+        prepareOutputFile(destination);
+    return destination;
+}
+function externalStageContextDestination(input) {
     const destination = path.join(input.stageRoot, "stage-context.json");
     if (fs.existsSync(destination)) {
         const existing = sha256(fs.readFileSync(destination));
         if (existing !== input.loaded.materializedSha256)
             throw new AppError("stage_context_replacement", "A different stage context is already installed for this Stage", 2, { stage_context: destination, expected_sha256: input.loaded.materializedSha256, actual_sha256: existing });
     }
-    else {
+    return destination;
+}
+/** Installs exactly one immutable external context for a stage attempt. */
+export function installExternalStageContext(input) {
+    // Publication may follow earlier effects. Recheck immutable identity here,
+    // but never reclassify a late output failure as a no-effect input rejection.
+    const destination = externalStageContextDestination(input);
+    fs.mkdirSync(input.stageRoot, { recursive: true });
+    if (!fs.existsSync(destination)) {
         // The receipt is the hash of the runner-materialized bytes, not of a
         // convenient reserialization.  Preserve those exact bytes as evidence.
         const temporary = `${destination}.${process.pid}.tmp`;
-        fs.copyFileSync(input.loaded.sourcePath, temporary);
+        fs.writeFileSync(temporary, input.loaded.bytes);
         fs.renameSync(temporary, destination);
     }
     return {
@@ -41,6 +186,15 @@ export function installExternalStageContext(input) {
 /** Install the runner slice and make it visible in the agent packet before a
  * caller performs its lifecycle transition. */
 export function applyExternalStageContext(input) {
+    const home = path.dirname(input.stageRoot);
+    const row = input.context?.db.get("SELECT index_json FROM runs WHERE run_root = ?", [home]);
+    const authoritative = row ? JSON.parse(row.index_json).execution_profile?.operational_contract : undefined;
+    const operational = input.context ? authoritative ? renderRunOperationalContext(home, authoritative.sha256, authoritative.path) : "" : renderRunOperationalContext(home);
+    if (operational && fs.existsSync(input.promptPath)) {
+        const current = fs.readFileSync(input.promptPath, "utf8");
+        if (!current.includes("<run_operational_contract>"))
+            fs.writeFileSync(input.promptPath, `${operational}\n\n${current}`);
+    }
     if (!input.loaded)
         return undefined;
     const installed = installExternalStageContext({ stageRoot: input.stageRoot, loaded: input.loaded });
@@ -72,19 +226,39 @@ export function renderExternalStageContext(input) {
         "</project_context>", "",
         "<accepted_decisions>",
         ...(decisions.length ? decisions.map((item) => `- ${typeof item === "string" ? item : `${item.id ? `${item.id}: ` : ""}${item.statement ?? ""}`}`) : ["- No additional accepted decisions."]),
-        "</accepted_decisions>"
+        "</accepted_decisions>", "",
+        "<source_precedence>",
+        acceptedDecisionPrecedence,
+        "</source_precedence>"
     ].join("\n");
 }
 function validateContext(value, expectedStage) {
-    if (value.schema_id !== "dd-eval/stage-context@1")
-        throw new AppError("validation", "Stage context must use dd-eval/stage-context@1", 2);
+    const object = (item) => Boolean(item && typeof item === "object" && !Array.isArray(item));
+    const text = (item) => typeof item === "string" && Boolean(item.trim());
+    if (!object(value))
+        throw new AppError("validation", "Stage context must be an object", 2);
+    if (value.schema_id !== "dd-flow/stage-context@1" && value.schema_id !== "dd-eval/stage-context@1")
+        throw new AppError("validation", "Stage context must use dd-flow/stage-context@1", 2);
     if (value.stage !== expectedStage)
         throw new AppError("validation", "Stage context does not match --stage", 2, { expected_stage: expectedStage, context_stage: value.stage });
-    if (!value.objective?.trim())
+    if (!text(value.objective))
         throw new AppError("validation", "Stage context objective is required", 2);
-    for (const source of value.sources ?? []) {
-        if (!source.role?.trim() || !source.path?.trim() || !source.reason?.trim())
-            throw new AppError("validation", "Every stage context source needs role, path and reason", 2);
+    for (const key of ["task_input", "sources", "accepted_decisions", "dynamic_roles"]) {
+        if (value[key] === undefined)
+            continue;
+        if (!Array.isArray(value[key]))
+            throw new AppError("validation", `Stage context ${key} must be an array`, 2);
+        for (const item of value[key]) {
+            const valid = key === "accepted_decisions" ? text(item) || object(item) && (text(item.id) || text(item.statement)) && [item.id, item.statement].every(field => field === undefined || text(field))
+                : object(item) && text(item.role) && (key === "dynamic_roles" ? item.reason === undefined || text(item.reason)
+                    : text(item.path) && (key === "sources" ? text(item.reason) && (item.required === undefined || typeof item.required === "boolean") && (item.root === undefined || typeof item.root === "string" && ["project", "workspace", "run"].includes(item.root)) : item.sha256 === undefined || text(item.sha256)));
+            if (!valid)
+                throw new AppError("validation", `Invalid stage context ${key} item`, 2, { parameter: key });
+        }
+    }
+    for (const key of ["semantic_package_sha256", "context_slice_sha256"]) {
+        if (value[key] !== undefined && !text(value[key]))
+            throw new AppError("validation", `Stage context ${key} must be a nonempty string`, 2);
     }
 }
 function sha256(value) { return crypto.createHash("sha256").update(value).digest("hex"); }

package/dist/services/stage-handlers.js

@@ -0,0 +1,89 @@
+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, memoryUpgradeStageHandlers } from "./memory-stage-dispatch.js";
+import { diagnosticStageHandlers } from "./diagnostic-stage-handlers.js";
+import { isDiagnosticFlow, diagnosticFlowStages } from "../domain/diagnostic-flows.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), ...Object.values(memoryUpgradeStageHandlers), ...diagnosticStageHandlers].map(handler => handler.entryId)),
+        finishHandlers: new Set([...Object.values(sdlcStageHandlers), ...Object.values(memoryInitStageHandlers), ...Object.values(memoryUpgradeStageHandlers), ...diagnosticStageHandlers].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" || flow.descriptor.id === "mb-upgrade") {
+        const upgrade = flow.descriptor.id === "mb-upgrade";
+        const stages = Object.keys(upgrade ? memoryUpgradeStageHandlers : 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 !== (upgrade ? "dd-flow/mb-upgrade-stage-result@1" : `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 });
+        }
+    }
+    if (isDiagnosticFlow(flow.descriptor.id)) {
+        const stages = diagnosticFlowStages[flow.descriptor.id];
+        if (flow.descriptor.entry_stage !== "preflight" || flow.descriptor.terminal_stages.length !== 1 || flow.descriptor.terminal_stages[0] !== "report"
+            || flow.descriptor.stages.length !== stages.length || flow.descriptor.edges.length !== stages.length - 1
+            || flow.descriptor.stages.some((stage, index) => stage.id !== stages[index] || stage.directory !== `${String(index + 1).padStart(2, "0")}-${stage.id}`)
+            || stages.slice(0, -1).some((stage, index) => !flow.descriptor.edges.some(edge => edge.from === stage && edge.to === stages[index + 1] && edge.on === "accepted"))
+            || flow.descriptor.stages.some(stage => JSON.parse(flow.stageBlob(stage.id, "result_schema").toString("utf8")).$id !== "dd-flow/diagnostic-stage-result@1")) {
+            throw new AppError("flow_handler_scope_invalid", "Diagnostic handlers require their registered four-stage layout and result schema", 2, { phase: "prepare", effect: "no_effect" });
+        }
+    }
+    for (const stage of flow.descriptor.stages) {
+        const handlers = flow.descriptor.id === "sdlc" ? Object.values(sdlcStageHandlers) : flow.descriptor.id === "mb-init" ? Object.values(memoryInitStageHandlers)
+            : flow.descriptor.id === "mb-upgrade" ? Object.values(memoryUpgradeStageHandlers)
+                : diagnosticStageHandlers.filter(handler => handler.flowId === flow.descriptor.id);
+        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;
+}