@akanjs/cli 3.0.0-alpha.11 → 3.0.0-alpha.111

package/guidelines/queryRule/queryRule.instruction.md

@@ -0,0 +1,178 @@
+# Query Rule — Filters, Slices, Hydration, Search, Cascade
+
+How a model's data is queried, exposed to a client store, searched, and removed. Filters and slices are the two
+query surfaces; `q.search()` and the `text` field roles are the search surface; `cascade` is what a removal takes
+with it. `conventions` carries the invariants — this is the full contract behind them.
+
+## Slices, Queries, and Hydration
+
+- **The root slice (`""`, generated by `slice()`) takes `queryKey` and `args`, not a query.** `initX("byOwner",
+  [ownerId])` names one of the model's own filters and passes that filter's args; no key at all is the `any`
+  filter every model carries. A raw query descriptor let a caller compose a query the model never declared, and
+  could not survive the query string at all — `String(value)` sends `[object Object]`. Args are parsed by the type
+  the filter declared, a missing required one is refused, and args past the declared ones are dropped
+  (`resolveFilterQuery`, `pkgs/akanjs/document/filterMeta.ts`). It is an admin API: `root:` is always `Admin`.
+- **Give an id filter arg a `ref` and the admin panel stops asking for hex.** `filter().arg("ownerId", ID, { ref:
+  "user" })` names the model the id points at; the arg then renders a picker that runs the same query maker against
+  that model's own filters, so a ref of a ref keeps nesting. The picker holds its rows in local state rather than the
+  ref model's store — that store is a singleton, and loading into it would overwrite whatever listing of the same
+  model is already on screen. `ref` is the only UI hint a filter arg carries; there is no render callback, because a
+  function cannot cross to the client.
+- **A summary counter names the listing it counts, on the field itself.** `field(Int).meta(getQueryMeta("user")
+  .query("byStatuses").args([["prepare"]]))` is what makes the dashboard tile clickable: clicking it applies that
+  filter to the listing in place — one request, no navigation — and fills the arg controls under the toolbar, so
+  the filter is visible and editable rather than opaque. `args` may be a thunk (`() => [dayjs().subtract(1,
+  "hour")]`), read at the click so a relative time is current. A meta naming a different model counts a different
+  listing, so its tile stays inert here. `AdminPanel`'s `queryMap` still overrides per column, and is now only for
+  a column whose field cannot declare one.
+- **A picker row is labelled by `labelOf`, which reads `Light<Model>.label()` first.** Then the field carrying
+  `text: "title"`, then `title` / `name`, with the id as the floor. Write the method on the Light class — that is
+  where display logic belongs, and the same label is what `Load.Units` and the in-page agent's screen scope show.
+  A model with none renders ids and says so in the picker.
+- A slice's `exec` returns a `QueryOf` (an opaque query descriptor, `pkgs/akanjs/constant/types.ts`); you **cannot** chain `.sort()`/`.limit()` on it.
+- Apply ordering/paging via the store `init` fetch option instead: `initX(..., { sort, page, limit })` (`pkgs/akanjs/fetch/fetchType/sliceFetch.type.ts`).
+- **A slice list is either one window or an accumulated one, and the store says which.** `setPageOf<Model>` swaps
+  the window and `pageOf<Model>` names it; `loadMoreOf<Model>()` appends the rows *after* the ones already loaded
+  and takes no page number, because in an accumulated list no page number names anything. It skips by
+  `<model>List.length` rather than by `page * limit`, which is what keeps the offset from drifting from what is on
+  screen: a live insertion at the front moves the server's baseline by one, so a page number asks for rows the
+  list already shows. It also leaves `pageOf<Model>` at 1 — live placement is refused anywhere but the first page,
+  so paging by number used to switch live sync off permanently on the first "more", silently. `isCumulativeOf<Model>`
+  is the mode, and it is what stops a live insertion from truncating an accumulated list back to one page's worth.
+- **"Is there more" is `hasMoreOf<Model>`, never `count > page * limit`.** It is set from the length of the batch
+  the server just returned, so it survives `{ insight: false }` — which makes no count query at all — and cannot
+  drift from the count a live event moved. `loadMoreOf<Model>()` is a no-op once it is false, and `Load.Units`
+  draws no infinite-scroll sentinel.
+- Generated list accessors like `listBy(...)` return `Promise<Doc[]>`. For a chainable builder (`.sort().skip().limit().select()`) use the model facade's `findMany`/`findOne` (`FindManyChain`, `pkgs/akanjs/document/into.ts`).
+- **Hydrated vs raw:** server queries return hydrated `cnst.<Model>` instances (with `set`/`save`/`refresh`); client fetch results are raw `GetStateObject` plain data (functions stripped, `pkgs/akanjs/base/types.ts`).
+- Every filter generates fourteen methods: `list` · `listIds` · `find` · `findId` · `pick` · `pickId` · `exists` ·
+  `count` · `insight` · `query` · **`remove`** · **`removeOne`** · **`update`** · **`updateOne`**. The last four are
+  query-level writes — one atomic UPDATE, **no hooks**, and therefore no `_postRemove` and no cascade. Use them on a
+  model that carries no removal side effect; otherwise remove documents one at a time.
+- **`update<Filter>` / `updateOne<Filter>` are chains, not calls:** `await updateInRoot(rootId).set({ status:
+  "archived" })`. The patch cannot trail the filter args — a filter's own args may be optional and no tuple type
+  puts a required element after those — so it lands on a terminal `.set()`, mirroring the `UPDATE … SET …` it
+  compiles to. Building the chain touches nothing; only `.set()` runs a query.
+- `removeOne` / `updateOne` hit the **newest** match — the subquery they compile to is ordered `createdAt` descending
+  and there is no way to change that. They also report only counts, never which row they touched, so they are for
+  "there is at most one of these", not for claiming the next item off a queue. Pass a query that matches one row.
+- **A filter may not be keyed after its own model.** Filter methods are assigned after CRUD, so a filter `chat` on
+  model `chat` would silently swap the single-document `removeChat`/`updateChat` for a hookless query-level one. It
+  throws at boot instead (`assertFilterFitsCrud`).
+- **"Has no value" is `q.empty`, never `q.missing`.** The three absence operators are distinct: `q.exists` is the
+  key being present, `q.missing` is the key being *absent from the stored JSON*, and `q.empty` is either — absent,
+  or present and null. An optional field is written both ways over its life: an insert that omits it leaves the key
+  out, while a document read back and saved carries the explicit `null` that the read materialized. So `q.missing`
+  matches a freshly inserted row and silently stops matching that same row after its first round-trip save. Reach
+  for it only to find rows written before the field was declared.
+
+## Text Search In A Filter — `q.search()`
+
+- Text search is a filter query node like any other: `bySearch: filter().arg("text", String).query((text, q) =>
+  q.search(text, { prefix: true }))`. The generated `listBySearch` / `countBySearch` / `queryBySearch` /
+  `insightBySearch` come for free — you do **not** need a slice to make search usable.
+- **Only add a search slice when the model's data is safe to enumerate.** A filter is server-side; a slice is a
+  client-callable endpoint, so on a model whose slice `get:` is `Public` a search slice hands anyone a way to walk the
+  table. Leave that decision to the mounting app.
+- `q.search()` compiles to a JOIN, not a WHERE fragment, so it **must sit at an AND position**. Nesting it under
+  `q.any()` or `q.not()` throws, and it is rejected in `updateOneByQuery` / `updateManyByQuery` — a query-level write
+  takes no join, so ignoring the node would silently widen the write to every other matching row.
+- Blank or whitespace-only input matches **nothing**. Never "fix" that into a passthrough: a passthrough turns a
+  search endpoint into a full listing.
+- Order by relevance with the built-in `relevance` sort key. It is an empty sort map, which the store reads as
+  "unspecified": score order when a search join is present, `createdAt` descending otherwise. That fallback is the
+  compiler's own, not a model-defined default — redefining `latest` on the model does not change it.
+- **A slice endpoint never reaches "unspecified".** The resolver fills `latest` before the query is built, so a
+  client asking for the score order has to name `relevance`; leaving `sort` off gets `latest`, not relevance.
+- Scope a search with `columns` (`q.search(text, { columns: ["title"] })`) and re-weight with `weights`, a tuple of
+  finite numbers positional over `["title", "desc", "tag", "filter"]`.
+
+
+## Text Search Fields — the `text` role
+
+- A field joins the full-text index by declaring one of five roles: `field(String, { text: "title" })`, and likewise
+  `"desc"`, `"tag"`, `"thumb"`, `"filter"`. Nothing else opts a field in, and there is no per-model switch.
+- Pick the role by what the value *is*, because `bm25` weights them positionally (`title` 10, `tag` 3, `desc` 1,
+  `filter` 0): `title` is the one line a human scans for, `desc` is prose, `tag` is a keyword list, `filter` is a
+  scoping value (status, owner, role) that must be matchable but must never outrank a real title hit.
+- `thumb` is mirrored for rendering a hit and is **not** indexed — never expect it to match.
+- **`field.secret`, `field.hidden` and `resolve()` take no `text` role — it is a compile error**, because the
+  mirror is plaintext and an indexed secret would leak through search. The class build throws the same refusal as
+  a backstop, for an option object the excess-property check cannot see through, and names the way out: drop the
+  role, or leave the field unmasked. Do not work around either. The throw also covers a `text` field *underneath*
+  one of those — a scalar's own field is reachable through its parent, so `f.secret(Noti)` where `Noti.label`
+  carries a role is rejected at the parent, not silently indexed; that one is only reachable at runtime, since the
+  pairing spans two files.
+- The role works on a relation too (`image: field(File, { text: "thumb" })`) and on an array (`playing: field([String],
+  { text: "tag" })`); an array of objects indexes by leaf key, including an array leaf (`works[*].tags`). A field
+  inside a `Map` indexes nothing: there is no fixed path to extract it from.
+- Declaring roles is all the wiring there is. Mirror rows are maintained by SQL triggers — not document hooks —
+  because `updateOneByQuery` and friends fire no hooks, and most searchable-field mutations go through exactly that
+  path.
+- Search runs on sqlite/libsql only. `q.search()` against Postgres throws, loudly, rather than returning every row.
+- `AKAN_SEARCH_ENABLED=0` switches the index off process-wide; unset means on. It never deletes mirror data, and
+  re-enabling reconciles every ref. **Give every process the same value** — a process cannot drop triggers for models
+  it does not mount, so a mixed fleet leaves stale triggers behind.
+- The tokenizer is `AKAN_SEARCH_TOKENIZER` (or `database.search.tokenizer`, which wins), defaulting to
+  `unicode61 remove_diacritics 2`. Changing it rebuilds the index from the mirror on the next boot — the model
+  tables are never re-read — so it is a safe knob, unlike a `text` role change, which re-reads every row. The
+  rebuild takes no cross-process claim, so a fleet restarted at once repeats it in every process; stagger the
+  restart when the mirror is large.
+
+## Cascade Remove — the `cascade` option
+
+**The value names the direction, and getting it wrong is a data loss.** The two actions can sit on the same field
+shape, so `cascade` never means "related" — it means one of exactly these:
+
+- `removeRef` — *when I am removed, remove what this field points at.* Declared on the relation the owner holds:
+  `image: field(File, { cascade: "removeRef" })`, arrays included. Only a relation accepts it; a primitive, a bare
+  `ID`, and a scalar each fail the class build.
+- `removeWith` — *when what this field points at is removed, remove me.* Declared on the child's own reference to
+  its owner, so the owner never learns about its children and a lib model can be extended by an app's. Three forms:
+  a relation (`field(AgentSession, { cascade: "removeWith" })`), an id with `ref`, or a polymorphic id with
+  `refPath`. An array, a Map, `ref` together with `refPath`, and a field naming no owner each fail the class build.
+- **A `refPath` must name an `enumOf` field** — a free-form owner type is unknowable at build time, so every
+  model's removal would have to sweep the polymorphic table on the chance it is the owner.
+- **`cascade: "removeWithAny"` buys that sweep on purpose**, for the one shape an enum cannot express: a child
+  whose owner is any model in the app, named by a free-form `String` holding the owner's refName. It is a third
+  action rather than a flag beside `removeWith`, because the widening and the direction are one decision — the
+  option type pairs the action with the `refPath` it reads the owner off, so neither can be declared alone.
+
+  ```ts
+  parent: field(ID, { refPath: "parentType", cascade: "removeWithAny" }),
+  parentType: field(String),   // holds the owner's refName
+  ```
+
+  The lookup itself is cheap — the declaration auto-creates the same `{ removedAt, typeKey, fk }` index, so a
+  removal that owns nothing is one index probe returning zero rows, not a scan. **The price is bulk: one wildcard
+  edge anywhere turns every cascade in the app back to one document at a time**, because a query-level removal of
+  *any* model would be a removal whose wildcard children were never looked for. The boot log says so in one
+  `info` line naming the edges — that line is the answer to "why does this app remove everything per document".
+  The opt-in is what keeps an app that declared none on the fast path.
+
+  Refused at the class build: `removeWithAny` on a `refPath` that already names an `enumOf` (the enum names the
+  candidates and indexes better — use `removeWith`), a `typeKey` that is not a `String` (the sweep matches a
+  refName against that column, and a column that cannot hold one silently finds nothing), and the action with no
+  `refPath` at all — that last one is a typecheck error at the call site, and the class build keeps the same
+  refusal for the macro and bundled paths that reach it untyped. A wildcard owner is also exempt from the mount
+  check that a monomorphic owner fails at boot — it names no module to mount.
+- **A cascade goes through the target's service, never its model** — that path is what runs the target's
+  `_postRemove`, where a module puts the side effect the removal has to carry.
+- **Bulk is decided at boot, per target model, for both directions.** A target with no `remove` schema hook, no
+  `_pre`/`_postRemove`, no cascade of its own, and no children takes one `removeManyByQuery`. Adding a
+  `_postRemove` silently flips it back to one document at a time — the boot log is the only place that shows.
+- **The plan is sealed after every service is live**, so a `listenPost("remove")` registered in `onInit` counts,
+  and an unmounted `removeRef` target or `removeWith` owner fails the boot rather than the first removal. An
+  unmounted `refPath` candidate only warns, since that list spans optional modules by design.
+- **Nothing checks whether another document still references the same target.** `File` in particular is deduped
+  by `origin`, so two parents can share one row; `removeRef` claims the field owns its target exclusively.
+- Removal is soft (`removedAt`), but the storage delete a `_postRemove` performs is not — a cascade is not
+  restorable, and reviving the owner does not revive what went with it.
+- A `removeWith` declaration **auto-creates its index** (`{ removedAt, fk }`, or `{ removedAt, typeKey, fk }` when
+  polymorphic); every non-base field lives in the `_doc` JSON column, so the lookup would otherwise scan the table.
+- **Query-level removes fire no hooks and therefore no cascade** — `removeManyByQuery` / `updateManyByQuery`, the
+  generated `remove<Filter>` / `update<Filter>`, and the facade's `removeById` / `updateById`. Remove one document
+  at a time when it cascades.
+- Cascades are **idempotent**: `removedAt IS NULL` is ANDed into every query-level write. Cycles are cut by a
+  visited set carried down the whole chain, with a depth cap of 16.
+

