@niscorp/moss 0.2.0 → 0.2.2

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