@noy-db/hub 0.7.1-pre.0 → 0.8.0

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

@@ -14,7 +14,26 @@
  */
 import type { Reduction, ReduceSpec, ReduceResult, ReductionUpstream } from './reduction.js';
 import type { GroupedQuery, GroupedQueryN } from './groupby.js';
+import type { GroupMaintenanceSource } from '../../kernel/query/live/incremental.js';
+import type { WindowFactory, WindowSpec, WindowedQuery } from './window.js';
+/**
+ * Re-exported so `kernel/query/builder.ts` can name `.window()`'s spec and
+ * return type WITHOUT a second spine→service import specifier: this strategy
+ * module is the seam the kernel is allowed to reach (`check-architecture.mjs`
+ * → PRE_EXISTING_SPINE_SERVICE_IMPORTS), and adding a new grandfathered path
+ * there for a type-only import would loosen the ratchet for no gain.
+ */
+export type { WindowSpec, WindowedQuery } from './window.js';
+/**
+ * Options for {@link withReduce}. `window` is the {@link WindowFactory}
+ * returned by `withWindow()` — omitted, `.window()` throws and the window
+ * engine stays out of the bundle entirely (see `window.ts` § "Opting in").
+ */
+export interface ReduceOptions {
+    readonly window?: WindowFactory;
+}
 import type { ViaPipeline } from '../../kernel/via/pipeline.js';
+import type { HydrationGate } from '../../kernel/query/hydration.js';
 /**
  * Seam interface. `@internal` — will promote to public only when the
  * aggregate service is extracted into its own package.
@@ -28,19 +47,40 @@ export interface ReduceStrategy {
      * reduction runs. NO_REDUCE throws; the active strategy
      * constructs a real `Reduction`.
      */
-    aggregate<Spec extends ReduceSpec>(executeRecords: () => readonly unknown[], spec: Spec, upstreams: readonly ReductionUpstream[]): Reduction<ReduceResult<Spec>>;
+    aggregate<Spec extends ReduceSpec>(executeRecords: () => readonly unknown[], spec: Spec, upstreams: readonly ReductionUpstream[], 
+    /** #1414 — the source collection's cold gate, when there is one. */
+    gate?: HydrationGate): Reduction<ReduceResult<Spec>>;
     /**
      * Build a `GroupedQuery<T, F, S>` for `Query.groupBy(field)`. Same
      * closure / upstream inputs as `aggregate` plus the group key field.
      */
-    groupBy<T, F extends string, S extends keyof T = never, M extends keyof T & string = never>(executeRecords: () => readonly unknown[], field: F, upstreams: readonly ReductionUpstream[], dictLabelResolver?: (key: string, locale: string, fallback?: string | readonly string[]) => Promise<string | undefined>, via?: ViaPipeline): GroupedQuery<T, F, S, M>;
+    groupBy<T, F extends string, S extends keyof T = never, M extends keyof T & string = never>(executeRecords: () => readonly unknown[], field: F, upstreams: readonly ReductionUpstream[], dictLabelResolver?: (key: string, locale: string, fallback?: string | readonly string[]) => Promise<string | undefined>, via?: ViaPipeline, 
+    /**
+     * #1341 (grouped half) — the delta-maintenance seam. Supplied by
+     * `Query.groupBy()` only for a plan `canMaintainIncrementally()` admits;
+     * omitted, `.groupBy().aggregate().live()` re-runs in full as before.
+     */
+    maintenance?: GroupMaintenanceSource): GroupedQuery<T, F, S, M>;
     /**
      * Variadic-keyed sibling — builds a `GroupedQueryN<T, F, S>` for
      * `Query.groupBy(...fields)`. No dictLabelResolver — `<field>Label`
      * projection only applies to single-field groupings, which dispatch
      * through `groupBy` above.
      */
