@nathapp/nax-agent 0.91.7 → 0.91.8-canary.2

package/dist/memory/store.d.ts

@@ -0,0 +1,106 @@
+/**
+ * File-backed note mirror. Slugs are validated before I/O; directory and existing
+ * note targets must resolve inside their scope root.
+ *
+ * Reads and mutations are both run relative to a *pinned* parent. The parent's
+ * identity is verified against the directory the store resolved, the helper process
+ * then chdirs into it, and every later operation is resolved by that process against
+ * its own cwd. A name on disk can be renamed or replaced afterwards without moving
+ * the pinned directory, so nothing the store verified can be redirected underneath it:
+ * a read takes the entry's bytes from the pinned parent, and a write stages, publishes
+ * and cleans up there. Revalidating a pathname instead would leave the window this
+ * closes — a parent swapped out of the root, restored for the check, and swapped out
+ * again for the syscall names an outside file on both sides of the comparison.
+ *
+ * The caller's global cwd is never changed. Post-checks report moved directories;
+ * they are not the mechanism that prevents access to replacements.
+ *
+ * The store also owns the record files beside the notes: the `decisions.jsonl`
+ * mirror (one JSON object per line), the `pending-forgets.jsonl` record of queued
+ * forgets, `sync.json` (the sync state) and each scope's generated `MEMORY.md`.
+ * They hold no user-authored paths, so they are read and written without a slug to
+ * validate — save a pending forget's own slug, which names a note and must be one.
+ * The only scope rule is that the user files need a user directory. A record read is
+ * still confined: it is read under the project directory's pin and never follows a
+ * link out of the store.
+ */
+import type { Dirent } from "node:fs";
+import type { AgentLogger } from "#src/infra/agent-logger";
+import { withPinnedDirectory } from "#src/internal/pinned-directory";
+import { type MemoryDecision, type MemoryNote, type MemoryPendingForget, type MemoryScope } from "./types.ts";
+interface Identity {
+    readonly dev: number;
+    readonly ino: number;
+}
+/** One open file: read through its descriptor, never through its path. */
+interface OpenedFile {
+    readText(): Promise<string>;
+    close(): Promise<void>;
+}
+/** Open one file for reading without following a link at it. */
+type OpenFile = (path: string, flags: number) => Promise<OpenedFile>;
+type StatPath = (path: string) => Promise<Identity>;
+type MakeDir = (path: string, options: {
+    recursive: true;
+}) => Promise<string | undefined>;
+/** Directory entries carry their type, so a listing never has to open a path to learn what it is. */
+type ReadDirEntries = (path: string, options: {
+    withFileTypes: true;
+}) => Promise<Dirent[]>;
+type RemoveFile = (path: string, options: {
+    force: true;
+}) => Promise<void>;
+/** I/O seam: reads run under the pinned parent; deletes use the active one; `pin` takes it. */
+export declare const _memoryStoreDeps: {
+    open: OpenFile;
+    stat: StatPath;
+    mkdir: MakeDir;
+    readdir: ReadDirEntries;
+    rm: RemoveFile;
+    pin: typeof withPinnedDirectory;
+};
+/** The files this store owns, spelled out once so every caller agrees on them. */
+export interface MemoryStorePaths {
+    readonly projectDir: string;
+    readonly userDir: string | null;
+    readonly index: string;
+    readonly notesDir: string;
+    readonly decisions: string;
+    readonly pendingForgets: string;
+    readonly syncState: string;
+    readonly lock: string;
+    readonly outboxDir: string;
+    readonly userIndex: string | null;
+    readonly userNotesDir: string | null;
+}
+/** Where the sync loop has got to: the provider it talks to and the two cursors. */
+export interface MemorySyncState {
+    readonly provider: string | null;
+    readonly cursor: {
+        readonly project: string | null;
+        readonly user: string | null;
+    };
+    readonly lastPullAt: string | null;
+    readonly lastError: string | null;
+}
+/** The mirror: notes, plus the record files sync and the index refresh maintain. */
+export interface MemoryStore {
+    readonly paths: MemoryStorePaths;
+    readNote(scope: MemoryScope, slug: string): Promise<MemoryNote | null>;
+    writeNote(note: MemoryNote): Promise<void>;
+    deleteNote(scope: MemoryScope, slug: string): Promise<void>;
+    listNotes(scope: MemoryScope): Promise<MemoryNote[]>;
+    readDecisions(): Promise<MemoryDecision[]>;
+    writeDecisions(decisions: readonly MemoryDecision[]): Promise<void>;
+    readPendingForgets(): Promise<MemoryPendingForget[]>;
+    writePendingForgets(entries: readonly MemoryPendingForget[]): Promise<void>;
+    readSyncState(): Promise<MemorySyncState>;
+    writeSyncState(state: MemorySyncState): Promise<void>;
+    writeIndex(scope: MemoryScope, text: string): Promise<void>;
+}
+export declare function createMemoryStore(input: {
+    readonly projectDir: string;
+    readonly userDir?: string | null;
+    readonly logger: AgentLogger;
+}): MemoryStore;
+export {};

