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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (78) hide show
  1. package/.build-stamp +1 -1
  2. package/{CodeAgent-4pnxwptq.js → CodeAgent-8d5qs787.js} +2 -2
  3. package/{CodeTui-hhndze8h.js → CodeTui-z5vkm9ea.js} +1 -1
  4. package/TunnelShare-qkm8zp03.js +14 -0
  5. package/{agent.command-p02330r6.js → agent.command-ydftceda.js} +5 -5
  6. package/akanCode.js +2 -2
  7. package/{application.command-ywks5ywm.js → application.command-wthg8nn9.js} +18 -13
  8. package/{applicationBuildRunner-9cnnsdm5.js → applicationBuildRunner-t2r84sz6.js} +72 -26
  9. package/buildBatch.proc.js +5 -5
  10. package/{cloud.command-1tzkvje1.js → cloud.command-sz11hpre.js} +22 -17
  11. package/cloud.script-nqevg5qw.js +24 -0
  12. package/{code.command-16pm1p2v.js → code.command-9h3yrzhe.js} +6 -6
  13. package/{context.command-6ys86sqf.js → context.command-15j9b7c0.js} +16 -16
  14. package/context.runner-8gg030b0.js +25 -0
  15. package/{guideline.command-3zay3d8g.js → guideline.command-snh85ctf.js} +2 -2
  16. package/guidelines/agentRule/agentRule.instruction.md +21 -4
  17. package/guidelines/conventions/conventions.instruction.md +17 -10
  18. package/guidelines/mcpRule/mcpRule.instruction.md +13 -6
  19. package/guidelines/pageRule/pageRule.instruction.md +21 -5
  20. package/guidelines/queryRule/queryRule.instruction.md +13 -1
  21. package/guidelines/runtimeRule/runtimeRule.instruction.md +20 -2
  22. package/guidelines/ssrRule/ssrRule.instruction.md +6 -1
  23. package/guidelines/transportRule/transportRule.instruction.md +12 -5
  24. package/guidelines/workspaceOnboarding/workspaceOnboarding.instruction.md +2 -1
  25. package/incrementalBuilder.proc.js +3 -3
  26. package/{index-jgs8z8xb.js → index-0fz95kxe.js} +1 -1
  27. package/{index-1f33g2z5.js → index-2azahjaw.js} +81 -28
  28. package/{index-kcbq2qcf.js → index-2mwc0g0d.js} +1 -1
  29. package/{index-qkcwsg6r.js → index-2xcc2ax5.js} +2 -2
  30. package/{index-68c3gzvg.js → index-301pdbzz.js} +56 -9
  31. package/{index-z6v7k9sb.js → index-31es1yev.js} +24 -2
  32. package/{index-p4dnj2wc.js → index-3wypz6xj.js} +59 -8
  33. package/{index-e9e9cebg.js → index-40brg4px.js} +3 -3
  34. package/{index-tk3jg2bm.js → index-42j4a8zq.js} +2 -2
  35. package/{index-1mfyyxh5.js → index-4vgbysa0.js} +3 -3
  36. package/{index-9hbhm6cs.js → index-55j120r8.js} +1 -1
  37. package/{index-vg28jsf9.js → index-6txx6a9p.js} +214 -71
  38. package/{index-zn6bn1s2.js → index-74tjjsnc.js} +4 -4
  39. package/{index-g2s33373.js → index-905qdgqp.js} +1 -1
  40. package/{index-qtkycaqn.js → index-9th4gszy.js} +38 -21
  41. package/{index-bb4hj03s.js → index-a58emady.js} +10 -10
  42. package/{index-4w3skd33.js → index-a5dhqkdr.js} +3 -3
  43. package/{index-sh9mmp5v.js → index-b70zct19.js} +7 -7
  44. package/{index-z9xepn8t.js → index-bt438yxm.js} +556 -142
  45. package/{index-ngpn9hzy.js → index-espk51ah.js} +2 -2
  46. package/{index-b5vptvnt.js → index-hmt54t45.js} +4 -4
  47. package/{index-qfzfaq96.js → index-j9vyj3dj.js} +3 -3
  48. package/{index-ekpp5tax.js → index-js6geqjn.js} +4 -97
  49. package/{index-fmder14z.js → index-pcwzkdqb.js} +1 -1
  50. package/{index-jaa81e9r.js → index-qfp55x1y.js} +4 -4
  51. package/{index-sng3vt0p.js → index-skk9zc1x.js} +2 -2
  52. package/{index-rr7jk14m.js → index-wcej7g4z.js} +13 -10
  53. package/{index-q8age5az.js → index-xb8809yb.js} +2 -2
  54. package/{index-ynqxpwx6.js → index-xjf5j657.js} +1 -1
  55. package/index.js +22 -22
  56. package/{library.command-a8n9h8j4.js → library.command-gycrwhf1.js} +3 -3
  57. package/{localRegistry.command-1e6m7w2f.js → localRegistry.command-jtd8gaes.js} +12 -12
  58. package/{module.command-b6f1p1xa.js → module.command-v6hgs1bc.js} +5 -5
  59. package/{package.command-tc27ftmy.js → package.command-shzpcfph.js} +3 -3
  60. package/package.json +2 -2
  61. package/{page.command-m5wyqfkd.js → page.command-ptxn5kqk.js} +3 -3
  62. package/{pipeline.command-4qxyafpz.js → pipeline.command-zz31pgax.js} +2 -2
  63. package/{primitive.command-9yaatk0d.js → primitive.command-a1vse91z.js} +6 -6
  64. package/{projectTypecheck-87k6z6ab.js → projectTypecheck-2ztky9cf.js} +1 -1
  65. package/{quality.command-ht1wjhv8.js → quality.command-ah8qcakd.js} +387 -73
  66. package/{repair.command-evg9g911.js → repair.command-cvazbz99.js} +5 -5
  67. package/{scalar.command-xsejjeq1.js → scalar.command-0acvyp26.js} +4 -4
  68. package/{subspace.command-ps12q5y7.js → subspace.command-822qx2bx.js} +8 -8
  69. package/templates/app/tsconfig.json.template +2 -7
  70. package/templates/env/_env.server.type.ts +10 -5
  71. package/templates/facetIndex/index.ts +2 -2
  72. package/templates/workspaceRoot/bunfig.toml.template +0 -4
  73. package/{tunnel.command-khzgvrj8.js → tunnel.command-ycmja19q.js} +7 -7
  74. package/{workflow.command-qpyq0ya5.js → workflow.command-abb1d5xy.js} +10 -10
  75. package/{workspace.command-3dq7e9g2.js → workspace.command-qm7cw29v.js} +33 -32
  76. package/TunnelShare-zmq6bbar.js +0 -14
  77. package/cloud.script-8g83xqdg.js +0 -24
  78. package/context.runner-3jrypwe3.js +0 -25
