cabloy 5.1.103 → 5.1.105

package/.cabloy-version

@@ -1 +1 @@
-5.1.103
+5.1.105

package/.claude/skills/cabloy-backend-scaffold/references/follow-up-checklist.md

@@ -24,7 +24,7 @@ After generating or extending a backend thread, check which follow-up layers app
 
 - migration/version changes
 - `meta.version`
-- field indexes
+- field indexes; in shared-database multitenancy, preserve ordinary lookup indexes and enforce business uniqueness in tenant-aware business logic rather than with `table.unique(...)`
 - relations
 - datasource choice
 - cache behavior

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 5.1.105
+
+### Features
+
+- Filter SSR menus based on user roles.
+- Add SSR site access policies.
+- Add an event for retrieving action permissions.
+- Update `monkeySys.ts` functionality.
+
+## 5.1.104
+
+### Features
+
+- Add update capabilities.
+
+### Bug Fixes
+
+- Initialize the passport model during application startup.
+
+### Improvements
+
+- Rename the generic async state type.
+- Rename async local state APIs.
+- Document the passport SSR state bridge.
+- Clarify memory state SSR transfer behavior.
+- Clarify how to select model state helpers.
+
 ## 5.1.103
 
 ### Features

package/CLAUDE.md

@@ -67,6 +67,7 @@ Before inventing a custom implementation path:
 - `src/bean` defines the global shorthand surface; classes that should not appear in `IBeanRecordGlobal` should move to `src/lib` or `src/service` rather than being filtered by `@Virtual()`.
 - When backend code references `this.bean.xxx`, `ctx.bean.xxx`, or `app.bean.xxx`, use `IBeanRecordGlobal` and module `src/.metadata/index.ts` as the first static lookup surface; use `IBeanRecordGeneral` or `src/service` only when the target is not a global shorthand.
 - When adding a persisted field to an existing backend resource, ask the user whether `vonaModule.fileVersion` should be incremented before changing `meta.version.ts` or the module schema path. If yes, add a new migration version and bump `fileVersion`. If no, keep the current `fileVersion` and fold the schema change into the current version path. Do not assume the versioning strategy without confirmation.
+- In shared-database multitenancy, do not use `table.unique(...)` for business uniqueness. Keep ordinary indexes for lookup performance and enforce tenant-scoped uniqueness in the business layer.
 - For `@Api.field(...)` and related schemaLike composition, framework guards now preserve previously attached OpenAPI metadata across schema rebuilds, but structure-shaping schemaLike is still order-sensitive. Treat `v.object(...)`, `v.array(...)`, `v.optional()`, `v.nullable()`, `v.default(...)`, and preprocess/transform wrappers as structure-shaping; keep the final structure-defining schemaLike last and verify emitted schema/OpenAPI output after such edits.
 
 ## Verification expectations

package/cabloy-docs/backend/controller-aop-guide.md

@@ -93,8 +93,8 @@ Typical jobs include:
 ```typescript
 @Passport.public()
 @Passport.activated(false)
-@Passport.roleName({ name: 'admin' })
-@Passport.admin()
+@Passport.roleName({ name: 'systemAdmin' })
+@Passport.systemAdmin()
 ```
 
 These shorthands still map back to the generic aspect model.

package/cabloy-docs/backend/field-indexes.md

@@ -66,6 +66,14 @@ Field indexes can also be configured through app config.
 
 That means index behavior participates in the broader configuration system rather than being locked into one metadata file only.
 
+## Shared-database multitenancy and business uniqueness
+
+Ordinary indexes in `meta.index` improve lookup and query performance. They do not define a business uniqueness rule.
+
+In shared-database multitenancy, do not use `table.unique(...)` for tenant-scoped business uniqueness. A database-wide unique constraint can reject the same business value when it belongs to a different tenant.
+
+Keep the ordinary indexes needed by the access pattern, and enforce the tenant-scoped uniqueness rule in tenant-aware business logic.
+
 ## Implementation checks for persistence changes
 
 When changing persistence design, do not stop at entity fields and model methods.
@@ -74,7 +82,8 @@ Also ask:
 
 1. does this access pattern need an index?
 2. should the index belong in `meta.index`?
-3. is the typed style a better fit than raw string declarations?
+3. does a business key need tenant-scoped uniqueness, to be enforced in tenant-aware business logic rather than with `table.unique(...)`?
+4. is the typed style a better fit than raw string declarations?
 
 That leads to backend changes that are more production-aware and more aligned with Vona’s module metadata model.
 

package/cabloy-docs/backend/menu-guide.md

