@4fu/arbor-notes-sqlite 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@4fu/arbor-notes-sqlite",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "description": "The default NoteStore: one copy of every note, checked writes, revisions, anchors and the active set on SQLite beside the journal.",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
+  },
+  "types": "./index.d.ts",
+  "main": "./index.js",
+  "files": [
+    "diff.d.ts",
+    "diff.js",
+    "index.d.ts",
+    "index.js",
+    "notes.d.ts",
+    "notes.js",
+    "refs.d.ts",
+    "refs.js",
+    "schema.d.ts",
+    "schema.js",
+    "score.d.ts",
+    "score.js",
+    "search.d.ts",
+    "search.js"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/4fuu/arbor.git",
+    "directory": "packages/notes-sqlite"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@4fu/arbor-errors": "0.1.0",
+    "@4fu/arbor-interfaces": "0.1.0"
+  }
+}

package/refs.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Note refs (docs/journal.md#refs).
+ *
+ * A note is `n012`; one of its revisions is `n012@3`. A bare `n012` means the
+ * latest revision. Everything else in the store reads refs through here, so a
+ * malformed one is refused in the core's error shape instead of reaching
+ * storage.
+ */
+import type { EventRef, NoteId, NoteRef, Ref, WindowRef } from "@4fu/arbor-interfaces";
+export declare function noteIdOf(id: number): NoteId;
+export declare function noteRefOf(id: number, revision: number): NoteRef;
+/** The note id a ref names, with or without a revision, or `null`. */
+export declare function parseNoteId(ref: string): number | null;
+/** The note id and the revision a ref names; a bare id means the latest. */
+export declare function parseNoteRef(ref: string): {
+    id: number;
+    revision: number | null;
+} | null;
+/** The forms one note ref is looked up under: the revision, then the bare id. */
+export declare function noteRefForms(ref: Ref): Ref[];
+/** A window ref read back out of storage. */
+export declare function storedWindowRef(value: string | null): WindowRef | null;
+/** An event ref read back out of storage. */
+export declare function storedEventRef(value: string | null): EventRef | null;

package/refs.js

@@ -0,0 +1,49 @@
+/**
+ * Note refs (docs/journal.md#refs).
+ *
+ * A note is `n012`; one of its revisions is `n012@3`. A bare `n012` means the
+ * latest revision. Everything else in the store reads refs through here, so a
+ * malformed one is refused in the core's error shape instead of reaching
+ * storage.
+ */
+export function noteIdOf(id) {
+    return `n${id}`;
+}
+export function noteRefOf(id, revision) {
+    return `n${id}@${revision}`;
+}
+/** The note id a ref names, with or without a revision, or `null`. */
+export function parseNoteId(ref) {
+    const match = /^n(\d+)(?:@(\d+))?$/.exec(ref);
+    if (match === null)
+        return null;
+    return Number(match[1]);
+}
+/** The note id and the revision a ref names; a bare id means the latest. */
+export function parseNoteRef(ref) {
+    const match = /^n(\d+)(?:@(\d+))?$/.exec(ref);
+    if (match === null)
+        return null;
+    return { id: Number(match[1]), revision: match[2] === undefined ? null : Number(match[2]) };
+}
+/** The forms one note ref is looked up under: the revision, then the bare id. */
+export function noteRefForms(ref) {
+    const match = /^(n\d+)@(\d+)$/.exec(ref);
+    return match === null ? [ref] : [ref, match[1]];
+}
+/** A window ref read back out of storage. */
+export function storedWindowRef(value) {
+    if (value === null)
+        return null;
+    if (!/^c\d+$/.test(value))
+        throw new Error(`stored window ref ${value} is not a ref`);
+    return value;
+}
+/** An event ref read back out of storage. */
+export function storedEventRef(value) {
+    if (value === null)
+        return null;
+    if (!/^r\d+$/.test(value))
+        throw new Error(`stored event ref ${value} is not a ref`);
+    return value;
+}

package/schema.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The SQLite schema for notes (docs/memory.md).
+ *
+ * Notes are the long-term memory: one copy of each, shared by every window.
+ * The store keeps its own database beside the journal's, and records every
+ * write in the journal as a `note_revision` event, so the journal stays the one
+ * record of what happened while the store stays the one copy of the content.
+ *
+ * Layout:
+ *
+ * - `notes` - one row per note: its current state. A delete leaves the row and
+ *   marks it `deleted`, so every ref to it keeps resolving.
+ * - `note_revisions` - one row per revision, append-only, in the one global
+ *   write order `wseq`. The body of every revision that ever was stays here.
+ * - `note_usage` - what windows cite, use as evidence and read, decayed by age
+ *   when it is scored.
+ * - `note_refs` - the refs every revision names, with the note id when the ref
+ *   is a note: the backlinks one lookup reads, and the evidence links the
+ *   credit walk follows.
+ * - `note_epochs` - one row per snapshot epoch, with the write order it was
+ *   built at.
+ * - `note_epoch_items` - the active notes one epoch froze, with the summaries
+ *   it froze them at, so a window's prefix never changes under it.
+ * - `notes_fts` - trigram index for exact substrings over title, summary and
+ *   body.
+ */
+import type { DatabaseSync } from "node:sqlite";
+/** Bumped when a change makes an existing database unusable. */
+export declare const SCHEMA_VERSION = 1;
+/** The FTS5 table note search reads. */
+export declare const FTS_TABLE = "notes_fts";
+/** Create the schema when it is missing, and check the version when it is not. */
+export declare function createSchema(db: DatabaseSync): void;
+export declare function readMeta(db: DatabaseSync, key: string): string | null;

package/schema.js

@@ -0,0 +1,141 @@
+/**
+ * The SQLite schema for notes (docs/memory.md).
+ *
+ * Notes are the long-term memory: one copy of each, shared by every window.
+ * The store keeps its own database beside the journal's, and records every
+ * write in the journal as a `note_revision` event, so the journal stays the one
+ * record of what happened while the store stays the one copy of the content.
+ *
+ * Layout:
+ *
+ * - `notes` - one row per note: its current state. A delete leaves the row and
+ *   marks it `deleted`, so every ref to it keeps resolving.
+ * - `note_revisions` - one row per revision, append-only, in the one global
+ *   write order `wseq`. The body of every revision that ever was stays here.
+ * - `note_usage` - what windows cite, use as evidence and read, decayed by age
+ *   when it is scored.
+ * - `note_refs` - the refs every revision names, with the note id when the ref
+ *   is a note: the backlinks one lookup reads, and the evidence links the
+ *   credit walk follows.
+ * - `note_epochs` - one row per snapshot epoch, with the write order it was
+ *   built at.
+ * - `note_epoch_items` - the active notes one epoch froze, with the summaries
+ *   it froze them at, so a window's prefix never changes under it.
+ * - `notes_fts` - trigram index for exact substrings over title, summary and
+ *   body.
+ */
+/** Bumped when a change makes an existing database unusable. */
+export const SCHEMA_VERSION = 1;
+/** The FTS5 table note search reads. */
+export const FTS_TABLE = "notes_fts";
+const STATEMENTS = [
+    `PRAGMA journal_mode = WAL`,
+    `PRAGMA foreign_keys = ON`,
+    `PRAGMA busy_timeout = 5000`,
+    `CREATE TABLE IF NOT EXISTS meta (
+     key TEXT PRIMARY KEY,
+     value TEXT NOT NULL
+   )`,
+    // The note's current state. The revisions are the history; this row is what
+    // a list, a search and the active set read.
+    `CREATE TABLE IF NOT EXISTS notes (
+     id INTEGER PRIMARY KEY AUTOINCREMENT,
+     created INTEGER NOT NULL,
+     updated INTEGER NOT NULL,
+     revision INTEGER NOT NULL,
+     title TEXT NOT NULL,
+     summary TEXT NOT NULL,
+     body TEXT NOT NULL,
+     status TEXT NOT NULL,
+     window TEXT,
+     anchor TEXT,
+     event TEXT
+   )`,
+    `CREATE INDEX IF NOT EXISTS notes_status ON notes (status, id)`,
+    // One row per revision, append-only. `wseq` is the one global write order
+    // the epoch's delta is measured from; one note has one row per revision.
+    `CREATE TABLE IF NOT EXISTS note_revisions (
+     wseq INTEGER PRIMARY KEY AUTOINCREMENT,
+     note INTEGER NOT NULL,
+     revision INTEGER NOT NULL,
+     title TEXT NOT NULL,
+     summary TEXT NOT NULL,
+     body TEXT NOT NULL,
+     deleted INTEGER NOT NULL DEFAULT 0,
+     time INTEGER NOT NULL,
+     window TEXT,
+     event TEXT,
+     anchor TEXT,
+     refs TEXT,
+     UNIQUE (note, revision)
+   )`,
+    // What windows cite, use as evidence and read. One event is recorded once,
+    // so the unique index leaves the reads - which name no event - alone.
+    `CREATE TABLE IF NOT EXISTS note_usage (
+     note INTEGER NOT NULL,
+     kind TEXT NOT NULL,
+     weight REAL NOT NULL,
+     window TEXT,
+     event TEXT,
+     time INTEGER NOT NULL
+   )`,
+    `CREATE UNIQUE INDEX IF NOT EXISTS note_usage_event
+     ON note_usage (note, kind, event) WHERE event IS NOT NULL`,
+    `CREATE INDEX IF NOT EXISTS note_usage_time ON note_usage (time)`,
+    // The refs every revision names: what it cites and what it holds as
+    // evidence. `to_note` is set when the ref is a note, which is what makes the
+    // evidence links between notes - the ones the credit walk follows.
+    `CREATE TABLE IF NOT EXISTS note_refs (
+     note INTEGER NOT NULL,
+     revision INTEGER NOT NULL,
+     kind TEXT NOT NULL,
+     ref TEXT NOT NULL,
+     to_note INTEGER,
+     weight REAL NOT NULL,
+     time INTEGER NOT NULL,
+     PRIMARY KEY (note, revision, kind, ref)
+   )`,
+    `CREATE INDEX IF NOT EXISTS note_refs_ref ON note_refs (ref, weight DESC)`,
+    `CREATE TABLE IF NOT EXISTS note_epochs (
+     epoch INTEGER PRIMARY KEY AUTOINCREMENT,
+     time INTEGER NOT NULL,
+     wseq INTEGER NOT NULL,
+     budget_count INTEGER NOT NULL,
+     budget_tokens INTEGER NOT NULL
+   )`,
+    // The active notes one epoch froze, with the summaries it froze them at.
+    `CREATE TABLE IF NOT EXISTS note_epoch_items (
+     epoch INTEGER NOT NULL,
+     note INTEGER NOT NULL,
+     revision INTEGER NOT NULL,
+     title TEXT NOT NULL,
+     summary TEXT NOT NULL,
+     tokens INTEGER NOT NULL,
+     time INTEGER NOT NULL,
+     PRIMARY KEY (epoch, note)
+   )`,
+    // Exact substrings, for Chinese and mixed text.
+    `CREATE VIRTUAL TABLE IF NOT EXISTS ${FTS_TABLE}
+     USING fts5(title, summary, body, tokenize = 'trigram')`,
+];
+/** Create the schema when it is missing, and check the version when it is not. */
+export function createSchema(db) {
+    // The version lives in the one table that has to exist before anything else.
+    db.exec(`CREATE TABLE IF NOT EXISTS meta (
+       key TEXT PRIMARY KEY,
+       value TEXT NOT NULL
+     )`);
+    const version = readMeta(db, "schema_version");
+    if (version !== null && Number(version) !== SCHEMA_VERSION) {
+        throw new Error(`notes schema ${version} is not supported by this build (${SCHEMA_VERSION}); migrate or rebuild the database`);
+    }
+    for (const statement of STATEMENTS)
+        db.exec(statement);
+    if (version === null) {
+        db.prepare("INSERT INTO meta (key, value) VALUES ('schema_version', ?)").run(String(SCHEMA_VERSION));
+    }
+}
+export function readMeta(db, key) {
+    const row = db.prepare("SELECT value FROM meta WHERE key = ?").get(key);
+    return row === undefined ? null : row.value;
+}

package/score.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The active set's usage score (docs/memory.md#the-active-set).
+ *
+ * At each snapshot epoch the host picks the active set by usage score - what
+ * windows cite, use as evidence and read, decayed by age - within a count and
+ * token budget. Credit for the active set flows through evidence links up to
+ * three hops, decaying 50/25/12.5, with a visited set so a loop is walked once.
+ * A note gets its direct credit or its linked share, whichever is larger.
+ *
+ * The walk follows the evidence links of a note's current revision, in both
+ * directions, and a deleted note earns nothing and passes nothing on. A range
+ * link is not walked: `Anchor.range` is a string, not the refs of the two ends
+ * of the range, so arbor has no range link to follow.
+ */
+import type { DatabaseSync } from "node:sqlite";
+import type { ActiveSetBudget } from "@4fu/arbor-interfaces";
+/** What a window's own use of a note is worth against a bare cite. */
+export declare const USE_WEIGHTS: {
+    readonly cite: 1;
+    readonly evidence: 1;
+    readonly read: 0.25;
+};
+/** How far credit flows, and what each hop is worth: 50, 25, 12.5. */
+export declare const MAX_CREDIT_HOPS = 3;
+/** One note, scored for the active set. */
+export interface ScoredNote {
+    note: number;
+    score: number;
+    /** The token estimate of the note's summary line, for the budget. */
+    tokens: number;
+}
+/** What is left of one use after its age: half of it every half-life. */
+export declare function decay(ageMs: number, halfLifeMs: number): number;
+/**
+ * A rough token estimate of one rendered line: a Chinese, Japanese or Korean
+ * character is one token, and every other script about four characters. It is
+ * an estimate, and it is the same one for every note, which is what the budget
+ * needs.
+ */
+export declare function estimateTokens(text: string): number;
+/** Every use still worth something, as decayed credit per note. */
+export declare function loadCredit(db: DatabaseSync, now: number, halfLifeMs: number): Map<number, number>;
+/**
+ * The evidence links between notes, in both directions. Only a note's current
+ * revision carries links, so an edge from an older revision is not there.
+ */
+export declare function loadEdges(db: DatabaseSync): Map<number, Set<number>>;
+/**
+ * The share of other notes' credit that reaches one note: a breadth-first walk
+ * over the evidence links, each note credited once at the shortest distance
+ * the walk reaches it, so a loop is walked once.
+ */
+export declare function linkedCredit(note: number, credit: ReadonlyMap<number, number>, edges: ReadonlyMap<number, Set<number>>): number;
+/** Every note that is not deleted, with its score, strongest first. */
+export declare function scoreNotes(db: DatabaseSync, now: number, halfLifeMs: number): ScoredNote[];
+/**
+ * The rule pick: the strongest notes first, ties by id, within the count and
+ * the token budget. A note with no use is not picked; freshness reaches a
+ * window through the delta, not through the snapshot.
+ */
+export declare function pickByBudget(scored: readonly ScoredNote[], budget: ActiveSetBudget): ScoredNote[];
+/**
+ * The judge's bounded share: at most a share of the budget, additive only. The
+ * judge adds notes the rule score did not pick and never drops one it did,
+ * because it never outweighs the model's own use.
+ */
+export declare function applyJudgeShare(picked: readonly ScoredNote[], scored: ReadonlyMap<number, ScoredNote>, judgeKeep: readonly string[], judgeShare: number, budget: ActiveSetBudget): ScoredNote[];

package/score.js

@@ -0,0 +1,203 @@
+/**
+ * The active set's usage score (docs/memory.md#the-active-set).
+ *
+ * At each snapshot epoch the host picks the active set by usage score - what
+ * windows cite, use as evidence and read, decayed by age - within a count and
+ * token budget. Credit for the active set flows through evidence links up to
+ * three hops, decaying 50/25/12.5, with a visited set so a loop is walked once.
+ * A note gets its direct credit or its linked share, whichever is larger.
+ *
+ * The walk follows the evidence links of a note's current revision, in both
+ * directions, and a deleted note earns nothing and passes nothing on. A range
+ * link is not walked: `Anchor.range` is a string, not the refs of the two ends
+ * of the range, so arbor has no range link to follow.
+ */
+/** What a window's own use of a note is worth against a bare cite. */
+export const USE_WEIGHTS = { cite: 1, evidence: 1, read: 0.25 };
+/** How far credit flows, and what each hop is worth: 50, 25, 12.5. */
+export const MAX_CREDIT_HOPS = 3;
+/** Usage older than this many half-lives has decayed to nothing worth. */
+const USAGE_HALF_LIVES_LOADED = 10;
+function toNumber(value) {
+    if (typeof value === "number")
+        return value;
+    if (typeof value === "bigint")
+        return Number(value);
+    throw new Error(`notes: storage returned a value that is not a number: ${String(value)}`);
+}
+/** What is left of one use after its age: half of it every half-life. */
+export function decay(ageMs, halfLifeMs) {
+    if (ageMs <= 0)
+        return 1;
+    return Math.pow(0.5, ageMs / halfLifeMs);
+}
+/**
+ * A rough token estimate of one rendered line: a Chinese, Japanese or Korean
+ * character is one token, and every other script about four characters. It is
+ * an estimate, and it is the same one for every note, which is what the budget
+ * needs.
+ */
+export function estimateTokens(text) {
+    let tokens = 0;
+    let other = 0;
+    for (const character of text) {
+        const codePoint = character.codePointAt(0);
+        if (isCjk(codePoint)) {
+            tokens += 1;
+            continue;
+        }
+        other += 1;
+        if (other === 4) {
+            tokens += 1;
+            other = 0;
+        }
+    }
+    return tokens + (other > 0 ? 1 : 0);
+}
+function isCjk(codePoint) {
+    return ((codePoint >= 0x3400 && codePoint <= 0x4dbf) ||
+        (codePoint >= 0x4e00 && codePoint <= 0x9fff) ||
+        (codePoint >= 0xf900 && codePoint <= 0xfaff) ||
+        (codePoint >= 0x3040 && codePoint <= 0x30ff) ||
+        (codePoint >= 0xac00 && codePoint <= 0xd7af) ||
+        (codePoint >= 0x20000 && codePoint <= 0x2a6df) ||
+        (codePoint >= 0x2a700 && codePoint <= 0x2ebef));
+}
+/** Every use still worth something, as decayed credit per note. */
+export function loadCredit(db, now, halfLifeMs) {
+    const since = now - halfLifeMs * USAGE_HALF_LIVES_LOADED;
+    const rows = db
+        .prepare("SELECT note, weight, time FROM note_usage WHERE time > ?")
+        .all(since);
+    const credit = new Map();
+    for (const row of rows) {
+        const note = toNumber(row.note);
+        const weight = toNumber(row.weight);
+        const value = weight * decay(now - toNumber(row.time), halfLifeMs);
+        credit.set(note, (credit.get(note) ?? 0) + value);
+    }
+    return credit;
+}
+/**
+ * The evidence links between notes, in both directions. Only a note's current
+ * revision carries links, so an edge from an older revision is not there.
+ */
+export function loadEdges(db) {
+    const rows = db
+        .prepare(`SELECT e.note AS from_note, e.to_note AS to_note
+       FROM note_refs e
+       JOIN notes f ON f.id = e.note AND f.revision = e.revision AND f.status != 'deleted'
+       JOIN notes t ON t.id = e.to_note AND t.status != 'deleted'
+       WHERE e.kind = 'evidence' AND e.to_note IS NOT NULL`)
+        .all();
+    const edges = new Map();
+    const link = (from, to) => {
+        const neighbours = edges.get(from) ?? new Set();
+        neighbours.add(to);
+        edges.set(from, neighbours);
+    };
+    for (const row of rows) {
+        const from = toNumber(row.from_note);
+        const to = toNumber(row.to_note);
+        link(from, to);
+        link(to, from);
+    }
+    return edges;
+}
+/**
+ * The share of other notes' credit that reaches one note: a breadth-first walk
+ * over the evidence links, each note credited once at the shortest distance
+ * the walk reaches it, so a loop is walked once.
+ */
+export function linkedCredit(note, credit, edges) {
+    const visited = new Set([note]);
+    let frontier = [note];
+    let total = 0;
+    for (let hop = 1; hop <= MAX_CREDIT_HOPS && frontier.length > 0; hop += 1) {
+        const next = [];
+        for (const current of frontier) {
+            for (const neighbour of edges.get(current) ?? []) {
+                if (visited.has(neighbour))
+                    continue;
+                visited.add(neighbour);
+                next.push(neighbour);
+            }
+        }
+        if (next.length === 0)
+            break;
+        const share = Math.pow(0.5, hop);
+        for (const reached of next) {
+            total += (credit.get(reached) ?? 0) * share;
+        }
+        frontier = next;
+    }
+    return total;
+}
+/** Every note that is not deleted, with its score, strongest first. */
+export function scoreNotes(db, now, halfLifeMs) {
+    const credit = loadCredit(db, now, halfLifeMs);
+    const edges = loadEdges(db);
+    const rows = db
+        .prepare("SELECT id, title, summary FROM notes WHERE status != 'deleted'")
+        .all();
+    const scored = rows.map((row) => {
+        const note = toNumber(row.id);
+        const direct = credit.get(note) ?? 0;
+        return {
+            note,
+            score: Math.max(direct, linkedCredit(note, credit, edges)),
+            tokens: estimateTokens(`${row.title}\n${row.summary}`),
+        };
+    });
+    scored.sort((a, b) => b.score - a.score || a.note - b.note);
+    return scored;
+}
+/**
+ * The rule pick: the strongest notes first, ties by id, within the count and
+ * the token budget. A note with no use is not picked; freshness reaches a
+ * window through the delta, not through the snapshot.
+ */
+export function pickByBudget(scored, budget) {
+    const picked = [];
+    let tokens = 0;
+    for (const item of scored) {
+        if (item.score <= 0)
+            break;
+        if (picked.length >= budget.count)
+            break;
+        if (tokens + item.tokens > budget.tokens)
+            continue;
+        picked.push(item);
+        tokens += item.tokens;
+    }
+    return picked;
+}
+/**
+ * The judge's bounded share: at most a share of the budget, additive only. The
+ * judge adds notes the rule score did not pick and never drops one it did,
+ * because it never outweighs the model's own use.
+ */
+export function applyJudgeShare(picked, scored, judgeKeep, judgeShare, budget) {
+    const slots = Math.max(0, Math.floor(judgeShare * budget.count));
+    if (slots === 0 || judgeKeep.length === 0)
+        return [...picked];
+    const chosen = new Set(picked.map((item) => item.note));
+    let tokens = picked.reduce((total, item) => total + item.tokens, 0);
+    const added = [];
+    for (const ref of judgeKeep) {
+        if (added.length >= slots || chosen.size >= budget.count)
+            break;
+        const match = /^n(\d+)(?:@(\d+))?$/.exec(ref);
+        if (match === null)
+            continue;
+        const item = scored.get(Number(match[1]));
+        if (item === undefined || chosen.has(item.note))
+            continue;
+        if (tokens + item.tokens > budget.tokens)
+            continue;
+        added.push(item);
+        chosen.add(item.note);
+        tokens += item.tokens;
+    }
+    return [...picked, ...added];
+}

package/search.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Lexical search over notes (docs/journal.md#search, docs/memory.md).
+ *
+ * Lists show summaries and never bodies, so note search is a lookup of the
+ * notes whose title, summary or body holds the query as an exact substring:
+ * the trigram index answers three characters and more, which is what makes a
+ * Chinese substring findable, and a `LIKE` scan answers a one- or
+ * two-character query, which has no trigram of its own. Results come back in id
+ * order, so a page is byte-stable however it is paged.
+ */
+import type { DatabaseSync, SQLInputValue } from "node:sqlite";
+/** A query shorter than this cannot use the trigram index. */
+export declare const MIN_TRIGRAM_CHARS = 3;
+/** One condition over `notes n`, and the values it is bound to. */
+export interface SubstringClause {
+    sql: string;
+    params: readonly SQLInputValue[];
+}
+/** The notes holding the query, as a condition over `notes n`. */
+export declare function substringClause(query: string): SubstringClause;
+/** The ids of several notes that hold the query, by id. */
+export declare function holdingIds(db: DatabaseSync, query: string, ids: readonly number[]): number[];
+/** Escape a literal for `LIKE ... ESCAPE '\'`. */
+export declare function escapeLike(value: string): string;
+export declare function likePattern(query: string): string;
+/** Quote one phrase for an FTS5 `MATCH`, so outside text is never syntax. */
+export declare function quoteFts(value: string): string;

package/search.js

@@ -0,0 +1,50 @@
+/**
+ * Lexical search over notes (docs/journal.md#search, docs/memory.md).
+ *
+ * Lists show summaries and never bodies, so note search is a lookup of the
+ * notes whose title, summary or body holds the query as an exact substring:
+ * the trigram index answers three characters and more, which is what makes a
+ * Chinese substring findable, and a `LIKE` scan answers a one- or
+ * two-character query, which has no trigram of its own. Results come back in id
+ * order, so a page is byte-stable however it is paged.
+ */
+import { FTS_TABLE } from "./schema.js";
+/** A query shorter than this cannot use the trigram index. */
+export const MIN_TRIGRAM_CHARS = 3;
+/** The notes holding the query, as a condition over `notes n`. */
+export function substringClause(query) {
+    if (Array.from(query).length >= MIN_TRIGRAM_CHARS) {
+        return {
+            sql: `n.id IN (SELECT rowid FROM ${FTS_TABLE} WHERE ${FTS_TABLE} MATCH ?)`,
+            params: [quoteFts(query)],
+        };
+    }
+    const pattern = likePattern(query);
+    return {
+        sql: `(n.title LIKE ? ESCAPE '\\' OR n.summary LIKE ? ESCAPE '\\' OR n.body LIKE ? ESCAPE '\\')`,
+        params: [pattern, pattern, pattern],
+    };
+}
+/** The ids of several notes that hold the query, by id. */
+export function holdingIds(db, query, ids) {
+    if (ids.length === 0)
+        return [];
+    const clause = substringClause(query);
+    const rows = db
+        .prepare(`SELECT n.id AS id FROM notes n
+       WHERE ${clause.sql} AND n.id IN (${ids.map(() => "?").join(", ")})
+       ORDER BY n.id`)
+        .all(...clause.params, ...ids);
+    return rows.map((row) => Number(row.id));
+}
+/** Escape a literal for `LIKE ... ESCAPE '\'`. */
+export function escapeLike(value) {
+    return value.replace(/[\\%_]/g, (character) => `\\${character}`);
+}
+export function likePattern(query) {
+    return `%${escapeLike(query)}%`;
+}
+/** Quote one phrase for an FTS5 `MATCH`, so outside text is never syntax. */
+export function quoteFts(value) {
+    return `"${value.replace(/"/g, '""')}"`;
+}