@classytic/mongokit 3.39.0 → 3.40.0

package/dist/{Repository-IxI983_m.d.mts → Repository-CR8Y9g2E.d.mts}

@@ -1,6 +1,6 @@
 import { _ as UpdateOptions, a as CreateOptions, b as LookupOptions, c as FindOneAndUpdateOptions, d as LookupPopulateResult, g as UpdateManyResult, h as SessionOptions, m as ReadOptions, o as DeleteManyResult, 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, g as ObjectId, i as CountStrategy, r as CollationOptions, t as AggregatePaginationOptions, u as PaginationConfig, v as ReadPreferenceType, x as SortSpec$1, y as SelectSpec } from "./pagination-BpIv2bdS.mjs";
-import { _ as RepositoryOptions, d as PluginType, f as PrioritizedHook, o as Middleware, p as RepositoryContext } from "./repository-ZbLtL7Nk.mjs";
+import { _ as RepositoryOptions, d as PluginType, f as PrioritizedHook, o as Middleware, p as RepositoryContext } from "./repository-odl03582.mjs";
 import { t as PaginationEngine } from "./PaginationEngine-D-P19Y9m.mjs";
 import { AggPaginationRequest, AggRequest, AggResult, ArchiveOptions, ArchiveResult, ArchiveSink, ChangeEvent, FilterInput, KeysetAggPaginationResult, QueryOptions, RepoCapabilities, RepositoryBase, TenantPurgeOptions, TenantPurgeResult, TenantPurgeStrategy, WatchOptions } from "@classytic/repo-core/repository";
 import { ClientSession, Expression, Model, PipelineStage, PopulateOptions } from "mongoose";
@@ -519,6 +519,37 @@ interface TransitionMachine {
   readonly name: string;
   assertTransition(entityId: string, from: string, to: string): void;
 }
+/** `Repository.getAll` parameters. */
+type GetAllParams = {
+  filters?: Record<string, unknown>;
+  sort?: SortSpec$1 | string;
+  cursor?: string;
+  after?: string;
+  /** Cursor for the PREVIOUS page. Mutually exclusive with `after`/`cursor`. */
+  before?: string;
+  page?: number;
+  pagination?: {
+    page?: number;
+    limit?: number;
+  };
+  limit?: number;
+  search?: string;
+  mode?: 'offset' | 'keyset';
+  hint?: string | Record<string, 1 | -1>;
+  maxTimeMS?: number;
+  countStrategy?: CountStrategy;
+  /** Ceiling for `countStrategy: 'capped'`. */
+  countLimit?: number;
+  readPreference?: ReadPreferenceType;
+  /** Advanced populate options (from QueryParser or Arc's BaseController) */
+  populateOptions?: PopulateOptions[];
+  /** Collation for locale-aware string comparison */
+  collation?: CollationOptions;
+  /** Lookup configurations for $lookup joins (from QueryParser or manual) */
+  lookups?: LookupOptions[];
+  /** Skip pagination entirely — returns raw TDoc[] (same as findAll) */
+  noPagination?: boolean;
+};
 declare class Repository<TDoc = unknown> extends RepositoryBase {
   /**
    * Cache handle ATTACHED BY the unified cache plugin at wiring time —
@@ -916,36 +947,19 @@ declare class Repository<TDoc = unknown> extends RepositoryBase {
    * // Skip cache for fresh data
    * await repo.getAll({ filters: { status: 'active' } }, { skipCache: true });
    */
-  getAll(params?: {
-    filters?: Record<string, unknown>;
-    sort?: SortSpec$1 | string;
-    cursor?: string;
-    after?: string;
-    /** Cursor for the PREVIOUS page. Mutually exclusive with `after`/`cursor`. */
-    before?: string;
-    page?: number;
-    pagination?: {
-      page?: number;
-      limit?: number;
-    };
-    limit?: number;
-    search?: string;
-    mode?: 'offset' | 'keyset';
-    hint?: string | Record<string, 1 | -1>;
-    maxTimeMS?: number;
-    countStrategy?: CountStrategy;
-    /** Ceiling for `countStrategy: 'capped'`. */
-    countLimit?: number;
-    readPreference?: ReadPreferenceType;
-    /** Advanced populate options (from QueryParser or Arc's BaseController) */
-    populateOptions?: PopulateOptions[];
-    /** Collation for locale-aware string comparison */
-    collation?: CollationOptions;
-    /** Lookup configurations for $lookup joins (from QueryParser or manual) */
-    lookups?: LookupOptions[];
-    /** Skip pagination entirely — returns raw TDoc[] (same as findAll) */
-    noPagination?: boolean;
-  }, options?: CacheableOptions): Promise<OffsetPaginationResult<TDoc> | KeysetPaginationResult<TDoc> | TDoc[]>;
+  /** An explicit `mode` (or `noPagination`) decides the envelope, so the result type follows it. */
+  getAll(params: GetAllParams & {
+    mode: 'offset';
+    noPagination?: false;
+  }, options?: CacheableOptions): Promise<OffsetPaginationResult<TDoc>>;
+  getAll(params: GetAllParams & {
+    mode: 'keyset';
+    noPagination?: false;
+  }, options?: CacheableOptions): Promise<KeysetPaginationResult<TDoc>>;
+  getAll(params: GetAllParams & {
+    noPagination: true;
+  }, options?: CacheableOptions): Promise<TDoc[]>;
+  getAll(params?: GetAllParams, options?: CacheableOptions): Promise<OffsetPaginationResult<TDoc> | KeysetPaginationResult<TDoc> | TDoc[]>;
   /**
    * Atomic "look up by filter, insert `data` if missing, return the doc."
    *
@@ -1268,6 +1282,11 @@ declare class Repository<TDoc = unknown> extends RepositoryBase {
   }, patch?: Record<string, unknown>, options?: SessionOptions & {
     idField?: string;
     upsert?: boolean;
+    /**
+     * The document as the caller just read it in this session. Hooks' `loadTarget()`
+     * returns it instead of reading again. Pass only a read taken in the same session.
+     */
+    target?: Record<string, unknown>;
   }): Promise<TDoc | null>;
   /**
    * State-machine-backed CAS transition with status history — the
@@ -1801,6 +1820,12 @@ declare class Repository<TDoc = unknown> extends RepositoryBase {
    * 4. DEFAULT (500) — user-registered hooks
    */
   _buildContext(operation: string, options: Record<string, unknown> | object): Promise<RepositoryContext>;
