@zenera/rag 1.1.6 → 1.1.9

package/dist/common/embedder.d.ts

@@ -0,0 +1,3 @@
+import { type Embedder } from '@zenera/neo';
+export declare function resolveEmbedder(ref: string | undefined): Promise<Embedder>;
+//# sourceMappingURL=embedder.d.ts.map

package/dist/common/embedder.js

@@ -0,0 +1,64 @@
+import { bold, CliError, CURATED, cyan, dim, ensureHome, envNames, form, KeyStore, note, PROVIDERS, table, usageError, } from '@zenera/cli/lib';
+import { createEmbedder } from '@zenera/neo';
+// ---------------------------------------------------------------------------
+// Getting an embedder, and saying what the choices are when there is none
+//
+// The keyring is materialised here, and only here. The `zen` frame does not do
+// it, and a command that forgets to looks exactly like a machine with no key:
+// `zen key ls` shows the credential live and the command still says the
+// environment variable is not set. Real env always wins, so a shell that names
+// a key is never overridden by one on disk.
+//
+// Nothing in here is about a particular index. Which model made the vectors is
+// recorded in the manifest and enforced on every later search, so this only has
+// to turn a reference into an embedder — or, given none, into a list worth
+// choosing from.
+// ---------------------------------------------------------------------------
+export async function resolveEmbedder(ref) {
+    ensureHome();
+    const keys = await KeyStore.open();
+    // Asked before materialising, because materialising is what erases the
+    // difference between "the environment had it" and "the keyring supplied it".
+    const fromEnv = new Set(PROVIDERS.filter((p) => envNames(p).some((n) => process.env[n])));
+    keys.materialize();
+    if (!ref) {
+        throw choices(keys, fromEnv);
+    }
+    return createEmbedder(ref);
+}
+/**
+ * Well-known embedding models per provider, read off the CLI's catalog table so
+ * there is one list rather than two that drift. Any ref the registry can parse
+ * works; these are the ones worth typing. Anthropic has none because it
+ * publishes no embeddings API at all.
+ */
+const embeddingsOf = (provider) => CURATED[provider].filter((m) => m.roles.includes('embedding')).map((m) => m.id);
+/** What could be passed, with the ones this machine can actually use first. */
+function choices(keys, fromEnv) {
+    const rows = [];
+    const rest = [];
+    for (const provider of PROVIDERS) {
+        for (const model of embeddingsOf(provider)) {
+            const source = fromEnv.has(provider)
+                ? 'environment'
+                : keys.active(provider)
+                    ? 'keyring'
+                    : '';
+            const row = [`  ${cyan(`${provider}:${model}`)}`, dim(source || form(provider).env)];
+            (source ? rows : rest).push(row);
+        }
+    }
+    note(bold('Embeddings'));
+    for (const line of table([...rows, ...rest])) {
+        note(line);
+    }
+    note('');
+    if (rows.length === 0) {
+        note(dim('  no provider on this machine has a credential — try: zen key add openai'));
+        note('');
+    }
+    // `pick` is the one that ends the question rather than restating it: it
+    // tries them and prints the first that answers.
+    return usageError('no embedder named', 'pass --embedding <ref>, or run: zen models pick --embedding');
+}
+//# sourceMappingURL=embedder.js.map

package/dist/common/locate.d.ts

@@ -0,0 +1,18 @@
+import { type IndexKind, type IndexSpec } from './manifest.ts';
+/** How the directory was arrived at, which is what decides whether to say so. */
+export type DirSource = 'flag' | 'env' | 'found' | 'default';
+export interface Located {
+    dir: string;
+    from: DirSource;
+}
+export interface LocateOptions {
+    env?: NodeJS.ProcessEnv;
+    /** do not climb above this; the home directory, or the root, by default */
+    ceiling?: string;
+}
+export declare function locateIndex(cwd: string, flag: string | undefined, spec: IndexSpec, options?: LocateOptions): Located;
+/** Where a new index goes: the same environment variable, minus the search. */
+export declare function outputDir(cwd: string, flag: string | undefined, spec: IndexSpec, env?: NodeJS.ProcessEnv): string;
+/** An index of this kind is a directory with a manifest saying so; nothing else is asserted. */
+export declare function isIndex(dir: string, kind: IndexKind): boolean;
+//# sourceMappingURL=locate.d.ts.map

package/dist/{schema → common}/locate.js

@@ -1,22 +1,28 @@
 import { CliError, EXIT } from '@zenera/cli/lib';
