@akanjs/cli 3.1.0-rc.9 → 3.1.0

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 (91) hide show
  1. package/.build-stamp +1 -1
  2. package/{CodeAgent-rkjyxgec.js → CodeAgent-c53dm40p.js} +2 -2
  3. package/{CodeAgentRpcHost-p7h6n2hp.js → CodeAgentRpcHost-9g27hmer.js} +1 -1
  4. package/{CodeTui-h7pyj6xa.js → CodeTui-xz9jtrn3.js} +47 -4
  5. package/README.ko.md +1 -1
  6. package/README.md +1 -1
  7. package/TunnelShare-59zd4j8n.js +14 -0
  8. package/{agent.command-3qxf4xcj.js → agent.command-qawf7z4s.js} +5 -5
  9. package/akanCode.js +7 -5
  10. package/{application.command-m1kcd7jf.js → application.command-jqrgqk6j.js} +35 -9
  11. package/{applicationBuildRunner-dj0xkrep.js → applicationBuildRunner-grgrey5c.js} +23 -8
  12. package/buildBatch.proc.js +9 -9
  13. package/{cloud.command-9cp1t0f5.js → cloud.command-p9067ssj.js} +13 -13
  14. package/cloud.script-f0r4ce7j.js +24 -0
  15. package/{code.command-0ad6gw2a.js → code.command-t6j55sbk.js} +25 -12
  16. package/commandManifest.json +1 -1
  17. package/{context.command-0qx447mb.js → context.command-eqbzbgth.js} +16 -16
  18. package/context.runner-1cs88ags.js +25 -0
  19. package/{guideline.command-cv5bmrx2.js → guideline.command-w905q73w.js} +2 -2
  20. package/guidelines/agentRule/agentRule.instruction.md +25 -10
  21. package/guidelines/conventions/conventions.instruction.md +71 -24
  22. package/guidelines/fieldRule/fieldRule.instruction.md +17 -0
  23. package/guidelines/mcpRule/mcpRule.instruction.md +93 -48
  24. package/guidelines/modelDocument/modelDocument.instruction.md +2 -1
  25. package/guidelines/modelStore/modelStore.instruction.md +7 -0
  26. package/guidelines/pageRule/pageRule.instruction.md +55 -8
  27. package/guidelines/queryRule/queryRule.instruction.md +24 -10
  28. package/guidelines/runtimeRule/runtimeRule.instruction.md +12 -4
  29. package/guidelines/ssrRule/ssrRule.instruction.md +9 -6
  30. package/guidelines/transportRule/transportRule.instruction.md +36 -5
  31. package/guidelines/workspaceOnboarding/workspaceOnboarding.instruction.md +5 -3
  32. package/guidelines/workspaceRecipes/workspaceRecipes.instruction.md +28 -8
  33. package/incrementalBuilder.proc.js +3 -3
  34. package/{index-j4mkhz93.js → index-0dd6z4b9.js} +3 -3
  35. package/{index-bspm21y1.js → index-1de5f0qq.js} +7 -7
  36. package/{index-j237xtew.js → index-1enc9rga.js} +2 -2
  37. package/index-25ks6x4k.js +643 -0
  38. package/{index-wa5jbxj1.js → index-2mrn1mrg.js} +1 -0
  39. package/{index-qwa5k1j8.js → index-3aynkpf8.js} +1 -1
  40. package/{index-vk0pa0mn.js → index-3hvmytbs.js} +2 -1
  41. package/{index-w44cy4vs.js → index-45c0mxb6.js} +2 -2
  42. package/{index-fyq1z6kt.js → index-48n4yhm4.js} +3 -3
  43. package/{index-192ha4xh.js → index-64pjry21.js} +1 -1
  44. package/{index-5edzv8fn.js → index-aqwdjn4x.js} +2 -2
  45. package/{index-d2242ksy.js → index-at7bz0xq.js} +3 -0
  46. package/{index-9z426msb.js → index-avjqbtkj.js} +7 -6
  47. package/{index-20bxxyvn.js → index-bs9yr4we.js} +40 -2
  48. package/{index-d72hfmdm.js → index-cgexcnwd.js} +8 -8
  49. package/{index-1xj2t7cb.js → index-dkfadmrx.js} +7 -7
  50. package/{index-35hc95h5.js → index-eabfsarf.js} +1 -1
  51. package/{index-pydbnfez.js → index-er62k6w3.js} +35 -9
  52. package/{index-1p98exm2.js → index-f2gfq0yh.js} +2 -2
  53. package/{index-jw1zm273.js → index-fbw3kmt5.js} +54 -10
  54. package/{index-4mhy6qme.js → index-fnqj2d2w.js} +4 -4
  55. package/{index-awbdfcf2.js → index-hqh4mpgt.js} +4 -4
  56. package/{index-fmzcs8v6.js → index-j4dzazmw.js} +4 -4
  57. package/{index-va06nr10.js → index-n8dsax1f.js} +64 -19
  58. package/{index-g1mbppa9.js → index-nr8m4j21.js} +5 -5
  59. package/{index-86jt2a0e.js → index-qh73jnyb.js} +1 -1
  60. package/{index-8fp3b47h.js → index-vtj332gj.js} +281 -46
  61. package/{index-tamvyvj3.js → index-wt7m1hfc.js} +3 -3
  62. package/{index-cpb3nvma.js → index-yfy3t4kw.js} +2 -2
  63. package/{index-trpasv9q.js → index-yyxy7aff.js} +1 -1
  64. package/{index-d47ypebv.js → index-z5cxrbvv.js} +75 -19
  65. package/index.js +40 -22
  66. package/{library.command-erp2f56n.js → library.command-z1v7zepj.js} +3 -3
  67. package/{localRegistry.command-y176p558.js → localRegistry.command-48n23bjy.js} +12 -12
  68. package/{module.command-gs2r615e.js → module.command-rv307dk7.js} +5 -5
  69. package/{package.command-j10r76ax.js → package.command-7xkzc8m1.js} +3 -3
  70. package/package.json +16 -16
  71. package/{page.command-4h4a8pnh.js → page.command-34hpdt7v.js} +3 -3
  72. package/{pipeline.command-a2nrk26m.js → pipeline.command-ckvhrpyg.js} +2 -2
  73. package/{primitive.command-w6t0asqz.js → primitive.command-em0twr5a.js} +6 -6
  74. package/{projectTypecheck-f534enqj.js → projectTypecheck-fy6hn05y.js} +1 -1
  75. package/{quality.command-77x7vbbx.js → quality.command-c6p2819k.js} +2 -2
  76. package/{repair.command-y6sstev7.js → repair.command-j6czdgrv.js} +5 -5
  77. package/{routeSourceValidator-7ycnfz0e.js → routeSourceValidator-6jd0q6r6.js} +47 -14
  78. package/{scalar.command-20b8cy0k.js → scalar.command-17e20sj2.js} +4 -4
  79. package/skills/akan-code/SKILL.md +4 -0
  80. package/skills/akan-store/SKILL.md +4 -2
  81. package/{subspace.command-5c7yasd7.js → subspace.command-n3j7vv0w.js} +8 -17
  82. package/templates/migration/__migrationId__.ts +23 -0
  83. package/templates/server.ts +8 -1
  84. package/templates/workspaceRoot/biome.json.template +1 -1
  85. package/{tunnel.command-2kw8vt9g.js → tunnel.command-cm578f4s.js} +7 -7
  86. package/{workflow.command-2djwmpqf.js → workflow.command-h9vkr6jb.js} +10 -10
  87. package/{workspace.command-ms84ykse.js → workspace.command-tp8ysvjs.js} +30 -28
  88. package/TunnelShare-661cxz5e.js +0 -14
  89. package/cloud.script-dgstqt1m.js +0 -24
  90. package/context.runner-1vsjztjg.js +0 -25
  91. package/index-665zp9rs.js +0 -271
