@noopolis/daimon 0.2.0 → 0.2.2

package/dist/runtime/wakeMomentFs.js

@@ -0,0 +1,223 @@
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { WAKE_MOMENTS } from "../contracts/wakeMomentContract.js";
+import { assertNoSymlinkComponents, assertRuntimeDirectory, identity, sameIdentity } from "./physicalReadiness.js";
+import { WakeMomentFault, WakeMomentIo } from "./wakeMomentIo.js";
+export { WakeMomentFault } from "./wakeMomentIo.js";
+/** Diagnostics never include source paths, file contents, or arbitrary exception text. */
+export function wakeMomentFailure(error) {
+    if (error instanceof WakeMomentFault)
+        return error.reason;
+    const code = error?.code;
+    return ["EACCES", "EPERM", "ENOENT", "ENOSPC", "EIO", "ELOOP", "ENOTDIR", "EEXIST", "EMFILE", "ENAMETOOLONG", "EXDEV"].includes(code ?? "") ? code : "recording_io_failed";
+}
+/** Pin the caller's root, then re-check the same dev/ino/uid/mode at every write boundary. */
+export async function pinMomentStore(directory, io, verifyPrepared) {
+    await assertNoSymlinkComponents(directory, io.fs.lstat);
+    const before = await io.fs.lstat(directory);
+    assertPrivate(before);
+    // A raw handle is shared by the capture and separately bounded finalization scopes.
+    const fd = await io.call("pinStore", () => open(directory, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW));
+    const expected = identity(before);
+    const store = {
+        async verify(scope, target) {
+            try {
+                await scope.call("verifyPreparedStore", async () => { await verifyPrepared?.(); });
+                await assertNoSymlinkComponents(directory, scope.fs.lstat);
+                const entry = await scope.fs.lstat(directory);
+                const opened = await scope.call("statStore", () => fd.stat());
+                assertPrivate(entry);
+                if (!sameIdentity(expected, identity(entry)) || !sameIdentity(expected, identity(opened)))
+                    throw new Error("changed");
+                if (target?.startsWith(`${directory}${path.sep}`))
+                    await assertNoSymlinkComponents(path.dirname(target), scope.fs.lstat);
+            }
+            catch {
+                scope.check();
+                throw new WakeMomentFault("recording_store_changed");
+            }
+        },
+        close: () => fd.close()
+    };
+    try {
+        await store.verify(io);
+        return store;
+    }
+    catch (error) {
+        void fd.close().catch(() => undefined);
+        throw error;
+    }
+}
+function assertPrivate(entry) {
+    assertRuntimeDirectory(entry, "recording.directory", "private", { uid: process.getuid?.() ?? -1, gid: process.getgid?.() ?? -1 });
+}
+export async function openMomentDirectory(directory, io = new WakeMomentIo()) {
+    await assertNoSymlinkComponents(directory, io.fs.lstat);
+    const fd = await io.fs.open(directory, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+    try {
+        assertPrivate(await fd.stat());
+        return fd;
+    }
+    catch (error) {
+        await fd.close();
+        throw error;
+    }
+}
+export async function ensureMomentDirectory(directory, io = new WakeMomentIo()) {
+    let created = false;
+    try {
+        await io.fs.mkdir(directory, { mode: 0o700 });
+        created = true;
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+    }
+    const fd = await openMomentDirectory(directory, io);
+    try {
+        await fd.sync();
+    }
+    finally {
+        await fd.close();
+    }
+    if (created)
+        await syncMomentDirectory(path.dirname(directory), io);
+}
+export async function syncMomentDirectory(directory, io = new WakeMomentIo()) {
+    const fd = await io.fs.open(directory, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+    try {
+        await fd.sync();
+    }
+    finally {
+        await fd.close();
+    }
+}
+/** Refuses symlinks, special files and hard-linked metadata, including a FIFO before it can block. */
+export async function openMomentFile(file, flags = constants.O_RDONLY, io = new WakeMomentIo()) {
+    const fd = await io.fs.open(file, flags | constants.O_NOFOLLOW | constants.O_NONBLOCK, 0o600);
+    try {
+        const stat = await fd.stat();
+        if (!stat.isFile() || stat.nlink !== 1)
+            throw new WakeMomentFault("invalid_metadata_file");
+        return fd;
+    }
+    catch (error) {
+        await fd.close();
+        throw error;
+    }
+}
+export function manifestBytes(value, max = WAKE_MOMENTS.maxManifestBytes) {
+    const bytes = JSON.stringify(value);
+    if (Buffer.byteLength(bytes) > Math.min(max, WAKE_MOMENTS.maxManifestBytes))
+        throw new WakeMomentFault("manifest_size_limit");
+    return bytes;
+}
+export async function readMomentJson(file, io = new WakeMomentIo(), max = WAKE_MOMENTS.maxManifestBytes) {
+    const fd = await openMomentFile(file, constants.O_RDONLY, io);
+    try {
+        const limit = Math.min(max, WAKE_MOMENTS.maxManifestBytes);
+        if ((await fd.stat()).size > limit)
+            throw new WakeMomentFault("manifest_size_limit");
+        const chunks = [];
+        let length = 0;
+        for (;;) {
+            const buffer = Buffer.alloc(Math.min(64 * 1024, limit + 1 - length));
+            const { bytesRead } = await fd.read(buffer, 0, buffer.length, null);
+            if (!bytesRead)
+                break;
+            length += bytesRead;
+            if (length > limit)
+                throw new WakeMomentFault("manifest_size_limit");
+            chunks.push(buffer.subarray(0, bytesRead));
+        }
+        return JSON.parse(Buffer.concat(chunks, length).toString("utf8"));
+    }
+    finally {
+        await fd.close();
+    }
+}
+/** Unlike FileHandle.writeFile, each syscall is admitted through the cancellation fence. */
+export async function writeMomentBytes(fd, bytes) {
+    const buffer = typeof bytes === "string" ? Buffer.from(bytes) : bytes;
+    for (let offset = 0; offset < buffer.length;) {
+        const { bytesWritten } = await fd.write(buffer, offset, Math.min(64 * 1024, buffer.length - offset), null);
+        if (!bytesWritten)
+            throw new WakeMomentFault("short_write");
+        offset += bytesWritten;
+    }
+}
+export async function writeMomentJson(file, bytes, io, cleanup, verifyReplacement) {
+    let temporary;
+    do {
+        temporary = `${file}.${randomUUID()}.tmp`;
+    } while (await momentPathExists(temporary, io));
+    const fd = await openMomentFile(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, io);
+    cleanup.add(temporary); // Exclusive creation, never the name alone, establishes cleanup ownership.
+    try {
+        await writeMomentBytes(fd, bytes);
+        await fd.sync();
+        await fd.close();
+        let reservation;
+        try {
+            reservation = await openMomentFile(file, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, io);
+            cleanup.add(file);
+        }
+        catch (error) {
+            if (!verifyReplacement || error.code !== "EEXIST")
+                throw error;
+            await verifyReplacement(); // The caller must establish ownership before replacement.
+            reservation = await openMomentFile(file, constants.O_RDONLY, io);
+        }
+        await reservation.close();
+        await io.fs.rename(temporary, file);
+        cleanup.delete(temporary);
+        await syncMomentDirectory(path.dirname(file), io);
+    }
+    finally {
+        await fd.close();
+    }
+}
+export async function momentPathExists(target, io = new WakeMomentIo()) {
+    try {
+        await io.fs.lstat(target);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+/** Never recurse until root identity AND the target's parent components have just been verified. */
+export async function cleanMomentPaths(paths, store, io) {
+    for (const target of paths) {
+        await removeMomentPath(target, store, io);
+        paths.delete(target);
+    }
+}
+/** Explicit traversal keeps recursive cleanup cancellable between individual filesystem calls. */
+export async function removeMomentPath(target, store, io) {
+    await store.verify(io, target);
+    let entry;
+    try {
+        entry = await io.fs.lstat(target);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        throw error;
+    }
+    if (entry.isDirectory()) {
+        await assertNoSymlinkComponents(target, io.fs.lstat);
+        for await (const child of await io.fs.opendir(target))
+            await removeMomentPath(path.join(target, child.name), store, io);
+        await store.verify(io, target);
+        await io.fs.rmdir(target);
+    }
+    else {
+        await store.verify(io, target);
+        await io.fs.unlink(target);
+    }
+}

package/dist/runtime/wakeMomentHistory.d.ts

@@ -0,0 +1,26 @@
+import { WakeMomentIo } from "./wakeMomentIo.js";
+export declare const SNAPSHOT_NAME: RegExp;
+export declare const snapshotRootName: (id: string) => string;
+declare const INDEX_VERSION = "noopolis.daimon.wake-latest.v1";
+export type SnapshotIndex = {
+    version: typeof INDEX_VERSION;
+    snapshot: string;
+    oldest: string | null;
+};
+export declare function snapshotName(startedAt: string, executionId: string): string;
+export declare function snapshotTime(name: string): number;
+/** Eligibility precedes BOTH base selection and retention protection, not only deletion. */
+export declare function eligibleSnapshot(directory: string, name: string, io: WakeMomentIo, rollback?: ReadonlySet<string>): Promise<boolean>;
+/** Only a missing/invalid index or an expired oldest name requires history enumeration. */
+export declare function completeSnapshotNames(directory: string, io?: WakeMomentIo, rollback?: ReadonlySet<string>): Promise<string[]>;
+export declare function indexFromNames(names: string[]): SnapshotIndex | undefined;
+export declare function latestSnapshotIndex(directory: string, io: WakeMomentIo, rollback?: ReadonlySet<string>): Promise<{
+    index?: SnapshotIndex;
+    names?: string[];
+}>;
+/** Called after manifest publication, before the marker: a crash leaves an invalid index,
+ * never a valid stale pointer hiding a newer complete snapshot. Clock rollback keeps the newer base. */
+export declare function indexWithSnapshot(previous: SnapshotIndex | undefined, name: string): SnapshotIndex;
+export declare function writeSnapshotIndex(directory: string, index: SnapshotIndex, io: WakeMomentIo, cleanup: Set<string>): Promise<void>;
+export {};
+//# sourceMappingURL=wakeMomentHistory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"wakeMomentHistory.d.ts","sourceRoot":"","sources":["../../src/runtime/wakeMomentHistory.ts"],"names":[],"mappings":"AAIA,OAAO,EAAmB,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAElE,eAAO,MAAM,aAAa,QAAyC,CAAC;AACpE,eAAO,MAAM,gBAAgB,GAAI,IAAI,MAAM,KAAG,MAAoE,CAAC;AACnH,QAAA,MAAM,aAAa,mCAAmC,CAAC;AAEvD,MAAM,MAAM,aAAa,GAAG;IAAE,OAAO,EAAE,OAAO,aAAa,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAEvG,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAG3E;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKjD;AAED,4FAA4F;AAC5F,wBAAsB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,YAAY,EAAE,QAAQ,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAU1I;AAED,2FAA2F;AAC3F,wBAAsB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,eAAqB,EAAE,QAAQ,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAczI;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,aAAa,GAAG,SAAS,CAEzE;AAUD,wBAAsB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,YAAY,EAAE,QAAQ,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC;IAAE,KAAK,CAAC,EAAE,aAAa,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAOnK;AAED;wGACwG;AACxG,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,aAAa,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,CAMlG;AAED,wBAAsB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,EAAE,EAAE,YAAY,EAAE,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CASvI"}

package/dist/runtime/wakeMomentHistory.js

@@ -0,0 +1,109 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { WAKE_MOMENTS } from "../contracts/wakeMomentContract.js";
+import { readMomentJson, writeMomentJson } from "./wakeMomentFs.js";
+import { WakeMomentFault, WakeMomentIo } from "./wakeMomentIo.js";
+export const SNAPSHOT_NAME = /^\d{8}T\d{9}Z-[A-Za-z0-9._-]{1,200}$/;
+export const snapshotRootName = (id) => id === "." || id === ".." ? id.replaceAll(".", "%2E") : id;
+const INDEX_VERSION = "noopolis.daimon.wake-latest.v1";
+const INDEX_BYTES = 1024;
+export function snapshotName(startedAt, executionId) {
+    const execution = /^[A-Za-z0-9._-]{1,128}$/.test(executionId) ? executionId : `sha256-${createHash("sha256").update(executionId).digest("hex")}`;
+    return `${startedAt.replace(/[-:.]/g, "")}-${execution}`;
+}
+export function snapshotTime(name) {
+    if (!SNAPSHOT_NAME.test(name))
+        return NaN;
+    const value = `${name.slice(0, 4)}-${name.slice(4, 6)}-${name.slice(6, 8)}T${name.slice(9, 11)}:${name.slice(11, 13)}:${name.slice(13, 15)}.${name.slice(15, 18)}Z`;
+    const time = Date.parse(value);
+    return Number.isFinite(time) && new Date(time).toISOString() === value ? time : NaN;
+}
+/** Eligibility precedes BOTH base selection and retention protection, not only deletion. */
+export async function eligibleSnapshot(directory, name, io, rollback) {
+    if (!Number.isFinite(snapshotTime(name)))
+        return false;
+    const target = path.join(directory, name);
+    if ([target, `${target}.manifest.json`, `${target}${WAKE_MOMENTS.completionSuffix}`].some((file) => rollback?.has(file)))
+        return false;
+    try {
+        const entry = await io.fs.lstat(target), manifest = await io.fs.lstat(`${target}.manifest.json`);
+        const marker = await io.fs.lstat(`${target}${WAKE_MOMENTS.completionSuffix}`);
+        return entry.isDirectory() && manifest.isFile() && manifest.nlink === 1
+            && marker.isFile() && marker.size === 0 && marker.nlink === 1;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+/** Only a missing/invalid index or an expired oldest name requires history enumeration. */
+export async function completeSnapshotNames(directory, io = new WakeMomentIo(), rollback) {
+    const names = [];
+    try {
+        for await (const entry of await io.fs.opendir(directory)) {
+            if (entry.isDirectory() && await eligibleSnapshot(directory, entry.name, io, rollback))
+                names.push(entry.name);
+        }
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    names.sort((a, b) => snapshotTime(b) - snapshotTime(a) || b.localeCompare(a));
+    // Timestamp ties use publication metadata; no historical manifest contents are read.
+    const stamps = new Map();
+    for (let i = 0; i < names.length; i++)
+        if (snapshotTime(names[i]) === snapshotTime(names[i - 1] ?? "") || snapshotTime(names[i]) === snapshotTime(names[i + 1] ?? "")) {
+            stamps.set(names[i], (await io.fs.lstat(path.join(directory, `${names[i]}.manifest.json`), { bigint: true })).mtimeNs);
+        }
+    return names.sort((a, b) => snapshotTime(b) - snapshotTime(a) || ((stamps.get(a) ?? 0n) < (stamps.get(b) ?? 0n) ? 1 : (stamps.get(a) ?? 0n) > (stamps.get(b) ?? 0n) ? -1 : b.localeCompare(a)));
+}
+export function indexFromNames(names) {
+    return names[0] ? { version: INDEX_VERSION, snapshot: names[0], oldest: names.length > 1 ? names[names.length - 1] : null } : undefined;
+}
+function isSnapshotIndex(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).length !== 3)
+        return false;
+    const index = value;
+    return index.version === INDEX_VERSION && typeof index.snapshot === "string" && Number.isFinite(snapshotTime(index.snapshot))
+        && (index.oldest === null || (typeof index.oldest === "string" && index.oldest !== index.snapshot
+            && Number.isFinite(snapshotTime(index.oldest)) && snapshotTime(index.oldest) <= snapshotTime(index.snapshot)));
+}
+export async function latestSnapshotIndex(directory, io, rollback) {
+    try {
+        const value = await readMomentJson(path.join(directory, "latest"), io, INDEX_BYTES);
+        if (isSnapshotIndex(value) && await eligibleSnapshot(directory, value.snapshot, io, rollback))
+            return { index: value };
+    }
+    catch {
+        io.check(); /* The bounded index is a cache; recover from missing/damaged metadata. */
+    }
+    const names = await completeSnapshotNames(directory, io, rollback);
+    return { index: indexFromNames(names), names };
+}
+/** Called after manifest publication, before the marker: a crash leaves an invalid index,
+ * never a valid stale pointer hiding a newer complete snapshot. Clock rollback keeps the newer base. */
+export function indexWithSnapshot(previous, name) {
+    if (!previous)
+        return { version: INDEX_VERSION, snapshot: name, oldest: null };
+    const newest = snapshotTime(name) >= snapshotTime(previous.snapshot) ? name : previous.snapshot;
+    const others = [previous.oldest, newest === name ? previous.snapshot : name].filter((entry) => entry !== null);
+    others.sort((a, b) => snapshotTime(a) - snapshotTime(b));
+    return { version: INDEX_VERSION, snapshot: newest, oldest: others[0] };
+}
+export async function writeSnapshotIndex(directory, index, io, cleanup) {
+    const target = path.join(directory, "latest");
+    await writeMomentJson(target, JSON.stringify(index), io, cleanup, async () => {
+        let owned = false;
+        try {
+            owned = isSnapshotIndex(await readMomentJson(target, io, INDEX_BYTES));
+        }
+        catch {
+            io.check();
+        }
+        if (!owned)
+            throw new WakeMomentFault("invalid_latest_index");
+    });
+    cleanup.delete(target);
+}

package/dist/runtime/wakeMomentIo.d.ts

@@ -0,0 +1,22 @@
+import * as fs from "node:fs/promises";
+export declare class WakeMomentFault extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+/** Internal fault-injection seam, never configuration or a public runtime export. */
+export type WakeMomentIoProbe = (operation: string, target?: string, entries?: number) => void | Promise<void>;
+/** Every filesystem call checks cancellation before issuing I/O and after it settles. */
+export declare class WakeMomentIo {
+    private readonly probe?;
+    readonly fs: typeof fs;
+    verifyWrite?: (target?: string) => Promise<void>;
+    private aborted;
+    private expires;
+    constructor(probe?: WakeMomentIoProbe | undefined);
+    check(): void;
+    call<T>(operation: string, action: () => Promise<T>, target?: string): Promise<T>;
+    bounded<T>(milliseconds: number, action: () => Promise<T>): Promise<T>;
+    private handle;
+    private directory;
+}
+//# sourceMappingURL=wakeMomentIo.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"wakeMomentIo.d.ts","sourceRoot":"","sources":["../../src/runtime/wakeMomentIo.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAKvC,qBAAa,eAAgB,SAAQ,KAAK;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM;gBAAd,MAAM,EAAE,MAAM;CACpC;AAED,qFAAqF;AACrF,MAAM,MAAM,iBAAiB,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE/G,yFAAyF;AACzF,qBAAa,YAAY;IAMX,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC;IALnC,QAAQ,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC;IACvB,WAAW,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAAY;gBAEE,KAAK,CAAC,EAAE,iBAAiB,YAAA;IAgBtD,KAAK,IAAI,IAAI;IAOP,IAAI,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAoBjF,OAAO,CAAC,CAAC,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAa5E,OAAO,CAAC,MAAM;IASd,OAAO,CAAC,SAAS;CAkBlB"}

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"}