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

package/dist/services/interactive-request.js

@@ -0,0 +1,287 @@
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { requireProjectByRoot } from "./projects.js";
+import { appendAudit } from "./audit.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { prepareInteractiveRunBundle } from "./interactive-run-bundle.js";
+import { PreparedInteractiveAttachedSession } from "./interactive-attached-session.js";
+import { RetainedExecutionBundle } from "./execution-bundles.js";
+import { runBundleAuthorityMetadata } from "./runs.js";
+import { readRunStartRequest, runStartPayloadLimit } from "./run-start-custody.js";
+import { nextDescriptorRunId, PreparedDescriptorRunStart } from "./descriptor-run-start.js";
+import { bundledHandlerContext } from "./stage-handlers.js";
+import { PreparedProjectFlowSource } from "./project-flow-source.js";
+import { readInteractiveBundleData } from "./interactive-bundle-data.js";
+import { PreparedInteractiveGitBaseline } from "./interactive-git-baseline.js";
+import { PreparedInteractiveBeforeVersions, restoreInteractiveBeforeVersions } from "./interactive-before-versions.js";
+import { observeMemoryGitPolicySelection } from "./memory-init-git-policy.js";
+import { readBoundedReleaseFile } from "./release-source.js";
+const event = "interactive.request", hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const digest = (value) => typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+function refuse(reason) {
+    throw new AppError("interactive_request_invalid", "Interactive requires the original retained request and its own RUN", 2, { reason, effect: "no_effect" });
+}
+function selection(input) {
+    return hybridDigest({ source: input.source.sha256, execution: input.execution.sha256, engine: input.engine.manifestSha256,
+        baseline: input.baseline.sha256, before: input.beforeVersions.sha256, request: input.requestText,
+        git: input.gitExecutable, policy: input.gitPolicy, receipts: [...input.receipts ?? []],
+        ...(input.launchSelection !== undefined ? { launch_selection: input.launchSelection } : {}),
+        receipt_bytes: [...input.receiptBytes ?? []].map(([key, bytes]) => [key, Buffer.from(bytes).toString("base64")]) });
+}
+/** Allocation can choose a different free RUN ID without changing any selected
+ * task data. Only the engine binding's RUN field is allocation-local. */
+function bundleSelection(manifest, scope) {
+    return hybridDigest({ flow_id: manifest.flow_id, scope, descriptor: manifest.descriptor,
+        execution_settings: manifest.execution_settings, profile_settings: manifest.profile_settings,
+        engine_manifest: manifest.engine_manifest, engine_binding_path: manifest.engine_binding.path,
+        canon: manifest.canon, project_pack: manifest.project_pack, bootstrap_receipts: manifest.bootstrap_receipts,
+        inventory: manifest.inventory.filter(item => item.path !== manifest.engine_binding.path) });
+}
+function decode(value, limit) {
+    if (typeof value !== "string" || value.length > Math.ceil(limit / 3) * 4)
+        refuse("invalid_request_bytes");
+    const bytes = Buffer.from(value, "base64");
+    if (!bytes.length || bytes.length > limit || bytes.toString("base64") !== value)
+        refuse("invalid_request_bytes");
+    return bytes;
+}
+function json(bytes) {
+    try {
+        return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        return refuse("invalid_request_json");
+    }
+}
+/** SQL/data only, including when called by the allocation writer. Full engine,
+ * compiled schema and physical workspace admission happens outside the writer. */
+export function readInteractiveRequest(context, { projectRoot, requestId }) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$/.test(requestId))
+        refuse("invalid_request_id");
+    const scope = { projectRoot, requestId }, project = context.db.get("SELECT id FROM projects WHERE root=? AND status='active'", [projectRoot]);
+    if (!project)
+        refuse("project_not_registered");
+    const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type=? AND json_extract(payload_json,'$.scope.requestId')=? LIMIT 2", [project.id, event, requestId]);
+    if (!rows.length)
+        return null;
+    if (rows.length !== 1 || Buffer.byteLength(rows[0].payload_json) > runStartPayloadLimit)
+        refuse("ambiguous_or_unbounded_request");
+    const value = json(Buffer.from(rows[0].payload_json));
+    if (!value || Object.keys(value).sort().join() !== "admission_json,admission_sha256,blobs,bound_at,bundle_selection_sha256,manifest_base64,manifest_sha256,project_id,schema_id,scope,selection_sha256,source_sha256"
+        || value.schema_id !== "dd-flow/interactive-request@1" || value.project_id !== project.id || hybridDigest(value.scope) !== hybridDigest(scope)
+        || ![value.selection_sha256, value.bundle_selection_sha256, value.source_sha256, value.manifest_sha256, value.admission_sha256].every(digest)
+        || typeof value.bound_at !== "string" || !Number.isFinite(Date.parse(value.bound_at))
+        || typeof value.admission_json !== "string" || Buffer.byteLength(value.admission_json) > 1024 * 1024
+        || !Array.isArray(value.blobs) || value.blobs.length > 4096)
+        refuse("request_scope_changed");
+    const bytes = decode(value.manifest_base64, 1024 * 1024), manifest = json(bytes);
+    const admission = json(Buffer.from(value.admission_json));
+    if (hash(bytes) !== value.manifest_sha256 || hybridDigest(admission) !== value.admission_sha256
+        || !manifest || manifest.schema_id !== "dd-flow/execution-bundle@1" || manifest.flow_id !== "interactive"
+        || !Array.isArray(manifest.inventory) || manifest.inventory.length !== value.blobs.length
+        || manifest.inventory.some(item => !item || typeof item.path !== "string" || !digest(item.sha256))
+        || typeof manifest.engine_binding?.path !== "string"
+        || !Array.isArray(manifest.bootstrap_receipts) || manifest.bootstrap_receipts.length
+        || !admission?.executionScope || admission.executionScope.projectRoot !== projectRoot || admission.executionScope.requestId !== requestId
+        || bundleSelection(manifest, admission.executionScope) !== value.bundle_selection_sha256)
+        refuse("retained_bundle_changed");
+    const refs = new Map(manifest.inventory.map(item => [item.path, item.sha256])), names = new Set();
+    let total = 0;
+    for (const item of value.blobs) {
+        if (!item || Object.keys(item).sort().join() !== "base64,path" || typeof item.path !== "string" || names.has(item.path))
+            refuse("retained_blob_inventory_changed");
+        const content = decode(item.base64, 1024 * 1024);
+        total += content.length;
+        if (total > 32 * 1024 * 1024 || hash(content) !== refs.get(item.path))
+            refuse("retained_blob_changed");
+        names.add(item.path);
+    }
+    return value;
+}
+/** Compare supplied launch selectors with retained raw intent, not today's
+ * aliases/defaults or a newly observed equivalent model. Omission preserves the
+ * original selection. This reads only the independently validated request. */
+export function assertInteractiveLaunchReplay(context, scope, supplied) {
+    const request = readInteractiveRequest(context, scope);
+    if (!request)
+        refuse("original_request_required");
+    const blob = (name) => {
+        const selected = request.blobs.find(item => item.path === name);
+        if (!selected)
+            refuse("original_launch_selection_required");
+        return Buffer.from(selected.base64, "base64");
+    };
+    const admission = json(Buffer.from(request.admission_json));
+    if (supplied.workspace !== undefined && supplied.workspace !== admission.executionScope.workspace
+        || supplied.requestText !== undefined && !Buffer.from(supplied.requestText).equals(blob("runtime/source-request.md")))
+        refuse("launch_inputs_changed");
+    if (supplied.gitPolicy !== undefined) {
+        const frozen = json(blob("runtime/git-policy.json"));
+        if (hybridDigest(supplied.gitPolicy) !== hybridDigest({ route: frozen.policy.route, integrationBranch: frozen.policy.integration_branch }))
+            refuse("launch_inputs_changed");
+    }
+    const selectors = supplied.launchSelection;
+    if (selectors && Object.keys(selectors).length) {
+        const original = json(blob("runtime/launch-selection.json"));
+        if (Object.entries(selectors).some(([key, value]) => !Object.hasOwn(original, key)
+            || hybridDigest(value) !== hybridDigest(original[key])))
+            refuse("launch_inputs_changed");
+    }
+    return request;
+}
+/** Called with compiled bundle admission already complete. No filesystem or
+ * handler/schema loading: this fence also protects the allocation transaction. */
+export function assertInteractiveRequestBundle(context, projectId, bundle) {
+    const frozen = bundle.execution.snapshot(), request = readInteractiveRequest(context, frozen.scope);
+    if (!request || request.project_id !== projectId || bundle.manifest.flow_id !== "interactive"
+        || bundleSelection(bundle.manifest, frozen.scope) !== request.bundle_selection_sha256)
+        refuse("request_bundle_changed");
+    const binding = json(bundle.blob(bundle.manifest.engine_binding.path));
+    const original = request.blobs.find(item => item.path === bundle.manifest.engine_binding.path);
+    const initial = original ? json(Buffer.from(original.base64, "base64")) : null;
+    if (!initial || binding.run_id !== bundle.manifest.run_id || binding.bound_at !== request.bound_at
+        || hybridDigest({ ...binding, run_id: null }) !== hybridDigest({ ...initial, run_id: null }))
+        refuse("allocation_binding_changed");
+}
+/** Freeze once before allocation. Attached hook claim and request insertion
+ * share one writer; replay never creates another claim, RUN or input capture. */
+export function retainInteractiveRequest(context, input, attached) {
+    if (context.db.isOwnedWriteTransaction?.())
+        refuse("preparation_outside_writer_required");
+    const frozen = input.execution.snapshot(), scope = { projectRoot: frozen.scope.projectRoot, requestId: frozen.scope.requestId };
+    const project = requireProjectByRoot(context, scope.projectRoot), chosen = selection(input), prior = readInteractiveRequest(context, scope);
+    if (prior) {
+        if (prior.selection_sha256 !== chosen)
+            refuse("request_changed");
+        return prior;
+    }
+    if (readRunStartRequest(context, project.id, scope.requestId))
+        refuse("foreign_run_request");
+    if (frozen.settings.execution === "attached") {
+        if (!(attached instanceof PreparedInteractiveAttachedSession) || hybridDigest(attached.snapshot().scope) !== hybridDigest(frozen.scope)
+            || hybridDigest(attached.evidence().reference) !== hybridDigest(frozen.settings.attached_session_receipt))
+            refuse("trusted_attached_selection_required");
+    }
+    else if (attached)
+        refuse("foreign_attached_selection");
+    const bundle = prepareInteractiveRunBundle(context, input), metadata = runBundleAuthorityMetadata(bundle);
+    const value = { schema_id: "dd-flow/interactive-request@1", project_id: project.id, scope,
+        selection_sha256: chosen, bundle_selection_sha256: bundleSelection(bundle.manifest, frozen.scope), source_sha256: input.source.sha256,
+        bound_at: input.boundAt, manifest_base64: bundle.manifestBytes().toString("base64"), manifest_sha256: bundle.sha256,
+        admission_json: metadata.admissionJson, admission_sha256: metadata.anchor.admission_sha256,
+        blobs: bundle.manifest.inventory.map(ref => ({ path: ref.path, base64: bundle.blob(ref.path).toString("base64") })) };
+    if (Buffer.byteLength(JSON.stringify(value)) > runStartPayloadLimit)
+        refuse("request_exceeds_bound");
+    return context.db.writeTransaction(() => {
+        const current = readInteractiveRequest(context, scope);
+        if (current) {
+            if (current.selection_sha256 !== chosen)
+                refuse("request_changed");
+            return current;
+        }
+        if (readRunStartRequest(context, project.id, scope.requestId))
+            refuse("foreign_run_request");
+        attached?.retainPreparedSql(context);
+        appendAudit(context, { projectId: project.id, eventType: event, payload: value });
+        const retained = readInteractiveRequest(context, scope);
+        if (!retained)
+            refuse("request_readback_missing");
+        return retained;
+    }, "interactive.retainRequest");
+}
+/** Restore initial data from request custody, never current defaults, files or
+ * global canon. Generic admission still checks actual selected engine bytes. */
+function restoreBundle(request) {
+    const admission = json(Buffer.from(request.admission_json));
+    if (!Array.isArray(admission.receipts) || admission.receipts.some(item => !Array.isArray(item) || item.length !== 2 || !digest(item[0]))
+        || new Set(admission.receipts.map(item => item[0])).size !== admission.receipts.length)
+        refuse("invalid_retained_execution_receipts");
+    return RetainedExecutionBundle.admit(decode(request.manifest_base64, 1024 * 1024), request.manifest_sha256, new Map(request.blobs.map(item => [item.path, Buffer.from(item.base64, "base64")])), { ...admission, receipts: new Map(admission.receipts), descriptorContext: bundledHandlerContext(new Map()) });
+}
+function bindRunId(bundle, runId) {
+    if (bundle.manifest.run_id === runId)
+        return bundle;
+    const manifest = structuredClone(bundle.manifest), admission = bundle.admission();
+    const binding = json(bundle.blob(manifest.engine_binding.path));
+    binding.run_id = runId;
+    const bytes = Buffer.from(JSON.stringify(binding)), sha256 = hash(bytes);
+    const blobs = new Map(manifest.inventory.map(ref => [ref.path, bundle.blob(ref.path)]));
+    blobs.set(manifest.engine_binding.path, bytes);
+    manifest.run_id = runId;
+    manifest.engine_binding.sha256 = sha256;
+    for (const ref of manifest.inventory)
+        if (ref.path === manifest.engine_binding.path)
+            ref.sha256 = sha256;
+    const encoded = Buffer.from(JSON.stringify(manifest));
+    return RetainedExecutionBundle.admit(encoded, hash(encoded), blobs, { ...admission, runId, engineBindingSha256: sha256 });
+}
+function revalidateBeforeAllocation(context, request, bundle) {
+    const scope = bundle.execution.snapshot().scope, manifestBytes = bundle.blob("project-pack/manifest.json");
+    const pack = json(manifestBytes);
+    if (!Array.isArray(pack.included_files))
+        refuse("invalid_retained_project_pack");
+    const source = PreparedProjectFlowSource.restoreRetained({ schema_id: "dd-flow/project-flow-source@1",
+        scope: { projectRoot: scope.projectRoot, workspace: scope.workspace, flowId: "interactive" },
+        blobs: ["project-pack/manifest.json", ...pack.included_files].map(name => ({ path: name, base64: bundle.blob(name).toString("base64") })) }, request.source_sha256);
+    if (hybridDigest(source.projectPackProvenance()) !== hybridDigest(bundle.manifest.project_pack))
+        refuse("retained_project_pack_changed");
+    bundle.engine().admitInteractiveFlow(source);
+    if (bundle.execution.settings.execution === "attached") {
+        const attached = PreparedInteractiveAttachedSession.restore(context, scope);
+        if (hybridDigest(attached.evidence().reference) !== hybridDigest(bundle.execution.settings.attached_session_receipt))
+            refuse("retained_attached_selection_changed");
+    }
+    revalidateInteractiveEntryWorkspace(context, bundle);
+}
+/** Shared RUN-start physical fence. Git porcelain can remain unchanged while
+ * an already-dirty file's content changes, so status alone is insufficient. */
+export function revalidateInteractiveEntryWorkspace(context, bundle) {
+    if (context.db.isOwnedWriteTransaction?.())
+        refuse("physical_revalidation_outside_writer_required");
+    if (bundle.manifest.flow_id !== "interactive")
+        refuse("interactive_bundle_required");
+    const scope = bundle.execution.snapshot().scope;
+    const policy = json(bundle.blob("runtime/git-policy.json"));
+    if (hybridDigest(policy.scope) !== hybridDigest({ requestId: scope.requestId, projectRoot: scope.projectRoot, workspaceRoot: scope.workspace })
+        || hash(readBoundedReleaseFile(policy.git_executable, 64 * 1024 * 1024)) !== policy.git_sha256)
+        refuse("retained_git_selection_changed");
+    const observed = observeMemoryGitPolicySelection(context.env, { scope: policy.scope, gitExecutable: policy.git_executable,
+        selection: { route: policy.policy.route, integrationBranch: policy.policy.integration_branch } });
+    if (hybridDigest(observed) !== hybridDigest(policy.policy))
+        refuse("git_policy_changed_before_allocation");
+    const retained = readInteractiveBundleData(bundle, "runtime/git-baseline.json"), before = readInteractiveBundleData(bundle, "runtime/before-versions.json");
+    const baseline = PreparedInteractiveGitBaseline.restore(retained.bytes, retained.sha256);
+    const versions = restoreInteractiveBeforeVersions(before.bytes, before.sha256, baseline);
+    // Physical equality check only. Retained before-images remain authoritative;
+    // later current bytes cannot replace the original evidence on retry.
+    const current = (() => {
+        try {
+            return PreparedInteractiveBeforeVersions.capture(baseline, versions.entries.map(item => item.path));
+        }
+        catch (error) {
+            if (error instanceof AppError)
+                throw error;
+            return refuse("before_versions_unavailable_before_allocation");
+        }
+    })();
+    if (current.sha256 !== before.sha256)
+        refuse("before_versions_changed_before_allocation");
+    baseline.revalidate({ projectRoot: scope.projectRoot, workspace: scope.workspace, gitExecutable: policy.git_executable, env: context.env });
+}
+export function startInteractiveRun(context, scope) {
+    if (context.db.isOwnedWriteTransaction?.())
+        refuse("preparation_outside_writer_required");
+    const request = readInteractiveRequest(context, scope);
+    if (!request)
+        refuse("original_request_required");
+    const allocation = readRunStartRequest(context, request.project_id, scope.requestId);
+    if (allocation) {
+        if (allocation.payload.initial_index.flow_kind !== "interactive")
+            refuse("foreign_run_request");
+        return PreparedDescriptorRunStart.restore(context, scope).apply(context);
+    }
+    const bundle = bindRunId(restoreBundle(request), nextDescriptorRunId(context, { ...scope, slug: "interactive" }));
+    assertInteractiveRequestBundle(context, request.project_id, bundle);
+    revalidateBeforeAllocation(context, request, bundle);
+    return PreparedDescriptorRunStart.prepare(context, { bundle }).apply(context);
+}

