@starci/eslint-canon-fe 8.2.14 → 8.2.15

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 8.2.15 - 2026-10-13
+
+- Changed: carry the runtime mirror of HFS manifest 3.0.0 (one front-end standard for the lite and the full edition, owner ruling 2026-10-13) and the canon pins for Grammar 0.9.14, HFS 4.2.14, jest-preset 2.2.7 and CLI 1.2.14.
+- Added: `fe-stack-import` (law `fe-stack`, finding code `FE_STACK_FORBIDDEN`): an import (static, re-export, dynamic, `require`, type-only included) of a package any concern of the fe-stack catalog (`runtime/knowledge/hfs/fe-stack.yaml`) forbids, and `@supabase/*` outside `modules/auth` (slot `fe.modules.auth`), are refused. The catalog is read from the runtime copy; a missing copy stops the lint run with the fix.
+- Changed: the transport law follows the Apollo GraphQL + axios API layer. `fetch` (and `Request`, `EventSource`, `sendBeacon`) is legal in every file of the API layer (`modules/api`, the shared api package), `@apollo/client` only there, `axios` only in its REST calls (`modules/api/rest/`), `socket.io-client` only in `hooks/socketio/` (`fetch-only-in-api-client`, message `placed`); `client-fetch-has-signal` and `no-shared-transport-state` judge the whole layer (the generated `graphql/__generated__/` excepted); `no-hand-typed-wire` admits GraphQL documents in the API layer (one file per operation) and refuses them elsewhere; `one-outcome-union` names `GraphQLResponse` in `modules/api/graphql/types.ts` as the one vocabulary and also reads a `success` discriminant. The `modules/db` outcome home and the server reader role are gone.
+- Changed: `hooks-folder-holds-hooks-only` judges the hooks families `hooks/{swr,rhf,zustand,socketio,effects,reuseables}` by the files their slots name (message `family`); `SwrSideEffects.tsx` and `SocketIoSideEffects.tsx` are legal `.tsx` files of `hooks/`.
+- Changed: `use-client-only-at-boundary` admits the client state a layout mounts once (`components/providers/<name>/index.tsx`, `redux/ReduxProvider.tsx`, `modules/toast/toast.tsx`, the two side-effect components); `client-no-server-import` and `server-module-marks-server-only` drop the server reader role.
+- Changed: `presentational-purity` recognises the stack's data, form, state, socket and toast hooks (`use{Query,Mutate,Get,Post,Put,Patch,Delete}<X>Swr`, `use<X>Form`, `useForm`, `useAppDispatch`, `use<X>SocketIo`, `use<X>WithToast`, the Apollo hooks); the served-locale rules find the links of the Apollo clients folder and read the header name case-insensitively; `use-intl-formatter` admits `dayjs` in `modules/dayjs`.
+- Changed: `heroicons-is-the-glyph-vendor` is replaced by `one-icon-set`: product glyphs come only from the fe-stack icon set (`@phosphor-icons/react`, subpaths included); Heroicons and `@starci/heroicons` are refused like any second catalogue. A package the catalog forbids by name (date libraries, i18n stacks, glyph sets, transports) is reported once, by `fe-stack-import`.
+
 ## 8.2.14 - 2026-10-12
 
 - Changed: carry the merged runtime mirror and canon pins for Grammar 0.9.13, Stylelint canon 2.0.9, HFS 4.2.13 and CLI 1.2.13. The bundled HFS manifest 2.2.0 recognizes declaration-only ambient owners; ESLint rule implementations are unchanged.

package/README.md

@@ -22,6 +22,7 @@ recommended set lifted to `error`), typed linting, and the inline-directive fenc
 `reportUnusedDisableDirectives`). The repository states nothing.
 
 - The **Sonar parity** law (R235): the smells SonarCloud measures that a lint rule can decide, `no-await-in-loop`, `prefer-code-point`, `prefer-string-raw`, `no-nested-conditional`, `no-void-operator`, `no-unused-import`, `prefer-export-from` and `no-unused-prop-types`, plus the typescript-eslint rules `no-deprecated`, `no-base-to-string` and `require-await` the factory turns on (they read types, so the source block is typed). A Next `matcher` string keeps its escapes (the segment config is read statically); `*.spec.ts` and `*.e2e-spec.ts` are outside the scan, so outside these rules.
+- The **fe-stack** law: `fe-stack-import` refuses an import of a library the front-end stack catalog forbids (one canonical library per concern, read from `runtime/knowledge/hfs/fe-stack.yaml`) and `@supabase/*` outside `modules/auth`.
 - The **ignore** block: `node_modules`, `.next`, `dist`, `coverage`, `__generated__` and `.starci/`.
 - The **source** block governs `apps/*/src/**` and `packages/*/src/**` with types (`parserOptions.projectService`) and
   `settings.starci.hfs`, the slot view path-scoped rules ask (`lib/hfs.mjs` `hfsOf`), never a path pattern.

package/client-boundary.mjs

@@ -10,19 +10,34 @@
  * The directive is allowed in exactly the places the framework or the interaction requires:
  *   - the `index.tsx` of an interactive block (or overlay), which is the connected half;
  *   - a leaf, whose interactivity is intrinsic (a menu, a tooltip trigger);
