@classytic/mongokit 3.43.1 → 3.44.0

package/skills/mongokit/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: mongokit
+description: Mongoose 9 repositories for MongoDB, implementing repo-core StandardRepo. Use for models, repositories, plugins (tenant, soft delete, cache, audit), offset and keyset pagination, status transitions with history, transactions, outbox, search, geo, index checks. Triggers - mongokit, Repository, applyTransition, getAll, withTransaction, QueryParser.
+metadata:
+  minVersion: "3.43.1"
+  package: "@classytic/mongokit"
+  peers: "@classytic/repo-core >=0.31.1, mongoose >=9.11.2, node >=22"
+---
+
+# @classytic/mongokit
+
+Repository layer over Mongoose with the shared `StandardRepo<TDoc>` contract. Misses return `null` (or `{ success: false }`), not a thrown 404, unless `throwOnNotFound: true`.
+
+## Do not hand-roll
+
+| Need | Use |
+|---|---|
+| Register a model twice safely | `defineModel`, `defineModels` (explicit `onExisting`) |
+| Repo with tenant, soft delete, timestamps, cache, audit in the safe order | `createRepository` |
+| Status change with legality check, history row, race diagnosis | `repo.applyTransition` + `TransitionMachine` |
+| Compare-and-set on a version stamp | `repo.claimVersion` |
+| Multi-document atomic write | `withTransaction`, `batchTransaction`, `repo.withTransaction` |
+| Duplicate key (E11000) detection | `isDuplicateKeyError` |
+| URL query string to filter, sort, page, populate | `QueryParser` |
+| Indexed search-as-you-type | `searchMode: 'prefix'`, `searchKeysPath`, `searchKeysIndex`, `rebuildSearchKeys` |
+| Transactional outbox table and repo | `createOutboxRepository` (`/outbox`) |
+| HTTP idempotency replay store | `createIdempotencyStore` (`/idempotency`) |
+| Cross-process lock | `createMongoLockAdapter` (`/lock`) |
+| "Are my declared indexes built?" | `verifyIndexes`, `formatIndexReport` (`/indexes`) |
+| Tenant field plus tenant-led indexes on a schema | `injectTenantField`, `declareIndexes` (`/tenant`) |
+| Query timeout, read concern, profiler comment | `configureQueryDefaults`, `assertQueryDefaultsConfigured` |
+| Skip the per-page count at scale | `configurePaginationDefaults`, `countStrategy` |
+| Soft delete, append-only, immutable states | `softDeletePlugin`, `appendOnlyPlugin`, `immutableStatesPlugin` |
+| Sequential or prefixed ids | `customIdPlugin`, `sequentialId`, `prefixedId` |
+| Worker lease on pending rows | `leasePlugin` |
+| Bypass tenant scope on purpose | `systemContext`, `adminBypass` |
+| Forward request scope to a repo call | `repoOptionsFromCtx` |
+| arc DataAdapter for a repo | `createMongooseAdapter` (`/adapter`) |
+| Throwaway Mongo in tests | `createTestRepository`, `withMongoMemory` (`/testkit`) |
+
+## Golden path
+
+Model and repo (one registration, tenant and soft delete in the canonical order):
+
+```ts
+import { createRepository, defineModel } from '@classytic/mongokit';
+import { Schema } from 'mongoose';
+
+const Order = defineModel('Order', () => {
+  const schema = new Schema({ organizationId: String, status: String, total: Number,
+    statusHistory: { type: [new Schema({ status: String, occurredAt: Date, by: String, note: String }, { _id: false })], default: [] } },
+    { timestamps: true });
+  schema.index({ organizationId: 1, createdAt: -1, _id: -1 }); // keyset order + _id tiebreak
+  return schema;
+}, { onExisting: 'reuse' });
+
+export const orderRepo = createRepository(Order, {
+  tenant: { tenantField: 'organizationId', required: true }, softDelete: true, batch: true,
+});
+```
+
+List (envelope is `{ method, data, ... }`; pass `mode` explicitly):
+
+```ts
+const page = await orderRepo.getAll({ mode: 'offset', page: 1, limit: 20, filters: { status: 'open' }, sort: { createdAt: -1 } }, { organizationId });
+const first = await orderRepo.getAll({ mode: 'keyset', limit: 20, sort: { createdAt: -1 } }, { organizationId });
+const next = await orderRepo.getAll({ mode: 'keyset', after: first.next, limit: 20, sort: { createdAt: -1 } }, { organizationId });
+```
+
+Status transition (machine is `{ name, assertTransition }`; `defineStateMachine` satisfies it):
+
+```ts
+const moved = await orderRepo.applyTransition(id, MACHINE, { from: 'open', to: 'paid', by: actorId, note }, { organizationId });
+```
+
+Atomic write plus outbox row in one transaction (needs a replica set):
+
+```ts
+import { withTransaction } from '@classytic/mongokit';
+await withTransaction(mongoose.connection, async (session) => {
+  await orderRepo.create(data, { session, organizationId });
+  await outboxRepo.create(row, { session });
+});
+```
+
+HTTP query: `const parsed = new QueryParser({ schema: OrderSchema }).parse(req.query); await repo.getAll(parsed, scope);`
+
+## Gotchas
+
+- Tenant scope rides in the options bag (`{ organizationId }`), not in `filters`. Missing it throws; cross-tenant ids return `null`.
+- Offset and keyset are chosen by `mode`, else `page`, else `after`, else a non-default `sort` means keyset. Always pass `mode`.
+- Keyset needs a compound index on the sort keys plus `_id` (tenant field first when scoped).
+- `applyTransition` pushes `{ status, occurredAt, by, note }` to `statusHistory` in the same atomic write; `history: false` skips it. Loss throws `TRANSITION_RACE_LOST` (409) or `TRANSITION_TARGET_MISSING` (404), codes are upper-case.
+- `repo.withTransaction` hands you a tx-bound repo; the standalone `withTransaction` hands you a raw session. Standalone mongod cannot transact.
+- Filter keys missing from the schema are stripped by `strictQuery`; develop with `warnOnStrictQueryStrip: true`.
+- `QueryParser` throws 400 `INVALID_QUERY_INPUT` on blocked input by default; `search` text is escaped, never rejected.
+- Reads through the raw model skip tenant, soft delete and cache.
+- Prefix search keys are derived; writes outside the repo need `rebuildSearchKeys`.
+
+## Never
+
+- Hand-roll `findOneAndUpdate({ status })` CAS, E11000 string matching, or `mongoose.models.X ?? model()`.
+- Deep-import; use the subpaths in `llms.txt`.
+- Look for pagination result or error types here: they live in `@classytic/repo-core`.
+
+## References
+
+- `references/repository-api.md`: read for the method list, options bag, bulk, createMany, claim, aggregate, soft delete.
+- `references/pagination-search.md`: read for keyset indexes, count strategy, prefix search, QueryParser grammar, geo, lookups.
+- `references/plugins-tenancy.md`: read for plugin order, tenant indexes, cache, audit, cascade, field filter, hooks.
+- `references/transactions-outbox.md`: read for transactions, outbox, idempotency, lock, query defaults and comments, index verification.
+- Cross-package: contract types, errors, envelopes in skill `repo-core`; arc wiring in skill `arc`.

