@akanjs/cli 3.1.0-rc.0 → 3.1.0-rc.10

package/guidelines/runtimeRule/runtimeRule.instruction.md

@@ -1,4 +1,4 @@
-# Runtime Rule — Serving, Processes, Logging, Image, Native Apps, Desktop Server, Assets, Build Pipeline
+# Runtime Rule — Serving, Processes, Dev Server, Logging, Image, Native Apps, Desktop Server, Assets, Build Pipeline
 
 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
@@ -114,6 +114,58 @@ worker per web-serving replica.
   `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.
 
+## The Dev Server And Local Runs — `akan start`
+
+- After changing application source code, test the app with `bun run akan start <appName>`; test production build
+  generation with `bun run akan build <appName>`.
+- **`akan start` takes several apps** — `akan start a,b`, `akan start a b`, `akan start all`, or no argument at
+  all for a checkbox that remembers the last pick.
+- **It opens a full-screen view by default, at any app count.** A rail of apps with the processes inside each
+  one — `host` for the dev host, gateway and RSC worker, plus a row per replica the gateway forwards — and the
+  selected one's log beside it. `Tab` walks every row and `1`-`9` jump to that app (the rail shows each app's
+  digit), `↑↓` scroll (shift for a page, `G` back to following), `/` greps, `e` shows stderr only, `c` clears,
+  `y` copies, `Y` copies the log path, `o` opens the browser, `r` restarts that app, `q` quits. Under `--share`,
+  `s` copies the public URL — the selected app's, or every app's from the merged row — and the header carries it
+  ahead of the local one, because the line `--share` printed before the view took the terminal is gone by its
+  first repaint. **`--plain` prints prefixed interleaved lines instead**, and a pipe, a redirect or an unsized
+  terminal downgrades to that on its own.
+- **A supervised session writes `local/apps/<app>/runtime/dev.log`, and that path is how a log gets handed over.**
+  Ink repaints one frame in place, so the full-screen view leaves a bordered screenshot in the scrollback and takes
+  the rest of the session with it — a drag-selection is cleared by the next repaint, and what survives carries
+  borders and lines truncated to the pane. The file is the same output with no ANSI, nothing truncated, and every
+  process of the app in arrival order, including the dev host's own build output, which reaches no other file. The
+  previous session is kept beside it as `dev.prev.log`. Hand somebody — or an agent — the path rather than a paste:
+  it costs one line instead of a transcript, and it can be re-read after a fix. In the view, `y` copies the lines
+  the filters have already narrowed and `Y` copies the path.
+- **How many apps boot at once is the machine's answer, not a constant.** A cold boot is an app's RSS peak (~1.8GB
+  per app, most of it the build worker — the base build, then the SSR registry's), so the default wave is what
+  memory and cores allow — half the memory budget divided by that peak, and one app per four cores — which boots a
+  laptop's apps together and still staggers them inside a small container. The session says which in one line.
+  The next wave starts once an app serves and its boot builds have settled, or 30 seconds after it serves, while
+  the app shows as ready — and `--open` opens it — as soon as it serves. `--concurrency <n>` overrides the wave
+  size, and `AKAN_MEMORY_LIMIT` lowers the budget it derives from.
+- **`--kill` frees the dev ports first** — it resolves each port's listener, walks up to the top of that akan dev
+  tree and signals it, so another checkout's server or a stale orphan on the same port is reclaimed. A holder that
+  is not recognisably an akan process is reported and left alone.
+- **A dev server watches its own app directory and the libs it actually depends on**, transitively, resolved once
+  at boot from the synced manifests — so a save under a lib the app never imports rebuilds and reloads nothing,
+  and neither does a save in a sibling app. An import that makes a new lib a dependency needs a fresh
+  `akan start`, because it needs a `sync` first anyway. Before the first `sync` the manifests do not exist yet and
+  the whole `libs/` container is watched, which is the safe direction.
+- **A built artifact runs from the generated app directory** with the Akan runtime environment variables:
+
+  ```bash
+  cd dist/apps/<appName> && USE_AKANJS_PKGS=true AKAN_PUBLIC_REPO_NAME=<repo> AKAN_PUBLIC_SERVE_DOMAIN="<domain>" \
+    AKAN_PUBLIC_APP_NAME=<appName> AKAN_PUBLIC_ENV=local AKAN_PUBLIC_OPERATION_MODE=local SERVER_MODE=federation \
+    AKAN_PUBLIC_BASE_PATHS=<basePaths> bun main.js
+  ```
+
+- **A server a test boots in-process takes `start({ listen: false, schedules: false })`** to run no internal
+  (init, interval, cron, queue worker); `listen: false` alone still runs them, as a batch replica does. A server
+  process a test spawns from source resolves the workspace from its cwd and gets the root `.env` from Bun, so
+  spawn it inside the repo with `bun --no-env-file`, or spawn the built `dist/apps/<app>` output, which needs
+  neither.
+
 ## Logging — Records, Request Context And Live Tail
 
 Every `Logger` call builds a `LogRecord` before any text exists: `at`, `level`, OTel `sev`, `name`, `message`,
@@ -152,6 +204,18 @@ normalized to `info` with one warning.
 - **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`.
