spawnfile 0.1.14 → 0.1.18

package/dist/manifest/workspaceSchemas.js

@@ -1,4 +1,6 @@
 import { z } from "zod";
+import { argvSchema, pinnedImageSchema } from "./commandSchemas.js";
+import { volumeFeedSchema } from "./volumeFeedSchemas.js";
 const workspaceResourceModeSchema = z.enum(["mutable", "readonly"]);
 const workspaceResourceSharingSchema = z.enum(["per_agent", "team"]);
 export const teamWorkspaceDocsSchema = z
@@ -51,9 +53,36 @@ const resourceMountSchema = z
         });
     }
 });
+/** Host-side credentials for a `fetch: build` git resource: a key file path, or an env var holding the key. */
+const gitResourceAuthSchema = z
+    .object({
+    ssh_key: z.string().trim().min(1).optional(),
+    ssh_key_env: z.string().trim().regex(/^[A-Za-z_][A-Za-z0-9_]*$/u, "ssh_key_env must be an environment variable name").optional()
+})
+    .strict()
+    .refine((value) => (value.ssh_key === undefined) !== (value.ssh_key_env === undefined), {
+    message: "git resource auth must declare exactly one of ssh_key or ssh_key_env"
+});
+/**
+ * True when a URL may carry a credential: any password, any userinfo on a
+ * non-SSH URL (a token is often sent as the user name), or a query string.
+ * An SSH user name (`git@host:...`, `ssh://git@host/...`) is not a secret.
+ */
+const urlEmbedsCredential = (url) => {
+    const scheme = /^([a-z][a-z0-9+.-]*):\/\/([^/]*)/iu.exec(url);
+    if (!scheme)
+        return url.includes("?");
+    const authority = scheme[2], userinfo = authority.includes("@") ? authority.slice(0, authority.lastIndexOf("@")) : undefined;
+    if (url.includes("?") || userinfo?.includes(":"))
+        return true;
+    return userinfo !== undefined && !/^(ssh|git\+ssh|ssh\+git)$/iu.test(scheme[1]);
+};
 const teamWorkspaceResourceGitSchema = z
     .object({
+    auth: gitResourceAuthSchema.optional(),
     branch: z.string().trim().optional(),
+    exclude: z.array(z.string().trim().min(1)).optional(),
+    fetch: z.enum(["start", "build"]).optional(),
     id: z.string().trim().min(1),
     kind: z.literal("git"),
     mount: resourceMountSchema,
@@ -72,6 +101,25 @@ const teamWorkspaceResourceGitSchema = z
             message: "git resources may declare at most one of branch, tag, or ref"
         });
     }
