@noy-db/hub 0.3.0-pre.8 → 0.3.0

package/dist/with-lookup/search/collection-facade.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Collection-level search / retrieval (`search` / `retrieve` / `similarTo` +
+ * the lexical-index build/flush/warm machinery).
+ *
+ * This is the retrieval surface: a pure client-side lexical scan
+ * (`search`), the persisted-or-in-memory inverted-index lifecycle
+ * (`flushIndex` / `warmIndex` / `buildRetrievalDocs` + the dict-label / blob-
+ * filename resolvers that feed it), and the lexical / semantic / hybrid
+ * `retrieve` fan-out plus raw-vector kNN (`similarTo`). None of it touches the
+ * write path — it reads the live eager cache and the encrypted `_vec` / `_ftindex`
+ * side-cars.
+ *
+ * Every function takes a small {@link SearchContext} instead of `this`,
+ * mirroring the `record-keys/` siblings.
+ *
+ * The `cache` is the SAME `Map` reference `Collection` owns (passed by
+ * reference, never copied) so the index always builds over the live working
+ * set. {@link buildPersistedIndexCallbacks} is special: it is invoked from the
+ * `Collection` constructor *before* `this.codec` exists, so it takes a context
+ * THUNK and resolves the context lazily at each callback invocation.
+ *
+ * Internal service — not exported as a `@noy-db/hub/*` subpath.
+ */
+import type { NoydbStore } from '../../kernel/types.js';
+import type { RecordCodec } from '../../kernel/enclave/index.js';
+import { type I18nTextDescriptor } from '../../via/i18n/core.js';
+import { type DictKeyDescriptor, type StaticDictDescriptor, type DictionaryHandle } from '../../via/i18n/dictionary.js';
+import type { BlobSet } from '../../with-shape/blobs/blob-set.js';
+import type { BlobFieldsConfig } from '../../with-shape/blobs/blob-compaction.js';
+import { type VectorSet, type EmbeddingDescriptor } from '../embeddings/index.js';
+import { type SearchOptions, type SearchResult } from './index.js';
+import type { IndexStore } from './index-store.js';
+import type { PersistedIndexCallbacks } from './persisted-index-store.js';
+import type { IndexDoc } from './inverted-index.js';
+import type { RetrieveOptions, RetrieveHit } from './retrieve-types.js';
+/** Everything the moving search/retrieval methods touched on `this.*`. */
+export interface SearchContext<T> {
+    /** Collection name — error context + `_ftindex` row key. */
+    readonly name: string;
+    /** Vault namespace the side-cars (`_vec`, `_ftindex`) live under. */
+    readonly vault: string;
+    /** The ciphertext store. */
+    readonly adapter: NoydbStore;
+    /** The record codec — decrypts the `_vec` / `_ftindex` side-car bodies. */
+    readonly codec: RecordCodec<T>;
+    /** The eager working-set cache (SHARED `Map` reference, never copied). */
+    readonly cache: Map<string, {
+        record: T;
+        version: number;
+    }>;
+    /** True in lazy mode — search/retrieve/warm require eager mode. */
+    readonly lazy: boolean;
+    /** Declared text-index fields, or undefined. */
+    readonly textIndexes: readonly string[] | undefined;
+    /** Declared i18n fields, or undefined. */
+    readonly i18nFields: Record<string, I18nTextDescriptor> | undefined;
+    /** Declared dictionary-key fields, or undefined. */
+    readonly dictKeyFields: Record<string, DictKeyDescriptor | StaticDictDescriptor> | undefined;
+    /** Declared blob fields, or undefined. */
+    readonly blobFields: BlobFieldsConfig | undefined;
+    /** Dictionary handle resolver (dynamic dict-key labels), or undefined. */
+    readonly getDictionary: ((name: string) => Promise<DictionaryHandle>) | undefined;
+    /** The lexical inverted-index store (in-memory or persisted), or undefined. */
+    readonly searchIndexStore: IndexStore | undefined;
+    /** The vector set for semantic retrieval, or undefined. */
+    readonly vectorSet: VectorSet | undefined;
+    /** The embeddings descriptor, or undefined. */
+    readonly embeddings: EmbeddingDescriptor | undefined;
+    /** Hydrate the eager cache before reading it. */
+    ensureHydrated(): Promise<void>;
+    /** Open the blob facade for a record (used to list indexed blob filenames). */
+    blob(id: string): BlobSet;
+}
+/**
+ * Client-side lexical scan over the live eager cache. Eager mode only;
+ * nothing searchable is written to the store.
+ */
+export declare function search<T>(ctx: SearchContext<T>, field: string, query: string, opts?: SearchOptions): Promise<SearchResult<T>[]>;
+/** L1 — build IndexDoc[] for the configured text fields over the live cache. */
+export declare function buildRetrievalDocs<T>(ctx: SearchContext<T>, labelMaps: Map<string, Map<string, Record<string, string>>>, blobFilenames: Map<string, Map<string, string[]>>, only?: readonly string[]): IndexDoc[];
+/** L1 — true iff any configured text index is also a blob field (gates ALL slot I/O). */
+export declare function hasIndexedBlobFields<T>(ctx: SearchContext<T>, only?: readonly string[]): boolean;
+/** L1.5 — force-persist the lexical index now (e.g. on save/idle). Persists only when textIndexPersist is enabled; a no-op otherwise. */
+export declare function flushIndex<T>(ctx: SearchContext<T>): Promise<void>;
+/**
+ * L1.5 — build the PersistedIndexCallbacks bridge: crypto lives here
+ * (collection has getDEK / encryptJsonString / decryptJsonString / adapter),
+ * the index store itself is crypto-free.
+ *
+ * Fingerprint encoding: body-wrap approach — save(json, fp) stores
+ * JSON.stringify({ fp, idx: json }) as the encrypted body so the standard
+ * EncryptedEnvelope shape is never extended. load() decrypts and JSON.parses
+ * the wrapper back out.
+ *
+ * Cache shape: ctx.cache stores { record, version } — currentFingerprint()
+ * iterates over e.version.
+ *
+ * NOTE: this factory is invoked from the `Collection` constructor *before*
+ * `this.codec` is assigned, so it takes a context THUNK and resolves the
+ * context lazily inside each callback — by the time a callback actually runs,
+ * the codec and cache are fully wired.
+ */
+export declare function buildPersistedIndexCallbacks<T>(provideCtx: () => SearchContext<T>): PersistedIndexCallbacks;
+/** L1 — pre-build the lexical index (e.g. on open) so the first retrieve() pays no build scan. */
+export declare function warmIndex<T>(ctx: SearchContext<T>): Promise<void>;
+/** Retrieval. mode: 'lexical' (default) | 'semantic' (L2) | 'hybrid' (L3). */
+export declare function retrieve<T>(ctx: SearchContext<T>, query: string, opts?: RetrieveOptions<T>): Promise<RetrieveHit<T>[]>;
+/** L2 — raw-vector kNN over the encrypted vector set (decrypted in the trusted tier).
+ *  Snippet is '' for vector hits in v1 (semantic match isn't span-located). */
+export declare function similarTo<T>(ctx: SearchContext<T>, vector: Float32Array, opts?: {
+    k?: number;
+    minScore?: number;
+    includeRecord?: boolean;
+}): Promise<RetrieveHit<T>[]>;
+/**
+ * L2 — the embedding write-hook: derive a record's embedding vector at
+ * write and persist it as the encrypted `_vec` side-car. Routed through the
+ * search strategy so it runs only when `withSearch()` is opted in — computing
+ * vectors that no gated `similarTo` / semantic `retrieve` could query would be
+ * dead weight, so the compute is paired with the search capability. The caller
+ * (`Collection.put`) only invokes this when `embeddings` is declared.
+ */
+export declare function embedOnWrite<T>(ctx: SearchContext<T>, id: string, record: T, version: number): Promise<void>;
+/**
+ * Force-re-derive every eligible tier-0 record's `_vec` sidecar once (#788).
+ * Opt-in bulk repair for the #726 re-namespace: legacy bare-id rows are
+ * unreachable to `buildVectorLoad` (it only recognises `<collection>/<id>`
+ * keys) and otherwise self-heal only when a record is next `put()` — this
+ * lets an adopter recover recall immediately instead of waiting on writes.
+ *
+ * **Skips elevated records** (`liveRecordIsElevated`) rather than refusing
+ * the whole walk — the OPPOSITE of `_applyCutoverTransform`'s
+ * `assertCutoverTierSafe` refuse-whole-batch precedent. An elevated record is
+ * SUPPOSED to have no `_vec` (`syncTierSearch` purges it on elevate);
+ * re-embedding one here would write searchable plaintext-derived data above
+ * tier 0. Load-bearing: never write a `_vec` row for an elevated record.
+ *
+ * Tombstones, delete markers, and a raw `get` racing a delete between `list`
+ * and `get` all decrypt to `null` (`decryptRecord` already folds
+ * tombstone/delete-marker into that null) and are skipped the same way.
+ * Unconditional re-derive, no already-migrated check — safe to re-run after
+ * a partial failure (each id is independently idempotent).
+ */
+export declare function rebuildEmbeddings<T>(ctx: SearchContext<T>): Promise<{
+    rebuilt: number;
+    skipped: number;
+}>;
+/**
+ * Sync the collection's SEARCH artifacts after a tier move (#721). Both the
+ * lexical `_ftindex` blob and the `_vec/<id>` embedding are encrypted under
+ * the tier-0 DEK and hold the record's derived plaintext (full field text /
+ * a text-invertible vector), so leaving them means elevation never hid what
+ * the record was searchable by — the `forget()` precedent, unapplied to
+ * elevate. `null` → the record left tier 0: purge its `_vec` sidecar (mirrors
+ * `Collection._purgeVector`), and invalidate the `_ftindex` blob (mirrors
+ * `Collection._purgeSearchIndex`: deletes the persisted blob when persisted,
+ * else drops the in-memory index) so the next `retrieve()` rebuilds from the
+ * elevated-free `ctx.cache`. A record → it is tier-0 again: re-embed it via
+ * {@link embedOnWrite}, then invalidate `_ftindex` so the rebuild includes it
+ * again. No-op fast when the collection has neither a lexical index nor a
+ * vector set.
+ */
+export declare function syncTierSearch<T>(ctx: SearchContext<T>, id: string, record: T | null, version?: number): Promise<void>;

