@ignex/ninox 0.1.7 → 0.2.0

package/README.md

@@ -281,7 +281,7 @@ builder, and the MongoDB `$jsonSchema` validator + indexes installed by
 | field kind | `s.*` | inferred TS type |
 | --- | --- | --- |
 | string / int / number | `s.string()` / `s.integer()` / `s.number()` | `string` / `number` / `number` |
-| exact BSON kinds | `s.double()` / `s.long()` / `s.decimal()` | `number` / `number` / `Decimal128` |
+| exact BSON kinds | `s.double()` / `s.long()` / `s.decimal()` | `number` / `Long` / `Decimal128` |
 | other scalars | `s.boolean()` / `s.date()` / `s.objectId()` | `boolean` / `Date` / `ObjectId` |
 | enum | `s.enum(['a', 'b'] as const)` | `'a' \| 'b'` (string or numeric literals) |
 | array | `s.array(s.string())` | `string[]` |
@@ -293,8 +293,10 @@ builder, and the MongoDB `$jsonSchema` validator + indexes installed by
 Constraints mirror `$jsonSchema`: strings (`minLength` / `maxLength` / `pattern`),
 numbers (`minimum` / `maximum` / `multipleOf` / `exclusiveMinimum` /
 `exclusiveMaximum`), arrays (`minItems` / `maxItems` / `uniqueItems`), objects
-(`minProperties` / `maxProperties` / `additionalProperties`). `format` is
-accepted but a no-op (MongoDB rejects the `$jsonSchema` keyword).
+(`minProperties` / `maxProperties` / `additionalProperties`). String `format`
+is validated client-side for `email`, `uri`, `date-time`, `date`, `uuid`,
+`hostname`, `ipv4`, and `ipv6`; it is not sent to MongoDB because the server
+rejects that `$jsonSchema` keyword.
 
 ```ts
 const userSchema = s.object({
@@ -342,7 +344,10 @@ do {
 ```
 
 `paginateCursor` supports `after` (forward) and `before` (backward); a sort whose
-keys don't match the cursor's is rejected at runtime.
+keys don't match the cursor's is rejected at runtime. The final sort key must be
+`_id` or an explicitly named `uniqueTiebreaker` with a unique index. Dotted paths
+and BSON values are supported. Offset pagination rejects offsets above 10,000 by
+default (`maxOffset` overrides); use keyset pagination for deep traversal.
 
 ## Geospatial
 