@@ -55,6 +55,36 @@ This makes menu retrieval part of the broader backend contract surface.
 
 In the current repo implementation, the out-of-the-box menu controller is public and delegates directly to `this.scope.service.menu.retrieveMenus(publicPath)`.
 
+## Static menu visibility
+
+`@SsrMenu(...)` items can declare static role visibility without changing the public menu DTO:
+
+```typescript
+@SsrMenu({
+  item: {
+    title: $locale('Operations'),
+    link: 'presetResource',
+    roles: ['systemAdmin'],
+  },
+  site: 'basic-siteadmin:admin',
+})
+```
+
+- Omit `roles`, or use `roles: []`, to make an item visible to anonymous and authenticated callers.
+- A nonempty `roles` array is visible when the current Passport has at least one matching role name.
+- `roles` is server-only declaration metadata. It is filtered out before the API response and is not part of `IMenuItem`, OpenAPI, or generated frontend clients.
+- This controls navigation disclosure only. It never grants access to a page, controller action, API, or resource; those boundaries retain their own route and Passport/permission guards.
+
+SSR Site menu definitions are cached structurally by Site and locale. The framework keeps static role policy in that prepared cache, then creates a filtered response for each request without mutating the cached definition.
+
+### Frontend query lifecycle
+
+Passport filtering does not add user or role identity to the frontend menu query key. The menu resource remains keyed by stable inputs: Site/public path and locale.
+
+On login, `ModelPassport.afterLogin()` stores the Passport/JWT before returning to the destination layout. The layout's ordinary `$useStateData(...)` lifecycle refreshes stale menu data using the newly authenticated request context. On logout, the Passport model navigates to login and then clears query data.
+
+A dynamic role or menu-policy change while the user remains signed in is different: the mutation owner must explicitly refresh authoritative Passport state when needed and invalidate or refetch the affected menu query. This is UI freshness behavior only; route, controller, API, and resource authorization remain enforced independently by their existing guards.
+
 ## Relationship to frontend integration
 
 Menu retrieval is especially relevant in SSR-sensitive frontend flows.

package/cabloy-docs/frontend/a-model-under-the-hood.md

@@ -85,9 +85,21 @@ Its main jobs are:
 - create the shared `QueryClient`
 - create the `QueryCache`
 - install the Vue Query plugin into the app
-- on the server, dehydrate query state after render
-- on the client, hydrate query state during SSR pre-hydration
-- clear the query client after server rendering completes
+- on the server, dehydrate eligible query state after render into `stateDefer.query`
+- on the client, hydrate that snapshot during SSR pre-hydration
+- clear the server query client after the snapshot has been created
+
+The server-to-client handoff is therefore:
+
+```text
+server QueryClient
+  → dehydrate after render
+  → stateDefer.query
+  → deferred SSR bootstrap state
+  → client QueryClient hydrate during SSR pre-hydration
+```
+
+This is an initial SSR handoff, not browser persistence. The server cache is request-scoped for this flow and is cleared after its snapshot is taken.
 
 This is the second important lower-level rule:
 
@@ -200,6 +212,10 @@ A practical reading rule is:
 - different state families differ in persistence/storage and SSR behavior
 - but they still participate in one model runtime vocabulary and query-key system
 
+`$useStateMem(...)` makes the two policy axes especially clear. It returns an assignable custom-ref surface that reads and writes through the Model Query Cache, while setting `persister: false` so no browser storage adapter is used. No persistence backend does not imply no SSR transfer: a successful eligible memory query can still be included in the shared Query Cache snapshot.
+
+A hydrated entry is reusable only when the later call resolves to the same effective key. The runtime prefixes each logical key with Model identity and, for selector-enabled Models, selector identity.
+
 ## Persister storage selection and restore/save/remove behavior
 
 The persister layer lives in:
@@ -243,7 +259,13 @@ This file confirms default behavior such as:
 - persistence max-age defaults
 - dehydration rules for sync persister-backed queries
 
-This is the place to check when the runtime feels surprising even though your page/model code looks correct.
+The current dehydration decision is ordered:
+
+1. `meta.ssr.dehydrate === false` explicitly excludes a query.
+2. A sync persister-backed query is excluded.
+3. Remaining queries use TanStack Query's current default dehydration predicate, which accepts successful queries.
+
+This is why `$useStateMem(...)` can participate in the initial SSR transfer despite `persister: false`, while `$useStateLocalAsync(...)` opts out explicitly. This is the place to check when the runtime feels surprising even though your page/model code looks correct.
 
 ## What this page does not re-explain
 

package/cabloy-docs/frontend/model-architecture.md

