@niscorp/moss 0.5.0 → 0.7.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 (57) hide show
  1. package/CHANGELOG.md +111 -0
  2. package/DESIGN.md +77 -40
  3. package/DOCS.md +639 -81
  4. package/README.md +2 -2
  5. package/dist/{chunk-JYBHJDT7.cjs → chunk-C2DNDIQX.cjs} +5 -4
  6. package/dist/chunk-C2DNDIQX.cjs.map +1 -0
  7. package/dist/{chunk-BZK37HR3.cjs → chunk-DSTHFSTO.cjs} +1996 -1336
  8. package/dist/chunk-DSTHFSTO.cjs.map +1 -0
  9. package/dist/chunk-F45SFR7W.cjs +903 -0
  10. package/dist/chunk-F45SFR7W.cjs.map +1 -0
  11. package/dist/{chunk-PCPQMC7A.js → chunk-IMZZB4JE.js} +5 -4
  12. package/dist/chunk-IMZZB4JE.js.map +1 -0
  13. package/dist/{chunk-BQRPR2F7.js → chunk-MTC46PGQ.js} +1979 -1317
  14. package/dist/chunk-MTC46PGQ.js.map +1 -0
  15. package/dist/chunk-MYGVHWS5.js +870 -0
  16. package/dist/chunk-MYGVHWS5.js.map +1 -0
  17. package/dist/{chunk-FTZ6NFKZ.js → chunk-X2Q546EB.js} +3 -3
  18. package/dist/{chunk-FTZ6NFKZ.js.map → chunk-X2Q546EB.js.map} +1 -1
  19. package/dist/{chunk-5U2ZZUI5.cjs → chunk-Z2VA6AOE.cjs} +5 -5
  20. package/dist/{chunk-5U2ZZUI5.cjs.map → chunk-Z2VA6AOE.cjs.map} +1 -1
  21. package/dist/document-AbQUbQaP.d.ts +381 -0
  22. package/dist/document-wHHxIXJz.d.cts +381 -0
  23. package/dist/{index-BuDuOSyx.d.cts → index-Dml1klpZ.d.cts} +5 -1
  24. package/dist/{index-BuDuOSyx.d.ts → index-Dml1klpZ.d.ts} +5 -1
  25. package/dist/index.cjs +17 -17
  26. package/dist/index.d.cts +7 -9
  27. package/dist/index.d.ts +7 -9
  28. package/dist/index.js +3 -3
  29. package/dist/integrations.cjs +3 -3
  30. package/dist/integrations.d.cts +1 -1
  31. package/dist/integrations.d.ts +1 -1
  32. package/dist/integrations.js +1 -1
  33. package/dist/node.cjs +8 -8
  34. package/dist/node.d.cts +3 -4
  35. package/dist/node.d.ts +3 -4
  36. package/dist/node.js +4 -4
  37. package/dist/tide.d.cts +1 -1
  38. package/dist/tide.d.ts +1 -1
  39. package/dist/unverified.cjs +3 -3
  40. package/dist/unverified.js +2 -2
  41. package/dist/vite.cjs +9 -9
  42. package/dist/vite.d.cts +6 -1
  43. package/dist/vite.d.ts +6 -1
  44. package/dist/vite.js +4 -4
  45. package/package.json +13 -13
  46. package/dist/app-BoVB0_0j.d.ts +0 -143
  47. package/dist/app-Cc8VnOz8.d.cts +0 -143
  48. package/dist/chunk-BQRPR2F7.js.map +0 -1
  49. package/dist/chunk-BZK37HR3.cjs.map +0 -1
  50. package/dist/chunk-FTFME3HS.cjs +0 -383
  51. package/dist/chunk-FTFME3HS.cjs.map +0 -1
  52. package/dist/chunk-JYBHJDT7.cjs.map +0 -1
  53. package/dist/chunk-PCPQMC7A.js.map +0 -1
  54. package/dist/chunk-ZWB6QDGF.js +0 -374
  55. package/dist/chunk-ZWB6QDGF.js.map +0 -1
  56. package/dist/document-CU3muGbz.d.cts +0 -169
  57. package/dist/document-UFbAd-Ka.d.ts +0 -169
