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

package/dist/memory/outbox.js

@@ -0,0 +1,289 @@
+/**
+ * The outbox: the writes the agent has taken but a provider has not
+ * acknowledged, held on disk until a sync delivers them.
+ *
+ * One JSON file per entry, `<seq padded to 8 digits>-<clientId>.json`, written
+ * whole through `writeFileAtomic`: the bytes land in a sibling `.tmp` stage and
+ * are renamed over the entry name, so a crash leaves either the old entry or
+ * none, never a torn one, and a reader never sees a half-written file. `seq`
+ * numbers the entries in the order they were taken. It is assigned inside a
+ * promise chain local to this instance, so two concurrent `enqueue` calls on
+ * one outbox get distinct sequences; a second process writing the same
+ * directory is outside that chain and may hand out an equal sequence, which is
+ * why `list` breaks a tie by client id — the order stays deterministic rather
+ * than globally correct.
+ *
+ * A file whose name matches the entry pattern but whose content is not an entry
+ * is never silently dropped: `list` leaves it out and `listInvalid` names it, so
+ * a caller can report what it could not read. A rejected entry stays in the
+ * outbox (`state: "rejected"`) instead of being deleted — the reason is the
+ * record of why the provider refused it, and a later CLI may requeue it.
+ *
+ * The one length rule an entry carries — a reason is at most
+ * `MEMORY_FORGET_REASON_MAX_CHARS` — is enforced where an entry is *taken*
+ * (`enqueue`), never where it is read. An entry that fails a read check does not
+ * get reported: it leaves `list`, `heldKeys` and every count built on them, and
+ * the write it holds is never replayed. A read check would therefore retire the
+ * entries written before it existed, so the gate refuses the request instead, and
+ * a reason that is already on disk still lists and still replays.
+ *
+ * Reads, directory creation and removal go through the mirror store's
+ * filesystem seam, `_memoryStoreDeps`; the write path is `writeFileAtomic`, whose
+ * own seam is `_atomicWriteDeps`. Temp names are never spelled here.
+ */
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { NaxError } from "#src/infra/nax-error";
+import { writeFileAtomic } from "#src/internal/atomic-write";
+import { byCodePoint, byNumber } from "#src/internal/sort";
+import { parseMemoryNoteRecord } from "./note.js";
+import { _memoryStoreDeps } from "./store.js";
+import { MEMORY_CLIENT_ID_RE, MEMORY_SCOPES, memoryNoteKey } from "./types.js";
+import { forgetReasonRefusal } from "./validate.js";
+const ERROR_STAGE = "memory";
+/** An entry file's name: the sequence, the client id that keys it, then the suffix. */
+const ENTRY_FILE_RE = /^(\d{8})-([A-Za-z0-9_-]+)\.json$/;
+const ENTRY_SEQ_DIGITS = 8;
+const ENTRY_SUFFIX = ".json";
+/** A link at an entry name is not an entry this outbox wrote, so reads never follow one. */
+const READ_FLAGS = constants.O_RDONLY | constants.O_NOFOLLOW;
+/**
+ * Every field an entry file has to carry to be replayed; the note is checked separately.
+ *
+ * `reason` is read unbounded on purpose. A queued entry's reason is the forget's own
+ * justification and a rejected one's is the provider's answer; the length a queued reason may
+ * have is enforced where an entry is taken (`enqueue`), not where it is read — see this file's
+ * header. A read check would turn every entry written before that gate into an invalid one.
+ */
+const EntrySchema = z.object({
+    kind: z.enum(["save", "forget"]),
+    clientId: z.string().regex(MEMORY_CLIENT_ID_RE),
+    scope: z.enum(MEMORY_SCOPES),
+    slug: z.string().min(1),
+    writeMode: z.enum(["direct", "proposal"]),
+    note: z.unknown().optional(),
+    reason: z.string().optional(),
+    requestReason: z.string().optional(),
+    seq: z.number().int().positive(),
+    enqueuedAt: z.string().min(1),
+    state: z.enum(["queued", "rejected"]),
+});
+/** A path that is not there: the outbox has no entries, rather than an error to report. */
+function isMissing(error) {
+    if (typeof error !== "object" || error === null || !("code" in error))
+        return false;
+    return error.code === "ENOENT" || error.code === "ENOTDIR";
+}
+function clientIdInvalid(clientId) {
+    return new NaxError(`memory outbox client id "${clientId}" is not a valid client id`, "MEMORY_CLIENT_ID_INVALID", {
+        stage: ERROR_STAGE,
+        clientId,
+    });
+}
+/** The refusal a request the queue cannot carry is thrown as, in the store's own vocabulary. */
+function writeRefused(refusal) {
+    return new NaxError(refusal.reason, "MEMORY_WRITE_REFUSED", { stage: ERROR_STAGE, field: refusal.field });
+}
+/**
+ * Refuse a request whose reason the queue could not carry, before any entry file exists.
+ *
+ * `forgetMemoryNote` already applies this rule to a forget, so this is the gate every caller
+ * of the outbox passes rather than a second, weaker copy of it: a reason that is empty, holds
+ * a line break or runs past `MEMORY_FORGET_REASON_MAX_CHARS` is refused here and nothing is
+ * written. The bound belongs on this side — the write — because a bound applied on the read
+ * side retires the entries that predate it: they leave `list` and `heldKeys` with no word,
+ * and the writes they hold are never replayed.
+ */
+function assertReasonCarries(request) {
+    if (request.reason === undefined)
+        return;
+    const refusal = forgetReasonRefusal(request.reason);
+    if (refusal !== null)
+        throw writeRefused(refusal);
+}
+/** An entry's file name; the sequence is padded so a plain name sort is a sequence sort. */
+function entryFileName(seq, clientId) {
+    return `${String(seq).padStart(ENTRY_SEQ_DIGITS, "0")}-${clientId}${ENTRY_SUFFIX}`;
+}
+/** The sequence and client id an entry file's name carries, or `null` when it is not one. */
+function entryFileNamed(name) {
+    const match = ENTRY_FILE_RE.exec(name);
+    if (match === null)
+        return null;
+    return { name, seq: Number(match[1]), clientId: match[2] };
+}
+/** Entries in sequence order, with equal sequences ordered by client id. */
+function byEntryOrder(a, b) {
+    return byNumber(a.seq, b.seq) || byCodePoint(a.clientId, b.clientId);
+}
+/** One decoded JSON value, or `null` when the text is not JSON. */
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        // Not JSON: the caller files the file name under listInvalid.
+        return null;
+    }
+}
+/** One file's text as an entry, or `null` when its content is not an entry. */
+function toEntry(text) {
+    const parsed = EntrySchema.safeParse(parseJson(text));
+    if (!parsed.success)
+        return null;
+    const { note, ...rest } = parsed.data;
+    if (note === undefined)
+        return rest;
+    try {
+        return { ...rest, note: parseMemoryNoteRecord(note) };
+    }
+    catch {
+        // A note the note schema refuses could never be replayed: the entry is not readable.
+        return null;
+    }
+}
+/**
+ * One entry as a rejection: `reason` carries the rejection, which is what the caller
+ * reads to decide whether to requeue. The reason the request itself carried — a
+ * forget's justification — is not lost to it; it moves to `requestReason`. Re-marking
+ * an already rejected entry replaces the rejection reason and keeps the original.
+ */
+function toRejected(entry, rejectionReason) {
+    const { reason: currentReason, requestReason: keptReason, ...rest } = entry;
+    const requestReason = keptReason ?? (entry.state === "queued" ? currentReason : undefined);
+    return {
+        ...rest,
+        ...(requestReason === undefined ? {} : { requestReason }),
+        state: "rejected",
+        reason: rejectionReason,
+    };
+}
+export function createMemoryOutbox(input) {
+    const { dir } = input;
+    const now = input.now ?? (() => new Date());
+    /** The tail of the enqueue chain: the one place a sequence is handed out. */
+    let chain = Promise.resolve();
+    /** Every name in the directory, whatever it holds; a missing directory holds nothing. */
+    async function entryNames() {
+        try {
+            const dirents = await _memoryStoreDeps.readdir(dir, { withFileTypes: true });
+            return dirents.map((entry) => entry.name);
+        }
+        catch (error) {
+            if (isMissing(error))
+                return [];
+            throw error;
+        }
+    }
+    /** Every entry file in the directory, in name order: the only names this outbox reads. */
+    async function entryFiles() {
+        return (await entryNames())
+            .map((name) => entryFileNamed(name))
+            .filter((file) => file !== null)
+            .sort((a, b) => byNumber(a.seq, b.seq) || byCodePoint(a.clientId, b.clientId));
+    }
+    /** One entry file's text; `null` when it cannot be read, which makes it an invalid entry. */
+    async function readEntryText(path) {
+        try {
+            const file = await _memoryStoreDeps.open(path, READ_FLAGS);
+            try {
+                return await file.readText();
+            }
+            finally {
+                await file.close();
+            }
+        }
+        catch {
+            // A file that vanished or cannot be read is not an entry the caller can act on.
+            return null;
+        }
+    }
+    /** One named file as an entry, or `null` when its content is not one. */
+    async function readEntry(file) {
+        const text = await readEntryText(join(dir, file.name));
+        return text === null ? null : toEntry(text);
+    }
+    /** The whole directory: readable entries in sequence order, plus the names that are not. */
+    async function scan() {
+        const entries = [];
+        const invalid = [];
+        for (const file of await entryFiles()) {
+            const entry = await readEntry(file);
+            if (entry === null)
+                invalid.push(file.name);
+            else
+                entries.push(entry);
+        }
+        entries.sort(byEntryOrder);
+        return { entries, invalid };
+    }
+    /** The entry files naming one client id: found by name, so an unreadable entry is removable. */
+    async function filesFor(clientId) {
+        return (await entryFiles()).filter((file) => file.clientId === clientId);
+    }
+    /** The request with its client id settled: a supplied id is kept, a missing one is minted. */
+    function withClientId(request) {
+        const clientId = request.clientId ?? randomUUID();
+        if (!MEMORY_CLIENT_ID_RE.test(clientId))
+            throw clientIdInvalid(clientId);
+        return { ...request, clientId };
+    }
+    /** The highest sequence the directory already carries: 0 when it holds no entry. */
+    async function highestSeq() {
+        const files = await entryFiles();
+        return files.reduce((highest, file) => Math.max(highest, file.seq), 0);
+    }
+    /** Write one entry file, creating the directory only now that there is something to store. */
+    async function writeEntry(request) {
+        const seq = (await highestSeq()) + 1;
+        const entry = { ...request, seq, enqueuedAt: now().toISOString(), state: "queued" };
+        await _memoryStoreDeps.mkdir(dir, { recursive: true });
+        await writeFileAtomic(join(dir, entryFileName(seq, request.clientId)), `${JSON.stringify(entry)}\n`);
+        return entry;
+    }
+    async function enqueue(request) {
+        // The id and the reason are settled before joining the chain: a refused request must not
+        // delay the next one, and a reason the queue cannot carry writes no entry at all.
+        const prepared = withClientId(request);
+        assertReasonCarries(prepared);
+        const run = chain.then(() => writeEntry(prepared));
+        // The chain never carries a rejection forward: one failed enqueue must not poison the next.
+        chain = run.then(() => undefined, () => undefined);
+        return await run;
+    }
+    async function list() {
+        return (await scan()).entries;
+    }
+    async function listInvalid() {
+        return (await scan()).invalid;
+    }
+    async function remove(clientId) {
+        for (const file of await filesFor(clientId)) {
+            await _memoryStoreDeps.rm(join(dir, file.name), { force: true });
+        }
+    }
+    async function markRejected(clientId, reason) {
+        for (const file of await filesFor(clientId)) {
+            const entry = await readEntry(file);
+            // An entry that cannot be read cannot be rewritten either; it stays for listInvalid.
+            if (entry === null)
+                continue;
+            const rejected = toRejected(entry, reason);
+            await writeFileAtomic(join(dir, file.name), `${JSON.stringify(rejected)}\n`);
+        }
+    }
+    async function heldKeys(kind) {
+        const keys = new Set();
+        for (const entry of (await scan()).entries) {
+            if (entry.state !== "queued")
+                continue;
+            if (kind !== undefined && entry.kind !== kind)
+                continue;
+            keys.add(memoryNoteKey(entry.scope, entry.slug));
+        }
+        return keys;
+    }
+    return { enqueue, list, listInvalid, remove, markRejected, heldKeys };
+}

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