@@ -129,7 +129,7 @@ The `a-model` source exposes five main state families through `BeanModelBase` he
 - `mem` → in-memory state through `$useStateMem(...)`
 - `local` → local-storage state through `$useStateLocal(...)`
 - `cookie` → cookie-backed state through `$useStateCookie(...)`
-- `db` → async persisted state through `$useStateDb(...)`
+- `db` → async persisted state through `$useStateLocalAsync(...)`
 
 This is why Zova Model is better understood as a **unified model-state layer** rather than only a remote-data wrapper.
 

package/cabloy-docs/frontend/model-state-guide.md

@@ -86,7 +86,34 @@ The important point is architectural:
 
 ## The main helper families
 
-The current source organizes model state around these helper families.
+The current source organizes model state around these helper families. They share model-owned query-key and cache infrastructure, but differ in the surface returned to callers and in their persistence and restore lifecycle.
+
+### Choose the state helper by ownership and lifecycle
+
+Choose a helper by the state surface, persistence, restore, and SSR behavior it needs, not only by whether its value should survive a reload.
+
+| Helper                     | Use it when                                                                       | Caller-facing surface                                                     | Persistence and restore                                                                      |
+| -------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `$useStateData(...)`       | The model owns remote or query-style async state and consumers need query status  | Full query wrapper, including `data`, `error`, and readiness/status state | Normal query lifecycle; may participate in query hydration subject to metadata               |
+| `$useStateMem(...)`        | The model owns reusable runtime state without a browser persistence backend       | Assignable state value                                                    | No browser persistence; eligible successful state can transfer through initial SSR hydration |
+| `$useStateLocal(...)`      | The model owns a small browser value that should restore synchronously            | Assignable state value                                                    | Synchronous `localStorage` restore                                                           |
+| `$useStateCookie(...)`     | The state needs cookie persistence or request-aware handling                      | Assignable state value                                                    | Synchronous cookie restore                                                                   |
+| `$useStateLocalAsync(...)` | The model owns longer-lived browser-local state whose restore may be asynchronous | Assignable state value                                                    | Asynchronous `localforage` restore                                                           |
+| `$useStateComputed(...)`   | The model exposes derived state                                                   | Computed value                                                            | No query fetch or persistence                                                                |
+
+### Data, local, and async-local behavior
+
+`$useStateData(...)`, `$useStateLocal(...)`, and `$useStateLocalAsync(...)` use the same model-owned cache foundation, but they are not interchangeable.
+
+| Concern              | `$useStateData(...)`                                      | `$useStateLocal(...)`                                         | `$useStateLocalAsync(...)`                                                                            |
+| -------------------- | --------------------------------------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| Return surface       | A memoized query wrapper                                  | An assignable state value                                     | An assignable state value                                                                             |
+| Source or storage    | `queryFn`, query cache, and query configuration           | `localStorage`                                                | `localforage`                                                                                         |
+| Initial availability | Follows the query lifecycle                               | Restores synchronously, then falls back to `meta.defaultData` | Restores asynchronously, then falls back to `meta.defaultData`                                        |
+| Intended write flow  | Mutation, cache update, and invalidation policy           | Replace or assign the model field                             | Replace or assign the model field                                                                     |
+| SSR behavior         | Can follow ordinary query dehydration and hydration rules | Browser storage is unavailable on the server                  | Browser storage is unavailable on the server and async-local state explicitly opts out of dehydration |
+
+Use the detailed [`$useStateData` Best Practices](/frontend/use-state-data-best-practices) guide for render-versus-interaction placement, `disableSuspenseOnInit`, freshness utilities, and explicit readiness boundaries.
 
 ### 1. `$useStateData(...)`
 
@@ -155,16 +182,62 @@ The pattern to notice is that the model owns both the mutation and the follow-up
 
 ## 3. `$useStateMem(...)`
 
-Use this when the state should stay only in memory.
+Use this for reusable runtime state that belongs to a Model but does not need a browser persistence backend. It returns an assignable value, rather than a query wrapper, while retaining Model-owned Query Cache identity.
 
 Current-source characteristics:
 
-- no persistence
-- `enabled: false`
+- `enabled: false`, so it does not define a normal remote-fetch lifecycle
 - `staleTime: Infinity`
