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

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 };
+}

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

@@ -0,0 +1,230 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
+function refuse(reason) {
+    throw new AppError("interactive_git_baseline_invalid", "Interactive needs its actual project/workspace Git baseline", 2, { reason, effect: "no_effect" });
+}
+function logical(value) {
+    return typeof value === "string" && value.length > 0 && value.length <= 4096 && !value.includes("\\") && !value.includes("\0")
+        && !path.isAbsolute(value) && value.split("/").every(part => part && part !== "." && part !== ".." && part !== ".git");
+}
+/** Hash regular files incrementally: large assets do not require a second full
+ * in-memory copy. Do not follow symlinks, read FIFOs or invoke Git clean filters. */
+function entry(root, name) {
+    const file = path.join(root, name);
+    let parent = root;
+    for (const part of name.split("/").slice(0, -1)) {
+        parent = path.join(parent, part);
+        try {
+            if (!fs.lstatSync(parent).isDirectory())
+                return { path: name, kind: "missing", mode: null, sha256: null };
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return { path: name, kind: "missing", mode: null, sha256: null };
+            throw error;
+        }
+    }
+    let stat;
+    try {
+        stat = fs.lstatSync(file);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { path: name, kind: "missing", mode: null, sha256: null };
+        throw error;
+    }
+    const mode = stat.mode & 0o7777;
+    if (stat.isSymbolicLink())
+        return { path: name, kind: "link", mode, sha256: hash(fs.readlinkSync(file, { encoding: "buffer" })) };
+    // Gitlinks/submodules are opaque. Their nested working tree is not included
+    // in this parent repository's git-visible scope or a writable-file delta.
+    if (stat.isDirectory())
+        return { path: name, kind: "directory", mode, sha256: null };
+    if (!stat.isFile())
+        refuse("special_file");
+    const fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    try {
+        const before = fs.fstatSync(fd, { bigint: true }), digest = createHash("sha256"), buffer = Buffer.allocUnsafe(256 * 1024);
+        if (before.dev !== BigInt(stat.dev) || before.ino !== BigInt(stat.ino) || !before.isFile())
+            refuse("file_changed_during_capture");
+        let length = 0n;
+        for (;;) {
+            const count = fs.readSync(fd, buffer, 0, buffer.length, null);
+            if (!count)
+                break;
+            digest.update(buffer.subarray(0, count));
+            length += BigInt(count);
+        }
+        const after = fs.fstatSync(fd, { bigint: true });
+        if (length !== before.size || after.size !== before.size || after.mtimeNs !== before.mtimeNs || after.ctimeNs !== before.ctimeNs)
+            refuse("file_changed_during_capture");
+        return { path: name, kind: "file", mode, sha256: digest.digest("hex") };
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function stamp(root, name) {
+    try {
+        let parent = root;
+        for (const part of name.split("/").slice(0, -1)) {
+            parent = path.join(parent, part);
+            if (!fs.lstatSync(parent).isDirectory())
+                return null;
+        }
+        const value = fs.lstatSync(path.join(root, name), { bigint: true });
+        return [value.dev, value.ino, value.mode, value.size, value.mtimeNs, value.ctimeNs].map(String);
+    }
+    catch (error) {
+        if (["ENOENT", "ENOTDIR"].includes(error.code ?? ""))
+            return null;
+        throw error;
+    }
+}
+function observe(input, retainedPaths = []) {
+    if (!path.isAbsolute(input.gitExecutable))
+        refuse("absolute_git_executable_required");
+    for (const root of [input.projectRoot, input.workspace]) {
+        if (!path.isAbsolute(root) || fs.realpathSync(root) !== root || !fs.lstatSync(root).isDirectory())
+            refuse("canonical_workspace_required");
+    }
+    const env = { ...Object.fromEntries(Object.entries(input.env).filter(([key]) => !key.startsWith("GIT_"))), GIT_OPTIONAL_LOCKS: "0" };
+    const git = (root, args, absent = false) => {
+        const result = spawnSync(input.gitExecutable, ["-c", "core.fsmonitor=false", "-C", root, ...args], { env, timeout: 15000, maxBuffer: 32 * 1024 * 1024 });
+        if (result.error || result.signal || result.status !== 0 && !(absent && [1, 128].includes(result.status ?? -1)))
+            refuse("git_observation_failed");
+        return result.status === 0 ? result.stdout : null;
+    };
+    const text = (root, args, absent = false) => git(root, args, absent)?.toString("utf8").trim() ?? null;
+    const repository = fs.realpathSync(text(input.projectRoot, ["rev-parse", "--path-format=absolute", "--git-common-dir"]));
+    if (fs.realpathSync(text(input.workspace, ["rev-parse", "--path-format=absolute", "--git-common-dir"])) !== repository
+        || text(input.projectRoot, ["rev-parse", "--show-toplevel"]) !== input.projectRoot
+        || text(input.workspace, ["rev-parse", "--show-toplevel"]) !== input.workspace)
+        refuse("foreign_workspace_repository");
+    if (git(input.workspace, ["ls-files", "--unmerged", "-z"]).length)
+        refuse("unmerged_index");
+    const identity = fs.statSync(input.workspace);
+    const meta = () => {
+        const index = text(input.workspace, ["rev-parse", "--path-format=absolute", "--git-path", "index"]);
+        let indexHash = null;
+        try {
+            indexHash = hash(fs.readFileSync(index));
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        return { head: text(input.workspace, ["rev-parse", "--verify", "HEAD"], true), branch: text(input.workspace, ["symbolic-ref", "--quiet", "--short", "HEAD"], true),
+            index_sha256: indexHash, status_base64: git(input.workspace, ["status", "--porcelain=v1", "-z", "--untracked-files=all", "--ignore-submodules=all"]).toString("base64") };
+    };
+    const names = () => {
+        const bytes = git(input.workspace, ["ls-files", "--cached", "--others", "--exclude-standard", "-z"]);
+        let value;
+        try {
+            value = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+        }
+        catch {
+            return refuse("non_utf8_file_name");
+        }
+        const items = [...new Set(value.split("\0").filter(Boolean))].sort();
+        if (items.length > 200_000 || items.some(name => !logical(name)))
+            refuse("unsafe_or_unbounded_inventory");
+        return items;
+    };
+    const before = meta(), visible = names(), paths = [...new Set([...visible, ...retainedPaths])].sort();
+    if (paths.length > 200_000 || paths.some(name => !logical(name)))
+        refuse("unsafe_or_unbounded_inventory");
+    const stamps = paths.map(name => stamp(input.workspace, name)), entries = paths.map(name => entry(input.workspace, name));
+    const currentRoot = fs.statSync(input.workspace);
+    if (identity.dev !== currentRoot.dev || identity.ino !== currentRoot.ino || hybridDigest(stamps) !== hybridDigest(paths.map(name => stamp(input.workspace, name)))
+        || hybridDigest(before) !== hybridDigest(meta()) || hybridDigest(visible) !== hybridDigest(names()))
+        refuse("workspace_changed_during_capture");
+    return { schema_id: "dd-flow/interactive-git-baseline@1", project_root: input.projectRoot, workspace: input.workspace,
+        repository, workspace_identity: { dev: identity.dev, ino: identity.ino }, ...before, visibility: "git-visible-and-retained@1", entries };
+}
+/** Read-only physical baseline, not permission to edit/commit existing dirty
+ * files. The RUN owner must retain this in its admitted bundle before work.
+ * Ignored files and opaque submodule contents are explicitly outside visibility. */
+export class PreparedInteractiveGitBaseline {
+    sha256;
+    #value;
+    constructor(value) {
+        if (Buffer.byteLength(JSON.stringify(value)) > 32 * 1024 * 1024)
+            refuse("unbounded_baseline");
+        this.#value = structuredClone(value);
+        this.sha256 = hash(Buffer.from(JSON.stringify(value)));
+        Object.freeze(this);
+    }
+    static capture(input) { return new PreparedInteractiveGitBaseline(observe(input)); }
+    /** Parsing only. Expected bytes/hash must come from the RUN's admitted bundle,
+     * not a caller's self-hashed replacement or a current project observation. */
+    static restore(bytes, expectedSha256) {
+        if (!bytes.length || bytes.length > 32 * 1024 * 1024 || !/^[a-f0-9]{64}$/.test(expectedSha256) || hash(bytes) !== expectedSha256)
+            refuse("retained_baseline_changed");
+        let value;
+        try {
+            value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+        }
+        catch {
+            return refuse("invalid_retained_baseline");
+        }
+        const checksum = (item) => typeof item === "string" && /^[a-f0-9]{64}$/.test(item);
+        if (!value || Object.keys(value).sort().join() !== "branch,entries,head,index_sha256,project_root,repository,schema_id,status_base64,visibility,workspace,workspace_identity"
+            || value.schema_id !== "dd-flow/interactive-git-baseline@1" || value.visibility !== "git-visible-and-retained@1"
+            || [value.project_root, value.workspace, value.repository].some(item => typeof item !== "string" || !path.isAbsolute(item))
+            || !value.workspace_identity || Object.keys(value.workspace_identity).sort().join() !== "dev,ino"
+            || Object.values(value.workspace_identity).some(item => !Number.isSafeInteger(item) || item < 0)
+            || value.branch !== null && (typeof value.branch !== "string" || !value.branch)
+            || value.head !== null && (typeof value.head !== "string" || !/^[a-f0-9]{40,64}$/.test(value.head))
+            || value.index_sha256 !== null && !checksum(value.index_sha256)
+            || typeof value.status_base64 !== "string" || Buffer.from(value.status_base64, "base64").toString("base64") !== value.status_base64
+            || !Array.isArray(value.entries) || value.entries.length > 200_000)
+            refuse("invalid_retained_baseline");
+        let previous = "";
+        for (const item of value.entries) {
+            if (!item || Object.keys(item).sort().join() !== "kind,mode,path,sha256" || !logical(item.path) || item.path <= previous
+                || !["file", "link", "directory", "missing"].includes(item.kind)
+                || (item.kind === "missing" ? item.mode !== null : !Number.isInteger(item.mode) || item.mode < 0 || item.mode > 0o7777)
+                || (["file", "link"].includes(item.kind) ? !checksum(item.sha256) : item.sha256 !== null))
+                refuse("invalid_retained_inventory");
+            previous = item.path;
+        }
+        const restored = new PreparedInteractiveGitBaseline(value);
+        if (restored.sha256 !== expectedSha256)
+            refuse("retained_baseline_changed");
+        return restored;
+    }
+    snapshot() { return structuredClone(this.#value); }
+    bytes() { return Buffer.from(JSON.stringify(this.#value)); }
+    revalidate(input) {
+        if (PreparedInteractiveGitBaseline.capture(input).sha256 !== this.sha256)
+            refuse("baseline_changed_before_retention");
+    }
+    observeChanges(input, retainedPaths = []) {
+        const current = new PreparedInteractiveGitBaseline(observe(input, [...this.#value.entries.map(item => item.path), ...retainedPaths]));
+        return { current, delta: this.changes(current) };
+    }
+    /** Exact working-file delta relative to entry, not HEAD. Pre-existing dirty
+     * content is not automatically attributed to this interactive RUN. Git/index
+     * movement is reported separately, never silently approved as integration. */
+    changes(current) {
+        const before = this.#value, after = current.#value;
+        if (before.project_root !== after.project_root || before.workspace !== after.workspace || before.repository !== after.repository
+            || hybridDigest(before.workspace_identity) !== hybridDigest(after.workspace_identity) || before.branch !== after.branch)
+            refuse("workspace_identity_changed");
+        const left = new Map(before.entries.map(item => [item.path, item])), right = new Map(after.entries.map(item => [item.path, item]));
+        if ([...left.keys()].some(name => !right.has(name)))
+            refuse("baseline_paths_not_observed");
+        const changes = [...new Set([...left.keys(), ...right.keys()])].sort().flatMap(name => {
+            const old = left.get(name)?.kind === "missing" ? null : left.get(name) ?? null, next = right.get(name)?.kind === "missing" ? null : right.get(name) ?? null;
+            return hybridDigest(old) === hybridDigest(next) ? [] : [{ path: name, before: old, after: next }];
+        });
+        return { baseline_sha256: this.sha256, current_sha256: current.sha256, changes,
+            head_changed: before.head !== after.head, index_changed: before.index_sha256 !== after.index_sha256 };
+    }
+}