@classytic/mongokit 3.8.0 → 3.10.0

package/README.md

@@ -3,13 +3,22 @@
 [![npm version](https://badge.fury.io/js/@classytic%2Fmongokit.svg)](https://www.npmjs.com/package/@classytic/mongokit)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Production-grade MongoDB repository pattern for Node.js. Zero runtime deps, Mongoose as a peer.
+Production-grade MongoDB repository pattern for Node.js. Zero runtime deps — Mongoose and `@classytic/repo-core` are peers.
 
 ```bash
-npm install @classytic/mongokit mongoose
+npm install @classytic/mongokit @classytic/repo-core mongoose
 ```
 
-Requires Mongoose `>=9.4.1`, Node.js `>=22`.
+Requires Mongoose `>=9.4.1`, `@classytic/repo-core` `>=0.1.0`, Node.js `>=22`.
+
+> **Swap-able with sqlitekit.** Mongokit implements the `StandardRepo<TDoc>` contract from `@classytic/repo-core/repository`. Controller code written against the contract runs unchanged on [@classytic/sqlitekit](https://www.npmjs.com/package/@classytic/sqlitekit) — both kits share an identical conformance suite.
+
+### Miss semantics (MinimalRepo contract)
+
+- `getById(id)` → returns `null` on miss (not thrown). Invalid-shape ids (e.g. `'not-a-valid-id'` on an ObjectId `_id`) short-circuit to `null` rather than raising mongoose `CastError`.
+- `update(id, data)` → returns `null` on miss.
+- `delete(id)` → returns `{ success: false, message: 'Document not found' }` on miss.
+- Pass `{ throwOnNotFound: true }` to opt back into the legacy 404-throw behavior for any of the three.
 
 ---
 

package/dist/{PaginationEngine-C2_tAvAD.mjs → PaginationEngine-B93fLCcO.mjs}

@@ -1,5 +1,5 @@
 import { r as warn } from "./logger-DJ7egMnd.mjs";
-import { t as createError } from "./error-Lw9GEAro.mjs";
+import { t as createError } from "./error-CzYwrfUP.mjs";
 import { n as encodeCursor, r as resolveCursorFilter } from "./cursor-J84rR6wG.mjs";
 import { r as validateKeysetSort, t as getPrimaryField } from "./sort-CrZjTK25.mjs";
 //#region src/pagination/utils/index-hint.ts

package/dist/actions/index.d.mts

@@ -1,2 +1,2 @@
-import { a as create_d_exports, i as delete_d_exports, n as update_d_exports, o as aggregate_d_exports, r as read_d_exports } from "../index-DlSAFIc9.mjs";
+import { a as create_d_exports, i as delete_d_exports, n as update_d_exports, o as aggregate_d_exports, r as read_d_exports } from "../index-C7WmYP6F.mjs";
 export { aggregate_d_exports as aggregate, create_d_exports as create, delete_d_exports as deleteActions, read_d_exports as read, update_d_exports as update };

package/dist/actions/index.mjs

@@ -1,5 +1,5 @@
 import { t as __exportAll } from "../chunk-CfYAbeIz.mjs";
-import { g as create_exports, i as update_exports, p as delete_exports, u as read_exports, v as aggregate_exports } from "../update-yjSoNnWy.mjs";
+import { g as create_exports, i as update_exports, p as delete_exports, u as read_exports, v as aggregate_exports } from "../update-CWXfFC6O.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 { Y as Plugin } from "../types-D57SZJeE.mjs";
+import { K as Plugin } from "../types-BUS0Zj8y.mjs";
 import { ClientSession, PipelineStage } from "mongoose";
 
 //#region src/ai/types.d.ts

package/dist/{error-Lw9GEAro.mjs → error-CzYwrfUP.mjs}

@@ -17,6 +17,29 @@ function createError(status, message) {
 	return error;
 }
 /**
+* Boolean classifier: true when `err` is an authoritative MongoDB duplicate
+* key error — and ONLY then. Used by arc's outbox / idempotency adapters to
+* distinguish "write already landed (idempotent no-op)" from "transient DB
+* error (must retry)".
+*
+* Deliberately narrow — matches only:
+*   - `code === 11000`
+*   - `codeName === 'DuplicateKey'`
+*
+* Does NOT match `err.name === 'MongoServerError'`, which is also true for
+* WriteConflict (112), NotWritablePrimary (10107), ExceededTimeLimit, and
+* every other server-side error. Treating those as duplicate keys would
+* cause arc's outbox to silently swallow transactional retries and lose
+* events.
+*/
+function isDuplicateKeyError(err) {
+	if (!err || typeof err !== "object") return false;
+	const e = err;
+	if (e.code === 11e3 || e.codeName === "DuplicateKey") return true;
+	if (e.status === 409 && e.duplicate !== void 0) return true;
+	return false;
+}
+/**
 * Detect and convert a MongoDB E11000 duplicate-key error into
 * a 409 HttpError with an actionable message.
 *
@@ -29,9 +52,8 @@ function createError(status, message) {
 * Returns `null` when the error is not a duplicate-key error.
 */
 function parseDuplicateKeyError(error, options = {}) {
-	if (!error || typeof error !== "object") return null;
+	if (!isDuplicateKeyError(error)) return null;
 	const mongoErr = error;
-	if (mongoErr.code !== 11e3) return null;
 	const fields = mongoErr.keyPattern ? Object.keys(mongoErr.keyPattern) : [];
 	const exposed = options.exposeValues === true;
 	const valuesString = exposed && mongoErr.keyValue ? Object.entries(mongoErr.keyValue).map(([k, v]) => `${k}: ${JSON.stringify(v)}`).join(", ") : "";
@@ -43,4 +65,4 @@ function parseDuplicateKeyError(error, options = {}) {
 	return httpError;
 }
 //#endregion
-export { parseDuplicateKeyError as n, createError as t };
+export { isDuplicateKeyError as n, parseDuplicateKeyError as r, createError as t };

package/dist/{index-DlSAFIc9.d.mts → index-C7WmYP6F.d.mts}

@@ -1,4 +1,4 @@
-import { B as MinMaxResult, D as FindOneAndUpdateOptions, G as OperationOptions, H as ObjectId, O as GroupResult, Q as PopulateSpec, _t as UpdateManyResult, a as AnyDocument, b as DeleteResult, ct as SelectSpec, et as ReadPreferenceType, g as CreateOptions, jt as LookupOptions, mt as SortSpec, vt as UpdateOptions, yt as UpdateWithValidationResult } from "./types-D57SZJeE.mjs";
+import { Dt as LookupOptions, E as GroupResult, H as OperationOptions, L as MinMaxResult, Q as ReadPreferenceType, T as FindOneAndUpdateOptions, Y as PopulateSpec, a as AnyDocument, at as SelectSpec, dt as SortSpec, g as CreateOptions, gt as UpdateWithValidationResult, ht as UpdateOptions, mt as UpdateManyResult, y as DeleteResult, z as ObjectId } from "./types-BUS0Zj8y.mjs";
 import { ClientSession, Model, PipelineStage } from "mongoose";
 
 //#region src/actions/aggregate.d.ts
@@ -218,7 +218,7 @@ declare namespace update_d_exports {
 /**
  * Update by ID
  */
-declare function update<TDoc = AnyDocument>(Model: Model<TDoc>, id: string | ObjectId, data: Record<string, unknown>, options?: UpdateOptions): Promise<TDoc>;
+declare function update<TDoc = AnyDocument>(Model: Model<TDoc>, id: string | ObjectId, data: Record<string, unknown>, options?: UpdateOptions): Promise<TDoc | null>;
 /**
  * Update with query constraints (optimized)
  * Returns null if constraints not met (not an error)
@@ -266,15 +266,15 @@ declare function findOneAndUpdate<TDoc = AnyDocument>(Model: Model<TDoc>, filter
 /**
  * Increment field
  */
-declare function increment<TDoc = AnyDocument>(Model: Model<TDoc>, id: string | ObjectId, field: string, value?: number, options?: UpdateOptions): Promise<TDoc>;
+declare function increment<TDoc = AnyDocument>(Model: Model<TDoc>, id: string | ObjectId, field: string, value?: number, options?: UpdateOptions): Promise<TDoc | null>;
 /**
  * Push to array
  */
-declare function pushToArray<TDoc = AnyDocument>(Model: Model<TDoc>, id: string | ObjectId, field: string, value: unknown, options?: UpdateOptions): Promise<TDoc>;
+declare function pushToArray<TDoc = AnyDocument>(Model: Model<TDoc>, id: string | ObjectId, field: string, value: unknown, options?: UpdateOptions): Promise<TDoc | null>;
 /**
  * Pull from array
  */
-declare function pullFromArray<TDoc = AnyDocument>(Model: Model<TDoc>, id: string | ObjectId, field: string, value: unknown, options?: UpdateOptions): Promise<TDoc>;
+declare function pullFromArray<TDoc = AnyDocument>(Model: Model<TDoc>, id: string | ObjectId, field: string, value: unknown, options?: UpdateOptions): Promise<TDoc | null>;
 declare namespace index_d_exports {
   export { aggregate_d_exports as aggregate, create_d_exports as create, delete_d_exports as deleteActions, read_d_exports as read, update_d_exports as update };
 }

package/dist/index.d.mts

@@ -1,12 +1,14 @@
-import { $ as ReadOptions, A as HttpError, At as LookupBuilder, B as MinMaxResult, C as EventPayload, Ct as ValidatorDefinition, D as FindOneAndUpdateOptions, Dt as IControllerResponse, E as FieldRules, Et as IController, F as KeysetPaginationOptions, G as OperationOptions, H as ObjectId, I as KeysetPaginationResult, J as PartialBy, K as PaginationConfig, L as Logger, M as InferRawDoc, N as JsonSchema, O as GroupResult, Ot as IRequestContext, P as KeysOfType, Q as PopulateSpec, R as LookupPopulateOptions, S as EventHandlers, St as ValidationResult, T as FieldPreset, Tt as WithTransactionOptions, U as OffsetPaginationOptions, V as NonNullableFields, W as OffsetPaginationResult, X as PluginFunction, Y as Plugin, Z as PluginType, _ as CrudSchemas, _t as UpdateManyResult, a as AnyDocument, at as RepositoryOptions, b as DeleteResult, bt as UserContext, c as CacheOperationOptions, ct as SelectSpec, d as CacheableOptions, dt as SoftDeleteOptions, et as ReadPreferenceType, f as CascadeOptions, ft as SoftDeleteRepository, g as CreateOptions, gt as UpdateInput, h as CreateInput, ht as Strict, i as AllPluginMethods, it as RepositoryOperation, j as InferDocument, jt as LookupOptions, k as HookMode, kt as IResponseFormatter, l as CacheOptions, lt as SessionOptions, m as CollationOptions, mt as SortSpec, n as AggregatePaginationOptions, nt as RepositoryEvent, o as AnyModel, ot as RequiredBy, p as CascadeRelation, pt as SortDirection, q as PaginationResult, r as AggregatePaginationResult, rt as RepositoryInstance, s as CacheAdapter, st as SchemaBuilderOptions, t as AggregateOptions, tt as RepositoryContext, u as CacheStats, ut as SoftDeleteFilterMode, v as DecodedCursor, vt as UpdateOptions, w as EventPhase, wt as WithPlugins, x as DocField, xt as ValidationChainOptions, y as DeepPartial, yt as UpdateWithValidationResult, z as LookupPopulateResult } from "./types-D57SZJeE.mjs";
-import { t as index_d_exports } from "./index-DlSAFIc9.mjs";
+import { $ as RepositoryContext, A as InferRawDoc, B as OffsetPaginationOptions, C as EventPhase, Ct as IControllerResponse, D as HookMode, Dt as LookupOptions, E as GroupResult, Et as LookupBuilder, F as LookupPopulateOptions, G as PartialBy, H as OperationOptions, I as LookupPopulateResult, J as PluginType, K as Plugin, L as MinMaxResult, M as KeysetPaginationOptions, N as KeysetPaginationResult, O as HttpError, P as Logger, Q as ReadPreferenceType, R as NonNullableFields, S as EventPayload, St as IController, T as FindOneAndUpdateOptions, Tt as IResponseFormatter, U as PaginationConfig, V as OffsetPaginationResult, W as PaginationResult, X as PrioritizedHook, Y as PopulateSpec, Z as ReadOptions, _ as DecodedCursor, _t as UserContext, a as AnyDocument, at as SelectSpec, b as DocField, bt as WithPlugins, c as CacheOperationOptions, ct as SoftDeleteOptions, d as CacheableOptions, dt as SortSpec, et as RepositoryEvent, f as CascadeOptions, ft as Strict, g as CreateOptions, gt as UpdateWithValidationResult, h as CreateInput, ht as UpdateOptions, i as AllPluginMethods, it as RequiredBy, j as KeysOfType, k as InferDocument, l as CacheOptions, lt as SoftDeleteRepository, m as CollationOptions, mt as UpdateManyResult, n as AggregatePaginationOptions, nt as RepositoryOperation, o as AnyModel, ot as SessionOptions, p as CascadeRelation, pt as UpdateInput, q as PluginFunction, r as AggregatePaginationResult, rt as RepositoryOptions, s as CacheAdapter, st as SoftDeleteFilterMode, t as AggregateOptions, tt as RepositoryInstance, u as CacheStats, ut as SortDirection, v as DeepPartial, vt as ValidationChainOptions, w as FieldPreset, wt as IRequestContext, x as EventHandlers, xt as WithTransactionOptions, y as DeleteResult, yt as ValidatorDefinition, z as ObjectId } from "./types-BUS0Zj8y.mjs";
+import { t as index_d_exports } from "./index-C7WmYP6F.mjs";
 import { PaginationEngine } from "./pagination/PaginationEngine.mjs";
-import { $ as aggregateHelpersPlugin, A as PrefixedIdOptions, B as BatchOperationsMethods, C as methodRegistryPlugin, D as CustomIdOptions, E as elasticSearchPlugin, F as prefixedId, G as AuditQueryOptions, H as batchOperationsPlugin, I as sequentialId, J as AuditTrailOptions, K as AuditQueryResult, L as cascadePlugin, M as customIdPlugin, N as dateSequentialId, O as DateSequentialIdOptions, P as getNextSequence, Q as AggregateHelpersMethods, R as CacheMethods, T as ElasticSearchOptions, U as AuditEntry, V as BulkWriteResult, W as AuditOperation, X as auditTrailPlugin, Y as AuditTrailQuery, Z as auditLogPlugin, _ as observabilityPlugin, a as uniqueField, b as MongoOperationsMethods, c as TenantContext, d as SubdocumentMethods, f as subdocumentPlugin, g as OperationMetric, h as ObservabilityOptions, i as requireField, j as SequentialIdOptions, k as IdGenerator, l as TenantStore, m as softDeletePlugin, n as blockIf, o as validationChainPlugin, p as SoftDeleteMethods, q as AuditTrailMethods, r as immutableField, s as timestampPlugin, t as autoInject, u as createTenantContext, v as MultiTenantOptions, w as fieldFilterPlugin, x as mongoOperationsPlugin, y as multiTenantPlugin, z as cachePlugin } from "./validation-chain.plugin-wGF34Ym-.mjs";
+import { $ as aggregateHelpersPlugin, A as PrefixedIdOptions, B as BatchOperationsMethods, C as methodRegistryPlugin, D as CustomIdOptions, E as elasticSearchPlugin, F as prefixedId, G as AuditQueryOptions, H as batchOperationsPlugin, I as sequentialId, J as AuditTrailOptions, K as AuditQueryResult, L as cascadePlugin, M as customIdPlugin, N as dateSequentialId, O as DateSequentialIdOptions, P as getNextSequence, Q as AggregateHelpersMethods, R as CacheMethods, T as ElasticSearchOptions, U as AuditEntry, V as BulkWriteResult, W as AuditOperation, X as auditTrailPlugin, Y as AuditTrailQuery, Z as auditLogPlugin, _ as observabilityPlugin, a as uniqueField, b as MongoOperationsMethods, c as TenantContext, d as SubdocumentMethods, f as subdocumentPlugin, g as OperationMetric, h as ObservabilityOptions, i as requireField, j as SequentialIdOptions, k as IdGenerator, l as TenantStore, m as softDeletePlugin, n as blockIf, o as validationChainPlugin, p as SoftDeleteMethods, q as AuditTrailMethods, r as immutableField, s as timestampPlugin, t as autoInject, u as createTenantContext, v as MultiTenantOptions, w as fieldFilterPlugin, x as mongoOperationsPlugin, y as multiTenantPlugin, z as cachePlugin } from "./validation-chain.plugin-JkipjuOR.mjs";
 import { n as SchemaPathsLike, t as FieldType$1 } from "./coercion-oM8G4b6m.mjs";
 import { n as SchemaIndexes } from "./indexes-C26GNZRU.mjs";
-import { a as isFieldUpdateAllowed, c as configureLogger, d as getFieldsForUser, f as getMongooseProjection, i as getSystemManagedFields, l as createFieldPreset, m as parseDuplicateKeyError, n as buildCrudSchemasFromMongooseSchema, o as validateUpdateBody, p as createError, r as getImmutableFields, s as createMemoryCache, t as buildCrudSchemasFromModel, u as filterResponseData } from "./mongooseToJsonSchema-BZaKOXXI.mjs";
+import { a as createFieldPreset, c as getMongooseProjection, d as parseDuplicateKeyError, i as configureLogger, l as createError, n as buildCrudSchemasFromMongooseSchema, o as filterResponseData, r as createMemoryCache, s as getFieldsForUser, t as buildCrudSchemasFromModel, u as isDuplicateKeyError } from "./mongooseToJsonSchema-t-MoVleF.mjs";
 import * as _$mongoose from "mongoose";
 import { ClientSession, Expression, Model, PipelineStage, PopulateOptions } from "mongoose";
+import { AggPaginationRequest, AggRequest, AggResult, RepositoryBase } from "@classytic/repo-core/repository";
+import { OffsetPaginationResultCore } from "@classytic/repo-core/pagination";
 
 //#region src/operations.d.ts
 /**
@@ -865,33 +867,43 @@ declare class QueryParser {
 }
 //#endregion
 //#region src/Repository.d.ts
-type HookListener = (data: any) => void | Promise<void>;
-/** Hook with priority for phase ordering */
-interface PrioritizedHook {
-  listener: HookListener;
-  priority: number;
-}
 /**
- * Plugin phase priorities (lower = runs first)
- * Policy hooks (multi-tenant, soft-delete, validation) MUST run before cache
- * to ensure filters are injected before cache keys are computed.
+ * Plugin phase priorities (lower = runs first).
+ *
+ * Re-exported from `@classytic/repo-core/hooks` so mongokit 3.10 callers see
+ * the same constant whether they import from mongokit or directly from
+ * repo-core — priorities are identical (POLICY=100, CACHE=200,
+ * OBSERVABILITY=300, DEFAULT=500) and the two refs are reference-equal.
  */
 declare const HOOK_PRIORITY: {
-  /** Policy enforcement: tenant isolation, soft-delete filtering, validation */readonly POLICY: 100; /** Caching: lookup/store after policy filters are applied */
-  readonly CACHE: 200; /** Observability: audit logging, metrics, telemetry */
-  readonly OBSERVABILITY: 300; /** Default priority for user-registered hooks */
+  readonly POLICY: 100;
+  readonly CACHE: 200;
+  readonly OBSERVABILITY: 300;
   readonly DEFAULT: 500;
 };
 /**
- * Production-grade repository for MongoDB
- * Event-driven, plugin-based, with smart pagination
+ * Production-grade repository for MongoDB.
+ *
+ * Extends `@classytic/repo-core/repository`'s `RepositoryBase` for the
+ * driver-agnostic hook + plugin plumbing (context builder, priority-sorted
+ * event engine, plugin-order validator) while layering every Mongo-specific
+ * concern — populate, aggregate, lookup, keyset + cursor pagination, $near
+ * rewriting — on top.
+ *
+ * Public surface is byte-stable with mongokit 3.9 (the `_hooks` property is
+ * preserved as a live read-through getter; all CRUD, event, and plugin method
+ * signatures unchanged). 3.10 is an internal re-plumbing release; consumers
+ * upgrading from 3.9 need no code changes.
  */
-declare class Repository<TDoc = unknown> {
+declare class Repository<TDoc = unknown> extends RepositoryBase {
   readonly Model: Model<TDoc>;
+  /**
+   * Mongoose model name. Duplicated on the instance for BC — arc / catalog /
+   * user code read `repo.model`. `RepositoryBase.modelName` points to the
+   * same string; prefer `modelName` in new code.
+   */
   readonly model: string;
-  readonly _hooks: Map<string, PrioritizedHook[]>;
   readonly _pagination: PaginationEngine<TDoc>;
-  private readonly _hookMode;
   readonly idField: string;
   readonly searchMode: 'text' | 'regex' | 'auto';
   readonly searchFields: string[] | undefined;
@@ -899,37 +911,22 @@ declare class Repository<TDoc = unknown> {
   private _hasTextIndex;
   constructor(Model: Model<TDoc, any, any, any>, plugins?: PluginType[], paginationConfig?: PaginationConfig, options?: RepositoryOptions);
   /**
-   * Register a plugin
-   */
-  use(plugin: PluginType): this;
-  /**
-   * Register event listener with optional priority for phase ordering.
+   * Live read-through view of the hook engine's listener registry.
    *
-   * @param event - Event name (e.g. 'before:getAll')
-   * @param listener - Hook function
-   * @param options - Optional { priority } — use HOOK_PRIORITY constants.
-   *                  Lower priority numbers run first.
-   *                  Default: HOOK_PRIORITY.DEFAULT (500)
-   */
-  on(event: RepositoryEvent | (string & {}), listener: HookListener, options?: {
-    priority?: number;
-  }): this;
-  /**
-   * Remove a specific event listener
-   */
-  off(event: RepositoryEvent | (string & {}), listener: HookListener): this;
-  /**
-   * Remove all listeners for an event, or all listeners entirely
-   */
-  removeAllListeners(event?: string): this;
-  /**
-   * Emit event (sync - for backwards compatibility)
+   * Preserved as a public field on the Repository for back-compat with
+   * mongokit ≤3.9 — existing tests and observability code pattern-match
+   * `repo._hooks.get('before:getAll')` / `repo._hooks.size`. Each access
+   * returns a fresh snapshot of the underlying HookEngine state.
+   *
+   * Read-only. To register listeners use `repo.on(event, listener, { priority })`.
    */
-  emit(event: string, data: unknown): void;
+  get _hooks(): Map<string, PrioritizedHook[]>;
   /**
-   * Emit event and await all async handlers (sorted by priority)
+   * Fire-and-forget emit aliased through RepositoryBase's async path so
+   * error hooks converted to/from sync mode still route uniformly. Mongokit
+   * ≤3.9 made this a private method on its subclass; the base class exposes
+   * it publicly and wraps it in `_emitHook` below for internal use.
    */
-  emitAsync(event: string, data: unknown): Promise<void>;
   private _emitHook;
   private _emitErrorHook;
   /**
@@ -1033,7 +1030,7 @@ declare class Repository<TDoc = unknown> {
   /**
    * Update document by ID
    */
-  update(id: string | ObjectId, data: Record<string, unknown>, options?: UpdateOptions): Promise<TDoc>;
+  update(id: string | ObjectId, data: Record<string, unknown>, options?: UpdateOptions): Promise<TDoc | null>;
   /**
    * Atomic findOneAndUpdate (compare-and-set primitive).
    *
@@ -1087,24 +1084,86 @@ declare class Repository<TDoc = unknown> {
    */
   delete(id: string | ObjectId, options?: SessionOptions & {
     idField?: string;
-    mode?: 'hard' | 'soft';
+    mode?: 'hard' | 'soft'; /** Legacy opt-in: throw a 404 error on miss instead of returning `{ success: false }`. */
+    throwOnNotFound?: boolean;
   }): Promise<DeleteResult>;
   /**
-   * Execute aggregation pipeline
-   * Routes through hook system for policy enforcement (multi-tenant, soft-delete)
+   * Kit-native aggregation pipeline — takes a MongoDB stage array and
+   * returns the raw pipeline output. Use this for `$lookup`, `$unwind`,
+   * `$facet`, `$graphLookup`, and any other mongo-specific power
+   * features that don't translate to SQL.
    *
-   * @param pipeline - Aggregation pipeline stages
-   * @param options - Aggregation options including governance controls
+   * For backend-portable aggregations (filter + group + measures +
+   * sort + limit) use `aggregate(req: AggRequest)` instead — it
+   * compiles the repo-core IR to the equivalent pipeline internally
+   * and produces the same row shape sqlitekit emits.
+   *
+   * Routes through the hook system for policy enforcement
+   * (multi-tenant, soft-delete).
+   *
+   * @param pipeline - MongoDB aggregation stage array
+   * @param options  - Aggregation options including governance controls
    */
-  aggregate<TResult = unknown>(pipeline: PipelineStage[], options?: AggregateOptions): Promise<TResult[]>;
+  aggregatePipeline<TResult = unknown>(pipeline: PipelineStage[], options?: AggregateOptions): Promise<TResult[]>;
   /**
-   * Aggregate pipeline with pagination
-   * Best for: Complex queries, grouping, joins
+   * Paginated kit-native aggregation pipeline. Same mongo-specific
+   * scope as `aggregatePipeline` — reach for this when you need
+   * `$lookup` / `$unwind` / `$facet` alongside pagination.
+   *
+   * Prefer `aggregatePaginate(req: AggPaginationRequest)` for
+   * cross-backend dashboard code; that method compiles the portable
+   * IR to an equivalent pipeline.
    *
-   * Policy hooks (multi-tenant, soft-delete) inject context.filters which are
-   * prepended as a $match stage to the pipeline, ensuring tenant isolation.
+   * Policy hooks (multi-tenant, soft-delete) inject context.filters
+   * which are prepended as a `$match` stage.
    */
-  aggregatePaginate(options?: AggregatePaginationOptions): Promise<AggregatePaginationResult<TDoc>>;
+  aggregatePipelinePaginate(options?: AggregatePaginationOptions): Promise<AggregatePaginationResult<TDoc>>;
+  /**
+   * Portable aggregation. Compiles the repo-core `AggRequest` IR to
+   * `[{$match}, {$group}, {$addFields}, {$project}, {$match}, {$sort},
+   * {$skip}, {$limit}]` against this repo's collection. Output rows
+   * carry one key per `groupBy` column plus one key per measure alias
+   * — identical shape to sqlitekit's `aggregate(req)`, so dashboards
+   * work unchanged across backends.
+   *
+   * Without `groupBy`: returns a single-row result with just the
+   * measures (scalar aggregation). Pass
+   * `{ measures: { total: { op: 'sum', field: 'amount' } } }` for a
+   * simple summary.
+   *
+   * For mongo-specific power features (`$lookup`, `$unwind`, `$facet`,
+   * `$graphLookup`, window operators) reach for `aggregatePipeline`
+   * — that's the kit-native escape hatch.
+   *
+   * Routes through the hook system for policy enforcement
+   * (multi-tenant, soft-delete) — plugins inject their scope into
+   * `context.filter`, which is merged into the pre-aggregate `$match`
+   * before compilation.
+   */
+  aggregate<TRow extends Record<string, unknown> = Record<string, unknown>>(req: AggRequest): Promise<AggResult<TRow>>;
+  /**
+   * Offset-paginated portable aggregation. Same IR as `aggregate`,
+   * wrapped in the standard `OffsetPaginationResultCore` envelope so
+   * UI code paginates aggregated dashboards with the same primitives
+   * as raw document lists.
+   *
+   * `countStrategy: 'none'` skips the second round-trip that computes
+   * `total`; the envelope reports `total: 0`, `pages: 0`, and derives
+   * `hasNext` from a `LIMIT N+1` peek on the data pipeline.
+   */
+  aggregatePaginate<TRow extends Record<string, unknown> = Record<string, unknown>>(req: AggPaginationRequest): Promise<OffsetPaginationResultCore<TRow>>;
+  /**
+   * Merge policy-hook-injected filters (multi-tenant scope,
+   * soft-delete) into the pre-aggregate `filter` slot of the request.
+   * Plugins speak mongo-query shape (`context.query` / `context.filters`);
+   * we merge those with the portable `req.filter` using `$and`.
+   *
+   * When the caller's filter is a Filter IR node we don't unwrap it —
+   * the pipeline compiler does Filter→mongo translation. Merging here
+   * as a mongo-shaped `$and` is safe because `compileFilterToMongo`
+   * passes through already-mongo queries unchanged.
+   */
+  private _injectPolicyScopeIntoAgg;
   /**
    * Get distinct values
    * Routes through hook system for policy enforcement (multi-tenant, soft-delete)
@@ -1173,42 +1232,66 @@ declare class Repository<TDoc = unknown> {
    */
   buildLookup(from?: string): LookupBuilder;
   /**
-   * Execute callback within a transaction with automatic retry on transient failures.
+   * Execute callback within a MongoDB transaction with automatic retry on
+   * transient failures.
    *
-   * Uses the MongoDB driver's `session.withTransaction()` which automatically retries
-   * on `TransientTransactionError` and `UnknownTransactionCommitResult`.
+   * **BREAKING (3.10):** the callback now receives a **tx-bound repository**,
+   * not a raw `ClientSession`. This matches repo-core's `StandardRepo.withTransaction`
+   * contract that every kit (sqlitekit, pgkit, prismakit) already implements
+   * — so cross-kit plugins and apps are portable. Session threading happens
+   * transparently: every CRUD call on `txRepo` auto-injects the session into
+   * its options bag, including plugin-added methods (`upsert`, `increment`,
+   * `updateMany`, `restore`, ...). Nested `txRepo.withTransaction(...)` throws.
    *
-   * The callback always receives a `ClientSession`. When `allowFallback` is true
-   * and the MongoDB deployment doesn't support transactions (e.g., standalone),
-   * the callback runs without a transaction on the same session.
+   * For raw-session cross-repo workflows — multiple repositories coordinating
+   * writes — use the standalone `withTransaction(connection, fn)` export
+   * from `@classytic/mongokit`. That helper remains session-based by design.
    *
-   * @param callback - Receives a `ClientSession` to pass to repository operations
+   * @param callback - Receives a tx-bound `Repository<TDoc>` — call its
+   *                   methods directly, no need to pass `{ session }` manually
    * @param options.allowFallback - Run without transaction on standalone MongoDB (default: false)
    * @param options.onFallback - Called when falling back to non-transactional execution
    * @param options.transactionOptions - MongoDB driver transaction options (readConcern, writeConcern, etc.)
    *
    * @example
    * ```typescript
-   * const result = await repo.withTransaction(async (session) => {
-   *   const order = await repo.create({ total: 100 }, { session });
-   *   await paymentRepo.create({ orderId: order._id }, { session });
-   *   return order;
+   * const order = await repo.withTransaction(async (txRepo) => {
+   *   const created = await txRepo.create({ total: 100 });
+   *   await txRepo.update(created._id, { confirmed: true });
+   *   return created;
    * });
    *
    * // With fallback for standalone/dev environments
-   * await repo.withTransaction(callback, {
-   *   allowFallback: true,
-   *   onFallback: (err) => logger.warn('Running without transaction', err),
+   * await repo.withTransaction(
+   *   async (txRepo) => {
+   *     await txRepo.create(doc);
+   *   },
+   *   {
+   *     allowFallback: true,
+   *     onFallback: (err) => logger.warn('Running without transaction', err),
+   *   },
+   * );
+   *
+   * // Cross-repo with explicit session:
+   * import { withTransaction } from '@classytic/mongokit';
+   * await withTransaction(mongoose.connection, async (session) => {
+   *   const order = await orderRepo.create(data, { session });
+   *   await inventoryRepo.decrement(..., { session });
    * });
    * ```
    */
-  withTransaction<T>(callback: (session: ClientSession) => Promise<T>, options?: WithTransactionOptions): Promise<T>;
+  withTransaction<T>(callback: (txRepo: this) => Promise<T>, options?: WithTransactionOptions): Promise<T>;
   /**
    * Execute custom query with event emission
    */
   _executeQuery<T>(buildQuery: (Model: Model<TDoc>) => Promise<T>): Promise<T>;
   /**
-   * Build operation context and run before hooks (sorted by priority).
+   * Build operation context and run before-hooks (sorted by priority).
+   *
+   * Narrows `RepositoryBase._buildContext`'s return type to mongokit's
+   * richer `RepositoryContext` (which carries `softDeleted`, `_cacheHit`,
+   * populate / readPreference / session, etc.). Runtime is inherited from
+   * the base class — this override is purely a type-narrowing shim.
    *
    * Hook execution order is deterministic:
    * 1. POLICY (100) — tenant isolation, soft-delete filtering, validation
@@ -1217,6 +1300,13 @@ declare class Repository<TDoc = unknown> {
    * 4. DEFAULT (500) — user-registered hooks
    */
   _buildContext(operation: string, options: Record<string, unknown> | object): Promise<RepositoryContext>;
+  /**
+   * Walk the well-known filter-carrying keys (`query`, `filters`,
+   * `having`) and route any Filter IR through `compileFilterToMongo`.
+   * Plain Mongo queries pass through untouched — `isFilter` is the
+   * discriminator. Returns a shallow clone; never mutates input.
+   */
+  private _normalizeFilterSlots;
   /**
    * Resolve the effective sort for getAll. Handles $near conflict detection
    * (warns + drops explicit sort when $near is in filters).
@@ -1240,6 +1330,36 @@ declare class Repository<TDoc = unknown> {
    * Parse populate specification
    */
   _parsePopulate(populate: PopulateSpec | undefined): string[] | PopulateOptions[];
+  /**
+   * Classify a driver error as an authoritative duplicate-key conflict.
+   *
+   * Used by arc's outbox / idempotency adapters to distinguish
+   * "write already landed (idempotent no-op)" from "transient DB error
+   * (must retry)". Every backend signals duplicate keys differently —
+   * MongoDB `code: 11000`, Prisma `P2002`, Postgres `23505` — so this
+   * predicate lives on the kit that knows its driver. Cross-driver
+   * adapters then depend only on the boolean outcome, not the shape of
+   * the underlying error.
+   *
+   * Deliberately narrow: matches ONLY `code === 11000` and
+   * `codeName === 'DuplicateKey'`. Does NOT match
+   * `err.name === 'MongoServerError'`, which is also true for
+   * WriteConflict, NotWritablePrimary, ExceededTimeLimit, and every
+   * other server-side error — treating those as duplicate keys would
+   * silently swallow transactional retries.
+   *
+   * @example
+   * try {
+   *   await outboxRepo.create(event);
+   * } catch (err) {
+   *   if (outboxRepo.isDuplicateKeyError(err)) {
+   *     // Idempotent no-op — event was already written by a prior attempt.
+   *     return;
+   *   }
+   *   throw err; // transient DB error — upstream retries
+   * }
+   */
+  isDuplicateKeyError(err: unknown): boolean;
   /**
    * Handle errors with proper HTTP status codes
    */
@@ -1298,4 +1418,4 @@ declare function isTransactionUnsupported(error: Error): boolean;
  */
 declare function createRepository<TDoc>(Model: _$mongoose.Model<TDoc, any, any, any>, plugins?: PluginType[], paginationConfig?: PaginationConfig, options?: RepositoryOptions): Repository<TDoc>;
 //#endregion
-export { ALL_OPERATIONS, type AggregateHelpersMethods, type AggregateOptions, type AggregatePaginationOptions, type AggregatePaginationResult, AggregationBuilder, type AllPluginMethods, type AnyDocument, type AnyModel, type AuditEntry, type AuditOperation, type AuditQueryOptions, type AuditQueryResult, type AuditTrailMethods, type AuditTrailOptions, AuditTrailQuery, type BatchOperationsMethods, type BulkWriteResult, type CacheAdapter, type CacheMethods, type CacheOperationOptions, type CacheOptions, type CacheStats, type CacheableOptions, type CascadeOptions, type CascadeRelation, type CollationOptions, type CreateInput, type CreateOptions, type CrudSchemas, type CustomIdOptions, type DateSequentialIdOptions, type DecodedCursor, type DeepPartial, type DeleteResult, type DocField, type ElasticSearchOptions, type EventHandlers, type EventPayload, type EventPhase, type FieldPreset, type FieldRules, type FieldType, type FilterQuery, type FindOneAndUpdateOptions, type GroupResult, HOOK_PRIORITY, type HookMode, type HttpError, type IController, type IControllerResponse, type IRequestContext, type IResponseFormatter, type IdGenerator, type InferDocument, type InferRawDoc, type JsonSchema, type KeysOfType, type KeysetPaginationOptions, type KeysetPaginationResult, type Logger, LookupBuilder, type LookupOptions, type LookupPopulateOptions, type LookupPopulateResult, MUTATING_OPERATIONS, type MinMaxResult, type MongoOperationsMethods, type MultiTenantOptions, type NonNullableFields, OP_REGISTRY, type ObjectId, type ObservabilityOptions, type OffsetPaginationOptions, type OffsetPaginationResult, type OperationDescriptor, type OperationMetric, type OperationOptions, type PaginationConfig, PaginationEngine, type PaginationResult, type ParsedQuery, type PartialBy, type Plugin, type PluginFunction, type PluginType, type PolicyKey, type PopulateOption, type PopulateSpec, type PrefixedIdOptions, QueryParser, type QueryParserOptions, READ_OPERATIONS, type ReadOptions, type ReadPreferenceType, Repository, Repository as default, type RepositoryContext, type RepositoryEvent, type RepositoryInstance, type RepositoryOperation, type RepositoryOptions, type RequiredBy, type SchemaBuilderOptions, type SchemaLike, type SearchMode, type SelectSpec, type SequentialIdOptions, type SessionOptions, type SoftDeleteFilterMode, type SoftDeleteMethods, type SoftDeleteOptions, type SoftDeleteRepository, type SortDirection, type SortSpec, type Strict, type SubdocumentMethods, type TenantContext, type TenantStore, type UpdateInput, type UpdateManyResult, type UpdateOptions, type UpdateWithValidationResult, type UserContext, type ValidationChainOptions, type ValidationResult, type ValidatorDefinition, type WithPlugins, type WithTransactionOptions, index_d_exports as actions, aggregateHelpersPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, blockIf, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, cachePlugin, cascadePlugin, configureLogger, createError, createFieldPreset, createMemoryCache, createRepository, createTenantContext, customIdPlugin, dateSequentialId, elasticSearchPlugin, fieldFilterPlugin, filterResponseData, getFieldsForUser, getImmutableFields, getMongooseProjection, getNextSequence, getSystemManagedFields, immutableField, isFieldUpdateAllowed, isTransactionUnsupported, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, operationsByPolicyKey, parseDuplicateKeyError, prefixedId, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validateUpdateBody, validationChainPlugin, withTransaction };
+export { ALL_OPERATIONS, type AggregateHelpersMethods, type AggregateOptions, type AggregatePaginationOptions, type AggregatePaginationResult, AggregationBuilder, type AllPluginMethods, type AnyDocument, type AnyModel, type AuditEntry, type AuditOperation, type AuditQueryOptions, type AuditQueryResult, type AuditTrailMethods, type AuditTrailOptions, AuditTrailQuery, type BatchOperationsMethods, type BulkWriteResult, type CacheAdapter, type CacheMethods, type CacheOperationOptions, type CacheOptions, type CacheStats, type CacheableOptions, type CascadeOptions, type CascadeRelation, type CollationOptions, type CreateInput, type CreateOptions, type CustomIdOptions, type DateSequentialIdOptions, type DecodedCursor, type DeepPartial, type DeleteResult, type DocField, type ElasticSearchOptions, type EventHandlers, type EventPayload, type EventPhase, type FieldPreset, type FieldType, type FilterQuery, type FindOneAndUpdateOptions, type GroupResult, HOOK_PRIORITY, type HookMode, type HttpError, type IController, type IControllerResponse, type IRequestContext, type IResponseFormatter, type IdGenerator, type InferDocument, type InferRawDoc, type KeysOfType, type KeysetPaginationOptions, type KeysetPaginationResult, type Logger, LookupBuilder, type LookupOptions, type LookupPopulateOptions, type LookupPopulateResult, MUTATING_OPERATIONS, type MinMaxResult, type MongoOperationsMethods, type MultiTenantOptions, type NonNullableFields, OP_REGISTRY, type ObjectId, type ObservabilityOptions, type OffsetPaginationOptions, type OffsetPaginationResult, type OperationDescriptor, type OperationMetric, type OperationOptions, type PaginationConfig, PaginationEngine, type PaginationResult, type ParsedQuery, type PartialBy, type Plugin, type PluginFunction, type PluginType, type PolicyKey, type PopulateOption, type PopulateSpec, type PrefixedIdOptions, QueryParser, type QueryParserOptions, READ_OPERATIONS, type ReadOptions, type ReadPreferenceType, Repository, Repository as default, type RepositoryContext, type RepositoryEvent, type RepositoryInstance, type RepositoryOperation, type RepositoryOptions, type RequiredBy, type SchemaLike, type SearchMode, type SelectSpec, type SequentialIdOptions, type SessionOptions, type SoftDeleteFilterMode, type SoftDeleteMethods, type SoftDeleteOptions, type SoftDeleteRepository, type SortDirection, type SortSpec, type Strict, type SubdocumentMethods, type TenantContext, type TenantStore, type UpdateInput, type UpdateManyResult, type UpdateOptions, type UpdateWithValidationResult, type UserContext, type ValidationChainOptions, type ValidatorDefinition, type WithPlugins, type WithTransactionOptions, index_d_exports as actions, aggregateHelpersPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, blockIf, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, cachePlugin, cascadePlugin, configureLogger, createError, createFieldPreset, createMemoryCache, createRepository, createTenantContext, customIdPlugin, dateSequentialId, elasticSearchPlugin, fieldFilterPlugin, filterResponseData, getFieldsForUser, getMongooseProjection, getNextSequence, immutableField, isDuplicateKeyError, isTransactionUnsupported, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, operationsByPolicyKey, parseDuplicateKeyError, prefixedId, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validationChainPlugin, withTransaction };

package/dist/index.mjs

@@ -1,14 +1,14 @@
 import { r as warn, t as configureLogger } from "./logger-DJ7egMnd.mjs";
-import { b as LookupBuilder } from "./update-yjSoNnWy.mjs";
-import { n as parseDuplicateKeyError, t as createError } from "./error-Lw9GEAro.mjs";
+import { b as LookupBuilder } from "./update-CWXfFC6O.mjs";
+import { n as isDuplicateKeyError, r as parseDuplicateKeyError, t as createError } from "./error-CzYwrfUP.mjs";
 import { t as actions_exports } from "./actions/index.mjs";
-import { A as AuditTrailQuery, C as cachePlugin, D as withTransaction, E as isTransactionUnsupported, F as MUTATING_OPERATIONS, I as OP_REGISTRY, L as READ_OPERATIONS, M as auditLogPlugin, N as aggregateHelpersPlugin, O as AggregationBuilder, P as ALL_OPERATIONS, R as operationsByPolicyKey, S as cascadePlugin, T as Repository, _ as customIdPlugin, a as uniqueField, b as prefixedId, c as createTenantContext, d as observabilityPlugin, f as multiTenantPlugin, g as elasticSearchPlugin, h as fieldFilterPlugin, i as requireField, j as auditTrailPlugin, k as batchOperationsPlugin, l as subdocumentPlugin, m as methodRegistryPlugin, n as blockIf, o as validationChainPlugin, p as mongoOperationsPlugin, r as immutableField, s as timestampPlugin, t as autoInject, u as softDeletePlugin, v as dateSequentialId, w as HOOK_PRIORITY, x as sequentialId, y as getNextSequence } from "./validation-chain.plugin-DwoOOWse.mjs";
-import { t as PaginationEngine } from "./PaginationEngine-C2_tAvAD.mjs";
+import { A as AuditTrailQuery, C as cachePlugin, D as withTransaction, E as isTransactionUnsupported, F as MUTATING_OPERATIONS, I as OP_REGISTRY, L as READ_OPERATIONS, M as auditLogPlugin, N as aggregateHelpersPlugin, O as AggregationBuilder, P as ALL_OPERATIONS, R as operationsByPolicyKey, S as cascadePlugin, T as Repository, _ as customIdPlugin, a as uniqueField, b as prefixedId, c as createTenantContext, d as observabilityPlugin, f as multiTenantPlugin, g as elasticSearchPlugin, h as fieldFilterPlugin, i as requireField, j as auditTrailPlugin, k as batchOperationsPlugin, l as subdocumentPlugin, m as methodRegistryPlugin, n as blockIf, o as validationChainPlugin, p as mongoOperationsPlugin, r as immutableField, s as timestampPlugin, t as autoInject, u as softDeletePlugin, v as dateSequentialId, w as HOOK_PRIORITY, x as sequentialId, y as getNextSequence } from "./validation-chain.plugin-Ccu6irtx.mjs";
+import { t as PaginationEngine } from "./PaginationEngine-B93fLCcO.mjs";
 import { isGeoOperator, parseGeoFilter } from "./query/primitives/geo.mjs";
 import { i as getMongooseProjection, n as filterResponseData, r as getFieldsForUser, t as createFieldPreset } from "./field-selection-dI0m4RBs.mjs";
 import { buildFieldTypeMap, coerceFieldValue, coerceHeuristic } from "./query/primitives/coercion.mjs";
 import { extractSchemaIndexes } from "./query/primitives/indexes.mjs";
-import { a as isFieldUpdateAllowed, i as getSystemManagedFields, n as buildCrudSchemasFromMongooseSchema, o as validateUpdateBody, r as getImmutableFields, s as createMemoryCache, t as buildCrudSchemasFromModel } from "./mongooseToJsonSchema-DUwXPStK.mjs";
+import { n as buildCrudSchemasFromMongooseSchema, r as createMemoryCache, t as buildCrudSchemasFromModel } from "./mongooseToJsonSchema-D1sdCOmj.mjs";
 //#region src/query/QueryParser.ts
 /**
 * Modern Query Parser
@@ -986,4 +986,4 @@ function createRepository(Model, plugins = [], paginationConfig = {}, options =
 }
 var src_default = Repository;
 //#endregion
-export { ALL_OPERATIONS, AggregationBuilder, AuditTrailQuery, HOOK_PRIORITY, LookupBuilder, MUTATING_OPERATIONS, OP_REGISTRY, PaginationEngine, QueryParser, READ_OPERATIONS, Repository, actions_exports as actions, aggregateHelpersPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, blockIf, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, cachePlugin, cascadePlugin, configureLogger, createError, createFieldPreset, createMemoryCache, createRepository, createTenantContext, customIdPlugin, dateSequentialId, src_default as default, elasticSearchPlugin, fieldFilterPlugin, filterResponseData, getFieldsForUser, getImmutableFields, getMongooseProjection, getNextSequence, getSystemManagedFields, immutableField, isFieldUpdateAllowed, isTransactionUnsupported, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, operationsByPolicyKey, parseDuplicateKeyError, prefixedId, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validateUpdateBody, validationChainPlugin, withTransaction };
+export { ALL_OPERATIONS, AggregationBuilder, AuditTrailQuery, HOOK_PRIORITY, LookupBuilder, MUTATING_OPERATIONS, OP_REGISTRY, PaginationEngine, QueryParser, READ_OPERATIONS, Repository, actions_exports as actions, aggregateHelpersPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, blockIf, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, cachePlugin, cascadePlugin, configureLogger, createError, createFieldPreset, createMemoryCache, createRepository, createTenantContext, customIdPlugin, dateSequentialId, src_default as default, elasticSearchPlugin, fieldFilterPlugin, filterResponseData, getFieldsForUser, getMongooseProjection, getNextSequence, immutableField, isDuplicateKeyError, isTransactionUnsupported, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, operationsByPolicyKey, parseDuplicateKeyError, prefixedId, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validationChainPlugin, withTransaction };