@noopolis/daimon 0.2.0 → 0.2.1

package/dist/runtime/wakeMomentIo.js

@@ -0,0 +1,114 @@
+import * as fs from "node:fs/promises";
+import { performance } from "node:perf_hooks";
+export class WakeMomentFault extends Error {
+    reason;
+    constructor(reason) {
+        super(reason);
+        this.reason = reason;
+    }
+}
+/** Every filesystem call checks cancellation before issuing I/O and after it settles. */
+export class WakeMomentIo {
+    probe;
+    fs;
+    verifyWrite;
+    aborted = false;
+    expires = Infinity;
+    constructor(probe) {
+        this.probe = probe;
+        this.fs = new Proxy(fs, {
+            get: (target, key) => {
+                const method = Reflect.get(target, key);
+                if (typeof method !== "function")
+                    return method;
+                return (...args) => this.call(String(key), async () => {
+                    const result = await Reflect.apply(method, target, args);
+                    if (key === "open")
+                        return this.handle(result, String(args[0]));
+                    if (key === "opendir")
+                        return this.directory(result, String(args[0]));
+                    if (key === "readdir")
+                        await this.probe?.("directoryEntries", String(args[0]), result.length);
+                    return result;
+                }, typeof args[key === "symlink" || key === "link" ? 1 : 0] === "string" ? String(args[key === "symlink" || key === "link" ? 1 : 0]) : undefined);
+            }
+        });
+    }
+    check() {
+        if (this.aborted || performance.now() >= this.expires) {
+            this.aborted = true;
+            throw new WakeMomentFault("capture_deadline_exceeded");
+        }
+    }
+    async call(operation, action, target) {
+        this.check();
+        await this.probe?.(operation, target);
+        this.check();
+        if (["open", "mkdir", "rename", "rm", "unlink", "rmdir", "link", "symlink", "write", "writeFile", "chmod"].includes(operation)) {
+            await this.verifyWrite?.(target);
+            this.check();
+        }
+        const result = await action();
+        try {
+            this.check();
+        }
+        catch (error) {
+            // An open already in flight can finish after abandonment; release its handle.
+            if (result && typeof result.close === "function") {
+                void result.close().catch(() => undefined);
+            }
+            throw error;
+        }
+        return result;
+    }
+    async bounded(milliseconds, action) {
+        this.expires = performance.now() + milliseconds;
+        let timer;
+        const deadline = new Promise((_resolve, reject) => {
+            timer = setTimeout(() => {
+                this.aborted = true;
+                reject(new WakeMomentFault("capture_deadline_exceeded"));
+            }, milliseconds);
+        });
+        try {
+            return await Promise.race([action(), deadline]);
+        }
+        finally {
+            clearTimeout(timer);
+            this.aborted = true;
+        }
+    }
+    handle(handle, target) {
+        return new Proxy(handle, { get: (fd, key) => {
+                const method = Reflect.get(fd, key, fd);
+                if (typeof method !== "function")
+                    return method;
+                if (key === "close")
+                    return method.bind(fd); // Closing never publishes data.
+                return (...args) => this.call(String(key), async () => Reflect.apply(method, fd, args), target);
+            } });
+    }
+    directory(directory, target) {
+        const io = this;
+        return new Proxy(directory, { get: (dir, key) => {
+                if (key === Symbol.asyncIterator)
+                    return async function* () {
+                        try {
+                            for (;;) {
+                                const entry = await io.call("readdir", () => dir.read(), target);
+                                if (!entry)
+                                    break;
+                                await io.probe?.("directoryEntries", target, 1);
+                                io.check();
+                                yield entry;
+                            }
+                        }
+                        finally {
+                            await dir.close();
+                        }
+                    };
+                const method = Reflect.get(dir, key, dir);
+                return typeof method === "function" ? method.bind(dir) : method;
+            } });
+    }
+}

package/dist/runtime/wakeMomentRecorder.d.ts