@@ -423,6 +428,11 @@ await db.populate(products, [
 // orders[0].customer, orders[0].more, products[0].tags are all typed.
 ```
 
+Populate reads are fresh by default. Pass `session`, `maxTimeMS`, read concern,
+or read preference in the options. `maxDocs` is an optional safety cap that
+throws on overflow rather than silently truncating a relation; `queryCache:
+true` explicitly opts into the shared read cache.
+
 ## Repository layer
 
 `createRepository(manager, 'collection')` wraps a manager + collection into a
@@ -454,12 +464,14 @@ const users = defineCollection('users', userSchema, {
 
 ## Transactions & migrations
 
-- `db.transaction(async (session) => ...)` — graceful session transactions with a
-  capability probe; on standalone servers (no transactions) it falls back to
-  plain non-transactional execution with `session === null`.
+- `db.transaction(async (session) => ...)` throws on standalone servers by
+  default. To accept non-atomic execution explicitly, pass
+  `{ allowNonTransactionalFallback: true }`; the callback then receives `null`.
 - `createMongoMigrationRunner(service, { migrationDir })` — file-based migrations
-  (`NNN_name.ts`, each exporting `up` / `down`) with a claim-based idempotency
-  journal (`_migrations`), safe under concurrent runners.
+  (`NNN_name.ts`, each exporting `up` / `down`) with a lease- and owner-token-
+  fenced journal (`_migrations`), safe under concurrent runners and stale-worker
+  takeover. Migrations should remain idempotent: file migrations are not
+  automatically wrapped in a database transaction.
 
 ```ts
 const runner = createMongoMigrationRunner(service, { migrationDir: './migrations' });
@@ -501,8 +513,8 @@ reports current size plus lifetime `hits` / `misses` / `sets` / `deletes` /
 > ⚠️ **Cache invalidation is write-through only.** Every ninox write drops that
 > collection's cached reads, but reads are **not** invalidated by external
 > writers — other processes, the raw `client` escape hatch, or direct DB
-> writes. With the default `ttlMs: 0` those reads stay stale indefinitely, so
-> multi-writer deployments should set `cache: { ttlMs }`, disable the cache,
+> writes. The default `ttlMs: 30_000` bounds that staleness; `ttlMs: 0` is an
+> explicit unbounded-cache opt-in. Multi-writer deployments can disable the cache,
 > route latency-critical reads through the change-stream-aware
 > [`createHotCache()`](#hot-cache-high-throughput), or — on a replica set — opt
 > into `cacheWatch: true`:
@@ -786,16 +798,18 @@ you need the code → status mapping yourself.
 > (at-least-once); opt in per op with `retryWrites: true`. Reads always retry
 > transient errors.
 
-Schema validation is enforced **by MongoDB** — the DB `$jsonSchema` validator
-derived from your schema is installed with `createSchema`, and the DB rejects
-violating writes with `VALIDATION_FAILED`. `createSchema` is **idempotent and
+Schema validation is enforced **by ninox and MongoDB** — inserts and full
+replacements are validated client-side by default (`validateWrites: false` opts
+out), while the DB `$jsonSchema` validator remains the backstop for partial
+updates, raw writes, and other clients. Violations raise `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).
+hot-swaps a validator explicitly (via `collMod`) and updates the manager's
+active schema. Client validation covers the DSL and raw `$jsonSchema` keywords;
+partial update operators are still enforced by the database.
 
 - **Strict by default** — `additionalProperties: false` is emitted unless a
   field opts out (`s.object({ ... }, { additionalProperties: true })`), so
@@ -898,6 +912,8 @@ createMongoService(clients, {
   cache: { maxSize: 1000, ttlMs: 30_000, clone: true }, // configure the default cache
   cacheWatch: true,           // change-stream invalidation of the cache (replica sets)
   drift: 'report',            // read-time schema-drift detection ('report'|'throw'|'off')
+  validateWrites: true,       // validate inserts/replacements before the DB call
+  allowNonTransactionalFallback: false, // throw instead of losing atomicity
   dedupeReads: true,
   perf: true,                 // master switch for cache + dedup
 });
@@ -908,8 +924,8 @@ createMongoService(clients, {
 - `service.health()` — ping every connected DB and report `{ ok, latencyMs, dbs }`.
 - **Multi-DB services** — define several clients in one service; each gets its own
   typed manager (`service.db.primaryClient`, `service.db.auditClient`, …), one
-  connection pool per URL, and **cache/dedup keys are namespaced by database** so
-  same-named collections in different databases never collide.
+  connection pool per URL, and **cache/dedup keys are namespaced by deployment,
+  database, and collection** so same-named collections never collide.
 - `watchCollection` / repository `.watch()` — caller-owned change streams.
 - `eachDb(fn)` — run a function over every connected manager.
 
@@ -1000,8 +1016,8 @@ bun run bench     # → bench/results/summary.json
 
 **Multi-DB cache isolation.** A single service can define several DB clients; the
 query cache and in-flight dedup are shared across them, and their keys are
-namespaced by **database** — so same-named physical collections in different
-databases can never share (or coalesce) entries. No action needed; it's handled.
+namespaced by **deployment and database** — same-named physical collections in
+different databases or clusters can never share (or coalesce) entries.
 
 **Standalone HotCache freshness is opt-in per query.** In standalone mode the
 ticker only refreshes queries that set `refreshIntervalMs`. A query with neither
@@ -1037,9 +1053,16 @@ the cache-effectiveness signals to watch in production.
 ## Tests
 
 ```bash
-bun test          # unit + integration (integration skips when no Mongo is reachable)
+bun test             # unit + integration (Mongo suites skip when no server is reachable)
+bun run test:e2e     # public-API workflows; fails unless MONGO_URL is reachable
 ```
 
+The e2e suite exercises real MongoDB schema validation, CRUD/repository flows,
+relations, aggregation, both pagination strategies, cache consistency,
+migrations, multi-DB behavior, and health checks. On a replica set it also
+verifies transaction commit/rollback; on standalone it verifies the explicit
+non-transactional fallback. Set `MONGO_URL` to select the server.
+
 ## Development
 
 ```bash
@@ -1058,7 +1081,8 @@ npm pack --dry-run    # inspect the published tarball contents
 The `files` allowlist ships `dist/`, `LICENSE`, and `README.md` — no `src/`,
 tests, or examples. CI enforces typecheck, lint, dependency audit, coverage
 (≥ 85%), the full example suite, a replica-set job for the HotCache
-change-stream tests, and an `npm pack` → fresh Node consumer smoke test.
+change-stream tests, e2e compatibility jobs for MongoDB 4.4/5/6/7/8, and an
+`npm pack` → fresh Node consumer that runs real CRUD and pagination.
 
 Release notes are kept in [`CHANGELOG.md`](./CHANGELOG.md). The publish gate
 (`prepublishOnly`) runs typecheck + lint + build.

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 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-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 { Db, MongoClient, ClientSession, Document, Filter, Hint, CollationOptions, ReadPreferenceLike, ReadConcernLike, WriteConcern, WithId, Condition, RootFilterOperators, Collection, FindOptions, Sort, FindCursor, ObjectId, Long, Decimal128, IndexDirection, CreateIndexesOptions, AggregateOptions, AggregationCursor, CreateCollectionOptions, TransactionOptions as TransactionOptions$1, InsertOneOptions, InsertOneResult, InsertManyResult, UpdateOptions, UpdateResult, FindOneAndUpdateOptions, DeleteResult, ChangeStreamOptions, ChangeStream } from 'mongodb';
+import { L as LoggerLike } from './timeout-BaP92Iyg.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-BaP92Iyg.js';
+import * as bson from 'bson';
 
 /**
  * Types + constants for the HotCache layer. All type-only (plus the stream-key
@@ -296,12 +297,11 @@ declare class InFlight {
 interface QueryCacheOptions {
     /** Max cached entries (default 500). */
     maxSize?: number;
-    /** Per-entry TTL in ms (default 0 = no expiry). */
+    /** Per-entry TTL in ms (default 30_000; set 0 explicitly for no expiry). */
     ttlMs?: number;
     /**
      * Clone results on every read so callers can't mutate the shared cache entry
-     * (default false — cloning has a per-read cost; treat cached results as
-     * read-only when disabled).
+     * (default true; set false only for read-only results where zero-copy matters).
      */
     clone?: boolean;
 }
@@ -325,15 +325,15 @@ interface QueryCacheStats {
     evictions: number;
 }
 /**
- * Compose the "collection" part of a cache key, namespaced by the DATABASE name.
- * One service shares a single QueryCache + InFlight across every DB client; without
- * the namespace, same-named physical collections in different databases would
- * collide — a read on DB A could be served DB B's cached rows, and identical
+ * Compose the collection part of a cache key, namespaced by deployment and DB.
+ * One service shares a QueryCache + InFlight across every client; without these
+ * namespaces, same-named physical collections in different databases/clusters
+ * would collide — a read on DB A could be served DB B's cached rows, and identical
  * concurrent reads across DBs could coalesce into one driver call. Reads,
  * write-through invalidations, and change-stream invalidations MUST all use the
  * same namespace so they agree.
  */
-declare const cacheCollectionKey: (dbName: string, physical: string) => string;
+declare const cacheCollectionKey: (dbName: string, physical: string, clusterNamespace?: string) => string;
 /**
  * Read-through query cache with per-collection invalidation.
  *
@@ -344,8 +344,8 @@ declare const cacheCollectionKey: (dbName: string, physical: string) => string;
  * collections changes. Invalidation is WRITE-THROUGH only: the ORM drops a
  * collection's entries on every write it performs. Reads are NOT invalidated by
  * external writers (other processes, the raw `client` escape hatch, or direct
- * DB writes) — with `ttlMs: 0` (default) those reads stay stale indefinitely,
- * so multi-writer deployments should set `ttlMs` or use the change-stream aware
+ * DB writes). The default 30-second TTL bounds staleness; `ttlMs: 0` explicitly
+ * disables expiry, so multi-writer deployments can also use the change-stream aware
  * `createHotCache()`. Perf wins: cache hits perform zero driver round-trips.
  */
 declare class QueryCache {
@@ -556,7 +556,9 @@ declare const isTransactionUnsupportedError: (error: unknown) => boolean;
 
 /** Minimal transaction runner surface (satisfied by the service `transaction`). */
 interface MongoTransactionRunner {
-    transaction: <T>(fn: (session: ClientSession | null) => Promise<T>) => Promise<T>;
+    transaction: <T>(fn: (session: ClientSession | null) => Promise<T>, options?: {
+        allowNonTransactionalFallback?: boolean;
+    }) => Promise<T>;
 }
 interface GracefulTransactionOptions {
     capabilities?: ReturnType<typeof createMongoCapabilitiesStore>;
@@ -564,17 +566,18 @@ interface GracefulTransactionOptions {
     logger?: LoggerLike;
     /** Map driver errors to typed DomainError/InfraError before rethrowing (default true). */
     wrapMongoErrors?: boolean;
+    /** Explicitly permit non-atomic execution on deployments without transactions. */
+    allowNonTransactionalFallback?: boolean;
 }
 /**
- * Run `fn` inside a transaction when the deployment supports it; otherwise run
- * with a `null` session (no-op fallback). Also handles "transactions
- * unsupported" errors by re-running with a null session.
+ * Run `fn` inside a transaction. Unsupported deployments throw unless
+ * `allowNonTransactionalFallback: true` explicitly permits 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).
+ * genuinely unsupported deployment only after explicit opt-in.
  */
 declare const withGracefulMongoTransaction: <T>(runner: MongoTransactionRunner, fn: (session: ClientSession | null) => Promise<T>, options?: GracefulTransactionOptions) => Promise<T>;
 
@@ -691,9 +694,8 @@ interface MongoMigrationRunnerOptions {
  *   - `./journal.ts` — lease-based `_migrations` journal (atomic, crash-safe)
  *
  * `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
+ * with an auto-renewed, owner-fenced lease; `down()` uses the same fencing,
+ * rolls back 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).
  */
@@ -857,7 +859,7 @@ interface DoubleField extends FieldMeta {
     exclusiveMinimum?: boolean;
     exclusiveMaximum?: boolean;
 }
-/** Strict BSON `long` (int64) field — inferred as `number` (precision caveat). */
+/** BSON `long` (int64) field — inferred as the driver's lossless `Long` type. */
 interface LongField extends FieldMeta {
     kind: 'long';
     minimum?: number;
@@ -1075,14 +1077,14 @@ interface QueryOptions {
      * 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.
+     * document is fetched from the DB (cache-miss); projections ignore absent
+     * required fields but still validate returned values.
      */
     drift?: DriftMode | boolean;
     /** Driver-level options forwarded untouched to the underlying call. */
     collation?: CollationOptions;
     readPreference?: ReadPreferenceLike;
-    readConcern?: ReadConcern;
+    readConcern?: ReadConcernLike;
     writeConcern?: WriteConcern;
     comment?: string | Document;
     let?: Document;
@@ -1252,7 +1254,7 @@ type InferField<T extends SchemaType> = T extends {
     kind: 'double';
 } ? number : T extends {
     kind: 'long';
-} ? number : T extends {
+} ? Long : T extends {
     kind: 'decimal';
 } ? Decimal128 : T extends {
     kind: 'geoPoint';
@@ -1284,13 +1286,8 @@ type InferDoc<T extends ObjectField> = InferObject<T>;
 
 /** A Mongo index definition usable by `createIndexes`. */
 interface IndexSpec {
-    key: Record<string, 1 | -1 | 'text' | 'hashed' | '2dsphere'>;
-    options?: {
-        name?: string;
-        unique?: boolean;
-        sparse?: boolean;
-        expireAfterSeconds?: number;
-    };
+    key: Record<string, IndexDirection>;
+    options?: CreateIndexesOptions;
 }
 /** Auto-timestamp field names maintained by the ORM when `timestamps` is set. */
 interface CollectionTimestamps {
@@ -1333,6 +1330,8 @@ interface DBClientDefinition<TCollections extends Record<string, CollectionLike>
     /** Per-logical-collection physical-name overrides. */
     collectionPhysicalNames?: Partial<Record<string, string>>;
     connectTimeoutMs?: number;
+    /** Enable driver command events before pools open (required for wire tracing). */
+    monitorCommands?: boolean;
     readPreference?: ReadPreferenceLike;
     readConcern?: ReadConcernLike;
     writeConcern?: WriteConcern;
@@ -1482,13 +1481,16 @@ declare const manyToMany: <const C extends string, const A extends string, const
 
 interface PopulateOptions {
     maxBatchSize?: number;
+    /** Cache keys only within this populate call (default true). */
     cache?: boolean;
-    /**
-     * Cap on docs fetched per foreign-key batch (default 10_000). A `hasMany` /
-     * `manyToMany` relation with more children than this is silently truncated —
-     * raise the cap when you expect larger joins.
-     */
+    /** Opt into the shared read-through query cache (default false for fresh joins). */
+    queryCache?: boolean;
+    /** Safety cap per foreign-key batch. Exceeding it throws instead of truncating. */
     maxDocs?: number;
+    session?: ClientSession;
+    maxTimeMS?: number;
+    readPreference?: ReadPreferenceLike;
+    readConcern?: ReadConcernLike;
 }
 
 /** Structured metadata attached to every logged DB operation. */
@@ -1505,12 +1507,14 @@ interface DbOpMeta {
      */
     params?: unknown;
 }
-
 /**
- * Aggregation types + the shared context handed to the aggregation op-group
- * factories (`./aggregate.ts`, `./group.ts`, `./text-search.ts`,
- * `./lookup-join.ts`). Type-only plus the `AggregationCtx` interface.
+ * The ignex-debugbar `debugQuery` free helper (`@ignex/core/debug`), resolved
+ * lazily so the ORM stays standalone: `undefined` until probed, `null` when
+ * `@ignex/core` is not installed (plain ORM usage), the function otherwise.
+ * `debugQuery` itself is a zero-cost pass-through when no request trace is
+ * active, so production ignex apps pay nothing either.
  */
+type DebugQuery = <T>(sql: string, params: unknown, fn: () => T | Promise<T>) => T | Promise<T>;
 
 interface GroupByConfig {
     /** Group key: a field name or a document of `$`-expressions. */
@@ -1554,7 +1558,9 @@ interface PipelineCustomization {
 }
 interface AggregationOpsOptions {
     resolveCollectionName: (logical: string) => string;
+    cacheNamespace?: string;
     wrapMongoErrors?: boolean;
+    debugQuery?: DebugQuery | null;
     /** Shared read cache (`undefined` = caching disabled). */
     cache?: QueryCache;
     /** Service default for in-flight read dedup. */
@@ -2010,17 +2016,6 @@ type UpdateOperators<T> = {
  */
 type UpdateInput<T> = Partial<T> | UpdateOperators<T>;
 
-/**
- * Shared CRUD context: the cross-cutting helpers every CRUD op group depends
- * on (collection resolution, tracing, retry plumbing, cache/dedup/drift read
- * pipeline, auto-timestamps, `select` normalization).
- *
- * `makeCrudOps` (see `./index.ts`) builds ONE context via `createCrudContext`
- * and hands it to the read / write / watch op-group factories, so the helpers
- * live in exactly one place instead of being duplicated per op. This module is
- * the dependency-injection seam of the CRUD layer.
- */
-
 type ColNames<TClients extends DbClientsDefinition, TDb extends ExtractDbNames<TClients>> = ExtractCollectionNames<TClients, TDb>;
 /** Input accepted by insert ops: the doc without `_id`, or with an explicit `_id`. */
 type InsertInput<T> = Omit<T, '_id'> & {
@@ -2048,13 +2043,17 @@ type FindQueryOptions<T> = FindOptions & QueryOptions & {
 type TimestampsByCollection = Record<string, CollectionTimestamps | undefined>;
 interface CrudOpsOptions {
     resolveCollectionName: (logical: string) => string;
+    /** Stable, non-secret identity of the MongoDB deployment for shared caches. */
+    cacheNamespace?: string;
     wrapMongoErrors?: boolean;
+    debugQuery?: DebugQuery | null;
     cache?: QueryCache;
     dedupeReads?: boolean;
     inFlight?: InFlight;
     hooks?: HooksRegistry;
     /** Auto-timestamp field names per collection (from the collection definition). */
     timestamps?: TimestampsByCollection;
+    validateWrites?: boolean;
     /** Service-level schema-drift policy for reads (default `'report'`). */
     drift?: DriftMode;
     /** Resolve the declared schema for a logical collection (drift detection). */
@@ -2068,7 +2067,7 @@ interface CrudOpsOptions {
  * and fire lifecycle hooks.
  */
 declare const makeCrudOps: <TClients extends DbClientsDefinition, TDb extends ExtractDbNames<TClients>>(client: Db, dbLabel: string, logger: LoggerLike, opts: CrudOpsOptions) => {
-    watchCollection: <X extends ColNames<TClients, TDb>>(collection: X, pipeline?: mongodb.Document[], options?: mongodb.ChangeStreamOptions) => mongodb.ChangeStream<CollectionDoc<TClients[TDb]["collections"][X]>, mongodb.ChangeStreamDocument<CollectionDoc<TClients[TDb]["collections"][X]>>>;
+    watchCollection: <X extends ColNames<TClients, TDb>>(collection: X, pipeline?: bson.Document[], options?: mongodb.ChangeStreamOptions) => mongodb.ChangeStream<CollectionDoc<TClients[TDb]["collections"][X]>, mongodb.ChangeStreamDocument<CollectionDoc<TClients[TDb]["collections"][X]>>>;
     query: <X extends ColNames<TClients, TDb>>(collection: X) => QueryBuilder<CollectionDoc<TClients[TDb]["collections"][X]>, CollectionDoc<TClients[TDb]["collections"][X]>>;
     insertOne: <X extends ColNames<TClients, TDb>>(collection: X, doc: InsertInput<CollectionDoc<TClients[TDb]["collections"][X]>>, options?: mongodb.InsertOneOptions & QueryOptions) => Promise<mongodb.InsertOneResult<CollectionDoc<TClients[TDb]["collections"][X]>>>;
     insertMany: <X extends ColNames<TClients, TDb>>(collection: X, docs: readonly InsertInput<CollectionDoc<TClients[TDb]["collections"][X]>>[], options?: mongodb.BulkWriteOptions & QueryOptions) => Promise<mongodb.InsertManyResult<CollectionDoc<TClients[TDb]["collections"][X]>>>;
@@ -2084,8 +2083,8 @@ declare const makeCrudOps: <TClients extends DbClientsDefinition, TDb extends Ex
         filter: FilterInput<CollectionDoc<TClients[TDb]["collections"][X]>>;
         update: UpdateInput<CollectionDoc<TClients[TDb]["collections"][X]>>;
         upsert?: boolean;
-    }[], options?: mongodb.BulkWriteOptions & QueryOptions) => Promise<mongodb.Document>;
-    bulkWrite: <X extends ColNames<TClients, TDb>>(collection: X, operations: mongodb.AnyBulkWriteOperation<CollectionDoc<TClients[TDb]["collections"][X]>>[], options?: mongodb.BulkWriteOptions & QueryOptions) => Promise<mongodb.Document>;
+    }[], options?: mongodb.BulkWriteOptions & QueryOptions) => Promise<bson.Document>;
+    bulkWrite: <X extends ColNames<TClients, TDb>>(collection: X, operations: mongodb.AnyBulkWriteOperation<CollectionDoc<TClients[TDb]["collections"][X]>>[], options?: mongodb.BulkWriteOptions & QueryOptions) => Promise<bson.Document>;
     updateWithVersion: <X extends ColNames<TClients, TDb>>(collection: X, filter: FilterInput<CollectionDoc<TClients[TDb]["collections"][X]>>, update: UpdateInput<CollectionDoc<TClients[TDb]["collections"][X]>>, options?: mongodb.FindOneAndUpdateOptions & QueryOptions) => Promise<VersionedUpdateResult<CollectionDoc<TClients[TDb]["collections"][X]>>>;
     findOneAndDelete: <X extends ColNames<TClients, TDb>>(collection: X, filter: FilterInput<CollectionDoc<TClients[TDb]["collections"][X]>>, options?: mongodb.FindOneAndDeleteOptions & QueryOptions) => Promise<CollectionDoc<TClients[TDb]["collections"][X]> | null>;
     replaceOne: <X extends ColNames<TClients, TDb>>(collection: X, filter: FilterInput<CollectionDoc<TClients[TDb]["collections"][X]>>, replacement: InsertInput<CollectionDoc<TClients[TDb]["collections"][X]>>, options?: mongodb.ReplaceOptions & QueryOptions) => Promise<mongodb.UpdateResult<CollectionDoc<TClients[TDb]["collections"][X]>>>;
@@ -2113,6 +2112,8 @@ interface MongoServiceConfig {
     migrationDir?: string;
     appName?: string;
     logger?: LoggerLike;
+    /** Explicit host tracer (Ignex debugQuery); null disables the optional probe. */
+    debugQuery?: DebugQuery | null;
     /**
      * Map driver errors to typed DomainError/InfraError before rethrowing. ON by
      * default — set `false` to surface raw driver errors instead.
@@ -2126,9 +2127,9 @@ interface MongoServiceConfig {
      * INVALIDATION: entries are dropped write-through — every ORM write
      * invalidates that collection's cached reads. External writers (other
      * processes, the raw `client` escape hatch, direct DB writes) do NOT
-     * invalidate; with the default `ttlMs: 0` those reads stay stale
-     * indefinitely, so multi-writer deployments should set `QueryCacheOptions.ttlMs`,
-     * disable the cache, route latency-critical reads through the
+     * invalidate. The default 30-second TTL bounds staleness; `ttlMs: 0`
+     * explicitly selects unbounded entries. Multi-writer deployments can disable
+     * the cache, route latency-critical reads through the
      * change-stream aware `createHotCache()`, or set `cacheWatch: true`.
      */
     cache?: QueryCache | QueryCacheOptions | null;
@@ -2143,6 +2144,8 @@ interface MongoServiceConfig {
      * `closeConnections()`. Default: false.
      */
     cacheWatch?: boolean;
+    /** Permit transaction callbacks to run non-atomically on unsupported servers. Default: false. */
+    allowNonTransactionalFallback?: boolean;
     /** Coalesce identical concurrent reads into one driver call. ON by default. */
     dedupeReads?: boolean;
     /**
@@ -2150,6 +2153,8 @@ interface MongoServiceConfig {
      * in-flight dedup even when the granular options are set. Defaults to true.
      */
     perf?: boolean;
+    /** Validate inserts and replacements against the schema before sending them. Default: true. */
+    validateWrites?: boolean;
     /**
      * Schema-drift policy for reads. When a document fetched from the DB
      * (cache-miss) doesn't match its declared schema:
@@ -2157,8 +2162,8 @@ interface MongoServiceConfig {
      *   - `'throw'` — throw `DomainError SCHEMA_DRIFT` (the document is never
      *     cached or returned)
      *   - `'off'` — no drift checking (previous behavior)
-     * Detection-only: documents are never mutated. Projected/partial reads are
-     * skipped. Overridable per op via `QueryOptions.drift`.
+     * Detection-only: documents are never mutated. Projected reads ignore absent
+     * fields but validate returned values. Overridable via `QueryOptions.drift`.
      */
     drift?: DriftMode;
 }
@@ -2251,6 +2256,8 @@ interface CacheInvalidationRef {
     db: Db;
     /** PHYSICAL collection name — cache keys use it, so invalidation must too. */
     collection: string;
+    /** Stable deployment identity shared with the manager's cache keys. */
+    namespace?: string;
 }
 declare class CacheInvalidator {
     private cache;
@@ -2276,25 +2283,19 @@ declare class CacheInvalidator {
     private watchLoop;
 }
 
-/**
- * Pagination types + the shared context handed to the two pagination
- * strategies (`./offset.ts`, `./cursor.ts`). Type-only plus the `PaginationCtx`
- * interface, so the strategy modules and the composing `makePaginationOps`
- * (in `./index.ts`) share one vocabulary without importing each other's logic.
- */
-
 interface PaginationConfig {
     page?: number;
     limit?: number;
     sort?: Record<string, 1 | -1>;
     /** Cap on the requested limit (default DEFAULT_MAX_LIMIT=1000). */
     maxLimit?: number;
+    /** Maximum offset before callers must switch to keyset pagination (default 10_000). */
+    maxOffset?: 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).
+     * Enables lean list reads — only the projected fields cross the wire. Drift
+     * checks ignore absent fields but still validate the returned values.
      */
     projection?: Document;
     /** Stages prepended to the data facet (e.g. extra $match). */
@@ -2311,6 +2312,8 @@ interface CursorPaginationConfig {
      * exist on every document for deterministic ordering.
      */
     sort: Record<string, 1 | -1>;
+    /** Unique final sort field. Defaults to `_id`; custom fields must have a unique index. */
+    uniqueTiebreaker?: string;
     /** Opaque cursor from a previous `nextCursor` — fetch the page after it. */
     after?: string;
     /** Opaque cursor — fetch the page before it (backward navigation). */
@@ -2328,7 +2331,9 @@ interface CursorPage<T> {
 }
 interface PaginationOpsOptions {
     resolveCollectionName: (logical: string) => string;
+    cacheNamespace?: string;
     wrapMongoErrors?: boolean;
+    debugQuery?: DebugQuery | null;
     /** Service-level schema-drift policy for reads (default `'report'`). */
     drift?: DriftMode;
     /** Resolve the declared schema for a logical collection (drift detection). */
@@ -2477,29 +2482,23 @@ declare const makeSchemaOps: (client: Db, _logger: LoggerLike, opts: SchemaOpsOp
     syncIndexes: (collection: string) => Promise<SyncIndexesResult>;
 };
 
+interface TransactionOptions extends TransactionOptions$1 {
+    /** Explicitly permit non-atomic execution when transactions are unsupported. */
+    allowNonTransactionalFallback?: boolean;
+}
 interface TransactionOpsOptions {
     migrationCollectionPhysical: string;
-    /** Map driver errors to typed DomainError/InfraError before rethrowing. */
     wrapMongoErrors?: boolean;
+    allowNonTransactionalFallback?: boolean;
 }
-/**
- * Transaction + idempotent-migration ops for one database handle.
- */
+/** Transaction + fenced idempotent-migration ops for one database handle. */
 declare const makeTransactionOps: (client: MongoClient, handle: Db, logger: LoggerLike, _config: Record<string, unknown>, opts: TransactionOpsOptions) => {
     transaction: <T>(fn: (session: ClientSession | null) => Promise<T>, options?: TransactionOptions) => Promise<T>;
-    migrate: (name: string, fn: (session: ClientSession | null) => Promise<void>, filePath?: string) => Promise<void>;
+    migrate: (name: string, fn: (session: ClientSession | null) => Promise<void>, filePath?: string, options?: {
+        allowNonTransactionalFallback?: boolean;
+    }) => Promise<void>;
 };
 
-/**
- * Per-database manager assembly. `buildManager` is the composition point of the
- * op-factory pattern: it builds the collection registry (schema/hooks/
- * timestamps), resolves logical→physical names, and **spreads** every
- * `make*Ops` factory into one `CollectionManager` object per database.
- *
- * The `CollectionManager` type mirrors that spread as an intersection so both
- * the runtime value and its type stay in sync from a single source.
- */
-
 /** One collection manager per connected DB — the ORM's primary surface. */
 type CollectionManager<TClients extends DbClientsDefinition, TDb extends ExtractDbNames<TClients>> = CrudOps<TClients, TDb> & ReturnType<typeof makePaginationOps<TClients, TDb>> & ReturnType<typeof makeAggregationOps<TClients, TDb>> & ReturnType<typeof makeSchemaOps> & ReturnType<typeof makeTransactionOps> & {
     /**
@@ -2512,6 +2511,8 @@ type CollectionManager<TClients extends DbClientsDefinition, TDb extends Extract
     }, options?: PopulateOptions) => Promise<Array<T & JoinedFields<TClients, TDb, R>>>;
     /** Raw `db()` handle escape hatch. */
     client: Db;
+    /** Raw pooled client for host integrations (e.g. command monitoring). */
+    mongoClient: MongoClient;
     /** Reference to sibling managers (cross-DB). */
     db: Record<string, unknown>;
 };
@@ -2798,4 +2799,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, isTransactionUnsupportedError, 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 DebugQuery, 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 TransactionOptions, 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 };