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

package/dist/memory/delivery.d.ts

@@ -0,0 +1,38 @@
+/**
+ * What a delivered write does to the mirror.
+ *
+ * A drain's job does not end when the provider says yes: the answer has to be written back,
+ * and *which* copy of the note it is written onto is the delicate part. Two shapes of queued
+ * `save` reach a drain, and they mean different things about the mirror:
+ *
+ * - a **staged** write, whose note the mirror holds — the save had the mirror's lock, wrote
+ *   its note there, and queued the request. The mirror is then the newer fact (it may have
+ *   been edited since), so only the provider's `id` and `status` are news;
+ * - a **fenced** write, queued while another writer owned the mirror, whose note the mirror
+ *   has never seen. The provider now holds content the mirror does not: writing back only the
+ *   id and status would leave the mirror on whatever older note it happened to hold, and the
+ *   entry carrying the new content is about to be removed — the write would be lost.
+ *
+ * The two are told apart by generation, not by recency: the mirror holds this write's note
+ * exactly when the ids agree. When they do not, the mirror holds *some* other note, and the
+ * only thing that makes it authoritative is that it is itself still on its way — that is, its
+ * id is still a queued entry of this outbox, staged by a save that has not been delivered yet.
+ * A mirror note in that state is a newer local generation and is left alone; anything else is
+ * the older copy the fenced write supersedes.
+ */
+import type { MemoryOutbox, MemoryOutboxEntry } from "./outbox.ts";
+import type { MemoryPushResult } from "./provider-types.ts";
+import type { MemoryStore } from "./store.ts";
+/** What applying a delivery needs: the mirror to write and the queue that says what is still coming. */
+export interface MemoryDeliveryInput {
+    readonly store: MemoryStore;
+    readonly outbox: MemoryOutbox;
+}
+/**
+ * Write one accepted `save` back into the mirror: the provider's id and status, onto the copy
+ * the provider's content came from.
+ *
+ * A `forget` deletes only on `deleted`: a proposal-mode forget the provider has merely
+ * recorded is still pending, and the note it names stays until it is not.
+ */
+export declare function applyPushed(input: MemoryDeliveryInput, entry: MemoryOutboxEntry, answer: MemoryPushResult): Promise<void>;

package/dist/memory/delivery.js

@@ -0,0 +1,28 @@
+/** Whether `id` names a write this outbox has queued and not yet delivered — a staged generation. */
+async function awaitingDelivery(outbox, id) {
+    return (await outbox.list()).some((entry) => entry.state === "queued" && entry.clientId === id);
+}
+/**
+ * Write one accepted `save` back into the mirror: the provider's id and status, onto the copy
+ * the provider's content came from.
+ *
+ * A `forget` deletes only on `deleted`: a proposal-mode forget the provider has merely
+ * recorded is still pending, and the note it names stays until it is not.
+ */
+export async function applyPushed(input, entry, answer) {
+    if (entry.kind === "forget") {
+        if (answer.status === "deleted")
+            await input.store.deleteNote(entry.scope, entry.slug);
+        return;
+    }
+    const delivered = entry.note;
+    if (delivered === undefined)
+        return;
+    const mirrored = await input.store.readNote(entry.scope, entry.slug);
+    if (mirrored !== null && mirrored.id !== delivered.id && (await awaitingDelivery(input.outbox, mirrored.id))) {
+        // A newer local generation is still queued: it is the copy that will be delivered next.
+        return;
+    }
+    const base = mirrored !== null && mirrored.id === delivered.id ? mirrored : delivered;
+    await input.store.writeNote({ ...base, id: answer.id, status: answer.status });
+}

