@venizia/ignis-docs 0.0.8-1 → 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/guides/migrations/scoped-rbac-migration.md

@@ -0,0 +1,300 @@
+# Migrating to the Scoped RBAC Authorization (ignis ≥ scoped-rbac release)
+
+> **Audience:** the team/agent maintaining **nx-seller** (and any app that wrote a custom
+> `DrizzleCasbinAdapter` subclass). This is a hand-off spec describing exactly what breaks when you
+> upgrade `@venizia/ignis` to the scoped-RBAC release and the two supported migration paths.
+
+---
+
+## 0. TL;DR
+
+The ignis `authorize` module was reworked around a single **edge table** + a **scoped Casbin model**.
+As part of that, several symbols nx-seller depends on were **removed or changed**. Upgrading ignis
+**will not compile** until you act on the breakages in §2.
+
+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 |
+
+Both are described below with exact before/after.
+
+---
+
+## 1. What changed in ignis
+
+| Area | Before | After |
+|------|--------|-------|
+| Adapter base | `DrizzleCasbinAdapter` (concrete, app subclassed it) | **removed.** New: thin `BaseFilteredAdapter<TFilter>` + a ready-made generic `ScopedCasbinAdapter` |
+| Adapter options | `IDrizzleCasbinAdapterOptions` | **removed.** `BaseFilteredAdapter` takes `{ scope, dataSource }`; `ScopedCasbinAdapter` takes `{ dataSource, entities }` |
+| Filter shape | `{ principalType, principalValue }` (flat) | `{ principal: { type, id } }` (`ICasbinPolicyFilter`) |
+| `CasbinRuleVariants` | `P, G, GROUP('group'), POLICY('policy')` + `SCHEME_SET`/`isValid` | trimmed to **casbin prefixes only**: `P, G, G2, G3, G4, G5`. `GROUP`/`POLICY` **removed** |
+| DB `variant` discriminator | lived on `CasbinRuleVariants.GROUP/.POLICY` | now `AuthorizationPolicyVariants.*.action` (`grant`, `assign_role`, `join_domain`, `role_inherits`, `resource_inherits`, `action_inherits`, `domain_inherits`) |
+| Cache drivers | `redis` **and** `in-memory` | **redis only.** `CasbinEnforcerCachedDrivers.IN_MEMORY` removed; `cached` is now `{ use: false } \| (ICasbinEnforcerCachedRedis & { use: true })` |
+| Cache invalidation interface | `IAuthorizationCacheInvalidator` / `TAuthorizationCacheInvalidator` | **removed.** `invalidateUserCache?`/`rebuildUserCache?` are now **optional** members of `IAuthorizationEnforcer` (feature-detected by the registry) |
+| Enforcer model | shared single enforcer | **pool** of per-request enforcers (`BasePoolHelper`); policy loaded per request, fail-closed |
+| Scoped option | n/a | new `isScoped?: boolean` on `ICasbinEnforcerOptions` |
+
+> **Note:** the old `CasbinRuleVariants.GROUP = 'group'` and `.POLICY = 'policy'`. Your
+> `PolicyDefinition.variant` column currently stores the strings **`'group'`** and **`'policy'`**.
+> Confirm with: `SELECT DISTINCT variant FROM identity."PolicyDefinition";`
+
+---
+
+## 2. What breaks in nx-seller (exact references)
+
+When you bump ignis, these stop compiling/working:
+
+1. **`packages/core/src/security/application-casbin-adapter.ts`**
+   - `extends DrizzleCasbinAdapter` → class removed.
+   - `import { DrizzleCasbinAdapter, IDrizzleCasbinAdapterOptions, ICasbinPolicyFilter } from '@venizia/ignis'` → first two removed; `ICasbinPolicyFilter` still exists but its **shape changed**.
+   - `filter.principalValue` / `filter.principalType` → now `filter.principal.id` / `filter.principal.type`.
+   - `CasbinRuleVariants.GROUP` / `CasbinRuleVariants.POLICY` → removed.
+   - `this.entities.role.principalType` / `this.entities.permission.principalType` → `entities` no longer provided by the base.
+
+2. **`packages/core/src/repositories/public/policy-definition.repository.ts`**
+   - Many `eq(pd.variant, CasbinRuleVariants.GROUP)` / `.POLICY` → constant removed. This file is the
+     biggest single breakage surface outside the adapter.
+
+3. **`packages/core/src/application/verifier.ts`** (enforcer registration)
+   - The Redis-absent fallback uses `CasbinEnforcerCachedDrivers.IN_MEMORY` → removed. You must pick
+     Redis or `{ use: false }`.
+
+4. Any seed/migration writing `variant = 'group' | 'policy'` keeps working at the DB level (those are
+   plain strings), but the **constants** that produced them are gone.
+
+---
+
+## 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`,
+your `group`/`policy` variant values, and all bespoke logic (global roles, HQ-owner expansion).
+
+### 3.1 Define your own variant constants
+
+`CasbinRuleVariants.GROUP/.POLICY` are gone from ignis, but your DB still stores `'group'`/`'policy'`.
+Own these strings locally so you are decoupled from ignis's casbin-prefix enum:
+
+```ts
+// packages/core/src/security/policy-variant.ts
+export class PolicyDefinitionVariant {
+  /** user→role assignment + user→merchant membership rows. */
+  static readonly GROUP = 'group';
+  /** permission grant rows (role→perm, user→perm). */
+  static readonly POLICY = 'policy';
+}
+```
+
+Then replace every `CasbinRuleVariants.GROUP` → `PolicyDefinitionVariant.GROUP` and
+`CasbinRuleVariants.POLICY` → `PolicyDefinitionVariant.POLICY` in
+`application-casbin-adapter.ts` **and** `policy-definition.repository.ts`.
+Keep using `CasbinRuleVariants.G` / `.P` for the **emitted casbin lines** (those still exist).
+
+### 3.2 Re-base `ApplicationCasbinAdapter` on `BaseFilteredAdapter`
+
+```ts
+// BEFORE
+import {
+  DrizzleCasbinAdapter,
+  type IDrizzleCasbinAdapterOptions,
+  type ICasbinPolicyFilter,
+} from '@venizia/ignis';
+
+export class ApplicationCasbinAdapter extends DrizzleCasbinAdapter {
+  private readonly appDataSource: IDrizzleCasbinAdapterOptions['dataSource'];
+  constructor(opts: IDrizzleCasbinAdapterOptions) {
+    super(opts);
+    this.appDataSource = opts.dataSource;
+  }
+  // ... used this.entities.role.principalType, filter.principalValue, etc.
+}
+```
+
+```ts
+// AFTER
+import { BaseFilteredAdapter, type ICasbinPolicyFilter } from '@venizia/ignis';
+import type { IDataSource } from '@venizia/ignis';
+
+interface IAppCasbinEntities {
+  role: { principalType: string };
+  permission: { principalType: string };
+}
+
+export class ApplicationCasbinAdapter extends BaseFilteredAdapter {
+  private readonly entities: IAppCasbinEntities;
+
+  constructor(opts: { dataSource: IDataSource; entities: IAppCasbinEntities }) {
+    super({ scope: ApplicationCasbinAdapter.name, dataSource: opts.dataSource });
+    this.entities = opts.entities;
+  }
+
+  // `this.connector` is provided by BaseFilteredAdapter (replaces this.appConnector).
+
+  override async loadFilteredPolicy(model: Model, filter: ICasbinPolicyFilter): Promise<void> {
+    const userId = filter.principal.id;          // was filter.principalValue
+    const principalType = filter.principal.type; // was filter.principalType
+    // ... unchanged bespoke logic ...
+    // Instead of `Helper.loadPolicyLine(line, model)` per line you may use:
+    //   await this.loadLines({ model, lines });
+  }
+}
+```
+
+Key swaps inside the class:
+- `this.appConnector` → `this.connector` (from `BaseFilteredAdapter`).
+- `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).
+- `CasbinRuleVariants.GROUP/.POLICY` → `PolicyDefinitionVariant.GROUP/.POLICY` (§3.1).
+
+### 3.3 Fix the cache fallback in `verifier.ts`
+
+```ts
+// 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
+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
+> 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`)
+
+Drop the `policyDefinition`/`tableName` entries the old base required; pass only what your re-based
+class declares:
+
+```ts
+const adapter = new ApplicationCasbinAdapter({
+  dataSource: this.get<PostgresCoreDataSource>({ /* unchanged */ }),
+  entities: {
+    role: { principalType: Role.AUTHORIZATION_SUBJECT! },
+    permission: { principalType: Permission.AUTHORIZATION_SUBJECT! },
+  },
+});
+```
+
+Everything else in the registration (`CASBIN_RBAC_MODEL`, `domainMatching`, `normalizePayloadFn`)
+stays. **Result: behavior identical, compiles on new ignis, zero data migration.**
+
+---
+
+## 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.
+
+### 4.1 Register the generic adapter + scoped model
+
+```ts
+import {
+  ScopedCasbinAdapter,
+  CASBIN_RBAC_DOMAIN_SCOPED_MODEL,
+  CasbinEnforcerModelDrivers,
+} from '@venizia/ignis';
+
+const adapter = new ScopedCasbinAdapter({
+  dataSource: this.get<PostgresCoreDataSource>({ /* ... */ }),
+  entities: {
+    policyDefinition: { tableName: PolicyDefinition.TABLE_NAME, schemaName: 'identity' },
+    permission: { tableName: Permission.TABLE_NAME, schemaName: 'identity' },
+    principals: { user: 'User', role: 'Role' },     // casbin name prefixes
+    domainTypes: ['Merchant', 'Organizer'],          // domain types you scope on
+    softDelete: { use: true, columnName: 'deleted_at' },
+  },
+});
+
+// In the enforcer options:
+//   model:   { driver: CasbinEnforcerModelDrivers.TEXT, definition: CASBIN_RBAC_DOMAIN_SCOPED_MODEL }
+//   isScoped: true
+//   adapter, cached
+//   ❌ remove domainMatching      (isScoped auto-registers keyMatch on g + objectMatch on g4)
+//   ❌ remove normalizePayloadFn  (scoped mode uses the default (sub,dom,obj,act) payload;
+//                                  pass the request domain via the provider's domain resolver instead)
+```
+
+### 4.2 Data migration — the `variant` column
+
+The scoped adapter filters on `AuthorizationPolicyVariants.*.action`, not `group`/`policy`. You must
+re-classify rows:
+
+| Current row (`variant`) | Becomes | Rule |
+|-------------------------|---------|------|
+| `group`, subject=User, target=Role | `assign_role` | user→role |
+| `group`, subject=Role, target=Role | `role_inherits` | role→role (if you have role hierarchy) |
+| `group`, subject=User, target=Merchant | `join_domain` | user→domain membership |
+| `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`
+  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.
+
+### 4.3 Re-express bespoke behavior as data
+
+| Today (code in `ApplicationCasbinAdapter`) | Scoped equivalent (data) |
+|--------------------------------------------|--------------------------|
+| Global role → wildcard `*` domain (`AppFixedRoles.isGlobalRole`) | Store the `assign_role` row with **NULL domain** → adapter emits `g, User_x, Role_y, *` |
+| NULL-domain role → expand to every member merchant | Grant rows with domain **`ANY_MEMBER`** + `join_domain` (`g2`) membership rows; the matcher resolves "any domain I'm a member of" |
+| 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
+
+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
+resource. Audit your permission `code`s before switching, or you may unintentionally widen access.
+
+### 4.5 Update `policy-definition.repository.ts`
+
+This file queries by `variant`. After the data migration, replace `CasbinRuleVariants.GROUP/.POLICY`
+with the relevant `AuthorizationPolicyVariants.*.action` values (e.g. `ASSIGN_ROLE.action`,
+`JOIN_DOMAIN.action`, `GRANT.action`) matching the row kind each query targets.
+
+---
+
+## 5. Decision guide
+
+```
+Need to ship the ignis bump now, behavior unchanged?      → Path B (bridge).
+Ready to model org hierarchy as data + run a migration?   → Path A (scoped).
+```
+
+Path B and Path A are not mutually exclusive: do **B** to upgrade safely, then schedule **A** to delete
+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`,
+      `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).
+- [ ] If `cached.use: true`, Redis is reachable; if a permission changes, call
+      `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)
+
+For context, the current registration (`packages/core/src/application/verifier.ts`) uses:
+`ApplicationCasbinAdapter` (subclass of removed `DrizzleCasbinAdapter`), `CASBIN_RBAC_MODEL` (flat
+`g + p`, exact `r.obj == p.obj`), a Redis-or-in-memory `cached`, `domainMatching { roleDefinition: 'g',
+fn: keyMatch }`, and a `normalizePayloadFn` mapping subject/domain via
+`ApplicationCasbinAdapter.toUserVerb/toMerchantVerb`. Path B keeps all of this except the adapter base
+and the in-memory cache; Path A replaces the adapter, model, `domainMatching`, and `normalizePayloadFn`.

package/wiki/references/base/filter-system/default-filter.md

@@ -299,13 +299,13 @@ export class Subscription extends BaseEntity<typeof Subscription.schema> {}
 
 ### Query Limit Protection
 
+Use the dedicated `settings.defaultLimit` to raise (or lower) the per-model default page size. Prefer it over putting `limit` inside `defaultFilter`:
+
 ```typescript
 @model({
   type: 'entity',
   settings: {
-    defaultFilter: {
-      limit: 1000,  // Prevent unbounded queries
-    },
+    defaultLimit: 1000,  // Per-model default when a query omits `limit`
   },
 })
 export class LogEntry extends BaseEntity<typeof LogEntry.schema> {}
@@ -315,6 +315,9 @@ await logRepo.find({ filter: {} });           // LIMIT 1000
 await logRepo.find({ filter: { limit: 50 } }); // LIMIT 50
 ```
 
+> [!TIP]
+> `defaultLimit` is independent of `defaultFilter`: bypassing the default filter via `shouldSkipDefaultFilter` does **not** drop the limit. See [Pagination → Default Limit](/references/base/filter-system/fields-order-pagination#default-limit).
+
 
 ## Relation Include Default Filters