spawnfile 0.1.17 → 0.1.19

package/dist/recording/deployment.js

@@ -0,0 +1,38 @@
+import { execFileSync } from "node:child_process";
+import { createDockerProbeGateway, dockerContextNameForTarget, inspectDockerDeployment } from "../deployment/index.js";
+import { SpawnfileError } from "../shared/index.js";
+import { resolveFeedStateDirectory } from "../volume/index.js";
+import { readRecordingFeedHistory } from "./history.js";
+import { syncMomentRecords } from "./sync.js";
+export const syncDeploymentMoments = async (options, handlers = {}) => {
+    const { record, recordPath } = options;
+    if (record.recording && !record.recording.agents) {
+        throw new SpawnfileError("runtime_error", "Deployment predates compiled recording facts; recompile and redeploy before record sync");
+    }
+    const agents = record.recording?.agents ?? [];
+    if (!agents.length)
+        return { written: 0, skipped: 0, nonExact: 0, failures: [], warnings: [] };
+    const inspections = await (handlers.inspectDockerDeployment ?? inspectDockerDeployment)(record, {
+        dockerCommand: options.dockerCommand, timeoutMs: options.timeoutMs
+    });
+    const gatewayFor = handlers.createDockerProbeGateway ?? createDockerProbeGateway;
+    const context = dockerContextNameForTarget(record.target);
+    const dockerTarget = context ? ["--context", context] : record.target.kind === "host" ? ["--host", record.target.value] : [];
+    return syncMomentRecords({
+        recordPath, agents, now: handlers.now,
+        execForAgent: (agent) => {
+            const units = record.units.filter((unit) => unit.contains.some((entry) => entry.kind === "agent" && entry.id === agent.node_id));
+            if (units.length !== 1)
+                throw new Error(`Expected one deployment unit for ${agent.node_id}, found ${units.length}`);
+            const unit = units[0], inspection = inspections.get(unit.id);
+            if (inspection?.running !== true)
+                throw new Error(`Container ${unit.id} is stopped or unreachable`);
+            const gateway = gatewayFor(record, unit, { inspection, dockerCommand: options.dockerCommand, timeoutMs: options.timeoutMs });
+            return (command) => gateway.exec(command);
+        },
+        readFeedHistory: handlers.readFeedHistory ?? (async (feed) => {
+            const state = resolveFeedStateDirectory(feed.volume_name, { exec: (_command, args) => execFileSync(options.dockerCommand ?? "docker", [...dockerTarget, ...args], { timeout: options.timeoutMs ?? 30_000, maxBuffer: 1024 * 1024 }) });
+            return readRecordingFeedHistory(state, (handlers.now ?? (() => new Date()))());
+        })
+    });
+};

package/dist/recording/history.d.ts

@@ -0,0 +1,16 @@
+import { type DeployResources } from "../deployment/index.js";
+import type { RecordingAgentReport } from "../report/index.js";
+import { type FeedLanding } from "../volume/index.js";
+export interface RecordingHistory<T> {
+    entries: T[];
+    errors: string[];
+    publicationPending?: true;
+}
+export declare const readRecordingDeployHistory: (recordPath: string) => Promise<RecordingHistory<DeployResources>>;
+export declare const readRecordingFeedHistory: (stateDir: string, now: Date) => RecordingHistory<FeedLanding>;
+/** Absence is unknown evidence, even for agents with no resource pins. Never use today's facts. */
+export declare const recordingHistoryAt: (entries: readonly DeployResources[], recordPath: string, startedAt: string, agentNodeId: string) => {
+    deployment: DeployResources | null;
+    agent?: RecordingAgentReport;
+    errors: string[];
+};

package/dist/recording/history.js

