@classytic/repo-core 0.22.0 → 0.23.0

package/dist/errors/conflict.d.mts

@@ -0,0 +1,84 @@
+//#region src/errors/conflict.d.ts
+/**
+ * Concurrency-conflict taxonomy — driver-agnostic contract.
+ *
+ * Two DIFFERENT conflicts hide under "the write lost a race", and they demand
+ * opposite responses:
+ *
+ * 1. **Transient transaction conflict** — the backend aborted a transaction
+ *    because of concurrent access, and re-running the SAME work is the
+ *    designed recovery. Retryable by definition.
+ *
+ *    | Backend    | Signal                                                     |
+ *    |------------|------------------------------------------------------------|
+ *    | MongoDB    | error label `TransientTransactionError` / code 112          |
+ *    | Postgres   | `40001` serialization_failure / `40P01` deadlock_detected   |
+ *    | SQLite     | `SQLITE_BUSY` / `SQLITE_LOCKED`                             |
+ *    | Prisma     | `P2034` (transaction conflict)                              |
+ *
+ * 2. **Version conflict** — an optimistic-concurrency CAS (`ifVersion`) found
+ *    the record changed since it was read. Re-running the same write would
+ *    overwrite someone else's change, so it is NEVER auto-retried: the caller
+ *    must re-read and re-decide (HTTP maps it to 409 + `If-Match` semantics).
+ *
+ * Classification of (1) belongs in the kit that knows its driver — same rule
+ * as `IsDuplicateKeyErrorFn`. Repositories expose it as
+ * `isTransientConflictError`; the shared `retryingTransaction` envelope
+ * consumes the boolean. The default is `neverTransient`: retrying work whose
+ * failure class is UNKNOWN is the unsafe direction (it re-runs side effects
+ * on validation/permission failures), so silence means "don't".
+ */
+/** Predicate shape kits implement and repositories expose as `isTransientConflictError`. */
+type IsTransientConflictFn = (err: unknown) => boolean;
+/**
+ * Safe default: nothing is transient until the kit says so. The opposite
+ * default (retry everything) turns a deterministic failure into N delayed
+ * copies of itself — and re-runs side effects that already happened.
+ */
+declare const neverTransient: IsTransientConflictFn;
+/**
+ * Conservative MongoDB FALLBACK — not mongokit's classifier, and not an
+ * exception to the ownership rule above. Exactly the role (and placement) of
+ * `conservativeMongoIsDuplicateKey`: a floor for a repository that exposes no
+ * `isTransientConflictError` of its own, so back-compat with a kit predating
+ * the predicate degrades to "the driver's own explicit signals" rather than
+ * to `neverTransient`. Kits still own classification — mongokit's method
+ * delegates here deliberately (there is nothing to add), and non-Mongo kits
+ * MUST implement their own: this returns `false` for `SQLITE_BUSY`, `P2034`,
+ * `40001`, and every other native signal.
+ *
+ * Matches ONLY the `TransientTransactionError` label the server attaches and
+ * the bare WriteConflict code — never message text.
+ */
+declare const conservativeMongoIsTransientConflict: IsTransientConflictFn;
+/**
+ * Optimistic-concurrency violation: an `ifVersion` CAS write found a
+ * different stored version than the caller read.
+ *
+ * A CLASS (not a factory) for the same reason primitives' outbox errors are
+ * classes: consumers branch on `instanceof` across package boundaries, and a
+ * version conflict must be distinguishable from not-found — a repository
+ * signals "no such record" with `null`, and MUST NOT collapse a stale version
+ * into it, or the caller retries a write that would clobber a concurrent one.
+ */
+declare class VersionConflictError extends Error {
+  readonly code: 'version_conflict';
+  /** HTTP mapping — 409 Conflict, pairs with ETag/`If-Match`. */
+  readonly status: 409;
+  readonly expectedVersion: number;
+  /** The stored version at CAS time, when the backend can report it cheaply. */
+  readonly actualVersion?: number;
+  readonly id?: string;
+  constructor(opts: {
+    expectedVersion: number;
+    actualVersion?: number;
+    id?: string;
+  });
+}
+/**
+ * Duck-typed check that survives two repo-core copies in one dependency
+ * graph, where `instanceof` silently fails across the boundary.
+ */
+declare function isVersionConflictError(err: unknown): err is VersionConflictError;
+//#endregion
+export { IsTransientConflictFn, VersionConflictError, conservativeMongoIsTransientConflict, isVersionConflictError, neverTransient };

package/dist/errors/conflict.mjs

