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

package/dist/services/interactive-git-dispatch.js

@@ -0,0 +1,278 @@
+import { spawnSync } from "node:child_process";
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { appendAudit } from "./audit.js";
+import { assertRunMutationAllowed } from "./run-recovery-guard.js";
+import { readInteractiveStageScope } from "./interactive-stage-entry.js";
+import { prepareInteractiveReviewedGitInputs } from "./interactive-finish-integration.js";
+import { readInteractiveWorkGit } from "./interactive-work-start.js";
+import { readDescriptorStageInput } from "./descriptor-stage-coordinator.js";
+import { readActiveDescriptorStageCoordinator } from "./descriptor-stage-settlement.js";
+import { integrateReviewedProjectFiles } from "./memory-finish-integration.js";
+import { observeReviewedProjectGitIntegration } from "./project-git-integration.js";
+const event = "interactive.integration_operation", phaseEvent = "interactive.integration_intent", anchorPath = '$.variables."interactive.integration"';
+function refuse(reason) {
+    throw new AppError("interactive_git_dispatch_invalid", "Interactive Git requires its original reviewed operation and active coordinator", 2, { reason, effect: "no_effect" });
+}
+function pending(reason) {
+    throw new AppError("interactive_integration_pending", "Reconcile the original Git effect before dispatching again", 2, { reason, effect: "unknown", recoverable: true, next_action: "reconcile_original_integration" });
+}
+function stored(context, scope) {
+    const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type=? AND json_extract(payload_json,'$.plan.run_id')=? LIMIT 2", [scope.projectId, event, scope.runId]);
+    const phases = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type=? AND json_extract(payload_json,'$.run_id')=? ORDER BY id LIMIT 3", [scope.projectId, phaseEvent, scope.runId]);
+    const anchor = context.db.get("SELECT json_extract(index_json,?) value FROM runs WHERE project_id=? AND id=?", [anchorPath, scope.projectId, scope.runId])?.value;
+    if (rows.length > 1 || phases.length > 2 || rows.some(row => Buffer.byteLength(row.payload_json) > 96 * 1024 * 1024)
+        || phases.some(row => Buffer.byteLength(row.payload_json) > 16384) || !!rows.length !== !!anchor || !rows.length && phases.length)
+        pending("integration_custody_lost");
+    if (!rows.length)
+        return { operation: null, phases: [] };
+    let operation, intent, value;
+    try {
+        operation = JSON.parse(rows[0].payload_json);
+        intent = phases.map(row => JSON.parse(row.payload_json));
+        value = JSON.parse(anchor);
+    }
+    catch {
+        return pending("integration_custody_invalid");
+    }
+    if (operation?.plan?.schema_id !== "dd-flow/interactive-git-operation@1" || operation.plan.run_id !== scope.runId
+        || operation.identity !== hybridDigest(operation.plan) || value.identity !== operation.identity || hybridDigest(value.phases) !== hybridDigest(intent)
+        || new Set(intent.map(item => item.phase)).size !== intent.length
+        || intent.some(item => item.run_id !== scope.runId || item.identity !== operation.identity || !["commit", "merge"].includes(item.phase)
+            || typeof item.baseline !== "string" || item.baseline !== "" && !/^[a-f0-9]{40,64}$/.test(item.baseline))
+        || intent.length === 2 && (intent[0].phase !== "commit" || intent[1].phase !== "merge"))
+        pending("integration_custody_changed");
+    return { operation, phases: intent };
+}
+function gitReader(context, plan) {
+    const env = { ...Object.fromEntries(Object.entries(context.env).filter(([name]) => !name.startsWith("GIT_"))), GIT_OPTIONAL_LOCKS: "0", GIT_LITERAL_PATHSPECS: "1" };
+    return (args, root = plan.reviewed.policy.scope.workspaceRoot) => {
+        const result = spawnSync(plan.reviewed.policy.git_executable, ["-c", "core.fsmonitor=false", "-C", root, ...args], { env, timeout: 10000, maxBuffer: 16 * 1024 * 1024, shell: false, windowsHide: true });
+        if (result.error || result.signal || result.status !== 0)
+            pending("original_git_readback_failed");
+        return args.includes("-z") ? result.stdout.toString("utf8") : result.stdout.toString("utf8").trim();
+    };
+}
+function assertOwnedHead(context, operation, phases, head) {
+    const { plan } = operation, git = gitReader(context, plan), commit = phases.find(item => item.phase === "commit");
+    if (!commit) {
+        if (head !== (plan.reviewed.policy.policy.initial_head ?? ""))
+            pending("source_head_not_owned");
+    }
+    else if (head !== commit.baseline) {
+        const message = `chore(${plan.run_id.toLowerCase()}): integrate reviewed project changes`;
+        const paths = [...plan.inventory.references, ...plan.inventory.removals].map(ref => ref.path);
+        if (git(["show", "-s", "--format=%P%n%s", head]) !== `${commit.baseline}\n${message}`.trim()
+            || git(["diff-tree", "--root", "--no-commit-id", "--no-renames", "--name-only", "-r", "-z", head]).split("\0").filter(Boolean).some(path => !paths.includes(path)))
+            pending("scoped_commit_not_proven");
+    }
+}
+function selection(plan) {
+    const policy = plan.reviewed.policy;
+    return { projectRoot: policy.scope.projectRoot, workspaceRoot: policy.scope.workspaceRoot,
+        integrationBranch: policy.policy.integration_branch, gitExecutable: policy.git_executable };
+}
+function assertTool(bundle, plan) {
+    const actual = readInteractiveWorkGit(bundle), selected = plan.reviewed.policy;
+    if (actual.git_executable !== selected.git_executable || actual.git_sha256 !== selected.git_sha256)
+        refuse("selected_git_changed");
+}
+function integrationCustody(context, input) {
+    if (context.db.isOwnedWriteTransaction?.())
+        refuse("preparation_outside_writer_required");
+    const selected = readInteractiveStageScope(context, { ...input, stage: "integration" }, true), reviewed = prepareInteractiveReviewedGitInputs(context, input);
+    const state = stored(context, selected.scope), operation = state.operation;
+    if (!operation || hybridDigest(operation.plan.reviewed) !== hybridDigest(reviewed.original))
+        refuse("original_integration_operation_required");
+    const assertCustody = (writer) => {
+        reviewed.assertCustody(writer);
+        if (hybridDigest(stored(writer, selected.scope)) !== hybridDigest(state))
+            pending("integration_custody_changed");
+    };
+    return { selected, reviewed, state, operation, assertCustody };
+}
+/** Historical operation custody, not current Git observation. Prepare outside
+ * the writer; the returned fence itself reads only retained SQL/bundle data. */
+export function prepareInteractiveIntegrationCustody(context, input) {
+    const retained = integrationCustody(context, input);
+    return { binding: { operation_sha256: retained.operation.identity, phases_sha256: hybridDigest(retained.state.phases) },
+        reviewed: structuredClone(retained.operation.plan.reviewed), assertCustody: retained.assertCustody };
+}
+/** Readback plus SQL custody for terminal acceptance. No dispatch or fresh
+ * operation selection; usable when a process died after the original effect. */
+export function prepareInteractiveFinishIntegration(context, input) {
+    const { selected, reviewed, state, operation, assertCustody } = integrationCustody(context, input), { plan } = operation;
+    const observe = () => {
+        assertTool(selected.bundle, plan);
+        assertCustody(context);
+        if (plan.reviewed.empty) {
+            if (state.phases.length)
+                pending("empty_run_has_git_intent");
+            reviewed.observeBeforeDispatch().revalidate();
+            return { schema_id: "dd-flow/interactive-finish-integration@1", operation_sha256: operation.identity, no_op: true, git: null };
+        }
+        const git = observeReviewedProjectGitIntegration(selection(plan), context.env, plan.inventory.references, plan.inventory.removals);
+        if (git.repository !== plan.reviewed.policy.policy.repository || git.workspace_branch !== plan.reviewed.policy.policy.workspace_branch)
+            refuse("policy_repository_or_branch_changed");
+        assertOwnedHead(context, operation, state.phases, git.workspace_head);
+        const merge = state.phases.find(item => item.phase === "merge");
+        if (merge && git.integration_head !== git.workspace_head && git.integration_head !== merge.baseline
+            && gitReader(context, plan)(["show", "-s", "--format=%P", git.integration_head], plan.reviewed.policy.scope.projectRoot) !== `${merge.baseline} ${git.workspace_head}`)
+            pending("scoped_merge_not_proven");
+        reviewed.assertReviewedSources();
+        assertCustody(context);
+        return { schema_id: "dd-flow/interactive-finish-integration@1", operation_sha256: operation.identity, no_op: false, git };
+    };
+    const observation = observe();
+    return { binding: { operation_sha256: operation.identity, phases_sha256: hybridDigest(state.phases) },
+        reviewed: structuredClone(plan.reviewed), value: () => structuredClone(observation), assertCustody, revalidate: () => {
+            if (context.db.isOwnedWriteTransaction?.())
+                refuse("physical_revalidation_outside_writer_required");
+            if (hybridDigest(observe()) !== hybridDigest(observation))
+                pending("integration_readback_changed");
+        } };
+}
+/** Existing scoped Git executor, with original selected index bytes retained
+ * before effects and each phase anchored separately. Never push/stash/reset,
+ * repeat an unresolved phase or rediscover a new agreement after commit. */
+export function integrateInteractiveFinish(context, input) {
+    if (context.db.isOwnedWriteTransaction?.())
+        refuse("preparation_outside_writer_required");
+    const selected = readInteractiveStageScope(context, { ...input, stage: "integration" }, true), { scope, bundle } = selected;
+    const reviewed = prepareInteractiveReviewedGitInputs(context, input);
+    const authority = (writer) => {
+        assertRunMutationAllowed(writer, scope.projectId, scope.runId);
+        const run = writer.db.get("SELECT status,index_json FROM runs WHERE project_id=? AND id=?", [scope.projectId, scope.runId]);
+        const index = JSON.parse(run.index_json);
+        if (run.status !== "running" || index.current_stage !== "integration"
+            || !index.stage_runs.some((stage) => stage.stage === "integration" && stage.status === "running"))
+            refuse("active_integration_required");
+        const stage = readDescriptorStageInput(writer, scope, bundle), actor = readActiveDescriptorStageCoordinator(writer, scope, bundle);
+        if (stage.input.predecessor?.stage !== "review" || hybridDigest(stage.input.predecessor.result) !== hybridDigest(reviewed.original.review_result))
+            refuse("accepted_review_predecessor_required");
+        if (writer.db.get("SELECT 1 FROM works WHERE project_id=? AND run_id=? AND parent_work_id=? AND status IN ('created','running','paused') LIMIT 1", [scope.projectId, scope.runId, actor.work_id]))
+            refuse("active_child_work");
+        return { stage, actor };
+    };
+    let state = stored(context, scope);
+    const replayed = Boolean(state.operation);
+    if (!state.operation) {
+        const owner = authority(context), admission = reviewed.prepareOriginalInputsAgreement(input.agreement);
+        const inventory = { references: reviewed.original.inventory.references, removals: reviewed.original.inventory.removals.map((ref) => {
+                const head = admission.original_inputs.find(item => item.path === ref.path).head;
+                if (!head)
+                    return ref;
+                if (head.git_mode !== "100644" && head.git_mode !== "100755")
+                    refuse("regular_original_removal_required");
+                return { ...ref, sha256: head.sha256, git_mode: head.git_mode };
+            }) };
+        const plan = { schema_id: "dd-flow/interactive-git-operation@1", run_id: input.runId, reviewed: reviewed.original, ...owner, inventory,
+            admission: { agreement: admission.agreement, original_inputs: admission.original_inputs.map(({ workspace, ...item }) => {
+                    const { base64: _retainedWorkspaceBytes, ...reference } = workspace;
+                    void _retainedWorkspaceBytes;
+                    return { ...item, workspace: reference };
+                }) } };
+        const operation = { identity: hybridDigest(plan), plan };
+        if (Buffer.byteLength(JSON.stringify(operation)) > 96 * 1024 * 1024)
+            refuse("integration_operation_exceeds_bound");
+        const sources = reviewed.observeBeforeDispatch();
+        sources.revalidate();
+        context.db.writeTransaction(() => {
+            reviewed.assertCustody(context);
+            sources.assertCustody(context);
+            if (hybridDigest(authority(context)) !== hybridDigest(owner))
+                refuse("integration_authority_changed");
+            const current = stored(context, scope);
+            if (current.operation) {
+                if (current.operation.identity !== operation.identity)
+                    pending("integration_operation_changed");
+                return;
+            }
+            appendAudit(context, { projectId: scope.projectId, eventType: event, payload: operation });
+            context.db.run("UPDATE runs SET index_json=json_set(index_json,?,json(?)) WHERE project_id=? AND id=?", [anchorPath, JSON.stringify({ identity: operation.identity, phases: [] }), scope.projectId, scope.runId]);
+        });
+        state = stored(context, scope);
+    }
+    const operation = state.operation, { plan } = operation;
+    if (hybridDigest(plan.reviewed) !== hybridDigest(reviewed.original))
+        refuse("accepted_integration_inputs_changed");
+    if (input.agreement !== undefined) {
+        const retained = plan.admission.agreement;
+        if (!retained || hybridDigest(input.agreement) !== hybridDigest({ basis: retained.basis, reason: retained.reason, include_existing_paths: retained.include_existing_paths }))
+            refuse("original_git_agreement_changed");
+    }
+    try {
+        const proof = prepareInteractiveFinishIntegration(context, input);
+        proof.revalidate();
+        return { integrated: true, replayed, integration: proof.value() };
+    }
+    catch (error) {
+        if (!(error instanceof AppError) || !["project_git_integration_invalid", "memory_git_integration_invalid"].includes(error.code))
+            throw error;
+    }
+    if (hybridDigest(authority(context)) !== hybridDigest({ stage: plan.stage, actor: plan.actor }))
+        refuse("integration_authority_changed");
+    if (state.phases.length) {
+        if (state.phases.length !== 1 || state.phases[0].phase !== "commit"
+            || plan.reviewed.policy.scope.projectRoot === plan.reviewed.policy.scope.workspaceRoot)
+            pending("original_git_phase_unresolved");
+        const head = gitReader(context, plan)(["rev-parse", "HEAD"]);
+        if (head === state.phases[0].baseline) {
+            // A selected index-only cleanup need not create a commit. Prove its
+            // source postcondition, then permit only the still-unissued merge.
+            try {
+                observeReviewedProjectGitIntegration({ ...selection(plan), projectRoot: plan.reviewed.policy.scope.workspaceRoot,
+                    integrationBranch: plan.reviewed.policy.policy.workspace_branch }, context.env, plan.inventory.references, plan.inventory.removals);
+            }
+            catch {
+                pending("original_commit_not_proven");
+            }
+        }
+        assertOwnedHead(context, operation, state.phases, head);
+    }
+    else
+        reviewed.observeBeforeDispatch().revalidate();
+    let dispatched = false;
+    try {
+        integrateReviewedProjectFiles(selection(plan), context.env, plan.inventory.references, input.runId, (phase, baseline, action) => {
+            assertTool(bundle, plan);
+            const prior = stored(context, scope);
+            if (prior.phases.some(item => item.phase === phase))
+                pending("original_git_phase_unresolved");
+            const before = phase === "commit" ? reviewed.observeBeforeDispatch() : null;
+            if (before)
+                before.revalidate();
+            else
+                assertOwnedHead(context, operation, prior.phases, gitReader(context, plan)(["rev-parse", "HEAD"]));
+            context.db.writeTransaction(() => {
+                reviewed.assertCustody(context);
+                before?.assertCustody(context);
+                if (hybridDigest(authority(context)) !== hybridDigest({ stage: plan.stage, actor: plan.actor }))
+                    refuse("integration_authority_changed");
+                const current = stored(context, scope);
+                if (current.operation?.identity !== operation.identity || current.phases.some(item => item.phase === phase)
+                    || phase === "commit" && current.phases.length)
+                    pending("original_git_phase_unresolved");
+                const intent = { identity: operation.identity, run_id: input.runId, phase, baseline };
+                appendAudit(context, { projectId: scope.projectId, eventType: phaseEvent, payload: intent });
+                context.db.run("UPDATE runs SET index_json=json_set(index_json,?,json(?)) WHERE project_id=? AND id=?", [anchorPath, JSON.stringify({ identity: operation.identity, phases: [...current.phases, intent] }), scope.projectId, scope.runId]);
+            });
+            dispatched = true;
+            // Intent recording is not permission to overwrite an index or task that
+            // changed during that writer. Recheck immediately before the effect.
+            before?.revalidate();
+            reviewed.assertCustody(context);
+            if (hybridDigest(authority(context)) !== hybridDigest({ stage: plan.stage, actor: plan.actor }))
+                refuse("integration_authority_changed");
+            action();
+        }, plan.reviewed.policy.policy, plan.inventory.removals);
+        const proof = prepareInteractiveFinishIntegration(context, input);
+        proof.revalidate();
+        return { integrated: true, replayed: false, integration: proof.value() };
+    }
+    catch (error) {
+        if (dispatched)
+            pending(error instanceof AppError ? error.code : "git_operation_failed");
+        throw error;
+    }
+}

