@niscorp/moss 0.3.3 → 0.5.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/CHANGELOG.md +534 -0
- package/DESIGN.md +265 -49
- package/DOCS.md +1524 -341
- package/README.md +37 -20
- package/dist/app-BoVB0_0j.d.ts +143 -0
- package/dist/app-Cc8VnOz8.d.cts +143 -0
- package/dist/chunk-3RIWTXGI.cjs +174 -0
- package/dist/chunk-3RIWTXGI.cjs.map +1 -0
- package/dist/chunk-4ZGAFZGS.js +152 -0
- package/dist/chunk-4ZGAFZGS.js.map +1 -0
- package/dist/chunk-5U2ZZUI5.cjs +137 -0
- package/dist/chunk-5U2ZZUI5.cjs.map +1 -0
- package/dist/chunk-6QPTMKRE.cjs +53 -0
- package/dist/chunk-6QPTMKRE.cjs.map +1 -0
- package/dist/chunk-BQRPR2F7.js +2704 -0
- package/dist/chunk-BQRPR2F7.js.map +1 -0
- package/dist/chunk-BZK37HR3.cjs +2716 -0
- package/dist/chunk-BZK37HR3.cjs.map +1 -0
- package/dist/chunk-FTFME3HS.cjs +383 -0
- package/dist/chunk-FTFME3HS.cjs.map +1 -0
- package/dist/{chunk-NE2EXMTO.js → chunk-FTZ6NFKZ.js} +43 -16
- package/dist/chunk-FTZ6NFKZ.js.map +1 -0
- package/dist/chunk-IUJ2TRNB.cjs +57 -0
- package/dist/chunk-IUJ2TRNB.cjs.map +1 -0
- package/dist/chunk-IW3A2YIC.js +49 -0
- package/dist/chunk-IW3A2YIC.js.map +1 -0
- package/dist/chunk-JYBHJDT7.cjs +30 -0
- package/dist/chunk-JYBHJDT7.cjs.map +1 -0
- package/dist/chunk-NRZ3Z2FF.js +61 -0
- package/dist/chunk-NRZ3Z2FF.js.map +1 -0
- package/dist/chunk-PCPQMC7A.js +26 -0
- package/dist/chunk-PCPQMC7A.js.map +1 -0
- package/dist/chunk-T5BRTFKP.js +53 -0
- package/dist/chunk-T5BRTFKP.js.map +1 -0
- package/dist/chunk-TGKDS2T7.cjs +330 -0
- package/dist/chunk-TGKDS2T7.cjs.map +1 -0
- package/dist/chunk-TLNRFAQ6.js +326 -0
- package/dist/chunk-TLNRFAQ6.js.map +1 -0
- package/dist/chunk-VKQPOZDJ.cjs +72 -0
- package/dist/chunk-VKQPOZDJ.cjs.map +1 -0
- package/dist/chunk-ZWB6QDGF.js +374 -0
- package/dist/chunk-ZWB6QDGF.js.map +1 -0
- package/dist/client/node.cjs.map +1 -1
- package/dist/client/node.d.cts +3 -1
- package/dist/client/node.d.ts +3 -1
- package/dist/client/node.js.map +1 -1
- package/dist/client.cjs +14 -302
- package/dist/client.cjs.map +1 -1
- package/dist/client.d.cts +9 -33
- package/dist/client.d.ts +9 -33
- package/dist/client.js +2 -2
- package/dist/document-CU3muGbz.d.cts +169 -0
- package/dist/document-UFbAd-Ka.d.ts +169 -0
- package/dist/env-CY8EGWnD.d.cts +24 -0
- package/dist/env-DEPqqHEb.d.ts +24 -0
- package/dist/index-BuDuOSyx.d.cts +130 -0
- package/dist/index-BuDuOSyx.d.ts +130 -0
- package/dist/index.cjs +45 -3918
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +46 -100
- package/dist/index.d.ts +46 -100
- package/dist/index.js +4 -94
- package/dist/index.js.map +1 -1
- package/dist/integrations.cjs +975 -0
- package/dist/integrations.cjs.map +1 -0
- package/dist/integrations.d.cts +63 -0
- package/dist/integrations.d.ts +63 -0
- package/dist/integrations.js +972 -0
- package/dist/integrations.js.map +1 -0
- package/dist/messages-CSwCJgH3.d.cts +51 -0
- package/dist/messages-CSwCJgH3.d.ts +51 -0
- package/dist/node.cjs +17 -3457
- package/dist/node.cjs.map +1 -1
- package/dist/node.d.cts +13 -10
- package/dist/node.d.ts +13 -10
- package/dist/node.js +5 -3
- package/dist/protocol.cjs +24 -0
- package/dist/protocol.cjs.map +1 -0
- package/dist/protocol.d.cts +11 -0
- package/dist/protocol.d.ts +11 -0
- package/dist/protocol.js +3 -0
- package/dist/protocol.js.map +1 -0
- package/dist/slots-96gNc9uH.d.cts +12 -0
- package/dist/slots-BX5N0Juv.d.ts +14 -0
- package/dist/slots-CU-AbnJg.d.cts +14 -0
- package/dist/slots-sLXDrlbG.d.ts +12 -0
- package/dist/socket-D90h1xSV.d.cts +24 -0
- package/dist/socket-D90h1xSV.d.ts +24 -0
- package/dist/targets-DInbLzff.d.cts +9 -0
- package/dist/targets-DInbLzff.d.ts +9 -0
- package/dist/terminal/dom/index.cjs +8 -3
- package/dist/terminal/dom/index.cjs.map +1 -1
- package/dist/terminal/dom/index.d.cts +3 -0
- package/dist/terminal/dom/index.d.ts +3 -0
- package/dist/terminal/dom/index.js +8 -3
- package/dist/terminal/dom/index.js.map +1 -1
- package/dist/terminal/dom/server.cjs +2 -7
- package/dist/terminal/dom/server.cjs.map +1 -1
- package/dist/terminal/dom/server.d.cts +3 -5
- package/dist/terminal/dom/server.d.ts +3 -5
- package/dist/terminal/dom/server.js +2 -7
- package/dist/terminal/dom/server.js.map +1 -1
- package/dist/terminal/index.cjs +22 -300
- package/dist/terminal/index.cjs.map +1 -1
- package/dist/terminal/index.d.cts +7 -2
- package/dist/terminal/index.d.ts +7 -2
- package/dist/terminal/index.js +21 -22
- package/dist/terminal/index.js.map +1 -1
- package/dist/terminal/ink/index.d.ts +3 -2
- package/dist/terminal/ink/index.js +149 -106
- package/dist/terminal/ink/index.js.map +1 -1
- package/dist/terminal/react/index.cjs +21 -71
- package/dist/terminal/react/index.cjs.map +1 -1
- package/dist/terminal/react/index.d.cts +5 -2
- package/dist/terminal/react/index.d.ts +5 -2
- package/dist/terminal/react/index.js +17 -20
- package/dist/terminal/react/index.js.map +1 -1
- package/dist/terminal/react/server.cjs +4 -68
- package/dist/terminal/react/server.cjs.map +1 -1
- package/dist/terminal/react/server.d.cts +9 -6
- package/dist/terminal/react/server.d.ts +9 -6
- package/dist/terminal/react/server.js +3 -18
- package/dist/terminal/react/server.js.map +1 -1
- package/dist/terminal/tty/index.cjs +147 -130
- package/dist/terminal/tty/index.cjs.map +1 -1
- package/dist/terminal/tty/index.d.cts +4 -2
- package/dist/terminal/tty/index.d.ts +4 -2
- package/dist/terminal/tty/index.js +147 -130
- package/dist/terminal/tty/index.js.map +1 -1
- package/dist/terminal/vue/index.cjs +20 -72
- package/dist/terminal/vue/index.cjs.map +1 -1
- package/dist/terminal/vue/index.d.cts +8 -12
- package/dist/terminal/vue/index.d.ts +8 -12
- package/dist/terminal/vue/index.js +45 -1
- package/dist/terminal/vue/index.js.map +1 -1
- package/dist/terminal/vue/server.cjs +4 -76
- package/dist/terminal/vue/server.cjs.map +1 -1
- package/dist/terminal/vue/server.d.cts +7 -6
- package/dist/terminal/vue/server.d.ts +7 -6
- package/dist/terminal/vue/server.js +3 -10
- package/dist/terminal/vue/server.js.map +1 -1
- package/dist/tide.cjs +41 -0
- package/dist/tide.cjs.map +1 -0
- package/dist/tide.d.cts +25 -0
- package/dist/tide.d.ts +25 -0
- package/dist/tide.js +39 -0
- package/dist/tide.js.map +1 -0
- package/dist/unverified.cjs +12 -0
- package/dist/unverified.cjs.map +1 -0
- package/dist/unverified.d.cts +7 -0
- package/dist/unverified.d.ts +7 -0
- package/dist/unverified.js +10 -0
- package/dist/unverified.js.map +1 -0
- package/dist/vite.cjs +96 -232
- package/dist/vite.cjs.map +1 -1
- package/dist/vite.d.cts +6 -8
- package/dist/vite.d.ts +6 -8
- package/dist/vite.js +97 -71
- package/dist/vite.js.map +1 -1
- package/package.json +56 -13
- package/dist/chunk-4T6KAXBP.js +0 -256
- package/dist/chunk-4T6KAXBP.js.map +0 -1
- package/dist/chunk-AUZMT3GL.js +0 -3406
- package/dist/chunk-AUZMT3GL.js.map +0 -1
- package/dist/chunk-EMRDIZLY.js +0 -99
- package/dist/chunk-EMRDIZLY.js.map +0 -1
- package/dist/chunk-HOZID4EM.js +0 -366
- package/dist/chunk-HOZID4EM.js.map +0 -1
- package/dist/chunk-NE2EXMTO.js.map +0 -1
- package/dist/chunk-SK4PDGEE.js +0 -55
- package/dist/chunk-SK4PDGEE.js.map +0 -1
- package/dist/document-DhWxieUc.d.cts +0 -1024
- package/dist/document-DhWxieUc.d.ts +0 -1024
- package/dist/slots-Do9ScG7v.d.cts +0 -37
- package/dist/slots-Do9ScG7v.d.ts +0 -37
package/DESIGN.md
CHANGED
|
@@ -51,11 +51,31 @@ Consequences:
|
|
|
51
51
|
UI are closed data, a publish can render its consequences in concrete terms —
|
|
52
52
|
*"crm.quotes → gained by: sales, intern, ray."* A human approves that.
|
|
53
53
|
|
|
54
|
-
Today the manifest is
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
54
|
+
Today the manifest is what the app handed `createServer`: read by a schema,
|
|
55
|
+
then frozen, so an edit to it throws. One part of it changes while a server
|
|
56
|
+
runs, through one door: a set of actions is handed over
|
|
57
|
+
(`server.replaceActions`) and verified before it is taken. The artifact library
|
|
58
|
+
that makes publish a runtime write for every artifact is specified and unbuilt
|
|
59
|
+
(see below). The mechanism is already the function it needs to be: what a set
|
|
60
|
+
of roles holds, and the policy it reads and writes under, are derived from what
|
|
61
|
+
is in force and dropped when that changes, so there is no invalidation
|
|
62
|
+
protocol; a pointer in the database tells every other process that it did.
|
|
63
|
+
The pointer tells them *that*, not *what*: another process reads again the
|
|
64
|
+
sets of actions it has a loader for (the ones a feature keeps in rows), and a
|
|
65
|
+
set handed to one process with `replaceActions` and no loader is that
|
|
66
|
+
process's alone. A library every process reads is the part that is unbuilt.
|
|
67
|
+
|
|
68
|
+
And there is one place it will be asked. Everything a shell loads that
|
|
69
|
+
somebody authored (its actions, its frame and layout store, its fragments, the
|
|
70
|
+
entries its reads replay) is answered by the running manifest in one function,
|
|
71
|
+
for a shell and a set of roles (`src/manifest/artifacts.ts`). A shell is built
|
|
72
|
+
from that answer and adopts it: an adopt puts in place the actions that are
|
|
73
|
+
held now, and the frame, each `{ ref }` of the layout store and each fragment
|
|
74
|
+
that the answer says differently from the last time. (The canvases are what a
|
|
75
|
+
shell starts with: an adopt does not take them again, a reset does.) The
|
|
76
|
+
entries vex replays are seeded from what
|
|
77
|
+
the running manifest holds; nothing else in moss reads one of the four off
|
|
78
|
+
what the app handed over.
|
|
59
79
|
|
|
60
80
|
### 3. One gate, every kind of principal
|
|
61
81
|
|
|
@@ -82,10 +102,13 @@ wait for it: the terminal never overwrites the value of the focused input when a
|
|
|
82
102
|
new tree arrives (bound inputs are identified by `model.path`), and `ui:model`
|
|
83
103
|
events debounce. A canvas — or a whole app — may also opt *out* and run its shell
|
|
84
104
|
in the browser, with vex as the enforcement floor: this is where offline and
|
|
85
|
-
zero-backend PGlite live. It is an explicit
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
105
|
+
zero-backend PGlite live. It is an explicit degrade, not a mode menu. What is
|
|
106
|
+
built is the whole app: an app with its own shell, which moss does not serve.
|
|
107
|
+
One screen mixing client-side canvases with authoritative server ones —
|
|
108
|
+
**authority islands** — is what the design allows, because a canvas slot
|
|
109
|
+
renders a tree and is indifferent to whether it came from a local shell or a
|
|
110
|
+
socket; no render target of moss's does it today, each registers its slots
|
|
111
|
+
against the wire alone (`src/terminal/targets.ts`).
|
|
89
112
|
|
|
90
113
|
---
|
|
91
114
|
|
|
@@ -98,23 +121,38 @@ The organizing principle: an app hands over **artifacts** and an
|
|
|
98
121
|
`vex_cache` is the API surface (nothing is generated), and the grantable set
|
|
99
122
|
is the introspected schema × vex's verb leaves. No table list is authored.
|
|
100
123
|
- **Per-principal resolution** is the charter applied at login: roles from the
|
|
101
|
-
assignment rows, granted action ids (with a
|
|
102
|
-
compiled vex scope policy, and the granted
|
|
103
|
-
|
|
124
|
+
app's `identity` seam or its assignment rows, granted action ids (with a
|
|
125
|
+
content-hash version token), the compiled vex scope policy, and the granted
|
|
126
|
+
layout variants (ring 2). Pure; kept for each set of roles, not for each
|
|
127
|
+
person, until what the app consists of changes.
|
|
104
128
|
- The **component registry** on the server is name-only stubs, derived by
|
|
105
|
-
walking the
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
129
|
+
walking what mentions a component: the actions in force, the layout
|
|
130
|
+
variants, the shell's canvases, frame, layout store and fragments
|
|
131
|
+
(nova/reflect's `componentsOf` — the walk is shared, not re-derived) — the
|
|
132
|
+
actual components live in the terminal.
|
|
133
|
+
- **Coherence is refused, not documented.** Whether an app may be served is
|
|
134
|
+
one verification (`src/manifest/verify.ts`): every action is one nova reads,
|
|
135
|
+
the charter verifies (`verifyCharter`, with nova's closure audit over the
|
|
136
|
+
definitions in force), every entry's `reach` names a profile the behaviors
|
|
137
|
+
declare, and nobody holds two layout variants of one action. It is asked at
|
|
138
|
+
boot, at every change (`refresh`, `replaceActions`), and of a manifest that
|
|
139
|
+
is not served (`verifyApp`); a boot or a change that fails it throws. The closure audit's findings are not errors: they are
|
|
140
|
+
filed under each role's `issues` in the report, and boot neither refuses on
|
|
141
|
+
them nor prints them. If it boots, the charter and the variants are
|
|
142
|
+
coherent; a push to an ungranted action can still be in it.
|
|
143
|
+
|
|
144
|
+
The test of the principle: moss's core adds no new vocabulary. Reads are vex,
|
|
145
|
+
writes are vex, compute is functions, UI is actions, permissions are the
|
|
146
|
+
charter. The server is the composition, not a fifth language. (The integrations
|
|
147
|
+
feature does read a document of its own, the bundle a separate service
|
|
148
|
+
publishes about itself. That is one reason it is a feature, and not the core.
|
|
149
|
+
Of a bundle it reads the fields that are nisc's own: the integration's id, what
|
|
150
|
+
it asks to be allowed, its grammar stamps, its actions and its phrases. What a
|
|
151
|
+
product adds to those (a store listing, where a screen is placed, a document a
|
|
152
|
+
person edits) is the host app's vocabulary: a bundle carries it under
|
|
153
|
+
`extension`, the app supplies the schema that reads it, and moss keeps it
|
|
154
|
+
without reading inside. A package does not own a closed vocabulary for what is
|
|
155
|
+
open.)
|
|
118
156
|
|
|
119
157
|
### Ring 2 — served layout variants
|
|
120
158
|
|
|
@@ -132,6 +170,145 @@ compiles it.
|
|
|
132
170
|
|
|
133
171
|
---
|
|
134
172
|
|
|
173
|
+
## How the code is laid out
|
|
174
|
+
|
|
175
|
+
Moss answers five questions about one request, in this order, and each
|
|
176
|
+
question has one module that owns it. A module is a directory under `src/`
|
|
177
|
+
with an `index.ts`, and nothing else sits at the top of `src/` but the main
|
|
178
|
+
entry.
|
|
179
|
+
|
|
180
|
+
1. **Who is calling?** `identity`: a token is a principal (the deployment's
|
|
181
|
+
verifier, moss's stored credential, the browser's cookie and its seal), and
|
|
182
|
+
a principal is a record (roles, scope values, what is installed for them).
|
|
183
|
+
2. **What exists for them?** `manifest`: what the app handed over, read by a
|
|
184
|
+
schema and frozen; what it consists of right now, with one writer; whether
|
|
185
|
+
that may be served; and what a set of roles holds of it. Every artifact a
|
|
186
|
+
shell is handed is asked of it: the actions, the frame and the layout
|
|
187
|
+
store, the fragments and the entries, in one answer for a shell and a set
|
|
188
|
+
of roles, and read off the app by nothing else. Of the entries it is the
|
|
189
|
+
source and not the only holder: see `data`, next.
|
|
190
|
+
3. **What may they read and write?** `data`: the vex engine, the policy a set
|
|
191
|
+
of roles reads and writes under, the routes, a seeded entry run as a
|
|
192
|
+
charter role, and the tables with their migration. The engine's cache is
|
|
193
|
+
the second place the app's entries are held. The running manifest's list
|
|
194
|
+
is copied into it once, at boot; from then on a replay, and the list of
|
|
195
|
+
fingerprints, resolve in the cache and the manifest is not asked; and the
|
|
196
|
+
cache holds what the list does not, a query written for an intent while
|
|
197
|
+
the app runs and any row it held before this boot. So what a fingerprint
|
|
198
|
+
resolves to is decided in `data` today, and what an action, a layout or a
|
|
199
|
+
fragment resolves to in `manifest`.
|
|
200
|
+
4. **What are they looking at?** `shells`: the shell host, one shell's build,
|
|
201
|
+
the stream of frames, and the screen read without attaching.
|
|
202
|
+
5. **How does it reach them?** `socket` for the live wire, `documents` for a
|
|
203
|
+
screen drawn into a page.
|
|
204
|
+
|
|
205
|
+
Under them sit two modules every other may import: `runtime`, what a
|
|
206
|
+
deployment supplies (the database, the verifier, the limits, the telemetry
|
|
207
|
+
sink), and `protocol`, what both ends of the wire agree on (the messages, the
|
|
208
|
+
close codes, the delta codec, the snapshot a drawn page carries). Over them
|
|
209
|
+
sits `server`, which answers none of the five: `createServer` constructs the
|
|
210
|
+
modules, hands each the narrow things it needs, starts the features and mounts
|
|
211
|
+
the routes, one step to a line. Over `server` sits `node`, how moss runs on
|
|
212
|
+
Node: the listener, the `ws` transport, the built site, and the Vite dev plugin
|
|
213
|
+
(`@niscorp/moss/node` and `/vite`). It imports the server, and nothing imports
|
|
214
|
+
it.
|
|
215
|
+
|
|
216
|
+
A **feature** owns none of the five. It lives in a directory of its own, ships
|
|
217
|
+
from an entry point of its own, and the core never imports it: the app creates
|
|
218
|
+
it and names it in its manifest's `features`, and the server starts it with
|
|
219
|
+
the seams (`FeatureSeams`: every member one function or one narrow value of
|
|
220
|
+
the module that owns it). `Feature` and `FeatureSeams` are the contract between
|
|
221
|
+
moss and its two features, and are not exported: an app names a feature and
|
|
222
|
+
cannot write one. **The seams are made for the feature they are handed
|
|
223
|
+
to, and what they reach is that feature's**: its own tables, which it names on
|
|
224
|
+
itself before it runs (`Feature.tables.names`); its own set of actions, kept
|
|
225
|
+
under its name, which it alone writes; the documents in its own rows. The core reads and
|
|
226
|
+
writes no row of a feature, reads no header of one, and holds no setting of
|
|
227
|
+
one (the key the integrations feature signs with is that feature's own).
|
|
228
|
+
`feature` is the module that says what a feature and
|
|
229
|
+
its seams are: types, and no code. There are two features: `integrations`
|
|
230
|
+
(`@niscorp/moss/integrations`), and `tide` (`@niscorp/moss/tide`), a committed
|
|
231
|
+
write minted into tide as a fact. A feature that needs something the seams do
|
|
232
|
+
not offer does not reach for it: the seam is added to the module that owns
|
|
233
|
+
the answer first, as a change of its own.
|
|
234
|
+
|
|
235
|
+
The terminal side is two more modules, built and shipped apart from the
|
|
236
|
+
server: `client`, the wire, which imports `protocol` and nothing else of moss,
|
|
237
|
+
and `terminal`, the conductor and the render targets, which imports `client`.
|
|
238
|
+
|
|
239
|
+
Which module may import which is written down once, as a table a build reads:
|
|
240
|
+
`scripts/check-modules.mts` in the repository. That table is the truth, and
|
|
241
|
+
this is a copy of it:
|
|
242
|
+
|
|
243
|
+
| Module | May import |
|
|
244
|
+
|---|---|
|
|
245
|
+
| `runtime` | nothing of moss |
|
|
246
|
+
| `protocol` | nothing of moss |
|
|
247
|
+
| `feature` | `runtime` |
|
|
248
|
+
| `identity` | `runtime`, `protocol` |
|
|
249
|
+
| `manifest` | `identity`, `feature` |
|
|
250
|
+
| `data` | `runtime`, `identity`, `manifest` |
|
|
251
|
+
| `shells` | `runtime`, `protocol`, `manifest`, `data` |
|
|
252
|
+
| `socket` | `runtime`, `protocol`, `identity`, `shells` |
|
|
253
|
+
| `documents` | `protocol`, `identity`, `shells` |
|
|
254
|
+
| `server` | every module above, and no feature |
|
|
255
|
+
| `node` | `runtime`, `protocol`, `identity`, `manifest`, `socket`, `documents`, `server` |
|
|
256
|
+
| `integrations` (a feature) | `runtime`, `feature` |
|
|
257
|
+
| `tide` (a feature) | `feature` |
|
|
258
|
+
| `client` | `protocol` |
|
|
259
|
+
| `terminal` | `client` |
|
|
260
|
+
|
|
261
|
+
The table has no cycle, and what it leaves out is as deliberate as what it
|
|
262
|
+
names. `shells` does not import `identity`: who somebody is, it is told.
|
|
263
|
+
`socket` does not import `manifest`: what somebody holds is a function it is
|
|
264
|
+
handed. `integrations` does not import `data`: what it reads and writes it
|
|
265
|
+
authors as vex entries and replays through a seam. Nor `manifest`: what it
|
|
266
|
+
asks about a bundle before letting it in (does a layout fit the kit, which
|
|
267
|
+
chains of steps never end) it asks through two seams. A feature imports `feature`, and `runtime` for where a span
|
|
268
|
+
goes, and nothing else of moss. A module imports another by its `index.ts`
|
|
269
|
+
and never a file inside it.
|
|
270
|
+
|
|
271
|
+
Four rules go with the table. A module's factory is handed a typed object of
|
|
272
|
+
the functions and values it needs, never the whole manifest and never the
|
|
273
|
+
whole runtime: those two are handed to `createServer`, and the wiring hands on
|
|
274
|
+
the parts. Each table and each long-lived piece of state has one owner, and
|
|
275
|
+
nobody else authors what is written to it. What crosses a boundary (a
|
|
276
|
+
manifest, a socket message, a route's body, a row, a token) is parsed by a
|
|
277
|
+
schema in the module where it enters, and no module holds a type assertion.
|
|
278
|
+
And a function is at most 300 lines (200 is fine; 300 is the ceiling), a file
|
|
279
|
+
at most 400 lines of code, a line at most 200 wide.
|
|
280
|
+
|
|
281
|
+
**One owner, as the code has it.** The owner of a table authors every
|
|
282
|
+
statement on its rows. It is not always the module that runs them, or the one
|
|
283
|
+
that made the table:
|
|
284
|
+
|
|
285
|
+
| Table | Whose | Where its statements are written | What is somewhere else, and why |
|
|
286
|
+
|---|---|---|---|
|
|
287
|
+
| `sessions` | `identity` | `identity/sessions.ts`: five statements straight to the pool, before anybody is signed in | Its table is made in `data`'s one migration run, from a sequence `identity` declares |
|
|
288
|
+
| `moss_generation` | `data` | `data/own-entries.ts`: two entries, one that reads and one that moves | `manifest` decides when it moves (`manifest/generation.ts`), through a function `data` hands over |
|
|
289
|
+
| `integrations`, `integration_actions` | the `integrations` feature | `integrations/entries.ts`: vex entries, replayed through the seam the feature is handed | The two tables are made by the core's own sequence (`data/tables.ts`, `nisc.moss`): that is the history every database has run, and it is not edited. The documents stored in `integration_actions` are brought to the current grammars by `data`, which holds the pool, when the feature asks through its seam |
|
|
290
|
+
|
|
291
|
+
`data` holds the engine and the one ledgered migration run, so every owner's
|
|
292
|
+
entries and every owner's migrations run through it. It authors no statement
|
|
293
|
+
on a table that is not its own. The app's own tables, and tide's when the app
|
|
294
|
+
keeps them, are migrated in the same run (`runtime.tables`) and are the app's
|
|
295
|
+
and tide's.
|
|
296
|
+
|
|
297
|
+
What holds the rules is a build that fails, not this page: `pnpm
|
|
298
|
+
check:modules` (the table above, the doors, nothing flat, no cycle, and no
|
|
299
|
+
feature in the core), `pnpm check:api` (an exported name is a line in
|
|
300
|
+
`api.txt`, and a line there is an exported name), `pnpm check:raw-sql` (a
|
|
301
|
+
statement outside vex is counted, with its reason) and `pnpm lint` (no type
|
|
302
|
+
assertion, no `any` that becomes a typed value, no written type predicate, the
|
|
303
|
+
two sizes and the width).
|
|
304
|
+
**Narrow inputs and one owner are held by none of the four**: they are read
|
|
305
|
+
for in review, and the table above is what a review found, not what a build
|
|
306
|
+
checks. What each gate holds is said at the top of its script. The rules
|
|
307
|
+
as somebody changing a package follows them are in the application guide,
|
|
308
|
+
"Changing a package" (`packages/nisc/AGENTS.md`).
|
|
309
|
+
|
|
310
|
+
---
|
|
311
|
+
|
|
135
312
|
## The socket
|
|
136
313
|
|
|
137
314
|
The authority channel. Transport-blind: the protocol speaks through a
|
|
@@ -190,6 +367,18 @@ Operational shape, all falling out of "the message is state, not history":
|
|
|
190
367
|
receive it, and the terminal holds no location that could drift out of step
|
|
191
368
|
with the server's. It is also the answer to a real failure: with no history
|
|
192
369
|
integration at all, a browser's back button unloaded the application.
|
|
370
|
+
- **A connection that drops.** The trees a terminal holds stay on screen
|
|
371
|
+
while it reconnects: the current ones are re-sent when it does, and blanking
|
|
372
|
+
in between would show a working app as an empty one. The price is that a
|
|
373
|
+
screen left up by a dead socket looks exactly like a live one, so the
|
|
374
|
+
connection's status is on what every render target renders against, beside
|
|
375
|
+
the frame and the trees, and a change of it is an update like a change of
|
|
376
|
+
them. What is drawn for it is not moss's: the two console targets print a
|
|
377
|
+
line, and the three that draw into an element say it on that element
|
|
378
|
+
(`data-wire-status`) and leave what it looks like to the app's stylesheet.
|
|
379
|
+
The terminal holds one socket at a time — it lets go of the one it had
|
|
380
|
+
before it makes another — so one connection writes the screen, whatever a
|
|
381
|
+
person pressed while the last was still connecting.
|
|
193
382
|
- **Emptiness.** A canvas whose layout renders no visible content is served as
|
|
194
383
|
`[]`, so a terminal collapses chrome on `length` alone. An `ActionSlot` is a
|
|
195
384
|
boundary, not content — visibility is decided by what's inside it.
|
|
@@ -268,7 +457,7 @@ Two reductions are available, and they are deliberately separate things:
|
|
|
268
457
|
constant.
|
|
269
458
|
- **Frame deltas** (`shellFrameDelta`, **off** by default) describe a changed
|
|
270
459
|
canvas against the frame the connection already holds, as copy runs plus
|
|
271
|
-
literal inserts (`src/delta.ts` — an encoder and a decoder, both readable in
|
|
460
|
+
literal inserts (`src/protocol/delta.ts` — an encoder and a decoder, both readable in
|
|
272
461
|
full, no dependency). Measured on Lyra: an in-place change (a keystroke
|
|
273
462
|
filtering a list, one row's badge flipping) falls to **1–4%** of the frame; a
|
|
274
463
|
navigation, where the tree is genuinely different, lands near **80%** and is
|
|
@@ -339,19 +528,28 @@ Two design points worth naming:
|
|
|
339
528
|
One durable nova `Shell` per authenticated principal — the socket is ephemeral,
|
|
340
529
|
the shell survives disconnect (reattach re-sends the current trees, and N
|
|
341
530
|
attached connections receive the same frames: shared canvases are the same
|
|
342
|
-
mechanism). Anonymous connections get a throwaway shell, disposed on detach
|
|
531
|
+
mechanism). Anonymous connections get a throwaway shell, disposed on detach,
|
|
532
|
+
and so does every connection of a page.
|
|
533
|
+
|
|
534
|
+
**Every living shell follows a change.** When what the app consists of
|
|
535
|
+
changes, each shell that lives is brought level with what its principal holds
|
|
536
|
+
now, in place: the kept ones, a visitor's, and a page's, in every host. A
|
|
537
|
+
host holds every shell it built from when its build lands until it ends, and
|
|
538
|
+
lets it go where it ends, so the walk is over the shells that live and no
|
|
539
|
+
other. A role change (`invalidateIdentity`) rebuilds every living shell of
|
|
540
|
+
that principal the same way: the kept one, and each one a page built for them.
|
|
343
541
|
|
|
344
542
|
**Lifetime.** A durable shell lives until sign-out, an operator reset, or the
|
|
345
|
-
idle sweep: nothing attached for `
|
|
346
|
-
disposed, rebuilt on the next connection. Only the idle clock is swept —
|
|
543
|
+
idle sweep: nothing attached for `runtime.shellIdleMs` (default 30 minutes) and
|
|
544
|
+
it is disposed, rebuilt on the next connection. Only the idle clock is swept —
|
|
347
545
|
deliberately no absolute cap, because that would discard the state of somebody
|
|
348
546
|
who is working. There is no TTL on the session behind it; a shell going away is
|
|
349
547
|
not a person being signed out.
|
|
350
548
|
|
|
351
|
-
**Enumeration and reset.** `shells.list()` reports every living shell
|
|
352
|
-
principal, attached connections, age, idle time, and what is
|
|
353
|
-
canvas. `shells.reset(principal)` disposes one and stands its
|
|
354
|
-
the same slot, carrying the attached connections across, so every terminal
|
|
549
|
+
**Enumeration and reset.** `shells.list()` reports every living shell the
|
|
550
|
+
host keeps — principal, attached connections, age, idle time, and what is
|
|
551
|
+
mounted on each canvas. `shells.reset(principal)` disposes one and stands its
|
|
552
|
+
replacement in the same slot, carrying the attached connections across, so every terminal
|
|
355
553
|
receives a frame and current trees exactly as on reattach. Both exist because
|
|
356
554
|
the host owns the map: an app that keeps its own note beside it can only drift
|
|
357
555
|
from it, and a shell nobody can enumerate is one nobody can be helped out of.
|
|
@@ -387,7 +585,7 @@ committed write to a table the query reads, it refetches (once for everybody
|
|
|
387
585
|
who would get the same rows) and calls back with the caller's new answer if it
|
|
388
586
|
changed (vex DESIGN.md, "Reactive reads").
|
|
389
587
|
|
|
390
|
-
The wire is the whole seam (`src/
|
|
588
|
+
The wire is the whole seam (`src/data/writes.ts`). Toward vex it is a `VexLive` — a
|
|
391
589
|
signal and a callback, carried in the in-process request's hono env, where no
|
|
392
590
|
network request can put one. Toward nova it is the response's `onChange`, which
|
|
393
591
|
nova applies through the endpoint's own `response` and `target`; the shell
|
|
@@ -466,7 +664,8 @@ Six things had to be true, and each is a small, separate decision:
|
|
|
466
664
|
- **Who may keep a page follows from who asked.** Drawn for nobody, a page is
|
|
467
665
|
the same for everybody and may be cached or written to a file; drawn for
|
|
468
666
|
somebody, it is theirs (`private, no-store`). That is one function
|
|
469
|
-
(`
|
|
667
|
+
(in `src/documents/document.ts`; `renderDocument` answers what it says as
|
|
668
|
+
the page's `headers`), keyed on whether a principal resolved. No page, route or
|
|
470
669
|
app declares which kind it is, so none can declare it wrong.
|
|
471
670
|
- **Nothing here can fail a page.** A kit component that throws, a shell that
|
|
472
671
|
will not build, a template without a root: the template goes out as it is and
|
|
@@ -516,7 +715,7 @@ an action — a `ui:` trigger, a two-way binding, a channel it waits on, a read
|
|
|
516
715
|
that keeps answering — so the question is decidable from the definitions
|
|
517
716
|
actually mounted, without running anything. Nova reports those facts
|
|
518
717
|
(`livenessOf`); moss, which holds the entries behind each fingerprint, composes
|
|
519
|
-
the verdict (`
|
|
718
|
+
the verdict (`src/shells/snapshot.ts`) and puts it on the snapshot as `live`. A page that
|
|
520
719
|
is not live is served as markup and its terminal opens no socket at all. A page
|
|
521
720
|
that is live gets a shell for as long as its connection lasts — per connection,
|
|
522
721
|
never per person. The one thing counted live without being read is code: a `fn:`
|
|
@@ -544,9 +743,12 @@ the application guide puts it — shell state is the truth.
|
|
|
544
743
|
|
|
545
744
|
The `fn:` escape hatch runs server-side, in-process, next to the durable shell.
|
|
546
745
|
The manifest's `functions(session)` builds handlers once per session, closing
|
|
547
|
-
over the living shell,
|
|
548
|
-
|
|
549
|
-
|
|
746
|
+
over the living shell, who is calling (the principal, their roles, what they
|
|
747
|
+
hold), the server's own surfaces as that session (`wire`), and `grant`/`revoke`.
|
|
748
|
+
A session says who is calling and holds no key: it carries no database pool, no
|
|
749
|
+
operator key and no policy object, and what app code needs of those has a call
|
|
750
|
+
(DOCS.md, `FunctionSession`). Agents live here (their reads run under the
|
|
751
|
+
caller's policy — they see what the caller sees); keys are `.env`. This is deliberately the *side-
|
|
550
752
|
effect-ful, session-bound* half. The canonical, side-effect-free function — an
|
|
551
753
|
independently deployable endpoint under `/fns` — is specified and pending.
|
|
552
754
|
|
|
@@ -554,7 +756,7 @@ independently deployable endpoint under `/fns` — is specified and pending.
|
|
|
554
756
|
|
|
555
757
|
Vex is the choke point every application write passes through, which makes its
|
|
556
758
|
write observer the one place a host can learn about all of them. Moss
|
|
557
|
-
|
|
759
|
+
hears it once and offers the news two ways — and the split is a privilege
|
|
558
760
|
boundary, not a convenience.
|
|
559
761
|
|
|
560
762
|
**The app lane carries no rows.** A declared reaction hears table, op, row
|
|
@@ -565,7 +767,10 @@ governed wire as everybody else. The alternative — handing rows to a callback
|
|
|
565
767
|
— puts data in the one place this stack has no fence for, arbitrary imperative
|
|
566
768
|
code, and `deliver` payloads are pings for exactly the same reason.
|
|
567
769
|
|
|
568
|
-
**The tide lane carries rows, because tide has the fence.**
|
|
770
|
+
**The tide lane carries rows, because tide has the fence.** It is a feature
|
|
771
|
+
(`createTideFacts`, `@niscorp/moss/tide`), not part of the core: it hears a
|
|
772
|
+
write through the one seam a feature is handed for that, and an app that runs
|
|
773
|
+
no tide names none. A fact is stamped
|
|
569
774
|
with the identity derived from the *write's own* scope, and the matcher offers
|
|
570
775
|
a fact only to reflexes running under that same identity. Tide is the one
|
|
571
776
|
place a row travels without being read — no policy is consulted on the way —
|
|
@@ -582,7 +787,9 @@ assert them, the way an app already asserts its charter.
|
|
|
582
787
|
|
|
583
788
|
**Pacing belongs to the host, not the engine.** Tide names the next instant it
|
|
584
789
|
wants waking for; the driver owns the timer, wakes on every ingest, and drains
|
|
585
|
-
to quiescence. The
|
|
790
|
+
to quiescence. The driver is tide's own (`createTideDriver`), as the Postgres
|
|
791
|
+
store is (`@niscorp/tide/postgres`): both were moss's, and they are tide's
|
|
792
|
+
pacing and tide's storage. The interval that used to stand in for this was both a latency
|
|
586
793
|
floor and a throughput ceiling — a chain advanced one hop per beat — and the
|
|
587
794
|
only periodic thing left is a janitor that finds nothing when nothing is
|
|
588
795
|
broken.
|
|
@@ -618,11 +825,11 @@ nothing.
|
|
|
618
825
|
|
|
619
826
|
| Temptation | Refusal |
|
|
620
827
|
|---|---|
|
|
621
|
-
| An auth provider | BYO identity.
|
|
622
|
-
| A framework | An assembly point. The intelligence lives in the artifacts; the server resolves, serves, pushes, enforces.
|
|
828
|
+
| An auth provider | BYO identity. Who somebody is, the app decides at its own door (magic link is the default strategy); the server only asks who a token is. Moss does keep a credential an app may use for that: `mintSession` stores a token by its hash once the app has decided, and `'dev-open'` trusts an unsigned one for a harness. Neither decides anything. |
|
|
829
|
+
| A framework | An assembly point. The intelligence lives in the artifacts; the server resolves, serves, pushes, enforces. Its core is ten modules, each one question or the wiring, and an eleventh that runs it on Node (*How the code is laid out*). |
|
|
623
830
|
| A place where policy hides | Every opinion it enforces is a readable artifact: charter, scope policy, assertion. No annotations, no interceptor magic. |
|
|
624
|
-
| 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. |
|
|
625
|
-
| 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,
|
|
831
|
+
| A second way to do anything | Reads are vex, writes are vex, compute is functions, UI is actions, permissions are the charter. Moss's core adds no vocabulary of its own, and holds itself to the same: the rows it keeps it reads and writes through vex entries, and the statements left outside vex are counted, each with its reason (`pnpm check:raw-sql`). |
|
|
832
|
+
| 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, and no chain of middleware for an app to configure (one gate may be laid over the operator prefix, `runtime.operatorGate`). A page's `<head>` is not managed either: it is a node in a layout, written into the document like the rest of the screen. The template, the route and the kit are the app's. |
|
|
626
833
|
|
|
627
834
|
## Deliberately unbuilt
|
|
628
835
|
|
|
@@ -644,12 +851,21 @@ On the record, so nothing reads as finished that isn't:
|
|
|
644
851
|
context management for models — one mechanism, two products.
|
|
645
852
|
- **Scale-out** beyond sticky sessions pinned by session id. What crosses
|
|
646
853
|
processes today is invalidation only: `refresh` moves a generation pointer
|
|
647
|
-
every process polls (`src/generation.ts`
|
|
648
|
-
|
|
854
|
+
every process polls (`src/manifest/generation.ts` holds the clock; the row is
|
|
855
|
+
read and moved through vex, `src/data/own-entries.ts`), and an optional fabric
|
|
856
|
+
(`runtime.fabric`, `src/server/signals.ts`) carries identity invalidations and nudges.
|
|
857
|
+
A set of actions does not cross: a process that follows the pointer reads
|
|
858
|
+
again the sets it has a loader for, and a set handed to another process
|
|
859
|
+
with `replaceActions` alone never reaches it (DOCS.md, "Many processes").
|
|
649
860
|
A shell is still resident in one process. A drawn document
|
|
650
861
|
adds one requirement to stickiness: the page request and the socket should
|
|
651
862
|
land on the same process, or a principal's shell is built twice and the page
|
|
652
|
-
repaints once.
|
|
863
|
+
repaints once. And one limit is each process's own: the integrations'
|
|
864
|
+
webhook door lets 240 calls a minute through for each integration, counted
|
|
865
|
+
in the memory of the process that takes them, so N processes let a vendor
|
|
866
|
+
through up to N times as often. One ceiling for a deployment would be a
|
|
867
|
+
store its processes share, with a write for every call; it is not built,
|
|
868
|
+
and a deployment that needs it sets it at its proxy.
|
|
653
869
|
- **Opening the app at a position.** A path that seeds the *app's* shell (a
|
|
654
870
|
deep link to a record) is not built. It is not the same thing as a page's
|
|
655
871
|
parameters: the app's shell is durable and shared across a person's
|