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

package/dist/services/memory-upgrade-selection.js

@@ -0,0 +1,430 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { AppError, errorRecord } from "../shared/errors.js";
+import { assertImportAdmission } from "../storage/import-guard.js";
+import { publishImmutableInput } from "../storage/immutable-input.js";
+import { captureMemoryUpgradeRequestCandidate, readMemoryUpgradeRequestCandidate } from "./memory-init-request-candidate.js";
+import { readMemoryUpgradeRequestInput } from "./memory-init-request-input.js";
+import { PreparedInstalledFlowSource } from "./installed-flow-source.js";
+import { PreparedMemoryLayer } from "./memory-layer.js";
+import { FrozenGenericExecution } from "./generic-execution.js";
+import { ResolvedFlowDescriptor } from "./flow-descriptors.js";
+import { readOperatorProfiles } from "./operator-profiles.js";
+import { AdmittedFrozenEngine } from "./frozen-engine.js";
+import { prepareMemoryInitEngineRelease, revalidateMemoryInitEngineRelease, selectMemoryInitInstalledEngine } from "./memory-init-engine-release.js";
+import { prepareMemoryUpgradeInventory, captureUpgradePreservationBaseline, readUpgradePreservationBaseline, captureUpgradeProjectLinks } from "./memory-upgrade-inventory.js";
+import { getProjectVersionStatus } from "./version-status.js";
+import { observeDescriptorWorkspace } from "./descriptor-run-start.js";
+import { readBoundedReleaseFile } from "./release-source.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { adjacentMigrationChain, readImpacts } from "./migrations.js";
+import { readSetupStatus } from "./setup.js";
+import { inspectMemoryGitExecutable } from "./memory-init-preflight.js";
+import { parseDocument } from "yaml";
+import semver from "semver";
+import { observeMemoryGitPolicySelection } from "./memory-init-git-policy.js";
+import { captureUpgradeProjectFiles, readUpgradeProjectFiles } from "./memory-upgrade-inventory.js";
+// ponytail: one bounded immutable record, like startup@3; split blobs only if
+// real canonical packs outgrow the existing 64 MiB startup-input ceiling.
+const limit = 64 * 1024 * 1024;
+const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
+function refuse(reason) {
+    throw new AppError("memory_upgrade_selection_invalid", "Upgrade requires its original resolved selection", 1, { reason, effect: "no_effect", next_action: "reconcile_exact_request" });
+}
+function exists(file) {
+    try {
+        fs.lstatSync(file);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+/** Data admission only. These fixed declaration names do not register code.
+ * RUN/bootstrap must still admit the actual selected engine's handler registry. */
+function descriptorData(source) {
+    const reference = source.descriptorReference();
+    if (reference.path !== "mb-upgrade/flow-descriptor.json")
+        refuse("foreign_flow");
+    const blobs = source.blobs(), flow = ResolvedFlowDescriptor.admit(blobs.get(reference.path), reference.sha256, {
+        blobs, entryHandlers: new Set(["memory-upgrade-stage-entry"]), finishHandlers: new Set(["memory-upgrade-stage-finish"])
+    });
+    const stages = ["preflight", "diff-analysis", "upgrade", "verify", "review", "finish"];
+    if (flow.descriptor.id !== "mb-upgrade" || flow.descriptor.entry_stage !== "preflight"
+        || flow.descriptor.stages.length !== stages.length || flow.descriptor.stages.some((stage, i) => stage.id !== stages[i]))
+        refuse("foreign_flow_layout");
+    return flow;
+}
+function files(input, baseline = false) {
+    if (!input || !Array.isArray(input.files) || input.files.length > 20_000)
+        refuse("invalid_layer");
+    const entries = new Map();
+    for (const entry of input.files) {
+        if (!entry || Object.keys(entry).sort().join() !== "base64,path" || typeof entry.base64 !== "string"
+            || entry.base64.length > 2 * 1024 * 1024 || entries.has(entry.path))
+            refuse("invalid_layer");
+        const bytes = Buffer.from(entry.base64, "base64");
+        if (bytes.toString("base64") !== entry.base64)
+            refuse("invalid_layer");
+        entries.set(entry.path, bytes);
+    }
+    return PreparedMemoryLayer.restoreRetained(entries, input.sha256, input.installation_sha256, baseline);
+}
+function current(home, scope, layer, env, baselineInstallationSha256, gitExecutable, includeProjectLinks = true, includeProjectFiles = true) {
+    const workspace = observeDescriptorWorkspace({ env }, scope.projectRoot, scope.workspaceRoot, gitExecutable);
+    let inventory = prepareMemoryUpgradeInventory(scope.workspaceRoot, layer);
+    const status = getProjectVersionStatus({ projectRoot: scope.workspaceRoot, rootSource: "explicit", canon: null });
+    const missingMarker = status?.memory_bank.status === "unknown" && status.memory_bank.reason === "memory_bank_version_missing"
+        || status?.memory_bank.source === ".memory-bank/mbb/index.md";
+    const canonVersion = missingMarker ? status?.flow_pack.canon_version_at_source_commit : status?.memory_bank.version;
+    const packVersion = status?.flow_pack.canon_version_at_source_commit;
+    if (!status || status.memory_bank.status !== "present" && !missingMarker || status.flow_pack.status !== "present" || !canonVersion
+        || !packVersion || semver.valid(canonVersion) !== canonVersion || semver.valid(packVersion) !== packVersion
+        || semver.gt(canonVersion, packVersion) || !/^[a-f0-9]{40}$/.test(status.flow_pack.source_commit ?? ""))
+        refuse("invalid_current_provenance");
+    const versionPath = missingMarker ? "index.md" : status.memory_bank.source?.replace(/^\.memory-bank\//, "");
+    if (typeof versionPath !== "string" || !inventory.inventory.entries.some(entry => entry.path === versionPath && entry.current?.kind === "file"))
+        refuse("unowned_version_source");
+    const manifest = readBoundedReleaseFile(inventory.inventory.current_manifest.path, 1024 * 1024);
+    if (hash(manifest) !== inventory.inventory.current_manifest.sha256)
+        refuse("current_changed");
+    const declared = JSON.parse(manifest.toString("utf8"));
+    if (declared.canon_version_at_source_commit !== packVersion || declared.source_commit !== status.flow_pack.source_commit)
+        refuse("current_changed");
+    const baseline = baselineInstallationSha256 === null ? null : PreparedMemoryLayer.fromCommittedCanon(home, declared, baselineInstallationSha256);
+    if (missingMarker) {
+        // Older real init outputs omitted this project marker. Their independently
+        // installed old canon, not mutable manifest text alone, supplies provenance.
+        const index = readBoundedReleaseFile(path.join(scope.workspaceRoot, ".memory-bank", versionPath), 1024 * 1024).toString("utf8");
+        const frontmatter = index.match(/^---\n([\s\S]*?)\n---(?:\n|$)/);
+        const document = frontmatter ? parseDocument(frontmatter[1]) : null;
+        if (!baseline || !document || document.errors.length || document.has("memory_bank_version"))
+            refuse("missing_version_marker_requires_canonical_baseline");
+        if (status.memory_bank.version && status.memory_bank.version !== canonVersion) {
+            // Canonical guidance historically carried stale prose version labels.
+            // Ignore that fallback only when it is the exact authenticated old guide;
+            // a divergent local version claim is an explicit conflict, not legacy.
+            const guide = inventory.inventory.entries.find(entry => entry.path === "mbb/index.md")?.current;
+            const original = baseline.files().get("mbb/index.md");
+            if (!original || guide?.kind !== "file" || guide.sha256 !== hash(original))
+                refuse("legacy_guidance_version_diverged");
+        }
+    }
+    if (baseline)
+        inventory = prepareMemoryUpgradeInventory(scope.workspaceRoot, layer, baseline);
+    const projectLinks = includeProjectLinks ? captureUpgradeProjectLinks(scope.workspaceRoot, gitExecutable ?? "git", env) : [];
+    return { workspace, current: { canon_version: canonVersion, source_commit: status.flow_pack.source_commit,
+            ...(includeProjectFiles ? { project_files: captureUpgradeProjectFiles(scope.workspaceRoot, gitExecutable ?? "git", env) } : {}),
+            ...(projectLinks.length ? { project_links: projectLinks } : {}),
+            ...(canonVersion !== packVersion ? { flow_pack_canon_version: packVersion } : {}),
+            manifest_base64: manifest.toString("base64"), version_source: versionPath, inventory, old_tree: captureUpgradePreservationBaseline(inventory),
+            ...(baseline ? { baseline_layer: { sha256: baseline.sha256, installation_sha256: baseline.installationSha256,
+                    files: [...baseline.files()].map(([logical, bytes]) => ({ path: logical, base64: bytes.toString("base64") })) } } : {}) } };
+}
+function paths(candidate) {
+    const root = path.dirname(candidate.retain().file);
+    return { payload: path.join(root, "resolved-selection.json"), receipt: path.join(root, "resolved-selection.receipt.json") };
+}
+function impacts(layer, sourceVersion, targetVersion) {
+    const manifest = JSON.parse(layer.files().get("dd-flow/manifest.json").toString("utf8"));
+    const entries = readImpacts(path.join(manifest.canon_memory_bank_root, "release-impact"));
+    return { chain: adjacentMigrationChain(sourceVersion, targetVersion, entries),
+        files: entries.map(entry => {
+            const reference = entry.source_reference;
+            const content = readBoundedReleaseFile(reference.path, 1024 * 1024);
+            if (hash(content) !== reference.sha256)
+                refuse("impact_changed");
+            return { ...reference, base64: content.toString("base64") };
+        }) };
+}
+function assertMixedCurrentContext(current, impact) {
+    const pack = current.flow_pack_canon_version;
+    if (pack === undefined)
+        return;
+    // An independently updated process pack is a real intermediate node, not
+    // permission to invent a migration hop or to claim the MB already upgraded.
+    if (semver.valid(current.canon_version) !== current.canon_version || semver.valid(pack) !== pack
+        || !semver.lt(current.canon_version, pack) || impact.chain.status !== "ok"
+        || !impact.chain.steps.some(step => step.to === pack))
+        refuse("invalid_mixed_current_context");
+}
+/** Historical input custody only. No current project/cache/profile or engine
+ * code is inspected; actual input restoration is a separate operation below. */
+export function readMemoryUpgradeSelection(home, scope) {
+    const original = readMemoryUpgradeRequestCandidate(home, scope);
+    if (!original)
+        return null;
+    const locations = paths(original.candidate), hasPayload = exists(locations.payload), hasReceipt = exists(locations.receipt);
+    if (!hasPayload && !hasReceipt)
+        return null;
+    if (!hasPayload || !hasReceipt)
+        refuse("selection_custody_missing");
+    try {
+        const bytes = readBoundedReleaseFile(locations.payload, limit), sha256 = hash(bytes);
+        const receipt = JSON.parse(readBoundedReleaseFile(locations.receipt, 16 * 1024).toString("utf8"));
+        const requestSha256 = hybridDigest(original.input);
+        if (hybridDigest(receipt) !== hybridDigest({ schema_id: "dd-flow/memory-upgrade-selection-receipt@1", scope,
+            request_input_sha256: requestSha256, selection_sha256: sha256 }))
+            refuse("selection_bytes_changed");
+        return { ...decodeMemoryUpgradeSelection(bytes, sha256, original.input, scope), original, bytes };
+    }
+    catch (error) {
+        if (error instanceof AppError)
+            throw error;
+        return refuse("invalid_retained_selection");
+    }
+}
+/** SQL-safe data decoding for accepted custody/recovery. No filesystem, current
+ * defaults, engine registry, storage probe or provider is consulted here. */
+export function decodeMemoryUpgradeSelection(bytes, expectedSha256, input, scope) {
+    try {
+        if (bytes.byteLength > limit || hash(bytes) !== expectedSha256)
+            refuse("selection_bytes_changed");
+        const objective = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(Buffer.from(input.intake_base64, "base64"));
+        const raw = readMemoryUpgradeRequestInput(input, scope, objective).selection;
+        const payload = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+        if (!payload || Object.keys(payload).filter(key => key !== "git").sort().join() !== "current,engine,execution,impact,layer,release,request_input_sha256,schema_id,scope,source,workspace"
+            || payload.schema_id !== "dd-flow/memory-upgrade-selection@1" || hybridDigest(payload.scope) !== hybridDigest(scope)
+            || payload.request_input_sha256 !== hybridDigest(input))
+            refuse("foreign_selection");
+        if (payload.git !== undefined) {
+            const { executable, probe, policy } = payload.git;
+            if (Object.keys(payload.git).sort().join() !== "executable,policy,probe"
+                || typeof executable !== "string" || !path.isAbsolute(executable)
+                || !probe || Object.keys(probe).sort().join() !== "executable_sha256,stderr_sha256,stdout_sha256,version"
+                || typeof probe.version !== "string" || !probe.version
+                || [probe.executable_sha256, probe.stdout_sha256, probe.stderr_sha256].some(value => typeof value !== "string" || !/^[a-f0-9]{64}$/.test(value))
+                || !policy || Object.keys(policy).sort().join() !== "initial_head,integration_branch,push_authorized,repository,route,source,workspace_branch"
+                || typeof policy.repository !== "string" || !path.isAbsolute(policy.repository)
+                || policy.route !== raw.git_policy.route || policy.integration_branch !== raw.git_policy.integrationBranch
+                || policy.source !== "explicit_request" || policy.push_authorized !== false
+                || policy.workspace_branch !== payload.workspace.branch || policy.initial_head !== payload.workspace.head)
+                refuse("invalid_git_selection");
+        }
+        if (!payload.release || typeof payload.release.manifest_base64 !== "string" || payload.release.manifest_base64.length > 2 * 1024 * 1024)
+            refuse("invalid_release_bytes");
+        const releaseBytes = Buffer.from(payload.release.manifest_base64, "base64");
+        if (releaseBytes.toString("base64") !== payload.release.manifest_base64 || hash(releaseBytes) !== raw.target_installation_sha256
+            || payload.release.manifest_sha256 !== raw.target_installation_sha256)
+            refuse("release_bytes_changed");
+        const release = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(releaseBytes));
+        if (payload.current?.old_tree !== undefined)
+            readUpgradePreservationBaseline(payload.current.old_tree, payload.current.inventory);
+        if (payload.current?.project_files !== undefined)
+            readUpgradeProjectFiles(payload.current.project_files);
+        if (payload.current?.project_links !== undefined) {
+            const links = payload.current.project_links, seen = new Set();
+            if (!Array.isArray(links) || links.length > 20_000 || JSON.stringify(links).length > 2 * 1024 * 1024)
+                refuse("invalid_project_links");
+            for (const link of links) {
+                if (!link || Object.keys(link).sort().join() !== "mode,path,sha256,target_base64"
+                    || typeof link.path !== "string" || path.isAbsolute(link.path)
+                    || link.path.split("/").some(part => !part || part === "." || part === "..")
+                    || seen.has(link.path) || typeof link.target_base64 !== "string"
+                    || Buffer.from(link.target_base64, "base64").toString("base64") !== link.target_base64
+                    || hash(Buffer.from(link.target_base64, "base64")) !== link.sha256
+                    || !Number.isInteger(link.mode) || link.mode < 0 || link.mode > 0o777)
+                    refuse("invalid_project_links");
+                seen.add(link.path);
+            }
+        }
+        const baseline = payload.current?.baseline_layer ? files(payload.current.baseline_layer, true) : null;
+        assertMixedCurrentContext(payload.current, payload.impact);
+        if ((baseline?.sha256 ?? null) !== payload.current.inventory.inventory.baseline_layer_sha256)
+            refuse("changed_canonical_baseline");
+        if (baseline) {
+            const manifest = JSON.parse(baseline.files().get("dd-flow/manifest.json").toString("utf8"));
+            if (manifest.source_commit !== payload.current.source_commit || manifest.canon_version_at_source_commit !== (payload.current.flow_pack_canon_version ?? payload.current.canon_version))
+                refuse("foreign_canonical_baseline");
+        }
+        if (payload.current.version_source !== undefined && !payload.current.inventory.inventory.entries.some(entry => entry.path === payload.current.version_source && entry.current?.kind === "file"))
+            refuse("unowned_version_source");
+        return { payload, sha256: expectedSha256, release };
+    }
+    catch (error) {
+        if (error instanceof AppError)
+            throw error;
+        return refuse("invalid_retained_selection");
+    }
+}
+/** Restore prepared data and the exact immutable code, not storage readiness
+ * or productive handler admission. Never consults current operator selections. */
+export function restoreMemoryUpgradeSelection(home, scope) {
+    const retained = readMemoryUpgradeSelection(home, scope);
+    if (!retained)
+        refuse("selection_required");
+    return { ...restoreMemoryUpgradeSelectionData(retained.bytes, retained.sha256, retained.original.input, scope), original: retained.original };
+}
+/** Restore the same owners from independently retained SQL bytes after the
+ * pre-storage candidate has been retired. This still admits the exact code;
+ * readable historical metadata alone is not engine execution authority. */
+export function restoreMemoryUpgradeSelectionData(bytes, expectedSha256, input, scope) {
+    const { payload, sha256, release } = decodeMemoryUpgradeSelection(bytes, expectedSha256, input, scope);
+    try {
+        const objective = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(Buffer.from(input.intake_base64, "base64"));
+        const raw = readMemoryUpgradeRequestInput(input, scope, objective).selection;
+        const source = PreparedInstalledFlowSource.restoreRetainedData(payload.source.snapshot, payload.source.sha256), layer = files(payload.layer);
+        if (source.installationSha256() !== raw.target_installation_sha256 || layer.installationSha256 !== raw.target_installation_sha256)
+            refuse("foreign_target");
+        const receipts = new Map(payload.execution.receipts), receiptBytes = new Map();
+        if (receipts.size !== payload.execution.receipts.length || receipts.size > 2)
+            refuse("invalid_execution_receipts");
+        for (const [checksum, encoded] of payload.execution.receipt_blobs ?? []) {
+            const content = Buffer.from(encoded, "base64");
+            if (content.length > 256 * 1024 || content.toString("base64") !== encoded || hash(content) !== checksum || receiptBytes.has(checksum))
+                refuse("invalid_execution_receipt_bytes");
+            receiptBytes.set(checksum, content);
+        }
+        const execution = FrozenGenericExecution.restore(payload.execution.snapshot, payload.execution.sha256, descriptorData(source), { requestId: scope.requestId, projectRoot: scope.projectRoot, workspace: scope.workspaceRoot }, receipts);
+        const consumed = [execution.settings.attached_session_receipt, execution.settings.delegation.native_capacity_receipt].filter(ref => ref !== null);
+        if (receipts.size !== consumed.length || receiptBytes.size !== consumed.length || consumed.some(ref => !receiptBytes.has(ref.sha256)))
+            refuse("execution_receipt_bytes_missing");
+        const engine = AdmittedFrozenEngine.admitSelection(payload.engine.identity, payload.engine.manifest_sha256);
+        if (payload.engine.release_pairing.facts.installation_sha256 !== raw.target_installation_sha256
+            || raw.engine_checksum !== null && raw.engine_checksum !== payload.engine.identity.integrity_checksum)
+            refuse("foreign_engine");
+        revalidateMemoryInitEngineRelease(payload.engine.release_pairing.facts, payload.engine.release_pairing.sha256, engine);
+        const canon = source.canonProvenance(), engineManifest = engine.manifest();
+        const layerManifest = JSON.parse(layer.files().get("dd-flow/manifest.json").toString("utf8"));
+        if (release.canon.version !== canon.version || release.canon.commit !== canon.commit || release.canon.archive.sha256 !== canon.archive_sha256
+            || release.engine.package !== engineManifest.package_name || release.engine.version !== engineManifest.package_version
+            || release.engine.archive.sha256 !== payload.engine.release_pairing.facts.archive_sha256
+            || layerManifest.source_commit !== canon.commit || layerManifest.canon_version_at_source_commit !== canon.version)
+            refuse("foreign_release_context");
+        const impactEntries = payload.impact.files.map(reference => {
+            const bytes = Buffer.from(reference.base64, "base64");
+            if (bytes.length > 1024 * 1024 || bytes.toString("base64") !== reference.base64 || hash(bytes) !== reference.sha256)
+                refuse("impact_bytes_changed");
+            return { ...JSON.parse(bytes.toString("utf8")), source_reference: { path: reference.path, sha256: reference.sha256 } };
+        });
+        if (hybridDigest(adjacentMigrationChain(payload.current.canon_version, source.canonProvenance().version, impactEntries)) !== hybridDigest(payload.impact.chain))
+            refuse("changed_impact_chain");
+        if (payload.current.inventory.sha256 !== hybridDigest(payload.current.inventory.inventory)
+            || payload.current.inventory.inventory.target_layer_sha256 !== layer.sha256
+            || payload.current.inventory.inventory.workspace_root !== scope.workspaceRoot
+            || hash(Buffer.from(payload.current.manifest_base64, "base64")) !== payload.current.inventory.inventory.current_manifest.sha256)
+            refuse("foreign_current_context");
+        const oldManifest = JSON.parse(Buffer.from(payload.current.manifest_base64, "base64").toString("utf8"));
+        if (oldManifest.source_commit !== payload.current.source_commit || oldManifest.canon_version_at_source_commit !== (payload.current.flow_pack_canon_version ?? payload.current.canon_version))
+            refuse("foreign_current_context");
+        const oldTree = payload.current.old_tree ? readUpgradePreservationBaseline(payload.current.old_tree, payload.current.inventory) : null;
+        const baselineLayer = payload.current.baseline_layer ? files(payload.current.baseline_layer, true) : null;
+        return { payload, sha256, source, layer, execution, engine, receipts, receiptBytes, release, oldTree, baselineLayer, bytes: Buffer.from(bytes) };
+    }
+    catch (error) {
+        if (error instanceof AppError)
+            throw error;
+        return refuse("invalid_retained_selection");
+    }
+}
+/** Pre-storage selection only: no SQLite open, project sync, RUN or provider.
+ * The receipt distinguishes never-selected from lost/partial selection, so a
+ * retry cannot silently replace its resolved profiles or selected release. */
+export class PreparedMemoryUpgradeSelection {
+    sha256;
+    #bytes;
+    #payload;
+    #home;
+    #candidate;
+    #source;
+    #layer;
+    #engine;
+    #env;
+    constructor(home, candidate, payload, source, layer, engine, env) {
+        this.#home = home;
+        this.#candidate = candidate;
+        this.#payload = structuredClone(payload);
+        this.#bytes = Buffer.from(JSON.stringify(payload));
+        if (this.#bytes.length > limit)
+            refuse("unbounded_selection");
+        this.sha256 = hash(this.#bytes);
+        this.#source = source;
+        this.#layer = layer;
+        this.#engine = engine;
+        this.#env = { ...env };
+        Object.freeze(this);
+    }
+    static prepare(home, scope, candidate, options) {
+        const original = captureMemoryUpgradeRequestCandidate(candidate, home, scope, candidate.objective);
+        const locations = paths(candidate);
+        if (exists(locations.payload) || exists(locations.receipt))
+            refuse("restore_existing_selection");
+        assertImportAdmission(home);
+        const raw = readMemoryUpgradeRequestInput(original, scope, candidate.objective).selection;
+        const source = PreparedInstalledFlowSource.fromInstalledRelease(home, raw.target_installation_sha256, "mb-upgrade");
+        const layer = PreparedMemoryLayer.fromInstalledRelease(home, raw.target_installation_sha256, options.now);
+        const engine = selectMemoryInitInstalledEngine(home, raw.target_installation_sha256, raw.engine_checksum ?? undefined);
+        const receipts = new Map(options.receipts ?? []);
+        const ordered = (entries) => [...entries].sort(([a], [b]) => a.localeCompare(b));
+        if (hybridDigest(ordered([...receipts])) !== hybridDigest(ordered(raw.receipts)))
+            refuse("execution_receipt_authority_missing");
+        const execution = FrozenGenericExecution.prepare(descriptorData(source), readOperatorProfiles(home), raw.execution, { requestId: scope.requestId, projectRoot: scope.projectRoot, workspace: scope.workspaceRoot }, receipts);
+        const consumed = [execution.settings.attached_session_receipt, execution.settings.delegation.native_capacity_receipt].filter(ref => ref !== null);
+        const selectedReceipts = [];
+        const receiptBlobs = [];
+        for (const reference of consumed) {
+            const content = options.receiptBytes?.get(reference.sha256);
+            if (!content || content.byteLength > 256 * 1024 || hash(content) !== reference.sha256)
+                refuse("execution_receipt_bytes_missing");
+            selectedReceipts.push([reference.sha256, structuredClone(receipts.get(reference.sha256))]);
+            receiptBlobs.push([reference.sha256, Buffer.from(content).toString("base64")]);
+        }
+        const pairing = prepareMemoryInitEngineRelease(home, raw.target_installation_sha256, engine), manifest = engine.manifest();
+        const selected = readSetupStatus(home), installation = selected.installation;
+        if (!installation || selected.installation_readiness !== "installed" || installation.manifest_sha256 !== raw.target_installation_sha256)
+            refuse("target_changed");
+        const git = inspectMemoryGitExecutable(options.env);
+        const policy = observeMemoryGitPolicySelection(options.env, { scope, gitExecutable: git.executable, selection: raw.git_policy });
+        const baseline = current(home, scope, layer, options.env, undefined, git.executable);
+        if (policy.workspace_branch !== baseline.workspace.branch || policy.initial_head !== baseline.workspace.head)
+            refuse("git_selection_changed");
+        const payload = { schema_id: "dd-flow/memory-upgrade-selection@1", scope: { ...scope }, request_input_sha256: hybridDigest(original),
+            ...baseline, git: { ...git, policy }, impact: impacts(layer, baseline.current.canon_version, source.canonProvenance().version), source: { sha256: source.sha256, snapshot: source.snapshot() },
+            release: { manifest_sha256: installation.manifest_sha256, manifest_base64: installation.manifest_bytes_base64 },
+            layer: { sha256: layer.sha256, installation_sha256: layer.installationSha256, files: [...layer.files()].map(([logical, content]) => ({ path: logical, base64: content.toString("base64") })) },
+            execution: { sha256: execution.sha256, snapshot: execution.snapshot(), receipts: selectedReceipts, receipt_blobs: receiptBlobs },
+            engine: { identity: { package_name: manifest.package_name, package_version: manifest.package_version, engine_version: manifest.engine_version,
+                    snapshot_root: manifest.snapshot_root, integrity_checksum: manifest.integrity.checksum }, manifest_sha256: engine.manifestSha256, release_pairing: pairing } };
+        assertMixedCurrentContext(payload.current, payload.impact);
+        return new PreparedMemoryUpgradeSelection(home, candidate, payload, source, layer, engine, options.env);
+    }
+    retain() {
+        const p = this.#payload, prior = readMemoryUpgradeSelection(this.#home, p.scope);
+        if (prior) {
+            if (prior.sha256 !== this.sha256)
+                refuse("selection_changed");
+            return { sha256: this.sha256, changed: false };
+        }
+        assertImportAdmission(this.#home);
+        if (hybridDigest(captureMemoryUpgradeRequestCandidate(this.#candidate, this.#home, p.scope, this.#candidate.objective)) !== p.request_input_sha256)
+            refuse("request_changed");
+        this.#source.revalidate();
+        if (p.git) {
+            const raw = readMemoryUpgradeRequestInput(captureMemoryUpgradeRequestCandidate(this.#candidate, this.#home, p.scope, this.#candidate.objective), p.scope, this.#candidate.objective).selection;
+            if (hash(readBoundedReleaseFile(p.git.executable, 64 * 1024 * 1024)) !== p.git.probe.executable_sha256
+                || hybridDigest(observeMemoryGitPolicySelection(this.#env, { scope: p.scope, gitExecutable: p.git.executable, selection: raw.git_policy })) !== hybridDigest(p.git.policy))
+                refuse("git_selection_changed");
+        }
+        const installedAt = JSON.parse(this.#layer.files().get("dd-flow/manifest.json").toString("utf8")).installed_at;
+        if (PreparedMemoryLayer.fromInstalledRelease(this.#home, this.#layer.installationSha256, installedAt).sha256 !== this.#layer.sha256
+            || hybridDigest(current(this.#home, p.scope, this.#layer, this.#env, p.current.baseline_layer?.installation_sha256 ?? null, p.git?.executable, p.current.project_links !== undefined, p.current.project_files !== undefined)) !== hybridDigest({ current: p.current, workspace: p.workspace })
+            || hybridDigest(impacts(this.#layer, p.current.canon_version, this.#source.canonProvenance().version)) !== hybridDigest(p.impact))
+            refuse("selection_changed_before_retention");
+        revalidateMemoryInitEngineRelease(p.engine.release_pairing.facts, p.engine.release_pairing.sha256, this.#engine);
+        const locations = paths(this.#candidate);
+        try {
+            publishImmutableInput(locations.receipt, Buffer.from(JSON.stringify({ schema_id: "dd-flow/memory-upgrade-selection-receipt@1", scope: p.scope,
+                request_input_sha256: p.request_input_sha256, selection_sha256: this.sha256 })), "memory_upgrade_selection_conflict");
+            publishImmutableInput(locations.payload, this.#bytes, "memory_upgrade_selection_conflict");
+            if (readMemoryUpgradeSelection(this.#home, p.scope)?.sha256 !== this.sha256)
+                refuse("selection_readback_failed");
+            return { sha256: this.sha256, changed: true };
+        }
+        catch (error) {
+            throw new AppError("memory_upgrade_selection_incomplete", "Upgrade selection requires exact request reconciliation", 1, { effect: "partial", request_id: p.scope.requestId, cause: errorRecord(error), next_action: "reconcile_exact_request" });
+        }
+    }
+}

package/dist/services/memory-upgrade-start.js

@@ -0,0 +1,60 @@
+import { AppError } from "../shared/errors.js";
+import { PreparedDescriptorRunStart } from "./descriptor-run-start.js";
+import { readRunStartRequest } from "./run-start-custody.js";
+import { PreparedMemoryUpgradeBootstrapReadiness } from "./memory-upgrade-bootstrap-readiness.js";
+import { readUpgradeStorageReadiness, assertMemoryUpgradeProjectCurrent, assertUpgradeExecutionStorage } from "./memory-upgrade-storage-readiness.js";
+import { restoreMemoryUpgradeSelection, restoreMemoryUpgradeSelectionData } from "./memory-upgrade-selection.js";
+import { PreparedProjectRegistration, registerPreparedProject } from "./projects.js";
+import { prepareMemoryUpgradeRunBundle } from "./memory-init-run-bundle.js";
+import { validateMemoryInitStartupScope } from "./memory-init-startup-custody.js";
+function refuse(reason) {
+    throw new AppError("memory_upgrade_start_invalid", "Upgrade RUN requires its retained request and accepted storage", 1, { reason, effect: "no_effect", next_action: "reconcile_exact_request" });
+}
+/** Register only metadata for an existing MB after target storage admission.
+ * Never use init's draft publication or revive an archived project. */
+export function registerMemoryUpgradeProject(context, scope) {
+    const existing = context.db.get("SELECT status FROM projects WHERE root=?", [scope.projectRoot]);
+    if (existing) {
+        if (existing.status !== "active")
+            refuse("project_not_active");
+        return;
+    }
+    const selected = restoreMemoryUpgradeSelection(context.ddFlowHome, scope);
+    assertMemoryUpgradeProjectCurrent(selected, scope, context.env);
+    assertUpgradeExecutionStorage(context, selected.engine);
+    const registration = PreparedProjectRegistration.prepare({ root: scope.projectRoot });
+    context.db.writeTransaction(() => {
+        const current = context.db.get("SELECT status FROM projects WHERE root=?", [scope.projectRoot]);
+        if (current) {
+            if (current.status !== "active")
+                refuse("project_not_active");
+            return;
+        }
+        registerPreparedProject(context, registration);
+    }, "memoryUpgrade.registerProject");
+}
+/** Storage admission precedes this operation. The existing RUN owner handles
+ * allocation/publication and exact retries; no Session or agent is dispatched.
+ * Restore a published request before observing mutable project/tool state. */
+export function startMemoryUpgradeRun(context, scope) {
+    validateMemoryInitStartupScope(scope);
+    if (context.db.isOwnedWriteTransaction?.())
+        refuse("startup_outside_writer_required");
+    const project = context.db.get("SELECT id FROM projects WHERE root=? AND status='active'", [scope.projectRoot]);
+    if (!project)
+        refuse("project_not_active");
+    const request = readRunStartRequest(context, project.id, scope.requestId);
+    if (request) {
+        if (request.payload.project_root !== scope.projectRoot || request.payload.workspace_root !== scope.workspaceRoot
+            || request.payload.initial_index.flow_kind !== "mb-upgrade")
+            refuse("run_request_changed");
+        return PreparedDescriptorRunStart.restore(context, { projectRoot: scope.projectRoot, requestId: scope.requestId }).apply(context);
+    }
+    const storage = readUpgradeStorageReadiness(context, scope);
+    if (!storage?.receipt.selection)
+        refuse("accepted_storage_required");
+    PreparedMemoryUpgradeBootstrapReadiness.prepareForRun(context, scope).apply(context);
+    const retained = storage.receipt.selection;
+    const selected = restoreMemoryUpgradeSelectionData(Buffer.from(retained.payload_json), retained.sha256, retained.request_input, scope);
+    return PreparedDescriptorRunStart.prepare(context, { bundle: prepareMemoryUpgradeRunBundle(context, selected) }).apply(context);
+}