-- still uses model-owned query cache semantics under the hood
+- `meta.persister: false`, so it does not read or write `localStorage`, cookies, or `localforage`
+- reads from existing Query Cache first, then `meta.defaultData`, then `undefined`
+- assignments update the Query Cache without a persister save
+- automatic key prefixing isolates the state by Model identity and, when enabled, selector identity
+
+This is useful when several consumers or Model methods need the same business state during the current frontend runtime, but the browser should not restore it from storage. For structured values, replace or assign the Model field so its custom-ref setter updates the Query Cache:
+
+```typescript
+this.selectedIds = nextSelectedIds;
+```
+
+A plain Controller field is usually clearer when the state belongs only to that one Controller. Choose `$useStateLocal(...)`, `$useStateCookie(...)`, or `$useStateLocalAsync(...)` when browser persistence is part of the requirement. Choose `$useStateData(...)` when consumers need query status, errors, freshness, or a remote-fetch lifecycle.
+
+### SSR transfer is not persistence
+
+`meta.persister: false` means no browser persistence backend. It does not, by itself, exclude the state from the initial SSR server-to-client Query Cache handoff.
+
+After server rendering, a successful eligible memory-state query can be dehydrated with the shared Query Cache. During client SSR pre-hydration, the snapshot is hydrated into the client QueryClient. A later `$useStateMem(...)` read can therefore receive the transferred value directly from cache when its effective key matches: the same Model, the same selector when selector mode is enabled, and the same logical `queryKey`.
+
+This transfer has limits:
+
+- it applies only to entries accepted by the normal dehydration policy; `meta.ssr.dehydrate: false` opts a state out
+- it is not a replacement for `localStorage`, cookies, or async-local persistence
+- it does not make the value survive a later browser reload without a new SSR handoff
+- it does not make an empty or unsuccessful cache entry transfer automatically
+
+The router-tabs Model uses memory state for current navigation keys and for tabs when tab caching is disabled. The page-data Model uses memory slots keyed by page path. Read [SSR Init Data](/frontend/ssr-init-data) for the page-side flow, or [A-Model Under the Hood](/frontend/a-model-under-the-hood) for the Query Cache and dehydration mechanics.
+
+### SSR/CSR bridge: `ModelPassport`
+
+`ModelPassport` shows that the state helper selected on the server and the one selected on the client do not have to be the same. Its application initialization creates the same logical state differently by environment:
+
+```typescript
+this.passport = process.env.CLIENT
+  ? this.$useStateLocal({ queryKey: ['passport'] })
+  : this.$useStateMem({ queryKey: ['passport'] });
+```
+
+On the SSR server, authenticated work can assign the current passport to the memory-backed Query Cache entry. If that entry is successful and eligible, it is dehydrated with the server QueryClient. During client SSR pre-hydration, the snapshot restores the entry before the client Model consumes it.
+
+The client then creates a `$useStateLocal(...)` wrapper for the same effective key. Its read order is Query Cache first, then `localStorage`, then `meta.defaultData`. The hydrated server passport therefore wins on the initial client read; synchronous local-storage restoration is a fallback only when the transferred cache entry is absent.
+
+This gives authentication state two complementary properties:
+
+- SSR uses the request-confirmed passport to keep the initial HTML and client hydration consistent.
+- CSR-only entry and later browser sessions can restore the client-local passport value from `localStorage`.
+
+The server `$useStateMem(...)` entry is the entry that is dehydrated. The client `$useStateLocal(...)` call is a new client-side wrapper that reuses hydrated cache because its effective key matches. Matching requires the same Model, the same selector when selector mode is enabled, and the same logical `queryKey`; the short logical key alone is not global identity.
 
-This is useful when you want model ownership and query-key identity without local persistence.
+Reading the hydrated value does not save it back to `localStorage`. A later assignment through the client local-state wrapper updates Query Cache and writes the local-storage record. This is an initial SSR cache handoff plus client persistence fallback, not automatic persistence of the SSR snapshot.
 
 ## 4. `$useStateLocal(...)`
 
@@ -195,9 +268,9 @@ Current-source characteristics:
 
 This is particularly relevant for state that must participate in request-aware or SSR-adjacent flows.
 
-## 6. `$useStateDb(...)`
+## 6. `$useStateLocalAsync(...)`
 
-Use this when the model state should persist asynchronously in db-style client storage.
+Use this when the model state should persist asynchronously in browser-local storage backed by `localforage`.
 
 Current-source characteristics:
 
@@ -205,10 +278,40 @@ Current-source characteristics:
 - `enabled: false`
 - `staleTime: Infinity`
 - explicit `ssr.dehydrate = false`
-- getters may need async restore flow before data is available
+- the first unresolved read may need async restore before the state is available
 
 This is useful for larger persisted client state that should outlive a page session without being stored in cookies or plain local storage.
 
