@venizia/ignis-docs 0.2.1-0 → 0.2.1-1

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

@@ -6,22 +6,12 @@ difficulty: intermediate
 
 # Relations & Includes
 
-Exhaustive reference for declaring `one`/`many` relations on a model and eager-loading them via `include` - one-to-one, one-to-many, and many-to-many. For the common tasks, start with the [Repositories overview](/references/base/repositories/).
+Declare `one`/`many` relations on a model, then eager-load them with `include` on any `find`/`findOne` call - one-to-one, one-to-many, and many-to-many. For CRUD basics, start with the [Repositories overview](/references/base/repositories/).
 
-**Files:**
-
-- [`packages/core/src/base/repositories/query-schemas/filter.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/repositories/query-schemas/filter.ts) - `TFilter`, `TInclusion`
-- [`packages/core/src/base/repositories/common/constants.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/repositories/common/constants.ts) - `RelationTypes`
-- [`packages/core/src/connectors/postgres/repositories/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/postgres/repositories/common/types.ts) - `TRelationConfig`
-- [`packages/core/src/connectors/postgres/repositories/dialect/filter.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/postgres/repositories/dialect/filter.ts) - `FilterBuilder` (`resolveRelations`, `toInclude`)
-- [`packages/core/src/connectors/postgres/repositories/dialect/relation.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/postgres/repositories/dialect/relation.ts) - `createRelations` (config -> Drizzle `relations()`)
-
-## Basic Include
-
-### One-to-many: user with posts
+## In one example
 
 ```typescript
-// Fetch user with their posts
+// Fetch a user with their posts
 const user = await userRepository.findOne({
   filter: {
     where: { id: '123' },
@@ -40,84 +30,133 @@ const user = await userRepository.findOne({
 // }
 ```
 
-### One-to-one: post with author
+> [!NOTE]
+> An `include` in the filter routes the query through Drizzle's Query API (`connector.query`) instead of the Core API. The `canUseCoreAPI` check in `ReadableRelationalRepository` makes that choice automatically. Core API is ~15-20% faster but skips relations and field selection. See [Performance Optimization](./advanced#performance-optimization).
 
-```typescript
-// Fetch post with its author
-const post = await postRepository.findOne({
-  filter: {
-    where: { id: 'p1' },
-    include: [{ relation: 'author' }],
-  },
-});
+## `TInclusion` options
 
-// Result:
-// {
-//   id: 'p1',
-//   title: 'First Post',
-//   authorId: '123',
-//   author: { id: '123', name: 'John', email: 'john@example.com' }
-// }
-```
+Each element of the `include` array accepts:
+
+| Option | Type | Default | Meaning |
+|---|---|---|---|
+| `relation` | `string` | required | Name of the relation to include, matching an entry in the model's `relations` array |
+| `scope` | `TFilter` | none | Nested filter on the related rows - `where`, `order`, `limit`, `fields`, `include` |
+| `shouldSkipDefaultFilter` | `boolean` | `false` | Skip the related model's default filter for this inclusion only |
+
+`scope` takes the same shape as a top-level filter - see the [Filter System](/references/base/filter-system/) reference for every `where` operator.
 
-### Multiple relations
+## Declaring relations on a model
+
+Relations are declared as a static `relations` resolver on the model, returning an array of `TRelationConfig`. `MetadataRegistry` resolves the array during schema discovery and passes it to `createRelations`. `createRelations` builds the actual Drizzle `relations()` definition - application code never calls it directly.
 
 ```typescript
-// Fetch post with author AND comments
-const post = await postRepository.findOne({
-  filter: {
-    where: { id: 'p1' },
-    include: [{ relation: 'author' }, { relation: 'comments' }],
-  },
-});
+// src/models/user.model.ts
+import { model, RelationTypes } from '@venizia/ignis';
+import { BaseEntity, TRelationConfig } from '@venizia/ignis/postgres';
+import { pgTable, text } from 'drizzle-orm/pg-core';
+import { Post } from './post.model';
+
+@model({ type: 'entity' })
+export class User extends BaseEntity<typeof User.schema> {
+  static override schema = pgTable('User', {
+    id: text('id').primaryKey(),
+    name: text('name').notNull(),
+    email: text('email').notNull(),
+  });
+
+  static override relations = (): TRelationConfig[] => [
+    {
+      name: 'posts',
+      type: RelationTypes.MANY,
+      schema: Post.schema,
+      metadata: { relationName: 'posts' },
+    },
+  ];
+}
 ```
 
-> [!NOTE]
-> When `include` is present in the filter, the repository uses the **Query API** (`connector.query`) instead of the Core API. This is handled automatically by the `canUseCoreAPI` check in `ReadableRelationalRepository` - see [Performance Optimization](./advanced#performance-optimization).
+Write the resolver as an arrow function (`() => [...]`), not a plain array. IGNIS defers evaluation until every `@model` class has registered, which avoids circular-import ordering issues between related models.
+
+### `TRelationConfig` fields
 
-## Scoped Includes
+| Field | Type | Meaning |
+|---|---|---|
+| `name` | `string` | Relation name used in `include` |
+| `type` | `RelationTypes.ONE` \| `RelationTypes.MANY` | Which Drizzle relation helper to build |
+| `schema` | `TTableSchemaWithId` | The related model's Drizzle table schema |
+| `metadata` | inferred from Drizzle's `one()`/`many()` params | `{ fields, references, relationName? }` for `ONE`; `{ relationName? }` for `MANY` |
 
-Apply filters, ordering, and limits to included relations using `scope` (itself a `TFilter`).
+`metadata`'s shape comes straight from Drizzle's own `one()`/`many()` parameter types, not a hand-duplicated one.
 
-### Filter related data
+### Relation types
+
+| Type | Drizzle function | Description | Example |
+|---|---|---|---|
+| `RelationTypes.ONE` (`'one'`) | `one()` | One-to-one or many-to-one | Post has one Author, User has one Profile |
+| `RelationTypes.MANY` (`'many'`) | `many()` | One-to-many | User has many Posts |
+
+> [!NOTE]
+> LoopBack 4 names these `hasMany`/`hasOne`/`belongsTo`. IGNIS uses Drizzle ORM's relation model instead, which has only `one` and `many`. A "belongsTo" relationship is `type: RelationTypes.ONE` with `fields` (the local foreign key) and `references` (the remote primary key) in `metadata`.
+
+### A model with both types
+
+This mirrors `examples/vert`'s `SaleChannelProduct` junction model: one `ONE` relation per foreign key, plus a `MANY` relation elsewhere.
 
 ```typescript
-// User with only published posts
-const user = await userRepository.findOne({
-  filter: {
-    where: { id: '123' },
-    include: [{ relation: 'posts', scope: { where: { status: 'published' } } }],
-  },
-});
+@model({ type: 'entity' })
+export class Post extends BaseEntity<typeof Post.schema> {
+  static override schema = postTable;
+
+  static override relations = (): TRelationConfig[] => [
+    {
+      name: 'author',
+      type: RelationTypes.ONE,
+      schema: User.schema,
+      metadata: {
+        fields: [Post.schema.authorId],
+        references: [User.schema.id],
+      },
+    },
+    {
+      name: 'comments',
+      type: RelationTypes.MANY,
+      schema: Comment.schema,
+      metadata: { relationName: 'comments' },
+    },
+  ];
+}
 ```
 
-### Order related data
+### Auto-resolution in the repository
+
+The repository never receives relations through its constructor. `MetadataRegistry` resolves them from the entity's static `relations` property. `FilterBuilder.resolveRelations()` reads and caches the result in a `WeakMap` the first time an include query needs them.
 
 ```typescript
-// User with posts ordered by date
-const user = await userRepository.findOne({
-  filter: {
-    where: { id: '123' },
-    include: [{ relation: 'posts', scope: { order: ['createdAt DESC'] } }],
-  },
-});
+@repository({ model: User, dataSource: PostgresDataSource })
+export class UserRepository extends DefaultCRUDRepository<typeof User.schema> {
+  // Relations auto-resolved from User.relations!
+}
 ```
 
-### Limit related data
+## Recipes
+
+### Include multiple relations
 
 ```typescript
-// User with their 5 most recent posts
-const user = await userRepository.findOne({
+const post = await postRepository.findOne({
   filter: {
-    where: { id: '123' },
-    include: [{ relation: 'posts', scope: { order: ['createdAt DESC'], limit: 5 } }],
+    where: { id: 'p1' },
+    include: [{ relation: 'author' }, { relation: 'comments' }],
   },
 });
 ```
 
-### Combined scope options
+### Filter, order, and limit included rows
+
+Combine `where`, `order`, `limit`, and `fields` inside `scope` the same way you would on a top-level filter:
 
 ```typescript
+// User with their 5 most recent published posts, id and title only
 const user = await userRepository.findOne({
   filter: {
     where: { id: '123' },
@@ -126,7 +165,7 @@ const user = await userRepository.findOne({
       scope: {
         where: { status: 'published' },
         order: ['createdAt DESC'],
-        limit: 10,
+        limit: 5,
         fields: ['id', 'title', 'createdAt'],
       },
     }],
@@ -134,7 +173,7 @@ const user = await userRepository.findOne({
 });
 ```
 
-### Skip default filter on includes
+### Skip the default filter on one inclusion
 
 Each inclusion can independently bypass the related model's default filter:
 
@@ -148,11 +187,9 @@ const user = await userRepository.findOne({
 });
 ```
 
-## Nested Includes
-
-Include relations of relations by nesting `include` inside `scope` (2 levels recommended, see [Performance Tips](#performance-tips)).
+### Nest includes two levels deep
 
-### Two-level nesting
+Put an `include` inside a `scope` to load a relation of a relation:
 
 ```typescript
 // User -> Posts -> Comments
@@ -165,27 +202,14 @@ const user = await userRepository.findOne({
     }],
   },
 });
-
-// Result:
-// {
-//   id: '123',
-//   name: 'John',
-//   posts: [
-//     {
-//       id: 'p1',
-//       title: 'First Post',
-//       comments: [
-//         { id: 'c1', text: 'Great post!' },
-//         { id: 'c2', text: 'Thanks for sharing' }
-//       ]
-//     }
-//   ]
-// }
 ```
 
-### Many-to-many through junction
+> [!WARNING] Performance
+> Each nested `include` adds SQL complexity. **Maximum 2 levels recommended.** For deeper relationships, run multiple queries instead - see [Performance Tips](#performance-tips).
+
+### Many-to-many through a junction table
 
-This is the pattern `examples/vert` uses for `Product` <-> `SaleChannel` through the `SaleChannelProduct` junction table:
+This is the pattern `examples/vert` uses for `Product` <-> `SaleChannel` through the `SaleChannelProduct` junction table. Include the junction relation, then nest the far side inside its `scope`.
 
 ```typescript
 // Product -> SaleChannelProduct (junction) -> SaleChannel
@@ -204,158 +228,44 @@ const product = await productRepository.findOne({
 //   id: 'prod1',
 //   name: 'Widget',
 //   saleChannelProducts: [
-//     {
-//       productId: 'prod1',
-//       saleChannelId: 'ch1',
-//       saleChannel: { id: 'ch1', name: 'Online Store' }
-//     },
-//     {
-//       productId: 'prod1',
-//       saleChannelId: 'ch2',
-//       saleChannel: { id: 'ch2', name: 'Retail' }
-//     }
+//     { productId: 'prod1', saleChannelId: 'ch1', saleChannel: { id: 'ch1', name: 'Online Store' } },
+//     { productId: 'prod1', saleChannelId: 'ch2', saleChannel: { id: 'ch2', name: 'Retail' } }
 //   ]
 // }
 ```
 
-> [!WARNING] Performance
-> Each nested `include` adds SQL complexity. **Maximum 2 levels recommended.** For deeper relationships, use multiple queries - see [Performance Tips](#performance-tips).
-
-## Defining Relations
-
-Relations are declared on the model as a static `relations` resolver returning an array of `TRelationConfig`. The framework translates them to Drizzle ORM relations internally during schema discovery.
-
-### Relation config type
-
-```typescript
-type TRelationConfig = {
-  name: string; // Relation name used in includes
-} & (
-  | {
-      type: 'one';   // one-to-one or many-to-one
-      schema: TTableSchemaWithId;
-      metadata: { fields, references, relationName? }; // Drizzle one() params
-    }
-  | {
-      type: 'many';  // one-to-many
-      schema: TTableSchemaWithId;
-      metadata: { relationName? };                      // Drizzle many() params
-    }
-);
-```
-
-`metadata`'s shape is inferred directly from Drizzle's own `one()`/`many()` relation-helper parameter types, not hand-duplicated.
+### Count relations without fetching them fully
 
-### In your model
+Fetch only `id` on the related rows to keep the payload small, then count the array client-side:
 
 ```typescript
-// src/models/user.model.ts
-import { model, RelationTypes } from '@venizia/ignis';
-import { BaseEntity, TRelationConfig } from '@venizia/ignis/postgres';
-import { pgTable, text } from 'drizzle-orm/pg-core';
-import { Post } from './post.model';
-
-@model({ type: 'entity' })
-export class User extends BaseEntity<typeof User.schema> {
-  static override schema = pgTable('User', {
-    id: text('id').primaryKey(),
-    name: text('name').notNull(),
-    email: text('email').notNull(),
-  });
+const users = await userRepository.find({
+  filter: {
+    include: [{ relation: 'posts', scope: { fields: ['id'] } }],
+  },
+});
 
-  static override relations = (): TRelationConfig[] => [
-    {
-      name: 'posts',
-      type: RelationTypes.MANY,
-      schema: Post.schema,
-      metadata: { relationName: 'posts' },
-    },
-  ];
-}
+const usersWithCounts = users.map(user => ({
+  ...user,
+  postCount: (user as any).posts?.length ?? 0,
+}));
 ```
 
-The resolver form (`() => [...]`) defers evaluation until all `@model` classes are registered, avoiding circular-import ordering issues between related models.
-
-### Relation types
-
-| Type | Drizzle function | Description | Example |
-|------|------------------|-------------|---------|
-| `RelationTypes.ONE` (`'one'`) | `one()` | One-to-one or many-to-one | Post has one Author, User has one Profile |
-| `RelationTypes.MANY` (`'many'`) | `many()` | One-to-many | User has many Posts |
-
-> [!NOTE]
-> Unlike LoopBack 4's `hasMany`/`hasOne`/`belongsTo` terminology, IGNIS uses Drizzle ORM's relation model, which has only `one` and `many` types. A "belongsTo" relationship is expressed as `type: RelationTypes.ONE` with `fields` (local FK) and `references` (remote PK) in `metadata`.
-
-### Example: model with both types
-
-This mirrors `examples/vert`'s `SaleChannelProduct` junction model - one `ONE` relation per foreign key, plus a `MANY` relation elsewhere:
+### Include conditionally
 
 ```typescript
-@model({ type: 'entity' })
-export class Post extends BaseEntity<typeof Post.schema> {
-  static override schema = postTable;
-
-  static override relations = (): TRelationConfig[] => [
-    {
-      name: 'author',
-      type: RelationTypes.ONE,
-      schema: User.schema,
-      metadata: {
-        fields: [Post.schema.authorId],
-        references: [User.schema.id],
-      },
-    },
-    {
-      name: 'comments',
-      type: RelationTypes.MANY,
-      schema: Comment.schema,
-      metadata: { relationName: 'comments' },
-    },
-  ];
-}
-```
-
-### How configs become Drizzle relations
-
-- **`MetadataRegistry` resolves the configs.** During schema discovery, it resolves each model's `relations` array and passes it to the `createRelations` helper ([`packages/core/src/connectors/postgres/repositories/dialect/relation.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/postgres/repositories/dialect/relation.ts)).
-- **`createRelations` builds the Drizzle definition.** It produces the actual Drizzle `relations()` definition, registered on the DataSource schema.
-- **Application code never calls it.** `createRelations` is internal - you only declare the `relations` resolver on the model.
-
-## Auto-Resolution
-
-- **Resolved from the model, not the constructor.** Relations are automatically resolved from the entity's static `relations` property via `MetadataRegistry` - no need to pass them in the repository constructor.
-- **Memoized per schema.** `FilterBuilder.resolveRelations()` reads and caches them in a `WeakMap` when building include queries.
+async function getUser(id: string, includePosts: boolean) {
+  const include = includePosts ? [{ relation: 'posts' }] : [];
 
-```typescript
-@repository({ model: User, dataSource: PostgresDataSource })
-export class UserRepository extends DefaultCRUDRepository<typeof User.schema> {
-  // Relations auto-resolved from User.relations!
+  return userRepository.findOne({
+    filter: { where: { id }, include },
+  });
 }
 ```
 
-## Hidden Properties in Relations
-
-When building include queries, `FilterBuilder.toInclude()` automatically:
-
-1. Resolves hidden properties for each related model via `resolveHiddenProperties()`.
-2. Resolves the default filter for each related model via `resolveDefaultFilter()` (unless `shouldSkipDefaultFilter` is set on that inclusion).
-3. Merges the default filter with any user-provided `scope` via `mergeFilter()`.
-4. Excludes hidden columns from the nested query's `columns` selection.
-
-```typescript
-// User model has hiddenProperties: ['password']
-const post = await postRepository.findOne({
-  filter: { include: [{ relation: 'author' }] },
-});
-
-// post.author will NOT include password - excluded at SQL level
-```
-
-See [Hidden Properties](./advanced#hidden-properties) for the top-level equivalent.
-
-## Type Safety with Generics
+### Type included results with a generic
 
-For queries with `include`, use generic type overrides for full type safety:
+`findOne`/`find` accept a type argument for the shape `include` produces, so the result is fully typed instead of falling back to the base entity:
 
 ```typescript
 type UserWithPosts = User & {
@@ -374,7 +284,7 @@ if (user) {
 }
 ```
 
-### Nested relations type
+The same pattern nests for a two-level include:
 
 ```typescript
 type ProductWithChannels = Product & {
@@ -396,86 +306,35 @@ const product = await productRepository.findOne<ProductWithChannels>({
 product?.saleChannelProducts[0].saleChannel.name; // Fully typed access
 ```
 
-## TInclusion Type Reference
-
-Each element in the `include` array has this shape:
-
-```typescript
-type TInclusion = {
-  relation: string;                    // Name of the relation to include
-  scope?: TFilter;                     // Optional nested filter (where, order, limit, fields, include)
-  shouldSkipDefaultFilter?: boolean;   // Skip the related model's default filter
-};
-```
-
-## Common Patterns
-
-### Find all with count of relations
-
-```typescript
-// Get users with post count
-const users = await userRepository.find({
-  filter: {
-    include: [{ relation: 'posts', scope: { fields: ['id'] } }], // Only fetch IDs to minimize data
-  },
-});
-
-const usersWithCounts = users.map(user => ({
-  ...user,
-  postCount: (user as any).posts?.length ?? 0,
-}));
-```
-
-### Conditional include
-
-```typescript
-async function getUser(id: string, includePosts: boolean) {
-  const include = includePosts ? [{ relation: 'posts' }] : [];
-
-  return userRepository.findOne({
-    filter: { where: { id }, include },
-  });
-}
-```
-
-## Error Handling
+## Hidden properties in relations
 
-### Relation not found
-
-If you try to include a relation that doesn't exist:
+`FilterBuilder.toInclude()` excludes hidden columns from every included relation at the SQL level, the same way the top-level query does. For each inclusion it resolves the related model's `hiddenProperties` and default filter, and merges the default filter with your `scope` via `mergeFilter()`. It then drops hidden columns from the nested `columns` selection.
 
 ```typescript
-// Error: [FilterBuilder][toInclude] Relation NOT FOUND | relation: 'nonExistent'
-await userRepository.find({
-  filter: { include: [{ relation: 'nonExistent' }] },
+// User model has hiddenProperties: ['password']
+const post = await postRepository.findOne({
+  filter: { include: [{ relation: 'author' }] },
 });
-```
-
-**Fix:** check your model's `relations` definition and ensure the relation name matches.
 
-### Invalid include format
-
-```typescript
-// Error: [FilterBuilder][toInclude] Invalid include format | include: ...
+// post.author will NOT include password - excluded at SQL level
 ```
 
-**Fix:** ensure each include element has a `relation` string property.
-
-### Schema key mismatch
+See [Hidden Properties](./advanced#hidden-properties) for the top-level equivalent.
 
-```
-Error: [UserRepository] Schema key mismatch | Entity name 'User' not found
-in connector.query | Available keys: [Post, Comment]
-```
+## Errors
 
-**Fix:** ensure your model's `TABLE_NAME` matches the schema registration - see [Query Interface Validation](./advanced#query-interface-validation).
+| Error | Cause | Fix |
+|---|---|---|
+| `[FilterBuilder][toInclude] Relation NOT FOUND \| relation: 'x'` | `include` names a relation absent from the model's `relations` array | Check the model's `relations` definition and match the name exactly |
+| `[FilterBuilder][toInclude] Invalid include format \| include: ...` | An `include` element has no `relation` string | Give every include element a `relation` field |
+| `[<Repository>] Schema key mismatch \| Entity name 'X' not found in connector.query` | The model's `TABLE_NAME` doesn't match its schema registration | See [Query Interface Validation](./advanced#query-interface-validation) |
 
-## Performance Tips
+## Performance tips
 
 1. **Limit nesting depth** - max 2 levels recommended.
-2. **Use `fields` in scope** - only fetch needed columns.
+2. **Use `fields` in scope** - fetch only the columns you need.
 3. **Use `limit` in scope** - don't fetch unbounded related data.
-4. **Consider separate queries** - for complex data needs, multiple simple queries often outperform one complex nested query.
+4. **Consider separate queries** - for complex data needs, several simple queries often outperform one deeply nested one.
 5. **Use `shouldSkipDefaultFilter` sparingly** - only when you explicitly need filtered-out records.
 
 ```typescript
@@ -489,10 +348,10 @@ const comments = await commentRepository.find({
 });
 ```
 
-## Quick Reference
+## Quick reference
 
 | Want to... | Code |
-|------------|------|
+|---|---|
 | Include one relation | `include: [{ relation: 'posts' }]` |
 | Include multiple | `include: [{ relation: 'posts' }, { relation: 'profile' }]` |
 | Filter included | `include: [{ relation: 'posts', scope: { where: { status: 'active' } } }]` |
@@ -510,3 +369,11 @@ const comments = await commentRepository.find({
 - [Filter System](/references/base/filter-system/) - every `where` operator, ordering, pagination
 - [Models - Full Reference](/references/base/models-reference) - `@model`, entity hierarchy, schema enrichers
 - [Drizzle ORM Relations](https://orm.drizzle.team/docs/rqb#relations) - relation definition guide
+
+**Files:**
+
+- [`packages/filter/src/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/filter/src/common/types.ts) - `TFilter`, `TInclusion`
+- [`packages/core-server/src/base/repositories/common/constants.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/base/repositories/common/constants.ts) - `RelationTypes`
+- [`packages/core-server/src/connectors/postgres/repositories/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/connectors/postgres/repositories/common/types.ts) - `TRelationConfig`
+- [`packages/core-server/src/connectors/relational/repositories/dialect/filter.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/connectors/relational/repositories/dialect/filter.ts) - `FilterBuilder` (`resolveRelations`, `toInclude`)
+- [`packages/core-server/src/connectors/postgres/repositories/dialect/relation.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/connectors/postgres/repositories/dialect/relation.ts) - `createRelations` (config -> Drizzle `relations()`)

package/content/references/base/repositories/soft-deletable.md

@@ -10,9 +10,9 @@ Reference for `SoftDeletableRepository` - delete methods set a `deletedAt` times
 
 **Files:**
 
-- [`packages/core/src/connectors/postgres/repositories/core/soft-deletable.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/postgres/repositories/core/soft-deletable.ts) - `SoftDeletableRelationalRepository` - delete/restore overrides, `isStrict` findById
-- [`packages/core/src/connectors/postgres/repositories/core/index.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/postgres/repositories/core/index.ts) - compatibility alias `SoftDeletableRepository`
-- [`packages/core/src/connectors/postgres/models/enrichers/tz.enricher.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/postgres/models/enrichers/tz.enricher.ts) - `generateTzColumnDefs` - adds the `deletedAt` column
+- [`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` - delete/restore overrides, `isStrict` findById
+- [`packages/core-server/src/connectors/postgres/repositories/core/index.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/connectors/postgres/repositories/core/index.ts) - compatibility alias `SoftDeletableRepository`
+- [`packages/core-server/src/connectors/postgres/models/enrichers/tz.enricher.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/connectors/postgres/models/enrichers/tz.enricher.ts) - `generateTzColumnDefs` - adds the `deletedAt` column
 
 ## Setup
 
@@ -91,7 +91,7 @@ const result = await repository.deleteById({
 
 ### deleteAll
 
-`where` only needs `options.force: true` when it is empty - a non-empty condition never needs it.
+`where` only needs `options.force: true` when `where` is empty - a non-empty condition never needs `force`.
 
 ```typescript
 // Soft delete matching records - non-empty where, no force needed
@@ -132,7 +132,7 @@ const result = await repository.deleteBy({
 ## Restore Operations
 
 - **Restore clears the timestamp.** Restore methods set `deletedAt = null`.
-- **Default filter is bypassed automatically.** They internally pass `shouldSkipDefaultFilter: true` so they can find the soft-deleted records the default filter would otherwise hide - you do not need to set this yourself.
+- **Default filter is bypassed automatically.** Restore methods internally pass `shouldSkipDefaultFilter: true`, so they can find the soft-deleted records the default filter would otherwise hide. You don't need to set this yourself.
 
 ### restoreById
 
@@ -189,8 +189,18 @@ const category = await repository.findById({
 // Throws: [CategoryRepository][findById] Entity with id 123 not found (HTTP 404)
 ```
 
+- **`isStrict` is the only thing the override adds.** Every other `findById` option - `retry`, `transaction`, `log`, `shouldSkipDefaultFilter`, `lock` - behaves exactly as on `DefaultCRUDRepository`. So does the `filter` argument.
 - **Everything else is inherited unchanged.** `find`, `findOne`, `count`, `existsWith` behave exactly as on `DefaultCRUDRepository`.
-- **The default filter excludes soft-deleted rows.** `{ deletedAt: null }` is applied automatically - pass `options: { shouldSkipDefaultFilter: true }` to include them.
+- **The default filter excludes soft-deleted rows.** IGNIS applies `{ deletedAt: null }` automatically - pass `options: { shouldSkipDefaultFilter: true }` to include them.
+
+You can combine `isStrict` with [read retry](/references/base/repositories/advanced#read-retry-replica-lag). The retry loop runs first, so a strict read waits out replica lag before it throws:
+
+```typescript
+const category = await repository.findById({
+  id: '123',
+  options: { retry: { maxAttempts: 4 }, isStrict: true },
+});
+```
 
 ## Options Reference