-import { readdirSync, statSync } from 'node:fs';
+import { readdirSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, isAbsolute, join, parse, relative, resolve } from 'node:path';
-import { MANIFEST_FILE } from "./files.js";
+import { MANIFEST_FILE } from "./manifest.js";
 // ---------------------------------------------------------------------------
 // Which index, when nobody said
 //
-// `--dir` and `$ZEN_SCHEMA_DB` are taken as written, missing or not: naming a
-// directory that turns out not to hold an index has to fail saying so, because
-// quietly using a different one would be a worse answer than an error.
+// `--dir` and the environment variable are taken as written, missing or not:
+// naming a directory that turns out not to hold an index has to fail saying so,
+// because quietly using a different one would be a worse answer than an error.
 //
 // With neither, the directory is looked for. There is no list of blessed names
 // here and there should not be — an index is self-describing, so what is being
-// looked for is a `manifest.json`, not a directory called `schema-db`.
-// `schema-db` is only the name a *new* index is given, and nothing reads it
-// back. The search is nearest-first: this directory, then what is under it,
-// then up a level and again, so `/assets/…/whatever` is reachable from
-// `/workspace` because the two meet at a shared root on the way up.
+// looked for is a `manifest.json`, not a directory called `schema-db`. That
+// name is only what a *new* index is given, and nothing reads it back. The
+// search is nearest-first: this directory, then what is under it, then up a
+// level and again, so `/assets/…/whatever` is reachable from `/workspace`
+// because the two meet at a shared root on the way up.
+//
+// The manifest is read rather than merely counted, because a tree holding both
+// an API index and a document index has two answers to "the nearest index" and
+// only one of them is the one being asked for. Scoping the search by kind is
+// what stops the other from being found — and stops two subjects that happen to
+// sit side by side from reading as an ambiguity.
 //
 // Three things bound it, and each is bounding a different kind of mistake.
 // Depth and a visit budget bound the cost. The ceiling — the home directory,
@@ -24,11 +30,8 @@ import { MANIFEST_FILE } from "./files.js";
 // blast radius, because an index in someone else's tree is not yours. And two
 // indexes at the same distance is an ambiguity rather than a tie to break:
 // choosing one silently is the one failure worth ruling out entirely, since
-// the wrong index does not error, it answers confidently about another API.
+// the wrong index does not error, it answers confidently about another corpus.
 // ---------------------------------------------------------------------------
-/** The name a new index is given. Nothing searches for it; only `index --out` writes it. */
-export const DEFAULT_DIR = './schema-db';
-export const DIR_ENV = 'ZEN_SCHEMA_DB';
 /** Far enough to climb out of a package into its workspace, not far enough to roam. */
 const MAX_LEVELS = 6;
 /** How far below a directory an index may sit and still count as being in it. */
@@ -37,45 +40,56 @@ const MAX_DEPTH = 3;
 const MAX_ENTRIES = 128;
 /** Directories the whole search may read, however it is shaped. */
 const MAX_VISITS = 400;