package/dist/services/interactive-run-bundle.js

@@ -0,0 +1,109 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { PreparedProjectFlowSource } from "./project-flow-source.js";
+import { FrozenGenericExecution } from "./generic-execution.js";
+import { AdmittedFrozenEngine } from "./frozen-engine.js";
+import { RetainedExecutionBundle } from "./execution-bundles.js";
+import { PreparedInteractiveGitBaseline } from "./interactive-git-baseline.js";
+import { PreparedInteractiveBeforeVersions, restoreInteractiveBeforeVersions } from "./interactive-before-versions.js";
+import { putInteractiveBundleData } from "./interactive-bundle-data.js";
+import { observeMemoryGitPolicySelection } from "./memory-init-git-policy.js";
+import { readBoundedReleaseFile } from "./release-source.js";
+import { nextDescriptorRunId } from "./descriptor-run-start.js";
+import { bundledHandlerContext } from "./stage-handlers.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const encode = (value) => Buffer.from(JSON.stringify(value));
+function refuse(reason) {
+    throw new AppError("interactive_run_bundle_invalid", "Interactive requires its original request, project pack, workspace and execution selection", 2, { reason, effect: "no_effect" });
+}
+/** Initial assembly only, outside the writer. Creates no RUN, workspace or
+ * Session and grants no file/Git mutation. The request owner must retain this
+ * exact bundle before allocation; retries restore it, never recapture state. */
+export function prepareInteractiveRunBundle(context, input) {
+    if (context.db.isOwnedWriteTransaction?.())
+        refuse("preparation_outside_writer_required");
+    if (!(input.source instanceof PreparedProjectFlowSource) || !(input.execution instanceof FrozenGenericExecution)
+        || !(input.engine instanceof AdmittedFrozenEngine) || !(input.baseline instanceof PreparedInteractiveGitBaseline)
+        || !(input.beforeVersions instanceof PreparedInteractiveBeforeVersions) || !Number.isFinite(Date.parse(input.boundAt)))
+        refuse("unprepared_selection");
+    if (typeof input.requestText !== "string" || !input.requestText.trim() || Buffer.byteLength(input.requestText) > 64 * 1024)
+        refuse("original_request_required");
+    const frozen = input.execution.snapshot(), flow = input.source.resolveRegisteredFlow(), sourceScope = input.source.scope();
+    if (frozen.settings.flow_id !== "interactive" || flow.descriptor.id !== "interactive" || flow.descriptor.origin !== "project"
+        || flow.sha256 !== frozen.settings.descriptor_sha256)
+        refuse("flow_selection_changed");
+    const baseline = input.baseline.snapshot();
+    if (sourceScope.projectRoot !== frozen.scope.projectRoot || sourceScope.workspace !== frozen.scope.workspace
+        || baseline.project_root !== frozen.scope.projectRoot || baseline.workspace !== frozen.scope.workspace)
+        refuse("workspace_selection_changed");
+    // Before-images from another baseline are not interchangeable, even when the
+    // selected paths happen to match. Empty initial images are valid before scope.
+    restoreInteractiveBeforeVersions(input.beforeVersions.bytes(), input.beforeVersions.sha256, input.baseline);
+    input.engine.admitInteractiveFlow(input.source);
+    if (!path.isAbsolute(input.gitExecutable))
+        refuse("absolute_git_executable_required");
+    const gitExecutable = fs.realpathSync(input.gitExecutable), gitSha256 = hash(readBoundedReleaseFile(gitExecutable, 64 * 1024 * 1024));
+    const gitScope = { requestId: frozen.scope.requestId, projectRoot: frozen.scope.projectRoot, workspaceRoot: frozen.scope.workspace };
+    const policy = observeMemoryGitPolicySelection(context.env, { scope: gitScope, gitExecutable, selection: input.gitPolicy });
+    if (policy.repository !== baseline.repository || policy.workspace_branch !== baseline.branch || policy.initial_head !== baseline.head)
+        refuse("git_policy_baseline_changed");
+    const manifest = input.engine.manifest(), checksum = manifest.integrity.checksum;
+    if (typeof checksum !== "string")
+        refuse("engine_identity_missing");
+    const runId = nextDescriptorRunId(context, { projectRoot: frozen.scope.projectRoot, requestId: frozen.scope.requestId, slug: "interactive" });
+    const binding = { schema_id: "dd-flow/run-engine-binding@1", run_id: runId,
+        project_root: frozen.scope.projectRoot, bound_at: input.boundAt, source: "run_creation", reason: "Request-bound interactive work with explicit same-RUN finish",
+        engine: { package_name: manifest.package_name, package_version: manifest.package_version, engine_version: manifest.engine_version,
+            integrity_checksum: checksum, snapshot_root: manifest.snapshot_root }, probe: { status: "not_required", command: null } };
+    const blobs = input.source.blobs();
+    const put = (logical, bytes) => {
+        if ([...blobs.keys()].some(name => name.toLowerCase() === logical.toLowerCase()) || !bytes.length || bytes.length > 1024 * 1024)
+            refuse("bundle_path_collision_or_size");
+        blobs.set(logical, bytes);
+        return { path: logical, sha256: hash(bytes) };
+    };
+    put("runtime/source-request.md", Buffer.from(input.requestText));
+    if (input.launchSelection !== undefined) {
+        if (!input.launchSelection || typeof input.launchSelection !== "object" || Array.isArray(input.launchSelection)
+            || Object.keys(input.launchSelection).some(key => !["rootProfile", "stageProfiles", "workProfiles", "execution", "stageSessionMode", "delegation"].includes(key)))
+            refuse("invalid_launch_selection");
+        // Raw selectors are replay intent, not execution authority. FrozenGenericExecution
+        // remains the only owner of resolved profiles and Session/delegation settings.
+        put("runtime/launch-selection.json", encode(input.launchSelection));
+    }
+    put("runtime/git-policy.json", encode({ schema_id: "dd-flow/interactive-git-policy@1", scope: gitScope,
+        git_executable: gitExecutable, git_sha256: gitSha256, policy }));
+    for (const reference of [frozen.settings.attached_session_receipt, frozen.settings.delegation.native_capacity_receipt]) {
+        if (!reference)
+            continue;
+        const bytes = input.receiptBytes?.get(reference.sha256);
+        if (!bytes || hash(bytes) !== reference.sha256 || !input.receipts?.has(reference.sha256))
+            refuse("execution_receipt_missing");
+        put(reference.path, Buffer.from(bytes));
+    }
+    const profiles = { schema_id: "dd-flow/profile-settings@1", profiles: frozen.profiles, aliases: {}, default_profile: null };
+    const profile = put("runtime/profiles.json", encode({ ...profiles, revision: hybridDigest(profiles) }));
+    const execution = put("runtime/execution.json", encode(frozen.settings));
+    const engineBinding = put("runtime/engine-binding.json", encode(binding));
+    const engineManifest = put("runtime/engine-manifest.json", input.engine.manifestBytes());
+    putInteractiveBundleData(blobs, "runtime/git-baseline.json", input.baseline.bytes());
+    putInteractiveBundleData(blobs, "runtime/before-versions.json", input.beforeVersions.bytes());
+    const provenance = { canon: input.source.canonProvenance(), project_pack: input.source.projectPackProvenance() };
+    const bundle = { schema_id: "dd-flow/execution-bundle@1", run_id: runId, flow_id: "interactive",
+        descriptor: input.source.descriptorReference(), execution_settings: execution, profile_settings: profile,
+        engine_binding: engineBinding, engine_manifest: engineManifest, bootstrap_receipts: [], ...provenance,
+        inventory: [...blobs].map(([logical, bytes]) => ({ path: logical, sha256: hash(bytes) })) };
+    input.source.revalidate();
+    input.beforeVersions.revalidate();
+    input.baseline.revalidate({ projectRoot: frozen.scope.projectRoot, workspace: frozen.scope.workspace, gitExecutable, env: context.env });
+    if (hash(readBoundedReleaseFile(gitExecutable, 64 * 1024 * 1024)) !== gitSha256)
+        refuse("selected_git_changed");
+    const bytes = encode(bundle);
+    return RetainedExecutionBundle.admit(bytes, hash(bytes), blobs, { runId, executionScope: frozen.scope,
+        bundleProjectRoot: frozen.scope.projectRoot, descriptorSha256: flow.sha256, engineChecksum: checksum,
+        engineBindingSha256: engineBinding.sha256, engineManifestSha256: engineManifest.sha256,
+        descriptorContext: bundledHandlerContext(new Map()), bundleProvenance: provenance, receipts: input.receipts ?? new Map() });
+}

