spawnfile 0.1.14 → 0.1.18

package/dist/compiler/training/rewind/materialize.js

@@ -0,0 +1,212 @@
+import { lstat, mkdir, mkdtemp, readdir, realpath, rename, rm, utimes, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { materializedMomentSchema } from "./contract.js";
+import { materializeFeed } from "./feed.js";
+import { materializeGit } from "./git.js";
+import { historyKey, inside, openHistory } from "./history.js";
+import { resolveRewindInputs } from "./inputs.js";
+import { inspectTrainingMoment } from "./leakCheck.js";
+import { inspectBundleFiles, restoreInspectedAccessTimes, snapshotBundleFiles } from "./leakFiles.js";
+import { materializeMemory } from "./memory.js";
+import { materializeMoltnet } from "./moltnet.js";
+import { matchingMomentRecords, originalMomentRecords, selectMomentRecord } from "./select.js";
+import { hasRecordPin, recordForInput } from "./recordInput.js";
+import { assertTaskClockInstant, createTaskClock } from "./taskClock.js";
+import { restoreAccessTimes, stampTree } from "./timestamps.js";
+import { materializeVolume } from "./volumes.js";
+/** Pure core for a per-trial caller: effective declarations, example identity and matching record. */
+export const resolveTrainingMoment = (plan, project, example, records = []) => {
+    const resolved = resolveRewindInputs(plan, project, example);
+    assertTaskClockInstant(resolved.at);
+    const candidateRecords = originalMomentRecords(matchingMomentRecords(records, plan.agent.id, resolved.at));
+    const record = selectMomentRecord(candidateRecords, plan.agent.id, resolved.at, resolved.inputs.filter((input) => !input.overridden));
+    const effectiveAt = record?.wake.startedAt ?? resolved.at;
+    assertTaskClockInstant(effectiveAt);
+    return { ...resolved, candidateRecords, record, effectiveAt };
+};
+const reason = (error) => error instanceof Error ? error.message : String(error);
+const serialize = (value) => `${JSON.stringify(value, null, 2)}\n`;
+const kindOf = (input) => input.section === "memory" ? "memory"
+    : input.section === "networks" ? "moltnet" : input.declaration.kind === "volume" && input.declaration.feed ? "feed" : input.declaration.kind;
+const reportInput = (input) => ({
+    section: input.section, id: input.id, declaredBy: input.declaredBy, kind: kindOf(input), fidelity: null,
+    basis: "refused", source: {}, path: null, notes: [], refusal: null
+});
+const dispatch = (context) => {
+    const { input } = context;
+    if (input.section === "memory")
+        return materializeMemory(context);
+    if (input.section === "networks")
+        return materializeMoltnet(context);
+    if (input.declaration.kind !== "volume")
+        return materializeGit(context);
+    return input.declaration.feed ? materializeFeed(context) : materializeVolume(context);
+};
+const assertEmptyOutput = async (out) => {
+    const existing = await lstat(out).catch((error) => {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    });
+    if (existing && (!existing.isDirectory() || (await readdir(out)).length))
+        throw new Error("Rewind --out must not exist or must be an empty directory");
+};
+const discardPayload = async (staging, moment) => {
+    moment.status = "refused";
+    for (const input of moment.inputs)
+        input.path = null;
+    for (const name of await readdir(staging))
+        if (name !== "moment.json" && name !== "leak-check.json") {
+            await rm(path.join(staging, name), { recursive: true, force: true });
+        }
+};
+/** A separately callable disk acceptance gate, also used to test deliberately broken producers. */
+export const finalizeTrainingMoment = async (staging, out, options = {}) => {
+    // Capture disk metadata before reading even moment.json; inspection preserves access times.
+    const { moment, check } = await inspectTrainingMoment(staging, options, true);
+    if (check) {
+        moment.leakCheck = { ok: check.ok, findings: check.findings.length };
+        if (!check.ok) {
+            for (const finding of check.findings) {
+                const affected = finding.input ? moment.inputs.filter((input) => input.section === finding.input.section
+                    && input.id === finding.input.id && input.declaredBy === finding.input.declaredBy) : moment.inputs;
+                for (const input of affected)
+                    input.refusal = [input.refusal, `${finding.class}: ${finding.path}: ${finding.detail}`].filter(Boolean).join("; ");
+            }
+            await discardPayload(staging, moment);
+        }
+        await writeFile(path.join(staging, "leak-check.json"), serialize(check));
+        await stampTree(path.join(staging, "leak-check.json"), moment.effectiveAt, moment.effectiveAt);
+    }
+    else
+        await discardPayload(staging, moment);
+    await writeFile(path.join(staging, "moment.json"), serialize(materializedMomentSchema.parse(moment)));
+    await stampTree(path.join(staging, "moment.json"), moment.effectiveAt, moment.effectiveAt);
+    await utimes(staging, new Date(moment.effectiveAt), new Date(moment.effectiveAt));
+    await restoreAccessTimes(staging, moment.effectiveAt);
+    await assertEmptyOutput(out);
+    await rename(staging, out);
+    if (check?.ok) {
+        // The post-restoration, post-rename payload is the acceptance target.
+        try {
+            const files = await snapshotBundleFiles(out);
+            const published = { ...check, checked: { ...check.checked, files: 0 }, findings: [] };
+            try {
+                await inspectBundleFiles(out, moment.inputs, published, files);
+            }
+            finally {
+                await restoreInspectedAccessTimes(files);
+            }
+            if (published.findings.length) {
+                check.findings.push(...published.findings);
+                check.ok = false;
+                moment.leakCheck = { ok: false, findings: check.findings.length };
+                for (const finding of published.findings)
+                    for (const input of moment.inputs.filter((entry) => !finding.input
+                        || entry.section === finding.input.section && entry.id === finding.input.id && entry.declaredBy === finding.input.declaredBy)) {
+                        input.refusal = `${finding.class}: ${finding.path}: ${finding.detail}`;
+                    }
+                await discardPayload(out, moment);
+                await writeFile(path.join(out, "moment.json"), serialize(materializedMomentSchema.parse(moment)));
+                await stampTree(path.join(out, "moment.json"), moment.effectiveAt, moment.effectiveAt);
+            }
+            check.checked.files = published.checked.files;
+            await writeFile(path.join(out, "leak-check.json"), serialize(check));
+            await stampTree(path.join(out, "leak-check.json"), moment.effectiveAt, moment.effectiveAt);
+            await utimes(out, new Date(moment.effectiveAt), new Date(moment.effectiveAt));
+        }
+        catch (error) {
+            await rm(out, { recursive: true, force: true });
+            throw error;
+        }
+    }
+    return moment;
+};
+/** Local-only rewind. No compilation artifacts, model invocation, auth, shell or network access. */
+export const materializeTrainingMoment = async (options) => {
+    const { plan, project, example } = options;
+    const resolved = resolveRewindInputs(plan, project, example);
+    assertTaskClockInstant(resolved.at);
+    let out = path.resolve(options.out);
+    await assertEmptyOutput(out);
+    let history, historyError;
+    try {
+        history = await openHistory(options.historyDir);
+    }
+    catch (error) {
+        historyError = `Cannot open history: ${reason(error)}`;
+    }
+    let record = null, recordError;
+    let candidateRecords = [];
+    try {
+        candidateRecords = matchingMomentRecords(await history?.records() ?? [], plan.agent.id, resolved.at);
+        record = selectMomentRecord(candidateRecords, plan.agent.id, resolved.at, resolved.inputs.filter((input) => !input.overridden));
+    }
+    catch (error) {
+        recordError = reason(error);
+    }
+    const attempts = candidateRecords.length;
+    candidateRecords = originalMomentRecords(candidateRecords);
+    const effectiveAt = record?.wake.startedAt ?? resolved.at;
+    assertTaskClockInstant(effectiveAt);
+    await mkdir(path.dirname(out), { recursive: true });
+    out = path.join(await realpath(path.dirname(out)), path.basename(out));
+    if (history && (inside(history.root, out) || inside(out, history.root)))
+        throw new Error("Rewind output and history must not overlap");
+    const staging = await mkdtemp(path.join(path.dirname(out), `.${path.basename(out)}.rewind-`));
+    try {
+        const moment = {
+            version: "spawnfile.materialized-moment.v1", status: "materialized", agent: plan.agent.id,
+            example: { id: resolved.selected.id, role: resolved.selected.role, dataset: resolved.selected.dataset },
+            at: resolved.at, effectiveAt, inputs: [], record: { matched: record !== null, ...(record ? {
+                    attempts, selectedStartedAt: record.wake.startedAt, executionId: record.wake.executionId, selection: "earliest-startedAt"
+                } : {}) }, leakCheck: { ok: false, findings: 0 }
+        };
+        for (const input of resolved.inputs) {
+            const entry = reportInput(input);
+            moment.inputs.push(entry);
+            try {
+                if (!input.overridden && (historyError || recordError))
+                    throw new Error(historyError ?? recordError);
+                const relative = `${input.section === "networks" ? "moltnet" : input.section}/${historyKey(input)}`;
+                const destination = path.join(staging, relative);
+                const usableRecord = recordForInput(record, input);
+                const result = await dispatch({ input, at: effectiveAt, agentSlug: resolved.agentSlug, agentId: plan.agent.id,
+                    record: usableRecord, candidateRecords: candidateRecords.filter((candidate) => recordForInput(candidate, input)), history, destination });
+                if (record && !record.exact && !input.overridden && !hasRecordPin(usableRecord, input)) {
+                    result.fidelity = "approximate";
+                    result.notes.push(...(record.errors ?? []));
+                }
+                await stampTree(destination, result.instant, effectiveAt);
+                Object.assign(entry, { fidelity: result.fidelity, basis: result.basis, source: result.source,
+                    notes: result.notes, path: relative, ...(result.build ? { build: result.build } : {}) });
+            }
+            catch (error) {
+                entry.refusal = reason(error);
+                moment.status = "refused";
+            }
+        }
+        if (recordError && resolved.inputs.length === 0)
+            throw new Error(recordError);
+        await writeFile(path.join(staging, "task-clock.json"), serialize(createTaskClock(effectiveAt)));
+        await writeFile(path.join(staging, "moment.json"), serialize(moment));
+        // Set only unstamped wrapper directories; per-input source times remain intact.
+        const wrappers = async (directory) => {
+            const relative = path.relative(staging, directory).split(path.sep).join("/");
+            if (moment.inputs.some((input) => input.path === relative))
+                return;
+            for (const entry of await readdir(directory, { withFileTypes: true })) {
+                if (entry.isDirectory())
+                    await wrappers(path.join(directory, entry.name));
+                else if (directory === staging)
+                    await stampTree(path.join(directory, entry.name), effectiveAt, effectiveAt);
+            }
+            await utimes(directory, new Date(effectiveAt), new Date(effectiveAt));
+        };
+        await wrappers(staging);
+        return await finalizeTrainingMoment(staging, out, { historyDir: options.historyDir });
+    }
+    finally {
+        await rm(staging, { recursive: true, force: true });
+    }
+};

package/dist/compiler/training/rewind/memory.d.ts

@@ -0,0 +1,10 @@
+import { type MemoryLedgerEvent } from "./memorySchemas.js";
+import type { InputContext, InputResult } from "./types.js";
+export interface MemoryLedger {
+    lines: string[];
+    events: MemoryLedgerEvent[];
+}
+export declare const parseMemoryLedger: (payload: string, label?: string) => MemoryLedger;
+/** The first future event is a boundary; a clock regression after it cannot reopen the cut. */
+export declare const selectMemoryPrefix: (ledger: MemoryLedger, at: string, seq?: number) => MemoryLedger;
+export declare const materializeMemory: (context: InputContext) => Promise<InputResult>;

package/dist/compiler/training/rewind/memory.js

@@ -0,0 +1,84 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { historyKey } from "./history.js";
+import { compareInstants } from "./instant.js";
+import { parseMemoryLedgerEvent } from "./memorySchemas.js";
+const reason = (error) => error instanceof Error ? error.message : String(error);
+export const parseMemoryLedger = (payload, label = "memory/events.jsonl") => {
+    if (payload === "")
+        return { lines: [], events: [] };
+    if (!payload.endsWith("\n"))
+        throw new Error(`${label}: ledger must end with LF`);
+    const lines = payload.slice(0, -1).split("\n");
+    const events = lines.map((line, index) => {
+        try {
+            return parseMemoryLedgerEvent(line);
+        }
+        catch (error) {
+            throw new Error(`${label}:${index + 1}: invalid Mneme event: ${reason(error)}`);
+        }
+    });
+    return { lines, events };
+};
+/** The first future event is a boundary; a clock regression after it cannot reopen the cut. */
+export const selectMemoryPrefix = (ledger, at, seq) => {
+    if (seq !== undefined && (!Number.isSafeInteger(seq) || seq < 0 || seq > ledger.events.length)) {
+        throw new Error(`Memory record seq ${seq} exceeds or does not identify a ledger prefix`);
+    }
+    const firstFuture = ledger.events.findIndex((event) => compareInstants(event.createdAt, at) > 0);
+    const length = seq ?? (firstFuture < 0 ? ledger.events.length : firstFuture);
+    const events = ledger.events.slice(0, length);
+    let sawNative = false;
+    events.forEach((event, index) => {
+        if (event.seq !== undefined) {
+            if (event.seq !== index + 1)
+                throw new Error(`Memory ledger line ${index + 1}: seq ${event.seq} is not contiguous`);
+            sawNative = true;
+        }
+        else if (sawNative)
+            throw new Error(`Memory ledger line ${index + 1}: seq-less legacy events must form a leading run`);
+        if (compareInstants(event.createdAt, at) > 0)
+            throw new Error(`Memory ledger line ${index + 1}: createdAt is later than the moment`);
+        if (index > 0 && compareInstants(event.createdAt, events[index - 1].createdAt) < 0) {
+            throw new Error(`Memory ledger line ${index + 1}: createdAt regresses within the selected prefix`);
+        }
+    });
+    return { events, lines: ledger.lines.slice(0, length) };
+};
+export const materializeMemory = async (context) => {
+    const { input, at, record, history, destination } = context;
+    if (input.section !== "memory")
+        throw new Error("Memory materialization requires a memory input");
+    const directory = path.join(destination, "memory");
+    if (input.overridden) {
+        await mkdir(directory, { recursive: true });
+        await writeFile(path.join(directory, "events.jsonl"), "");
+        return { fidelity: "overridden", basis: "override", source: { seq: 0 }, notes: [], instant: at };
+    }
+    const pin = record?.memory.find((entry) => entry.id === input.id && entry.declaredBy === input.declaredBy);
+    if (pin?.generation !== undefined)
+        throw new Error(`Memory bank ${input.id}: Mneme generations are unsupported`);
+    if (pin?.seq === 0) {
+        await mkdir(directory, { recursive: true });
+        await writeFile(path.join(directory, "events.jsonl"), "");
+        return { fidelity: "exact", basis: "record", source: { seq: 0 },
+            notes: ["The record pins an empty bank (seq: 0); no history ledger is required."], instant: at };
+    }
+    if (!history)
+        throw new Error(`Memory bank ${input.id} requires --history or an override`);
+    const ledgerPath = `memory/${historyKey(input)}/events.jsonl`;
+    const payload = await history.text(ledgerPath);
+    if (payload === null)
+        throw new Error(`Missing memory ledger ${ledgerPath}`);
+    const prefix = selectMemoryPrefix(parseMemoryLedger(payload, ledgerPath), at, pin?.seq);
+    await mkdir(directory, { recursive: true });
+    await writeFile(path.join(directory, "events.jsonl"), prefix.lines.length ? `${prefix.lines.join("\n")}\n` : "");
+    return {
+        fidelity: pin ? "exact" : "approximate", basis: pin ? "record" : "created-at-prefix",
+        source: { seq: prefix.events.length },
+        notes: ["Spawnfile structurally validated the selected ledger without a Mneme runtime dependency; no derived or authority audit state is included.",
+            "Mneme 0.1.1 rebuilds its index from the ledger before every index read.",
+            "Checksum verification is skipped: Mneme 0.1.1 hashes the original input before normalization, which cannot be reconstructed exactly from stored events."],
+        instant: prefix.events.at(-1)?.createdAt ?? at
+    };
+};

package/dist/compiler/training/rewind/memorySchemas.d.ts

@@ -0,0 +1,87 @@
+import { z } from "zod";
+/** Mirrors the public MemoryEvent contract and Mneme 0.1.1's strict ledger reader. */
+export declare const memoryEventSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodEnum<{
+        "memory.recalled": "memory.recalled";
+        "memory.observed": "memory.observed";
+        "memory.claimed": "memory.claimed";
+        "memory.registered": "memory.registered";
+        "memory.summarized": "memory.summarized";
+        "memory.located": "memory.located";
+        "memory.denied": "memory.denied";
+        "memory.forgotten": "memory.forgotten";
+        "memory.promoted": "memory.promoted";
+        "memory.consolidated": "memory.consolidated";
+    }>;
+    createdAt: z.ZodISODateTime;
+    principal: z.ZodObject<{
+        agentId: z.ZodString;
+        scope: z.ZodEnum<{
+            role: "role";
+            pair: "pair";
+            room: "room";
+            team: "team";
+            global: "global";
+            artifact: "artifact";
+            task: "task";
+        }>;
+        qualifier: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    scope: z.ZodString;
+    visibility: z.ZodEnum<{
+        private: "private";
+        public: "public";
+        pair: "pair";
+        room: "room";
+        team: "team";
+        global: "global";
+        sealed: "sealed";
+    }>;
+    source: z.ZodString;
+    content: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"text">;
+        text: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"claim">;
+        subject: z.ZodString;
+        predicate: z.ZodString;
+        object: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"decision">;
+        decision: z.ZodString;
+        rationale: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"artifact">;
+        description: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+        uri: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"relationship">;
+        from: z.ZodString;
+        relation: z.ZodString;
+        to: z.ZodString;
+    }, z.core.$strict>], "kind">;
+    tags: z.ZodArray<z.ZodString>;
+    entities: z.ZodArray<z.ZodString>;
+    sensitivity: z.ZodEnum<{
+        secret: "secret";
+        normal: "normal";
+        sensitive: "sensitive";
+    }>;
+    confidence: z.ZodOptional<z.ZodNumber>;
+    ttl: z.ZodOptional<z.ZodString>;
+    parentEventIds: z.ZodArray<z.ZodString>;
+    checksum: z.ZodString;
+    seq: z.ZodOptional<z.ZodNumber>;
+    memoryId: z.ZodOptional<z.ZodString>;
+    origin: z.ZodOptional<z.ZodEnum<{
+        system: "system";
+        awake: "awake";
+        dream: "dream";
+    }>>;
+    highWaterSeq: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type MemoryLedgerEvent = z.infer<typeof memoryEventSchema>;
+/** Mneme rejects duplicate JSON keys, including escaped and nested duplicates. */
+export declare const parseMemoryLedgerEvent: (line: string) => MemoryLedgerEvent;

