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

package/dist/services/memory-init-bootstrap-readiness.js

@@ -0,0 +1,210 @@
+import { createHash } from "node:crypto";
+import { Ajv2020 } from "ajv/dist/2020.js";
+import { AppError } from "../shared/errors.js";
+import { appendAudit } from "./audit.js";
+import { AdmittedFrozenEngine } from "./frozen-engine.js";
+import { hybridDigest, validateHybridContract } from "./hybrid-contracts.js";
+import { PreparedMemoryInitProjectBootstrap, readMemoryInitProjectBootstrap, readMemoryInitProjectBootstrapEngineAdmission, readMemoryInitReleaseSelection } from "./memory-init-project-bootstrap.js";
+const receiptEvent = "memory.bootstrap_ready", intentEvent = "memory.bootstrap_readiness_intent";
+const bytes = (value) => Buffer.from(JSON.stringify(value));
+const hash = (value) => createHash("sha256").update(value).digest("hex");
+function refuse(reason) {
+    throw new AppError("memory_init_bootstrap_readiness_invalid", "Bootstrap readiness lacks exact independently accepted custody", 1, { reason, effect: "no_effect", next_action: "reconcile_exact_request" });
+}
+function decoded(base64, sha256) {
+    if (typeof base64 !== "string" || base64.length > 2 * 1024 * 1024 || !/^[a-f0-9]{64}$/.test(sha256))
+        refuse("invalid_manifest_binding");
+    const content = Buffer.from(base64, "base64");
+    if (!content.length || content.length > 1024 * 1024 || content.toString("base64") !== base64 || hash(content) !== sha256)
+        refuse("changed_manifest_bytes");
+    return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(content));
+}
+/** Exact selected contract support, before invoking bootstrap publication. The
+ * public dispatcher must call this before its first project effect, not discover
+ * an unsupported engine after installing drafts. No provider operation occurs.
+ */
+export function prepareMemoryInitBootstrapSchema(engine) {
+    if (!(engine instanceof AdmittedFrozenEngine))
+        refuse("selected_engine_not_admitted");
+    const manifest = engine.manifest(), id = "dd-flow/memory-bootstrap-receipt@2";
+    const entries = manifest.schema_registry?.entries.filter(entry => entry.id === id) ?? [];
+    if (!Object.values(manifest.supports_contracts).flat().includes(id) || entries.length !== 1)
+        refuse("bootstrap_contract_not_supported");
+    return new Ajv2020({ strict: true, validateFormats: false }).compile(JSON.parse(engine.schema(entries[0].name).toString("utf8")));
+}
+/** Pure receipt construction from the prepared selection and accepted SQL
+ * dependencies. It is also used by writers/readers; no filesystem/schema IO.
+ */
+function material(context, binding) {
+    const scope = binding.scope, registered = readMemoryInitProjectBootstrap(context, scope);
+    const accepted = readMemoryInitProjectBootstrapEngineAdmission(context, scope);
+    const selection = readMemoryInitReleaseSelection(context, scope);
+    if (!registered || !accepted || registered.receipt.schema_id !== "dd-flow/memory-init-project-bootstrap@4"
+        || accepted.bootstrap_sha256 !== registered.sha256
+        || registered.receipt.target_sha256 !== hybridDigest(binding.target)
+        || registered.receipt.execution_sha256 !== binding.execution_sha256
+        || binding.target.request_id !== scope.requestId || binding.target.project_root !== scope.projectRoot
+        || binding.target.workspace_root !== scope.workspaceRoot
+        || binding.git_policy_sha256 !== accepted.git_policy_sha256
+        || !/^[a-f0-9]{64}$/.test(binding.pack_sha256))
+        refuse("changed_bootstrap_dependencies");
+    if (!selection || selection.bootstrap_identity !== registered.receipt.identity
+        || selection.execution_sha256 !== binding.execution_sha256 || selection.pack_sha256 !== binding.pack_sha256
+        || selection.installation_manifest_sha256 !== binding.installation_manifest_sha256
+        || selection.installation_manifest_base64 !== binding.installation_manifest_base64)
+        refuse("changed_release_selection");
+    if (!context.db.get("SELECT 1 FROM projects WHERE id=? AND root=? AND status='active'", [registered.receipt.project_id, scope.projectRoot]))
+        refuse("project_not_active");
+    const release = decoded(binding.installation_manifest_base64, binding.installation_manifest_sha256);
+    const engine = decoded(binding.engine_manifest_base64, accepted.proof.engine_manifest_sha256);
+    const engineSha256 = accepted.proof.engine_sha256;
+    if (typeof engineSha256 !== "string" || !/^[a-f0-9]{64}$/.test(engineSha256))
+        refuse("invalid_engine_identity");
+    if (release.engine.package !== engine.package_name || release.engine.version !== engine.package_version
+        || engine.integrity.checksum !== accepted.proof.engine_sha256)
+        refuse("foreign_selected_engine");
+    const fact = { requestId: scope.requestId, projectRoot: scope.projectRoot, workspace: scope.workspaceRoot };
+    const evidence = [
+        { kind: "storage-compatibility", path: "receipts/storage-compatibility.json", value: { schema_id: "dd-flow/memory-init-storage-evidence@1", scope, admission_identity: accepted.identity, proof: accepted.proof } },
+        { kind: "scaffold", path: "receipts/scaffold.json", value: { schema_id: "dd-flow/memory-init-scaffold-evidence@1", scope, bootstrap_sha256: registered.sha256, receipt: registered.receipt } },
+        { kind: "pack-install", path: "receipts/pack-install.json", value: { schema_id: "dd-flow/memory-init-pack-evidence@1", scope, bootstrap_sha256: registered.sha256, layer_sha256: registered.receipt.layer_sha256, pack_sha256: binding.pack_sha256, installation_sha256: binding.installation_manifest_sha256 } }
+    ].map(entry => ({ kind: entry.kind, path: entry.path, sha256: hash(bytes(entry.value)), base64: bytes(entry.value).toString("base64") }));
+    const reference = (index) => ({ path: evidence[index].path, sha256: evidence[index].sha256 });
+    const receipt = { schema_id: "dd-flow/memory-bootstrap-receipt@2", request_id: scope.requestId, flow_id: "mb-init",
+        project_root: scope.projectRoot, workspace: { path: scope.workspaceRoot, repository: binding.target.repository,
+            branch: binding.target.branch, commit: binding.target.head, git_state: binding.target.head === null ? "unborn" : "committed" },
+        baseline_sha256: registered.receipt.target_sha256, project_current: null,
+        upgrade_target: { canon_version: release.canon.version, pack_sha256: binding.pack_sha256 },
+        effective_execution: { engine_sha256: engineSha256, canon_sha256: release.canon.archive.sha256 },
+        readiness: "ready", storage: { route: "verified-no-op", outcome: "no-op", compatibility_receipt: reference(0),
+            drain_receipt: null, backup_receipt: null, plan_receipt: null, apply_receipt: null, verification_receipt: null },
+        effects: [{ kind: "scaffold", receipt: reference(1) }, { kind: "pack-install", receipt: reference(2) }] };
+    const admission = { receipts: new Map(evidence.map(entry => [entry.sha256, { kind: entry.kind, ...fact }])),
+        bootstrapIdentity: { ...fact, baselineSha256: registered.receipt.target_sha256,
+            engineSha256, canonSha256: release.canon.archive.sha256,
+            workspaceGit: { repository: binding.target.repository, branch: binding.target.branch, commit: binding.target.head } } };
+    const authority = { schema_id: "dd-flow/memory-bootstrap-authority@1", request_id: scope.requestId, project_root: scope.projectRoot,
+        workspace_root: scope.workspaceRoot, flow_id: "mb-init", readiness: "ready", model_access: "unknown",
+        bootstrap_sha256: hash(bytes(receipt)), project_bootstrap_sha256: registered.sha256,
+        engine_admission_identity: accepted.identity, binding, receipt, evidence };
+    return { authority, admission, projectId: registered.receipt.project_id };
+}
+function row(context, scope, event) {
+    const rows = context.db.all("SELECT project_id,payload_json FROM audit_events WHERE event_type=? AND json_extract(payload_json,'$.request_id')=? AND json_extract(payload_json,'$.project_root')=? AND json_extract(payload_json,'$.workspace_root')=? LIMIT 2", [event, scope.requestId, scope.projectRoot, scope.workspaceRoot]);
+    if (rows.length > 1)
+        refuse("ambiguous_readiness_custody");
+    if (!rows.length)
+        return null;
+    if (Buffer.byteLength(rows[0].payload_json) > 4 * 1024 * 1024)
+        refuse("unbounded_readiness_custody");
+    return { ...rows[0], value: JSON.parse(rows[0].payload_json) };
+}
+/** Historical readiness custody only. Current physical admission belongs to
+ * prepare/apply. Loss of either independent record cannot republish authority.
+ */
+export function readMemoryInitBootstrapReadiness(context, scope) {
+    try {
+        return context.db.readSnapshot(() => {
+            const retained = row(context, scope, receiptEvent), intent = row(context, scope, intentEvent);
+            if (!retained && !intent)
+                return null;
+            if (!retained || !intent)
+                refuse("readiness_custody_missing");
+            const binding = retained.value.binding;
+            if (!binding || hybridDigest(binding.scope) !== hybridDigest(scope)
+                || (Object.hasOwn(binding, "git_policy_sha256") && (typeof binding.git_policy_sha256 !== "string" || !/^[a-f0-9]{64}$/.test(binding.git_policy_sha256)))
+                || Object.keys(binding).sort().join() !== (Object.hasOwn(binding, "git_policy_sha256")
+                    ? "engine_manifest_base64,execution_sha256,git_policy_sha256,installation_manifest_base64,installation_manifest_sha256,pack_sha256,scope,target"
+                    : "engine_manifest_base64,execution_sha256,installation_manifest_base64,installation_manifest_sha256,pack_sha256,scope,target"))
+                refuse("invalid_readiness_binding");
+            const selected = material(context, binding), expected = { schema_id: "dd-flow/memory-bootstrap-readiness-intent@1", request_id: scope.requestId,
+                project_root: scope.projectRoot, workspace_root: scope.workspaceRoot, authority_sha256: hybridDigest(selected.authority) };
+            if (retained.project_id !== selected.projectId || intent.project_id !== selected.projectId
+                || hybridDigest(retained.value) !== hybridDigest(selected.authority) || hybridDigest(intent.value) !== hybridDigest(expected))
+                refuse("changed_readiness_custody");
+            return { ...selected, authority: structuredClone(selected.authority) };
+        });
+    }
+    catch (error) {
+        if (error instanceof AppError)
+            throw error;
+        return refuse("invalid_readiness_custody");
+    }
+}
+/** Request-owned runtime readiness, not semantic memory acceptance or account
+ * qualification. Provider failures after this receipt keep a partial bootstrap;
+ * no hidden model turn is dispatched to obtain the receipt.
+ */
+export class PreparedMemoryInitBootstrapReadiness {
+    #bootstrap;
+    #engine;
+    #binding;
+    #material;
+    constructor(bootstrap, engine, binding, selected) {
+        this.#bootstrap = bootstrap;
+        this.#engine = engine;
+        this.#binding = structuredClone(binding);
+        this.#material = selected;
+        Object.freeze(this);
+    }
+    static prepare(context, input) {
+        if (!(input.bootstrap instanceof PreparedMemoryInitProjectBootstrap))
+            refuse("unprepared_project_bootstrap");
+        const validate = prepareMemoryInitBootstrapSchema(input.engine);
+        const { registered: _registered, accepted: _accepted, ...binding } = input.bootstrap.prepareReadiness(context, input.engine);
+        void _registered;
+        void _accepted;
+        const selected = context.db.readSnapshot(() => material(context, binding));
+        if (!validate(selected.authority.receipt) || validateHybridContract("memory-bootstrap-receipt", selected.authority.receipt, selected.admission).length)
+            refuse("invalid_bootstrap_contract");
+        const prior = readMemoryInitBootstrapReadiness(context, binding.scope);
+        if (prior && hybridDigest(prior.authority) !== hybridDigest(selected.authority))
+            refuse("changed_readiness_request");
+        return new PreparedMemoryInitBootstrapReadiness(input.bootstrap, input.engine, binding, selected);
+    }
+    apply(context) {
+        const { registered: _registered, accepted: _accepted, ...current } = this.#bootstrap.prepareReadiness(context, this.#engine);
+        void _registered;
+        void _accepted;
+        if (hybridDigest(current) !== hybridDigest(this.#binding))
+            refuse("readiness_changed_after_preparation");
+        return context.db.writeTransaction(() => {
+            const selected = material(context, this.#binding);
+            if (hybridDigest(selected.authority) !== hybridDigest(this.#material.authority))
+                refuse("changed_bootstrap_dependencies");
+            const prior = readMemoryInitBootstrapReadiness(context, this.#binding.scope);
+            if (prior) {
+                if (hybridDigest(prior.authority) !== hybridDigest(selected.authority))
+                    refuse("changed_readiness_request");
+                return { ...prior, changed: false };
+            }
+            const scope = this.#binding.scope;
+            appendAudit(context, { projectId: selected.projectId, eventType: intentEvent,
+                payload: { schema_id: "dd-flow/memory-bootstrap-readiness-intent@1", request_id: scope.requestId, project_root: scope.projectRoot,
+                    workspace_root: scope.workspaceRoot, authority_sha256: hybridDigest(selected.authority) } });
+            appendAudit(context, { projectId: selected.projectId, eventType: receiptEvent, payload: selected.authority });
+            const accepted = readMemoryInitBootstrapReadiness(context, scope);
+            if (!accepted)
+                refuse("readiness_not_committed");
+            return { ...accepted, changed: true };
+        }, "memoryInit.bootstrapReadiness");
+    }
+}
+/** Productive bootstrap entry: contract admission precedes all project effects.
+ * A failure after draft publication is explicitly partial and resumes the same
+ * request; it never substitutes fresh initialization or a paid route probe.
+ */
+export function bootstrapMemoryInit(context, input, checkpoint) {
+    if (!(input.bootstrap instanceof PreparedMemoryInitProjectBootstrap))
+        refuse("unprepared_project_bootstrap");
+    prepareMemoryInitBootstrapSchema(input.engine);
+    const registered = input.bootstrap.applyWithEngine(context, input.engine, checkpoint);
+    try {
+        return PreparedMemoryInitBootstrapReadiness.prepare(context, input).apply(context);
+    }
+    catch (error) {
+        throw new AppError("memory_init_bootstrap_readiness_failed", "Project drafts are retained but bootstrap readiness is incomplete", 1, { effect: "partial", project_bootstrap_sha256: registered.sha256,
+            reason: error instanceof AppError ? error.details.reason ?? error.code : "readiness_operation_failed",
+            next_action: "reconcile_exact_request" });
+    }
+}

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

@@ -0,0 +1,89 @@
+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";
+/** 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) {
+    if (!(bundle instanceof RetainedExecutionBundle) || bundle.manifest.flow_id !== "mb-init"
+        || 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) {
+    const prepared = prepareMemoryInitContexts(bundle, objective, directory);
+    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,84 @@
+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 { 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 } from "./memory-init-contexts.js";
+import { parseRuntimeBudget } from "./runtime-budget.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) {
+    validateMemoryInitStartupScope(scope);
+    if (context.db.isOwnedWriteTransaction?.())
+        refuse("preparation_outside_writer_required");
+    parseRuntimeBudget(context.env.DD_FLOW_RUNTIME_BUDGET);
+    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 !== "mb-init"
+        || 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 = startMemoryInitRun(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 = prepareMemoryInitContextsFromStartup(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");
+    publishMemoryInitContexts(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");
+    }
+}