package/guidelines/runtimeRule/runtimeRule.generate.json

@@ -0,0 +1,25 @@
+{
+  "title": "Runtime Rule",
+  "description": "Akan build and runtime surfaces — web/csr toggles, the gateway/solo process model, logging, the generated image, and shipped assets",
+  "group": "core",
+  "codegenPriority": 4,
+  "deprecated": false,
+  "scans": [
+    {
+      "type": "example",
+      "description": "App and lib runtime declarations",
+      "path": "{apps,libs}/*/akan.config.ts",
+      "sample": 4
+    }
+  ],
+  "update": {
+    "filePath": "./runtimeRule.instruction.md",
+    "contents": ["web surface toggles", "process model", "logging and live tail", "generated image", "shipped assets"],
+    "rules": [
+      "Use current Akan APIs only",
+      "State the rule and the reason it exists, never restate a type signature",
+      "Name the env that narrows a build-time declaration wherever one exists",
+      "Keep it workspace-neutral — no app or repo names"
+    ]
+  }
+}

package/guidelines/runtimeRule/runtimeRule.instruction.md

@@ -0,0 +1,220 @@
+# 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.
+- **`PORT` is the whole tree's port, and a server-side self-call follows it.** `AkanApp` resolves it once
+  (`new AkanApp({ port })`, else `PORT`, else 8282) and publishes it to the replica it runs in-process and to
+  every child it spawns — a federation child listens on a unix socket, but the loopback fetches its SSR and RSC
+  worker make still come back through the gateway. `getEnv().serverPort` reads it whenever the origin resolved to
+  `localhost`, so a container run with `PORT=80` calls itself on 80. Override the origin only when it is genuinely
+  not this process: `AKAN_PUBLIC_SERVER_PORT` outranks `PORT`, and a `SERVER_HOST` naming another host is not a
+  self-call and keeps its explicit port.
+- **`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,64 @@ 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 page()
+  .param("orgId", ID)
+  .render(async ({ orgId }) => {
+    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.
+