cabloy 5.1.159 → 5.1.161

package/repo-docs/backend/shared-rbac-architecture.md

@@ -0,0 +1,339 @@
+# Shared RBAC Architecture
+
+This guide explains the shared RBAC foundation used by Cabloy Basic and Cabloy Start: the Vona `a-rbac` runtime, its extension boundary, and the Resource permission projection consumed by Zova.
+
+Use this page when you need to author, extend, debug, or verify RBAC across the backend/frontend boundary. For Start's operational role, grant, Department, and policy-editor workflow, read [RBAC Authorization](/backend/rbac-authorization) after this guide.
+
+> [!WARNING]
+> RBAC authority is enforced on the backend. `ModelResource.permissions`, `$passport.checkPermission(...)`, table-action visibility, and SSR-rendered capability state are browser UX projections. None of them authorize a direct API request.
+
+## The shortest accurate mental model
+
+```text
+@Passport.rbac route metadata
+  → shared a-rbac action catalog and guard
+  → edition/application policy resolver
+  → request-local decision and typed scope access
+  → protected backend action and persisted-data checks
+
+same composed guards
+  → Resource permission projection endpoint
+  → OpenAPI permission DTO
+  → ModelSdk / ModelResource
+  → ModelPassport / action visibility
+```
+
+The two paths intentionally share a decision source, but they have different purposes:
+
+| Path                            | Purpose                                       | Authority         |
+| ------------------------------- | --------------------------------------------- | ----------------- |
+| Guard + `rbacScope`             | Admit a request and constrain persisted data  | Backend authority |
+| Permission projection + matcher | Avoid offering browser actions that will fail | Frontend UX only  |
+
+## What is shared and what is application policy
+
+The shared `a-rbac` module does **not** prescribe a role table, grant table, Department model, Admin UI, or `systemAdmin` convention. It provides a reusable runtime contract:
+
+- catalog protected route actions;
+- run the RBAC guard and validate a decision;
+- bind that decision to the current request;
+- expose typed data-scope operations to controllers;
+- emit resolver and invalidation events; and
+- derive a minimized browser permission matcher from an allowed scope.
+
+An edition or application supplies the policy facts and resolver. Cabloy Start's `admin-rbac` module is one specimen: it resolves roles, grants, and Department facts, persists policy revisions, and provides an administration UI. Those are Start policy choices, not requirements of `a-rbac`.
+
+## 1. Opt in explicitly and obtain a stable action identity
+
+A controller action participates in dynamic RBAC only when it carries `@Passport.rbac(...)` metadata:
+
+```typescript
+@Web.get()
+@Passport.rbac({ dataScope: true })
+async select(...) {
+  // consume the scope below
+}
+```
+
+The shared RBAC catalog scans registered controller routes for this explicit metadata. An ordinary route does not become a policy action merely because a Resource or frontend UI exposes it.
+
+Each catalogued action has a stable identity:
+
+```text
+<controllerBeanFullName>#<action>
+```
+
+This identity is policy-facing. It is more stable and precise than a displayed menu item, a Resource name, or an HTTP path that might be mounted differently.
+
+### Action inheritance
+
+An action can inherit another action's policy inside the same controller. The catalog resolves that relationship centrally and fails closed for:
+
+- a missing target;
+- a self-reference;
+- an inheritance cycle; or
+- an invalid cross-controller alias.
+
+Backend policy inheritance is not the same operation as a frontend `permissionHint.actionInherit`. The former selects the action policy guarded on the server; the latter selects an emitted action key used by a UI renderer. Keep both metadata paths aligned, but do not assume their similar names make them equivalent automatically.
+
+**Representative shared sources**
+
+- `vona/src/suite-vendor/a-vona/modules/a-user/src/lib/passport.ts` — `Passport.rbac(...)` guard facade.
+- `vona/src/suite-vendor/a-cabloy/modules/a-rbac/src/bean/bean.rbacCatalog.ts` — route discovery, canonical keys, and inheritance validation.
+- `vona/src/suite-vendor/a-cabloy/modules/a-rbac/src/lib/rbac.ts` — action-key and request-decision helpers.
+
+## 2. Guard execution and the policy-resolver boundary
+
+`GuardRbac` executes for a protected route. Its job is not to query a particular role/grant schema; it orchestrates a valid decision:
+
+1. clear a prior RBAC decision from the current request context;
+2. find the current route in the shared catalog;
+3. merge the catalog/decorator options for that action;
+4. ask the configured scope adapter whether the subject is unrestricted;
+5. if not unrestricted, emit `a-rbac:resolvePolicy` for application policy code;
+6. validate that the returned decision is allowed, well formed, and bound to the expected action; and
+7. store only that validated decision on the current context.
+
+The decision is request-local capability state, stored through the `SymbolRbacDecision` helpers. It is not a process-global flag, a browser claim, or reusable state for another route.
+
+```text
+GuardRbac
+  → catalog action
+  → unrestricted adapter branch
+       or
+    a-rbac:resolvePolicy listener
+  → validate action-bound decision
+  → set request-local decision
+```
+
+### Extension contracts
+
+The shared event contracts make policy implementation replaceable:
+
+| Extension point            | Shared responsibility                                                 | Application responsibility                                                      |
+| -------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| `a-rbac:resolvePolicy`     | Ask for a decision for a catalog action                               | Resolve roles, grants, ownership, organizational facts, or another policy model |
+| Scope adapter              | Ask whether the subject is unrestricted; derive trusted create values | Define unrestricted subjects and trusted business fields                        |
+| `a-rbac:policyInvalidated` | Provide a common invalidation signal                                  | Advance/clear mutable policy state and dependent caches                         |
+
+The shared role-membership listener bridges `a-user:roleMembershipChanged` to `a-rbac:policyInvalidated`. An application that mutates additional policy facts must emit invalidation through its normal durable mutation path.
+
+## 3. A passing guard is not complete row authorization
+
+After guard admission, a controller must consume the current typed scope. The common injection surface is `@Arg.rbacScopeCurrent()`; framework extraction obtains `app.bean.rbacScope.current()` for the exact request action.
+
+| Operation          | Required scope operation | Why                                                                   |
+| ------------------ | ------------------------ | --------------------------------------------------------------------- |
+| List/select        | `where(callerWhere)`     | Preserve the caller filter while adding server scope                  |
+| View/update/delete | `checkEntry(entry)`      | Check the persisted target, not a client claim                        |
+| Bulk mutation      | `checkEntries(entries)`  | Ensure every intended target is inside scope                          |
+| Create             | `ownerValues()`          | Derive trusted owner/scope fields instead of accepting widening input |
+
+A representative list shape is:
+
+```typescript
+@Web.get()
+@Passport.rbac({ dataScope: true })
+async select(@Arg.rbacScopeCurrent() rbacScopeCurrent: IRbacScopeAccess) {
+  return await this.scope.service.record.select({
+    where: rbacScopeCurrent.where(this.ctx.request.query.where),
+  });
+}
+```
+
+The details vary by Resource contract, but the security rules do not:
+
+- caller filters are structurally **ANDed** with the server predicate;
+- permitted scope terms are **OR** alternatives;
+- unrestricted access still keeps the ordinary caller filter; and
+- missing, denied, malformed, or action-mismatched request decisions fail closed.
+
+For create operations, never trust a browser-supplied owner or organizational field merely because the browser previously displayed a matching action. Use `ownerValues()` and validate the persisted result through the same server policy model.
+
+**Representative shared sources**
+
+- `vona/src/suite-vendor/a-cabloy/modules/a-rbac/src/bean/guard.rbac.ts`
+- `vona/src/suite-vendor/a-cabloy/modules/a-rbac/src/bean/bean.rbacScope.ts`
+- `vona/src/suite-vendor/a-cabloy/modules/a-rbac/src/types/scope.ts`
+- `vona/src/suite-vendor/a-vona/modules/a-web/src/lib/decorator/arguments.ts`
+
+## 4. Resource permission projection reuses real guards
+
+The frontend does not receive a parallel grant database. `BeanPermission` builds a Resource permission snapshot by evaluating the real route guards for the current Passport.
+
+The endpoint path is owned by the Home Base permission controller/service. For a Resource name, `BeanPermission`:
+
+1. maps the Resource to its controller and cached routes;
+2. omits configured ignored actions (the default excludes `select`);
+3. applies the Passport admission precheck: public/authenticated, account-active, and activation state;
+4. runs the registered `retrievePermissionAction` extension point;
+5. evaluates the actual composed guards for the target action; and
+6. returns an ordinary boolean or an RBAC projection.
+
+### Target-route guard simulation
+
+To evaluate a target action without executing its controller, the permission bean temporarily:
+
+- installs the target route as `ctx.route`;
+- sets `ctx.innerAccess = false`;
+- clears any existing request-local RBAC decision;
+- calls the real `composeGuards(...)` chain;
+- converts `false`, `401`, and `403` to a denied permission; and
+- restores the previous route, inner-access value, and the prior decision's own-property state in `finally`.
+
+Unexpected errors are not silently treated as authorization outcomes; they propagate. This isolation is essential: a permission query must not leak or corrupt a decision from the surrounding request action.
+
+### Boolean actions and RBAC actions
+
+A permitted ordinary guarded action becomes `true`; a denied action becomes `false`. A permitted RBAC action asks the current typed scope for a browser projection:
+
+```text
+boolean
+  or
+{
+  key: string,
+  allowed: boolean,
+  matcher: { mode: 'all' }
+         | { mode: 'any', rules: [{ field, values }] }
+}
+```
+
+`permissionProjection()` returns `all` for unrestricted or non-data-scoped access. A restricted decision becomes normalized field/value rules, such as a trusted owner field or a configured organizational field. A restricted decision with no usable matcher rules fails with `403`; it does not become a permissive empty projection.
+
+The contract deliberately excludes routes, guard options, raw grant expressions, and policy topology. It is still authorization-derived data: treat projected field names and values as a minimized UX contract, not as information that must remain secret from the current authorized browser.
+
+**Representative shared sources**
+
+- `vona/src/suite-vendor/a-vona/modules/a-permission/src/bean/bean.permission.ts`
+- `vona/src/suite-vendor/a-vona/modules/a-permission/src/dto/permissions.tsx`
+- `vona/src/suite-vendor/a-vona/modules/a-openapi/src/types/permissions.ts`
+- `vona/src/suite-vendor/a-cabloy/modules/a-rbac/src/bean/bean.rbacScope.ts`
+
+## 5. Cache topology and server freshness
+
+Permission projection has three distinct backend cache shapes:
+
+| Result            | Cache identity                                            | Why                                                                |
+| ----------------- | --------------------------------------------------------- | ------------------------------------------------------------------ |
+| Resource snapshot | Resource + current user                                   | The returned action map can be user-specific                       |
+| Ordinary action   | Resource + action + sorted unique role IDs                | Non-RBAC guard results can be shared by role set                   |
+| RBAC action       | Resource + action + current user + sorted unique role IDs | Resolved terms can include user-specific values, such as ownership |
+
+`BeanPermission.clearAllCaches()` clears all three permission caches. Do not collapse an RBAC result to a role-only cache: two users can hold the same roles but receive different normalized owner/scope matcher values.
+
+Server-side invalidation must follow durable policy mutation. The shared runtime provides `a-rbac:policyInvalidated`; Start's policy listener is one specimen that advances its policy revision and schedules permission-cache clearing after database commit. A Basic/custom policy implementation must provide equivalent resolver and invalidation wiring for its own mutable facts.
+
+> [!NOTE]
+> Server invalidation refreshes **future server permission evaluations**. It is not a push channel into already-open browsers.
+
+## 6. DTO, SDK, and Resource ownership
+
+The permission DTO is emitted through the backend/OpenAPI contract. Generated Home API code owns the generated operation surface, while the generic Resource runtime fetches permissions through `ModelSdk.getPermissions(resource)` so every Resource can use the same infrastructure.
+
+```text
+GET /permission/:resource
+  → IOpenapiPermissions
+  → ModelSdk.getPermissions(resource)
+  → ModelResource.permissions
+  → page/action render scope
+```
+
+`ModelResource` is selector-scoped by Resource name and owns Resource bootstrap, schemas, query/mutation state, and permissions. Pages, tables, and entry toolbars consume this resource-owned reactive surface instead of creating unrelated permission requests.
+
+Read [Model Resource Owner Pattern](/frontend/model-resource-owner-pattern) for ModelResource ownership and reuse. This guide owns the projection producer, transport, matcher, and freshness semantics.
+
+## 7. Frontend permission decision order
+
+`ModelPassport.checkPermission(...)` evaluates a permission hint and Resource snapshot in this order:
+
+1. `permissionHint.public === true` allows immediately.
+2. Resolve `permissionHint.actionInherit ?? actionName`.
+3. With no resolved action, permit the action-based check.
+4. Nil permissions or `permissions === false` deny; `permissions === true` allows.
+5. If the resolved action exists in `permissions.actions`, use that entry:
+   - boolean entries are final;
+   - RBAC objects go to `matchPermissionAction(...)`.
+6. Only when the selected action entry is absent, try legacy `roleIds` and `roleNames` fallback.
+7. Otherwise deny.
+
+An explicit denied action therefore wins over legacy role fallback. A public/actionless hint is UI metadata, not a backend bypass: the eventual API route still runs its own Passport/RBAC guards.
+
+### Matcher semantics
+
+`matchPermissionAction(...)` is deliberately fail closed:
+
+| Projection/data condition                                                 | Frontend result                           |
+| ------------------------------------------------------------------------- | ----------------------------------------- |
+| `allowed !== true`, missing matcher, malformed rule, or empty `any` rules | Deny                                      |
+| `{ mode: 'all' }`                                                         | Allow                                     |
+| Valid `any` matcher, no `currentData`                                     | Allow coarse capability/preflight         |
+| One record                                                                | At least one rule must match that record  |
+| Multiple records                                                          | Every record must match at least one rule |
+| Empty record array                                                        | Deny                                      |
+
+Rules compare `String(record[field])` with string values. With no row data, a valid restricted projection means “some records may support this action”; it does **not** mean the current or later selected row is known to be authorized.
+
+This explains a normal table pattern:
+
+```text
+operations-column preflight → no row data → retain a possible action container
+row render                  → actual row → hide actions outside the projected scope
+```
+
+Bulk/action implementations that want selected-record semantics must pass those records to the matcher. Current generic UI surfaces may use a coarser no-row-data visibility decision; backend `checkEntries(...)` remains the final bulk authority.
+
+**Representative shared sources**
+
+- `zova/src/suite/a-home/modules/home-passport/src/model/passport.ts`
+- `zova/src/suite/a-home/modules/home-passport/src/lib/permissionActionMatcher.ts`
+- `zova/src/suite/a-home/modules/home-passport/test/lib/permissionActionMatcher.test.ts`
+
+## 8. SSR, hydration, and active-tab freshness
+
+With cookie-backed server identity, Resource bootstrap can load permission state during SSR and transfer it through the query-cache hydration path. The client can start from that request-confirmed projection without an immediate duplicate server render decision.
+
+When SSR cannot use cookies for identity, `ModelResource.permissions` intentionally remains unavailable on the server. Private action visibility must retain a neutral or fail-closed shell through hydration, then obtain the client-side authoritative projection at an explicit client boundary.
+
+### Current freshness limitation
+
+`ModelSdk.getPermissions(resource)` uses `staleTime: Infinity`. The current architecture does not subscribe an already-open browser tab to server-side `a-rbac:policyInvalidated`, and it has no general targeted permission-query invalidation/refetch for an already-mounted page after an administrator changes policy.
+
+Consequences:
+
+- a removed permission can remain visible in an open tab until an explicit refresh boundary;
+- a newly granted permission can remain hidden in an open tab until that boundary; and
+- neither state bypasses the next backend guard or persisted-data scope check.
+
+Use an application-appropriate refresh, reload, relogin, or explicit query invalidation/refetch boundary after live policy changes. Do not claim that clearing backend permission caches instantly updates a hydrated frontend query.
+
+## 9. Authoring and debugging checklist
+
+When extending shared RBAC:
+
+1. Decorate only actions intended for dynamic RBAC.
+2. Keep catalog/policy inheritance valid and test every alias.
+3. Provide an `a-rbac:resolvePolicy` listener and scope adapter for the policy facts your application owns.
+4. Consume the typed scope in every protected controller operation; a passing guard alone is not enough for row security.
+5. Derive create-time ownership with `ownerValues()` instead of trusting client fields.
+6. Emit policy invalidation through durable mutations and clear dependent server caches after successful commit.
+7. Treat matcher fields/values as a minimized browser contract, and keep browser matcher semantics aligned with backend scope semantics.
+8. Test direct requests separately from menus, buttons, or permission projections.
+9. Test stale-tab behavior explicitly whenever a policy change must update a live interface.
+
+## Verification checklist
+
+- Run the shared `a-rbac` catalog/guard and scope-current tests.
+- Run permission tests that cover route substitution, request-decision restoration, cache isolation, and denied guards.
+- Run frontend matcher tests for malformed projections, `all`, restricted one-row checks, and multi-row checks.
+- Verify anonymous, inactive, granted, ungranted, and scoped direct API requests.
+- Verify both cookie-backed and cookie-disabled SSR paths preserve a hydration-safe private-action shell.
+- After a policy mutation, verify future server evaluation is fresh and explicitly verify the intended browser refresh boundary.
+
+## Read next
+
+- [RBAC Authorization](/backend/rbac-authorization) — Start roles, grants, five data scopes, and operational policy management.
+- [Controller AOP Guide](/backend/controller-aop-guide) — route guard authoring.
+- [Model Resource Owner Pattern](/frontend/model-resource-owner-pattern) — Resource-owned query and permission state.
+- [Permission, formScene, and Action Visibility Guide](/frontend/permission-formscene-action-visibility-guide) — entry-page scene filtering and action rendering.
+- [Table Action Visibility and Permission Flow Guide](/frontend/table-action-visibility-permission-flow-guide) — list-page action consumers.
+- [Menu Authorization](/backend/menu-authorization) — navigation disclosure, a separate policy domain.

