latticesql 4.0.1 → 4.1.0

package/dist/index.d.cts

@@ -666,6 +666,224 @@ declare class InMemoryStateStore implements WritebackStateStore {
  */
 declare function createSQLiteStateStore(db: Database.Database): WritebackStateStore;
 
+/**
+ * Reranking — an optional second-stage scorer applied to the top candidates of
+ * a first-stage retrieval (vector / FTS / hybrid). A cross-encoder reranker
+ * typically lifts precision@k meaningfully over bi-encoder similarity, at the
+ * cost of one model call over the (small) candidate set.
+ *
+ * Bring your own reranker: Lattice never calls a model. The reranker is given
+ * the query and the candidate texts and returns a score per candidate; higher =
+ * more relevant. If it throws or returns nothing usable, retrieval falls back to
+ * the first-stage order — a reranker is an enhancement, never a hard dependency.
+ */
+/** A candidate handed to a reranker: an id and the text to score against the query. */
+interface RerankCandidate {
+    id: string;
+    content: string;
+}
+/** A reranker's verdict for one candidate. */
+interface RerankScore {
+    id: string;
+    score: number;
+}
+/**
+ * Rerank `candidates` for `query`, returning a score per id (higher = better).
+ * May be sync or async. Ids absent from the result keep their prior order after
+ * any that were scored.
+ */
+type RerankerFn = (query: string, candidates: RerankCandidate[]) => Promise<RerankScore[]> | RerankScore[];
+/**
+ * Apply a reranker to an ordered list of items, returning a new order. Each item
+ * supplies its `id` and the `content` to rerank on. On any reranker failure (or
+ * an empty/garbage result) the original order is returned unchanged — reranking
+ * never breaks retrieval.
+ *
+ * Returns `{ order, applied }`: `order` is the reordered items, `applied` is true
+ * only when the reranker actually contributed scores. Items the reranker didn't
+ * score retain their relative first-stage order, after the scored ones.
+ */
+declare function applyReranker<T extends {
+    id: string;
+    content: string;
+}>(query: string, items: T[], reranker: RerankerFn): Promise<{
+    order: T[];
+    applied: boolean;
+    scores: Map<string, number>;
+}>;
+
+/**
+ * Text chunking for embedding.
+ *
+ * Embedding a whole row as one vector blurs many topics into a single point,
+ * which loses precision and forces a retriever to send large units to the model.
+ * Splitting text into smaller, semantically coherent chunks — each embedded
+ * separately — raises precision@k and lets a retriever return a few small,
+ * on-point units instead of one big one (fewer tokens to a correct answer).
+ *
+ * The default `semanticChunker` is dependency-free and boundary-aware: it packs
+ * text up to a character budget, preferring to break at paragraph, then
+ * sentence, then word boundaries, with optional overlap so context that
+ * straddles a boundary is not lost. Bring your own {@link ChunkerFn} (e.g. a
+ * token-aware or code-aware splitter) when the default heuristic isn't enough.
+ */
+/** A single chunk of source text with its character offsets in the original. */
+interface TextChunk {
+    /** 0-based position of this chunk in the sequence. */
+    index: number;
+    /** The chunk text (already includes any leading overlap). */
+    content: string;
+    /** Inclusive start offset in the source string. */
+    start: number;
+    /** Exclusive end offset in the source string. */
+    end: number;
+}
+/** Splits source text into ordered chunks. */
+type ChunkerFn = (text: string) => TextChunk[];
+interface SemanticChunkerOptions {
+    /** Target maximum characters per chunk. Default 1000. */
+    maxChars?: number;
+    /**
+     * Characters of trailing context to repeat at the start of the next chunk.
+     * Default 0. Must be < maxChars.
+     */
+    overlap?: number;
+    /**
+     * Minimum chunk size — a trailing remainder smaller than this is merged into
+     * the previous chunk rather than emitted on its own. Default 0.
+     */
+    minChars?: number;
+}
+/**
+ * Create a boundary-aware chunker. Empty/whitespace-only input yields no chunks.
+ * Text shorter than `maxChars` yields a single chunk.
+ */
+declare function semanticChunker(opts?: SemanticChunkerOptions): ChunkerFn;
+/**
+ * Apply chunking to a piece of text using the table's config. When no chunker is
+ * configured the whole text is one chunk (index 0) — the historical behavior.
+ * A `contextPrefix` (e.g. a title or breadcrumb) is prepended to every chunk's
+ * embedded content so each chunk carries enough context to be retrieved well.
+ */
+declare function chunkText(text: string, chunker?: ChunkerFn, contextPrefix?: string): {
+    chunkIndex: number;
+    content: string;
+}[];
+
+/**
+ * Declarative computed columns + materialized rollups.
+ *
+ * **Computed columns** are stored columns derived from other columns on the same
+ * row by a pure function. They are recomputed on every write (and on a full
+ * `refreshComputedColumns`), so a consumer can index / filter / sort on a derived
+ * value without recomputing it per query, and an external edit to the rendered
+ * file can't desync it — the next write recomputes it.
+ *
+ * **Materialized rollups** are stored aggregates over a child table (e.g.
+ * `post.comment_count`). They are recomputed incrementally when the child table
+ * changes and in full via `refreshMaterializedRollups`.
+ *
+ * Both are opt-in per table and inert otherwise.
+ */
+
+interface ComputedColumnSpec {
+    /** Columns this value is derived from. Drives recompute-on-change + cycle check. */
+    deps: string[];
+    /** Pure derivation from the row. Receives the full (merged) row. */
+    compute: (row: Row) => unknown;
+    /** SQL column type. Default `TEXT`. */
+    type?: string;
+}
+type RollupFunction = 'count' | 'sum' | 'avg' | 'min' | 'max';
+interface MaterializedRollupSpec {
+    /** Child table to aggregate. */
+    sourceTable: string;
+    /** Column on the child table that references this table's primary key. */
+    foreignKey: string;
+    /** Aggregate function. */
+    fn: RollupFunction;
+    /** Child column to aggregate (omit for `count`). */
+    column?: string;
+    /** SQL column type for the stored rollup. Default `REAL`. */
+    type?: string;
+}
+/**
+ * Thrown when computed columns form a dependency cycle (A→B→A), which would make
+ * the recompute order undefined. Detected once at init.
+ */
+declare class ComputedColumnCycleError extends Error {
+    readonly table: string;
+    readonly cycle: string[];
+    constructor(table: string, cycle: string[]);
+}
+/**
+ * Validate that computed columns have no dependency cycle and return a safe
+ * recompute order (dependencies before dependents). Only deps that are
+ * themselves computed columns participate in ordering; deps on plain columns are
+ * leaves. Throws {@link ComputedColumnCycleError} on a cycle.
+ */
+declare function computedColumnOrder(table: string, computed: Record<string, ComputedColumnSpec>): string[];
+/**
+ * Compute the values for `computed` columns from a (full) row, in dependency
+ * order, mutating the working row so later computed columns can read earlier
+ * ones. Returns a map of computed column → value.
+ */
+declare function computeColumns(computed: Record<string, ComputedColumnSpec>, order: string[], row: Row): Record<string, unknown>;
+/** The DDL column spec map computed columns contribute. */
+declare function computedColumnDdl(computed: Record<string, ComputedColumnSpec>): Record<string, string>;
+/** The DDL column spec map materialized rollups contribute. */
+declare function rollupColumnDdl(rollups: Record<string, MaterializedRollupSpec>): Record<string, string>;
+/** The set of all dep columns across computed specs (for change detection). */
+declare function allComputedDeps(computed: Record<string, ComputedColumnSpec>): Set<string>;
+
+/**
+ * Data governance primitives — provenance and trust.
+ *
+ * **Provenance** records, immutably, where a row came from: how it was ingested,
+ * the source URI, and when. Stamped at creation and frozen — an update that tries
+ * to change a provenance column fails loudly, so the lineage a risk/compliance
+ * reviewer signs off on can't be quietly rewritten.
+ *
+ * **Trust** gates untrusted ingest: a table opted into trust gives every new row a
+ * `_trust_state` (default `unverified`), and a verification workflow
+ * (`markRowForReview` / `verifyRow`) moves rows to `needs_review` / `verified`.
+ * Downstream consumers can filter to verified rows only.
+ *
+ * Both are opt-in per table and add no overhead to tables that don't use them.
+ */
+type ProvenanceField = 'ingested_via' | 'source_uri' | 'ingested_at';
+interface ProvenanceConfig {
+    /**
+     * Which immutable provenance columns to add and stamp. Defaults to all three
+     * (`ingested_via`, `source_uri`, `ingested_at`). `ingested_at` is auto-stamped
+     * on insert when not supplied.
+     */
+    fields?: ProvenanceField[];
+}
+type TrustState = 'unverified' | 'needs_review' | 'verified';
+interface TrustConfig {
+    /** State assigned to a row on insert. Default `'unverified'`. */
+    defaultState?: TrustState;
+}
+declare const ALL_PROVENANCE_FIELDS: readonly ProvenanceField[];
+/** Trust bookkeeping columns (internal-prefixed-ish, opt-in per table). */
+declare const TRUST_COLUMNS: Record<string, string>;
+/** Resolve a `provenance` config (boolean | object) to its column list. */
+declare function resolveProvenanceFields(config: boolean | ProvenanceConfig | undefined): ProvenanceField[];
+/** The DDL column spec map a provenance config contributes. */
+declare function provenanceColumns(config: boolean | ProvenanceConfig | undefined): Record<string, string>;
+/** Resolve a `trust` config (boolean | object) to its default state. */
+declare function resolveTrustDefault(config: boolean | TrustConfig | undefined): TrustState | null;
+/**
+ * Thrown when an update tries to change an immutable provenance column. Lineage
+ * is creation-time only; surfacing this loudly prevents silent provenance drift.
+ */
+declare class ProvenanceImmutableError extends Error {
+    readonly table: string;
+    readonly column: string;
+    constructor(table: string, column: string);
+}
+
 type Row = Record<string, unknown>;
 
 interface LatticeOptions {
@@ -711,6 +929,14 @@ interface LatticeOptions {
      * ...")` on violation, so callers can catch it.
      */
     maxRowBytes?: number;
+    /**
+     * Default bounded-read cap for `query()` (4.1+). When set, a `query()` with no
+     * explicit `limit` and no per-call `maxRows` returns at most this many rows and
+     * throws `BoundedReadError` if more match — a guardrail against an accidental
+     * unbounded full-table load on a hot path. A per-call `maxRows` or an explicit
+     * `limit` overrides it. Off by default (unbounded, preserving prior behavior).
+     */
+    defaultMaxRows?: number;
 }
 /**
  * Retention policy for the change log.
@@ -855,7 +1081,41 @@ interface Filter {
      * For `in`, must be an array.
      */
     val?: unknown;
+    /**
+     * Extract a value from a JSON/JSONB column before comparing. A string like
+     * `'a.b'` or an array `['a', 'b']` addresses a nested key. Compiles to
+     * SQLite `json_extract(col, '$.a.b')` and Postgres `col #>> '{a,b}'`.
+     *
+     * @example
+     * ```ts
+     * { col: 'metadata_json', jsonPath: 'priority', op: 'gte', val: 3 }
+     * { col: 'data', jsonPath: ['address', 'city'], op: 'eq', val: 'NYC' }
+     * ```
+     */
+    jsonPath?: string | string[];
+}
+/** An OR group of filter expressions (any may match). */
+interface FilterOr {
+    or: FilterExpr[];
+}
+/** An AND group of filter expressions (all must match). */
+interface FilterAnd {
+    and: FilterExpr[];
 }
+/**
+ * A filter expression: a single {@link Filter} clause, or a recursive `or` / `and`
+ * group of expressions. A bare `Filter` (the pre-4.1 shape) is still a valid
+ * `FilterExpr`, so existing `filters: Filter[]` usage is unchanged.
+ *
+ * @example
+ * ```ts
+ * filters: [
+ *   { col: 'status', op: 'eq', val: 'open' },
+ *   { or: [ { col: 'priority', op: 'gte', val: 3 }, { col: 'pinned', op: 'eq', val: true } ] },
+ * ]
+ * ```
+ */
+type FilterExpr = Filter | FilterOr | FilterAnd;
 /**
  * Names of the four built-in render templates.
  *
@@ -1128,6 +1388,36 @@ interface TableDefinition {
     encrypted?: boolean | {
         columns: string[];
     };
+    /**
+     * Record immutable provenance for each row (4.1+). `true` adds three columns —
+     * `ingested_via`, `source_uri`, `ingested_at` — or pass a {@link ProvenanceConfig}
+     * to choose a subset. `ingested_at` is auto-stamped on insert; an `update()`
+     * that tries to change any provenance column throws `ProvenanceImmutableError`,
+     * so lineage can't be silently rewritten. Tables without this config are
+     * unaffected.
+     */
+    provenance?: boolean | ProvenanceConfig;
+    /**
+     * Gate untrusted ingest with a per-row trust state (4.1+). `true` (or a
+     * {@link TrustConfig}) adds `_trust_state` (default `'unverified'`) plus
+     * `_verified_by` / `_verified_at` / `_review_reason`, and enables the
+     * verification workflow (`markRowForReview` / `verifyRow` / `rowsNeedingReview`
+     * / `verifiedRows`). Tables without this config are unaffected.
+     */
+    trust?: boolean | TrustConfig;
+    /**
+     * Declarative computed columns (4.1+) — stored columns derived from other
+     * columns on the same row by a pure function, recomputed on every write (and
+     * via `refreshComputedColumns`). Lets you index / filter / sort on a derived
+     * value. A dependency cycle is rejected at init. See {@link ComputedColumnSpec}.
+     */
+    computed?: Record<string, ComputedColumnSpec>;
+    /**
+     * Materialized rollups (4.1+) — stored aggregates over a child table (e.g.
+     * `comment_count`), recomputed when the child changes and via
+     * `refreshMaterializedRollups`. See {@link MaterializedRollupSpec}.
+     */
+    materializedRollups?: Record<string, MaterializedRollupSpec>;
 }
 interface MultiTableDefinition {
     /** Returns the "anchor" entities — one output file is produced per anchor */
@@ -1157,6 +1447,27 @@ interface EmbeddingsConfig {
      * Bring your own model — Lattice does not bundle an embedding provider.
      */
     embed: (text: string) => Promise<number[]>;
+    /**
+     * Optional text splitter. When set, each row's concatenated text is split
+     * into chunks and every chunk is embedded separately, so semantic search
+     * matches the most relevant *part* of a row rather than the blurred average
+     * of the whole. Omit for the historical whole-row behavior (one vector/row).
+     * See `semanticChunker` for a dependency-free boundary-aware default.
+     */
+    chunker?: ChunkerFn;
+    /**
+     * Optional per-row context prefix prepended to every chunk before embedding
+     * (e.g. a title or breadcrumb), so each chunk carries enough context to be
+     * retrieved well on its own. Receives the full row.
+     */
+    contextPrefix?: (row: Row) => string;
+    /**
+     * Optional identifier of the embedding model, stored alongside each vector.
+     * Lets `refreshEmbeddings` detect and re-embed rows produced by a different
+     * model, and lets the doctor report mixed-model coverage. Purely advisory —
+     * Lattice never calls a model itself.
+     */
+    modelId?: string;
 }
 /**
  * Options for `Lattice.search()`.
@@ -1169,6 +1480,20 @@ interface SearchOptions {
      * score are excluded. Default: 0.
      */
     minScore?: number;
+    /**
+     * Optional second-stage reranker applied to the retrieved candidates before
+     * the top-K is returned. A cross-encoder reranker typically lifts precision
+     * over raw similarity. Bring your own — Lattice never calls a model. If it
+     * throws or returns nothing usable, the original similarity order is kept
+     * (graceful fallback). To rerank a larger pool than `topK`, set
+     * `rerankPoolSize`.
+     */
+    reranker?: RerankerFn;
+    /**
+     * Number of candidates to retrieve and hand to the `reranker` before slicing
+     * to `topK`. Defaults to `max(topK * 4, 20)`. Ignored when no reranker is set.
+     */
+    rerankPoolSize?: number;
 }
 /**
  * A single search result returned by `Lattice.search()`.
@@ -1178,6 +1503,17 @@ interface SearchResult {
     row: Row;
     /** Cosine similarity score (0–1). */
     score: number;
