spawnfile 0.1.17 → 0.1.18

package/dist/volume/feedPrepare.js

@@ -0,0 +1,228 @@
+// `include` and `prepare`: what a feed adds to the source in staging, before validation and freeze.
+//
+// THE REVISION DESCRIBES WHAT IS SERVED. With either declared, the revision is the digest of the source
+// revision, every included directory's digest and the prepare recipe (command, image digest, platform,
+// network), so it is decided WITHOUT running anything: an unchanged refresh compares digests and lands
+// nothing. The prepare output itself is not hashed into the revision (an install is not byte-reproducible
+// across registries and time); it is hashed into the land-time manifest like every other tree, so verify
+// still catches any change after landing.
+//
+// WHY A PINNED IMAGE. Native modules are built for the platform that installs them; installing on the
+// host would serve host binaries to containers on another libc or arch. A digest-pinned image on the
+// target platform is the same rule the `dependencies` bundle follows. `host: true` is the explicit
+// opt-out for steps that are platform-neutral (copying assets).
+//
+// WHY A CACHE. A heal re-lands the same revision from the source; without a cache that is a full
+// reinstall at the moment the volume is under attack. The cache is keyed by the revision (which already
+// covers tree + recipe + image + platform), lives in host state, and is re-verified by digest on every use.
+import { spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { cpSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { containerArgv } from "../compiler/workspaceBundleRun.js";
+import { feedError, removeTree } from "./feedLayout.js";
+import { sha256Hex } from "./feedManifest.js";
+import { digestDirectory, resolveFeedSource, stageFeedSource } from "./feedSource.js";
+import { feedPreparedDir } from "./feedTarget.js";
+const PREPARE_CACHE_KEEP = 2;
+const CONTAINER_TREE = "/spawnfile/feed";
+const preparedOf = (target) => target.include !== undefined || target.prepare !== undefined;
+const prepareRecipe = (target) => {
+    const prepare = target.prepare;
+    if (!prepare)
+        return null;
+    return prepare.kind === "image"
+        ? { command: prepare.command, image: prepare.image, network: prepare.network, platform: prepare.platform }
+        : { command: prepare.command, image: null, network: null, platform: null };
+};
+const compose = (target, source, include) => {
+    const prepared = { include, prepare: prepareRecipe(target), source_revision: source.revision };
+    return { provenance: { ...source.provenance, prepared }, revision: sha256Hex(`prepared\n${JSON.stringify(prepared)}\n`) };
+};
+const includeDigest = (from) => {
+    let stat;
+    try {
+        stat = lstatSync(from);
+    }
+    catch {
+        throw feedError(`feed include directory ${from} does not exist`);
+    }
+    if (!stat.isDirectory())
+        throw feedError(`feed include ${from} is not a directory`);
+    return digestDirectory(from);
+};
+/** The source revision, composed with `include` and `prepare` when the feed declares them. */
+export const resolveFeedContent = (target, { exec }) => {
+    const source = resolveFeedSource(target.source, { exec });
+    if (!preparedOf(target))
+        return source;
+    return compose(target, source, (target.include ?? []).map(({ from, to }) => ({ digest: includeDigest(from), to })));
+};
+/** The source half of a composed revision, which is what staging the source must reproduce. */
+const sourcePart = (resolved) => {
+    const { prepared, ...provenance } = resolved.provenance;
+    return { provenance, revision: prepared?.source_revision ?? resolved.revision };
+};
+/** Every component of `to` below the staged root must be absent or a real directory: never follow a staged symlink out. */
+const stageInclude = (stagingDir, from, to) => {
+    let parent = stagingDir;
+    const segments = to.split("/");
+    for (const [index, segment] of segments.entries()) {
+        const next = path.join(parent, segment);
+        let stat;
+        try {
+            stat = lstatSync(next);
+        }
+        catch {
+            stat = null;
+        }
+        if (index === segments.length - 1) {
+            if (stat)
+                throw feedError(`feed include target ${to} already exists in the fed tree; an include adds files, it never replaces them`);
+        }
+        else if (stat && !stat.isDirectory()) {
+            throw feedError(`feed include target ${to} passes through ${segments.slice(0, index + 1).join("/")}, which is not a directory in the fed tree`);
+        }
+        else if (!stat)
+            mkdirSync(next);
+        parent = next;
+    }
+    const destination = path.join(stagingDir, to);
+    cpSync(from, destination, { errorOnExist: true, force: false, preserveTimestamps: true, recursive: true, verbatimSymlinks: true });
+    return digestDirectory(destination);
+};
+const TIMEOUT_MARK = "SPAWNFILE_PREPARE_TIMEOUT", SPAWN_MARK = "SPAWNFILE_PREPARE_SPAWN_ERROR";
+/**
+ * spawnSync cannot kill a process group, and a child that ignores SIGTERM (or a descendant holding the
+ * pipes) would outlive its timeout while the refresh holds the lock. So the step runs under a tiny
+ * supervisor that starts it in its own process group and SIGKILLs the whole group on timeout and on exit.
+ */
+const SUPERVISOR = [
+    'const { spawn } = require("node:child_process");',
+    "const [ms, file, ...args] = process.argv.slice(1);",
+    'const child = spawn(file, args, { detached: true, stdio: "inherit" });',
+    'const killGroup = () => { try { process.kill(-child.pid, "SIGKILL"); } catch {} };',
+    "let timedOut = false;",
+    "const timer = setTimeout(() => { timedOut = true; killGroup(); }, Number(ms));",
+    `child.on("error", (error) => { clearTimeout(timer); console.error("${SPAWN_MARK} " + error.message); process.exit(127); });`,
+    `child.on("exit", (code, signal) => { clearTimeout(timer); killGroup(); if (timedOut) { console.error("${TIMEOUT_MARK}"); process.exit(124); } if (signal) console.error("killed by " + signal); process.exit(code === null ? 128 : code); });`
+].join("\n");
+const superviseSync = (argv, timeoutMs, options) => spawnSync(process.execPath, ["-e", SUPERVISOR, String(timeoutMs), ...argv], {
+    ...options, encoding: "utf8", killSignal: "SIGKILL", maxBuffer: 64 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"],
+    // Backstop only: the supervisor enforces the real deadline on the whole group.
+    timeout: timeoutMs + 10_000
+});
+const failure = (result, timeoutMs) => {
+    const stderr = String(result.stderr ?? "");
+    if (stderr.includes(TIMEOUT_MARK) || result.error?.code === "ETIMEDOUT")
+        return `did not finish within ${Math.round(timeoutMs / 1000)}s and was killed`;
+    if (result.error)
+        return `could not run: ${result.error.message}`;
+    if (stderr.includes(SPAWN_MARK))
+        return `could not run: ${stderr.slice(stderr.indexOf(SPAWN_MARK) + SPAWN_MARK.length).trim()}`;
+    if (result.status === 0)
+        return null;
+    const output = `${stderr}${String(result.stdout ?? "")}`.trim().split("\n").slice(-20).join("\n");
+    return `exited ${result.status}${output ? `:\n${output}` : ""}`;
+};
+/** Runs the declared prepare step in the staged tree; any failure lands nothing. */
+export const runFeedPrepare = (target, tree, resolved) => {
+    const prepare = target.prepare;
+    if (!prepare)
+        return;
+    const env = { SPAWNFILE_FEED_RESOURCE: target.resourceId, SPAWNFILE_FEED_REVISION: resolved.revision };
+    let result;
+    if (prepare.kind === "host") {
+        result = superviseSync(prepare.command, prepare.timeoutMs, { cwd: tree, env: { ...process.env, ...env, SPAWNFILE_FEED_TREE: tree } });
+    }
+    else {
+        const name = `spawnfile-feed-${randomBytes(8).toString("hex")}`;
+        result = superviseSync(containerArgv({
+            argv: prepare.command, dockerCommand: prepare.dockerCommand, env: { ...env, SPAWNFILE_FEED_TREE: CONTAINER_TREE }, image: prepare.image,
+            mounts: [[tree, CONTAINER_TREE]], name, network: prepare.network, platform: prepare.platform, workdir: CONTAINER_TREE
+        }), prepare.timeoutMs, {});
+        // Killing the client does not stop its container: remove it, bounded, before reporting.
+        if (result.status !== 0)
+            superviseSync([prepare.dockerCommand, "rm", "--force", name], 30_000, {});
+    }
+    const why = failure(result, prepare.timeoutMs);
+    if (why)
+        throw feedError(`the feed prepare command for ${target.resourceId} ${why}; nothing was landed`);
+    if (readdirSync(tree).length === 0)
+        throw feedError(`the feed prepare command for ${target.resourceId} left an empty tree; a fed volume never serves nothing`);
+};
+const cachePaths = (target, revision) => ({ marker: path.join(feedPreparedDir(target), `${revision}.json`), tree: path.join(feedPreparedDir(target), revision) });
+/** Copies a cached prepared tree into staging; true only when the copy's digest is the one recorded at store time. */
+const restoreCached = (target, revision, stagingDir, log) => {
+    const { marker, tree } = cachePaths(target, revision);
+    let digest;
+    try {
+        digest = JSON.parse(readFileSync(marker, "utf8")).digest;
+    }
+    catch {
+        return false;
+    }
+    try {
+        if (!lstatSync(tree).isDirectory())
+            return false;
+        cpSync(tree, stagingDir, { errorOnExist: true, force: false, preserveTimestamps: true, recursive: true, verbatimSymlinks: true });
+        if (digestDirectory(stagingDir) === digest) {
+            log(`reused the prepared tree for ${revision.slice(0, 12)} from the cache`);
+            return true;
+        }
+    }
+    catch { /* fall through to a fresh build */ }
+    log(`the cached prepared tree for ${revision.slice(0, 12)} no longer matches its digest; preparing it again`);
+    removeTree(tree, { volume: target.volume });
+    rmSync(marker, { force: true });
+    removeTree(stagingDir, { volume: target.volume });
+    mkdirSync(stagingDir);
+    return false;
+};
+/** Best-effort: a cache that cannot be written costs a reinstall later, never this landing. */
+const storeCached = (target, revision, stagingDir, log) => {
+    const directory = feedPreparedDir(target), { marker, tree } = cachePaths(target, revision);
+    const tmp = `${tree}.${process.pid}.tmp`;
+    try {
+        mkdirSync(directory, { mode: 0o700, recursive: true });
+        removeTree(tmp, { volume: target.volume });
+        cpSync(stagingDir, tmp, { errorOnExist: true, force: false, preserveTimestamps: true, recursive: true, verbatimSymlinks: true });
+        const digest = digestDirectory(tmp);
+        removeTree(tree, { volume: target.volume });
+        renameSync(tmp, tree);
+        writeFileSync(`${marker}.tmp`, `${JSON.stringify({ digest, revision })}\n`, { mode: 0o600 });
+        renameSync(`${marker}.tmp`, marker);
+        const entries = readdirSync(directory).filter((name) => name.endsWith(".json"))
+            .map((name) => ({ name: name.slice(0, -".json".length), time: statSync(path.join(directory, name)).mtimeMs }))
+            .sort((left, right) => right.time - left.time);
+        for (const stale of entries.slice(PREPARE_CACHE_KEEP)) {
+            rmSync(path.join(directory, `${stale.name}.json`), { force: true });
+            removeTree(path.join(directory, stale.name), { volume: target.volume });
+        }
+    }
+    catch (error) {
+        try {
+            removeTree(tmp, { volume: target.volume });
+        }
+        catch { /* reported below */ }
+        log(`could not cache the prepared tree for ${revision.slice(0, 12)}: ${error.message}`);
+    }
+};
+/**
+ * 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 const stageFeedContent = (target, resolved, stagingDir, { exec, log }) => {
+    if (!preparedOf(target))
+        return stageFeedSource(target.source, resolved, stagingDir, { exec });
+    if (target.prepare && restoreCached(target, resolved.revision, stagingDir, log))
+        return resolved;
+    const source = stageFeedSource(target.source, sourcePart(resolved), stagingDir, { exec });
+    const staged = compose(target, source, (target.include ?? []).map(({ from, to }) => ({ digest: stageInclude(stagingDir, from, to), to })));
+    if (target.prepare) {
+        log(`preparing ${staged.revision.slice(0, 12)}: ${target.prepare.command.join(" ")}${target.prepare.kind === "image" ? ` in ${target.prepare.image} (${target.prepare.platform})` : " on the host"}`);
+        runFeedPrepare(target, stagingDir, staged);
+        storeCached(target, staged.revision, stagingDir, log);
+    }
+    return staged;
+};

package/dist/volume/feedProject.d.ts

@@ -0,0 +1,39 @@
+import type { TeamWorkspaceResource } from "../manifest/index.js";
+import { type FeedExec } from "./feedSource.js";
+import { type FeedTarget } from "./feedTarget.js";
+type VolumeResource = Extract<TeamWorkspaceResource, {
+    kind: "volume";
+}>;
+type DeclaredFeed = NonNullable<VolumeResource["feed"]>;
+export interface FeedTargetOptions {
+    /** Docker client a containerized `prepare` runs through; default `docker`. */
+    dockerCommand?: string;
+    exec?: FeedExec;
+    fetch?: boolean;
+    healLimit?: number;
+    stateDir?: string;
+    validateTimeoutMs?: number;
+    volumePath?: string;
+}
+export interface DeclaredVolumeFeed {
+    /** Directory of the manifest that declared the resource; relative feed paths resolve here. */
+    base: string;
+    feed: DeclaredFeed;
+    id: string;
+    name: string;
+    record?: {
+        keepMs: number;
+    };
+}
+/** Every fed volume visible in the compile plan, deduplicated by id (team resources reach many agents). */
+export declare const findDeclaredVolumeFeeds: (inputPath: string) => Promise<DeclaredVolumeFeed[]>;
+/** `docker volume inspect` names the host directory of a named volume; the override serves other hosts and tests. */
+export declare const resolveVolumeHostPath: (name: string, { exec, volumePath }: {
+    exec?: FeedExec;
+    volumePath?: string;
+}) => string;
+/** Shared host-history location, including callers which only have deployed volume facts. */
+export declare const resolveFeedStateDirectory: (name: string, options?: FeedTargetOptions) => string;
+export declare const toFeedTarget: (declared: DeclaredVolumeFeed, options?: FeedTargetOptions) => FeedTarget;
+export declare const resolveFeedTarget: (inputPath: string, resourceId: string, options?: FeedTargetOptions) => Promise<FeedTarget>;
+export {};

package/dist/volume/feedProject.js

@@ -0,0 +1,92 @@
+// Resolves `<resource id>` in a Spawnfile project to a FeedTarget: the declared feed (paths resolved
+// against the declaring manifest), the host path of the named volume, and the host state directory.
+import path from "node:path";
+import { buildCompilePlan } from "../compiler/index.js";
+import { resolveBundleArchitecture } from "../compiler/workspaceBundleResolve.js";
+import { recordingKeepMs, SpawnfileError } from "../shared/index.js";
+import { feedError } from "./feedLayout.js";
+import { hostExec } from "./feedSource.js";
+import { DEFAULT_FEED_HEAL_LIMIT, DEFAULT_FEED_KEEP, DEFAULT_FEED_PREPARE_TIMEOUT_MS, DEFAULT_FEED_REF_COMMAND_TIMEOUT_MS, DEFAULT_FEED_VALIDATE_TIMEOUT_MS } from "./feedTarget.js";
+/** Every fed volume visible in the compile plan, deduplicated by id (team resources reach many agents). */
+export const findDeclaredVolumeFeeds = async (inputPath) => {
+    const plan = await buildCompilePlan(inputPath);
+    const byId = new Map();
+    const recordingById = new Map();
+    for (const node of plan.nodes) {
+        const keepMs = node.value.kind === "agent" ? recordingKeepMs(node.value.training?.record) : undefined;
+        for (const resource of node.value.workspaceResources ?? []) {
+            if (keepMs !== undefined && resource.kind === "volume" && resource.feed) {
+                recordingById.set(resource.id, Math.max(recordingById.get(resource.id) ?? 0, keepMs));
+            }
+            if (resource.kind !== "volume" || !resource.feed || byId.has(resource.id))
+                continue;
+            byId.set(resource.id, { base: path.dirname(resource.scope.key), feed: resource.feed, id: resource.id, name: resource.name });
+        }
+    }
+    for (const [id, keepMs] of recordingById)
+        byId.get(id).record = { keepMs };
+    return [...byId.values()].sort((left, right) => left.id.localeCompare(right.id));
+};
+/** `docker volume inspect` names the host directory of a named volume; the override serves other hosts and tests. */
+export const resolveVolumeHostPath = (name, { exec = hostExec, volumePath }) => {
+    if (volumePath)
+        return path.resolve(volumePath);
+    try {
+        const mountpoint = exec("docker", ["volume", "inspect", "--format", "{{.Mountpoint}}", name]).toString().trim();
+        if (!path.isAbsolute(mountpoint))
+            throw new Error(`unexpected mountpoint ${JSON.stringify(mountpoint)}`);
+        return mountpoint;
+    }
+    catch (error) {
+        throw feedError(`cannot find the host path of volume ${name}: ${String(error.message).trim().slice(0, 200)}. Deploy the organization once, or pass --volume-path.`);
+    }
+};
+/** Shared host-history location, including callers which only have deployed volume facts. */
+export const resolveFeedStateDirectory = (name, options = {}) => path.resolve(options.stateDir ?? path.join(path.dirname(resolveVolumeHostPath(name, options)), "spawnfile-feed"));
+const toPrepare = (prepare, options) => {
+    const timeoutMs = (prepare.timeout_seconds ?? DEFAULT_FEED_PREPARE_TIMEOUT_MS / 1000) * 1000;
+    if (prepare.host)
+        return { command: prepare.command, kind: "host", timeoutMs };
+    return {
+        command: prepare.command, dockerCommand: options.dockerCommand ?? "docker", image: prepare.image, kind: "image",
+        // The refresh runs on the host that serves the volume, so the target platform defaults to its own.
+        network: prepare.network ?? true, platform: prepare.platform ?? `linux/${resolveBundleArchitecture()}`, timeoutMs
+    };
+};
+const toRefRule = (ref, base) => ({
+    ...(ref.command ? { command: { argv: ref.command, cwd: base, timeoutMs: DEFAULT_FEED_REF_COMMAND_TIMEOUT_MS } } : {}),
+    ...(ref.fallback ? { fallback: ref.fallback } : {}),
+    ...(ref.template ? { template: ref.template } : {})
+});
+export const toFeedTarget = (declared, options = {}) => {
+    const volume = resolveVolumeHostPath(declared.name, options);
+    const feed = declared.feed, ref = feed.git?.ref;
+    const source = feed.git
+        ? { fetch: options.fetch ?? feed.git.fetch ?? false, kind: "git", ...(feed.git.paths ? { paths: feed.git.paths } : {}), ref: typeof ref === "string" ? ref : "HEAD", repo: path.resolve(declared.base, feed.git.repo) }
+        : { directory: path.resolve(declared.base, feed.directory), kind: "directory" };
+    return {
+        ...(feed.freeze ? { freeze: { after: feed.freeze.after, timezone: feed.freeze.timezone } } : {}),
+        healLimit: options.healLimit ?? DEFAULT_FEED_HEAL_LIMIT,
+        ...(feed.include ? { include: feed.include.map((entry) => ({ from: path.resolve(declared.base, entry.from), to: entry.to })) } : {}),
+        keep: feed.keep ?? DEFAULT_FEED_KEEP,
+        ...(feed.owner ? { owner: feed.owner } : {}),
+        ...(feed.prepare ? { prepare: toPrepare(feed.prepare, options) } : {}),
+        ...(declared.record ? { record: declared.record } : {}),
+        ...(ref !== undefined && typeof ref !== "string" ? { refRule: toRefRule(ref, declared.base) } : {}),
+        resourceId: declared.id,
+        source,
+        // Beside the volume's content root: the same filesystem (rename stays atomic), never inside it.
+        stateDir: resolveFeedStateDirectory(declared.name, { ...options, volumePath: volume }),
+        ...(feed.validate ? { validate: { command: feed.validate, cwd: declared.base, timeoutMs: options.validateTimeoutMs ?? DEFAULT_FEED_VALIDATE_TIMEOUT_MS } } : {}),
+        volume,
+        volumeName: declared.name
+    };
+};
+export const resolveFeedTarget = async (inputPath, resourceId, options = {}) => {
+    const feeds = await findDeclaredVolumeFeeds(inputPath);
+    const declared = feeds.find((entry) => entry.id === resourceId);
+    if (!declared) {
+        throw new SpawnfileError("validation_error", `no fed volume ${resourceId} in ${inputPath}${feeds.length ? `; fed volumes: ${feeds.map((entry) => entry.id).join(", ")}` : "; no volume declares feed"}`);
+    }
+    return toFeedTarget(declared, options);
+};

package/dist/volume/feedRecord.d.ts

@@ -0,0 +1,55 @@
+import { type FeedLanding } from "./feedLandings.js";
+import type { FeedProvenance } from "./feedSource.js";
+export declare const FEED_LANDED_VERSION = "spawnfile.volume-feed-landed.v1";
+export declare const FEED_IDENTITY_VERSION = "spawnfile.volume-feed.v1";
+export interface FeedIdentity {
+    files: number;
+    landed_at: string;
+    resource: string;
+    revision: string;
+    source: FeedProvenance;
+    tree: string;
+    version: typeof FEED_IDENTITY_VERSION;
+    volume: string;
+}
+export interface FeedLandedRecord {
+    /** Recoverable history, independent of the next refresh's source declaration. */
+    recording?: {
+        keep_ms: number;
+        landing: FeedLanding;
+    };
+    /** Re-land cycles per revision since the volume was last clean; a ceiling suspends auto-repair. */
+    heals: Record<string, number>;
+    identity: FeedIdentity;
+    identity_sha256: string;
+    /** Local date (freeze time zone) the serving revision was landed in; only feeds that declare a freeze stamp it. */
+    period?: string;
+    revision: string;
+    /** Physical name of the serving tree under trees/. */
+    tree: string;
+    /** Recorded tree names in serving order, the serving tree last. */
+    trees: string[];
+    version: typeof FEED_LANDED_VERSION;
+}
+export declare const isFeedRevision: (value: unknown) => value is string;
+export declare const isFeedTreeName: (value: unknown) => value is string;
+export declare const feedIdentityFindings: (record: unknown) => string[];
+export declare const feedLandedFindings: (record: unknown) => string[];
+/** Findings, not a throw: a corrupt record degrades to "nothing landed" and is re-earned by a full land. */
+export declare const readFeedLanded: (stateDir: string) => {
+    reason: string | null;
+    record: FeedLandedRecord | null;
+};
+/** tmp + rename, 0600, and only ever after the volume mutation it describes has succeeded. */
+export declare const writeFeedLanded: (stateDir: string, record: FeedLandedRecord) => FeedLandedRecord;
+export declare const feedIdentityBytes: (record: FeedIdentity) => string;
+/**
+ * Validated after it is on disk and before it is visible -- reparsing what the filesystem holds is what
+ * catches a truncated write -- then moved into the volume with one rename. The temporary file lives in
+ * `tmpDir`, outside the volume, so the volume root never gains a transient entry.
+ */
+export declare const writeFeedIdentity: (volume: string, record: FeedIdentity, { owner, tmpDir }: {
+    owner?: string;
+    tmpDir: string;
+}) => string;
+export declare const readFeedIdentityBytes: (volume: string) => string | null;

package/dist/volume/feedRecord.js

@@ -0,0 +1,148 @@
+// Two records, kept apart on purpose:
+//
+//   * the HOST record (`<state>/landed.json`), outside the volume: the only input the host decides from;
+//   * the IDENTITY record (`<volume>/.spawnfile-feed.json`), inside the volume: an OUTPUT for agents to
+//     read. The agent uid can replace that name, so the host takes no decision from it -- it reads it back
+//     only to compare its digest with the one the host recorded, which is a tamper check, not trust.
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, chmodSync, lchownSync } from "node:fs";
+import path from "node:path";
+import { writeDurableFileSync } from "../filesystem/index.js";
+import { isFeedLanding } from "./feedLandings.js";
+import { FEED_IDENTITY_FILE, feedError, feedTreeLink } from "./feedLayout.js";
+import { sha256Hex } from "./feedManifest.js";
+export const FEED_LANDED_VERSION = "spawnfile.volume-feed-landed.v1";
+export const FEED_IDENTITY_VERSION = "spawnfile.volume-feed.v1";
+const REVISION = /^[0-9a-f]{64}$/u;
+/** A physical tree name: the revision, or the revision plus a generation for a re-land beside a drifted copy. */
+const TREE_NAME = /^[0-9a-f]{64}(?:\.[1-9][0-9]*)?$/u;
+export const isFeedRevision = (value) => typeof value === "string" && REVISION.test(value);
+export const isFeedTreeName = (value) => typeof value === "string" && TREE_NAME.test(value);
+export const feedIdentityFindings = (record) => {
+    if (!record || typeof record !== "object" || Array.isArray(record))
+        return ["must be a JSON object"];
+    const value = record, findings = [];
+    if (value.version !== FEED_IDENTITY_VERSION)
+        findings.push(`version must be ${FEED_IDENTITY_VERSION}`);
+    if (!isFeedRevision(value.revision))
+        findings.push("revision must be a 64-character hex digest");
+    else if (typeof value.tree !== "string" || !value.tree.startsWith(`${feedTreeLink(value.revision)}`) || !isFeedTreeName(value.tree.slice("trees/".length)))
+        findings.push(`tree must be ${feedTreeLink(value.revision)}[.<generation>]`);
+    if (typeof value.resource !== "string" || !value.resource)
+        findings.push("resource must name the volume resource");
+    if (typeof value.volume !== "string" || !value.volume)
+        findings.push("volume must name the host volume");
+    if (!Number.isInteger(value.files) || value.files < 0)
+        findings.push("files must be a count");
+    if (typeof value.landed_at !== "string" || !value.landed_at)
+        findings.push("landed_at must be an instant");
+    if (!value.source || typeof value.source !== "object" || !["git", "directory"].includes(value.source.kind))
+        findings.push("source must describe a git or directory source");
+    return findings;
+};
+export const feedLandedFindings = (record) => {
+    if (!record || typeof record !== "object" || Array.isArray(record))
+        return ["must be a JSON object"];
+    const value = record, findings = [];
+    if (value.version !== FEED_LANDED_VERSION)
+        findings.push(`version must be ${FEED_LANDED_VERSION}`);
+    if (!isFeedRevision(value.revision))
+        findings.push("revision must be a 64-character hex digest");
+    if (!isFeedTreeName(value.tree) || (isFeedRevision(value.revision) && value.tree.slice(0, 64) !== value.revision))
+        findings.push("tree must name a tree of the serving revision");
+    if (!Array.isArray(value.trees) || value.trees.some((tree) => !isFeedTreeName(tree)))
+        findings.push("trees must list landed tree names");
+    else if (value.trees.at(-1) !== value.tree)
+        findings.push("trees must end with the serving tree");
+    if (typeof value.identity_sha256 !== "string" || !/^[0-9a-f]{64}$/u.test(value.identity_sha256))
+        findings.push("identity_sha256 must be a hex digest");
+    findings.push(...feedIdentityFindings(value.identity).map((finding) => `identity ${finding}`));
+    if (value.identity && (value.identity.revision !== value.revision || value.identity.tree !== `trees/${value.tree}`))
+        findings.push("identity must describe the serving tree");
+    if (value.period !== undefined && (typeof value.period !== "string" || !/^\d{4}-\d{2}-\d{2}$/u.test(value.period)))
+        findings.push("period must be a YYYY-MM-DD date");
+    if (!value.heals || typeof value.heals !== "object" || Array.isArray(value.heals))
+        findings.push("heals must be an object");
+    if (value.recording !== undefined && (!Number.isSafeInteger(value.recording?.keep_ms)
+        || value.recording.keep_ms <= 0 || !isFeedLanding(value.recording.landing)
+        || value.recording.landing.landed_at !== value.identity?.landed_at
+        || value.recording.landing.tree !== value.identity?.tree))
+        findings.push("recording must describe the landed identity");
+    return findings;
+};
+const landedPath = (stateDir) => path.join(stateDir, "landed.json");
+/** Findings, not a throw: a corrupt record degrades to "nothing landed" and is re-earned by a full land. */
+export const readFeedLanded = (stateDir) => {
+    let text;
+    try {
+        text = readFileSync(landedPath(stateDir), "utf8");
+    }
+    catch {
+        return { reason: null, record: null };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return { reason: "landed.json is not parseable JSON", record: null };
+    }
+    const findings = feedLandedFindings(parsed);
+    return findings.length ? { reason: `landed.json is invalid: ${findings.join("; ")}`, record: null } : { reason: null, record: parsed };
+};
+/** tmp + rename, 0600, and only ever after the volume mutation it describes has succeeded. */
+export const writeFeedLanded = (stateDir, record) => {
+    const findings = feedLandedFindings(record);
+    if (findings.length)
+        throw feedError(`refusing to write an invalid landed.json: ${findings.join("; ")}`);
+    mkdirSync(stateDir, { mode: 0o700, recursive: true });
+    const file = landedPath(stateDir), bytes = `${JSON.stringify(record, null, 2)}\n`;
+    if (record.recording)
+        writeDurableFileSync(file, bytes);
+    else {
+        const tmp = `${file}.${process.pid}.tmp`;
+        rmSync(tmp, { force: true });
+        writeFileSync(tmp, bytes, { mode: 0o600 });
+        renameSync(tmp, file);
+    }
+    return record;
+};
+export const feedIdentityBytes = (record) => `${JSON.stringify(record, null, 2)}\n`;
+/**
+ * Validated after it is on disk and before it is visible -- reparsing what the filesystem holds is what
+ * catches a truncated write -- then moved into the volume with one rename. The temporary file lives in
+ * `tmpDir`, outside the volume, so the volume root never gains a transient entry.
+ */
+export const writeFeedIdentity = (volume, record, { owner, tmpDir }) => {
+    const planned = feedIdentityFindings(record);
+    if (planned.length)
+        throw feedError(`refusing to publish an invalid ${FEED_IDENTITY_FILE}: ${planned.join("; ")}`);
+    const tmp = path.join(tmpDir, `${FEED_IDENTITY_FILE}.${process.pid}.tmp`);
+    rmSync(tmp, { force: true });
+    const bytes = feedIdentityBytes(record);
+    writeFileSync(tmp, bytes, { mode: 0o444 });
+    let written = null;
+    try {
+        written = JSON.parse(readFileSync(tmp, "utf8"));
+    }
+    catch { /* reported below */ }
+    const findings = written === null ? ["did not survive the write as JSON"] : feedIdentityFindings(written);
+    if (findings.length) {
+        rmSync(tmp, { force: true });
+        throw feedError(`${FEED_IDENTITY_FILE} failed validation after it was written: ${findings.join("; ")}`);
+    }
+    if (owner) {
+        const [uid, gid] = owner.split(":").map(Number);
+        lchownSync(tmp, uid, gid);
+    }
+    chmodSync(tmp, 0o444);
+    renameSync(tmp, path.join(volume, FEED_IDENTITY_FILE));
+    return sha256Hex(bytes);
+};
+export const readFeedIdentityBytes = (volume) => {
+    try {
+        return readFileSync(path.join(volume, FEED_IDENTITY_FILE), "utf8");
+    }
+    catch {
+        return null;
+    }
+};