package/skills/mongokit/references/pagination-search.md

@@ -0,0 +1,87 @@
+# Pagination, search, QueryParser
+
+## Envelopes (types from `@classytic/repo-core/pagination`)
+
+```
+offset: { method: 'offset', data, page, limit, total, pages, hasNext, hasPrev, warning? }
+keyset: { method: 'keyset', data, limit, hasMore, next, prev?, hasPrev?, end? }
+```
+
+Narrow on `result.method`. Rows are in `data`.
+
+## Choosing a mode
+
+`mode` wins; else `page` means offset; else `after` means keyset; else `PaginationConfig.defaultMode`; else any non-default `sort` means keyset.
+Pass `mode` so a changed sort does not flip the response shape. `before` walks backward from a `prev` cursor.
+
+Keyset sort gets an `_id` tiebreak automatically; the index must match: `{ organizationId: 1, createdAt: -1, _id: -1 }`.
+`strictKeysetSortFields` limits which fields may be sorted on. Cursors are scoped to collection, tenant, filter and collation; a wrong one
+is 400 `repo.cursor.invalid` or `repo.cursor.scope_mismatch` (`PAGINATION_ERROR_CODES`). Sign cursors with `cursorSecret`.
+
+## Counting
+
+Offset pages count by default. `countStrategy`: `exact`, `estimated`, `capped` (with `countLimit`), `cached` (memoised per filter, never inside a
+transaction), `none` (no total). Set a deployment default once at boot:
+
+```ts
+import { configurePaginationDefaults } from '@classytic/mongokit';
+configurePaginationDefaults({ defaultCountStrategy: 'capped', defaultCountLimit: 10000 });
+```
+
+Offsets past `maxOffset` are refused with `mongokit.pagination.offset_too_deep`; page with keyset instead.
+
+## Search modes (`RepositoryOptions.searchMode`)
+
+| Mode | Behavior | Needs |
+|---|---|---|
+| `text` (default) | `$text` | text index |
+| `regex` | case-insensitive `$or` over `searchFields` | `searchFields`, scans |
+| `auto` | text if a text index exists, else regex | |
+| `prefix` | every query word starts some stored token (`moh ali` finds "Mohammed Al-Ali") | `searchFields`, keys path, multikey index |
+
+Prefix setup:
+
+```ts
+import { Repository, searchKeysPath } from '@classytic/mongokit';
+schema.add({ _searchKeys: searchKeysPath() });
+schema.index({ organizationId: 1, _searchKeys: 1 }); // tenant first when scoped
+const repo = new Repository(Model, [], {}, { searchMode: 'prefix', searchFields: ['name', 'code'] });
+await repo.getAll({ search: 'moh ali', mode: 'offset', page: 1, limit: 10 }, { organizationId });
+```
+
+Unscoped models can use `searchKeysIndex()`, which returns `{ fields, options }` for `schema.index`. Keys are rewritten on every repo write path.
+Writes that skip the repo (raw model, an auth adapter) must call `buildSearchKeys` or be repaired with `rebuildSearchKeys`. Client-side highlight with
+`findSearchMatches` from `@classytic/mongokit/search` (mongoose-free).
+Folding: case, accents, tashkeel, `أ إ آ ٱ` to `ا`, `ة` to `ه`, `ى` to `ي`, Arabic-Indic digits. To OR the keys with a plain prefix on a code field
+(not tokenised), build the filter yourself: `{ $or: [prefixSearchFilter(q, { keysField: repo.searchKeysField }), { code: { $regex: '^' + escaped } }] }`
+(drop the first arm when it is `null`) and pass it as `filters`; `search` itself ANDs with `filters`.
+
+## QueryParser
+
+`new QueryParser({ schema, allowedFilterFields, allowedSortFields, maxLimit, searchMode, searchFields, invalidInput, allowedLookupCollections })`.
+`parse(req.query)` returns `{ filters, sort, page, limit, after, select, populate, lookups, search }`, ready for `repo.getAll`.
+
+```
+?status=active&age[gte]=18&sort=-createdAt&page=1&limit=20
+?populate[orders][select]=id,total&populate[orders][match][status]=paid
+?lookup[category][from]=categories&lookup[category][localField]=slug&lookup[category][foreignField]=slug&lookup[category][single]=true
+```
+
+Invalid or blocked input throws 400 `INVALID_QUERY_INPUT`; `invalidInput: 'drop'` widens results and is for trusted tooling only.
+Dangerous operators and ReDoS regexes are blocked; `$lookup` targets must be listed in `allowedLookupCollections`. The same grammar as other kits is
+exposed by `parseUrl` in `@classytic/repo-core/query-parser`.
+
+## Geo
+
+Coordinates are always `lng,lat`. Operators on a 2dsphere field:
+
+```
+?location[near]=-73.97,40.78,5000            // sorted by distance, meters optional
+?location[nearSphere]=-73.97,40.78,5000
+?location[withinRadius]=-73.97,40.78,5000    // unsorted, safe for counts, pagination and joins
+?location[geoWithin]=minLng,minLat,maxLng,maxLat
+```
+
+Out-of-range coordinates drop the clause. Declare the `2dsphere` index in the schema. `near` without a max distance cannot be counted (use
+`countStrategy: 'none'`); do not combine `near` with keyset mode. Prefer `withinRadius` for paged lists. Pure builders are at
+`@classytic/mongokit/query/primitives/geo`.