package/dist/with-lookup/search/fuse.d.ts

@@ -0,0 +1,22 @@
+/**
+ * L3 — Reciprocal Rank Fusion. Merges N ranked `RetrieveHit` lists into
+ * one, scoring each id by Σ 1/(k + rank) across the lists it appears in. Pure,
+ * deterministic, no I/O — which is why it serves BOTH hybrid lexical⊕semantic
+ * fusion AND klum-db's cross-vault federation (the lists are per-vault). The
+ * fused `score` is the RRF score, NOT BM25 or cosine.
+ */
+import type { RetrieveHit } from './retrieve-types.js';
+export interface FuseOptions {
+    /** Only 'rrf' in v1 (default). */
+    readonly strategy?: 'rrf';
+    /** RRF constant; larger flattens the rank weighting. Default 60. */
+    readonly k?: number;
+    /** Truncate the fused output to this many hits. */
+    readonly limit?: number;
+}
+/**
+ * Callers must supply hits with `rank >= 1` (the retrieve contract guarantees
+ * it; a federation caller passing `rank: 0` with `k: 0` would divide by zero).
+ * Doc-only note — no runtime guard; rank ≥ 1 is the retrieve contract.
+ */
+export declare function fuseRetrieval<T>(lists: ReadonlyArray<ReadonlyArray<RetrieveHit<T>>>, opts?: FuseOptions): RetrieveHit<T>[];

