@classytic/mongokit 3.28.0 → 3.30.0

package/dist/index.mjs

@@ -1,19 +1,21 @@
 import { n as idVariants } from "./id-resolution-BqDrk0S2.mjs";
-import { a as supportsTransactions, c as ALL_OPERATIONS, d as READ_OPERATIONS, f as operationsByPolicyKey, i as isTransactionUnsupported, l as MUTATING_OPERATIONS, m as createMongoPurgePort, n as Repository, o as withTransaction, p as MONGOKIT_CAPABILITIES, r as batchTransaction, s as AggregationBuilder, t as HOOK_PRIORITY, u as OP_REGISTRY } from "./Repository-BFBTAMlA.mjs";
-import { b as LookupBuilder, x as compileFilterToMongo } from "./update-1Lq9OMD2.mjs";
+import { _ as resetCapabilityProbeCache, a as supportsTransactions, b as transactionResolutionOf, c as ALL_OPERATIONS, d as READ_OPERATIONS, f as operationsByPolicyKey, g as probeMongoCapabilities, h as classifyHelloReply, i as isTransactionUnsupported, l as MUTATING_OPERATIONS, m as capabilitiesForSupport, n as Repository, o as withTransaction, p as MONGOKIT_CAPABILITIES, r as batchTransaction, s as AggregationBuilder, t as HOOK_PRIORITY, u as OP_REGISTRY, v as resolveMongoCapabilities, x as createMongoPurgePort, y as resolveTransactionSupport } from "./Repository-X7U2d0kU.mjs";
+import { b as LookupBuilder, x as compileFilterToMongo } from "./update-DHdXdOk_.mjs";
 import { n as warn, t as configureLogger } from "./logger-K7dPmu2U.mjs";
 import { n as isDuplicateKeyError, r as parseDuplicateKeyError, t as createError } from "./error-BuByZwKU.mjs";
 import { t as actions_exports } from "./actions/index.mjs";
-import { a as methodRegistryPlugin, c as getNextSequence, d as cachePlugin, f as batchOperationsPlugin, g as auditLogPlugin, h as ensureAuditTrailReady, i as multiTenantPlugin, l as prefixedId, m as auditTrailPlugin, n as softDeletePlugin, o as customIdPlugin, p as AuditTrailQuery, r as adminBypass, s as dateSequentialId, t as timestampPlugin, u as sequentialId } from "./timestamp.plugin-ennbatTW.mjs";
+import { a as customIdPlugin, c as prefixedId, d as AuditTrailQuery, f as auditTrailPlugin, i as multiTenantPlugin, l as sequentialId, m as auditLogPlugin, n as softDeletePlugin, o as dateSequentialId, p as ensureAuditTrailReady, r as adminBypass, s as getNextSequence, t as timestampPlugin, u as cachePlugin } from "./timestamp.plugin-ChFRcLRJ.mjs";
+import { n as batchOperationsPlugin, t as methodRegistryPlugin } from "./method-registry.plugin-DblM7V6j.mjs";
 import { t as PaginationEngine } from "./PaginationEngine-CczbvCAq.mjs";
 import { isGeoOperator, parseGeoFilter } from "./query/primitives/geo.mjs";
