@llblab/pi-kit 0.18.1 → 0.19.0

package/node_modules/@llblab/pi-state-flow/dist/lib/git.js

@@ -1,16 +1,10 @@
-// Domain: durable Git revision reads, compare-and-swap publication, and exact-commit push retry.
-import { createHash } from "node:crypto";
-import { closeSync, lstatSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+// Domain: optional settled-turn backup of already-accepted canonical State Flow files.
+import { closeSync, constants, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { dirname, relative, resolve, sep } from "node:path";
-import { spawn, spawnSync } from "node:child_process";
-import { assertOwnedFileUpdates, captureOwnedFileBases, captureTemporalFileBases, isStateFlowOwnedPath, parseScopeProvenance, parseScopeStream, restoreDurableFileBases, temporalScopePaths, sessionRuntimePaths, writeOwnedFileUpdates, } from "./durable.js";
-import { parseArtifactProvenanceRegistry } from "./artifact.js";
-import { planLegacyStorageMigration } from "./migration.js";
-import { sameJson } from "./json.js";
-import { validateTemporalState } from "./temporal.js";
-import { createSessionRuntime, parseSessionRuntime, serializeSessionRuntime } from "./snapshot.js";
-import { acquirePublicationLock, assertTemporalFileBase, loadTemporalFileRevision, planTemporalPublication, temporalFileReceipts, withStoragePublicationLock } from "./storage.js";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { spawnSync } from "node:child_process";
+import { captureOwnedFileBases, isStateFlowOwnedPath } from "./durable.js";
+import { acquirePublicationLock, withStoragePublicationLock } from "./storage.js";
 const GIT_TIMEOUT_MS = 15_000;
 const STATE_FLOW_COMMIT_TRAILER = "State-Flow-Durable: v1";
 function git(repositoryRoot, args, options = {}) {
@@ -18,17 +12,12 @@ function git(repositoryRoot, args, options = {}) {
         encoding: "utf8",
         timeout: GIT_TIMEOUT_MS,
         input: options.input,
-        ...(options.maxBuffer === undefined ? {} : { maxBuffer: options.maxBuffer }),
-        env: {
-            ...process.env,
-            GIT_TERMINAL_PROMPT: "0",
-            ...options.env,
-        },
+        env: { ...process.env, GIT_TERMINAL_PROMPT: "0", ...options.env },
     });
     const status = result.status ?? 1;
     const stdout = result.stdout ?? "";
     const stderr = result.error?.message ?? result.stderr ?? "";
-    if (status !== 0 && !options.allowFailure) {
+    if (result.error || (status !== 0 && !options.allowFailure)) {
         const detail = stderr.trim() || stdout.trim() || `exit status ${status}`;
         throw new Error(`Git command failed (${args.join(" ")}): ${detail}`);
     }
@@ -39,20 +28,9 @@ function assertDirectoryPath(path) {
     if (parent !== path)
         assertDirectoryPath(parent);
     const stat = lstatSync(path, { throwIfNoEntry: false });
-    if (stat && (!stat.isDirectory() || stat.isSymbolicLink()))
+    if (stat && (!stat.isDirectory() || stat.isSymbolicLink())) {
         throw new Error(`State Flow repository path is not a regular directory: ${path}`);
-}
-/** Explicit start only: initialize this exact root, preserving existing files and ancestor Git. */
-export function initializeGitRepository(repositoryRoot) {
-    const root = resolve(repositoryRoot);
-    assertDirectoryPath(root);
-    if (lstatSync(resolve(root, ".git"), { throwIfNoEntry: false })) {
-        assertRepositoryRoot(root);
-        return;
     }
-    mkdirSync(root, { recursive: true });
-    git(root, ["init"]);
-    assertRepositoryRoot(root);
 }
 function assertRepositoryRoot(repositoryRoot) {
     const expected = resolve(repositoryRoot);
@@ -61,27 +39,80 @@ function assertRepositoryRoot(repositoryRoot) {
         throw new Error(`State Flow Git metadata must not be a symlink: ${expected}`);
     }
     const actual = resolve(git(expected, ["rev-parse", "--show-toplevel"]).stdout.trim());
-    if (actual !== expected) {
-        throw new Error(`State Flow durable repository root mismatch: expected ${expected}, found ${actual}`);
-    }
+    if (actual !== expected)
+        throw new Error(`State Flow backup repository root mismatch: expected ${expected}, found ${actual}`);
     return expected;
 }
-/** Serialize cooperating State Flow publishers through capture, commit, and rollback. */
-function withPublicationLock(repositoryRoot, action) {
-    return withStoragePublicationLock(repositoryRoot, (lockedRoot) => {
-        const root = assertRepositoryRoot(lockedRoot);
-        const common = resolve(root, git(root, ["rev-parse", "--git-common-dir"]).stdout.trim());
-        const path = resolve(common, "state-flow-publication.lock");
-        const descriptor = acquirePublicationLock(path, (cause) => new Error(`State Flow publication lock is unavailable at ${path}; reconcile the active or interrupted publisher before retrying`, { cause }));
-        try {
-            writeFileSync(descriptor, `${process.pid}\n`);
-            return action(root);
-        }
-        finally {
-            closeSync(descriptor);
-            rmSync(path);
+function withBackupLock(repositoryRoot, action) {
+    const root = assertRepositoryRoot(repositoryRoot);
+    const common = resolve(root, git(root, ["rev-parse", "--git-common-dir"]).stdout.trim());
+    const path = resolve(common, "state-flow-backup.lock");
+    const descriptor = acquirePublicationLock(path, (cause) => new Error(`State Flow backup lock is unavailable at ${path}; retry on a later settled turn`, { cause }));
+    try {
+        writeFileSync(descriptor, `${process.pid}\n`);
+        return action(root);
+    }
+    finally {
+        closeSync(descriptor);
+        rmSync(path);
+    }
+}
+/** Inventory only the bounded canonical namespace, never artifact sources or unrelated directory trees. */
+function captureBackupFiles(root, tracked) {
+    const paths = new Set([...tracked].map((path) => resolve(root, path)));
+    const visit = (directory, depth) => {
+        assertDirectoryPath(directory);
+        for (const entry of readdirSync(directory, { withFileTypes: true })) {
+            const path = join(directory, entry.name);
+            if (isStateFlowOwnedPath(path, root)) {
+                if (!entry.isFile())
+                    throw new Error(`State Flow backup source is not a regular file: ${path}`);
+                paths.add(path);
+            }
+            else if (depth < 2 && isStateFlowOwnedPath(join(path, "checkpoint.json"), root)) {
+                if (entry.isSymbolicLink())
+                    throw new Error(`State Flow backup namespace is not a regular directory: ${path}`);
+                if (entry.isDirectory())
+                    visit(path, depth + 1);
+            }
         }
-    });
+    };
+    visit(root, 0);
+    return captureOwnedFileBases([...paths].sort(), root).map((file) => ({
+        path: relative(root, file.path).split(sep).join("/"),
+        bytes: file.bytes,
+        mode: file.bytes === undefined ? 0o600 : lstatSync(file.path).mode,
+    }));
+}
+/** Stage captured bytes through native Git filters without rereading live canonical files. */
+function prepareBackupWorktree(root, worktree, files) {
+    mkdirSync(worktree);
+    const directories = new Set();
+    for (const file of files) {
+        if (file.bytes === undefined)
+            continue;
+        const target = join(worktree, file.path);
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, file.bytes, { mode: file.mode & 0o777 });
+        let directory = dirname(file.path);
+        while (true) {
+            directories.add(directory);
+            if (directory === ".")
+                break;
+            directory = dirname(directory);
+        }
+    }
+    // Git policy is not semantic input and is read outside the canonical lock.
+    for (const directory of directories) {
+        const source = join(root, directory, ".gitattributes");
+        assertDirectoryPath(dirname(source));
+        const stat = lstatSync(source, { throwIfNoEntry: false });
+        if (!stat)
+            continue;
+        if (!stat.isFile() || stat.isSymbolicLink())
+            throw new Error(`State Flow backup attributes are not a regular file: ${source}`);
+        writeFileSync(join(worktree, directory, ".gitattributes"), readFileSync(source, { flag: constants.O_RDONLY | constants.O_NOFOLLOW }), { mode: 0o600 });
+    }
 }
 function currentHead(repositoryRoot) {
     const result = git(repositoryRoot, ["rev-parse", "--verify", "HEAD"], { allowFailure: true });
@@ -89,205 +120,55 @@ function currentHead(repositoryRoot) {
 }
 function currentBranchRef(repositoryRoot) {
     const result = git(repositoryRoot, ["symbolic-ref", "--quiet", "HEAD"], { allowFailure: true });
-    if (result.status !== 0 || result.stdout.trim().length === 0) {
-        throw new Error("State Flow durable publication requires an attached Git branch");
-    }
+    if (result.status !== 0 || result.stdout.trim().length === 0)
+        throw new Error("State Flow backup requires an attached Git branch");
     return result.stdout.trim();
 }
-/** One exact-path tree query per immutable revision; inspect only blobs the caller actually selects. */
-function revisionFileReader(repositoryRoot, revision, paths) {
-    const relativePaths = new Map(paths.map((path) => [path, relativeOwnedPath(path, repositoryRoot)]));
-    if (relativePaths.size === 0)
-        throw new Error("Git revision reader requires owned paths");
-    const selected = new Set(relativePaths.values());
-    const listing = git(repositoryRoot, ["ls-tree", "-z", revision, "--", ...selected], { env: {
-            GIT_LITERAL_PATHSPECS: "1", GIT_GLOB_PATHSPECS: "0", GIT_NOGLOB_PATHSPECS: "0", GIT_ICASE_PATHSPECS: "0",
-        } }).stdout;
-    if (listing.length > 0 && !listing.endsWith("\0"))
-        throw new Error("Historical Git tree listing is incomplete");
-    const entries = new Map();
-    for (const entry of listing.split("\0").filter(Boolean)) {
-        const separator = entry.indexOf("\t");
-        if (separator < 0)
-            throw new Error("Historical Git tree listing is malformed");
-        const path = entry.slice(separator + 1);
-        if (!selected.has(path))
-            continue;
-        entries.set(path, entries.has(path) ? null : entry.slice(0, separator));
-    }
-    const files = new Map();
-    return (path) => {
-        const relativePath = relativePaths.get(path);
-        if (relativePath === undefined)
-            throw new Error(`Git revision reader did not select path: ${path}`);
-        const cached = files.get(path);
-        if (cached)
-            return cached;
-        const entry = entries.get(relativePath);
-        if (entry === null)
-            throw new Error(`Historical Git tree has duplicate path: ${relativePath}`);
-        if (entry === undefined) {
-            const missing = { path, identity: "missing" };
-            files.set(path, missing);
-            return missing;
-        }
-        if (!/^100(?:644|755) blob [0-9a-f]+$/.test(entry)) {
-            throw new Error(`Historical State Flow file is not a regular blob: ${path}`);
-        }
-        // Selected state/runtime blobs have no semantic byte cap; Node's default pipe budget is only 1 MiB.
-        const content = git(repositoryRoot, ["show", `${revision}:${relativePath}`], { maxBuffer: Infinity }).stdout;
-        const file = { path, identity: `sha256:${createHash("sha256").update(content).digest("hex")}`, content };
-        files.set(path, file);
-        return file;
-    };
-}
-function revisionFile(repositoryRoot, revision, path) {
-    return revisionFileReader(repositoryRoot, revision, [path])(path);
-}
-function assertReadableRevision(root, revision) {
-    if (!/^[0-9a-f]{40,64}$/.test(revision)
-        || git(root, ["cat-file", "-e", `${revision}^{commit}`], { allowFailure: true }).status !== 0) {
-        throw new Error(`State Flow revision is not a readable Git commit: ${revision}`);
-    }
-}
-export function captureTemporalGitBase(cwd, sessionId, repositoryRoot, sessionKey = sessionId) {
-    return withPublicationLock(repositoryRoot, (root) => captureTemporalBaseUnderLock(cwd, sessionId, root, sessionKey));
-}
-function captureTemporalBaseUnderLock(cwd, sessionId, root, sessionKey = sessionId) {
-    return { head: currentHead(root), files: captureTemporalFileBases(cwd, sessionId, root, sessionKey) };
-}
-function revisionScopeFiles(read, paths) {
-    return {
-        paths,
-        checkpoint: read(paths.checkpoint),
-        patches: read(paths.patches),
-        meta: read(paths.meta),
-    };
-}
-/** Cold scope-stream reconstruction from canonical revision paths only. */
-export function loadTemporalRevision(cwd, sessionId, repositoryRoot, revision, sessionKey = sessionId) {
-    const root = assertRepositoryRoot(repositoryRoot);
-    assertReadableRevision(root, revision);
-    const scopePaths = ["global", "cwd", "session"].map((scope) => ({
-        scope, paths: temporalScopePaths(cwd, sessionId, scope, root, sessionKey),
-    }));
-    const canonicalRuntime = sessionRuntimePaths(cwd, sessionId, root, sessionKey);
-    const readFile = revisionFileReader(root, revision, [
-        ...scopePaths.flatMap(({ paths }) => [paths.checkpoint, paths.patches, paths.meta]),
-        canonicalRuntime.config, canonicalRuntime.runtime,
-    ]);
-    const files = [];
-    const scopes = {};
-    const provenance = { global: {}, cwd: {}, session: {} };
-    for (const { scope, paths } of scopePaths) {
-        const selected = revisionScopeFiles(readFile, paths);
-        files.push(selected.checkpoint, selected.patches, selected.meta);
-        provenance[scope] = parseScopeProvenance(selected.meta.content, selected.meta.path);
-        try {
-            scopes[scope] = parseScopeStream(selected.checkpoint.content, selected.patches.content, scope, scope === "cwd" ? cwd : undefined, selected.meta.content);
-        }
-        catch (error) {
-            throw new Error(`Invalid historical State Flow ${scope} scope`, { cause: error });
-        }
-    }
-    const readRuntime = (paths) => ({
-        paths, config: readFile(paths.config), runtime: readFile(paths.runtime), meta: readFile(paths.meta),
-    });
-    const { paths: runtimePaths, config, runtime, meta } = readRuntime(canonicalRuntime);
-    files.push(config, runtime);
-    const document = parseSessionRuntime(config.content, runtime.content, cwd, sessionId, meta.content);
-    if (document === undefined)
-        return { base: { head: revision, files }, scopes, provenance };
-    if (Object.keys(provenance.session).length === 0 && document.meta.artifacts !== undefined) {
-        provenance.session = parseArtifactProvenanceRegistry(document.meta.artifacts, "State Flow session artifact provenance");
-    }
-    const runtimeOwnerPath = runtime.content === undefined ? runtimePaths.meta : runtimePaths.runtime;
-    const owner = git(root, ["log", "-1", "--format=%H", revision, "--",
-        relativeOwnedPath(runtimePaths.config, root), relativeOwnedPath(runtimeOwnerPath, root),
-    ]).stdout.trim();
-    assertReadableRevision(root, owner);
-    let temporalRevision = document.meta.temporalRevision === undefined || document.meta.temporalRevision === "self"
-        ? owner : document.meta.temporalRevision;
-    if (temporalRevision !== revision) {
-        const ancestor = git(root, ["merge-base", "--is-ancestor", temporalRevision, revision], { allowFailure: true }).status === 0;
-        const parents = git(root, ["rev-list", "--parents", "-n", "1", revision]).stdout.trim().split(/\s+/);
-        // A store-wide semantic migration intentionally replaces all prior history with one root.
-        // Its complete tree owns every scope, so predecessor temporal pointers collapse to self.
-        if (!ancestor && parents.length === 1)
-            temporalRevision = owner;
-        else if (!ancestor) {
-            throw new Error("Temporal revision must be an ancestor of its runtime owner");
-        }
-        const selected = loadTemporalRevision(cwd, sessionId, root, temporalRevision, sessionKey);
-        Object.assign(scopes, selected.scopes);
-        Object.assign(provenance, selected.provenance);
-    }
-    if (scopes.global === undefined || scopes.cwd === undefined || scopes.session === undefined) {
-        throw new Error("Session runtime has incomplete temporal scope storage");
-    }
-    validateTemporalState({ lineage: document.meta.lineage, scopes: { global: scopes.global, cwd: scopes.cwd, session: scopes.session } });
-    return { base: { head: revision, files }, scopes, runtime: { document, revision: owner }, provenance };
-}
-function relativeOwnedPath(path, repositoryRoot) {
-    const output = relative(repositoryRoot, path);
-    if (output === "" || output === ".." || output.startsWith(`..${sep}`) || !isStateFlowOwnedPath(path, repositoryRoot)) {
-        throw new Error(`Git publication received a non-State Flow path: ${path}`);
-    }
-    return output.split(sep).join("/");
-}
-function commitOwnedFiles(repositoryRoot, updates, expectedHead, scopes, operation = "persist", rootCommit = false) {
-    assertOwnedFileUpdates(updates, repositoryRoot);
+function commitCurrentOwnedFiles(repositoryRoot, expectedHead) {
     const branchRef = currentBranchRef(repositoryRoot);
-    const observedHead = currentHead(repositoryRoot);
-    if (observedHead !== expectedHead) {
-        throw new Error("Durable State Flow Git base changed concurrently; reload before publishing");
-    }
-    const temporary = mkdtempSync(`${tmpdir()}${sep}state-flow-index-`);
-    const indexPath = `${temporary}${sep}index`;
-    const env = { GIT_INDEX_FILE: indexPath };
+    if (currentHead(repositoryRoot) !== expectedHead)
+        throw new Error("State Flow backup Git base changed concurrently");
+    const temporary = mkdtempSync(`${tmpdir()}${sep}state-flow-backup-index-`);
+    const env = { GIT_INDEX_FILE: `${temporary}${sep}index` };
     try {
         if (expectedHead === undefined)
             git(repositoryRoot, ["read-tree", "--empty"], { env });
         else
             git(repositoryRoot, ["read-tree", expectedHead], { env });
-        // A State Flow commit carries the complete non-ignored worktree delta, including user edits
-        // and manual deletions, while `.gitignore` stays authoritative for untracked files. The
-        // transient publication lock is ours, not repository content.
-        git(repositoryRoot, ["add", "-A", "--", ".", ":(exclude).state-flow-publication.lock"], { env });
-        const entries = [];
-        for (const update of updates) {
-            const relativePath = relativeOwnedPath(update.path, repositoryRoot);
-            if (update.content === undefined) {
-                git(repositoryRoot, ["update-index", "--force-remove", "--", relativePath], { env });
-                continue;
-            }
-            const blob = git(repositoryRoot, ["hash-object", "-w", "--stdin"], { input: update.content }).stdout.trim();
-            entries.push(`100644 ${blob}\t${relativePath}\0`);
-        }
-        // NUL framing preserves literal path characters while the blobs retain exact prepared bytes.
-        if (entries.length > 0)
-            git(repositoryRoot, ["update-index", "-z", "--index-info"], { env, input: entries.join("") });
+        const owned = (paths) => paths.split("\0").filter((path) => path.length > 0 && isStateFlowOwnedPath(resolve(repositoryRoot, path), repositoryRoot));
+        const headPaths = new Set(expectedHead === undefined ? [] : owned(git(repositoryRoot, ["ls-tree", "-r", "--name-only", "-z", expectedHead]).stdout));
+        const tracked = new Set([...headPaths, ...owned(git(repositoryRoot, ["ls-files", "--cached", "-z"]).stdout)]);
+        // No Git command, filter, staging write, or ref update runs inside this short capture lock.
+        const snapshot = withStoragePublicationLock(repositoryRoot, (root) => captureBackupFiles(root, tracked));
+        const present = snapshot.filter((file) => file.bytes !== undefined).map((file) => file.path);
+        const ignore = present.length === 0 ? { status: 1, stdout: "", stderr: "" }
+            : git(repositoryRoot, ["check-ignore", "--no-index", "--stdin", "-z"], { input: `${present.join("\0")}\0`, allowFailure: true });
+        if (ignore.status !== 0 && (ignore.status !== 1 || ignore.stderr.trim()))
+            throw new Error(`Git ignore selection failed: ${ignore.stderr || ignore.status}`);
+        const ignored = new Set(ignore.stdout.split("\0"));
+        const candidates = snapshot.filter((file) => file.bytes === undefined
+            ? headPaths.has(file.path) : tracked.has(file.path) || !ignored.has(file.path));
+        if (candidates.length === 0)
+            return undefined;
+        const pathspec = `${candidates.map((file) => file.path).join("\0")}\0`;
+        const worktree = join(temporary, "worktree");
+        prepareBackupWorktree(repositoryRoot, worktree, candidates);
+        git(repositoryRoot, ["--literal-pathspecs", `--work-tree=${worktree}`, "add", "-A", "-f", "--pathspec-from-file=-", "--pathspec-file-nul"], { env, input: pathspec });
         const tree = git(repositoryRoot, ["write-tree"], { env }).stdout.trim();
-        if (expectedHead !== undefined && !rootCommit) {
-            const previousTree = git(repositoryRoot, ["rev-parse", `${expectedHead}^{tree}`]).stdout.trim();
-            if (tree === previousTree)
-                return undefined;
-        }
-        const message = `state-flow: ${operation} ${scopes.join("+") || "runtime"} transition\n\n${STATE_FLOW_COMMIT_TRAILER}\n`;
-        const commitArgs = ["commit-tree", tree];
-        if (expectedHead !== undefined && !rootCommit)
-            commitArgs.push("-p", expectedHead);
-        const commit = git(repositoryRoot, commitArgs, { input: message }).stdout.trim();
-        const zero = "0".repeat(40);
-        assertOwnedFileUpdates(updates, repositoryRoot);
-        git(repositoryRoot, ["update-ref", branchRef, commit, expectedHead ?? zero]);
+        if (expectedHead !== undefined && tree === git(repositoryRoot, ["rev-parse", `${expectedHead}^{tree}`]).stdout.trim())
+            return undefined;
+        const args = ["commit-tree", tree];
+        if (expectedHead !== undefined)
+            args.push("-p", expectedHead);
+        const commit = git(repositoryRoot, args, { input: `state-flow: settled canonical backup\n\n${STATE_FLOW_COMMIT_TRAILER}\n` }).stdout.trim();
+        const previous = expectedHead ?? "0".repeat(commit.length);
+        git(repositoryRoot, ["update-ref", branchRef, commit, previous]);
         try {
-            // Align the caller-visible index with the committed tree so advancing HEAD through the
-            // isolated index leaves no artificial staged/unstaged status entries behind.
-            git(repositoryRoot, ["read-tree", commit]);
+            // Align only owned entries; the caller's unrelated stages and index-only data remain intact.
+            git(repositoryRoot, ["--literal-pathspecs", "reset", "--quiet", "--no-refresh", commit, "--pathspec-from-file=-", "--pathspec-file-nul"], { input: pathspec });
         }
         catch (error) {
-            git(repositoryRoot, ["update-ref", branchRef, expectedHead ?? zero, commit]);
+            git(repositoryRoot, ["update-ref", branchRef, previous, commit]);
             throw error;
         }
         return commit;
@@ -296,267 +177,7 @@ function commitOwnedFiles(repositoryRoot, updates, expectedHead, scopes, operati
         rmSync(temporary, { recursive: true, force: true });
     }
 }
-/** Explicit migration entrypoint; initialization adopts it only with the temporal writer cutover. */
-export function migrateLegacyStorageToGit(cwd, sessionId, repositoryRoot, sessionKey = sessionId) {
-    return withPublicationLock(repositoryRoot, (root) => migrateLegacyStorageUnderLock(cwd, sessionId, root, sessionKey));
-}
-function migrateLegacyStorageUnderLock(cwd, sessionId, root, sessionKey = sessionId) {
-    const plan = planLegacyStorageMigration(cwd, sessionId, root, undefined, sessionKey);
-    if (plan.updates.length === 0)
-        return { scopes: [] };
-    const current = captureOwnedFileBases(plan.bases.map(({ path }) => path), root);
-    if (current.some((base, index) => base.identity !== plan.bases[index].identity)) {
-        throw new Error("State Flow storage changed concurrently while planning migration");
-    }
-    return { scopes: plan.scopes, ...publishOwnedCohort(root, plan.updates, plan.bases, currentHead(root), plan.scopes, "migrate", false, true) };
-}
-function publishOwnedCohort(root, updates, bases, head, scopes, operation, push = true, rootCommit = false) {
-    let published = false;
-    try {
-        writeOwnedFileUpdates(updates, bases, root);
-        published = true;
-        const commit = commitOwnedFiles(root, updates, head, scopes, operation, rootCommit);
-        return commit === undefined ? {} : push ? { commit, push: pushGitCommit(root, commit) } : { commit };
-    }
-    catch (error) {
-        if (published) {
-            try {
-                const touched = new Set(updates.map(({ path }) => path));
-                restoreDurableFileBases(bases.filter(({ path }) => touched.has(path)), root, updates);
-            }
-            catch (rollbackError) {
-                throw new AggregateError([error, rollbackError], "State Flow publication and rollback failed");
-            }
-        }
-        throw error;
-    }
-}
-/** Explicit current-file adoption, not reconstruction or invention of pre-Git history. */
-export function adoptFileStateToGit(cwd, sessionId, repositoryRoot, revision, snapshot, sessionKey = sessionId, push = true) {
-    const selected = loadTemporalFileRevision(cwd, sessionId, repositoryRoot, revision, sessionKey);
-    if (snapshot.meta.step !== selected.runtime.meta.step)
-        throw new Error("Git adoption must preserve the semantic step");
-    const runtime = createSessionRuntime(snapshot, cwd, sessionId, selected.view.lineage, "unconfirmed", selected.provenance.session);
-    runtime.meta.temporalRevision = "self";
-    const sources = serializeSessionRuntime(runtime, cwd, sessionId);
-    initializeGitRepository(repositoryRoot);
-    return withPublicationLock(repositoryRoot, (root) => {
-        const current = captureTemporalBaseUnderLock(cwd, sessionId, root, sessionKey);
-        assertTemporalFileBase(selected.base, current);
-        const paths = sessionRuntimePaths(cwd, sessionId, root, sessionKey);
-        const provenancePaths = new Set([
-            temporalScopePaths(cwd, sessionId, "global", root, sessionKey).meta,
-            temporalScopePaths(cwd, sessionId, "cwd", root, sessionKey).meta,
-            temporalScopePaths(cwd, sessionId, "session", root, sessionKey).meta,
-        ]);
-        // Preserve exact valid scope bytes; only runtime provenance changes representation.
-        const updates = current.files.filter(({ path, identity }) => path.endsWith("checkpoint.json")
-            || path.endsWith("patches.jsonl")
-            || (provenancePaths.has(path) && identity !== "missing"))
-            .map(({ path, content }) => ({ path, content: content }));
-        updates.push({ path: paths.config, content: sources.config }, { path: paths.runtime, content: sources.runtime });
-        const existing = current.head && updates.every(({ path, content }) => revisionFile(root, current.head, path).content === content)
-            ? loadTemporalRevision(cwd, sessionId, root, current.head, sessionKey) : undefined;
-        if (existing && (!existing.runtime || !sameJson({ lineage: existing.runtime.document.meta.lineage, scopes: existing.scopes }, selected.view))) {
-            throw new Error("Existing Git runtime does not anchor the selected file cohort");
-        }
-        const publication = publishOwnedCohort(root, updates, current.files, current.head, [], "persist", push);
-        const target = publication.commit ?? existing.runtime.revision;
-        const remote = push ? publication.push ?? pushGitCommit(root, target) : undefined;
-        return { ...publication, revision: target, ...(remote === undefined ? {} : { push: remote }), view: selected.view, provenance: selected.provenance,
-            base: { head: publication.commit ?? current.head, files: temporalFileReceipts(current, updates) } };
-    });
-}
-/** Working-tree equality alone cannot prove that a new commit contains the selected cohort. */
-function includeUncommittedCohort(cwd, sessionId, root, current, updates, changedScopes, scopes, runtime, sessionKey = sessionId) {
-    const targets = new Map(updates.map((update) => [update.path, update]));
-    const desired = (paths) => paths.map((path) => targets.get(path) ?? { path, content: current.files.find((file) => file.path === path).content });
-    const pairs = ["global", "cwd", "session"].map((scope) => {
-        const paths = temporalScopePaths(cwd, sessionId, scope, root, sessionKey);
-        return { scope, pair: desired([paths.checkpoint, paths.patches]) };
-    });
-    const runtimePaths = runtime ? sessionRuntimePaths(cwd, sessionId, root, sessionKey) : undefined;
-    const runtimePair = runtimePaths ? desired([runtimePaths.config, runtimePaths.runtime]) : [];
-    const readFile = current.head === undefined ? undefined : revisionFileReader(root, current.head, [...pairs.flatMap(({ pair }) => pair), ...runtimePair].map(({ path }) => path));
-    const absentFromHead = (files) => files.some(({ path, content }) => readFile === undefined || readFile(path).content !== content);
-    for (const { scope, pair } of pairs) {
-        if (!absentFromHead(pair))
-            continue;
-        if (!scopes.includes(scope))
-            throw new Error(`Temporal scope update omitted an uncommitted stream: ${scope}`);
-        for (const update of pair)
-            targets.set(update.path, update);
-        if (!changedScopes.includes(scope))
-            changedScopes.push(scope);
-    }
-    if (absentFromHead(runtimePair))
-        for (const update of runtimePair)
-            targets.set(update.path, update);
-    updates.splice(0, updates.length, ...targets.values());
-}
-/** Persist selected streams from one validated view, never derive checkpoints from current state. */
-export function publishTemporalStateToGit(cwd, sessionId, view, scopes, base, repositoryRoot, runtime, sessionKey = sessionId, push = true, provenance) {
-    return withPublicationLock(repositoryRoot, (root) => {
-        const current = captureTemporalBaseUnderLock(cwd, sessionId, root, sessionKey);
-        assertTemporalFileBase(base, current);
-        if (runtime?.meta.publication === "files")
-            throw new Error("Git publication requires explicit Git provenance");
-        const runtimePaths = sessionRuntimePaths(cwd, sessionId, root, sessionKey);
-        const previousRuntime = parseSessionRuntime(current.files.find(({ path }) => path === runtimePaths.config)?.content, current.files.find(({ path }) => path === runtimePaths.runtime)?.content, cwd, sessionId, current.files.find(({ path }) => path === runtimePaths.meta)?.content);
-        if (previousRuntime?.meta.publication === "files")
-            throw new Error("File-only storage requires explicit full-cohort Git adoption");
-        const runtimeOnly = runtime?.meta.temporalRevision !== undefined && runtime.meta.temporalRevision !== "self";
-        if (runtimeOnly) {
-            if (scopes.length !== 0)
-                throw new Error("Runtime-only publication cannot write semantic scopes");
-            const selected = loadTemporalRevision(cwd, sessionId, root, runtime.meta.temporalRevision, sessionKey);
-            if (!sameJson(selected.scopes, view.scopes))
-                throw new Error("Runtime temporal reference does not match selected streams");
-        }
-        const { updates, changedScopes } = planTemporalPublication(cwd, sessionId, view, scopes, current, root, runtime, runtimeOnly, sessionKey, provenance);
-        if (!runtimeOnly)
-            includeUncommittedCohort(cwd, sessionId, root, current, updates, changedScopes, scopes, runtime !== undefined, sessionKey);
-        if (updates.length === 0)
-            return { base: current };
-        const publication = publishOwnedCohort(root, updates, current.files, current.head, changedScopes, "persist", push);
-        const nextFiles = temporalFileReceipts(current, updates);
-        return { ...publication, base: { head: publication.commit ?? current.head, files: nextFiles } };
-    });
-}
-export function resolveGitPushDestination(repositoryRoot) {
-    const root = assertRepositoryRoot(repositoryRoot);
-    const common = git(root, ["rev-parse", "--git-common-dir"]).stdout.trim();
-    const gitCommonDir = resolve(root, common);
-    const destination = pushDestination(root);
-    return destination === undefined ? undefined : { gitCommonDir, ...destination };
-}
-function pushDestination(repositoryRoot) {
-    const branchRef = currentBranchRef(repositoryRoot);
-    const branch = branchRef.slice("refs/heads/".length);
-    const configuredRemote = git(repositoryRoot, ["config", "--get", `branch.${branch}.remote`], { allowFailure: true });
-    if (configuredRemote.status > 1)
-        throw new Error(configuredRemote.stderr || "Cannot inspect Git remote configuration");
-    let remote = configuredRemote.status === 0 ? configuredRemote.stdout.trim() : "";
-    if (remote.length === 0) {
-        const remotes = git(repositoryRoot, ["remote"]).stdout.trim().split(/\s+/).filter(Boolean);
-        if (remotes.length === 0)
-            return undefined;
-        if (remotes.includes("origin"))
-            remote = "origin";
-        else if (remotes.length === 1)
-            remote = remotes[0];
-        else
-            throw new Error("State Flow durable publication cannot select a Git remote");
-    }
-    if (remote === ".")
-        throw new Error("State Flow durable publication requires a non-local Git remote");
-    const configuredMerge = git(repositoryRoot, ["config", "--get", `branch.${branch}.merge`], { allowFailure: true });
-    const ref = configuredMerge.status === 0 && configuredMerge.stdout.trim().length > 0
-        ? configuredMerge.stdout.trim()
-        : branchRef;
-    return { remote, ref };
-}
-/** Read-only publication policy; configuration errors are not local-only success. */
-export function isLocalGitRepository(repositoryRoot) {
-    return pushDestination(assertRepositoryRoot(repositoryRoot)) === undefined;
-}
-/** Push an already-created commit exactly; failures are publication state, not transition rejection. */
-export function isGitCommitAncestor(repositoryRoot, ancestor, descendant) {
-    const root = assertRepositoryRoot(repositoryRoot);
-    assertReadableRevision(root, ancestor);
-    assertReadableRevision(root, descendant);
-    const result = git(root, ["merge-base", "--is-ancestor", ancestor, descendant], { allowFailure: true });
-    if (result.status === 0)
-        return true;
-    if (result.status === 1)
-        return false;
-    throw new Error(`Cannot inspect Git commit ancestry: ${result.stderr || `exit ${result.status}`}`);
-}
-/** Own one non-interactive exact-target push; cancellation is not confirmation of child exit. */
-export function pushGitTarget(repositoryRoot, destination, commit, signal) {
-    if (typeof commit !== "string" || !/^[0-9a-f]{40,64}$/.test(commit))
-        return Promise.reject(new Error("Git push target must be an exact commit"));
-    if (signal?.aborted)
-        return Promise.reject(new Error("Git push aborted"));
-    return new Promise((resolve, reject) => {
-        const child = spawn("git", ["-C", repositoryRoot, "push", "--", destination.remote, `${commit}:${destination.ref}`], {
-            detached: process.platform !== "win32", // Own the POSIX group, not a detached daemon; retain the child handle.
-            stdio: ["ignore", "ignore", "pipe"],
-            windowsHide: true,
-            env: { ...process.env, GIT_TERMINAL_PROMPT: "0", GCM_INTERACTIVE: "never" },
-        });
-        let stderr = "";
-        let failure;
-        let settled = false;
-        function terminate(error) {
-            failure ??= error;
-            if (child.exitCode !== null || child.signalCode !== null) {
-                child.stderr?.destroy(); // Do not wait indefinitely for an outliving helper's inherited pipe.
-                return;
-            }
-            if (!child.pid)
-                return;
-            try {
-                if (process.platform === "win32")
-                    child.kill("SIGKILL");
-                else
-                    process.kill(-child.pid, "SIGKILL");
-            }
-            catch {
-                // No exit proof: keep the promise and caller's lease outstanding, even if signalling fails.
-            }
-        }
-        const abort = () => terminate(new Error("Git push aborted"));
-        const timeout = setTimeout(() => terminate(new Error(`Git push timed out after ${GIT_TIMEOUT_MS}ms`)), GIT_TIMEOUT_MS);
-        function finish(error) {
-            if (settled)
-                return;
-            settled = true;
-            clearTimeout(timeout);
-            signal?.removeEventListener("abort", abort);
-            if (error)
-                reject(error);
-            else
-                resolve();
-        }
-        child.stderr?.on("data", (chunk) => { stderr = (stderr + chunk.toString("utf8")).slice(-1000); });
-        child.on("error", (error) => {
-            failure ??= error;
-            if (!child.pid)
-                finish(error); // Spawn failure owns no live process; kill errors do not prove exit.
-        });
-        child.once("exit", () => { if (failure)
-            child.stderr?.destroy(); });
-        child.once("close", (code, endedBy) => finish(failure ?? (code === 0 ? undefined
-            : new Error(`Git push failed (${endedBy ?? code}): ${stderr.trim() || "no diagnostic output"}`))));
-        signal?.addEventListener("abort", abort, { once: true });
-        if (signal?.aborted)
-            abort();
-    });
-}
-export function pushGitCommit(repositoryRoot, commit) {
-    try {
-        const root = assertRepositoryRoot(repositoryRoot);
-        assertReadableRevision(root, commit);
-        const destination = pushDestination(root);
-        if (destination === undefined)
-            return { status: "local", commit };
-        const remote = git(root, ["ls-remote", destination.remote, destination.ref], { allowFailure: true });
-        const remoteHead = remote.stdout.trim().split(/\s+/)[0];
-        if (remote.status === 0 && remoteHead && /^[0-9a-f]{40,64}$/.test(remoteHead)
-            && git(root, ["merge-base", "--is-ancestor", commit, remoteHead], { allowFailure: true }).status === 0) {
-            return { status: "pushed", commit };
-        }
-        const result = git(root, ["push", destination.remote, `${commit}:${destination.ref}`], { allowFailure: true });
-        if (result.status === 0)
-            return { status: "pushed", commit };
-        return {
-            status: "pending",
-            commit,
-            error: (result.stderr.trim() || result.stdout.trim() || `exit status ${result.status}`),
-        };
-    }
-    catch (error) {
-        return { status: "pending", commit, error: error instanceof Error ? error.message : String(error) };
-    }
+/** Commit only current State Flow-owned files; never changes canonical acceptance. */
+export function backupCurrentStateFlowFiles(repositoryRoot) {
+    return withBackupLock(repositoryRoot, (root) => commitCurrentOwnedFiles(root, currentHead(root)));
 }