@@ -0,0 +1,25 @@
1
+ // @bun
2
+ import {
3
+ ContextRunner2
4
+ } from "./index-cgexcnwd.js";
5
+ import"./index-dkfadmrx.js";
6
+ import"./index-f2gfq0yh.js";
7
+ import"./index-hqh4mpgt.js";
8
+ import"./index-0dd6z4b9.js";
9
+ import"./index-j4dzazmw.js";
10
+ import"./index-qh73jnyb.js";
11
+ import"./index-3hvmytbs.js";
12
+ import"./index-nr8m4j21.js";
13
+ import"./index-m9jj544v.js";
14
+ import"./index-aqwdjn4x.js";
15
+ import"./index-yyxy7aff.js";
16
+ import"./index-zzvvc845.js";
17
+ import"./index-fbw3kmt5.js";
18
+ import"./index-25ks6x4k.js";
19
+ import"./index-64pjry21.js";
20
+ import"./index-n8dsax1f.js";
21
+ import"./index-hj6w4ka1.js";
22
+ import"./index-52w0fvh8.js";
23
+ export {
24
+ ContextRunner2 as ContextRunner
25
+ };
@@ -2,9 +2,9 @@
2
2
  import {
3
3
  script,
4
4
  command
5
- } from "./index-jw1zm273.js";
5
+ } from "./index-fbw3kmt5.js";
6
6
  import"./index-52w0fvh8.js";
7
- import"./index-va06nr10.js";
7
+ import"./index-n8dsax1f.js";
8
8
  import {
9
9
  Prompter2
10
10
  } from "./index-zzvvc845.js";
@@ -180,6 +180,14 @@ pages declaring one name never clash, and a registry kept outside the surface re
180
180
  stores its uploads keeps a map beside the transcript keyed on name and size — the same guess `Attachment.same`
181
181
  has to make, and the one that is wrong for two crops of one export. So when both sides carry a `ref`, it *is* the
182
182
  answer to "the same file twice", and the heuristic is what is left for when they do not.
