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

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

@@ -0,0 +1,85 @@
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+const partLimit = 1024 * 1024, totalLimit = 32 * partLimit;
+const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
+function refuse(reason) {
+    throw new AppError("interactive_bundle_data_invalid", "Interactive data must fit the existing retained bundle limits", 2, { reason, effect: "no_effect" });
+}
+function pathFor(logical, ordinal) { return `${logical}.parts/${String(ordinal).padStart(4, "0")}.bin`; }
+function supported(logical) { if (!["runtime/git-baseline.json", "runtime/before-versions.json", "runtime/work-context.json"].includes(logical))
+    refuse("unsupported_data_role"); }
+/** Packaging only, not admission. Keep ordinary small JSON unchanged; large
+ * before-images use explicit immutable parts instead of widening global limits. */
+export function putInteractiveBundleData(blobs, logical, input) {
+    supported(logical);
+    if (!input.length || input.byteLength > totalLimit)
+        refuse("unbounded_data");
+    const bytes = Buffer.from(input), additions = new Map();
+    const sha256 = hash(bytes);
+    if (bytes.length <= partLimit)
+        additions.set(logical, bytes);
+    else {
+        const parts = [];
+        for (let offset = 0; offset < bytes.length; offset += partLimit) {
+            const part = Buffer.from(bytes.subarray(offset, offset + partLimit)), file = pathFor(logical, parts.length);
+            additions.set(file, part);
+            parts.push({ path: file, bytes: part.length, sha256: hash(part) });
+        }
+        const index = { schema_id: "dd-flow/interactive-bundle-parts@1", logical_path: logical, bytes: bytes.length, sha256, parts };
+        additions.set(logical, Buffer.from(JSON.stringify(index)));
+    }
+    const existing = new Set([...blobs.keys()].map(name => name.toLowerCase()));
+    if ([...additions.keys()].some(name => existing.has(name.toLowerCase())))
+        refuse("data_path_collision");
+    const total = [...blobs.values(), ...additions.values()].reduce((sum, value) => sum + value.length, 0);
+    if (total > totalLimit)
+        refuse("bundle_budget_exceeded");
+    for (const [file, content] of additions)
+        blobs.set(file, content);
+    return { sha256, reference: { path: logical, sha256: hash(additions.get(logical)) } };
+}
+/** Reads only the selected inventory, never nearby files or current project
+ * bytes. For multipart data reference hashes the physical index; sha256 hashes
+ * the reconstructed logical data. They intentionally are not interchangeable. */
+export function readInteractiveBundleData(bundle, logical) {
+    supported(logical);
+    const physical = (file) => {
+        const refs = bundle.manifest.inventory.filter(item => item.path === file);
+        if (refs.length !== 1)
+            refuse("data_reference_required");
+        const bytes = bundle.blob(file);
+        if (!bytes.length || bytes.length > partLimit || hash(bytes) !== refs[0].sha256)
+            refuse("data_part_changed");
+        return { bytes, reference: refs[0] };
+    };
+    const root = physical(logical);
+    let value;
+    try {
+        value = JSON.parse(root.bytes.toString("utf8"));
+    }
+    catch {
+        value = null;
+    }
+    if (!value || typeof value !== "object" || value.schema_id !== "dd-flow/interactive-bundle-parts@1")
+        return { ...root, sha256: root.reference.sha256 };
+    const index = value;
+    if (Object.keys(index).sort().join() !== "bytes,logical_path,parts,schema_id,sha256" || index.logical_path !== logical
+        || !Number.isSafeInteger(index.bytes) || index.bytes <= partLimit || index.bytes > totalLimit
+        || typeof index.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(index.sha256) || !Array.isArray(index.parts)
+        || index.parts.length !== Math.ceil(index.bytes / partLimit))
+        refuse("invalid_data_index");
+    const parts = [];
+    for (const [ordinal, part] of index.parts.entries()) {
+        if (!part || Object.keys(part).sort().join() !== "bytes,path,sha256" || part.path !== pathFor(logical, ordinal)
+            || part.bytes !== Math.min(partLimit, index.bytes - ordinal * partLimit))
+            refuse("invalid_data_part");
+        const selected = physical(part.path);
+        if (selected.reference.sha256 !== part.sha256 || selected.bytes.length !== part.bytes)
+            refuse("data_part_changed");
+        parts.push(selected.bytes);
+    }
+    const bytes = Buffer.concat(parts);
+    if (bytes.length !== index.bytes || hash(bytes) !== index.sha256)
+        refuse("logical_data_changed");
+    return { bytes, sha256: index.sha256, reference: root.reference };
+}

