@deksden-com/dd-flow-cli 0.9.0-beta.16 → 0.9.0-beta.161

package/dist/services/memory-ordinary-defaults.js

@@ -0,0 +1,129 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { isDeepStrictEqual } from "node:util";
+import { AppError } from "../shared/errors.js";
+import { readOperatorProfiles, resolveOperatorProfile } from "./operator-profiles.js";
+import { validateVnextExecutionProfile } from "./vnext-execution-profile.js";
+import { loadVnextWorkspacePolicy } from "./vnext-workspace-policy.js";
+import { readMemoryInitGitPolicy } from "./memory-init-git-policy.js";
+export const ordinaryConfigurationPaths = [".memory-bank/dd-flow/project-execution.json", ".memory-bank/dd-flow/project-workspace.json"];
+function gitObservation(context, workspace, args) {
+    const env = Object.fromEntries(Object.entries(context.env ?? process.env).filter(([key]) => !key.startsWith("GIT_")));
+    const result = spawnSync("git", ["-C", workspace, ...args], { env: { ...env, GIT_OPTIONAL_LOCKS: "0" }, encoding: "utf8", timeout: 10000, maxBuffer: 65536 });
+    return result.status === 0 ? result.stdout.trim() : null;
+}
+function retainedUnbornBranch(context, workspace, scope) {
+    if (!scope || scope.projectRoot !== workspace || scope.workspaceRoot !== workspace)
+        return null;
+    const policy = readMemoryInitGitPolicy(context, scope);
+    if (!policy || policy.initial_head !== null || policy.route !== "integration_branch_direct")
+        return null;
+    const git = (args) => gitObservation(context, workspace, args), common = git(["rev-parse", "--git-common-dir"]);
+    if (!common || fs.realpathSync(path.resolve(workspace, common)) !== policy.repository
+        || git(["symbolic-ref", "--quiet", "--short", "HEAD"]) !== policy.workspace_branch
+        || policy.workspace_branch !== policy.integration_branch || git(["rev-parse", "--verify", "HEAD"]) !== null
+        || git(["for-each-ref", "--format=%(refname)", "refs/heads/"]) !== "")
+        return null;
+    return policy.integration_branch;
+}
+/** Project-owned technical defaults only; never grants authority to a future task. */
+export function prepareMemoryOrdinaryDefaults(context, workspace, selectedProfile, scope, integrationBranch, targetFeatureBranchTemplate) {
+    const proposals = [], missing = [];
+    const existing = ordinaryConfigurationPaths.map(logical => fs.existsSync(path.join(workspace, logical)));
+    if (existing[0])
+        validateVnextExecutionProfile(JSON.parse(fs.readFileSync(path.join(workspace, ordinaryConfigurationPaths[0]), "utf8")));
+    if (existing[1])
+        loadVnextWorkspacePolicy(workspace);
+    if (!existing[0]) {
+        const settings = readOperatorProfiles(context.ddFlowHome);
+        let profile;
+        try {
+            profile = resolveOperatorProfile(settings, selectedProfile);
+        }
+        catch {
+            if (settings.default_profile)
+                profile = resolveOperatorProfile(settings);
+        }
+        if (!profile)
+            missing.push("configured ordinary executor profile");
+        else {
+            const value = { schema_id: "dd-flow/project-execution@3", stage_session_mode: "new_session", plan_review_mode: "auto", code_review_mode: "auto",
+                merge_mode: "server", merge_delivery: { strategy: "local" }, merge_cleanup: { source: "retain" }, stop_target: "merge_completed",
+                execution: { agent_profile_id: profile.id, delegation: { mode: "external", max_parallel: 1 } } };
+            validateVnextExecutionProfile(value);
+            proposals.push({ path: ordinaryConfigurationPaths[0], value });
+        }
+    }
+    let reason = "existing_valid_project_configuration";
+    if (!existing[1]) {
+        const git = (args) => gitObservation(context, workspace, args);
+        const remote = git(["symbolic-ref", "--quiet", "refs/remotes/origin/HEAD"]);
+        const branches = git(["for-each-ref", "--format=%(refname:short)", "refs/heads/"])?.split("\n").filter(Boolean) ?? [];
+        const unborn = !remote && !branches.length ? retainedUnbornBranch(context, workspace, scope) : null;
+        const remoteBranch = remote?.startsWith("refs/remotes/origin/") ? remote.slice("refs/remotes/origin/".length) : null;
+        // The Memory flow's retained explicit choice is also a technical default, not
+        // new merge/push authority. Existing ordinary configuration wins above.
+        const branch = integrationBranch ?? remoteBranch ?? (branches.length === 1 ? branches[0] : unborn);
+        reason = integrationBranch !== undefined ? "retained_explicit_integration_branch" : remoteBranch ? "verified_origin_head" : unborn ? "retained_unborn_init_branch_technical_default" : branch ? "verified_single_local_branch_technical_default" : "integration_branch_choice_required";
+        if (!branch || branch !== unborn && !git(["rev-parse", "--verify", `${integrationBranch === undefined && remoteBranch ? `refs/remotes/origin/${branch}` : `refs/heads/${branch}`}^{commit}`]))
+            missing.push("ordinary integration branch (multiple or unavailable candidates)");
+        else {
+            const contractFile = path.join(workspace, ".memory-bank/dd-flow/flow-contract.json");
+            const contract = fs.existsSync(contractFile) ? JSON.parse(fs.readFileSync(contractFile, "utf8")) : null;
+            const localTemplate = contract?.workspace?.feature_branch_template;
+            // Preserve compatible project routing; legacy PRT contracts use the
+            // retained upgrade target's default, not an unrelated local canon.
+            const template = typeof localTemplate === "string" && localTemplate.includes("<RUN>") ? localTemplate : targetFeatureBranchTemplate;
+            if (typeof template !== "string" || !template.includes("<RUN>"))
+                missing.push("ordinary feature branch template from selected flow contract");
+            else
+                proposals.push({ path: ordinaryConfigurationPaths[1], value: { schema_id: "dd-flow/project-workspace@1", workspace: {
+                            route: "feature_worktree", integration_branch: branch, feature_branch_template: template, provision_stage: "protocolize_start"
+                        } } });
+        }
+    }
+    return { proposals, preserved_paths: ordinaryConfigurationPaths.filter((_, index) => existing[index]), required_paths: ordinaryConfigurationPaths.filter((_, index) => !existing[index]), missing, reason };
+}
+/** Existing compose output custody selects these files; this checks their executable meaning. */
+export function assertMemoryOrdinaryConfigurationOutputs(context, workspace, defaults, artifacts, scope) {
+    for (const logical of defaults.required_paths)
+        if (!artifacts.some(artifact => artifact.root === "workspace" && artifact.path === logical)) {
+            throw new AppError("memory_stage_result_invalid", "Compose must retain each required ordinary configuration as an accepted Work output", 2, { phase: "prepare", effect: "no_effect", recoverable: true, reason: "ordinary_configuration_output_missing", path: logical });
+        }
+    const values = new Map(ordinaryConfigurationPaths.map(logical => [logical, JSON.parse(fs.readFileSync(path.join(workspace, logical), "utf8"))]));
+    const profile = validateVnextExecutionProfile(values.get(ordinaryConfigurationPaths[0]));
+    const policy = loadVnextWorkspacePolicy(workspace);
+    if (profile.execution)
+        resolveOperatorProfile(readOperatorProfiles(context.ddFlowHome), profile.execution.agent_profile_id);
+    for (const item of defaults.proposals)
+        if (!isDeepStrictEqual(values.get(item.path), item.value)) {
+            throw new AppError("memory_stage_result_invalid", "Compose changed supplied technical defaults", 2, { phase: "prepare", effect: "no_effect", reason: "ordinary_configuration_changed", path: item.path });
+        }
+    const branch = policy.workspace.integration_branch;
+    const exists = gitObservation(context, workspace, ["rev-parse", "--verify", `refs/heads/${branch}^{commit}`]);
+    const remote = exists ? null : gitObservation(context, workspace, ["rev-parse", "--verify", `refs/remotes/origin/${branch}^{commit}`]);
+    if (!exists && !remote && retainedUnbornBranch(context, workspace, scope) !== branch)
+        throw new AppError("memory_stage_result_invalid", "Ordinary integration branch is not an existing repository branch", 2, { phase: "prepare", effect: "no_effect", reason: "ordinary_integration_branch_unavailable" });
+}
+export function assertMemoryOrdinaryConfigurationCoverage(value, defaults) {
+    const plan = value;
+    if (plan.details?.works?.some(work => work.write_scopes.some(scope => scope.root === "workspace" && defaults.preserved_paths.includes(scope.path)))) {
+        throw new AppError("memory_stage_result_invalid", "Fresh init preserves valid existing ordinary configuration; remove that configuration write scope", 2, { phase: "prepare", effect: "no_effect", recoverable: true, reason: "existing_ordinary_configuration_write" });
+    }
+    for (const logical of defaults.required_paths)
+        if (!plan.details?.works?.some(work => work.unit_ids.length && work.write_scopes.some(scope => scope.root === "workspace" && scope.path === logical))) {
+            throw new AppError("memory_stage_result_invalid", "Compose must assign the missing ordinary configuration to a reviewed unit and an exact write scope", 2, { phase: "prepare", effect: "no_effect", recoverable: true, reason: "ordinary_configuration_unassigned", path: logical });
+        }
+}
+/** Upgrade must admit missing project-owned paths before its diff is immutable. */
+export function assertMemoryOrdinaryUpgradeConfigurationCoverage(value, defaults) {
+    const changes = value.details.path_map;
+    if (changes.some(change => change.action !== "retain" && [change.from, change.to].some(path => path !== null && defaults.preserved_paths.includes(path)))) {
+        throw new AppError("memory_stage_result_invalid", "Upgrade preserves valid existing ordinary configuration", 2, { phase: "prepare", effect: "no_effect", recoverable: true, reason: "existing_ordinary_configuration_write" });
+    }
+    for (const logical of defaults.required_paths)
+        if (!changes.some(change => change.from === null && change.to === logical && change.ownership === "project" && change.action === "add")) {
+            throw new AppError("memory_stage_result_invalid", "Upgrade analysis must assign each missing ordinary configuration as an exact project-owned addition", 2, { phase: "prepare", effect: "no_effect", recoverable: true, reason: "ordinary_configuration_unassigned", path: logical });
+        }
+}

