spawnfile 0.1.17 → 0.1.19

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

@@ -0,0 +1,239 @@
+import { chmod, lstat, mkdir, readFile, readdir, readlink, realpath, symlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { momentRecordSchema, parseMomentRecord, parseWakeMoments } from "../../../recording/index.js";
+import { deployResourceLogPath, deployResourcesAt, deployResourcesSchema } from "../../../deployment/index.js";
+import { readFeedLandings } from "../../../volume/index.js";
+export const inside = (root, target) => {
+    const relative = path.relative(root, target);
+    return relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+};
+export const safeSegment = (value) => {
+    if (!value || value === "." || value === ".." || /[/\\\0]/u.test(value))
+        throw new Error(`Unsafe history identity ${JSON.stringify(value)}`);
+    return value;
+};
+export const historyKey = (identity) => `${safeSegment(encodeURIComponent(identity.declaredBy))}/${safeSegment(identity.id)}`;
+const reason = (error) => error instanceof Error ? error.message : String(error);
+/** All reads of the consumer history layout pass through this containment boundary. */
+export class History {
+    root;
+    constructor(root) { this.root = root; }
+    async path(relative) {
+        if (path.isAbsolute(relative) || relative.includes("\\") || relative.includes("\0"))
+            throw new Error(`Unsafe history path ${relative}`);
+        const target = path.resolve(this.root, relative);
+        if (!inside(this.root, target))
+            throw new Error(`History path escapes root: ${relative}`);
+        let ancestor = target;
+        while (true) {
+            try {
+                const physical = await realpath(ancestor);
+                if (!inside(this.root, physical))
+                    throw new Error(`History symlink escape: ${relative}`);
+                break;
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+                if (ancestor === this.root)
+                    throw new Error(`History root no longer exists: ${this.root}`);
+                ancestor = path.dirname(ancestor);
+            }
+        }
+        try {
+            await lstat(target);
+            // A dangling symlink is not a missing history entry.
+            const physical = await realpath(target);
+            if (!inside(this.root, physical))
+                throw new Error(`History symlink escape: ${relative}`);
+            return target;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            const entry = await lstat(target).catch(() => null);
+            if (entry?.isSymbolicLink())
+                throw new Error(`Dangling history symlink: ${relative}`);
+            return null;
+        }
+    }
+    async bytes(relative) {
+        const file = await this.path(relative);
+        if (file === null)
+            return null;
+        if (!(await lstat(await realpath(file))).isFile())
+            throw new Error(`History entry must be a regular file: ${relative}`);
+        return readFile(file);
+    }
+    async text(relative) { return (await this.bytes(relative))?.toString("utf8") ?? null; }
+    async jsonl(relative, schema) {
+        const payload = await this.text(relative);
+        if (payload === null)
+            return null;
+        const lines = payload.split("\n");
+        if (lines.at(-1) === "")
+            lines.pop();
+        return lines.map((line, index) => {
+            try {
+                return schema.parse(JSON.parse(line));
+            }
+            catch (error) {
+                throw new Error(`Invalid history ${relative}:${index + 1}: ${reason(error)}`);
+            }
+        });
+    }
+    async feedLandings(key, resource) {
+        const relative = `${key}/landings.jsonl`, file = await this.path(relative);
+        if (!file)
+            return [];
+        if (!(await lstat(await realpath(file))).isFile())
+            throw new Error(`History entry must be a regular file: ${relative}`);
+        const result = readFeedLandings(path.dirname(file));
+        if (result.errors.length)
+            throw new Error(`Invalid history ${result.errors.map((error) => `${relative}:${error.replace(/^(?:wake moments )?line /u, "")}`).join("; ")}`);
+        result.entries.forEach((entry, index) => {
+            if (entry.resource !== resource)
+                throw new Error(`Invalid history ${relative}:${index + 1}: Landing resource disagrees with the history input`);
+        });
+        return result.entries;
+    }
+    async wakeMoments(relative) {
+        const payload = await this.text(relative);
+        if (payload === null)
+            return null;
+        const result = parseWakeMoments(payload);
+        if (result.errors.length)
+            throw new Error(`Invalid history ${result.errors.map((error) => `${relative}:${error.replace(/^(?:wake moments )?line /u, "")}`).join("; ")}`);
+        return result.entries;
+    }
+    /** One imported deployment, preserving its original absolute identity without opening that path. */
+    async deploymentResources(at, agentId) {
+        const directory = await this.path("deployments");
+        if (!directory)
+            return null;
+        const logs = [];
+        for (const name of (await readdir(directory)).sort()) {
+            const relative = `deployments/${name}`, entry = await this.path(relative);
+            if (!entry)
+                throw new Error(`History entry vanished: ${relative}`);
+            if (name.endsWith(".resource-log.jsonl"))
+                logs.push(relative);
+            else if ((await lstat(await realpath(entry))).isDirectory() && await this.path(`${relative}/resource-log.jsonl`))
+                logs.push(`${relative}/resource-log.jsonl`);
+        }
+        if (!logs.length)
+            return null;
+        if (logs.length !== 1)
+            throw new Error("Rewind history must contain one deployment resource log; multiple deployments are ambiguous");
+        const relative = logs[0], entries = await this.jsonl(relative, deployResourcesSchema) ?? [];
+        if (!entries.length)
+            return null;
+        const identities = new Set(entries.map((entry) => entry.deployment_id));
+        const recordPath = entries[0].deployment_id;
+        if (identities.size !== 1 || !path.isAbsolute(recordPath) || path.resolve(recordPath) !== recordPath) {
+            throw new Error(`Invalid history ${relative}: expected one canonical deployment_id`);
+        }
+        const originalLog = deployResourceLogPath(recordPath);
+        const mirror = path.basename(recordPath) === "record.json"
+            ? `deployments/${path.basename(path.dirname(recordPath))}/${path.basename(originalLog)}`
+            : `deployments/${path.basename(originalLog)}`;
+        if (relative !== mirror)
+            throw new Error(`Invalid history ${relative}: deployment_id requires ${mirror}`);
+        if (!agentId)
+            throw new Error("Deployment resource lookup requires the compiled agent ID");
+        return deployResourcesAt(entries, recordPath, at, agentId);
+    }
+    async records() {
+        const directory = await this.path("moments");
+        if (!directory)
+            return [];
+        const records = [];
+        const seen = new Set();
+        const walk = async (relative) => {
+            const file = await this.path(relative);
+            if (!file)
+                throw new Error(`History entry vanished: ${relative}`);
+            const physical = await realpath(file);
+            if ((await lstat(physical)).isDirectory()) {
+                if (seen.has(physical))
+                    throw new Error(`Repeated moment history directory: ${relative}`);
+                seen.add(physical);
+                for (const name of (await readdir(file)).sort())
+                    await walk(`${relative}/${name}`);
+            }
+            else if (relative.endsWith(".jsonl"))
+                records.push(...(await this.jsonl(relative, momentRecordSchema) ?? []));
+            else if (relative.endsWith(".json")) {
+                try {
+                    records.push(parseMomentRecord((await this.text(relative))));
+                }
+                catch (error) {
+                    throw new Error(`Invalid history ${relative}: ${reason(error)}`);
+                }
+            }
+        };
+        await walk("moments");
+        return records;
+    }
+    /** Validate all tree entries before git or another local parser receives the directory. */
+    async repository(relative) {
+        const root = await this.path(relative);
+        if (!root)
+            return null;
+        const seen = new Set();
+        const walk = async (entry) => {
+            const file = await this.path(entry);
+            if (!file)
+                throw new Error(`History entry vanished: ${entry}`);
+            const physical = await realpath(file), stats = await lstat(physical);
+            if (seen.has(physical))
+                return;
+            seen.add(physical);
+            if (stats.isDirectory())
+                for (const name of await readdir(file))
+                    await walk(`${entry}/${name}`);
+            else if (!stats.isFile())
+                throw new Error(`Special history file: ${entry}`);
+        };
+        await walk(relative);
+        return root;
+    }
+    async copyTree(relative, destination) {
+        const source = await this.path(relative);
+        if (!source)
+            throw new Error(`Missing retained tree: ${relative}`);
+        const stats = await lstat(source);
+        if (!stats.isDirectory())
+            throw new Error(`Retained tree must be a real directory: ${relative}`);
+        const copy = async (entry, target) => {
+            const file = await this.path(entry);
+            if (!file)
+                throw new Error(`History entry vanished: ${entry}`);
+            const stat = await lstat(file);
+            if (stat.isSymbolicLink()) {
+                await symlink(await readlink(file), target);
+                return;
+            }
+            if (stat.isDirectory()) {
+                await mkdir(target, { recursive: true });
+                for (const name of (await readdir(file)).sort())
+                    await copy(`${entry}/${name}`, path.join(target, name));
+            }
+            else if (stat.isFile()) {
+                await writeFile(target, (await this.bytes(entry)));
+                await chmod(target, stat.mode & 0o777);
+            }
+            else
+                throw new Error(`Special history file: ${entry}`);
+        };
+        await copy(relative, destination);
+    }
+}
+export const openHistory = async (directory) => {
+    if (directory === undefined)
+        return undefined;
+    const root = await realpath(path.resolve(directory));
+    if (!(await lstat(root)).isDirectory())
+        throw new Error(`History must be a directory: ${directory}`);
+    return new History(root);
+};

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

@@ -0,0 +1,18 @@
+export * from "./contract.js";
+export * from "./history.js";
+export * from "./inputs.js";
+export * from "./instant.js";
+export * from "./leakCheck.js";
+export * from "./materialize.js";
+export * from "./select.js";
+export * from "./taskClock.js";
+export { feedLandingAt } from "../../../volume/index.js";
+export { selectFeedCommit } from "./feed.js";
+export { selectCommitAt } from "./gitProcess.js";
+export { selectMemoryPrefix, parseMemoryLedger } from "./memory.js";
+export { rewindMoltnetJson } from "./moltnetJson.js";
+export { selectVolumeSnapshot } from "./volumes.js";
+export type * from "./types.js";
+export { inspectMoltnetSqlite } from "./moltnetSqlite.js";
+export type { MoltnetMessageFilter, MoltnetSqliteInspection } from "./moltnetSqlite.js";
+export type { MoltnetMessage } from "./moltnetSchemas.js";

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

@@ -0,0 +1,15 @@
+export * from "./contract.js";
+export * from "./history.js";
+export * from "./inputs.js";
+export * from "./instant.js";
+export * from "./leakCheck.js";
+export * from "./materialize.js";
+export * from "./select.js";
+export * from "./taskClock.js";
+export { feedLandingAt } from "../../../volume/index.js";
+export { selectFeedCommit } from "./feed.js";
+export { selectCommitAt } from "./gitProcess.js";
+export { selectMemoryPrefix, parseMemoryLedger } from "./memory.js";
+export { rewindMoltnetJson } from "./moltnetJson.js";
+export { selectVolumeSnapshot } from "./volumes.js";
+export { inspectMoltnetSqlite } from "./moltnetSqlite.js";

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

@@ -0,0 +1,9 @@
+import type { LoadedTrainingProject, TrainingPlan } from "../plan/index.js";
+import type { RewindInput } from "./types.js";
+/** The same compiled resources, accessible bank sources and surface attachments P2 resolves. */
+export declare const resolveRewindInputs: (plan: TrainingPlan, project: LoadedTrainingProject, selector: string) => {
+    inputs: RewindInput[];
+    selected: import("./select.js").SelectedExample;
+    at: string;
+    agentSlug: string;
+};

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

@@ -0,0 +1,67 @@
+import path from "node:path";
+import { resolveTrainingOverride, resolveTrainingResource } from "../plan/references.js";
+import { selectTrainingExample } from "./select.js";
+import { normalizeInstant } from "./instant.js";
+/** The same compiled resources, accessible bank sources and surface attachments P2 resolves. */
+export const resolveRewindInputs = (plan, project, selector) => {
+    const selected = selectTrainingExample(plan, selector);
+    const agent = project.compilePlan.nodes.find((node) => node.value.kind === "agent" && node.id === plan.agent.id);
+    if (!agent)
+        throw new Error(`No compiled training agent ${plan.agent.id}`);
+    const raw = project.datasets[selected.sourcePath]?.value.examples.find((example) => example.id === selected.id);
+    if (!raw || normalizeInstant(raw.at) !== normalizeInstant(selected.example.at))
+        throw new Error(`Loaded example disagrees with plan: ${selector}`);
+    const inputs = [];
+    const declarationBase = (id) => {
+        const node = project.compilePlan.nodes.find((candidate) => candidate.id === id);
+        if (!node)
+            throw new Error(`Missing declaring node ${id}`);
+        return path.dirname(node.value.kind === "agent" ? node.value.sourcePath ?? node.value.source : node.value.source);
+    };
+    for (const resource of agent.value.workspaceResources ?? []) {
+        const { declaredBy } = resolveTrainingResource(project.compilePlan, agent, resource.id, "Rewind resource");
+        inputs.push({ section: "resources", id: resource.id, declaredBy, declarationBase: declarationBase(declaredBy),
+            declaration: resource, overridden: false });
+    }
+    const banks = new Set();
+    for (const entry of agent.value.memoryAccess ?? []) {
+        const key = JSON.stringify([entry.source, entry.bank.id]);
+        if (banks.has(key))
+            continue;
+        banks.add(key);
+        const node = project.compilePlan.nodes.find((candidate) => candidate.value.source === entry.source);
+        if (!node)
+            throw new Error(`Memory bank ${entry.bank.id} has no declaring node`);
+        inputs.push({ section: "memory", id: entry.bank.id, declaredBy: node.id,
+            declarationBase: declarationBase(node.id), declaration: entry.bank, overridden: false });
+    }
+    const networks = new Set();
+    for (const attachment of agent.value.surfaces?.moltnet ?? []) {
+        const sources = new Set([attachment.teamSource, ...Object.keys(attachment.contextRooms ?? {})]);
+        for (const node of project.compilePlan.nodes) {
+            if (node.value.kind !== "team" || !sources.has(node.value.source))
+                continue;
+            for (const network of node.value.networks ?? []) {
+                if (network.id !== attachment.network)
+                    continue;
+                const key = JSON.stringify([node.id, network.id]);
+                if (networks.has(key))
+                    continue;
+                networks.add(key);
+                inputs.push({ section: "networks", id: network.id, declaredBy: node.id,
+                    declarationBase: declarationBase(node.id), declaration: network, overridden: false });
+            }
+        }
+    }
+    for (const section of ["resources", "memory", "networks"]) {
+        for (const declaration of raw[section] ?? []) {
+            const identity = resolveTrainingOverride(project.compilePlan, agent, section, declaration.id, `Rewind override ${selector}`);
+            const index = inputs.findIndex((input) => input.section === section && input.id === identity.id && input.declaredBy === identity.declaredBy);
+            if (index === -1)
+                throw new Error(`Missing effective override ${section}:${identity.id}`);
+            inputs[index] = { ...inputs[index], declaration, declarationBase: path.dirname(selected.sourcePath), overridden: true };
+        }
+    }
+    inputs.sort((a, b) => a.section.localeCompare(b.section) || a.declaredBy.localeCompare(b.declaredBy) || a.id.localeCompare(b.id));
+    return { inputs, selected, at: normalizeInstant(raw.at), agentSlug: agent.slug };
+};

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

@@ -0,0 +1,4 @@
+/** RFC3339Nano ordering, including offsets and fractions Date.parse would truncate. */
+export declare const instantNanos: (value: string) => bigint;
+export declare const compareInstants: (left: string, right: string) => number;
+export declare const normalizeInstant: (value: string) => string;

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

@@ -0,0 +1,24 @@
+import { trainingInstantSchema } from "../../../manifest/index.js";
+/** RFC3339Nano ordering, including offsets and fractions Date.parse would truncate. */
+export const instantNanos = (value) => {
+    trainingInstantSchema.parse(value);
+    const match = /^(.*T\d{2}:\d{2})(?::(\d{2})(?:\.(\d{1,9}))?)?(Z|[+-]\d{2}:\d{2})$/u.exec(value);
+    if (!match)
+        throw new Error(`Unsupported instant ${value}: at most nanosecond precision is required`);
+    const seconds = Date.parse(`${match[1]}:${match[2] ?? "00"}${match[4]}`);
+    if (!Number.isFinite(seconds))
+        throw new Error(`Invalid instant ${value}`);
+    return BigInt(seconds) * 1000000n + BigInt((match[3] ?? "").padEnd(9, "0"));
+};
+export const compareInstants = (left, right) => {
+    const a = instantNanos(left), b = instantNanos(right);
+    return a < b ? -1 : a > b ? 1 : 0;
+};
+export const normalizeInstant = (value) => {
+    const ns = instantNanos(value), seconds = ns / 1000000000n;
+    const fraction = (ns % 1000000000n + 1000000000n) % 1000000000n;
+    const floorSeconds = ns < 0n && fraction !== 0n ? seconds - 1n : seconds;
+    const base = new Date(Number(floorSeconds * 1000n)).toISOString().replace(/\.000Z$/u, "");
+    const tail = fraction.toString().padStart(9, "0").replace(/0+$/u, "");
+    return `${base}${tail ? `.${tail}` : ""}Z`;
+};

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

@@ -0,0 +1,10 @@
+import { type LeakCheck, type MaterializedMoment } from "./contract.js";
+export interface LeakCheckOptions {
+    historyDir?: string;
+}
+/** Independent acceptance boundary: only disk reports, disk payloads and disk history are trusted. */
+export declare const inspectTrainingMoment: (bundle: string, options?: LeakCheckOptions, skipRefused?: boolean) => Promise<{
+    moment: MaterializedMoment;
+    check: LeakCheck | null;
+}>;
+export declare const leakCheckTrainingMoment: (bundle: string, options?: LeakCheckOptions) => Promise<LeakCheck>;

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

@@ -0,0 +1,56 @@
+import { readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+import { materializedMomentSchema, leakCheckSchema } from "./contract.js";
+import { openHistory } from "./history.js";
+import { diskPath, inspectBundleFiles, restoreInspectedAccessTimes, snapshotBundleFiles } from "./leakFiles.js";
+import { inspectGitBundle } from "./leakGit.js";
+import { inspectInputProvenance } from "./leakProvenance.js";
+import { addInputFinding, inspectFeedBundle, inspectMemoryBundle, inspectMoltnetBundle, inspectVolumeBundle } from "./leakInputs.js";
+/** Independent acceptance boundary: only disk reports, disk payloads and disk history are trusted. */
+export const inspectTrainingMoment = async (bundle, options = {}, skipRefused = false) => {
+    const root = await realpath(path.resolve(bundle));
+    const files = await snapshotBundleFiles(root);
+    try {
+        const moment = materializedMomentSchema.parse(JSON.parse(await readFile(await diskPath(root, "moment.json"), "utf8")));
+        if (skipRefused && moment.status === "refused")
+            return { moment, check: null };
+        const report = { version: "spawnfile.leak-check.v1", at: moment.effectiveAt, ok: false,
+            checked: { files: 0, gitObjects: 0, memoryEvents: 0, moltnetMessages: 0, moltnetEvents: 0, snapshots: 0 }, findings: [] };
+        await inspectBundleFiles(root, moment.inputs, report, files);
+        for (const input of moment.inputs) {
+            const kind = input.kind === "memory" ? "memory-event"
+                : input.kind === "moltnet" ? "moltnet-message" : input.kind === "feed" ? "feed-identity"
+                    : input.kind === "volume" ? "snapshot" : "git-object";
+            try {
+                if (!input.path || input.refusal || !input.fidelity)
+                    throw new Error("Input is not materialized");
+                const directory = await diskPath(root, input.path);
+                // Do not hand git/SQLite a payload with escaping paths, even for a failed check.
+                if (report.findings.some((finding) => finding.class === "symlink-escape"
+                    && (finding.path === input.path || finding.path.startsWith(`${input.path}/`))))
+                    continue;
+                if (["git", "bundle", "feed"].includes(input.kind))
+                    await inspectInputProvenance(root, input, report, options.historyDir);
+                if (input.kind === "git")
+                    await inspectGitBundle(directory, input, report);
+                if (input.kind === "memory")
+                    await inspectMemoryBundle(root, input, report);
+                if (input.kind === "feed")
+                    await inspectFeedBundle(root, input, report, moment, await openHistory(options.historyDir));
+                if (input.kind === "moltnet")
+                    await inspectMoltnetBundle(root, input, report);
+                if (input.kind === "volume")
+                    await inspectVolumeBundle(root, input, report, await openHistory(options.historyDir));
+            }
+            catch (error) {
+                addInputFinding(report, input, kind, error instanceof Error ? error.message : String(error), input.path ?? ".");
+            }
+        }
+        report.ok = report.findings.length === 0;
+        return { moment, check: leakCheckSchema.parse(report) };
+    }
+    finally {
+        await restoreInspectedAccessTimes(files);
+    }
+};
+export const leakCheckTrainingMoment = async (bundle, options = {}) => (await inspectTrainingMoment(bundle, options)).check;

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

@@ -0,0 +1,5 @@
+import { type FeedIdentity } from "../../../volume/index.js";
+import type { MaterializedInput, MaterializedMoment } from "./contract.js";
+import { type History } from "./history.js";
+/** Publication metadata can follow the bound only when independent history proves the incoming pin/window. */
+export declare const permitsFeedPublicationTime: (identity: FeedIdentity, input: MaterializedInput, moment: MaterializedMoment, history?: History) => Promise<boolean>;

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

@@ -0,0 +1,25 @@
+import { feedLandingAt } from "../../../volume/index.js";
+import { historyKey } from "./history.js";
+import { compareInstants } from "./instant.js";
+import { recordInputErrors } from "./recordInput.js";
+import { selectMomentRecord } from "./select.js";
+/** Publication metadata can follow the bound only when independent history proves the incoming pin/window. */
+export const permitsFeedPublicationTime = async (identity, input, moment, history) => {
+    if (!history || identity.landed_at !== input.source.landedAt)
+        return false;
+    if (input.basis === "record" && input.fidelity === "exact" && moment.record.matched) {
+        const record = selectMomentRecord(await history.records(), moment.agent, moment.at, [input]);
+        const pin = record?.feeds.find((entry) => entry.id === input.id);
+        return Boolean(record && pin && compareInstants(record.wake.startedAt, moment.effectiveAt) === 0
+            && !recordInputErrors(record, input).length && pin.revision === identity.revision
+            && pin.tree.replace(/^trees\//u, "") === identity.tree.replace(/^trees\//u, "")
+            && pin.commit === input.source.commit && compareInstants(pin.landedAt, identity.landed_at) === 0);
+    }
+    if (input.basis !== "landing-log" || input.fidelity !== "approximate")
+        return false;
+    const landing = feedLandingAt(await history.feedLandings(`feeds/${historyKey(input)}`, input.id), moment.effectiveAt);
+    return Boolean(landing?.ambiguous && landing.revision === identity.revision
+        && landing.tree.replace(/^trees\//u, "") === identity.tree.replace(/^trees\//u, "")
+        && landing.commit === input.source.commit && landing.switching_at === input.source.switchingAt
+        && compareInstants(landing.landed_at, identity.landed_at) === 0);
+};

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

@@ -0,0 +1,10 @@
+import type { BigIntStats } from "node:fs";
+import type { LeakCheck, MaterializedInput } from "./contract.js";
+export declare const inputAtPath: (inputs: MaterializedInput[], relative: string) => MaterializedInput | undefined;
+export declare const diskPath: (root: string, relative: string) => Promise<string>;
+/** Capture metadata before any inspection read can advance an entry's access time. */
+export declare const snapshotBundleFiles: (root: string) => Promise<Map<string, BigIntStats>>;
+/** Preserve the inspected access times, including future ones; never hide an existing violation. */
+export declare const restoreInspectedAccessTimes: (files: Map<string, BigIntStats>) => Promise<void>;
+/** No symlinks are traversed. Inspection never reads a target outside the bundle. */
+export declare const inspectBundleFiles: (root: string, inputs: MaterializedInput[], report: LeakCheck, files: Map<string, BigIntStats>) => Promise<void>;

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

@@ -0,0 +1,106 @@
+import { lstat, lutimes, readdir, readlink, realpath, utimes } from "node:fs/promises";
+import path from "node:path";
+import { inside } from "./history.js";
+import { instantNanos } from "./instant.js";
+export const inputAtPath = (inputs, relative) => inputs.find((input) => input.path !== null && (relative === input.path || relative.startsWith(`${input.path}/`)));
+export const diskPath = async (root, relative) => {
+    const candidate = path.resolve(root, relative);
+    if (!inside(root, candidate) || path.isAbsolute(relative))
+        throw new Error(`Bundle path escapes root: ${relative}`);
+    if (!inside(root, await realpath(candidate)))
+        throw new Error(`Bundle symlink escapes root: ${relative}`);
+    return candidate;
+};
+/** Capture metadata before any inspection read can advance an entry's access time. */
+export const snapshotBundleFiles = async (root) => {
+    const files = new Map();
+    const visit = async (file) => {
+        const stats = await lstat(file, { bigint: true });
+        files.set(file, stats);
+        if (stats.isDirectory())
+            for (const name of (await readdir(file)).sort())
+                await visit(path.join(file, name));
+    };
+    await visit(root);
+    return files;
+};
+/** Preserve the inspected access times, including future ones; never hide an existing violation. */
+export const restoreInspectedAccessTimes = async (files) => {
+    for (const [file, stats] of [...files].reverse()) {
+        // Numeric strings preserve sub-millisecond precision; negative numeric arguments mean "now" in Node.
+        await (stats.isSymbolicLink() ? lutimes : utimes)(file, String(Number(stats.atimeNs / 1000n) / 1_000_000), String(Number(stats.mtimeNs / 1000n) / 1_000_000));
+    }
+};
+/** No symlinks are traversed. Inspection never reads a target outside the bundle. */
+export const inspectBundleFiles = async (root, inputs, report, files) => {
+    const at = instantNanos(report.at);
+    const latestDate = new Date(Math.min(253_402_300_799_999, Date.parse(report.at) + 14 * 3600_000)).toISOString().slice(0, 10);
+    const visit = async (file) => {
+        const relative = path.relative(root, file).split(path.sep).join("/") || ".";
+        const owner = inputAtPath(inputs, relative);
+        const input = owner ? { section: owner.section, id: owner.id, declaredBy: owner.declaredBy } : null;
+        const add = (kind, detail) => {
+            report.findings.push({ input, class: kind, path: relative, detail });
+        };
+        const stats = files.get(file);
+        if (!owner && relative !== ".") {
+            const reportFile = ["moment.json", "leak-check.json", "task-clock.json"].includes(relative) && stats.isFile();
+            const wrapper = stats.isDirectory() && inputs.some((entry) => entry.path?.startsWith(`${relative}/`));
+            if (!reportFile && !wrapper)
+                add("bundle-entry", "Unexpected entry outside the materialized inputs and reports");
+        }
+        report.checked.files++;
+        if (stats.mtimeNs > at)
+            add("file-time", "Modification time is later than the moment");
+        if (stats.atimeNs > at)
+            add("file-time", "Access time is later than the moment");
+        const allowedGitDirectory = owner?.kind === "git" && relative === `${owner.path}/.git` && stats.isDirectory();
+        if (path.basename(file).toLowerCase() === ".git" && !allowedGitDirectory) {
+            add("git-object", "Unexpected .git repository metadata outside the materialized git resource repository");
+        }
+        const head = files.get(path.join(file, "HEAD"));
+        const objects = files.get(path.join(file, "objects"));
+        const refs = files.get(path.join(file, "refs"));
+        if (stats.isDirectory() && head && (head.isFile() || head.isSymbolicLink())
+            && objects && (objects.isDirectory() || objects.isSymbolicLink())
+            && refs && (refs.isDirectory() || refs.isSymbolicLink()) && !allowedGitDirectory) {
+            add("git-object", "Unexpected bare repository (HEAD, objects/, refs/) outside the materialized git resource repository");
+        }
+        for (const match of path.basename(file).matchAll(/\d{4}-\d{2}-\d{2}/gu)) {
+            const date = match[0];
+            const parsed = Date.parse(`${date}T00:00:00Z`);
+            if (Number.isFinite(parsed) && new Date(parsed).toISOString().startsWith(date) && date > latestDate) {
+                add("dated-path", `Calendar date ${date} is later than the latest possible local date ${latestDate}`);
+            }
+        }
+        if (stats.isSymbolicLink()) {
+            const link = await readlink(file);
+            if (path.isAbsolute(link) || !inside(root, path.resolve(path.dirname(file), link))) {
+                add("symlink-escape", `Unsafe symlink target ${JSON.stringify(link)}`);
+                return;
+            }
+            // Even a dangling leaf can cross an existing symlink in a parent component.
+            let target = path.resolve(path.dirname(file), link);
+            for (;;) {
+                try {
+                    if (!inside(root, await realpath(target)))
+                        add("symlink-escape", "Symlink resolves outside the bundle");
+                    break;
+                }
+                catch (error) {
+                    if (error.code !== "ENOENT") {
+                        add("symlink-escape", `Cannot resolve symlink: ${String(error)}`);
+                        break;
+                    }
+                    if (target === root)
+                        break;
+                    target = path.dirname(target);
+                }
+            }
+        }
+        else if (!stats.isDirectory() && !stats.isFile())
+            add("symlink-escape", "Special files are not allowed in a moment bundle");
+    };
+    for (const file of files.keys())
+        await visit(file);
+};

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

@@ -0,0 +1,3 @@
+import type { LeakCheck, MaterializedInput } from "./contract.js";
+/** Enumerate every stored object, independently of the materializer's chosen-object list. */
+export declare const inspectGitBundle: (repository: string, input: MaterializedInput, report: LeakCheck) => Promise<void>;