+    if (value.fetch === "build") {
+        if ([value.branch, value.tag, value.ref].some((selector) => selector !== undefined && selector === "")) {
+            context.addIssue({ code: z.ZodIssueCode.custom, message: "git resource branch, tag, or ref must not be empty with fetch: build" });
+        }
+        if (value.mode !== "readonly") {
+            context.addIssue({ code: z.ZodIssueCode.custom, message: "git resources with fetch: build are pinned image content and must be mode: readonly" });
+        }
+        if (urlEmbedsCredential(value.url)) {
+            context.addIssue({ code: z.ZodIssueCode.custom, message: "git resource url must not embed a credential; declare auth instead" });
+        }
+    }
+    else {
+        if (value.auth !== undefined) {
+            context.addIssue({ code: z.ZodIssueCode.custom, message: "git resource auth requires fetch: build; a container-start clone never receives host credentials" });
+        }
+        if (value.exclude !== undefined) {
+            context.addIssue({ code: z.ZodIssueCode.custom, message: "git resource exclude requires fetch: build" });
+        }
+    }
     if (value.sharing === "team") {
         context.addIssue({
             code: z.ZodIssueCode.custom,
@@ -81,6 +129,7 @@ const teamWorkspaceResourceGitSchema = z
 });
 const teamWorkspaceResourceVolumeSchema = z
     .object({
+    feed: volumeFeedSchema.optional(),
     id: z.string().trim().min(1),
     kind: z.literal("volume"),
     mount: resourceMountSchema,
@@ -88,9 +137,66 @@ const teamWorkspaceResourceVolumeSchema = z
     name: z.string().trim().optional(),
     sharing: workspaceResourceSharingSchema.optional()
 })
-    .strict();
-const teamWorkspaceResourceSchema = z.discriminatedUnion("kind", [
+    .strict()
+    .superRefine((value, context) => {
+    if (!value.feed)
+        return;
+    // The host job addresses the volume by its exact host name, so a derived, unpublished name cannot be fed.
+    if (!value.name)
+        context.addIssue({ code: z.ZodIssueCode.custom, message: "fed volumes must declare name" });
+    // A readonly volume is made read-only by the container rewriting the whole volume on every start;
+    // a fed volume is instead frozen tree by tree on the host, so it stays mutable at the mount.
+    if (value.mode !== "mutable")
+        context.addIssue({ code: z.ZodIssueCode.custom, message: "fed volumes must declare mode: mutable; the host freezes every landed tree" });
+});
+/** Declared inputs Spawnfile builds into the bundle archive. Exactly one input kind per bundle. */
+const workspaceBundleFilesSchema = z.object({
+    exclude: z.array(z.string().trim().min(1)).optional(),
+    /** Archive the tree of this commit (any git revision) instead of the work tree; needs no clean checkout. */
+    ref: z.string().trim().min(1).optional(),
+    root: z.string().trim().min(1)
+}).strict();
+/**
+ * Declared inputs Spawnfile builds into the bundle archive. Exactly one input kind per bundle:
+ * `files` (git-tracked files), `dependencies` (lockfile installed for the target platform in a
+ * pinned image) or `generated` (a declared command writing an output directory from declared inputs).
+ */
+const workspaceBundleBuildSchema = z.object({
+    dependencies: z.object({
+        check: argvSchema.optional(),
+        dev: z.boolean().optional(),
+        directory: z.string().trim().min(1),
+        image: pinnedImageSchema,
+        manager: z.literal("npm").optional(),
+        scripts: z.boolean().optional()
+    }).strict().optional(),
+    files: workspaceBundleFilesSchema.optional(),
+    generated: z.object({
+        command: argvSchema,
+        cwd: z.string().trim().min(1).optional(),
+        image: pinnedImageSchema.optional(),
+        inputs: z.array(workspaceBundleFilesSchema).min(1),
+        timeout_seconds: z.number().int().positive().max(86_400).optional(),
+        tools: z.array(argvSchema).optional()
+    }).strict().optional()
+}).strict().superRefine((value, context) => {
+    if ([value.files, value.dependencies, value.generated].filter((kind) => kind !== undefined).length !== 1) {
+        context.addIssue({ code: z.ZodIssueCode.custom, message: "bundle build must declare exactly one of files, dependencies or generated" });
+    }
+});
+const teamWorkspaceResourceBundleSchema = z.object({
+    build: workspaceBundleBuildSchema.optional(),
+    id: z.string().trim().min(1), kind: z.literal("bundle"), mount: resourceMountSchema,
+    mode: z.literal("readonly"), sha256: z.string().regex(/^sha256:[a-f0-9]{64}$/u).optional(),
+    sharing: z.literal("per_agent").optional(), source: z.string().trim().min(1).optional()
+}).strict().superRefine((value, context) => {
+    if ((value.source === undefined) === (value.build === undefined)) {
+        context.addIssue({ code: z.ZodIssueCode.custom, message: "bundle resources must declare exactly one of source or build" });
+    }
+});
+export const teamWorkspaceResourceSchema = z.discriminatedUnion("kind", [
     teamWorkspaceResourceGitSchema,
+    teamWorkspaceResourceBundleSchema,
     teamWorkspaceResourceVolumeSchema
 ]);
 const workspaceSkillRequirementSchema = z
@@ -119,7 +225,10 @@ export const teamWorkspaceSchema = z
     const normalizeResourceIdentity = (resource) => {
         if (resource.kind === "git") {
             return JSON.stringify({
+                auth: resource.auth ?? null,
                 branch: resource.branch?.trim() ?? "",
+                exclude: resource.exclude ?? null,
+                fetch: resource.fetch ?? "start",
                 kind: "git",
                 mode: resource.mode,
                 mount: normalizeMount(resource.mount),
@@ -129,7 +238,13 @@ export const teamWorkspaceSchema = z
                 url: resource.url
             });
         }
+        if (resource.kind === "bundle")
+            return JSON.stringify({
+                build: resource.build ?? null, kind: resource.kind, mode: resource.mode, mount: normalizeMount(resource.mount),
+                sha256: resource.sha256 ?? null, sharing: resource.sharing ?? "per_agent", source: resource.source ?? null
+            });
         return JSON.stringify({
+            ...(resource.feed ? { feed: resource.feed } : {}),
             kind: "volume",
             mode: resource.mode,
             mount: normalizeMount(resource.mount),

package/dist/recording/compose.d.ts

@@ -0,0 +1,3 @@
+import { type ComposeMomentRecordInput, type MomentRecord } from "./types.js";
+/** Compose only supplied evidence at the turn boundary; this function reads no files or clock. */
+export declare const composeMomentRecord: (input: ComposeMomentRecordInput) => MomentRecord;

package/dist/recording/compose.js

@@ -0,0 +1,93 @@
+import { feedLandingAt } from "../volume/index.js";
+import { recordingHistoryAt } from "./history.js";
+import { MOMENT_RECORD_VERSION } from "./types.js";
+const orderedUnique = (values) => [...new Set(values)].sort();
+/** Compose only supplied evidence at the turn boundary; this function reads no files or clock. */
+export const composeMomentRecord = (input) => {
+    const { row, agentNodeId } = input;
+    const errors = [...(input.errors ?? [])];
+    if (row.agent_id !== agentNodeId)
+        errors.push(`Wake agent ${row.agent_id} does not match compiled agent ${agentNodeId}`);
+    if (row.error !== undefined)
+        errors.push(`Wake recording: ${row.error}`);
+    if (!row.deliveries.length)
+        throw new Error("A wake moment requires at least one delivery");
+    const startedAt = row.started_at, started = Date.parse(startedAt);
+    if (!Number.isFinite(started))
+        throw new Error("A wake moment requires a valid started_at");
+    const resources = [];
+    const history = recordingHistoryAt(input.deployResources, input.deploymentRecordPath, startedAt, agentNodeId);
+    const { deployment, agent } = history;
+    errors.push(...history.errors);
+    if (deployment && (!deployment.activation_exact || deployment.exact === false)) {
+        errors.push(`Deployment activation is non-exact${deployment.activation_note ? `: ${deployment.activation_note}` : ""}`);
+    }
+    for (const resource of [...(agent?.resources ?? [])].sort((a, b) => a.id.localeCompare(b.id) || a.kind.localeCompare(b.kind))) {
+        const matches = deployment?.resources.filter((entry) => entry.id === resource.id && entry.kind === resource.kind) ?? [];
+        const pin = matches[0];
+        if (matches.length !== 1 || !pin) {
+            errors.push(`${matches.length ? "Ambiguous" : "Missing"} deployment history for ${resource.kind} resource ${resource.id} at ${startedAt}`);
+            continue;
+        }
+        resources.push(pin.kind === "git"
+            ? { id: pin.id, kind: pin.kind, commit: pin.commit, sha256: pin.sha256 }
+            : { id: pin.id, kind: pin.kind, sha256: pin.sha256 });
+    }
+    const feeds = [];
+    for (const { id, volume_name } of agent?.feeds ?? []) {
+        const history = Object.hasOwn(input.feedLandings, id) ? input.feedLandings[id] : [];
+        const landing = feedLandingAt(history.filter((entry) => entry.resource === id && entry.volume === volume_name), startedAt);
+        if (!landing) {
+            errors.push(`Missing feed history for ${id} at ${startedAt}`);
+            continue;
+        }
+        if (landing.ambiguous)
+            errors.push(`Feed ${id} transition is ambiguous at ${startedAt} (${landing.switching_at} through ${landing.landed_at})`);
+        feeds.push({ id, revision: landing.revision, tree: landing.tree, landedAt: landing.landed_at,
+            ...(landing.commit === undefined ? {} : { commit: landing.commit }),
+            ...(landing.ref === undefined ? {} : { ref: landing.ref }),
+            ...(landing.paths === undefined ? {} : { paths: [...landing.paths] }),
+            ...(landing.period === undefined ? {} : { period: landing.period }) });
+    }
+    const memory = [];
+    for (const bank of [...(agent?.memory ?? [])].sort((a, b) => a.id.localeCompare(b.id) || a.declared_by.localeCompare(b.declared_by))) {
+        const ledger = bank.ledger_path === null ? undefined : input.memoryLedgers[bank.ledger_path];
+        if (!ledger || ledger.errors?.length) {
+            const reasons = ledger?.errors?.length ? ledger.errors : ["ledger could not be read"];
+            errors.push(...reasons.map((reason) => `Memory bank ${bank.id} (${bank.declared_by}): ${reason}`));
+            continue;
+        }
+        const seq = ledger.entries.reduce((highest, entry) => Date.parse(entry.createdAt) <= started ? Math.max(highest, entry.seq) : highest, 0);
+        memory.push({ id: bank.id, declaredBy: bank.declared_by, seq });
+    }
+    const snapshotIds = orderedUnique(agent?.snapshots ?? []);
+    for (const id of snapshotIds) {
+        if (!row.snapshots.some((entry) => entry.id === id))
+            errors.push(`Missing pre-turn snapshot for ${id}`);
+    }
+    const volumes = [];
+    for (const { id, snapshot } of [...row.snapshots].sort((a, b) => a.id.localeCompare(b.id))) {
+        if (!snapshotIds.includes(id)) {
+            errors.push(`Unexpected pre-turn snapshot for ${id}: not an effective recording root for ${agentNodeId}`);
+            continue;
+        }
+        volumes.push({ id, snapshot });
+    }
+    const messageIds = row.deliveries.flatMap(({ delivery_id }) => {
+        const match = /^moltnet:(.+)$/u.exec(delivery_id);
+        return match ? [match[1]] : [];
+    });
+    return {
+        version: MOMENT_RECORD_VERSION, agent: agentNodeId,
+        wake: {
+            at: row.deliveries[0].occurred_at, startedAt, executionId: row.execution_id,
+            deliveries: row.deliveries.map(({ delivery_id, kind, occurred_at }) => ({ deliveryId: delivery_id, kind, occurredAt: occurred_at })),
+            ...(messageIds.length ? { surface: "moltnet", messageId: messageIds[0] } : {})
+        },
+        recordedAt: input.recordedAt, exact: errors.length === 0, resources, feeds, memory,
+        moltnet: orderedUnique(agent?.networks ?? []).map((network) => ({ network, cursor: startedAt,
+            ...(messageIds.length ? { messageIds: [...messageIds] } : {}) })),
+        volumes,
+        ...(errors.length ? { errors } : {})
+    };
+};

package/dist/recording/deployment.d.ts

@@ -0,0 +1,15 @@
+import { createDockerProbeGateway, inspectDockerDeployment, type DeploymentRecord } from "../deployment/index.js";
+import { type SyncMomentRecordsOptions, type SyncMomentRecordsResult } from "./sync.js";
+export interface RecordingDeploymentHandlers {
+    createDockerProbeGateway?: typeof createDockerProbeGateway;
+    inspectDockerDeployment?: typeof inspectDockerDeployment;
+    readFeedHistory?: SyncMomentRecordsOptions["readFeedHistory"];
+    now?: () => Date;
+}
+export interface RecordingDeploymentOptions {
+    record: DeploymentRecord;
+    recordPath: string;
+    dockerCommand?: string;
+    timeoutMs?: number;
+}
+export declare const syncDeploymentMoments: (options: RecordingDeploymentOptions, handlers?: RecordingDeploymentHandlers) => Promise<SyncMomentRecordsResult>;

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