@@ -31,7 +31,10 @@ pages declaring one name never clash, and a registry kept outside the surface re
31
31
  **refuses every call until the app names a guard of its own** — the same answer `None` gives, with no boot
32
32
  warning. A product with accounts names it in its `option.ts`, `option.setAgentAccess(SignedIn)`, taking the same
33
33
  guard classes every endpoint takes (an array is ANDed, `null` clears what a library set); without one the chat
34
- cannot spend the LLM key.
34
+ cannot spend the LLM key. **The guard decides who, not what** — the browser writes the instructions, tools and
35
+ transcript — so `option.setAgentRequestPolicy((request, { account, ip }) => request)` sees each turn after the
36
+ guard, before the quota and the model (tool names as the page published them), and returns what is sent, or
37
+ throws an `Err` (`agent.error.requestRefused`) to refuse it.
35
38
  `persist` keeps the transcript across reloads (sessionStorage; `{ storage: "local" }` to outlive the tab),
36
39
  default off, and `shortcut={false}` gives the browser back the Cmd/Ctrl+L the launcher otherwise captures.
37
40
  **`persist` also takes a `SessionHistory` of the app's own** — `{ load, save, clear }` — which is how a
@@ -104,7 +107,10 @@ pages declaring one name never clash, and a registry kept outside the surface re
104
107
  parts, so that is what it answers with no `host` set. A `host` the app named is a gateway the class knows
105
108
  nothing about, and it stays text-only until `option.setLlm({ accepts })` says otherwise — handing bytes to a
106
109
  model that cannot decode them kills the whole turn on a 400, where text-only degrades them to a note the model
107
- can repeat back.
110
+ can repeat back. A `host` naming OpenAI's own endpoint is the default host by hostname, not a gateway, and an
111
+ app's own chat-completions adaptor claims through `OpenaiLlm.acceptsOf(llmOption)` instead of copying the rule —
112
+ a copy that read "any host is a gateway" kept a vision model text-only for an app that spelled out
113
+ `https://api.openai.com/v1`.
108
114
  - **A refusal is `agent.error.llmRequestFailed`, and it names the host** — unless the prompt did not fit. The
109
115
  provider's own sentence rides in `reason` and the hostname in `provider`. `LlmOverflow.refusal(host, status,
