@classytic/mongokit 3.45.0 → 3.46.0

package/README.md

@@ -584,6 +584,25 @@ describeKernelConformance({
 });
 ```
 
+### Sharding readiness: `tenantUniques`
+
+MongoDB refuses `shardCollection` on a tenant key while ANY unique index lacks that key as its
+prefix, so one global unique index makes a collection unshardable by tenant. Supply
+`tenantUniques` to enable `unique-indexes-tenant-prefixed`: the suite binds the kernel with
+tenancy ON, reads every registered schema's indexes, and requires each unique one to lead with the
+tenant field, or to appear in `allowGlobal` with a reason and a disposition for when the
+deployment is sharded or split into pods (`shard-key-prefix`, `identity-registry`, `pod-local` or
+`drop`). It also fails when no unique index was inspected, and on a stale or reasonless
+`allowGlobal` entry.
+
+```ts
+tenantUniques: {
+  tenantField: 'organizationId',
+  bindScoped: (conn) => kernel.defineParty({ tenant: { enabled: true }, autoIndex: false }).bind(conn, runtime),
+  allowGlobal: [{ index: 'party_site_slug', reason: 'public slug, no tenant', t2: 'identity-registry' }],
+},
+```
+
 Check ids are exported as `KERNEL_CONFORMANCE_CHECKS` (a `const` tuple, so `skip` is a typed
 union — a mistyped id is a compile error, not an ineffective skip).
 

package/dist/kernel-conformance/index.d.mts

@@ -37,14 +37,16 @@ export declare const KERNEL_CONFORMANCE_CHECKS: readonly [
 /** §11.5 — an injected outbox that does not enlist `ctx.session` is REFUSED. (conditional) */
 'outbox-requires-transactional-save',
 /** §11.10 — a blueprint with optional modules off registers no extra models. (conditional) */
-'optional-modules-register-no-models'];
+'optional-modules-register-no-models',
+/** scale D7 — every unique index leads with the tenant field, or is a registered global. (conditional) */
+'unique-indexes-tenant-prefixed'];
 type ConformanceCheck = (typeof KERNEL_CONFORMANCE_CHECKS)[number];
 /**
  * Checks that only run when the kernel supplies the input they need. When the input is
  * absent they are reported as NOT EXERCISED — a visible marker test plus a report entry,
  * never a silent pass.
  */
-export declare const CONDITIONAL_CHECKS: readonly ["bind-verifies-requirements", "outbox-requires-transactional-save", "optional-modules-register-no-models"];
+export declare const CONDITIONAL_CHECKS: readonly ["bind-verifies-requirements", "outbox-requires-transactional-save", "optional-modules-register-no-models", "unique-indexes-tenant-prefixed"];
 /**
  * The two runner functions the suite needs, INJECTED by the consumer.
  *
@@ -118,6 +120,23 @@ interface KernelConformanceReport {
   readonly skipped: readonly ConformanceCheckStatus[];
   readonly notExercised: readonly ConformanceCheckStatus[];
 }
+/** What becomes of a deliberately global unique index once a deployment is sharded or podded (D7). */
+type GlobalUniqueDisposition = 'shard-key-prefix' | 'identity-registry' | 'pod-local' | 'drop';
+/** A unique index that is global ON PURPOSE. A bare name is not enough: the reason is the contract. */
+interface AllowedGlobalUnique {
+  /** The index NAME as declared (`options.name`), or its keys joined by `,` when unnamed. */
+  readonly index: string;
+  readonly reason: string;
+  readonly t2: GlobalUniqueDisposition;
+}
+interface TenantUniquesOptions {
+  /** The tenant field the kernel prefixes with, e.g. `'organizationId'`. */
+  readonly tenantField: string;
+  /** Bind the kernel with tenancy ENABLED (field strategy) on the connection the suite supplies. */
+  readonly bindScoped: (connection: Connection) => unknown | Promise<unknown>;
+  /** Deliberate globals. Empty (the default) means every unique index must be tenant-led. */
+  readonly allowGlobal?: readonly AllowedGlobalUnique[];
+}
 interface KernelConformanceOptions<TBlueprint extends KernelBlueprintLike, TEngine> {
   /** Kernel name, e.g. `'party'`. Used in test titles and to derive legacy export names. */
   readonly name: string;
@@ -215,6 +234,28 @@ interface KernelConformanceOptions<TBlueprint extends KernelBlueprintLike, TEngi
    * `optional-modules-register-no-models` (§11.10).
    */
   readonly minimalBlueprint?: () => TBlueprint;
+  /**
+   * Enables `unique-indexes-tenant-prefixed` (scale decision D7).
+   *
+   * MongoDB refuses `shardCollection` on a tenant key when ANY unique index does not start with
+   * that key, so one global unique makes the whole collection unshardable by tenant and turns a
+   * later move to pods or shards into a data migration. The check binds the kernel with tenancy
+   * ON, reads every registered schema's indexes, and requires each unique one to lead with the
+   * tenant field, or to be registered in `allowGlobal` with a reason and a T2 disposition.
+   *
+   * It also fails when it inspected no unique index at all (a scan that finds nothing proves
+   * nothing), and when an `allowGlobal` entry names an index that no longer exists or is now
+   * tenant-led (a stale entry would hide a real one).
+   *
+   * ```ts
+   * tenantUniques: {
+   *   tenantField: 'organizationId',
+   *   bindScoped: (connection) => defineX({ tenant: { enabled: true } }).bind(connection, runtime),
+   *   allowGlobal: [{ index: 'directory_site_slug', reason: 'public slug resolved without a tenant', t2: 'identity-registry' }],
+   * }
+   * ```
+   */
+  readonly tenantUniques?: TenantUniquesOptions;
   /**
    * Explicit, reasoned opt-outs. Unknown or duplicate ids throw at call time. Every skip is
    * printed and registered as a visible marker test.
@@ -240,4 +281,4 @@ interface InstrumentedTransport {
  * "did I create this?", never by inspecting the object.
  */
 export declare function instrumentTransport(inner: EventTransportLike): InstrumentedTransport;
-export type { ConformanceCheck, ConformanceCheckOutcome, ConformanceCheckStatus, ConformanceConnect, ConformanceConnectionHandle, ConformanceEvent, ConformanceRunner, ConformanceSkip, EventTransportLike, InstrumentedTransport, KernelBindContext, KernelBlueprintLike, KernelConformanceOptions, KernelConformanceReport };
+export type { AllowedGlobalUnique, ConformanceCheck, ConformanceCheckOutcome, ConformanceCheckStatus, ConformanceConnect, ConformanceConnectionHandle, ConformanceEvent, ConformanceRunner, ConformanceSkip, EventTransportLike, GlobalUniqueDisposition, InstrumentedTransport, KernelBindContext, KernelBlueprintLike, KernelConformanceOptions, KernelConformanceReport, TenantUniquesOptions };

package/dist/kernel-conformance/index.mjs

@@ -104,7 +104,8 @@ const KERNEL_CONFORMANCE_CHECKS = [
 	"maintenance-fails-loud",
 	"bind-verifies-requirements",
 	"outbox-requires-transactional-save",
-	"optional-modules-register-no-models"
+	"optional-modules-register-no-models",
+	"unique-indexes-tenant-prefixed"
 ];
 /**
 * Checks that only run when the kernel supplies the input they need. When the input is
@@ -114,7 +115,8 @@ const KERNEL_CONFORMANCE_CHECKS = [
 const CONDITIONAL_CHECKS = [
 	"bind-verifies-requirements",
 	"outbox-requires-transactional-save",
-	"optional-modules-register-no-models"
+	"optional-modules-register-no-models",
+	"unique-indexes-tenant-prefixed"
 ];
 // src/kernel-conformance/suite.ts
 /**
@@ -217,12 +219,14 @@ function describeKernelConformance(opts) {
 	const conditionalInputs = {
 		"bind-verifies-requirements": "bindWithUnmetRequirement",
 		"outbox-requires-transactional-save": "bindWithNonTransactionalOutbox",
-		"optional-modules-register-no-models": "minimalBlueprint"
+		"optional-modules-register-no-models": "minimalBlueprint",
+		"unique-indexes-tenant-prefixed": "tenantUniques"
 	};
 	const conditionalSupplied = {
 		"bind-verifies-requirements": opts.bindWithUnmetRequirement !== void 0,
 		"outbox-requires-transactional-save": opts.bindWithNonTransactionalOutbox !== void 0,
-		"optional-modules-register-no-models": opts.minimalBlueprint !== void 0
+		"optional-modules-register-no-models": opts.minimalBlueprint !== void 0,
+		"unique-indexes-tenant-prefixed": opts.tenantUniques !== void 0
 	};
 	const statuses = KERNEL_CONFORMANCE_CHECKS.map((check) => {
 		const reason = skipReasons.get(check);
@@ -589,6 +593,41 @@ function describeKernelConformance(opts) {
 				assert(check, drift.extra.length === 0 && drift.missing.length === 0, `the minimal bind registered [${registered.join(", ")}] but declared [${minimal.modelNames.join(", ")}] — a disabled module still compiled a model`);
 			});
 		});
+		register("unique-indexes-tenant-prefixed", "every unique index leads with the tenant field, or is a registered global", async () => {
+			const check = "unique-indexes-tenant-prefixed";
+			const cfg = opts.tenantUniques;
+			const allowed = new Map((cfg.allowGlobal ?? []).map((g) => [g.index, g]));
+			for (const g of allowed.values()) assert(check, g.reason.trim().length > 0, `allowGlobal entry '${g.index}' has no reason — a global unique index without one is the defect this check exists to catch`);
+			await withConnection(async (connection) => {
+				const before = new Set(Object.keys(connection.models));
+				await opts.tenantUniques?.bindScoped(connection);
+				const offenders = [];
+				const seenGlobals = /* @__PURE__ */ new Set();
+				let inspected = 0;
+				for (const modelName of Object.keys(connection.models).filter((n) => !before.has(n))) {
+					const schema = connection.models[modelName]?.schema;
+					for (const [fields, options] of schema?.indexes() ?? []) {
+						if (!options?.unique) continue;
+						inspected++;
+						const keys = Object.keys(fields);
+						const name = String(options.name ?? keys.join(","));
+						if (keys[0] === cfg.tenantField) {
+							assert(check, !allowed.has(name), `allowGlobal lists '${name}' but it already leads with '${cfg.tenantField}' — remove the stale entry (it would hide a future global)`);
+							continue;
+						}
+						if (allowed.has(name)) {
+							seenGlobals.add(name);
+							continue;
+						}
+						offenders.push(`${modelName}.${name} {${keys.join(", ")}}`);
+					}
+				}
+				assert(check, offenders.length === 0, `unique index(es) that do not lead with '${cfg.tenantField}': [${offenders.join("; ")}]. MongoDB refuses shardCollection on a tenant key while any unique index lacks it. Prefix the index with the tenant field, or register it in tenantUniques.allowGlobal with a reason and a T2 disposition.`);
+				assert(check, inspected > 0, "no unique index was inspected — the scoped bind registered none, so this check proved nothing");
+				const stale = [...allowed.keys()].filter((n) => !seenGlobals.has(n));
+				assert(check, stale.length === 0, `allowGlobal names index(es) that no scoped model declares: [${stale.join(", ")}] — remove them`);
+			});
+		});
 	});
 }
 function defaultReport(report) {

package/package.json

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