spawnfile 0.1.14 → 0.1.18

package/dist/volume/feedRef.js

@@ -0,0 +1,117 @@
+// Moving refs and the freeze: which git ref a refresh lands, decided per refresh from the host's clock,
+// the declared rule and the host's own record -- never from anything inside the volume.
+//
+// WHY A PERIOD AND A REF NAME, NOT A COUNT OF ANYTHING. A freeze exists so readers who already started
+// on this period's content are not moved mid-work. Whether they started cannot be read from the volume
+// (agents can write and delete there, so any marker could freeze a period nobody used or thaw one they
+// did). The host answers it from two things it owns: the period (local date in the freeze time zone) it
+// stamped on the serving revision when it landed, and its clock. A spurious freeze keeps the period on
+// content it already had; a spurious thaw moves content under readers. Both rules err toward the freeze.
+//
+// WHY A MISSING REF IS A WAIT BEFORE THE CUTOFF. A dated ref does not exist until its producer cuts it,
+// so at period start "no such ref" is the normal state, not a failure; a timer that exits non-zero for
+// it every poll trains people to ignore the alarm. Until the freeze cutoff it is a clean wait; after it
+// (or with no freeze) it is a refusal.
+import { spawnSync } from "node:child_process";
+import { FEED_REF_PLACEHOLDER } from "../manifest/index.js";
+import { feedError } from "./feedLayout.js";
+const dateFormats = new Map();
+const clockFormats = new Map();
+const memo = (cache, zone, make) => {
+    if (!cache.has(zone))
+        cache.set(zone, make());
+    return cache.get(zone);
+};
+/** YYYY-MM-DD in `zone` at `now`. */
+export const feedLocalDate = (now, zone) => memo(dateFormats, zone, () => new Intl.DateTimeFormat("en-CA", { day: "2-digit", month: "2-digit", timeZone: zone, year: "numeric" })).format(now);
+/** HH:MM (24-hour, zero-padded, so a string compare orders it) in `zone` at `now`. */
+export const feedLocalClock = (now, zone) => memo(clockFormats, zone, () => new Intl.DateTimeFormat("en-GB", { hour: "2-digit", hourCycle: "h23", minute: "2-digit", timeZone: zone })).format(now);
+export const expandFeedRefTemplate = (template, now) => template.replace(FEED_REF_PLACEHOLDER, (_match, zone) => feedLocalDate(now, zone ?? "UTC"));
+/**
+ * The fed paths at `now`: each declared path with its date placeholders expanded at the same instant as the
+ * ref, so a dated ref and the dated directory inside it always name the same day. Undefined feeds the whole tree.
+ */
+export const expandFeedPaths = (paths, now) => paths?.map((entry) => expandFeedRefTemplate(entry, now));
+/** The period a landing at `now` belongs to; only a feed that declares a freeze has periods. */
+export const feedPeriod = (target, now) => target.freeze ? feedLocalDate(now, target.freeze.timezone) : undefined;
+const offsetFormats = new Map();
+const offsetMinutes = (instant, zone) => {
+    const name = memo(offsetFormats, zone, () => new Intl.DateTimeFormat("en-US", { timeZone: zone, timeZoneName: "longOffset" }))
+        .formatToParts(instant).find((part) => part.type === "timeZoneName")?.value ?? "GMT";
+    const match = /GMT([+-])(\d{2}):(\d{2})/u.exec(name);
+    return match ? (match[1] === "-" ? -1 : 1) * (Number(match[2]) * 60 + Number(match[3])) : 0;
+};
+/**
+ * The INSTANT `after` (HH:MM local) first arrives on `date` in `zone`. An instant, not a wall-clock
+ * compare: when clocks fall back the wall clock repeats an hour, and a wall-clock compare would thaw a
+ * volume that already froze. An ambiguous local time resolves to its first occurrence and a skipped one
+ * to the earlier candidate: both err toward freezing sooner.
+ */
+export const feedCutoffInstant = (date, after, zone) => {
+    const naive = Date.parse(`${date}T${after}:00Z`), span = 14 * 3_600_000;
+    const candidates = [...new Set([offsetMinutes(new Date(naive - span), zone), offsetMinutes(new Date(naive + span), zone)])]
+        .map((offset) => ({ instant: naive - offset * 60_000, offset }));
+    const valid = candidates.filter(({ instant, offset }) => offsetMinutes(new Date(instant), zone) === offset);
+    return new Date(Math.min(...(valid.length ? valid : candidates).map(({ instant }) => instant)));
+};
+const pastCutoff = (target, now) => target.freeze !== undefined &&
+    now.getTime() >= feedCutoffInstant(feedLocalDate(now, target.freeze.timezone), target.freeze.after, target.freeze.timezone).getTime();
+const runRefCommand = (target, command, repo) => {
+    const [file, ...args] = command.argv;
+    const result = spawnSync(file, args, {
+        cwd: command.cwd, encoding: "utf8",
+        env: { ...process.env, SPAWNFILE_FEED_REPO: repo, SPAWNFILE_FEED_RESOURCE: target.resourceId },
+        maxBuffer: 1024 * 1024, stdio: ["ignore", "pipe", "pipe"], timeout: command.timeoutMs
+    });
+    if (result.error?.code === "ETIMEDOUT")
+        throw feedError(`the feed ref command for ${target.resourceId} did not finish within ${Math.round(command.timeoutMs / 1000)}s`);
+    if (result.error)
+        throw feedError(`the feed ref command for ${target.resourceId} could not run: ${result.error.message}`);
+    if (result.status !== 0)
+        throw feedError(`the feed ref command for ${target.resourceId} failed (${result.signal ? `killed by ${result.signal}` : `exit ${result.status}`}): ${String(result.stderr).trim().slice(-300)}`);
+    return String(result.stdout).split("\n").map((line) => line.trim()).find((line) => line !== "") ?? null;
+};
+const refExists = (exec, repo, ref) => {
+    try {
+        exec("git", ["-C", repo, "rev-parse", "--verify", "--quiet", "--end-of-options", `${ref}^{commit}`]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * The ref this refresh lands: the fixed ref, or the rule's ref when it exists, else its fallback. A rule
+ * whose ref and fallback are both missing is a wait before the freeze cutoff and a refusal after it.
+ */
+export const chooseFeedRef = (target, { exec, now }) => {
+    const source = target.source, rule = target.refRule;
+    if (source.kind !== "git")
+        return { kind: "ref", ref: "" };
+    if (!rule)
+        return { kind: "ref", ref: source.ref };
+    const primary = rule.template !== undefined ? expandFeedRefTemplate(rule.template, now) : runRefCommand(target, rule.command, source.repo);
+    for (const candidate of [primary, rule.fallback]) {
+        if (candidate && refExists(exec, source.repo, candidate))
+            return { kind: "ref", ref: candidate };
+    }
+    const wanted = `${primary ? JSON.stringify(primary) : "the ref command printed no ref"}${rule.fallback ? ` (fallback ${JSON.stringify(rule.fallback)} is missing too)` : ""}`;
+    if (target.freeze && !pastCutoff(target, now)) {
+        return { kind: "waiting", reason: `waiting for ${wanted} in ${source.repo}: it is ${feedLocalClock(now, target.freeze.timezone)} ${target.freeze.timezone} and it is due by ${target.freeze.after}` };
+    }
+    throw feedError(`no ref to land for ${target.resourceId}: ${wanted} does not exist in ${source.repo}${target.freeze ? ` and the ${target.freeze.after} ${target.freeze.timezone} cutoff has passed` : ""}`);
+};
+/**
+ * Frozen: the host landed the serving revision in THIS period, the period's cutoff has passed, and the ref
+ * and paths chosen now are the ones it was landed from. A new period, a different ref name (the next
+ * period's ref appearing) or different expanded paths advance again.
+ */
+export const feedFrozen = (target, record, ref, now, paths) => {
+    if (!target.freeze || !record?.period || !pastCutoff(target, now))
+        return false;
+    if (record.period !== feedLocalDate(now, target.freeze.timezone))
+        return false;
+    const landed = record.identity.source;
+    return landed.kind !== "git" || target.source.kind !== "git"
+        || (landed.ref === ref && JSON.stringify(landed.paths ?? null) === JSON.stringify(paths ?? null));
+};

package/dist/volume/feedRefresh.d.ts

@@ -0,0 +1,15 @@
+import { type FeedRuntime } from "./feedLand.js";
+import { type FeedTarget } from "./feedTarget.js";
+/** `frozen` and `waiting` are clean holds: the volume keeps serving what it has (see feedRef.ts). */
+export type FeedRefreshStatus = "busy" | "current" | "frozen" | "landed" | "repaired" | "suspended" | "tampered" | "waiting";
+export interface FeedRefreshResult {
+    findings: string[];
+    previous: string | null;
+    revision: string | null;
+    status: FeedRefreshStatus;
+}
+/** Clean means nothing needs a human: exit 0. */
+export declare const feedResultClean: (result: FeedRefreshResult) => boolean;
+export declare const refreshVolumeFeed: (target: FeedTarget, runtime?: FeedRuntime) => FeedRefreshResult;
+/** Read-only: reports what a refresh would heal, changes nothing. Taken under the lock so a swap in flight is never misread. */
+export declare const verifyVolumeFeed: (target: FeedTarget, runtime?: Pick<FeedRuntime, "log">) => FeedRefreshResult;

package/dist/volume/feedRefresh.js

@@ -0,0 +1,187 @@
+// `spawnfile volume refresh` and `spawnfile volume verify`, under the single-writer lock.
+//
+// A refresh lands a new revision when the source moved. When it did not, it sweeps the volume against
+// the host record and heals what it can: re-lands a drifted tree from the source (beside it, as a new
+// generation), restores the `current` link, republishes the identity record. One revision is re-landed at
+// most `healLimit` times; the count survives clean refreshes and resets only when a new revision lands,
+// so tampering that alternates with quiet periods cannot buy unlimited repairs.
+import { mkdirSync } from "node:fs";
+import path from "node:path";
+import { assertFeedVolumeRoot, assertOutsideVolume, assertSameDevice, auditFeedRoot, feedTreeLink, LINK_OPS, pointCurrent } from "./feedLayout.js";
+import { buildFeedManifest, writeFeedManifest } from "./feedManifest.js";
+import { landFeed } from "./feedLand.js";
+import { publishFeedLanded, ensureFeedLanding } from "./feedLandings.js";
+import { acquireFeedLock } from "./feedLock.js";
+import { resolveFeedContent } from "./feedPrepare.js";
+import { readFeedLanded, writeFeedIdentity } from "./feedRecord.js";
+import { chooseFeedRef, expandFeedPaths, feedFrozen, feedPeriod } from "./feedRef.js";
+import { fetchFeedSource, hostExec } from "./feedSource.js";
+import { feedStagingDir, feedTrashDir } from "./feedTarget.js";
+import { sweepFeed } from "./feedVerify.js";
+/** Clean means nothing needs a human: exit 0. */
+export const feedResultClean = (result) => result.status === "busy" || result.status === "current" || result.status === "frozen" || result.status === "waiting" ||
+    (result.status === "landed" && result.findings.length === 0);
+/** Every check that decides where host state may be written runs before anything -- the lock included -- is written. */
+const confine = (target) => {
+    assertFeedVolumeRoot(target.volume);
+    assertOutsideVolume(target.volume, target.stateDir, "the feed state directory");
+};
+const prepare = (target) => {
+    for (const [label, directory] of [["the feed staging directory", feedStagingDir(target)], ["the feed trash directory", feedTrashDir(target)]]) {
+        mkdirSync(directory, { mode: 0o700, recursive: true });
+        assertSameDevice(target.volume, directory, label);
+    }
+};
+const withLock = (target, log, run) => {
+    confine(target);
+    const lock = acquireFeedLock(target.stateDir);
+    if (!lock) {
+        log(`another writer holds ${path.join(target.stateDir, "lock")}; nothing to do`);
+        return { findings: [], previous: null, revision: null, status: "busy" };
+    }
+    try {
+        return run();
+    }
+    finally {
+        lock.release();
+    }
+};
+const repairable = (sweep) => sweep.drift || sweep.relink || sweep.identity !== null;
+const heal = (target, record, sweep, runtime, { held = false } = {}) => {
+    const log = runtime.log ?? (() => undefined);
+    const base = { findings: sweep.findings, previous: record.revision, revision: record.revision };
+    for (const finding of sweep.findings)
+        log(`TAMPER: ${finding}`);
+    if (sweep.failed || sweep.planted || sweep.blocked)
+        return { ...base, status: "tampered" };
+    if (target.record || record.recording)
+        ensureFeedLanding(target, record, (runtime.now ?? (() => new Date()))());
+    if (sweep.drift) {
+        const cycles = record.heals[record.revision] ?? 0;
+        if (cycles >= target.healLimit) {
+            log(`auto-repair suspended: ${record.revision.slice(0, 12)} was re-landed ${cycles} times and drifted again; it resumes when a new revision lands`);
+            return { ...base, status: "suspended" };
+        }
+        const resolved = resolveFeedContent(target, { exec: runtime.exec ?? hostExec });
+        if (resolved.revision !== record.revision) {
+            // A held volume never advances, not even to repair itself.
+            if (held)
+                return { ...base, findings: [...sweep.findings, `the volume is held at ${record.revision.slice(0, 12)} and its source no longer reproduces it (now ${resolved.revision.slice(0, 12)}); not re-landing while held`], status: "tampered" };
+            landFeed(target, resolved, record, { period: feedPeriod(target, (runtime.now ?? (() => new Date()))()), runtime });
+            return { ...base, revision: resolved.revision, status: "repaired" };
+        }
+        log(`re-landing ${record.revision.slice(0, 12)} from the source beside the drifted tree`);
+        landFeed(target, resolved, record, { exact: held, force: true, heals: { ...record.heals, [record.revision]: cycles + 1 }, ...(record.period ? { period: record.period } : {}), runtime });
+        return { ...base, status: "repaired" };
+    }
+    let switchingAt;
+    if (sweep.relink)
+        pointCurrent(target.volume, feedTreeLink(record.tree), { ops: runtime.ops ?? LINK_OPS, tmpDir: feedStagingDir(target),
+            ...(target.record ? { beforeRename: () => { switchingAt = (runtime.now ?? (() => new Date()))().toISOString(); } } : {}) });
+    const reestablished = sweep.relink && target.record ? (runtime.now ?? (() => new Date()))() : undefined;
+    let next = record;
+    if (sweep.identity || reestablished) {
+        const identity = reestablished ? { ...record.identity, landed_at: reestablished.toISOString() } : record.identity;
+        next = { ...record, identity, identity_sha256: writeFeedIdentity(target.volume, identity, { owner: target.owner, tmpDir: feedStagingDir(target) }) };
+    }
+    publishFeedLanded(target, next, reestablished ?? (runtime.now ?? (() => new Date()))(), record, switchingAt);
+    const after = sweepFeed(target, next);
+    if (repairable(after))
+        return { findings: [...sweep.findings, ...after.findings.map((finding) => `still after repair: ${finding}`)], previous: record.revision, revision: record.revision, status: "tampered" };
+    return { ...base, status: repairable(sweep) && sweep.unknown.length === 0 ? "repaired" : "tampered" };
+};
+/**
+ * Same bytes under a new period or ref name: the serving revision is now this period's content, so its
+ * period and provenance are re-stamped (record, then the identity agents read). Without it a ref that
+ * moved to identical content would never count as landed this period, and the freeze would never hold.
+ */
+const adopt = (target, record, resolved, period, runtime) => {
+    const source = resolved.provenance;
+    if (target.record || record.recording)
+        ensureFeedLanding(target, record, (runtime.now ?? (() => new Date()))());
+    if ((!period && !target.record) || (record.period === period && JSON.stringify(record.identity.source) === JSON.stringify(source))) {
+        if (target.record)
+            ensureFeedLanding(target, record, (runtime.now ?? (() => new Date()))());
+        return;
+    }
+    const now = target.record ? (runtime.now ?? (() => new Date()))() : undefined;
+    const identity = { ...record.identity, source, ...(now ? { landed_at: now.toISOString() } : {}) };
+    const identitySha = writeFeedIdentity(target.volume, identity, { owner: target.owner, tmpDir: feedStagingDir(target) });
+    publishFeedLanded(target, { ...record, identity, identity_sha256: identitySha, period }, now ?? new Date(), record);
+};
+/** A held volume (frozen, or waiting for a ref that does not exist yet) keeps serving what it has; it is still verified and healed. */
+const holdLocked = (target, record, held, runtime) => {
+    const sweep = sweepFeed(target, record);
+    if (sweep.findings.length)
+        return heal(target, record, sweep, runtime, { held: true });
+    if (target.record)
+        ensureFeedLanding(target, record, (runtime.now ?? (() => new Date()))());
+    (runtime.log ?? (() => undefined))(`${held}: serving ${record.revision.slice(0, 12)}`);
+    return { findings: [], previous: record.revision, revision: record.revision, status: held };
+};
+const refreshLocked = (target, runtime) => {
+    const log = runtime.log ?? (() => undefined), exec = runtime.exec ?? hostExec, now = (runtime.now ?? (() => new Date()))();
+    prepare(target);
+    fetchFeedSource(target.source, { exec });
+    const { reason, record } = readFeedLanded(target.stateDir);
+    if (reason)
+        log(`ignoring the host record: ${reason}; treating this volume as carrying nothing`);
+    const choice = chooseFeedRef(target, { exec, now });
+    let concrete = target;
+    // Path templates expand at the same instant the ref was chosen from.
+    const paths = target.source.kind === "git" ? expandFeedPaths(target.source.paths, now) : undefined;
+    if (choice.kind === "waiting") {
+        log(choice.reason);
+        if (!record)
+            return { findings: [], previous: null, revision: null, status: "waiting" };
+    }
+    else if (target.source.kind === "git")
+        concrete = { ...target, source: { ...target.source, ...(paths ? { paths } : {}), ref: choice.ref } };
+    const frozen = choice.kind === "ref" && feedFrozen(target, record, choice.ref, now, paths);
+    if (record && (choice.kind === "waiting" || frozen)) {
+        if (frozen)
+            log(`frozen: ${record.revision.slice(0, 12)} was landed this period and the ${target.freeze.after} ${target.freeze.timezone} cutoff has passed`);
+        const landed = record.identity.source;
+        // Held at its own commit and the paths it landed, so a heal reproduces what is served and never what
+        // the ref moved to or what a path template expands to today.
+        const held = landed.kind === "git" && target.source.kind === "git"
+            ? { ...target, source: { fetch: target.source.fetch, kind: "git", label: landed.ref, ...(landed.paths ? { paths: landed.paths } : {}), ref: landed.commit, repo: target.source.repo } } : target;
+        return holdLocked(held, record, frozen ? "frozen" : "waiting", runtime);
+    }
+    const resolved = resolveFeedContent(concrete, { exec });
+    const period = feedPeriod(target, now);
+    if (!record || record.revision !== resolved.revision) {
+        log(`refresh needed: ${record ? `${record.revision.slice(0, 12)} -> ${resolved.revision.slice(0, 12)}` : `nothing landed -> ${resolved.revision.slice(0, 12)}`}`);
+        // A new revision does not excuse what else is in the volume: the root is audited on every landing.
+        const findings = auditFeedRoot(target.volume);
+        const landed = landFeed(concrete, resolved, record, { ...(period ? { period } : {}), runtime });
+        findings.push(...landed.unknownTrees.map((name) => `trees/${name} is not a tree this host landed`));
+        for (const finding of findings)
+            log(`TAMPER: ${finding}`);
+        return { findings, previous: record?.revision ?? null, revision: landed.revision, status: "landed" };
+    }
+    const sweep = sweepFeed(concrete, record);
+    if (!sweep.findings.length) {
+        // Same bytes, moved mtime: somebody touched the mount without changing content. Re-stamp the manifest.
+        if (sweep.touched.length)
+            writeFeedManifest(target.stateDir, buildFeedManifest(path.join(target.volume, feedTreeLink(record.tree)), record.tree));
+        adopt(concrete, record, resolved, period, runtime);
+        log(`already current: ${record.revision.slice(0, 12)}`);
+        return { findings: [], previous: record.revision, revision: record.revision, status: "current" };
+    }
+    const healed = heal(concrete, record, sweep, runtime);
+    // A repair of the content this period chose is this period's landing too.
+    const after = healed.status === "repaired" ? readFeedLanded(target.stateDir).record : null;
+    if (after && after.revision === resolved.revision)
+        adopt(concrete, after, resolved, period, runtime);
+    return healed;
+};
+export const refreshVolumeFeed = (target, runtime = {}) => withLock(target, runtime.log ?? (() => undefined), () => refreshLocked(target, runtime));
+/** Read-only: reports what a refresh would heal, changes nothing. Taken under the lock so a swap in flight is never misread. */
+export const verifyVolumeFeed = (target, runtime = {}) => withLock(target, runtime.log ?? (() => undefined), () => {
+    const { reason, record } = readFeedLanded(target.stateDir);
+    if (!record)
+        return { findings: [reason ?? "nothing has been landed in this volume yet"], previous: null, revision: null, status: "tampered" };
+    const sweep = sweepFeed(target, record);
+    return { findings: sweep.findings, previous: record.revision, revision: record.revision, status: sweep.findings.length ? "tampered" : "current" };
+});

package/dist/volume/feedSource.d.ts

@@ -0,0 +1,66 @@
+export type FeedSourceSpec = 
+/** `label` names the ref in provenance when `ref` is a pinned commit (a held volume re-landing what it serves). */
+{
+    fetch: boolean;
+    kind: "git";
+    label?: string;
+    paths?: string[];
+    ref: string;
+    repo: string;
+} | {
+    directory: string;
+    kind: "directory";
+};
+/** What `include` and `prepare` added on top of the source; its digest, not the source's, is the revision. */
+export interface FeedPreparedProvenance {
+    include: Array<{
+        digest: string;
+        to: string;
+    }>;
+    prepare: {
+        command: string[];
+        image: string | null;
+        network: boolean | null;
+        platform: string | null;
+    } | null;
+    source_revision: string;
+}
+export type FeedProvenance = {
+    commit: string;
+    kind: "git";
+    paths: string[] | null;
+    prepared?: FeedPreparedProvenance;
+    ref: string;
+} | {
+    kind: "directory";
+    prepared?: FeedPreparedProvenance;
+};
+export interface ResolvedFeedSource {
+    provenance: FeedProvenance;
+    revision: string;
+}
+export type FeedExec = (command: string, args: string[], options?: {
+    cwd?: string;
+    input?: Buffer;
+}) => Buffer;
+/**
+ * Stdin is closed unless input is given: tar once exited 0 having extracted nothing because its archive
+ * was silently discarded, so `stageFeedSource` also refuses an empty extraction.
+ */
+export declare const hostExec: FeedExec;
+/** Sorted (path, kind, executable bit, bytes) of a directory tree; symlinks by their target text. */
+export declare const digestDirectory: (root: string) => string;
+export declare const fetchFeedSource: (spec: FeedSourceSpec, { exec }?: {
+    exec?: FeedExec;
+}) => void;
+export declare const resolveFeedSource: (spec: FeedSourceSpec, { exec }?: {
+    exec?: FeedExec;
+}) => ResolvedFeedSource;
+/**
+ * Copies the source into `stagingDir` (which must exist and be empty) and returns the revision of what
+ * was actually staged. For a directory that is re-derived from the copy, so a source edited mid-copy
+ * lands as the bytes that were copied, under their own revision, never as a mislabelled mix.
+ */
+export declare const stageFeedSource: (spec: FeedSourceSpec, resolved: ResolvedFeedSource, stagingDir: string, { exec }?: {
+    exec?: FeedExec;
+}) => ResolvedFeedSource;

package/dist/volume/feedSource.js

@@ -0,0 +1,104 @@
+// Where a fed volume's content comes from, and how it is copied into a private staging directory.
+//
+// A revision is CONTENT-addressed: a commit that does not change the fed paths, or a directory whose
+// bytes did not move, resolves to the same revision and lands nothing.
+import { execFileSync } from "node:child_process";
+import { cpSync, lstatSync, readFileSync, readdirSync, readlinkSync } from "node:fs";
+import path from "node:path";
+import { feedError } from "./feedLayout.js";
+import { sha256Hex } from "./feedManifest.js";
+/**
+ * Stdin is closed unless input is given: tar once exited 0 having extracted nothing because its archive
+ * was silently discarded, so `stageFeedSource` also refuses an empty extraction.
+ */
+export const hostExec = (command, args, options = {}) => execFileSync(command, args, {
+    cwd: options.cwd,
+    input: options.input,
+    maxBuffer: 1024 * 1024 * 1024,
+    stdio: [options.input === undefined ? "ignore" : "pipe", "pipe", "pipe"]
+});
+const gitOut = (exec, repo, args) => exec("git", ["-C", repo, ...args]).toString().trim();
+/** Sorted (path, kind, executable bit, bytes) of a directory tree; symlinks by their target text. */
+export const digestDirectory = (root) => {
+    const lines = [];
+    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);
+            if (stat.isSymbolicLink())
+                lines.push(`l ${JSON.stringify(key)} ${JSON.stringify(readlinkSync(full))}`);
+            else if (stat.isDirectory()) {
+                lines.push(`d ${JSON.stringify(key)}`);
+                walk(full, key);
+            }
+            else if (stat.isFile())
+                lines.push(`f ${JSON.stringify(key)} ${stat.mode & 0o111 ? "x" : "-"} ${sha256Hex(readFileSync(full))}`);
+            else
+                throw feedError(`${full} is a special file; a fed volume carries only files, directories and symlinks`);
+        }
+    };
+    walk(root, "");
+    return sha256Hex(`directory\n${lines.join("\n")}\n`);
+};
+export const fetchFeedSource = (spec, { exec = hostExec } = {}) => {
+    if (spec.kind !== "git" || !spec.fetch)
+        return;
+    try {
+        exec("git", ["-C", spec.repo, "fetch", "--prune", "--quiet", "origin"]);
+    }
+    catch (error) {
+        throw feedError(`could not fetch the feed repository ${spec.repo}: ${String(error.message).trim().slice(0, 300)}`);
+    }
+};
+export const resolveFeedSource = (spec, { exec = hostExec } = {}) => {
+    if (spec.kind === "directory") {
+        let stat;
+        try {
+            stat = lstatSync(spec.directory);
+        }
+        catch {
+            throw feedError(`feed directory ${spec.directory} does not exist`);
+        }
+        if (!stat.isDirectory())
+            throw feedError(`feed directory ${spec.directory} is not a directory`);
+        return { provenance: { kind: "directory" }, revision: digestDirectory(spec.directory) };
+    }
+    let commit;
+    const trees = [];
+    try {
+        commit = gitOut(exec, spec.repo, ["rev-parse", "--verify", "--end-of-options", `${spec.ref}^{commit}`]);
+        for (const entry of spec.paths ?? [""]) {
+            const tree = gitOut(exec, spec.repo, ["rev-parse", "--verify", "--end-of-options", entry ? `${commit}:${entry}` : `${commit}^{tree}`]);
+            if (gitOut(exec, spec.repo, ["cat-file", "-t", tree]) !== "tree")
+                throw new Error(`${entry} is not a directory at ${commit.slice(0, 12)}`);
+            trees.push(`${entry}\0${tree}`);
+        }
+    }
+    catch (error) {
+        throw feedError(`cannot resolve ${spec.ref}${spec.paths ? ` (${spec.paths.join(", ")})` : ""} in ${spec.repo}: ${String(error.message).trim().slice(0, 300)}`);
+    }
+    return {
+        provenance: { commit, kind: "git", paths: spec.paths ?? null, ref: spec.label ?? spec.ref },
+        revision: sha256Hex(`git\n${trees.join("\n")}\n`)
+    };
+};
+/**
+ * Copies the source into `stagingDir` (which must exist and be empty) and returns the revision of what
+ * was actually staged. For a directory that is re-derived from the copy, so a source edited mid-copy
+ * lands as the bytes that were copied, under their own revision, never as a mislabelled mix.
+ */
+export const stageFeedSource = (spec, resolved, stagingDir, { exec = hostExec } = {}) => {
+    if (spec.kind === "directory") {
+        cpSync(spec.directory, stagingDir, { errorOnExist: true, force: false, preserveTimestamps: true, recursive: true, verbatimSymlinks: true });
+        if (readdirSync(stagingDir).length === 0)
+            throw feedError(`feed directory ${spec.directory} is empty; a fed volume never serves nothing`);
+        return { ...resolved, revision: digestDirectory(stagingDir) };
+    }
+    const provenance = resolved.provenance;
+    const archive = exec("git", ["-C", spec.repo, "archive", "--format=tar", provenance.commit, ...(spec.paths ? ["--", ...spec.paths] : [])]);
+    exec("tar", ["-x", "-C", stagingDir], { input: archive });
+    if (readdirSync(stagingDir).length === 0) {
+        throw feedError(`extracting ${provenance.commit.slice(0, 12)} produced an empty tree in ${stagingDir}; a fed volume never serves nothing`);
+    }
+    return resolved;
+};

