@classytic/mongokit 3.7.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-CPmZv7Ds.mjs → PaginationEngine-B93fLCcO.mjs}

@@ -1,7 +1,7 @@
 import { r as warn } from "./logger-DJ7egMnd.mjs";
-import { t as createError } from "./error-Lw9GEAro.mjs";
-import { n as encodeCursor, r as resolveCursorFilter } from "./cursor-DZ9JSoMM.mjs";
-import { r as validateKeysetSort, t as getPrimaryField } from "./sort-ffe-9JBg.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
 /**
 * Read a Mongoose schema's declared indexes, defensively.

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-C-qZUqv8.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 { _ as aggregate_exports, f as delete_exports, h as create_exports, l as read_exports, r as update_exports } from "../update-BDsQ3cdy.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 { J as Plugin } from "../types-BgdeBXI1.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-C-qZUqv8.d.mts → index-C7WmYP6F.d.mts}

@@ -1,4 +1,4 @@
-import { $ as ReadPreferenceType, At as LookupOptions, D as GroupResult, V as ObjectId, W as OperationOptions, Z as PopulateSpec, _t as UpdateOptions, a as AnyDocument, b as DeleteResult, g as CreateOptions, gt as UpdateManyResult, pt as SortSpec, st as SelectSpec, vt as UpdateWithValidationResult, z as MinMaxResult } from "./types-BgdeBXI1.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
@@ -213,12 +213,12 @@ declare function exists<TDoc = AnyDocument>(Model: Model<TDoc>, query: Record<st
   _id: unknown;
 } | null>;
 declare namespace update_d_exports {
-  export { increment, pullFromArray, pushToArray, update, updateByQuery, updateMany, updateWithConstraints, updateWithValidation };
+  export { findOneAndUpdate, increment, pullFromArray, pushToArray, update, updateByQuery, updateMany, updateWithConstraints, updateWithValidation };
 }
 /**
  * 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)
@@ -255,18 +255,26 @@ declare function updateMany(Model: Model<unknown>, query: Record<string, unknown
  * Update by query
  */
 declare function updateByQuery<TDoc = AnyDocument>(Model: Model<TDoc>, query: Record<string, unknown>, data: Record<string, unknown>, options?: UpdateOptions): Promise<TDoc | null>;