@@ -0,0 +1,33 @@
+import { WAKE_MOMENTS } from "../contracts/wakeMomentContract.js";
+import type { OrganizationRuntimeAgentConfig } from "./organizationRuntime.js";
+import type { StoredWakeAcceptanceRecord } from "./wakeAcceptanceRecord.js";
+import { type WakeMomentIoProbe } from "./wakeMomentIo.js";
+import { type WakeSnapshot } from "./wakeMomentSnapshot.js";
+export { appendWakeMomentRow } from "./wakeMomentRows.js";
+export { pruneWakeMoments } from "./wakeMomentRetention.js";
+export type WakeMomentRow = {
+    version: typeof WAKE_MOMENTS.version;
+    agent_id: string;
+    execution_id: string;
+    started_at: string;
+    deliveries: {
+        acceptance_id: string;
+        delivery_id: string;
+        kind: string;
+        occurred_at: string;
+    }[];
+    snapshots: WakeSnapshot[];
+    error?: string;
+};
+/** Internal seams, intentionally absent from the public runtime barrel/config schema. */
+export type WakeMomentOptions = {
+    now?: () => number;
+    captureDeadlineMs?: number;
+    finalizationDeadlineMs?: number;
+    maxManifestBytes?: number;
+    probe?: WakeMomentIoProbe;
+    verifyStore?: () => Promise<void>;
+};
+/** Advisory, per attempt, and completely inert for an agent without recording. */
+export declare function recordWakeMoment(agent: OrganizationRuntimeAgentConfig, executionId: string, records: readonly StoredWakeAcceptanceRecord[], options?: WakeMomentOptions): Promise<void>;
+//# sourceMappingURL=wakeMomentRecorder.d.ts.map

package/dist/runtime/wakeMomentRecorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wakeMomentRecorder.d.ts","sourceRoot":"","sources":["../../src/runtime/wakeMomentRecorder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAClE,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,0BAA0B,CAAC;AAC/E,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,2BAA2B,CAAC;AAE5E,OAAO,EAAgB,KAAK,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACzE,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAGjF,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAE5D,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,OAAO,YAAY,CAAC,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IACjG,UAAU,EAAE;QAAE,aAAa,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAChG,SAAS,EAAE,YAAY,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CAC3C,CAAC;AAEF,yFAAyF;AACzF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACzF,CAAC;AAEF,kFAAkF;AAClF,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,8BAA8B,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,0BAA0B,EAAE,EAAE,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgDjM"}

package/dist/runtime/wakeMomentRecorder.js