183
+ - **A tool hands the model a file with `ToolReturn.attach(result, [attachment])`** (`akanjs/store`), which lands in
184
+ `ToolCallResult.attachments` beside the value — a `result` reaches the model as JSON text, so a URL in it is read
185
+ as letters and base64 as a wall of them. It takes a user attachment's shape and meets the same `accepts` check and
186
+ type allow-list; Anthropic carries it inside the `tool_result`, the chat-completions dialect (whose `tool` message
187
+ holds text alone) in one user message after the turn's tool messages. It is outside the 20,000-character ceiling
188
+ and held to the 4 MB per-file one, and only the latest turn's ride as bytes: an earlier one becomes a note telling
189
+ the model to call the tool again while the picture is on screen, since one picture costs over a thousand tokens on
190
+ every turn it rides.
183
191
  - **Speech is one engine contract and the framework's own policy.** `<Agent.Chat voice={engine} />` takes a
184
192
  `VoiceEngine` — `listen(handlers)` and `speak(sentence)`, both cancellable — and the chat decides everything
185
193
  else: a press-to-talk microphone whose transcript lands in the composer to be corrected, one utterance per
@@ -398,6 +406,10 @@ pages declaring one name never clash, and a registry kept outside the surface re
398
406
  renders one editor per row, and at most one of them is ever open, so one name is registered rather than fifty.
399
407
  It also means the verb is absent from the catalogue while nothing is open, which is honest — and costs the
400
408
  agent nothing, because the catalogue is re-read on the turn that follows the tool call that opened the form.
409
+ - **A shell's `submit<Model>` refuses while an upload is in flight.** `Model.EditModal` (also while its submit is
410
+ disabled) and `Model.ViewEditModal` disable the button and answer `The <model> form is not ready to submit.` while
411
+ `<model>FormUploading` is not empty. That key is read `{ agent: false }`, so the refusal is how an agent learns of
412
+ the upload: call `submit<Model>` again once the file has landed, rather than setting the field a second time.
401
413
 
402
414
  ## Forms
403
415
  - **A form control publishes its own setter, and reading a form publishes one tool that fills several at once.**
@@ -614,14 +626,17 @@ pages declaring one name never clash, and a registry kept outside the surface re
614
626
  row, Tab completing its name, and Escape closing the menu and then, pressed again, the panel.
615
627
 
616
628
  ## Built-In Tools
617
- - The framework publishes five built-ins on every store surface: `navigate` (internal paths only, the same router
629
+ - The framework publishes six built-ins on every store surface: `navigate` (internal paths only, the same router
618
630
  `Link` rides), `goBack` (this session's history — global, because history is not a control a page owns and a page
619
631
  that draws no back link is not one you may not leave — a screen that must not be left withholds them with `builtins`,
620
632
  not with prose), `readScreen` (the rendered DOM as compact text — headings, links, control values, and `(disabled)`
621
633
  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
622
634
  read), `readState(key)` (one masked store key — a key that is unknown or that this screen does not read is refused
623
- *with the keys it can* read, the way `readScreen` names its sections), and `highlight(target)`. Declaring a hook tool
624
- under one of those names shadows the built-in, so reuse them only to mean that. **There is no general-purpose wait**:
635
+ *with the keys it can* read, the way `readScreen` names its sections), `highlight(target)`, and `viewImage(src)` (one
636
+ `<img>` on screen, redrawn as a JPEG at most 1568px long and attached to the result — `src` must be one this view
637
+ shows, as `readScreen({ images: true })` printed it, so the agent cannot have the browser fetch an address of its
638
+ own, and a `data:` one is refused). Declaring a hook tool under one of those names shadows the built-in, so reuse
639
+ them only to mean that. **There is no general-purpose wait**:
625
640
  a built-in one was reachable on every screen and a model spent it on whatever key it liked, parking turns nobody
626
641
  asked to park. Waiting belongs to the screen that knows what is worth waiting for — publish an `st.tool` beside the
627
642
  control that starts the work, and let it await the work.
@@ -630,8 +645,8 @@ pages declaring one name never clash, and a registry kept outside the surface re
630
645
  awaits `ScreenSettle.wait()` — DOM quiescence, bounded, because the client router hands its promise to nobody —
631
646
  and the session awaits it after every tool that did not declare `settle: false` before taking the change report.
632
647
  Without it the report describes the moment before the change landed and the `readScreen` that follows reads the
633
- page the user left. The reading built-ins (`readScreen`, `readState`, `highlight`) declare it, because a wait
634
- costs 120ms of quiet at the very least and they change nothing a resource holds.
648
+ page the user left. The reading built-ins (`readScreen`, `readState`, `highlight`, `viewImage`) declare it,
649
+ because a wait costs 120ms of quiet at the very least and they change nothing a resource holds.
635
650
  New tools and state from a fresh route are still only listed from the next turn: the catalogue is snapshotted
636
651
  when the turn starts.
637
652
  - **A tool that waits for its own work costs no model turns; one that returns early costs one round trip per
@@ -665,8 +680,8 @@ pages declaring one name never clash, and a registry kept outside the surface re
665
680
  - **An image is always named, and its address rides only when asked for.** `readScreen` prints `[image: <alt>]`,
666
681
  and `[image]` for one with no `alt` — dropping the unlabelled one left a card that renders a picture reading
667
682
  exactly like a card that renders nothing, and "this page shows no image" is the one answer the screen cannot
