@niscorp/moss 0.9.3 → 0.10.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 (108) hide show
  1. package/CHANGELOG.md +110 -0
  2. package/DESIGN.md +58 -55
  3. package/DOCS.md +259 -168
  4. package/README.md +5 -5
  5. package/dist/{chunk-PVZMCEBX.cjs → chunk-3CKBKTXA.cjs} +2 -2
  6. package/dist/chunk-3CKBKTXA.cjs.map +1 -0
  7. package/dist/{chunk-TAAKHW3U.js → chunk-3PL4AH4I.js} +4 -4
  8. package/dist/{chunk-TAAKHW3U.js.map → chunk-3PL4AH4I.js.map} +1 -1
  9. package/dist/{chunk-QAHDSRPK.js → chunk-4URQHVYG.js} +2 -2
  10. package/dist/chunk-4URQHVYG.js.map +1 -0
  11. package/dist/{chunk-U43CBKKE.cjs → chunk-6ACVHHFK.cjs} +32 -30
  12. package/dist/chunk-6ACVHHFK.cjs.map +1 -0
  13. package/dist/{chunk-IUJ2TRNB.cjs → chunk-7MOEKAVC.cjs} +6 -6
  14. package/dist/{chunk-IUJ2TRNB.cjs.map → chunk-7MOEKAVC.cjs.map} +1 -1
  15. package/dist/{chunk-NCQBGK3E.cjs → chunk-BFA76AKR.cjs} +4 -4
  16. package/dist/chunk-BFA76AKR.cjs.map +1 -0
  17. package/dist/{chunk-T5BRTFKP.js → chunk-DSVRFAGX.js} +3 -3
  18. package/dist/{chunk-T5BRTFKP.js.map → chunk-DSVRFAGX.js.map} +1 -1
  19. package/dist/{chunk-IW3A2YIC.js → chunk-EYWD733E.js} +3 -3
  20. package/dist/{chunk-IW3A2YIC.js.map → chunk-EYWD733E.js.map} +1 -1
  21. package/dist/{chunk-IY5BOFLK.cjs → chunk-G4P3XEVM.cjs} +19 -19
  22. package/dist/chunk-G4P3XEVM.cjs.map +1 -0
  23. package/dist/{chunk-6QPTMKRE.cjs → chunk-HUP7CZ7X.cjs} +6 -6
  24. package/dist/{chunk-6QPTMKRE.cjs.map → chunk-HUP7CZ7X.cjs.map} +1 -1
  25. package/dist/{chunk-VKQPOZDJ.cjs → chunk-LTS4AM6T.cjs} +4 -4
  26. package/dist/chunk-LTS4AM6T.cjs.map +1 -0
  27. package/dist/{chunk-UTFOMFCH.js → chunk-MEHCZECW.js} +5 -5
  28. package/dist/chunk-MEHCZECW.js.map +1 -0
  29. package/dist/{chunk-6MZPY4X6.js → chunk-MYPK5YZR.js} +249 -199
  30. package/dist/chunk-MYPK5YZR.js.map +1 -0
  31. package/dist/{chunk-TKXYPO2Y.js → chunk-NUX5MH4I.js} +4 -4
  32. package/dist/chunk-NUX5MH4I.js.map +1 -0
  33. package/dist/{chunk-EXMOO7ZR.cjs → chunk-UVY5ZPWW.cjs} +326 -276
  34. package/dist/chunk-UVY5ZPWW.cjs.map +1 -0
  35. package/dist/{chunk-MVG333UF.js → chunk-VYYDLGQ2.js} +27 -25
  36. package/dist/chunk-VYYDLGQ2.js.map +1 -0
  37. package/dist/{chunk-NRZ3Z2FF.js → chunk-WKZWSWOJ.js} +4 -4
  38. package/dist/chunk-WKZWSWOJ.js.map +1 -0
  39. package/dist/{chunk-YGZS5B2U.cjs → chunk-XH6TSWG4.cjs} +7 -7
  40. package/dist/{chunk-YGZS5B2U.cjs.map → chunk-XH6TSWG4.cjs.map} +1 -1
  41. package/dist/client.cjs +5 -5
  42. package/dist/client.js +2 -2
  43. package/dist/{document-CuF4JqzJ.d.cts → document-DvhT_HaJ.d.cts} +1 -1
  44. package/dist/{document-BzXQvEc1.d.ts → document-iKaRinZE.d.ts} +1 -1
  45. package/dist/{index-CSEo7Tys.d.cts → index-DWj3_0Zg.d.cts} +3 -0
  46. package/dist/{index-CSEo7Tys.d.ts → index-DWj3_0Zg.d.ts} +3 -0
  47. package/dist/index.cjs +16 -16
  48. package/dist/index.d.cts +4 -4
  49. package/dist/index.d.ts +4 -4
  50. package/dist/index.js +4 -4
  51. package/dist/integrations.cjs +27 -18
  52. package/dist/integrations.cjs.map +1 -1
  53. package/dist/integrations.d.cts +1 -1
  54. package/dist/integrations.d.ts +1 -1
  55. package/dist/integrations.js +25 -16
  56. package/dist/integrations.js.map +1 -1
  57. package/dist/node.cjs +9 -9
  58. package/dist/node.d.cts +2 -2
  59. package/dist/node.d.ts +2 -2
  60. package/dist/node.js +5 -5
  61. package/dist/protocol.cjs +5 -5
  62. package/dist/protocol.js +1 -1
  63. package/dist/terminal/dom/index.cjs +3 -3
  64. package/dist/terminal/dom/index.js +1 -1
  65. package/dist/terminal/dom/server.cjs +2 -2
  66. package/dist/terminal/dom/server.js +1 -1
  67. package/dist/terminal/index.cjs +3 -3
  68. package/dist/terminal/index.js +2 -2
  69. package/dist/terminal/ink/index.js.map +1 -1
  70. package/dist/terminal/react/index.cjs +9 -9
  71. package/dist/terminal/react/index.cjs.map +1 -1
  72. package/dist/terminal/react/index.js +4 -4
  73. package/dist/terminal/react/index.js.map +1 -1
  74. package/dist/terminal/react/server.cjs +4 -4
  75. package/dist/terminal/react/server.js +2 -2
  76. package/dist/terminal/tty/index.cjs +12 -12
  77. package/dist/terminal/tty/index.cjs.map +1 -1
  78. package/dist/terminal/tty/index.js +6 -6
  79. package/dist/terminal/tty/index.js.map +1 -1
  80. package/dist/terminal/vue/index.cjs +9 -9
  81. package/dist/terminal/vue/index.cjs.map +1 -1
  82. package/dist/terminal/vue/index.js +4 -4
  83. package/dist/terminal/vue/index.js.map +1 -1
  84. package/dist/terminal/vue/server.cjs +4 -4
  85. package/dist/terminal/vue/server.js +2 -2
  86. package/dist/tide.d.cts +1 -1
  87. package/dist/tide.d.ts +1 -1
  88. package/dist/unverified.cjs +4 -4
  89. package/dist/unverified.js +3 -3
  90. package/dist/vite.cjs +36 -10
  91. package/dist/vite.cjs.map +1 -1
  92. package/dist/vite.d.cts +2 -2
  93. package/dist/vite.d.ts +2 -2
  94. package/dist/vite.js +31 -5
  95. package/dist/vite.js.map +1 -1
  96. package/package.json +13 -13
  97. package/dist/chunk-6MZPY4X6.js.map +0 -1
  98. package/dist/chunk-EXMOO7ZR.cjs.map +0 -1
  99. package/dist/chunk-IY5BOFLK.cjs.map +0 -1
  100. package/dist/chunk-MVG333UF.js.map +0 -1
  101. package/dist/chunk-NCQBGK3E.cjs.map +0 -1
  102. package/dist/chunk-NRZ3Z2FF.js.map +0 -1
  103. package/dist/chunk-PVZMCEBX.cjs.map +0 -1
  104. package/dist/chunk-QAHDSRPK.js.map +0 -1
  105. package/dist/chunk-TKXYPO2Y.js.map +0 -1
  106. package/dist/chunk-U43CBKKE.cjs.map +0 -1
  107. package/dist/chunk-UTFOMFCH.js.map +0 -1
  108. package/dist/chunk-VKQPOZDJ.cjs.map +0 -1
package/DOCS.md CHANGED
@@ -88,10 +88,10 @@ reaction's `run` — and `features`. Absent `shell`, the app serves data only
88
88
  an org). Moss always injects `{ userId }` (the principal; `'anonymous'` for
89
89
  nobody signed in); this contributes the rest, merged
90
90
  server-side and asked per request, so a value derived from the clock is
91
- never held for a session. Synchronous. `identity` is the record
91
+ never kept for a session. Synchronous. `identity` is the record
92
92
  `identity.resolve` answered: absent for nobody signed in, and in an app with
93
93
  no `identity` seam. What `scope` answers is merged over that record's
94
- `scope`, the values that are held for the session.
94
+ `scope`, the values that are kept for the session.
95
95
  - `identity.resolve(principal, read)` — who a principal is, resolved once per
96
96
  session and cached by moss (bounded by `runtime.identityMax` /
97
97
  `identityIdleMs`, re-resolved every `sessionRevalidateMs`). Returns an
@@ -113,7 +113,7 @@ reaction's `run` — and `features`. Absent `shell`, the app serves data only
113
113
  twice.` A map of handlers by id still works and is deprecated.
114
114
  **`server.checkFunctions()`** builds nobody's shell once, drops it, and reads
115
115
  what its `functions(session)` returned, so what is wrong with the functions
116
- is refused or said before anyone is served. The app calls it once it holds
116
+ is refused or said before anyone is served. The app calls it once it has
117
117
  the server, as a session hook may reach for the server, after it has
118
118
  mounted every route of its own, and before it listens. Nobody's shell
119
119
  makes its reads in-process, and the server takes no route once it has
@@ -125,22 +125,22 @@ reaction's `run` — and `features`. Absent `shell`, the app serves data only
125
125
  returned a map of handlers, which is deprecated: return a list of { id,
126
126
  description, execute }.`, or `[moss] functions with no description:
127
127
  auth.leave. Give each a description.` An empty description counts as none,
128
- and a function given by a map has none. **A shell holds only the functions
128
+ and a function given by a map has none. **A shell has only the functions
129
129
  its principal's roles grant**, in the charter's `functions` part (names or
130
130
  globs, with `extends` and `deny`, as `actions`): a role with none may call
131
131
  none, and an `fn:` endpoint to one it does not grant fails when it is called.
132
- What a living shell holds follows the roles an adopt answers, as its actions
132
+ What a living shell has follows the roles an adopt answers, as its actions
133
133
  do.
134
- - **The boot is refused** where somebody holds an action that calls a
134
+ - **The boot is refused** where somebody is granted an action that calls a
135
135
  function their roles do not grant, and **`server.checkFunctions()` refuses**
136
136
  where an action, or a fragment the shells ship, calls a function the app
137
137
  does not have (`"home" calls "auth.leave", which the app has no function
138
138
  of`); an app with no `functions` has none. It reads the `fn:` endpoints of
139
- the actions held by each role on its own, each combination `wearable` or
139
+ the actions granted to each role on its own, each combination `wearable` or
140
140
  `assignments` lists, and `public`, and of the fragments the shells ship,
141
141
  and lists every call that is missing: `"member" hold "chrome.topbar",
142
142
  which calls "auth.leave": their functions do not grant it`. A set handed
143
- over while the app runs is held to the same. A name with a template in it
143
+ over while the app runs is checked the same way. A name with a template in it
144
144
  (`fn: '{{$.saveFn}}'`) is worked out when it is called, and the shell's map
145
145
  decides then.
146
146
  - **`functions: ['*']`** grants every function, as an app had before this