@@ -0,0 +1,50 @@
+/**
+ * The provider seam: the one interface the sync loop, the outbox drain and the
+ * save / forget operations talk to. A provider is any object that can pull a
+ * page of notes, push one write and say whether it is reachable; `search` is
+ * optional because the mirror answers keyword search locally
+ * (`searchMemoryNotes`), so only a provider with a remote search index needs it.
+ *
+ * A provider refuses a write it will never accept by throwing `NaxError` code
+ * `MEMORY_PUSH_REJECTED` with the reason as its message; `isMemoryPushRejected`
+ * recognises it. Every other throw, and a timeout, is transient and retryable.
+ */
+import type { MemoryDecision, MemoryHit, MemoryNote, MemoryNoteStatus, MemoryScope } from "./types.ts";
+/** One write to hand a provider: a note to store, or a slug to forget (a tombstone). */
+export interface MemoryWriteRequest {
+    readonly kind: "save" | "forget";
+    readonly clientId: string;
+    readonly scope: MemoryScope;
+    readonly slug: string;
+    readonly writeMode: "direct" | "proposal";
+    readonly note?: MemoryNote;
+    readonly reason?: string;
+}
+/** What the provider made of a write: the note id (or the client id) and its status. */
+export interface MemoryPushResult {
+    readonly id: string;
+    readonly status: MemoryNoteStatus;
+}
+/** One page of a pull; `done` is only true on the last page. */
+export interface MemoryPage {
+    readonly notes: readonly MemoryNote[];
+    readonly decisions?: readonly MemoryDecision[];
+    readonly nextCursor?: string;
+    readonly done: boolean;
+}
+/** The injectable provider seam; `local` is the built-in, always-reachable one. */
+export interface MemoryProvider {
+    readonly id: string;
+    pull(input: {
+        scope: MemoryScope;
+        cursor: string | null;
+        take: number;
+    }): Promise<MemoryPage>;
+    push(request: MemoryWriteRequest): Promise<MemoryPushResult>;
+    search?(input: {
+        scope: MemoryScope;
+        text: string;
+        limit: number;
+    }): Promise<readonly MemoryHit[]>;
+    reachable(): Promise<boolean>;
+}

