cabloy 5.1.60 → 5.1.62

package/cabloy-docs/backend/vona-source-reading-map.md

@@ -0,0 +1,157 @@
+# Vona Source Reading Map
+
+This page is a practical map for contributors and AI workflows that need to read Vona backend source code efficiently.
+
+It does not try to teach every backend subsystem from scratch. Instead, it answers a narrower question:
+
+> when I need to understand one kind of Vona backend behavior, which files should I read first, and in what order?
+
+Use this page together with:
+
+- [Backend Source Reading Roadmap](/backend/backend-source-reading-roadmap)
+- [Backend (Vona)](/backend/introduction)
+- [Backend Foundation](/backend/foundation)
+- [Backend CLI](/backend/cli)
+- [Backend Scripts](/backend/scripts)
+- [Controller Guide](/backend/controller-guide)
+- [Service Guide](/backend/service-guide)
+- [Model Guide](/backend/model-guide)
+- [Entity Guide](/backend/entity-guide)
+- [Backend Directory Structure](/reference/backend-directory-structure)
+
+## Why this page exists
+
+In a framework-sized backend codebase, source reading usually becomes slow for one reason:
+
+- you can already find _a_ relevant file
+- but you do not yet know the shortest path to the _next_ file
+
+Vona especially benefits from a reading map because several layers cooperate at once:
+
+- root scripts and CLI wrappers
+- generated metadata surfaces
+- controller / service / model / entity layering
+- module and suite boundaries
+- project-level backend hooks such as play or build helpers
+
+This page gives a compact starting sequence for each common backend topic so readers can move from concept guide to source path without drifting.
+
+## How to use this page
+
+For each topic below:
+
+1. start with the concept guide to refresh the architectural intent
+2. read the first source file to identify the public entry surface
+3. continue into the next runtime file only if you still need the implementation detail
+4. stop as soon as you have enough information for the task
+
+The goal is not to read the entire backend tree every time. The goal is to choose the shortest accurate path.
+
+## 1. CLI and backend startup entry path
+
+Use this path when you are asking questions like:
+
+- where does backend execution enter from the repo root?
+- how does `npm run vona` reach the Vona CLI?
+- where does `play` diverge from normal CLI startup?
+- where does the backend build or verification hook surface begin?
+
+### Read the docs first
+
+- [Backend CLI](/backend/cli)
+- [Backend Scripts](/backend/scripts)
+- [Backend (Vona)](/backend/introduction)
+- [Backend Directory Structure](/reference/backend-directory-structure)
+
+### Then read source in this order
+
+1. `package.json`
+2. `vona/packages-cli/cli/src/bin/vona.ts`
+3. `vona/packages-cli/cli/src/start.ts`
+4. `vona/src/backend/cli.ts`
+5. `vona/src/backend/play/index.ts`
+
+### What each file clarifies
+
+- `package.json` shows the root `vona` script and the shared monorepo workflow entrypoint
+- `vona.ts` shows how raw CLI argv is normalized, how `play` is treated specially, and where normal execution hands off to `VonaCommand`
+- `start.ts` shows the CLI bootstrap class itself
+- `src/backend/cli.ts` shows the project-level backend build hook surface
+- `src/backend/play/index.ts` shows the backend playground-oriented verification entrypoint through `mockCtx(...)`
+
+## 2. Representative backend resource and module CRUD path
+
+Use this path when you are asking questions like:
+
+- how is one backend module wired end-to-end?
+- where do controller, service, model, and entity responsibilities separate?
+- where do generated metadata and API path registrations live?
+
+### Read the docs first
+
+- [Controller Guide](/backend/controller-guide)
+- [Service Guide](/backend/service-guide)
+- [Model Guide](/backend/model-guide)
+- [Entity Guide](/backend/entity-guide)
+- [Backend Directory Structure](/reference/backend-directory-structure)
+
+### Then read source in this order
+
+1. `vona/src/suite/a-training/modules/training-student/src/index.ts`
+2. `vona/src/suite/a-training/modules/training-student/src/.metadata/index.ts`
+3. `vona/src/suite/a-training/modules/training-student/src/controller/student.ts`
+4. `vona/src/suite/a-training/modules/training-student/src/service/student.ts`
+5. `vona/src/suite/a-training/modules/training-student/src/model/student.ts`
+6. `vona/src/suite/a-training/modules/training-student/src/entity/student.tsx`
+
+### What each file clarifies
+
+- `index.ts` shows the module export surface and tells you that generated metadata is part of the public reading path
+- `.metadata/index.ts` shows the generated registration surface for entity, model, service, controller, DTO, API path, and scope wiring
+- `controller/student.ts` shows the resource-facing HTTP layer through `@Controller('student')`, `@Resource()`, and CRUD methods delegating to `this.scope.service.student`
+- `service/student.ts` shows the orchestration layer delegating to `this.scope.model.student`
+- `model/student.ts` shows the compact model binding from `@Model(...)` to `EntityStudent`
+- `entity/student.tsx` shows the entity fields plus OpenAPI and Zova render metadata that drive the broader contract loop
+
+### When to continue into DTOs
+
+If your next question becomes one of these:
+
+- what is the request/response DTO shape for this resource?
+- where do the select/view/create/update transport contracts live?
+
+then continue into the module DTO files referenced from `.metadata/index.ts`.
+
+If your next question is instead about generated registration, onion names, or API path typing, return to `.metadata/index.ts` before reading deeper.
+
+If the next question becomes specifically about explicit DTOs, inferred DTO helpers, or how DTO choices surface in generated metadata, continue with [DTO Infer and Generation](/backend/dto-infer-generation).
+
+If the next question becomes specifically about how those controller, DTO, and entity surfaces become emitted backend contract, continue with [Backend Contract Emission Source Reading Map](/backend/backend-contract-emission-source-reading-map).
+
+## 3. A compact reading strategy
+
+When in doubt, use this order:
+
+1. read the concept guide first
+2. open the smallest source entrypoint that matches your question
+3. read the generated metadata surface early when the topic spans multiple backend layers
+4. only then descend into controller, service, model, or entity details
+
+That order usually gets you to the answer faster than starting from the deepest backend runtime file first.
+
+## Where to read next
+
+- If you now want a proof-oriented layer-by-layer backend validation workflow, continue with [Backend Source Reading Verify Playbook](/backend/backend-source-reading-verify-playbook).
+- If something already looks wrong and you want symptom-first diagnosis, continue with [Backend Source Reading Debug Checklist](/backend/backend-source-reading-debug-checklist).
+
+## Final takeaway
+
+The fastest way to read Vona accurately is not to memorize every file under `vona/`.
+
+It is to recognize which question you are asking first:
+
+- CLI and startup entry question
+- resource and module wiring question
+- DTO and generated-metadata question
+
+Then start from the smallest public source surface that matches that question and only descend into deeper files as needed.