package/dist/services/interactive-input-delivery.js

@@ -0,0 +1,82 @@
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { assertPreparedRunBundleSqlAuthority } from "./runs.js";
+import { readInteractiveUserInputs, readInteractiveInputDelivery, retainInteractiveUserInput } from "./interactive-user-inputs.js";
+import { prepareRunControllerAnswer, answerRunController } from "./run-controller.js";
+function refuse(reason) {
+    throw new AppError("interactive_input_delivery_invalid", "Interactive delivery requires its original input and exact controller pause", 2, { reason, effect: "no_effect" });
+}
+function pending(input, delivery) {
+    throw new AppError("interactive_input_delivery_pending", "User input is retained; reconcile its original controller answer without retargeting", 1, { effect: "committed", recoverable: true, request_id: input.requestId, delivery, next_action: "retry_exact_interactive_input" });
+}
+/** No new dispatcher. Retain the user bytes, then queue the ordinary HITL answer.
+ * The original pause target survives loss between those two existing owners. */
+export function deliverInteractiveUserInput(context, scope, bundle, input) {
+    if (context.db.isOwnedWriteTransaction?.())
+        refuse("preparation_outside_writer_required");
+    const before = readInteractiveUserInputs(context, scope, bundle), prior = before.turns.find(turn => turn.request_id === input.requestId);
+    // Validate exact raw replay through its existing owner before observing or
+    // queuing any controller operation. Changed retry bytes are still no-effect.
+    if (prior)
+        retainInteractiveUserInput(context, scope, bundle, input);
+    const select = () => {
+        const run = assertPreparedRunBundleSqlAuthority(context, scope, bundle), index = JSON.parse(run.index_json);
+        if (bundle.execution.settings.execution !== "managed" || !context.db.get("SELECT 1 FROM sqlite_schema WHERE type='table' AND name='run_controllers'"))
+            return null;
+        const stage = index.stage_runs?.filter((item) => item.stage === index.current_stage).at(-1);
+        if (index.current_stage !== "interactive" || !stage || !["paused", "waiting_for_user"].includes(stage.status) || !stage.pause?.id)
+            return null;
+        const controllers = context.db.all("SELECT controller_id FROM run_controllers WHERE project_id=? AND run_id=? AND status NOT IN ('completed','cancelled','superseded')", [scope.projectId, scope.runId]);
+        if (controllers.length > 1)
+            refuse("ambiguous_controller");
+        const controller = controllers[0];
+        if (!controller)
+            return null;
+        // An already queued answer will wake the same coordinator, which must read
+        // the complete retained input set. Do not queue a second answer to its pause.
+        if (context.db.get("SELECT 1 FROM run_controller_operations WHERE controller_id=? AND json_extract(input_json,'$.action')='user_answer' AND json_extract(input_json,'$.pause_id')=?", [controller.controller_id, stage.pause.id]))
+            return null;
+        return { controller_id: controller.controller_id, pause_id: stage.pause.id,
+            request_id: `interactive-${hybridDigest({ run_id: scope.runId, request_id: input.requestId })}` };
+    };
+    const target = prior ? readInteractiveInputDelivery(context, scope, bundle, input.requestId) : context.db.readSnapshot(select);
+    let prepared;
+    const answer = target ? { projectRoot: input.projectRoot, runId: scope.runId, requestId: target.request_id,
+        pauseId: target.pause_id, answerFile: input.intakeFile } : null;
+    if (target && answer) {
+        try {
+            prepared = prepareRunControllerAnswer(context, answer);
+            const operationId = `${target.controller_id}:answer:${target.request_id}`;
+            if (prepared.operationId !== operationId)
+                refuse("original_controller_changed");
+            if (prepared.kind === "create") {
+                if (!prepared.bytes.equals(Buffer.from(input.bytes)))
+                    refuse("prepared_user_bytes_changed");
+            }
+            else {
+                const operation = context.db.get("SELECT input_json FROM run_controller_operations WHERE operation_id=?", [operationId]);
+                const value = operation ? JSON.parse(operation.input_json) : null;
+                if (!value || value.action !== "user_answer" || value.pause_id !== target.pause_id
+                    || value.sha256 !== createHash("sha256").update(input.bytes).digest("hex"))
+                    refuse("original_answer_changed");
+            }
+        }
+        catch (error) {
+            if (prior)
+                return pending(input, target);
+            throw error;
+        }
+    }
+    const retained = retainInteractiveUserInput(context, scope, bundle, { requestId: input.requestId, kind: input.kind,
+        bytes: input.bytes, expectedInputsSha256: input.expectedInputsSha256, delivery: target });
+    if (!target || !answer || !prepared)
+        return { ...retained, delivery: { kind: "retained_only" } };
+    try {
+        const queued = answerRunController(context, answer, prepared);
+        return { ...retained, delivery: { kind: "controller_answer", pause_id: target.pause_id, ...queued } };
+    }
+    catch {
+        return pending(input, target);
+    }
+}