package/dist/compiler/training/rewind/memorySchemas.js

@@ -0,0 +1,50 @@
+import { z } from "zod";
+import { trainingInstantSchema } from "../../../manifest/index.js";
+const safeSequence = z.number().int().nonnegative().refine(Number.isSafeInteger);
+/** Mirrors the public MemoryEvent contract and Mneme 0.1.1's strict ledger reader. */
+export const memoryEventSchema = z.object({
+    id: z.string().min(1),
+    type: z.enum(["memory.observed", "memory.claimed", "memory.registered", "memory.summarized",
+        "memory.recalled", "memory.located", "memory.denied", "memory.forgotten", "memory.promoted", "memory.consolidated"]),
+    createdAt: trainingInstantSchema,
+    principal: z.object({ agentId: z.string().min(1),
+        scope: z.enum(["global", "team", "room", "pair", "task", "role", "artifact"]), qualifier: z.string().optional()
+    }).strict(),
+    scope: z.string(), visibility: z.enum(["private", "pair", "team", "room", "global", "public", "sealed"]),
+    source: z.string(),
+    content: z.discriminatedUnion("kind", [
+        z.object({ kind: z.literal("text"), text: z.string() }).strict(),
+        z.object({ kind: z.literal("claim"), subject: z.string(), predicate: z.string(), object: z.string() }).strict(),
+        z.object({ kind: z.literal("decision"), decision: z.string(), rationale: z.string().optional() }).strict(),
+        z.object({ kind: z.literal("artifact"), description: z.string(), path: z.string().optional(), uri: z.string().optional() }).strict(),
+        z.object({ kind: z.literal("relationship"), from: z.string(), relation: z.string(), to: z.string() }).strict()
+    ]),
+    tags: z.array(z.string()), entities: z.array(z.string()),
+    sensitivity: z.enum(["normal", "sensitive", "secret"]), confidence: z.number().finite().optional(),
+    ttl: z.string().optional(), parentEventIds: z.array(z.string()), checksum: z.string().min(1),
+    seq: safeSequence.refine((value) => value > 0).optional(), memoryId: z.string().optional(),
+    origin: z.enum(["awake", "dream", "system"]).optional(), highWaterSeq: safeSequence.optional()
+}).strict();
+/** Mneme rejects duplicate JSON keys, including escaped and nested duplicates. */
+export const parseMemoryLedgerEvent = (line) => {
+    const value = JSON.parse(line);
+    const objects = [];
+    let string = "";
+    for (const [token] of line.matchAll(/"(?:\\.|[^"\\])*"|[{}\[\]:]/gu)) {
+        if (token === "{")
+            objects.push(new Set());
+        else if (token === "[")
+            objects.push(null);
+        else if (token === "}" || token === "]")
+            objects.pop();
+        else if (token === ":") {
+            const key = JSON.parse(string), keys = objects.at(-1);
+            if (keys.has(key))
+                throw new Error(`duplicate JSON key ${JSON.stringify(key)}`);
+            keys.add(key);
+        }
+        else
+            string = token;
+    }
+    return memoryEventSchema.parse(value);
+};