package/skills/mongokit/references/plugins-tenancy.md

@@ -0,0 +1,102 @@
+# Plugins, tenancy, indexes
+
+## Order
+
+Prefer `createRepository`: it installs the canonical order and sets `pluginOrderChecks: 'throw'`. Hand-built chains
+(`new Repository(Model, [...])`) must keep: `methodRegistryPlugin` first; `multiTenantPlugin` before soft delete and cache (cache keys need
+the tenant); `softDeletePlugin` before `batchOperationsPlugin` (bulk ops must see the deletion filter). `requirePlugins: [MONGOKIT_PLUGIN_NAMES.multiTenant]`
+makes a missing plugin a boot error instead of a tenant leak.
+
+## Bundled plugins
+
+| Plugin | Adds |
+|---|---|
+| `timestampPlugin` | `createdAt`, `updatedAt` |
+| `softDeletePlugin` | `deletedAt` mark, read filter, `restore`, `getDeleted` |
+| `multiTenantPlugin` | tenant filter and payload injection (`tenantField`, `contextKey`, `required`, `fieldType`, `skipWhen`, `resolveContext`) |
+| `cachePlugin` | read-through cache with write invalidation |
+| `auditTrailPlugin` | persisted audit ledger with field diffs (`mode: 'transactional'` is atomic only inside a transaction) |
+| `auditLogPlugin` | structured log lines through your logger |
+| `changeLogPlugin` | change feed for sync (`@classytic/mongokit/plugins`) |
+| `cascadePlugin` | delete related rows (`relations`, `parallel`, `batchSize`) |
+| `fieldFilterPlugin` | role-based field visibility (`createFieldPreset`) |
+| `validationChainPlugin` | `requireField`, `immutableField`, `uniqueField`, `blockIf`, `autoInject` |
+| `customIdPlugin` | `sequentialId`, `prefixedId`, `dateSequentialId` |
+| `appendOnlyPlugin`, `immutableStatesPlugin` | refuse updates and deletes, or freeze rows in terminal states |
+| `leasePlugin` | time-bounded work claims (`nowFn` or per-call `now`, `attemptsField`, `maxAttempts`, `pendingFilter` object or `(now) => filter`, `deadLeaseStatuses`; `extend`/`release` need the row still in `processingStatus`) |
+| `batchOperationsPlugin`, `mongoOperationsPlugin`, `aggregateHelpersPlugin`, `subdocumentPlugin` | extra methods through the registry |
+| `observabilityPlugin` | timing, metrics, slow-op callback |
+| `elasticSearchPlugin` | delegate `search` to Elasticsearch |
+| `searchKeysPlugin` | prefix keys (installed by `searchMode: 'prefix'`) |
+
+Counters: `getNextSequence(key, inc, connection, session)` uses `_mongokit_counters`; `createSequenceCounter({ connection, collection })`
+binds `next`, `read`, `ensureAtLeast` (each with an optional session) to your own collection name; `sequentialId` / `dateSequentialId` take `counterCollection` for the same collection.
+Period-scoped: `getNextPeriodSequence(base, { period: 'year' | 'month' | 'day', timeZone, at?, session? })` (or `nextInPeriod`) derives the
+key from the civil date of `at` in an IANA zone and returns `{ seq, period, counterKey }`; `dateSequentialId` takes `timeZone`, `at(ctx)`, `counterKey`.
+Retention purge (append-only or frozen rows): build `appendOnlyPlugin` and/or `immutableStatesPlugin` with `allowPurge: true`, then
+`purgeByFilter(filter, { type: 'hard' }, { retentionPurge: { reason, actor } })` (or `deleteMany(filter, { mode: 'hard', retentionPurge })`).
+Each delete call emits `after:append-only-purge` / `after:immutable-states-purge` with `deletedCount` and `session`. Listeners are awaited and a
+throwing one fails the purge; write the audit row with `{ session: event.session }` so it commits or aborts with the delete. Ordinary deletes stay refused.
+Function-form anonymize writes through the guarded `updateMany` (frozen / append-only rows refused); `immutableStatesPlugin` reads state in the call's session.
+
+`leasePlugin` (after `methodRegistryPlugin`): `lease({ filter, leaseFor, leasedBy, now })` claims a pending row or a dead lease (a row
+still in `processingStatus` whose expiry passed); the caller filter, its `$or` included, is ANDed in. `extend` and `release` CAS on
+`leasedBy` plus a live expiry, so make `leasedBy` unique per claim. Cancelling a leased row from outside should also `$unset` the lease fields.
+With `maxAttempts`, set `exhaustedStatus: 'failed'` (and `exhaustedAtField`) and schedule `reapExhausted({ now, limit })`: it moves rows at the cap
+whose lease lapsed (or that sit pending) to that status by CAS and returns them once, for the host to audit and alert.
+
+## Tenancy
+
+```ts
+multiTenantPlugin({ tenantField: 'organizationId', contextKey: 'organizationId', required: true, fieldType: 'objectId' });
+await repo.getAll({ mode: 'offset', page: 1 }, { organizationId });          // scoped
+await repo.update(id, data, { organizationId: 'other' });                     // null: cross-tenant miss
+await repo.getAll({ mode: 'offset', page: 1 }, systemContext());              // bypassTenant for jobs
+```
+
+`createTenantContext()` (AsyncLocalStorage) removes the need to pass the scope on each call. `repoOptionsFromCtx(ctx)` forwards a request scope.
+Richer rules (branches, owners, roles) compose on top with `skipWhen` and `adminBypass({ adminRoles })`; do not widen the plugin.
+
+## Tenant-led indexes
+
+`@classytic/mongokit/tenant` mutates the schema so every declared compound index leads with the tenant field:
+
+```ts
+import { injectTenantField } from '@classytic/mongokit/tenant';
+import { resolveTenantConfig } from '@classytic/repo-core/tenant';
+
+injectTenantField(schema, resolveTenantConfig({ tenantField: 'organizationId' }), {
+  skipIndexes: ['event_id_unique'],
+  indexes: [{ fields: { buyerId: 1, createdAt: -1 }, scope: 'global', options: { name: 'buyer_history_global' } }],
+});
+```
+
+`scope: 'global'` keeps the index as written for an identity read across tenants; it must be named, must not name the tenant field, and must be
+paired with a `bypassTenant` read. TTL indexes are never prefixed.
+
+## Cache
+
+```ts
+import { cachePlugin, createMemoryCache } from '@classytic/mongokit';
+cachePlugin({ adapter: createMemoryCache(), defaults: { staleTime: 30, gcTime: 300, swr: true }, prefix: 'orders' });
+await repo.getById(id, { cache: { bypass: true } });          // per call
+```
+
+An adapter is `{ get, set(key, value, ttlSeconds), delete, clear? }`. Writes invalidate by tag; `autoTagsFromScope` tags with the tenant.
+
+## Audit trail
+
+```ts
+auditTrailPlugin({ mode: 'transactional', collectionName: 'audit_trail', ttlDays: 365, excludeFields: ['password'], metadata: (ctx) => ({ actor: ctx.actorId }) });
+await ensureAuditTrailReady();   // at boot, so the first transaction does not create the collection
+const query = new AuditTrailQuery(Model);
+```
+
+`best-effort` (default) is fire and forget and is observability only.
+
+## Index discipline
+
+- Declare every index in the schema (`schema.index(fields, { name })`); name each one so drift reports are readable.
+- Sort, cursor, purge and prefix-search fields all need a supporting index; unindexed purge is O(n squared).
+- Run `verifyIndexes(connection)` in CI or a deploy check (see `transactions-outbox.md`); it is read-only and never builds indexes.
+- Tag slow queries with `comment` (per call or `configureQueryDefaults({ comment })`) so they are findable in the profiler.

