spawnfile 0.1.17 → 0.1.19

package/dist/runtime/pi/adapter.js

@@ -85,6 +85,9 @@ const assertSupportedPiSurfaces = (surfaces) => {
 };
 export const piAdapter = {
     assertSupportedModelTarget(target) {
+        if (target.reasoningEffort !== undefined) {
+            throw new SpawnfileError("validation_error", "Pi runtime does not support reasoning_effort; only Daimon Codex and Grok engines support it");
+        }
         if (target.endpoint) {
             if (target.provider !== "custom" && target.provider !== "local") {
                 throw new SpawnfileError("validation_error", "Pi runtime only supports endpoints on custom or local model providers");

package/dist/runtime/pi/containerTargets.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { CLI_ENGINE_SKILL_BASE_DIRECTORIES } from "../common.js";
 import { listExecutionModelSecretNames } from "../../compiler/modelEnv.js";
 import { renderPiScheduleSource } from "./appScheduleSource.js";
 import { createPiAgentConfig, renderPiApp, renderPiAppConfig, renderPiModelsConfig, renderPiPackageJson, resolvePiEngine, } from "./appTemplate.js";
@@ -29,6 +30,11 @@ export const createPiContainerTargets = async (inputs) => {
         relativePath: `secrets/${secretName}`,
     }));
     return [{
+            agentPathsByNodeId: Object.fromEntries(agentInputs.map((input) => [input.id, {
+                    workspacePath: `<instance-root>/workspace/agents/${input.slug}`,
+                    homePath: `<instance-root>/runtime/agents/${input.slug}`,
+                    skillRoots: CLI_ENGINE_SKILL_BASE_DIRECTORIES.map((root) => `<instance-root>/workspace/agents/${input.slug}/${path.posix.relative("workspace", root)}`)
+                }])),
             engineByNodeId,
             envFiles,
             files: [

package/dist/runtime/picoclaw/adapter.js

@@ -152,6 +152,9 @@ const createContainerTargets = async (inputs) => inputs.map((input) => {
 });
 export const picoClawAdapter = {
     assertSupportedModelTarget(target) {
+        if (target.reasoningEffort !== undefined) {
+            throw new SpawnfileError("validation_error", "PicoClaw runtime does not support reasoning_effort; only Daimon Codex and Grok engines support it");
+        }
         if (target.endpoint) {
             if (target.endpoint.compatibility === "anthropic" &&
                 target.auth.method === "none") {

package/dist/runtime/registry.d.ts

@@ -3,6 +3,8 @@ import type { RuntimeLifecycleStatus } from "../shared/index.js";
 import type { RuntimeAdapter } from "./types.js";
 export type RuntimeRegistryInstall = {
     capabilityReceipt?: string;
+    /** Per-architecture receipts embedded in a multi-architecture image index. */
+    capabilityReceipts?: DaimonCapabilityReceipts;
     contractManifestSha256?: string;
     digest?: string;
     image: string;
@@ -21,6 +23,7 @@ export type RuntimeRegistryInstall = {
 } | {
     kind: "source_repo";
 };
+export type DaimonCapabilityReceipts = Partial<Record<"amd64" | "arm64", string>>;
 export interface RuntimeRegistryEntry {
     defaultBranch: string;
     install?: RuntimeRegistryInstall;

package/dist/runtime/registry.js

@@ -16,13 +16,22 @@ const runtimeInstallSchema = z.discriminatedUnion("kind", [
     z
         .object({
         capability_receipt: z.string().regex(/^sha256:[a-f0-9]{64}$/).optional(),
+        capability_receipts: z
+            .object({
+            amd64: z.string().regex(/^sha256:[a-f0-9]{64}$/).optional(),
+            arm64: z.string().regex(/^sha256:[a-f0-9]{64}$/).optional()
+        })
+            .strict()
+            .refine((receipts) => Object.keys(receipts).length > 0, "capability_receipts must pin at least one architecture")
+            .optional(),
         contract_manifest_sha256: z.string().regex(/^sha256:[a-f0-9]{64}$/).optional(),
         digest: z.string().regex(/^sha256:[a-f0-9]{64}$/).optional(),
         image: z.string().min(1),
         kind: z.literal("container_image"),
         tag: z.string().min(1)
     })
-        .strict(),
+        .strict()
+        .refine((install) => !(install.capability_receipt && install.capability_receipts), "capability_receipt and capability_receipts are mutually exclusive"),
     z
         .object({
         kind: z.literal("npm"),
@@ -71,6 +80,9 @@ export const parseRuntimeRegistry = (source) => {
                     ...(entry.install.capability_receipt
                         ? { capabilityReceipt: entry.install.capability_receipt }
                         : {}),
+                    ...(entry.install.capability_receipts
+                        ? { capabilityReceipts: { ...entry.install.capability_receipts } }
+                        : {}),
                     ...(entry.install.contract_manifest_sha256
                         ? { contractManifestSha256: entry.install.contract_manifest_sha256 }
                         : {}),

package/dist/runtime/types.d.ts

@@ -34,7 +34,14 @@ export interface ContainerTargetPersistentMount {
     reason: string;
 }
 export type RuntimeContainerConfigValueTransform = "bearer";
+export interface ContainerTargetAgentPaths {
+    workspacePath: string;
+    homePath: string | null;
+    skillRoots: string[];
+}
 export interface ContainerTarget {
+    /** Adapter-owned paths, using the same placeholders as emitted configuration. */
+    agentPathsByNodeId?: Record<string, ContainerTargetAgentPaths>;
     configEnvBindings?: RuntimeContainerConfigEnvBinding[];
     /**
      * Optional node id -> resolved engine kind map (currently only populated by
@@ -51,6 +58,12 @@ export interface ContainerTarget {
         model: string;
         reasoningEffort: string;
     }>;
+    /** Daimon only: each brokered Grok agent's declared per-turn budget, for its broker registration. */
+    grokTurnLimitsByNodeId?: Record<string, {
+        maxRequests?: number;
+        maxTokens?: number;
+        timeoutMs?: number;
+    }>;
     files: EmittedFile[];
     id: string;
     opaqueMountTargets?: string[];
@@ -191,6 +204,8 @@ export interface RuntimeAdapter {
     compileTeam?(node: ResolvedTeamNode): Promise<AdapterCompileResult>;
     createContainerTargets?(inputs: ContainerTargetInput[]): Promise<ContainerTarget[]>;
     name: string;
+    /** Throws a SpawnfileError for what compile would refuse for this agent; run by `spawnfile validate`. */
+    preflightAgent?(node: ResolvedAgentNode, nodeId: string): void;
     prepareRuntimeAuth?(input: RuntimeAuthPreparationInput): Promise<RuntimeAuthPreparationResult>;
     scaffoldAgentProject?(): RuntimeAgentScaffold;
     statusProbes?: RuntimeStatusProbe[];

package/dist/runtime/usageLedgerRead.d.ts

@@ -35,6 +35,12 @@ export interface UsageLedgerRead {
     records: UsageRecord[];
     unreadable: UsageLedgerReadFailure[];
 }
+/** `cat`s one generation through `exec`. A genuinely absent file reads as
+ * empty; every other failure is reported, never swallowed. */
+export declare const readRuntimeFileViaExec: (exec: UsageLedgerExec, filePath: string) => Promise<{
+    failure?: UsageLedgerReadFailure;
+    text: string;
+}>;
 /**
  * Reads both ledger generations (`usage.jsonl` and `usage.jsonl.1`) through
  * `exec` and parses them. Rotated (older) records are returned before

package/dist/runtime/usageLedgerRead.js

@@ -66,7 +66,7 @@ const isAbsentLedgerFile = (error) => {
 };
 /** `cat`s one generation through `exec`. A genuinely absent file reads as
  * empty; every other failure is reported, never swallowed. */
-const readLedgerGeneration = async (exec, filePath) => {
+export const readRuntimeFileViaExec = async (exec, filePath) => {
     try {
         const result = await exec(["cat", filePath]);
         return { text: result.stdout };
@@ -89,8 +89,8 @@ const readLedgerGeneration = async (exec, filePath) => {
  */
 export const readUsageLedgerViaExec = async (exec, paths) => {
     const [rotated, primary] = await Promise.all([
-        readLedgerGeneration(exec, paths.rotatedFilePath),
-        readLedgerGeneration(exec, paths.filePath)
+        readRuntimeFileViaExec(exec, paths.rotatedFilePath),
+        readRuntimeFileViaExec(exec, paths.filePath)
     ]);
     return {
         // Every row is kept, across both generations: aggregates dedupe by `turn`

package/dist/shared/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./constants.js";
 export * from "./errors.js";
+export * from "./recording.js";
 export * from "./redaction.js";
 export * from "./types.js";
 export * from "./volumeNames.js";

package/dist/shared/index.js

@@ -1,5 +1,6 @@
 export * from "./constants.js";
 export * from "./errors.js";
+export * from "./recording.js";
 export * from "./redaction.js";
 export * from "./types.js";
 export * from "./volumeNames.js";

package/dist/shared/recording.d.ts

@@ -0,0 +1,8 @@
+export declare const DEFAULT_RECORD_KEEP_MS: number;
+/** Absence disables recording; an empty declaration opts into the default window. */
+export declare const recordingKeepMs: (record: {
+    keep?: string;
+} | undefined) => number | undefined;
+export declare const maxRecordingKeepMs: (records: Iterable<{
+    keep?: string;
+} | undefined>) => number | undefined;

package/dist/shared/recording.js

@@ -0,0 +1,25 @@
+import { SpawnfileError } from "./errors.js";
+export const DEFAULT_RECORD_KEEP_MS = 30 * 24 * 60 * 60_000;
+/** Absence disables recording; an empty declaration opts into the default window. */
+export const recordingKeepMs = (record) => {
+    if (record === undefined)
+        return undefined;
+    if (record.keep === undefined)
+        return DEFAULT_RECORD_KEEP_MS;
+    const match = /^([1-9][0-9]*)([mhd])$/u.exec(record.keep);
+    const factors = { m: 60_000, h: 60 * 60_000, d: 24 * 60 * 60_000 };
+    const milliseconds = match ? Number(match[1]) * factors[match[2]] : NaN;
+    if (!Number.isSafeInteger(milliseconds) || milliseconds <= 0) {
+        throw new SpawnfileError("validation_error", "record.keep must be a safe positive duration matching ^[1-9][0-9]*[mhd]$");
+    }
+    return milliseconds;
+};
+export const maxRecordingKeepMs = (records) => {
+    let maximum;
+    for (const record of records) {
+        const keep = recordingKeepMs(record);
+        if (keep !== undefined)
+            maximum = Math.max(maximum ?? 0, keep);
+    }
+    return maximum;
+};

package/dist/target/dockerCommandExecutorCore.js

@@ -44,7 +44,7 @@ const ordinaryOptions = (raw) => {
     return true;
 };
 const validate = (file, args, options) => {
-    if (typeof file !== "string" || file.length < 1 || file.length > 128 || file.includes("\0")
+    if (typeof file !== "string" || file.length < 1 || Buffer.byteLength(file, "utf8") > 1_024 || file.includes("\0")
         || Buffer.from(file, "utf8").toString("utf8") !== file
         || !Array.isArray(args) || nodeTypes.isProxy(args)
         || Object.getPrototypeOf(args) !== Array.prototype || args.length > 1_024

package/dist/target/dockerTargetBinding.js

@@ -50,7 +50,8 @@ const selectTargetContext = (input) => {
 const isDockerContextEndpoint = (endpoint) => endpoint.length <= 4_096
     && /^(?:npipe|ssh|tcp|unix|fd|http|https):\/\/[^\s]+$/u.test(endpoint);
 const selectTargetOptions = (input) => {
-    if (input.dockerCommand !== undefined && (typeof input.dockerCommand !== "string" || input.dockerCommand.length === 0 || input.dockerCommand.length > 128)) {
+    if (input.dockerCommand !== undefined && (typeof input.dockerCommand !== "string" || input.dockerCommand.length === 0
+        || input.dockerCommand.includes("\0") || Buffer.byteLength(input.dockerCommand, "utf8") > 1_024)) {
         return selectionFailure("validation_error");
     }
     if (input.timeoutMs !== undefined && (typeof input.timeoutMs !== "number" || !Number.isSafeInteger(input.timeoutMs) || input.timeoutMs < 1 || input.timeoutMs > 120_000)) {

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;
+};