@venizia/ignis-docs 0.1.0 → 0.2.1-0

package/content/guides/core-concepts/persistent/postgres-drivers.md

@@ -8,7 +8,7 @@ IGNIS talks to PostgreSQL through a **driver seam**: `IRelationalDriver` owns co
 Supabase is unmodified PostgreSQL, so it is not a separate connector: it varies the **driver**, not the SQL dialect. The `@venizia/ignis/postgres/supabase` submodule adds the two things Supabase deployments actually need - pooler presets and an RLS auth-context helper.
 
 > [!IMPORTANT] Every database client is optional
-> `pg` and `postgres` are both **optional peer dependencies**. The `@venizia/ignis/postgres` module pulls in neither - each driver is imported lazily, only when the client you built selects it. Install the one your app uses:
+> `pg` and `postgres` are both **optional peer dependencies**. The `@venizia/ignis/postgres` module pulls in neither - only the driver class you import and name in `@datasource({ driver })` reaches your bundle. Install the one your app uses:
 >
 > ```bash
 > bun add pg          # node-postgres
@@ -19,60 +19,89 @@ Supabase is unmodified PostgreSQL, so it is not a separate connector: it varies
 
 | Import | Contents | Loads |
 | :--- | :--- | :--- |
-| `@venizia/ignis/postgres` | `BasePostgresDataSource`, `IRelationalDriver`, `resolveDatabaseDriver`, repository hierarchy | no client library |
+| `@venizia/ignis/postgres` | `BasePostgresDataSource`, `IRelationalDriver`, repository hierarchy | no client library |
 | `@venizia/ignis/postgres/node-postgres` | `NodePostgresDriver` | `pg` |
 | `@venizia/ignis/postgres/postgres-js` | `PostgresJsDriver` | `postgres` |
 | `@venizia/ignis/postgres/supabase` | `PoolerModes`, `buildPostgresJsOptions`, `withAuthContext`, Supabase role re-exports | `drizzle-orm/supabase` |
 
-## The Default: a Bare Pool
+## Naming the Driver Class
 
-Hand IGNIS a `pg.Pool` on `this.client` and it adopts it into a `NodePostgresDriver` on first use - no driver import needed:
+`@datasource({ driver })` takes the driver **class**, not a driver-name string:
 
 ```typescript
-import { DataSourceDrivers, datasource } from '@venizia/ignis';
+import { datasource, ValueOrPromise } from '@venizia/ignis';
 import { BasePostgresDataSource } from '@venizia/ignis/postgres';
-import { drizzle } from 'drizzle-orm/node-postgres';
+import { NodePostgresDriver } from '@venizia/ignis/postgres/node-postgres';
 import { Pool } from 'pg';
 
