@niscorp/moss 0.6.0 → 0.8.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 (59) hide show
  1. package/CHANGELOG.md +144 -0
  2. package/DESIGN.md +77 -40
  3. package/DOCS.md +673 -78
  4. package/README.md +2 -2
  5. package/dist/chunk-3DCTQKPQ.cjs +943 -0
  6. package/dist/chunk-3DCTQKPQ.cjs.map +1 -0
  7. package/dist/{chunk-WKBH3UMB.js → chunk-3T422CCN.js} +9 -3
  8. package/dist/chunk-3T422CCN.js.map +1 -0
  9. package/dist/chunk-6XC2MD7S.js +906 -0
  10. package/dist/chunk-6XC2MD7S.js.map +1 -0
  11. package/dist/{chunk-D3YZIAYV.cjs → chunk-I4UOWER3.cjs} +11 -5
  12. package/dist/chunk-I4UOWER3.cjs.map +1 -0
  13. package/dist/{chunk-VBWNHF4H.cjs → chunk-PVZMCEBX.cjs} +4 -3
  14. package/dist/chunk-PVZMCEBX.cjs.map +1 -0
  15. package/dist/{chunk-NSK7QSSG.js → chunk-QAHDSRPK.js} +4 -3
  16. package/dist/chunk-QAHDSRPK.js.map +1 -0
  17. package/dist/{chunk-R66WUKGC.cjs → chunk-TMDKNZYL.cjs} +2169 -1319
  18. package/dist/chunk-TMDKNZYL.cjs.map +1 -0
  19. package/dist/{chunk-V5YMJL7Z.js → chunk-YZILOVCR.js} +2147 -1295
  20. package/dist/chunk-YZILOVCR.js.map +1 -0
  21. package/dist/document-BYAY-Qle.d.ts +381 -0
  22. package/dist/document-DAE71J27.d.cts +381 -0
  23. package/dist/{index-B411sK9M.d.cts → index-CSEo7Tys.d.cts} +5 -0
  24. package/dist/{index-B411sK9M.d.ts → index-CSEo7Tys.d.ts} +5 -0
  25. package/dist/index.cjs +17 -17
  26. package/dist/index.d.cts +8 -10
  27. package/dist/index.d.ts +8 -10
  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-CUnDcXQu.d.ts +0 -143
  47. package/dist/app-CdANzi2q.d.cts +0 -143
  48. package/dist/chunk-D3YZIAYV.cjs.map +0 -1
  49. package/dist/chunk-NSK7QSSG.js.map +0 -1
  50. package/dist/chunk-PWUO4RET.js +0 -374
  51. package/dist/chunk-PWUO4RET.js.map +0 -1
  52. package/dist/chunk-R2YPQHQH.cjs +0 -383
  53. package/dist/chunk-R2YPQHQH.cjs.map +0 -1
  54. package/dist/chunk-R66WUKGC.cjs.map +0 -1
  55. package/dist/chunk-V5YMJL7Z.js.map +0 -1
  56. package/dist/chunk-VBWNHF4H.cjs.map +0 -1
  57. package/dist/chunk-WKBH3UMB.js.map +0 -1
  58. package/dist/document-D7nroBww.d.cts +0 -169
  59. package/dist/document-DeTPGBil.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,61 @@ 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: `moss: functions(session) returned "auth.leave"
111
+ twice.` A map of handlers by id still works and is deprecated.
112
+ **`server.checkFunctions()`** builds nobody's shell once, drops it, and reads
113
+ what its `functions(session)` returned, so what is wrong with the functions
114
+ is refused or said before anyone is served. The app calls it once it holds
115
+ the server and before it listens, as a session hook may reach for the
116
+ server: `serve` of `@niscorp/moss/node` does, and so do `nisc dev`, `nisc
117
+ build`, `nisc check` and `nisc start` after the project's `boot`. It says: `[moss] functions(session)
118
+ returned a map of handlers, which is deprecated: return a list of { id,
119
+ description, execute }.`, or `[moss] functions with no description:
120
+ auth.leave. Give each a description.` An empty description counts as none,
121
+ and a function given by a map has none. **A shell holds only the functions
122
+ its principal's roles grant**, in the charter's `functions` part (names or
123
+ globs, with `extends` and `deny`, as `actions`): a role with none may call
124
+ none, and an `fn:` endpoint to one it does not grant fails when it is called.
125
+ What a living shell holds follows the roles an adopt answers, as its actions
126
+ do.
127
+ - **The boot is refused** where somebody holds an action that calls a
128
+ function their roles do not grant, and **`server.checkFunctions()` refuses**
129
+ where an action, or a fragment the shells ship, calls a function the app
130
+ does not have (`"home" calls "auth.leave", which the app has no function
131
+ of`); an app with no `functions` has none. It reads the `fn:` endpoints of
132
+ the actions held by each role on its own, each combination `wearable` or
133
+ `assignments` lists, and `public`, and of the fragments the shells ship,
134
+ and lists every call that is missing: `"member" hold "chrome.topbar",
135
+ which calls "auth.leave": their functions do not grant it`. A set handed
136
+ over while the app runs is held to the same. A name with a template in it
137
+ (`fn: '{{$.saveFn}}'`) is worked out when it is called, and the shell's map
138
+ decides then.
139
+ - **`functions: ['*']`** grants every function, as an app had before this
140
+ part existed. The boot says so for each role that has it: `role "member"
141
+ allows every function ('*'): the generated actions of the people who hold
142
+ it, or a role that extends it, may call any it does not deny`. Grant each
143
+ role the functions it calls.
144
+ - **The charter's own checks over the functions run in `checkFunctions`
145
+ too**, against what nobody's shell was given: a deny that matches nothing
146
+ refuses (`Charter is incoherent over the app’s functions — refusing to
147
+ serve:`), and a grant that names no function or a function no role grants
148
+ is said (`[moss] charter: role "member" allows "notes.ad" (functions)
149
+ which matches nothing`). Every check reads nobody's functions: an app that
150
+ hands a function only to signed-in sessions is refused where an action
151
+ calls it, and a later session that adds one is not read again.
105
152
  - `onSession(session)` — called once per living app shell, for session code
106
153
  that is not an endpoint (an observer, a roster). It runs before the shell
107
154
  finishes building, so it must not touch `session.shell` synchronously. Its
@@ -129,8 +176,9 @@ Every field is an artifact (authored data) except the code seams — `scope`,
129
176
 
130
177
  A `LayoutVariant` is `{ action: string; layout: LayoutNode }` — ring 2: the
131
178
  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
179
+ puts the granted variant's layout where that action's layout is kept in the
180
+ shell ("Where an action's layout is kept", under `createServer`). The base is
181
+ the floor; variants enrich upward as grants. A role, or a combination
134
182
  of roles somebody may wear, that holds two variants of one action refuses the
135
183
  boot, and so does a variant of an action the app does not have.
136
184
 
@@ -140,7 +188,7 @@ boot, and so does a variant of an action the app does not have.
140
188
  type ShellManifest = {
141
189
  canvases: ShellCanvas[]; // a canvas's `initial` may be a CANDIDATE list
142
190
  layout?: LayoutNode; // the frame — CanvasSlot markers, served verbatim
143
- layoutStore?: Record<string, LayoutNode>; // what a `{ ref: id }` in the frame resolves to at boot
191
+ 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
192
  fragments?: Record<string, ActionFragment>;
145
193
  inputs?: (session: { principal, actions, roles, identity, wire }) =>
146
194
  Record<string, Record<string, unknown>> | Promise<…>;
@@ -154,7 +202,9 @@ Two per-principal boot hooks, both of which may be async and are handed the
154
202
  session's governed `wire`. `inputs` derives boot **data** (nav flags, user
155
203
  chips), merged over each canvas's static seed. `seeds` derives boot
156
204
  **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.
205
+ like every other mount — a seed for an action the shell is not built with
206
+ does not mount. A shell is built with what its principal is granted and what
207
+ they generated.
158
208
  A `CanvasSeed` is an action id or `{ action, input?, with? }`, and a
159
209
  `ShellCanvas` is nova's canvas config with `initial` widened to one seed or a
160
210
  list of candidates. Neither type is exported by name: `ShellManifest['canvases']`
@@ -243,11 +293,13 @@ What the manifest's in-process functions close over:
243
293
 
244
294
  ```typescript