package/repo-docs/backend/user-management.md

@@ -0,0 +1,92 @@
+# User Management
+
+User Management is the administrative façade for the canonical user records of an instance. It is for system operators who need to inspect and maintain accounts; it is not a second identity store, an authentication-provider guide, or a self-service registration flow.
+
+> <Badge type="warning" text="Start specimen" /> This guide uses the Cabloy Start `admin-user` module to make the operational model concrete. An edition can compose the administration UI differently while keeping the same boundary between user facts, roles, departments, and backend authorization.
+
+## What User Management owns
+
+A typical administrative User Resource lets a system administrator:
+
+- list and search user accounts;
+- view profile and account state;
+- update permitted profile fields;
+- activate accounts;
+- change account status; and
+- inspect the user's role and Department memberships.
+
+The Start controller exposes this resource surface in `vona/src/suite/cabloy-admin/modules/admin-user/src/controller/user.ts`. Its management actions are individually protected with `@Passport.systemAdmin()`:
+
+```typescript
+@Web.put('account-status/:id')
+@Passport.systemAdmin()
+async setAccountStatus(...) {
+  return await this.scope.service.user.setAccountStatus(...);
+}
+```
+
+This guard is the authority boundary. A visible Admin menu or UI action does not authorize a direct request by itself.
+
+## User facts, role memberships, and Department memberships
+
+A user record is one kind of fact. Role membership and Department membership are related but separate facts:
+
+| Fact                  | Answers                                             | Owning administration flow                              |
+| --------------------- | --------------------------------------------------- | ------------------------------------------------------- |
+| User profile          | Who is this account?                                | User Management                                         |
+| Role membership       | Which access groups does the user hold?             | [Role Management](/backend/role-management)             |
+| Department membership | Which organizational units does the user belong to? | [Department Management](/backend/department-management) |
+
+The Start user-detail service deliberately projects all three so an operator can understand the account in one place. It does not make the User Resource the owner of every membership mutation.
+
+A practical rule is: update account lifecycle in User Management; update an access grouping through Role Management; update organizational placement through Department Management.
+
+## Account lifecycle safeguards
+
+Activation and account status are different concerns. Activation is generally part of bringing a registered account into service; account status controls whether an existing account can continue to use the system.
+
+In the Start specimen, disabling an account has operational consequences beyond changing a field:
+
+1. the service refuses an unsafe system-administrator transition;
+2. permission state is cleared; and
+3. active Passport sessions for the disabled user are evicted.
+
+This protects against a stale signed-in session continuing with an old permission projection. It also illustrates why account-status changes belong in the backend service, rather than in a frontend-only switch.
+
+## Recommended operator workflow
+
+```text
+Find user
+  → inspect account, roles, and Departments
+  → update profile or account lifecycle when appropriate
+  → change role memberships in Role Management
+  → change organizational memberships in Department Management
+  → verify the affected user's refreshed access
+```
+
+When an operator changes a current user's access-related state, the relevant client should reacquire authoritative Passport, menu, and permission data. That refresh improves UX; the backend guards still enforce every request independently.
+
+## Boundaries to keep clear
+
+- User Management is not an authentication-provider implementation. Read [Auth Guide](/backend/auth-guide) for sign-in providers and authentication flows.
+- A user having a role does not automatically grant every API action. Action and data authorization are configured through [RBAC Authorization](/backend/rbac-authorization).
+- Seeing a menu does not authorize an API request. See [Menu Authorization](/backend/menu-authorization).
+- User records are scoped to the active Vona instance; do not treat an administrative view as a cross-instance lookup surface.
+
+## Verification checklist
+
+When implementing or adapting User Management, verify that:
+
+1. every account-management endpoint has an explicit backend guard;
+2. user detail can accurately distinguish account fields from role and Department memberships;
+3. disabling a user invalidates permission/session state according to the active edition's policy;
+4. protected administrator transitions cannot remove the final usable administrator; and
+5. role and Department changes are made through their respective owners rather than duplicated in a user form.
+
+## Read next
+
+- [User Access Guide](/backend/user-access-guide)
+- [Auth Guide](/backend/auth-guide)
+- [Role Management](/backend/role-management)
+- [Department Management](/backend/department-management)
+- [RBAC Authorization](/backend/rbac-authorization)