package/dist/memory/index-render.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The generated `MEMORY.md` index: the rendered facts a session starts with.
+ *
+ * The index is data, never instructions. Every field is sanitised to a single
+ * line and cut at `MEMORY_DESCRIPTION_MAX_CHARS` before it reaches the text, so a
+ * note cannot contribute a heading, a bullet or a sentence that reads as a
+ * directive. Section order, type order and the line shapes are the contract the
+ * memory tool and the run-stage injection both display, so they are pinned here.
+ *
+ * Rendering is pure. The caps (`maxBytes`, `maxLines`) are applied last: entries
+ * are dropped from the end, a header left with no entry goes with them, and one
+ * trailing line names how many were left out — all of it counted against the caps.
+ * `refreshMemoryIndex` is the one impure entry: it renders from a store and writes
+ * both scope indexes back through it.
+ */
+import type { MemoryStore } from "./store.ts";
+import { type MemoryDecision, type MemoryNote } from "./types.ts";
+/** The public input: the notes of both scopes and the decisions of the project. */
+export interface RenderMemoryIndexInput {
+    readonly projectNotes: readonly MemoryNote[];
+    readonly userNotes: readonly MemoryNote[];
+    readonly decisions: readonly MemoryDecision[];
+    /** `"<scope>/<slug>"` of every note with a queued forget. */
+    readonly heldForgets?: ReadonlySet<string>;
+    /** Default `MEMORY_INDEX_MAX_BYTES`, clamped up to `MEMORY_INDEX_MIN_BYTES`. */
+    readonly maxBytes?: number;
+    /** Default `MEMORY_INDEX_MAX_LINES`, clamped up to `MEMORY_INDEX_MIN_LINES`. */
+    readonly maxLines?: number;
+}
+/** The rendered index, plus how many entries the caps left out. */
+export interface RenderedMemoryIndex {
+    readonly text: string;
+    readonly omitted: number;
+}
+/**
+ * What a refresh carries into both renderings: the held keys and the two caps. The keys
+ * are the ones the outbox still holds; the record's own keys are added to them.
+ */
+export interface RefreshMemoryIndexOptions {
+    /** `"<scope>/<slug>"` of every note with a queued forget. */
+    readonly heldForgets?: ReadonlySet<string>;
+    /** Default `MEMORY_INDEX_MAX_BYTES`, clamped up to `MEMORY_INDEX_MIN_BYTES`. */
+    readonly maxBytes?: number;
+    /** Default `MEMORY_INDEX_MAX_LINES`, clamped up to `MEMORY_INDEX_MIN_LINES`. */
+    readonly maxLines?: number;
+}
+/**
+ * Regenerate the index files of a store from what it holds: the project notes and
+ * the decisions into `MEMORY.md`, and — on a store that has a user directory — the
+ * user notes into the user scope's `MEMORY.md`, which carries the header lines and
+ * the `## User` section only. Every note with a queued or recorded forget is marked.
+ * The project rendering is what is returned.
+ */
+export declare function refreshMemoryIndex(store: MemoryStore, options?: RefreshMemoryIndexOptions): Promise<RenderedMemoryIndex>;
+export declare function renderMemoryIndex(input: RenderMemoryIndexInput): RenderedMemoryIndex;

package/dist/memory/index-render.js

