@ignex/ninox 0.1.4 → 0.1.6

package/README.md

@@ -556,6 +556,7 @@ topProducts.invalidate();              // drop all entries
 topProducts.invalidate(3);             // drop just the { limit: 3 } entry
 hot.invalidateParams('topProducts', 3); // same, via dynamic name lookup
 hot.invalidateCollection('products');  // drop every query watching that collection
+hot.invalidateIds('products', [id]);   // drop only entries depending on that document
 await hot.stop();                      // close streams + ticker
 ```
 
@@ -565,6 +566,47 @@ parameters. Loader errors are never cached (they retry on the next read), and
 concurrent identical reads are in-flight-deduped. `has(name)` checks whether a
 query is registered.
 
+### Fine-tuned purges: watch ids (or groups of ids)
+
+By default a write anywhere in a collection purges **every** query bound to it.
+That's the safe contract — and often what you want for wide results like
+aggregations. When a query's entries map cleanly onto specific documents,
+declare `idsOf` on the watch ref and invalidation becomes surgical:
+
+```ts
+const userFeed = hot.register('userFeed', {
+  loader: async (userId: string) => db.findMany('orders', { customerId: userId }),
+  watch: [
+    // Only the entries whose feed includes THIS order are purged; other
+    // users' feeds stay warm. Works across processes via change streams.
+    { db: db.client, collection: 'orders', idsOf: (userId: string) => feedOrderIds(userId) },
+  ],
+});
+// …or drive it yourself (works in standalone mode too):
+hot.invalidateIds('orders', [changedOrderId]);
+```
+
+- `idsOf` receives the query's loader arguments and returns **every document id
+  the result depends on** — one per doc, or many for grouped/aggregated rows.
+  Ids may be strings, numbers or ObjectIds; an ObjectId and its hex string
+  match. It must be pure and cheap (runs once per load).
+- **Omit `idsOf` to keep burst semantics** — the right choice for whole-collection
+  aggregations (`countDocuments`, `$group`, …): any change to the collection
+  purges the query's entire LRU.
+- A ref without an extractor next to one with (multi-collection watchers)
+  forces a full purge whenever *its* collection changes; the extracted
+  collection stays surgical.
+- If `idsOf` throws or returns a non-array, affected entries are treated
+  conservatively: they are dropped by any targeted change instead of kept.
+- Watch `stats().perQuery[name].idDrops` to see how many entries targeted
+  purges are saving you (each drop is a read that stayed warm elsewhere).
+
+In replica mode the change stream feeds `invalidateIds` automatically from each
+event's `documentKey._id`; in standalone mode call it from your ORM's
+after-write hooks or wherever you learn about a change. Note that extraction
+sees only the loader arguments — a by-sku lookup whose dependency `_id` isn't
+derivable from `{ sku }` should either key entries by `_id` or stay coarse.
+
 Set `autoRefresh: false` to **turn off the global auto-refetch** entirely — the
 standalone ticker never runs, so data only updates via manual invalidation or
 `ttlMs` expiry. This keeps the DB from being polled when you'd rather drive
@@ -578,8 +620,9 @@ const hot = createHotCache({ probe, autoRefresh: false, defaultTtlMs: 5_000 });
 Pin the mode to skip the probe entirely when you already know the deployment
 (`mode: 'replica'` / `mode: 'standalone'`), and use `hot.stats()` for
 observability — it reports per-query `hits` / `misses` / `refreshes` /
-`loadErrors` / `sizeSkips` plus current sizes. Cap runaway single entries with a
-per-query `maxValueBytes` (larger values are still returned, just not cached).
+`loadErrors` / `sizeSkips` / `idDrops` plus current sizes. Cap runaway single
+entries with a per-query `maxValueBytes` (larger values are still returned,
+just not cached).
 
 Cached results are shared **by reference** (zero clone overhead); if a caller might
 mutate a result, enable per-query `clone: true` (or `cache: { clone: true }`) so
@@ -744,10 +787,15 @@ you need the code → status mapping yourself.
 > transient errors.
 
 Schema validation is enforced **by MongoDB** — the DB `$jsonSchema` validator
-derived from your schema is installed with `createSchema` (and hot-swapped with
-`updateSchema`), and the DB rejects violating writes with `VALIDATION_FAILED`.
-ninox deliberately does **not** validate *incoming user input* at runtime (no
-client-side/zod layer).
+derived from your schema is installed with `createSchema`, and the DB rejects
+violating writes with `VALIDATION_FAILED`. `createSchema` is **idempotent and
+self-reconciling**: it provisions a NEW collection, and when the collection
+already exists it upgrades the DB schema to match the current ORM schema
+(hot-swapping the validator via `collMod` only when it has drifted, and
+creating any newly-declared indexes) — so calling it on every boot keeps
+Mongo's schema in lockstep with your models as they change. `updateSchema`
+hot-swaps a validator explicitly (via `collMod`). ninox deliberately does
+**not** validate *incoming user input* at runtime (no client-side/zod layer).
 
 - **Strict by default** — `additionalProperties: false` is emitted unless a
   field opts out (`s.object({ ... }, { additionalProperties: true })`), so
@@ -771,7 +819,8 @@ client-side/zod layer).
   `DomainError` carries the offending field paths (`extra.fields`), the failing
   document id (`extra.documentId`), and the raw `extra.details`, so a rejected
   write names exactly what (and which document) violated the schema.
-- **Index lifecycle** — `createSchema` installs the declared indexes;
+- **Index lifecycle** — `createSchema` installs the declared indexes (and, on
+  an existing collection, adds any newly-declared ones without dropping);
   `syncIndexes(collection)` reconciles drift (`await db.syncIndexes('products')`
   creates missing declared keys and drops undeclared ones, `_id_` kept).
 
@@ -972,9 +1021,10 @@ unknown keys in object literals AND non-literal patches. The only way an unknown
 key passes is a variable explicitly typed with an index signature
 (`Record<string, any>`) — prefer inline literals for full checking.
 
-**Index drift.** `createSchema` installs declared indexes; if they drift out of
-band (manual drops, other tooling), `syncIndexes('collection')` reconciles —
-creates missing declared indexes and drops undeclared ones (`_id_` kept).
+**Index drift.** `createSchema` installs declared indexes on creation and adds
+newly-declared ones on re-provision; if indexes drift out of band (manual
+drops, other tooling), `syncIndexes('collection')` reconciles — creates
+missing declared indexes and drops undeclared ones (`_id_` kept).
 
 **Observability.** `QueryCache.stats()` (hits/misses/evictions/…) and
 `hot.stats()` (per-query hits/misses/refreshes/loadErrors/evictions/…) give you

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as mongodb from 'mongodb';
 import { Db, MongoClient, ClientSession, Document, Filter, Hint, CollationOptions, ReadPreferenceLike, ReadConcern, WriteConcern, WithId, Condition, RootFilterOperators, Collection, FindOptions, Sort, FindCursor, ObjectId, Decimal128, ReadConcernLike, AggregateOptions, AggregationCursor, CreateCollectionOptions, TransactionOptions, InsertOneOptions, InsertOneResult, InsertManyResult, UpdateOptions, UpdateResult, FindOneAndUpdateOptions, DeleteResult, ChangeStreamOptions, ChangeStream } from 'mongodb';
-import { L as LoggerLike } from './timeout-BE_ULjdG.js';
-export { C as CacheOptions, a as LRU, b as LRUOptions, c as LogFn, d as LogLevel, e as createCachedAsyncFactory, f as createCachedFactory, g as createConsoleLogger, h as createNoopLogger, i as hashString, s as sleep, j as sleepJittered, k as stableHash, l as stableStringify, w as withTimeout } from './timeout-BE_ULjdG.js';
+import { L as LoggerLike } from './timeout-B10CTiGm.js';
+export { C as CacheOptions, a as LRU, b as LRUOptions, c as LogFn, d as LogLevel, e as createCachedAsyncFactory, f as createCachedFactory, g as createConsoleLogger, h as createNoopLogger, i as hashString, s as sleep, j as sleepJittered, k as stableHash, l as stableStringify, w as withTimeout } from './timeout-B10CTiGm.js';
 import * as bson from 'bson';
 
 /**
@@ -13,10 +13,37 @@ import * as bson from 'bson';
 
 /** A collection to watch for invalidation. `collection` is the PHYSICAL name. */
 interface HotCollectionRef {
-    /** Raw `Db` handle (e.g. `service.db.primaryClient.client`). */
-    db: Db;
+    /**
+     * Raw `Db` handle (e.g. `service.db.primaryClient.client`) — or a lazy
+     * `() => Db` accessor resolved when the watcher starts. The lazy form lets
+     * apps register queries at module scope (before the connection exists) and
+     * only touch the live handle at `start()` time.
+     */
+    db: Db | (() => Db);
     /** Physical collection name whose writes invalidate bound queries. */
     collection: string;
+    /**
+     * Fine-tuned invalidation: extract the document ids (or groups of ids) that
+     * one loader call's arguments depend on. Without this, ANY write to the
+     * collection purges every entry of every query bound to it; with it, a
+     * change-stream event (replica mode) or a manual
+     * `invalidateIds(collection, [id])` call purges ONLY the entries that
+     * extracted this id — sibling entries stay warm.
+     *
+     * Return every id the result depends on (one per document, or many for
+     * grouped/aggregated results). Ids may be strings, numbers, ObjectIds… —
+     * they are compared after stable normalization, so an ObjectId and its hex
+     * string match.
+     *
+     * Must be pure and cheap (it runs once per load). If it throws or returns a
+     * non-array the entry is marked conservative: it is dropped by ANY targeted
+     * change on that collection instead of being kept incorrectly.
+     *
+     * Typed as `never`-params (contravariance-safe, same trick as `LRU`'s
+     * `onEvict`): declare your own parameter types and they line up with the
+     * query's loader args — `idsOf: (team: string) => members(team)`.
+     */
+    idsOf?: (...args: never) => readonly unknown[];
 }
 /** Opt-in query registration. `TArgs` = the parameter tuple, `TResult` = loader result. */
 interface HotQueryConfig<TArgs extends readonly unknown[], TResult> {
@@ -124,6 +151,8 @@ interface HotQueryStats {
     loadErrors: number;
     /** Values too large to cache (`maxValueBytes`). */
     sizeSkips: number;
+    /** Entries dropped by id-targeted invalidation (`invalidateIds` / change events). */
+    idDrops: number;
     /** Capacity evictions (LRU). */
     evictions: number;
 }
@@ -187,18 +216,41 @@ declare class HotCache {
      * called manually to wire ORM write hooks in standalone mode.
      */
     invalidateCollection(collection: string): void;
+    /**
+     * Fine-tuned purge: drop only the entries that depend on specific document
+     * ids of a watched collection. Two complementary mechanisms feed it:
+     *
+     *   - **Replica mode** — the change stream extracts `documentKey._id` from
+     *     each event and calls this with just that id, so a write to one document
+     *     no longer purges every query bound to the whole collection.
+     *   - **Manual (any mode)** — call it from ORM after-write hooks or anywhere
+     *     else you know exactly which ids changed.
+     *
+     * Per query bound to `collection`, semantics are:
+     *   - watch ref declares `idsOf` → only LRU entries whose extracted ids
+     *     include one of `ids` are dropped (`depsAll` entries — where extraction
+     *     failed — are dropped too; conservative). Sibling entries stay warm and
+     *     `stats().perQuery[name].idDrops` counts what was dropped.
+     *   - no `idsOf` on any bound ref → full purge of that query (the
+     *     `invalidateCollection` behavior — the safe default).
+     */
+    invalidateIds(collection: string, ids: readonly unknown[]): void;
     /** Drop every cached entry for every query. */
     clear(): void;
     /**
      * Runtime observability snapshot: total queries/entries plus per-query
-     * counters (`hits`, `misses`, background `refreshes`, `loadErrors`, and
-     * `sizeSkips` for entries dropped by `maxValueBytes`). Useful for dashboards
-     * and cache-effectiveness checks.
+     * counters (`hits`, `misses`, background `refreshes`, `loadErrors`,
+     * `sizeSkips` for entries dropped by `maxValueBytes`, and `idDrops` for
+     * entries dropped by id-targeted invalidation). Useful for dashboards and
+     * cache-effectiveness checks.
      */
     stats(): HotCacheStats;
     /**
      * Probe replica support once, then start change-stream watchers (replica) or
      * the global refresh ticker (standalone). Idempotent — resolves the mode.
+     * A FAILED start does not stick: the memoized promise is cleared so the next
+     * `get()`/`start()` retries probing (one transient blip during startup must
+     * not disable background freshness for the life of the instance).
      */
     start(): Promise<HotCacheMode>;
     /**
@@ -207,11 +259,25 @@ declare class HotCache {
      * re-probes or re-opens background resources.
      */
     stop(): Promise<void>;
+    /**
+     * A FAILED start does not stick: clear the memoized state so the next
+     * `get()`/`start()` retries probing (one transient blip during startup must
+     * not disable background freshness for the life of the instance).
+     */
+    private forgetFailedStart;
     private runStart;
     private ensureStarted;
     private defaultProbe;
     private fetch;
     private setEntry;
+    /**
+     * Extract the watched-document dependencies of one loader call. Namespaced by
+     * collection so multi-collection watchers never cross-invalidate. An extractor
+     * that throws or returns a non-array yields `{ depsAll: true }` — the entry is
+     * then dropped by ANY targeted change on its watched collections instead of
+     * being incorrectly kept.
+     */
+    private computeDeps;
 }
 /** Create a new global hot-cache instance. */
 declare const createHotCache: (options?: HotCacheOptions) => HotCache;
@@ -286,6 +352,12 @@ declare const cacheCollectionKey: (dbName: string, physical: string) => string;
 declare class QueryCache {
     private lru;
     private index;
+    /**
+     * Reverse index: key → every collection it is registered under. Without it,
+     * keys dropped by TTL expiry / capacity eviction / version-guard would stay
+     * listed in `index` forever (unbounded growth + O(dead) invalidation scans).
+     */
+    private keyCollections;
     /** Per-collection version — bumped on every invalidation/clear of that collection. */
     private colVersions;
     private ttlMs;
@@ -309,6 +381,10 @@ declare class QueryCache {
      */
     versionOf(collection: string): number;
     get(key: string): unknown | undefined;
+    /** Remove a key from the LRU and every collection index that references it. */
+    private dropKey;
+    /** Remove `key` from `index` (called for evictions AND explicit drops). */
+    private unregisterKey;
     set(key: string, value: unknown, ttlMs?: number, collections?: string[], versions?: Record<string, number>): void;
     delete(key: string): void;
     /** Drop every cached entry belonging to a physical collection. */
@@ -439,6 +515,14 @@ declare const TRANSIENT_MONGO_ERROR_CODES: ReadonlySet<number>;
 declare const isMongoTransientError: (error: unknown) => boolean;
 /** True when the error is a duplicate-key violation (code 11000 / E11000 message). */
 declare const isMongoDuplicateKeyError: (error: unknown) => boolean;
+/**
+ * True when the deployment cannot run transactions at all (standalone mongod,
+ * or storage engine without retryable writes) — callers fall back to
+ * non-transactional execution. Shared by BOTH fallback layers
+ * (`withGracefulMongoTransaction` and the service `transaction` op) so they
+ * classify identically.
+ */
+declare const isTransactionUnsupportedError: (error: unknown) => boolean;
 
 /** Minimal transaction runner surface (satisfied by the service `transaction`). */
 interface MongoTransactionRunner {
@@ -453,8 +537,14 @@ interface GracefulTransactionOptions {
 }
 /**
  * Run `fn` inside a transaction when the deployment supports it; otherwise run
- * with a `null` session (no-op fallback). Also handles the "retryable writes
- * unsupported" error by re-running with a null session.
+ * with a `null` session (no-op fallback). Also handles "transactions
+ * unsupported" errors by re-running with a null session.
+ *
+ * When capability state is UNKNOWN (probe failed/timed out and no URL hint or
+ * env override says otherwise), we ATTEMPT the real transaction rather than
+ * silently downgrading — a transient startup blip must not turn an atomic
+ * write into a non-atomic one. The catch path still falls back cleanly on a
+ * genuinely unsupported deployment (at the cost of one failed round trip).
  */
 declare const withGracefulMongoTransaction: <T>(runner: MongoTransactionRunner, fn: (session: ClientSession | null) => Promise<T>, options?: GracefulTransactionOptions) => Promise<T>;
 
@@ -478,21 +568,6 @@ declare const HOOK_NAMES: readonly HookName[];
 /** Run a single hook (no-op when the collection has none registered). */
 declare const runHooks: <TSchema = Document>(registry: HooksRegistry | undefined, collection: string, name: HookName, ctx: HookContext<TSchema>) => Promise<void>;
 
-/**
- * A self-contained DataLoader — batch + cache loading that eliminates the
- * N+1 query problem (the classic GraphQL utility, implemented from scratch so
- * the ORM owns its batching behavior).
- *
- * Semantics:
- *  - concurrent `load(key)` calls made in the same tick are coalesced into ONE
- *    `batch(keys)` call (flushed on a microtask, or after `maxBatchDelayMs`)
- *  - the batch result is a Map (key → value); a missing key resolves `undefined`
- *  - results are cached per key (canonicalized via `keyOf`) for the loader's
- *    lifetime; `clear`/`clearAll` reset the cache
- *  - a FAILED batch is never cached: its keys are evicted so a later `load`
- *    runs a fresh batch instead of re-surfacing the same rejection
- *  - `maxBatchSize` splits oversized batches
- */
 interface DataLoaderOptions<Key, Value> {
     /** Resolve a batch of keys → one Map. Keys that have no row should be absent. */
     batch: (keys: Key[]) => Promise<Map<Key, Value>>;
@@ -549,7 +624,10 @@ interface MigrationModule {
 interface MongoMigrationRunner {
     /** Apply every not-yet-applied migration in numeric order. */
     up(): Promise<void>;
-    /** Roll back applied migrations in reverse order (down to `targetName` when given). */
+    /**
+     * Roll back applied migrations in reverse order (down to `targetName` when
+     * given). An unknown `targetName` throws BEFORE anything is rolled back.
+     */
     down(targetName?: string): Promise<void>;
     status(): Promise<{
         applied: string[];
@@ -561,6 +639,18 @@ interface MongoMigrationRunner {
 interface MongoMigrationRunnerOptions {
     migrationDir?: string;
     logger?: LoggerLike;
+    /**
+     * Which connected database the journal + migrations target (key of the
+     * service's db map). Defaults to the FIRST connected key — set this explicitly
+     * in multi-database services to avoid silently migrating the wrong one.
+     */
+    db?: string;
+    /**
+     * Migration claim lease in ms (default 120_000). A `running` claim older than
+     * the lease is considered orphaned (hard crash) and may be stolen by another
+     * runner; live claims are renewed automatically during long `up()`s.
+     */
+    leaseMs?: number;
 }
 
 /**
@@ -568,11 +658,14 @@ interface MongoMigrationRunnerOptions {
  * two sub-systems:
  *
  *   - `./files.ts`   — discover / load / scaffold `NNN_name.ts` files
- *   - `./journal.ts` — claim-based `_migrations` journal (atomic, crash-safe)
+ *   - `./journal.ts` — lease-based `_migrations` journal (atomic, crash-safe)
  *
- * `up()` applies pending migrations in numeric order with an atomic claim;
- * `down()` rolls back applied migrations in reverse order; `status()` reports
- * applied/pending; `create()` scaffolds a new file.
+ * `up()` applies pending migrations in numeric order under an exclusive claim
+ * with an auto-renewed lease (long migrations can't be stolen by another
+ * runner, but a crashed runner's claim expires); `down()` rolls back applied
+ * migrations in reverse order and validates its target BEFORE destroying
+ * anything; `status()` reports applied/pending; `create()` scaffolds a new file
+ * atomically (`wx` — concurrent scaffolds never clobber each other).
  */
 
 /** The `service` shape the runner needs (one connected manager + config/logger). */
@@ -592,10 +685,12 @@ interface RetryOptions {
 }
 /**
  * Retry `fn` while it throws a *transient* Mongo error (network / not-primary /
- * sharding), with exponential backoff `delayMs * 2^attempt`. Domain errors and
- * genuine data errors are never retried.
+ * sharding / server-selection during failover), with exponential backoff
+ * `delayMs * 2^attempt` plus ±20% jitter — synchronized retry waves against a
+ * recovering cluster amplify outages instead of absorbing them. Domain errors
+ * and genuine data errors are never retried.
  */
-declare const withRetry: <T>(fn: () => Promise<T>, options?: RetryOptions, _ctx?: unknown) => Promise<T>;
+declare const withRetry: <T>(fn: () => Promise<T>, options?: RetryOptions) => Promise<T>;
 /**
  * Manual transaction helper: start → run → commit, aborting + ending the
  * session on any failure. Prefer the service-level `transaction()` which also
@@ -939,14 +1034,22 @@ interface QueryOptions {
      * a committed write whose ack was lost would be re-executed, so enable only
      * for idempotent writes). Default: off for write ops.
      */
-    retryWrites?: boolean /**
+    /**
+     * Per-op write-retry override. Reads always retry transient errors; writes
+     * retry ONLY when `retryWrites: true` (retrying a write is at-least-once —
+     * a committed write whose ack was lost would be re-executed, so enable only
+     * for idempotent writes). Default: off for write ops.
+     */
+    retryWrites?: boolean;
+    /**
      * Per-op schema-drift policy override for reads (see `MongoServiceConfig.drift`).
      * `true` → `'throw'`, `false` → `'off'`, or an explicit `DriftMode` string.
      * Unset inherits the service-level default (`'report'`). Only checked when a
      * document is fetched from the DB (cache-miss); projected/partial reads are
      * skipped.
-     */;
-    drift?: DriftMode | boolean /** Driver-level options forwarded untouched to the underlying call. */;
+     */
+    drift?: DriftMode | boolean;
+    /** Driver-level options forwarded untouched to the underlying call. */
     collation?: CollationOptions;
     readPreference?: ReadPreferenceLike;
     readConcern?: ReadConcern;
@@ -1013,16 +1116,16 @@ interface QueryBuilderContext<TDoc extends Document> {
     run: <T>(opName: string, filter: FilterInput<TDoc>, execute: (driverOpts: FindOptions) => Promise<T>, options?: QueryOptions) => Promise<T>;
 }
 /**
- * Lazy, fluent, schema-typed query builder. Nothing hits the database until an
- * executor (`one`/`many`/`cursor`/`count`/`exists`) is called. Projections via
- * `select` are pushed to the driver so only requested fields are transferred.
+ * Lazy, fluent, IMMUTABLE, schema-typed query builder. Every chain method
+ * returns a NEW builder — a stored base query can be safely reused as a
+ * template without derived chains contaminating it:
+ *
+ *   const admins = users.query('users').where({ role: 'admin' });
+ *   await admins.where({ age: { $gte: 18 } }).many(); // base unchanged
  *
- *   await users.query('users')
- *     .where({ role: 'admin' })
- *     .sort({ createdAt: -1 })
- *     .select(['_id', 'email'])
- *     .limit(20)
- *     .many();
+ * Nothing hits the database until an executor (`one`/`many`/`cursor`/`count`/
+ * `exists`) is called. Projections via `select` are pushed to the driver so
+ * only requested fields are transferred.
  */
 declare class QueryBuilder<TDoc extends Document, TSelection = TDoc> {
     private readonly ctx;
@@ -1034,34 +1137,39 @@ declare class QueryBuilder<TDoc extends Document, TSelection = TDoc> {
     private _options;
     constructor(ctx: QueryBuilderContext<TDoc>);
     get filter(): FilterInput<TDoc>;
-    /** Shallow-merge a filter into the current one (later keys win). */
-    where(filter: FilterInput<TDoc>): this;
-    /** AND-combine the current filter with a new one. */
-    and(filter: FilterInput<TDoc>): this;
-    /** OR-combine: current filter AND (filter1 OR filter2 ...). */
-    or(...filters: Array<FilterInput<TDoc>>): this;
+    /** Copy-on-write fork used by every chain method. */
+    private fork;
+    /** Merge a filter into the current one (operator docs deep-merge per key). */
+    where(filter: FilterInput<TDoc>): QueryBuilder<TDoc, TSelection>;
+    /** AND-combine the current filter with a new one (stays flat across repeats). */
+    and(filter: FilterInput<TDoc>): QueryBuilder<TDoc, TSelection>;
+    /**
+     * OR-combine: current filter AND (filter1 OR filter2 ...). Requires at least
+     * one filter — an empty `$or` is rejected by the server.
+     */
+    or(...filters: Array<FilterInput<TDoc>>): QueryBuilder<TDoc, TSelection>;
     /** Set the sort order (`{ field: 1 | -1 }`). */
-    sort(sort: Sort): this;
+    sort(sort: Sort): QueryBuilder<TDoc, TSelection>;
     /** Skip the first `n` matching documents. */
-    skip(n: number): this;
+    skip(n: number): QueryBuilder<TDoc, TSelection>;
     /** Limit the result set to `n` documents. */
-    limit(n: number): this;
+    limit(n: number): QueryBuilder<TDoc, TSelection>;
     /** Project only the given fields — the projection is pushed to the driver. */
     select<const K extends keyof TSelection>(fields: readonly K[]): QueryBuilder<TDoc, Pick<TSelection, K>>;
     /** Raw projection document (`{ field: 1 }` / `{ field: 0 }`). */
-    project(projection: Document): this;
+    project(projection: Document): QueryBuilder<TDoc, TSelection>;
     /** Set the index hint. */
-    hint(hint: Hint): this;
+    hint(hint: Hint): QueryBuilder<TDoc, TSelection>;
     /** Set the driver cursor batch size. */
-    batchSize(n: number): this;
+    batchSize(n: number): QueryBuilder<TDoc, TSelection>;
     /** Run the query inside a transaction session. */
-    session(session: NonNullable<QueryOptions['session']>): this;
+    session(session: NonNullable<QueryOptions['session']>): QueryBuilder<TDoc, TSelection>;
     /** Cap server-side execution time. */
-    maxTimeMS(ms: number): this;
+    maxTimeMS(ms: number): QueryBuilder<TDoc, TSelection>;
     /** Bypass the read cache for this query when `false`. */
-    cache(on: boolean): this;
+    cache(on: boolean): QueryBuilder<TDoc, TSelection>;
     /** Override in-flight dedup for this query when set. */
-    dedupe(on: boolean): this;
+    dedupe(on: boolean): QueryBuilder<TDoc, TSelection>;
     /** Compile the builder into driver options (does not execute). */
     private compile;
     private countOptions;
@@ -1069,11 +1177,11 @@ declare class QueryBuilder<TDoc extends Document, TSelection = TDoc> {
     one(): Promise<WithId<TSelection> | null>;
     /** Fetch many documents (default limit 100 when unset). */
     many(): Promise<WithId<TSelection>[]>;
-    /** Streaming cursor (raw driver cursor; no retry, applies batchSize). */
+    /** Streaming cursor (raw driver cursor; no retry/cache/drift — caller-owned). */
     cursor(): FindCursor<WithId<TDoc>>;
     /** Count matching documents. */
     count(): Promise<number>;
-    /** True when at least one document matches. */
+    /** True when at least one document matches (`_id`-only projection — no doc transfer). */
     exists(): Promise<boolean>;
 }
 
@@ -1359,6 +1467,13 @@ interface DbOpMeta {
     physicalCollection?: string;
     db: string;
     op: string;
+    /**
+     * What was sent to the database (filter / document / update / pipeline /
+     * options). Surfaced in the ignex debugbar as the span's `params`, so the
+     * dashboard shows exactly what the query carried — not just its name.
+     * Optional: ops without a payload worth showing omit it.
+     */
+    params?: unknown;
 }
 
 /**
@@ -1441,7 +1556,7 @@ interface TextSearchPagination {
 
 interface CrudOpDeps<TCollection> {
     trace: <T>(meta: DbOpMeta, fn: () => T | Promise<T>) => Promise<T>;
-    meta: (collection: TCollection, op: string) => DbOpMeta;
+    meta: (collection: TCollection, op: string, params?: unknown) => DbOpMeta;
 }
 
 /**
@@ -2024,8 +2139,14 @@ interface DbHealthResult {
     ok: boolean;
     /** Ping round-trip time in ms (present when `ok`). */
     latencyMs?: number;
+    /** Why the ping failed — timeout vs auth vs network (present when `!ok`). */
+    error?: string;
 }
 interface HealthReport {
+    /**
+     * Overall status. `false` when ANY db fails — including the degenerate
+     * "no dbs connected" case (an empty manager record is NOT healthy).
+     */
     ok: boolean;
     /** Total elapsed time across all pings in ms. */
     latencyMs: number;
@@ -2138,6 +2259,14 @@ interface PaginationConfig {
     sort?: Record<string, 1 | -1>;
     /** Cap on the requested limit (default DEFAULT_MAX_LIMIT=1000). */
     maxLimit?: number;
+    /**
+     * Projection applied to the data facet (e.g. `{ _id: 1, updatedAt: 1 }`).
+     *
+     * Enables lean list reads — only the projected fields cross the wire. When
+     * set, the schema-drift check is skipped for the page (projected docs
+     * intentionally lack the collection's full field set).
+     */
+    projection?: Document;
     /** Stages prepended to the data facet (e.g. extra $match). */
     prePipeline?: Document[];
     /** Stages appended inside the data facet. */
@@ -2298,9 +2427,19 @@ interface SchemaOpsOptions {
     getDefinition: (logical: string) => CollectionRegistryEntry | undefined;
 }
 /**
- * Schema-first collection management. `createSchema` provisions a collection
- * with a `$jsonSchema` validator derived from the ORM schema (and creates any
- * declared indexes); `updateSchema` hot-swaps the validator via `collMod`.
+ * Schema-first collection management.
+ *
+ * `createSchema` is IDEMPOTENT and SELF-RECONCILING: on a NEW collection it
+ * provisions the `$jsonSchema` validator derived from the ORM schema plus the
+ * declared indexes; when the collection ALREADY exists it upgrades the DB
+ * schema to match the current ORM schema — hot-swapping the validator via
+ * `collMod` only when it has actually drifted, and creating any newly-declared
+ * indexes. It never drops indexes or data (destructive reconciliation stays
+ * explicit via `syncIndexes`), so it is safe to call on every boot: the Mongo
+ * schema follows the app schema automatically as models change.
+ *
+ * `updateSchema` hot-swaps a validator explicitly (via `collMod`);
+ * `syncIndexes` reconciles index drift (create missing, drop undeclared).
  */
 declare const makeSchemaOps: (client: Db, _logger: LoggerLike, opts: SchemaOpsOptions) => {
     createSchema: (collection: string, createCollectionOptions?: CreateCollectionOptions) => Promise<void>;
@@ -2506,7 +2645,13 @@ declare const createResolveCollectionName: (config: ResolveCollectionConfig) =>
  * explicit (mirrors sdk-db `normalizeMongoUrl`):
  *  - retryWrites=false unless already set (keeps semantics predictable)
  *  - w=1 unless another write concern is present
- *  - directConnection=true for single-host non-replicaSet URIs
+ *  - directConnection=true ONLY for single-host, non-replica-set,
+ *    non-SRV URIs (`mongodb+srv` implies replica-set discovery — appending
+ *    `directConnection` there makes the driver reject the URI)
+ *
+ * Parsing is manual (string split + URLSearchParams) instead of WHATWG `new
+ * URL`: the URL parser rejects multi-host seed lists (`h1:27017,h2:27017` —
+ * it reads `,h2` as a port) and re-encodes userinfo/path in surprising ways.
  */
 declare const normalizeMongoUrl: (rawUrl: string) => string;
 
@@ -2560,8 +2705,14 @@ declare const decodeCursor: (cursor: string) => KeysetCursor;
 declare const buildKeysetFilter: (sort: Record<string, 1 | -1>, values: unknown[], direction: "after" | "before") => Document;
 
 /**
- * Merge multiple Mongo filters into one. Empty/undefined parts are skipped and
- * later keys win on shallow conflicts (mirrors sdk-db `mergeMongoFilters`).
+ * Merge multiple Mongo filters into one. Empty/undefined parts are skipped.
+ *
+ * Conflicting keys deep-merge when BOTH sides are plain objects (operator
+ * documents like `{ $gte: 18 }` / `{ $in: [...] }`), so
+ * `merge({ role: 'admin', age: { $gte: 18 } }, { age: { $lte: 65 } })`
+ * keeps both range clauses instead of the old shallow-assign silently
+ * dropping `$gte`. Scalars replace (last write wins). Top-level `$and`/`$or`
+ * arrays CONCATENATE — dropping a sibling branch would change semantics.
  */
 declare const mergeMongoFilters: <T extends Document>(...parts: Array<Filter<T> | undefined>) => Filter<T>;
 
@@ -2617,4 +2768,4 @@ declare const createMongoToolkit: <TClients extends DbClientsDefinition = DbClie
 };
 type MongoToolkit<TClients extends DbClientsDefinition> = ReturnType<typeof createMongoToolkit<TClients>>;
 
-export { type AccumulatorResult, type AccumulatorSpec, type Added, type AggregationMeta, type AggregationStages, type AnyField, AppError, type ArrayField, BadRequest, type BelongsToRelation, type BooleanField, type CacheInvalidationRef, CacheInvalidator, type Chainable, type CollectionDefinition, type CollectionDoc, type CollectionLike, type CollectionManager, type CollectionMap, type CollectionName, type CollectionTimestamps, type CollectionValue, type CrudListQuery, type CrudOps, type CursorPage, type CursorPaginationConfig, type DBClientDefinition, DEFAULT_FIND_LIMIT, DEFAULT_MAX_LIMIT, DataLoader, type DataLoaderOptions, type DateField, type DateRangeConfig, type DbClientsDefinition, type DbHealthResult, type DecimalField, DomainError, type DoubleField, type DriftIssue, type DriftIssueCode, type DriftMode, ERROR_HTTP_STATUS, type EnumField, type ErrorContext, type ExprResult, type ExtractCollectionNames, type ExtractCollectionType, type ExtractDbNames, type FacetOutput, type FacetPipelineStage, type FacetSpec, type FieldFlags, type FieldMeta, type FieldName, type FieldRef, type FilterInput, type FindQueryOptions, type ForeignDocOf, type GeoNearOutput, type GeoNearSpec, type GeoPoint, type GeoPointField, type GracefulTransactionOptions, type GroupByConfig, type GroupSpec, type Grouped, HOOK_NAMES, type HasManyRelation, type HealthReport, type Hook, type HookContext, type HookMap, type HookName, type HooksRegistry, HotCache, type HotCacheMode, type HotCacheOptions, type HotCacheStats, type HotCollectionRef, type HotQueryAccessor, type HotQueryConfig, type HotQueryStats, InFlight, type IndexSpec, type InferDoc, type InferField, InfraError, type InsertInput, type IntegerField, type JoinedFields, type KeysetCursor, LoggerLike, type LongField, type LookupConfig, type LookupJoinedFor, type LookupParams, type LookupSpecFor, MAX_BATCH_OPS, type ManyToManyRelation, type MigrationContext, type MigrationModule, type MongoCapabilities, type MongoCapabilitiesStore, type MongoJsonSchema, type MongoMigrationRunner, type MongoMigrationRunnerOptions, type MongoService, type MongoServiceConfig, type MongoToolkit, type MongoToolkitOptions, type MongoTransactionRunner, type NamedCollection, type NamedCollectionDefinition, type NamedObjectField, type NormalizedPagination, type NullField, type NumberBounds, type NumberField, type ObjectField, type ObjectIdField, type PaginationConfig, type PaginationResult, PipelineBuilder, type PipelineCustomization, type PipelineStage, type PopulateOptions, type Projected, type Projection, QueryBuilder, type QueryBuilderContext, QueryCache, type QueryCacheOptions, type QueryCacheStats, type QueryOptions, type RawField, type RelationDef, type RelationDefBase, type RemoveIndexSignature, type Repository, type RepositoryOptions, type ResolvedQueryOptions, type RetryOptions, type SchemaType, type SearchConfig, type SortKeys, type StringField, type SyncIndexesResult, TRANSIENT_MONGO_ERROR_CODES, type TimestampsByCollection, type Unsetted, type UnwindSpec, type Unwound, type UpdateInput, type UpdateOperators, type ValidRelation, type VersionedUpdateResult, belongsTo, buildKeysetFilter, buildMongoActiveFilter, buildPaginationResult, cacheCollectionKey, canonicalKey, createHotCache, createMongoCapabilitiesStore, createMongoMigrationRunner, createMongoService, createMongoToolkit, createRepository, createResolveCollectionName, decodeCursor, defineCollection, defineCollections, encodeCursor, hasMany, httpStatusForError, isAppError, isDomainError, isInfraError, isMappedMongoError, isMongoDuplicateKeyError, isMongoTransientError, manyToMany, mapMongoDriverError, mergeMongoActiveFilter, mergeMongoFilters, normalizeMongoUrl, normalizePageLimit, optional, probeMongoCapabilities, runHooks, s, serializeError, stripDocumentId, stripPrimaryKey, toMongoSchema, toMongoValidator, validateDoc, withDefault, withGracefulMongoTransaction, withRetry, withTransaction };
+export { type AccumulatorResult, type AccumulatorSpec, type Added, type AggregationMeta, type AggregationStages, type AnyField, AppError, type ArrayField, BadRequest, type BelongsToRelation, type BooleanField, type CacheInvalidationRef, CacheInvalidator, type Chainable, type CollectionDefinition, type CollectionDoc, type CollectionLike, type CollectionManager, type CollectionMap, type CollectionName, type CollectionTimestamps, type CollectionValue, type CrudListQuery, type CrudOps, type CursorPage, type CursorPaginationConfig, type DBClientDefinition, DEFAULT_FIND_LIMIT, DEFAULT_MAX_LIMIT, DataLoader, type DataLoaderOptions, type DateField, type DateRangeConfig, type DbClientsDefinition, type DbHealthResult, type DecimalField, DomainError, type DoubleField, type DriftIssue, type DriftIssueCode, type DriftMode, ERROR_HTTP_STATUS, type EnumField, type ErrorContext, type ExprResult, type ExtractCollectionNames, type ExtractCollectionType, type ExtractDbNames, type FacetOutput, type FacetPipelineStage, type FacetSpec, type FieldFlags, type FieldMeta, type FieldName, type FieldRef, type FilterInput, type FindQueryOptions, type ForeignDocOf, type GeoNearOutput, type GeoNearSpec, type GeoPoint, type GeoPointField, type GracefulTransactionOptions, type GroupByConfig, type GroupSpec, type Grouped, HOOK_NAMES, type HasManyRelation, type HealthReport, type Hook, type HookContext, type HookMap, type HookName, type HooksRegistry, HotCache, type HotCacheMode, type HotCacheOptions, type HotCacheStats, type HotCollectionRef, type HotQueryAccessor, type HotQueryConfig, type HotQueryStats, InFlight, type IndexSpec, type InferDoc, type InferField, InfraError, type InsertInput, type IntegerField, type JoinedFields, type KeysetCursor, LoggerLike, type LongField, type LookupConfig, type LookupJoinedFor, type LookupParams, type LookupSpecFor, MAX_BATCH_OPS, type ManyToManyRelation, type MigrationContext, type MigrationModule, type MongoCapabilities, type MongoCapabilitiesStore, type MongoJsonSchema, type MongoMigrationRunner, type MongoMigrationRunnerOptions, type MongoService, type MongoServiceConfig, type MongoToolkit, type MongoToolkitOptions, type MongoTransactionRunner, type NamedCollection, type NamedCollectionDefinition, type NamedObjectField, type NormalizedPagination, type NullField, type NumberBounds, type NumberField, type ObjectField, type ObjectIdField, type PaginationConfig, type PaginationResult, PipelineBuilder, type PipelineCustomization, type PipelineStage, type PopulateOptions, type Projected, type Projection, QueryBuilder, type QueryBuilderContext, QueryCache, type QueryCacheOptions, type QueryCacheStats, type QueryOptions, type RawField, type RelationDef, type RelationDefBase, type RemoveIndexSignature, type Repository, type RepositoryOptions, type ResolvedQueryOptions, type RetryOptions, type SchemaType, type SearchConfig, type SortKeys, type StringField, type SyncIndexesResult, TRANSIENT_MONGO_ERROR_CODES, type TimestampsByCollection, type Unsetted, type UnwindSpec, type Unwound, type UpdateInput, type UpdateOperators, type ValidRelation, type VersionedUpdateResult, belongsTo, buildKeysetFilter, buildMongoActiveFilter, buildPaginationResult, cacheCollectionKey, canonicalKey, createHotCache, createMongoCapabilitiesStore, createMongoMigrationRunner, createMongoService, createMongoToolkit, createRepository, createResolveCollectionName, decodeCursor, defineCollection, defineCollections, encodeCursor, hasMany, httpStatusForError, isAppError, isDomainError, isInfraError, isMappedMongoError, isMongoDuplicateKeyError, isMongoTransientError, isTransactionUnsupportedError, manyToMany, mapMongoDriverError, mergeMongoActiveFilter, mergeMongoFilters, normalizeMongoUrl, normalizePageLimit, optional, probeMongoCapabilities, runHooks, s, serializeError, stripDocumentId, stripPrimaryKey, toMongoSchema, toMongoValidator, validateDoc, withDefault, withGracefulMongoTransaction, withRetry, withTransaction };