@venizia/ignis-docs 0.0.8 → 0.2.0

package/content/guides/get-started/philosophy.md

@@ -1,6 +1,6 @@
 # Philosophy: The Best of Two Worlds
 
-Ignis combines the structured, enterprise-grade development experience of **LoopBack 4** with the speed and simplicity of **Hono**.
+IGNIS combines the structured, enterprise-grade development experience of **LoopBack 4** with the speed and simplicity of **Hono**.
 
 <div class="philosophy-hero">
 <div class="hero-content">
@@ -34,7 +34,7 @@ When building REST APIs and server applications with Node.js/Bun, developers cho
 
 <div class="landscape-card balanced">
 <div class="card-header">
-<h3>Ignis, Ts.ED</h3>
+<h3>IGNIS, Ts.ED</h3>
 <span class="card-badge">Balanced</span>
 </div>
 <p class="card-motto">Structure with lighter footprint</p>
@@ -86,7 +86,7 @@ When building REST APIs and server applications with Node.js/Bun, developers cho
 
 <div class="perf-row highlight">
 <div class="perf-info">
-<span class="perf-name">Ignis</span>
+<span class="perf-name">IGNIS</span>
 <span class="perf-meta">~30ms startup · ~30MB</span>
 </div>
 <div class="perf-bar-container">
@@ -162,7 +162,7 @@ When building REST APIs and server applications with Node.js/Bun, developers cho
 <th>Aspect</th>
 <th>Minimal (Hono/Express)</th>
 <th>Enterprise (NestJS/LoopBack)</th>
-<th class="highlight-col">Ignis</th>
+<th class="highlight-col">IGNIS</th>
 </tr>
 </thead>
 <tbody>
@@ -221,7 +221,7 @@ When building REST APIs and server applications with Node.js/Bun, developers cho
 <th>Feature</th>
 <th>Minimal</th>
 <th>Enterprise</th>
-<th class="highlight-col">Ignis</th>
+<th class="highlight-col">IGNIS</th>
 </tr>
 </thead>
 <tbody>
@@ -274,7 +274,7 @@ When building REST APIs and server applications with Node.js/Bun, developers cho
 <th>Aspect</th>
 <th>Hono</th>
 <th>NestJS</th>
-<th class="highlight-col">Ignis</th>
+<th class="highlight-col">IGNIS</th>
 </tr>
 </thead>
 <tbody>
@@ -330,7 +330,7 @@ When building REST APIs and server applications with Node.js/Bun, developers cho
 </table>
 </div>
 
-## The Ignis Synthesis
+## The IGNIS Synthesis
 
 <div class="synthesis">
 
@@ -359,7 +359,7 @@ When building REST APIs and server applications with Node.js/Bun, developers cho
 <div class="synthesis-operator">=</div>
 
 <div class="synthesis-box result">
-<h4>Ignis</h4>
+<h4>IGNIS</h4>
 <ul>
 <li>DI + Speed</li>
 <li>Structure + Simplicity</li>
@@ -400,7 +400,7 @@ When building REST APIs and server applications with Node.js/Bun, developers cho
 </div>
 
 <div class="excel-card ignis">
-<h3>Ignis</h3>
+<h3>IGNIS</h3>
 <p class="excel-subtitle">The balanced choice</p>
 <div class="excel-pros">
 <h4>Strengths</h4>
@@ -452,7 +452,7 @@ When building REST APIs and server applications with Node.js/Bun, developers cho
 
 </div>
 
-## When Should You Use Ignis?
+## When Should You Use IGNIS?
 
 <div class="decision-matrix">
 
@@ -530,7 +530,7 @@ When building REST APIs and server applications with Node.js/Bun, developers cho
 
 <div class="perfect-card">
 <h4>Production APIs</h4>
-<p>10-100+ endpoints with enterprise patterns. Controllers, services, repositories — all built-in and ready.</p>
+<p>10-100+ endpoints with enterprise patterns. Controllers, services, repositories - all built-in and ready.</p>
 </div>
 
 <div class="perfect-card">