package/repo-docs/frontend/model-resource-owner-pattern.md

@@ -65,6 +65,8 @@ It becomes the place that owns:
 
 This page explains that pattern explicitly.
 
+`ModelResource` owns the reactive permission surface for its Resource. For the shared backend guard evaluation, permission DTO, matcher semantics, SSR transfer, and browser-freshness boundary behind that surface, read [Shared RBAC Architecture](/backend/shared-rbac-architecture).
+
 ## What “resource owner” means in Zova
 
 In this context, a resource-owner model is a model bean that becomes the reusable frontend boundary for one backend resource.

package/repo-docs/frontend/permission-formscene-action-visibility-guide.md

@@ -17,6 +17,7 @@ Several existing docs already explain nearby pieces:
 - [Form Scene to Page Meta Guide](/frontend/form-scene-to-page-meta-guide) explains how `formScene` becomes `formMeta`, then `pageMeta`
 - [Page Meta Guide](/frontend/page-meta-guide) explains shell/task presentation
 - [Model Resource Owner Pattern](/frontend/model-resource-owner-pattern) and related resource-model docs explain permissions as part of resource ownership
+- [Shared RBAC Architecture](/backend/shared-rbac-architecture) explains the shared backend permission projection, frontend matcher, and authority boundary
 
 What those pages do not isolate directly is the specific runtime rule for entry-page action visibility.
 
