cabloy 5.1.61 → 5.1.62

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

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

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

@@ -0,0 +1,248 @@
+# OpenAPI Runtime Under the Hood
+
+This guide explains the lower-level runtime of `a-openapi` in Zova through the current public Cabloy Basic source.
+
+Use this page when you want to understand:
+
+- how `$sdk` becomes available on beans
+- what `ModelSdk` and `SysSdk` each own
+- how bootstrap and permissions loading work
+- how request/query/filter/body/row/paged schema surfaces are derived
+- why `a-openapi` is a lower-level shared runtime substrate for resource, model, and table consumers
+
+## Why this page exists
+
+Several existing docs already explain usage and positioning around the server-data ladder:
+
+- [Server Data](/frontend/server-data)
+- [SDK Guide](/frontend/sdk-guide)
+- [OpenAPI SDK Guide](/frontend/openapi-sdk-guide)
+- [API Schema Guide](/frontend/api-schema-guide)
+
+What those pages do not isolate directly is the source-first runtime path inside `a-openapi` itself.
+
+That is the gap this page fills.
+
+## The shortest accurate mental model
+
+A practical mental model is:
+
+1. `a-openapi` injects `$sdk` onto beans through its module monkey
+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
+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.
+
+## Source-confirmed reading path
+
+When reading this topic, use this order:
+
+1. `zova/src/suite-vendor/a-zova/modules/a-openapi/src/monkey.ts`
+2. `zova/src/suite-vendor/a-zova/modules/a-openapi/src/model/sdk.ts`
+3. `zova/src/suite-vendor/a-zova/modules/a-openapi/src/bean/sys.sdk.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. optional supporting files:
+   - `zova/src/suite-vendor/a-zova/modules/a-openapi/src/types/sdk.ts`
+   - `zova/src/suite-vendor/a-zova/modules/a-openapi/src/config/config.ts`
+
+That order moves from bean-level injection, to the locale-scoped model surface, to the lower fetch/cache layer, to the schema extraction layer, and finally to the schema/type contract.
+
+## `$sdk` injection and locale-scoped runtime
+
+The injection layer lives in:
+
+```text
+zova/src/suite-vendor/a-zova/modules/a-openapi/src/monkey.ts
+```
+
+The key source-confirmed behavior is:
+
+- `beanInit(...)` defines `$sdk` on bean instances
+- `$sdk` points to a ref-like current `ModelSdk`
+- `moduleLoaded(...)` loads the SDK model for the current locale
+- locale changes trigger `_loadSdk()` again
+
+That means `$sdk` is not a static global object.
+
+It is a runtime-injected, locale-scoped model surface.
+
+## `ModelSdk` responsibilities
+
+The selector-backed model lives in:
+
+```text
+zova/src/suite-vendor/a-zova/modules/a-openapi/src/model/sdk.ts
+```
+
+The current source confirms that `ModelSdk` is:
+
+- `@Model({ enableSelector: true })`
+- selector-backed by locale
+- responsible for:
+  - `getBootstrap(resource)`
+  - `getPermissions(resource)`
+  - `getSdk(api, method)`
+  - `getSchema(schemaName)`
+  - `getZodSchema(schemaName)`
+  - `getSchemaDefaultValue(schemaName)`
+  - `createApiSchemas(api, method)`
+  - `loadSchemaProperties(schema, schemaScene)`
+  - `schemaToZodSchema(schema)`
+
+A practical reading rule is:
+
+- `ModelSdk` is the higher model-facing façade over lower OpenAPI runtime state
+- it is the surface most downstream consumers actually reuse
+
+## `SysSdk` responsibilities
+
+The lower runtime owner lives in:
+
+```text
+zova/src/suite-vendor/a-zova/modules/a-openapi/src/bean/sys.sdk.ts
+```
+
+Its main jobs are:
+
+- store loaded bootstraps
+- store loaded schemas
+- store loaded operation SDK entries by API and method
+- fetch bootstrap data
+- fetch operation-level OpenAPI docs
+- cache schemas and operation objects in reactive stores
+- reload caches during SSR HMR reload paths
+
+This is the lower-level owner beneath `ModelSdk`.
+
+A practical rule is:
+
+- `ModelSdk` is the model-facing surface
+- `SysSdk` is the lower cache/fetch owner
+
+## Bootstrap and permissions loading
+
+The bootstrap path is defined in `ModelSdk.getBootstrap(resource)`.
+
+The source confirms that:
+
+- bootstrap data is loaded first
+- permissions are then loaded through `getPermissions(resource)`
+- on the server, permissions are autoloaded as part of the bootstrap path
+- on the client, permission queries are refetched when needed
+
+That means bootstrap and permissions are part of the same lower-level OpenAPI/runtime ladder, not unrelated utilities.
+
+## `getSdk(...)` and schema preloading
+
+The operation-level SDK path is centered on:
+
+- `ModelSdk.getSdk(api, apiMethod)`
+- `SysSdk.loadSdk(...)`
+
+The source confirms that:
+
+- one operation-level SDK entry is keyed by API path and request method
+- schema docs are fetched through the lower OpenAPI fetch path
+- component schemas referenced by the operation document are cached into `SysSdk.schemas`
+- operation metadata is cached into `SysSdk.sdks`
+
+That means `getSdk(...)` is not only a fetch helper. It is also a preloading point for the schema runtime that later powers query/body/row/filter access.
+
+## `createApiSchemas(...)` and derived schema surfaces
+
+The high-value consumer-facing helper is:
+
+- `createApiSchemas(api, method)`
+
+The source confirms that it exposes these derived surfaces:
+
+- `query`
+- `filter`
+- `requestBody`
+- `responseBody`
+- `paged`
+- `row`
+
+This is the most practical lower-level bridge from raw OpenAPI docs into the higher-level resource, form, and table runtimes.
+
+A practical reading rule is:
+
+- downstream consumers should reuse these derived schema surfaces
+- they should not rebuild request/query/body/row extraction rules independently
+
+## `schema.ts` and scene-aware property loading
+
+The canonical schema extraction layer lives in:
+
+```text
+zova/src/suite-vendor/a-zova/modules/a-openapi/src/lib/schema.ts
+```
+
+This file owns the main lower-level helpers for:
+
+- request body schema extraction
+- response body schema extraction
+- request query schema extraction
+- filter-schema extraction
+- scene-aware property loading
+- JSON-schema-to-Zod conversion
+
+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
+- field ordering is resolved through `rest.order`
+
+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.
+
+## Current consumers that prove the contract
+
+The clearest current consumers of `a-openapi` runtime are:
+
+- `rest-resource/src/model/resource.ts`
+- list and entry page shells that reuse `ModelResource`
+- table/form runtimes that consume schema surfaces derived from `createApiSchemas(...)` and `loadSchemaProperties(...)`
+
+This is enough to show that `a-openapi` should be understood as shared runtime substrate rather than one isolated SDK helper.
+
+## What this page does not re-explain
+
+This page does **not** fully re-explain:
+
+- how to configure or generate OpenAPI SDK output -> see [OpenAPI SDK Guide](/frontend/openapi-sdk-guide)
+- the broader server-data abstraction ladder -> see [Server Data](/frontend/server-data)
+- how `$apiSchema` is positioned conceptually -> see [API Schema Guide](/frontend/api-schema-guide)
+- downstream resource-owner or table runtime behavior -> see the relevant resource/table deep dives
+
+Its job is only to explain the lower-level `a-openapi` runtime and source path.
+
+## Where to read next
+
+Use these next steps depending on your question:
+
+- if you want the broader server-data ladder, read [Server Data](/frontend/server-data)
+- 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 the table/resource consumer side, read [Zova Table Under the Hood](/frontend/zova-table-under-the-hood) and the resource deep dives
+
+## Final takeaway
+
+The most accurate way to read `a-openapi` is not as one generated-client helper.
+
+Read it as the lower-level schema/runtime bridge that:
+
+- injects `$sdk`
+- scopes SDK/runtime state by locale
+- loads bootstrap, permissions, operation docs, and component schemas
+- derives request/query/filter/body/row/paged schema surfaces
+- applies scene-aware schema-property shaping
+- supports higher-level resource, form, and table consumers
+
+That is the source-confirmed role of `a-openapi` in the current Cabloy Basic frontend architecture.