cabloy 5.1.149 → 5.1.150

package/.cabloy-version

@@ -1 +1 @@
-5.1.149
+5.1.150

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

@@ -18,7 +18,8 @@ After generating or extending a backend thread, check which follow-up layers app
 - treat the top-level `$Dto.create(...)` / `$Dto.update(...)` default omissions as a write-input authorization boundary, not as a reason to mechanically narrow ordinary `$Dto.get(...)` contracts
 - when a narrowed DTO or OpenAPI schema is expected to remove physical response fields, separately shape and verify the action response; declaration narrowing alone does not guarantee runtime field stripping
 - when stable Entity, Model, relation, or query truth exists, define the DTO projection first with `$Dto.*` and, where needed, `columns`, `include`, or `dtoClass`
-- for an inferred field, use `$makeMetadata(...)` for metadata-only refinement and `$makeSchema(...)` for schema or validation refinement; use a class-body `@Api.field(...)` member only for a genuinely new field
+- for an inferred/projected field, use `$makeMetadata(...)` for metadata-only refinement and `$makeSchema(...)` for schema or validation refinement; use a class-body `@Api.field(...)` member only for a genuinely new declared field
+- before using `$makeMetadata(...)`, confirm the `fields` key already has an inferred/projected schema; a true virtual key added only through `@Dto({ fields })` must use `$makeSchema(...)` with a final concrete `z.<type>()` schema, because `fieldSource(...)` maps a source path but supplies no missing type; see [Virtual fields in the DTO fields map](../../../../repo-docs/backend/dto-infer-generation.md#virtual-fields-in-the-dto-fields-map)
 - when inference cannot express the contract clearly, choose an explicit DTO deliberately; see [Default-first three-layer DTO authoring](../../../../repo-docs/backend/dto-infer-generation.md#default-first-three-layer-dto-authoring)
 - frontend contract impact
 - `@Api.field(...)` / `$makeSchema(...)` ordering: framework guards now preserve previously attached OpenAPI metadata across schema rebuilds, but structure-shaping schemaLike is still order-sensitive

package/.claude/skills/cabloy-frontend-scaffold/SKILL.md

@@ -180,6 +180,7 @@ Check whether the feature needs:
 - schema-driven UI or `$apiSchema` review
 - SSR hydration-equivalence review: classify state as SSR-required or intentionally deferred; keep server HTML and the hydration-time client render equivalent; defer private, cookie-unavailable, or browser-only query/load/render branches to an explicit post-hydration, admission, mounted, or interaction boundary
 - distinguish `$useStateData(...)` query ownership from readiness waits: `disableSuspenseOnInit` only skips its init-time suspense kick and does not prevent query creation or fetches; choose `$QueryEnsureLoaded(...)` or freshness helpers only at the later boundary that needs them
+- verify that render-driving UI reads model/query-owned reactive state (`query.data` or a model-derived surface); keep awaited `refetch()` results local to one-shot interaction/orchestration and never as a parallel ongoing controller/render state copy
 - reverse fullstack handoff when newly added frontend resources will later be consumed by backend metadata or backend tooling
 
 If the frontend change introduces resources such as a custom form-field renderer, table-cell renderer, or other generated metadata that backend `ZovaRender.field(...)` / `ZovaRender.cell(...)` will consume, do not treat the task as frontend-only cleanup.

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 5.1.150
+
+### Features
+
+- Add `bypassPersister` support.
+- Update query functionality.
+- Add runbook updates.
+- Add schema alias support.
+- Add SKU stock availability support.
+- Update related functionality and resources.
+
+### Bug Fixes
+
+- Fix end-to-end tests.
+- Correct `bypassPersister` behavior.
+- Update schema tests.
+
+### Improvements
+
+- Refactor the student model and service.
+- Improve documentation for `bypassPersister`.
+
 ## 5.1.149
 
 ### Features

package/CLAUDE.md

@@ -65,6 +65,7 @@ Before inventing a custom implementation path:
 - In Zova page routes, any route with dynamic `params` must define `route.name`; do not rely on unnamed path-keyed routes for typed `$params`. Static routes should omit `route.name` unless a documented named-route requirement exists; use `$router.getPagePath(...)` for canonical static URL generation rather than adding a name or alias for convenience. Ordinary business routes without `locale` params should omit app-config aliases unless a documented system, compatibility, or user-facing URL exception requires one. Choose `ssrProfile` from the page's rendering contract: Web remains `public` by default, while `session` is an explicit choice for cookie-backed state, protected admission, personalized first paint, or private SSR data; the absence of a locale parameter alone does not select a profile. `requiresAuth` is independent, so anonymous routes must explicitly use `requiresAuth: false`. Regenerate page metadata after route changes.
 - For frontend async state that affects rendering or interaction across consumers, prefer model-owned `$useStateData(...)` over controller-managed fetch/cache state.
 - Default to establishing such query state during render. Use `disableSuspenseOnInit: true` only for relatively stable query-backed state when you want to skip the init-time `query.suspense()` kick; it does not prevent query creation, fetches, or hydration-time rendering. If strict readiness is needed later, wait explicitly at the interaction boundary.
+- For render-driving async state, read the current query-owned reactive surface (`query.data` or a model-derived projection); an awaited `query.refetch()` result is valid only for one-shot interaction or orchestration and must not become a parallel ongoing controller/render state owner.
 - In SSR, keep server HTML and the client's hydration-time initial render equivalent. When server rendering intentionally omits private, cookie-unavailable, or browser-only state, keep the same neutral shell or placeholder through hydration and defer its query/load/render branch to an explicit post-hydration, admission, mounted, or interaction boundary.
 - Keep repo-wide AI rules in `CLAUDE.md` short and durable; put branching Zova analysis workflows in `.claude/skills/`.
 - Do not modify shared environment identity or ports merely to bypass a busy resource. For intentional parallel worktree setup, follow `repo-docs/fullstack/parallel-worktree-environment.md`; otherwise wait for the shared resource or ask the user. Create or change worktree-local environment overrides only through the explicitly invoked `cabloy-worktree-environment` skill and its confirmation phase, and only in `vona/env/.env.local` and `zova/env/.env.local`; never modify flavor-, mode-, app-mode-, or runtime-specific `.env.*.local` files. The skill derives the standard `APP_NAME`, `SERVER_LISTEN_PORT`, `DEV_SERVER_PORT`, `DEV_SERVER_HMR_PORT`, and API-derived `API_BASE_URL` tuple only from Git worktree metadata and fixed port baselines; never read or expose `.env*` content while recommending values. Admin and Web are alternative commands using this shared tuple and must not run concurrently in one worktree; use another linked worktree for concurrent use. Detect the active edition before choosing scripts, and never run `npm run init` as an automatic follow-up.

package/package.json

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

package/repo-docs/backend/dto-guide.md

@@ -183,7 +183,7 @@ A practical split is:
 - use inferred DTOs when the contract closely follows model structure or query shape
 - wrap inferred DTOs in a named DTO class when reuse or discoverability becomes more important
 
-When stable Entity, Model, relation, or query truth already exists, prefer inference first: use `$Dto.*` with `columns`, `include`, or `dtoClass` to define the projection; use `@Dto({ fields })` with `$makeMetadata(...)` for metadata-only differences or `$makeSchema(...)` for schema and validation differences; add an `@Api.field(...)` member only for a genuinely new field absent from the inferred contract. Keep an explicit DTO as a deliberate fallback when no suitable upstream truth exists or the inferred composition is less clear.
+When stable Entity, Model, relation, or query truth already exists, prefer inference first: use `$Dto.*` with `columns`, `include`, or `dtoClass` to define the projection; use `@Dto({ fields })` with `$makeMetadata(...)` only for metadata-only differences on an existing inferred/projected field, or `$makeSchema(...)` for schema and validation differences. A true virtual `fields` key absent from that projection must use `$makeSchema(...)` with a final concrete `z.<type>()` schema; `fieldSource(...)` maps its binding but supplies no type. Add an `@Api.field(...)` member only for a genuinely new declared DTO property. See [Virtual fields in the DTO fields map](/backend/dto-infer-generation#virtual-fields-in-the-dto-fields-map) for the full decision rule. Keep an explicit DTO as a deliberate fallback when no suitable upstream truth exists or the inferred composition is less clear.
 
 Advanced inferred DTO shaping can also stay named and reusable through helper options such as `dtoClass`, especially for relation-aware contracts and nested DTO surfaces. `$Dto.get(...)` otherwise keeps the complete model-aware read shape by default; use `columns` or `dtoClass` for a genuine business projection, not merely to remove `iid` or `deleted`. For the canonical authoring sequence, see [Default-first three-layer DTO authoring](/backend/dto-infer-generation#default-first-three-layer-dto-authoring) and [Default read shape versus a public projection](/backend/dto-infer-generation#default-read-shape-versus-a-public-projection).
 
@@ -205,11 +205,12 @@ When creating DTOs:
 
 1. check whether an Entity, Model, relation, or query shape already provides suitable upstream contract truth
 2. define the inferred projection before redeclaring fields: choose the `$Dto.*` helper and, where needed, `columns`, `include`, or `dtoClass`
-3. use `$makeMetadata(...)` for metadata-only refinement and `$makeSchema(...)` for schema or validation refinement of an inferred field
-4. use `@Api.field(...)` for a genuinely new field, not as a second declaration of an inferred field
-5. keep DTO validation and OpenAPI concerns aligned, and keep the final structure-defining schema last when using schema-like composition
-6. decide whether the contract should remain inferred, be wrapped in a named inferred DTO, or deliberately fall back to an explicit DTO
-7. treat DTO design as part of the contract between backend handlers, models, and frontend integration
+3. use `$makeMetadata(...)` for metadata-only refinement and `$makeSchema(...)` for schema or validation refinement of an inferred/projected field
+4. for a true virtual key added only through `@Dto({ fields })`, use `$makeSchema(...)` with a final concrete `z.<type>()` schema; `fieldSource(...)` supplies no missing type
+5. use `@Api.field(...)` for a genuinely new declared DTO property, not as a second declaration of an inferred field
+6. keep DTO validation and OpenAPI concerns aligned, and keep the final structure-defining schema last when using schema-like composition
+7. decide whether the contract should remain inferred, be wrapped in a named inferred DTO, or deliberately fall back to an explicit DTO
+8. treat DTO design as part of the contract between backend handlers, models, and frontend integration
 
 ## Where to read next
 

package/repo-docs/backend/dto-infer-generation.md

@@ -193,6 +193,25 @@ export class DtoStudentSelectReq extends $Dto.queryPage(EntityStudent, [
 
 Framework DTO composition preserves inherited OpenAPI metadata when a field schema is refined. That includes metadata such as titles, render information, and scene identity. It does **not** make structure-shaping schema-like arguments order-independent: keep the final structure-defining argument last and verify the effective schema rather than assuming a metadata merge can repair a reordered schema.
 
+#### Virtual fields in the DTO fields map
+
+The Layer 2 `$makeMetadata(...)` rule has a precondition: the field key must already be supplied by the inferred projection, whether through the `$Dto.*` base, `columns`, `include`, or `dtoClass`. It overlays metadata on that existing runtime schema.
+
+A **true virtual DTO field** is a key added only through `@Dto({ fields })` and absent from that inherited projection. Define such a key with `$makeSchema(...)` and a final concrete Zod schema, even when its purpose is only to map a renderer to a nested source:
+
+```typescript
+const descriptionMarkdownField = $makeSchema(
+  ZovaRender.fieldSource('content.descriptionMarkdown'),
+  ZovaRender.field('basic-markdown:formFieldMarkdown'),
+  v.optional(),
+  z.string(),
+);
+```
+
+`z.string()` establishes the virtual key's validation and emitted OpenAPI type. `fieldSource(...)` only maps the DTO-facing key to the canonical source path used by downstream schema-driven UI; it does not supply a type. `$makeMetadata(...)` alone has no inherited schema to overlay for a true virtual key, so its metadata is attached to an unconstrained fallback rather than a meaningful field schema.
+
+Use a class-body `@Api.field(...)` member instead when the new field should be a declared, statically typed DTO property rather than a contract-only `fields`-map key.
+
 `@Dto({ fields })` changes the runtime contract and metadata. It does not rewrite the TypeScript property type inferred from the `$Dto.*` base class. Do not add a duplicate `declare` field or a second field decorator solely to mirror a runtime schema restriction unless a separate static contract is genuinely required and is type-compatible with the inferred base.
 
 ### Layer 3: add contract-only fields
@@ -507,10 +526,11 @@ When evaluating a return shape or input contract that closely follows model stru
 2. is the contract get/list/query/create/update/aggregate/group oriented, and which `$Dto.*` helper matches it?
 3. should `columns`, `include`, `with`, or `dtoClass` define the projection boundary?
 4. should the inferred DTO stay inline or be wrapped in a named DTO class?
-5. for every local difference, is it metadata-only (`$makeMetadata(...)`) or schema-affecting (`$makeSchema(...)`)?
-6. is every `@Api.field(...)` member genuinely new instead of a redeclared inferred field?
-7. if `$makeSchema(...)` is used, is the structure-defining schema last and is emitted schema/OpenAPI verification planned?
-8. does the resulting DTO also affect OpenAPI and frontend generation paths?
-9. is CRUD generation already giving enough contract structure that another handwritten DTO would be redundant, or is an explicit DTO clearer?
+5. for every local difference, does the `fields` key already have an inferred/projected schema, or is it a true virtual key?
+6. use `$makeMetadata(...)` only for metadata-only refinement of an inferred/projected field; define every true virtual key with `$makeSchema(...)` and a final concrete `z.<type>()` schema
+7. is every `@Api.field(...)` member genuinely new instead of a redeclared inferred field?
+8. if `$makeSchema(...)` is used, is the structure-defining schema last and is emitted schema/OpenAPI verification planned?
+9. does the resulting DTO also affect OpenAPI and frontend generation paths?
+10. is CRUD generation already giving enough contract structure that another handwritten DTO would be redundant, or is an explicit DTO clearer?
 
 That helps reduce redundant type work and keeps contracts closer to the model truth.

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

@@ -187,6 +187,44 @@ The important SSR-aware rule is:
 
 That means stale-time behavior is part of the model runtime contract, not only a local query option.
 
+### Per-fetch persistence bypass
+
+The returned query's `refetch()` is extended by the model runtime with an opt-in per-fetch persistence bypass:
+
+```ts
+await query.refetch({ bypassPersister: true });
+```
+
+The source-level execution path is:
+
+```text
+query.refetch({ bypassPersister: true })
+  -> BeanModelUseQuery refetch wrapper
+  -> remove bypassPersister from the public options
+  -> attach a per-fetch internal marker
+  -> TanStack Query fetch
+  -> BeanModelPersister wrapper
+  -> call queryFn(context) directly
+  -> TanStack Query updates in-memory query state
+  -> observers and query.data update
+```
+
+An ordinary refetch follows the existing persister path instead:
+
+```text
+query.refetch()
+  -> TanStack Query fetch
+  -> experimental query persister
+  -> possible persisted restore or restore-triggered refresh
+  -> normal persistence behavior
+```
+
+For a bypassed fetch, the marker makes the model persister skip persisted restore and the persister's save path for that fetch. The result still goes through TanStack Query's normal success/error handling, so the query's in-memory data, timestamps, observers, and reactive result continue to behave normally. The marker is scoped to the fetch and does not modify static query options or `meta.persister`; `meta.persister: false` remains the query-wide switch.
+
+This option is not a force-new-request primitive. The model wrapper preserves TanStack Query cancellation and in-flight deduplication semantics, including the meaning of `cancelRefetch`. A fetch that has already been deduplicated cannot be retroactively converted into a bypassed fetch. The bypass call also does not automatically cancel an ordinary persistence callback that was already queued before it.
+
+The current implementation transports the marker through the installed TanStack Query observer's internal fetch-options forwarding. `bypassPersister` is therefore a Zova model option, not a native public TanStack `RefetchOptions` field; the model wrapper keeps that internal detail out of the normal authoring surface.
+
 ## State helper families as one runtime family
 
 The state helper layer lives mainly in:

package/repo-docs/frontend/a-openapi-under-the-hood.md

@@ -31,7 +31,7 @@ A practical mental model is:
 2. `$sdk` resolves a locale-scoped `ModelSdk`
 3. `ModelSdk` exposes bootstrap, permissions, sdk, schema, Zod, and default-value helpers
 4. `SysSdk` owns the lower cache/fetch layer for bootstrap/docs/schemas
-5. `schema.ts` extracts request/query/filter/body/row/paged schema surfaces and applies scene-aware property selection
+5. `schema.ts` extracts request/query/filter/body/row/paged schema surfaces, applies scene-aware property selection, and normalizes `fieldSource` fields into canonical runtime keys
 6. downstream resource/model/table consumers reuse those lower-level surfaces rather than rebuilding them independently
 
 That means `a-openapi` is not only about generated SDK usage. It is also the lower-level schema/runtime bridge beneath the higher-level frontend runtime.
@@ -204,12 +204,21 @@ This file owns the main lower-level helpers for:
 - scene-aware property loading
 - JSON-schema-to-Zod conversion
 
+### Scene overlays, `fieldSource`, and preserved aliases
+
 The most important scene-aware rule is in `loadSchemaProperties(...)`:
 
 - property metadata can be extended by `rest.*`
-- scene-specific overlays such as `table`, `form`, `form-view`, `form-create`, and `filter` are applied
+- for `form-view`, `form-create`, and `filter`, it merges base `rest`, the shared `rest.form` overlay, and then the exact scene overlay before reading `fieldSource`
+- other scenes apply their exact overlay
 - field ordering is resolved through `rest.order`
 
+When that effective metadata supplies `fieldSource`, its nested source path becomes the canonical runtime `key`. This is the field identity that downstream form and structural consumers bind and render. The first differing original schema property name that resolves to this key is retained as `schemaKey`; later coalesced names are retained in `schemaKeys`. If a schema property already has the canonical name, `key` itself remains that original identity.
+
+Several schema properties can therefore describe one canonical field without producing several runtime field records. Coalescing is by canonical key, so its result does not depend on declaration order. Ordinary properties that do not use `fieldSource` do not acquire alias metadata.
+
+The preserved names are metadata aliases, not additional bindings. They let a structural consumer accept a DTO-facing field name while still handing the canonical key to the form runtime. See [Zova Form Under the Hood](/frontend/zova-form-under-the-hood#fieldsource-canonicalization-and-preserved-schema-aliases) for the binding consequence and [Form Layout Guide](/frontend/form-layout-guide#how-the-resolver-handles-the-declared-tree) for author-facing declaration rules.
+
 That means `a-openapi` is not only a transport/schema lookup layer.
 
 It is also the lower-level metadata shaping layer for schema-driven UI behavior.
@@ -243,6 +252,8 @@ Use these next steps depending on your question:
 - if you want OpenAPI generation/config usage, read [OpenAPI SDK Guide](/frontend/openapi-sdk-guide)
 - if you want schema-driven UI positioning, read [API Schema Guide](/frontend/api-schema-guide)
 - if you want the resource-owner consumer side, read [ModelResource Internals Deep Dive](/frontend/model-resource-internals-deep-dive)
+- if you want canonical schema keys to become form bindings, read [Zova Form Under the Hood](/frontend/zova-form-under-the-hood)
+- if you want Form Layout field-declaration matching, read [Form Layout Guide](/frontend/form-layout-guide)
 - if you want the table/resource consumer side, read [Zova Table Under the Hood](/frontend/zova-table-under-the-hood) and the resource deep dives
 
 ## Final takeaway

package/repo-docs/frontend/form-layout-guide.md

@@ -219,13 +219,25 @@ Set `layout: 'flow'` when compact fields should appear from left to right withou
 
 ## How the resolver handles the declared tree
 
-Before rendering, `resolveFormLayout(...)` reconciles `formLayout` with the current scene's resolved schema properties. This makes the declaration a **placement overlay**, not an allow-list.
+Before rendering, `resolveFormLayout(...)` reconciles `formLayout` with the current scene's resolved schema properties. This makes the declaration a **placement overlay**, not an allow-list. The preceding OpenAPI normalization step is explained in [OpenAPI Runtime Under the Hood](/frontend/a-openapi-under-the-hood#scene-overlays-fieldsource-and-preserved-aliases).
 
 ### Eligible and omitted fields
 
 Only schema properties with `rest.visible !== false` are eligible. When an eligible visible field is absent from `formLayout`, the resolver appends it as a root-level field after the declared nodes, in schema-property order.
 
-A virtual relation field that uses `fieldSource` is represented at runtime by its nested source key. A declared relation name can therefore resolve to exactly one eligible source key with that name as its prefix; for example, `studentContentForm` resolves to `studentContentForm.descriptionMarkdown`. This preserves the DTO's business-level layout tree while rendering the actual nested form value. If more than one source key has that prefix, declare the exact source key instead.
+A field that uses `fieldSource` is represented at runtime by its nested canonical source key. The loader stores that source path in `key`, retains the first differing original schema name in `schemaKey`, and retains further coalesced names in `schemaKeys`. A property already named by its canonical key retains that identity in `key`. These preserved names are aliases for declaration matching, not separate fields or bindings.
+
+Form Layout accepts three declaration forms in precedence order:
+
+1. the exact eligible canonical key;
+2. any uniquely mapped preserved schema alias from `schemaKey` or `schemaKeys`;
+3. a unique relation-prefix shorthand.
+
+For example, a real relation declaration `studentContentForm` can resolve to the sole `studentContentForm.descriptionMarkdown` source, while an intentional `fieldSource` schema alias such as `_descriptionMarkdown` can resolve to `content.descriptionMarkdown` even though it is not that source path's prefix. The resolved plan always renders and binds the canonical nested key. `fieldSource(...)` is a binding and canonical-key mapping mechanism; it neither infers nor declares the backend DTO field type. A projected field already has a schema, while a true virtual DTO key absent from the inferred projection must be defined with `$makeSchema(...)` and a concrete schema such as `z.string()`; see [Virtual fields in the DTO fields map](/backend/dto-infer-generation#virtual-fields-in-the-dto-fields-map).
+
+An alias or relation prefix must resolve to exactly one eligible canonical source. If multiple visible source keys match, it is unresolved and receives `unknownField`; declare the exact canonical source key instead. Exact canonical matches win over colliding aliases. Invisible properties contribute neither eligible fields nor usable aliases.
+
+Duplicate declarations are detected by canonical key, so an alias and `content.descriptionMarkdown` cannot render the same field twice. Resolved field names, duplicate identity, and tab paths all use the canonical key. If a declaration is removed because it is unknown, invisible, ambiguous, or duplicate, otherwise unplaced eligible canonical fields are still appended at the root.
 
 If a field must not render, make it invisible in schema metadata. Leaving it out of `formLayout.children` is not enough.
 
@@ -324,7 +336,7 @@ ZovaRender.block('basic-pageentry:blockForm', {
 });
 ```
 
-`studentContentForm` is one virtual nested-relation field in the structural tree. Its Markdown renderer owns the nested source-field UI, while the separate `StudentContent` group expresses that it is a distinct content area rather than part of the responsive profile Grid.
+`studentContentForm` is one projected, `fieldSource`-mapped nested-relation field in the structural tree. It remains the DTO-facing declaration name, while the resolved plan rewrites it to `studentContentForm.descriptionMarkdown` before field-state lookup and rendering. Its Markdown renderer owns the nested source-field UI, while the separate `StudentContent` group expresses that it is a distinct content area rather than part of the responsive profile Grid.
 
 `trainingRecords` is one field in the structural tree. Its `basic-details:formFieldDetails` renderer owns the nested details UI; Form Layout does not recursively arrange the properties inside each detail record.
 
@@ -371,8 +383,9 @@ Here `formFieldLayout.inline: true` controls how each field wrapper is presented
 4. Use `formLayout` when the requirement is field placement, Grid or flow structure, groups, or tabs.
 5. Use `layout`, `formFieldLayout`, `options`, or provider behaviors when the requirement is one field's wrapper or renderer.
 6. Keep entry actions in page-entry toolbar blocks. Keep filter action semantics in `basic-page:blockFilterActions`; place that block inside Form Layout when the actions must share structural Grid or flow placement with fields.
-7. For maintained Cabloy Basic list filters, prefer one inline flow section that explicitly lists every real filter-schema field in schema order and ends with one embedded `basic-page:blockFilterActions` block. Do not add virtual request fields, alter filter transforms, or combine it with a sibling action block.
+7. For maintained Cabloy Basic list filters, prefer one inline flow section that explicitly lists every real filter-schema field in schema order and ends with one embedded `basic-page:blockFilterActions` block. Do not add synthetic request-only filter fields, alter filter transforms, or combine it with a sibling action block.
 8. Review field names against the scene-specific schema. Unlisted visible fields are appended; unknown and duplicate declarations are silently pruned from the rendered plan.
+9. Prefer an exact canonical source path when an alias or relation prefix could match multiple visible fields. Do not list both an alias and its canonical key; canonical duplicate detection keeps only the first declaration.
 
 ## Source-reading and verification path
 
@@ -380,10 +393,14 @@ For source-level investigation, follow this order:
 
 1. `vona/src/suite/a-training/modules/training-student/src/dto/studentCreate.tsx` or `studentSelectResItem.tsx`
 2. `zova/src/suite-vendor/a-zova/modules/a-openapi/src/types/resource/formLayout.ts`
-3. `zova/src/suite-vendor/a-zova/modules/a-form/src/lib/formLayout.ts`
-4. `zova/src/suite/cabloy-basic/modules/basic-form/src/component/blockFormLayout/controller.tsx`
-5. `vona/src/suite/a-training/modules/training-student/test/student.test.ts`
-
-The Student test verifies that entry and filter DTO metadata preserves the current block nesting, optional IDs, Grid columns/spans, flow layout selection, and field order through OpenAPI generation. It is a contract-metadata test, not a browser end-to-end assertion for tabs, layout behavior, or error badges.
+3. `zova/src/suite-vendor/a-zova/modules/a-openapi/src/lib/schema.ts`
+4. `zova/src/suite-vendor/a-zova/modules/a-openapi/src/types/rest.ts`
+5. `zova/src/suite-vendor/a-zova/modules/a-form/src/lib/formLayout.ts`
+6. `zova/src/suite/cabloy-basic/modules/basic-form/src/component/blockFormLayout/controller.tsx`
+7. `zova/src/suite-vendor/a-zova/modules/a-openapi/test/lib/schema.test.ts`
+8. `zova/src/suite-vendor/a-zova/modules/a-form/test/lib/formLayout.test.ts`
+9. `vona/src/suite/a-training/modules/training-student/test/student.test.ts`
+
+The OpenAPI loader test verifies canonical `fieldSource` keys, preserved aliases, scene overlays, coalescing, and declaration-order independence. The Form Layout test verifies canonical rewriting, alias and prefix resolution, ambiguity, duplicate detection, visibility, and tab paths. The Student test verifies that entry and filter DTO metadata preserves the current block nesting, optional IDs, Grid columns/spans, flow layout selection, and field order through OpenAPI generation. It is a contract-metadata test, not a browser end-to-end assertion for tabs, layout behavior, or error badges.
 
 For the broader form runtime, continue with [Zova Form Under the Hood](/frontend/zova-form-under-the-hood) and [Zova Form Source Reading Map](/frontend/zova-form-source-reading-map).

package/repo-docs/frontend/model-resource-best-practices.md

@@ -360,6 +360,8 @@ Use this checklist before merging resource-model changes:
 8. Does bootstrap/readiness stay inside the model boundary?
 9. Are `$fetch`, `$sdk`, and model state composed coherently?
 10. Would another screen reuse this model surface confidently?
+11. Does ongoing render output read `query.data` or a model-derived reactive surface rather than an awaited `refetch()` snapshot?
+12. Are awaited `refetch()` results limited to one-shot interaction/orchestration without creating a parallel ongoing render-state owner?
 
 ## When to use this page
 

package/repo-docs/frontend/model-resource-cookbook.md

@@ -121,9 +121,15 @@ const modelStudent = (await ctx.bean._getBean(
   true,
 )) as ModelStudent;
 const querySummary = modelStudent.summary(id);
-const { data: summary } = await querySummary.refetch();
+
+await querySummary.refetch({ bypassPersister: true });
+$host.$appModal.dialog({
+  slotDefault: () => <ZMarkdownHtml html={querySummary.data?.descriptionHtml ?? ''} />,
+});
 ```
 
+`refetch({ bypassPersister: true })` is useful when this interaction needs an API-fresh result without restoring or scheduling a persistence save through the persister for that fetch. The successful result still updates the model-owned in-memory query, and the dialog remains bound to `querySummary.data`, so the query remains the source of its ongoing render state rather than transferring ownership to an awaited-result snapshot. The option affects only this fetch; normal query cancellation and in-flight deduplication rules still apply. It is not a force-new-request option: when an existing fetch is reused by TanStack Query, that fetch's semantics remain in effect. The bypassed fetch itself does not intentionally replace an existing persisted value; an already queued ordinary persistence callback is a separate operation and is not automatically cancelled. Use static `meta.persister: false` only when persistence should be disabled for the query generally.
+
 ### Avoid
 
 Do not create a second model that independently caches the same student resource list/item state just because a custom action was added.

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

@@ -278,6 +278,50 @@ const passportCode = await this.$passport.ensureFreshTempAuthToken(options);
 
 Both paths reuse the same model-owned query. When `$QueryGetFresh(...)` finds stale data, it starts `query.suspense()` and returns `undefined` for the current render; reactive query state provides the replacement value on a later render. `$QueryEnsureFresh(...)` instead waits for that refresh and propagates query errors to the interaction flow.
 
+## Render-driving state versus one-shot refetch results
+
+A query established during render remains the owner of its ongoing state. Render paths should read the current reactive surface—typically `query.data`, `query.pending`, `query.error`, or a model-derived projection—and let query updates drive a later render.
+
+An interaction or orchestration boundary may still await `query.refetch()` when it needs one result to decide whether to continue a command, navigate, show a notification, or open a dialog. That result is local to the current sequence; it does not transfer query ownership to the controller or render path.
+
+Do not copy an awaited `refetch()` result into a second long-lived controller/render state that drives an open dialog or persistent component. If the UI remains mounted and displays query-backed data, bind it to `query.data` or a model-derived reactive surface so later refetches and model updates remain visible.
+
+### Per-fetch persistence bypass
+
+When one interaction needs an API-fresh result but should not restore persisted data or schedule a persistence save for that fetch, use the model query's per-fetch option:
+
+```ts
+await query.refetch({ bypassPersister: true });
+```
+
+`bypassPersister: true`:
+
+- affects only the current fetch
+- does not change the query's static options or `meta.persister`
+- skips persisted-query restore for that fetch
+- does not schedule that fetch through the persister's save path
+- still lets TanStack Query update the in-memory query, timestamps, observers, and reactive `query.data`
+- does not create a second query or cache owner
+
+This option is not a force-new-request flag. Cancellation, `cancelRefetch`, and in-flight deduplication continue to follow TanStack Query semantics. If an existing fetch is reused, its already-established fetch semantics remain in effect. The bypassed fetch itself does not intentionally replace an existing persisted value; an already queued ordinary persistence callback is a separate operation and is not automatically cancelled.
+
+This is different from static `meta.persister: false`: the static option disables persistence for the query generally, while `bypassPersister: true` opts out only for one fetch.
+
+For example, an interaction can request a fresh summary and then open a dialog while the dialog remains bound to the query-owned state:
+
+```ts
+const querySummary = modelStudent.summary(id);
+await querySummary.refetch({ bypassPersister: true });
+
+$host.$appModal.dialog({
+  slotDefault: () => (
+    <ZMarkdownHtml html={querySummary.data?.descriptionHtml ?? ''} />
+  ),
+});
+```
+
+The awaited result may coordinate the current interaction, but ongoing rendering should continue to read `querySummary.data`.
+
 ## Practical rule 7: derive render-time state once per render when possible
 
 Even when the query object is reused, a controller can still become noisy if it repeatedly derives the same values in several helper calls.

package/repo-docs/frontend/zova-form-source-reading-map.md

@@ -147,21 +147,29 @@ Use this path when you are asking questions like:
 
 - how does a schema become rendered fields?
 - where do field props come from?
+- where does `fieldSource` become the canonical form key, and where are original schema aliases preserved?
 - how are metadata expressions or render providers resolved?
 
 ### Read the docs first
 
 - [API Schema Guide](/frontend/api-schema-guide)
+- [OpenAPI Runtime Under the Hood](/frontend/a-openapi-under-the-hood)
 - [Form Guide](/frontend/form-guide)
 
 ### Then read source in this order
 
-1. `zova/src/suite-vendor/a-zova/modules/a-form/src/component/form/controller.tsx`
-2. `zova/src/suite-vendor/a-zova/modules/a-form/src/component/form/render.tsx`
-3. `zova/src/suite-vendor/a-zova/modules/a-form/src/types/formField.ts`
+1. `zova/src/suite-vendor/a-zova/modules/a-openapi/src/lib/schema.ts`
+2. `zova/src/suite-vendor/a-zova/modules/a-openapi/src/types/rest.ts`
+3. `zova/src/suite-vendor/a-zova/modules/a-openapi/test/lib/schema.test.ts`
+4. `zova/src/suite-vendor/a-zova/modules/a-form/src/component/form/controller.tsx`
+5. `zova/src/suite-vendor/a-zova/modules/a-form/src/component/form/render.tsx`
+6. `zova/src/suite-vendor/a-zova/modules/a-form/src/types/formField.ts`
 
 ### What each file clarifies
 
+- `schema.ts` shows scene-aware `fieldSource` canonicalization and coalescing by canonical key
+- `types/rest.ts` defines the preserved `schemaKey` and `schemaKeys` aliases
+- `schema.test.ts` is the compact behavior matrix for canonical keys, aliases, scene overlays, declaration-order independence, and ordinary fields
 - `form/controller.tsx` shows schema property loading, field CEL scope creation, and top-level field prop extraction
 - `form/render.tsx` shows how schema properties become children when the form body is not manually overridden
 - `types/formField.ts` shows the field render-context shapes that the runtime passes through to renderers and behaviors
@@ -224,12 +232,14 @@ Use this path when you are asking questions like:
 
 - where does `formLayout` come from in a resource DTO?
 - how are fields, embedded blocks, sections, groups, and tabs normalized before rendering?
+- how do canonical keys, preserved schema aliases, and unique relation-prefix shorthand resolve to one field?
 - why are omitted visible fields appended or duplicate fields removed?
 - where does Cabloy Basic render responsive grids and tab error badges?
 
 ### Read the docs first
 
 - [Form Layout Guide](/frontend/form-layout-guide)
+- [OpenAPI Runtime Under the Hood](/frontend/a-openapi-under-the-hood)
 - [Table + Resource CRUD Cookbook](/frontend/table-resource-crud-cookbook)
 - [Resource Entry Page Deep Dive](/frontend/resource-entry-page-deep-dive)
 
@@ -238,18 +248,25 @@ Use this path when you are asking questions like:
 1. `vona/src/suite/a-training/modules/training-student/src/dto/studentCreate.tsx`
 2. `vona/src/suite/a-training/modules/training-student/src/dto/studentSelectResItem.tsx`
 3. `zova/src/suite-vendor/a-zova/modules/a-openapi/src/types/resource/formLayout.ts`
-4. `zova/src/suite-vendor/a-zova/modules/a-form/src/lib/formLayout.ts`
-5. `zova/src/suite/cabloy-basic/modules/basic-form/src/component/blockFormLayout/controller.tsx`
-6. `zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockFilterActions/controller.tsx`
-7. `vona/src/suite/a-training/modules/training-student/test/student.test.ts`
+4. `zova/src/suite-vendor/a-zova/modules/a-openapi/src/lib/schema.ts`
+5. `zova/src/suite-vendor/a-zova/modules/a-openapi/src/types/rest.ts`
+6. `zova/src/suite-vendor/a-zova/modules/a-form/src/lib/formLayout.ts`
+7. `zova/src/suite/cabloy-basic/modules/basic-form/src/component/blockFormLayout/controller.tsx`
+8. `zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockFilterActions/controller.tsx`
+9. `zova/src/suite-vendor/a-zova/modules/a-openapi/test/lib/schema.test.ts`
+10. `zova/src/suite-vendor/a-zova/modules/a-form/test/lib/formLayout.test.ts`
+11. `vona/src/suite/a-training/modules/training-student/test/student.test.ts`
 
 ### What each file clarifies
 
 - the Student DTOs show the entry and filter block composition that supplies layout metadata
 - the OpenAPI type contract defines the legal node grammar and responsive values
-- the resolver reconciles field metadata with visible schema fields, generated IDs, diagnostics, and preserved embedded blocks
-- the Basic block controller renders sections, groups, tabs, field spans, and embedded blocks while delegating fields to `$$form.renderField(...)`
+- `schema.ts` resolves scene overlays, canonicalizes `fieldSource`, and coalesces aliases that target one canonical key
+- `types/rest.ts` defines the preserved alias metadata
+- the resolver filters visible fields, resolves exact canonical keys before unique aliases and unique prefixes, and records duplicate identity and tab paths by canonical key
+- the Basic block controller renders sections, groups, tabs, field spans, and embedded blocks while delegating canonical field names to `$$form.renderField(...)`
 - `blockFilterActions` shows how a block rendered inside Form Layout reuses the inherited form CEL scope to invoke `$$filter`
+- the OpenAPI and Form Layout unit tests verify canonicalization, alias precedence, ambiguity, duplicates, visibility, root append, and tab paths
 - the Student test verifies emitted metadata nesting, columns, spans, embedded action blocks, and optional IDs; it is not a browser rendering test
 
 ## 8. Resource-driven CRUD page integration

package/repo-docs/frontend/zova-form-under-the-hood.md

@@ -11,6 +11,7 @@ Use this page together with:
 - [Zova Reactivity Under the Hood](/frontend/zova-reactivity-under-the-hood)
 - [Behavior Guide](/frontend/behavior-guide)
 - [API Schema Guide](/frontend/api-schema-guide)
+- [OpenAPI Runtime Under the Hood](/frontend/a-openapi-under-the-hood)
 
 Use this page after [Form Guide](/frontend/form-guide) when you want to move from the public authoring surface to the internal cooperation among form controllers, field controllers, schema metadata, provider config, behaviors, and CRUD integration.
 
@@ -233,6 +234,14 @@ A practical reading takeaway is:
 - **schema is not only validation truth**
 - **schema also drives ordering, render metadata, and scene-specific field behavior**
 
+### `fieldSource` canonicalization and preserved schema aliases
+
+`loadSchemaProperties(...)` constructs the effective property `rest` metadata before inspecting `fieldSource`: base metadata, the applicable shared `form` overlay, and then the exact scene overlay. When that metadata supplies `fieldSource`, its nested source path becomes the property's canonical `key`.
+
+The form uses this canonical key for field-property lookup, CEL field scope, values, validation, and rendering. When an original schema property name differs, `schemaKey` preserves the first such name that reached the canonical key, while `schemaKeys` preserves later coalesced names. A property already named by its canonical key retains that identity in `key`. These preserved names are aliases for metadata consumers such as Form Layout, not independent form bindings.
+
+Consequently, several DTO-facing schema names can represent one nested field without creating duplicate form state. The OpenAPI loader owns this normalization and coalescing; see [OpenAPI Runtime Under the Hood](/frontend/a-openapi-under-the-hood#scene-overlays-fieldsource-and-preserved-aliases) for its lower-level contract.
+
 ### The form owner supplies the schema lifetime
 
 `ZForm` derives `properties` and `zodSchema` from the schema it receives. Its runtime does not own `$apiSchema` locale selection or refresh a facade retained by the page/controller. If the owner supplies a schema object created under an earlier locale, the form will faithfully render that object's titles and metadata.
@@ -445,6 +454,8 @@ That means automatic schema-driven rendering is not happening magically in the w
 
 When `ZForm` receives a nonempty block list, the render bean delegates body rendering to those blocks instead of iterating schema fields directly. For Cabloy Basic structural forms, `basic-form:blockFormLayout` resolves `formLayout` against the form's current schema properties and calls `$$form.renderField(...)` for each surviving layout field.
 
+For a field declaration, the shared resolver first accepts an exact canonical key, then a uniquely mapped preserved schema alias, and then a unique relation-prefix shorthand. It rewrites an alias or shorthand to the canonical key before calling `$$form.renderField(...)`. Exact canonical keys win over colliding aliases; ambiguous aliases or prefixes are reported as `unknownField`. Duplicate tracking and tab-path bookkeeping use the canonical key, while visible canonical fields not placed by a surviving declaration are appended afterward. See [Form Layout Guide](/frontend/form-layout-guide#how-the-resolver-handles-the-declared-tree) for the full DTO authoring rules.
+
 Form Layout also supports a leaf `block` node. It wraps an existing resource block descriptor and the Basic renderer invokes it with the inherited `IJsxRenderContextForm`, including the same JSX runtime and CEL scope. The node has no schema property or field value; for example, a filter can place `basic-page:blockFilterActions` inside a flow section while that action block continues to read `$$filter` from the filter-owned form scope.
 
 This keeps ownership separate:

package/repo-docs/fullstack/one-to-one-companion-resource-guide.md

@@ -318,7 +318,7 @@ const contentField = $makeMetadata(
 );
 ```
 
-The exact renderer is edition-specific; the nested source contract is not. Use the DTO relation option type, `include`, and `dtoClass` according to the inferred DTO pattern. Do not add derived HTML to a mutation DTO merely because it exists in the table.
+The exact renderer is edition-specific; the nested source contract is not. This is a valid `$makeMetadata(...)` overlay because `parentContentForm` is already supplied by the inferred relation projection through the DTO relation option type, `include`, and `dtoClass`; its schema exists before the renderer and `fieldSource(...)` metadata is added. `fieldSource(...)` maps the projected field to the nested source path but does not declare `sourceMarkdown`'s type. If a field-map key is instead a true virtual DTO key absent from the inferred projection, define it with `$makeSchema(...)` and an appropriate final concrete schema such as `z.string()`; see [Virtual fields in the DTO fields map](/backend/dto-infer-generation#virtual-fields-in-the-dto-fields-map). Do not add derived HTML to a mutation DTO merely because it exists in the table.
 
 A DTO or OpenAPI declaration is not a substitute for runtime response review. If a service returns an already-built object with extra properties, narrowing the declaration alone may not remove those properties from JSON. Verify the actual action response as well as emitted schema metadata.
 

package/repo-e2e/specs/a-commerce.spec.ts

@@ -1737,6 +1737,7 @@ test(
     const categoryName = `E2E SKU Category ${suffix}`;
     const productTitle = `E2E SKU Product ${suffix}`;
     const skuCode = `E2E-SKU-${suffix}`;
+    const stockActionPath = '/api/commerce/trade/stockBalance/adjustStock';
     const adminContext = await browser.newContext();
     const adminPage = await adminContext.newPage();
     const adminPageErrors = collectPageErrors(adminPage);
@@ -1805,8 +1806,46 @@ test(
       const skuRow = adminPage.getByRole('row', { name: new RegExp(skuCode) });
       await expect(skuRow).toBeVisible();
       await expect(skuRow.getByText('12.34', { exact: true })).toBeVisible();
+      await expect(skuRow.getByText('0', { exact: true })).toBeVisible();
       await expect(skuRow.getByText('Draft', { exact: true })).toBeVisible();
       await expect(skuRow.getByRole('link', { name: skuCode, exact: true })).toBeVisible();
+      const adjustStockButton = skuRow.getByRole('button', { name: 'Adjust stock', exact: true });
+      await expect(adjustStockButton).toBeVisible();
+      await expect(adminPage.locator('html')).toHaveAttribute(
+        'data-zova-hydrated',
+        'commerceAdmin',
+      );
+      await adjustStockButton.click();
+      await expect(adminPage.getByRole('dialog')).toBeVisible();
+      await expect(adminPage.getByRole('dialog').getByText(skuCode, { exact: true })).toBeVisible();
+      await expect(adminPage.getByRole('dialog').getByText('0', { exact: true })).toBeVisible();
+      const deltaInput = adminPage.getByRole('group', { name: 'Delta' }).getByRole('spinbutton');
+      const reasonInput = adminPage.getByRole('group', { name: 'Reason' }).getByRole('textbox');
+      await deltaInput.fill('7');
+      await reasonInput.fill('Initial E2E stock');
+      const stockRequest = adminPage.waitForRequest(request => {
+        return request.method() === 'POST' && new URL(request.url()).pathname === stockActionPath;
+      });
+      const stockResponse = adminPage.waitForResponse(response => {
+        return (
+          response.request().method() === 'POST' &&
+          new URL(response.url()).pathname === stockActionPath
+        );
+      });
+      await adminPage
+        .getByRole('dialog')
+        .getByRole('button', { name: 'Adjust stock', exact: true })
+        .click();
+      const stockRequestValue = await stockRequest;
+      expect(stockRequestValue.postDataJSON()).toMatchObject({
+        skuId,
+        delta: 7,
+        reason: 'Initial E2E stock',
+        correlationId: expect.any(String),
+      });
+      expect((await stockResponse).ok()).toBeTruthy();
+      await expect(adminPage.getByRole('dialog')).toHaveCount(0);
+      await expect(skuRow.getByText('7', { exact: true })).toBeVisible();
       await expect(
         adminPage.locator('section').getByText('SKU code', { exact: true }),
       ).toBeVisible();
@@ -1822,6 +1861,7 @@ test(
       expect(adminPageErrors).toEqual([]);
     } finally {
       if (skuId && headers) {
+        await adminPage.request.delete(`${stockActionPath}/${skuId}`, { headers }).catch(() => {});
         const response = await adminPage.request.delete(`${skuActionPath}/${skuId}`, { headers });
         expect(response.ok()).toBeTruthy();
       }

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

@@ -1,6 +1,6 @@
 {
   "name": "vona-cli",
-  "version": "1.1.141",
+  "version": "1.1.142",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "vona cli",
   "keywords": [