@@ -182,7 +182,7 @@ reaction's `run` — and `features`. Absent `shell`, the app serves data only
182
182
  `reconcile` step aims at it (nova's SHELL_DOCS.md, "A canvas that names its
183
183
  own reconciler"): handed each row as written, it decides what is kept,
184
184
  matched, moved and removed — several cards of one action on one list canvas,
185
- matched by a key and kept in the list's order. Every shell moss builds holds
185
+ matched by a key and kept in the list's order. Every shell moss builds has
186
186
  them, the app's and each page's, the one a document is drawn from and the
187
187
  socket's: from one seed, a reconciler that answers the same rows the same
188
188
  way places the same instances in both. A reconciler
@@ -217,7 +217,7 @@ charter's `layouts` section selects who is granted which variant id, and moss
217
217
  puts the granted variant's layout where that action's layout is kept in the
218
218
  shell ("Where an action's layout is kept", under `createServer`). The base is
219
219
  the floor; variants enrich upward as grants. A role, or a combination
220
- of roles somebody may wear, that holds two variants of one action refuses the
220
+ of roles somebody may wear, that is granted two variants of one action refuses the
221
221
  boot, and so does a variant of an action the app does not have.
222
222
 
223
223
  #### `ShellManifest`
@@ -246,15 +246,15 @@ they generated.
246
246
  A `CanvasSeed` is an action id or `{ action, input?, with? }`, and a
247
247
  `ShellCanvas` is nova's canvas config with `initial` widened to one seed or a
248
248
  list of candidates. Neither type is exported by name: `ShellManifest['canvases']`
249
- carries both. Of a list of candidates, the first action the principal holds
250
- mounts; a canvas none of whose candidates they hold starts empty. A canvas's
249
+ carries both. Of a list of candidates, the first action the principal is granted
250
+ mounts; a canvas none of whose candidates they are granted starts empty. A canvas's
251
251
  `reconcile` names one of the app's `reconcilers`.
252
252
 
253
253
  `components` is the kit as the server knows it: each component's name, with
254
254
  its `meta` (a `description`, and `propsSchema`, the zod schema of its props).
255
255
  A name listed there is registered in the shell whether or not a layout of the
256
256
  app uses it. The `components` of the app's own `shell` are also the kit a
257
- bundle's layouts are held to at intake, and the one the integrations'
257
+ bundle's layouts are checked against at intake, and the one the integrations'
258
258
  contract lists ([`@niscorp/moss/integrations`](#niscorpmossintegrations)): a
259
259
  bundle's layout that uses a component not listed there is refused, and where
260
260
  a component's `propsSchema` is a zod object, so is a prop it has no place for.
@@ -363,7 +363,7 @@ throw, and so do `set` and `delete` on its `layoutStore`, which is to read. A
363
363
  definition read off it (`shell.getRuntime(id).definition`) is the action as it
364
364
  was written, with the layout it is drawn with now in place: where moss keeps a
365
365
  layout does not show. An action, a fragment, a canvas, a layout and the phrases reach a shell
366
- through moss, which verifies them and decides who holds them; added on the
366
+ through moss, which verifies them and decides who is granted them; added on the
367
367
  shell directly they are not verified, are in nobody's catalog and are gone
368
368
  when the shell is rebuilt. Everything else (reads, navigation, `dispatch`,
369
369
  `publish`, the observers) works as on nova's `Shell`, which is still the
@@ -379,9 +379,9 @@ import type { ActionDefinition } from '@niscorp/nova';
379
379
  const register = (session: FunctionSession, definition: ActionDefinition): void => unverifiedShell(session).registerAction(definition);
380
380
  ```
381
381
 
382
- **A session says who is calling and holds no key.** It carries no `runtime`
382
+ **A session says who is calling and has no key.** It carries no `runtime`
383
383
  (the database pool, the operator key) and no `policy` (the
384
- object the routes enforce for everybody holding those roles). What app code
384
+ object the routes enforce for everybody wearing those roles). What app code
385
385
  needs of either has a call:
386
386
 
387
387
  - **A read or a write as the caller**: `session.wire`, the routes, enforced.
@@ -391,7 +391,8 @@ needs of either has a call:
391
391
  intent and the shape. The query is written, compiled and run under the
392
392
  policy and the scope values the routes serve this principal under, resolved
393
393
  when it is asked: the writer is shown only the tables they may read, and a
394
- query that reaches past their policy is refused. It is kept in the cache the
394
+ query that reaches past their policy is refused. A replay of an entry that
395
+ declares a `reach` is served at that reach, as the routes serve it. It is kept in the cache the
395
396
  routes replay from, so `answer.meta.cache.fingerprint` replays over
396
397
  `session.wire` afterwards, for whoever the policy lets. Moss keeps one
397
398
  engine for each `writers` object: hand over the same object each time. It
@@ -493,8 +494,18 @@ functions: (session) => [
493
494
  theirs whose newest version was neither saved nor used within that time is
494
495
  deleted, every version of it, by a sweep that runs as the server comes up and
495
496
  then every hour. What is published for everybody never ages, and what the
496
- build ships is not a row. Without the setting nothing is deleted. A limit of
497
- `0` or less refuses the boot.
497
+ build ships is not a row. Without the setting nothing is deleted. A limit
498
+ that is not a whole number of milliseconds, or is under two hours
499
+ (7,200,000 ms), refuses the boot.
500
+
501
+ **Time the app is down counts as unused.** After a downtime longer than
502
+ `artifactsUnusedMs`, the sweep as the server comes up deletes everything of
503
+ everybody's that was not used since. With `runtime.artifactsUnusedSinceStart:
504
+ true` the time is counted only since this server started: the sweep deletes
505
+ nothing until the server has been up for `artifactsUnusedMs`, so what was
506
+ last used before the start is unused from the start on. Running time before
507
+ the start does not count either, and a server restarted more often than
508
+ `artifactsUnusedMs` deletes nothing.
498
509
  - **It reaches its owner's open shells a moment after the save answers**, as a
499
510
  saved layout does, and not before: a function that saves an action and
500
511
  opens it in the same call finds it not there yet. One that is to be seen at
@@ -519,20 +530,20 @@ functions: (session) => [
519
530
  endpoints, and where both define an endpoint of one name the action's is
520
531
  the one called. What an assistant is told it may generate is the app's to
521
532
  decide: it writes the prompt, and its own function calls `save`.
522
- - **A generated action opens the actions its owner holds**, their own
533
+ - **A generated action opens the actions its owner is granted**, their own
523
534
  generated ones among them, and no other: nova's audit is run on it with
524
535
  those as its catalog, and what it finds refuses the save, as it does for a
525
536
  saved layout. So do a component no shell of the app has, and a layout that
526
- names a ref moss keeps a layout under (`action/…`, `canvas/…`, `frame`). A fragment is held to its schema, its id, its
527
- layout and its endpoints, and not to that audit, which reads a whole action:
528
- a step of a fragment that opens an action its owner does not hold is refused
537
+ names a ref moss keeps a layout under (`action/…`, `canvas/…`, `frame`). A fragment is checked against its schema, its id, its
538
+ layout and its endpoints, and not against that audit, which reads a whole action:
539
+ a step of a fragment that opens an action its owner is not granted is refused
529
540
  by nova when it runs, because that action is not in their shell.
530
541
  - **It is checked when it is saved and again when a shell is built.** One
531
542
  that no longer passes (its owner lost the grant its read needs, say) is left
532
543
  out of every shell built from then on, with a line (`[moss] the action "…"
533
544
  of … is left out: …`).
534
545
  - **A reset takes it out of its owner's shells**, and the layouts they saved
535
- for it are not drawn while it is out: a layout whose action its holder has
546
+ for it are not drawn while it is out: a layout whose action its owner has
536
547
  no longer is not loaded. `list('layout')` still lists them. Going back to a
537
548
  version of the action brings both back.
538
549
  - **No action an app ships or hands over, and no fragment of a shell, has an
@@ -552,7 +563,7 @@ whose `principal` is their `userId`, and a row they insert or update carries
552
563
  it, whatever the statement says. Vex keeps that rule on every read and every
553
564
  write; moss's code passes no principal. **Who may save at all is the charter's**: a function that calls
554
565
  `session.artifacts.save` is the app's, an action calls it, and the charter
555
- says who holds that action. A session nobody is signed in to saves nothing
566
+ says who is granted that action. A session nobody is signed in to saves nothing
556
567
  and lists nothing: everybody who is not signed in shares one `userId`.
557
568
 
558
569
  - The layout is the principal's and nobody else's. Moss gives it its id, a
@@ -574,16 +585,17 @@ or write a row of another account.
574
585
 
575
586
  **A read vex wrote** for a request (`session.answerIntent`) is saved under
576
587
  the fingerprint vex gave it, with no body:
577
- `session.artifacts.save([{ kind: 'read', id: 'fp_…' }])`. Moss takes the entry
578
- from vex's own table and keeps it as written: the query, the Prism config of
579
- its mapping, its shape and its intent.
588
+ `session.artifacts.save([{ kind: 'read', id: 'fp_…', body: undefined }])`.
589
+ Moss takes the entry from vex's own table and keeps it as written: the query,
590
+ the Prism config of its mapping, its shape and its intent, so a read that
591
+ comes with a body is refused.
580
592
 
581
593
  - **It is answered to the person who saved it and to nobody else.** When one
582
594
  of their requests replays that fingerprint, moss answers it, compiled, from
583
595
  their rows. Anybody else who sends the fingerprint gets what vex's own table
584
- still holds under it, as for any query vex wrote and nobody saved, and a
596
+ still has under it, as for any query vex wrote and nobody saved, and a
585
597
  caller nobody is signed in for is never answered a saved read.
586
- - **It is a query vex wrote, and is held as one.** Vex's limits apply to it
598
+ - **It is a query vex wrote, and is kept as one.** Vex's limits apply to it
587
599
  (`maxLimit`), as they do not to an entry the app ships. A request that names
588
600
  its fingerprint with an intent and a shape is written anew by vex into its
589
601
  own table; the saved read is what its owner is answered until they save the
@@ -608,12 +620,12 @@ its mapping, its shape and its intent.
608
620
 
609
621
  **What a shell draws under an action's ref**, the first of these that there
610
622
  is: the principal's own layout marked in use; the layout variant their roles
611
- hold (`app.layouts`); the layout published for everybody that is marked in use
623
+ are granted (`app.layouts`); the layout published for everybody that is marked in use
612
624
  (`server.defaults`); the layout the build ships.
613
625
 
614
626
  **What is refused**, at a save and at a restore, in a sentence, with nothing
615
627
  written: a body that is not `{ ref, layout, use? }`; a `ref` nothing is kept
616
- under for the principal (an action they do not hold, or one that is not in
628
+ under for the principal (an action they are not granted, or one that is not in
617
629
  force; an action with no layout of its own, or one that names a layout of the
618
630
  store by its id; any name that is none of `action/<id>`, `frame` and
619
631
  `canvas/<id>`); a component no shell of
@@ -626,8 +638,8 @@ a control the action listens on that the layout leaves out, a control no
626
638
  trigger handles). The same is asked of every saved layout when a shell is
627
639
  built, there against the components of that shell alone: one that does not
628
640
  pass is left out, what is under it is drawn, and a line says why (`[moss] the layout "…" of … is left out: …`). One whose ref
629
- its holder's store keeps nothing under any more (the action left, or they
630
- hold it no longer) is not loaded and nothing is said.
641
+ its owner's store keeps nothing under any more (the action left, or they
642
+ are granted it no longer) is not loaded and nothing is said.
631
643
 
632
644
  **The layouts of the app's own shell** are saved with the same calls: its own
633
645
  under `ref: 'frame'`, and a canvas's under `ref: 'canvas/<the canvas's id>'`.
@@ -659,20 +671,22 @@ true } }])`.
659
671
  gives a shell a canvas when something is first pushed onto it, whether or not
660
672
  its manifest declares it, and it is drawn where a layout has a canvas slot for
661
673
  it (`{ component: 'CanvasSlot', props: { canvasId: 'notes' } }`). Moss reads
662
- which canvases the layouts a shell is built from hold a slot for and its
674
+ which canvases the layouts a shell is built from have a slot for and its
663
675
  manifest does not declare. Every layout counts (the frame, a canvas's, an
664
- action's that the principal holds, a fragment's, one the app keeps in its
676
+ action's that the principal is granted, a fragment's, one the app keeps in its
665
677
  layout store), the build's and a saved or generated one alike. Once a layout
666
- leaves force and no other holds a slot for such a canvas, an open shell loses
678
+ leaves force and no other has a slot for such a canvas, an open shell loses
667
679
  the canvas, with what is mounted on it. A slot whose `canvasId` is worked out
668
680
  when it is drawn (`'$.c.id'`, a template) counts for none. Moss gives a shell
669
681
  no canvas, and the canvases a manifest declares are never taken out. What is
670
682
  pushed onto a canvas after its slot went is mounted and drawn nowhere, as on
671
683
  any canvas no layout has a slot for.
672
684
 
673
- **Moss changes and deletes no row.** `list` answers the latest version of each
685
+ **A save, a restore and a reset each add rows and change none.** The one
686
+ column moss changes is `last_used_at`, and the one delete is the aging sweep's
687
+ ("It ages out when nobody uses it"). `list` answers the latest version of each
674
688
  of the principal's artifacts that has a body. `history` answers the versions
675
- of one, the newest first (the newest 500). `restore` is a new save that holds
689
+ of one, the newest first (the newest 500). `restore` is a new save that contains
676
690
  a copy of a version and says which (`copiedFrom`); it is checked as a save
677
691
  is. `reset` is a new save whose version has no body: none of the principal's
678
692
  is in force under that id, and what is under it is drawn again. A reset is a
@@ -682,7 +696,7 @@ drawn. The next save that marks one for that ref, or takes the one in use out
682
696
  (a reset, or a save of it without the mark), takes the mark off the rest.
683
697
 
684
698
  The rows are in `artifact_saves` (one for each save) and `artifacts` (one for
685
- each version a save holds), which migration `nisc.moss/5` makes. They are
699
+ each version a save contains), which migration `nisc.moss/5` makes. They are
686
700
  read and written through three vex entries of moss's own that no route serves
687
701
  (`src/artifactory/saves.ts`). What is in force for an artifact is its latest
688
702
  version by `created_at`; every id moss gives is a uuid. A body is kept with
@@ -763,9 +777,9 @@ functions: (session) => [
763
777
  refuses**, with the same sentences. Each artifact is checked beside what is
764
778
  in force for the principal with the draft laid over, so a layout may be for
765
779
  an action that is itself in the draft. A draft is one shell's, so what is
766
- added to it is held to the components of that shell, where a save is held to
767
- those of any shell of the app. A new action or fragment gets its
768
- `generated.` id here, and keeps it when the draft is saved. An `id` names
780
+ added to it is checked against the components of that shell, where a save
781
+ is checked against those of any shell of the app. A new action or fragment
782
+ gets its `generated.` id here, and keeps it when the draft is saved. An `id` names
769
783
  one in the draft, or one the principal saved: a new take of it, which stands
770
784
  in for the saved one in this shell until the draft is saved or the take is
771
785
  taken out. An add that marks a layout `use: true` takes the mark off the
@@ -777,13 +791,13 @@ functions: (session) => [
777
791
  - **What the shell draws**: what is in the draft, then what `session.artifacts`
778
792
  would draw. A drafted layout marked `use: true` is drawn in place of a saved
779
793
  one that is marked for the same ref.
780
- - **`list`** answers what the draft holds, and **`remove`** takes one out of
794
+ - **`list`** answers what the draft contains, and **`remove`** takes one out of
781
795
  it; what is under it is drawn again. **`discard`** empties it.
782
796
  - **Each add or removal is a numbered step**, from 1. **`show(step)`** has the
783
797
  shell show the draft as it was after that step, and `show(0)` none of it. A
784
798
  add or a removal while an earlier step is shown goes on from that step: the
785
799
  steps after it are dropped. The steps are the draft's and are saved nowhere.
786
- - **`save`** is one save of what the draft holds, as the principal's own and
800
+ - **`save`** is one save of what the draft contains, as the principal's own and
787
801
  under the ids it had, checked once more. The draft is then empty and the
788
802
  shell keeps what it shows. An empty draft is refused.
789
803
  - **Calls on one draft are taken in turn**: each starts from the draft as the
@@ -803,12 +817,15 @@ type NiscRuntime = {
803
817
  db: MutationClient; // writes
804
818
  cache?: CacheBackend; // defaults to vex's postgres cache on `pool`
805
819
  vexConfig?: QueryEngineConfig['config']; // the query engine's settings (limits, read timeout); default vex's own
820
+ answerReadableRows?: boolean; // a write on the vex surfaces answers only the rows the caller may read; default false
821
+ checkMovedRows?: boolean; // refuse a write that moves a row out of the caller's update rule; default true
806
822
  session: SessionVerifier | 'sessions' | 'dev-open'; // REQUIRED — no default
807
823
  origins?: readonly string[]; // origins that are the app's own page, beside the host a request names (a proxy that rewrites `Host`)
808
824
  migrations?: 'apply' | 'verify'; // the boot's ledgered run; default 'verify'
809
825
  tables?: readonly Sequence[]; // the app's own table sequences, in that same run
810
826
  shellIdleMs?: number; // idle shell eviction; default 30 min, `0` disables
811
827
  artifactsUnusedMs?: number; // delete what a person generated once nobody has loaded it for this long; default never
828
+ artifactsUnusedSinceStart?: boolean; // count that time only since this server started; default false: time the app was down counts
812
829
  anonymousShellMax?: number; // shells for nobody signed in alive at once; default 1,000, `Infinity` is no limit
813
830
  endpointTimeoutMs?: number; // a server shell's endpoint call, and the build of a shell; default nova's, 30s
814
831
  sessionRevalidateMs?: number; // live-socket re-verify; default 60s, `0` disables
@@ -830,7 +847,7 @@ the function form of `session`. The type is not exported by name.
830
847
  `socketCompression` and `socketMaxMessageBytes` are settings of the Node
831
848
  transport. The server reads them, once, and the socket it hands out
832
849
  (`server.socket`) carries them to whichever transport is handed it. So they
833
- hold wherever that socket is attached: under `serve`, `nisc start`, the dev
850
+ apply wherever that socket is attached: under `serve`, `nisc start`, the dev
834
851
  plugin (`nisc dev`), and a host of the app's own that calls
835
852
  `attachSocket(httpServer, server.socket)`. No host says them again.
836
853
 
@@ -841,6 +858,19 @@ own reads and writes. The generation counter and a feature's own entries (the
841
858
  integrations' registry) read the tables that are theirs off the database
842
859
  whatever the list names, and know no other table.
843
860
 
861
+ `answerReadableRows` is vex's option of that name on the `/api/vex` surfaces
862
+ (vex DOCS, "Replay"). Without it a write answers every row it wrote, whole,
863
+ whatever the caller's read rules say. With it, a write answers only the rows
864
+ the caller's charter lets them read, and an entry whose role cannot read the
865
+ table it writes answers no row: a sign-in entry that deletes a one-time link
866
+ and reads who signs in from the deleted row stops working.
867
+
868
+ `checkMovedRows` is vex's option of that name, on the `/api/vex` surfaces and
869
+ `executeAs` (vex DOCS, "Replay"). An update that writes a column the caller's
870
+ update rule pins (`owner_id` under an `owner_id = me` rule) to a value the rule
871
+ does not allow is refused with 400 `scope_denied`, and nothing is written.
872
+ `checkMovedRows: false` lets such a write move the row, as moss did before.
873
+
844
874
  `session` is required, deliberately — authentication is the one door that must
845
875
  not default open, and it used to. Three answers: `'sessions'` uses moss's own
846
876
  stored credential (below); `'dev-open'` trusts every well-formed token and says
@@ -861,7 +891,7 @@ asked about again, an identity record older than it is resolved again when it
861
891
  is next read, and the generation pointer is polled
862
892
  ([Many processes](#many-processes)). `0` turns off all three, and so does
863
893
  `Infinity` or any interval above 2^31 − 1 ms (24.8 days), the longest a timer
864
- of Node's holds: a process then follows no `refresh`, `replaceActions` or
894
+ of Node's can wait: a process then follows no `refresh`, `replaceActions` or
865
895
  approval of an integration that another process made.
866
896
 
867
897
  `operatorKey` is what a request under `/operator` presents as
@@ -885,10 +915,10 @@ Somebody signed in is served whatever the count is, and a shell one of the
885
915
  manifest's pages builds for somebody signed in takes no place.
886
916
 
887
917
  **What the limit is, exactly.** One count, for everybody with nobody signed
888
- in, in one process. It bounds what that process holds in memory for them, and
918
+ in, in one process. It bounds what that process keeps in memory for them, and
889
919
  it does nothing else:
890
920
 
891
- - It is not a limit for each visitor. Whoever holds the places holds them:
921
+ - It is not a limit for each visitor. Whoever takes the places keeps them:
892
922
  one client that opens `anonymousShellMax` connections and keeps them open
893
923
  has every place, and every other visitor with nobody signed in is sent
894
924
  `at_capacity` until one of those closes. People who are signed in go on
@@ -902,20 +932,20 @@ it does nothing else:
902
932
  close is like any other: the place is given back, a shell for nobody is
903
933
  disposed, and a signed-in person's shell starts its idle time.
904
934
  - It is counted by the process that takes the connection. A deployment of N
905
- processes holds up to N times the limit.
935
+ processes allows up to N times the limit.
906
936
  - Moss builds no limit for each address, because the address is not moss's
907
937
  to know: behind a proxy every connection comes from the proxy, and which
908
938
  header says where the visitor is, is the proxy's to say.
909
939
 
910
940
  **A deployment that faces the internet** limits how many connections one
911
- address may hold where the address is known: at its proxy or load balancer,
941
+ address may keep open where the address is known: at its proxy or load balancer,
912
942
  on the socket's path (`/socket`). With that in place, `anonymousShellMax` is
913
943
  what it is sized for here, memory. What an app can do on its own: a first
914
944
  screen for nobody that is a page which is not live opens no socket and takes
915
945
  no place (`nisc build` says which pages are live, and why).
916
946
 
917
947
  The default is from a measurement (2026-10-10, Node 24): lyceum's real boot,
918
- 2,000 connections for nobody opened through `server.socket` and held, the heap
948
+ 2,000 connections for nobody opened through `server.socket` and kept open, the heap
919
949
  read after a forced collection before and after, with a transport that drops
920
950
  what it is sent.
921
951
 
@@ -943,7 +973,7 @@ the row.
943
973
  its own identity check and hands the token to the terminal (or sets it as
944
974
  the browser's cookie, [`sessionCookies`](#sessioncookiespage-token-options)).
945
975
  Expired rows are swept on every mint — no timer to run.
946
- - `revokeAllFor` deletes every token a principal holds: signed out everywhere.
976
+ - `revokeAllFor` deletes every token a principal has: signed out everywhere.
947
977
  `session.revoke()` in a function calls it for the session's own principal;
948
978
  this is for signing out somebody else (an owner removes a member).
949
979
  No exported call deletes one token and leaves the principal's others.
@@ -963,10 +993,10 @@ the row.
963
993
  in a function closes that principal's terminals and disposes their shell,
964
994
  and forgets nothing: the app deletes its own credential where it signs
965
995
  somebody out. An app that wants moss's stored sessions and a rule of its
966
- own on top (a member who was removed, an account on hold) sets
996
+ own on top (a member who was removed, a suspended account) sets
967
997
  `session: 'sessions'` and puts the rule where it belongs: `revokeAllFor`
968
998
  when the member is removed, or `identity.resolve` answering
969
- `{ roles: ['public'], scope: {} }` for somebody who may hold nothing.
999
+ `{ roles: ['public'], scope: {} }` for somebody who may be granted nothing.
970
1000
 
971
1001
  ```typescript
