cabloy 5.1.115 → 5.1.117

package/cabloy-docs/backend/orm-select-guide.md

@@ -122,29 +122,34 @@ A practical operator-family reading is:
 - composition/subquery: `_and_`, `_or_`, `_not_`, `_exists_`, `_notExists_`
 - identifier helper: `_ref_`
 
-### Omitting a condition with `Op.omit`
+### Absent, `undefined`, and `null` in `where`
 
-Use `Op.omit` when you want to express omission explicitly at the call site. `Op.omit` is defined as `undefined`, but using the named constant makes the business meaning of the query object clearer.
+A direct `where` object distinguishes omitted conditions from SQL `NULL` checks:
+
+| Field value                | Meaning                           |
+| -------------------------- | --------------------------------- |
+| Field is absent            | Do not add a condition            |
+| Own field with `undefined` | Do not add a condition            |
+| `Op.omit`                  | Explicitly do not add a condition |
+| `null`                     | Match SQL `NULL` with `IS NULL`   |
+
+An own `undefined` means the property exists on the JavaScript object but its value is `undefined`, such as `{ title: undefined }`. It has the same query result as an absent field, while `Op.omit` is the readable way to make that omission intentional in a dynamically composed query.
 
 Representative pattern:
 
 ```typescript
 import { Op } from 'vona-module-a-orm';
 
-const where = {
-  title: { _includes_: 'ai' },
-  stars: { _gt_: 20 },
-};
-
 await this.scope.model.post.select({
   where: {
-    ...where,
-    stars: Op.omit,
+    title: undefined, // omitted
+    stars: Op.omit, // explicitly omitted
+    publishedAt: null, // SQL IS NULL
   },
 });
 ```
 
-This lets a query builder remove one condition cleanly without rebuilding the whole `where` object by hand, while `null` remains available for SQL `IS NULL` semantics.
+The same direct-`where` rule applies to filters used by mutation, aggregate, and group operations.
 
 That distinction also matters at the request-contract layer: omitting a nullable filter and passing a real `null` are different operations. When a query DTO needs `IS NULL` behavior from frontend query params, the parsing contract must explicitly preserve `null` instead of collapsing it to omission.
 

package/cabloy-docs/backend/rate-limit-guide.md

