spawnfile 0.1.17 → 0.1.19

package/dist/volume/feedLayout.d.ts

@@ -0,0 +1,61 @@
+import { readlinkSync, renameSync, symlinkSync, unlinkSync } from "node:fs";
+import type { Stats } from "node:fs";
+import { SpawnfileError } from "../shared/index.js";
+export declare const FEED_TREES_DIR = "trees";
+export declare const FEED_CURRENT_LINK = "current";
+export declare const FEED_IDENTITY_FILE = ".spawnfile-feed.json";
+export declare const VOLUME_RESOURCE_SENTINEL = ".spawnfile-resource-identity";
+export declare const VOLUME_ROOT_MODE = 493;
+/** Every name the host itself ever writes at the volume root, plus the container's own sentinel. */
+export declare const FEED_ROOT_NAMES: readonly string[];
+export declare const feedError: (message: string) => SpawnfileError;
+export declare const feedTreeLink: (revision: string) => string;
+/** Read before any write, and a refusal rather than a repair: the start guard owns that contract. */
+export declare const assertFeedVolumeRoot: (volume: string) => void;
+/** Absent is not an error (null); a symlink or file where a host directory belongs is a refusal, never a repair. */
+export declare const assertRealDirectory: (target: string, label: string) => Stats | null;
+/** rename(2) is atomic only within one filesystem; a cross-device "rename" is a copy readers can watch. */
+export declare const assertSameDevice: (volume: string, other: string, label: string) => void;
+/** Host state must never live where an agent can write it: it decides what a root-run job deletes. */
+export declare const assertOutsideVolume: (volume: string, target: string, label: string) => void;
+/**
+ * Ownership and read-only modes for a staged tree, before it is reachable. Never follows a symlink.
+ * The top directory stays 0755 so the one rename into the volume works for a non-root writer;
+ * `landTree` freezes it the moment it lands.
+ */
+export declare const ownAndFreeze: (stagingDir: string, { owner, volume }: {
+    owner?: string;
+    volume: string;
+}) => void;
+/** The one rename that makes a validated tree part of the volume, with its root frozen the moment it lands. */
+export declare const landTree: (stagingDir: string, treePath: string) => void;
+/** Every filesystem call the link swap makes, so a test can watch what the swap actually does. */
+export declare const LINK_OPS: Readonly<{
+    lstat: import("fs").StatSyncFn;
+    readlink: typeof readlinkSync;
+    rename: typeof renameSync;
+    symlink: typeof symlinkSync;
+    unlink: typeof unlinkSync;
+}>;
+export type LinkOps = typeof LINK_OPS;
+export declare const moveAsideCommand: (volume: string, target: string) => string;
+/**
+ * ATOMIC OR NOTHING. The live name is never unlinked: a new link is created under a temporary name outside
+ * the volume and rename(2)'d over the live one, so a reader resolving `current` sees the old target or
+ * the new one, never a missing name. The target is relative so it resolves the same on the host and at
+ * the container mount. Returns false when the link already points at `target`.
+ */
+export declare const pointCurrent: (volume: string, target: string, { ops, tmpDir, beforeRename }: {
+    ops?: LinkOps;
+    tmpDir: string;
+    beforeRename?: () => void;
+}) => boolean;
+/** Thaw and delete a tree OUTSIDE the volume. A recursive delete is only ever aimed at a real directory. */
+export declare const removeTree: (target: string, { volume }: {
+    volume: string;
+}) => void;
+/** One rename out of the volume. Write on the moved directory is needed to change its parent. */
+export declare const parkTree: (treePath: string, trash: string, stamp: string) => string;
+/** Names at the volume root the host never writes. Reported, never deleted: they are evidence. */
+export declare const auditFeedRoot: (volume: string) => string[];
+export declare const treeShape: (target: string) => "missing" | "directory" | "symlink" | "file";

package/dist/volume/feedLayout.js