@@ -0,0 +1,81 @@
+import { WAKE_MOMENTS } from "../contracts/wakeMomentContract.js";
+import { cleanMomentPaths, pinMomentStore, wakeMomentFailure } from "./wakeMomentFs.js";
+import { WakeMomentIo } from "./wakeMomentIo.js";
+import { captureWakeSnapshot } from "./wakeMomentSnapshot.js";
+import { appendWakeMomentRow } from "./wakeMomentRows.js";
+import { pruneWakeMoments } from "./wakeMomentRetention.js";
+export { appendWakeMomentRow } from "./wakeMomentRows.js";
+export { pruneWakeMoments } from "./wakeMomentRetention.js";
+/** Advisory, per attempt, and completely inert for an agent without recording. */
+export async function recordWakeMoment(agent, executionId, records, options = {}) {
+    const recording = agent.recording;
+    if (!recording)
+        return;
+    const now = options.now ?? Date.now, io = new WakeMomentIo(options.probe), cleanup = new Set();
+    const errors = [];
+    let store, row;
+    try {
+        await io.bounded(options.captureDeadlineMs ?? WAKE_MOMENTS.captureDeadlineMs, async () => {
+            store = await pinMomentStore(recording.directory, io, options.verifyStore);
+            io.verifyWrite = (target) => store.verify(io, target);
+            await store.verify(io); // Immediately before capture, against the pinned root.
+            row = {
+                version: WAKE_MOMENTS.version, agent_id: agent.id, execution_id: executionId, started_at: new Date(now()).toISOString(),
+                deliveries: records.map(({ acceptance_id, delivery_id, event }) => ({ acceptance_id, delivery_id, kind: event.kind, occurred_at: event.occurred_at })), snapshots: []
+            };
+            for (const root of recording.snapshots) {
+                try {
+                    const captured = await captureWakeSnapshot({ directory: recording.directory, root, startedAt: row.started_at, executionId, io, cleanup, maxManifestBytes: options.maxManifestBytes });
+                    io.check();
+                    row.snapshots.push(captured.snapshot);
+                    if (captured.note)
+                        errors.push(`${root.id}: ${captured.note}`);
+                }
+                catch (error) {
+                    io.check(); // Deadline abandons the remaining roots, not just this one.
+                    if (wakeMomentFailure(error) === "recording_store_changed")
+                        throw error;
+                    errors.push(`${root.id}: ${wakeMomentFailure(error)}`);
+                }
+            }
+        });
+    }
+    catch (error) {
+        errors.push(wakeMomentFailure(error));
+    }
+    // Capture is fenced before the row or cognition: late I/O completions cannot issue another write.
+    const finalizer = new WakeMomentIo(options.probe);
+    try {
+        await finalizer.bounded(options.finalizationDeadlineMs ?? WAKE_MOMENTS.finalizationDeadlineMs, async () => {
+            if (!store || !row) {
+                logFailure(errors.join("; "));
+                return;
+            }
+            finalizer.verifyWrite = (target) => store.verify(finalizer, target);
+            if (errors.length)
+                row.error = errors.join("; ").slice(0, 2048);
+            // A stuck best-effort cleanup must not prevent the error row from being attempted.
+            const [cleaned] = await Promise.all([
+                cleanMomentPaths(cleanup, store, finalizer).then(() => true, (error) => { logFailure(wakeMomentFailure(error)); return false; }),
+                appendWakeMomentRow(recording.directory, row, finalizer)
+            ]);
+            if (cleaned) {
+                finalizer.check();
+                await pruneWakeMoments(recording, agent.id, now(), row, finalizer, store);
+            }
+        });
+    }
+    catch (error) {
+        logFailure(wakeMomentFailure(error));
+    }
+    finally {
+        if (store)
+            void store.close().catch(() => undefined);
+    }
+}
+function logFailure(reason) {
+    try {
+        console.error(`daimon: wake recording failed: ${reason}`);
+    }
+    catch { /* Logging is advisory too. */ }
+}

package/dist/runtime/wakeMomentRetention.d.ts

@@ -0,0 +1,7 @@
+import { type WakeMomentRecording } from "../contracts/wakeMomentContract.js";
+import { type MomentStore } from "./wakeMomentFs.js";
+import { WakeMomentIo } from "./wakeMomentIo.js";
+import type { WakeMomentRow } from "./wakeMomentRecorder.js";
+/** First-line age check; a full sweep every 64 calls also handles foreign prefixes/clock rollback. */
+export declare function pruneWakeMoments(recording: WakeMomentRecording, agentId: string, now?: number, current?: WakeMomentRow, scope?: WakeMomentIo, authority?: MomentStore): Promise<void>;
+//# sourceMappingURL=wakeMomentRetention.d.ts.map

package/dist/runtime/wakeMomentRetention.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wakeMomentRetention.d.ts","sourceRoot":"","sources":["../../src/runtime/wakeMomentRetention.ts"],"names":[],"mappings":"AAIA,OAAO,EAAgB,KAAK,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AAC5F,OAAO,EAAkI,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrL,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAkB7D,sGAAsG;AACtG,wBAAsB,gBAAgB,CAAC,SAAS,EAAE,mBAAmB,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,SAAa,EAAE,OAAO,CAAC,EAAE,aAAa,EAAE,KAAK,CAAC,EAAE,YAAY,EAAE,SAAS,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAU/L"}

package/dist/runtime/wakeMomentRetention.js