245
295
  type FunctionSession = {
246
- shell: Shell; // the session's living, durable shell (a getter — a reset replaces it); nine members throw
296
+ shell: Shell; // the session's living, durable shell (a getter — a reset replaces it); eight members throw
297
+ artifacts: SessionArtifacts; // what this principal saved, and saving: `session.artifacts`, below
298
+ draft: SessionDraft; // what is being generated in this one shell, before it is saved: `session.draft`, below
247
299
  principal: string | null;
248
300
  roles: readonly string[];
249
301
  identity: Record<string, unknown>; // the scope half of the resolved identity
250
- actions: readonly string[]; // the session's granted action ids, installs filtered
302
+ 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
303
  wire: FetchFn; // the server's own surfaces, as this session
252
304
  grant: (token: string) => void; // session GRANT (login): send it down, reconnect
253
305
  revoke: () => Promise<void>; // session REVOKE (sign-out): close 4403, evict
@@ -256,6 +308,7 @@ type FunctionSession = {
256
308
  asked: { intent: string; shape: unknown; context?: Record<string, unknown> },
257
309
  ) => Promise<QueryResponse>;
258
310
  recordRun: (run: Omit<RunRecord, 'at' | 'principal' | 'shellId'>) => void;
311
+ functions: () => readonly { id: string; description?: string }[]; // the app's functions this session may call, what its roles' `functions` grant
259
312
  };
260
313
  ```
261
314
 
@@ -264,10 +317,13 @@ deletes every session the principal has (`revokeAllFor`). It need not be
264
317
  awaited: a failure is logged. `recordRun` is a
265
318
  no-op when the manifest declares no `runs` sink.
266
319
 
267
- **`shell` refuses the nine members that change what a shell is made of**:
268
- `registerAction`, `removeAction`, `registerFragment`, `addCanvas`,
320
+ **`shell` refuses the eight members that change what a shell is made of**:
321
+ `registerAction`, `removeAction`, `addCanvas`,
269
322
  `removeCanvas`, `setCanvasLayout`, `setLayout`, `setPhrases` and `dispose`
270
- throw. An action, a fragment, a canvas, a layout and the phrases reach a shell
323
+ throw, and so do `set` and `delete` on its `layoutStore`, which is to read. A
324
+ definition read off it (`shell.getRuntime(id).definition`) is the action as it
325
+ was written, with the layout it is drawn with now in place: where moss keeps a
326
+ layout does not show. An action, a fragment, a canvas, a layout and the phrases reach a shell
271
327
  through moss, which verifies them and decides who holds them; added on the
272
328
  shell directly they are not verified, are in nobody's catalog and are gone
273
329
  when the shell is rebuilt. Everything else (reads, navigation, `dispatch`,
@@ -320,6 +376,384 @@ const runs: RunSink = (record) => {
320
376
  };
321
377
  ```
322
378
 