package/dist/services/interactive-checks.js

@@ -0,0 +1,179 @@
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { appendAudit } from "./audit.js";
+import { readInteractiveStageScope } from "./interactive-stage-entry.js";
+import { readDescriptorStageInput } from "./descriptor-stage-coordinator.js";
+import { assertPreparedRunBundleSqlAuthority } from "./runs.js";
+import { PreparedInteractiveWorkspaceChanges } from "./interactive-mutation-scope.js";
+import { readInteractiveWorkGit } from "./interactive-work-start.js";
+import { readInteractiveWorkHistory } from "./interactive-work-history.js";
+import { codeCheckProfileHash, projectPolicyCheckDeclarations, runCodeChecks, PreparedCheckEvidence, validateCheckDeclaration } from "./code-checks.js";
+import { memoryCheckEnvironment } from "./memory-verification-checks.js";
+function refuse(reason) {
+    throw new AppError("interactive_checks_invalid", "Interactive checks require retained obligations and the exact current patch", 2, { reason, effect: "no_effect" });
+}
+const event = "interactive.check_plan";
+function latest(context, scope) {
+    const row = context.db.get("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type=? AND json_extract(payload_json,'$.run_id')=? ORDER BY id DESC LIMIT 1", [scope.projectId, event, scope.runId]);
+    if (!row)
+        return null;
+    if (Buffer.byteLength(row.payload_json) > 1024 * 1024)
+        refuse("unbounded_check_plan");
+    const value = JSON.parse(row.payload_json);
+    if (value.run_id !== scope.runId || value.plan?.run_id !== scope.runId || value.plan.schema_id !== "dd-flow/interactive-check-plan@1"
+        || value.sha256 !== hybridDigest(value.plan) || !Array.isArray(value.plan.checks))
+        refuse("changed_check_plan");
+    return value;
+}
+/** One existing aggregate check runner and receipt store. Selection is retained
+ * before execution, independently of the Stage proposal being assessed. */
+export class PreparedInteractiveChecks {
+    sha256;
+    #selected;
+    #packet;
+    #changes;
+    #history;
+    #plan;
+    #environment;
+    constructor(selected, packet, changes, history, plan, environment) {
+        this.#selected = selected;
+        this.#packet = packet;
+        this.#changes = changes;
+        this.#history = history;
+        this.#plan = structuredClone(plan);
+        this.#environment = environment;
+        this.sha256 = hybridDigest(plan);
+        Object.freeze(this);
+    }
+    static prepare(context, input) {
+        if (context.db.isOwnedWriteTransaction?.())
+            refuse("preparation_outside_writer_required");
+        if (!["hardening", "review"].includes(input.stage) || !Array.isArray(input.additionalChecks) || input.additionalChecks.length > 4096)
+            refuse("invalid_check_selection");
+        const selected = readInteractiveStageScope(context, input), { scope, bundle, run } = selected;
+        const packet = readDescriptorStageInput(context, scope, bundle), frozen = bundle.execution.snapshot().scope, git = readInteractiveWorkGit(bundle);
+        if (!run.run_root)
+            refuse("run_root_required");
+        if (selected.selected.needs_scope_refresh)
+            refuse("current_scope_required");
+        const checks = [...projectPolicyCheckDeclarations(frozen.workspace, "code"), ...projectPolicyCheckDeclarations(frozen.workspace, "readiness")];
+        const ids = new Set(checks.map(check => check.id));
+        for (const extra of input.additionalChecks) {
+            if (!extra || Object.keys(extra).sort().join() !== "command,id,purpose" || typeof extra.id !== "string" || !/^CHK-[A-Za-z0-9-]{1,64}$/.test(extra.id)
+                || ids.has(extra.id) || [extra.command, extra.purpose].some(value => typeof value !== "string" || !value.trim() || value.includes("\0") || Buffer.byteLength(value) > 16384))
+                refuse("invalid_check_selection");
+            ids.add(extra.id);
+            checks.push({ ...extra, source: "plan", availability: "available", run_at: "readiness" });
+        }
+        checks.sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+        for (const check of checks)
+            validateCheckDeclaration(frozen.workspace, check);
+        if (!checks.length && (typeof input.noChecksReason !== "string" || !input.noChecksReason.trim() || input.noChecksReason.includes("\0") || Buffer.byteLength(input.noChecksReason) > 16384))
+            refuse("explicit_no_checks_reason_required");
+        if (checks.length && input.noChecksReason !== undefined)
+            refuse("no_checks_reason_with_checks");
+        const changes = PreparedInteractiveWorkspaceChanges.prepare(context, scope, bundle, { projectRoot: frozen.projectRoot,
+            workspace: frozen.workspace, gitExecutable: git.git_executable, env: context.env });
+        const plan = { schema_id: "dd-flow/interactive-check-plan@1", run_id: input.runId, stage: input.stage, attempt: packet.attempt,
+            bundle_sha256: bundle.sha256, input_sha256: packet.inputSha256, user_inputs_sha256: selected.selected.inputs.sha256,
+            scope_revision: selected.selected.revision, file_changes_sha256: hybridDigest(changes.snapshot().delta.changes),
+            profile_sha256: codeCheckProfileHash(frozen.workspace, checks), checks, no_checks_reason: checks.length ? null : input.noChecksReason };
+        if (Buffer.byteLength(JSON.stringify({ run_id: plan.run_id, sha256: "a".repeat(64), plan })) > 1024 * 1024)
+            refuse("unbounded_check_plan");
+        const prepared = new PreparedInteractiveChecks(selected, packet, changes, hybridDigest(readInteractiveWorkHistory(context, scope, bundle)), plan, memoryCheckEnvironment(context, scope.projectId, scope.runId));
+        prepared.revalidate(context);
+        return prepared;
+    }
+    static restore(context, input) {
+        const selected = readInteractiveStageScope(context, input), retained = latest(context, selected.scope);
+        if (!retained || retained.plan.stage !== input.stage)
+            refuse("retained_check_plan_required");
+        const prepared = this.prepare(context, { ...input, additionalChecks: retained.plan.checks.filter(check => check.source === "plan")
+                .map(({ id, command, purpose }) => ({ id, command, purpose })),
+            ...(retained.plan.no_checks_reason === null ? {} : { noChecksReason: retained.plan.no_checks_reason }) });
+        if (prepared.sha256 !== retained.sha256)
+            refuse("retained_check_plan_changed");
+        return prepared;
+    }
+    /** Carry declared obligations into the initial critic's current Stage. The
+     * common evidence owner still rejects changed task/patch/policy or missing
+     * receipts; this does not execute or bless an author's test claims. */
+    static prepareReview(context, input) {
+        const selected = readInteractiveStageScope(context, { ...input, stage: "review" }), retained = latest(context, selected.scope);
+        if (!retained)
+            return null;
+        return this.prepare(context, { ...input, stage: "review", additionalChecks: retained.plan.checks.filter(check => check.source === "plan")
+                .map(({ id, command, purpose }) => ({ id, command, purpose })),
+            ...(retained.plan.no_checks_reason === null ? {} : { noChecksReason: retained.plan.no_checks_reason }) });
+    }
+    value() { return structuredClone(this.#plan); }
+    checkInput() {
+        const { bundle_sha256, user_inputs_sha256, scope_revision, file_changes_sha256, profile_sha256, checks } = this.#plan;
+        return { projectId: this.#selected.scope.projectId, runId: this.#plan.run_id, runHome: this.#packet.runRoot,
+            workspaceRoot: this.#selected.bundle.execution.snapshot().scope.workspace, scope: "aggregate",
+            checks: structuredClone(checks), expectedProfileHash: profile_sha256,
+            // Stage custody changes do not by themselves invalidate checks of the
+            // same task/patch/policy. The common runner still owns reuse eligibility.
+            evidenceContext: `interactive:${hybridDigest({ bundle_sha256, user_inputs_sha256, scope_revision, file_changes_sha256, profile_sha256, checks })}`,
+            artifactDir: `${this.#selected.bundle.descriptor.stage(this.#plan.stage).directory}/checks/${this.sha256}`,
+            ...(this.#environment ? { checkEnvironment: this.#environment } : {}) };
+    }
+    assertSelection(context) {
+        this.#selected.assertCustody(context);
+        const { scope, bundle } = this.#selected, run = assertPreparedRunBundleSqlAuthority(context, scope, bundle), index = JSON.parse(run.index_json);
+        if (run.status !== "running" || index.current_stage !== this.#plan.stage
+            || hybridDigest(readDescriptorStageInput(context, scope, bundle)) !== hybridDigest(this.#packet)
+            || hybridDigest(readInteractiveWorkHistory(context, scope, bundle)) !== this.#history)
+            refuse("check_selection_changed");
+        const previous = latest(context, scope);
+        if (previous && previous.plan.user_inputs_sha256 === this.#plan.user_inputs_sha256
+            && previous.plan.checks.some(check => !this.#plan.checks.some(current => hybridDigest(current) === hybridDigest(check))))
+            refuse("check_obligation_dropped");
+    }
+    revalidate(context) {
+        this.#changes.revalidate();
+        readInteractiveWorkGit(this.#selected.bundle);
+        if (codeCheckProfileHash(this.checkInput().workspaceRoot, this.#plan.checks) !== this.#plan.profile_sha256
+            || hybridDigest(memoryCheckEnvironment(context, this.#selected.scope.projectId, this.#plan.run_id) ?? null) !== hybridDigest(this.#environment ?? null))
+            refuse("check_policy_changed");
+        context.db.readSnapshot(() => this.assertSelection(context));
+    }
+    retain(context) {
+        this.revalidate(context);
+        return context.db.writeTransaction(() => {
+            this.#changes.assertCustody(context);
+            this.assertSelection(context);
+            if (latest(context, this.#selected.scope)?.sha256 === this.sha256)
+                return { changed: false };
+            appendAudit(context, { projectId: this.#selected.scope.projectId, eventType: event, payload: { run_id: this.#plan.run_id, sha256: this.sha256, plan: this.value() } });
+            return { changed: true };
+        });
+    }
+    assertCustody(context) {
+        this.#changes.assertCustody(context);
+        this.assertSelection(context);
+        if (latest(context, this.#selected.scope)?.sha256 !== this.sha256)
+            refuse("retained_check_plan_required");
+    }
+    async execute(context) {
+        this.retain(context);
+        if (!this.#plan.checks.length)
+            return [];
+        const receipts = await runCodeChecks(context, this.checkInput());
+        try {
+            this.revalidate(context);
+        }
+        catch (error) {
+            if (error instanceof AppError)
+                error.details.effect = "committed";
+            throw error;
+        }
+        return receipts;
+    }
+    evidence(context) {
+        this.revalidate(context);
+        if (latest(context, this.#selected.scope)?.sha256 !== this.sha256)
+            refuse("retained_check_plan_required");
+        return this.#plan.checks.length ? PreparedCheckEvidence.prepare(context, this.checkInput()) : null;
+    }
+}

package/dist/services/interactive-execution.js

@@ -0,0 +1,33 @@
+import { AppError } from "../shared/errors.js";
+import { FrozenGenericExecution } from "./generic-execution.js";
+import { PreparedInteractiveAttachedSession } from "./interactive-attached-session.js";
+import { prepareOperatorProfile, resolveOperatorProfile } from "./operator-profiles.js";
+/** Fresh interactive selection only; continuation restores the retained bundle
+ * rather than re-reading current defaults or claiming a different Session. */
+export function prepareInteractiveExecution(context, input) {
+    const { scope, flow, profiles, selection } = input;
+    if (flow.descriptor.id !== "interactive" || Object.hasOwn(selection, "attachedSessionReceipt")) {
+        throw new AppError("interactive_execution_invalid", "Interactive execution must use its registered flow and CLI-owned Session binding", 2, { effect: "no_effect" });
+    }
+    const mode = selection.execution ?? "attached";
+    const stageSessionMode = selection.stageSessionMode ?? (mode === "attached" ? "same_session" : "new_session");
+    let attached = null;
+    let receipts = new Map();
+    const receiptBytes = new Map();
+    if (mode === "attached") {
+        if (!input.source && !input.launchArgs)
+            throw new AppError("interactive_attached_session_required", "Interactive defaults to the current trusted Session; select managed execution explicitly when unavailable", 2, { phase: "prepare", effect: "no_effect", next_action: "provide_matching_attached_session_or_choose_managed" });
+        if (stageSessionMode !== "same_session")
+            throw new AppError("interactive_execution_invalid", "An attached root cannot claim a new physical Session per Stage; choose managed execution for that route", 2, { effect: "no_effect" });
+        const profile = prepareOperatorProfile(typeof selection.rootProfile === "object" ? selection.rootProfile : resolveOperatorProfile(profiles, selection.rootProfile));
+        attached = input.source ? PreparedInteractiveAttachedSession.prepare(context, scope, profile, input.source)
+            : PreparedInteractiveAttachedSession.prepareCurrent(context, scope, profile, input.launchArgs);
+        const evidence = attached.evidence();
+        receipts = evidence.receipts;
+        receiptBytes.set(evidence.reference.sha256, evidence.bytes);
+    }
+    const execution = FrozenGenericExecution.prepare(flow, profiles, { ...selection, execution: mode,
+        stageSessionMode, delegation: selection.delegation ?? { mode: "external", max_parallel: 1 },
+        ...(attached ? { attachedSessionReceipt: attached.evidence().reference } : {}) }, scope, receipts);
+    return { execution, attached, receipts, receiptBytes };
+}

package/dist/services/interactive-finish-integration.js

@@ -0,0 +1,236 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { assertPreparedRunBundleSqlAuthority } from "./runs.js";
+import { readInteractiveStageScope } from "./interactive-stage-entry.js";
+import { readAcceptedInteractiveStage } from "./interactive-stage-handlers.js";
+import { readCompletedInteractiveWork } from "./interactive-work-completion.js";
+import { PreparedInteractiveWorkspaceChanges, assertInteractiveUserBasis } from "./interactive-mutation-scope.js";
+import { readInteractiveWorkGit } from "./interactive-work-start.js";
+import { assertReviewedProjectGitInventory } from "./project-git-integration.js";
+const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
+function refuse(reason) {
+    throw new AppError("interactive_finish_integration_invalid", "Integration requires the accepted interactive task, review and exact original Git inputs", 2, { reason, effect: "no_effect" });
+}
+/** Frozen SQL/bundle policy, never ambient branch inference or Git authority. */
+export function readInteractiveGitPolicy(context, scope, bundle) {
+    if (bundle.manifest.flow_id !== "interactive")
+        refuse("interactive_bundle_required");
+    const run = assertPreparedRunBundleSqlAuthority(context, scope, bundle), logical = "runtime/git-policy.json";
+    const references = bundle.manifest.inventory.filter(ref => ref.path === logical), bytes = bundle.blob(logical);
+    if (references.length !== 1 || !bytes.length || bytes.length > 32768 || references[0].sha256 !== hash(bytes))
+        refuse("frozen_git_policy_required");
+    let value;
+    try {
+        value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        return refuse("invalid_git_policy");
+    }
+    const frozen = bundle.execution.snapshot().scope;
+    if (value?.schema_id !== "dd-flow/interactive-git-policy@1" || Object.keys(value).sort().join() !== "git_executable,git_sha256,policy,schema_id,scope"
+        || Object.keys(value.scope ?? {}).sort().join() !== "projectRoot,requestId,workspaceRoot"
+        || value.scope?.projectRoot !== run.project_root || value.scope?.workspaceRoot !== run.workspace_root
+        || value.scope.projectRoot !== frozen.projectRoot || value.scope.workspaceRoot !== frozen.workspace || value.scope.requestId !== frozen.requestId
+        || typeof value.git_executable !== "string" || !path.isAbsolute(value.git_executable) || !/^[a-f0-9]{64}$/.test(value.git_sha256)
+        || value.policy?.source !== "explicit_request" || value.policy.push_authorized !== false
+        || !["feature_worktree", "integration_branch_direct"].includes(value.policy.route)
+        || typeof value.policy.repository !== "string" || !path.isAbsolute(value.policy.repository)
+        || !value.policy.workspace_branch || !value.policy.integration_branch
+        || value.policy.initial_head !== null && !/^[a-f0-9]{40,64}$/.test(value.policy.initial_head))
+        refuse("git_policy_scope_changed");
+    return structuredClone(value);
+}
+/** Read-only early inspection; no accepted review, Git write or inclusion
+ * approval is required. Resolve any user decision before freezing review. */
+export function observeInteractiveOriginalGitInputs(context, input) {
+    if (context.db.isOwnedWriteTransaction?.())
+        refuse("physical_observation_outside_writer_required");
+    const selected = readInteractiveStageScope(context, input), policy = readInteractiveGitPolicy(context, selected.scope, selected.bundle);
+    const git = readInteractiveWorkGit(selected.bundle);
+    if (git.git_executable !== policy.git_executable || git.git_sha256 !== policy.git_sha256)
+        refuse("selected_git_changed");
+    const baseline = selected.selected.baseline.snapshot();
+    if (policy.policy.repository !== baseline.repository || policy.policy.workspace_branch !== baseline.branch
+        || policy.policy.initial_head !== baseline.head)
+        refuse("reviewed_git_baseline_changed");
+    const changes = PreparedInteractiveWorkspaceChanges.prepare(context, selected.scope, selected.bundle, {
+        projectRoot: policy.scope.projectRoot, workspace: policy.scope.workspaceRoot, gitExecutable: git.git_executable, env: context.env
+    });
+    const originalInputs = readOriginalGitInputs(context, policy, selected.selected.active_paths, selected.selected.before_versions);
+    changes.revalidate();
+    selected.assertCustody(context);
+    if (hybridDigest(readInteractiveGitPolicy(context, selected.scope, selected.bundle)) !== hybridDigest(policy))
+        refuse("git_policy_scope_changed");
+    return { baseline_sha256: selected.selected.baseline.sha256, user_inputs_sha256: selected.selected.inputs.sha256,
+        scope_revision: selected.selected.revision, original_inputs: originalInputs };
+}
+function readOriginalGitInputs(context, policy, paths, beforeVersions) {
+    if (paths.length > 4096)
+        refuse("reviewed_inventory_exceeds_bound");
+    const before = new Map(beforeVersions.map(item => [item.path, item]));
+    const env = { ...Object.fromEntries(Object.entries(context.env).filter(([key]) => !key.startsWith("GIT_"))), GIT_OPTIONAL_LOCKS: "0", GIT_LITERAL_PATHSPECS: "1" };
+    const git = (args) => {
+        const result = spawnSync(policy.git_executable, ["-c", "core.fsmonitor=false", "-C", policy.scope.workspaceRoot, ...args], { env, timeout: 10000, maxBuffer: 16 * 1024 * 1024, shell: false, windowsHide: true });
+        if (result.error || result.signal || result.status !== 0)
+            refuse("original_git_inputs_unavailable");
+        return result.stdout;
+    };
+    let total = 0;
+    const version = (header, retain) => {
+        const match = /^([0-7]{6}) (?:blob )?([a-f0-9]{40,64})(?: 0)?$/.exec(header);
+        if (!match || !["100644", "100755", "120000"].includes(match[1]))
+            refuse("regular_original_git_input_required");
+        const bytes = git(["cat-file", "blob", match[2]]);
+        total += bytes.length;
+        if (total > 64 * 1024 * 1024)
+            refuse("original_git_inputs_exceed_bound");
+        return { sha256: hash(bytes), git_mode: match[1], ...(retain ? { base64: bytes.toString("base64") } : {}) };
+    };
+    const entries = (bytes, retain) => {
+        let text;
+        try {
+            text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+        }
+        catch {
+            return refuse("original_git_paths_invalid");
+        }
+        const values = new Map();
+        for (const entry of text.split("\0").filter(Boolean)) {
+            const tab = entry.indexOf("\t"), logical = entry.slice(tab + 1);
+            if (tab < 0 || !paths.includes(logical) || values.has(logical))
+                refuse("original_git_paths_invalid");
+            values.set(logical, version(entry.slice(0, tab), retain));
+        }
+        return values;
+    };
+    const heads = entries(paths.length && policy.policy.initial_head ? git(["ls-tree", "-z", policy.policy.initial_head, "--", ...paths]) : Buffer.alloc(0), false);
+    const indexes = entries(paths.length ? git(["ls-files", "--stage", "-z", "--", ...paths]) : Buffer.alloc(0), true);
+    const same = (left, right) => left?.sha256 === right?.sha256 && left?.git_mode === right?.git_mode;
+    return paths.map(logical => {
+        const workspace = before.get(logical);
+        if (!workspace)
+            refuse("working_change_before_version_missing");
+        const head = heads.get(logical) ?? null, index = indexes.get(logical) ?? null;
+        const source = workspace.kind === "file" ? { sha256: workspace.sha256, git_mode: workspace.mode & 0o111 ? "100755" : "100644" } : null;
+        return { path: logical, workspace: structuredClone(workspace), head, index,
+            preexisting_changes: !same(source, head) || !same(index, head) };
+    });
+}
+/** Select the exact accepted review and its entry-relative file delta from
+ * retained SQL. Works after Git effects: no fresh workspace/HEAD is used to
+ * manufacture a replacement reviewed inventory. Dispatch still needs original
+ * dirty-input admission, a retained operation intent and physical revalidation. */
+export function prepareInteractiveReviewedGitInputs(context, input) {
+    if (context.db.isOwnedWriteTransaction?.())
+        refuse("preparation_outside_writer_required");
+    const selected = readInteractiveStageScope(context, { ...input, stage: "integration" }), { scope, bundle } = selected;
+    const review = readAcceptedInteractiveStage(context, { ...input, stage: "review" });
+    const read = (writer) => {
+        const policy = readInteractiveGitPolicy(writer, scope, bundle), state = selected.selected;
+        const result = review.result, collection = review.proof.collection;
+        if (!collection || result.details.review?.verdict !== "accept" || state.needs_scope_refresh
+            || result.baseline_sha256 !== state.baseline.sha256 || result.scope_revision !== state.revision
+            || result.user_inputs_sha256 !== state.inputs.sha256 || !state.inputs.finish_requested)
+            refuse("current_accepted_review_required");
+        const work = readCompletedInteractiveWork(writer, { ...scope, workId: collection.work_id }, bundle), packet = work.start.assignment.packet;
+        if (packet.stage !== "review" || packet.owner_stage !== "review" || work.result.verdict !== "ready" || work.receipt.changes.length
+            || packet.input_sha256 !== result.input_sha256 || packet.baseline_sha256 !== result.baseline_sha256
+            || packet.scope_revision !== result.scope_revision || packet.user_inputs_sha256 !== result.user_inputs_sha256
+            || packet.file_changes_sha256 !== result.file_changes_sha256)
+            refuse("accepted_readonly_critic_required");
+        const baseline = state.baseline.snapshot(), delta = state.baseline.changes(work.start.baseline);
+        if (delta.head_changed || delta.index_changed || hybridDigest(delta.changes) !== result.file_changes_sha256
+            || work.receipt.observed_snapshot_sha256 !== work.start.baseline.sha256
+            || policy.policy.repository !== baseline.repository || policy.policy.workspace_branch !== baseline.branch
+            || policy.policy.initial_head !== baseline.head)
+            refuse("reviewed_git_baseline_changed");
+        if (delta.changes.length > 4096)
+            refuse("reviewed_inventory_exceeds_bound");
+        const originals = new Map(state.before_versions.map(item => [item.path, item]));
+        const allowed = new Set(state.active_paths);
+        const references = [], removals = [];
+        for (const change of delta.changes) {
+            const before = originals.get(change.path);
+            if (!allowed.has(change.path) || !before
+                || change.before && (change.before.kind !== "file" || before.sha256 !== change.before.sha256 || before.mode !== change.before.mode)
+                || !change.before && before.kind !== "missing" || change.after && change.after.kind !== "file")
+                refuse("reviewed_file_scope_changed");
+            const entry = change.after ?? change.before;
+            if (!entry?.sha256 || entry.mode === null)
+                refuse("reviewed_regular_file_required");
+            (change.after ? references : removals).push({ root: "workspace", path: change.path, sha256: entry.sha256,
+                git_mode: entry.mode & 0o111 ? "100755" : "100644" });
+        }
+        // An honest empty patch is a terminal no-op, not permission to merge a
+        // pre-existing feature branch or commit unrelated staged/dirty files.
+        if (delta.changes.length)
+            assertReviewedProjectGitInventory(references, removals);
+        return { policy, review_sha256: review.proof.result_sha256, review_result: review.reference, review_work_id: collection.work_id,
+            reviewed_snapshot_sha256: work.receipt.observed_snapshot_sha256, reviewed_sources_sha256: hybridDigest(work.start.baseline.snapshot().entries), baseline_sha256: state.baseline.sha256,
+            user_inputs_sha256: state.inputs.sha256, scope_revision: state.revision, file_changes_sha256: result.file_changes_sha256,
+            changes: delta.changes, inventory: { references, removals }, empty: delta.changes.length === 0 };
+    };
+    const original = context.db.readSnapshot(() => read(context));
+    const assertCustody = (writer) => {
+        selected.assertCustody(writer);
+        review.assertCustody(writer);
+        if (hybridDigest(read(writer)) !== hybridDigest(original))
+            refuse("accepted_integration_custody_changed");
+    };
+    const observeBeforeDispatch = () => {
+        if (context.db.isOwnedWriteTransaction?.())
+            refuse("physical_observation_outside_writer_required");
+        const git = readInteractiveWorkGit(bundle);
+        if (git.git_executable !== original.policy.git_executable || git.git_sha256 !== original.policy.git_sha256)
+            refuse("selected_git_changed");
+        const changes = PreparedInteractiveWorkspaceChanges.prepare(context, scope, bundle, { projectRoot: original.policy.scope.projectRoot,
+            workspace: original.policy.scope.workspaceRoot, gitExecutable: git.git_executable, env: context.env });
+        if (hash(Buffer.from(JSON.stringify(changes.currentSnapshot()))) !== original.reviewed_snapshot_sha256)
+            refuse("reviewed_sources_changed");
+        assertCustody(context);
+        return changes;
+    };
+    const assertReviewedSources = () => {
+        if (context.db.isOwnedWriteTransaction?.())
+            refuse("physical_observation_outside_writer_required");
+        // Admit the owned HEAD/index effects, not a different working source tree.
+        // An unselected dependency changing after checks cannot inherit readiness.
+        const observed = selected.selected.baseline.observeChanges({ projectRoot: original.policy.scope.projectRoot,
+            workspace: original.policy.scope.workspaceRoot, gitExecutable: original.policy.git_executable, env: context.env }, selected.selected.active_paths);
+        if (hybridDigest(observed.current.snapshot().entries) !== original.reviewed_sources_sha256)
+            refuse("reviewed_source_footprint_changed");
+        assertCustody(context);
+    };
+    const observeOriginalInputs = () => {
+        const changes = observeBeforeDispatch(), policy = original.policy;
+        const inputs = readOriginalGitInputs(context, policy, original.changes.map(change => change.path), selected.selected.before_versions);
+        changes.revalidate();
+        assertCustody(context);
+        return inputs;
+    };
+    /** Semantic interpretation stays with the agent. The CLI verifies that a
+     * declared inclusion decision cites genuine delivered user input and covers
+     * exactly the pre-existing selected changes. Finish alone is not approval.
+     * This value must be retained with the future Git operation's intent before
+     * effects; calling this helper itself performs no acceptance or Git writes. */
+    const prepareOriginalInputsAgreement = (agreement) => {
+        const originals = observeOriginalInputs(), paths = originals.filter(item => item.preexisting_changes).map(item => item.path).sort();
+        if (!paths.length) {
+            if (agreement)
+                throw new AppError("interactive_finish_integration_invalid", "Selected files have no pre-RUN changes; retry integration without --result-file", 2, { reason: "unexpected_existing_input_agreement", phase: "prepare", effect: "no_effect", recoverable: true });
+            return { original_inputs: originals, agreement: null };
+        }
+        if (!agreement)
+            throw new AppError("interactive_git_agreement_required", "Selected files contain pre-RUN changes; preserve them or explicitly agree their inclusion before commit", 2, { reason: "preexisting_selected_changes", effect: "no_effect", recoverable: true, paths, continuation: { kind: "existing_input_decision_required" } });
+        if (typeof agreement.reason !== "string" || !agreement.reason.trim() || agreement.reason.length > 64 * 1024
+            || hybridDigest(agreement.include_existing_paths) !== hybridDigest(paths))
+            refuse("exact_existing_input_agreement_required");
+        assertInteractiveUserBasis(agreement.basis, selected.selected.inputs);
+        assertCustody(context);
+        return { original_inputs: originals, agreement: { ...structuredClone(agreement), user_inputs_sha256: original.user_inputs_sha256 } };
+    };
+    return { original: structuredClone(original), assertCustody, observeBeforeDispatch, assertReviewedSources, observeOriginalInputs, prepareOriginalInputsAgreement };
+}