@niscorp/moss 0.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 (96) hide show
  1. package/DESIGN.md +592 -0
  2. package/DOCS.md +943 -0
  3. package/LICENSE +202 -0
  4. package/README.md +155 -0
  5. package/dist/chunk-2AHJ6VDR.js +3314 -0
  6. package/dist/chunk-2AHJ6VDR.js.map +1 -0
  7. package/dist/chunk-EMRDIZLY.js +99 -0
  8. package/dist/chunk-EMRDIZLY.js.map +1 -0
  9. package/dist/chunk-HF6IGQ74.js +3342 -0
  10. package/dist/chunk-HF6IGQ74.js.map +1 -0
  11. package/dist/chunk-J72N3EMJ.js +238 -0
  12. package/dist/chunk-J72N3EMJ.js.map +1 -0
  13. package/dist/chunk-SK4PDGEE.js +55 -0
  14. package/dist/chunk-SK4PDGEE.js.map +1 -0
  15. package/dist/chunk-ZOEUEMDX.js +251 -0
  16. package/dist/chunk-ZOEUEMDX.js.map +1 -0
  17. package/dist/client/node.cjs +42 -0
  18. package/dist/client/node.cjs.map +1 -0
  19. package/dist/client/node.d.cts +9 -0
  20. package/dist/client/node.d.ts +9 -0
  21. package/dist/client/node.js +40 -0
  22. package/dist/client/node.js.map +1 -0
  23. package/dist/client.cjs +275 -0
  24. package/dist/client.cjs.map +1 -0
  25. package/dist/client.d.cts +52 -0
  26. package/dist/client.d.ts +52 -0
  27. package/dist/client.js +4 -0
  28. package/dist/client.js.map +1 -0
  29. package/dist/document-BEn2zXah.d.cts +993 -0
  30. package/dist/document-BEn2zXah.d.ts +993 -0
  31. package/dist/index.cjs +3716 -0
  32. package/dist/index.cjs.map +1 -0
  33. package/dist/index.d.cts +104 -0
  34. package/dist/index.d.ts +104 -0
  35. package/dist/index.js +96 -0
  36. package/dist/index.js.map +1 -0
  37. package/dist/node.cjs +3309 -0
  38. package/dist/node.cjs.map +1 -0
  39. package/dist/node.d.cts +28 -0
  40. package/dist/node.d.ts +28 -0
  41. package/dist/node.js +64 -0
  42. package/dist/node.js.map +1 -0
  43. package/dist/slots-Do9ScG7v.d.cts +37 -0
  44. package/dist/slots-Do9ScG7v.d.ts +37 -0
  45. package/dist/terminal/dom/index.cjs +34 -0
  46. package/dist/terminal/dom/index.cjs.map +1 -0
  47. package/dist/terminal/dom/index.d.cts +11 -0
  48. package/dist/terminal/dom/index.d.ts +11 -0
  49. package/dist/terminal/dom/index.js +32 -0
  50. package/dist/terminal/dom/index.js.map +1 -0
  51. package/dist/terminal/dom/server.cjs +16 -0
  52. package/dist/terminal/dom/server.cjs.map +1 -0
  53. package/dist/terminal/dom/server.d.cts +14 -0
  54. package/dist/terminal/dom/server.d.ts +14 -0
  55. package/dist/terminal/dom/server.js +14 -0
  56. package/dist/terminal/dom/server.js.map +1 -0
  57. package/dist/terminal/index.cjs +346 -0
  58. package/dist/terminal/index.cjs.map +1 -0
  59. package/dist/terminal/index.d.cts +32 -0
  60. package/dist/terminal/index.d.ts +32 -0
  61. package/dist/terminal/index.js +100 -0
  62. package/dist/terminal/index.js.map +1 -0
  63. package/dist/terminal/ink/index.d.ts +33 -0
  64. package/dist/terminal/ink/index.js +189 -0
  65. package/dist/terminal/ink/index.js.map +1 -0
  66. package/dist/terminal/react/index.cjs +87 -0
  67. package/dist/terminal/react/index.cjs.map +1 -0
  68. package/dist/terminal/react/index.d.cts +15 -0
  69. package/dist/terminal/react/index.d.ts +15 -0
  70. package/dist/terminal/react/index.js +35 -0
  71. package/dist/terminal/react/index.js.map +1 -0
  72. package/dist/terminal/react/server.cjs +79 -0
  73. package/dist/terminal/react/server.cjs.map +1 -0
  74. package/dist/terminal/react/server.d.cts +16 -0
  75. package/dist/terminal/react/server.d.ts +16 -0
  76. package/dist/terminal/react/server.js +28 -0
  77. package/dist/terminal/react/server.js.map +1 -0
  78. package/dist/terminal/tty/index.cjs +201 -0
  79. package/dist/terminal/tty/index.cjs.map +1 -0
  80. package/dist/terminal/tty/index.d.cts +18 -0
  81. package/dist/terminal/tty/index.d.ts +18 -0
  82. package/dist/terminal/tty/index.js +199 -0
  83. package/dist/terminal/tty/index.js.map +1 -0
  84. package/dist/terminal/vue/index.cjs +104 -0
  85. package/dist/terminal/vue/index.cjs.map +1 -0
  86. package/dist/terminal/vue/index.d.cts +23 -0
  87. package/dist/terminal/vue/index.d.ts +23 -0
  88. package/dist/terminal/vue/index.js +3 -0
  89. package/dist/terminal/vue/index.js.map +1 -0
  90. package/dist/terminal/vue/server.cjs +88 -0
  91. package/dist/terminal/vue/server.cjs.map +1 -0
  92. package/dist/terminal/vue/server.d.cts +18 -0
  93. package/dist/terminal/vue/server.d.ts +18 -0
  94. package/dist/terminal/vue/server.js +21 -0
  95. package/dist/terminal/vue/server.js.map +1 -0
  96. package/package.json +213 -0