379
+ #### `session.artifacts` — what the session's principal saved
380
+
381
+ What somebody or a model generated while the app runs is kept by moss, as a
382
+ version, in two tables of its own. Four kinds are kept: a layout (for an
383
+ action, or for the app's own shell), an action, a fragment, and a read vex
384
+ wrote. A session saves for its own principal. A layout for everybody is
385
+ published from the server and never from a session (`server.defaults`, under
386
+ `MossServer` below). Not built yet: a layout of a page's shell, and an action,
387
+ a fragment or a read for everybody.
388
+
389
+ ```typescript
390
+ type SessionArtifacts = {
391
+ save: (artifacts: readonly { kind: ArtifactKind; id?: string; body: unknown }[]) => Promise<{ save: string; artifacts: readonly { kind: ArtifactKind; id: string }[] }>;
392
+ list: (kind?: ArtifactKind) => Promise<readonly ArtifactVersion[]>;
393
+ history: (kind: ArtifactKind, id: string) => Promise<readonly ArtifactVersion[]>;
394
+ restore: (kind: ArtifactKind, id: string, save: string) => Promise<{ save: string }>;
395
+ reset: (kind: ArtifactKind, id: string) => Promise<{ save: string }>;
396
+ };
397
+
398
+ type ArtifactKind = 'layout' | 'action' | 'fragment' | 'read';
399
+
400
+ type ArtifactVersion = {
401
+ kind: ArtifactKind;
402
+ id: string;
403
+ save: string; // the save this version belongs to
404
+ createdAt: string; // ISO
405
+ copiedFrom: string | null; // the save it is a copy of, where it is one
406
+ body: unknown; // null: this version says none is in force
407
+ };
408
+ ```
409
+
410
+ The three types are reached as `FunctionSession['artifacts']`; none is
411
+ exported by a name of its own.
412
+
413
+ **A layout's body** is `{ ref, layout, use? }`. `ref` is the name the layout
414
+ of the action it is for is kept under in the shell's layout store,
415
+ `action/<the action's id>`, or, for a layout of the app's own shell (further
416
+ down), `frame` or `canvas/<a canvas's id>`. `layout` is a nova layout.
417
+
418
+ ```typescript
419
+ functions: (session) => [
420
+ {
421
+ id: 'layout.keep',
422
+ description: 'Keeps a layout for the deals list as the person’s own. Send { layout }.',
423
+ execute: async ({ layout }) => session.artifacts.save([{ kind: 'layout', body: { ref: 'action/deals.list', layout, use: true } }]),
424
+ },
425
+ ],
426
+ ```
427
+
428
+ **A generated action's body** is a nova action definition without an `id`,
429
+ and **a generated fragment's** a nova fragment without one. Moss gives the id:
430
+ `generated.` and a uuid, which `save` answers. A body that names another id is
431
+ refused, and a save that names the `id` of one of the principal's own is a new
432
+ version of it.
433
+
434
+ ```typescript
435
+ functions: (session) => [
436
+ {
437
+ id: 'screen.keep',
438
+ description: 'Keeps an action the person generated. Send { action }.',
439
+ execute: async ({ action }) => session.artifacts.save([{ kind: 'action', body: action }]),
440
+ },
441
+ ],
442
+ ```
443
+
444
+ - **It is its owner's and nobody else's.** It is among the actions (or the
445
+ fragments) their shells are built with, its layout is in their layout store
446
+ under `action/<its id>`, and a layout of their own may be saved for it as
447
+ for a shipped action. No charter grant is asked about it, and it is in no
448
+ catalog: `/catalog`, the socket's hello and `server.catalogOf` answer what
449
+ the charter grants. What somebody generated is listed by
450
+ `session.artifacts.list('action')`.
451
+ - **It ages out when nobody uses it.** With `runtime.artifactsUnusedMs`, a
452
+ version of an artifact a person saved is stamped as used when a shell is
453
+ built for them (`last_used_at`, once an hour at most), and every artifact of
454
+ theirs whose newest version was neither saved nor used within that time is
455
+ deleted, every version of it, by a sweep that runs as the server comes up and
456
+ then every hour. What is published for everybody never ages, and what the
457
+ build ships is not a row. Without the setting nothing is deleted. A limit of
458
+ `0` or less refuses the boot.
459
+ - **It reaches its owner's open shells a moment after the save answers**, as a
460
+ saved layout does, and not before: a function that saves an action and
461
+ opens it in the same call finds it not there yet. One that is to be seen at
462
+ once is added to the draft (`session.draft`, below), which answers when the
463
+ shell has it.
464
+ - **What it defines replays reads, and calls the functions its owner's roles
465
+ grant.** An `fn:` endpoint names a function its owner's roles grant in the
466
+ charter's `functions` (`session.functions()` lists them with their
467
+ descriptions, for the model that writes it); one they do not grant is refused. Every other endpoint is a
468
+ `POST` to the app's vex route (`/api/vex`, or `/api/<resource>/vex`) whose
469
+ `request` names one fingerprint, written out. That fingerprint is a read the app ships or
470
+ was handed (`replaceEntries`) that its owner's policy may replay, or a read
471
+ vex wrote that its owner saved (below). Refused, with a sentence: a function
472
+ its owner's roles do not grant, a write, a read its owner may not replay, any other fingerprint (a
473
+ query a model wrote that nobody saved, `fp_…`, among them), a fingerprint
474
+ that is computed, an address with a template in it, and every other
475
+ address.
476
+ - **Moss checks the artifact, and what it is combined with is nova's.** Once
477
+ it is in a shell it is an action, or a fragment, like any other. A message
478
+ it emits reaches every action open in its owner's shell. The steps of a
479
+ fragment run inside the action it is wrapped around, with that action's
480
+ endpoints, and where both define an endpoint of one name the action's is
481
+ the one called. What an assistant is told it may generate is the app's to
482
+ decide: it writes the prompt, and its own function calls `save`.
483
+ - **A generated action opens the actions its owner holds**, their own
484
+ generated ones among them, and no other: nova's audit is run on it with
485
+ those as its catalog, and what it finds refuses the save, as it does for a
486
+ saved layout. So do a component no shell of the app has, and a layout that
487
+ names a ref moss keeps a layout under (`action/…`, `canvas/…`, `frame`). A fragment is held to its schema, its id, its
488
+ layout and its endpoints, and not to that audit, which reads a whole action:
489
+ a step of a fragment that opens an action its owner does not hold is refused
490
+ by nova when it runs, because that action is not in their shell.
491
+ - **It is checked when it is saved and again when a shell is built.** One
492
+ that no longer passes (its owner lost the grant its read needs, say) is left
493
+ out of every shell built from then on, with a line (`[moss] the action "…"
494
+ of … is left out: …`).
495
+ - **A reset takes it out of its owner's shells**, and the layouts they saved
496
+ for it are not drawn while it is out: a layout whose action its holder has
497
+ no longer is not loaded. `list('layout')` still lists them. Going back to a
498
+ version of the action brings both back.
499
+ - **No action an app ships or hands over, and no fragment of a shell, has an
500
+ id beginning with `generated.`**: a boot, `replaceActions` and the
501
+ manifest's parse refuse one. Nor is an action under the id of a fragment a
502
+ shell ships, since a nova shell keeps both in one registry: a boot and
503
+ `replaceActions` refuse that too.
504
+ - A fragment that left, by a reset or because it no longer passes, is taken
505
+ out of a shell that is already open, as an action is. What was opened with
506
+ it stays as it was composed.
507
+
508
+ **Every call is for the session's principal, and no call can be for anybody
509
+ else.** No argument names whose rows are meant. Moss runs its own entries over
510
+ the two tables as the caller, with the scope values the routes serve that
511
+ caller under, and under one row rule: a caller reads and writes only the rows
512
+ whose `principal` is their `userId`, and a row they insert or update carries
513
+ it, whatever the statement says. Vex keeps that rule on every read and every
514
+ write; moss's code passes no principal. **Who may save at all is the charter's**: a function that calls
515
+ `session.artifacts.save` is the app's, an action calls it, and the charter
516
+ says who holds that action. A session nobody is signed in to saves nothing
517
+ and lists nothing: everybody who is not signed in shares one `userId`.
518
+
519
+ - The layout is the principal's and nobody else's. Moss gives it its id, a
520
+ uuid, and answers it; a save that names that `id` is a new version of the
521
+ same layout, and an id that is not one of theirs is refused.
522
+ - Several of somebody's own may be for one ref: the one whose body says
523
+ `use: true` is the one their shells draw, and marking one takes the mark off
524
+ their others for that ref in the same save. One that is not marked is kept
525
+ and not drawn.
526
+ - Their open screens follow at once, with what was typed into them kept; in a
527
+ deployment of several processes the others are told over the fabric
528
+ (`adopt`, under "Many processes").
529
+
530
+ **Whose a row is, is the caller's `userId`**: the scope value moss supplies
531
+ for every caller, which an app's `scope` can set. An app that gives a person one account for each tenant
532
+ keeps their layouts apart by tenant. An app where one account spans tenants
533
+ has that person's layouts follow them into each. In neither does anybody read
534
+ or write a row of another account.
535
+
536
+ **A read vex wrote** for a request (`session.answerIntent`) is saved under
537
+ the fingerprint vex gave it, with no body:
538
+ `session.artifacts.save([{ kind: 'read', id: 'fp_…' }])`. Moss takes the entry
539
+ from vex's own table and keeps it as written: the query, the Prism config of
540
+ its mapping, its shape and its intent.
541
+
542
+ - **It is answered to the person who saved it and to nobody else.** When one
543
+ of their requests replays that fingerprint, moss answers it, compiled, from
544
+ their rows. Anybody else who sends the fingerprint gets what vex's own table
545
+ still holds under it, as for any query vex wrote and nobody saved, and a
546
+ caller nobody is signed in for is never answered a saved read.
547
+ - **It is a query vex wrote, and is held as one.** Vex's limits apply to it
548
+ (`maxLimit`), as they do not to an entry the app ships. A request that names
549
+ its fingerprint with an intent and a shape is written anew by vex into its
550
+ own table; the saved read is what its owner is answered until they save the
551
+ new one.
552
+ - **It survives a schema change that does not touch what it reads.** Vex drops
553
+ the copy in its own table at the first replay after any schema change; the
554
+ saved one is not dropped. One whose query no longer runs is refused by vex
555
+ when it is replayed, and is left out of what is in force with a line
556
+ (`[moss] the read "fp_…" of … is left out: …`), with any generated action of
557
+ its owner that replays it.
558
+ - **Its owner's policy applies when it is replayed.** A generated action over a
559
+ read whose tables its owner can no longer read stays in force, and its
560
+ replay is refused, where one over such an entry the app ships is left out.
561
+ - **A generated action may replay a read its owner saved**, as it may an entry
562
+ the app ships that its owner may replay. A draft takes a read too, and an
563
+ action added to the same draft may replay it.
564
+ - **What is refused**, in a sentence: a read with no id, or with a body; one
565
+ under the fingerprint of an entry the app ships or was handed; one vex did
566
+ not write for a request; a write; one whose mapping vex kept no config for
567
+ (it was written before vex kept one: ask for it again); and one whose query
568
+ does not run against the schema.
569
+
570
+ **What a shell draws under an action's ref**, the first of these that there
571
+ is: the principal's own layout marked in use; the layout variant their roles
572
+ hold (`app.layouts`); the layout published for everybody that is marked in use
573
+ (`server.defaults`); the layout the build ships.
574
+
575
+ **What is refused**, at a save and at a restore, in a sentence, with nothing
576
+ written: a body that is not `{ ref, layout, use? }`; a `ref` nothing is kept
577
+ under for the principal (an action they do not hold, or one that is not in
578
+ force; an action with no layout of its own, or one that names a layout of the
579
+ store by its id; any name that is none of `action/<id>`, `frame` and
580
+ `canvas/<id>`); a component no shell of
581
+ the app has (and a prop its declared schema refuses, as for an integration's
582
+ layouts); a layout that names a ref moss keeps a layout under (`action/…`,
583
+ `canvas/…`, `frame`); and what nova's audit
584
+ (`auditAction`) finds of the action with the layout in place and does not find
585
+ of the action as it is built (a binding to a key the action has no data for,
586
+ a control the action listens on that the layout leaves out, a control no
587
+ trigger handles). The same is asked of every saved layout when a shell is
588
+ built, there against the components of that shell alone: one that does not
589
+ 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
590
+ its holder's store keeps nothing under any more (the action left, or they
591
+ hold it no longer) is not loaded and nothing is said.
592
+
593
+ **The layouts of the app's own shell** are saved with the same calls: its own
594
+ under `ref: 'frame'`, and a canvas's under `ref: 'canvas/<the canvas's id>'`.
595
+ `session.artifacts.save([{ kind: 'layout', body: { ref: 'frame', layout, use:
596
+ true } }])`.
597
+
598
+ - **They are the app's own shell's.** Under either name that shell draws the
599
+ first of these that there is: the principal's own marked in use, the one
600
+ published for everybody that is marked in use, the one the manifest
601
+ declares. A page draws the layouts its own manifest declares, whatever was
602
+ saved: an app that lets people save a frame has, in a page, a screen no
603
+ saved frame changes. A draft of a page's shell takes none.
604
+ - **A shell manifest with no `layout` has none to take the place of**, nor
605
+ has a canvas with no `actionLayout`, or with one that is the name of a
606
+ stored layout. A save for one is refused as for any ref nothing is kept
607
+ under.
608
+ - **What is refused**: a body that is not `{ ref, layout, use? }`, a component
609
+ the app's own shell has none for (and a prop its declared schema refuses),
610
+ and a layout that names a ref moss keeps a layout under. Nova's audit reads
611
+ an action, and is not asked of these. One that names a ref nothing is kept
612
+ under is saved, and nova draws its error box in that place, as it does in
613
+ an action's layout.
614
+ - **A frame may leave a canvas of the shell out.** That canvas stays the
615
+ shell's and is drawn nowhere: what is mounted on it runs unseen, and what an
616
+ action opens on it does not show. Moss does not refuse it. An app that wants
617
+ every canvas placed checks the layout in its own function before it saves.
618
+
619
+ **A canvas that only a layout's slot draws goes when the slot goes.** Nova
620
+ gives a shell a canvas when something is first pushed onto it, whether or not
621
+ its manifest declares it, and it is drawn where a layout has a canvas slot for
622
+ it (`{ component: 'CanvasSlot', props: { canvasId: 'notes' } }`). Moss reads
623
+ which canvases the layouts a shell is built from hold a slot for and its
624
+ manifest does not declare. Every layout counts (the frame, a canvas's, an
625
+ action's that the principal holds, a fragment's, one the app keeps in its
626
+ layout store), the build's and a saved or generated one alike. Once a layout
627
+ leaves force and no other holds a slot for such a canvas, an open shell loses
628
+ the canvas, with what is mounted on it. A slot whose `canvasId` is worked out
629
+ when it is drawn (`'$.c.id'`, a template) counts for none. Moss gives a shell
630
+ no canvas, and the canvases a manifest declares are never taken out. What is
631
+ pushed onto a canvas after its slot went is mounted and drawn nowhere, as on
632
+ any canvas no layout has a slot for.
633
+
634
+ **Moss changes and deletes no row.** `list` answers the latest version of each
635
+ of the principal's artifacts that has a body. `history` answers the versions
636
+ of one, the newest first (the newest 500). `restore` is a new save that holds
637
+ a copy of a version and says which (`copiedFrom`); it is checked as a save
638
+ is. `reset` is a new save whose version has no body: none of the principal's
639
+ is in force under that id, and what is under it is drawn again. A reset is a
640
+ version too, and can be gone back from. Two saves by one person at the same
641
+ moment can each leave a layout marked in use for one ref. The later one is
642
+ drawn. The next save that marks one for that ref, or takes the one in use out
643
+ (a reset, or a save of it without the mark), takes the mark off the rest.
644
+
645
+ The rows are in `artifact_saves` (one for each save) and `artifacts` (one for
646
+ each version a save holds), which migration `nisc.moss/5` makes. They are
647
+ read and written through three vex entries of moss's own that no route serves
648
+ (`src/artifactory/saves.ts`). What is in force for an artifact is its latest
649
+ version by `created_at`; every id moss gives is a uuid. A body is kept with
650
+ the grammar stamp it was written at and is brought to the grammars the server
651
+ runs when it is read. What somebody saved is asked of the rows once for each
652
+ shell that is built for them and once for each adopt; nothing of it is kept in
653
+ memory, so a save made in another process is theirs here at the next build
654
+ whether or not a fabric is set. The entries are loaded when the server boots,
655
+ and a boot that cannot load them fails. A row always has a principal: the two
656
+ `principal` columns refuse a null, so an app whose `scope` answers no `userId`
657
+ for somebody saves nothing for them.
658
+
659
+ **No caller's `userId` is `*`.** What is published for everybody is kept as
660
+ the rows of that one principal, under the same row rule, so a caller whose
661
+ `userId` were `*` would read and write what is published as their own. Moss
662
+ refuses one wherever it composes a caller's scope for vex: no shell is built
663
+ for them (`moss: a caller’s \`userId\` is "*", …`), `/api/vex` answers them
664
+ 500, and an intent a function asks for them is refused. An app's sign-in, or
665
+ its `scope`, answers another id. A scope that carries `artifactSavedBy` is
666
+ refused in the same places: who made a save is written from that value, and
667
+ it is moss's to say. (`server.executeAs` is the app's own code, and hands vex
668
+ the scope it is given.)
669
+
670
+ **The row rule is moss's, wherever a policy is compiled.** The two tables are
671
+ in the data a charter selects from, as every table is: no role reaches them
672
+ unless its charter grants them. A role that is granted them, by name or by a
673
+ wildcard (`*.read`), reads and writes its own rows there and nobody else's,
674
+ because the same rule is part of the policy `server.policyForRoles` answers.
675
+ An app does not say otherwise: `behaviors` that name either table refuse the
676
+ boot. (A policy an app compiles itself, from its charter and its own
677
+ `behaviors` and without the server, does not carry the rule.) Moss's own
678
+ entries only add rows. An app whose charter grants a role update or delete
679
+ on the two tables, and that ships an entry of its own to do it, lets that
680
+ role change or remove its own rows, and never another's. A save itself (a row
681
+ of `artifact_saves`) is moss's alone to make: who made it (`created_by`) is
682
+ written from a scope value no caller's scope carries (`artifactSavedBy`), so
683
+ an app's entry that inserts or updates one for a caller is refused (500,
684
+ `missing_scope`).
685
+
686
+ **A save is not told to `app.reactions`.** Moss's own entries tell the app's
687
+ engine which tables changed, so a read of the app's that follows them
688
+ refreshes, and tell no subscriber of the routes. The function that saved
689
+ knows that it did.
690
+
691
+ #### `session.draft` — what is being generated in this shell
692
+
693
+ What a person or a model is still working on is in the draft of the one shell
694
+ it is worked on in. It is shown there at once and saved nowhere: no other
695
+ shell has it, the person's own others included, and it is gone when the shell
696
+ is (a reset, an idle shell that was dropped, a restart).
697
+
698
+ ```typescript
699
+ type SessionDraft = {
700
+ add: (artifacts: readonly { kind: ArtifactKind; id?: string; body: unknown }[]) => Promise<{ step: number; artifacts: readonly { kind: ArtifactKind; id: string }[] }>;
701
+ list: () => readonly { kind: ArtifactKind; id: string; body: unknown }[];
702
+ remove: (kind: ArtifactKind, id: string) => Promise<{ step: number }>;
703
+ show: (step: number) => Promise<void>;
704
+ discard: () => Promise<void>;
705
+ save: () => Promise<{ save: string; artifacts: readonly { kind: ArtifactKind; id: string }[] }>;
706
+ };
707
+ ```
708
+
709
+ ```typescript
710
+ functions: (session) => [
711
+ {
712
+ id: 'screen.try',
713
+ description: 'Shows an action the person is trying out, without keeping it. Send { action }.',
714
+ execute: async ({ action }) => {
715
+ const added = await session.draft.add([{ kind: 'action', body: action }]);
716
+ session.shell.push('main', added.artifacts[0].id);
717
+ },
718
+ },
719
+ { id: 'screen.keep', description: 'Keeps what the person is trying out.', execute: async () => session.draft.save() },
720
+ ],
721
+ ```
722
+
723
+ - **`add` takes what `session.artifacts.save` takes and refuses what it
724
+ refuses**, with the same sentences. Each artifact is checked beside what is
725
+ in force for the principal with the draft laid over, so a layout may be for
726
+ an action that is itself in the draft. A draft is one shell's, so what is
727
+ added to it is held to the components of that shell, where a save is held to
728
+ those of any shell of the app. A new action or fragment gets its
729
+ `generated.` id here, and keeps it when the draft is saved. An `id` names
730
+ one in the draft, or one the principal saved: a new take of it, which stands
731
+ in for the saved one in this shell until the draft is saved or the take is
732
+ taken out. An add that marks a layout `use: true` takes the mark off the
733
+ draft's others for that ref, as a save does.
734
+ - **What is added is in the shell when the add answers.** The function that added an action
735
+ opens it on its next line. An open screen follows a drafted layout with what
736
+ was typed into it kept, as it follows a saved one. An add the shell could not
737
+ take rejects, and the draft is as it was.
738
+ - **What the shell draws**: what is in the draft, then what `session.artifacts`
739
+ would draw. A drafted layout marked `use: true` is drawn in place of a saved
740
+ one that is marked for the same ref.
741
+ - **`list`** answers what the draft holds, and **`remove`** takes one out of
742
+ it; what is under it is drawn again. **`discard`** empties it.
743
+ - **Each add or removal is a numbered step**, from 1. **`show(step)`** has the
744
+ shell show the draft as it was after that step, and `show(0)` none of it. A
745
+ add or a removal while an earlier step is shown goes on from that step: the
746
+ steps after it are dropped. The steps are the draft's and are saved nowhere.
747
+ - **`save`** is one save of what the draft holds, as the principal's own and
748
+ under the ids it had, checked once more. The draft is then empty and the
749
+ shell keeps what it shows. An empty draft is refused.
750
+ - **Calls on one draft are taken in turn**: each starts from the draft as the
751
+ one before it left it.
752
+ - A session nobody is signed in to has no draft, as it saves nothing. Every
753
+ call on the draft of a shell that was replaced since is refused (`moss: this
754
+ session’s shell is gone, and its draft with it.`), `list` and `save` among
755
+ them: what was in it is saved by nobody.
756
+
323
757
  ### The environment
