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

package/dist/services/memory-init-contexts.js

@@ -0,0 +1,181 @@
+import path from "node:path";
+import fs from "node:fs";
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { RetainedExecutionBundle } from "./execution-bundles.js";
+import { publishImmutableInput } from "../storage/immutable-input.js";
+import { readBoundedReleaseFile } from "./release-source.js";
+import { readMemoryInitStartupInput } from "./memory-init-startup-custody.js";
+import { readUpgradeStorageReadiness } from "./memory-upgrade-storage-readiness.js";
+import { isSourceSnapshotFlow } from "../domain/source-snapshot-flows.js";
+import { readDiagnosticRequest } from "./diagnostic-start.js";
+import { isDeliveryFlow } from "../domain/delivery-flows.js";
+/** Repair's objective is already part of its own retained bundle. Continuation
+ * does not need the source diagnostic or mutable operator/request files. */
+export function prepareMemoryFixContexts(bundle, directory) {
+    return prepareRequestContexts(bundle, directory, "mb-fix");
+}
+/** Static controller candidates carry only the original request. Current turns,
+ * scope and checks are read from their retained owners at each Stage boundary. */
+export function prepareInteractiveContexts(bundle, directory) {
+    return prepareRequestContexts(bundle, directory, "interactive");
+}
+export function prepareDeliveryContexts(bundle, directory) {
+    if (!isDeliveryFlow(bundle.manifest.flow_id))
+        throw new AppError("delivery_context_invalid", "Delivery bundle required", 2, { effect: "no_effect" });
+    return prepareRequestContexts(bundle, directory, bundle.manifest.flow_id);
+}
+export function publishDeliveryContexts(bundle, objective, directory, expectedSha256, expectedOwner) {
+    const original = prepareDeliveryContexts(bundle, directory);
+    if (objective !== original.objective)
+        throw new AppError("delivery_context_invalid", "Delivery objective cannot be replaced", 2, { effect: "no_effect" });
+    return publishMemoryContexts(bundle, objective, directory, expectedSha256, expectedOwner, bundle.manifest.flow_id);
+}
+function prepareRequestContexts(bundle, directory, flowId) {
+    const code = isDeliveryFlow(flowId) ? "delivery_context_invalid" : flowId === "interactive" ? "interactive_context_invalid" : "memory_fix_context_invalid";
+    if (!(bundle instanceof RetainedExecutionBundle) || bundle.manifest.flow_id !== flowId)
+        throw new AppError(code, "Retained request-owning bundle required", 2, { effect: "no_effect" });
+    const bytes = bundle.blob("runtime/source-request.md"), refs = bundle.manifest.inventory.filter(ref => ref.path === "runtime/source-request.md");
+    if (!bytes.length || bytes.length > 64 * 1024 || refs.length !== 1 || refs[0].sha256 !== createHash("sha256").update(bytes).digest("hex"))
+        throw new AppError(code, "Original retained request required", 2, { effect: "no_effect" });
+    let objective;
+    try {
+        objective = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+    }
+    catch {
+        throw new AppError(code, "Original request must be UTF-8", 2, { effect: "no_effect" });
+    }
+    return { ...prepareMemoryContexts(bundle, objective, directory, flowId), objective };
+}
+export function publishInteractiveContexts(bundle, objective, directory, expectedSha256, expectedOwner) {
+    const original = prepareInteractiveContexts(bundle, directory);
+    if (objective !== original.objective)
+        throw new AppError("interactive_context_invalid", "Interactive objective cannot be replaced", 2, { effect: "no_effect" });
+    return publishMemoryContexts(bundle, objective, directory, expectedSha256, expectedOwner, "interactive");
+}
+export function publishMemoryFixContexts(bundle, objective, directory, expectedSha256, expectedOwner) {
+    const original = prepareMemoryFixContexts(bundle, directory);
+    if (objective !== original.objective)
+        throw new AppError("memory_fix_context_invalid", "Repair objective cannot be replaced", 2, { effect: "no_effect" });
+    return publishMemoryContexts(bundle, objective, directory, expectedSha256, expectedOwner, "mb-fix");
+}
+export function prepareDiagnosticContextsFromRequest(context, bundle, directory) {
+    const scope = bundle.execution.snapshot().scope, flowId = bundle.manifest.flow_id;
+    if (!isSourceSnapshotFlow(flowId))
+        throw new AppError("diagnostic_context_invalid", "Source-snapshot bundle required", 2, { effect: "no_effect" });
+    const request = readDiagnosticRequest(context, { projectRoot: scope.projectRoot, requestId: scope.requestId, flowId });
+    if (!request || request.execution_sha256 !== bundle.execution.sha256)
+        throw new AppError("diagnostic_context_invalid", "Original diagnostic objective required", 2, { effect: "no_effect" });
+    return { ...prepareMemoryContexts(bundle, request.objective, directory, flowId), objective: request.objective };
+}
+export function publishDiagnosticContexts(bundle, objective, directory, expectedSha256, expectedOwner) {
+    if (!isSourceSnapshotFlow(bundle.manifest.flow_id))
+        throw new AppError("diagnostic_context_invalid", "Source-snapshot bundle required", 2, { effect: "no_effect" });
+    return publishMemoryContexts(bundle, objective, directory, expectedSha256, expectedOwner, bundle.manifest.flow_id);
+}
+/** Original upgrade intake comes from the independently retained storage
+ * selection, including after project publication changes the old tree. */
+export function prepareMemoryUpgradeContextsFromStartup(context, bundle, directory) {
+    if (!(bundle instanceof RetainedExecutionBundle) || bundle.manifest.flow_id !== "mb-upgrade") {
+        throw new AppError("memory_upgrade_context_invalid", "Upgrade contexts require a retained upgrade bundle", 2, { effect: "no_effect" });
+    }
+    const scope = bundle.execution.snapshot().scope;
+    const retained = readUpgradeStorageReadiness(context, { requestId: scope.requestId, projectRoot: scope.projectRoot, workspaceRoot: scope.workspace });
+    if (!retained?.receipt.selection || !retained.selection
+        || retained.selection.payload.execution.sha256 !== bundle.execution.sha256
+        || retained.selection.payload.engine.manifest_sha256 !== bundle.manifest.engine_manifest.sha256) {
+        throw new AppError("memory_upgrade_context_invalid", "Upgrade contexts require the original request selection", 1, { effect: "no_effect" });
+    }
+    const objective = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(Buffer.from(retained.receipt.selection.request_input.intake_base64, "base64"));
+    return { ...prepareMemoryContexts(bundle, objective, directory, "mb-upgrade"), objective };
+}
+/** Public init consumes the independently retained intake, never a newly
+ * inferred objective. Historical v1 SDK requests must not invent one. */
+export function prepareMemoryInitContextsFromStartup(context, bundle, directory) {
+    if (!(bundle instanceof RetainedExecutionBundle) || bundle.manifest.flow_id !== "mb-init") {
+        throw new AppError("memory_init_context_invalid", "Init contexts require a retained memory bundle", 2, { effect: "no_effect" });
+    }
+    const scope = bundle.execution.snapshot().scope;
+    const retained = readMemoryInitStartupInput(context, { requestId: scope.requestId, projectRoot: scope.projectRoot, workspaceRoot: scope.workspace });
+    if (!retained || !["dd-flow/memory-init-startup-input@2", "dd-flow/memory-init-startup-input@3"].includes(retained.payload.schema_id)
+        || retained.payload.objective === undefined || retained.payload.execution.sha256 !== bundle.execution.sha256
+        || retained.payload.engine.manifest_sha256 !== bundle.manifest.engine_manifest.sha256) {
+        throw new AppError("memory_init_context_invalid", "Init contexts require the exact retained objective and execution selection", 1, { effect: "no_effect" });
+    }
+    return { ...prepareMemoryInitContexts(bundle, retained.payload.objective, directory), objective: retained.payload.objective };
+}
+/** Prepare bytes only. Immutable publication and the controller retain their
+ * existing ownership; this does not create directories, Sessions or RUNs. */
+export function prepareMemoryInitContexts(bundle, objective, directory) {
+    return prepareMemoryContexts(bundle, objective, directory, "mb-init");
+}
+function prepareMemoryContexts(bundle, objective, directory, flowId) {
+    if (!(bundle instanceof RetainedExecutionBundle) || bundle.manifest.flow_id !== flowId
+        || typeof objective !== "string" || !objective.trim() || Buffer.byteLength(objective) > 64 * 1024
+        || !path.isAbsolute(directory) || path.resolve(directory) !== directory) {
+        throw new AppError("memory_init_context_invalid", "Init contexts require a retained memory bundle, bounded objective and absolute directory", 2, { effect: "no_effect" });
+    }
+    const files = new Map(), stages = Object.create(null);
+    const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
+    for (const stage of bundle.descriptor.descriptor.stages) {
+        const file = path.join(directory, `${stage.id}.json`);
+        const bytes = Buffer.from(JSON.stringify({ schema_id: "dd-flow/stage-context@1", stage: stage.id, objective }));
+        files.set(file, bytes);
+        stages[stage.id] = { file, sha256: hash(bytes) };
+    }
+    const file = path.join(directory, "managed-context.json"), bytes = Buffer.from(JSON.stringify({ schema_id: "dd-flow/managed-context@1", stages }));
+    files.set(file, bytes);
+    return { file, sha256: hash(bytes), files };
+}
+/** Publish candidates only; an existing controller SQL receipt still owns
+ * their execution authority. The caller supplies an already owned directory
+ * and independently retained package digest. Never replaces conflicting files. */
+export function publishMemoryInitContexts(bundle, objective, directory, expectedSha256, expectedOwner) {
+    return publishMemoryContexts(bundle, objective, directory, expectedSha256, expectedOwner, "mb-init");
+}
+export function publishMemoryUpgradeContexts(bundle, objective, directory, expectedSha256, expectedOwner) {
+    return publishMemoryContexts(bundle, objective, directory, expectedSha256, expectedOwner, "mb-upgrade");
+}
+function publishMemoryContexts(bundle, objective, directory, expectedSha256, expectedOwner, flowId) {
+    const prepared = prepareMemoryContexts(bundle, objective, directory, flowId);
+    if (prepared.sha256 !== expectedSha256)
+        throw new AppError("memory_init_context_invalid", "Context package selection changed", 1, { effect: "no_effect" });
+    const owner = fs.lstatSync(directory);
+    if (expectedOwner && (owner.dev !== expectedOwner.dev || owner.ino !== expectedOwner.ino)) {
+        throw new AppError("memory_init_context_invalid", "Context directory differs from its retained owner", 1, { effect: "no_effect" });
+    }
+    const assertOwner = () => {
+        const current = fs.lstatSync(directory);
+        if (!current.isDirectory() || current.dev !== owner.dev || current.ino !== owner.ino || fs.realpathSync(directory) !== directory) {
+            throw new AppError("memory_init_context_invalid", "Context directory owner changed", 1, { effect: "no_effect" });
+        }
+    };
+    assertOwner();
+    // Reject any known collision before creating the first candidate.
+    for (const [file, bytes] of prepared.files) {
+        try {
+            fs.lstatSync(file);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                continue;
+            throw error;
+        }
+        if (!readBoundedReleaseFile(file, bytes.length).equals(bytes))
+            throw new AppError("memory_init_context_invalid", "Existing context bytes differ", 1, { effect: "no_effect", path: file });
+    }
+    let attempted = false;
+    try {
+        for (const [file, bytes] of prepared.files) {
+            assertOwner();
+            attempted = true;
+            publishImmutableInput(file, bytes, "memory_init_context_invalid");
+        }
+        assertOwner();
+        return { file: prepared.file, sha256: prepared.sha256 };
+    }
+    catch (error) {
+        throw new AppError("memory_init_context_publication_incomplete", "Context candidates require exact-request reconciliation", 1, { effect: attempted ? "partial" : "no_effect", directory, expected_sha256: expectedSha256,
+            reason: error instanceof AppError ? error.code : "context_publication_failed" });
+    }
+}