package/dist/memory/provider-types.js

@@ -0,0 +1 @@
+export {};

package/dist/memory/records.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The record files the mirror keeps beside its notes, decoded.
+ *
+ * `decisions.jsonl` is one `MemoryDecision` per line, `pending-forgets.jsonl` one
+ * `MemoryPendingForget` per line, and `sync.json` is one `MemorySyncState`: all three are
+ * written whole by this store and read back by it, so what makes a line a decision — or
+ * a pending forget, or what makes a file a state — is a schema rather than a cast.
+ * Keeping the schemas here leaves the store to decide what a refused line *means*
+ * (skipped with a warning) and this module to decide what counts as one.
+ */
+import { z } from "zod";
+import { type MemoryDecision, type MemoryPendingForget } from "./types.ts";
+declare const SyncStateSchema: z.ZodObject<{
+    provider: z.ZodNullable<z.ZodString>;
+    cursor: z.ZodObject<{
+        project: z.ZodNullable<z.ZodString>;
+        user: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    lastPullAt: z.ZodNullable<z.ZodString>;
+    lastError: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+/** What `sync.json` holds: the shape the store's `MemorySyncState` is read back as. */
+export type ParsedSyncState = z.infer<typeof SyncStateSchema>;
+/** The state of a store that has never synced. */
+export declare function defaultSyncState(): ParsedSyncState;
+/** One mirror line as a decision, or `null` when the line is not one. */
+export declare function parseDecisionLine(line: string): MemoryDecision | null;
+/** One mirror line as a pending forget, or `null` when the line is not one. */
+export declare function parsePendingForgetLine(line: string): MemoryPendingForget | null;
+/**
+ * A JSONL record's text as its entries. A line the decoder refuses is skipped with one
+ * report naming its 1-based line number, never fatal: the other lines are still the
+ * record. A record file that is not there (`null`) is the empty record, not the absent
+ * one — a store that has never recorded anything answers `[]` and creates nothing.
+ */
+export declare function decodeRecordLines<T>(text: string | null, decode: (line: string) => T | null, warnSkipped: (line: number) => void): T[];
+/** One record file's text: one JSON object per line, and nothing at all when empty. */
+export declare function encodeRecordLines(entries: readonly unknown[]): string;
+/** The whole `sync.json` text as a state, or `null` when it does not hold one. */
+export declare function parseSyncStateText(text: string): ParsedSyncState | null;
+export {};

package/dist/memory/records.js

@@ -0,0 +1,93 @@
+/**
+ * The record files the mirror keeps beside its notes, decoded.
+ *
+ * `decisions.jsonl` is one `MemoryDecision` per line, `pending-forgets.jsonl` one
+ * `MemoryPendingForget` per line, and `sync.json` is one `MemorySyncState`: all three are
+ * written whole by this store and read back by it, so what makes a line a decision — or
+ * a pending forget, or what makes a file a state — is a schema rather than a cast.
+ * Keeping the schemas here leaves the store to decide what a refused line *means*
+ * (skipped with a warning) and this module to decide what counts as one.
+ */
+import { z } from "zod";
+import { MEMORY_CLIENT_ID_RE, MEMORY_DECISION_STATUSES, MEMORY_SCOPES, MEMORY_SLUG_RE, } from "./types.js";
+/** A decision as one mirror line; the shape is what makes a line a decision. */
+const DecisionSchema = z.object({
+    id: z.string().min(1),
+    subject: z.string().min(1),
+    predicate: z.string().min(1),
+    object: z.string().min(1),
+    updatedAt: z.string().min(1),
+    status: z.enum(MEMORY_DECISION_STATUSES),
+});
+/**
+ * A pending forget as one mirror line. The slug and the client id are the two values
+ * later code acts on — the slug names the note an approval retires, the client id names
+ * the write — so a line carries a note slug and an outbox id, never an arbitrary string.
+ */
+const PendingForgetSchema = z.object({
+    clientId: z.string().regex(MEMORY_CLIENT_ID_RE),
+    scope: z.enum(MEMORY_SCOPES),
+    slug: z.string().regex(MEMORY_SLUG_RE),
+    reason: z.string(),
+});
+const SyncStateSchema = z.object({
+    provider: z.string().nullable(),
+    cursor: z.object({ project: z.string().nullable(), user: z.string().nullable() }),
+    lastPullAt: z.string().nullable(),
+    lastError: z.string().nullable(),
+});
+/** The state of a store that has never synced. */
+export function defaultSyncState() {
+    return { provider: null, cursor: { project: null, user: null }, lastPullAt: null, lastError: null };
+}
+/** One decoded JSON value, or `null` when the text is not JSON. */
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        // Not JSON: the caller decides whether that is a skipped line or a defaulted state.
+        return null;
+    }
+}
+/** One mirror line as a decision, or `null` when the line is not one. */
+export function parseDecisionLine(line) {
+    const parsed = DecisionSchema.safeParse(parseJson(line));
+    return parsed.success ? parsed.data : null;
+}
+/** One mirror line as a pending forget, or `null` when the line is not one. */
+export function parsePendingForgetLine(line) {
+    const parsed = PendingForgetSchema.safeParse(parseJson(line));
+    return parsed.success ? parsed.data : null;
+}
+/**
+ * A JSONL record's text as its entries. A line the decoder refuses is skipped with one
+ * report naming its 1-based line number, never fatal: the other lines are still the
+ * record. A record file that is not there (`null`) is the empty record, not the absent
+ * one — a store that has never recorded anything answers `[]` and creates nothing.
+ */
+export function decodeRecordLines(text, decode, warnSkipped) {
+    if (text === null)
+        return [];
+    const entries = [];
+    for (const [index, raw] of text.split("\n").entries()) {
+        if (raw.trim() === "")
+            continue;
+        const entry = decode(raw);
+        if (entry === null) {
+            warnSkipped(index + 1);
+            continue;
+        }
+        entries.push(entry);
+    }
+    return entries;
+}
+/** One record file's text: one JSON object per line, and nothing at all when empty. */
+export function encodeRecordLines(entries) {
+    return entries.map((entry) => `${JSON.stringify(entry)}\n`).join("");
+}
+/** The whole `sync.json` text as a state, or `null` when it does not hold one. */
+export function parseSyncStateText(text) {
+    const parsed = SyncStateSchema.safeParse(parseJson(text));
+    return parsed.success ? parsed.data : null;
+}