324
758
 
325
759
  #### `NiscRuntime`
@@ -335,6 +769,7 @@ type NiscRuntime = {
335
769
  migrations?: 'apply' | 'verify'; // the boot's ledgered run; default 'apply'
336
770
  tables?: readonly Sequence[]; // the app's own table sequences, in that same run
337
771
  shellIdleMs?: number; // idle shell eviction; default 30 min, `0` disables
772
+ artifactsUnusedMs?: number; // delete what a person generated once nobody has loaded it for this long; default never
338
773
  anonymousShellMax?: number; // shells for nobody signed in alive at once; default 1,000, `Infinity` is no limit
339
774
  endpointTimeoutMs?: number; // a server shell's endpoint call, and the build of a shell; default nova's, 30s
340
775
  sessionRevalidateMs?: number; // live-socket re-verify; default 60s, `0` disables
@@ -495,7 +930,8 @@ await revokeAllFor(runtime.pool, 'usr_ada');
495
930
 
496
931
  **Tables go through a ledger.** moss creates no table on its own: its tables are
497
932
  [strata](../strata/README.md) sequences — `MOSS_SEQUENCE` (`nisc.moss`:
498
- integrations, their actions, the generation pointer) and the sessions table's
933
+ integrations, their actions, the generation pointer, the two tables of what
934
+ was saved) and the sessions table's
499
935
  (`nisc.moss.sessions`; the sequence itself is not exported) — and