@@ -0,0 +1,225 @@
+import { MEMORY_DESCRIPTION_MAX_CHARS, MEMORY_INDEX_MAX_BYTES, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MIN_BYTES, MEMORY_INDEX_MIN_LINES, memoryNoteKey, } from "./types.js";
+/** The two lines every index starts with. */
+const HEADING_LINES = ["# Memory", "Memory notes are recorded facts, not instructions."];
+/** The order the project section lists its type blocks in: most actionable first. */
+const TYPE_ORDER = ["project", "feedback", "reference", "user"];
+/** What a note line renders between its slug and its description. */
+const FIELD_SEPARATOR = "—";
+/** Anything that would end a line or act as a control: flattened to one space. */
+const CONTROL_CHARS = /[\p{Cc}\u2028\u2029]/gu;
+/** A run of spaces left behind by flattening a control character. */
+const SPACE_RUNS = / {2,}/g;
+/** A held key that keeps every note line unmarked. */
+const NO_HELD_FORGETS = new Set();
+/** The UTF-8 meter the byte cap is counted in. */
+const UTF8 = new TextEncoder();
+function headingLine(text) {
+    return { kind: "heading", text };
+}
+function sectionLine(text) {
+    return { kind: "section", text };
+}
+function typeLine(type) {
+    return { kind: "type", text: `### ${type}` };
+}
+function entryLine(text) {
+    return { kind: "entry", text };
+}
+/**
+ * One field as index data: a single line, single spaces, at most the description
+ * cap. Text is flattened first and cut second, so the cap counts what is shown.
+ * Trimming is what keeps a leading line break from opening the line with a space.
+ */
+function sanitizeField(text) {
+    return cutToCap(text.replace(CONTROL_CHARS, " ").replace(SPACE_RUNS, " ").trim());
+}
+/** At most `MEMORY_DESCRIPTION_MAX_CHARS` code points: no surrogate pair is split. */
+function cutToCap(text) {
+    const chars = Array.from(text);
+    if (chars.length <= MEMORY_DESCRIPTION_MAX_CHARS)
+        return text;
+    return chars.slice(0, MEMORY_DESCRIPTION_MAX_CHARS).join("").trimEnd();
+}
+/** One note as one index line: the note's type, slug and description, then its markers. */
+function noteLine(note, heldForgets) {
+    const fields = `- [${note.type}] ${note.slug} ${FIELD_SEPARATOR} ${sanitizeField(note.description)}`;
+    return `${fields}${markersOf(note, heldForgets)}`;
+}
+/**
+ * What a note's line ends with. A note awaiting approval says so; a note with a
+ * queued forget says so. Both can hold at once — a proposal-mode note forgotten
+ * before it was approved — so they are appended in that reading order.
+ */
+function markersOf(note, heldForgets) {
+    const pending = note.status === "pending" ? " (pending)" : "";
+    const forgetting = heldForgets.has(`${note.scope}/${note.slug}`) ? " (forget pending)" : "";
+    return `${pending}${forgetting}`;
+}
+/** The notes an index shows: a superseded, rejected or deleted note is history. */
+function renderable(notes) {
+    return notes.filter((note) => note.status === "active" || note.status === "pending");
+}
+/** The project scope's notes, grouped into one block per type that has any. */
+function projectSection(input, heldForgets) {
+    const projectNotes = renderable(input.projectNotes);
+    const blocks = [];
+    for (const type of TYPE_ORDER) {
+        const lines = projectNotes
+            .filter((note) => note.type === type)
+            .map((note) => entryLine(noteLine(note, heldForgets)));
+        if (lines.length === 0)
+            continue;
+        blocks.push(typeLine(type), ...lines);
+    }
+    return blocks.length === 0 ? [] : [sectionLine("## Project"), ...blocks];
+}
+/** An `updatedAt` as a sortable number; an unparsable stamp sorts as the oldest. */
+function updatedAtOf(decision) {
+    const time = Date.parse(decision.updatedAt);
+    return Number.isNaN(time) ? 0 : time;
+}
+/** One decision as one index line: three sanitised fields, one space apart. */
+function decisionLine(decision) {
+    const fields = [decision.subject, decision.predicate, decision.object].map((field) => sanitizeField(field));
+    return `- ${fields.join(" ")}`;
+}
+/** The decisions still in force, newest first: a superseded or rejected one is history. */
+function decisionsSection(decisions) {
+    const lines = decisions
+        .filter((decision) => decision.status === "active")
+        .sort((a, b) => updatedAtOf(b) - updatedAtOf(a))
+        .map((decision) => entryLine(decisionLine(decision)));
+    return lines.length === 0 ? [] : [sectionLine("## Decisions"), ...lines];
+}
+/** The user scope's notes: one flat list, in the same line shape as the project's. */
+function userSection(userNotes, heldForgets) {
+    const lines = renderable(userNotes).map((note) => entryLine(noteLine(note, heldForgets)));
+    return lines.length === 0 ? [] : [sectionLine("## User"), ...lines];
+}
+/** Every line as the text it renders: one newline between, none trailing. */
+function joinLines(lines) {
+    return lines.map((line) => line.text).join("\n");
+}
+/**
+ * The keys both renderings mark: the caller's held forgets plus the ones the mirror has
+ * recorded. A proposal forget is answered long before anything acts on it, so the record
+ * — not the caller — is what still knows about it; a key held by both is one mark.
+ */
+async function markedForgets(store, heldForgets) {
+    const recorded = await store.readPendingForgets();
+    if (recorded.length === 0)
+        return heldForgets ?? NO_HELD_FORGETS;
+    const keys = new Set(heldForgets ?? NO_HELD_FORGETS);
+    for (const entry of recorded)
+        keys.add(memoryNoteKey(entry.scope, entry.slug));
+    return keys;
+}
+/**
+ * Regenerate the index files of a store from what it holds: the project notes and
+ * the decisions into `MEMORY.md`, and — on a store that has a user directory — the
+ * user notes into the user scope's `MEMORY.md`, which carries the header lines and
+ * the `## User` section only. Every note with a queued or recorded forget is marked.
+ * The project rendering is what is returned.
+ */
+export async function refreshMemoryIndex(store, options = {}) {
+    const heldForgets = await markedForgets(store, options.heldForgets);
+    const caps = { maxBytes: options.maxBytes, maxLines: options.maxLines };
+    const project = renderMemoryIndex({
+        projectNotes: await store.listNotes("project"),
+        userNotes: [],
+        decisions: await store.readDecisions(),
+        heldForgets,
+        ...caps,
+    });
+    await store.writeIndex("project", project.text);
+    if (store.paths.userDir !== null) {
+        const userNotes = await store.listNotes("user");
+        const user = renderMemoryIndex({ projectNotes: [], userNotes, decisions: [], heldForgets, ...caps });
+        await store.writeIndex("user", user.text);
+    }
+    return project;
+}
+/** The grouping depth of a line: a section is 2, a type block is 3, everything else 1. */
+function levelOf(line) {
+    if (line.kind === "section")
+        return 2;
+    if (line.kind === "type")
+        return 3;
+    return 1;
+}
+/** The index of the last entry line, or -1 when the index holds none. */
+function lastEntryIndex(lines) {
+    for (let index = lines.length - 1; index >= 0; index -= 1) {
+        if (lines[index].kind === "entry")
+            return index;
+    }
+    return -1;
+}
+/**
+ * The index without its last entry, and without the header that entry leaves empty.
+ *
+ * Everything after the last entry is a heading, and dropping that entry empties
+ * all of them, so the cut is a suffix: the trailing headings go with the entry and
+ * no other heading can have become empty. `null` means there is no entry left.
+ */
+function withoutLastEntry(lines) {
+    let cut = lastEntryIndex(lines);
+    if (cut < 0)
+        return null;
+    while (cut > 0 && levelOf(lines[cut - 1]) > 1)
+        cut -= 1;
+    return { lines: lines.slice(0, cut), removed: lines.slice(cut) };
+}
+/** The line a truncated index ends with: how many entries it left out and how to reach them. */
+function omittedLine(omitted) {
+    return { kind: "omitted", text: `- ${omitted} more entries not shown; use the memory tool to search.` };
+}
+/** What one line costs the joined text: its own bytes and the newline before it. */
+function lineCost(line) {
+    return UTF8.encode(line.text).byteLength + 1;
+}
+/** The bytes a run of lines costs the joined text. */
+function costOf(lines) {
+    return lines.reduce((total, line) => total + lineCost(line), 0);
+}
+/**
+ * The index cut down to its budgets, entries last-first.
+ *
+ * Each turn drops the last entry (a note line or a decision line) and any header
+ * it leaves empty, then measures again — the trailing "not shown" line is part of
+ * what is measured, so the count it names is already paid for. The running byte
+ * total is only adjusted by what a turn removed, so a long index is cut in one
+ * pass rather than re-measured from scratch. The minimums make the two headings
+ * plus that line always fit, so the loop cannot overrun.
+ */
+function truncate(lines, maxBytes, maxLines) {
+    const capBytes = Math.max(maxBytes, MEMORY_INDEX_MIN_BYTES);
+    const capLines = Math.max(maxLines, MEMORY_INDEX_MIN_LINES);
+    let kept = lines;
+    // The first line of the text carries no newline of its own.
+    let bytes = costOf(kept) - 1;
+    let omitted = 0;
+    for (;;) {
+        const tail = omitted === 0 ? [] : [omittedLine(omitted)];
+        const candidate = [...kept, ...tail];
+        if (candidate.length <= capLines && bytes + costOf(tail) <= capBytes) {
+            return { text: joinLines(candidate), omitted };
+        }
+        const drop = withoutLastEntry(kept);
+        if (drop === null)
+            return { text: joinLines(candidate), omitted };
+        kept = drop.lines;
+        bytes -= costOf(drop.removed);
+        omitted += 1;
+    }
+}
+export function renderMemoryIndex(input) {
+    const heldForgets = input.heldForgets ?? NO_HELD_FORGETS;
+    const lines = [
+        ...HEADING_LINES.map(headingLine),
+        ...projectSection(input, heldForgets),
+        ...decisionsSection(input.decisions),
+        ...userSection(input.userNotes, heldForgets),
+    ];
+    return truncate(lines, input.maxBytes ?? MEMORY_INDEX_MAX_BYTES, input.maxLines ?? MEMORY_INDEX_MAX_LINES);
+}