@@ -0,0 +1,234 @@
+// The physical layout of a fed volume, and every rule about what the host writer may touch inside it.
+//
+// WHY THESE RULES ARE NOT NEGOTIABLE
+// ----------------------------------
+// A fed volume is mounted into running agents, and the container's start guard inspects the volume
+// root on every start: the root must stay mode 0755 and `.spawnfile-resource-identity` must stay exactly
+// the bytes, owner and mode the container wrote. Readers inside the agents never pause for a refresh.
+// So a host writer can break every agent without writing a byte an agent reads:
+//
+//   * a partially copied tree, or a tree mid-delete, inside the volume -> a reader (or the start
+//     guard) lists an entry that is gone by the time it is opened;
+//   * a recursive chown/chmod aimed at the volume root -> the identity sentinel changes -> the next
+//     container start refuses the volume;
+//   * the root's own mode moved off 0755 -> the start guard refuses the volume.
+//
+// Hence the shape every function here enforces: content is staged OUTSIDE the volume, enters it through
+// exactly one rename(2), becomes visible through one rename(2) of the `current` link, leaves it through
+// exactly one rename(2), and is deleted outside it. No recursive mode or ownership change is ever aimed
+// at anything but a tree the host still holds privately.
+//
+//     <state>/staging/<revision>-<pid>/   copied, validated, owned, frozen here
+//         |  rename(2)
+//     <volume>/trees/<revision>/          immutable content, never rewritten in place
+//     <volume>/current -> trees/<revision>   rename(2) over the old link
+//     <volume>/.spawnfile-feed.json       which revision `current` serves
+//         |  rename(2)
+//     <state>/trash/<revision>-<stamp>/   deleted out here, never inside the volume
+//
+// The volume root stays writable by the agent uid (the container chowns it on start), so the host never
+// takes a decision from a name inside the volume: every path it is about to touch is lstat'd and refused
+// unless it is the real directory the host created.
+import { chmodSync, lchownSync, lstatSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, unlinkSync } from "node:fs";
+import path from "node:path";
+import { SpawnfileError } from "../shared/index.js";
+export const FEED_TREES_DIR = "trees";
+export const FEED_CURRENT_LINK = "current";
+export const FEED_IDENTITY_FILE = ".spawnfile-feed.json";
+export const VOLUME_RESOURCE_SENTINEL = ".spawnfile-resource-identity";
+export const VOLUME_ROOT_MODE = 0o755;
+/** Every name the host itself ever writes at the volume root, plus the container's own sentinel. */
+export const FEED_ROOT_NAMES = Object.freeze([VOLUME_RESOURCE_SENTINEL, FEED_IDENTITY_FILE, FEED_TREES_DIR, FEED_CURRENT_LINK]);
+export const feedError = (message) => new SpawnfileError("runtime_error", message);
+const fail = (message) => { throw feedError(message); };
+export const feedTreeLink = (revision) => `${FEED_TREES_DIR}/${revision}`;
+const readlinkOrNull = (target) => { try {
+    return readlinkSync(target);
+}
+catch {
+    return null;
+} };
+/** Resolved through symlinks even when the leaf does not exist yet: the nearest existing ancestor is realpath'd. */
+const canonical = (target) => {
+    const absolute = path.resolve(target);
+    try {
+        return realpathSync(absolute);
+    }
+    catch {
+        const parent = path.dirname(absolute);
+        return parent === absolute ? absolute : path.join(canonical(parent), path.basename(absolute));
+    }
+};
+/** Read before any write, and a refusal rather than a repair: the start guard owns that contract. */
+export const assertFeedVolumeRoot = (volume) => {
+    let stat;
+    try {
+        stat = statSync(volume);
+    }
+    catch {
+        return fail(`fed volume ${volume} does not exist; deploy the organization once so the volume is created`);
+    }
+    if (!stat.isDirectory())
+        fail(`fed volume ${volume} is not a directory`);
+    const mode = stat.mode & 0o7777;
+    if (mode !== VOLUME_ROOT_MODE) {
+        fail(`fed volume root ${volume} is mode 0${mode.toString(8)}, must be 0755: the container start guard refuses any other mode. Repair with: chmod 0755 ${volume}`);
+    }
+    // The container bootstraps an EMPTY volume and refuses a non-empty one without its sentinel, so content
+    // landed before the first start would stop every agent from starting at all.
+    let sentinel = null;
+    try {
+        sentinel = lstatSync(path.join(volume, VOLUME_RESOURCE_SENTINEL));
+    }
+    catch { /* reported below */ }
+    if (!sentinel?.isFile()) {
+        fail(`fed volume ${volume} has no ${VOLUME_RESOURCE_SENTINEL}: start the organization once so the container initializes the volume, then refresh it`);
+    }
+};
+/** Absent is not an error (null); a symlink or file where a host directory belongs is a refusal, never a repair. */
+export const assertRealDirectory = (target, label) => {
+    let stat;
+    try {
+        stat = lstatSync(target);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    if (stat.isSymbolicLink()) {
+        fail(`${label} ${target} is a symlink to ${JSON.stringify(readlinkOrNull(target))}, not a directory; nothing on this host creates it, so the volume was written by something else. Refusing to operate through it.`);
+    }
+    if (!stat.isDirectory())
+        fail(`${label} ${target} is not a directory; refusing to operate on it`);
+    return stat;
+};
+/** rename(2) is atomic only within one filesystem; a cross-device "rename" is a copy readers can watch. */
+export const assertSameDevice = (volume, other, label) => {
+    const want = statSync(volume).dev, got = statSync(other).dev;
+    if (want !== got)
+        fail(`${label} ${other} is on device ${got} but the fed volume ${volume} is on device ${want}; every swap depends on rename(2), which cannot cross filesystems. Put ${label} on the volume's filesystem.`);
+};
+/** Host state must never live where an agent can write it: it decides what a root-run job deletes. */
+export const assertOutsideVolume = (volume, target, label) => {
+    const root = canonical(volume), scope = canonical(target);
+    // Whole path components: a sibling named `..state` is inside the volume, `../state` is not.
+    const escapes = (relative) => relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative);
+    if (!escapes(path.relative(root, scope)) || !escapes(path.relative(scope, root))) {
+        fail(`${label} ${scope} overlaps the fed volume ${root}; host state and staging must live outside the volume`);
+    }
+};
+const walkPostOrder = (root, visit) => {
+    const walk = (target) => {
+        const stat = lstatSync(target);
+        if (stat.isDirectory())
+            for (const name of readdirSync(target).sort())
+                walk(path.join(target, name));
+        visit(target, stat);
+    };
+    walk(root);
+};
+/**
+ * Ownership and read-only modes for a staged tree, before it is reachable. Never follows a symlink.
+ * The top directory stays 0755 so the one rename into the volume works for a non-root writer;
+ * `landTree` freezes it the moment it lands.
+ */
+export const ownAndFreeze = (stagingDir, { owner, volume }) => {
+    assertOutsideVolume(volume, stagingDir, "the staging tree");
+    const [uid, gid] = owner ? owner.split(":").map(Number) : [undefined, undefined];
+    walkPostOrder(stagingDir, (target, stat) => {
+        if (!stat.isFile() && !stat.isDirectory() && !stat.isSymbolicLink())
+            fail(`${target} is a special file; a fed volume carries only files, directories and symlinks`);
+        if (uid !== undefined && gid !== undefined)
+            lchownSync(target, uid, gid);
+        if (stat.isSymbolicLink())
+            return;
+        chmodSync(target, target === stagingDir ? 0o755 : (stat.mode & 0o7777) & ~0o222);
+    });
+};
+/** The one rename that makes a validated tree part of the volume, with its root frozen the moment it lands. */
+export const landTree = (stagingDir, treePath) => {
+    renameSync(stagingDir, treePath);
+    chmodSync(treePath, 0o555);
+};
+/** Every filesystem call the link swap makes, so a test can watch what the swap actually does. */
+export const LINK_OPS = Object.freeze({ lstat: lstatSync, readlink: readlinkSync, rename: renameSync, symlink: symlinkSync, unlink: unlinkSync });
+export const moveAsideCommand = (volume, target) => `mv -- ${target} ${path.join(path.dirname(volume), `${path.basename(target)}.planted`)}`;
+/**
+ * ATOMIC OR NOTHING. The live name is never unlinked: a new link is created under a temporary name outside
+ * the volume and rename(2)'d over the live one, so a reader resolving `current` sees the old target or
+ * the new one, never a missing name. The target is relative so it resolves the same on the host and at
+ * the container mount. Returns false when the link already points at `target`.
+ */
+export const pointCurrent = (volume, target, { ops = LINK_OPS, tmpDir, beforeRename }) => {
+    const live = path.join(volume, FEED_CURRENT_LINK);
+    let existing = null;
+    try {
+        existing = ops.lstat(live);
+    }
+    catch { /* absent: the first land */ }
+    if (existing && !existing.isSymbolicLink()) {
+        fail(`${live} is a real ${existing.isDirectory() ? "directory" : "file"}, not the host's link; nothing here deletes a name it did not write. Clear it with: ${moveAsideCommand(volume, live)}`);
+    }
+    if (existing && ops.readlink(live) === target)
+        return false;
+    const tmp = path.join(tmpDir, `.${FEED_CURRENT_LINK}.${process.pid}.tmp`);
+    try {
+        ops.unlink(tmp);
+    }
+    catch { /* no leftover from a crashed run */ }
+    ops.symlink(target, tmp);
+    beforeRename?.();
+    ops.rename(tmp, live);
+    return true;
+};
+/** Thaw and delete a tree OUTSIDE the volume. A recursive delete is only ever aimed at a real directory. */
+export const removeTree = (target, { volume }) => {
+    assertOutsideVolume(volume, target, "the tree being deleted");
+    let stat;
+    try {
+        stat = lstatSync(target);
+    }
+    catch {
+        return;
+    }
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+        rmSync(target, { force: true });
+        return;
+    }
+    const thaw = (directory) => {
+        chmodSync(directory, 0o700);
+        for (const entry of readdirSync(directory, { withFileTypes: true }))
+            if (entry.isDirectory())
+                thaw(path.join(directory, entry.name));
+    };
+    thaw(target);
+    rmSync(target, { recursive: true, force: true });
+};
+/** One rename out of the volume. Write on the moved directory is needed to change its parent. */
+export const parkTree = (treePath, trash, stamp) => {
+    assertRealDirectory(treePath, "the fed tree being retired");
+    const parked = path.join(trash, `${path.basename(treePath)}-${stamp}`);
+    chmodSync(treePath, 0o755);
+    renameSync(treePath, parked);
+    return parked;
+};
+/** Names at the volume root the host never writes. Reported, never deleted: they are evidence. */
+export const auditFeedRoot = (volume) => {
+    const findings = [];
+    for (const entry of readdirSync(volume, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+        if (!FEED_ROOT_NAMES.includes(entry.name))
+            findings.push(`${entry.name} is a name this host never writes at the volume root`);
+    }
+    return findings;
+};
+export const treeShape = (target) => {
+    let stat;
+    try {
+        stat = lstatSync(target);
+    }
+    catch {
+        return "missing";
+    }
+    return stat.isSymbolicLink() ? "symlink" : stat.isDirectory() ? "directory" : "file";
+};

package/dist/volume/feedLock.d.ts

@@ -0,0 +1,7 @@
+export declare const FEED_LOCK_FILE = "lock";
+export interface FeedLock {
+    path: string;
+    release: () => void;
+}
+/** Null when another live writer holds the lock. */
+export declare const acquireFeedLock: (stateDir: string) => FeedLock | null;

package/dist/volume/feedLock.js

@@ -0,0 +1,131 @@
+// ONE WRITER AT A TIME. Two refreshes racing are survivable (content is addressed by revision), but a
+// refresh racing a garbage collection or a re-land is a reader watching entries move. The lock is a
+// file created with O_EXCL in the host state directory, carrying the holder's pid and a random token.
+//
+// A crashed holder leaves the file behind, so a holder whose pid is gone on this host is stale. Reclaiming
+// it is serialized by a second O_EXCL guard file that also names its holder's pid. A guard is cleared only
+// when its own holder is provably dead, never by age: an age rule lets a live but slow reclaimer lose its
+// guard and then delete the lock a second reclaimer just took. Under the guard the lock is re-read and
+// removed only if it is still the exact stale bytes that were judged.
+//
+// A lock or guard that cannot be read as an owner (a crash between create and write) is not contention:
+// it is reported, with the one command that clears it, instead of reading as "busy" forever.
+//
+// Every job that must not interleave with a swap (a release that recreates containers, for example)
+// takes this same lock through `acquireFeedLock`.
+import { randomUUID } from "node:crypto";
+import { closeSync, mkdirSync, openSync, readFileSync, rmSync, unlinkSync, writeSync } from "node:fs";
+import { hostname } from "node:os";
+import path from "node:path";
+import { feedError } from "./feedLayout.js";
+export const FEED_LOCK_FILE = "lock";
+const processAlive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+};
+const createExclusive = (file, content) => {
+    let fd;
+    try {
+        fd = openSync(file, "wx", 0o600);
+    }
+    catch (error) {
+        if (error.code === "EEXIST")
+            return false;
+        throw error;
+    }
+    try {
+        writeSync(fd, content);
+    }
+    finally {
+        closeSync(fd);
+    }
+    return true;
+};
+const readOrNull = (file) => { try {
+    return readFileSync(file, "utf8");
+}
+catch {
+    return null;
+} };
+/** An owner record, allowing a live writer the moment between creating the file and writing it. */
+const readOwnerText = (file) => {
+    const first = readOrNull(file);
+    if (first === null || parseOwner(first) !== null)
+        return first;
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 100);
+    return readOrNull(file);
+};
+const parseOwner = (text) => {
+    try {
+        const value = JSON.parse(text ?? "");
+        return Number.isInteger(value.pid) && typeof value.host === "string" ? value : null;
+    }
+    catch {
+        return null;
+    }
+};
+/** Stale only when provably dead: same host and no such pid. An unreadable lock is a live one. */
+const isStale = (text) => {
+    const owner = parseOwner(text);
+    return owner !== null && owner.host === hostname() && !processAlive(owner.pid);
+};
+const ownerContent = () => `${JSON.stringify({ at: new Date().toISOString(), host: hostname(), pid: process.pid, token: randomUUID() })}\n`;
+const malformed = (file) => {
+    throw feedError(`the feed lock ${file} does not name a holder (a writer crashed while taking it); if no refresh is running, clear it with: rm -- ${file}`);
+};
+const reclaim = (file, judged) => {
+    const guard = `${file}.reclaim`, mine = ownerContent();
+    if (!createExclusive(guard, mine)) {
+        const held = readOwnerText(guard);
+        if (held === null)
+            return false;
+        if (parseOwner(held) === null)
+            malformed(guard);
+        if (!isStale(held))
+            return false;
+        // Clear the dead guard only if it is still the bytes judged dead, then compete for it again.
+        if (readOrNull(guard) !== held)
+            return false;
+        rmSync(guard, { force: true });
+        if (!createExclusive(guard, mine))
+            return false;
+    }
+    try {
+        if (readOrNull(file) !== judged)
+            return false;
+        unlinkSync(file);
+        return true;
+    }
+    finally {
+        if (readOrNull(guard) === mine)
+            rmSync(guard, { force: true });
+    }
+};
+/** Null when another live writer holds the lock. */
+export const acquireFeedLock = (stateDir) => {
+    mkdirSync(stateDir, { mode: 0o700, recursive: true });
+    const file = path.join(stateDir, FEED_LOCK_FILE);
+    const content = ownerContent();
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        if (createExclusive(file, content)) {
+            return {
+                path: file,
+                release: () => { if (readOrNull(file) === content)
+                    rmSync(file, { force: true }); }
+            };
+        }
+        const held = readOwnerText(file);
+        if (held === null)
+            continue;
+        if (parseOwner(held) === null)
+            malformed(file);
+        if (!isStale(held) || !reclaim(file, held))
+            return null;
+    }
+    return null;
+};

