@venizia/ignis-docs 0.2.1-0 → 0.2.1-1

package/content/extensions/components/authorization/api.md

@@ -10,10 +10,30 @@ Every option, binding key, class, and method the Authorization component exposes
 
 **Files:**
 
-- [`packages/core/src/components/auth/authorize/`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/auth/authorize) - component, providers, enforcers, adapters, models, middleware
-- [`packages/core/src/components/auth/base/abstract-auth-registry.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/auth/base/abstract-auth-registry.ts) - `AbstractAuthRegistry` (shared with Authentication)
-- [`packages/core/src/base/metadata/persistents.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/metadata/persistents.ts) - `@model` populating `AUTHORIZATION_SUBJECT`
-- [`packages/core/src/helpers/inversion/mixins/model.mixin.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/helpers/inversion/mixins/model.mixin.ts) - `MetadataRegistry` authorize-settings queries
+- [`packages/core-server/src/components/auth/authorize/`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/authorize) - component, providers, enforcers, adapters, models, middleware
+- [`packages/core-server/src/components/auth/base/abstract-auth-registry.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/base/abstract-auth-registry.ts) - `AbstractAuthRegistry` (shared with Authentication)
+- [`packages/core-server/src/base/metadata/persistents.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/base/metadata/persistents.ts) - `@model` populating `AUTHORIZATION_SUBJECT`
+- [`packages/core-server/src/helpers/inversion/mixins/model.mixin.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/helpers/inversion/mixins/model.mixin.ts) - `MetadataRegistry` authorize-settings queries
+
+## Find what you need
+
+| You want to | Go to |
+|---|---|
+| Bind global options and per-enforcer options | [Binding keys](#binding-keys) |
+| Configure `AuthorizeComponent` at startup | [IAuthorizeOptions](#iauthorizeoptions) |
+| Configure the Casbin enforcer (model, cache, pool) | [ICasbinEnforcerOptions](#icasbinenforceroptions) |
+| Write a route's `authorize` spec | [IAuthorizationSpec (route-level)](#iauthorizationspec-route-level) |
+| Resolve a request's domain scope | [IAuthorizationDomainSource / TAuthorizationDomainResolver](#iauthorizationdomainsource-tauthorizationdomainresolver) |
+| Look up an action, decision, or role constant | [Constants](#constants) |
+| Read the scoped RBAC `.conf` model | [CASBIN_RBAC_DOMAIN_SCOPED_MODEL](#casbin_rbac_domain_scoped_model) |
+| Register or resolve enforcers | [AuthorizationEnforcerRegistry](#authorizationenforcerregistry) |
+| Understand how the Casbin enforcer builds and evaluates rules | [CasbinAuthorizationEnforcer](#casbinauthorizationenforcer) |
+| Use the ready-made Postgres adapter | [ScopedCasbinAdapter](#scopedcasbinadapter) |
+| Write a custom adapter | [BaseFilteredAdapter](#basefilteredadapter) |
+| Grant a subset of a subject's operations | [Subset grants (custom rows)](#subset-grants-custom-rows) and [GrantBuilder.planGrant](#grantbuilderplangrant) |
+| Seed `PolicyDefinition` / `Permission` rows | [Policy and permission builders](#policy-and-permission-builders) |
+| Wire `authorize` into a REST or gRPC controller | [Controller integration](#controller-integration) |
+| Read the context keys the middleware sets | [Context variables](#context-variables) |
 
 ## Import paths
 
@@ -29,7 +49,7 @@ import {
   CasbinAuthorizationEnforcer,
 
   // Adapters
-  BaseFilteredAdapter, ScopedCasbinAdapter,
+  BaseFilteredAdapter, ScopedCasbinAdapter, PrincipalPolicyEdges,
 
   // Scoped RBAC model
   CASBIN_RBAC_DOMAIN_SCOPED_MODEL,
@@ -37,11 +57,9 @@ import {
   // Models
   AuthorizationRole,
 
-  // Policy / permission catalog builders
-  AuthorizationPolicyBuilder, AuthorizationPermissionBuilder,
-
-  // Resource-hierarchy matcher (register on a custom Casbin model)
-  objectMatch,
+  // Policy / permission catalog builders - AuthorizationPermissionBuilder.objectMatch is the
+  // resource-hierarchy matcher (register on a custom Casbin model)
+  AuthorizationPolicyBuilder, AuthorizationPermissionBuilder, GrantBuilder,
 
   // Constants
   Authorization, AuthorizationActions, AuthorizationDecisions, AuthorizationDomainScopes,
@@ -115,7 +133,8 @@ flowchart TD
     Voters -->|DENY| E403a[/403 Denied by voter/]
     Voters -->|ALLOW| Next4([next - voter allow])
     Voters -->|ABSTAIN / none| HasEnforcers{Enforcers registered?}
-    HasEnforcers -->|No| Next6([next - skip, no enforcers])
+    HasEnforcers -->|No, defaultDecision: allow| Next6([next - allow, warning logged])
+    HasEnforcers -->|No, defaultDecision: deny or unset| E403c[/403 no enforcer registered/]
     HasEnforcers -->|Yes| Resolve[Resolve enforcer by name]
     Resolve --> ResolveDomain["Resolve domain (if spec.domain or domainResolver)"]
     ResolveDomain --> Cache{Rules cached?}
@@ -201,13 +220,12 @@ components/auth/authorize/
 │   ├── base-filtered.ts          # BaseFilteredAdapter (thin abstract) + ICasbinPolicyFilter
 │   ├── scoped-casbin.adapter.ts  # ScopedCasbinAdapter (generic edge-table reader)
 │   └── types.ts                  # IScopedCasbinEntities, IScopedCasbinTable, ICasbinPolicySource
+├── builders/
+│   ├── grant.builder.ts           # GrantBuilder
+│   ├── permission.builder.ts      # AuthorizationPermissionBuilder + static objectMatch
+│   └── policy.builder.ts          # AuthorizationPolicyBuilder
 ├── common/
-│   ├── constants.ts               # Authorization, Actions, Decisions, PolicyVariants, Roles, ...
-│   ├── keys.ts                    # AuthorizeBindingKeys
-│   ├── object-match.ts            # objectMatch resource-hierarchy matcher
-│   ├── permission-builder.ts      # AuthorizationPermissionBuilder
-│   ├── policy-builder.ts          # AuthorizationPolicyBuilder
-│   ├── resolve-request-domain.ts  # resolveRequestDomain
+│   ├── constants.ts               # Authorization, Actions, Decisions, PolicyVariants, Roles, AuthorizeBindingKeys, ...
 │   └── types.ts                   # IAuthorizeOptions, IAuthorizationEnforcer, ICasbinEnforcerOptions, ...
 ├── enforcers/
 │   ├── casbin.enforcer.ts        # CasbinAuthorizationEnforcer
@@ -215,7 +233,9 @@ components/auth/authorize/
 │   └── models/rbac-domain.model.ts # CASBIN_RBAC_DOMAIN_SCOPED_MODEL
 ├── middlewares/authorize.middleware.ts # authorize() standalone function
 ├── models/authorization-role.model.ts  # AuthorizationRole
-├── providers/authorization.provider.ts # AuthorizationProvider
+├── providers/
+│   ├── authorization.provider.ts # AuthorizationProvider
+│   └── request-domain.ts         # resolveRequestDomain, readDeclarative
 └── component.ts                        # AuthorizeComponent
 ```
 
@@ -230,7 +250,7 @@ components/auth/authorize/
 | Rules caching | Built rules cached on the Hono context per-request - avoids rebuilding for multi-spec routes |
 | Registry singleton | Mirrors `AuthenticationStrategyRegistry` - shares `AbstractAuthRegistry<T>` |
 | Filtered adapter pattern | `BaseFilteredAdapter` is a thin read-only base; subclasses implement only `loadFilteredPolicy` |
-| No-enforcer fallback | No enforcers registered -> the middleware skips authorization and calls `next()` instead of throwing |
+| No-enforcer fallback | No enforcers registered -> the middleware honors `defaultDecision`: `deny` (default) throws a named 403, `allow` proceeds and logs a warning |
 | Single edge table (scoped model) | `ScopedCasbinAdapter` reads one `PolicyDefinition` table for every edge type - no per-relation tables |
 
 ## AuthorizeComponent
@@ -253,7 +273,7 @@ class AuthorizeComponent extends BaseComponent {
 > [!NOTE]
 > Enforcer registration is separate - `AuthorizeComponent` only validates global options. Register enforcers via `AuthorizationEnforcerRegistry.register()`.
 
-Source -> [`component.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/auth/authorize/component.ts)
+Source -> [`component.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/authorize/component.ts)
 
 ## Binding keys
 
@@ -275,7 +295,7 @@ class AuthorizeBindingKeys {
 
 `AuthorizeBindingKeys.enforcerOptions(name)` is called automatically by `AuthorizationEnforcerRegistry.register()` when `options` is provided; `CasbinAuthorizationEnforcer` injects its options from `AuthorizeBindingKeys.enforcerOptions('casbin')`.
 
-Source -> [`common/keys.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/auth/authorize/common/keys.ts)
+Source -> [`common/constants.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/authorize/common/constants.ts)
 
 ## Option interfaces
 
@@ -306,7 +326,7 @@ Casbin-specific options, provided per-enforcer via `AuthorizationEnforcerRegistr
 | `model` | `{ driver: 'file', definition } \| { driver: 'text', definition }` | - | **Required.** Casbin model (file path or inline text). For scoped RBAC, use `CASBIN_RBAC_DOMAIN_SCOPED_MODEL` |
 | `cached` | `{ use: false } \| (ICasbinEnforcerCachedRedis & { use: true })` | - | **Required.** Caching configuration (Redis-only) |
 | `adapter` | `Adapter` | - | Casbin adapter instance (e.g. `ScopedCasbinAdapter`) |
-| `isScoped` | `boolean` | `false` | Enables the scoped model: 4-token `(sub, dom, obj, act)` requests; auto-registers `keyMatch` on `g` + `objectMatch` on the resource relation |
+| `isScoped` | `boolean` | `false` | Enables the scoped model: 4-token `(sub, dom, obj, act)` requests. Auto-registers `keyMatch`, `objectMatch`, and `ResourceRoleManager` - see [`CasbinAuthorizationEnforcer`](#casbinauthorizationenforcer) |
 | `poolSize` | `number` | `16` | Pooled enforcers (each request enforces on its own borrowed instance) |
 | `poolAcquireTimeoutMs` | `number` | `5000` | Max ms to wait for a free pooled enforcer before failing closed |
 | `normalizePayloadFn` | `(opts) => { subject, resource, action, domain? }` | - | Custom (non-scoped) payload normalizer, run before evaluation |
@@ -330,6 +350,15 @@ interface ICasbinEnforcerOptions<E extends Env = Env, TAction = string, TResourc
 > [!NOTE]
 > `cached.options.expiresIn` must be `>= 10_000` ms (`MIN_EXPIRES_IN`). Caching is **Redis-only** - the in-memory driver was removed.
 
+### Domain hierarchy edges (`g3`)
+
+There is no enforcer-level option for domain hierarchy - a role assignment (`g`), a grant (`g3`), or a domain membership (`g2`) declared at a parent domain reaching its children is driven entirely by `g3` policy lines already present in a principal's own line set, whenever `isScoped: true`. Two sources produce those lines - see `resolveDomainEdges` on [`ScopedCasbinAdapter`](#scopedcasbinadapter) below for the second one:
+
+- `domain_inherits` rows reachable from the principal's domain closure (`ScopedCasbinAdapter`'s `DOMAIN_EDGE` branch, always on).
+- `ScopedCasbinAdapter`'s `resolveDomainEdges` constructor hook, for a hierarchy the app already owns on a business table.
+
+`registerMatchers()` (see [`configure()`](#configure) below) wires this unconditionally for every scoped model, sharing one overlay across the three role managers. Freshness is whatever the per-user policy-line cache already guarantees; there is no separate TTL or invalidation call to reason about.
+
 **Cache configuration (discriminated union):**
 
 ```typescript
@@ -381,7 +410,9 @@ type TAuthorizationDomainResolver<E extends Env = Env> = (opts: {
 }) => ValueOrPromise<TNullable<{ type: string; id: IdType }>>;
 ```
 
-`resolveRequestDomain()` (`common/resolve-request-domain.ts`) turns either shape into a casbin domain string with this precedence: `spec.domain` (resolver, then declarative `readDeclarative()`) -> `IAuthorizeOptions.domainResolver` -> `AuthorizationDomainScopes.SYSTEM_WIDE`. `readDeclarative()` reads `context.req.param/header/query()` for `'param'|'header'|'query'`, or `context.get(key)` for `'context'`.
+`resolveRequestDomain()` (`providers/request-domain.ts`) turns either shape into a casbin domain string. Precedence: `spec.domain` (resolver, then declarative `readDeclarative()`) -> `IAuthorizeOptions.domainResolver` -> `AuthorizationDomainScopes.SYSTEM_WIDE`.
+
+`readDeclarative()` reads `context.req.param/header/query()` for `'param'|'header'|'query'`, or `context.get(key)` for `'context'`.
 
 ### TAuthorizationConditions / TAuthorizationVoter / TAuthorizeFn
 
@@ -413,7 +444,7 @@ interface IAuthorizationRequest<TAction = string, TResource = string> {
 }
 ```
 
-Source -> [`common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/auth/authorize/common/types.ts)
+Source -> [`common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/authorize/common/types.ts)
 
 ## Constants
 
@@ -428,13 +459,15 @@ All constant classes follow the same pattern: static readonly values + `SCHEME_S
 | `Authorization.ENFORCER` | `'authorization.enforcer'` | Binding key prefix for enforcers |
 | `Authorization.DOMAIN` | `'authorization.domain'` | Context key for the resolved request domain scope |
 
-**`AuthorizationActions`** - `CREATE` `UPDATE` `DELETE` `EXECUTE` `READ` `WRITE` `MANAGE`. `AuthorizationActions.LATTICE` declares the standard action hierarchy consumed by `AuthorizationPolicyBuilder.actionLattice()`:
+**`AuthorizationActions`** - `CREATE` `UPDATE` `DELETE` `EXECUTE` `READ` `WRITE` `MANAGE` `CUSTOM`. `AuthorizationActions.LATTICE` declares the standard action hierarchy consumed by `AuthorizationPolicyBuilder.actionLattice()`:
 
 | `child` | `parent` |
 |---|---|
 | `READ`, `WRITE`, `EXECUTE` | `MANAGE` |
 | `CREATE`, `UPDATE`, `DELETE` | `WRITE` |
 
+`CUSTOM` (`'custom'`) is a grant-mode marker for a subset grant carrying `metadata.ops` - see [Subset grants](#subset-grants-custom-rows). It is deliberately absent from `LATTICE`: it names an encoding, not a position in the action hierarchy.
+
 **`AuthorizationDecisions`** - `ALLOW` `DENY` `ABSTAIN`.
 
 | Method | String check | Number check |
@@ -460,7 +493,13 @@ All constant classes follow the same pattern: static readonly values + `SCHEME_S
 | `REGEX_MATCH` | `'regexMatch'` | Treats the stored/policy value as a full regular expression |
 
 > [!IMPORTANT]
-> Applied as `fn(requestDomain, policyDomain)` - the wildcard must live on the **stored/policy** side. `keyMatch("Merchant_X", "*") === true`, `keyMatch("Merchant_X", "Merchant_X") === true`, `keyMatch("Merchant_X", "Merchant_Y") === false`.
+> Applied as `fn(requestDomain, policyDomain)` - the wildcard must live on the **stored/policy** side.
+>
+> | Call | Result |
+> |---|---|
+> | `keyMatch("Merchant_X", "*")` | `true` |
+> | `keyMatch("Merchant_X", "Merchant_X")` | `true` |
+> | `keyMatch("Merchant_X", "Merchant_Y")` | `false` |
 
 **`CasbinRuleVariants`** - the Casbin line prefixes declared by the scoped model, numbered in request-tuple order (`sub -> dom -> obj -> act`).
 
@@ -470,7 +509,7 @@ All constant classes follow the same pattern: static readonly values + `SCHEME_S
 | `G` | `'g'` | Role membership + role inheritance (the `sub` axis) |
 | `G2` | `'g2'` | User -> domain membership (the `dom` axis) |
 | `G3` | `'g3'` | Domain hierarchy (the `dom` axis) |
-| `G4` | `'g4'` | Resource hierarchy (the `obj` axis, via `objectMatch`) |
+| `G4` | `'g4'` | Resource hierarchy (the `obj` axis, served by `ResourceRoleManager`) |
 | `G5` | `'g5'` | Action hierarchy (the `act` axis) |
 
 **`AuthorizationPolicyVariants`** - the DB `variant` discriminator stored on each `PolicyDefinition` row (the kind of "edge"). Each entry carries `action` (the DB value) and `rule` (the Casbin prefix `ScopedCasbinAdapter` emits for it).
@@ -504,7 +543,7 @@ All constant classes follow the same pattern: static readonly values + `SCHEME_S
 | `GUEST` | `'001_guest'` | 1 |
 | `UNKNOWN_USER` | `'000_unknown-user'` | 0 |
 
-Source -> [`common/constants.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/auth/authorize/common/constants.ts)
+Source -> [`common/constants.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/authorize/common/constants.ts)
 
 ## CASBIN_RBAC_DOMAIN_SCOPED_MODEL
 
@@ -536,17 +575,23 @@ m = g(r.sub, p.sub, r.dom) && (p.dom == "SYSTEM_WIDE" || (p.dom == "ANY_MEMBER"
 | `g` | `sub` | `assign_role` (user -> role) + `role_inherits` (role -> role), domain-aware. Registered with `keyMatch` so a `*` domain on a link matches any request domain |
 | `g2` | `dom` (membership) | `join_domain` - powers the `ANY_MEMBER` grant scope |
 | `g3` | `dom` (nesting) | `domain_inherits`, plus a self-link so an exact domain always matches itself |
-| `g4` | `obj` | `resource_inherits` - explicit non-standard nesting edges; registered with `objectMatch` |
+| `g4` | `obj` | `resource_inherits` - explicit non-standard nesting edges; served by `ResourceRoleManager`, not a matching function |
 | `g5` | `act` | `action_inherits`, plus a self-link |
 
-**Effect** is casbin's `allow-and-deny` effector: a request needs a matching `allow` AND no matching `deny` - default-DENY, and an explicit `deny` always overrides an `allow`. This is deliberately NOT casbin's `deny-override` effector (`!some(where (p.eft == deny))`), which would be default-ALLOW.
+**Effect** is casbin's `allow-and-deny` effector. A request needs a matching `allow` AND no matching `deny` - default-DENY. An explicit `deny` always overrides an `allow`. This is deliberately NOT casbin's `deny-override` effector (`!some(where (p.eft == deny))`), which would be default-ALLOW.
+
+**Domain clause**, matched by `p.dom`:
 
-**Domain clause**, matched by `p.dom`: `SYSTEM_WIDE` matches every domain (bypasses membership, super-admin); `ANY_MEMBER` matches every domain the subject joined (via `g2`); `<Type>_<id>` matches that domain, or a nested child via `g3`.
+| `p.dom` value | Matches |
+|---|---|
+| `SYSTEM_WIDE` | Every domain - bypasses membership, super-admin |
+| `ANY_MEMBER` | Every domain the subject joined, via `g2` |
+| `<Type>_<id>` | That domain, or a nested child via `g3` |
 
 > [!NOTE]
 > Relies on the default `DefaultRoleManager`'s self-link behavior (`hasLink(name, name) === true`) for `g3`/`g4`/`g5` - a custom role manager must preserve self-links.
 
-Source -> [`enforcers/models/rbac-domain.model.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/auth/authorize/enforcers/models/rbac-domain.model.ts)
+Source -> [`enforcers/models/rbac-domain.model.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/authorize/enforcers/models/rbac-domain.model.ts)
 
 ## AbstractAuthRegistry
 
@@ -579,7 +624,7 @@ type TRegistryDescriptor<TItem> = { container: Container; targetClass: TClass<TI
 
 `AuthorizationEnforcerRegistry.getBindingPrefix()` returns `Authorization.ENFORCER` (`'authorization.enforcer'`).
 
-Source -> [`base/abstract-auth-registry.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/auth/base/abstract-auth-registry.ts)
+Source -> [`base/abstract-auth-registry.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/base/abstract-auth-registry.ts)
 
 ## AuthorizationEnforcerRegistry
 
@@ -614,7 +659,7 @@ class AuthorizationEnforcerRegistry extends AbstractAuthRegistry<IAuthorizationE
 |--------|---------|-------------|
 | `getInstance()` | `AuthorizationEnforcerRegistry` | Singleton instance (created on first call) |
 | `register(opts)` | `this` | Registers enforcers with type-safe options (chainable) |
-| `hasEnforcers()` | `boolean` | `descriptors.size > 0` - used by the middleware to skip authorization when no enforcers exist |
+| `hasEnforcers()` | `boolean` | `descriptors.size > 0` - used by the middleware to decide whether to honor `defaultDecision` instead of resolving an enforcer |
 | `getDefaultEnforcerName()` | `string` | Delegates to `getDefaultName()` |
 | `resolveEnforcer({ name })` | `Promise<IAuthorizationEnforcer>` | Resolves + auto-configures once (`configuredEnforcers` Set) |
 | `resolveOptions()` | `IAuthorizeOptions \| undefined` | Iterates all registered containers looking for `AuthorizeBindingKeys.OPTIONS` |
@@ -622,7 +667,12 @@ class AuthorizationEnforcerRegistry extends AbstractAuthRegistry<IAuthorizationE
 | `rebuildUserCache(opts)` | `Promise<{ cacheKey, lineCount }>` | Drops then immediately re-extracts + re-caches |
 | `reset()` | `void` | Clears descriptors AND `configuredEnforcers` |
 
-**`register()` behavior:** validates no duplicate names within the call, validates each name is not already registered, binds each class as a singleton at `authorization.enforcer.{name}`, and - if `options` is given - binds it to `AuthorizeBindingKeys.enforcerOptions(name)`.
+**`register()` behavior:**
+
+- Validates no duplicate names within the call.
+- Validates each name is not already registered.
+- Binds each class as a singleton at `authorization.enforcer.{name}`.
+- If `options` is given, binds it to `AuthorizeBindingKeys.enforcerOptions(name)`.
 
 **Configure-once pattern:**
 
@@ -637,7 +687,7 @@ async resolveEnforcer(opts: { name: string }): Promise<IAuthorizationEnforcer> {
 }
 ```
 
-Source -> [`enforcers/enforcer-registry.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/auth/authorize/enforcers/enforcer-registry.ts)
+Source -> [`enforcers/enforcer-registry.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/authorize/enforcers/enforcer-registry.ts)
 
 ## IAuthorizationEnforcer interface
 
@@ -675,7 +725,7 @@ interface IAuthorizationEnforcer<
 
 ## CasbinAuthorizationEnforcer
 
-Wraps the `casbin` library (optional peer dependency). Each request evaluates on its **own** enforcer borrowed from a `BasePoolHelper<Enforcer>` - the adapter (DB load) only runs on a throwaway enforcer to build a user's lines (cached in Redis if configured); every request then enforces on a pooled enforcer freshly loaded with those lines. This isolates concurrency and keeps the DB out of the hot path.
+Wraps the `casbin` library (optional peer dependency). The adapter only loads from the database on a throwaway enforcer, to build one user's policy lines (cached in Redis if configured). Every request then evaluates on its own enforcer, borrowed from a `BasePoolHelper<Enforcer>` and freshly loaded with those lines. This isolates concurrency and keeps the database out of the hot path.
 
 ```typescript
 class CasbinAuthorizationEnforcer<E extends Env = Env, TAction extends string = string, TResource extends string = string>
@@ -723,16 +773,41 @@ Called once by the registry on first use:
 5. Builds a `BasePoolHelper<Enforcer>` (`size = poolSize ?? 16`, `acquireTimeoutMs = poolAcquireTimeoutMs ?? 5000`). Each pooled enforcer is created **without an adapter** (no DB load at warmup), then `registerMatchers()` and `assertMatcherCompilesSync()` run on it.
 6. `await pool.warmup()` - pre-creates the enforcers.
 
-`registerMatchers()` - when `isScoped`, registers `keyMatch` as the domain matching func on `g`, adds `objectMatch` as a function, and registers it as the matching func on the resource relation (`g4`). When `domainMatching` is set (flat model), registers the chosen `Util.*Func` on the named role definition. Always finishes with `buildRoleLinks()`.
+**`registerMatchers()`** - when `isScoped`, registers three things:
+
+| Registers | On |
+|---|---|
+| `keyMatch` | Domain matching func on `g` |
+| `objectMatch` | Matcher-expression function via `addFunction` - called directly in the model's matcher string, not as a relation's matching func |
+| `ResourceRoleManager` | Named role manager for `g4` |
+
+`g4` skips `addNamedMatchingFunc` on purpose. It sets casbin's `hasPattern`, which disables `DefaultRoleManager`'s fast path on every link check, not just `g4` lookups.
+
+For every scoped model, three more role managers are wired unconditionally - not behind a separate option:
 
-`assertMatcherCompilesSync()` - a boot-time smoke test: forces casbin's lazy matcher compile with one dummy `enforceSync` (4 args when scoped/`normalizePayloadFn`, else 3), so a malformed matcher, an unregistered function, or an arity mismatch fails at warmup instead of on the first real request.
+| Registers | On | Notes |
+|---|---|---|
+| `MembershipRoleManager` | `g2` | Joining a parent domain membership makes the request domain's ancestors match too |
+| `DomainHierarchyRoleManager` | `g3` | Grant domain nesting, request-domain-first |
+| `DomainHierarchyRoleManager` (`reversed: true`) | `g`, via casbin's own `DefaultRoleManager.addDomainHierarchy()` | Role-assignment domain, stored-domain-first - the opposite argument order from `g3` |
+
+The `g3` instance, the reversed `g` instance and `MembershipRoleManager` on `g2` are handed the same overlay `Map<child, Set<parent>>`. Casbin's `buildRoleLinks()` feeds every `g3` policy line to the `g3` instance via `addLink`, which writes into that shared overlay - the reversed `g` instance and `MembershipRoleManager` only ever read it, since casbin never puts the `g`-axis manager in its own `rmMap` and so never calls `addLink` on it directly. See [Domain hierarchy edges (`g3`)](#domain-hierarchy-edges-g3) above for where those `g3` lines come from.
+
+When `domainMatching` is set (flat model), `registerMatchers()` registers the chosen `Util.*Func` on the named role definition instead, and always finishes with `buildRoleLinks()`.
+
+**`assertMatcherCompilesSync()`** is a boot-time smoke test. It forces casbin's lazy matcher compile with one dummy `enforceSync` call (4 args when scoped/`normalizePayloadFn`, else 3). A malformed matcher, an unregistered function, or an arity mismatch fails at warmup, not on the first real request.
 
 ### buildRules()
 
 Returns `ICasbinRules = { user, lines }` - the user's complete Casbin policy lines.
 
-- `extractUserLines(user)` builds a fresh, isolated enforcer *with the adapter*, calls `adapter.loadFilteredPolicy({ principal: { type, id } })`, then `extractLinesFrom()` serializes every p-type and g-type rule (not just `p`/`g` - every `p*`/`g*` the model declares, so the scoped model's `g2`-`g5` hierarchies are included) back into lines.
-- `fetchLinesWithRedisCache` returns cached lines on a hit (Redis owns expiry via `PX`). On a miss it dedups concurrent misses through `pendingLineFetches` (single-flight), extracts once, and writes the lines back to Redis. A corrupt entry is logged and discarded (refetch), never a 500.
+| Function | Behavior |
+|---|---|
+| `extractUserLines(user)` | Builds a fresh, isolated enforcer *with the adapter* and calls `adapter.loadFilteredPolicy({ principal: { type, id } })` |
+| `extractLinesFrom()` | Serializes every `p*`/`g*` rule the model declares back into lines, not just `p`/`g` - including the scoped model's `g2`-`g5` hierarchies |
+| `fetchLinesWithRedisCache` | Returns cached lines on a hit (Redis owns expiry via `PX`); on a miss, dedups concurrent misses via `pendingLineFetches` (single-flight), extracts once, and writes the lines back to Redis |
+
+A corrupt cache entry is logged and discarded, then refetched - never surfaced as a `500`.
 
 ### evaluate()
 
@@ -748,9 +823,9 @@ On any error inside `pool.use`, the pool **destroys** the borrowed enforcer (fai
 
 ### invalidateUserCache() / rebuildUserCache()
 
-Redis-only (throw if caching is disabled). `invalidateUserCache` deletes the user's shared Redis key (next request rebuilds lazily). `rebuildUserCache` deletes then immediately re-extracts (on a throwaway enforcer) and re-caches. Because the key is shared in Redis, a single call is correct across instances.
+Redis-only - both throw if caching is disabled. `invalidateUserCache` deletes the user's shared Redis key; the next request rebuilds lazily. `rebuildUserCache` deletes, then immediately re-extracts (on a throwaway enforcer) and re-caches. The key is shared in Redis, so one call is correct across every instance.
 
-Source -> [`enforcers/casbin.enforcer.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/auth/authorize/enforcers/casbin.enforcer.ts)
+Source -> [`enforcers/casbin.enforcer.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/authorize/enforcers/casbin.enforcer.ts)
 
 ## BaseFilteredAdapter
 
@@ -781,14 +856,19 @@ abstract class BaseFilteredAdapter<TFilter = ICasbinPolicyFilter> extends BaseHe
 interface ICasbinPolicyFilter { principal: { type: string; id: IdType }; }
 
 /** Minimal contract - NOT the framework's general IDataSource. Any Drizzle-backed datasource satisfies it. */
-interface ICasbinPolicySource { connector: TCasbinPolicyConnector; }
+interface ICasbinPolicySource {
+  getConnector?(): TCasbinPolicyConnector; // preferred: lazily wires the driver on first read, survives pool rotation
+  connector?: TCasbinPolicyConnector;      // back-compat: a pre-wired connector
+}
 type TCasbinPolicyConnector = PgDatabase<PgQueryResultHKT, Record<string, AnyType>>;
 ```
 
 > [!NOTE]
-> Components that only need query execution depend on this minimal local contract (`ICasbinPolicySource`) rather than a connector class - `src/components/**` never imports `@/connectors/postgres` for this.
+> `ICasbinPolicySource` is a minimal local contract, not the framework's general `IDataSource` - `src/components/**` never imports `@/connectors/postgres` for this. The `connector` getter resolves `getConnector?.() ?? connector`. When a datasource exposes neither, it throws a clear `[BaseFilteredAdapter]` error - never a bare `TypeError`.
+
+`query()` runs a raw `SQL` statement and normalizes the result to a row array. Drizzle's `execute()` shape differs per driver: node-postgres yields `{ rows }`, postgres-js yields the row list itself. Call `query()` rather than read `.rows` directly.
 
-`query()` runs a raw `SQL` statement and normalizes the result to a row array - Drizzle's `execute()` shape differs per driver (node-postgres yields `{ rows }`, postgres-js yields the row list itself), so subclasses must call `query()` rather than read `.rows` directly. `loadLines()` is the other orchestration helper - subclasses call it after assembling their own casbin lines:
+`loadLines()` is the other orchestration helper. Call it after assembling your own casbin lines:
 
 ```typescript
 protected async loadLines(opts: { model: Model; lines: string[] }): Promise<void> {
@@ -799,7 +879,7 @@ protected async loadLines(opts: { model: Model; lines: string[] }): Promise<void
 }
 ```
 
-Source -> [`adapters/base-filtered.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/auth/authorize/adapters/base-filtered.ts), [`adapters/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/auth/authorize/adapters/types.ts)
+Source -> [`adapters/base-filtered.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/authorize/adapters/base-filtered.ts), [`adapters/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/authorize/adapters/types.ts)
 
 ## ScopedCasbinAdapter
 
@@ -808,27 +888,76 @@ The generic, read-only `FilteredAdapter` for the scoped RBAC model. Reads **one
 ```typescript
 class ScopedCasbinAdapter extends BaseFilteredAdapter<IScopedCasbinPolicyFilter> {
   protected readonly entities: IScopedCasbinEntities;
-  constructor(opts: { dataSource: ICasbinPolicySource; entities: IScopedCasbinEntities });
+  protected readonly resolveDomainEdges?: TResolveDomainEdgesFn;
+  constructor(opts: {
+    dataSource: ICasbinPolicySource;
+    entities: IScopedCasbinEntities;
+    resolveDomainEdges?: TResolveDomainEdgesFn;
+  });
 
   async loadFilteredPolicy(model: Model, filter: IScopedCasbinPolicyFilter): Promise<void>;
 
-  protected queryRoleAssignments(opts): Promise<{ lines: string[]; roleIds: IdType[] }>; // -> g
-  protected queryMemberships(opts): Promise<string[]>;                                   // -> g2
-  protected queryGrants(opts): Promise<string[]>;                                        // -> p
-  protected loadStructuralTrees(): Promise<string[]>;   // role(g)/domain(g3)/resource(g4)/action(g5)
-  protected queryRoleInherits(): Promise<string[]>;     // -> g
-  protected queryDomainInherits(): Promise<string[]>;   // -> g3
-  protected queryResourceInherits(): Promise<string[]>; // -> g4
-  protected queryActionInherits(): Promise<string[]>;   // -> g5
-  protected expandRoleClosure(opts: { role: { ids: IdType[]; edges: string[] } }): IdType[]; // BFS over role_inherits
+  protected async queryPrincipalPolicies(opts: {
+    principal: { type: string; id: IdType };
+  }): Promise<TPrincipalPolicyRow[]>; // one statement, two recursive CTEs (role_closure, domain_closure) - direct edges + reachable role_inherits + role-closure grants + reachable domain_inherits
+  protected collectDirectRow(opts: {
+    row: TPrincipalPolicyRow;
+    principal: { type: string; id: IdType };
+    lines: string[];
+    directGrants: TGrantRow[];
+  }): void; // routes one 'direct' row to its g/g2 line, or into the direct-grant batch
+  protected async buildGrantLines(opts: { subjectType: string; rows: TGrantRow[] }): Promise<string[]>; // -> p, shared by direct and role-closure grants
+  protected async queryEdgePolicies(): Promise<string[]>; // -> g4 (resource_inherits) + g5 (action_inherits), the two code-fixed structural trees
 }
 ```
 
+```typescript
+/** The `kind` discriminator values in `TPrincipalPolicyRow`, one per UNION ALL branch of `queryPrincipalPolicies`. */
+class PrincipalPolicyEdges {
+  static readonly DIRECT = 'direct';
+  static readonly ROLE_EDGE = 'roleEdge';
+  static readonly ROLE_GRANT = 'roleGrant';
+  static readonly DOMAIN_EDGE = 'domainEdge';
+}
+
+/** A grant row as fetched, before it becomes casbin lines. Permission columns are null when the join misses. */
+type TGrantRow = {
+  subjectId: IdType;
+  objectCode: TNullable<string>;
+  objectSubject: TNullable<string>;
+  objectMethod: TNullable<string>;
+  action: TNullable<string>;
+  effect: TNullable<string>;
+  domain: TNullable<string>;
+  metadata?: unknown;
+};
+
+/** A row from the single principal-policy statement; `kind` says which branch produced it. */
+type TPrincipalPolicyRow = TGrantRow & {
+  kind: TConstValue<typeof PrincipalPolicyEdges>;
+  variant: string;
+  targetType: TNullable<string>;
+  targetId: IdType;
+};
+```
+
+> [!NOTE]
+> **There is no cache in the adapter.** Every `loadFilteredPolicy()` call re-runs both statements. If extraction cost becomes a measured problem, add the indexes below rather than a staleness window. The framework does not create these indexes. Your `PolicyDefinition` schema owns that, but the queries need them:
+>
+> | Index | Serves |
+> |---|---|
+> | `(variant, subject_type, subject_id)` | `queryPrincipalPolicies`' two CTE anchor terms (`role_closure`, `domain_closure`) and its `direct` branch |
+> | `(variant, subject_id)` | `role_closure`'s recursive-term join and the role-grant branch |
+> | `(variant, subject_type, subject_id)` again | `domain_closure`'s recursive term and the `domainEdge` branch. A domain node's identity is `(type, id)`, so both join on the pair, not `subject_id` alone |
+> | `(variant)`, or per-variant partial indexes | `queryEdgePolicies`' two branches (`resource_inherits`, `action_inherits`) - each filters on `variant` alone |
+>
+> Without them, the recursive CTEs' anchor and direct-edge branches fall back to a sequential scan of the whole `PolicyDefinition` table. Measured with `EXPLAIN (ANALYZE, BUFFERS)` against a real Postgres database.
+
 ```typescript
 interface IScopedCasbinTable { tableName: string; schemaName?: string; }
 
 interface IScopedCasbinEntities {
-  policyDefinition: IScopedCasbinTable;          // the single edge table
+  policyDefinition: IScopedCasbinTable & { metadata?: { columnName: string } }; // metadata.columnName opts into subset grants
   permission: IScopedCasbinTable;                // permission catalog (id, code, ...)
   principals: { user: string; role: string };    // casbin name prefixes
   domainTypes: string[];                          // e.g. ['Merchant', 'Organizer']
@@ -838,14 +967,47 @@ interface IScopedCasbinEntities {
 interface IScopedCasbinPolicyFilter { principal: { type: string; id: IdType }; }
 ```
 
-**`loadFilteredPolicy()` - two waves:**
+**`loadFilteredPolicy()` runs one wave of two independent statements:**
+
+1. `Promise.all` of two statements, neither waiting on the other:
+
+   **`queryPrincipalPolicies`** covers everything scoped to the principal, tagged by `kind`:
+
+   | `kind` | Rows |
+   |---|---|
+   | `DIRECT` | The principal's own `assign_role` / `join_domain` / `grant` rows |
+   | `ROLE_EDGE` | `role_inherits` edges reachable from its roles |
+   | `ROLE_GRANT` | Grants of that role closure |
+   | `DOMAIN_EDGE` | `domain_inherits` edges reachable from its domains |
+
+   It resolves two `WITH RECURSIVE` CTEs in SQL. `role_closure` seeds from `assign_role` rows and walks `role_inherits`. `domain_closure` seeds from `join_domain` rows and walks `domain_inherits`. Each recursive term uses `UNION`, not `UNION ALL` - the de-duplication is what terminates a cyclic graph.
+
+   **`queryEdgePolicies`** covers the two code-fixed structural trees, `resource_inherits` (`g4`) and `action_inherits` (`g5`), merged into one statement with two `UNION ALL` branches. `domain_inherits` (`g3`) is not loaded here - see [why `g3` is scoped differently](#why-g3-is-scoped-and-g4-g5-are-not).
+
+2. **Row routing:**
+
+   | `kind` | Routed to |
+   |---|---|
+   | `direct` | `collectDirectRow` - `g` for `assign_role`, `g2` for `join_domain`, or the direct-grant batch for `grant` |
+   | `roleEdge` | `g` lines, inline |
+   | `domainEdge` | `g3` lines, inline |
+   | `roleGrant` | Batched separately |
+
+   Both grant batches expand through the shared `buildGrantLines`.
+
+3. All lines load via `loadLines`.
+
+Only reachable edges are emitted: `role_inherits` edges from the principal's roles, and `domain_inherits` edges from its domains - never the whole role/domain graph. An edge outside either closure could never be traversed by the matcher anyway. This is behavior-preserving, and it shrinks every user's payload.
 
-1. **Wave 1 (parallel):** the principal's own edges - role assignments (`g`), domain memberships (`g2`), direct grants (`p`) - plus the shared structural trees (`role_inherits` -> `g`, `domain_inherits` -> `g3`, `resource_inherits` -> `g4`, `action_inherits` -> `g5`).
-2. **Role closure:** `expandRoleClosure` does a cycle-safe BFS over the `role_inherits` (`g`) edges to collect the assigned roles plus all transitive parents.
-3. **Wave 2:** fetches the grants (`p`) of every role in the closure, so a user inherits parent-role permissions.
-4. All lines load via `loadLines`.
+### Why `g3` is scoped and `g4`/`g5` are not
 
-All queries use the `sql` template tag from `drizzle-orm`; tables are schema-qualified via `sql.identifier` (injection-safe), interpolated values are bound parameters. The soft-delete clause (`AND <alias>.<col> IS NULL`) is appended when `entities.softDelete.use` is true. `queryGrants` short-circuits to `[]` when given no subject ids (no DB round-trip).
+`g4` (resource) and `g5` (action) are fixed by the codebase - a few hundred rows, constant regardless of tenant count. `queryEdgePolicies` loads them whole for every principal.
+
+`g3` (domain) grows with the domain count - many merchants under few organizers. It is scoped to the principal's domain closure inside `queryPrincipalPolicies` instead.
+
+**The permission join is a `LEFT JOIN`, not `INNER JOIN`.** A grant whose target does not resolve (missing or soft-deleted `Permission` row) is logged and skipped by `buildGrantLines`, not silently dropped from the result set.
+
+All queries use the `sql` template tag from `drizzle-orm`. Tables are schema-qualified via `sql.identifier` (injection-safe); interpolated values are bound parameters. The soft-delete clause (`AND <alias>.<col> IS NULL`) is appended when `entities.softDelete.use` is true.
 
 ```typescript
 import { ScopedCasbinAdapter } from '@venizia/ignis';
@@ -862,23 +1024,86 @@ const adapter = new ScopedCasbinAdapter({
 });
 ```
 
-Source -> [`adapters/scoped-casbin.adapter.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/auth/authorize/adapters/scoped-casbin.adapter.ts)
+Source -> [`adapters/scoped-casbin.adapter.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/authorize/adapters/scoped-casbin.adapter.ts)
 
-## objectMatch
+### `resolveDomainEdges` - `g3` edges from business data
 
-Resource-hierarchy matcher registered by the scoped model (both as a function `objectMatch(r.obj, p.obj)` in the matcher expression AND as the `g4` matching func). Decides whether a requested resource falls under a granted one, WITHOUT needing a stored edge for the "standard" case (dotted nesting is derived from the code itself):
+A second, opt-in source of `g3` edges, alongside the `DOMAIN_EDGE` branch above. Configured on the constructor, for a tenant hierarchy the app already owns as a plain foreign key on a business table rather than `domain_inherits` rows:
 
 ```typescript
-const objectMatch = (requested: string, granted: string): boolean => {
-  if (granted === '*') return true;
-  if (requested === granted) return true;
-  return requested.startsWith(`${granted}.`);
-};
+type TResolveDomainEdgesFn = (opts: {
+  principal: { type: string; id: IdType };
+  domains: string[];
+}) => Promise<Array<{ child: string; parent: string }>>;
+
+new ScopedCasbinAdapter({
+  dataSource,
+  entities,
+  resolveDomainEdges: async ({ principal, domains }) => [{ child, parent }, ...],
+});
 ```
 
-`objectMatch('Activation.findById', 'Activation')` -> `true` (dotted nesting - endpoint under subject). `objectMatch('OrderItem', 'Order')` -> `false` unless a `resource_inherits` (`g4`) edge links them - non-standard nesting always needs an explicit edge.
+`domains` is the principal's own domain closure, reconstructed from rows `queryPrincipalPolicies` already fetched (the `join_domain` seed plus both ends of every `domainEdge` row) rather than a third query. The hook returns `{ child, parent }` pairs as already-formed `<Type>_<id>` tokens; `loadFilteredPolicy` turns each into a `g3, <child>, <parent>` line, the exact shape a real `domain_inherits` row produces - nothing downstream can tell which source produced a given edge. A hook edge duplicating a real `domain_inherits` row is harmless: `DomainHierarchyRoleManager.addLink` stores parents in a `Set`, so the duplicate `addLink` call is a no-op.
+
+A throwing hook is caught, logged, and treated as no edges for that one load - the rows already gathered (direct grants, role assignments, table-sourced `g3` rows) still load normally. This is the fail-secure direction: a missing `g3` edge only narrows what `g`/`g2`/`g3` reach, it can never widen it. The hook cannot join `queryPrincipalPolicies`'s wave (it needs that query's rows to compute `domains`) but does not wait on the independent `queryEdgePolicies` either - both resolve concurrently once the closure is known.
+
+### Subset grants (custom rows)
+
+A grant row can express an arbitrary subset of a subject's operations instead of a full tier:
+
+| Field | Value |
+|---|---|
+| `action` | `'custom'` |
+| Target | A subject-level resource node - `Permission.method` is `AuthorizationPermissionBuilder.RESOURCE_NODE_METHOD`, the `*` sentinel |
+| `metadata` | `{ ops: [...] }` |
+
+`ops` holds **method names**, not full permission codes. The subject comes from the target node, so `ops: ['find']` against node `Order` resolves to `Order.find`.
+
+`buildGrantLines` expands each custom row into one `p` line per operation, using that operation's catalogued action (never the `custom` sentinel). The emitted lines are byte-identical to what equivalent per-operation grant rows produce. Expansion runs one extra batched query (`queryOperationCatalog`) per extraction, and none when no custom rows are present.
 
-Source -> [`common/object-match.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/auth/authorize/common/object-match.ts)
+Reading is **opt-in**: without `entities.policyDefinition.metadata.columnName` mapped, the adapter never selects the `metadata` column, and a custom row is logged and skipped.
+
+**Rejection rules** (`rejectCustomRow`, checked in this order). Each produces one `error`-level log line naming the subject id and object code, so a skipped grant can be diagnosed from the log alone:
+
+| Condition | Logged reason |
+|---|---|
+| `action = 'custom'` but `metadata.columnName` is not mapped | `metadata.columnName is not mapped, so metadata.ops cannot be read` |
+| `action = 'custom'` but `metadata.ops` is missing, empty, or not an array of non-empty strings | `metadata.ops is missing, empty, or not an array of non-empty strings` |
+| `metadata.ops` is present but `action` is not `'custom'` | `metadata.ops is present but action is not "custom", so the intent is ambiguous` |
+| The target's `Permission.method` is not the `*` resource-node sentinel | `the target must be a subject-level resource node` |
+
+A row that passes all four checks can still drop an individual **unresolvable operation name** during expansion. `expandCustomGrants` logs it separately, naming the unknown operations. The row's other valid operations still expand and emit lines.
+
+**Composing a grant:** use `planGrant` (below) rather than hand-building a custom row. It collapses an operation selection into tier grants wherever possible. What does not collapse falls back to a custom row, or a single per-operation row.
+
+Source -> [`adapters/scoped-casbin.adapter.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/authorize/adapters/scoped-casbin.adapter.ts)
+
+## AuthorizationPermissionBuilder.objectMatch
+
+Resource-hierarchy matcher registered by the scoped model **only** as a function - `objectMatch(r.obj, p.obj)`, called directly in the matcher expression via `addFunction`. It decides whether a requested resource falls under a granted one, without needing a stored edge for the standard case. Dotted nesting is derived from the code itself.
+
+`objectMatch` is **not** registered as the `g4` matching func. `g4` (`resource_inherits`) is served by a dedicated `ResourceRoleManager` instead - see [ScopedCasbinAdapter](#scopedcasbinadapter). Registering it via `addNamedMatchingFunc` would set casbin's `hasPattern`. That disables `DefaultRoleManager`'s O(1) fast path on every link check, not only `g4` lookups.
+
+It lives as a `static` method on `AuthorizationPermissionBuilder`, the class that owns the `code = <subject>.<method>` format it matches against. It must stay `static` with no `this` reference, since Casbin calls it by reference:
+
+```typescript
+class AuthorizationPermissionBuilder {
+  static objectMatch(requested: string, granted: string): boolean {
+    if (granted === '*') return true;
+    if (requested === granted) return true;
+    return requested.startsWith(`${granted}.`);
+  }
+}
+
+enforcer.addFunction('objectMatch', AuthorizationPermissionBuilder.objectMatch);
+```
+
+| Call | Result | Why |
+|---|---|---|
+| `objectMatch('Activation.findById', 'Activation')` | `true` | Dotted nesting - endpoint under subject |
+| `objectMatch('OrderItem', 'Order')` | `false`, unless a `resource_inherits` (`g4`) edge links them | Non-standard nesting always needs an explicit edge |
+
+Source -> [`builders/permission.builder.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/authorize/builders/permission.builder.ts)
 
 ## AuthorizationProvider
 
@@ -918,8 +1143,11 @@ for (const voter of spec.voters ?? []) {
   // ABSTAIN -> next voter
 }
 
-// 5. Resolve enforcer (no-enforcer fallback)
-if (!registry.hasEnforcers()) return next();
+// 5. Resolve enforcer (no-enforcer fallback honors defaultDecision - fails closed by default)
+if (!registry.hasEnforcers()) {
+  if (options?.defaultDecision === 'allow') return next(); // logs a warning
+  throw 403 'no enforcer registered'; // AuthorizationErrors.ENFORCER_NOT_REGISTERED
+}
 const enforcer = await registry.resolveEnforcer({ name: enforcerName ?? registry.getDefaultEnforcerName() });
 
 // 5b. Resolve request domain - only when spec.domain or a global domainResolver is in play
@@ -949,7 +1177,7 @@ await next();
 roles.map(r => typeof r === 'string' ? r : (r.identifier ?? r.name ?? String(r.id ?? '')));
 ```
 
-Source -> [`providers/authorization.provider.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/auth/authorize/providers/authorization.provider.ts)
+Source -> [`providers/authorization.provider.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/authorize/providers/authorization.provider.ts)
 
 ## Standalone authorize() function
 
@@ -962,7 +1190,7 @@ export const authorize = (opts: { spec: IAuthorizationSpec; enforcerName?: strin
 
 A module-level singleton `AuthorizationProvider`; the returned handler is a standard Hono `MiddlewareHandler`.
 
-Source -> [`middlewares/authorize.middleware.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/auth/authorize/middlewares/authorize.middleware.ts)
+Source -> [`middlewares/authorize.middleware.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/authorize/middlewares/authorize.middleware.ts)
 
 ## AuthorizationRole
 
@@ -988,7 +1216,7 @@ class AuthorizationRole implements IAuthorizationRole {
 interface IAuthorizationRole { readonly name: string; readonly priority: number; readonly identifier: string; }
 ```
 
-Source -> [`models/authorization-role.model.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/auth/authorize/models/authorization-role.model.ts)
+Source -> [`models/authorization-role.model.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/authorize/models/authorization-role.model.ts)
 
 ## Policy and permission builders
 
@@ -1003,6 +1231,8 @@ class AuthorizationPolicyBuilder {
   static readonly ACTION_PRINCIPAL = 'Action';
 
   static grant(opts: { subject: { type; id }; permission: { type; id }; action: string; domain?: TNullable<TPolicyDomainInput>; effect: TAuthorizationDecision }): PolicyDefinitionRow;
+  /** A subset grant: subject -> resource node, granting only `ops` (method names). `action` is fixed to `AuthorizationActions.CUSTOM`; the adapter expands `ops` at read time (see Subset grants). */
+  static customGrant(opts: { subject: { type; id }; permission: { type; id }; ops: string[]; domain?: TNullable<TPolicyDomainInput>; effect: TAuthorizationDecision }): PolicyDefinitionRow;
   static assignRole(opts: { user: { type; id }; role: { type; id }; domain?: TNullable<TPolicyDomainInput> }): PolicyDefinitionRow;
   static joinDomain(opts: { user: { type; id }; domain: { type; id } }): PolicyDefinitionRow;
   static roleInherits(opts: { child: { type; id }; parent: { type; id } }): PolicyDefinitionRow;
@@ -1026,7 +1256,7 @@ class AuthorizationPolicyBuilder {
 
 ### AuthorizationPermissionBuilder
 
-Builds `Permission` catalog rows (the `obj` axis the scoped matcher resolves). Generic over the name/description type, so i18n and plain-text apps both fit - the framework only owns the `code`/`method`/`action` shape.
+Builds `Permission` catalog rows (the `obj` axis the scoped matcher resolves). Generic over the name/description type, so i18n and plain-text apps both fit. The framework only owns the `code`/`method`/`action` shape.
 
 ```typescript
 class AuthorizationPermissionBuilder {
@@ -1054,7 +1284,44 @@ class AuthorizationPermissionBuilder {
 }
 ```
 
-Source -> [`common/policy-builder.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/auth/authorize/common/policy-builder.ts), [`common/permission-builder.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/auth/authorize/common/permission-builder.ts)
+Source -> [`builders/policy.builder.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/authorize/builders/policy.builder.ts), [`builders/permission.builder.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/authorize/builders/permission.builder.ts)
+
+### GrantBuilder.planGrant
+
+The supported way to compose an operations-subset grant. Pure - resolves against a caller-supplied catalog and returns rows for the caller to persist. It never touches the database. Call it on the singleton (`GrantBuilder.getInstance().planGrant(...)`).
+
+```typescript
+type TGrantIntent = { tier: TAuthorizationAction } | { ops: string[] };
+
+class GrantBuilder {
+  planGrant(opts: {
+    subject: { type: string; id: IdType };
+    resource: { type: string; id: IdType; subject: string };
+    intent: TGrantIntent;
+    catalog: Array<{ subject: string; method: string; code: string; action: string }>;
+    domain?: TNullable<TPolicyDomainInput>;
+    effect?: TAuthorizationDecision;              // default AuthorizationDecisions.ALLOW
+    supportsCustomMetadata?: boolean;              // default true - false forces per-operation rows instead of a custom row
+    exact?: boolean;                               // default false - true skips collapsing into tier grants
+  }): TPlannedGrantRow[];
+}
+```
+
+| `intent` | Behavior |
+|---|---|
+| `{ tier }` | One tier-grant row. Throws on a tier outside `read`/`write`/`execute`/`manage`. |
+| `{ ops }` collapsing into `manage` | Only when the subject has an operation in **each** of `read`, `write`, and `execute` - otherwise `manage` would silently pre-authorize a future operation in an empty tier. |
+| `{ ops }` collapsing into a narrow tier | Whenever the selection **completely covers** a `read`/`write`/`execute` tier, however few operations it holds. `ops: ['find']` collapses into `read` when `find` is the subject's only `read` operation. |
+| `{ ops }` with `exact: true` | Skips collapsing entirely - use for a selection that must never widen as new operations join a tier. |
+| Leftover after collapsing | One custom row (`AuthorizationPolicyBuilder.customGrant`) - or, when the leftover is a single operation or `supportsCustomMetadata: false`, one per-operation row per leftover operation. |
+
+A per-operation row's `permission.id` is the operation's **code** (e.g. `Order.find`), not a database id. The planner is pure and has no DB access, so the caller resolves codes to ids when persisting.
+
+Throws (`getError`) on an invalid tier, an empty `ops`, or an `ops` entry absent from the resource's catalog slice.
+
+Mirrors `ScopedCasbinAdapter.buildGrantLines`'s expansion: a planned custom row and the equivalent per-operation rows expand to identical casbin lines - see [Subset grants](#subset-grants-custom-rows).
+
+Source -> [`builders/grant.builder.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/auth/authorize/builders/grant.builder.ts)
 
 ## Model-based authorization metadata
 
@@ -1092,7 +1359,7 @@ getAuthorizeModelSettings(opts: { format: 'array' }): Array<{ name: string; auth
 getAuthorizeModelSettings(opts: { format: 'record' }): Record<string, { authorize: IModelAuthorizeSettings; entry: IModelRegistryEntry }>;
 ```
 
-Source -> [`base/metadata/persistents.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/metadata/persistents.ts), [`helpers/inversion/mixins/model.mixin.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/helpers/inversion/mixins/model.mixin.ts)
+Source -> [`base/metadata/persistents.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/base/metadata/persistents.ts), [`helpers/inversion/mixins/model.mixin.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/helpers/inversion/mixins/model.mixin.ts)
 
 ## Controller integration
 
@@ -1167,7 +1434,7 @@ type TRouteAuthConfig = { authenticate?: TRouteAuthenticateConfig; authorize?: T
 
 Applied identically to `count`, `find`, `findById`, `findOne`, `create`, `updateById`, `updateBy`, `deleteById`, `deleteBy`.
 
-Source -> [`base/controllers/rest/abstract.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/controllers/rest/abstract.ts), [`base/controllers/grpc/abstract.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/controllers/grpc/abstract.ts), [`base/controllers/factory/definition.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/controllers/factory/definition.ts)
+Source -> [`base/controllers/rest/abstract.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/base/controllers/rest/abstract.ts), [`base/controllers/grpc/abstract.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/base/controllers/grpc/abstract.ts), [`base/controllers/factory/definition.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/base/controllers/factory/definition.ts)
 
 ## Context variables
 
@@ -1180,7 +1447,7 @@ declare module 'hono' {
     [Authentication.AUDIT_USER_ID]: IdType;
     [Authentication.SKIP_AUTHENTICATION]: boolean;
 
-    [Authorization.RULES]: unknown;
+    [Authorization.RULES]: Map<string, unknown>;
     [Authorization.SKIP_AUTHORIZATION]: boolean;
     [Authorization.DOMAIN]: string;
   }