@classytic/mongokit 3.13.3 → 3.13.4

package/dist/{Repository-CNBTCVat.mjs → Repository-BZrU_nXs.mjs}

@@ -1,4 +1,4 @@
-import { a as count, b as LookupBuilder, c as getByQuery, d as deleteById, f as deleteByQuery, h as createMany, l as getOrCreate, m as create, n as update, o as exists, r as updateByQuery, s as getById, t as findOneAndUpdate, x as compileFilterToMongo, y as distinct } from "./update-C-3viiw1.mjs";
+import { a as count, b as LookupBuilder, c as getByQuery, d as deleteById, f as deleteByQuery, h as createMany, l as getOrCreate, m as create, n as update, o as exists, r as updateByQuery, s as getById, t as findOneAndUpdate, x as compileFilterToMongo, y as distinct } from "./update-BXMnCvO6.mjs";
 import { n as warn } from "./logger-DprijP5h.mjs";
 import { n as isDuplicateKeyError, r as parseDuplicateKeyError, t as createError } from "./error-B00pI7dV.mjs";
 import { t as PaginationEngine } from "./PaginationEngine-CfQRM1yz.mjs";

package/dist/actions/index.d.mts

@@ -1,2 +1,2 @@
-import { a as create_d_exports, i as delete_d_exports, n as update_d_exports, o as aggregate_d_exports, r as read_d_exports } from "../index-BbHaKwi5.mjs";
+import { a as create_d_exports, i as delete_d_exports, n as update_d_exports, o as aggregate_d_exports, r as read_d_exports } from "../index-Dccha9dw.mjs";
 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 };

package/dist/actions/index.mjs

@@ -1,5 +1,5 @@
 import { t as __exportAll } from "../chunk-CfYAbeIz.mjs";