+### Initialize and ensure async-local state
+
+Assign the state property before awaiting it. When later initialization depends on the restored value, establish an explicit restore boundary with `$ensureStateLocalAsync(...)`. It waits for the pending initial restore to settle; it does not force another load and does not guarantee a defined result:
+
+```typescript
+protected async __init__() {
+  this.tabs = this.$useStateLocalAsync({
+    queryKey: ['tabs'],
+    meta: {
+      defaultData: [],
+    },
+  });
+
+  await this.$ensureStateLocalAsync(this.tabs);
+
+  // Continue only after persisted tabs, or the fallback default, is available.
+  this.initializeTabs();
+}
+```
+
+`meta.defaultData` is a fallback: it initializes the state only when no persisted value is restored. If neither provides a value, the ensured result can still be `undefined`. The router-tabs model follows this assign-then-ensure sequence before it continues with route initialization.
+
+Persisted local and async-local state should be updated by replacing or assigning the model field so its custom-ref setter can update query state and persist the new value:
+
+```typescript
+this.tabs = nextTabs;
+```
+
+Do not rely on an in-place nested mutation alone to persist the change. Assigning `undefined` removes the persisted value.
+
 ## 7. `$useStateComputed(...)`
 
 Use this when the model should expose derived state that is still model-key-oriented but computed locally.
@@ -233,6 +336,8 @@ that logical key is prefixed internally with model identity, and with selector w
 
 That means model code can use short business-facing keys while still getting namespace isolation.
 
+Automatic model namespacing does not make every varying runtime value part of the logical key. Logical keys still describe stable resource inputs. Do not add a user or role fingerprint solely because a backend response is evaluated through the current Passport; use the normal authentication lifecycle for login/logout and explicitly invalidate or refetch affected stable keys for an in-session policy change. See [use-state-data-best-practices.md](./use-state-data-best-practices.md) for the full rule.
+
 ## Persistence and restore behavior
 
 Current source treats persistence as part of the model-state runtime.
@@ -252,16 +357,17 @@ Model state choices can affect SSR behavior.
 
 Current-source behaviors to remember:
 
-- query state can be dehydrated on server and hydrated on client
+- successful eligible Query Cache state can be dehydrated on the server and hydrated on the client
+- `$useStateMem(...)` has no browser persister but can participate in that initial SSR handoff unless excluded by metadata
 - mutations are not dehydrated
-- `db` state is explicitly not dehydrated
-- server cannot use local-storage or db persistence backends
-- cookie state is special because cookie access can still exist through the app cookie surface
+- `$useStateLocalAsync(...)` explicitly opts out of dehydration
+- server-side sync local and cookie persister-backed Query Cache entries are excluded by the default dehydration policy; this does not prevent a client `$useStateLocal(...)` or `$useStateCookie(...)` wrapper from reusing a hydrated entry that the server created with a different eligible helper
+- server cannot use local-storage or async-local persistence backends; cookie state is special because cookie access can still exist through the app cookie surface
 
 Practical implication:
 
-- do not assume every persisted model state behaves the same during SSR
-- choose `mem`, `local`, `cookie`, `db`, or `data` based on ownership and hydration requirements, not only convenience
+- do not equate browser persistence with SSR transfer, or assume every state family behaves the same during SSR
+- choose `mem`, `local`, `cookie`, `localAsync`, or `data` based on ownership, persistence, and hydration requirements, not only convenience
 
 ## Real examples to read
 
@@ -289,7 +395,7 @@ This file shows:
 
 - `@Model({ enableSelector: true, ... })`
 - richer model initialization in `__init__`
-- mixed use of `$useStateMem(...)` and `$useStateDb(...)`
+- mixed use of `$useStateMem(...)` and `$useStateLocalAsync(...)`
 - model-owned tab state with cache and persistence decisions
 
 ### SSR-sensitive auth model

package/cabloy-docs/frontend/ssr-init-data.md

