spawnfile 0.1.14 → 0.1.18

package/dist/target/publicArtifactSnapshot.js

@@ -5,6 +5,7 @@ import { z } from "zod";
 import { assertOrdinaryJsonGraph, opaqueTargetHandleSchema, runIdSchema, selectedTargetSchema } from "./contracts.js";
 export const TARGET_PUBLIC_ARTIFACT_SNAPSHOT_REQUEST_VERSION = "spawnfile.target-public-artifact-snapshot.request.v1";
 export const TARGET_PUBLIC_ARTIFACT_SNAPSHOT_VERSION = "spawnfile.target-public-artifact-snapshot.v1";
+export const TARGET_PUBLIC_ARTIFACT_SNAPSHOT_NOT_PRESENT_VERSION = "spawnfile.target-public-artifact-snapshot.not-present.v1";
 export const TARGET_PUBLIC_ARTIFACT_ROOT = "/tmp/spawnfile-public";
 export const MAX_TARGET_PUBLIC_ARTIFACT_BYTES = 131_072;
 const digestSchema = z.string().regex(/^sha256:[0-9a-f]{64}$/u);
@@ -12,10 +13,13 @@ const identifierSchema = z.string().regex(/^[a-z][a-z0-9_-]{0,63}$/u);
 const mediaTypeSchema = z.string()
     .max(127)
     .regex(/^[a-z][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/u);
+const PUBLIC_ARTIFACT_PATH = /^\/tmp\/spawnfile-public\/[A-Za-z0-9][A-Za-z0-9._-]*$/u;
 const publicPathSchema = z.string().max(255)
-    .regex(/^\/tmp\/spawnfile-public\/[A-Za-z0-9][A-Za-z0-9._/-]*$/u)
-    .refine((value) => !value.includes("//") && !value.endsWith("/")
-    && !value.split("/").some((part) => part === "." || part === ".."));
+    // This is intentionally a direct child of the isolated public tmpfs.  A
+    // nested path would require a recursive openat-style resolver to keep every
+    // parent below the mount while an untrusted world is writing its output.
+    .regex(PUBLIC_ARTIFACT_PATH);
+export const isTargetPublicArtifactPath = (value) => typeof value === "string" && value.length <= 255 && PUBLIC_ARTIFACT_PATH.test(value);
 export const targetPublicArtifactSnapshotRequestSchema = z.object({
     artifact: z.object({
         id: identifierSchema,
@@ -53,6 +57,17 @@ export const targetPublicArtifactSnapshotSchema = z.object({
         context.addIssue({ code: z.ZodIssueCode.custom, message: "artifact content mismatch" });
     }
 });
+export const targetPublicArtifactSnapshotNotPresentSchema = z.object({
+    artifact_id: identifierSchema,
+    request_digest: digestSchema,
+    run_id: runIdSchema,
+    status: z.literal("not_present"),
+    version: z.literal(TARGET_PUBLIC_ARTIFACT_SNAPSHOT_NOT_PRESENT_VERSION)
+}).strict();
+export const targetPublicArtifactSnapshotResultSchema = z.union([
+    targetPublicArtifactSnapshotSchema,
+    targetPublicArtifactSnapshotNotPresentSchema
+]);
 const canonicalJsonValue = (value) => {
     if (Array.isArray(value))
         return `[${value.map(canonicalJsonValue).join(",")}]`;
@@ -126,6 +141,14 @@ export const parseTargetPublicArtifactSnapshot = (raw) => {
     assertOrdinaryPublicArtifactSnapshot(raw);
     return targetPublicArtifactSnapshotSchema.parse(raw);
 };
+export const parseTargetPublicArtifactSnapshotNotPresent = (raw) => {
+    assertOrdinaryPublicArtifactSnapshot(raw);
+    return targetPublicArtifactSnapshotNotPresentSchema.parse(raw);
+};
+export const parseTargetPublicArtifactSnapshotResult = (raw) => {
+    assertOrdinaryPublicArtifactSnapshot(raw);
+    return targetPublicArtifactSnapshotResultSchema.parse(raw);
+};
 export const createTargetPublicArtifactSnapshotRequestDigest = (raw) => `sha256:${createHash("sha256")
     .update("spawnfile.target-public-artifact-snapshot.request.v1\0", "utf8")
     .update(canonicalJson(parseTargetPublicArtifactSnapshotRequest(raw)), "utf8")
@@ -147,4 +170,15 @@ export const createTargetPublicArtifactSnapshot = (input) => {
         version: TARGET_PUBLIC_ARTIFACT_SNAPSHOT_VERSION
     });
 };
+export const createTargetPublicArtifactSnapshotNotPresent = (raw) => {
+    const request = parseTargetPublicArtifactSnapshotRequest(raw);
+    return parseTargetPublicArtifactSnapshotNotPresent({
+        artifact_id: request.artifact.id,
+        request_digest: createTargetPublicArtifactSnapshotRequestDigest(request),
+        run_id: request.run_id,
+        status: "not_present",
+        version: TARGET_PUBLIC_ARTIFACT_SNAPSHOT_NOT_PRESENT_VERSION
+    });
+};
 export const createCanonicalTargetPublicArtifactSnapshotBytes = (raw) => canonicalJsonValue(parseTargetPublicArtifactSnapshot(raw));
+export const createCanonicalTargetPublicArtifactSnapshotResultBytes = (raw) => canonicalJsonValue(parseTargetPublicArtifactSnapshotResult(raw));

package/dist/volume/feedLand.d.ts

@@ -0,0 +1,31 @@
+import { type LinkOps } from "./feedLayout.js";
+import { type FeedLandedRecord } from "./feedRecord.js";
+import { type FeedExec, type ResolvedFeedSource } from "./feedSource.js";
+import { type FeedTarget } from "./feedTarget.js";
+export interface FeedRuntime {
+    exec?: FeedExec;
+    log?: (line: string) => void;
+    now?: () => Date;
+    ops?: LinkOps;
+}
+export interface FeedLandResult {
+    revision: string;
+    reused: boolean;
+    tree: string;
+    treesRemoved: string[];
+    unknownTrees: string[];
+}
+export declare const isoSeconds: (date: Date) => string;
+/**
+ * The declared validation hook: the gate between "staged" and "reachable". Non-zero exit lands nothing.
+ * It validates; it may not edit: the tree is digested before and after, and any change is a refusal,
+ * because changed bytes would be served under a revision that does not describe them.
+ */
+export declare const runFeedValidation: (target: FeedTarget, tree: string, resolved: ResolvedFeedSource) => void;
+export declare const landFeed: (target: FeedTarget, resolved: ResolvedFeedSource, record: FeedLandedRecord | null, { exact, force, heals, period, runtime }?: {
+    exact?: boolean;
+    force?: boolean;
+    heals?: Record<string, number>;
+    period?: string;
+    runtime?: FeedRuntime;
+}) => FeedLandResult;

package/dist/volume/feedLand.js

@@ -0,0 +1,174 @@
+// The mutating half of a refresh: stage, validate, freeze, land, point `current`, publish the identity,
+// record, collect garbage. Read feedLayout.ts first: it owns every rule about what may touch the volume.
+//
+// WHAT THIS FILE DECIDES FROM, EXHAUSTIVELY: the host record and manifests outside the volume, the
+// source, and the host clock. The volume itself is read only to assert that what is about to be touched
+// is the real directory the host created, and to find a tree name nobody occupies.
+//
+// GENERATIONS, NOT REPLACEMENTS. A tree is never replaced under its own name: a re-land of revision R
+// lands as `trees/R.1` (then `.2`, ...) beside the drifted `trees/R`, `current` moves to it with one
+// rename, and the drifted tree is retired later like any other. So `current` never dangles, not even
+// between two adjacent renames, and nothing the host did not record is ever parked or deleted.
+import { spawnSync } from "node:child_process";
+import { lstatSync, mkdirSync, readdirSync } from "node:fs";
+import path from "node:path";
+import { FEED_TREES_DIR, LINK_OPS, assertRealDirectory, feedError, feedTreeLink, landTree, ownAndFreeze, parkTree, pointCurrent, removeTree } from "./feedLayout.js";
+import { buildFeedManifest, compareFeedManifest, manifestDrift, readFeedManifest, removeFeedManifest, writeFeedManifest } from "./feedManifest.js";
+import { ensureFeedLanding, publishFeedLanded } from "./feedLandings.js";
+import { FEED_IDENTITY_VERSION, FEED_LANDED_VERSION, writeFeedIdentity } from "./feedRecord.js";
+import { stageFeedContent } from "./feedPrepare.js";
+import { digestDirectory, hostExec } from "./feedSource.js";
+import { feedStagingDir, feedTrashDir } from "./feedTarget.js";
+export const isoSeconds = (date) => `${date.toISOString().slice(0, 19)}Z`;
+const stampOf = (date) => `${isoSeconds(date).replace(/[:-]/gu, "")}.${process.pid}`;
+/**
+ * The declared validation hook: the gate between "staged" and "reachable". Non-zero exit lands nothing.
+ * It validates; it may not edit: the tree is digested before and after, and any change is a refusal,
+ * because changed bytes would be served under a revision that does not describe them.
+ */
+export const runFeedValidation = (target, tree, resolved) => {
+    if (!target.validate)
+        return;
+    const before = digestDirectory(tree);
+    const [command, ...args] = target.validate.command;
+    const result = spawnSync(command, args, {
+        cwd: target.validate.cwd,
+        encoding: "utf8",
+        env: {
+            ...process.env,
+            SPAWNFILE_FEED_PROVENANCE: JSON.stringify(resolved.provenance),
+            SPAWNFILE_FEED_RESOURCE: target.resourceId,
+            SPAWNFILE_FEED_REVISION: resolved.revision,
+            SPAWNFILE_FEED_TREE: tree
+        },
+        maxBuffer: 16 * 1024 * 1024,
+        stdio: ["ignore", "pipe", "pipe"],
+        timeout: target.validate.timeoutMs
+    });
+    if (result.error?.code === "ETIMEDOUT") {
+        throw feedError(`the feed validation command for ${target.resourceId} did not finish within ${Math.round(target.validate.timeoutMs / 1000)}s and was killed; nothing was landed`);
+    }
+    if (result.error)
+        throw feedError(`the feed validation command for ${target.resourceId} could not run: ${result.error.message}`);
+    if (result.status !== 0) {
+        const output = `${result.stderr ?? ""}${result.stdout ?? ""}`.trim().split("\n").slice(-20).join("\n");
+        throw feedError(`the feed validation command rejected revision ${resolved.revision.slice(0, 12)} of ${target.resourceId} (${result.signal ? `killed by ${result.signal}` : `exit ${result.status}`}); nothing was landed${output ? `:\n${output}` : ""}`);
+    }
+    if (digestDirectory(tree) !== before)
+        throw feedError(`the feed validation command for ${target.resourceId} modified the tree it was validating; a validation hook may only read it, so nothing was landed`);
+};
+const treesDirOf = (target) => path.join(target.volume, FEED_TREES_DIR);
+const treeMatches = (target, name) => {
+    const treePath = path.join(treesDirOf(target), name);
+    if (!assertRealDirectory(treePath, `the fed tree ${FEED_TREES_DIR}/${name.slice(0, 12)}`))
+        return false;
+    const manifest = readFeedManifest(target.stateDir, name);
+    return manifest !== null && manifestDrift(compareFeedManifest(treePath, manifest)).length === 0;
+};
+/** The first name for `revision` that nothing occupies -- whatever occupies the others, the host never moves it. */
+const freshTreeName = (target, revision) => {
+    for (let generation = 0;; generation += 1) {
+        const name = generation === 0 ? revision : `${revision}.${generation}`;
+        try {
+            lstatSync(path.join(treesDirOf(target), name));
+        }
+        catch {
+            return name;
+        }
+    }
+};
+/** Copies, validates, owns and freezes OUTSIDE the volume, then moves the finished tree in with one rename. */
+const stageAndLand = (target, resolved, { exact, exec, log }) => {
+    const stagingDir = path.join(feedStagingDir(target), `${resolved.revision}-${process.pid}`);
+    removeTree(stagingDir, { volume: target.volume });
+    mkdirSync(stagingDir);
+    let staged;
+    try {
+        staged = stageFeedContent(target, resolved, stagingDir, { exec, log });
+        // A held volume re-lands exactly what it serves: inputs that moved mid-copy are a refusal, not a new revision.
+        if (exact && staged.revision !== resolved.revision)
+            throw feedError(`the source moved while ${resolved.revision.slice(0, 12)} was being re-landed (copied ${staged.revision.slice(0, 12)}); a held volume never advances, so nothing was landed`);
+        if (staged.revision !== resolved.revision)
+            log(`the source moved while it was copied; landing what was copied as ${staged.revision.slice(0, 12)}`);
+        runFeedValidation(target, stagingDir, staged);
+        ownAndFreeze(stagingDir, { owner: target.owner, volume: target.volume });
+    }
+    catch (error) {
+        try {
+            removeTree(stagingDir, { volume: target.volume });
+        }
+        catch { /* the original error says more */ }
+        throw error;
+    }
+    const name = freshTreeName(target, staged.revision);
+    writeFeedManifest(target.stateDir, buildFeedManifest(stagingDir, name));
+    landTree(stagingDir, path.join(treesDirOf(target), name));
+    log(`landed ${FEED_TREES_DIR}/${name.slice(0, 12)}${name.length > 64 ? name.slice(64) : ""}`);
+    return { name, resolved: staged };
+};
+/**
+ * Retires recorded trees beyond `keep`, oldest-served first by the host's own order (never by
+ * filesystem mtimes). Names the host never recorded are reported and left in place.
+ */
+const collectGarbage = (target, order, serving, now) => {
+    const treesDir = treesDirOf(target);
+    if (!assertRealDirectory(treesDir, "the fed volume's trees/ directory"))
+        return { removed: [], unknown: [] };
+    const present = readdirSync(treesDir, { withFileTypes: true });
+    const real = new Set(present.filter((entry) => entry.isDirectory()).map((entry) => entry.name));
+    const unknown = present.map((entry) => entry.name).filter((name) => !order.includes(name)).sort();
+    const retired = order.filter((name) => name !== serving);
+    const doomed = retired.slice(0, Math.max(0, retired.length - target.keep));
+    for (const name of doomed) {
+        if (!real.has(name))
+            continue;
+        removeTree(parkTree(path.join(treesDir, name), feedTrashDir(target), stampOf(now)), { volume: target.volume });
+    }
+    return { removed: doomed, unknown };
+};
+export const landFeed = (target, resolved, record, { exact = false, force = false, heals = {}, period, runtime = {} } = {}) => {
+    const clock = runtime.now ?? (() => new Date()), log = runtime.log ?? (() => undefined), exec = runtime.exec ?? hostExec;
+    if (record && (target.record || record.recording))
+        ensureFeedLanding(target, record, clock());
+    // Preserve the existing timestamp behavior when recording is absent.
+    const started = target.record ? undefined : clock();
+    if (!assertRealDirectory(treesDirOf(target), "the fed volume's trees/ directory"))
+        mkdirSync(treesDirOf(target), { mode: 0o755 });
+    // A retained tree for this revision is reused only when the host recorded it and its manifest still
+    // describes it -- and it passes the validation policy as declared NOW, like any new tree.
+    const retained = force ? undefined : [...(record?.trees ?? [])].reverse().find((name) => name.slice(0, 64) === resolved.revision && treeMatches(target, name));
+    let name, landedSource = resolved;
+    if (retained) {
+        runFeedValidation(target, path.join(treesDirOf(target), retained), resolved);
+        name = retained;
+    }
+    else
+        ({ name, resolved: landedSource } = stageAndLand(target, resolved, { exact, exec, log }));
+    const revision = landedSource.revision;
+    let switchingAt;
+    const changed = pointCurrent(target.volume, feedTreeLink(name), { ops: runtime.ops ?? LINK_OPS, tmpDir: feedStagingDir(target),
+        ...(target.record ? { beforeRename: () => { switchingAt = clock().toISOString(); } } : {}) });
+    const now = started ?? clock();
+    if (changed)
+        log(`current -> ${feedTreeLink(name.slice(0, 12))}`);
+    const manifest = readFeedManifest(target.stateDir, name) ?? buildFeedManifest(path.join(treesDirOf(target), name), name);
+    const identity = {
+        files: manifest.files, landed_at: target.record ? now.toISOString() : isoSeconds(now), resource: target.resourceId, revision, source: landedSource.provenance,
+        tree: feedTreeLink(name), version: FEED_IDENTITY_VERSION, volume: target.volumeName
+    };
+    const identitySha = writeFeedIdentity(target.volume, identity, { owner: target.owner, tmpDir: feedStagingDir(target) });
+    // Order is serving history: the serving tree is always last.
+    let trees = [...(record?.trees ?? []).filter((entry) => entry !== name), name];
+    let previous = record;
+    const write = () => previous = publishFeedLanded(target, { heals, identity, identity_sha256: identitySha, ...(period ? { period } : {}), revision, tree: name, trees, version: FEED_LANDED_VERSION }, now, previous, switchingAt);
+    write();
+    const gc = collectGarbage(target, trees, name, now);
+    if (gc.removed.length) {
+        for (const removed of gc.removed)
+            removeFeedManifest(target.stateDir, removed);
+        trees = trees.filter((entry) => !gc.removed.includes(entry));
+        write();
+        log(`retired ${gc.removed.length} tree(s): ${gc.removed.map((entry) => entry.slice(0, 12)).join(", ")}`);
+    }
+    return { revision, reused: retained !== undefined, tree: name, treesRemoved: gc.removed, unknownTrees: gc.unknown };
+};

package/dist/volume/feedLandings.d.ts

@@ -0,0 +1,45 @@
+import { type FeedLandedRecord } from "./feedRecord.js";
+import type { FeedPreparedProvenance } from "./feedSource.js";
+import type { FeedTarget } from "./feedTarget.js";
+export declare const FEED_LANDING_VERSION = "spawnfile.volume-feed-landing.v1";
+export declare const FEED_LANDINGS_FILE = "landings.jsonl";
+export interface FeedLanding {
+    version: typeof FEED_LANDING_VERSION;
+    resource: string;
+    volume: string;
+    revision: string;
+    tree: string;
+    source: ({
+        kind: "git";
+        repo: string;
+    } | {
+        kind: "directory";
+        directory: string;
+    }) & {
+        prepared?: FeedPreparedProvenance;
+    };
+    commit?: string;
+    ref?: string;
+    paths?: string[];
+    switching_at: string;
+    landed_at: string;
+    period?: string;
+}
+export declare const isFeedLanding: (value: unknown) => value is FeedLanding;
+/** Invalid lines are findings beside valid entries; an absent log is an empty history. */
+export declare const readFeedLandings: (stateDir: string) => {
+    entries: FeedLanding[];
+    errors: string[];
+};
+/** A transition's inclusive window cannot identify which tree a concurrent reader observed. */
+export declare const feedLandingAt: (entries: readonly FeedLanding[], instant: string | Date) => (FeedLanding & {
+    ambiguous?: true;
+}) | null;
+type LandingTarget = Pick<FeedTarget, "stateDir" | "record"> & Partial<Pick<FeedTarget, "source">>;
+/** Call only after writing the corresponding landed.json; the existing feed lock serializes writers. */
+export declare const appendFeedLanding: (target: LandingTarget, record: FeedLandedRecord, now: Date) => void;
+/** A verified clean host record seeds opt-in history or repairs a previously failed append. */
+export declare const ensureFeedLanding: (target: LandingTarget, record: FeedLandedRecord, now: Date) => void;
+/** Reconcile the authoritative predecessor before ANY replacement, even a revision advance. */
+export declare const publishFeedLanded: (target: FeedTarget, record: FeedLandedRecord, now: Date, previous: FeedLandedRecord | null, switchingAt?: string) => FeedLandedRecord;
+export {};

package/dist/volume/feedLandings.js

@@ -0,0 +1,111 @@
+// Recording history is host state, beside landed.json, and survives retirement of the physical trees.
+import path from "node:path";
+import { appendRetainedJsonl, entryAt, readRetainedJsonl, syncFileSync } from "../filesystem/index.js";
+import { isFeedRevision, isFeedTreeName, writeFeedLanded } from "./feedRecord.js";
+export const FEED_LANDING_VERSION = "spawnfile.volume-feed-landing.v1";
+export const FEED_LANDINGS_FILE = "landings.jsonl";
+const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const text = (value) => typeof value === "string" && value.length > 0;
+const stringArray = (value) => Array.isArray(value) && value.every(text);
+const prepared = (value) => {
+    if (value === undefined)
+        return true;
+    if (!object(value) || !isFeedRevision(value.source_revision) || !Array.isArray(value.include))
+        return false;
+    if (!value.include.every((entry) => object(entry) && isFeedRevision(entry.digest) && text(entry.to)))
+        return false;
+    const recipe = value.prepare;
+    return recipe === null || (object(recipe) && stringArray(recipe.command)
+        && (recipe.image === null || text(recipe.image)) && (recipe.network === null || typeof recipe.network === "boolean")
+        && (recipe.platform === null || text(recipe.platform)));
+};
+export const isFeedLanding = (value) => {
+    if (!object(value) || value.version !== FEED_LANDING_VERSION || !text(value.resource) || !text(value.volume))
+        return false;
+    if (!isFeedRevision(value.revision) || !text(value.tree) || value.tree !== `trees/${value.tree.slice(6)}`
+        || !isFeedTreeName(value.tree.slice(6)) || value.tree.slice(6, 70) !== value.revision)
+        return false;
+    if (!text(value.landed_at) || !Number.isFinite(Date.parse(value.landed_at)))
+        return false;
+    if (!text(value.switching_at) || !Number.isFinite(Date.parse(value.switching_at))
+        || Date.parse(value.switching_at) > Date.parse(value.landed_at))
+        return false;
+    if (value.period !== undefined && (typeof value.period !== "string" || !/^\d{4}-\d{2}-\d{2}$/u.test(value.period)))
+        return false;
+    if (!object(value.source) || !prepared(value.source.prepared))
+        return false;
+    if (value.source.kind === "directory") {
+        return text(value.source.directory) && value.commit === undefined && value.ref === undefined && value.paths === undefined;
+    }
+    return value.source.kind === "git" && text(value.source.repo) && text(value.commit) && /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/u.test(value.commit)
+        && text(value.ref) && (value.paths === undefined || stringArray(value.paths));
+};
+/** Invalid lines are findings beside valid entries; an absent log is an empty history. */
+export const readFeedLandings = (stateDir) => readRetainedJsonl(path.join(stateDir, FEED_LANDINGS_FILE), isFeedLanding);
+/** A transition's inclusive window cannot identify which tree a concurrent reader observed. */
+export const feedLandingAt = (entries, instant) => {
+    const at = instant instanceof Date ? instant.getTime() : Date.parse(instant);
+    const transition = entryAt(entries.filter((entry) => at <= Date.parse(entry.landed_at)), instant, (entry) => entry.switching_at);
+    return transition ? { ...transition, ambiguous: true } : entryAt(entries, instant, (entry) => entry.landed_at);
+};
+const landingFromRecord = (target, record) => {
+    if (record.recording)
+        return record.recording.landing;
+    if (!target.source)
+        throw new Error("Landed record has no recoverable recording provenance");
+    const identity = record.identity, provenance = identity.source;
+    const source = target.source.kind === "git"
+        ? { kind: "git", repo: target.source.repo }
+        : { directory: target.source.directory, kind: "directory" };
+    if (provenance.prepared)
+        source.prepared = provenance.prepared;
+    return {
+        version: FEED_LANDING_VERSION, resource: identity.resource, volume: identity.volume,
+        revision: identity.revision, tree: identity.tree, source, switching_at: identity.landed_at, landed_at: identity.landed_at,
+        ...(provenance.kind === "git" ? { commit: provenance.commit, ref: provenance.ref, ...(provenance.paths ? { paths: provenance.paths } : {}) } : {}),
+        ...(record.period ? { period: record.period } : {})
+    };
+};
+/** Call only after writing the corresponding landed.json; the existing feed lock serializes writers. */
+export const appendFeedLanding = (target, record, now) => {
+    const keepMs = record.recording?.keep_ms ?? target.record?.keepMs;
+    if (keepMs === undefined)
+        return;
+    const entry = landingFromRecord(target, record);
+    appendRetainedJsonl(path.join(target.stateDir, FEED_LANDINGS_FILE), entry, {
+        isEntry: isFeedLanding, keepMs, now, timeOf: (landing) => landing.landed_at
+    });
+};
+/** A verified clean host record seeds opt-in history or repairs a previously failed append. */
+export const ensureFeedLanding = (target, record, now) => {
+    if (!target.record && !record.recording)
+        return;
+    const expected = JSON.stringify(landingFromRecord(target, record));
+    const history = readFeedLandings(target.stateDir);
+    if (history.errors.length)
+        throw new Error(`Cannot reconcile feed history: ${history.errors.join("; ")}`);
+    if (JSON.stringify(history.entries.at(-1)) === expected) {
+        syncFileSync(path.join(target.stateDir, FEED_LANDINGS_FILE));
+        return;
+    }
+    // Also covers recovery after a previous host-record directory fsync failed.
+    syncFileSync(path.join(target.stateDir, "landed.json"));
+    appendFeedLanding(target, record, now);
+};
+/** Reconcile the authoritative predecessor before ANY replacement, even a revision advance. */
+export const publishFeedLanded = (target, record, now, previous, switchingAt) => {
+    if (previous)
+        ensureFeedLanding(target, previous, now);
+    const { recording: _previousRecording, ...next } = record;
+    const landing = target.record ? landingFromRecord(target, next) : undefined;
+    if (landing)
+        landing.switching_at = switchingAt
+            ?? (previous?.identity.landed_at === next.identity.landed_at ? previous.recording?.landing.switching_at : undefined)
+            ?? landing.landed_at;
+    const published = writeFeedLanded(target.stateDir, target.record ? {
+        ...next, recording: { keep_ms: target.record.keepMs, landing: landing }
+    } : next);
+    if (target.record)
+        ensureFeedLanding(target, published, now);
+    return published;
+};

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";