@classytic/mongokit 3.38.1 → 3.40.0

package/dist/{repository-H_ffGgpE.d.mts → repository-odl03582.d.mts}

@@ -1,6 +1,6 @@
-import { a as PopulateSpec, i as ObjectId, l as SortSpec, o as ReadPreferenceType, r as FilterQuery, s as SelectSpec, t as AnyDocument } from "./core-62oo3N1C.mjs";
+import { _ as PopulateSpec, g as ObjectId, h as FilterQuery, i as CountStrategy, p as AnyDocument, v as ReadPreferenceType, x as SortSpec, y as SelectSpec } from "./pagination-BpIv2bdS.mjs";
 import { r as DocField } from "./type-utils-CLzRFtIA.mjs";
-import { RepoCapabilities, RepositoryBase } from "@classytic/repo-core/repository";
+import { DistributionConfig, DistributionMissHandler, RepoCapabilities, RepositoryBase } from "@classytic/repo-core/repository";
 import { Model, PipelineStage } from "mongoose";
 import { HttpError } from "@classytic/repo-core/errors";
 import { OffsetPaginationResult } from "@classytic/repo-core/pagination";
@@ -199,6 +199,28 @@ interface RepositoryOptions {
    * ```
    */
   requirePlugins?: readonly RepositoryPluginName[];
+  /**
+   * Declare the collection's shard key so every filter-taking verb
+   * (`getAll`, `findAll`, `getOne`, `count`, `updateMany`, `aggregate`, …)
+   * catches a filter that omits it — the query mongos has to fan out to
+   * every shard. Id-addressed verbs (`getById`, `update`, `delete`,
+   * `claim`) are not checked; their `_id` match is routed, not scattered.
+   *
+   * The check runs AFTER `before:*` hooks, so a tenant field injected by
+   * `multiTenantPlugin` satisfies a `key: 'organizationId'` guard and the
+   * guard only ever fires on the calls that dropped the scope —
+   * `bypassTenant: true`, an unscoped repo, a hand-built cross-tenant
+   * `$or`. List verbs a host legitimately runs cross-shard (a global
+   * dashboard's `aggregate`) in `exemptOperations`.
+   *
+   * `onMissingKey` defaults to `'warn'` — once per operation name through
+   * mongokit's logger (`configureLogger` routes it); pass `onMiss` to
+   * observe every miss yourself, or `'throw'` for hosts where a scatter-
+   * gather is never acceptable. Omit the option entirely and nothing runs.
+   */
+  distribution?: DistributionConfig & {
+    onMiss?: DistributionMissHandler;
+  };
   /**
    * Override the whole runtime capability descriptor.
    *
@@ -295,6 +317,8 @@ interface RepositoryContext {
   limit?: number;
   /** Cursor for next page (keyset pagination) */
   after?: string;
+  /** Cursor for the PREVIOUS page (keyset pagination). Mutually exclusive with `after`. */
+  before?: string;
   /** Search query string */
   search?: string;
   /** Pagination mode */
@@ -303,8 +327,10 @@ interface RepositoryContext {
   hint?: string | Record<string, 1 | -1>;
   /** Maximum execution time in milliseconds */
   maxTimeMS?: number;
-  /** Count strategy for offset pagination */
-  countStrategy?: 'exact' | 'estimated' | 'none';
+  /** Count strategy for offset pagination. See {@link CountStrategy}. */
+  countStrategy?: CountStrategy;
+  /** Ceiling for `countStrategy: 'capped'` (default 10000). */
+  countLimit?: number;
   /** Whether this is a soft delete operation (set by softDeletePlugin) */
   softDeleted?: boolean;
   /** Include soft-deleted documents in queries */
@@ -337,8 +363,23 @@ interface RepositoryContext {
   _cacheResolved?: unknown;
   /** Cache hit status (internal — `'fresh'` or `'stale'`) */
   _cacheStatus?: 'fresh' | 'stale' | 'miss' | 'disabled' | 'bypass';
-  /** IDs to cascade delete (internal) */
-  _cascadeIds?: unknown[];
+  /**
+   * Parent key values captured before a delete, by `parentKey` (internal —
+   * cascade plugin). Restrict, detach and cascade all read these.
+   */
+  _cascadeParentKeys?: Map<string, unknown[]>;
+  /**
+   * Memo shared by every hook of THIS operation: N plugins that need the same read pay for
+   * one. Scoped to the operation, so it can never serve a value across writes. A rejected
+   * load is forgotten, so the next caller retries.
+   */
+  memo?: <T>(key: string, load: () => Promise<T>) => Promise<T>;
+  /**
+   * The persisted document an id-addressed operation targets, as it is BEFORE the write,
+   * read once under the operation's session (not tenant-filtered — the write's own filter
+   * decides whether it applies). Use this instead of `Model.findById(context.id)` in a hook.
+   */
+  loadTarget?: () => Promise<Record<string, unknown> | null>;
   /** Custom context data from plugins */
   [key: string]: unknown;
 }
@@ -502,6 +543,9 @@ type AllPluginMethods<TDoc> = {
   deleteSubdocument(parentId: string | ObjectId, arrayPath: DocField<TDoc>, subId: string | ObjectId, options?: Record<string, unknown>): Promise<TDoc>;
   restore(id: string | ObjectId, options?: {
     session?: unknown;
+    organizationId?: unknown;
+    bypassTenant?: boolean;
+    [key: string]: unknown;
   }): Promise<TDoc>;
   getDeleted(params?: {
     filters?: Record<string, unknown>;

package/dist/sync/index.d.mts

@@ -0,0 +1,40 @@
+import { ClientSession, Connection, Model } from "mongoose";
+import { ChangeLogStore, CommandStreamStore, CommandStreamTx } from "@classytic/repo-core/sync";
+//#region src/sync/index.d.ts
+interface ChangeLogModelOptions {
+  /** Entries collection. Default `sync_changes`; its counter lives in `<collection>_counter`. */
+  collection?: string;
+  /** Mongoose model name prefix. Default `SyncChange`. Must be unique per connection. */
+  modelName?: string;
+}
+interface ChangeLogModels {
+  entries: Model<Record<string, unknown>>;
+  counter: Model<Record<string, unknown>>;
+  /** The counter document's id (one feed per entries collection). */
+  feed: string;
+}
+declare function createChangeLogModels(connection: Connection, options?: ChangeLogModelOptions): ChangeLogModels;
+declare function createChangeLogStore(models: ChangeLogModels): ChangeLogStore;
+interface CommandStreamModelOptions {
+  /** Collection prefix: `<prefix>_streams`, `<prefix>_verdicts`, `<prefix>_aliases`. Default `sync`. */
+  prefix?: string;
+  /** Mongoose model name prefix. Default `SyncStream`. Must be unique per connection. */
+  modelName?: string;
+}
+interface CommandStreamModels {
+  streams: Model<Record<string, unknown>>;
+  verdicts: Model<Record<string, unknown>>;
+  aliases: Model<Record<string, unknown>>;
+}
+declare function createCommandStreamModels(connection: Connection, options?: CommandStreamModelOptions): CommandStreamModels;
+interface MongoCommandStreamTx extends CommandStreamTx {
+  readonly session: ClientSession;
+}
+/**
+ * The mongo {@link CommandStreamStore} (replica set). Proven by `runCommandStreamStoreConformance`.
+ * Concurrent transactions on one stream write-conflict on its document and `withTransaction`
+ * retries the loser, which then reads the winner's watermark.
+ */
+declare function createCommandStreamStore(connection: Pick<Connection, 'startSession'>, models: CommandStreamModels, changes: ChangeLogStore): CommandStreamStore<MongoCommandStreamTx>;
+//#endregion
+export { ChangeLogModelOptions, ChangeLogModels, CommandStreamModelOptions, CommandStreamModels, MongoCommandStreamTx, createChangeLogModels, createChangeLogStore, createCommandStreamModels, createCommandStreamStore };

package/dist/sync/index.mjs

@@ -0,0 +1,334 @@
+import { i as withTransaction } from "../transaction-B5L9glO0.mjs";
+import { Schema } from "mongoose";
+//#region src/sync/index.ts
+function createChangeLogModels(connection, options = {}) {
+	const { collection = "sync_changes", modelName = "SyncChange" } = options;
+	const entriesName = modelName;
+	const counterName = `${modelName}Counter`;
+	return {
+		entries: connection.models[entriesName] ?? connection.model(entriesName, (() => {
+			const schema = new Schema({
+				seq: {
+					type: Number,
+					required: true
+				},
+				scope: {
+					type: String,
+					required: true
+				},
+				docId: {
+					type: String,
+					required: true
+				},
+				op: {
+					type: String,
+					enum: ["upsert", "delete"],
+					required: true
+				},
+				version: {
+					type: Number,
+					required: true
+				},
+				doc: { type: Schema.Types.Mixed },
+				tenantId: { type: String },
+				at: {
+					type: Date,
+					required: true
+				}
+			}, {
+				collection,
+				versionKey: false,
+				minimize: false
+			});
+			schema.index({ seq: 1 }, {
+				unique: true,
+				name: "feed_order"
+			});
+			schema.index({
+				tenantId: 1,
+				scope: 1,
+				seq: 1
+			}, { name: "tenant_scope_feed" });
+			return schema;
+		})()),
+		counter: connection.models[counterName] ?? connection.model(counterName, new Schema({
+			_id: {
+				type: String,
+				required: true
+			},
+			seq: {
+				type: Number,
+				required: true
+			}
+		}, {
+			collection: `${collection}_counter`,
+			versionKey: false
+		})),
+		feed: collection
+	};
+}
+/** Fixed-width, so the opaque cursor also sorts as text. */
+const toCursor = (seq) => String(seq).padStart(16, "0");
+const fromCursor = (cursor) => {
+	if (cursor === "") return 0;
+	const seq = Number(cursor);
+	if (!Number.isSafeInteger(seq) || seq < 0) throw new Error(`[mongokit:sync] "${cursor}" is not a cursor from this feed`);
+	return seq;
+};
+const DEFAULT_LIMIT = 500;
+function createChangeLogStore(models) {
+	const { entries, counter, feed } = models;
+	const sessionOf = (options) => options?.session ? { session: options.session } : {};
+	const filterOf = (after, options = {}) => {
+		const { tenantId, scopes, sharedScopes } = options;
+		const tenant = tenantId === void 0 ? {} : sharedScopes?.length ? { $or: [{ tenantId }, { scope: { $in: [...sharedScopes] } }] } : { tenantId };
+		return {
+			seq: { $gt: after },
+			...tenant,
+			...scopes ? { scope: { $in: [...scopes] } } : {}
+		};
+	};
+	const toEntry = (row) => ({
+		scope: row.scope,
+		docId: row.docId,
+		op: row.op,
+		version: row.version,
+		...row.doc !== void 0 && row.doc !== null ? { doc: row.doc } : {},
+		...typeof row.tenantId === "string" ? { tenantId: row.tenantId } : {},
+		at: row.at,
+		cursor: toCursor(row.seq)
+	});
+	return {
+		async append(entry, options) {
+			const session = sessionOf(options);
+			const seq = (await counter.findOneAndUpdate({ _id: feed }, { $inc: { seq: 1 } }, {
+				upsert: true,
+				returnDocument: "after",
+				lean: true,
+				...session
+			}).exec()).seq;
+			const at = /* @__PURE__ */ new Date();
+			await entries.create([{
+				seq,
+				scope: entry.scope,
+				docId: entry.docId,
+				op: entry.op,
+				version: entry.version,
+				...entry.op === "upsert" && entry.doc !== void 0 ? { doc: entry.doc } : {},
+				...entry.tenantId !== void 0 ? { tenantId: entry.tenantId } : {},
+				at
+			}], session);
+			return {
+				...entry,
+				at,
+				cursor: toCursor(seq)
+			};
+		},
+		async since(cursor, options = {}) {
+			const limit = options.limit ?? DEFAULT_LIMIT;
+			const rows = await entries.find(filterOf(fromCursor(cursor), options)).sort({ seq: 1 }).limit(limit + 1).lean().exec();
+			const page = rows.slice(0, limit).map(toEntry);
+			const last = page[page.length - 1];
+			return {
+				changes: page,
+				cursor: last ? last.cursor : cursor,
+				hasMore: rows.length > limit
+			};
+		},
+		async latestCursor(options = {}) {
+			const row = await entries.findOne(filterOf(0, options)).sort({ seq: -1 }).select({ seq: 1 }).lean().exec();
+			return row?.seq ? toCursor(row.seq) : "";
+		}
+	};
+}
+function createCommandStreamModels(connection, options = {}) {
+	const { prefix = "sync", modelName = "SyncStream" } = options;
+	const model = (name, schema) => connection.models[name] ?? connection.model(name, schema());
+	return {
+		streams: model(modelName, () => new Schema({
+			_id: {
+				type: String,
+				required: true
+			},
+			tenantId: {
+				type: String,
+				required: true
+			},
+			processed: {
+				type: Number,
+				required: true
+			}
+		}, {
+			collection: `${prefix}_streams`,
+			versionKey: false
+		})),
+		verdicts: model(`${modelName}Verdict`, () => {
+			const schema = new Schema({
+				_id: {
+					type: String,
+					required: true
+				},
+				stream: {
+					type: String,
+					required: true
+				},
+				seq: {
+					type: Number,
+					required: true
+				},
+				outcome: {
+					type: String,
+					enum: [
+						"applied",
+						"rejected",
+						"blocked",
+						"resolved"
+					],
+					required: true
+				},
+				code: { type: String },
+				fingerprint: {
+					type: String,
+					required: true
+				},
+				body: { type: String },
+				dependsOn: {
+					type: [String],
+					default: void 0
+				},
+				resolution: {
+					type: {
+						action: String,
+						by: String,
+						at: String,
+						_id: false
+					},
+					default: void 0
+				}
+			}, {
+				collection: `${prefix}_verdicts`,
+				versionKey: false
+			});
+			schema.index({
+				stream: 1,
+				seq: 1
+			}, {
+				unique: true,
+				name: "stream_seq"
+			});
+			schema.index({
+				dependsOn: 1,
+				outcome: 1
+			}, {
+				name: "blocked_on",
+				partialFilterExpression: { outcome: "blocked" }
+			});
+			return schema;
+		}),
+		aliases: model(`${modelName}Alias`, () => {
+			const schema = new Schema({
+				tenantId: {
+					type: String,
+					required: true
+				},
+				localId: {
+					type: String,
+					required: true
+				},
+				serverId: {
+					type: String,
+					required: true
+				}
+			}, {
+				collection: `${prefix}_aliases`,
+				versionKey: false
+			});
+			schema.index({
+				tenantId: 1,
+				localId: 1
+			}, {
+				unique: true,
+				name: "tenant_local"
+			});
+			return schema;
+		})
+	};
+}
+/**
+* The mongo {@link CommandStreamStore} (replica set). Proven by `runCommandStreamStoreConformance`.
+* Concurrent transactions on one stream write-conflict on its document and `withTransaction`
+* retries the loser, which then reads the winner's watermark.
+*/
+function createCommandStreamStore(connection, models, changes) {
+	const { streams, verdicts, aliases } = models;
+	const toVerdict = ({ _id, code, ...rest }) => ({
+		commandId: _id,
+		...rest,
+		...code == null ? {} : { code }
+	});
+	return {
+		changes,
+		transaction: (work) => withTransaction(connection, (session) => work({ session })),
+		async stream({ session }, id) {
+			const row = await streams.findById(id).session(session).lean().exec();
+			return row ? {
+				tenantId: row.tenantId,
+				processed: row.processed
+			} : null;
+		},
+		async advance({ session }, id, tenantId, from, to) {
+			if (from === 0) {
+				if (await streams.exists({ _id: id }).session(session)) return false;
+				await streams.create([{
+					_id: id,
+					tenantId,
+					processed: to
+				}], { session });
+				return true;
+			}
+			return (await streams.updateOne({
+				_id: id,
+				processed: from
+			}, { $set: { processed: to } }, { session }).exec()).modifiedCount === 1;
+		},
+		async verdict({ session }, commandId) {
+			const row = await verdicts.findById(commandId).session(session).lean().exec();
+			return row ? toVerdict(row) : null;
+		},
+		async record({ session }, { commandId, ...rest }) {
+			await verdicts.replaceOne({ _id: commandId }, rest, {
+				upsert: true,
+				session
+			}).exec();
+		},
+		async blockedOn({ session }, commandId) {
+			return (await verdicts.find({
+				outcome: "blocked",
+				dependsOn: commandId
+			}).sort({ seq: 1 }).session(session).lean().exec()).map(toVerdict);
+		},
+		async alias({ session }, { tenantId, localId, serverId }) {
+			const existing = await aliases.findOne({
+				tenantId,
+				localId
+			}).session(session).lean().exec();
+			if (existing) {
+				if (existing.serverId !== serverId) throw new Error(`[mongokit:sync] "${localId}" already names "${existing.serverId}"`);
+				return;
+			}
+			await aliases.create([{
+				tenantId,
+				localId,
+				serverId
+			}], { session });
+		},
+		async aliasOf({ session }, tenantId, localId) {
+			return (await aliases.findOne({
+				tenantId,
+				localId
+			}).session(session).lean().exec())?.serverId ?? null;
+		}
+	};
+}
+//#endregion
+export { createChangeLogModels, createChangeLogStore, createCommandStreamModels, createCommandStreamStore };

package/dist/tenant/index.d.mts

@@ -0,0 +1,89 @@
+import { Schema } from "mongoose";
+import { ResolvedTenantConfig } from "@classytic/repo-core/tenant";
+//#region src/tenant/index.d.ts
+/** Which read an index serves. Default `'tenant'`. See the module docblock. */
+type IndexScope = 'tenant' | 'global';
+/** Key directions and types a declaration may use. Mirrors what `schema.index()` accepts. */
+type IndexKeyValue = 1 | -1 | 'text' | '2dsphere' | '2d' | 'hashed';
+/**
+ * Index options passed through to `schema.index()`. `name` is the only one this module
+ * reads (to apply and to explain exemptions); everything else is Mongoose's.
+ */
+interface IndexDeclarationOptions {
+  name?: string | undefined;
+  unique?: boolean | undefined;
+  sparse?: boolean | undefined;
+  partialFilterExpression?: Record<string, unknown> | undefined;
+  expireAfterSeconds?: number | undefined;
+  collation?: Record<string, unknown> | undefined;
+  background?: boolean | undefined;
+  [option: string]: unknown;
+}
+/**
+ * One index, declared by a kernel for its own model or by a host through a kernel's
+ * `indexes` seam. The kernel applies it through {@link injectTenantField}, which is what
+ * makes `scope` mean something: a `'tenant'` declaration is prefixed exactly like the
+ * kernel's own indexes, a `'global'` one is kept as written.
+ */
+interface IndexDeclaration {
+  readonly fields: Readonly<Record<string, IndexKeyValue>>;
+  readonly options?: IndexDeclarationOptions | undefined;
+  /** @default 'tenant' */
+  readonly scope?: IndexScope | undefined;
+}
+interface InjectTenantFieldOptions {
+  /**
+   * Index NAMES (the `name` option of `schema.index()`) already on the schema whose key
+   * spec must NOT get the tenant prefix. The escape hatch for a kernel's OWN global
+   * identity index declared inline in its schema builder (`order_event_id_unique`: the
+   * event id is a kernel-generated UUID and the drain's idempotency contract is exactly
+   * one row per event regardless of tenant). Prefer declaring such an index through
+   * `indexes` with `scope: 'global'`; this exists so a schema builder need not know the
+   * tenant config. Unnamed indexes cannot be exempted: give the index a name first.
+   */
+  readonly skipIndexes?: readonly string[] | undefined;
+  /**
+   * Additional declarations, applied AFTER the prepend pass so their `scope` is honoured.
+   * This is where a kernel threads its host's `indexes` seam.
+   */
+  readonly indexes?: readonly IndexDeclaration[] | undefined;
+}
+/**
+ * Refuse a declaration that cannot mean what it says. Called before any schema mutation
+ * so a bad host config fails at DESCRIBE time, with the fix in the message, rather than
+ * building a wrong index on the first bind.
+ */
+declare function assertIndexDeclaration(declaration: IndexDeclaration, tenant: Pick<ResolvedTenantConfig, 'tenantField'>): void;
+/**
+ * Add `declarations` to `schema` honouring each one's scope.
+ *
+ * `'tenant'` declarations are prefixed with the tenant field when scoping is enabled
+ * (unless they already lead with it, so a host that wrote it out is not double-prefixed);
+ * `'global'` ones are added exactly as written. When scoping is disabled every declaration
+ * is added as written, because there is no partition to lead with.
+ *
+ * Exported for kernels whose optional models inject the tenant field on their own path and
+ * only need the host's extra declarations applied afterwards.
+ */
+declare function declareIndexes(schema: Schema, tenant: ResolvedTenantConfig, declarations: readonly IndexDeclaration[] | undefined): void;
+/**
+ * Inject the tenant field into a Mongoose schema and make its indexes tenant-correct.
+ *
+ * 1. Adds the field, typed by `tenant.fieldType` (`ObjectId` with `ref`, or `String`).
+ *    `required` only when scoping is enabled and the config says so: a single-tenant
+ *    deployment still gets the field, because domain verbs reference it in raw queries.
+ * 2. When scoping is enabled, prepends the tenant field to every index already declared
+ *    on the schema, EXCEPT: one that already names the field; a TTL index (MongoDB rejects
+ *    a compound TTL spec outright, and a time-driven sweep has no tenant to give); and any
+ *    index named in `skipIndexes`.
+ * 3. Applies `indexes` through {@link declareIndexes}, so a `'global'` declaration is never
+ *    touched by step 2 whatever order the caller thought about it in.
+ * 4. Guarantees one tenant-leading index. After the prepend any compound serves a
+ *    tenant-only query via the prefix rule, so a bare `{ tenant: 1 }` is added ONLY when
+ *    nothing was prepended: next to a compound it is a redundant prefix paid on every
+ *    insert (PACKAGE_RULES P11.1; the fleet index audit found this pattern behind most of
+ *    86 redundant indexes across 615).
+ */
+declare function injectTenantField(schema: Schema, tenant: ResolvedTenantConfig, options?: InjectTenantFieldOptions): void;
+//#endregion
+export { IndexDeclaration, IndexDeclarationOptions, IndexKeyValue, IndexScope, InjectTenantFieldOptions, assertIndexDeclaration, declareIndexes, injectTenantField };

package/dist/tenant/index.mjs

@@ -0,0 +1,96 @@
+import mongoose from "mongoose";
+//#region src/tenant/index.ts
+/** Mongoose keeps declared indexes on `schema._indexes`; `schema.indexes()` is a copy. */
+function indexEntries(schema) {
+	return schema._indexes ?? [];
+}
+function isScoped(tenant) {
+	return tenant.enabled && tenant.strategy === "field";
+}
+/**
+* Refuse a declaration that cannot mean what it says. Called before any schema mutation
+* so a bad host config fails at DESCRIBE time, with the fix in the message, rather than
+* building a wrong index on the first bind.
+*/
+function assertIndexDeclaration(declaration, tenant) {
+	if (Object.keys(declaration.fields).length === 0) throw new Error("[mongokit/tenant] an index declaration needs at least one field");
+	if (declaration.scope === "global") {
+		if (typeof declaration.options?.name !== "string" || declaration.options.name.length === 0) throw new Error(`[mongokit/tenant] a global index must be named: { fields: ${JSON.stringify(declaration.fields)}, scope: 'global' } has no \`options.name\`. A tenant exemption is deliberate, and an unnamed one cannot be told from an oversight.`);
+		if (declaration.fields[tenant.tenantField] !== void 0) throw new Error(`[mongokit/tenant] index "${declaration.options.name}" is scope 'global' but names the tenant field "${tenant.tenantField}". A global index serves reads that have no tenant to give; drop the field, or declare the index with scope 'tenant'.`);
+	}
+}
+/**
+* Add `declarations` to `schema` honouring each one's scope.
+*
+* `'tenant'` declarations are prefixed with the tenant field when scoping is enabled
+* (unless they already lead with it, so a host that wrote it out is not double-prefixed);
+* `'global'` ones are added exactly as written. When scoping is disabled every declaration
+* is added as written, because there is no partition to lead with.
+*
+* Exported for kernels whose optional models inject the tenant field on their own path and
+* only need the host's extra declarations applied afterwards.
+*/
+function declareIndexes(schema, tenant, declarations) {
+	if (!declarations || declarations.length === 0) return;
+	for (const declaration of declarations) {
+		assertIndexDeclaration(declaration, tenant);
+		const options = declaration.options;
+		const scoped = isScoped(tenant) && declaration.scope !== "global";
+		const leadsWithTenant = Object.keys(declaration.fields)[0] === tenant.tenantField;
+		const fields = scoped && !leadsWithTenant ? {
+			[tenant.tenantField]: 1,
+			...declaration.fields
+		} : { ...declaration.fields };
+		schema.index(fields, options);
+	}
+}
+/**
+* Inject the tenant field into a Mongoose schema and make its indexes tenant-correct.
+*
+* 1. Adds the field, typed by `tenant.fieldType` (`ObjectId` with `ref`, or `String`).
+*    `required` only when scoping is enabled and the config says so: a single-tenant
+*    deployment still gets the field, because domain verbs reference it in raw queries.
+* 2. When scoping is enabled, prepends the tenant field to every index already declared
+*    on the schema, EXCEPT: one that already names the field; a TTL index (MongoDB rejects
+*    a compound TTL spec outright, and a time-driven sweep has no tenant to give); and any
+*    index named in `skipIndexes`.
+* 3. Applies `indexes` through {@link declareIndexes}, so a `'global'` declaration is never
+*    touched by step 2 whatever order the caller thought about it in.
+* 4. Guarantees one tenant-leading index. After the prepend any compound serves a
+*    tenant-only query via the prefix rule, so a bare `{ tenant: 1 }` is added ONLY when
+*    nothing was prepended: next to a compound it is a redundant prefix paid on every
+*    insert (PACKAGE_RULES P11.1; the fleet index audit found this pattern behind most of
+*    86 redundant indexes across 615).
+*/
+function injectTenantField(schema, tenant, options = {}) {
+	for (const declaration of options.indexes ?? []) assertIndexDeclaration(declaration, tenant);
+	const declaredNames = new Set(indexEntries(schema).map(([, o]) => o?.name).filter((n) => typeof n === "string"));
+	for (const name of options.skipIndexes ?? []) if (!declaredNames.has(name)) throw new Error(`[mongokit/tenant] skipIndexes names '${name}', but no index on this schema has that name — rename the exemption with the index, or the index silently gets the tenant prefix`);
+	const isObjectId = tenant.fieldType === "objectId";
+	const scoped = isScoped(tenant);
+	schema.add({ [tenant.tenantField]: {
+		type: isObjectId ? mongoose.Schema.Types.ObjectId : String,
+		...scoped && tenant.required ? { required: true } : {},
+		...isObjectId && tenant.ref ? { ref: tenant.ref } : {}
+	} });
+	if (!scoped) {
+		declareIndexes(schema, tenant, options.indexes);
+		return;
+	}
+	const skip = new Set(options.skipIndexes ?? []);
+	for (const entry of indexEntries(schema)) {
+		const [fields, indexOptions] = entry;
+		if (fields[tenant.tenantField] !== void 0) continue;
+		if (indexOptions?.expireAfterSeconds !== void 0) continue;
+		const name = indexOptions?.name;
+		if (typeof name === "string" && skip.has(name)) continue;
+		entry[0] = {
+			[tenant.tenantField]: 1,
+			...fields
+		};
+	}
+	declareIndexes(schema, tenant, options.indexes);
+	if (!indexEntries(schema).some(([fields]) => Object.keys(fields)[0] === tenant.tenantField)) schema.index({ [tenant.tenantField]: 1 });
+}
+//#endregion
+export { assertIndexDeclaration, declareIndexes, injectTenantField };

package/dist/testkit/index.d.mts

@@ -1,5 +1,5 @@
-import { n as Repository } from "../Repository-BdSkQ8vc.mjs";
-import { n as CreateRepositoryConfig } from "../create-repository-BU4x9Kb0.mjs";
+import { r as Repository } from "../Repository-CR8Y9g2E.mjs";
+import { n as CreateRepositoryConfig } from "../create-repository-CAle1MSU.mjs";
 import { Connection, Model, Schema } from "mongoose";
 import { MongoMemoryReplSet, MongoMemoryServer } from "mongodb-memory-server";
 //#region src/testkit/index.d.ts

package/dist/testkit/index.mjs

@@ -1,4 +1,4 @@
-import { t as createRepository } from "../create-repository-B5EulQ31.mjs";
+import { t as createRepository } from "../create-repository-BzBUMvd1.mjs";
 import { createConnection } from "mongoose";
 //#region src/testkit/index.ts
 function idempotentStop(server) {