110
116
  reason)` builds it, and reads the one refusal a chat can undo — a prompt past the window, recognized from each
@@ -627,7 +633,7 @@ pages declaring one name never clash, and a registry kept outside the surface re
627
633
 
628
634
  ## Built-In Tools
629
635
  - The framework publishes six built-ins on every store surface: `navigate` (internal paths only, the same router
630
- `Link` rides), `goBack` (this session's history — global, because history is not a control a page owns and a page
636
+ `Link` rides, so the app's navigation guards are asked and a refusal is reported as a kept page), `goBack` (this session's history — global, because history is not a control a page owns and a page
631
637
  that draws no back link is not one you may not leave — a screen that must not be left withholds them with `builtins`,
632
638
  not with prose), `readScreen` (the rendered DOM as compact text — headings, links, control values, and `(disabled)`
633
639
  on a control or button that has it; the chat's own UI is skipped via `data-agent-ui`, and a password value is never
@@ -648,7 +654,18 @@ pages declaring one name never clash, and a registry kept outside the surface re
648
654
  page the user left. The reading built-ins (`readScreen`, `readState`, `highlight`, `viewImage`) declare it,
649
655
  because a wait costs 120ms of quiet at the very least and they change nothing a resource holds.
650
656
  New tools and state from a fresh route are still only listed from the next turn: the catalogue is snapshotted
651
- when the turn starts.
657
+ when the turn starts. **So a navigation ends the model's turn, and a name nobody listed is answered with the names
658
+ that exist.** A call is looked up when it runs, so one batched behind `navigate` already reaches the new screen —
659
+ but the model wrote it against the old catalogue, and a screen-scoped name it never saw is one it composed
660
+ (`addBacklogTicketInProject` for `addBacklogTicket`), and refused with a bare `Unknown tool` it composes the next.
661
+ `AgentService.preamble` therefore says that a navigation ends the turn and that names are never guessed, and the
662
+ session answers an unknown name with the tools listed now — saying, when the catalogue moved since the turn's
663
+ list was written, that the call was written against the screen it left and the new one's tools arrive with their
664
+ arguments next turn. `navigate`'s own answer says the same, reports the path the page actually landed on when a
665
+ redirect or the not-found page moved it elsewhere, and a path with no route is refused with the internal links on
666
+ screen (`ScreenTarget.linkedRoutes`) rather than an invitation to compose another. Layout-level tools — a channel
667
+ post, a new wiki page — stay listed across routes, which is why the cross-screen requests that use only them never
668
+ hit this.
652
669
  - **A tool that waits for its own work costs no model turns; one that returns early costs one round trip per
653
670
  look.** The session awaits `run`, so a `.exec` that awaits the store action finishing the job simply makes the
654
671
  turn take that long — and the change report that follows carries whatever landed, so the model needs no second
@@ -160,9 +160,10 @@ not "fix" it back.
160
160
  - Bun's runner (`describe`, `expect`, `test` from `bun:test`); colocated `*.test.ts` / `*.spec.ts`; focused behavior
161
161
  tests of public contracts and edge cases. A placeholder `it` with a descriptive title is the floor; a
162
162
  security-relevant behaviour gets a real suite.
163
- - Run `bun run akan test <pkg>` from the root, or `cd <pkg> && bun test --isolate`. Plain `bun test` shares one
164
- global object across files and fails dozens of tests from that pollution (`bunfig.toml` `[test] isolate` is not
165
- honored as of Bun 1.4.4); from the repo root it breaks subprocess stdio pipes.
163
+ - Run `bun run akan test <pkg> [files]` from the root (`files`: comma-separated paths from the target or the root;
164
+ the only way a signal test runs), or `cd <pkg> && bun test --isolate ./<file>`. Plain `bun test` shares one global
165
+ object across files and fails dozens of tests from that pollution (`bunfig.toml` `[test] isolate` is not honored as
166
+ of Bun 1.4.4); from the repo root it breaks subprocess stdio pipes.
166
167
  - Signal tests split in two: `<model>.signal.spec.ts` holds fixtures on `sampleOf(cnst.XInput)` with explicit
167
168
  `Promise<cnst.X>` returns and **no assertions**; `<model>.signal.test.ts` holds `describe("<Model> Signal")`,
168
169
  describe-scope `let` fixtures, one `beforeAll`, story-ordered `it`s, negatives via
@@ -252,7 +253,8 @@ Declared in `akan.config.ts`, narrowed — never widened — by an env at boot;
252
253
  `ca-certificates` and `tzdata`.
253
254
  - **Native apps are the `native` section** (iOS, Android, desktop). A desktop app's carried server listens on a
254
255
  loopback port any local program can call — guard it as a network server — and ships `private/` and its env
255
- readable on the user's computer; read runtime files from `AKAN_APP_DIR`.
256
+ readable on the user's computer; read runtime files from `AKAN_APP_DIR`, and keep a secret the user gives it with
257
+ `NativeSecret` (the OS credential store), never in a file.
256
258
  - **`database: { modes: [...] }`** (`single`, `multiple`, `cluster`), chosen by `AKAN_DATABASE_MODE`; an app running
257
259
  in two modes avoids `q.raw`.
258
260
 
@@ -333,8 +335,9 @@ orchestration in `service`, client state in `store`; `Template` is forms, `Unit`
333
335
  `remove<Model>(id)`, and `pickAndWrite` writes through the save hooks (`queryRule`).
334
336
  - **`<model>.service.ts`** — a few lines: load → chain → `return await ….save()` (keep the `return await`). Side
335
337
  effects go in `override async _preUpdate` / `_postCreate`; fire-and-forget is `void`-ed. Load every referenced
336
- document, then save, then notify. Return `null` / `false` for not allowed or not found; the signal decides
337
- whether that is an error.
338
+ document, then save, then notify; writes that must land together go in `this.transaction(async () => …)` and
339
+ their notification in `this.afterCommit(…)` (`queryRule`). Return `null` / `false` for not allowed or not found;
340
+ the signal decides whether that is an error.
338
341
  - **`<model>.signal.ts`** — `XInternal` → `XSlice` → `XEndpoint`, all three even when empty; `exec` is a one-liner
339
342
  calling the service.
340
343
  - **`<model>.store.ts`** — custom actions only for a toast, an optimistic update, or a multi-field write:
@@ -394,9 +397,9 @@ orchestration in `service`, client state in `store`; `Template` is forms, `Unit`
394
397
  wrong JSON type, a value outside its enum or a missing required field answers 400 with `data.name` naming the
395
398
  path (`data.items.2.price`); a defaulted field may be left out, an undeclared key is dropped, and a stored model's
396
399
  input keeps an absent field absent.
397
- - **Reserved names**: generated CRUD (`create<Model>`, `update<Model>`, `remove<Model>`, …) exists for every model.
398
- The service layer reports a collision as a typecheck error, but a colliding signal name can pass sync, typecheck
399
- and build and fail at runtime — treat it as an error.
400
+ - **Reserved names**: generated CRUD (`create<Model>`, `update<Model>`, `remove<Model>`, …) exists for every model
401
+ whose slice mounts the verb. `fetch.*` is one namespace across modules and a pubsub or message is routed by its bare
402
+ name, so the server refuses to boot on two claims of one name (`[DI:fetch]`, `[DI:socket]`), naming both.
400
403
  - **Queries (`queryRule`)**: the root slice takes `queryKey` + `args`, never a raw query. A slice `exec` returns a
401
404
  `query<Filter>(…)` descriptor (never a `list<Filter>` array) and is paged through `initX(…, { sort, page, limit })`.
402
405
  A projection is bare on the facade (`pickById(id, { secret: true })`), under `select` on a filter accessor — the
@@ -414,7 +417,8 @@ orchestration in `service`, client state in `store`; `Template` is forms, `Unit`
414
417
  screen with `page().prompt(name, description)`, and publish one component a host draws with
415
418
  `page().app(name, description, load)` — a read-only tool whose `load` may only query.
416
419
  - **In-page agent (`agentRule`)**: mount `<Agent.Chat />` once in a layout; it never executes tools and refuses
417
- every call until `option.setAgentAccess(<guard>)`; the LLM is `option.setLlm({ apiKey, model, host })`, never env.
420
+ every call until `option.setAgentAccess(<guard>)`, which decides who — what a turn may ask is
421
+ `option.setAgentRequestPolicy`; the LLM is `option.setLlm({ apiKey, model, host })`, never env.
418
422
  The surface is what components declare — `st.tool(…).exec(fn)` beside its control, `st.use` / `st.sel` /
419
423
  `st.ref` keys — never a store class. `st.use.x({ agent: false })` hides a key; its model's `hidden` / `secret` /
420
424
  `visual` fields are stripped at read. A tool value is capped at 20,000 characters. Route guidance is
@@ -505,6 +509,9 @@ export default page()
505
509
  - `.render()` gets the declared args flat and typed (no `PageProps`, no `loader=` prop). Order: `usePage()`, fetch,
506
510
  return; auth is the chain's `.guard()`, which runs before anything renders. Hand `fetch.init*` / `view*` / `edit*` fields to sections unawaited; await only what the shell reads
507
511
  (title, redirect, link id) in one `Promise.all`.
512
+ - **A route never writes while it renders**: a `fetch.<mutation>()` in a stage or a component it renders throws
513
+ `base.error.mutationInRender`, since opening a link would perform it. Send it from a user action;
514
+ `{ duringRender: true }` only for a write harmless to repeat and safe for anyone to trigger (`ssrRule`).
508
515
  - Gate auth with `.guard(() => signedIn())` (`@libs/shared/webkit`; a new workspace has that lib only with
509
516
  `create-workspace --libs true`) at `_layout.tsx`, and repeat it on a page that needs more; it is a courtesy, the
510
517
  endpoint guards are the gate. `getSelf({ unauthorize })` in a body still works. `async` only when the body awaits;
@@ -40,6 +40,9 @@ export class FileSlice extends slice(srv.file, {
40
40
  `update`, `remove`), same fallbacks (`create`/`update`/`remove` inherit `cru`), and the same scope: it narrows
41
41
  the root slice and the generated CRUD, and never reaches a named slice or a custom endpoint. Those declare
42
42
  their own `mcp` beside their own `guards`. The bare `mcp: false` is every key at once, still within that scope.
43
+ - **An app's slice replaces a lib's whole**, on the server and in the client: its own `guards` (a `None` verb is
44
+ denied everywhere) and its own `mcp` map, or, when it writes none, every verb the lib's slice took off stays off.
45
+ To keep a mounted lib's tools off without its slice, use `setMcp({ excludeSignals, excludeEndpoints })` (below).
43
46
  - **A view keeps reaching it.** To a host that renders MCP Apps views, an endpoint refused for `mcp: false` alone
44
47
  is published with `visibility: ["app"]`: an app's view may call it, the model is never shown it (below). Every
45
48
  other refusal still holds there.
@@ -56,11 +59,13 @@ export class FileSlice extends slice(srv.file, {
56
59
  ## Configuration
57
60
  Settings live in the app's `lib/option.ts` — `option.setMcp({ … })`, taking `enabled`, `readOnly`, `path`,
58
61
  `version`, `instructions`, `allowedOrigins`, `pageSize`, `language`, `legacyTextBlock`, `outputSchema`, `rateLimit`,
59
- `promptBudget`, `apps`, `modern`, and `auth` — or `setMcp((env) => …)` for settings derived from the server env.
62
+ `promptBudget`, `apps`, `modern`, `auth`, and `excludeSignals` / `excludeEndpoints` (curation like `mcp: false`,
63
+ added up across libs, an unmatched name warned at boot) — or `setMcp((env) => …)` for settings derived from the
64
+ server env.
60
65
  **Not `main.ts`**: the gateway
61
66
  there only spawns children, and `option.ts` is the app-authored file `server.ts` already hands to the process that
62
67
  mounts `/mcp`. Every lib's option is read in mount order with the app's last, so an app tightens what a library
63
- declared without restating it. Each field also has an env spelling (`AKAN_MCP`, `AKAN_MCP_READONLY`,
68
+ declared without restating it. Each field but the two lists also has an env spelling (`AKAN_MCP`, `AKAN_MCP_READONLY`,
64
69
  `AKAN_MCP_PATH`, `AKAN_MCP_VERSION`, `AKAN_MCP_INSTRUCTIONS`, `AKAN_MCP_ALLOWED_ORIGINS`, `AKAN_MCP_PAGE_SIZE`,
65
70
  `AKAN_MCP_LANGUAGE`, `AKAN_MCP_LEGACY_TEXT`, `AKAN_MCP_OUTPUT_SCHEMA`, `AKAN_MCP_RATE_LIMIT`, `AKAN_MCP_CONCURRENT`,
66
71
  `AKAN_MCP_PROMPT_BUDGET`, `AKAN_MCP_APPS`, `AKAN_MCP_MODERN`, `AKAN_MCP_AUTH_SERVERS`, `AKAN_MCP_SCOPES`, `AKAN_MCP_RESOURCE`) for a deployment that configures what the source does
@@ -410,8 +415,9 @@ export default page()
410
415
  names share one namespace with the prompts, and an endpoint keeps its name over an app's, with a boot warning.
411
416
  - **`load` may only query.** A mutation, a file upload, a room subscription or a message sent while it runs throws
412
417
  `base.error.mutationInApp` before anything is sent — on the server through every `await`, in a browser for its
413
- synchronous part. Writes stay in `.render()` around the element (the `Close` above), and gating stays in
414
- `.guard()`: a `getSelf({ unauthorize })` inside `load` would redirect a view.
418
+ synchronous part, `{ duringRender: true }` or not. The buttons and forms that write stay in `.render()` around the
419
+ element (the `Close` above), and gating stays in `.guard()`: a `getSelf({ unauthorize })` inside `load` would
420
+ redirect a view.
415
421
  - **A host that declares the extension** (claude.ai, Claude Desktop, ChatGPT, VS Code, Goose) is also given
416
422
  `_meta.ui.resourceUri` (`ui://<app>/apps/<name>`) and draws the app's own view in place of the result: one HTML
