@ignex/ninox 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,2570 @@
+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-BgrqtMnd.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-BgrqtMnd.js';
+import * as bson from 'bson';
+
+/**
+ * Types + constants for the HotCache layer. All type-only (plus the stream-key
+ * separator constant), so the coordinating class (`HotCache` in `./index.ts`)
+ * and its strategy modules (`./ticker.ts`, `./watcher.ts`) share one vocabulary
+ * without importing each other's runtime logic.
+ */
+
+/** A collection to watch for invalidation. `collection` is the PHYSICAL name. */
+interface HotCollectionRef {
+    /** Raw `Db` handle (e.g. `service.db.primaryClient.client`). */
+    db: Db;
+    /** Physical collection name whose writes invalidate bound queries. */
+    collection: string;
+}
+/** Opt-in query registration. `TArgs` = the parameter tuple, `TResult` = loader result. */
+interface HotQueryConfig<TArgs extends readonly unknown[], TResult> {
+    /** Read-through loader executed on cache miss / background refresh. */
+    loader: (...args: TArgs) => Promise<TResult>;
+    /**
+     * Optional cache-key extractor. Lets callers decide which parameters form the
+     * key (e.g. hash only some of them). Default: `stableHash` of all arguments.
+     */
+    keyOf?: (...args: TArgs) => string;
+    /** Per-query TTL in ms (`0` = no expiry). Defaults to `defaultTtlMs`. */
+    ttlMs?: number;
+    /** Per-query LRU cap. Defaults to `defaultMaxSize`. */
+    maxSize?: number;
+    /**
+     * Background refresh interval in ms (standalone ticker only). Default `0` =
+     * no background refresh — entries then update only via `ttlMs` expiry or
+     * manual `invalidate*` calls. In standalone mode with `autoRefresh` on, a
+     * query with neither `refreshIntervalMs` nor `ttlMs` set serves values until
+     * it is manually invalidated (unbounded staleness); `start()` logs a warning
+     * naming those queries so you can opt in deliberately.
+     */
+    refreshIntervalMs?: number;
+    /**
+     * Collections whose data changes invalidate this query. Used by replica mode
+     * to open change-stream watchers. In standalone mode these have no effect
+     * (the ticker refreshes instead) — use `invalidateCollection` manually if
+     * needed.
+     */
+    watch?: HotCollectionRef[];
+    /**
+     * Clone results on every read so callers can't mutate the shared cached entry
+     * (default false — cloning has a per-read cost; treat cached results as
+     * read-only when disabled).
+     */
+    clone?: boolean;
+    /**
+     * Upper bound (bytes) for a cached value, estimated via a cheap BSON-aware
+     * size probe. Larger values are still returned to the caller but are NOT
+     * cached (a first oversized result logs a warning). Protects the LRU from
+     * holding unbounded single entries. Default: no limit.
+     */
+    maxValueBytes?: number;
+}
+interface HotCacheOptions {
+    /**
+     * Replica-support probe. Default: `probeMongoCapabilities` over the first
+     * watched collection's `db`. Return `true` → change-stream mode,
+     * `false` → standalone ticker mode. A probe that returns no result (timeout)
+     * falls back to standalone with a warning — pass `mode` to pin the behavior.
+     */
+    probe?: () => Promise<boolean>;
+    /**
+     * Pin the cache mode directly, skipping the probe entirely. `'replica'` opens
+     * change-stream watchers, `'standalone'` starts the ticker. Useful when the
+     * deployment is known (e.g. from connection config) and you want to avoid a
+     * `hello` round-trip or a mis-detection.
+     */
+    mode?: 'replica' | 'standalone';
+    /** Default per-query TTL in ms (`0` = no expiry). Default `0`. */
+    defaultTtlMs?: number;
+    /** Default per-query LRU cap. Default `500`. */
+    defaultMaxSize?: number;
+    /** Global ticker interval in ms (standalone mode). Default `1000`. */
+    tickIntervalMs?: number;
+    /**
+     * Master switch for the standalone background-refresh ticker. `true` (default)
+     * runs the global ticker that re-fetches entries at `refreshIntervalMs`. Set
+     * `false` to turn off auto-refetch entirely — data then updates only via
+     * manual `invalidate`/`invalidateParams`/`invalidateCollection` or `ttlMs`
+     * expiry. Replica-mode change streams are event-driven and unaffected.
+     */
+    autoRefresh?: boolean;
+    logger?: LoggerLike;
+}
+type HotCacheMode = 'unknown' | 'replica' | 'standalone';
+/** Typed handle returned by `register` — type-safe alternative to dynamic `get`. */
+interface HotQueryAccessor<TArgs extends readonly unknown[], TResult> {
+    /** Read-through: serve from LRU, else run the loader. */
+    get: (...args: TArgs) => Promise<TResult>;
+    /**
+     * Manual invalidation (fully typed, with intellisense on the parameters).
+     * Called with no arguments it drops every cached entry for this query; called
+     * with the query's parameters it drops only that parameter's entry.
+     *
+     *   topProducts.invalidate();      // drop all
+     *   topProducts.invalidate(10);    // drop only the { limit: 10 } entry
+     */
+    invalidate: {
+        (): void;
+        (...args: TArgs): void;
+    };
+}
+/** Per-query runtime counters (see `HotCache.stats()`). */
+interface HotQueryStats {
+    /** Current number of cached entries for this query. */
+    size: number;
+    /** Reads served from the LRU without running the loader. */
+    hits: number;
+    /** Reads that ran the loader (LRU miss or expired entry). */
+    misses: number;
+    /** Background refreshes kicked by the standalone ticker. */
+    refreshes: number;
+    /** Loader rejections (failed reads/refreshes). */
+    loadErrors: number;
+    /** Values too large to cache (`maxValueBytes`). */
+    sizeSkips: number;
+    /** Capacity evictions (LRU). */
+    evictions: number;
+}
+/** Snapshot of the whole cache (see `HotCache.stats()`). */
+interface HotCacheStats {
+    mode: HotCacheMode;
+    /** Number of registered queries. */
+    queries: number;
+    /** Total cached entries across all queries. */
+    entries: number;
+    perQuery: Record<string, HotQueryStats>;
+}
+
+declare class HotCache {
+    private options;
+    private logger;
+    private refreshEnabled;
+    private queries;
+    private inflight;
+    private watcher;
+    private ticker;
+    private _mode;
+    private started;
+    private startAttempted;
+    private stopped;
+    private disposed;
+    private startPromise?;
+    constructor(options?: HotCacheOptions);
+    /** Number of cached entries across all registered queries. */
+    get size(): number;
+    /** Resolved mode: `unknown` until `start()` (or the first `get`) probes. */
+    get mode(): HotCacheMode;
+    /** Whether the standalone background-refresh ticker is enabled (`autoRefresh`). */
+    get autoRefresh(): boolean;
+    /** Whether a query with this name has been registered. */
+    has(name: string): boolean;
+    /**
+     * Opt a query into the hot cache. Throws `BadRequest` on a duplicate name.
+     * Returns a fully typed accessor — `.get(...args)` (intellisense on the loader
+     * parameters) and `.invalidate()` / `.invalidate(...args)` for manual
+     * invalidation (all entries or a single parameter set).
+     */
+    register<TArgs extends readonly unknown[], TResult>(name: string, config: HotQueryConfig<TArgs, TResult>): HotQueryAccessor<TArgs, TResult>;
+    /**
+     * Read-through read by dynamic name lookup. Call parameters are hashed into
+     * the cache key (`keyOf` override wins). Throws `BadRequest` for an unknown
+     * query name. For fully typed parameters/results prefer the accessor returned
+     * by `register()` — this dynamic form returns `Promise<unknown>`.
+     */
+    get(name: string, ...args: unknown[]): Promise<unknown>;
+    /** Drop every cached entry for a registered query. */
+    invalidate(name: string): void;
+    /**
+     * Drop only the cached entry for a specific parameter set. The key is computed
+     * exactly like `get` (`keyOf` override ?? `stableHash` of args), so the same
+     * parameters invalidate the same entry.
+     */
+    invalidateParams(name: string, ...args: unknown[]): void;
+    /**
+     * Invalidate every query bound to a physical collection (via `watch`). Can be
+     * called manually to wire ORM write hooks in standalone mode.
+     */
+    invalidateCollection(collection: string): 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.
+     */
+    stats(): HotCacheStats;
+    /**
+     * Probe replica support once, then start change-stream watchers (replica) or
+     * the global refresh ticker (standalone). Idempotent — resolves the mode.
+     */
+    start(): Promise<HotCacheMode>;
+    /**
+     * Stop the ticker, close every change stream, and **dispose** the instance.
+     * Terminal: a later `get()` serves cached values read-through but never
+     * re-probes or re-opens background resources.
+     */
+    stop(): Promise<void>;
+    private runStart;
+    private ensureStarted;
+    private defaultProbe;
+    private fetch;
+    private setEntry;
+}
+/** Create a new global hot-cache instance. */
+declare const createHotCache: (options?: HotCacheOptions) => HotCache;
+
+/**
+ * In-flight request coalescing: identical concurrent operations share a single
+ * Promise so the underlying (expensive) work runs once. This is the "query
+ * dedup" optimization used by the CRUD read path.
+ */
+declare class InFlight {
+    private pending;
+    get size(): number;
+    run<T>(key: string, fn: () => Promise<T>): Promise<T>;
+    clear(): void;
+}
+
+interface QueryCacheOptions {
+    /** Max cached entries (default 500). */
+    maxSize?: number;
+    /** Per-entry TTL in ms (default 0 = 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).
+     */
+    clone?: boolean;
+}
+/** Snapshot of cache health (see `QueryCache.stats()`). */
+interface QueryCacheStats {
+    size: number;
+    maxSize: number;
+    /** Reads served from the cache without touching the DB. */
+    hits: number;
+    /** Reads that missed (absent or expired). */
+    misses: number;
+    /** `set()` calls (writes to the cache). */
+    sets: number;
+    /** `delete()` calls. */
+    deletes: number;
+    /** `invalidateByCollection` calls that actually dropped entries. */
+    invalidateEvents: number;
+    /** `clear()` calls. */
+    clearEvents: number;
+    /** Capacity evictions (LRU). */
+    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
+ * 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;
+/**
+ * Read-through query cache with per-collection invalidation.
+ *
+ * Keys are `collection<sep>hash` so a single write can invalidate every cached
+ * read for that collection. 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
+ * `createHotCache()`. Perf wins: cache hits perform zero driver round-trips.
+ */
+declare class QueryCache {
+    private lru;
+    private index;
+    private ttlMs;
+    private clone;
+    private hits;
+    private misses;
+    private sets;
+    private deletes;
+    private invalidateEvents;
+    private clearEvents;
+    constructor(options?: QueryCacheOptions);
+    get size(): number;
+    /** Cache-health snapshot: sizes plus lifetime hit/miss/eviction counters. */
+    stats(): QueryCacheStats;
+    /** Compose a cache key for a collection + filter/options hash. */
+    key(collection: string, filterHash: string): string;
+    get(key: string): unknown | undefined;
+    set(key: string, value: unknown, ttlMs?: number): void;
+    delete(key: string): void;
+    /** Drop every cached entry belonging to a physical collection. */
+    invalidateByCollection(collection: string): void;
+    clear(): void;
+}
+
+/**
+ * Transaction capability detection. MongoDB transactions require a replica set
+ * (or mongos). The ORM probes once and caches the result so the transaction
+ * wrapper can fall back to plain (non-transactional) execution on standalone
+ * servers.
+ */
+interface MongoCapabilities {
+    probed: boolean;
+    transactionsSupported: boolean;
+}
+interface MongoCapabilitiesStore {
+    get(): MongoCapabilities;
+    set(capabilities: MongoCapabilities): void;
+    reset(): void;
+}
+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;
+    op?: string;
+}
+/**
+ * Canonical HTTP status for each error code. `AppError.statusCode` is set from
+ * this table at construction (falling back to the class default: 400 for
+ * `DomainError`, 500 for `InfraError`), so a framework can respond with
+ * `err.statusCode` directly and still get correct REST semantics:
+ *   NOT_FOUND → 404, DUPLICATE_KEY/VERSION_CONFLICT/COLLECTION_EXISTS → 409,
+ *   VALIDATION_FAILED → 422, MONGO_TIMEOUT → 504.
+ */
+declare const ERROR_HTTP_STATUS: Record<string, number>;
+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) }`.
+     */
+    toJSON(): Record<string, unknown>;
+}
+declare class DomainError extends AppError {
+    constructor(code: string, message: string, extra?: Record<string, unknown>);
+}
+declare class InfraError extends AppError {
+    constructor(code: string, message: string, extra?: Record<string, unknown>);
+}
+declare class BadRequest extends DomainError {
+    constructor(message: string, extra?: Record<string, unknown>);
+}
+declare const isAppError: (err: unknown) => err is AppError;
+declare const isDomainError: (err: unknown) => err is DomainError;
+declare const isInfraError: (err: unknown) => err is InfraError;
+
+/**
+ * Raw driver-error mapping: turn Mongo driver errors (codes 11000, 112, 50,
+ * 121, bulk-write, transient) into the ORM's typed `DomainError` / `InfraError`,
+ * plus `extractValidationPaths` for surfacing which `$jsonSchema` fields failed.
+ */
+
+/**
+ * Map a raw driver error to a typed DomainError/InfraError. Mirrors the sdk-db
+ * mapping table (codes 11000 → DUPLICATE_KEY, 112 → VERSION_CONFLICT,
+ * 50 → MONGO_TIMEOUT, 121 → VALIDATION_FAILED, everything else → MONGO_QUERY_ERROR).
+ * When the error is already an AppError it is returned unchanged.
+ */
+declare const mapMongoDriverError: (error: unknown, ctx?: ErrorContext) => unknown;
+/** True when the error is already a mapped AppError (used by callers that opted into wrapping). */
+declare const isMappedMongoError: (error: unknown) => error is AppError;
+
+/**
+ * Framework-facing error helpers: `httpStatusForError` (effective HTTP status
+ * for any thrown value) and `serializeError` (reduce any thrown value to a
+ * stable, client-safe payload).
+ */
+
+/** Effective HTTP status for any thrown value: AppError-aware, raw → 500 (503 transient). */
+declare const httpStatusForError: (err: unknown) => number;
+/**
+ * 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
+ * framework can forward the result directly without parsing Mongo server
+ * internals (`errInfo`, `writeErrors`, `keyPattern`, ...):
+ *
+ *   app.use((err, _req, res, _next) => {
+ *     const payload = serializeError(err, { db, collection, op });
+ *     res.status(payload.statusCode).json(payload);
+ *   });
+ */
+declare const serializeError: (err: unknown, ctx?: ErrorContext) => Record<string, unknown>;
+
+/**
+ * Transient-error detection: which MongoDB errors are safe to retry. This is a
+ * leaf module (no folder imports) so both `driver-map.ts` and `http-status.ts`
+ * can depend on it without cycles.
+ */
+/**
+ * Server error codes MongoDB raises that are safe to retry (network hiccups,
+ * not-primary, sharding moves, interrupted queries). Mirrors the reference set.
+ *
+ * Frozen + typed `ReadonlySet` so a consumer can't mutate the shared instance
+ * (it is a module-level singleton, re-exported through the barrel).
+ */
+declare const TRANSIENT_MONGO_ERROR_CODES: ReadonlySet<number>;
+/** True when the error is a transient Mongo failure that retry can recover from. */
+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;
+
+/** Minimal transaction runner surface (satisfied by the service `transaction`). */
+interface MongoTransactionRunner {
+    transaction: <T>(fn: (session: ClientSession | null) => Promise<T>) => Promise<T>;
+}
+interface GracefulTransactionOptions {
+    capabilities?: ReturnType<typeof createMongoCapabilitiesStore>;
+    urlHint?: string;
+    logger?: LoggerLike;
+    /** Map driver errors to typed DomainError/InfraError before rethrowing (default true). */
+    wrapMongoErrors?: boolean;
+}
+/**
+ * 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.
+ */
+declare const withGracefulMongoTransaction: <T>(runner: MongoTransactionRunner, fn: (session: ClientSession | null) => Promise<T>, options?: GracefulTransactionOptions) => Promise<T>;
+
+/**
+ * Lifecycle hooks — the ORM's middleware system. Hooks are declared per
+ * collection and run around the corresponding CRUD operation.
+ */
+type HookName = 'beforeCreate' | 'afterCreate' | 'beforeUpdate' | 'afterUpdate' | 'beforeDelete' | 'afterDelete' | 'afterRead';
+interface HookContext<TSchema = Document> {
+    collection: string;
+    doc?: TSchema;
+    docs?: TSchema[];
+    filter?: Filter<Document>;
+    options?: Record<string, unknown>;
+}
+type Hook<TSchema = Document> = (ctx: HookContext<TSchema>) => void | Promise<void>;
+type HookMap<TSchema = Document> = Partial<Record<HookName, Hook<TSchema>>>;
+/** Registry keyed by logical collection name. */
+type HooksRegistry = Record<string, HookMap>;
+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>>;
+    /** Max keys per batch call (default 1000). */
+    maxBatchSize?: number;
+    /** Flush delay in ms (default 0 → microtask flush, i.e. one tick batching). */
+    maxBatchDelayMs?: number;
+    /** Cache loaded values (default true). */
+    cache?: boolean;
+    /** Canonical key function for value-based keys (ObjectId, Date, ...). */
+    keyOf?: (key: Key) => string;
+    cacheMap?: Map<string, Promise<Value | undefined>>;
+}
+declare class DataLoader<Key, Value> {
+    private readonly batchFn;
+    private readonly maxBatchSize;
+    private readonly maxBatchDelayMs;
+    private readonly cacheEnabled;
+    private readonly keyOf;
+    private readonly cache;
+    private queue;
+    private scheduled;
+    private flushing;
+    constructor(options: DataLoaderOptions<Key, Value>);
+    /** Load one key. Concurrent loads are batched; cached keys resolve instantly. */
+    load(key: Key): Promise<Value | undefined>;
+    /** Load many keys (each resolves independently). */
+    loadMany(keys: readonly Key[]): Promise<Array<Value | undefined>>;
+    clear(key: Key): this;
+    clearAll(): this;
+    /** Pre-populate the cache without hitting the batch function. */
+    prime(key: Key, value: Value): this;
+    get pendingCount(): number;
+    private scheduleFlush;
+    private flush;
+}
+/** Canonical key for value-comparison keys (ObjectId → hex, primitives → typed string). */
+declare const canonicalKey: (value: unknown) => string;
+
+/**
+ * Migration types + constants shared by `./files.ts` (discovery/scaffolding),
+ * `./journal.ts` (the `_migrations` journal) and `./index.ts` (the runner).
+ */
+
+interface MigrationContext {
+    service: unknown;
+    logger: LoggerLike;
+    name: string;
+}
+interface MigrationModule {
+    up: (ctx: MigrationContext) => void | Promise<void>;
+    down: (ctx: MigrationContext) => void | Promise<void>;
+}
+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). */
+    down(targetName?: string): Promise<void>;
+    status(): Promise<{
+        applied: string[];
+        pending: string[];
+    }>;
+    /** Scaffold a new `NNN_name.ts` migration file; returns its path. */
+    create(name: string): Promise<string>;
+}
+interface MongoMigrationRunnerOptions {
+    migrationDir?: string;
+    logger?: LoggerLike;
+}
+
+/**
+ * File-based migration runner — `createMongoMigrationRunner`. Orchestrates the
+ * two sub-systems:
+ *
+ *   - `./files.ts`   — discover / load / scaffold `NNN_name.ts` files
+ *   - `./journal.ts` — claim-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.
+ */
+
+/** The `service` shape the runner needs (one connected manager + config/logger). */
+interface MigrationService {
+    db: Record<string, unknown>;
+    logger: LoggerLike;
+    config?: {
+        migrationDir?: string;
+    };
+}
+declare const createMongoMigrationRunner: (service: MigrationService, options?: MongoMigrationRunnerOptions) => MongoMigrationRunner;
+
+interface RetryOptions {
+    maxAttempts?: number;
+    delayMs?: number;
+    logger?: LoggerLike;
+}
+/**
+ * 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.
+ */
+declare const withRetry: <T>(fn: () => Promise<T>, options?: RetryOptions, _ctx?: unknown) => Promise<T>;
+/**
+ * Manual transaction helper: start → run → commit, aborting + ending the
+ * session on any failure. Prefer the service-level `transaction()` which also
+ * handles capability detection and unsupported-server fallback.
+ */
+declare const withTransaction: <T>(client: MongoClient, fn: (session: ClientSession) => Promise<T>) => Promise<T>;
+
+/**
+ * Types for the read-side document-drift validator (`validateDoc`). Pure type
+ * declarations — the detection logic lives in `./validate.ts`,
+ * `./field-validators.ts` (per-kind rules), and `./helpers.ts`.
+ */
+/**
+ * Read-path drift policy: how the ORM reacts to a document that doesn't match
+ * its declared schema when it is fetched from the DB (cache-miss).
+ *
+ *   - `'off'`    — do not check (pre-drift-detection behavior).
+ *   - `'report'` — log a warning with field-level detail, return as-is.
+ *   - `'throw'`  — throw `DomainError SCHEMA_DRIFT` with the offending fields.
+ */
+type DriftMode = 'off' | 'report' | 'throw';
+type DriftIssueCode = 'missing' | 'type' | 'unknown_key' | 'constraint' | 'enum';
+/** A single schema/drift violation on a stored document. */
+interface DriftIssue {
+    /** Dot-path to the offending field (array indexes as `[n]`), e.g. `profile.address.city`. */
+    path: string;
+    code: DriftIssueCode;
+    /** Human-readable expectation, e.g. `string(minLength 3)`, `ObjectId`, `enum[...]`. */
+    expected: string;
+    message: string;
+}
+
+/**
+ * The `$jsonSchema` fragment type emitted by the ORM's schema DSL.
+ *
+ * Kept in its own module (no imports) so both the DSL (`types.ts`) and the
+ * converter (`to-mongo-schema.ts`) can reference it without a circular import
+ * — the DSL's `s.jsonSchema(fragment)` escape hatch needs the type, and the
+ * converter produces it.
+ *
+ * Mirrors the MongoDB `$jsonSchema` keywords this ORM supports (plus a few it
+ * accepts verbatim via the raw escape hatch). Unknown/unlisted keywords are not
+ * enforced at the type level, so a raw fragment can still be passed through
+ * `as MongoJsonSchema` when needed.
+ */
+interface MongoJsonSchema {
+    /** A single BSON type, or an array of allowed types (e.g. ['date', 'null']). */
+    bsonType?: string | string[];
+    required?: string[];
+    properties?: Record<string, MongoJsonSchema>;
+    additionalProperties?: boolean | MongoJsonSchema;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    format?: string;
+    minimum?: number;
+    maximum?: number;
+    /** Draft-4 boolean form, or numeric form on newer servers. */
+    exclusiveMinimum?: boolean | number;
+    exclusiveMaximum?: boolean | number;
+    multipleOf?: number;
+    enum?: unknown[];
+    items?: MongoJsonSchema | MongoJsonSchema[];
+    minItems?: number;
+    maxItems?: number;
+    uniqueItems?: boolean;
+    minProperties?: number;
+    maxProperties?: number;
+    description?: string;
+}
+
+/**
+ * Typed schema DSL for `ninox`.
+ *
+ * Schemas are plain, serializable objects (kind + constraints + flags). They
+ * serve three purposes at once:
+ *   1. Derive the TypeScript document type (`InferDoc<T>`)
+ *   2. Drive the fluent query builder's field typing
+ *   3. Convert to a MongoDB `$jsonSchema` validator (`toMongoValidator`)
+ *
+ * Example:
+ *   const userSchema = s.object({
+ *     _id: s.objectId(),
+ *     email: s.string().optional(),
+ *     age: s.integer({ minimum: 0 }),
+ *     role: s.enum(['admin', 'user'] as const),
+ *     createdAt: s.date(),
+ *   });
+ *   type User = InferDoc<typeof userSchema>;
+ */
+
+interface FieldFlags {
+    optional: boolean;
+    hasDefault: boolean;
+    defaultValue?: unknown;
+}
+interface FieldMeta {
+    kind: string;
+    flags: FieldFlags;
+    description?: string;
+}
+interface StringField extends FieldMeta {
+    kind: 'string';
+    format?: string;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+}
+interface IntegerField extends FieldMeta {
+    kind: 'number';
+    integer: true;
+    minimum?: number;
+    maximum?: number;
+    multipleOf?: number;
+    /** Draft-4 boolean form: `minimum` is excluded from the allowed range. */
+    exclusiveMinimum?: boolean;
+    exclusiveMaximum?: boolean;
+}
+interface NumberField extends FieldMeta {
+    kind: 'number';
+    integer?: false;
+    minimum?: number;
+    maximum?: number;
+    multipleOf?: number;
+    exclusiveMinimum?: boolean;
+    exclusiveMaximum?: boolean;
+}
+/** Strict BSON `double` (IEEE 754 float64) field. */
+interface DoubleField extends FieldMeta {
+    kind: 'double';
+    minimum?: number;
+    maximum?: number;
+    multipleOf?: number;
+    exclusiveMinimum?: boolean;
+    exclusiveMaximum?: boolean;
+}
+/** Strict BSON `long` (int64) field — inferred as `number` (precision caveat). */
+interface LongField extends FieldMeta {
+    kind: 'long';
+    minimum?: number;
+    maximum?: number;
+    multipleOf?: number;
+    exclusiveMinimum?: boolean;
+    exclusiveMaximum?: boolean;
+}
+/** Strict BSON `decimal` (Decimal128) field — inferred as `Decimal128`. */
+interface DecimalField extends FieldMeta {
+    kind: 'decimal';
+    minimum?: number;
+    maximum?: number;
+    multipleOf?: number;
+    exclusiveMinimum?: boolean;
+    exclusiveMaximum?: boolean;
+}
+interface BooleanField extends FieldMeta {
+    kind: 'boolean';
+}
+interface DateField extends FieldMeta {
+    kind: 'date';
+}
+interface ObjectIdField extends FieldMeta {
+    kind: 'objectId';
+}
+interface ArrayField<I extends SchemaType = SchemaType> extends FieldMeta {
+    kind: 'array';
+    items: I;
+    minItems?: number;
+    maxItems?: number;
+    uniqueItems?: boolean;
+}
+interface ObjectField<P extends Record<string, SchemaType> = Record<string, SchemaType>, N extends string = string> extends FieldMeta {
+    kind: 'object';
+    properties: P;
+    additionalProperties?: boolean;
+    minProperties?: number;
+    maxProperties?: number;
+    /**
+     * Optional collection name carried by the schema. When present, the schema is
+     * the single source of truth for the collection name — `defineCollections`
+     * keys the derived `collections` map by it.
+     */
+    name?: N;
+}
+interface EnumField<V extends readonly (string | number)[] = readonly (string | number)[]> extends FieldMeta {
+    kind: 'enum';
+    values: V;
+}
+interface AnyField extends FieldMeta {
+    kind: 'any';
+}
+interface NullField extends FieldMeta {
+    kind: 'null';
+}
+interface GeoPointField extends FieldMeta {
+    kind: 'geoPoint';
+}
+interface RawField extends FieldMeta {
+    kind: 'raw';
+    /** Arbitrary `$jsonSchema` fragment passed through verbatim (escape hatch). */
+    fragment: MongoJsonSchema;
+}
+type SchemaType = StringField | IntegerField | NumberField | DoubleField | LongField | DecimalField | BooleanField | DateField | ObjectIdField | ArrayField | ObjectField | EnumField | AnyField | NullField | GeoPointField | RawField;
+/** A schema with chainable `.optional()` / `.default()` modifiers attached. */
+type Chainable<T extends SchemaType> = T & {
+    optional(): Chainable<T & {
+        flags: {
+            optional: true;
+        };
+    }>;
+    default(value: unknown): Chainable<T & {
+        flags: {
+            hasDefault: true;
+            defaultValue: unknown;
+        };
+    }>;
+};
+/**
+ * Object schema factory (exposed as `s.object`). When `name` is provided the
+ * returned schema carries it as a required literal, so `defineCollections` can
+ * key the derived map by it and forget a name becomes a type error.
+ */
+declare function objectField<P extends Record<string, SchemaType>, N extends string>(properties: P, opts: {
+    additionalProperties?: boolean;
+    minProperties?: number;
+    maxProperties?: number;
+    name: N;
+}): Chainable<ObjectField<P, N> & {
+    name: N;
+}>;
+declare function objectField<P extends Record<string, SchemaType>>(properties: P, opts?: {
+    additionalProperties?: boolean;
+    minProperties?: number;
+    maxProperties?: number;
+}): Chainable<ObjectField<P, string>>;
+/** Numeric constraints shared by every numeric field kind. */
+type NumberBounds = {
+    minimum?: number;
+    maximum?: number;
+    multipleOf?: number;
+    exclusiveMinimum?: boolean;
+    exclusiveMaximum?: boolean;
+};
+declare const s: {
+    /** UTF-8 string field (optional `format` / length / regex constraints). */
+    string(opts?: {
+        format?: string;
+        minLength?: number;
+        maxLength?: number;
+        pattern?: string;
+    }): Chainable<StringField>;
+    /** 32-bit integer field with optional bounds (min/max, exclusive, multipleOf). */
+    integer(opts?: NumberBounds): Chainable<IntegerField>;
+    /** Double/float field with optional bounds (min/max, exclusive, multipleOf). */
+    number(opts?: NumberBounds): Chainable<NumberField>;
+    /** Strict BSON `double` (IEEE 754 float64) field. */
+    double(opts?: NumberBounds): Chainable<DoubleField>;
+    /** Strict BSON `long` (int64) field — inferred as `number`. */
+    long(opts?: NumberBounds): Chainable<LongField>;
+    /** Strict BSON `decimal` (Decimal128) field — inferred as `Decimal128`. */
+    decimal(opts?: NumberBounds): Chainable<DecimalField>;
+    /** Boolean field. */
+    boolean(): Chainable<BooleanField>;
+    /** UTC datetime field (BSON date). */
+    date(): Chainable<DateField>;
+    /** MongoDB ObjectId field (`_id` and foreign keys). */
+    objectId(): Chainable<ObjectIdField>;
+    /** Array of `items` (nested schema types allowed), with optional length/uniqueness. */
+    array<I extends SchemaType>(items: I, opts?: {
+        minItems?: number;
+        maxItems?: number;
+        uniqueItems?: boolean;
+    }): Chainable<ArrayField<I>>;
+    object: typeof objectField;
+    /** Enum union of literal string/number values. */
+    enum<V extends readonly (string | number)[]>(values: V): Chainable<EnumField<V>>;
+    /** Unconstrained field (no validator bounds). */
+    any(): Chainable<AnyField>;
+    /** Explicitly-nullable field. */
+    null(): Chainable<NullField>;
+    /** GeoJSON Point field (type `Point` + `[lng, lat]` coordinates) for `2dsphere` queries. */
+    geoPoint(): Chainable<GeoPointField>;
+    /**
+     * Raw `$jsonSchema` escape hatch: pass an arbitrary fragment through verbatim
+     * to the validator. Use for Mongo keywords the DSL doesn't model (e.g.
+     * `patternProperties`, `allOf`, `anyOf`, `dependencies`).
+     */
+    jsonSchema(fragment: MongoJsonSchema): Chainable<RawField>;
+};
+/** Standalone modifier: mark a field as optional (`s.string().optional()` equivalent). */
+declare const optional: <T extends SchemaType>(field: T) => Chainable<T & {
+    flags: {
+        optional: true;
+    };
+}>;
+/** Standalone modifier: attach a default value. */
+declare const withDefault: <T extends SchemaType>(field: T, value: unknown) => Chainable<T & {
+    flags: {
+        hasDefault: true;
+        defaultValue: unknown;
+    };
+}>;
+
+/**
+ * Drift-validation orchestrator: `validateValue` (dispatch to the per-kind
+ * registry), `validateObjectProps` (declared properties + strict unknown-key
+ * handling), and the public `validateDoc` entry point.
+ *
+ * Recursion between `validateValue` and `validateObjectProps` flows through the
+ * `deps` object so neither this module nor `./field-validators.ts` imports the
+ * other (no cycle).
+ */
+
+/** Check a stored document against the declared schema; returns any drift issues. */
+declare const validateDoc: (schema: ObjectField, doc: Document) => DriftIssue[];
+
+/**
+ * SDK-level query options. These are separated from driver options so the
+ * public API surface stays stable against driver changes. `resolveQueryOptions`
+ * strips them out and forwards the remainder untouched to the driver.
+ */
+interface QueryOptions {
+    session?: ClientSession;
+    maxTimeMS?: number;
+    hint?: Hint;
+    /** Retry attempts for transient errors (default 3). */
+    maxAttempts?: number;
+    /** Base retry backoff in ms (default 150, exponential). */
+    retryDelayMs?: number;
+    batchSize?: number;
+    /**
+     * Per-op in-flight dedup override. `true` forces dedup on, `false` forces it
+     * off (even when the service default is on); unset inherits the service
+     * `dedupeReads` default.
+     */
+    dedupe?: boolean;
+    /** Per-op read-cache bypass. `false` skips the cache for this read. */
+    cache?: 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. */;
+    collation?: CollationOptions;
+    readPreference?: ReadPreferenceLike;
+    readConcern?: ReadConcern;
+    writeConcern?: WriteConcern;
+    comment?: string | Document;
+    let?: Document;
+    timeoutMS?: number;
+}
+interface ResolvedQueryOptions<TDriverOpts = Record<string, unknown>> {
+    maxAttempts: number;
+    retryDelayMs: number;
+    /** Tri-state: `undefined` inherits the service-level default. */
+    dedupe?: boolean;
+    /** Tri-state: `undefined` inherits the service-level default. */
+    cache?: boolean;
+    /** Write ops retry transient errors only when this is `true`. */
+    retryWrites?: boolean;
+    sdk: {
+        session?: ClientSession;
+        maxTimeMS?: number;
+        hint?: Hint;
+        batchSize?: number;
+        drift?: DriftMode | boolean;
+    };
+    driverOpts: TDriverOpts;
+}
+
+/**
+ * Strict, schema-aware query filter.
+ *
+ * The driver's own `Filter<T>` is deliberately loose: its `RootFilterOperators`
+ * extends `Document` (`{ [key: string]: any }`), so `Filter<PreciseDoc>` still
+ * accepts ANY top-level key. This type re-declares the field-level portion of
+ * the filter plus the root operators WITHOUT inheriting that index signature,
+ * so a typo'd or undeclared field is a compile error on object literals.
+ *
+ * It is a strict subset of the driver's `Filter<T>`, so the ORM bridges it with
+ * a cast only at the driver boundary.
+ */
+
+/** Field-level portion of a filter: exact match, `$`-operators, or nested. */
+type FieldFilters<T> = {
+    [P in keyof WithId<T>]?: Condition<WithId<T>[P]>;
+};
+/** Root operators, mirroring the driver's `RootFilterOperators` without `Document`'s index signature. */
+type RootOperators<T> = {
+    $and?: FilterInput<T>[];
+    $nor?: FilterInput<T>[];
+    $or?: FilterInput<T>[];
+    $text?: RootFilterOperators<T>['$text'];
+    $where?: RootFilterOperators<T>['$where'];
+    $comment?: RootFilterOperators<T>['$comment'];
+};
+type FilterInput<T> = FieldFilters<T> & RootOperators<T>;
+
+/**
+ * Execution context provided by the CRUD layer. `run` participates in the
+ * uniform trace + retry + cache + in-flight-dedup pipeline and returns the
+ * merged driver options to the execute closure.
+ */
+interface QueryBuilderContext<TDoc extends Document> {
+    physicalName: string;
+    collection: Collection<TDoc>;
+    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.
+ *
+ *   await users.query('users')
+ *     .where({ role: 'admin' })
+ *     .sort({ createdAt: -1 })
+ *     .select(['_id', 'email'])
+ *     .limit(20)
+ *     .many();
+ */
+declare class QueryBuilder<TDoc extends Document, TSelection = TDoc> {
+    private readonly ctx;
+    private _filter;
+    private _sort?;
+    private _skip?;
+    private _limit?;
+    private _projection?;
+    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;
+    /** Set the sort order (`{ field: 1 | -1 }`). */
+    sort(sort: Sort): this;
+    /** Skip the first `n` matching documents. */
+    skip(n: number): this;
+    /** Limit the result set to `n` documents. */
+    limit(n: number): this;
+    /** 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;
+    /** Set the index hint. */
+    hint(hint: Hint): this;
+    /** Set the driver cursor batch size. */
+    batchSize(n: number): this;
+    /** Run the query inside a transaction session. */
+    session(session: NonNullable<QueryOptions['session']>): this;
+    /** Cap server-side execution time. */
+    maxTimeMS(ms: number): this;
+    /** Bypass the read cache for this query when `false`. */
+    cache(on: boolean): this;
+    /** Override in-flight dedup for this query when set. */
+    dedupe(on: boolean): this;
+    /** Compile the builder into driver options (does not execute). */
+    private compile;
+    private countOptions;
+    /** Fetch one document (limit forced to 1). */
+    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). */
+    cursor(): FindCursor<WithId<TDoc>>;
+    /** Count matching documents. */
+    count(): Promise<number>;
+    /** True when at least one document matches. */
+    exists(): Promise<boolean>;
+}
+
+/**
+ * Shared type-level utilities (no runtime code).
+ */
+/**
+ * Strip index-signature keys (e.g. `Document`'s `[key: string]`) from a type,
+ * leaving only its explicitly declared fields.
+ */
+type RemoveIndexSignature<T> = {
+    [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K];
+};
+/** GeoJSON Point as stored in MongoDB (used by `s.geoPoint()` and `$geoNear`). */
+type GeoPoint = {
+    type: 'Point';
+    coordinates: [number, number];
+};
+
+/**
+ * Type-level inference from the schema DSL → the document's TypeScript type.
+ *
+ *   type User = InferDoc<typeof userSchema>;
+ *
+ * `optional`/`default` fields become `T | undefined`; everything else is required.
+ */
+type InferField<T extends SchemaType> = T extends {
+    kind: 'string';
+} ? string : T extends {
+    kind: 'number';
+} ? number : T extends {
+    kind: 'boolean';
+} ? boolean : T extends {
+    kind: 'date';
+} ? Date : T extends {
+    kind: 'objectId';
+} ? ObjectId : T extends {
+    kind: 'double';
+} ? number : T extends {
+    kind: 'long';
+} ? number : T extends {
+    kind: 'decimal';
+} ? Decimal128 : T extends {
+    kind: 'geoPoint';
+} ? GeoPoint : T extends {
+    kind: 'array';
+} ? InferField<T['items']>[] : T extends {
+    kind: 'object';
+} ? InferObject<Extract<T, ObjectField>> : T extends {
+    kind: 'enum';
+} ? T['values'][number] : T extends {
+    kind: 'null';
+} ? null : T extends {
+    kind: 'any';
+} ? unknown : T extends {
+    kind: 'raw';
+} ? unknown : never;
+/** True when a field is optional (`.optional()`) or defaulted (`.default(v)`). */
+type IsOptionalProp<T extends SchemaType> = T['flags']['optional'] extends true ? true : T['flags']['hasDefault'] extends true ? true : false;
+/**
+ * Optional/default fields become *optional keys* (`qty?: number`) rather than
+ * required-but-`| undefined`, so documents can be built without them.
+ */
+type InferObject<T extends ObjectField> = {
+    [K in keyof T['properties'] as IsOptionalProp<T['properties'][K]> extends true ? never : K]: InferField<T['properties'][K]>;
+} & {
+    [K in keyof T['properties'] as IsOptionalProp<T['properties'][K]> extends true ? K : never]?: InferField<T['properties'][K]>;
+};
+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;
+    };
+}
+/** Auto-timestamp field names maintained by the ORM when `timestamps` is set. */
+interface CollectionTimestamps {
+    /** Field stamped with the creation time on insert (default `createdAt`). */
+    createdAt?: string;
+    /** Field stamped with the modification time on every update (default `updatedAt`). */
+    updatedAt?: string;
+}
+/**
+ * Collection definition. A value of `collections` may be either a raw object
+ * schema (`s.object({...})`) or a `CollectionDefinition` carrying optional
+ * indexes + hooks.
+ */
+interface CollectionDefinition<TSchema extends ObjectField = ObjectField> {
+    schema: TSchema;
+    indexes?: IndexSpec[];
+    hooks?: HookMap<InferDoc<TSchema>>;
+    /**
+     * Auto-maintain timestamps on create/update. `true` uses the defaults
+     * (`createdAt`/`updatedAt`); an object names custom fields. Fields must exist
+     * in the schema for the values to be stamped.
+     */
+    timestamps?: CollectionTimestamps | boolean;
+}
+type CollectionLike = CollectionDefinition<any> | ObjectField;
+/**
+ * One logical Mongo database. Keys of `collections` are the *logical* collection
+ * names used in every ORM call; physical names are derived via
+ * `collectionPrefix` / `collectionPhysicalNames`.
+ */
+interface DBClientDefinition<TCollections extends Record<string, CollectionLike> = Record<string, CollectionLike>> {
+    /** Actual MongoDB database name. */
+    name: string;
+    /** Connection string. Falls back to env `DB_<CONSTANT_CASE_KEY>`, then config.defaultDb. */
+    dbUrl?: string;
+    collections: TCollections;
+    /** Prefix applied to every logical collection name to produce the physical name. */
+    collectionPrefix?: string;
+    collectionPrefixSeparator?: string;
+    /** Per-logical-collection physical-name overrides. */
+    collectionPhysicalNames?: Partial<Record<string, string>>;
+    connectTimeoutMs?: number;
+    readPreference?: ReadPreferenceLike;
+    readConcern?: ReadConcernLike;
+    writeConcern?: WriteConcern;
+}
+type DbClientsDefinition = Record<string, DBClientDefinition<Record<string, CollectionLike>>>;
+type CollectionDoc<T> = T extends CollectionDefinition<infer S> ? InferDoc<S> : T extends ObjectField ? InferDoc<T> : never;
+type ExtractDbNames<TClients extends DbClientsDefinition> = keyof TClients & string;
+type ExtractCollectionNames<TClients extends DbClientsDefinition, TDb extends ExtractDbNames<TClients>> = keyof TClients[TDb]['collections'] & string;
+type ExtractCollectionType<TClients extends DbClientsDefinition, TDb extends ExtractDbNames<TClients>, TCollection extends ExtractCollectionNames<TClients, TDb>> = CollectionDoc<TClients[TDb]['collections'][TCollection]>;
+
+/**
+ * Relation definitions used by `populate`. Relations declare how documents in
+ * one collection reference documents in another; `populate` then resolves them
+ * with DataLoader-batched `$in` queries (1 + N queries total, not 1 + N×M).
+ */
+
+interface RelationDefBase {
+    /** Foreign logical collection. */
+    collection: string;
+    /** Field on the source document holding the reference key(s). */
+    localField: string;
+    /** Field on the foreign document to match (default `_id`). */
+    foreignField?: string;
+    /** Field name attached to the source document after population. */
+    as: string;
+    /** Optional: max keys per batched `$in` query. */
+    maxBatchSize?: number;
+    /** Optional: cache resolved relations on the loader (default true). */
+    cache?: boolean;
+    /** When true, a missing belongsTo target attaches `undefined` instead of `null`. */
+    optional?: boolean;
+}
+interface BelongsToRelation extends RelationDefBase {
+    type: 'belongsTo';
+}
+interface HasManyRelation extends RelationDefBase {
+    type: 'hasMany';
+}
+interface ManyToManyRelation extends RelationDefBase {
+    type: 'manyToMany';
+    through: {
+        /** Join collection (logical). */
+        collection: string;
+        /** Field on the join doc pointing at the source doc. */
+        localField: string;
+        /** Field on the join doc pointing at the target doc. */
+        foreignField: string;
+    };
+}
+type RelationDef = BelongsToRelation | HasManyRelation | ManyToManyRelation;
+type RelColNames<TClients extends DbClientsDefinition, TDb extends ExtractDbNames<TClients>> = ExtractCollectionNames<TClients, TDb>;
+type RelDocOf<TClients extends DbClientsDefinition, TDb extends ExtractDbNames<TClients>, C extends RelColNames<TClients, TDb>> = ExtractCollectionType<TClients, TDb, C>;
+/** Field-name union of a doc, excluding Mongo `Document`'s index-signature keys. */
+type RelField<T> = Extract<keyof RemoveIndexSignature<T>, string>;
+/** Validates one relation object `R` against the source doc and the registry. */
+type ValidRelation<TClients extends DbClientsDefinition, TDb extends ExtractDbNames<TClients>, TSource extends Document, R> = R extends {
+    type: 'belongsTo';
+    collection: infer C;
+} ? C extends RelColNames<TClients, TDb> ? Omit<R, 'localField' | 'foreignField'> & {
+    localField: RelField<TSource>;
+    foreignField?: RelField<RelDocOf<TClients, TDb, C>>;
+} : never : R extends {
+    type: 'hasMany';
+    collection: infer C;
+} ? C extends RelColNames<TClients, TDb> ? Omit<R, 'localField' | 'foreignField'> & {
+    localField: RelField<TSource>;
+    foreignField?: RelField<RelDocOf<TClients, TDb, C>>;
+} : never : R extends {
+    type: 'manyToMany';
+    collection: infer C;
+    through: {
+        collection: infer TC;
+    };
+} ? C extends RelColNames<TClients, TDb> ? TC extends RelColNames<TClients, TDb> ? Omit<R, 'localField' | 'foreignField' | 'through'> & {
+    localField: RelField<TSource>;
+    foreignField?: RelField<RelDocOf<TClients, TDb, C>>;
+    through: {
+        collection: TC;
+        localField: RelField<RelDocOf<TClients, TDb, TC>>;
+        foreignField: RelField<RelDocOf<TClients, TDb, TC>>;
+    };
+} : never : never : never;
+/**
+ * Maps a tuple of relations to the joined `as` fields attached to result docs.
+ * `belongsTo` resolves to `Doc | null`; `hasMany` / `manyToMany` to `Doc[]`.
+ */
+type JoinedFields<TClients extends DbClientsDefinition, TDb extends ExtractDbNames<TClients>, R extends readonly unknown[]> = {
+    [K in keyof R as K extends `${number}` ? R[K] extends {
+        as: infer A extends string;
+    } ? A : never : never]: R[K] extends {
+        type: 'belongsTo';
+        collection: infer C;
+    } ? C extends RelColNames<TClients, TDb> ? RelDocOf<TClients, TDb, C> | null : never : R[K] extends {
+        type: 'hasMany' | 'manyToMany';
+        collection: infer C;
+    } ? C extends RelColNames<TClients, TDb> ? RelDocOf<TClients, TDb, C>[] : never : never;
+};
+type BelongsToConfig<C extends string, A extends string, L extends string, F extends string> = Omit<BelongsToRelation, 'type' | 'collection' | 'as' | 'localField' | 'foreignField'> & {
+    collection: C;
+    as: A;
+    localField: L;
+    foreignField?: F;
+};
+type HasManyConfig<C extends string, A extends string, L extends string, F extends string> = Omit<HasManyRelation, 'type' | 'collection' | 'as' | 'localField' | 'foreignField'> & {
+    collection: C;
+    as: A;
+    localField: L;
+    foreignField?: F;
+};
+type ManyToManyConfig<C extends string, A extends string, L extends string, TC extends string, F extends string, TLoc extends string, TFor extends string> = Omit<ManyToManyRelation, 'type' | 'collection' | 'as' | 'localField' | 'foreignField' | 'through'> & {
+    collection: C;
+    as: A;
+    localField: L;
+    foreignField?: F;
+    through: {
+        collection: TC;
+        localField: TLoc;
+        foreignField: TFor;
+    };
+};
+/** One source doc → at most one foreign doc (defaults `foreignField: '_id'`). */
+declare const belongsTo: <const C extends string, const A extends string, const L extends string, const F extends string = "_id">(config: BelongsToConfig<C, A, L, F>) => BelongsToRelation & {
+    collection: C;
+    as: A;
+    localField: L;
+    foreignField: F;
+};
+/** One source doc → many foreign docs (defaults `foreignField: '_id'`). */
+declare const hasMany: <const C extends string, const A extends string, const L extends string, const F extends string = "_id">(config: HasManyConfig<C, A, L, F>) => HasManyRelation & {
+    collection: C;
+    as: A;
+    localField: L;
+    foreignField: F;
+};
+/** Source doc → join docs → target docs through a pivot collection. */
+declare const manyToMany: <const C extends string, const A extends string, const L extends string, const TC extends string, const F extends string = "_id", const TLoc extends string = "_id", const TFor extends string = "_id">(config: ManyToManyConfig<C, A, L, TC, F, TLoc, TFor>) => ManyToManyRelation & {
+    collection: C;
+    as: A;
+    localField: L;
+    foreignField: F;
+    through: {
+        collection: TC;
+        localField: TLoc;
+        foreignField: TFor;
+    };
+};
+
+interface PopulateOptions {
+    maxBatchSize?: number;
+    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.
+     */
+    maxDocs?: number;
+}
+
+/** Structured metadata attached to every logged DB operation. */
+interface DbOpMeta {
+    collection: string;
+    physicalCollection?: string;
+    db: string;
+    op: string;
+}
+
+interface CrudOpDeps<TCollection> {
+    trace: <T>(meta: DbOpMeta, fn: () => T | Promise<T>) => Promise<T>;
+    meta: (collection: TCollection, op: string) => DbOpMeta;
+}
+
+/**
+ * Self-declared pipeline stage types (no ODM dependency). A stage is any object
+ * with a `$`-operator key; `Document` is the escape hatch for custom stages.
+ */
+type PipelineStage = Document;
+type FacetPipelineStage = Document;
+/** Real top-level field names of a document (index-signature keys excluded). */
+type FieldName<T> = Extract<keyof RemoveIndexSignature<T>, string>;
+/** `$`-prefixed reference to a real field, e.g. `$status`. */
+type FieldRef<T> = `$${FieldName<T>}`;
+/** Value allowed in a `$project` / `$addFields` / `$set` document. */
+type ProjectionValue = boolean | number | string | null | Document;
+/**
+ * A `$project` / `$addFields` / `$set` spec. Known fields autocomplete;
+ * arbitrary computed / new field names are allowed.
+ */
+type Projection<TDoc> = {
+    [K in FieldName<TDoc>]?: ProjectionValue;
+} & Record<string, ProjectionValue>;
+/** Result type of a single projection / expression value. */
+type ExprResult<TDoc, V> = V extends `$${infer F}` ? F extends FieldName<TDoc> ? TDoc[F & keyof TDoc] : unknown : unknown;
+type IncludeKeys<P> = {
+    [K in keyof P]: P[K] extends 1 ? K : P[K] extends true ? K : never;
+}[keyof P];
+type ExcludeKeys<P> = {
+    [K in keyof P]: P[K] extends 0 ? K : P[K] extends false ? K : never;
+}[keyof P];
+type HasInclusions<P> = IncludeKeys<P> extends never ? false : true;
+type ComputedFields<TDoc, P> = {
+    [K in Exclude<keyof P, FieldName<TDoc>>]: ExprResult<TDoc, P[K]>;
+};
+/** Pick the included fields, keeping `_id` unless the projection drops it. */
+type PickedWithId<TDoc, P> = Pick<TDoc, IncludeKeys<P> & keyof TDoc> & ('_id' extends keyof TDoc ? '_id' extends IncludeKeys<P> | ExcludeKeys<P> ? unknown : Pick<TDoc, '_id'> : unknown);
+/**
+ * Output document of a `$project`. With inclusions (`1`) the output keeps only
+ * those fields (+ `_id`); otherwise it is the input minus exclusions (`0`),
+ * plus any computed new fields (typed when they are `$field` references).
+ */
+type Projected<TDoc extends Document, P> = HasInclusions<P> extends true ? PickedWithId<TDoc, P> & ComputedFields<TDoc, P> : Omit<TDoc, ExcludeKeys<P> & keyof TDoc> & ComputedFields<TDoc, P>;
+/** Output of `$addFields` / `$set`: the input plus added / overridden fields. */
+type Added<TDoc, P> = TDoc & {
+    [K in keyof P]: ExprResult<TDoc, P[K]>;
+};
+/** Output of `$unset` (fields removed). */
+type Unsetted<TDoc, F> = Omit<TDoc, UnsetKeys<F> & keyof TDoc>;
+type UnsetKeys<F> = F extends readonly (infer E)[] ? E extends string ? E : never : F extends string ? F : never;
+/** `$sort` spec: real fields autocomplete; arbitrary paths allowed. */
+type SortKeys<TDoc> = {
+    [K in FieldName<TDoc>]?: 1 | -1;
+} & Record<string, 1 | -1>;
+/**
+ * `$geoNear` spec — MongoDB requires `$geoNear` to be the FIRST pipeline stage
+ * and a `2dsphere` (or `2d`) index on the location field.
+ */
+interface GeoNearSpec {
+    /** GeoJSON Point or [longitude, latitude] near which to search. */
+    near: GeoPoint | [number, number];
+    /** Field name written with the computed distance (meters when `spherical`). */
+    distanceField: string;
+    maxDistance?: number;
+    minDistance?: number;
+    spherical?: boolean;
+    distanceMultiplier?: number;
+    includeLocs?: string;
+    key?: string;
+    query?: Document;
+}
+/** Output of `$geoNear`: the input doc plus the computed distance field. */
+type GeoNearOutput<TDoc extends Document, S extends GeoNearSpec> = TDoc & {
+    [K in S['distanceField']]: number;
+};
+/** Value accepted by `$group` accumulators. */
+type AccumulatorSpec = {
+    $sum: number | string | Document | null;
+} | {
+    $avg: number | string | Document | null;
+} | {
+    $first: number | string | Document | null;
+} | {
+    $last: number | string | Document | null;
+} | {
+    $max: number | string | Document | null;
+} | {
+    $min: number | string | Document | null;
+} | {
+    $push: number | string | Document | null;
+} | {
+    $addToSet: number | string | Document | null;
+} | {
+    $count: Record<string, never>;
+};
+/**
+ * `$group` spec: `_id` autocompletes real fields (or a bare name / `null` /
+ * an arbitrary expression document); other keys are accumulators.
+ */
+type GroupSpec<TDoc> = {
+    _id: FieldRef<TDoc> | FieldName<TDoc> | null | Document;
+} & Record<string, AccumulatorSpec | FieldRef<TDoc> | FieldName<TDoc> | null | Document>;
+type DollarField<TDoc, V> = V extends `$${infer F}` ? F extends FieldName<TDoc> ? TDoc[F & keyof TDoc] : unknown : V extends Document ? unknown : V;
+/** Resolved type of a `$group` accumulator expression. */
+type AccumulatorResult<TDoc, A> = A extends {
+    $sum: unknown;
+} ? number : A extends {
+    $avg: unknown;
+} ? number : A extends {
+    $count: unknown;
+} ? number : A extends {
+    $first: infer V;
+} ? DollarField<TDoc, V> : A extends {
+    $last: infer V;
+} ? DollarField<TDoc, V> : A extends {
+    $max: infer V;
+} ? DollarField<TDoc, V> : A extends {
+    $min: infer V;
+} ? DollarField<TDoc, V> : A extends {
+    $push: infer V;
+} ? DollarField<TDoc, V>[] : A extends {
+    $addToSet: infer V;
+} ? DollarField<TDoc, V>[] : unknown;
+/** Output document of a `$group`: `_id` + one field per accumulator. */
+type Grouped<TDoc, G extends GroupSpec<TDoc>> = {
+    _id: G['_id'] extends FieldRef<TDoc> ? DollarField<TDoc, G['_id']> : G['_id'] extends FieldName<TDoc> ? G['_id'] extends keyof TDoc ? TDoc[G['_id']] : unknown : G['_id'] extends null ? null : unknown;
+} & {
+    [K in Exclude<keyof G, '_id'>]: AccumulatorResult<TDoc, G[K]>;
+};
+/** `$unwind` argument (string path or object form). */
+type UnwindSpec = string | {
+    path: string;
+    includeArrayIndex?: string;
+    preserveNullAndEmptyArrays?: boolean;
+};
+type UnwindScalar<TDoc, F extends string> = F extends keyof TDoc ? TDoc[F] extends readonly (infer E)[] ? E : TDoc[F] : unknown;
+/** Output of `$unwind`: the unwound array field becomes its element type. */
+type Unwound<TDoc, P extends UnwindSpec> = P extends string ? P extends `$${infer F}` ? TDoc & {
+    [K in F]: UnwindScalar<TDoc, F>;
+} : TDoc : P extends {
+    path: `$${infer F}`;
+    preserveNullAndEmptyArrays: true;
+} ? TDoc & {
+    [K in F]: UnwindScalar<TDoc, F> | null;
+} : P extends {
+    path: `$${infer F}`;
+} ? TDoc & {
+    [K in F]: UnwindScalar<TDoc, F>;
+} : TDoc;
+/** Foreign collection's document type for a `$lookup.from`. */
+type ForeignDocOf<TClients extends DbClientsDefinition, TDb extends ExtractDbNames<TClients>, C> = C extends ExtractCollectionNames<TClients, TDb> ? ExtractCollectionType<TClients, TDb, C> : never;
+/**
+ * `$lookup` spec keyed by a concrete foreign collection `F`. `from` is
+ * validated as a known collection, `localField` a field on the source doc,
+ * `foreignField` a field on the foreign doc.
+ *
+ * `F` is inferred from `from` as its own type parameter so the sub-pipeline
+ * callback can be contextually typed against the foreign doc without depending
+ * on the (not-yet-inferred) whole spec — this avoids the implicit-`any` pitfall
+ * of an `S & Valid<..., S>` intersection.
+ */
+type LookupSpecFor<TClients extends DbClientsDefinition, TDb extends ExtractDbNames<TClients>, TDoc extends Document, F extends ExtractCollectionNames<TClients, TDb>> = {
+    from: F;
+    localField: FieldName<TDoc>;
+    foreignField?: FieldName<ForeignDocOf<TClients, TDb, F>>;
+    as: string;
+    let?: Record<string, unknown>;
+};
+/** Source doc joined with the `$lookup` output under its `as` field. */
+type LookupJoinedFor<TClients extends DbClientsDefinition, TDb extends ExtractDbNames<TClients>, TDoc extends Document, F extends ExtractCollectionNames<TClients, TDb>, A extends string, O extends Document = ForeignDocOf<TClients, TDb, F>> = TDoc & {
+    [K in A]: O[];
+};
+/**
+ * `$facet` spec: each named branch is a raw pipeline or a function receiving a
+ * builder scoped to the current doc.
+ */
+type FacetSpec<TClients extends DbClientsDefinition, TDb extends ExtractDbNames<TClients>, TDoc extends Document> = Record<string, Document[] | ((sub: PipelineBuilder<TClients, TDb, TDoc>) => PipelineBuilder<TClients, TDb, any> | Document[])>;
+/** Output of `$facet`: one array per branch, typed when built with a builder. */
+type FacetOutput<TClients extends DbClientsDefinition, TDb extends ExtractDbNames<TClients>, TDoc extends Document, F extends FacetSpec<TClients, TDb, TDoc>> = {
+    [K in keyof F]: F[K] extends (s: any) => infer R ? R extends PipelineBuilder<any, any, infer O> ? O[] : unknown[] : unknown[];
+};
+/** Backward-compatible runtime shape for the callback `aggregate().lookup(...)`. */
+interface LookupParams<TDoc extends Document = Document> {
+    from: string;
+    localField: FieldName<TDoc> | string;
+    foreignField: string;
+    as: string;
+    pipeline?: Document[];
+    let?: Record<string, unknown>;
+}
+
+/**
+ * Fully type-safe, chainable aggregation pipeline builder.
+ *
+ * Every stage is typed against the current document shape, so intellisense
+ * follows the real schema fields and the result type of `.toArray()` /
+ * `.first()` is inferred through the whole chain. `$lookup` sub-pipelines are
+ * scoped to the related collection's schema and `$facet` branches get their own
+ * typed sub-builder — see `src/service/pipeline-types.ts` for the type model.
+ *
+ *   const top = await db.pipeline('orders')
+ *     .match({ status: 'paid' })
+ *     .group({ _id: '$userId', total: { $sum: '$total' } })
+ *     .sort({ total: -1 })
+ *     .limit(3)
+ *     .toArray();
+ */
+
+/** Execution dependencies wired up by `makeAggregationOps`. */
+interface PipelineBuilderDeps {
+    logical: string;
+    coll: () => Collection<Document>;
+    crudDeps: CrudOpDeps<string>;
+    mergeDriver: (driverOpts: Record<string, unknown>, sdk: {
+        session?: ClientSession;
+        maxTimeMS?: number;
+        hint?: Hint;
+    }) => AggregateOptions;
+    options?: AggregateOptions & QueryOptions;
+}
+declare class PipelineBuilder<TClients extends DbClientsDefinition, TDb extends ExtractDbNames<TClients>, TDoc extends Document> {
+    private readonly deps;
+    private readonly stages;
+    constructor(deps: PipelineBuilderDeps, stages?: Document[]);
+    /** Raw accumulated stages — embeddable into `$lookup` / `$facet` branches. */
+    raw(): Document[];
+    private assertNonNegativeFinite;
+    match(filter: FilterInput<TDoc>): this;
+    sort(sort: SortKeys<TDoc>): this;
+    limit(n: number): this;
+    skip(n: number): this;
+    sample(n: number): this;
+    /**
+     * `$geoNear` — requires a `2dsphere`/`2d` index and MUST be the first stage.
+     * Adds the computed distance to `spec.distanceField` on every output doc.
+     */
+    geoNear<const S extends GeoNearSpec>(spec: S): PipelineBuilder<TClients, TDb, GeoNearOutput<TDoc, S>>;
+    project<const P extends Projection<TDoc>>(projection: P): PipelineBuilder<TClients, TDb, Projected<TDoc, P>>;
+    addFields<const P extends Projection<TDoc>>(fields: P): PipelineBuilder<TClients, TDb, Added<TDoc, P>>;
+    set<const P extends Projection<TDoc>>(fields: P): PipelineBuilder<TClients, TDb, Added<TDoc, P>>;
+    unset<const F extends string | readonly string[]>(fields: F): PipelineBuilder<TClients, TDb, Unsetted<TDoc, F>>;
+    count<const F extends string>(field: F): PipelineBuilder<TClients, TDb, {
+        [K in F]: number;
+    }>;
+    group<const G extends GroupSpec<TDoc>>(group: G): PipelineBuilder<TClients, TDb, Grouped<TDoc, G>>;
+    unwind<const P extends UnwindSpec>(path: P): PipelineBuilder<TClients, TDb, Unwound<TDoc, P>>;
+    lookup<const F extends ExtractCollectionNames<TClients, TDb>, const A extends string, const O extends Document = ForeignDocOf<TClients, TDb, F>>(spec: LookupSpecFor<TClients, TDb, TDoc, F> & {
+        as: A;
+        pipeline?: Document[] | ((sub: PipelineBuilder<TClients, TDb, ForeignDocOf<TClients, TDb, F>>) => PipelineBuilder<TClients, TDb, O> | Document[]);
+    }): PipelineBuilder<TClients, TDb, LookupJoinedFor<TClients, TDb, TDoc, F, A, O>>;
+    facet<const F extends FacetSpec<TClients, TDb, TDoc>>(facets: F): PipelineBuilder<TClients, TDb, FacetOutput<TClients, TDb, TDoc, F>>;
+    /** Run the pipeline and return every output document. */
+    toArray(): Promise<TDoc[]>;
+    /** Run the pipeline and return the first output document (or null). */
+    first(): Promise<TDoc | null>;
+    /** Streaming cursor (raw driver cursor; no retry / trace). */
+    cursor(): AggregationCursor<TDoc>;
+    private derive;
+    private evalLookup;
+    private evalFacets;
+}
+
+/**
+ * Typed aggregation-stage builder for the `db.aggregate(collection, (stages) =>
+ * [...])` callback API. Each stage is validated against the source document
+ * (`match` fields autocomplete and typo'd fields are compile errors), `$lookup`
+ * sub-pipelines are scoped to the related collection, and `$facet` branches get
+ * their own typed sub-builder. For inferred result types use the chained
+ * `db.pipeline()` builder instead (`src/service/pipeline-builder.ts`).
+ */
+interface AggregationStages<TDoc extends Document = Document, TClients extends DbClientsDefinition = DbClientsDefinition, TDb extends ExtractDbNames<TClients> = ExtractDbNames<TClients>> {
+    match(filter: FilterInput<TDoc>): {
+        $match: FilterInput<TDoc>;
+    };
+    project(fields: Projection<TDoc>): {
+        $project: Projection<TDoc>;
+    };
+    addFields(fields: Projection<TDoc>): {
+        $addFields: Projection<TDoc>;
+    };
+    set(fields: Projection<TDoc>): {
+        $set: Projection<TDoc>;
+    };
+    unset(fields: string | string[]): {
+        $unset: string | string[];
+    };
+    sort(sort: SortKeys<TDoc>): {
+        $sort: SortKeys<TDoc>;
+    };
+    limit(n: number): {
+        $limit: number;
+    };
+    skip(n: number): {
+        $skip: number;
+    };
+    count(field: string): {
+        $count: string;
+    };
+    group(group: GroupSpec<TDoc>): {
+        $group: GroupSpec<TDoc>;
+    };
+    /**
+     * `$geoNear` — requires a `2dsphere`/`2d` index and MUST be the first stage
+     * (throws otherwise).
+     */
+    geoNear(spec: GeoNearSpec): {
+        $geoNear: GeoNearSpec;
+    };
+    lookup<const F extends ExtractCollectionNames<TClients, TDb>, const A extends string, const O extends Document = ForeignDocOf<TClients, TDb, F>>(params: LookupSpecFor<TClients, TDb, TDoc, F> & {
+        as: A;
+        pipeline?: Document[] | ((sub: PipelineBuilder<TClients, TDb, ForeignDocOf<TClients, TDb, F>>) => PipelineBuilder<TClients, TDb, O> | Document[]);
+    }): {
+        $lookup: Document;
+    };
+    facet(facets: Record<string, Document[] | ((stages: AggregationStages<TDoc, TClients, TDb>) => Document[])>): {
+        $facet: Record<string, Document[]>;
+    };
+    unwind(path: UnwindSpec): {
+        $unwind: UnwindSpec;
+    };
+    fill(params: Document): {
+        $fill: Document;
+    };
+    bucket(params: Document): {
+        $bucket: Document;
+    };
+    bucketAuto(params: Document): {
+        $bucketAuto: Document;
+    };
+    densify(params: Document): {
+        $densify: Document;
+    };
+}
+
+/**
+ * Strict, schema-aware update payloads.
+ *
+ * The MongoDB driver's own `UpdateFilter<T>` is intentionally loose — every
+ * operator is intersected with `Record<string, any>`, so unknown keys and
+ * wrong value types all type-check. These types re-derive each `$` operator
+ * against the document type instead: keys are restricted to schema fields,
+ * `$inc`/`$mul`/`$bit` to numeric fields, `$push`/`$addToSet`/`$pull`/`$pullAll`/
+ * `$pop` to array fields, and `$currentDate` to date fields. The driver accepts
+ * a superset of these payloads, so the tight type is passed through with a
+ * plain cast at the driver boundary.
+ */
+/** Fields of `T` whose value is numeric (usable with `$inc`, `$mul`, `$bit`). */
+type NumericFields<T> = {
+    [K in keyof T as T[K] extends number ? K : never]?: number;
+};
+/** Fields of `T` whose value is a `Date` (usable with `$currentDate`). */
+type DateFields<T> = {
+    [K in keyof T as T[K] extends Date ? K : never]?: true | {
+        $type: 'date' | 'timestamp';
+    };
+};
+/** Value accepted by `$push` for an array of `I`. */
+type PushValue<I> = I | {
+    $each: readonly I[];
+    $position?: number;
+    $slice?: number;
+    $sort?: 1 | -1 | Record<string, 1 | -1>;
+};
+/** Value accepted by `$addToSet` for an array of `I`. */
+type AddToSetValue<I> = I | {
+    $each: readonly I[];
+};
+/** Value accepted by `$pull` for an array of `I`. */
+type PullValue<I> = I | {
+    $in: readonly I[];
+};
+/** Array fields of `T` mapped to a per-op value type derived from the item type. */
+type PushFields<T> = {
+    [K in keyof T as T[K] extends readonly unknown[] ? K : never]?: T[K] extends readonly (infer I)[] ? PushValue<I> : never;
+};
+type AddToSetFields<T> = {
+    [K in keyof T as T[K] extends readonly unknown[] ? K : never]?: T[K] extends readonly (infer I)[] ? AddToSetValue<I> : never;
+};
+type PullFields<T> = {
+    [K in keyof T as T[K] extends readonly unknown[] ? K : never]?: T[K] extends readonly (infer I)[] ? PullValue<I> : never;
+};
+type PullAllFields<T> = {
+    [K in keyof T as T[K] extends readonly unknown[] ? K : never]?: T[K] extends readonly (infer I)[] ? readonly I[] : never;
+};
+type PopFields<T> = {
+    [K in keyof T as T[K] extends readonly unknown[] ? K : never]?: 1 | -1;
+};
+/** The `$`-operator form of an update, keyed strictly against the document type. */
+type UpdateOperators<T> = {
+    $set?: Partial<T>;
+    $setOnInsert?: Partial<T>;
+    $unset?: Partial<Record<keyof T, '' | true | 1>>;
+    $inc?: NumericFields<T>;
+    $mul?: NumericFields<T>;
+    $min?: Partial<T>;
+    $max?: Partial<T>;
+    $bit?: NumericFields<T>;
+    $currentDate?: DateFields<T>;
+    $push?: PushFields<T>;
+    $addToSet?: AddToSetFields<T>;
+    $pull?: PullFields<T>;
+    $pullAll?: PullAllFields<T>;
+    $pop?: PopFields<T>;
+    $rename?: Partial<Record<keyof T, keyof T>>;
+};
+/**
+ * Update payload accepted by the ORM's update methods: either a plain field
+ * patch (automatically wrapped in `$set` by `formatUpdateFilter`) or
+ * `$`-operator syntax. Keys and values are checked against the document schema.
+ *
+ * The doc type is precise (schema-derived), so unknown keys are rejected in
+ * fresh object literals via excess-property checking AND in non-literal patches
+ * (the inferred type has no index signature to absorb them). The only way an
+ * unknown key passes is a variable explicitly typed with an index signature
+ * (e.g. `Record<string, any>`) — an intentional "unknown shape" escape hatch;
+ * prefer inline literals for full checking.
+ */
+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'> & {
+    _id?: T extends {
+        _id: infer I;
+    } ? I : never;
+};
+type VersionedUpdateResult<T> = {
+    ok: true;
+    doc: T;
+} | {
+    ok: false;
+    reason: 'not_found' | 'version_conflict';
+};
+/**
+ * Find-query options. Extends driver `FindOptions` + SDK `QueryOptions` with a
+ * first-class `select` (field list) that is translated to a driver `projection`
+ * so only the requested fields are transferred from the server.
+ */
+type FindQueryOptions<T> = FindOptions & QueryOptions & {
+    /** Project only the listed fields — pushed to the driver as `projection`. */
+    select?: readonly (keyof T)[];
+};
+/** Per-collection auto-timestamp config (keyed by logical collection name). */
+type TimestampsByCollection = Record<string, CollectionTimestamps | undefined>;
+interface CrudOpsOptions {
+    resolveCollectionName: (logical: string) => string;
+    wrapMongoErrors?: boolean;
+    cache?: QueryCache;
+    dedupeReads?: boolean;
+    inFlight?: InFlight;
+    hooks?: HooksRegistry;
+    /** Auto-timestamp field names per collection (from the collection definition). */
+    timestamps?: TimestampsByCollection;
+    /** Service-level schema-drift policy for reads (default `'report'`). */
+    drift?: DriftMode;
+    /** Resolve the declared schema for a logical collection (drift detection). */
+    getSchema?: (logical: string) => ObjectField | undefined;
+}
+
+/**
+ * Build the CRUD operation set for one database. Every method is collection-name
+ * first and schema-typed (no `<TDoc>` at call sites). Reads go through the
+ * cache + in-flight dedup path; writes invalidate the cache for that collection
+ * 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?: 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]>>>;
+    updateOne: <X extends ColNames<TClients, TDb>>(collection: X, filter: FilterInput<CollectionDoc<TClients[TDb]["collections"][X]>>, update: UpdateInput<CollectionDoc<TClients[TDb]["collections"][X]>>, options?: mongodb.UpdateOptions & QueryOptions) => Promise<mongodb.UpdateResult<CollectionDoc<TClients[TDb]["collections"][X]>>>;
+    updateMany: <X extends ColNames<TClients, TDb>>(collection: X, filter: FilterInput<CollectionDoc<TClients[TDb]["collections"][X]>>, update: UpdateInput<CollectionDoc<TClients[TDb]["collections"][X]>>, options?: mongodb.UpdateOptions & QueryOptions) => Promise<mongodb.UpdateResult<CollectionDoc<TClients[TDb]["collections"][X]>>>;
+    findOneAndUpdate: <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<CollectionDoc<TClients[TDb]["collections"][X]> | null>;
+    findOneAndReplace: <X extends ColNames<TClients, TDb>>(collection: X, filter: FilterInput<CollectionDoc<TClients[TDb]["collections"][X]>>, replacement: CollectionDoc<TClients[TDb]["collections"][X]>, options?: mongodb.FindOneAndReplaceOptions & QueryOptions) => Promise<CollectionDoc<TClients[TDb]["collections"][X]> | null>;
+    deleteOne: <X extends ColNames<TClients, TDb>>(collection: X, filter: FilterInput<CollectionDoc<TClients[TDb]["collections"][X]>>, options?: mongodb.DeleteOptions & QueryOptions) => Promise<mongodb.DeleteResult>;
+    deleteMany: <X extends ColNames<TClients, TDb>>(collection: X, filter: FilterInput<CollectionDoc<TClients[TDb]["collections"][X]>>, options?: mongodb.DeleteOptions & QueryOptions) => Promise<mongodb.DeleteResult>;
+    softDeleteOne: <X extends ColNames<TClients, TDb>>(collection: X, filter: FilterInput<CollectionDoc<TClients[TDb]["collections"][X]>>, options?: mongodb.UpdateOptions & QueryOptions) => Promise<mongodb.UpdateResult<CollectionDoc<TClients[TDb]["collections"][X]>>>;
+    upsert: <X extends ColNames<TClients, TDb>>(collection: X, filter: FilterInput<CollectionDoc<TClients[TDb]["collections"][X]>>, update: UpdateInput<CollectionDoc<TClients[TDb]["collections"][X]>>, options?: mongodb.UpdateOptions & QueryOptions) => Promise<mongodb.UpdateResult<CollectionDoc<TClients[TDb]["collections"][X]>>>;
+    bulkUpsert: <X extends ColNames<TClients, TDb>>(collection: X, operations: {
+        filter: FilterInput<CollectionDoc<TClients[TDb]["collections"][X]>>;
+        update: UpdateInput<CollectionDoc<TClients[TDb]["collections"][X]>>;
+        upsert?: boolean;
+    }[], 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]>>>;
+    getOne: <X extends ColNames<TClients, TDb>>(collection: X, filter?: FilterInput<CollectionDoc<TClients[TDb]["collections"][X]>> | undefined, options?: FindQueryOptions<CollectionDoc<TClients[TDb]["collections"][X]>> | undefined) => Promise<CollectionDoc<TClients[TDb]["collections"][X]> | null>;
+    getOneOrFail: <X extends ColNames<TClients, TDb>>(collection: X, filter?: FilterInput<CollectionDoc<TClients[TDb]["collections"][X]>> | undefined, options?: FindQueryOptions<CollectionDoc<TClients[TDb]["collections"][X]>> | undefined, errorFactory?: ((name: string) => Error) | undefined) => Promise<CollectionDoc<TClients[TDb]["collections"][X]>>;
+    findMany: <X extends ColNames<TClients, TDb>>(collection: X, filter?: FilterInput<CollectionDoc<TClients[TDb]["collections"][X]>> | undefined, options?: FindQueryOptions<CollectionDoc<TClients[TDb]["collections"][X]>> | undefined) => Promise<CollectionDoc<TClients[TDb]["collections"][X]>[]>;
+    findManyCursor: <X extends ColNames<TClients, TDb>>(collection: X, filter?: FilterInput<CollectionDoc<TClients[TDb]["collections"][X]>> | undefined, options?: FindQueryOptions<CollectionDoc<TClients[TDb]["collections"][X]>> | undefined) => mongodb.FindCursor<CollectionDoc<TClients[TDb]["collections"][X]>>;
+    findActive: <X extends ColNames<TClients, TDb>>(collection: X, filter?: FilterInput<CollectionDoc<TClients[TDb]["collections"][X]>> | undefined, options?: FindQueryOptions<CollectionDoc<TClients[TDb]["collections"][X]>> | undefined) => Promise<CollectionDoc<TClients[TDb]["collections"][X]>[]>;
+    findActiveOne: <X extends ColNames<TClients, TDb>>(collection: X, filter?: FilterInput<CollectionDoc<TClients[TDb]["collections"][X]>> | undefined, options?: FindQueryOptions<CollectionDoc<TClients[TDb]["collections"][X]>> | undefined) => Promise<CollectionDoc<TClients[TDb]["collections"][X]> | null>;
+    countDocuments: <X extends ColNames<TClients, TDb>>(collection: X, filter?: FilterInput<CollectionDoc<TClients[TDb]["collections"][X]>> | undefined, options?: mongodb.CountDocumentsOptions & QueryOptions) => Promise<number>;
+    distinct: <X extends ColNames<TClients, TDb>, K extends keyof CollectionDoc<TClients[TDb]["collections"][X]>>(collection: X, field: K, filter?: FilterInput<CollectionDoc<TClients[TDb]["collections"][X]>> | undefined, options?: FindQueryOptions<CollectionDoc<TClients[TDb]["collections"][X]>> | undefined) => Promise<CollectionDoc<TClients[TDb]["collections"][X]>[K][]>;
+    estimatedDocumentCount: <X extends ColNames<TClients, TDb>>(collection: X, options?: mongodb.EstimatedDocumentCountOptions & QueryOptions) => Promise<number>;
+};
+type CrudOps<TClients extends DbClientsDefinition, TDb extends ExtractDbNames<TClients>> = ReturnType<typeof makeCrudOps<TClients, TDb>>;
+
+/**
+ * Service configuration: the `MongoServiceConfig` options type, cache policy
+ * resolution (`resolveCache`), and runtime-config derivation
+ * (`resolveRuntimeConfig`). Pure — no connection or manager wiring here, so the
+ * config concerns of the service are isolated from the composition root.
+ */
+
+interface MongoServiceConfig {
+    defaultDb?: string;
+    migrationDir?: string;
+    appName?: string;
+    logger?: LoggerLike;
+    /**
+     * Map driver errors to typed DomainError/InfraError before rethrowing. ON by
+     * default — set `false` to surface raw driver errors instead.
+     */
+    wrapMongoErrors?: boolean;
+    /**
+     * Read-through query cache shared by every CRUD read. ON by default:
+     * `undefined` creates a default `QueryCache()`, `QueryCacheOptions` builds
+     * one, a `QueryCache` is reused, and `null` disables caching.
+     *
+     * 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
+     * change-stream aware `createHotCache()`, or set `cacheWatch: true`.
+     */
+    cache?: QueryCache | QueryCacheOptions | null;
+    /**
+     * Opt into change-stream invalidation of the shared query cache. When `true`
+     * (and a cache is enabled), after `makeConnections()` one `$changeStream`
+     * watcher is opened per registered collection; any write — including external
+     * ones — invalidates that collection's cached reads. Requires a replica set /
+     * mongos. On standalone servers the streams are rejected, a warning is logged
+     * once, and invalidation silently disables (the cache stays write-through
+     * only). Watchers self-heal across transient errors and are closed by
+     * `closeConnections()`. Default: false.
+     */
+    cacheWatch?: boolean;
+    /** Coalesce identical concurrent reads into one driver call. ON by default. */
+    dedupeReads?: boolean;
+    /**
+     * Master performance switch. `perf: false` disables the query cache and
+     * in-flight dedup even when the granular options are set. Defaults to true.
+     */
+    perf?: boolean;
+    /**
+     * Schema-drift policy for reads. When a document fetched from the DB
+     * (cache-miss) doesn't match its declared schema:
+     *   - `'report'` (default) — log a warning with the offending fields, return as-is
+     *   - `'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`.
+     */
+    drift?: DriftMode;
+}
+
+interface DbHealthResult {
+    /** Logical db client key (e.g. `primary`). */
+    name: string;
+    ok: boolean;
+    /** Ping round-trip time in ms (present when `ok`). */
+    latencyMs?: number;
+}
+interface HealthReport {
+    ok: boolean;
+    /** Total elapsed time across all pings in ms. */
+    latencyMs: number;
+    dbs: DbHealthResult[];
+}
+
+interface SearchConfig {
+    /** Fields to search across. */
+    searchFields: string[];
+    /** Search term. */
+    searchTerm: string;
+    /** Loose per-character matching (`$regex` mode only). */
+    fuzzy?: boolean;
+    /** Case sensitivity (`$text` mode; `$regex` mode uses this too). */
+    caseSensitive?: boolean;
+    /** true → `$regex` search; false (default) → `$text` search. */
+    useRegex?: boolean;
+    /** `$text` search language (defaults to the server's default). */
+    language?: string;
+    /** `$text` diacritic sensitivity (default false → insensitive). */
+    diacriticSensitive?: boolean;
+    /**
+     * When true, `textSearch` sorts by `searchScore` (textScore meta) instead of
+     * the caller's sort. `$text`-mode only.
+     */
+    sortByScore?: boolean;
+}
+
+/**
+ * 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.
+ */
+
+interface GroupByConfig {
+    /** Group key: a field name or a document of `$`-expressions. */
+    groupBy: string | Record<string, unknown>;
+    /** Accumulator expressions, e.g. `{ revenue: { $sum: '$total' } }`. */
+    accumulate?: Record<string, unknown>;
+    /** Sort the grouped output. */
+    sort?: Record<string, 1 | -1>;
+    /** Cap the number of groups returned. */
+    limit?: number;
+}
+interface DateRangeConfig {
+    /** Date field to bucket on (must exist on every doc). */
+    dateField: string;
+    /** Inclusive range start. */
+    startDate: Date;
+    /** Inclusive range end. */
+    endDate: Date;
+    /** Bucket granularity (default `day`). */
+    granularity?: 'hour' | 'day' | 'week' | 'month' | 'year';
+}
+interface LookupConfig {
+    /** Related (logical) collection to join. */
+    fromCollection: string;
+    /** Field on the source docs holding the foreign key. */
+    localField: string;
+    /** Field on the foreign docs to match. */
+    foreignField: string;
+    /** Output field name for the joined array. */
+    as: string;
+    /** Optional `$pipeline` limiting/filtering the joined docs. */
+    pipeline?: Document[];
+    /** When true, `$unwind` the joined array (preserving nulls). */
+    unwindSingle?: boolean;
+}
+interface PipelineCustomization {
+    /** Stages prepended before the generated aggregation. */
+    prePipeline?: Document[];
+    /** Stages appended after the generated aggregation. */
+    postPipeline?: Document[];
+}
+interface AggregationOpsOptions {
+    resolveCollectionName: (logical: string) => string;
+    wrapMongoErrors?: boolean;
+}
+/** Pagination subset used by `textSearch`. */
+interface TextSearchPagination {
+    page?: number;
+    limit?: number;
+    sort?: Record<string, 1 | -1>;
+    maxLimit?: number;
+}
+
+/**
+ * Aggregation ops for one database: `aggregate`, `pipeline`, `groupBy`,
+ * `textSearch`, `dateRangeAnalysis`, `lookupJoin`. All collection-name first
+ * and schema-typed.
+ */
+declare const makeAggregationOps: <TClients extends DbClientsDefinition, TDb extends ExtractDbNames<TClients>>(client: Db, dbLabel: string, logger: LoggerLike, opts: AggregationOpsOptions) => {
+    lookupJoin: <X extends ExtractCollectionNames<TClients, TDb>, TResult extends Document = CollectionDoc<TClients[TDb]["collections"][X]>>(collection: X, baseFilter: FilterInput<CollectionDoc<TClients[TDb]["collections"][X]>>, lookups: LookupConfig[], customization?: PipelineCustomization, options?: mongodb.AggregateOptions & QueryOptions) => Promise<TResult[]>;
+    textSearch: <X extends ExtractCollectionNames<TClients, TDb>>(collection: X, baseFilter: FilterInput<CollectionDoc<TClients[TDb]["collections"][X]>>, searchConfig: SearchConfig, paginationConfig?: TextSearchPagination, customization?: PipelineCustomization, options?: mongodb.AggregateOptions & QueryOptions) => Promise<PaginationResult<CollectionDoc<TClients[TDb]["collections"][X]> & {
+        searchScore?: number;
+    }>>;
+    groupBy: <X extends ExtractCollectionNames<TClients, TDb>, TResult_1 extends Document = Document>(collection: X, baseFilter: FilterInput<CollectionDoc<TClients[TDb]["collections"][X]>>, config: GroupByConfig, customization?: PipelineCustomization, options?: mongodb.AggregateOptions & QueryOptions) => Promise<TResult_1[]>;
+    dateRangeAnalysis: <X extends ExtractCollectionNames<TClients, TDb>, TResult_2 extends Document = Document>(collection: X, baseFilter: FilterInput<CollectionDoc<TClients[TDb]["collections"][X]>>, dateConfig: DateRangeConfig, analysisConfig?: {
+        accumulate?: Record<string, unknown>;
+        sort?: Record<string, 1 | -1>;
+        limit?: number;
+    }, customization?: PipelineCustomization, options?: mongodb.AggregateOptions & QueryOptions) => Promise<TResult_2[]>;
+    aggregate: <X extends ExtractCollectionNames<TClients, TDb>, TResult_3 extends Document = Document>(collection: X, pipelineBuilder: (stages: AggregationStages<CollectionDoc<TClients[TDb]["collections"][X]>, TClients, TDb>) => Document[], options?: mongodb.AggregateOptions & QueryOptions) => Promise<mongodb.AggregationCursor<TResult_3>>;
+    pipeline: <const X extends ExtractCollectionNames<TClients, TDb>>(collection: X, options?: mongodb.AggregateOptions & QueryOptions) => PipelineBuilder<TClients, TDb, CollectionDoc<TClients[TDb]["collections"][X]>>;
+};
+
+/**
+ * Optional change-stream watchers that invalidate the shared query cache on
+ * EXTERNAL writes — other processes, the raw `client` escape hatch, or direct
+ * DB writes — closing the write-through-only gap of the ORM `QueryCache`.
+ *
+ * Requires a replica set / mongos. On standalone servers `$changeStream` is
+ * rejected, so the invalidator logs a warning once and disables itself (the
+ * cache then stays write-through only — see `MongoServiceConfig.cacheWatch`).
+ *
+ * One watcher is opened per unique (database, physical collection); any change
+ * invalidates every cached read for that collection via
+ * `QueryCache.invalidateByCollection`. Watchers self-heal: transient errors
+ * retry with backoff and the collection is re-invalidated on reopen, so
+ * changes missed during an outage don't leave stale entries behind.
+ */
+
+/** A collection whose external writes should invalidate cached reads. */
+interface CacheInvalidationRef {
+    /** Raw `Db` handle (e.g. `service.db.primaryClient.client`). */
+    db: Db;
+    /** PHYSICAL collection name — cache keys use it, so invalidation must too. */
+    collection: string;
+}
+declare class CacheInvalidator {
+    private cache;
+    private logger;
+    private streams;
+    private disabled;
+    private stopped;
+    private warnedUnsupported;
+    constructor(options: {
+        cache: QueryCache;
+        logger: LoggerLike;
+    });
+    /** Number of currently open change streams. */
+    get size(): number;
+    /**
+     * Open one watcher per unique (database, physical collection). Idempotent:
+     * already-open streams are skipped; after `stop()` a later `start()` reopens.
+     * Never throws — failures are logged (on unsupported servers it disables once).
+     */
+    start(refs: CacheInvalidationRef[]): Promise<void>;
+    /** Close every watcher. Safe to call repeatedly, and before any `start`. */
+    stop(): Promise<void>;
+    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;
+    /** Stages prepended to the data facet (e.g. extra $match). */
+    prePipeline?: Document[];
+    /** Stages appended inside the data facet. */
+    postPipeline?: Document[];
+    queryOptions?: QueryOptions;
+}
+interface CursorPaginationConfig<T = Document> {
+    limit?: number;
+    /**
+     * Sort keys (1 ascending / -1 descending). MUST include a unique tiebreaker —
+     * typically `_id` — so cursor boundaries are unambiguous. Sort fields should
+     * exist on every document for deterministic ordering.
+     */
+    sort: Record<string, 1 | -1>;
+    /** Opaque cursor from a previous `nextCursor` — fetch the page after it. */
+    after?: string;
+    /** Opaque cursor — fetch the page before it (backward navigation). */
+    before?: string;
+    /** Cap on the requested limit (default DEFAULT_MAX_LIMIT). */
+    maxLimit?: number;
+    queryOptions?: QueryOptions;
+}
+interface CursorPage<T> {
+    data: T[];
+    /** Opaque cursor for the next page in the queried direction, or null when exhausted. */
+    nextCursor: string | null;
+    /** True when another page exists in the queried direction. */
+    hasMore: boolean;
+}
+interface PaginationOpsOptions {
+    resolveCollectionName: (logical: string) => string;
+    wrapMongoErrors?: boolean;
+    /** Service-level schema-drift policy for reads (default `'report'`). */
+    drift?: DriftMode;
+    /** Resolve the declared schema for a logical collection (drift detection). */
+    getSchema?: (logical: string) => ObjectField | undefined;
+}
+
+/**
+ * Pagination ops for one database: `paginateFlexible` (offset, `$facet`) and
+ * `paginateCursor` (keyset). Both are collection-name first and schema-typed.
+ */
+declare const makePaginationOps: <TClients extends DbClientsDefinition, TDb extends ExtractDbNames<TClients>>(client: Db, dbLabel: string, logger: LoggerLike, opts: PaginationOpsOptions) => {
+    paginateCursor: <X extends ExtractCollectionNames<TClients, TDb>>(collection: X, baseFilter: FilterInput<CollectionDoc<TClients[TDb]["collections"][X]>>, config: CursorPaginationConfig<CollectionDoc<TClients[TDb]["collections"][X]>>) => Promise<CursorPage<CollectionDoc<TClients[TDb]["collections"][X]>>>;
+    paginateFlexible: <X extends ExtractCollectionNames<TClients, TDb>>(collection: X, baseFilter: FilterInput<CollectionDoc<TClients[TDb]["collections"][X]>>, config?: PaginationConfig) => Promise<PaginationResult<CollectionDoc<TClients[TDb]["collections"][X]>>>;
+};
+
+/**
+ * Schema-driven collection registry.
+ *
+ * Collection names are carried by the schema itself (`s.object({...}, { name })`
+ * or `defineCollection(name, schema, extras)`), so the ORM's `collections` map
+ * is *derived* from the schemas instead of hand-typed. The keys of the derived
+ * map ARE the schema names — a typo'd collection name becomes a type error
+ * everywhere (CRUD, query builder, relations, populate).
+ *
+ *   const users = s.object(
+ *     { _id: s.objectId(), email: s.string() },
+ *     { name: 'users' },
+ *   );
+ *   const orders = defineCollection('orders', s.object({ ... }), {
+ *     indexes: [{ key: { userId: 1 } }],
+ *   });
+ *
+ *   const dbClients = {
+ *     primary: {
+ *       name: 'app',
+ *       collections: defineCollections(users, orders),
+ *     },
+ *   };
+ */
+
+/** An object schema that carries its collection name. */
+type NamedObjectField<N extends string = string> = ObjectField<Record<string, SchemaType>, N> & {
+    name: N;
+};
+/** A collection definition (schema + optional indexes/hooks) that carries its name. */
+type NamedCollectionDefinition<N extends string = string, S extends ObjectField = ObjectField> = CollectionDefinition<S & {
+    name: N;
+}> & {
+    name: N;
+};
+/** Either form accepted by `defineCollections`. */
+type NamedCollection = (ObjectField & {
+    name: string;
+}) | ({
+    schema: ObjectField;
+    indexes?: IndexSpec[];
+    hooks?: HookMap<any>;
+    timestamps?: CollectionTimestamps | boolean;
+} & {
+    name: string;
+});
+/** Extract the carried collection name from a named collection item. */
+type StringName<T> = T extends {
+    name: infer N;
+} ? Extract<N, string> : never;
+type CollectionName<T> = T extends {
+    schema: infer S;
+} ? StringName<S> : StringName<T>;
+/** The value placed in the derived `collections` map for a given item. */
+type CollectionValue<T> = T extends {
+    schema: infer S;
+    indexes?: infer _Ix;
+    hooks?: infer _Hk;
+} ? CollectionDefinition<Extract<S, ObjectField>> : T;
+/** The derived `collections` map type: keyed by each item's carried name. */
+type CollectionMap<T extends readonly NamedCollection[]> = {
+    [K in T[number] as CollectionName<K>]: CollectionValue<K>;
+};
+/**
+ * Attach a collection name to a schema (plus optional indexes/hooks) and return
+ * a `CollectionDefinition`-shaped item. When no extras are needed this is
+ * equivalent to `s.object({...}, { name })`.
+ */
+declare const defineCollection: <N extends string, S extends ObjectField>(name: N, schema: S, extras?: {
+    indexes?: IndexSpec[];
+    hooks?: HookMap<InferDoc<S>>;
+    timestamps?: CollectionTimestamps | boolean;
+}) => NamedCollectionDefinition<N, S>;
+/**
+ * Derive a `collections` map from schemas that carry their own names. Throws on
+ * duplicate names. The returned map's keys are the schema names and its values
+ * are valid `CollectionLike` entries, so it plugs directly into
+ * `DBClientDefinition.collections` with full type inference.
+ */
+declare const defineCollections: <const T extends readonly NamedCollection[]>(...items: T) => CollectionMap<T>;
+
+/** Convert an object schema into a Mongo JSON-schema fragment (no `$jsonSchema` wrapper). */
+declare const toMongoSchema: (schema: ObjectField) => MongoJsonSchema;
+/** Full validator object ready for `createCollection({ validator })` / `collMod`. */
+declare const toMongoValidator: (schema: ObjectField) => {
+    $jsonSchema: MongoJsonSchema;
+};
+
+interface CollectionRegistryEntry {
+    schema?: ObjectField;
+    indexes?: IndexSpec[];
+}
+/** What `syncIndexes` changed on a collection. */
+interface SyncIndexesResult {
+    /** Names of indexes that were created (missing declared indexes). */
+    created: string[];
+    /** Names of indexes that were dropped (undeclared, excluding `_id_`). */
+    dropped: string[];
+}
+interface SchemaOpsOptions {
+    resolveCollectionName: (logical: string) => string;
+    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`.
+ */
+declare const makeSchemaOps: (client: Db, _logger: LoggerLike, opts: SchemaOpsOptions) => {
+    createSchema: (collection: string, createCollectionOptions?: CreateCollectionOptions) => Promise<void>;
+    updateSchema: (collection: string, schema?: ObjectField) => Promise<void>;
+    syncIndexes: (collection: string) => Promise<SyncIndexesResult>;
+};
+
+interface TransactionOpsOptions {
+    migrationCollectionPhysical: string;
+    /** Map driver errors to typed DomainError/InfraError before rethrowing. */
+    wrapMongoErrors?: boolean;
+}
+/**
+ * Transaction + 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>;
+};
+
+/**
+ * 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> & {
+    /**
+     * DataLoader-backed relation population (kills N+1). Each relation is
+     * validated against the schema registry (`collection` / `localField` /
+     * `foreignField` / `through`), and the joined `as` fields are typed.
+     */
+    populate: <const T extends Document, const R extends readonly RelationDef[]>(docs: T[], relations: R & {
+        [K in keyof R]: ValidRelation<TClients, TDb, T, R[K]>;
+    }, options?: PopulateOptions) => Promise<Array<T & JoinedFields<TClients, TDb, R>>>;
+    /** Raw `db()` handle escape hatch. */
+    client: Db;
+    /** Reference to sibling managers (cross-DB). */
+    db: Record<string, unknown>;
+};
+
+/**
+ * Service facade — the composition root. `createMongoService` wires the whole
+ * ORM: it resolves config (`./config.ts`), opens pooled connections
+ * (`./connection.ts`), assembles one `CollectionManager` per database
+ * (`./manager.ts`), and exposes health (`./health.ts`).
+ *
+ * Kept deliberately thin: each concern lives in a sibling module and is only
+ * composed here.
+ */
+
+type MongoService<TClients extends DbClientsDefinition = DbClientsDefinition> = {
+    db: {
+        [K in ExtractDbNames<TClients> as `${K}Client`]: CollectionManager<TClients, K>;
+    };
+    /** Open the pooled MongoClients and build all managers. */
+    makeConnections: (names?: (keyof TClients & string)[]) => Promise<void>;
+    closeConnections: () => Promise<void>;
+    /** Run `fn` over every connected manager (in parallel). */
+    eachDb: <T>(fn: (manager: unknown, dbKey: string) => Promise<T>) => Promise<T[]>;
+    /** Ping every connected database and report per-DB health. */
+    health: () => Promise<HealthReport>;
+    getDbUrl: (name: string) => string;
+    config: {
+        defaultDb: string;
+        migrationDir: string;
+        appName: string;
+    };
+    logger: LoggerLike;
+    ObjectId: typeof ObjectId;
+};
+/**
+ * Assemble the ORM service from a client definition:
+ *
+ *   const service = createMongoService({
+ *     primary: {
+ *       name: 'app',
+ *       dbUrl: process.env.MONGO_URL,
+ *       collectionPrefix: process.env.DB_PREFIX,
+ *       collections: { users: userSchema, orders: { schema: orderSchema, indexes: [...] } },
+ *     },
+ *   });
+ *   await service.makeConnections();
+ *   const users = service.db.primaryClient;
+ *   await users.insertOne('users', { email });
+ *   const page = await users.paginateFlexible('users', {}, { page: 1, limit: 20 });
+ */
+declare const createMongoService: <TClients extends DbClientsDefinition = DbClientsDefinition>(dbClients: TClients, configOverrides?: MongoServiceConfig) => MongoService<TClients>;
+
+interface AggregationMeta {
+    executionTimeMs?: number;
+    indexesUsed?: string[];
+}
+/** Uniform pagination result shape (shared by all list/paginate/search ops). */
+interface PaginationResult<T> {
+    data: T[];
+    totalCount: number;
+    hasNextPage: boolean;
+    hasPrevPage: boolean;
+    currentPage: number;
+    totalPages: number;
+    aggregationMeta?: AggregationMeta;
+}
+declare const buildPaginationResult: <T>(data: T[], totalCount: number, page: number, limit: number) => PaginationResult<T>;
+
+/**
+ * Optional repository layer over a `CollectionManager` — a thin, domain-typed
+ * convenience wrapper. The op-based core API is unchanged; a repository just
+ * binds a manager + collection name so call sites don't repeat the collection
+ * literal, and adds small ergonomic helpers (`getById`, `getByIds`,
+ * `updateVersioned`, `exists`, …).
+ *
+ * There is deliberately NO change tracking / unit-of-work: `getById` → mutate →
+ * `update`/`updateVersioned` is explicit, matching the core op semantics. All
+ * perf features (cache, dedup, batching, populate) and collection hooks /
+ * timestamps apply transparently because every method delegates to the manager.
+ */
+
+interface RepositoryOptions {
+    /** Default `findMany` limit (defaults to the ORM's `DEFAULT_FIND_LIMIT`). */
+    limit?: number;
+}
+/** Repository for one collection — type is derived from the manager + name. */
+type Repository<TClients extends DbClientsDefinition, TDb extends ExtractDbNames<TClients>, C extends ExtractCollectionNames<TClients, TDb>> = RepositoryFor<TClients, TDb, C, ExtractCollectionType<TClients, TDb, C>>;
+type RepositoryFor<TClients extends DbClientsDefinition, TDb extends ExtractDbNames<TClients>, C extends ExtractCollectionNames<TClients, TDb>, Doc extends Document> = {
+    readonly collection: C;
+    /** The underlying manager — escape hatch to any op. */
+    readonly manager: CollectionManager<TClients, TDb>;
+    /** Fetch one doc by primary key, or `null`. */
+    getById(id: Doc['_id'], options?: FindQueryOptions<Doc>): Promise<Doc | null>;
+    /** Fetch many docs by primary key (`$in`). */
+    getByIds(ids: readonly Doc['_id'][], options?: FindQueryOptions<Doc>): Promise<Doc[]>;
+    /** Fetch one doc by filter, or `null`. */
+    findOne(filter?: FilterInput<Doc>, options?: FindQueryOptions<Doc>): Promise<Doc | null>;
+    /** Fetch one doc by filter or throw `NOT_FOUND`. */
+    findOneOrFail(filter?: FilterInput<Doc>, options?: FindQueryOptions<Doc>): Promise<Doc>;
+    /** Fetch many docs (default limit from `RepositoryOptions.limit`). */
+    findMany(filter?: FilterInput<Doc>, options?: FindQueryOptions<Doc>): Promise<Doc[]>;
+    /** Fetch many non-soft-deleted docs. */
+    findActive(filter?: FilterInput<Doc>, options?: FindQueryOptions<Doc>): Promise<Doc[]>;
+    /** Count docs matching a filter. */
+    count(filter?: FilterInput<Doc>, options?: QueryOptions): Promise<number>;
+    /** Whether at least one doc matches. */
+    exists(filter?: FilterInput<Doc>, options?: FindQueryOptions<Doc>): Promise<boolean>;
+    /** Distinct values of `field`. */
+    distinct<K extends keyof Doc>(field: K, filter?: FilterInput<Doc>, options?: FindQueryOptions<Doc>): Promise<Array<Doc[K]>>;
+    /** Insert one doc. */
+    create(doc: InsertInput<Doc>, options?: InsertOneOptions & QueryOptions): Promise<InsertOneResult<Doc>>;
+    /** Insert many docs. */
+    createMany(docs: readonly InsertInput<Doc>[], options?: QueryOptions): Promise<InsertManyResult<Doc>>;
+    /** Update one doc by primary key. */
+    update(id: Doc['_id'], patch: UpdateInput<Doc>, options?: UpdateOptions & QueryOptions): Promise<UpdateResult<Doc>>;
+    /** Optimistic-lock update by primary key (`__v` CAS). */
+    updateVersioned(id: Doc['_id'], patch: UpdateInput<Doc>, options?: FindOneAndUpdateOptions & QueryOptions): Promise<VersionedUpdateResult<Doc>>;
+    /** Delete one doc by primary key. */
+    deleteById(id: Doc['_id'], options?: QueryOptions): Promise<DeleteResult>;
+    /** Soft-delete one doc by primary key (sets `deletedAt`). */
+    softDelete(id: Doc['_id'], options?: QueryOptions): Promise<UpdateResult<Doc>>;
+    /** `$facet` pagination with totals (one round trip). */
+    page(filter: FilterInput<Doc>, config?: PaginationConfig): Promise<PaginationResult<Doc>>;
+    /** Keyset/cursor pagination (O(log n), no totals). */
+    pageCursor(filter: FilterInput<Doc>, config: CursorPaginationConfig<Doc>): Promise<CursorPage<Doc>>;
+    /** Type-safe chained aggregation builder. */
+    pipeline(options?: QueryOptions): PipelineBuilder<TClients, TDb, Doc>;
+    /** Callback aggregation over a typed stage builder. */
+    aggregate(stages: (s: AggregationStages<Doc, TClients, TDb>) => Document[], options?: QueryOptions): Promise<AggregationCursor<Document>>;
+    /** DataLoader-batched relation population (no N+1). */
+    populate<const T extends Document, const R extends readonly RelationDef[]>(docs: T[], relations: R & {
+        [K in keyof R]: ValidRelation<TClients, TDb, T, R[K]>;
+    }, options?: PopulateOptions): Promise<Array<T & JoinedFields<TClients, TDb, R>>>;
+    /** Change stream (caller-owned — attach `error` listener + close). */
+    watch(pipeline?: Document[], options?: ChangeStreamOptions): ChangeStream<Doc>;
+};
+/**
+ * Bind a repository to a manager + collection. `Doc` is inferred from the
+ * collection name — no `<TDoc>` at call sites.
+ */
+declare const createRepository: <TClients extends DbClientsDefinition, TDb extends ExtractDbNames<TClients>, C extends ExtractCollectionNames<TClients, TDb>>(manager: CollectionManager<TClients, TDb>, collection: C, options?: RepositoryOptions) => Repository<TClients, TDb, C>;
+
+interface ResolveCollectionConfig {
+    /** Prepended to every physical name: `prefix + separator + logical`. */
+    collectionPrefix?: string;
+    /** Joins `collectionPrefix` and the logical name (default `-`). */
+    collectionPrefixSeparator?: string;
+    /** Per-logical-name physical overrides; wins over the prefix rule. */
+    collectionPhysicalNames?: Partial<Record<string, string>>;
+}
+/**
+ * Resolve a logical collection name → physical collection name.
+ *  - explicit `collectionPhysicalNames[logical]` wins
+ *  - otherwise `prefix + separator + logical`
+ *  - no prefix → identity
+ */
+declare const createResolveCollectionName: (config: ResolveCollectionConfig) => (logical: string) => string;
+
+/**
+ * Normalize a Mongo connection string so performance/reliability defaults are
+ * 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
+ */
+declare const normalizeMongoUrl: (rawUrl: string) => string;
+
+/** Default cap for list/pagination limits (mirrors sdk-db). */
+declare const DEFAULT_MAX_LIMIT = 1000;
+/** Default limit applied to `findMany` when none is provided. */
+declare const DEFAULT_FIND_LIMIT = 100;
+/**
+ * Hard cap for a single `insertMany` / `bulkWrite` / `bulkUpsert` call (the
+ * driver splits at 100k; anything above is almost certainly an unbounded caller
+ * array). Above this the ORM throws `BadRequest` instead of spiking memory.
+ */
+declare const MAX_BATCH_OPS = 100000;
+
+/**
+ * Keyset (cursor) pagination helpers — pure, DB-agnostic.
+ *
+ * Unlike offset pagination, keyset pagination filters on the *last seen* row's
+ * sort values, so it stays O(log n) regardless of page depth (no deep `$skip`)
+ * and is stable under concurrent inserts. It cannot report a total count —
+ * use `paginateFlexible` ($facet) when you need totals.
+ *
+ * Requirement: every sort key (and the `_id` tiebreaker) should exist on every
+ * document for deterministic ordering, since the boundary comparison relies on
+ * them.
+ */
+
+interface KeysetCursor {
+    /** The sort spec this cursor belongs to (used to reject mismatched cursors). */
+    sort: Record<string, 1 | -1>;
+    /** Boundary field values, in sort-key order. */
+    values: unknown[];
+}
+/** Base64url-encode a cursor. The payload is opaque to callers. */
+declare const encodeCursor: (cursor: KeysetCursor) => string;
+/** Decode + validate an opaque cursor. Throws on malformed input. */
+declare const decodeCursor: (cursor: string) => KeysetCursor;
+/**
+ * Build the keyset filter for the next page.
+ *
+ * Sort keys `[k1(d1), k2(d2), ...]` with boundary values `[v1, v2, ...]` produce
+ * the standard disjunction of prefix-equalities plus a strict comparison on the
+ * next key:
+ *
+ *   k1 ≻ v1  OR  (k1 = v1 AND k2 ≻ v2)  OR  ...  OR  (k1 = v1 AND ... AND kn ≻ vn)
+ *
+ * where `≻` is `>` for ascending keys and `<` for descending keys when
+ * `direction` is `'after'` (inverted for `'before'`). `_id` is the natural
+ * unique tiebreaker.
+ */
+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`).
+ */
+declare const mergeMongoFilters: <T extends Document>(...parts: Array<Filter<T> | undefined>) => Filter<T>;
+
+interface CrudListQuery {
+    page?: number;
+    limit?: number;
+}
+interface NormalizedPagination {
+    page: number;
+    limit: number;
+    offset: number;
+}
+/**
+ * Normalize + validate page/limit. Pure — no DB knowledge.
+ *  - `page` is floored to >= 1
+ *  - `limit` must be within [1, maxLimit] or a `BadRequest` is thrown
+ */
+declare const normalizePageLimit: (query: CrudListQuery, maxLimit: number, defaults?: {
+    page?: number;
+    limit?: number;
+}) => NormalizedPagination;
+
+/**
+ * Soft-delete support. A soft-deleted row is one where `deletedAt` exists and is
+ * non-null. Mirrors sdk-db's `crud-shared/soft-delete.ts`.
+ */
+declare const buildMongoActiveFilter: () => Filter<Document>;
+/**
+ * Merge a caller filter with the soft-delete "active" filter.
+ *  - softDelete=false → the caller filter unchanged
+ *  - empty/absent filter → active filter alone
+ *  - otherwise → `{ $and: [filter, active] }`
+ */
+declare const mergeMongoActiveFilter: <T extends Document>(softDelete: boolean, filter?: FilterInput<T> | Filter<T>) => Filter<T>;
+
+/** Remove the `_id` field from a document (returns the same object when absent). */
+declare const stripDocumentId: <T extends Record<string, unknown>>(doc: T) => Omit<T, "_id">;
+/** Remove an arbitrary primary key field from an object. */
+declare const stripPrimaryKey: <T extends Record<string, unknown>, K extends keyof T & string>(patch: T, key: K) => Omit<T, K>;
+
+interface MongoToolkitOptions extends MongoServiceConfig {
+}
+/**
+ * Convenience bundle: service + migration runner sharing one config.
+ *
+ *   const toolkit = createMongoToolkit({ primary: { name, collections } });
+ *   await toolkit.service.makeConnections();
+ *   await toolkit.migrations.up();
+ */
+declare const createMongoToolkit: <TClients extends DbClientsDefinition = DbClientsDefinition>(dbClients: TClients, options?: MongoToolkitOptions) => {
+    service: MongoService<TClients>;
+    migrations: MongoMigrationRunner;
+};
+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 };