@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.
- package/DESIGN.md +592 -0
- package/DOCS.md +943 -0
- package/LICENSE +202 -0
- package/README.md +155 -0
- package/dist/chunk-2AHJ6VDR.js +3314 -0
- package/dist/chunk-2AHJ6VDR.js.map +1 -0
- package/dist/chunk-EMRDIZLY.js +99 -0
- package/dist/chunk-EMRDIZLY.js.map +1 -0
- package/dist/chunk-HF6IGQ74.js +3342 -0
- package/dist/chunk-HF6IGQ74.js.map +1 -0
- package/dist/chunk-J72N3EMJ.js +238 -0
- package/dist/chunk-J72N3EMJ.js.map +1 -0
- package/dist/chunk-SK4PDGEE.js +55 -0
- package/dist/chunk-SK4PDGEE.js.map +1 -0
- package/dist/chunk-ZOEUEMDX.js +251 -0
- package/dist/chunk-ZOEUEMDX.js.map +1 -0
- package/dist/client/node.cjs +42 -0
- package/dist/client/node.cjs.map +1 -0
- package/dist/client/node.d.cts +9 -0
- package/dist/client/node.d.ts +9 -0
- package/dist/client/node.js +40 -0
- package/dist/client/node.js.map +1 -0
- package/dist/client.cjs +275 -0
- package/dist/client.cjs.map +1 -0
- package/dist/client.d.cts +52 -0
- package/dist/client.d.ts +52 -0
- package/dist/client.js +4 -0
- package/dist/client.js.map +1 -0
- package/dist/document-BEn2zXah.d.cts +993 -0
- package/dist/document-BEn2zXah.d.ts +993 -0
- package/dist/index.cjs +3716 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +104 -0
- package/dist/index.d.ts +104 -0
- package/dist/index.js +96 -0
- package/dist/index.js.map +1 -0
- package/dist/node.cjs +3309 -0
- package/dist/node.cjs.map +1 -0
- package/dist/node.d.cts +28 -0
- package/dist/node.d.ts +28 -0
- package/dist/node.js +64 -0
- package/dist/node.js.map +1 -0
- package/dist/slots-Do9ScG7v.d.cts +37 -0
- package/dist/slots-Do9ScG7v.d.ts +37 -0
- package/dist/terminal/dom/index.cjs +34 -0
- package/dist/terminal/dom/index.cjs.map +1 -0
- package/dist/terminal/dom/index.d.cts +11 -0
- package/dist/terminal/dom/index.d.ts +11 -0
- package/dist/terminal/dom/index.js +32 -0
- package/dist/terminal/dom/index.js.map +1 -0
- package/dist/terminal/dom/server.cjs +16 -0
- package/dist/terminal/dom/server.cjs.map +1 -0
- package/dist/terminal/dom/server.d.cts +14 -0
- package/dist/terminal/dom/server.d.ts +14 -0
- package/dist/terminal/dom/server.js +14 -0
- package/dist/terminal/dom/server.js.map +1 -0
- package/dist/terminal/index.cjs +346 -0
- package/dist/terminal/index.cjs.map +1 -0
- package/dist/terminal/index.d.cts +32 -0
- package/dist/terminal/index.d.ts +32 -0
- package/dist/terminal/index.js +100 -0
- package/dist/terminal/index.js.map +1 -0
- package/dist/terminal/ink/index.d.ts +33 -0
- package/dist/terminal/ink/index.js +189 -0
- package/dist/terminal/ink/index.js.map +1 -0
- package/dist/terminal/react/index.cjs +87 -0
- package/dist/terminal/react/index.cjs.map +1 -0
- package/dist/terminal/react/index.d.cts +15 -0
- package/dist/terminal/react/index.d.ts +15 -0
- package/dist/terminal/react/index.js +35 -0
- package/dist/terminal/react/index.js.map +1 -0
- package/dist/terminal/react/server.cjs +79 -0
- package/dist/terminal/react/server.cjs.map +1 -0
- package/dist/terminal/react/server.d.cts +16 -0
- package/dist/terminal/react/server.d.ts +16 -0
- package/dist/terminal/react/server.js +28 -0
- package/dist/terminal/react/server.js.map +1 -0
- package/dist/terminal/tty/index.cjs +201 -0
- package/dist/terminal/tty/index.cjs.map +1 -0
- package/dist/terminal/tty/index.d.cts +18 -0
- package/dist/terminal/tty/index.d.ts +18 -0
- package/dist/terminal/tty/index.js +199 -0
- package/dist/terminal/tty/index.js.map +1 -0
- package/dist/terminal/vue/index.cjs +104 -0
- package/dist/terminal/vue/index.cjs.map +1 -0
- package/dist/terminal/vue/index.d.cts +23 -0
- package/dist/terminal/vue/index.d.ts +23 -0
- package/dist/terminal/vue/index.js +3 -0
- package/dist/terminal/vue/index.js.map +1 -0
- package/dist/terminal/vue/server.cjs +88 -0
- package/dist/terminal/vue/server.cjs.map +1 -0
- package/dist/terminal/vue/server.d.cts +18 -0
- package/dist/terminal/vue/server.d.ts +18 -0
- package/dist/terminal/vue/server.js +21 -0
- package/dist/terminal/vue/server.js.map +1 -0
- 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.
|