972
1002
  // the app's own door: who they are is the app's to establish, then a session
@@ -1022,7 +1052,7 @@ reason as `fingerprint: why` — and nothing was applied. It asks on every run,
1022
1052
  so a release that changes an entry and no table is checked too.
1023
1053
 
1024
1054
  One kind of entry is said and not refused: one that already did not fit before
1025
- the run and that the cache table already holds a copy of, exactly as it is. That
1055
+ the run and that the cache table already has a copy of, exactly as it is. That
1026
1056
  is an old fault, not this run's. A new or changed entry gets no such pass. A
1027
1057
  copy is there where a release before 0.6.0 wrote it, or where the app writes
1028
1058
  one itself for an engine of its own (`seedCache`). Moss writes none since
@@ -1107,7 +1137,7 @@ order: the manifest is read and frozen; who a token is is resolved
1107
1137
  the tables are checked (migrated under `migrations: 'apply'`) and the data
1108
1138
  module stands; the running manifest is
1109
1139
  created, which is the boot check, and the data module is told to ask it for an
1110
- entry (it compiles the ones it holds, and one vex cannot run refuses the boot);
1140
+ entry (it compiles the ones it keeps, and one vex cannot run refuses the boot);
1111
1141
  identity; the server's own routes (the
1112
1142
  authentication, `/catalog`, vex); the shell hosts, the app's and each page's;
1113
1143
  what crosses processes; the features, each started with seams made for it; the
@@ -1115,22 +1145,22 @@ operator prefix; the app's reactions hear a write; the generation pointer is
1115
1145
  watched; the socket.
1116
1146
  A step that refuses is the boot's refusal.
1117
1147
 
