@niscorp/moss 0.2.1 → 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,19 @@
1
1
  # @niscorp/moss
2
2
 
3
+ ## 0.2.3
4
+
5
+ ### Patch Changes
6
+
7
+ - 48da7db: `mountSite` answers a missing file with 404. A name with an extension that is neither a file in `dist` nor a page of the manifest used to fall through to the catch-all and come back as the drawn page with a 200 — so a browser holding a page from before a deploy asked for its old script and was handed a document. A page whose own path has a dot in it (`/docs/v1.2`) is still that page.
8
+ - 80e1ee8: Documentation: the packages are live, and releases are compatible. `STYLE_GUIDE.md` gains "The packages are live" — a release does not break an app that works on the one before it; what should go is deprecated and stays; a breaking change is a last resort that needs the maintainer's approval before it is written — and `AGENTS.md` points every agent changing nisc itself to it. The status lines that said "pre-1.0, breaking changes expected" (nova), "API is pre-1.0 and moves" (moss) and "everything else may move" (tide) now say the same. moss's deprecated `installedIntegrations` is no longer described as scheduled for removal: it stays on the type. The style guide's Node floor is corrected to 22.12, what every package's `engines` already says. No code changes.
9
+
10
+ ## 0.2.2
11
+
12
+ ### Patch Changes
13
+
14
+ - 633d0d1: Docs: `domTarget` no longer redraws the page on every wire update — with a nova that keeps what did not change, an update costs what changed and nothing on the page loses its focus, scroll or animation to it. No change to moss's own code.
15
+ - 45d6731: `installedIntegrations` on the manifest is marked deprecated: the server never called it. Which integrations are live for a principal's tenant is `installed` on the record `identity.resolve` returns.
16
+
3
17
  ## 0.2.1
4
18
 
5
19
  ### Patch Changes
package/DESIGN.md CHANGED
@@ -144,7 +144,8 @@ canvas's tree), `render-delta` (the same tree, against the last one — opt-in,
144
144
  see below), `session` (a login grant), `error`. **Up:** `event` (a
145
145
  canvas-tagged `NovaEvent`), `publish` (a channel message), `resync` (this
146
146
  connection's copy of a canvas drifted; send whole frames), `back` (undo the
147
- last navigation).
147
+ last navigation), `popTo` (jump to an instance already on a canvas's stack),
148
+ `reset` (below).
148
149
 
149
150
  Operational shape, all falling out of "the message is state, not history":
150
151
 
@@ -303,8 +304,9 @@ the shell for the life of the process.
303
304
  The shell is built from the manifest: canvases and fragments are data; a canvas's
304
305
  `initial` may be a candidate list, and the first action the principal holds
305
306
  mounts — so login is the anonymous principal's application (the charter's
306
- `public` grant) by derivation, not a special case. `inputs(session)` is the app's
307
- one per-principal boot hook. Endpoint calls ride the server's own HTTP surfaces
307
+ `public` grant) by derivation, not a special case. `inputs(session)` and
308
+ `seeds(session)` are the app's per-principal boot hooks — boot data and boot
309
+ instances. Endpoint calls ride the server's own HTTP surfaces
308
310
  with the session's token — the server shell is just another principal-bound
309
311
  client, enforcement included.
310
312
 
@@ -564,7 +566,11 @@ On the record, so nothing reads as finished that isn't:
564
566
  the catalog itself streams: serve the graph neighborhood of a principal's
565
567
  active actions now, fault the rest in on demand. Level streaming for humans is
566
568
  context management for models — one mechanism, two products.
567
- - **Scale-out** beyond sticky sessions pinned by session id. A drawn document
569
+ - **Scale-out** beyond sticky sessions pinned by session id. What crosses
570
+ processes today is invalidation only: `refresh` moves a generation pointer
571
+ every process polls (`src/generation.ts`), and an optional fabric
572
+ (`runtime.fabric`, `src/fabric.ts`) carries identity invalidations and nudges.
573
+ A shell is still resident in one process. A drawn document
568
574
  adds one requirement to stickiness: the page request and the socket should
569
575
  land on the same process, or a principal's shell is built twice and the page
570
576
  repaints once.
package/DOCS.md CHANGED
@@ -1,9 +1,18 @@
1
1
  # Moss — API Reference
2
2
 
3
- Seven entry points: `@niscorp/moss` (the server), `@niscorp/moss/node` (the Node
4
- listener), `@niscorp/moss/client` (the wire), `@niscorp/moss/terminal` (the
5
- terminal), `@niscorp/moss/terminal/react`, `@niscorp/moss/terminal/vue` and
6
- `@niscorp/moss/terminal/dom` (the render targets). API is pre-1.0 and moves.
3
+ Fourteen entry points: `@niscorp/moss` (the server), `@niscorp/moss/node` (the
4
+ Node listener and the built site), `@niscorp/moss/vite` (the dev plugin),
5
+ `@niscorp/moss/client` and `@niscorp/moss/client/node` (the wire and its Node
6
+ host), `@niscorp/moss/terminal` (the terminal), and the render targets:
7
+ `terminal/react`, `terminal/vue`, `terminal/dom` (each with a `/server` entry
8
+ that draws to a string), `terminal/tty` and `terminal/ink`. The version is below 1.0 and
9
+ the package is live on npm all the same: what is documented here keeps working
10
+ from one release to the next, and what should go is deprecated, not removed.
11
+
12
+ The nisc packages (`charter`, `nova`, `prism`, `strata`, `tide`, `vex`) and
13
+ `zod` are required peers. `react`/`react-dom`, `vue`, `ink` and `vite` are
14
+ optional peers, needed only by the entry that names them. `hono`,
15
+ `@hono/node-server` and `ws` are moss's own dependencies.
7
16
 
