monsqlize 2.0.6 → 3.1.0

package/dist/types/monsqlize.d.mts

@@ -1,4 +1,5 @@
 import type { LoggerLike } from './base.mjs';
+import type { SchemaDslRuntime, SchemaDslRuntimeOptions } from 'schema-dsl/runtime';
 
 /**
  * SSH tunnel configuration for connecting through a bastion host.
@@ -31,7 +32,8 @@ export interface SSHConfig {
     localPort?: number;
 }
 
-import type { Collection, DbAccessor, HealthView } from './collection.mjs';
+import type { Collection, CursorValueNormalizer, CursorValueType, DbAccessor, HealthView } from './collection.mjs';
+import type { DataTaskJobError } from './data-tasks.mjs';
 import type { Lock, LockOptions, LockStats } from './lock.mjs';
 import type { ModelAutoIndexOptions, ModelEnsureAllIndexesOptions, ModelIndexEnsureSummary, ModelInstance } from './model.mjs';
 import type { MongoConnectConfig } from './mongodb.mjs';
@@ -68,6 +70,61 @@ import type { SlowQueryLogConfigInput, SlowQueryLogEntry, SlowQueryLogFilter, Sl
 import type { ChangeStreamSyncManager, SyncConfig, SyncStats } from './sync.mjs';
 import type { Transaction, TransactionOptions, TransactionStats } from './transaction.mjs';
 
+/** Write path policy mode. `allow-both` preserves the existing collection and model write behavior. */
+export type WritePathPolicyMode = 'allow-both' | 'model-only';
+
+/** Controls whether native raw access is available under a write path policy. */
+export type WritePathPolicyRawMode = 'inherit' | 'allow' | 'block';
+
+/** Controls whether collection/database management writes are available under a write path policy. */
+export type WritePathPolicyManagementMode = 'inherit' | 'allow' | 'block';
+
+/** Controls violation handling; `warn` logs and allows for migration observation. */
+export type WritePathPolicyViolationAction = 'throw' | 'warn';
+
+/** Per-namespace write path policy rule. */
+export interface WritePathPolicyRule {
+    /** Write policy mode. Default: `allow-both`. */
+    mode?: WritePathPolicyMode;
+    /** Raw native access policy. `inherit` allows in `allow-both` and blocks in `model-only`. */
+    raw?: WritePathPolicyRawMode;
+    /** Management write policy. `inherit` allows model management and blocks external management in `model-only`. */
+    management?: WritePathPolicyManagementMode;
+    /** Violation action. Default: `throw`. */
+    onViolation?: WritePathPolicyViolationAction;
+}
+
+/** Runtime write path policy configuration. */
+export interface WritePathPolicyOptions {
+    /**
+     * Default rule applied when no namespace override matches.
+     * Omit this option to preserve existing behavior (`allow-both`).
+     */
+    default?: WritePathPolicyMode | WritePathPolicyRule;
+    /**
+     * Namespace overrides matched in this order: `iid`, `pool:db.collection`,
+     * `db.collection`, then `collection`.
+     */
+    namespaces?: Record<string, WritePathPolicyMode | WritePathPolicyRule>;
+}
+
+export type MonSQLizeSchemaDslRuntime = Pick<
+    SchemaDslRuntime,
+    's' | 'dsl' | 'validate' | 'registerExtensions' | 'dispose'
+>;
+
+/** schema-dsl runtime integration. Omit to let monSQLize create one isolated runtime per MonSQLize instance. */
+export interface SchemaDslRuntimeConfig {
+    /** Disable model schema-dsl compilation and validation when false. Default: true. */
+    enabled?: boolean;
+    /** Existing schema-dsl runtime instance. monSQLize will use it but will not dispose it. */
+    runtime?: MonSQLizeSchemaDslRuntime;
+    /** Options passed to `createRuntime()` when monSQLize owns the runtime. */
+    options?: SchemaDslRuntimeOptions;
+    /** Extension definitions registered on the selected runtime before model schema compilation. */
+    extensions?: readonly unknown[];
+}
+
 export interface MonSQLizeOptions {
     type?: 'mongodb';
     databaseName?: string;
@@ -82,7 +139,7 @@ export interface MonSQLizeOptions {
      * - A plain config object. Recognised fields:
      *     `maxEntries` / `maxSize` (v1 alias), `maxMemory`, `defaultTtl` / `ttl` (v1 alias),
      *     `enableStats`, `enableTags`, `cleanupInterval`, `enabled`,
-     *     `autoInvalidate` (v1 alias for `cacheAutoInvalidate`)
+     *     `autoInvalidate` (broad write invalidation, disabled by default)
      */
     cache?: CacheLike | MemoryCache | MultiLevelCacheOptions | {
         /** Maximum number of entries; v2 name. Alias: maxSize (v1). */
@@ -103,20 +160,24 @@ export interface MonSQLizeOptions {
         cleanupInterval?: number;
         /** Disable cache entirely when false. Default: true. */
         enabled?: boolean;
-        /** @deprecated Use top-level `cacheAutoInvalidate`. v1 alias: auto-invalidate on writes. */
+        /** Broadly invalidate collection query caches after successful writes. Default: false. */
         autoInvalidate?: boolean;
         /**
          * Distributed cache invalidation via Redis Pub/Sub.
          * When configured, broadcasts `delPattern` events to all other connected instances.
-         * `ioredis` is installed with monSQLize; this block only enables and configures Redis usage.
+         * Provide `redisUrl` or an existing Redis-like `redis` instance when enabling this block.
          * @since v2.0.0
          */
         distributed?: {
-            /** Redis URL for the Pub/Sub connection. Defaults to `"redis://localhost:6379"`. */
+            /** Redis URL for the Pub/Sub connection. */
             redisUrl?: string;
+            /** Alias for `redisUrl`. */
+            url?: string;
+            /** Alias for `redisUrl`. */
+            uri?: string;
             /** Existing ioredis `Redis` instance to use for publishing. */
             redis?: unknown;
-            /** Pub/Sub channel name shared across instances. Default: `"cache-hub:invalidate"`. */
+            /** Pub/Sub channel name shared across instances. Default: `"monsqlize:cache:invalidate"`. */
             channel?: string;
             /** Unique ID for this instance; used to filter self-published messages. Auto-generated if omitted. */
             instanceId?: string;
@@ -126,6 +187,8 @@ export interface MonSQLizeOptions {
         [key: string]: unknown;
     };
     logger?: LoggerLike | null;
+    /** Isolated schema-dsl runtime configuration for Model schema compilation and validation. */
+    schemaDsl?: false | SchemaDslRuntimeConfig;
     pools?: PoolConfig[];
     poolStrategy?: PoolStrategy;
     poolFallback?: ConnectionPoolManagerOptions['poolFallback'];
@@ -148,12 +211,27 @@ export interface MonSQLizeOptions {
         lockMaxDuration?: number;
         lockCleanupInterval?: number;
         maxStatsSamples?: number;
+        /**
+         * v1 compatibility placeholder. The current v2 transaction cache lock is process-local
+         * and this option is not wired into distributed cache-lock interception.
+         *
+         * Use `DistributedCacheLockManager` explicitly for business critical sections, pair it
+         * with idempotency/fencing, or disable cache where cross-instance strict consistency is
+         * required.
+         *
+         * @deprecated This option is retained for compatibility only and does not enable a
+         * distributed transaction cache lock in the v2 runtime.
+         */
         distributedLock?: Record<string, unknown>;
     };
     /** Global query timeout in milliseconds applied to all find/aggregate operations. Default: 2000. @since v1.3.0 */
     maxTimeMS?: number;
-    /** Default limit for find() when caller does not specify one. Default: 10. @since v1.3.0 */
+    /** Default limit for find() when caller does not specify one. Default: 500. @since v1.3.0 */
     findLimit?: number;
+    /** Maximum allowed explicit limit for find(). limit(0) keeps MongoDB's unlimited semantics. Default: 10000. @since v3.0.0 */
+    findMaxLimit?: number;
+    /** Maximum allowed explicit skip for find() and offsetJump. Default: 50000. @since v3.0.0 */
+    findMaxSkip?: number;
     /** Slow query threshold in milliseconds; populates slowQueryLog.filter.minExecutionTimeMs when slowQueryLog is enabled. Default: 500. @since v1.3.0 */
     slowQueryMs?: number;
     /** Maximum allowed limit for findPage() operations. Requests exceeding this cap are silently clamped. Default: 500. @since v1.3.0 */
@@ -162,9 +240,17 @@ export interface MonSQLizeOptions {
     namespace?: { scope?: 'database' | 'connection'; instanceId?: string; };
     /** HMAC-SHA256 secret used to sign and verify cursor tokens returned by findPage(). @since v1.3.0 */
     cursorSecret?: string;
+    /** Require cursorSecret before findPage can emit or consume cursor tokens. Default: false. @since v3.0.0 */
+    requireCursorSecret?: boolean;
+    /** Controls startup warning when cursorSecret is missing. Default: 'production'. @since v3.0.0 */
+    cursorSecretWarning?: 'off' | 'production' | 'always';
+    /** Global cursor value type hints used when findPage decodes after/before tokens. @since v3.0.0 */
+    cursorTypes?: Record<string, CursorValueType>;
+    /** Global cursor value normalizer used when findPage decodes after/before tokens. @since v3.0.0 */
+    cursorValueNormalizer?: CursorValueNormalizer;
     /** Logging tag configuration applied to slow-query event payloads. @since v1.3.0 */
     log?: { slowQueryTag?: { event?: string; code?: string;[key: string]: unknown }; formatSlowQuery?: (meta: unknown) => unknown; };
-    /** Auto-convert 24-character hex strings to ObjectId in query filters. Pass a field map to selectively enable per field. Default: true for mongodb type (pass `false` to disable). @since v1.3.0 */
+    /** Auto-convert valid 24-character hex strings to ObjectId across query/write paths. Pass `false` to disable, or use `excludeFields`, `maxDepth`, or `{ field: false }` escape hatches. Default: true for mongodb type. @since v1.3.0 */
     autoConvertObjectId?: boolean | {
         enabled?: boolean;
         excludeFields?: string[];
@@ -178,8 +264,13 @@ export interface MonSQLizeOptions {
     models?: string | { path: string; pattern?: string; recursive?: boolean; };
     /** Global automatic model index creation control. Defaults to true for backward compatibility. */
     autoIndex?: ModelAutoIndexOptions;
-    /** Auto-invalidate cache on write operations. @since v1.3.0 */
+    /** Compatibility alias for `cache.autoInvalidate`. Prefer the nested cache option. */
     cacheAutoInvalidate?: boolean;
+    /**
+     * Optional write path governance. By default both collection and model write APIs remain available.
+     * Use `model-only` per default or namespace to require writes through the model API.
+     */
+    writePathPolicy?: WritePathPolicyOptions;
 }
 
 export interface MonSQLizeInstance {
@@ -276,21 +367,24 @@ export interface MonSQLizeInstance {
      */
     withTransaction<T>(callback: (transaction: Transaction) => Promise<T>, options?: TransactionOptions): Promise<T>;
     /**
-     * Execute a callback while holding a distributed lock; the lock is released automatically on completion.
+     * Execute a callback while holding a legacy monSQLize lock; the lock is released automatically on completion.
+     * @deprecated Business locks are retained for compatibility. Prefer application/framework-level locking.
      * @param key Unique lock identifier key.
      * @param callback Async callback executed while the lock is held.
      * @param options Optional lock options.
      */
     withLock<T>(key: string, callback: () => Promise<T>, options?: LockOptions): Promise<T>;
     /**
-     * Acquire a distributed lock, blocking until it is available or the timeout is reached.
+     * Acquire a legacy monSQLize lock, blocking until it is available or the timeout is reached.
+     * @deprecated Business locks are retained for compatibility. Prefer application/framework-level locking.
      * @param key Unique lock identifier key.
      * @param options Optional lock options.
      * @returns The acquired lock instance.
      */
     acquireLock(key: string, options?: LockOptions): Promise<Lock>;
     /**
-     * Try to acquire a distributed lock without blocking; returns `null` if the lock is already held.
+     * Try to acquire a legacy monSQLize lock without blocking; returns `null` if the lock is already held.
+     * @deprecated Business locks are retained for compatibility. Prefer application/framework-level locking.
      * @param key Unique lock identifier key.
      * @param options Optional lock options (`retryTimes` is not supported).
      * @returns The acquired lock instance, or `null` if unavailable.
@@ -300,27 +394,29 @@ export interface MonSQLizeInstance {
     getSyncManager(): ChangeStreamSyncManager | null;
     /** Return the slow-query log manager; `null` when slow-query logging is not enabled. */
     getSlowQueryLogManager(): SlowQueryLogManager | null;
-    /** Return the Saga orchestrator instance. */
+    /** @deprecated Saga APIs are retained for compatibility. Prefer application/framework-level workflow orchestration. */
     getSagaOrchestrator(): SagaOrchestrator;
-    /** Shorthand alias for `getSagaOrchestrator()`. */
+    /** @deprecated Saga APIs are retained for compatibility. Prefer application/framework-level workflow orchestration. */
     saga(): SagaOrchestrator;
     /**
      * Register a Saga definition.
+     * @deprecated Saga APIs are retained for compatibility. Prefer application/framework-level workflow orchestration.
      * @param definition Saga definition object containing steps and compensation logic.
      */
     defineSaga(definition: SagaDefinition): Promise<SagaDefinition>;
     /**
      * Execute the named registered Saga.
+     * @deprecated Saga APIs are retained for compatibility. Prefer application/framework-level workflow orchestration.
      * @param name Saga name.
      * @param data Initial data passed into the Saga.
      * @returns The Saga execution result.
      */
     executeSaga(name: string, data: unknown): Promise<SagaResult>;
-    /** List all registered Saga names. */
+    /** @deprecated Saga APIs are retained for compatibility. Prefer application/framework-level workflow orchestration. */
     listSagas(): string[];
     /** Return aggregate transaction statistics; `null` before transaction capability initialization. */
     getTransactionStats(): TransactionStats | null;
-    /** Return Saga execution statistics (success / failure / compensation counts, etc.). */
+    /** @deprecated Saga APIs are retained for compatibility. Prefer application/framework-level workflow orchestration. */
     getSagaStats(): SagaStats;
     /** Return distributed cache invalidator statistics; `null` when distributed invalidation is not enabled. */
     getDistributedCacheInvalidatorStats(): DistributedCacheInvalidatorStats | null;
@@ -452,17 +548,26 @@ export default class MonSQLize implements MonSQLizeInstance {
     ensureModelIndexes(options?: ModelEnsureAllIndexesOptions): Promise<ModelIndexEnsureSummary>;
     startSession(options?: TransactionOptions): Promise<Transaction>;
     withTransaction<T>(callback: (transaction: Transaction) => Promise<T>, options?: TransactionOptions): Promise<T>;
+    /** @deprecated Business locks are retained for compatibility. Prefer application/framework-level locking. */
     withLock<T>(key: string, callback: () => Promise<T>, options?: LockOptions): Promise<T>;
+    /** @deprecated Business locks are retained for compatibility. Prefer application/framework-level locking. */
     acquireLock(key: string, options?: LockOptions): Promise<Lock>;
+    /** @deprecated Business locks are retained for compatibility. Prefer application/framework-level locking. */
     tryAcquireLock(key: string, options?: Omit<LockOptions, 'retryTimes'>): Promise<Lock | null>;
     getSyncManager(): ChangeStreamSyncManager | null;
     getSlowQueryLogManager(): SlowQueryLogManager | null;
+    /** @deprecated Saga APIs are retained for compatibility. Prefer application/framework-level workflow orchestration. */
     getSagaOrchestrator(): SagaOrchestrator;
+    /** @deprecated Saga APIs are retained for compatibility. Prefer application/framework-level workflow orchestration. */
     saga(): SagaOrchestrator;
+    /** @deprecated Saga APIs are retained for compatibility. Prefer application/framework-level workflow orchestration. */
     defineSaga(definition: SagaDefinition): Promise<SagaDefinition>;
+    /** @deprecated Saga APIs are retained for compatibility. Prefer application/framework-level workflow orchestration. */
     executeSaga(name: string, data: unknown): Promise<SagaResult>;
+    /** @deprecated Saga APIs are retained for compatibility. Prefer application/framework-level workflow orchestration. */
     listSagas(): string[];
     getTransactionStats(): TransactionStats | null;
+    /** @deprecated Saga APIs are retained for compatibility. Prefer application/framework-level workflow orchestration. */
     getSagaStats(): SagaStats;
     getDistributedCacheInvalidatorStats(): DistributedCacheInvalidatorStats | null;
     startSync(): Promise<void>;
@@ -505,7 +610,15 @@ export default class MonSQLize implements MonSQLizeInstance {
     static hasExpressionInObject: typeof hasExpressionInObject;
     static hasExpressionInPipeline: typeof hasExpressionInPipeline;
     static createRedisCacheAdapter: typeof createRedisCacheAdapter;
+    /**
+     * @deprecated Retained for v1 compatibility. Non-database function caching is no longer a recommended monSQLize feature path;
+     * use `cache-hub` directly or an application-owned cache layer for new generic function-cache usage.
+     */
     static withCache: typeof withCache;
+    /**
+     * @deprecated Retained for v1 compatibility. Non-database function caching is no longer a recommended monSQLize feature path;
+     * use `cache-hub` directly or an application-owned cache layer for new generic function-cache usage.
+     */
     static FunctionCache: typeof FunctionCache;
     static adaptLegacyCacheLike: typeof adaptLegacyCacheLike;
     static MultiLevelCache: typeof MultiLevelCache;
@@ -517,6 +630,7 @@ export default class MonSQLize implements MonSQLizeInstance {
     static SlowQueryLogMemoryStorage: typeof SlowQueryLogMemoryStorage;
     static MongoDBSlowQueryLogStorage: typeof MongoDBSlowQueryLogStorage;
     static BatchQueue: typeof BatchQueue;
+    static DataTaskJobError: typeof DataTaskJobError;
     static generateQueryHash: typeof generateQueryHash;
     static SagaOrchestrator: typeof SagaOrchestrator;
 }

package/dist/types/monsqlize.d.ts

@@ -1,4 +1,5 @@
 import type { LoggerLike } from './base';
+import type { SchemaDslRuntime, SchemaDslRuntimeOptions } from 'schema-dsl/runtime';
 
 /**
  * SSH tunnel configuration for connecting through a bastion host.
@@ -31,7 +32,8 @@ export interface SSHConfig {
     localPort?: number;
 }
 
-import type { Collection, DbAccessor, HealthView } from './collection';
+import type { Collection, CursorValueNormalizer, CursorValueType, DbAccessor, HealthView } from './collection';
+import type { DataTaskJobError } from './data-tasks';
 import type { Lock, LockOptions, LockStats } from './lock';
 import type { ModelAutoIndexOptions, ModelEnsureAllIndexesOptions, ModelIndexEnsureSummary, ModelInstance } from './model';
 import type { MongoConnectConfig } from './mongodb';
@@ -68,6 +70,61 @@ import type { SlowQueryLogConfigInput, SlowQueryLogEntry, SlowQueryLogFilter, Sl
 import type { ChangeStreamSyncManager, SyncConfig, SyncStats } from './sync';
 import type { Transaction, TransactionOptions, TransactionStats } from './transaction';
 
+/** Write path policy mode. `allow-both` preserves the existing collection and model write behavior. */
+export type WritePathPolicyMode = 'allow-both' | 'model-only';
+
+/** Controls whether native raw access is available under a write path policy. */
+export type WritePathPolicyRawMode = 'inherit' | 'allow' | 'block';
+
+/** Controls whether collection/database management writes are available under a write path policy. */
+export type WritePathPolicyManagementMode = 'inherit' | 'allow' | 'block';
+
+/** Controls violation handling; `warn` logs and allows for migration observation. */
+export type WritePathPolicyViolationAction = 'throw' | 'warn';
+
+/** Per-namespace write path policy rule. */
+export interface WritePathPolicyRule {
+    /** Write policy mode. Default: `allow-both`. */
+    mode?: WritePathPolicyMode;
+    /** Raw native access policy. `inherit` allows in `allow-both` and blocks in `model-only`. */
+    raw?: WritePathPolicyRawMode;
+    /** Management write policy. `inherit` allows model management and blocks external management in `model-only`. */
+    management?: WritePathPolicyManagementMode;
+    /** Violation action. Default: `throw`. */
+    onViolation?: WritePathPolicyViolationAction;
+}
+
+/** Runtime write path policy configuration. */
+export interface WritePathPolicyOptions {
+    /**
+     * Default rule applied when no namespace override matches.
+     * Omit this option to preserve existing behavior (`allow-both`).
+     */
+    default?: WritePathPolicyMode | WritePathPolicyRule;
+    /**
+     * Namespace overrides matched in this order: `iid`, `pool:db.collection`,
+     * `db.collection`, then `collection`.
+     */
+    namespaces?: Record<string, WritePathPolicyMode | WritePathPolicyRule>;
+}
+
+export type MonSQLizeSchemaDslRuntime = Pick<
+    SchemaDslRuntime,
+    's' | 'dsl' | 'validate' | 'registerExtensions' | 'dispose'
+>;
+
+/** schema-dsl runtime integration. Omit to let monSQLize create one isolated runtime per MonSQLize instance. */
+export interface SchemaDslRuntimeConfig {
+    /** Disable model schema-dsl compilation and validation when false. Default: true. */
+    enabled?: boolean;
+    /** Existing schema-dsl runtime instance. monSQLize will use it but will not dispose it. */
+    runtime?: MonSQLizeSchemaDslRuntime;
+    /** Options passed to `createRuntime()` when monSQLize owns the runtime. */
+    options?: SchemaDslRuntimeOptions;
+    /** Extension definitions registered on the selected runtime before model schema compilation. */
+    extensions?: readonly unknown[];
+}
+
 export interface MonSQLizeOptions {
     type?: 'mongodb';
     databaseName?: string;
@@ -82,7 +139,7 @@ export interface MonSQLizeOptions {
      * - A plain config object. Recognised fields:
      *     `maxEntries` / `maxSize` (v1 alias), `maxMemory`, `defaultTtl` / `ttl` (v1 alias),
      *     `enableStats`, `enableTags`, `cleanupInterval`, `enabled`,
-     *     `autoInvalidate` (v1 alias for `cacheAutoInvalidate`)
+     *     `autoInvalidate` (broad write invalidation, disabled by default)
      */
     cache?: CacheLike | MemoryCache | MultiLevelCacheOptions | {
         /** Maximum number of entries; v2 name. Alias: maxSize (v1). */
@@ -103,20 +160,24 @@ export interface MonSQLizeOptions {
         cleanupInterval?: number;
         /** Disable cache entirely when false. Default: true. */
         enabled?: boolean;
-        /** @deprecated Use top-level `cacheAutoInvalidate`. v1 alias: auto-invalidate on writes. */
+        /** Broadly invalidate collection query caches after successful writes. Default: false. */
         autoInvalidate?: boolean;
         /**
          * Distributed cache invalidation via Redis Pub/Sub.
          * When configured, broadcasts `delPattern` events to all other connected instances.
-         * `ioredis` is installed with monSQLize; this block only enables and configures Redis usage.
+         * Provide `redisUrl` or an existing Redis-like `redis` instance when enabling this block.
          * @since v2.0.0
          */
         distributed?: {
-            /** Redis URL for the Pub/Sub connection. Defaults to `"redis://localhost:6379"`. */
+            /** Redis URL for the Pub/Sub connection. */
             redisUrl?: string;
+            /** Alias for `redisUrl`. */
+            url?: string;
+            /** Alias for `redisUrl`. */
+            uri?: string;
             /** Existing ioredis `Redis` instance to use for publishing. */
             redis?: unknown;
-            /** Pub/Sub channel name shared across instances. Default: `"cache-hub:invalidate"`. */
+            /** Pub/Sub channel name shared across instances. Default: `"monsqlize:cache:invalidate"`. */
             channel?: string;
             /** Unique ID for this instance; used to filter self-published messages. Auto-generated if omitted. */
             instanceId?: string;
@@ -126,6 +187,8 @@ export interface MonSQLizeOptions {
         [key: string]: unknown;
     };
     logger?: LoggerLike | null;
+    /** Isolated schema-dsl runtime configuration for Model schema compilation and validation. */
+    schemaDsl?: false | SchemaDslRuntimeConfig;
     pools?: PoolConfig[];
     poolStrategy?: PoolStrategy;
     poolFallback?: ConnectionPoolManagerOptions['poolFallback'];
@@ -148,12 +211,27 @@ export interface MonSQLizeOptions {
         lockMaxDuration?: number;
         lockCleanupInterval?: number;
         maxStatsSamples?: number;
+        /**
+         * v1 compatibility placeholder. The current v2 transaction cache lock is process-local
+         * and this option is not wired into distributed cache-lock interception.
+         *
+         * Use `DistributedCacheLockManager` explicitly for business critical sections, pair it
+         * with idempotency/fencing, or disable cache where cross-instance strict consistency is
+         * required.
+         *
+         * @deprecated This option is retained for compatibility only and does not enable a
+         * distributed transaction cache lock in the v2 runtime.
+         */
         distributedLock?: Record<string, unknown>;
     };
     /** Global query timeout in milliseconds applied to all find/aggregate operations. Default: 2000. @since v1.3.0 */
     maxTimeMS?: number;
-    /** Default limit for find() when caller does not specify one. Default: 10. @since v1.3.0 */
+    /** Default limit for find() when caller does not specify one. Default: 500. @since v1.3.0 */
     findLimit?: number;
+    /** Maximum allowed explicit limit for find(). limit(0) keeps MongoDB's unlimited semantics. Default: 10000. @since v3.0.0 */
+    findMaxLimit?: number;
+    /** Maximum allowed explicit skip for find() and offsetJump. Default: 50000. @since v3.0.0 */
+    findMaxSkip?: number;
     /** Slow query threshold in milliseconds; populates slowQueryLog.filter.minExecutionTimeMs when slowQueryLog is enabled. Default: 500. @since v1.3.0 */
     slowQueryMs?: number;
     /** Maximum allowed limit for findPage() operations. Requests exceeding this cap are silently clamped. Default: 500. @since v1.3.0 */
@@ -162,9 +240,17 @@ export interface MonSQLizeOptions {
     namespace?: { scope?: 'database' | 'connection'; instanceId?: string; };
     /** HMAC-SHA256 secret used to sign and verify cursor tokens returned by findPage(). @since v1.3.0 */
     cursorSecret?: string;
+    /** Require cursorSecret before findPage can emit or consume cursor tokens. Default: false. @since v3.0.0 */
+    requireCursorSecret?: boolean;
+    /** Controls startup warning when cursorSecret is missing. Default: 'production'. @since v3.0.0 */
+    cursorSecretWarning?: 'off' | 'production' | 'always';
+    /** Global cursor value type hints used when findPage decodes after/before tokens. @since v3.0.0 */
+    cursorTypes?: Record<string, CursorValueType>;
+    /** Global cursor value normalizer used when findPage decodes after/before tokens. @since v3.0.0 */
+    cursorValueNormalizer?: CursorValueNormalizer;
     /** Logging tag configuration applied to slow-query event payloads. @since v1.3.0 */
     log?: { slowQueryTag?: { event?: string; code?: string;[key: string]: unknown }; formatSlowQuery?: (meta: unknown) => unknown; };
-    /** Auto-convert 24-character hex strings to ObjectId in query filters. Pass a field map to selectively enable per field. Default: true for mongodb type (pass `false` to disable). @since v1.3.0 */
+    /** Auto-convert valid 24-character hex strings to ObjectId across query/write paths. Pass `false` to disable, or use `excludeFields`, `maxDepth`, or `{ field: false }` escape hatches. Default: true for mongodb type. @since v1.3.0 */
     autoConvertObjectId?: boolean | {
         enabled?: boolean;
         excludeFields?: string[];
@@ -178,8 +264,13 @@ export interface MonSQLizeOptions {
     models?: string | { path: string; pattern?: string; recursive?: boolean; };
     /** Global automatic model index creation control. Defaults to true for backward compatibility. */
     autoIndex?: ModelAutoIndexOptions;
-    /** Auto-invalidate cache on write operations. @since v1.3.0 */
+    /** Compatibility alias for `cache.autoInvalidate`. Prefer the nested cache option. */
     cacheAutoInvalidate?: boolean;
+    /**
+     * Optional write path governance. By default both collection and model write APIs remain available.
+     * Use `model-only` per default or namespace to require writes through the model API.
+     */
+    writePathPolicy?: WritePathPolicyOptions;
 }
 
 export interface MonSQLizeInstance {
@@ -276,21 +367,24 @@ export interface MonSQLizeInstance {
      */
     withTransaction<T>(callback: (transaction: Transaction) => Promise<T>, options?: TransactionOptions): Promise<T>;
     /**
-     * Execute a callback while holding a distributed lock; the lock is released automatically on completion.
+     * Execute a callback while holding a legacy monSQLize lock; the lock is released automatically on completion.
+     * @deprecated Business locks are retained for compatibility. Prefer application/framework-level locking.
      * @param key Unique lock identifier key.
      * @param callback Async callback executed while the lock is held.
      * @param options Optional lock options.
      */
     withLock<T>(key: string, callback: () => Promise<T>, options?: LockOptions): Promise<T>;
     /**
-     * Acquire a distributed lock, blocking until it is available or the timeout is reached.
+     * Acquire a legacy monSQLize lock, blocking until it is available or the timeout is reached.
+     * @deprecated Business locks are retained for compatibility. Prefer application/framework-level locking.
      * @param key Unique lock identifier key.
      * @param options Optional lock options.
      * @returns The acquired lock instance.
      */
     acquireLock(key: string, options?: LockOptions): Promise<Lock>;
     /**
-     * Try to acquire a distributed lock without blocking; returns `null` if the lock is already held.
+     * Try to acquire a legacy monSQLize lock without blocking; returns `null` if the lock is already held.
+     * @deprecated Business locks are retained for compatibility. Prefer application/framework-level locking.
      * @param key Unique lock identifier key.
      * @param options Optional lock options (`retryTimes` is not supported).
      * @returns The acquired lock instance, or `null` if unavailable.
@@ -300,27 +394,29 @@ export interface MonSQLizeInstance {
     getSyncManager(): ChangeStreamSyncManager | null;
     /** Return the slow-query log manager; `null` when slow-query logging is not enabled. */
     getSlowQueryLogManager(): SlowQueryLogManager | null;
-    /** Return the Saga orchestrator instance. */
+    /** @deprecated Saga APIs are retained for compatibility. Prefer application/framework-level workflow orchestration. */
     getSagaOrchestrator(): SagaOrchestrator;
-    /** Shorthand alias for `getSagaOrchestrator()`. */
+    /** @deprecated Saga APIs are retained for compatibility. Prefer application/framework-level workflow orchestration. */
     saga(): SagaOrchestrator;
     /**
      * Register a Saga definition.
+     * @deprecated Saga APIs are retained for compatibility. Prefer application/framework-level workflow orchestration.
      * @param definition Saga definition object containing steps and compensation logic.
      */
     defineSaga(definition: SagaDefinition): Promise<SagaDefinition>;
     /**
      * Execute the named registered Saga.
+     * @deprecated Saga APIs are retained for compatibility. Prefer application/framework-level workflow orchestration.
      * @param name Saga name.
      * @param data Initial data passed into the Saga.
      * @returns The Saga execution result.
      */
     executeSaga(name: string, data: unknown): Promise<SagaResult>;
-    /** List all registered Saga names. */
+    /** @deprecated Saga APIs are retained for compatibility. Prefer application/framework-level workflow orchestration. */
     listSagas(): string[];
     /** Return aggregate transaction statistics; `null` before transaction capability initialization. */
     getTransactionStats(): TransactionStats | null;
-    /** Return Saga execution statistics (success / failure / compensation counts, etc.). */
+    /** @deprecated Saga APIs are retained for compatibility. Prefer application/framework-level workflow orchestration. */
     getSagaStats(): SagaStats;
     /** Return distributed cache invalidator statistics; `null` when distributed invalidation is not enabled. */
     getDistributedCacheInvalidatorStats(): DistributedCacheInvalidatorStats | null;
@@ -452,17 +548,26 @@ export default class MonSQLize implements MonSQLizeInstance {
     ensureModelIndexes(options?: ModelEnsureAllIndexesOptions): Promise<ModelIndexEnsureSummary>;
     startSession(options?: TransactionOptions): Promise<Transaction>;
     withTransaction<T>(callback: (transaction: Transaction) => Promise<T>, options?: TransactionOptions): Promise<T>;
+    /** @deprecated Business locks are retained for compatibility. Prefer application/framework-level locking. */
     withLock<T>(key: string, callback: () => Promise<T>, options?: LockOptions): Promise<T>;
+    /** @deprecated Business locks are retained for compatibility. Prefer application/framework-level locking. */
     acquireLock(key: string, options?: LockOptions): Promise<Lock>;
+    /** @deprecated Business locks are retained for compatibility. Prefer application/framework-level locking. */
     tryAcquireLock(key: string, options?: Omit<LockOptions, 'retryTimes'>): Promise<Lock | null>;
     getSyncManager(): ChangeStreamSyncManager | null;
     getSlowQueryLogManager(): SlowQueryLogManager | null;
+    /** @deprecated Saga APIs are retained for compatibility. Prefer application/framework-level workflow orchestration. */
     getSagaOrchestrator(): SagaOrchestrator;
+    /** @deprecated Saga APIs are retained for compatibility. Prefer application/framework-level workflow orchestration. */
     saga(): SagaOrchestrator;
+    /** @deprecated Saga APIs are retained for compatibility. Prefer application/framework-level workflow orchestration. */
     defineSaga(definition: SagaDefinition): Promise<SagaDefinition>;
+    /** @deprecated Saga APIs are retained for compatibility. Prefer application/framework-level workflow orchestration. */
     executeSaga(name: string, data: unknown): Promise<SagaResult>;
+    /** @deprecated Saga APIs are retained for compatibility. Prefer application/framework-level workflow orchestration. */
     listSagas(): string[];
     getTransactionStats(): TransactionStats | null;
+    /** @deprecated Saga APIs are retained for compatibility. Prefer application/framework-level workflow orchestration. */
     getSagaStats(): SagaStats;
     getDistributedCacheInvalidatorStats(): DistributedCacheInvalidatorStats | null;
     startSync(): Promise<void>;
@@ -505,7 +610,15 @@ export default class MonSQLize implements MonSQLizeInstance {
     static hasExpressionInObject: typeof hasExpressionInObject;
     static hasExpressionInPipeline: typeof hasExpressionInPipeline;
     static createRedisCacheAdapter: typeof createRedisCacheAdapter;
+    /**
+     * @deprecated Retained for v1 compatibility. Non-database function caching is no longer a recommended monSQLize feature path;
+     * use `cache-hub` directly or an application-owned cache layer for new generic function-cache usage.
+     */
     static withCache: typeof withCache;
+    /**
+     * @deprecated Retained for v1 compatibility. Non-database function caching is no longer a recommended monSQLize feature path;
+     * use `cache-hub` directly or an application-owned cache layer for new generic function-cache usage.
+     */
     static FunctionCache: typeof FunctionCache;
     static adaptLegacyCacheLike: typeof adaptLegacyCacheLike;
     static MultiLevelCache: typeof MultiLevelCache;
@@ -517,6 +630,7 @@ export default class MonSQLize implements MonSQLizeInstance {
     static SlowQueryLogMemoryStorage: typeof SlowQueryLogMemoryStorage;
     static MongoDBSlowQueryLogStorage: typeof MongoDBSlowQueryLogStorage;
     static BatchQueue: typeof BatchQueue;
+    static DataTaskJobError: typeof DataTaskJobError;
     static generateQueryHash: typeof generateQueryHash;
     static SagaOrchestrator: typeof SagaOrchestrator;
 }

package/dist/types/runtime.d.mts

@@ -91,6 +91,10 @@ export interface MultiLevelCacheOptions {
 }
 
 export type MultiLevelInvalidationMessage = {
+    type: 'del' | 'delete' | 'invalidateKey';
+    key: string;
+    ts: number;
+} | {
     type: 'delPattern';
     pattern: string;
     ts: number;
@@ -189,6 +193,7 @@ export type DistributedCacheInvalidatorStats = HubInvalidatorStats;
 export declare class DistributedCacheInvalidator {
     constructor(options: DistributedCacheInvalidatorOptions);
     invalidate(pattern: string): Promise<void>;
+    invalidateKey(key: string): Promise<void>;
     getStats(): HubInvalidatorStats;
     close(): Promise<void>;
 }
@@ -253,11 +258,19 @@ export interface FunctionCacheOptions extends HubFunctionCacheOptions {
     defaultTTL?: number;
 }
 
+/**
+ * @deprecated Retained for v1 compatibility. Non-database function caching is no longer a recommended monSQLize feature path;
+ * use `cache-hub` directly or an application-owned cache layer for new generic function-cache usage.
+ */
 export declare function withCache<TArgs extends unknown[], TResult>(
     fn: (...args: TArgs) => Promise<TResult>,
     options?: WithCacheOptions<(...args: TArgs) => Promise<TResult>>,
 ): CachedFunction<TArgs, TResult>;
 
+/**
+ * @deprecated Retained for v1 compatibility. Non-database function caching is no longer a recommended monSQLize feature path;
+ * use `cache-hub` directly or an application-owned cache layer for new generic function-cache usage.
+ */
 export declare class FunctionCache {
     constructor(cacheOrDb?: CacheLike | { getCache(): CacheLike; }, options?: FunctionCacheOptions);
     register(name: string, fn: (...args: unknown[]) => Promise<unknown>, options?: {
@@ -291,7 +304,7 @@ export declare class ModelInstance<TDocument = any> implements ModelInstanceCont
     readonly dbName: string;
     readonly poolName?: string;
     readonly definition: ModelDefinition<TDocument>;
-    getNamespace(): { iid: string; type: 'mongodb'; db: string; collection: string; };
+    getNamespace(): { iid: string; type: 'mongodb'; db: string; collection: string; pool?: string; };
     getRelations(): Record<string, RelationConfig>;
     getEnums(): Record<string, string>;
     raw(): unknown;