@@ -0,0 +1,97 @@
+# Rate Limit Guide
+
+## Overview
+
+`a-ratelimit` limits matched Vona HTTP API actions across all application workers. It runs as the global `a-ratelimit:rateLimit` interceptor after Passport has resolved an authenticated or anonymous subject, and before request-body parsing, pipes, local middleware, and controller code. See [Controller AOP Guide](/backend/controller-aop-guide) for the general request-stage diagram and the distinction between a local aspect and a route override of an existing global onion.
+
+It protects controller APIs. Put volumetric, static-file, unknown-route, and network-edge protection in the reverse proxy, WAF, or gateway.
+
+## Enablement and rollout
+
+The interceptor ships with `enable: false` to preserve compatibility. Enable the global interceptor through standard onion configuration and begin in observe mode:
+
+```ts
+config.onions.interceptor['a-ratelimit:rateLimit'] = {
+  enable: true,
+  rateLimit: {
+    mode: 'observe',
+    limit: 120,
+    windowMs: 60_000,
+  },
+};
+```
+
+`observe` records requests that would exceed the policy but does not reject them. Review `rate_limit.would_reject` events and Redis health, then deliberately enable enforcement:
+
+```ts
+config.onions.interceptor['a-ratelimit:rateLimit'] = {
+  enable: true,
+  rateLimit: {
+    mode: 'enforce',
+    limit: 120,
+    windowMs: 60_000,
+    key: 'identity',
+    headers: true,
+  },
+};
+```
+
+Use instance configuration when tenants require different policy values. Each limiter key always includes the active instance, so one instance never consumes another instance’s quota.
+
+## Route policies
+
+Use `Core.rateLimit(...)` on a controller for its baseline policy, or on an action for a stricter policy, an intentional shared bucket, or an explicit exemption:
+
+```ts
+import { Core } from 'vona-module-a-core';
+
+@Core.rateLimit({
+  enable: true,
+  rateLimit: {
+    mode: 'enforce',
+    limit: 5,
+    windowMs: 60_000,
+    name: 'password-reset',
+  },
+})
+@Web.post('request-reset')
+@Passport.public()
+async requestReset() {}
+
+@Core.rateLimit({ enable: false })
+@Web.get('health')
+@Passport.public()
+health() {}
+```
+
+`enable`, matching, and ordering remain outer interceptor options. The nested `rateLimit` object contains the quota policy, so partial controller/action overrides inherit the remaining policy fields through normal Vona onion merging. Interceptor options use normal Vona precedence: application config, active-instance config, controller/action decorators, then controlled dynamic onion overrides used by tests. A controller/action can enable a narrower policy while the global interceptor is disabled, or set `enable: false` as a reviewed exemption after global activation. Do not put this policy in another middleware’s options: only `a-ratelimit:rateLimit` consumes the `rateLimit` object at the post-Passport interceptor stage.
+
+## Identity and Redis storage
+
+The default `key: 'identity'` combines the proxy-trusted `ctx.ip` with the authenticated subject. Anonymous callers therefore receive an IP-scoped budget. Use `key: 'ip'` for an explicitly IP-only policy or `key: 'subject'` when a stable subject budget must follow a user across addresses.
+
+Do not parse `X-Forwarded-For` in application code. Vona resolves `ctx.ip` according to its configured proxy trust settings. The trusted reverse proxy must replace client-supplied forwarding headers before forwarding a request.
+
+The limiter always uses the dedicated `limiter` Redis client; this infrastructure choice is not a route-policy field. It registers one atomic Lua fixed-window counter command during module startup and invokes that command for each request. Redis keys contain the instance, policy, normalized route, window start, and a SHA-256 digest of the identity; raw IP addresses and subject IDs are not stored in key text.
+
+Fixed windows provide one low-cost atomic operation per request. A limit can burst around a window boundary; choose lower limits or shorter windows for especially sensitive actions.
+
+## HTTP response contract
+
+In enforce mode, evaluated requests expose RFC 9333 fields when `headers` is enabled:
+
+- `RateLimit-Limit`
+- `RateLimit-Remaining`
+- `RateLimit-Reset` (seconds until the window resets)
+
+A rejected request returns Vona’s standard HTTP `429 Too Many Requests` response and also includes `Retry-After`. The rejected request does not reach body parsing or controller logic.
+
+If the limiter Redis operation fails during enforce mode, Cabloy returns `503`, not `429`, and logs `rate_limit.redis_error`. This closed behavior preserves admission protection rather than silently accepting unbounded public traffic. During observe mode, a Redis failure is logged but does not turn the observation rollout into an outage.
+
+## Operations
+
+The primary structured events are `rate_limit.would_reject`, `rate_limit.rejected`, and `rate_limit.redis_error`. They contain only route/policy/instance and error-class information; do not add raw identities, full URLs, or Redis keys to logs or metric labels.
+
+The `limiter` client may initially use the same Redis deployment as other Vona clients, but it is separately configured so production can isolate its endpoint, timeout, and capacity. Ensure Redis remains available before globally setting `enable: true` with `rateLimit.mode: 'enforce'`.
+
+See [Controller AOP Guide](/backend/controller-aop-guide), [Config Guide](/backend/config-guide), [Redis Guide](/backend/redis-guide), and [Multi-Instance and Instance Resolution](/backend/multi-instance-and-instance-resolution).

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