@@ -557,42 +557,42 @@ When building REST APIs and server applications with Node.js/Bun, developers cho
 <div class="choose-card">
 <h3>Use Hono/Fastify/Express When:</h3>
 <ul>
-<li><strong>Simple webhook handler</strong> — No structure overhead needed</li>
-<li><strong>Edge/serverless functions</strong> — Minimal cold start, tiny bundle</li>
-<li><strong>Rapid prototyping</strong> — Get something running in minutes</li>
-<li><strong>1-5 endpoint microservices</strong> — Structure adds complexity</li>
-<li><strong>Maximum control needed</strong> — No conventions to follow</li>
-<li><strong>Learning web development</strong> — Simpler mental model</li>
+<li><strong>Simple webhook handler</strong> - No structure overhead needed</li>
+<li><strong>Edge/serverless functions</strong> - Minimal cold start, tiny bundle</li>
+<li><strong>Rapid prototyping</strong> - Get something running in minutes</li>
+<li><strong>1-5 endpoint microservices</strong> - Structure adds complexity</li>
+<li><strong>Maximum control needed</strong> - No conventions to follow</li>
+<li><strong>Learning web development</strong> - Simpler mental model</li>
 </ul>
 </div>
 
 <div class="choose-card">
 <h3>Use NestJS/LoopBack When:</h3>
 <ul>
-<li><strong>Large team (10+ developers)</strong> — Strong conventions prevent chaos</li>
-<li><strong>Enterprise with strict standards</strong> — Mature, battle-tested, auditable</li>
-<li><strong>Extensive ecosystem needed</strong> — Many official and community modules</li>
-<li><strong>Complex microservices</strong> — Built-in support for messaging, CQRS</li>
-<li><strong>Hiring is a priority</strong> — Large talent pool familiar with it</li>
-<li><strong>Long-term support critical</strong> — Corporate backing, LTS versions</li>
+<li><strong>Large team (10+ developers)</strong> - Strong conventions prevent chaos</li>
+<li><strong>Enterprise with strict standards</strong> - Mature, battle-tested, auditable</li>
+<li><strong>Extensive ecosystem needed</strong> - Many official and community modules</li>
+<li><strong>Complex microservices</strong> - Built-in support for messaging, CQRS</li>
+<li><strong>Hiring is a priority</strong> - Large talent pool familiar with it</li>
+<li><strong>Long-term support critical</strong> - Corporate backing, LTS versions</li>
 </ul>
 </div>
 
 <div class="choose-card highlight">
-<h3>Use Ignis When:</h3>
+<h3>Use IGNIS When:</h3>
 <ul>
-<li><strong>Any size API (10-100+ endpoints)</strong> — Structure without heavy overhead</li>
-<li><strong>Any team size</strong> — Scales from solo dev to enterprise teams</li>
-<li><strong>Performance matters</strong> — Hono's speed with enterprise patterns</li>
-<li><strong>Modern stack preferred</strong> — ESM native, Bun optimized, TypeScript-first</li>
-<li><strong>Coming from NestJS/LoopBack</strong> — Familiar patterns, better performance</li>
-<li><strong>Need built-in features</strong> — DI, validation, OpenAPI, auth ready to use</li>
+<li><strong>Any size API (10-100+ endpoints)</strong> - Structure without heavy overhead</li>
+<li><strong>Any team size</strong> - Scales from solo dev to enterprise teams</li>
+<li><strong>Performance matters</strong> - Hono's speed with enterprise patterns</li>
+<li><strong>Modern stack preferred</strong> - ESM native, Bun optimized, TypeScript-first</li>
+<li><strong>Coming from NestJS/LoopBack</strong> - Familiar patterns, better performance</li>
+<li><strong>Need built-in features</strong> - DI, validation, OpenAPI, auth ready to use</li>
 </ul>
 </div>
 
 </div>
 
-## Why Choose Ignis
+## Why Choose IGNIS
 
 <div class="tradeoffs">
 
