cabloy 5.1.97 → 5.1.99

package/cabloy-docs/frontend/resource-list-page-deep-dive.md

@@ -102,7 +102,7 @@ zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/page/resource/controlle
 Its main jobs are:
 
 - resolve the current selector-backed `ModelResource`
-- autoload select API schemas
+- ensure select API schemas are loaded
 - read `schemaRow?.rest?.blocks`
 - render those blocks through `ZovaJsx`
 

package/cabloy-docs/frontend/rest-resource-source-reading-map.md

@@ -207,7 +207,7 @@ Read:
 This controller does three main things:
 
 1. resolves the selector-backed `ModelResource` instance from `this.$params.resource`
-2. autoloads `apiSchemasSelect.sdk`
+2. ensures `apiSchemasSelect.sdk` is loaded
 3. reads `schemaRow?.rest?.blocks` and renders those blocks through `ZovaJsx`
 
 The key point is what it does **not** do.
@@ -239,7 +239,7 @@ It mainly owns:
 - `formMeta` derivation
 - `formProvider` lookup from `ModelResource`
 - `formSchema` lookup from `ModelResource`
-- autoload of the form API schemas
+- ensuring the form API schemas are loaded
 - block rendering from `formSchema?.rest?.blocks`
 
 Again, the most important insight is what it does **not** fully own.

package/cabloy-docs/frontend/rest-resource-under-the-hood.md

@@ -98,7 +98,7 @@ Route record
                  └─ page-controller shell
                       ├─ resolves current resource / id / formScene
                       ├─ resolves selector-backed ModelResource
-                      ├─ autoloads top-level API schema surface
+                      ├─ ensures top-level API schema surface is loaded
                       └─ reads schemaRow.rest.blocks or formSchema.rest.blocks
                                │
                                ▼
@@ -255,7 +255,7 @@ zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/page/resource/controlle
 The main jobs of `ControllerPageResource` are:
 
 1. resolve the selector-backed model from `this.$params.resource`
-2. autoload the select API schema through `this.$$modelResource.apiSchemasSelect.sdk`
+2. ensure the select API schema is loaded through `this.$$modelResource.apiSchemasSelect.sdk`
 3. read `this.schemaRow?.rest?.blocks`
 4. render those blocks through `ZovaJsx`
 
@@ -291,7 +291,7 @@ The main jobs of `ControllerPageEntry` are:
 - derive `formMeta`
 - expose `formProvider` from the model
 - expose `formSchema` from the model
-- autoload the form API schemas
+- ensure the form API schemas are loaded
 - read `formSchema?.rest?.blocks`
 - render those blocks through `ZovaJsx`
 
@@ -366,7 +366,7 @@ That means one generic model class can serve many resources safely, because the
 Inside initialization, `_bootstrap()` calls:
 
 ```typescript
-$QueryAutoLoad(() => this.$sdk.getBootstrap(this.resource));
+$QueryEnsureLoaded(() => this.$sdk.getBootstrap(this.resource));
 ```
 
 and then resolves:

package/cabloy-docs/frontend/server-data.md

@@ -45,6 +45,8 @@ Use OpenAPI SDK generation when you want backend-generated API contracts to driv
 
 Use schema-driven layers when metadata itself needs to participate in higher-level frontend behavior such as validation or automatic rendering.
 
+If your main question is not only which data-access layer to choose, but how data ownership, sharing boundaries, persistence, and SSR semantics fit together in large Vue systems, read [State Architecture for Vue Developers](/frontend/state-architecture-for-vue-developers) together with this page.
+
 ## Why this matters for Cabloy
 
 This abstraction ladder is one of the key links between Zova and Vona.

package/cabloy-docs/frontend/state-architecture-for-vue-developers.md