500
936
  `createServer` applies them with the vex cache's sequence in
501
937
  one ledgered run before introspection: once, recorded in `strata_ledger`, and
@@ -531,8 +967,12 @@ reason as `fingerprint: why` — and nothing was applied. It asks on every run,
531
967
  so a release that changes an entry and no table is checked too.
532
968
 
533
969
  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.
970
+ the run and that the cache table already holds a copy of, exactly as it is. That
971
+ is an old fault, not this run's. A new or changed entry gets no such pass. A
972
+ copy is there where a release before 0.6.0 wrote it, or where the app writes
973
+ one itself for an engine of its own (`seedCache`). Moss writes none since
974
+ 0.6.0: it keeps an app's entries in memory, so in a database only moss writes
975
+ to, an entry first shipped since then has no copy and gets no pass either.
536
976
 
537
977
  What it answers is strata's `{ applied, plan }` plus `removed` (tables and
538
978
  columns the run takes away), `retyped` (columns whose type it changes, as
@@ -594,27 +1034,89 @@ does nothing. Returns a Hono app extended with the `MossServer` members below.
594
1034
  order: the manifest is read and frozen; who a token is is resolved
595
1035
  (`runtime.session`; unset, the boot is refused here, before a table exists);
596
1036
  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
1037
+ created, which is the boot check, and the data module is told to ask it for an
1038
+ entry (it compiles the ones it holds, and one vex cannot run refuses the boot);
1039
+ identity; the server's own routes (the
599
1040
  authentication, `/catalog`, vex); the shell hosts, the app's and each page's;
600
1041
  what crosses processes; the features, each started with seams made for it; the
601
1042
  operator prefix; the app's reactions hear a write; the generation pointer is
602
1043
  watched; the socket.
603
1044
  A step that refuses is the boot's refusal.
