cabloy 5.1.61 → 5.1.62

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

@@ -100,6 +100,9 @@ For the downstream bridge and consumption path, also see:
 A practical split is:
 
 - this page explains backend contract authoring and emission
+- [Backend Contract Emission Specimen](/backend/backend-contract-emission-specimen) explains one concrete emitted action thread
+- [Backend Contract Emission Source Reading Map](/backend/backend-contract-emission-source-reading-map) explains the shortest file-order path through the emission inputs
+- [Backend Contract Emission Output Inspection](/backend/backend-contract-emission-output-inspection) explains how to inspect the emitted output surfaces themselves
 - the fullstack page explains the bridge from emitted OpenAPI to generated frontend SDK
 - the frontend page explains how Zova consumes that contract in its own workflows
 

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

@@ -10,10 +10,10 @@ This is one of the main bridges between synchronous application code and distrib
 
 ## Create a queue
 
-Example: create a queue named `add` in module `demo-student`.
+Example: create a queue named `add` in module `training-student`.
 
 ```bash
-npm run vona :create:bean queue add -- --module=demo-student
+npm run vona :create:bean queue add -- --module=training-student
 ```
 
 ## Queue definition
@@ -197,7 +197,7 @@ Representative pattern:
 ```typescript
 config.onions = {
   queue: {
-    'demo-student:add': {
+    'training-student:add': {
       concurrency: false,
       transaction: false,
       options: {

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

@@ -10,10 +10,10 @@ Vona provides a Redlock-based distributed lock abstraction so that mutual exclus
 
 ## Create a redlock definition
 
-Example: create redlock metadata in module `demo-student`.
+Example: create redlock metadata in module `training-student`.
 
 ```bash
-npm run vona :create:bean meta redlock -- --module=demo-student
+npm run vona :create:bean meta redlock -- --module=training-student
 ```
 
 ## Lock resource types

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

@@ -10,10 +10,10 @@ This matters because recurring work is modeled with the same broader distributed
 
 ## Create a schedule
 
-Example: create a schedule named `log` in module `demo-student`.
+Example: create a schedule named `log` in module `training-student`.
 
 ```bash
-npm run vona :create:bean schedule log -- --module=demo-student
+npm run vona :create:bean schedule log -- --module=training-student
 ```
 
 ## Schedule definition

package/cabloy-docs/backend/scripts.md

@@ -114,3 +114,11 @@ When documenting or automating backend scripts:
 - prefer root scripts for normal contributor workflows
 - drop to `vona/package.json` only when you need backend-specific detail
 - verify commands against current scripts before publishing examples
+
+## Where to read next
+
+If your next question is not only how the monorepo runs backend workflows, but which source surfaces those workflows eventually enter, continue with:
+
+- [Backend CLI](/backend/cli)
+- [Backend Source Reading Roadmap](/backend/backend-source-reading-roadmap)
+- [Vona Source Reading Map](/backend/vona-source-reading-map)

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

@@ -58,7 +58,7 @@ Vona supports custom serializer transforms through `@SerializerTransform(...)`.
 Representative generation workflow:
 
 ```bash
-npm run vona :create:bean serializerTransform upper -- --module=demo-student
+npm run vona :create:bean serializerTransform upper -- --module=training-student
 ```
 
 Representative pattern:
@@ -88,7 +88,7 @@ Field-level serialization is attached through `@Api.field(...)` metadata helpers
 Representative pattern:
 
 ```typescript
-@Api.field(v.serializerTransform('demo-student:upper'))
+@Api.field(v.serializerTransform('training-student:upper'))
 name: string;
 ```
 

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

@@ -10,10 +10,10 @@ In practice, the service guide is also the most useful page for understanding ba
 
 ## Create a service
 
-Example: create a service named `student` in module `demo-student`.
+Example: create a service named `student` in module `training-student`.
 
 ```bash
-npm run vona :create:bean service student -- --module=demo-student
+npm run vona :create:bean service student -- --module=training-student
 ```
 
 ## Service definition
@@ -58,7 +58,7 @@ class ControllerStudent {
 import type { ServiceStudent } from '../service/student.ts';
 
 class ControllerStudent {
-  @Use('demo-student.service.student')
+  @Use('training-student.service.student')
   serviceStudent: ServiceStudent;
 }
 ```