package/dist/volume/feedTarget.d.ts

@@ -0,0 +1,70 @@
+import type { FeedSourceSpec } from "./feedSource.js";
+export declare const DEFAULT_FEED_KEEP = 1;
+export declare const DEFAULT_FEED_HEAL_LIMIT = 3;
+export declare const DEFAULT_FEED_VALIDATE_TIMEOUT_MS: number;
+export declare const DEFAULT_FEED_PREPARE_TIMEOUT_MS: number;
+export declare const DEFAULT_FEED_REF_COMMAND_TIMEOUT_MS = 60000;
+/** A command run inside the staged tree before validation: in a digest-pinned image on `platform`, or on the host. */
+export type FeedPrepare = {
+    command: string[];
+    dockerCommand: string;
+    image: string;
+    kind: "image";
+    network: boolean;
+    platform: string;
+    timeoutMs: number;
+} | {
+    command: string[];
+    kind: "host";
+    timeoutMs: number;
+};
+/** A git ref resolved per refresh: a template expanded at the host clock, or a command printing a ref. */
+export interface FeedRefRule {
+    command?: {
+        argv: string[];
+        cwd: string;
+        timeoutMs: number;
+    };
+    fallback?: string;
+    template?: string;
+}
+/** Everything a refresh or verify needs, resolved from the manifest and the host. */
+export interface FeedTarget {
+    /** Once local time passes `after`, a volume that already landed this period's ref stops advancing. */
+    freeze?: {
+        after: string;
+        timezone: string;
+    };
+    /** Re-lands of one revision before auto-repair is suspended. */
+    healLimit: number;
+    /** Host directories copied into the staged tree at `to` (tree-relative) before `prepare`. */
+    include?: Array<{
+        from: string;
+        to: string;
+    }>;
+    /** Retired trees kept beside the serving one, so a reader mid-read survives at least one swap. */
+    keep: number;
+    owner?: string;
+    prepare?: FeedPrepare;
+    /** Landing-history retention for recording agents consuming this volume; absent means no log I/O. */
+    record?: {
+        keepMs: number;
+    };
+    /** Replaces `source.ref` of a git source with a ref chosen on every refresh. */
+    refRule?: FeedRefRule;
+    resourceId: string;
+    source: FeedSourceSpec;
+    /** Host state outside the volume, on its filesystem: record, manifests, staging, trash, lock, prepare cache. */
+    stateDir: string;
+    validate?: {
+        command: string[];
+        cwd: string;
+        timeoutMs: number;
+    };
+    /** Host path of the volume's content root. */
+    volume: string;
+    volumeName: string;
+}
+export declare const feedStagingDir: (target: FeedTarget) => string;
+export declare const feedTrashDir: (target: FeedTarget) => string;
+export declare const feedPreparedDir: (target: FeedTarget) => string;