8
17
  ## `@niscorp/moss`
9
18
 
@@ -19,7 +28,8 @@ besides its artifacts.
19
28
  ```typescript
20
29
  type NiscApp = {
21
30
  charter: Charter; // resolved per principal
22
- assignments: Record<string, readonly string[]>; // principal → roles
31
+ assignments?: Record<string, readonly string[]>; // principal → roles (authored; or `identity`)
32
+ wearable?: readonly (readonly string[])[]; // the role combinations one principal may wear
23
33
  actions: Record<string, ActionDefinition>; // the app's actions
24
34
  layouts?: Record<string, LayoutVariant>; // ring 2: variant id → { action, layout }
25
35
  behaviors?: ScopeBehaviors; // row-level scope semantics, per table or per profile
@@ -27,16 +37,67 @@ type NiscApp = {
27
37
  resources?: Record<string, readonly string[] | { entities: readonly string[] }>;
28
38
  shell?: ShellManifest; // the server shell, as data — THE APP
29
39
  pages?: Record<string, PageManifest>; // what is drawn at a path and kept by nothing
40
+ grammars?: readonly Sequence[]; // the app's own strata grammar sequences
41
+ // the code seams
42
+ scope?: (principal: string | null, identity?: IdentityRecord) => Record<string, unknown>;
43
+ identity?: { as?: string; resolve: (principal, read) => Promise<IdentityRecord> };
44
+ phrases?: (session) => Phrasebook | undefined | Promise<Phrasebook | undefined>;
45
+ phraseKeys?: PhraseKeys;
30
46
  functions?: (session: FunctionSession) => Record<string, FunctionHandler>;
47
+ onSession?: (session: FunctionSession) => void;
48
+ runs?: RunSink;
49
+ reactions?: readonly { table; op?; run }[]; // see "Reacting to writes"
50
+ facts?: { tide; identity; chain? }; // see "Reacting to writes"
51
+ // integrations (see "Integrations")
52
+ installedIntegrations?: (principal: string | null) => readonly string[] | Promise<readonly string[]>; // deprecated, never called
53
+ integrationActor?: (integration: string, actsFor: string) => string | null | Promise<string | null>;
54
+ attachable?: Record<string, Record<string, string>>;
55
+ menuSlots?: readonly string[];
56
+ assistantTools?: readonly string[];
57
+ publishChecks?: readonly string[];
58
+ editorRegions?: readonly string[];
59
+ placementNames?: Readonly<Record<string, string>>;
60
+ storePress?: StorePress;
31
61
  };
32
62
  ```
33
63
 