@@ -0,0 +1,93 @@
+# Telemetry Guide
+
+Vona can export backend distributed traces through the optional `a-telemetry` module. It is disabled by default and keeps Winston as the application logging API.
+
+## Enable tracing
+
+Configure the following deployment environment variables:
+
+```ini
+TELEMETRY_ENABLED=true
+TELEMETRY_SERVICE_NAME=cabloy-basic
+TELEMETRY_OTLP_HTTP_URL=https://collector.example.com/v1/traces
+TELEMETRY_OTLP_HTTP_HEADERS=authorization=Bearer%20token
+TELEMETRY_SAMPLING_ROOT_RATIO=0.1
+
+# Optional: continue trusted internal HTTP traces only
+TELEMETRY_INGRESS_TRUSTED_PROXY_CIDRS=10.0.0.0/8
+TELEMETRY_INGRESS_INTERNAL_HEADER=x-vona-telemetry-ingress
+TELEMETRY_INGRESS_INTERNAL_HEADER_VALUE=internal
+```
+
+The module exports traces through OTLP/HTTP protobuf. Use an OpenTelemetry Collector as the stable integration boundary; the Collector may export to Tempo, Jaeger, or a managed observability platform.
+
+`TELEMETRY_SAMPLING_ROOT_RATIO` is the root sampling ratio. Begin with a low value such as `0.01` to `0.1`, then increase only after measuring exporter drops, CPU, memory, and trace volume.
+
+## Propagation
+
+The module uses W3C Trace Context:
+
+- public HTTP ingress ignores caller-supplied `traceparent` and `tracestate`, so local root sampling always applies
+- a trusted internal ingress may continue W3C trace context only when its direct socket peer matches `TELEMETRY_INGRESS_TRUSTED_PROXY_CIDRS` and the protected classification header has the configured value
+- outgoing queue jobs and Redis Broadcast messages carry a versioned technical trace carrier
+- queue and Broadcast consumers create child spans in a new Vona context
+- internal `performAction(...)` calls create an internal child span
+
+The trusted-CIDR list defaults to empty. Keep it empty unless a controlled reverse proxy or gateway is responsible for classifying internal traffic. The application evaluates the direct socket peer, not `ctx.innerAccess`, `ctx.ip`, or generic proxy settings. A trusted proxy must remove any client-provided copy of the classification header and overwrite it with its own decision before forwarding the request. When public and internal traffic use the same proxy, CIDR matching alone is insufficient; the protected header is required as the second trust condition.
+
+Vona emits `x-request-id` for HTTP requests. It is a request diagnostic identifier and is different from OpenTelemetry `trace_id` and `span_id`.
+
+Existing domain `correlationId` values remain business or idempotency identifiers. Do not replace them with trace IDs or automatically attach raw business IDs to span attributes.
+
+## Logging correlation
+
+When an active telemetry span is present, existing Vona log entries receive these technical fields:
+
+```text
+request_id
+trace_id
+span_id
+trace_flags
+```
+
+Continue to use `$logger` and `$loggerChild(...)`. Do not create request-specific cached loggers.
+
+## Custom module spans
+
+Use the global telemetry facade from a container-managed bean when adding a bounded custom operation:
+
+```ts
+return await this.bean.telemetry.withNamedSpan('payment.validate', async () => {
+  return await this._validatePayment();
+});
+```
+
+All facade methods are safe to call without checking `enabled`. When telemetry is disabled, `startSpan(...)` returns a non-recording span, `withSpan(...)` directly invokes its callback, and `recordException(...)` does nothing; no trace is created, activated, propagated, or exported.
+
+`withNamedSpan(...)` is the preferred API: it creates an active child span, records thrown errors, and always attempts to end the span. For an operation whose lifecycle must be controlled manually, use `startSpan(...)`, `withSpan(...)`, and `recordException(...)` without an `enabled` branch:
+
+```ts
+const span = this.bean.telemetry.startSpan('payment.validate');
+try {
+  return await this.bean.telemetry.withSpan(span, () => this._validatePayment());
+} catch (error) {
+  this.bean.telemetry.recordException(span, error);
+  throw error;
+} finally {
+  span.end();
+}
+```
+
+The facade intentionally does not expose carrier propagation, HTTP ingress trust, HTTP span handling, or provider lifecycle. Use a stable, bounded operation name and follow the privacy and cardinality rules below.
+
+## Privacy and cardinality
+
+The built-in spans use HTTP method, route templates, status codes, module/controller/action names, queue names, Broadcast names, and retry counts. They do not record request or response bodies, cookies, authorization headers, raw query values, user IDs, tenant names, or business document IDs.
+
+Only add business attributes after an explicit privacy, tenancy, cardinality, and retention review. Prefer bounded operation categories over opaque identifiers.
+
+## Operations
+
+Every Vona worker owns and flushes its own exporter. Export failures and shutdown timeouts must not fail user requests. Configure Collector-side tail sampling for error or slow-trace retention instead of trying to force sampling in application code.
+
+Browser telemetry, WebSocket message tracing, database instrumentation, and third-party SDK instrumentation are intentionally separate follow-up work.

package/cabloy-docs/backend/vona-source-reading-map.md

@@ -128,7 +128,50 @@ If the next question becomes specifically about explicit DTOs, inferred DTO help
 
 If the next question becomes specifically about how those controller, DTO, and entity surfaces become emitted backend contract, continue with [Backend Contract Emission Source Reading Map](/backend/backend-contract-emission-source-reading-map).
 