- *   - `error.tsx` and `global-error.tsx`, which Next requires to be client components.
+ *   - `error.tsx` and `global-error.tsx`, which Next requires to be client components;
+ *   - the client state of the front-end stack, which only ever runs in the browser: a provider of
+ *     `components/providers/<name>/index.tsx`, every file of `hooks/` (the SWR, form, store, socket and effect hooks and the
+ *     side-effect components), the redux store (`redux/`) and the toast module (`modules/toast/`). A directive there states
+ *     what the file already is; it ships nothing a server component would have kept.
  * Everything below a client block is already on the client and needs no directive; everything
  * above it is a server component and must not have one.
  */
 
 import ts from "typescript"
-import { classifyImport, fileOf, isProductSource, kindOfFile, roleOfFile, slotOfFile, tierOfFile } from "./lib/scope.mjs"
+import { isProductSource, kindOfFile, roleOfFile, slotOfFile, tierOfFile } from "./lib/scope.mjs"
 import { typed } from "./lib/types.mjs"
 
-/** The route roles that are client-only by the framework's own rule: `error` and `global-error`. */
 /** Route-tree roles that are client components by construction: the error boundaries, and the providers wrapper a layout renders. */
 const FRAMEWORK_CLIENT_ROLES = new Set(["error", "global-error", "providers"])
 
