@4fu/arbor-notes-sqlite 2026.1106.1 → 2026.1107.0

package/README.md

@@ -56,7 +56,9 @@ npm install @4fu/arbor-core @4fu/arbor-journal-sqlite @4fu/arbor-notes-sqlite \
 ```
 
 `@4fu/arbor-plugin-http` is optional; it is the example plugin below.
-`@4fu/arbor-segmenter-jieba` is an optional peer of the journal.
+`@4fu/arbor-segmenter-jieba` is an optional peer of the lexical package, and
+`@4fu/arbor-search-zvec` an optional peer of the journal: absent either one, the
+journal searches lexically and nothing else changes.
 
 ## A minimal host
 
@@ -120,6 +122,8 @@ window gets, and how a continuation keeps working in it, are in
 | [`@4fu/arbor-journal-sqlite`](packages/journal-sqlite) | the default `Journal` and `BlobStore` on SQLite |
 | [`@4fu/arbor-notes-sqlite`](packages/notes-sqlite) | the default `NoteStore` on SQLite, beside the journal |
 | [`@4fu/arbor-segmenter-jieba`](packages/segmenter-jieba) | the default `Segmenter`: jieba's dictionary segmentation for the word index, optional |
+| [`@4fu/arbor-lexical`](packages/lexical) | the lexical search the journal and notes share: word segmentation, the FTS5 helpers and the merge order |
+| [`@4fu/arbor-search-zvec`](packages/search-zvec) | the optional semantic channel: event text embedded and searched by meaning with zvec |
 | [`@4fu/arbor-workspace-dir`](packages/workspace-dir) | the fallback `Workspace`: one directory per window, with a continuation working in its predecessor's directory in place |
 | [`@4fu/arbor-workspace-ovnfs`](packages/workspace-ovnfs) | the default `Workspace` when ovnfs is installed: one shared folder, per-window copy-on-write checkouts the model opens and applies back |
 | [`@4fu/arbor-environment-dir`](packages/environment-dir) | the default `Environment`: one `/env` directory, a revision per item, validation and deltas |
@@ -171,6 +175,7 @@ tarball would contain ([docs/release.md](docs/release.md)).
 | `packages/errors` | the error shape every refusal uses: the rule and the next action |
 | `packages/journal-sqlite` | the default `Journal` and `BlobStore` on SQLite |
 | `packages/segmenter-jieba` | the default `Segmenter`: jieba's dictionary segmentation for the word index, optional |
+| `packages/lexical` | the lexical search the journal and notes share: word segmentation, the FTS5 helpers and the merge order |
 | `packages/notes-sqlite` | the default `NoteStore` on SQLite, beside the journal |
 | `packages/judge-jev` | the default `Judge`: Jev, TypeSafe AI's System One classifier, answering the dispatch decisions |
 | `packages/workspace-dir` | the default `Workspace`: one directory per window, with a continuation working in its predecessor's directory in place, and the lookup of another window's directory it contributes to the catalog |

package/index.d.ts

@@ -4,10 +4,12 @@
 export { SqliteNoteStore, SUMMARY_LIMIT, DEFAULT_BODY_LIMIT, MAX_BODY_LIMIT } from "./notes.ts";
 export { DEFAULT_MIN_INTERVAL_MS, DEFAULT_ACTIVE_BUDGET, DEFAULT_JUDGE_SHARE, DEFAULT_HALF_LIFE_MS, deriveSummary, } from "./notes.ts";
 export type { SqliteNoteStoreOptions } from "./notes.ts";
-export { SCHEMA_VERSION, FTS_TABLE, createSchema } from "./schema.ts";
+export { SCHEMA_VERSION, FTS_TABLE, WORD_TABLE, createSchema } from "./schema.ts";
 export { noteIdOf, noteRefOf, parseNoteId, parseNoteRef, noteRefForms, storedWindowRef, storedEventRef, } from "./refs.ts";
+export { fallbackSegmenter, resolveSegmenter, indexText } from "@4fu/arbor-lexical";
 export { USE_WEIGHTS, MAX_CREDIT_HOPS, decay, estimateTokens, linkedCredit, loadCredit, loadEdges, pickByBudget, applyJudgeShare, scoreNotes, } from "./score.ts";
 export type { ScoredNote } from "./score.ts";
 export { MIN_TRIGRAM_CHARS, substringClause, holdingIds, escapeLike, likePattern, quoteFts, } from "./search.ts";
 export type { SubstringClause } from "./search.ts";
 export { bodyDiff } from "./diff.ts";
+export { resolveSemanticIndex } from "./semantic.ts";

package/index.js

@@ -3,8 +3,10 @@
  */
 export { SqliteNoteStore, SUMMARY_LIMIT, DEFAULT_BODY_LIMIT, MAX_BODY_LIMIT } from "./notes.js";
 export { DEFAULT_MIN_INTERVAL_MS, DEFAULT_ACTIVE_BUDGET, DEFAULT_JUDGE_SHARE, DEFAULT_HALF_LIFE_MS, deriveSummary, } from "./notes.js";
-export { SCHEMA_VERSION, FTS_TABLE, createSchema } from "./schema.js";
+export { SCHEMA_VERSION, FTS_TABLE, WORD_TABLE, createSchema } from "./schema.js";
 export { noteIdOf, noteRefOf, parseNoteId, parseNoteRef, noteRefForms, storedWindowRef, storedEventRef, } from "./refs.js";
+export { fallbackSegmenter, resolveSegmenter, indexText } from "@4fu/arbor-lexical";
 export { USE_WEIGHTS, MAX_CREDIT_HOPS, decay, estimateTokens, linkedCredit, loadCredit, loadEdges, pickByBudget, applyJudgeShare, scoreNotes, } from "./score.js";
 export { MIN_TRIGRAM_CHARS, substringClause, holdingIds, escapeLike, likePattern, quoteFts, } from "./search.js";
 export { bodyDiff } from "./diff.js";
+export { resolveSemanticIndex } from "./semantic.js";

package/notes.d.ts

@@ -15,7 +15,11 @@
  *   count and token budget, and frozen with the epoch's version, so every
  *   window opened in one epoch has the same prefix and later windows see the
  *   changes as a delta;
- * - every write recorded in the journal as a `note_revision` event.
+ * - every write recorded in the journal as a `note_revision` event;
+ * - lexical search: a word index with BM25, a trigram index for exact
+ *   substrings, and a `LIKE` scan for one- and two-character queries, merged
+ *   with exact substring hits first - and a semantic channel, note text embedded
+ *   and searched by meaning, when `@4fu/arbor-search-zvec` is installed.
  *
  * It is synchronous inside: one `DatabaseSync`, one transaction per write, so
  * the revision a write checks and the revision it writes are one atomic step.
@@ -23,7 +27,7 @@
  * database and the journal. The interface is asynchronous because a `NoteStore`
  * may live behind a process boundary.
  */
-import type { ActiveCandidate, ActiveSetBudget, Journal, Note, NoteBody, NoteContext, NoteDelta, NoteQuery, NoteRef, NoteRevision, NoteSummary, NoteUseInput, NoteWriteInput, NotesSnapshot, NoteStore, Page, SnapshotOptions } from "@4fu/arbor-interfaces";
+import type { ActiveCandidate, ActiveSetBudget, Journal, Note, NoteBody, NoteContext, NoteDelta, NoteQuery, NoteRef, NoteRevision, NoteSummary, NoteUseInput, NoteWriteInput, NotesSnapshot, NoteStore, Page, Segmenter, SemanticIndex, SnapshotOptions } from "@4fu/arbor-interfaces";
 /** A summary is at most this many characters (docs/memory.md). */
 export declare const SUMMARY_LIMIT = 200;
 /** How many characters of a body one read returns. */
@@ -46,6 +50,16 @@ export interface SqliteNoteStoreOptions {
     now?: () => number;
     /** Usage loses half of its weight this often. 24 hours. */
     usageHalfLifeMs?: number;
+    /** Word segmentation for the word index. Defaults to jieba, or the approximation. */
+    segmenter?: Segmenter;
+    /**
+     * The semantic channel: note text embedded and searched by meaning
+     * (docs/memory.md#search). Omitted, the zvec channel is used when
+     * `@4fu/arbor-search-zvec` is installed and its store opens, and there is no
+     * channel otherwise. `null` forces lexical search even when the package is
+     * installed.
+     */
+    semantic?: SemanticIndex | null;
     /**
      * One fixed string from the deployment's text table, so this implementation
      * writes none of its own (docs/prompting.md#language-and-the-text-table).
@@ -60,11 +74,17 @@ export declare class SqliteNoteStore implements NoteStore {
     private readonly db;
     private readonly journal;
     private readonly clock;
+    private readonly segmenter;
     private readonly halfLifeMs;
+    private readonly semantic;
+    /** The temporary directory an in-memory store's vector collection lives in. */
+    private readonly ownedVectorDirectory;
     /** The table every refusal this store raises is written from. */
     private readonly text;
     /** One write at a time: a write spans the notes database and the journal. */
     private writeQueue;
+    private semanticReady;
+    private semanticCaughtUp;
     private closed;
     constructor(options: SqliteNoteStoreOptions);
     write(input: NoteWriteInput): Promise<Note>;
@@ -100,7 +120,44 @@ export declare class SqliteNoteStore implements NoteStore {
     }): Promise<Page<ActiveCandidate>>;
     recordUse(input: NoteUseInput): Promise<void>;
     close(): Promise<void>;
+    /**
+     * Index the notes the semantic channel does not hold yet, and say how many.
+     *
+     * A restart over an existing database, a channel that was not ready when the
+     * notes were written, and a write whose indexing failed all leave notes to
+     * catch up on. A channel that is not ready yet holds what it was given and
+     * indexes that itself, so this answers 0 until it is.
+     */
+    catchUpSemantic(): Promise<number>;
     private ensureOpen;
+    /**
+     * Hand one note's text to the semantic channel, when there is one.
+     *
+     * The note is embedded as one text: its title, its summary and its body, in
+     * the order the lexical index weights them. The vector channel holds one
+     * vector per note and cannot weight a note's parts against each other the way
+     * BM25 weights the three columns, so the title - the note's name - leads the
+     * text and the body follows it, and a query that means either reaches the
+     * note (docs/memory.md#search).
+     */
+    private addToSemantic;
+    /** Take one note's text back out of the semantic channel, as a delete does. */
+    private removeFromSemantic;
+    /**
+     * The semantic channel's candidates, as ranks in the order it gave them.
+     *
+     * An absent channel, one that is not ready yet, and one that refuses all
+     * answer with nothing, and the search is exactly the lexical one. The note
+     * read's own filters decide which candidates count, so a channel that filters
+     * less than the store does still answers the read it was asked for.
+     */
+    private semanticRanks;
+    /**
+     * The notes among `ids` the read's own filters allow, in the order given. A
+     * deleted note is not among them, so a vector that outlived its note never
+     * reaches a page.
+     */
+    private allowedNoteIds;
     private noteRow;
     private revisionRow;
     private latestRevisionRow;
@@ -108,6 +165,8 @@ export declare class SqliteNoteStore implements NoteStore {
     /** The current summary and revision of several notes, in one read. */
     private noteStatesFor;
     private summaryPageBySql;
+    /** One page of an ordered id list, in the order the list gives. */
+    private summaryPage;
     private summaryPageByIds;
     /**
      * The notes about a target, or linked to a ref: the notes the events on that

package/notes.js

@@ -15,7 +15,11 @@
  *   count and token budget, and frozen with the epoch's version, so every
  *   window opened in one epoch has the same prefix and later windows see the
  *   changes as a delta;
- * - every write recorded in the journal as a `note_revision` event.
+ * - every write recorded in the journal as a `note_revision` event;
+ * - lexical search: a word index with BM25, a trigram index for exact
+ *   substrings, and a `LIKE` scan for one- and two-character queries, merged
+ *   with exact substring hits first - and a semantic channel, note text embedded
+ *   and searched by meaning, when `@4fu/arbor-search-zvec` is installed.
  *
  * It is synchronous inside: one `DatabaseSync`, one transaction per write, so
  * the revision a write checks and the revision it writes are one atomic step.
@@ -24,13 +28,19 @@
  * may live behind a process boundary.
  */
 import { DatabaseSync } from "node:sqlite";
+import { randomUUID } from "node:crypto";
+import { rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { arborError, isArborError } from "@4fu/arbor-errors";
 import { DEFAULT_PAGE_LIMIT, MAX_PAGE_LIMIT } from "@4fu/arbor-interfaces";
+import { indexText, resolveSegmenter } from "@4fu/arbor-lexical";
 import { bodyDiff } from "./diff.js";
 import { noteIdOf, noteRefOf, noteRefForms, parseNoteId, parseNoteRef, storedEventRef, storedWindowRef, } from "./refs.js";
-import { FTS_TABLE, createSchema } from "./schema.js";
+import { FTS_TABLE, WORD_TABLE, createSchema } from "./schema.js";
 import { USE_WEIGHTS, applyJudgeShare, pickByBudget, scoreNotes } from "./score.js";
-import { holdingIds, substringClause } from "./search.js";
+import { holdingIds, matchedIds } from "./search.js";
+import { resolveSemanticIndex } from "./semantic.js";
 import { textOf, zhTextTable } from "@4fu/arbor-prompt";
 /** A summary is at most this many characters (docs/memory.md). */
 export const SUMMARY_LIMIT = 200;
@@ -47,6 +57,13 @@ export const DEFAULT_JUDGE_SHARE = 0.15;
 export const DEFAULT_HALF_LIFE_MS = 86_400_000;
 /** How many events one `about` lookup reads. */
 const ABOUT_EVENT_LIMIT = 200;
+/**
+ * The fewest candidates the semantic channel is asked for. A page of one still
+ * fuses the channels over a handful of candidates, so a hit the word index
+ * ranked first is not lost to a semantic hit the channel would have ranked
+ * second.
+ */
+const MIN_SEMANTIC_CANDIDATES = 10;
 function toNumber(value) {
     if (typeof value === "number")
         return value;
@@ -164,20 +181,38 @@ export class SqliteNoteStore {
     db;
     journal;
     clock;
+    segmenter;
     halfLifeMs;
+    semantic;
+    /** The temporary directory an in-memory store's vector collection lives in. */
+    ownedVectorDirectory;
     /** The table every refusal this store raises is written from. */
     text;
     /** One write at a time: a write spans the notes database and the journal. */
     writeQueue = Promise.resolve();
+    semanticReady = false;
+    semanticCaughtUp = false;
     closed = false;
     constructor(options) {
         this.path = options.path ?? ":memory:";
         this.db = new DatabaseSync(this.path);
-        createSchema(this.db);
+        this.segmenter = options.segmenter ?? resolveSegmenter();
+        // The segmenter is resolved first: a version-1 database migrates by
+        // segmenting the notes it already holds into the word index.
+        createSchema(this.db, this.segmenter);
         this.journal = options.journal;
         this.clock = options.now ?? (() => Date.now());
         this.halfLifeMs = options.usageHalfLifeMs ?? DEFAULT_HALF_LIFE_MS;
         this.text = options.text ?? ((key, args) => textOf(zhTextTable, key, args));
+        // An in-memory store has no directory of its own; give it a temporary one
+        // and take it away on close. The semantic channel's store lives under it,
+        // beside where the notes database would be.
+        const root = this.path === ":memory:" ? join(tmpdir(), `arbor-notes-${randomUUID()}`) : null;
+        this.semantic =
+            options.semantic === undefined
+                ? resolveSemanticIndex(root === null ? `${this.path}.vectors` : join(root, "vectors"))
+                : options.semantic;
+        this.ownedVectorDirectory = root;
     }
     // --- writes -------------------------------------------------------------
     async write(input) {
@@ -233,6 +268,17 @@ export class SqliteNoteStore {
                 .run(event.ref, written.id, written.revision);
             this.db.prepare("UPDATE notes SET event = ? WHERE id = ?").run(event.ref, written.id);
         });
+        // The semantic channel is asynchronous, so the note is indexed once its
+        // revision is committed: a write never waits on a model, and a channel that
+        // is not ready yet holds the text until it is. With no channel there is
+        // nothing to wait for, and the write takes the path it always did. A delete
+        // takes the note's vector back out, as a redaction does in the journal.
+        if (this.semantic !== null) {
+            if (written.deleted)
+                await this.removeFromSemantic(written.id);
+            else
+                await this.addToSemantic(written.id, written.title, written.summary, written.body);
+        }
         return toNote(this.noteRow(written.id));
     }
     /** The rules a write has to meet before it touches the one copy. */
@@ -375,12 +421,16 @@ export class SqliteNoteStore {
             .prepare(`INSERT INTO note_revisions (note, revision, title, summary, body, deleted, time, window, event, anchor, refs)
          VALUES (?, ?, ?, ?, ?, ?, ?, ?, NULL, ?, ?)`)
             .run(id, revision, input.title, summary, body, deleted ? 1 : 0, time, window, anchorJson, refs);
-        // The search index holds the current state; a deleted note is not found.
+        // The search indexes hold the current state; a deleted note is not found.
         this.db.prepare(`DELETE FROM ${FTS_TABLE} WHERE rowid = ?`).run(id);
+        this.db.prepare(`DELETE FROM ${WORD_TABLE} WHERE rowid = ?`).run(id);
         if (!deleted) {
             this.db
                 .prepare(`INSERT INTO ${FTS_TABLE} (rowid, title, summary, body) VALUES (?, ?, ?, ?)`)
                 .run(id, input.title, summary, body);
+            this.db
+                .prepare(`INSERT INTO ${WORD_TABLE} (rowid, title, summary, body) VALUES (?, ?, ?, ?)`)
+                .run(id, indexText(input.title, this.segmenter), indexText(summary, this.segmenter), indexText(body, this.segmenter));
         }
         // The refs the revision names: what it cites and what it holds as
         // evidence. The evidence ones between notes are what the credit walk
@@ -403,6 +453,8 @@ export class SqliteNoteStore {
             time,
             title: input.title,
             summary,
+            body,
+            deleted,
             window,
             anchor,
         };
@@ -417,6 +469,7 @@ export class SqliteNoteStore {
                 .prepare("DELETE FROM note_refs WHERE note = ? AND revision = ?")
                 .run(written.id, written.revision);
             this.db.prepare(`DELETE FROM ${FTS_TABLE} WHERE rowid = ?`).run(written.id);
+            this.db.prepare(`DELETE FROM ${WORD_TABLE} WHERE rowid = ?`).run(written.id);
             if (written.created) {
                 this.db.prepare("DELETE FROM notes WHERE id = ?").run(written.id);
                 return;
@@ -431,6 +484,9 @@ export class SqliteNoteStore {
                 this.db
                     .prepare(`INSERT INTO ${FTS_TABLE} (rowid, title, summary, body) VALUES (?, ?, ?, ?)`)
                     .run(written.id, previous.title, previous.summary, previous.body);
+                this.db
+                    .prepare(`INSERT INTO ${WORD_TABLE} (rowid, title, summary, body) VALUES (?, ?, ?, ?)`)
+                    .run(written.id, indexText(previous.title, this.segmenter), indexText(previous.summary, this.segmenter), indexText(previous.body, this.segmenter));
             }
         });
     }
@@ -511,16 +567,25 @@ export class SqliteNoteStore {
         const offset = Math.max(0, Math.floor(query.offset ?? 0));
         const text = (query.query ?? "").trim();
         // `about` and `linked` bound the result to the notes the journal resolved,
-        // in weight order; a text match narrows that set.
+        // in weight order; a text match narrows that set. The semantic channel does
+        // not widen a bound the journal resolved, so it is not asked at all here.
         if (query.about !== undefined || query.linked !== undefined) {
             const ordered = await this.linkedNoteIds(query.about, query.linked);
-            const holding = text === "" ? null : new Set(holdingIds(this.db, text, ordered));
+            const holding = text === "" ? null : new Set(holdingIds(this.db, text, ordered, this.segmenter));
             const chosen = holding === null ? ordered : ordered.filter((id) => holding.has(id));
             const page = this.summaryPageByIds(chosen, query, limit, offset);
             return { ...page, nextCall: searchCall(query, offset, limit) };
         }
-        const match = text === "" ? null : substringClause(text);
-        const page = this.summaryPageBySql(query, limit, offset, match);
+        // No query lists every note by id; a query is answered by the lexical
+        // channels and the semantic one, merged: exact substring hits first, then
+        // word hits, then the hits only the semantic channel found.
+        const semantic = text === "" ? [] : await this.semanticRanks(text, limit, query.status);
+        const matched = text === ""
+            ? null
+            : matchedIds(this.db, text, this.segmenter, query.status, semantic);
+        const page = matched === null
+            ? this.summaryPageBySql(query, limit, offset)
+            : this.summaryPage(matched, limit, offset);
         return { ...page, nextCall: searchCall(query, offset, limit) };
     }
     async active() {
@@ -686,6 +751,39 @@ export class SqliteNoteStore {
         this.closed = true;
         await this.writeQueue;
         this.db.close();
+        // The channel's own store is closed with the notes database, and the
+        // temporary directory an in-memory store gave it goes with it.
+        if (this.semantic !== null)
+            await this.semantic.close();
+        if (this.ownedVectorDirectory !== null) {
+            await rm(this.ownedVectorDirectory, { recursive: true, force: true });
+        }
+    }
+    /**
+     * Index the notes the semantic channel does not hold yet, and say how many.
+     *
+     * A restart over an existing database, a channel that was not ready when the
+     * notes were written, and a write whose indexing failed all leave notes to
+     * catch up on. A channel that is not ready yet holds what it was given and
+     * indexes that itself, so this answers 0 until it is.
+     */
+    async catchUpSemantic() {
+        this.ensureOpen();
+        if (this.semantic === null || !(await this.semantic.ready()))
+            return 0;
+        const held = await this.semantic.held();
+        const rows = this.db
+            .prepare(`SELECT id, title, summary, body FROM notes WHERE status <> 'deleted' ORDER BY id`)
+            .all();
+        let indexed = 0;
+        for (const row of rows) {
+            const id = toNumber(row.id);
+            if (held.has(noteIdOf(id)))
+                continue;
+            await this.addToSemantic(id, row.title, row.summary, row.body);
+            indexed += 1;
+        }
+        return indexed;
     }
     // --- internals ---------------------------------------------------------
     ensureOpen() {
@@ -698,6 +796,104 @@ export class SqliteNoteStore {
             });
         }
     }
+    /**
+     * Hand one note's text to the semantic channel, when there is one.
+     *
+     * The note is embedded as one text: its title, its summary and its body, in
+     * the order the lexical index weights them. The vector channel holds one
+     * vector per note and cannot weight a note's parts against each other the way
+     * BM25 weights the three columns, so the title - the note's name - leads the
+     * text and the body follows it, and a query that means either reaches the
+     * note (docs/memory.md#search).
+     */
+    async addToSemantic(id, title, summary, body) {
+        if (this.semantic === null)
+            return;
+        try {
+            await this.semantic.add(noteIdOf(id), [title, summary, body].join("\n"));
+        }
+        catch {
+            // An optional channel that refuses leaves the note searchable lexically;
+            // a catch-up indexes it once the channel answers again.
+        }
+    }
+    /** Take one note's text back out of the semantic channel, as a delete does. */
+    async removeFromSemantic(id) {
+        if (this.semantic === null)
+            return;
+        try {
+            await this.semantic.remove(noteIdOf(id));
+        }
+        catch {
+            // As with a write: the channel is optional, and the note is gone from
+            // every index the store owns.
+        }
+    }
+    /**
+     * The semantic channel's candidates, as ranks in the order it gave them.
+     *
+     * An absent channel, one that is not ready yet, and one that refuses all
+     * answer with nothing, and the search is exactly the lexical one. The note
+     * read's own filters decide which candidates count, so a channel that filters
+     * less than the store does still answers the read it was asked for.
+     */
+    async semanticRanks(query, limit, status) {
+        if (this.semantic === null)
+            return [];
+        const ready = await this.semantic.ready();
+        if (ready !== this.semanticReady) {
+            // The channel just became usable, or stopped being: index what it missed
+            // while it was not.
+            this.semanticReady = ready;
+            this.semanticCaughtUp = false;
+        }
+        if (!this.semanticCaughtUp) {
+            this.semanticCaughtUp = true;
+            await this.catchUpSemantic();
+        }
+        if (!ready)
+            return [];
+        // The filters a note read applies are the store's own, and none of them is
+        // a field of the channel: a note's status changes at every snapshot epoch
+        // without a revision, and `about` and `linked` are bounds the journal
+        // resolved. So the channel is asked for the notes nearest the query and
+        // nothing else, and the store applies its own filters to what comes back -
+        // exactly as the journal does with the targets it filters on itself
+        // (docs/memory.md#search).
+        const asked = {};
+        const refs = await this.semantic.search(query, Math.max(limit, MIN_SEMANTIC_CANDIDATES), asked);
+        const ids = [];
+        for (const ref of refs) {
+            const id = parseNoteId(ref);
+            if (id !== null)
+                ids.push(id);
+        }
+        const allowed = this.allowedNoteIds(ids, status);
+        // The channel's order, as ranks the shared merge reads: the nearest hit
+        // carries the most negative rank, so it normalizes to the best score.
+        return allowed.map((id, index) => ({ rowid: id, rank: index - allowed.length }));
+    }
+    /**
+     * The notes among `ids` the read's own filters allow, in the order given. A
+     * deleted note is not among them, so a vector that outlived its note never
+     * reaches a page.
+     */
+    allowedNoteIds(ids, status) {
+        if (ids.length === 0)
+            return [];
+        const clauses = ["status <> 'deleted'"];
+        const params = [...ids];
+        if (status !== undefined) {
+            clauses.push("status = ?");
+            params.push(status);
+        }
+        const rows = this.db
+            .prepare(`SELECT id FROM notes
+         WHERE id IN (${ids.map(() => "?").join(", ")}) AND ${clauses.join(" AND ")}`)
+            .all(...params);
+        const allowed = new Set(rows.map((row) => toNumber(row.id)));
+        return ids.filter((id) => allowed.has(id));
+    }
     noteRow(id) {
         const row = this.db
             .prepare(`SELECT id, created, updated, revision, title, summary, body, status, window, anchor, event