-import { t as createRepository } from "./create-repository-2DMwkYVz.mjs";
-import { _ as cascadePlugin, a as uniqueField, c as subdocumentPlugin, d as mongoOperationsPlugin, f as leasePlugin, g as elasticSearchPlugin, h as fieldFilterPlugin, i as requireField, l as observabilityPlugin, m as immutableStatesPlugin, n as blockIf, o as validationChainPlugin, p as idempotencyStorePlugin, r as immutableField, s as createTenantContext, t as autoInject, u as MONGOKIT_PLUGIN_NAMES, v as appendOnlyPlugin, y as aggregateHelpersPlugin } from "./validation-chain.plugin-k9joH2qw.mjs";
+import { t as createRepository } from "./create-repository-DYe5YEie.mjs";
+import { n as defineModel, r as isModelRegistered, t as ModelCollisionError } from "./model-registry-ClKtWiHa.mjs";
+import { _ as cascadePlugin, a as uniqueField, c as subdocumentPlugin, d as mongoOperationsPlugin, f as leasePlugin, g as elasticSearchPlugin, h as fieldFilterPlugin, i as requireField, l as observabilityPlugin, m as idempotencyStorePlugin, n as blockIf, o as validationChainPlugin, p as immutableStatesPlugin, r as immutableField, s as createTenantContext, t as autoInject, u as MONGOKIT_PLUGIN_NAMES, v as appendOnlyPlugin, y as aggregateHelpersPlugin } from "./validation-chain.plugin-BxTl_dYR.mjs";
 import { i as getMongooseProjection, n as filterResponseData, r as getFieldsForUser, t as createFieldPreset } from "./field-selection-FSQFLpsU.mjs";
 import { buildFieldTypeMap, coerceFieldValue, coerceHeuristic } from "./query/primitives/coercion.mjs";
 import { extractSchemaIndexes } from "./query/primitives/indexes.mjs";
 import { n as createMemoryCache, t as toPlain } from "./to-plain-vksRrLtc.mjs";
-import { n as buildCrudSchemasFromMongooseSchema, t as buildCrudSchemasFromModel } from "./mongooseToJsonSchema-CByt1VhQ.mjs";
+import { n as buildCrudSchemasFromMongooseSchema, t as buildCrudSchemasFromModel } from "./mongooseToJsonSchema-DKbnKduN.mjs";
 import { runChunkedPurge } from "@classytic/repo-core/repository";
 import { isControlParam } from "@classytic/repo-core/query-parser";
 //#region src/actions/cascade-references.ts
@@ -145,6 +147,77 @@ async function cascadePurgeReferences(options) {
 	return out;
 }
 //#endregion
+//#region src/model-blueprint.ts
+function isProductionRuntime() {
+	return process.env.NODE_ENV === "production";
+}
+/**
+* Describe a set of models as a connection-free blueprint. Duplicate spec names are rejected
+* here, at describe time, before any connection is involved.
+*/
+function defineModels(spec) {
+	const { models, assemble } = spec;
+	const names = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const m of models) {
+		if (seen.has(m.name)) throw new Error(`[mongokit] defineModels: duplicate model spec name '${m.name}'. Each model must be described exactly once.`);
+		seen.add(m.name);
+		names.push(m.name);
+	}
+	const modelNames = Object.freeze([...names]);
+	return {
+		modelNames,
+		bind(connection) {
+			const map = /* @__PURE__ */ new Map();
+			const created = [];
+			const replaced = [];
+			try {
+				for (const s of models) {
+					const preExisting = isModelRegistered(s.name, connection);
+					if (s.existing.mode === "replace") {
+						if (isProductionRuntime()) throw new Error(`[mongokit] model '${s.name}' declares existing policy 'replace', which is forbidden when NODE_ENV=production. Use a separate connection for a second engine; do not clobber a live production model.`);
+						if (preExisting) {
+							const original = connection.models[s.name];
+							replaced.push({
+								name: s.name,
+								schema: original.schema,
+								collection: original.collection.name
+							});
+							connection.deleteModel(s.name);
+						}
+					}
+					const onExisting = s.existing.mode === "reuse" ? "reuse" : "throw";
+					const throwHint = s.existing.mode === "throw" && s.existing.hint ? s.existing.hint : `Registering model set [${modelNames.join(", ")}]; already bound this call: [${created.join(", ") || "none"}]${s.collection ? ` (collection '${s.collection}')` : ""}.`;
+					const model = defineModel(s.name, s.schema, {
+						onExisting,
+						connection,
+						throwHint,
+						...s.collection !== void 0 ? { collection: s.collection } : {}
+					});
+					if (!preExisting) created.push(s.name);
+					map.set(s.name, model);
+				}
+				return assemble(map);
+			} catch (err) {
+				const rollbackErrors = [];
+				for (const name of created) try {
+					connection.deleteModel(name);
+				} catch (e) {
+					rollbackErrors.push(e);
+				}
+				for (const r of replaced) try {
+					if (connection.models[r.name]) connection.deleteModel(r.name);
+					connection.model(r.name, r.schema, r.collection);
+				} catch (e) {
+					rollbackErrors.push(e);
+				}
+				if (rollbackErrors.length > 0) throw new AggregateError([err, ...rollbackErrors], `[mongokit] defineModels.bind failed AND ${rollbackErrors.length} rollback operation(s) failed — the connection model registry may be inconsistent.`);
+				throw err;
+			}
+		}
+	};
+}
+//#endregion
 //#region src/query/parser/pipeline-sanitizer.ts
 /**
 * Sanitize $match configuration to prevent dangerous operators.
@@ -1611,4 +1684,4 @@ function systemContext(extra) {
 */
 var src_default = Repository;
 //#endregion