package/dist/with-lookup/search/index-store.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The index persistence seam (L1.5). MemoryIndexStore is session-scoped and
+ * lazy; an opaque-blob backend implements the same interface so the
+ * collection call-site is unchanged.
+ */
+import { InvertedIndex, type IndexDoc } from './inverted-index.js';
+export interface IndexStore {
+    ensureBuilt(build: () => ReadonlyArray<IndexDoc>): Promise<InvertedIndex>;
+    markDirty(): void;
+    flush(): Promise<void>;
+    readonly built: boolean;
+}
+export declare class MemoryIndexStore implements IndexStore {
+    private index;
+    get built(): boolean;
+    ensureBuilt(build: () => ReadonlyArray<IndexDoc>): Promise<InvertedIndex>;
+    markDirty(): void;
+    flush(): Promise<void>;
+}

package/dist/with-lookup/search/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Search service — scan-mode full-text search.
+ *
+ * Tree-shakeable: only reaches the bundle when `collection.search()` is called.
+ * The store-usable blind index (SSE) is a separate, gated opt-in and not
+ * built here.
+ */
+export { tokenize, type Tokenizer } from './tokenize.js';
+export { searchScan, type SearchOptions, type SearchResult, type SearchEntry } from './scan.js';
+export { segmentTokens, segmentTokenizer, type Token } from './segment.js';
+export { InvertedIndex, type IndexDoc, type IndexHit, type QueryOptions } from './inverted-index.js';
+export { extractSnippet } from './snippet.js';
+export { MemoryIndexStore, type IndexStore } from './index-store.js';
+export { buildStringFieldEntries } from './build-docs.js';
+export type { RetrieveOptions, RetrieveHit } from './retrieve-types.js';
+export { fuseRetrieval, type FuseOptions } from './fuse.js';
+export { withSearch } from './active.js';
+export { NO_SEARCH, type SearchStrategy } from './strategy.js';
+export { SearchNotEnabledError } from '../../kernel/errors.js';