1118
- **Where the app's entries are held.** In the running manifest
1119
- (`src/artifactory/`), in memory, and nowhere else. It holds the entries the
1148
+ **Where the app's entries are kept.** In the running manifest
1149
+ (`src/artifactory/`), in memory, and nowhere else. It keeps the entries the
1120
1150
  app shipped and each set handed over with `server.replaceEntries`, compiled as
1121
1151
  vex replays them, and it is what the engine asks first: a request's
1122
1152
  fingerprint, and the list of fingerprints a feature or the operator is told
1123
1153
  of, resolve there. So what a fingerprint resolves to is what this process's
1124
1154
  app ships, read from the build at every boot.
1125
1155
 
1126
- What the running manifest does not hold is asked of the cache table
1156
+ What the running manifest does not have is asked of the cache table
1127
1157
  (`vex_cache`, or the cache `runtime.cache` hands over). That table keeps what
1128
1158
  vex wrote itself while the app runs: a query `session.answerIntent` wrote.
1129
1159
  **Nothing is copied into it at boot, and a row in it that no request wrote is
1130
1160
  not replayed.** Vex gives a query it writes the hash of the request it was
1131
1161
  written for, and that is what moss asks of a row before it answers from it. A
1132
1162
  release before 0.6.0 copied every entry of the app there at each boot, and a
1133
- database that ran one still holds those rows, which carry no such hash. Moss
1163
+ database that ran one still has those rows, which carry no such hash. Moss
1134
1164
  answers from none of them and deletes none: an entry the app no longer ships
1135
1165
  is refused (`cache_miss`). Two things an app may have leaned on are gone with
1136
1166
  the copy:
@@ -1146,7 +1176,7 @@ the copy:
1146
1176
  `action/<id>`. An app goes on writing an action's layout in its definition;
1147
1177
  where a shell is built, moss moves it into the store, and the definition the
1148
1178
  shell is handed names it by `{ ref: 'action/<id>' }`. A layout variant the
1149
- person's roles hold is what the store holds under that name instead. An action
1179
+ person's roles are granted is what the store keeps under that name instead. An action
1150
1180
  with no layout, or one whose `layout` is already the name of a stored layout,
1151
1181
  is handed over as it is. Three things follow:
1152
1182
 
@@ -1157,7 +1187,7 @@ is handed over as it is. Three things follow:
1157
1187
  endpoints and its triggers.
1158
1188
  - **Code that reads an action's definition off its session's shell**
1159
1189
  (`session.shell.getRuntime(id).definition`) finds it as it was written, with
1160
- the layout in place: the one the store holds now, so a variant or a change
1190
+ the layout in place: the one the store keeps now, so a variant or a change
1161
1191
  shows. `server.actions()` answers the definitions as they were written too.
1162
1192
  Only the whole shell (`unverifiedShell(session)`), which is nova's own,
1163
1193
  shows `{ ref }`; there the layout is `shell.layoutStore.get('action/<id>')`.
@@ -1203,11 +1233,11 @@ The manifest does not parse — refusing to serve:
1203
1233
  Each line is a place and what was expected there. An action, a fragment and a
1204
1234
  layout (a layout variant's, a canvas's, the frame's, the layout store's) are
1205
1235
  read by nova's schemas; an entry's `dsl` and `mutation` by vex's and its
1206
- `mapping` by Prism's; `grammars` by strata's. Every other data field is held to
1236
+ `mapping` by Prism's; `grammars` by strata's. Every other data field is checked against
1207
1237
  the shape `NiscApp` gives it, and a field `NiscApp` does not have is refused.
1208
- A code seam is held to being a function. A component's contract
1238
+ A code seam is checked to be a function. A component's contract
1209
1239
  (`shell.components`) is the kit's own record and may carry more than moss
1210
- names. The charter and `behaviors` are held to being objects; the charter is
1240
+ names. The charter and `behaviors` are checked to be objects; the charter is
1211
1241
  verified by the check below and `behaviors` by vex when a policy is compiled.
1212
1242
 
1213
1243
  **Then it is frozen**, every level of it, in place. Once `createServer` has
@@ -1241,7 +1271,8 @@ feature serves).
1241
1271
 
1242
1272
  The socket is not a Hono route: `server.socket` is fed by the runtime's
1243
1273
  transport (`/socket` under `serve` and `attachSocket`). Every request is
1244
- identified once, from `Authorization: Bearer <token>`: a session token goes
1274
+ identified once, from `Authorization: Bearer <token>` (the scheme in any
1275
+ case; a header with no scheme is read whole as the token): a session token goes
1245
1276
  through the `session` verifier (`401` when it does not resolve); a token
1246
1277
  whose prefix a feature registered is that feature's to read (the integrations
1247
1278
  read `ik_`, an integration key); no header is the anonymous principal. There
@@ -1281,7 +1312,7 @@ It's a Hono app — mount it, extend it, or hand it to a listener.
1281
1312
  where it cannot see (a role, an install): run the check boot runs over what
1282
1313
  is in force (the charter, every entry's reach, the layout variants), drop
1283
1314
  every per-principal memo and identity record, and have every living shell
1284
- adopt: it is brought level with what its principal holds now, in place
1315
+ adopt: it is brought level with what its principal is granted now, in place
1285
1316
  ("A change is the server's", under `shells` below). Every living shell is
1286
1317
  the one kept for each signed-in person, the one built for each connection
1287
1318
  of nobody signed in, and the one a page built for each connection. It also
@@ -1322,7 +1353,7 @@ It's a Hono app — mount it, extend it, or hand it to a listener.
1322
1353
  is refused from then on, and a name a feature keeps is not the app's. The
1323
1354
  entries in force are what the app shipped, then each set: an entry of a set
1324
1355
  is replayed in place of one the app shipped under the same fingerprint, for
1325
- as long as the set holds it. Every entry is read by the schema the
1356
+ as long as the set contains it. Every entry is read by the schema the
1326
1357
  manifest's entries are read by, compiled, and checked before the set is
1327
1358
  taken: a write by vex's authoring lint, and the reach an entry declares by
1328
1359
  the check boot runs. Refused, the promise rejects with what was found
@@ -1344,14 +1375,14 @@ It's a Hono app — mount it, extend it, or hand it to a listener.
1344
1375
  shows the build's again. **A layout:** `server.defaults(who).save([{ kind:
1345
1376
  'layout', body: { ref: 'action/<id>', layout, use: true } }])` is drawn under
1346
1377
  that action's ref unless its principal has a layout of their own in use or
1347
- their roles hold a layout variant; `ref: 'frame'` and `ref: 'canvas/<id>'`
1378
+ their roles are granted a layout variant; `ref: 'frame'` and `ref: 'canvas/<id>'`
1348
1379
  publish the layouts of the app's own shell. **An action or a fragment** is
1349
1380
  given its id by whoever publishes it, as a shipped one has one: `save([{
1350
1381
  kind: 'action', id: 'promo', body }])`; one without an id is refused, and so
1351
1382
  is one under `generated.`. The charter grants it by that id, so a new id
1352
1383
  needs a grant and one that is a shipped action's or fragment's replaces the
1353
1384
  build's for everybody until it is reset. **A read** vex wrote is published
1354
- under its fingerprint, `save([{ kind: 'read', id: '<fingerprint>' }])`, and is
1385
+ under its fingerprint, `save([{ kind: 'read', id: '<fingerprint>', body: undefined }])`, and is
1355
1386
  answered to everybody after what the caller saved themselves; one under the
1356
1387
  fingerprint of a shipped entry is refused. `publisher` is who the publish is
1357
1388
  made by, kept with the save (`artifact_saves.created_by`); an empty one is
@@ -1370,9 +1401,9 @@ It's a Hono app — mount it, extend it, or hand it to a listener.
1370
1401
  calls are ones the publisher's roles grant, its reads ones they may replay,
1371
1402
  no write), and then the whole as a manifest, as a set handed over is:
1372
1403
  `Publish refused — actions call functions the app does not have, or that
1373
- their holders’ charter does not grant:` lists a holder whose roles do not
1374
- grant a call. When the rows are read, the same again, and what does not pass
1375
- any more is left out with a line, said once for each read of the rows: a
1404
+ their holders’ charter does not grant:` lists whoever is granted an action
1405
+ whose call their roles do not grant. When the rows are read, the same
1406
+ again, and what does not pass any more is left out with a line, said once for each read of the rows: a
1376
1407
  layout, an action or a fragment on its own where its own check refuses it
1377
1408
  (`[moss] the action "…" published for everybody is left out: …`), and the
1378
1409
  actions and fragments all together where the manifest refuses them (`[moss]
@@ -1380,7 +1411,7 @@ It's a Hono app — mount it, extend it, or hand it to a listener.
1380
1411
  …`). Once `checkFunctions` has read the app's functions, the rows are read
1381
1412
  again against them: a published action calling a function a new build
1382
1413
  dropped is left out, and the boot is not refused. When a shell is built, for
1383
- that shell and that principal: a layout for an action they do not hold is
1414
+ that shell and that principal: a layout for an action they are not granted is
1384
1415
  not loaded, and a published fragment a shell cannot draw is left out of that
1385
1416
  shell (`[moss] the fragment "…" published for everybody is left out of a
1386
1417
  shell that cannot draw it: …`).
@@ -1391,16 +1422,16 @@ It's a Hono app — mount it, extend it, or hand it to a listener.
1391
1422
  A publish has every living shell adopt, as `refresh` does, and moves the
1392
1423
  pointer, whether or not the rows can be read back: every other process on
1393
1424
  the same database follows the pointer and reads them.
1394
- - `catalogOf(principal): Promise<{ ids, hash }>` — what a principal holds of the
1425
+ - `catalogOf(principal): Promise<{ ids, hash }>` — what a principal is granted of the
1395
1426
  actions in force: `{ ids, hash }`, the granted action ids sorted, with a
1396
1427
  content-hash version token (equal hash, equal application). The principal is
1397
1428
  resolved the way a request resolves it (the `identity` seam, or
1398
1429
  `assignments`), so an integration's actions are there only where it is
1399
1430
  installed. `null` is nobody signed in.
1400
- There is no asking by a list of roles: what somebody holds depends on who
1431
+ There is no asking by a list of roles: what somebody is granted depends on who
1401
1432
  they are resolved to be, installs included, and the server resolves it.
1402
1433
  - `policyForRoles(roles): ScopePolicy` — what a set of roles may read and
1403
- write: the vex policy a request by somebody holding exactly these roles is
1434
+ write: the vex policy a request by somebody wearing exactly these roles is
1404
1435
  served under, compiled from the charter and `behaviors` over every table the
1405
1436
  database has. **One policy per role, merged** — a person may wear several (an
1406
1437
  instructor who also trains here), and reach belongs to the role rather than
@@ -1410,8 +1441,9 @@ It's a Hono app — mount it, extend it, or hand it to a listener.
1410
1441
  - `charterReport(): VerifyReport` — the report `verifyCharter` gave this server:
1411
1442
  boot's, then that of each change that passed. `{ errors, warnings,