package/dist/memory/store.js

@@ -0,0 +1,459 @@
+import { constants } from "node:fs";
+import { mkdir, open, readdir, rm, stat } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { errorMessage } from "#src/infra/errors";
+import { NaxError } from "#src/infra/nax-error";
+import { writeFileAtomic } from "#src/internal/atomic-write";
+import { openPinnedRead, pinnedOperation, resolvePinned, withPinnedDirectory } from "#src/internal/pinned-directory";
+import { isInside, realOrRaw } from "#src/internal/realpath";
+import { byCodePoint } from "#src/internal/sort";
+import { parseMemoryNote, serializeMemoryNote } from "./note.js";
+import { decodeRecordLines, defaultSyncState, encodeRecordLines, parseDecisionLine, parsePendingForgetLine, parseSyncStateText, } from "./records.js";
+import { MEMORY_SLUG_RE, } from "./types.js";
+const ERROR_STAGE = "memory";
+const INDEX_FILE = "MEMORY.md";
+const NOTES_DIR = "notes";
+const NOTE_SUFFIX = ".md";
+const DECISIONS_FILE = "decisions.jsonl";
+const SYNC_STATE_FILE = "sync.json";
+const PENDING_FORGETS_FILE = "pending-forgets.jsonl";
+/** Reads refuse final-component links; the verified parent pin protects their ancestors. */
+const READ_FLAGS = constants.O_RDONLY | constants.O_NOFOLLOW;
+function identityOf(info) {
+    return { dev: info.dev, ino: info.ino };
+}
+/** I/O seam: reads run under the pinned parent; deletes use the active one; `pin` takes it. */
+export const _memoryStoreDeps = {
+    open: async (path, flags) => {
+        const pinned = await openPinnedRead(path, flags);
+        if (pinned !== null)
+            return pinned;
+        const handle = await open(path, flags);
+        return {
+            stat: async () => identityOf(await handle.stat()),
+            readText: () => handle.readFile({ encoding: "utf8" }),
+            close: () => handle.close(),
+        };
+    },
+    stat: async (path) => identityOf(await stat(path)),
+    mkdir: (path, options) => mkdir(path, options),
+    readdir: (path, options) => readdir(path, options),
+    rm: (path, options) => pinnedOperation(path, "rm") ?? rm(path, options),
+    pin: withPinnedDirectory,
+};
+/** `undefined`, `null` and `""` all mean "this store has no user directory". */
+function dirOrNull(dir) {
+    return dir === undefined || dir === null || dir === "" ? null : dir;
+}
+function memoryStorePaths(projectDir, userDir) {
+    return {
+        projectDir,
+        userDir,
+        index: join(projectDir, INDEX_FILE),
+        notesDir: join(projectDir, NOTES_DIR),
+        decisions: join(projectDir, DECISIONS_FILE),
+        pendingForgets: join(projectDir, PENDING_FORGETS_FILE),
+        syncState: join(projectDir, SYNC_STATE_FILE),
+        lock: join(projectDir, "sync.lock"),
+        outboxDir: join(projectDir, "outbox"),
+        userIndex: userDir === null ? null : join(userDir, INDEX_FILE),
+        userNotesDir: userDir === null ? null : join(userDir, NOTES_DIR),
+    };
+}
+function isMissing(error) {
+    if (typeof error !== "object" || error === null || !("code" in error))
+        return false;
+    return error.code === "ENOENT" || error.code === "ENOTDIR";
+}
+/** Only regular files and confined links with valid `<slug>.md` names are notes. */
+function noteSlugIn(entry) {
+    if (!entry.isFile() && !entry.isSymbolicLink())
+        return null;
+    const name = entry.name;
+    if (!name.endsWith(NOTE_SUFFIX))
+        return null;
+    const slug = name.slice(0, -NOTE_SUFFIX.length);
+    return MEMORY_SLUG_RE.test(slug) ? slug : null;
+}
+function invalidSlug(slug) {
+    return new NaxError(`memory slug "${slug}" is not a valid note slug`, "MEMORY_SLUG_INVALID", {
+        stage: ERROR_STAGE,
+        slug,
+    });
+}
+function scopeUnavailable(scope) {
+    return new NaxError(`memory scope "${scope}" is unavailable: this store has no user directory`, "MEMORY_SCOPE_UNAVAILABLE", {
+        stage: ERROR_STAGE,
+        scope,
+    });
+}
+function outsideRoot(scope, path, root, cause) {
+    return new NaxError(`memory path "${path}" is outside the memory scope root "${root}"`, "MEMORY_PATH_OUTSIDE", {
+        stage: ERROR_STAGE,
+        scope,
+        path,
+        root,
+        ...(cause === undefined ? {} : { cause }),
+    });
+}
+function isOutsidePath(error) {
+    return error instanceof NaxError && error.code === "MEMORY_PATH_OUTSIDE";
+}
+function isSymlinkLoop(error) {
+    if (typeof error !== "object" || error === null || !("code" in error))
+        return false;
+    return error.code === "ELOOP";
+}
+function sameIdentity(a, b) {
+    return a.dev === b.dev && a.ino === b.ino;
+}
+/** The slug, validated: the one check that must happen before anything touches the filesystem. */
+function validSlug(slug) {
+    if (!MEMORY_SLUG_RE.test(slug))
+        throw invalidSlug(slug);
+}
+export function createMemoryStore(input) {
+    const { logger } = input;
+    const paths = memoryStorePaths(input.projectDir, dirOrNull(input.userDir));
+    /** The notes directory of one scope, proved to sit inside that scope's root. */
+    function confinedNotesDir(scope) {
+        const root = scope === "user" ? paths.userDir : paths.projectDir;
+        const notesDir = scope === "user" ? paths.userNotesDir : paths.notesDir;
+        if (root === null || notesDir === null)
+            throw scopeUnavailable(scope);
+        if (!isInside(root, notesDir))
+            throw outsideRoot(scope, notesDir, root);
+        return { root, notesDir };
+    }
+    /** The resolved form of `path`, refused unless it is still inside the root. */
+    function confinedRealPath(scope, root, path) {
+        const resolved = realOrRaw(path);
+        if (!isInside(root, resolved))
+            throw outsideRoot(scope, path, root);
+        return resolved;
+    }
+    /** The identity of whatever is at `path`, or `null` when nothing is. */
+    async function identityAt(path) {
+        try {
+            return await _memoryStoreDeps.stat(path);
+        }
+        catch (error) {
+            if (isMissing(error))
+                return null;
+            throw error;
+        }
+    }
+    /** The note's entry in a verified directory — the one place a note path is spelled. */
+    function entryPathIn(handle, slug) {
+        return join(handle.dir, `${slug}${NOTE_SUFFIX}`);
+    }
+    /** The same entry as the caller spelled the directory: what a warning names. */
+    function entryName(handle, slug) {
+        return join(handle.spelling, `${slug}${NOTE_SUFFIX}`);
+    }
+    /** The scope's notes directory, resolved, confined and identified. */
+    async function openNotesDir(scope) {
+        const { root, notesDir } = confinedNotesDir(scope);
+        const dir = confinedRealPath(scope, root, notesDir);
+        const identity = await identityAt(dir);
+        return identity === null ? null : { scope, root, spelling: notesDir, dir, identity };
+    }
+    /** The same, creating the directory (and its parents) first: the write path's entry point. */
+    async function ensureNotesDir(scope) {
+        const { root, notesDir } = confinedNotesDir(scope);
+        await _memoryStoreDeps.mkdir(notesDir, { recursive: true });
+        const dir = confinedRealPath(scope, root, notesDir);
+        // A directory that vanishes between the `mkdir` and this `stat` is a genuine failure,
+        // not a missing mirror: the error propagates rather than being reported as "empty".
+        const identity = await _memoryStoreDeps.stat(dir);
+        return { scope, root, spelling: notesDir, dir, identity };
+    }
+    /** Detect movement of the original path; the pin is what keeps operations off a replacement. */
+    async function assertSameDirectory(handle) {
+        const dir = confinedRealPath(handle.scope, handle.root, handle.dir);
+        const identity = await identityAt(dir);
+        if (dir !== handle.dir || identity === null || !sameIdentity(identity, handle.identity)) {
+            throw outsideRoot(handle.scope, handle.dir, handle.root);
+        }
+    }
+    /**
+     * One entry's text, read relative to the verified, pinned parent — never to a pathname.
+     *
+     * The worker resolves the entry against the cwd it pinned and verified, so a directory
+     * renamed or replaced afterwards cannot redirect the answer. A plain file is then opened by
+     * name inside that same session: no path in this process is revalidated, so the window a
+     * check leaves — a parent swapped out of the root, restored for the check and swapped out
+     * again for the syscall — does not exist here. A link is a name whose bytes live elsewhere,
+     * so its target is confined against the scope root and read where it resolves.
+     */
+    async function readEntryText(handle, entry) {
+        try {
+            const resolved = await resolvePinned(entry);
+            // Only reachable inside the pinned session; a vanished entry reads as missing.
+            if (resolved === null)
+                return null;
+            if (resolved !== entry)
+                return await readConfinedTarget(handle, resolved);
+            const file = await openPinnedRead(entry, READ_FLAGS);
+            if (file === null)
+                return null;
+            try {
+                return await file.readText();
+            }
+            finally {
+                await file.close();
+            }
+        }
+        catch (error) {
+            if (isMissing(error))
+                return null;
+            if (isSymlinkLoop(error))
+                throw outsideRoot(handle.scope, entry, handle.root, error);
+            throw error;
+        }
+    }
+    /** A link's destination has its own ancestors: the notes-directory pin cannot protect them. */
+    async function readConfinedTarget(handle, target) {
+        const resolved = confinedRealPath(handle.scope, handle.root, target);
+        const dir = dirname(resolved);
+        const identity = await identityAt(dir);
+        if (identity === null)
+            return null;
+        return inPinnedDirectory({ ...handle, dir, spelling: dir, identity }, async () => {
+            // Stat and spawn may have encountered a replaced ancestor. Prove confinement from
+            // the destination pin itself, not by reopening its absolute spelling. Once proved,
+            // the final NOFOLLOW open stays relative to this same inode even if its name moves.
+            const pinnedTarget = await resolvePinned(resolved);
+            if (pinnedTarget === null)
+                return null;
+            confinedRealPath(handle.scope, handle.root, pinnedTarget);
+            if (pinnedTarget !== resolved)
+                throw outsideRoot(handle.scope, target, handle.root);
+            const file = await openConfined(handle.scope, handle.root, resolved, resolved);
+            if (file === null)
+                return null;
+            try {
+                return await file.readText();
+            }
+            finally {
+                await file.close();
+            }
+        });
+    }
+    /** One note's text, in a pinned session of its own. */
+    function readNoteText(handle, slug) {
+        return inPinnedDirectory(handle, () => readEntryText(handle, entryPathIn(handle, slug)));
+    }
+    /** The confined handle for a file, or `null` when it vanished; a link at it is refused. */
+    async function openConfined(scope, root, path, target) {
+        try {
+            return await _memoryStoreDeps.open(target, READ_FLAGS);
+        }
+        catch (error) {
+            if (isMissing(error))
+                return null;
+            if (isSymlinkLoop(error))
+                throw outsideRoot(scope, path, root, error);
+            throw error;
+        }
+    }
+    async function readNote(scope, slug) {
+        validSlug(slug);
+        const handle = await openNotesDir(scope);
+        if (handle === null)
+            return null;
+        const text = await readNoteText(handle, slug);
+        return text === null ? null : parseMemoryNote(text);
+    }
+    async function writeNote(note) {
+        validSlug(note.slug);
+        const handle = await ensureNotesDir(note.scope);
+        const target = entryPathIn(handle, note.slug);
+        // Check an existing symlink's destination, but replace the note entry itself atomically.
+        confinedRealPath(handle.scope, handle.root, target);
+        // All staging, rename and cleanup operations stay relative to the pinned parent.
+        // Checks report a moved directory without touching its replacement.
+        await inPinnedDirectory(handle, () => writeFileAtomic(target, serializeMemoryNote(note), {
+            beforePublish: () => assertSameDirectory(handle),
+            afterPublish: (stage) => verifyPublished(handle, target, stage),
+        }));
+    }
+    /** The note that was just published must be inside the root, and it is taken back if not. */
+    async function verifyPublished(handle, target, stage) {
+        try {
+            await assertSameDirectory(handle);
+            confinedRealPath(handle.scope, handle.root, target);
+        }
+        catch (error) {
+            const landed = await pinnedOperation(target, "stat");
+            if (landed !== null && sameIdentity(landed, stage))
+                await _memoryStoreDeps.rm(target, { force: true });
+            throw error;
+        }
+    }
+    function inPinnedDirectory(handle, action) {
+        return _memoryStoreDeps.pin({
+            path: handle.dir,
+            identity: handle.identity,
+            changed: () => outsideRoot(handle.scope, handle.dir, handle.root),
+        }, action);
+    }
+    async function deleteNote(scope, slug) {
+        validSlug(slug);
+        const handle = await openNotesDir(scope);
+        if (handle === null)
+            return;
+        const entry = entryPathIn(handle, slug);
+        // A note that resolves out of the root is refused, then the directory is proved to be
+        // the one verified: what goes is that entry, in that directory, never a link's target.
+        confinedRealPath(handle.scope, handle.root, entry);
+        await inPinnedDirectory(handle, async () => {
+            await assertSameDirectory(handle);
+            await _memoryStoreDeps.rm(entry, { force: true });
+            await assertSameDirectory(handle);
+        });
+    }
+    /** The listing reports a skipped file once, whatever the reason, and carries on. */
+    function warnSkipped(path, error) {
+        const message = isOutsidePath(error)
+            ? "skipping memory note outside the scope root"
+            : "skipping unreadable memory note";
+        logger.warn("memory", message, { path, error: errorMessage(error) });
+    }
+    /** The note one listed file holds, or `null` when the file is skipped (never throws). */
+    async function listedNote(handle, slug) {
+        try {
+            const text = await readEntryText(handle, entryPathIn(handle, slug));
+            // A file that vanished between the listing and the read is skipped without a warning.
+            return text === null ? null : parseMemoryNote(text);
+        }
+        catch (error) {
+            warnSkipped(entryName(handle, slug), error);
+            return null;
+        }
+    }
+    /** The notes of one listing, read inside the one pinned session that session opened. */
+    async function listedNotes(handle, slugs) {
+        const notes = [];
+        for (const slug of slugs) {
+            const note = await listedNote(handle, slug);
+            if (note !== null)
+                notes.push(note);
+        }
+        return notes;
+    }
+    async function listNotes(scope) {
+        const handle = await openNotesDir(scope);
+        if (handle === null)
+            return [];
+        await assertSameDirectory(handle);
+        let entries;
+        try {
+            entries = await _memoryStoreDeps.readdir(handle.dir, { withFileTypes: true });
+        }
+        catch (error) {
+            if (isMissing(error))
+                return [];
+            throw error;
+        }
+        // Names read from a directory that was replaced while it was listed cannot be trusted to
+        // name its notes, and a listing cannot tell — so it is refused rather than returned.
+        await assertSameDirectory(handle);
+        const slugs = entries
+            .map((entry) => noteSlugIn(entry))
+            .filter((slug) => slug !== null)
+            .sort(byCodePoint);
+        if (slugs.length === 0)
+            return [];
+        return await inPinnedDirectory(handle, () => listedNotes(handle, slugs));
+    }
+    /** A scope's root directory itself, verified and identified: records sit directly inside it. */
+    async function openScopeDir(scope) {
+        const root = scope === "user" ? paths.userDir : paths.projectDir;
+        if (root === null)
+            throw scopeUnavailable(scope);
+        const dir = confinedRealPath(scope, root, root);
+        const identity = await identityAt(dir);
+        return identity === null ? null : { scope, root, spelling: root, dir, identity };
+    }
+    /** One record file's text, read under the project directory's pin, never outside it. */
+    async function readRecordText(path) {
+        const handle = await openScopeDir("project");
+        if (handle === null)
+            return null;
+        const entry = join(handle.dir, basename(path));
+        return await inPinnedDirectory(handle, () => readEntryText(handle, entry));
+    }
+    /** Publish one record file, creating its directory on demand: staging needs one. */
+    async function writeRecordFile(path, text) {
+        await _memoryStoreDeps.mkdir(dirname(path), { recursive: true });
+        await writeFileAtomic(path, text);
+    }
+    /** One skipped mirror line, reported once, naming the line so it can be found. */
+    function warnSkippedDecision(line) {
+        logger.warn("memory", "skipping a decisions line that is not a memory decision", {
+            path: paths.decisions,
+            line,
+        });
+    }
+    function warnSkippedPendingForget(line) {
+        logger.warn("memory", "skipping a pending-forgets line that is not a pending forget", {
+            path: paths.pendingForgets,
+            line,
+        });
+    }
+    async function readDecisions() {
+        return decodeRecordLines(await readRecordText(paths.decisions), parseDecisionLine, warnSkippedDecision);
+    }
+    async function writeDecisions(decisions) {
+        await writeRecordFile(paths.decisions, encodeRecordLines(decisions));
+    }
+    async function readPendingForgets() {
+        const text = await readRecordText(paths.pendingForgets);
+        return decodeRecordLines(text, parsePendingForgetLine, warnSkippedPendingForget);
+    }
+    /** The record rewritten whole; every entry's slug must be one a note can carry. */
+    async function writePendingForgets(entries) {
+        for (const entry of entries)
+            validSlug(entry.slug);
+        await writeRecordFile(paths.pendingForgets, encodeRecordLines(entries));
+    }
+    async function readSyncState() {
+        const text = await readRecordText(paths.syncState);
+        // A missing file is the state of a store that has never synced; nothing to report.
+        if (text === null)
+            return defaultSyncState();
+        const state = parseSyncStateText(text);
+        if (state !== null)
+            return state;
+        logger.warn("memory", "memory sync state is unreadable; using the default state", { path: paths.syncState });
+        return defaultSyncState();
+    }
+    async function writeSyncState(state) {
+        await writeRecordFile(paths.syncState, `${JSON.stringify(state)}\n`);
+    }
+    /** The generated index of one scope: the user index is the one a store may not have. */
+    function indexPathFor(scope) {
+        const path = scope === "user" ? paths.userIndex : paths.index;
+        if (path === null)
+            throw scopeUnavailable(scope);
+        return path;
+    }
+    async function writeIndex(scope, text) {
+        await writeRecordFile(indexPathFor(scope), text);
+    }
+    return {
+        paths,
+        readNote,
+        writeNote,
+        deleteNote,
+        listNotes,
+        readDecisions,
+        writeDecisions,
+        readPendingForgets,
+        writePendingForgets,
+        readSyncState,
+        writeSyncState,
+        writeIndex,
+    };
+}

