spawnfile 0.1.17 → 0.1.19

package/dist/compiler/training/rewind/git.js

@@ -0,0 +1,159 @@
+import { mkdir, rm } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { deployedResource } from "./deployedResource.js";
+import { historyKey } from "./history.js";
+import { assertLocalGitRepository } from "./gitHistory.js";
+import { assertCommitNotFuture, commitAt, commitInstant, resolveRewindCommit, rewindGit } from "./gitProcess.js";
+import { exportGitTree, extractOverrideBundle } from "./gitTree.js";
+import { resolveRecordedCommit } from "./recordedCommit.js";
+import { materializeRecordedBundle } from "./recordedBundle.js";
+import { recordActivationErrors } from "./recordInput.js";
+export { commitAt, commitInstant, resolveRewindCommit, rewindGit, rewindGitEnvironment, rewindGitSync, selectCommitAt } from "./gitProcess.js";
+export { exportGitTree } from "./gitTree.js";
+export { assertLocalGitRepository } from "./gitHistory.js";
+const FULL_OBJECT = /^(?:[a-fA-F0-9]{40}|[a-fA-F0-9]{64})$/u;
+export const localRepositoryPath = (location, base) => {
+    if (location.startsWith("file://")) {
+        const url = new URL(location);
+        if (url.hostname && url.hostname !== "localhost")
+            throw new Error("Rewind only reads local repositories; remote file hosts are forbidden");
+        return fileURLToPath(url);
+    }
+    if (/^[A-Za-z][A-Za-z0-9+.-]*:/u.test(location) || /^[^/]+@[^:]+:/u.test(location))
+        throw new Error("Rewind only reads local repositories; network access is forbidden");
+    return path.resolve(base, location);
+};
+/** Import only the transitive object set of the selected commit; no source refs or config survive. */
+export const materializeCleanRepository = async (repository, commit, destination) => {
+    const format = (await rewindGit(repository, ["rev-parse", "--show-object-format"])).toString().trim();
+    const pack = await rewindGit(repository, ["pack-objects", "--revs", "--stdout"], Buffer.from(`${commit}\n`));
+    await mkdir(destination, { recursive: true });
+    await rewindGit(destination, ["init", "--quiet", "--template=", "--initial-branch=moment", `--object-format=${format}`]);
+    await rewindGit(destination, ["config", "core.logAllRefUpdates", "false"]);
+    await rewindGit(destination, ["index-pack", "--stdin"], pack);
+    await rewindGit(destination, ["update-ref", "refs/heads/moment", commit]);
+    await rewindGit(destination, ["read-tree", commit]);
+    await rewindGit(destination, ["checkout-index", "--all", "--force"]);
+    // read-tree may reuse cached stat data from an existing index; rebuild it from scratch.
+    await rm(path.join(destination, ".git/index"));
+    await rewindGit(destination, ["read-tree", commit]);
+    for (const name of ["FETCH_HEAD", "ORIG_HEAD", "logs", "packed-refs"])
+        await rm(path.join(destination, ".git", name), { recursive: true, force: true });
+};
+const selectorOf = (resource) => resource.kind === "git"
+    ? resource.ref || (resource.branch ? `refs/heads/${resource.branch}` : resource.tag ? `refs/tags/${resource.tag}` : "HEAD")
+    : resource.build?.files?.ref ?? "HEAD";
+const localRoot = (resource) => resource.kind === "git" ? resource.url
+    : resource.build?.files?.root ?? resource.build?.dependencies?.directory ?? resource.build?.generated?.cwd ?? resource.build?.generated?.inputs[0]?.root;
+/** Preserve the authored root's prefix when its checkout exists; otherwise use a plain manifest-relative root. */
+const bundlePrefix = async (root, base) => {
+    const absolute = path.resolve(base, root);
+    try {
+        return (await rewindGit(absolute, ["rev-parse", "--show-prefix"])).toString().trim().replace(/\/$/u, "");
+    }
+    catch {
+        if (path.isAbsolute(root) || root.split(/[\\/]/u).includes(".."))
+            throw new Error(`Cannot determine historical repository prefix for bundle root ${root}; keep its local checkout or use a repository-relative root`);
+        return root.replace(/^\.\//u, "").replace(/\/$/u, "").replace(/^\.$/u, "");
+    }
+};
+const materializeBundle = async (resource, context, repository, commit) => {
+    const build = resource.build;
+    const trees = [];
+    if (!build)
+        trees.push({ root: "" });
+    else if (build.files)
+        trees.push({ root: await bundlePrefix(build.files.root, context.input.declarationBase), exclude: build.files.exclude });
+    else if (build.dependencies)
+        trees.push({ root: await bundlePrefix(build.dependencies.directory, context.input.declarationBase) });
+    else {
+        const origins = await Promise.all(build.generated.inputs.map(async (input) => {
+            try {
+                return (await rewindGit(path.resolve(context.input.declarationBase, input.root), ["rev-parse", "--show-toplevel"])).toString().trim();
+            }
+            catch {
+                return null;
+            } // Missing relative roots are mapped against the retained repository below.
+        }));
+        if (new Set(origins.filter((origin) => origin !== null)).size > 1) {
+            throw new Error("Generated bundle inputs span multiple git repositories; one recorded repository/commit cannot rewind them correctly");
+        }
+        // Keep repository-relative paths: trial preparation can restore the declared cwd/input relationship.
+        for (const input of build.generated.inputs) {
+            if (input.ref !== undefined)
+                throw new Error("Generated bundle inputs cannot pin a ref: the deferred command reads the work tree");
+            const root = await bundlePrefix(input.root, context.input.declarationBase);
+            trees.push({ root, prefix: root, exclude: input.exclude });
+        }
+    }
+    for (const tree of trees)
+        await exportGitTree(repository, commit, context.destination, { ...tree, mergeIdentical: true });
+    return { trees, deferred: Boolean(build?.dependencies || build?.generated) };
+};
+export const materializeGit = async (context) => {
+    const { input, history } = context;
+    if (input.section !== "resources" || input.declaration.kind === "volume")
+        throw new Error("Git rewind requires a git or bundle resource");
+    const resource = input.declaration, selector = selectorOf(resource), pinned = FULL_OBJECT.test(selector);
+    const matchingRecord = input.overridden ? undefined : context.record?.resources.find((entry) => entry.id === input.id);
+    const activationErrors = matchingRecord ? recordActivationErrors(context.record) : [];
+    const candidateCommits = input.overridden ? [] : context.candidateRecords?.flatMap((candidate) => candidate.resources.flatMap((entry) => entry.id === input.id && entry.kind === "git" ? [entry.commit] : [])) ?? [];
+    if (matchingRecord && matchingRecord.kind !== resource.kind)
+        throw new Error(`Moment resource ${input.id} kind disagrees with its declaration`);
+    const deployed = !input.overridden && !matchingRecord && !(resource.kind === "git" && pinned)
+        ? await deployedResource(context) : null;
+    if (deployed && deployed.pin.kind !== resource.kind)
+        throw new Error(`Deployment resource ${input.id} kind disagrees with its declaration`);
+    const effectivePin = matchingRecord ?? deployed?.pin;
+    const bundlePin = effectivePin?.kind === "bundle" ? effectivePin : undefined;
+    if (bundlePin && await materializeRecordedBundle(history, bundlePin.sha256, context.destination)) {
+        return { fidelity: activationErrors.length || deployed && !deployed.exact ? "approximate" : "exact", basis: deployed ? "deploy-log" : "record",
+            source: { sha256: bundlePin.sha256 }, notes: [...(deployed?.notes ?? []), ...activationErrors], instant: context.at };
+    }
+    if (deployed && bundlePin)
+        throw new Error(`Deployment bundle ${bundlePin.sha256} could not be reproduced from retained archive bytes`);
+    const bundleNote = bundlePin ? `Recorded bundle ${bundlePin.sha256} could not be reproduced from retained archive bytes.` : undefined;
+    const gitPin = effectivePin?.kind === "git" ? effectivePin : undefined;
+    const record = pinned ? undefined : gitPin;
+    if (input.overridden && resource.kind === "bundle" && resource.source) {
+        await extractOverrideBundle(localRepositoryPath(resource.source, input.declarationBase), context.destination, resource.sha256);
+        return { fidelity: "overridden", basis: "override", source: {}, notes: [], instant: context.at };
+    }
+    if (resource.kind === "bundle" && resource.source)
+        throw new Error(`${bundleNote ?? "Prebuilt bundle has no matching recorded archive"} and cannot be rewound; provide an override`);
+    let repository = input.overridden ? null : await history?.repository(`git/${historyKey(input)}`);
+    const fromHistory = Boolean(repository);
+    if ((gitPin || candidateCommits.length) && !repository)
+        throw new Error(`Missing git history for recorded resource ${input.id}`);
+    if (!repository && (pinned || input.overridden)) {
+        const declared = localRoot(resource);
+        if (declared)
+            repository = localRepositoryPath(declared, input.declarationBase);
+    }
+    if (!repository)
+        throw new Error(`Missing git history for ${input.id}; unpinned resources require --history`);
+    await assertLocalGitRepository(repository, !input.overridden && history && repository.startsWith(`${history.root}${path.sep}`) ? history : undefined);
+    for (const commit of candidateCommits)
+        await resolveRecordedCommit(repository, commit);
+    const recordedCommit = gitPin ? await resolveRecordedCommit(repository, gitPin.commit) : null;
+    const selected = pinned || record || input.overridden
+        ? await (record ? Promise.resolve(recordedCommit) : resolveRewindCommit(repository, selector))
+            .then(async (commit) => ({ commit, instant: await commitInstant(repository, commit) }))
+        : await commitAt(repository, selector, context.at);
+    if (!selected)
+        throw new Error(`No first-parent commit for ${selector} exists at or before ${context.at}`);
+    await assertCommitNotFuture(repository, selected.commit, context.at);
+    const bundle = resource.kind === "bundle" ? await materializeBundle(resource, context, repository, selected.commit) : undefined;
+    if (resource.kind === "git")
+        await materializeCleanRepository(repository, selected.commit, context.destination);
+    return {
+        fidelity: input.overridden ? "overridden" : resource.kind === "bundle" ? "approximate"
+            : record && activationErrors.length ? "approximate" : deployed ? deployed.exact ? "exact" : "approximate" : pinned || record ? "exact" : "approximate",
+        basis: input.overridden ? "override" : pinned ? "pinned" : deployed ? "deploy-log" : record ? "record" : "selector-at",
+        source: { commit: selected.commit, ...(!fromHistory ? { repository } : {}), ...(bundle ? { trees: bundle.trees } : {}) }, instant: selected.instant,
+        notes: [...(deployed?.notes ?? []), ...(record || bundle ? activationErrors : []), ...(pinned || record || input.overridden ? [] : ["Commit dates do not establish when a commit reached the selected ref."]),
+            ...(!input.overridden && resource.kind === "bundle" ? [bundleNote ?? "Source reconstruction has no matching recorded bundle digest."] : [])],
+        ...(bundle?.deferred ? { build: "deferred" } : {})
+    };
+};

package/dist/compiler/training/rewind/gitArchive.d.ts

@@ -0,0 +1,2 @@
+/** Retain raw blob bytes: archive attributes may disclose refs added after the moment. */
+export declare const exportFeedGitTree: (repository: string, commit: string, destination: string, paths?: string[]) => Promise<void>;

package/dist/compiler/training/rewind/gitArchive.js

@@ -0,0 +1,7 @@
+import { exportGitTree, safeCommittedPath } from "./gitTree.js";
+/** Retain raw blob bytes: archive attributes may disclose refs added after the moment. */
+export const exportFeedGitTree = async (repository, commit, destination, paths) => {
+    for (const selected of paths ?? [])
+        safeCommittedPath(selected);
+    await exportGitTree(repository, commit, destination, { paths });
+};

package/dist/compiler/training/rewind/gitHistory.d.ts

@@ -0,0 +1,3 @@
+import type { History } from "./history.js";
+/** Git's textual indirections are not covered by ordinary realpath containment. */
+export declare const assertLocalGitRepository: (repository: string, history?: History) => Promise<void>;

package/dist/compiler/training/rewind/gitHistory.js

@@ -0,0 +1,55 @@
+import { lstat, readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+import { rewindGit } from "./gitProcess.js";
+/** Git's textual indirections are not covered by ordinary realpath containment. */
+export const assertLocalGitRepository = async (repository, history) => {
+    const exists = (file) => history ? history.path(path.relative(history.root, file)) : lstat(file).then(() => file, (error) => {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    });
+    const text = (file) => history ? history.text(path.relative(history.root, file)) : readFile(file, "utf8").catch((error) => {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    });
+    const dotGit = path.join(repository, ".git");
+    if (history && await exists(dotGit) && !(await lstat(dotGit)).isDirectory())
+        throw new Error("History repository .git indirection files are not supported; retain a standalone repository");
+    // `git -C` would discover an ancestor repository if this history directory is not itself one.
+    if (history && !await exists(dotGit) && (!await exists(path.join(repository, "HEAD")) || !await exists(path.join(repository, "objects")))) {
+        throw new Error("History entry is not a standalone git repository");
+    }
+    // Check config includes before asking git anything: even rev-parse reads included config files.
+    if (history) {
+        const directory = await exists(dotGit) ? dotGit : repository;
+        // `commondir` is another textual redirect git follows during discovery, before any command runs.
+        for (const name of ["commondir", "objects/info/alternates", "objects/info/http-alternates", "shallow", "info/grafts"]) {
+            if (await text(path.join(directory, name)))
+                throw new Error(`Rewind requires complete standalone git history; ${name} is unsupported`);
+        }
+        const configFile = path.join(directory, "config");
+        const configText = await text(configFile);
+        if (configText && /^\s*\[\s*include(?:if)?\b/imu.test(configText))
+            throw new Error("Rewind refuses git configuration indirection include");
+    }
+    // Resolve only after refusing textual worktree links that could leave the history root.
+    const gitDirectory = (await rewindGit(repository, ["rev-parse", "--absolute-git-dir"])).toString().trim();
+    if (history)
+        await history.path(path.relative(history.root, gitDirectory));
+    for (const name of ["commondir", "objects/info/alternates", "objects/info/http-alternates", "shallow", "info/grafts"]) {
+        if (await text(path.join(gitDirectory, name)))
+            throw new Error(`Rewind requires complete standalone git history; ${name} is unsupported`);
+    }
+    const config = (await rewindGit(repository, ["config", "--local", "--no-includes", "--list", "--null"]))
+        .toString().split("\0").filter(Boolean);
+    for (const entry of config) {
+        const key = entry.split("\n")[0].toLowerCase();
+        if (key === "include.path" || /^includeif\..*\.path$/u.test(key) || key === "extensions.partialclone" || /^remote\..*\.promisor$/u.test(key)) {
+            throw new Error(`Rewind refuses git configuration indirection ${key}`);
+        }
+    }
+    const packs = path.join(gitDirectory, "objects/pack");
+    if (await exists(packs) && (await readdir(packs)).some((name) => name.endsWith(".promisor")))
+        throw new Error("Rewind refuses incomplete promisor git history");
+};

package/dist/compiler/training/rewind/gitProcess.d.ts

@@ -0,0 +1,19 @@
+/** Do not inherit GIT_DIR, injected -c options, credentials or user/system configuration. */
+export declare const rewindGitEnvironment: () => NodeJS.ProcessEnv;
+/** Bounded argv-only git invocation. Local transport is the only enabled protocol. */
+export declare const rewindGit: (repo: string, args: readonly string[], input?: Buffer) => Promise<Buffer>;
+/** Adapter for the existing synchronous feed revision function; it never fetches. */
+export declare const rewindGitSync: (repo: string, args: readonly string[]) => Buffer;
+export interface SelectedCommit {
+    commit: string;
+    instant: string;
+    authorInstant?: string;
+}
+export declare const commitInstant: (repo: string, commit: string) => Promise<string>;
+/** Validate the selected source before any copy/export, regardless of the materialized layout. */
+export declare const assertCommitNotFuture: (repo: string, commit: string, at: string) => Promise<void>;
+export declare const resolveRewindCommit: (repo: string, selector: string) => Promise<string>;
+/** Dates approximate ref history; they cannot establish when a commit reached a moving ref. */
+export declare const commitAt: (repo: string, selector: string, at: string) => Promise<SelectedCommit | null>;
+/** Stable ties preserve the first-parent order returned by git. */
+export declare const selectCommitAt: (commits: readonly SelectedCommit[], at: string) => SelectedCommit | null;

package/dist/compiler/training/rewind/gitProcess.js

@@ -0,0 +1,81 @@
+import { execFile, execFileSync } from "node:child_process";
+import { compareInstants } from "./instant.js";
+const LIMIT = 268_435_456;
+/** Do not inherit GIT_DIR, injected -c options, credentials or user/system configuration. */
+export const rewindGitEnvironment = () => ({
+    PATH: process.env.PATH,
+    ...(process.env.SystemRoot ? { SystemRoot: process.env.SystemRoot } : {}),
+    LC_ALL: "C", GIT_CONFIG_NOSYSTEM: "1", GIT_CONFIG_SYSTEM: "/dev/null", GIT_CONFIG_GLOBAL: "/dev/null",
+    GIT_NO_REPLACE_OBJECTS: "1", GIT_OPTIONAL_LOCKS: "0", GIT_TERMINAL_PROMPT: "0", GIT_NO_LAZY_FETCH: "1",
+    GIT_ATTR_NOSYSTEM: "1", GIT_CONFIG_COUNT: "0"
+});
+const argumentsFor = (repo, args) => [
+    "-c", "core.hooksPath=/dev/null", "-c", "core.fsmonitor=false", "-c", "core.autocrlf=false",
+    "-c", "core.logAllRefUpdates=false", "-c", "core.attributesFile=/dev/null", "-c", "protocol.allow=never", "-c", "protocol.file.allow=always",
+    "-c", "maintenance.auto=false", "-c", "gc.auto=0", "-c", "safe.directory=*", "-C", repo, ...args
+];
+/** Bounded argv-only git invocation. Local transport is the only enabled protocol. */
+export const rewindGit = (repo, args, input) => new Promise((resolve, reject) => {
+    const child = execFile("git", argumentsFor(repo, args), {
+        encoding: "buffer", env: rewindGitEnvironment(), maxBuffer: LIMIT, timeout: 60_000
+    }, (error, stdout, stderr) => {
+        if (error)
+            reject(new Error(`Rewind git ${args[0]} failed: ${stderr.toString("utf8").trim() || error.message}`));
+        else
+            resolve(stdout);
+    });
+    child.stdin?.on("error", () => undefined);
+    child.stdin?.end(input);
+});
+/** Adapter for the existing synchronous feed revision function; it never fetches. */
+export const rewindGitSync = (repo, args) => execFileSync("git", argumentsFor(repo, args), {
+    env: rewindGitEnvironment(), maxBuffer: LIMIT, stdio: ["ignore", "pipe", "pipe"], timeout: 60_000
+});
+/** Git's pretty formatter drops negative epochs. Read the signed raw dates instead. */
+const commitDates = async (repo, commit) => {
+    const headers = (await rewindGit(repo, ["cat-file", "commit", commit])).toString().split("\n\n", 1)[0];
+    const date = (role) => {
+        const match = new RegExp(`^${role} .* (-?\\d+) [+-]\\d{4}$`, "mu").exec(headers);
+        const seconds = match ? Number(match[1]) : NaN;
+        if (!Number.isSafeInteger(seconds) || !Number.isFinite(new Date(seconds * 1000).getTime())) {
+            throw new Error(`Commit ${commit} has an invalid ${role} date`);
+        }
+        return new Date(seconds * 1000).toISOString();
+    };
+    return { author: date("author"), committer: date("committer") };
+};
+export const commitInstant = async (repo, commit) => (await commitDates(repo, commit)).committer;
+/** Validate the selected source before any copy/export, regardless of the materialized layout. */
+export const assertCommitNotFuture = async (repo, commit, at) => {
+    const dates = await commitDates(repo, commit);
+    if (Object.values(dates).some((instant) => compareInstants(instant, at) > 0)) {
+        throw new Error(`Selected commit ${commit} has an author or committer date after ${at}`);
+    }
+};
+export const resolveRewindCommit = async (repo, selector) => {
+    if (!selector || selector.startsWith("-") || /[\0\r\n]/u.test(selector))
+        throw new Error("Invalid git selector");
+    const ref = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/iu.test(selector) ? selector.toLowerCase() : selector;
+    return (await rewindGit(repo, ["rev-parse", "--verify", "--end-of-options", `${ref}^{commit}`])).toString().trim();
+};
+/** Dates approximate ref history; they cannot establish when a commit reached a moving ref. */
+export const commitAt = async (repo, selector, at) => {
+    let head;
+    try {
+        head = await resolveRewindCommit(repo, selector);
+    }
+    catch {
+        return null;
+    }
+    const commits = (await rewindGit(repo, ["log", "--first-parent", "--format=%H", head, "--"]))
+        .toString().trim().split("\n").filter(Boolean);
+    const dated = [];
+    for (const commit of commits) {
+        const dates = await commitDates(repo, commit);
+        dated.push({ commit, instant: dates.committer, authorInstant: dates.author });
+    }
+    return selectCommitAt(dated, at);
+};
+/** Stable ties preserve the first-parent order returned by git. */
+export const selectCommitAt = (commits, at) => commits.filter((entry) => compareInstants(entry.instant, at) <= 0 && compareInstants(entry.authorInstant ?? entry.instant, at) <= 0)
+    .reduce((latest, entry) => latest === null || compareInstants(entry.instant, latest.instant) > 0 ? entry : latest, null);

package/dist/compiler/training/rewind/gitTree.d.ts

@@ -0,0 +1,14 @@
+export declare const safeCommittedPath: (value: string) => string;
+export interface ExportTreeOptions {
+    root?: string;
+    exclude?: readonly string[];
+    paths?: readonly string[];
+    prefix?: string;
+    mergeIdentical?: boolean;
+}
+/** Materialize blobs by object id, without invoking archive attributes, filters or extraction tools. */
+export declare const exportGitTree: (repo: string, commit: string, destination: string, options?: ExportTreeOptions) => Promise<void>;
+/** Overrides use validated local ustar bytes, never tar commands or the network. */
+export declare const extractOverrideBundle: (file: string, destination: string, expected?: string) => Promise<void>;
+/** Validated archive bytes are extracted only after digest validation by the caller. */
+export declare const extractBundleBytes: (bytes: Buffer, destination: string) => Promise<void>;

package/dist/compiler/training/rewind/gitTree.js

@@ -0,0 +1,90 @@
+import { lstat, mkdir, readFile, readlink, stat, symlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { compileExcludePatterns } from "../../workspaceBundleFiles.js";
+import { validateWorkspaceBundleTar } from "../../workspaceBundleArtifacts.js";
+import { rewindGit } from "./gitProcess.js";
+export const safeCommittedPath = (value) => {
+    if (!value || value.startsWith("/") || value.includes("\\") || value.includes("\0") || value.split("/").some((part) => !part || part === "." || part === ".." || part.toLowerCase() === ".git")) {
+        throw new Error(`Unsafe committed path: ${value}`);
+    }
+    return value;
+};
+/** Never traverse a symlink left by an earlier generated input while merging trees. */
+const parentDirectory = async (root, relative) => {
+    let directory = root;
+    for (const segment of relative.split("/").slice(0, -1)) {
+        directory = path.join(directory, segment);
+        const existing = await lstat(directory).catch((error) => { if (error.code === "ENOENT")
+            return null; throw error; });
+        if (existing && !existing.isDirectory())
+            throw new Error(`Committed entry traverses a non-directory: ${relative}`);
+        if (!existing)
+            await mkdir(directory);
+    }
+};
+/** Materialize blobs by object id, without invoking archive attributes, filters or extraction tools. */
+export const exportGitTree = async (repo, commit, destination, options = {}) => {
+    const root = options.root && options.root !== "." ? safeCommittedPath(options.root.replace(/\/$/u, "")) : "";
+    const tree = root ? `${commit}:${root}` : `${commit}^{tree}`;
+    if ((await rewindGit(repo, ["cat-file", "-t", tree])).toString().trim() !== "tree")
+        throw new Error(`Bundle root ${root || "."} is not a tree at ${commit}`);
+    const entries = (await rewindGit(repo, ["ls-tree", "-rz", tree])).toString("utf8").split("\0").filter(Boolean);
+    const excluded = compileExcludePatterns(options.exclude);
+    const prefix = options.prefix ? safeCommittedPath(options.prefix) : "";
+    await mkdir(destination, { recursive: true });
+    for (const entry of entries) {
+        const tab = entry.indexOf("\t"), name = safeCommittedPath(entry.slice(tab + 1));
+        const [mode, kind, oid] = entry.slice(0, tab).split(" ");
+        if (excluded(name) || (options.paths && !options.paths.some((selected) => name === selected || name.startsWith(`${selected}/`))))
+            continue;
+        if (kind !== "blob" || !["100644", "100755", "120000"].includes(mode))
+            throw new Error(`Committed path ${name} is not a supported file or symlink (submodules need their own history)`);
+        const target = path.join(destination, prefix, name), bytes = await rewindGit(repo, ["cat-file", "blob", oid]);
+        await parentDirectory(destination, [prefix, name].filter(Boolean).join("/"));
+        if (options.mergeIdentical) {
+            const present = await lstat(target).catch((error) => { if (error.code === "ENOENT")
+                return null; throw error; });
+            if (present) {
+                const identical = mode === "120000" ? present.isSymbolicLink() && await readlink(target) === bytes.toString("utf8")
+                    : present.isFile() && (present.mode & 0o111 ? "100755" : "100644") === mode && (await readFile(target)).equals(bytes);
+                if (!identical)
+                    throw new Error(`Conflicting generated bundle inputs at ${name}`);
+                continue;
+            }
+        }
+        if (mode === "120000")
+            await symlink(bytes.toString("utf8"), target);
+        else
+            await writeFile(target, bytes, { flag: "wx", mode: mode === "100755" ? 0o755 : 0o644 });
+    }
+};
+/** Overrides use validated local ustar bytes, never tar commands or the network. */
+export const extractOverrideBundle = async (file, destination, expected) => {
+    const info = await stat(file);
+    if (!info.isFile() || info.size > 536_870_912)
+        throw new Error("Override bundle must be a bounded local tar file");
+    const bytes = await readFile(file);
+    if (expected && `sha256:${createHash("sha256").update(bytes).digest("hex")}` !== expected)
+        throw new Error("Override bundle checksum mismatch");
+    await extractBundleBytes(bytes, destination);
+};
+/** Validated archive bytes are extracted only after digest validation by the caller. */
+export const extractBundleBytes = async (bytes, destination) => {
+    validateWorkspaceBundleTar(bytes);
+    await mkdir(destination, { recursive: true });
+    const text = (buffer) => buffer.toString("utf8").replace(/\0.*$/su, "");
+    for (let offset = 0; offset < bytes.length && !bytes.subarray(offset, offset + 512).every((byte) => byte === 0);) {
+        const header = bytes.subarray(offset, offset + 512), prefix = text(header.subarray(345, 500)), name = text(header.subarray(0, 100));
+        const target = path.join(destination, safeCommittedPath(`${prefix ? `${prefix}/` : ""}${name}`.replace(/\/$/u, "")));
+        const size = Number.parseInt(text(header.subarray(124, 136)).trim(), 8);
+        if (header[156] === 53)
+            await mkdir(target, { recursive: true });
+        else {
+            await mkdir(path.dirname(target), { recursive: true });
+            const executable = Number.parseInt(text(header.subarray(100, 108)).trim(), 8) & 0o111;
+            await writeFile(target, bytes.subarray(offset + 512, offset + 512 + size), { flag: "wx", mode: executable ? 0o755 : 0o644 });
+        }
+        offset += 512 + Math.ceil(size / 512) * 512;
+    }
+};

package/dist/compiler/training/rewind/history.d.ts

@@ -0,0 +1,28 @@
+import type { z } from "zod";
+import { type MomentRecord, type WakeMomentRow } from "../../../recording/index.js";
+import { type DeployResources } from "../../../deployment/index.js";
+import { type FeedLanding } from "../../../volume/index.js";
+export declare const inside: (root: string, target: string) => boolean;
+export declare const safeSegment: (value: string) => string;
+export declare const historyKey: (identity: {
+    declaredBy: string;
+    id: string;
+}) => string;
+/** All reads of the consumer history layout pass through this containment boundary. */
+export declare class History {
+    readonly root: string;
+    constructor(root: string);
+    path(relative: string): Promise<string | null>;
+    bytes(relative: string): Promise<Buffer | null>;
+    text(relative: string): Promise<string | null>;
+    jsonl<T>(relative: string, schema: z.ZodType<T>): Promise<T[] | null>;
+    feedLandings(key: string, resource: string): Promise<FeedLanding[]>;
+    wakeMoments(relative: string): Promise<WakeMomentRow[] | null>;
+    /** One imported deployment, preserving its original absolute identity without opening that path. */
+    deploymentResources(at: string, agentId?: string): Promise<DeployResources | null>;
+    records(): Promise<MomentRecord[]>;
+    /** Validate all tree entries before git or another local parser receives the directory. */
+    repository(relative: string): Promise<string | null>;
+    copyTree(relative: string, destination: string): Promise<void>;
+}
+export declare const openHistory: (directory?: string) => Promise<History | undefined>;