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

package/dist/memory/mirror-lock.js

@@ -0,0 +1,334 @@
+/**
+ * The mirror's lock protocol, as the operations that change a mirror use it.
+ *
+ * A store owns more than one mirror: its project directory, and — when it has one — the
+ * user directory every project shares. The lock file is the artifact that already means
+ * "this mirror has one writer", and everything a save, a forget or an approval decides —
+ * is this key already queued, what the mirror holds, which sequence the queue takes —
+ * means nothing if two writers compute it at the same time. That is why the unit here is a
+ * *set* of locks rather than the project's one: two projects sharing a user directory are
+ * two writers of the same user notes, and a project-only lock lets both of them stage the
+ * same user slug at once. A set is taken in one canonical order (the locks sorted by their
+ * resolved path), so no two writers can hold one lock each and wait for the other's.
+ *
+ * The two halves are both needed and neither replaces the other. The in-process chain is
+ * what the lock file cannot be: the protocol classifies the caller's own pid as `own` and
+ * would let a second writer in this process take the lock over from the first, so a
+ * same-process writer waits behind the chain instead. The lock file is what the chain
+ * cannot be: it is the one fact another process can read.
+ *
+ * It is separate from the operations because all of them need exactly this and nothing of
+ * each other's: `operations.ts` reaches it for saves, forgets and approvals alike, and the
+ * split keeps that file inside its size limit without forking the protocol.
+ */
+import { join } from "node:path";
+import { errorMessage } from "#src/infra/errors";
+import { NaxError } from "#src/infra/nax-error";
+import { isProcessAlive } from "#src/internal/process-alive";
+import { realOrRaw } from "#src/internal/realpath";
+import { byCodePoint } from "#src/internal/sort";
+import { acquireSessionLock } from "#src/session-store/index";
+import { holderState, readSessionLock } from "#src/session-store/session-lock";
+import { _memoryStoreDeps } from "./store.js";
+import { GLOBAL_MEMORY_TIMERS, warnQuietly } from "./support.js";
+import { claimOperation, operationInFlight, releaseOperation, syncInFlight } from "./sync-flight.js";
+/** The code the lock protocol throws for a live holder another process owns. */
+const SESSION_LOCKED = "SESSION_LOCKED";
+/** The lock file's name inside the directory it guards. */
+const LOCK_FILE = "sync.lock";
+/** The scopes a store can have a mirror for: the project's, and the shared user one. */
+const ALL_SCOPES = ["project", "user"];
+/** How often a contending operation retries the mirror's existing lock protocol. */
+const FENCED_POLL_MS = 10;
+/**
+ * The clock an operation stamps with: the caller's, or the process clock.
+ *
+ * Every operation that stamps a note or a lock file takes the same default, so this is
+ * the one place it is spelled — an approval stamps a note without asking a provider, and
+ * still reads its clock here.
+ */
+export function clockOf(input) {
+    return input.now ?? (() => new Date());
+}
+/**
+ * The lock guarding one scope's mirror, or `null` when this store has no such scope.
+ *
+ * The target is spelled in its *resolved* form, and that is the identity every part of the
+ * protocol works with: the map key that deduplicates the set, the path a claim or a writer
+ * chain is registered under, and the file whose holder is read. Two stores can name one
+ * directory through different spellings — nax hands each store its own `userDir`, and a
+ * symlinked alias of the same directory is a different string — so a raw path would let two
+ * writers of one mirror believe they hold two different locks, which is exactly the pair the
+ * chain exists to order.
+ */
+function targetOf(store, scope) {
+    const spelling = scope === "user" ? store.paths.userDir : store.paths.projectDir;
+    if (spelling === null)
+        return null;
+    const dir = realOrRaw(spelling);
+    return { path: join(dir, LOCK_FILE), dir };
+}
+/**
+ * The locks that guard the given scopes, deduplicated and in the one order every caller
+ * takes them.
+ *
+ * The set is keyed and sorted by resolved path because two processes must agree on it
+ * without sharing any state: a writer holding one lock and waiting for the other while its
+ * counterpart holds that one and waits for this one is a deadlock, and it only stays
+ * impossible while both sides sort the same way. Sorting the spellings instead would break
+ * as soon as one caller reached the same directory through a link.
+ */
+export function lockTargetsFor(store, scopes) {
+    const byPath = new Map();
+    for (const scope of scopes) {
+        const target = targetOf(store, scope);
+        if (target !== null)
+            byPath.set(target.path, target);
+    }
+    return [...byPath.values()].sort((left, right) => byCodePoint(left.path, right.path));
+}
+/** Every lock this store's writers share: the project's mirror and, when it has one, the user's. */
+export function storeLockTargets(store) {
+    return lockTargetsFor(store, ALL_SCOPES);
+}
+/** Whether a sync of this process is in flight for any mirror of this store. */
+export function mirrorSyncInFlight(store) {
+    return storeLockTargets(store).some((target) => syncInFlight(target.path));
+}
+/** The liveness probe a lock holder is judged by: the caller's, or the real one. */
+function livenessOf(input) {
+    return input.isAlive ?? isProcessAlive;
+}
+/** Everything the lock protocol needs for one lock: the directory its guard lives in, the holder. */
+function lockDeps(input, dir) {
+    return {
+        dir,
+        pid: input.pid ?? process.pid,
+        now: clockOf(input),
+        logger: input.logger,
+        isAlive: livenessOf(input),
+    };
+}
+/**
+ * Take one mirror's lock, or `null` when another writer already holds it.
+ *
+ * A lock file another live process owns is that process's mirror, and this caller leaves it
+ * alone. A lock file naming this very process is *not* such a holder: either a sync of this
+ * process is running, or the file is a lock this process leaked when a release failed, and
+ * taking it over is the only way the next writer can deliver again. `ownSync` says which of
+ * the two this caller is — a sync passing its own claim in, an operation passing `false` and
+ * so refusing while a sync of this process is in flight (the protocol would call our own pid
+ * `own` and hand over the lock the sync still believes it holds).
+ *
+ * The sync is checked before the file is even read: a sync that has claimed this mirror but
+ * has not written its lock yet is still a sync, and waiting for it is what keeps the two
+ * of them off the mirror at once.
+ */
+async function takeMirrorLock(input, target, ownSync) {
+    if (!ownSync && syncInFlight(target.path))
+        return null;
+    const deps = lockDeps(input, target.dir);
+    const isAlive = livenessOf(input);
+    await _memoryStoreDeps.mkdir(target.dir, { recursive: true });
+    const holder = readSessionLock(target.path).body;
+    if (holder !== undefined && !reclaimable(holder, deps, isAlive))
+        return null;
+    try {
+        return acquireSessionLock(target.path, deps, isAlive);
+    }
+    catch (error) {
+        if (error instanceof NaxError && error.code === SESSION_LOCKED)
+            return null;
+        throw error;
+    }
+}
+/**
+ * Whether a lock file that is already there is this caller's to take over: a live holder is
+ * not, and everything else is — a stale holder is a process that is gone, and a pid of our
+ * own is either the sync this caller is, or a lock this process leaked.
+ */
+function reclaimable(holder, deps, isAlive) {
+    return holderState(holder, deps, isAlive) !== "live";
+}
+/** Hand one lock back; a failed release is reported, never thrown, so the result still returns. */
+export async function releaseMirrorLock(input, release) {
+    try {
+        await release();
+    }
+    catch (error) {
+        warnQuietly(input.logger, "memory operation could not release the mirror lock", {
+            path: input.store.paths.lock,
+            error: errorMessage(error),
+        });
+    }
+}
+/** Release every lock taken, latest first: the reverse of the order they were acquired in. */
+export async function releaseMirrorLocks(input, held) {
+    for (const release of [...held].reverse())
+        await releaseMirrorLock(input, release);
+}
+/** Wait one interval on the operation's own timer seam. */
+async function pause(timers, ms) {
+    await new Promise((resolve) => {
+        timers.setTimeout(resolve, ms);
+    });
+}
+/**
+ * Take one lock before declaring any write, regardless of how long its holder pauses.
+ *
+ * Neither elapsed time nor an existing queued key proves the current holder has declared
+ * its write. Waiting for ownership coordinates staging and sequence allocation across
+ * processes without guessing whether the holder is saving or syncing. A dead or stale
+ * holder is reclaimed by the existing lock protocol; a live holder must release it.
+ */
+async function waitForTurn(input, target) {
+    const timers = input.timers ?? GLOBAL_MEMORY_TIMERS;
+    for (;;) {
+        const lock = await takeMirrorLock(input, target, false);
+        if (lock !== null)
+            return lock;
+        await pause(timers, FENCED_POLL_MS);
+    }
+}
+/**
+ * Take every one of `targets`, in the order given, and hand them all back whatever happens.
+ *
+ * Nothing is awaited between the claims and the last acquisition that another writer of this
+ * process could see: the claims mark this process as a writer for the whole wait, so a sync
+ * that starts meanwhile (`operationInFlight`) leaves the mirror alone instead of taking our
+ * own pid's lock file over.
+ */
+export async function withMirrorLocks(input, targets, work) {
+    for (const target of targets)
+        claimOperation(target.path);
+    const held = [];
+    try {
+        for (const target of targets)
+            held.push(await waitForTurn(input, target));
+        return await work();
+    }
+    finally {
+        await releaseMirrorLocks(input, held);
+        for (const target of targets)
+            releaseOperation(target.path);
+    }
+}
+/**
+ * Run `work` as this store's only writer — of the project mirror and of the user mirror its
+ * projects share — and hand every lock back whatever `work` does.
+ *
+ * Waiting is the only ordering this can offer, so it is the right one for an operation that
+ * has nowhere else to put its write: a save or a forget can queue an entry and return, but an
+ * approval has to change the note it read, which means it has to be the writer when it reads
+ * it. A live holder — another process, or a sync of this process — is waited out on the
+ * operation's timers, and a failed release is reported rather than thrown, so `work`'s own
+ * answer still reaches the caller.
+ */
+export function withMirrorLock(input, work) {
+    return withMirrorLocks(input, storeLockTargets(input.store), work);
+}
+/**
+ * One release for every lock taken: each is handed back even when an earlier one fails, and
+ * the first failure is re-thrown afterwards so the caller reports it in its own terms.
+ *
+ * A run that stopped at the first failure would leave the rest held, which is a mirror nobody
+ * can write to; a run that swallowed it would report a clean release that never happened.
+ */
+function combinedRelease(releases) {
+    return async () => {
+        let failure;
+        for (const release of releases) {
+            try {
+                await release();
+            }
+            catch (error) {
+                failure ??= error;
+            }
+        }
+        if (failure !== undefined)
+            throw failure;
+    };
+}
+/**
+ * Take every lock a run needs, or `null` when any of them is held.
+ *
+ * A sync that waited would be a sync the run's caller cannot bound, so contention is a
+ * result — `locked` — rather than a wait. The locks already taken are handed back before
+ * returning, because a lock kept while reporting "I got nothing" is a mirror nobody can
+ * write to. The operation claim is read first: a write operation of this process is midway
+ * through the mirror, and the protocol would call our own pid `own` and hand this run the
+ * file that operation believes it holds.
+ *
+ * A failure that is not contention — a directory that cannot be created, a lock file that
+ * cannot be read — unwinds exactly the same way: what this run took is handed back before the
+ * error leaves. A lock abandoned here holds its heartbeat too, so the mirror it guards would
+ * stay locked to every other writer until the heartbeat aged out.
+ */
+export async function acquireMirrorLocks(input, targets) {
+    const held = [];
+    try {
+        for (const target of targets) {
+            const lock = operationInFlight(target.path) ? null : await takeMirrorLock(input, target, true);
+            if (lock === null) {
+                await releaseMirrorLocks(input, held);
+                return null;
+            }
+            held.push(lock);
+        }
+    }
+    catch (error) {
+        await releaseMirrorLocks(input, held);
+        throw error;
+    }
+    return combinedRelease([...held].reverse());
+}
+/** The tail a store with no writer in flight waits behind: nothing. */
+const NO_WRITER = Promise.resolve();
+/**
+ * The writers this process is running, by the mirror they write: the tail a writer waits behind.
+ *
+ * The lock file is what makes the mirror's writers exclusive across processes, and a
+ * same-process writer cannot rely on it — the protocol classifies our own pid as ours and
+ * would let the second writer take the lock over from the first — so this chain is what
+ * orders them here. It is keyed by the mirror rather than by the note key because one store's
+ * writers are already one writer: ordering them wholesale is what the lock says about other
+ * processes, and it costs a writer of a second key only the wait for the first to finish. The
+ * stored tail is the one that cannot reject, so one failed operation never poisons the next,
+ * and the last one of a store drops its entry — a chain left behind is a leak, not a guard.
+ *
+ * It is keyed by *every* shared lock path for the same reason the file protocol takes a set:
+ * two projects sharing a user directory are two writers of that directory, and their chains
+ * have to meet on the path they share.
+ */
+const writerChains = new Map();
+/**
+ * Run `work` once every earlier writer of the same mirror has settled.
+ *
+ * Taking the tail happens before the first `await`: a queue read after a yield is one two
+ * writers both pass, which is exactly the interleaving this orders away. The caller's own
+ * rejection is re-thrown unchanged — a refusal must reach its caller, not the next writer —
+ * and the chain continues from a tail that swallows it.
+ */
+export async function orderedByStore(lockPath, work) {
+    const run = (writerChains.get(lockPath) ?? NO_WRITER).then(work);
+    const tail = run.then(() => undefined, () => undefined);
+    writerChains.set(lockPath, tail);
+    try {
+        return await run;
+    }
+    finally {
+        if (writerChains.get(lockPath) === tail)
+            writerChains.delete(lockPath);
+    }
+}
+/**
+ * Run `work` behind every earlier writer of any mirror this store shares.
+ *
+ * One chain per lock path, nested in the same canonical order the locks themselves are taken
+ * in, so a writer of project A and a writer of project B — both sharing one user directory —
+ * meet on that directory's chain before either reaches its own lock. The nesting order has to
+ * match the file locks' order for the same deadlock reason they are sorted.
+ */
+export function orderedByMirrorLocks(store, work) {
+    return storeLockTargets(store).reduce((inner, target) => () => orderedByStore(target.path, inner), work)();
+}