package/dist/with-lookup/search/inverted-index.d.ts

@@ -0,0 +1,47 @@
+export interface IndexDoc {
+    readonly id: string;
+    readonly fields: ReadonlyArray<{
+        readonly field: string;
+        readonly locale?: string;
+        readonly text: string;
+    }>;
+}
+export interface IndexHit {
+    readonly id: string;
+    readonly score: number;
+    readonly field: string;
+    readonly locale?: string;
+    readonly text: string;
+    readonly offset: number;
+}
+export interface QueryOptions {
+    readonly limit?: number;
+    readonly match?: 'any' | 'all';
+    readonly prefix?: boolean;
+    readonly fields?: readonly string[];
+}
+export interface IndexSnapshot {
+    readonly v: 1;
+    readonly fieldStats: ReadonlyArray<[string, {
+        df: [string, number][];
+        n: number;
+        totalLen: number;
+    }]>;
+    readonly docs: ReadonlyArray<{
+        id: string;
+        field: string;
+        locale?: string;
+        text: string;
+        len: number;
+        tf: [string, number][];
+        firstOffset: [string, number][];
+    }>;
+}
+export declare class InvertedIndex {
+    private readonly fieldStats;
+    private readonly docs;
+    static build(docs: ReadonlyArray<IndexDoc>): InvertedIndex;
+    query(query: string, opts?: QueryOptions): IndexHit[];
+    toSnapshot(): IndexSnapshot;
+    static fromSnapshot(s: IndexSnapshot): InvertedIndex;
+}

