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

package/content/references/base/datasources-reference.md

@@ -10,12 +10,12 @@ Exhaustive reference for `IDataSource`, `AbstractDataSource`, the PostgreSQL con
 
 **Files:**
 
-- [`packages/core/src/base/datasources/abstract.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/datasources/abstract.ts) - neutral `AbstractDataSource`
-- [`packages/core/src/base/datasources/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/datasources/common/types.ts) - `IDataSource`, `DataSourceDrivers`, neutral transaction types
-- [`packages/core/src/connectors/postgres/datasources/abstract.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/postgres/datasources/abstract.ts) - `AbstractPostgresDataSource`
-- [`packages/core/src/connectors/postgres/datasources/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/postgres/datasources/base.ts) - `BasePostgresDataSource`
-- [`packages/core/src/connectors/postgres/datasources/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/postgres/datasources/common/types.ts) - PostgreSQL connector types, `IsolationLevels`
-- [`packages/core/src/connectors/postgres/drivers`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/postgres/drivers) - `IRelationalDriver`, `NodePostgresDriver`, `PostgresJsDriver`
+- [`packages/core-server/src/base/datasources/abstract.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/base/datasources/abstract.ts) - neutral `AbstractDataSource`
+- [`packages/core-server/src/base/datasources/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/base/datasources/common/types.ts) - `IDataSource`, `DataSourceDrivers`, neutral transaction types
+- [`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) - `AbstractPostgresDataSource`
+- [`packages/core-server/src/connectors/postgres/datasources/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/connectors/postgres/datasources/base.ts) - `BasePostgresDataSource`
+- [`packages/core-server/src/connectors/postgres/datasources/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/connectors/postgres/datasources/common/types.ts) - PostgreSQL connector types, `IsolationLevels`
+- [`packages/core-server/src/connectors/postgres/drivers`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/connectors/postgres/drivers) - `IRelationalDriver`, `NodePostgresDriver`, `PostgresJsDriver`
 
 > [!IMPORTANT] Base vs. connectors
 > - **Split.** Engine-neutral root at `src/base/datasources/`; per-engine connectors at `src/connectors/{postgres,typesense}/datasources/`.
@@ -39,7 +39,7 @@ Exhaustive reference for `IDataSource`, `AbstractDataSource`, the PostgreSQL con
 
 Engine-neutral contract implemented by every datasource in the framework, regardless of engine.
 