package/dist/services/interactive-mutation-scope.js

@@ -0,0 +1,231 @@
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { appendAudit } from "./audit.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { readPreparedInteractiveBeforeVersions, readPreparedInteractiveGitBaseline } from "./interactive-baseline-custody.js";
+import { PreparedInteractiveBeforeVersions, restoreInteractiveBeforeVersions } from "./interactive-before-versions.js";
+import { readInteractiveUserInputs } from "./interactive-user-inputs.js";
+import { assertPreparedRunBundleSqlAuthority } from "./runs.js";
+import { assertRunMutationAllowed } from "./run-recovery-guard.js";
+import { readInteractiveWorkHistory, assertInteractiveCorrectionHistory } from "./interactive-work-history.js";
+const eventType = "interactive.mutation_scope";
+const digest = (value) => typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+function refuse(reason) {
+    throw new AppError("interactive_mutation_scope_invalid", "Interactive scope requires delivered user input and original before-images", 2, { reason, effect: "no_effect", ...(reason === "current_scope_required" ? { phase: "prepare", recoverable: true } : {}) });
+}
+function pathsValid(paths) {
+    if (!Array.isArray(paths) || paths.length > 20_000 || paths.some(value => typeof value !== "string" || !value.trim())
+        || new Set(paths).size !== paths.length || hybridDigest(paths) !== hybridDigest([...paths].sort()))
+        refuse("ordered_unique_paths_required");
+}
+/** Delivered-input custody only; the agent still assesses what it authorizes. */
+export function assertInteractiveUserBasis(basis, inputs) {
+    if (!basis || Object.keys(basis).sort().join() !== "event_id,role,sha256" || !Number.isSafeInteger(basis.event_id) || basis.event_id < 0 || !digest(basis.sha256))
+        refuse("delivered_user_basis_required");
+    const delivered = basis.role === "request" ? basis.event_id === 0 && basis.sha256 === inputs.initial_request.sha256
+        : inputs.messages.some(source => ["turn", "answer", "finish"].includes(source.role) && source.role === basis.role && source.event_id === basis.event_id && source.sha256 === basis.sha256);
+    if (!delivered)
+        refuse("delivered_user_basis_required");
+}
+/** SQL-only custody, not semantic approval. A later user message invalidates
+ * active scope until the coordinator explicitly reassesses the full input set. */
+export function readInteractiveMutationScope(context, scope, bundle) {
+    return context.db.readSnapshot(() => {
+        const baseline = readPreparedInteractiveGitBaseline(context, scope, bundle);
+        const initial = readPreparedInteractiveBeforeVersions(context, scope, bundle);
+        const inputs = readInteractiveUserInputs(context, scope, bundle);
+        const versions = new Map(initial.value.entries.map(item => [item.path, item]));
+        const approved = new Set(), requests = new Set(), records = [];
+        let revision = hybridDigest({ bundle: bundle.sha256, baseline: baseline.sha256, before: initial.sha256 }), total = 0;
+        const rows = context.db.all("SELECT id,payload_json FROM audit_events WHERE project_id=? AND event_type=? AND json_extract(payload_json,'$.run_id')=? ORDER BY id LIMIT 129", [scope.projectId, eventType, scope.runId]);
+        if (rows.length > 128)
+            refuse("too_many_scope_decisions");
+        for (const row of rows) {
+            total += Buffer.byteLength(row.payload_json);
+            if (total > 128 * 1024 * 1024)
+                refuse("unbounded_scope_history");
+            let value;
+            try {
+                value = JSON.parse(row.payload_json);
+            }
+            catch {
+                return refuse("invalid_scope_custody");
+            }
+            if (!value || Object.keys(value).sort().join() !== "basis,before_sha256,before_versions,bundle_sha256,paths,previous_sha256,reason,request_id,run_id,schema_id,user_inputs_sha256"
+                || value.schema_id !== "dd-flow/interactive-mutation-scope@1" || value.run_id !== scope.runId || value.bundle_sha256 !== bundle.sha256
+                || typeof value.request_id !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value.request_id) || requests.has(value.request_id)
+                || !digest(value.user_inputs_sha256) || typeof value.reason !== "string" || !value.reason.trim() || value.reason.length > 64 * 1024
+                || value.previous_sha256 !== revision)
+                refuse("invalid_scope_custody");
+            pathsValid(value.paths);
+            assertInteractiveUserBasis(value.basis, inputs);
+            if (value.basis.event_id >= row.id || value.basis.role === "finish" && value.paths.some(name => !approved.has(name)))
+                refuse("scope_not_supported_by_prior_user_input");
+            const original = restoreInteractiveBeforeVersions(Buffer.from(JSON.stringify(value.before_versions)), value.before_sha256, baseline.baseline);
+            const missing = value.paths.filter(name => !versions.has(name));
+            if (hybridDigest(original.entries.map(item => item.path)) !== hybridDigest(missing))
+                refuse("before_scope_changed");
+            for (const item of original.entries)
+                versions.set(item.path, item);
+            for (const name of value.paths) {
+                if (!versions.has(name))
+                    refuse("before_version_required");
+                approved.add(name);
+            }
+            requests.add(value.request_id);
+            records.push(value);
+            revision = hybridDigest({ previous: revision, record: value });
+        }
+        const current = records.at(-1) ?? null, needsRefresh = !current || current.user_inputs_sha256 !== inputs.sha256;
+        return { baseline: baseline.baseline, inputs, records, revision, before_versions: [...versions.values()].sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0),
+            ever_approved_paths: [...approved].sort(), active_paths: needsRefresh ? [] : [...current.paths], needs_scope_refresh: needsRefresh };
+    });
+}
+/** A coordinator's bounded interpretation of actual user input, not an agent
+ * replacement spec or proof of applicability. Dispatch, current file state,
+ * hardening and independent review still belong to ordinary Stage/Work owners. */
+export class PreparedInteractiveMutationScope {
+    #scope;
+    #bundle;
+    #record;
+    #before;
+    constructor(scope, bundle, record, before) {
+        this.#scope = { ...scope };
+        this.#bundle = bundle;
+        this.#record = structuredClone(record);
+        this.#before = before;
+        Object.freeze(this);
+    }
+    static prepare(context, scope, bundle, proposal) {
+        if (!proposal || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(proposal.requestId) || !digest(proposal.expectedInputsSha256)
+            || typeof proposal.reason !== "string" || !proposal.reason.trim() || proposal.reason.length > 64 * 1024)
+            refuse("invalid_scope_proposal");
+        pathsValid(proposal.paths);
+        const current = readInteractiveMutationScope(context, scope, bundle), prior = current.records.find(item => item.request_id === proposal.requestId);
+        if (prior) {
+            if (prior.user_inputs_sha256 !== proposal.expectedInputsSha256 || hybridDigest(prior.paths) !== hybridDigest(proposal.paths)
+                || hybridDigest(prior.basis) !== hybridDigest(proposal.basis) || prior.reason !== proposal.reason)
+                refuse("scope_request_conflict");
+            return new PreparedInteractiveMutationScope(scope, bundle, prior, null);
+        }
+        if (proposal.expectedInputsSha256 !== current.inputs.sha256)
+            refuse("user_inputs_changed");
+        assertInteractiveUserBasis(proposal.basis, current.inputs);
+        const known = new Set(current.before_versions.map(item => item.path));
+        const before = PreparedInteractiveBeforeVersions.capture(current.baseline, proposal.paths.filter(name => !known.has(name)));
+        const record = { schema_id: "dd-flow/interactive-mutation-scope@1", run_id: scope.runId, bundle_sha256: bundle.sha256,
+            request_id: proposal.requestId, user_inputs_sha256: proposal.expectedInputsSha256, basis: structuredClone(proposal.basis), reason: proposal.reason,
+            paths: [...proposal.paths], before_versions: before.snapshot(), before_sha256: before.sha256, previous_sha256: current.revision };
+        return new PreparedInteractiveMutationScope(scope, bundle, record, before);
+    }
+    snapshot() { return structuredClone(this.#record); }
+    revalidate() { this.#before?.revalidate(); }
+    retain(context) {
+        this.revalidate();
+        return context.db.writeTransaction(() => this.retainPreparedSql(context), "interactive.retainMutationScope");
+    }
+    /** Pair with an actual Stage/Work acceptance writer after outside-writer
+     * physical revalidation. No filesystem observation inside this method. */
+    retainPreparedSql(context) {
+        if (!context.db.isOwnedWriteTransaction?.())
+            refuse("owned_writer_required");
+        const current = readInteractiveMutationScope(context, this.#scope, this.#bundle), value = this.#record;
+        const prior = current.records.find(item => item.request_id === value.request_id);
+        if (prior) {
+            if (hybridDigest(prior) !== hybridDigest(value))
+                refuse("scope_request_conflict");
+            return { changed: false, scope: current };
+        }
+        assertRunMutationAllowed(context, this.#scope.projectId, this.#scope.runId);
+        if (current.revision !== value.previous_sha256 || current.inputs.sha256 !== value.user_inputs_sha256)
+            refuse("scope_changed_before_acceptance");
+        const run = assertPreparedRunBundleSqlAuthority(context, this.#scope, this.#bundle), index = JSON.parse(run.index_json);
+        const stage = index.stage_runs?.filter((item) => item.stage === index.current_stage).at(-1);
+        if (index.current_stage === "review")
+            assertInteractiveCorrectionHistory(readInteractiveWorkHistory(context, this.#scope, this.#bundle), stage?.attempt ?? "try-001");
+        if (!["running", "waiting_for_user"].includes(run.status) || !["preflight", "interactive", "consolidation", "hardening", "review"].includes(index.current_stage)
+            || !stage || !["running", "waiting_for_user", "paused"].includes(stage.status))
+            refuse("scope_stage_required");
+        if (current.inputs.finish_requested) {
+            // Hardening may add a file needed by the original delivered task without
+            // re-asking permission. Applicability is agent-owned and reviewed against
+            // the full current inputs; the finish action alone adds no new scope.
+            if (value.basis.role === "finish" && value.paths.some(name => !current.ever_approved_paths.includes(name)))
+                refuse("finish_does_not_expand_scope");
+        }
+        else if (!["preflight", "interactive"].includes(index.current_stage) || value.basis.role === "finish")
+            refuse("scope_stage_required");
+        appendAudit(context, { projectId: this.#scope.projectId, eventType, payload: value });
+        return { changed: true, scope: readInteractiveMutationScope(context, this.#scope, this.#bundle) };
+    }
+}
+/** Physical working-tree evidence before integration, not semantic approval or
+ * permission to stage/commit. Observe outside the writer, then fence the same
+ * user/scope revision inside the ordinary Stage/Work acceptance transaction. */
+export class PreparedInteractiveWorkspaceChanges {
+    sha256;
+    #scope;
+    #bundle;
+    #selection;
+    #input;
+    #observed;
+    #retainedPaths;
+    constructor(scope, bundle, selection, input, retainedPaths) {
+        if (selection.needs_scope_refresh)
+            refuse("current_scope_required");
+        this.#scope = { ...scope };
+        this.#bundle = bundle;
+        this.#selection = selection;
+        this.#input = { ...input, env: { ...input.env } };
+        this.#retainedPaths = [...retainedPaths];
+        // Retain explicitly selected paths even when project ignore rules hide new
+        // files. Git visibility alone must not turn an approved edit into no delta.
+        this.#observed = selection.baseline.observeChanges(this.#input, [...selection.active_paths, ...this.#retainedPaths]);
+        const { delta } = this.#observed, allowed = new Set(selection.active_paths);
+        const originals = new Map(selection.before_versions.map(item => [item.path, item]));
+        if (delta.head_changed || delta.index_changed)
+            refuse("git_movement_requires_integration");
+        for (const change of delta.changes) {
+            if (!allowed.has(change.path))
+                refuse("working_change_outside_scope");
+            const original = originals.get(change.path);
+            if (!original || (change.before ? original.kind !== "file" || original.sha256 !== change.before.sha256 || original.mode !== change.before.mode
+                : original.kind !== "missing"))
+                refuse("working_change_before_version_missing");
+            if (change.after && change.after.kind !== "file")
+                refuse("regular_file_scope_required");
+            if (change.after && fs.lstatSync(path.join(this.#input.workspace, change.path)).nlink !== 1)
+                refuse("linked_working_change");
+        }
+        this.sha256 = hybridDigest(this.snapshot());
+        Object.freeze(this);
+    }
+    static prepare(context, scope, bundle, input, retainedPaths = []) {
+        if (context.db.isOwnedWriteTransaction?.())
+            refuse("physical_observation_outside_writer_required");
+        return new PreparedInteractiveWorkspaceChanges(scope, bundle, readInteractiveMutationScope(context, scope, bundle), input, retainedPaths);
+    }
+    snapshot() {
+        return { schema_id: "dd-flow/interactive-workspace-changes@1", run_id: this.#scope.runId,
+            bundle_sha256: this.#bundle.sha256, scope_revision: this.#selection.revision,
+            user_inputs_sha256: this.#selection.inputs.sha256, delta: structuredClone(this.#observed.delta) };
+    }
+    currentSnapshot() { return this.#observed.current.snapshot(); }
+    revalidate() {
+        const observed = this.#selection.baseline.observeChanges(this.#input, [...this.#selection.active_paths, ...this.#retainedPaths]);
+        if (observed.current.sha256 !== this.#observed.current.sha256)
+            refuse("working_changes_changed_before_acceptance");
+        for (const change of observed.delta.changes)
+            if (change.after && fs.lstatSync(path.join(this.#input.workspace, change.path)).nlink !== 1)
+                refuse("linked_working_change");
+    }
+    assertCustody(context) {
+        if (!context.db.isOwnedWriteTransaction?.())
+            refuse("owned_writer_required");
+        const current = readInteractiveMutationScope(context, this.#scope, this.#bundle);
+        if (current.needs_scope_refresh || current.revision !== this.#selection.revision
+            || current.inputs.sha256 !== this.#selection.inputs.sha256 || current.baseline.sha256 !== this.#selection.baseline.sha256)
+            refuse("working_changes_scope_changed");
+    }
+}