@starci/hfs 4.2.12 → 4.2.14

package/runtime/knowledge/patterns/be/event-bus.yaml

@@ -283,3 +283,18 @@ files:
     role: "The consumed event's e2e flow; titles event-bus/<scenario>: ... prove the pattern."
     spec: event-bus/atomic-with-transaction, event-bus/relay-only-after-commit, event-bus/redelivery-then-dead-letter, event-bus/duplicate-delivery-is-a-noop
     rules: [BE_PATTERN_SPEC_MISSING]
+# Edition lite (owner ruling 2026-10-12, R212 case-1): the same ports and rules, a Supabase adapter behind them.
+liteAdapter:
+  summary: >-
+    Under lite the event bus keeps typed events, the vendored contract, publish(event, tx) in the domain transaction, the outbox,
+    the inbox and thin consumers; Kafka is replaced by pgmq-backed topics, or by in-process delivery after commit for a back end
+    with a single api app.
+  ports:
+    - {port: EventPublisher (platform/event-bus), adapter: the same outbox row in the domain transaction}
+    - {port: relay, adapter: "fans each committed event out with pgmq.send to one queue per consumer group of its topic, marking the row in the same transaction"}
+    - {port: EventConsumer (platform/event-bus), adapter: "pgmq.read with a visibility timeout, the inbox claim on the event id, pgmq.delete on success, pgmq.archive as the dead letter"}
+  forbids: [kafkajs]
+  proof: >-
+    Unit specs as full; the event-bus/* scenarios are optional integration specs on `starci supabase start`, and there is no e2e
+    async spec (R155 and R167 are full's).
+  see: [knowledge/patterns/be/supabase-queues.yaml]

package/runtime/knowledge/patterns/be/jobs.yaml

@@ -259,3 +259,13 @@ files:
     role: "Titles fenced-job/<scenario>: ... prove the pattern."
     spec: fenced-job/claim-bumps-token, fenced-job/zombie-fenced-out, fenced-job/redispatch-isolated
     rules: [BE_PATTERN_SPEC_MISSING]
+# Edition lite (owner ruling 2026-10-12, R212 case-1): the same ports and rules, a Supabase adapter behind them.
+liteAdapter:
+  summary: >-
+    Under lite a fenced job is unchanged: the job row with its fencing token, the atomic claim, guarded writes and run keys. The
+    row's table is a supabase migration, and the processor is fed by the lite queue (pgmq).
+  ports:
+    - {port: job claim (platform/jobs), adapter: "the same claim SQL through the shared EntityManager; the table comes from supabase/migrations"}
+    - {port: processor delivery, adapter: "the lite queue worker (pgmq.read, visibility timeout, archive on dead letter)"}
+  proof: Unit specs as full (job-claim.service.spec.ts); the fenced-job/* scenarios are optional integration specs on `starci supabase start`.
+  see: [knowledge/patterns/be/supabase-queues.yaml]

package/runtime/knowledge/patterns/be/projections.yaml

@@ -176,3 +176,13 @@ files:
     role: "Titles projection/<scenario>: ... prove the pattern."
     spec: projection/recompute-is-idempotent, projection/replay-rebuilds
     rules: [BE_PATTERN_SPEC_MISSING]
+# Edition lite (owner ruling 2026-10-12, R212 case-1): the same ports and rules, a Supabase adapter behind them.
+liteAdapter:
+  summary: >-
+    Under lite a projection is unchanged in behaviour (only it writes its table, recompute is idempotent and replayable, readers
+    use get*); its table is a supabase migration with a rows type, so the slot carries no projection entity (be.projections lite
+    overlay), and it is kept current by a reactor or a job on the lite transport.
+  ports:
+    - {port: read model table, adapter: "a supabase migration plus <name>.sql.ts and <name>.rows.ts under persistence/"}
+  proof: Unit specs as full (the projection is a logic role at 100 per file); the projection/* scenarios are optional integration specs.
+  see: [knowledge/patterns/be/supabase-queues.yaml]

package/runtime/knowledge/patterns/be/queues.yaml

@@ -234,3 +234,18 @@ files:
     role: "Titles queue/<scenario>: ... prove the pattern."
     spec: queue/enqueue-atomic-with-transaction, queue/relay-job-id-is-outbox-id, queue/scheduler-fires-once
     rules: [BE_PATTERN_SPEC_MISSING]
+# Edition lite (owner ruling 2026-10-12, R212 case-1): the same ports and rules, a Supabase adapter behind them.
+liteAdapter:
+  summary: >-
+    Under lite the queue pattern is unchanged above the port (producers, the outbox written in the caller's transaction, processors,
+    schedulers declared with their queue) and its transport is Supabase Queues (pgmq) instead of BullMQ and Redis.
+  ports:
+    - {port: QueueOutbox (platform/queue), adapter: the same outbox row written through the caller's tx; nothing changes}
+    - {port: queue transport (queue-transport.port.ts), adapter: "pgmq-queue-transport.client.ts: pgmq.send through the shared EntityManager, the outbox id inside the message"}
+    - {port: QueueWorkerRegistry (platform/queue), adapter: "a poll loop per queue: pgmq.read with the policy's visibility timeout, pgmq.delete on success, pgmq.set_vt for backoff, pgmq.archive when read_ct exceeds the attempts"}
+    - {port: schedulers, adapter: "a pg_cron job declared in a supabase migration that calls pgmq.send; no BullMQ job scheduler"}
+  forbids: [bullmq, "@nestjs/bullmq", redis, ioredis, "@nestjs/schedule"]
+  proof: >-
+    Unit specs as full (queue-outbox, relay and worker services, the pgmq client against mockEntityManager); the queue/* scenarios are
+    optional integration specs on `starci supabase start` (R155 is full's).
+  see: [knowledge/patterns/be/supabase-queues.yaml]

package/runtime/knowledge/patterns/be/reactors.yaml

@@ -138,3 +138,11 @@ files:
   - path: src/tests/e2e/<area>/<event>.e2e-spec.ts
     slot: be.tests.e2e
     role: The reactor's event flow through the bus, redelivery included.
+# Edition lite (owner ruling 2026-10-12, R212 case-1): the same ports and rules, a Supabase adapter behind them.
+liteAdapter:
+  summary: >-
+    Under lite a reactor is unchanged: a thin consumer of another context's events that dispatches one command. Its deliveries
+    come from the lite event bus (its own pgmq queue per consumer group).
+  ports:
+    - {port: EventConsumer delivery, adapter: "the reactor's pgmq queue (see event-bus.yaml liteAdapter)"}
+  see: [knowledge/patterns/be/supabase-queues.yaml]

package/runtime/knowledge/patterns/be/realtime.yaml

@@ -207,3 +207,20 @@ files:
     spec: realtime/subscriber-receives-push, realtime/foreign-topic-is-isolated, realtime/disconnect-releases-subscription
     rules: [BE_PATTERN_SPEC_MISSING]
     optional: true
+# Edition lite (owner rulings 2026-10-12 and 2026-10-13, R212 cases 1-2): the same ports, door and rules; one instance behind them.
+liteAdapter:
+  summary: >-
+    Under lite the realtime pattern is the full one: the socket.io gateway of be.feature.realtime.websocket
+    (transport/websocket/<channel>.gateway.ts) runs inside the be api process, one instance with the default in-memory adapter
+    and no Redis adapter. A reactor publishes to the RealtimeHub of platform/realtime, which emits to the principal-scoped room
+    of the namespace; the front end listens through hooks/socketio (knowledge/patterns/fe/realtime.yaml). graphql-ws
+    subscriptions are not used in lite.
+  ports:
+    - {port: RealtimeHub.publish (platform/realtime), adapter: "the socket.io server of the api process emits to the namespace room of the topic (no Redis adapter: one instance)"}
+    - {port: RealtimeHub.subscribe, adapter: "the gateway's @SubscribeMessage handler joins the room built from the principal, as full"}
+    - {port: topic scope, adapter: "the room name built from @CurrentPrincipal (BE_REALTIME_TOPIC_SCOPE), as full"}
+  forbids: [redis, ioredis, "@socket.io/redis-adapter", graphql-ws, graphql-subscriptions]
+  proof: >-
+    The gateway's own unit spec (<channel>.gateway.spec.ts) and the hub adapter's spec, as full; the realtime/* scenarios are
+    optional integration specs on `starci supabase start` (lite has no e2e).
+  see: [knowledge/patterns/be/supabase-queues.yaml, knowledge/patterns/fe/realtime.yaml]

package/runtime/knowledge/patterns/be/saga.yaml

@@ -246,3 +246,16 @@ rules:
       manual:
         - Check the injected fault hits the compensation, not only the step before it.
     relatedExamples: [saga]
+# Edition lite (owner ruling 2026-10-12, R212 case-1): the same ports and rules, a Supabase adapter behind them.
+liteAdapter:
+  summary: >-
+    Under lite a saga is unchanged: the orchestrator service, the versioned state behind the fenced store, steps and their
+    compensations, and consumers advancing it through the inbox. Its events travel on the lite event bus (pgmq queues per
+    consumer group).
+  ports:
+    - {port: saga events, adapter: "the lite event-bus adapter (pgmq) - see event-bus.yaml liteAdapter"}
+    - {port: saga state store, adapter: "the same table and version fence, created by a supabase migration (no TypeORM entity under lite)"}
+  proof: >-
+    The orchestrator's unit spec (<saga>.saga.service.spec.ts) as full; the e2e compensation specs of R173 are full's, so a lite
+    saga proves each compensation in the orchestrator's unit spec and, optionally, an integration spec on `starci supabase start`.
+  see: [knowledge/patterns/be/supabase-queues.yaml]

package/runtime/knowledge/patterns/fe/folder.yaml

@@ -29,8 +29,11 @@ rules:
       `hfs.json` `sides.fe.apps` with kind `next` (slot `fe.app.next`; the scaffold writes `landing` and `app`) — and all
       product source lives under fe/apps/<app>/src. An fe/src/ does not exist. Each Next source root
       (fe/apps/<app>/src) uses app/ for framework adapters; features/{pages,layouts,overlays} for route-facing product
-      composition; components/{blocks,composites,branches,leaves} for product visuals; hooks/<domain> for React hooks;
-      and modules/<capability> for cohesive reusable technical and domain capabilities. Every app carries the required
+      composition; components/{blocks,composites,branches,leaves} for product visuals and components/providers for the
+      client providers the root layout mounts; hooks/ for React hooks (swr, rhf, zustand, socketio, effects, reuseables and
+      <domain>); redux/ for the app-wide store; and modules/<capability> for cohesive reusable technical and domain
+      capabilities (api, auth, toast, i18n, config, routes, brand, types, storage, superjson, dayjs, utils). Each concern's
+      library and home is knowledge/hfs/fe-stack.yaml. Every app carries the required
       module instances of slot `fe.modules` and one brand.css under modules/brand when it sets brand tokens
       (`fe.modules.brand`). No other empty role
       folder is required. Grammar remains a separate product-agnostic package. The only files that may sit directly in the
@@ -78,9 +81,10 @@ rules:
         when: "A routed authentication scenario"
         write: "fe/apps/<app>/src/features/pages/AuthenticationPage/index.tsx"
       - id: case-2
-        when: "A reusable API client, reader or session capability"
+        when: "A back-end call or the session"
         write: >
-          fe/apps/<app>/src/modules/api/ or fe/apps/<app>/src/modules/session/ with one explicit public index.ts entry
+          slot fe.modules.api (one file per query or mutation) or slot fe.modules.auth, each with one explicit public index.ts
+          entry
       - id: case-3
         when: "A reusable product visual without scenario ownership"
         write: "an owner folder of slot `fe.components` under the layer it belongs to — for example fe/apps/<app>/src/components/leaves/<Name>/index.tsx"
@@ -257,7 +261,7 @@ rules:
         when: "Global app files"
         write: >
           app/globals.css, app/global-error.tsx, app/[locale]/error.tsx, app/[locale]/not-found.tsx, app/sitemap.ts,
-          app/robots.ts, app/health/{live,ready}/route.ts
+          app/robots.ts, app/health/live/route.ts (the one route handler, FE-ROUTE)
     verification:
       automated:
         - FE_ERROR_BOUNDARY_MISSING
@@ -287,33 +291,35 @@ rules:
     relatedExamples: []
 
   - id: FE-FOLDER-4
-    title: Hooks are hooks; readers and transport live in modules
+    title: Hooks are hooks; operations and transport live in modules
     kind: mandatory
     hfsRules: [R56, R50, R49, R21, R26]
     requirement: |
-      hooks/<domain>/ holds React hooks (use*.ts, one hook per file) and exactly one <domain>.shared.ts for shared
-      non-hook helpers of that domain (key builders, token readers). A file in hooks/ that is not a hook and is not the shared
-      file is a finding. Server-side readers (fetch and map, no React) live in modules/api/<domain>/read-*.ts and are
-      wrapped in React cache() when several blocks call them in one request. Generic client plumbing, the Outcome type,
-      the generated wire types (from be/contracts/, through the root codegen) live in modules/api; environment reading lives in modules/config; every
-      href builder lives in modules/routes; locale routing lives in modules/i18n; colour values live in modules/brand.
+      hooks/ holds React hooks (use*.ts, one hook per file): hooks/swr (one SWR wrapper per modules/api operation, plus
+      SwrSideEffects.tsx), hooks/rhf (forms), hooks/zustand/<store> (a store and its hooks), hooks/socketio (sockets.ts,
+      SocketIoSideEffects.tsx, enums/, types/), hooks/effects (app-wide side effects), hooks/reuseables (generic hooks) and
+      hooks/<domain>/ with exactly one <domain>.shared.ts for shared non-hook helpers of that domain. A file in hooks/ that is
+      none of these is a finding. The Apollo clients and their links, one file per query and mutation, the GraphQLResponse
+      envelope, the generated wire types (from be/contracts/, through the root codegen) and the axios calls live in
+      modules/api; the session lives in modules/auth; mutation feedback in modules/toast; environment reading in
+      modules/config; every href builder in modules/routes; locale routing in modules/i18n; colour values in modules/brand.
       A helper name defined twice across hook files is a finding.
     rationale: |
       A rule that says what a hooks folder is also says where everything else goes, so nobody copies a helper sixteen
-      times or fills hooks/ with server fetch functions.
+      times or fills hooks/ with transport calls.
     cases:
       - id: case-1
-        when: "Authentication request lifecycle"
-        write: "fe/apps/<app>/src/hooks/authentication/useAuthentication.ts"
+        when: "A query the sales page reads"
+        write: "fe/apps/<app>/src/hooks/swr/api/graphql/queries/useQuerySalesSummarySwr.ts over modules/api/graphql/queries/query-sales-summary.ts"
       - id: case-2
         when: "A helper shared by the hooks of one domain"
         write: "fe/apps/<app>/src/hooks/sales/sales.shared.ts, for example useSalesAccessToken's token reader"
       - id: case-3
-        when: "A server read used by several blocks"
-        write: "fe/apps/<app>/src/modules/api/sales/read-sales-summary.ts, exported through modules/api/index.ts"
+        when: "A form"
+        write: "fe/apps/<app>/src/hooks/rhf/useSendHandoffForm.ts"
       - id: case-4
         when: "The API client"
-        write: "fe/apps/<app>/src/modules/api/client.ts and fe/apps/<app>/src/modules/api/outcome.ts"
+        write: "fe/apps/<app>/src/modules/api/graphql/clients/ (auth and no-auth Apollo clients, links/) and fe/apps/<app>/src/modules/api/graphql/types.ts"
       - id: case-5
         when: "Intrinsic custom helper"
         write: "fe/apps/<app>/src/hooks/ui/useAutoScroll.ts; direct useRef and useState calls may remain in their visual owner"

package/runtime/knowledge/sonar-gate.yaml

@@ -81,13 +81,17 @@ overall:
   cognitiveComplexity:
     rule: typescript:S3776
     via: overall.issues
-# Lite is the same quality policy without a test or coverage world. Readers select this block from hfs.json edition;
-# keeping both gates in this document makes every threshold data, never a branch-local restatement.
+# Lite is the same quality policy, coverage included: a lite back end keeps full's unit run and its 100 per file on the measured
+# logic files (owner ruling 2026-10-12, R212 case-1). Readers select this block from hfs.json edition; the gate keeps its own
+# name so a lite project's server gate stays a separate object, and every threshold below equals full's.
 lite:
   gate:
     name: starci-quality-lite
     newCodePeriod: {type: NUMBER_OF_DAYS, value: 30}
   newCode:
+    coverage:
+      metric: new_coverage
+      minPercent: 100
     ignoreBelowChangedLines: 20
     duplication:
       metric: new_duplicated_lines_density
@@ -109,6 +113,10 @@ lite:
     hotspots:
       metric: security_hotspots_reviewed
       minReviewedPercent: 100
+    coverage:
+      metric: coverage
+      minPercent: 100
+      perFile: true
     duplication:
       metric: duplicated_lines_density
       maxPercent: 3

package/runtime/modules/kernel/failure-codes.yaml

@@ -862,16 +862,6 @@ FE_APP_ISOLATION:
   owner: op-retry
   kind: check-finding
 
-FE_AUTH_SESSION_TRUST:
-  title: "Server code trusts `getSession`, or a Server Action does not establish and refuse an anonymous principal"
-  title_vi: "Mã server tin getSession hoặc Server Action không xác thực principal"
-  meaning_vi: "`<path>` gọi `auth.getSession()` trên server, write action không bắt đầu bằng `await getPrincipal()`, không trả Outcome `refused` cho anonymous (trừ `fe.modules.db/auth/write-sign-in.ts` đang xác thực chính caller anonymous), hoặc mutation nhạy cảm không gọi `auth.getUser()`."
-  causes_vi:
-    - "Vi phạm L14: server dùng claims đã kiểm tra; write action xác thực principal trước mọi việc và mutation nhạy cảm kiểm tra user từ Auth server."
-  nextStep_vi: "Dùng `getPrincipal()`/`getClaims()`, từ chối anonymous bằng Outcome có kiểu, và gọi `auth.getUser()` cho tiền, bảo mật tài khoản hay đổi role."
-  owner: op-retry
-  kind: check-finding
-
 FE_BLOCK_PRODUCT_HOOK_DEFINITION:
   title: "Block defines a product hook"
   title_vi: "Khối giao diện tự định nghĩa hook sản phẩm"
@@ -889,8 +879,8 @@ FE_CLIENT_REACHES_SERVER:
   meaning_vi: "Một mô-đun có chỉ thị `\"use client\"` với tới, qua chuỗi import chạy thật (nhiều bước, không tính import chỉ-kiểu), một mô-đun import `server-only`, `next/headers`, `next/server`, `next-intl/server`, `node:*` hoặc `fs`. Lời nhắn nêu client đầu vào và cả chuỗi import."
   causes_vi:
     - "Hook hoặc module dùng chung được client component import gián tiếp lại đọc request ở máy chủ"
-    - "Reader máy chủ bị import từ đường đi của một client component thay vì chỉ từ server component"
-  nextStep_vi: "Op vừa tạo ra bản này sẽ được chạy lại để đọc dữ liệu ở server component và truyền xuống bằng props, hoặc đưa import ra khỏi đồ thị client theo lời nhắn; không thêm ngoại lệ."
+    - "Module chỉ chạy ở máy chủ bị import từ đường đi của một client component"
+  nextStep_vi: "Op vừa tạo ra bản này sẽ được chạy lại để đọc dữ liệu qua hook SWR gọi `modules/api`, hoặc đưa import ra khỏi đồ thị client theo lời nhắn; không thêm ngoại lệ."
   owner: op-retry
   kind: check-finding
 
@@ -949,36 +939,6 @@ FE_CUSTOM_HOOK_LOCATION:
   owner: other-op:interface.implement
   kind: check-finding
 
-FE_DB_ERROR_HANDLED:
-  title: "An awaited Supabase result drops `error` or collapses failure to empty data"
-  title_vi: "Kết quả Supabase bỏ qua error hoặc gộp lỗi thành dữ liệu rỗng"
-  meaning_vi: "Kết quả await ở `<path>` không đọc `error`, không được truyền nguyên vẹn vào `toOutcome`, hoặc dùng `data ?? []` nên `refused`/`unavailable` biến thành dữ liệu rỗng."
-  causes_vi:
-    - "Vi phạm L12: mọi `{data,error}` đi qua một Outcome có kiểu; không destructure chỉ data và không nuốt lỗi."
-  nextStep_vi: "Đọc và ánh xạ `error`, hoặc truyền toàn bộ result vào `toOutcome(result)` rồi xử lý đủ các nhánh Outcome."
-  owner: op-retry
-  kind: check-finding
-
-FE_DB_RESULT_TYPED:
-  title: "A Supabase result is cast, explicitly generic, or an unbounded list read"
-  title_vi: "Kết quả Supabase bị ép kiểu hoặc truy vấn danh sách không giới hạn"
-  meaning_vi: "Truy vấn ở `<path>` dùng generic trên `single/maybeSingle/returns`, ép kiểu/non-null assertion, hoặc đọc danh sách không có `limit` hay biên keyset."
-  causes_vi:
-    - "Vi phạm L11: kiểu hàng phải suy ra từ `Database`; mọi đọc nhiều dòng phải có giới hạn tĩnh."
-  nextStep_vi: "Bỏ generic/cast/assertion, sửa type nguồn trong `database.types.ts`, và thêm `.limit()` hoặc biên keyset."
-  owner: op-retry
-  kind: check-finding
-
-FE_DB_WRITE_SHAPE:
-  title: "A Supabase Server Action uses input before schema parsing, or a write module exports no action"
-  title_vi: "Server Action dùng input trước khi schema parse"
-  meaning_vi: "Write module ở `<path>` không export Server Action, hoặc tham số được dùng trước lần gọi `schema.parse`/`schema.safeParse` đầu tiên."
-  causes_vi:
-    - "Vi phạm phần write-shape của L14: input không được tin trước validation."
-  nextStep_vi: "Export action async trong `write-*.ts` và để lần dùng input đầu tiên là `schema.parse(input)` hoặc `schema.safeParse(input)`."
-  owner: op-retry
-  kind: check-finding
-
 FE_ERROR_BOUNDARY_MISSING:
   title: "Next app lacks a required error or loading boundary"
   title_vi: "Ứng dụng Next thiếu trang lỗi hoặc trang đang tải bắt buộc"
@@ -1004,9 +964,9 @@ FE_GRAPHQL_CONTRACT:
 FE_HOOKS_ARE_HOOKS:
   title: "`hooks/` hold hooks and one shared file per domain"
   title_vi: "hooks/ chứa thứ không phải hook"
-  meaning_vi: "`<file>` trong `hooks/` không phải React hook, hoặc một domain có nhiều hơn một tệp `.shared.ts` (hay tệp shared không mang tên domain), hoặc một helper được khai báo ở nhiều tệp của domain. Reader server về `modules/api`, helper về `<domain>.shared.ts`."
+  meaning_vi: "`<file>` trong `hooks/` không phải React hook, hoặc một domain có nhiều hơn một tệp `.shared.ts` (hay tệp shared không mang tên domain), hoặc một helper được khai báo ở nhiều tệp của domain. Hàm gọi mạng về `modules/api`, helper về `<domain>.shared.ts`."
   causes_vi:
-    - "Vi phạm luật R56: `hooks/<domain>/` chỉ chứa `use*.ts` và một `<domain>.shared.ts` cho helper dùng chung; reader server nằm ở `modules/api/<domain>/read-*.ts` (bọc `cache()`)."
+    - "Vi phạm luật R56: `hooks/` chỉ chứa hook: `hooks/swr` (mỗi operation của `modules/api` một hook SWR), `hooks/rhf`, `hooks/zustand/<store>`, `hooks/socketio`, `hooks/effects`, `hooks/reuseables` và `hooks/<domain>/` với một `<domain>.shared.ts` cho helper dùng chung."
   nextStep_vi: "Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra (nợ hàng loạt có codemod của HFS); không cần ai can thiệp thêm."
   owner: op-retry
   kind: check-finding
@@ -1175,12 +1135,12 @@ FE_ROUTE_FILES_THIN:
   kind: check-finding
 
 FE_ROUTE_HANDLER_FORBIDDEN:
-  title: "A front-end route handler is not health/live or the Supabase auth callback slot"
+  title: "A front-end route handler is not health/live or the auth callback slot"
   title_vi: "Route handler phía front end không thuộc hai cửa được phép"
-  meaning_vi: "`<path>` là `route.ts` phía fe nhưng không phải `health/live` và không thuộc ô `fe.route.callback`."
+  meaning_vi: "`<path>` là `route.ts` phía fe nhưng không phải `app/health/live/route.ts` và không thuộc ô `fe.route.callback`; front end của mọi app không phục vụ API."
   causes_vi:
-    - "Vi phạm L15: webhook, cron, public API và callback bên thứ ba là feature của back end."
-  nextStep_vi: "Chuyển handler sang feature back end; chỉ giữ health/live và callback PKCE trong ô `fe.route.callback`."
+    - "Vi phạm luật R243: front end không có route handler nào ngoài health/live và callback auth; webhook, cron, public API và callback bên thứ ba là feature của back end, dữ liệu đi qua `modules/api` và hook SWR."
+  nextStep_vi: "Chuyển handler sang feature back end (GraphQL cho front end, REST cho webhook/public/OAuth) và gọi nó từ `modules/api`; chỉ giữ health/live và callback trong ô `fe.route.callback`."
   owner: op-retry
   kind: check-finding
 
@@ -1195,6 +1155,16 @@ FE_ROUTE_ONE_PAGE:
   owner: other-op:interface.implement
   kind: check-finding
 
+FE_SERVER_ACTION_FORBIDDEN:
+  title: "A front-end file carries a `\"use server\"` directive"
+  title_vi: "Front end có Server Action (\"use server\")"
+  meaning_vi: "`<path>` mang chỉ thị `\"use server\"` (ở đầu module hoặc trong một hàm); front end của mọi app không có Server Action."
+  causes_vi:
+    - "Vi phạm luật R243: front end gọi back end qua mutation GraphQL trong `modules/api/graphql/mutations` bọc bởi hook `useMutate*Swr`, kết quả báo bằng `modules/toast` (R212 case-2)."
+  nextStep_vi: "Xoá Server Action, thêm mutation GraphQL ở back end và `mutation-<x>.ts` trong `modules/api`, gọi qua `useMutate<X>Swr` và `useGraphQLWithToast`; việc nặng là mutation đưa job vào hàng đợi rồi theo dõi bằng status query hoặc socket."
+  owner: op-retry
+  kind: check-finding
+
 FE_SERVICE_ROLE_FORBIDDEN:
   title: "A service-role or credential-shaped environment value enters the front end"
   title_vi: "Service role hoặc biến môi trường bí mật đi vào front end"
@@ -1226,13 +1196,23 @@ FE_SOURCE_LAYOUT_INVALID:
   owner: other-op:interface.implement
   kind: check-finding
 
+FE_STACK_FORBIDDEN:
+  title: "A front end depends on or imports a package that knowledge/hfs/fe-stack.yaml forbids"
+  title_vi: "Front end dùng thư viện bị fe-stack cấm"
+  meaning_vi: "`<path>` khai báo phụ thuộc hoặc import `<package>`, thư viện nằm trong `forbids` của concern `<concern>` trong knowledge/hfs/fe-stack.yaml; mỗi concern chỉ có một thư viện chuẩn."
+  causes_vi:
+    - "Vi phạm luật R244: front end dùng đúng thư viện chuẩn của từng concern trong fe-stack.yaml (phiên bản ở canon-pins.yaml), không cài thư viện thay thế bên cạnh."
+  nextStep_vi: "Gỡ `<package>` khỏi package.json và thay import bằng thư viện chuẩn của concern đó; nếu cần một concern mới, thêm nó vào fe-stack.yaml và canon-pins.yaml trước."
+  owner: op-retry
+  kind: check-finding
+
 FE_SUPABASE_CLIENT_OWNER:
-  title: "A front-end Supabase client, import or call is outside the db owner, or is not typed with `Database`"
-  title_vi: "Supabase client phía front end sai chủ sở hữu hoặc thiếu kiểu Database"
-  meaning_vi: "Import/call Supabase ở `<path>` không thuộc ô `fe.modules.db`/`fe.package.db`, hoặc client được tạo mà không mang kiểu `Database` đã sinh."
+  title: "A front-end Supabase import or call is outside `fe.modules.auth`, or reaches past the auth API"
+  title_vi: "Supabase phía front end ngoài modules/auth hoặc dùng ngoài API auth"
+  meaning_vi: "Import/call Supabase ở `<path>` không thuộc ô `fe.modules.auth`, hoặc gọi API ngoài auth (`.from`, `.rpc`, `.storage`, `.channel`): front end không đọc hay ghi dữ liệu qua Supabase."
   causes_vi:
-    - "Vi phạm L10: chỉ các ô db được import/call `@supabase/ssr` hay `@supabase/supabase-js`; mọi client là `SupabaseClient<Database>`/`create*Client<Database>`."
-  nextStep_vi: "Chuyển factory và truy vấn vào ô db đúng của app/gói, import API công khai của ô đó, và thêm kiểu `Database`; không thêm ngoại lệ."
+    - "Vi phạm luật R217: Supabase trên front end chỉ là xác thực (đăng nhập, phiên, access token) trong `modules/auth`; dữ liệu đi qua `modules/api` (Apollo GraphQL) và hook SWR tới back end (R212 case-2)."
+  nextStep_vi: "Chuyển client Supabase vào `modules/auth` và chỉ giữ API auth; đọc/ghi dữ liệu bằng query/mutation GraphQL trong `modules/api` và hook `hooks/swr`; không thêm ngoại lệ."
   owner: op-retry
   kind: check-finding
 
@@ -1271,11 +1251,11 @@ FE_TIER_DIRECTION:
   kind: check-finding
 
 FE_TRANSPORT_OWNER:
-  title: "One `fetch`, in the repository's one transport client, with timeout and abort"
-  title_vi: "fetch ngoài client duy nhất"
-  meaning_vi: "`fetch` ở `<file>` ngoài client truyền tải duy nhất của repository (gọi, gán lại hoặc truyền như giá trị), thư viện HTTP khác được import, reader `read-*.ts` không đi qua client, repository có nhiều hơn một client hoặc nhiều hơn một union `Outcome` (mỗi app giữ một bản, hoặc gói api cộng thêm một bản của app), hoặc state dùng chung dạng `let`."
+  title: "One transport: the Apollo clients and the one axios instance of modules/api"
+  title_vi: "Gọi back end ngoài transport duy nhất"
+  meaning_vi: "`fetch` hoặc thư viện HTTP/GraphQL khác ở `<file>` ngoài transport duy nhất của repository (gọi, gán lại hoặc truyền như giá trị), repository có nhiều hơn một thư mục client hoặc nhiều hơn một envelope `GraphQLResponse` (mỗi app giữ một bản, hoặc gói api cộng thêm một bản của app), hoặc state dùng chung dạng `let` giữ token/locale."
   causes_vi:
-    - "Vi phạm luật R50: Mỗi repository đúng một client `fetch`, có timeout + `AbortSignal`: `packages/<family>-api/src/client.ts` khi các app dùng chung, hoặc `modules/api/client.ts` của app duy nhất; không singleton `let` giữ token/locale; credential truyền bằng tham số/context."
+    - "Vi phạm luật R50: Mỗi repository đúng một transport: client Apollo auth/no-auth với chuỗi link (retry, error, timeout, refresh, access token, http) trong `modules/api/graphql/clients/` của app duy nhất hoặc `packages/<family>-api/src/graphql/clients/` khi các app dùng chung, và một instance axios trong `modules/api/rest` cho upload, presigned URL và endpoint auth; component đọc qua hook `hooks/swr`."
   nextStep_vi: "Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra và mục của luật trong tiêu chuẩn HFS; nợ cũ cần quyết định thiết kế nên op không thêm ngoại lệ, chỉ tách hoặc chuyển về đúng chủ."
   owner: op-retry
   kind: check-finding
@@ -1283,9 +1263,9 @@ FE_TRANSPORT_OWNER:
 FE_WIRE_GENERATED:
   title: "Wire types generated from the be contract snapshots the fe side reads"
   title_vi: "Kiểu wire gõ tay"
-  meaning_vi: "`<file>` tự gõ kiểu wire/ép kiểu phản hồi, hoặc kiểu sinh ra cũ hơn ảnh chụp hợp đồng. Dùng kiểu sinh từ `be/contracts/`."
+  meaning_vi: "`<file>` tự gõ kiểu wire/ép kiểu phản hồi, hoặc kiểu sinh ra cũ hơn ảnh chụp hợp đồng. Dùng kiểu do graphql-codegen sinh từ `be/contracts/<app>/schema.graphql`."
   causes_vi:
-    - "Vi phạm luật R52: Kiểu wire sinh từ ảnh chụp hợp đồng của be (`be/contracts/`, chạy `starci gate run --root <app>` ở gốc app); tài liệu GraphQL trong `.graphql`; cấm `as GraphqlResult<T>`; enum wire không phải `string`."
+    - "Vi phạm luật R52: Kiểu wire do graphql-codegen sinh từ `be/contracts/<app>/schema.graphql` (đọc tại chỗ, không chép) vào `modules/api/graphql/__generated__`; kiểu request/response của mỗi operation re-export kiểu sinh; cấm ép kiểu phản hồi; enum wire không phải `string`."
   nextStep_vi: "Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra và mục của luật trong tiêu chuẩn HFS; nợ cũ cần quyết định thiết kế nên op không thêm ngoại lệ, chỉ tách hoặc chuyển về đúng chủ."
   owner: op-retry
   kind: check-finding
@@ -1892,7 +1872,7 @@ HFS_REQUIRED_FILE_MISSING:
   title_vi: "Thiếu tệp, thư mục hoặc số lượng tối thiểu bắt buộc theo bảng kê"
   meaning_vi: "Bảng kê HFS đòi một tệp hoặc thư mục phải có trong mỗi phần của kho (gói dùng chung, module frontend, api, i18n, tuyến, layout...), hoặc đòi kho có ít nhất một ứng dụng hay tính năng thuộc loại bắt buộc. Mục đó không tồn tại; khi là số lượng tối thiểu thì báo tại hfs.json. Thiếu nó thì phần liên quan chưa hoạt động đầy đủ hoặc kho chưa phải một sản phẩm hoàn chỉnh."
   causes_vi:
-    - "Tạo thư mục mới nhưng chưa thêm tệp bắt buộc như index.ts, client.ts, outcome.ts hoặc package.json"
+    - "Tạo thư mục mới nhưng chưa thêm tệp bắt buộc như index.ts, store.ts, toast.tsx hoặc package.json"
     - "Tệp có nhưng tên hoặc chỗ đặt khác với bảng kê"
     - "Kho chưa có tính năng hoặc ứng dụng nào của loại bắt buộc"
   nextStep_vi: "Op vừa tạo ra bản này sẽ được chạy lại để tạo tệp còn thiếu đúng chỗ bảng kê chỉ định; nếu cấu trúc hiện có là chủ ý thì đó là việc sửa bảng kê, do người giám sát làm, không phải kho tự đổi."

package/runtime/modules/kernel/removed-vocabulary.yaml

@@ -266,3 +266,51 @@ removed:
     use: 'probeDraft reads only and returns verdict, draft and sends; a foreign draft receives no keys'
     since: 1.0.0-alpha.9
     match: '\b(?:draftProbe|probeDraft)\.(?:restore|restored|removed|after)\b'
+  - id: code-fe-db-result-typed
+    kind: code
+    name: FE_DB_RESULT_TYPED
+    use: 'the front end reads no data through Supabase (R217, auth only in fe.modules.auth); reads are GraphQL queries of modules/api wrapped by hooks/swr, typed by graphql-codegen (R52 FE_WIRE_GENERATED)'
+    since: 1.0.0-alpha.13
+  - id: code-fe-db-error-handled
+    kind: code
+    name: FE_DB_ERROR_HANDLED
+    use: 'a failure arrives as the GraphQLResponse envelope of modules/api/graphql/types.ts and is never collapsed into empty data (R51 FE_HTTP_STATUS_COLLAPSE)'
+    since: 1.0.0-alpha.13
+  - id: code-fe-auth-session-trust
+    kind: code
+    name: FE_AUTH_SESSION_TRUST
+    use: 'the front end runs no server code that trusts a session (R243 FE_SERVER_ACTION_FORBIDDEN); the back end verifies the access token against the JWKS (R219 BE_SUPABASE_JWT_VERIFIED)'
+    since: 1.0.0-alpha.13
+  - id: code-fe-db-write-shape
+    kind: code
+    name: FE_DB_WRITE_SHAPE
+    use: 'a write is a GraphQL mutation of modules/api wrapped by a useMutate<X>Swr hook and reported by modules/toast; Server Actions are refused (R243 FE_SERVER_ACTION_FORBIDDEN)'
+    since: 1.0.0-alpha.13
+  - id: slot-fe-modules-db
+    kind: vocabulary
+    name: fe.modules.db
+    use: 'the front end reads and writes through the back end GraphQL API in fe.modules.api, wrapped by hooks/swr; Supabase on the front end is fe.modules.auth only (owner ruling 2026-10-13)'
+    since: 1.0.0-alpha.13
+    match: '\bfe\.modules\.db\b'
+  - id: slot-fe-package-db
+    kind: vocabulary
+    name: fe.package.db
+    use: 'a shared front-end data client is fe.package.api (Apollo clients and the GraphQLResponse union); Supabase on the front end is fe.modules.auth only'
+    since: 1.0.0-alpha.13
+    match: '\bfe\.package\.db\b'
+  - id: slot-be-feature-realtime-supabase
+    kind: vocabulary
+    name: be.feature.realtime.supabase
+    use: 'both editions push through the socket.io gateway be.feature.realtime.websocket; lite runs it in the api process'
+    since: 1.0.0-alpha.13
+    match: '\bbe\.feature\.realtime\.supabase\b'
+  - id: slot-key-anonymous-actions
+    kind: vocabulary
+    name: anonymousActions
+    use: 'the front end holds no Server Action (R243 FE_SERVER_ACTION_FORBIDDEN), so no slot lists anonymous ones'
+    since: 1.0.0-alpha.13
+  - id: lint-heroicons-is-the-glyph-vendor
+    kind: vocabulary
+    name: heroicons-is-the-glyph-vendor
+    use: 'the eslint-fe rule is one-icon-set: the application icon set is @phosphor-icons/react (knowledge/hfs/fe-stack.yaml icons), imported only by the Icon leaf; the grammar Icon takes whatever glyph the app supplies'
+    since: 1.0.0-alpha.13

package/runtime/scripts/hfs/architecture/client-reaches-server.mjs

@@ -1,6 +1,5 @@
 import { builtinModules } from 'node:module';
 import { sourceLocation } from '../../lib/ts-ast.mjs';
-import { isServerActionModule } from './server-action.mjs';
 
 /**
  * R55 `client-reaches-server` (FE_CLIENT_REACHES_SERVER), the repository half of the eslint rule `client-no-server-import`,
@@ -58,7 +57,6 @@ const scanClientEntry = (entry, { ts, graph, runtime, violations }) => {
   const seen = new Map([[entry.rel, { chain: [entry.rel], first: null }]]);
   const queue = [entry.rel];
   for (const rel of queue) {
-    if (isServerActionModule(ts, graph.files.get(rel).sourceFile)) continue;
     const state = seen.get(rel);
     for (const hit of runtime.serverOf(rel)) {
       const at = state.first ?? sourceLocation(graph.files.get(rel).sourceFile, hit.node);

package/runtime/scripts/hfs/architecture/config.mjs

@@ -199,7 +199,8 @@ function inferredLayout(root, workspaces) {
     features: collect('src/features'),
     components: [...new Set(components)],
     hooks: collect('src/hooks'),
-    modules: collect('src/modules'),
+    // src/redux/ (fe.redux) is a modules-tier owner beside src/modules/ (owner ruling 2026-10-13, fe-stack state-global).
+    modules: [...collect('src/modules'), ...collect('src/redux')],
     transport: collect('src/modules/api'),
   };
 }
@@ -291,7 +292,7 @@ function derivedGrammar(root, packageRoot, workspaces, apps = []) {
     if (declaresGrammar(pkg)) consumerManifests.push(manifest);
   }
   if (!consumerManifests.length) return null;
-  return { package: GRAMMAR_PACKAGE, entry: `${GRAMMAR_PACKAGE}/common`, styleEntry: `${GRAMMAR_PACKAGE}/common.css`, styleSources, consumerManifests, peers: ['react', '@heroui/react'] };
+  return { package: GRAMMAR_PACKAGE, entry: `${GRAMMAR_PACKAGE}/common`, styleEntry: `${GRAMMAR_PACKAGE}/common.css`, styleSources, consumerManifests, peers: ['react', '@heroui/react', '@xyflow/react'] };
 }
 
 /**

package/runtime/scripts/hfs/architecture/dead-exports.mjs

@@ -8,7 +8,7 @@
  *                      so a file only a spec imports is dead, on purpose. Type-only imports reach a file.
  *
  * Owner = every graph.ownerRoots unit whose tier is not `app` and whose public entry file is in the graph (index.ts or
- * index.tsx, a package's src/index.ts). The `entries` its slot declares (slot data, e.g. fe.modules.db browser.ts) are further
+ * index.tsx, a package's src/index.ts). The `entries` its slot declares (slot data: a second public entry file of the owner) are further
  * public entries of the same owner, judged exactly like the entry. The exported names of an entry are its named exports, `export { a as b }`,
  * `export { x } from`, declarations with `export`, and `default` for `export default`. `export *` is refused by owners.mjs
  * and contributes no name here.
@@ -34,6 +34,7 @@ import fs from 'node:fs';
 import { canonical } from './config.mjs';
 import path from 'node:path';
 import { treeOf } from './required-files.mjs';
+import { globExpression } from '../../lib/glob.mjs';
 
 export const DEAD_EXPORT_RULE_IDS = ['HFS_UNUSED_EXPORT', 'HFS_UNUSED_FILE'];
 
@@ -59,7 +60,10 @@ export function entryOf(graph, config, key, owner) {
 /** The additional public entry files (repository-relative, in the graph) the slot manifest declares for the owner (slot field `entries`, on the slot that holds its entry file). */
 function extraEntries(graph, entry) {
   const found = graph.resolver.classifyPath(entry);
-  return (found.slot ? graph.resolver.slot(found.slot)?.entries ?? [] : []).map(name => `${found.root}/${name}`).filter(rel => graph.files.has(rel));
+  const names = found.slot ? graph.resolver.slot(found.slot)?.entries ?? [] : [];
+  // an entry holding `*` (one file per operation) names every graph file it matches
+  const matches = name => [...graph.files.keys()].filter(rel => globExpression(`${found.root}/${name}`).test(rel));
+  return names.flatMap(name => (name.includes('*') ? matches(name) : [`${found.root}/${name}`].filter(rel => graph.files.has(rel))));
 }
 
 const importBindings = (ts, declaration) => {

package/runtime/scripts/hfs/architecture/error-masked.mjs

@@ -33,13 +33,22 @@ const isGraphqlRegistration = (kit, checker, node) => kit.ts.isCallExpression(no
   && ['forRoot', 'forRootAsync'].includes(node.expression.name.text)
   && kit.isImportOf(checker, node.expression.expression, 'GraphQLModule', '@nestjs/graphql');
 
+/**
+ * The formatter a `formatError` value names: the value itself, or the callee of an arrow whose body only calls it (an arrow that
+ * binds the errors service, `(formatted, error) => formatGraphqlError(errors, formatted, error)`).
+ */
+function formatterOf(ts, value) {
+  if (value && ts.isArrowFunction(value) && ts.isCallExpression(value.body)) return value.body.expression;
+  return value;
+}
+
 function passesMaskedFormatError(kit, inErrors, checker, call) {
   const { ts } = kit;
   let masked = false;
   for (const argument of call.arguments) {
     kit.walk(argument, inner => {
       if ((ts.isPropertyAssignment(inner) || ts.isShorthandPropertyAssignment(inner)) && kit.propertyNameText(inner.name) === 'formatError'
-        && inErrors(checker, kit.valueOfProperty(inner))) masked = true;
+        && inErrors(checker, formatterOf(ts, kit.valueOfProperty(inner)))) masked = true;
     });
   }
   return masked;

package/runtime/scripts/hfs/architecture/frontend.mjs

@@ -8,7 +8,7 @@ import { checkWorldRenderBoundaries } from './frontend-world.mjs';
 import { checkGrammar } from './frontend-grammar.mjs';
 import { checkRoute } from './frontend-routing.mjs';
 const FEATURE_TIERS = new Set(['pages', 'layouts', 'overlays']);
-const COMPONENT_TIERS = new Set(['blocks', 'composites', 'branches', 'leaves']);
+const COMPONENT_TIERS = new Set(['blocks', 'composites', 'branches', 'leaves', 'providers']);
 
 function absolute(root, relative) {
   return path.resolve(root, ...relative.split('/'));
@@ -90,7 +90,7 @@ function checkFrontendSourceLayout(config, sourceFile, roots) {
   if (located.role === 'hooks') valid = located.relative.includes('/') || roleEntry(located.relative);
   return valid ? [] : [{ ruleId: 'FE_SOURCE_LAYOUT_INVALID', path: relativePath(config.root, sourceFile.fileName), line: 1, column: 1,
     message: ({ features: 'Frontend features contain only pages, layouts and overlays plus an optional root public entry.',
-      components: 'Frontend components contain only blocks, composites, branches and leaves plus an optional root public entry.',
+      components: 'Frontend components contain only blocks, composites, branches, leaves and providers plus an optional root public entry.',
       hooks: 'Every authored custom hook is grouped below a domain folder under hooks; only the root public entry may sit directly under hooks.' })[located.role] }];
 }
 
@@ -139,8 +139,15 @@ function reportExportedHooks(state) {
   }
 }
 
+/** True when the slot that owns this file names it as its `hooks` role (redux/hooks.ts, modules/toast/hooks.ts): the owner's own typed hooks. */
+function slotHooksRole(config, fileName) {
+  const found = config.hfs?.classifyPath?.(relativePath(config.root, fileName));
+  const role = found?.slot ? config.hfs.slot(found.slot)?.roles?.hooks : undefined;
+  return typeof role === 'string' && path.basename(fileName) === role;
+}
+
 function checkCustomHookLocations(config, context, sourceFile, roots) {
-  if (insideAny(roots.hooks, sourceFile.fileName)) return [];
+  if (insideAny(roots.hooks, sourceFile.fileName) || slotHooksRole(config, sourceFile.fileName)) return [];
   const { ts } = context;
   const state = { ts, config, sourceFile, checker: context.checkerFor(sourceFile.fileName), violations: [], seen: new Set() };
   visitHookDeclarations(state, sourceFile);