package/dist/volume/feedTarget.js

@@ -0,0 +1,9 @@
+import path from "node:path";
+export const DEFAULT_FEED_KEEP = 1;
+export const DEFAULT_FEED_HEAL_LIMIT = 3;
+export const DEFAULT_FEED_VALIDATE_TIMEOUT_MS = 10 * 60_000;
+export const DEFAULT_FEED_PREPARE_TIMEOUT_MS = 30 * 60_000;
+export const DEFAULT_FEED_REF_COMMAND_TIMEOUT_MS = 60_000;
+export const feedStagingDir = (target) => path.join(target.stateDir, "staging");
+export const feedTrashDir = (target) => path.join(target.stateDir, "trash");
+export const feedPreparedDir = (target) => path.join(target.stateDir, "prepared");

package/dist/volume/feedTestKit.d.ts

@@ -0,0 +1,11 @@
+import { type FeedTarget } from "./feedTarget.js";
+export interface FeedFixture {
+    cleanup: () => void;
+    root: string;
+    source: string;
+    target: FeedTarget;
+    volume: string;
+}
+/** A volume shaped like one a container has initialized: mode 0755 with its resource sentinel. */
+export declare const createFeedFixture: (overrides?: Partial<FeedTarget>) => FeedFixture;
+export declare const writeSourceFiles: (directory: string, files: Record<string, string>) => void;