@@ -31,7 +31,18 @@ export class ControllerPageTodo {
 1. a model bean encapsulates the data access path
 2. the controller injects the model
 3. `__init__` prepares the data on the server
-4. model-based SSR support synchronizes that data to the client and completes hydration automatically
+4. successful eligible Query Cache state is captured in the SSR handoff
+5. client SSR pre-hydration restores that cache before the client model consumes it
+
+## What hydration reuses
+
+The initial SSR handoff reuses model Query Cache data, not only `$useStateData(...)` results. A successful eligible `$useStateMem(...)` value can also transfer from the server to the initial client runtime even though it has no browser persistence backend.
+
+Client reuse requires the model call to resolve to the same effective query key: Zova prefixes the logical key with Model identity and, for selector-enabled models, selector identity. State marked with `meta.ssr.dehydrate: false` is excluded. This handoff does not make memory state durable across a later browser reload, and it does not guarantee that every client query avoids fetching.
+
+`ModelPassport` is a concrete SSR/CSR bridge: the server creates `passport` with `$useStateMem({ queryKey: ['passport'] })`, while the client creates `$useStateLocal({ queryKey: ['passport'] })`. The successful eligible server memory entry is what SSR transfers. Because the client local-state wrapper reads Query Cache before `localStorage`, the hydrated passport supplies the initial client value when the effective key matches. If no transferred entry exists, `$useStateLocal(...)` can instead restore its browser-local value. Hydration alone does not save the transferred value to `localStorage`; later client-side assignments do.
+
+For helper selection and the complete passport flow, read [Model State Guide](/frontend/model-state-guide). For the dehydration filter and QueryClient lifecycle, read [A-Model Under the Hood](/frontend/a-model-under-the-hood).
 
 ## Implementation checks for SSR data-loading changes
 

package/cabloy-docs/frontend/use-state-data-best-practices.md

@@ -325,6 +325,29 @@ Readable keys improve:
 - tracing cache behavior
 - future refactors when similar query families grow
 
+## Practical rule 9: key stable resource inputs, not ambient caller identity
+
+A `$useStateData(...)` query key identifies the stable variant of a resource. Include inputs that change that variant, such as an operation or resource identifier, filters, pagination, Site/public path, or locale.
+
+Do not append the current username, authenticated flag, Passport role names or IDs, or another authorization fingerprint merely because the server evaluates the current Passport while producing the response. Those values are ambient request context, not automatically part of the frontend resource identity.
+
+Normal authentication transitions already provide lifecycle boundaries: login stores the new Passport before navigating into the destination model, and that model's ordinary query lifecycle refreshes stale data under the new request context. Logout clears query data after leaving protected UI.
+
+Use explicit invalidation or refetch when authorization policy changes during an otherwise continuing authenticated session, such as an administrator changing role membership, Site policy, or menu policy. Refresh authoritative Passport state when necessary, then synchronize the affected stable resource key; do not turn a policy fingerprint into the key by default.
+
+For example, the menu resource is keyed by its stable Site/public path and locale:
+
+```ts
+queryKey: ['retrieveMenus', publicPath, locale];
+```
+
+Do not key it by the current roles:
+
+```ts
+// Avoid: roles are ambient request policy, not menu resource identity.
+queryKey: ['retrieveMenus', publicPath, locale, roleNames];
+```
+
 ## Anti-pattern: command-first controller state
 
 A common anti-pattern looks like this:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cabloy",
-  "version": "5.1.103",
+  "version": "5.1.105",
   "gitHead": "2c5c19284bab738e492856189acb6fad74b8a7b7",
   "description": "A Node.js fullstack framework",
   "keywords": [

package/vona/packages-vona/vona/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona",
-  "version": "5.1.73",
+  "version": "5.1.74",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "Vona is an intuitive, elegant and powerful Node.js framework for rapidly developing enterprise applications of any size",
   "keywords": [

package/vona/pnpm-lock.yaml

@@ -501,8 +501,8 @@ importers:
         specifier: npm:@cabloy/zod@4.3.8
         version: '@cabloy/zod@4.3.8'
       zova:
-        specifier: ^5.1.132
-        version: 5.1.132(typescript@5.9.3)(vue@3.5.39(typescript@5.9.3))
+        specifier: ^5.1.134
+        version: 5.1.134(typescript@5.9.3)(vue@3.5.39(typescript@5.9.3))
       zova-jsx:
         specifier: ^1.1.77
         version: 1.1.77(typescript@5.9.3)
@@ -528,8 +528,8 @@ importers:
         specifier: ^5.1.29
         version: 5.1.29
       zova-module-a-model:
-        specifier: ^5.1.31
-        version: 5.1.31(vue@3.5.39(typescript@5.9.3))
+        specifier: ^5.1.33
+        version: 5.1.33(vue@3.5.39(typescript@5.9.3))
       zova-module-a-openapi:
         specifier: ^5.1.43
         version: 5.1.43
@@ -537,8 +537,8 @@ importers:
         specifier: ^5.1.29
         version: 5.1.29
       zova-module-a-routertabs:
-        specifier: ^5.1.32
-        version: 5.1.32
+        specifier: ^5.1.33
+        version: 5.1.33
       zova-module-a-ssr:
         specifier: ^5.1.29
         version: 5.1.29
@@ -573,8 +573,8 @@ importers:
         specifier: npm:@cabloy/zod@4.3.8
         version: '@cabloy/zod@4.3.8'
       zova:
-        specifier: ^5.1.132
-        version: 5.1.132(typescript@5.9.3)(vue@3.5.39(typescript@5.9.3))
+        specifier: ^5.1.134
+        version: 5.1.134(typescript@5.9.3)(vue@3.5.39(typescript@5.9.3))
       zova-jsx:
         specifier: ^1.1.77
         version: 1.1.77(typescript@5.9.3)
@@ -600,8 +600,8 @@ importers:
         specifier: ^5.1.29
         version: 5.1.29
       zova-module-a-model:
-        specifier: ^5.1.31
-        version: 5.1.31(vue@3.5.39(typescript@5.9.3))
+        specifier: ^5.1.33
+        version: 5.1.33(vue@3.5.39(typescript@5.9.3))
       zova-module-a-openapi:
         specifier: ^5.1.43
         version: 5.1.43
@@ -609,8 +609,8 @@ importers:
         specifier: ^5.1.29
         version: 5.1.29
       zova-module-a-routertabs:
-        specifier: ^5.1.32
-        version: 5.1.32
+        specifier: ^5.1.33
+        version: 5.1.33
       zova-module-a-ssr:
         specifier: ^5.1.29
         version: 5.1.29
@@ -1517,13 +1517,13 @@ importers:
   src/suite-vendor/a-file:
     dependencies:
       vona-module-a-file:
-        specifier: ^5.0.4
+        specifier: ^5.0.5
         version: link:modules/a-file
       vona-module-file-cloudflare:
-        specifier: ^5.0.3
+        specifier: ^5.0.4
         version: link:modules/file-cloudflare
       vona-module-file-native:
-        specifier: ^5.0.3
+        specifier: ^5.0.4
         version: link:modules/file-native
 
   src/suite-vendor/a-file/modules/a-file:
@@ -1625,7 +1625,7 @@ importers:
   src/suite-vendor/a-test:
     dependencies:
       vona-module-test-file:
-        specifier: ^5.0.4
+        specifier: ^5.0.5
         version: link:modules/test-file
 
   src/suite-vendor/a-test/modules/test-auth:
@@ -7993,8 +7993,8 @@ packages:
   zova-module-a-meta@5.1.21:
     resolution: {integrity: sha512-7vsLOMw1UQEZ+8qbBaiz9t4n3N7AU1jxpaiSIIky7hBvKO9nuHq+e7FONpj9poa8WeHkYoflBg/8imKBy/IlNw==}
 
-  zova-module-a-model@5.1.31:
-    resolution: {integrity: sha512-/6MV5xSklEkain5t0vsZ37ImyIihutCu7ymytq5RFG0QbeKtbSAI/IB6TS2mfkjLkiy97SmDJbuiLGso7Cg/Gw==}
+  zova-module-a-model@5.1.33:
+    resolution: {integrity: sha512-NwxCguvESPLUSA2zo5vVH3Qx29o5znmUL2qU9khwjXUmDPbOTeYTkgPCI33fTsy8VnkguoWBLMgUdOsaJF+7OA==}
 
   zova-module-a-openapi@5.1.43:
     resolution: {integrity: sha512-xJKvSPl1AZnH7EpgEd9a3u3IEpJfnou19DKre/7TL1KdiTdfNThLrmmkdP1UNYlUHUgCczcGUwZDdMiE9gdxwA==}
@@ -8005,8 +8005,8 @@ packages:
   zova-module-a-routerstack@5.1.26:
     resolution: {integrity: sha512-uu4tFw2DUruanPR7cojM5p6rvyCIh+tnwPmq7s0jZdg+5XBr+YMy1RGjnE8vPFSLHW8C71hlNbps6VpKvKMiiQ==}
 
-  zova-module-a-routertabs@5.1.32:
-    resolution: {integrity: sha512-HZziZYnXUAZZ3YhQl2Qc+/KhCS7/GlKs9Ob4eIZok+YdDPF3iaVJsW+y+5l3rbtxIFsZtRsUZtoys2+p5wEvSQ==}
+  zova-module-a-routertabs@5.1.33:
+    resolution: {integrity: sha512-u5YIFc7OfUsxruIG8QP4sH1+TCps2vAYUpAMNfT1XPkJLHdFGkjEc6++KMCpv4jGpNDoQ42/LefEQGg7vqnQuw==}
 
   zova-module-a-ssr@5.1.29:
     resolution: {integrity: sha512-wlxLSy+Wjh/UFEVqsKQ105bvXceXPdIDmJQPKF0hSwiNY1R8HUottADfXPwYOatzZAayZ4AU4vQIpG92F2GJiA==}
@@ -8032,11 +8032,11 @@ packages:
   zova-module-rest-resource@5.1.41:
     resolution: {integrity: sha512-7Y8rLmHdw0pynlWqsyHPWuCWFLwr/0HsNvfef64cPw91LRujf/7OlulVWqH8ZoFNioZZUpfumB+t/+mICoYfFg==}
 
-  zova-suite-a-zova@5.1.131:
-    resolution: {integrity: sha512-NRPt3ahLwHg+rLuA2VXRbEmrg/bTdgwdQmU9C8nj9R0+E1f0ehbbsUWJFQFN6hJNco5+rDDSDfBlvejf4z6L1w==}
+  zova-suite-a-zova@5.1.133:
+    resolution: {integrity: sha512-N7YSmamP2eV3MBV4RnFXXUlDg9yEcvYkHDxfcgQQFjR1iQyxNbCLO1Ud4Bjcinray2KNrnOF41e+0gn7A6jzRQ==}
 
-  zova@5.1.132:
-    resolution: {integrity: sha512-lQK1VRnwthDx0qayS7kdElyfAmvPEhlt6sk/2jK5mTbqojsjuDNkrEa9Ck2Q78fag800U6pDwV83o6CRbSUTeA==}
+  zova@5.1.134:
+    resolution: {integrity: sha512-nnieXjXy0+94FKZCT05dGvwASJQ7PiM387r+dToLAuSFRCqgQwaLvYyrOXN2RhKt8Z5nefWDMwA9LPWgBksnLg==}
 
   zwitch@1.0.5:
     resolution: {integrity: sha512-V50KMwwzqJV0NpZIZFwfOD5/lyny3WlSzRiXgA0G7VUnRlqttta1L6UQIHzd6EuBY/cHGfwTIck7w1yH6Q5zUw==}
@@ -13935,7 +13935,7 @@ snapshots:
 
   zova-module-a-meta@5.1.21: {}
 
-  zova-module-a-model@5.1.31(vue@3.5.39(typescript@5.9.3)):
+  zova-module-a-model@5.1.33(vue@3.5.39(typescript@5.9.3)):
     dependencies:
       '@tanstack/query-core': 5.101.2
       '@tanstack/query-persist-client-core': 5.101.2
@@ -13957,7 +13957,7 @@ snapshots:
 
   zova-module-a-routerstack@5.1.26: {}
 
-  zova-module-a-routertabs@5.1.32: {}
+  zova-module-a-routertabs@5.1.33: {}
 
   zova-module-a-ssr@5.1.29:
     dependencies:
@@ -14010,7 +14010,7 @@ snapshots:
 
   zova-module-rest-resource@5.1.41: {}
 
-  zova-suite-a-zova@5.1.131(typescript@5.9.3)(vue@3.5.39(typescript@5.9.3)):
+  zova-suite-a-zova@5.1.133(typescript@5.9.3)(vue@3.5.39(typescript@5.9.3)):
     dependencies:
       zova-module-a-api: 5.1.21
       zova-module-a-app: 5.1.24
@@ -14025,11 +14025,11 @@ snapshots:
       zova-module-a-interceptor: 5.1.29
       zova-module-a-logger: 5.1.26
       zova-module-a-meta: 5.1.21
-      zova-module-a-model: 5.1.31(vue@3.5.39(typescript@5.9.3))
+      zova-module-a-model: 5.1.33(vue@3.5.39(typescript@5.9.3))
       zova-module-a-openapi: 5.1.43
       zova-module-a-router: 5.1.29
       zova-module-a-routerstack: 5.1.26
-      zova-module-a-routertabs: 5.1.32
+      zova-module-a-routertabs: 5.1.33
       zova-module-a-ssr: 5.1.29
       zova-module-a-ssrhmr: 5.1.22
       zova-module-a-ssrserver: 5.1.22
@@ -14044,10 +14044,10 @@ snapshots:
       - typescript
       - vue
 
-  zova@5.1.132(typescript@5.9.3)(vue@3.5.39(typescript@5.9.3)):
+  zova@5.1.134(typescript@5.9.3)(vue@3.5.39(typescript@5.9.3)):
     dependencies:
       zova-core: 5.1.77(patch_hash=0f4164c4d2bbb16d671beb5c26759dff37769be0709df941bc7b90b94261ac54)(typescript@5.9.3)
-      zova-suite-a-zova: 5.1.131(typescript@5.9.3)(vue@3.5.39(typescript@5.9.3))
+      zova-suite-a-zova: 5.1.133(typescript@5.9.3)(vue@3.5.39(typescript@5.9.3))
     transitivePeerDependencies:
       - '@vue/composition-api'
       - debug