package/dist/with-lookup/search/persisted-index-store.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Persisted backend for the L1 lexical index (L1.5). Crypto-free: the
+ * collection injects load/save/remove + a fingerprint provider. In-memory while
+ * live (L1 behavior); persists an opaque snapshot via a debounced flush, and
+ * validates a loaded blob against a {count,maxVersion} fingerprint so a stale
+ * blob is never used — only rebuilt.
+ *
+ * #725: a debounced save (encrypt + adapter.put) racing a purge (removePersisted,
+ * called by elevate's tier purge and forget's erasure) is guarded by an epoch counter
+ * — see the `epoch` field doc for the mechanism and why it also closes the issue's
+ * variant (b) for free. Residual gap, structurally unavoidable without a durable
+ * write-ahead log: a process CRASH strictly between a stale save's `adapter.put`
+ * landing and its compensating `remove()` running (or between the compensating
+ * remove landing and `pendingCompensation` being persisted somewhere durable — it is
+ * in-memory only) leaves the resurrected blob at rest until the next natural
+ * rebuild-persist. This is on par with the gate-before-put optimization's own crash
+ * residual (a crash between `isStale()` returning false and the put landing) — both
+ * are eliminated only by making the purge and the save's commit point transactional
+ * with the store, which is out of scope for an in-memory debounce layer over an
+ * arbitrary opaque-blob backend.
+ */
+import { InvertedIndex, type IndexDoc } from './inverted-index.js';
+import type { IndexStore } from './index-store.js';
+export interface Fingerprint {
+    readonly count: number;
+    readonly maxVersion: number;
+}
+export interface PersistedIndexCallbacks {
+    load(): Promise<{
+        json: string;
+        fingerprint: Fingerprint;
+    } | null>;
+    /** `isStale()` reflects whether a purge (removePersisted) has landed since this
+     *  save's epoch was captured — check it AFTER any async encrypt step and BEFORE
+     *  the actual adapter.put, skipping the write when true (#725 review: shrinks the
+     *  at-rest window for purge-beats-encrypt orderings to zero). Belt-and-suspenders:
+     *  PersistedIndexStore's own post-save epoch check (persist(), below) is the
+     *  backstop that catches every other ordering, including a purge landing during
+     *  the put itself. */
+    save(json: string, fp: Fingerprint, isStale: () => boolean): Promise<void>;
+    remove(): Promise<void>;
+    currentFingerprint(): Fingerprint;
+    debounceMs?: number;
+}
+export declare class PersistedIndexStore implements IndexStore {
+    private readonly cb;
+    private index;
+    private timer;
+    private lastBuild;
+    private readonly debounceMs;
+    /**
+     * Bumped by every purge (removePersisted). A save() captured under a since-stale
+     * epoch undoes its own effect once it settles, however it interleaves with the
+     * purge's own delete — a delete can never be overtaken by a save that was
+     * scheduled before it (#725).
+     *
+     * Subsumes the issue's variant (b) (a stale, pre-purge in-memory index getting
+     * paired with a live, post-purge fingerprint and TRUSTED by a cold load, defeating
+     * the fingerprint backstop) for free — no separate handling needed: removePersisted()
+     * always resets `index` to undefined in the SAME synchronous step that bumps the
+     * epoch (below), and the only two paths that can repopulate `index` (ensureBuilt's
+     * cold rebuild, rebuildAndPersist's rebuild) do so strictly from `lastBuild()`, which
+     * the collection wires to read its LIVE cache at call time — not a frozen snapshot.
+     * Cache eviction (the collection dropping the purged/forgotten record) always
+     * precedes removePersisted() in both the elevate and forget call paths (#721's
+     * syncCache eviction / forget's tombstone write both land before syncSearch /
+     * _purgeSearchIndex runs). So any rebuild that executes strictly after
+     * removePersisted() — the only way `index` becomes defined again post-purge —
+     * necessarily observes the post-purge cache, and any rebuild that predates
+     * removePersisted() has its `index` wiped by it. There is no ordering in which a
+     * stale (pre-purge) index survives to be skip-rebuilt and persisted under a
+     * matching live fingerprint. Regression-pinned in
+     * `search-persisted-index-store.test.ts` ("variant (b) is subsumed...").
+     */
+    private epoch;
+    /**
+     * Set when a compensating/purging remove() (`compensate()` undoing a stale
+     * save, or `removePersisted()`'s own purge, #764) fails. Unlike the routine
+     * best-effort swallow on the debounced flush path (markDirty's timer
+     * .catch(), below — safe there because the fingerprint backstop forces a
+     * rebuild on the next cold load), a failed removal leaves a resurrected or
+     * un-purged blob at rest whose fingerprint can still match the live cache —
+     * a cold load would TRUST it, not rebuild past it. So this is never silently
+     * dropped: every subsequent store entrypoint (ensureBuilt, rebuildAndPersist,
+     * removePersisted) retries the remove first and refuses to proceed past it
+     * until it succeeds (#725 review), and the raw adapter error is wrapped in
+     * {@link PersistedIndexCompensationError} (#764) so a caller can catch a
+     * stuck removal deliberately instead of an indistinguishable adapter error.
+     * A crash between a landed put and its compensating remove (before this
+     * flag or a retry can run) is a residual gap — see the class doc.
+     */
+    private pendingCompensation;
+    constructor(cb: PersistedIndexCallbacks);
+    get built(): boolean;
+    ensureBuilt(build: () => ReadonlyArray<IndexDoc>): Promise<InvertedIndex>;
+    markDirty(): void;
+    /** Force an immediate persist (cancels any pending debounce). */
+    flush(): Promise<void>;
+    /** Delete the persisted blob and drop the in-memory index (forget/erasure/tier
+     *  move). A failed purge is wrapped in {@link PersistedIndexCompensationError}
+     *  (#764) and left sticky (`pendingCompensation`) so the next store entrypoint
+     *  retries it — never silently dropped, same posture #725 established for a
+     *  stale save's own compensating remove. */
+    removePersisted(): Promise<void>;
+    /** Rebuild using the last known build thunk, then persist. */
+    private rebuildAndPersist;
+    /** Persist the current index, then undo it if a purge (removePersisted) landed
+     *  while the save was in flight — a delete can never be overtaken by a save
+     *  that was scheduled before it (#725). A failed undo does not silently vanish:
+     *  see `pendingCompensation`. */
+    private persist;
+    /** Undo a stale save. Failure is sticky, not swallowed: see `pendingCompensation`.
+     *  Wraps the raw adapter error in {@link PersistedIndexCompensationError} (#764) so
+     *  a caller (e.g. the tier ops' `syncTierSearch`) can catch a stuck compensation
+     *  deliberately instead of treating it as an indistinguishable adapter failure. */
+    private compensate;
+    /** Retries a sticky compensation before any store entrypoint proceeds. Failure
+     *  re-wraps the raw adapter error the same way `compensate()` does (#764) — the
+     *  flag stays set (untouched here) so the NEXT entrypoint retries again. */
+    private retryPendingCompensation;
+}