@@ -84,7 +84,7 @@ class ControllerStudent {
 ```typescript
 class ControllerStudent {
   findOne() {
-    return this.$scope.demoStudent.service.student.findOne();
+    return this.$scope.trainingStudent.service.student.findOne();
   }
 }
 ```
@@ -103,19 +103,19 @@ Direct bean access patterns are also available.
 ### Global container access: `_getBean`
 
 ```typescript
-const serviceStudent = this.bean._getBean('demo-student.service.student');
+const serviceStudent = this.bean._getBean('training-student.service.student');
 ```
 
 ### Request-scoped access
 
 ```typescript
-const serviceStudent = this.ctx.bean._getBean('demo-student.service.student');
+const serviceStudent = this.ctx.bean._getBean('training-student.service.student');
 ```
 
 ### Fresh bean creation: `_newBean`
 
 ```typescript
-const serviceStudent = this.bean._newBean('demo-student.service.student');
+const serviceStudent = this.bean._newBean('training-student.service.student');
 ```
 
 A practical split is:
@@ -127,7 +127,7 @@ A practical split is:
 A practical “when to use which” rule is:
 
 - use `this.scope.service.student` when the dependency belongs to the current module and ordinary business code is enough
-- use `this.$scope.demoStudent.service.student` when the dependency clearly belongs to another module
+- use `this.$scope.trainingStudent.service.student` when the dependency clearly belongs to another module
 - use `this.bean._getBean(...)` when you need explicit app-container access by bean identifier
 - use `this.ctx.bean._getBean(...)` when the workflow should resolve through request-scoped access
 - use `this.bean._newBean(...)` when you need a fresh bean instance instead of the ordinary resolved one
@@ -138,7 +138,7 @@ Services are one bean scene inside the larger backend essentials model.
 
 That means service access should be understood together with:
 
-- bean identifiers such as `demo-student.service.student`
+- bean identifiers such as `training-student.service.student`
 - local module scope vs cross-module scope
 - other scope resource categories such as model and entity
 
@@ -166,3 +166,12 @@ A better default is:
 4. choose deliberately among local scope, cross-module scope, injection, and direct bean access
 
 That keeps backend access patterns aligned with Vona’s actual architecture instead of using one access style everywhere by habit.
+
+## Where to read next
+
+If your next question is how service orchestration hands off to the persistence and contract layers in one real module, continue with:
+
+- [Model Guide](/backend/model-guide)
+- [Entity Guide](/backend/entity-guide)
+- [Vona Source Reading Map](/backend/vona-source-reading-map)
+- [Backend Resource/Module Contract Chain](/backend/backend-resource-module-contract-chain)

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

@@ -42,10 +42,10 @@ This is one of the reasons backend startup belongs in the backend docs, not in t
 
 ## Create a startup bean
 
-Example: create a startup named `log` in module `demo-student`.
+Example: create a startup named `log` in module `training-student`.
 
 ```bash
-npm run vona :create:bean startup log -- --module=demo-student
+npm run vona :create:bean startup log -- --module=training-student
 ```
 
 Representative shape:
@@ -102,7 +102,7 @@ Representative pattern:
 ```typescript
 config.onions = {
   startup: {
-    'demo-student:log': {
+    'training-student:log': {
       after: false,
       debounce: true,
       instance: false,
@@ -148,7 +148,7 @@ App config can disable a startup explicitly:
 ```typescript
 config.onions = {
   startup: {
-    'demo-student:log': {
+    'training-student:log': {
       enable: false,
     },
   },
@@ -200,7 +200,7 @@ Module monkey files can also receive module-oriented hook callbacks, and the app
 Representative CLI workflow:
 
 ```bash
-npm run vona :init:monkey demo-student
+npm run vona :init:monkey training-student
 ```
 
 ### Startup beans

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

@@ -27,7 +27,7 @@ A practical mental model is:
 Create a status bean in your module with the shared Vona CLI entrypoint:
 
 ```bash
-npm run vona :create:bean meta status -- --module=demo-student
+npm run vona :create:bean meta status -- --module=training-student
 ```
 
 This follows the same `:create:bean` workflow used by other backend bean scenes and metadata beans.
@@ -112,11 +112,11 @@ The stored payload is:
 
 So a practical storage reading is:
 
-| Field    | Meaning                                 |
-| -------- | --------------------------------------- |
-| `module` | the owning backend module               |
-| `name`   | the status key inside that module       |
-| `value`  | the persisted JSON value for that key   |
+| Field    | Meaning                               |
+| -------- | ------------------------------------- |
+| `module` | the owning backend module             |
+| `name`   | the status key inside that module     |
+| `value`  | the persisted JSON value for that key |
 
 The current migration creates the table with the framework basic fields plus:
 
@@ -134,7 +134,7 @@ That means two different modules can both use a key such as `enable` without col
 
 A practical reading is:
 
-- `demo-student + enable` is one status record
+- `training-student + enable` is one status record
 - `demo-course + enable` is a different status record
 
 This makes Status a natural fit for module-local state.

package/cabloy-docs/backend/unit-testing.md

@@ -33,7 +33,7 @@ This is why Vona testing should not be reduced to isolated helper-unit testing o
 Example:
 
 ```bash
-npm run vona :create:test student -- --module=demo-student
+npm run vona :create:test student -- --module=training-student
 ```
 
 ## Execute tests
@@ -91,7 +91,7 @@ Locale-sensitive variants and additional request-context helpers are also availa
 Representative pattern:
 
 ```typescript
-const scopeStudent = app.scope('demo-student');
+const scopeStudent = app.scope('training-student');
 ```
 
 This lets tests exercise:
@@ -108,7 +108,7 @@ through the same scoped abstractions used in application code.
 Representative pattern:
 
 ```typescript
-await app.bean.executor.performAction('get', '/demo/student');
+await app.bean.executor.performAction('get', '/training/student');
 ```
 
 This is especially useful because it exercises the controller path more realistically than only unit-testing isolated helper functions.

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