-export { ALL_OPERATIONS, AggregationBuilder, AuditTrailQuery, HOOK_PRIORITY, LookupBuilder, MONGOKIT_CAPABILITIES, MONGOKIT_PLUGIN_NAMES, MUTATING_OPERATIONS, OP_REGISTRY, PaginationEngine, QueryParser, READ_OPERATIONS, Repository, actions_exports as actions, adminBypass, aggregateHelpersPlugin, appendOnlyPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, batchTransaction, blockIf, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, cachePlugin, cascadePlugin, cascadePurgeReferences, compileFilterToMongo, configureLogger, createError, createFieldPreset, createMemoryCache, createOptionsExtractor, createRepository, createTenantContext, customIdPlugin, dateSequentialId, src_default as default, elasticSearchPlugin, ensureAuditTrailReady, fieldFilterPlugin, filterResponseData, getFieldsForUser, getMongooseProjection, getNextSequence, idVariants, idempotencyStorePlugin, immutableField, immutableStatesPlugin, isDuplicateKeyError, isTransactionUnsupported, leasePlugin, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, operationsByPolicyKey, parseDuplicateKeyError, prefixedId, repoOptionsFromCtx, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, supportsTransactions, systemContext, timestampPlugin, toPlain, uniqueField, validationChainPlugin, withTransaction };
+export { ALL_OPERATIONS, AggregationBuilder, AuditTrailQuery, HOOK_PRIORITY, LookupBuilder, MONGOKIT_CAPABILITIES, MONGOKIT_PLUGIN_NAMES, MUTATING_OPERATIONS, ModelCollisionError, OP_REGISTRY, PaginationEngine, QueryParser, READ_OPERATIONS, Repository, actions_exports as actions, adminBypass, aggregateHelpersPlugin, appendOnlyPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, batchTransaction, blockIf, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, cachePlugin, capabilitiesForSupport, cascadePlugin, cascadePurgeReferences, classifyHelloReply, compileFilterToMongo, configureLogger, createError, createFieldPreset, createMemoryCache, createOptionsExtractor, createRepository, createTenantContext, customIdPlugin, dateSequentialId, src_default as default, defineModel, defineModels, elasticSearchPlugin, ensureAuditTrailReady, fieldFilterPlugin, filterResponseData, getFieldsForUser, getMongooseProjection, getNextSequence, idVariants, idempotencyStorePlugin, immutableField, immutableStatesPlugin, isDuplicateKeyError, isModelRegistered, isTransactionUnsupported, leasePlugin, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, operationsByPolicyKey, parseDuplicateKeyError, prefixedId, probeMongoCapabilities, repoOptionsFromCtx, requireField, resetCapabilityProbeCache, resolveMongoCapabilities, resolveTransactionSupport, sequentialId, softDeletePlugin, subdocumentPlugin, supportsTransactions, systemContext, timestampPlugin, toPlain, transactionResolutionOf, uniqueField, validationChainPlugin, withTransaction };

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