417
423
  document per app, which `akan build` writes to `mcp-apps/<name>.html` beside `csr/` and `akan start` writes to
@@ -444,8 +450,9 @@ export default page()
444
450
  reaches the host with `base.error.readOnlyDeployment`, toasted in the person's language. A `.prompt()` page's text
445
451
  tool is dropped, since its run renders the whole page; the prompt stays.
446
452
  - **`.prompt()` is a briefing, never a view.** Its page is also a text tool of the same name, marked
447
- `readOnlyHint: false`, since running the page makes its own `fetch.*` calls, mutations included. To have a host draw
448
- part of that screen, declare an `.app()` beside it.
453
+ `readOnlyHint: false`, since running the page makes its own `fetch.*` calls; like any render it refuses a mutation
454
+ with `base.error.mutationInRender` unless the call passes `{ duringRender: true }`. To have a host draw part of that
455
+ screen, declare an `.app()` beside it.
449
456
  - **The view has no network.** `connect-src` stays closed; the app's own origin is opened for what a page loads by
450
457
  URL — fonts (served with `Access-Control-Allow-Origin: *`) and stored images — and every root-relative URL the
451
458
  page writes is pointed at it, since a host may block the document's `<base>` (Claude does).
@@ -41,6 +41,13 @@ body shape — this is the full contract behind them. Before changing route beha
41
41
  hydration, so an effect that needs the query on its first run takes the page's `.search()` value as a prop.
