@classytic/mongokit 3.29.0 → 3.31.0

package/README.md

@@ -430,6 +430,49 @@ Atlas **`$search` / `$vectorSearch`** indexes are Atlas-only and don't exist on
 
 All accept `{ replset?, dbName?, uri? }`.
 
+## Kernel Conformance — `@classytic/mongokit/kernel-conformance`
+
+An **executable contract suite** for domain kernels built on `defineModels()`. A kernel that
+follows the Describe → Bind → Verify → Serve → Close lifecycle wires this into its own test
+directory; passing it IS conformance.
+
+It asserts what ordinary kernel tests do not: that `defineX(shape)` registers nothing, that
+`bind` registers exactly the declared models on the SUPPLIED connection and performs no index
+I/O, that a second bind throws `ModelCollisionError`, that a host-supplied event transport is
+never closed while an internally-created one is, that `close()` is idempotent, that no legacy
+`createX`/`destroy`/`dispose` surface survives, and that a failing index sync REJECTS rather
+than being swallowed.
+
+**The test runner is injected, never imported** — mongokit takes no dependency (not even an
+optional peer) on vitest, and the suite runs unmodified under any runner that exposes
+`describe`/`it`. Assertions are internal, so no `expect` implementation is required.
+
+```ts
+import mongoose from 'mongoose';
+import { describe, it } from 'vitest';
+import { describeKernelConformance } from '@classytic/mongokit/kernel-conformance';
+import * as kernel from '../../src/index.js';
+
+describeKernelConformance({
+  name: 'party',
+  runner: { describe, it },
+  // A FACTORY — purity is only observable if the suite can call defineX itself.
+  blueprint: () => kernel.defineParty({ multiTenant: false, autoIndex: false }),
+  // Never connected: every check is registry-level, so no server is needed.
+  connect: async () => mongoose.createConnection(),
+  bind: (bp, conn, ctx) => bp.bind(conn, { eventTransport: ctx.transport }),
+  expectedModelNames: ['Party'],
+  moduleExports: kernel,
+  // Opt-outs are explicit, typed, and REQUIRE a reason; each one still emits a
+  // visible `[SKIPPED] <id> — <reason>` test. A silent skip is the bug this suite exists
+  // to prevent.
+  skip: [{ check: 'bind-verifies-requirements', reason: '…' }],
+});
+```
+
+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).
+
 ## License
 
 MIT

package/dist/{PaginationEngine-CczbvCAq.mjs → PaginationEngine-CuONvwCM.mjs}

@@ -636,7 +636,27 @@ var PaginationEngine = class {
 			hasNext = data.length > sanitizedLimit;
 			if (hasNext) data.pop();
 		} else hasNext = sanitizedPage < totalPages;