668
- support. `readScreen({ images: true })` appends `(<src>)` to each, for handing one to a tool that takes a
669
- picture; it is off by default because a gallery is one long URL per thumbnail, which is the read's whole budget
683
+ support. `readScreen({ images: true })` appends `(<src>)` to each, for handing one to `viewImage` or another tool
684
+ that takes a picture; it is off by default because a gallery is one long URL per thumbnail, which is the read's whole budget
670
685
  spent on the part of the screen it can say the least about. A `data:` URL is never printed — that is the bytes
671
686
  themselves rather than somewhere to fetch them.
672
687
  - **A screen is only aimable if its names are printed.** `readScreen` writes `(#anchor)` beside a heading that
@@ -751,9 +766,9 @@ pages declaring one name never clash, and a registry kept outside the surface re
751
766
  that matter light up with no code. An inline arrow publishes no tool, carries no annotation, and therefore
752
767
  draws nothing: one wrapper silently costs three things at once.
753
768
  - **For a control the framework did not render, spread `agentAttrs`** from `akanjs/ui`:
754
- `<button {...agentAttrs(run)} onClick={run}>`, where `run` is what `st.tool(…).exec(…)` returned. It reads the
755
- name off the callable, so there is nothing to keep in sync and no `ref` to thread — and it earns the same E2E
756
- selector and accessibility name an `akanjs/ui` control has. Never hand-write `data-akan-*`.
769
+ `<button type="button" {...agentAttrs(run)} onClick={run}>`, where `run` is what `st.tool(…).exec(…)` returned.
770
+ It reads the name off the callable, so there is nothing to keep in sync and no `ref` to thread — and it earns the
771
+ same E2E selector and accessibility name an `akanjs/ui` control has. Never hand-write `data-akan-*`.
757
772
  - **A control that shares its handler with its siblings takes a key**: `agentAttrs(switchTab, menu)`, in the same
758
773
  vocabulary the call's argument uses. One tool serves a whole tab strip or a whole list, so without it every
759
774
  namesake is interchangeable in the DOM and the page can say *what* the agent did but never *where* — which the
@@ -55,7 +55,8 @@ not "fix" it back.
55
55
  the module dictionary's `.error({})` — imported from `"../dict"` on the server, from `"@libs/<lib>/client"` /
56
56
  `"@apps/<app>/client"` in UI. A `throw` is an error; a raw `Error` rejected, returned or stored loses the key and
57
57
  status too (a warning for now). Exempt: tests, `*.constant.ts`, a root `native/` folder (plugins throw
58
- `AkanNativeError`), and `common/**` / `env/**`, which have no legal `Err` import — keep throwing code out of them.
58
+ `AkanNativeError`), `script/migration/**` (an operator reads its message), and `common/**` / `env/**`, which have
59
+ no legal `Err` import — keep throwing code out of them.
59
60
  - **Never import a third-party package** from `page/**`, any barrel, a module logic file
60
61
  (`*.{constant,dictionary,document,service,signal,store}.ts`) or module component
61
62
  (`*.{Template,Unit,Util,View,Zone}.tsx`) — re-export it through a lib first (one-line shims in a lib's `common/`,
@@ -89,6 +90,12 @@ not "fix" it back.
89
90
  - **Never wrap a form setter in a pass-through arrow** — `(v) => st.do.setTypeOnTicket(v)` emits no
90
91
  `data-akan-action` and publishes no agent tool. A wrapper that transforms, adds a statement, or calls `writeOnX`
91
92
  is legal; publish it with an explicit `st.tool`.
93
+ - **Never call a hook conditionally** — a skipped call shifts every later hook, and production React crashes
94
+ elsewhere. Biome's `useHookAtTopLevel` checks plain hooks (`useState`, `useEffect`), early returns included.
95
+ `no-conditional-st-hook` checks the `st` hooks it cannot see — `st.use.*`, `st.slice.<x>.use.*`, `st.sel`, `st.ref`,
96
+ `st.tool(…).exec()` / `.card()`, `st.useState(…).init()`, `st.expose(…).value()` — behind `||` / `&&` / `??`, in a
97
+ ternary, an `if`, a `switch`, a loop, a `catch`, a default value, an optional call or a callback; not after an early
98
+ `return` or inside a helper the component calls. Read each into its own `const` at the top, then combine.
92
99
  - **No deep imports past a barrel**, except cross-module constants (`../map/map.constant`).
93
100
  - **Never import across the client/server boundary** (`apps/**`, `libs/**`). Client files (`ui/`, `webkit/`,
94
101
  `page/`, `*.store.ts`, every `.tsx`) never import a `*.document|dictionary|service|signal.ts`, `srvkit/`, a
@@ -155,7 +162,7 @@ not "fix" it back.
155
162
  security-relevant behaviour gets a real suite.
156
163
  - Run `bun run akan test <pkg>` from the root, or `cd <pkg> && bun test --isolate`. Plain `bun test` shares one
157
164
  global object across files and fails dozens of tests from that pollution (`bunfig.toml` `[test] isolate` is not
158
- honored as of Bun 1.3); from the repo root it breaks subprocess stdio pipes.
165
+ honored as of Bun 1.4.4); from the repo root it breaks subprocess stdio pipes.
159
166
  - Signal tests split in two: `<model>.signal.spec.ts` holds fixtures on `sampleOf(cnst.XInput)` with explicit