package/dist/volume/feedManifest.d.ts

@@ -0,0 +1,27 @@
+export declare const FEED_MANIFEST_VERSION = "spawnfile.volume-feed-manifest.v1";
+export type FeedManifestEntry = ["d", number] | ["f", number, number, number, string] | ["l", string];
+export interface FeedManifest {
+    entries: Record<string, FeedManifestEntry>;
+    files: number;
+    /** Physical tree name the manifest describes. */
+    tree: string;
+    version: typeof FEED_MANIFEST_VERSION;
+}
+export interface FeedManifestComparison {
+    changed: string[];
+    extra: string[];
+    missing: string[];
+    touched: string[];
+}
+export declare const sha256Hex: (value: string | Buffer) => string;
+/** Built from the frozen staged tree, so it records exactly the modes and bytes that land. */
+export declare const buildFeedManifest: (root: string, tree: string) => FeedManifest;
+/**
+ * `changed` is drift on its own evidence (kind, size, mode, link target, or a same-size rewrite whose
+ * digest moved); `touched` is a file whose mtime moved while its bytes did not.
+ */
+export declare const compareFeedManifest: (root: string, manifest: FeedManifest) => FeedManifestComparison;
+export declare const manifestDrift: (comparison: FeedManifestComparison) => string[];
+export declare const writeFeedManifest: (stateDir: string, manifest: FeedManifest) => void;
+export declare const readFeedManifest: (stateDir: string, tree: string) => FeedManifest | null;
+export declare const removeFeedManifest: (stateDir: string, tree: string) => void;