-export function locateIndex(cwd, flag, options = {}) {
+export function locateIndex(cwd, flag, spec, options = {}) {
     const env = options.env ?? process.env;
     if (flag) {
         return { dir: resolve(cwd, flag), from: 'flag' };
     }
-    const named = env[DIR_ENV]?.trim();
+    const named = env[spec.envName]?.trim();
     if (named) {
         return { dir: resolve(cwd, named), from: 'env' };
     }
-    const found = search(resolve(cwd), options.ceiling ?? ceilingFor(cwd));
+    const found = search(resolve(cwd), options.ceiling ?? ceilingFor(cwd), spec);
     // Nothing found still answers with the default, so the error names the
     // directory everyone expects rather than the last place that was searched.
     return found
         ? { dir: found, from: 'found' }
-        : { dir: resolve(cwd, DEFAULT_DIR), from: 'default' };
+        : { dir: resolve(cwd, spec.defaultDir), from: 'default' };
 }
 /** Where a new index goes: the same environment variable, minus the search. */
-export function outputDir(cwd, flag, env = process.env) {
-    return resolve(cwd, flag ?? env[DIR_ENV]?.trim() ?? DEFAULT_DIR);
+export function outputDir(cwd, flag, spec, env = process.env) {
+    return resolve(cwd, flag ?? env[spec.envName]?.trim() ?? spec.defaultDir);
 }
-/** An index is a directory with a manifest in it; nothing else is asserted here. */
-export function isIndex(dir) {
+/** An index of this kind is a directory with a manifest saying so; nothing else is asserted. */
+export function isIndex(dir, kind) {
+    let text;
     try {
-        return statSync(join(dir, MANIFEST_FILE)).isFile();
+        text = readFileSync(join(dir, MANIFEST_FILE), 'utf8');
     }
     catch {
         return false;
     }
+    let found;
+    try {
+        found = JSON.parse(text).kind;
+    }
+    catch {
+        // A manifest too broken to parse is still an index, and saying so is
+        // what gets the caller that error instead of "nothing found".
+        return true;
+    }
+    return (found ?? 'schema') === kind;
 }
-function search(cwd, ceiling) {
+function search(cwd, ceiling, spec) {
     const budget = { left: MAX_VISITS, seen: new Set() };
     let dir = cwd;
     for (let level = 0; level < MAX_LEVELS; level++) {
-        const found = nearest(dir, budget);
+        const found = nearest(dir, budget, spec.kind);
         if (found.length === 1) {
             return found[0];
         }
         if (found.length > 1) {
-            throw new CliError(`more than one index is equally close to here: ${found.join(', ')}`, EXIT.usage, `say which with --dir, or set ${DIR_ENV}`);
+            throw new CliError(`more than one index is equally close to here: ${found.join(', ')}`, EXIT.usage, `say which with --dir, or set ${spec.envName}`);
         }
         budget.seen.add(dir);
         const up = dirname(dir);
@@ -87,10 +101,10 @@ function search(cwd, ceiling) {
     return undefined;
 }
 /** Every index at the shallowest depth that has any, so a tie can be reported as one. */
-function nearest(root, budget) {
+function nearest(root, budget, kind) {
     let frontier = [root];
     for (let depth = 0; depth <= MAX_DEPTH && frontier.length > 0; depth++) {
-        const found = frontier.filter(isIndex);
+        const found = frontier.filter((dir) => isIndex(dir, kind));
         if (found.length > 0) {
             return found;
         }

package/dist/common/manifest.d.ts

@@ -0,0 +1,50 @@
+export declare const MANIFEST_FILE = "manifest.json";
+export type IndexKind = 'schema' | 'docs';
+/** How to name a kind when something has to be said about it. */
+export declare const SUBJECT: Record<IndexKind, {
+    label: string;
+    command: string;
+}>;
+/** The part of a manifest that does not depend on what was indexed. */
+export interface IndexHead {
+    /** the format version of this kind of index */
+    version: number;
+    kind: IndexKind;
+    createdAt: string;
+    indexer: string;
+    /** `ref` as it was typed, `id` as the embedder answers to it */
+    embedding: {
+        ref: string;
+        id: string;
+        dimensions: number;
+    };
+    /** whether the table carries an fts index, and whether it carries a vector one */
+    indexes: {
+        fts: boolean;
+        vector: boolean;
+    };
+}
+/** One subject's identity: enough to find an index, read one, and refuse one. */
+export interface IndexSpec {
+    kind: IndexKind;
+    version: number;
+    /** the name a NEW index is given; nothing ever searches for it */
+    defaultDir: string;
+    envName: string;
+}
+/**
+ * The manifest, or the reason there is not one. Three refusals, and each names
+ * a different thing to do next: build one, use the other subject, rebuild.
+ */
+export declare function readHead<T extends IndexHead>(dir: string, spec: IndexSpec): Promise<T>;
+/**
+ * A store answers with the neighbours of a vector, and a vector means nothing
+ * without the model that produced it. Asking one model's index a question
+ * embedded by another returns rows, in an order that is noise.
+ *
+ * Either spelling is accepted, because `openai:text-embedding-3-small` and
+ * `text-embedding-3-small` are one model and which of them was typed is not
+ * something anyone should have to remember.
+ */
+export declare function assertSameEmbedding(head: IndexHead, ref: string): void;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/common/manifest.js

@@ -0,0 +1,62 @@
+import { CliError, EXIT } from '@zenera/cli/lib';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+// ---------------------------------------------------------------------------
+// What every index says about itself
+//
+// An index is a directory, and `manifest.json` is the first thing anything
+// reads out of one. It is written LAST by a build, so its presence is the
+// commit marker: a half-built directory has no manifest and reads as "not
+// indexed" rather than as a store that quietly lost half of what it holds.
+//
+// `kind` is what keeps two subjects apart in one tree. Without it, pointing a
+// document search at an API index is not an error — it is rows, in an order
+// that means nothing, about the wrong corpus entirely. That is the failure
+// worth spending a field on.
+// ---------------------------------------------------------------------------
+export const MANIFEST_FILE = 'manifest.json';
+/** How to name a kind when something has to be said about it. */
+export const SUBJECT = {
+    schema: { label: 'a schema index', command: 'zen rag schema' },
+    docs: { label: 'a document index', command: 'zen rag docs' },
+};
+/**
+ * The manifest, or the reason there is not one. Three refusals, and each names
+ * a different thing to do next: build one, use the other subject, rebuild.
+ */
+export async function readHead(dir, spec) {
+    const { label, command } = SUBJECT[spec.kind];
+    let text;
+    try {
+        text = await readFile(join(dir, MANIFEST_FILE), 'utf8');
+    }
+    catch {
+        throw new CliError(`${dir} does not hold an index`, EXIT.invalid, `build one with \`${command} index\`, or name an existing one with --dir or $${spec.envName}`);
+    }
+    const head = JSON.parse(text);
+    // Written since there was more than one kind; before that there was only
+    // the one, so a manifest that does not say is a schema index.
+    const kind = head.kind ?? 'schema';
+    if (kind !== spec.kind) {
+        throw new CliError(`${dir} holds ${SUBJECT[kind].label}, not ${label}`, EXIT.invalid, `read it with \`${SUBJECT[kind].command} search\``);
+    }
+    if (head.version !== spec.version) {
+        throw new CliError(`${dir} is a version ${head.version} index, and this indexer reads version ${spec.version}`, EXIT.invalid, `rebuild it with \`${command} index\``);
+    }
+    return head;
+}
+/**
+ * A store answers with the neighbours of a vector, and a vector means nothing
+ * without the model that produced it. Asking one model's index a question
+ * embedded by another returns rows, in an order that is noise.
+ *
+ * Either spelling is accepted, because `openai:text-embedding-3-small` and
+ * `text-embedding-3-small` are one model and which of them was typed is not
+ * something anyone should have to remember.
+ */
+export function assertSameEmbedding(head, ref) {
+    if (ref !== head.embedding.ref && ref !== head.embedding.id) {
+        throw new CliError(`this index was built with ${head.embedding.ref}, not ${ref}`, EXIT.invalid, `search it with --embedding ${head.embedding.ref}, or rebuild it`);
+    }
+}
+//# sourceMappingURL=manifest.js.map

package/dist/common/progress.d.ts

@@ -0,0 +1,57 @@
+export declare const LOCK_FILE = ".lock";
+export declare const README_FILE = "README.md";
+/** The floor on how often README.md is rewritten. */
+export declare const INTERVAL_MS = 5000;
+export interface Building<S> {
+    documents: readonly string[];
+    embedding: string;
+    started: number;
+    now: number;
+    /** the current phase, as it should be said out loud */
+    step: string;
+    done: number;
+    total: number;
+    /** what the documents turned out to hold, once they have been read */
+    summary: S | undefined;
+}
+export interface Completed<M> {
+    dir: string;
+    manifest: M;
+    ms: number;
+}
+export interface Failed {
+    documents: readonly string[];
+    step: string;
+    reason: unknown;
+    started: number;
+}
+/** The three states a README can be in, written by whoever knows the subject. */
+export interface Report<S, M> {
+    building(state: Building<S>): string;
+    complete(state: Completed<M>): string;
+    failed(state: Failed): string;
+}
+export interface BuildPlan<S, M, P extends string> {
+    /** where the index goes */
+    dir: string;
+    files: readonly string[];
+    /** the embedding reference as it was typed */
+    embedding: string;
+    indexer: string;
+    /** every phase, in order; the first is where a build starts */
+    phases: Readonly<Record<P, string>>;
+    report: Report<S, M>;
+}
+export interface Journal<S, M, P extends string> {
+    phase(name: P): void;
+    read(summary: S, total: number): void;
+    progress(done: number, total: number): void;
+    finish(manifest: M): void;
+    fail(reason: unknown): void;
+}
+/**
+ * Takes the directory, or refuses it. Two builds writing one index would
+ * interleave their store writes and leave one that neither of them describes.
+ */
+export declare function beginBuild<S, M, P extends string>(plan: BuildPlan<S, M, P>): Journal<S, M, P>;
+//# sourceMappingURL=progress.d.ts.map

package/dist/common/progress.js

@@ -0,0 +1,155 @@
+import { CliError, EXIT } from '@zenera/cli/lib';
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { hostname } from 'node:os';
+import { basename, join } from 'node:path';
+// ---------------------------------------------------------------------------
+// A build that says what it is doing
+//
+// Indexing a large corpus is minutes of silence with a directory slowly
+// filling up, and the directory is the only thing a second person — or a second
+// process, or an agent reading the tree — ever sees. So the build writes two
+// files into it and keeps them true:
+//
+//   .lock       who is building this, right now. Gone when nothing is.
+//   README.md   a progress report while it runs, and a description of what the
+//               index holds once it does not.
+//
+// Nothing in either file is an absolute path. A project's `assets/` directory
+// is mounted at `/assets` inside an agent's sandbox, so an index built there is
+// read under a name this process never sees; a host path would be a lie there.
+//
+// What is here is the mechanics — the lock, the throttle, the atomic rewrite.
+// The words belong to whatever is being indexed, so they arrive as a `Report`.
+// ---------------------------------------------------------------------------
+export const LOCK_FILE = '.lock';
+export const README_FILE = 'README.md';
+/** The floor on how often README.md is rewritten. */
+export const INTERVAL_MS = 5000;
+/**
+ * Takes the directory, or refuses it. Two builds writing one index would
+ * interleave their store writes and leave one that neither of them describes.
+ */
+export function beginBuild(plan) {
+    const documents = plan.files.map((file) => basename(file));
+    const started = Date.now();
+    const lock = {
+        pid: process.pid,
+        host: hostname(),
+        startedAt: new Date(started).toISOString(),
+        indexer: plan.indexer,
+        embedding: plan.embedding,
+        documents,
+    };
+    mkdirSync(plan.dir, { recursive: true });
+    claim(join(plan.dir, LOCK_FILE), lock);
+    let phase = Object.keys(plan.phases)[0];
+    let summary;
+    let done = 0;
+    let total = 0;
+    let wroteAt = 0;
+    let closed = false;
+    const write = (body) => {
+        // Through a temp name, so a reader never catches half a file.
+        const target = join(plan.dir, README_FILE);
+        const temp = `${target}.tmp`;
+        writeFileSync(temp, body);
+        renameSync(temp, target);
+        wroteAt = Date.now();
+    };
+    const report = () => write(plan.report.building({
+        documents,
+        embedding: plan.embedding,
+        started,
+        now: Date.now(),
+        step: plan.phases[phase],
+        done,
+        total,
+        summary,
+    }));
+    const maybe = () => {
+        if (!closed && Date.now() - wroteAt >= INTERVAL_MS) {
+            report();
+        }
+    };
+    // The first embedding request can block for ten seconds or more, so a purely
+    // event-driven throttle would leave the elapsed line frozen through it.
+    const ticker = setInterval(maybe, INTERVAL_MS);
+    ticker.unref();
+    const close = (body) => {
+        if (closed) {
+            return;
+        }
+        closed = true;
+        clearInterval(ticker);
+        write(body);
+        rmSync(join(plan.dir, LOCK_FILE), { force: true });
+    };
+    report();
+    return {
+        phase(name) {
+            phase = name;
+            maybe();
+        },
+        read(seen, count) {
+            summary = seen;
+            total = count;
+            maybe();
+        },
+        progress(at, of) {
+            done = at;
+            total = of;
+            maybe();
+        },
+        finish(manifest) {
+            close(plan.report.complete({ dir: plan.dir, manifest, ms: Date.now() - started }));
+        },
+        fail(reason) {
+            close(plan.report.failed({ documents, step: plan.phases[phase], reason, started }));
+        },
+    };
+}
+/**
+ * `wx` makes the create and the check one operation, so two builds racing for
+ * the same directory cannot both win. A lock whose process is gone is stale by
+ * definition and is taken rather than respected — a crashed build must not make
+ * a directory permanently unbuildable.
+ */
+function claim(path, lock) {
+    const body = `${JSON.stringify(lock, null, 4)}\n`;
+    try {
+        writeFileSync(path, body, { flag: 'wx' });
+        return;
+    }
+    catch (err) {
+        if (err.code !== 'EEXIST') {
+            throw err;
+        }
+    }
+    const held = readLock(path);
+    if (held && held.host === hostname() && alive(held.pid)) {
+        throw new CliError(`this index is already being built (pid ${held.pid}, since ${held.startedAt})`, EXIT.failed, `wait for it, or build elsewhere with --out`);
+    }
+    writeFileSync(path, body);
+}
+function readLock(path) {
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * `kill(pid, 0)` sends no signal and only asks whether the process exists.
+ * EPERM means it exists and belongs to someone else, which still counts.
+ */
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}
+//# sourceMappingURL=progress.js.map

package/dist/common/prose.d.ts

@@ -0,0 +1,13 @@
+/** An indented block, which markdown renders verbatim and an agent reads as a table. */
+export declare function fields(rows: readonly string[][]): string[];
+/** A markdown table, padded so the source is readable unrendered. */
+export declare function grid(headers: readonly string[], rows: readonly (readonly string[])[]): string[];
+export declare function plural(n: number, one: string, many?: string): string;
+export declare function duration(ms: number): string;
+/** The first line only: a stack trace in a README helps nobody. */
+export declare function message(reason: unknown): string;
+export declare function searched(indexes: {
+    fts: boolean;
+    vector: boolean;
+}): string;
+//# sourceMappingURL=prose.d.ts.map

package/dist/common/prose.js

@@ -0,0 +1,56 @@
+// ---------------------------------------------------------------------------
+// Small renderings, shared by every README a build writes
+//
+// These are markdown that an agent reads as often as a person does, so the
+// phrasing is plain and the shapes are stable. Nothing here knows what was
+// indexed.
+// ---------------------------------------------------------------------------
+/** An indented block, which markdown renders verbatim and an agent reads as a table. */
+export function fields(rows) {
+    const width = Math.max(...rows.map((r) => (r[0] ?? '').length));
+    return rows.map(([name, value]) => `    ${(name ?? '').padEnd(width)}  ${value ?? ''}`);
+}
+/** A markdown table, padded so the source is readable unrendered. */
+export function grid(headers, rows) {
+    const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => (r[i] ?? '').length)));
+    const line = (cells) => `| ${cells.map((c, i) => c.padEnd(widths[i] ?? 0)).join(' | ')} |`;
+    return [
+        line(headers),
+        `| ${widths.map((w) => '-'.repeat(w)).join(' | ')} |`,
+        ...rows.map(line),
+    ];
+}
+export function plural(n, one, many = `${one}s`) {
+    return `${n} ${n === 1 ? one : many}`;
+}
+export function duration(ms) {
+    const seconds = Math.round(ms / 1000);
+    if (seconds < 1) {
+        return 'under a second';
+    }
+    if (seconds < 60) {
+        return `${seconds}s`;
+    }
+    const minutes = Math.floor(seconds / 60);
+    return minutes < 60
+        ? `${minutes}m${seconds % 60}s`
+        : `${Math.floor(minutes / 60)}h${minutes % 60}m`;
+}
+/** The first line only: a stack trace in a README helps nobody. */
+export function message(reason) {
+    const text = reason instanceof Error ? reason.message : String(reason);
+    return text.split('\n')[0]?.trim() || 'no reason given';
+}
+export function searched(indexes) {
+    if (!indexes.fts && !indexes.vector) {
+        return 'scanned flat: neither index was built';
+    }
+    if (!indexes.vector) {
+        // Below a couple of thousand rows an IVF index has nothing to train on.
+        return 'searched by full text and by vector, the latter as a flat scan';
+    }
+    return indexes.fts
+        ? 'searched by full text and by vector'
+        : 'searched by vector, with no full-text index';
+}
+//# sourceMappingURL=prose.js.map

package/dist/index.d.ts

@@ -1,13 +1,14 @@
-export * from './present.ts';
-export * from './query.ts';
+export * from './common/locate.ts';
+export * from './common/manifest.ts';
+export * from './common/match.ts';
 export * from './schema/build.ts';
 export * from './schema/entities.ts';
 export * from './schema/files.ts';
 export * from './schema/graph.ts';
 export * from './schema/hydrate.ts';
-export * from './schema/locate.ts';
 export * from './schema/lookup.ts';
-export * from './schema/match.ts';
+export * from './schema/present.ts';
+export * from './schema/query.ts';
 export * from './schema/render.ts';
 export * from './schema/schema.ts';
 export * from './schema/search.ts';
@@ -15,5 +16,6 @@ export * from './schema/spec.ts';
 export * from './schema/store.ts';
 export * from './schema/subgraph.ts';
 export * from './schema/tools.ts';
+export * from './schema/trace.ts';
 export * from './schema/typescript.ts';
 //# sourceMappingURL=index.d.ts.map