-    groupByN<T, F extends readonly string[], S extends keyof T = never, M extends keyof T & string = never>(executeRecords: () => readonly unknown[], fields: F, upstreams: readonly ReductionUpstream[], via?: ViaPipeline): GroupedQueryN<T, F, S, M>;
+    groupByN<T, F extends readonly string[], S extends keyof T = never, M extends keyof T & string = never>(executeRecords: () => readonly unknown[], fields: F, upstreams: readonly ReductionUpstream[], via?: ViaPipeline, 
+    /** #1341 (grouped half) — see `groupBy` above. */
+    maintenance?: GroupMaintenanceSource): GroupedQueryN<T, F, S, M>;
+    /**
+     * Build a `WindowedQuery<T>` for `Query.window(spec)` (#1349). Same closure
+     * / upstream inputs as `groupBy`, plus the window definition. The Via
+     * pipeline is threaded so `.select()` gets the same money/distinct reducer
+     * rewriting `.aggregate()` gets.
+     *
+     * Throws unless the strategy was built as `withReduce({ window: withWindow() })`
+     * — the second opt-in exists so the window engine is not charged to a
+     * consumer who only aggregates. See `window.ts` § "Opting in".
+     */
+    window<T>(executeRecords: () => readonly unknown[], spec: WindowSpec, upstreams: readonly ReductionUpstream[], via?: ViaPipeline): WindowedQuery<T>;
     /**
      * Terminal streaming aggregator for `ScanBuilder.aggregate(spec)`.
      * Takes an async iterable of decrypted records + the spec and

package/dist/with-lookup/reduce/window.d.ts

@@ -0,0 +1,262 @@
+/**
+ * Query DSL `.window()` — SQL window functions over the query's result rows
+ * (#1349).
+ *
+ * ```ts
+ * invoices.query()
+ *   .where('status', '==', 'open')
+ *   .window({ partitionBy: 'clientId', orderBy: 'date' })
+ *   .select({ balance: runningSum('amount'), prev: lag('amount', 1), n: rowNumber() })
+ *   .run()
+ * ```
+ *
+ * Pure in-hub post-processing: the store holds ciphertext, so this runs after
+ * decryption like every other query stage. No index is consulted — see
+ * "Complexity" below for why the sorted-index fast path is deliberately not
+ * taken in v1.
+ *
+ * ## What it is, precisely
+ *
+ * A window function adds COLUMNS to a row; it never adds, removes or reorders
+ * rows. `.select()` therefore returns the query's own rows, in the query's own
+ * order, each widened with the window outputs. `orderBy` inside `.window()`
+ * decides how a PARTITION is walked; `Query.orderBy()` decides how the RESULT
+ * is presented. That is SQL's split and both are honoured independently.
+ *
+ * ⭐ Distinguished from `.groupBy()` by ARITY: `.groupBy().aggregate()` emits
+ * one row per bucket and drops the source rows; `.window().select()` keeps
+ * every source row and attaches per-row values computed over its partition.
+ *
+ * ## The frame — `rows unbounded preceding → current row`, and only that
+ *
+ * A running aggregate at position `i` of its partition sees exactly rows
+ * `0..i`. There is no `RANGE`, no `n preceding`, no `following`, and no
+ * `frame` option to pass — explicit frames are a separate feature, and a
+ * half-built frame surface is worse than none. `lag`/`lead` are navigation,
+ * not aggregation, so they are unaffected by the frame.
+ *
+ * ## Ordering inside a partition is TOTAL
+ *
+ * Rows are sorted by the `orderBy` keys and, where those compare equal, by
+ * their UPSTREAM POSITION — the sort is a stable sort over an ascending index
+ * array, so equal keys keep the order the query produced them in. Without that
+ * final key, `lag`/`lead` over equal keys would be a coin flip between runs.
+ *
+ * The value comparator is {@link compareReduced}, shared with the post-group
+ * ordering of #1336 rather than reinvented, and for the same reason: a money
+ * value reaches this stage DECODED, as an exact decimal string, and lexical
+ * order gets `'9882.00'` vs `'10004.00'` backwards. (The pre-group row
+ * pipeline asks `ViaPipeline.compareForOrder` instead — that reads the STORED
+ * scaled-integer form, which is not what a decoded row holds, so it cannot
+ * serve here.)
+ *
+ * PEER-ship for `rank` is decided by the `orderBy` keys ALONE, never by the
+ * upstream tie-break — otherwise no two rows would ever be peers and `rank`
+ * would collapse into `rowNumber`.
+ *
+ * ## Complexity, and the index question
+ *
+ * O(n log n): one partition pass, then a sort per partition. #1344's sorted
+ * indexes could in principle make the sort a merge, but the input here is the
+ * query's already-materialised, already-DECODED result rows — the index is
+ * over stored (encoded) values on the collection, and it has no way to express
+ * "sorted within each partition of `clientId`". Taking a fast path would mean
+ * proving identical output including the upstream tie-break, which the index
+ * cannot witness. So v1 sorts. This is the correct path, not a placeholder.
+ *
+ * ## Opting in — and why there is a second opt-in at all
+ *
+ * `withReduce()` alone does NOT light this up: `.window()` throws until the
+ * strategy is built as `withReduce({ window: withWindow() })`. That is not
+ * ceremony for its own sake — it is the SAME no-op-stub-until-opted-in rule
+ * that keeps `Reduction`/`GroupedQuery` out of the floor bundle, applied one
+ * level down. `withReduce()`'s returned object is a live value the bundler
+ * cannot prove unused, so a `window()` method that named {@link WindowedQuery}
+ * directly made this whole engine reachable from `withReduce` and charged it
+ * to every consumer who opted into ordinary aggregation and will never call
+ * `.window()`. Measured: the `analytics` bundle scenario went 960 → 1,845
+ * gzipped bytes, +92%. Passing the factory in means the engine is reachable
+ * only from a consumer that names `withWindow`.
+ * ⛔ Do not "simplify" this back into `withReduce()` — `check-bundle.mjs`'s
+ * `analytics` scenario carries a `WindowedQuery` eager-import canary that will
+ * fail if you do.
+ *
+ * ## Not in `explain()`
+ *
+ * Same shape as #1336's post-group ops: `explain()` is a terminal on `Query`,
+ * and `.window()` leaves `Query` for `WindowedQuery`, so there is no
+ * `explain()` in the chain past this point to add a node to. The window stage
+ * also has nothing to choose — one dispatch, over rows already in memory.
+ */
+import type { Reducer } from './reducers.js';
+import type { ReductionUpstream, LiveReduction } from './reduction.js';
+import type { DateTruncKey } from '../../kernel/query/reduce/date-trunc.js';
+import type { MoneyString } from '../../via/money/branded.js';
+import type { ViaPipeline } from '../../kernel/via/pipeline.js';
+/** One ordering key inside a window: a field name, a `dateTrunc()` key, or either with a direction. */
+export type WindowOrderInput<F extends string = string> = F | DateTruncKey | {
+    readonly field: F | DateTruncKey;
+    readonly direction?: 'asc' | 'desc';
+};
+/**
+ * The window definition passed to `.window()`.
+ *
+ * Both members are optional and mean what SQL's omissions mean: no
+ * `partitionBy` is one partition holding the whole relation; no `orderBy`
+ * makes every row in a partition a peer (so `rank()` is 1 throughout and a
+ * running aggregate sees the rows in upstream order).
+ */
+export interface WindowSpec<F extends string = string> {
+    /** Field name(s) and/or `dateTrunc()` key(s) to partition on. */
+    readonly partitionBy?: F | DateTruncKey | readonly (F | DateTruncKey)[];
+    /** How each partition is walked. Successive keys are tie-breakers. */
+    readonly orderBy?: WindowOrderInput<F> | readonly WindowOrderInput<F>[];
+}
+/**
+ * A non-aggregating window function (ranking or navigation). Built by the
+ * factories below — the shape is opaque to consumers.
+ */
+export interface WindowFn<R = unknown> {
+    readonly __window: true;
+    readonly op: 'rowNumber' | 'rank' | 'lag' | 'lead';
+    /**
+     * Compute one value per row of an ORDERED partition.
+     * `peerStart[i]` is the index of the first row that compares equal to row
+     * `i` under the window's `orderBy` keys.
+     */
+    evaluate(rows: readonly unknown[], peerStart: readonly number[]): R[];
+}
+/**
+ * A `.select()` slot: either a window function or an ordinary {@link Reducer},
+ * which runs as a RUNNING aggregate under the v1 frame. Any reducer works —
+ * `count()`, `sum()`, `countDistinct()`, a custom one — so `runningSum` and
+ * `runningMoneySum` below are named conveniences, not a separate mechanism.
+ */
+export type WindowSelectSpec = Readonly<Record<string, WindowFn<unknown> | Reducer<unknown, unknown>>>;
+/** Result type of one `.select()` slot. */
+type WindowSlotResult<V> = V extends WindowFn<infer R> ? R : V extends Reducer<infer R, unknown> ? R : unknown;
+/** A window result row: the source record widened with the selected outputs. */
+export type WindowRow<T, Spec extends WindowSelectSpec> = T & {
+    [K in keyof Spec]: WindowSlotResult<Spec[K]>;
+};
+/**
+ * Sequential position of the row within its partition, starting at 1. NEVER
+ * repeats — two rows that tie under `orderBy` still get distinct numbers,
+ * resolved by the upstream tie-break. Use {@link rank} when ties should share
+ * a number.
+ */
+export declare function rowNumber(): WindowFn<number>;
+/**
+ * Competition rank within the partition, starting at 1. Rows that compare
+ * EQUAL under the window's `orderBy` keys share a rank, and the next distinct
+ * value SKIPS the ranks they consumed — `1, 2, 2, 4`. This is the only place
+ * `rank` and {@link rowNumber} differ, so a fixture without ties cannot tell
+ * them apart.
+ *
+ * With no `orderBy` every row is a peer and every rank is 1.
+ */
+export declare function rank(): WindowFn<number>;
+/**
+ * Value of `field` from the row `offset` positions EARLIER in the partition.
+ * Returns `defaultValue` (default `undefined`) for the first `offset` rows.
+ */
+export declare function lag<R = unknown>(field: string, offset?: number, defaultValue?: R): WindowFn<R | undefined>;
+/**
+ * Value of `field` from the row `offset` positions LATER in the partition.
+ * Returns `defaultValue` (default `undefined`) for the last `offset` rows.
+ */
+export declare function lead<R = unknown>(field: string, offset?: number, defaultValue?: R): WindowFn<R | undefined>;
+/**
+ * Running total of a numeric `field` over `rows unbounded preceding → current
+ * row`. Identical to passing `sum(field)` — named for the reading.
+ *
+ * ⚠️ For a declared money field use {@link runningMoneySum}: it is the same
+ * reducer, but typed `MoneyString` to match what the exact BigInt rewrite
+ * actually returns.
+ */
+export declare function runningSum(field: string): Reducer<number>;
+/**
+ * Running total of a **declared money field**, exact at any magnitude.
+ *
+ * The reducer is the ordinary money `sum`, and it is rewritten by
+ * `ViaPipeline.wrapReducers` into `via/money/money-reducer.ts`'s BigInt
+ * accumulator at `.select()` time — the SAME rewrite `.aggregate()` and
+ * `.groupBy()` get, so a running balance and a grand total cannot disagree.
+ * Nothing here touches a float: values accumulate as scaled `bigint`s and each
+ * row's value is `formatScaledInt`'d out of the state at that point.
+ */
+export declare function runningMoneySum(field: string): Reducer<MoneyString>;
+/**
+ * Execute the window stage. Pure function over a row array — exported for
+ * tests and for any future `scan().window()` reuse.
+ *
+ * Rows are returned in INPUT order, each a shallow copy widened with the
+ * selected outputs. A `dateTrunc()` partition key is read off an internal
+ * projection and is deliberately NOT stamped on the output row — unlike
+ * `.groupBy()`, where the derived key IS the result key.
+ */
+export declare function applyWindow<R>(records: readonly unknown[], spec: WindowSpec, select: WindowSelectSpec): R[];
+/**
+ * What `withWindow()` hands to `withReduce()`. Named as a type so
+ * `strategy.ts` / `active.ts` can speak it in a TYPE-ONLY import and never
+ * pull this module into their runtime graph.
+ */
+export type WindowFactory = <T>(executeRecords: () => readonly unknown[], spec: WindowSpec, upstreams: readonly ReductionUpstream[], via?: ViaPipeline) => WindowedQuery<T>;
+/**
+ * Light up `.window()` on `Query`.
+ *
+ * ```ts
+ * import { withReduce, withWindow } from '@noy-db/hub/reduce'
+ * createNoydb({ store, user, secret, reduceStrategy: withReduce({ window: withWindow() }) })
+ * ```
+ *
+ * The only reference to {@link WindowedQuery} outside this module's own
+ * consumers — see "Opting in" in the module docs for why that matters.
+ */
+export declare function withWindow(): WindowFactory;
+/**
+ * Chainable wrapper returned by `Query.window(spec)`. Terminates with
+ * `.select(spec)`, which is the only operation on it — a window with nothing
+ * selected computes nothing.
+ */
+export declare class WindowedQuery<T> {
+    private readonly executeRecords;
+    private readonly spec;
+    private readonly upstreams;
+    private readonly via?;
+    constructor(executeRecords: () => readonly unknown[], spec: WindowSpec, upstreams: readonly ReductionUpstream[], via?: ViaPipeline | undefined);
+    /**
+     * Attach window outputs to every row. Each slot is either a
+     * {@link WindowFn} (`rowNumber`, `rank`, `lag`, `lead`) or a `Reducer`,
+     * which runs as a running aggregate over `rows unbounded preceding →
+     * current row`.
+     *
+     * Reducers are rewritten through the collection's Via pipeline exactly as
+     * `.aggregate()` rewrites them, so a `sum` over a declared money field
+     * becomes the exact BigInt accumulator and a `countDistinct` dedups on the
+     * canonical index key.
+     */
+    select<Spec extends WindowSelectSpec>(spec: Spec): WindowSelection<WindowRow<T, Spec>>;
+}
+/**
+ * The `.window(...).select(...)` terminal. Mirrors `GroupedReduction`'s shape
+ * — `.run()` and `.live()` — minus the post-group stage: ordering and limiting
+ * of window OUTPUT rows belong on the underlying `Query`, before `.window()`,
+ * because a window never changes the row set.
+ */
+export declare class WindowSelection<R> {
+    private readonly executeRecords;
+    private readonly spec;
+    private readonly select;
+    private readonly upstreams;
+    constructor(executeRecords: () => readonly unknown[], spec: WindowSpec, select: WindowSelectSpec, upstreams: readonly ReductionUpstream[]);
+    /** Execute the query and return every row, widened with the window outputs. */
+    run(): R[];
+    /**
+     * Reactive terminal — re-runs the whole window pipeline on every upstream
+     * change, the same naive-recompute contract `GroupedReduction.live()` has.
+     * Always call `live.stop()` when finished.
+     */
+    live(): LiveReduction<R[]>;
+}
+export {};

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