package/skills/mongokit/references/repository-api.md

@@ -0,0 +1,83 @@
+# Repository API
+
+`new Repository(Model, plugins?, paginationConfig?, options?)` or `createRepository(Model, config)`. `config` keys:
+`tenant`, `softDelete`, `timestamps`, `batch`, `cache`, `audit`, `customId`, `plugins` (appended last), `pagination`, plus
+`RepositoryOptions` (`idField`, `searchMode`, `searchFields`, `pluginOrderChecks`, `requirePlugins`, `queryDefaults`, `hooks`).
+The factory installs plugins in the safe order (registry, tenant, soft delete, timestamps, custom id, cache, audit, batch) and
+fails fast on a bad order.
+
+Every method takes an options bag last: `{ session, organizationId, select, populate, lean, throwOnNotFound, bypassTenant, includeDeleted, comment, maxTimeMS }`.
+
+## Reads
+
+| Method | Miss result |
+|---|---|
+| `getById(id, opts)` | `null` (a malformed id is a miss, not a CastError) |
+| `getOne(filter, { sort })`, `getByQuery` | `null` |
+| `getByIds(ids)` | `Map` of found rows |
+| `getAll(params, opts)` | envelope with empty `data` |
+| `findAll(filter, opts)` | `[]` |
+| `count`, `exists`, `distinct` | `0`, `null`, `[]` |
+| `iterate(filter, { batchSize, after })` | async batches `{ docs, checkpoint }`, resumable |
+| `cursor`, `watch` | streams (watch needs a replica set) |
+
+Filters accept Mongo objects or repo-core Filter IR (`eq`, `and`, `in_` from `@classytic/repo-core/filter`).
+
+## Writes
+
+| Method | Notes |
+|---|---|
+| `create`, `createMany` | `createMany` rejects on a partial write; `isCreateManyPartialError(err)` then read the report |
+| `update(id, data, opts)` | `null` on miss; `ifVersion` adds a stamp check |
+| `findOneAndUpdate(filter, update, { sort })` | atomic claim of the oldest row |
+| `getOrCreate(filter, data)` | `{ doc, created }`, no race |
+| `delete(id, { mode })` | soft when `softDeletePlugin` is on; `mode: 'hard'` removes |
+| `updateMany`, `deleteMany`, `bulkWrite` | need `batchOperationsPlugin` (or `batch: true`) after soft delete |
+| `bulkUpsert(rows, { key, set, inc, setOnInsert })` | one command, per-row outcome; MongoDB 8; refused without a unique index on key plus scope |
+| `purgeByField`, `purgeByFilter`, `archiveByFilter` | chunked, abortable, plugin-composed cleanup; index the field first |
+
+## Compare-and-set family
+
+| Primitive | Use when | Loss signal |
+|---|---|---|
+| `claim(id, { from, to, where }, patch)` | state move, `from` may be an array | `null` |
+| `applyTransition(id, machine, args)` | state move with legality, history, diagnosis | throws 409, 404 or the machine's error |
+| `claimVersion(id, { from, where }, update)` | optimistic lock, `$inc` on `version` | `null` |
+| `claim` with `upsert` and `from === to` | first-writer-wins insert | existing doc |
+| `leasePlugin().lease()` | worker takes the next pending row with a TTL | `null` |
+
+`applyTransition` args: `from`, `to`, `set`, `push`, `inc`, `unset`, `where`, `by`, `note`, `history` (field name or `false`), `field`, `at`,
+`priorAt`, `historyExtra`. Options also take `target` (forwarded to `claim`).
+A `TransitionMachine` is `{ name, assertTransition(entityId, from, to) }`; throw your domain error from it. Legality is checked before the
+write; on a lost race the row is re-read and the error reflects its CURRENT state. It does no read of its own, so pass `priorAt` (when the
+row entered its current state, from your read) to record `durationInPriorMs`, and guard that read with `where: { updatedAt }` or `target`.
+`historyExtra` merges extra fields into the entry; reserved keys and either arg with `history: false` are a 400.
+
+Codes: `TRANSITION_RACE_LOST` (409, still legal, re-read and retry), `TRANSITION_TARGET_MISSING` (404). An idempotent event handler
+treats both as "already moved". Tenant scope must be passed in the options bag.
+
+## Aggregation
+
+`aggregate(req)` is the portable IR (`groupBy`, `measures`, `having`, `sort`, date buckets), identical on other kits. `aggregatePipeline(stages)`
+is native Mongo (`$lookup`, `$facet`). `aggregatePaginate` and `aggregatePipelinePaginate` return envelopes. `lookupPopulate(params)` joins by
+any field without a `ref`. `compileFilterToMongo(filterIR)` reuses the filter compiler inside a custom pipeline.
+
+## Soft delete
+
+`softDeletePlugin({ deletedField: 'deletedAt', filterMode })` adds `restore(id)` and `getDeleted(params)`; reads hide deleted rows unless
+`includeDeleted: true`. Make unique indexes partial so deleted rows do not block inserts:
+
+```ts
+schema.index({ email: 1 }, { unique: true, partialFilterExpression: { deletedAt: null } });
+```
+
+## Events and hooks
+
+`repo.on('before:update' | 'after:create' | 'error:delete', handler, { priority })` with `HOOK_PRIORITY` (POLICY 100, VALIDATION 150, CACHE 200,
+OBSERVABILITY 300, DEFAULT 500). `before:*` handlers may mutate `context.data` and `context.query`. `registerRepositoryEvents` (from
+`@classytic/repo-core/events`) publishes domain events from repo operations.
+
+## Errors
+
+Repo errors are `HttpError` shaped (`status`, `code`, `meta`, `duplicate`, `validationErrors`); see skill `repo-core`.
+`isDuplicateKeyError(err)` and `parseDuplicateKeyError(err)` (field names only unless `exposeValues`) classify E11000.