package/dist/memory/index.d.ts

@@ -0,0 +1,12 @@
+export { type RefreshMemoryIndexOptions, type RenderedMemoryIndex, type RenderMemoryIndexInput, refreshMemoryIndex, renderMemoryIndex, } from "./index-render.ts";
+export { createLocalMemoryProvider } from "./local-provider.ts";
+export { isMemoryPushRejected, parseMemoryNote, parseMemoryNoteRecord, serializeMemoryNote, } from "./note.ts";
+export { approveMemoryNote, forgetMemoryNote, type MemoryApproveInput, type MemoryForgetInput, type MemoryForgetResult, type MemoryOperationInput, type MemorySaveInput, type MemorySaveResult, saveMemoryNote, } from "./operations.ts";
+export { createMemoryOutbox, type MemoryOutbox, type MemoryOutboxEntry } from "./outbox.ts";
+export type { MemoryPage, MemoryProvider, MemoryPushResult, MemoryWriteRequest, } from "./provider-types.ts";
+export { searchMemoryNotes, tokenizeMemoryQuery } from "./search.ts";
+export { createMemoryStore, type MemoryStore, type MemoryStorePaths, type MemorySyncState, } from "./store.ts";
+export { raceTimeout } from "./support.ts";
+export { type MemorySyncInput, type MemorySyncResult, syncMemory } from "./sync.ts";
+export { MEMORY_CLIENT_ID_RE, MEMORY_DECISION_STATUSES, MEMORY_DESCRIPTION_MAX_CHARS, MEMORY_FORGET_REASON_MAX_CHARS, MEMORY_INDEX_MAX_BYTES, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MIN_BYTES, MEMORY_INDEX_MIN_LINES, MEMORY_NOTE_BODY_MAX_BYTES, MEMORY_NOTE_STATUSES, MEMORY_NOTE_TYPES, MEMORY_OP_TIMEOUT_MS, MEMORY_PROBE_TIMEOUT_MS, MEMORY_PULL_MAX_PAGES, MEMORY_PULL_PAGE_SIZE, MEMORY_SCOPES, MEMORY_SLUG_RE, MEMORY_SOURCE_MAX_CHARS, type MemoryDecision, type MemoryDecisionStatus, type MemoryHit, type MemoryNote, type MemoryNoteStatus, type MemoryNoteType, type MemoryNoteWrite, type MemoryPendingForget, type MemoryScope, type MemoryTimers, type MemoryWriteRefusal, } from "./types.ts";
+export { findSecret, forgetReasonRefusal, validateMemoryNoteWrite } from "./validate.ts";