package/dist/services/memory-init-controller-start.js

@@ -0,0 +1,119 @@
+import fs from "node:fs";
+import path from "node:path";
+import { AppError, errorRecord } from "../shared/errors.js";
+import { validateMemoryInitStartupScope, readMemoryInitStartupInput } from "./memory-init-startup-custody.js";
+import { startMemoryInitRun } from "./memory-init-start.js";
+import { startMemoryUpgradeRun } from "./memory-upgrade-start.js";
+import { requireProjectByRoot } from "./projects.js";
+import { readRunStartRequest } from "./run-start-custody.js";
+import { readFlowRunExecutionBundle } from "./runs.js";
+import { requireRun } from "./run-controller-state.js";
+import { prepareRunControllerLaunch } from "./run-controller.js";
+import { prepareMemoryInitContextsFromStartup, publishMemoryInitContexts, prepareMemoryUpgradeContextsFromStartup, publishMemoryUpgradeContexts } from "./memory-init-contexts.js";
+import { parseRuntimeBudget } from "./runtime-budget.js";
+import { isSourceSnapshotFlow } from "../domain/source-snapshot-flows.js";
+import { startDiagnosticRun } from "./diagnostic-start.js";
+import { prepareDiagnosticContextsFromRequest, publishDiagnosticContexts } from "./memory-init-contexts.js";
+import { prepareMemoryFixContexts, publishMemoryFixContexts } from "./memory-init-contexts.js";
+import { startMemoryFixRun } from "./memory-fix-request.js";
+import { startInteractiveRun } from "./interactive-request.js";
+import { prepareInteractiveContexts, publishInteractiveContexts } from "./memory-init-contexts.js";
+import { prepareDeliveryContexts, publishDeliveryContexts } from "./memory-init-contexts.js";
+import { isDeliveryFlow } from "../domain/delivery-flows.js";
+import { startDeliveryRun } from "./delivery-request.js";
+function refuse(reason) {
+    throw new AppError("memory_init_controller_start_invalid", "Init controller requires its exact published startup request", 1, { reason, effect: "no_effect", next_action: "reconcile_exact_request" });
+}
+/** Bridge the already published logical RUN to the existing controller. The
+ * RUN-start owner admits the root; startup custody supplies the objective.
+ * An existing controller replays before candidate publication, so missing
+ * productive inputs are never reconstructed here. No process is launched. */
+export function prepareMemoryInitControllerStart(context, scope) {
+    return prepareMemoryControllerStart(context, scope, "mb-init");
+}
+export function prepareMemoryUpgradeControllerStart(context, scope) {
+    return prepareMemoryControllerStart(context, scope, "mb-upgrade");
+}
+export function prepareDiagnosticControllerStart(context, scope, flowId) {
+    return prepareMemoryControllerStart(context, scope, flowId);
+}
+export function prepareMemoryFixControllerStart(context, scope) {
+    return prepareMemoryControllerStart(context, scope, "mb-fix");
+}
+export function prepareInteractiveControllerStart(context, scope) {
+    return prepareMemoryControllerStart(context, scope, "interactive");
+}
+export function prepareDeliveryControllerStart(context, scope, flowId) {
+    return prepareMemoryControllerStart(context, scope, flowId);
+}
+function prepareMemoryControllerStart(context, scope, flowId) {
+    validateMemoryInitStartupScope(scope);
+    if (context.db.isOwnedWriteTransaction?.())
+        refuse("preparation_outside_writer_required");
+    parseRuntimeBudget(context.env.DD_FLOW_RUNTIME_BUDGET);
+    if (flowId === "mb-init") {
+        const startup = readMemoryInitStartupInput(context, scope);
+        if (!startup || !["dd-flow/memory-init-startup-input@2", "dd-flow/memory-init-startup-input@3"].includes(startup.payload.schema_id))
+            refuse("retained_objective_required");
+    }
+    const project = requireProjectByRoot(context, scope.projectRoot);
+    const request = readRunStartRequest(context, project.id, scope.requestId);
+    if (!request?.published || request.payload.initial_index.flow_kind !== flowId
+        || request.payload.workspace_root !== scope.workspaceRoot)
+        refuse("published_run_required");
+    // Restores the exact request and verifies independent SQL/physical root
+    // ownership without consulting current canon/profiles or creating a RUN.
+    const started = isDeliveryFlow(flowId) ? startDeliveryRun(context, { projectRoot: scope.projectRoot, requestId: scope.requestId, flowId }) : flowId === "interactive" ? startInteractiveRun(context, scope) : flowId === "mb-fix" ? startMemoryFixRun(context, scope) : isSourceSnapshotFlow(flowId) ? startDiagnosticRun(context, { projectRoot: scope.projectRoot, requestId: scope.requestId, flowId })
+        : flowId === "mb-init" ? startMemoryInitRun(context, scope) : startMemoryUpgradeRun(context, scope);
+    const run = requireRun(context, project.id, started.runId);
+    const bundle = readFlowRunExecutionBundle(context, { projectRoot: scope.projectRoot, runId: run.id });
+    if (!bundle || bundle.sha256 !== started.bundleSha256)
+        refuse("retained_bundle_required");
+    if (bundle.execution.settings.execution !== "managed")
+        refuse("managed_execution_required");
+    const contexts = isDeliveryFlow(flowId) ? prepareDeliveryContexts(bundle, run.run_root) : flowId === "interactive" ? prepareInteractiveContexts(bundle, run.run_root) : flowId === "mb-fix" ? prepareMemoryFixContexts(bundle, run.run_root) : isSourceSnapshotFlow(flowId) ? prepareDiagnosticContextsFromRequest(context, bundle, run.run_root)
+        : flowId === "mb-init" ? prepareMemoryInitContextsFromStartup(context, bundle, run.run_root)
+            : prepareMemoryUpgradeContextsFromStartup(context, bundle, run.run_root);
+    const input = { projectRoot: scope.projectRoot, runId: run.id, requestId: scope.requestId,
+        contextFile: contexts.file, contextSha256: contexts.sha256 };
+    const controllers = context.db.get("SELECT 1 FROM sqlite_schema WHERE type='table' AND name='run_controllers'")
+        ? context.db.all("SELECT request_id FROM run_controllers WHERE project_id=? AND run_id=?", [project.id, run.id]) : [];
+    if (controllers.some(row => row.request_id === scope.requestId))
+        return { input, prepared: prepareRunControllerLaunch(context, input) };
+    if (controllers.length)
+        refuse("foreign_controller_request");
+    // A directory without a receipt is an interrupted/unknown outcome, not
+    // evidence that no owner ran. Do not create another physical controller.
+    let controllerRootFound = false;
+    try {
+        fs.lstatSync(path.join(run.run_root, "controllers"));
+        controllerRootFound = true;
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    if (controllerRootFound)
+        refuse("controller_custody_missing");
+    if (context.db.get("SELECT 1 FROM sessions WHERE project_id=? AND run_id=? LIMIT 1", [project.id, run.id]))
+        refuse("session_owner_requires_reconciliation");
+    const rootOwner = context.db.readSnapshot(() => {
+        if (readRunStartRequest(context, project.id, scope.requestId)?.sha256 !== request.sha256)
+            refuse("run_request_changed");
+        const row = context.db.get("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type='flow_run.start_root_owned' AND json_extract(payload_json,'$.run_id')=?", [project.id, run.id]);
+        if (!row)
+            refuse("root_owner_missing");
+        return JSON.parse(row.payload_json).owner;
+    });
+    if (!rootOwner || !Number.isSafeInteger(rootOwner.dev) || !Number.isSafeInteger(rootOwner.ino))
+        refuse("root_owner_changed");
+    const publish = isDeliveryFlow(flowId) ? publishDeliveryContexts : flowId === "interactive" ? publishInteractiveContexts : flowId === "mb-fix" ? publishMemoryFixContexts : isSourceSnapshotFlow(flowId) ? publishDiagnosticContexts : flowId === "mb-init" ? publishMemoryInitContexts : publishMemoryUpgradeContexts;
+    publish(bundle, contexts.objective, run.run_root, contexts.sha256, rootOwner);
+    try {
+        return { input, prepared: prepareRunControllerLaunch(context, input) };
+    }
+    catch (error) {
+        throw new AppError("memory_init_controller_start_incomplete", "Retained context candidates require exact-request reconciliation", 1, { effect: "partial", run_id: run.id, request_id: scope.requestId, context_sha256: contexts.sha256,
+            cause: errorRecord(error), next_action: "reconcile_exact_request" });
+    }
+}

package/dist/services/memory-init-engine-release.js

@@ -0,0 +1,223 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { AdmittedFrozenEngine } from "./frozen-engine.js";
+import { readSetupStatus } from "./setup.js";
+import { inspectReleaseArchive } from "./release-archive.js";
+import { readBoundedReleaseFile } from "./release-source.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { engineVersionRoot } from "../storage/paths.js";
+import { engineSnapshotChecksum, installPackageEngine } from "./engines.js";
+const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
+function refuse(reason) {
+    throw new AppError("memory_init_engine_release_invalid", "Selected engine is not the verified installed release payload", 1, { reason, phase: "prepare", effect: "no_effect" });
+}
+/** Select already delivered release bytes, never the invoking CLI or highest
+ * package version. Ambiguous dependency snapshots require explicit selection. */
+export function selectMemoryInitInstalledEngine(home, installationSha256, checksum) {
+    if (!path.isAbsolute(home) || path.resolve(home) !== home || fs.realpathSync(home) !== home)
+        refuse("noncanonical_installation_home");
+    const selected = readSetupStatus(home), installation = selected.installation;
+    if (!installation || selected.installation_readiness !== "installed" || installation.manifest_sha256 !== installationSha256)
+        refuse("installation_selection_changed");
+    if (checksum !== undefined && !/^[a-f0-9]{64}$/.test(checksum))
+        refuse("invalid_engine_checksum");
+    const base = engineVersionRoot(home, installation.manifest.engine.package, installation.manifest.engine.version);
+    const parent = path.dirname(base), version = path.basename(base), candidates = [];
+    if (!fs.existsSync(parent))
+        refuse("selected_engine_not_delivered");
+    if (!fs.lstatSync(parent).isDirectory() || fs.realpathSync(parent) !== parent)
+        refuse("unsafe_engine_store");
+    for (const entry of fs.readdirSync(parent, { withFileTypes: true })) {
+        if (!entry.isDirectory() || !(entry.name === version || entry.name.startsWith(`${version}--`)
+            && /^[a-f0-9]{64}$/.test(entry.name.slice(version.length + 2))))
+            continue;
+        const root = path.join(parent, entry.name);
+        try {
+            const bytes = readBoundedReleaseFile(path.join(root, "engine.json"), 1024 * 1024);
+            const manifest = JSON.parse(bytes.toString("utf8"));
+            if (manifest.snapshot_root !== root || entry.name !== version && entry.name !== `${version}--${manifest.integrity?.checksum}`
+                || checksum !== undefined && manifest.integrity?.checksum !== checksum)
+                continue;
+            const engine = AdmittedFrozenEngine.admitSelection({ package_name: manifest.package_name, package_version: manifest.package_version,
+                engine_version: manifest.engine_version, snapshot_root: root, integrity_checksum: manifest.integrity?.checksum }, hash(bytes));
+            prepareMemoryInitEngineRelease(home, installationSha256, engine);
+            candidates.push(engine);
+        }
+        catch (error) {
+            // An unavailable or mismatching old snapshot cannot authorize this release.
+            if (error instanceof AppError || error instanceof SyntaxError || error.code === "ENOENT")
+                continue;
+            throw error;
+        }
+    }
+    if (candidates.length !== 1)
+        refuse(candidates.length ? "ambiguous_selected_engine" : "selected_engine_not_delivered");
+    return candidates[0];
+}
+function checkFile(root, entry) {
+    let file = root;
+    const parts = entry.path.split("/");
+    for (const [index, part] of parts.entries()) {
+        file = path.join(file, part);
+        const stat = fs.lstatSync(file);
+        if (stat.isSymbolicLink() || (index === parts.length - 1 ? !stat.isFile() : !stat.isDirectory()))
+            refuse("unsafe_snapshot_path");
+    }
+    if ((fs.lstatSync(file).mode & 0o111) !== entry.executable_mode)
+        refuse("snapshot_payload_mode_changed");
+    if (entry.bytes === 0) {
+        const fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+        try {
+            const stat = fs.fstatSync(fd);
+            if (!stat.isFile() || stat.size !== 0 || fs.readSync(fd, Buffer.alloc(1), 0, 1, 0) !== 0)
+                refuse("snapshot_payload_changed");
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    else if (hash(readBoundedReleaseFile(file, entry.bytes)) !== entry.sha256)
+        refuse("snapshot_payload_changed");
+}
+function checkInventory(root, inventory) {
+    const expected = new Set(inventory.map(entry => entry.path));
+    for (const entry of fs.readdirSync(root, { recursive: true, withFileTypes: true })) {
+        const logical = path.relative(root, path.join(entry.parentPath, entry.name)).split(path.sep).join("/");
+        if (!entry.isFile() && !entry.isDirectory())
+            refuse("unsafe_snapshot_path");
+        if (logical !== "engine.json" && !expected.has(logical)
+            && (entry.name === "engine.json" || entry.isFile() && !logical.startsWith("node_modules/")))
+            refuse("unselected_snapshot_file");
+    }
+}
+function archiveInventory(archive, engineRoot) {
+    const entries = inspectReleaseArchive(archive, readBoundedReleaseFile(path.join(path.dirname(engineRoot), "archive.tgz"), Math.min(archive.bytes, 256 * 1024 * 1024)));
+    const inventory = [];
+    for (const entry of entries) {
+        if (entry.path !== "package" && !entry.path.startsWith("package/"))
+            refuse("foreign_payload_root");
+        if (entry.kind !== "file")
+            continue;
+        const logical = entry.path.slice("package/".length);
+        if (!logical || logical === "engine.json")
+            refuse("reserved_payload_path");
+        inventory.push({ path: logical, sha256: hash(entry.bytes), executable_mode: entry.mode & 0o111, bytes: entry.bytes.length });
+    }
+    return inventory;
+}
+/** Existing package/dependency acquisition supplies the independently selected
+ * full checksum. This gate binds transferred package files to verified setup
+ * bytes before delivery and again in the owned staging directory. */
+export function deliverMemoryInitReleaseEngine(context, input) {
+    const home = context.ddFlowHome;
+    if (!path.isAbsolute(home) || fs.realpathSync(home) !== home || !path.isAbsolute(input.packageRoot)
+        || fs.realpathSync(input.packageRoot) !== input.packageRoot || !/^[a-f0-9]{64}$/.test(input.expectedChecksum))
+        refuse("invalid_delivery_selection");
+    const selected = readSetupStatus(home), installation = selected.installation;
+    if (!installation || selected.installation_readiness !== "installed" || installation.manifest_sha256 !== input.installationSha256)
+        refuse("installation_selection_changed");
+    const inventory = archiveInventory(installation.manifest.engine.archive, installation.engine_root);
+    const check = (root) => {
+        try {
+            for (const file of inventory)
+                checkFile(root, file);
+            checkInventory(root, inventory);
+            if (engineSnapshotChecksum(root) !== input.expectedChecksum)
+                refuse("delivery_checksum_changed");
+            const current = readSetupStatus(home);
+            if (current.installation_readiness !== "installed" || hybridDigest(current.installation) !== hybridDigest(installation))
+                refuse("installation_changed_during_delivery");
+        }
+        catch (error) {
+            if (error instanceof AppError && error.code === "memory_init_engine_release_invalid")
+                throw error;
+            return refuse("payload_unavailable_or_changed");
+        }
+    };
+    check(input.packageRoot);
+    const delivered = installPackageEngine(context, { packageRoot: input.packageRoot, packageName: installation.manifest.engine.package,
+        version: installation.manifest.engine.version, expectedChecksum: input.expectedChecksum, validateStaged: check });
+    try {
+        return selectMemoryInitInstalledEngine(home, input.installationSha256, input.expectedChecksum);
+    }
+    catch (error) {
+        throw new AppError("memory_init_engine_delivery_incomplete", "Delivered engine requires exact selection reconciliation", 1, { effect: delivered.changed ? "partial" : "no_effect", path: delivered.path, reason: error instanceof AppError ? error.details.reason ?? error.code : "delivered_selection_changed" });
+    }
+}
+/** expectedSha256 must come from independent request custody. No current
+ * installation/canon/profile reads and no restoration of missing files. */
+export function revalidateMemoryInitEngineRelease(input, expectedSha256, engine) {
+    try {
+        if (!(engine instanceof AdmittedFrozenEngine) || !input || typeof input !== "object" || Array.isArray(input))
+            refuse("invalid_retained_pairing");
+        const facts = input, digest = (value) => typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+        if (Object.keys(facts).sort().join() !== "archive_sha256,engine_manifest_sha256,engine_sha256,installation_sha256,inventory,schema_id"
+            || facts.schema_id !== "dd-flow/memory-init-engine-release@1" || !digest(expectedSha256)
+            || [facts.installation_sha256, facts.archive_sha256, facts.engine_manifest_sha256, facts.engine_sha256].some(value => !digest(value))
+            || !Array.isArray(facts.inventory) || !facts.inventory.length || facts.inventory.length > 100_000
+            || hybridDigest(facts) !== expectedSha256)
+            refuse("invalid_retained_pairing");
+        const manifest = engine.manifest();
+        if (engine.manifestSha256 !== facts.engine_manifest_sha256 || manifest.integrity.checksum !== facts.engine_sha256)
+            refuse("foreign_engine_identity");
+        const seen = new Set();
+        let total = 0;
+        for (const entry of facts.inventory) {
+            if (!entry || Object.keys(entry).sort().join() !== "bytes,executable_mode,path,sha256" || typeof entry.path !== "string"
+                || entry.path.length > 1024 || entry.path !== entry.path.normalize("NFC") || /[\\:]/.test(entry.path)
+                || [...entry.path].some(character => character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127)
+                || entry.path.split("/").some(part => !part || part === "." || part === "..") || entry.path === "engine.json"
+                || seen.has(entry.path.toLowerCase()) || !digest(entry.sha256) || !Number.isSafeInteger(entry.bytes) || entry.bytes < 0
+                || entry.bytes === 0 && entry.sha256 !== hash(Buffer.alloc(0))
+                || !Number.isSafeInteger(entry.executable_mode) || entry.executable_mode < 0 || entry.executable_mode > 0o111 || (entry.executable_mode & ~0o111) !== 0
+                || (total += entry.bytes) > 512 * 1024 * 1024)
+                refuse("invalid_retained_inventory");
+            seen.add(entry.path.toLowerCase());
+            checkFile(manifest.snapshot_root, entry);
+        }
+        checkInventory(manifest.snapshot_root, facts.inventory);
+        AdmittedFrozenEngine.admitSelection({ package_name: manifest.package_name, package_version: manifest.package_version,
+            engine_version: manifest.engine_version, snapshot_root: manifest.snapshot_root, integrity_checksum: facts.engine_sha256 }, facts.engine_manifest_sha256);
+        return { facts: structuredClone(facts), sha256: expectedSha256 };
+    }
+    catch (error) {
+        if (error instanceof AppError && error.code === "memory_init_engine_release_invalid")
+            throw error;
+        return refuse("payload_unavailable_or_changed");
+    }
+}
+/** Fresh selection only. Restarts must retain this inventory independently,
+ * not consult the current installation. This does not install dependencies,
+ * admit handlers/storage/provider access or grant project effects. */
+export function prepareMemoryInitEngineRelease(home, installationSha256, engine) {
+    try {
+        if (!(engine instanceof AdmittedFrozenEngine))
+            refuse("unprepared_engine");
+        if (!path.isAbsolute(home) || path.resolve(home) !== home || fs.realpathSync(home) !== home)
+            refuse("noncanonical_installation_home");
+        const selected = readSetupStatus(home), installation = selected.installation;
+        if (!installation || selected.installation_readiness !== "installed" || installation.manifest_sha256 !== installationSha256)
+            refuse("installation_selection_changed");
+        const manifest = engine.manifest();
+        if (manifest.package_name !== installation.manifest.engine.package || manifest.package_version !== installation.manifest.engine.version)
+            refuse("foreign_engine_identity");
+        AdmittedFrozenEngine.admitSelection({ 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 }, engine.manifestSha256);
+        const archive = installation.manifest.engine.archive;
+        const inventory = archiveInventory(archive, installation.engine_root);
+        const final = readSetupStatus(home);
+        if (final.installation_readiness !== "installed" || hybridDigest(final.installation) !== hybridDigest(installation))
+            refuse("installation_changed_during_admission");
+        const facts = { schema_id: "dd-flow/memory-init-engine-release@1", installation_sha256: installationSha256,
+            archive_sha256: archive.sha256, engine_manifest_sha256: engine.manifestSha256,
+            engine_sha256: manifest.integrity.checksum, inventory: inventory.sort((a, b) => a.path.localeCompare(b.path, "en")) };
+        return revalidateMemoryInitEngineRelease(facts, hybridDigest(facts), engine);
+    }
+    catch (error) {
+        if (error instanceof AppError && error.code === "memory_init_engine_release_invalid")
+            throw error;
+        return refuse("payload_unavailable_or_changed");
+    }
+}