package/DOCS.md CHANGED
@@ -54,7 +54,7 @@ type NiscApp = {
54
54
  actions: Record<string, ActionDefinition>; // the app's actions
55
55
  layouts?: Record<string, LayoutVariant>; // ring 2: variant id → { action, layout }
56
56
  behaviors?: ScopeBehaviors; // row-level scope semantics, per table or per profile
57
- entries?: readonly (SeedEntry | SeedMutation)[]; // the prewarmed API surface
57
+ entries?: readonly (SeedEntry | SeedMutation)[]; // the API surface: the reads and writes the app serves
58
58
  resources?: Record<string, readonly string[] | { entities: readonly string[] }>;
59
59
  shell?: ShellManifest; // the server shell, as data — THE APP
60
60
  pages?: Record<string, PageManifest>; // what is drawn at a path and kept by nothing
@@ -64,7 +64,7 @@ type NiscApp = {
64
64
  identity?: { as?: string; resolve: (principal, read) => Promise<IdentityRecord> };
65
65
  phrases?: (session) => Phrasebook | undefined | Promise<Phrasebook | undefined>;
66
66
  phraseKeys?: PhraseKeys;
67
- functions?: (session: FunctionSession) => Record<string, FunctionHandler>;
67
+ functions?: (session: FunctionSession) => readonly FunctionDefinition[] | Record<string, FunctionHandler>;
68
68
  onSession?: (session: FunctionSession) => void;
69
69
  runs?: RunSink;
70
70
  reactions?: readonly { table; op?; run }[]; // see "Reacting to writes"
@@ -94,14 +94,53 @@ Every field is an artifact (authored data) except the code seams — `scope`,
94
94
  session and cached by moss (bounded by `runtime.identityMax` /
95
95
  `identityIdleMs`, re-resolved every `sessionRevalidateMs`). Returns an
96
96
  `IdentityRecord`: `{ roles, scope, installed?, tag? }`. `read(fingerprint,
97
- scope)` executes a seeded entry through moss's engine, replay-only, under
97
+ scope)` executes an entry the app serves through moss's engine, replay-only, under
98
98
  the policy of the charter role `identity.as` names (it throws when `as` is
99
99
  unset). Moss never reads inside the record's `scope`. Absent, `assignments`
100
100
  and `scope` answer, and every registered integration is live for everybody.
101
- - `functions(session)` — the handlers behind `fn:` endpoints. Called once for
102
- each shell that is built: the app's, a page's, and the one a reset builds.
103
- Like `onSession`, it runs before the shell finishes building, so it must
104
- not touch `session.shell` synchronously.
101
+ - `functions(session)` — the functions behind `fn:` endpoints. Called once
102
+ for each shell that is built: the app's, a page's, and the one a reset
103
+ builds. Like `onSession`, it runs before the shell finishes building, so it
104
+ must not touch `session.shell` synchronously. It returns a list of
105
+ `FunctionDefinition`, `{ id: string; description: string; execute:
106
+ FunctionHandler }`: `id` is what the charter's `functions` and an `fn:`
107
+ endpoint name, `execute` is what an `fn:` endpoint calls, `(data, signal) =>
108
+ Promise<unknown>`, and `description` says what it does and what to send, for
109
+ the model that writes a call to it (`session.functions()` lists it). Two
110
+ under one id are refused when a shell is built: `moss: functions(session)
111
+ returned "auth.leave" twice.` A map of handlers by id still works and is
112
+ deprecated. The first shell a process builds says once what to change, read
113
+ off what that first session's `functions(session)` returned: `[moss]
114
+ functions(session) returned a map of handlers, which is deprecated: return a
115
+ list of { id, description, execute }.`, or `[moss] functions with no
116
+ description: auth.leave. Give each a description.` An empty description
117
+ counts as none, and a function given by a map has none. **A shell holds only the functions
118
+ its principal's roles grant**, in the charter's `functions` part (names or
119
+ globs, with `extends` and `deny`, as `actions`): a role with none may call
120
+ none, and an `fn:` endpoint to one it does not grant fails when it is called.
121
+ What a living shell holds follows the roles an adopt answers, as its actions
122
+ do.
123
+ - **The boot is refused** where somebody holds an action that calls a
124
+ function their roles do not grant. It reads the `fn:` endpoints of the
125
+ actions held by each role on its own, each combination `wearable` or
126
+ `assignments` lists, and `public`, and of the fragments the shells ship,
127
+ and lists every call that is missing: `"member" hold "chrome.topbar",
128
+ which calls "auth.leave": their functions do not grant it`. A name with a
129
+ template in it (`fn: '{{$.saveFn}}'`) is worked out when it is called, and
130
+ the shell's map decides then.
131
+ - **`functions: ['*']`** grants every function, as an app had before this
132
+ part existed. The boot says so for each role that has it: `role "member"
133
+ allows every function ('*'): the generated actions of the people who hold
134
+ it, or a role that extends it, may call any it does not deny`. Grant each
135
+ role the functions it calls.
136
+ - **A grant that names no function** is said at the first shell a process
137
+ builds, when the names of the app's functions are known, with the
138
+ charter's own checks: `[moss] charter: role "member" allows "notes.ad"
139
+ (functions) which matches nothing`, a deny that matches nothing, and a
140
+ function no role grants. They are read against the names that shell's
141
+ `functions(session)` returned: an app whose functions differ by who the
142
+ session is for may see a grant reported that another session's names
143
+ would match.
105
144
  - `onSession(session)` — called once per living app shell, for session code
106
145
  that is not an endpoint (an observer, a roster). It runs before the shell
107
146
  finishes building, so it must not touch `session.shell` synchronously. Its
@@ -129,8 +168,9 @@ Every field is an artifact (authored data) except the code seams — `scope`,
129
168
 
130
169
  A `LayoutVariant` is `{ action: string; layout: LayoutNode }` — ring 2: the
131
170
  charter's `layouts` section selects who is granted which variant id, and moss
132
- substitutes the granted variant's layout onto the definition at shell build. The
133
- base is the floor; variants enrich upward as grants. A role, or a combination
171
+ puts the granted variant's layout where that action's layout is kept in the
172
+ shell ("Where an action's layout is kept", under `createServer`). The base is
173
+ the floor; variants enrich upward as grants. A role, or a combination
134
174
  of roles somebody may wear, that holds two variants of one action refuses the
135
175
  boot, and so does a variant of an action the app does not have.
136
176
 
@@ -140,7 +180,7 @@ boot, and so does a variant of an action the app does not have.
140
180
  type ShellManifest = {
141
181
  canvases: ShellCanvas[]; // a canvas's `initial` may be a CANDIDATE list
142
182
  layout?: LayoutNode; // the frame — CanvasSlot markers, served verbatim
143
- layoutStore?: Record<string, LayoutNode>; // what a `{ ref: id }` in the frame resolves to at boot
183
+ layoutStore?: Record<string, LayoutNode>; // what a `{ ref: id }` in the frame resolves to at boot; no name is `frame` or begins with `action/` or `canvas/`
144
184
  fragments?: Record<string, ActionFragment>;
145
185
  inputs?: (session: { principal, actions, roles, identity, wire }) =>
146
186
  Record<string, Record<string, unknown>> | Promise<…>;
@@ -154,7 +194,9 @@ Two per-principal boot hooks, both of which may be async and are handed the
154
194
  session's governed `wire`. `inputs` derives boot **data** (nav flags, user
155
195
  chips), merged over each canvas's static seed. `seeds` derives boot
156
196
  **instances**: by canvas id, the actions to push, in order, ring-1-filtered
157
- like every other mount — a seed the principal is not granted does not mount.
197
+ like every other mount — a seed for an action the shell is not built with
198
+ does not mount. A shell is built with what its principal is granted and what
199
+ they generated.
158
200
  A `CanvasSeed` is an action id or `{ action, input?, with? }`, and a
159
201
  `ShellCanvas` is nova's canvas config with `initial` widened to one seed or a
160
202
  list of candidates. Neither type is exported by name: `ShellManifest['canvases']`
@@ -243,11 +285,13 @@ What the manifest's in-process functions close over:
243
285
 
244
286
  ```typescript
245
287
  type FunctionSession = {
246
- shell: Shell; // the session's living, durable shell (a getter — a reset replaces it); nine members throw
288
+ shell: Shell; // the session's living, durable shell (a getter — a reset replaces it); eight members throw
289
+ artifacts: SessionArtifacts; // what this principal saved, and saving: `session.artifacts`, below
290
+ draft: SessionDraft; // what is being generated in this one shell, before it is saved: `session.draft`, below
247
291
  principal: string | null;
248
292
  roles: readonly string[];
249
293
  identity: Record<string, unknown>; // the scope half of the resolved identity
250
- actions: readonly string[]; // the session's granted action ids, installs filtered
294
+ actions: readonly string[]; // the ids of the actions the shell was built with: what the roles are granted, installs filtered, and what the principal generated
251
295
  wire: FetchFn; // the server's own surfaces, as this session
252
296
  grant: (token: string) => void; // session GRANT (login): send it down, reconnect
253
297
  revoke: () => Promise<void>; // session REVOKE (sign-out): close 4403, evict
@@ -256,6 +300,7 @@ type FunctionSession = {
256
300
  asked: { intent: string; shape: unknown; context?: Record<string, unknown> },
257
301
  ) => Promise<QueryResponse>;
258
302
  recordRun: (run: Omit<RunRecord, 'at' | 'principal' | 'shellId'>) => void;
303
+ functions: () => readonly { id: string; description?: string }[]; // the app's functions this session may call, what its roles' `functions` grant
259
304
  };
260
305
  ```
261
306
 
@@ -264,10 +309,13 @@ deletes every session the principal has (`revokeAllFor`). It need not be
264
309
  awaited: a failure is logged. `recordRun` is a
265
310
  no-op when the manifest declares no `runs` sink.
266
311
 
267
- **`shell` refuses the nine members that change what a shell is made of**:
268
- `registerAction`, `removeAction`, `registerFragment`, `addCanvas`,
312
+ **`shell` refuses the eight members that change what a shell is made of**:
313
+ `registerAction`, `removeAction`, `addCanvas`,
269
314
  `removeCanvas`, `setCanvasLayout`, `setLayout`, `setPhrases` and `dispose`
270
- throw. An action, a fragment, a canvas, a layout and the phrases reach a shell
315
+ throw, and so do `set` and `delete` on its `layoutStore`, which is to read. A
316
+ definition read off it (`shell.getRuntime(id).definition`) is the action as it
317
+ was written, with the layout it is drawn with now in place: where moss keeps a
318
+ layout does not show. An action, a fragment, a canvas, a layout and the phrases reach a shell
271
319
  through moss, which verifies them and decides who holds them; added on the
272
320
  shell directly they are not verified, are in nobody's catalog and are gone
273
321
  when the shell is rebuilt. Everything else (reads, navigation, `dispatch`,
@@ -320,6 +368,376 @@ const runs: RunSink = (record) => {
320
368
  };
321
369
  ```
322
370
 
371
+ #### `session.artifacts` — what the session's principal saved
372
+
373
+ What somebody or a model generated while the app runs is kept by moss, as a
374
+ version, in two tables of its own. Four kinds are kept: a layout (for an
375
+ action, or for the app's own shell), an action, a fragment, and a read vex
376
+ wrote. A session saves for its own principal. A layout for everybody is
377
+ published from the server and never from a session (`server.defaults`, under
378
+ `MossServer` below). Not built yet: a layout of a page's shell, and an action,
379
+ a fragment or a read for everybody.
380
+
381
+ ```typescript
382
+ type SessionArtifacts = {
383
+ save: (artifacts: readonly { kind: ArtifactKind; id?: string; body: unknown }[]) => Promise<{ save: string; artifacts: readonly { kind: ArtifactKind; id: string }[] }>;
384
+ list: (kind?: ArtifactKind) => Promise<readonly ArtifactVersion[]>;
385
+ history: (kind: ArtifactKind, id: string) => Promise<readonly ArtifactVersion[]>;
386
+ restore: (kind: ArtifactKind, id: string, save: string) => Promise<{ save: string }>;
387
+ reset: (kind: ArtifactKind, id: string) => Promise<{ save: string }>;
388
+ };
389
+
390
+ type ArtifactKind = 'layout' | 'action' | 'fragment' | 'read';
391
+
392
+ type ArtifactVersion = {
393
+ kind: ArtifactKind;
394
+ id: string;
395
+ save: string; // the save this version belongs to
396
+ createdAt: string; // ISO
397
+ copiedFrom: string | null; // the save it is a copy of, where it is one
398
+ body: unknown; // null: this version says none is in force
399
+ };
400
+ ```
401
+
402
+ The three types are reached as `FunctionSession['artifacts']`; none is
403
+ exported by a name of its own.
404
+
405
+ **A layout's body** is `{ ref, layout, use? }`. `ref` is the name the layout
406
+ of the action it is for is kept under in the shell's layout store,
407
+ `action/<the action's id>`, or, for a layout of the app's own shell (further
408
+ down), `frame` or `canvas/<a canvas's id>`. `layout` is a nova layout.
409
+
410
+ ```typescript
411
+ functions: (session) => [
412
+ {
413
+ id: 'layout.keep',
414
+ description: 'Keeps a layout for the deals list as the person’s own. Send { layout }.',
415
+ execute: async ({ layout }) => session.artifacts.save([{ kind: 'layout', body: { ref: 'action/deals.list', layout, use: true } }]),
416
+ },
417
+ ],
418
+ ```
419
+
420
+ **A generated action's body** is a nova action definition without an `id`,
421
+ and **a generated fragment's** a nova fragment without one. Moss gives the id:
422
+ `generated.` and a uuid, which `save` answers. A body that names another id is
423
+ refused, and a save that names the `id` of one of the principal's own is a new
424
+ version of it.
425
+
426
+ ```typescript
427
+ functions: (session) => [
428
+ {
429
+ id: 'screen.keep',
430
+ description: 'Keeps an action the person generated. Send { action }.',
431
+ execute: async ({ action }) => session.artifacts.save([{ kind: 'action', body: action }]),
432
+ },
433
+ ],
434
+ ```
435
+
436
+ - **It is its owner's and nobody else's.** It is among the actions (or the
437
+ fragments) their shells are built with, its layout is in their layout store
438
+ under `action/<its id>`, and a layout of their own may be saved for it as
439
+ for a shipped action. No charter grant is asked about it, and it is in no
440
+ catalog: `/catalog`, the socket's hello and `server.catalogOf` answer what
441
+ the charter grants. What somebody generated is listed by
442
+ `session.artifacts.list('action')`.
443
+ - **It reaches its owner's open shells a moment after the save answers**, as a
444
+ saved layout does, and not before: a function that saves an action and
445
+ opens it in the same call finds it not there yet. One that is to be seen at
446
+ once is put into the draft (`session.draft`, below), which answers when the
447
+ shell has it.
448
+ - **What it defines replays reads, and calls the functions its owner's roles
449
+ grant.** An `fn:` endpoint names a function its owner's roles grant in the
450
+ charter's `functions` (`session.functions()` lists them with their
451
+ descriptions, for the model that writes it); one they do not grant is refused. Every other endpoint is a
452
+ `POST` to the app's vex route (`/api/vex`, or `/api/<resource>/vex`) whose
453
+ `request` names one fingerprint, written out. That fingerprint is a read the app ships or
454
+ was handed (`replaceEntries`) that its owner's policy may replay, or a read
455
+ vex wrote that its owner saved (below). Refused, with a sentence: a function
456
+ its owner's roles do not grant, a write, a read its owner may not replay, any other fingerprint (a
457
+ query a model wrote that nobody saved, `fp_…`, among them), a fingerprint
458
+ that is computed, an address with a template in it, and every other
459
+ address.
460
+ - **Moss checks the artifact, and what it is combined with is nova's.** Once
461
+ it is in a shell it is an action, or a fragment, like any other. A message
462
+ it emits reaches every action open in its owner's shell. The steps of a
463
+ fragment run inside the action it is wrapped around, with that action's
464
+ endpoints, and where both define an endpoint of one name the action's is
465
+ the one called. What an assistant is told it may generate is the app's to
466
+ decide: it writes the prompt, and its own function calls `save`.
467
+ - **A generated action opens the actions its owner holds**, their own
468
+ generated ones among them, and no other: nova's audit is run on it with
469
+ those as its catalog, and what it finds refuses the save, as it does for a
470
+ saved layout. So do a component no shell of the app has, and a layout that
471
+ names a ref moss keeps a layout under (`action/…`, `canvas/…`, `frame`). A fragment is held to its schema, its id, its
472
+ layout and its endpoints, and not to that audit, which reads a whole action:
473
+ a step of a fragment that opens an action its owner does not hold is refused
474
+ by nova when it runs, because that action is not in their shell.
475
+ - **It is checked when it is saved and again when a shell is built.** One
476
+ that no longer passes (its owner lost the grant its read needs, say) is left
477
+ out of every shell built from then on, with a line (`[moss] the action "…"
478
+ of … is left out: …`).
479
+ - **A reset takes it out of its owner's shells**, and the layouts they saved
480
+ for it are not drawn while it is out: a layout whose action its holder has
481
+ no longer is not loaded. `list('layout')` still lists them. Going back to a
482
+ version of the action brings both back.
483
+ - **No action an app ships or hands over, and no fragment of a shell, has an
484
+ id beginning with `generated.`**: a boot, `replaceActions` and the
485
+ manifest's parse refuse one. Nor is an action under the id of a fragment a
486
+ shell ships, since a nova shell keeps both in one registry: a boot and
487
+ `replaceActions` refuse that too.
488
+ - A fragment that left, by a reset or because it no longer passes, is taken
489
+ out of a shell that is already open, as an action is. What was opened with
490
+ it stays as it was composed.
491
+
492
+ **Every call is for the session's principal, and no call can be for anybody
493
+ else.** No argument names whose rows are meant. Moss runs its own entries over
494
+ the two tables as the caller, with the scope values the routes serve that
495
+ caller under, and under one row rule: a caller reads and writes only the rows
496
+ whose `principal` is their `userId`, and a row they insert or update carries
497
+ it, whatever the statement says. Vex keeps that rule on every read and every
498
+ write; moss's code passes no principal. **Who may save at all is the charter's**: a function that calls
499
+ `session.artifacts.save` is the app's, an action calls it, and the charter
500
+ says who holds that action. A session nobody is signed in to saves nothing
501
+ and lists nothing: everybody who is not signed in shares one `userId`.
502
+
503
+ - The layout is the principal's and nobody else's. Moss gives it its id, a
504
+ uuid, and answers it; a save that names that `id` is a new version of the
505
+ same layout, and an id that is not one of theirs is refused.
506
+ - Several of somebody's own may be for one ref: the one whose body says
507
+ `use: true` is the one their shells draw, and marking one takes the mark off
508
+ their others for that ref in the same save. One that is not marked is kept
509
+ and not drawn.
510
+ - Their open screens follow at once, with what was typed into them kept; in a
511
+ deployment of several processes the others are told over the fabric
512
+ (`adopt`, under "Many processes").
513
+
514
+ **Whose a row is, is the caller's `userId`**: the scope value moss supplies
515
+ for every caller, which an app's `scope` can set. An app that gives a person one account for each tenant
516
+ keeps their layouts apart by tenant. An app where one account spans tenants
517
+ has that person's layouts follow them into each. In neither does anybody read
518
+ or write a row of another account.
519
+
520
+ **A read vex wrote** for a request (`session.answerIntent`) is saved under
521
+ the fingerprint vex gave it, with no body:
522
+ `session.artifacts.save([{ kind: 'read', id: 'fp_…' }])`. Moss takes the entry
523
+ from vex's own table and keeps it as written: the query, the Prism config of
524
+ its mapping, its shape and its intent.
525
+
526
+ - **It is answered to the person who saved it and to nobody else.** When one
527
+ of their requests replays that fingerprint, moss answers it, compiled, from
528
+ their rows. Anybody else who sends the fingerprint gets what vex's own table
529
+ still holds under it, as for any query vex wrote and nobody saved, and a
530
+ caller nobody is signed in for is never answered a saved read.
531
+ - **It is a query vex wrote, and is held as one.** Vex's limits apply to it
532
+ (`maxLimit`), as they do not to an entry the app ships. A request that names
533
+ its fingerprint with an intent and a shape is written anew by vex into its
534
+ own table; the saved read is what its owner is answered until they save the
535
+ new one.
536
+ - **It survives a schema change that does not touch what it reads.** Vex drops
537
+ the copy in its own table at the first replay after any schema change; the
538
+ saved one is not dropped. One whose query no longer runs is refused by vex
539
+ when it is replayed, and is left out of what is in force with a line
540
+ (`[moss] the read "fp_…" of … is left out: …`), with any generated action of
541
+ its owner that replays it.
542
+ - **Its owner's policy applies when it is replayed.** A generated action over a
543
+ read whose tables its owner can no longer read stays in force, and its
544
+ replay is refused, where one over such an entry the app ships is left out.
545
+ - **A generated action may replay a read its owner saved**, as it may an entry
546
+ the app ships that its owner may replay. A draft takes a read too, and an
547
+ action put into the same draft may replay it.
548
+ - **What is refused**, in a sentence: a read with no id, or with a body; one
549
+ under the fingerprint of an entry the app ships or was handed; one vex did
550
+ not write for a request; a write; one whose mapping vex kept no config for
551
+ (it was written before vex kept one: ask for it again); and one whose query
552
+ does not run against the schema.
553
+
554
+ **What a shell draws under an action's ref**, the first of these that there
555
+ is: the principal's own layout marked in use; the layout variant their roles
556
+ hold (`app.layouts`); the layout published for everybody that is marked in use
557
+ (`server.defaults`); the layout the build ships.
558
+
559
+ **What is refused**, at a save and at a restore, in a sentence, with nothing
560
+ written: a body that is not `{ ref, layout, use? }`; a `ref` nothing is kept
561
+ under for the principal (an action they do not hold, or one that is not in
562
+ force; an action with no layout of its own, or one that names a layout of the
563
+ store by its id; any name that is none of `action/<id>`, `frame` and
564
+ `canvas/<id>`); a component no shell of
565
+ the app has (and a prop its declared schema refuses, as for an integration's
566
+ layouts); a layout that names a ref moss keeps a layout under (`action/…`,
567
+ `canvas/…`, `frame`); and what nova's audit
568
+ (`auditAction`) finds of the action with the layout in place and does not find
569
+ of the action as it is built (a binding to a key the action has no data for,
570
+ a control the action listens on that the layout leaves out, a control no
571
+ trigger handles). The same is asked of every saved layout when a shell is
572
+ built, there against the components of that shell alone: one that does not
573
+ 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
574
+ its holder's store keeps nothing under any more (the action left, or they
575
+ hold it no longer) is not loaded and nothing is said.
576
+
577
+ **The layouts of the app's own shell** are saved with the same calls: its own
578
+ under `ref: 'frame'`, and a canvas's under `ref: 'canvas/<the canvas's id>'`.
579
+ `session.artifacts.save([{ kind: 'layout', body: { ref: 'frame', layout, use:
580
+ true } }])`.
581
+
582
+ - **They are the app's own shell's.** Under either name that shell draws the
583
+ first of these that there is: the principal's own marked in use, the one
584
+ published for everybody that is marked in use, the one the manifest
585
+ declares. A page draws the layouts its own manifest declares, whatever was
586
+ saved: an app that lets people save a frame has, in a page, a screen no
587
+ saved frame changes. A draft of a page's shell takes none.
588
+ - **A shell manifest with no `layout` has none to take the place of**, nor
589
+ has a canvas with no `actionLayout`, or with one that is the name of a
590
+ stored layout. A save for one is refused as for any ref nothing is kept
591
+ under.
592
+ - **What is refused**: a body that is not `{ ref, layout, use? }`, a component
593
+ the app's own shell has none for (and a prop its declared schema refuses),
594
+ and a layout that names a ref moss keeps a layout under. Nova's audit reads
595
+ an action, and is not asked of these. One that names a ref nothing is kept
596
+ under is saved, and nova draws its error box in that place, as it does in
597
+ an action's layout.
598
+ - **A frame may leave a canvas of the shell out.** That canvas stays the
599
+ shell's and is drawn nowhere: what is mounted on it runs unseen, and what an
600
+ action opens on it does not show. Moss does not refuse it. An app that wants
601
+ every canvas placed checks the layout in its own function before it saves.
602
+
603
+ **A canvas that only a layout's slot draws goes when the slot goes.** Nova
604
+ gives a shell a canvas when something is first pushed onto it, whether or not
605
+ its manifest declares it, and it is drawn where a layout has a canvas slot for
606
+ it (`{ component: 'CanvasSlot', props: { canvasId: 'notes' } }`). Moss reads
607
+ which canvases the layouts a shell is built from hold a slot for and its
608
+ manifest does not declare. Every layout counts (the frame, a canvas's, an
609
+ action's that the principal holds, a fragment's, one the app keeps in its
610
+ layout store), the build's and a saved or generated one alike. Once a layout
611
+ leaves force and no other holds a slot for such a canvas, an open shell loses
612
+ the canvas, with what is mounted on it. A slot whose `canvasId` is worked out
613
+ when it is drawn (`'$.c.id'`, a template) counts for none. Moss gives a shell
614
+ no canvas, and the canvases a manifest declares are never taken out. What is
615
+ pushed onto a canvas after its slot went is mounted and drawn nowhere, as on
616
+ any canvas no layout has a slot for.
617
+
618
+ **Moss changes and deletes no row.** `list` answers the latest version of each
619
+ of the principal's artifacts that has a body. `history` answers the versions
620
+ of one, the newest first (the newest 500). `restore` is a new save that holds
621
+ a copy of a version and says which (`copiedFrom`); it is checked as a save
622
+ is. `reset` is a new save whose version has no body: none of the principal's
623
+ is in force under that id, and what is under it is drawn again. A reset is a
624
+ version too, and can be gone back from. Two saves by one person at the same
625
+ moment can each leave a layout marked in use for one ref. The later one is
626
+ drawn. The next save that marks one for that ref, or takes the one in use out
627
+ (a reset, or a save of it without the mark), takes the mark off the rest.
628
+
629
+ The rows are in `artifact_saves` (one for each save) and `artifacts` (one for
630
+ each version a save holds), which migration `nisc.moss/5` makes. They are
631
+ read and written through three vex entries of moss's own that no route serves
632
+ (`src/artifactory/saves.ts`). What is in force for an artifact is its latest
633
+ version by `created_at`; every id moss gives is a uuid. A body is kept with
634
+ the grammar stamp it was written at and is brought to the grammars the server
635
+ runs when it is read. What somebody saved is asked of the rows once for each
636
+ shell that is built for them and once for each adopt; nothing of it is kept in
637
+ memory, so a save made in another process is theirs here at the next build
638
+ whether or not a fabric is set. The entries are loaded when the server boots,
639
+ and a boot that cannot load them fails. A row always has a principal: the two
640
+ `principal` columns refuse a null, so an app whose `scope` answers no `userId`
641
+ for somebody saves nothing for them.
642
+
643
+ **No caller's `userId` is `*`.** What is published for everybody is kept as
644
+ the rows of that one principal, under the same row rule, so a caller whose
645
+ `userId` were `*` would read and write what is published as their own. Moss
646
+ refuses one wherever it composes a caller's scope for vex: no shell is built
647
+ for them (`moss: a caller’s \`userId\` is "*", …`), `/api/vex` answers them
648
+ 500, and an intent a function asks for them is refused. An app's sign-in, or
649
+ its `scope`, answers another id. A scope that carries `artifactSavedBy` is
650
+ refused in the same places: who made a save is written from that value, and
651
+ it is moss's to say. (`server.executeAs` is the app's own code, and hands vex
652
+ the scope it is given.)
653
+
654
+ **The row rule is moss's, wherever a policy is compiled.** The two tables are
655
+ in the data a charter selects from, as every table is: no role reaches them
656
+ unless its charter grants them. A role that is granted them, by name or by a
657
+ wildcard (`*.read`), reads and writes its own rows there and nobody else's,
658
+ because the same rule is part of the policy `server.policyForRoles` answers.
659
+ An app does not say otherwise: `behaviors` that name either table refuse the
660
+ boot. (A policy an app compiles itself, from its charter and its own
661
+ `behaviors` and without the server, does not carry the rule.) Moss's own
662
+ entries only add rows. An app whose charter grants a role update or delete
663
+ on the two tables, and that ships an entry of its own to do it, lets that
664
+ role change or remove its own rows, and never another's. A save itself (a row
665
+ of `artifact_saves`) is moss's alone to make: who made it (`created_by`) is
666
+ written from a scope value no caller's scope carries (`artifactSavedBy`), so
667
+ an app's entry that inserts or updates one for a caller is refused (500,
668
+ `missing_scope`).
669
+
670
+ **A save is not told to `app.reactions`.** Moss's own entries tell the app's
671
+ engine which tables changed, so a read of the app's that follows them
672
+ refreshes, and tell no subscriber of the routes. The function that saved
673
+ knows that it did.
674
+
675
+ #### `session.draft` — what is being generated in this shell
676
+
677
+ What a person or a model is still working on is in the draft of the one shell
678
+ it is worked on in. It is shown there at once and saved nowhere: no other
679
+ shell has it, the person's own others included, and it is gone when the shell
680
+ is (a reset, an idle shell that was dropped, a restart).
681
+
682
+ ```typescript
683
+ type SessionDraft = {
684
+ put: (artifacts: readonly { kind: ArtifactKind; id?: string; body: unknown }[]) => Promise<{ step: number; artifacts: readonly { kind: ArtifactKind; id: string }[] }>;
685
+ list: () => readonly { kind: ArtifactKind; id: string; body: unknown }[];
686
+ remove: (kind: ArtifactKind, id: string) => Promise<{ step: number }>;
687
+ show: (step: number) => Promise<void>;
688
+ discard: () => Promise<void>;
689
+ save: () => Promise<{ save: string; artifacts: readonly { kind: ArtifactKind; id: string }[] }>;
690
+ };
691
+ ```
692
+
693
+ ```typescript
694
+ functions: (session) => [
695
+ {
696
+ id: 'screen.try',
697
+ description: 'Shows an action the person is trying out, without keeping it. Send { action }.',
698
+ execute: async ({ action }) => {
699
+ const put = await session.draft.put([{ kind: 'action', body: action }]);
700
+ session.shell.push('main', put.artifacts[0].id);
701
+ },
702
+ },
703
+ { id: 'screen.keep', description: 'Keeps what the person is trying out.', execute: async () => session.draft.save() },
704
+ ],
705
+ ```
706
+
707
+ - **`put` takes what `session.artifacts.save` takes and refuses what it
708
+ refuses**, with the same sentences. Each artifact is checked beside what is
709
+ in force for the principal with the draft laid over, so a layout may be for
710
+ an action that is itself in the draft. A draft is one shell's, so what is
711
+ put into it is held to the components of that shell, where a save is held to
712
+ those of any shell of the app. A new action or fragment gets its
713
+ `generated.` id here, and keeps it when the draft is saved. An `id` names
714
+ one in the draft, or one the principal saved: a new take of it, which stands
715
+ in for the saved one in this shell until the draft is saved or the take is
716
+ taken out. A put that marks a layout `use: true` takes the mark off the
717
+ draft's others for that ref, as a save does.
718
+ - **A put is in the shell when it answers.** The function that put an action
719
+ opens it on its next line. An open screen follows a drafted layout with what
720
+ was typed into it kept, as it follows a saved one. A put the shell could not
721
+ take rejects, and the draft is as it was.
722
+ - **What the shell draws**: what is in the draft, then what `session.artifacts`
723
+ would draw. A drafted layout marked `use: true` is drawn in place of a saved
724
+ one that is marked for the same ref.
725
+ - **`list`** answers what the draft holds, and **`remove`** takes one out of
726
+ it; what is under it is drawn again. **`discard`** empties it.
727
+ - **Each put or removal is a numbered step**, from 1. **`show(step)`** has the
728
+ shell show the draft as it was after that step, and `show(0)` none of it. A
729
+ put or a removal while an earlier step is shown goes on from that step: the
730
+ steps after it are dropped. The steps are the draft's and are saved nowhere.
731
+ - **`save`** is one save of what the draft holds, as the principal's own and
732
+ under the ids it had, checked once more. The draft is then empty and the
733
+ shell keeps what it shows. An empty draft is refused.
734
+ - **Calls on one draft are taken in turn**: each starts from the draft as the
735
+ one before it left it.
736
+ - A session nobody is signed in to has no draft, as it saves nothing. Every
737
+ call on the draft of a shell that was replaced since is refused (`moss: this
738
+ session’s shell is gone, and its draft with it.`), `list` and `save` among
739
+ them: what was in it is saved by nobody.
740
+
323
741
  ### The environment