package/DESIGN.md ADDED
@@ -0,0 +1,592 @@
1
+ # Moss — Design Document
2
+
3
+ ## Purpose
4
+
5
+ A lightweight runtime that serves *capabilities* instead of code. A principal
6
+ logs in, a charter resolves, and what arrives over the socket is their
7
+ application: the actions they may use, the data those actions may touch, live,
8
+ revocable, and identical in mechanism for humans and AI agents.
9
+
10
+ **One sentence:** the resolved catalog is the application.
11
+
12
+ **Why it had to exist.** The stack was server-shaped and had no server. Actions
13
+ are wire-ready data and nothing wired them; the charter resolved but had nowhere
14
+ trusted to execute; vex's multi-user machinery was built and dormant; server
15
+ functions had no host; there was no transport anywhere. Six mechanisms, all
16
+ built or specified, all homeless — and every app rebuilt the same wiring (its
17
+ own shell, its own vex host, its own identity stub). Moss is the missing organ:
18
+ the trusted place where the charter executes, the shell runs, and existence is
19
+ served.
20
+
21
+ ---
22
+
23
+ ## The inversion
24
+
25
+ A traditional application server hosts code and exposes endpoints. Everyone
26
+ receives the same application; authorization is a wall of checks around it. Moss
27
+ inverts the relationship on four axes.
28
+
29
+ ### 1. It serves existence
30
+
31
+ The unit served is the action — the complete behavioral contract (layout +
32
+ triggers + endpoints + input). A principal's resolved catalog **is** their
33
+ application. Deny-by-nonexistence, made true by a server rather than cosmetic in
34
+ a client: an ungranted action is not hidden or disabled, it is absent. There is
35
+ no `if (canAccess)` to forget, because the thing to guard was never sent. The
36
+ warehouse kiosk granted two actions is not a locked-down app; it is a two-action
37
+ app.
38
+
39
+ ### 2. Deployment is a data operation
40
+
41
+ Every field of the manifest is an authored artifact — the charter, the action
42
+ definitions, the layout variants, the prewarmed API surface, the shell's
43
+ canvases. Publishing a change is a write to that data; moss derives the rest.
44
+ Consequences:
45
+
46
+ - **No version skew.** The shell and the definitions it runs live server-side;
47
+ the client is a thin terminal that rarely changes.
48
+ - **Rollback is a pointer move.** The library is versioned; "published" is a
49
+ pointer per (artifact, tenant, channel), and reverting moves it back.
50
+ - **The release artifact is a diff, not a build log.** Because permissions and
51
+ UI are closed data, a publish can render its consequences in concrete terms —
52
+ *"crm.quotes → gained by: sales, intern, ray."* A human approves that.
53
+
54
+ Today the manifest is a compiled constant, seeded as generation 0; the artifact
55
+ library that makes publish a runtime write is specified and unbuilt (see below).
56
+ The mechanism is already the pure function it needs to be: resolution and shell
57
+ construction are derived from an immutable manifest, so a new generation is a new
58
+ manifest, and the per-principal memos die with it — no invalidation protocol.
59
+
60
+ ### 3. One gate, every kind of principal
61
+
62
+ The resolved catalog feeds the human's shell, an agent's tool policy, the
63
+ function gate, and the boot verifier from **one document**. User permissions, AI
64
+ guardrails, feature flags, and plan entitlements collapse into one charter
65
+ resolving to one set, per principal.
66
+
67
+ ### 4. The shell runs on the server
68
+
69
+ Nova's core is headless and its interchange is serializable (`RenderNode[]`
70
+ down, `NovaEvent` up), so the shell executes server-side and the client is a
71
+ canvas terminal: a registry, a socket, a renderer. State is authoritative — the
72
+ LiveView move, but streaming semantic trees, so the terminal is tiny and
73
+ swappable — five targets ship: the app's React kit (`terminal/react`), the
74
+ app's Vue kit (`terminal/vue`), nova's plain-DOM kit (`terminal/dom`), a line REPL (`terminal/tty`), and a
75
+ full-screen TUI (`terminal/ink`). Swappable is literal: `mountTerminal`
76
+ hot-swaps targets over one wire, the session and current trees surviving the
77
+ swap. The DOM target is the proof the terminal is trivial — nova's DOM adapter
78
+ and default kit, zero framework, zero config.
79
+
80
+ The cost is the round trip, and two rules cover the one interaction that cannot
81
+ wait for it: the terminal never overwrites the value of the focused input when a
82
+ new tree arrives (bound inputs are identified by `model.path`), and `ui:model`
83
+ events debounce. A canvas — or a whole app — may also opt *out* and run its shell
84
+ in the browser, with vex as the enforcement floor: this is where offline and
85
+ zero-backend PGlite live. It is an explicit per-canvas degrade, not a mode menu;
86
+ one screen can mix client-side chrome with authoritative server canvases —
87
+ **authority islands**. The frame doesn't care: a canvas slot renders a tree and
88
+ is indifferent to whether it came from a local shell or a socket.
89
+
90
+ ---
91
+
92
+ ## Derivation over configuration
93
+
94
+ The organizing principle: an app hands over **artifacts** and an
95
+ **environment**, and everything mechanical is *derived* — never configured.
96
+
97
+ - The **data layer** stands up from what's present: the database's seeded
98
+ `vex_cache` is the API surface (nothing is generated), and the grantable set
99
+ is the introspected schema × vex's verb leaves. No table list is authored.
100
+ - **Per-principal resolution** is the charter applied at login: roles from the
101
+ assignment rows, granted action ids (with a content-hash version token), the
102
+ compiled vex scope policy, and the granted layout variants (ring 2). Pure;
103
+ memoized because the documents are static per process.
104
+ - The **component registry** on the server is name-only stubs, derived by
105
+ walking the manifest's layouts (variants included, nova/reflect's
106
+ `componentsOf` — the walk is shared, not re-derived) — the actual components
107
+ live in the terminal.
108
+ - **Coherence is refused, not documented.** `createServer` runs `verifyCharter`
109
+ (with nova's closure audit injected over effective definitions) and
110
+ `verifyVariants`, and throws on errors. If it boots, it's coherent.
111
+
112
+ The test of the principle: moss adds no new vocabulary. Reads are vex, writes are
113
+ vex, compute is functions, UI is actions, permissions are the charter. The server
114
+ is the composition, not a fifth language.
115
+
116
+ ### Ring 2 — served layout variants
117
+
118
+ Per-principal UI difference is existence (ring 1) or a served variant (ring 2),
119
+ never a runtime capability flag in a layout. A layout variant (`NiscApp.layouts`)
120
+ is `{ action, layout }` under a minted id; the charter's `layouts` section
121
+ selects who holds which. At shell build, moss substitutes the granted variant's
122
+ layout onto the definition *before* the shell exists, so every downstream render
123
+ and serialize is already per-principal and the terminal renders what it is served
124
+ — nothing on the wire says why a button is absent. The base layout is the floor
125
+ (the least-privileged holder's shape); variants enrich upward as grants, so
126
+ `extends` composes them and a forgotten grant fails closed. This is the charter's
127
+ extensibility paying off: one `Section` value, moss hands the universe in and
128
+ compiles it.
129
+
130
+ ---
131
+
132
+ ## The socket
133
+
134
+ The authority channel. Transport-blind: the protocol speaks through a
135
+ four-function `Connection` seam (`send`/`close`/`onMessage`/`onClose`), and the
136
+ RFC 6455 plumbing lives with each runtime's entry (`ws` on Node in `./node`,
137
+ Bun-native later). One connection per client carries every canvas — ten open
138
+ canvases are ten canvas ids on one pipe.
139
+
140
+ **Down:** `hello` (the resolved catalog on connect, and the protocol the server speaks — the terminal names its own on the upgrade), `catalog` (declared for
141
+ catalog pushes — not yet sent; terminals know it and ignore it), `frame` (the
142
+ canvas arrangement — a served layout of `CanvasSlot` markers), `render` (a
143
+ canvas's tree), `render-delta` (the same tree, against the last one — opt-in,
144
+ see below), `session` (a login grant), `error`. **Up:** `event` (a
145
+ canvas-tagged `NovaEvent`), `publish` (a channel message), `resync` (this
146
+ connection's copy of a canvas drifted; send whole frames), `back` (undo the
147
+ last navigation).
148
+
149
+ Operational shape, all falling out of "the message is state, not history":
150
+
151
+ - **Backpressure.** At most one pending tree per canvas per connection; a newer
152
+ render replaces it, never queues behind it. A diff *stream* could never drop
153
+ an update this way — which is exactly why frame deltas are written against
154
+ the last frame **sent**, never against an intermediate that was coalesced
155
+ away. Dropping renders stays free.
156
+ - **Delivery.** Events are fire-and-forget; the tree is the confirmation. No
157
+ acks, no replay after reconnect — a replayed intention against a changed screen
158
+ is worse than a lost one, so reconnect simply re-sends the current trees. The
159
+ same rule holds before the first connect: nothing is sent on a socket that is
160
+ not open and nothing is held for when it is. A server-drawn page (below) is on
161
+ screen before its socket, so a press in that moment is dropped.
162
+ - **Durability.** The projection (once built) is the durable thing; the shell is
163
+ a warm cache rebuilt from definitions + projection. Evicting an idle shell and
164
+ restarting the process are both safe — shells rehydrate on the next connection.
165
+ This is why an idle sweep can exist at all, and why `reset` costs nothing but
166
+ the screen someone was on.
167
+ - **Recovery.** `reset` (up) throws a session's shell away and serves its
168
+ replacement. It names no canvas, because it is the recovery for a session
169
+ whose canvases are the broken thing; it is protocol-level, so no action
170
+ declares it and no charter grants it. This is not a convenience: a shell is
171
+ server state keyed by principal, so a wedged one survives every gesture a
172
+ client can make alone — reloading reattaches to it, and so does signing out
173
+ and back in. Without a verb the client can send, a person watching a dead
174
+ screen has no move left.
175
+ - **Going back.** `back` (up) undoes the last navigation. It names no canvas
176
+ either, and for a related reason: back is one gesture over the whole shell,
177
+ and a terminal is served trees, not stacks — it could not name the canvas that
178
+ moved last if it wanted to. What back MEANS is decided where the stacks live:
179
+ nova's shell keeps a journal of the positions its navigations displaced, and
180
+ `back` restores the newest one it can. So the browser's back button, a TUI's
181
+ Escape and an app's own control are one message, an app authors nothing to
182
+ receive it, and the terminal holds no location that could drift out of step
183
+ with the server's. It is also the answer to a real failure: with no history
184
+ integration at all, a browser's back button unloaded the application.
185
+ - **Emptiness.** A canvas whose layout renders no visible content is served as
186
+ `[]`, so a terminal collapses chrome on `length` alone. An `ActionSlot` is a
187
+ boundary, not content — visibility is decided by what's inside it.
188
+ - **Size.** Two optional reductions — transport compression and frame deltas —
189
+ sit under the protocol, both off the app's books. See below.
190
+
191
+ ### What a frame costs
192
+
193
+ A server-authored shell pays for its inversion in bytes: every change re-sends
194
+ a canvas's whole tree, where a client-side framework would have re-rendered
195
+ locally and sent nothing. That is the trade the shell exists to make, and it is
196
+ worth measuring rather than assuming.
197
+
198
+ Two reductions are available, and they are deliberately separate things:
199
+
200
+ - **Compression** (`socketCompression`, **on** by default) is
201
+ `permessage-deflate`, an RFC 7692 websocket extension. It is negotiated by
202
+ the transport, invisible above the `Connection` seam, and understood by every
203
+ browser. Render trees are mostly repeated keys, so it earns roughly 3–4×. Its
204
+ cost is memory, and it is not small: about 260 KB resident per connection at
205
+ the `ws` defaults, against about 43 KB for the shell being served. That trade
206
+ is obviously right at hundreds of connections and obviously wrong at a
207
+ hundred thousand, which is the only reason it is a knob rather than a
208
+ constant.
209
+ - **Frame deltas** (`shellFrameDelta`, **off** by default) describe a changed
210
+ canvas against the frame the connection already holds, as copy runs plus
211
+ literal inserts (`src/delta.ts` — an encoder and a decoder, both readable in
212
+ full, no dependency). Measured on Lyra: an in-place change (a keystroke
213
+ filtering a list, one row's badge flipping) falls to **1–4%** of the frame; a
214
+ navigation, where the tree is genuinely different, lands near **80%** and is
215
+ therefore left whole.
216
+
217
+ The choice of algorithm is the interesting part, because the obvious one is
218
+ wrong. A **structural** diff — walk both trees, emit `[path, value]` for every
219
+ leaf that moved — is what a virtual DOM does and what most people reach for. On
220
+ a navigation it measured **98–114%** of the frame it was replacing: worse than
221
+ useless, because every path string is overhead the frame itself doesn't carry,
222
+ and an unkeyed list reorder costs the whole list. A **byte** matcher has no
223
+ such cliff: it finds shared vocabulary between two trees that share no
224
+ structure at all, and it is indifferent to what the tree means. It is also far
225
+ simpler to prove correct, which for a layer that can silently desync a screen
226
+ is the dominant consideration.
227
+
228
+ Three rules keep it honest:
229
+
230
+ 1. **One baseline per shell.** Every connection is level with the host's
231
+ `sent` map — attaching serves whole frames, and a change fans out to
232
+ everyone — so one encode serves the whole room.
233
+ 2. **Decisively smaller, or whole.** A delta is only sent at ≤60% of the frame.
234
+ Below that it wins even after deflate; above it, deflate on the whole frame
235
+ does as well and the terminal does less work.
236
+ 3. **Checksummed, always.** Every delta carries a hash of the frame it should
237
+ rebuild. A terminal that lands anywhere else discards the result and sends
238
+ `resync` — the failure this layer must not have is a screen that is silently
239
+ wrong, and no saving is worth risking it.
240
+
241
+ Neither reduction is visible to an application, and neither changes a rendered
242
+ tree. A terminal that never advertises `delta=1` is served exactly what it was
243
+ served before either existed.
244
+
245
+ Two design points worth naming:
246
+
247
+ - **Transport → shell addressing.** The wire tags every event with its canvas;
248
+ moss stamps the canvas's *active instance* as the event's origin, and nova's
249
+ own origin filter delivers it to that instance's triggers alone. The terminal
250
+ never learns what an origin is — addressing translation is the host's job,
251
+ where both vocabularies meet. This is why two instances of one action on
252
+ different canvases don't cross-fire, with zero client-side logic.
253
+ - **Identity is asked twice.** The HTTP surfaces re-ask the `session` verifier
254
+ on every request; the socket asks at upgrade and then on a timer for as long
255
+ as the connection lives. A verifier is the whole of what an app writes to
256
+ give tokens a lifetime (`null` = expired), and moss never learns what expiry
257
+ means — it only asks again. The socket half is not optional polish: asking
258
+ once left an expired credential rendering happily while every endpoint the
259
+ server shell called came back 401, because that wire rides the HTTP
260
+ middleware. A live interface whose every load silently fails is worse than a
261
+ lock screen. A verifier that *throws* is a fault, not a sign-out — a database
262
+ blip must not become an outage, so only an explicit `null` closes.
263
+ - **Session lifecycle is capabilities, not channels.** The in-process function
264
+ seam hands each session a `grant(token)` and a `revoke()`. A login function
265
+ grants (the token goes down every connection as a `session` message; the
266
+ terminals reconnect authenticated); a sign-out function revokes (every
267
+ connection closes `4403`, the durable shell is evicted). The app calls
268
+ capabilities; it never knows where the session machinery lives. On the wire,
269
+ `4401` (stale token) and `4403` (sign-out) are the same recovery, not a
270
+ retry: drop the token, reconnect anonymous — retrying with a stale token
271
+ would loop forever.
272
+
273
+ ## Server shells
274
+
275
+ One durable nova `Shell` per authenticated principal — the socket is ephemeral,
276
+ the shell survives disconnect (reattach re-sends the current trees, and N
277
+ attached connections receive the same frames: shared canvases are the same
278
+ mechanism). Anonymous connections get a throwaway shell, disposed on detach.
279
+
280
+ **Lifetime.** A durable shell lives until sign-out, an operator reset, or the
281
+ idle sweep: nothing attached for `idleMs` (default 30 minutes) and it is
282
+ disposed, rebuilt on the next connection. Only the idle clock is swept —
283
+ deliberately no absolute cap, because that would discard the state of somebody
284
+ who is working. There is no TTL on the session behind it; a shell going away is
285
+ not a person being signed out.
286
+
287
+ **Enumeration and reset.** `shells.list()` reports every living shell —
288
+ principal, attached connections, age, idle time, and what is mounted on each
289
+ canvas. `shells.reset(principal)` disposes one and stands its replacement in
290
+ the same slot, carrying the attached connections across, so every terminal
291
+ receives a frame and current trees exactly as on reattach. Both exist because
292
+ the host owns the map: an app that keeps its own note beside it can only drift
293
+ from it, and a shell nobody can enumerate is one nobody can be helped out of.
294
+ Since everything a shell derives from is re-read at build, the replacement is
295
+ the screen boot would serve that principal now — which is also the whole cost:
296
+ a reset is not a repair that preserves what someone was doing.
297
+
298
+ **One canvas cannot take the session down.** Rendering is guarded per canvas.
299
+ A tree that throws holds its last good frame and its neighbours keep rendering,
300
+ rather than killing the flush pass, escaping a microtask uncaught, and wedging
301
+ the shell for the life of the process.
302
+
303
+ The shell is built from the manifest: canvases and fragments are data; a canvas's
304
+ `initial` may be a candidate list, and the first action the principal holds
305
+ mounts — so login is the anonymous principal's application (the charter's
306
+ `public` grant) by derivation, not a special case. `inputs(session)` is the app's
307
+ one per-principal boot hook. Endpoint calls ride the server's own HTTP surfaces
308
+ with the session's token — the server shell is just another principal-bound
309
+ client, enforcement included.
310
+
311
+ ---
312
+
313
+ ### A read that keeps answering
314
+
315
+ A shell's vex reads go through the session's wire — an in-process request
316
+ against this server's own mounts. For an entry declaring
317
+ `refresh: 'reactive'`, vex can keep answering after it returned: every
318
+ committed write to a table the query reads, it refetches (once for everybody
319
+ who would get the same rows) and calls back with the caller's new answer if it
320
+ changed (vex DESIGN.md, "Reactive reads").
321
+
322
+ The wire is the whole seam (`src/follow.ts`). Toward vex it is a `VexLive` — a
323
+ signal and a callback, carried in the in-process request's hono env, where no
324
+ network request can put one. Toward nova it is the response's `onChange`, which
325
+ nova applies through the endpoint's own `response` and `target`; the shell
326
+ re-renders and the change reaches every attached terminal like any data change.
327
+ No app code, no channel, no reaction.
328
+
329
+ The follow ends when the call's signal aborts (nova aborts it on unmount),
330
+ when the last subscriber leaves (nova unsubscribes when a newer call to the
331
+ same endpoint lands), or at once when nobody takes the response up — a server
332
+ function reading through the same wire follows nothing. An answer that changed
333
+ in the gap between the response and nova's subscription is held and handed
334
+ over on subscribe.
335
+
336
+ This retires most of "writers announce, viewers react" for data: a screen whose
337
+ reads are reactive needs no channel to stay current. Channels stay for signals
338
+ that are not data — a deck moving to its next slide mounts an action, which no
339
+ data update can do. Not built yet: carrying invalidations between processes
340
+ (the fabric would gain an `invalidate-tables` signal; until then each process's
341
+ rows TTL bounds it) and pausing the follows of a shell with nothing attached.
342
+
343
+ ## The document
344
+
345
+ A page request is the one moment a terminal has nothing: the socket is not up,
346
+ the script may not have run. Moss can answer it with the screen itself, because
347
+ the screen is a value. `attach` already sends a frame and a tree per canvas;
348
+ `shells.snapshot` returns the same thing without attaching anybody, a terminal
349
+ that draws to a string turns it into markup with the app's own kit, and the
350
+ app's own `index.html` goes out with the screen in it and the snapshot beside
351
+ it. The browser's terminal starts from that snapshot and adopts the elements
352
+ already there. **A drawn page is a first frame delivered early**, and nothing
353
+ else: the socket still attaches, still sends current trees, and is still the
354
+ authority. If the two disagree — the shell moved in between, the cookie and the
355
+ stored token are different people — the next frame simply repaints.
356
+
357
+ What it costs was measured before it was built (atrium, one core, warm):
358
+ drawing a signed-in screen to a string is 0.4–0.7 ms; a whole anonymous document
359
+ — build a shell, read it, draw it — about 0.65 ms, some 1,500 a second. The
360
+ page carries its screen twice (markup and snapshot), 3–5 KB compressed.
361
+
362
+ Six things had to be true, and each is a small, separate decision:
363
+
364
+ - **The read does not disturb anybody.** A snapshot renders, and rendering can
365
+ pick up a change the flush pass has not sent. `attach` handles that by making
366
+ the newcomer's frame the whole room's; a snapshot handles it by not touching
367
+ the `sent` baseline at all, so the next flush still finds its change.
368
+ - **It waits for the screen to be whole, but not for long.** `seeds` land a tick
369
+ after the build, and mounts chain loads. Nova marks an instance `active` only
370
+ after its mount hook has been awaited, so "the seeds are in and nothing is
371
+ `initializing`" is the shell saying its first screen is complete — a signal
372
+ that was always there. The wait is bounded (300 ms by default): a document
373
+ must not hang on a slow integration, and a skeleton is a legitimate screen.
374
+ - **Who is asking comes off a cookie**, because a page request carries nothing
375
+ else. The wire keeps a copy of the session token there (`browserEnv`'s
376
+ `cookie`), and it is read for exactly one thing — choosing whose screen to
377
+ draw. Every other surface still wants the token itself, so the copy opens no
378
+ door: a cross-site request that carried it could draw a page it cannot read.
379
+ - **An anonymous page and its socket are two shells that must name their
380
+ instances alike.** A principal's page is drawn from their durable shell and
381
+ the socket attaches to that same shell — same ids, nothing to arrange. Nobody
382
+ has a durable shell: the page is drawn from one throwaway shell and the socket
383
+ builds another. So the first is built under a random *seed* and mints its ids
384
+ in order under it; the terminal names the seed on the upgrade; the second
385
+ mints the same ids. Plain counters would have been simpler and wrong — the
386
+ origin an event claims is checked against the canvas it names, and that check
387
+ is only worth anything while a stale id from another shell names nothing.
388
+ - **Who may keep a page follows from who asked.** Drawn for nobody, a page is
389
+ the same for everybody and may be cached or written to a file; drawn for
390
+ somebody, it is theirs (`private, no-store`). That is one function
391
+ (`documentHeaders`), keyed on whether a principal resolved. No page, route or
392
+ app declares which kind it is, so none can declare it wrong.
393
+ - **Nothing here can fail a page.** A kit component that throws, a shell that
394
+ will not build, a template without a root: the template goes out as it is and
395
+ the terminal paints it the way it always did.
396
+
397
+ The route is the app's, and so are the template and the kit. Moss draws nothing
398
+ itself: `terminal/react/server`, `terminal/vue/server` and `terminal/dom/server`
399
+ are terminals like the others — handed a screen, they draw it — and the same
400
+ shape as lyceum's SSH door, which has drawn served trees inside a server
401
+ process since before this existed.
402
+
403
+ One thing a kit must hold up its end of: its first pass in the browser has to
404
+ draw what the server drew. Anything that differs between the two — the window's
405
+ width, a portal target, storage — may not decide a component's first render.
406
+ Lyra's kit answered "is the window wide" from `window.matchMedia` in a state
407
+ initialiser, behind a `typeof window` guard; the guard is the bug, because it
408
+ makes the two sides disagree about the same render, and on a wide screen React
409
+ threw the page's elements away. What a component writes onto `<html>` from an
410
+ effect (a palette) is not in the page until the script runs, so the app reads it
411
+ off the snapshot and hands it to the document. Each app holds both with a check.
412
+
413
+ ## Pages
414
+
415
+ `shell` is the app: one durable shell per person, the thing that rearranges
416
+ itself around whoever holds it. Not everything at a path is that. A welcome, the
417
+ docs, a published talk are read, not worked in, and a person who is signed in is
418
+ still the same person when they open one.
419
+
420
+ A **page** is a shell manifest and the path it is drawn at
421
+ (`app.pages`). It is drawn by the same machinery with the keeping taken out: a
422
+ shell is built from the page's manifest for whoever asked, read, and disposed.
423
+ Everything else is unchanged, which is the point —
424
+
425
+ - what exists on it is still ring 1. A strip that names the signed-in person is
426
+ an action a member is granted, on a canvas whose candidates a stranger is
427
+ granted none of. Being signed in changes what a page *has*, through the
428
+ charter, and nothing in a layout asks;
429
+ - its reads still run under the caller's policy;
430
+ - its cacheability is still decided by who asked, in the one place above.
431
+
432
+ So a signed-in person on `/docs` is themselves — and still has no shell there.
433
+ Their app shell is neither built nor touched.
434
+
435
+ **Does anything stand behind a page afterwards?** Only if something on it can
436
+ still happen. Every reason a drawn screen is not finished is a declared part of
437
+ an action — a `ui:` trigger, a two-way binding, a channel it waits on, a read
438
+ that keeps answering — so the question is decidable from the definitions
439
+ actually mounted, without running anything. Nova reports those facts
440
+ (`livenessOf`); moss, which holds the entries behind each fingerprint, composes
441
+ the verdict (`shellNeedOf`) and puts it on the snapshot as `live`. A page that
442
+ is not live is served as markup and its terminal opens no socket at all. A page
443
+ that is live gets a shell for as long as its connection lasts — per connection,
444
+ never per person. The one thing counted live without being read is code: a `fn:`
445
+ endpoint that something calls.
446
+
447
+ `onSession` does not run for a page. That is not an economy: session code is
448
+ arbitrary, and a host that ran it could no longer say what a page can do. It is
449
+ the app's, and the app's shell is always live.
450
+
451
+ **Pages as files.** `exportDocuments` is the same draw, for nobody, once per
452
+ path. It takes no credential and has no way to be given one, so a file is only
453
+ ever the page as nobody in particular sees it. Each file reports whether it is
454
+ live and which reads its markup was drawn with (frozen at the moment of
455
+ writing). A live page is still written — whether a server stands beside the
456
+ files is the build's to know.
457
+
458
+ **What a path means, and what it does not.** A path picks between the app and a
459
+ page, and can seed a page's canvas with its parameters. It does not address a
460
+ place *inside* the app: the app's shell is state, one per person, shared by
461
+ every terminal they have open, and a URL that tried to name a position in it
462
+ would be naming something two tabs cannot disagree about. Routing stays where
463
+ the application guide puts it — shell state is the truth.
464
+
465
+ ## The function seam
466
+
467
+ The `fn:` escape hatch runs server-side, in-process, next to the durable shell.
468
+ The manifest's `functions(session)` builds handlers once per session, closing
469
+ over the living shell, the caller's compiled scope policy, the environment, and
470
+ `grant`/`revoke`. Agents live here (their reads run under the caller's policy —
471
+ they see what the caller sees); keys are `.env`. This is deliberately the *side-
472
+ effect-ful, session-bound* half. The canonical, side-effect-free function — an
473
+ independently deployable endpoint under `/fns` — is specified and pending.
474
+
475
+ ## The write lanes
476
+
477
+ Vex is the choke point every application write passes through, which makes its
478
+ write observer the one place a host can learn about all of them. Moss
479
+ subscribes once and splits the news two ways — and the split is a privilege
480
+ boundary, not a convenience.
481
+
482
+ **The app lane carries no rows.** A declared reaction hears table, op, row
483
+ *count* and the unforgeable scope. That is enough to invalidate, resync, or
484
+ push a ping onto a living shell, and it is not enough to leak anything: a
485
+ receiver that wants data re-reads it under its own policy, through the same
486
+ governed wire as everybody else. The alternative — handing rows to a callback
487
+ — puts data in the one place this stack has no fence for, arbitrary imperative
488
+ code, and `deliver` payloads are pings for exactly the same reason.
489
+
490
+ **The tide lane carries rows, because tide has the fence.** A fact is stamped
491
+ with the identity derived from the *write's own* scope, and the matcher offers
492
+ a fact only to reflexes running under that same identity. Tide is the one
493
+ place a row travels without being read — no policy is consulted on the way —
494
+ so that stamp is the whole boundary, and it is the app's naming rule, never a
495
+ listener's interest, that sets it. Stamping by who is listening would walk one
496
+ tenant's row into another tenant's effect, which is a defect this stack has
497
+ already had once and does not intend to have again.
498
+
499
+ Interest is **declared, not discovered**: reactions name their table up front
500
+ and moss routes by that name, so app code never string-matches a fingerprint
501
+ to work out what happened. The cost of the declaration is that a name nothing
502
+ writes fires nothing, quietly — derive the names from `mutationEffect` and
503
+ assert them, the way an app already asserts its charter.
504
+
505
+ **Pacing belongs to the host, not the engine.** Tide names the next instant it
506
+ wants waking for; the driver owns the timer, wakes on every ingest, and drains
507
+ to quiescence. The interval that used to stand in for this was both a latency
508
+ floor and a throughput ceiling — a chain advanced one hop per beat — and the
509
+ only periodic thing left is a janitor that finds nothing when nothing is
510
+ broken.
511
+
512
+ ## Model runs
513
+
514
+ An agent lives behind the function seam, so the app server is the one place that
515
+ sees every model call a session makes. The manifest declares a `runs` sink;
516
+ `session.recordRun` stamps `at`, `principal` and `shellId` and hands over a
517
+ `RunRecord` — which agent, which model, what it cost, and the whole exchange as
518
+ `RunTurn[]`: every message out, every tool call with its arguments, every result
519
+ back.
520
+
521
+ `RunTurn` is deliberately moss's own shape. Moss depends on neither an LLM client
522
+ nor an agent framework, and a client's message union leaking into the app server
523
+ would make one provider's idea of a turn the contract. The caller flattens
524
+ whatever it ran into this, once, at the seam that knows both sides. Arguments stay
525
+ a string because providers send them JSON-encoded, and re-encoding a parse is how
526
+ a malformed call stops looking malformed in the record.
527
+
528
+ Nothing is aggregated, and there is no cost in currency: per-model price tables
529
+ rot, tokens are the honest unit, and `provider` + `model` let pricing be layered on
530
+ later. Per person, per model, per agent and per day are group-bys over the rows.
531
+
532
+ **No default sink.** A bounded in-memory array would answer "the last few minutes,
533
+ gone on restart", which is not a question anyone asks about an agent's behaviour.
534
+ Unset means unrecorded, which is at least honest. The session rides along so a sink
535
+ can persist through the CALLER's own governed wire rather than a privileged one —
536
+ a record that could be written on another principal's behalf would be worth
537
+ nothing.
538
+
539
+ ## What it refuses to be
540
+
541
+ | Temptation | Refusal |
542
+ |---|---|
543
+ | An auth provider | BYO identity. The server consumes a session token, never mints one; magic link is the default strategy. |
544
+ | A framework | An assembly point. The intelligence lives in the artifacts; the server resolves, serves, pushes, enforces. Component count stays single-digit. |
545
+ | A place where policy hides | Every opinion it enforces is a readable artifact: charter, scope policy, assertion. No annotations, no interceptor magic. |
546
+ | A second way to do anything | Reads are vex, writes are vex, compute is functions, UI is actions, permissions are the charter. Moss adds no vocabulary of its own. |
547
+ | A web framework | A page is a shell manifest at a path; a drawn document is a first frame delivered early. No file-system routes, no layouts-of-layouts, no loaders, no middleware, no head management: the template, the route and the kit are the app's. |
548
+
549
+ ## Deliberately unbuilt
550
+
551
+ On the record, so nothing reads as finished that isn't:
552
+
553
+ - **The artifact library.** Versioned artifact rows + snapshots + a published
554
+ pointer per channel, so publish is a runtime write, not a rebuild — the thing
555
+ §2 ("deployment is a data operation") is building toward. The open decisions
556
+ are tenancy overlays, draft/published channels, and live-shell migration on
557
+ publish (nova needs a `replaceAction` that rebinds live instances without
558
+ dropping their data). Verify-at-boot becomes verify-at-publish, same gates.
559
+ - **The `/fns` host** — named, side-effect-free, independently deployable
560
+ functions under `/fns`, gated by catalog closure.
561
+ - **The projection model** — per-identity state held in the DB, written-and-
562
+ pushed, seeded on login with no AI call, held while the principal is offline.
563
+ - **The working set (level streaming).** For large apps and AI context budgets,
564
+ the catalog itself streams: serve the graph neighborhood of a principal's
565
+ active actions now, fault the rest in on demand. Level streaming for humans is
566
+ context management for models — one mechanism, two products.
567
+ - **Scale-out** beyond sticky sessions pinned by session id. A drawn document
568
+ adds one requirement to stickiness: the page request and the socket should
569
+ land on the same process, or a principal's shell is built twice and the page
570
+ repaints once.
571
+ - **Opening the app at a position.** A path that seeds the *app's* shell (a
572
+ deep link to a record) is not built. It is not the same thing as a page's
573
+ parameters: the app's shell is durable and shared across a person's
574
+ terminals, so an opener has to be idempotent against whatever is already
575
+ mounted, and decide what a reload means after they have moved on.
576
+ - **Letting a page's connection go.** A terminal that holds a token on a page
577
+ drawn for nobody (a file, on a static host) connects, and is served a page
578
+ shell for as long as it stays — even when that page turns out not to be live
579
+ for them either. Closing such a connection once its frames are sent is unbuilt.
580
+ - **A stricter cookie.** The cookie is a copy of the token, readable by the
581
+ page's script like the token itself. An `HttpOnly` one — with the socket
582
+ reading it at the upgrade, the token out of the URL and out of script — needs
583
+ login to finish over HTTP (a socket message cannot set a cookie) and an Origin
584
+ check on the upgrade that does not exist today.
585
+
586
+ ## Boundaries
587
+
588
+ Moss composes the other nisc packages and owns none of their concerns: charter
589
+ resolves and verifies, vex reads and writes under scope, nova is the UI (headless
590
+ core + a framework adapter), prism is the endpoint transform language. Moss is
591
+ the organ that was missing — the trusted place where the charter executes, the
592
+ shell runs, and existence is served. See [DOCS.md](DOCS.md) for the API.