@@ -0,0 +1,63 @@
+//#region src/errors/conflict.ts
+/**
+* Safe default: nothing is transient until the kit says so. The opposite
+* default (retry everything) turns a deterministic failure into N delayed
+* copies of itself — and re-runs side effects that already happened.
+*/
+const neverTransient = () => false;
+/**
+* Conservative MongoDB FALLBACK — not mongokit's classifier, and not an
+* exception to the ownership rule above. Exactly the role (and placement) of
+* `conservativeMongoIsDuplicateKey`: a floor for a repository that exposes no
+* `isTransientConflictError` of its own, so back-compat with a kit predating
+* the predicate degrades to "the driver's own explicit signals" rather than
+* to `neverTransient`. Kits still own classification — mongokit's method
+* delegates here deliberately (there is nothing to add), and non-Mongo kits
+* MUST implement their own: this returns `false` for `SQLITE_BUSY`, `P2034`,
+* `40001`, and every other native signal.
+*
+* Matches ONLY the `TransientTransactionError` label the server attaches and
+* the bare WriteConflict code — never message text.
+*/
+const conservativeMongoIsTransientConflict = (err) => {
+	if (!err || typeof err !== "object") return false;
+	const e = err;
+	if (Array.isArray(e.errorLabels) && e.errorLabels.includes("TransientTransactionError")) return true;
+	if (typeof e.hasErrorLabel === "function" && e.hasErrorLabel("TransientTransactionError")) return true;
+	return e.code === 112 || e.codeName === "WriteConflict";
+};
+/**
+* Optimistic-concurrency violation: an `ifVersion` CAS write found a
+* different stored version than the caller read.
+*
+* A CLASS (not a factory) for the same reason primitives' outbox errors are
+* classes: consumers branch on `instanceof` across package boundaries, and a
+* version conflict must be distinguishable from not-found — a repository
+* signals "no such record" with `null`, and MUST NOT collapse a stale version
+* into it, or the caller retries a write that would clobber a concurrent one.
+*/
+var VersionConflictError = class extends Error {
+	code = "version_conflict";
+	/** HTTP mapping — 409 Conflict, pairs with ETag/`If-Match`. */
+	status = 409;
+	expectedVersion;
+	/** The stored version at CAS time, when the backend can report it cheaply. */
+	actualVersion;
+	id;
+	constructor(opts) {
+		super(`Version conflict${opts.id ? ` on "${opts.id}"` : ""}: expected v${opts.expectedVersion}` + (opts.actualVersion !== void 0 ? `, found v${opts.actualVersion}` : ""));
+		this.name = "VersionConflictError";
+		this.expectedVersion = opts.expectedVersion;
+		if (opts.actualVersion !== void 0) this.actualVersion = opts.actualVersion;
+		if (opts.id !== void 0) this.id = opts.id;
+	}
+};
+/**
+* Duck-typed check that survives two repo-core copies in one dependency
+* graph, where `instanceof` silently fails across the boundary.
+*/
+function isVersionConflictError(err) {
+	return err instanceof VersionConflictError || typeof err === "object" && err !== null && err.name === "VersionConflictError" && err.code === "version_conflict";
+}
+//#endregion
+export { VersionConflictError, conservativeMongoIsTransientConflict, isVersionConflictError, neverTransient };

package/dist/errors/index.d.mts

@@ -1,6 +1,7 @@
+import { IsTransientConflictFn, VersionConflictError, conservativeMongoIsTransientConflict, isVersionConflictError, neverTransient } from "./conflict.mjs";
 import { DuplicateKeyMeta, ERROR_CODES, ErrorCode, ErrorContract, ErrorDetail, HttpError, ValidationErrorMeta } from "./types.mjs";
 import { statusToErrorCode, toErrorContract } from "./contract.mjs";
 import { createError, isHttpError } from "./create-error.mjs";
 import { IsDuplicateKeyErrorFn, ToDuplicateKeyHttpErrorOptions, conservativeMongoIsDuplicateKey, toDuplicateKeyHttpError } from "./duplicate-key.mjs";
 import { errorContractSchema, errorDetailSchema } from "./schema.mjs";
-export { type DuplicateKeyMeta, ERROR_CODES, type ErrorCode, type ErrorContract, type ErrorDetail, type HttpError, type IsDuplicateKeyErrorFn, type ToDuplicateKeyHttpErrorOptions, type ValidationErrorMeta, conservativeMongoIsDuplicateKey, createError, errorContractSchema, errorDetailSchema, isHttpError, statusToErrorCode, toDuplicateKeyHttpError, toErrorContract };
+export { type DuplicateKeyMeta, ERROR_CODES, type ErrorCode, type ErrorContract, type ErrorDetail, type HttpError, type IsDuplicateKeyErrorFn, type IsTransientConflictFn, type ToDuplicateKeyHttpErrorOptions, type ValidationErrorMeta, VersionConflictError, conservativeMongoIsDuplicateKey, conservativeMongoIsTransientConflict, createError, errorContractSchema, errorDetailSchema, isHttpError, isVersionConflictError, neverTransient, statusToErrorCode, toDuplicateKeyHttpError, toErrorContract };