324
742
 
325
743
  #### `NiscRuntime`
@@ -495,7 +913,8 @@ await revokeAllFor(runtime.pool, 'usr_ada');
495
913
 
496
914
  **Tables go through a ledger.** moss creates no table on its own: its tables are
497
915
  [strata](../strata/README.md) sequences — `MOSS_SEQUENCE` (`nisc.moss`:
498
- integrations, their actions, the generation pointer) and the sessions table's
916
+ integrations, their actions, the generation pointer, the two tables of what
917
+ was saved) and the sessions table's
499
918
  (`nisc.moss.sessions`; the sequence itself is not exported) — and
500
919
  `createServer` applies them with the vex cache's sequence in
501
920
  one ledgered run before introspection: once, recorded in `strata_ledger`, and
@@ -531,8 +950,12 @@ reason as `fingerprint: why` — and nothing was applied. It asks on every run,
531
950
  so a release that changes an entry and no table is checked too.
532
951
 
533
952
  One kind of entry is said and not refused: one that already did not fit before
534
- the run and that the database already holds seeded exactly as it is. That is an
535
- old fault, not this run's. A new or changed entry gets no such pass.
953
+ the run and that the cache table already holds a copy of, exactly as it is. That
954
+ is an old fault, not this run's. A new or changed entry gets no such pass. A
955
+ copy is there where a release before 0.6.0 wrote it, or where the app writes
956
+ one itself for an engine of its own (`seedCache`). Moss writes none since
957
+ 0.6.0: it keeps an app's entries in memory, so in a database only moss writes
958
+ to, an entry first shipped since then has no copy and gets no pass either.
536
959
 