package/dist/memory/note.d.ts

@@ -0,0 +1,15 @@
+import { type MemoryNote } from "./types.ts";
+/**
+ * Validate an already-decoded note-shaped object (the shared shape validation a
+ * provider pull reuses). Throws `MEMORY_NOTE_INVALID` naming the first bad key.
+ */
+export declare function parseMemoryNoteRecord(record: unknown): MemoryNote;
+/** Decode one note file. Throws `MEMORY_NOTE_INVALID` naming the first bad key. */
+export declare function parseMemoryNote(text: string): MemoryNote;
+/** Encode one note as a file: the keys in `NOTE_KEYS` order, then a blank line, then the body. */
+export declare function serializeMemoryNote(note: MemoryNote): string;
+/**
+ * Whether a provider refused a write for a reason retrying cannot fix. Every
+ * other throw (and a timeout) is transient.
+ */
+export declare function isMemoryPushRejected(error: unknown): boolean;

package/dist/memory/note.js

@@ -0,0 +1,131 @@
+/**
+ * The note codec: one Markdown file per note, frontmatter between two `---`
+ * lines (one `key: value` per line, single-line plain scalars, unknown keys
+ * ignored), then one blank line, then the body.
+ *
+ * `parseMemoryNote` validates the frontmatter with a zod schema and reports the
+ * first bad key as `MEMORY_NOTE_INVALID`; `parseMemoryNoteRecord` is the same
+ * validation over an already-decoded object, so a provider pull validates a
+ * note exactly as a mirror read does. That schema is also where the model's
+ * field limits live (`MEMORY_DESCRIPTION_MAX_CHARS`, `MEMORY_SOURCE_MAX_CHARS`,
+ * `MEMORY_NOTE_BODY_MAX_BYTES`), so a note over them can be neither read back
+ * from the mirror nor pulled into it.
+ */
+import { z } from "zod";
+import { NaxError } from "#src/infra/nax-error";
+import { MEMORY_DESCRIPTION_MAX_CHARS, MEMORY_NOTE_BODY_MAX_BYTES, MEMORY_NOTE_STATUSES, MEMORY_NOTE_TYPES, MEMORY_SCOPES, MEMORY_SLUG_RE, MEMORY_SOURCE_MAX_CHARS, } from "./types.js";
+const ERROR_STAGE = "memory";
+const FRONTMATTER_FENCE = "---";
+const FENCE_LINE = /^---[ \t]*$/;
+const BLANK_LINE = /^[ \t]*$/;
+const LINE_BREAK = /[\r\n]/;
+/** The frontmatter keys a note carries, in the order `serializeMemoryNote` writes them. */
+const NOTE_KEYS = ["id", "slug", "type", "scope", "description", "source", "updatedAt", "status"];
+const NOTE_KEY_SET = new Set(NOTE_KEYS);
+/**
+ * A one-line field: non-empty, no line break, and at most `maxChars` characters when the
+ * field is capped. The model's limits are enforced here rather than only on the save path,
+ * so a note arriving from a provider is held to the same shape a note file must have — a
+ * pull cannot persist a description, source or body the write validator would have refused.
+ */
+function singleLine(minMessage, maxChars) {
+    const bounded = maxChars === undefined ? z.string() : z.string().max(maxChars, `must be at most ${maxChars} characters`);
+    return bounded.min(1, minMessage).refine((value) => !LINE_BREAK.test(value), "must be a single line");
+}
+/** The body's cap is in UTF-8 bytes, so a multi-byte body can fail below the character count. */
+function noteBody() {
+    return z.string().refine((value) => Buffer.byteLength(value, "utf8") <= MEMORY_NOTE_BODY_MAX_BYTES, {
+        message: `must be at most ${MEMORY_NOTE_BODY_MAX_BYTES} bytes`,
+    });
+}
+const NoteSchema = z.object({
+    id: singleLine("must not be empty"),
+    slug: singleLine("must not be empty").regex(MEMORY_SLUG_RE, "must be a slug (lower-case letters, digits and '-')"),
+    type: z.enum(MEMORY_NOTE_TYPES),
+    scope: z.enum(MEMORY_SCOPES),
+    description: singleLine("must not be empty", MEMORY_DESCRIPTION_MAX_CHARS),
+    source: singleLine("must not be empty", MEMORY_SOURCE_MAX_CHARS),
+    updatedAt: singleLine("must not be empty"),
+    status: z.enum(MEMORY_NOTE_STATUSES),
+    body: noteBody(),
+});
+function invalidNote(message, key) {
+    return new NaxError(`memory note invalid: ${message}`, "MEMORY_NOTE_INVALID", key === undefined ? { stage: ERROR_STAGE } : { stage: ERROR_STAGE, key });
+}
+function stripLineBreak(line) {
+    return line.endsWith("\r") ? line.slice(0, -1) : line;
+}
+function isNoteKey(key) {
+    return NOTE_KEY_SET.has(key);
+}
+/** Split one `key: value` line; the value is everything after the first `: `. */
+function splitField(line) {
+    const separator = line.indexOf(": ");
+    if (separator !== -1)
+        return { key: line.slice(0, separator), value: line.slice(separator + 2) };
+    if (line.endsWith(":"))
+        return { key: line.slice(0, -1), value: "" };
+    return null;
+}
+/**
+ * The lines between the fences, plus the body after the required blank separator line.
+ *
+ * A note file has exactly one body layout: the closing fence, one blank line, then the
+ * body. Text on the line straight after the fence is not a body — it is a file written by
+ * something that does not follow the format — so it is refused rather than adopted as one:
+ * a body that swallowed the first line of a malformed file would be persisted and served
+ * as if it had been written deliberately.
+ */
+function splitNoteText(text) {
+    const lines = text.split("\n").map(stripLineBreak);
+    const [first] = lines;
+    if (first === undefined || !FENCE_LINE.test(first))
+        throw invalidNote("frontmatter must start with a --- line");
+    const close = lines.findIndex((line, index) => index > 0 && FENCE_LINE.test(line));
+    if (close === -1)
+        throw invalidNote("frontmatter has no closing --- line");
+    const fields = {};
+    for (const line of lines.slice(1, close)) {
+        const field = splitField(line);
+        if (field !== null && isNoteKey(field.key))
+            fields[field.key] = field.value;
+    }
+    const rest = lines.slice(close + 1);
+    const [separator] = rest;
+    if (separator !== undefined && !BLANK_LINE.test(separator)) {
+        throw invalidNote("the body must start on the line after a blank line");
+    }
+    return { fields, body: separator === undefined ? "" : rest.slice(1).join("\n") };
+}
+/**
+ * Validate an already-decoded note-shaped object (the shared shape validation a
+ * provider pull reuses). Throws `MEMORY_NOTE_INVALID` naming the first bad key.
+ */
+export function parseMemoryNoteRecord(record) {
+    const parsed = NoteSchema.safeParse(record);
+    if (parsed.success)
+        return parsed.data;
+    const issue = parsed.error.issues[0];
+    const key = issue?.path[0] === undefined ? null : String(issue.path[0]);
+    if (key === null)
+        throw invalidNote(issue?.message ?? "invalid note");
+    throw invalidNote(`${key}: ${issue?.message ?? "invalid"}`, key);
+}
+/** Decode one note file. Throws `MEMORY_NOTE_INVALID` naming the first bad key. */
+export function parseMemoryNote(text) {
+    const { fields, body } = splitNoteText(text);
+    return parseMemoryNoteRecord({ ...fields, body });
+}
+/** Encode one note as a file: the keys in `NOTE_KEYS` order, then a blank line, then the body. */
+export function serializeMemoryNote(note) {
+    const frontmatter = NOTE_KEYS.map((key) => `${key}: ${note[key]}`).join("\n");
+    const head = `${FRONTMATTER_FENCE}\n${frontmatter}\n${FRONTMATTER_FENCE}\n`;
+    return note.body === "" ? head : `${head}\n${note.body}`;
+}
+/**
+ * Whether a provider refused a write for a reason retrying cannot fix. Every
+ * other throw (and a timeout) is transient.
+ */
+export function isMemoryPushRejected(error) {
+    return error instanceof NaxError && error.code === "MEMORY_PUSH_REJECTED";
+}