package/dist/memory/refusal.d.ts

@@ -0,0 +1,36 @@
+/**
+ * What a permanent refusal undoes, and in which order.
+ *
+ * A provider that refuses a write will refuse it again, so the guards a write relies on
+ * while it might still be delivered come off here: the request leaves the queue and the
+ * mirror goes back to the note it held before the write staged. Both are *consequences* of
+ * the refusal, not alternatives to it, so neither step can decide whether the other runs —
+ * and neither can replace the error the caller is owed. A queue entry left behind is
+ * refused again by the next sync and costs a line; a note nobody put back costs the mirror
+ * a fact it held.
+ *
+ * It lives apart from the operations because both halves of a refusal — a save's and a
+ * forget's — need exactly this and nothing of each other's.
+ */
+import type { AgentLogger } from "#src/infra/agent-logger";
+import type { MemoryOutbox } from "./outbox.ts";
+import type { MemoryStore } from "./store.ts";
+import type { MemoryNote, MemoryScope } from "./types.ts";
+/** What a refusal needs of an operation's inputs: the mirror it restores and where it reports. */
+export interface RefusalInput {
+    readonly store: MemoryStore;
+    readonly outbox: MemoryOutbox;
+    readonly logger: AgentLogger;
+}
+/** Take a refused write back off the queue, whatever the queue does. */
+export declare function discardRefused(input: RefusalInput, clientId: string): Promise<void>;
+/**
+ * Undo a refused save: the note that was under the key before, or no note at all.
+ *
+ * A rollback that fails is reported, never thrown: the caller is owed the provider's
+ * refusal, and a second error raised here would replace it. The mirror is then left
+ * holding the refused note, which is the one case worth a warning of its own.
+ */
+export declare function restoreNote(input: RefusalInput, scope: MemoryScope, slug: string, previous: MemoryNote | null): Promise<void>;
+/** Put a refused forget's note back; a failure is reported, never thrown, for the same reason. */
+export declare function restoreForgotten(input: RefusalInput, previous: MemoryNote): Promise<void>;