@@ -603,7 +603,7 @@ When building REST APIs and server applications with Node.js/Bun, developers cho
 <li><span class="highlight-text">Built-in DI</span>, validation, OpenAPI, auth</li>
 <li><span class="highlight-text">Structured codebase</span> from day one</li>
 <li><span class="highlight-text">Easier testing</span> with dependency injection</li>
-<li><span class="highlight-text">Single file build</span> — compile to one executable with Bun</li>
+<li><span class="highlight-text">Single file build</span> - compile to one executable with Bun</li>
 <li><span class="highlight-text">Scales</span> from solo dev to enterprise teams</li>
 </ul>
 </div>
@@ -611,10 +611,10 @@ When building REST APIs and server applications with Node.js/Bun, developers cho
 <div class="tradeoff cost">
 <h3>What's Growing</h3>
 <ul>
-<li><span class="highlight-text">Community</span> — expanding every day</li>
-<li><span class="highlight-text">Documentation</span> — continuously improving</li>
-<li><span class="highlight-text">Ecosystem</span> — core features ready, plugins coming</li>
-<li><span class="highlight-text">LTS</span> — planning for long-term support</li>
+<li><span class="highlight-text">Community</span> - expanding every day</li>
+<li><span class="highlight-text">Documentation</span> - continuously improving</li>
+<li><span class="highlight-text">Ecosystem</span> - core features ready, plugins coming</li>
+<li><span class="highlight-text">LTS</span> - planning for long-term support</li>
 </ul>
 </div>
 

package/content/guides/get-started/setup.md

@@ -1,6 +1,6 @@
 # Setup
 
-Everything you need to start building with Ignis. This guide covers installation for macOS, Linux, and Windows (via WSL2).
+Everything you need to start building with IGNIS. This guide covers installation for macOS, Linux, and Windows (via WSL2).
 
 ## Requirements
 
@@ -153,5 +153,5 @@ sudo service postgresql start
 
 ## Next Steps
 
-- [5-Minute Quickstart](./5-minute-quickstart.md) — Build your first API
-- [Complete Installation](../tutorials/complete-installation.md) — Full project setup
+- [5-Minute Quickstart](./5-minute-quickstart.md) - Build your first API
+- [Complete Installation](../tutorials/complete-installation.md) - Full project setup

package/content/guides/index.md

@@ -1,6 +1,6 @@
-# Getting Started with Ignis
+# Getting Started with IGNIS
 
-Welcome to Ignis — a TypeScript framework that combines enterprise architecture patterns with Hono's blazing performance. Whether you're building a SaaS backend, REST API, gRPC service, or microservice, these guides will take you from installation to production-ready code with type-safe database operations, auto-generated OpenAPI docs, and clean dependency injection.
+Welcome to IGNIS - a TypeScript framework that combines enterprise architecture patterns with Hono's blazing performance. Whether you're building a SaaS backend, REST API, gRPC service, or microservice, these guides will take you from installation to production-ready code with type-safe database operations, auto-generated OpenAPI docs, and clean dependency injection.
 
 <div class="guide-cards">
 
@@ -31,7 +31,7 @@ Welcome to Ignis — a TypeScript framework that combines enterprise architectur
 
 <a href="./get-started/philosophy" class="guide-card">
 <h3>Philosophy</h3>
-<p>Why Ignis? Design decisions explained</p>
+<p>Why IGNIS? Design decisions explained</p>
 </a>
 
 </div>

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

