@akanjs/cli 3.0.0-alpha.9 → 3.0.0-alpha.90

package/guidelines/runtimeRule/runtimeRule.instruction.md

@@ -0,0 +1,213 @@
+# Runtime Rule — Serving, Processes, Logging, Image, Assets
+
+How an Akan app is built, what it serves, how many processes it runs, where its logs go, and what ends up in
+its image. Everything here is declared in `akan.config.ts` or narrowed by an env at boot; none of it is reached
+from domain code. `conventions` carries the invariants — this is the full contract behind them.
+
+## Web Surfaces — Building And Serving Without SSR/CSR
+
+An app serves three things: the API, the SSR/RSC web renderer, and the CSR single-file bundle. The API is always
+on; the other two are declared in `akan.config.ts` as **`web: true | false | { csr: boolean }`** and can be
+narrowed again per deployment.
+
+```ts
+const config: AppConfig = { web: { csr: false } }; // web without the mobile bundle
+const config: AppConfig = { web: false }; // api only
+```
+
+- **`web: { csr: false }`** drops the CSR build phase and the `/__csr` + `?csr=true` routes. The CSR bundle is
+  what the Capacitor mobile build ships, so a web-only deployment never needs it — and an app that declares a
+  `mobile` section is refused, because `akan build-ios` copies `dist/apps/<app>/csr/<target>.html` into the
+  native project.
+- **`web: false`** is an API-only build: no base artifact, no pages or client bundles, no RSC worker
+  entrypoint, and no `public/` in the image (the web router's catch-all is its only reader). Nothing under
+  `page/` is served, including routes a lib contributed through `syncPageLibs`.
+- **There is no CSR-without-SSR option, by type.** The CSR bundle inlines the stylesheet the SSR base artifact
+  compiles, so it would ship an unstyled app — the object form therefore carries only `csr`, and SSR goes off
+  only through the whole-surface `false`.
+- **At runtime, `AKAN_SSR` and `AKAN_CSR` narrow further and never widen** — `false` or `0` turns one off, and
+  `AKAN_SSR=false` takes CSR with it for the same reason the option has no such pair. A surface the build left
+  out cannot be switched back on, and the boot log names what the process ended up serving. The generated
+  Dockerfile writes the build's own answer as the image default.
+- **A build with no web artifact boots the API instead of crashing.** `WebRouter.create` returns `null` when
+  `.akan/artifact/base-artifact.json` is absent — an api-only build, or a workspace with no `page/` at all.
+- `akan start` ignores `web` and keeps the whole dev surface: the incremental builder is also the file watcher,
+  so switching it off would take server-code HMR with it. It warns once when the config and the dev server
+  disagree.
+- The saving is mostly the RSC worker, which is a **separate process per web-serving replica**. Measured on
+  `apps/akan` at boot plus one render: 350MB across 3 processes with SSR on, 120MB across 2 with
+  `AKAN_SSR=false`, and the built image goes 86MB → 6.2MB when the artifacts are left out of it too.
+- **The generated image installs `ca-certificates` and `tzdata` and nothing else.** It used to carry the whole
+  Chromium runtime, ffmpeg, `build-essential`, `python3` and `redis` in every app's image whether or not the app
+  reached for any of them. An app that needs one declares it in `docker.preRuns` / `docker.postRuns`, which are
+  emitted around the `bun install` — that is the migration for a `puppeteer` or `ffmpeg` app.
+
+## Route Prefixes — Where The API Is Mounted
+
+Signal endpoints hang off `/api` and the websocket upgrade off `/api/ws`. Both move, and both have to move in
+three places at once: the route table the replica builds, the gateway's own upgrade check, and the `fetchClient`
+in every browser tab. That last one is the constraint the design is built around.
+
+```ts
+// apps/<app>/main.ts — the deployment's answer
+await new AkanApp({ prefix: "/backend", websocketPrefix: "/socket" }).start();
+```
+
+```ts
+// apps/<app>/akan.config.ts — the build's answer, for the bundles a server never gets to correct
+const config: AppConfig = { api: { prefix: "/backend", websocketPrefix: "/socket" } };
+```
+
+- **Three sources, narrowest first.** `globalThis.__AKAN_PREFIX__`, then `AKAN_API_PREFIX` / `AKAN_WS_PREFIX`,
+  then `AKAN_PUBLIC_API_PREFIX` / `AKAN_PUBLIC_WS_PREFIX`, then `/api` and `/ws`. Read them through
+  `getApiPrefix()` / `getWsPrefix()` from `akanjs/base`; never write either literal again.
+- **`AKAN_API_PREFIX` is deliberately outside the `AKAN_PUBLIC_*` namespace.** Only that namespace is inlined
+  into client bundles at build time, so a name inside it could never act as a runtime override — and only a name
+  inside it can reach a prebuilt bundle at all. The two jobs need two names.
+- **`new AkanApp({ prefix })` reaches the browser through the page, not through a prop.** `FetchClient` fixes its
+  origin when the module graph initializes, before any component renders, so a React prop — a `System.Provider`
+  value, anything out of `implicitRootLayout` — is always too late. The value rides the SSR classic bootstrap
+  script instead, the one thing guaranteed to run ahead of every module script, and is omitted when it matches
+  what the bundle already assumes. `akan.config.ts` is what a Capacitor bundle or a statically served CSR shell
+  follows, because neither is rendered by a server that could tell it otherwise.
+- **A prefix is a path segment.** A blank value or a bare `/` is refused: `/` would be mounted ahead of the SSR
+  catch-all and swallow every page route. A prefix whose first segment is a declared basePath is refused at
+  `init()` for the same reason in the other direction.
+- **The prefix is fixed before `init()`.** `setPrefix` / `setWebsocketPrefix` throw once the server has started,
+  because `init()` is where the route table and the devtools routes are built.
+- `robots.txt`, the locale redirect's API bypass and the OpenAPI `servers` URL all derive from it. The blob
+  storage default (`/api/localFile/getBlob`) does **not**: those URLs are stored in rows, so moving the prefix
+  does not move what was already written.
+
+## The Process Model — Gateway And Solo
+
+A container runs one process per replica, a gateway in front of them when there is more than one, and one RSC
+worker per web-serving replica.
+
+- **One traffic replica runs in the container's only process.** `AKAN_REPLICA=0,0,1` — the default, and what
+  every environment in `infra/app/values` sets — means there is nothing to balance and nothing to fan pubsub out
+  to, so `AkanApp` starts that replica in-process rather than spawning it. Measured on `apps/akan`: 28MB less RSS
+  and twice the requests per second, because every request used to cross a unix-socket proxy hop. Declare two or
+  more and the gateway is back, spawning and proxying them.
+- **`AKAN_SOLO=false` forces the gateway** for a single replica. Like `AKAN_SSR`, the env only narrows — it
+  cannot fold a real gateway's replicas into one process. Passing `replica` to `new AkanApp(...)` also keeps the
+  gateway: code that states a topology is asking for the thing that serves it.
+- **`akan start` always runs the gateway**, whatever the replica count. It is also the dev host's builder relay,
+  its crash page, and what holds the port across a child restart.
+- **A batch-only replica (`0,1,0`) keeps the gateway too**, because a batch server never listens and the gateway
+  is then the only thing bound to answer `/_akan/app/health`.
+- **The RSC worker is never folded in.** It runs under `--conditions react-server`, which resolves the same
+  module graph differently, so it cannot share a process with the server that renders client components.
+- **A solo process answers `/_akan/app/health`, `/_akan/app/metrics` and `/_akan/bench/ping` itself**, in the
+  gateway's own shape — a `children` array with one entry — so a probe reads one contract either way. It owns the
+  rotating log file the gateway would otherwise write, in the same `runtime/logs` directory.
+- **Nothing supervises a solo process but the orchestrator**, since the gateway's crash-restart-with-backoff went
+  with it. `infra/app/templates/app.yaml` carries the liveness, readiness and startup probes that replace it.
+- **`main.ts` imports `AkanApp` from `akanjs/server/akanApp`, not the barrel.** The barrel re-exports
+  `AkanServer`, whose graph the gateway never runs; through it the process evaluated 35MB of SSR renderer and
+  SQLite driver to spawn children and relay bytes. Keep entrypoint imports at the leaf.
+
+## Logging — Records, Request Context And Live Tail
+
+Every `Logger` call builds a `LogRecord` before any text exists: `at`, `level`, OTel `sev`, `name`, `message`,
+`pid`, `replicaIdx`, `role` (`gateway` / `all` / `batch` / `rsc-worker`) and — inside a call — `traceId`,
+`endpoint` (`mutation:signScContract`, `internal:cleanupJob`, `page:/org/[orgId]`) and `origin` (`http`,
+`websocket`, `mcp`, `internal`, `page`). The console line is rendered from the record and is byte-identical to
+what it was; a sink reads `entry.record` and renders only if it touches `entry.message`.
+
+The level ladder is `trace verbose debug info warn error`. `log` was a seventh tier *below* `info` that
+`AKAN_PUBLIC_LOG_LEVEL=info` silently dropped; the method is kept and emits at `info`, so
+`no-deprecated-log-level.grit` refuses a call to it — write `.info()`. `AKAN_PUBLIC_LOG_LEVEL=log` still boots,
+normalized to `info` with one warning.
+
+- **Request context is on by default, production included.** `SignalContext.try` / `SignalContext.run` own the
+  `AsyncLocalStorage` scope for the whole call, including the 500 log, so every line of one request shares a
+  `traceId`. Internal triggers get `internal:<key>`, the RSC worker gets `page:<route>`, MCP calls are the
+  endpoint's own type with `origin: "mcp"`. `AKAN_LOG_CONTEXT=0` is the escape hatch; `AKAN_TRACE=1` is a
+  different switch that adds span and query aggregation. Measured cost: ~25ns per call.
+- **Not everything carries context, by design.** The primitive query fast path (an unauthenticated GET of a
+  primitive with no args, guards or middlewares) skips it; the schedule adaptor's own `started/finished/error`
+  lines wrap the traced handler from outside; gateway-internal lines have none. `akan logs --endpoint` says so.
+- **`Logger.addSink(sink, { minLevel })` — give a sink its floor.** A sink with none follows `AKAN_LOG_FILE_LEVEL`
+  (default `trace`), which is why a registered sink used to make every `verbose` call render (1,294ns against an
+  11ns reject). The IPC forwarder and any sink that never reads the text pass a floor and cost a record literal.
+- **The hub lives with whoever owns the surface**: the gateway when there is one, the replica itself under solo
+  (`AKAN_REPLICA=0,0,1`), the same rule as the rotating log file and `/_akan/app/*`. It keeps a ring
+  (`AKAN_LOG_BUFFER` records / `AKAN_LOG_BUFFER_MB`, default 2000 / 4), suppresses a line repeating more than 20
+  times a second into one counted line, and serves `<runtimeDir>/akan-control.sock` (`0600`, NDJSON). A child
+  forwards records only while a subscriber wants that level (`log.level` IPC), so an unwatched process sends
+  nothing; `AKAN_LOG_STREAM=1` keeps it on. The RSC worker forwards to its replica the same way.
+- **`akan logs <app>`** is the client: `--level --grep --endpoint --trace --child --role --origin --since`
+  AND together, comma lists OR, `*` is the only glob; `--replay N` first, `--follow false` for history only,
+  `--json` for NDJSON, `--runtime-dir` for a built app. Inside `akan console`, `.tail level=warn grep=payment`,
+  `.tail off`, `.trace <id>` — the console is its own `listen: false` process, so these attach to the running
+  server's socket rather than reading their own logs.
+- **The generated Dockerfile sets `AKAN_LOG_TO_FILE=0`.** A container's writable layer is ephemeral and nothing
+  collects a file from it; stdout is the collection path. A deployment that wants the files back sets
+  `AKAN_LOG_TO_FILE=1`.
+- **Never log per delivered record in anything that delivers records.** The control socket and the hub do not,
+  and a subscriber asking for everything is the test.
+
+## The Generated Image — `docker` In `akan.config.ts`
+
+**`docker` is `string | { image, preRuns, postRuns, command }`** — a whole Dockerfile, or the parts Akan
+assembles one from. There is no `content` field; the string *is* the content.
+
+```ts
+const config: AppConfig = {
+  docker: { preRuns: ["apt-get update && apt-get install -y --no-install-recommends ffmpeg"] },
+};
+const config: AppConfig = { docker: "FROM oven/bun:1-slim\n…" }; // verbatim, nothing merged in
+```
+
+- `image` and each run entry take `string | { amd64?, arm64? }`; the object form compiles to a
+  `RUN if [ "$TARGETARCH" = "<arch>" ]` guard, so a multi-arch build runs it on one leg only. `preRuns` land
+  before `bun install --production` (where a native dependency's build tools have to be), `postRuns` after it
+  and before the app files are copied.
+- **A lib declares the steps its own runtime needs**, and every app that mounts it inherits them:
+  `libs/<lib>/akan.config.ts` takes `docker: { preRuns, postRuns }` and nothing else — the base image and the
+  command belong to the app. Lib steps are emitted before the app's own, and an identical step declared twice
+  becomes one layer.
+- **The string form takes no contributions.** A Dockerfile handed over whole is used exactly as written, so a
+  lib's `preRuns` are dropped rather than spliced into a file Akan does not own. An app that needs both writes
+  the parts instead.
+- Like `externalLibs`, lib steps are collected from **every lib in the workspace**, not just this app's
+  dependency closure — narrowing that set needs the dependency scan, and this config is re-read on every file
+  change in dev. Keep a lib's steps to what its runtime genuinely requires.
+- `AkanAppConfig.docker` is the resolved declaration; `AkanAppConfig.dockerfile` is the text `akan build` writes
+  to `dist/apps/<app>/Dockerfile`.
+
+## Shipped Assets — `assets` In `akan.config.ts`
+
+`akan build` copies the whole `public/` tree into `dist`, lib assets dereferenced, and that copy is the image.
+**`assets: { pruneFonts, keepFonts }`** trims the fonts out of it that nothing reads. **Source trees are never
+touched** — an app's and a lib's own `public/` keep every file, because one shared font folder is picked over
+differently by every app that mounts it and by other repos.
+
+```ts
+const config: LibConfig = { assets: { keepFonts: ["fonts/Assistant-*.woff2"] } }; // libs/<lib>/akan.config.ts
+const config: AppConfig = { assets: { pruneFonts: false } }; // emergency valve, not the normal escape hatch
+```
+
+- **A font with `optimize` on is a build input, not a runtime asset.** `FontOptimizer` subsets it into
+  `.akan/artifact/fonts` and the emitted CSS points at `/_akan/fonts/*`, which `WebRouter` serves from the
+  artifact — so the source in `public/` is never opened again. That is the bulk of what this drops, and it
+  applies to the fonts the app *does* use, not only the ones it does not.
+- **The keep-set is derived per app, per build; there is no list of fonts to drop.** An exclude list would rot
+  the moment another app or repo started using one of them, and nobody would know to update it. A font survives
+  because ① its font declares `optimize: false`, so `FontCss.getRuntimeCss` emits the raw src; ② something
+  references its filename — anything under `public/`, the compiled stylesheet, a client/server bundle, the CSR
+  shell; or ③ a `keepFonts` glob names it.
+- **`keepFonts` belongs to the `akan.config.ts` that owns the font**, written against that lib's or app's own
+  `public/` (`"fonts/X.woff2"`, resolved to `libs/<lib>/fonts/X.woff2`). A lib shared across repos carries the
+  reason its own CSS needs a font, instead of every mounting app rediscovering it in production.
+- **A reference from a build bundle is ignored for an already-subset font.** Every route file's `fonts`
+  declaration is inlined into the pages bundle, the client chunks and the CSR shell, so a declared source is in
+  all three whether or not anything loads it. `public/` and the compiled CSS are read as authoritative.
+- **A generated manifest that lists every public asset keeps every font it names** — a service-worker precache
+  file is the usual one. That is a real reference, not a false positive, so the build reports it at `info`:
+  read the `[font-prune] kept …` line before concluding the prune does nothing.
+- Matching is by filename, including the percent-encoded spelling, so a `url()` survives however it is written.
+- The phase is `assets`, between `csr` and `compress`. An api-only build (`web: false`) copies no `public/` and
+  the phase finds nothing to do.
+

package/guidelines/ssrRule/ssrRule.instruction.md

@@ -71,18 +71,62 @@ Never collapse this into one client file with a mode `useState` and every panel
 
 **③ Sync state instead of fetching it.** A server component cannot hold state, so render the initial data on the
 server and hand it across as a serializable object. The route calls `fetch.initXInY(...)` / `fetch.viewX(...)` and
-passes the result into a `Zone`; `Load.Units` / `Load.View` hydrate the store from it. A `useEffect(…, [])` that
-fetches on mount renders an empty shell, hydrates, then round-trips for data the server already had.
+passes `xInitInY` / `xView` into a `Zone`; `Load.Units` / `Load.View` hydrate the store from it. A
+`useEffect(…, [])` that fetches on mount renders an empty shell, hydrates, then round-trips for data the server
+already had.
 
 **④ Push the boundary down to the leaf that needs it.** A store-reading `Zone` should hold zero markup and delegate
 to a server `View` — `User.Zone.Self` is one line, `st.use.self()` into `<User.View.General user={self} />`, so the
 whole detail surface renders server-side wherever a route uses the `View` directly.
 
-**⑤ Hand the promise across, not the awaited value.** `ClientInit` / `ClientView` are `PromiseOrObject<T>`, so a
-route may pass an unawaited `fetch.initX(...)` and `Load.*` resolves it behind a skeleton. `await` blocks the shell
-for data the page needs immediately; the promise streams the rest. Independent fetches still go through one
+**⑤ Hand each promise across, not the awaited value.** `fetch.init<Model><Suffix>`, `fetch.view<Model>` and
+`fetch.edit<Model>` are awaitable *and* destructurable, so a route can split one call into the promises its
+sections actually need:
+
+```tsx
+export default async function Page({ params: { orgId } }: PageProps) {
+  const { taskInitInOrg, taskListInOrg } = fetch.initTaskInOrg(orgId);
+  const { orgView } = fetch.viewOrg(orgId);
+  return (
+    <>
+      <Org.Zone.Header view={orgView} />
+      <Task.Zone.Card init={taskInitInOrg} />
+      <Load.Stream of={taskListInOrg} fallback={<Loading.Skeleton active />}>
+        {(taskList) => taskList.map((task) => <Task.Unit.Row key={task.id} task={task} />)}
+      </Load.Stream>
+    </>
+  );
+}
+```
+
+Both queries leave immediately — splitting the result never serializes them — and each section renders behind its
+own boundary as its own data lands, so one slow query no longer holds the page. `x<Slice>List` does not wait for
+the aggregate the way `x<Slice>Init` must.
+
+**`await` is still the right call for what the page needs immediately.** It returns the shape the helper always
+gave and keeps that markup in the shell, which is what SEO snapshots, prerendering and pre-hydration E2E read; a
+boundary moves its subtree out of the shell and into the stream. Independent awaited fetches still go through one
 `Promise.all`.
 
+Three rules the shape enforces:
+
+- **`x<Slice>List` and `x<Slice>Insight` are server-only.** They hold hydrated model instances, which React Flight
+  refuses as props to a client component. Consume them in a server component; `x<Slice>Init` (plain data) is the
+  one that crosses into a `Zone`.
+- **Never hand the whole handle to a component** — pass the field. `<Zone init={xInitInY} />`, not
+  `<Zone init={fetch.initXInY(id)} />`.
+- **Rendering the list on the server costs one extra hydration.** `Load.Stream` builds the model instances on the
+  server and `Load.Units` builds them again after hydration, so a large list is still better off going through
+  `x<Slice>Init` → `Zone` alone. Reach for `Load.Stream` when the markup is small and static enough that having
+  it in the HTML is worth more than the second pass.
+
+**A failure now surfaces where it happened.** One `Promise.all` in the page body reports nothing about which of
+eight queries threw; per-section boundaries put each rejection at its own boundary.
+
+**Keep the auth gate in the shell.** A redirect thrown after the shell has flushed can only be delivered as a
+soft-redirect script, so `getSelf({ unauthorize: "/signin" })` stays in `_layout.tsx` or the page body — never
+inside a streamed section.
+
 **⑥ Use named `ReactNode` slots, not just `children`.** `Layout.Navbar` accepts `title`, `back`, `left`, `right`,
 and `children`, so a client shell composes server-rendered content in five places instead of absorbing it.
 

package/guidelines/transportRule/transportRule.generate.json

@@ -0,0 +1,31 @@
+{
+  "title": "Transport Rule",
+  "description": "How a call reaches an Akan signal — guards across HTTP and websocket, socket identity and cleanup, binary pubsub frames, and mutation HTTP verbs",
+  "group": "core",
+  "codegenPriority": 4,
+  "deprecated": false,
+  "scans": [
+    {
+      "type": "example",
+      "description": "Guard classes and their scope markers",
+      "path": "{apps,libs}/*/srvkit/guards.ts",
+      "sample": 2
+    },
+    {
+      "type": "example",
+      "description": "Signal endpoints declaring guards, pubsub, and message handlers",
+      "path": "{apps,libs}/*/lib/*/*.signal.ts",
+      "sample": 4
+    }
+  ],
+  "update": {
+    "filePath": "./transportRule.instruction.md",
+    "contents": ["guards across transports", "signal body types", "binary pubsub", "mutation HTTP verbs"],
+    "rules": [
+      "Use current Akan APIs only",
+      "State the rule and the reason it exists, never restate a type signature",
+      "Say what leaks or breaks when a rule is ignored",
+      "Keep it workspace-neutral — no app or repo names"
+    ]
+  }
+}

package/guidelines/transportRule/transportRule.instruction.md

@@ -0,0 +1,60 @@
+# Transport Rule — Guards, Sockets, Binary Frames, HTTP Verbs
+
+How a call reaches a signal: what a guard may read on either transport, how a websocket carries its credential
+and its per-connection state, when a pubsub payload leaves JSON for a binary frame, and which HTTP verb a
+mutation is mounted under. `conventions` carries the invariants — this is the full contract behind them.
+
+## Guards And Transports
+
+- Guards run on both HTTP and websocket calls. Read the caller with `context.get<T>("account")` (`pkgs/akanjs/signal/signalContext.ts`) instead of branching on `getHttpContext()` / `getWebSocketContext()`.
+- Slice-level `guards` only reach the generated query/mutation endpoints. A `pubsub`/`message` endpoint is unguarded unless it declares its own `guards` in its signal option.
+- A pubsub room is authorized once, at subscribe. When a socket's credential changes the framework re-runs each room's guards and unsubscribes the ones that now fail (`SignalResolver.revalidateWsRooms`), so guards must stay side-effect free and safe to re-run.
+- A websocket carries its credential in the handshake snapshot on `ws.data` (`AppWsData`); clients that hold the token in memory send it with `fetch.setJwt(...)`, which forwards an auth frame over the socket.
+- **Never read the caller's IP off the socket or the request peer — take `.with(Ip)`.** Whenever a federation
+  gateway is in front, `ws.remoteAddress` and the child's own peer are the *gateway* (`127.0.0.1`) for every
+  caller and for the whole life of every socket. `Ip` reads what a proxy recorded (`x-real-ip`, then the first
+  `x-forwarded-for` entry) and falls back to the peer only when nothing proxied the call — which is the answer
+  for a solo process behind an ingress that sets neither; `context.getClientIp()` is the same answer inside a
+  guard or middleware. It arrives unwrapped from
+  its `::ffff:` IPv4-mapped form, so it can address a `udp4` socket as well as identify a caller, and it is
+  `null` rather than a placeholder when genuinely unknown — a loopback-looking address for an unknown caller
+  is the failure this replaced. The gateway also forwards the client port (`x-forwarded-port`, read with
+  `context.getClientPort()`) along with host and protocol.
+- **Every socket carries a `socketId`, and only the framework mints one.** `AppWsData` assigns it at the handshake, and a `message` / `pubsub` handler reads it off the `Ws` internal arg — `.with(Ws)` hands `{ ws, socketId, subscribe, on, off }`. Never mint your own from `ws.data`: the room bookkeeping keys on the framework's id, and a second one fails to match it silently. It identifies a **connection**, not a caller — a reconnect gets a new id and the federation gateway's own socket is a different one — so per-user state keys on the account, never on this.
+
+- **A cleanup registered with `ws.on("disconnect" | "unsubscribe", fn)` is scoped to the call that registered it.**
+  From a `pubsub` subscribe it belongs to that room — `unsubscribe` runs when the client leaves it or a credential
+  change revokes it, `disconnect` when the socket closes while still subscribed — so a room already left runs
+  neither again, and cleanup that must happen either way registers for both. From a `message` handler it belongs to
+  the socket and runs at close. A handler that throws is logged and never blocks the rest of the teardown.
+
+## Binary Pubsub
+
+- **`pubsub(Binary)` sends its payload in a websocket binary frame**, skipping the JSON `{ type: "pub" }`
+  envelope and the base64 a JSON wire would need. The client's subscribe callback receives a `Uint8Array`.
+  Nothing else is declared: the return type is the whole switch, and text and binary frames coexist on one
+  socket, so every JSON endpoint is untouched. The optimization applies only when the **whole** return is
+  `Binary` — `[Binary]`, or a `Binary` inside a model, falls back to base64.
+- **A declared `Binary` room coalesces under backpressure**: while a socket cannot keep up the room keeps only
+  its newest frame and drops the rest, which is what a telemetry or video stream wants. Declare
+  `pubsub(Binary, { backpressure: "queue" })` when the frames are a sequence a subscriber must see in full, such
+  as deltas against a base it already holds; the send buffer then grows with the slowest subscriber. Coalescing
+  is keyed by the endpoint, not carried with the frame, so this process, an IPC deliver and a Redis fan-out all
+  reach the same answer. Coalesced frames are counted in `pubsubCoalesceCount` on the replica's metrics report.
+- **A `pubsub(Any)` that happens to carry bytes is framed too, and warns once.** `Any` passes a `Buffer` through
+  untouched, so the transport sees bytes and sends them whole rather than as a number array — an undeclared
+  publisher is fixed rather than left corrupt. It is still not the contract: it queues rather than coalescing
+  (nobody declared lossy delivery for that room), and a Redis fan-out still JSON-stringifies it. Declare
+  `Binary`.
+- The federation gateway relays a binary frame unchanged, and Bun IPC carries bytes as bytes, so the only hop
+  that needed teaching was the socket itself. A cross-server (Redis) fan-out encodes it as protobuf `bytes`.
+
+## Mutation HTTP Verb
+
+- A `mutation` is `POST`. `{ method: "PATCH" | "PUT" | "DELETE" }` moves it, and one path may carry several verbs
+  — a `query` GET and a `mutation` POST on the same custom `path` are mounted side by side. Two endpoints claiming
+  the same path **and** verb fail the boot rather than silently shadowing one another.
+- Reach for it only when a foreign wire protocol forces the verb (a client you cannot change that sends
+  `PATCH /rest/v1/<table>`). Akan's own `fetch.*` client, the OpenAPI document, and the API explorer all follow
+  whatever is declared, so nothing needs restating per caller.
+