+- **`AKAN_LOG_FORMAT=ndjson` makes the container's stdout one JSON record per line, and the hub owner (gateway or
+  solo replica) its only writer** — every other server process turns its console off and forwards from
+  `AKAN_LOG_STDOUT_LEVEL` (default: the console level); a child's or the RSC worker's crash stack is wrapped as a
+  `raw=true` record instead of breaking the stream. Text stays the default; turn it on in the deployment.
+- **`AKAN_LOG_STREAM_TOKEN` mounts `/_akan/app/logs`** (SSE, `Last-Event-ID` resume, explicit `gap` events);
+  unset, the route does not exist.
+- **`AKAN_LOG_CANONICAL=1|slow`** writes one `ok|error <endpoint> ms= status=` line per call; **`AKAN_LOG_FLIGHT=1`**
+  keeps each call's last 64 sub-level records and promotes them (`flight=true`) only when it failed or ran past
+  `AKAN_LOG_FLIGHT_MS`; an `x-akan-debug` header lowers one request to `trace` — in `local`, or with the
+  `AKAN_LOG_DEBUG_HEADER` secret.
+- **Structured values go in `LogRecord.attrs` via `Logger.emit(...)`**; a key naming a secret is `[redacted]`
+  before the record exists.
 - **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.
 
@@ -257,9 +321,10 @@ const config: AppConfig = {
   Intel Macs are not a target, so `--arch x64` on macOS is refused.
 - **A release is signed only with `--sign` and notarized only with `--notarize`** (`build-desktop`,
   `publish-update`); the environment names the identity and never decides to use it, so a shell exporting a Developer
-  ID signs and uploads nothing unasked. Before either, the server the app carries is searched for every secret value
-  of the workspace's server env files and refused with the paths, and one line names the identity and the service
-  the app goes to.
+  ID signs and uploads nothing unasked. Every release build and every `publish-update` of a target that carries a
+  server, signed or not, first searches that server for every secret value of the workspace's server env files and
+  refuses with the paths; an env file it cannot evaluate stops the release too, and a debug build is not searched.
+  One line then names the identity and the service the app goes to.
 - **A macOS release for download is signed with a Developer ID and notarized.**
   `AKAN_NATIVE_MACOS_IDENTITY` names a keychain identity, or `AKAN_NATIVE_MACOS_CERTIFICATE` +
   `_CERTIFICATE_PASSWORD` a `.p12` the build imports into a keychain of its own (a CI runner);
@@ -280,12 +345,15 @@ const config: AppConfig = {
   key. List the online signing key first and offline spares after it (up to three): a phone binary trusts all of
   them, and a key may revoke only the keys listed before it, so a leaked key cannot lock out its spares. A desktop
   app trusts the first; `publicKey` is the one-key form. `akan publish-update <app>` builds and signs a release
-  into `updates/`: upload that folder to `url`, the manifests last, or let `--upload s3://<bucket>/<prefix>` do it
-  (credentials and endpoint from `S3_*` or `AWS_*`; a release file the bucket holds is skipped). A phone reads only
-  `<url>/<platform>/<channel>/<nativeApi>.json`, so each store generation on a channel takes its own fixes.
+  into `updates/`: upload that release's files to `url` and its manifest last, or let
+  `--upload s3://<bucket>/<prefix>` do it (credentials and endpoint from `S3_*` or `AWS_*`; a release file the bucket
+  holds is skipped), which sends that release alone, and nothing when it is missing or fails a check. Never upload the
+  folder whole: a phone's is also where `pack-update` writes by default.
+  A phone reads only `<url>/<platform>/<channel>/<nativeApi>.json`, so each store generation on a channel takes its
+  own fixes.
   `akan pack-update` writes an unsigned phone bundle for whoever holds the key to sign and records it in
   `<out>/pack.json`, exiting 2 when `--against` says it needs a new store build; `akan push-update` packs and uploads to
-  an akasys project that holds the key, and `akan register-binary` registers a store build after `release-*`. A
+  the Akan Cloud project that holds the key, and `akan register-binary` registers a store build after `release-*`. A
   release that hangs is rolled back while the app runs, and `report: { url }` has a phone post what became of each
   release (applied, confirmed, rolled back and why) at its next launch, so rollback rates are visible. `devtools: true`
   opens the web inspector of a release build for an internal test target. The channel is the backend env the binary was built for unless `channel` names one;
@@ -307,10 +375,11 @@ const config: AppConfig = {
   their page paints, so a dark board never flashes white, and `desktop.publisher` names who publishes a Windows app in
   Apps & features and its executable's company (the app name when unset, never Bun's own).
 - **A third-party page shown first-party** — a scoreboard, a menu board — is the `external-view` plugin, listed in
-  `native.plugins`: a webview over the window with a browser profile of its own, held to the origins it was opened
-  for, with an init script, `evaluate`, a trusted `sendKey`, `capture`, and `loadFailed` / `gone` (it reloads, or is
-  rebuilt, by itself) / `consoleMessage` events. Every method on Windows; macOS 14+ lacks `sendKey`, `setMuted` and
-  `capture`.
+  `native.plugins`: a webview over the window with a browser profile of its own, its top level held to the origins it
+  was opened for while its frames load web content from anywhere, with an init script that runs in the top document
+  only, `evaluate`, a trusted `sendKey`, `capture`, and `loadFailed` / `gone` (it reloads, or is rebuilt, by itself;
+  the reason is `terminated` on macOS, and `rebuildFailed` when a rebuild failed and the view is closed, to be opened
+  again) / `consoleMessage` events. Every method on Windows; macOS 14+ lacks `sendKey`, `setMuted` and `capture`.
 
 ## A Desktop App's Server — `bin` And `trustedDependencies`
 
@@ -326,7 +395,7 @@ has none, or none when it has one, is refused, and switching means a reinstall.
 tied to the image's system, code only a process the app never starts loads — and whatever only they pull in; the
 image keeps them, and the server's own bundle must not import them. A package another dependency still installs
 stops the build, naming who needs it. So does a native addon that would not load on a user's computer: no binary
-for the app's OS and CPU, a link outside the system, or a `binding.gyp` its install never compiled. It runs as an API-only edge server on SQLite, on a loopback port the launcher picks — the last session's when
+for the app's OS and CPU, a link outside the system, or a `binding.gyp` its install never compiled. It runs as an API-only edge server in database mode `single` (SQLite), on a loopback port the launcher picks — the last session's when
 it is free, which is not a guarantee, so a provider that needs an exact redirect URI signs in through a cloud
 server's adapter. It refuses a `Host` other than its own, but any program on the computer can still call that port:
 guard its endpoints as a network server's. It runs in one process, so a `main.ts` or an env asking for replicas (`replica`,
@@ -416,10 +485,14 @@ in those alone, and `modules: ["@edge"]` (or `AKAN_MODULES=@edge`) names every m
 inject, cascade to and hold a relation to. `desktop: { server: { profile: "edge", modules: ["@edge"] } }` builds the
 carried server that way: `env/env.server.<env>.edge.ts` is bundled in place of `env/env.server.<env>.ts`, which never
 enters it, and the build evaluates the profile file with no app env and refuses one whose secret-named keys hold a
-value — a `process.env.X ?? "literal"` counts as the literal. Each lib's env defaults (`env.server.testing.ts`) are
+value — a `process.env.X ?? "literal"` counts as the literal. Signing, encryption, master and session keys, `pwd`, a
+`…dsn` and a connection string are secret-named, and a URL holding a password or a secret-named query parameter is a
+secret under any key. The profile may spread `libEnv`, and the lib defaults it reaches are checked as the bundle
+carries them; a profile that imports the file it replaces is refused. Each lib's env defaults (`env.server.testing.ts`) are
 swapped the same way: for the lib's `env/env.server.testing.edge.ts`, held to the same check, or for the defaults with
-every secret-named value left out, which the build names in a warning. `akan build <app> --profile edge` does the
-same for an image. A module listing only edge does not mount under `akan start` (local): list `local` too to develop
+every secret-named value left out, which the build names in a warning — and a default a JSON snapshot cannot carry (a
+function, Map, Set, Date, class instance, bigint or non-finite number) is refused unless the lib has its profile file.
+`akan build <app> --profile edge` does the same for an image. A module listing only edge does not mount under `akan start` (local): list `local` too to develop
 it there.
 
 **A file the user picks reaches the server as a grant, never as a copy or a path.** With `"file-picker"` in
@@ -444,6 +517,29 @@ page API is
 hook; `volume` and `filePicker` also come from `akanjs/client/native` itself. A capability the shell
 lacks is added there: an app's own plugin runs as Bun code in the plugin host and cannot add a native shell op.
 
+**A plugin the app or lib owns lives in `native/<id>/`**, the folder named after the plugin id: `native-plugin.json`
+beside its page API (`src/index.ts`, `definePlugin` from `akanjs/client/native`), its desktop part (`src/desktop.ts`,
+`defineDesktopPlugin` from `akanjs/native/desktop`), Kotlin and Swift. Every mobile and desktop target ships it; a
+lib's reach only the apps that depend on it, and the app's own wins an id. Its page API is imported by a `webkit/`
+hook (`../native/<id>/src`) and nothing else; pages and components call the hook, the same way they reach
+`akanjs/client/native`. A plugin throws `AkanNativeError`, the error its bridge carries back to the page, which is
+why `no-throw-raw-error` exempts a root `native/` folder.
+
+**A page's storage and browser APIs follow the shell, not the browser.** A native shell serves the page from
+`app://localhost` on iOS, macOS and Linux, which keeps no cookies: `document.cookie` reads `""` and a write is
+dropped, so the value exists in the browser and vanishes in the app. Web Storage does work in the shells, but it
+bypasses the store akanjs picks per platform (the shell's Preferences in an app) and throws during SSR. So app and lib
+code never touches `document.cookie`, `localStorage` or `sessionStorage` (`no-document-cookie`, `no-web-storage`): it
+uses `getCookie` / `setCookie` / `removeCookie`, `storage`, and `secretStorage` for tokens and credentials, all from
+`akanjs/client`. `setCookie` writes `path=/; SameSite=Lax; Secure`, and an options object overrides only the keys it
+names — pass `sameSite: "none"` only for a cookie a cross-site POST must carry back. Browser APIs an app WebView lacks
+stay in a `webkit/` hook that branches on `isNativeApp()` from `akanjs/client/native`, which is where the app side goes
+too (`no-web-only-api-outside-webkit`, a warning): `navigator.share` / `canShare` (Android's WebView has none),
+`navigator.serviceWorker` and `Notification.requestPermission` / `.permission` (no app page has them),
+`navigator.geolocation` (use `useGeoLocation` from `akanjs/webkit`) and `navigator.vibrate` (iOS has none; use
+`haptics`). They are legal on the web, so the rule does not ban them; a root `native/` folder is out of its scope,
+since a plugin's web part is where those APIs belong.
+
 ## Database Modes — `database` In `akan.config.ts`
 
 | mode | database | cache · queue · pubsub | runs as |
@@ -556,7 +652,7 @@ const config: AppConfig = { assets: { pruneFonts: false } }; // emergency valve,
 
 Akan Cloud builds and deploys each app as `build` → `docker` → `deploy`, and `ota` after them when asked. **An app's own stages go in
 `apps/<app>/akan.config.ts` under `pipeline`; stages around every app go in the workspace root's
-`akan.config.ts`**, typed `WorkspaceConfig` (`before`, `after`, `post`, `env`, `timeout`). Both are `import type`
+`akan.config.ts`**, typed `WorkspaceConfig`, under its own `pipeline` (`before`, `after`, `post`, `env`, `timeout`). Both are `import type`
 objects (or `(ctx) => …`), and `akan pipeline dry-run | validate | plan` turns them into the plan Akan Cloud runs —
 locally, running nothing.
 

package/guidelines/ssrRule/ssrRule.instruction.md

@@ -38,6 +38,19 @@ A third-party client package and the `ui/<Folder>/index_.tsx` + `lazy()` boundar
 not flagged. Interaction-driven `fetch.*` inside an `onClick` is not flagged either — only mount-time loads are,
 because those are the ones the server could have performed.
 
+## Lint Rules Behind The Boundary
+- `no-async-component-in-ui` (`{apps,libs}/**/ui/**/*.tsx`) — React has no async client component, so a `ui/`
+  component that awaits breaks as soon as a client parent renders it, and the load drops below the route, which
+  could have started it before the first byte. Only a PascalCase binding whose own initializer is `async` is matched,
+  so an async handler inside a synchronous component and `lazy(async () => import(…))` are untouched.
+- `no-init-fetch-in-client` — `fetch.init<Model><Suffix>` and `fetch.get<Model>Init<Suffix>` compose the slice's list
+  and insight queries into the hydration snapshot `Load.Units` / `Load.View` seed the store from. From a route it
+  resolves before the first byte; after hydration it is two extra round-trips for a shell the browser already
+  painted. Load it in the page and pass the result (or the unawaited `x<Model>Init<Suffix>` promise) down as `init`,
+  and reload from the client through the generated `st.do.init<Model><Suffix>()`. The rule is gated on the real
+  `"use client"` directive plus `*.store.ts` and matches by shape (`init` + `Capitalize<refName>` +
+  `Capitalize<suffix>`), so a hand-written `initPayment` is out.
+
 ## Implementation Playbook
 
 **① Wrap the interaction, not the UI.** The smallest useful client component adds one behaviour and renders

package/guidelines/transportRule/transportRule.instruction.md

@@ -1,13 +1,20 @@
-# Transport Rule — Guards, Sockets, Binary Frames, HTTP Verbs
+# Transport Rule — Guards, Sockets, Deadlines, Rate Limits, Server-To-Server Calls, Bytes, 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.
+and its per-connection state, how long a call may take and what it may cache or count, how one server calls
+another, which body types and bytes cross the wire, 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.
+- **Every endpoint that declares no guards is named in a boot `warn`**, since it answers anyone over HTTP and
+  WebSocket — a named slice's `init()`, a root slice, a `pubsub`/`message`/`query`/`mutation`. Write
+  `guards: [Public]` to keep one open on purpose.
+- **A generated verb is taken off HTTP with `guards: { cru: false }`** (or `get`/`create`/`update`/`remove:
+  false`), and a verb whose guards resolve to none is not mounted at all. `mcp: { cru: false }` does **not** do
+  this: it keeps the verbs off the agent shelf while HTTP serves them to whoever passes their guards.
 - 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. Each re-check runs on a fresh `SignalContext`, so a guard that memoizes per context answers anew.
 - **Arguments are parsed after the `"account"` guards** (`SignalContext.init` reads the body, `exec` parses): the order is middlewares → `account` guards → parse → `resource` guards → internal arguments → handler, whatever order `guards: [...]` lists them in. A caller an account guard refuses never reaches a scalar parser, which is what keeps a slow parser from being a pre-auth denial of service. A guard or middleware that reads `context.args` / `getArg()` earlier still gets the value, parsed on first read — a mismarked account guard keeps working. One visible consequence: an unauthenticated call with a malformed argument answers 401/403 instead of 400.
 - 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.
@@ -24,7 +31,8 @@ mutation is mounted under. `conventions` carries the invariants — this is the
 - **A device or another server proves itself with a machine token.** `MachineToken.issue({ kind, id, version },
   { expiresAt? })` in `akanjs/server` signs an EdDSA JWT (`typ: akan-machine+jwt`, `aud: <app>/<environment>`) with
   `AKAN_MACHINE_PRIVATE_KEY`; it never expires unless asked. `akan machine-keygen <file>` writes that key to a file
-  and prints only the public one. A server with either key verifies the bearer of every call — HTTP, and the
+  and prints only the public one. A server with either key (`AKAN_MACHINE_PRIVATE_KEY` or
+  `AKAN_MACHINE_PUBLIC_KEY`) verifies the bearer of every call — HTTP, and the
   websocket's auth frame — after every lib middleware, and sets `account.machine = { kind, id, version }` from a
   verified token; it takes off a `machine` any other middleware or a session's claims put there, so a staff token
   can never pass for one, and a session middleware already reads the EdDSA token as anonymous. `.with(Machine)` hands
@@ -47,14 +55,37 @@ mutation is mounted under. `conventions` carries the invariants — this is the
   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.
+- **A subscribe the client leaves before it finishes joins nothing.** When an `unsubscribe` for the room, or the
+  socket's close, arrives while the subscribe is still running, the subscribe answers `subscribe: false` and runs its
+  `unsubscribe` cleanup (and its `disconnect` one when the socket closed) instead of joining the room.
+
+## Writing A Guard
+
+- **Resource guards are `Can<Verb><Model>` classes in `srvkit/guards.ts`** that `implements Guard` with an
+  `async canPass(context)`. They **fail closed**: no resource named ⇒ `false`; a load that throws ⇒ `logger.warn`
+  then `false`. Admin bypass goes first.
+- **Keep `static name = "User";` on guard classes.** `fetch` serializes guard names and the API explorer filters
+  on them; it looks like dead code, and deleting it breaks the UI. Comment it so the next reader knows.
+- **Every guard class declares `static scope: GuardScope`, required with no default.** `"account"` means the
+  verdict reads the caller and nothing about the call, so it can be evaluated with no arguments — which is what
+  lets an MCP listing hide what this caller certainly cannot use. `"resource"` means it needs the call's arguments
+  (`context.getArg()`) and fails closed without them, so it is never evaluated for a listing: the entry stays
+  visible and is stopped at call time. Getting it wrong is not a type error, so the marker is mandatory rather than
+  defaulted — `SignedIn` / `Admin` / role checks are `"account"`, and every `Can<Verb><Model>` is `"resource"`.
+  What a mismarked guard does to a listing, and `static agents = false` on `Person`: `mcpRule`.
+- **Guards ship with the library that owns the model** and are imported by its own signals through the package
+  path, so a mounting app inherits authorization and cannot forget it.
+- The acting user arrives via `.with(Self)` / `.with(CurrentUserId)` / `.with(Me)`; never trust a client-supplied
+  id. Services re-check ownership even when a guard already gated the call — two independent gates.
+- `srvkit/guards.ts` earns real comments: explain what would leak without each guard.
 
 ## Request Deadlines
 
 - **`{ timeout: <ms> }` in an endpoint's signal option is the whole configuration surface**, and it reaches both
   ends of the call. Server side, the `Timeout` middleware races the handler against it and answers
   `base.error.gatewayTimeout` (504) once it is spent. Client side, `FetchSerializer` ships the value on the
-  serialized endpoint and `fetch.<endpoint>()` uses it as that request's `AbortSignal.timeout` budget, so the
-  browser does not abandon a call the server is still allowed to be working on.
+  serialized endpoint and `fetch.<endpoint>()` uses it as that call's deadline — every retry of the call and every
+  wait between them included — so the browser does not abandon a call the server is still allowed to be working on.
 - **The middleware is registered by default and has no default of its own.** An endpoint that declares no
   `timeout` is passed straight through — a default here would put a deadline on every endpoint in the app that
   nobody asked for, which is why the middleware used to be opt-in and, being opt-in, made the declared value
@@ -62,7 +93,9 @@ mutation is mounted under. `conventions` carries the invariants — this is the
   five-minute budget that is a five-minute hold on the event loop for a call that answered in a millisecond.
 - **Without a declaration the client's own default applies — 30 seconds** (`DEFAULT_TIMEOUT_MS`,
   `fetch/client/httpClient.ts`), and the server imposes nothing. Nothing else bounds a request: `Bun.serve` runs
-  with `idleTimeout: 0`, so a long call is only ever ended by one of these two.
+  with `idleTimeout: 0`, so a long call is only ever ended by one of these two. An endpoint whose real work runs
+  longer — provisioning, a firmware flow, an external orchestration — therefore has to declare one, or it dies
+  mid-flight with a transport error that does not say whether the server ever received it.
 - **Precedence is caller, then endpoint, then client default.** `fetch.x(…, { timeout: 5_000 })` overrides what
   the endpoint declared; `{ timeout: false }` waits as long as the runtime will. An app moves its own default
   with `fetch.instance.setTimeout(ms)` — `lib/useClient.ts` is generated, so the `timeout` option on
@@ -92,13 +125,65 @@ mutation is mounted under. `conventions` carries the invariants — this is the
 - **The entry is the handler's result, not the response.** The lookup wraps the handler only, so `resolveReturn`
   still runs per call on the cached value — field masking, `hidden`/`secret` stripping and relation resolution are
   never cached, and a relation still costs its own load. The cache saves the handler, not the serialization.
+- **A hit hands `resolveReturn` an instance of the declared return model**, rebuilt from an entry that keeps its
+  `Map`s, bytes and dates, so a `resolveField` reads the same methods and `Dayjs` values on a hit as on a miss. It is
+  the declared model, not the service's document: a method only the document has is not there on a hit, and a return
+  declared as a `Light` model shows `resolveField` its light fields only. The entry still holds `hidden` and `secret`
+  values for its TTL, as the handler returned them.
+- **A write drops the answers it made stale.** Plug the adaptor into the service and call it after the write:
+
+  ```ts
+  export class BannerService extends serve(db.banner, ({ plug }) => ({
+    endpointCache: plug(EndpointCacheControl),
+  })) {
+    override async _postUpdate(banner: db.Banner) {
+      await this.endpointCache.invalidate("bannerListInPublic");
+      await this.endpointCache.invalidate("bannerInsightInPublic");
+      return banner;
+    }
+  }
+  ```
+
+  `invalidate(endpoint)` drops every cached answer of that endpoint, across instances. A slice's `init({ cache })`
+  caches its `<model>Insight<Slice>` as well as its list, so drop both or the count stays stale.
+  `invalidate(endpoint, args)` drops the one call with those arguments: pass every declared argument in order as the
+  endpoint receives it, `null` for an omitted search argument (search arguments are nullable, so an omitted one is
+  stored as `null`). A slice list also carries `skip` / `limit` / `sort`, so drop it with the endpoint-wide form.
+  A mismatched list misses silently and still answers `true`.
+- **How it is keyed:** every entry key carries its endpoint's generation, a random token the endpoint-wide form
+  replaces in one write. Nothing is scanned, and a miss already running when you invalidate writes under the old
+  token, where nobody reads it. A token is never reused, so a generation that expires (after a day) or is evicted
+  starts a fresh one instead of reviving dropped answers, and an endpoint name nothing serves leaves no key behind for
+  good. **A `{ cache }` TTL is capped at one day**, the generation's life: an entry outliving its token could never be
+  read, so a longer TTL is written as a day. Entries under an old token stay in the cache until their own TTL, and a
+  Redis that BullMQ shares has to run `noeviction`, so nothing frees them early: give an endpoint you invalidate often
+  a short TTL. The one-call form
+  deletes that entry, so a miss for those arguments already running can write it back; reach for the endpoint-wide
+  form when that matters. It answers `false` (logged as an error) when the cache failed. A cached call reads the
+  generation before its entry.
 - **A cache backend that is down does not take the endpoint down.** A failed read is warned and the call runs
   uncached; a failed write is warned and dropped.
-- The default middleware chain is `Logging → Timeout → <lib middlewares>`, and the call inside it runs an
-  `account` rate limit → account guards → argument parse → resource guards → internal arguments → cache →
-  handler: a hung cache backend is bounded by the same deadline as the handler it stands in for. **`Retry` was removed** — an automatic re-run of an endpoint
+- A call runs the cross-site check and an `ip` rate limit, then the body read, then the default middleware chain
+  `Logging → Timeout → <lib middlewares>`, and inside it an `account` rate limit → account guards → argument
+  parse → resource guards → internal arguments → cache → handler: a hung cache backend is bounded by the same
+  deadline as the handler it stands in for. **`Retry` was removed** — an automatic re-run of an endpoint
   whose failure it cannot classify replays whatever the first attempt already did.
 
+## Repeated Mutations
+
+- **A mutation sent again under the same `Idempotency-Key` header runs once.** The key is checked after the
+  resource guards and the internal arguments, and it is scoped to the endpoint, the caller and a digest of the
+  arguments, so one caller's key never hands another caller its answer. A repeat while the first run is still going
+  answers 409 `base.error.idempotencyInFlight`.
+- **A repeat answers the first response as it was sent** — resolved, masked and serialized — for 24 hours. What
+  is kept is that wire form, never the handler's result, so no `hidden` or `secret` field reaches the cache.
+- A handler that throws frees the key, so a repeat runs it again. A failure after the handler returned is kept and
+  replayed instead, for the same 24 hours and a transient one (a relation read during a database blip) included:
+  the handler's writes stand, so running it again would repeat them.
+- **Only an HTTP call is deduplicated.** A signed-out call, one whose handler returns a `Response` (whose headers,
+  such as a session's `Set-Cookie`, cannot be replayed), a websocket call, and a call through MCP all run every
+  time.
+
 ## Rate Limits
 
 - **`{ rateLimit: { calls, windowMs?, by? } }` in an endpoint's signal option** counts calls per caller per window
@@ -107,9 +192,9 @@ mutation is mounted under. `conventions` carries the invariants — this is the
   checked after the middlewares and before the guards, keyed by `accountKey(account)`; a caller it names nothing
   for — an anonymous one — is counted by address. Leaving a pubsub room is never counted.
 - **The answer is 429 `base.error.tooManyRequests` with `data: { seconds }`** and a `Retry-After` header; a WS
-  call gets the same payload as its error frame, and the HTTP client restores a proxy's own non-JSON 429 under the
-  same key (seconds from its `Retry-After`, else 60). The first refusal per endpoint per process is warned once;
-  later ones log at `debug`, so a flood does not become a log flood.
+  call gets the same payload as its error frame, and the HTTP client restores a proxy's own 429 — a page, or JSON
+  naming no error key of ours — under the same key (seconds from its `Retry-After`, `0` included, else 60). The first
+  refusal per endpoint per process is warned once; later ones log at `debug`, so a flood does not become a log flood.
 - **Keys and addresses.** The address is `context.getClientIp()` — the trusted-proxy answer, never a raw header
   from an untrusted peer. Callers whose address is unknown share one `unknown` budget (fail closed), and the first
   such call is warned about, since it usually means the proxy in front records no `X-Real-IP`/`X-Forwarded-For`
@@ -134,6 +219,43 @@ mutation is mounted under. `conventions` carries the invariants — this is the
   `{ ok: true } | { ok: false, retryAfterMs }` and is never switched off — throw the module's own `Err` with the
   wait when it refuses.
 
+## Calling Another Server
+
+- **A server-side `fetch.clone({ origin })` opens no websocket unless `connect: true`**, and neither does a clone
+  of such a clone: it makes one-off calls to another server, and a socket it opened would reconnect forever with
+  nobody to close it. It never carries the visitor's session either: a call to another origin sends only the `jwt`
+  its caller gave the clone.
+- **Retry a call with `retry`, never with a loop of your own.** `fetch.clone({ origin, retry: {} })` (or a call's
+  own `{ retry }`) tries again on an unreachable server, a 502/503/504 and a 429 after its Retry-After, backing off
+  with jitter until the call's one deadline runs out. A mutation retries under one `Idempotency-Key` it mints, or
+  the `idempotencyKey` you name, and the server runs it once per key, caller and arguments (Repeated Mutations
+  above); a signed-out call, one whose handler returns a `Response`, and a call through MCP run every time. A 4xx
+  is never retried.
+- **A failure another process reported travels as itself.** A server-to-server `fetch.<endpoint>(..., { origin })`
+  restores the remote `Err` — the same class, key and `data` — so a hop that rethrows it answers its own caller
+  with that error and the dictionary translates it. Never wrap the catch in a `new Error`, and never re-key it as a
+  `new Err` of your own: both discard what the endpoint chose to say, and a bare `Error` is generalized to
+  `Internal Server Error` on the way out.
+- `String(err)` and `${err}` read `Err: <key> {…data}`, the data as one line of JSON with secret-named keys masked,
+  so a ``logger.warn(`…: ${String(error)}`)`` keeps the exit code or status the `Err` carried.
+
+## Body Types And Bytes
+
+- `.body(...)` / `.param(...)` args accept `ConstantFieldTypeInput` only: scalars, model refs, or `enumOf(...)`.
+  Numbers are `Int` or `Float` — `Number` is rejected (`pkgs/akanjs/signal/endpointInfo.ts`).
+- **`Upload` is valid only inside a mutation flagged for file upload**:
+  `mutation([cnst.File], { fileUpload: true }).body("files", [Upload])`, as the `file` module does. It is not a
+  model field type. The other body args of such a mutation arrive typed as in a JSON body. A file's `type` on the
+  server is what its name implies, not its bytes — check the bytes when the type matters.
+- **`Binary` is raw bytes on the wire.** It is `Uint8Array` on both sides — a Node `Buffer` is one, so a server
+  handler may pass one straight in — and it accepts base64 in either direction, so the same declaration serves a
+  JSON body and a binary frame. A `Binary` return travels as base64 in an HTTP body. It is never a model field
+  (`fieldRule`).
+- **Never send bytes as `Any`.** `Any` passes a `Buffer` through untouched and `JSON.stringify` then spells it
+  `{ type: "Buffer", data: number[] }`, which `JSON.parse` never restores; the result is 3.6x the wire and a shape
+  that only breaks at the first byte-offset read. A return declared `Any` that turns out to be bytes fails instead
+  of reaching the caller as `{}`, and MCP refuses a `Binary` return for the same reason it refuses `Any`.
+
 ## Binary Pubsub
 
 - **`pubsub(Binary)` sends its payload in a websocket binary frame**, skipping the JSON `{ type: "pub" }`

package/guidelines/workspaceOnboarding/workspaceOnboarding.instruction.md

@@ -230,10 +230,10 @@ Six worked recipes carry the full code for the most frequent Akan changes, toget
 | Recipe | Covers |
 |---|---|
 | 1. Adding a field to a model | the five `constant.ts` classes, the dictionary entry, the store form, `akan sync` |
-| 2. Injecting a dependency into a service | `service<srv.XService>()`, `plug(Adapter)`, `env(...)`, `use<T>()` |
+| 2. Injecting a dependency into a service | `service<srv.XService>()`, `plug(Adapter)`, `env(...)`, `use<T>()`, writing an `adapt()` adapter |
 | 3. Creating and using a slice | `slice()` guards, the generated `init<Model><Suffix>`, `Load.Units` hydration |
 | 4. Creating a mutation endpoint | the document chain method, the service call, the signal `guards`, the store action |
-| 5. Internal triggers | `internal()` with interval and cron |
+| 5. Internal triggers | `internal()` with interval and cron, queue retries and the dead letter |
 | 6. Creating an insight | the `XInsight` class, the aggregation, the dashboard tile |
 | Data Flow Summary | how a value travels page → store → signal → service → document → DB |
 | Auto-Generated API Reference | what signal, service, store, and document each generate — never hand-write these |
@@ -244,7 +244,7 @@ existing content first and change only the relevant sections — never rewrite a
 ## Modeling & Query Gotchas
 
 A short list of things the type system does not always catch. The full rules for text search, `cascade`, and the
-query-level writes are in the convention set above; these are the shapes that build green and fail later.
+query-level writes are in `queryRule`; these are the shapes that build green and fail later.
 
 - **Slices return a query, not a list.** A slice `exec` must return `this.<model>Service.query<Filter>(...)`, never
   a `list<Filter>(...)` / `listBy...(...)` array. Returning an array type-checks but fails at runtime with
@@ -258,7 +258,7 @@ query-level writes are in the convention set above; these are the shapes that bu
   **bare** — `this.userModel.pickById(id, { passwordHash: true })`, likewise `pickOne` / `find` / `findOne` /
   `findById`. A generated filter accessor takes it **inside the option object** —
   `this.userModel.findByAccountId(accountId, statuses, { select: { passwordHash: true } })`. Handing `{ select: … }`
-  to the facade selects a field named `select`, which no model has: the value arrives empty, with no error.
+  to the facade projects a field named `select`, which no model has, and throws `Unknown document field path`.
 - **`cascade` names a direction, and the wrong one is a data loss** — `removeRef` on the relation the owner holds,
   `removeWith` on the child's reference to its owner. A query-level removal fires no hooks and therefore no cascade.
 - **`q.search()` is a filter node, not a slice requirement.** `bySearch: filter().arg("text", String).query((text,

package/guidelines/workspaceRecipes/workspaceRecipes.instruction.md

@@ -66,11 +66,12 @@ const form = st.use.taskForm();
 
 ### Recipe 2: Injecting a Dependency into a Service
 
-Three patterns: injecting an **external adapter** (`use<>()`), another **module's service** (`service<>()`),
-or a **predefined framework adapter** (`plug()`). A field named `<refName>Service` resolves to the service
-registered under `<refName>` — the `Service`/`Signal` suffix is required and stripped to derive the lookup key.
+Four patterns: injecting an **external adapter** (`use<>()`), another **module's service** (`service<>()`),
+a **predefined framework adapter** (`plug()`), or **an adapter you own** (`adapt()` + `plug()`). A field named
+`<refName>Service` resolves to the service registered under `<refName>` — the `Service`/`Signal` suffix is required
+and stripped to derive the lookup key.
 
-> **For a new adapter you own, prefer the `adapt()` shape in pattern C over the `option.ts` registration in
+> **For a new adapter you own, prefer the `adapt()` shape in pattern D over the `option.ts` registration in
 > pattern A.** An `adapt()` class self-registers and is injected with `plug(TheClass)`, so it never touches
 > `option.ts`. Pattern A is the legacy constructor-style shape: recognise it, keep it working, and migrate one
 > only when you are already changing it.
@@ -141,12 +142,64 @@ export class TaskService extends serve(db.task, ({ plug }) => ({
 }
 ```
 
-For a custom adapter class (not a predefined role), pass the class itself, e.g. `ipfsApi: plug(IpfsApi)`.
+To reach the file itself (a `Bun.file()` response with ranges, a CLI tool, a size check), ask the role where it
+lives: `this.storage.resolveLocalPath?.(path, access)` (`access` optional) answers the absolute disk path
+`BlobStorage` uses, picking the root as its writes do with `access` and by the `private/` prefix without it. It
+answers `null` for a key that is rooted, holds a NUL, or leaves that root — refuse that key, never fall back to
+`readData()` for it. Fall back only when the adaptor has no `resolveLocalPath` at all (object storage). **A key
+that reaches you from a request passes `access: "public"`**: without it a `private/` key resolves under the private
+root, so a public route would serve private files. Never cast the role to reach `root` / `privateRoot`.
+
+For a custom adapter class (not a predefined role), pass the class itself, e.g. `ipfsApi: plug(IpfsApi)`. Two framework
+adapters are plugged that way: `rateLimit: plug(RateLimit)` to count a business key, and
+`endpointCache: plug(EndpointCacheControl)` to drop an endpoint's `{ cache }` answers after the write that made them
+stale: `await this.endpointCache.invalidate("bannerListInPublic")`, plus `"bannerInsightInPublic"` for a slice's
+count.
 Injecting a file/image field is usually simpler than calling
 storage directly: declare `image: field(File).optional()` (or `images: field([File])`) on the model and let the
 store's generated `upload<Field>On<Model>(fileList)` action handle the upload. Add `{ cascade: "removeRef" }` to that
 field when the file belongs to the model alone, and removing the model removes the file and its stored object.
 
+**D. An adapter you own — `adapt()` in `srvkit/`**
+
+An injected singleton is an `adapt()` class in `srvkit/`. Write new adapters this way.
+
+```typescript
+export class AdminNoti extends adapt("adminNoti" as const, ({ use, env, plug, memory }) => ({
+  discordApi: use<DiscordApi>(),
+  workspaceRoot: env(() => `~/build/${getEnv().environment}`),
+  masterHost: plug(MasterHost),
+  tokenMap: memory(Map, { of: String }),
+})) {}
+```
+
+- Inject it with `plug(TheClass)` from a service or from another adapter. Destructure only the injectors you use,
+  and write the registration key `as const`.
+- **Do not register an `adapt()` class in `lib/option.ts`.** It self-registers, and `plug(Class)` uses the class
+  itself as the token. `option.ts` is now only for legacy constructor-style adapters and for widening the options
+  type.
+- `this.logger` is provided; never construct a `Logger` inside an `adapt()` class. Lifecycle work goes in
+  `override async onInit()`.
+- **`adapt()` is for singletons only.** A per-use value object stays a plain class you `new` at the call site. If
+  there is not exactly one per process that a service needs injected, it is a plain class.
+- **`memory(...)` takes a scalar or model class, not only a primitive** — `memory(Map, { of: CallStateInput })`
+  serializes through the constant and travels as JSON text, so the Redis and sqlite-backed caches round-trip the
+  same declaration. Never hand-encode JSON into a `String` memory. A memory is scoped to the service or adaptor
+  that declares it; `ttl` (milliseconds) sets how long each write lives unless the `set` call names its own
+  `expireAt`, and a `Map` entry expires on its own.
+
+Conventions that hold for both adapter shapes (A and D):
+
+- Route every remote call through one private `#api<T>(path, init?)` with `signal: AbortSignal.timeout(20_000)`.
+- Paginate with `for (let page = 1; ; page += 1)` broken by `if (pageItems.length < 100) break;`.
+- Resolve secrets as `process.env.X ?? options.x ?? deterministicGenerator(...)` **inside a function**, never at
+  module scope.
+- Extend a function by appending an optional trailing parameter with a default, never by changing arity.
+- Parameters: up to three required primitives positional; optional flags in a trailing `{ … } = {}`; four or more
+  parameters, or any two same-typed strings, in one named destructured object.
+- Release locks in `finally`. Load heavy optional dependencies through a module-level memoized promise
+  (`puppeteerLoad ??= import("puppeteer")`).
+
 ---
 
 ### Recipe 3: Creating and Using a Slice
@@ -245,7 +298,11 @@ async startTask(taskId: string) {
 
 // 6. <Model>.Util.tsx — Reusable button component
 export const Start = ({ taskId }: { taskId: string }) => (
-  <button className={buttonRecipe({ variant: "primary", size: "xs" })} onClick={() => st.do.startTask(taskId)}>
+  <button
+    type="button"
+    className={buttonRecipe({ variant: "primary", size: "xs" })}
+    onClick={() => st.do.startTask(taskId)}
+  >
     Start
   </button>
 );
@@ -285,6 +342,10 @@ async cleanupStaleTasks() {
 - `initialize()` — runs once on service startup
 - `process(Return).msg(Type)` — message queue consumer
 
+A `process` job's `backoff: { type: "exponential", delay, maxDelay }` caps the wait between attempts, and the
+internal's `onFailed(job, error)` runs once a job has failed for good — its last attempt, or bullmq's stall limit —
+the dead letter, on either queue.
+
 ---
 
 ### Recipe 6: Creating an Insight (Aggregation / Dashboard Stats)
@@ -492,7 +553,7 @@ akan sync automatically generates APIs across all layers. Only write custom logi
 | Auto-Generated | Description |
 |---------------|-------------|
 | `this.<model>Model` | Auto-injected model adaptor |
-| `get<Model>(id)`, `load<Model>(id)` | Single document lookup |
+| `get<Model>(id)`, `load<Model>(id)` | Single document lookup: `get` throws `NoDocumentError` for a missing or removed id, answered 404 `base.error.documentNotFound`; `load` returns `null` |
 | `create<Model>(data)`, `update<Model>(id, data)`, `remove<Model>(id)` | CRUD operations — named after the model, e.g. `createTask`/`updateTask`/`removeTask` (there is no literal `createModel`) |
 | `list<Query>(args)`, `find<Query>(args)`, `pick<Query>(args)` | Filter-based queries |
 | `exists<Query>(args)`, `count<Query>(args)`, `insight<Query>(args)` | Filter-based helpers |