@@ -0,0 +1,47 @@
+import { acquirePidLock, deployResourcesAt, readDeployResources, reconcileDeploymentResources } from "../deployment/index.js";
+import { acquireFeedLock, ensureFeedLanding, readFeedLanded, readFeedLandings } from "../volume/index.js";
+export const readRecordingDeployHistory = async (recordPath) => {
+    try {
+        const release = await acquirePidLock(`${recordPath}.resource-log.lock`);
+        try {
+            await reconcileDeploymentResources(recordPath);
+            return readDeployResources(recordPath);
+        }
+        finally {
+            await release();
+        }
+    }
+    catch {
+        return { ...readDeployResources(recordPath), publicationPending: true };
+    }
+};
+export const readRecordingFeedHistory = (stateDir, now) => {
+    try {
+        const lock = acquireFeedLock(stateDir);
+        if (!lock)
+            throw new Error("Feed history publication pending");
+        try {
+            const { record, reason } = readFeedLanded(stateDir);
+            if (!record?.recording || reason)
+                throw new Error(reason ?? "Missing authoritative feed recording");
+            ensureFeedLanding({ stateDir }, record, now);
+            return readFeedLandings(stateDir);
+        }
+        finally {
+            lock.release();
+        }
+    }
+    catch {
+        return { ...readFeedLandings(stateDir), publicationPending: true };
+    }
+};
+/** Absence is unknown evidence, even for agents with no resource pins. Never use today's facts. */
+export const recordingHistoryAt = (entries, recordPath, startedAt, agentNodeId) => {
+    const deployment = deployResourcesAt(entries, recordPath, startedAt, agentNodeId);
+    if (!deployment)
+        return { deployment, errors: [`Missing deployment history at ${startedAt}`] };
+    const agents = deployment.recording_agents?.filter((agent) => agent.node_id === agentNodeId) ?? [];
+    return agents.length === 1 ? { deployment, agent: agents[0], errors: [] } : {
+        deployment, errors: [`${agents.length ? "Ambiguous" : "Missing"} activation recording facts for ${agentNodeId} at ${startedAt}`]
+    };
+};

package/dist/recording/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./types.js";
+export * from "./moment.js";
+export * from "./compose.js";
+export * from "./parse.js";
+export * from "./store.js";
+export * from "./sync.js";
+export * from "./deployment.js";
+export * from "./history.js";
+export * from "./read.js";

package/dist/recording/index.js

@@ -0,0 +1,9 @@
+export * from "./types.js";
+export * from "./moment.js";
+export * from "./compose.js";
+export * from "./parse.js";
+export * from "./store.js";
+export * from "./sync.js";
+export * from "./deployment.js";
+export * from "./history.js";
+export * from "./read.js";

package/dist/recording/moment.d.ts