1412
1443
  perRole }`, over the universes boot resolved against. Boot and `refresh` read
1413
- `errors` alone and print nothing of the rest, so this is where a host reads
1414
- it, to draw, log or hold a deploy on: `warnings` (an action no role grants, an
1444
+ `errors`, and boot prints the `shape` warnings (a key the charter does not
1445
+ read, a string where a list belongs) and nothing else, so this is where a host reads
1446
+ it, to draw, log or stop a deploy on: `warnings` (an action no role grants, an
1415
1447
  `allow` that matches nothing) and each role's closure `issues`. `errors` is
1416
1448
  always empty here. A push whose target is a binding (`@event.payload`,
1417
1449
  `$.target`) is listed among the `issues` as "not in the catalog", though it is
@@ -1419,23 +1451,24 @@ It's a Hono app — mount it, extend it, or hand it to a listener.
1419
1451
  - `invalidateIdentity(principal): boolean` — forget one principal's identity
1420
1452
  record and reset every living shell of theirs (a role change): the one the
1421
1453
  app keeps for them, and the one a page built for each connection of theirs.
1422
- `false` = no record was held.
1454
+ `false` = no record was kept.
1423
1455
  - `invalidateTag(tag): number` — forget every identity record wearing the
1424
1456
  tag the app put on it (`IdentityRecord.tag`); answers how many. Then every
1425
1457
  living shell adopts, as after `refresh` ("A change is the server's", under
1426
- `shells` below): it is brought level with what its principal holds now, in
1427
- place, so a function or an action their new roles do not grant is no longer
1428
- held. No shell is reset: what people were in the middle of stays. Every
1458
+ `shells` below): it is brought level with what its principal is granted now,
1459
+ in place, so a function or an action their new roles do not grant is no
1460
+ longer in their shell. No shell is reset: what people were in the middle of stays. Every
1429
1461
  living shell, not only those of the records forgotten: a record can be
1430
1462
  dropped while its shell lives (past `runtime.identityMax`, or unread for
1431
1463
  `runtime.identityIdleMs`), and no tag finds it then. So each call asks the app's
1432
1464
  `identity` again for every signed-in person with a living shell whose
1433
- record is not held.
1465
+ record is not kept.
1434
1466
  - `identity(principal): Promise<IdentityRecord>` — who one principal is,
1435
1467
  resolved the way a request resolves it: `{ roles, scope, installed? }`,
1436
1468
  through the same cache the request path uses. `null` is nobody signed in.
1437
1469
  With no `identity` seam the roles are the ones `assignments` names, and
1438
- `scope` is empty.
1470
+ `scope` is empty. A principal it does not name as its own key is `public`,
1471
+ one called `toString` or `constructor` included.
1439
1472
  - `identities?: { list(); meter() }` — the resident identity
1440
1473
  roster (`{ principal, since, lastSeen }`) and what the cache costs
1441
1474
  (`{ size, max, resolved, evicted, expired }`). Present only when the app
@@ -1532,17 +1565,17 @@ is live when something on it can still happen:
1532
1565
 
1533
1566
  What can be pressed is read off the layout a screen is drawn with: a `{ ref }`
1534
1567
  in it, the one an action's own layout is named by included, is read through
1535
- to the layout the shell's store holds under it.
1568
+ to the layout the shell's store keeps under it.
1536
1569
 
1537
1570
  A read made while the action opened is **finished**: its answer is in the tree
1538
1571
  (and listed in `drawnWith`). The app's own shell is always live for a signed-in
1539
1572
  principal — it is the thing that is kept. nova supplies the facts
1540
1573
  (`livenessOf`, `@niscorp/nova/reflect`); moss composes the verdict, because
1541
- the running manifest holds the entries in force, by fingerprint
1574
+ the running manifest keeps the entries in force, by fingerprint
1542
1575
  (`src/shells/snapshot.ts`; the function is not exported, its answer is
1543
1576
  `live`, `why` and `drawnWith` on the snapshot). It reads that list and not
1544
- the cache table, which can hold more: a fingerprint the running manifest does
1545
- not hold (a query written by `answerIntent`) is the last line of the table.
1577
+ the cache table, which can have more: a fingerprint the running manifest does
1578
+ not have (a query written by `answerIntent`) is the last line of the table.
1546
1579
 
1547
1580
  When `live` is false the trees are the whole of the screen, and the terminal
1548
1581
  opens no socket.
@@ -1581,26 +1614,26 @@ What it is handed is `DocumentConfig`, and what it answers is `DrawnDocument`.
1581
1614
  the same node the effect reads it from. Values are escaped.
1582
1615
  - **The page's `<head>` is its screen's own.** It is a node in a layout —
1583
1616
  nova's `nova:head`, whose children (`nova:title`, `nova:meta`, `nova:link`,
1584
- `nova:script`) are the elements a head holds, their props the elements'
1617
+ `nova:script`) are the elements a head contains, their props the elements'
1585
1618
  attributes. It is in the snapshot's trees like everything else on the screen,
1586
1619
  so the elements are read off them and written into the template's `<head>`:
1587
1620
  one takes the place of the tag that said the same thing, anything else is
1588
1621
  added, and the rest of the head is left as the template has it. `head` in the
1589
1622
  result is what was read (`{ elements, actions, refused }`); absent, the
1590
1623
  screen has no head and the page went out with the template's. What a head may
1591
- not hold — something that runs, or styles — is left out and logged. In the
1624
+ not contain — something that runs, or styles — is left out and logged. In the
1592
1625
  browser the terminal keeps the page's head on the same node as the screen
1593
1626
  moves, and the template's own tags come back when it stops saying them.
1594
1627
  - **`site`** is the address the site is served at. With it, every path's
1595
1628
  document says its own canonical address (`<link rel="canonical">`, `og:url`).
1596
1629
  Without it the template's is left as it is.
1597
- - **`template`** must hold the empty root (`root`, default
1630
+ - **`template`** must contain the empty root (`root`, default
1598
1631
  `<div id="root"></div>`). The screen goes inside it, the snapshot element
1599
1632
  straight after. `root` is an empty element written as it stands in the
1600
1633
  template, its opening tag and at once its closing tag: any element
1601
- (`<main id="app"></main>`), not only a `div`. A template that does not hold
1634
+ (`<main id="app"></main>`), not only a `div`. A template that does not contain
1602
1635
  the root, or a root that is not an empty element (an opening tag alone, one
1603
- that holds something, one closed in its own tag), has no place for a screen:
1636
+ that contains something, one closed in its own tag), has no place for a screen:
1604
1637
  the page goes out undrawn (`drawn: false`), and the second case is logged.
1605
1638
  - **`server`** is asked three things, and its type says so
1606
1639
  (`DocumentConfig['server']`): `principalOf(token)`, `page(path)` and
@@ -1655,7 +1688,7 @@ paths (`server.executeAs` runs a read the app serves as a charter role), are the
1655
1688
  caller's.
1656
1689
 
1657
1690
  `renderDocument` is the one way a page is drawn, and its parts are not
1658
- exported. It reads the session the browser holds off the request's cookie, and
1691
+ exported. It reads the session the browser keeps off the request's cookie, and
1659
1692
  it writes the snapshot into the page as a
1660
1693
  `<script type="application/json" id="nisc-snapshot">` element with every `<`
1661
1694
  (and U+2028/2029) escaped: a tree carries what people typed, and a path is
@@ -1678,7 +1711,7 @@ const files: ExportedDocument[] = await exportDocuments({ ...drawing, paths: ['/
1678
1711
  The `Set-Cookie` values that keep `token` in the browser of the page at this
1679
1712
  origin — or, for `null`, take it back. For a sign-in the app answers over HTTP
1680
1713
  (a link redeemed, a provider's callback): set them on the response, and the
1681
- page that follows is signed in having never held the token.
1714
+ page that follows is signed in having never had the token.
1682
1715
 
1683
1716
  ```typescript
1684
1717
  server.get('/login', async (c) => {
@@ -1727,7 +1760,14 @@ and each one a page built for them, with the payload; every other process is
1727
1760
  nudged on the same channel, without it. `false`: no shell of theirs lives
1728
1761
  here.
1729
1762
 
1730
- Two rules hold this lane honest:
1763
+ **A channel is not a trusted lane.** The person's own terminal can publish
1764
+ any channel with any payload into their own shell (`{ type: 'publish',
1765
+ channel, payload }` on the socket), and inside the shell that cannot be told
1766
+ apart from `deliver`. An action must not treat what arrives on a channel as
1767
+ coming from the server: it re-reads what it needs under its own policy, as a
1768
+ reaction does.
1769
+
1770
+ Two rules keep this lane honest:
1731
1771
 
1732
1772
  - **A reaction is told THAT a write landed, never what it wrote.** No rows.
1733
1773
  A receiver that wants the data re-reads it under its own policy — a row
@@ -1792,7 +1832,7 @@ it answers `undefined`, nothing is minted.
1792
1832
  `TIDE_DDL` are exported by `@niscorp/tide/postgres`. They were moss's, and do
1793
1833
  what they did: see tide's [DOCS.md](../tide/DOCS.md), "The driver" and "The
1794
1834
  Postgres store". `createTideStore(runtime.pool, { migrate: false })` takes the
1795
- pool the runtime holds, with `TIDE_SEQUENCE` in `runtime.tables`, and its tables
1835
+ pool the runtime keeps, with `TIDE_SEQUENCE` in `runtime.tables`, and its tables
1796
1836
  are ordinary tables to moss: migrated by `nisc migrate`, introspected,
1797
1837
  grantable, and scoped by a behavior like any other.
1798
1838
 
@@ -1818,13 +1858,13 @@ them. The sequences are checked in the one ledgered run, before the feature
1818
1858
  starts (migrated there under `migrations: 'apply'`), and `migrateTables`
1819
1859
  applies them. A feature reads and writes those
1820
1860
  tables through vex, as an app does, with entries of its own: they are seeded into a
1821
- cache of their own, held by an engine no route is handed, so `/api/vex`
1861
+ cache of their own, kept by an engine no route is handed, so `/api/vex`
1822
1862
  answers `cache_miss` for one of them whatever the charter grants whoever asks,
1823
1863
  and no surface lists it. They run under a policy that admits the tables the
1824
1864
  feature named as its own and no other, and asks for no principal. An entry
1825
1865
  that reads or writes any other table refuses the boot (`moss: the feature "…"
1826
1866
  handed over an entry that reads or writes a table that is not its own: "…"`).
1827
- What another table holds, a feature reads as the app does: through the app's
1867
+ What another table contains, a feature reads as the app does: through the app's
1828
1868
  entries, under the charter. A write by a feature tells the app's engine which
1829
1869
  tables changed, so a reactive read over one of them answers again.
1830
1870
 
@@ -1838,7 +1878,7 @@ tables changed, so a reactive read over one of them answers again.
1838
1878
  `server.invalidateIdentity`, `invalidateTag` and `nudge` publish after
1839
1879
  applying locally: `invalidate-identity`, `invalidate-tag` and `nudge`. The
1840
1880
  fourth, `adopt`, names a principal and tells a process to bring the shells
1841
- it holds for them level with what they hold now; moss publishes it when a
1881
+ it keeps for them level with what they are granted now; moss publishes it when a
1842
1882
  layout is saved for that principal (`session.artifacts`), and it says
1843
1883
  nothing of what was saved. Best-effort:
1844
1884
  each targets state that heals on its own clock. Unset, every path behaves as
@@ -1865,7 +1905,7 @@ tables changed, so a reactive read over one of them answers again.
1865
1905
  that is unset), and when it has moved it reads again every set of actions
1866
1906
  it has a loader for, drops what it had read of what is published for
1867
1907
  everybody (the next shell it builds reads that again), runs the check
1868
- boot runs over what it would then serve, drops what it derived (what each set of roles holds, the compiled
1908
+ boot runs over what it would then serve, drops what it derived (what each set of roles is granted, the compiled
1869
1909
  policies, the identity records) and has its living shells adopt.
1870
1910
  **The pointer carries no set.** It says that something changed, and a
1871
1911
  process learns what by reading rows. The only set that has a loader is the
@@ -1878,7 +1918,7 @@ tables changed, so a reactive read over one of them answers again.
1878
1918
  what they derived and adopt again.
1879
1919
  The row is read and moved through vex, by two
1880
1920
  entries of moss's own that no route serves (`src/data/own-entries.ts`);
1881
- `src/artifactory/generation.ts` holds the clock and no SQL. A move is a compare
1921
+ `src/artifactory/generation.ts` keeps the clock and no SQL. A move is a compare
1882
1922
  and a set: the next number is written where the counter is still what was
1883
1923
  read, and read again where it is not. A move a process could not follow is
1884
1924
  tried again at every poll until it is followed, and logged when that is
@@ -1887,13 +1927,13 @@ tables changed, so a reactive read over one of them answers again.
1887
1927
  has moved on or the reload fails another way, and once when it is followed
1888
1928
  (`followed the generation pointer to 4, after 12 looks that failed`). A
1889
1929
  reload that fails the same way for an hour is one line, not sixty.
1890
- - The identity cache — what holds the records `app.identity` resolves. It is
1930
+ - The identity cache — what keeps the records `app.identity` resolves. It is
1891
1931
  the server's own (`src/identity/cache.ts`) and is not exported. Its limits
1892
1932
  are `runtime.identityMax` (default 10,000) and `runtime.identityIdleMs`
1893
1933
  (default 30 minutes). At `identityMax` the least recently read record is
1894
1934
  dropped to make room, and whoever it was is resolved again on their next
1895
1935
  request. A record is forgotten with `server.invalidateIdentity`,
1896
- `invalidateTag` and `refresh`, and what is held is read through
1936
+ `invalidateTag` and `refresh`, and what is kept is read through
1897
1937
  `server.identities`.
1898
1938
 
1899
1939
  ### Telemetry
@@ -1911,13 +1951,13 @@ with `integrations/` and whose `hasPrincipal` is `false`. The generation
1911
1951
  counter's poll emits none. A `socket.upgrade` is `ok` (admitted), `refused` (the token
1912
1952
  offered is nobody's, or no place is left for a shell for nobody) or
1913
1953
  `error` (the session could not be opened: the verifier
1914
- threw, what somebody holds could not be asked, their shell could not be built).
1954
+ threw, what somebody is granted could not be asked, their shell could not be built).
1915
1955
  A `socket.close` span runs from the upgrade to the close.
1916
1956
  `emit` is never awaited, and a sink that throws costs the caller nothing: the
1917
1957
  throw is caught where the span is emitted, and logged.
1918
1958
 
1919
1959
  `refused` is a no the server gave (a policy, a limit, an integration that is
1920
- not installed): an outcome, and not a fault. `attributes` holds identifiers
1960
+ not installed): an outcome, and not a fault. `attributes` contains identifiers
1921
1961
  and measurements (a fingerprint, a count, a status) and never a payload, a