@@ -0,0 +1,177 @@
+---
+title: Migrating to the new Redis Helper API
+description: Breaking changes and migration steps for the IGNIS Redis helper refactor - folder-per-topology, AbstractRedisHelper, camelCase methods, Sentinel, and the createRedisHelper factory
+---
+
+# Migrating to the new Redis Helper API
+
+> **Audience:** any application upgrading `@venizia/ignis-helpers` (and `@venizia/ignis`) across the Redis helper refactor release. This guide describes exactly what breaks and how to migrate. It applies to every consumer - it is not specific to any one app.
+
+---
+
+## 0. TL;DR
+
+The IGNIS Redis module was restructured into one base class plus three topologies (single / cluster / sentinel) behind a segregated `IRedisHelper` interface. Several public symbols were **renamed with no back-compat aliases (clean break)**, and the lowercase hash/multi methods were removed in favor of camelCase. Your project **will not compile** against the new version until you apply the renames in §1.
+
+Nothing in your data or Redis server changes - this is a code-level rename plus a few additive features. The single and cluster connection behavior is byte-for-byte identical to before; only the new `RedisSentinelHelper` introduces new behavior.
+
+| Effort | What |
+|--------|------|
+| **Low - mechanical renames** | Apply the rename table in §1 and the method renames in §1.2. Compiler-guided: every stale reference becomes a type error. |
+
+---
+
+## 1. What changed (breaking)
+
+### 1.1 Class and type renames (no aliases)
+
+| Old (removed) | New |
+|---------------|-----|
+| `DefaultRedisHelper` | `AbstractRedisHelper` |
+| `RedisHelper` | `RedisSingleHelper` |
+| `IRedisHelperOptions` | `IRedisSingleHelperOptions` |
+| `IRedisHelperProps` | `IRedisSingleHelperProps` |
+
+`RedisClusterHelper` is **unchanged** in name and behavior.
+
+`AbstractRedisHelper` is the base class (never constructed directly). Use it only where you need an `instanceof` check or a concrete-class binding; for plain typing prefer the `IRedisHelper` interface.
+
+### 1.2 Lowercase methods removed - use camelCase
+
+The duplicate lowercase aliases were removed. The camelCase forms are now the only API.
+
+| Old (removed) | New |
+|---------------|-----|
+| `.hset(...)` | `.hSet(...)` |
+| `.hgetall(...)` | `.hGetAll(...)` |
+| `.mset(...)` | `.mSet(...)` |
+| `.mget(...)` | `.mGet(...)` |
+
+Single-word methods (`get`, `set`, `del`, `keys`, `publish`, `subscribe`) are unchanged.
+
+### 1.3 Callback type narrowed
+
+`IRedisHelperCallbacks.onError` now receives `error: unknown` (was `error: any`). This only affects you if you access properties on `error` without narrowing first.
+
+---
+
+## 2. Find every affected site
+
+Run this in your project root. Every match is a site to migrate:
+
+```bash
+grep -rnE 'DefaultRedisHelper|\bRedisHelper\b|IRedisHelper(Options|Props)\b|\.(hset|mset|hgetall|mget)\(' src
+```
+
+`\bRedisHelper\b` matches the bare class only - it will not match `RedisClusterHelper` / `RedisSingleHelper`.
+
+After migrating, re-run it; a clean result plus a green `tsc` means you are done.
+
+---
+
+## 3. Migration steps (before / after)
+
+### Constructing a single-node connection
+
+```typescript
+// Before
+import { RedisHelper } from '@venizia/ignis-helpers';
+const redis = new RedisHelper({ name: 'cache', host, port, password });
+
+// After
+import { RedisSingleHelper } from '@venizia/ignis-helpers';
+const redis = new RedisSingleHelper({ name: 'cache', host, port, password });
+```
+
+### Typing a Redis connection (config, fields, params)
+
+Prefer the interface for plain typing:
+
+```typescript
+// Before
+import { DefaultRedisHelper } from '@venizia/ignis-helpers';
+function useRedis(connection: DefaultRedisHelper) { /* ... */ }
+
+// After
+import type { IRedisHelper } from '@venizia/ignis-helpers';
+function useRedis(connection: IRedisHelper) { /* ... */ }
+```
+
+### instanceof checks and concrete bindings
+
+Use the concrete base class (you cannot `instanceof` an interface):
+
+```typescript
+// Before
+if (connection instanceof DefaultRedisHelper) { /* ... */ }
+
+// After
+import { AbstractRedisHelper } from '@venizia/ignis-helpers';
+if (connection instanceof AbstractRedisHelper) { /* ... */ }
+```
+
+### Options type rename
+
+```typescript
+// Before
+import type { IRedisHelperOptions } from '@venizia/ignis-helpers';
+
+// After
+import type { IRedisSingleHelperOptions } from '@venizia/ignis-helpers';
+```
+
+### Hash and multi-key calls
+
+```typescript
+// Before
+await redis.hset({ key, value });
+const all = await redis.hgetall({ key });
+await redis.mset({ payload });
+const many = await redis.mget({ keys });
+
+// After
+await redis.hSet({ key, value });
+const all = await redis.hGetAll({ key });
+await redis.mSet({ payload });
+const many = await redis.mGet({ keys });
+```
+
+---
+
+## 4. Runtime behavior changes to verify
+
+These compile unchanged but behave slightly differently. All are strictly safer; verify only if your code depended on the old behavior.
+
+| Method | Old behavior | New behavior |
+|--------|--------------|--------------|
+| `subscribe` / `unsubscribe` | threw inside the ioredis callback on a subscription error (an unhandled async throw) | logs the error and returns; never throws |
+| `del` / `mGet` / `mSet` | forwarded empty input to Redis, which throws "wrong number of arguments" | empty input is a no-op: returns `0` / `[]` / void without a Redis call |
+
+If you wrapped `subscribe(...)` in a `try/catch` expecting it to throw, that branch no longer fires. If you relied on `del([])` throwing, it now returns `0`.
+
+---
+
+## 5. What you gain (additive - no action required)
+
+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).
+- **`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`).
+- **`set` TTL option** - `set({ key, value, options: { expiresIn } })` where `expiresIn` is milliseconds (uses `PX`).
+- **All three topologies are interchangeable** - anywhere an `IRedisHelper` is accepted (BullMQ, Socket.IO, WebSocket, the Casbin cache), you can now pass a single, cluster, or sentinel helper without changing the consumer.
+
+---
+
+## 6. Migration checklist
+
+- [ ] Run the grep in §2; note every match.
+- [ ] Apply the §1.1 class/type renames.
+- [ ] Apply the §1.2 lowercase to camelCase method renames.
+- [ ] Switch plain-typed connection references to `IRedisHelper`; keep `AbstractRedisHelper` for `instanceof` / concrete bindings.
+- [ ] Narrow `onError` usage if you read fields off `error`.
+- [ ] Review §4 if you relied on subscribe throwing or empty-input throwing.
+- [ ] Re-run the grep (clean) and `tsc` (green); run your test suite.
+
+When the grep is clean and the build is green, the migration is complete - there is no data or server-side change to perform.