+    /**
+     * For a chunked embedding, the index of the chunk that produced the best
+     * score for this row. Absent for whole-row (unchunked) embeddings.
+     */
+    chunkIndex?: number;
+    /**
+     * For a chunked embedding, the text of the best-matching chunk — useful as a
+     * precise, low-token snippet to hand to a model. Absent for whole-row
+     * embeddings or when chunk content was not stored.
+     */
+    matchedContent?: string;
 }
 /**
  * Dimension scores passed to `Lattice.reward()`.
@@ -1264,6 +1600,19 @@ interface WritebackDefinition {
      */
     onReject?: (entry: unknown, result: WritebackValidationResult) => void;
 }
+/**
+ * Column projection for a query — return only the columns you need, so wide
+ * tables don't transfer (or decrypt) columns the caller will discard.
+ *
+ * - `string[]` — include exactly these columns.
+ * - `{ include }` — include exactly these columns.
+ * - `{ exclude }` — return all columns except these.
+ */
+type QueryProjection = string[] | {
+    include: string[];
+} | {
+    exclude: string[];
+};
 interface QueryOptions {
     /**
      * Equality filters — shorthand for `filters: [{ col, op: 'eq', val }]`.
@@ -1271,30 +1620,123 @@ interface QueryOptions {
      */
     where?: Record<string, unknown>;
     /**
-     * Advanced filter clauses with full operator support.
-     * Combined with `where` using AND.
+     * Advanced filter clauses with full operator support. May include recursive
+     * `or` / `and` groups (4.1+) and per-clause `jsonPath` extraction. Combined
+     * with `where` using AND.
      *
      * @example
      * ```ts
      * filters: [
      *   { col: 'priority',   op: 'gte',    val: 3 },
      *   { col: 'deleted_at', op: 'isNull'          },
-     *   { col: 'tag',        op: 'in',     val: ['bug', 'feature'] },
+     *   { or: [ { col: 'tag', op: 'eq', val: 'bug' }, { col: 'tag', op: 'eq', val: 'feature' } ] },
      * ]
      * ```
      */
-    filters?: Filter[];
+    filters?: FilterExpr[];
     orderBy?: string;
     orderDir?: 'asc' | 'desc';
     limit?: number;
     offset?: number;
+    /**
+     * Return only these columns (4.1+). See {@link QueryProjection}. Omitted
+     * columns are never transferred or decrypted.
+     */
+    projection?: QueryProjection;
+    /**
+     * Bounded-read cap (4.1+). When set and no explicit `limit` is given, the
+     * query reads at most `maxRows` rows and **throws `BoundedReadError`** if more
+     * exist — forcing the caller to paginate rather than silently loading an
+     * unbounded result set. Overrides `LatticeOptions.defaultMaxRows`. An explicit
+     * `limit` opts out (the caller has bounded the read themselves).
+     */
+    maxRows?: number;
+    /**
+     * Return one row per distinct value of these column(s) (4.1+). Compiles to
+     * Postgres `DISTINCT ON (...)` and an emulated SQLite `ROW_NUMBER()` window.
+     * Which row survives per group is determined by `orderBy`/`orderDir` (then the
+     * primary key as a deterministic tiebreak).
+     */
+    distinctOn?: string | string[];
+    /**
+     * Expand declared relations on each returned row (4.1+). Each name must be a
+     * key of the table's `relations`. A `belongsTo` relation attaches the single
+     * related row (or null); a `hasMany` relation attaches an array. Related rows
+     * are fetched in ONE batched `IN (...)` query per relation — no N+1.
+     */
+    include?: string[];
+}
+interface QueryPageOptions {
+    /** Equality filters (same as QueryOptions.where). */
+    where?: Record<string, unknown>;
+    /** Advanced filters (same as QueryOptions.filters). */
+    filters?: FilterExpr[];
+    /** Sort column the cursor walks. Defaults to the primary key. */
+    orderBy?: string;
+    orderDir?: 'asc' | 'desc';
+    /** Page size. Default 50. */
+    limit?: number;
+    /** Opaque cursor from a prior page's `nextCursor`. Omit for the first page. */
+    cursor?: string;
+    /** Return only these columns (see {@link QueryProjection}). */
+    projection?: QueryProjection;
+}
+interface QueryPageResult {
+    /** The page of rows. */
+    rows: Row[];
+    /** Opaque cursor for the next page, or null when this is the last page. */
+    nextCursor: string | null;
+    /** Whether more rows exist beyond this page. */
+    hasMore: boolean;
 }
 interface CountOptions {
     /** Equality filters (same as QueryOptions.where) */
     where?: Record<string, unknown>;
     /** Advanced filter clauses (same as QueryOptions.filters) */
-    filters?: Filter[];
+    filters?: FilterExpr[];
+}
+/** SQL aggregate function. */
+type AggregateFunction = 'count' | 'sum' | 'avg' | 'min' | 'max';
+/** One aggregate column in an {@link AggregateOptions}. */
+interface AggregateSpec {
+    /** The aggregate function to apply. */
+    fn: AggregateFunction;
+    /**
+     * Column to aggregate. Omit for `count` to mean `COUNT(*)`. Required for
+     * `sum`/`avg`/`min`/`max`.
+     */
+    col?: string;
+    /** Output key for this aggregate in each result row. */
+    as: string;
+    /** Apply `DISTINCT` inside the aggregate (e.g. `COUNT(DISTINCT col)`). */
+    distinct?: boolean;
+}
+/** A HAVING clause on an aggregate output (post-grouping filter). */
+interface AggregateHaving {
+    /** The `as` key of an aggregate in the same query. */
+    aggregate: string;
+    op: FilterOp;
+    val?: unknown;
 }
