@venizia/ignis-docs 0.2.0 → 0.2.1-0

package/content/extensions/helpers/worker-thread/reference.md

@@ -0,0 +1,428 @@
+---
+title: Worker Thread - Full Reference
+description: Complete reference for WorkerPoolHelper, BaseWorkerHelper, BaseWorkerThreadHelper, BaseWorkerBusHelper, and every constructor option and error message
+difficulty: intermediate
+---
+
+# Worker Thread - Full Reference
+
+Exhaustive reference for the worker-thread classes, every constructor option, event-handler default, and troubleshooting case. For a readable introduction and the common tasks, start with the [Worker Thread overview](/extensions/helpers/worker-thread/).
+
+**Files:**
+
+- [`packages/helpers/src/modules/worker-thread/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/worker-thread/base.ts) - `AbstractWorkerHelper`, `BaseWorkerHelper`, `AbstractWorkerThreadHelper`, `BaseWorkerThreadHelper`
+- [`packages/helpers/src/modules/worker-thread/worker-bus.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/worker-thread/worker-bus.ts) - `AbstractWorkerBusHelper`, `BaseWorkerBusHelper`, `AbstractWorkerMessageBusHandlerHelper`, `BaseWorkerMessageBusHandlerHelper`
+- [`packages/helpers/src/modules/worker-thread/worker-pool.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/worker-thread/worker-pool.ts) - `WorkerPoolHelper`
+- [`packages/helpers/src/modules/worker-thread/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/worker-thread/types.ts) - `IWorker`, `IWorkerThread`, `IWorkerBus`, `IWorkerMessageBusHandler`
+- [`packages/helpers/src/modules/worker-thread/index.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/worker-thread/index.ts) - barrel
+
+## Quick Reference
+
+| Class | Extends | Use Case |
+|-------|---------|----------|
+| `WorkerPoolHelper` | `BaseHelper` | Singleton registry that tracks and limits active worker instances |
+| `BaseWorkerHelper<MessageType>` | `AbstractWorkerHelper<MessageType>` | Wraps a `Worker` with event lifecycle hooks (online, exit, error, message) |
+| `BaseWorkerThreadHelper` | `AbstractWorkerThreadHelper` | Runs inside a worker thread; manages named `WorkerBus` channels |
+| `BaseWorkerBusHelper<IC, IP>` | `AbstractWorkerBusHelper<IC, IP>` | Bidirectional `MessagePort` communication with pre/post hooks |
+| `BaseWorkerMessageBusHandlerHelper<IC>` | `AbstractWorkerMessageBusHandlerHelper<IC>` | Defines event handlers for a worker bus (message, close, error, exit) |
+
+| Item | Value |
+|------|-------|
+| **Package** | `@venizia/ignis-helpers` |
+| **Peer Dependency** | None (uses built-in `node:worker_threads`) |
+| **Runtimes** | Node.js (uses `node:worker_threads` and `node:os`) |
+
+### Import paths
+
+```typescript
+import {
+  WorkerPoolHelper,
+  BaseWorkerHelper,
+  BaseWorkerThreadHelper,
+  BaseWorkerBusHelper,
+  BaseWorkerMessageBusHandlerHelper,
+  AbstractWorkerHelper,
+  AbstractWorkerThreadHelper,
+  AbstractWorkerBusHelper,
+  AbstractWorkerMessageBusHandlerHelper,
+} from '@venizia/ignis-helpers';
+
+import type {
+  IWorker,
+  IWorkerThread,
+  IWorkerBus,
+  IWorkerMessageBusHandler,
+} from '@venizia/ignis-helpers';
+```
+
+## WorkerPoolHelper
+
+`Source ->` [`worker-pool.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/worker-thread/worker-pool.ts)
+
+Singleton registry for active workers. Limits the pool size to the number of CPU cores by default.
+
+```typescript
+import { WorkerPoolHelper } from '@venizia/ignis-helpers';
+
+// Get the singleton instance
+const pool = WorkerPoolHelper.getInstance();
+
+// Or construct a custom instance directly
+const customPool = new WorkerPoolHelper({ ignoreMaxWarning: true });
+```
+
+> [!NOTE]
+> `WorkerPoolHelper.getInstance()` always creates the singleton with `ignoreMaxWarning: false`. To override this behavior, construct a new instance manually - the singleton and a manually-constructed instance are independent registries.
+
+### Constructor options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `ignoreMaxWarning` | `boolean` | `false` | When `true`, allows registering workers beyond the CPU core count. When `false`, registration is skipped once the pool reaches the CPU core limit. |
+
+### Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `getInstance` | `static getInstance(): WorkerPoolHelper` | Returns the singleton pool instance (creates one with `ignoreMaxWarning: false` if needed) |
+| `register` | `register<MessageType>(opts: { key: string; worker: IWorker<MessageType> }): boolean` | Adds a worker to the pool. Returns `false` and logs instead of registering if the key already exists or the pool is at the CPU limit |
+| `unregister` | `async unregister(opts: { key: string }): Promise<void>` | Terminates the worker (`worker.terminate()`) and removes it from the pool. The registry entry is deleted even if termination throws |
+| `get` | `get<MessageType>(opts: { key: string }): IWorker<MessageType> \| undefined` | Retrieves a registered worker by key |
+| `has` | `has(opts: { key: string }): boolean` | Checks if a worker is registered under the given key |
+| `size` | `size(): number` | Returns the number of currently registered workers |
+
+> [!WARNING]
+> When the pool reaches the CPU core limit and `ignoreMaxWarning` is `false`, further `register()` calls return `false` and log a warning. No error is thrown.
+
+## BaseWorkerHelper (main thread worker wrapper)
+
+`Source ->` [`base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/worker-thread/base.ts)
+
+Creates a `Worker` from a file path and automatically binds all lifecycle events.
+
+```typescript
+import { BaseWorkerHelper } from '@venizia/ignis-helpers';
+
+const worker = new BaseWorkerHelper<MyMessageType>({
+  identifier: 'data-processor',
+  path: './workers/data-processor.js',
+  options: { workerData: { batchSize: 100 } },
+  eventHandlers: {
+    onMessage: opts => console.log('Received:', opts.message),
+    onError: opts => console.error('Worker error:', opts.error),
+  },
+});
+```
+
+### Constructor options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `identifier` | `string` | - | A unique name for this worker instance, used as the `BaseHelper` identifier and in log output. Required. |
+| `path` | `string \| URL` | - | Path to the worker script file, passed directly to `new Worker()`. Required. |
+| `options` | `WorkerOptions` (Node.js) | - | Passed directly to `new Worker()`. Required. Supports `workerData`, `transferList`, `env`, etc. |
+| `scope` | `string` | `'BaseWorkerHelper'` | Accepted but currently ignored - the constructor always sets the logger scope to `BaseWorkerHelper.name`, not `opts.scope`. |
+| `eventHandlers` | `Partial<Pick<IWorker<MessageType>, 'onOnline' \| 'onExit' \| 'onError' \| 'onMessage' \| 'onMessageError'>>` | `undefined` | Optional overrides for lifecycle event callbacks. Any handler not provided falls back to default logging behavior. |
+
+### Event handler overrides
+
+| Handler | Signature | Default behavior |
+|---------|-----------|-------------------|
+| `onOnline` | `() => ValueOrPromise<void>` | Logs `"Worker ONLINE"` at info level |
+| `onExit` | `(opts: { code: string \| number }) => ValueOrPromise<void>` | Logs `"Worker EXIT | Code: %s"` at warn level |
+| `onError` | `(opts: { error: Error }) => ValueOrPromise<void>` | Logs `"Worker ERROR | Error: %s"` at error level |
+| `onMessage` | `(opts: { message: MessageType }) => ValueOrPromise<void>` | Logs `"Worker MESSAGE | message: %j"` at error level |
+| `onMessageError` | `(opts: { error: Error }) => ValueOrPromise<void>` | Logs `"Worker MESSAGE_ERROR | Error: %s"` at error level |
+
+### Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `binding` | `binding(): void` | Binds all five event handlers (`online`, `exit`, `error`, `message`, `messageerror`) to the internal `Worker` instance. Called automatically by the constructor. Throws `[binding] Invalid worker instance to bind event handlers` if `this.worker` is falsy |
+
+Every handler runs through `invokeHook`, which wraps the call in a `try/catch`: a synchronous throw inside a user handler is caught and logged (`"Hook execution FAILED | Error: %s"`) rather than crashing the process. Async rejections are settled the same way via `voidExecution`.
+
+### AbstractWorkerHelper (subclassing)
+
+For full control, extend `AbstractWorkerHelper` and implement all five lifecycle methods directly instead of passing `eventHandlers`:
+
+```typescript
+import { AbstractWorkerHelper } from '@venizia/ignis-helpers';
+
+class CustomWorker extends AbstractWorkerHelper<MyMessage> {
+  onOnline() {
+    // Custom online handling
+  }
+
+  onExit(opts: { code: string | number }) {
+    // Custom exit handling, e.g., restart logic
+  }
+
+  onError(opts: { error: Error }) {
+    // Custom error handling
+  }
+
+  onMessage(opts: { message: MyMessage }) {
+    // Custom message processing
+  }
+
+  onMessageError(opts: { error: Error }) {
+    // Custom message error handling
+  }
+}
+```
+
+`AbstractWorkerHelper<MessageType>` declares `worker: Worker`, `options: WorkerOptions`, and the five abstract lifecycle methods above; it does not implement `binding()` itself.
+
+## BaseWorkerThreadHelper (inside a worker thread)
+
+`Source ->` [`base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/worker-thread/base.ts)
+
+Used inside a worker script to manage named communication buses. Must be instantiated from within a worker thread - constructing it on the main thread throws.
+
+```typescript
+// Inside worker-script.js
+import { BaseWorkerThreadHelper } from '@venizia/ignis-helpers';
+
+const thread = new BaseWorkerThreadHelper({ scope: 'DataProcessor' });
+```
+
+### Constructor options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `scope` | `string` | - | Logger scope and `BaseHelper` identifier for this worker thread. Required. |
+
+The constructor checks `isMainThread` (from `node:worker_threads`) and throws `[BaseWorker] Cannot start worker in MAIN_THREAD` if `true`.
+
+### Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `bindWorkerBus` | `bindWorkerBus<IC, IP>(opts: { key: string; bus: IWorkerBus<IC, IP> }): void` | Registers a bus under the given key. Logs a warning and returns without overwriting if the key already exists |
+| `unbindWorkerBus` | `unbindWorkerBus(opts: { key: string }): void` | Calls `port.removeAllListeners()` on the bus's port, then deletes it from the registry. Logs a warning if the key is not found |
+| `getWorkerBus` | `getWorkerBus<IC, IP>(opts: { key: string }): IWorkerBus<IC, IP>` | Returns the bus for the given key. Throws `[getWorkerBus] Not found worker bus | key: {key}` if not found |
+
+`unbindWorkerBus` is defined only on `BaseWorkerThreadHelper`, not on the `AbstractWorkerThreadHelper` interface - `AbstractWorkerThreadHelper` declares `buses`, `bindWorkerBus`, and `getWorkerBus` as abstract.
+
+## BaseWorkerMessageBusHandlerHelper
+
+`Source ->` [`worker-bus.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/worker-thread/worker-bus.ts)
+
+Defines the event callbacks for a worker bus.
+
+```typescript
+const handler = new BaseWorkerMessageBusHandlerHelper<MyPayload>({
+  scope: 'ProcessorHandler',
+  onMessage: opts => console.log('Processing:', opts.message),
+  onError: opts => console.error('Bus error:', opts.error),
+});
+```
+
+### Constructor options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `scope` | `string` | - | Logger scope and identifier. Required. |
+| `onMessage` | `(opts: { message: IConsumePayload }) => ValueOrPromise<void>` | - | Handler called when a message is received on the port. Required. |
+| `onClose` | `() => ValueOrPromise<void>` | No-op `() => {}` | Handler called when the port emits `close`. |
+| `onError` | `(opts: { error: Error }) => ValueOrPromise<void>` | Logs `"worker error: %s"` at error level | Handler called on port `error` and `messageerror` events. |
+| `onExit` | `(opts: { exitCode: number \| string }) => ValueOrPromise<void>` | Logs `"worker EXITED | exitCode: %s"` at warn level | Handler called when the port emits `exit`. |
+
+## BaseWorkerBusHelper (MessagePort communication)
+
+`Source ->` [`worker-bus.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/worker-thread/worker-bus.ts)
+
+Wraps a `MessagePort` to provide structured bidirectional messaging with lifecycle event handlers.
+
+```typescript
+import { BaseWorkerBusHelper, BaseWorkerMessageBusHandlerHelper } from '@venizia/ignis-helpers';
+import { parentPort } from 'node:worker_threads';
+
+const handler = new BaseWorkerMessageBusHandlerHelper<IncomingMessage>({
+  scope: 'MyBusHandler',
+  onMessage: opts => console.log('Received:', opts.message),
+});
+
+const bus = new BaseWorkerBusHelper<IncomingMessage, OutgoingMessage>({
+  scope: 'MyBus',
+  port: parentPort!,
+  busHandler: handler,
+});
+```
+
+### Constructor options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `scope` | `string` | - | Logger scope and identifier. Required. |
+| `port` | `MessagePort` | - | The `MessagePort` to bind for communication. Required. |
+| `busHandler` | `IWorkerMessageBusHandler<IConsumePayload>` | - | Handler that receives incoming messages and lifecycle events. Required. |
+
+The constructor binds `message`, `error`, `messageerror`, `exit`, and `close` listeners on `port`, each routed through the handler's matching callback (`error` and `messageerror` both call `handler.onError`).
+
+### Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `postMessage` | `postMessage(opts: { message: IPublishPayload; transferList: readonly Transferable[] \| undefined }): ValueOrPromise<void>` | Sends a message through the port. If `transferList` is provided, calls `port.postMessage(message, [...transferList])`; otherwise `port.postMessage(message)`. Logs and returns (does not throw) if `port` is falsy |
+
+### Pre/post message hooks
+
+`onBeforePostMessage` and `onAfterPostMessage` are optional properties declared on the class but left `undefined` by the constructor - assign them after construction:
+
+```typescript
+bus.onBeforePostMessage = opts => {
+  console.log('About to send:', opts.message);
+};
+
+bus.onAfterPostMessage = opts => {
+  console.log('Sent:', opts.message);
+};
+```
+
+`postMessage` invokes `onBeforePostMessage` (if set) before the port write and `onAfterPostMessage` (if set) after, both through the same `try/catch`-wrapped `invokeHook` used for the port event listeners.
+
+### Sending transferable objects
+
+```typescript
+// Send a simple message
+bus.postMessage({
+  message: { result: 'processed' },
+  transferList: undefined,
+});
+
+// Send with transferable objects (zero-copy)
+const buffer = new ArrayBuffer(1024);
+bus.postMessage({
+  message: { result: 'binary-data' },
+  transferList: [buffer],
+});
+```
+
+## Types
+
+`Source ->` [`types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/worker-thread/types.ts)
+
+```typescript
+interface IWorker<MessageType> {
+  worker: Worker;
+  options: WorkerOptions;
+
+  onOnline(): ValueOrPromise<void>;
+  onExit(opts: { code: string | number }): ValueOrPromise<void>;
+  onError(opts: { error: Error }): ValueOrPromise<void>;
+  onMessage(opts: { message: MessageType }): ValueOrPromise<void>;
+  onMessageError(opts: { error: Error }): ValueOrPromise<void>;
+}
+
+interface IWorkerThread {
+  buses: { [workerKey: string | symbol]: IWorkerBus<AnyType, AnyType> };
+}
+
+interface IWorkerMessageBusHandler<IConsumePayload> {
+  onMessage: (opts: { message: IConsumePayload }) => ValueOrPromise<void>;
+  onClose: () => ValueOrPromise<void>;
+  onError: (opts: { error: Error }) => ValueOrPromise<void>;
+  onExit: (opts: { exitCode: number | string }) => ValueOrPromise<void>;
+}
+
+interface IWorkerBus<IConsumePayload, IPublishPayload> {
+  port: MessagePort;
+  handler: IWorkerMessageBusHandler<IConsumePayload>;
+
+  onBeforePostMessage?(opts: { message: IPublishPayload }): ValueOrPromise<void>;
+  onAfterPostMessage?(opts: { message: IPublishPayload }): ValueOrPromise<void>;
+  postMessage(opts: {
+    message: IPublishPayload;
+    transferList: readonly Transferable[] | undefined;
+  }): ValueOrPromise<void>;
+}
+```
+
+## Troubleshooting
+
+### "[BaseWorker] Cannot start worker in MAIN_THREAD"
+
+**Cause:** `BaseWorkerThreadHelper` was instantiated on the main thread. This class is designed to run only inside a worker thread (where `isMainThread` from `node:worker_threads` is `false`).
+
+**Fix:** Only create `BaseWorkerThreadHelper` instances inside worker scripts that are spawned via `new Worker(path)`:
+
+```typescript
+// worker-script.js (spawned by the main thread)
+import { BaseWorkerThreadHelper } from '@venizia/ignis-helpers';
+
+const thread = new BaseWorkerThreadHelper({ scope: 'MyWorker' }); // OK here
+```
+
+### "[binding] Invalid worker instance to bind event handlers"
+
+**Cause:** `BaseWorkerHelper.binding()` was called but the internal `Worker` instance is falsy. This can occur if the worker script path is invalid and the `Worker` constructor fails.
+
+**Fix:** Ensure the `path` passed to `BaseWorkerHelper` points to a valid, existing JavaScript file:
+
+```typescript
+const worker = new BaseWorkerHelper({
+  identifier: 'my-worker',
+  path: './workers/my-worker.js', // Must exist and be a valid worker script
+  options: {},
+});
+```
+
+### "[register] Invalid worker registry instance | please init registry before register new worker!"
+
+**Cause:** `WorkerPoolHelper.register()` was called but the internal registry `Map` is falsy. This is a defensive check that should not occur under normal usage.
+
+**Fix:** Ensure you are using either `WorkerPoolHelper.getInstance()` or `new WorkerPoolHelper()`, both of which initialize the registry in the constructor.
+
+### "[getWorkerBus] Not found worker bus | key: {key}"
+
+**Cause:** `BaseWorkerThreadHelper.getWorkerBus()` was called with a key that has not been registered via `bindWorkerBus()`.
+
+**Fix:** Verify the bus was bound before retrieving it:
+
+```typescript
+thread.bindWorkerBus({ key: 'my-bus', bus: myBus });
+
+// Now safe to retrieve
+const bus = thread.getWorkerBus({ key: 'my-bus' });
+```
+
+### "Failed to post message to main | Invalid parentPort!"
+
+**Cause:** `BaseWorkerBusHelper.postMessage()` was called but the `port` property is falsy. This typically means the bus was constructed with an invalid `MessagePort`. This is logged at error level, not thrown - the message is silently dropped.
+
+**Fix:** Ensure a valid `MessagePort` (e.g., `parentPort` from `node:worker_threads` or a port from `new MessageChannel()`) is passed to the constructor:
+
+```typescript
+import { parentPort } from 'node:worker_threads';
+
+const bus = new BaseWorkerBusHelper({
+  scope: 'MyBus',
+  port: parentPort!, // Must be a valid MessagePort
+  busHandler: handler,
+});
+```
+
+### Worker pool silently skips registration
+
+**Cause:** The pool has reached the CPU core limit and `ignoreMaxWarning` is `false` (the default for `getInstance()`). `register()` returns `false` and logs a warning instead of throwing.
+
+**Fix:** Either free up pool slots first, or create a pool with `ignoreMaxWarning: true`:
+
+```typescript
+// Option 1: Free up pool slots
+await pool.unregister({ key: 'old-worker' });
+pool.register({ key: 'new-worker', worker: newWorker });
+
+// Option 2: Allow exceeding the limit
+const pool = new WorkerPoolHelper({ ignoreMaxWarning: true });
+```
+
+## See also
+
+- [Worker Thread overview](/extensions/helpers/worker-thread/) - introduction and the most common tasks
+- [Queue Helper](/extensions/helpers/queue/) - message-queue processing as an alternative to worker threads
+- [Node.js Worker Threads](https://nodejs.org/api/worker_threads.html) - official `worker_threads` documentation
+- [MessagePort API](https://nodejs.org/api/worker_threads.html#class-messageport) - underlying port communication
+- [Transferable Objects](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Transferable_objects) - zero-copy data transfer

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

@@ -200,7 +200,7 @@ const user = await userRepo.findById({ id: '123' });
 // { id: '123', email: 'john@example.com' }
 
 // Connector query - includes all fields
-const connector = userRepo.getConnector();
+const connector = userRepo.connector;
 const [fullUser] = await connector
   .select()
   .from(User.schema)

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

@@ -254,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 })`
@@ -413,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`).