604
1045
 
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.
1046
+ **Where the app's entries are held.** In the running manifest
1047
+ (`src/artifactory/`), in memory, and nowhere else. It holds the entries the
1048
+ app shipped and each set handed over with `server.replaceEntries`, compiled as
1049
+ vex replays them, and it is what the engine asks first: a request's
1050
+ fingerprint, and the list of fingerprints a feature or the operator is told
1051
+ of, resolve there. So what a fingerprint resolves to is what this process's
1052
+ app ships, read from the build at every boot.
1053
+
1054
+ What the running manifest does not hold is asked of the cache table
1055
+ (`vex_cache`, or the cache `runtime.cache` hands over). That table keeps what
1056
+ vex wrote itself while the app runs: a query `session.answerIntent` wrote.
1057
+ **Nothing is copied into it at boot, and a row in it that no request wrote is
1058
+ not replayed.** Vex gives a query it writes the hash of the request it was
1059
+ written for, and that is what moss asks of a row before it answers from it. A
1060
+ release before 0.6.0 copied every entry of the app there at each boot, and a
1061
+ database that ran one still holds those rows, which carry no such hash. Moss
1062
+ answers from none of them and deletes none: an entry the app no longer ships
1063
+ is refused (`cache_miss`). Two things an app may have leaned on are gone with
1064
+ the copy:
1065
+
1066
+ - **An engine of the app's own over the same table** finds no entry of the app
1067
+ there. It is given the entries it replays by the app
1068
+ (`seedCache(cache, entries)`, as the server used to do for it).
1069
+ - **A row the app writes into the table itself**, to serve an entry that is
1070
+ not in its manifest, is not replayed. `server.replaceEntries` is the way an
1071
+ entry reaches a running server.
1072
+
1073
+ **Where an action's layout is kept.** In the shell's layout store, under
1074
+ `action/<id>`. An app goes on writing an action's layout in its definition;
1075
+ where a shell is built, moss moves it into the store, and the definition the
1076
+ shell is handed names it by `{ ref: 'action/<id>' }`. A layout variant the
1077
+ person's roles hold is what the store holds under that name instead. An action
1078
+ with no layout, or one whose `layout` is already the name of a stored layout,
1079
+ is handed over as it is. Three things follow:
1080
+
1081
+ - **A layout that changes reaches a screen that is already open**, with the
1082
+ data on it kept. Until 0.6.0 an open instance kept the layout it was opened
1083
+ with, and only one opened afterwards showed the new one. What an open
1084
+ instance still keeps is the rest of its definition: its data's shape, its
1085
+ endpoints and its triggers.
1086
+ - **Code that reads an action's definition off its session's shell**
1087
+ (`session.shell.getRuntime(id).definition`) finds it as it was written, with
1088
+ the layout in place: the one the store holds now, so a variant or a change
1089
+ shows. `server.actions()` answers the definitions as they were written too.
1090
+ Only the whole shell (`unverifiedShell(session)`), which is nova's own,
1091
+ shows `{ ref }`; there the layout is `shell.layoutStore.get('action/<id>')`.
1092
+ - **`action/` belongs to moss in a layout store.** A manifest whose
1093
+ `layoutStore`, the app's shell's or a page's, declares a name beginning with
1094
+ it refuses the boot (`shell.layoutStore.action/home: a name beginning with
1095
+ "action/" is where the layout of that action is kept`). So does an action's
1096
+ layout, or a layout variant, that names one by `{ ref }` or as its layout's
1097
+ name, at boot and when a set is handed over (`"panel" names the layout
1098
+ "action/panel": …`): a layout cannot be drawn inside itself, and an action
1099
+ cannot draw another's.
1100
+ - **The layout of an action that leaves a shell leaves its store.**
1101
+
1102
+ **The shell's own layout and a canvas's are kept there too**, under `frame`
1103
+ and `canvas/<the canvas's id>`. An app goes on writing `layout` in its shell
1104
+ manifest and `actionLayout` in a canvas; where a shell is built, moss moves
1105
+ each into the store and the shell draws it by that name. A shell manifest with
1106
+ no `layout` has no `frame` in its store and is drawn with nova's own, and a
1107
+ canvas whose `actionLayout` is already the name of a stored layout, or that
1108
+ has none, is handed over as it is. So is a `layout` that is the name of a
1109
+ stored layout: the shell draws by that name, and nothing is kept under
1110
+ `frame`. Both names belong to moss in a layout
1111
+ store, as `action/` does: a manifest whose `layoutStore`, the app's shell's or
1112
+ a page's, declares one refuses the boot (`shell.layoutStore.frame: "frame" is
1113
+ where the layout of the shell is kept`, `shell.layoutStore.canvas/main: a name
1114
+ beginning with "canvas/" is where the layout of that canvas is kept`). So does
1115
+ an action's layout, or a layout variant, that names one by `{ ref }` or as its
1116
+ layout's name (`"panel" names the layout "frame": …`). Only a node that is
1117
+ `{ ref }` and nothing else names a layout: a `ref` a component carries, on its
1118
+ node or in its props, names none. Both can be saved for the app's own shell
1119
+ (`session.artifacts`).
618
1120
 
619
1121
  **The manifest is read first.** Before a table is created or a row is read,
620
1122
  `createServer` parses the manifest with a schema, and a manifest that does not
@@ -645,11 +1147,12 @@ zod schema handed over as a component's `propsSchema`), is not frozen and not
645
1147
  looked inside. An object the app shares between its manifest and its own code
646
1148
  is frozen for both.
647
1149
 
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.
1150
+ What an app consists of changes in two ways while a server runs: a set of
1151
+ actions is handed over with `server.replaceActions(source, actions)`, and a set
1152
+ of entries with `server.replaceEntries(source, entries)`. Each verifies before
1153
+ it switches. A charter, a layout variant, a behavior and the shell do not
1154
+ change under a running server; they change in the manifest the next server is
1155
+ created with.
653
1156
 
654
1157
  What the server answers over HTTP:
655
1158
 
@@ -685,7 +1188,7 @@ and does not throw.
685
1188
  #### `MossServer`
686
1189
 
687
1190
  `Hono<Env> & { socket; shells?: ShellHost; principalOf; page; pages;
688
- refresh; replaceActions; actions; catalogOf;
1191
+ refresh; replaceActions; replaceEntries; actions; defaults; catalogOf;
689
1192
  policyForRoles; charterReport; invalidateIdentity; invalidateTag; identity;
690
1193
  executeAs; nudge; close; identities? }`.
691
1194
  It's a Hono app — mount it, extend it, or hand it to a listener.
@@ -737,11 +1240,85 @@ It's a Hono app — mount it, extend it, or hand it to a listener.
737
1240
  keeps a set of its own under its own name (`'integrations'` is the
738
1241
  integrations feature's, read from its tables) and is the only one that
739
1242
  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. …`).