42
42
  - There is no `loader=` / `render=` page prop and no `PageProps` interface: the chain declares the arguments and
43
43
  `.render()` receives them flat, typed, with `lang` on every route and `children` added for a layout.
44
+ - **A route only reads while it renders.** A `fetch.<mutation>()` (or socket message) sent from `.render()`, `.guard()`,
45
+ `.head()`, `.loading()` or a layout's `.notFound()` / `.error()` (a `.prompt()` run included) throws
46
+ `base.error.mutationInRender` synchronously, before it is sent — a `.catch()` on its promise never sees it: opening a
47
+ link to the page would perform it. Send a write from a user action — a button through a store action. Only a write
48
+ that is harmless to repeat and safe for anyone to trigger (a warm-up) passes `{ duringRender: true }` as the option
49
+ after the endpoint's own arguments (`fetch.updateX(id, data, { duringRender: true })`). `akan quality` flags the call,
50
+ same-file helpers included, as `akan.ssr.render-mutation`.
44
51
 
45
52
  ## Route Guards — `.guard()`
46
53
 
@@ -71,6 +78,14 @@ body shape — this is the full contract behind them. Before changing route beha
71
78
  - **A route guard is not authorization for data.** It keeps a person off a screen and redirects early; every query
72
79
  the screen makes is still judged by that endpoint's own `guards`. Write both: the signal guard is the gate, the
73
80
  route guard is the courtesy that answers before the screen draws.
81
+ - **Keeping a person on a page is `router.addNavigationGuard(guard)`, not `.guard()`.** `guard({ kind, from, to })`
82
+ is asked before every in-app move — `push`, `replace`, `back`, a `Link`, the browser's back and forward (`pop`), a
83
+ native back or swipe, the agent's `navigate` and `goBack` — with routes free of locale and basePath and `to: null`
84
+ for a `back`. `false`, a throw or a rejection keeps the page, `router.navigation()` rejects with
85
+ `NavigationRefused`, and a refused browser back is undone before the page redraws. Guards answer one at a time; a
86
+ move started while one decides is refused. Register it from an effect and return the remover
87
+ (`useEffect(() => router.addNavigationGuard(…), [isDirty])`). Redirects, `notFound()`, `setLang` and moves off the
88
+ origin are not asked; a closing tab is `beforeunload`'s.
74
89
 
75
90
  ## MCP Apps — `.app()`
76
91
 
@@ -82,11 +97,12 @@ body shape — this is the full contract behind them. Before changing route beha
82
97
  source), shares one namespace with every page's prompts and apps, and needs an English description. A name
83
98
  `.render()` already receives (`lang`, a `.param()` / `.search()` name, another app) fails to compile and throws when