package/content/guides/migrations/scoped-rbac-migration.md

@@ -16,8 +16,8 @@ You have two paths:
 
 | Path | Effort | When |
 |------|--------|------|
-| **B — Bridge** (re-base your custom adapter on `BaseFilteredAdapter`, keep your flat model) | Low — code only, **no data migration** | Do this first to unblock the upgrade |
-| **A — Adopt scoped** (delete your custom adapter, use `ScopedCasbinAdapter` + scoped model) | High — needs a **data migration** | The intended long-term target |
+| **B - Bridge** (re-base your custom adapter on `BaseFilteredAdapter`, keep your flat model) | Low - code only, **no data migration** | Do this first to unblock the upgrade |
+| **A - Adopt scoped** (delete your custom adapter, use `ScopedCasbinAdapter` + scoped model) | High - needs a **data migration** | The intended long-term target |
 
 Both are described below with exact before/after.
 
@@ -67,9 +67,9 @@ When you bump ignis, these stop compiling/working:
 
 ---
 
-## 3. Path B — Bridge (recommended first step, no data migration)
+## 3. Path B - Bridge (recommended first step, no data migration)
 
-Goal: compile against new ignis with **identical runtime behavior** — keep your flat `CASBIN_RBAC_MODEL`,
+Goal: compile against new ignis with **identical runtime behavior** - keep your flat `CASBIN_RBAC_MODEL`,
 your `group`/`policy` variant values, and all bespoke logic (global roles, HQ-owner expansion).
 
 ### 3.1 Define your own variant constants