@@ -0,0 +1,217 @@
+import { Connection } from "mongoose";
+//#region src/kernel-conformance/types.d.ts
+/**
+ * Every check the suite can run, in execution order. The ids are STABLE — `skip` is typed
+ * against this tuple, so a typo is a compile error rather than a silently-ineffective skip
+ * (a skip that skips nothing is the same silent-permissiveness bug class the suite exists
+ * to catch).
+ */
+declare const KERNEL_CONFORMANCE_CHECKS: readonly ["describe-purity", "blueprint-model-names", "bind-registers-declared-models", "bind-connection-scoped", "bind-no-index-io", "no-autoindex-on-bind", "fresh-schema-per-connection", "double-bind-collision", "transport-not-closed-when-supplied", "owned-transport-closed", "close-idempotent", "no-legacy-surface", "maintenance-fails-loud", "bind-verifies-requirements", "outbox-requires-transactional-save", "optional-modules-register-no-models"];
+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.
+ */
+declare const CONDITIONAL_CHECKS: readonly ["bind-verifies-requirements", "outbox-requires-transactional-save", "optional-modules-register-no-models"];
+/**
+ * The two runner functions the suite needs, INJECTED by the consumer.
+ *
+ * mongokit deliberately does not import `vitest` (not even as an optional peer): the suite
+ * would then only work under one runner and would put a test framework in the dependency
+ * graph of a package every kernel installs in production. Injection costs the consumer one
+ * line — `runner: { describe, it }` — and in exchange the suite runs unmodified under
+ * vitest, jest, mocha or `node:test`. Assertions are internal (precise `Error` messages),
+ * so no `expect` implementation is required either.
+ */
+interface ConformanceRunner {
+  describe(name: string, fn: () => void): unknown;
+  it(name: string, fn: () => void | Promise<void>): unknown;
+}
+/** The minimum a `defineX(shape)` result must expose to be conformance-testable. */
+interface KernelBlueprintLike {
+  readonly id?: string;
+  readonly modelNames: readonly string[];
+}
+/** A domain-event-shaped envelope. Structural — the suite never imports primitives. */
+interface ConformanceEvent {
+  readonly type: string;
+  readonly payload?: unknown;
+  readonly meta?: Record<string, unknown>;
+}
+/**
+ * Structurally compatible with `@classytic/primitives`' `EventTransport` and arc's
+ * `MemoryEventTransport`. Declared here so mongokit stays dependency-free.
+ */
+interface EventTransportLike {
+  readonly name?: string;
+  publish(event: ConformanceEvent): Promise<void> | void;
+  publishMany?(events: readonly ConformanceEvent[]): Promise<unknown>;
+  subscribe?(pattern: string, handler: (event: ConformanceEvent) => unknown): Promise<() => void> | (() => void);
+  close?(): Promise<void> | void;
+}
+/** Collaborators the suite hands to `bind`. The kernel maps them onto its own runtime. */
+interface KernelBindContext {
+  /**
+   * Present ONLY for the supplied-transport ownership check. When absent the kernel must
+   * create (and therefore own) its internal bus.
+   */
+  readonly transport?: EventTransportLike;
+}
+/** A connection plus its teardown. Return this from `connect` when cleanup is needed. */
+interface ConformanceConnectionHandle {
+  readonly connection: Connection;
+  teardown?(): Promise<void> | void;
+}
+type ConformanceConnect = () => Promise<Connection | ConformanceConnectionHandle>;
+/**
+ * An explicit, REASONED opt-out. The reason is required: an unexplained skip is
+ * indistinguishable from an oversight, and this suite exists because oversights were
+ * invisible.
+ */
+interface ConformanceSkip {
+  readonly check: ConformanceCheck;
+  readonly reason: string;
+}
+type ConformanceCheckOutcome = 'run' | 'skipped' | 'not-exercised';
+interface ConformanceCheckStatus {
+  readonly check: ConformanceCheck;
+  readonly outcome: ConformanceCheckOutcome;
+  /** Why it was skipped, or which option would exercise a conditional check. */
+  readonly reason?: string;
+}
+/** Emitted once per suite, before any test runs. */
+interface KernelConformanceReport {
+  readonly kernel: string;
+  readonly checks: readonly ConformanceCheckStatus[];
+  readonly skipped: readonly ConformanceCheckStatus[];
+  readonly notExercised: readonly ConformanceCheckStatus[];
+}
+interface KernelConformanceOptions<TBlueprint extends KernelBlueprintLike, TEngine> {
+  /** Kernel name, e.g. `'party'`. Used in test titles and to derive legacy export names. */
+  readonly name: string;
+  /** `describe`/`it` from the consumer's own test runner. See {@link ConformanceRunner}. */
+  readonly runner: ConformanceRunner;
+  /**
+   * A FACTORY, not a value — `() => defineParty({ ... })`.
+   *
+   * Purity (§11.1) is only observable if the suite can call `defineX` itself while watching
+   * the model registries; a pre-built blueprint has already done whatever it was going to do.
+   * The factory also gives every check a pristine blueprint, so one check's bind can never
+   * poison another's.
+   *
+   * Describe the conformance blueprint WITHOUT `forceRecreate` (the collision check needs a
+   * real collision) and, when the kernel offers it, with `autoIndex: false`.
+   */
+  readonly blueprint: () => TBlueprint;
+  /**
+   * A live or registry-only connection. `async () => mongoose.createConnection()` (never
+   * connected) is enough for every check and needs no server — model registration and the
+   * index-call spies are registry-level. Return a {@link ConformanceConnectionHandle} when
+   * teardown is needed. Called once per check that binds.
+   */
+  readonly connect: ConformanceConnect;
+  /** Bind the blueprint the suite handed you. Map `ctx.transport` onto the kernel runtime. */
+  readonly bind: (blueprint: TBlueprint, connection: Connection, ctx: KernelBindContext) => TEngine | Promise<TEngine>;
+  /**
+   * Build the transport used by `transport-not-closed-when-supplied`. Defaults to the
+   * suite's own in-process transport, which satisfies the `EventTransport` contract.
+   */
+  readonly makeTransport?: () => EventTransportLike;
+  /**
+   * The exact model set the blueprint must declare. Supplied ⇒ an exact match is REQUIRED;
+   * a drift in either direction fails.
+   */
+  readonly expectedModelNames?: readonly string[];
+  /**
+   * The kernel's public module namespace (`import * as kernel from '../../src/index.js'`)
+   * or a list of its exported names. Required by `no-legacy-surface`.
+   */
+  readonly moduleExports?: Readonly<Record<string, unknown>> | readonly string[];
+  /** Extra export names that must NOT exist (legacy factories this kernel used to ship). */
+  readonly forbiddenExportNames?: readonly string[];
+  /** The sole construction export. Defaults to `define<Pascal(name)>`, e.g. `defineParty`. */
+  readonly constructionExportName?: string;
+  /**
+   * Find the engine's INTERNAL transport for the owned-transport check. Defaults to the
+   * first transport-shaped value among `events`, `transport`, `eventTransport`, `bus`.
+   */
+  readonly resolveInternalTransport?: (engine: TEngine) => EventTransportLike | undefined;
+  /**
+   * Direct probe for "was the internally-created bus closed?". Overrides the default
+   * subscribe-publish-close-publish observation when a kernel's bus is not reachable.
+   */
+  readonly internalTransportClosed?: (engine: TEngine) => boolean | Promise<boolean>;
+  /**
+   * Bind with a deliberately UNMET runtime requirement. Must reject/throw (§11.5).
+   * Enables `bind-verifies-requirements`.
+   */
+  readonly bindWithUnmetRequirement?: (connection: Connection) => unknown | Promise<unknown>;
+  /**
+   * Bind with an injected `OutboxStore` whose `transactionalSave` is ABSENT or `false` — the
+   * exact shape of a hand-rolled host store. The bind must reject/throw, and the error must
+   * NAME `transactionalSave`. Enables `outbox-requires-transactional-save`.
+   *
+   * ```ts
+   * bindWithNonTransactionalOutbox: (connection) =>
+   *   defineX({ … }).bind(connection, { outbox: { save: async () => undefined } as never }),
+   * ```
+   *
+   * ## When to supply it — and when a reasoned `skip` is the RIGHT answer
+   *
+   * The rule is **"this kernel persists outbox rows that must commit atomically with the state
+   * change they describe"**, NOT "this kernel's runtime happens to accept an `outbox`". Of the
+   * 32 kernels that thread an outbox through their runtime, only three verified the flag; but
+   * the remedy for the other 29 is a JUDGEMENT per kernel, not a sweep.
+   *
+   * Supply it when a rolled-back write could still emit its event and a downstream consumer
+   * would ACT on the ghost — a sale that never committed paying a commission, an access grant
+   * that never committed syncing a credential. That is the case `@classytic/access` and
+   * `@classytic/referral` gate at boot.
+   *
+   * SKIP it, with the reason stating so, when the kernel's outbox use is genuinely best-effort:
+   * the events are notifications/telemetry that a later reconciliation would correct, or nothing
+   * downstream takes an irreversible action on them. Inventing a requirement no code path needs
+   * is decoration of the opposite kind — a recorded remedy for `referral` demanded `transactions`
+   * on the belief that `convert()` wrote a row AND bumped a counter, when `attributeSale` is one
+   * read plus one atomic `getOrCreate`. Read the write paths before deciding.
+   *
+   * A kernel whose runtime accepts no outbox at all skips with that as the reason.
+   */
+  readonly bindWithNonTransactionalOutbox?: (connection: Connection) => unknown | Promise<unknown>;
+  /**
+   * A blueprint describing the kernel with its OPTIONAL modules disabled. Enables
+   * `optional-modules-register-no-models` (§11.10).
+   */
+  readonly minimalBlueprint?: () => TBlueprint;
+  /**
+   * Explicit, reasoned opt-outs. Unknown or duplicate ids throw at call time. Every skip is
+   * printed and registered as a visible marker test.
+   */
+  readonly skip?: readonly ConformanceSkip[];
+  /** Receives the manifest before any test runs. Defaults to a `console` summary. */
+  readonly onReport?: (report: KernelConformanceReport) => void;
+}
+//#endregion
+//#region src/kernel-conformance/suite.d.ts
+declare function describeKernelConformance<TBlueprint extends KernelBlueprintLike, TEngine>(opts: KernelConformanceOptions<TBlueprint, TEngine>): void;
+//#endregion
+//#region src/kernel-conformance/transport.d.ts
+/** A minimal, valid domain-event envelope (`type` + `meta.id` is all any bus reads). */
+declare function conformanceEvent(type: string): ConformanceEvent;
+/** An in-process transport good enough to stand in for a host-owned shared bus. */
+declare function createConformanceTransport(name?: string): EventTransportLike;
+interface InstrumentedTransport {
+  /** Hand THIS to the kernel. */
+  readonly transport: EventTransportLike;
+  /** How many times the kernel called `close()` on it. Must stay 0. */
+  closeCalls(): number;
+}
+/**
+ * Wrap a transport so `close()` calls are counted. The wrapper forwards everything else, so
+ * the kernel cannot tell the difference — which is the point: ownership must be decided by
+ * "did I create this?", never by inspecting the object.
+ */
+declare function instrumentTransport(inner: EventTransportLike): InstrumentedTransport;
+//#endregion
+export { CONDITIONAL_CHECKS, type ConformanceCheck, type ConformanceCheckOutcome, type ConformanceCheckStatus, type ConformanceConnect, type ConformanceConnectionHandle, type ConformanceEvent, type ConformanceRunner, type ConformanceSkip, type EventTransportLike, type InstrumentedTransport, KERNEL_CONFORMANCE_CHECKS, type KernelBindContext, type KernelBlueprintLike, type KernelConformanceOptions, type KernelConformanceReport, conformanceEvent, createConformanceTransport, describeKernelConformance, instrumentTransport };