-## 3. A compact reading strategy
+## 3. Controller request pipeline, onion configuration, and rate limiting
+
+Use this path when you are asking questions like:
+
+- what runs before route matching, after route matching, or after Passport authentication?
+- should this concern be system/global/local middleware, guard, interceptor, pipe, or filter?
+- why does a controller/action override preserve some global onion options?
+- why does `@Core.rateLimit(...)` configure a global interceptor instead of adding a local one?
+
+### Read the docs first
+
+- [AOP Overview](/backend/aop-overview)
+- [Controller AOP Guide](/backend/controller-aop-guide)
+- [Controller Guide](/backend/controller-guide)
+- [Rate Limit Guide](/backend/rate-limit-guide) when the concern is request admission
+
+### Then read source in this order
+
+1. `vona/src/suite-vendor/a-vona/modules/a-web/src/main.ts`
+2. `vona/src/suite-vendor/a-vona/modules/a-web/src/bean/bean.router.ts`
+3. `vona/src/suite-vendor/a-vona/modules/a-web/src/lib/middleware/middlewareGuard.ts`
+4. `vona/src/suite-vendor/a-vona/modules/a-web/src/lib/middleware/middlewareInterceptor.ts`
+5. `vona/src/suite-vendor/a-vona/modules/a-web/src/lib/middleware/middlewarePipe.ts`
+6. `vona/src/suite-vendor/a-vona/modules/a-onion/src/service/onion_.ts`
+7. `vona/src/suite-vendor/a-vona/modules/a-aspect/src/lib/use/useOnionBase.ts`
+8. `vona/src/suite-vendor/a-vona/modules/a-aspect/src/lib/use/useOnionGlobalBase.ts`
+9. `vona/src/suite-vendor/a-vona/modules/a-ratelimit/src/bean/interceptor.rateLimit.ts` when tracing rate-limit policy consumption
+
+### What each file clarifies
+
+- `main.ts` proves that system middleware is composed before router lookup.
+- `bean.router.ts` establishes the matched-route sequence: global middleware, guard, interceptor, pipe, local middleware, then action.
+- The guard, interceptor, and pipe middleware files show the fixed middle stages independently.
+- `onion_.ts` proves global/local onion composition and the effective deep merge of defaults, configuration, route metadata, and dynamic overrides.
+- `useOnionBase.ts` shows how a local use decorator joins the local execution chain; `useOnionGlobalBase.ts` shows how a global use decorator writes route options for an already-global onion.
+- `interceptor.rateLimit.ts` is the concrete post-Passport policy consumer and shows why `rateLimit` is owned by that interceptor’s options.
+
+For exception behavior only, continue to `a-error/src/config/config.ts` and `a-aspectutils/src/service/filter.ts`. Do not treat filters as part of the normal successful request path.
+
+### Stop condition
+
+Do not infer placement from an aspect/decorator name alone. Prove both the outer route stage in `bean.router.ts` and the inner global/local composition and option merge in `onion_.ts` before changing request-path behavior.
+
+## 4. A compact reading strategy
 
 When in doubt, use this order:
 

package/cabloy-docs/frontend/model-resource-owner-pattern.md

@@ -361,6 +361,8 @@ Use a resource-owner model when:
 
 This pattern is especially strong for admin-style, resource-driven UIs.
 
+When the same persisted domain also has a genuinely different customer self-service contract, keep this owner for the Admin Resource boundary and use a dedicated model for the distinct self-service state. See [Admin Resource and Web Self-Service](/fullstack/admin-resource-and-web-self-service) for the cross-stack decision rule and Commerce Order specimen.
+
 ## When not to use this pattern
 
 Do not reach for this pattern by default when:

package/cabloy-docs/frontend/ssr-overview.md