@@ -134,7 +135,7 @@ Only after the scene passes does the controller call:
 This is the critical source-confirmed distinction:
 
 - **scene filtering** decides whether this action should even be considered in the current page-entry scene
-- **permission checking** decides whether the user is allowed to perform it
+- **frontend permission checking** decides whether the current UI should offer it; backend guards remain the authoritative execution decision
 
 ## 4. What `permissionHint.formScene` really means
 
@@ -311,6 +312,7 @@ Use these next steps depending on your question:
 - if you want the list-page row/bulk contrast, read [Table Action Visibility and Permission Flow Guide](/frontend/table-action-visibility-permission-flow-guide)
 - if you want shell/task presentation semantics, read [Page Meta Guide](/frontend/page-meta-guide)
 - if you want the underlying resource permission/model context, read [Model Resource Owner Pattern](/frontend/model-resource-owner-pattern)
+- if you want the shared backend projection, matcher, SSR, and freshness semantics, read [Shared RBAC Architecture](/backend/shared-rbac-architecture)
 
 ## Final takeaway
 
@@ -318,8 +320,8 @@ The most accurate rule for current Cabloy Basic entry-page action visibility is:
 
 - `permissionHint.formScene` is a scene-aware visibility prefilter
 - `$$pageEntry.formMeta.formScene` is the current scene source