537
960
  What it answers is strata's `{ applied, plan }` plus `removed` (tables and
538
961
  columns the run takes away), `retyped` (columns whose type it changes, as
@@ -594,27 +1017,89 @@ does nothing. Returns a Hono app extended with the `MossServer` members below.
594
1017
  order: the manifest is read and frozen; who a token is is resolved
595
1018
  (`runtime.session`; unset, the boot is refused here, before a table exists);
596
1019
  the tables are migrated and the data module stands; the running manifest is
597
- created, which is the boot check, and the entries it holds are seeded where
598
- vex replays from; identity; the server's own routes (the
1020
+ created, which is the boot check, and the data module is told to ask it for an
1021
+ entry (it compiles the ones it holds, and one vex cannot run refuses the boot);
1022
+ identity; the server's own routes (the
599
1023
  authentication, `/catalog`, vex); the shell hosts, the app's and each page's;
600
1024
  what crosses processes; the features, each started with seams made for it; the
601
1025
  operator prefix; the app's reactions hear a write; the generation pointer is
602
1026
  watched; the socket.
603
1027
  A step that refuses is the boot's refusal.
604
1028
 
605
- **Where the app's entries are held.** In two places while a server runs. The
606
- running manifest holds the list the app shipped and is their source: the boot
607
- check reads it, and a shell is told of the reads on its screens from it. That
608
- list is copied once, at boot, into the cache vex replays from (`vex_cache`,
609
- or the cache `runtime.cache` hands over). The cache is what runs them: a
610
- request's fingerprint, and the list of fingerprints a feature or the operator
611
- is told of, resolve there, and the manifest is not asked. The cache also
612
- holds what the list does not: a query `session.answerIntent` wrote while the
613
- app runs, and any row it held before this boot (seeding writes each entry of
614
- the list and takes none out, so in a database that outlives the process an
615
- entry the app no longer ships is still there, protected). As in 0.4.0. Which
616
- of the two decides what a fingerprint resolves to is what the next piece of
617
- work changes, and nothing here has moved it.
1029
+ **Where the app's entries are held.** In the running manifest
1030
+ (`src/artifactory/`), in memory, and nowhere else. It holds the entries the
1031
+ app shipped and each set handed over with `server.replaceEntries`, compiled as
1032
+ vex replays them, and it is what the engine asks first: a request's
1033
+ fingerprint, and the list of fingerprints a feature or the operator is told
1034
+ of, resolve there. So what a fingerprint resolves to is what this process's
1035
+ app ships, read from the build at every boot.
1036
+
1037
+ What the running manifest does not hold is asked of the cache table
1038
+ (`vex_cache`, or the cache `runtime.cache` hands over). That table keeps what
1039
+ vex wrote itself while the app runs: a query `session.answerIntent` wrote.
1040
+ **Nothing is copied into it at boot, and a row in it that no request wrote is
1041
+ not replayed.** Vex gives a query it writes the hash of the request it was
1042
+ written for, and that is what moss asks of a row before it answers from it. A
1043
+ release before 0.6.0 copied every entry of the app there at each boot, and a
1044
+ database that ran one still holds those rows, which carry no such hash. Moss
1045
+ answers from none of them and deletes none: an entry the app no longer ships
1046
+ is refused (`cache_miss`). Two things an app may have leaned on are gone with
1047
+ the copy:
1048
+
1049
+ - **An engine of the app's own over the same table** finds no entry of the app
1050
+ there. It is given the entries it replays by the app
1051
+ (`seedCache(cache, entries)`, as the server used to do for it).
1052
+ - **A row the app writes into the table itself**, to serve an entry that is
1053
+ not in its manifest, is not replayed. `server.replaceEntries` is the way an
1054
+ entry reaches a running server.
1055
+
1056
+ **Where an action's layout is kept.** In the shell's layout store, under
1057
+ `action/<id>`. An app goes on writing an action's layout in its definition;
1058
+ where a shell is built, moss moves it into the store, and the definition the
1059
+ shell is handed names it by `{ ref: 'action/<id>' }`. A layout variant the
1060
+ person's roles hold is what the store holds under that name instead. An action
1061
+ with no layout, or one whose `layout` is already the name of a stored layout,
1062
+ is handed over as it is. Three things follow:
1063
+
1064
+ - **A layout that changes reaches a screen that is already open**, with the
1065
+ data on it kept. Until 0.6.0 an open instance kept the layout it was opened
1066
+ with, and only one opened afterwards showed the new one. What an open
1067
+ instance still keeps is the rest of its definition: its data's shape, its
1068
+ endpoints and its triggers.
1069
+ - **Code that reads an action's definition off its session's shell**
1070
+ (`session.shell.getRuntime(id).definition`) finds it as it was written, with
1071
+ the layout in place: the one the store holds now, so a variant or a change
1072
+ shows. `server.actions()` answers the definitions as they were written too.
1073
+ Only the whole shell (`unverifiedShell(session)`), which is nova's own,
1074
+ shows `{ ref }`; there the layout is `shell.layoutStore.get('action/<id>')`.
1075
+ - **`action/` belongs to moss in a layout store.** A manifest whose
1076
+ `layoutStore`, the app's shell's or a page's, declares a name beginning with
1077
+ it refuses the boot (`shell.layoutStore.action/home: a name beginning with
1078
+ "action/" is where the layout of that action is kept`). So does an action's
1079
+ layout, or a layout variant, that names one by `{ ref }` or as its layout's
1080
+ name, at boot and when a set is handed over (`"panel" names the layout
1081
+ "action/panel": …`): a layout cannot be drawn inside itself, and an action
1082
+ cannot draw another's.
1083
+ - **The layout of an action that leaves a shell leaves its store.**
1084
+
1085
+ **The shell's own layout and a canvas's are kept there too**, under `frame`
1086
+ and `canvas/<the canvas's id>`. An app goes on writing `layout` in its shell
1087
+ manifest and `actionLayout` in a canvas; where a shell is built, moss moves
1088
+ each into the store and the shell draws it by that name. A shell manifest with
1089
+ no `layout` has no `frame` in its store and is drawn with nova's own, and a
1090
+ canvas whose `actionLayout` is already the name of a stored layout, or that
1091
+ has none, is handed over as it is. So is a `layout` that is the name of a
1092
+ stored layout: the shell draws by that name, and nothing is kept under
1093
+ `frame`. Both names belong to moss in a layout
1094
+ store, as `action/` does: a manifest whose `layoutStore`, the app's shell's or
1095
+ a page's, declares one refuses the boot (`shell.layoutStore.frame: "frame" is
1096
+ where the layout of the shell is kept`, `shell.layoutStore.canvas/main: a name
1097
+ beginning with "canvas/" is where the layout of that canvas is kept`). So does
1098
+ an action's layout, or a layout variant, that names one by `{ ref }` or as its
1099
+ layout's name (`"panel" names the layout "frame": …`). Only a node that is
1100
+ `{ ref }` and nothing else names a layout: a `ref` a component carries, on its
1101
+ node or in its props, names none. Both can be saved for the app's own shell
1102
+ (`session.artifacts`).
618
1103
 
619
1104
  **The manifest is read first.** Before a table is created or a row is read,
620
1105
  `createServer` parses the manifest with a schema, and a manifest that does not
@@ -645,11 +1130,12 @@ zod schema handed over as a component's `propsSchema`), is not frozen and not
645
1130
  looked inside. An object the app shares between its manifest and its own code
646
1131
  is frozen for both.
647
1132
 
648
- What an app consists of changes in one way while a server runs: a set of
649
- actions is handed over with `server.replaceActions(source, actions)`, which
650
- verifies before it switches. A charter, a layout variant, an entry, a behavior
651
- and the shell do not change under a running server; they change in the manifest
652
- the next server is created with.
1133
+ What an app consists of changes in two ways while a server runs: a set of
1134
+ actions is handed over with `server.replaceActions(source, actions)`, and a set
1135
+ of entries with `server.replaceEntries(source, entries)`. Each verifies before
1136
+ it switches. A charter, a layout variant, a behavior and the shell do not
1137
+ change under a running server; they change in the manifest the next server is
1138
+ created with.
653
1139
 
654
1140
  What the server answers over HTTP:
655
1141
 
@@ -685,8 +1171,8 @@ and does not throw.
685
1171
  #### `MossServer`
686
1172
 
687
1173
  `Hono<Env> & { socket; shells?: ShellHost; principalOf; page; pages;
688
- refresh; replaceActions; actions; catalogOf;
689
- policyForRoles; charterReport; invalidateIdentity; invalidateTenant; identity;
1174
+ refresh; replaceActions; replaceEntries; actions; defaults; catalogOf;
1175
+ policyForRoles; charterReport; invalidateIdentity; invalidateTag; identity;
690
1176
  executeAs; nudge; close; identities? }`.
691
1177
  It's a Hono app — mount it, extend it, or hand it to a listener.
692
1178
 
@@ -737,11 +1223,65 @@ It's a Hono app — mount it, extend it, or hand it to a listener.
737
1223
  keeps a set of its own under its own name (`'integrations'` is the
738
1224
  integrations feature's, read from its tables) and is the only one that
739
1225
  replaces it: handing a set over under a feature's name throws (`moss: the