@@ -22,7 +22,7 @@
  * 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 { RecordCodec } from '../../capsule/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';
@@ -31,8 +31,8 @@ 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';
+import type { IndexDoc, IndexBuildOptions } from './inverted-index.js';
+import type { RetrieveOptions, RetrieveHit, SimilarToOptions } from './retrieve-types.js';
 /** Everything the moving search/retrieval methods touched on `this.*`. */
 export interface SearchContext<T> {
     /** Collection name — error context + `_ftindex` row key. */
@@ -52,6 +52,8 @@ export interface SearchContext<T> {
     readonly lazy: boolean;
     /** Declared text-index fields, or undefined. */
     readonly textIndexes: readonly string[] | undefined;
+    /** Subset of `textIndexes` recording token positions for phrase / proximity (#1354). */
+    readonly textIndexPositions: readonly string[] | undefined;
     /** Declared i18n fields, or undefined. */
     readonly i18nFields: Record<string, I18nTextDescriptor> | undefined;
     /** Declared dictionary-key fields, or undefined. */
@@ -78,6 +80,13 @@ export interface SearchContext<T> {
 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 — the positional-postings opt-in for this collection (#1354), or
+ * `undefined` when nothing opted in. Returning `undefined` rather than
+ * `{ positions: [] }` keeps the no-opt-in path byte-identical to a caller that
+ * never heard of positions.
+ */
+export declare function positionBuildOptions<T>(ctx: SearchContext<T>): IndexBuildOptions | undefined;
 /** 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. */
@@ -103,15 +112,42 @@ export declare function flushIndex<T>(ctx: SearchContext<T>): Promise<void>;
 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). */
+/**
+ * Retrieval. mode: 'lexical' (default) | 'semantic' (L2) | 'hybrid' (L3).
+ *
+ * ## `within` — the typed half of retrieval (#1343)
+ *
+ * Money / number / date / boolean fields are NOT tokenised into the lexical
+ * index and never will be: instead of a second (typed-token) index format, a
+ * typed match is expressed as an ordinary `Query` and handed to `within`, so
+ * the comparison runs in the query engine — over the sorted / compound range
+ * indexes — in each field's CANONICAL space (money as its scaled integer, not
+ * as a lexically-compared string). `retrieve()` contributes the text half and
+ * intersects.
+ *
+ * Two ordering properties, both load-bearing:
+ *
+ * - **Scoring is global; narrowing is not.** BM25 runs over the WHOLE corpus
+ *   (df / N / avgdl unchanged by `within`), so a document's score is the same
+ *   whichever `within` it is paired with — a filter re-ranks nothing. Narrowing
+ *   the postings instead would make IDF filter-dependent and scores
+ *   incomparable between two calls. It also costs nothing to score first: the
+ *   index already scores every doc and only slices at the end.
+ * - **`limit` counts hits from the NARROWED set.** Truncating corpus-wide first
+ *   and filtering after would under-return (`limit: 10` yielding 1), so the
+ *   mode branches run unlimited and the caller's `limit` is applied last.
+ *
+ * An empty `within` result set yields NO hits — never all of them.
+ *
+ * A `within` with an empty text query is **typed-only retrieval**: the typed
+ * predicate is the whole query, returned in the usual hit shape (score 0,
+ * `field: '(within)'`, empty snippet) so a typed and a text search are read the
+ * same way. An empty query with NO `within` still matches nothing.
+ */
 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>[]>;
+export declare function similarTo<T>(ctx: SearchContext<T>, vector: Float32Array, opts?: SimilarToOptions): 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

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

@@ -3,9 +3,11 @@
  * lazy; an opaque-blob backend implements the same interface so the
  * collection call-site is unchanged.
  */
-import { InvertedIndex, type IndexDoc } from './inverted-index.js';
+import { InvertedIndex, type IndexDoc, type IndexBuildOptions } from './inverted-index.js';
 export interface IndexStore {
-    ensureBuilt(build: () => ReadonlyArray<IndexDoc>): Promise<InvertedIndex>;
+    /** `opts` carries the positional-postings opt-in (#1354); a persisted store also
+     *  uses it to decide whether a loaded sidecar still matches the live config. */
+    ensureBuilt(build: () => ReadonlyArray<IndexDoc>, opts?: IndexBuildOptions): Promise<InvertedIndex>;
     markDirty(): void;
     flush(): Promise<void>;
     readonly built: boolean;
@@ -13,7 +15,7 @@ export interface IndexStore {
 export declare class MemoryIndexStore implements IndexStore {
     private index;
     get built(): boolean;
-    ensureBuilt(build: () => ReadonlyArray<IndexDoc>): Promise<InvertedIndex>;
+    ensureBuilt(build: () => ReadonlyArray<IndexDoc>, opts?: IndexBuildOptions): Promise<InvertedIndex>;
     markDirty(): void;
     flush(): Promise<void>;
 }

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

@@ -8,12 +8,14 @@
 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 { InvertedIndex, type IndexDoc, type IndexHit, type QueryOptions, type IndexBuildOptions, type IndexSnapshot } from './inverted-index.js';
 export { extractSnippet } from './snippet.js';
 export { MemoryIndexStore, type IndexStore } from './index-store.js';
 export { buildStringFieldEntries, type FieldEntry } from './build-docs.js';
-export type { RetrieveOptions, RetrieveHit } from './retrieve-types.js';
+export type { RetrieveOptions, RetrieveHit, SimilarToOptions } from './retrieve-types.js';
 export { fuseRetrieval, type FuseOptions } from './fuse.js';
+export { withVectorIndex, DEFAULT_INDEX_MIN_VECTORS, type VectorIndexOptions } from '../embeddings/with-vector-index.js';
+export type { VectorIndex, VectorIndexConfig, VectorIndexSearchOptions } from '../embeddings/vector-index.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

@@ -14,14 +14,43 @@ export interface IndexHit {
     readonly text: string;
     readonly offset: number;
 }
+/** Build-time index shape. The only knob is which fields carry positions. */
+export interface IndexBuildOptions {
+    /** Fields whose postings record token positions (phrase / proximity). Opt-in: index size grows. */
+    readonly positions?: readonly string[];
+}
 export interface QueryOptions {
     readonly limit?: number;
     readonly match?: 'any' | 'all';
     readonly prefix?: boolean;
     readonly fields?: readonly string[];
+    /**
+     * Per-field score weights (BM25F-style, #1354). Purely query-side — nothing
+     * in the index changes. A field with no entry weighs 1, and the no-boost path
+     * performs no multiplication at all, so an unboosted query's scores are
+     * bit-for-bit what they were before boosts existed.
+     *
+     * ⚠️ Textbook BM25F pools term frequencies ACROSS fields before one
+     * saturation step. This index scores each field independently and keeps the
+     * best (see the class doc), so a boost weights the per-field score instead.
+     * Same intent — "a hit in `name` is worth more than a hit in `notes`" —
+     * different arithmetic; do not expect Lucene's BM25F numbers.
+     */
+    readonly boost?: Readonly<Record<string, number>>;
 }
+/**
+ * Persisted shape. `v` is the format stamp: an older stamp is REJECTED and the
+ * index rebuilt, never migrated or read leniently — see
+ * {@link parseIndexSnapshot}. v1 (pre-#1354) had no `posFields` and no `pos`,
+ * and a v1 blob read as v2 would silently answer "this doc has no positions",
+ * i.e. "your phrase does not match", which is a wrong answer rather than a slow
+ * one.
+ */
+export declare const INDEX_SNAPSHOT_VERSION = 2;
 export interface IndexSnapshot {
-    readonly v: 1;
+    readonly v: number;
+    /** Fields whose docs carry `pos`. Empty ⇒ nobody opted in. */
+    readonly posFields: readonly string[];
     readonly fieldStats: ReadonlyArray<[string, {
         df: [string, number][];
         n: number;
@@ -35,13 +64,20 @@ export interface IndexSnapshot {
         len: number;
         tf: [string, number][];
         firstOffset: [string, number][];
+        /** term -> ascending token ordinals. Present iff `field` ∈ `posFields`. */
+        pos?: [string, number[]][];
     }>;
 }
 export declare class InvertedIndex {
     private readonly fieldStats;
     private readonly docs;
-    static build(docs: ReadonlyArray<IndexDoc>): InvertedIndex;
+    private posFields;
+    static build(docs: ReadonlyArray<IndexDoc>, opts?: IndexBuildOptions): InvertedIndex;
+    /** Fields this index carries positions for (#1354) — the store compares it against the live config. */
+    get positionFields(): ReadonlySet<string>;
     query(query: string, opts?: QueryOptions): IndexHit[];
+    /** Token ordinal → char offset in the ORIGINAL text, by re-segmenting this one doc. */
+    private charOffsetAt;
     toSnapshot(): IndexSnapshot;
     static fromSnapshot(s: IndexSnapshot): InvertedIndex;
 }

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

@@ -19,7 +19,7 @@
  * 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 { InvertedIndex, type IndexDoc, type IndexBuildOptions } from './inverted-index.js';
 import type { IndexStore } from './index-store.js';
 export interface Fingerprint {
     readonly count: number;
@@ -47,6 +47,9 @@ export declare class PersistedIndexStore implements IndexStore {
     private index;
     private timer;
     private lastBuild;
+    /** The positional-postings opt-in the last caller asked for (#1354). A loaded
+     *  sidecar that does not carry exactly these fields is discarded, not adapted. */
+    private lastOpts;
     private readonly debounceMs;
     /**
      * Bumped by every purge (removePersisted). A save() captured under a since-stale
@@ -92,7 +95,7 @@ export declare class PersistedIndexStore implements IndexStore {
     private pendingCompensation;
     constructor(cb: PersistedIndexCallbacks);
     get built(): boolean;
-    ensureBuilt(build: () => ReadonlyArray<IndexDoc>): Promise<InvertedIndex>;
+    ensureBuilt(build: () => ReadonlyArray<IndexDoc>, opts?: IndexBuildOptions): Promise<InvertedIndex>;
     markDirty(): void;
     /** Force an immediate persist (cancels any pending debounce). */
     flush(): Promise<void>;

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

@@ -0,0 +1,28 @@
+/** One quoted clause. `slop === undefined` ⇒ strict ordered phrase. */
+export interface PhraseClause {
+    readonly terms: readonly string[];
+    readonly slop: number | undefined;
+}
+export interface ParsedQuery {
+    /** Unquoted terms — scored exactly as before #1354. */
+    readonly terms: readonly string[];
+    readonly phrases: readonly PhraseClause[];
+}
+/**
+ * Split a raw query into bare terms + quoted clauses. An unterminated quote
+ * has no closing delimiter to match, so it never forms a clause and its text
+ * falls through to the bare-term tokenizer — a typo degrades to today's
+ * behaviour rather than to an error.
+ */
+export declare function parseSearchQuery(query: string): ParsedQuery;
+/**
+ * Occurrences of a clause inside one field's positional postings, plus the
+ * token position the first occurrence starts at (`-1` when there is none).
+ *
+ * `positions` maps term → ascending token ordinals. A term the posting does
+ * not carry is an immediate miss.
+ */
+export declare function matchClause(positions: ReadonlyMap<string, readonly number[]>, clause: PhraseClause): {
+    count: number;
+    start: number;
+};