84
99
  the module loads, as does an app named like the page's `.prompt()`.
85
- - **`load` may only query** (`base.error.mutationInApp` otherwise): keep writes in `.render()` around the element, and
86
- gating in `.guard()`. The view runs `load` with no layout body and no `.render()`: it gets the root layout's theme,
87
- fonts and framework providers through the generated `McpAppRoot` and the `_overrides.tsx` over the page (one the web
88
- draws outside the root layout wraps `McpAppRoot`, its toasts included), and nothing a layout body provides. The
89
- chain is the `export default` expression itself: one bound to a name fails the build. Full contract: `mcpRule`.
100
+ - **`load` may only query** (`base.error.mutationInApp` otherwise, `duringRender` or not): keep the buttons and forms
101
+ that write in `.render()` around the element, and gating in `.guard()`. The view runs `load` with no layout body
102
+ and no `.render()`: it gets the root layout's theme, fonts and framework providers through the generated
103
+ `McpAppRoot` and the `_overrides.tsx` over the page (one the web draws outside the root layout wraps `McpAppRoot`,
104
+ its toasts included), and nothing a layout body provides. The chain is the `export default` expression itself: one
105
+ bound to a name fails the build. Full contract: `mcpRule`.
90
106
 
91
107
  ## Heads
92
108
 
@@ -72,6 +72,9 @@ this is the full contract behind them.
72
72
  "there is at most one of these", not for claiming the next item off a queue. Pass a query that matches one row.
73
73
  The query is a compare-and-set in every mode: of two concurrent `updateOne({ id, balance: { $gte: n } }, …)` that
74
74
  both read the row as matching, only one applies, so `modifiedCount` is the verdict.
75
+ - **`{ touch: false }` leaves `updatedAt` as stored** on a query-level write: in the options of `updateOne` /
76
+ `updateMany` / `updateById`, or `.set(update, { touch: false })` on a filter chain. Bookkeeping that is no edit — a
77
+ lease heartbeat, a mirrored snapshot — otherwise moves the row in every `updatedAt` period and sort.
75
78
  - **A filter may not be keyed after its own model.** Filter methods are assigned after CRUD, so a filter `chat` on
76
79
  model `chat` would silently swap the single-document `removeChat`/`updateChat` for a hookless query-level one. It
77
80
  throws at boot instead (`assertFilterFitsCrud`).
@@ -112,9 +115,18 @@ this is the full contract behind them.
112
115
  document path**: they fire no hooks, so a model whose removal cascades or carries a `_postRemove` still goes
113
116
  through `remove<Model>(id)`.
114
117
  - The write-through pair is `pickAndWrite(id, data)` / `pickOneAndWrite(query, data)` — pick the document, write
115
- into it and save it, so the save hooks do run; reach for those when the write has to be seen by them.
118
+ into it and save it, so the save hooks do run; reach for those when the write has to be seen by them. A third
119
+ argument `{ touch: false }`, like `doc.save({ touch: false })`, keeps `updatedAt` while the hooks and live sync
120
+ still run — a nudge that re-sends a row its rooms must re-read, with no edit to stamp.
116
121
  - `upsertById(data, { preserveTimestamps })` writes a record whole under its own id, new or in place, with no
117
122
  hook: the write a sync or a backfill repeats safely, keeping the record's `createdAt`/`updatedAt` when asked.
123
+ - **Writes that must land together go in `this.transaction(async () => …)`**, which every service has: it commits
124
+ when the body resolves, returns its value, and rolls back when it throws, rethrowing that error unchanged. A
125
+ server has one database, so it covers every model, hooks and query-level writes included; a nested call joins the
126
+ outer one, with no savepoint. Cache, `memory` and outside calls are not in it — hand them to
127
+ `this.afterCommit(fn)`, run once the commit lands, never after a rollback, at once outside one; one that throws is
128
+ logged, never thrown, and the rest still run. On SQLite it holds the only write turn: keep it short.
129
+ `@Transaction()` is deprecated.
118
130
 
119
131
  ## Text Search In A Filter — `q.search()`
120
132
 
@@ -101,6 +101,10 @@ worker per web-serving replica.
101
101
  - **A solo process answers `/_akan/app/health`, `/_akan/app/metrics` and `/_akan/bench/ping` itself**, in the
102
102
  gateway's own shape — a `children` array with one entry — so a probe reads one contract either way. It owns the
103
103
  rotating log file the gateway would otherwise write, in the same `runtime/logs` directory.
104
+ - **Health detail and metrics answer only `Authorization: Bearer $AKAN_STATUS_TOKEN`** (or the log stream token)
105
+ outside `local`: without it `/_akan/app/health` is `{ status }` alone (still 200) and `/_akan/app/metrics` is 401.
106
+ A probe that reads only the status code needs nothing; give a scraper or monitor `AKAN_STATUS_TOKEN`, which reads
107
+ nothing else.
104
108
  - **Nothing supervises a solo process but the orchestrator**, since the gateway's crash-restart-with-backoff went
105
109
  with it. `infra/app/templates/app.yaml` carries the liveness, readiness and startup probes that replace it.
106
110
  - **`PORT` is the whole tree's port, and a server-side self-call follows it.** `AkanApp` resolves it once
@@ -209,7 +213,7 @@ normalized to `info` with one warning.
209
213
  `AKAN_LOG_STDOUT_LEVEL` (default: the console level); a child's or the RSC worker's crash stack is wrapped as a
210
214
  `raw=true` record instead of breaking the stream. Text stays the default; turn it on in the deployment.
