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

package/dist/services/frozen-engine.js

@@ -0,0 +1,387 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { Ajv } from "ajv/dist/ajv.js";
+import { AppError } from "../shared/errors.js";
+import { engineSnapshotChecksum } from "./engines.js";
+import { readBoundedReleaseFile } from "./release-source.js";
+import { shellArgument } from "./runtime-command.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { isMemoryInitResourceStorageFacts } from "./memory-init-resource-storage.js";
+import { memoryInitStartupInputSchemas } from "./memory-init-startup-custody.js";
+import { SETUP_STARTUP_MS } from "../harness-runtime/lib/setup-progress.mjs";
+import { isDiagnosticFlow } from "../domain/diagnostic-flows.js";
+function storageProbeRefuse(reason, probe) {
+    const summary = probe ? ` (${probe.error_code ?? probe.signal ?? `exit ${probe.status}`})` : "";
+    throw new AppError("frozen_engine_storage_incompatible", `Selected frozen engine cannot admit memory-flow storage${summary}`, 1, { reason, effect: "no_effect", ...(probe ? { probe } : {}) });
+}
+function probeFailure(result) {
+    const code = result.error?.code ?? null;
+    return { status: result.status, signal: result.signal, error_code: code, timed_out: code === "ETIMEDOUT",
+        timeout_ms: SETUP_STARTUP_MS, stdout_bytes: result.stdout?.length ?? null, stderr_bytes: result.stderr?.length ?? null };
+}
+const hash = (bytes) => crypto.createHash("sha256").update(bytes).digest("hex");
+function refuse(reason) {
+    throw new AppError("frozen_engine_invalid", "Frozen engine cannot be admitted", 1, { reason, phase: "prepare", effect: "no_effect" });
+}
+function json(bytes) {
+    try {
+        return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        return refuse("invalid_utf8_json");
+    }
+}
+function shape(name, value, property) {
+    const schema = JSON.parse(fs.readFileSync(new URL(`../schemas/${name}.schema.json`, import.meta.url), "utf8"));
+    return new Ajv({ strict: false, validateFormats: false }).compile(property ? schema.properties[property] : schema)(value) === true;
+}
+function containedFile(root, relative) {
+    if (path.isAbsolute(relative) || relative.split(/[\\/]/).some(part => part === ".." || part === "." || !part))
+        refuse("escaping_engine_path");
+    const parts = relative.split(/[\\/]/);
+    let current = root;
+    for (const [index, part] of parts.entries()) {
+        current = path.join(current, part);
+        const stat = fs.lstatSync(current);
+        if (stat.isSymbolicLink() || (index === parts.length - 1 ? !stat.isFile() : !stat.isDirectory()))
+            refuse("non_regular_engine_path");
+    }
+    return current;
+}
+/** New-bundle admission only. It does not replace historical binding or storage admission. */
+export class AdmittedFrozenEngine {
+    manifestSha256;
+    entrypoint;
+    nodeExecutable;
+    #manifest;
+    #bytes;
+    constructor(manifest, bytes, entrypoint) {
+        this.#manifest = manifest;
+        this.#bytes = bytes;
+        this.manifestSha256 = hash(bytes);
+        this.entrypoint = entrypoint;
+        this.nodeExecutable = fs.realpathSync(process.execPath);
+        Object.freeze(this);
+    }
+    /** Both hashes are independently selected by the RUN/bundle authority. No subprocess probe. */
+    static admit(binding, expectedManifestSha256) {
+        if (!shape("run-engine-binding", binding) || !/^[a-f0-9]{64}$/.test(expectedManifestSha256))
+            refuse("invalid_binding_identity");
+        return AdmittedFrozenEngine.fromIdentity(binding.engine, expectedManifestSha256);
+    }
+    /** Pre-RUN selection: no invented RUN id, binding or allocation authority. */
+    static admitSelection(identity, expectedManifestSha256) {
+        if (!shape("run-engine-binding", identity, "engine") || !/^[a-f0-9]{64}$/.test(expectedManifestSha256))
+            refuse("invalid_selection_identity");
+        return AdmittedFrozenEngine.fromIdentity(identity, expectedManifestSha256);
+    }
+    /** Physical relocation preserves the original manifest as provenance. It
+     * cannot authorize a different executable or different semantic metadata. */
+    static admitRelocation(binding, retained, expectedSha256, target) {
+        if (hash(retained) !== expectedSha256 || !shape("run-engine-binding", binding)
+            || !shape("run-engine-binding", target) || binding.run_id !== target.run_id)
+            refuse("invalid_relocation_identity");
+        const value = json(retained);
+        if (!shape("engine-manifest", value))
+            refuse("invalid_manifest_shape");
+        const original = value;
+        if (original.snapshot_root !== binding.engine.snapshot_root
+            || original.package_name !== binding.engine.package_name || original.package_version !== binding.engine.package_version
+            || original.engine_version !== binding.engine.engine_version || original.integrity.checksum !== binding.engine.integrity_checksum
+            || Object.entries(binding.engine).some(([key, value]) => key !== "snapshot_root" && value !== target.engine[key])) {
+            refuse("foreign_relocation_identity");
+        }
+        try {
+            const bytes = readBoundedReleaseFile(path.join(target.engine.snapshot_root, "engine.json"), 1024 * 1024);
+            const selected = AdmittedFrozenEngine.admit(target, hash(bytes));
+            const semantic = (manifest) => Object.fromEntries(Object.entries(manifest)
+                .filter(([key]) => !["snapshot_root", "package_root", "installed_at", "install_source"].includes(key)));
+            if (hybridDigest(semantic(original)) !== hybridDigest(semantic(selected.manifest())))
+                refuse("relocated_manifest_changed");
+            return selected;
+        }
+        catch (error) {
+            if (error instanceof AppError && error.code === "frozen_engine_invalid")
+                throw error;
+            return refuse("snapshot_unavailable_or_unreadable");
+        }
+    }
+    static fromIdentity(identity, expectedManifestSha256) {
+        try {
+            const root = path.resolve(identity.snapshot_root);
+            if (!path.isAbsolute(identity.snapshot_root) || !fs.lstatSync(root).isDirectory())
+                refuse("missing_or_linked_snapshot");
+            const bytes = readBoundedReleaseFile(path.join(root, "engine.json"), 1024 * 1024);
+            if (hash(bytes) !== expectedManifestSha256)
+                refuse("manifest_bytes_changed");
+            const value = json(bytes);
+            if (!shape("engine-manifest", value))
+                refuse("invalid_manifest_shape");
+            const manifest = value;
+            if (manifest.package_name !== identity.package_name || manifest.package_version !== identity.package_version
+                || manifest.engine_version !== identity.engine_version || path.resolve(manifest.snapshot_root) !== root
+                || manifest.integrity.mode !== "full_content" || manifest.integrity.checksum !== identity.integrity_checksum)
+                refuse("foreign_manifest_identity");
+            if (engineSnapshotChecksum(root) !== identity.integrity_checksum)
+                refuse("executable_snapshot_changed");
+            const entrypoint = containedFile(root, manifest.entrypoint);
+            if (!manifest.schema_registry || manifest.schema_registry.entries.length === 0)
+                refuse("missing_schema_registry");
+            const names = new Set(), paths = new Set();
+            for (const entry of manifest.schema_registry.entries) {
+                if (names.has(entry.name) || paths.has(entry.path))
+                    refuse("ambiguous_schema_registry");
+                names.add(entry.name);
+                paths.add(entry.path);
+                const schemaBytes = readBoundedReleaseFile(containedFile(root, entry.path), 1024 * 1024);
+                if (hash(schemaBytes) !== entry.checksum || json(schemaBytes)?.$id !== entry.id)
+                    refuse("schema_registry_identity_changed");
+            }
+            return new AdmittedFrozenEngine(manifest, bytes, entrypoint);
+        }
+        catch (error) {
+            if (error instanceof AppError && error.code === "frozen_engine_invalid")
+                throw error;
+            return refuse("snapshot_unavailable_or_unreadable");
+        }
+    }
+    manifest() { return structuredClone(this.#manifest); }
+    manifestBytes() { return Buffer.from(this.#bytes); }
+    /** Qualify actual descriptor handlers in this immutable executable, not the
+     * invoking CLI catalog. No storage or productive operation is admitted. */
+    admitMemoryInitFlow(source, startupInputSchema) {
+        return this.#admitMemoryFlow(source, "mb-init", startupInputSchema);
+    }
+    admitMemoryUpgradeFlow(source) {
+        return this.#admitMemoryFlow(source, "mb-upgrade");
+    }
+    admitDiagnosticFlow(source, flowId) {
+        return this.#admitMemoryFlow(source, flowId);
+    }
+    #admitMemoryFlow(source, flowId, startupInputSchema) {
+        const fail = (reason, details = {}) => {
+            throw new AppError("frozen_engine_flow_incompatible", `Selected frozen engine cannot admit ${flowId} handlers`, 1, { ...details, reason, phase: "prepare", effect: "no_effect" });
+        };
+        const revalidate = () => {
+            try {
+                if (hash(readBoundedReleaseFile(path.join(this.#manifest.snapshot_root, "engine.json"), 1024 * 1024)) !== this.manifestSha256
+                    || engineSnapshotChecksum(this.#manifest.snapshot_root) !== this.#manifest.integrity.checksum)
+                    fail("engine_changed_during_admission");
+                // Historical checksums exclude every engine.json path, including a
+                // nested directory. New memory execution must not admit unhashed code;
+                // do not change the checksum algorithm used by existing SDLC RUNs.
+                if (fs.readdirSync(this.#manifest.snapshot_root, { recursive: true, withFileTypes: true })
+                    .some(entry => entry.name === "engine.json" && path.resolve(entry.parentPath) !== this.#manifest.snapshot_root))
+                    fail("unhashed_engine_path");
+            }
+            catch (error) {
+                if (error instanceof AppError && error.code === "frozen_engine_flow_incompatible")
+                    throw error;
+                fail("engine_unavailable_during_admission");
+            }
+        };
+        if (startupInputSchema !== undefined && !memoryInitStartupInputSchemas.includes(startupInputSchema))
+            fail("unsupported_startup_input_schema");
+        const input = Buffer.from(JSON.stringify({ source: source.snapshot(), source_sha256: source.sha256,
+            ...(startupInputSchema === undefined ? {} : { startup_input_schema: startupInputSchema }) }));
+        if (input.length > 64 * 1024 * 1024)
+            fail("unbounded_source");
+        const flow = source.resolveRegisteredFlow();
+        if (flow.descriptor.id !== flowId)
+            fail("foreign_flow_source");
+        const expected = { schema_id: isDiagnosticFlow(flowId) ? "dd-flow/diagnostic-engine-flow@1" : flowId === "mb-upgrade" ? "dd-flow/memory-upgrade-engine-flow@1"
+                : startupInputSchema === undefined ? "dd-flow/memory-init-engine-flow@1" : "dd-flow/memory-init-engine-flow@2",
+            ...(startupInputSchema === undefined ? {} : { startup_input_schema: startupInputSchema }),
+            flow_id: flowId, source_sha256: source.sha256,
+            descriptor_sha256: source.descriptorReference().sha256, stages: flow.descriptor.stages.map(stage => stage.id) };
+        revalidate();
+        const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !["NODE_OPTIONS", "NODE_PATH"].includes(key) && !key.startsWith("DD_FLOW_")));
+        const started = performance.now();
+        const result = spawnSync(this.nodeExecutable, [this.entrypoint, "runtime", "flow", "admit", "--operation", isDiagnosticFlow(flowId) ? flowId : flowId === "mb-init" ? "memory-init" : "memory-upgrade", "--json"], { input, cwd: this.#manifest.snapshot_root, env: { ...env, DD_FLOW_ENGINE_MODE: "1", DD_FLOW_ENGINE_HOME: this.#manifest.snapshot_root },
+            // This is cold startup of a selected CLI, not an already-loaded handler.
+            // Admission is bounded local validation; no provider operation is started.
+            timeout: SETUP_STARTUP_MS, maxBuffer: 1024 * 1024, shell: false, windowsHide: true });
+        if (result.error || result.signal || result.status !== 0)
+            fail("selected_engine_probe_failed", {
+                ...probeFailure(result), operation: flowId, elapsed_ms: Math.round(performance.now() - started), probe: probeFailure(result)
+            });
+        revalidate();
+        let response;
+        try {
+            response = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(result.stdout));
+        }
+        catch {
+            return fail("invalid_probe_json");
+        }
+        if (!response || typeof response !== "object" || Array.isArray(response) || Object.keys(response).sort().join() !== "action,facts,ok,sha256"
+            || response.ok !== true || response.action !== "runtime_flow_admit" || !response.facts || typeof response.facts !== "object" || Array.isArray(response.facts)
+            || hybridDigest(response.facts) !== hybridDigest(expected)
+            || response.sha256 !== hybridDigest(expected))
+            fail("invalid_probe_response");
+        return { facts: structuredClone(expected), sha256: hybridDigest(expected), engine_manifest_sha256: this.manifestSha256,
+            engine_sha256: this.#manifest.integrity.checksum };
+    }
+    /** Execute admission in the selected immutable engine, never in the invoking CLI.
+     * This qualifies storage connections only, not provider or flow readiness.
+     */
+    admitMemoryInitStorage(home, resourceHome) {
+        return this.admitMemoryStorage(home, resourceHome, "memory-init");
+    }
+    /** A distinct operation: old engines cannot accidentally claim support for
+     * upgrade request custody merely because init storage admission succeeds. */
+    admitMemoryUpgradeStorage(home, resourceHome) {
+        return this.admitMemoryStorage(home, resourceHome, "memory-upgrade");
+    }
+    /** Execute storage transition in this exact snapshot before AppContext opens
+     * a writer. A timeout or malformed acknowledgement never proves no effect. */
+    qualifyMemoryUpgradeStorage(home, resourceHome) {
+        const intact = () => hash(readBoundedReleaseFile(path.join(this.#manifest.snapshot_root, "engine.json"), 1024 * 1024)) === this.manifestSha256
+            && engineSnapshotChecksum(this.#manifest.snapshot_root) === this.#manifest.integrity.checksum;
+        if (!intact())
+            refuse("engine_changed_before_storage_qualification");
+        const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !["NODE_OPTIONS", "NODE_PATH"].includes(key)));
+        const reply = spawnSync(this.nodeExecutable, [this.entrypoint, "runtime", "storage", "qualify", "--operation", "memory-upgrade", "--json"], { env: { ...env, DD_FLOW_HOME: home, DD_FLOW_RESOURCE_HOME: resourceHome, DD_FLOW_ENGINE_MODE: "1", DD_FLOW_ENGINE_HOME: this.#manifest.snapshot_root },
+            encoding: "utf8", timeout: 120000, maxBuffer: 1024 * 1024, shell: false, windowsHide: true });
+        if (!intact())
+            refuse("engine_changed_during_storage_qualification");
+        if (reply.error || reply.signal || reply.status !== 0)
+            storageProbeRefuse("selected_engine_qualification_failed", { status: reply.status, signal: reply.signal });
+        let response;
+        try {
+            response = JSON.parse(reply.stdout);
+        }
+        catch {
+            return storageProbeRefuse("invalid_qualification_json");
+        }
+        const facts = response?.facts;
+        if (response?.ok !== true || response.action !== "runtime_storage_qualify" || facts?.schema_id !== "dd-flow/memory-upgrade-storage-capability@1"
+            || facts.operation !== "memory-upgrade" || !["verified-no-op", "migration"].includes(facts.route) || facts.productive_admission !== false
+            || hybridDigest(facts.source_stores) !== hybridDigest([path.join(home, "db.sqlite"), path.join(resourceHome, "runtime.sqlite")])
+            || response.sha256 !== hybridDigest(facts))
+            storageProbeRefuse("invalid_qualification_facts");
+        return { facts, sha256: response.sha256, engine_manifest_sha256: this.manifestSha256, engine_sha256: this.#manifest.integrity.checksum };
+    }
+    transitionMemoryUpgradeStorage(input) {
+        const intact = () => hash(readBoundedReleaseFile(path.join(this.#manifest.snapshot_root, "engine.json"), 1024 * 1024)) === this.manifestSha256
+            && engineSnapshotChecksum(this.#manifest.snapshot_root) === this.#manifest.integrity.checksum;
+        if (!intact())
+            refuse("engine_changed_before_storage_transition");
+        const args = ["runtime", "storage", "transition", "--action", input.action, "--project-root", input.scope.projectRoot,
+            "--workspace-root", input.scope.workspaceRoot, "--request-id", input.scope.requestId, "--selection-sha256", input.selectionSha256,
+            ...(input.expectedSha256 ? ["--expected-sha256", input.expectedSha256] : []), ...(input.recoveryId ? ["--recovery-id", input.recoveryId] : []),
+            ...(input.offline ? ["--offline"] : []), "--json"];
+        const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !["NODE_OPTIONS", "NODE_PATH"].includes(key)));
+        const reply = spawnSync(this.nodeExecutable, [this.entrypoint, ...args], { env: { ...env, DD_FLOW_HOME: input.home, DD_FLOW_RESOURCE_HOME: input.resourceHome,
+                DD_FLOW_ENGINE_MODE: "1", DD_FLOW_ENGINE_HOME: this.#manifest.snapshot_root }, encoding: "utf8", timeout: 120000, maxBuffer: 1024 * 1024, shell: false, windowsHide: true });
+        const fail = (reason, details = {}) => {
+            throw new AppError("frozen_engine_storage_transition_failed", "Observe or reconcile the original selected-engine storage request", 1, { reason, effect: "unknown", ...details });
+        };
+        let unchanged = false;
+        try {
+            unchanged = intact();
+        }
+        catch { /* Committed effects remain unknown if code custody is lost. */ }
+        if (!unchanged)
+            fail("engine_changed_during_storage_transition");
+        if (reply.error || reply.signal || reply.status !== 0) {
+            let child = {};
+            try {
+                child = JSON.parse(reply.stderr);
+            }
+            catch { /* Unknown acknowledgements retain unknown effect. */ }
+            fail("selected_engine_transition_failed", { status: reply.status, signal: reply.signal, error_code: reply.error?.code ?? null,
+                child_code: child.error?.code ?? null, child_reason: child.error?.details?.reason ?? null, effect: child.error?.details?.effect === "no_effect" ? "no_effect" : "unknown" });
+        }
+        let response;
+        try {
+            response = JSON.parse(reply.stdout);
+        }
+        catch {
+            return fail("invalid_transition_json");
+        }
+        if (!response || typeof response !== "object" || Array.isArray(response))
+            fail("invalid_transition_response");
+        const selected = response.engine;
+        if (response.ok !== true || response.action !== "runtime_storage_transition" || response.operation !== input.action
+            || !response.scope || typeof response.scope !== "object" || Array.isArray(response.scope)
+            || hybridDigest(response.scope) !== hybridDigest(input.scope) || response.selection_sha256 !== input.selectionSha256
+            || selected?.manifest_sha256 !== this.manifestSha256 || selected.sha256 !== this.#manifest.integrity.checksum)
+            fail("foreign_transition_acknowledgement");
+        return response;
+    }
+    admitMemoryStorage(home, resourceHome, operation) {
+        for (const root of [home, resourceHome]) {
+            if (!path.isAbsolute(root) || path.resolve(root) !== root || fs.realpathSync(root) !== root)
+                storageProbeRefuse("noncanonical_storage_home");
+        }
+        const revalidateEngine = () => {
+            if (hash(readBoundedReleaseFile(path.join(this.#manifest.snapshot_root, "engine.json"), 1024 * 1024)) !== this.manifestSha256
+                || engineSnapshotChecksum(this.#manifest.snapshot_root) !== this.#manifest.integrity.checksum)
+                storageProbeRefuse("engine_changed_during_admission");
+        };
+        revalidateEngine();
+        const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !["NODE_OPTIONS", "NODE_PATH"].includes(key)));
+        const started = performance.now();
+        const result = spawnSync(this.nodeExecutable, [this.entrypoint, "runtime", "storage", "admit", "--operation", operation, "--json"], { env: { ...env, DD_FLOW_HOME: home, DD_FLOW_RESOURCE_HOME: resourceHome, DD_FLOW_ENGINE_MODE: "1", DD_FLOW_ENGINE_HOME: this.#manifest.snapshot_root },
+            timeout: SETUP_STARTUP_MS, maxBuffer: 1024 * 1024, shell: false, windowsHide: true });
+        if (result.error || result.signal || result.status !== 0)
+            storageProbeRefuse("selected_engine_probe_failed", {
+                ...probeFailure(result), operation, elapsed_ms: Math.round(performance.now() - started)
+            });
+        revalidateEngine();
+        let response;
+        try {
+            response = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(result.stdout));
+        }
+        catch {
+            return storageProbeRefuse("invalid_probe_json");
+        }
+        if (!response || typeof response !== "object" || Array.isArray(response) || Object.keys(response).sort().join() !== "action,facts,ok,sha256"
+            || response.ok !== true || response.action !== "runtime_storage_admit")
+            storageProbeRefuse("invalid_probe_response");
+        const facts = response.facts, run = facts?.run;
+        if (!facts || Object.keys(facts).sort().join() !== "operation,outcome,resource,route,run,schema_id"
+            || facts.schema_id !== `dd-flow/${operation}-engine-storage@1` || facts.operation !== operation
+            || facts.route !== "verified-no-op" || facts.outcome !== "no-op" || response.sha256 !== hybridDigest(facts)
+            || !isMemoryInitResourceStorageFacts(facts.resource) || facts.resource.store_path !== path.join(resourceHome, "runtime.sqlite")
+            || !run || Object.keys(run).sort().join() !== "executing_writer_version,operation,outcome,route,schema_id,schema_sha256,store_dev,store_ino,store_kind,store_path"
+            || run.schema_id !== "dd-flow/memory-init-runtime-storage@1" || run.operation !== "memory-init" || run.store_kind !== "run"
+            || run.store_path !== path.join(home, "db.sqlite") || run.route !== "verified-no-op" || run.outcome !== "no-op"
+            || run.executing_writer_version !== 2 || typeof run.schema_sha256 !== "string" || !/^[a-f0-9]{64}$/.test(run.schema_sha256))
+            storageProbeRefuse("invalid_probe_facts");
+        for (const store of [run, facts.resource]) {
+            const stat = fs.lstatSync(store.store_path);
+            if (!stat.isFile() || stat.nlink !== 1 || stat.dev !== store.store_dev || stat.ino !== store.store_ino)
+                storageProbeRefuse("storage_identity_changed");
+        }
+        return { facts: structuredClone(facts), sha256: response.sha256, engine_manifest_sha256: this.manifestSha256,
+            engine_sha256: this.#manifest.integrity.checksum };
+    }
+    /** Read an exact registered schema from this snapshot, never the mutable CLI. */
+    schema(name) {
+        try {
+            if (!fs.lstatSync(this.#manifest.snapshot_root).isDirectory())
+                refuse("missing_or_linked_snapshot");
+            const entry = this.#manifest.schema_registry?.entries.find(item => item.name === name);
+            if (!entry)
+                refuse("schema_not_registered");
+            const bytes = readBoundedReleaseFile(containedFile(this.#manifest.snapshot_root, entry.path), 1024 * 1024);
+            if (hash(bytes) !== entry.checksum || json(bytes).$id !== entry.id)
+                refuse("schema_registry_identity_changed");
+            return Buffer.from(bytes);
+        }
+        catch (error) {
+            if (error instanceof AppError && error.code === "frozen_engine_invalid")
+                throw error;
+            return refuse("schema_unavailable");
+        }
+    }
+    /** No PATH/dd-flow fallback or mutable launcher environment reference. */
+    command(home, args) {
+        if (!path.isAbsolute(home))
+            refuse("runtime_home_not_absolute");
+        return `DD_FLOW_HOME=${shellArgument(home)} DD_FLOW_ENGINE_MODE=1 DD_FLOW_ENGINE_HOME=${shellArgument(this.#manifest.snapshot_root)} ${[this.nodeExecutable, this.entrypoint, ...args].map(shellArgument).join(" ")}`;
+    }
+}

package/dist/services/generic-execution.js

@@ -0,0 +1,164 @@
+import { AppError } from "../shared/errors.js";
+import { sameSessionProfile } from "./execution-policy.js";
+import { hybridDigest, validateHybridContract } from "./hybrid-contracts.js";
+import { prepareOperatorProfile, resolveOperatorProfile } from "./operator-profiles.js";
+function fail(message, issues) {
+    throw new AppError("generic_execution_invalid", message, 2, { phase: "prepare", effect: "no_effect", ...(issues ? { issues } : {}) });
+}
+function freeze(value) {
+    if (value !== null && typeof value === "object") {
+        for (const child of Object.values(value))
+            freeze(child);
+        Object.freeze(value);
+    }
+}
+function scopedReceipts(settings, scope, receipts) {
+    for (const [reference, kind] of [
+        [settings.attached_session_receipt, "attached-session-binding"],
+        [settings.delegation.native_capacity_receipt, "native-capacity"]
+    ]) {
+        if (reference === null)
+            continue;
+        const fact = receipts.get(reference.sha256);
+        if (!fact || fact.kind !== kind || fact.requestId !== scope.requestId
+            || fact.projectRoot !== scope.projectRoot || fact.workspace !== scope.workspace) {
+            fail("Execution receipt does not belong to the selected request and workspace");
+        }
+    }
+}
+function validateSnapshot(snapshot, flow, scope, receipts) {
+    if (!snapshot || typeof snapshot !== "object" || Array.isArray(snapshot)
+        || Object.keys(snapshot).some(key => !["schema_id", "scope", "settings", "profiles"].includes(key))
+        || ["schema_id", "scope", "settings", "profiles"].some(key => !Object.hasOwn(snapshot, key))
+        || snapshot.schema_id !== "dd-flow/frozen-execution@1"
+        || !snapshot.scope || typeof snapshot.scope !== "object" || Array.isArray(snapshot.scope)
+        || !scope || [scope.requestId, scope.projectRoot, scope.workspace].some(value => typeof value !== "string" || !value.trim())
+        || hybridDigest(snapshot.scope) !== hybridDigest(scope))
+        fail("Invalid frozen execution identity");
+    const content = { schema_id: "dd-flow/profile-settings@1", profiles: snapshot.profiles, aliases: {}, default_profile: null };
+    const profiles = { ...content, revision: hybridDigest(content) };
+    const issues = validateHybridContract("execution-settings", snapshot.settings, {
+        descriptor: flow.descriptor, descriptorSha256: flow.sha256, profileSettings: profiles, receipts
+    });
+    if (issues.length)
+        fail("Frozen execution violates the admitted descriptor or profile policy", issues);
+    const settings = snapshot.settings;
+    if (snapshot.profiles.length !== settings.profiles.length
+        || snapshot.profiles.some(profile => !settings.profiles.some(reference => reference.id === profile.id && reference.revision === profile.revision))) {
+        fail("Frozen profile bytes and revision inventory differ");
+    }
+    for (const stage of flow.descriptor.stages) {
+        if (!Object.hasOwn(settings.stage_profiles, stage.id))
+            fail("Every declared stage must have an explicit frozen route");
+    }
+    scopedReceipts(settings, scope, receipts);
+}
+/** Separate from SDLC settings: no plan review, merge, bootstrap command or stop target. */
+export class FrozenGenericExecution {
+    sha256;
+    settings;
+    #snapshot;
+    #flow;
+    constructor(snapshot, flow) {
+        freeze(snapshot);
+        this.#snapshot = snapshot;
+        this.#flow = flow;
+        this.settings = snapshot.settings;
+        this.sha256 = hybridDigest(snapshot);
+        Object.freeze(this);
+    }
+    /** Pure selection from one admitted operator snapshot; never reread it during a RUN. */
+    static prepare(flow, operatorSettings, selection, scope, receipts = new Map()) {
+        const issues = validateHybridContract("profile-settings", operatorSettings);
+        if (issues.length)
+            fail("Operator profiles cannot be frozen", issues);
+        if (!selection || typeof selection !== "object" || Array.isArray(selection)
+            || Object.keys(selection).some(key => !["rootProfile", "stageProfiles", "workProfiles", "execution", "stageSessionMode", "attachedSessionReceipt", "delegation"].includes(key))) {
+            fail("Unsupported execution selection");
+        }
+        if (!["mb-init", "mb-upgrade"].includes(flow.descriptor.id)
+            && (selection.execution === undefined || selection.stageSessionMode === undefined || selection.delegation === undefined)) {
+            fail("Non-memory flows must supply their own execution defaults explicitly");
+        }
+        let rootSelection = selection.rootProfile;
+        if (rootSelection !== undefined && typeof rootSelection !== "string") {
+            const profile = prepareOperatorProfile(rootSelection);
+            const existing = operatorSettings.profiles.find(entry => entry.id === profile.id);
+            if (Object.hasOwn(operatorSettings.aliases, profile.id) || existing && existing.revision !== hybridDigest(profile))
+                fail("Operation-only profile conflicts with an existing ID or alias");
+            const { revision: _revision, ...content } = structuredClone(operatorSettings);
+            void _revision;
+            if (!existing)
+                content.profiles.push({ id: profile.id, revision: hybridDigest(profile), profile });
+            operatorSettings = { ...content, revision: hybridDigest(content) };
+            rootSelection = profile.id;
+        }
+        const profiles = new Map();
+        const resolve = (id) => {
+            const profile = prepareOperatorProfile(resolveOperatorProfile(operatorSettings, id));
+            profiles.set(profile.id, { id: profile.id, revision: hybridDigest(profile), profile });
+            return profile.id;
+        };
+        const root = resolve(rootSelection);
+        const stages = Object.create(null);
+        if (selection.stageProfiles !== undefined && (!selection.stageProfiles || typeof selection.stageProfiles !== "object" || Array.isArray(selection.stageProfiles))) {
+            fail("Stage profile selection must be an object");
+        }
+        for (const id of Object.keys(selection.stageProfiles ?? {}))
+            flow.stage(id);
+        for (const stage of flow.descriptor.stages) {
+            const selected = selection.stageProfiles && Object.hasOwn(selection.stageProfiles, stage.id) ? selection.stageProfiles[stage.id] : undefined;
+            if (selected !== undefined && typeof selected !== "string")
+                fail("Stage profile selection must name a profile");
+            stages[stage.id] = selected === undefined ? root : resolve(selected);
+        }
+        if (selection.workProfiles !== undefined && (!Array.isArray(selection.workProfiles) || selection.workProfiles.some(id => typeof id !== "string"))) {
+            fail("Approved Work profiles must be a list of profile IDs");
+        }
+        const works = [...new Set((selection.workProfiles ?? []).map(id => resolve(id)))];
+        const delegation = selection.delegation;
+        if (delegation !== undefined && (!delegation || typeof delegation !== "object" || Array.isArray(delegation)
+            || Object.keys(delegation).some(key => !["mode", "max_parallel", "nativeCapacityReceipt"].includes(key))))
+            fail("Unsupported delegation selection");
+        const settings = {
+            schema_id: "dd-flow/execution-settings@1", flow_id: flow.descriptor.id, descriptor_sha256: flow.sha256,
+            execution: selection.execution ?? "managed", attached_session_receipt: selection.attachedSessionReceipt ?? null,
+            stage_session_mode: selection.stageSessionMode ?? "new_session",
+            delegation: { mode: delegation?.mode ?? "external", max_parallel: delegation?.max_parallel ?? 1, native_capacity_receipt: delegation?.nativeCapacityReceipt ?? null },
+            profiles: [...profiles.values()].map(({ id, revision }) => ({ id, revision })), root_profile: root,
+            stage_profiles: stages, work_profiles: works
+        };
+        const snapshot = structuredClone({ schema_id: "dd-flow/frozen-execution@1", scope, settings, profiles: [...profiles.values()] });
+        validateSnapshot(snapshot, flow, scope, receipts);
+        return new FrozenGenericExecution(snapshot, flow);
+    }
+    /** Admission uses retained bytes and trusted scope/receipts, never the current operator settings. */
+    static restore(snapshot, expectedSha256, flow, scope, receipts = new Map()) {
+        if (!/^[a-f0-9]{64}$/.test(expectedSha256) || hybridDigest(snapshot) !== expectedSha256)
+            fail("Frozen execution identity changed");
+        const retained = structuredClone(snapshot);
+        validateSnapshot(retained, flow, scope, receipts);
+        return new FrozenGenericExecution(retained, flow);
+    }
+    snapshot() { return structuredClone(this.#snapshot); }
+    stage(id) {
+        this.#flow.stage(id);
+        return { profile: this.profile(this.settings.stage_profiles[id]), session_mode: this.settings.stage_session_mode };
+    }
+    work(stage, profileId) {
+        const coordinator = this.stage(stage).profile;
+        const id = profileId ?? coordinator.id;
+        if (id !== coordinator.id && !this.settings.work_profiles.includes(id))
+            fail("Work profile is not approved for this RUN");
+        const worker = this.profile(id);
+        if (this.settings.delegation.mode === "native" && !sameSessionProfile(coordinator, worker))
+            fail("Native Work cannot change execution profile");
+        return { coordinator, worker, delegation: structuredClone(this.settings.delegation) };
+    }
+    profile(id) {
+        const value = this.#snapshot.profiles.find(entry => entry.id === id);
+        if (!value)
+            fail("Profile is absent from the frozen execution inventory");
+        return structuredClone(value.profile);
+    }
+}