package/dist/volume/feedManifest.js

@@ -0,0 +1,123 @@
+// The land-time manifest of a fed tree: what the host put there, kept OUTSIDE the volume.
+//
+// WHY VERIFY INSTEAD OF PREVENT: the mount stays mutable (the container owns the volume root), and an
+// owner can always restore its own write bit, so nothing on the host can make the landed tree
+// tamper-proof. The honest guarantee is "cannot be changed unnoticed for longer than one refresh".
+//
+// EVERY FILE IS HASHED ON EVERY CHECK. A stat-only pass is cheaper, but an owner can rewrite a file with
+// equal-length bytes and put its mtime back, which no stat tuple notices. A fed tree is read in full by
+// agents anyway; reading it once per refresh is the price of a check that cannot be fooled that way.
+// Every walk here uses lstat and never descends a symlink: an agent can plant one.
+import { createHash } from "node:crypto";
+import { lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+export const FEED_MANIFEST_VERSION = "spawnfile.volume-feed-manifest.v1";
+export const sha256Hex = (value) => createHash("sha256").update(value).digest("hex");
+const fileDigest = (file) => sha256Hex(readFileSync(file));
+const walkShapes = (root) => {
+    const shapes = new Map();
+    const walk = (directory, prefix) => {
+        for (const name of readdirSync(directory).sort()) {
+            const full = path.join(directory, name), key = prefix ? `${prefix}/${name}` : name;
+            const stat = lstatSync(full);
+            const mode = stat.mode & 0o7777;
+            if (stat.isSymbolicLink())
+                shapes.set(key, ["l", readlinkSync(full)]);
+            else if (stat.isDirectory()) {
+                shapes.set(key, ["d", mode]);
+                walk(full, key);
+            }
+            else
+                shapes.set(key, ["f", stat.size, Math.round(stat.mtimeMs), mode]);
+        }
+    };
+    walk(root, "");
+    return shapes;
+};
+/** Built from the frozen staged tree, so it records exactly the modes and bytes that land. */
+export const buildFeedManifest = (root, tree) => {
+    const entries = {};
+    let files = 0;
+    for (const [key, shape] of walkShapes(root)) {
+        if (shape[0] === "f") {
+            entries[key] = [...shape, fileDigest(path.join(root, key))];
+            files += 1;
+        }
+        else
+            entries[key] = shape;
+    }
+    return { entries, files, tree, version: FEED_MANIFEST_VERSION };
+};
+/**
+ * `changed` is drift on its own evidence (kind, size, mode, link target, or a same-size rewrite whose
+ * digest moved); `touched` is a file whose mtime moved while its bytes did not.
+ */
+export const compareFeedManifest = (root, manifest) => {
+    const actual = walkShapes(root);
+    const result = { changed: [], extra: [], missing: [], touched: [] };
+    for (const [key, want] of Object.entries(manifest.entries)) {
+        const got = actual.get(key);
+        if (!got) {
+            result.missing.push(key);
+            continue;
+        }
+        if (got[0] !== want[0]) {
+            result.changed.push(key);
+            continue;
+        }
+        if (want[0] === "l") {
+            if (got[1] !== want[1])
+                result.changed.push(key);
+            continue;
+        }
+        if (want[0] === "d") {
+            if (got[1] !== want[1])
+                result.changed.push(key);
+            continue;
+        }
+        const file = got;
+        if (file[1] !== want[1] || file[3] !== want[3]) {
+            result.changed.push(key);
+            continue;
+        }
+        let digest = null;
+        try {
+            digest = fileDigest(path.join(root, key));
+        }
+        catch { /* unreadable is drift */ }
+        if (digest !== want[4])
+            result.changed.push(key);
+        else if (file[2] !== want[2])
+            result.touched.push(key);
+    }
+    for (const key of actual.keys())
+        if (!(key in manifest.entries))
+            result.extra.push(key);
+    return result;
+};
+export const manifestDrift = (comparison) => [
+    ...comparison.missing.map((key) => `${key} missing`),
+    ...comparison.extra.map((key) => `${key} added`),
+    ...comparison.changed.map((key) => `${key} changed`)
+];
+const manifestPath = (stateDir, tree) => path.join(stateDir, "manifests", `${tree}.json`);
+export const writeFeedManifest = (stateDir, manifest) => {
+    const file = manifestPath(stateDir, manifest.tree);
+    mkdirSync(path.dirname(file), { mode: 0o700, recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    rmSync(tmp, { force: true });
+    writeFileSync(tmp, `${JSON.stringify(manifest)}\n`, { mode: 0o600 });
+    renameSync(tmp, file);
+};
+export const readFeedManifest = (stateDir, tree) => {
+    try {
+        const value = JSON.parse(readFileSync(manifestPath(stateDir, tree), "utf8"));
+        return value?.version === FEED_MANIFEST_VERSION && value.tree === tree && value.entries ? value : null;
+    }
+    catch {
+        return null;
+    }
+};
+export const removeFeedManifest = (stateDir, tree) => {
+    rmSync(manifestPath(stateDir, tree), { force: true });
+};

package/dist/volume/feedPrepare.d.ts

@@ -0,0 +1,16 @@
+import { type FeedExec, type ResolvedFeedSource } from "./feedSource.js";
+import { type FeedTarget } from "./feedTarget.js";
+/** The source revision, composed with `include` and `prepare` when the feed declares them. */
+export declare const resolveFeedContent: (target: FeedTarget, { exec }: {
+    exec: FeedExec;
+}) => ResolvedFeedSource;
+/** Runs the declared prepare step in the staged tree; any failure lands nothing. */
+export declare const runFeedPrepare: (target: FeedTarget, tree: string, resolved: ResolvedFeedSource) => void;
+/**
+ * Stages the source, then the includes, then runs prepare, in `stagingDir` (existing, empty). Returns the
+ * revision of what was actually staged: a source or include edited mid-copy lands under its own revision.
+ */
+export declare const stageFeedContent: (target: FeedTarget, resolved: ResolvedFeedSource, stagingDir: string, { exec, log }: {
+    exec: FeedExec;
+    log: (line: string) => void;
+}) => ResolvedFeedSource;