@venizia/ignis-docs 0.0.8-0 → 0.0.8-2

package/wiki/extensions/components/authorization/usage.md

@@ -485,6 +485,7 @@ import { Authorization, Authentication } from '@venizia/ignis';
 const user = c.get(Authentication.CURRENT_USER);  // IAuthUser
 const rules = c.get(Authorization.RULES);           // unknown (type depends on enforcer)
 const isSkipped = c.get(Authorization.SKIP_AUTHORIZATION); // boolean
+const domain = c.get(Authorization.DOMAIN);         // string ("<Type>_<id>" | "SYSTEM_WIDE"), set when domain scoping is in play
 
 // Set skip dynamically
 c.set(Authorization.SKIP_AUTHORIZATION, true);
@@ -493,66 +494,6 @@ c.set(Authorization.SKIP_AUTHORIZATION, true);
 c.set(Authorization.RULES, null);
 ```
 
-## Using IAuthorizationComparable
-
-For custom action/resource comparison logic beyond plain string equality, implement `IAuthorizationComparable`.
-
-### StringAuthorizationAction with Wildcard
-
-The built-in `StringAuthorizationAction` supports a wildcard (`*`) that matches any action:
-
-```typescript
-import { StringAuthorizationAction } from '@venizia/ignis';
-
-const wildcard = StringAuthorizationAction.build({ value: '*' });
-wildcard.isEqual('read');    // true — wildcard matches all
-wildcard.isEqual('delete');  // true — wildcard matches all
-wildcard.isEqual('create');  // true — wildcard matches all
-
-const readOnly = StringAuthorizationAction.build({ value: 'read' });
-readOnly.isEqual('read');    // true
-readOnly.isEqual('update');  // false
-```
-
-### StringAuthorizationResource
-
-Standard string comparison for resources (no wildcard):
-
-```typescript
-import { StringAuthorizationResource } from '@venizia/ignis';
-
-const article = StringAuthorizationResource.build({ value: 'Article' });
-article.isEqual('Article');  // true
-article.isEqual('User');     // false
-```
-
-### Custom Comparable Implementation
-
-Create your own comparable type for advanced matching:
-
-```typescript
-import type { IAuthorizationComparable } from '@venizia/ignis';
-
-class HierarchicalResource implements IAuthorizationComparable<string> {
-  readonly value: string;
-
-  constructor(opts: { value: string }) {
-    this.value = opts.value;
-  }
-
-  compare(other: string): number {
-    // Match if the other resource starts with this resource's value
-    // e.g., 'articles' matches 'articles.comments'
-    if (other.startsWith(this.value)) return 0;
-    return this.value.localeCompare(other);
-  }
-
-  isEqual(other: string): boolean {
-    return this.compare(other) === 0;
-  }
-}
-```
-
 ## Custom Enforcer
 
 Create a custom enforcer by implementing `IAuthorizationEnforcer`:
@@ -645,60 +586,50 @@ AuthorizationEnforcerRegistry.getInstance().register({
 
 ## Custom Filtered Adapter
 
-Create a custom adapter by extending `BaseFilteredAdapter`:
+For most apps, use the ready-made [`ScopedCasbinAdapter`](./api#scopedcasbinadapter) — it reads a single
+edge table and needs no subclassing. Write a custom adapter only when your storage model differs.
+
+`BaseFilteredAdapter` is now thin: it provides the datasource/connector plumbing, the `isFiltered()`
+flag, no-op write methods, and a `loadLines` helper. A subclass implements **only** `loadFilteredPolicy`
+— query your store for ONE principal's policies and turn them into casbin lines.
 
 ```typescript
 import {
   BaseFilteredAdapter,
-  IBaseFilteredAdapterEntities,
   ICasbinPolicyFilter,
-  TBasePolicyRow,
+  type IDataSource,
 } from '@venizia/ignis';
+import type { Model } from 'casbin';
 