package/dist/with-lookup/search/retrieve-types.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Public option / result types for `collection.retrieve()` (L1). Kept in
+ * the search service so collection.ts holds only thin call-sites; re-exported
+ * from the search barrel and the hub root.
+ */
+import type { Query } from '../../kernel/query/builder.js';
+export interface RetrieveOptions<T = unknown> {
+    readonly limit?: number;
+    readonly match?: 'any' | 'all';
+    readonly prefix?: boolean;
+    readonly snippetWindow?: number;
+    readonly fields?: readonly string[];
+    readonly includeRecord?: boolean;
+    /** Retrieval strategy; defaults to 'lexical'. 'hybrid' fuses lexical+semantic (L3). */
+    readonly mode?: 'lexical' | 'semantic' | 'hybrid';
+    /** L2 — minimum cosine score for semantic hits (semantic mode only). */
+    readonly minScore?: number;
+    /** L3 — intersect hits with a structured query (retrieve ∩ where). Eager-mode only. */
+    readonly within?: Query<T>;
+}
+export interface RetrieveHit<T> {
+    readonly id: string;
+    readonly score: number;
+    readonly rank: number;
+    readonly field: string;
+    readonly snippet: string;
+    readonly locale?: string;
+    readonly record?: T;
+}

package/dist/with-lookup/search/scan.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Scan-mode full-text search — ranks **already-decrypted** records by
+ * BM25 against a tokenized query. Pure client-side: nothing is written to the
+ * store, so this adds **zero** leakage (unlike a store-usable blind index,
+ * which is a separate, gated opt-in).
+ *
+ * O(n) over the collection; intended for small/medium collections (the pilot's
+ * scale) where moving the existing userland scan into the DB is the win.
+ */
+import { type Tokenizer } from './tokenize.js';
+export interface SearchOptions {
+    /** Top-N by score (default: all matches). */
+    readonly limit?: number;
+    /** `'any'` (default) = OR of query terms; `'all'` = every term must match. */
+    readonly match?: 'any' | 'all';
+    /** Treat the LAST query term as a prefix (typeahead). */
+    readonly prefix?: boolean;
+}
+export interface SearchResult<T> {
+    readonly id: string;
+    readonly score: number;
+    readonly record: T;
+}
+export interface SearchEntry<T> {
+    readonly id: string;
+    readonly record: T;
+}
+export declare function searchScan<T>(entries: ReadonlyArray<SearchEntry<T>>, field: string, query: string, opts?: SearchOptions, tokenizer?: Tokenizer): SearchResult<T>[];

package/dist/with-lookup/search/segment.d.ts

@@ -0,0 +1,15 @@
+/**
+ * i18n word tokenizer for the L1 lexical index. Uses Intl.Segmenter
+ * (standard ECMAScript — hub-portable) to dictionary-segment Thai/Lao/Khmer/CJK,
+ * which the word-run `tokenize` cannot. Terms are matched in NFKC-lowercased form;
+ * offsets index the ORIGINAL text so snippets slice the user's text.
+ */
+import type { Tokenizer } from './tokenize.js';
+export interface Token {
+    readonly term: string;
+    readonly offset: number;
+}
+/** Word-like tokens with NFKC-lowercased terms + original-text char offsets. */
+export declare const segmentTokens: (text: string) => Token[];
+/** Term-only tokenizer (the public `Tokenizer` shape) — for queries. */
+export declare const segmentTokenizer: Tokenizer;

package/dist/with-lookup/search/serialize.d.ts

@@ -0,0 +1,4 @@
+/** (De)serialize an InvertedIndex to/from a JSON string for persistence (L1.5). */
+import { InvertedIndex } from './inverted-index.js';
+export declare function serializeIndex(idx: InvertedIndex): string;
+export declare function deserializeIndex(json: string): InvertedIndex;