@@ -147,24 +147,24 @@ Key swaps inside the class:
 - `filter.principalValue` → `filter.principal.id`; `filter.principalType` → `filter.principal.type`.
 - `this.entities.role.principalType` / `this.entities.permission.principalType` → from your own
   `entities` (pass the same values you pass today; drop the `tableName`/`policyDefinition` parts the
-  base used to require — you import the Drizzle tables directly already).
+  base used to require - you import the Drizzle tables directly already).
 - `CasbinRuleVariants.GROUP/.POLICY` → `PolicyDefinitionVariant.GROUP/.POLICY` (§3.1).
 
 ### 3.3 Fix the cache fallback in `verifier.ts`
 
 ```ts
-// BEFORE — in-memory fallback (driver removed)
+// BEFORE - in-memory fallback (driver removed)
 const cached: ICasbinEnforcerOptions['cached'] = redis
   ? { use: true, driver: CasbinEnforcerCachedDrivers.REDIS, options: { ... } }
   : { use: true, driver: CasbinEnforcerCachedDrivers.IN_MEMORY, options: { expiresIn: 5*60*1000 } };
 
-// AFTER — Redis or no cache
+// AFTER - Redis or no cache
 const cached: ICasbinEnforcerOptions['cached'] = redis
   ? { use: true, driver: CasbinEnforcerCachedDrivers.REDIS, options: { connection: redis, expiresIn: 5*60*1000, keyFn: ({ user }) => `casbin:${user.principalType}:${user.userId}` } }
   : { use: false };
 ```
 
-> **Decide:** in prod, **always provide Redis** — without it every request rebuilds the policy from the
+> **Decide:** in prod, **always provide Redis** - without it every request rebuilds the policy from the
 > DB (no per-user cache). The pool still protects you from the concurrency race, but you lose the line cache.
 
 ### 3.4 Adapter construction (`verifier.ts`)
@@ -187,7 +187,7 @@ stays. **Result: behavior identical, compiles on new ignis, zero data migration.
 
 ---
 
-## 4. Path A — Adopt the scoped model (target state)
+## 4. Path A - Adopt the scoped model (target state)
 
 This deletes `ApplicationCasbinAdapter` entirely and uses the generic `ScopedCasbinAdapter`. The
 bespoke logic moves from **code** into **data (edges)**. Do this once Path B has unblocked you.