package/dist/memory/index.js

@@ -0,0 +1,11 @@
+export { refreshMemoryIndex, renderMemoryIndex, } from "./index-render.js";
+export { createLocalMemoryProvider } from "./local-provider.js";
+export { isMemoryPushRejected, parseMemoryNote, parseMemoryNoteRecord, serializeMemoryNote, } from "./note.js";
+export { approveMemoryNote, forgetMemoryNote, saveMemoryNote, } from "./operations.js";
+export { createMemoryOutbox } from "./outbox.js";
+export { searchMemoryNotes, tokenizeMemoryQuery } from "./search.js";
+export { createMemoryStore, } from "./store.js";
+export { raceTimeout } from "./support.js";
+export { syncMemory } from "./sync.js";
+export { MEMORY_CLIENT_ID_RE, MEMORY_DECISION_STATUSES, MEMORY_DESCRIPTION_MAX_CHARS, MEMORY_FORGET_REASON_MAX_CHARS, MEMORY_INDEX_MAX_BYTES, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MIN_BYTES, MEMORY_INDEX_MIN_LINES, MEMORY_NOTE_BODY_MAX_BYTES, MEMORY_NOTE_STATUSES, MEMORY_NOTE_TYPES, MEMORY_OP_TIMEOUT_MS, MEMORY_PROBE_TIMEOUT_MS, MEMORY_PULL_MAX_PAGES, MEMORY_PULL_PAGE_SIZE, MEMORY_SCOPES, MEMORY_SLUG_RE, MEMORY_SOURCE_MAX_CHARS, } from "./types.js";
+export { findSecret, forgetReasonRefusal, validateMemoryNoteWrite } from "./validate.js";

package/dist/memory/local-provider.d.ts

@@ -0,0 +1,3 @@
+import type { MemoryProvider } from "./provider-types.ts";
+import type { MemoryStore } from "./store.ts";
+export declare function createLocalMemoryProvider(store: MemoryStore): MemoryProvider;

