@venizia/ignis-docs 0.2.0 → 0.2.1-1

package/content/references/base/repositories/advanced.md

@@ -1,27 +1,28 @@
 ---
 title: Advanced Repository Features
-description: Transactions, hidden properties, and performance optimization
+description: Transactions, row-level locking, hidden properties, performance, and safety guards
 difficulty: intermediate
 ---
 
 # Advanced Repository Features
 
-Transactions, hidden properties, performance optimization, type inference, and debugging.
+Everything beyond basic CRUD - transactions, row-level locking, hidden-property exclusion, performance tuning, return-type inference, debugging, and the built-in safety guards. For the common tasks, start with the [Repositories overview](/references/base/repositories/).
 
-## Prerequisites
+**Files:**
 
-Before reading this document, you should understand:
-
-- [Basic Repository Operations](./index.md) - CRUD operations and basic filtering
-- [Filter System](../filter-system/) - Advanced query building
-- Database transactions - ACID properties and isolation levels
-- TypeScript advanced types - Utility types and type inference
+- [`packages/core-server/src/base/repositories/core/abstract.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/base/repositories/core/abstract.ts) - engine-neutral `AbstractRepository`
+- [`packages/core-server/src/base/repositories/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/base/repositories/common/types.ts) - `IExtraOptions`, `TLockOptions`, `TCount`, `TDataRange`, `IReadRetryOptions`, `IWithReadRetry`, `TFindOptions`, `TFindOneOptions`, `TFindRangeOptions`, `TDataWithRange`
+- [`packages/helpers/src/utilities/retry.utility.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/utilities/retry.utility.ts) - `executeWithRetryUntil`, the engine behind `options.retry`
+- [`packages/core-server/src/connectors/postgres/repositories/core/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/connectors/postgres/repositories/core/base.ts) - `RelationalBaseRepository` - hidden-column exclusion, `buildQuery`, `resolveConnector`, lock validation
+- [`packages/core-server/src/connectors/postgres/repositories/core/readable.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/connectors/postgres/repositories/core/readable.ts) - `ReadableRelationalRepository` - Core API vs. Query API selection, `shouldQueryRange`
+- [`packages/core-server/src/connectors/postgres/repositories/core/persistable.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/connectors/postgres/repositories/core/persistable.ts) - `PersistableRelationalRepository` - create/update/delete, empty-where guard
+- [`packages/core-server/src/connectors/postgres/repositories/core/soft-deletable.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/connectors/postgres/repositories/core/soft-deletable.ts) - `SoftDeletableRelationalRepository`
+- [`packages/core-server/src/connectors/postgres/repositories/dialect/update.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/connectors/postgres/repositories/dialect/update.ts) - `UpdateBuilder` - nested JSON path updates
+- [`packages/core-server/src/connectors/postgres/datasources/abstract.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/connectors/postgres/datasources/abstract.ts) - `beginTransaction()`, isolation levels
 
 ## Transactions
 
-Orchestrate atomic operations across multiple repositories.
-
-### Basic Transaction
+Operations on separate repositories only become one atomic unit when they share a transaction handle. Start one and pass it to every call that must succeed or fail together:
 
 ```typescript
 const tx = await repository.beginTransaction();
@@ -30,66 +31,70 @@ try {
   // All operations use the same transaction
   const user = await userRepository.create({
     data: { name: 'Alice', email: 'alice@example.com' },
-    options: { transaction: tx }
+    options: { transaction: tx },
   });
 
   const profile = await profileRepository.create({
     data: { userId: user.data.id, bio: 'Hello!' },
-    options: { transaction: tx }
+    options: { transaction: tx },
   });
 
-  // Commit if all succeeded
   await tx.commit();
-
   return { user: user.data, profile: profile.data };
 } catch (error) {
-  // Rollback on any error
   await tx.rollback();
   throw error;
 }
 ```
 
-### Isolation Levels
+### The rules
 
-Control how transactions interact with concurrent operations:
+- `beginTransaction()` delegates to `dataSource.beginTransaction()`.
+- The returned `IDatabaseTransaction` exposes `isActive`, `commit()`, `rollback()`, `connector`, and `isolationLevel`.
+- Pass the same `tx` as `options.transaction` on every call that belongs to the unit of work.
+
+> [!WARNING] `rollback()` can throw
+> A failed `COMMIT` or `ROLLBACK` throws rather than resolving as success - a poisoned connection is destroyed rather than returned to the pool. Because `rollback()` can throw and is normally called from a `catch`, nest it in its own `try...catch` if the rollback error matters. A `rollback()` called after the transaction already failed is a silent no-op. The `catch { await tx.rollback(); throw error; }` pattern in the basic transaction example is always safe. See [DataSources - Full Reference](/references/base/datasources-reference#transaction-support) for the full commit/rollback lifecycle.
+
+### Isolation levels
+
+Pass `isolationLevel` to control how the transaction sees concurrent changes:
 
 ```typescript
+import { IsolationLevels } from '@venizia/ignis/postgres';
+
 const tx = await repository.beginTransaction({
-  isolationLevel: 'SERIALIZABLE'
+  isolationLevel: IsolationLevels.SERIALIZABLE,
 });
 ```
 
-| Level | Description | Use Case |
-|-------|-------------|----------|
-| `READ COMMITTED` | Default. See committed data only | Most applications |
-| `REPEATABLE READ` | Consistent reads within transaction | Reports, analytics |
-| `SERIALIZABLE` | Full isolation, prevents anomalies | Financial, inventory |
+| Level | SQL | Use case |
+|---|---|---|
+| `IsolationLevels.READ_COMMITTED` | `READ COMMITTED` | Default. Sees committed data only |
+| `IsolationLevels.REPEATABLE_READ` | `REPEATABLE READ` | Consistent reads within the transaction |
+| `IsolationLevels.SERIALIZABLE` | `SERIALIZABLE` | Full isolation, prevents anomalies |
+
+A plain string literal (`'SERIALIZABLE'`) works too - `isolationLevel` is typed `TIsolationLevel`, a string union the const class's values satisfy.
 
-### Transaction with Multiple Repositories
+### Raw SQL inside a transaction
+
+A transaction also covers Drizzle's `sql` template for atomic column updates:
 
 ```typescript
 async function transferFunds(fromId: string, toId: string, amount: number) {
   const tx = await accountRepository.beginTransaction();
 
   try {
-    // Debit source account
     await accountRepository.updateById({
       id: fromId,
       data: { balance: sql`balance - ${amount}` },
-      options: { transaction: tx }
+      options: { transaction: tx },
     });
 
-    // Credit destination account
     await accountRepository.updateById({
       id: toId,
       data: { balance: sql`balance + ${amount}` },
-      options: { transaction: tx }
-    });
-
-    // Record the transfer
-    await transferRepository.create({
-      data: { fromId, toId, amount, status: 'completed' },
-      options: { transaction: tx }
+      options: { transaction: tx },
     });
 
     await tx.commit();
@@ -100,14 +105,9 @@ async function transferFunds(fromId: string, toId: string, amount: number) {
 }
 ```
 
-
 ## Row-Level Locking
 
-Acquire pessimistic locks on selected rows within a transaction using PostgreSQL's `SELECT ... FOR UPDATE/SHARE` syntax.
-
-### Basic Usage
-
-Pass `lock` in options alongside a `transaction`:
+Acquire pessimistic locks on selected rows inside a transaction with PostgreSQL's `SELECT ... FOR UPDATE/SHARE`. Pass `lock` alongside `transaction`:
 
 ```typescript
 const tx = await repository.beginTransaction();
@@ -116,10 +116,7 @@ try {
   // Lock the row - other transactions will wait
   const item = await repository.findOne({
     filter: { where: { id: '123' } },
-    options: {
-      transaction: tx,
-      lock: { strength: 'update' },
-    },
+    options: { transaction: tx, lock: { strength: 'update' } },
   });
 
   // Safe to modify - no concurrent changes possible
@@ -136,86 +133,126 @@ try {
 }
 ```
 
-### Lock Strengths
+**Supported methods:** `find`, `findOne`, `findById` (delegates to `findOne`). Not `count`/`existsWith`.
+
+### Lock strengths
 
-Use the `LockStrengths` constant class or string literals:
+Use the `LockStrengths` const class or an equivalent string literal:
 
 ```typescript
 import { LockStrengths } from '@venizia/ignis';
 
-// Using constant
 lock: { strength: LockStrengths.UPDATE }
-
-// Using string literal
+// same as
 lock: { strength: 'update' }
 ```
 
-| Strength | SQL | Use Case |
-|----------|-----|----------|
+| Strength | SQL | Use case |
+|---|---|---|
 | `update` | `FOR UPDATE` | Exclusive lock for writes |
 | `no key update` | `FOR NO KEY UPDATE` | Exclusive lock, allows concurrent `FOR KEY SHARE` |
 | `share` | `FOR SHARE` | Shared read lock, prevents writes |
 | `key share` | `FOR KEY SHARE` | Weakest lock, only prevents key changes |
 
-### Wait Behavior
+### Wait behavior
 
-Control what happens when rows are already locked:
+Control what happens when a targeted row is already locked via `lock.config`:
 
 ```typescript
 // Skip locked rows (queue-style worker pattern)
 const items = await repository.find({
   filter: { where: { status: 'pending' }, limit: 10 },
-  options: {
-    transaction: tx,
-    lock: { strength: 'update', config: { skipLocked: true } },
-  },
+  options: { transaction: tx, lock: { strength: 'update', config: { skipLocked: true } } },
 });
 
 // Fail immediately instead of waiting
 const item = await repository.findOne({
   filter: { where: { id: '123' } },
-  options: {
-    transaction: tx,
-    lock: { strength: 'update', config: { noWait: true } },
-  },
+  options: { transaction: tx, lock: { strength: 'update', config: { noWait: true } } },
 });
 ```
 
 | Config | SQL | Behavior |
-|--------|-----|----------|
-| *(none)* | `FOR UPDATE` | Wait until lock is released |
-| `{ noWait: true }` | `FOR UPDATE NOWAIT` | Throw error immediately if locked |
+|---|---|---|
+| *(none)* | `FOR UPDATE` | Wait until the lock is released |
+| `{ noWait: true }` | `FOR UPDATE NOWAIT` | Throw immediately if locked |
 | `{ skipLocked: true }` | `FOR UPDATE SKIP LOCKED` | Silently skip locked rows |
 
-### Constraints
-
-> [!WARNING]
-> Row-level locking requires a **transaction** and is **incompatible with `include`/`fields`** in the filter (these use the Drizzle Query API which does not support `.for()`).
+`noWait` and `skipLocked` are mutually exclusive at the type level (`TLockConfig`).
+
+> [!WARNING] Requires a transaction, incompatible with `include`/`fields`
+> Row-level locking needs a transaction and cannot combine with `include`/`fields` in the filter - both force the Drizzle Query API, which has no `.for()`.
+>
+> ```typescript
+> // Error - no transaction
+> await repository.findOne({
+>   filter: { where: { id: '123' } },
+>   options: { lock: { strength: 'update' } },
+> });
+>
+> // Error - include forces the Query API
+> await repository.findOne({
+>   filter: { where: { id: '123' }, include: [{ relation: 'posts' }] },
+>   options: { transaction: tx, lock: { strength: 'update' } },
+> });
+> ```
+
+## Read Retry (Replica Lag)
+
+Behind a replicated pool (e.g. PgDog), a read right after a write can land on a replica that has not caught up. The row looks missing or stale. Pass `retry` to re-read until it is fresh:
 
 ```typescript
-// Error - no transaction
-await repository.findOne({
-  filter: { where: { id: '123' } },
-  options: { lock: { strength: 'update' } },
+// create -> read: default predicate ("result is non-null") is enough
+const user = await userRepository.findById({
+  id,
+  options: { retry: { maxAttempts: 4 } },
 });
 
-// Error - include uses Query API
-await repository.findOne({
-  filter: { where: { id: '123' }, include: [{ relation: 'posts' }] },
-  options: { transaction: tx, lock: { strength: 'update' } },
+// update -> read: tell retry what "fresh" means
+const order = await orderRepository.findById({
+  id,
+  options: { retry: { until: result => result?.status === 'PAID' } },
 });
 ```
 
-**Supported methods:** `find`, `findOne`, `findById`
+Works the same on PostgreSQL and search (Typesense, Meilisearch) repositories.
 
+### The rules
 
-## Hidden Properties
+- Retry happens only when the read succeeded but `until(result)` says "not yet".
+- A real database error is never retried. It throws immediately, same as without `retry`.
+- Out of attempts? You get the last result as-is. No new error.
+- Inside a transaction, retry is skipped - transactions already go to the primary. Locked reads (`lock`) require a transaction, so they never retry either.
+- On [`SoftDeletableRepository.findById`](/references/base/repositories/soft-deletable#findbyid-with-isstrict), `isStrict: true` is checked only after the attempts run out. A strict read waits out replica lag before it throws `404`.
+- Write verbs do not have this option. `retry` on a write is a compile error.
+
+### Options
+
+| Option | Type | Default | Meaning |
+|--------|------|---------|---------|
+| `maxAttempts` | `number` | `3` | Total reads, including the first. Below `1` throws. |
+| `until` | `(result) => boolean` | per verb (below) | Return `true` to stop: "fresh enough". |
+| `maxTotalMs` | `number` | unlimited | Stop starting new attempts after this much time. Never cuts a running read short. |
+| `backoff` | `IRetryBackoffOptions` | 50ms up to 500ms, jittered | Wait between attempts. Details: [Retry Utility](/references/utilities/retry). |
+| `signal` | `AbortSignal` | - | Cancel the loop. An abort rejects the call. |
 
-Automatically exclude sensitive fields from query results.
+`until` is typed per verb - the predicate sees exactly what the verb returns:
 
-### Configuration
+| Verb | `until` sees | Default: stops when |
+|---|---|---|
+| `findOne` / `findById` | `TNullable<R>` | result is not `null`/`undefined` |
+| `find` | `Array<R>` | array is non-empty |
+| `find` + `shouldQueryRange: true` | `{ data: R[]; range: ... }` | `data` is non-empty |
 
-Define hidden properties in your model:
+> [!WARNING] Empty is a normal answer for `find`
+> `find`'s default predicate is "array is non-empty". A `find` that legitimately matches nothing will burn all attempts before returning `[]`. Where "no results" is normal, pass your own `until` - or do not use `retry` there.
+
+> [!TIP]
+> `retry` runs on `executeWithRetryUntil` from `@venizia/ignis-helpers` - use it directly for any non-repository polling. See [Retry Utility](/references/utilities/retry).
+
+## Hidden Properties
+
+Fields like `password` must never leave the database by accident. Declare them once on the model and every read path drops them for you:
 
 ```typescript
 @model({
@@ -229,496 +266,335 @@ export class User extends BaseEntity<typeof User.schema> {
 }
 ```
 
-### Automatic Exclusion
-
-Hidden properties are excluded at the **SQL level** for maximum security:
-
 ```typescript
-// Read operations exclude hidden properties
 const user = await userRepository.findById({ id: '123' });
-// Result: { id: '123', email: 'john@example.com', name: 'John' }
-// Note: password, secret, apiKey are NOT included
-
-// Write operations exclude hidden from RETURNING clause
-const created = await userRepository.create({
-  data: { email: 'new@example.com', password: 'hashed_secret' }
-});
-// Result: { count: 1, data: { id: '456', email: 'new@example.com' } }
-// Note: password stored in DB but not returned
-```
-
-### Filtering by Hidden Properties
-
-You **can** filter by hidden properties - you just can't see them in results:
-
-```typescript
-// This works! Finds user but password not in result
-const user = await userRepository.findOne({
-  filter: { where: { password: 'hashed_value' } }
-});
+// { id: '123', email: 'john@example.com', name: 'John' } - no password, secret, apiKey
 ```
 
-### Relations with Hidden Properties
-
-Hidden properties are also excluded from included relations:
-
-```typescript
-const post = await postRepository.findOne({
-  filter: {
-    include: [{ relation: 'author' }]
-  }
-});
-// post.author will NOT include password, secret, etc.
-```
-
-### Accessing Hidden Data
-
-When you need hidden fields (e.g., for authentication), bypass the repository:
-
-```typescript
-// Direct connector access - includes all fields
-const connector = userRepository.getConnector();
-const [fullUser] = await connector
-  .select()
-  .from(User.schema)
-  .where(eq(User.schema.email, 'john@example.com'));
-// fullUser includes password, secret, apiKey
-```
+### The rules
 
+- Exclusion happens at the **SQL level** - hidden columns are never selected, not filtered out afterward.
+- Read operations exclude hidden properties from the result.
+- Write operations exclude hidden properties from the `RETURNING` clause - the value is still written, only not echoed back.
+- You **can** filter `where` on a hidden property; you still cannot see it in the result.
+- Hidden properties are also excluded from included relations - see [Relations & Includes](./relations#hidden-properties-in-relations).
+- Need a hidden field anyway (e.g. to verify a password hash)? Use `repository.connector` to bypass the exclusion - see [Direct Connector Access](#direct-connector-access).
 
 ## Performance Optimization
 
-### Core API for Flat Queries
+### Core API for flat queries
 
-The repository automatically uses Drizzle's Core API (faster) for simple queries:
+A query with no `include`/`fields` runs on Drizzle's Core API, which is faster than the Query API a relation forces:
 
 ```typescript
 // Automatically optimized - uses Core API
 const users = await repository.find({
-  filter: {
-    where: { status: 'active' },
-    limit: 10,
-    order: ['createdAt DESC']
-  }
+  filter: { where: { status: 'active' }, limit: 10, order: ['createdAt DESC'] },
 });
-// Uses: db.select().from(table).where(...).orderBy(...).limit(10)
+// db.select().from(table).where(...).orderBy(...).limit(10)
 
-// Uses Query API (has relations)
+// Has a relation - uses Query API
 const usersWithPosts = await repository.find({
-  filter: {
-    where: { status: 'active' },
-    include: [{ relation: 'posts' }]
-  }
+  filter: { where: { status: 'active' }, include: [{ relation: 'posts' }] },
 });
-// Uses: db.query.tableName.findMany({ with: { posts: true }, ... })
+// db.query.tableName.findMany({ with: { posts: true }, ... })
 ```
 
-| Filter Options | API Used | Performance |
-|----------------|----------|-------------|
+| Filter options | API used | Performance |
+|---|---|---|
 | `where`, `limit`, `order`, `offset`/`skip` only | Core API | ~15-20% faster |
 | Has `include` (relations) | Query API | Standard |
 | Has `fields` selection | Query API | Standard |
 
-### Always Use Limit
+### Always set a limit
 
-Prevent memory exhaustion on large tables:
+An unbounded `find` can return millions of rows:
 
 ```typescript
-// Good - bounded result set
-await repository.find({
-  filter: {
-    where: { status: 'active' },
-    limit: 100
-  }
-});
+// Bounded result set
+await repository.find({ filter: { where: { status: 'active' }, limit: 100 } });
 
-// Dangerous - could return millions of rows
-await repository.find({
-  filter: { where: { status: 'active' } }
-});
+// Dangerous - no limit in the filter
+await repository.find({ filter: { where: { status: 'active' } } });
 ```
 
 > [!NOTE]
-> `find()` always applies a default limit of `10` when no `limit` is set in the filter. Pass an explicit `limit` in the filter to override this default.
+> `find()` always applies a default limit when the filter has none. It uses the model's `@model({ settings: { defaultLimit } })` if declared, otherwise the global default of `10`. Pass an explicit `limit` to override either default. `findOne`/`findById` are unaffected - they force `limit: 1` on the Core API path regardless.
 
-### Pagination with Data Range
+### Pagination with data range
 
-Use `shouldQueryRange` to get both data and total count in a single call:
+Pass `shouldQueryRange` to get data and total count from a single call:
 
 ```typescript
 const result = await userRepository.find({
-  filter: {
-    where: { status: 'active' },
-    limit: 20,
-    skip: 40,
-    order: ['createdAt DESC']
-  },
-  options: { shouldQueryRange: true }
+  filter: { where: { status: 'active' }, limit: 20, skip: 40, order: ['createdAt DESC'] },
+  options: { shouldQueryRange: true },
 });
-
-// Result type: { data: User[], range: { start: number, end: number, total: number } }
-// range follows HTTP Content-Range standard (inclusive end index)
-// Example: { data: [...20 users], range: { start: 40, end: 59, total: 150 } }
+// { data: User[], range: { start: 40, end: 59, total: 150 } }
+// range follows the HTTP Content-Range standard (inclusive end index)
 ```
 
-This runs `find` and `count` in parallel via `Promise.all` for optimal performance. Inside a transaction the two queries run sequentially instead - a transaction connector wraps a single client, so parallel queries on it are not safe.
+- **Parallel by default.** `find` and `count` execute concurrently via `Promise.all`.
+- **Sequential inside a transaction.** A transaction connector wraps a single client, so parallel queries on it are not safe - the two queries run one after another instead.
 
-### WeakMap Cache
-
-The filter builder caches table column metadata, avoiding repeated reflection:
-
-```typescript
-// Internal optimization - automatic
-// First query: getTableColumns(schema) -> cached in WeakMap
-// Subsequent queries: retrieved from WeakMap cache
-```
+### WeakMap cache
 
+- **Column metadata is cached per schema.** The filter builder caches table column metadata (`getCachedColumns`) to avoid repeated reflection.
+- **Populated on first access.** The first access calls Drizzle's `getTableColumns()` and caches the result; later queries read the `WeakMap` instead.
+- **No configuration needed.** The cache is automatic.
 
 ## TypeScript Return Types
 
-### shouldReturn Inference
+### shouldReturn inference
 
-Repository methods infer return types based on `shouldReturn`:
+`shouldReturn` decides the result shape at the type level, no manual casting needed:
 
 ```typescript
 // shouldReturn: false - TypeScript knows data is null
 const result1 = await repository.create({
   data: { name: 'John' },
-  options: { shouldReturn: false }
+  options: { shouldReturn: false },
 });
-// Type: Promise<{ count: number; data: undefined | null }>
+// Promise<{ count: number; data: undefined | null }>
 
 // shouldReturn: true (default) - TypeScript knows data is the entity
-const result2 = await repository.create({
-  data: { name: 'John' },
-  options: { shouldReturn: true }
-});
-// Type: Promise<{ count: number; data: User }>
-console.log(result2.data.name); // 'John' - fully typed!
-
-// Array operations
-const results = await repository.createAll({
-  data: [{ name: 'John' }, { name: 'Jane' }],
-  options: { shouldReturn: true }
-});
-// Type: Promise<{ count: number; data: User[] }>
+const result2 = await repository.create({ data: { name: 'John' } });
+console.log(result2.data.name); // 'John' - fully typed
 ```
 
-### Generic Return Types
+The same inference applies to `createAll`, `updateById`, `updateAll`, `updateBy`, `deleteById`, `deleteAll`, `deleteBy`.
 
-Override return types for queries with relations:
+### Generic return types
+
+Pass a type argument to widen the result for a query with relations:
 
 ```typescript
-// Define expected return type
-type UserWithPosts = User & {
-  posts: Post[];
-};
+type UserWithPosts = User & { posts: Post[] };
 
-// Use generic override
 const user = await userRepository.findOne<UserWithPosts>({
-  filter: {
-    where: { id: '123' },
-    include: [{ relation: 'posts' }]
-  }
+  filter: { where: { id: '123' }, include: [{ relation: 'posts' }] },
 });
 
-// TypeScript knows the structure!
 if (user) {
   console.log(user.posts[0].title); // Fully typed
 }
 ```
 
-**Supported Methods:**
-- `find<R>()`, `findOne<R>()`, `findById<R>()`
-- `create<R>()`, `createAll<R>()`
-- `updateById<R>()`, `updateAll<R>()`, `updateBy<R>()`
-- `deleteById<R>()`, `deleteAll<R>()`, `deleteBy<R>()`
-
+**Supported on:** `find<R>()`, `findOne<R>()`, `findById<R>()`, `create<R>()`, `createAll<R>()`, `updateById<R>()`, `updateAll<R>()`, `updateBy<R>()`, `deleteById<R>()`, `deleteAll<R>()`, `deleteBy<R>()`.
 
 ## Debugging
 
-### Log Option
+### Log option
 
-Enable logging for specific operations:
+Pass `log` to trace a single operation without turning on logging globally:
 
 ```typescript
-// Enable debug logging
 await repository.create({
   data: { name: 'John', email: 'john@example.com' },
-  options: {
-    log: { use: true, level: 'debug' }
-  }
-});
-// Output: [_create] Executing with opts: { data: [...], options: {...} }
-
-// Available levels: 'debug', 'info', 'warn', 'error'
-await repository.updateById({
-  id: '123',
-  data: { name: 'Jane' },
-  options: { log: { use: true, level: 'info' } }
+  options: { log: { use: true, level: 'debug' } },
 });
+// [_create] Executing with opts: { data: [...], options: {...} }
 ```
 
-**Available on:** `create`, `createAll`, `updateById`, `updateAll`, `updateBy`, `deleteById`, `deleteAll`, `deleteBy` (all write operations that go through `_create`, `_update`, or `_delete` internal methods)
+| Level | Meaning |
+|---|---|
+| `debug` | Verbose - opts and intermediate state |
+| `info` | Default when `level` is omitted |
+| `warn` | Notable but non-fatal conditions |
+| `error` | Failure paths |
 
-### Query Interface Validation
+**Supported on:** `create`, `createAll`, `updateById`, `updateAll`, `updateBy`, `deleteById`, `deleteAll`, `deleteBy` - every write operation that goes through the internal `_create`, `_update`, or `_delete` methods.
 
-The repository validates schema registration on startup:
+### Query interface validation
 
-```typescript
-// If schema key doesn't match, you get a helpful error:
-// Error: [UserRepository] Schema key mismatch
-// | Entity name 'User' not found in connector.query
-// | Available keys: [Configuration, Post]
-// | Ensure the model's TABLE_NAME matches the schema registration key
-```
+The repository validates schema registration the first time it touches the Query API. A mismatch fails with a pointer to the problem instead of a raw Drizzle error:
 
+```
+Error: [UserRepository] Schema key mismatch
+| Entity name 'User' not found in connector.query
+| Available keys: [Configuration, Post]
+| Ensure the model's TABLE_NAME matches the schema registration key
+```
 
 ## Safety Features
 
-### Empty Where Protection
+### Empty where protection
 
-Prevents accidental mass updates/deletes:
+`updateAll`/`updateBy`/`deleteAll`/`deleteBy` refuse an empty `where` unless `force: true` is passed, to block accidental mass updates and deletes:
 
 ```typescript
-// Throws error - empty where without force
+// Throws - empty where without force
 await repository.deleteAll({ where: {} });
 
-// Explicit force flag - logs warning, proceeds
-await repository.deleteAll({
-  where: {},
-  options: { force: true }
-});
+// Explicit force - logs a warning, proceeds
+await repository.deleteAll({ where: {}, options: { force: true } });
 // Warning: [_delete] Entity: User | Performing delete with empty condition
 ```
 
 | Scenario | `force: false` (default) | `force: true` |
-|----------|-------------------------|---------------|
-| Empty `where` | Throws error | Logs warning, proceeds |
+|---|---|---|
+| Empty `where` | Throws | Logs a warning, proceeds |
 | Valid `where` | Executes normally | Executes normally |
 
 > [!NOTE]
-> This protection applies to `updateAll`, `updateBy`, `deleteAll`, and `deleteBy`. The `updateById` and `deleteById` methods always have a non-empty where (`{ id }`) so they are not affected.
+> `updateById` and `deleteById` always have a non-empty where (`{ id }`), so this guard never applies to them.
 
-### Transaction Safety
+### Transaction safety
 
-The `resolveConnector` method validates transaction state before use:
+`resolveConnector` validates transaction state before every use. A transaction already committed or rolled back fails fast instead of running against a dead connection:
 
-```typescript
-// If a transaction has already been committed or rolled back:
-// Error: [UserRepository][resolveConnector] Transaction is no longer active
 ```
-
+Error: [UserRepository][resolveConnector] Transaction is no longer active
+```
 
 ## Direct Connector Access
 
-For advanced queries not supported by the repository API:
+`repository.connector` is a getter (not a method) that resolves the datasource's Drizzle connector, for queries the repository API does not cover:
 
 ```typescript
-// Get the Drizzle connector
-const connector = repository.getConnector();
+const connector = repository.connector;
 
-// Raw Drizzle query
 const results = await connector
-  .select({
-    userId: userTable.id,
-    postCount: sql<number>`count(${postTable.id})`,
-  })
+  .select({ userId: userTable.id, postCount: sql<number>`count(${postTable.id})` })
   .from(userTable)
   .leftJoin(postTable, eq(userTable.id, postTable.authorId))
   .groupBy(userTable.id)
   .having(sql`count(${postTable.id}) > 5`);
-
-// Use with caution - bypasses repository features like hidden properties
 ```
 
+> [!WARNING]
+> Queries through `connector` bypass repository features - hidden-property exclusion included. Use it with intent, not as a default escape hatch.
 
 ## Repository Class Hierarchy
 
-| Class | Scope | Description |
-|-------|-------|-------------|
-| `AbstractRepository` | N/A | Engine-neutral abstract base (`src/base`), defines all method signatures, lazy `dataSource`/`entity` resolution. No mixin composition - plain `BaseHelper` subclass. |
-| `PostgresBaseRepository` | N/A | PostgreSQL connector base. Adds `FilterBuilder`, hidden-column exclusion (`getHiddenProperties`/`getVisibleProperties`), default-filter application (`getDefaultFilter`/`applyDefaultFilter`) - the behavior formerly provided by the now-removed `FieldsVisibilityMixin`/`DefaultFilterMixin` (see [Repository Mixins](./mixins.md)). |
-| `ReadableRepository` | `READ_ONLY` | Read-only operations (`find`, `findOne`, `findById`, `count`, `existsWith`). Write operations throw errors. |
-| `PersistableRepository` | `READ_WRITE` | Adds write operations (`create`, `update`, `delete`) with `UpdateBuilder` |
-| `DefaultCRUDRepository` | `READ_WRITE` | Extends `PersistableRepository` with no additional logic - **recommended default** |
-| `SoftDeletableRepository` | `READ_WRITE` | Extends `DefaultCRUDRepository` with soft delete + restore operations |
+The PostgreSQL connector's canonical names carry the engine in the class name. The historical `*Repository` names remain as compatibility aliases re-exporting the exact same classes.
 
-### Creating a Read-Only Repository
+| Canonical class | Alias | Scope | Description |
+|---|---|---|---|
+| `AbstractRepository` | - | N/A | Engine-neutral abstract base (`src/base`), defines every method signature, lazy `dataSource`/`entity` resolution. Plain `BaseHelper` subclass, no mixin composition. |
+| `RelationalBaseRepository` | `PostgresBaseRepository` | N/A | PostgreSQL connector base. Adds `FilterBuilder`/`UpdateBuilder`, hidden-column exclusion (`getHiddenProperties`/`getVisibleProperties`), default-filter application (`getDefaultFilter`/`applyDefaultFilter`) - the behavior formerly provided by the now-removed `FieldsVisibilityMixin`/`DefaultFilterMixin` (see [Repository Mixins](./mixins)). |
+| `ReadableRelationalRepository` | `ReadableRepository` | `READ_ONLY` | Read-only operations (`find`, `findOne`, `findById`, `count`, `existsWith`). Write operations throw. |
+| `PersistableRelationalRepository` | `PersistableRepository` | `READ_WRITE` | Adds write operations (`create`, `update`, `delete`) with `UpdateBuilder`. |
+| `DefaultRelationalRepository` | `DefaultCRUDRepository` | `READ_WRITE` | Extends `PersistableRelationalRepository` with no additional logic - **recommended default**. |
+| `SoftDeletableRelationalRepository` | `SoftDeletableRepository` | `READ_WRITE` | Extends `DefaultRelationalRepository` with soft delete and restore - see [SoftDeletableRepository](./soft-deletable). |
+
+Code samples throughout the docs use the alias names (`DefaultCRUDRepository`, `ReadableRepository`), since that is what `@venizia/ignis/postgres` code most commonly imports today.
 
 ```typescript
 @repository({ model: AuditLog, dataSource: PostgresDataSource })
 export class AuditLogRepository extends ReadableRepository<typeof AuditLog.schema> {
   // Only has: find, findOne, findById, count, existsWith
-  // Write operations throw "NOT ALLOWED" error
+  // Write operations throw a "NOT ALLOWED" error
 }
 ```
 
-### Alias Methods
-
-`AbstractRepository` provides two alias methods for convenience:
+### Alias methods
 
-- `updateBy(opts)` - Alias for `updateAll(opts)`. Delegates directly.
-- `deleteBy(opts)` - Alias for `deleteAll(opts)`. Delegates directly.
-
-Both accept the same parameters (`where`, `data`/`options`) and support `shouldReturn` and `force` options.
+`AbstractRepository` provides two alias methods for convenience, both delegating directly and supporting the same `shouldReturn`/`force` options:
 
+- `updateBy(opts)` - alias for `updateAll(opts)`.
+- `deleteBy(opts)` - alias for `deleteAll(opts)`.
 
 ## Default Filter Bypass
 
-When models have a `defaultFilter` configured, you can bypass it for admin/maintenance operations:
+A model's `defaultFilter` (e.g. soft-delete's `isDeleted = false`) applies to every query unless you opt out for an admin or maintenance path:
 
 ```typescript
 // Normal query - default filter applies
-await repository.find({
-  filter: { where: { status: 'active' } }
-});
-// WHERE isDeleted = false AND status = 'active' (if model has soft-delete default)
+await repository.find({ filter: { where: { status: 'active' } } });
+// WHERE isDeleted = false AND status = 'active' (if the model has a soft-delete default)
 
-// Admin query - bypass default filter
+// Admin query - bypass the default filter
 await repository.find({
   filter: { where: { status: 'active' } },
-  options: { shouldSkipDefaultFilter: true }
+  options: { shouldSkipDefaultFilter: true },
 });
 // WHERE status = 'active' (includes deleted records)
 ```
 
-**Supported on all operations:**
+**Supported on every operation:**
 
 ```typescript
-// Read operations
 await repository.find({ filter, options: { shouldSkipDefaultFilter: true } });
 await repository.findOne({ filter, options: { shouldSkipDefaultFilter: true } });
 await repository.count({ where, options: { shouldSkipDefaultFilter: true } });
-
-// Write operations
 await repository.updateAll({ where, data, options: { shouldSkipDefaultFilter: true } });
 await repository.deleteAll({ where, options: { shouldSkipDefaultFilter: true, force: true } });
 ```
 
-**Combined with transactions:**
-
-```typescript
-const tx = await repository.beginTransaction();
-await repository.updateAll({
-  where: { status: 'archived' },
-  data: { isDeleted: true },
-  options: {
-    transaction: tx,
-    shouldSkipDefaultFilter: true
-  }
-});
-await tx.commit();
-```
-
 > [!TIP]
-> See [Default Filter](../filter-system/default-filter.md) for full documentation on configuring model default filters.
-
+> Combine it with a transaction for an atomic admin operation:
+> ```typescript
+> const tx = await repository.beginTransaction();
+> await repository.updateAll({
+>   where: { status: 'archived' },
+>   data: { isDeleted: true },
+>   options: { transaction: tx, shouldSkipDefaultFilter: true },
+> });
+> await tx.commit();
+> ```
+> See [Default Filter](../filter-system/default-filter) for configuring model default filters.
 
 ## Nested JSON Updates
 
-Repositories support updating specific fields within `json` or `jsonb` columns without overwriting the entire object. This is achieved using **JSON Path Notation** in the update data via the `UpdateBuilder`.
-
-### Basic Usage
-
-Use dot notation keys to target nested properties:
+`json`/`jsonb` columns update in place with dot-notation keys - `UpdateBuilder` compiles them into chained `jsonb_set` calls instead of overwriting the whole column:
 
 ```typescript
-// Assume 'metadata' is a JSONB column
-// Current value: { theme: 'light', notifications: { email: true } }
-
+// 'metadata' is a jsonb column: { theme: 'light', notifications: { email: true } }
 await repository.updateById({
   id: '123',
   data: {
-    // Update only the theme, preserving other fields
-    'metadata.theme': 'dark'
-  }
-});
-
-// New value: { theme: 'dark', notifications: { email: true } }
-```
-
-### Supported Features
-
-- **Deep Nesting:** Update properties at any depth (e.g., `settings.display.font.size`).
-- **Array Access:** Update array elements by index (e.g., `tags[0]`).
-- **Auto-Creation:** Creates missing intermediate keys automatically (`jsonb_set` with `create_missing = true`).
-- **Type Safety:** Validates that the target column is a JSON/JSONB type.
-- **Multiple Updates:** Multiple updates to the same column are chained as nested `jsonb_set` calls.
-- **Mixed Updates:** Combine regular column updates with JSON path updates in a single call.
-
-### Examples
-
-#### Deeply Nested Updates
-
-```typescript
-await repository.updateById({
-  id: '123',
-  data: {
-    'metadata.settings.display.fontSize': 16,
-    'metadata.settings.display.showSidebar': true
-  }
+    status: 'active',                    // regular column
+    'metadata.theme': 'dark',            // JSON path, any depth
+    'metadata.addresses[0].primary': true, // array element by index
+  },
 });
+// metadata becomes: { theme: 'dark', notifications: { email: true }, addresses: [{ primary: true }, ...] }
 ```
 
-#### Array Element Updates
+### The rules
 
-```typescript
-await repository.updateById({
-  id: '123',
-  data: {
-    // Set the first address as primary
-    'metadata.addresses[0].primary': true
-  }
-});
-```
+- **Deep nesting:** target a property at any depth (`settings.display.font.size`).
+- **Array access:** update an array element by index (`tags[0]`).
+- **Auto-creation:** missing intermediate keys are created automatically (`jsonb_set` with `create_missing = true`).
+- **Type safety:** the target column must be `json`/`jsonb`. Any other column type throws.
+- **Multiple paths on one column:** chained as nested `jsonb_set` calls in a single statement.
+- **Mixed updates:** regular columns and JSON paths combine in the same `data` object, as in the basic usage example.
 
-#### Mixed Updates (Regular + JSON)
+### Security and validation
 
-You can mix regular column updates with JSON path updates:
-
-```typescript
-await repository.updateById({
-  id: '123',
-  data: {
-    status: 'active',           // Regular column
-    'metadata.lastLogin': now,  // JSON path
-    'preferences.lang': 'en'   // Another JSON path
-  }
-});
-```
-
-### Security & Validation
-
-The framework validates JSON paths to prevent SQL injection:
-- **Allowed Characters:** Path components must match `/^[a-zA-Z_][a-zA-Z0-9_-]*$|^\d+$/` (identifiers, kebab-case, or array indices).
-- **Column Type Validation:** Only `json` and `jsonb` columns are allowed. Other column types throw an error.
-- **Values:** Values are serialized to JSONB literals with proper escaping.
+- **Allowed characters:** each path component must match `/^[a-zA-Z_][a-zA-Z0-9_-]*$|^\d+$/` (identifiers, kebab-case, or array indices) - this is what blocks SQL injection through a path.
+- **Column type validation:** only `json` and `jsonb` columns are allowed.
+- **Values:** serialized to JSONB literals with proper escaping.
 
 > [!NOTE]
-> This feature uses PostgreSQL's `jsonb_set` function. It is only available for columns defined as `json` or `jsonb`.
-
+> This feature uses PostgreSQL's `jsonb_set` function and only applies to columns defined as `json` or `jsonb`.
 
 ## ExtraOptions Reference
 
-All repository operations accept an `options` parameter with these fields:
+Every repository operation accepts an `options` parameter (`IExtraOptions`, narrowed by postgres to `IDatabaseExtraOptions`):
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `transaction` | `ITransaction` | - | Transaction context for the operation |
+| `transaction` | `IDatabaseTransaction` | - | Transaction context for the operation |
 | `log` | `{ use: boolean; level?: TLogLevel }` | - | Enable operation logging |
 | `shouldSkipDefaultFilter` | `boolean` | `false` | Bypass the default filter from model settings |
 | `lock` | `TLockOptions` | - | Row-level locking (requires transaction, Core API only) |
 
+Read operations (`find`, `findOne`, `findById`) additionally support:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `retry` | `IReadRetryOptions` | - | Re-read with backoff until a predicate passes - see [Read Retry](#read-retry-replica-lag). Skipped inside a transaction. Not accepted by write operations. |
+
 Write operations additionally support:
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `shouldReturn` | `boolean` | `true` | Return the created/updated/deleted data |
-| `force` | `boolean` | `false` | Allow empty `where` condition on bulk operations |
+| `force` | `boolean` | `false` | Allow an empty `where` condition on bulk operations |
 | `shouldQueryRange` | `boolean` | `false` | Return `{ data, range }` with total count (find only) |
 
-
 ## Quick Reference
 
 | Feature | Code |
@@ -730,36 +606,22 @@ Write operations additionally support:
 | Bypass default filter | `options: { shouldSkipDefaultFilter: true }` |
 | Lock rows for update | `options: { transaction: tx, lock: { strength: 'update' } }` |
 | Lock + skip locked | `options: { transaction: tx, lock: { strength: 'update', config: { skipLocked: true } } }` |
+| Retry a read until fresh | `options: { retry: { until: result => result?.status === 'PAID' } }` |
 | Enable logging | `options: { log: { use: true, level: 'debug' } }` |
 | Force delete all | `options: { force: true }` |
 | Skip returning data | `options: { shouldReturn: false }` |
 | Get data + count | `options: { shouldQueryRange: true }` |
-| Access connector | `repository.getConnector()` |
-
-
-## Next Steps
-
-- [Overview](./index.md) - Repository basics
-- [Filter System](../filter-system/) - Query operators
-- [Default Filter](../filter-system/default-filter.md) - Automatic filter configuration
-- [Repository Mixins (Removed)](./mixins.md) - Where mixin behavior lives now
-- [Relations & Includes](./relations.md) - Eager loading
-- [Soft-Deletable Repository](./soft-deletable.md) - Soft delete operations
-- [JSON Path Filtering](../filter-system/json-filtering) - JSONB queries
-- [Array Operators](../filter-system/array-operators) - PostgreSQL arrays
-
-## See Also
-
-- **Related Concepts:**
-  - [Repositories Overview](./index) - Core repository operations
-  - [Transactions](/guides/core-concepts/persistent/transactions) - Transaction guide
-  - [DataSources](/guides/core-concepts/persistent/datasources) - Database connections
-
-- **Related Topics:**
-  - [Repository Mixins (Removed)](./mixins) - Where mixin behavior lives now
-  - [Relations & Includes](./relations) - Loading related data
-  - [Filter System](/references/base/filter-system/) - Query operators
-
-- **Best Practices:**
-  - [Performance Optimization](/best-practices/performance-optimization) - Query optimization
-  - [Data Modeling](/best-practices/data-modeling) - Repository patterns
+| Access connector | `repository.connector` |
+
+## See also
+
+- [Repositories overview](/references/base/repositories/) - CRUD basics, common tasks
+- [Relations & Includes](./relations) - eager loading, nested `scope` filters, many-to-many
+- [SoftDeletableRepository](./soft-deletable) - soft delete, restore, hard delete
+- [Repository Mixins (Removed)](./mixins) - where `FieldsVisibilityMixin`/`DefaultFilterMixin` behavior lives now
+- [Filter System](/references/base/filter-system/) - every `where` operator, JSON paths, array operators
+- [Default Filter](/references/base/filter-system/default-filter) - automatic filter configuration
+- [DataSources - Full Reference](/references/base/datasources-reference) - transaction internals, isolation levels, driver seam
+- [Transactions guide](/guides/core-concepts/persistent/transactions) - multi-operation database transactions
+- [Retry Utility](/references/utilities/retry) - `executeWithRetry`/`executeWithRetryUntil`, backoff strategies, jitter modes
+- [Search & Typesense - Repository Tiers](/guides/core-concepts/persistent/search-typesense#repository-tiers) - `retry` on the search chain