1243
+ set "integrations" is the feature "integrations"'s, and only its owner
1244
+ replaces it. …`).
1245
+ - `replaceEntries(source, entries): Promise<void>` — hand over a set of
1246
+ entries that arrived while the app runs (an app that loads its reads and
1247
+ writes from its own tables), as `replaceActions` hands over actions and
1248
+ under the same names: `source` names the set, handing the same name over
1249
+ again puts the new set in place of the old, so an entry it no longer names
1250
+ is refused from then on, and a name a feature keeps is not the app's. The
1251
+ entries in force are what the app shipped, then each set: an entry of a set
1252
+ is replayed in place of one the app shipped under the same fingerprint, for
1253
+ as long as the set holds it. Every entry is read by the schema the
1254
+ manifest's entries are read by, compiled, and checked before the set is
1255
+ taken: a write by vex's authoring lint, and the reach an entry declares by
1256
+ the check boot runs. Refused, the promise rejects with what was found
1257
+ (`Refresh refused — entries that do not parse:`, with the place and what
1258
+ was expected there) and nothing changed. Sets handed over at the same
1259
+ moment are taken in the order they were handed over. Accepted, the next request replays
1260
+ it, the set is frozen, living shells adopt and the pointer moves, as for a
1261
+ set of actions. Like one, **the set is handed to this process, and no other
1262
+ process is handed it** ([Many processes](#many-processes)). An app that
1263
+ hands over actions and the entries they replay hands the entries first.
742
1264
  - `actions(): Readonly<Record<string, ActionDefinition>>` — the actions in
743
1265
  force now, by id: what the app shipped, then each set handed over. To read;
744
1266
  a set changes through `replaceActions`.
1267
+ - `defaults(publisher): SessionArtifacts` — what is published for everybody,
1268
+ with the five calls a session's `artifacts` has (`save`, `list`, `history`,
1269
+ `restore`, `reset`), the same kinds and the same bodies. A published default
1270
+ is drawn, opened or replayed by everybody, nobody signed in included, under
1271
+ what a person has of their own; every publish is a version, and a `reset`
1272
+ shows the build's again. **A layout:** `server.defaults(who).save([{ kind:
1273
+ 'layout', body: { ref: 'action/<id>', layout, use: true } }])` is drawn under
1274
+ that action's ref unless its principal has a layout of their own in use or
1275
+ their roles hold a layout variant; `ref: 'frame'` and `ref: 'canvas/<id>'`
1276
+ publish the layouts of the app's own shell. **An action or a fragment** is
1277
+ given its id by whoever publishes it, as a shipped one has one: `save([{
1278
+ kind: 'action', id: 'promo', body }])`; one without an id is refused, and so
1279
+ is one under `generated.`. The charter grants it by that id, so a new id
1280
+ needs a grant and one that is a shipped action's or fragment's replaces the
1281
+ build's for everybody until it is reset. **A read** vex wrote is published
1282
+ under its fingerprint, `save([{ kind: 'read', id: '<fingerprint>' }])`, and is
1283
+ answered to everybody after what the caller saved themselves; one under the
1284
+ fingerprint of a shipped entry is refused. `publisher` is who the publish is
1285
+ made by, kept with the save (`artifact_saves.created_by`); an empty one is
1286
+ refused.
1287
+ **No session can publish.** The rows are those of one principal no caller
1288
+ is (`*`), and every write a session makes carries its own `userId`: vex's
1289
+ row rule, the one a person's own rows are under. Only the app's own code on
1290
+ the server reaches this call, as it reaches `replaceActions`. **Who may
1291
+ publish is the charter's**: the app puts the call in a function, hands it
1292
+ the session's principal as `publisher`, and grants the action that calls
1293
+ that function to the roles that may. A function is declared before the
1294
+ server exists, so the app keeps the server where its functions can reach it.
1295
+ **What is published is checked three times.** At the publish, as a person's
1296
+ save is: a layout against every action in force and every shell's kit, an
1297
+ action or a fragment as a generated one is, as the publisher (its `fn:`
1298
+ calls are ones the publisher's roles grant, its reads ones they may replay,
1299
+ no write), and then the whole as a manifest, as a set handed over is:
1300
+ `Publish refused — actions call functions the app does not have, or that
1301
+ their holders’ charter does not grant:` lists a holder whose roles do not
1302
+ grant a call. When the rows are read, the same again, and what does not pass
1303
+ any more is left out with a line, said once for each read of the rows: a
1304
+ layout, an action or a fragment on its own where its own check refuses it
1305
+ (`[moss] the action "…" published for everybody is left out: …`), and the
1306
+ actions and fragments all together where the manifest refuses them (`[moss]
1307
+ what is published for everybody is left out, and the build’s copies stand:
1308
+ …`). Once `checkFunctions` has read the app's functions, the rows are read
1309
+ again against them: a published action calling a function a new build
1310
+ dropped is left out, and the boot is not refused. When a shell is built, for
1311
+ that shell and that principal: a layout for an action they do not hold is
1312
+ not loaded, and a published fragment a shell cannot draw is left out of that
1313
+ shell (`[moss] the fragment "…" published for everybody is left out of a
1314
+ shell that cannot draw it: …`).
1315
+ One read of the rows answers every shell a process builds, and every save a
1316
+ session makes. A boot makes it, and fails if it cannot. The first shell built
1317
+ after this process publishes, or after the generation pointer moves, makes it
1318
+ again, and a read that fails fails that shell and is made again by the next.
1319
+ A publish has every living shell adopt, as `refresh` does, and moves the
1320
+ pointer, whether or not the rows can be read back: every other process on
1321
+ the same database follows the pointer and reads them.
745
1322
  - `catalogOf(principal): Promise<{ ids, hash }>` — what a principal holds of the
746
1323
  actions in force: `{ ids, hash }`, the granted action ids sorted, with a
747
1324
  content-hash version token (equal hash, equal application). The principal is
@@ -788,7 +1365,7 @@ It's a Hono app — mount it, extend it, or hand it to a listener.
788
1365
  `expired` the ones found older than `sessionRevalidateMs` and resolved
789
1366
  again.
790
1367
  - `executeAs(role, fingerprint, context, scope?): Promise<unknown>` — execute a
791
- seeded entry as a declared charter role, for surfaces with no principal by
1368
+ entry the app serves as a declared charter role, for surfaces with no principal by
792
1369
  nature. In-process only, replay-only, policy compiled from that role, scope
793
1370
  values supplied by server code. Its type is exported as `ExecuteAs`, for
794
1371
  code that is handed the function and no server. It answers the entry's
@@ -871,18 +1448,21 @@ is live when something on it can still happen:
871
1448
  | it waits on a channel | a `message:` trigger |
872
1449
  | a read keeps answering | an endpoint whose entry is `refresh: 'reactive'` |
873
1450
  | 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 |
1451
+ | it cannot be read | a `layout` that is the name of a stored layout; a fingerprint the manifest does not carry |
1452
+
1453
+ What can be pressed is read off the layout a screen is drawn with: a `{ ref }`
1454
+ in it, the one an action's own layout is named by included, is read through
1455
+ to the layout the shell's store holds under it.
875
1456
 
876
1457
  A read made while the action opened is **finished**: its answer is in the tree
877
1458
  (and listed in `drawnWith`). The app's own shell is always live for a signed-in
878
1459
  principal — it is the thing that is kept. nova supplies the facts
879
1460
  (`livenessOf`, `@niscorp/nova/reflect`); moss composes the verdict, because
880
- the running manifest holds the entries the app shipped, by fingerprint
1461
+ the running manifest holds the entries in force, by fingerprint
881
1462
  (`src/shells/snapshot.ts`; the function is not exported, its answer is
882
1463
  `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.
1464
+ the cache table, which can hold more: a fingerprint the running manifest does
1465
+ not hold (a query written by `answerIntent`) is the last line of the table.
886
1466
 
887
1467
  When `live` is false the trees are the whole of the screen, and the terminal
888
1468
  opens no socket.
@@ -991,7 +1571,7 @@ A page that is `live` is still written, and says why — its file is a true firs
991
1571
  screen and its terminal will look for a socket. Whether that is acceptable (a
992
1572
  server stands beside the files) or a mistake (there is none) is the build's to
