@noy-db/hub 0.3.0-pre.10 → 0.3.0-pre.12

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

@@ -0,0 +1,56 @@
+/**
+ * Strategy seam between core Collection and the optional indexing
+ * service. Core imports `IndexStrategy` and `IndexState` as
+ * TYPE-ONLY symbols and `NO_INDEXING` as a tiny runtime stub.
+ *
+ * The heavy classes — `CollectionIndexes`, `PersistedCollectionIndex`,
+ * `LazyQuery` — are only instantiated inside the `withIndexing()`
+ * factory under `./active.ts`, which in turn is only reachable through
+ * the `@noy-db/hub/indexing` subpath export. A consumer that never
+ * imports the subpath ships none of those classes in their bundle
+ * (ESM tree-shaking + hub's `"sideEffects": false`).
+ *
+ * @internal
+ */
+import type { CollectionIndexes, IndexDef } from './eager-indexes.js';
+import type { PersistedCollectionIndex } from './persisted-indexes.js';
+/**
+ * Per-collection container for whatever mirrors the active strategy
+ * decided to materialize. Both accessors may return `null` — they do
+ * for `NO_INDEXING`, and `getEagerIndexes` returns null in a
+ * lazy-mode collection even when indexing is active (lazy uses the
+ * persisted mirror instead).
+ *
+ * `isEnabled` is a cheap guard so collection code can short-circuit
+ * the full indexing path without inspecting either mirror.
+ *
+ * @internal
+ */
+export interface IndexState {
+    readonly isEnabled: boolean;
+    getEagerIndexes(): CollectionIndexes | null;
+    getPersistedIndexes(): PersistedCollectionIndex | null;
+}
+/**
+ * Factory that builds one `IndexState` per Collection. Called exactly
+ * once inside each Collection constructor with the declared
+ * `IndexDef[]` and the lazy-mode flag (so lazy collections get the
+ * persisted mirror and eager collections get the in-memory one).
+ *
+ * @internal
+ */
+export interface IndexStrategy {
+    createState(args: {
+        readonly defs: readonly IndexDef[];
+        readonly lazy: boolean;
+    }): IndexState;
+}
+/**
+ * No-indexing stub. Every Collection defaults to this; it returns a
+ * cheap `IndexState` whose mirrors are both `null`. Collection code
+ * null-checks both accessors and short-circuits, so no indexing code
+ * path runs and the heavy classes never arrive in the bundle.
+ *
+ * @internal
+ */
+export declare const NO_INDEXING: IndexStrategy;

package/dist/with-lookup/indexing/unique-constraints.d.ts

@@ -0,0 +1,74 @@
+/**
+ * In-memory unique-constraint enforcement for eager-mode collections.
+ *
+ * Each `UniqueConstraintSet` holds one or more constraints, each covering
+ * an ordered tuple of field names. On every `put()` the caller invokes
+ * `check()` BEFORE the store write; on success it calls `upsert()` to
+ * update the maps. `remove()` is called on `delete()`.
+ *
+ * Null-distinct semantics: if ANY constrained field is `null` or
+ * `undefined` in the record, that record is exempt from the constraint —
+ * `keyFor` returns `null` and the record is silently skipped.
+ * This matches standard SQL NULL-distinct behavior.
+ *
+ * Only used in eager mode (`prefetch !== false`). Lazy-mode collections
+ * throw at registration instead (see Collection constructor).
+ */
+import type { IndexDef } from './eager-indexes.js';
+export declare class UniqueConstraintSet {
+    private readonly collectionName;
+    private readonly constraints;
+    constructor(collectionName: string, uniqueDefs: readonly (readonly string[])[]);
+    get size(): number;
+    /**
+     * Compute the canonical key for a record under a given constraint.
+     * Returns `null` if any constrained field is `null` or `undefined`
+     * (the record is exempt — no constraint is checked).
+     */
+    private keyFor;
+    /**
+     * Throw `UniqueConstraintError` if writing `id` with `record` would
+     * collide with a DIFFERENT existing record. Call BEFORE the store write.
+     */
+    check(id: string, record: unknown): void;
+    /**
+     * Update the constraint maps after a successful write.
+     * Pass `previous` when updating an existing record (so the old key
+     * is removed first). Pass `null` or `undefined` for a fresh insert.
+     */
+    upsert(id: string, record: unknown, previous?: unknown): void;
+    /**
+     * Remove a record from all constraint maps.
+     * Called by `Collection.delete()`.
+     */
+    remove(id: string, record: unknown): void;
+    /**
+     * Rebuild all constraint maps from a full snapshot.
+     * Called after hydration (ensureHydrated / hydrateFromSnapshot).
+     *
+     * **Last-writer-wins**: this method does NOT validate pre-existing data
+     * for duplicates. If the store already contains two records sharing a
+     * constrained value (written before the unique index was declared), the
+     * last one processed wins the map slot and the duplicate is silently
+     * displaced — no error is thrown, and the earlier holder is evicted from
+     * the map. Callers retrofitting a unique index onto populated data should
+     * run a one-time uniqueness scan before relying on enforcement.
+     */
+    build(entries: Iterable<readonly [string, unknown]>): void;
+}
+/**
+ * Build the `UniqueConstraintSet` for a collection from its `IndexDef[]`,
+ * or return `null` when no `unique: true` index is declared.
+ *
+ * Unique enforcement is **eager-mode only**. If any `unique` index is
+ * declared on a lazy (`prefetch:false`), CRDT, or tiered collection, this
+ * throws `UnsupportedIndexOptionError` at registration rather than letting
+ * those write paths (which bypass `check()`/`upsert()`) silently skip
+ * enforcement. Kept out of the Collection constructor to keep that
+ * always-on kernel file lean (kernel-surface invariant).
+ */
+export declare function buildUniqueConstraintSet(collectionName: string, indexes: readonly IndexDef[] | undefined, mode: {
+    readonly lazy: boolean;
+    readonly crdt: boolean;
+    readonly tiered: boolean;
+}): UniqueConstraintSet | null;

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