package/dist/compiler/training/rewind/moltnet.d.ts

@@ -0,0 +1,2 @@
+import type { InputContext, InputResult } from "./types.js";
+export declare const materializeMoltnet: (context: InputContext) => Promise<InputResult>;

package/dist/compiler/training/rewind/moltnet.js

@@ -0,0 +1,54 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { historyKey } from "./history.js";
+import { compareInstants } from "./instant.js";
+import { emptyMoltnetSnapshot, moltnetMessages, parseMoltnetSnapshot, rewindMoltnetJson } from "./moltnetJson.js";
+import { rewindMoltnetSqlite } from "./moltnetSqlite.js";
+export const materializeMoltnet = async (context) => {
+    const { input, at, record, history, destination } = context;
+    if (input.section !== "networks")
+        throw new Error("Moltnet materialization requires a network input");
+    if (input.overridden) {
+        await mkdir(destination, { recursive: true });
+        await writeFile(path.join(destination, "state.json"), `${JSON.stringify(emptyMoltnetSnapshot(input.declaration, at), null, 2)}\n`);
+        return { fidelity: "overridden", basis: "override", source: {}, notes: ["Fresh network state is stored as a JSON snapshot with the declared rooms."], instant: at };
+    }
+    const pin = record?.moltnet.find((entry) => entry.network === input.id);
+    if (pin && compareInstants(pin.cursor, at) !== 0) {
+        throw new Error(`Moltnet network ${input.id}: recorded cursor must equal wake.startedAt (${at})`);
+    }
+    if (!history)
+        throw new Error(`Moltnet network ${input.id} requires --history or an override`);
+    const base = `moltnet/${historyKey(input)}`;
+    const json = await history.bytes(`${base}/state.json`), sqlite = await history.bytes(`${base}/moltnet.sqlite`);
+    if (!json && !sqlite)
+        throw new Error(`Missing Moltnet store ${base}/state.json or moltnet.sqlite`);
+    if (json && sqlite)
+        throw new Error(`Ambiguous Moltnet history: both state.json and moltnet.sqlite exist for ${input.id}`);
+    await mkdir(destination, { recursive: true });
+    let messages;
+    if (json) {
+        const cut = rewindMoltnetJson(parseMoltnetSnapshot(JSON.parse(json.toString("utf8"))), at);
+        messages = moltnetMessages(cut);
+        await writeFile(path.join(destination, "state.json"), `${JSON.stringify(cut, null, 2)}\n`);
+    }
+    else {
+        const file = path.join(destination, "moltnet.sqlite");
+        await writeFile(file, sqlite);
+        // History readers never open the source database: SQLite recovery is confined to these copies.
+        for (const suffix of ["-wal", "-journal"]) {
+            const bytes = await history.bytes(`${base}/moltnet.sqlite${suffix}`);
+            if (bytes)
+                await writeFile(`${file}${suffix}`, bytes);
+        }
+        messages = await rewindMoltnetSqlite(file, at);
+    }
+    const retainedIds = new Set(messages.map((message) => message.id));
+    const missing = pin?.messageIds?.filter((id) => !retainedIds.has(id)) ?? [];
+    if (missing.length)
+        throw new Error(`Moltnet network ${input.id}: recorded wake message IDs ${missing.join(", ")} are not retained after the cursor cut`);
+    return { fidelity: pin ? "exact" : "approximate", basis: pin ? "record-cursor" : "created-at-cut",
+        source: pin ? { cursor: pin.cursor } : {}, instant: at,
+        notes: ["Future agent registrations and their memberships are removed; retained registration updates are clamped. Other membership history is unavailable (best effort).",
+            "Room removals without a recorded removal instant retain the current removal state; current JSON Moltnet uses a zero-time marker."] };
+};

