cabloy 5.1.149 → 5.1.151

package/repo-docs/backend/migration-and-changes.md

@@ -48,6 +48,31 @@ The key rule is:
 
 In the scaffolded CRUD workflow, this is not an isolated maintenance step. The generator-driven thread treats `fileVersion` as part of the same backend evolution path that also touches entity/model/controller/test resources.
 
+## Decide whether to increment fileVersion
+
+For a new persisted field or another schema-shape change on an existing resource, decide whether `vonaModule.fileVersion` should change **before** editing `meta.version.ts`, a versioned schema path, or the module `package.json`.
+
+### Increment fileVersion
+
+Choose a new migration version when the change must be applied sequentially to an existing released module:
+
+1. increment `fileVersion`;
+2. add a new migration branch;
+3. preserve older branches as historical snapshots;
+4. introduce the schema change in the new branch.
+
+Do not introduce the same column in an older create path and again in a later migration branch. A fresh installation can execute version branches sequentially and fail on a duplicate column.
+
+### Keep the current fileVersion
+
+When the change belongs in the current version path rather than new migration history:
+
+1. keep the existing `fileVersion`;
+2. fold the schema change into the current version path;
+3. do not create a new migration branch.
+
+Ask before choosing this strategy; do not infer migration history from the field change alone. Any change to `meta.version.ts` requires `npm run test` so the test database is recreated and schema/data consistency is exercised.
+
 ## `meta.version`
 
 Vona uses a bean named `meta.version` to organize migration code for a module.
@@ -156,9 +181,9 @@ When the generated CRUD thread evolves, migration should evolve with it.
 
 A practical sequence is:
 
-1. increment `fileVersion`
+1. decide whether to increment `fileVersion`
 2. add or adjust entity/model structure
-3. update `meta.version` logic
+3. update the current or new `meta.version` path to match that decision
 4. rerun migration locally
 5. verify the contract through tests and controller actions
 

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

@@ -254,7 +254,7 @@ A practical distinction is:
 
 That means model behavior affects performance and consistency semantics, not only data retrieval.
 
