@niscorp/moss 0.4.0 → 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.
Files changed (175) hide show
  1. package/CHANGELOG.md +481 -0
  2. package/DESIGN.md +265 -49
  3. package/DOCS.md +1524 -341
  4. package/README.md +37 -20
  5. package/dist/app-BoVB0_0j.d.ts +143 -0
  6. package/dist/app-Cc8VnOz8.d.cts +143 -0
  7. package/dist/chunk-3RIWTXGI.cjs +174 -0
  8. package/dist/chunk-3RIWTXGI.cjs.map +1 -0
  9. package/dist/chunk-4ZGAFZGS.js +152 -0
  10. package/dist/chunk-4ZGAFZGS.js.map +1 -0
  11. package/dist/chunk-5U2ZZUI5.cjs +137 -0
  12. package/dist/chunk-5U2ZZUI5.cjs.map +1 -0
  13. package/dist/chunk-6QPTMKRE.cjs +53 -0
  14. package/dist/chunk-6QPTMKRE.cjs.map +1 -0
  15. package/dist/chunk-BQRPR2F7.js +2704 -0
  16. package/dist/chunk-BQRPR2F7.js.map +1 -0
  17. package/dist/chunk-BZK37HR3.cjs +2716 -0
  18. package/dist/chunk-BZK37HR3.cjs.map +1 -0
  19. package/dist/chunk-FTFME3HS.cjs +383 -0
  20. package/dist/chunk-FTFME3HS.cjs.map +1 -0
  21. package/dist/{chunk-U3UR5AOQ.js → chunk-FTZ6NFKZ.js} +43 -16
  22. package/dist/chunk-FTZ6NFKZ.js.map +1 -0
  23. package/dist/chunk-IUJ2TRNB.cjs +57 -0
  24. package/dist/chunk-IUJ2TRNB.cjs.map +1 -0
  25. package/dist/chunk-IW3A2YIC.js +49 -0
  26. package/dist/chunk-IW3A2YIC.js.map +1 -0
  27. package/dist/chunk-JYBHJDT7.cjs +30 -0
  28. package/dist/chunk-JYBHJDT7.cjs.map +1 -0
  29. package/dist/chunk-NRZ3Z2FF.js +61 -0
  30. package/dist/chunk-NRZ3Z2FF.js.map +1 -0
  31. package/dist/chunk-PCPQMC7A.js +26 -0
  32. package/dist/chunk-PCPQMC7A.js.map +1 -0
  33. package/dist/chunk-T5BRTFKP.js +53 -0
  34. package/dist/chunk-T5BRTFKP.js.map +1 -0
  35. package/dist/chunk-TGKDS2T7.cjs +330 -0
  36. package/dist/chunk-TGKDS2T7.cjs.map +1 -0
  37. package/dist/chunk-TLNRFAQ6.js +326 -0
  38. package/dist/chunk-TLNRFAQ6.js.map +1 -0
  39. package/dist/chunk-VKQPOZDJ.cjs +72 -0
  40. package/dist/chunk-VKQPOZDJ.cjs.map +1 -0
  41. package/dist/chunk-ZWB6QDGF.js +374 -0
  42. package/dist/chunk-ZWB6QDGF.js.map +1 -0
  43. package/dist/client/node.cjs.map +1 -1
  44. package/dist/client/node.d.cts +3 -1
  45. package/dist/client/node.d.ts +3 -1
  46. package/dist/client/node.js.map +1 -1
  47. package/dist/client.cjs +14 -302
  48. package/dist/client.cjs.map +1 -1
  49. package/dist/client.d.cts +9 -33
  50. package/dist/client.d.ts +9 -33
  51. package/dist/client.js +2 -2
  52. package/dist/document-CU3muGbz.d.cts +169 -0
  53. package/dist/document-UFbAd-Ka.d.ts +169 -0
  54. package/dist/env-CY8EGWnD.d.cts +24 -0
  55. package/dist/env-DEPqqHEb.d.ts +24 -0
  56. package/dist/index-BuDuOSyx.d.cts +130 -0
  57. package/dist/index-BuDuOSyx.d.ts +130 -0
  58. package/dist/index.cjs +45 -3916
  59. package/dist/index.cjs.map +1 -1
  60. package/dist/index.d.cts +46 -100
  61. package/dist/index.d.ts +46 -100
  62. package/dist/index.js +4 -94
  63. package/dist/index.js.map +1 -1
  64. package/dist/integrations.cjs +975 -0
  65. package/dist/integrations.cjs.map +1 -0
  66. package/dist/integrations.d.cts +63 -0
  67. package/dist/integrations.d.ts +63 -0
  68. package/dist/integrations.js +972 -0
  69. package/dist/integrations.js.map +1 -0
  70. package/dist/messages-CSwCJgH3.d.cts +51 -0
  71. package/dist/messages-CSwCJgH3.d.ts +51 -0
  72. package/dist/node.cjs +17 -3455
  73. package/dist/node.cjs.map +1 -1
  74. package/dist/node.d.cts +13 -10
  75. package/dist/node.d.ts +13 -10
  76. package/dist/node.js +5 -3
  77. package/dist/protocol.cjs +24 -0
  78. package/dist/protocol.cjs.map +1 -0
  79. package/dist/protocol.d.cts +11 -0
  80. package/dist/protocol.d.ts +11 -0
  81. package/dist/protocol.js +3 -0
  82. package/dist/protocol.js.map +1 -0
  83. package/dist/slots-96gNc9uH.d.cts +12 -0
  84. package/dist/slots-BX5N0Juv.d.ts +14 -0
  85. package/dist/slots-CU-AbnJg.d.cts +14 -0
  86. package/dist/slots-sLXDrlbG.d.ts +12 -0
  87. package/dist/socket-D90h1xSV.d.cts +24 -0
  88. package/dist/socket-D90h1xSV.d.ts +24 -0
  89. package/dist/targets-DInbLzff.d.cts +9 -0
  90. package/dist/targets-DInbLzff.d.ts +9 -0
  91. package/dist/terminal/dom/index.cjs +8 -3
  92. package/dist/terminal/dom/index.cjs.map +1 -1
  93. package/dist/terminal/dom/index.d.cts +3 -0
  94. package/dist/terminal/dom/index.d.ts +3 -0
  95. package/dist/terminal/dom/index.js +8 -3
  96. package/dist/terminal/dom/index.js.map +1 -1
  97. package/dist/terminal/dom/server.cjs +2 -7
  98. package/dist/terminal/dom/server.cjs.map +1 -1
  99. package/dist/terminal/dom/server.d.cts +3 -5
  100. package/dist/terminal/dom/server.d.ts +3 -5
  101. package/dist/terminal/dom/server.js +2 -7
  102. package/dist/terminal/dom/server.js.map +1 -1
  103. package/dist/terminal/index.cjs +22 -300
  104. package/dist/terminal/index.cjs.map +1 -1
  105. package/dist/terminal/index.d.cts +7 -2
  106. package/dist/terminal/index.d.ts +7 -2
  107. package/dist/terminal/index.js +21 -22
  108. package/dist/terminal/index.js.map +1 -1
  109. package/dist/terminal/ink/index.d.ts +3 -2
  110. package/dist/terminal/ink/index.js +149 -106
  111. package/dist/terminal/ink/index.js.map +1 -1
  112. package/dist/terminal/react/index.cjs +21 -71
  113. package/dist/terminal/react/index.cjs.map +1 -1
  114. package/dist/terminal/react/index.d.cts +5 -2
  115. package/dist/terminal/react/index.d.ts +5 -2
  116. package/dist/terminal/react/index.js +17 -20
  117. package/dist/terminal/react/index.js.map +1 -1
  118. package/dist/terminal/react/server.cjs +4 -68
  119. package/dist/terminal/react/server.cjs.map +1 -1
  120. package/dist/terminal/react/server.d.cts +9 -6
  121. package/dist/terminal/react/server.d.ts +9 -6
  122. package/dist/terminal/react/server.js +3 -18
  123. package/dist/terminal/react/server.js.map +1 -1
  124. package/dist/terminal/tty/index.cjs +147 -130
  125. package/dist/terminal/tty/index.cjs.map +1 -1
  126. package/dist/terminal/tty/index.d.cts +4 -2
  127. package/dist/terminal/tty/index.d.ts +4 -2
  128. package/dist/terminal/tty/index.js +147 -130
  129. package/dist/terminal/tty/index.js.map +1 -1
  130. package/dist/terminal/vue/index.cjs +20 -72
  131. package/dist/terminal/vue/index.cjs.map +1 -1
  132. package/dist/terminal/vue/index.d.cts +8 -12
  133. package/dist/terminal/vue/index.d.ts +8 -12
  134. package/dist/terminal/vue/index.js +45 -1
  135. package/dist/terminal/vue/index.js.map +1 -1
  136. package/dist/terminal/vue/server.cjs +4 -76
  137. package/dist/terminal/vue/server.cjs.map +1 -1
  138. package/dist/terminal/vue/server.d.cts +7 -6
  139. package/dist/terminal/vue/server.d.ts +7 -6
  140. package/dist/terminal/vue/server.js +3 -10
  141. package/dist/terminal/vue/server.js.map +1 -1
  142. package/dist/tide.cjs +41 -0
  143. package/dist/tide.cjs.map +1 -0
  144. package/dist/tide.d.cts +25 -0
  145. package/dist/tide.d.ts +25 -0
  146. package/dist/tide.js +39 -0
  147. package/dist/tide.js.map +1 -0
  148. package/dist/unverified.cjs +12 -0
  149. package/dist/unverified.cjs.map +1 -0
  150. package/dist/unverified.d.cts +7 -0
  151. package/dist/unverified.d.ts +7 -0
  152. package/dist/unverified.js +10 -0
  153. package/dist/unverified.js.map +1 -0
  154. package/dist/vite.cjs +96 -232
  155. package/dist/vite.cjs.map +1 -1
  156. package/dist/vite.d.cts +6 -8
  157. package/dist/vite.d.ts +6 -8
  158. package/dist/vite.js +97 -71
  159. package/dist/vite.js.map +1 -1
  160. package/package.json +51 -8
  161. package/dist/chunk-4T6KAXBP.js +0 -256
  162. package/dist/chunk-4T6KAXBP.js.map +0 -1
  163. package/dist/chunk-EMRDIZLY.js +0 -99
  164. package/dist/chunk-EMRDIZLY.js.map +0 -1
  165. package/dist/chunk-HOZID4EM.js +0 -366
  166. package/dist/chunk-HOZID4EM.js.map +0 -1
  167. package/dist/chunk-R3QMJ3JF.js +0 -3404
  168. package/dist/chunk-R3QMJ3JF.js.map +0 -1
  169. package/dist/chunk-SK4PDGEE.js +0 -55
  170. package/dist/chunk-SK4PDGEE.js.map +0 -1
  171. package/dist/chunk-U3UR5AOQ.js.map +0 -1
  172. package/dist/document-DhWxieUc.d.cts +0 -1024
  173. package/dist/document-DhWxieUc.d.ts +0 -1024
  174. package/dist/slots-Do9ScG7v.d.cts +0 -37
  175. 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 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.
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 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.
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 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.
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 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. The closure audit's findings are not
111
- errors: they are filed under each role's `issues` in the report, and boot
112
- neither refuses on them nor prints them. If it boots, the charter and the
113
- variants are coherent; a push to an ungranted action can still be in it.
114
-
115
- The test of the principle: moss adds no new vocabulary. Reads are vex, writes are
116
- vex, compute is functions, UI is actions, permissions are the charter. The server
117
- is the composition, not a fifth language.
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 `idleMs` (default 30 minutes) and it is
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 mounted on each
353
- canvas. `shells.reset(principal)` disposes one and stands its replacement in
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/follow.ts`). Toward vex it is a `VexLive` — a
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
- (`documentHeaders`), keyed on whether a principal resolved. No page, route or
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 (`shellNeedOf`) and puts it on the snapshot as `live`. A page that
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, the caller's compiled scope policy, the environment, and
548
- `grant`/`revoke`. Agents live here (their reads run under the caller's policy —
549
- they see what the caller sees); keys are `.env`. This is deliberately the *side-
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
- subscribes once and splits the news two ways — and the split is a privilege
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.** A fact is stamped
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 interval that used to stand in for this was both a latency
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. The server consumes a session token, never mints one; magic link is the default strategy. |
622
- | A framework | An assembly point. The intelligence lives in the artifacts; the server resolves, serves, pushes, enforces. Component count stays single-digit. |
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, no head management: the template, the route and the kit are the app's. |
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`), and an optional fabric
648
- (`runtime.fabric`, `src/fabric.ts`) carries identity invalidations and nudges.
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