-		const warning = shouldWarnDeepPagination(sanitizedPage, this.config.deepPageThreshold) ? `Deep pagination (page ${sanitizedPage}). Consider getAll({ after, sort, limit }) for better performance.` : void 0;
+		/**
+		* A CLAMPED limit is reported, not swallowed.
+		*
+		* `validateLimit` caps silently by design — an over-ask is benign and rejecting it
+		* would be worse (that contradiction cost a day: the querystring schema's `maximum`
+		* made the parser's documented clamp unreachable, so `?limit=200` 400'd and two UI
+		* callers rendered the failure as an empty list).
+		*
+		* But clamping quietly has its own cost. A caller asking for 1000 and receiving 100
+		* gets an arbitrary slice with no signal — which is exactly how a bank-account
+		* picker rendered "No accounts found" against 696 accounts, because the rows it
+		* wanted were outside the first page. `limit` in the response already carries the
+		* effective value; nobody compares it. A warning is the channel that is actually
+		* read.
+		*
+		* Deep-pagination takes precedence when both apply: it is the more actionable of
+		* the two, and stacking warnings turns a signal into noise.
+		*/
+		const requestedLimit = Number(limit);
+		const wasClamped = Number.isFinite(requestedLimit) && requestedLimit > sanitizedLimit;
+		const warning = shouldWarnDeepPagination(sanitizedPage, this.config.deepPageThreshold) ? `Deep pagination (page ${sanitizedPage}). Consider getAll({ after, sort, limit }) for better performance.` : wasClamped ? `Requested limit ${Math.floor(requestedLimit)} exceeds this repository's cap; returning ${sanitizedLimit}. Filter server-side or sort deterministically — the returned page is otherwise an arbitrary slice.` : void 0;
 		return {
 			method: "offset",
 			data,

package/dist/{create-repository-D4ZU94b3.d.mts → Repository-BAzymuOz.d.mts}

@@ -1,10 +1,8 @@
-import { _ as WithTransactionOptions, a as DeleteManyResult, f as OperationOptions, g as UpdateOptions, h as UpdateManyResult, i as CreateOptions, l as LookupPopulateOptions, m as SessionOptions, o as DeleteResult, p as ReadOptions, r as CacheableOptions, s as FindOneAndUpdateOptions, t as AggregateOptions, u as LookupPopulateResult, v as LookupBuilder, y as LookupOptions } from "./operations-C8IcCHF9.mjs";
+import { _ as WithTransactionOptions, a as DeleteManyResult, f as OperationOptions, g as UpdateOptions, h as UpdateManyResult, i as CreateOptions, l as LookupPopulateOptions, m as SessionOptions, o as DeleteResult, p as ReadOptions, r as CacheableOptions, s as FindOneAndUpdateOptions, t as AggregateOptions, u as LookupPopulateResult, v as LookupBuilder, y as LookupOptions } from "./operations-CuzX9m2Z.mjs";
 import { a as PopulateSpec, i as ObjectId, l as SortSpec$1, o as ReadPreferenceType, s as SelectSpec } from "./core-62oo3N1C.mjs";
 import { c as PaginationConfig, r as CollationOptions, t as AggregatePaginationOptions } from "./pagination-jSUdrACK.mjs";
-import { _ as RepositoryOptions, d as PluginType, f as PrioritizedHook, o as Middleware, p as RepositoryContext } from "./repository-DCHRWRXw.mjs";
-import { T as AuditTrailOptions, _ as RepositoryCachePluginOptions, i as CustomIdOptions, t as MultiTenantOptions } from "./multi-tenant.plugin-DVyVGREb.mjs";
+import { _ as RepositoryOptions, d as PluginType, f as PrioritizedHook, o as Middleware, p as RepositoryContext } from "./repository-Q16ErTu8.mjs";
 import { t as PaginationEngine } from "./PaginationEngine-CBS1XGzp.mjs";
-import { i as Logger, o as SoftDeleteOptions } from "./plugin-options-vFufQZMZ.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";
 import { Filter } from "@classytic/repo-core/filter";
@@ -526,8 +524,29 @@ declare class Repository<TDoc = unknown> extends RepositoryBase {
    * Runtime capability descriptor required by `StandardRepo<TDoc>`
    * (repo-core 0.6.0). Hosts feature-detect once at boot instead of
    * try/catching `UnsupportedOperationError` per call.
-   */
-  readonly capabilities: RepoCapabilities;
+   *
+   * **OBSERVED, not declared** (changed 2026-08-05). Until then this was a
+   * class field pointing at the static `MONGOKIT_CAPABILITIES`, so
+   * `transactions` read `true` for every mongoose-backed repository —
+   * including one pointed at a standalone `mongod`, which cannot run a
+   * transaction at all. Every kernel boot gate that reads it (wallet, party,
+   * invoice, purchase, flow, …) was therefore unfalsifiable decoration
+   * (AGENTS.md FAIL LOUD rule 4).
+   *
+   * Now it derives the deployment-dependent flags (`transactions`,
+   * `nestedTransactions`, `changeStreams`) from THIS model's connection and
+   * its live SDAM topology. A getter rather than a constructor snapshot on
+   * purpose: a repository built before `mongoose.connect()` resolves upgrades
+   * its own answer the moment the connection is up, with no invalidation step.
+   * When the topology cannot be read the answer is `transactions: false` +
+   * `transactionsResolution: 'unknown'` — fail closed, never an optimistic
+   * yes (rule 3). See `capabilities.ts` and `probeMongoCapabilities`.
+   *
+   * `options.capabilities` overrides the whole descriptor for hosts/tests that
+   * genuinely know better (a proxied connection, a non-mongoose driver seam).
+   */
+  get capabilities(): RepoCapabilities;
+  private readonly _capabilitiesOverride;
   readonly Model: Model<TDoc>;
   /**
    * Mongoose model name. Duplicated on the instance for BC — arc / catalog /
@@ -927,8 +946,9 @@ declare class Repository<TDoc = unknown> extends RepositoryBase {
   /**
    * Update a document by id and return the post-update doc.
    *
-   * Compiles to `Model.findOneAndUpdate(filter, { $set: data }, { new:
-   * true, runValidators: true })` under the hood and routes through the
+   * Compiles to `Model.findOneAndUpdate(filter, { $set: data },
+   * { returnDocument: 'after', runValidators: true })` under the hood and
+   * routes through the
    * full plugin pipeline — `multiTenantPlugin` injects the tenant scope,
    * `auditTrailPlugin` records the change, `cachePlugin` invalidates,
    * `softDeletePlugin` etc. all compose. Returns `null` on miss (the
@@ -943,7 +963,7 @@ declare class Repository<TDoc = unknown> extends RepositoryBase {
    * const doc = await CampaignModel.findOneAndUpdate(
    *   { _id: id, organizationId: ctx.orgId },     // hand-rolled tenant filter
    *   { $set: patch, $currentDate: { updatedAt: 1 } },
-   *   { new: true, runValidators: true }
+   *   { returnDocument: 'after', runValidators: true }
    * );
    * return doc ? toEntity(doc) : null;
    *
@@ -972,7 +992,7 @@ declare class Repository<TDoc = unknown> extends RepositoryBase {
    * const doc = await CampaignModel.findOneAndUpdate(
    *   { _id: id, organizationId: ctx.orgId, status: 'pending' },
    *   { $set: { status: 'sent', sentAt: new Date() } },
-   *   { new: true }
+   *   { returnDocument: 'after' }
    * );
    * if (!doc) throw new ConcurrentTransitionError(id);
    *
@@ -1826,51 +1846,4 @@ declare class Repository<TDoc = unknown> extends RepositoryBase {
   _handleError(error: Error): HttpError;
 }
 //#endregion
-//#region src/create-repository.d.ts
-/**
- * Audit config — either a `Logger` (routes to `auditLogPlugin`, which
- * writes structured log lines through your logger) or an
- * `AuditTrailOptions` object (routes to `auditTrailPlugin`, which
- * persists a queryable compliance ledger in its own collection).
- *
- * Discrimination: a value carrying any of the `Logger` function members
- * (`info` / `warn` / `error` / `debug`) is treated as a logger; anything
- * else is treated as `AuditTrailOptions` (all of whose members are
- * data-shaped except `metadata` / `onError`, which don't overlap with
- * the logger member names).
- */
-type AuditConfig = Logger | AuditTrailOptions;
-/**
- * Declarative repository config. Every key is optional; a feature's
- * plugin is installed only when its key is present. The remaining
- * `RepositoryOptions` keys (`idField`, `hooks`, `schema`, `updateSchema`,
- * `events`, `requirePlugins`, ...) pass through to the `Repository`
- * constructor unchanged.
- */
-interface CreateRepositoryConfig extends RepositoryOptions {
-  /** Multi-tenant scoping — forwarded to `multiTenantPlugin`. */
-  tenant?: MultiTenantOptions;
-  /** Soft-delete — `true` for defaults, or `SoftDeleteOptions`. */
-  softDelete?: boolean | SoftDeleteOptions;
-  /** createdAt/updatedAt stamping — `timestampPlugin` takes no options. */
-  timestamps?: boolean;
-  /** Batch ops (`updateMany`/`deleteMany`/`bulkWrite`) via `batchOperationsPlugin`. */
-  batch?: boolean;
-  /** Read-through cache — forwarded to `cachePlugin`. */
-  cache?: RepositoryCachePluginOptions;
-  /** Audit — `Logger` → `auditLogPlugin`; `AuditTrailOptions` → `auditTrailPlugin`. */
-  audit?: AuditConfig;
-  /** Custom ID generation — forwarded to `customIdPlugin`. */
-  customId?: CustomIdOptions;
-  /** Extra plugins appended AFTER the canonical stack. */
-  plugins?: PluginType[];
-  /** Pagination engine config (defaultLimit, maxLimit, ...). */
-  pagination?: PaginationConfig;
-}
-/**
- * Build a `Repository` from a declarative config. See module JSDoc for
- * ordering guarantees and an example.
- */
-declare function createRepository<TDoc>(model: Model<TDoc, any, any, any>, config?: CreateRepositoryConfig): Repository<TDoc>;
-//#endregion
-export { Repository as a, HOOK_PRIORITY as i, CreateRepositoryConfig as n, TransitionMachine as o, createRepository as r, AggregationBuilder as s, AuditConfig as t };
+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 };