740
- set of actions "integrations" is the feature "integrations"'s, and only its
741
- owner replaces it. …`).
1226
+ set "integrations" is the feature "integrations"'s, and only its owner
1227
+ replaces it. …`).
1228
+ - `replaceEntries(source, entries): Promise<void>` — hand over a set of
1229
+ entries that arrived while the app runs (an app that loads its reads and
1230
+ writes from its own tables), as `replaceActions` hands over actions and
1231
+ under the same names: `source` names the set, handing the same name over
1232
+ again puts the new set in place of the old, so an entry it no longer names
1233
+ is refused from then on, and a name a feature keeps is not the app's. The
1234
+ entries in force are what the app shipped, then each set: an entry of a set
1235
+ is replayed in place of one the app shipped under the same fingerprint, for
1236
+ as long as the set holds it. Every entry is read by the schema the
1237
+ manifest's entries are read by, compiled, and checked before the set is
1238
+ taken: a write by vex's authoring lint, and the reach an entry declares by
1239
+ the check boot runs. Refused, the promise rejects with what was found
1240
+ (`Refresh refused — entries that do not parse:`, with the place and what
1241
+ was expected there) and nothing changed. Sets handed over at the same
1242
+ moment are taken in the order they were handed over. Accepted, the next request replays
1243
+ it, the set is frozen, living shells adopt and the pointer moves, as for a
1244
+ set of actions. Like one, **the set is handed to this process, and no other
1245
+ process is handed it** ([Many processes](#many-processes)). An app that
1246
+ hands over actions and the entries they replay hands the entries first.
742
1247
  - `actions(): Readonly<Record<string, ActionDefinition>>` — the actions in
743
1248
  force now, by id: what the app shipped, then each set handed over. To read;
744
1249
  a set changes through `replaceActions`.
1250
+ - `defaults(publisher): SessionArtifacts` — what is published for everybody,
1251
+ with the five calls a session's `artifacts` has (`save`, `list`, `history`,
1252
+ `restore`, `reset`) and the same body: `server.defaults(who).save([{ kind:
1253
+ 'layout', body: { ref: 'action/<id>', layout, use: true } }])` publishes a
1254
+ layout for an action, and every shell draws it under that action's ref
1255
+ unless its principal has a layout of their own in use or their roles hold a
1256
+ layout variant. With `ref: 'frame'` it publishes the layout of the app's own
1257
+ shell, and with `ref: 'canvas/<id>'` that of one of its canvases: each is
1258
+ drawn for everybody who has none of their own in use. Several may be kept for one ref and the one marked `use:
1259
+ true` is drawn; every publish is a version; a `reset` shows the build's
1260
+ again. A layout is the one kind that is published: an action or a fragment
1261
+ is refused here. `publisher` is who the publish is made by, and is kept with the save
1262
+ (`artifact_saves.created_by`); an empty one is refused.
1263
+ **No session can publish.** The rows are those of one principal no caller
1264
+ is (`*`), and every write a session makes carries its own `userId`: vex's
1265
+ row rule, the one a person's own rows are under. Only the app's own code on
1266
+ the server reaches this call, as it reaches `replaceActions`. **Who may
1267
+ publish is the charter's**: the app puts the call in a function, hands it
1268
+ the session's principal as `publisher`, and grants the action that calls
1269
+ that function to the roles that may. A function is declared before the
1270
+ server exists, so the app keeps the server where its functions can reach it.
1271
+ A layout is checked when it is published as one is when it is saved, held to
1272
+ every action in force with the layout it is built with: a ref no such action
1273
+ keeps a layout under is refused, and so is what a save refuses. When a shell
1274
+ is built it is checked again for that shell and that principal: one for an
1275
+ action they do not hold is not loaded, and one that no longer passes is left
1276
+ out with a line (`[moss] the layout "…" published for everybody is left out:
1277
+ …`, said once for each time the rows are read, not at every shell).
1278
+ One read of the rows answers every shell a process builds. A boot makes it,
1279
+ and fails if it cannot. The first shell built after this process publishes,
1280
+ or after the generation pointer moves, makes it again, and a read that fails
1281
+ fails that shell and is made again by the next. A publish has every living
1282
+ shell adopt, as `refresh` does, and moves the pointer, whether or not the
1283
+ rows can be read back: every other process on the same database follows
1284
+ within one poll ([Many processes](#many-processes)).
745
1285
  - `catalogOf(principal): Promise<{ ids, hash }>` — what a principal holds of the
746
1286
  actions in force: `{ ids, hash }`, the granted action ids sorted, with a
747
1287
  content-hash version token (equal hash, equal application). The principal is
@@ -771,7 +1311,7 @@ It's a Hono app — mount it, extend it, or hand it to a listener.
771
1311
  record and reset every living shell of theirs (a role change): the one the
772
1312
  app keeps for them, and the one a page built for each connection of theirs.
773
1313
  `false` = no record was held.
774
- - `invalidateTenant(tag): number` — forget every identity record wearing the
1314
+ - `invalidateTag(tag): number` — forget every identity record wearing the
775
1315
  tag the app put on it (`IdentityRecord.tag`); answers how many. Forgets, does
776
1316
  not reset shells.
777
1317
  - `identity(principal): Promise<IdentityRecord>` — who one principal is,
@@ -788,7 +1328,7 @@ It's a Hono app — mount it, extend it, or hand it to a listener.
788
1328
  `expired` the ones found older than `sessionRevalidateMs` and resolved
789
1329
  again.
790
1330
  - `executeAs(role, fingerprint, context, scope?): Promise<unknown>` — execute a
791
- seeded entry as a declared charter role, for surfaces with no principal by
1331
+ entry the app serves as a declared charter role, for surfaces with no principal by
792
1332
  nature. In-process only, replay-only, policy compiled from that role, scope
793
1333
  values supplied by server code. Its type is exported as `ExecuteAs`, for
794
1334
  code that is handed the function and no server. It answers the entry's
@@ -871,18 +1411,21 @@ is live when something on it can still happen:
871
1411
  | it waits on a channel | a `message:` trigger |
872
1412
  | a read keeps answering | an endpoint whose entry is `refresh: 'reactive'` |
873
1413
  | it calls code | a `fn:` endpoint that anything calls — code is not read |
874
- | it cannot be read | a layout kept in the store; a fingerprint the manifest does not carry |
1414
+ | it cannot be read | a `layout` that is the name of a stored layout; a fingerprint the manifest does not carry |
1415
+
1416
+ What can be pressed is read off the layout a screen is drawn with: a `{ ref }`
1417
+ in it, the one an action's own layout is named by included, is read through
1418
+ to the layout the shell's store holds under it.
875
1419
 
876
1420
  A read made while the action opened is **finished**: its answer is in the tree
877
1421
  (and listed in `drawnWith`). The app's own shell is always live for a signed-in
878
1422
  principal — it is the thing that is kept. nova supplies the facts
879
1423
  (`livenessOf`, `@niscorp/nova/reflect`); moss composes the verdict, because
880
- the running manifest holds the entries the app shipped, by fingerprint
1424
+ the running manifest holds the entries in force, by fingerprint
881
1425
  (`src/shells/snapshot.ts`; the function is not exported, its answer is
882
1426
  `live`, `why` and `drawnWith` on the snapshot). It reads that list and not
883
- the cache a replay resolves in, which can hold more: a fingerprint the
884
- manifest does not carry (a query written by `answerIntent`, a row an earlier
885
- boot seeded) is the last line of the table.
1427
+ the cache table, which can hold more: a fingerprint the running manifest does
1428
+ not hold (a query written by `answerIntent`) is the last line of the table.
886
1429
 
887
1430
  When `live` is false the trees are the whole of the screen, and the terminal
888
1431
  opens no socket.
@@ -991,7 +1534,7 @@ A page that is `live` is still written, and says why — its file is a true firs
991
1534
  screen and its terminal will look for a socket. Whether that is acceptable (a
992
1535
  server stands beside the files) or a mistake (there is none) is the build's to
993
1536
  decide, from the report. Writing the files, and listing a parameterised page's
994
- paths (`server.executeAs` runs a seeded read as a charter role), are the
1537
+ paths (`server.executeAs` runs a read the app serves as a charter role), are the
995
1538
  caller's.
996
1539
 
997
1540
  `renderDocument` is the one way a page is drawn, and its parts are not
@@ -1171,11 +1714,14 @@ tables changed, so a reactive read over one of them answers again.
1171
1714
  - `runtime.fabric` — `{ publish(message), subscribe(apply) }`, the
1172
1715
  host's transport (Postgres `LISTEN/NOTIFY` is the expected one; the type is
1173
1716
  `NiscRuntime['fabric']`, and is not exported by a name of its own). A
1174
- message is one of the three signals below with `origin`, the process that
1175
- sent it, which moss stamps and checks. It carries
1176
- three signals to the other processes: `invalidate-identity`,
1177
- `invalidate-tenant` and `nudge` — what `server.invalidateIdentity`,
1178
- `invalidateTenant` and `nudge` publish after applying locally. Best-effort:
1717
+ message is one of the four below with `origin`, the process that
1718
+ sent it, which moss stamps and checks. Three are what
1719
+ `server.invalidateIdentity`, `invalidateTag` and `nudge` publish after
1720
+ applying locally: `invalidate-identity`, `invalidate-tag` and `nudge`. The
1721
+ fourth, `adopt`, names a principal and tells a process to bring the shells
1722
+ it holds for them level with what they hold now; moss publishes it when a
1723
+ layout is saved for that principal (`session.artifacts`), and it says
1724
+ nothing of what was saved. Best-effort:
1179
1725
  each targets state that heals on its own clock. Unset, every path behaves as
1180
1726
  in one process. The wiring is `src/server/signals.ts`; it is the server's
1181
1727
  own and is not exported.
@@ -1193,25 +1739,27 @@ tables changed, so a reactive read over one of them answers again.
1193
1739
  logged with what was wrong with it and nothing it carried
1194
1740
  (`[moss:fabric] the transport handed over what is not a message…`); the ones
1195
1741
  after it are dropped without a line.
1196
- - The generation pointer — the persistent counter `server.refresh()` and
1197
- `server.replaceActions()` move (`moss_generation`, one row, part of
1742
+ - The generation pointer — the persistent counter `server.refresh()`,
1743
+ `server.replaceActions()`, `server.replaceEntries()` and a publish
1744
+ (`server.defaults`) move (`moss_generation`, one row, part of
1198
1745
  `MOSS_SEQUENCE`). Each process polls it (on `sessionRevalidateMs`; 60s when
1199
1746
  that is unset), and when it has moved it reads again every set of actions
1200
- it has a loader for, runs the check boot runs over what it would then
1201
- serve, drops what it derived (what each set of roles holds, the compiled
1747
+ it has a loader for, drops what it had read of what is published for
1748
+ everybody (the next shell it builds reads that again), runs the check
1749
+ boot runs over what it would then serve, drops what it derived (what each set of roles holds, the compiled
1202
1750
  policies, the identity records) and has its living shells adopt.
1203
1751
  **The pointer carries no set.** It says that something changed, and a
1204
1752
  process learns what by reading rows. The only set that has a loader is the
1205
1753
  integrations feature's (`'integrations'`). A set handed to
1206
- `server.replaceActions` in one process is in that process's memory: every
1207
- other process reaches the same generation and goes on serving the set of
1208
- that name it was last handed itself, or none. So an app that runs several
1209
- processes hands the set to each of them with `server.replaceActions`, on a
1210
- signal of its own. Each call moves the pointer once more, and the others drop
1754
+ `server.replaceActions` or `server.replaceEntries` in one process is in that
1755
+ process's memory: every other process reaches the same generation and goes
1756
+ on serving the set of that name it was last handed itself, or none. So an
1757
+ app that runs several processes hands the set to each of them, on a signal
1758
+ of its own. Each call moves the pointer once more, and the others drop
1211
1759
  what they derived and adopt again.
1212
1760
  The row is read and moved through vex, by two
1213
1761
  entries of moss's own that no route serves (`src/data/own-entries.ts`);
1214
- `src/manifest/generation.ts` holds the clock and no SQL. A move is a compare
1762
+ `src/artifactory/generation.ts` holds the clock and no SQL. A move is a compare
1215
1763
  and a set: the next number is written where the counter is still what was
1216
1764
  read, and read again where it is not. A move a process could not follow is
1217
1765
  tried again at every poll until it is followed, and logged when that is
@@ -1226,7 +1774,7 @@ tables changed, so a reactive read over one of them answers again.
1226
1774
  (default 30 minutes). At `identityMax` the least recently read record is
1227
1775
  dropped to make room, and whoever it was is resolved again on their next
1228
1776
  request. A record is forgotten with `server.invalidateIdentity`,
1229
- `invalidateTenant` and `refresh`, and what is held is read through
1777
+ `invalidateTag` and `refresh`, and what is held is read through
1230
1778
  `server.identities`.
1231
1779
 
1232
1780
  ### Telemetry
@@ -1286,8 +1834,8 @@ app that resolves people through `identity`.
1286
1834
  grants recompiled at that named profile. The vex surfaces and `executeAs` do
1287
1835
  it themselves; it narrows rows, never widens verbs.
1288
1836
  - A layout variant a set of roles holds (ring 2) is put in place of its
1289
- action's layout where a shell is built. Nothing answers the variants by
1290
- themselves.
1837
+ action's layout where a shell is built, in the shell's layout store.
1838
+ Nothing answers the variants by themselves.
1291
1839
  - `verifyApp(app, grants)` — the check boot runs, for an app
1292
1840
  that is not booted (a check, a build step): the charter with each role's
1293
1841
  closure audited, every entry's reach, the layout variants. It reads `charter`,
@@ -1328,17 +1876,20 @@ for (const error of report.errors) console.error(`${error.check}: ${error.detail
1328
1876
  is not exported). It is handed no manifest and no
1329
1877
  runtime, but a typed object of what it needs: one function that answers what
1330
1878
  a principal's shell is made of (who they are, the action definitions they
1331
- hold with their roles' layout variant in place, the canvases, the frame, the
1332
- layout store's seed, the fragments, the entries, the component names), the
1879
+ hold, the canvases and the frame, each naming its layout in the layout
1880
+ store, the layout store's seed with those layouts in it (for an action the
1881
+ published one over the build's, their roles' layout variant over that, and
1882
+ over it the layout of their own they marked in use), the
1883
+ fragments, the entries, the component names), the
1333
1884
  app's code a shell calls (`inputs`, `seeds`, `phrases`, `functions`,
1334
1885
  `onSession`, `runs`), the wire for a token, and its limits. Everything in
1335
1886
  that answer but who somebody is comes from the running manifest, which is
1336
1887
  asked once for each build and once for each adopt
1337
- (`src/manifest/artifacts.ts`): an action, a layout, a fragment and an entry
1888
+ (`artifactsFor`, `src/artifactory/running.ts`): an action, a layout, a fragment and an entry
1338
1889
  reach a shell through that one answer, and the server's wiring reads none
1339
1890
  of them off the app. For an entry that is what a shell is told of the reads
1340
- on its screens. What a read replays is not in the answer: the entries have
1341
- two holders (see "Where the app's entries are held", under `createServer`).
1891
+ on its screens. What a read replays the engine asks the running manifest
1892
+ for too (see "Where the app's entries are held", under `createServer`).
1342
1893
  A kept shell may sit unattached for
1343
1894
  `runtime.shellIdleMs` (default 30 minutes; `0` disables the sweep). A shell
1344
1895
  that is not kept (nobody signed in; any shell of a page's host) ends when
@@ -1364,21 +1915,28 @@ for (const error of report.errors) console.error(`${error.check}: ${error.detail
1364
1915
  - A host has no `adopt` and no `stop`. Each was a second way, for one
1365
1916
  host, to something a server does for all of them at once.
1366
1917
  **A change is the server's.** When what the app consists of changes
1367
- (`server.refresh()`, `server.replaceActions()`, an integration approved
1918
+ (`server.refresh()`, `server.replaceActions()`, `server.replaceEntries()`, an integration approved
1368
1919
  or removed, a change another process made), every living shell of every
1369
- host adopts: it is brought level with what its principal holds now, in
1920
+ 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
1370
1921
  place. Every living shell: the ones a host keeps, and the ones it built
1371
1922
  for one connection, which for the app's host is each visitor's and for a
1372
1923
  page's host is everybody's. Definitions that arrived or changed are
1373
1924
  registered and mounted instances keep their state; one that left, or is no
1374
1925
  longer granted, is removed and its instances unmounted. The shell's own
1375
- layouts are taken from the same answer: the frame, each `{ ref }` of the
1376
- layout store and each fragment that is answered differently from the last
1377
- time is put in place, and every attached terminal is sent the frame. One
1926
+ layouts are taken from the same answer: each `{ ref }` of the layout
1927
+ store and each fragment that is answered differently from the last time
1928
+ is put in place, and every attached terminal is sent the frame. The
1929
+ shell's layout, a canvas's and an
1930
+ action's own layout are each one of those refs, so a screen that is open shows a
1931
+ layout that changed, with its data kept, and a ref that is answered no
1932
+ longer is taken out of the store. One
1378
1933
  that is answered as it was is left alone, so a ref the shell's own code
1379
1934
  set since (`shell.setLayout`) stands through a change that did not touch
1380
- it. What a shell's canvases are, and what is mounted on them, is the
1381
- shell's own state and is not taken again: a reset builds that afresh. A
1935
+ it. The canvases a shell's manifest declares, and what is mounted on any
1936
+ canvas, are the shell's own state and are not taken again: a reset builds
1937
+ that afresh. A canvas the manifest does not declare, that a layout in
1938
+ force held a slot for, is taken out by an adopt, with what is mounted on
1939
+ it, once no layout holds the slot. A
1382
1940
  shell that cannot adopt is logged and keeps what it held; the rest go on.
1383
1941
  Each shell adopts on its own: one whose principal is never answered (an
1384
1942
  `identity` that hangs for them) holds up no other. So a change asks about