1922
1962
  row or who a principal is: a principal is there only as `hasPrincipal`. Moss
1923
1963
  sets none of `traceId`, `spanId` and `parentSpanId`.
@@ -1932,7 +1972,7 @@ const telemetry: Telemetry = { emit: (span) => void spans.push(span) };
1932
1972
 
1933
1973
  ### Resolution
1934
1974
 
1935
- Who somebody is, what they hold and what they may read and write are asked of
1975
+ Who somebody is, what they are granted and what they may read and write are asked of
1936
1976
  the server, which resolves a principal the way a request does (the `identity`
1937
1977
  seam, or `assignments`): `(await server.identity(principal)).roles`,
1938
1978
  `server.catalogOf(principal)`, `server.policyForRoles(roles)`. Nothing is
@@ -1952,7 +1992,7 @@ app that resolves people through `identity`.
1952
1992
  - An entry that declares a `reach` (vex) is served under the same roles'
1953
1993
  grants recompiled at that named profile. The vex surfaces and `executeAs` do
1954
1994
  it themselves; it narrows rows, never widens verbs.
1955
- - A layout variant a set of roles holds (ring 2) is put in place of its
1995
+ - A layout variant a set of roles is granted (ring 2) is put in place of its
1956
1996
  action's layout where a shell is built, in the shell's layout store.
1957
1997
  Nothing answers the variants by themselves.
1958
1998
  - `verifyApp(app, grants)` — the check boot runs, for an app
@@ -1964,7 +2004,8 @@ app that resolves people through `identity`.
1964
2004
  report is `{ errors, said, charter }`: `errors` is `{ check, detail }[]`,