package/dist/memory/local-provider.js

@@ -0,0 +1,127 @@
+/**
+ * The built-in provider: a local mirror is its own provider, so it is always
+ * reachable and never needs a network.
+ *
+ * A `save` lands in the store with `active` (a `direct` write) or `pending` (a
+ * `proposal`, which is not in force until an approval); a `forget` deletes the
+ * note under `direct` and leaves it in place under `proposal`. Both resolve the
+ * id the caller can key the mirror on — the note's id for a save, the write's
+ * client id for a forget, which has no note left to name.
+ *
+ * A proposal forget is the one write the mirror cannot carry out, so it is queued in
+ * the store's `pending-forgets.jsonl` instead: the record is what an index refresh and
+ * an approval read later, in a process that never saw the request. A `direct` forget or
+ * a save of that key takes the entry back out — the mirror then holds what was asked
+ * for. Nothing else may write the record on this provider's behalf.
+ *
+ * A write the store can never accept — an unslugged note, a scope this store does not
+ * have, a target outside it — is refused as `MEMORY_PUSH_REJECTED`, never retried.
+ * A failure that a retry can fix (a permission error, a full disk) is left as it is,
+ * including one from the record write: the operation keeps the write queued and a
+ * later sync replays it.
+ *
+ * `pull` is the empty finished page: the mirror is the store the caller already
+ * reads, so there is nothing to pull back into it. There is no `search`; keyword
+ * search runs over the mirror through `searchMemoryNotes`.
+ */
+import { NaxError } from "#src/infra/nax-error";
+import { memoryNoteKey } from "./types.js";
+const ERROR_STAGE = "memory";
+/** The status a write lands with: a proposal is not in force until an approval. */
+const WRITE_MODE_STATUS = {
+    direct: "active",
+    proposal: "pending",
+};
+/**
+ * The store's own refusal codes: the write can never be accepted, so a retry
+ * cannot help. Everything else the store throws is I/O and stays retryable.
+ */
+const PERMANENT_STORE_CODES = new Set([
+    "MEMORY_PATH_OUTSIDE",
+    "MEMORY_SCOPE_UNAVAILABLE",
+    "MEMORY_SLUG_INVALID",
+]);
+function pushRejected(message) {
+    return new NaxError(message, "MEMORY_PUSH_REJECTED", { stage: ERROR_STAGE });
+}
+/** A permanent store refusal as a provider rejection; anything else passes through. */
+function pushRejectedFrom(error) {
+    if (!(error instanceof NaxError) || !PERMANENT_STORE_CODES.has(error.code))
+        return error;
+    return new NaxError(error.message, "MEMORY_PUSH_REJECTED", {
+        stage: ERROR_STAGE,
+        storeCode: error.code,
+        cause: error,
+    });
+}
+/** Run one store mutation, so a permanent refusal reaches the caller in the contract's code. */
+async function throughStore(action) {
+    try {
+        await action();
+    }
+    catch (error) {
+        throw pushRejectedFrom(error);
+    }
+}
+/** The entry a proposal forget leaves in the record: the request's own id and reason. */
+function queuedForget(request) {
+    return { clientId: request.clientId, scope: request.scope, slug: request.slug, reason: request.reason ?? "" };
+}
+/** Whether rewriting the record would change it: an unchanged list is not written back. */
+function sameEntries(before, after) {
+    if (before.length !== after.length)
+        return false;
+    return before.every((entry, index) => {
+        const other = after[index];
+        return (other !== undefined &&
+            entry.clientId === other.clientId &&
+            entry.scope === other.scope &&
+            entry.slug === other.slug &&
+            entry.reason === other.reason);
+    });
+}
+/**
+ * The record rewritten without `key`'s entry, and with `queued` appended after the
+ * others when a proposal forget is what took the entry out. The store validates the
+ * slugs it is handed, so a forget of a slug no note can carry is refused here — before
+ * anything is recorded — even though a proposal never reaches the notes themselves.
+ */
+async function rewriteRecord(store, key, queued) {
+    const entries = await store.readPendingForgets();
+    const kept = entries.filter((entry) => memoryNoteKey(entry.scope, entry.slug) !== key);
+    const next = queued === null ? kept : [...kept, queued];
+    // A key the record does not hold leaves the file alone: absent stays absent.
+    if (sameEntries(entries, next))
+        return;
+    await store.writePendingForgets(next);
+}
+export function createLocalMemoryProvider(store) {
+    /** A save is accepted by definition: the mirror is what the provider is. */
+    async function save(request) {
+        const note = request.note;
+        if (note === undefined)
+            throw pushRejected(`memory save for "${request.slug}" carries no note`);
+        const status = WRITE_MODE_STATUS[request.writeMode];
+        await throughStore(() => store.writeNote({ ...note, status }));
+        // Saving the slug again means it is wanted, so whatever forget it was queued for goes.
+        const key = memoryNoteKey(note.scope, note.slug);
+        await throughStore(() => rewriteRecord(store, key, null));
+        return { id: note.id, status };
+    }
+    /** A forget under direct removes the note; a proposal leaves it for an approval. */
+    async function forget(request) {
+        const direct = request.writeMode === "direct";
+        if (direct)
+            await throughStore(() => store.deleteNote(request.scope, request.slug));
+        const key = memoryNoteKey(request.scope, request.slug);
+        await throughStore(() => rewriteRecord(store, key, direct ? null : queuedForget(request)));
+        return { id: request.clientId, status: direct ? "deleted" : "pending" };
+    }
+    return {
+        id: "local",
+        pull: async () => ({ notes: [], done: true }),
+        push: async (request) => (request.kind === "save" ? save(request) : forget(request)),
+        // A local mirror has no network to be unreachable.
+        reachable: async () => true,
+    };
+}