211
215
  - **`AKAN_LOG_STREAM_TOKEN` mounts `/_akan/app/logs`** (SSE, `Last-Event-ID` resume, explicit `gap` events);
212
- unset, the route does not exist.
216
+ unset, the route does not exist. The same bearer also unlocks the health detail and metrics.
213
217
  - **`AKAN_LOG_CANONICAL=1|slow`** writes one `ok|error <endpoint> ms= status=` line per call; **`AKAN_LOG_FLIGHT=1`**
214
218
  keeps each call's last 64 sub-level records and promotes them (`flight=true`) only when it failed or ran past
215
219
  `AKAN_LOG_FLIGHT_MS`; an `x-akan-debug` header lowers one request to `trace` — in `local`, or with the
@@ -235,6 +239,10 @@ const config: AppConfig = { docker: "FROM oven/bun:1.4.4-slim\n…" }; // verbat
235
239
  `RUN if [ "$TARGETARCH" = "<arch>" ]` guard, so a multi-arch build runs it on one leg only. `preRuns` land
236
240
  before `bun install --production` (where a native dependency's build tools have to be), `postRuns` after it
237
241
  and before the app files are copied.
242
+ - **The image installs the versions the workspace locked.** `akan build` writes a `bun.lock` beside the image's
243
+ `package.json`, cut down from the workspace's to what the server needs, and the image installs it
244
+ `--frozen-lockfile`. A workspace without a root `bun.lock` gets a warning and an unlocked install; a Dockerfile
245
+ written whole copies `bun.lock` itself.
238
246
  - **A lib declares the steps its own runtime needs**, and every app that mounts it inherits them:
239
247
  `libs/<lib>/akan.config.ts` takes `docker: { preRuns, postRuns }` and nothing else — the base image and the
240
248
  command belong to the app. Lib steps are emitted before the app's own, and an identical step declared twice
@@ -509,6 +517,14 @@ The carried server asks the shell that showed the dialog over its IPC channel, s
509
517
  and nothing else, and no page ever holds a path. Behind a dev build `akan start` checks the grant's signature
510
518
  against a key in `~/.akan/native` instead, in `operationMode` local only; every other server refuses a grant.
511
519
 
520
+ **A secret the user gives the server is kept by the OS, never in a file.** `NativeSecret.set(key, value)`,
521
+ `get(key)` (null when none is kept) and `remove(key)` from `akanjs/server` reach the OS credential store through the
522
+ shell that carries the server — the macOS Keychain, the Windows Credential Manager, the Secret Service on Linux — in a
523
+ store of the server's own, apart from the page's `secretStorage`, so no page script reads it. Anywhere but a carried
524
+ server `NativeSecret.available` is false and every call rejects: keep secrets in the env there. On macOS without a
525
+ Team ID signature, any program of the same user can read the store's key through `security`, as with
526
+ `secretStorage`.
527
+
512
528
  **Devices belong to the shell, not the server.** Displays and their changes (`screen`), windows placed on them
513
529
  (`window`), the system volume and mute (`volume`), global shortcuts (`global-shortcut`), keep-awake (`keep-awake`)
514
530
  and launch at login (`autostart`) are native runtime plugins, each added to `native.plugins`. Every builtin plugin's
@@ -532,7 +548,9 @@ bypasses the store akanjs picks per platform (the shell's Preferences in an app)
532
548
  code never touches `document.cookie`, `localStorage` or `sessionStorage` (`no-document-cookie`, `no-web-storage`): it
533
549
  uses `getCookie` / `setCookie` / `removeCookie`, `storage`, and `secretStorage` for tokens and credentials, all from
534
550
  `akanjs/client`. `setCookie` writes `path=/; SameSite=Lax; Secure`, and an options object overrides only the keys it
535
- names — pass `sameSite: "none"` only for a cookie a cross-site POST must carry back. Browser APIs an app WebView lacks
551
+ names — pass `sameSite: "none"` only for a cookie a cross-site POST must carry back. `getCookie` reads a name sent
552
+ twice as unset, since a sibling subdomain can plant a second copy; server code reads `cookieJar()` from
553
+ `akanjs/fetch`, or `CookieJar.parse(req.headers.get("cookie"))`, never `req.cookies`. Browser APIs an app WebView lacks
536
554
  stay in a `webkit/` hook that branches on `isNativeApp()` from `akanjs/client/native`, which is where the app side goes
537
555
  too (`no-web-only-api-outside-webkit`, a warning): `navigator.share` / `canShare` (Android's WebView has none),
538
556
  `navigator.serviceWorker` and `Notification.requestPermission` / `.permission` (no app page has them),
@@ -28,7 +28,12 @@ on the client side**.
28
28
  - `akan.ssr.client-static-markup` — a large subtree wraps one or two interactive touches. Keep the interactive
29
29
  element in the client component and hoist the static subtree into a server component received as `children`.
30
30
  - `akan.ssr.client-mount-load` — a `useEffect(…, [])` loads server data. Fetch it in the route and pass the
31
- init/view object down.
31
+ init/view object down. A mutation is not a load: send it from a user action (a button through a store action),
32
+ never from the route.
33
+ - `akan.ssr.render-mutation` — a route's stages (a layout's `.notFound()` / `.error()` included), or a same-file
34
+ function they call, send a mutation, which throws `base.error.mutationInRender`: opening a link would perform it.
35
+ Move it to a user action; pass `{ duringRender: true }`, as the option after the endpoint's own arguments, only for
36
+ a write that is harmless to repeat and safe for anyone to trigger.
32
37
  - `akan.ssr.module-missing-server-view` — a module renders only from `Template`/`Zone`/`Util` and declares no
33
38
  `Unit`/`View`. Add them and have the `Zone` delegate.
34
39
  - `akan.ssr.template-client-state` — a `Template` holds form state in `useState`. Bind to the store instead:
@@ -20,14 +20,21 @@ HTTP verb a mutation is mounted under. `conventions` carries the invariants —
20
20
  - 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.
21
21
  - **Never read the caller's IP off the socket or the request peer — take `.with(Ip)`.** Whenever a federation
22
22
  gateway is in front, `ws.remoteAddress` and the child's own peer are the *gateway* (`127.0.0.1`) for every
23
- caller and for the whole life of every socket. `Ip` reads what a proxy recorded (`x-real-ip`, then the first
24
- `x-forwarded-for` entry) and falls back to the peer only when nothing proxied the call — which is the answer
25
- for a solo process behind an ingress that sets neither; `context.getClientIp()` is the same answer inside a
26
- guard or middleware. It arrives unwrapped from
23
+ caller and for the whole life of every socket. `Ip` reads forwarded headers only from a trusted peer — loopback,
24
+ a unix socket, and the private ranges until `AKAN_TRUSTED_PROXIES` (CIDRs or addresses, plus `private`, `none`,
25
+ `*`) replaces them; any other peer is the caller itself. Unset or `*`, it reads `x-real-ip`, else the leftmost
26
+ `x-forwarded-for` entry. A list walks `x-forwarded-for` from the nearest hop to the first untrusted address and
27
+ reads `x-real-ip` only without one — so list the load balancer's and ingress controller's own addresses (or a CIDR
28
+ holding only them), and have the proxy set or append `X-Forwarded-For` rather than pass the client's through.
29
+ `private` lets any pod in those ranges name any caller: pair it with a NetworkPolicy admitting only the ingress.
30
+ From any other peer `x-forwarded-host` / `-proto` / `-port` are dropped before a route runs, so a public proxy
31
+ that rewrites `Host` must be listed, or the browser's mutations fail the cross-site check.
32
+ The gateway hands its children the one address it resolved; `context.getClientIp()` is the same answer inside a
33
+ guard or middleware. It arrives in one canonical spelling, unwrapped from
27
34
  its `::ffff:` IPv4-mapped form, so it can address a `udp4` socket as well as identify a caller, and it is
28
35
  `null` rather than a placeholder when genuinely unknown — a loopback-looking address for an unknown caller
29
36
  is the failure this replaced. The gateway also forwards the client port (`x-forwarded-port`, read with
30
- `context.getClientPort()`) along with host and protocol.
37
+ `context.getClientPort()`), host and protocol, each taken from the request only when its peer is trusted.
31
38
  - **A device or another server proves itself with a machine token.** `MachineToken.issue({ kind, id, version },
32
39
  { expiresAt? })` in `akanjs/server` signs an EdDSA JWT (`typ: akan-machine+jwt`, `aud: <app>/<environment>`) with
33
40
  `AKAN_MACHINE_PRIVATE_KEY`; it never expires unless asked. `akan machine-keygen <file>` writes that key to a file
@@ -250,7 +250,8 @@ query-level writes are in `queryRule`; these are the shapes that build green and
250
250
  a `list<Filter>(...)` / `listBy...(...)` array. Returning an array type-checks but fails at runtime with
251
251
  `Unknown document field path: 0`. (See Recipe 3.)
252
252
  - **Custom endpoint names must not collide with generated CRUD.** `create/update/remove/view/edit/merge<Model>`
253
- already exist. A collision can build green and fail only at runtime — pick a distinct verb.
253
+ already exist wherever the slice mounts the verb. A collision builds green and the server refuses to boot
254
+ (`[DI:fetch]`) — pick a distinct verb.
254
255
  - **Numbers are `Int` or `Float`, never `Number`.** `field(Number)` / `.body("x", Number)` fail to typecheck.
255
256
  - **Array fields use `field([T])`** — `tags: field([String])`, `images: field([File])`.
256
257
  - **Reading a secret field needs an explicit select, and the two call sites spell it differently.**
@@ -8,7 +8,7 @@ import {
8
8
  CodegenLock,
9
9
  WorkspaceExecutor,
10
10
  AppExecutor
11
- } from "./index-rr7jk14m.js";
11
+ } from "./index-wcej7g4z.js";
12
12
  import"./index-52w0fvh8.js";
13
13
  import {
14
14
  GraphClientEntryDiscovery,
@@ -19,10 +19,10 @@ import {
19
19
  DevChangePlanner,
20
20
  DevGeneratedIndexSync,
21
21
  SsrDevBundler
22
- } from "./index-ngpn9hzy.js";
22
+ } from "./index-espk51ah.js";
23
23
  import {
24
24
  ServerGraphFile
25
- } from "./index-jgs8z8xb.js";
25
+ } from "./index-0fz95kxe.js";
26
26
  import {
27
27
  prepareDevWatchBatch
28
28
  } from "./index-a5vmm6x4.js";
@@ -2,7 +2,7 @@
2
2
  import {
3
3
  AsyncDefaultExportDetector,
4
4
  resolveSsrPageEntriesForApp
5
- } from "./index-rr7jk14m.js";
5
+ } from "./index-wcej7g4z.js";
6
6
  import {
7
7
  FileSys2
8
8
  } from "./index-52w0fvh8.js";