+interface AggregateOptions {
+    /** Columns to GROUP BY. Omit for a single grand-total row. */
+    groupBy?: string[];
+    /** The aggregate columns to compute (at least one). */
+    aggregates: AggregateSpec[];
+    /** Row-level equality filters applied before grouping. */
+    where?: Record<string, unknown>;
+    /** Row-level advanced filters applied before grouping. */
+    filters?: FilterExpr[];
+    /** Post-grouping filters on aggregate outputs. */
+    having?: AggregateHaving[];
+    /** Order the grouped rows by a groupBy column or an aggregate `as` key. */
+    orderBy?: string;
+    orderDir?: 'asc' | 'desc';
+    /** Max grouped rows to return. */
+    limit?: number;
+}
+/** One row of {@link Lattice.aggregate} output: groupBy columns + aggregate keys. */
+type AggregateResult = Record<string, unknown>;
 interface InitOptions {
     migrations?: Migration[];
     /**
@@ -2041,6 +2483,692 @@ declare class ProgressThrottle {
     force(event: RenderProgress): void;
 }
 
+/** Internal table that stores one embedding vector per (table, row, chunk). */
+declare const EMBEDDINGS_TABLE = "_lattice_embeddings";
+/**
+ * Ensure the internal embeddings storage table exists with the chunk-aware
+ * schema, migrating an older two-key (table_name, row_pk) layout forward.
+ *
+ * The embeddings table is a DERIVED cache — every vector can be recomputed from
+ * its source row — so when an older schema is detected it is rebuilt rather than
+ * preserved bit-for-bit. The migration is idempotent: once `chunk_index` exists
+ * the function is a no-op.
+ */
+declare function ensureEmbeddingsTable(adapter: StorageAdapter): Promise<void>;
+/** Concatenate the configured fields of a row into a single embeddable string. */
+declare function concatRowText(row: Row, fields: string[]): string;
+/**
+ * Compute and store the embedding(s) for a row. When the config supplies a
+ * `chunker`, the row text is split and each chunk is embedded + stored under its
+ * own `chunk_index`; otherwise the whole text is one chunk (index 0). The row's
+ * prior chunks are replaced atomically-per-row (delete then insert).
+ */
+declare function storeEmbedding(adapter: StorageAdapter, table: string, pk: string, row: Row, config: EmbeddingsConfig): Promise<void>;
+/** Remove all stored embedding chunks for a row. */
+declare function removeEmbedding(adapter: StorageAdapter, table: string, pk: string): Promise<void>;
+/** Cosine similarity between two vectors. */
+declare function cosineSimilarity(a: number[], b: number[]): number;
+/**
+ * Error thrown when a stored vector's dimensionality does not match the query
+ * vector's — almost always a sign the embedding model changed without a
+ * re-embed. Surfaced loudly rather than silently scoring mismatched vectors.
+ */
+declare class EmbeddingDimensionMismatchError extends Error {
+    readonly table: string;
+    readonly expected: number;
+    readonly found: number;
+    constructor(table: string, expected: number, found: number);
+}
+/**
+ * Search rows by semantic similarity. Uses a native vector index (pgvector) when
+ * one exists for the table; otherwise an in-process cosine scan over the stored
+ * chunk vectors. Either way results respect `deleted_at IS NULL` on the base
+ * table and are de-duplicated to the best-scoring chunk per row.
+ */
+declare function searchByEmbedding(adapter: StorageAdapter, table: string, queryText: string, config: EmbeddingsConfig, topK: number, minScore: number, pkColumn?: string): Promise<SearchResult[]>;
+interface RefreshEmbeddingsOptions {
+    /** Only re-embed rows whose stored model differs from `config.modelId`. */
+    staleModelOnly?: boolean;
+    /** Embed rows that have no stored embedding. Default true. */
+    backfillMissing?: boolean;
+    /** Re-embed rows whose source changed since `embedded_at` (caller decides via `changedSince`). */
+    changedSince?: string;
+    /** Page size for the base-table scan. Default 500. */
+    batchSize?: number;
+}
+interface EmbeddingRefreshResult {
+    /** Rows that were (re-)embedded. */
+    embedded: number;
+    /** Rows skipped because they were already current. */
+    skipped: number;
+    /** Orphaned embeddings removed (their source row no longer exists). */
+    removed: number;
+}
+/**
+ * Backfill / re-embed a table's vectors incrementally — embed only what's
+ * missing or stale, rather than re-embedding everything. Honors `deleted_at`
+ * and sweeps embeddings whose source row is gone.
+ */
+declare function refreshEmbeddings(adapter: StorageAdapter, table: string, config: EmbeddingsConfig, pkColumn?: string, opts?: RefreshEmbeddingsOptions): Promise<EmbeddingRefreshResult>;
+
+/**
+ * Ranking signals — lightweight, deterministic boosts applied to a retrieval
+ * score from columns already on the row, no model required. Pure relevance
+ * (vector/FTS/hybrid) ignores how fresh, how rewarded, or how referenced a row
+ * is; these signals fold that business context back into the ranking.
+ *
+ * Each signal yields a value in [0, 1]; the combined boost is a weighted sum,
+ * and the caller multiplies the base score by `(1 + boost)` so a strong signal
+ * lifts an already-relevant row without drowning relevance entirely.
+ */
+
+/** Exponential recency decay: 1.0 at age 0, 0.5 at one half-life, → 0 with age. */
+interface RecencySignal {
+    /** Timestamp column (ISO-8601 string or epoch ms). */
+    column: string;
+    /** Half-life in days — the age at which the boost halves. */
+    halfLifeDays: number;
+    /** Weight of this signal in the combined boost. */
+    weight: number;
+}
+/** Reward signal: saturating boost from a `_reward_total`-style column. */
+interface RewardSignal {
+    /** Column holding the cumulative reward. Default `_reward_total`. */
+    column?: string;
+    /** Weight of this signal in the combined boost. */
+    weight: number;
+}
+/**
+ * Backlink signal: a saturating boost from an inbound-reference-count column. A
+ * row referenced by many others is more central/authoritative, so it ranks higher.
+ */
+interface BacklinkSignal {
+    /** Column holding the inbound reference count. Default `_backlink_count`. */
+    column?: string;
+    /** Weight of this signal in the combined boost. */
+    weight: number;
+}
+/** A custom per-row signal returning a value in [0, 1]. */
+interface CustomSignal {
+    fn: (row: Row) => number;
+    weight: number;
+}
+interface RankingOptions {
+    recency?: RecencySignal;
+    reward?: RewardSignal;
+    backlink?: BacklinkSignal;
+    custom?: CustomSignal;
+    /**
+     * Reference time (epoch ms) for recency decay. Defaults to `Date.now()`.
+     * Pass it for deterministic ranking/tests.
+     */
+    now?: number;
+}
+/** Recency boost in [0, 1] for a row's timestamp column. */
+declare function recencyBoost(row: Row, signal: RecencySignal, nowMs: number): number;
+/** Saturating reward boost in [0, 1): r / (1 + r) for non-negative reward. */
+declare function rewardBoost(row: Row, signal: RewardSignal): number;
+/** Saturating backlink boost in [0, 1): b / (1 + b) for a non-negative count. */
+declare function backlinkBoost(row: Row, signal: BacklinkSignal): number;
+/**
+ * Combined, weighted ranking boost for a row (≥ 0). Multiply a base relevance
+ * score by `(1 + rankingBoost(...))` to apply it.
+ */
+declare function rankingBoost(row: Row, opts: RankingOptions): number;
+
+/**
+ * Hybrid search — fuse semantic (vector) retrieval with lexical (full-text)
+ * retrieval so the result set has both the recall of embeddings and the
+ * precision of exact-term matching. Neither arm alone is enough: vectors miss
+ * rare exact tokens (names, ids, codes), keywords miss paraphrases.
+ *
+ * Fusion is Reciprocal Rank Fusion (RRF): a document's score is the sum over the
+ * arms it appears in of `1 / (k + rank)`, with `k = 60` by default. RRF needs
+ * only the per-arm *ranks*, so the two arms' incomparable score scales (cosine
+ * similarity vs ts_rank/bm25) never have to be normalized against each other.
+ *
+ * Optional post-fusion stages: deterministic ranking signals (recency / reward /
+ * custom) and a bring-your-own reranker. Results carry a full score breakdown
+ * for `--explain`.
+ */
+
+interface HybridSearchOptions {
+    /** Final number of results. Default 10. */
+    topK?: number;
+    /** RRF constant — larger flattens the rank contribution. Default 60. */
+    rrfK?: number;
+    /** Candidates pulled from each arm before fusion. Default max(topK*4, 20). */
+    poolSize?: number;
+    /** Minimum cosine similarity for the vector arm. Default 0. */
+    minVectorScore?: number;
+    /** Embeddings config — enables the vector arm. Omit for FTS-only fusion. */
+    embeddingsConfig?: EmbeddingsConfig;
+    /** Primary-key column of the base table. Default 'id'. */
+    pkColumn?: string;
+    /** Deterministic post-fusion ranking signals. */
+    ranking?: RankingOptions;
+    /** Optional reranker over the fused top candidates (graceful fallback). */
+    reranker?: RerankerFn;
+}
+/** Per-result score breakdown (the `--explain` payload). */
+interface HybridScoreBreakdown {
+    /** Final score used for ordering. */
+    final: number;
+    /** Reciprocal-rank-fusion score before ranking/rerank. */
+    rrf: number;
+    /** 1-based rank in the vector arm, or null if absent. */
+    vectorRank: number | null;
+    /** Cosine similarity from the vector arm, or null. */
+    vectorScore: number | null;
+    /** 1-based rank in the FTS arm, or null if absent. */
+    ftsRank: number | null;
+    /** FTS relevance score (ts_rank / -bm25), or null. */
+    ftsScore: number | null;
+    /** Multiplicative ranking boost applied (0 when no ranking signals). */
+    rankingBoost: number;
+    /** Reranker score, when a reranker actually scored this row. */
+    rerankerScore?: number;
+}
+interface HybridSearchResult {
+    row: Row;
+    score: number;
+    explain: HybridScoreBreakdown;
+    /** Best-matching chunk text from the vector arm, when available. */
+    matchedContent?: string;
+}
+/**
+ * Run a hybrid (vector + full-text) search over one table and return fused,
+ * optionally ranked + reranked results with a per-result score breakdown.
+ * Soft-deleted rows are excluded (both arms honor `deleted_at`).
+ */
+declare function hybridSearch(adapter: StorageAdapter, table: string, query: string, opts?: HybridSearchOptions): Promise<HybridSearchResult[]>;
+
+/**
+ * Graph-augmented retrieval.
+ *
+ * Pure similarity retrieval treats every row as an island. Real knowledge is
+ * relational: a document cites another, a task blocks a task, a person belongs to
+ * a team. A typed-edge graph over the rows lets retrieval be *relationship-aware*
+ * — traverse from an anchor entity to its neighborhood, and boost results that
+ * are graph-connected to the things you already care about.
+ *
+ * Edges live in one internal `__lattice_edges` table (GUI-hidden by prefix).
+ * They can be added explicitly, or extracted with **zero LLM** from existing
+ * foreign-key columns. Traversal is a **bounded BFS** with hard caps on depth and
+ * visited-node count, so a dense or cyclic graph can never blow up memory.
+ */
+
+/** Absolute ceiling on traversal depth — a hard guard against runaway BFS. */
+declare const MAX_TRAVERSAL_DEPTH = 5;
+/** Default ceiling on visited nodes per traversal. */
+declare const DEFAULT_MAX_NODES = 10000;
+interface GraphNode {
+    table: string;
+    id: string;
+}
+interface GraphEdge {
+    srcTable: string;
+    srcId: string;
+    dstTable: string;
+    dstId: string;
+    /** Edge type/label (e.g. 'cites', 'blocks', 'member_of'). */
+    type: string;
+    /** Edge weight (default 1). Higher = stronger relationship. */
+    weight?: number;
+}
+type TraversalDirection = 'out' | 'in' | 'both';
+interface TraversalOptions {
+    /** Max BFS depth (clamped to MAX_TRAVERSAL_DEPTH). Default 2. */
+    maxDepth?: number;
+    /** Follow out-edges, in-edges, or both. Default 'out'. */
+    direction?: TraversalDirection;
+    /** Restrict to these edge types. */
+    edgeTypes?: string[];
+    /** Stop after visiting this many nodes (cycle/blowup guard). Default 10000. */
+    maxNodes?: number;
+}
+interface TraversalNode {
+    node: GraphNode;
+    /** BFS depth from the start node (start = 0). */
+    depth: number;
+}
+interface GraphTraversalResult {
+    start: GraphNode;
+    nodes: TraversalNode[];
+    edges: GraphEdge[];
+    /** True if a cap (depth or node count) stopped the traversal early. */
+    truncated: boolean;
+}
+/** Ensure the internal edges table exists (idempotent, GUI-hidden by prefix). */
+declare function ensureEdgesTable(adapter: StorageAdapter): Promise<void>;
+/** Add (upsert) one edge. */
+declare function addEdge(adapter: StorageAdapter, edge: GraphEdge): Promise<void>;
+/** Add many edges (each upserted). */
+declare function addEdges(adapter: StorageAdapter, edges: GraphEdge[]): Promise<void>;
+/** Remove one edge (all matching types when `type` omitted). */
+declare function removeEdge(adapter: StorageAdapter, edge: Omit<GraphEdge, 'weight' | 'type'> & {
+    type?: string;
+}): Promise<void>;
+/** Direct neighbors of a node (one hop), in the given direction + type filter. */
+declare function neighbors(adapter: StorageAdapter, node: GraphNode, opts?: {
+    direction?: TraversalDirection;
+    edgeTypes?: string[];
+}): Promise<GraphEdge[]>;
+/**
+ * Bounded breadth-first traversal from `start`. Hard caps: depth is clamped to
+ * {@link MAX_TRAVERSAL_DEPTH}, and the visited set is capped at `maxNodes`. A
+ * visited set prevents revisiting nodes in cyclic graphs.
+ */
+declare function traverse(adapter: StorageAdapter, start: GraphNode, opts?: TraversalOptions): Promise<GraphTraversalResult>;
+interface ExtractEdgesSpec {
+    /** Source table holding the foreign key. */
+    srcTable: string;
+    /** FK column on the source table. */
+    fkColumn: string;
+    /** Table the FK points at. */
+    dstTable: string;
+    /** Edge type to label the extracted edges. Default `<fkColumn>`. */
+    type?: string;
+    /** Source-table primary key. Default 'id'. */
+    pkColumn?: string;
+}
+/**
+ * Zero-LLM edge extraction: derive `srcTable[pk] --type--> dstTable[fk]` edges
+ * from a foreign-key column. Deterministic; no model. Returns the edge count.
+ */
+declare function extractEdgesFromColumn(adapter: StorageAdapter, spec: ExtractEdgesSpec): Promise<number>;
+/**
+ * Adjacency boost — re-score retrieval results by their graph connectivity to a
+ * set of anchor nodes (e.g. the entities in the user's current context). A
+ * result adjacent (within `maxDepth`) to an anchor is boosted by the edge weight
+ * decayed by hop distance, scaled by `weight`. This makes retrieval
+ * relationship-aware: things related to what you already care about rank higher.
+ *
+ * Returns a new array sorted by the boosted score; pure (no DB writes).
+ */
+interface GraphBoostOptions {
+    /** Anchor nodes whose neighborhood is preferred. */
+    anchors: GraphNode[];
+    /** Table the results belong to (results are `{ id, score }`). */
+    resultTable: string;
+    /** Boost weight applied to the adjacency signal. Default 0.5. */
+    weight?: number;
+    /** Hop radius from anchors to consider. Clamped to MAX_TRAVERSAL_DEPTH. Default 1. */
+    maxDepth?: number;
+    /** Edge direction from the anchor's perspective. Default 'both'. */
+    direction?: TraversalDirection;
+    edgeTypes?: string[];
+}
+interface GraphBoostResult<T> {
+    item: T;
+    baseScore: number;
+    boostedScore: number;
+    /** Min hop distance to an anchor (Infinity if unreachable). */
+    hops: number;
+}
+declare function graphAdjacencyBoost<T extends {
+    id: string;
+    score: number;
+}>(adapter: StorageAdapter, results: T[], opts: GraphBoostOptions): Promise<GraphBoostResult<T>[]>;
+
+/**
+ * Seamless cloud file-byte access — an in-database presigned-URL broker.
+ *
+ * After joining a cloud via invite, a scoped member connects directly to the
+ * cloud's Postgres as their own least-privilege role. They can SELECT a `files`
+ * row they're allowed to see, but they hold no S3 credential, so fetching the
+ * bytes would otherwise fail. This installs a `SECURITY DEFINER` function that,
+ * **inside Postgres** (the only place the owner's key lives, away from members),
+ * gates on the member's row-visibility and computes a short-lived AWS SigV4
+ * presigned URL for exactly that object — so the member fetches/uploads bytes
+ * with zero config and never holds a key.
+ *
+ * Why sign in plpgsql: the secret must never leave the database for a member's
+ * process, so a Node-side presign is out — the signature is computed in-DB via
+ * `pgcrypto` HMAC-SHA256. Correctness of the SigV4 chain is verified against
+ * AWS's published test vectors (no real S3 needed).
+ *
+ * Postgres + a cloud only. SQLite is single-user with local bytes — no-op.
+ */
+
+/** Owner-only table holding the least-privilege S3 key. Never member-granted. */
+declare const S3_SECRET_TABLE = "__lattice_cloud_s3_secret";
+/**
+ * SQL that installs the presigner: `pgcrypto`, the owner-only secret table, the
+ * SigV4 signer, and the visibility-gated `lattice_presign_file` wrapper. All
+ * `SECURITY DEFINER` bodies are search_path-pinned by the caller.
+ *
+ * `lattice_aws_sigv4_presign(...)` is parameterized on the date/time so it can be
+ * verified deterministically against AWS test vectors; `lattice_presign_file`
+ * derives the date from `now()` at call time.
+ */
+declare function filePresignSql(): string;
+/**
+ * Install the presigner into the current Postgres schema. No-op on SQLite.
+ * `schema` is used to pin the `SECURITY DEFINER` search_path (reuse
+ * {@link cloudSchema} to resolve it) — required to prevent a member from
+ * shadowing `files` / the visibility helpers via `pg_temp`.
+ */
+declare function installFilePresigner(adapter: StorageAdapter, schema: string): Promise<void>;
+interface CloudS3Secret {
+    bucket: string;
+    region: string;
+    accessKey: string;
+    secretKey: string;
+    /** Optional key prefix applied to every object. */
+    prefix?: string;
+    /** Optional host override for S3-compatible stores. */
+    endpoint?: string;
+}
+/** Store/replace the owner's least-privilege S3 key (owner-only; never granted). */
+declare function setCloudS3Secret(adapter: StorageAdapter, secret: CloudS3Secret): Promise<void>;
+/**
+ * Grant a member group EXECUTE on the presigner (so every current + future
+ * member can presign their own visible files), WITHOUT granting any access to
+ * the owner-only secret table. Idempotent.
+ */
+declare function grantPresignerToMemberGroup(adapter: StorageAdapter, memberGroup: string): Promise<void>;
+/** Whether the presigner function is installed in the current schema. */
+declare function hasFilePresigner(adapter: StorageAdapter): Promise<boolean>;
+
+/**
+ * Retrieval evaluation — measure the quality of any ranked-retrieval function
+ * against a labeled query set, with the standard information-retrieval metrics:
+ * Precision@k, Recall@k, Mean Reciprocal Rank (MRR), normalized Discounted
+ * Cumulative Gain (nDCG@k), and Mean Average Precision (MAP).
+ *
+ * The evaluator is deliberately decoupled from any specific search
+ * implementation: you hand it a {@link Retriever} — a function that maps a query
+ * string to a best-first list of row ids — plus the ground-truth relevant ids
+ * per query. That makes it usable to grade semantic search, full-text search, a
+ * hybrid fusion, a graph-augmented retriever, or an external service, and to
+ * regression-gate any of them in CI so an upgrade can't silently lower quality.
+ *
+ * All metric math is computed in-process from the ranked id lists; nothing here
+ * touches the database, so it is dialect-agnostic and side-effect free.
+ */
+/**
+ * A graded relevance label. `gain` is the graded usefulness of the row for the
+ * query (used by nDCG); omit it for binary relevance (treated as gain 1).
+ */
+interface RelevanceLabel {
+    id: string;
+    /** Graded relevance gain (default 1). Higher = more useful. */
+    gain?: number;
+}
+/**
+ * A single labeled evaluation query: the query text plus the ground-truth set
+ * of ids that *should* be retrieved. Order of `relevant` is irrelevant — it is
+ * a set; ranking quality is judged against the order the retriever returns.
+ */
+interface EvalQuery {
+    /** Stable identifier for per-query reporting. Defaults to the query text. */
+    id?: string;
+    /** Natural-language query text passed to the retriever. */
+    query: string;
+    /** Ground-truth relevant ids — bare ids (binary) or graded labels. */
+    relevant: string[] | RelevanceLabel[];
+}
+/**
+ * Maps a query to a ranked, best-first list of row ids. May be sync or async.
+ * Returning more than `k` ids is fine — the evaluator applies the cutoff.
+ */
+type Retriever = (query: string) => Promise<string[]> | string[];
+interface RetrievalEvalOptions {
+    /** Primary cutoff for P@k / Recall@k / nDCG@k. Default 10. */
+    k?: number;
+    /**
+     * Additional cutoffs to also report (e.g. `[1, 3, 5, 10]`). Each appears in
+     * {@link RetrievalEvalSummary.byK}. The primary `k` is always reported.
+     */
+    ks?: number[];
+}
+/** Per-query metric breakdown. */
+interface PerQueryEval {
+    id: string;
+    query: string;
+    /** Relevant ids found in the top-k, divided by k. */
+    precisionAtK: number;
+    /** Relevant ids found in the top-k, divided by total relevant. */
+    recallAtK: number;
+    /** 1 / (rank of the first relevant id), 0 if none were returned. */
+    reciprocalRank: number;
+    /** DCG@k / ideal-DCG@k, in [0, 1]. */
+    ndcgAtK: number;
+    /** Average precision over the full returned list (the AP that MAP averages). */
+    averagePrecision: number;
+    /** Number of ids the retriever returned. */
+    retrieved: number;
+    /** Number of ground-truth relevant ids. */
+    relevantTotal: number;
+}
+/** Aggregate metrics across the whole query set, plus per-query detail. */
+interface RetrievalEvalSummary {
+    /** The primary cutoff used for the top-level aggregate fields. */
+    k: number;
+    /** Number of queries evaluated. */
+    queryCount: number;
+    /** Mean Precision@k. */
+    precisionAtK: number;
+    /** Mean Recall@k. */
+    recallAtK: number;
+    /** Mean Reciprocal Rank. */
+    mrr: number;
+    /** Mean nDCG@k. */
+    ndcgAtK: number;
+    /** Mean Average Precision. */
+    map: number;
+    /** Per-cutoff means, present when `ks` is supplied (always includes `k`). */
+    byK?: Record<number, {
+        precisionAtK: number;
+        recallAtK: number;
+        ndcgAtK: number;
+    }>;
+    /** Per-query metrics, in input order. */
+    perQuery: PerQueryEval[];
+}
+/**
+ * Evaluate a retriever against a labeled query set.
+ *
+ * @throws Error if `queries` is empty — an eval over no queries would silently
+ *   report a meaningless "0 across the board", so it fails loudly instead.
+ */
+declare function evaluateRetrieval(queries: EvalQuery[], retriever: Retriever, opts?: RetrievalEvalOptions): Promise<RetrievalEvalSummary>;
+/**
+ * Compare a candidate summary against a baseline and report regressions beyond
+ * a tolerance. Designed to drive a CI gate: a retrieval change that lowers any
+ * headline metric by more than `tolerance` fails the build.
+ */
+interface EvalRegression {
+    metric: 'precisionAtK' | 'recallAtK' | 'mrr' | 'ndcgAtK' | 'map';
+    baseline: number;
+    candidate: number;
+    delta: number;
+}
+declare function detectRetrievalRegressions(baseline: RetrievalEvalSummary, candidate: RetrievalEvalSummary, tolerance?: number): EvalRegression[];
+
+/**
+ * Retrieval health diagnostics — a read-only `doctor` for a Lattice database's
+ * search surface. It reports, without mutating anything:
+ *
+ *   - which retrieval extensions are available/installed (FTS5, pgvector,
+ *     sqlite-vec, pg_trgm),
+ *   - per-table full-text and embedding coverage (how many base rows are
+ *     actually indexed/embedded vs how many exist),
+ *   - staleness and gaps surfaced as severity-ranked issues.
+ *
+ * The point is proactive detection: index or embedding drift is otherwise
+ * invisible until a user notices bad results. `diagnoseRetrieval` surfaces it
+ * first, and `lattice doctor` puts it one command away. Everything here is a
+ * `SELECT`/introspection — no DDL, no writes, both dialects.
+ */
+
+type HealthSeverity = 'info' | 'warning' | 'error';
+type HealthIssueKind = 'fts_missing' | 'fts_stale' | 'fts_empty' | 'embedding_missing' | 'embedding_stale' | 'extension_missing' | 'dimension_mismatch' | 'index_stale';
+interface RetrievalHealthIssue {
+    /** Table the issue concerns, or undefined for a global/extension issue. */
+    table?: string;
+    kind: HealthIssueKind;
+    severity: HealthSeverity;
+    message: string;
+    /** Optional remediation hint. */
+    hint?: string;
+}
+/** Availability of the retrieval extensions on this connection. */
+interface ExtensionAvailability {
+    /** SQLite compiled with FTS5. */
+    fts5?: boolean;
+    /** SQLite sqlite-vec extension loaded (vec_version() resolves). */
+    sqliteVec?: boolean;
+    /** Postgres pgvector installed (CREATE EXTENSION vector done). */
+    pgvectorInstalled?: boolean;
+    /** Postgres pgvector available to install. */
+    pgvectorAvailable?: boolean;
+    /** Postgres pg_trgm installed. */
+    pgTrgmInstalled?: boolean;
+}
+interface TableHealth {
+    table: string;
+    /** Non-deleted base rows. */
+    rowCount: number;
+    /** Rows present in the FTS index, when one exists. */
+    ftsIndexed?: number;
+    /** ftsIndexed / rowCount, in [0, 1]. */
+    ftsCoverage?: number;
+    /** Embeddings stored for this table. */
+    embeddingCount?: number;
+    /** embeddingCount / rowCount, in [0, 1]. */
+    embeddingCoverage?: number;
+    issues: RetrievalHealthIssue[];
+}
+interface RetrievalHealthReport {
+    dialect: 'sqlite' | 'postgres';
+    extensions: ExtensionAvailability;
+    tables: TableHealth[];
+    /** Global (non-table) issues, e.g. a missing extension. */
+    issues: RetrievalHealthIssue[];
+    /** True when no `error`-severity issue exists anywhere. */
+    healthy: boolean;
+}
+/** What a table is expected to support, so gaps can be flagged as errors. */
+interface RetrievalHealthSpec {
+    table: string;
+    /** Table opted into full-text search. */
+    expectFts?: boolean;
+    /** Table opted into embeddings. */
+    expectEmbeddings?: boolean;
+    /** Known embedding dimension (reserved for dimension checks). */
+    embeddingDim?: number;
+}
+interface DiagnoseOptions {
+    /**
+     * Tables to diagnose with their expected capabilities. When omitted, the
+     * doctor reports extension availability and embedding coverage for every
+     * table that already has stored embeddings, but cannot flag "missing"
+     * (it has no expectations to compare against).
+     */
+    tables?: RetrievalHealthSpec[];
+    /**
+     * Coverage below which a partially-indexed/embedded table is flagged stale.
+     * Default 1 — anything short of full coverage is a `warning`.
+     */
+    staleThreshold?: number;
+}
+/**
+ * Produce a retrieval health report for the given connection.
+ *
+ * Read-only and dialect-agnostic. Pass `tables` (with expectations) to get
+ * missing-index / missing-embedding errors; omit it for a capability + coverage
+ * snapshot only.
+ */
+declare function diagnoseRetrieval(adapter: StorageAdapter, opts?: DiagnoseOptions): Promise<RetrievalHealthReport>;
+/** Render a report as a human-readable multi-line string (for `lattice doctor`). */
+declare function formatHealthReport(report: RetrievalHealthReport): string;
+
+/**
+ * Reproducible retrieval benchmark harness.
+ *
+ * Produces the speed-to-answer numbers a buyer would benchmark you on —
+ * p50/p95/p99 latency for filtered query, full-text search, vector search, and
+ * SQL aggregation — plus ingest throughput, all on synthetic data at a
+ * configurable scale, on either dialect. It exercises the *real* code paths
+ * (the same `fullTextSearch` / `searchByEmbedding` / SQL the library serves in
+ * production), so the numbers are honest, and it ships in the package so the
+ * same harness that gates regressions in CI can be re-run by anyone.
+ *
+ * Default scale is small so a CI SLO gate runs in seconds; override via the
+ * `scale` option (or the `LATTICE_BENCH_ROWS` / `LATTICE_BENCH_QUERIES` /
+ * `LATTICE_BENCH_DIM` env vars) to reproduce the large-n published numbers.
+ *
+ * The default embedder is a dependency-free deterministic token-hash vector —
+ * it measures latency/throughput honestly without pulling in a model. Pass your
+ * own `embed` to benchmark with real vectors.
+ */
+
+interface LatencyStats {
+    count: number;
+    min: number;
+    max: number;
+    mean: number;
+    p50: number;
+    p95: number;
+    p99: number;
+}
+interface BenchmarkScale {
+    /** Rows inserted into the synthetic table. */
+    rows: number;
+    /** Distinct queries timed for each measured operation. */
+    queries: number;
+    /** Embedding dimensionality. */
+    dim: number;
+}
+interface BenchmarkReport {
+    dialect: 'sqlite' | 'postgres';
+    scale: BenchmarkScale;
+    ingest: {
+        rows: number;
+        ms: number;
+        rowsPerSec: number;
+    };
+    query: LatencyStats;
+    fts: LatencyStats;
+    vector: LatencyStats;
+    aggregate: LatencyStats;
+    /** Peak resident-set bytes observed during the vector-search phase. */
+    peakRssBytes: number;
+    /**
+     * Whether the `vector` numbers reflect the NATIVE index (pgvector/sqlite-vec)
+     * or the in-process O(n) scan fallback. `false` means no extension was present,
+     * so `vector.p95` is the scan baseline — not the indexed number. Surfaced so a
+     * published benchmark can never present the scan as the index.
+     */
+    vectorIndexed: boolean;
+}
+interface BenchmarkOptions {
+    scale?: Partial<BenchmarkScale>;
+    /** Embedder; defaults to a deterministic dependency-free token-hash vector. */
+    embed?: (text: string) => Promise<number[]>;
+    /** Table name for the synthetic data (dropped + recreated). Default `_lattice_bench`. */
+    table?: string;
+}
+declare function percentile(sortedAsc: number[], p: number): number;
+declare function latencyStats(samples: number[]): LatencyStats;
+/**
+ * Run the benchmark against an adapter. Creates a synthetic table, populates it,
+ * builds an FTS index + embeddings, times each operation, and drops the table.
+ */
+declare function benchmarkRetrieval(adapter: StorageAdapter, opts?: BenchmarkOptions): Promise<BenchmarkReport>;
+/** A service-level objective for a single latency metric, in milliseconds. */
+interface RetrievalSlo {
+    metric: 'query.p95' | 'fts.p95' | 'vector.p95' | 'aggregate.p95';
+    maxMs: number;
+}
+interface SloViolation extends RetrievalSlo {
+    observedMs: number;
+}
+/** Check a report against SLOs; returns the violations (empty = all pass). */
+declare function checkSlos(report: BenchmarkReport, slos: RetrievalSlo[]): SloViolation[];
+
 /**
  * Thrown by Lattice.seed when onUnresolvedLink: 'throw' is set and one or more
  * junction links could not be created because their target rows did not
@@ -2126,6 +3254,18 @@ declare class Lattice {
     private readonly _writeHooks;
     /** Optional cap on per-row payload bytes; see LatticeOptions.maxRowBytes. */
     private _maxRowBytes;
+    /** Optional default bounded-read cap; see LatticeOptions.defaultMaxRows. */
+    private _defaultMaxRows;
+    /** table → immutable provenance column names (governance: P-PROV). */
+    private readonly _provenanceCols;
+    /** table → default trust state for new rows (governance: P-TRUST). */
+    private readonly _trustDefault;
+    /** table → computed-column specs + recompute order + dep set (P-VIEW). */
+    private readonly _computed;
+    /** table → materialized rollup specs (P-VIEW). */
+    private readonly _rollups;
+    /** source table → parents whose rollup it feeds (for incremental recompute). */
+    private readonly _rollupSources;
     /**
      * Reject the row if its payload exceeds `_maxRowBytes`. Cost is dominated
      * by Buffer.byteLength() on string columns; we skip numbers/booleans
@@ -2350,6 +3490,12 @@ declare class Lattice {
      * inside a GUC-scoped transaction.
      */
     private _prepareInsert;
+    /**
+     * Stamp governance defaults at insert time: auto-set `ingested_at` for a
+     * provenance table (when not supplied) and the default `_trust_state` for a
+     * trust table. Returns a shallow copy; a no-op for tables without governance.
+     */
+    private _applyGovernanceDefaults;
     /** Post-insert side effects (changelog, audit, write hooks, embedding sync),
      *  identical for the plain and force-visibility insert paths. */
     private _afterInsert;
@@ -2363,6 +3509,31 @@ declare class Lattice {
     upsert(table: string, row: Row): Promise<string>;
     upsertBy(table: string, col: string, val: unknown, row: Row): Promise<string>;
     update(table: string, id: PkLookup, row: Partial<Row>, provenance?: ChangeProvenance): Promise<void>;
+    /** Compute a table's computed columns from a (full) row, returning the merged row. */
+    private _applyComputedColumns;
+    /**
+     * On update, if the changed columns include any computed-column dependency,
+     * fetch + decrypt the current row, merge the changes, recompute the computed
+     * columns, and fold them into the update payload. No-op otherwise.
+     */
+    private _recomputeComputedOnUpdate;
+    /** Recompute parent rollup(s) for the FK values carried on a source row. */
+    private _propagateRollupsFromRow;
+    /** Recompute the parent rollup(s) fed by a changed source row (fetched by id). */
+    private _propagateRollups;
+    /** Recompute a single rollup cell for one parent row. */
+    private _recomputeRollupCell;
+    /**
+     * Recompute all computed columns for every row of a table (a full pass). Use
+     * after a bulk import that bypassed the per-row recompute, or after changing a
+     * computed definition. Requires `computed` config.
+     */
+    refreshComputedColumns(table: string): Promise<number>;
+    /**
+     * Recompute all materialized rollups for every row of a table (a full,
+     * authoritative pass). Requires `materializedRollups` config.
+     */
+    refreshMaterializedRollups(table: string): Promise<number>;
     /**
      * Update a row and return the full updated row. Equivalent to `update()`
      * followed by `get()`.
@@ -2485,8 +3656,147 @@ declare class Lattice {
      * @returns Matching rows with similarity scores, sorted best-first.
      */
     search(table: string, query: string, opts?: SearchOptions): Promise<SearchResult[]>;
+    /**
+     * Hybrid search — fuse semantic (vector) and full-text retrieval with
+     * Reciprocal Rank Fusion, with optional deterministic ranking signals
+     * (recency / reward / custom) and an optional reranker. Returns fused results
+     * with a per-result score breakdown (`explain`). The vector arm is enabled
+     * when the table has `embeddings` config; otherwise it is full-text only.
+     */
+    hybridSearch(table: string, query: string, opts?: Omit<HybridSearchOptions, 'embeddingsConfig' | 'pkColumn'>): Promise<HybridSearchResult[]>;
+    /**
+     * Backfill / re-embed a table's vectors incrementally — embed only rows that
+     * are missing, model-stale, or changed since a timestamp, sweeping embeddings
+     * whose source row is gone. Honors `deleted_at`. Requires `embeddings` config.
+     */
+    refreshEmbeddings(table: string, opts?: RefreshEmbeddingsOptions): Promise<EmbeddingRefreshResult>;
+    /**
+     * Build (or rebuild) a native vector index (pgvector / sqlite-vec) for `table`
+     * from the stored embeddings, so semantic search uses an indexed
+     * approximate-nearest-neighbor lookup instead of an in-process scan. Returns
+     * the number of vectors indexed; a no-op (returns 0) when no native vector
+     * extension is available, unless `requireExtension` is set. Requires
+     * `embeddings` config (to determine the vector dimension).
+     */
+    buildVectorIndex(table: string, requireExtension?: boolean): Promise<number>;
+    /**
+     * Evaluate a retriever against a labeled query set, returning the standard IR
+     * metrics (P@k / Recall@k / MRR / nDCG@k / MAP). The retriever is any
+     * `(query) => rankedRowIds` function, so this grades semantic search,
+     * full-text search, a hybrid fusion, or an external service — and can gate
+     * retrieval-quality regressions in CI.
+     */
+    evaluateRetrieval(queries: EvalQuery[], retriever: Retriever, opts?: RetrievalEvalOptions): Promise<RetrievalEvalSummary>;
+    /**
+     * Diagnose the database's retrieval health: extension availability plus
+     * per-table full-text and embedding coverage, with gaps/staleness surfaced as
+     * severity-ranked issues. Read-only. When `tables` is omitted, the expectations
+     * are derived from each registered table's `fts` / `embeddings` config.
+     */
+    diagnoseRetrieval(opts?: {
+        tables?: RetrievalHealthSpec[];
+    }): Promise<RetrievalHealthReport>;
+    /**
+     * Run the reproducible retrieval benchmark against this connection and return
+     * latency percentiles + ingest throughput. Default scale is small (CI-fast);
+     * pass `scale` (or set LATTICE_BENCH_* env vars) to reproduce large-n numbers.
+     */
+    benchmarkRetrieval(opts?: BenchmarkOptions): Promise<BenchmarkReport>;
     query(table: string, opts?: QueryOptions): Promise<Row[]>;
+    /**
+     * Keyset (cursor) pagination — stable, index-friendly paging that stays fast
+     * arbitrarily deep into a result set (unlike OFFSET, which scans-and-discards).
+     * Returns a page plus an opaque `nextCursor` (null on the last page).
+     */
+    queryPage(table: string, opts?: QueryPageOptions): Promise<QueryPageResult>;
+    /**
+     * Attach declared relations to each row in `rows` (mutates in place). Each
+     * relation is fetched in ONE batched `IN (...)` query — no N+1. `belongsTo`
+     * attaches a single row (or null); `hasMany` attaches an array.
+     */
+    private _expandRelations;
     count(table: string, opts?: CountOptions): Promise<number>;
+    /**
+     * SQL-side aggregation — `COUNT`/`SUM`/`AVG`/`MIN`/`MAX` with optional
+     * `GROUP BY` and `HAVING`, computed in the database so only the grouped result
+     * rows transfer (never the underlying rows). Returns one object per group with
+     * the groupBy columns and each aggregate under its `as` key.
+     *
+     * @example
+     * ```ts
+     * await db.aggregate('orders', {
+     *   groupBy: ['status'],
+     *   aggregates: [{ fn: 'count', as: 'n' }, { fn: 'sum', col: 'total', as: 'revenue' }],
+     *   having: [{ aggregate: 'n', op: 'gt', val: 10 }],
+     *   orderBy: 'revenue', orderDir: 'desc',
+     * });
+     * ```
+     */
+    aggregate(table: string, opts: AggregateOptions): Promise<AggregateResult[]>;
+    private _assertTrust;
+    /**
+     * Mark a row `verified` — sets `_trust_state='verified'`, `_verified_by`, and
+     * `_verified_at` (now). Requires `trust` config on the table.
+     */
+    verifyRow(table: string, id: PkLookup, verifiedBy?: string): Promise<void>;
+    /**
+     * Flag a row for human review — sets `_trust_state='needs_review'` and an
+     * optional `_review_reason`. Requires `trust` config on the table.
+     */
+    markRowForReview(table: string, id: PkLookup, reason?: string): Promise<void>;
+    /** Rows currently in `needs_review` state (non-deleted). Requires `trust` config. */
+    rowsNeedingReview(table: string): Promise<Row[]>;
+    /** Rows currently in `verified` state (non-deleted). Requires `trust` config. */
+    verifiedRows(table: string): Promise<Row[]>;
+    /** Add (upsert) a typed edge between two rows. */
+    addEdge(edge: GraphEdge): Promise<void>;
+    /** Add (upsert) many typed edges. */
+    addEdges(edges: GraphEdge[]): Promise<void>;
+    /** Remove an edge (all types between the pair when `type` omitted). */
+    removeEdge(edge: Omit<GraphEdge, 'weight' | 'type'> & {
+        type?: string;
+    }): Promise<void>;
+    /** Direct neighbors (one hop) of a node. */
+    neighbors(node: GraphNode, opts?: {
+        direction?: TraversalDirection;
+        edgeTypes?: string[];
+    }): Promise<GraphEdge[]>;
+    /** Bounded BFS from a node (depth ≤ 5, node-count capped). */
+    traverseGraph(start: GraphNode, opts?: TraversalOptions): Promise<GraphTraversalResult>;
+    /** Zero-LLM edge extraction from a foreign-key column. Returns the edge count. */
+    extractEdges(spec: ExtractEdgesSpec): Promise<number>;
+    /**
+     * Graph-augmented hybrid search: run {@link hybridSearch}, then boost results
+     * that are graph-adjacent to the `anchors` (e.g. the user's current-context
+     * entities), so relationship-relevant rows rank higher. Returns the reranked
+     * hybrid results (the graph boost is folded into each score).
+     */
+    graphSearch(table: string, query: string, opts: Omit<HybridSearchOptions, 'embeddingsConfig' | 'pkColumn'> & {
+        anchors: GraphNode[];
+        graphWeight?: number;
+        graphDepth?: number;
+        graphDirection?: TraversalDirection;
+        graphEdgeTypes?: string[];
+    }): Promise<HybridSearchResult[]>;
+    /**
+     * Enable keyless cloud file-byte access cloud-wide (Postgres cloud only).
+     * Installs the in-database SigV4 presigner + `pgcrypto`, stores the owner's
+     * least-privilege S3 key in an **owner-only, member-unreadable** table, and
+     * grants the cloud's member group EXECUTE on `lattice_presign_file` — so every
+     * current + future member can presign GET/PUT URLs for the `files` rows they're
+     * allowed to see, holding no key themselves. One owner action turns it on for
+     * the whole cloud.
+     */
+    enableCloudFilePresigning(secret: CloudS3Secret, opts?: {
+        memberGroup?: string;
+    }): Promise<void>;
+    /**
+     * Presign a GET/PUT URL for a `files` row, computed inside Postgres and gated
+     * on the caller's row-visibility (the keyless-member path). Requires the
+     * presigner to be installed + an S3 secret configured
+     * ({@link enableCloudFilePresigning}). TTL is capped at 60s server-side.
+     */
+    presignFile(fileId: string, method: 'GET' | 'PUT', ttlSeconds?: number): Promise<string>;
     render(outputDir: string, opts?: RenderOptions): Promise<RenderResult>;
     /**
      * Render into `outputDir` through the shared single-flight guard, intended to
@@ -2510,7 +3820,10 @@ declare class Lattice {
      * rendered context tree is read THROUGH the member's RLS connection + masking
      * views — making the on-disk tree the viewer's own scoped projection. Owner /
      * local SQLite leave it unset → identity → unchanged behavior. Set on the
-     * engine (not per-render-call) so the opts-less auto-render path masks too.
+     * SchemaManager (the read layer), not per-render-call, so the opts-less
+     * auto-render path masks too — AND so the reverse-sync engine, which reads the
+     * same SchemaManager, writes a member's file edit back through the masked view
+     * instead of the REVOKE'd base table. One resolver, every reader.
      */
     setRenderReadRelation(fn: (table: string) => string): void;
     /**
@@ -3008,6 +4321,17 @@ declare function parseConfigFile(configPath: string): ParsedConfig;
  */
 declare function parseConfigString(yamlContent: string, configDir: string): ParsedConfig;
 
+/**
+ * Thrown by a bounded read (`QueryOptions.maxRows` or `defaultMaxRows`) when more
+ * rows match than the cap allows and no explicit `limit` was given — forcing the
+ * caller to paginate instead of silently loading an unbounded result set.
+ */
+declare class BoundedReadError extends Error {
+    readonly table: string;
+    readonly maxRows: number;
+    constructor(table: string, maxRows: number);
+}
+
 declare function contentHash(content: string): string;
 
 /**
@@ -3552,6 +4876,123 @@ declare class PostgresAdapter implements StorageAdapter {
     private _registerPolyfills;
 }
 
+/**
+ * Durable retry for transient database failures.
+ *
+ * Under contention a database returns retryable errors that a robust app should
+ * simply re-attempt: SQLite `SQLITE_BUSY`, Postgres serialization failures
+ * (`40001`) and deadlocks (`40P01` / `40P02`), and dropped connections. `withRetry`
+ * re-runs an operation through a bounded, decorrelated-jitter backoff so these
+ * blips don't surface as user-facing failures.
+ *
+ * CRITICAL: only wrap **idempotent** work — a whole bulk operation or a Lattice
+ * API method that is safe to re-run, NOT a raw non-idempotent `adapter.run()`
+ * (re-running an `INSERT` after a mid-statement connection drop could double-apply
+ * it). A nested `withRetry` is detected and does NOT add a second retry layer, so
+ * composing retry-wrapped helpers can't multiply the attempt count.
+ */
+interface RetryOptions {
+    /** Maximum attempts including the first. Default 5. */
+    maxAttempts?: number;
+    /** Base backoff in ms. Default 50. */
+    baseDelayMs?: number;
+    /** Backoff ceiling in ms. Default 2000. */
+    maxDelayMs?: number;
+    /** Override the retryable-error classifier. */
+    isRetryable?: (err: unknown) => boolean;
+    /** Called before each retry (for logging/metrics). */
+    onRetry?: (err: unknown, attempt: number, delayMs: number) => void;
+    /** Injectable RNG in [0,1) for deterministic tests. Default Math.random. */
+    random?: () => number;
+    /** Injectable sleep for deterministic tests. Default real setTimeout. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/** Default classifier: SQLITE_BUSY / locked, retryable PG SQLSTATEs, dropped sockets. */
+declare function isRetryableDbError(err: unknown): boolean;
+/**
+ * Run `fn`, retrying transient DB failures with decorrelated-jitter backoff.
+ * A nested call (already inside a `withRetry`) runs `fn` directly without a
+ * second retry layer.
+ *
+ * @throws the last error if every attempt fails, or immediately for a
+ *   non-retryable error.
+ */
+declare function withRetry<T>(fn: () => Promise<T>, opts?: RetryOptions): Promise<T>;
+
+/**
+ * Online, resumable migrations.
+ *
+ * A naive backfill that updates a whole table in one statement takes a long
+ * table lock — a maintenance window — and, if killed partway, has to restart
+ * from zero. A chunked migration instead walks the table's primary key in
+ * batches, each its own short transaction, and records progress in a checkpoint
+ * table after every batch. So it never holds a long lock, and a kill (deploy,
+ * crash, OOM) is recoverable: `resumeMigration` picks up after the last
+ * checkpointed key instead of redoing completed work.
+ *
+ * The per-batch `apply` callback MUST be idempotent — a batch can re-run if the
+ * process dies between applying it and committing its checkpoint.
+ */
+
+type MigrationStatus = 'running' | 'complete' | 'reverted';
+interface MigrationCheckpoint {
+    id: string;
+    table: string;
+    lastPk: string | null;
+    processed: number;
+    status: MigrationStatus;
+    startedAt: string;
+    updatedAt: string;
+}
+interface ChunkedMigrationOptions {
+    /** Unique, stable id for this migration (the resume key). */
+    id: string;
+    /** Table to walk. */
+    table: string;
+    /** Process one batch of rows. MUST be idempotent. */
+    apply: (rows: Row[], adapter: StorageAdapter) => Promise<void>;
+    /** Rows per batch. Default 500. */
+    batchSize?: number;
+    /** Primary-key column to walk (must be sortable). Default 'id'. */
+    pkColumn?: string;
+    /** Optional WHERE predicate (without the leading WHERE) to scope rows. */
+    where?: string;
+    /** Bound params for `where`. */
+    whereParams?: unknown[];
+}
+interface ChunkedMigrationResult {
+    id: string;
+    processed: number;
+    batches: number;
+    status: MigrationStatus;
+}
+/** Ensure the checkpoint table exists (idempotent). */
+declare function ensureCheckpointTable(adapter: StorageAdapter): Promise<void>;
+declare function getMigrationCheckpoint(adapter: StorageAdapter, id: string): Promise<MigrationCheckpoint | null>;
+declare function listMigrationCheckpoints(adapter: StorageAdapter): Promise<MigrationCheckpoint[]>;
+/**
+ * Apply a chunked migration. Creates a checkpoint and walks the table in
+ * batches, committing progress after each. If a checkpoint for `id` already
+ * exists (a prior killed run), it resumes from there. Re-running a completed
+ * migration is a no-op.
+ */
+declare function applyChunkedMigration(adapter: StorageAdapter, opts: ChunkedMigrationOptions): Promise<ChunkedMigrationResult>;
+/**
+ * Resume a previously-started (and not completed) chunked migration. Throws if
+ * no checkpoint exists for `id` — use {@link applyChunkedMigration} to start one.
+ */
+declare function resumeMigration(adapter: StorageAdapter, opts: ChunkedMigrationOptions): Promise<ChunkedMigrationResult>;
+/**
+ * Revert a migration: walk the processed rows in batches applying `revert`, then
+ * mark the checkpoint `reverted`. `revert` must be idempotent.
+ */
+declare function revertMigration(adapter: StorageAdapter, id: string, table: string, revert: (rows: Row[], adapter: StorageAdapter) => Promise<void>, opts?: {
+    batchSize?: number;
+    pkColumn?: string;
+    where?: string;
+    whereParams?: unknown[];
+}): Promise<ChunkedMigrationResult>;
+
 /**
  * Framework-shipped tables that every Lattice can opt into via
  * {@link registerNativeEntities}. These tables are intentionally generic —
@@ -4181,6 +5622,13 @@ declare function isPrivateIp(ip: string): boolean;
 interface FtsHit {
     id: string;
     snippet: string;
+    /**
+     * Relevance score, higher = better. Populated by the indexed tier
+     * (`ts_rank` on Postgres, `-bm25` on SQLite FTS5). Absent / 0 for the LIKE
+     * fallback tier, which has no ranking model. Used to order hits and as the
+     * FTS signal in hybrid fusion.
+     */
+    score?: number;
 }
 interface FtsGroup {
     table: string;
@@ -4225,6 +5673,66 @@ declare function hasFtsIndex(adapter: StorageAdapter, table: string): Promise<bo
  */
 declare function fullTextSearch(adapter: StorageAdapter, tables: string[], opts: FtsOptions): Promise<FtsResult>;
 
+/**
+ * Native indexed vector search.
+ *
+ * The in-process cosine scan in `embeddings.ts` loads and scores every stored
+ * vector per query — O(n), fine at small n but a disqualifier at enterprise
+ * scale. When the database provides an approximate-nearest-neighbor index this
+ * module builds and queries it instead, turning vector search into an indexed
+ * ~O(log n) lookup that stays flat as n grows.
+ *
+ * - **Postgres + pgvector:** a per-table `_lattice_vec_<table>` with a
+ *   `vector(dim)` column and an HNSW index on cosine distance (`<=>`).
+ * - **SQLite + sqlite-vec:** a per-table `vec0` virtual table (used when the
+ *   extension has been loaded into the connection).
+ *
+ * The JSON store in `_lattice_embeddings` remains the portable source of record;
+ * this index is a DERIVED accelerator built from it (mirroring how the FTS index
+ * derives from the base table). When no extension is present, callers fall back
+ * to the in-process scan, and `lattice doctor` reports the missing extension.
+ *
+ * The index is opt-in: `buildVectorIndex` populates it from the JSON store, and
+ * search uses it only when `hasVectorIndex` is true — so the default behavior is
+ * unchanged for users who never call it.
+ */
+
+/**
+ * Per-table native vector index name. The table is grammar-guarded here because
+ * the returned name is interpolated into DDL (`CREATE TABLE "..."`, `DROP`,
+ * `INSERT`); every build/drop/search path derives the index name through this
+ * one function, so a single guard at the choke point covers them all.
+ */
+declare function vectorIndexName(table: string): string;
+interface VectorHit {
+    pk: string;
+    chunkIndex: number;
+    content: string | null;
+    /** Cosine similarity in [0, 1] (1 − cosine distance). */
+    score: number;
+}
+/** Whether this connection has a usable native vector extension. */
+declare function vectorIndexAvailable(adapter: StorageAdapter): Promise<boolean>;
+/** Whether a native vector index table exists for `table`. */
+declare function hasVectorIndex(adapter: StorageAdapter, table: string): Promise<boolean>;
+/**
+ * Build (or rebuild) the native vector index for `table` from the JSON store,
+ * for vectors of dimension `dim`. No-op when no native extension is available.
+ * Returns the number of vectors indexed.
+ *
+ * @throws when called with an unavailable extension *and* `requireExtension` is
+ *   true — surfacing a misconfiguration loudly rather than silently doing
+ *   nothing. By default it is a reported no-op (returns 0).
+ */
+declare function buildVectorIndex(adapter: StorageAdapter, table: string, dim: number, requireExtension?: boolean): Promise<number>;
+/** Drop a table's native vector index. */
+declare function dropVectorIndex(adapter: StorageAdapter, table: string): Promise<void>;
+/**
+ * Query the native vector index for the nearest chunks to `queryVector`.
+ * Returns up to `limit` hits with cosine similarity scores ≥ `minScore`.
+ */
+declare function searchVectorIndex(adapter: StorageAdapter, table: string, queryVector: number[], limit: number, minScore: number): Promise<VectorHit[]>;
+
 /**
  * Reference-ingestion API — parallel to {@link attachBlob}, but records a row
  * that *indexes* data living elsewhere instead of copying bytes. The returned
@@ -5250,4 +6758,4 @@ declare class FileSourceKeyStore implements SourceKeyStore {
     private encodeFile;
 }
 
-export { type AddWorkspaceOptions, type AdoptNativeOptions, type AdoptResult, type ApplyWriteResult, type AudienceRowCtx, type AuditEvent, type AutoUpdateResult, type BelongsToRelation, type BelongsToSource, type BlobMetadata, type BuiltinTemplateName, CLOUD_SETTING_SYSTEM_PROMPT, CLOUD_SETTING_WORKSPACE_LOGO, CLOUD_SETTING_WORKSPACE_LOGO_ETAG, CONFIG_SUBDIR, type CatalogEntity, type CatalogRecord, type ChangeEntry, type ChangelogOptions, type ClassifyMatch, type CleanupOptions, type CleanupResult, type CloudProbeResult, type CountOptions, type CrawlOptions, type CrawlResult, type CustomSource, DEFAULT_ENTRY_TYPES, DEFAULT_TYPE_ALIASES, type DiscoveredTable, type EmbeddingsConfig, type EnrichOptions, type EnrichResult, type EnrichedSource, type EnrichmentLookup, type EntityContextDefinition, type EntityContextManifestEntry, type EntityFileManifestInfo, type EntityFileSource, type EntityFileSpec, type EntityProfileField, type EntityProfileSection, type EntityProfileTemplate, type EntityRenderSpec, type EntityRenderTemplate, type EntitySectionPerRow, type EntitySectionsTemplate, type EntityTableColumn, type EntityTableTemplate, type ExtractedObject, FileSourceKeyStore, type FileSourceKeyStoreOptions, type FilesRow, type Filter, type FilterOp, FoldCache, type FtsConfig, type FtsGroup, type FtsHit, type FtsOptions, type FtsResult, type GuiServerHandle, type HasManyRelation, type HasManySource, InMemorySourceKeyStore, InMemoryStateStore, type InitOptions, LEGACY_MEMBER_GROUP, LOCAL_DB_RELPATH, Lattice, type LatticeConfig, type LatticeConfigInput, type LatticeEntityDef, type LatticeEntityRenderSpec, type LatticeFieldDef, type LatticeFieldType, type LatticeManifest, type LatticeOptions, type LinkOptions, type LlmClient, type LlmMessage, type ManyToManySource, type MarkdownTableColumn, type MigrateResult, type Migration, type MigrationOptions, type MigrationProgress, type MigrationResult, type MultiTableDefinition, NATIVE_ENTITY_DEFS, NATIVE_ENTITY_NAMES, NATIVE_REGISTRY_TABLE, type Observation, type OrderBySpec, type OrganizeOptions, type OrganizeResult, type OrganizedCreation, type OrganizedLink, type ParseError, type ParseResult, type ParsedConfig, type PdfOptions, type PdfSenderInput, type PkLookup, PostgresAdapter, type PostgresAdapterOptions, type PreparedStatement, type PrimaryKey, ProgressThrottle, type QueryOptions, READ_ONLY_HEADER, ROOT_DIRNAME, type ReadOnlyHeaderOptions, type ReconcileOptions, type ReconcileResult, type RefKind, type RefProvider, type ReferenceMetadata, ReferenceUnavailableError, type Relation, type RemoteBlobStore, type RenderHooks, type RenderOptions, type RenderProgress, type RenderProgressCallback, type RenderProgressKind, type RenderResult, type RenderSpec, type ReportConfig, type ReportResult, type ReportSection, type ReportSectionResult, type ResolveOptions, type ReverseSeedDetection, type ReverseSeedResult, type ReverseSeedTableResult, type ReverseSyncError, type ReverseSyncResult, type ReverseSyncUpdate, type RewardScores, type Row, type RowVisibilityDefault, type S3Config, type S3StoreConfig, S3UnavailableError, SQLiteAdapter, type SchemaEntity, type SearchOptions, type SearchResult, type SecurityOptions, type SeedConfig, type SeedLinkSpec, SeedReconciliationError, type SeedResult, type SelfSource, type SessionEntry, type SessionParseOptions, type SessionWriteEntry, type SessionWriteOp, type SessionWriteParseResult, type SourceHandle, type SourceKeyStore, type SourceMetadata, type SourceQueryOptions, SourceShreddedError, type StartGuiServerOptions, type StopFn, type StorageAdapter, type SyncResult, type TableDefinition, type TablePolicy, type TemplateRenderSpec, type TurnParams, type TurnResult, type UnresolvedLink, type UpsertByNaturalKeyOptions, type UserIdentity, type UserPreferences, type Viewer, type VisionOptions, type VisionSenderInput, WORKSPACES_SUBDIR, type WatchOptions, type WorkspacePaths, type WorkspaceRecord, type WorkspaceRegistry, type WriteHook, type WriteHookContext, type WritebackDefinition, type WritebackStateStore, type WritebackValidationResult, activeWorkspaceLabel, addWorkspace, adoptNativeEntities, analyticsEnabled, applyTokenBudget, applyWriteEntry, archiveLocalSqlite, assertSafeUrl, attachBlob, audiencePredicate, audienceViewSql, autoFtsColumns, autoUpdate, backfillOwnership, canManageRoles, classifyLinks, cloudRlsInstalled, configDir, contentHash, crawlUrl, createReadOnlyHeader, createS3Store, createSQLiteStateStore, decrypt, defaultWorkspaceYaml, deleteDbCredential, deleteToken, deriveCanonicalContexts, deriveKey, describeImage, describePdf, discoverCloudTables, enableAudienceView, enableChangelogRls, enableRlsForTable, encrypt, enrichKnowledge, ensureFtsIndex, ensureLatticeRoot, entityFileNames, estimateTokens, extractObjects, findLatticeRoot, fixSchemaConflicts, foldEntity, frontmatter, ftsTableName, fullTextSearch, generateEntryId, generateMemberPassword, generateWriteEntryId, getActiveWorkspace, getCloudSetting, getDbCredential, getOrCreateMasterKey, getTablePolicy, getWorkspace, hasFtsIndex, hashFile, importLegacyUserConfig, installCloudRls, installCloudSettings, isEncrypted, isNativeEntity, isPostgresUrl, isPrivateIp, isRowAudience, listDbCredentials, listNativeBindings, listTokens, listWorkspaces, loadColumnPolicy, manifestPath, markdownTable, memberGroupFor, memberRoleName, migrateLatticeData, observationVisible, observationsFromChange, openTargetLatticeForMigration, openUnderSource, organizeSource, parseConfigFile, parseConfigString, parseMarkdownEntries, parseMatches, parseObjects, parseSessionMD, parseSessionWrites, probeCloud, providerForUrl, provisionMemberRole, readIdentity, readManifest, readPreferences, readRegistry, readToken, referenceLocalFile, referenceUrl, regenerateAudienceViewFromDb, registerNativeEntities, registryPath, resolveActiveS3Config, resolveLatticeRoot, resolveSource, resolveWorkspacePaths, revokeMemberRole, rootConfigDir, s3Key, saveDbCredential, saveDbCredentialForTeam, sealUnderSource, secureCloud, seedColumnPolicyFromYaml, setActiveWorkspace, setCloudSetting, setColumnAudience, setRowVisibility, setTableDefaultVisibility, setTableNeverShare, shredSource, slugify, startGuiServer, summarizeText, tableNeedsAudienceView, toSafeDirName, truncate, validateEntryId, workspaceBlobsDir, workspaceConfigPath, workspaceContextDir, workspaceDataDir, workspaceDbPath, workspaceDir, workspacesDir, writeIdentity, writeManifest, writePreferences, writeRegistry, writeToken };
+export { ALL_PROVENANCE_FIELDS, type AddWorkspaceOptions, type AdoptNativeOptions, type AdoptResult, type AggregateFunction, type AggregateHaving, type AggregateOptions, type AggregateResult, type AggregateSpec, type ApplyWriteResult, type AudienceRowCtx, type AuditEvent, type AutoUpdateResult, type BacklinkSignal, type BelongsToRelation, type BelongsToSource, type BenchmarkOptions, type BenchmarkReport, type BenchmarkScale, type BlobMetadata, BoundedReadError, type BuiltinTemplateName, CLOUD_SETTING_SYSTEM_PROMPT, CLOUD_SETTING_WORKSPACE_LOGO, CLOUD_SETTING_WORKSPACE_LOGO_ETAG, CONFIG_SUBDIR, type CatalogEntity, type CatalogRecord, type ChangeEntry, type ChangelogOptions, type ChunkedMigrationOptions, type ChunkedMigrationResult, type ChunkerFn, type ClassifyMatch, type CleanupOptions, type CleanupResult, type CloudProbeResult, type CloudS3Secret, ComputedColumnCycleError, type ComputedColumnSpec, type CountOptions, type CrawlOptions, type CrawlResult, type CustomSignal, type CustomSource, DEFAULT_ENTRY_TYPES, DEFAULT_MAX_NODES, DEFAULT_TYPE_ALIASES, type DiagnoseOptions, type DiscoveredTable, EMBEDDINGS_TABLE, EmbeddingDimensionMismatchError, type EmbeddingRefreshResult, type EmbeddingsConfig, type EnrichOptions, type EnrichResult, type EnrichedSource, type EnrichmentLookup, type EntityContextDefinition, type EntityContextManifestEntry, type EntityFileManifestInfo, type EntityFileSource, type EntityFileSpec, type EntityProfileField, type EntityProfileSection, type EntityProfileTemplate, type EntityRenderSpec, type EntityRenderTemplate, type EntitySectionPerRow, type EntitySectionsTemplate, type EntityTableColumn, type EntityTableTemplate, type EvalQuery, type EvalRegression, type ExtensionAvailability, type ExtractEdgesSpec, type ExtractedObject, FileSourceKeyStore, type FileSourceKeyStoreOptions, type FilesRow, type Filter, type FilterAnd, type FilterExpr, type FilterOp, type FilterOr, FoldCache, type FtsConfig, type FtsGroup, type FtsHit, type FtsOptions, type FtsResult, type GraphBoostOptions, type GraphBoostResult, type GraphEdge, type GraphNode, type GraphTraversalResult, type GuiServerHandle, type HasManyRelation, type HasManySource, type HealthIssueKind, type HealthSeverity, type HybridScoreBreakdown, type HybridSearchOptions, type HybridSearchResult, InMemorySourceKeyStore, InMemoryStateStore, type InitOptions, LEGACY_MEMBER_GROUP, LOCAL_DB_RELPATH, type LatencyStats, Lattice, type LatticeConfig, type LatticeConfigInput, type LatticeEntityDef, type LatticeEntityRenderSpec, type LatticeFieldDef, type LatticeFieldType, type LatticeManifest, type LatticeOptions, type LinkOptions, type LlmClient, type LlmMessage, MAX_TRAVERSAL_DEPTH, type ManyToManySource, type MarkdownTableColumn, type MaterializedRollupSpec, type MigrateResult, type Migration, type MigrationCheckpoint, type MigrationOptions, type MigrationProgress, type MigrationResult, type MigrationStatus, type MultiTableDefinition, NATIVE_ENTITY_DEFS, NATIVE_ENTITY_NAMES, NATIVE_REGISTRY_TABLE, type Observation, type OrderBySpec, type OrganizeOptions, type OrganizeResult, type OrganizedCreation, type OrganizedLink, type ParseError, type ParseResult, type ParsedConfig, type PdfOptions, type PdfSenderInput, type PerQueryEval, type PkLookup, PostgresAdapter, type PostgresAdapterOptions, type PreparedStatement, type PrimaryKey, ProgressThrottle, type ProvenanceConfig, type ProvenanceField, ProvenanceImmutableError, type QueryOptions, type QueryPageOptions, type QueryPageResult, type QueryProjection, READ_ONLY_HEADER, ROOT_DIRNAME, type RankingOptions, type ReadOnlyHeaderOptions, type RecencySignal, type ReconcileOptions, type ReconcileResult, type RefKind, type RefProvider, type ReferenceMetadata, ReferenceUnavailableError, type RefreshEmbeddingsOptions, type Relation, type RelevanceLabel, type RemoteBlobStore, type RenderHooks, type RenderOptions, type RenderProgress, type RenderProgressCallback, type RenderProgressKind, type RenderResult, type RenderSpec, type ReportConfig, type ReportResult, type ReportSection, type ReportSectionResult, type RerankCandidate, type RerankScore, type RerankerFn, type ResolveOptions, type RetrievalEvalOptions, type RetrievalEvalSummary, type RetrievalHealthIssue, type RetrievalHealthReport, type RetrievalHealthSpec, type RetrievalSlo, type Retriever, type RetryOptions, type ReverseSeedDetection, type ReverseSeedResult, type ReverseSeedTableResult, type ReverseSyncError, type ReverseSyncResult, type ReverseSyncUpdate, type RewardScores, type RewardSignal, type RollupFunction, type Row, type RowVisibilityDefault, type S3Config, type S3StoreConfig, S3UnavailableError, S3_SECRET_TABLE, SQLiteAdapter, type SchemaEntity, type SearchOptions, type SearchResult, type SecurityOptions, type SeedConfig, type SeedLinkSpec, SeedReconciliationError, type SeedResult, type SelfSource, type SemanticChunkerOptions, type SessionEntry, type SessionParseOptions, type SessionWriteEntry, type SessionWriteOp, type SessionWriteParseResult, type SloViolation, type SourceHandle, type SourceKeyStore, type SourceMetadata, type SourceQueryOptions, SourceShreddedError, type StartGuiServerOptions, type StopFn, type StorageAdapter, type SyncResult, TRUST_COLUMNS, type TableDefinition, type TableHealth, type TablePolicy, type TemplateRenderSpec, type TextChunk, type TraversalDirection, type TraversalNode, type TraversalOptions, type TrustConfig, type TrustState, type TurnParams, type TurnResult, type UnresolvedLink, type UpsertByNaturalKeyOptions, type UserIdentity, type UserPreferences, type VectorHit, type Viewer, type VisionOptions, type VisionSenderInput, WORKSPACES_SUBDIR, type WatchOptions, type WorkspacePaths, type WorkspaceRecord, type WorkspaceRegistry, type WriteHook, type WriteHookContext, type WritebackDefinition, type WritebackStateStore, type WritebackValidationResult, activeWorkspaceLabel, addEdge, addEdges, addWorkspace, adoptNativeEntities, allComputedDeps, analyticsEnabled, applyChunkedMigration, applyReranker, applyTokenBudget, applyWriteEntry, archiveLocalSqlite, assertSafeUrl, attachBlob, audiencePredicate, audienceViewSql, autoFtsColumns, autoUpdate, backfillOwnership, backlinkBoost, benchmarkRetrieval, buildVectorIndex, canManageRoles, checkSlos, chunkText, classifyLinks, cloudRlsInstalled, computeColumns, computedColumnDdl, computedColumnOrder, concatRowText, configDir, contentHash, cosineSimilarity, crawlUrl, createReadOnlyHeader, createS3Store, createSQLiteStateStore, decrypt, defaultWorkspaceYaml, deleteDbCredential, deleteToken, deriveCanonicalContexts, deriveKey, describeImage, describePdf, detectRetrievalRegressions, diagnoseRetrieval, discoverCloudTables, dropVectorIndex, enableAudienceView, enableChangelogRls, enableRlsForTable, encrypt, enrichKnowledge, ensureCheckpointTable, ensureEdgesTable, ensureEmbeddingsTable, ensureFtsIndex, ensureLatticeRoot, entityFileNames, estimateTokens, evaluateRetrieval, extractEdgesFromColumn, extractObjects, filePresignSql, findLatticeRoot, fixSchemaConflicts, foldEntity, formatHealthReport, frontmatter, ftsTableName, fullTextSearch, generateEntryId, generateMemberPassword, generateWriteEntryId, getActiveWorkspace, getCloudSetting, getDbCredential, getMigrationCheckpoint, getOrCreateMasterKey, getTablePolicy, getWorkspace, grantPresignerToMemberGroup, graphAdjacencyBoost, hasFilePresigner, hasFtsIndex, hasVectorIndex, hashFile, hybridSearch, importLegacyUserConfig, installCloudRls, installCloudSettings, installFilePresigner, isEncrypted, isNativeEntity, isPostgresUrl, isPrivateIp, isRetryableDbError, isRowAudience, latencyStats, listDbCredentials, listMigrationCheckpoints, listNativeBindings, listTokens, listWorkspaces, loadColumnPolicy, manifestPath, markdownTable, memberGroupFor, memberRoleName, migrateLatticeData, neighbors, observationVisible, observationsFromChange, openTargetLatticeForMigration, openUnderSource, organizeSource, parseConfigFile, parseConfigString, parseMarkdownEntries, parseMatches, parseObjects, parseSessionMD, parseSessionWrites, percentile, probeCloud, provenanceColumns, providerForUrl, provisionMemberRole, rankingBoost, readIdentity, readManifest, readPreferences, readRegistry, readToken, recencyBoost, referenceLocalFile, referenceUrl, refreshEmbeddings, regenerateAudienceViewFromDb, registerNativeEntities, registryPath, removeEdge, removeEmbedding, resolveActiveS3Config, resolveLatticeRoot, resolveProvenanceFields, resolveSource, resolveTrustDefault, resolveWorkspacePaths, resumeMigration, revertMigration, revokeMemberRole, rewardBoost, rollupColumnDdl, rootConfigDir, s3Key, saveDbCredential, saveDbCredentialForTeam, sealUnderSource, searchByEmbedding, searchVectorIndex, secureCloud, seedColumnPolicyFromYaml, semanticChunker, setActiveWorkspace, setCloudS3Secret, setCloudSetting, setColumnAudience, setRowVisibility, setTableDefaultVisibility, setTableNeverShare, shredSource, slugify, startGuiServer, storeEmbedding, summarizeText, tableNeedsAudienceView, toSafeDirName, traverse, truncate, validateEntryId, vectorIndexAvailable, vectorIndexName, withRetry, workspaceBlobsDir, workspaceConfigPath, workspaceContextDir, workspaceDataDir, workspaceDbPath, workspaceDir, workspacesDir, writeIdentity, writeManifest, writePreferences, writeRegistry, writeToken };