160
167
  `Promise<cnst.X>` returns and **no assertions**; `<model>.signal.test.ts` holds `describe("<Model> Signal")`,
161
168
  describe-scope `let` fixtures, one `beforeAll`, story-ordered `it`s, negatives via
@@ -223,9 +230,10 @@ Playbook (warning table, code, checklist: `ssrRule`): ① wrap the interaction a
223
230
  `useEffect(…, [])` load; ④ a store-reading `Zone` holds no markup and delegates to a server `View`; ⑤ hand each
224
231
  promise across — `const { xInitInY, xListInY } = fetch.initXInY(id)`, `xInitInY` to a `Zone`, `xListInY` to
225
232
  `<Load.Stream>` (model instances, server-only) — and `await` only what the shell must contain; ⑥ named `ReactNode`
226
- slots (`Layout.Navbar`); ⑦ derived display logic on `Light<Model>`; ⑧ `getSelf({ unauthorize: "/signin" })` in
227
- `_layout.tsx` (an in-page redirect after I/O; `.config({ ssr: "block" })` for a 3xx); ⑨ CSS (`data-*` +
228
- `group-data-[…]`, `<details>`) over client state for visibility; ⑩ heavy islands behind `index_.tsx` + `lazy()`.
233
+ slots (`Layout.Navbar`); ⑦ derived display logic on `Light<Model>`; ⑧ `.guard(() => signedIn())`
234
+ (`@libs/shared/webkit`) on `_layout.tsx` (a real 3xx before anything renders; `getSelf({ unauthorize })` in a body
235
+ redirects in-page after I/O); ⑨ CSS (`data-*` + `group-data-[…]`, `<details>`) over client state for visibility;
236
+ ⑩ heavy islands behind `index_.tsx` + `lazy()`.
229
237
 
230
238
  ## Runtime & Build Configuration
231
239
 
@@ -266,6 +274,8 @@ Declared in `akan.config.ts`, narrowed — never widened — by an env at boot;
266
274
  never a bare `<input>` for a model field; nested rows use `st.do.writeOnX("payments.3.name", v)` and the generated
267
275
  `add<Field>OnX` / `sub<Field>OnX`. Never hand-write `data-akan-*`.
268
276
  - Read with `st.use.*`, write with `st.do.*`; client components never call `fetch.*`.
277
+ - A raw `<button>` defaults to `type="submit"`, so a click inside any `<form>` also submits it. Write
278
+ `type="button"` on every raw `<button>` that does not submit; `<Button>` from `akanjs/ui` already defaults to it.
269
279
  - **Never persist form values yourself** — `Load.Edit`, `Model.EditModal` and `Model.New` save and recover the whole
270
280
  `<model>Form` per record or route and user (`draft={false}` off, `draft="<scope>"` to name it; secret and hidden
271
281
  values never saved; field `cache` / `cacheKey` props are deprecated no-ops — `modelStore`).
@@ -276,7 +286,9 @@ Declared in `akan.config.ts`, narrowed — never widened — by an env at boot;
276
286
  - Enum→class lookups: a module-scope `as const` map typed `{ [key in cnst.XStatus["value"]]: string }`, not
277
287
  `Record<...>`. Shared by a second module, the classes become a recipe variant in `ui/Recipe/`; only an enum→variant
278
288
  name map (`BadgeVariants["variant"]`) moves to `webkit/`.
279
- - `<Link>` from `akanjs/ui` for internal navigation; `<a>` only for `mailto:` and external links.
289
+ - `<Link>` from `akanjs/ui` for internal navigation; `<a>` only for `mailto:` and external links. A `<Link>` handed
290
+ an absolute URL (any scheme, any case) or a `//host` path passes it through untouched and opens it outside the app;
291
+ only an app path gets the locale and basePath. `Href.isExternal(href)` from `akanjs/client` is that test.
280
292
 
281
293
  ## Naming And Language
282
294
 
@@ -315,9 +327,10 @@ orchestration in `service`, client state in `store`; `Template` is forms, `Unit`
315
327
  `sort: {}` always present. Chain methods validate → mutate → `return this`, never `save()` (the caller saves, so
316
328
  `org.removeUser(id).removeInvite(id).save()` composes), with a one-line transition comment above each. Atomic
317
329
  counters live on the Model class with the updater callback, returning `!!modifiedCount`; indexes and derived
318
- totals go in `static override _onSchema`. **Removal is always soft** and reads see live rows unless
319
- `{ withRemoved: true }`. `updateById` / `removeById` fire no hooks — a cascading or `_postRemove` model removes
320
- through `remove<Model>(id)`, and `pickAndWrite` writes through the save hooks (`queryRule`).
330
+ totals go in `static override _onSchema`. **Removal is soft** and reads see live rows unless
331
+ `{ withRemoved: true }`; the one hard delete is `purge<Filter>` / `purgeMany`, for data past retention.
332
+ `updateById` / `removeById` fire no hooks — a cascading or `_postRemove` model removes through
333
+ `remove<Model>(id)`, and `pickAndWrite` writes through the save hooks (`queryRule`).
321
334
  - **`<model>.service.ts`** — a few lines: load → chain → `return await ….save()` (keep the `return await`). Side