package/dist/memory/operations.d.ts

@@ -0,0 +1,123 @@
+import { type AgentLogger } from "#src/infra/agent-logger";
+import { type MemoryOutbox } from "./outbox.ts";
+import type { MemoryProvider } from "./provider-types.ts";
+import type { MemoryStore } from "./store.ts";
+import { type MemoryNote, type MemoryNoteStatus, type MemoryNoteWrite, type MemoryScope, type MemoryTimers } from "./types.ts";
+/** What every operation is given: the mirror it writes, the queue and the provider it talks to. */
+export interface MemoryOperationInput {
+    readonly store: MemoryStore;
+    readonly outbox: MemoryOutbox;
+    readonly provider: MemoryProvider;
+    /**
+     * Reported through when the save cannot be undone; the other outcomes say what
+     * became of the write in the result, so a delivered save has nothing to say.
+     */
+    readonly logger: AgentLogger;
+    /** The clock a note is stamped from; default `() => new Date()`. */
+    readonly now?: () => Date;
+    /** The timer seam the probe and the push race against; default the process globals. */
+    readonly timers?: MemoryTimers;
+    /** The liveness probe a lock holder is judged by; default `isProcessAlive`. */
+    readonly isAlive?: (pid: number) => boolean;
+}
+/** One save: the write to store, the mode it is stored in, and the label it is stored under. */
+export interface MemorySaveInput extends MemoryOperationInput {
+    readonly write: MemoryNoteWrite;
+    /** `direct` takes effect at once; `proposal` is held pending until it is approved. */
+    readonly writeMode: "direct" | "proposal";
+    /** The one-line label the note records as its `source` (`"nax-chat"`, `"nax-run"`, ...). */
+    readonly source: string;
+}
+/** What a save came to: the note's slug, the status it ended in, and whether a provider took it. */
+export interface MemorySaveResult {
+    readonly slug: string;
+    readonly status: MemoryNoteStatus;
+    readonly delivered: boolean;
+}
+/** One forget: the note to retire, why, and the mode it is retired in. */
+export interface MemoryForgetInput extends MemoryOperationInput {
+    readonly scope: MemoryScope;
+    readonly slug: string;
+    readonly reason: string;
+    /** `direct` retires the note at once; `proposal` asks for approval and leaves it in place. */
+    readonly writeMode: "direct" | "proposal";
+}
+/** What a forget came to: the slug it names, the status it ended in, and whether it was delivered. */
+export interface MemoryForgetResult {
+    readonly slug: string;
+    readonly status: MemoryNoteStatus;
+    readonly delivered: boolean;
+}
+/**
+ * One approval: the note to put in force, named by its scope and slug.
+ *
+ * The mirror is the whole of what an approval decides: no queue to declare a write on, no provider
+ * to ask, and every lock seam defaulted, so `{ store, scope, slug }` is a complete input.
+ */
+export interface MemoryApproveInput {
+    readonly store: MemoryStore;
+    readonly scope: MemoryScope;
+    readonly slug: string;
+    /** The clock an approved note is re-stamped from; default `() => new Date()`. */
+    readonly now?: () => Date;
+    /** Reported through when the lock cannot be handed back; default the host logger slot. */
+    readonly logger?: AgentLogger;
+    /** The timer seam the lock wait polls on; default the process globals. */
+    readonly timers?: MemoryTimers;
+    /** The liveness probe a lock holder is judged by; default `isProcessAlive`. */
+    readonly isAlive?: (pid: number) => boolean;
+}
+/**
+ * Store one note and deliver it to the provider, or queue it for the next sync.
+ *
+ * The validator decides first, so a refusal leaves the store exactly as it found it.
+ * Everything after it runs in the mirror's own order — one save at a time in this process
+ * (`orderedByMirrorLocks`) and one writer at a time across processes (the store's locks) —
+ * because the "is this key already queued?" answer, the note staged in the mirror and the
+ * entry the queue takes are one decision: interleaved, they deliver in the wrong order or
+ * leave the mirror on the older note.
+ */
+export declare function saveMemoryNote(input: MemorySaveInput): Promise<MemorySaveResult>;
+/**
+ * Forget one note: retire it in the mirror and tell the provider, or queue the request.
+ *
+ * The reason is checked first, before the lock and before anything is written: a justification
+ * that is empty, carries a line break or runs past `MEMORY_FORGET_REASON_MAX_CHARS` is refused
+ * as `MEMORY_WRITE_REFUSED`, so no such text reaches the request the provider is pushed or the
+ * entry a queued forget leaves in the mirror's outbox.
+ *
+ * A mirror another writer owns is not this forget's to change, so it is coordinated exactly as
+ * a save is: this process's chain (`orderedByStore`) orders the forgets and saves of one mirror,
+ * and the store's lock file orders them across processes. Without the lock a forget could delete
+ * a note while another process's save restored or overwrote it, and the queue's order would
+ * describe writes that never happened in that order. A permanent refusal is the one answer
+ * undone, under `direct`, and it is rethrown; an absent slug is never queued.
+ */
+export declare function forgetMemoryNote(input: MemoryForgetInput): Promise<MemoryForgetResult>;
+/**
+ * Put one pending note in force in this mirror — or retire the note a recorded forget names.
+ *
+ * Only the note the mirror holds is consulted, so approval is a local transition rather than an
+ * authorization step: it asks no provider and writes nothing to the queue, and a forget waiting
+ * there is still waiting afterwards. What it does read besides the note is the mirror's
+ * pending-forget record — `pending-forgets.jsonl`, written by the local provider for a proposal
+ * forget — and the queue's held keys, because the index it regenerates carries those markers.
+ *
+ * An entry in the record is the one thing an approval can carry out that a rewrite cannot: the note
+ * is deleted, the entry is taken out of the record, the index is regenerated, and the note comes
+ * back as it was read with `status: "deleted"` — its `updatedAt` still says when it was written.
+ * That arm runs before the activation of a `pending` note, because a pending forget wins over a
+ * pending save: the agent asked for the note to go after asking for it to exist. A delete that
+ * throws leaves the entry where it is, so the next approval finds the forget again.
+ *
+ * The read and the rewrite are one decision, so they run under the same ordering and the same lock
+ * file a save and a forget use: this is a writer of the mirror, and what it approves must be the
+ * note the mirror holds now rather than a copy read before another writer's newer one landed.
+ * Waiting is the right answer here, unlike a save's — an approval has no queue to put its write on.
+ *
+ * A note already in force, with nothing recorded against it, is returned exactly as it stands —
+ * approving it again is not a rewrite, so its `updatedAt` still says when it was made active. A
+ * note that is history is not a note waiting for approval, and neither is one this mirror does
+ * not hold: both are `MEMORY_NOTE_NOT_FOUND`, because there is nothing to approve.
+ */
+export declare function approveMemoryNote(input: MemoryApproveInput): Promise<MemoryNote>;