34
- Every field is an artifact (authored data) except `functions`, which is the code
35
- escape hatch. Absent `shell`, the app serves data only (no server shells). Absent
36
- `functions`, `fn:` endpoints fail loudly.
64
+ Every field is an artifact (authored data) except the code seams — `scope`,
65
+ `identity`, `phrases`, `functions`, `onSession`, `runs`, a reaction's `run`,
66
+ `facts`, and the integration hooks. Absent `shell`, the app serves data only
67
+ (no server shells). Absent `functions`, `fn:` endpoints fail loudly.
68
+
69
+ - `assignments` is optional: an app that declares `identity` answers roles per
70
+ principal and never builds the map. `wearable` declares the role
71
+ combinations the boot gates check; absent, they are derived from
72
+ `assignments` (`wearableOf`).
73
+ - `scope(principal, identity?)` — what a principal is beyond its id (a tenant,
74
+ an org). Moss always injects `{ userId }`; this contributes the rest, merged
75
+ server-side and asked per request, so a value derived from the clock is
76
+ never held for a session. Synchronous.
77
+ - `identity.resolve(principal, read)` — who a principal is, resolved once per
78
+ session and cached by moss (bounded by `runtime.identityMax` /
79
+ `identityIdleMs`, re-resolved every `sessionRevalidateMs`). Returns an
80
+ `IdentityRecord`: `{ roles, scope, installed?, tag? }`. `read(fingerprint,
81
+ scope)` executes a seeded entry through moss's engine, replay-only, under
82
+ the policy of the charter role `identity.as` names (it throws when `as` is
83
+ unset). Moss never reads inside the record's `scope`. Absent, `assignments`
84
+ and `scope` answer, and every registered integration is live for everybody.
85
+ - `onSession(session)` — called once per living app shell, for session code
86
+ that is not an endpoint (an observer, a roster). It runs before the shell
87
+ finishes building, so it must not touch `session.shell` synchronously. Its
88
+ return value is ignored. It does not run for a page.
89
+ - `runs: (record: RunRecord, session: FunctionSession) => void` — where model
90
+ runs go. Fed by `session.recordRun`; no default sink, unset means
91
+ unrecorded. A `RunRecord` carries `at`, `principal`, `shellId`, `agentId`,
92
+ `agentPath`, `label`, `provider`, `model`, the token counts, `reported`,
93
+ `steps`, `elapsedMs`, `outcome`, and optionally `turns: RunTurn[]` (the whole
94
+ exchange; a tool call and its result are two turns) and `response`.
95
+ - `grammars` — strata sequences for documents only this app defines the shape
96
+ of (its kit's component props). See "Documents are read in this code's
97
+ grammars" below.
37
98
 
38
99
  A `LayoutVariant` is `{ action: string; layout: LayoutNode }` — ring 2: the
39
- charter's `layouts` section selects who holds which variant id, and moss
100
+ charter's `layouts` section selects who is granted which variant id, and moss
40
101
  substitutes the granted variant's layout onto the definition at shell build. The
41
102
  base is the floor; variants enrich upward as grants.
42
103
 
@@ -46,14 +107,22 @@ base is the floor; variants enrich upward as grants.
46
107
  type ShellManifest = {
47
108
  canvases: ShellCanvas[]; // a canvas's `initial` may be a CANDIDATE list
48
109
  layout?: LayoutNode; // the frame — CanvasSlot markers, served verbatim
110
+ layoutStore?: Record<string, LayoutNode>; // what a `{ ref: id }` in the frame resolves to at boot
49
111
  fragments?: Record<string, ActionFragment>;
50
- inputs?: (session: { principal, actions, roles }) => Record<string, Record<string, unknown>>;
112
+ inputs?: (session: { principal, actions, roles, identity, wire }) =>
113
+ Record<string, Record<string, unknown>> | Promise<…>;
114
+ seeds?: (session: { principal, actions, roles, wire }) =>
115
+ Record<string, CanvasSeed[]> | Promise<…>;
51
116
  components?: Record<string, { meta?: { description?; propsSchema? } }>;
52
117
  };
53
118
  ```
54
119
 
55
- `inputs` is the app's one per-principal boot-derivation hook (nav flags, user
56
- chips), merged over each canvas's static seed.
120
+ Two per-principal boot hooks, both of which may be async and are handed the
121
+ session's governed `wire`. `inputs` derives boot **data** (nav flags, user
122
+ chips), merged over each canvas's static seed. `seeds` derives boot
123
+ **instances**: by canvas id, the actions to push, in order, ring-1-filtered
124
+ like every other mount — a seed the principal is not granted does not mount.
125
+ A `CanvasSeed` is an action id or `{ action, input?, with? }`.
57
126
 
58
127
  #### `PageManifest` — `app.pages`
59
128
 
@@ -72,8 +141,8 @@ go. It is the same machinery with the keeping taken out:
72
141
 
73
142
  - **The same actions and the same charter.** What exists on a page for a given
74
143
  person is ring 1, as everywhere: a strip saying who is signed in is an action
75
- a member is granted, on a canvas whose candidate list a stranger holds none
76
- of. Nothing in a layout asks who anybody is.
144
+ a member is granted, on a canvas whose candidate list a stranger is granted
145
+ none of. Nothing in a layout asks who anybody is.
77
146
  - **The same policy on every read.** A page's endpoints ride the server's own
78
147
  surfaces as whoever asked — nobody, or the signed-in principal.
79
148
  - **No shell is kept.** A page's shell lives for one read (the document) or one
@@ -100,13 +169,15 @@ out. Nothing downstream (the socket, the delta encoder, the terminal) learns a
100
169
  language exists.
101
170
 
102
171
  ```typescript
103
- phrases?: (principal: string | null) => Phrasebook | undefined; // source phrase → translation
172
+ phrases?: (session: { principal: string | null; identity: Record<string, unknown>; wire: FetchFn }) =>
173
+ Phrasebook | undefined | Promise<Phrasebook | undefined>; // source phrase → translation
104
174
  phraseKeys?: PhraseKeys; // which keys carry prose
105
175
  ```
106
176
 
107
177
  - Per **principal**, because a shell is per principal. Resolved once when the
108
178
  shell is built, so changing somebody's language is a `reset`/rebuild — exactly
109
- like changing their catalog.
179
+ like changing their catalog. May be async; it is handed the session's wire
180
+ and the scope half of the resolved identity, so a book can be read from rows.
110
181
  - Returning `undefined` or `{}` is the **source language** and costs nothing: the
111
182
  pass returns the same tree object and the frame serializes to the bytes it
112
183
  always did.
@@ -127,14 +198,21 @@ type FunctionSession = {
127
198
  shell: Shell; // the session's living, durable shell (a getter — a reset replaces it)
128
199
  principal: string | null;
129
200
  roles: readonly string[];
201
+ identity: Record<string, unknown>; // the scope half of the resolved identity
202
+ actions: readonly string[]; // the session's granted action ids, installs filtered
130
203
  wire: FetchFn; // the server's own surfaces, as this session
131
204
  runtime: NiscRuntime;
132
205
  policy: ScopePolicy; // the caller's compiled scope policy
133
206
  grant: (token: string) => void; // session GRANT (login): send it down, reconnect
134
- revoke: () => void; // session REVOKE (sign-out): close 4403, evict
207
+ revoke: () => Promise<void>; // session REVOKE (sign-out): close 4403, evict
208
+ recordRun: (run: Omit<RunRecord, 'at' | 'principal' | 'shellId'>) => void;
135
209
  };
136
210
  ```
137
211
 
212
+ `revoke` settles when the credential is gone: under `session: 'sessions'` it
213
+ deletes every session the principal has (`revokeAllFor`). `recordRun` is a
214
+ no-op when the manifest declares no `runs` sink.
215
+
138
216
  ### The environment
139
217
 
140
218
  #### `NiscRuntime`
@@ -145,13 +223,24 @@ type NiscRuntime = {
145
223
  db: MutationClient; // writes
146
224
  cache?: CacheBackend; // defaults to vex's postgres cache on `pool`
147
225
  session: SessionVerifier | 'sessions' | 'dev-open'; // REQUIRED — no default
226
+ migrations?: 'apply' | 'verify'; // the boot's ledgered run; default 'apply'
148
227
  shellIdleMs?: number; // idle shell eviction; default 30 min, `0` disables
228
+ endpointTimeoutMs?: number; // a server shell's endpoint call; default nova's, 30s
149
229
  sessionRevalidateMs?: number; // live-socket re-verify; default 60s, `0` disables
230
+ identityMax?: number; // resident identity records; default 10,000
231
+ identityIdleMs?: number; // drop an unread identity record; default 30 min, `0` disables
150
232
  shellFrameDelta?: boolean; // send changed canvases as deltas; default off
151
233
  socketCompression?: boolean | Record<string, unknown>; // permessage-deflate; default on
234
+ operatorKey?: string; // enables `/operator/*`; absent, every route there is 404
235
+ operatorGate?: (c: Context, next: Next) => Response | void | Promise<Response | void>;
236
+ fabric?: Fabric; // cross-process invalidations and nudges; default off
237
+ telemetry?: Telemetry; // one span sink; default off
238
+ signingSeed?: string; // dev only: a stable assertion signing keypair
152
239
  };
153
240
  ```
154
241
 
242
+ `SessionVerifier` is `(token: string) => string | null | Promise<string | null>`.
243
+
155
244
  `session` is required, deliberately — authentication is the one door that must
156
245
  not default open, and it used to. Three answers: `'sessions'` uses moss's own
157
246
  stored credential (below); `'dev-open'` trusts every well-formed token and says
@@ -168,6 +257,8 @@ the row (one token, or every token a principal holds). The app mints at its
168
257
  own door after its own identity check and hands the token to the terminal;
169
258
  its table (`SESSIONS_SEQUENCE`) rides `createServer` boot automatically under
170
259
  `'sessions'`. Expired rows are swept on every mint — no timer to run.
260
+ `sessionVerifierOf(runtime)` resolves the three-way `session` choice to a
261
+ `SessionVerifier`, and throws when the field is unset.
171
262
 
172
263
  **Tables go through a ledger.** moss creates no table on its own: its tables are
173
264
  [strata](../strata/README.md) sequences — `MOSS_SEQUENCE` (integrations, their
@@ -212,12 +303,35 @@ harness wants and a deployment must opt into out loud.
212
303
  Stands up the data layer, **refuses to boot** on an incoherent charter
213
304
  (`verifyCharter` + nova's closure audit), memoizes per-principal policy,
214
305
  catalogs, and ring-2 variant bindings, mounts the vex surfaces and `/catalog`, and — when the manifest
215
- declares a shell — the shell host behind the socket. Returns a Hono app extended
216
- with `{ socket, shells? }`.
306
+ declares a shell — the shell host behind the socket. Also refused at boot: an
307
+ entry whose `reach` names no profile the behaviors declare, and two pages that
308
+ could answer one path. Returns a Hono app extended with the `MossServer`
309
+ members below.
310
+
311
+ What the server answers over HTTP:
312
+
313
+ | Path | What |
314
+ |---|---|
315
+ | `GET /catalog` | `{ principal, actions, hash }` — the application, resolved for the caller |
316
+ | `/api/vex` | the vex surface over the full schema: locked (replay-only), scoped per principal |
317
+ | `/api/<resource>/vex` | the same, over one of `app.resources`' entity subgraphs |
318
+ | `/api/integrations/*` | `GET contract` (`?id=`, `?format=md`), `GET verify-key`, `POST frame` (mint a frame grant) |
319
+ | `/integrations/:id/*` | the proxy to an approved integration, as the signed-in caller; plus `frame/:token` (and `frame/:token/:call`) and `hook/*`, which take no session |
320
+ | `/operator/integrations` | list, register (`POST`), `:id/approve`, `:id/probe`, `DELETE :id` — keyed by `x-operator-key` |
321
+
322
+ The socket is not a Hono route: `server.socket` is fed by the runtime's
323
+ transport (`/socket` under `serve` and `attachSocket`). Every request is
324
+ identified once, from `Authorization: Bearer <token>`: a session token goes
325
+ through the `session` verifier (`401` when it does not resolve); a token with
326
+ the `ik_` prefix is an integration key, resolved with `x-nisc-acts-for`
327
+ through `app.integrationActor` (`401` unknown key, `403` no actor); no header
328
+ is the anonymous principal. There is no `/fns` surface.
217
329
 
218
330
  #### `MossServer`
219
331
 
220
- `Hono<Env> & { socket: SocketAccept; shells?: ShellHost; principalOf; page; … }`.
332
+ `Hono<Env> & { socket: SocketAccept; shells?: ShellHost; principalOf; page; pages;
333
+ refresh; invalidateIdentity; invalidateTenant; identity; executeAs;
334
+ callIntegration; nudge; generation; close; identities? }`.
221
335
  It's a Hono app — mount it, extend it, or hand it to a listener.
222
336
 
223
337
  - `principalOf(token): Promise<string | null>` — the deployment's own session
@@ -231,6 +345,39 @@ It's a Hono app — mount it, extend it, or hand it to a listener.
231
345
  (its name, the `ShellHost` that draws it, the input its path carries), or
232
346
  `undefined` for a path that is the app's. The document route and the socket
233
347
  ask the same question here.
348
+ - `refresh(): void` — artifacts changed at runtime (actions loaded from rows):
349
+ re-run the boot gates, drop every per-principal memo and identity record,
350
+ and have living shells adopt their re-resolved definitions in place. Throws
351
+ on an incoherent charter or variant set, and the old resolution keeps
352
+ serving. It also moves the generation pointer, so every other process on the
353
+ same database does the same within one poll.
354
+ - `generation(): number` — the generation this process last observed (`-1`
355
+ before the first read).
356
+ - `invalidateIdentity(principal): boolean` — forget one principal's identity
357
+ record and reset their shell (a role change). `false` = no record was held.
358
+ - `invalidateTenant(tag): number` — forget every identity record wearing the
359
+ tag the app put on it (`IdentityRecord.tag`); answers how many. Forgets, does
360
+ not reset shells.
361
+ - `identity(principal): Promise<IdentityRecord>` — the resolved record for one
362
+ principal, through the same cache the request path uses.
363
+ - `identities?: { list(): IdentityReport[]; meter() }` — the resident identity
364
+ roster (`{ principal, since, lastSeen }`) and what the cache costs
365
+ (`{ size, max, resolved, evicted, expired }`). Present only when the app
366
+ declares `identity`.
367
+ - `executeAs(role, fingerprint, context, scope?): Promise<unknown>` — execute a
368
+ seeded entry as a declared charter role, for surfaces with no principal by
369
+ nature. In-process only, replay-only, policy compiled from that role, scope
370
+ values supplied by server code.
371
+ - `callIntegration(id, path, { principal, method?, body?, scope? }):
372
+ Promise<Response>` — call an installed integration when nobody is driving;
373
+ throws unless it is approved and installed for the principal's tenant.
374
+ - `nudge(principal, channel): void` — publish, payload-less, onto one
375
+ principal's living shell, in whichever process holds it (local `deliver`,
376
+ then the fabric).
377
+ - `close(): void` — stop every timer the server started (the generation poll,
378
+ the identity sweep, socket revalidation, the shell idle sweeps). For a host
379
+ that retires a server in-process; every timer is unref'd, so a process that
380
+ boots once needs none of it.
234
381
 
235
382
  ### The document
236
383
 
@@ -447,7 +594,76 @@ Tide reads no clocks and paces nothing; this is the thing that does.
447
594
  before its own wake ran. It is how work is *recovered*, never how it moves.
448
595
 
449
596
  Hand `app.facts.tide` the **driver**, not bare tide, so a minted fact wakes
450
- the engine instead of waiting for somebody's beat.
597
+ the engine instead of waiting for somebody's beat. The driver is `{ ingest,
598
+ fire, wake, stop }`; `stop()` resolves once nothing it started still touches
599
+ the store. `config.now` replaces the clock; `janitorMs` defaults to 5 minutes;
600
+ absent `retention`, nothing is swept.
601
+
602
+ #### `createTideStore(pool, options?)` / `TIDE_SEQUENCE`
603
+
604
+ The Postgres store tide runs on, as a strata sequence (`TIDE_SEQUENCE`, tables
605
+ `TIDE_TABLES`). Returns a tide `TideStore` plus `ready: Promise<void>`.
606
+ `mintWrites` is the bridge the fact lane uses.
607
+
608
+ ### Integrations
609
+
610
+ A separate service registered with the deployment, whose actions join the
611
+ manifest once an operator approves them. The HTTP surfaces are listed under
612
+ [`createServer`](#createserverapp-runtime-promisemossserver); the operator seam
613
+ exists only when `runtime.operatorKey` is set.
614
+
615
+ - Manifest hooks: `installedIntegrations(principal)` (deprecated and never called — the
616
+ install list moss filters by is `IdentityRecord.installed`; absent = all), `integrationActor(integration,
617
+ actsFor)` (the principal a keyed call acts as; `null` refuses), `attachable`
618
+ and `menuSlots` (where an integration's actions may appear), `assistantTools`,
619
+ `publishChecks`, `editorRegions` (the names a bundle's declarations may use),
620
+ `placementNames`, `storePress` (where a bundle's listing images land).
621
+ - `runIntake(payload, ctx): IntakeResult` — validate a bundle:
622
+ `{ ok: true, bundle } | { ok: false, reasons }`.
623
+ - `initIntegrations(pool)`, `MOSS_SEQUENCE`, `listIntegrations(pool)`,
624
+ `loadIntegrationActions(pool, upgrader?)`, `integrationByKey(pool, key)`,
625
+ `listAttachments(pool, hostAction)`, `listPlacements(pool)` — the stored rows.
626
+ - `integrationOfAction(id)`, `filterInstalled(ids, installed)` — which
627
+ integration an action id belongs to, and the catalog filter.
628
+ - `buildContract(app, integrationId)`, `contractAsMarkdown(contract,
629
+ fingerprints)` — what `/api/integrations/contract` serves.
630
+ `describePlacements(bundle, names?)` — the placement sentence stored with an
631
+ integration's row at registration.
632
+ - `copyPress`, `callIntegrationWith` — the press copy at intake and the
633
+ machinery behind `server.callIntegration`.
634
+ - `createAssertionSigner(seed?)`, `verifyAssertion(token, verifyKey, now?)` —
635
+ the ed25519 assertion the proxy signs and an integration verifies.
636
+ `mintIntegrationKey()` (`ik_…`) and `hashIntegrationKey(key)` — the
637
+ integration's own credential, stored hashed.
638
+
639
+ ### Many processes
640
+
641
+ - `runtime.fabric: Fabric` — `{ publish(message), subscribe(apply) }`, the
642
+ host's transport (Postgres `LISTEN/NOTIFY` is the expected one). It carries
643
+ three signals to the other processes: `invalidate-identity`,
644
+ `invalidate-tenant` and `nudge` — what `server.invalidateIdentity`,
645
+ `invalidateTenant` and `nudge` publish after applying locally. Best-effort:
646
+ each targets state that heals on its own clock. Unset, every path behaves as
647
+ in one process. `wireFabric(fabric, origin, apply)` is the wiring, exported
648
+ for hosts that are not moss's server.
649
+ - `createGeneration(pool, { onMoved, everyMs? }): Generation` — the persistent
650
+ pointer `server.refresh()` moves (`moss_generation`, part of
651
+ `MOSS_SEQUENCE`). Each process polls it (`DEFAULT_GENERATION_POLL_MS`, 60s;
652
+ the server polls on `sessionRevalidateMs`) and drops its derivations when it
653
+ moves.
654
+ - `createIdentityCache(ctx): IdentityCache` — the cache behind `app.identity`:
655
+ `{ get, invalidate, invalidateAll, invalidateTag, list, meter, stop }`.
656
+ Defaults `DEFAULT_IDENTITY_MAX` and `DEFAULT_IDENTITY_IDLE_MS`.
657
+
658
+ ### Telemetry
659
+
660
+ `runtime.telemetry: { emit(span) }` — one sink, off by default. A
661
+ `TelemetrySpan` is `{ name, startUnixNano, endUnixNano, status: 'ok' | 'error' |
662
+ 'refused', attributes, traceId?, spanId?, parentSpanId? }`. Moss emits one per
663
+ vex execution, fn call, integration call, shell build, and socket upgrade and
664
+ close. `emitterOf(telemetry)` wraps a sink so a throwing one costs the caller
665
+ nothing (`undefined` when there is none); `spanClock()` stamps a start and
666
+ measures the end.
451
667
 
452
668
  ### Resolution (exposed for tools)
453
669
 
@@ -455,7 +671,7 @@ the engine instead of waiting for somebody's beat.
455
671
  unassigned wears `['public']`.
456
672
  - `resolvePolicy(app, grants, principal): ScopePolicy` — the compiled vex policy
457
673
  this principal reads and writes under. **One policy per role, merged** — a
458
- person may hold several (an instructor who also trains here), and reach belongs
674
+ person may wear several (an instructor who also trains here), and reach belongs
459
675
  to the role rather than to the person. The merge is a union: broadest wins.
460
676
  - `resolvePolicyAtReach(app, grants, principal, reach): ScopePolicy` — the same
461
677
  principal's grants recompiled under a named profile, for entries that declare
@@ -465,15 +681,31 @@ the engine instead of waiting for somebody's beat.
465
681
  sorted, with a content-hash version token (equal hash, equal application).
466
682
  - `resolveVariants(app, principal): ReadonlyMap<string, LayoutNode>` — action id →
467
683
  the granted variant's layout (ring 2; empty map = every action serves its base).
684
+ - `resolveCatalogForRoles(app, roles, installed)`, `resolveVariantsForRoles(app,
685
+ roles)`, `resolvePolicyForRoles(app, grants, roles)` — the same resolutions,
686
+ given roles rather than a principal, for a caller that already resolved who
687
+ somebody is (the `identity` seam). `resolveRoles`, `resolveCatalog` and the
688
+ other principal-taking forms read `assignments` only.
689
+ - `wearableOf(app): readonly (readonly string[])[]` — the role combinations the
690
+ app can produce: `app.wearable`, else derived from `assignments`, deduplicated.
691
+ - `memoKeyOf(app, principal): string` — the key the per-principal memos depend
692
+ on (roles + installed set), from `assignments` with no install list.
468
693
  - `verifyVariants(app): string[]` — the ring-2 boot gate: every variant reshapes a
469
- shipped action, and no wearable role combination holds two variants of one
470
- action. Non-empty = refuse to boot.
694
+ shipped action, and no wearable role combination is granted two variants of
695
+ one action. Non-empty = refuse to boot.
471
696
  - `createDataLayer(runtime, entries?): Promise<DataLayer>` — `{ engine, schema,
472
697
  grants }`, stood up from what's present.
473
698
  - `createShellHost(ctx): ShellHost` — the durable per-principal shell host.
474
699
  `ctx.idleMs` bounds how long a shell may sit unattached (default
475
700
  `DEFAULT_IDLE_MS`, 30 minutes; `0` disables the sweep).
476
- - `ShellHost` — `{ session, adopt, list, reset, stop }`.
701
+ - `ShellHost` — `{ session, snapshot, adopt, deliver, list, reset, stop }`.
702
+ - `session(token, principal, options?)` — `options = { seed?, inputs? }`
703
+ (`ShellOpening`); `snapshot` is described under [The document](#the-document).
704
+ - `adopt()` — every living durable shell re-registers its freshly resolved
705
+ granted definitions in place (what `server.refresh()` calls).
706
+ - `deliver(principal, channel, payload?): boolean` — publish into one
707
+ principal's living durable shell. `false` = they have no living shell;
708
+ nothing is built.
477
709
  - `list(): ShellReport[]` — every durable shell alive right now:
478
710
  `{ principal, connections, since, idleSince, canvases }`. moss owns the map,
479
711
  so moss enumerates it; an app keeping its own note beside it can only drift.
@@ -483,7 +715,7 @@ the engine instead of waiting for somebody's beat.
483
715
  - `stop()` — stop the idle sweep (the timer is unref'd, so a plain process
484
716
  needn't call it).
485
717
  - `ShellSession` — what `ShellHost.session(token, principal)` returns:
486
- `{ shell, attach, detach, resync, dispatch, publish, back, reset }`. The living nova `Shell`,
718
+ `{ shell, attach, detach, resync, dispatch, publish, back, popTo, reset }`. The living nova `Shell`,
487
719
  for in-process hosts (dev checks, embedded tools) that drive it directly;
488
720
  remote clients ride `attach`/`dispatch`. `shell` is a **getter** — `reset`
489
721
  replaces the shell under a session already held, so a snapshot of the field
@@ -495,7 +727,7 @@ the engine instead of waiting for somebody's beat.
495
727
  ### The socket protocol
496
728
 
497
729
  - `createSocket(ctx): SocketAccept` — `ctx = { session, catalog, shells?, page?,
498
- revalidateMs? }`. One `accept(url, connection)` per connection; `accept.stop()`
730
+ revalidateMs?, telemetry? }`. One `accept(url, connection)` per connection; `accept.stop()`
499
731
  ends revalidation (the timer is unref'd, so a plain process needn't call it).
500
732
  - **Identity is asked twice.** At upgrade, and then every `revalidateMs`
501
733
  (default `DEFAULT_REVALIDATE_MS`, 60s; `0` disables) for as long as the
@@ -513,7 +745,7 @@ the engine instead of waiting for somebody's beat.
513
745
  interface whose every load silently fails.
514
746
  - `Connection` — the transport seam: `{ send, close, onMessage, onClose }`.
515
747
  - `ServerMessage` — `hello | catalog | frame | render | render-delta | session | error`.
516
- - `ClientMessage` — `event | publish | resync | reset | back`.
748
+ - `ClientMessage` — `event | publish | resync | reset | back | popTo`.
517
749
  - `render-delta` is only ever sent to a connection that advertised `?delta=1`
518
750
  on the upgrade, and only when the server is configured for it. Everything
519
751
  else is served whole frames, unchanged. See [Wire size](#wire-size).
@@ -534,8 +766,17 @@ the engine instead of waiting for somebody's beat.
534
766
  by whatever canvases moved. Protocol-level, so a browser's back button, a
535
767
  TUI's Escape and an app's own control are one message on one wire, and an app
536
768
  authors nothing to receive it.
769
+ - `popTo` names a canvas and an instance already on its stack
770
+ (`{ type: 'popTo', canvas, instance }`): unmount everything above it, in one
771
+ step — a breadcrumb's jump, which several `back`s would race.
537
772
  - `CLOSE_INVALID_TOKEN = 4401`, `CLOSE_SIGNED_OUT = 4403`,
538
- `CLOSE_PROTOCOL_MISMATCH = 4426`.
773
+ `CLOSE_SHELL_FAILED = 4500`, `CLOSE_PROTOCOL_MISMATCH = 4426`. `4500` means
774
+ the server could not open a session for this connection (commonly a
775
+ definition failing validation): a `session_failed` error frame naming the
776
+ failing definitions, then the close. The refusal is that terminal's alone,
777
+ and reconnecting later is reasonable.
778
+ - `error` codes: `invalid_token`, `session_failed`, `client_too_old`,
779
+ `server_too_old`, `no_shell` (the app serves no shell), `invalid_message`.
539
780
  - **Protocol version.** `PROTOCOL` is the wire protocol this server speaks and
540
781
  `PROTOCOL_MIN` the oldest it still serves. A terminal names its protocol on
541
782
  the upgrade (`?protocol=N`, beside the token); one that names none speaks `1`,
@@ -544,7 +785,9 @@ the engine instead of waiting for somebody's beat.
544
785
  (`client_too_old` or `server_too_old`) and a `4426` close. `hello` carries
545
786
  `protocol`, so a terminal can refuse a server older than it can speak to.
546
787
  Bump `PROTOCOL` when a message changes shape; raise `PROTOCOL_MIN` only when
547
- the server stops speaking an old one.
788
+ the server stops speaking an old one. Both are `1` today. `PROTOCOL`,
789
+ `PROTOCOL_MIN` and `CLOSE_PROTOCOL_MISMATCH` are defined in `src/socket.ts`
790
+ and are not re-exported from the package root.
548
791
  - **`?path=`** — the path the terminal is on. A path that leads to a page is
549
792
  served that page's shell, built for this connection alone and seeded with the
550
793
  path's parameters; any other path (and no path) is the app's shell. A
@@ -592,7 +835,7 @@ copy runs from the old frame plus literal inserts, checksummed.
592
835
 
593
836
  ```typescript
594
837
  // server
595
- const server = await serve(app, { pool, db, shellFrameDelta: true });
838
+ const server = await serve(app, { pool, db, session: 'sessions', shellFrameDelta: true });
596
839
 
597
840
  // terminal — both ends have to want it
598
841
  const wire = createWire({ delta: true });
@@ -644,7 +887,39 @@ Correctness, which matters more than the saving:
644
887
  app's own for `/`, one of the manifest's pages for a path that leads to one.
645
888
  `index.html` itself never goes out as a file. Register the app's own routes
646
889
  first; this is the catch-all. `owned` (default: moss's own prefixes) names
647
- what is never a page — an unknown path under one is a 404, not a screen.
890
+ what is never a page — an unknown path under one is a 404, not a screen. So is
891
+ a **missing file**: a name with an extension that is neither a file in `dist`
892
+ nor a page of the manifest is answered 404 (a browser holding a page from
893
+ before a deploy asks for its script by the old name, and needs "gone" back,
894
+ not a document). A page's own path may have a dot in it (`/docs/v1.2`).
895
+ What a browser may keep of these files, and compressing what goes out, is not
896
+ said here: `nisc start` puts both around the whole server (`@niscorp/cli`,
897
+ "`nisc start`"). A host running its own listener over `mountSite` says them
898
+ itself.
899
+ - `MOSS_PATHS` — the prefixes the app server answers itself:
900
+ `/^\/(api|catalog|socket|operator|integrations)(\/|$)/`. The default `owned`
901
+ here and in the dev plugin.
902
+
903
+ ## `@niscorp/moss/vite`
904
+
905
+ Requires the optional `vite` peer.
906
+
907
+ - `mossDev(options): Plugin` — the app server inside vite's dev process
908
+ (serve only): no proxy and no second process. The socket is attached once to
909
+ vite's own http server; `/` and any path a page answers go out as
910
+ `index.html` through `transformIndexHtml` with the screen drawn in
911
+ (`renderDocument`); `MOSS_PATHS` go to the app server; the rest is vite's.
912
+ An edit under a watched path re-boots the whole app and reloads the page;
913
+ the outgoing server answers until the new one is up, and a failed re-boot
914
+ keeps it.
915
+ - `options.app(load): Promise<DevApp>` — stand the app up. `load` is vite's
916
+ `ssrLoadModule`. `DevApp = { server, close?, draw?, htmlAttributes?,
917
+ tokenKey?, signIn? }`; absent `draw`, pages go out undrawn.
918
+ - `signIn(who)` enables `/dev/as/<who>`: it stores the returned token (and
919
+ its cookie copy) and goes to `/`. `null` is nobody of that name.
920
+ - `watch?: RegExp` (default: `src/app`, `src/server`, `src/db`, `src/ui` and
921
+ the nisc config), `index?` (default `index.html`), `owned?` (default
922
+ `MOSS_PATHS`), `label?` (default `moss`).
648
923
 
649
924
  ## `@niscorp/moss/client`
650
925
 
@@ -668,7 +943,8 @@ Correctness, which matters more than the saving:
668
943
  token itself — so it adds no way in.
669
944
  - `readDocumentSnapshot(doc?): DocumentSnapshot | undefined` — the snapshot a
670
945
  server-drawn page carries (`{ frame, trees, principal, seed?, path?, live? }`),
671
- or `undefined` for a page that carries none. Never throws.
946
+ or `undefined` for a page that carries none. Never throws. `principal` is a
947
+ boolean — whether the page was drawn for somebody — never who.
672
948
  - `initial` — pass what `readDocumentSnapshot()` returned. The wire starts from
673
949
  it instead of from nothing, so the first render matches the page's HTML and
674
950
  the first frames off the socket confirm it. It is used only when it was drawn
@@ -681,7 +957,7 @@ Correctness, which matters more than the saving:
681
957
  is `false`, the wire does not connect and `status()` is `'static'`. `reset()`,
682
958
  or a token arriving, connects after all.
683
959
  - `Wire` — `{ subscribe, snapshot, status, dispatch(canvas, event), publish,
684
- reset, back, dispose }`. `snapshot()` is `{ frame, trees }`; `status()` is
960
+ reset, back, popTo(canvas, instance), dispose }`. `snapshot()` is `{ frame, trees }`; `status()` is
685
961
  `'connecting' | 'open' | 'closed' | 'incompatible' | 'static'` and changes notify subscribers like
686
962
  snapshot changes do (a renderer must be able to tell a dead socket from an
687
963
  empty app). Hand it to a renderer.
@@ -859,7 +1135,7 @@ Requires the optional `vue` peer.
859
1135
  as props and the content as its default slot.
860
1136
  - **Adoption**, as the react target: a root that holds server-drawn elements,
861
1137
  on a wire with a frame, is mounted with `createSSRApp` and adopted.
862
- - `registerWireSlots(registry, slotWrapper?)`, `terminalFrame(api, registry)` —
1138
+ - `registerWireSlots(registry, slotWrapper)`, `terminalFrame(api, registry)` —
863
1139
  the wire slots and the frame component, shared with the server entry.
864
1140
 
865
1141
  ### `@niscorp/moss/terminal/vue/server`
@@ -870,11 +1146,16 @@ Requires the optional `vue` peer.
870
1146
 
871
1147
  ## `@niscorp/moss/terminal/dom`
872
1148
 
873
- - `domTarget({ root, registry? }): Target` — nova's DOM adapter plus nova's
874
- default component kit rendered into `root`, stylesheet injected once per
875
- document. Zero framework; pass a registry to restyle. It needs no adoption:
876
- nova's DOM adapter rebuilds its root on every render, so its first render
877
- replaces server-drawn elements with the same elements in one synchronous step.
1149
+ - `domTarget({ root, registry? }): Target` — nova's DOM adapter rendered into
1150
+ `root`. Omit `registry` for nova's default component kit, with its
1151
+ stylesheet injected once per document and its class on the root; pass your
1152
+ own and nothing is injected — the look is the app's. Zero framework. It needs no adoption:
1153
+ the first render of nova's DOM adapter replaces server-drawn elements with
1154
+ the same elements in one synchronous step. Every render after it patches: an
1155
+ element whose part of the tree did not change is the same node, so a wire
1156
+ update costs what changed and nothing on the page loses its focus, scroll or
1157
+ animation to it (nova's ADAPTER.md, "The DOM adapter keeps what did not
1158
+ change").
878
1159
 
879
1160
  ### `@niscorp/moss/terminal/dom/server`
880
1161