322
335
  effects go in `override async _preUpdate` / `_postCreate`; fire-and-forget is `void`-ed. Load every referenced
323
336
  document, then save, then notify. Return `null` / `false` for not allowed or not found; the signal decides
@@ -370,9 +383,10 @@ orchestration in `service`, client state in `store`; `Template` is forms, `Unit`
370
383
  ### Calls, Queries, Agents (summaries)
371
384
 
372
385
  - **Wire (`transportRule`)**: a deadline is the endpoint's `{ timeout: <ms> }` (undeclared, the client quits at
373
- 30 s; the handler is not cancelled); `{ cache }` only on a `query` with no internal argument; `{ rateLimit }` per
374
- endpoint, `option.setRateLimit` per app, `plug(RateLimit)` for a business key. `socketId` names a connection, not
375
- a caller. A device proves itself with a `MachineToken`. Server to server, `fetch.clone({ origin })` opens no socket
386
+ 30 s; the handler is not cancelled); `{ cache }` only on a `query` with no internal argument, capped at one day,
387
+ dropped early by `invalidate(endpoint, args?)` on a plugged `EndpointCacheControl`; `{ rateLimit }` per endpoint,
388
+ `option.setRateLimit` per app, `plug(RateLimit)` for a business key. `socketId` names a connection, not a caller. A
389
+ device proves itself with a `MachineToken`. Server to server, `fetch.clone({ origin })` opens no socket
376
390
  without `connect: true`, retries through `retry`, and rethrows a remote `Err` as is — never wrapped or re-keyed.
377
391
  - **Body types**: `.body()` / `.param()` take scalars, model refs, or `enumOf(...)`; `Int` / `Float`, never
378
392
  `Number` (`pkgs/akanjs/signal/endpointInfo.ts`); `Upload` only in a `fileUpload: true` mutation; bytes are
@@ -396,8 +410,9 @@ orchestration in `service`, client state in `store`; `Template` is forms, `Unit`
396
410
  - **MCP (`mcpRule`)**: `/mcp` publishes every guarded endpoint by default; `mcp: false` (or a `slice()` `mcp` map
397
411
  mirroring `guards`) is curation, not authorization. `guards: [Every, Person]` reserves an act for a person;
398
412
  `.with(AgentCall)` narrows an agent's call. Settings are `option.setMcp` in `lib/option.ts`; `JWT_SECRET` is
399
- required outside `local`. Never make a refusal message more helpful. Every entry needs a `.desc()`; publish a
400
- screen with `page().prompt(name, description)`.
413
+ required outside `local`. Never make a refusal message more helpful. Every entry needs a `.desc()`; brief a
414
+ screen with `page().prompt(name, description)`, and publish one component a host draws with
415
+ `page().app(name, description, load)` — a read-only tool whose `load` may only query.
401
416
  - **In-page agent (`agentRule`)**: mount `<Agent.Chat />` once in a layout; it never executes tools and refuses
402
417
  every call until `option.setAgentAccess(<guard>)`; the LLM is `option.setLlm({ apiKey, model, host })`, never env.
403
418
  The surface is what components declare — `st.tool(…).exec(fn)` beside its control, `st.use` / `st.sel` /
@@ -412,6 +427,10 @@ orchestration in `service`, client state in `store`; `Template` is forms, `Unit`
412
427
  `plug(StorageAdaptorRole)` · `use<T>()` only for a legacy `option.ts` singleton · `env(...)` for config.
413
428
  - `memory(...)` takes a scalar or model class (`memory(Map, { of: CallStateInput })`); never hand-encode JSON into a
414
429
  `String` memory.
430
+ - A file your own code stored through `plug(StorageAdaptorRole)` has its disk path at
431
+ `storage.resolveLocalPath?.(path, access)` (`fieldRule`): `null` means refused (answer 404, never fall back to
432
+ `readData()`), `undefined` means the adaptor keeps no local files, and a key that comes from a request passes
433
+ `access: "public"`. A `File` field is not one: `libs/shared` stores it through its own `StorageApi`.
415
434
  - **A new adapter is an `adapt()` singleton in `srvkit/`**, injected with `plug(TheClass)`, key `as const`. Never
416
435
  register it in `lib/option.ts` (it self-registers); never construct a `Logger` in it (`this.logger` exists);
417
436
  lifecycle work in `override async onInit()`. A per-use value object is a plain class. Legacy
@@ -422,6 +441,8 @@ orchestration in `service`, client state in `store`; `Template` is forms, `Unit`
422
441
 
423
442
  - State-machine preconditions throw in `document.ts`, cross-document rules in `service.ts`, request policy in
424
443
  `signal.ts` guards. Best-effort code returns a sentinel (`null`, `undefined`, `[0, 0]`, `{}`) — no Result types.
444
+ - A `pick` or generated `get<Model>` that finds no live row answers 404 `base.error.documentNotFound` by itself
445
+ (`NoDocumentError`); load with a nullable `load<Model>` and throw `Err.NotFound` only to say more than that.
425
446
  - An endpoint names the errors it throws on purpose — `errors: { 409: ["ticket.error.locked"] }` in its signal