-For the broader cache story, also see [Cache Guide](/backend/cache-guide).
+For the broader cache story, also see [Cache Guide](/backend/cache-guide). For dependencies between Models, see [Cross-model query-cache dependencies](/backend/cache-guide#cross-model-query-cache-dependencies).
 
 ## Relationship to the backend contract loop
 

package/repo-docs/backend/resource-field-update.md

@@ -0,0 +1,156 @@
+# Existing Resource Field Update
+
+<Badge type="tip" text="Common" />
+
+Use this workflow when changing a field on an existing Vona resource. It covers a new persisted field, validation or metadata refinement, enum-like constraints, and the optional renderer follow-up that connects backend `ZovaRender.*(...)` metadata to Zova resources.
+
+This is a field-update workflow, not a substitute for initial module or CRUD scaffolding. For a new backend thread, start from [CRUD Workflow](/backend/crud-workflow). For an already stale generated consumer, start from the [Contract Loop Playbook](/fullstack/contract-loop-playbook).
+
+## When to use this workflow
+
+Use it when you need to:
+
+- add a stored field to an existing resource;
+- refine validation, titles, OpenAPI metadata, or `ZovaRender.field(...)` / `ZovaRender.cell(...)` metadata for an existing field;
+- add enum-like field constraints;
+- decide whether a persisted field change increments `vonaModule.fileVersion`;
+- add a custom form-field or table-cell renderer because shared renderer options are insufficient.
+
+Before changing anything, detect the active edition from the root marker. Explain the common backend workflow once, then resolve renderer keys, frontend flavors, build commands, and generated-output paths from the active edition.
+
+## Persisted field or metadata-only change
+
+Classify the work before editing migration code.
+
+### New persisted field
+
+Examples include a new `level: number`, `status: string`, or stored relation key. This changes storage shape and requires an explicit `fileVersion` decision.
+
+### Metadata-only or validation/rendering refinement
+
+Examples include:
+
+- enum validation for a field that already exists in storage;
+- a new field or table rendering hint;
+- locale-label changes;
+- stricter validation that does not change storage shape.
+
+This usually does not require a `fileVersion` increment. Confirm the current schema first instead of assuming the field already exists.
+
+## Decide whether to increment fileVersion
+
+For a new persisted field, decide with the user **before** editing `meta.version.ts`, a versioned schema path, or the module `package.json`.
+
+### Increment fileVersion
+
+When the change needs a new sequential migration:
+
+1. increment `vonaModule.fileVersion`;
+2. add a new `meta.version.ts` migration branch;
+3. preserve older branches as historical snapshots;
+4. introduce the field only in the new version branch.
+
+Do not add the same column to an older create path and again to a later migration branch. A fresh installation can apply the branches sequentially and fail on a duplicate column.
+
+### Keep the current fileVersion
+
+When the user decides not to create new migration history:
+
+1. keep the current `fileVersion`;
+2. fold the schema change into the current version path;
+3. do not create a new migration branch.
+
+For the complete migration lifecycle and test requirement, see [Migration and Changes](/backend/migration-and-changes#decide-whether-to-increment-fileversion).
+
+## Inspect the existing resource thread
+
+Read the current implementation before proposing changes:
+
+- entity and model;
+- DTOs, controller, and service;
+- `meta.version.ts` and module `package.json`;
+- locale files;
+- resource tests;
+- root `package.json`, `npm run vona`, and `npm run zova`.
+
+Use source patterns to determine whether DTOs are inferred. Do not hand-edit generated consumers or duplicate existing schema metadata.
+
+## Update entity truth first
+
+Treat the entity as the primary field-definition surface. Typical changes begin with `@Api.field(...)`, validation helpers, titles, and `ZovaRender.*(...)` metadata.
+
+For enum-like values, prefer a constrained schema that expresses the allowed values explicitly, for example `z.union([z.literal(1), z.literal(2), z.literal(3)])`.
+
+Structure-shaping schema helpers remain order-sensitive. When a field uses `v.object(...)`, `v.array(...)`, `v.optional()`, `v.nullable()`, `v.default(...)`, preprocess/transform wrappers, or an explicit zod schema, keep the final structure-defining schema-like argument last. Then verify emitted schema/OpenAPI output rather than assuming argument reordering is safe.
+
+For the underlying contract surface, see [Entity Guide](/backend/entity-guide#api-field-as-the-shared-contract-surface).
+
+## Preserve the inferred DTO flow
+
+When DTOs use `$Dto.create(...)`, `$Dto.update(...)`, `$Dto.get(...)`, or another inferred projection, let the entity change propagate. Add hand-authored field lists only when the current source demonstrates an intentional business projection or a separate contract-only field.
+
+For projected fields, 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.
+
+Read [DTO Infer and Generation](/backend/dto-infer-generation) when inference cannot express the intended contract. If serialization metadata controls the returned value, also confirm that the target controller action opts into `@Core.serializer()`.
+
+## Choose the renderer branch
+
+Prefer the smallest rendering change that expresses the requirement:
+
+1. reuse an existing shared renderer;
+2. configure it with field-level options;
+3. create a custom module-local renderer only when the shared surface cannot express the needed behavior.
+
+For a field-rendering select, provide a visible placeholder unless the UX genuinely requires a preselected value.
+
+### Shared renderer reuse
+
+Resolve renderer keys and component behavior in the active edition. Cabloy Basic and Cabloy Start can differ in select wrappers, placeholder behavior, UI library, flavors, and generated outputs. Do not copy a Basic renderer key or empty-item convention into Start without inspecting the Start baseline.
+
+### Custom renderer follow-up
+
+A custom backend-rendered field normally needs both sides of the frontend pair:
+
+- a module-local FormField component;
+- a registered module-local `@TableCell(...)` bean when backend `ZovaRender.cell(...)` references a table cell.
+
+A plain frontend component is not sufficient for backend table-cell metadata. Reuse the closest shared renderer’s option/data flow and keep the customization focused.
+
+For public implementation patterns, see [Form Guide](/frontend/form-guide), [TableCell Cookbook](/frontend/table-cell-cookbook#pattern-7-backend-contract-to-frontend-cell-handoff), and the Basic-only [Custom Form/Table Renderers tutorial](/fullstack/tutorial-4-custom-level-renderers).
+
+## Follow the contract loop
+
+A field change commonly has two possible handoffs:
+
+- a persisted entity/DTO/OpenAPI change begins with the **forward chain**: update backend truth, verify emitted contract output, regenerate frontend consumers, then make thin follow-up changes;
+- a new frontend-owned FormField or TableCell resource begins the **reverse chain**: update frontend source, regenerate metadata when needed, run the active edition’s complete frontend build, then run `npm run deps:vona`.
+
+Do not treat `build:rest:*` alone as sufficient for reverse-chain work. The SSR bundle and REST output must move together. If generated `.zova-rest` output already contains the expected keys but Vona still sees stale types after the normal build and dependency sync, treat the issue as local dependency drift and repair the local installation state before hand-patching generated links.
+
+Use the [Contract Loop Playbook](/fullstack/contract-loop-playbook) for edition-aware commands and recovery details.
+
+## Update locale and tests
+
+Update locale files when users can see field titles, enum labels, placeholders, or renderer helper text.
+
+Minimum backend coverage generally includes:
+
+- create with the field;
+- select/list behavior;
+- update persistence;
+- get-by-id or view response;
+- delete behavior when it is relevant.
+
+For constrained enum-like values, add a negative test that proves an invalid value is rejected. Test-local persisted resources must be deleted in `finally` using precise owned identities and reverse dependency order.
+
+## Verification checklist
+
+Choose checks that match the layers changed:
+
+- inspect generated schema/OpenAPI after structure-shaping field changes;
+- run the narrow resource test and relevant typecheck;
+- run `npm run test` for any `meta.version.ts` change so the test database is recreated and migration consistency is exercised;
+- run the relevant frontend metadata/build/dependency synchronization when custom renderer resources are involved;
+- verify action-level serializer behavior with an API test when `v.serializer*` metadata changes returned fields.
+
+Finish by confirming the backend contract, frontend resources, generated handoff, and user-visible locale labels all describe the same field behavior.

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/router-tabs-introduction.md

@@ -110,15 +110,13 @@ Recommended order:
 
 1. [Router Tabs Mechanism](/frontend/router-tabs-mechanism)
 2. [Router Tabs Admin and Web Comparison](/frontend/router-tabs-admin-web-comparison)
-3. `repo-docs-internal/architecture/router-tabs-design-boundaries.md`
+3. inspect the current implementation and public comparison guidance for refactor boundaries
 
 ## Scope boundary
 
 The public router-tabs docs explain the shared frontend mechanism and how to use it.
 
-For internal design boundaries, maintenance invariants, and refactor safety rules, see:
-
-- `repo-docs-internal/architecture/router-tabs-design-boundaries.md`
+For maintainer-only design boundaries, maintenance invariants, and refactor safety rules, consult an established internal-documentation home when the active repository provides one. The public mechanism, layout, route-meta, and Admin/Web comparison guides remain the shared implementation baseline.
 
 ## See also
 

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/a-pay-payment-suite.md

@@ -265,7 +265,7 @@ The Commerce payment route requires authentication and uses the session SSR prof
 
 The invariant is more important than a particular visual shell: server HTML and the hydration-time initial render must agree about private payment/order data. Do not render customer-owned payment state on the server when the request cannot authorize it, and do not let the provider return itself settle Commerce.
 
-For the deeper SSR return and Passport recovery rationale, maintainers can consult the internal architecture note. The public rule remains: settle on verified server facts; recover private browser state only after hydration and authorization.
+When the active repository provides the corresponding internal architecture note, maintainers can consult it for deeper SSR return and Passport recovery rationale. The public rule remains: settle on verified server facts; recover private browser state only after hydration and authorization.
 
 ## Reliability and security invariants
 

package/repo-docs/fullstack/contract-loop-playbook.md

@@ -113,6 +113,9 @@ Examples:
 - controller request or response changed
 - validation changed
 - OpenAPI metadata changed
+- an existing resource field changed
+
+For an existing resource-field change, first use [Existing Resource Field Update](/backend/resource-field-update) to make the persistence, DTO, locale, renderer, and migration decision explicit. Then continue with the applicable contract-loop branch.
 
 Then use the **forward chain**:
 
@@ -357,6 +360,7 @@ Use the tutorial series as examples of the two chains:
 
 - [Fullstack Introduction](/fullstack/introduction)
 - [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
+- [Existing Resource Field Update](/backend/resource-field-update)
 - [Frontend Metadata Back to Backend](/fullstack/frontend-metadata-to-backend)
 - [Vona + Zova Integration](/fullstack/vona-zova-integration)
 - [OpenAPI SDK Guide](/frontend/openapi-sdk-guide)