@ignex/ninox 0.1.6 → 0.2.0

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-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';
 
 /**
@@ -297,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;
 }
@@ -326,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.
  *
@@ -345,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 {
@@ -411,14 +410,6 @@ declare const createMongoCapabilitiesStore: () => MongoCapabilitiesStore;
 /** Probe a connected client/db via `hello`. */
 declare const probeMongoCapabilities: (client: MongoClient | Db | null | undefined) => Promise<MongoCapabilities>;
 
-/**
- * The ORM's error classes (`AppError` → `DomainError` / `InfraError` /
- * `BadRequest`), their type guards, and the `ERROR_HTTP_STATUS` table that sets
- * each error's `statusCode` at construction.
- *
- * A leaf module: nothing else in `src/errors/` imports this (so `driver-map.ts`
- * and `http-status.ts` can depend on it without cycles).
- */
 interface ErrorContext {
     db?: string;
     collection?: string;
@@ -437,23 +428,47 @@ declare class AppError extends Error {
     readonly code: string;
     readonly statusCode: number;
     readonly extra?: Record<string, unknown>;
-    constructor(code: string, message: string, statusCode?: number, extra?: Record<string, unknown>);
     /**
-     * Stable, client-safe serialization for framework error middleware: a
-     * framework can forward `JSON.stringify(error)` (or `error.toJSON()`) straight
-     * to the client — no parsing of server internals. `stack` is dropped; the
-     * shape is always `{ name, code, message, statusCode, ...(extra) }`.
+     * Whether `message`/`extra` may be sent to a CLIENT.
+     *
+     * Fail-closed: a 4xx message is the caller's contract, a 5xx message is an
+     * operator detail that may quote a driver, a host or a query. Pass `expose`
+     * explicitly to override — only for a 5xx whose text was written for callers
+     * (e.g. `new InfraError("DRAINING", "queue is draining", extra, true)`).
+     */
+    readonly expose: boolean;
+    constructor(code: string, message: string, statusCode?: number, extra?: Record<string, unknown>, expose?: boolean);
+    /**
+     * Full, stack-free shape for LOGS and typed consumers:
+     * `{ name, code, message, statusCode, ...(extra) }`.
+     *
+     * It carries the real message, so it is NOT the client path — use
+     * {@link toClientPayload} (or `serializeError`) for anything a caller sees, and
+     * prefer `logger.error({ err })` so pino's own serializer keeps the stack in the
+     * log rather than in a payload.
      */
     toJSON(): Record<string, unknown>;
+    /**
+     * The client-safe payload — the same shape as {@link toJSON}, except that a
+     * non-exposed error's `message` is replaced by the canonical reason phrase and
+     * its `extra` is dropped. A framework can forward this (or `serializeError`'s
+     * result) without auditing what the message might contain.
+     *
+     * @param options - `expose: true` forces the real (masked) message + extra.
+     * @returns The client payload.
+     */
+    toClientPayload(options?: {
+        expose?: boolean;
+    }): Record<string, unknown>;
 }
 declare class DomainError extends AppError {
-    constructor(code: string, message: string, extra?: Record<string, unknown>);
+    constructor(code: string, message: string, extra?: Record<string, unknown>, expose?: boolean);
 }
 declare class InfraError extends AppError {
-    constructor(code: string, message: string, extra?: Record<string, unknown>);
+    constructor(code: string, message: string, extra?: Record<string, unknown>, expose?: boolean);
 }
 declare class BadRequest extends DomainError {
-    constructor(message: string, extra?: Record<string, unknown>);
+    constructor(message: string, extra?: Record<string, unknown>, expose?: boolean);
 }
 declare const isAppError: (err: unknown) => err is AppError;
 declare const isDomainError: (err: unknown) => err is DomainError;
@@ -483,8 +498,16 @@ declare const isMappedMongoError: (error: unknown) => error is AppError;
 
 /** Effective HTTP status for any thrown value: AppError-aware, raw → 500 (503 transient). */
 declare const httpStatusForError: (err: unknown) => number;
+/** Options for {@link serializeError}. */
+interface SerializeErrorOptions {
+    /**
+     * Include the real message (and `extra`) even for a non-exposed error — the
+     * development / trusted-caller path. It is still credential-masked.
+     */
+    expose?: boolean;
+}
 /**
- * Reduce any thrown value to a stable, client-safe error payload:
+ * Reduce any thrown value to a stable, CLIENT-SAFE error payload:
  * `{ name, code, message, statusCode, ...(extra) }`.
  *
  * Raw driver errors are mapped through `mapMongoDriverError` first, so a
@@ -495,8 +518,15 @@ declare const httpStatusForError: (err: unknown) => number;
  *     const payload = serializeError(err, { db, collection, op });
  *     res.status(payload.statusCode).json(payload);
  *   });
+ *
+ * Fail-closed by default: a 4xx message/extra is the caller's contract, while a
+ * 5xx message is replaced by the canonical reason phrase (`Internal Server
+ * Error`, `Service Unavailable`, …) and `extra` is dropped — a driver message
+ * that quotes a host, a query or a stored value never reaches a client. The
+ * detail stays on the error itself for logs; pass `{ expose: true }` (or a
+ * per-error `expose`) to opt out for a trusted caller.
  */
-declare const serializeError: (err: unknown, ctx?: ErrorContext) => Record<string, unknown>;
+declare const serializeError: (err: unknown, ctx?: ErrorContext, options?: SerializeErrorOptions) => Record<string, unknown>;
 
 /**
  * Transient-error detection: which MongoDB errors are safe to retry. This is a
@@ -526,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>;
@@ -534,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>;
 
@@ -661,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).
  */
@@ -827,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;
@@ -1045,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;
@@ -1222,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';
@@ -1254,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 {
@@ -1303,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;
@@ -1452,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. */
@@ -1475,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. */
@@ -1524,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. */
@@ -1980,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'> & {
@@ -2018,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). */
@@ -2083,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.
@@ -2096,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;
@@ -2113,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;
     /**
@@ -2120,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:
@@ -2127,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;
 }
@@ -2221,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;
@@ -2246,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). */
@@ -2281,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). */
@@ -2298,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). */
@@ -2447,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> & {
     /**
@@ -2482,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>;
 };
@@ -2768,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 };