package/dist/memory/refusal.js

@@ -0,0 +1,25 @@
+import { bookkeeping } from "./support.js";
+/** Take a refused write back off the queue, whatever the queue does. */
+export async function discardRefused(input, clientId) {
+    const data = { path: input.store.paths.outboxDir, clientId };
+    const remove = () => input.outbox.remove(clientId);
+    await bookkeeping(input.logger, "memory operation could not take a refused write off the queue", data, remove);
+}
+/**
+ * Undo a refused save: the note that was under the key before, or no note at all.
+ *
+ * A rollback that fails is reported, never thrown: the caller is owed the provider's
+ * refusal, and a second error raised here would replace it. The mirror is then left
+ * holding the refused note, which is the one case worth a warning of its own.
+ */
+export async function restoreNote(input, scope, slug, previous) {
+    const data = { path: input.store.paths.notesDir, slug };
+    const restore = () => (previous === null ? input.store.deleteNote(scope, slug) : input.store.writeNote(previous));
+    await bookkeeping(input.logger, "memory save could not restore the previous note", data, restore);
+}
+/** Put a refused forget's note back; a failure is reported, never thrown, for the same reason. */
+export async function restoreForgotten(input, previous) {
+    const data = { path: input.store.paths.notesDir, slug: previous.slug };
+    const rewrite = () => input.store.writeNote(previous);
+    await bookkeeping(input.logger, "memory forget could not restore the note", data, rewrite);
+}