package/dist/errors/index.mjs

@@ -1,6 +1,7 @@
+import { VersionConflictError, conservativeMongoIsTransientConflict, isVersionConflictError, neverTransient } from "./conflict.mjs";
 import { ERROR_CODES } from "./types.mjs";
 import { statusToErrorCode, toErrorContract } from "./contract.mjs";
 import { createError, isHttpError } from "./create-error.mjs";
 import { conservativeMongoIsDuplicateKey, toDuplicateKeyHttpError } from "./duplicate-key.mjs";
 import { errorContractSchema, errorDetailSchema } from "./schema.mjs";
-export { ERROR_CODES, conservativeMongoIsDuplicateKey, createError, errorContractSchema, errorDetailSchema, isHttpError, statusToErrorCode, toDuplicateKeyHttpError, toErrorContract };
+export { ERROR_CODES, VersionConflictError, conservativeMongoIsDuplicateKey, conservativeMongoIsTransientConflict, createError, errorContractSchema, errorDetailSchema, isHttpError, isVersionConflictError, neverTransient, statusToErrorCode, toDuplicateKeyHttpError, toErrorContract };

package/dist/lock/index.d.mts

@@ -65,6 +65,25 @@ interface LockAdapter {
    * single round-trip; a read-then-write split is racy.
    */
   tryAcquire(name: string, holderId: string, leaseMs: number): Promise<boolean> | boolean;
+  /**
+   * Optional FENCED acquire — same atomic semantics as `tryAcquire`, but a
+   * successful (or extended) acquisition returns a MONOTONIC token minted by
+   * the STORE. A process cannot fence itself: only the CAS authority can
+   * guarantee that a later holder's token is strictly greater, which is what
+   * lets downstream stores reject a stale ex-holder's writes after lease
+   * loss — the overlap that serialized renewal narrows but cannot close.
+   *
+   * Contract: token increases on every CHANGE of holder (extension by the
+   * same holder keeps its token); `null` = not acquired. Adapters that
+   * cannot mint monotonic tokens (pure-memory across restarts) omit this
+   * method — callers feature-detect, and the delivery-guarantees matrix
+   * documents which stores fence.
+   */
+  tryAcquireFenced?(name: string, holderId: string, leaseMs: number): Promise<{
+    token: number;
+  } | null> | {
+    token: number;
+  } | null;
   /**
    * Release the lock if held by `holderId`. Returns `true` on actual
    * release, `false` when the lock isn't held by this holder. Safe
@@ -91,6 +110,8 @@ interface LockState {
   expiresAt: Date;
   /** When the current holder first acquired (or last extended) the lock. */
   acquiredAt: Date;
+  /** Fencing token of the current holder, when the adapter fences. */
+  token?: number;
 }
 /** Adapter-construction options that every backend shares. */
 interface BaseLockAdapterOptions {

package/dist/lock/index.mjs

@@ -76,6 +76,7 @@ import { randomUUID } from "node:crypto";
 function createMemoryLockAdapter(options = {}) {
 	const { defaultLeaseMs = 3e4 } = options;
 	const store = /* @__PURE__ */ new Map();
+	const fenceSeq = /* @__PURE__ */ new Map();
 	function readLive(name, now) {
 		const entry = store.get(name);
 		if (!entry) return void 0;
@@ -87,16 +88,22 @@ function createMemoryLockAdapter(options = {}) {
 	}
 	return {
 		tryAcquire(name, holderId, leaseMs) {
+			return this.tryAcquireFenced?.(name, holderId, leaseMs) !== null;
+		},
+		tryAcquireFenced(name, holderId, leaseMs) {
 			const ms = leaseMs > 0 ? leaseMs : defaultLeaseMs;
 			const now = Date.now();
 			const live = readLive(name, now);
-			if (live && live.holder !== holderId) return false;
+			if (live && live.holder !== holderId) return null;
+			const token = live ? live.token : (fenceSeq.get(name) ?? 0) + 1;
+			if (!live) fenceSeq.set(name, token);
 			store.set(name, {
 				holder: holderId,
 				expiresAt: now + ms,
-				acquiredAt: live ? live.acquiredAt : now
+				acquiredAt: live ? live.acquiredAt : now,
+				token
 			});
-			return true;
+			return { token };
 		},
 		release(name, holderId) {
 			const live = readLive(name, Date.now());

package/dist/repository/capabilities.d.mts

@@ -102,12 +102,54 @@ interface AggregateOpsSupport {
 interface RepoCapabilities {
   /** `withTransaction(fn)` — D1 throws, standalone Mongo throws 263. */
   transactions: boolean;
+  /**
+   * `WriteOptions.ifVersion` CAS honored (stale version → thrown
+   * `VersionConflictError`, success increments the version). Kits without
+   * it throw on the option — see the `ifVersion` contract.
+   */
+  optimisticConcurrency?: boolean;
   /**
    * True if calling `withTransaction` inside another `withTransaction`
-   * callback is expected to work. Mongo's driver supports it via the
-   * same session; SQL drivers typically reject it.
+   * callback is expected to work — as observed on THIS repository, not on
+   * the underlying driver. A kit whose tx-bound repo throws on nested
+   * `withTransaction` declares `false` even when its driver would allow
+   * nesting on the raw session: the capability describes what a caller
+   * holding this object may do. Conformance asserts the two agree.
    */
   nestedTransactions: boolean;
+  /**
+   * WHO owns retry of a transaction aborted by a transient conflict.
+   *
+   * - `'managed'` — `withTransaction` retries internally (MongoDB's
+   *   convenient transaction API re-runs the callback on
+   *   `TransientTransactionError` / `UnknownTransactionCommitResult` for up
+   *   to 120s). The caller MUST invoke it exactly once.
+   * - `'caller'` — one attempt per call; an outer envelope
+   *   (`retryingTransaction`) owns the loop. Manual BEGIN/COMMIT kits.
+   *
+   * **Absent means `'managed'`** — i.e. `retryingTransaction` does not add a
+   * retry layer. Wrapping a self-retrying transaction multiplies the retry
+   * budget (5 outer attempts × a 120s inner window) and makes the callback's
+   * execution count unpredictable, which is the strictly worse failure: a
+   * missing retry surfaces a conflict as a 409, a nested one re-runs side
+   * effects an unbounded number of times. Same posture as
+   * {@link neverTransient} — silence means "don't".
+   *
+   * A kit exposing `withTransaction` MUST declare this (conformance checks).
+   */
+  transactionRetry?: 'managed' | 'caller';
+  /**
+   * This repository refuses writes — another component owns them and
+   * enforces invariants the table cannot express (Better Auth's identity
+   * collections, a SQL view, a read replica). Write methods throw
+   * `ReadOnlyRepositoryError`; hosts should refuse write ROUTES at boot
+   * rather than surfacing the wall on the first request.
+   *
+   * Absent means writable, so nothing changes for ordinary repositories.
+   * Set it via {@link asReadOnlyRepo} rather than by hand — the flag alone
+   * is a label, and a label is not a control.
+   */
+  readOnly?: boolean;
   /** `findOneAndUpdate` with upsert: true. */
   upsert: boolean;
   /** `isDuplicateKeyError(err)` classifier. */

package/dist/repository/index.d.mts

@@ -6,8 +6,10 @@ import { ArchiveOptions, ArchivePort, ArchiveProgress, ArchiveResult, ArchiveSin
 import { PLUGIN_ORDER_CONSTRAINTS, Plugin, PluginFunction, PluginType, validatePluginOrder } from "./plugin-types.mjs";
 import { RepositoryBase, RepositoryBaseOptions } from "./base.mjs";
 import { AggregateOpsSupport, RepoCapabilities } from "./capabilities.mjs";
-import { AggCacheOptions, AggDateBucket, AggDateBucketInterval, AggDateBucketUnit, AggExecutionHints, AggMeasure, AggPaginationRequest, AggRequest, AggResult, AggRow, AggTopN, AggTopNTies, BulkCreateResult, BulkWriteOperation, BulkWriteResult, ChangeEvent, ClaimTransition, ClaimVersionTransition, CursorOptions, DeleteManyResult, DeleteOptions, DeleteResult, FilterInput, FindAllOptions, FindOneAndUpdateOptions, InferDoc, KeysetAggPaginationResult, MinimalRepo, PaginationParams, QueryOptions, RepositorySession, StandardRepo, TenantPurgeOptions, TenantPurgeProgress, TenantPurgeResult, TenantPurgeStrategy, TransitionArgs, TransitionMachine, UpdateManyResult, WatchOptions, WriteOptions } from "./types.mjs";
+import { AggCacheOptions, AggDateBucket, AggDateBucketInterval, AggDateBucketUnit, AggExecutionHints, AggMeasure, AggPaginationRequest, AggRequest, AggResult, AggRow, AggTopN, AggTopNTies, BulkCreateResult, BulkWriteOperation, BulkWriteResult, ChangeEvent, ClaimTransition, ClaimVersionTransition, CursorOptions, DeleteManyResult, DeleteOptions, DeleteResult, FilterInput, FindAllOptions, FindOneAndUpdateOptions, InferDoc, KeysetAggPaginationResult, MinimalRepo, PaginationParams, QueryOptions, RepositorySession, StandardRepo, TenantPurgeOptions, TenantPurgeProgress, TenantPurgeResult, TenantPurgeStrategy, TransactionHandle, TransitionArgs, TransitionMachine, UpdateManyResult, WatchOptions, WriteOptions } from "./types.mjs";
 import { DistributionConfig, DistributionMissHandler, createDistributionGuard, filterReferencesKey } from "./distribution.mjs";
 import { STANDARD_REPO_OPTION_KEYS, StandardRepoOptionKey } from "./options.mjs";
 import { PurgePort, WritingPurgeStrategy, runChunkedPurge } from "./purge.mjs";
-export { type AggCacheOptions, type AggDateBucket, type AggDateBucketInterval, type AggDateBucketUnit, type AggExecutionHints, type AggMeasure, type AggPaginationRequest, type AggRequest, type AggResult, type AggRow, type AggTopN, type AggTopNTies, type AggregateOpsSupport, type ArchiveOptions, type ArchivePort, type ArchiveProgress, type ArchiveResult, type ArchiveSink, type BulkCreateResult, type BulkWriteOperation, type BulkWriteResult, type ChangeEvent, type ClaimTransition, type ClaimVersionTransition, type CursorOptions, type DeleteManyResult, type DeleteOptions, type DeleteResult, type DistributionConfig, type DistributionMissHandler, type FilterInput, type FindAllOptions, type FindOneAndUpdateOptions, type InferDoc, type KeysetAggPaginationResult, type LookupPopulateOptions, type LookupPopulateResult, type LookupRow, type LookupSpec, type MinimalRepo, PLUGIN_ORDER_CONSTRAINTS, type PaginationParams, type Plugin, type PluginFunction, type PluginType, type PurgePort, type QueryOptions, type RepoCapabilities, RepositoryBase, type RepositoryBaseOptions, type RepositorySession, type RetryPolicy, STANDARD_REPO_OPTION_KEYS, type StandardRepo, type StandardRepoOptionKey, type TenantPurgeOptions, type TenantPurgeProgress, type TenantPurgeResult, type TenantPurgeStrategy, type TransitionArgs, type TransitionMachine, type UpdateInput, type UpdateManyResult, type WatchOptions, type WriteOptions, type WritingPurgeStrategy, createDistributionGuard, filterReferencesKey, nestDottedKeys, nestDottedKeysAll, runChunkedArchive, runChunkedPurge, throwIfAborted, validatePluginOrder, withRetry };
+import { ReadOnlyRepoOptions, ReadOnlyRepositoryError, asReadOnlyRepo, isReadOnlyRepo } from "./read-only.mjs";
+import { RetryingTransactionOptions, retryingTransaction } from "./retrying-transaction.mjs";
+export { type AggCacheOptions, type AggDateBucket, type AggDateBucketInterval, type AggDateBucketUnit, type AggExecutionHints, type AggMeasure, type AggPaginationRequest, type AggRequest, type AggResult, type AggRow, type AggTopN, type AggTopNTies, type AggregateOpsSupport, type ArchiveOptions, type ArchivePort, type ArchiveProgress, type ArchiveResult, type ArchiveSink, type BulkCreateResult, type BulkWriteOperation, type BulkWriteResult, type ChangeEvent, type ClaimTransition, type ClaimVersionTransition, type CursorOptions, type DeleteManyResult, type DeleteOptions, type DeleteResult, type DistributionConfig, type DistributionMissHandler, type FilterInput, type FindAllOptions, type FindOneAndUpdateOptions, type InferDoc, type KeysetAggPaginationResult, type LookupPopulateOptions, type LookupPopulateResult, type LookupRow, type LookupSpec, type MinimalRepo, PLUGIN_ORDER_CONSTRAINTS, type PaginationParams, type Plugin, type PluginFunction, type PluginType, type PurgePort, type QueryOptions, type ReadOnlyRepoOptions, ReadOnlyRepositoryError, type RepoCapabilities, RepositoryBase, type RepositoryBaseOptions, type RepositorySession, type RetryPolicy, type RetryingTransactionOptions, STANDARD_REPO_OPTION_KEYS, type StandardRepo, type StandardRepoOptionKey, type TenantPurgeOptions, type TenantPurgeProgress, type TenantPurgeResult, type TenantPurgeStrategy, type TransactionHandle, type TransitionArgs, type TransitionMachine, type UpdateInput, type UpdateManyResult, type WatchOptions, type WriteOptions, type WritingPurgeStrategy, asReadOnlyRepo, createDistributionGuard, filterReferencesKey, isReadOnlyRepo, nestDottedKeys, nestDottedKeysAll, retryingTransaction, runChunkedArchive, runChunkedPurge, throwIfAborted, validatePluginOrder, withRetry };

package/dist/repository/index.mjs

@@ -6,4 +6,6 @@ import { RepositoryBase } from "./base.mjs";
 import { createDistributionGuard, filterReferencesKey } from "./distribution.mjs";
 import { STANDARD_REPO_OPTION_KEYS } from "./options.mjs";
 import { runChunkedPurge } from "./purge.mjs";
-export { PLUGIN_ORDER_CONSTRAINTS, RepositoryBase, STANDARD_REPO_OPTION_KEYS, createDistributionGuard, filterReferencesKey, nestDottedKeys, nestDottedKeysAll, runChunkedArchive, runChunkedPurge, throwIfAborted, validatePluginOrder, withRetry };
+import { ReadOnlyRepositoryError, asReadOnlyRepo, isReadOnlyRepo } from "./read-only.mjs";
+import { retryingTransaction } from "./retrying-transaction.mjs";
+export { PLUGIN_ORDER_CONSTRAINTS, ReadOnlyRepositoryError, RepositoryBase, STANDARD_REPO_OPTION_KEYS, asReadOnlyRepo, createDistributionGuard, filterReferencesKey, isReadOnlyRepo, nestDottedKeys, nestDottedKeysAll, retryingTransaction, runChunkedArchive, runChunkedPurge, throwIfAborted, validatePluginOrder, withRetry };

package/dist/repository/read-only.d.mts

@@ -0,0 +1,60 @@
+//#region src/repository/read-only.d.ts
+/**
+ * `asReadOnlyRepo` — seal a repository whose rows are owned by ANOTHER writer.
+ *
+ * ## The failure this exists to make impossible
+ *
+ * Some tables are projected into a repository for reading — pagination, query
+ * parser, filters, OpenAPI, permissions — while a different component owns
+ * their writes and enforces invariants the table itself cannot express.
+ * Better Auth's `user` / `session` / `account` / `member` collections are the
+ * canonical case: it hashes credentials, cascades org membership, revokes
+ * sessions, and fires plugin hooks on every mutation.
+ *
+ * A full read/write repository handed to a generic CRUD layer turns that into
+ * one config line away from disaster: `POST /users` writes a row Better Auth
+ * never saw, with no password hashing and no hooks. The overlay's docstring
+ * saying "read-side" is not a control.
+ *
+ * So the seal is structural. Write methods throw, and `capabilities.readOnly`
+ * is `true` so a host can refuse write ROUTES at boot instead of discovering
+ * the wall on the first request. Reads pass through untouched.
+ *
+ * ## Why a Proxy and not a hand-written wrapper
+ *
+ * The write surface is open-ended: kits contribute methods (`claim`,
+ * `applyTransition`, plugin-added helpers) that no fixed list here would
+ * cover, and a wrapper that forwarded unknown properties would leak exactly
+ * those. The Proxy inverts the default — a method is readable only if it is
+ * on the KNOWN-read list, so a kit's novel write method is sealed by default
+ * rather than by remembering to add it.
+ */
+interface ReadOnlyRepoOptions {
+  /**
+   * Who owns writes to these rows, and how a caller should perform them.
+   * Surfaces verbatim in the thrown error — a developer hitting the wall
+   * needs the alternative, not just the refusal.
+   *
+   * @example 'Better Auth owns writes to `user`; mutate via auth.api'
+   */
+  reason: string;
+}
+/** Error thrown when a write is attempted through a sealed repository. */
+declare class ReadOnlyRepositoryError extends Error {
+  /** The method that was refused. */
+  readonly method: string;
+  constructor(method: string, reason: string);
+}
+/**
+ * Wrap `repo` so every write throws {@link ReadOnlyRepositoryError} and
+ * `capabilities.readOnly` reports `true`.
+ *
+ * Reads are forwarded to the original (bound to it, so `this` stays correct
+ * for kits that use private state). The wrapper is transparent to type
+ * inference: it returns the same type it was given.
+ */
+declare function asReadOnlyRepo<TRepo extends object>(repo: TRepo, options: ReadOnlyRepoOptions): TRepo;
+/** True when a repository (or adapter repository) declares itself read-only. */
+declare function isReadOnlyRepo(repo: unknown): boolean;
+//#endregion
+export { ReadOnlyRepoOptions, ReadOnlyRepositoryError, asReadOnlyRepo, isReadOnlyRepo };

package/dist/repository/read-only.mjs

@@ -0,0 +1,80 @@
+//#region src/repository/read-only.ts
+/**
+* Methods that only READ. Everything else callable is refused — a novel
+* kit-contributed method is sealed until it is listed here deliberately.
+*/
+const READ_METHODS = /* @__PURE__ */ new Set([
+	"getAll",
+	"getById",
+	"getOne",
+	"getByQuery",
+	"getByIds",
+	"findAll",
+	"count",
+	"exists",
+	"distinct",
+	"aggregate",
+	"cursor",
+	"stream",
+	"watch",
+	"explain",
+	"getDeleted",
+	"isDuplicateKeyError",
+	"isTransientConflictError"
+]);
+/** Non-callable properties that pass through (introspection, not behaviour). */
+const PASSTHROUGH_PROPS = /* @__PURE__ */ new Set([
+	"idField",
+	"modelName",
+	"Model",
+	"model",
+	"db",
+	"tables",
+	"schema",
+	"name"
+]);
+/** Error thrown when a write is attempted through a sealed repository. */
+var ReadOnlyRepositoryError = class extends Error {
+	/** The method that was refused. */
+	method;
+	constructor(method, reason) {
+		super(`Repository is read-only: refused \`${method}()\`. ${reason}.`);
+		this.name = "ReadOnlyRepositoryError";
+		this.method = method;
+	}
+};
+/**
+* Wrap `repo` so every write throws {@link ReadOnlyRepositoryError} and
+* `capabilities.readOnly` reports `true`.
+*
+* Reads are forwarded to the original (bound to it, so `this` stays correct
+* for kits that use private state). The wrapper is transparent to type
+* inference: it returns the same type it was given.
+*/
+function asReadOnlyRepo(repo, options) {
+	return new Proxy(repo, {
+		get(target, prop, receiver) {
+			if (prop === "capabilities") return {
+				...Reflect.get(target, prop, receiver) ?? {},
+				readOnly: true
+			};
+			if (typeof prop === "symbol" || PASSTHROUGH_PROPS.has(prop)) return Reflect.get(target, prop, receiver);
+			const value = Reflect.get(target, prop, receiver);
+			if (typeof value !== "function") return value;
+			if (READ_METHODS.has(prop)) return value.bind(target);
+			return () => {
+				throw new ReadOnlyRepositoryError(prop, options.reason);
+			};
+		},
+		set(_target, prop) {
+			throw new ReadOnlyRepositoryError(String(prop), options.reason);
+		}
+	});
+}
+/** True when a repository (or adapter repository) declares itself read-only. */
+function isReadOnlyRepo(repo) {
+	if (!repo || typeof repo !== "object") return false;
+	return repo.capabilities?.readOnly === true;
+}
+//#endregion
+export { ReadOnlyRepositoryError, asReadOnlyRepo, isReadOnlyRepo };

package/dist/repository/resilience.d.mts

@@ -32,7 +32,21 @@ interface RetryPolicy {
   maxAttempts?: number;
   /** Base delay (ms) for exponential backoff. Default 100ms; doubles each attempt. */
   baseDelayMs?: number;
-  /** Decide whether a given error is transient. Default: retry every error. */
+  /** Ceiling for a single backoff delay. Default: uncapped. */
+  maxDelayMs?: number;
+  /**
+   * Full jitter: each delay is `random(0, computed)`. Default `false` for
+   * back-compat. Turn it ON for any policy shared by concurrent writers —
+   * synchronized deterministic backoff makes colliding transactions collide
+   * again on every attempt.
+   */
+  jitter?: boolean;
+  /**
+   * Decide whether a given error is transient. Default: retry every error —
+   * kept for back-compat, but UNSAFE as a shared default (it re-runs side
+   * effects on deterministic failures); pass an explicit predicate.
+   * `retryingTransaction` always does.
+   */
   shouldRetry?: (err: unknown, attempt: number) => boolean;
 }
 /**

package/dist/repository/resilience.mjs

@@ -1,5 +1,25 @@
 //#region src/repository/resilience.ts
 /**
+* Abortable sleep. A plain `setTimeout` promise holds the process through an
+* abort — a cancelled request would silently wait out its full backoff before
+* noticing. Listener is removed on the timer path so repeated retries don't
+* accumulate listeners on one long-lived signal.
+*/
+function sleep(ms, signal) {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) return reject(signal.reason);
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(signal?.reason);
+		};
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+/**
 * Run `fn` with exponential backoff when a policy is provided. Falls
 * through to a single attempt when `policy` is undefined — callers wrap
 * unconditionally and the no-policy path costs nothing.
@@ -21,7 +41,10 @@ async function withRetry(fn, policy, signal) {
 			lastErr = err;
 			if (attempt === maxAttempts - 1) break;
 			if (!shouldRetry(err, attempt + 1)) break;
-			await new Promise((r) => setTimeout(r, baseDelayMs * 2 ** attempt));
+			let delay = baseDelayMs * 2 ** attempt;
+			if (policy.maxDelayMs !== void 0) delay = Math.min(delay, policy.maxDelayMs);
+			if (policy.jitter) delay = Math.random() * delay;
+			await sleep(delay, signal);
 		}
 	}
 	throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));

package/dist/repository/retrying-transaction.d.mts

@@ -0,0 +1,48 @@
+import { StandardRepo, TransactionHandle } from "./types.mjs";
+import { IsTransientConflictFn } from "../errors/conflict.mjs";
+//#region src/repository/retrying-transaction.d.ts
+interface RetryingTransactionOptions {
+  /** Max attempts including the first. Default 5. */
+  maxAttempts?: number;
+  /** Base backoff (ms); exponential, FULL-jittered. Default 50. */
+  baseDelayMs?: number;
+  /** Backoff ceiling (ms). Default 2000. */
+  maxDelayMs?: number;
+  /**
+   * Conflict classifier. Default: the repository's own
+   * `isTransientConflictError`, else `neverTransient` — an unclassified
+   * error runs ONCE and surfaces, because re-running side effects on an
+   * unknown failure is the unsafe direction.
+   */
+  isTransient?: IsTransientConflictFn;
+  /**
+   * Override the repository's declared `capabilities.transactionRetry`.
+   *
+   * Escape hatch for a repository that cannot declare (a hand-written test
+   * double, a proxy that hides `capabilities`). Prefer fixing the
+   * declaration — an override that disagrees with the kit re-creates the
+   * double-retry this option exists to prevent.
+   */
+  retryOwner?: 'managed' | 'caller';
+  /** Abort between attempts (never mid-transaction). */
+  signal?: AbortSignal;
+  /** Observability tap: called before each re-run with the conflict. */
+  onRetry?: (err: unknown, attempt: number) => void;
+  /** Forwarded to `withTransaction` untouched. */
+  transactionOptions?: Record<string, unknown>;
+}
+/**
+ * Run `fn` inside `repo.withTransaction`, re-running on transient conflicts.
+ *
+ * Throws immediately (no retry) when the repository cannot provide
+ * transactions — a caller asking for transactional semantics on a backend
+ * that cannot deliver them is a wiring error to surface at the call site,
+ * not a mode to degrade through. Method presence alone is NOT the test: kits
+ * expose `withTransaction` unconditionally and fail at BEGIN, so a
+ * repository that publishes a capability descriptor is held to it
+ * (`transactions !== true` — which `'unknown'` deliberately reports, failing
+ * closed on an unconfirmed deployment).
+ */
+declare function retryingTransaction<TDoc, T>(repo: StandardRepo<TDoc>, fn: (txRepo: StandardRepo<TDoc>, uow?: TransactionHandle) => Promise<T>, options?: RetryingTransactionOptions): Promise<T>;
+//#endregion
+export { RetryingTransactionOptions, retryingTransaction };

package/dist/repository/retrying-transaction.mjs

@@ -0,0 +1,35 @@
+import { neverTransient } from "../errors/conflict.mjs";
+import { withRetry } from "./resilience.mjs";
+//#region src/repository/retrying-transaction.ts
+/**
+* Run `fn` inside `repo.withTransaction`, re-running on transient conflicts.
+*
+* Throws immediately (no retry) when the repository cannot provide
+* transactions — a caller asking for transactional semantics on a backend
+* that cannot deliver them is a wiring error to surface at the call site,
+* not a mode to degrade through. Method presence alone is NOT the test: kits
+* expose `withTransaction` unconditionally and fail at BEGIN, so a
+* repository that publishes a capability descriptor is held to it
+* (`transactions !== true` — which `'unknown'` deliberately reports, failing
+* closed on an unconfirmed deployment).
+*/
+async function retryingTransaction(repo, fn, options = {}) {
+	if (typeof repo.withTransaction !== "function") throw new Error("retryingTransaction requires repository.withTransaction — this backend does not provide transactions (capability `transactions: false`). Wire a transactional kit, or drop the transactional envelope for this resource.");
+	const capabilities = repo.capabilities;
+	if (capabilities && capabilities.transactions !== true) throw new Error(`retryingTransaction: repository.withTransaction exists but the repository declares \`transactions: ${String(capabilities.transactions)}\` — this deployment cannot run transactions (standalone MongoDB, D1, or an unconfirmed topology). Every call would fail at BEGIN. Wire a transactional deployment, or drop the transactional envelope.`);
+	const isTransient = options.isTransient ?? (typeof repo.isTransientConflictError === "function" ? repo.isTransientConflictError.bind(repo) : neverTransient);
+	if ((options.retryOwner ?? capabilities?.transactionRetry ?? "managed") === "managed") return repo.withTransaction(fn, options.transactionOptions);
+	return withRetry(() => repo.withTransaction(fn, options.transactionOptions), {
+		maxAttempts: options.maxAttempts ?? 5,
+		baseDelayMs: options.baseDelayMs ?? 50,
+		maxDelayMs: options.maxDelayMs ?? 2e3,
+		jitter: true,
+		shouldRetry: (err, attempt) => {
+			if (!isTransient(err)) return false;
+			options.onRetry?.(err, attempt);
+			return true;
+		}
+	}, options.signal);
+}
+//#endregion
+export { retryingTransaction };