package/dist/with-lookup/search/snippet.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Minimal-disclosure snippet: a char-window around a match offset (L1).
+ * Unicode-safe (operates on code points). `…` marks each truncated end.
+ */
+export declare function extractSnippet(text: string, offset: number, window?: number): string;

package/dist/with-lookup/search/strategy.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Search capability strategy — the on-demand collection-level retrieval
+ * operations the `Collection` routes through: scan-mode full-text `search`,
+ * unified `retrieve` (lexical | semantic | hybrid), raw-vector `similarTo`, and
+ * the lexical-index lifecycle (`warmIndex` / `flushIndex`). The active engine
+ * ({@link withSearch}) dynamically imports the search/retrieval facade (keeping
+ * it out of the floor bundle); {@link NO_SEARCH} throws.
+ *
+ * The embedding write-hook (`embedOnWrite`) is paired here too: opting into
+ * `withSearch()` enables both the query surface AND the put()-time vector
+ * compute — a vector that no gated `similarTo` / semantic `retrieve` could read
+ * is dead weight, so embedding compute is not separately gatable. `Collection`
+ * always assembles the per-call {@link SearchContext} and delegates here, so an
+ * un-opted-in caller hits `NO_SEARCH`'s throw.
+ * @internal
+ */
+import type { SearchContext } from './collection-facade.js';
+import type { SearchOptions, SearchResult } from './index.js';
+import type { RetrieveOptions, RetrieveHit } from './retrieve-types.js';
+export interface SearchStrategy {
+    search<T>(ctx: SearchContext<T>, field: string, query: string, opts?: SearchOptions): Promise<SearchResult<T>[]>;
+    retrieve<T>(ctx: SearchContext<T>, query: string, opts?: RetrieveOptions<T>): Promise<RetrieveHit<T>[]>;
+    similarTo<T>(ctx: SearchContext<T>, vector: Float32Array, opts?: {
+        k?: number;
+        minScore?: number;
+        includeRecord?: boolean;
+    }): Promise<RetrieveHit<T>[]>;
+    warmIndex<T>(ctx: SearchContext<T>): Promise<void>;
+    flushIndex<T>(ctx: SearchContext<T>): Promise<void>;
+    embedOnWrite<T>(ctx: SearchContext<T>, id: string, record: T, version: number): Promise<void>;
+    rebuildEmbeddings<T>(ctx: SearchContext<T>): Promise<{
+        rebuilt: number;
+        skipped: number;
+    }>;
+}
+/**
+ * No-op stub — the floor default. Every capability method (and the embedding
+ * write-hook) throws {@link SearchNotEnabledError}; opt in with
+ * `searchStrategy: withSearch()` in createNoydb. @internal
+ */
+export declare const NO_SEARCH: SearchStrategy;

package/dist/with-lookup/search/tokenize.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Default text tokenizer for scan-mode search.
+ *
+ * NFKC-normalize → lowercase → split on Unicode letter/number runs. This is a
+ * word-boundary tokenizer: it does **not** segment scripts written without
+ * inter-word spaces (Thai, Lao, Khmer, CJK) — those collapse to one token per
+ * run. For such data, a dictionary/ICU segmenter is the right `tokenizer`
+ * (the engine takes one as a parameter); substring/`contains` matching is the
+ * pragmatic fallback until then.
+ */
+export type Tokenizer = (text: string) => string[];
+export declare const tokenize: Tokenizer;