-`Source ->` [`packages/core/src/base/datasources/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/datasources/common/types.ts)
+`Source ->` [`packages/core-server/src/base/datasources/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/base/datasources/common/types.ts)
 
 ```typescript
 interface IDataSource<
@@ -82,7 +82,7 @@ interface IDataSource<
 
 Top-level abstract class extended by every engine. Extends `BaseHelper` for scoped logging. Contains **no SQL, no Drizzle, and no connection-pool members** - those are added by each connector.
 
-`Source ->` [`packages/core/src/base/datasources/abstract.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/datasources/abstract.ts)
+`Source ->` [`packages/core-server/src/base/datasources/abstract.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/base/datasources/abstract.ts)
 
 ```typescript
 abstract class AbstractDataSource<
@@ -104,7 +104,7 @@ abstract class AbstractDataSource<
 
 | Method | Return type | Description |
 |---|---|---|
-| `configure(opts?)` | `ValueOrPromise<void>` | Initialize the underlying connection. This is the **only** abstract member of the neutral root - `getConnectionString()` is not part of it; it is declared one level down, on `AbstractPostgresDataSource` (see below) |
+| `configure(opts?)` | `ValueOrPromise<void>` | Initialize the underlying connection. This is the **only** abstract member of the neutral root. `getConnectionString()` is not part of it - it is declared one level down, on `AbstractPostgresDataSource` (see below) |
 
 **Concrete methods** (defaults, overridable by connectors):
 
@@ -123,7 +123,7 @@ abstract class AbstractDataSource<
 | `discoverDefinitions({ read, kind })` | Walks the bound model classes, reads a connector-specific artifact via `read`, and returns a name-keyed registry. Skips undefined reads, throws on duplicate names, honors `autoDiscovery: false`. Shared plumbing every connector's own `discoverSchema()`-equivalent builds on |
 
 > [!NOTE] NotSupported convention
-> Every capability an engine does not implement - transactions, row-level locking - uses the same `throwNotSupported` utility ([`packages/core/src/utilities/error.utility.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/utilities/error.utility.ts)), producing a consistent `501 Not Implemented` whose `normalized.code` resolves to `'core.not_supported'`. This is how the typesense connector signals "not applicable to this engine" instead of silently no-op-ing.
+> Every capability an engine does not implement - transactions, row-level locking - uses the same `throwNotSupported` utility ([`packages/core-server/src/utilities/error.utility.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/utilities/error.utility.ts)). It produces a consistent `501 Not Implemented` whose `normalized.code` resolves to `'core.not_supported'`. This is how the typesense connector signals "not applicable to this engine" instead of silently no-op-ing.
 
 ### `IDataSourceCapabilities`
 
@@ -137,7 +137,7 @@ Only `BasePostgresDataSource` overrides `getCapabilities()` to return `{ transac
 
 ## PostgreSQL connector: `AbstractPostgresDataSource` and `BasePostgresDataSource`
 
-`Source ->` [`packages/core/src/connectors/postgres/datasources/abstract.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/postgres/datasources/abstract.ts), [`packages/core/src/connectors/postgres/datasources/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/postgres/datasources/base.ts)
+`Source ->` [`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), [`packages/core-server/src/connectors/postgres/datasources/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/connectors/postgres/datasources/base.ts)
 
 ### `AbstractPostgresDataSource`
 
@@ -176,20 +176,20 @@ The fourth generic, `Client = Pool`, is what lets a postgres-js datasource decla
 |---|---|---|
 | `getConnector()` | `TRelationalConnector<Schema>` | Wires the driver on first use (via `wireDriverFromMetadata()`), then returns `this.connector` |
 | `getClient()` | `Client` | Raw driver client escape hatch - `pg.Pool` for node-postgres, `Sql` for postgres-js. Reads `this.driver.getClient()` if a driver is resolved, else `this.client` directly. Throws if neither is set |
-| `getQueryDialect()` | `IRelationalQueryDialect` | Returns a shared, lazily-constructed `FilterBuilder` instance (static, one per process) |
-| `onSecretRotated(opts)` | `Promise<void>` | Applies rotated credentials to `this.settings`, rebuilds the driver/connector/client against a fresh pool, calls `this.configure()` and `this.resolveDriver()`, then drains the old pool once the new one is in place. See [Secrets & Vault](/guides/core-concepts/secrets-vault) |
+| `getQueryDialect()` | `IRelationalQueryDialect` | Returns a shared, lazily-constructed `PostgresQueryDialect` instance (static, one per process) |
+| `onSecretRotated(opts)` | `Promise<void>` | Applies rotated credentials to `this.settings` and rebuilds the driver/connector/client against a fresh pool. Calls `this.configure()` and `this.resolveDriver()`, then drains the old pool once the new one is in place. See [Secrets & Vault](/guides/core-concepts/secrets-vault) |
 
 **Protected methods:**
 
 | Method | Description |
 |---|---|
-| `wireDriverFromMetadata()` | Idempotent, lazy. If `this.connector` already exists, no-ops. If `this.driver` exists but `this.connector` does not, builds the connector from it. Otherwise reads the class named in `@datasource({ driver })` from `MetadataRegistry`, instantiates it over `this.client`, and calls `useDriver()`. Throws if neither `client` nor `driver` is set, or if the named `driver` metadata is not a class (a string, historically valid for search engines, is rejected here with a message pointing at `NodePostgresDriver`) |
+| `wireDriverFromMetadata()` | Idempotent, lazy. If `this.connector` already exists, no-ops. If `this.driver` exists but `this.connector` does not, builds the connector from it. Otherwise reads the class named in `@datasource({ driver })` from `MetadataRegistry`, instantiates it over `this.client`, and calls `useDriver()`. Throws if neither `client` nor `driver` is set. It also throws if the named `driver` metadata is not a class. A string, historically valid for search engines, is rejected here with a message pointing at `NodePostgresDriver` |
 | `resolveDriver()` | Calls `wireDriverFromMetadata()`, then returns `this.driver` |
 | `useDriver({ driver, schema? })` | Assigns `this.driver` **and** builds `this.connector` from it in one step - the two-step form (driver set, connector forgotten) is unrepresentable. `schema` defaults to `getSchema()`. The public escape hatch for a custom or third-party driver, bypassing `@datasource({ driver })` entirely |
 | `mapSecretToSettings({ secret })` | Maps Vault's `{ username, password }` secret shape to `pg`'s `{ user, password }` settings shape, for `onSecretRotated()` |
 
 > [!NOTE] Driver seam
-> - **Class, not a string.** `@datasource({ driver })` names the driver **class** (`NodePostgresDriver` or `PostgresJsDriver`) - a driver-name string cannot carry `pg`/`postgres` into the app's bundle, only a real class reference can.
+> - **Class, not a string.** `@datasource({ driver })` names the driver **class** (`NodePostgresDriver` or `PostgresJsDriver`). A driver-name string cannot carry `pg`/`postgres` into the app's bundle - only a real class reference can.
 > - **`configure()` only assigns `this.client`.** The protected `wireDriverFromMetadata()` (called internally by `getConnector()`/`resolveDriver()`) instantiates the named class over it and builds `this.connector`, lazily and idempotently.
 > - **Where the drivers live.** `pg` and `postgres` are both optional peer dependencies; concrete drivers live at `@venizia/ignis/postgres/node-postgres` and `@venizia/ignis/postgres/postgres-js`, and Supabase support at `@venizia/ignis/postgres/supabase`. See [Postgres Drivers & Supabase](/guides/core-concepts/persistent/postgres-drivers).
 
@@ -197,7 +197,7 @@ The fourth generic, `Client = Pool`, is what lets a postgres-js datasource decla
 
 Extends `AbstractPostgresDataSource` with a constructor, **schema auto-discovery**, and a real `beginTransaction()` implementation backed by the connection pool. Internally named `BaseRelationalDataSource`.
 
-`Source ->` [`packages/core/src/connectors/postgres/datasources/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/postgres/datasources/base.ts)
+`Source ->` [`packages/core-server/src/connectors/postgres/datasources/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/connectors/postgres/datasources/base.ts)
 
 ```typescript
 abstract class BaseRelationalDataSource<
@@ -246,7 +246,7 @@ This means tables and relations never need to be manually merged in the datasour
 
 1. **Your DataSource's `constructor` runs.** You call `super()` with `name` and `config`. Schema is auto-discovered from `@repository` bindings unless `schema` is provided manually.
 2. **`Application.registerDataSources()` runs during startup.** The application fetches your datasource instance from the DI container and calls `configure()` on it.
-3. **Your `configure()` method runs.** Its only job is to create the raw client and assign it to `this.client` - `getConnector()`/`beginTransaction()` lazily instantiate the class named in `@datasource({ driver })` over it and build the Drizzle connector. `configure()` never touches `this.connector` directly.
+3. **Your `configure()` method runs.** Its only job is to create the raw client and assign it to `this.client`. `getConnector()`/`beginTransaction()` lazily instantiate the class named in `@datasource({ driver })` over it and build the Drizzle connector. `configure()` never touches `this.connector` directly.
 
 ### Example implementations
 
@@ -362,11 +362,11 @@ export class PostgresDataSource extends BasePostgresDataSource<IDataSourceConfig
 ```
 
 > [!IMPORTANT]
-> `configure()` must leave the datasource with a way to reach the database: either assign the raw client to `this.client` (paired with naming the driver class in `@datasource({ driver })`), or wire a driver directly with `this.useDriver({ driver })` for a custom or third-party driver. `getConnector()`/`beginTransaction()` resolve the driver lazily from whichever you provided. With neither, `wireDriverFromMetadata()` throws `No driver and no client`.
+> `configure()` must leave the datasource with a way to reach the database. Either assign the raw client to `this.client`, paired with naming the driver class in `@datasource({ driver })`. Or wire a driver directly with `this.useDriver({ driver })` for a custom or third-party driver. `getConnector()`/`beginTransaction()` resolve the driver lazily from whichever you provided. With neither, `wireDriverFromMetadata()` throws `No driver and no client`.
 
 ### `@datasource` decorator
 
-`Source ->` [`packages/core/src/base/metadata/persistents.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/metadata/persistents.ts)
+`Source ->` [`packages/core-server/src/base/metadata/persistents.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/base/metadata/persistents.ts)
 
 ```typescript
 @datasource({
@@ -404,7 +404,7 @@ export class PostgresDataSource extends BasePostgresDataSource<IDataSourceConfig
 
 ## Driver interface
 
-`Source ->` [`packages/core/src/connectors/postgres/drivers`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/postgres/drivers)
+`Source ->` [`packages/core-server/src/connectors/postgres/drivers`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/connectors/postgres/drivers)
 
 `IRelationalDriver` owns connection acquisition and the raw control statements (`BEGIN`/`COMMIT`/`ROLLBACK`) - the only two places the connector is hard-wired to a specific client library.
 
@@ -434,7 +434,7 @@ interface IStatementResult {
 | `getClient()` | Raw client escape - `pg.Pool` for node-postgres, `Sql` for postgres-js |
 | `end()` | Closes the underlying client/pool |
 | `IRelationalConnection.execute({ statement })` | Runs a control statement verbatim (never parameterized - `BEGIN TRANSACTION ISOLATION LEVEL $1` is not valid SQL) |
-| `IRelationalConnection.release({ destroy? })` | Returns the connection to the pool, or discards it when `destroy: true` - required after a failed `COMMIT`/`ROLLBACK`, since the session may still hold an open transaction |
+| `IRelationalConnection.release({ destroy? })` | Returns the connection to the pool, or discards it when `destroy: true`. Required after a failed `COMMIT`/`ROLLBACK`, since the session may still hold an open transaction |
 
 Two concrete drivers ship today, both satisfying `IRelationalDriver` and both proven by the same conformance suite:
 
@@ -443,12 +443,12 @@ Two concrete drivers ship today, both satisfying `IRelationalDriver` and both pr
 | `NodePostgresDriver` | `pg` | Rejects a client without `connect()` **and** `totalCount` (pool accounting) - catches a bare `pg.Client` |
 | `PostgresJsDriver` | `postgres` | Rejects a client without `reserve()` **and** `unsafe()` - catches a `pg.Pool` passed to the wrong driver |
 
-- **Driver asymmetry, deliberate.** After a failed `COMMIT`, `pg` can destroy the poisoned connection (`release(err)`); postgres-js has no destroy semantics (`ReservedSql.release()` takes no argument), so it returns the connection to the pool regardless.
+- **Driver asymmetry, deliberate.** After a failed `COMMIT`, `pg` can destroy the poisoned connection (`release(err)`). postgres-js has no destroy semantics - `ReservedSql.release()` takes no argument - so it returns the connection to the pool regardless.
 - **Both drivers accept the same call.** `IRelationalConnection.release({ destroy: true })` is accepted by both drivers and honored by one. See [Postgres Drivers & Supabase](/guides/core-concepts/persistent/postgres-drivers) for the full driver comparison and Supabase's transaction-pooler requirements.
 
 ## Connector types
 
-`Source ->` [`packages/core/src/connectors/postgres/datasources/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/postgres/datasources/common/types.ts)
+`Source ->` [`packages/core-server/src/connectors/postgres/datasources/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/connectors/postgres/datasources/common/types.ts)
 
 | Type | Description |
 |---|---|
@@ -460,7 +460,7 @@ Two concrete drivers ship today, both satisfying `IRelationalDriver` and both pr
 
 ### `DataSourceDrivers`
 
-`Source ->` [`packages/core/src/base/datasources/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/datasources/common/types.ts)
+`Source ->` [`packages/core-server/src/base/datasources/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/base/datasources/common/types.ts)
 
 An identity-only const-class - the engine actually used is chosen by which driver **class** `@datasource({ driver })` names, not by this constant. `DataSourceDrivers` is read by nothing else in `src`; it never routes connector configuration.
 
@@ -484,7 +484,7 @@ DataSourceDrivers.isValid('node-postgres')  // true
 ```
 
 > [!NOTE]
-> `NODE_POSTGRES`/`POSTGRES_JS` remain valid `TDataSourceDriver` string values, but `@datasource({ driver })` on a **relational** datasource no longer accepts them - it takes the `NodePostgresDriver`/`PostgresJsDriver` class instead (see [Postgres Drivers & Supabase](/guides/core-concepts/persistent/postgres-drivers)). Search connectors (`TYPESENSE`, `MEILISEARCH`) still take the driver-name string form, because `extends TypesenseDataSource` already names the engine and is what carries the client into the bundle.
+> `NODE_POSTGRES`/`POSTGRES_JS` remain valid `TDataSourceDriver` string values. But `@datasource({ driver })` on a **relational** datasource no longer accepts them - it takes the `NodePostgresDriver`/`PostgresJsDriver` class instead (see [Postgres Drivers & Supabase](/guides/core-concepts/persistent/postgres-drivers)). Search connectors (`TYPESENSE`, `MEILISEARCH`) still take the driver-name string form. `extends TypesenseDataSource` already names the engine, and that is what carries the client into the bundle.
 
 ## Transaction support
 
@@ -499,28 +499,29 @@ Only engines that declare `getCapabilities().transactions === true` implement re
 3. On a failed `BEGIN`, destroys the connection (`release({ destroy: true })`) and rethrows - it is never leaked back to the pool in an unknown state
 4. Returns an `IDatabaseTransaction` object exposing `isActive`, `commit()`, `rollback()`, and the connection-scoped `connector`
 
-- **Shared `finish()`.** `commit()`/`rollback()` share one internal `finish()` that flips `isActive` to `false` **before** issuing the statement, so a commit racing a rollback cannot double-release the same connection - then runs `COMMIT`/`ROLLBACK`.
+- **Shared `finish()`.** `commit()`/`rollback()` share one internal `finish()`. It flips `isActive` to `false` **before** issuing the statement, so a commit racing a rollback cannot double-release the same connection, then runs `COMMIT`/`ROLLBACK`.
 - **Outcome handling.** On success the connection is released back to the pool; on failure it is destroyed and the error is rethrown.
 
 > [!WARNING] `commit()`/`rollback()` throw on failure
 > - **A failed `COMMIT` or `ROLLBACK` throws** - a failed `COMMIT` never resolves as success.
-> - **The poisoned connection is destroyed**, not returned to the pool, where the driver supports it: `node-postgres` can discard a connection; `postgres-js` has no destroy semantics and pools it anyway.
+> - **The poisoned connection is destroyed**, not returned to the pool, where the driver supports it. `node-postgres` can discard a connection; `postgres-js` has no destroy semantics and pools it anyway.
 > - **Nest `rollback()` in its own `try...catch`.** It can throw and is normally called from a `catch`, so nesting keeps the rollback error from replacing the original cause.
-> - **Calling `rollback()` twice is safe.** After a transaction already ended by failure, `rollback()` is a silent no-op (already torn down), so the canonical `catch { await tx.rollback(); throw error; }` pattern always works. See [Transactions](/guides/core-concepts/persistent/transactions) and [Postgres Drivers & Supabase](/guides/core-concepts/persistent/postgres-drivers).
+> - **Calling `rollback()` twice is safe.** After a transaction already ended by failure, `rollback()` is a silent no-op, because it's already torn down.
+> - **The canonical shape.** `catch { await tx.rollback(); throw error; }` always works. See [Transactions](/guides/core-concepts/persistent/transactions) and [Postgres Drivers & Supabase](/guides/core-concepts/persistent/postgres-drivers).
 
 ### Neutral vs. PostgreSQL transaction types
 
 `src/base` declares the engine-neutral shape; the PostgreSQL connector narrows it with connection details.
 
 ```typescript
-// packages/core/src/base/datasources/common/types.ts - engine-neutral
+// packages/core-server/src/base/datasources/common/types.ts - engine-neutral
 interface ITransaction {
   isActive: boolean;
   commit(): Promise<void>;
   rollback(): Promise<void>;
 }
 
-// packages/core/src/connectors/postgres/datasources/common/types.ts - PostgreSQL
+// packages/core-server/src/connectors/postgres/datasources/common/types.ts - PostgreSQL
 interface IDatabaseTransaction<Schema extends TAnyDataSourceSchema = TAnyDataSourceSchema>
   extends ITransaction {
   connector: TRelationalConnector<Schema>;
@@ -585,7 +586,7 @@ try {
 > [!TIP]
 > For most use cases, prefer `repository.beginTransaction()`, which provides a higher-level API. See [Repositories](/references/base/repositories/#run-inside-a-transaction).
 
-This architecture ensures datasources are configured consistently and that the fully-initialized Drizzle connector, aware of all schemas and relations, is available to repositories for querying.
+This architecture keeps datasource configuration consistent. The fully-initialized Drizzle connector, aware of all schemas and relations, is available to repositories for querying.
 
 ## See also
 

package/content/references/base/datasources.md

@@ -43,10 +43,10 @@ A `@repository` binds a model to `PostgresDataSource`, and the schema is auto-di
 
 ## How it works
 
-- **Driver is a class, not a string.** `@datasource({ driver })` names `NodePostgresDriver` or `PostgresJsDriver` as a class reference - never a driver-name string. Only a real class reference carries `pg`/`postgres` into the application's bundle, so both stay genuinely optional peer dependencies.
+- **Driver is a class, not a string.** `@datasource({ driver })` names `NodePostgresDriver` or `PostgresJsDriver` as a class reference, never a driver-name string. Only a class reference carries `pg`/`postgres` into the bundle, keeping both packages optional.
 - **`configure()` has exactly one job.** Build the raw client and assign it to `this.client` (a `pg.Pool` for node-postgres, or a postgres-js `Sql`). It never touches `this.connector` directly.
-- **The driver wires lazily.** The first time `getConnector()` or `beginTransaction()` is called, the base class reads the class named in `@datasource({ driver })`, instantiates it over `this.client`, and builds `this.connector` from it.
-- **Base vs. connector split.** IGNIS splits datasources into an engine-neutral root (`AbstractDataSource` - no SQL, no Drizzle, no pool) and per-engine connectors (`BasePostgresDataSource` for PostgreSQL, a parallel class for typesense). See [Connectors](/references/base/connectors) for the full architecture.
+- **The driver wires lazily.** The first time `getConnector()` or `beginTransaction()` is called, the base class reads the class named in `@datasource({ driver })`. It instantiates that class over `this.client` and builds `this.connector` from it.
+- **Base vs. connector split.** IGNIS splits datasources into an engine-neutral root (`AbstractDataSource` - no SQL, no Drizzle, no pool) and per-engine connectors. `BasePostgresDataSource` is the PostgreSQL connector; typesense has a parallel class. See [Connectors](/references/base/connectors) for the full architecture.
 - **Naming.** The PostgreSQL connector's canonical class is `BaseRelationalDataSource`; `BasePostgresDataSource` and `BaseDataSource` are compatibility aliases re-exporting the same class.
 
 ## Common tasks
@@ -139,7 +139,7 @@ try {
 
 ### Share one datasource across repositories
 
-One `PostgresDataSource` instance is shared by every repository bound to it - `@repository` auto-injects the datasource, and `getSchema()` merges the tables and relations of every model bound to it.
+One `PostgresDataSource` instance is shared by every repository bound to it. `@repository` auto-injects the datasource, and `getSchema()` merges the tables and relations of every model bound to it.
 
 ```typescript
 @repository({ model: User, dataSource: PostgresDataSource })
@@ -161,5 +161,5 @@ export class ConfigurationRepository extends DefaultCRUDRepository<typeof Config
 
 **Files:**
 
-- [`packages/core/src/base/datasources/abstract.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/datasources/abstract.ts) - neutral `AbstractDataSource`
-- [`packages/core/src/connectors/postgres/datasources/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/postgres/datasources/base.ts) - PostgreSQL `BasePostgresDataSource`
+- [`packages/core-server/src/base/datasources/abstract.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/base/datasources/abstract.ts) - neutral `AbstractDataSource`
+- [`packages/core-server/src/connectors/postgres/datasources/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/connectors/postgres/datasources/base.ts) - PostgreSQL `BasePostgresDataSource`

package/content/references/base/dependency-injection.md

@@ -13,9 +13,9 @@ Technical reference for the DI system in IGNIS - managing resource lifecycles an
 - `packages/inversion/src/modules/registry/index.ts` - Base `MetadataRegistry`
 - `packages/inversion/src/modules/metadata/injectors.ts` - Base `@inject` decorator
 - `packages/inversion/src/common/types.ts` - `BindingScopes`, `BindingValueTypes`, `BindingKeys`, `IProvider`
-- `packages/core/src/helpers/inversion/container.ts` - Extended `Container` with `ApplicationLogger`
-- `packages/core/src/helpers/inversion/registry.ts` - Extended `MetadataRegistry` (singleton, with model/repository/datasource mixins)
-- `packages/core/src/base/metadata/injectors.ts` - Core `@inject` (wired to extended registry)
+- `packages/core-server/src/helpers/inversion/container.ts` - Extended `Container` with `ApplicationLogger`
+- `packages/core-server/src/helpers/inversion/registry.ts` - Extended `MetadataRegistry` (singleton, with model/repository/datasource mixins)
+- `packages/core-server/src/base/metadata/injectors.ts` - Core `@inject` (wired to extended registry)
 
 ## Quick Reference
 
@@ -41,7 +41,7 @@ Before reading this document, you should understand:
 
 Heart of the DI system - registry managing all application resources.
 
-**File:** `packages/inversion/src/modules/container/index.ts` (Base) & `packages/core/src/helpers/inversion/container.ts` (Extended)
+**File:** `packages/inversion/src/modules/container/index.ts` (Base) & `packages/core-server/src/helpers/inversion/container.ts` (Extended)
 
 The base `Container` extends `BaseHelper` (which provides `scope` and `identifier` properties). The core `Container` extends the base and adds a `Logger` instance.
 
@@ -73,7 +73,8 @@ const container = new Container({ scope: 'MyApp' }); // scope is optional, defau
 
 When `container.instantiate(MyClass)` is called:
 
-1. **Constructor injection** - Reads `@inject` metadata from the class by parameter index (the `Reflect`-stored array is already index-keyed, so there is no sort step), resolves each dependency from the container, and passes them as constructor arguments. If any index in range has no `@inject` metadata, `instantiate()` throws immediately rather than passing `undefined`.
+1. **Constructor injection** - Reads `@inject` metadata from the class by parameter index. The `Reflect`-stored array is already index-keyed, so there is no sort step; the container resolves each dependency and passes them as constructor arguments.
+   - If any index in range has no `@inject` metadata, `instantiate()` throws immediately rather than passing `undefined`.
 2. **Property injection** - After the instance is created, reads property metadata, resolves each dependency, and assigns them directly to the instance properties.
 
 ```typescript
@@ -90,16 +91,16 @@ class UserController {
 ```
 
 > [!IMPORTANT]
-> **Every constructor parameter of a container-instantiated class must carry `@inject`.** Mixing decorated and undecorated parameters is forbidden - `@inject` stores its metadata at the parameter's index, so an undecorated parameter leaves a hole in that array, and there is no channel through which the container could supply it anyway (it would resolve to `undefined`). `instantiate()` refuses the shape by class name and parameter index instead of silently dereferencing the hole:
+> **Every constructor parameter of a container-instantiated class must carry `@inject`.** Mixing decorated and undecorated parameters is forbidden. `@inject` stores its metadata at the parameter's index, so an undecorated parameter leaves a hole in that array. There is no channel through which the container could supply it anyway - it would resolve to `undefined`. `instantiate()` refuses the shape by class name and parameter index instead of silently dereferencing the hole:
 >
 > ```
 > [NoteController] Constructor parameter 0 has no @inject | Every parameter of a container-instantiated
 > class must be decorated - the container cannot supply an undecorated one
 > ```
 >
-> The check lives in `instantiate()`, not in the `@inject` decorator itself: parameter decorators run right-to-left, so when `@inject` on parameter 1 runs, parameter 0 has not been visited yet and nothing at that point can know whether it will end up decorated.
+> The check lives in `instantiate()`, not in the `@inject` decorator itself. Parameter decorators run right-to-left, so when `@inject` on parameter 1 runs, parameter 0 has not been visited yet - nothing at that point can know whether it will end up decorated.
 >
-> This does not apply to `@repository`-decorated classes whose constructor appears undecorated at index 0 - the `@repository` decorator programmatically writes that inject metadata (`registry.setInjectMetadata({ target, index: 0, ... })`) even though no literal `@inject` appears in source. See [Repositories](./repositories/).
+> This does not apply to `@repository`-decorated classes whose constructor appears undecorated at index 0. The `@repository` decorator programmatically writes that inject metadata (`registry.setInjectMetadata({ target, index: 0, ... })`), even though no literal `@inject` appears in source. See [Repositories](./repositories/).
 
 ## `Binding` Class
 
@@ -205,7 +206,7 @@ This is also used internally by `container.get()` and `container.getBinding()` w
 
 The `@inject` decorator marks where dependencies should be injected - either on constructor parameters or class properties.
 
-**File:** `packages/inversion/src/modules/metadata/injectors.ts` (base) & `packages/core/src/base/metadata/injectors.ts` (core wrapper)
+**File:** `packages/inversion/src/modules/metadata/injectors.ts` (base) & `packages/core-server/src/base/metadata/injectors.ts` (core wrapper)
 
 ### Signature
 
@@ -261,7 +262,7 @@ import { inject } from '@venizia/ignis';
 
 ## Registering a Class
 
-No class decorator is needed to make a class injectable. A class becomes resolvable once a binding exists for it - created either by boot auto-discovery, by a framework helper (`app.controller()`, `app.service()`, `@repository`), or explicitly with `container.bind()`. Scope is configured on the binding, never on the class:
+No class decorator is needed to make a class injectable. A class becomes resolvable once a binding exists for it. That binding can come from boot auto-discovery, from a framework helper (`app.controller()`, `app.service()`, `@repository`), or explicitly from `container.bind()`. Scope is configured on the binding, never on the class:
 
 ```typescript
 class UserService extends BaseService {
@@ -305,7 +306,7 @@ A singleton exported as `metadataRegistry`. Extends `BaseHelper`.
 
 ### Core MetadataRegistry
 
-**File:** `packages/core/src/helpers/inversion/registry.ts`
+**File:** `packages/core-server/src/helpers/inversion/registry.ts`
 
 Extends the base with controller, repository, model, and datasource metadata support via mixins. Accessed as a singleton via `MetadataRegistry.getInstance()`.
 

package/content/references/base/filter-system/application-usage.md

@@ -6,7 +6,7 @@ difficulty: intermediate
 
 # Using Filters in Your Application
 
-A `filter` typically starts as a JSON-encoded query string on an HTTP request and ends as a Drizzle query - here is what happens at each layer in between.
+A `filter` starts as a JSON-encoded query string on an HTTP request and ends as a Drizzle query. Here is where to hook into each layer in between.
 
 ```
 HTTP Request         GET /products?filter={"where":{"status":"active"},"limit":10}
@@ -22,11 +22,9 @@ Repository Layer       applyDefaultFilter() merges the @model default filter,
                         FilterBuilder converts Filter -> Drizzle query options, executes
 ```
 
-## Controller layer
+## Generate a CRUD controller from an entity
 
-### `ControllerFactory` (recommended)
-
-`ControllerFactory.defineCrudController` generates a full CRUD controller, including filter parsing and validation, from an entity and a repository binding:
+For a standard `GET`/`POST`/`PATCH`/`DELETE` resource, generate the controller instead of writing filter parsing by hand. `ControllerFactory.defineCrudController` builds it from an entity and a repository binding:
 
 ```typescript
 // src/controllers/product.controller.ts
@@ -65,7 +63,7 @@ export class ProductController extends _Controller {
 }
 ```
 
-**Filter-bearing endpoints generated:**
+This generates every filter-bearing endpoint the resource needs:
 
 | Method | Endpoint | Query param |
 |---|---|---|
@@ -74,17 +72,34 @@ export class ProductController extends _Controller {
 | GET | `/products/find-one` | `filter` |
 | GET | `/products/count` | `where` |
 
-- **`isStrict.requestSchema`** controls whether these query params are Zod-required or optional.
-- **`isStrict.path`** controls trailing-slash strictness.
-- **Write endpoints** (`POST /`, `PATCH /{id}`, `DELETE /{id}`, ...) are also generated by the factory, and take no filter.
+Set `isStrict.requestSchema: true` to make these query params Zod-required; set `isStrict.path: true` to reject trailing-slash variants of the route. Write endpoints (`POST /`, `PATCH /{id}`, `DELETE /{id}`, ...) come from the same factory call and take no filter.
+
+## Map a request query string to a parsed filter
+
+`FilterSchema` and `WhereSchema` both accept a JSON string or a plain object, so the same schema validates a Hono query param (always a string) and a filter built in code:
 
-### Custom controller with manual filter handling
+| Request | Parsed filter |
+|---|---|
+| `GET /products?filter={"where":{"status":"active"}}` | `{ where: { status: 'active' } }` |
+| `GET /products?filter={"limit":10,"skip":20}` | `{ limit: 10, skip: 20 }` |
+| `GET /products?filter={"where":{"price":{"gte":100,"lte":500}},"order":["price ASC"]}` | `{ where: { price: { gte: 100, lte: 500 } }, order: ['price ASC'] }` |
+| `GET /products/count?where={"role":"admin"}` | `{ role: 'admin' }` |
+
+`WhereSchema` is independent of `FilterSchema` - it backs the `count` endpoint, which takes `where` directly rather than a full filter.
 
-For a route outside the generated CRUD set, accept `FilterSchema` directly:
+## Write a custom route that accepts a filter
+
+For a route outside the generated CRUD set, use `FilterQuerySchema` - the same query shape the generated `find` route takes:
 
 ```typescript
 import { z } from '@hono/zod-openapi';
-import { BaseRestController, controller, FilterSchema, inject, jsonResponse } from '@venizia/ignis';
+import {
+  BaseRestController,
+  controller,
+  FilterQuerySchema,
+  inject,
+  jsonResponse,
+} from '@venizia/ignis';
 
 @controller({ path: '/products' })
 export class ProductController extends BaseRestController {
@@ -100,7 +115,7 @@ export class ProductController extends BaseRestController {
       configs: {
         path: '/search',
         method: 'get',
-        request: { query: z.object({ filter: FilterSchema }) },
+        request: { query: FilterQuerySchema },
         responses: jsonResponse({ schema: z.array(z.object({ id: z.string() })) }),
       },
       handler: async context => {
@@ -113,23 +128,29 @@ export class ProductController extends BaseRestController {
 }
 ```
 
-## Filter schema validation
+### The two query shapes
 
-`FilterSchema` and `WhereSchema` are both `z.union([<object shape>, <JSON string>.transform(JSON.parse)])` - they accept either format, so a Hono query param (always a string) and a filter built in code both validate:
+Reach for these instead of rebuilding the same object at every route.
 
-```typescript
-// Object format (built in code)
-{ where: { status: 'active' }, limit: 10 }
+| Schema | Query shape | Use it for |
+|---|---|---|
+| `FilterQuerySchema` | `{ filter?: TFilter }` | Any route that takes a full filter |
+| `WhereQuerySchema` | `{ where?: TWhere }` | Any route that takes conditions and no pagination |
+
+Both are plain Zod objects, so a route that takes more than one parameter extends rather than rebuilds:
 
-// JSON string format (from a URL query string)
-'{"where":{"status":"active"},"limit":10}'
+```typescript
+request: { query: WhereQuerySchema.extend({ q: z.string().max(255).optional() }) },
 ```
 
-`WhereSchema` is independent of `FilterSchema` - it backs the `count` endpoint, which takes `where` directly rather than a full filter.
+Neither needs an extra `.optional()`. `FilterSchema` already carries one, so `FilterSchema.optional()` is the same schema written longer, and a trailing `.partial()` on a single optional key does nothing.
 
-## Service layer
+> [!NOTE]
+> The generated `updateBy` and `deleteBy` routes deliberately do not use `WhereQuerySchema`. They require `where`, because a missing one rewrites or deletes every row in the table.
 
-A service can rewrite the filter before it reaches the repository - useful when a constraint is a caller/session concern rather than a per-model constant (see [Default Filter](./default-filter) for the model-level alternative):
+## Rewrite a filter before it reaches the repository
+
+Add a service between the controller and the repository when a constraint is a caller or session concern rather than a per-model constant - a tenant ID pulled from the request context, for example. Use [Default Filter](./default-filter) instead when the constraint applies to every caller of the model:
 
 ```typescript
 @service()
@@ -147,7 +168,9 @@ export class ProductService {
 }
 ```
 
-## HTTP request examples
+## Build a filter query string from a client
+
+Encode the filter as JSON and pass it as the `filter` query param, whichever HTTP client you use:
 
 **cURL:**
 ```bash
@@ -166,9 +189,9 @@ const response = await fetch(`/api/products?filter=${encodeURIComponent(JSON.str
 const response = await axios.get('/api/products', { params: { filter: JSON.stringify(filter) } });
 ```
 
-## Debugging a filter
+## Debug what a filter compiles to
 
-`buildQuery` compiles a filter into Drizzle query options without executing it - the fastest way to check what a filter actually resolves to:
+Call `buildQuery` to compile a filter into Drizzle query options without executing it - the fastest way to check what a filter actually resolves to:
 
 ```typescript
 const queryOptions = repository.buildQuery({ filter: complexFilter });
@@ -180,12 +203,13 @@ console.log('Generated query options:', queryOptions);
 ## See also
 
 - [Filter System Overview](./) - the `filter` shape and every `where` operator family
-- [Default Filter](./default-filter) - `shouldSkipDefaultFilter`, and the model-level alternative to the service-layer pattern above
+- [Default Filter](./default-filter) - `shouldSkipDefaultFilter`, and the model-level alternative to the service-layer rewrite above
 - [Use Case Gallery](./use-cases) - more filter shapes with their generated SQL
 - [Advanced Repository Features](../repositories/advanced.md) - transactions, locking, and the full `log`/`lock` options
 
 **Files:**
 
-- [`packages/core/src/base/controllers/factory/controller.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/controllers/factory/controller.ts) - `ControllerFactory.defineCrudController`
-- [`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) - `FilterSchema`, `TFilter`, `TInclusion`
-- [`packages/core/src/connectors/postgres/repositories/core/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/postgres/repositories/core/base.ts) - `RelationalBaseRepository.buildQuery`
+- [`packages/kernel/src/base/controllers/factory/controller.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/kernel/src/base/controllers/factory/controller.ts) - `ControllerFactory.defineCrudController`
+- [`packages/kernel/src/base/repositories/query-schemas/index.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/kernel/src/base/repositories/query-schemas/index.ts) - `FilterSchema`, `WhereSchema`, `FilterQuerySchema`, `WhereQuerySchema`
+- [`packages/filter/src/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/filter/src/common/types.ts) - `TFilter`, `TInclusion`
+- [`packages/connectors/src/relational/core/repositories/core/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/connectors/src/relational/core/repositories/core/base.ts) - `RelationalBaseRepository.buildQuery`