@@ -0,0 +1,61 @@
+import { z } from "zod";
+export declare const recordedSha256Schema: z.ZodString;
+export declare const recordedCommitSchema: z.ZodString;
+export declare const momentRecordSchema: z.ZodObject<{
+    version: z.ZodLiteral<"spawnfile.moment-record.v1">;
+    agent: z.ZodString;
+    wake: z.ZodObject<{
+        at: z.ZodISODateTime;
+        startedAt: z.ZodISODateTime;
+        executionId: z.ZodString;
+        deliveries: z.ZodArray<z.ZodObject<{
+            deliveryId: z.ZodString;
+            kind: z.ZodString;
+            occurredAt: z.ZodISODateTime;
+        }, z.core.$strict>>;
+        surface: z.ZodOptional<z.ZodLiteral<"moltnet">>;
+        room: z.ZodOptional<z.ZodString>;
+        from: z.ZodOptional<z.ZodString>;
+        messageId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    recordedAt: z.ZodISODateTime;
+    exact: z.ZodBoolean;
+    errors: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    resources: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodLiteral<"git">;
+        commit: z.ZodString;
+        sha256: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodLiteral<"bundle">;
+        sha256: z.ZodString;
+    }, z.core.$strict>], "kind">>;
+    feeds: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        revision: z.ZodString;
+        tree: z.ZodString;
+        commit: z.ZodOptional<z.ZodString>;
+        ref: z.ZodOptional<z.ZodString>;
+        paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        landedAt: z.ZodISODateTime;
+        period: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    memory: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        declaredBy: z.ZodString;
+        seq: z.ZodNumber;
+        generation: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    moltnet: z.ZodArray<z.ZodObject<{
+        network: z.ZodString;
+        cursor: z.ZodISODateTime;
+        messageIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    volumes: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        snapshot: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type MomentRecord = z.infer<typeof momentRecordSchema>;
+export declare const parseMomentRecord: (payload: string) => MomentRecord;

package/dist/recording/moment.js

@@ -0,0 +1,36 @@
+import { z } from "zod";
+import { trainingInstantSchema } from "../manifest/index.js";
+import { MOMENT_RECORD_VERSION } from "./types.js";
+const text = z.string().min(1);
+const count = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+export const recordedSha256Schema = z.string().regex(/^sha256:[a-f0-9]{64}$/u);
+export const recordedCommitSchema = z.string()
+    .regex(/^(?:[a-fA-F0-9]{40}|[a-fA-F0-9]{64})$/u, "Expected a full 40- or 64-hex commit object id")
+    .toLowerCase();
+const unique = (schema, key) => z.array(schema).superRefine((items, context) => {
+    const keys = new Set();
+    items.forEach((item, index) => {
+        const id = key(item);
+        if (keys.has(id))
+            context.addIssue({ code: "custom", message: `Duplicate identity ${id}`, path: [index] });
+        keys.add(id);
+    });
+});
+export const momentRecordSchema = z.object({
+    version: z.literal(MOMENT_RECORD_VERSION), agent: text,
+    wake: z.object({ at: trainingInstantSchema, startedAt: trainingInstantSchema, executionId: text,
+        deliveries: z.array(z.object({ deliveryId: text, kind: text, occurredAt: trainingInstantSchema }).strict()).min(1),
+        surface: z.literal("moltnet").optional(), room: z.string().optional(),
+        from: z.string().optional(), messageId: text.optional() }).strict(),
+    recordedAt: trainingInstantSchema, exact: z.boolean(), errors: z.array(z.string()).optional(),
+    resources: unique(z.discriminatedUnion("kind", [
+        z.object({ id: text, kind: z.literal("git"), commit: recordedCommitSchema, sha256: recordedSha256Schema.optional() }).strict(),
+        z.object({ id: text, kind: z.literal("bundle"), sha256: recordedSha256Schema }).strict()
+    ]), (r) => r.id),
+    feeds: unique(z.object({ id: text, revision: text, tree: text, commit: recordedCommitSchema.optional(), ref: text.optional(),
+        paths: z.array(text).optional(), landedAt: trainingInstantSchema, period: text.optional() }).strict(), (r) => r.id),
+    memory: unique(z.object({ id: text, declaredBy: text, seq: count, generation: count.optional() }).strict(), (r) => JSON.stringify([r.declaredBy, r.id])),
+    moltnet: unique(z.object({ network: text, cursor: trainingInstantSchema, messageIds: z.array(text).optional() }).strict(), (r) => r.network),
+    volumes: unique(z.object({ id: text, snapshot: text }).strict(), (r) => r.id)
+}).strict();
+export const parseMomentRecord = (payload) => momentRecordSchema.parse(JSON.parse(payload));

package/dist/recording/parse.d.ts

@@ -0,0 +1,15 @@
+import { type MemoryLedgerEntry, type WakeMomentRow } from "./types.js";
+export interface RecordingJsonlRead<T> {
+    entries: T[];
+    errors: string[];
+}
+export interface RecordingJsonlParser<T> {
+    write: (chunk: string) => void;
+    finish: () => RecordingJsonlRead<T>;
+}
+export declare const createWakeMomentsParser: () => RecordingJsonlParser<WakeMomentRow>;
+export declare const createMemoryLedgerParser: () => RecordingJsonlParser<MemoryLedgerEntry>;
+/** Preserve valid rows and report each malformed line, including a torn final append. */
+export declare const parseWakeMoments: (payload: string) => RecordingJsonlRead<WakeMomentRow>;
+/** Missing/invalid sequence numbers are unknown history; never infer them from line order. */
+export declare const parseMemoryLedger: (payload: string) => RecordingJsonlRead<MemoryLedgerEntry>;

package/dist/recording/parse.js

@@ -0,0 +1,74 @@
+import { z } from "zod";
+import { WAKE_MOMENT_VERSION } from "./types.js";
+const text = z.string().min(1);
+const instant = z.iso.datetime({ offset: true }).refine((value) => Number.isFinite(Date.parse(value)));
+const count = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+const snapshot = z.object({
+    id: text.regex(/^[A-Za-z0-9._-]{1,128}$/u),
+    snapshot: text.regex(/^\d{8}T\d{9}Z-[A-Za-z0-9._-]{1,200}$/u),
+    files: count, copied: count, linked: count, skipped: count
+}).strict();
+const wakeMomentSchema = z.object({
+    version: z.literal(WAKE_MOMENT_VERSION), agent_id: text, execution_id: text, started_at: instant,
+    deliveries: z.array(z.object({
+        acceptance_id: text, delivery_id: text, kind: text, occurred_at: instant
+    }).strict()).min(1),
+    snapshots: z.array(snapshot).max(16).refine((values) => new Set(values.map(({ id }) => id)).size === values.length),
+    error: text.max(2048).optional()
+}).strict();
+// Only the public cursor fields are consumed; event contents never enter a moment record.
+const memoryLedgerSchema = z.object({ seq: count.positive(), createdAt: instant });
+const lineParser = (label, schema, maxBytes) => {
+    const entries = [], errors = [];
+    let pending = "", lineNumber = 0, oversized = false;
+    const parseLine = (line) => {
+        lineNumber += 1;
+        try {
+            if (oversized || (maxBytes !== undefined && Buffer.byteLength(line, "utf8") + 1 > maxBytes))
+                throw new Error("row size limit");
+            entries.push(schema.parse(JSON.parse(line)));
+        }
+        catch {
+            errors.push(`${label} line ${lineNumber}: invalid JSON or entry`);
+        }
+        oversized = false;
+    };
+    return {
+        write(chunk) {
+            const lines = chunk.split("\n");
+            for (let index = 0; index < lines.length; index += 1) {
+                if (!oversized)
+                    pending += lines[index];
+                if (maxBytes !== undefined && Buffer.byteLength(pending, "utf8") + 1 > maxBytes) {
+                    oversized = true;
+                    pending = "";
+                }
+                if (index < lines.length - 1) {
+                    parseLine(pending);
+                    pending = "";
+                }
+            }
+        },
+        finish() {
+            if (pending || oversized) {
+                parseLine(pending);
+                pending = "";
+            }
+            return { entries, errors };
+        }
+    };
+};
+export const createWakeMomentsParser = () => lineParser("wake moments", wakeMomentSchema, 4_194_304);
+export const createMemoryLedgerParser = () => lineParser("memory ledger", memoryLedgerSchema);
+/** Preserve valid rows and report each malformed line, including a torn final append. */
+export const parseWakeMoments = (payload) => {
+    const parser = createWakeMomentsParser();
+    parser.write(payload);
+    return parser.finish();
+};
+/** Missing/invalid sequence numbers are unknown history; never infer them from line order. */
+export const parseMemoryLedger = (payload) => {
+    const parser = createMemoryLedgerParser();
+    parser.write(payload);
+    return parser.finish();
+};

package/dist/recording/read.d.ts

@@ -0,0 +1,8 @@
+import type { UsageLedgerExec } from "../runtime/usageLedgerRead.js";
+import type { RecordingJsonlParser, RecordingJsonlRead } from "./parse.js";
+/** Each exec response is bounded (base64 adds 1/3); decode UTF-8 across byte boundaries.
+ * Pin the initial length/inode so appends cannot make sync chase a growing ledger forever. */
+export declare const readRecordingJsonl: <T>(exec: UsageLedgerExec, file: string, parser: RecordingJsonlParser<T>, chunkBytes?: number) => Promise<RecordingJsonlRead<T> & {
+    failure?: string;
+    missing?: true;
+}>;

package/dist/recording/read.js

@@ -0,0 +1,61 @@
+import { StringDecoder } from "node:string_decoder";
+import { z } from "zod";
+// Daimon's generated organization image uses its Node standalone base (runtime metadata),
+// and runs the Node daimon-runtime launcher. No optional container executable is required.
+const readChunkScript = `
+const fs = require('node:fs');
+try {
+  const fd = fs.openSync(process.argv[1], 'r');
+  try {
+    const stat = fs.fstatSync(fd);
+    if (!stat.isFile()) throw {code:'NOT_REGULAR_FILE'};
+    const bytes = Buffer.alloc(Number(process.argv[3]));
+    const count = fs.readSync(fd, bytes, 0, bytes.length, Number(process.argv[2]));
+    process.stdout.write(JSON.stringify({size:stat.size, identity:stat.dev+':'+stat.ino, data:bytes.subarray(0,count).toString('base64')}));
+  } finally { fs.closeSync(fd); }
+} catch (error) {
+  if (error.code === 'ENOENT') process.stdout.write('null');
+  else { process.stderr.write(String(error.code || 'READ_FAILED')); process.exitCode = 1; }
+}`;
+const chunkSchema = z.object({
+    size: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER), identity: z.string().min(1),
+    data: z.string().regex(/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u)
+}).strict().nullable();
+/** Each exec response is bounded (base64 adds 1/3); decode UTF-8 across byte boundaries.
+ * Pin the initial length/inode so appends cannot make sync chase a growing ledger forever. */
+export const readRecordingJsonl = async (exec, file, parser, chunkBytes = 256 * 1024) => {
+    const decoder = new StringDecoder("utf8");
+    let offset = 0, length, identity;
+    try {
+        if (!Number.isSafeInteger(chunkBytes) || chunkBytes <= 0 || chunkBytes > 256 * 1024)
+            throw new Error("Invalid recording chunk size");
+        do {
+            const count = Math.min(chunkBytes, length === undefined ? chunkBytes : length - offset);
+            const { stdout } = await exec(["node", "-e", readChunkScript, file, String(offset), String(count)]);
+            const chunk = chunkSchema.parse(JSON.parse(stdout));
+            if (chunk === null) {
+                if (length !== undefined)
+                    throw new Error("Runtime file disappeared during read");
+                return { ...parser.finish(), missing: true };
+            }
+            length ??= chunk.size;
+            identity ??= chunk.identity;
+            if (identity !== chunk.identity || chunk.size < length)
+                throw new Error("Runtime file replaced or truncated during read");
+            const bytes = Buffer.from(chunk.data, "base64");
+            if (bytes.length > count || bytes.length < Math.min(count, length - offset))
+                throw new Error("Incomplete runtime file chunk");
+            const bounded = bytes.subarray(0, length - offset);
+            parser.write(decoder.write(bounded));
+            offset += bounded.length;
+        } while (offset < length);
+        parser.write(decoder.end());
+        return parser.finish();
+    }
+    catch (error) {
+        // The remote script emits codes only. Do not expose raw exec messages or partial stdout.
+        const reason = error instanceof Error && /^(?:Invalid recording|Runtime file|Incomplete runtime)/u.test(error.message)
+            ? error.message : "Runtime file exec or chunk decoding failed";
+        return { entries: [], errors: [], failure: reason };
+    }
+};