package/dist/with-party/auth-introspection/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Authentication introspection.
+ *
+ * Three surfaces over the configured tier model and the actual
+ * per-user enrollment state:
+ *
+ * 1. **Vault-wide English summary** — {@link describeAuthConfig}.
+ * 2. **Vault-wide Mermaid diagram** — {@link diagramAuthConfig}.
+ * 3. **Per-user introspection** — {@link describeUserAuth}, gated by
+ *    the `view-user-auth` policy gate (off by default).
+ *
+ * The per-user surface is held to a strict allowlist — fields not on
+ * the allowlist are dropped, never rendered. The negative test in
+ * `auth-introspection.test.ts` exercises the allowlist by feeding a
+ * contrived keyring with fake "secret" fields and asserting that none
+ * of them appear in the output.
+ *
+ * @module
+ */
+import type { NoydbStore } from '../../kernel/types.js';
+/** Vault-wide English summary of the configured authentication graph. */
+export declare function describeAuthConfig(store: NoydbStore, vault: string): Promise<string>;
+/**
+ * Render the vault's auth graph as Mermaid `flowchart TB` source. The
+ * caller pipes this through Mermaid (CLI or browser) to get an SVG.
+ */
+export declare function diagramAuthConfig(store: NoydbStore, vault: string): Promise<string>;
+/**
+ * Render the per-user enrollment summary. Returns an empty
+ * (non-throwing) string when the user has no keyring file — never
+ * confirms or denies the existence of the user from the document
+ * alone.
+ *
+ * Sanitization is strict: only the slot list, enrollment dates, and
+ * recovery-profile counts are rendered. WebAuthn cred ids, OIDC
+ * subject ids, password hashes, recovery codes, TOTP secrets — all
+ * dropped at the allowlist boundary, not redacted.
+ */
+export declare function describeUserAuth(store: NoydbStore, vault: string, userId: string): Promise<string>;
+/** Bulk variant for owner dashboards. */
+export declare function describeAllUsersAuth(store: NoydbStore, vault: string): Promise<Array<{
+    userId: string;
+    description: string;
+}>>;

package/dist/with-party/broker/active.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Enable the credential-broker capability (#479, spec §5).
+ *
+ * Pass to `createNoydb({ brokerStrategy: withBroker(config) })` to make
+ * `vault.broker()` live. Each method dynamic-imports the seed lifecycle
+ * engine (`./seed.js`) — mirroring `via/classified/active.ts`'s per-method
+ * dynamic-import seam — so `with-party/broker/seed.ts` (the heavy module:
+ * the CAS enrol, quiesce-then-swap rotate, and the challenge/response round
+ * trip) is reachable only through the `@noy-db/hub/broker` subpath and
+ * never enters the single-user floor bundle.
+ *
+ * The single-flight, per-vault-per-profile refresh cache (H-6/I6) lives
+ * HERE, in this factory's closure — shared across every `credentialSource(profile)`
+ * call for this one broker instance (in turn shared across every vault of a
+ * `createNoydb()` instance — `vault.broker()` passes the SAME `BrokerStrategy`
+ * for all of them), so `rotate()` can quiesce it (await any in-flight
+ * round-trip, then drop it) before the seed swap. The cache key is
+ * `${vault}\0${profile}` — keyed by vault FIRST, or two vaults sharing this
+ * one strategy would collide and hand vault-B a cached credential minted
+ * (and STS-scoped) for vault-A.
+ */
+import type { BrokerStrategy, BrokerConfig } from '../../port/with/broker-strategy.js';
+export declare function withBroker(config: BrokerConfig): BrokerStrategy;

package/dist/with-party/broker/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `@noy-db/hub/broker` — subpath export for the credential-broker capability
+ * (#479, credential-broker spec). Apps that never call `vault.broker()` can
+ * exclude this subpath entirely: the floor default `NO_BROKER` throws, and
+ * this module's real engine (`with-party/broker/{seed,active}.ts`) is only
+ * ever reached through `withBroker()`'s dynamic imports, so it never enters
+ * a floor bundle.
+ *
+ * Also re-exports the host-side helpers (`issueChallenge`, `verifyBrokerProof`)
+ * from the enclave barrel, so a Lambda/Worker implementing the reference
+ * broker host can import just this one subpath and get everything it
+ * needs, `crypto.subtle`-only.
+ */
+export { withBroker } from './active.js';
+export { NO_BROKER, type BrokerStrategy, type BrokerCtx, type BrokerConfig, type CredentialBrokerHandle, } from '../../port/with/broker-strategy.js';
+export { BrokerNotEnabledError, BrokerEnrolmentError, BrokerProofError } from '../../kernel/errors.js';
+import { verifyBrokerProof } from '../../kernel/enclave/index.js';
+import type { IssuedChallenge, VerifyBrokerProofArgs } from '../../kernel/enclave/index.js';
+/**
+ * {@link issueChallengeRaw} (the enclave's mechanical primitive) with a
+ * `[10s, 60s]` TTL clamp applied, so a reference host built on this barrel
+ * gets a safe challenge TTL without having to know the bounds itself.
+ */
+export declare function issueChallenge(opts?: {
+    ttlMs?: number;
+}): IssuedChallenge;
+export { verifyBrokerProof };
+export type { VerifyBrokerProofArgs };