package/dist/volume/feedTestKit.js

@@ -0,0 +1,45 @@
+import { chmodSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { VOLUME_RESOURCE_SENTINEL } from "./feedLayout.js";
+import { DEFAULT_FEED_HEAL_LIMIT } from "./feedTarget.js";
+/** A volume shaped like one a container has initialized: mode 0755 with its resource sentinel. */
+export const createFeedFixture = (overrides = {}) => {
+    const root = mkdtempSync(path.join(tmpdir(), "spawnfile-feed-"));
+    const volume = path.join(root, "volume", "_data"), source = path.join(root, "source");
+    mkdirSync(volume, { recursive: true });
+    chmodSync(volume, 0o755);
+    writeFileSync(path.join(volume, VOLUME_RESOURCE_SENTINEL), "sha256:fixture\n", { mode: 0o644 });
+    mkdirSync(source);
+    writeFileSync(path.join(source, "a.txt"), "alpha\n");
+    const target = {
+        healLimit: DEFAULT_FEED_HEAL_LIMIT, keep: 1, resourceId: "shared-data", source: { directory: source, kind: "directory" },
+        stateDir: path.join(root, "volume", "spawnfile-feed"), volume, volumeName: "shared-data-vol", ...overrides
+    };
+    const cleanup = () => {
+        // Frozen trees are a-w; restore write so the temp root can be removed.
+        const thaw = (directory) => {
+            try {
+                if (!lstatSync(directory).isDirectory())
+                    return;
+                chmodSync(directory, 0o755);
+            }
+            catch {
+                return;
+            }
+            for (const name of readdirSync(directory))
+                thaw(path.join(directory, name));
+        };
+        thaw(root);
+        rmSync(root, { force: true, recursive: true });
+    };
+    return { cleanup, root, source, target, volume };
+};
+export const writeSourceFiles = (directory, files) => {
+    rmSync(directory, { force: true, recursive: true });
+    mkdirSync(directory, { recursive: true });
+    for (const [name, content] of Object.entries(files)) {
+        mkdirSync(path.dirname(path.join(directory, name)), { recursive: true });
+        writeFileSync(path.join(directory, name), content);
+    }
+};

package/dist/volume/feedVerify.d.ts

@@ -0,0 +1,18 @@
+import { type FeedLandedRecord } from "./feedRecord.js";
+import type { FeedTarget } from "./feedTarget.js";
+export interface FeedSweep {
+    blocked: boolean;
+    drift: boolean;
+    failed: boolean;
+    findings: string[];
+    identity: "forged" | "missing" | null;
+    planted: boolean;
+    relink: boolean;
+    touched: string[];
+    unknown: string[];
+}
+/**
+ * NO EXCEPTION LEAVES THIS SWEEP WITHOUT A FINDING. A sweep that throws is a volume nothing verified,
+ * and it must read as "not clean", never as a quiet exit.
+ */
+export declare const sweepFeed: (target: FeedTarget, record: FeedLandedRecord) => FeedSweep;