package/dist/memory/support.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The pieces every memory module races, reports and logs with.
+ *
+ * They live apart from the modules that use them because the memory modules form a
+ * dependency order of their own: sync needs the lock protocol, and the lock protocol needs
+ * the timer seam and the never-throwing warn — but not each other. Keeping these three here
+ * is what lets `mirror-lock.ts` and `sync.ts` both reach them without the import cycle a
+ * shared helper in either one would create.
+ *
+ * - `GLOBAL_MEMORY_TIMERS` boxes the process timer handles, so a fake clock can stand in for
+ *   them through the `MemoryTimers` contract without any caller casting a timer id.
+ * - `raceTimeout` bounds an operation nobody can cancel.
+ * - `providerAnswers` turns a probe's three failures into the one fact they share.
+ * - `warnQuietly` reports a failure without letting the reporting fail its caller.
+ */
+import type { AgentLogger } from "#src/infra/agent-logger";
+import type { MemoryProvider } from "./provider-types.ts";
+import { type MemoryTimers } from "./types.ts";
+/**
+ * The timers an operation races against when the caller injects none: the process
+ * globals, read at call time so a substituted global is still observed. The handle
+ * is handed back boxed — `MemoryTimers` keeps the timer id opaque precisely so a
+ * fake clock can stand in for the real one, and a box clears the handle this race
+ * armed without ever casting one.
+ */
+export declare const GLOBAL_MEMORY_TIMERS: MemoryTimers;
+/**
+ * `promise`'s value if it settles within `ms`, and a `MEMORY_TIMEOUT` rejection if it does not.
+ *
+ * The timer is armed when the race starts and cleared the moment either side
+ * settles, so a race that finished leaves nothing armed behind it — the property
+ * a fake clock reads as `pending() === 0`. `setTimeout` is the cancellable kind
+ * here on purpose (the `forbidden-patterns-source` exception): `Bun.sleep` cannot
+ * be cancelled, and a sleep that outlives the answer is exactly the leak this
+ * clears.
+ *
+ * A timer race does not cancel the work it raced: the provider call keeps running
+ * after a timeout, because nothing on that side of the seam accepts a signal. Its
+ * late rejection is therefore claimed here rather than left to surface as an
+ * unhandled rejection in whatever process this library runs in.
+ */
+export declare function raceTimeout<T>(promise: Promise<T>, ms: number, timers: MemoryTimers): Promise<T>;
+/** Ask the provider whether it answers within the probe deadline: a throw and a timeout are `false`. */
+export declare function providerAnswers(provider: MemoryProvider, timers: MemoryTimers): Promise<boolean>;
+/**
+ * Report a failure without letting the reporting fail the caller.
+ *
+ * The logger is an input, not a guarantee: a host logger that throws would
+ * otherwise turn the never-throws contract into a rejection at exactly the
+ * moment a result is owed, so a logger failure is discarded on purpose. Shared
+ * with the save path, whose rollback is also reported rather than thrown.
+ */
+export declare function warnQuietly(logger: AgentLogger, message: string, data: Record<string, unknown>): void;
+/**
+ * Run one bookkeeping step whose failure must not become the caller's answer.
+ *
+ * A provider's refusal is the error the caller is owed, and what follows it — taking the
+ * refused write back off the queue, putting back the note the mirror held — is a consequence
+ * of that error, not an alternative to it. A step that throws is reported and the rest still
+ * runs: a mirror left missing a note it holds, because a queue file could not be removed, is
+ * worse than an entry surviving to be refused again.
+ */
+export declare function bookkeeping(logger: AgentLogger, message: string, data: Record<string, unknown>, step: () => Promise<void>): Promise<void>;