1965
2005
  `check` one of `'actions'` (a definition nova's schema does not read),
1966
2006
  `'charter'`, `'reach'` and `'variants'`; `said` is what a boot only says (a
1967
- chain of steps that never ends), and `charter` is the charter engine's whole
2007
+ chain of steps that never ends, a role that allows every function, and the
2008
+ charter's `shape` warnings), and `charter` is the charter engine's whole
1968
2009
  report. A boot refuses on `errors`. A running server answers for what is in
1969
2010
  force with `server.charterReport()`. It verifies and does nothing else: what
1970
2011
  it is handed is not read by the manifest's schema and is not frozen.
@@ -1995,7 +2036,7 @@ for (const error of report.errors) console.error(`${error.check}: ${error.detail
1995
2036
  is not exported). It is handed no manifest and no
1996
2037
  runtime, but a typed object of what it needs: one function that answers what
1997
2038
  a principal's shell is made of (who they are, the action definitions they
1998
- hold, the canvases and the frame, each naming its layout in the layout
2039
+ are granted, the canvases and the frame, each naming its layout in the layout
1999
2040
  store, the layout store's seed with those layouts in it (for an action the
2000
2041
  published one over the build's, their roles' layout variant over that, and
2001
2042
  over it the layout of their own they marked in use), the
@@ -2008,11 +2049,11 @@ for (const error of report.errors) console.error(`${error.check}: ${error.detail
2008
2049
  reach a shell through that one answer, and the server's wiring reads none
2009
2050
  of them off the app. For an entry that is what a shell is told of the reads
2010
2051
  on its screens. What a read replays the engine asks the running manifest
2011
- for too (see "Where the app's entries are held", under `createServer`).
2052
+ for too (see "Where the app's entries are kept", under `createServer`).
2012
2053
  A kept shell may sit unattached for
2013
2054
  `runtime.shellIdleMs` (default 30 minutes; `0` disables the sweep). A shell
2014
2055
  that is not kept (nobody signed in; any shell of a page's host) ends when
2015
- its last terminal leaves, and the host holds nothing of a shell that has
2056
+ its last terminal leaves, and the host keeps nothing of a shell that has
2016
2057
  ended.
2017
2058
  - `session(token, principal, options?)` — `options = { seed?, inputs? }`;
2018
2059
  `snapshot` is described under [The document](#the-document), and what it
@@ -2030,13 +2071,13 @@ for (const error of report.errors) console.error(`${error.check}: ${error.detail
2030
2071
  so that a change can reach it. The socket ends it when the connection
2031
2072
  closes. Code that opens one in process and attaches nothing ends it
2032
2073
  itself, with `session.detach(connection)` (any connection: none was
2033
- attached); until then the host holds the shell.
2074
+ attached); until then the host keeps the shell.
2034
2075
  - A host has no `adopt` and no `stop`. Each was a second way, for one
2035
2076
  host, to something a server does for all of them at once.
2036
2077
  **A change is the server's.** When what the app consists of changes
2037
2078
  (`server.refresh()`, `server.replaceActions()`, `server.replaceEntries()`, an integration approved
2038
2079
  or removed, a change another process made), every living shell of every
2039
- host adopts (a layout somebody saved for themselves is adopted by the shells of that principal alone): it is brought level with what its principal holds now, in
2080
+ host adopts (a layout somebody saved for themselves is adopted by the shells of that principal alone): it is brought level with what its principal is granted now, in
2040
2081
  place. Every living shell: the ones a host keeps, and the ones it built
2041
2082
  for one connection, which for the app's host is each visitor's and for a
2042
2083
  page's host is everybody's. Definitions that arrived or changed are
@@ -2054,13 +2095,13 @@ for (const error of report.errors) console.error(`${error.check}: ${error.detail
2054
2095
  it. The canvases a shell's manifest declares, and what is mounted on any
2055
2096
  canvas, are the shell's own state and are not taken again: a reset builds
2056
2097
  that afresh. A canvas the manifest does not declare, that a layout in
2057
- force held a slot for, is taken out by an adopt, with what is mounted on
2058
- it, once no layout holds the slot. A
2059
- shell that cannot adopt is logged and keeps what it held; the rest go on.
2098
+ force had a slot for, is taken out by an adopt, with what is mounted on
2099
+ it, once no layout has the slot. A
2100
+ shell that cannot adopt is logged and keeps what it had; the rest go on.
2060
2101
  Each shell adopts on its own: one whose principal is never answered (an
2061
- `identity` that hangs for them) holds up no other. So a change asks about
2102
+ `identity` that hangs for them) delays no other. So a change asks about
2062
2103
  every living shell in the same moment, and an app's `identity` runs at
2063
- once for every signed-in principal whose record is not held.
2104
+ once for every signed-in principal whose record is not kept.
2064
2105
  A shell whose build was under way adopts when it lands, and so does one a
2065
2106
  reset was replacing; no change waits for a build, or for another change.
2066
2107
  One built for the length of a `snapshot` is read and ended, and adopts
@@ -2074,7 +2115,9 @@ for (const error of report.errors) console.error(`${error.check}: ${error.detail
2074
2115
  it built for each of their connections.) `false` = they have no living
2075
2116
  shell in this host; nothing is built. This host, in this process: it
2076
2117
  reaches no page's shell and no other process. To tell somebody's screens
2077
- that something changed, wherever they live, a server calls `nudge`.
2118
+ that something changed, wherever they live, a server calls `nudge`. The
2119
+ person's own terminal can publish the same channel with any payload, so
2120
+ what arrives on a channel is a ping, not the server's word.
2078
2121
  - `list()` — every durable shell alive right now, each as
2079
2122
  `{ principal, connections, since, idleSince, canvases }`. moss owns the map,
2080
2123
  so moss enumerates it; an app keeping its own note beside it can only drift.
@@ -2089,7 +2132,7 @@ for (const error of report.errors) console.error(`${error.check}: ${error.detail
2089
2132
  Every living shell of theirs on this host: the one it keeps for them, or,
2090
2133
  on a host that keeps none (a page's), the one built for each of their
2091
2134
  connections, each replaced for itself.
2092
- `false` = they hold no shell, which is an answer, not an error. The
2135
+ `false` = they have no shell, which is an answer, not an error. The
2093
2136
  replacement is built from what the shell was opened with (for a page's,
2094
2137
  the inputs of its path and its id seed), and a shell's resets run one
2095
2138
  after another. A reset that arrives while another waits for its turn is
@@ -2106,9 +2149,9 @@ for (const error of report.errors) console.error(`${error.check}: ${error.detail
2106
2149
  remote clients ride `attach`/`dispatch`. Nine members of `shell` throw, as
2107
2150
  on [`FunctionSession`](#functionsession): the whole shell is
2108
2151
  `unverifiedShell(session)`. `shell` is a **getter** — `reset`
2109
- replaces the shell under a session already held, so a snapshot of the field
2152
+ replaces the shell under a session already handed out, so a snapshot of the field
2110
2153
  would go on addressing the disposed one.
2111
- `dispatch(canvas, event)` holds what a terminal sent to the shell: the
2154
+ `dispatch(canvas, event)` checks what a terminal sent to the shell: the
2112
2155
  canvas must be one the shell has, an `origin` the event names must be an
2113
2156
  instance on that canvas (with none, the canvas's active instance is
2114
2157
  stamped), and the event must parse as one of nova's (`NovaEventSchema`:
@@ -2157,7 +2200,7 @@ server.nudge('usr_ada', 'notes-changed');
2157
2200
  transport: `server.socket(url, connection)`. `server.socket.stop()` ends
2158
2201
  revalidation (the timer is unref'd, so a plain process needn't call it).
2159
2202
  `createServer` builds it (`src/socket/`), handed who a token is, what
2160
- somebody holds, and where a session comes from for the app and for each
2203
+ somebody is granted, and where a session comes from for the app and for each
2161
2204
  page. Neither its factory nor its type is exported by name: the type is
2162
2205
  `MossServer['socket']`.
2163
2206
  - **Identity is asked twice.** At upgrade, and then every
@@ -2166,15 +2209,28 @@ server.nudge('usr_ada', 'notes-changed');
2166
2209
  somebody else — gets an `invalid_token` error frame and a `4401` close, which
2167
2210
  is the recovery the terminal already performs: drop the token, reconnect
2168
2211
  anonymous, land on the served lock screen.
2169
- - Anonymous connections are never revalidated: nothing they hold can expire.
2212
+ - Anonymous connections are never revalidated: nothing they have can expire.
2170
2213
  - A verifier that **throws** is a fault, not a sign-out — the connection is
2171
2214
  left alone and asked again next pass, so a database blip cannot become an
2172
2215
  outage. Only an explicit `null` (or a changed principal) closes. That it
2173
2216
  threw is logged, once for a pass: how many connections could not be asked
2174
2217
  about, and the first error.
2175
- - One pass at a time: a pass asks about every connection in turn, and one
2176
- that is due while another is still asking is skipped. A slow verifier is
2177
- not asked more the slower it gets.
2218
+ - One pass at a time: a pass asks the verifier once for each token, every
2219
+ token at the same moment, so connections that present one token share one
2220
+ call, and a revoked token's socket closes within one `sessionRevalidateMs`
2221
+ plus the time the verifier takes to answer, however many connections there
2222
+ are. The most the verifier is called is once for each distinct token every
2223
+ `sessionRevalidateMs`, and the calls of a pass arrive together at its
2224
+ start: with 200 tokens, 200 calls at once each interval. A verifier with a
2225
+ strict limit on calls at once queues them itself; with
2226
+ `session: 'sessions'` they are 200 queries on the pool at once, ahead of
2227
+ requests that arrive in that moment. A pass waits for the answers until
2228
+ the next pass is due; an answer that comes later is acted on when it comes
2229
+ (a `null` closes), and those connections are not asked about again until
2230
+ it has come. A pass that came due while another was still waiting starts
2231
+ as soon as that one ends. A slow verifier is not asked more the slower it
2232
+ gets. A verifier that never answers for one token leaves only that token's
2233
+ connections unchecked, and every other is still asked.
2178
2234
  - Without this the socket was the asymmetry: the HTTP surfaces re-ask on
2179
2235
  every request, so an expired credential left the socket open and rendering
2180
2236
  while every endpoint the server shell called came back 401 — a live
@@ -2185,7 +2241,7 @@ server.nudge('usr_ada', 'notes-changed');
2185
2241
  catalog asked, its shell built) is not attached to a shell, so a kept shell
2186
2242
  idles and one built for that connection alone is disposed. The type also
2187
2243
  has `upgrade` (below) and `seal`. `seal` is set by the socket, on a
2188
- connection whose browser holds a seal: a transport leaves it out.
2244
+ connection whose browser has a seal: a transport leaves it out.
2189
2245
  - `ServerMessage` (`@niscorp/moss/protocol`) — what the server sends: `hello | catalog | frame | render |
2190
2246
  render-delta | session | pong | error`.
2191
2247
  - What a terminal sends is `event | publish | resync | reset | back | popTo | ping`,
@@ -2222,7 +2278,7 @@ server.nudge('usr_ada', 'notes-changed');
2222
2278
  protocol-level, not app-level — no action declares it and no charter grants
2223
2279
  it — and it is answered by the frames it produces, not by an envelope of its
2224
2280
  own. Any terminal may send it, signed in or not, and each one that is acted
2225
- on is a whole build: who somebody is, what they hold, and the app's
2281
+ on is a whole build: who somebody is, what they are granted, and the app's
2226
2282
  `inputs`, `phrases`, `functions` and `seeds`. Resets that arrive while one
2227
2283
  waits for its turn are answered by it (`reset(principal)`, under `shells`),
2228
2284
  so a burst costs two builds at most. Nothing limits how often: a terminal
@@ -2251,7 +2307,7 @@ server.nudge('usr_ada', 'notes-changed');
2251
2307
  - `4503`: the server is serving as many terminals with nobody signed in as
2252
2308
  `runtime.anonymousShellMax` allows, and built no shell for this one. An
2253
2309
  `at_capacity` error frame, then the close. Not a recovery: the terminal
2254
- keeps what it holds and reconnects with its usual backoff, which grows
2310
+ keeps what it has and reconnects with its usual backoff, which grows
2255
2311
  for as long as it is refused.
2256
2312
  - `4426`: the two ends speak protocols the other cannot (below).
2257
2313
  - `error` codes: `invalid_token`, `session_failed`, `at_capacity`,
@@ -2267,7 +2323,7 @@ server.nudge('usr_ada', 'notes-changed');
2267
2323
  - **Who a terminal is** is decided on the upgrade request, from a header of
2268
2324
  it — never from its address, which is what every proxy on the way writes
2269
2325
  into its log. A terminal offers the subprotocol `nisc`, and beside it its
2270
- token when it holds one: `offerToken(token | null)` returns the list to
2326
+ token when it has one: `offerToken(token | null)` returns the list to
2271
2327
  construct the socket with (`new WebSocket(url, offerToken(token))`), and the
2272
2328
  server answers `nisc`. A token in the address (`?token=`) is not read. A
2273
2329
  transport hands the offer over as `connection.upgrade.offered`
@@ -2276,14 +2332,16 @@ server.nudge('usr_ada', 'notes-changed');
2276
2332
  - **A browser on the app's own page** is who its session cookie says
2277
2333
  ([`sessionCookies`](#sessioncookiespage-token-options)). The cookie is read
2278
2334
  only when the upgrade's `Origin` is the host it was addressed to, or one
2279
- `runtime.origins` lists. (Behind a proxy that rewrites `Host` and with
2280
- nothing listed, no page is the app's own: terminals hold their own tokens,
2335
+ `runtime.origins` lists. A `Host` that writes out the scheme's own port
2336
+ (`app.example.com:443` for `https://app.example.com`, `:80` for `http`)
2337
+ names the same host. (Behind a proxy that rewrites `Host` and with
2338
+ nothing listed, no page is the app's own: terminals keep their own tokens,
2281
2339
  as before, and moss says so once in the log.) A token such a page offers is who it is and is
2282
2340
  moved into the cookie by the answer to the upgrade; one that no longer
2283
2341
  resolves is nobody (served, not refused) and is taken back. `?key=` names
2284
2342
  which of the browser's sessions the terminal is — a seat; the cookie is named
2285
2343
  by it. `?leave=1` is a terminal that was signed out: it is nobody whatever
2286
- its browser holds, and the cookie is taken back. A transport passes what the
2344
+ its browser has, and the cookie is taken back. A transport passes what the
2287
2345
  request carried as `connection.upgrade` — `{ offered, origin, host, cookie }`
2288
2346
  — and, when it has not answered the request yet, `answer(cookies)`: moss
2289
2347
  calls it once who is asking is decided, with the `Set-Cookie` values to
@@ -2373,12 +2431,12 @@ through the object form — when connection count matters more than bandwidth.
2373
2431
  An object is handed to `ws` verbatim; see its `perMessageDeflate` options.
2374
2432
 
2375
2433
  The setting is the Node transport's, and the server's socket carries it there
2376
- from the runtime: it holds under `serve`, `nisc start`, the dev plugin, and a
2434
+ from the runtime: it applies under `serve`, `nisc start`, the dev plugin, and a
2377
2435
  host that attaches `server.socket` itself.
2378
2436
 
2379
2437
  #### Frame deltas — `runtime.shellFrameDelta`, default **off**
2380
2438
 
2381
- A changed canvas, described against the frame that connection already holds:
2439
+ A changed canvas, described against the frame that connection already has:
2382
2440
  copy runs from the old frame plus literal inserts, checksummed.
2383
2441
 
2384
2442
  ```typescript
@@ -2398,7 +2456,7 @@ the same shell, in the same pass. The two kinds of connection coexist.
2398
2456
  **A canvas whose frame is over 64 KB is always sent whole.** Comparing two
2399
2457
  frames costs the server in proportion to their size, not to what changed, and
2400
2458
  it does that work on the thread every session shares — about 7 ms at 64 KB, a
2401
- second at 2.7 MB. So when the frame a terminal holds, or the one replacing it,
2459
+ second at 2.7 MB. So when the frame a terminal has, or the one replacing it,
2402
2460
  is longer than 64 KB, the server does not compare them. It is not a setting.
2403
2461
 
2404
2462
  What it buys, measured on Lyra:
@@ -2462,7 +2520,7 @@ Correctness, which matters more than the saving:
2462
2520
  first; this is the catch-all. `owned` (default: moss's own prefixes) names
2463
2521
  what is never a page — an unknown path under one is a 404, not a screen. So is
2464
2522
  a **missing file**: a name with an extension that is neither a file in `dist`
2465
- nor a page of the manifest is answered 404 (a browser holding a page from
2523
+ nor a page of the manifest is answered 404 (a browser keeping a page from
2466
2524
  before a deploy asks for its script by the old name, and needs "gone" back,
2467
2525
  not a document). A page's own path may have a dot in it (`/docs/v1.2`).
2468
2526
  What a browser may keep of these files, and compressing what goes out, is not
@@ -2505,7 +2563,12 @@ Requires the optional `vite` peer.
2505
2563
  (`renderDocument`); `MOSS_PATHS` go to the app server; the rest is vite's.
2506
2564
  An edit under a watched path re-boots the whole app and reloads the page;
2507
2565
  the outgoing server answers until the new one is up, and a failed re-boot
2508
- keeps it. The connections of an app that is let go are closed (`1001`), so
2566
+ keeps it. What the charter does not read as written (its `shape` warnings
2567
+ in `server.charterReport()`, such as a misspelt `denny`) is shown over the
2568
+ page on vite's error overlay each time a browser connects, one line for
2569
+ each; the app runs under it. While the overlay is open, it covers the page,
2570
+ and vite turns the next live update into a full reload. An app whose
2571
+ charter has no `shape` warning never sees it. The connections of an app that is let go are closed (`1001`), so
2509
2572
  a terminal that is not a page connects again, to the app that is booted.
2510
2573
  - `options.app(load): Promise<DevApp>` — stand the app up. `load` is vite's
2511
2574
  `ssrLoadModule`. `DevApp = { server, close?, draw?, htmlAttributes?,
@@ -2517,9 +2580,15 @@ Requires the optional `vite` peer.
2517
2580
  end of the request's socket is loopback (`127.0.0.0/8`, `::1`, or either
2518
2581
  written as an IPv4-mapped IPv6 address). Any other request is answered
2519
2582
  `403` with a sentence that says why, and the app is not asked. What a
2520
- header says of where a request came from (`X-Forwarded-For`) is not read;
2521
- behind a proxy on the same machine every request is the proxy's, and is
2522
- this machine's.
2583
+ header says of where a request came from (`X-Forwarded-For`) decides
2584
+ nothing; behind a proxy on the same machine every request is the proxy's,
2585
+ and is this machine's. A tunnel (ngrok, cloudflared, a dev tunnel) is such
2586
+ a proxy: anybody who has its address signs in as anybody. When
2587
+ `X-Forwarded-For`, `X-Real-IP` or `Forwarded: for=` names an address other
2588
+ than this machine, the sign-in is answered (`302`, with the session) and
2589
+ the dev log says so. A proxy that names no address (`Forwarded:
2590
+ for=unknown`, or a hidden name such as `for=_hidden`) gets the same line in
2591
+ the log; nothing is refused for it.
2523
2592
  - `signInFromNetwork?: boolean` (default `false`) answers the sign-in to
2524
2593
  every device that can reach the dev server, for trying a signed-in screen
2525
2594
  on a phone. It hands out a session for whoever the address names: with it
@@ -2626,7 +2695,7 @@ vocabulary, and the app that has it defines it.
2626
2695
 
2627
2696
  `check` and `prepare` are handed, as `bundle` (`ExtensionContext`), what moss
2628
2697
  knows of the bundle: `integration` (its id), `url` (where its service
2629
- lives), `actions` (its action definitions, each already held to its
2698
+ lives), `actions` (its action definitions, each already checked against its
2630
2699
  namespace, its endpoints and the kit), `fingerprints` (the ones the app
2631
2700
  serves), and `layoutMisfits(layout)` (each place a layout does not fit the
2632
2701
  app's kit, for a vocabulary that lets a bundle carry one).
@@ -2635,7 +2704,7 @@ vocabulary, and the app that has it defines it.
2635
2704
  "console.log(require('node:crypto').randomBytes(32).toString('base64'))"`).
2636
2705
  With none, a keypair is made when the feature starts and kept nowhere, so
2637
2706
  each boot and each process has its own. Give one where an integration's
2638
- service holds the public half in its environment, or where a deployment
2707
+ service keeps the public half in its environment, or where a deployment
2639
2708
  runs more than one process: the same seed is the same key everywhere. It is
2640
2709
  this feature's setting and no other feature is handed it. One that decodes
2641
2710
  to fewer than 32 bytes refuses the boot.
@@ -2665,14 +2734,14 @@ that:
2665
2734
  - `listIntegrations(): Promise<RegisteredIntegration<Extension>[]>` — every
2666
2735
  registered integration, in the order of the ids: `{ id, status, url,
2667
2736
  extension }`. `status` is `'pending'` or `'approved'`; `extension` is what
2668
- the row holds, read by the app's schema and so typed by it (`undefined`: the
2737
+ the row stores, read by the app's schema and so typed by it (`undefined`: the
2669
2738
  bundle carried none, the app supplied no schema, or the schema no longer
2670
2739
  reads what was stored, which is logged with the integration's id). An app
2671
2740
  builds its placements, its listing and anything else from this.
2672
2741
  - `callIntegration(id, path, { principal, method?, body?, scope? }):
2673
2742
  Promise<Response>` — call an installed integration when
2674
2743
  nobody is driving; throws unless it is approved and installed for the
2675
- principal's tenant. It is not held to the integration's reach: an app calls
2744
+ principal's tenant. It is not checked against the integration's reach: an app calls
2676
2745
  an endpoint its own vocabulary names (a preview, a page it mounts on a route
2677
2746
  of its own) with this. `principal` is who the call is made for, and who the
2678
2747
  assertion names. `method` defaults to `POST`; `body` is sent as JSON;
@@ -2693,7 +2762,7 @@ for everybody, and an empty list is none.
2693
2762
  The rule that reads it is this feature's (an
2694
2763
  `ext.<audience>.<integration>.<name>` action is there for somebody only where
2695
2764
  that integration is in their list), and it is laid when the feature starts:
2696
- an app that names no feature has no such rule, and holds an `ext.…` action
2765
+ an app that names no feature has no such rule, and has an `ext.…` action
2697
2766
  of its own wherever the charter grants it.
2698
2767
 
2699
2768
  What the feature serves once it is started:
@@ -2706,10 +2775,10 @@ What the feature serves once it is started:
2706
2775
 
2707
2776
  A bearer token with the `ik_` prefix is an integration key: it is resolved to
2708
2777
  the integration it was issued to and, through `integrationActor`, to a
2709
- principal (`401` unknown key, `403` no actor). No two integrations hold the
2778
+ principal (`401` unknown key, `403` no actor). No two integrations have the
2710
2779
  hash of one key (a unique index on `integrations.key_hash`).
2711
2780
 
2712
- **What intake holds a bundle to**, before any of it is kept. It is upgraded by
2781
+ **What intake checks a bundle against**, before any of it is kept. It is upgraded by
2713
2782
  its grammar stamps and read by the bundle's schema. Each action is named
2714
2783
  `ext.<audience>.<integration>.<name>` under the integration's own id; each of
2715
2784
  its endpoints is a fingerprint the app serves, called on one of the app's vex
@@ -2721,7 +2790,7 @@ routed: a `..`, `.`, `%2e` or `\` that would move it is refused, and so is a
2721
2790
  `{{…}}` template, which is filled in when the endpoint is called; one in the
2722
2791
  query is taken. Its layout composes what the app's kit has; and no
2723
2792
  chain of its steps, laid over the app's own actions, runs for ever. Then
2724
- `extension` is read by the app's schema and held to the app's `check`. Every
2793
+ `extension` is read by the app's schema and checked by the app's `check`. Every
2725
2794
  reason, moss's and the app's, is reported together, and any one refuses the
2726
2795
  bundle whole: the last good import keeps serving.
2727
2796
 
@@ -2734,7 +2803,7 @@ bundle whole: the last good import keeps serving.
2734
2803
  its actions in place of the ones it shipped before, and the hash of its key
2735
2804
  on the import a key is issued with. It lands whole, or the import before it
2736
2805
  is still there, whole. The answer carries `key` once, on the registration
2737
- whose key the row holds: the hash is written where the row holds none, so of
2806
+ whose key the row stores: the hash is written where the row has none, so of
2738
2807
  two registrations of one new integration in the same moment one is answered
2739
2808
  the key and the other is answered as a later import is, with none.
2740
2809
  - *Approve* (`POST /operator/integrations/:id/approve`) reads what the
@@ -2760,12 +2829,23 @@ bundle whole: the last good import keeps serving.
2760
2829
  - *The proxy* (`/integrations/:id/*`) forwards a signed-in caller's call to an
2761
2830
  approved integration that is installed for them, with an assertion that
2762
2831
  says who they are. It forwards the paths the integration's actions declare
2763
- as endpoints, each for whoever holds an action that declares it, and
2832
+ as endpoints, each for whoever is granted an action that declares it, and
2764
2833
  answers `404` for any other path.
2765
2834
  - *A webhook* (`POST /integrations/:id/hook/*`) takes no session and no
2766
2835
  assertion is minted for it: the body goes on to the integration's service
2767
- byte for byte, with the vendor's headers but `authorization` and `host`,
2768
- and the integration checks the vendor's signature itself. An integration
2836
+ byte for byte, and the integration checks the vendor's signature itself.
2837
+ The vendor's headers go with it, signature headers and `content-type`
2838
+ among them, but not the credentials a browser or a proxy adds:
2839
+ `authorization`, `cookie`, `proxy-authorization` and moss's
2840
+ `x-operator-key` stay behind, and so does `host`. Any web page can send a
2841
+ signed-in visitor's browser to the hook, so what it carries of the app's
2842
+ session must not leave. The headers that
2843
+ frame one connection (`transfer-encoding`, `keep-alive`, `expect`,
2844
+ `upgrade`) stay behind too: the request to the service is framed anew from
2845
+ the body that arrived. A request that asks to upgrade its connection
2846
+ (`Connection: upgrade` with `Upgrade`) is a socket upgrade, which the door
2847
+ never sees. One that carries `Connection: upgrade` without `Upgrade` is
2848
+ answered `502`: Node's fetch refuses to send that header. An integration
2769
2849
  that is unknown or not approved answers `404`. **The door has a limit, and
2770
2850
  it is a limit per process**: 240 calls a minute for each integration,
2771
2851
  counted in the memory of the process that takes them, in windows of a minute
@@ -2776,6 +2856,17 @@ bundle whole: the last good import keeps serving.
2776
2856
  a process that restarts counts from nothing. It is not a ceiling for the
2777
2857
  deployment, and neither number is a setting: a deployment that needs one
2778
2858
  ceiling across its processes sets it where they meet, at its proxy.
2859
+ - *How an answer is served.* What the integration's service answers, through
2860
+ the proxy or a webhook, goes back with its status, its body and its
2861
+ `content-type`, plus `x-content-type-options: nosniff` and
2862
+ `content-security-policy: sandbox allow-scripts allow-forms allow-popups
2863
+ allow-popups-to-escape-sandbox allow-modals allow-downloads
2864
+ allow-top-navigation`. A page a browser lands on (an OAuth `form_post`
2865
+ callback, a SAML POST) still runs its script, submits its forms and moves
2866
+ the window on, but as a page with no origin, never the app's own: it cannot
2867
+ read the app's cookies or browser storage, a socket it opens is refused,
2868
+ and a form it posts into the app carries no session cookie. A `fetch` that
2869
+ reads the answer is not affected by either header.
2779
2870
 
2780
2871
  **A vendor's own page inside the app** is the app's to mount. Moss frames
2781
2872
  none: an app that wants one serves a route of its own (`routes(server)` in
@@ -2799,12 +2890,12 @@ app's own vex entry reads `integrations.extension` as it reads any column.
2799
2890
  | `extension` | what its bundle said in the app's own vocabulary, as the app's `prepare` answered it |
2800
2891
  | `last_import_at`, `last_error` | when the last good import landed, and why the last one did not |
2801
2892
 
2802
- `integration_actions` holds one row for each action: `integration_id`,
2893
+ `integration_actions` has one row for each action: `integration_id`,
2803
2894
  `action_id`, `definition`, and `grammar`, the stamps the definition is written
2804
2895
  at.
2805
2896
 
2806
2897
  The feature reads and writes them through vex, with entries of its own that no
2807
- route serves (see [Features](#features)); it holds no SQL. Landing a bundle is
2898
+ route serves (see [Features](#features)); it contains no SQL. Landing a bundle is
2808
2899
  a batch, so `runtime.db` has to have `transaction`, as it does for any batch an
2809
2900
  app writes.
2810
2901
 
@@ -2834,7 +2925,7 @@ const approved = async (): Promise<RegisteredIntegration<Listing>[]> => (await i
2834
2925
 
2835
2926
  `{ verifyKey, mint(claims, ttlMs?) }` — the ed25519 assertion the feature signs
2836
2927
  every call to an integration with, for a check or a service in the same
2837
- workspace that wants to mint or hold one. An integration verifies it against
2928
+ workspace that wants to mint or keep one. An integration verifies it against
2838
2929
  `GET /api/integrations/verify-key`.
2839
2930
 
2840
2931
  `seed` is 32 bytes as base64, and makes the same keypair wherever it is given:
@@ -2946,7 +3037,7 @@ goes around moss: see [`FunctionSession`](#functionsession).
2946
3037
  - `initial` — pass what `readDocumentSnapshot()` returned. The wire starts from
2947
3038
  it instead of from nothing, so the first render matches the page's HTML and
2948
3039
  the first frames off the socket confirm it. It is used only when it was drawn
2949
- for who this terminal is — signed in and holding a token, or neither;
3040
+ for who this terminal is — signed in and with a token, or neither;
2950
3041
  anything else is somebody else's screen and the wire starts empty. Its `seed`
2951
3042
  is named on the first connect only. Its `path` is named on every connect
2952
3043
  (`config.path` overrides it; a page that was not drawn on the server passes
@@ -2992,7 +3083,7 @@ is the same recovery a layer down. It is also the way out of `incompatible`,
2992
3083
  once the server has been updated: the connection it makes is found compatible
2993
3084
  or not on its own account, and is retried like any other when it drops.
2994
3085
 
2995
- **The wire holds one socket at a time.** Before it makes one it lets go of the
3086
+ **The wire has one socket at a time.** Before it makes one it lets go of the
2996
3087
  one it had: its handlers come off and it is closed. That one may have closed
2997
3088
  already, may have carried another principal, or may be a connect still in
2998
3089
  flight when `reset()` was called; whichever, nothing it says afterwards is
@@ -3047,7 +3138,7 @@ one pressed once the connection is open drops them and is sent, because it was
3047
3138
  pressed on the screen the person sees now. `publish`, `back` and `popTo` name
3048
3139
  no canvas to check against, and are dropped unless the connection is open.
3049
3140
 
3050
- `back()` sends `{ type: 'back' }` and nothing else — no location is held here,
3141
+ `back()` sends `{ type: 'back' }` and nothing else — no location is kept here,
3051
3142
  so what comes back is whatever canvases moved, over the same stream every other
3052
3143
  change arrives on. It is dropped on a closed socket rather than queued: a back
3053
3144
  pressed during an outage is about a screen the person is no longer being served,
@@ -3120,7 +3211,7 @@ in the subpaths.
3120
3211
  status.
3121
3212
 
3122
3213
  **The connection's status reaches every target, the same way.** When a
3123
- connection drops, the trees the terminal holds stay on screen: a reconnect
3214
+ connection drops, the trees the terminal has stay on screen: a reconnect
3124
3215
  re-sends the current ones, and blanking in between would show a working app as
3125
3216
  an empty one. So a screen left up by a dead socket looks exactly like a live
3126
3217
  one, and every target is told which it is: `api.status()` is `'connecting' |
@@ -3170,7 +3261,7 @@ Requires the optional `react`/`react-dom` peers.
3170
3261
  SlotWrapper. Served trees carry identity only, so its props
3171
3262
  (`TerminalSlotWrapperProps`) are `{ canvasId, instanceId, definitionId }`
3172
3263
  and the content as `children` — `definitionId`, not `action`.
3173
- - **Adoption.** A `root` that already holds elements, on a wire that has a
3264
+ - **Adoption.** A `root` that already contains elements, on a wire that has a
3174
3265
  frame, was drawn on the server from the snapshot the wire started from: the
3175
3266
  target adopts those elements (`hydrateRoot`) instead of replacing them. An
3176
3267
  empty root, or a wire with no frame (the page was drawn for somebody else),
@@ -3187,7 +3278,7 @@ Requires the optional `react`/`react-dom` peers.
3187
3278
  one. It is drawn with the status the page's terminal starts in: `'static'`
3188
3279
  when `live` is `false` (no socket is opened for that page), `'connecting'`
3189
3280
  otherwise. So a kit component that draws the status draws the same thing on
3190
- both sides. The same holds for the Vue entry below.
3281
+ both sides. The same applies to the Vue entry below.
3191
3282
 
3192
3283
  **What a kit owes a server-drawn page.** The first pass in the browser must
3193
3284
  draw exactly what the server drew, so nothing that differs between the two may
@@ -3201,7 +3292,7 @@ decide a component's first render:
3201
3292
  - What a component puts on `<html>` from an effect is not in the page until the
3202
3293
  script runs; give it to `renderDocument`'s `htmlAttributes`.
3203
3294
 
3204
- An app holds this with a check: draw the page, open it in a DOM with the real
3295
+ An app guards this with a check: draw the page, open it in a DOM with the real
3205
3296
  wire and target, and assert React said nothing (atrium's and lyra's `ssr-check`).
3206
3297
 
3207
3298
  ## `@niscorp/moss/terminal/vue`
@@ -3223,7 +3314,7 @@ Requires the optional `vue` peer.
3223
3314
  - `TerminalSlotWrapper` — a Vue component wrapping each action instance at
3224
3315
  the `ActionSlot` boundary, handed `{ canvasId, instanceId, definitionId }`
3225
3316
  as props (`TerminalSlotWrapperProps`) and the content as its default slot.
3226
- - **Adoption**, as the react target: a root that holds server-drawn elements,
3317
+ - **Adoption**, as the react target: a root that contains server-drawn elements,
3227
3318
  on a wire with a frame, is mounted with `createSSRApp` and adopted.
3228
3319
 
3229
3320
  ### `@niscorp/moss/terminal/vue/server`