@dokebi/search 0.0.0-stage → 0.1.0

package/dist/plugin.js

@@ -0,0 +1,671 @@
+import { definePlugin, definePoint, providerDependency, } from '@dokebi/core';
+import { diagnostics } from '@dokebi/core/libraries';
+import { Cursors, queryFingerprint } from './cursor.js';
+import { SearchError } from './errors.js';
+import { indexesOf } from './indexes.js';
+import { DEFAULT_SECRETS_ENV, MIN_SECRET_LENGTH, options } from './options.js';
+import { detectDriver, isMissingTable, isQueryable, serverDialect, session, } from './sql.js';
+import { COUNTS_TABLE, INDEXES_TABLE, Store, TERMS_TABLE, } from './store.js';
+import { MAX_QUERY_WORDS, queryTerms, terms } from './terms.js';
+const db = providerDependency({
+    name: 'dokebi-db',
+    version: '^0.4.1',
+    packageName: '@dokebi/db',
+    load: () => import('@dokebi/db'),
+});
+/** The `core:describe` point (core 0.4.2), declared by name. */
+export const describePoint = definePoint('core:describe');
+/** How often a call tries to reach a database that was down (an optional connection, D-0127). */
+const RETRY_MS = 1000;
+const DEFAULT_LIMIT = 20;
+/** Rows of the leading word one statement reads (a request reads up to examineLimit). */
+const CHUNK = 500;
+const MAX_ID = 128;
+const MAX_SCOPE = 64;
+const MAX_SCOPES = 32;
+/** A field's text above this many characters is refused (the terms of 1 MB of text). */
+const MAX_TEXT = 1_000_000;
+const SEP = '\u0000';
+/** Buffered words that start a flush before its interval. */
+const FLUSH_WORDS = 2000;
+/** How often repeated flush failures are logged (D-0047). */
+const REPEAT_MS = 60_000;
+function optionalConnection(database, name) {
+    if (typeof database.status !== 'function')
+        return false;
+    return database.status(name).startup === 'optional';
+}
+/** A failure that waiting for the database does not cure (a missing table, a wrong server). */
+function permanent(error) {
+    const { plugin, code } = (error ?? {});
+    if (plugin === 'dokebi-search')
+        return code !== 'NOT_READY';
+    return plugin === 'dokebi-db' && (code === 'INVALID_OPTIONS' || code === 'INVALID_RESOURCE');
+}
+/** The signing secrets: the environment variable of secretsEnv wins over dokebi.yaml. */
+function signingSecrets(settings) {
+    const variable = settings.secretsEnv ?? DEFAULT_SECRETS_ENV;
+    const value = process.env[variable];
+    if (value?.trim()) {
+        const secrets = value.split(',').map((part) => part.trim());
+        if (secrets.length > 8 ||
+            new Set(secrets).size !== secrets.length ||
+            secrets.some((secret) => secret.length < MIN_SECRET_LENGTH || secret.length > 512))
+            throw new SearchError('INVALID_OPTIONS', `Search secrets in ${variable} are invalid: one to eight different secrets of ${MIN_SECRET_LENGTH} to 512 characters, separated by commas`, { data: { variable } });
+        return { secrets, from: 'environment', variable };
+    }
+    if (settings.secrets?.length)
+        return { secrets: settings.secrets, from: 'options', variable };
+    throw new SearchError('SECRET_MISSING', `Search cursor secret missing: options.dokebi-search.secrets in dokebi.yaml is empty and ${variable} is not set`, { data: { variable } });
+}
+function plain(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+const byKey = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+class SearchRuntime {
+    #options;
+    #indexes;
+    #context;
+    #database;
+    #resource;
+    #live;
+    #bringing;
+    #lastTry = 0;
+    #lastError;
+    #derived;
+    #cursors;
+    #stale = new Set();
+    /**
+     * Word count changes not yet in the table: `index\0field\0term` → delta. The counts only
+     * choose a search's leading word (a hint), so they are added after the writes, outside the
+     * caller's transaction: a common word's count is never a row every writer waits on (db AI.md
+     * 6.4), and MariaDB's snapshot isolation never refuses the caller's commit over it (errno 1020).
+     * A rolled-back write leaves its delta: the counts may drift, never the results.
+     */
+    #pending = new Map();
+    #flushing;
+    #repeats;
+    constructor(parsed, indexes) {
+        this.#options = parsed;
+        this.#indexes = indexes;
+    }
+    async setup(context) {
+        const started = performance.now();
+        const settings = this.#options;
+        if (settings.searchLimit < settings.examineLimit)
+            throw new SearchError('INVALID_OPTIONS', `searchLimit (${settings.searchLimit}) is below examineLimit (${settings.examineLimit})`, { data: { field: 'searchLimit' } });
+        const database = context.getDependency(db);
+        let resource;
+        try {
+            resource = database.resource(settings.connection);
+        }
+        catch (cause) {
+            throw new SearchError('UNKNOWN_CONNECTION', `The search connection ${settings.connection} is not a dokebi-db connection`, { cause, data: { connection: settings.connection } });
+        }
+        if (!isQueryable(resource))
+            throw new SearchError('UNSUPPORTED_RESOURCE', `Connection ${settings.connection} is not a pg, mysql2/promise or mariadb pool`, { data: { connection: settings.connection } });
+        this.#context = context;
+        this.#database = database;
+        this.#resource = resource;
+        if (context.runtime.describing === true)
+            return this.#describing(context);
+        const signing = signingSecrets(settings);
+        this.#cursors = new Cursors(signing.secrets);
+        // Names only, never the values (D-0047).
+        context.logger.log('debug', 'Search cursor secrets resolved.', {
+            code: 'SEARCH_SECRETS',
+            from: signing.from,
+            variable: signing.variable,
+            count: signing.secrets.length,
+        });
+        try {
+            this.#live = await this.#bringUp();
+        }
+        catch (error) {
+            // D-0127: an optional connection that is down does not stop the start; calls answer
+            // NOT_READY (with the cause) and reach the database again once it answers.
+            if (!optionalConnection(database, settings.connection) || permanent(error))
+                throw error;
+            this.#unavailable(error);
+        }
+        this.#repeats = new diagnostics.Repeats({ logger: context.logger, intervalMs: REPEAT_MS });
+        const timer = setInterval(() => {
+            void this.#flush();
+        }, settings.counts.flushMs);
+        timer.unref();
+        context.defer(async () => {
+            clearInterval(timer);
+            await this.#flush();
+            this.#repeats?.flush();
+        });
+        context.logger.log('debug', 'Search set up.', {
+            code: 'SEARCH_SETUP',
+            connection: settings.connection,
+            indexes: this.#indexes.names.length,
+            ready: this.#live !== undefined,
+            ms: Math.round(performance.now() - started),
+        });
+        return this.#api();
+    }
+    async #bringUp() {
+        const settings = this.#options;
+        const context = this.#context;
+        const resource = this.#resource;
+        const driver = await detectDriver(resource);
+        if (!driver)
+            throw new SearchError('UNSUPPORTED_RESOURCE', `Connection ${settings.connection} is not a pg, mysql2/promise or mariadb pool`, { data: { connection: settings.connection } });
+        const server = await serverDialect(driver, session(driver, resource));
+        // The plugin's own pool of the same connection, so searches never take the request pool;
+        // pool.max 0 shares the connection's.
+        this.#derived ??=
+            settings.pool.max > 0
+                ? await this.#database.derive(settings.connection, {
+                    purpose: 'search',
+                    overrides: { max: settings.pool.max },
+                })
+                : resource;
+        const pool = session(driver, this.#derived);
+        const store = new Store(server.dialect, settings.counts.slots);
+        let stored;
+        try {
+            await store.check(pool);
+            stored = await store.fingerprints(pool);
+        }
+        catch (error) {
+            if (isMissingTable(error))
+                throw new SearchError('TABLE_MISSING', 'The search tables are missing or older than this version', { cause: error, data: { connection: settings.connection } });
+            throw error;
+        }
+        // A new index is current (its rows are written from now on); a changed one is stale until
+        // the application indexed its rows again and called markCurrent.
+        for (const name of this.#indexes.names) {
+            const fingerprint = this.#indexes.fingerprint(name);
+            const before = stored.get(name);
+            if (before === undefined)
+                await store.saveFingerprint(pool, name, fingerprint, Date.now());
+            else if (before !== fingerprint) {
+                this.#stale.add(name);
+                context.logger.log('warn', 'A search index declaration changed: its rows need indexing again.', {
+                    code: 'SEARCH_INDEX_CHANGED',
+                    index: name,
+                    fix: `Index the rows of ${name} again (search.indexMany in batches), then call search.markCurrent('${name}')`,
+                });
+            }
+        }
+        context.logger.log('debug', 'Search connected.', {
+            code: 'SEARCH_CONNECTED',
+            connection: settings.connection,
+            dialect: server.dialect,
+            version: server.version,
+            pool: settings.pool.max,
+            stale: this.#stale.size,
+        });
+        return { driver, store, pool };
+    }
+    #unavailable(error) {
+        this.#lastError = error;
+        this.#lastTry = Date.now();
+        this.#context?.logger.log('warn', 'Search database is not reachable; calls answer NOT_READY until it is.', {
+            code: 'SEARCH_DB_UNAVAILABLE',
+            connection: this.#options.connection,
+            error: diagnostics.describeError(error),
+        });
+    }
+    /** The live store, or one more try when the database was down (at most once per second). */
+    async #ready() {
+        if (this.#live)
+            return this.#live;
+        if (!this.#bringing && Date.now() - this.#lastTry >= RETRY_MS) {
+            this.#lastTry = Date.now();
+            this.#bringing = this.#bringUp().finally(() => {
+                this.#bringing = undefined;
+            });
+        }
+        if (this.#bringing) {
+            try {
+                this.#live = await this.#bringing;
+                this.#context?.logger.log('info', 'Search database reached.', {
+                    code: 'SEARCH_DB_RECOVERED',
+                    connection: this.#options.connection,
+                });
+                return this.#live;
+            }
+            catch (error) {
+                this.#lastError = error;
+                if (permanent(error))
+                    throw error;
+            }
+        }
+        throw new SearchError('NOT_READY', 'The search database is not reachable', {
+            cause: this.#lastError,
+            data: { connection: this.#options.connection, retryAfterMs: RETRY_MS },
+        });
+    }
+    /** A statement failure as a coded error that keeps the driver's cause. */
+    async #run(operation, work) {
+        const live = await this.#ready();
+        try {
+            return await work(live);
+        }
+        catch (error) {
+            if (error instanceof SearchError)
+                throw error;
+            if (this.#context?.logger.isEnabled('debug'))
+                this.#context.logger.log('debug', 'Search statement failed.', {
+                    code: 'SEARCH_STORE_FAILED',
+                    operation,
+                    error: diagnostics.describeError(error),
+                });
+            throw new SearchError('STORE_FAILED', `The search could not ${operation}`, {
+                cause: error,
+                data: { operation },
+            });
+        }
+    }
+    #fields(index) {
+        const fields = typeof index === 'string' ? this.#indexes.fields(index) : undefined;
+        if (!fields)
+            throw new SearchError('UNKNOWN_INDEX', `Search index ${String(index)} is not declared`, {
+                data: { index: String(index).slice(0, 40) },
+            });
+        return fields;
+    }
+    #id(value, error = 'INVALID_ITEM') {
+        if (typeof value !== 'string' || !value.length || value.length > MAX_ID)
+            throw new SearchError(error, `id is a string of 1 to ${MAX_ID} characters`, {
+                data: { field: 'id' },
+            });
+        return value;
+    }
+    #scope(value, at, error) {
+        if (typeof value !== 'string' || value.length > MAX_SCOPE)
+            throw new SearchError(error, `${at} is a string of at most ${MAX_SCOPE} characters`, {
+                data: { field: at },
+            });
+        return value;
+    }
+    /** The rows and words of an item: one row per term, field and scope. */
+    #rowsOf(index, item) {
+        const fields = this.#fields(index);
+        if (!plain(item))
+            throw new SearchError('INVALID_ITEM', 'The item is { id, sortKey, scopes?, fields }');
+        this.#id(item.id);
+        if (!Number.isSafeInteger(item.sortKey))
+            throw new SearchError('INVALID_ITEM', 'sortKey is a safe integer', {
+                data: { field: 'sortKey' },
+            });
+        const scopes = item.scopes ?? [''];
+        if (!Array.isArray(scopes) || !scopes.length || scopes.length > MAX_SCOPES)
+            throw new SearchError('INVALID_ITEM', `scopes is a list of 1 to ${MAX_SCOPES} strings`, {
+                data: { field: 'scopes' },
+            });
+        for (const scope of scopes)
+            this.#scope(scope, 'scopes', 'INVALID_ITEM');
+        if (new Set(scopes).size !== scopes.length)
+            throw new SearchError('INVALID_ITEM', 'scopes are different strings', {
+                data: { field: 'scopes' },
+            });
+        if (!plain(item.fields))
+            throw new SearchError('INVALID_ITEM', 'fields is an object of texts', {
+                data: { field: 'fields' },
+            });
+        const rows = [];
+        const pairs = new Set();
+        for (const [field, text] of Object.entries(item.fields)) {
+            if (!fields.includes(field))
+                throw new SearchError('UNKNOWN_FIELD', `Field ${field} is not declared in ${index}`, {
+                    data: { index, field: field.slice(0, 40) },
+                });
+            if (text === null || text === undefined)
+                continue;
+            if (typeof text !== 'string' || text.length > MAX_TEXT)
+                throw new SearchError('INVALID_ITEM', `fields.${field} is a string of at most ${MAX_TEXT} characters`, { data: { field } });
+            const rules = this.#indexes.rules(index, field);
+            if (!rules)
+                continue;
+            for (const term of terms(text, rules)) {
+                pairs.add(`${field}${SEP}${term}`);
+                for (const scope of scopes)
+                    rows.push({ field, term, scope });
+            }
+        }
+        return { rows, pairs };
+    }
+    /** Writes one item: only the rows and counts that differ from what it had. */
+    async #write(live, tx, index, item) {
+        const { rows, pairs } = this.#rowsOf(index, item);
+        const old = await live.store.itemRows(tx, index, item.id);
+        const oldPairs = new Set(old.map((row) => `${row.field}${SEP}${row.term}`));
+        const key = (row) => `${row.field}${SEP}${row.term}${SEP}${row.scope}`;
+        if (old.some((row) => row.sortKey !== item.sortKey)) {
+            // The display order is part of every row's key: a new sortKey rewrites them all.
+            await live.store.deleteItem(tx, index, item.id);
+            await live.store.insertRows(tx, index, item.id, item.sortKey, rows);
+        }
+        else {
+            const now = new Set(rows.map(key));
+            const before = new Set(old.map(key));
+            const gone = old.filter((row) => !now.has(key(row)));
+            const added = rows.filter((row) => !before.has(key(row)));
+            if (gone.length)
+                await live.store.deleteRows(tx, index, item.id, gone);
+            if (added.length)
+                await live.store.insertRows(tx, index, item.id, item.sortKey, added);
+        }
+        this.#count(index, oldPairs, pairs);
+    }
+    /** Buffers the count changes of the words that came and went (added by #flush). */
+    #count(index, before, after) {
+        const add = (pair, delta) => {
+            const key = `${index}${SEP}${pair}`;
+            const value = (this.#pending.get(key) ?? 0) + delta;
+            if (value === 0)
+                this.#pending.delete(key);
+            else
+                this.#pending.set(key, value);
+        };
+        for (const pair of after)
+            if (!before.has(pair))
+                add(pair, 1);
+        for (const pair of before)
+            if (!after.has(pair))
+                add(pair, -1);
+        if (this.#pending.size >= FLUSH_WORDS)
+            void this.#flush();
+    }
+    /**
+     * Adds the buffered count changes to the table, one autocommit statement per index on the
+     * plugin's pool, words in sorted order. A failure is logged and the changes are kept for the
+     * next flush. Never rejects.
+     */
+    #flush() {
+        if (this.#flushing)
+            return this.#flushing;
+        if (!this.#pending.size || !this.#live)
+            return Promise.resolve();
+        const live = this.#live;
+        const taken = this.#pending;
+        this.#pending = new Map();
+        const work = async () => {
+            const byIndex = new Map();
+            for (const [key, delta] of taken) {
+                const first = key.indexOf(SEP);
+                const second = key.indexOf(SEP, first + 1);
+                const index = key.slice(0, first);
+                const list = byIndex.get(index) ?? [];
+                list.push({ field: key.slice(first + 1, second), term: key.slice(second + 1), delta });
+                byIndex.set(index, list);
+            }
+            for (const [index, deltas] of byIndex) {
+                deltas.sort((a, b) => byKey(a.field, b.field) || byKey(a.term, b.term));
+                try {
+                    await live.store.addCounts(live.pool, index, deltas);
+                }
+                catch (error) {
+                    // Kept for the next flush: the counts are late, never lost while the process runs.
+                    for (const row of deltas) {
+                        const key = `${index}${SEP}${row.field}${SEP}${row.term}`;
+                        this.#pending.set(key, (this.#pending.get(key) ?? 0) + row.delta);
+                    }
+                    this.#repeats?.log('error', 'Search word counts could not be written; they are kept for the next flush.', 'SEARCH_COUNTS_FAILED', error);
+                }
+            }
+        };
+        this.#flushing = work().finally(() => {
+            this.#flushing = undefined;
+        });
+        return this.#flushing;
+    }
+    #query(index, query) {
+        const fields = this.#fields(index);
+        if (!plain(query))
+            throw new SearchError('INVALID_QUERY', 'The query is { field, q, scope?, limit?, cursor? }');
+        if (typeof query.field !== 'string' || !fields.includes(query.field))
+            throw new SearchError('UNKNOWN_FIELD', `Field ${String(query.field)} is not declared in ${index}`, { data: { index, field: String(query.field).slice(0, 40) } });
+        if (typeof query.q !== 'string' || query.q.length > 1000)
+            throw new SearchError('INVALID_QUERY', 'q is a string of at most 1000 characters', {
+                data: { field: 'q' },
+            });
+        const scope = this.#scope(query.scope ?? '', 'scope', 'INVALID_QUERY');
+        const limit = query.limit ?? DEFAULT_LIMIT;
+        if (!Number.isSafeInteger(limit) || limit < 1 || limit > this.#options.list.maxLimit)
+            throw new SearchError('INVALID_QUERY', `limit is an integer from 1 to ${this.#options.list.maxLimit}`, { data: { field: 'limit' } });
+        const rules = this.#indexes.rules(index, query.field);
+        const { terms: words, short } = queryTerms(query.q, rules);
+        if (!words.length)
+            throw new SearchError('INVALID_QUERY', 'The query has no word to search for', {
+                data: { field: 'q' },
+            });
+        if (words.length > MAX_QUERY_WORDS)
+            throw new SearchError('INVALID_QUERY', `The query has more than ${MAX_QUERY_WORDS} words`, {
+                data: { field: 'q', words: words.length },
+            });
+        if (short.length)
+            throw new SearchError('INVALID_QUERY', `Every word is at least ${rules.minLength} characters in ${index}.${query.field}`, { data: { field: 'q', minLength: rules.minLength } });
+        const fingerprint = queryFingerprint(index, query.field, scope, words);
+        const state = query.cursor === undefined
+            ? undefined
+            : this.#cursors.open(query.cursor, fingerprint);
+        return { field: query.field, scope, limit, words, fingerprint, state };
+    }
+    async #find(live, index, query) {
+        const { field, scope, limit, words, fingerprint, state } = this.#query(index, query);
+        const cursors = this.#cursors;
+        const after = state && { sortKey: state.sortKey, id: state.id };
+        if (words.length === 1) {
+            // One word: one equality lookup in display order, whatever its frequency.
+            const rows = await live.store.page(live.pool, {
+                index,
+                field,
+                scope,
+                term: words[0],
+                after,
+                limit: limit + 1,
+            });
+            const items = rows.slice(0, limit);
+            const last = items.at(-1);
+            return Object.freeze({
+                items: Object.freeze(items.map((item) => Object.freeze(item))),
+                ...(rows.length > limit && last
+                    ? {
+                        next: cursors.sign({
+                            query: fingerprint,
+                            sortKey: last.sortKey,
+                            id: last.id,
+                            examined: 0,
+                        }),
+                    }
+                    : {}),
+                partial: false,
+                examined: rows.length,
+            });
+        }
+        // Several words: the rarest leads (the same one on every page of the search).
+        let lead = state?.lead;
+        if (lead !== undefined && !words.includes(lead))
+            throw new SearchError('INVALID_CURSOR', 'The search cursor is not valid: lead', {
+                data: { reason: 'lead' },
+            });
+        if (lead === undefined) {
+            const counts = await live.store.counts(live.pool, index, field, words);
+            let best;
+            let fewest = Number.POSITIVE_INFINITY;
+            for (const word of words) {
+                // A hint only: a word counted 0 leads, and its scan ends at once when it has no rows.
+                const count = counts.get(word) ?? 0;
+                if (count < fewest ||
+                    (count === fewest && best !== undefined && word.length > best.length)) {
+                    best = word;
+                    fewest = count;
+                }
+            }
+            lead = best;
+        }
+        const others = words.filter((word) => word !== lead);
+        const total = state?.examined ?? 0;
+        const budget = Math.min(this.#options.examineLimit, this.#options.searchLimit - total);
+        const items = [];
+        let examined = 0;
+        let position = after;
+        // Whether rows of the leading word may follow `position`.
+        let more = true;
+        while (items.length < limit && examined < budget) {
+            const chunk = Math.min(CHUNK, budget - examined);
+            const rows = await live.store.scan(live.pool, {
+                index,
+                field,
+                scope,
+                lead,
+                others,
+                after: position,
+                limit: chunk,
+            });
+            let read = 0;
+            for (const row of rows) {
+                read += 1;
+                position = { sortKey: row.sortKey, id: row.id };
+                if (row.hit) {
+                    items.push(Object.freeze({ id: row.id, sortKey: row.sortKey }));
+                    if (items.length === limit)
+                        break;
+                }
+            }
+            examined += read;
+            // A short chunk is the end of the word's rows; the page may have filled before its end.
+            if (rows.length < chunk) {
+                if (read === rows.length)
+                    more = false;
+                break;
+            }
+        }
+        const answer = { items: Object.freeze(items), examined };
+        if (!more || !position)
+            return Object.freeze({ ...answer, partial: false });
+        if (items.length < limit && total + examined >= this.#options.searchLimit) {
+            this.#context?.logger.log('debug', 'Search ended as too broad.', {
+                code: 'SEARCH_TOO_BROAD',
+                index,
+                field,
+                words: words.length,
+                examined: total + examined,
+            });
+            return Object.freeze({ ...answer, partial: false, stopped: 'SEARCH_TOO_BROAD' });
+        }
+        return Object.freeze({
+            ...answer,
+            next: cursors.sign({
+                query: fingerprint,
+                lead,
+                sortKey: position.sortKey,
+                id: position.id,
+                examined: total + examined,
+            }),
+            partial: items.length < limit,
+        });
+    }
+    /** Drain: the buffered counts go to the table while the database is still open. */
+    async drain() {
+        await this.#flush();
+    }
+    #api() {
+        const indexes = this.#indexes;
+        return Object.freeze({
+            indexes,
+            terms: (index, field, text) => {
+                this.#fields(index);
+                const rules = indexes.rules(index, field);
+                if (!rules)
+                    throw new SearchError('UNKNOWN_FIELD', `Field ${String(field)} is not declared in ${index}`);
+                if (typeof text !== 'string')
+                    throw new SearchError('INVALID_ITEM', 'text is a string', { data: { field: 'text' } });
+                return Object.freeze([...terms(text, rules)].sort(byKey));
+            },
+            // The item is checked (and its terms made) once, inside #write: a SearchError passes #run.
+            index: async (tx, index, item) => {
+                await this.#run('index an item', async (live) => this.#write(live, session(live.driver, tx), index, item));
+            },
+            indexMany: async (tx, index, items) => {
+                if (!Array.isArray(items))
+                    throw new SearchError('INVALID_ITEM', 'indexMany takes a list of items');
+                await this.#run('index items', async (live) => {
+                    const client = session(live.driver, tx);
+                    for (const item of items)
+                        await this.#write(live, client, index, item);
+                });
+            },
+            remove: async (tx, index, id) => {
+                this.#fields(index);
+                const item = this.#id(id);
+                return this.#run('remove an item', async (live) => {
+                    const client = session(live.driver, tx);
+                    const old = await live.store.itemRows(client, index, item);
+                    if (!old.length)
+                        return Object.freeze({ removed: false });
+                    await live.store.deleteItem(client, index, item);
+                    this.#count(index, new Set(old.map((row) => `${row.field}${SEP}${row.term}`)), new Set());
+                    return Object.freeze({ removed: true });
+                });
+            },
+            find: async (index, query) => {
+                return this.#run('search', (live) => this.#find(live, index, query));
+            },
+            flush: () => this.#flush(),
+            markCurrent: async (index) => {
+                this.#fields(index);
+                await this.#run('record an index as current', async (live) => {
+                    await live.store.saveFingerprint(live.pool, index, indexes.fingerprint(index), Date.now());
+                    this.#stale.delete(index);
+                });
+            },
+            status: () => Object.freeze(indexes.names.map((name) => Object.freeze({
+                name,
+                fingerprint: indexes.fingerprint(name),
+                stale: this.#stale.has(name),
+            }))),
+        });
+    }
+    /** `dokebi describe` opens no connection: the tables and indexes, every query refused. */
+    #describing(context) {
+        const settings = this.#options;
+        const indexes = this.#indexes;
+        context.contribute(describePoint, {
+            section: 'search',
+            describe: () => ({
+                connection: settings.connection,
+                tables: [TERMS_TABLE, COUNTS_TABLE, INDEXES_TABLE],
+                indexes: Object.fromEntries(indexes.names.map((name) => [name, indexes.fields(name)])),
+                examineLimit: settings.examineLimit,
+                searchLimit: settings.searchLimit,
+            }),
+        });
+        const refuse = () => Promise.reject(new SearchError('DESCRIBING', 'Search is being described: no query runs'));
+        return Object.freeze({
+            indexes,
+            terms: (index, field, text) => {
+                const rules = indexes.rules(index, field);
+                if (!rules)
+                    throw new SearchError('UNKNOWN_FIELD', `Field ${field} is not declared in ${index}`);
+                return Object.freeze([...terms(String(text), rules)].sort(byKey));
+            },
+            index: refuse,
+            indexMany: refuse,
+            remove: refuse,
+            find: refuse,
+            flush: () => Promise.resolve(),
+            markCurrent: refuse,
+            status: () => Object.freeze([]),
+        });
+    }
+}
+/** Factory input: `{ app, options?, entry }`: `entry` is the module of src/infra/search/indexes.ts. */
+export const createPlugin = definePlugin({
+    name: 'dokebi-search',
+    version: '0.1.0',
+    core: '^0.4.2',
+    options,
+    dependencies: () => [db],
+    contributes: [describePoint],
+    // The module of src/infra/search/indexes.ts (or the indexes themselves): INVALID_INDEXES otherwise.
+    entry: (input) => indexesOf(input),
+    instance: ({ options: parsed, entry }) => new SearchRuntime(parsed, entry),
+});