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

package/dist/with-commit/sequence/index.d.ts

@@ -19,7 +19,7 @@
  * to its record in the same operation.
  */
 import type { NoydbStore } from '../../kernel/types.js';
-import { type EnclaveKey } from '../../kernel/enclave/index.js';
+import { type EnclaveKey } from '../../capsule/index.js';
 export { withSequence } from './active.js';
 export { NO_SEQUENCE, type SequenceStrategy } from './strategy.js';
 export { SequenceNotEnabledError } from '../../kernel/errors.js';

package/dist/with-commit/tx/invariants.d.ts

@@ -5,7 +5,7 @@
  * fires solely inside `db.transaction({ amendment: true }, …)` and requires
  * an admin/owner role plus a registered guard. That is the right shape for
  * the WORM-override path, but normal application transactions also need
- * cross-record invariants that hold on every commit — e.g. niwat's
+ * cross-record invariants that hold on every commit — e.g. pilot1's
  * `assertR1` ("every payment is 100% receipted").
  *
  * `withTransactions({ invariants: [...] })` registers such invariants. Each

package/dist/with-commit/tx/transaction.d.ts

@@ -20,12 +20,22 @@
  *
  * Ops are buffered during the body. On body-return the hub:
  *
+ * 0. **Drain (#1420)** — waits out any plain `Collection.put()` /
+ *    `.delete()` already in flight on a key this commit touches, so
+ *    the pre-flight below reads a version that includes it. Without
+ *    this the pre-flight cannot see a write that has STARTED but not
+ *    yet reached the store, and one of the two writes vanishes with
+ *    both reporting success.
  * 1. **Pre-flight** — re-reads every touched envelope and enforces
  *    any caller-supplied `expectedVersion`. A mismatch throws
  *    `ConflictError` with *no* writes performed.
- * 2. **Execute** — calls `Collection.put()` / `.delete()` for each
- *    staged op in declaration order. History snapshots, ledger
- *    appends, and change events fire as normal per op.
+ * 2. **Execute** — re-validates each op's `expectedVersion` against
+ *    the CURRENT stored version (#1420 — the pre-flight's verdict is
+ *    otherwise unchecked all the way to the write, and this path
+ *    carries no store-level CAS the way the atomic one does), then
+ *    calls `Collection.put()` / `.delete()` for each staged op in
+ *    declaration order. History snapshots, ledger appends, and change
+ *    events fire as normal per op.
  * 3. **Unwind on failure** — if step 2 throws mid-batch, each
  *    already-committed op is reverted via the raw store (restoring
  *    the captured prior envelope, or deleting if none existed). The

package/dist/with-commit/vault-head/head.d.ts

@@ -9,7 +9,7 @@
  *
  * @packageDocumentation
  */
-import { type EnclaveKey } from '../../kernel/enclave/index.js';
+import { type EnclaveKey } from '../../capsule/index.js';
 import type { NoydbStore } from '../../kernel/types.js';
 /** `{ recordId → version }` for one bucket. */
 export type BucketBody = Record<string, number>;

package/dist/with-commit/vault-head/index.d.ts

@@ -7,4 +7,4 @@ export { withVaultHead } from './active.js';
 export { verifyVaultHead, type HeadDiscrepancy, type HeadVerifyResult, type HeadVerdict, type HeadUnverifiableReason } from './verify.js';
 export { NO_VAULT_HEAD, VAULT_HEAD_COLLECTION, DEFAULT_HEAD_BUCKETS, type VaultHeadStrategy, type WithVaultHeadOptions, type HeadEntry, } from './strategy.js';
 export type { NoydbStore, EncryptedEnvelope } from '../../kernel/types.js';
-export type { EnclaveKey } from '../../kernel/enclave/index.js';
+export type { EnclaveKey } from '../../capsule/index.js';

package/dist/with-commit/vault-head/strategy.d.ts

@@ -63,7 +63,7 @@
  * @packageDocumentation
  */
 import type { NoydbStore, EncryptedEnvelope } from '../../kernel/types.js';
-import type { EnclaveKey } from '../../kernel/enclave/index.js';
+import type { EnclaveKey } from '../../capsule/index.js';
 /** Reserved collection the head's buckets live in. */
 export declare const VAULT_HEAD_COLLECTION: "_head";
 /** Default bucket count — see the sizing table above. */

package/dist/with-commit/vault-head/verify.d.ts

@@ -9,7 +9,7 @@
  * @packageDocumentation
  */
 import type { NoydbStore } from '../../kernel/types.js';
-import type { EnclaveKey } from '../../kernel/enclave/index.js';
+import type { EnclaveKey } from '../../capsule/index.js';
 import type { VaultHeadStrategy } from './strategy.js';
 /** One record the store is not serving faithfully. */
 export interface HeadDiscrepancy {

package/dist/with-formula/derivations/dispatch.d.ts

@@ -26,7 +26,7 @@ import type { TxContext } from '../../with-commit/tx/transaction.js';
 import type { DerivationRegistry } from './registry.js';
 import type { ReadOnlyVaultFacade } from '../../with-audit/guards/types.js';
 import type { Collection } from '../../kernel/collection.js';
-import type { EnclaveKey } from '../../kernel/enclave/index.js';
+import type { EnclaveKey } from '../../capsule/index.js';
 import type { EncryptedEnvelope } from '../../kernel/types.js';
 import type { ledgerAuditHook, WaveContext } from '../../kernel/via/dispatch.js';
 /** The per-write dispatch context threaded into `putDerivedOutput`. */

package/dist/with-formula/derivations/fanout-sidecar.d.ts

@@ -21,7 +21,7 @@
  * @module
  */
 import type { NoydbStore } from '../../kernel/types.js';
-import { type EnclaveKey } from '../../kernel/enclave/index.js';
+import { type EnclaveKey } from '../../capsule/index.js';
 type GetDEK = (collectionName: string) => Promise<EnclaveKey>;
 /** Magic-prefixed JSON payload at `_meta/<recordId>`. */
 export interface FanoutSidecar {

package/dist/with-formula/materialized-views/dependency-analyzer.d.ts

@@ -45,9 +45,10 @@ export declare function summarizeQueryPlan(query: Query<any>): string;
  *     same `queryHash`, refresh would be a no-op, and stale MV rows
  *     would persist. Hashing in declaration order makes any reorder
  *     trigger a refresh.
- *   - `groupBy` fields ARE sorted. Multi-key groupBy buckets are
- *     commutative (`canonicalGroupKey` produces the same composite key
- *     regardless of field order in the input spec).
+ *   - `groupBy` fields ARE sorted, by their canonical `describeGroupKey`
+ *     description (which is the field name itself for a plain key). Multi-key
+ *     groupBy buckets are commutative (`canonicalGroupKey` produces the same
+ *     composite key regardless of field order in the input spec).
  *   - `aggregate` keys ARE sorted. Reducer-spec keys are independent
  *     of each other — order of declaration doesn't change output.
  *

package/dist/with-formula/materialized-views/emit-memo.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Identity of one MV's output, per vault — MV names are not globally unique.
+ *
+ * ⚠️ `\0` written as the ESCAPE, not as a raw byte. A raw NUL in the source
+ * makes git classify the whole file as binary, so it stops diffing and stops
+ * being reviewable — caught here by a `Bin 0 -> 8811 bytes` line in a diffstat.
+ * The separator itself is right: no vault or collection name can contain one.
+ */
+export declare function emitMemoKey(vault: string, mvName: string, outputCollection: string): string;
+/**
+ * The rows this MV last wrote, or `null` when the memo cannot be trusted —
+ * nothing recorded yet, or the output collection moved under us.
+ *
+ * `stamp` of `null` means the collection cannot supply one (lazy mode), which
+ * is treated as "no memo" rather than "unchanged".
+ */
+export declare function readEmitMemo(key: string, stamp: number | null): ReadonlyMap<string, string> | null;
+/** Record what this refresh actually left on disk. A `null` stamp records nothing. */
+export declare function writeEmitMemo(key: string, stamp: number | null, rows: Map<string, string>): void;
+/** Forget one MV's output entirely. Used when a refresh could not complete cleanly. */
+export declare function dropEmitMemo(key: string): void;
+/**
+ * A canonical string for the row a refresh is about to write, or `null` when no
+ * safe one exists.
+ *
+ * The MV's `queryHash` is folded in so a strategy change rewrites every row
+ * even where the projected content happens to match — a row carrying a stale
+ * `_materializedFrom.queryHash` is stale by definition (`stale.ts`).
+ *
+ * `_materializedFrom` itself is excluded: its `materializedAt` moves on every
+ * refresh, so including it would make every comparison differ and the memo a
+ * pure cost.
+ *
+ * ⛔ Returns `null` rather than throwing on anything `JSON.stringify` refuses
+ * (a `BigInt`, a cycle). Declining to memoize costs the old write; guessing
+ * costs a stale view.
+ */
+export declare function rowContentKey(row: Record<string, unknown>, queryHash: string): string | null;
+/** Test seam — the process-wide memo must not leak between test cases. */
+export declare function _clearEmitMemos(): void;

package/dist/with-formula/materialized-views/executor.d.ts

@@ -32,6 +32,14 @@ export interface MVExecutorAccessor {
 export interface RefreshResult {
     /** Rows newly written / overwritten. */
     written: number;
+    /**
+     * #1418 — rows whose content was byte-identical to what this MV last wrote,
+     * so the encrypt-and-store round trip was skipped. Counted separately from
+     * `written` on purpose: `written` means "a row was persisted", and reporting
+     * a skip as a write would make the two indistinguishable to anyone
+     * diagnosing whether a refresh actually did anything.
+     */
+    skipped: number;
     /** Rows tombstoned via `_internalDelete` (only when `onEmpty: 'delete'`). */
     deleted: number;
     /** Failed row writes (non-strict mode). */

package/dist/with-formula/materialized-views/index.d.ts

@@ -5,7 +5,7 @@ export { analyzeDependencies, summarizeQueryPlan } from './dependency-analyzer.j
 export { computeQueryHash, canonicalizeQueryPlan } from './query-hash.js';
 export { markMVStale, resolveStaleMVOnRead, isMVStale, clearMVStale } from './stale.js';
 export type { MVStaleAccessor } from './stale.js';
-export type { MaterializedViewSpec, MaterializedViewStrategy, MaterializedViewOutput, MaterializedFromMeta, UnionSource, UnionArmJoin, ProjectionSpec, ProjectionJoinLeg, } from './types.js';
+export type { MaterializedViewSpec, MaterializedViewStrategy, MaterializedViewOutput, MaterializedFromMeta, UnionSource, UnionArmJoin, UnionArmRefJoin, UnionArmDeclaredJoin, ProjectionSpec, ProjectionJoinLeg, } from './types.js';
 export type { RegisteredMV } from './registry.js';
 export type { MVExecutorAccessor, RefreshResult } from './executor.js';
 export { MaterializedViewCycleError, MaterializedViewConfigError, MaterializedViewSourceUnknownError, MaterializedViewTooLargeError, } from '../../kernel/errors.js';

package/dist/with-formula/materialized-views/registry.d.ts

@@ -167,6 +167,21 @@ export declare class MaterializedViewRegistry {
      */
     validate(graph: ViaGraph): void;
 }
+/**
+ * #1414 — wrap an `MVQueryContext` so its `.collection().query()` returns a
+ * query with the cold-collection gate removed.
+ *
+ * The MV engine reads its sources synchronously: registration inspects the
+ * plan the spec callback returns, and the executor's scan runs from inside a
+ * write commit. Both predate #1414 and both have always read whatever the
+ * in-memory cache held. Gating them would convert a pre-existing (and
+ * separately tracked) staleness into a thrown error on a write path nobody
+ * pointed at a query — so the engine keeps its old source and #1414's change
+ * stays on the surface a consumer or a guard actually calls.
+ *
+ * @internal
+ */
+export declare function ungatedMvContext(db: MVQueryContext): MVQueryContext;
 /**
  * Wrap an `MVQueryContext` so its `.collection().query()` returns a
  * Query<T> with the MV's declared predicates attached. Bare Queries

package/dist/with-formula/materialized-views/types.d.ts

@@ -1,9 +1,12 @@
+import type { GroupKey } from '../../kernel/query/reduce/date-trunc.js';
 import type { Query } from '../../kernel/query/builder.js';
 import type { Collection } from '../../kernel/collection.js';
 import type { ReduceSpec, Reduction } from '../../with-lookup/reduce/reduction.js';
 import type { GroupedReduction } from '../../with-lookup/reduce/groupby.js';
-import type { JoinStrategy } from '../../kernel/query/join.js';
+import type { JoinStrategy } from '../../kernel/query/relate/join.js';
+import type { JoinOnSpec } from '../../kernel/query/relate/join-on.js';
 import type { MoneyDescriptor } from '../../via/money/descriptor.js';
+import type { WindowSpec, WindowSelectSpec } from '../../with-lookup/reduce/window.js';
 import type { ExactMath } from '../../via/money/exact.js';
 import type { I18nTextDescriptor } from '../../via/i18n/core.js';
 /**
@@ -92,24 +95,32 @@ export interface UnionSource<TRow extends Record<string, unknown>> {
      */
     readonly map: (sourceRow: Record<string, unknown>) => TRow | null | undefined;
     /**
-     * Optional FK joins to apply to this arm's rows before {@link map}.
-     * Each leg resolves a `ref()`-declared foreign key on the arm's
-     * source collection into an attached right-side record under
-     * `as` — the same machinery as the query-form `Query.join()`.
-     *
-     * The right-side collections must be listed in the strategy's
-     * {@link MaterializedViewSpec.sources} so writes to them trigger
-     * MV refresh — registration throws `MaterializedViewConfigError`
-     * otherwise (the union dependency set comes from arm `collection`s
-     * alone, which would not include join targets).
+     * Optional joins to apply to this arm's rows before {@link map}, in two
+     * shapes (a leg is one or the other):
+     *
+     *  - {@link UnionArmRefJoin} `{ field, as }` — resolves a `ref()`-declared
+     *    foreign key on the arm's source collection into an attached right-side
+     *    record under `as`; the same machinery as the query-form `Query.join()`.
+     *    Its right-side collections must be listed in the strategy's
+     *    {@link MaterializedViewSpec.sources} so writes to them trigger MV
+     *    refresh — registration throws `MaterializedViewConfigError` otherwise
+     *    (a ref's target is not known until the ref is declared, after
+     *    `openVault()`).
+     *  - {@link UnionArmDeclaredJoin} `{ target, as, on }` (#1411) — the
+     *    query-form `Query.joinOn()`: composite equality or a range, with the
+     *    predicate as DATA. No `ref()` needed, and `target` is a literal
+     *    collection name, so it joins the dependency set on its own and the
+     *    predicate folds into `queryHash`.
      */
     readonly join?: ReadonlyArray<UnionArmJoin>;
 }
+/** One join leg on a UNION arm — a ref join or a declared join (#1411). */
+export type UnionArmJoin = UnionArmRefJoin | UnionArmDeclaredJoin;
 /**
  * One FK join leg on a UNION arm. Mirrors the option shape of the
  * query-form `Query.join(field, { as, maxRows?, strategy? })`.
  */
-export interface UnionArmJoin {
+export interface UnionArmRefJoin {
     /** FK field on the arm's source collection (must have a `ref()` declared). */
     readonly field: string;
     /** Alias under which the resolved right-side record attaches on the source row. */
@@ -119,11 +130,30 @@ export interface UnionArmJoin {
     /** Planner strategy override. `undefined` → auto-select. */
     readonly strategy?: JoinStrategy;
 }
+/**
+ * One DECLARED join leg on a UNION arm (#1411) — `Query.joinOn(target, { as,
+ * on, mode?, maxRows? })` in declaration form. The `on` is plain JSON: a
+ * composite-equality pair list or a `{ left, op, right }` range. A left row
+ * matching nothing gets `null` under `as` (left outer); `mode: 'inner'` drops
+ * it. ⚠️ A declared join EXPANDS rows — one output row per match.
+ */
+export interface UnionArmDeclaredJoin {
+    /** Right-side collection name. Joins the MV's dependency set automatically. */
+    readonly target: string;
+    /** Alias under which each matching right-side record attaches on the source row. */
+    readonly as: string;
+    /** The predicate — see `JoinOnSpec`. Normalised and validated at registration. */
+    readonly on: JoinOnSpec;
+    /** `'inner'` drops left rows with no match; omit for left-outer (`null` under `as`). */
+    readonly mode?: 'inner';
+    /** Per-side / output row ceiling override. `undefined` → the join default. */
+    readonly maxRows?: number;
+}
 /**
  * Projection-form registration (#810): one output row per record of a
  * primary `source` collection, enriched with forward FK legs and
  * reverse one-to-many "collect" legs BEFORE `map` shapes the MV row.
- * The niwat federated read-model shape — a bill row carrying its
+ * The pilot1 federated read-model shape — a bill row carrying its
  * client lookup plus the receipt / application / credit-note sets
  * that point back at it.
  */
@@ -314,11 +344,16 @@ export interface MaterializedViewSpec<TRow extends Record<string, unknown>> {
      * field names for multi-key grouping (same shape as
      * `Query.groupBy(...fields)`).
      *
+     * A field name can be replaced by a `dateTrunc(field, unit, { timeZone })`
+     * derived calendar key (#1350) — the bucket is computed on the mapped row
+     * before grouping, and the key's parameters fold into the MV's `queryHash`,
+     * so re-parameterising it forces a refresh.
+     *
      * UNION-mode only. Ignored if {@link query} is set — single-source
      * grouping is expressed inside the `Query<T>` returned from `query()`
      * via `.groupBy(...).aggregate(...)`.
      */
-    groupBy?: string | ReadonlyArray<string>;
+    groupBy?: GroupKey | ReadonlyArray<GroupKey>;
     /**
      * Reduction spec for UNION mode. Applied per-group after
      * {@link groupBy} buckets the concatenated mapped-row stream from
@@ -398,6 +433,44 @@ export interface MaterializedViewSpec<TRow extends Record<string, unknown>> {
      * if declared alone.
      */
     moneyFields?: Record<string, MoneyDescriptor>;
+    /**
+     * #1411 — a declared WINDOW over the finished rows: a running total, a
+     * ranking, or a look at the neighbouring row.
+     *
+     * ```ts
+     * groupBy: ['client', 'period'],
+     * aggregate: { total: sum('amount') },
+     * moneyFields: { amount: THB, total: THB, cumulative: THB },
+     * window: {
+     *   partitionBy: 'client',
+     *   orderBy: 'period',
+     *   select: { cumulative: runningMoneySum('total') },
+     * },
+     * ```
+     *
+     * Runs AFTER {@link groupBy} + {@link aggregate} and BEFORE {@link derive},
+     * which is the order the useful shape needs: aggregate per (client, period),
+     * then accumulate ACROSS periods. A window before grouping would accumulate
+     * over raw rows and every number would be wrong.
+     *
+     * ⭐ **This is the one stage that may look at other rows, and it is sound for
+     * a reason `derive` cannot borrow.** `derive` is single-row by contract;
+     * materialization is a full recompute, so the window sees every row the view
+     * will store, in order, exactly once. That is also why it is not offered on
+     * the `query` form — there the rows come from a `Query`, which has its own
+     * `.window()`.
+     *
+     * **Money is exact** when the accumulated field is declared in
+     * {@link moneyFields}: reducer slots are rewritten through the same binding
+     * `aggregate` uses, so `runningMoneySum` accumulates in BigInt rather than
+     * float. Window FUNCTIONS (`rowNumber`, `rank`, `lag`, `lead`) navigate
+     * rather than accumulate and need no rewrite.
+     *
+     * A `select` key that collides with a {@link groupBy} field throws
+     * `MaterializedViewConfigError` — the same rule, and the same reason, as
+     * `derive`: a group key is the row's identity and feeds {@link rowKey}.
+     */
+    window?: MaterializedViewWindow;
     /**
      * Compute-time i18n resolution locale (`mv` layer). UNION-mode only.
      *
@@ -507,3 +580,22 @@ export interface MaterializedViewStrategy {
     readonly __noydb_strategy: 'materialized-view';
     readonly spec: MaterializedViewSpec<any>;
 }
+/** @internal — the MV's own money descriptors, keyed by output field. */
+export type MoneyDescriptorMap = Record<string, MoneyDescriptor>;
+/**
+ * #1411 — a declared window: {@link WindowSpec}'s partition/order, plus the
+ * outputs to attach. Same `select` shape as `Query.window(...).select(...)`,
+ * so a rule prototyped in the ad-hoc builder moves into a declaration
+ * unchanged.
+ */
+export interface MaterializedViewWindow extends WindowSpec {
+    /**
+     * The columns the window adds. Each slot is a window function
+     * (`rowNumber`, `rank`, `lag`, `lead`) or an ordinary reducer, which runs as
+     * a RUNNING aggregate over `rows unbounded preceding → current row`.
+     *
+     * Must be non-empty: a window that selects nothing computes nothing, and
+     * declaring one is more likely a mistake than an intention.
+     */
+    readonly select: WindowSelectSpec;
+}

package/dist/with-formula/materialized-views/window-stage.d.ts

@@ -0,0 +1,11 @@
+import type { MaterializedViewWindow, MoneyDescriptorMap } from './types.js';
+/**
+ * Apply a declared window to the finished row set.
+ *
+ * `moneyFields` is the MV's own descriptor map; when present, every REDUCER
+ * slot is rewritten exactly as `aggregate`'s are. Window functions
+ * (`rowNumber`, `rank`, `lag`, `lead`) are passed through untouched — they
+ * navigate rows rather than accumulate values, so there is nothing to make
+ * exact.
+ */
+export declare function applyDeclaredWindow(rows: readonly Record<string, unknown>[], window: MaterializedViewWindow, moneyFields?: MoneyDescriptorMap): ReadonlyArray<Record<string, unknown>>;

package/dist/with-formula/overlay-views/types.d.ts

@@ -37,7 +37,7 @@ export interface OverlayedViewSpec {
      * shadowValue` for a given id, virtual-collection reads of that id
      * return the overlay row; otherwise reads return the base row.
      *
-     * Niwat's canonical example: `dataStatus === 'override'` flips a
+     * Pilot1's canonical example: `dataStatus === 'override'` flips a
      * row into operator-controlled mode.
      *
      * No callback merge, no priority lattice, no field-level merge —

package/dist/with-formula/overlay-views/virtual-collection.d.ts

@@ -9,14 +9,23 @@ import type { OverlayedViewSpec } from './types.js';
  *   - `get(id)`: overlay row wins iff `overlay[shadowField] === shadowValue`;
  *     when `spec.mergeMode` is set, an intermediate status may instead pull
  *     a declared subset of fields from the overlay over the base
- *   - `list()` / `.query()`: union of ids, per-id merge applied
+ *   - `list()`: union of ids, per-id merge applied
  *   - `put(record)` / `put(id, record)`: routes to overlay; id derived
  *     via the base MV's `rowKey` (validated on the two-arg form)
  *   - `delete(id)`: removes the overlay row only; base stays
  *
- * Reactive APIs (`live`, `subscribe`, `query().live()`) are out of
- * scope for this release and surface as "not yet implemented" — wired in a
- * future sub-issue.
+ * ⚠️ **`query()` THROWS** — it is not implemented for overlay views (#154);
+ * use `list()` + filter, or read the base / overlay collections directly.
+ * This paragraph used to list `.query()` beside `list()` as working, while
+ * naming only `query().live()` among the deferrals — so the header
+ * over-claimed the one method on this class that throws, and the deferral
+ * list quietly omitted it. Corrected 2026-09-04; the throw-stubs below are
+ * the authority, and a doc comment that disagrees with an adjacent `never`
+ * return type is worth more scepticism than one that disagrees with distant
+ * code.
+ *
+ * Also deferred, same issue, same shape: `live`, `subscribe`,
+ * `query().live()`.
  */
 export declare class OverlayedCollection<T extends Record<string, unknown> = any> {
     private readonly spec;

package/dist/with-lookup/embeddings/chunks.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Sub-document chunking (#1360) — multiple vectors per record.
+ *
+ * A long document encoded as ONE vector averages its topics away: a contract
+ * whose fortieth clause is the only relevant one scores like a contract about
+ * nothing in particular. Chunking encodes SPANS of the record's source text
+ * separately, and scores a record by its BEST chunk.
+ *
+ * ## What a span indexes into — the load-bearing definition
+ *
+ * `start` / `end` are **character offsets into
+ * `embeddingSourceText(record, descriptor.source)`** — the joined source text,
+ * NOT into any single field. When `source` names several fields the text is
+ * their `' '`-join, so an offset can sit past a join boundary; that is exactly
+ * why the offsets are defined against the join and not against a field. The
+ * consumer reconstructs the snippet with the same call:
+ *
+ * ```ts
+ * const text = embeddingSourceText(record, descriptor.source)
+ * const snippet = text.slice(hit.chunk.start, hit.chunk.end)
+ * ```
+ *
+ * `similarTo()` does precisely that to fill `hit.snippet`, so a returned span
+ * is checkable against the record the consumer already holds.
+ *
+ * ## What is deliberately NOT here
+ *
+ * No bundled splitter. The splitter is host-supplied like `encode` — chunking
+ * a legal clause, a markdown section and a chat transcript are different
+ * problems and hub has no business guessing.
+ *
+ * The approximate index that was deferred here HAS since been built — it is
+ * `ivf-flat.ts`, opted into with `withVectorIndex()`, and it is OFF by default
+ * (see `vector-set.ts`'s `topK`). This file's own multiplier is what gated it:
+ * chunking stores one vector per chunk, so a corpus of R records at C chunks
+ * each brute-forces R·C vectors, and the index threshold counts VECTORS.
+ * ⛔ Managed plaintext vector backends (pgvector, Vectorize, Qdrant) remain
+ * excluded BY DECISION, and building an in-hub index does not reopen that: the
+ * backend would hold plaintext vectors, and embedding inversion leaks the text
+ * back out. The index built here never leaves the hub and is never persisted.
+ */
+import type { EmbeddingDescriptor } from './descriptor.js';
+/** A span the host's splitter proposes: `[start, end)` into the joined source text. */
+export interface EmbeddingChunkSpan {
+    readonly start: number;
+    readonly end: number;
+    /** Stable chunk id; defaults to `c<index>` when the splitter does not supply one. */
+    readonly id?: string;
+}
+/** A chunk as it is stored and returned — a span with a resolved id, no vector. */
+export interface EmbeddingChunk {
+    readonly id: string;
+    readonly start: number;
+    readonly end: number;
+}
+/** A chunk plus its vector, as held in memory by {@link VectorSet}. */
+export interface StoredChunk extends EmbeddingChunk {
+    readonly vec: Float32Array;
+}
+/**
+ * Normalise the splitter's output: drop empty/inverted/out-of-range spans,
+ * resolve ids. Invalid spans are DROPPED rather than thrown on — a splitter is
+ * host code running over host text, and one degenerate span (a trailing
+ * separator, a zero-width match) must not fail the write; a record that ends up
+ * with no usable span falls back to the whole-record vector, which is the
+ * pre-#1360 behaviour and never worse than not indexing the record at all.
+ */
+export declare function normalizeChunkSpans(spans: readonly EmbeddingChunkSpan[], textLength: number): EmbeddingChunk[];
+/**
+ * Encode each chunk of `text` under the descriptor's `encode` hook.
+ * Returns `[]` when no `chunk` hook is declared or it yields no usable span —
+ * the caller then stores the single whole-record vector, unchanged.
+ *
+ * Dimension is checked per chunk by the caller (it owns the error's field
+ * name), so this stays a pure derive.
+ */
+export declare function deriveChunkVectors(text: string, descriptor: EmbeddingDescriptor): Promise<(EmbeddingChunk & {
+    vec: Float32Array;
+})[]>;

package/dist/with-lookup/embeddings/descriptor.d.ts

@@ -1,8 +1,29 @@
+import type { EmbeddingChunkSpan } from './chunks.js';
+import type { VectorIndexConfig } from './vector-index.js';
 export interface EmbeddingDescriptor {
     readonly source: string | readonly string[];
     readonly encode: (text: string) => Promise<Float32Array>;
     readonly dim: number;
     readonly model: string;
+    /**
+     * Optional sub-document splitter (#1360). Given the record's joined source
+     * text (`embeddingSourceText(record, source)`), return the spans to encode
+     * separately — `start`/`end` are character offsets into THAT string. When
+     * declared and non-empty, the record is scored by its BEST chunk and the
+     * winning span comes back on the hit; when absent or empty, the record keeps
+     * exactly one whole-text vector, as before.
+     */
+    readonly chunk?: (text: string) => readonly EmbeddingChunkSpan[];
+    /**
+     * Opt into the approximate vector index (#1360 part 2) with
+     * `index: withVectorIndex()`. Absent — the default — and every semantic
+     * query is an exact brute-force cosine scan, unchanged.
+     *
+     * Opting in is not an instruction to index NOW: the index is built only once
+     * the collection holds at least `minVectors` vectors, and any single query
+     * can still demand exactness with `{ exact: true }`.
+     */
+    readonly index?: VectorIndexConfig;
 }
 /** Concatenate the record's source-field text (skips empties; supports nested/[]-wildcard paths). */
 export declare function embeddingSourceText(record: Record<string, unknown>, source: string | readonly string[]): string;

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

@@ -1,4 +1,7 @@
 export { cosine } from './cosine.js';
 export { embeddingSourceText, type EmbeddingDescriptor } from './descriptor.js';
 export { VectorSet, type StoredVector, type VectorHit } from './vector-set.js';
+export { withVectorIndex, DEFAULT_INDEX_MIN_VECTORS, type VectorIndexOptions } from './with-vector-index.js';
+export type { VectorIndex, VectorIndexConfig, VectorIndexSearchOptions } from './vector-index.js';
 export { encodeVecId } from './vec-id.js';
+export { deriveChunkVectors, normalizeChunkSpans, type EmbeddingChunk, type EmbeddingChunkSpan, type StoredChunk, } from './chunks.js';