@@ -34,6 +34,8 @@ For browser work that must wait for the initial SSR handoff, register `this.$ssr
 
 This lifecycle applies only to the initial client hydration of SSR HTML. It is not an SPA-startup or later client-navigation readiness signal. Do not render a client-ready marker into server HTML; add it from an `onHydrated(...)` callback when browser-visible evidence is required.
 
+For a render-time branch, use `this.$ssr.isRuntimeSsrHydrated`. It is reactive and is `false` during server rendering and the browser's initial hydration render, then `true` after that hydration completes. It is also immediately `true` for SPA startup and later client navigation. Use it to retain the same neutral shell before hydration and begin private or browser-only queries and UI afterward. It indicates only SSR-hydration lifecycle readiness, not completed route admission, authentication, or data loading.
+
 ### SEO meta
 
 SSR also supports flexible SEO metadata handling.

package/cabloy-docs/fullstack/admin-resource-and-web-self-service.md

@@ -0,0 +1,329 @@
+# Admin Resource and Web Self-Service
+
+A business domain often has two valid audiences:
+
+- **Admin** users perform permission-controlled operational work, usually through schema-driven resource pages.
+- **Web** users perform self-service work on data that belongs to them, usually through purpose-built pages.
+
+Those audiences should usually share the same domain, persistence model, and lifecycle rules. They should not automatically share one HTTP projection, one authorization rule, or one frontend page architecture.
+
+This guide explains the reusable Cabloy pattern:
+
+> Keep one business resource boundary, but expose separate Admin Resource and Web self-service contracts when their authority, scope, projection, or experience differs.
+
+The pattern is Common-first and applies to both Cabloy Basic and Cabloy Start. The Commerce Order implementation used below is a **Cabloy Basic specimen**; detect the active edition before relying on its UI, site, or build details.
+
+## Where this guide fits
+
+This page connects several mechanisms that have their own deeper documentation:
+
+- [Backend Resource/Module Contract Chain](/backend/backend-resource-module-contract-chain) explains backend resource layers.
+- [Model Resource Owner Pattern](/frontend/model-resource-owner-pattern) explains Admin resource-state ownership.
+- [Contract Loop Playbook](/fullstack/contract-loop-playbook) explains generated contract direction and recovery.
+- [SSR Review Checklist](/frontend/ssr-review-checklist) explains server-render and hydration review boundaries.
+
+Use this page when the design question is broader:
+
+> Should Admin operators and Web users consume one resource as one API/page, or as separate audience-specific surfaces?
+
+## The shortest accurate model
+
+Treat these as different decisions:
+
+| Concern                         | Usually shared                                              | Usually audience-specific                                 |
+| ------------------------------- | ----------------------------------------------------------- | --------------------------------------------------------- |
+| Business identity and lifecycle | Entity, model, domain service, state transitions            | —                                                         |
+| Authorization                   | Common authentication infrastructure                        | Admin role/action guards; Web owner scope                 |
+| HTTP contract                   | Controller/module ownership and generated-contract workflow | Operation names, request DTOs, response DTOs              |
+| Query semantics                 | Instance scope and domain persistence                       | Operational query capability; customer-visible predicates |
+| Frontend state                  | Generated API contract and domain terminology               | Admin resource owner; Web self-service model              |
+| User interface                  | Shared frontend framework and routing system                | `presetResource` Admin page; purpose-built Web page       |
+
+Do **not** duplicate a persistence model merely because Admin and Web read the domain differently. Conversely, do **not** force a customer experience through the Admin Resource contract merely because both consumers refer to the same rows.
+
+A useful default is:
+
+- **Admin:** preserve the conventional Resource actions `select` and `view`; add `create`, `update`, and `delete` only when the operators truly own those mutations.
+- **Web:** use explicit self-service names such as `mine` and `viewMine`; the service derives ownership from the authenticated user.
+
+This makes the contract self-describing. An unqualified `view` remains the operational Resource action, while `viewMine` communicates a different authority and query scope.
+
+## Specimen: one Order domain, two read contracts
+
+The Cabloy Basic Commerce Order controller is a read-only Admin Resource plus a customer self-service surface:
+
+```text
+Order domain
+├── Admin Resource
+│   ├── GET /order           → select
+│   └── GET /order/:id       → view
+└── Web self-service
+    ├── GET /order/mine      → mine
+    └── GET /order/viewMine/:id → viewMine
+```
+
+See the controller in [order.ts](https://github.com/cabloy/cabloy/blob/main/vona/src/suite/a-commerce/modules/commerce-trade/src/controller/order.ts).
+
+The controller uses `@Resource()` so the ordinary `select` and `view` actions participate in the Admin Resource contract. They use `@Passport.systemAdmin()` because they are operational reads. The `mine` and `viewMine` actions remain separate customer-facing operations; they do not inherit the Admin action guard.
+
+A read-only Resource is a first-class shape. Registering `select` and `view` does not require pretending that operators may create, update, or delete an immutable business record such as an Order.
+
+### Navigation is not authorization
+
+An Admin SSR menu can point to `presetResource` and declare a `systemAdmin` role. That controls navigation disclosure and selects the generic Resource UI. It does **not** authorize the API action.
+
+Likewise, a protected Web route can provide browser admission and redirect behavior, but it does not replace backend owner scope or controller authorization.
+
+Keep these boundaries separate:
+
+1. menu and route metadata decide whether and how a user reaches a page;
+2. controller guards decide whether a caller may invoke an operation;
+3. service/model query scope decides which records that operation can observe.
+
+For menu behavior, see [Menu Guide](/backend/menu-guide). For route admission, see [Navigation Guards Guide](/frontend/navigation-guards-guide).
+
+## Make DTOs audience-specific projections
+
+An entity is a persistence shape, not a promise to every API consumer. Use operation-specific DTOs for each audience.
+
+In the Order specimen, the Admin Resource uses a query/list/view family:
+
+- `DtoOrderSelectReq`
+- `DtoOrderSelectResItem`
+- `DtoOrderSelectRes`
+- `DtoOrderView`
+
+These contracts can expose the operational projection and the metadata that generic Admin list and entry pages require.
+
+The customer surface uses a deliberately narrow family:
+
+- `DtoOrderMineReq`
+- `DtoOrderMineRes`
+- `DtoOrderSummary`
+- `DtoOrderDetail`
+
+For example, the customer summary has only the stable list information needed by the customer experience: identity, customer-visible state, currency, payable total, and creation time. It does not expose `userId`, instance information, correlation identifiers, or Admin page metadata.
+
+The detail projection can include customer-relevant immutable snapshots, such as the purchase address and order lines, without becoming an alias for the entire persisted row.
+
+### Keep request authority on the server
+
+A self-service request DTO may expose useful page controls such as a visible state filter, date filter, sort, `pageNo`, and `pageSize`. It must not let the caller supply the authoritative owner identity or tenant/instance boundary.
+
+In the Order specimen, `DtoOrderMineReq` derives from `$Dto.queryPage(...)`, but it only permits customer-safe filters. The service obtains the user id from the current Passport and adds it to the query itself.
+
+This distinction is essential:
+
+```text
+Web request:  permitted filter and paging intent
+Service:      authoritative owner and visible-state predicates
+Model/ORM:    normal active-instance scope
+```
+
+See [DTO Guide](/backend/dto-guide) for operation DTO design and [Multi-Instance and Instance Resolution](/backend/multi-instance-and-instance-resolution) for the normal instance boundary.
+
+## Put ownership and visibility inside the paged query
+
+Self-service visibility is a query rule, not a presentation cleanup step.
+
+The Order service uses `selectAndCount(...)` to apply all of these before the database calculates the count or page:
+
+- the owner derived from `currentUser`;
+- the customer-visible order states;
+- permitted caller filters;
+- deterministic default ordering.
+
+Conceptually:
+
+```typescript
+const result = await model.order.selectAndCount({
+  ...params,
+  where: {
+    ...params?.where,
+    userId: currentUser.id,
+    state: customerVisibleStates,
+  },
+  orders: params?.orders ?? [['id', 'desc']],
+});
+```
+
+The order of responsibility matters:
+
+1. accept only the DTO's permitted filtering intent;
+2. overwrite authoritative constraints such as owner and allowed states;
+3. let the scoped model execute count, ordering, offset, and limit together;
+4. map the result to the Web projection.
+
+Do not load a broad result, paginate it, and then remove foreign or unavailable rows in memory. That produces incorrect `total` and `pageCount`, can make pages unexpectedly empty, and risks exposing data before filtering.
+
+For a single record, include the owner in the lookup itself. A foreign record should normally be absent from the caller's scoped result; do not use a cross-instance probe merely to change absence into a distinguishable authorization response.
+
+See [ORM Select Guide](/backend/orm-select-guide) for query and projection behavior.
+
+### Pagination is one contract across layers
+
+A list is not genuinely paginated until all of these agree:
+
+1. the request DTO derives from `$Dto.queryPage(...)`;
+2. the response DTO derives from `$Dto.listAndCount(...)`;
+3. the service applies audience scope before `selectAndCount(...)`;
+4. the generated SDK describes the list-and-count result;
+5. the frontend model includes the varying query input in its query key;
+6. the page consumes `list`, `pageNo`, `pageSize`, `total`, and `pageCount` consistently.
+
+The Order Web page demonstrates the final step by requesting `{ pageNo, pageSize }`, rendering `data.list`, and changing pages from the returned `pageCount`.
+
+## Admin frontend: let the Resource owner stay the owner
+
+For an operational Admin surface, the generic Resource infrastructure is usually the right page architecture.
+
+The Order specimen has an SSR menu entry whose `presetResource` target identifies `commerce-trade:order`. Generic Admin Resource pages then consume the backend's Resource metadata, permission surface, schemas, table behavior, and read actions.
+
+The module-level `ModelOrder` is intentionally thin:
+
+```typescript
+@Use({ beanFullName: 'rest-resource.model.resource' })
+protected get $$modelResource(): ModelResource {
+  return usePrepareArg('commerce-trade:order', true);
+}
+
+select(query?: Record<string, unknown>) {
+  return this.$$modelResource.select(query);
+}
+```
+
+This is not a second Admin cache tree. `ModelResource` remains the selector-scoped owner of resource bootstrap, permissions, schemas, query state, and invalidation policy. The thin facade is useful only when it gives the module a clearer semantic boundary while preserving the generic Resource surface.
+
+Use this path when the Admin experience is mainly:
+
+- schema-driven list, filter, view, form, or action behavior;
+- conventional Resource permissions and metadata;
+- operational work that benefits from generic page infrastructure.
+
+For the underlying owner pattern, read [Model Resource Owner Pattern](/frontend/model-resource-owner-pattern), [Using `ModelResource` in Your Module](/frontend/model-resource-usage-guide), and [Resource Model Best Practices and Anti-Patterns](/frontend/model-resource-best-practices).
+
+## Web frontend: use a dedicated self-service model when semantics diverge
+
+A customer order page is not a smaller Admin table. It has different API names, customer-safe projections, owner scope, interaction flow, and presentation requirements.
+
+The Order specimen therefore uses `ModelOrderMine` for `mine` and `viewMine`, alongside purpose-built orders-list and order-detail page controllers. The dedicated model owns query state for those self-service operations:
+
+```typescript
+mine(query) {
+  return this.$useStateData({
+    queryKey: ['mine', query],
+    queryFn: () => this.scope.api.commerceTradeOrder.mine({ query }),
+  });
+}
+```
+
+This does not violate the Admin Resource owner rule. The two model boundaries own different state domains:
+
+| Model                                | Owns                                                                     |
+| ------------------------------------ | ------------------------------------------------------------------------ |
+| Admin `ModelOrder` → `ModelResource` | Admin Resource `select`/`view`, schemas, permissions, generic page state |
+| Web `ModelOrderMine`                 | Customer `mine`/`viewMine` queries and customer-page state               |
+
+Use a dedicated Web model and pages when the self-service contract is genuinely different. Do not create a parallel cache owner merely because an Admin endpoint needs a small domain-specific helper; keep such Admin helpers as thin facades over the existing Resource owner instead.
+
+For model-owned remote state and query keys, see [Model State Guide](/frontend/model-state-guide).
+
+## Private Web SSR needs explicit admission and hydration boundaries
+
+Private customer data must not appear in server HTML when the SSR path cannot establish the customer's authenticated state. The Order specimen keeps a neutral shell through server render and hydration-time initial render, then begins private queries only at an explicit client-side boundary.
+
+The required layers work together:
+
+1. **Route admission** uses the appropriate protected-route metadata for browser navigation.
+2. **Backend contract enforcement** uses controller guards and service-level owner scope as the authoritative data boundary.
+3. **Model gating** avoids creating the private query until the browser runtime and authenticated Passport are available.
+4. **Page gating** keeps the same neutral shell until the page reaches its post-hydration admission boundary.
+5. **Query behavior** may use `disableSuspenseOnInit: true` where appropriate, but that flag only disables the initialization-time suspense kick.
+
+Do not treat `disableSuspenseOnInit` as proof that a query cannot be created, fetched, or affect hydration. It is not an authorization mechanism or a substitute for an explicit hydration boundary.
+
+For the full review criteria, see [SSR Review Checklist](/frontend/ssr-review-checklist), [SSR Init Data](/frontend/ssr-init-data), and [`$useStateData` Best Practices](/frontend/use-state-data-best-practices).
+
+## Follow the forward contract loop
+
+Changing audience-specific backend contracts is a forward-chain change.
+
+Use this order:
+
+1. change Vona controller and DTO contract truth first;
+2. inspect the emitted OpenAPI surface, including every Admin and Web operation;
+3. keep the Zova module's operation ownership explicit;
+4. regenerate generated SDK, schema, and type consumers;
+5. adapt thin Admin facades or dedicated Web models to the generated API;
+6. do not hand-edit generated API clients or types.
+
+The Order module owns its four operations—`select`, `view`, `mine`, and `viewMine`—through its OpenAPI configuration. That is the appropriate place to constrain the generated module contract slice.
+
+Read [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk) for the forward-chain bridge and [Contract Loop Playbook](/fullstack/contract-loop-playbook) for generation, consumer drift, reverse-chain, and local dependency-drift decisions.
+
+## Verification checklist
+
+Review this pattern at the boundaries where an accidental merge would matter:
+
+- [ ] Admin Resource permissions expose exactly the operational actions intended; a read-only resource does not accidentally gain mutation actions.
+- [ ] Admin `select` and `view` enforce their controller authorization independently of menu visibility.
+- [ ] Web list and detail derive ownership server-side and treat foreign or cross-instance records as absent.
+- [ ] Web visibility predicates are applied before count, ordering, and pagination.
+- [ ] Web request and response projections contain no owner, tenant, or operational-only data.
+- [ ] Generated contract output contains every intended Admin and Web operation, and frontend consumers use it without manual generated-file edits.
+- [ ] The Admin menu reaches the intended `presetResource` entry and generic Resource page.
+- [ ] Web SSR and hydration render the same neutral private-data shell until admission; post-hydration behavior is tested separately.
+- [ ] Where the domain has a meaningful customer journey, targeted browser coverage proves the authenticated list/detail flow as well as access denial.
+
+Use [Unit Testing](/backend/unit-testing) for backend test conventions and [SSR Review Checklist](/frontend/ssr-review-checklist) for SSR-specific checks.
+
+## Anti-patterns
+
+Avoid these shortcuts:
+
+### One broad endpoint with role-dependent response shapes
+
+Do not make `view(id)` return a full operational row for an Admin and a reduced customer row for someone else. The contract, authorization, cache semantics, and generated types become ambiguous. Use distinct operations and DTOs.
+
+### Post-pagination ownership filtering
+
+Do not query broad rows, page them, and then filter for owner or state in memory. Scope the database query first.
+
+### Navigation as authorization
+
+Do not rely on `@SsrMenu` roles or frontend `requiresAuth` to secure an API. They affect navigation and admission only; backend operations must enforce authority and data scope themselves.
+
+### Generic Admin page as a customer experience
+
+Do not use `presetResource` just because a customer page happens to list resource rows. Customer-oriented layout, detail, pagination, and actions often deserve purpose-built pages.
+
+### Competing resource cache ownership
+
+Do not create another Admin resource model/cache owner when the custom Admin operation still belongs to the same Resource boundary. Reuse `ModelResource` through a thin facade. Create a separate model only for a genuinely distinct self-service state domain.
+
+### Hydration flags as privacy controls
+
+Do not assume a suspense or rendering flag prevents private data loading. Use explicit server, browser, authentication, and post-hydration boundaries.
+
+### Hand-patched generated contracts
+
+Do not fix a changed backend operation by editing generated frontend API or type files. Repair contract truth and regenerate the owned SDK slice.
+
+## Decision rule
+
+When one business resource serves Admin and Web users:
+
+> Share domain persistence and lifecycle logic. Split API contracts, DTO projections, query authority, frontend state ownership, and page architecture wherever the audiences have different authority or experience.
+
+Use Admin `select`/`view` with the generic Resource owner for conventional operations. Use explicit Web self-service operations and dedicated Web state/pages when customer scope and UX diverge.
+
+## Read next
+
+- [Backend Resource/Module Contract Chain](/backend/backend-resource-module-contract-chain)
+- [Menu Guide](/backend/menu-guide)
+- [ORM Select Guide](/backend/orm-select-guide)
+- [Model Resource Owner Pattern](/frontend/model-resource-owner-pattern)
+- [Resource Model Best Practices and Anti-Patterns](/frontend/model-resource-best-practices)
+- [SSR Review Checklist](/frontend/ssr-review-checklist)
+- [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
+- [Contract Loop Playbook](/fullstack/contract-loop-playbook)

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

@@ -226,7 +226,7 @@ That means:
 - use **thin model facades** as semantic wrappers over generated APIs
 - **reuse the existing resource-owner** when the custom API still belongs to an existing resource
 
-For resource-bound custom endpoints, prefer `rest-resource.model.resource` as the state owner. A module-local model may still exist, but it should remain a semantic facade instead of becoming a second cache owner.
+For resource-bound custom endpoints, prefer `rest-resource.model.resource` as the state owner. A module-local model may still exist, but it should remain a semantic facade instead of becoming a second cache owner. When Admin Resource consumption and Web self-service consumption have genuinely different API, scope, projection, or SSR semantics, see [Admin Resource and Web Self-Service](/fullstack/admin-resource-and-web-self-service) for the boundary between Admin owner reuse and a dedicated Web model.
 
 See the downstream pattern in `.claude/skills/cabloy-contract-loop/references/resource-custom-state-pattern.md`.