package/skills/mongokit/references/transactions-outbox.md

@@ -0,0 +1,101 @@
+# Transactions, outbox, idempotency, locks, defaults
+
+Transactions need a replica set (a single-node replica set is fine). `supportsTransactions`, `isTransactionUnsupported` and
+`repo.capabilities.transactions` report what the deployment can do; the descriptor is observed from the live topology.
+
+## Three transaction forms
+
+```ts
+import { batchTransaction, withTransaction } from '@classytic/mongokit';
+
+// 1. one repo: callback gets a tx-bound repo and a handle with the raw session
+await orderRepo.withTransaction(async (tx, uow) => {
+  const order = await tx.create({ total: 100 });
+  await tx.update(order._id, { confirmed: true });
+  await outboxRepo.create(row, { session: uow?.session });   // work outside the repo joins the session
+  return order;
+});
+
+// 2. several repos, each auto-bound to one session
+await batchTransaction(mongoose.connection, { orders: orderRepo, events: eventRepo }, async ({ orders, events }) => {
+  const created = await orders.create(data);
+  await events.create({ type: 'order.placed', orderId: created._id });
+});
+
+// 3. raw session, for code that is not a repo
+await withTransaction(mongoose.connection, async (session) => { await orderRepo.create(data, { session }); });
+```
+
+Options: `transactionOptions`, `allowFallback` (dev on standalone: runs once without a transaction), `onFallback(err)`. Transient errors retry
+per the driver rules. Nested `tx.withTransaction` throws; reuse the outer bound repo. `isTransientConflictError(err)` marks retryable conflicts.
+
+To serialise writers on a row, the write must change it. An update that sets a field to the value it already has (`$set: { at: now }` from two
+writers at the same instant) is a no-op: it takes no write lock, so two transactions doing it never conflict. Make the write real, for example
+`$inc: { writes: 1 }` on the row (the same holds for a lease or gate row you rely on to order concurrent work).
+
+## Outbox (`@classytic/mongokit/outbox`)
+
+```ts
+import { createOutboxRepository } from '@classytic/mongokit/outbox';
+const outboxRepo = createOutboxRepository(mongoose.connection, { visibleAtField: 'visibleAt' });
+```
+
+It is the Mongo half only: the model (`_id` is the event id, so replays are duplicate-key no-ops), four indexes for claim, dedupe and retention, and
+a repository with the required registry and batch plugins. Wrap it with arc's `repositoryAsOutboxStore(repo, { visibleAtField })` (use the SAME
+`visibleAtField`) and relay with arc's outbox module. Write the row in the same session as the business write. Delivered rows expire by TTL
+(`ttlSeconds`, default 7 days); pending and dead-lettered rows never do. Statuses: `OUTBOX_STATUSES`. The repository has no `maxLimit` cap, so
+the relay's `batchSize` is the claim window; pass `pagination: { maxLimit }` to set a ceiling (keep `batchSize` at or below it).
+
+## Idempotency claims (`/idempotency`)
+
+```ts
+import { createIdempotencyModel, createIdempotencyStore } from '@classytic/mongokit/idempotency';
+import { runIdempotent } from '@classytic/repo-core/idempotency';
+const store = createIdempotencyStore(createIdempotencyModel(mongoose.connection), { retentionSeconds: 7 * 86400 });
+```
+
+Size `retentionSeconds` to the longest a caller may retry. Contract details are in skill `repo-core`.
+
+## Locks, usage, sync, read models
+
+| Subpath | Export | Use |
+|---|---|---|
+| `/lock` | `createMongoLockAdapter({ connection, nowFn })` | cross-process mutex with expiry (`nowFn` must track wall time: TTL index). `acquire(name, holder, leaseMs)` answers `{ acquired, holder, previousHolder?, acquiredAt, expiresAt }` from the one atomic write (no `inspect` first to learn who held it); `tryAcquire` stays a boolean |
+| `/lock` | `createMongoDailyLedger({ connection, collectionName })` | arc `DailyLedger` for `createDailyGate`: one claim per key and civil day; every claim gets a unique token, and complete/release act only on the claim the calling invocation won (an older run never completes or releases a newer stale re-grant, a retry stays fenced). Host code: `claim(key, day, info)` returns a handle with fenced `complete()` / `release()`. Manual completion is the explicit `adminCompleteDay`, never a fallback |
+| `/usage` | `createMongoUsageStore` | metered counters per period |
+| `/sync` | `createChangeLogStore(models, { now, onSequenced })`, `createCommandStreamStore` | offline sync stores (models from `createChangeLogModels`, `sequencing: 'deferred'` with `sequencerLeaseMs` to keep writers off the counter row); `now` stamps `at`; `onSequenced({ cursor, numbered, by })` wakes a replay hub when entries got cursors, also after a read lost the sequencer lease to another holder; retention: schedule `prune(before)`; horizons are kept per `(tenantId, scope)`, so `since(cursor, { tenantId, scopes })` throws `CursorExpiredError` only when something that reader can see was pruned past its cursor, and it resyncs from `latestCursor(sameOptions)` (never below its horizon) |
+| `/read-model` | `applyIncrements`, `rebuildInto`, `reconcile` | counter read models with drift reports |
+| `/testkit` | `createTestRepository`, `withMongoMemory`, `createMongoMemory`, `clearCollections` | in-memory Mongo (replica set) for tests |
+| `/testkit` | `assertQueryPlan`, `explainCommands` | gate or explain the commands a call really sent (`commands: ['findAndModify']` for a lease claim) |
+| `/kernel-conformance` | conformance suite | prove a kernel behaves on this kit |
+
+## Query defaults and comments
+
+Resolution order: per call, then repository (`queryDefaults` option), then deployment.
+
+```ts
+import { assertQueryDefaultsConfigured, configureAggregateDefaults, configureQueryDefaults } from '@classytic/mongokit';
+configureQueryDefaults({ maxTimeMS: 15000, readConcern: 'majority', comment: 'api' });
+configureAggregateDefaults({ maxTimeMs: 30000, allowDiskUse: true });
+assertQueryDefaultsConfigured(mongoose.connection);   // boot gate: throws without maxTimeMS or a client timeoutMS
+await repo.getAll({ mode: 'offset', page: 1 }, { comment: 'orders.list', maxTimeMS: 5000, hint: { organizationId: 1, createdAt: -1 } });
+```
+
+Inside a transaction a default read or write concern is dropped (the transaction owns it); a per-call one is passed through.
+
+## Verify indexes
+
+```ts
+import { formatIndexReport, verifyIndexes } from '@classytic/mongokit/indexes';
+const report = await verifyIndexes(mongoose.connection, { includeModel: (name) => name !== 'AuthSession' });
+if (report.missingUnique.length || report.incompatible.length) throw new Error(formatIndexReport(report));
+```
+
+`missingUnique` means duplicates may already exist; `incompatible` means the same keys with different `unique`, `partialFilterExpression`,
+`sparse`, `collation` or TTL (fix by rebuild). Extra indexes in the database are not drift. Build indexes in a deploy step, never at serve time.
+
+## Model registry
+
+`defineModel(name, () => schema, { onExisting: 'reuse' | 'throw', connection })`: `reuse` for stubs and counters, `throw` (`ModelCollisionError`)
+when you contribute fields or indexes a locked schema would silently drop. `defineModels({ models, assemble })` describes a model set without a
+connection, then `blueprint.bind(connection)` registers it (policies `throw`, `reuse`, `replace` for tests only).