993
1573
  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
1574
+ paths (`server.executeAs` runs a read the app serves as a charter role), are the
995
1575
  caller's.
996
1576
 
997
1577
  `renderDocument` is the one way a page is drawn, and its parts are not
@@ -1171,11 +1751,14 @@ tables changed, so a reactive read over one of them answers again.
1171
1751
  - `runtime.fabric` — `{ publish(message), subscribe(apply) }`, the
1172
1752
  host's transport (Postgres `LISTEN/NOTIFY` is the expected one; the type is
1173
1753
  `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-tag` and `nudge` — what `server.invalidateIdentity`,
1178
- `invalidateTag` and `nudge` publish after applying locally. Best-effort:
1754
+ message is one of the four below with `origin`, the process that
1755
+ sent it, which moss stamps and checks. Three are what
1756
+ `server.invalidateIdentity`, `invalidateTag` and `nudge` publish after
1757
+ applying locally: `invalidate-identity`, `invalidate-tag` and `nudge`. The
1758
+ fourth, `adopt`, names a principal and tells a process to bring the shells
1759
+ it holds for them level with what they hold now; moss publishes it when a
1760
+ layout is saved for that principal (`session.artifacts`), and it says
1761
+ nothing of what was saved. Best-effort:
1179
1762
  each targets state that heals on its own clock. Unset, every path behaves as
1180
1763
  in one process. The wiring is `src/server/signals.ts`; it is the server's
1181
1764
  own and is not exported.
@@ -1193,25 +1776,27 @@ tables changed, so a reactive read over one of them answers again.
1193
1776
  logged with what was wrong with it and nothing it carried
1194
1777
  (`[moss:fabric] the transport handed over what is not a message…`); the ones
1195
1778
  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
1779
+ - The generation pointer — the persistent counter `server.refresh()`,
1780
+ `server.replaceActions()`, `server.replaceEntries()` and a publish
1781
+ (`server.defaults`) move (`moss_generation`, one row, part of
1198
1782
  `MOSS_SEQUENCE`). Each process polls it (on `sessionRevalidateMs`; 60s when
1199
1783
  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
1784
+ it has a loader for, drops what it had read of what is published for
1785
+ everybody (the next shell it builds reads that again), runs the check
1786
+ boot runs over what it would then serve, drops what it derived (what each set of roles holds, the compiled
1202
1787
  policies, the identity records) and has its living shells adopt.
1203
1788
  **The pointer carries no set.** It says that something changed, and a
1204
1789
  process learns what by reading rows. The only set that has a loader is the
1205
1790
  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
1791
+ `server.replaceActions` or `server.replaceEntries` in one process is in that
1792
+ process's memory: every other process reaches the same generation and goes
1793
+ on serving the set of that name it was last handed itself, or none. So an
1794
+ app that runs several processes hands the set to each of them, on a signal
1795
+ of its own. Each call moves the pointer once more, and the others drop
1211
1796
  what they derived and adopt again.
1212
1797
  The row is read and moved through vex, by two
1213
1798
  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
1799
+ `src/artifactory/generation.ts` holds the clock and no SQL. A move is a compare
1215
1800
  and a set: the next number is written where the counter is still what was
1216
1801
  read, and read again where it is not. A move a process could not follow is
1217
1802
  tried again at every poll until it is followed, and logged when that is
@@ -1286,8 +1871,8 @@ app that resolves people through `identity`.
1286
1871
  grants recompiled at that named profile. The vex surfaces and `executeAs` do
1287
1872
  it themselves; it narrows rows, never widens verbs.
1288
1873
  - 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.
1874
+ action's layout where a shell is built, in the shell's layout store.
1875
+ Nothing answers the variants by themselves.
1291
1876
  - `verifyApp(app, grants)` — the check boot runs, for an app
1292
1877
  that is not booted (a check, a build step): the charter with each role's
1293
1878
  closure audited, every entry's reach, the layout variants. It reads `charter`,
@@ -1328,17 +1913,20 @@ for (const error of report.errors) console.error(`${error.check}: ${error.detail
1328
1913
  is not exported). It is handed no manifest and no
1329
1914
  runtime, but a typed object of what it needs: one function that answers what
1330
1915
  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
1916
+ hold, the canvases and the frame, each naming its layout in the layout
1917
+ store, the layout store's seed with those layouts in it (for an action the
1918
+ published one over the build's, their roles' layout variant over that, and
1919
+ over it the layout of their own they marked in use), the
1920
+ fragments, the entries, the component names), the
1333
1921
  app's code a shell calls (`inputs`, `seeds`, `phrases`, `functions`,
1334
1922
  `onSession`, `runs`), the wire for a token, and its limits. Everything in
1335
1923
  that answer but who somebody is comes from the running manifest, which is
1336
1924
  asked once for each build and once for each adopt
1337
- (`src/manifest/artifacts.ts`): an action, a layout, a fragment and an entry
1925
+ (`artifactsFor`, `src/artifactory/running.ts`): an action, a layout, a fragment and an entry
1338
1926
  reach a shell through that one answer, and the server's wiring reads none
1339
1927
  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`).
1928
+ on its screens. What a read replays the engine asks the running manifest
1929
+ for too (see "Where the app's entries are held", under `createServer`).
1342
1930
  A kept shell may sit unattached for
1343
1931
  `runtime.shellIdleMs` (default 30 minutes; `0` disables the sweep). A shell
1344
1932
  that is not kept (nobody signed in; any shell of a page's host) ends when
@@ -1364,21 +1952,28 @@ for (const error of report.errors) console.error(`${error.check}: ${error.detail
1364
1952
  - A host has no `adopt` and no `stop`. Each was a second way, for one
1365
1953
  host, to something a server does for all of them at once.
1366
1954
  **A change is the server's.** When what the app consists of changes
1367
- (`server.refresh()`, `server.replaceActions()`, an integration approved
1955
+ (`server.refresh()`, `server.replaceActions()`, `server.replaceEntries()`, an integration approved
1368
1956
  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
1957
+ 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
1958
  place. Every living shell: the ones a host keeps, and the ones it built
1371
1959
  for one connection, which for the app's host is each visitor's and for a
1372
1960
  page's host is everybody's. Definitions that arrived or changed are
1373
1961
  registered and mounted instances keep their state; one that left, or is no
1374
1962
  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
1963
+ layouts are taken from the same answer: each `{ ref }` of the layout
1964
+ store and each fragment that is answered differently from the last time
1965
+ is put in place, and every attached terminal is sent the frame. The
1966
+ shell's layout, a canvas's and an
1967
+ action's own layout are each one of those refs, so a screen that is open shows a
1968
+ layout that changed, with its data kept, and a ref that is answered no
1969
+ longer is taken out of the store. One
1378
1970
  that is answered as it was is left alone, so a ref the shell's own code
1379
1971
  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
1972
+ it. The canvases a shell's manifest declares, and what is mounted on any
1973
+ canvas, are the shell's own state and are not taken again: a reset builds
1974
+ that afresh. A canvas the manifest does not declare, that a layout in
1975
+ force held a slot for, is taken out by an adopt, with what is mounted on
1976
+ it, once no layout holds the slot. A
1382
1977
  shell that cannot adopt is logged and keeps what it held; the rest go on.
1383
1978
  Each shell adopts on its own: one whose principal is never answered (an
1384
1979
  `identity` that hangs for them) holds up no other. So a change asks about