package/dist/memory/search.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Keyword search over the mirror — the "did this note mention that?" lookup a
+ * session runs before it starts work.
+ *
+ * Matching is whole-token and Unicode-aware, never substring: `replay` finds a
+ * note about the replay budget and not one about something that "replays".
+ * Tokenising the query and the note through the same function is what makes
+ * that true by construction, on both sides of the comparison.
+ *
+ * Search is pure — notes in, hits out, no store, no filesystem, no provider —
+ * so the ranking a caller sees is a function of its arguments alone.
+ */
+import type { MemoryHit, MemoryNote } from "./types.ts";
+/** The distinct, lower-cased tokens of `text`, in first-occurrence order. */
+export declare function tokenizeMemoryQuery(text: string): readonly string[];
+/** Search the mirror's notes for the words in `text`. */
+export declare function searchMemoryNotes(notes: readonly MemoryNote[], text: string, limit: number): readonly MemoryHit[];

package/dist/memory/search.js

@@ -0,0 +1,112 @@
+/** A run of Unicode letters and digits: everything else separates tokens. */
+const TOKEN_RUN = /[\p{L}\p{N}]+/gu;
+/** The shortest token worth matching: `a` and `2` carry no signal. */
+const MIN_TOKEN_LENGTH = 2;
+/** The distinct, lower-cased tokens of `text`, in first-occurrence order. */
+export function tokenizeMemoryQuery(text) {
+    const tokens = text.toLowerCase().match(TOKEN_RUN) ?? [];
+    return [...new Set(tokens.filter((token) => token.length >= MIN_TOKEN_LENGTH))];
+}
+/** The statuses a search may return: a note not yet pushed still counts, a dead one never does. */
+const SEARCHABLE_STATUSES = new Set(["active", "pending"]);
+/** How much of a body line a snippet keeps. */
+const SNIPPET_MAX_CHARS = 160;
+/** The line breaks a body is split on: `\n`, `\r\n` and a lone `\r`. */
+const BODY_LINE_BREAK = /\r\n|\r|\n/;
+/** A query token found in the note's own words is worth twice one found in its body. */
+const HEAD_SCORE = 2;
+/** A query token found only in the body still counts, once. */
+const BODY_SCORE = 1;
+/** The text of one note that ranks it highest: its name and its one-line summary. */
+function headText(note) {
+    return `${note.slug} ${note.description}`;
+}
+/** How much one note is worth for one query: 2 per head token, 1 per body token. */
+function scoreNote(note, queryTokens) {
+    const head = new Set(tokenizeMemoryQuery(headText(note)));
+    const body = new Set(tokenizeMemoryQuery(note.body));
+    let score = 0;
+    for (const token of queryTokens) {
+        if (head.has(token))
+            score += HEAD_SCORE;
+        if (body.has(token))
+            score += BODY_SCORE;
+    }
+    return score;
+}
+/** The instant a timestamp names in epoch milliseconds, or null when it names none. */
+function instantOf(updatedAt) {
+    const ms = Date.parse(updatedAt);
+    return Number.isNaN(ms) ? null : ms;
+}
+/**
+ * Newest first by the instant `updatedAt` names, not by its literal text: the
+ * note codec accepts any non-empty single line, so two notes may carry the same
+ * moment in different UTC offsets (`…T12:00:00+09:00` is `…T03:00:00Z`), and a
+ * string compare would rank them wrongly.
+ *
+ * One total order covers every pair, so the comparator is transitive whatever the
+ * input order: values that name an instant come first, newest to oldest, and the
+ * values that name none follow, compared as text. Mixing the two comparisons
+ * instead would let an unparseable value sort lexically between two instants
+ * whose chronological order is the reverse, and the ranking would then depend on
+ * the order the notes arrived in.
+ */
+function compareUpdatedDesc(a, b) {
+    const aMs = instantOf(a);
+    const bMs = instantOf(b);
+    if (aMs === null || bMs === null) {
+        if (aMs !== null)
+            return -1;
+        if (bMs !== null)
+            return 1;
+        return a === b ? 0 : a < b ? 1 : -1;
+    }
+    return aMs === bMs ? 0 : aMs < bMs ? 1 : -1;
+}
+/** Rank: score descending, then newest first, then slug ascending. */
+function compareScored(a, b) {
+    if (a.score !== b.score)
+        return b.score - a.score;
+    const byUpdatedAt = compareUpdatedDesc(a.note.updatedAt, b.note.updatedAt);
+    if (byUpdatedAt !== 0)
+        return byUpdatedAt;
+    return a.note.slug < b.note.slug ? -1 : a.note.slug > b.note.slug ? 1 : 0;
+}
+/** The first body line that holds one of the query's tokens, cut to a snippet. */
+function snippetOf(body, queryTokens) {
+    for (const line of body.split(BODY_LINE_BREAK)) {
+        const lineTokens = new Set(tokenizeMemoryQuery(line));
+        if (queryTokens.some((token) => lineTokens.has(token)))
+            return line.slice(0, SNIPPET_MAX_CHARS);
+    }
+    return "";
+}
+/** Search the mirror's notes for the words in `text`. */
+export function searchMemoryNotes(notes, text, limit) {
+    const queryTokens = tokenizeMemoryQuery(text);
+    if (queryTokens.length === 0 || limit <= 0)
+        return [];
+    const scored = [];
+    for (const note of notes) {
+        if (!SEARCHABLE_STATUSES.has(note.status))
+            continue;
+        const score = scoreNote(note, queryTokens);
+        if (score > 0)
+            scored.push({ note, score });
+    }
+    scored.sort(compareScored);
+    return scored.slice(0, limit).map((ranked) => toHit(ranked, queryTokens));
+}
+/** The public shape of one ranked note. */
+function toHit({ note, score }, queryTokens) {
+    return {
+        slug: note.slug,
+        scope: note.scope,
+        type: note.type,
+        description: note.description,
+        status: note.status,
+        score,
+        snippet: snippetOf(note.body, queryTokens),
+    };
+}