-@datasource({ driver: DataSourceDrivers.NODE_POSTGRES })
+@datasource({ driver: NodePostgresDriver })
 export class PostgresDataSource extends BasePostgresDataSource<IDataSourceConfigs> {
-  configure() {
-    this.client = new Pool({ connectionString: this.getConnectionString() });
-    this.connector = drizzle({ client: this.client, schema: this.getSchema() });
+  override configure(): ValueOrPromise<void> {
+    this.client = new Pool({ connectionString: this.getConnectionString() }); // that is all
   }
 }
 ```
 
-`this.client` is the raw-client slot: the `pg.Pool` (or postgres-js `Sql`) your `configure()` built. `getClient()` hands it back as the escape hatch, and `beginTransaction()` resolves a driver from it lazily. A datasource that sets neither `this.client` nor a driver throws `No driver and no client` on its first transaction.
+`configure()` only builds `this.client` - the raw `pg.Pool` (or postgres-js `Sql`) your app's connection settings produce. The base class wires the driver **and** the connector lazily, on first call to `getConnector()` or `beginTransaction()`: it reads the class named in `@datasource({ driver })`, instantiates it over `this.client`, and builds the pooled Drizzle connector from that. `getClient()` hands `this.client` back as the raw-client escape hatch. A datasource that sets neither `this.client` nor a driver (via `useDriver()`, below) throws `No driver and no client` on first use.
+
+> [!IMPORTANT] Why a class, not a name
+> A driver-name string cannot carry `pg` or `postgres` into your bundle - it is just text. A dynamic `import('./node-postgres.js')` keyed off that string would defer *execution*, not *packaging*: every bundler statically resolves a literal specifier and packages whatever it points to, so a build that only used node-postgres would still fail with `Could not resolve: "postgres"` the moment postgres-js's import appeared anywhere in the module graph reachable at build time. Naming the class instead makes the driver module a real value reference - the one thing a bundler is forced to keep - which is what lets `pg` and `postgres` stay genuinely optional peers. A bare side-effect import (`import '@venizia/ignis/postgres/node-postgres'`) would not work either: `@venizia/ignis` declares `sideEffects: false`, so a bundler is free to drop an import whose exports go unused.
+>
+> Two tests pin this from different angles: `packages/core/src/__tests__/connectors/postgres/no-eager-driver-import.test.ts` proves no barrel **loads** a driver package in a fresh process (the runtime module graph), and `packages/core/src/__tests__/connectors/postgres/bundle/optional-peers.test.ts` proves no barrel gets a driver package **packaged** by a real bundler.
 
 ## Using postgres-js
 
-Wire a driver explicitly with `useDriver()` - it assigns the driver **and** builds the pooled connector in one step, so the half-wired state (driver set, connector forgotten) cannot exist:
+Same shape, different class:
 
 ```typescript
-import { DataSourceDrivers, datasource } from '@venizia/ignis';
+import { datasource, ValueOrPromise } from '@venizia/ignis';
 import { BasePostgresDataSource } from '@venizia/ignis/postgres';
 import { PostgresJsDriver } from '@venizia/ignis/postgres/postgres-js';
 import postgres from 'postgres';
 import type { Sql } from 'postgres';
 
-@datasource({ driver: DataSourceDrivers.POSTGRES_JS })
+@datasource({ driver: PostgresJsDriver })
 export class PostgresDataSource extends BasePostgresDataSource<
   IDataSourceConfigs,
   typeof schema,
   {},
   Sql // getClient() is now honestly typed as postgres-js's Sql, not pg.Pool
 > {
-  configure() {
+  override configure(): ValueOrPromise<void> {
+    this.client = postgres(this.getConnectionString());
+  }
+}
+```
+
+The fourth type parameter (`Client`) defaults to `pg.Pool`; declare it when the raw client escape hatch (`getClient()`) should carry the real type.
+
+## Driver Constructors Validate Their Client
+
+Both shipped drivers throw immediately if constructed with the wrong shape of client, instead of failing later inside a query:
+
+```typescript
+new NodePostgresDriver({ client: pool }); // client must expose connect() AND totalCount (pool accounting)
+new PostgresJsDriver({ client: sql });    // client must expose reserve() AND unsafe()
+```
+
+`NodePostgresDriver` rejects a bare `pg.Client` - it exposes `connect()` too, but has no pool accounting and cannot hand out a dedicated connection per transaction. `PostgresJsDriver` rejects a `pg.Pool` the same way. You will not normally construct these yourself: `wireDriverFromMetadata()` does it for you from `this.client`, so this validation fires the first time a datasource wired the wrong client behind the wrong `@datasource({ driver })` class.
+
+## Custom or Third-Party Drivers: `useDriver()`
+
+For a driver IGNIS does not ship, wire it explicitly with `useDriver()` - it assigns the driver **and** builds the pooled connector in one step, so the half-wired state (driver set, connector forgotten) cannot exist:
+
+```typescript
+export class PostgresDataSource extends BasePostgresDataSource<IDataSourceConfigs> {
+  override configure(): ValueOrPromise<void> {
     this.useDriver({
-      driver: new PostgresJsDriver({ client: postgres(this.getConnectionString()) }),
+      driver: new MyCustomDriver({ client: myClient }),
       schema: this.getSchema(),
     });
   }
 }
 ```
 
-The fourth type parameter (`Client`) defaults to `pg.Pool`; declare it when the raw client escape hatch (`getClient()`) should carry the real type.
+`useDriver()` bypasses `@datasource({ driver })` entirely - you never need to name a class in the decorator when you wire the driver yourself in `configure()`.
 
 > [!WARNING] postgres-js cannot destroy a poisoned connection
 > After a failed `COMMIT` or `ROLLBACK`, node-postgres **destroys** the connection instead of pooling it - the session may still hold an open transaction that the next borrower would inherit. postgres-js has no destroy semantics (`ReservedSql.release()` takes no argument), so the connection is returned to the pool anyway. This asymmetry is real and IGNIS does not paper over it; it is pinned by the driver's own tests.
@@ -117,18 +146,23 @@ Supabase exposes three ways in, and one of them silently breaks prepared stateme
 The transaction pooler (Supavisor) rebinds the backend per transaction, so a server-side prepared statement created on one backend simply is not there next time. `buildPostgresJsOptions` encodes this so you cannot forget it:
 
 ```typescript
-import { buildPostgresJsOptions, PoolerModes } from '@venizia/ignis/postgres/supabase';
+import { datasource } from '@venizia/ignis';
+import { BasePostgresDataSource } from '@venizia/ignis/postgres';
 import { PostgresJsDriver } from '@venizia/ignis/postgres/postgres-js';
+import { buildPostgresJsOptions, PoolerModes } from '@venizia/ignis/postgres/supabase';
 import postgres from 'postgres';
 
-const client = postgres(connectionString, {
-  ...buildPostgresJsOptions({ mode: PoolerModes.TRANSACTION, max: 10 }),
-});
-
-this.useDriver({ driver: new PostgresJsDriver({ client }), schema: this.getSchema() });
+@datasource({ driver: PostgresJsDriver })
+export class SupabaseDataSource extends BasePostgresDataSource<IDataSourceConfigs> {
+  override configure() {
+    this.client = postgres(connectionString, {
+      ...buildPostgresJsOptions({ mode: PoolerModes.TRANSACTION, max: 10 }),
+    });
+  }
+}
 ```
 
-`prepare: false` is emitted only for `TRANSACTION` mode; `max` is forwarded only when you pass it, so postgres-js's own default survives.
+`prepare: false` is emitted only for `TRANSACTION` mode; `max` is forwarded only when you pass it, so postgres-js's own default survives. Naming `PostgresJsDriver` in `@datasource` is what wires it - `configure()` only needs to build the client, same as node-postgres.
 
 ### Row Level Security
 
@@ -164,4 +198,4 @@ The submodule also re-exports Drizzle's Supabase helpers (`anonRole`, `authentic
 
 ## Adding a Driver
 
-One file under `src/connectors/postgres/drivers/`, implementing the four verbs above, plus a fake client and a test that runs the shared conformance suite (`run({ driver, resolveDatabaseDriver })` in `src/__tests__/connectors/postgres/drivers/conformance/`). Register a sub-path export and an optional peer dependency; never re-export the driver from the drivers barrel - that is what would make its package load eagerly for everyone.
+One file under `src/connectors/postgres/drivers/`, implementing the four verbs above, plus a fake client and a test that runs the shared conformance suite (`run({ driver, buildDriverProbe })` in `src/__tests__/connectors/postgres/drivers/conformance/`). Register a sub-path export and an optional peer dependency; never re-export the driver from the drivers barrel - that is what would make its package load eagerly for everyone.

package/content/guides/core-concepts/persistent/search-meilisearch.md

@@ -61,10 +61,12 @@ The `searchable` and `filterable` flags are **load-bearing here** and are silent
 import { datasource } from '@venizia/ignis';
 import { MeilisearchDataSource } from '@venizia/ignis/meilisearch';
 
-@datasource({ driver: 'meilisearch' })
+@datasource()
 export class ArticleSearchDataSource extends MeilisearchDataSource {}
 ```
 
+No `driver` in the decorator, and that is not an omission. A relational datasource has to name one, because a single `BasePostgresDataSource` runs on either `pg` or `postgres` and something must pick. A search datasource has already picked: `extends MeilisearchDataSource` **is** the engine reference, and it is what carries the `meilisearch` package into your bundle. Naming the engine twice would just be a second chance to disagree with yourself.
+
 Configured through `IMeilisearchDataSourceSettings`:
 
 ```typescript

package/content/guides/core-concepts/persistent/search-typesense.md

@@ -176,11 +176,11 @@ await connector.linkSynonymSets({ collection: 'articles', synonymSets: ['article
 
 ```typescript
 // src/datasources/search.datasource.ts
-import { DataSourceDrivers, datasource } from '@venizia/ignis';
+import { datasource } from '@venizia/ignis';
 import { TypesenseDataSource } from '@venizia/ignis/typesense';
 import { applicationEnvironment, int } from '@venizia/ignis-helpers';
 
-@datasource({ driver: DataSourceDrivers.TYPESENSE })
+@datasource()
 export class SearchDataSource extends TypesenseDataSource {
   constructor() {
     super({
@@ -201,6 +201,8 @@ export class SearchDataSource extends TypesenseDataSource {
 }
 ```
 
+No `driver` in the decorator, and that is not an omission. A relational datasource has to name one, because a single `BasePostgresDataSource` runs on either `pg` or `postgres` and something must pick. A search datasource has already picked: `extends TypesenseDataSource` **is** the engine reference, and it is what carries the `typesense` package into your bundle. Naming the engine twice would just be a second chance to disagree with yourself.
+
 `TypesenseDataSource` extends `BaseSearchDataSource` (adds auto-discovery/provisioning) which extends `AbstractSearchDataSource` (engine contract: `getDriver()`, `getQueryDialect()`, `compileCollection()`, `ensureCollection()`) which extends the engine-neutral `AbstractDataSource`. Since `TypesenseDataSource` never overrides `beginTransaction()`, it inherits the neutral `NotSupported` default - see [Connectors](/references/base/connectors).
 
 On `configure()`, the datasource auto-provisions every discovered collection (`ensureCollection()` per definition, plus any declared `synonyms`) unless constructed with `autoProvision: false`.
@@ -252,8 +254,8 @@ export class ArticleRepository extends DefaultSearchRepository<TArticleDocument>
 
 ### Write error semantics (shared by both search engines)
 
-- **`create()` with a duplicate id throws `409` (`messageCode: 'core.search_engine.already_exists'`)** on both Typesense and Meilisearch - a duplicate is a conflict, never a silent overwrite. If you want last-write-wins, call `upsert()` explicitly. (On Meilisearch the pre-check is not atomic - see the [Meilisearch guide](./search-meilisearch); use `upsert()` when concurrent same-id creates are possible.)
-- **`updateById()` against a missing id throws `404` (`messageCode: 'core.search_engine.not_found'`)** on both engines. This is the deliberate divergence from the PostgreSQL connector, where a missing-id `updateById` is a silent `{ count: 0 }`.
+- **`create()` with a duplicate id throws `409` (`normalized.code: 'core.search_engine.already_exists'`)** on both Typesense and Meilisearch - a duplicate is a conflict, never a silent overwrite. If you want last-write-wins, call `upsert()` explicitly. (On Meilisearch the pre-check is not atomic - see the [Meilisearch guide](./search-meilisearch); use `upsert()` when concurrent same-id creates are possible.)
+- **`updateById()` against a missing id throws `404` (`normalized.code: 'core.search_engine.not_found'`)** on both engines. This is the deliberate divergence from the PostgreSQL connector, where a missing-id `updateById` is a silent `{ count: 0 }`.
 - **`deleteById()` against a missing id is silent** (`{ count: 0, data: null }`), matching the relational connectors.
 
 ## Searching with `search({ mode })`
@@ -411,7 +413,7 @@ The typesense connector has no transaction or row-level-locking model. Passing a
 await articleRepository.updateById({
   id: '123',
   data: { title: 'New' },
-  options: { transaction: tx }, // throws: 501, messageCode 'core.not_supported'
+  options: { transaction: tx }, // throws: 501, normalized.code 'core.not_supported'
 });
 ```
 

package/content/guides/core-concepts/persistent/transactions.md

@@ -3,7 +3,7 @@
 IGNIS supports explicit transaction objects that can be passed across multiple services and repositories, allowing for complex, multi-step business logic to be atomic.
 
 > [!NOTE] PostgreSQL-only capability
-> Real transactions are a **PostgreSQL connector** capability - `BasePostgresDataSource.getCapabilities()` returns `{ transactions: true }` and its `beginTransaction()` opens a real database transaction, as documented below. The typesense connector inherits the engine-neutral `AbstractDataSource` default: calling `beginTransaction()` on it throws a `501 Not Implemented` (`messageCode: 'core.not_supported'`) via the shared `throwNotSupported` utility. See [Connectors](/references/base/connectors) for the capabilities model.
+> Real transactions are a **PostgreSQL connector** capability - `BasePostgresDataSource.getCapabilities()` returns `{ transactions: true }` and its `beginTransaction()` opens a real database transaction, as documented below. The typesense connector inherits the engine-neutral `AbstractDataSource` default: calling `beginTransaction()` on it throws a `501 Not Implemented` (`normalized.code: 'core.not_supported'`) via the shared `throwNotSupported` utility. See [Connectors](/references/base/connectors) for the capabilities model.
 
 ## Using Transactions
 

package/content/guides/core-concepts/secrets-vault.md

@@ -0,0 +1,177 @@
+---
+title: Secrets & Vault
+description: Load configuration and credentials from a vault, hydrate them at boot, and rotate database credentials without a restart
+difficulty: intermediate
+---
+
+# Secrets & Vault
+
+IGNIS can load configuration and credentials from a vault instead of reading `process.env` directly. This guide shows how to enable it, how to consume secrets in your code, and how to rotate dynamic database credentials into a live pool without restarting the server.
+
+> [!TIP] You do not have to do anything to keep working as before
+> Until you override `registerSecrets()`, IGNIS uses the `system-envs` provider, which reads `process.env`. Everything below is opt-in.
+
+## The Mental Model
+
+Secrets reach your app through two paths:
+
+- **Hydrate** - at boot, IGNIS fetches secrets and merges them into `process.env` / `Envs`. Existing code that reads `process.env.APP_ENV_*` keeps working with no change.
+- **Provider** - the resolved provider is bound in the container at `@app/config`. Inject it wherever you need on-demand reads, dynamic credentials, or rotation.
+
+You configure both in one place: a `registerSecrets()` override on your application class.
+
+## Enabling a Provider
+
+Override `registerSecrets()` on your `Application extends BaseApplication`.
+
+### HashiCorp Vault
+
+Recommended for enterprise: KV v2 static secrets plus dynamic database credentials with automatic rotation.
+
+```typescript
+import { SecretProviders, VaultAuthMethods } from '@venizia/ignis-helpers';
+
+export class Application extends BaseApplication {
+  override registerSecrets() {
+    return {
+      provider: SecretProviders.HASHICORP_VAULT,
+
+      config: {
+        endpoint: 'https://vault.internal:8200',
+        // Dev: a raw token. Production: AppRole or Kubernetes.
+        auth: { method: VaultAuthMethods.APP_ROLE, roleId, secretId },
+        // or: { method: VaultAuthMethods.TOKEN, token }
+        // or: { method: VaultAuthMethods.KUBERNETES, role: 'my-app' }
+      },
+
+      // Static KV v2 secrets -> merged into Envs once at boot.
+      hydrate: [
+        { path: 'secret/data/myapp/config' },                    // keys land as-is
+        { path: 'secret/data/myapp/db', prefix: 'APP_ENV_DS_' }, // optional prefix
+        // { path: 'secret/data/myapp/db', keys: { password: 'APP_ENV_DS_PASSWORD' } },
+      ],
+
+      // Dynamic engine secrets -> renewed and rotated automatically.
+      lease: [
+        { key: 'datasources.PostgresDataSource', path: 'database/creds/app-role' },
+      ],
+    };
+  }
+}
+```
+
+`node-vault` is an optional peer. Install it in the application that uses this provider:
+
+```bash
+bun add node-vault
+```
+
+Applications that do not use this provider never need it - not even when compiling a binary with
+`Bun.build`. If your application uses this provider **and** compiles a binary, ship `node-vault` in
+`node_modules` next to the binary, or inject a ready-made `client` through the helper options.
+
+### Dotenv Vault
+
+An encrypted `.env.vault` file decrypted at runtime with a per-environment `DOTENV_KEY`. Static only.
+
+```typescript
+import { SecretProviders } from '@venizia/ignis-helpers';
+
+export class Application extends BaseApplication {
+  override registerSecrets() {
+    return {
+      provider: SecretProviders.DOTENV_VAULT,
+      config: { path: '.env.vault', dotenvKey: process.env.DOTENV_KEY },
+      hydrate: [{ path: 'ignored' }], // decrypts the file and merges it into Envs
+    };
+  }
+}
+```
+
+```bash
+bun add @dotenvx/dotenvx
+```
+
+### System Env (default)
+
+The default; shown here only to be explicit. Reads `process.env`, no dependencies.
+
+```typescript
+override registerSecrets() {
+  return { provider: SecretProviders.SYSTEM_ENVS };
+}
+```
+
+## Addressing and Merging
+
+Each `hydrate` entry resolves a path to a flat key-value object that is merged into `Envs` and `process.env`:
+
+- **Convention** - store the keys in the vault already named `APP_ENV_...` and they merge as-is, no mapping needed.
+- **`prefix`** - prepend a string to every merged key.
+- **`keys`** - an explicit `vaultKey -> envKey` map for precise control (wins over `prefix`).
+
+When the provider is live, vault values take precedence over `process.env`.
+
+## Reading Secrets in Your Code
+
+Inject the provider bound at `@app/config`.
+
+```typescript
+import type { ISecretsHelper } from '@venizia/ignis-helpers';
+
+@service()
+export class BillingService {
+  constructor(
+    @inject({ key: '@app/config' }) private secrets: ISecretsHelper,
+  ) {}
+
+  async run() {
+    // A single keyed value (TTL-cached):
+    const apiKey = await this.secrets.get({ path: 'secret/data/myapp/stripe', key: 'apiKey' });
+
+    // Or the whole bundle at a path:
+    const bundle = await this.secrets.getBundle({ path: 'secret/data/myapp/stripe' });
+  }
+}
+```
+
+Code that only relies on hydrated values keeps reading `process.env.APP_ENV_*` and needs no injection at all.
+
+## Rotating Database Credentials
+
+Dynamic secrets let Vault mint short-lived database credentials that expire and rotate. IGNIS renews them and, on rotation, rebuilds the connection pool gracefully.
+
+You do **not** write any rotation code for PostgreSQL. Two steps enable it:
+
+1. Configure a dynamic database engine in Vault so a read against `database/creds/<role>` returns fresh credentials with a TTL.
+2. Add a `lease` entry whose `key` is the DI binding key of your datasource (`datasources.<ClassName>`), as in the HashiCorp example above.
+
+From there IGNIS:
+
+- renews the lease before it expires;
+- when Vault issues fresh credentials, calls the datasource's `onSecretRotated()`, which swaps the new credentials in, builds a new pool, and drains the old one so in-flight transactions finish;
+- keeps the app running - no restart.
+
+> [!WARNING] Your datasource configure() must read from this.settings
+> Rotation writes the new credentials onto `this.settings` and re-runs `configure()`. If your `configure()` builds the pool from a hard-coded connection string instead, rotation rebuilds with stale credentials. Build the pool from `this.settings`:
+> ```typescript
+> override configure(): void {
+>   this.client = new Pool(this.settings);
+> }
+> ```
+
+## Behaviour When the Vault Is Down
+
+The failure policy is keyed on `NODE_ENV`:
+
+- **Development** (`local`, `debug`, `development`, `dev`, `sit`) - a vault failure logs a warning and falls back to `process.env`, so you can work offline.
+- **Everything else** - a vault failure throws and crashes the boot. The app never starts with missing or empty secrets.
+
+## Testing Against a Real Vault
+
+A local end-to-end setup (Vault dev-mode plus a throwaway PostgreSQL) is described in `docs/superpowers/vault-integration-local-testing.md` in the repository.
+
+## See Also
+
+- [Secrets & Vault Reference](/references/base/secrets) - full API, machinery, and const-classes
+- [DataSources](/guides/core-concepts/persistent/datasources) - the pool that rotation rebuilds

package/content/guides/core-concepts/services.md

@@ -57,7 +57,7 @@ export class UserService extends BaseService {
 
 ## Registering a Service
 
-Registration is always imperative - call `this.service(ClassName)` inside an application lifecycle method. Do not add `@injectable` to services; `this.service()` handles the binding.
+Registration is always imperative - call `this.service(ClassName)` inside an application lifecycle method, which handles the binding. There is no class-level decorator for this.
 
 ```typescript
 import { BaseApplication } from '@venizia/ignis';

package/content/guides/migrations/redis-helpers-migration.md

@@ -155,7 +155,7 @@ If you wrapped `subscribe(...)` in a `try/catch` expecting it to throw, that bra
 
 These are new and do not break anything:
 
-- **`RedisSentinelHelper`** - Redis Sentinel topology with automatic failover. See the [Redis Helper reference](/extensions/helpers/redis/) (Sentinel section).
+- **`RedisSentinelHelper`** - Redis Sentinel topology with automatic failover. See the [Redis Helper full reference](/extensions/helpers/redis/reference#construction-sentinel) (Sentinel section).
 - **`createRedisHelper({ mode })`** - a factory that builds the right helper from `RedisModes.SINGLE | CLUSTER | SENTINEL`, so you can pick a topology from config.
 - **`RedisModes`** and **`RedisSentinelRoles`** - const-classes for the enumerable mode/role strings, with matching `TRedisMode` / `TRedisSentinelRole` types.
 - **Expanded data API** - key lifecycle and counters (`exists`, `expire`, `expireAt`, `ttl`, `persist`, `incr`, `decr`, `incrBy`, `decrBy`), hash completion (`hGet`, `hDel`, `hExists`, `hKeys`, `hVals`, `hIncrBy`, `hLen`), sets (`sAdd`, `sRem`, `sMembers`, `sIsMember`, `sCard`), and lists (`lPush`, `rPush`, `lPop`, `rPop`, `lRange`, `lLen`).

package/content/guides/migrations/unified-connectors-migration.md

@@ -16,7 +16,7 @@ IGNIS core was restructured around ONE engine-neutral repository family:
 - `src/base` now holds a single `AbstractRepository` / `AbstractDataSource` / `AbstractEntity` family. Every engine implements it under `src/connectors/{postgres,typesense}`.
 - Postgres remains re-exported from the root barrel - **your imports keep working unchanged**. Every connector is also addressable explicitly: `@venizia/ignis/postgres`, `@venizia/ignis/typesense` (typesense is subpath-only; its client is an optional peer).
 - Canonical class names are the paradigm-family names (`BaseRelationalDataSource`, `BaseRelationalEntity`, `DefaultRelationalRepository`, ...); the engine name appears only at the concrete datasource (`TypesenseDataSource`) and the query dialect (`PostgresQueryOperators`). The historical names (`BaseDataSource`, `BaseEntity`, `BasePostgresDataSource`, `BasePostgresEntity`, `RDBQueryOperators`, `DefaultCRUDRepository`, ...) all remain as alias re-exports of the SAME classes - `instanceof`, metadata, and bindings are unaffected. No action required; prefer the family names in new code.
-- New capabilities model: `dataSource.getCapabilities()` and a standardized NotSupported error (HTTP 501, messageCode `core.not_supported`) for engine gaps (e.g. transactions on search engines).
+- New capabilities model: `dataSource.getCapabilities()` and a standardized NotSupported error (HTTP 501, `normalized.code` `core.not_supported`) for engine gaps (e.g. transactions on search engines).
 - New engine: the **Typesense search branch** (`BaseSearchEntity`, `defineSearchCollection`, typed `TSearchDocument`, `DefaultSearchRepository`). It does not affect existing postgres code.
 
 ## Required migrations (in order)
@@ -78,7 +78,7 @@ Run this once after the version bump, before trusting the first `tsc` run.
 
 ### 4. Auth endpoint error contract (only if you assert on it)
 
-The three auth endpoints backed by unimplemented service methods (`refreshToken`, `getUserInformation`) now return the standardized NotSupported error: HTTP 501 with messageCode `core.not_supported` and message `[AuthController] <feature> is not supported.` (previously a plain `Method not implemented`). BANA was scanned: no code asserts on the old string - listed for completeness.
+The three auth endpoints backed by unimplemented service methods (`refreshToken`, `getUserInformation`) now return the standardized NotSupported error: HTTP 501 with `normalized.code` `core.not_supported` and message `[AuthController] <feature> is not supported.` (previously a plain `Method not implemented`). BANA was scanned: no code asserts on the old string - listed for completeness.
 
 ## Strongly recommended (not compile-blocking)
 

package/content/guides/tutorials/building-a-crud-api.md

@@ -179,7 +179,7 @@ import {
   datasource,
   ValueOrPromise,
 } from '@venizia/ignis';
-import { drizzle } from 'drizzle-orm/node-postgres';
+import { NodePostgresDriver } from '@venizia/ignis/postgres/node-postgres';
 import { Pool } from 'pg';
 
 interface IDSConfigs {
@@ -195,15 +195,14 @@ interface IDSConfigs {
  *
  * How it works:
  * 1. @repository decorator binds model to datasource
- * 2. When configure() is called, getSchema() auto-discovers all bound models
- * 3. Drizzle is initialized with the auto-discovered schema
+ * 2. getSchema() auto-discovers all bound models when the driver/connector are wired
+ * 3. Naming NodePostgresDriver in @datasource is what wires the driver and Drizzle connector
  */
-@datasource({ driver: 'node-postgres' })
+@datasource({ driver: NodePostgresDriver })
 export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
   constructor() {
     super({
       name: PostgresDataSource.name,
-      // Driver is read from @datasource decorator - no need to pass here!
       config: {
         host: process.env.APP_ENV_POSTGRES_HOST ?? 'localhost',
         port: +(process.env.APP_ENV_POSTGRES_PORT ?? 5432),
@@ -216,11 +215,8 @@ export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
   }
 
   override configure(): ValueOrPromise<void> {
-    // getSchema() auto-discovers models from @repository bindings
-    const schema = this.getSchema();
-
-    // Log discovered schema for debugging
-    const schemaKeys = Object.keys(schema);
+    // getSchema() auto-discovers models from @repository bindings; log it for debugging
+    const schemaKeys = Object.keys(this.getSchema());
     this.logger.debug(
       '[configure] Auto-discovered schema | Schema + Relations (%s): %o',
       schemaKeys.length,
@@ -228,9 +224,9 @@ export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
     );
 
     // The client must land on this.client - a local would leave beginTransaction() with nothing
-    // to resolve a driver from, and it would throw `No driver and no client`.
+    // to resolve a driver from, and it would throw `No driver and no client`. NodePostgresDriver
+    // named in @datasource above is what wires the driver and Drizzle connector from it.
     this.client = new Pool(this.settings);
-    this.connector = drizzle({ client: this.client, schema });
   }
 }
 ```
@@ -239,7 +235,7 @@ export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
 - Schema is auto-discovered from `@repository` decorators - no manual registration needed
 - Uses `getSchema()` for lazy schema resolution (resolves when all models are loaded)
 - Uses environment variables for connection config
-- Implements `configure()` for connection setup and `getConnectionString()` for URL generation
+- `configure()` only assigns `this.client` - the base class wires the driver and connector from `@datasource({ driver })`; implements `getConnectionString()` for URL generation
 
 > **Deep Dive:** See [DataSources Reference](/references/base/datasources) for advanced configuration and multiple database support.
 

package/content/guides/tutorials/ecommerce-api.md

@@ -357,7 +357,7 @@ import {
   datasource,
   ValueOrPromise,
 } from '@venizia/ignis';
-import { drizzle } from 'drizzle-orm/node-postgres';
+import { NodePostgresDriver } from '@venizia/ignis/postgres/node-postgres';
 import { Pool } from 'pg';
 
 interface IDSConfigs {
@@ -368,7 +368,7 @@ interface IDSConfigs {
   password: string;
 }
 
-@datasource({ driver: 'node-postgres' })
+@datasource({ driver: NodePostgresDriver })
 export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
   constructor() {
     super({
@@ -384,18 +384,18 @@ export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
   }
 
   override configure(): ValueOrPromise<void> {
-    const schema = this.getSchema();
+    const schema = Object.keys(this.getSchema());
 
     this.logger.debug(
       '[configure] Auto-discovered schema | Schema + Relations (%s): %o',
-      Object.keys(schema).length,
-      Object.keys(schema),
+      schema.length,
+      schema,
     );
 
     // The client must land on this.client - a local would leave beginTransaction() with nothing
-    // to resolve a driver from, and it would throw `No driver and no client`.
+    // to resolve a driver from, and it would throw `No driver and no client`. NodePostgresDriver
+    // named in @datasource above is what wires the driver and Drizzle connector from it.
     this.client = new Pool(this.settings);
-    this.connector = drizzle({ client: this.client, schema });
   }
 }
 ```
@@ -526,12 +526,11 @@ export class OrderRepository extends DefaultCRUDRepository<typeof Order.schema>
 
 ```typescript
 // src/services/product.service.ts
-import { injectable, inject } from '@venizia/ignis';
+import { inject } from '@venizia/ignis';
 import { BaseService } from '@venizia/ignis';
 import { ProductRepository } from '../repositories/product.repository';
 import { getError } from '@venizia/ignis-helpers';
 
-@injectable({})
 export class ProductService extends BaseService {
   constructor(
     @inject({ key: 'repositories.ProductRepository' })
@@ -595,7 +594,7 @@ export class ProductService extends BaseService {
 
 ```typescript
 // src/services/cart.service.ts
-import { injectable, inject } from '@venizia/ignis';
+import { inject } from '@venizia/ignis';
 import { BaseService } from '@venizia/ignis';
 import { CartRepository } from '../repositories/cart.repository';
 import { ProductService } from './product.service';
@@ -606,7 +605,6 @@ interface ICartItem {
   quantity: number;
 }
 
-@injectable({})
 export class CartService extends BaseService {
   constructor(
     @inject({ key: 'repositories.CartRepository' })
@@ -733,7 +731,7 @@ export class CartService extends BaseService {
 
 ```typescript
 // src/services/order.service.ts
-import { injectable, inject } from '@venizia/ignis';
+import { inject } from '@venizia/ignis';
 import { BaseService } from '@venizia/ignis';
 import { OrderRepository } from '../repositories/order.repository';
 import { CartService } from './cart.service';
@@ -758,7 +756,6 @@ interface ICreateOrderInput {
   billingAddress?: IOrderAddress;
 }
 
-@injectable({})
 export class OrderService extends BaseService {
   constructor(
     @inject({ key: 'repositories.OrderRepository' })
@@ -906,12 +903,10 @@ export class OrderService extends BaseService {
 
 ```typescript
 // src/services/payment.service.ts
-import { injectable } from '@venizia/ignis';
 import { BaseService } from '@venizia/ignis';
 import Stripe from 'stripe';
 import { applicationEnvironment } from '@venizia/ignis-helpers';
 
-@injectable({})
 export class PaymentService extends BaseService {
   private _stripe: Stripe;