package/cabloy-docs/backend/websocket-protocol-guide.md

@@ -59,7 +59,7 @@ _:[eventNameOrShortCode, data]
 More precisely, the server sends:
 
 ```typescript
-`${eventPrefix}${JSON.stringify([eventNameInner, data])}`
+`${eventPrefix}${JSON.stringify([eventNameInner, data])}`;
 ```
 
 That means the Web Socket protocol is event-oriented rather than frame-schema-oriented.
@@ -71,7 +71,7 @@ The event prefix comes from module config:
 ```typescript
 return {
   eventPrefix: '_:',
-}
+};
 ```
 
 A practical interpretation is:
@@ -200,7 +200,7 @@ Representative logical payload:
 {
   "i": 1,
   "m": "get",
-  "p": "/demo/student/findOne",
+  "p": "/training/student/findOne",
   "q": { "id": 3 },
   "h": { "x-demo": "1" }
 }
@@ -209,7 +209,7 @@ Representative logical payload:
 Representative wire packet:
 
 ```text
-_:["_b",{"i":1,"m":"get","p":"/demo/student/findOne","q":{"id":3},"h":{"x-demo":"1"}}]
+_:["_b",{"i":1,"m":"get","p":"/training/student/findOne","q":{"id":3},"h":{"x-demo":"1"}}]
 ```
 
 ## `sysReady`
@@ -378,4 +378,4 @@ Use the practical split:
 - [Web Socket Guide](/backend/websocket-guide) for architecture
 - [Web Socket Usage Guide](/backend/websocket-usage-guide) for server-side authoring patterns
 - [Web Socket Call Flow](/backend/websocket-call-flow) for source tracing