-interface MyEntities extends IBaseFilteredAdapterEntities {
-  permission: { tableName: string; principalType: string };
-  role: { tableName: string; principalType: string };
-  policyDefinition: { tableName: string; principalType: string };
-}
-
-class MyCustomAdapter extends BaseFilteredAdapter<MyEntities> {
-  constructor(opts: { entities: MyEntities; /* your dependencies */ }) {
-    super({ scope: MyCustomAdapter.name, entities: opts.entities });
+// Narrow the filter if you like, or use the default ICasbinPolicyFilter ({ principal: { type, id } }).
+class MyCustomAdapter extends BaseFilteredAdapter<ICasbinPolicyFilter> {
+  constructor(opts: { dataSource: IDataSource }) {
+    super({ scope: MyCustomAdapter.name, dataSource: opts.dataSource });
   }
 
-  protected async buildDirectPolicies(opts: {
-    filter: ICasbinPolicyFilter;
-    rolePrincipal: string;
-  }): Promise<string[]> {
-    // Query direct permission policies for the user
-    // Return casbin `p` lines using this.toPolicyLine()
-    const rows = await this.queryDirectPolicies(opts.filter);
-    return rows.map(row => this.toPolicyLine({ row })).filter(Boolean) as string[];
-  }
+  async loadFilteredPolicy(model: Model, filter: ICasbinPolicyFilter): Promise<void> {
+    const { type, id } = filter.principal;
+
+    // 1. Query your store for THIS principal's policies (this.connector is provided by the base).
+    // 2. Build casbin lines as plain strings, e.g.:
+    //      `p, User_${id}, Order, read, allow`
+    //      `g, User_${id}, Role_42, *`
+    const lines: string[] = await this.buildLinesFor({ type, id });
 
-  protected async buildGroupPolicies(opts: {
-    filter: ICasbinPolicyFilter;
-  }): Promise<{ lines: string[]; roleIds: (string | number)[] }> {
-    // Query role assignments for the user
-    // Return casbin `g` lines using this.toGroupLine() + role IDs
-    return { lines: [...], roleIds: [...] };
+    // 3. Load them into the model with the base helper.
+    await this.loadLines({ model, lines });
   }
 
-  protected async buildRolePolicies(opts: {
-    roleIds: (string | number)[];
-    rolePrincipal: string;
-  }): Promise<string[]> {
-    // Query permission policies inherited through roles
-    // Return casbin `p` lines using this.toPolicyLine()
-    return [...];
+  private async buildLinesFor(principal: { type: string; id: unknown }): Promise<string[]> {
+    // ...your queries via this.connector...
+    return [];
   }
 }
 ```
 
-The base class provides shared formatters:
-- `this.formatDomain(domain)` -- adds entity prefix to domain values
-- `this.toGroupLine({ subject, role, domain })` -- formats `g` lines
-- `this.toPolicyLine({ row })` -- formats `p` lines
+The base no longer ships template-method hooks (`buildDirectPolicies`/`buildGroupPolicies`/…) or line
+formatters — you own line construction. See `ScopedCasbinAdapter` for a full reference implementation
+(role closure, structural trees, soft-delete, schema-qualified SQL).
 
 ## AuthorizationRole Comparison
 
@@ -789,6 +720,175 @@ const settings = registry.getAuthorizeModelSettings({ format: 'array' });
 > [!TIP]
 > Defining `authorize.principal` on the model makes the model the single source of truth for its authorization subject. This eliminates string duplication across route configs and policy setup.
 
+## RBAC with Domains (Multi-Tenant)
+
+For multi-tenant apps where a user holds roles **scoped to specific tenants** (and sometimes globally), use Casbin's [RBAC with domains](https://casbin.apache.org/docs/rbac-with-domains/) model and register a **domain matching function** via `domainMatching`. This lets the domain slot of a grouping (`g`) policy use a wildcard, so a global role is a single line (`g, user, role, *`) and role permissions stay domain-agnostic (`p, role, *, …`).
+
+> [!TIP]
+> Why this matters: putting the tenant on the membership (`g`) and keeping permissions wildcard (`p.dom = "*"`) keeps a user's materialized policy count **linear** (`memberships + permissions`) instead of the `permissions × tenants` cross-product. For a user with 30 tenants and 700 permissions that is ~730 lines instead of ~21,000.
+
+There are two ways to do domain scoping:
+
+- **Scoped model (recommended)** — set `isScoped: true` + use `ScopedCasbinAdapter` + the built-in
+  `CASBIN_RBAC_DOMAIN_SCOPED_MODEL`, and supply the request domain **per route** via `spec.domain` (or a
+  global `domainResolver`). The enforcer registers the matchers for you; you do not write `domainMatching`
+  or `normalizePayloadFn`.
+- **Manual flat model (lower-level)** — keep a flat `g + p` model and register `domainMatching` +
+  `normalizePayloadFn` yourself. Documented below under [The model](#the-model).
+
+### Scoped model + per-route domain (recommended)
+
+Register the scoped enforcer (see [Setup](./#step-3-register-enforcers-via-registry)) with `isScoped: true`,
+then tell each route where to read its domain from. `IAuthorizationSpec.domain` accepts either a
+**declarative source** or a **resolver function**:
+
+```typescript
+import type { IAuthorizationDomainSource, TAuthorizationDomainResolver } from '@venizia/ignis';
+
+// (a) Declarative — read the domain id from a request param/header/query/context var:
+authorize({
+  spec: {
+    action: 'read',
+    resource: 'Order',
+    domain: { from: 'param', key: 'merchantId', type: 'Merchant' }, // → "Merchant_<param>"
+  },
+});
+
+// (b) Resolver — compute { type, id } yourself (return null → SYSTEM_WIDE):
+authorize({
+  spec: {
+    action: 'read',
+    resource: 'Order',
+    domain: ({ context }) => {
+      const merchantId = resolveActiveMerchant({ context });
+      return merchantId ? { type: 'Merchant', id: merchantId } : null;
+    },
+  },
+});
+```
+
+Precedence (see `resolveRequestDomain`): `spec.domain` (resolver → declarative) → the global
+`IAuthorizeOptions.domainResolver` → `SYSTEM_WIDE`. The resolved value is stashed on
+`Authorization.DOMAIN` and passed to the enforcer as `request.domain`. A route with no domain at all
+enforces `SYSTEM_WIDE` (super-admin scope) in scoped mode.
+
+For a **global fallback** (apply the same resolver to every route that doesn't set `spec.domain`):
+
+```typescript
+this.bind<IAuthorizeOptions>({ key: AuthorizeBindingKeys.OPTIONS }).toValue({
+  defaultDecision: 'deny',
+  domainResolver: ({ context }) => {
+    const id = resolveActiveMerchant({ context });
+    return id ? { type: 'Merchant', id } : null;
+  },
+});
+```
+
+### The model
+
+```ini
+[request_definition]
+r = sub, dom, obj, act
+
+[policy_definition]
+p = sub, dom, obj, act, eft
+
+[role_definition]
+g = _, _, _
+
+[policy_effect]
+e = some(where (p.eft == allow)) && !some(where (p.eft == deny))
+
+[matchers]
+m = g(r.sub, p.sub, r.dom) && keyMatch(r.dom, p.dom) && r.obj == p.obj && r.act == p.act
+```
+
+- `g = _, _, _` — the membership relation is **domain-aware** (subject, role, domain).
+- `g(r.sub, p.sub, r.dom)` — the registered domain matching function decides whether the request domain matches the stored membership domain (this is what makes `*` a wildcard).
+- `keyMatch(r.dom, p.dom)` — `keyMatch` is a **built-in matcher function** (no registration needed); it lets a permission with `p.dom = "*"` match any request domain.
+
+### Registering the domain matching function
+
+Pass `domainMatching` in the enforcer options. It is registered once during `configure()`:
+
+```typescript
+import {
+  AuthorizationEnforcerRegistry,
+  AuthorizationEnforcerTypes,
+  CasbinAuthorizationEnforcer,
+  CasbinDomainMatchingFunctions,
+  CasbinEnforcerModelDrivers,
+  type ICasbinEnforcerOptions,
+} from '@venizia/ignis';
+
+AuthorizationEnforcerRegistry.getInstance().register({
+  container: this,
+  enforcers: [
+    {
+      enforcer: CasbinAuthorizationEnforcer,
+      name: 'casbin',
+      type: AuthorizationEnforcerTypes.CASBIN,
+      options: {
+        model: { driver: CasbinEnforcerModelDrivers.TEXT, definition: CASBIN_RBAC_MODEL },
+        adapter,
+        cached,
+        // For a domain model, normalizePayloadFn MUST always return a `domain`.
+        normalizePayloadFn: ({ user, action, resource, context }) => ({
+          subject: `User_${user.userId}`,
+          domain: `Merchant_${resolveActiveMerchant({ context })}`,
+          resource,
+          action,
+        }),
+        // Register keyMatch on the `g` role definition so wildcard domains work:
+        domainMatching: { roleDefinition: 'g', fn: CasbinDomainMatchingFunctions.KEY_MATCH },
+      } satisfies ICasbinEnforcerOptions,
+    },
+  ],
+});
+```
+
+> [!NOTE]
+> `domainMatching` is opt-in. When omitted, domains are compared as exact strings and behavior is unchanged. The enforcer calls Casbin's `addNamedDomainMatchingFunc(roleDefinition, Util.keyMatchFunc)` internally — you never call it directly.
+
+### Choosing the matching function
+
+`keyMatch` is the safe default for opaque domain identifiers like `Merchant_<uuid>`: it treats only `*` as special and never splits on `/` or `:`, so it cannot accidentally match one tenant against another. Use the others only if your domains are structured paths.
+
+```typescript
+domainMatching: { roleDefinition: 'g', fn: CasbinDomainMatchingFunctions.KEY_MATCH };   // * wildcard (recommended)
+domainMatching: { roleDefinition: 'g', fn: CasbinDomainMatchingFunctions.KEY_MATCH_2 };  // /tenants/:id
+domainMatching: { roleDefinition: 'g', fn: CasbinDomainMatchingFunctions.KEY_MATCH_3 };  // /tenants/{id}
+domainMatching: { roleDefinition: 'g', fn: CasbinDomainMatchingFunctions.REGEX_MATCH };  // ^Merchant_.*$
+```
+
+### All cases — policy lines and outcomes
+
+Given the model above with `keyMatch` registered on `g`, the request is `enforceSync(subject, domain, resource, action)`:
+
+| Case | Policy lines | Request | Outcome |
+|------|--------------|---------|---------|
+| **Scoped role** (owner/employee in a tenant) | `g, User_u, Role_owner, Merchant_A`<br/>`p, Role_owner, *, Material.find, read, allow` | `(User_u, Merchant_A, Material.find, read)` | ✅ allow |
+| **Scoped role — isolation** | (same as above) | `(User_u, Merchant_B, Material.find, read)` | ❌ deny (`g` domain doesn't match) |
+| **Multi-tenant role** | `g, User_u, Role_owner, Merchant_A`<br/>`g, User_u, Role_owner, Merchant_B`<br/>`p, Role_owner, *, Material.find, read, allow` | `(User_u, Merchant_B, Material.find, read)` | ✅ allow (one `g` line per owned tenant; **single** `p` line) |
+| **Global role** (e.g. guest/onboarding) | `g, User_u, Role_guest, *`<br/>`p, Role_guest, *, Organizer.onBoarding, create, allow` | `(User_u, Merchant_anything, Organizer.onBoarding, create)` | ✅ allow (wildcard `g` domain) |
+| **Direct user permission (scoped)** | `p, User_u, Merchant_A, Report.read, read, allow` | `(User_u, Merchant_A, Report.read, read)` | ✅ allow (reflexive `g(u,u,dom)` + `keyMatch`) |
+| **Direct user permission — isolation** | (same as above) | `(User_u, Merchant_B, Report.read, read)` | ❌ deny |
+| **Deny override** | `p, Role_x, *, Secret.read, read, deny`<br/>`p, Role_y, *, Secret.read, read, allow` | any domain where the user has both roles | ❌ deny (`!some(p.eft == deny)`) |
+
+> [!IMPORTANT]
+> The function is applied as `fn(requestDomain, policyDomain)` — the wildcard belongs on the **stored** side. Store only `*` or exact domain values (never `Merchant_*`) to keep isolation guaranteed.
+
+### Misconfiguration is caught early
+
+If `roleDefinition` is not declared under `[role_definition]` in the model, `configure()` throws — Casbin would otherwise register the function as a silent no-op, leaving wildcard domains permanently unmatched (global roles silently denied):
+
+```typescript
+// model declares `g` only
+domainMatching: { roleDefinition: 'g2', fn: CasbinDomainMatchingFunctions.KEY_MATCH };
+// => throws: Role definition "g2" is not declared in the Casbin model. Declare it under
+//    [role_definition] (e.g. `g = _, _, _`) before enabling domainMatching.
+```
+
 ## See Also
 
 - [Setup & Configuration](./) -- Binding keys, options interfaces, and initial setup

package/wiki/extensions/helpers/kafka/consumer.md

@@ -21,9 +21,10 @@ class KafkaConsumerHelper<
 | `start(opts)` | `(opts: IKafkaConsumeStartOptions): Promise<void>` | Start consuming (creates stream, wires callbacks) |
 | `startLagMonitoring(opts)` | `(opts: { topics: string[]; interval?: number }): void` | Start periodic lag monitoring |
 | `stopLagMonitoring()` | `(): void` | Stop lag monitoring |
-| `isHealthy()` | `(): boolean` | `true` when broker connected |
+| `isHealthy()` | `(): boolean` | `true` when at least one broker connected |
 | `isReady()` | `(): boolean` | `isHealthy()` **and** `consumer.isActive()` |
 | `getHealthStatus()` | `(): TKafkaHealthStatus` | `'connected'` \| `'disconnected'` \| `'unknown'` |
+| `getConnectedBrokerCount()` | `(): number` | Number of currently connected brokers |
 | `close(opts?)` | `(opts?: { isForce?: boolean }): Promise<void>` | Stop lag, close stream, close consumer |
 
 ## IKafkaConsumerOptions
@@ -41,8 +42,8 @@ interface IKafkaConsumerOptions<KeyType, ValueType, HeaderKeyType, HeaderValueTy
 | `identifier` | `string` | `'kafka-consumer'` | Scoped logging identifier |
 | `deserializers` | `Partial<Deserializers<K,V,HK,HV>>` | -- | Key/value/header deserializers |
 | `autocommit` | `boolean \| number` | `false` | Auto-commit offsets. `true` = default interval, `number` = custom ms |
-| `sessionTimeout` | `number` | `30000` | Session timeout -- consumer removed from group if no heartbeat |
-| `heartbeatInterval` | `number` | `3000` | Heartbeat interval -- must be less than `sessionTimeout` |
+| `sessionTimeout` | `number` | `60000` | Session timeout -- consumer removed from group if no heartbeat |
+| `heartbeatInterval` | `number` | `10000` | Heartbeat interval -- must be less than `sessionTimeout` |
 | `rebalanceTimeout` | `number` | `sessionTimeout` | Max time for rebalance. Defaults to the value of `sessionTimeout` |
 | `highWaterMark` | `number` | `1024` | Stream buffer size (messages) |
 | `minBytes` | `number` | `1` | Min bytes per fetch response |
@@ -141,8 +142,8 @@ await helper.start({ topics: ['orders'] });
 helper.startLagMonitoring({ topics: ['orders'], interval: 10_000 });
 
 // Health check
-helper.isHealthy(); // true when broker connected
-helper.isReady();   // true when broker connected AND consumer is active
+helper.isHealthy(); // true when at least one broker connected
+helper.isReady();   // true when at least one broker connected AND consumer is active
 
 // Shutdown
 await helper.close();

package/wiki/extensions/helpers/kafka/examples.md

@@ -318,7 +318,7 @@ export class OrderEventService {
 | `Failed to deserialize a message` | Mismatch between serializer and deserializer | Ensure matching serde. For old data, use a new consumer group or recreate topic |
 | `JSON.stringify cannot serialize BigInt` | `message.offset` and `message.timestamp` are `bigint` | Use custom replacer: `(_k, v) => typeof v === 'bigint' ? v.toString() : v` |
 | Consumer idle (no messages) | More consumers than partitions | Ensure `numPartitions >= numConsumers` |
-| `isHealthy()` returns `false` | No broker connected yet, or connection lost | Check broker addresses, SASL config, network connectivity |
+| `isHealthy()` returns `false` | All brokers disconnected (a single idle disconnect won't trigger this) | Check broker addresses, SASL config, network connectivity. Use `getConnectedBrokerCount()` for details |
 | `isReady()` returns `false` (consumer) | Consumer not active -- `start()` not called or stream closed | Call `await helper.start({ topics })` before checking readiness |
 | Graceful shutdown timeout | In-flight requests taking too long | Increase `shutdownTimeout` or use `close({ isForce: true })` |
 

package/wiki/extensions/helpers/kafka/index.md

@@ -16,9 +16,9 @@ The Kafka module provides four helper classes built on a shared `BaseKafkaHelper
 All helpers (except schema registry) extend `BaseKafkaHelper` which provides:
 
 - **Scoped logging** via `BaseHelper` (Winston with daily rotation)
-- **Health tracking** -- `isHealthy()`, `isReady()`, `getHealthStatus()`
+- **Health tracking** -- per-broker connection tracking via `isHealthy()`, `isReady()`, `getHealthStatus()`, `getConnectedBrokerCount()`
 - **Broker event callbacks** -- `onBrokerConnect`, `onBrokerDisconnect`
-- **Broker failure tracking** -- automatic `configureBrokerFailed()` sets status to `'disconnected'`
+- **Broker failure tracking** -- automatic `configureBrokerFailed()` sets status to `'disconnected'` only when all brokers are gone
 - **Graceful shutdown** -- timeout-based with force fallback
 - **Sensible defaults** via `KafkaDefaults` constants
 - **Factory pattern** via `newInstance()` static method
@@ -115,21 +115,25 @@ All Kafka helpers (except schema registry) extend `BaseKafkaHelper<TClient>`, wh
 ```typescript
 abstract class BaseKafkaHelper<TClient extends Base<BaseOptions>> extends BaseHelper {
   // Health
-  isHealthy(): boolean;          // healthStatus === 'connected'
-  isReady(): boolean;            // healthStatus === 'connected' (consumer overrides: + isActive())
-  getHealthStatus(): TKafkaHealthStatus; // 'connected' | 'disconnected' | 'unknown'
+  isHealthy(): boolean;              // true when at least one broker is connected
+  isReady(): boolean;                // healthStatus === 'connected' (consumer overrides: + isActive())
+  getHealthStatus(): TKafkaHealthStatus;  // 'connected' | 'disconnected' | 'unknown'
+  getConnectedBrokerCount(): number; // number of currently connected brokers
 
   // Shutdown (used by subclasses)
   protected closeClient(): Promise<void>;
   protected gracefulCloseClient(): Promise<void>; // races closeClient vs shutdownTimeout
+  protected resetHealthState(): void;             // clears broker tracking + sets 'disconnected'
 }
 ```
 
+Health tracking uses a **per-broker connection set** (`host:port` keys). A single idle broker disconnect does not make the client unhealthy -- only when **all** brokers are disconnected does `isHealthy()` return `false`.
+
 Health status transitions automatically via broker events:
-- `client:broker:connect` -> `'connected'`
-- `client:broker:disconnect` -> `'disconnected'`
-- `client:broker:failed` -> `'disconnected'`
-- `close()` -> `'disconnected'`
+- `client:broker:connect` -> adds broker, sets `healthStatus` to `'connected'`
+- `client:broker:disconnect` -> removes broker, sets `healthStatus` to `'disconnected'` only when all brokers are gone
+- `client:broker:failed` -> removes broker, sets `healthStatus` to `'disconnected'` only when all brokers are gone
+- `close()` -> clears all brokers, sets `healthStatus` to `'disconnected'`
 
 ## Connection Options
 
@@ -400,8 +404,8 @@ import { KafkaDefaults } from '@venizia/ignis-helpers/kafka';
 | `STRICT` | `true` | Producer | Fail on unknown topics |
 | `AUTOCREATE_TOPICS` | `false` | Producer | Auto-create topics on produce |
 | `AUTOCOMMIT` | `false` | Consumer | Auto-commit offsets |
-| `SESSION_TIMEOUT` | `30000` | Consumer | Session timeout in ms |
-| `HEARTBEAT_INTERVAL` | `3000` | Consumer | Heartbeat interval in ms |
+| `SESSION_TIMEOUT` | `60000` | Consumer | Session timeout in ms |
+| `HEARTBEAT_INTERVAL` | `10000` | Consumer | Heartbeat interval in ms |
 | `HIGH_WATER_MARK` | `1024` | Consumer | Stream buffer size (messages) |
 | `MIN_BYTES` | `1` | Consumer | Min bytes per fetch |
 | `METADATA_MAX_AGE` | `300000` | Consumer | Metadata cache TTL in ms |
@@ -570,7 +574,7 @@ const consumer = KafkaConsumerHelper.newInstance({
 
 ```typescript
 // All three -- identical API
-helper.isHealthy();      // true when broker connected
+helper.isHealthy();      // true when at least one broker connected
 helper.isReady();        // Admin/Producer: same as isHealthy()
                          // Consumer: isHealthy() + consumer.isActive()
 helper.getHealthStatus(); // 'connected' | 'disconnected' | 'unknown'

package/wiki/extensions/helpers/kafka/producer.md

@@ -18,9 +18,10 @@ class KafkaProducerHelper<
 | `newInstance(opts)` | `static newInstance<K,V,HK,HV>(opts): KafkaProducerHelper<K,V,HK,HV>` | Factory method |
 | `getProducer()` | `(): Producer<K,V,HK,HV>` | Access the underlying `Producer` |
 | `runInTransaction(cb)` | `<R>(cb: TKafkaTransactionCallback<R,K,V,HK,HV>): Promise<R>` | Execute callback within a Kafka transaction |
-| `isHealthy()` | `(): boolean` | `true` when broker connected |
+| `isHealthy()` | `(): boolean` | `true` when at least one broker connected |
 | `isReady()` | `(): boolean` | Same as `isHealthy()` |
 | `getHealthStatus()` | `(): TKafkaHealthStatus` | `'connected'` \| `'disconnected'` \| `'unknown'` |
+| `getConnectedBrokerCount()` | `(): number` | Number of currently connected brokers |
 | `close(opts?)` | `(opts?: { isForce?: boolean }): Promise<void>` | Close the producer (default: graceful) |
 
 ## IKafkaProducerOptions
@@ -64,7 +65,7 @@ const helper = KafkaProducerHelper.newInstance({
 });
 
 // Health check
-helper.isHealthy();      // true when connected
+helper.isHealthy();      // true when at least one broker connected
 helper.getHealthStatus(); // 'connected' | 'disconnected' | 'unknown'
 
 // Send messages via the underlying producer
@@ -153,7 +154,7 @@ If the callback throws, the transaction is automatically aborted and the error r
 2. **Force fallback**: If graceful times out, automatically force-closes
 3. **Force** (`{ isForce: true }`): Immediately calls `close(true)` without timeout protection
 
-After `close()`, `healthStatus` is set to `'disconnected'`.
+After `close()`, all broker tracking is cleared and `healthStatus` is set to `'disconnected'`.
 
 ```typescript
 // Graceful (recommended)

package/wiki/guides/core-concepts/persistent/datasources.md

@@ -12,7 +12,6 @@ A DataSource manages database connections and supports **schema auto-discovery**
 import {
   BaseDataSource,
   datasource,
-  TNodePostgresConnector,
   ValueOrPromise,
 } from '@venizia/ignis';
 import { drizzle } from 'drizzle-orm/node-postgres';
@@ -32,11 +31,11 @@ export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
     super({
       name: PostgresDataSource.name,
       config: {
-        host: process.env.POSTGRES_HOST ?? 'localhost',
-        port: +(process.env.POSTGRES_PORT ?? 5432),
-        database: process.env.POSTGRES_DATABASE ?? 'mydb',
-        user: process.env.POSTGRES_USER ?? 'postgres',
-        password: process.env.POSTGRES_PASSWORD ?? '',
+        host: process.env.APP_ENV_POSTGRES_HOST ?? 'localhost',
+        port: +(process.env.APP_ENV_POSTGRES_PORT ?? 5432),
+        database: process.env.APP_ENV_POSTGRES_DATABASE ?? 'mydb',
+        user: process.env.APP_ENV_POSTGRES_USERNAME ?? 'postgres',
+        password: process.env.APP_ENV_POSTGRES_PASSWORD ?? '',
       },
       // No schema needed - auto-discovered from @repository bindings!
     });
@@ -148,11 +147,11 @@ export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
     super({
       name: PostgresDataSource.name,
       config: {
-        host: process.env.POSTGRES_HOST ?? 'localhost',
-        port: +(process.env.POSTGRES_PORT ?? 5432),
-        database: process.env.POSTGRES_DATABASE ?? 'mydb',
-        user: process.env.POSTGRES_USER ?? 'postgres',
-        password: process.env.POSTGRES_PASSWORD ?? '',
+        host: process.env.APP_ENV_POSTGRES_HOST ?? 'localhost',
+        port: +(process.env.APP_ENV_POSTGRES_PORT ?? 5432),
+        database: process.env.APP_ENV_POSTGRES_DATABASE ?? 'mydb',
+        user: process.env.APP_ENV_POSTGRES_USERNAME ?? 'postgres',
+        password: process.env.APP_ENV_POSTGRES_PASSWORD ?? '',
       },
     });
   }

package/wiki/guides/core-concepts/persistent/index.md

@@ -46,16 +46,16 @@ export class User extends BaseEntity<typeof User.schema> {
 
 // 2. Create a DataSource
 @datasource({ driver: 'node-postgres' })
-export class PostgresDataSource extends BaseDataSource<TNodePostgresConnector, IDSConfigs> {
+export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
   constructor() {
     super({
       name: PostgresDataSource.name,
       config: {
-        host: process.env.POSTGRES_HOST ?? 'localhost',
-        port: +(process.env.POSTGRES_PORT ?? 5432),
-        database: process.env.POSTGRES_DATABASE ?? 'mydb',
-        user: process.env.POSTGRES_USER ?? 'postgres',
-        password: process.env.POSTGRES_PASSWORD ?? '',
+        host: process.env.APP_ENV_POSTGRES_HOST ?? 'localhost',
+        port: +(process.env.APP_ENV_POSTGRES_PORT ?? 5432),
+        database: process.env.APP_ENV_POSTGRES_DATABASE ?? 'mydb',
+        user: process.env.APP_ENV_POSTGRES_USERNAME ?? 'postgres',
+        password: process.env.APP_ENV_POSTGRES_PASSWORD ?? '',
       },
     });
   }

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

@@ -6,15 +6,17 @@ Models define your data structure using Drizzle ORM schemas. A model is a single
 
 ```typescript
 // src/models/entities/user.model.ts
-import { BaseEntity, extraUserColumns, generateIdColumnDefs, model } from '@venizia/ignis';
-import { pgTable } from 'drizzle-orm/pg-core';
+import { BaseEntity, generateIdColumnDefs, generateTzColumnDefs, model } from '@venizia/ignis';
+import { pgTable, text } from 'drizzle-orm/pg-core';
 
 @model({ type: 'entity' })
 export class User extends BaseEntity<typeof User.schema> {
   // Define schema as static property
   static override schema = pgTable('User', {
     ...generateIdColumnDefs({ id: { dataType: 'string' } }),
-    ...extraUserColumns({ idType: 'string' }),
+    ...generateTzColumnDefs(),
+    name: text('name').notNull(),
+    email: text('email').notNull(),
   });
 
   // Relations (empty array if none)
@@ -126,7 +128,8 @@ static override schema = pgTable('User', {
 ```typescript
 static override schema = pgTable('User', {
   ...generateIdColumnDefs({ id: { dataType: 'string' } }),  // id (text with UUID default)
-  ...extraUserColumns({ idType: 'string' }),                 // status, audit fields, timestamps
+  ...generateTzColumnDefs(),                                 // createdAt, modifiedAt
+  ...generateUserAuditColumnDefs(),                          // createdBy, modifiedBy
   // ... your fields
 });
 ```
@@ -139,7 +142,6 @@ static override schema = pgTable('User', {
 | `generateTzColumnDefs()` | `createdAt`, `modifiedAt` | Track timestamps |
 | `generateUserAuditColumnDefs()` | `createdBy`, `modifiedBy` | Track who created/updated |
 | `generateDataTypeColumnDefs()` | `dataType`, `tValue`, `nValue`, etc. | Configuration tables |
-| `extraUserColumns()` | Combines audit + status + type | Full-featured entities |
 
 :::note User Audit Options
 The `generateUserAuditColumnDefs` enricher supports an `allowAnonymous` option (default: `true`). Set to `false` to require authenticated user context and throw errors for anonymous operations:

package/wiki/guides/core-concepts/persistent/repositories.md

@@ -159,10 +159,18 @@ All repository operations accept an `options` parameter with these fields:
 | `shouldSkipDefaultFilter` | `boolean` | Bypass the model's default filter (e.g., soft delete) |
 
 ```typescript
-// Create without returning data (faster for bulk inserts)
+// Create without returning data (faster)
 await repo.create({
-  data: bulkData,
-  options: { shouldReturn: false }
+  data: { code: 'SETTING', group: 'SYSTEM' },
+  options: { shouldReturn: false },
+});
+
+// Bulk create multiple records
+await repo.createAll({
+  data: [
+    { code: 'SETTING_A', group: 'SYSTEM' },
+    { code: 'SETTING_B', group: 'SYSTEM' },
+  ],
 });
 
 // Query with pagination range

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

@@ -62,7 +62,8 @@ Ignis supports standard PostgreSQL isolation levels:
 | `REPEATABLE READ` | Queries see a snapshot as of the start of the transaction. | Reports, consistent reads across multiple queries. |
 | `SERIALIZABLE` | Strictest level. Emulates serial execution. | Financial transactions, critical data integrity. |
 
-Note: `READ UNCOMMITTED` is technically accepted but behaves as `READ COMMITTED` in PostgreSQL.
+> [!NOTE]
+> Ignis only supports these three levels. `READ UNCOMMITTED` is **not** accepted — PostgreSQL treats it as `READ COMMITTED` anyway, so Ignis omits it to avoid confusion.
 
 ## Best Practices
 

package/wiki/guides/core-concepts/rest-controllers.md

@@ -218,7 +218,7 @@ this.bindRoute({
 For standard CRUD (Create, Read, Update, Delete) operations, `Ignis` provides a `ControllerFactory` that can generate a full-featured controller for any given entity. This significantly reduces boilerplate code.
 
 ```typescript
-// src/controllers/configuration.controller.ts (Example from @examples/vert)
+// src/controllers/configuration/configuration.controller.ts (Example from @examples/vert)
 import { Configuration } from '@/models';
 import { ConfigurationRepository } from '@/repositories';
 import {
@@ -236,7 +236,7 @@ const _Controller = ControllerFactory.defineCrudController({
   controller: {
     name: 'ConfigurationController',
     basePath: BASE_PATH,
-    isStrict: true,
+    isStrict: { path: true, requestSchema: true },
   },
   entity: () => Configuration, // Provide a resolver for your entity class
 });

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

@@ -19,7 +19,6 @@ To create a service, extend the `BaseService` class and inject the repositories
 
 ```typescript
 import { BaseService, inject } from '@venizia/ignis';
-import { getError } from '@venizia/ignis-helpers';
 import { ConfigurationRepository } from '../repositories';
 import { UserRepository } from '../repositories';
 import { LoggingService } from './logging.service'; // Example of another service