-- `$passport.checkPermission(...)` is still the actual authorization check
-- the action renders only if both layers pass
+- `$passport.checkPermission(...)` is the frontend permission-projection/visibility check; backend guards authorize execution
+- the action renders only if both UI layers pass
 - bulk actions do not currently carry `formScene` in their permission hints
 
 That is the source-confirmed `permission / formScene / action visibility` path in the current Basic frontend architecture.

package/repo-docs/frontend/table-action-visibility-permission-flow-guide.md

@@ -16,6 +16,7 @@ Several existing docs already explain nearby pieces:
 
 - [Table Guide](/frontend/table-guide) and [Zova Table Under the Hood](/frontend/zova-table-under-the-hood) explain table runtime and rendering
 - [Model Resource Owner Pattern](/frontend/model-resource-owner-pattern) explains `ModelResource` as the owner of permissions and schema
+- [Shared RBAC Architecture](/backend/shared-rbac-architecture) explains the shared backend projection, frontend matcher, and authority boundary
 - [Permission, formScene, and Action Visibility Guide](/frontend/permission-formscene-action-visibility-guide) explains the entry-page scene-aware action path
 
 What those pages do not isolate directly is the list-page row/bulk action visibility path.
@@ -247,6 +248,7 @@ Use these next steps depending on your question:
 - if you want the list-page runtime path that hosts these actions, read [Resource List Page Deep Dive](/frontend/resource-list-page-deep-dive)
 - if you want the entry-page scene-aware action path, read [Permission, formScene, and Action Visibility Guide](/frontend/permission-formscene-action-visibility-guide)
 - if you want the broader resource-owner permission surface, read [Model Resource Owner Pattern](/frontend/model-resource-owner-pattern)
+- if you want the shared projection producer, matcher, SSR, and freshness semantics, read [Shared RBAC Architecture](/backend/shared-rbac-architecture)
 - if you want table runtime internals, read [Zova Table Under the Hood](/frontend/zova-table-under-the-hood)
 
 ## Final takeaway