426
447
  option, with keys its dictionary defines and never `base.error.*`. That is the status's OpenAPI response and a line
427
448
  of the MCP tool's description; outside production a thrown key it leaves out warns once. A caller narrows with
@@ -438,7 +459,9 @@ orchestration in `service`, client state in `store`; `Template` is forms, `Unit`
438
459
  - Import `Int`, `Float`, `ID`, `Any`, `Binary`, `Upload`, `ImageResult`, `enumOf`, `dayjs` from `akanjs/base`;
439
460
  `String` / `Boolean` / `Date` are globals. No `JSON` scalar (use `Any`), no `Number`, and `Binary` / `Upload` are
440
461
  never fields — a file is `field(File).optional()` / `field([File])`, uploaded by the generated
441
- `upload<Field>On<Model>`.
462
+ `upload<Field>On<Model>` (which `Field.Img` / `Files` and siblings use when handed the generated setter); it marks
463
+ the field in `<model>FormUploading` while the request runs and drops a result whose form was set whole meanwhile
464
+ (or, on a single field, re-picked) — gate a hand-written submit on it.
442
465
  - Defaults: a literal for scalars, a thunk for anything constructed (`default: () => dayjs()`). Arrays
443
466
  `field([T])`; optional `.optional()`.
444
467
  - **`field.hidden` / `field.secret` read `null` on the client while the type declares them** — guard with `??` or
@@ -447,15 +470,15 @@ orchestration in `service`, client state in `store`; `Template` is forms, `Unit`
447
470
 
448
471
  ## Akan Page Routing (`apps/**/page/**`)
449
472
 
450
- Full contract — heads, CSR root layouts, typed params, lib pages, `devOnly`: `pageRule`.
473
+ Full contract — guards, apps, heads, CSR root layouts, typed params, lib pages, `devOnly`: `pageRule`.
451
474
 
452
475
  - `page/` holds `.tsx` route modules only: `<routeName>.tsx` or `_index.tsx`, `_layout.tsx`, `_overrides.tsx` — no
453
476
  other `_*.tsx`, helpers, `.ts` / `.js` files, or uppercase filenames. `[id]` is a dynamic segment, `(group)` a
454
477
  route group.
455
478
  - **A route file exports one chain** — `page()`, `layout()` in a `_layout.tsx`, `rootLayout()` in a root
456
- `_layout.tsx` — and every setting is a stage (`.param`, `.search`, `.config`, `.head`, `.loading`; `.notFound` /
457
- `.error` on layouts; `.fonts` / `.theme` / `.manifest` / … on the root; `.prompt` on a page). A named export
458
- beside it fails the build.
479
+ `_layout.tsx` — and every setting is a stage (`.param`, `.search`, `.config`, `.guard`, `.head`, `.loading`;
480
+ `.notFound` / `.error` on layouts; `.fonts` / `.theme` / `.manifest` / … on the root; `.prompt` / `.app` on a page).
481
+ A named export beside it fails the build.
459
482
  - **Name every `[x]` segment with `.param("x", Type)`** and read query keys only via `.search("k", Type)`; values
460
483
  arrive typed. `lang` is never declared — every stage receives it.
461
484
  - `.head()` takes JSX or a function returning it — never a metadata object; deeper heads replace by tag identity,
@@ -471,19 +494,21 @@ Full contract — heads, CSR root layouts, typed params, lib pages, `devOnly`: `
471
494
  export default page()
472
495
  .param("orgId", ID)
473
496
  .config({ transition: "stack" })
497
+ .guard(() => signedIn())
474
498
  .render(({ orgId }) => {
475
499
  const { l } = usePage();
476
- getSelf({ unauthorize: "/signin" });
477
500
  const { taskInitInOrg } = fetch.initTaskInOrg(orgId);
478
501
  return <Task.Zone.Card init={taskInitInOrg} prefix={`/org/${orgId}`} />;
479
502
  });
480
503
  ```
481
504
 
482
- - `.render()` gets the declared args flat and typed (no `PageProps`, no `loader=` prop). Order: `usePage()`, auth,
483
- fetch, return. Hand `fetch.init*` / `view*` / `edit*` fields to sections unawaited; await only what the shell reads
505
+ - `.render()` gets the declared args flat and typed (no `PageProps`, no `loader=` prop). Order: `usePage()`, fetch,
506
+ 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
484
507
  (title, redirect, link id) in one `Promise.all`.
485
- - Gate auth at `_layout.tsx` (repeating `getSelf` in the page is fine). `async` only when the body awaits; the
486
- callback is not a React component, so it takes no name and no return type. No `useState`, `useEffect`, or
508
+ - Gate auth with `.guard(() => signedIn())` (`@libs/shared/webkit`; a new workspace has that lib only with
509
+ `create-workspace --libs true`) at `_layout.tsx`, and repeat it on a page that needs more; it is a courtesy, the
510
+ endpoint guards are the gate. `getSelf({ unauthorize })` in a body still works. `async` only when the body awaits;
511
+ the callback is not a React component, so it takes no name and no return type. No `useState`, `useEffect`, or
487
512
  comments in page files.
488
513
 