package/dist/compiler/training/rewind/moltnetJson.d.ts

@@ -0,0 +1,13 @@
+import type { TeamNetwork } from "../../../manifest/index.js";
+import { type MoltnetSnapshot, type MoltnetEvent, type MoltnetMessage, type MoltnetInspection, type MoltnetFinding } from "./moltnetSchemas.js";
+export declare const moltnetMessages: (snapshot: MoltnetSnapshot) => MoltnetMessage[];
+export declare const parseMoltnetSnapshot: (value: unknown) => MoltnetSnapshot;
+export declare const emptyMoltnetSnapshot: (network: TeamNetwork, at: string) => MoltnetSnapshot;
+export declare const latestMoltnetMessage: <T extends {
+    created_at: string;
+}>(messages: T[]) => T | undefined;
+/** Pure cut. Delivery offsets must be remapped after removing interior future events. */
+export declare const rewindMoltnetJson: (source: MoltnetSnapshot, at: string) => MoltnetSnapshot;
+/** Independent timestamp inspection of event payloads, including embedded messages and rooms. */
+export declare const inspectMoltnetEvent: (event: MoltnetEvent, at: string, path: string) => MoltnetFinding[];
+export declare const inspectMoltnetJson: (path: string, at: string) => Promise<MoltnetInspection>;