+/**
+ * Atomic findOneAndUpdate primitive.
+ *
+ * Returns the matched document (post-update by default) or null when no doc
+ * matches and `upsert` is false. Used by outbox relays, distributed locks,
+ * and workflow semaphores that need compare-and-set in a single round-trip.
+ */
+declare function findOneAndUpdate<TDoc = AnyDocument>(Model: Model<TDoc>, filter: Record<string, unknown>, update: Record<string, unknown> | Record<string, unknown>[], options?: FindOneAndUpdateOptions): Promise<TDoc | null>;
 /**
  * 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,13 +1,51 @@
-import { $ as ReadPreferenceType, A as InferDocument, At as LookupOptions, B as NonNullableFields, C as EventPayload, Ct as WithPlugins, D as GroupResult, Dt as IRequestContext, E as FieldRules, Et as IControllerResponse, F as KeysetPaginationResult, G as PaginationConfig, H as OffsetPaginationOptions, I as Logger, J as Plugin, K as PaginationResult, L as LookupPopulateOptions, M as JsonSchema, N as KeysOfType, O as HookMode, Ot as IResponseFormatter, P as KeysetPaginationOptions, Q as ReadOptions, R as LookupPopulateResult, S as EventHandlers, St as ValidatorDefinition, T as FieldPreset, Tt as IController, U as OffsetPaginationResult, V as ObjectId, W as OperationOptions, X as PluginType, Y as PluginFunction, Z as PopulateSpec, _ as CrudSchemas, _t as UpdateOptions, a as AnyDocument, at as RequiredBy, b as DeleteResult, bt as ValidationChainOptions, c as CacheOperationOptions, ct as SessionOptions, d as CacheableOptions, dt as SoftDeleteRepository, et as RepositoryContext, f as CascadeOptions, ft as SortDirection, g as CreateOptions, gt as UpdateManyResult, h as CreateInput, ht as UpdateInput, i as AllPluginMethods, it as RepositoryOptions, j as InferRawDoc, k as HttpError, kt as LookupBuilder, l as CacheOptions, lt as SoftDeleteFilterMode, m as CollationOptions, mt as Strict, n as AggregatePaginationOptions, nt as RepositoryInstance, o as AnyModel, ot as SchemaBuilderOptions, p as CascadeRelation, pt as SortSpec, q as PartialBy, r as AggregatePaginationResult, rt as RepositoryOperation, s as CacheAdapter, st as SelectSpec, t as AggregateOptions, tt as RepositoryEvent, u as CacheStats, ut as SoftDeleteOptions, v as DecodedCursor, vt as UpdateWithValidationResult, w as EventPhase, wt as WithTransactionOptions, x as DocField, xt as ValidationResult, y as DeepPartial, yt as UserContext, z as MinMaxResult } from "./types-BgdeBXI1.mjs";
-import { t as index_d_exports } from "./index-C-qZUqv8.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-Be9rG04B.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-Du-UopRK.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
+/**
+ * Where a plugin should inject its scoping filter (multi-tenant scope,
+ * soft-delete filter, etc.) on the RepositoryContext.
+ *
+ * - `data`        — single-doc create payload (`context.data`)
+ * - `dataArray`   — multi-doc create payload (`context.dataArray`)
+ * - `query`       — raw filter (`context.query`); the dominant convention
+ * - `filters`     — paginated list options' filter sub-bag (`context.filters`)
+ * - `operations`  — bulkWrite per-sub-op (special — plugins walk each entry)
+ * - `none`        — no scoping target (op accepts no filter input)
+ */
+type PolicyKey = 'data' | 'dataArray' | 'query' | 'filters' | 'operations' | 'none';
+interface OperationDescriptor {
+  /** Where multi-tenant / soft-delete plugins inject their scoping filter. */
+  policyKey: PolicyKey;
+  /** Whether this op writes to the database. Drives audit + cache invalidation. */
+  mutates: boolean;
+  /** True when `context.id` is populated by the time before/after hooks fire. */
+  hasIdContext: boolean;
+}
+/**
+ * The registry. Order intentionally groups by category for readability.
+ * Adding a new RepositoryOperation requires exactly one entry here, after
+ * which every bundled plugin auto-classifies it correctly.
+ */
+declare const OP_REGISTRY: Readonly<Record<RepositoryOperation, OperationDescriptor>>;
+/** All known repository operations, in registry order. */
+declare const ALL_OPERATIONS: RepositoryOperation[];
+/** Operations that mutate the database. Drives audit + cache invalidation lists. */
+declare const MUTATING_OPERATIONS: readonly RepositoryOperation[];
+/** Operations that don't mutate. Drives default cacheable ops. */
+declare const READ_OPERATIONS: readonly RepositoryOperation[];
+/** Filter ops by their policy injection key. */
+declare function operationsByPolicyKey(key: PolicyKey): RepositoryOperation[];
+//#endregion
 //#region src/query/AggregationBuilder.d.ts
 /** Options for $vectorSearch stage (Atlas only) */
 interface VectorSearchOptions {
@@ -829,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;
@@ -863,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;
   /**
@@ -997,7 +1030,37 @@ 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).
+   *
+   * Single round-trip match-and-mutate for outbox relays, distributed locks,
+   * and workflow semaphores. Goes through the full hook pipeline so
+   * multi-tenant scope, soft-delete, audit, and cache plugins all apply.
+   *
+   * Returns the matched document (post-update by default) or `null` when no
+   * document matches and `upsert` is false.
+   *
+   * @example FIFO claim-lease for an outbox worker
+   * ```ts
+   * const claimed = await outboxRepo.findOneAndUpdate(
+   *   { status: 'pending', leaseExpiresAt: { $lt: new Date() } },
+   *   { $set: { status: 'processing', leaseExpiresAt: leaseUntil, leasedBy: workerId } },
+   *   { sort: { createdAt: 1 }, returnDocument: 'after' },
+   * );
+   * if (!claimed) return; // queue empty
+   * ```
+   *
+   * @example CAS upsert
+   * ```ts
+   * const lock = await locksRepo.findOneAndUpdate(
+   *   { _id: lockKey, ownerId: { $in: [null, workerId] } },
+   *   { $set: { ownerId: workerId, expiresAt: leaseUntil } },
+   *   { upsert: true },
+   * );
+   * ```
+   */
+  findOneAndUpdate<TResult = TDoc>(filter: Record<string, unknown>, update: Record<string, unknown> | Record<string, unknown>[], options?: FindOneAndUpdateOptions): Promise<TResult | null>;
   /**
    * Delete a document by ID.
    *
@@ -1021,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.
+   *
+   * 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
+   */
+  aggregatePipeline<TResult = unknown>(pipeline: PipelineStage[], options?: AggregateOptions): Promise<TResult[]>;
+  /**
+   * 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.
+   */
+  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.
    *
-   * @param pipeline - Aggregation pipeline stages
-   * @param options - Aggregation options including governance controls
+   * 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<TResult = unknown>(pipeline: PipelineStage[], options?: AggregateOptions): Promise<TResult[]>;
+  aggregate<TRow extends Record<string, unknown> = Record<string, unknown>>(req: AggRequest): Promise<AggResult<TRow>>;
   /**
-   * Aggregate pipeline with pagination
-   * Best for: Complex queries, grouping, joins
+   * 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.
    *
-   * Policy hooks (multi-tenant, soft-delete) inject context.filters which are
-   * prepended as a $match stage to the pipeline, ensuring tenant isolation.
+   * `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(options?: AggregatePaginationOptions): Promise<AggregatePaginationResult<TDoc>>;
+  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)
@@ -1107,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
@@ -1151,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).
@@ -1174,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
    */
@@ -1232,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 { 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 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, type MinMaxResult, type MongoOperationsMethods, type MultiTenantOptions, type NonNullableFields, type ObjectId, type ObservabilityOptions, type OffsetPaginationOptions, type OffsetPaginationResult, type OperationMetric, type OperationOptions, type PaginationConfig, PaginationEngine, type PaginationResult, type ParsedQuery, type PartialBy, type Plugin, type PluginFunction, type PluginType, type PopulateOption, type PopulateSpec, type PrefixedIdOptions, QueryParser, type QueryParserOptions, 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, 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 };