@@ -0,0 +1,218 @@
+# State Architecture for Vue Developers
+
+This guide is for Vue developers who already know common Vue state patterns and want the shortest docs-style explanation of how Zova/Cabloy organizes large-project state differently.
+
+It does **not** argue that Vue's usual tools are wrong.
+It explains why large projects often need a stronger architecture for state ownership, sharing boundaries, persistence, cache semantics, and SSR behavior.
+
+Use this page together with:
+
+- [Reading Zova for Vue Developers](/frontend/reading-zova-for-vue-developers)
+- [Zova vs Vue 3 Comparison](/frontend/zova-vs-vue3-comparison)
+- [IoC and Beans](/frontend/ioc-and-beans)
+- [Model Architecture](/frontend/model-architecture)
+- [Model Resource Owner Pattern](/frontend/model-resource-owner-pattern)
+
+## Why this page exists
+
+Many Vue teams do not struggle because they picked one obviously bad tool.
+
+They struggle because a large codebase gradually accumulates many valid state mechanisms at the same time:
+
+- component-local reactive state
+- composables
+- `provide/inject`
+- store layers
+- query cache
+- local persistence
+- SSR-specific state rules
+
+Each mechanism can solve a real local problem.
+
+The large-project difficulty usually appears later, when the team can no longer answer these questions cleanly:
+
+- who owns this state?
+- how far should it be shared?
+- which lifecycle rules apply to it?
+- who owns cache identity and invalidation?
+- is this only a value, or part of a larger resource boundary?
+
+That is the architectural problem this page addresses.
+
+## The shortest accurate summary
+
+If you only remember one paragraph, remember this one:
+
+> Large Vue projects rarely become hard because they need one more state tool. They usually become hard because ownership, sharing boundaries, persistence, cache semantics, and SSR behavior stop composing into one coherent system.
+
+Zova's answer is to push those concerns back under a more explicit architecture:
+
+- **Controller / Bean** makes ownership more explicit
+- **IoC scopes** make sharing boundaries more explicit
+- **Model** unifies several state families under one model-owned boundary
+- **Resource Owner** keeps query, schema, permissions, forms, and invalidation closer to one resource-level owner
+
+## Start with boundary questions, not only tool questions
+
+In many Vue projects, state discussions begin with questions like these:
+
+- should this go into a composable?
+- should this move to a store?
+- should we add a query layer?
+- should we persist this in localStorage?
+
+Those are reasonable questions.
+
+But in a large system, the more important questions usually come first:
+
+1. **Ownership** — which framework-managed object should own this state?
+2. **Sharing boundary** — is it local, parent/child shared, app-level, or system-level?
+3. **State family** — is it query-style remote state, in-memory state, local persistence, cookie-backed state, or async persisted state?
+4. **Lifecycle** — what should survive page disposal, refresh, route transitions, or SSR request boundaries?
+5. **Resource boundary** — does this state belong to a larger resource owner that also owns schema, permissions, forms, and invalidation?
+
+Zova tries to answer those questions structurally instead of leaving them spread across unrelated mechanisms.
+
+## 1. Ownership: make the state host explicit
+
+A common Vue mental model starts with local reactive primitives and composition logic inside `setup()`.
+
+Zova keeps Vue's reactive foundation, but changes the visible business-facing host. The most important state often lives on framework-managed Controller or Bean instances instead of starting life as scattered local variables.
+
+That changes the reading question from:
+
+- which composable or local variable holds this?
+
+into:
+
+- which Controller, Bean, or Model owns this?
+
+That is a better scaling question because ownership drift is often the first step toward cache drift, persistence drift, and SSR drift.
+
+For the broader authoring-model shift, read [Reading Zova for Vue Developers](/frontend/reading-zova-for-vue-developers) and [Zova vs Vue 3 Comparison](/frontend/zova-vs-vue3-comparison).
+
+## 2. Sharing: treat scope as a first-class architectural decision
+
+Large Vue codebases often express different sharing ranges through different mechanisms:
+
+- component-local state
+- parent-child props or `provide/inject`
+- app-level stores
+- long-lived globals or imported singletons
+
+Zova tries to keep more of those cases inside one bean-and-container architecture.
+
+A compact comparison is:
+
+| Sharing range      | Common Vue pattern                                      | Zova framing                                        |
+| ------------------ | ------------------------------------------------------- | --------------------------------------------------- |
+| component-internal | local state or component-local composables              | `ctx`-scoped bean ownership                         |
+| between-components | props/emits, parent-owned composables, `provide/inject` | hierarchical injection such as `host` or `skipSelf` |
+| app-global         | store or app-level provided state                       | `app`-scoped bean ownership                         |
+| system-level       | module singleton or long-lived imported state           | `sys`-scoped bean ownership                         |
+
+The key idea is simple:
+
+> Do not start by switching mechanisms. Start by choosing the sharing boundary.
+
+This distinction becomes especially important in SSR, where app/request state and system-level state should not be mixed casually.
+
+Read together with [IoC and Beans](/frontend/ioc-and-beans) and [System Startup Guide](/frontend/system-startup-guide).
+
+## 3. Model: unify multiple state families under one model boundary
+
+In many stacks, remote cache, in-memory shared state, local persistence, cookie state, and async persistent state are handled by separate tools or utilities.
+
+Zova Model tries to organize those families under one broader model-owned runtime.
+
+The current model layer exposes five main state families:
+
+- `data`
+- `mem`
+- `local`
+- `cookie`
+- `db`
+
+This means Model is not only a request wrapper and not only another store.
+
+Its architectural role is to give several important state categories a shared home for concerns such as:
+
+- cache identity
+- invalidation
+- restore behavior
+- persistence strategy
+- SSR-aware hydration behavior
+
+Read together with [Model Architecture](/frontend/model-architecture), [Model State Guide](/frontend/model-state-guide), and [Server Data](/frontend/server-data).
+
+## 4. Resource Owner: keep resource semantics together
+
+A large frontend resource usually needs more than a query call.
+
+The frontend often also needs:
+
+- schema
+- permissions
+- forms
+- list and item queries
+- create/update/delete mutations
+- invalidation rules
+
+If those concerns are split across pages, form helpers, store logic, and query callbacks, the resource boundary becomes hard to explain.
+
+Zova's resource-owner direction tries to keep more of that semantic bundle under one stable owner.
+
+A useful shorthand is:
+
+> the page consumes resource semantics, while the model owns query and resource semantics.
+
+That is why the Resource Owner pattern matters in large applications: it improves not only reuse, but also boundary stability.
+
+Read together with [Model Resource Owner Pattern](/frontend/model-resource-owner-pattern) and [Using ModelResource in Your Module](/frontend/model-resource-usage-guide).
+
+## One comparison table
+
+| Dimension          | Common large-Vue drift                                            | Zova architectural answer                                       |
+| ------------------ | ----------------------------------------------------------------- | --------------------------------------------------------------- |
+| State host         | state starts locally, then moves outward case by case             | assign ownership first to Controller / Bean / Model             |
+| Sharing            | sharing range often changes the mechanism                         | sharing is framed through IoC scopes                            |
+| Persistence        | local, cookie, and async persistence drift into utilities         | persistence lives inside model-state families                   |
+| Cache identity     | keys and refresh rules drift across pages and callbacks           | model identity and model policy own more of the cache semantics |
+| SSR                | request-level and long-lived state can blur together              | `app` and `sys` make the distinction structural                 |
+| Resource semantics | schema, forms, permissions, and invalidation spread across layers | Resource Owner pulls them back under one owner                  |
+
+## When this architecture matters most
+
+This architecture is most valuable when the frontend is:
+
+- long-lived
+- maintained by multiple developers
+- SSR-aware
+- cache-heavy
+- persistence-heavy
+- resource-heavy
+
+For small or short-lived projects, a lighter scattered approach may still be good enough.
+
+The point is not that every Vue project must adopt the same architecture.
+The point is that as complexity rises, boundary control becomes more important than adding one more tool.
+
+## Recommended reading path
+
+If this page matches your question, continue in this order:
+
+1. [Reading Zova for Vue Developers](/frontend/reading-zova-for-vue-developers)
+2. [Zova vs Vue 3 Comparison](/frontend/zova-vs-vue3-comparison)
+3. [IoC and Beans](/frontend/ioc-and-beans)
+4. [Model Architecture](/frontend/model-architecture)
+5. [Model State Guide](/frontend/model-state-guide)
+6. [Model Resource Owner Pattern](/frontend/model-resource-owner-pattern)
+7. [System Startup Guide](/frontend/system-startup-guide)
+
+## Final takeaway
+
+The most important practical idea is simple:
+
+> Large Vue projects usually do not need more state tools first. They need a state architecture that can keep ownership, scope, persistence, cache semantics, SSR behavior, and resource boundaries coherent as the system grows.
+
+That is the main reason to read Zova's frontend architecture through Controller / Bean ownership, IoC scopes, Model, and Resource Owner, instead of mapping every state problem back to one more isolated Vue mechanism.