-- this page for client-visible wire format and built-in protocol fields
+- this page for client-visible wire format and built-in protocol fields

package/cabloy-docs/backend/websocket-usage-guide.md

@@ -54,7 +54,7 @@ Use the Vona CLI to create a namespace bean shell.
 Example:
 
 ```bash
-npm run vona :create:bean socketNamespace chat -- --module=demo-student
+npm run vona :create:bean socketNamespace chat -- --module=training-student
 ```
 
 The generated shape follows the `a-socket` boilerplate pattern.
@@ -83,8 +83,7 @@ export interface ISocketNamespaceOptionsChatEvents {
   };
 }
 
-export interface ISocketNamespaceOptionsChat
-  extends IDecoratorSocketNamespaceOptions<ISocketNamespaceOptionsChatEvents> {}
+export interface ISocketNamespaceOptionsChat extends IDecoratorSocketNamespaceOptions<ISocketNamespaceOptionsChatEvents> {}
 
 @SocketNamespace<ISocketNamespaceOptionsChat>({
   namespace: '/chat',
@@ -231,14 +230,17 @@ If the behavior belongs to connect or disconnect time, create a `socketConnectio
 Example:
 
 ```bash
-npm run vona :create:bean socketConnection audit -- --module=demo-student
+npm run vona :create:bean socketConnection audit -- --module=training-student
 ```
 
 Representative generated shape:
 
 ```typescript
 import type { Next } from 'vona';
-import type { IDecoratorSocketConnectionOptions, ISocketConnectionExecute } from 'vona-module-a-socket';
+import type {
+  IDecoratorSocketConnectionOptions,
+  ISocketConnectionExecute,
+} from 'vona-module-a-socket';
 import type { WebSocket } from 'ws';
 import { BeanBase } from 'vona';
 import { SocketConnection } from 'vona-module-a-socket';
@@ -273,7 +275,7 @@ If the behavior belongs to inbound socket messages, create a `socketPacket` bean
 Example:
 
 ```bash
-npm run vona :create:bean socketPacket chat -- --module=demo-student
+npm run vona :create:bean socketPacket chat -- --module=training-student
 ```
 
 Representative generated shape:
@@ -289,7 +291,12 @@ export interface ISocketPacketOptionsChat extends IDecoratorSocketPacketOptions
 
 @SocketPacket<ISocketPacketOptionsChat>()
 export class SocketPacketChat extends BeanBase implements ISocketPacketExecute {
-  async execute(_data: any, _ws: WebSocket, _options: ISocketPacketOptionsChat, next: Next): Promise<void> {
+  async execute(
+    _data: any,
+    _ws: WebSocket,
+    _options: ISocketPacketOptionsChat,
+    next: Next,
+  ): Promise<void> {
     return next();
   }
 }
@@ -353,4 +360,4 @@ If you need the broader context next, read:
 
 - [Web Socket Guide](/backend/websocket-guide) for architecture
 - [Web Socket Protocol Guide](/backend/websocket-protocol-guide) for the client-visible wire format
-- [Web Socket Call Flow](/backend/websocket-call-flow) for source tracing and debugging
+- [Web Socket Call Flow](/backend/websocket-call-flow) for source tracing and debugging

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

@@ -0,0 +1,281 @@
+# Model Runtime Under the Hood
+
+This guide explains the lower-level runtime of `a-model` in Zova through the current public Cabloy Basic source.
+
+Use this page when you want to understand:
+
+- how the model module bootstraps its shared query infrastructure
+- how `$queryClient` becomes available on beans
+- how the model inheritance stack is assembled
+- how query keys are prefixed and normalized
+- how `useQuery`, state helpers, and persister behavior fit together
+- how SSR dehydrate/hydrate and stale-time rules participate in the model runtime
+
+## Why this page exists
+
+Several existing docs already explain the role and usage of models well:
+
+- [Model Architecture](/frontend/model-architecture)
+- [Model State Guide](/frontend/model-state-guide)
+- [Model Resource Owner Pattern](/frontend/model-resource-owner-pattern)
+- [ModelResource Internals Deep Dive](/frontend/model-resource-internals-deep-dive)
+
+What those pages do not isolate directly is the lower-level generic `a-model` runtime chain.
+
+That is the gap this page fills.
+
+## The shortest accurate mental model
+
+A practical mental model is:
+
+1. `@Model()` registers a model bean on the model scene
+2. the `a-model` module monkey bootstraps a shared `QueryClient`
+3. the monkey injects `$queryClient` onto bean instances
+4. `BeanModelBase` is the public entry into a deeper inheritance stack for query, mutation, state, and persistence behavior
+5. all model query/state operations prefix keys by model identity, and selector-enabled models add selector identity too
+6. `useQuery`, state helpers, and persister behavior cooperate to apply SSR-aware stale/hydration/persistence rules
+
+That means the model layer is not only a set of convenience helpers. It is a lower-level shared query/persistence runtime for the frontend.
+
+## Source-confirmed reading path
+
+When reading this topic, use this order:
+
+1. `zova/src/suite-vendor/a-zova/modules/a-model/src/monkey.ts`
+2. `zova/src/suite-vendor/a-zova/modules/a-model/src/service/storage.ts`
+3. `zova/src/suite-vendor/a-zova/modules/a-model/src/bean/bean.modelBase.ts`
+4. `zova/src/suite-vendor/a-zova/modules/a-model/src/bean/bean.model/bean.model.last.ts`
+5. `zova/src/suite-vendor/a-zova/modules/a-model/src/bean/bean.model/bean.model.query.ts`
+6. `zova/src/suite-vendor/a-zova/modules/a-model/src/bean/bean.model/bean.model.useQuery.ts`
+7. `zova/src/suite-vendor/a-zova/modules/a-model/src/bean/bean.model/bean.model.useState.ts`
+8. `zova/src/suite-vendor/a-zova/modules/a-model/src/bean/bean.model/bean.model.persister.ts`
+9. `zova/src/suite-vendor/a-zova/modules/a-model/src/config/config.ts`
+
+That order moves from module bootstrapping, to shared query storage, to the public model bean entry, then into identity, query, useQuery, state, persister, and finally default config behavior.
+
+## monkey/bootstrap and `QueryClient` wiring
+
+The module monkey lives in:
+
+```text
+zova/src/suite-vendor/a-zova/modules/a-model/src/monkey.ts
+```
+
+The source confirms that:
+
+- `appInitialize()` creates/initializes shared storage
+- `moduleLoaded()` lets the storage service finish module-level setup
+- `beanInit(...)` defines `$queryClient` on beans
+- `$queryClient` is resolved through `useQueryClient()` and marked raw
+
+This is the first important lower-level rule:
+
+- the model runtime is bootstrapped at module/app level before higher model helpers are used
+
+## `ServiceStorage` and shared query lifecycle
+
+The shared query-storage/runtime owner lives in:
+
+```text
+zova/src/suite-vendor/a-zova/modules/a-model/src/service/storage.ts
+```
+
+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
+
+This is the second important lower-level rule:
+
+- the model runtime is not only about per-model helper methods
+- it also owns one shared query lifecycle around SSR and client hydration
+
+## The public model bean entry and inheritance stack
+
+The public bean entry lives in:
+
+```text
+zova/src/suite-vendor/a-zova/modules/a-model/src/bean/bean.modelBase.ts
+```
+
+It is intentionally thin:
+
+- `BeanModelBase extends BeanModelFirst`
+
+A key lower-level identity layer appears in:
+
+```text
+zova/src/suite-vendor/a-zova/modules/a-model/src/bean/bean.model/bean.model.last.ts
+```
+
+This file confirms that:
+
+- selector identity is stored on the model when `enableSelector` is on
+- `self` and `scopeSelf` provide access to the effective model bean/runtime scope
+
+This is the rule to keep in mind when reading the rest of the runtime:
+
+- `BeanModelBase` is the public entry
+- the lower-level behavior is assembled through the internal inheritance chain beneath it
+
+## Query-key prefixing and normalization
+
+The core query identity logic lives in:
+
+```text
+zova/src/suite-vendor/a-zova/modules/a-model/src/bean/bean.model/bean.model.query.ts
+```
+
+The most important lower-level rule is `_forceQueryKeyPrefix(...)`.
+
+The source confirms that query keys are prefixed with:
+
+- bean full name
+- selector, when selector mode is enabled
+
+This matters because model query identity is not only whatever the caller typed in `queryKey`.
+
+The model runtime namespaces the key automatically.
+
+This same layer also owns:
+
+- `$setQueryData(...)`
+- `$invalidateQueries(...)`
+- `$refetchQueries(...)`
+- `$queryFind(...)`
+- filter normalization through `$normalizeFilters(...)`
+
+That means key prefixing and invalidation are part of the same lower-level runtime layer.
+
+## `useQuery` runtime behavior
+
+The query wrapper lives in:
+
+```text
+zova/src/suite-vendor/a-zova/modules/a-model/src/bean/bean.model/bean.model.useQuery.ts
+```
+
+The source confirms that `useQuery` behavior is not passed through untouched.
+
+It adds:
+
+- prefixed query keys
+- persister integration
+- default error handling
+- SSR-aware stale-time branching
+
+The important SSR-aware rule is:
+
+- async queries use configured async stale time by default
+- during client SSR pre-hydration, cached SSR data can switch to SSR stale-time behavior
+
+That means stale-time behavior is part of the model runtime contract, not only a local query option.
+
+## State helper families as one runtime family
+
+The state helper layer lives mainly in:
+
+```text
+zova/src/suite-vendor/a-zova/modules/a-model/src/bean/bean.model/bean.model.useState.ts
+```
+
+This is where the five main state families are exposed:
+
+- `data`
+- `mem`
+- `local`
+- `cookie`
+- `db`
+
+The important lower-level point is that these are not unrelated helpers.
+
+They are one model-owned runtime family built on shared query/persistence identity.
+
+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
+
+## Persister storage selection and restore/save/remove behavior
+
+The persister layer lives in:
+
+```text
+zova/src/suite-vendor/a-zova/modules/a-model/src/bean/bean.model/bean.model.persister.ts
+```
+
+Its main jobs are:
+
+- choose the storage backend
+- compute storage key and prefix
+- apply `buster`
+- apply `maxAge`
+- restore persisted state
+- save persisted state
+- remove persisted state
+- prefix persisted query identity consistently with the model/query runtime
+
+The storage options include:
+
+- cookie
+- local
+- db
+
+This is the clearest lower-level source for understanding why model persistence behavior differs by state family and why restored state still respects model identity.
+
+## Default config behavior
+
+The default model-runtime config lives in:
+
+```text
+zova/src/suite-vendor/a-zova/modules/a-model/src/config/config.ts
+```
+
+This file confirms default behavior such as:
+
+- query retry/refetch defaults
+- async stale time
+- SSR stale time
+- 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.
+
+## What this page does not re-explain
+
+This page does **not** fully re-explain:
+
+- the architectural role of Model -> see [Model Architecture](/frontend/model-architecture)
+- the public helper-family usage -> see [Model State Guide](/frontend/model-state-guide)
+- the resource-owner pattern -> see [Model Resource Owner Pattern](/frontend/model-resource-owner-pattern)
+- the resource-owner internals -> see [ModelResource Internals Deep Dive](/frontend/model-resource-internals-deep-dive)
+
+Its job is only to explain the lower-level generic `a-model` runtime.
+
+## Where to read next
+
+Use these next steps depending on your question:
+
+- if you want the architectural role of Model, read [Model Architecture](/frontend/model-architecture)
+- if you want state helper usage, read [Model State Guide](/frontend/model-state-guide)
+- if you want resource-owner patterns built on this runtime, read [Model Resource Owner Pattern](/frontend/model-resource-owner-pattern)
+- if you want the resource-owner itself, read [ModelResource Internals Deep Dive](/frontend/model-resource-internals-deep-dive)
+- if you want the lower OpenAPI/schema substrate beneath some model behavior, read [A-OpenAPI Under the Hood](/frontend/a-openapi-under-the-hood)
+
+## Final takeaway
+
+The most accurate way to read `a-model` is not as one set of convenience wrappers around TanStack Query.
+
+Read it as the lower-level frontend model runtime that:
+
+- bootstraps a shared query client
+- injects query access into beans
+- composes model identity and selector-aware query-key namespacing
+- applies persistence and SSR-aware hydration/stale behavior
+- supports higher-level model and resource-owner patterns on top of that lower runtime
+
+That is the source-confirmed role of `a-model` in the current Cabloy Basic frontend architecture.