@@ -0,0 +1,143 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import path from "node:path";
+import { WAKE_MOMENTS } from "../contracts/wakeMomentContract.js";
+import { cleanMomentPaths, openMomentDirectory, openMomentFile, pinMomentStore, removeMomentPath, syncMomentDirectory, writeMomentBytes } from "./wakeMomentFs.js";
+import { WakeMomentIo } from "./wakeMomentIo.js";
+import { momentLines } from "./wakeMomentRows.js";
+import { completeSnapshotNames, eligibleSnapshot, indexFromNames, latestSnapshotIndex, snapshotRootName, snapshotTime, writeSnapshotIndex } from "./wakeMomentHistory.js";
+const sweeps = new Map();
+const key = (snapshot) => `${snapshot.id}/${snapshot.snapshot}`;
+function expiredRow(line, agentId, cutoff, current) {
+    try {
+        const row = JSON.parse(line.toString("utf8"));
+        if (current && row.execution_id === current.execution_id && row.started_at === current.started_at)
+            return undefined;
+        if (row?.version === WAKE_MOMENTS.version && row.agent_id === agentId && typeof row.execution_id === "string"
+            && Array.isArray(row.deliveries) && Array.isArray(row.snapshots) && typeof row.started_at === "string"
+            && new Date(row.started_at).toISOString() === row.started_at && Date.parse(row.started_at) < cutoff)
+            return row;
+    }
+    catch { /* Unknown/partial lines are not ours to delete. */ }
+    return undefined;
+}
+/** First-line age check; a full sweep every 64 calls also handles foreign prefixes/clock rollback. */
+export async function pruneWakeMoments(recording, agentId, now = Date.now(), current, scope, authority) {
+    const io = scope ?? new WakeMomentIo();
+    const store = authority ?? await pinMomentStore(recording.directory, io);
+    io.verifyWrite = (target) => store.verify(io, target);
+    try {
+        const cutoff = now - recording.keepMs;
+        await pruneSnapshots(recording.directory, new Set(current?.snapshots.map(key) ?? []), cutoff, io, store);
+        await pruneRows(recording, agentId, cutoff, current, io, store);
+    }
+    finally {
+        if (!authority)
+            await store.close();
+    }
+}
+async function pruneRows(recording, agentId, cutoff, current, io, store) {
+    const target = path.join(recording.directory, WAKE_MOMENTS.rowsFile);
+    let source;
+    try {
+        source = await openMomentFile(target, constants.O_RDONLY, io);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        throw error;
+    }
+    const temporary = `${target}.${randomUUID()}.tmp`;
+    let output, changed = false, created = false;
+    try {
+        const count = (sweeps.get(target) ?? 0) + 1;
+        sweeps.set(target, count % 64);
+        let firstExpired = false;
+        for await (const line of momentLines(source)) {
+            firstExpired = expiredRow(line, agentId, cutoff, current) !== undefined;
+            break;
+        }
+        if (!firstExpired && count % 64 !== 0)
+            return;
+        output = await openMomentFile(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, io);
+        created = true;
+        const reread = await openMomentFile(target, constants.O_RDONLY, io);
+        try {
+            for await (const line of momentLines(reread)) {
+                const expired = expiredRow(line, agentId, cutoff, current);
+                if (!expired) {
+                    await writeMomentBytes(output, line);
+                    continue;
+                }
+                changed = true;
+            }
+        }
+        finally {
+            await reread.close();
+        }
+        if (!changed)
+            return;
+        await output.sync();
+        await output.close();
+        output = undefined;
+        await io.fs.rename(temporary, target);
+        created = false;
+        await syncMomentDirectory(recording.directory, io);
+    }
+    finally {
+        await source.close();
+        await output?.close();
+        if (created)
+            await removeMomentPath(temporary, store, io);
+    }
+}
+/** Age comes from names; ownership comes from the writer's zero-byte completion marker. */
+async function pruneSnapshots(directory, protectedSnapshots, cutoff, io, store) {
+    const namespace = path.join(directory, WAKE_MOMENTS.snapshotsDirectory);
+    try {
+        const ns = await openMomentDirectory(namespace, io);
+        await ns.close();
+        for await (const root of await io.fs.opendir(namespace)) {
+            if (!root.isDirectory() || !/^(?:[A-Za-z0-9._-]{1,128}|%2E|%2E%2E)$/.test(root.name))
+                continue;
+            const id = root.name === "%2E" ? "." : root.name === "%2E%2E" ? ".." : root.name;
+            if (snapshotRootName(id) !== root.name)
+                continue;
+            const base = path.join(namespace, root.name);
+            const fd = await openMomentDirectory(base, io);
+            await fd.close();
+            const state = await latestSnapshotIndex(base, io);
+            if (!state.names && (state.index.oldest === null || snapshotTime(state.index.oldest) >= cutoff))
+                continue;
+            const names = state.names ?? await completeSnapshotNames(base, io), removed = new Set();
+            for (const name of names.slice(1)) {
+                if (protectedSnapshots.has(`${id}/${name}`) || snapshotTime(name) >= cutoff)
+                    continue;
+                const target = path.join(base, name), manifest = `${target}.manifest.json`, marker = `${target}${WAKE_MOMENTS.completionSuffix}`;
+                await store.verify(io, target);
+                if (!await eligibleSnapshot(base, name, io))
+                    continue;
+                await store.verify(io, target);
+                await removeMomentPath(target, store, io);
+                await removeMomentPath(manifest, store, io);
+                await removeMomentPath(marker, store, io);
+                await syncMomentDirectory(base, io);
+                removed.add(name);
+            }
+            const index = indexFromNames(names.filter((name) => !removed.has(name)));
+            if (index) {
+                const cleanup = new Set();
+                try {
+                    await writeSnapshotIndex(base, index, io, cleanup);
+                }
+                finally {
+                    await cleanMomentPaths(cleanup, store, io);
+                }
+            }
+        }
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}

package/dist/runtime/wakeMomentRows.d.ts

@@ -0,0 +1,8 @@
+import type { FileHandle } from "node:fs/promises";
+import { WakeMomentIo } from "./wakeMomentIo.js";
+import type { WakeMomentRow } from "./wakeMomentRecorder.js";
+/** One append write and fsync. A torn prior append is delimited, never mistaken for this attempt. */
+export declare function appendWakeMomentRow(directory: string, row: WakeMomentRow, io?: WakeMomentIo): Promise<void>;
+/** Bound memory even when a damaged/foreign rows file has no newlines. */
+export declare function momentLines(fd: FileHandle): AsyncGenerator<Buffer>;
+//# sourceMappingURL=wakeMomentRows.d.ts.map

package/dist/runtime/wakeMomentRows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wakeMomentRows.d.ts","sourceRoot":"","sources":["../../src/runtime/wakeMomentRows.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAInD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE7D,qGAAqG;AACrG,wBAAsB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,EAAE,EAAE,eAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBvH;AAED,0EAA0E;AAC1E,wBAAuB,WAAW,CAAC,EAAE,EAAE,UAAU,GAAG,cAAc,CAAC,MAAM,CAAC,CAmBzE"}

package/dist/runtime/wakeMomentRows.js

@@ -0,0 +1,66 @@
+import { constants } from "node:fs";
+import path from "node:path";
+import { WAKE_MOMENTS } from "../contracts/wakeMomentContract.js";
+import { openMomentFile, syncMomentDirectory, WakeMomentFault } from "./wakeMomentFs.js";
+import { WakeMomentIo } from "./wakeMomentIo.js";
+/** One append write and fsync. A torn prior append is delimited, never mistaken for this attempt. */
+export async function appendWakeMomentRow(directory, row, io = new WakeMomentIo()) {
+    const line = Buffer.from(`${JSON.stringify(row)}\n`);
+    if (line.length > WAKE_MOMENTS.maxRowBytes)
+        throw new WakeMomentFault("row_size_limit");
+    const target = path.join(directory, WAKE_MOMENTS.rowsFile);
+    let created = false, fd;
+    try {
+        fd = await openMomentFile(target, constants.O_RDWR | constants.O_CREAT | constants.O_EXCL | constants.O_APPEND, io);
+        created = true;
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+        fd = await openMomentFile(target, constants.O_RDWR | constants.O_APPEND, io);
+    }
+    try {
+        const size = (await fd.stat()).size;
+        const tail = Buffer.alloc(1);
+        if (size)
+            await fd.read(tail, 0, 1, size - 1);
+        const bytes = size && tail[0] !== 10 ? Buffer.concat([Buffer.from("\n"), line]) : line;
+        const { bytesWritten } = await fd.write(bytes);
+        if (bytesWritten !== bytes.length)
+            throw new WakeMomentFault("short_row_write");
+        await fd.sync();
+        if (created)
+            await syncMomentDirectory(directory, io);
+    }
+    finally {
+        await fd.close();
+    }
+}
+/** Bound memory even when a damaged/foreign rows file has no newlines. */
+export async function* momentLines(fd) {
+    const chunk = Buffer.alloc(64 * 1024);
+    let pending = [], length = 0;
+    for (;;) {
+        const { bytesRead } = await fd.read(chunk, 0, chunk.length, null);
+        if (!bytesRead)
+            break;
+        let start = 0;
+        while (start < bytesRead) {
+            const newline = chunk.indexOf(10, start);
+            const end = newline >= start && newline < bytesRead ? newline + 1 : bytesRead;
+            const part = Buffer.from(chunk.subarray(start, end));
+            length += part.length;
+            if (length > WAKE_MOMENTS.maxRowBytes)
+                throw new WakeMomentFault("row_size_limit");
+            pending.push(part);
+            if (part[part.length - 1] === 10) {
+                yield Buffer.concat(pending, length);
+                pending = [];
+                length = 0;
+            }
+            start = end;
+        }
+    }
+    if (length)
+        yield Buffer.concat(pending, length);
+}

package/dist/runtime/wakeMomentSnapshot.d.ts

@@ -0,0 +1,56 @@
+import { WAKE_MOMENTS } from "../contracts/wakeMomentContract.js";
+import { WakeMomentIo } from "./wakeMomentIo.js";
+export { completeSnapshotNames, snapshotName, snapshotRootName, snapshotTime } from "./wakeMomentHistory.js";
+type Identity = {
+    dev: string;
+    ino: string;
+    size: string;
+    mtimeNs: string;
+    ctimeNs: string;
+    mode: number;
+};
+export type SnapshotEntry = {
+    type: "file" | "directory" | "symlink";
+    mode: number;
+    size: string;
+    source: Identity;
+    target?: string;
+};
+export type WakeSnapshotManifest = {
+    version: typeof WAKE_MOMENTS.version;
+    id: string;
+    snapshot: string;
+    started_at: string;
+    sourcePath: string;
+    entries: Record<string, SnapshotEntry>;
+};
+export type WakeSnapshot = {
+    id: string;
+    snapshot: string;
+    files: number;
+    copied: number;
+    linked: number;
+    skipped: number;
+};
+export declare function readSnapshotManifest(directory: string, name: string, id: string, io?: WakeMomentIo, maxManifestBytes?: number): Promise<WakeSnapshotManifest | undefined>;
+/** SOURCE identity, never the copied inode's metadata: ordinary writers cannot restore ctime. */
+export declare function sameSnapshotSource(left: Identity, right: Identity): boolean;
+type CaptureInput = {
+    directory: string;
+    root: {
+        id: string;
+        path: string;
+    };
+    startedAt: string;
+    executionId: string;
+    /** Internal test bounds; not caller configuration. */
+    maxEntries?: number;
+    maxManifestBytes?: number;
+    io?: WakeMomentIo;
+    cleanup?: Set<string>;
+};
+export declare function captureWakeSnapshot(input: CaptureInput): Promise<{
+    snapshot: WakeSnapshot;
+    note?: string;
+}>;
+//# sourceMappingURL=wakeMomentSnapshot.d.ts.map

package/dist/runtime/wakeMomentSnapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wakeMomentSnapshot.d.ts","sourceRoot":"","sources":["../../src/runtime/wakeMomentSnapshot.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAIlE,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,OAAO,EAAE,qBAAqB,EAAE,YAAY,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE7G,KAAK,QAAQ,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAC3G,MAAM,MAAM,aAAa,GAAG;IAAE,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,QAAQ,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AACtI,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,EAAE,OAAO,YAAY,CAAC,OAAO,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAC3G,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CACxC,CAAC;AACF,MAAM,MAAM,YAAY,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAC5H,wBAAsB,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,eAAqB,EAAE,gBAAgB,GAAoC,MAAM,GAAG,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CAQtN;AAED,iGAAiG;AACjG,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAG3E;AAKD,KAAK,YAAY,GAAG;IAClB,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAC9F,sDAAsD;IACtD,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC/C,EAAE,CAAC,EAAE,YAAY,CAAC;IAAC,OAAO,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC1C,CAAC;AAEF,wBAAsB,mBAAmB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,YAAY,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAkBjH"}