@@ -737,13 +933,11 @@ export class SqliteNoteStore {
         }
         return states;
     }
-    summaryPageBySql(query, limit, offset, match) {
-        const clauses = [];
+    summaryPageBySql(query, limit, offset) {
+        // A delete leaves the row and marks it, and this reads the notes table
+        // itself, so it leaves the deleted ones out on its own (docs/memory.md).
+        const clauses = ["n.status <> 'deleted'"];
         const params = [];
-        if (match !== null) {
-            clauses.push(match.sql);
-            params.push(...match.params);
-        }
         if (query.status !== undefined) {
             clauses.push("n.status = ?");
             params.push(query.status);
@@ -759,10 +953,28 @@ export class SqliteNoteStore {
             .get(...params).n);
         return { items: rows.map(toSummary), total, limit };
     }
+    /** One page of an ordered id list, in the order the list gives. */
+    summaryPage(ordered, limit, offset) {
+        const page = ordered.slice(offset, offset + limit);
+        if (page.length === 0)
+            return { items: [], total: ordered.length, limit };
+        const rows = this.db
+            .prepare(`SELECT id, revision, title, summary, status, updated FROM notes
+         WHERE id IN (${page.map(() => "?").join(", ")})`)
+            .all(...page);
+        const byId = new Map(rows.map((row) => [toNumber(row.id), row]));
+        const items = page
+            .map((id) => byId.get(id))
+            .filter((row) => row !== undefined)
+            .map(toSummary);
+        return { items, total: ordered.length, limit };
+    }
     summaryPageByIds(ordered, query, limit, offset) {
         if (ordered.length === 0)
             return { items: [], total: 0, limit };
-        const clauses = [`id IN (${ordered.map(() => "?").join(", ")})`];
+        // A delete leaves the row and marks it, and no search returns the note
+        // again, whichever lookup ordered it (docs/memory.md).
+        const clauses = [`status <> 'deleted'`, `id IN (${ordered.map(() => "?").join(", ")})`];
         const params = [...ordered];
         if (query.status !== undefined) {
             clauses.push("status = ?");

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@4fu/arbor-notes-sqlite",
-  "version": "2026.1106.1",
+  "version": "2026.1107.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.",
+  "description": "The default NoteStore: one copy of every note, checked writes, revisions, anchors, the active set and search on SQLite beside the journal: lexical, and semantic when the optional channel is installed.",
   "exports": {
     ".": {
       "types": "./index.d.ts",
@@ -25,7 +25,9 @@
     "score.d.ts",
     "score.js",
     "search.d.ts",
-    "search.js"
+    "search.js",
+    "semantic.d.ts",
+    "semantic.js"
   ],
   "engines": {
     "node": ">=24"
@@ -40,8 +42,17 @@
     "access": "public"
   },
   "dependencies": {
-    "@4fu/arbor-errors": "2026.1106.1",
-    "@4fu/arbor-interfaces": "2026.1106.1",
-    "@4fu/arbor-prompt": "2026.1106.1"
+    "@4fu/arbor-errors": "2026.1107.0",
+    "@4fu/arbor-interfaces": "2026.1107.0",
+    "@4fu/arbor-lexical": "2026.1107.0",
+    "@4fu/arbor-prompt": "2026.1107.0"
+  },
+  "peerDependencies": {
+    "@4fu/arbor-search-zvec": "2026.1107.0"
+  },
+  "peerDependenciesMeta": {
+    "@4fu/arbor-search-zvec": {
+      "optional": true
+    }
   }
 }

package/schema.d.ts

@@ -23,12 +23,17 @@
  *   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.
+ * - `notes_words` - word index for BM25 over the same three columns, segmented
+ *   (docs/journal.md#search).
  */
 import type { DatabaseSync } from "node:sqlite";
+import type { Segmenter } from "@4fu/arbor-interfaces";
 /** Bumped when a change makes an existing database unusable. */
-export declare const SCHEMA_VERSION = 1;
+export declare const SCHEMA_VERSION = 2;
 /** 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;
+/** The word index note search reads. */
+export declare const WORD_TABLE = "notes_words";
+/** Create the schema when it is missing, migrate an older one, and record the version. */
+export declare function createSchema(db: DatabaseSync, segmenter?: Segmenter): void;
 export declare function readMeta(db: DatabaseSync, key: string): string | null;

package/schema.js

@@ -23,11 +23,25 @@
  *   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.
+ * - `notes_words` - word index for BM25 over the same three columns, segmented
+ *   (docs/journal.md#search).
  */
+import { indexText, resolveSegmenter } from "@4fu/arbor-lexical";
 /** Bumped when a change makes an existing database unusable. */
-export const SCHEMA_VERSION = 1;
+export const SCHEMA_VERSION = 2;
 /** The FTS5 table note search reads. */
 export const FTS_TABLE = "notes_fts";
+/** The word index note search reads. */
+export const WORD_TABLE = "notes_words";
+/** The trigram index: exact substrings, for Chinese and mixed text. */
+const TRIGRAM_INDEX = `CREATE VIRTUAL TABLE IF NOT EXISTS ${FTS_TABLE}
+   USING fts5(title, summary, body, tokenize = 'trigram')`;
+/**
+ * The word index: one column per searched field, each holding that field's
+ * segments, one per line. The columns are what the BM25 weights rank by.
+ */
+const WORD_INDEX = `CREATE VIRTUAL TABLE IF NOT EXISTS ${WORD_TABLE}
+   USING fts5(title, summary, body, tokenize = 'unicode61')`;
 const STATEMENTS = [
     `PRAGMA journal_mode = WAL`,
     `PRAGMA foreign_keys = ON`,
@@ -114,25 +128,61 @@ const STATEMENTS = [
      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')`,
+    TRIGRAM_INDEX,
+    WORD_INDEX,
 ];
-/** Create the schema when it is missing, and check the version when it is not. */
-export function createSchema(db) {
+/**
+ * Version 2 added the word index (docs/journal.md#search): a segmented word
+ * index with BM25 beside the trigram index, which is what lets a multi-word
+ * query find a note that holds the words apart from each other. Every note,
+ * every ref and the trigram index stay, so a version-1 database opens where it
+ * left off: the notes it already holds are segmented into the new index in the
+ * same step that records the version, and a delete leaves a note out of it.
+ */
+function migrateToVersion2(db, segmenter) {
+    // One transaction: the index and the version that says it is there land
+    // together, so a database that stops half way through is still the version it
+    // was and migrates again, whole, instead of half-indexing twice.
+    db.exec("BEGIN IMMEDIATE");
+    try {
+        db.exec(WORD_INDEX);
+        const insert = db.prepare(`INSERT INTO ${WORD_TABLE} (rowid, title, summary, body) VALUES (?, ?, ?, ?)`);
+        const rows = db
+            .prepare("SELECT id, title, summary, body FROM notes WHERE status <> 'deleted'")
+            .all();
+        for (const row of rows) {
+            insert.run(Number(row.id), indexText(row.title, segmenter), indexText(row.summary, segmenter), indexText(row.body, segmenter));
+        }
+        db.prepare("INSERT OR REPLACE INTO meta (key, value) VALUES ('schema_version', ?)").run(String(SCHEMA_VERSION));
+        db.exec("COMMIT");
+    }
+    catch (error) {
+        try {
+            db.exec("ROLLBACK");
+        }
+        catch {
+            // The transaction is already gone; the original error is what matters.
+        }
+        throw error;
+    }
+}
+/** Create the schema when it is missing, migrate an older one, and record the version. */
+export function createSchema(db, segmenter = resolveSegmenter()) {
     // 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`);
+    if (version !== null && Number(version) > SCHEMA_VERSION) {
+        throw new Error(`notes schema ${version} is newer than this build (${SCHEMA_VERSION}); upgrade arbor, or migrate the database`);
     }
+    if (Number(version) === SCHEMA_VERSION - 1)
+        migrateToVersion2(db, segmenter);
     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));
+    if (version === null || Number(version) !== SCHEMA_VERSION) {
+        db.prepare("INSERT OR REPLACE INTO meta (key, value) VALUES ('schema_version', ?)").run(String(SCHEMA_VERSION));
     }
 }
 export function readMeta(db, key) {

package/search.d.ts

@@ -1,27 +1,60 @@
 /**
  * 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.
+ * The channels the journal has, merged the same way, and one more when a
+ * deployment installed it:
+ *
+ * - a word index, segmented and ranked with BM25 over title, summary and body,
+ *   the title and the summary weighted above the body;
+ * - a trigram index for exact substrings, which is what makes a Chinese
+ *   substring findable;
+ * - a `LIKE` scan, for one- and two-character queries, which have no trigram of
+ *   their own;
+ * - a semantic channel, note text embedded and searched by meaning, when
+ *   `@4fu/arbor-search-zvec` is installed.
+ *
+ * Exact substring hits come first, then word hits that are not already there,
+ * then the hits only the semantic channel found, each channel by its own
+ * relevance. The `LIKE` scan has no relevance of its own, so it answers in id
+ * order and 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;
+import type { NoteStatus, Segmenter } from "@4fu/arbor-interfaces";
+import { MIN_TRIGRAM_CHARS, escapeLike, likePattern, quoteFts } from "@4fu/arbor-lexical";
+import type { Ranked } from "@4fu/arbor-lexical";
+export { MIN_TRIGRAM_CHARS, escapeLike, likePattern, quoteFts };
+/**
+ * The BM25 column weights both note indexes are ranked with, in the order the
+ * FTS5 tables carry their columns: title, summary, body. The title names the
+ * note and the summary is its one line, so a hit in either counts for more
+ * than one in the body: ten times as much for the title, four times for the
+ * summary.
+ */
+export declare const COLUMN_WEIGHTS = "10.0, 4.0, 1.0";
 /** 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`. */
+/** The notes holding the query as an exact substring, 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;
+/**
+ * The notes a text query matches, in the order search returns them: exact
+ * substring hits first, then word hits that are not already there, each channel
+ * by its own relevance, then the hits only the semantic channel found. A
+ * one- or two-character query has no trigram and no word match of its own, so
+ * the fallback scan answers it in id order, and the semantic channel's hits
+ * follow it.
+ *
+ * `semantic` is the channel's own candidates as ranks, in the order it gave
+ * them: the note store asks it for the notes nearest the query and applies its
+ * own filters to what comes back, so a channel that filters less than the store
+ * does still answers the read it was asked (docs/memory.md#search).
+ */
+export declare function matchedIds(db: DatabaseSync, query: string, segmenter: Segmenter, status?: NoteStatus, semantic?: readonly Ranked[]): number[];
+/**
+ * The ids of several notes that hold the query: an exact substring or the
+ * query's words. `about` and `linked` bound a lookup to the notes the journal
+ * resolved, in their own weight order, so this answers a set and not an order.
+ */
+export declare function holdingIds(db: DatabaseSync, query: string, ids: readonly number[], segmenter: Segmenter): number[];

package/search.js

@@ -1,50 +1,127 @@
 /**
  * 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.
+ * The channels the journal has, merged the same way, and one more when a
+ * deployment installed it:
+ *
+ * - a word index, segmented and ranked with BM25 over title, summary and body,
+ *   the title and the summary weighted above the body;
+ * - a trigram index for exact substrings, which is what makes a Chinese
+ *   substring findable;
+ * - a `LIKE` scan, for one- and two-character queries, which have no trigram of
+ *   their own;
+ * - a semantic channel, note text embedded and searched by meaning, when
+ *   `@4fu/arbor-search-zvec` is installed.
+ *
+ * Exact substring hits come first, then word hits that are not already there,
+ * then the hits only the semantic channel found, each channel by its own
+ * relevance. The `LIKE` scan has no relevance of its own, so it answers in id
+ * order and 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`. */
+import { MIN_TRIGRAM_CHARS, escapeLike, likePattern, mergeHits, quoteFts, trigramMatch, wordMatch, } from "@4fu/arbor-lexical";
+import { FTS_TABLE, WORD_TABLE } from "./schema.js";
+export { MIN_TRIGRAM_CHARS, escapeLike, likePattern, quoteFts };
+/**
+ * The BM25 column weights both note indexes are ranked with, in the order the
+ * FTS5 tables carry their columns: title, summary, body. The title names the
+ * note and the summary is its one line, so a hit in either counts for more
+ * than one in the body: ten times as much for the title, four times for the
+ * summary.
+ */
+export const COLUMN_WEIGHTS = "10.0, 4.0, 1.0";
+/** The `LIKE` scan's condition, for a query the trigram index cannot answer. */
+function likeClause(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 word index's condition: every one of the query's segments. */
+function wordClause(tokens) {
+    return {
+        sql: `n.id IN (SELECT rowid FROM ${WORD_TABLE} WHERE ${WORD_TABLE} MATCH ?)`,
+        params: [wordMatch(tokens)],
+    };
+}
+/** The notes holding the query as an exact substring, 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)],
+            params: [trigramMatch(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],
-    };
+    return likeClause(query);
 }
-/** The ids of several notes that hold the query, by id. */
-export function holdingIds(db, query, ids) {
+/** Every match from one index, by relevance, with the status filter applied. */
+function ranked(db, table, match, status) {
+    const filtered = status === undefined ? "" : " AND n.status = ?";
+    const params = status === undefined ? [match] : [match, status];
+    const rows = db
+        .prepare(`SELECT f.rowid AS rowid, bm25(${table}, ${COLUMN_WEIGHTS}) AS rank
+       FROM ${table} f JOIN notes n ON n.id = f.rowid
+       WHERE ${table} MATCH ?${filtered}
+       ORDER BY rank, f.rowid`)
+        .all(...params);
+    return rows.map((row) => ({ rowid: Number(row.rowid), rank: Number(row.rank) }));
+}
+/** The notes a one- or two-character query holds, in id order. */
+function scanIds(db, query, status) {
+    const clause = likeClause(query);
+    // A delete leaves the row and marks it, and the scan reads the notes table
+    // itself, so it leaves the deleted ones out on its own (docs/memory.md).
+    const filtered = status === undefined ? " AND n.status <> 'deleted'" : " AND n.status = ?";
+    const rows = db
+        .prepare(`SELECT n.id AS id FROM notes n WHERE ${clause.sql}${filtered} ORDER BY n.id`)
+        .all(...clause.params, ...(status === undefined ? [] : [status]));
+    return rows.map((row) => Number(row.id));
+}
+/**
+ * The notes a text query matches, in the order search returns them: exact
+ * substring hits first, then word hits that are not already there, each channel
+ * by its own relevance, then the hits only the semantic channel found. A
+ * one- or two-character query has no trigram and no word match of its own, so
+ * the fallback scan answers it in id order, and the semantic channel's hits
+ * follow it.
+ *
+ * `semantic` is the channel's own candidates as ranks, in the order it gave
+ * them: the note store asks it for the notes nearest the query and applies its
+ * own filters to what comes back, so a channel that filters less than the store
+ * does still answers the read it was asked (docs/memory.md#search).
+ */
+export function matchedIds(db, query, segmenter, status, semantic = []) {
+    if (Array.from(query).length < MIN_TRIGRAM_CHARS) {
+        // A one- or two-character query has no trigram and no word match of its
+        // own: the scan answers it in id order, and the semantic channel's hits
+        // follow it.
+        const scanned = scanIds(db, query, status).map((rowid) => ({ rowid, rank: 0 }));
+        return mergeHits({ channel: "substring", hits: scanned }, { channel: "semantic", hits: semantic }).map((hit) => hit.rowid);
+    }
+    const substrings = ranked(db, FTS_TABLE, trigramMatch(query), status);
+    const match = wordMatch(segmenter.segment(query));
+    const words = match === "" ? [] : ranked(db, WORD_TABLE, match, status);
+    return mergeHits({ channel: "substring", hits: substrings }, { channel: "word", hits: words }, { channel: "semantic", hits: semantic }).map((hit) => hit.rowid);
+}
+/**
+ * The ids of several notes that hold the query: an exact substring or the
+ * query's words. `about` and `linked` bound a lookup to the notes the journal
+ * resolved, in their own weight order, so this answers a set and not an order.
+ */
+export function holdingIds(db, query, ids, segmenter) {
     if (ids.length === 0)
         return [];
-    const clause = substringClause(query);
+    const clauses = [substringClause(query)];
+    if (Array.from(query).length >= MIN_TRIGRAM_CHARS) {
+        const tokens = segmenter.segment(query);
+        if (wordMatch(tokens) !== "")
+            clauses.push(wordClause(tokens));
+    }
     const rows = db
         .prepare(`SELECT n.id AS id FROM notes n
-       WHERE ${clause.sql} AND n.id IN (${ids.map(() => "?").join(", ")})
+       WHERE (${clauses.map((clause) => clause.sql).join(" OR ")})
+         AND n.id IN (${ids.map(() => "?").join(", ")})
        ORDER BY n.id`)
-        .all(...clause.params, ...ids);
+        .all(...clauses.flatMap((clause) => 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, '""')}"`;
-}

package/semantic.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The semantic channel the note store uses when the caller names none
+ * (docs/memory.md#search).
+ *
+ * The spec calls for note text to be embedded and searched by meaning beside the
+ * lexical indexes, and the default is zvec when `@4fu/arbor-search-zvec` is
+ * installed: `resolveSemanticIndex` loads it, and the store uses what it returns
+ * when the caller names no channel. The package is an optional peer dependency,
+ * so a deployment that leaves it out keeps working.
+ *
+ * What is left here is the absence that answers when the package is not there:
+ * no channel, and search is exactly lexical. That is also the answer when the
+ * package is installed but its vector store will not open - zvec's prebuilt
+ * binary does not load on this platform, or another host holds the collection -
+ * and when no embedding model is available, because the package says so by
+ * handing back nothing.
+ */
+import type { SemanticIndex } from "@4fu/arbor-interfaces";
+/**
+ * The semantic channel a note store uses when the caller names none: the zvec
+ * one when the package is installed and its store opens, and none otherwise.
+ *
+ * `load` replaces how the zvec package is loaded. A host that resolves modules
+ * its own way passes its own; so does a test that has no zvec package to load. A
+ * load that fails falls back rather than stopping the store, because the package
+ * is optional: it may be missing, or its prebuilt binary may not load on this
+ * platform.
+ */
+export declare function resolveSemanticIndex(path: string, load?: (path: string) => SemanticIndex | null): SemanticIndex | null;

package/semantic.js

@@ -0,0 +1,57 @@
+/**
+ * The semantic channel the note store uses when the caller names none
+ * (docs/memory.md#search).
+ *
+ * The spec calls for note text to be embedded and searched by meaning beside the
+ * lexical indexes, and the default is zvec when `@4fu/arbor-search-zvec` is
+ * installed: `resolveSemanticIndex` loads it, and the store uses what it returns
+ * when the caller names no channel. The package is an optional peer dependency,
+ * so a deployment that leaves it out keeps working.
+ *
+ * What is left here is the absence that answers when the package is not there:
+ * no channel, and search is exactly lexical. That is also the answer when the
+ * package is installed but its vector store will not open - zvec's prebuilt
+ * binary does not load on this platform, or another host holds the collection -
+ * and when no embedding model is available, because the package says so by
+ * handing back nothing.
+ */
+import { createRequire } from "node:module";
+/** The package that holds the zvec semantic index, when a deployment installed it. */
+const ZVEC_PACKAGE = "@4fu/arbor-search-zvec";
+/**
+ * Load the zvec semantic index over a store beside the notes database's own, or
+ * `null` when it is not there: the package is not installed, or it holds no
+ * index.
+ */
+function loadZvec(path) {
+    const require = createRequire(import.meta.url);
+    const loaded = require(ZVEC_PACKAGE);
+    const create = loaded?.createZvecIndex;
+    if (typeof create !== "function")
+        return null;
+    const index = create({ path });
+    if (index === null || typeof index !== "object")
+        return null;
+    const shape = index;
+    if (typeof shape.add !== "function" || typeof shape.search !== "function")
+        return null;
+    return index;
+}
+/**
+ * The semantic channel a note store uses when the caller names none: the zvec
+ * one when the package is installed and its store opens, and none otherwise.
+ *
+ * `load` replaces how the zvec package is loaded. A host that resolves modules
+ * its own way passes its own; so does a test that has no zvec package to load. A
+ * load that fails falls back rather than stopping the store, because the package
+ * is optional: it may be missing, or its prebuilt binary may not load on this
+ * platform.
+ */
+export function resolveSemanticIndex(path, load = loadZvec) {
+    try {
+        return load(path);
+    }
+    catch {
+        return null;
+    }
+}