@classytic/mongokit 3.36.0 → 3.39.0

package/dist/{index-DKEql4cL.d.mts → index-CmjNyulu.d.mts}

@@ -1,5 +1,5 @@
-import { _ as UpdateOptions, a as CreateOptions, b as LookupOptions, c as FindOneAndUpdateOptions, f as MinMaxResult, g as UpdateManyResult, l as GroupResult, p as OperationOptions, s as DeleteResult } from "./operations-DZodvjC-.mjs";
-import { a as PopulateSpec, i as ObjectId, l as SortSpec, o as ReadPreferenceType, s as SelectSpec, t as AnyDocument } from "./core-62oo3N1C.mjs";
+import { _ as UpdateOptions, a as CreateOptions, b as LookupOptions, c as FindOneAndUpdateOptions, f as MinMaxResult, g as UpdateManyResult, l as GroupResult, p as OperationOptions, s as DeleteResult } from "./operations-CrRIoc8Z.mjs";
+import { _ as PopulateSpec, g as ObjectId, p as AnyDocument, v as ReadPreferenceType, x as SortSpec, y as SelectSpec } from "./pagination-BpIv2bdS.mjs";
 import { p as UpdateWithValidationResult } from "./type-utils-CLzRFtIA.mjs";
 import { Model, PipelineStage } from "mongoose";
 declare namespace aggregate_d_exports {
@@ -12,9 +12,18 @@ declare function aggregate<TResult = unknown>(Model: Model<any>, pipeline: Pipel
   session?: unknown;
 }): Promise<TResult[]>;
 /**
- * Aggregate with pagination using native MongoDB $facet
- * WARNING: $facet results must be <16MB. For larger results (limit >1000),
- * consider using Repository.aggregatePaginate() or splitting into separate queries.
+ * Aggregate with pagination.
+ *
+ * Page and count run as TWO concurrent pipelines rather than one `$facet`.
+ * `$facet` bundles every returned document plus the count into a SINGLE output
+ * document, and no stage may exceed 16MB — so a page of large documents failed
+ * with `BSONObjectTooLarge` instead of paginating, and the only defence was a
+ * warning above an arbitrary limit of 1000 that told the caller to go
+ * elsewhere. `$facet` also cannot use an index for the stages inside it.
+ *
+ * The trade: two reads, so a concurrent write between them can leave `total`
+ * a document out of step with `data` — the same trade `PaginationEngine`
+ * already makes on both its offset and aggregate paths.
  */
 declare function aggregatePaginate<TDoc = AnyDocument>(Model: Model<TDoc>, pipeline: PipelineStage[], options?: {
   page?: number;
@@ -91,14 +100,64 @@ declare function minMax(Model: Model<any>, field: string, query?: Record<string,
   session?: unknown;
 }): Promise<MinMaxResult>;
 declare namespace create_d_exports {
-  export { create, createDefault, createMany, upsert };
+  export { CreateManyFailure, CreateManyPartial, CreateManyPartialError, create, createDefault, createMany, isCreateManyPartialError, upsert };
 }
 /**
  * Create single document
  */
 declare function create<TDoc = AnyDocument>(Model: Model<TDoc>, data: Record<string, unknown>, options?: CreateOptions): Promise<TDoc>;
 /**
- * Create multiple documents
+ * One rejected input, keyed by its position in the array that was passed in.
+ *
+ * The index is the load-bearing part: it is the only way to tie a failure back
+ * to the caller's own record — the driver reports failures positionally, and a
+ * rejected document never comes back with an `_id` to match on.
+ */
+interface CreateManyFailure {
+  /** Position in the ORIGINAL `dataArray`. */
+  index: number;
+  /** The input that was rejected, as supplied. */
+  doc: Record<string, unknown>;
+  /** MongoDB error code, e.g. 11000 for a duplicate key. */
+  code?: number;
+  message: string;
+}
+/**
+ * What a partially-successful `createMany` actually did.
+ *
+ * Attached to the thrown error as `partial`. `createMany` still REJECTS — that
+ * is unchanged and deliberate — but the rejection now says which documents
+ * landed and which did not, instead of leaving the caller to dig through a
+ * driver error to find out.
+ */
+interface CreateManyPartial<TDoc = AnyDocument> {
+  /** Documents the server accepted. */
+  inserted: TDoc[];
+  /** Every rejected input, in input order. */
+  failed: CreateManyFailure[];
+}
+/** The error `createMany` throws when some documents landed and some did not. */
+type CreateManyPartialError<TDoc = AnyDocument> = Error & {
+  partial?: CreateManyPartial<TDoc>;
+};
+/** Narrow a caught error to one carrying a partial-write report. */
+declare function isCreateManyPartialError<TDoc = AnyDocument>(err: unknown): err is CreateManyPartialError<TDoc> & {
+  partial: CreateManyPartial<TDoc>;
+};
+/**
+ * Create multiple documents.
+ *
+ * **A rejection does NOT mean nothing was written.** Neither ordering does:
+ * `ordered: true` stops at the first failure and keeps everything before it,
+ * `ordered: false` keeps everything valid. Measured on a six-document batch
+ * with a conflict in the middle — ordered wrote 3, unordered wrote 5. Only a
+ * transaction gives all-or-nothing.
+ *
+ * So the rejection carries a `partial` report naming what landed and what did
+ * not, because the alternative is a caller retrying the whole batch and
+ * double-writing everything that had already succeeded. Use it to retry only
+ * `failed`, or to reconcile — and prefer a unique index or an idempotency key
+ * for anything that will be retried automatically.
  */
 declare function createMany<TDoc = AnyDocument>(Model: Model<TDoc>, dataArray: Record<string, unknown>[], options?: CreateOptions): Promise<TDoc[]>;
 /**
@@ -301,4 +360,4 @@ declare namespace index_d_exports {
   export { aggregate_d_exports as aggregate, create_d_exports as create, delete_d_exports as deleteActions, read_d_exports as read, update_d_exports as update };
 }
 //#endregion
-export { create_d_exports as a, delete_d_exports as i, update_d_exports as n, aggregate_d_exports as o, read_d_exports as r, index_d_exports as t };
+export { CreateManyFailure as a, create_d_exports as c, delete_d_exports as i, isCreateManyPartialError as l, update_d_exports as n, CreateManyPartial as o, read_d_exports as r, CreateManyPartialError as s, index_d_exports as t, aggregate_d_exports as u };

package/dist/index.d.mts

@@ -1,18 +1,17 @@
-import { _ as UpdateOptions, a as CreateOptions, b as LookupOptions, c as FindOneAndUpdateOptions, d as LookupPopulateResult, f as MinMaxResult, g as UpdateManyResult, h as SessionOptions, i as ConvenientTransactionOptions, l as GroupResult, m as ReadOptions, n as CacheOperationOptions, p as OperationOptions, r as CacheableOptions, s as DeleteResult, t as AggregateOptions, u as LookupPopulateOptions, v as WithTransactionOptions, y as LookupBuilder } from "./operations-DZodvjC-.mjs";
-import { a as PopulateSpec, c as SortDirection, i as ObjectId, l as SortSpec$1, n as AnyModel, o as ReadPreferenceType, s as SelectSpec, t as AnyDocument } from "./core-62oo3N1C.mjs";
-import { a as DecodedCursor, c as PaginationConfig, i as CursorPayload, l as ValueType, n as BasePaginationOptions, o as KeysetPaginationOptions, r as CollationOptions, s as OffsetPaginationOptions, t as AggregatePaginationOptions } from "./pagination-jSUdrACK.mjs";
-import { t as index_d_exports } from "./index-DKEql4cL.mjs";
+import { _ as UpdateOptions, a as CreateOptions, b as LookupOptions, c as FindOneAndUpdateOptions, d as LookupPopulateResult, f as MinMaxResult, g as UpdateManyResult, h as SessionOptions, i as ConvenientTransactionOptions, l as GroupResult, m as ReadOptions, n as CacheOperationOptions, p as OperationOptions, r as CacheableOptions, s as DeleteResult, t as AggregateOptions, u as LookupPopulateOptions, v as WithTransactionOptions, y as LookupBuilder } from "./operations-CrRIoc8Z.mjs";
+import { _ as PopulateSpec, a as CursorPayload, b as SortDirection, c as MongokitPageExtras, d as ValueType, f as CursorSecret, g as ObjectId, i as CountStrategy, l as OffsetPaginationOptions, m as AnyModel, n as BasePaginationOptions, o as DecodedCursor, p as AnyDocument, r as CollationOptions, s as KeysetPaginationOptions, t as AggregatePaginationOptions, u as PaginationConfig, v as ReadPreferenceType, x as SortSpec$1, y as SelectSpec } from "./pagination-BpIv2bdS.mjs";
+import { a as CreateManyFailure, l as isCreateManyPartialError, o as CreateManyPartial, s as CreateManyPartialError, t as index_d_exports } from "./index-CmjNyulu.mjs";
 import { a as InferRawDoc, c as NonNullableFields, d as Strict, f as UpdatePatch, i as InferDocument, l as PartialBy, n as DeepPartial, o as KeysOfType, p as UpdateWithValidationResult, r as DocField, s as MongoOperatorUpdate, t as CreateInput, u as RequiredBy } from "./type-utils-CLzRFtIA.mjs";
-import { S as RepositoryPluginName, _ as RepositoryOptions, a as HookMode, b as MONGOKIT_PLUGIN_NAMES, c as MinimalRepoView, d as PluginType, f as PrioritizedHook, g as RepositoryOperation, h as RepositoryInstance, i as EventPhase, l as Plugin, m as RepositoryEvent, n as EventHandlers, o as Middleware, p as RepositoryContext, r as EventPayload, s as MiddlewareContext, t as AllPluginMethods, u as PluginFunction, v as UserContext, x as MongoKitPluginName, y as WithPlugins } from "./repository-H_ffGgpE.mjs";
-import { A as ensureAuditTrailReady, C as AuditTrailMethods, D as AuditTrailQueryOptions, E as AuditTrailQuery, O as EnsureAuditTrailReadyOptions, S as AuditQueryResult, T as AuditTrailOptions, _ as RepositoryCachePluginOptions, a as DateSequentialIdOptions, b as AuditOperation, c as SequentialIdOptions, d as getNextSequence, f as prefixedId, g as RepositoryCacheHandle, h as CacheOptions, i as CustomIdOptions, k as auditTrailPlugin, l as customIdPlugin, m as CacheAdapter, n as adminBypass, o as IdGenerator, p as sequentialId, r as multiTenantPlugin, s as PrefixedIdOptions, t as MultiTenantOptions, u as dateSequentialId, v as cachePlugin, w as AuditTrailMode, x as AuditQueryOptions, y as AuditEntry } from "./multi-tenant.plugin-BwSvTirB.mjs";
-import { t as PaginationEngine } from "./PaginationEngine-CBS1XGzp.mjs";
-import { a as AggregationPlan, c as SortOrder, i as AggregationBuilder, l as SortSpec, n as Repository, o as GroupSpec, r as TransitionMachine, s as ProjectionSpec, t as HOOK_PRIORITY, u as VectorSearchOptions } from "./Repository-BdSkQ8vc.mjs";
-import { a as SoftDeleteFilterMode, c as ValidationChainOptions, i as Logger, l as ValidatorDefinition, n as CascadeRelation, o as SoftDeleteOptions, r as FieldPreset, s as SoftDeleteRepository, t as CascadeOptions } from "./plugin-options-DXnlKM3B.mjs";
-import { n as CreateRepositoryConfig, r as createRepository, t as AuditConfig } from "./create-repository-BU4x9Kb0.mjs";
-import { A as IdempotencyStoreMethods, B as auditLogPlugin, C as LeaseMethods, D as ImmutableStatesPluginOptions, E as ImmutableClaimView, F as elasticSearchPlugin, H as appendOnlyPlugin, I as cascadePlugin, L as BatchOperationsMethods, M as idempotencyStorePlugin, N as fieldFilterPlugin, O as immutableStatesPlugin, P as ElasticSearchOptions, R as BulkWriteResult, S as methodRegistryPlugin, T as leasePlugin, U as AggregateHelpersMethods, V as AppendOnlyPluginOptions, W as aggregateHelpersPlugin, _ as OperationMetric, a as requireField, b as mongoOperationsPlugin, c as timestampPlugin, d as createTenantContext, f as SubdocumentMethods, g as ObservabilityOptions, h as softDeletePlugin, i as immutableField, j as IdempotencyStorePluginOptions, k as IdempotencyClaim, l as TenantContext, m as SoftDeleteMethods, n as autoInject, o as uniqueField, p as subdocumentPlugin, r as blockIf, s as validationChainPlugin, t as OperationType, u as TenantStore, v as observabilityPlugin, w as LeasePluginOptions, y as MongoOperationsMethods, z as batchOperationsPlugin } from "./validation-chain.plugin-yQRob3Av.mjs";
+import { S as RepositoryPluginName, _ as RepositoryOptions, a as HookMode, b as MONGOKIT_PLUGIN_NAMES, c as MinimalRepoView, d as PluginType, f as PrioritizedHook, g as RepositoryOperation, h as RepositoryInstance, i as EventPhase, l as Plugin, m as RepositoryEvent, n as EventHandlers, o as Middleware, p as RepositoryContext, r as EventPayload, s as MiddlewareContext, t as AllPluginMethods, u as PluginFunction, v as UserContext, x as MongoKitPluginName, y as WithPlugins } from "./repository-ZbLtL7Nk.mjs";
+import { A as ensureAuditTrailReady, C as AuditTrailMethods, D as AuditTrailQueryOptions, E as AuditTrailQuery, O as EnsureAuditTrailReadyOptions, S as AuditQueryResult, T as AuditTrailOptions, _ as RepositoryCachePluginOptions, a as DateSequentialIdOptions, b as AuditOperation, c as SequentialIdOptions, d as getNextSequence, f as prefixedId, g as RepositoryCacheHandle, h as CacheOptions, i as CustomIdOptions, k as auditTrailPlugin, l as customIdPlugin, m as CacheAdapter, n as adminBypass, o as IdGenerator, p as sequentialId, r as multiTenantPlugin, s as PrefixedIdOptions, t as MultiTenantOptions, u as dateSequentialId, v as cachePlugin, w as AuditTrailMode, x as AuditQueryOptions, y as AuditEntry } from "./multi-tenant.plugin-B-tzNeYL.mjs";
+import { t as PaginationEngine } from "./PaginationEngine-D-P19Y9m.mjs";
+import { a as AggregationPlan, c as SortOrder, i as AggregationBuilder, l as SortSpec, n as Repository, o as GroupSpec, r as TransitionMachine, s as ProjectionSpec, t as HOOK_PRIORITY, u as VectorSearchOptions } from "./Repository-IxI983_m.mjs";
+import { a as SoftDeleteFilterMode, c as ValidationChainOptions, i as Logger, l as ValidatorDefinition, n as CascadeRelation, o as SoftDeleteOptions, r as FieldPreset, s as SoftDeleteRepository, t as CascadeOptions } from "./plugin-options-BuvtOSZf.mjs";
+import { n as CreateRepositoryConfig, r as createRepository, t as AuditConfig } from "./create-repository-CRXjDa3N.mjs";
+import { A as IdempotencyStoreMethods, B as auditLogPlugin, C as LeaseMethods, D as ImmutableStatesPluginOptions, E as ImmutableClaimView, F as elasticSearchPlugin, H as appendOnlyPlugin, I as cascadePlugin, L as BatchOperationsMethods, M as idempotencyStorePlugin, N as fieldFilterPlugin, O as immutableStatesPlugin, P as ElasticSearchOptions, R as BulkWriteResult, S as methodRegistryPlugin, T as leasePlugin, U as AggregateHelpersMethods, V as AppendOnlyPluginOptions, W as aggregateHelpersPlugin, _ as OperationMetric, a as requireField, b as mongoOperationsPlugin, c as timestampPlugin, d as createTenantContext, f as SubdocumentMethods, g as ObservabilityOptions, h as softDeletePlugin, i as immutableField, j as IdempotencyStorePluginOptions, k as IdempotencyClaim, l as TenantContext, m as SoftDeleteMethods, n as autoInject, o as uniqueField, p as subdocumentPlugin, r as blockIf, s as validationChainPlugin, t as OperationType, u as TenantStore, v as observabilityPlugin, w as LeasePluginOptions, y as MongoOperationsMethods, z as batchOperationsPlugin } from "./validation-chain.plugin-DvrLJIbJ.mjs";
 import { n as SchemaPathsLike, t as FieldType$1 } from "./coercion-BjdPX3YF.mjs";
 import { n as SchemaIndexes } from "./indexes-DIjMpYES.mjs";
-import { S as parseDuplicateKeyError, _ as getMongooseProjection, a as createMemoryCache, b as createError, g as getFieldsForUser, h as filterResponseData, i as buildCrudSchemasFromMongooseSchema, m as createFieldPreset, n as CrudSchemasFramework, o as LoggerConfig, r as buildCrudSchemasFromModel, s as configureLogger, t as toPlain, u as idVariants, v as CreateErrorOptions, x as isDuplicateKeyError, y as ParseDuplicateKeyOptions } from "./to-plain-Dyz_qvuo.mjs";
+import { S as parseDuplicateKeyError, _ as getMongooseProjection, a as createMemoryCache, b as createError, g as getFieldsForUser, h as filterResponseData, i as buildCrudSchemasFromMongooseSchema, m as createFieldPreset, n as CrudSchemasFramework, o as LoggerConfig, r as buildCrudSchemasFromModel, s as configureLogger, t as toPlain, u as idVariants, v as CreateErrorOptions, x as isDuplicateKeyError, y as ParseDuplicateKeyOptions } from "./to-plain-B8ufk3Qz.mjs";
 import { RepoCapabilities } from "@classytic/repo-core/repository";
 import { ClientSession, Connection, Model, PipelineStage, Schema } from "mongoose";
 //#region src/actions/cascade-references.d.ts
@@ -396,6 +395,71 @@ declare const READ_OPERATIONS: readonly RepositoryOperation[];
 /** Filter ops by their policy injection key. */
 declare function operationsByPolicyKey(key: PolicyKey): RepositoryOperation[];
 //#endregion
+//#region src/pagination/defaults.d.ts
+/**
+ * The subset of {@link PaginationConfig} that describes a deployment rather
+ * than one collection's shape.
+ *
+ * Deliberately NOT `defaultLimit` / `maxLimit` / `cursorVersion`: those are
+ * per-collection judgements (a line-item list and an audit log want different
+ * page sizes), and a process-wide override of them would be a surprise rather
+ * than a policy. What is here is the scale policy — how a page is walked, and
+ * whether the rows behind it are counted — plus the one SECURITY setting that
+ * is deployment-wide by nature: a signing key is one key for the process, and a
+ * repository that quietly declined to use it would be the hole.
+ */
+interface PaginationDefaults {
+  /** See {@link PaginationConfig.defaultCountStrategy}. */
+  defaultCountStrategy?: CountStrategy;
+  /**
+   * See {@link PaginationConfig.defaultCountLimit}.
+   *
+   * Belongs to the deployment for the same reason the strategy does: it is the
+   * point past which this business stops caring about an exact row count, which
+   * is one answer for the whole process, not per collection.
+   */
+  defaultCountLimit?: number;
+  /**
+   * See {@link PaginationConfig.cursorSecret}.
+   *
+   * The reason this one MUST be reachable here: a kernel builds its own
+   * repositories, so without the policy seam a host could sign the cursors it
+   * mints itself while every engine-owned list kept issuing unsigned ones — a
+   * half-signed deployment, which is an unsigned deployment.
+   */
+  cursorSecret?: CursorSecret;
+  /** See {@link PaginationConfig.defaultMode}. */
+  defaultMode?: 'offset' | 'keyset';
+  /**
+   * See {@link PaginationConfig.maxPage}.
+   *
+   * The other half of the offset cost: `skip(n)` walks n index entries before
+   * returning anything, so an unbounded page number is an unbounded read. A
+   * fleet that has moved to keyset can lower this to make the offset path's
+   * remaining callers fail loudly instead of quietly costing a scan.
+   */
+  maxPage?: number;
+}
+/**
+ * Set the deployment's pagination policy. Merges into whatever is already set,
+ * so two call sites configuring different keys do not clobber each other.
+ *
+ * Call it at boot, before composing modules. Ordering is not load-bearing —
+ * repositories read this at query time, not construction time — but a call
+ * made after traffic starts changes behaviour mid-flight, which is rarely what
+ * anyone means.
+ */
+declare function configurePaginationDefaults(defaults: PaginationDefaults): void;
+/**
+ * The current deployment policy. Empty until something configures it.
+ *
+ * A COPY — `Readonly<T>` is erased at runtime, and handing out the live object
+ * would let a caller mutate the policy through a getter that promised not to.
+ */
+declare function getPaginationDefaults(): Readonly<PaginationDefaults>;
+/** Back to library defaults. For tests — a global that cannot be reset is a leak between them. */
+declare function resetPaginationDefaults(): void;
+//#endregion
 //#region src/query/parser/types.d.ts
 type SortSpec$2 = Record<string, 1 | -1>;
 type FilterQuery = Record<string, unknown>;
@@ -972,4 +1036,4 @@ declare function createOptionsExtractor<TCtx extends Record<string, unknown>>(fi
  */
 declare function systemContext(extra?: SessionOptions): SessionOptions;
 //#endregion
-export { ALL_OPERATIONS, type AggregateHelpersMethods, type AggregateOptions, type AggregatePaginationOptions, AggregationBuilder, type AggregationPlan, type SortOrder as AggregationSortOrder, type SortSpec as AggregationSortSpec, type AllPluginMethods, type AnyDocument, type AnyModel, type AppendOnlyPluginOptions, type AuditConfig, type AuditEntry, type AuditOperation, type AuditQueryOptions, type AuditQueryResult, type AuditTrailMethods, type AuditTrailMode, type AuditTrailOptions, AuditTrailQuery, type AuditTrailQueryOptions, type BasePaginationOptions, type BatchOperationsMethods, type BulkWriteResult, type CacheAdapter, type CacheOperationOptions, type CacheOptions, type CacheableOptions, type CapabilityConnectionLike, type CapabilityProbeOptions, type CapabilityResolution, type CascadeOptions, type CascadePurgeReferencesOptions, type CascadeRelation, type CollationOptions, type CollectionRWLike, type ConvenientTransactionOptions, type CreateErrorOptions, type CreateInput, type CreateOptions, type CreateRepositoryConfig, type CrudSchemasFramework, type CursorPayload, type CustomIdOptions, type DateSequentialIdOptions, type DecodedCursor, type DeepPartial, type DefineModelOptions, type DeleteResult, type DocField, type ElasticSearchOptions, type EnsureAuditTrailReadyOptions, type EventHandlers, type EventPayload, type EventPhase, type ExistingModelPolicy, type FieldPreset, type FieldType, type FilterQuery, type FindOneAndUpdateOptions, type GroupResult, type GroupSpec, HOOK_PRIORITY, type HookMode, type IdGenerator, type IdempotencyClaim, type IdempotencyStoreMethods, type IdempotencyStorePluginOptions, type ImmutableClaimView, type ImmutableStatesPluginOptions, type InferDocument, type InferRawDoc, type KeysOfType, type KeysetPaginationOptions, type LeaseMethods, type LeasePluginOptions, type Logger, type LoggerConfig, LookupBuilder, type LookupOptions, type LookupPopulateOptions, type LookupPopulateResult, MONGOKIT_CAPABILITIES, MONGOKIT_PLUGIN_NAMES, MUTATING_OPERATIONS, type Middleware, type MiddlewareContext, type MinMaxResult, type MinimalRepoView, type ModelBlueprint, ModelCollisionError, type ModelSpec, type MongoKitPluginName, type MongoOperationsMethods, type MongoOperatorUpdate, type MongoRepoCapabilities, type MultiTenantOptions, type NonNullableFields, OP_REGISTRY, type ObjectId, type ObservabilityOptions, type OffsetPaginationOptions, type OperationDescriptor, type OperationMetric, type OperationOptions, type OperationType, type PaginationConfig, PaginationEngine, type ParseDuplicateKeyOptions, type ParsedQuery, type PartialBy, type Plugin, type PluginFunction, type PluginType, type PolicyKey, type PopulateOption, type PopulateSpec, type PrefixedIdOptions, type PrioritizedHook, type ProjectionSpec, type PurgeMode, type PurgeableRepoLike, QueryParser, type QueryParserOptions, type QuerySchema, READ_OPERATIONS, type ReadOptions, type ReadPreferenceType, type ReferencePurgeResult, type ReferenceRelation, Repository, Repository as default, type RepositoryCacheHandle, type RepositoryCachePluginOptions, type RepositoryContext, type RepositoryEvent, type RepositoryInstance, type RepositoryOperation, type RepositoryOptions, type RepositoryPluginName, type RequiredBy, type SchemaLike, type SearchMode, type SelectSpec, type SequentialIdOptions, type SessionOptions, type SessionStarter, type SoftDeleteFilterMode, type SoftDeleteMethods, type SoftDeleteOptions, type SoftDeleteRepository, type SortDirection, type SortSpec$1 as SortSpec, type Strict, type SubdocumentMethods, type TenantContext, type TenantStore, type TransactionSupport, type TransitionMachine, type UpdateManyResult, type UpdateOptions, type UpdatePatch, type UpdateWithValidationResult, type UserContext, type ValidationChainOptions, type ValidatorDefinition, type ValueType, type VectorSearchOptions, type WithPlugins, type WithTransactionOptions, index_d_exports as actions, adminBypass, aggregateHelpersPlugin, appendOnlyPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, batchTransaction, blockIf, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, cachePlugin, capabilitiesForSupport, cascadePlugin, cascadePurgeReferences, classifyHelloReply, compileFilterToMongo, configureLogger, createError, createFieldPreset, createMemoryCache, createOptionsExtractor, createRepository, createTenantContext, customIdPlugin, dateSequentialId, defineModel, defineModels, elasticSearchPlugin, ensureAuditTrailReady, fieldFilterPlugin, filterResponseData, getFieldsForUser, getMongooseProjection, getNextSequence, idVariants, idempotencyStorePlugin, immutableField, immutableStatesPlugin, isDuplicateKeyError, isModelRegistered, isTransactionUnsupported, leasePlugin, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, operationsByPolicyKey, parseDuplicateKeyError, prefixedId, probeMongoCapabilities, repoOptionsFromCtx, requireField, resetCapabilityProbeCache, resolveMongoCapabilities, resolveTransactionSupport, sequentialId, softDeletePlugin, subdocumentPlugin, supportsTransactions, systemContext, timestampPlugin, toPlain, transactionResolutionOf, uniqueField, validationChainPlugin, withTransaction };
+export { ALL_OPERATIONS, type AggregateHelpersMethods, type AggregateOptions, type AggregatePaginationOptions, AggregationBuilder, type AggregationPlan, type SortOrder as AggregationSortOrder, type SortSpec as AggregationSortSpec, type AllPluginMethods, type AnyDocument, type AnyModel, type AppendOnlyPluginOptions, type AuditConfig, type AuditEntry, type AuditOperation, type AuditQueryOptions, type AuditQueryResult, type AuditTrailMethods, type AuditTrailMode, type AuditTrailOptions, AuditTrailQuery, type AuditTrailQueryOptions, type BasePaginationOptions, type BatchOperationsMethods, type BulkWriteResult, type CacheAdapter, type CacheOperationOptions, type CacheOptions, type CacheableOptions, type CapabilityConnectionLike, type CapabilityProbeOptions, type CapabilityResolution, type CascadeOptions, type CascadePurgeReferencesOptions, type CascadeRelation, type CollationOptions, type CollectionRWLike, type ConvenientTransactionOptions, type CountStrategy, type CreateErrorOptions, type CreateInput, type CreateManyFailure, type CreateManyPartial, type CreateManyPartialError, type CreateOptions, type CreateRepositoryConfig, type CrudSchemasFramework, type CursorPayload, type CursorSecret, type CustomIdOptions, type DateSequentialIdOptions, type DecodedCursor, type DeepPartial, type DefineModelOptions, type DeleteResult, type DocField, type ElasticSearchOptions, type EnsureAuditTrailReadyOptions, type EventHandlers, type EventPayload, type EventPhase, type ExistingModelPolicy, type FieldPreset, type FieldType, type FilterQuery, type FindOneAndUpdateOptions, type GroupResult, type GroupSpec, HOOK_PRIORITY, type HookMode, type IdGenerator, type IdempotencyClaim, type IdempotencyStoreMethods, type IdempotencyStorePluginOptions, type ImmutableClaimView, type ImmutableStatesPluginOptions, type InferDocument, type InferRawDoc, type KeysOfType, type KeysetPaginationOptions, type LeaseMethods, type LeasePluginOptions, type Logger, type LoggerConfig, LookupBuilder, type LookupOptions, type LookupPopulateOptions, type LookupPopulateResult, MONGOKIT_CAPABILITIES, MONGOKIT_PLUGIN_NAMES, MUTATING_OPERATIONS, type Middleware, type MiddlewareContext, type MinMaxResult, type MinimalRepoView, type ModelBlueprint, ModelCollisionError, type ModelSpec, type MongoKitPluginName, type MongoOperationsMethods, type MongoOperatorUpdate, type MongoRepoCapabilities, type MongokitPageExtras, type MultiTenantOptions, type NonNullableFields, OP_REGISTRY, type ObjectId, type ObservabilityOptions, type OffsetPaginationOptions, type OperationDescriptor, type OperationMetric, type OperationOptions, type OperationType, type PaginationConfig, type PaginationDefaults, PaginationEngine, type ParseDuplicateKeyOptions, type ParsedQuery, type PartialBy, type Plugin, type PluginFunction, type PluginType, type PolicyKey, type PopulateOption, type PopulateSpec, type PrefixedIdOptions, type PrioritizedHook, type ProjectionSpec, type PurgeMode, type PurgeableRepoLike, QueryParser, type QueryParserOptions, type QuerySchema, READ_OPERATIONS, type ReadOptions, type ReadPreferenceType, type ReferencePurgeResult, type ReferenceRelation, Repository, Repository as default, type RepositoryCacheHandle, type RepositoryCachePluginOptions, type RepositoryContext, type RepositoryEvent, type RepositoryInstance, type RepositoryOperation, type RepositoryOptions, type RepositoryPluginName, type RequiredBy, type SchemaLike, type SearchMode, type SelectSpec, type SequentialIdOptions, type SessionOptions, type SessionStarter, type SoftDeleteFilterMode, type SoftDeleteMethods, type SoftDeleteOptions, type SoftDeleteRepository, type SortDirection, type SortSpec$1 as SortSpec, type Strict, type SubdocumentMethods, type TenantContext, type TenantStore, type TransactionSupport, type TransitionMachine, type UpdateManyResult, type UpdateOptions, type UpdatePatch, type UpdateWithValidationResult, type UserContext, type ValidationChainOptions, type ValidatorDefinition, type ValueType, type VectorSearchOptions, type WithPlugins, type WithTransactionOptions, index_d_exports as actions, adminBypass, aggregateHelpersPlugin, appendOnlyPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, batchTransaction, blockIf, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, cachePlugin, capabilitiesForSupport, cascadePlugin, cascadePurgeReferences, classifyHelloReply, compileFilterToMongo, configureLogger, configurePaginationDefaults, createError, createFieldPreset, createMemoryCache, createOptionsExtractor, createRepository, createTenantContext, customIdPlugin, dateSequentialId, defineModel, defineModels, elasticSearchPlugin, ensureAuditTrailReady, fieldFilterPlugin, filterResponseData, getFieldsForUser, getMongooseProjection, getNextSequence, getPaginationDefaults, idVariants, idempotencyStorePlugin, immutableField, immutableStatesPlugin, isCreateManyPartialError, isDuplicateKeyError, isModelRegistered, isTransactionUnsupported, leasePlugin, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, operationsByPolicyKey, parseDuplicateKeyError, prefixedId, probeMongoCapabilities, repoOptionsFromCtx, requireField, resetCapabilityProbeCache, resetPaginationDefaults, resolveMongoCapabilities, resolveTransactionSupport, sequentialId, softDeletePlugin, subdocumentPlugin, supportsTransactions, systemContext, timestampPlugin, toPlain, transactionResolutionOf, uniqueField, validationChainPlugin, withTransaction };

package/dist/index.mjs

@@ -1,16 +1,16 @@
 import { n as idVariants } from "./id-resolution-BqDrk0S2.mjs";
-import { _ as resetCapabilityProbeCache, a as supportsTransactions, b as transactionResolutionOf, c as ALL_OPERATIONS, d as READ_OPERATIONS, f as operationsByPolicyKey, g as probeMongoCapabilities, h as classifyHelloReply, i as isTransactionUnsupported, l as MUTATING_OPERATIONS, m as capabilitiesForSupport, n as Repository, o as withTransaction, p as MONGOKIT_CAPABILITIES, r as batchTransaction, s as AggregationBuilder, t as HOOK_PRIORITY, u as OP_REGISTRY, v as resolveMongoCapabilities, x as createMongoPurgePort, y as resolveTransactionSupport } from "./Repository-BArvU32x.mjs";
-import { b as LookupBuilder, x as compileFilterToMongo } from "./update-jSXp3nu3.mjs";
+import { _ as resetCapabilityProbeCache, a as supportsTransactions, b as transactionResolutionOf, c as ALL_OPERATIONS, d as READ_OPERATIONS, f as operationsByPolicyKey, g as probeMongoCapabilities, h as classifyHelloReply, i as isTransactionUnsupported, l as MUTATING_OPERATIONS, m as capabilitiesForSupport, n as Repository, o as withTransaction, p as MONGOKIT_CAPABILITIES, r as batchTransaction, s as AggregationBuilder, t as HOOK_PRIORITY, u as OP_REGISTRY, v as resolveMongoCapabilities, x as createMongoPurgePort, y as resolveTransactionSupport } from "./Repository-D7fDpyFx.mjs";
+import { _ as compileFilterToMongo, g as LookupBuilder, x as isCreateManyPartialError } from "./update-c_01A0if.mjs";
 import { n as warn, t as configureLogger } from "./logger-K7dPmu2U.mjs";
 import { n as isDuplicateKeyError, r as parseDuplicateKeyError, t as createError } from "./error-BuByZwKU.mjs";
 import { t as actions_exports } from "./actions/index.mjs";
-import { a as customIdPlugin, c as prefixedId, d as AuditTrailQuery, f as auditTrailPlugin, i as multiTenantPlugin, l as sequentialId, m as auditLogPlugin, n as softDeletePlugin, o as dateSequentialId, p as ensureAuditTrailReady, r as adminBypass, s as getNextSequence, t as timestampPlugin, u as cachePlugin } from "./timestamp.plugin-BEc6TANm.mjs";
-import { n as batchOperationsPlugin, t as methodRegistryPlugin } from "./method-registry.plugin-DblM7V6j.mjs";
-import { t as PaginationEngine } from "./PaginationEngine-GdyX29tE.mjs";
+import { a as customIdPlugin, c as prefixedId, d as AuditTrailQuery, f as auditTrailPlugin, i as multiTenantPlugin, l as sequentialId, m as auditLogPlugin, n as softDeletePlugin, o as dateSequentialId, p as ensureAuditTrailReady, r as adminBypass, s as getNextSequence, t as timestampPlugin, u as cachePlugin } from "./timestamp.plugin-B5eiaItQ.mjs";
+import { n as batchOperationsPlugin, t as methodRegistryPlugin } from "./method-registry.plugin-C63pGn1d.mjs";
+import { a as getPaginationDefaults, i as configurePaginationDefaults, o as resetPaginationDefaults, t as PaginationEngine } from "./PaginationEngine-DQ7beTCR.mjs";
 import { isGeoOperator, parseGeoFilter } from "./query/primitives/geo.mjs";
-import { t as createRepository } from "./create-repository-CPNbktFG.mjs";
+import { t as createRepository } from "./create-repository-DOe9E_5F.mjs";
 import { n as defineModel, r as isModelRegistered, t as ModelCollisionError } from "./model-registry-ClKtWiHa.mjs";
-import { _ as cascadePlugin, a as uniqueField, c as subdocumentPlugin, d as mongoOperationsPlugin, f as leasePlugin, g as elasticSearchPlugin, h as fieldFilterPlugin, i as requireField, l as observabilityPlugin, m as idempotencyStorePlugin, n as blockIf, o as validationChainPlugin, p as immutableStatesPlugin, r as immutableField, s as createTenantContext, t as autoInject, u as MONGOKIT_PLUGIN_NAMES, v as appendOnlyPlugin, y as aggregateHelpersPlugin } from "./validation-chain.plugin-CyK1s9Ze.mjs";
+import { _ as cascadePlugin, a as uniqueField, c as subdocumentPlugin, d as mongoOperationsPlugin, f as leasePlugin, g as elasticSearchPlugin, h as fieldFilterPlugin, i as requireField, l as observabilityPlugin, m as idempotencyStorePlugin, n as blockIf, o as validationChainPlugin, p as immutableStatesPlugin, r as immutableField, s as createTenantContext, t as autoInject, u as MONGOKIT_PLUGIN_NAMES, v as appendOnlyPlugin, y as aggregateHelpersPlugin } from "./validation-chain.plugin-Bju1D1Sn.mjs";
 import { i as getMongooseProjection, n as filterResponseData, r as getFieldsForUser, t as createFieldPreset } from "./field-selection-FSQFLpsU.mjs";
 import { buildFieldTypeMap, coerceFieldValue, coerceHeuristic } from "./query/primitives/coercion.mjs";
 import { extractSchemaIndexes } from "./query/primitives/indexes.mjs";
@@ -509,6 +509,11 @@ function parseFilters(rt, filters, depth = 0) {
 			rt.reject(`Blocked filter field not in allowlist: ${baseField}`, { field: baseField });
 			continue;
 		}
+		if (key === "$and") {
+			const branches = parseCompoundBranches(rt, value, depth);
+			if (branches.length > 0) parsedFilters.$and = branches;
+			continue;
+		}
 		if (operatorMatch) {
 			const [, , operator] = operatorMatch;
 			if (rt.dangerousOperators.includes(`$${operator}`)) {
@@ -707,6 +712,24 @@ function handleBracketSyntax(rt, field, operators, parsedFilters, depth = 0) {
 	if (typeof parsedFilters[field] === "object" && Object.keys(parsedFilters[field]).length === 0) delete parsedFilters[field];
 }
 /** Parse `?or=[...]` / `?OR=[...]` / `?$or=[...]` groups into an $or array. */
+/**
+* Parse the branches of a compound operator (`$and`, and the body of `$or`).
+*
+* Every branch goes back through `parseFilters`, so the operator block, the allowlist and the
+* regex budget all apply inside it. Branches that parse to `{}` are DROPPED: a branch holding
+* only a blocked operator would otherwise become match-all, which widens the query instead of
+* failing it — the exact shape `parseOr` documents below.
+*/
+function parseCompoundBranches(rt, raw, depth) {
+	const items = Array.isArray(raw) ? raw : typeof raw === "object" && raw ? Object.values(raw) : [];
+	const branches = [];
+	for (const item of items) {
+		if (typeof item !== "object" || !item) continue;
+		const parsed = parseFilters(rt, item, depth + 1);
+		if (Object.keys(parsed).length > 0) branches.push(parsed);
+	}
+	return branches;
+}
 function parseOr(rt, query) {
 	const orArray = [];
 	const raw = query?.or || query?.OR || query?.$or;
@@ -1758,4 +1781,4 @@ function systemContext(extra) {
 */
 var src_default = Repository;
 //#endregion
-export { ALL_OPERATIONS, AggregationBuilder, AuditTrailQuery, HOOK_PRIORITY, LookupBuilder, MONGOKIT_CAPABILITIES, MONGOKIT_PLUGIN_NAMES, MUTATING_OPERATIONS, ModelCollisionError, OP_REGISTRY, PaginationEngine, QueryParser, READ_OPERATIONS, Repository, actions_exports as actions, adminBypass, aggregateHelpersPlugin, appendOnlyPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, batchTransaction, blockIf, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, cachePlugin, capabilitiesForSupport, cascadePlugin, cascadePurgeReferences, classifyHelloReply, compileFilterToMongo, configureLogger, createError, createFieldPreset, createMemoryCache, createOptionsExtractor, createRepository, createTenantContext, customIdPlugin, dateSequentialId, src_default as default, defineModel, defineModels, elasticSearchPlugin, ensureAuditTrailReady, fieldFilterPlugin, filterResponseData, getFieldsForUser, getMongooseProjection, getNextSequence, idVariants, idempotencyStorePlugin, immutableField, immutableStatesPlugin, isDuplicateKeyError, isModelRegistered, isTransactionUnsupported, leasePlugin, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, operationsByPolicyKey, parseDuplicateKeyError, prefixedId, probeMongoCapabilities, repoOptionsFromCtx, requireField, resetCapabilityProbeCache, resolveMongoCapabilities, resolveTransactionSupport, sequentialId, softDeletePlugin, subdocumentPlugin, supportsTransactions, systemContext, timestampPlugin, toPlain, transactionResolutionOf, uniqueField, validationChainPlugin, withTransaction };
+export { ALL_OPERATIONS, AggregationBuilder, AuditTrailQuery, HOOK_PRIORITY, LookupBuilder, MONGOKIT_CAPABILITIES, MONGOKIT_PLUGIN_NAMES, MUTATING_OPERATIONS, ModelCollisionError, OP_REGISTRY, PaginationEngine, QueryParser, READ_OPERATIONS, Repository, actions_exports as actions, adminBypass, aggregateHelpersPlugin, appendOnlyPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, batchTransaction, blockIf, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, cachePlugin, capabilitiesForSupport, cascadePlugin, cascadePurgeReferences, classifyHelloReply, compileFilterToMongo, configureLogger, configurePaginationDefaults, createError, createFieldPreset, createMemoryCache, createOptionsExtractor, createRepository, createTenantContext, customIdPlugin, dateSequentialId, src_default as default, defineModel, defineModels, elasticSearchPlugin, ensureAuditTrailReady, fieldFilterPlugin, filterResponseData, getFieldsForUser, getMongooseProjection, getNextSequence, getPaginationDefaults, idVariants, idempotencyStorePlugin, immutableField, immutableStatesPlugin, isCreateManyPartialError, isDuplicateKeyError, isModelRegistered, isTransactionUnsupported, leasePlugin, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, operationsByPolicyKey, parseDuplicateKeyError, prefixedId, probeMongoCapabilities, repoOptionsFromCtx, requireField, resetCapabilityProbeCache, resetPaginationDefaults, resolveMongoCapabilities, resolveTransactionSupport, sequentialId, softDeletePlugin, subdocumentPlugin, supportsTransactions, systemContext, timestampPlugin, toPlain, transactionResolutionOf, uniqueField, validationChainPlugin, withTransaction };

package/dist/indexes/verify-indexes.d.mts

@@ -0,0 +1,69 @@
+//#region src/indexes/verify-indexes.d.ts
+/**
+ * Compare DECLARED indexes against what a database actually has.
+ *
+ * `unique: true` on a schema is a correctness constraint only if the index was
+ * built. A skipped deploy step is otherwise SILENT — one deployment ran with
+ * 401 declared indexes absent, accumulated duplicate rows on a "unique" field,
+ * and nothing anywhere said the constraint did not exist. mongokit owns the
+ * declaration, so it owns the means to check it.
+ *
+ * Read-only. It NEVER builds: index builds belong to a deploy step, not to a
+ * serving process.
+ *
+ * Missing UNIQUE indexes are reported separately from missing regular ones —
+ * the first silently admits duplicate data, the second only costs a scan.
+ *
+ * DELIBERATELY ONE-DIRECTIONAL: an index present in the database but absent
+ * from a schema is NOT drift. Auth libraries and migrations manage indexes
+ * outside the ODM, and treating those as removable is exactly what makes a
+ * `syncIndexes()` unsafe.
+ *
+ * Sibling of `query/primitives/indexes`, which reads DECLARATIONS only and
+ * touches no connection. This module is the live comparison.
+ */
+/** The slice of a Mongoose-like connection this needs. Structural on purpose. */
+interface IndexVerifiableConnection {
+  modelNames(): string[];
+  model(name: string): IndexVerifiableModel;
+}
+interface IndexVerifiableModel {
+  schema: {
+    indexes(): Array<[Record<string, unknown>, Record<string, unknown>?]>;
+  };
+  collection: {
+    name: string;
+    listIndexes(): {
+      toArray(): Promise<Array<Record<string, unknown>>>;
+    };
+  };
+}
+interface MissingIndex {
+  model: string;
+  collection: string;
+  /** The declared key, JSON-stringified — stable to log and to diff. */
+  key: string;
+}
+interface IndexVerifyReport {
+  modelsChecked: number;
+  /** Declared `unique` indexes with nothing behind them. Duplicates can already exist. */
+  missingUnique: MissingIndex[];
+  missingRegular: MissingIndex[];
+  /** Models whose indexes could not be read — collection absent, or no permission. */
+  unreadable: string[];
+}
+interface VerifyIndexesOptions {
+  /**
+   * Include a model in the sweep. Default: every model.
+   *
+   * A kernel that materialises different model sets per mode must skip exactly
+   * the set its deploy step skips — indexing a model CREATES its collection, so
+   * a mismatch here reports permanent phantom drift instead of a real gap.
+   */
+  includeModel?: (modelName: string) => boolean;
+}
+declare function verifyIndexes(connection: IndexVerifiableConnection, options?: VerifyIndexesOptions): Promise<IndexVerifyReport>;
+/** One-line summary for a boot log. */
+declare function formatIndexReport(report: IndexVerifyReport): string;
+//#endregion
+export { IndexVerifiableConnection, IndexVerifiableModel, IndexVerifyReport, MissingIndex, VerifyIndexesOptions, formatIndexReport, verifyIndexes };

package/dist/indexes/verify-indexes.mjs

@@ -0,0 +1,76 @@
+//#region src/indexes/verify-indexes.ts
+/**
+* Order-sensitive: a compound index is not the same index with keys swapped.
+*
+* A SINGLE-field numeric index is direction-agnostic though — mongo traverses
+* an index either way, so `{t:1}` and `{t:-1}` are the same index and a schema
+* declaring one against a database holding the other is not drift. Only numeric
+* directions collapse; `2dsphere` / `hashed` are index TYPES, not directions.
+*/
+function normalizeKey(key) {
+	const entries = Object.entries(key);
+	if (entries.length === 1 && typeof entries[0]?.[1] === "number") return JSON.stringify([[entries[0][0]]]);
+	return JSON.stringify(entries);
+}
+/**
+* A TEXT index is stored under a key mongo invents (`{_fts, _ftsx}`) with the
+* real fields moved to `weights`, so it never matches its own declaration by
+* key. Compare the field SET instead, or every text index reads as permanently
+* missing and the whole check becomes noise nobody reads.
+*/
+function textFields(key) {
+	const fields = Object.entries(key).filter(([, dir]) => dir === "text").map(([field]) => field);
+	return fields.length > 0 ? fields.sort() : null;
+}
+async function verifyIndexes(connection, options = {}) {
+	const include = options.includeModel ?? (() => true);
+	const report = {
+		modelsChecked: 0,
+		missingUnique: [],
+		missingRegular: [],
+		unreadable: []
+	};
+	for (const name of connection.modelNames().sort()) {
+		if (!include(name)) continue;
+		const model = connection.model(name);
+		const declared = model.schema.indexes();
+		if (declared.length === 0) continue;
+		let existing;
+		let existingText;
+		try {
+			const live = await model.collection.listIndexes().toArray();
+			existing = new Set(live.map((i) => normalizeKey(i.key)));
+			existingText = new Set(live.filter((i) => i.weights).map((i) => JSON.stringify(Object.keys(i.weights).sort())));
+		} catch {
+			report.unreadable.push(name);
+			continue;
+		}
+		report.modelsChecked += 1;
+		for (const [key, indexOptions] of declared) {
+			const asText = textFields(key);
+			if (asText) {
+				if (existingText.has(JSON.stringify(asText))) continue;
+			} else if (existing.has(normalizeKey(key))) continue;
+			const entry = {
+				model: name,
+				collection: model.collection.name,
+				key: JSON.stringify(key)
+			};
+			if (indexOptions?.unique) report.missingUnique.push(entry);
+			else report.missingRegular.push(entry);
+		}
+	}
+	return report;
+}
+/** One-line summary for a boot log. */
+function formatIndexReport(report) {
+	const parts = [
+		`${report.modelsChecked} models checked`,
+		`missing unique: ${report.missingUnique.length}`,
+		`missing regular: ${report.missingRegular.length}`
+	];
+	if (report.unreadable.length > 0) parts.push(`unreadable: ${report.unreadable.length}`);
+	return `[index-check] ${parts.join(" — ")}`;
+}
+//#endregion
+export { formatIndexReport, verifyIndexes };

package/dist/{method-registry.plugin-DblM7V6j.mjs → method-registry.plugin-C63pGn1d.mjs}

@@ -16,6 +16,58 @@ import { t as createError } from "./error-BuByZwKU.mjs";
 * // bulkWrite is what this plugin contributes.
 * await repo.bulkWrite([...ops]);
 */
+/**
+* Driver options `bulkWrite` forwards, and the only ones it forwards.
+*
+* The signature used to be `{ session?, ordered?, [key: string]: unknown }` and
+* the call forwarded exactly two of them. So `writeConcern: { w: 'majority' }`
+* on a money import was accepted by the type, dropped on the floor, and the
+* write went out under the default concern with nothing raised.
+*/
+const BULK_WRITE_OPTIONS = [
+	"ordered",
+	"session",
+	"writeConcern",
+	"bypassDocumentValidation",
+	"comment",
+	"let",
+	"ignoreUndefined"
+];
+/**
+* Driver options that EXIST but this method does not forward.
+*
+* The options bag is dual-purpose by design: it is spread into
+* `_buildContext`, so it also carries plugin context — `organizationId` for
+* multi-tenant scoping, and whatever else a host's plugins read off it.
+* Refusing every unrecognised key therefore breaks legitimate callers, which
+* is exactly how the first version of this fence failed: it rejected the
+* tenant id and took two passing tests with it.
+*
+* So the line sits where the caller's expectation is. If the DRIVER would
+* understand the option and we would silently not pass it on, refuse — that is
+* the case where someone believes they configured the write. A key the driver
+* does not know either is plugin context, and passes through untouched.
+*/
+const UNSUPPORTED_DRIVER_OPTIONS = /* @__PURE__ */ new Set([
+	"forceServerObjectId",
+	"timeoutMS",
+	"maxTimeMS",
+	"retryWrites",
+	"checkKeys",
+	"serializeFunctions",
+	"enableUtf8Validation",
+	"raw",
+	"explain"
+]);
+/** Narrow the bag to driver options, refusing the ones we would silently drop. */
+function pickBulkWriteOptions(options) {
+	const dropped = Object.keys(options).filter((k) => UNSUPPORTED_DRIVER_OPTIONS.has(k));
+	if (dropped.length > 0) throw createError(400, `bulkWrite: option(s) ${dropped.map((k) => `'${k}'`).join(", ")} are MongoDB driver options this method does not forward. Refused rather than ignored, because silently dropping one changes what the write does. Supported: ${BULK_WRITE_OPTIONS.join(", ")}.`);
+	const out = {};
+	for (const key of BULK_WRITE_OPTIONS) if (options[key] !== void 0) out[key] = options[key];
+	out.ordered = options.ordered ?? true;
+	return out;
+}
 function batchOperationsPlugin() {
 	return {
 		name: "batch-operations",
@@ -36,6 +88,7 @@ function batchOperationsPlugin() {
 			* ]);
 			*/
 			repo.registerMethod("bulkWrite", async function(operations, options = {}) {
+				const driverOptions = pickBulkWriteOptions(options);
 				const context = await this._buildContext("bulkWrite", {
 					operations,
 					...options
@@ -43,10 +96,7 @@ function batchOperationsPlugin() {
 				try {
 					const finalOps = context.operations || operations;
 					if (!finalOps || finalOps.length === 0) throw createError(400, "bulkWrite requires at least one operation");
-					const result = await this.Model.bulkWrite(finalOps, {
-						ordered: options.ordered ?? true,
-						session: options.session
-					});
+					const result = await this.Model.bulkWrite(finalOps, driverOptions);
 					const bulkResult = {
 						ok: result.ok,
 						insertedCount: result.insertedCount,

package/dist/{multi-tenant.plugin-BwSvTirB.d.mts → multi-tenant.plugin-B-tzNeYL.d.mts}

@@ -1,5 +1,5 @@
-import { i as ObjectId } from "./core-62oo3N1C.mjs";
-import { l as Plugin, p as RepositoryContext } from "./repository-H_ffGgpE.mjs";
+import { g as ObjectId } from "./pagination-BpIv2bdS.mjs";
+import { l as Plugin, p as RepositoryContext } from "./repository-ZbLtL7Nk.mjs";
 import mongoose, { Connection } from "mongoose";
 import { CacheAdapter as CacheAdapter$1, CacheOptions, RepositoryCacheHandle as RepositoryCacheHandle$1, RepositoryCachePluginOptions, cachePlugin } from "@classytic/repo-core/cache";
 import { TenantConfig } from "@classytic/repo-core/tenant";
@@ -312,7 +312,10 @@ interface SequentialIdOptions {
   prefix: string;
   /** Mongoose model — used to derive the counter key from model name */
   model: mongoose.Model<any>;
-  /** Number of digits to pad to (default: 4 → "0001") */
+  /**
+   * MINIMUM number of digits (default: 4 → "0001"). Never truncates —
+   * sequence 10000 under `padding: 4` renders as `INV-10000`.
+   */
   padding?: number;
   /** Separator between prefix and number (default: '-') */
   separator?: string;
@@ -346,10 +349,54 @@ interface DateSequentialIdOptions {
    * - 'daily'   → BILL-2026-02-20-0001, resets every day
    */
   partition?: 'yearly' | 'monthly' | 'daily';
-  /** Number of digits to pad to (default: 4) */
+  /**
+   * MINIMUM number of digits for the sequence (default: 4). `padStart` never
+   * truncates, so the 10,000th id of a period under `padding: 4` is
+   * `BILL-2026-10000` — it grows a digit rather than wrapping to `0000`.
+   * Lexical sort order therefore only holds while a period stays below
+   * 10^padding; size the padding for your peak period.
+   */
   padding?: number;
   /** Separator (default: '-') */
   separator?: string;
+  /**
+   * Counter scope.
+   * - `'global'` (default) — one counter per model + period, shared by
+   *   every tenant in the database. Ids are unique across the deployment.
+   * - `'tenant'` — one counter per tenant + model + period, keyed by
+   *   `context[tenantKey]`. Every tenant's numbering starts at 1 (Shopify-
+   *   style per-shop order numbers) and the write hot spot on the single
+   *   shared counter document splits per tenant. Ids are unique WITHIN a
+   *   tenant only — index the field compound with the tenant field.
+   *   Fails closed: a create with no tenant in context throws rather than
+   *   falling back to the global key, which would silently merge two
+   *   tenants' sequences.
+   */
+  scope?: 'global' | 'tenant';
+  /**
+   * Context key carrying the tenant id under `scope: 'tenant'` (default:
+   * `'organizationId'` — the same default as `multiTenantPlugin`'s
+   * `contextKey`, so `repo.create(data, { organizationId })` feeds both).
+   */
+  tenantKey?: string;
+  /**
+   * Which clock decides the period boundary.
+   *
+   * - `'local'` (default) — the server's `TZ`. Kept as the default because it
+   *   is what every existing deployment already generated: flipping it would
+   *   retroactively change which period an id near a month boundary belongs
+   *   to, and those ids are invoice and order numbers.
+   * - `'utc'` — **the correct choice for more than one replica.** Two replicas
+   *   with different `TZ` settings derive different counter keys for the same
+   *   logical month and each increments its own, so the same number is issued
+   *   twice inside one tenant-period. UTC is the one boundary every replica
+   *   agrees on. It also matches the ecosystem's other period key,
+   *   `usagePeriod()` in `@classytic/repo-core/usage`.
+   *
+   * Containers usually run UTC anyway, which is exactly why the difference
+   * stays invisible until one host is configured otherwise.
+   */
+  timezone?: 'local' | 'utc';
 }
 /**
  * Generator: Date-partitioned sequential counter.
@@ -371,6 +418,15 @@ interface DateSequentialIdOptions {
  *   }),
  * })
  * ```
+ *
+ * @example Per-tenant numbering in a shared database
+ * ```typescript
+ * customIdPlugin({
+ *   field: 'orderNumber',
+ *   generator: dateSequentialId({ prefix: 'ORD', model: OrderModel, scope: 'tenant' }),
+ * })
+ * // org-a: ORD-2026-02-0001, ORD-2026-02-0002 …   org-b: ORD-2026-02-0001 …
+ * ```
  */
 declare function dateSequentialId(options: DateSequentialIdOptions): IdGenerator;
 interface PrefixedIdOptions {