package/dist/services/memory-preflight-bootstrap-custody.js

@@ -0,0 +1,115 @@
+import { AppError } from "../shared/errors.js";
+import { FrozenGenericExecution } from "./generic-execution.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { readMemoryInitBootstrapReadiness } from "./memory-init-bootstrap-readiness.js";
+import { PreparedMemoryStageResult } from "./memory-stage-results.js";
+import { PreparedMemoryInitProjectBootstrap } from "./memory-init-project-bootstrap.js";
+import { PreparedMemoryInitBootstrapReadiness } from "./memory-init-bootstrap-readiness.js";
+import { AdmittedFrozenEngine } from "./frozen-engine.js";
+import { observeMemoryInitSourceInventory } from "./memory-init-preflight.js";
+import { RetainedExecutionBundle } from "./execution-bundles.js";
+function refuse(reason) {
+    throw new AppError("memory_preflight_bootstrap_custody_invalid", "Preflight does not consume its independently accepted bootstrap", 2, { reason, effect: "no_effect" });
+}
+/** Bootstrap-specific admission for the productive preflight handler. Result
+ * schema, RUN/input identity, physical revalidation and coordinator settlement
+ * remain separate handler obligations; this is not stage completion authority.
+ */
+export class PreparedMemoryPreflightBootstrapCustody {
+    #scope;
+    #authoritySha256;
+    #resultSha256;
+    #physical = null;
+    #semanticScope;
+    constructor(scope, authoritySha256, resultSha256, semanticScope) {
+        this.#scope = { ...scope };
+        this.#authoritySha256 = authoritySha256;
+        this.#resultSha256 = resultSha256;
+        this.#semanticScope = semanticScope;
+        Object.freeze(this);
+    }
+    static prepare(context, input) {
+        if (!(input.execution instanceof FrozenGenericExecution) || !(input.result instanceof PreparedMemoryStageResult)
+            || input.execution.settings.flow_id !== "mb-init")
+            refuse("unprepared_preflight");
+        const frozen = input.execution.snapshot();
+        const scope = { requestId: frozen.scope.requestId, projectRoot: frozen.scope.projectRoot, workspaceRoot: frozen.scope.workspace };
+        const accepted = readMemoryInitBootstrapReadiness(context, scope);
+        if (!accepted || accepted.authority.binding.execution_sha256 !== input.execution.sha256)
+            refuse("missing_or_foreign_bootstrap");
+        const result = input.result.value(), details = result.details;
+        if (result.stage !== "preflight" || result.schema_id !== "dd-flow/mb-init-preflight-result@1")
+            refuse("foreign_stage");
+        const semanticScope = details.semantic_scope;
+        if (typeof semanticScope !== "string" || !semanticScope.trim() || Buffer.byteLength(semanticScope) > 16384 || semanticScope.includes("\0"))
+            refuse("invalid_semantic_scope");
+        return new PreparedMemoryPreflightBootstrapCustody(scope, hybridDigest(accepted.authority), input.result.sha256, semanticScope);
+    }
+    /** Productive preparation additionally restores the request-owned bootstrap
+     * and rechecks its physical prerequisites. No publication or model probe is
+     * dispatched. Result/RUN input and invoking assertBundleReference remain
+     * obligations of the registered stage handler, not this bootstrap fence.
+     */
+    static preparePhysical(context, input) {
+        if (!(input.engine instanceof AdmittedFrozenEngine))
+            refuse("selected_engine_not_admitted");
+        const prepared = PreparedMemoryPreflightBootstrapCustody.prepare(context, input);
+        const bootstrap = PreparedMemoryInitProjectBootstrap.restore(context, input.execution);
+        PreparedMemoryInitBootstrapReadiness.prepare(context, { bootstrap, engine: input.engine });
+        const inventory = prepared.observeInventory(context);
+        prepared.assertCustody(context);
+        prepared.#physical = { bootstrap, engine: input.engine, inventorySha256: inventory.sha256 };
+        return prepared;
+    }
+    /** Outside writers: recheck current root/source/tools/pack/engine/storage.
+     * The acceptance writer uses assertCustody only, with no filesystem access.
+     */
+    revalidate(context) {
+        if (!this.#physical)
+            refuse("physical_preparation_required");
+        PreparedMemoryInitBootstrapReadiness.prepare(context, this.#physical);
+        if (this.observeInventory(context).sha256 !== this.#physical.inventorySha256)
+            refuse("preserved_inventory_changed");
+        this.assertCustody(context);
+    }
+    /** SQL-only fence for the handler's eventual atomic acceptance writer. */
+    assertCustody(context) {
+        const accepted = readMemoryInitBootstrapReadiness(context, this.#scope);
+        if (!accepted || hybridDigest(accepted.authority) !== this.#authoritySha256)
+            refuse("bootstrap_changed_after_preparation");
+    }
+    /** Exact manifest reference, not merely a same-hash path supplied by an agent.
+     * RUN/input identity is separately fenced by its prepared result binding and
+     * descriptor settlement; this method alone is not RUN execution authority.
+     */
+    assertBundleReference(context, bundle, result) {
+        if (!(bundle instanceof RetainedExecutionBundle) || !(result instanceof PreparedMemoryStageResult))
+            refuse("unprepared_bundle_reference");
+        context.db.readSnapshot(() => {
+            this.assertCustody(context);
+            const frozen = bundle.execution.snapshot(), accepted = readMemoryInitBootstrapReadiness(context, this.#scope);
+            if (!accepted)
+                refuse("missing_or_foreign_bootstrap");
+            const value = result.value(), details = value.details;
+            if (bundle.descriptor.descriptor.id !== "mb-init" || bundle.execution.sha256 !== accepted.authority.binding.execution_sha256
+                || frozen.scope.requestId !== this.#scope.requestId || frozen.scope.projectRoot !== this.#scope.projectRoot || frozen.scope.workspace !== this.#scope.workspaceRoot
+                || value.stage !== "preflight" || value.run_id !== bundle.manifest.run_id
+                || bundle.manifest.bootstrap_receipts.length !== 1
+                || bundle.manifest.bootstrap_receipts[0].sha256 !== accepted.authority.bootstrap_sha256
+                || !bundle.blob(bundle.manifest.bootstrap_receipts[0].path).equals(Buffer.from(JSON.stringify(accepted.authority.receipt))))
+                refuse("foreign_bundle_bootstrap_reference");
+            if (details.semantic_scope !== this.#semanticScope)
+                refuse("foreign_preflight_semantic_scope");
+            // Bootstrap/physical preparation belongs to the exact result that was
+            // checked, not another schema-valid result with the same selected fields.
+            if (result.sha256 !== this.#resultSha256)
+                refuse("preflight_result_changed_after_preparation");
+        });
+    }
+    observeInventory(context) {
+        const accepted = readMemoryInitBootstrapReadiness(context, this.#scope);
+        if (!accepted)
+            refuse("missing_or_foreign_bootstrap");
+        return observeMemoryInitSourceInventory(accepted.authority.binding.target, accepted.authority.receipt.baseline_sha256, context.env);
+    }
+}

package/dist/services/memory-preflight-handler.js

@@ -0,0 +1,274 @@
+import { AppError } from "../shared/errors.js";
+import { RetainedExecutionBundle } from "./execution-bundles.js";
+import { PreparedMemoryStageResult } from "./memory-stage-results.js";
+import { PreparedMemoryPreflightBootstrapCustody } from "./memory-preflight-bootstrap-custody.js";
+import { PreparedMemoryBaselinePreservation } from "./memory-baseline-preservation.js";
+import { PreparedMemoryResultBinding } from "./memory-result-binding.js";
+import { ObservedMemorySources } from "./memory-source-observations.js";
+import { memorySourceKey } from "./memory-stage-results.js";
+import { readMemoryInitBootstrapReadiness } from "./memory-init-bootstrap-readiness.js";
+import { observeMemoryInitSourceInventory } from "./memory-init-preflight.js";
+import { readMemoryInitProjectBootstrap } from "./memory-init-project-bootstrap.js";
+import { readPublishedMemoryReferenceInventory } from "./memory-layer-publication.js";
+import path from "node:path";
+import { PreparedDescriptorStageStart } from "./descriptor-stage-start.js";
+import { PreparedDescriptorStageCoordinator, readDescriptorStageInput } from "./descriptor-stage-coordinator.js";
+import { PreparedDescriptorStageSettlement } from "./descriptor-stage-settlement.js";
+import { assertPreparedRunBundleSqlAuthority, readFlowRunExecutionBundle } from "./runs.js";
+import { requireProjectByRoot } from "./projects.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { readAcceptedStageData } from "./stage-report-renderer.js";
+import { readMemoryCompositionRegistration } from "./memory-composition-registration.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { captureMemoryUpgradeSources } from "./memory-upgrade-analysis-handler.js";
+function refuse(reason) {
+    throw new AppError("memory_preflight_handler_invalid", "Memory preflight cannot accept this execution or result", 2, { reason, effect: "no_effect" });
+}
+function bounded(bytes, empty = false) {
+    if (!(bytes instanceof Uint8Array) || bytes.length > 1024 * 1024 || !empty && !bytes.length)
+        refuse("invalid_result_bytes");
+}
+function selected(context, input) {
+    const bundle = readFlowRunExecutionBundle(context, input);
+    if (!bundle || bundle.descriptor.descriptor.id !== "mb-init" || bundle.descriptor.descriptor.entry_stage !== "preflight")
+        refuse("registered_memory_bundle_required");
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const scope = { projectId: project.id, runId: input.runId, stage: "preflight" };
+    const run = assertPreparedRunBundleSqlAuthority(context, scope, bundle);
+    const stage = JSON.parse(run.index_json).stage_runs.find((entry) => entry.stage === "preflight");
+    return { bundle, scope, accepted: stage?.status === "done" };
+}
+/** Proposed references select a subset, never establish the source allowlist.
+ * Only regular files in the independently restored bootstrap baseline may be
+ * preflight project evidence. Ignored/private, linked, runtime and canon paths
+ * are not silently read as project truth. Their other proof roles are separate.
+ */
+export function captureMemoryPreflightSources(context, bundle, bytes) {
+    return captureSources(context, bundle, bytes).sources;
+}
+/** Historical blueprint support comes only from the independently registered
+ * graph. It is not a current output observation or a caller-supplied allowlist. */
+export function captureRegisteredMemoryCompositionSources(context, bundle, registrationScope) {
+    const registration = readMemoryCompositionRegistration(context, registrationScope);
+    if (registration.run_id !== bundle.manifest.run_id || registration.execution_sha256 !== bundle.execution.sha256)
+        refuse("foreign_composition_registration");
+    if (bundle.descriptor.descriptor.id === "mb-upgrade") {
+        const blueprint = JSON.parse(Buffer.from(registration.result_base64, "base64").toString("utf8"));
+        const historical = new Map();
+        // Only restoring the independently registered blueprint. Its initial
+        // artifact references are not freshly produced Work or current outputs;
+        // final acceptance selects those independently from settled SQL results.
+        for (const unit of blueprint.units) {
+            for (const artifact of unit.artifacts)
+                historical.set(`${artifact.root}\0${artifact.path}`, artifact.sha256);
+            unit.artifacts = [];
+        }
+        return { sources: captureMemoryUpgradeSources(context, bundle, registrationScope.stage, Buffer.from(JSON.stringify(blueprint))),
+            historical, registrationSha256: hybridDigest(registration), inputSha256: registration.input_sha256 };
+    }
+    return { ...captureSources(context, bundle, Buffer.from(registration.result_base64, "base64"), true),
+        registrationSha256: hybridDigest(registration), inputSha256: registration.input_sha256 };
+}
+function captureSources(context, bundle, bytes, registeredBlueprint = false) {
+    bounded(bytes);
+    if (!(bundle instanceof RetainedExecutionBundle) || bundle.descriptor.descriptor.id !== "mb-init")
+        refuse("prepared_memory_bundle_required");
+    const preservation = PreparedMemoryBaselinePreservation.prepare(context, bundle.execution), scope = bundle.execution.snapshot().scope;
+    const ready = readMemoryInitBootstrapReadiness(context, { requestId: scope.requestId, projectRoot: scope.projectRoot, workspaceRoot: scope.workspace });
+    if (!ready || ready.authority.binding.execution_sha256 !== bundle.execution.sha256)
+        refuse("accepted_bootstrap_required");
+    const inventory = observeMemoryInitSourceInventory(ready.authority.binding.target, ready.authority.receipt.baseline_sha256, context.env);
+    const allowed = new Map(inventory.entries.filter(entry => entry.kind === "file").map(entry => [entry.path, entry.sha256]));
+    let value;
+    try {
+        value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        refuse("invalid_result_json");
+    }
+    const registered = readMemoryInitProjectBootstrap(context, ready.authority.binding.scope);
+    if (!registered)
+        refuse("accepted_bootstrap_required");
+    const owned = readPublishedMemoryReferenceInventory(context.ddFlowHome, { ...ready.authority.binding.scope,
+        targetSha256: registered.receipt.target_sha256, layerSha256: registered.receipt.layer_sha256,
+        packSha256: ready.authority.binding.pack_sha256, installationSha256: ready.authority.binding.installation_manifest_sha256 }, ready.authority.binding.target, registered.receipt.layer_publication_sha256, registered.receipt.draft_identity_sha256);
+    const receipts = new Map(bundle.manifest.bootstrap_receipts.map(ref => [`execution-bundle/${ref.path}`, ref.sha256]));
+    for (const ref of ready.authority.evidence) {
+        const selected = bundle.manifest.inventory.find(item => item.path === ref.path && item.sha256 === ref.sha256);
+        if (selected)
+            receipts.set(`execution-bundle/${ref.path}`, ref.sha256);
+    }
+    let run = null;
+    const acceptedReferences = new Map();
+    const selectRun = () => run ??= assertPreparedRunBundleSqlAuthority(context, { projectId: ready.projectId, runId: bundle.manifest.run_id }, bundle);
+    let selectedAccepted = false;
+    const rejectProposal = (reason, reference, message) => {
+        const proposal = value;
+        if (registeredBlueprint || proposal.run_id !== bundle.manifest.run_id || typeof proposal.stage !== "string" || typeof proposal.input_sha256 !== "string")
+            refuse("unselected_preflight_source");
+        const index = JSON.parse(selectRun().index_json), stage = index.stage_runs.find((stage) => stage.stage === proposal.stage);
+        if (index.current_stage !== proposal.stage || stage?.status !== "running" || stage.input_sha256 !== proposal.input_sha256)
+            refuse("unselected_preflight_source");
+        throw new AppError("memory_preflight_handler_invalid", message, 2, { reason, ...reference, phase: "prepare", effect: "no_effect", recoverable: true });
+    };
+    const proposedMismatches = [];
+    const pending = [{ value, role: "source", original: false }], locations = new Map(), expected = new Map(), historical = new Map();
+    let nodes = 0;
+    while (pending.length) {
+        if (++nodes > 100000)
+            refuse("result_tree_exceeds_bound");
+        const entry = pending.pop(), node = entry.value;
+        if (Array.isArray(node)) {
+            for (const child of node)
+                pending.push({ ...entry, value: child });
+            continue;
+        }
+        if (!node || typeof node !== "object")
+            continue;
+        const record = node;
+        if (typeof record.root === "string" && typeof record.path === "string" && typeof record.sha256 === "string") {
+            let selected;
+            if (["project", "workspace"].includes(record.root)) {
+                selected = allowed.get(record.path) ?? undefined;
+                if (!entry.original && ["evidence", "artifacts"].includes(entry.role))
+                    selected ??= owned.artifacts.get(record.path);
+            }
+            else if (!entry.original && (entry.role === "evidence" || entry.role === "artifacts")) {
+                if (record.root === "run") {
+                    selected = receipts.get(record.path);
+                    if (selected === undefined) {
+                        if (!selectedAccepted) {
+                            let stage = value.stage;
+                            const declared = bundle.descriptor.descriptor.stages.find(item => item.id === stage);
+                            if (!declared)
+                                refuse("unselected_preflight_source");
+                            selectedAccepted = true;
+                            const index = JSON.parse(selectRun().index_json);
+                            const acceptedStage = index.stage_runs?.some((item) => item.stage === stage && item.status === "done");
+                            if (acceptedStage)
+                                readAcceptedStageData(context, { projectId: ready.projectId, runId: bundle.manifest.run_id, stage: declared.id });
+                            if (index.current_stage === stage || acceptedStage) {
+                                const input = readDescriptorStageInput(context, { projectId: ready.projectId, runId: bundle.manifest.run_id, stage: declared.id }, bundle, true, acceptedStage);
+                                acceptedReferences.set(`${declared.directory}/stage-input.json`, input.inputSha256);
+                            }
+                            const visited = new Set();
+                            while (stage && !visited.has(stage)) {
+                                visited.add(stage);
+                                stage = bundle.descriptor.descriptor.edges.find(edge => edge.to === stage && edge.on === "accepted")?.from;
+                                if (stage && index.stage_runs?.some((item) => item.stage === stage && item.status === "done")) {
+                                    const accepted = readAcceptedStageData(context, { projectId: ready.projectId, runId: bundle.manifest.run_id, stage });
+                                    const result = JSON.parse(accepted.bytes.toString("utf8"));
+                                    if (result.schema_id !== `dd-flow/mb-init-${stage}-result@1` || result.run_id !== bundle.manifest.run_id
+                                        || result.stage !== stage || !(result.outcome === "accepted" || stage === "verify" && result.outcome === "needs_repair" && bundle.descriptor.successor("verify", "needs_repair") === "review"))
+                                        refuse("unselected_preflight_source");
+                                    acceptedReferences.set(accepted.result.path, accepted.result.sha256);
+                                    const input = readDescriptorStageInput(context, { projectId: ready.projectId, runId: bundle.manifest.run_id, stage }, bundle, true, true);
+                                    acceptedReferences.set(`${bundle.descriptor.stage(stage).directory}/stage-input.json`, input.inputSha256);
+                                }
+                            }
+                        }
+                        selected = acceptedReferences.get(record.path);
+                    }
+                }
+                if (record.root === "canon")
+                    selected = owned.canon.get(record.path);
+            }
+            if (selected === undefined)
+                return rejectProposal("unselected_preflight_source", { root: record.root, path: record.path }, "Remove or replace this unselected reference with an admitted project source, preflight result or Stage input; Git metadata is not project source evidence");
+            if (selected !== record.sha256) {
+                if (registeredBlueprint)
+                    refuse("registered_source_sha256_mismatch");
+                proposedMismatches.push({ root: record.root, path: record.path });
+            }
+            const key = memorySourceKey(record.root, record.path);
+            if (registeredBlueprint && !entry.original && ["evidence", "artifacts"].includes(entry.role)
+                && ["project", "workspace"].includes(record.root) && !allowed.has(record.path) && owned.artifacts.get(record.path) === selected) {
+                historical.set(key, selected);
+            }
+            else {
+                expected.set(key, selected);
+                locations.set(key, { root: record.root, path: record.path });
+            }
+        }
+        for (const [key, child] of Object.entries(record))
+            pending.push({ value: child, role: ["evidence", "artifacts"].includes(key) ? key : entry.role,
+                original: entry.original || key === "inventory" });
+    }
+    const selectedRun = [...locations.values()].some(location => location.root === "run") ? selectRun() : null;
+    const observation = ObservedMemorySources.capture({ project: scope.projectRoot, workspace: scope.workspace,
+        canon: path.join(scope.workspace, ".memory-bank"), ...(selectedRun ? { run: selectedRun.run_root ?? selectedRun.run_dir } : {}) }, [...locations.values()]);
+    const hashes = observation.hashes();
+    for (const [key, sha256] of expected)
+        if (hashes.get(key) !== sha256)
+            refuse("preflight_source_changed");
+    preservation.assertCustody(context);
+    if (proposedMismatches.length) {
+        rejectProposal("proposed_source_sha256_mismatch", proposedMismatches[0], "Proposed evidence SHA differs from the CLI-selected source; correct the result reference without changing the source");
+    }
+    return { sources: observation, historical };
+}
+/** The bootstrap-specific acceptance part of the preflight handler. It does
+ * not establish RUN/input/coordinator authority; finishMemoryPreflight supplies
+ * those independently. Kept separate for actual bootstrap qualification.
+ */
+export class PreparedMemoryPreflightAcceptance {
+    #bundle;
+    #result;
+    #bootstrap;
+    constructor(bundle, result, bootstrap) {
+        this.#bundle = bundle;
+        this.#result = result;
+        this.#bootstrap = bootstrap;
+        Object.freeze(this);
+    }
+    static prepare(context, input) {
+        if (!(input.bundle instanceof RetainedExecutionBundle) || !(input.result instanceof PreparedMemoryStageResult))
+            refuse("prepared_bundle_and_result_required");
+        const value = JSON.parse(input.result.bytes().toString("utf8"));
+        // Preliminary units/minor findings are allowed by the frozen contract;
+        // DISCOVER establishes final inventory. Material blockers cannot advance.
+        if (value.stage !== "preflight" || value.outcome !== "accepted"
+            || value.findings.some((finding) => finding.severity !== "minor" && finding.status !== "resolved"))
+            refuse("preflight_not_accepted");
+        const bootstrap = PreparedMemoryPreflightBootstrapCustody.preparePhysical(context, { execution: input.bundle.execution, result: input.result, engine: input.bundle.engine() });
+        const prepared = new PreparedMemoryPreflightAcceptance(input.bundle, input.result, bootstrap);
+        prepared.assertCustody(context);
+        return prepared;
+    }
+    revalidate(context) { this.#bootstrap.revalidate(context); this.assertCustody(context); }
+    assertCustody(context) { this.#bootstrap.assertBundleReference(context, this.#bundle, this.#result); }
+}
+/** Handler implementation awaiting the complete memory-handler registry. No
+ * RUN allocation, profile mutation, installation fallback or provider dispatch.
+ * Returns the retained prompt for the controller's separately fenced dispatch.
+ */
+export function startMemoryPreflight(context, input) {
+    bounded(input.bytes, true);
+    const { bundle, accepted } = selected(context, input);
+    if (accepted)
+        refuse("use_accepted_finish_replay");
+    const preservation = PreparedMemoryBaselinePreservation.prepare(context, bundle.execution);
+    const start = PreparedDescriptorStageStart.prepare(context, { ...input, stage: "preflight" });
+    preservation.revalidate(context);
+    const stage = start.apply(context, writer => preservation.assertCustody(writer));
+    const coordinator = PreparedDescriptorStageCoordinator.prepare(context, { ...input, stage: "preflight" });
+    preservation.revalidate(context);
+    const work = coordinator.apply(context, writer => preservation.assertCustody(writer));
+    return { ...stage, ...work };
+}
+export function finishMemoryPreflight(context, input) {
+    bounded(input.bytes);
+    const { bundle, scope, accepted } = selected(context, input);
+    const sources = captureMemoryPreflightSources(context, bundle, input.bytes);
+    const binding = PreparedMemoryResultBinding.prepare(context, { ...scope, flow: bundle.descriptor, execution: bundle.execution, bundle,
+        sources, acceptedReplay: accepted });
+    const replay = binding.acceptedBytes();
+    if (replay && !replay.equals(input.bytes))
+        refuse("accepted_result_changed");
+    const result = PreparedMemoryStageResult.prepare(input.bytes, bundle.descriptor, binding.binding());
+    const acceptance = PreparedMemoryPreflightAcceptance.prepare(context, { bundle, result });
+    const settlement = PreparedDescriptorStageSettlement.prepare(context, { ...input, stage: "preflight", bytes: result.bytes() });
+    binding.revalidate(context);
+    acceptance.revalidate(context);
+    return settlement.apply(context, writer => { binding.assertCustody(writer); acceptance.assertCustody(writer); });
+}