@@ -0,0 +1,10 @@
+/**
+ * Enable the search / retrieval capability.
+ * Pass to `createNoydb({ searchStrategy: withSearch() })` to make a collection's
+ * `search` / `retrieve` / `similarTo` / `warmIndex` / `flushIndex` methods live,
+ * and to enable the put()-time embedding-vector compute for collections that
+ * declare an `embeddings` config. The search/retrieval engine is dynamically
+ * imported here, so it stays out of the floor bundle until opted in.
+ */
+import type { SearchStrategy } from './strategy.js';
+export declare function withSearch(): SearchStrategy;

package/dist/with-lookup/search/build-docs.d.ts

@@ -0,0 +1,15 @@
+import type { I18nTextDescriptor } from '../../via/i18n/core.js';
+import type { DictKeyDescriptor, StaticDictDescriptor } from '../../via/i18n/dictionary.js';
+import type { IndexDoc } from './inverted-index.js';
+type FieldEntry = IndexDoc['fields'][number];
+export declare function buildStringFieldEntries(record: Record<string, unknown>, textIndexes: readonly string[], only?: readonly string[]): FieldEntry[];
+export declare function buildI18nFieldEntries(record: Record<string, unknown>, i18nFields: Record<string, I18nTextDescriptor>, textIndexes: readonly string[], only?: readonly string[]): FieldEntry[];
+/** label map: field -> (key -> { locale -> label }). Precomputed in the collection (async for dynamic dicts). */
+export declare function buildDictKeyFieldEntries(record: Record<string, unknown>, dictKeyFields: Record<string, DictKeyDescriptor | StaticDictDescriptor>, labelMaps: Map<string, Map<string, Record<string, string>>>, textIndexes: readonly string[], only?: readonly string[]): FieldEntry[];
+/**
+ * Blob filenames precomputed in the collection (`field -> filenames[]`, from one
+ * async `listSlots()` per record — the heaviest source, see {@link buildBlobFieldEntries}'s
+ * caller). Bytes are never tokenized; only the slot `filename` is indexed.
+ */
+export declare function buildBlobFieldEntries(filenamesByField: Map<string, string[]>): FieldEntry[];
+export {};

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

@@ -0,0 +1,123 @@
+/**
+ * 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>;

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,41 @@
+/**
+ * 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.
+ */
+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>;
+    save(json: string, fp: Fingerprint): 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;
+    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). */
+    removePersisted(): Promise<void>;
+    /** Rebuild using the last known build thunk, then persist. */
+    private rebuildAndPersist;
+    private persist;
+}

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,37 @@
+/**
+ * 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>;
+}
+/**
+ * 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;