+  /**
+   * `memo` and (for an id-addressed op) `loadTarget` — attached before the before-hooks
+   * run so every hook of one operation shares one read. A caller that has just read the
+   * document in the same session passes it as `target`, and nothing is read at all.
+   */
+  private _sharedReadSeams;
   /**
    * Feed the resolved filter of a guarded verb to the distribution guard.
    * The slot follows `OP_REGISTRY[op].policyKey` (`query` vs `filters`);
@@ -1916,4 +1941,4 @@ declare class Repository<TDoc = unknown> extends RepositoryBase {
   private _translateError;
 }
 //#endregion
-export { AggregationPlan as a, SortOrder as c, AggregationBuilder as i, SortSpec as l, Repository as n, GroupSpec as o, TransitionMachine as r, ProjectionSpec as s, HOOK_PRIORITY as t, VectorSearchOptions as u };
+export { AggregationBuilder as a, ProjectionSpec as c, VectorSearchOptions as d, TransitionMachine as i, SortOrder as l, HOOK_PRIORITY as n, AggregationPlan as o, Repository as r, GroupSpec as s, GetAllParams as t, SortSpec as u };

package/dist/actions/index.mjs

@@ -1,5 +1,5 @@
 import { t as __exportAll } from "../rolldown-runtime-D7D4PA-g.mjs";
-import { b as create_exports, i as update_exports, m as aggregate_exports, p as delete_exports, u as read_exports } from "../update-c_01A0if.mjs";
+import { S as create_exports, i as update_exports, m as aggregate_exports, p as delete_exports, u as read_exports } from "../update-DG0fCwRJ.mjs";
 //#region src/actions/index.ts
 var actions_exports = /* @__PURE__ */ __exportAll({
 	aggregate: () => aggregate_exports,

package/dist/ai/index.d.mts

@@ -1,4 +1,4 @@
-import { l as Plugin } from "../repository-ZbLtL7Nk.mjs";
+import { l as Plugin } from "../repository-odl03582.mjs";
 import { PipelineStage } from "mongoose";
 //#region src/ai/types.d.ts
 /** Supported similarity metrics for vector search */

package/dist/better-auth/index.mjs

@@ -1,4 +1,4 @@
-import { n as Repository } from "../Repository-D7fDpyFx.mjs";
+import { n as Repository } from "../Repository-BMgPSkqZ.mjs";
 import { n as createMongooseAdapter } from "../adapter-BrVfPFSW.mjs";
 import { asReadOnlyRepo } from "@classytic/repo-core/repository";
 import { pluralizeBetterAuthCollection, resolveBetterAuthCollections } from "@classytic/repo-core/better-auth";

package/dist/{create-repository-DOe9E_5F.mjs → create-repository-BzBUMvd1.mjs}

@@ -1,5 +1,5 @@
-import { n as Repository } from "./Repository-D7fDpyFx.mjs";
-import { a as customIdPlugin, f as auditTrailPlugin, i as multiTenantPlugin, m as auditLogPlugin, n as softDeletePlugin, t as timestampPlugin, u as cachePlugin } from "./timestamp.plugin-B5eiaItQ.mjs";
+import { n as Repository } from "./Repository-BMgPSkqZ.mjs";
+import { b as auditLogPlugin, g as cachePlugin, i as multiTenantPlugin, l as customIdPlugin, n as softDeletePlugin, t as timestampPlugin, v as auditTrailPlugin } from "./timestamp.plugin-DF0gJB6p.mjs";
 import { n as batchOperationsPlugin, t as methodRegistryPlugin } from "./method-registry.plugin-C63pGn1d.mjs";
 //#region src/create-repository.ts
 function isLoggerAudit(value) {

package/dist/{create-repository-CRXjDa3N.d.mts → create-repository-CAle1MSU.d.mts}

@@ -1,8 +1,8 @@
 import { u as PaginationConfig } from "./pagination-BpIv2bdS.mjs";
-import { _ as RepositoryOptions, d as PluginType } from "./repository-ZbLtL7Nk.mjs";
-import { T as AuditTrailOptions, _ as RepositoryCachePluginOptions, i as CustomIdOptions, t as MultiTenantOptions } from "./multi-tenant.plugin-B-tzNeYL.mjs";
-import { n as Repository } from "./Repository-IxI983_m.mjs";
-import { i as Logger, o as SoftDeleteOptions } from "./plugin-options-BuvtOSZf.mjs";
+import { _ as RepositoryOptions, d as PluginType } from "./repository-odl03582.mjs";
+import { D as AuditTrailOptions, i as CustomIdOptions, t as MultiTenantOptions, y as RepositoryCachePluginOptions } from "./multi-tenant.plugin-CBgCo9im.mjs";
+import { r as Repository } from "./Repository-CR8Y9g2E.mjs";
+import { i as Logger, o as SoftDeleteOptions } from "./plugin-options-Zk46lD6F.mjs";
 import { Model } from "mongoose";
 //#region src/create-repository.d.ts
 /**

package/dist/idempotency/index.d.mts

@@ -0,0 +1,23 @@
+import { Connection, Model } from "mongoose";
+import { IdempotencyClaimStore } from "@classytic/repo-core/idempotency";
+//#region src/idempotency/index.d.ts
+interface IdempotencyModelOptions {
+  /** Collection name. Default `idempotency_claims`. */
+  collection?: string;
+  /** Mongoose model name. Default `IdempotencyClaim`. Must be unique per connection. */
+  modelName?: string;
+}
+interface IdempotencyStoreOptions {
+  /**
+   * How long a claim is kept after its last write before the TTL monitor removes it.
+   * Default 7 days. Size it to the longest a caller may retry — a retry after the claim
+   * is gone executes again. An offline till that syncs days later needs more.
+   */
+  retentionSeconds?: number;
+}
+/** Build (or return) the claims model on `connection`. Idempotent per connection. */
+declare function createIdempotencyModel(connection: Connection, options?: IdempotencyModelOptions): Model<Record<string, unknown>>;
+/** The store over a model from {@link createIdempotencyModel}. */
+declare function createIdempotencyStore(model: Model<Record<string, unknown>>, options?: IdempotencyStoreOptions): IdempotencyClaimStore;
+//#endregion
+export { IdempotencyModelOptions, IdempotencyStoreOptions, createIdempotencyModel, createIdempotencyStore };

package/dist/idempotency/index.mjs

@@ -0,0 +1,134 @@
+import { Schema } from "mongoose";
+import { identityKey } from "@classytic/repo-core/idempotency";
+//#region src/idempotency/index.ts
+/**
+* The mongo {@link IdempotencyClaimStore} — use this with `runIdempotent` from
+* `@classytic/repo-core/idempotency`; never keep a per-module claims table.
+*
+* ```ts
+* const store = createIdempotencyStore(createIdempotencyModel(connection));
+* const run = await runIdempotent({ store, identity, requestFingerprint, execute });
+* ```
+*
+* One document per identity, `_id` = `identityKey(identity)`, so "insert iff absent" is
+* the `_id` index and every compare-and-set is a single-document filter. Proven by
+* `runIdempotencyStoreConformance` (`@classytic/repo-core/testing`) in this package's tests.
+*/
+const DEFAULT_RETENTION_SECONDS = 604800;
+/** Build (or return) the claims model on `connection`. Idempotent per connection. */
+function createIdempotencyModel(connection, options = {}) {
+	const { collection = "idempotency_claims", modelName = "IdempotencyClaim" } = options;
+	const existing = connection.models[modelName];
+	if (existing) return existing;
+	const schema = new Schema({
+		_id: {
+			type: String,
+			required: true
+		},
+		identity: {
+			type: Schema.Types.Mixed,
+			required: true
+		},
+		requestFingerprint: {
+			type: String,
+			required: true
+		},
+		state: {
+			type: String,
+			enum: [
+				"in_flight",
+				"succeeded",
+				"failed"
+			],
+			required: true
+		},
+		leaseToken: {
+			type: String,
+			required: true
+		},
+		leaseExpiresAt: {
+			type: Date,
+			required: true
+		},
+		createdAt: {
+			type: Date,
+			required: true
+		},
+		completedAt: { type: Date },
+		result: { type: Schema.Types.Mixed },
+		attempts: {
+			type: Number,
+			required: true
+		},
+		progress: { type: Schema.Types.Mixed },
+		context: { type: Schema.Types.Mixed },
+		lastError: { type: String },
+		purgeAt: {
+			type: Date,
+			required: true
+		}
+	}, {
+		collection,
+		versionKey: false,
+		minimize: false
+	});
+	schema.index({ purgeAt: 1 }, {
+		expireAfterSeconds: 0,
+		name: "retention"
+	});
+	schema.index({
+		"identity.operation": 1,
+		state: 1,
+		leaseExpiresAt: 1
+	}, { name: "lapsed_sweep" });
+	return connection.model(modelName, schema);
+}
+/** The store over a model from {@link createIdempotencyModel}. */
+function createIdempotencyStore(model, options = {}) {
+	const retentionMs = (options.retentionSeconds ?? DEFAULT_RETENTION_SECONDS) * 1e3;
+	const claims = () => model.collection;
+	const toDoc = (claim) => ({
+		...claim,
+		_id: identityKey(claim.identity),
+		purgeAt: new Date(Date.now() + retentionMs)
+	});
+	/** The caller's transaction, so a claim commits or rolls back with the writes it describes. */
+	const withSession = (options) => options?.session ? { session: options.session } : {};
+	const ownedInFlight = (identity, leaseToken) => ({
+		_id: identityKey(identity),
+		state: "in_flight",
+		leaseToken
+	});
+	return {
+		async get(identity, options) {
+			const doc = await claims().findOne({ _id: identityKey(identity) }, withSession(options));
+			if (!doc) return null;
+			const { _id, purgeAt, ...claim } = doc;
+			return claim;
+		},
+		async insert(claim, options) {
+			try {
+				await claims().insertOne(toDoc(claim), withSession(options));
+				return true;
+			} catch (error) {
+				if (error.code === 11e3) return false;
+				throw error;
+			}
+		},
+		async swap(identity, expectedLeaseToken, next, options) {
+			return (await claims().replaceOne(ownedInFlight(identity, expectedLeaseToken), toDoc(next), withSession(options))).matchedCount === 1;
+		},
+		async release(identity, expectedLeaseToken, options) {
+			return (await claims().deleteOne(ownedInFlight(identity, expectedLeaseToken), withSession(options))).deletedCount === 1;
+		},
+		async listLapsed(operation, now, limit) {
+			return (await claims().find({
+				"identity.operation": operation,
+				state: "in_flight",
+				leaseExpiresAt: { $lte: now }
+			}).sort({ leaseExpiresAt: 1 }).limit(limit).toArray()).map(({ _id, purgeAt, ...claim }) => claim);
+		}
+	};
+}
+//#endregion
+export { createIdempotencyModel, createIdempotencyStore };

package/dist/index.d.mts

@@ -2,18 +2,19 @@ import { _ as UpdateOptions, a as CreateOptions, b as LookupOptions, c as FindOn
 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-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 { 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-odl03582.mjs";
+import { A as EnsureAuditTrailReadyOptions, C as AuditQueryOptions, D as AuditTrailOptions, E as AuditTrailMode, M as ensureAuditTrailReady, O as AuditTrailQuery, S as AuditOperation, T as AuditTrailMethods, _ as CacheOptions, a as DateSequentialIdOptions, b as cachePlugin, c as SequentialIdOptions, d as ensureSequenceAtLeast, f as getNextSequence, g as CacheAdapter, h as sequentialId, i as CustomIdOptions, j as auditTrailPlugin, k as AuditTrailQueryOptions, l as customIdPlugin, m as readSequence, n as adminBypass, o as IdGenerator, p as prefixedId, r as multiTenantPlugin, s as PrefixedIdOptions, t as MultiTenantOptions, u as dateSequentialId, v as RepositoryCacheHandle, w as AuditQueryResult, x as AuditEntry, y as RepositoryCachePluginOptions } from "./multi-tenant.plugin-CBgCo9im.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 { a as AggregationBuilder, c as ProjectionSpec, d as VectorSearchOptions, i as TransitionMachine, l as SortOrder, n as HOOK_PRIORITY, o as AggregationPlan, r as Repository, s as GroupSpec, t as GetAllParams, u as SortSpec } from "./Repository-CR8Y9g2E.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-Zk46lD6F.mjs";
+import { n as CreateRepositoryConfig, r as createRepository, t as AuditConfig } from "./create-repository-CAle1MSU.mjs";
+import { A as IdempotencyStoreMethods, B as batchOperationsPlugin, C as LeaseMethods, D as ImmutableStatesPluginOptions, E as ImmutableClaimView, F as elasticSearchPlugin, G as aggregateHelpersPlugin, H as AppendOnlyPluginOptions, I as cascadePlugin, L as BatchOperationsMethods, M as idempotencyStorePlugin, N as fieldFilterPlugin, O as immutableStatesPlugin, P as ElasticSearchOptions, R as BulkWriteOptions, S as methodRegistryPlugin, T as leasePlugin, U as appendOnlyPlugin, V as auditLogPlugin, W as AggregateHelpersMethods, _ 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 BulkWriteResult } from "./validation-chain.plugin-DYp9E7K2.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-B8ufk3Qz.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-k7SjNlSS.mjs";
 import { RepoCapabilities } from "@classytic/repo-core/repository";
 import { ClientSession, Connection, Model, PipelineStage, Schema } from "mongoose";
+import "@classytic/repo-core/query-parser";
 //#region src/actions/cascade-references.d.ts
 type PurgeMode = 'hard' | 'soft' | 'anonymize';
 /** Raw collection surface — a native MongoDB `Collection` or a Mongoose `Model`. */
@@ -837,6 +838,35 @@ declare function isTransactionUnsupported(error: Error): boolean;
  */
 declare function supportsTransactions(connection: unknown): boolean;
 //#endregion
+//#region src/utils/scope.d.ts
+/** The fields that decide whose rows an operation touches, and inside which transaction. */
+interface RepoScope {
+  /** Platform-admin escape hatch. Present only when the source carried no tenant. */
+  bypassTenant?: true;
+  session?: ClientSession;
+  user?: unknown;
+  userId?: unknown;
+  requestId?: unknown;
+  /** Tenant values, keyed by each declared tenant context key (`organizationId`, …). */
+  [tenantKey: string]: unknown;
+}
+/**
+ * Record that `repo` resolves its tenant from `contextKey`. Called by
+ * `multiTenantPlugin` at bind, so forwarding knows a custom key (`branchId`)
+ * without the host restating it.
+ */
+declare function declareTenantContextKey(repo: object, contextKey: string): void;
+/** Every tenant context key relevant to a call spanning these repositories. */
+declare function tenantContextKeysOf(...repos: ReadonlyArray<object | undefined>): string[];
+/**
+ * The scope to hand a second repository call made on behalf of `source`
+ * (a hook's `RepositoryContext`, or a host's request context).
+ *
+ * Absent values are omitted, never written as `undefined`, so spreading the
+ * result into an options bag cannot erase a value set there.
+ */
+declare function forwardScope(source: Record<string, unknown> | null | undefined, tenantKeys?: readonly string[]): RepoScope;
+//#endregion
 //#region src/utils/repo-options.d.ts
 /**
  * Forward request-scoped context fields into a mongokit options bag.
@@ -883,23 +913,20 @@ declare function supportsTransactions(connection: unknown): boolean;
  * });
  * ```
  *
- * The fields read (all optional — extracted only when present and not
- * `undefined`):
- *
- * - `organizationId` — multi-tenant scope key. The
- *   `multiTenantPlugin` casts to `ObjectId` automatically when
- *   configured with `fieldType: 'objectId'`; do NOT pre-cast.
- * - `userId` / `user` — audit attribution (audit-log + audit-trail
- *   plugins read these for the `who` column).
- * - `session` — mongoose `ClientSession` for transaction threading.
- * - `requestId` — observability correlation id.
- *
- * Fields beyond this set should be added inline at the call site —
- * `repoOptionsFromCtx` deliberately stays narrow so adding a new
- * convention to the canonical set is a deliberate API decision, not
- * a quiet drift.
+ * It is `forwardScope` (see `./scope.ts`), the same rule every internal
+ * hop uses, so a request context and a cascade forward identically:
+ *
+ * - the tenant (`organizationId`, `tenantId`) — `multiTenantPlugin` casts
+ *   to `ObjectId` itself when configured with `fieldType: 'objectId'`;
+ *   do NOT pre-cast;
+ * - `bypassTenant`, only when literally `true` AND no tenant is present
+ *   (the tenant plugin honours a bypass before a tenant, so carrying both
+ *   would widen a scoped call to every tenant);
+ * - `session`, and `user` / `userId` / `requestId` for attribution.
+ *
+ * Domain fields beyond this set belong to `createOptionsExtractor`.
  */
-declare function repoOptionsFromCtx<TCtx extends Record<string, unknown>>(ctx: TCtx | undefined | null): Record<string, unknown>;
+declare function repoOptionsFromCtx<TCtx extends Record<string, unknown>>(ctx: TCtx | undefined | null): RepoScope;
 /**
  * Build a typed extractor for **consumer-defined** ctx → options
  * forwarding. Same conceptual shape as `repoOptionsFromCtx`, but the
@@ -920,12 +947,11 @@ declare function repoOptionsFromCtx<TCtx extends Record<string, unknown>>(ctx: T
  * output keys are inferred from the input field tuple — you can
  * destructure with full autocomplete.
  *
- * **Difference from `repoOptionsFromCtx`.** That helper hardcodes the
- * fields **mongokit's bundled plugins** read (`organizationId`,
- * `userId`, `user`, `session`, `requestId`). Use it when those are
- * sufficient. Reach for `createOptionsExtractor` when your domain has
- * its own canonical fields (`actorRef`, `actorKind`, `correlationId`,
- * `idempotencyKey`, `sagaRunId`, ...) that should also forward.
+ * **Scope is always included, and never from `fields`.** The extractor
+ * returns `forwardScope(ctx)` plus the declared DOMAIN fields. Listing a
+ * scope key (`organizationId`, `bypassTenant`, `session`, …) in `fields`
+ * changes nothing: those follow the one scope rule, so an extractor cannot
+ * forget the bypass, or carry a bypass beside a tenant.
  *
  * @example Per-package canonical extractor
  * ```ts
@@ -940,12 +966,12 @@ declare function repoOptionsFromCtx<TCtx extends Record<string, unknown>>(ctx: T
  *   idempotencyKey?: string;
  * };
  *
+ * // Domain fields only: the scope (organizationId, session, bypass) is
+ * // always included by the one scope rule.
  * export const repoOptionsFromCtx = createOptionsExtractor<CommissionCtx>([
- *   'organizationId',
  *   'actorRef',
  *   'actorKind',
  *   'correlationId',
- *   'session',
  *   'idempotencyKey',
  * ]);
  *
@@ -1036,4 +1062,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 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 };
+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 BulkWriteOptions, 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 GetAllParams, 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, type RepoScope, 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, declareTenantContextKey, defineModel, defineModels, elasticSearchPlugin, ensureAuditTrailReady, ensureSequenceAtLeast, fieldFilterPlugin, filterResponseData, forwardScope, getFieldsForUser, getMongooseProjection, getNextSequence, getPaginationDefaults, idVariants, idempotencyStorePlugin, immutableField, immutableStatesPlugin, isCreateManyPartialError, isDuplicateKeyError, isModelRegistered, isTransactionUnsupported, leasePlugin, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, operationsByPolicyKey, parseDuplicateKeyError, prefixedId, probeMongoCapabilities, readSequence, repoOptionsFromCtx, requireField, resetCapabilityProbeCache, resetPaginationDefaults, resolveMongoCapabilities, resolveTransactionSupport, sequentialId, softDeletePlugin, subdocumentPlugin, supportsTransactions, systemContext, tenantContextKeysOf, timestampPlugin, toPlain, transactionResolutionOf, uniqueField, validationChainPlugin, withTransaction };