package/dist/recording/store.d.ts

@@ -0,0 +1,10 @@
+import type { MomentRecord, WakeMomentRow } from "./types.js";
+/** Project records share a directory, so each gets its own state subdirectory. */
+export declare const deploymentMomentsDirectory: (recordPath: string) => string;
+export declare const momentFileName: (row: WakeMomentRow) => string;
+export declare const withMomentStore: <T>(recordPath: string, slug: string, action: (directory: string) => Promise<T>) => Promise<T>;
+/** Caller holds the store lock. Existing records are never replaced, including non-exact ones. */
+export declare const writeMomentRecord: (directory: string, record: MomentRecord, row: WakeMomentRow) => Promise<boolean>;
+export declare const newestMomentInstant: (directory: string, agentId: string) => Promise<number>;
+/** Retention reads the recorded instant, never mtime; preserve all newest-instant ties. */
+export declare const pruneMomentRecords: (directory: string, agentId: string, now: Date, keepMs: number) => Promise<void>;

package/dist/recording/store.js

@@ -0,0 +1,94 @@
+import { createHash } from "node:crypto";
+import { lstat, mkdir, readFile, readdir, unlink } from "node:fs/promises";
+import path from "node:path";
+import { acquirePidLock } from "../deployment/pidLock.js";
+import { syncDirectory, writeDurableFile } from "../filesystem/index.js";
+/** Project records share a directory, so each gets its own state subdirectory. */
+export const deploymentMomentsDirectory = (recordPath) => path.join(path.dirname(recordPath), ...(path.basename(recordPath) === "record.json" ? [] : [path.basename(recordPath, ".json")]), "moments");
+/** JSON object keys are sorted recursively; array order and all row values remain significant. */
+const canonicalJson = (value) => {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (value !== null && typeof value === "object")
+        return `{${Object.entries(value)
+            .filter(([, entry]) => entry !== undefined).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)
+            .map(([key, entry]) => `${JSON.stringify(key)}:${canonicalJson(entry)}`).join(",")}}`;
+    return JSON.stringify(value);
+};
+export const momentFileName = (row) => {
+    const { started_at: startedAt, execution_id: executionId } = row;
+    const compact = new Date(startedAt).toISOString().replace(/[-:.]/gu, "");
+    const safeId = /^[A-Za-z0-9._-]{1,128}$/u.test(executionId)
+        ? executionId : `sha256-${createHash("sha256").update(executionId).digest("hex")}`;
+    const attempt = createHash("sha256").update(canonicalJson(row)).digest("hex").slice(0, 12);
+    return `${compact}-${safeId}-${attempt}.json`;
+};
+const ensurePrivateDirectory = async (directory) => {
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const stat = await lstat(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new Error(`Moment directory is not a real directory: ${directory}`);
+};
+export const withMomentStore = async (recordPath, slug, action) => {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/u.test(slug))
+        throw new Error("Unsafe recording agent slug");
+    const root = deploymentMomentsDirectory(recordPath);
+    await ensurePrivateDirectory(root);
+    const directory = path.join(root, slug);
+    await ensurePrivateDirectory(directory);
+    const release = await acquirePidLock(path.join(directory, ".sync.lock"));
+    try {
+        return await action(directory);
+    }
+    finally {
+        await release();
+    }
+};
+/** Caller holds the store lock. Existing records are never replaced, including non-exact ones. */
+export const writeMomentRecord = async (directory, record, row) => {
+    const file = path.join(directory, momentFileName(row));
+    try {
+        const stat = await lstat(file);
+        if (!stat.isFile() || stat.isSymbolicLink())
+            throw new Error(`Moment is not a regular file: ${file}`);
+        const existing = JSON.parse(await readFile(file, "utf8"));
+        if (existing.agent !== record.agent || existing.wake?.executionId !== record.wake.executionId
+            || existing.wake?.startedAt !== record.wake.startedAt)
+            throw new Error(`Moment filename collision: ${file}`);
+        return false;
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    await writeDurableFile(file, `${JSON.stringify(record, null, 2)}\n`);
+    return true;
+};
+const storedMoments = async (directory, agentId) => {
+    const candidates = [];
+    for (const name of (await readdir(directory)).sort()) {
+        if (!name.endsWith(".json"))
+            continue;
+        const file = path.join(directory, name), stat = await lstat(file);
+        if (!stat.isFile() || stat.isSymbolicLink())
+            throw new Error(`Moment is not a regular file: ${file}`);
+        const record = JSON.parse(await readFile(file, "utf8"));
+        const started = Date.parse(record.wake?.startedAt);
+        if (record.version !== "spawnfile.moment-record.v1" || record.agent !== agentId || !Number.isFinite(started)) {
+            throw new Error(`Invalid retained moment: ${file}`);
+        }
+        candidates.push({ file, started });
+    }
+    return candidates;
+};
+export const newestMomentInstant = async (directory, agentId) => (await storedMoments(directory, agentId)).reduce((latest, item) => Math.max(latest, item.started), -Infinity);
+/** Retention reads the recorded instant, never mtime; preserve all newest-instant ties. */
+export const pruneMomentRecords = async (directory, agentId, now, keepMs) => {
+    const candidates = await storedMoments(directory, agentId);
+    const newest = candidates.reduce((latest, item) => Math.max(latest, item.started), -Infinity);
+    const expired = candidates.filter((item) => item.started < newest && item.started < now.getTime() - keepMs);
+    for (const item of expired)
+        await unlink(item.file);
+    if (expired.length)
+        await syncDirectory(directory);
+};

package/dist/recording/sync.d.ts

@@ -0,0 +1,24 @@
+import { type DeployResources } from "../deployment/index.js";
+import type { RecordingAgentReport } from "../report/index.js";
+import type { UsageLedgerExec } from "../runtime/usageLedgerRead.js";
+import type { FeedLanding } from "../volume/index.js";
+import { type RecordingHistory } from "./history.js";
+export interface SyncMomentRecordsOptions {
+    recordPath: string;
+    agents: readonly RecordingAgentReport[];
+    execForAgent: (agent: RecordingAgentReport) => UsageLedgerExec;
+    readFeedHistory: (feed: RecordingAgentReport["feeds"][number]) => Promise<RecordingHistory<FeedLanding>>;
+    readDeployHistory?: (recordPath: string) => RecordingHistory<DeployResources> | Promise<RecordingHistory<DeployResources>>;
+    readChunkBytes?: number;
+    now?: () => Date;
+}
+export interface SyncMomentRecordsResult {
+    written: number;
+    skipped: number;
+    nonExact: number;
+    /** Operational errors cause nonzero exit; data errors only qualify exactness. */
+    failures: string[];
+    warnings: string[];
+}
+/** Artifact egress only. No turn, snapshot copy, network-history fetch, or source resolution. */
+export declare const syncMomentRecords: (options: SyncMomentRecordsOptions) => Promise<SyncMomentRecordsResult>;

package/dist/recording/sync.js

@@ -0,0 +1,126 @@
+import path from "node:path";
+import { deployResourcesAt } from "../deployment/index.js";
+import { composeMomentRecord } from "./compose.js";
+import { readRecordingDeployHistory, recordingHistoryAt } from "./history.js";
+import { createMemoryLedgerParser, createWakeMomentsParser } from "./parse.js";
+import { readRecordingJsonl } from "./read.js";
+import { newestMomentInstant, pruneMomentRecords, withMomentStore, writeMomentRecord } from "./store.js";
+/** Artifact egress only. No turn, snapshot copy, network-history fetch, or source resolution. */
+export const syncMomentRecords = async (options) => {
+    const result = { written: 0, skipped: 0, nonExact: 0, failures: [], warnings: [] };
+    if (!options.agents.length)
+        return result;
+    const now = (options.now ?? (() => new Date()))();
+    if (!Number.isFinite(now.getTime()))
+        throw new Error("Recording requires a valid clock");
+    const deploy = await (options.readDeployHistory ?? readRecordingDeployHistory)(options.recordPath);
+    const deployTail = deploy.entries.at(-1);
+    const deployPendingSince = deployTail ? Date.parse(deployTail.activated_at) : -Infinity;
+    const currentDeployment = deployResourcesAt(deploy.entries, options.recordPath, now);
+    for (const agent of options.agents) {
+        try {
+            if (!Number.isSafeInteger(agent.keep_ms) || agent.keep_ms <= 0)
+                throw new Error("Invalid recording retention");
+            const exec = options.execForAgent(agent);
+            const directories = new Set([agent.directory, ...deploy.entries
+                    .filter((entry) => entry.deployment_id === path.resolve(options.recordPath))
+                    .flatMap((entry) => entry.recording_agents ?? []).filter((entry) => entry.node_id === agent.node_id)
+                    .map((entry) => entry.directory)]);
+            const errors = deploy.errors.map((error) => `Deploy history: ${error}`);
+            const rowsBySlug = new Map();
+            rowsBySlug.set(agent.slug, []);
+            for (const directory of directories) {
+                // Retention still runs when a log has become empty since the previous sync.
+                rowsBySlug.set(path.posix.basename(directory), rowsBySlug.get(path.posix.basename(directory)) ?? []);
+                const wake = await readRecordingJsonl(exec, path.posix.join(directory, "wake-moments.jsonl"), createWakeMomentsParser(), options.readChunkBytes);
+                if (wake.failure)
+                    throw new Error(`Wake moments unreadable: ${wake.failure}`);
+                errors.push(...wake.errors);
+                for (const row of wake.entries) {
+                    if (row.agent_id !== agent.node_id) {
+                        errors.push(`Foreign wake row for ${row.agent_id}`);
+                        continue;
+                    }
+                    const historical = recordingHistoryAt(deploy.entries, options.recordPath, row.started_at, agent.node_id).agent;
+                    const slug = historical?.slug ?? agent.slug;
+                    const rows = rowsBySlug.get(slug) ?? [];
+                    rows.push({ row, directory });
+                    rowsBySlug.set(slug, rows);
+                }
+            }
+            const memoryCache = Object.create(null);
+            const feedCache = new Map();
+            result.warnings.push(...errors.map((error) => `${agent.node_id}: ${error}`));
+            for (const [slug, rows] of rowsBySlug)
+                await withMomentStore(options.recordPath, slug, async (directory) => {
+                    const newest = rows.reduce((latest, { row }) => Math.max(latest, Date.parse(row.started_at)), await newestMomentInstant(directory, agent.node_id));
+                    for (const { row, directory: sourceDirectory } of rows) {
+                        const started = Date.parse(row.started_at);
+                        // Do not recreate already-pruned attempts on every sync while Daimon retains its row log.
+                        if (started < now.getTime() - agent.keep_ms && started < newest) {
+                            result.skipped += 1;
+                            continue;
+                        }
+                        const { agent: historical, deployment } = recordingHistoryAt(deploy.entries, options.recordPath, row.started_at, agent.node_id);
+                        const rowErrors = [...errors];
+                        if (deploy.publicationPending && started >= deployPendingSince)
+                            rowErrors.push("Deploy history publication pending");
+                        if (historical && historical.directory !== sourceDirectory)
+                            rowErrors.push("Wake row directory differs from activation recording facts");
+                        const feedLandings = Object.create(null);
+                        for (const feed of historical?.feeds ?? []) {
+                            const key = JSON.stringify([feed.id, feed.volume_name]);
+                            if (!feedCache.has(key)) {
+                                try {
+                                    feedCache.set(key, await options.readFeedHistory(feed));
+                                }
+                                catch {
+                                    feedCache.set(key, { entries: [], errors: [`cannot resolve or read host landing history for volume ${feed.volume_name}`] });
+                                }
+                            }
+                            const history = feedCache.get(key);
+                            feedLandings[feed.id] = history.entries.filter((entry) => entry.resource === feed.id && entry.volume === feed.volume_name);
+                            const tail = history.entries.at(-1);
+                            const pendingSince = tail ? Date.parse(tail.landed_at) : -Infinity;
+                            if (history.publicationPending && started >= pendingSince)
+                                rowErrors.push(`Feed ${feed.id}: history publication pending`);
+                            rowErrors.push(...history.errors.map((error) => `Feed ${feed.id}: ${error}`));
+                        }
+                        const memoryLedgers = Object.create(null);
+                        for (const bank of historical?.memory ?? []) {
+                            if (bank.ledger_path === null)
+                                continue;
+                            const current = agent.memory.some((entry) => entry.id === bank.id && entry.declared_by === bank.declared_by
+                                && entry.ledger_path === bank.ledger_path);
+                            // Older facts do not carry a physical volume ID. A different report cannot
+                            // establish that today's readable path still names the historical bank.
+                            if (!current || deployment?.report_sha256 !== currentDeployment?.report_sha256) {
+                                memoryLedgers[bank.ledger_path] = { entries: [], errors: ["Historical bank identity or mount cannot be verified in the current deployment"] };
+                                continue;
+                            }
+                            if (!memoryCache[bank.ledger_path]) {
+                                const ledger = await readRecordingJsonl(exec, bank.ledger_path, createMemoryLedgerParser(), options.readChunkBytes);
+                                memoryCache[bank.ledger_path] = ledger.failure || ledger.missing
+                                    ? { entries: [], errors: [`Ledger unreadable: ${ledger.failure ?? "runtime file is absent"}`] } : ledger;
+                            }
+                            memoryLedgers[bank.ledger_path] = memoryCache[bank.ledger_path];
+                        }
+                        const record = composeMomentRecord({ row, agentNodeId: agent.node_id, deploymentRecordPath: options.recordPath,
+                            feedLandings, deployResources: deploy.entries, memoryLedgers, errors: rowErrors, recordedAt: now.toISOString() });
+                        if (await writeMomentRecord(directory, record, row)) {
+                            result.written += 1;
+                            if (!record.exact)
+                                result.nonExact += 1;
+                        }
+                        else
+                            result.skipped += 1;
+                    }
+                    await pruneMomentRecords(directory, agent.node_id, now, agent.keep_ms);
+                });
+        }
+        catch (error) {
+            result.failures.push(`${agent.node_id}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return result;
+};