package/dist/volume/feedRef.d.ts

@@ -0,0 +1,43 @@
+import type { FeedLandedRecord } from "./feedRecord.js";
+import type { FeedExec } from "./feedSource.js";
+import type { FeedTarget } from "./feedTarget.js";
+/** YYYY-MM-DD in `zone` at `now`. */
+export declare const feedLocalDate: (now: Date, zone: string) => string;
+/** HH:MM (24-hour, zero-padded, so a string compare orders it) in `zone` at `now`. */
+export declare const feedLocalClock: (now: Date, zone: string) => string;
+export declare const expandFeedRefTemplate: (template: string, now: Date) => string;
+/**
+ * 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 declare const expandFeedPaths: (paths: string[] | undefined, now: Date) => string[] | undefined;
+/** The period a landing at `now` belongs to; only a feed that declares a freeze has periods. */
+export declare const feedPeriod: (target: FeedTarget, now: Date) => string | undefined;
+/**
+ * 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 declare const feedCutoffInstant: (date: string, after: string, zone: string) => Date;
+export type FeedRefChoice = {
+    kind: "ref";
+    ref: string;
+} | {
+    kind: "waiting";
+    reason: string;
+};
+/**
+ * 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 declare const chooseFeedRef: (target: FeedTarget, { exec, now }: {
+    exec: FeedExec;
+    now: Date;
+}) => FeedRefChoice;
+/**
+ * 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 declare const feedFrozen: (target: FeedTarget, record: FeedLandedRecord | null, ref: string, now: Date, paths?: string[]) => boolean;