489
514
  ## Akan Sync Conventions (`apps/**`, `libs/**`)
@@ -538,6 +563,28 @@ export default page()
538
563
  barrel holds only `export *` lines). `ui/<Folder>/index_.tsx` is the `"use client"` + `lazy()` boundary beside a
539
564
  server-safe `index.tsx` — merging the pair breaks RSC.
540
565
 
566
+ ## Data Migrations (`apps/*/script/migration/**`)
567
+
568
+ A change that reshapes stored documents ships a migration: `akan create-migration <name> <app>` writes
569
+ `script/migration/<yyyyMMddHHmm>_<name>.ts`, a default-exported `migration(title)` from `akanjs/server`, which
570
+ `akan migrate <app>` runs locally and `bun main.js ops migrate` in a built container (the `cheatsheet/dev/migration`
571
+ docs page).
572
+
573
+ - The new code reads both shapes until every environment has applied it — a deploy serves traffic first.
574
+ - Write only through `table(refName)`, never a service, a document or raw `sql` — a service write runs the model's
575
+ hooks, and none of them reaches the change log a rollback reverts. Call nothing outside the database.
576
+ - `plan` reads only and must hash the same on unchanged data: a timestamp, `createId()` or random value in it makes
577
+ every `apply --expect <planHash>` refuse as `planChanged`.
578
+ - Past about five seconds on SQLite, an apply's one transaction makes the live server's writes fail. Take
579
+ `.config({ transaction: false })`, which commits each `rewrite` batch and resumes a `partial` run from the top of
580
+ `apply` — so a second run must change nothing (a `where` the new shape no longer matches).
581
+ - `$ne` leaves out rows whose path is missing or `null` (match them with `{ path: null }`; `$exists: false` misses a
582
+ stored `null`); `find`, `count` and `rewrite` include removed rows unless `{ withRemoved: false }`; a `table()` write
583
+ leaves `updatedAt` alone.
584
+ - Throw a plain `Error` an operator can act on. Never edit a migration an environment has applied — write another;
585
+ delete it once every environment has, unless its `.rollback(fn)` may still be needed: without the file a rollback
586
+ runs the default undo.
587
+
541
588
  ## Present In The Code — Do Not Imitate
542
589
 
543
590
  Warts in older files — never copy them; when two shapes disagree, follow the newer neighbour: `children: any`
@@ -64,10 +64,27 @@ Use this whenever generating constants or scalar constants. It defines the curre
64
64
  field as a relation to `File`: `image: field(File).optional()` for one, `images: field([File])` for many.
65
65
  - The store then auto-generates an `upload<Field>On<Model>(fileList)` action that calls the framework upload
66
66
  mutation and polls file status until it leaves `"uploading"` (`pkgs/akanjs/store/action.ts`).
67
+ - **An upload is scoped to the form that started it.** `Field.Img` / `Imgs` / `File` / `Files` handed the generated
68
+ `set<Field>On<Model>` upload through `upload<Field>On<Model>` (any other `onChange` keeps the plain slice upload).
69
+ While the request runs, `<model>FormUploading` holds a ticket under the field's name (`{}` when idle);
70
+ `check<Model>Submitable`, `Model.EditModal` and `Model.ViewEditModal` keep submit disabled, and
71
+ `create` / `update<Model>InForm` (so `submit<Model>`) save nothing. A written result runs `_postSet<Field>` like
72
+ any setter. The result is dropped when the form was set whole meanwhile (`new` / `edit` / `reset`, a save, a
73
+ draft restore, `set<Model>Form`, an edit shell's hydration — the store clears the key on every
74
+ `set({ <model>Form })` — or another record's id) or, on a single field, when a newer upload or a
75
+ `set<Field>On<Model>` superseded it; an array field inserts into the list as it is when the result lands. A form
76
+ replaced inside an immer updater (`set((state) => { state.<model>Form = … })`) is not seen, so its uploads stay
77
+ valid. A hand-written submit reads `Object.keys(st.use.<model>FormUploading()).length` rather than tracking uploads
78
+ itself.
67
79
  - Storage is wired through the `StorageAdaptor` DI role (default `BlobStorage`,
68
80
  `pkgs/akanjs/service/predefinedAdaptor/storage.adaptor.ts`); the reference implementation is the `file` module.
69
81
  Do not hand-roll data-URL fallbacks. `{ cascade: "removeRef" }` on the field removes the file with its owner
70
82
  (`queryRule`).
83
+ - For a file your own code wrote through `plug(StorageAdaptorRole)`, the disk path is
84
+ `storage.resolveLocalPath?.(path, access)` — `null` means refused (rooted, NUL, or outside the root; never fall
85
+ back to `readData()`), `undefined` means the adaptor keeps no local files, and an untrusted key passes
86
+ `access: "public"`. A `File` field is not one: `libs/shared` stores it through its own `StorageApi`, which may be
87
+ object storage. Never cast the role to read `BlobStorage`'s `root` / `privateRoot`.
71
88
 
72
89
  ## Current Akan Patterns
73
90
  - Use `String`, `Boolean`, `Date`, `Int`, `Float`, `ID`, scalar classes, model light classes, or enum classes as field types.