+/** The slots of client state outside the hooks tier: the redux store and the toast module (fe-stack state-global, toast). */
+const CLIENT_STATE_SLOTS = new Set(["fe.redux", "fe.modules.toast"])
+
+/**
+ * The client state of the front-end stack, which runs only in the browser, so the directive states what the file already is: a
+ * provider entry (`fe.components.providers`), every file of the hooks tier, the redux store and the toast module.
+ */
+const isClientState = (context) =>
+  (slotOfFile(context) === "fe.components.providers" && roleOfFile(context) === "entry") ||
+  tierOfFile(context) === "hooks" ||
+  CLIENT_STATE_SLOTS.has(slotOfFile(context))
+
 /** True when the program opens with the `"use client"` directive. */
 const clientDirective = (program) =>
   program.body.find(
@@ -41,7 +56,8 @@ const isInteractionBoundary = (context) => {
 }
 
 /** Where the directive is a legitimate boundary. */
-const isBoundary = (context) => (slotOfFile(context) === "fe.route" && FRAMEWORK_CLIENT_ROLES.has(roleOfFile(context))) || isInteractionBoundary(context)
+const isBoundary = (context) =>
+  (slotOfFile(context) === "fe.route" && FRAMEWORK_CLIENT_ROLES.has(roleOfFile(context))) || isInteractionBoundary(context) || isClientState(context)
 
 /** The slot a file fills in the route tree (its role in `fe.route`, or the page or layout owner of a feature), when it fills one. */
 const routeFill = (context) => {
@@ -55,13 +71,13 @@ const routeFill = (context) => {
 export const useClientOnlyAtBoundary = {
   meta: {
     type: "problem",
-    docs: { description: "`\"use client\"` appears only at a block index, a leaf, or a Next error boundary." },
+    docs: { description: "`\"use client\"` appears only at a block index, a leaf, a Next error boundary, or the client state of the stack (a provider, `hooks/`, `redux/`, `modules/toast/`)." },
     schema: [],
     messages: {
       slot:
         "`\"use client\"` on a {{slot}}. Routes, pages and layouts are server components: making one a client component ships its whole subtree, including the message catalog, to every reader and stops it reading data on the server. Move the interaction into a block below it and put the directive on that block's `index.tsx`; context providers go in the route tree's `providers.tsx`.",
       elsewhere:
-        "`\"use client\"` here is not at an interaction boundary. The directive belongs on the `index.tsx` of the interactive block (or overlay), on a leaf whose interaction is intrinsic, on `error.tsx`/`global-error.tsx`, or on the route tree's `providers.tsx` (the context providers a layout renders around its children). Below a client block the file is already client; above one it must stay a server component.",
+        "`\"use client\"` here is not at an interaction boundary. The directive belongs on the `index.tsx` of the interactive block (or overlay), on a leaf whose interaction is intrinsic, on `error.tsx`/`global-error.tsx`, on the route tree's `providers.tsx` (the context providers a layout renders around its children), or on the client state of the stack (`components/providers/<name>/index.tsx`, `hooks/`, `redux/`, `modules/toast/`). Below a client block the file is already client; above one it must stay a server component.",
     },
   },
   create(context) {
@@ -92,25 +108,18 @@ const serverApiReason = (source) => {
   return null
 }
 
-/** A server-only source: the marker package, a server API, a server reader (role `reader` of slot `fe.modules.api`). */
-const serverOnlyReason = (context, source) => {
-  if (source === "server-only") return "`server-only`"
-  const api = serverApiReason(source)
-  if (api) return api
-  const target = classifyImport(context, source)
-  if (target?.slot === "fe.modules.api" && target.role === "reader") return `the server reader \`${source}\``
-  return null
-}
+/** A server-only source: the marker package or a server API. */
+const serverOnlyReason = (source) => (source === "server-only" ? "`server-only`" : serverApiReason(source))
 
 /** A client component imports nothing that only exists on the server. */
 export const clientNoServerImport = {
   meta: {
     type: "problem",
-    docs: { description: "A `\"use client\"` file does not import `server-only`, `next/headers`, a Node built-in or a server reader." },
+    docs: { description: "A `\"use client\"` file does not import `server-only`, `next/headers`, `next/server`, `next-intl/server` or a Node built-in." },
     schema: [],
     messages: {
       server:
-        "This client component imports {{what}}, which exists only on the server. The build either fails or, worse, pulls server code and its secrets toward the browser bundle. Read the data in a server component or a server reader and pass the result down as props, or call the app client through SWR.",
+        "This client component imports {{what}}, which exists only on the server. The build either fails or, worse, pulls server code and its secrets toward the browser bundle. Read the data through an SWR hook of `hooks/swr` over an operation of `modules/api`, and keep request-scoped server APIs in server components.",
     },
   },
   create(context) {
@@ -121,7 +130,7 @@ export const clientNoServerImport = {
       },
       ImportDeclaration(node) {
         if (!client || node.importKind === "type") return
-        const what = serverOnlyReason(context, String(node.source.value))
+        const what = serverOnlyReason(String(node.source.value))
         if (what) context.report({ node, messageId: "server", data: { what } })
       },
     }
@@ -139,7 +148,7 @@ const isMarkerStatement = (statement) =>
 
 /** True when a TypeScript source file opens with `import "server-only"`. */
 const tsFileIsMarked = (file) => {
-  // a file-level directive ("use server") is the prologue: the marker is the first statement after it
+  // a file-level directive ("use strict") is the prologue: the marker is the first statement after it
   const first = file.statements.find((statement) => !(ts.isExpressionStatement(statement) && ts.isStringLiteral(statement.expression)))
   return Boolean(first) && ts.isImportDeclaration(first) && !first.importClause && ts.isStringLiteral(first.moduleSpecifier) && first.moduleSpecifier.text === "server-only"
 }
@@ -177,14 +186,13 @@ export const serverModuleMarksServerOnly = {
     // A block or a page is a server or client COMPONENT, not a server module: whether client code reaches the server through it is
     // the machine's multi-hop question (FE_CLIENT_REACHES_SERVER). The marker belongs to the modules that hold server work.
     if (COMPONENT_TIERS.has(tierOfFile(context))) return {}
-    const reader = roleOfFile(context) === "reader"
     let client = false
     let marked = false
     const uses = []
     return {
       Program(program) {
         client = clientDirective(program) !== null
-        // a file-level directive ("use server") is the prologue, not a statement: the marker is the first statement after it
+        // a file-level directive ("use strict") is the prologue, not a statement: the marker is the first statement after it
         marked = isMarkerStatement(program.body.find((statement) => !(statement.type === "ExpressionStatement" && typeof statement.directive === "string")))
       },
       "ImportDeclaration, ExportNamedDeclaration, ExportAllDeclaration"(node) {
@@ -204,14 +212,48 @@ export const serverModuleMarksServerOnly = {
       "Program:exit"() {
         // a "use client" file that imports the server is client-no-server-import's finding, not a missing marker
         if (client || marked) return
-        // A server reader (`read-*.ts`, role `reader` of the api slot) is server-only by its role, whatever it imports.
-        if (reader && uses.length === 0) context.report({ node: context.sourceCode.ast, messageId: "mark", data: { what: "the request (it is a server reader)" } })
         for (const use of uses) context.report({ node: use.node, messageId: "mark", data: { what: use.what } })
       },
     }
   },
 }
 
+// -- FE-CLIENT-2c (R243 FE_SERVER_ACTION_FORBIDDEN) ------------------------------------------------
+
+/**
+ * The front end serves no API: no `"use server"` directive, at the top of a module or as the first statement of a function.
+ * Reads and writes reach the back end through the operations of `modules/api` and the SWR hooks; a write that must run on a
+ * server is a GraphQL mutation of the back end.
+ */
+export const noServerAction = {
+  meta: {
+    type: "problem",
+    docs: { description: "No `\"use server\"` directive (module or function level): the front end holds no Server Action." },
+    schema: [],
+    messages: {
+      action:
+        "`\"use server\"` makes this a Server Action: an HTTP endpoint the front end serves, with its own input parsing, credential and error mapping beside the back end's. The front end serves no API. Write it as a GraphQL mutation of the back end, call it through its operation in `modules/api/graphql/mutations/` and its SWR hook (`hooks/swr/`), and report the outcome through `modules/toast`.",
+    },
+  },
+  create(context) {
+    const check = (statements) => {
+      for (const statement of statements ?? []) {
+        if (statement.type !== "ExpressionStatement" || typeof statement.directive !== "string") return
+        if (statement.directive === "use server") context.report({ node: statement, messageId: "action" })
+      }
+    }
+    const body = (node) => {
+      if (node.body?.type === "BlockStatement") check(node.body.body)
+    }
+    return {
+      Program: (program) => check(program.body),
+      FunctionDeclaration: body,
+      FunctionExpression: body,
+      ArrowFunctionExpression: body,
+    }
+  },
+}
+
 // -- FE-CLIENT-3 -----------------------------------------------------------------------------------
 
 /** Web storage exists only in the browser and only under `modules/`, which guards it. */
@@ -348,6 +390,7 @@ export const rules = {
   "use-client-only-at-boundary": useClientOnlyAtBoundary,
   "client-no-server-import": clientNoServerImport,
   "server-module-marks-server-only": serverModuleMarksServerOnly,
+  "no-server-action": noServerAction,
   "web-storage-only-in-modules": webStorageOnlyInModules,
   "no-dangerous-html": noDangerousHtml,
   "response-cookie-attributes": responseCookieAttributes,

package/docs/client-boundary.md

@@ -2,13 +2,13 @@
 
 Law module: `client-boundary.mjs`. Catalogue: R55 FE_CLIENT_BOUNDARY.
 
-Server first. `"use client"` appears only on the `index.tsx` of an interactive block (or overlay), on a leaf whose interaction is intrinsic, on a branch or leaf of a workspace package (`packages/<pkg>/src/{branches,leaves}/`, where the grammar tiers sit directly under `src/`), and on `error.tsx` / `global-error.tsx`, which Next requires to be client components. Routes, pages and layouts are server components.
+Server first. `"use client"` appears only on the `index.tsx` of an interactive block (or overlay), on a leaf whose interaction is intrinsic, on a branch or leaf of a workspace package (`packages/<pkg>/src/{branches,leaves}/`, where the grammar tiers sit directly under `src/`), on `error.tsx` / `global-error.tsx`, which Next requires to be client components, on the route tree's `providers.tsx`, and on the client state a layout mounts once: a provider (`components/providers/<name>/index.tsx`), `redux/ReduxProvider.tsx`, the toast region `modules/toast/toast.tsx` and the side-effect components `hooks/swr/SwrSideEffects.tsx` and `hooks/socketio/SocketIoSideEffects.tsx`. Routes, pages and layouts are server components; the hooks, slices and modules below a client boundary are already client and carry no directive.
 
 Every rule below is an error in `starciFeConfig`; none can be switched off or suppressed inline.
 
 ## `starci-fe/use-client-only-at-boundary`
 
-`"use client"` appears only at a block index, a leaf, or a Next error boundary.
+`"use client"` appears only at a block index, a leaf, a Next error boundary, or the client state a layout mounts once (a provider, a side-effect component, the redux provider, the toast region).
 
 **Invalid** (`src/app/[locale]/layout.tsx`)
 
@@ -32,7 +32,7 @@ export const Feed = () => null
 
 ## `starci-fe/client-no-server-import`
 
-A `"use client"` file does not import `server-only`, `next/headers`, `next/server`, `next-intl/server`, a Node built-in or a server reader (sub-check `FE_CLIENT_SERVER_IMPORT`).
+A `"use client"` file does not import `server-only`, `next/headers`, `next/server`, `next-intl/server` or a Node built-in (sub-check `FE_CLIENT_SERVER_IMPORT`).
 
 **Invalid** (`src/components/blocks/Feed/index.tsx`)
 
@@ -50,27 +50,27 @@ import useSWR from "swr"
 
 **Finding code:** `FE_CLIENT_SERVER_IMPORT`
 
-**Why:** The client component at `<file>` imports code that exists only on the server (`server-only`, `next/headers`, Node modules, a server reader).
+**Why:** A client component in `<file>` imports code that exists only on the server (`server-only`, `next/headers`, a Node module, a server-only module).
 
-**Fix:** Read data in a server component or server reader and pass it down as props; or use SWR calling the app client.
+**Fix:** Read the data through an SWR hook of `hooks/swr` over an operation of `modules/api`; keep request-scoped server APIs in server components.
 
 ## `starci-fe/server-module-marks-server-only`
 
 A module that imports `next/headers`, `next/server` (a value import), `next-intl/server`, a Node built-in, or a module that is itself server-only starts with `import "server-only"` (sub-check `FE_SERVER_ONLY_MARK`). A module is server-only when the TypeScript module resolution of the import specifier reaches a source file whose first statement is `import "server-only"`; `import type` and `import { type X }` carry no runtime and are not judged. Route files are server components by construction and need no marker: they are recognized by their slot (`fe.route`, `fe.source-root-pinned`), not by their name. A `"use client"` file that imports the server is `client-no-server-import`'s finding. The multi-hop client reachability (a client block reaching a marked module through a hook) is the architecture machine's.
 
-**Invalid** (`src/modules/api/courses/read-courses.ts`)
+**Invalid** (`src/modules/i18n/request-locale.ts`)
 
 ```ts
 import { headers } from "next/headers"
-export const readCourses = async () => (await headers()).get("x-locale")
+export const requestLocale = async () => (await headers()).get("accept-language")
 ```
 
-**Valid** (`src/modules/api/courses/read-courses.ts`)
+**Valid** (`src/modules/i18n/request-locale.ts`)
 
 ```ts
 import "server-only"
 import { headers } from "next/headers"
-export const readCourses = async () => (await headers()).get("x-locale")
+export const requestLocale = async () => (await headers()).get("accept-language")
 ```
 
 **Finding code:** `FE_SERVER_ONLY_MARK`

package/docs/hooks-folder.md

@@ -2,13 +2,13 @@
 
 Law module: `hooks-folder.mjs`. Catalogue: R56 FE_HOOKS_ARE_HOOKS (lint half).
 
-`hooks/<domain>/use<Name>.ts` holds one hook per file; `hooks/<domain>/<domain>.shared.ts` holds the domain's non-hook helpers; server readers live in `modules/api/<domain>/read-*.ts`. Whether a folder has exactly one shared file and whether a helper name repeats across files belongs to the architecture machine.
+`hooks/` holds the hook families of the front-end stack, each its own slot whose `allows` name its files: `hooks/swr/` (`api/{graphql,rest}/{queries,mutations}/use{Query,Mutate,Get,Post,Put,Patch,Delete}<X>Swr.ts`, one SWR hook per `modules/api` operation, and `SwrSideEffects.tsx`), `hooks/rhf/use<X>Form.ts`, `hooks/zustand/<store>/` (`store.ts` and `use*.ts`), `hooks/socketio/` (`sockets.ts`, `SocketIoSideEffects.tsx`, `enums/`, `types/`, `use*.ts`), `hooks/effects/use*.ts` and `hooks/reuseables/use*.ts`. Beside them, `hooks/<domain>/use<Name>.ts` holds one hook per file and `hooks/<domain>/<domain>.shared.ts` the domain's non-hook helpers. The two side-effect components are the only `.tsx` files of `hooks/`. A call to the back end is an operation of `modules/api`, never a hook's own code. Whether a folder has exactly one shared file and whether a helper name repeats across files belongs to the architecture machine.
 
 Every rule below is an error in `starciFeConfig`; none can be switched off or suppressed inline.
 
 ## `starci-fe/hooks-folder-holds-hooks-only`
 
-`hooks/<domain>/` holds `use*.ts` hooks and one `<domain>.shared.ts`; nothing else.
+`hooks/` holds `use*.ts` hooks under the names their family slot gives and, per domain, one `<domain>.shared.ts`; nothing else. A hook file exports one hook; `server-only` and `next/headers` are never imported there.
 
 **Invalid** (`src/hooks/course/readCourse.ts`)
 
@@ -24,6 +24,18 @@ export const useCourse = () => 1
 
 **Finding code:** `FE_HOOKS_ARE_HOOKS`
 
-**Why:** `<file>` in `hooks/` is not a React hook. Server readers belong in `modules/api`, helpers in `<domain>.shared.ts`.
+**Invalid** (`src/hooks/swr/api/graphql/queries/useGetCourseSwr.ts`: a REST name in the GraphQL queries folder)
 
-**Fix:** One hook per `use*.ts` file; shared helpers go into `<domain>.shared.ts`; server readers go into `modules/api/<domain>/read-*.ts`.
+```ts
+export const useGetCourseSwr = () => 1
+```
+
+**Valid** (`src/hooks/swr/api/graphql/queries/useQueryCourseSwr.ts`)
+
+```ts
+export const useQueryCourseSwr = () => 1
+```
+
+**Why:** `<file>` inside `hooks/` is not a React hook, or is not a file its hooks family names. A call to the back end goes to `modules/api`, a helper to `<domain>.shared.ts`.
+
+**Fix:** One hook per `use*.ts` file under the name its family gives it (`hooks/swr/api/graphql/queries/useQuery<X>Swr.ts`, `hooks/rhf/use<X>Form.ts`, ...); a shared helper goes in `<domain>.shared.ts`; a back-end call is an operation of `modules/api`.

package/docs/hygiene.md

@@ -57,7 +57,7 @@ const subscribe = (listener: () => void) => {
 
 ## `starci-fe/no-data-fetch-in-effect`
 
-An effect body starts no promise: no `await`, `fetch`, `.then`, `void load()`, `mutate()` or `refresh()`; read through SWR or a server reader. The call is judged when it runs synchronously in the body (an immediately-invoked function counts); a promise started inside a listener or timer callback the effect registers, or in the cleanup, is that callback's work. A call is a load when its type is a promise, when it is `.then`-ed, or when it is `void`-ed and untyped; a platform promise other than `fetch` (`audio.play()`, `clipboard.writeText()`) is not a data load. Data freshness comes from the SWR key: an SWR `mutate()` or `refresh()` called directly in the effect body is a finding too; run it from the event that changed the data (a handler, a socket message).
+An effect body starts no promise: no `await`, `fetch`, `.then`, `void load()`, `mutate()` or `refresh()`; read through an SWR hook (`hooks/swr`) over an operation of `modules/api`. The call is judged when it runs synchronously in the body (an immediately-invoked function counts); a promise started inside a listener or timer callback the effect registers, or in the cleanup, is that callback's work. A call is a load when its type is a promise, when it is `.then`-ed, or when it is `void`-ed and untyped; a platform promise other than `fetch` (`audio.play()`, `clipboard.writeText()`) is not a data load. Data freshness comes from the SWR key: an SWR `mutate()` or `refresh()` called directly in the effect body is a finding too; run it from the event that changed the data (a handler, a socket message).
 
 **Invalid** (`src/components/blocks/Feed/component.tsx`)
 
@@ -75,7 +75,7 @@ const { data } = useSWR(key, fetcher)
 
 **Why:** `useEffect` in `<file>` loads data (`await`, `fetch`, `.then`): no cache, no request merging, no loading/error state, no cancellation.
 
-**Fix:** Read on the client with SWR calling the app client (`hooks/`), and on the route side with a server reader `modules/api/<domain>/read-*.ts`.
+**Fix:** Read with an SWR hook of `hooks/swr` over an operation of `modules/api`, keyed by what changes; call `mutate()` from the event that changes the data (handler, socket message).
 
 ## `starci-fe/no-empty-catch`
 

package/docs/transport.md

@@ -2,13 +2,13 @@
 
 Law module: `transport.mjs`. Catalogue: R50 FE_TRANSPORT_OWNER, R51 FE_HTTP_STATUS_COLLAPSE, R52 FE_WIRE_GENERATED.
 
-One repository, one client, one result vocabulary. The client is the file of HFS slot `fe.transport.client` (`apps/<app>/src/modules/api/client.ts`, a one-app repository) or `fe.package.api.client` (`packages/<family>-api/src/client.ts`, the shared client of a multi-app repository); the vocabulary is `Outcome<T>` (`ok`, `refused`, `invalid`, `not-found`, `unavailable`), declared in the file of the slot the manifest marks `outcomeHome`: `fe.transport.outcome`, `fe.package.api.outcome`, or `fe.modules.db.outcome` (`modules/db/outcome.ts`) in a lite app, whose db owner is the transport. The rules read the slot of the file being linted, never its path. 401 and 403 become `refused`; nothing collapses a status into `null`; wire types are generated from the contract copy in `modules/api/contract/`.
+One front end, one API layer, one result vocabulary (lite and full alike). The API layer is `modules/api` (slot `fe.modules.api`, or the shared api package `fe.package.api`): the transport owner is the folder of the auth and no-auth Apollo clients and their link chain (slot `fe.transport.client`: `apps/<app>/src/modules/api/graphql/clients/`, or `fe.package.api.client`: `packages/<family>-api/src/graphql/clients/`), one file per GraphQL operation runs on them (`graphql/queries/query-<x>.ts`, `graphql/mutations/mutation-<x>.ts`), and the REST calls (uploads, presigned URLs, auth endpoints) are axios calls in `rest/<area>/`. `fetch` is reached only in the API layer, `@apollo/client` is imported only there, `axios` only by its REST calls and `socket.io-client` only by `hooks/socketio/`; everything else reaches the back end through the SWR hooks of `hooks/swr/`. The vocabulary is `GraphQLResponse<T>` (`success`, `message`, `error`, `data`), declared in the file of the slot the manifest marks `outcomeHome`: `fe.transport.outcome` (`modules/api/graphql/types.ts`) or `fe.package.api.outcome`. The rules read the slot of the file being linted, never its path. A raw `fetch` answered in the clients folder maps 401 and 403 to `refused`; nothing collapses a status into `null`; wire types are generated from the be contract snapshot into `graphql/__generated__/`, and a GraphQL document is written only in the API layer.
 
 Every rule below is an error in `starciFeConfig`; none can be switched off or suppressed inline.
 
 ## `starci-fe/fetch-only-in-api-client`
 
-The repository's single `fetch` (and `Request`, `EventSource`, `navigator.sendBeacon`) lives in the api client slot. The global is found by scope resolution: `fetch(...)`, `globalThis.fetch`, `window.fetch`, `self.fetch`, `const f = fetch` and `const { fetch } = globalThis` all count, a local or imported `fetch` does not. A fetch library is refused by module specifier (axios, ky, got, undici, ofetch, graphql-request, urql, `@apollo/*`, ...; `import`, `export ... from`, `import()` and `require`), also inside the client. Another file of the api package (`src/transport.ts`) is not the client.
+`fetch` (and `Request`, `EventSource`, `navigator.sendBeacon`) lives in the API layer (`modules/api`, or the shared api package). The global is found by scope resolution: `fetch(...)`, `globalThis.fetch`, `window.fetch`, `self.fetch`, `const f = fetch` and `const { fetch } = globalThis` all count, a local or imported `fetch` does not. The canonical transports are placed by module specifier (`import`, `export ... from`, `import()` and `require`): `@apollo/client` only in the API layer, `axios` only in its REST calls (`modules/api/rest/`), `socket.io-client` only in `hooks/socketio/` (`placed`). Another HTTP library (got, undici, ofetch, `@apollo/server`, ...) is refused everywhere (`library`); one the fe-stack catalog forbids by name (ky, graphql-request, urql, ...) is `fe-stack-import`'s finding.
 
 **Invalid** (`src/hooks/course/useCourse.ts`)
 
@@ -16,29 +16,29 @@ The repository's single `fetch` (and `Request`, `EventSource`, `navigator.sendBe
 const r = await fetch(url)
 ```
 
-**Valid** (`src/hooks/course/useCourse.ts`)
+**Valid** (`src/hooks/swr/api/graphql/queries/useQueryCourseSwr.ts`)
 
 ```ts
-const r = await client.get(url)
+const swr = useSWR([QUERY_COURSE_SWR_KEY, id], () => queryCourse({ request: { id } }))
 ```
 
 **Finding code:** `FE_TRANSPORT_OWNER`
 
-**Why:** `fetch` (or `Request`, `EventSource`, `sendBeacon`, another HTTP library) in `<file>` is outside the single client (`modules/api/client.ts`, or `src/client.ts` of the shared api package). Each repo has exactly one transport path.
+**Why:** `<file>` reaches the back end outside the API layer: `fetch` (or `Request`, `EventSource`, `sendBeacon`, another HTTP library) outside `modules/api`, or Apollo, axios or socket.io-client outside its home (`modules/api`, `modules/api/rest`, `hooks/socketio`).
 
-**Fix:** Call the repo's client and receive `Outcome<T>`; do not call `fetch` yourself.
+**Fix:** Call an operation of `modules/api` (Apollo GraphQL, or axios in `modules/api/rest`) through its SWR hook in `hooks/swr`; listen to realtime through `hooks/socketio`.
 
 ## `starci-fe/client-fetch-has-signal`
 
-Every `fetch` in `modules/api/client.ts` passes an AbortSignal (timeout or caller).
+Every `fetch` in the API layer (`modules/api`: a custom fetch handed to the Apollo http link, a raw call) passes an AbortSignal (timeout or caller).
 
-**Invalid** (`src/modules/api/client.ts`)
+**Invalid** (`src/modules/api/graphql/clients/links/http.ts`)
 
 ```ts
 fetch(url, { method: "GET" })
 ```
 
-**Valid** (`src/modules/api/client.ts`)
+**Valid** (`src/modules/api/graphql/clients/links/http.ts`)
 
 ```ts
 fetch(url, { method: "GET", signal: AbortSignal.timeout(8000) })
@@ -54,13 +54,13 @@ fetch(url, { method: "GET", signal: AbortSignal.timeout(8000) })
 
 `modules/api/**` holds no module-level `let`/`var`.
 
-**Invalid** (`src/modules/api/client.ts`)
+**Invalid** (`src/modules/api/graphql/clients/links/http.ts`)
 
 ```ts
 let token = null
 ```
 
-**Valid** (`src/modules/api/client.ts`)
+**Valid** (`src/modules/api/graphql/clients/links/http.ts`)
 
 ```ts
 export const request = (token: string) => token
@@ -76,13 +76,13 @@ export const request = (token: string) => token
 
 The api client branches on the response status: a comparison of the fetch response's status (typed as a `Response`) with 401 and 403 (`===`, `||`, a literal list `.includes`/`.has`, or a `switch` with both cases) whose consequent builds an object with `kind: "refused"`. The three literals lying anywhere in the file do not pass, and neither does a mapping delegated to a function in another file.
 
-**Invalid** (`src/modules/api/client.ts`)
+**Invalid** (`src/modules/api/graphql/clients/links/http.ts`)
 
 ```ts
 const r = await fetch(u, { signal })
 ```
 
-**Valid** (`src/modules/api/client.ts`)
+**Valid** (`src/modules/api/graphql/clients/links/http.ts`)
 
 ```ts
 const r = await fetch(u, { signal })
@@ -99,13 +99,13 @@ if (r.status === 401 || r.status === 403) return { ok: false, kind: "refused" }
 
 A failure, a non-ok HTTP response or a failed `Outcome`, is not folded into one branch or into an empty value; its reason is read and kept (an HTTP status is mapped first: 401/403 `refused`, 404 `not-found`, 422 `invalid`, the rest `unavailable`).
 
-**Invalid** (`src/modules/api/client.ts`)
+**Invalid** (`src/modules/api/graphql/clients/links/http.ts`)
 
 ```ts
 if (!res.ok) return null
 ```
 
-**Valid** (`src/modules/api/client.ts`)
+**Valid** (`src/modules/api/graphql/clients/links/http.ts`)
 
 ```ts
 if (!res.ok) return toOutcome(res.status)
@@ -119,15 +119,15 @@ if (!res.ok) return toOutcome(res.status)
 
 ## `starci-fe/no-hand-typed-wire`
 
-A transport response body is narrowed from `unknown` or typed by a generated wire type (a type imported from a `__generated__/` module), never by a hand-written one: `(await response.json()) as unknown` is the sanctioned entry and does not fire; an assertion or annotation of a `.json()` read (directly, or through a `const` initialised with one) to any other type does. Inline GraphQL documents are also refused. A hand-declared interface is not judged by its name; only a response read typed by hand is.
+A transport response body is narrowed from `unknown` or typed by a generated wire type (a type imported from a `__generated__/` module), never by a hand-written one: `(await response.json()) as unknown` is the sanctioned entry and does not fire; an assertion or annotation of a `.json()` read (directly, or through a `const` initialised with one) to any other type does. A GraphQL document (a `gql`/`graphql` tagged template or a string that reads as one) is written only in the API layer, one file per operation (`graphql/queries/query-<x>.ts`, `graphql/mutations/mutation-<x>.ts`), where codegen reads it; outside the layer it is refused. A hand-declared interface is not judged by its name; only a response read typed by hand is.
 
-**Invalid** (`src/modules/api/course/read-course.ts`)
+**Invalid** (`src/modules/api/graphql/queries/query-course.ts`)
 
 ```ts
 const x = (await res.json()) as Course
 ```
 
-**Valid** (`src/modules/api/course/read-course.ts`)
+**Valid** (`src/modules/api/graphql/queries/query-course.ts`)
 
 ```ts
 import type { CourseQuery } from "../__generated__/graphql"
@@ -137,9 +137,9 @@ const x: CourseQuery = parse(raw)
 
 **Finding code:** `FE_WIRE_GENERATED`
 
-**Why:** `<file>` hand-types a wire type or casts a response. Use types generated from `contract/`.
+**Why:** `<file>` hand-types a wire type, casts a response, or writes a GraphQL document outside the API layer. Use the types generated from `be/contracts/`.
 
-**Fix:** Run codegen from the contract copy at `modules/api/contract/` and import the generated types; put GraphQL documents in `.graphql` files.
+**Fix:** Run codegen from the be contract snapshot (`be/contracts/`) and import the generated types; write each GraphQL document in its operation file under `modules/api/graphql/queries` or `modules/api/graphql/mutations`.
 
 ## `starci-fe/outcome-kinds-exhaustive`
 
@@ -171,9 +171,9 @@ switch (outcome.kind) {
 
 ## `starci-fe/one-outcome-union`
 
-A result union (`ok` / `kind` discriminant) is declared only in the outcome-home slot (`outcomeHome: true` in the slot manifest); elsewhere the code composes `Outcome<T>`.
+A result union (`success` / `ok` / `kind` discriminant) is declared only in the outcome-home slot (`outcomeHome: true` in the slot manifest: `modules/api/graphql/types.ts`, or the api package's `src/graphql/types.ts`); elsewhere the code composes `GraphQLResponse<T>`.
 
-A union type alias is a result union when its resolved members are all object types that carry the same literal-typed discriminant in the result vocabulary: `ok` (each member pins it to one value, `true` and `false` both present) or `kind` (at least one literal of the Outcome vocabulary: `ok`, `refused`, `forbidden`, `invalid`, `not-found`, `unavailable`). The members are read through the type checker, so `Ok<T> | Failure` and intersections are seen as what they are; no name (`*Outcome`, `*Result`) decides anything. UI state unions (`status`, `state`, `type`, a `kind` of tree nodes or menu items) are not result vocabulary and pass; so does an alias that only composes the one union (`type Read = Outcome<Course>`, `Exclude<Outcome<T>, ...>`). `Outcome<T> | { ok: false; kind: "conflict" }` adds an arm to the one union and is refused.
+A union type alias is a result union when its resolved members are all object types that carry the same literal-typed discriminant in the result vocabulary: `success` or `ok` (each member pins it to one value, `true` and `false` both present) or `kind` (at least one literal of the Outcome vocabulary: `ok`, `refused`, `forbidden`, `invalid`, `not-found`, `unavailable`). The members are read through the type checker, so `Ok<T> | Failure` and intersections are seen as what they are; no name (`*Outcome`, `*Result`) decides anything. UI state unions (`status`, `state`, `type`, a `kind` of tree nodes or menu items) are not result vocabulary and pass; so does an alias that only composes the one union (`type Read = Outcome<Course>`, `Exclude<Outcome<T>, ...>`). `Outcome<T> | { ok: false; kind: "conflict" }` adds an arm to the one union and is refused.
 
 **Invalid** (`src/hooks/invite/useInvite.ts`)
 
@@ -184,12 +184,12 @@ export type InviteOutcome = { ok: true } | { ok: false; kind: "refused" }
 **Valid** (`src/hooks/invite/useInvite.ts`)
 
 ```ts
-import type { Outcome } from "@/modules/api/outcome"
-export type InviteOutcome = Outcome<{ id: string }>
+import type { GraphQLResponse } from "@/modules/api/graphql/types"
+export type InviteResponse = GraphQLResponse<{ id: string }>
 ```
 
 **Finding code:** `FE_HTTP_STATUS_COLLAPSE`
 
-**Why:** `<file>` declares another result union (`ok` or `kind`) outside `outcome.ts`. A repo has only one `Outcome<T>`.
+**Why:** `<file>` declares another result union (`success`, `ok` or `kind`) outside `modules/api/graphql/types.ts`. A repo has only one result vocabulary, `GraphQLResponse<T>`.
 
-**Fix:** Use `Outcome<T>` from `modules/api/outcome.ts` (or the shared api package); add business detail through a second parameter instead of declaring a new union.
+**Fix:** Use `GraphQLResponse<T>` of `modules/api/graphql/types.ts` (or the shared api package); put the business detail in its `data` instead of declaring a new union.

package/docs/type-safety.md

@@ -10,13 +10,13 @@ Every rule below is an error in `starciFeConfig`; none can be switched off or su
 
 No cast through `unknown`; it turns checking off at the boundary.
 
-**Invalid** (`src/modules/api/read-course.ts`)
+**Invalid** (`src/modules/api/graphql/queries/query-course.ts`)
 
 ```tsx
 const row = payload as unknown as CourseRow
 ```
 
-**Valid** (`src/modules/api/read-course.ts`)
+**Valid** (`src/modules/api/graphql/queries/query-course.ts`)
 
 ```tsx
 const row = parseCourseRow(payload)
@@ -32,13 +32,13 @@ const row = parseCourseRow(payload)
 
 No `as T` or `<T>x`; narrow with a check, a guard or a parser.
 
-**Invalid** (`src/modules/api/read-course.ts`)
+**Invalid** (`src/modules/api/graphql/queries/query-course.ts`)
 
 ```tsx
 const row = payload as CourseRow
 ```
 
-**Valid** (`src/modules/api/read-course.ts`)
+**Valid** (`src/modules/api/graphql/queries/query-course.ts`)
 
 ```tsx
 const row = isCourseRow(payload) ? payload : null
@@ -76,13 +76,13 @@ const first = rows[0] ?? fallbackRow
 
 No `any`; use a real type or `unknown` and narrow.
 
-**Invalid** (`src/modules/api/read-course.ts`)
+**Invalid** (`src/modules/api/graphql/queries/query-course.ts`)
 
 ```tsx
 const parse = (value: any) => value.id
 ```
 
-**Valid** (`src/modules/api/read-course.ts`)
+**Valid** (`src/modules/api/graphql/queries/query-course.ts`)
 
 ```tsx
 const parse = (value: unknown) => (isCourseRow(value) ? value.id : null)