@@ -221,7 +221,7 @@ const adapter = new ScopedCasbinAdapter({
 //                                  pass the request domain via the provider's domain resolver instead)
 ```
 
-### 4.2 Data migration — the `variant` column
+### 4.2 Data migration - the `variant` column
 
 The scoped adapter filters on `AuthorizationPolicyVariants.*.action`, not `group`/`policy`. You must
 re-classify rows:
@@ -234,11 +234,11 @@ re-classify rows:
 | `policy` (role→perm or user→perm) | `grant` | permission grant |
 
 New edge types you may need to **add** (no equivalent today):
-- `domain_inherits` (Merchant ⊂ Organizer / HQ) — **this replaces the bespoke `queryHqOwnerOrgMerchants`
+- `domain_inherits` (Merchant ⊂ Organizer / HQ) - **this replaces the bespoke `queryHqOwnerOrgMerchants`
   JOIN**. Materialize one row per Merchant→Organizer (or →HQ-merchant) relationship; the scoped model's
   `g3` then cascades a grant on the parent domain to all child merchants automatically. Maintain these
   rows when merchants/organizers are created or moved.
-- `resource_inherits` (`g4`) / `action_inherits` (`g5`) — only if you want resource/action hierarchies.
+- `resource_inherits` (`g4`) / `action_inherits` (`g5`) - only if you want resource/action hierarchies.
 
 ### 4.3 Re-express bespoke behavior as data
 
@@ -249,7 +249,7 @@ New edge types you may need to **add** (no equivalent today):
 | HQ-owner expansion (live JOIN) | `domain_inherits` (`g3`) edges (see §4.2) |
 | Domain-agnostic role permissions (`p, Role, *, ...`) | Grant rows with domain `ANY_MEMBER` (default when `domain` is NULL) |
 
-### 4.4 Behavioral caveat — resource matching changes
+### 4.4 Behavioral caveat - resource matching changes
 
 Your flat model uses exact `r.obj == p.obj`. The scoped model uses **`objectMatch`** (dotted-prefix +
 wildcard): a grant on `Order` will now **also** match `Order.findById`, and `p.obj = '*'` matches any
@@ -277,20 +277,20 @@ the bespoke adapter and gain resource/action/domain hierarchies for free.
 
 ## 6. Verification checklist (either path)
 
-- [ ] `bun run build` (or `tsc -p .`) is clean — no references to `DrizzleCasbinAdapter`,
+- [ ] `bun run build` (or `tsc -p .`) is clean - no references to `DrizzleCasbinAdapter`,
       `IDrizzleCasbinAdapterOptions`, `CasbinRuleVariants.GROUP/.POLICY`, `CasbinEnforcerCachedDrivers.IN_MEMORY`,
       `IAuthorizationCacheInvalidator`.
 - [ ] `SELECT DISTINCT variant FROM identity."PolicyDefinition"` matches what your adapter filters on
       (`group`/`policy` for Path B; the new `*.action` set for Path A).
 - [ ] A request for a user with a role-inherited / per-merchant / global permission resolves the same
-      ALLOW/DENY as before the upgrade (pick 3–4 representative users and diff).
+      ALLOW/DENY as before the upgrade (pick 3-4 representative users and diff).
 - [ ] If `cached.use: true`, Redis is reachable; if a permission changes, call
-      `enforcer.invalidateUserCache({ user })` (or rely on TTL) — see the ignis authorization docs.
+      `enforcer.invalidateUserCache({ user })` (or rely on TTL) - see the ignis authorization docs.
 - [ ] Super-admin / always-allow-roles still short-circuit (these run in the provider before the enforcer).
 
 ---
 
-## 7. Reference — current nx-seller wiring (before)
+## 7. Reference - current nx-seller wiring (before)
 
 For context, the current registration (`packages/core/src/application/verifier.ts`) uses:
 `ApplicationCasbinAdapter` (subclass of removed `DrizzleCasbinAdapter`), `CASBIN_RBAC_MODEL` (flat

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

@@ -0,0 +1,113 @@
+---
+title: Upgrading to Unified Connectors (BANA Guide)
+description: What changed in @venizia/ignis 0.0.11-0 / @venizia/ignis-helpers 0.0.10-0 and the exact steps a consumer application must take
+---
+
+# Upgrading to Unified Connectors
+
+**Target audience:** the BANA (nx-seller) team, and any application upgrading from `@venizia/ignis@0.0.10-x` / `@venizia/ignis-helpers@0.0.9-x`.
+
+**Verification status:** every step below was validated against a full copy of BANA's `packages/core` source compiled against the release tarballs - the migration ends at **zero compile errors**. The search branch was additionally validated end to end against a live 3-node Typesense cluster.
+
+## What changed (summary)
+
+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 engine: the **Typesense search branch** (`BaseSearchEntity`, `defineSearchCollection`, typed `TSearchDocument`, `DefaultSearchRepository`). It does not affect existing postgres code.
+
+## Required migrations (in order)
+
+### 1. Transaction type rename - the only sweeping change
+
+`ITransaction` is now the neutral base contract (no `connector` field). The postgres-rich types were renamed:
+
+| Old | New |
+|---|---|
+| `ITransaction<Schema>` (with `.connector`) | `IDatabaseTransaction<Schema>` |
+| `ITransactionOptions` (postgres isolation levels) | `IDatabaseTransactionOptions` |
+| `IExtraOptions` used as the repository 4th generic | `IDatabaseExtraOptions` |
+
+Measured impact on BANA: 398 files, one mechanical rewrite, proven zero-error:
+
+```bash
+grep -rl 'ITransaction\|IExtraOptions' packages/*/src --include='*.ts' \
+  | xargs sed -i 's/\bITransaction\b/IDatabaseTransaction/g; s/\bIExtraOptions\b/IDatabaseExtraOptions/g'
+```
+
+Note: `options?.transaction?.connector` inside `DefaultCRUDRepository` (alias of `DefaultRelationalRepository`) subclasses needs NO change - the postgres tiers now default their options generic to `IDatabaseExtraOptions`, so that path stays typed automatically.
+
+### 2. `applicationEnvironment.get` - options object
+
+The second positional argument became an options object (and gained `transform`):
+
+```typescript
+// Before
+const port = applicationEnvironment.get<string>(Keys.PORT, '3000');
+
+// After
+const port = applicationEnvironment.get<string>(Keys.PORT, { defaultValue: '3000' });
+
+// New capability - transform raw env values in one read:
+const nodes = applicationEnvironment.get<string[], string>(Keys.NODES, {
+  defaultValue: [],
+  transform: value => toDelimitedArray(value),
+});
+```
+
+Measured impact on BANA: **5 call sites** use the positional form. They fail at compile time (not silently), so `tsc` will point at each one:
+
+```bash
+grep -rnE "applicationEnvironment.get(<[^>]*>)?\([^,)]+, [^{]" packages/*/src --include='*.ts'
+```
+
+New helpers: `toDelimitedArray(input, separator?)` (split + trim + drop empties) and `toTrimmed(input)` from `@venizia/ignis-helpers`.
+
+### 3. Purge stale TypeScript build info
+
+The package's `exports` map changed; stale incremental caches replay phantom diagnostics for unchanged files (a page of bogus "missing property" errors while new files compile clean):
+
+```bash
+find . -name '*.tsbuildinfo' -not -path '*/node_modules/*' -delete
+```
+
+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.
+
+## Strongly recommended (not compile-blocking)
+
+### Declare decorator flags directly in every bun-run app
+
+bun 1.3.14 silently DROPS `@inject` constructor-parameter decorators when the app's `tsconfig.json` only inherits `experimentalDecorators` through a package-style `extends` it fails to resolve. Symptom: the app boots normally, every route mounts, and then `this.repository` / injected services are `undefined` at request time. Protect every app that runs via `bun src/...`:
+
+```jsonc
+// tsconfig.json - alongside your extends, not instead of it
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  }
+}
+```
+
+All IGNIS examples now declare these explicitly.
+
+## Rollout procedure (proven order)
+
+1. Bump `@venizia/ignis` -> `0.0.11-0` and `@venizia/ignis-helpers` -> `0.0.10-0` in ONE canary package first - `packages/commerce` is the recommended canary (heaviest transaction + ControllerFactory usage).
+2. Run migrations 1-3 on the canary; `tsc --noEmit` must be clean.
+3. Run the canary's test suite.
+4. Green -> apply migrations repo-wide, bump the remaining packages, full suite.
+
+## What you explicitly do NOT need to do
+
+- No import-path changes: root-barrel imports of `BaseDataSource`, `BaseEntity`, `DefaultCRUDRepository`, decorators, etc. all keep working (dual-door export model + compatibility aliases).
+- No repository/generic signature changes: `DefaultCRUDRepository<Schema, DataObject, PersistObject, ...>` call sites are unchanged (a 4th options generic was APPENDED with a default).
+- No runtime behavior changes on the postgres path: the whole pre-existing RDB behavior suite runs unchanged inside the release gates, and every behavior delta was verified to have no trigger inside BANA (`@model` tableName divergence: 0 occurrences; message-string assertions: 0).
+- Nothing search-related: BANA imports zero search symbols today.