package/cabloy-docs/frontend/system-startup-guide.md

@@ -167,6 +167,8 @@ The legacy system-start docs used route registration as the clearest example bou
 
 That distinction is especially important in SSR-capable systems, where app lifecycles can repeat while system-level route and config wiring should not.
 
+If your main question is how this `app` versus `sys` lifecycle split participates in the broader state architecture of a large Vue application, read [State Architecture for Vue Developers](/frontend/state-architecture-for-vue-developers) together with [IoC and Beans](/frontend/ioc-and-beans).
+
 A practical reading sequence is:
 
 1. [Environment and Config Guide](/frontend/environment-config-guide)

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

@@ -0,0 +1,384 @@
+# `$useStateData` Best Practices
+
+This guide explains how to use `$useStateData(...)` well in Zova, especially when you are deciding whether a piece of async frontend data should behave like render-time state or interaction-time ad hoc fetch logic.
+
+Read [Model Architecture](/frontend/model-architecture) first if you want the broader role of Model.
+
+Read [Model State Guide](/frontend/model-state-guide) first if you want the larger helper-family overview.
+
+Use this page when your real design question is one of these:
+
+- should this async value live in a model query or stay inside one controller?
+- should the query be established during render or only during interaction?
+- should I use `enabled: false` or let the query participate in the normal lifecycle?
+- how should I think about `disableSuspenseOnInit: true`?
+- if I remove a manual `ensure...()` helper, can interaction still wait for query readiness when needed?
+
+## Why this page exists
+
+`$useStateData(...)` is easy to misuse if it is treated only as a request helper.
+
+The larger value is architectural:
+
+- model-owned async state gets one stable owner
+- query identity, persistence, restore, and refetch behavior stay in one place
+- render logic can consume a formal query state instead of rebuilding mini loading/cache systems in controllers
+
+The common failure mode is not that the code stops working immediately.
+
+The common failure mode is that the code keeps working while the state model becomes increasingly command-oriented, duplicated, and difficult to reason about.
+
+## The core mental model
+
+The best starting point is simple:
+
+> treat `$useStateData(...)` as a model-owned async state source, not only as a function that happens to fetch data.
+
+That changes several downstream decisions.
+
+If a value affects:
+
+- whether a button can be clicked
+- accepted file types
+- maximum upload size
+- whether a UI branch is shown
+- whether a flow can continue safely
+
+then that value is usually not just a click-time fetch result.
+It is part of the page's real interaction state.
+
+## Practical rule 1: prefer model ownership for reusable async state
+
+When a value has broader reuse, persistence, or lifecycle requirements, prefer model ownership.
+
+Typical good fits are:
+
+- upload policy by scene
+- resource bootstrap
+- schema metadata
+- permission/capability state
+- query-style domain state reused across pages or components
+
+Typical weak fits are:
+
+- a one-off page-local toggle
+- a tiny local interaction detail with no reuse value
+- temporary page-only state that does not benefit from caching or restore semantics
+
+### Review question
+
+Ask:
+
+> if another controller needed this same async value tomorrow, would I want the ownership and lifecycle policy to already exist in one model?
+
+If the answer is yes, that state usually belongs in a model.
+
+## Practical rule 2: if the value affects render or interaction rules, establish the query during render
+
+If a value determines runtime interaction conditions, prefer this shape:
+
+1. model exposes `getXxx(...)`
+2. controller/page establishes the query during render
+3. render consumes `data`, `pending`, and derived values
+4. interaction consumes that existing query state instead of inventing a second lifecycle
+
+### Why this is good
+
+This keeps the UI honest.
+
+The rendered UI can already know:
+
+- whether interaction should wait
+- which accept/multiple flags apply
+- which validation path should be used
+
+### Smell
+
+A controller renders as though the interaction is ready, but clicking the button is what really begins the important state lookup.
+
+That is a sign that a query-state concern may have been pushed too far into imperative interaction code.
+
+## Practical rule 3: `disableSuspenseOnInit: true` disables the init-time `query.suspense()` kick, not the query itself
+
+This point needs precise wording.
+
+Current model runtime shows that `$useStateData(...)` creates the query wrapper first, then, only on first creation, optionally calls `query.suspense()`:
+
+```ts
+if (!this[SymbolUseQueries][queryHash]) {
+  const useQuery = this.$useQuery(options, queryClient);
+  this[SymbolUseQueries][queryHash] = useQuery;
+  if (!options.meta?.disableSuspenseOnInit) {
+    useQuery.suspense();
+  }
+}
+```
+
+Two details matter:
+
+- the query is already created either way
+- the runtime does **not** use `await` there
+
+So `disableSuspenseOnInit: true` does **not** mean “block vs do not block render” in a strict synchronous sense.
+
+It more precisely means:
+
+- with default behavior, the first consumer of that query immediately kicks one init-time `query.suspense()` call
+- with `disableSuspenseOnInit: true`, that automatic init-time kick is skipped
+
+This option is often a good fit when you want:
+
+- query state to exist immediately
+- persistence/restore/refetch behavior to remain normal
+- no automatic init-time `query.suspense()` kick on first creation
+
+Representative pattern:
+
+```ts
+getUploadPolicy(imageScene?: string) {
+  if (!imageScene) return undefined;
+  return this.$useStateData({
+    queryKey: ['uploadPolicy', 'image', imageScene],
+    queryFn: async () => {
+      return this.scope.api.image.getUploadPolicy({ imageScene });
+    },
+    meta: {
+      disableSuspenseOnInit: true,
+    },
+  });
+}
+```
+
+### What it does not mean
+
+It does not mean:
+
+- no query should be created
+- no request should run
+- no persisted value should be restored
+- no refetch should happen later
+- interaction can never explicitly wait for query readiness
+
+That distinction matters a lot.
+
+## Practical rule 4: distinguish three different semantics
+
+A useful review habit is to keep these three behaviors separate.
+
+| Case                                                            | What happens                                                                       | What it does **not** mean                                                          | Best fit                                                                                                                         |
+| --------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| Default `$useStateData(...)`                                    | On first query creation, runtime immediately calls `query.suspense()` once         | It does **not** synchronously `await` readiness in that call site                  | Data where “first consumer should eagerly kick one refresh/update semantic” is a good default                                    |
+| `$useStateData(..., { meta: { disableSuspenseOnInit: true } })` | Query still exists, but the automatic init-time `query.suspense()` kick is skipped | It does **not** disable the query, persistence, restore, or later refetch behavior | Data that is relatively stable inside the current frontend process and does not need an automatic first-consumer kick every time |
+| `await query.suspense()`                                        | Current logic sequence explicitly waits until the query is ready                   | It is **not** merely a hint or passive kickoff                                     | Interaction or orchestration boundaries where later logic must not continue until the value is ready                             |
+
+Two practical consequences follow from this table:
+
+1. multiple synchronous `query.suspense()` calls can still deduplicate at the query runtime level
+2. only explicit `await query.suspense()` introduces a true sequencing guarantee for the current logic path
+
+## Practical rule 5: be cautious with `enabled: false` and `staleTime: Infinity`
+
+These options are useful, but they are easy to over-apply.
+
+### `enabled: false`
+
+Use it when the query should not exist yet because a real prerequisite is missing.
+
+Good examples:
+
+- required params are absent
+- the page is in a branch where the query truly does not apply
+- the query would be meaningless or invalid before some explicit condition
+
+Be cautious when the real motivation is only:
+
+- “I want to fetch later when the user clicks”
+
+That often means you are taking a state concern and turning it back into a command concern.
+
+### `staleTime: Infinity`
+
+Use it when the value is effectively static for the relevant session.
+
+Be cautious when the underlying backend configuration may change.
+
+If backend scene config can change, letting the query participate in normal freshness/refetch rules is usually healthier than freezing it forever.
+
+## Practical rule 6: removing a manual `ensure...()` helper does not mean interaction can never wait
+
+A common over-correction is:
+
+- first version: controller manually owns fetching through `ensure...()`
+- second version: remove `ensure...()` and assume interaction must never wait for anything
+
+The better middle ground is:
+
+- query lifecycle remains model-owned
+- query is established during render
+- interaction consumes the existing query
+- if an edge timing window appears, interaction may wait for the existing query to finish
+
+That is very different from rebuilding a second fetch lifecycle.
+
+## 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.
+
+A good cleanup pattern is to derive one local state object such as:
+
+- `acceptAttr`
+- `multiple`
+- `pending`
+
+and let input/button/render branches consume that shared result.
+
+### Why this helps
+
+It makes one render pass easier to understand:
+
+- what query-backed state is being consumed
+- which UI props come from that state
+- where the interaction gate really is
+
+### Smell
+
+The controller repeatedly:
+
+- grabs the same query
+- re-reads the same policy data
+- re-derives the same `multiple` or `accept` value in several places
+
+That is often a sign that local render-time derivation should be consolidated.
+
+## Practical rule 8: design query keys so the ownership boundary is obvious
+
+Prefer keys that make the domain explicit.
+
+For example:
+
+- `['uploadPolicy', 'image', imageScene]`
+- `['uploadPolicy', 'file', fileScene]`
+
+This is usually better than ambiguous cross-domain shapes such as:
+
+- `['uploadPolicy', scene]`
+
+### Why this matters
+
+Readable keys improve:
+
+- debugging
+- tracing cache behavior
+- future refactors when similar query families grow
+
+## Anti-pattern: command-first controller state
+
+A common anti-pattern looks like this:
+
+- model query is disabled by default
+- controller clicks trigger `ensure...()`
+- controller maintains the important timing logic itself
+- render does not fully know the interaction conditions yet
+
+### Why this is harmful
+
+- the model no longer owns the full lifecycle cleanly
+- restore/refetch semantics are weakened or bypassed
+- controller responsibilities grow too large
+- interaction rules become harder to inspect from the render path
+
+## Better pattern: model-owned query, render-owned derivation, interaction-owned orchestration
+
+A healthier split is:
+
+### Model owns
+
+- `queryKey`
+- `queryFn`
+- persistence/restore/refetch lifecycle
+- the stable meaning of the async state
+
+### Controller/page owns
+
+- how the query-backed state is rendered
+- derived props needed by the current UI
+- user interaction flow
+- edge-timing waits on the already-existing query when necessary
+
+This creates a much cleaner division of responsibilities.
+
+## Representative examples
+
+### Example A: resource entry pages usually prefer the default init-time kick
+
+A good counterexample to overusing `disableSuspenseOnInit: true` is the resource entry-page branch.
+
+Useful reading pages are:
+
+- [Resource Entry Page Deep Dive](/frontend/resource-entry-page-deep-dive)
+- [ModelResource Internals Deep Dive](/frontend/model-resource-internals-deep-dive)
+
+In that branch, the practical expectation is often:
+
+- opening a row page may show an already-known value first
+- but entering that page should still eagerly kick one update semantic for the item-level state
+- the page benefits from the default “first consumer kicks `query.suspense()` once” behavior
+
+This makes entry pages a good mental model for queries where the default init-time kick is healthy:
+
+- the query is a real page-state dependency
+- the first consumer should actively nudge freshness
+- you usually do not want every caller to remember to add that kickoff manually
+
+This is not about synchronous blocking.
+It is about preserving the default eager-init semantic when the first consumer of that page state appears.
+
+### Example B: upload policy prefers `disableSuspenseOnInit: true`
+
+Representative files in the Cabloy Basic frontend:
+
+- `zova/src/suite/cabloy-basic/modules/basic-image/src/model/image.ts`
+- `zova/src/suite/cabloy-basic/modules/basic-file/src/model/file.ts`
+- `zova/src/suite/cabloy-basic/modules/basic-image/src/component/formFieldImage/controller.tsx`
+- `zova/src/suite/cabloy-basic/modules/basic-file/src/component/formFieldFile/controller.tsx`
+
+### What this example demonstrates
+
+- `getUploadPolicy(...)` stays in the model
+- the query is created as formal state instead of a one-off click helper
+- `disableSuspenseOnInit: true` skips the automatic init-time `query.suspense()` kick while preserving the query as formal state
+- render derives `acceptAttr`, `multiple`, and `pending`
+- interaction reuses that state
+- interaction may still `await query.suspense()` on the already-created query if an edge timing window requires it
+
+Why this is a good fit:
+
+- upload policy is a real query-backed state
+- it is relatively stable within the current frontend process
+- every first consumer does not need to auto-kick one eager init-time refresh semantic
+- the strict-ready moment is the interaction boundary, not every initial render consumer
+
+Taken together, Example A and Example B show the most important design contrast on this page:
+
+- entry-page item state is a good example of why the default init-time kick can be valuable
+- upload policy is a good example of why a stable state may still be a formal query while skipping that init-time kick
+
+## Checklist before you use `$useStateData(...)`
+
+Ask these questions:
+
+1. Is this value really a reusable async state source rather than a one-off action result?
+2. Will this value affect render or interaction conditions?
+3. Should another page or controller be able to consume the same lifecycle and cache policy later?
+4. Is `disableSuspenseOnInit: true` enough, instead of disabling the query entirely?
+5. Would `enabled: false` or `staleTime: Infinity` accidentally cut off useful restore/refetch behavior?
+6. If interaction needs a safety wait, can it wait on the existing query rather than reintroducing a manual `ensure...()` lifecycle?
+7. Can I derive the render-time state once and reuse it across the UI branch?
+
+## Final takeaway
+
+The most important usage insight is simple:
+
+> `$useStateData(...)` is strongest when it models async state that the UI can render from, persist, restore, and refresh naturally.
+
+When that mindset is clear, controllers become thinner, models become more authoritative, and query lifecycle decisions become easier to reason about.