@niscorp/moss 0.2.1 → 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 +7 -0
- package/DESIGN.md +10 -4
- package/DOCS.md +311 -39
- package/README.md +23 -14
- package/dist/{document-BEn2zXah.d.cts → document-Chfu7uNX.d.cts} +7 -0
- package/dist/{document-BEn2zXah.d.ts → document-Chfu7uNX.d.ts} +7 -0
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +2 -2
- package/dist/index.d.ts +2 -2
- package/dist/index.js.map +1 -1
- package/dist/node.d.cts +1 -1
- package/dist/node.d.ts +1 -1
- package/dist/terminal/dom/server.cjs.map +1 -1
- package/dist/terminal/dom/server.js.map +1 -1
- package/dist/vite.d.cts +1 -1
- package/dist/vite.d.ts +1 -1
- package/package.json +13 -13
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,12 @@
|
|
|
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
|
+
|
|
3
10
|
## 0.2.1
|
|
4
11
|
|
|
5
12
|
### 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)`
|
|
307
|
-
|
|
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.
|
|
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
|
-
|
|
4
|
-
listener
|
|
5
|
-
|
|
6
|
-
`@niscorp/moss/terminal
|
|
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
|
|
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
|
|
35
|
-
|
|
36
|
-
`
|
|
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
|
|
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 }) =>
|
|
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
|
-
|
|
56
|
-
|
|
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
|
|
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
|
|
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
|
|
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.
|
|
216
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
874
|
-
|
|
875
|
-
|
|
876
|
-
|
|
877
|
-
|
|
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
|
|