package/dist/services/interactive-stage-entry.js

@@ -0,0 +1,41 @@
+import { AppError } from "../shared/errors.js";
+import { interactiveStages } from "../domain/interactive-flow.js";
+import { requireProjectByRoot } from "./projects.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { readFlowRunExecutionBundle, assertPreparedRunBundleSqlAuthority } from "./runs.js";
+import { readInteractiveMutationScope } from "./interactive-mutation-scope.js";
+import { PreparedDescriptorStageStart } from "./descriptor-stage-start.js";
+import { PreparedDescriptorStageCoordinator } from "./descriptor-stage-coordinator.js";
+function refuse(reason) {
+    throw new AppError("interactive_stage_invalid", "Interactive Stage requires its own RUN, delivered inputs and retained scope", 2, { reason, effect: "no_effect" });
+}
+/** Internal entry only, not public availability or Work/Git authorization.
+ * Generic runtime remains the sole owner of attempts, root Work and Session. */
+export function readInteractiveStageScope(context, input, historical = false) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot)), bundle = readFlowRunExecutionBundle(context, input);
+    if (!bundle || bundle.manifest.flow_id !== "interactive" || !interactiveStages.includes(input.stage))
+        refuse("interactive_stage_required");
+    bundle.descriptor.stage(input.stage);
+    const scope = { projectId: project.id, runId: input.runId, stage: input.stage }, run = assertPreparedRunBundleSqlAuthority(context, scope, bundle);
+    const index = JSON.parse(run.index_json);
+    const replay = Boolean(historical && index.stage_runs?.some((item) => item.stage === input.stage && item.status === "done"));
+    const selected = readInteractiveMutationScope(context, scope, bundle);
+    if (!replay && !["preflight", "interactive"].includes(input.stage) && !selected.inputs.finish_requested)
+        refuse("explicit_finish_required");
+    return { bundle, scope, run, replay, selected,
+        /** SQL/data only. A turn, HITL answer or scope decision racing entry cannot
+         * silently become a different input to an already prepared coordinator. */
+        assertCustody(writer) {
+            const current = readInteractiveMutationScope(writer, scope, bundle);
+            if (current.revision !== selected.revision || current.inputs.sha256 !== selected.inputs.sha256
+                || current.baseline.sha256 !== selected.baseline.sha256)
+                refuse("interactive_stage_inputs_changed");
+        }
+    };
+}
+export function startInteractiveStage(context, input) {
+    const selected = readInteractiveStageScope(context, input, true);
+    const start = PreparedDescriptorStageStart.prepare(context, input).apply(context, selected.assertCustody);
+    const coordinator = PreparedDescriptorStageCoordinator.prepare(context, input).apply(context, selected.assertCustody);
+    return { ...start, ...coordinator };
+}