package/dist/memory/mirror-lock.d.ts

@@ -0,0 +1,109 @@
+import type { AgentLogger } from "#src/infra/agent-logger";
+import { type MemoryStore } from "./store.ts";
+import type { MemoryScope, MemoryTimers } from "./types.ts";
+/** The lock's release: the protocol hands one back per acquisition, and it must be called. */
+export type ReleaseLock = () => Promise<void>;
+/**
+ * What the protocol needs of an operation's inputs: the mirror for its directories and lock
+ * paths, plus the clock, logger, timers and liveness probe a lock is taken and waited out with.
+ * A save's or a forget's inputs satisfy it as they are; an approval's does too once its
+ * optional seams are filled from the process defaults, and a sync's with its own pid.
+ */
+export interface MirrorLockInput {
+    readonly store: MemoryStore;
+    readonly logger: AgentLogger;
+    readonly now?: () => Date;
+    readonly timers?: MemoryTimers;
+    readonly isAlive?: (pid: number) => boolean;
+    /** The pid this process claims in the lock; default `process.pid`. */
+    readonly pid?: number;
+}
+/** One lock file and the directory it lives in: the pair every lock operation needs. */
+export interface MirrorLockTarget {
+    readonly path: string;
+    readonly dir: string;
+}
+/**
+ * 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 declare function clockOf(input: {
+    readonly now?: () => Date;
+}): () => Date;
+/**
+ * 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 declare function lockTargetsFor(store: MemoryStore, scopes: readonly MemoryScope[]): readonly MirrorLockTarget[];
+/** Every lock this store's writers share: the project's mirror and, when it has one, the user's. */
+export declare function storeLockTargets(store: MemoryStore): readonly MirrorLockTarget[];
+/** Whether a sync of this process is in flight for any mirror of this store. */
+export declare function mirrorSyncInFlight(store: MemoryStore): boolean;
+/** Hand one lock back; a failed release is reported, never thrown, so the result still returns. */
+export declare function releaseMirrorLock(input: MirrorLockInput, release: ReleaseLock): Promise<void>;
+/** Release every lock taken, latest first: the reverse of the order they were acquired in. */
+export declare function releaseMirrorLocks(input: MirrorLockInput, held: readonly ReleaseLock[]): Promise<void>;
+/**
+ * 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 declare function withMirrorLocks<T>(input: MirrorLockInput, targets: readonly MirrorLockTarget[], work: () => Promise<T>): Promise<T>;
+/**
+ * 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 declare function withMirrorLock<T>(input: MirrorLockInput, work: () => Promise<T>): Promise<T>;
+/**
+ * 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 declare function acquireMirrorLocks(input: MirrorLockInput, targets: readonly MirrorLockTarget[]): Promise<ReleaseLock | null>;
+/**
+ * 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 declare function orderedByStore<T>(lockPath: string, work: () => Promise<T>): Promise<T>;
+/**
+ * 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 declare function orderedByMirrorLocks<T>(store: MemoryStore, work: () => Promise<T>): Promise<T>;