-import { g as create_exports, i as update_exports, p as delete_exports, u as read_exports, v as aggregate_exports } from "../update-C-3viiw1.mjs";
+import { g as create_exports, i as update_exports, p as delete_exports, u as read_exports, v as aggregate_exports } from "../update-BXMnCvO6.mjs";
 //#region src/actions/index.ts
 var actions_exports = /* @__PURE__ */ __exportAll({
 	aggregate: () => aggregate_exports,

package/dist/better-auth/index.mjs

@@ -1,4 +1,4 @@
-import { n as Repository } from "../Repository-CNBTCVat.mjs";
+import { n as Repository } from "../Repository-BZrU_nXs.mjs";
 import { n as createMongooseAdapter } from "../adapter-DTDMnUOH.mjs";
 import { pluralizeBetterAuthCollection, resolveBetterAuthCollections } from "@classytic/repo-core/better-auth";
 //#region src/better-auth/index.ts

package/dist/{index-BbHaKwi5.d.mts → index-Dccha9dw.d.mts}

@@ -175,7 +175,9 @@ declare function getById<TDoc = AnyDocument>(Model: Model<TDoc>, id: string | Ob
  * @returns Document or null
  * @throws Error if document not found and throwOnNotFound is true
  */
-declare function getByQuery<TDoc = AnyDocument>(Model: Model<TDoc>, query: Record<string, unknown>, options?: OperationOptions): Promise<TDoc | null>;
+declare function getByQuery<TDoc = AnyDocument>(Model: Model<TDoc>, query: Record<string, unknown>, options?: OperationOptions & {
+  sort?: SortSpec;
+}): Promise<TDoc | null>;
 /**
  * Get document by query without throwing (returns null if not found)
  */

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { $ as RepositoryEvent, A as KeysetPaginationOptions, B as ObjectId, C as FieldPreset, Ct as IControllerResponse, D as InferDocument, Dt as LookupOptions, E as HookMode, Et as LookupBuilder, F as MiddlewareContext, G as Plugin, H as OperationOptions, I as MinMaxResult, J as PopulateSpec, K as PluginFunction, L as MinimalRepoView, M as LookupPopulateOptions, N as LookupPopulateResult, O as InferRawDoc, P as Middleware, Q as RepositoryContext, R as MongoOperatorUpdate, S as EventPhase, St as IController, T as GroupResult, Tt as IResponseFormatter, U as PaginationConfig, V as OffsetPaginationOptions, W as PartialBy, X as ReadOptions, Y as PrioritizedHook, Z as ReadPreferenceType, _ as DeleteManyResult, _t as ValidationChainOptions, a as AnyModel, at as SessionOptions, b as EventHandlers, bt as WithPlugins, c as CacheableOptions, ct as SoftDeleteRepository, d as CollationOptions, dt as Strict, et as RepositoryInstance, f as CreateInput, ft as UpdateManyResult, g as DeepPartial, gt as UserContext, h as DecodedCursor, ht as UpdateWithValidationResult, i as AnyDocument, it as SelectSpec, j as Logger, k as KeysOfType, l as CascadeOptions, lt as SortDirection, m as CursorPayload, mt as UpdatePatch, n as AggregatePaginationOptions, nt as RepositoryOptions, o as BasePaginationOptions, ot as SoftDeleteFilterMode, p as CreateOptions, pt as UpdateOptions, q as PluginType, r as AllPluginMethods, rt as RequiredBy, s as CacheOperationOptions, st as SoftDeleteOptions, t as AggregateOptions, tt as RepositoryOperation, u as CascadeRelation, ut as SortSpec, v as DeleteResult, vt as ValidatorDefinition, w as FindOneAndUpdateOptions, wt as IRequestContext, x as EventPayload, xt as WithTransactionOptions, y as DocField, yt as ValueType, z as NonNullableFields } from "./types-BbaPZleN.mjs";
-import { t as index_d_exports } from "./index-BbHaKwi5.mjs";
+import { t as index_d_exports } from "./index-Dccha9dw.mjs";
 import { PaginationEngine } from "./pagination/PaginationEngine.mjs";
 import { $ as AuditQueryResult, A as elasticSearchPlugin, B as sequentialId, D as leasePlugin, E as LeasePluginOptions, F as SequentialIdOptions, G as RepositoryCachePluginOptions, H as CacheAdapter, I as customIdPlugin, J as BulkWriteResult, K as cachePlugin, L as dateSequentialId, M as DateSequentialIdOptions, N as IdGenerator, O as fieldFilterPlugin, P as PrefixedIdOptions, Q as AuditQueryOptions, R as getNextSequence, S as mongoOperationsPlugin, T as LeaseMethods, U as CacheOptions, V as cascadePlugin, W as RepositoryCacheHandle, X as AuditEntry, Y as batchOperationsPlugin, Z as AuditOperation, _ as observabilityPlugin, a as uniqueField, at as AggregateHelpersMethods, b as multiTenantPlugin, c as TenantContext, d as SubdocumentMethods, et as AuditTrailMethods, f as subdocumentPlugin, g as OperationMetric, h as ObservabilityOptions, i as requireField, it as auditLogPlugin, j as CustomIdOptions, k as ElasticSearchOptions, l as TenantStore, m as softDeletePlugin, n as blockIf, nt as AuditTrailQuery, o as validationChainPlugin, ot as aggregateHelpersPlugin, p as SoftDeleteMethods, q as BatchOperationsMethods, r as immutableField, rt as auditTrailPlugin, s as timestampPlugin, t as autoInject, tt as AuditTrailOptions, u as createTenantContext, v as MultiTenantOptions, w as methodRegistryPlugin, x as MongoOperationsMethods, y as adminBypass, z as prefixedId } from "./validation-chain.plugin-CAPYCj_T.mjs";
 import { n as SchemaPathsLike, t as FieldType$1 } from "./coercion-TRMmR49h.mjs";
@@ -1095,7 +1095,9 @@ declare class Repository<TDoc = unknown> extends RepositoryBase {
   /**
    * Get single document by query
    */
-  getByQuery(query: Record<string, unknown>, options?: CacheableOptions): Promise<TDoc | null>;
+  getByQuery(query: Record<string, unknown>, options?: CacheableOptions & {
+    sort?: SortSpec;
+  }): Promise<TDoc | null>;
   /**
    * Get single document by arbitrary filter.
    * Unlike getByQuery, this method is designed for Arc/controller use where
@@ -1104,7 +1106,9 @@ declare class Repository<TDoc = unknown> extends RepositoryBase {
    * @example
    * const product = await repo.getOne({ slug: 'laptop', organizationId: 'org_1' });
    */
-  getOne(query: Record<string, unknown>, options?: CacheableOptions): Promise<TDoc | null>;
+  getOne(query: Record<string, unknown>, options?: CacheableOptions & {
+    sort?: SortSpec;
+  }): Promise<TDoc | null>;
   /**
    * Fetch ALL documents matching filters without pagination.
    * Use for background jobs, exports, batch processing where you need every doc.
@@ -2137,6 +2141,80 @@ declare function repoOptionsFromCtx<TCtx extends Record<string, unknown>>(ctx: T
  *   options bag never erases inherited values).
  */
 declare function createOptionsExtractor<TCtx extends Record<string, unknown>>(fields: readonly (keyof TCtx & string)[]): (ctx: TCtx | undefined | null) => Record<string, unknown>;
+/**
+ * Canonical options bag for repo calls made OUTSIDE any request scope —
+ * event handlers, cron jobs, queue workers, migration scripts.
+ *
+ * `multiTenantPlugin` requires `organizationId` in the operation
+ * context so reads/writes can't leak across tenants from the request
+ * layer. Background work has no inherited request scope; calling a
+ * tenant-aware repo from an event subscriber without a bypass throws:
+ *
+ *   "[mongokit] Multi-tenant: Missing 'organizationId' in context for ..."
+ *
+ * Worse, if the call site is wrapped in `try/catch` (as event handlers
+ * routinely are — they fire-and-forget), the error is swallowed and
+ * the side effect silently doesn't happen. We've shipped that bug.
+ *
+ * `systemContext()` returns the canonical opts bag for that case —
+ * currently `{ bypassTenant: true }`. The multi-tenant plugin still
+ * emits an `after:tenant-bypass` audit event with `reason: 'option'`
+ * so observability sees these calls distinct from request-scoped ones.
+ *
+ * **Greppable on purpose.** A reviewer scanning the codebase can find
+ * every "I'm running outside any tenant scope" callsite by searching
+ * `systemContext(` — no chasing magic option spreads.
+ *
+ * **NOT a substitute for proper access control.** Same caveat as raw
+ * `bypassTenant`: this bypasses tenant scoping; it does NOT bypass
+ * authentication or RBAC. Use only at trusted boundaries — event
+ * handlers wired at startup, cron jobs scheduled in code, scripts
+ * running with admin credentials.
+ *
+ * The `extra` overload composes cleanly with transaction sessions and
+ * audit-attribution fields; the function's `bypassTenant: true` is
+ * applied last so it cannot be accidentally overridden.
+ *
+ * @example Event handler
+ * ```ts
+ * import { systemContext } from '@classytic/mongokit';
+ *
+ * order.events.subscribe('order:completed', async (event) => {
+ *   const matches = await enrollmentRepo.aggregatePipeline(
+ *     [{ $match: { orderId: event.payload.orderId, status: 'active' } }],
+ *     systemContext(),
+ *   );
+ *   for (const m of matches) {
+ *     await enrollmentRepo.update(m._id, { status: 'fulfilled' }, systemContext());
+ *   }
+ * });
+ * ```
+ *
+ * @example Composed with a transaction
+ * ```ts
+ * await withTransaction(conn, async (session) => {
+ *   await enrollmentRepo.update(id, data, systemContext({ session }));
+ *   await auditRepo.create(entry, systemContext({ session }));
+ * });
+ * ```
+ *
+ * @example Cron / scheduled cleanup
+ * ```ts
+ * for await (const doc of repo.cursor(
+ *   { expiresAt: { $lt: new Date() } },
+ *   systemContext(),
+ * )) {
+ *   await repo.delete(doc._id, systemContext());
+ * }
+ * ```
+ *
+ * @param extra - Optional extra options to merge in (e.g. `session`
+ *   for transactions, `userId` for audit attribution). Any
+ *   `bypassTenant` value here is overridden — the function name is
+ *   load-bearing.
+ * @returns A `SessionOptions` object with `bypassTenant: true` set.
+ */
+declare function systemContext(extra?: SessionOptions): SessionOptions;
 //#endregion
 //#region src/index.d.ts
 /**
@@ -2151,4 +2229,4 @@ declare function createOptionsExtractor<TCtx extends Record<string, unknown>>(fi
  */
 declare function createRepository<TDoc>(Model: _$mongoose.Model<TDoc, any, any, any>, plugins?: PluginType[], paginationConfig?: PaginationConfig, options?: RepositoryOptions): Repository<TDoc>;
 //#endregion
-export { ALL_OPERATIONS, type AggregateHelpersMethods, type AggregateOptions, type AggregatePaginationOptions, AggregationBuilder, type AllPluginMethods, type AnyDocument, type AnyModel, type AuditEntry, type AuditOperation, type AuditQueryOptions, type AuditQueryResult, type AuditTrailMethods, type AuditTrailOptions, AuditTrailQuery, type BasePaginationOptions, type BatchOperationsMethods, type BulkWriteResult, type CacheAdapter, type CacheOperationOptions, type CacheOptions, type CacheableOptions, type CascadeOptions, type CascadeRelation, type CollationOptions, type CreateInput, type CreateOptions, type CursorPayload, type CustomIdOptions, type DateSequentialIdOptions, type DecodedCursor, type DeepPartial, type DeleteResult, type DocField, type ElasticSearchOptions, type EventHandlers, type EventPayload, type EventPhase, type FieldPreset, type FieldType, type FilterQuery, type FindOneAndUpdateOptions, type GroupResult, HOOK_PRIORITY, type HookMode, type IController, type IControllerResponse, type IRequestContext, type IResponseFormatter, type IdGenerator, type InferDocument, type InferRawDoc, type KeysOfType, type KeysetPaginationOptions, type LeaseMethods, type LeasePluginOptions, type Logger, LookupBuilder, type LookupOptions, type LookupPopulateOptions, type LookupPopulateResult, MUTATING_OPERATIONS, type Middleware, type MiddlewareContext, type MinMaxResult, type MinimalRepoView, type MongoOperationsMethods, type MongoOperatorUpdate, type MultiTenantOptions, type NonNullableFields, OP_REGISTRY, type ObjectId, type ObservabilityOptions, type OffsetPaginationOptions, type OperationDescriptor, type OperationMetric, type OperationOptions, type PaginationConfig, PaginationEngine, type ParsedQuery, type PartialBy, type Plugin, type PluginFunction, type PluginType, type PolicyKey, type PopulateOption, type PopulateSpec, type PrefixedIdOptions, type PrioritizedHook, QueryParser, type QueryParserOptions, READ_OPERATIONS, type ReadOptions, type ReadPreferenceType, Repository, Repository as default, type RepositoryCacheHandle, type RepositoryCachePluginOptions, type RepositoryContext, type RepositoryEvent, type RepositoryInstance, type RepositoryOperation, type RepositoryOptions, type RequiredBy, type SchemaLike, type SearchMode, type SelectSpec, type SequentialIdOptions, type SessionOptions, type SoftDeleteFilterMode, type SoftDeleteMethods, type SoftDeleteOptions, type SoftDeleteRepository, type SortDirection, type SortSpec, type Strict, type SubdocumentMethods, type TenantContext, type TenantStore, type UpdateManyResult, type UpdateOptions, type UpdatePatch, type UpdateWithValidationResult, type UserContext, type ValidationChainOptions, type ValidatorDefinition, type ValueType, type WithPlugins, type WithTransactionOptions, index_d_exports as actions, adminBypass, aggregateHelpersPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, batchTransaction, blockIf, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, cachePlugin, cascadePlugin, compileFilterToMongo, configureLogger, createError, createFieldPreset, createMemoryCache, createOptionsExtractor, createRepository, createTenantContext, customIdPlugin, dateSequentialId, elasticSearchPlugin, fieldFilterPlugin, filterResponseData, getFieldsForUser, getMongooseProjection, getNextSequence, immutableField, isDuplicateKeyError, isTransactionUnsupported, leasePlugin, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, operationsByPolicyKey, parseDuplicateKeyError, prefixedId, repoOptionsFromCtx, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validationChainPlugin, withTransaction };
+export { ALL_OPERATIONS, type AggregateHelpersMethods, type AggregateOptions, type AggregatePaginationOptions, AggregationBuilder, type AllPluginMethods, type AnyDocument, type AnyModel, type AuditEntry, type AuditOperation, type AuditQueryOptions, type AuditQueryResult, type AuditTrailMethods, type AuditTrailOptions, AuditTrailQuery, type BasePaginationOptions, type BatchOperationsMethods, type BulkWriteResult, type CacheAdapter, type CacheOperationOptions, type CacheOptions, type CacheableOptions, type CascadeOptions, type CascadeRelation, type CollationOptions, type CreateInput, type CreateOptions, type CursorPayload, type CustomIdOptions, type DateSequentialIdOptions, type DecodedCursor, type DeepPartial, type DeleteResult, type DocField, type ElasticSearchOptions, type EventHandlers, type EventPayload, type EventPhase, type FieldPreset, type FieldType, type FilterQuery, type FindOneAndUpdateOptions, type GroupResult, HOOK_PRIORITY, type HookMode, type IController, type IControllerResponse, type IRequestContext, type IResponseFormatter, type IdGenerator, type InferDocument, type InferRawDoc, type KeysOfType, type KeysetPaginationOptions, type LeaseMethods, type LeasePluginOptions, type Logger, LookupBuilder, type LookupOptions, type LookupPopulateOptions, type LookupPopulateResult, MUTATING_OPERATIONS, type Middleware, type MiddlewareContext, type MinMaxResult, type MinimalRepoView, type MongoOperationsMethods, type MongoOperatorUpdate, type MultiTenantOptions, type NonNullableFields, OP_REGISTRY, type ObjectId, type ObservabilityOptions, type OffsetPaginationOptions, type OperationDescriptor, type OperationMetric, type OperationOptions, type PaginationConfig, PaginationEngine, type ParsedQuery, type PartialBy, type Plugin, type PluginFunction, type PluginType, type PolicyKey, type PopulateOption, type PopulateSpec, type PrefixedIdOptions, type PrioritizedHook, QueryParser, type QueryParserOptions, READ_OPERATIONS, type ReadOptions, type ReadPreferenceType, Repository, Repository as default, type RepositoryCacheHandle, type RepositoryCachePluginOptions, type RepositoryContext, type RepositoryEvent, type RepositoryInstance, type RepositoryOperation, type RepositoryOptions, type RequiredBy, type SchemaLike, type SearchMode, type SelectSpec, type SequentialIdOptions, type SessionOptions, type SoftDeleteFilterMode, type SoftDeleteMethods, type SoftDeleteOptions, type SoftDeleteRepository, type SortDirection, type SortSpec, type Strict, type SubdocumentMethods, type TenantContext, type TenantStore, type UpdateManyResult, type UpdateOptions, type UpdatePatch, type UpdateWithValidationResult, type UserContext, type ValidationChainOptions, type ValidatorDefinition, type ValueType, type WithPlugins, type WithTransactionOptions, index_d_exports as actions, adminBypass, aggregateHelpersPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, batchTransaction, blockIf, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, cachePlugin, cascadePlugin, compileFilterToMongo, configureLogger, createError, createFieldPreset, createMemoryCache, createOptionsExtractor, createRepository, createTenantContext, customIdPlugin, dateSequentialId, elasticSearchPlugin, fieldFilterPlugin, filterResponseData, getFieldsForUser, getMongooseProjection, getNextSequence, immutableField, isDuplicateKeyError, isTransactionUnsupported, leasePlugin, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, operationsByPolicyKey, parseDuplicateKeyError, prefixedId, repoOptionsFromCtx, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, systemContext, timestampPlugin, uniqueField, validationChainPlugin, withTransaction };

package/dist/index.mjs

@@ -1,10 +1,10 @@
-import { b as LookupBuilder, x as compileFilterToMongo } from "./update-C-3viiw1.mjs";
+import { b as LookupBuilder, x as compileFilterToMongo } from "./update-BXMnCvO6.mjs";
 import { n as warn, t as configureLogger } from "./logger-DprijP5h.mjs";
 import { n as isDuplicateKeyError, r as parseDuplicateKeyError, t as createError } from "./error-B00pI7dV.mjs";
 import { t as actions_exports } from "./actions/index.mjs";
-import { a as withTransaction, c as MUTATING_OPERATIONS, d as operationsByPolicyKey, i as isTransactionUnsupported, l as OP_REGISTRY, n as Repository, o as AggregationBuilder, r as batchTransaction, s as ALL_OPERATIONS, t as HOOK_PRIORITY, u as READ_OPERATIONS } from "./Repository-CNBTCVat.mjs";
+import { a as withTransaction, c as MUTATING_OPERATIONS, d as operationsByPolicyKey, i as isTransactionUnsupported, l as OP_REGISTRY, n as Repository, o as AggregationBuilder, r as batchTransaction, s as ALL_OPERATIONS, t as HOOK_PRIORITY, u as READ_OPERATIONS } from "./Repository-BZrU_nXs.mjs";
 import { t as PaginationEngine } from "./PaginationEngine-CfQRM1yz.mjs";
-import { A as aggregateHelpersPlugin, C as sequentialId, D as AuditTrailQuery, E as batchOperationsPlugin, O as auditTrailPlugin, S as prefixedId, T as cachePlugin, _ as fieldFilterPlugin, a as uniqueField, b as dateSequentialId, c as createTenantContext, d as observabilityPlugin, f as adminBypass, g as leasePlugin, h as methodRegistryPlugin, i as requireField, k as auditLogPlugin, l as subdocumentPlugin, m as mongoOperationsPlugin, n as blockIf, o as validationChainPlugin, p as multiTenantPlugin, r as immutableField, s as timestampPlugin, t as autoInject, u as softDeletePlugin, v as elasticSearchPlugin, w as cascadePlugin, x as getNextSequence, y as customIdPlugin } from "./validation-chain.plugin-Bbbnq8ay.mjs";
+import { A as aggregateHelpersPlugin, C as sequentialId, D as AuditTrailQuery, E as batchOperationsPlugin, O as auditTrailPlugin, S as prefixedId, T as cachePlugin, _ as fieldFilterPlugin, a as uniqueField, b as dateSequentialId, c as createTenantContext, d as observabilityPlugin, f as adminBypass, g as leasePlugin, h as methodRegistryPlugin, i as requireField, k as auditLogPlugin, l as subdocumentPlugin, m as mongoOperationsPlugin, n as blockIf, o as validationChainPlugin, p as multiTenantPlugin, r as immutableField, s as timestampPlugin, t as autoInject, u as softDeletePlugin, v as elasticSearchPlugin, w as cascadePlugin, x as getNextSequence, y as customIdPlugin } from "./validation-chain.plugin-BJwwV9jQ.mjs";
 import { i as getMongooseProjection, n as filterResponseData, r as getFieldsForUser, t as createFieldPreset } from "./field-selection-Br3WPOEb.mjs";
 import { isGeoOperator, parseGeoFilter } from "./query/primitives/geo.mjs";
 import { buildFieldTypeMap, coerceFieldValue, coerceHeuristic } from "./query/primitives/coercion.mjs";
@@ -1207,6 +1207,85 @@ function createOptionsExtractor(fields) {
 		return out;
 	};
 }
+/**
+* Canonical options bag for repo calls made OUTSIDE any request scope —
+* event handlers, cron jobs, queue workers, migration scripts.
+*
+* `multiTenantPlugin` requires `organizationId` in the operation
+* context so reads/writes can't leak across tenants from the request
+* layer. Background work has no inherited request scope; calling a
+* tenant-aware repo from an event subscriber without a bypass throws:
+*
+*   "[mongokit] Multi-tenant: Missing 'organizationId' in context for ..."
+*
+* Worse, if the call site is wrapped in `try/catch` (as event handlers
+* routinely are — they fire-and-forget), the error is swallowed and
+* the side effect silently doesn't happen. We've shipped that bug.
+*
+* `systemContext()` returns the canonical opts bag for that case —
+* currently `{ bypassTenant: true }`. The multi-tenant plugin still
+* emits an `after:tenant-bypass` audit event with `reason: 'option'`
+* so observability sees these calls distinct from request-scoped ones.
+*
+* **Greppable on purpose.** A reviewer scanning the codebase can find
+* every "I'm running outside any tenant scope" callsite by searching
+* `systemContext(` — no chasing magic option spreads.
+*
+* **NOT a substitute for proper access control.** Same caveat as raw
+* `bypassTenant`: this bypasses tenant scoping; it does NOT bypass
+* authentication or RBAC. Use only at trusted boundaries — event
+* handlers wired at startup, cron jobs scheduled in code, scripts
+* running with admin credentials.
+*
+* The `extra` overload composes cleanly with transaction sessions and
+* audit-attribution fields; the function's `bypassTenant: true` is
+* applied last so it cannot be accidentally overridden.
+*
+* @example Event handler
+* ```ts
+* import { systemContext } from '@classytic/mongokit';
+*
+* order.events.subscribe('order:completed', async (event) => {
+*   const matches = await enrollmentRepo.aggregatePipeline(
+*     [{ $match: { orderId: event.payload.orderId, status: 'active' } }],
+*     systemContext(),
+*   );
+*   for (const m of matches) {
+*     await enrollmentRepo.update(m._id, { status: 'fulfilled' }, systemContext());
+*   }
+* });
+* ```
+*
+* @example Composed with a transaction
+* ```ts
+* await withTransaction(conn, async (session) => {
+*   await enrollmentRepo.update(id, data, systemContext({ session }));
+*   await auditRepo.create(entry, systemContext({ session }));
+* });
+* ```
+*
+* @example Cron / scheduled cleanup
+* ```ts
+* for await (const doc of repo.cursor(
+*   { expiresAt: { $lt: new Date() } },
+*   systemContext(),
+* )) {
+*   await repo.delete(doc._id, systemContext());
+* }
+* ```
+*
+* @param extra - Optional extra options to merge in (e.g. `session`
+*   for transactions, `userId` for audit attribution). Any
+*   `bypassTenant` value here is overridden — the function name is
+*   load-bearing.
+* @returns A `SessionOptions` object with `bypassTenant: true` set.
+*/
+function systemContext(extra) {
+	return {
+		...extra,
+		bypassTenant: true
+	};
+}
 //#endregion
 //#region src/index.ts
 /**
@@ -1224,4 +1303,4 @@ function createRepository(Model, plugins = [], paginationConfig = {}, options =
 }
 var src_default = Repository;
 //#endregion
-export { ALL_OPERATIONS, AggregationBuilder, AuditTrailQuery, HOOK_PRIORITY, LookupBuilder, MUTATING_OPERATIONS, OP_REGISTRY, PaginationEngine, QueryParser, READ_OPERATIONS, Repository, actions_exports as actions, adminBypass, aggregateHelpersPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, batchTransaction, blockIf, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, cachePlugin, cascadePlugin, compileFilterToMongo, configureLogger, createError, createFieldPreset, createMemoryCache, createOptionsExtractor, createRepository, createTenantContext, customIdPlugin, dateSequentialId, src_default as default, elasticSearchPlugin, fieldFilterPlugin, filterResponseData, getFieldsForUser, getMongooseProjection, getNextSequence, immutableField, isDuplicateKeyError, isTransactionUnsupported, leasePlugin, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, operationsByPolicyKey, parseDuplicateKeyError, prefixedId, repoOptionsFromCtx, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validationChainPlugin, withTransaction };
+export { ALL_OPERATIONS, AggregationBuilder, AuditTrailQuery, HOOK_PRIORITY, LookupBuilder, MUTATING_OPERATIONS, OP_REGISTRY, PaginationEngine, QueryParser, READ_OPERATIONS, Repository, actions_exports as actions, adminBypass, aggregateHelpersPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, batchTransaction, blockIf, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, cachePlugin, cascadePlugin, compileFilterToMongo, configureLogger, createError, createFieldPreset, createMemoryCache, createOptionsExtractor, createRepository, createTenantContext, customIdPlugin, dateSequentialId, src_default as default, elasticSearchPlugin, fieldFilterPlugin, filterResponseData, getFieldsForUser, getMongooseProjection, getNextSequence, immutableField, isDuplicateKeyError, isTransactionUnsupported, leasePlugin, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, operationsByPolicyKey, parseDuplicateKeyError, prefixedId, repoOptionsFromCtx, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, systemContext, timestampPlugin, uniqueField, validationChainPlugin, withTransaction };

package/dist/plugins/index.mjs

@@ -1,2 +1,2 @@
-import { A as aggregateHelpersPlugin, C as sequentialId, D as AuditTrailQuery, E as batchOperationsPlugin, O as auditTrailPlugin, S as prefixedId, T as cachePlugin, _ as fieldFilterPlugin, a as uniqueField, b as dateSequentialId, c as createTenantContext, d as observabilityPlugin, g as leasePlugin, h as methodRegistryPlugin, i as requireField, k as auditLogPlugin, l as subdocumentPlugin, m as mongoOperationsPlugin, n as blockIf, o as validationChainPlugin, p as multiTenantPlugin, r as immutableField, s as timestampPlugin, t as autoInject, u as softDeletePlugin, v as elasticSearchPlugin, w as cascadePlugin, x as getNextSequence, y as customIdPlugin } from "../validation-chain.plugin-Bbbnq8ay.mjs";
+import { A as aggregateHelpersPlugin, C as sequentialId, D as AuditTrailQuery, E as batchOperationsPlugin, O as auditTrailPlugin, S as prefixedId, T as cachePlugin, _ as fieldFilterPlugin, a as uniqueField, b as dateSequentialId, c as createTenantContext, d as observabilityPlugin, g as leasePlugin, h as methodRegistryPlugin, i as requireField, k as auditLogPlugin, l as subdocumentPlugin, m as mongoOperationsPlugin, n as blockIf, o as validationChainPlugin, p as multiTenantPlugin, r as immutableField, s as timestampPlugin, t as autoInject, u as softDeletePlugin, v as elasticSearchPlugin, w as cascadePlugin, x as getNextSequence, y as customIdPlugin } from "../validation-chain.plugin-BJwwV9jQ.mjs";
 export { AuditTrailQuery, aggregateHelpersPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, blockIf, cachePlugin, cascadePlugin, createTenantContext, customIdPlugin, dateSequentialId, elasticSearchPlugin, fieldFilterPlugin, getNextSequence, immutableField, leasePlugin, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, prefixedId, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validationChainPlugin };

package/dist/{update-C-3viiw1.mjs → update-BXMnCvO6.mjs}

@@ -864,6 +864,7 @@ async function getByQuery(Model, query, options = {}) {
 	const mongoQuery = Model.findOne(query);
 	if (options.select) mongoQuery.select(options.select);
 	if (options.populate) mongoQuery.populate(parsePopulate$1(options.populate));
+	if (options.sort) mongoQuery.sort(options.sort);
 	if (options.lean) mongoQuery.lean();
 	if (options.session) mongoQuery.session(options.session);
 	if (options.readPreference) mongoQuery.read(options.readPreference);

package/dist/{validation-chain.plugin-Bbbnq8ay.mjs → validation-chain.plugin-BJwwV9jQ.mjs}

@@ -1,7 +1,7 @@
-import { _ as upsert } from "./update-C-3viiw1.mjs";
+import { _ as upsert } from "./update-BXMnCvO6.mjs";
 import { n as warn } from "./logger-DprijP5h.mjs";
 import { t as createError } from "./error-B00pI7dV.mjs";
-import { l as OP_REGISTRY, s as ALL_OPERATIONS, t as HOOK_PRIORITY } from "./Repository-CNBTCVat.mjs";
+import { l as OP_REGISTRY, s as ALL_OPERATIONS, t as HOOK_PRIORITY } from "./Repository-BZrU_nXs.mjs";
 import { r as getFieldsForUser } from "./field-selection-Br3WPOEb.mjs";
 import mongoose from "mongoose";
 import { cachePlugin } from "@classytic/repo-core/cache";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/mongokit",
-  "version": "3.13.3",
+  "version": "3.13.4",
   "description": "Production-grade MongoDB repositories - smart pagination, events, and plugins. Built on @classytic/repo-core.",
   "type": "module",
   "sideEffects": false,