@niscorp/nisc 0.10.0 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/AGENTS.md CHANGED
@@ -1,16 +1,22 @@
1
1
  # Building an application on nisc
2
2
 
3
- > **Reading this from `node_modules/@niscorp/nisc/`?** It is the rulebook for the nisc version installed beside it, shipped with it. Where it names a path in the nisc repository, look here instead: `packages/<name>/README.md` and `DESIGN.md` are `node_modules/@niscorp/<name>/`; `/STYLE_GUIDE.md` is beside this file; the lab apps it holds up as examples (`apps/lab/lyceum`, …) and `docs/` are at [github.com/moccadroid/niscorp](https://github.com/moccadroid/niscorp). An app made by `npm create nisc` points its own `AGENTS.md` here.
3
+ > **Reading this from `node_modules/@niscorp/nisc/`?** It is the rulebook for the nisc version installed beside it, shipped with it. Where it names a path in the nisc repository, look here instead: `packages/<name>/README.md` and `DESIGN.md` are `node_modules/@niscorp/<name>/`; the lab apps it points to as examples (`apps/lab/lyceum`, …) and `docs/` are at [github.com/moccadroid/niscorp](https://github.com/moccadroid/niscorp). An app made by `npm create nisc` points its own `AGENTS.md` here.
4
4
 
5
- > **Changing nisc itself — a package, not an app built on it?** The `@niscorp` packages are live on npm and may be in use by third parties. No change may break an app that works today, and a breaking change is never yours to decide: it is a last resort that needs the maintainer's explicit approval *before* it is written. Read `/STYLE_GUIDE.md`, "The packages are live", first, and then the last part of this file, "Changing a package": where a new thing goes, and the builds that fail when it goes somewhere else.
5
+ > **Changing nisc itself — a package, not an app built on it?** The `@niscorp` packages are live on npm and may be in use by third parties. No change may break an app that works today, and a breaking change is never yours to decide: it is a last resort that needs the maintainer's explicit approval *before* it is written. Read `STYLE_GUIDE.md`, beside this file, "The packages are live", first, and then `CHANGING_A_PACKAGE.md`, beside this file (`packages/nisc/` in the repository): where a new thing goes, and the builds that fail when it goes somewhere else.
6
6
 
7
7
  > **Build with this file; review with `REVIEW.md`, beside it.** A review checks the app's shape — reads replayed as entries, words in Prism, the charter gating what a person reaches — which the app's own checks do not see. Run one after each step of the order of work, not only at the end: drift found early is one file, found late it is everything built on it.
8
8
 
9
- For agents generating or reviewing a nisc application. This file states the application-level rules, and it presumes no app that came before it — but it is not the whole specification. The **grammars** live in the package docs, and they are required reading, not background: a layout node, an `ActionDefinition`, a Prism config, a charter document and a Vex DSL are each defined in their own package's `README.md` and `DESIGN.md`. Read the doc for a package before authoring that package's artifact. This file governs how they compose into an application.
9
+ For agents generating or reviewing a nisc application. This file states the application-level rules, and it presumes no app that came before it. It is not the whole specification:
10
+
11
+ - The **grammars** are in the package docs, and they are required reading, not background. A layout node, an `ActionDefinition`, a Prism config, a charter document and a Vex DSL are each defined in their own package's `README.md`, `DESIGN.md` and reference docs (`DOCS.md`; nova's `ACTION_DOCS.md`, `LAYOUT_DOCS.md` and the rest).
12
+ - Read the docs of a package before authoring that package's artifact.
13
+ - This file governs how they compose into an application.
10
14
 
11
15
  ## The thesis
12
16
 
13
- Everything the app does is data with a schema. An action is JSON. A layout is JSON. A transform is JSON. A query is JSON. A mutation is JSON. A charter is JSON. A plan is JSON. Each artifact is validated by a Zod schema at the boundary and executed by a runtime; nothing executable is a code string. Imperative TypeScript exists only at the edges, and only as:
17
+ Everything the app does is data with a schema. An action, a layout, a transform, a query, a mutation, a charter and a plan are each JSON. Each artifact is validated by a Zod schema at the boundary and executed by a runtime; nothing executable is a code string.
18
+
19
+ Imperative TypeScript exists only at the edges, and only as:
14
20
 
15
21
  1. a **renderer primitive** — a registry component: props in, events out;
16
22
  2. an **endpoint** — real data access behind a URL or registered function;
@@ -20,27 +26,45 @@ Everything the app does is data with a schema. An action is JSON. A layout is JS
20
26
 
21
27
  Code that is none of these — a React feature component, a fetch-and-massage helper, an inline formatter — is a discipline break.
22
28
 
23
- The mental model for the UI: **shells host canvases, canvases host action instances, actions render JSON layouts.** There are no screens. Chrome, lists, forms, dialogs, dashboards — all of them are actions loaded onto canvases. How actions are arranged across canvases is a design choice.
29
+ **The UI: shells host canvases, canvases host action instances, actions render JSON layouts.** There are no screens. Chrome, lists, forms, dialogs, dashboards — all of them are actions loaded onto canvases. How actions are arranged across canvases is a design choice.
30
+
31
+ A canvas keeps its instances in one of two modes:
24
32
 
25
- A canvas holds its instances in one of two modes. `stack` (the default) is a card deck: the top instance is active, the rest suspended, and the canvas renders the top alone — menu → list → detail → form, with Back real. `list` is a tray: every instance stays live and the canvas renders them all through an `actionLayout` that loops `$.instances` into `ActionSlot`s. A list canvas is how a surface gets *composed* rather than drawn — nobody hand-authors a launcher; the actions render themselves.
33
+ - `stack` (the default) is a card deck: the top instance is active, the rest suspended, and the canvas renders the top alone — menu → list → detail → form, with Back real.
34
+ - `list` is a tray: every instance stays live and the canvas renders them all through an `actionLayout` that loops `$.instances` into `ActionSlot`s. A list canvas is how a surface gets *composed* rather than drawn — nobody hand-authors a launcher; the actions render themselves.
26
35
 
27
- By default the shell runs on the server: the app is a `defineApp` manifest handed to moss, which builds one durable shell per principal and streams rendered trees to a thin canvas terminal. That shell is **the app** — one per person, the thing that rearranges itself around them. A path can also lead to a **page** (`pages` on the manifest): the same actions on a manifest of its own, drawn for whoever asks and kept by nothing — a welcome, the docs. And the first screen of either can arrive *with* the page request, drawn on the server by the app's own kit and adopted by the terminal (moss DESIGN.md, "The document" and "Pages"). Client execution — the shell in the browser, built by the app's own factory — is an explicit degrade for offline and zero-backend apps (D1), not a mode menu.
36
+ **Where the shell runs.**
37
+
38
+ - By default the shell runs on the server: the app is a `defineApp` manifest handed to moss, which builds one durable shell per principal and streams rendered trees to a thin canvas terminal. That shell is **the app** — one per person, the thing that rearranges itself around them.
39
+ - A path can also lead to a **page** (`pages` on the manifest): the same actions on a manifest of its own, drawn for whoever asks and kept by nothing — a welcome, the docs.
40
+ - The first screen of either can arrive *with* the page request, drawn on the server by the app's own kit and adopted by the terminal (moss DESIGN.md, "The document" and "Pages").
41
+ - Client execution — the shell in the browser, built by the app's own factory — is an explicit degrade for offline and zero-backend apps (D1), not a mode menu.
28
42
 
29
43
  ## Decisions are the user's
30
44
 
31
- This document has **rules** and **decision points**. Rules you follow without asking. Decision points are choices nisc deliberately leaves open — **never resolve one silently**. Present the options, the tradeoffs, and a recommendation, then wait for the answer. Decide alone only when you hold all the information an informed decision needs — for architecture questions you almost never do.
45
+ This document has **rules** and **decision points**. Rules you follow without asking. Decision points are choices nisc deliberately leaves open — **never resolve one silently**. Present the options, the tradeoffs, and a recommendation, then wait for the answer. Decide alone only when you have all the information an informed decision needs — for architecture questions you almost never do.
46
+
47
+ Collect the answers **before implementation starts**. The build is meant to run as an implement/check loop, and a loop that stops mid-flight to ask questions isn't running — front-loading the decisions is what lets it run to done.
32
48
 
33
- Collect the answers **before implementation starts**. The build is meant to run as an implement/check loop, and a loop that stops mid-flight to ask questions isn't running — front-loading the decisions is what lets it run to done. The known decision points:
49
+ The known decision points:
34
50
 
35
51
  - **D1 — Posture.** A moss server app (default: the shell runs server-side, the client is a canvas terminal) or a client-degrade app (the shell runs in the browser — offline, zero-backend, portable). The degrade is explicit, per app or per canvas.
36
52
  - **D2 — Environment.** What the runtime is handed: the database (PGlite for dev and demos, Postgres for real), a cache backend, a session verifier. For a client-degrade app: what serves the endpoints — in-memory fixtures, PGlite, a real backend, mixed.
37
53
  - **D3 — Reads.** Vex query endpoints, or plain endpoints with hand-written handlers. *Whether* to use Vex is the decision; *how* is fixed (see "Using Vex").
38
54
  - **D4 — Writes.** Vex mutation entries — the closed grammar, authored like reads and replayed as `{ fingerprint, context }` — or plain endpoint handlers. Either way a write is an endpoint; nothing writes inline.
39
- - **D5 — Routing.** What a path leads to. Three separate questions: whether the first screen is **drawn on the server** (it is drawn for whoever the browser's session cookie says, rule 12 — and a page drawn for a signed-in person may be kept by nothing between the server and their browser); which paths are **pages** rather than the app, and whether those are served live or written out as files (a file is only ever the page as nobody sees it; the build reports which pages can still do something and so want a server beside them); and whether the app's own shell state syncs to the address bar. Consequences to say out loud: a page keeps no shell, so anything on it that can be pressed gets a shell per connection, not per person; and the app's shell is one per person across every tab they have open, so a URL cannot hold a position inside it that two tabs disagree about.
55
+ - **D5 — Routing.** What a path leads to. Three separate questions:
56
+ 1. Whether the first screen is **drawn on the server**. It is drawn for whoever the browser's session cookie says (rule 12), and a page drawn for a signed-in person may be kept by nothing between the server and their browser.
57
+ 2. Which paths are **pages** rather than the app, and whether those are served live or written out as files. A file is only ever the page as nobody sees it; the build reports which pages can still do something and so want a server beside them.
58
+ 3. Whether the app's own shell state syncs to the address bar.
59
+
60
+ Consequences to say out loud: a page keeps no shell, so anything on it that can be pressed gets a shell per connection, not per person; and the app's shell is one per person across every tab they have open, so a URL cannot carry a position inside it that two tabs disagree about.
40
61
 
41
- Any other fork not covered by a rule gets one of two treatments. A genuine open choice is surfaced like a decision point. A choice that plainly follows from answers already given — the canvas arrangement implied by the views, one form per entity, delete-with-confirm — is **derived**: recorded in `PLAN.md` for review, not asked. When in doubt, ask.
62
+ Any other fork not covered by a rule gets one of two treatments:
42
63
 
43
- Conflicts get the same treatment too: when this document, a package README, and the code disagree, one of them has rotted — report the discrepancy, don't guess which one is right.
64
+ - A genuine open choice is surfaced like a decision point.
65
+ - A choice that plainly follows from answers already given — the canvas arrangement implied by the views, one form per entity, delete-with-confirm — is **derived**: recorded in `PLAN.md` for review, not asked.
66
+
67
+ When in doubt, ask. Conflicts get the same treatment: when this document, a package README, and the code disagree, one of them has rotted — report the discrepancy, don't guess which one is right.
44
68
 
45
69
  ## Before any code: the interview
46
70
 
@@ -51,7 +75,7 @@ Step one of every build is a conversation, not a scaffold. Ask the user one batc
51
75
 
52
76
  Rules of the interview:
53
77
 
54
- - **Front-load everything.** Sweep the brief against D1–D5, the rules, and the order of work, and ask it all in one round. The goal is zero questions after the build starts; a fork that surfaces mid-build still gets asked, but treat it as a defect of your interview, not as routine.
78
+ - **Front-load everything.** Sweep the brief against D1–D5, the rules, and the order of work, and ask it all in one round. The goal is zero questions after the build starts. A fork that surfaces mid-build still gets asked, but treat it as a defect of your interview, not as routine.
55
79
  - **Every choice lands in `PLAN.md` with its tier**: **answered** by the user, **delegated** by name ("D4: delegated"), or **derived** — it plainly follows from answers already given and is recorded for review, not asked. A blanket "go" or "you decide" delegates nothing. A choice that fits none of the three tiers blocks the build.
56
80
  - If an answer implies a constraint the user didn't name (multi-user later → roles and scope rules now; AI later → keep reads Vex-shaped now), say so during the interview, not in a commit message.
57
81
 
@@ -61,77 +85,254 @@ Pick per need; every piece works standalone. Nova is the only mandatory one for
61
85
 
62
86
  | Package | Use it for | Don't use it for |
63
87
  |---|---|---|
64
- | `nova` | the UI: shells, canvases, actions, layouts, fragments. Renderers are adapters (`/adapters/react`, `/dom`, `/tty`, `/ink`) — the core is surface-blind. `/reflect` inspects a live tree (checks, screen diffs), `/agent` is the layout-authoring surface, `/devtools` the inspector | — |
65
- | `moss` | the app server: `defineApp` manifest + runtime → data layer, per-principal policy and catalogs, server shells, pages, the socket, and the canvas terminal (`/terminal` plus a per-surface entry: `/terminal/react`, `/vue`, `/dom`, `/tty`, `/ink`). Draws a page request's first screen (`renderDocument`, with `/terminal/react/server` and its siblings) and writes pages as files (`exportDocuments`). What is not its core is a feature, created by the app and named in the manifest's `features`: `/integrations` (separate services that add screens) and `/tide` (`createTideFacts`: each committed write, minted into tide as a fact) | client-degrade apps — they wire their own shell. Routing inside the app: there is none, shell state is the truth |
66
- | `tide` | automations, as data: a reflex turns the clock, a write or a signal into one named effect, through a durable ledger. `createTideDriver` paces it (wake on a fact, sleep until the next due instant). `/postgres` is its store over Postgres (`createTideStore(pool)`; `TIDE_SEQUENCE` is its tables, for `runtime.tables`). Under moss a write reaches it through moss's `/tide` feature, and its ledger is read through vex like any table | a step language — a flow of several steps is a chain of reflexes, each effect producing the fact the next one fires on |
67
- | `charter` | the policy document: roles → glob selections over the app's universes, resolved per principal, verified at boot | enforcement — the governed target enforces |
68
- | `prism` | every transform: shaping, formatting, branching | anything a schema or layout expresses directly |
69
- | `vex` | query and mutation endpoints: `{ fingerprint, context }` → rows or effects (see "Using Vex") | writes outside its closed mutation grammar |
70
- | `loom` | compiling a Zod schema into an editing form — prefer it over hand-laying a form the schema already describes | layouts that aren't schema-backed documents |
71
- | `signal` | LLM calls | — |
72
- | `cortex` | agents, tools, orchestration | — |
73
- | `solid` | streaming structured LLM output into UI | — |
74
- | `haptic` | reading data from web pages: `discover({ url, instruction })` (`/discovery`, a model run) writes a JSON artifact once, and `prepareArtifact(artifact).run({ url })` reads the page's current values from it later with no model. `/search` finds the pages first when there is only an instruction. An artifact can also be written by hand and checked with `prepared.inspect()` (its `ARTIFACTS.md`). Stored artifacts are upgraded through the `nisc.haptic` grammar (`/migrations`) | scheduling the runs, storing the data, or deciding what happens with it — those are the caller's |
75
- | `cli` | the `nisc` command: `dev`, `build` (bundle, then say how each path is served — a file, or a server, and why), `export` (the site as a folder; only ever the page as nobody sees it), `start` (the built terminal, pages drawn), `check`, `migrate` (the tables' pending migrations, applied only if the app's entries fit the result). One file, `nisc.config.ts`, says how the app boots and how a screen is drawn | configuration of anything derivable — which paths exist and what each needs is read off the app |
76
- | `strata` | versions: an app's tables as ledgered sequences; stored and submitted documents stamped and upgraded through grammar sequences; `strata upgrade` for artifacts in source (see Versions) | editing a migration that has run — append one |
88
+ | `nova` | The UI: shells, canvases, actions, layouts, fragments. Renderers are adapters (`/adapters/react`, `/vue`, `/dom`, `/tty`, `/ink`); the core is surface-blind. `/reflect` inspects a live tree (checks, screen diffs), `/agent` is the layout-authoring surface, `/devtools` the inspector. | — |
89
+ | `moss` | The app server: `defineApp` manifest + runtime → data layer, per-principal policy and catalogs, server shells, pages, the socket, and the canvas terminal (`/terminal` plus a per-surface entry: `/terminal/react`, `/vue`, `/dom`, `/tty`, `/ink`). Draws a page request's first screen (`renderDocument`, with `/terminal/react/server` and its siblings) and writes pages as files (`exportDocuments`). What is not its core is a feature, created by the app and named in the manifest's `features`: `/integrations` (separate services that add screens) and `/tide` (`createTideFacts`: each committed write, minted into tide as a fact). | Client-degrade apps — they wire their own shell. Routing inside the app: there is none, shell state is the truth. |
90
+ | `tide` | Automations, as data: a reflex turns the clock, a write or a signal into one named effect, through a durable ledger. `createTideDriver` paces it (wake on a fact, sleep until the next due instant). `/postgres` is its store over Postgres (`createTideStore(pool)`; `TIDE_SEQUENCE` is its tables, for `runtime.tables`). Under moss a write reaches it through moss's `/tide` feature, and its ledger is read through vex like any table. | A step language — a flow of several steps is a chain of reflexes, each effect producing the fact the next one fires on. |
91
+ | `charter` | The policy document: roles → glob selections over the app's universes, resolved per principal, verified at boot. | Enforcement — the governed target enforces. |
92
+ | `prism` | Every transform: shaping, formatting, branching. | Anything a schema or layout expresses directly. |
93
+ | `vex` | Query and mutation endpoints: `{ fingerprint, context }` → rows or effects (see "Using Vex"). | Writes outside its closed mutation grammar. |
94
+ | `loom` | Compiling a Zod schema into an editing form — prefer it over hand-laying a form the schema already describes. | Layouts that aren't schema-backed documents. |
95
+ | `signal` | LLM calls. | — |
96
+ | `cortex` | Agents, tools, orchestration. | — |
97
+ | `solid` | Streaming structured LLM output into UI. | — |
98
+ | `haptic` | Reading data from web pages: `discover({ url, instruction })` (`/discovery`, a model run) writes a JSON artifact once, and `prepareArtifact(artifact).run({ url })` reads the page's current values from it later with no model. `/search` finds the pages first when there is only an instruction. An artifact can also be written by hand and checked with `prepared.inspect()` (its `ARTIFACTS.md`). Stored artifacts are upgraded through the `nisc.haptic` grammar (`/migrations`). | Scheduling the runs, storing the data, or deciding what happens with it — those are the caller's. |
99
+ | `cli` | The `nisc` command. `dev`; `build` (bundle, then say how each path is served — a file, or a server, and why); `export` (the site as a folder; only ever the page as nobody sees it); `start` (the built terminal, pages drawn); `check`; `migrate` (the tables' pending migrations, applied only if the app's entries fit the result). One file, `nisc.config.ts`, says how the app boots and how a screen is drawn. | Configuration of anything derivable — which paths exist and what each needs is read off the app. |
100
+ | `strata` | Versions: an app's tables as ledgered sequences; stored and submitted documents stamped and upgraded through grammar sequences; `strata upgrade` for artifacts in source (see "Versions"). | Editing a migration that has run — append one. |
77
101
 
78
102
  ## Rules
79
103
 
80
- **Actions**
104
+ ### Actions
105
+
106
+ **1.** Everything visible is an action (`.action.ts`) + JSON layout (`.layout.ts`) loaded onto a canvas. No React views, no app logic in components.
107
+
108
+ **2.** One component registry, assembled once.
109
+
110
+ - Primitives are domain-blind. A component name containing a domain noun (`InvoiceRow`, `DealCard`) is a feature component in disguise — wrong.
111
+ - Repeated structure is a data-driven spec prop on a generic primitive (a `Table`'s `columns`), not a new component.
112
+ - A component never imports the shell, actions, or data code. If it needs domain knowledge to render, compute the field upstream in a transform.
113
+ - **Components are configured, never styled.** A prop says what a thing is (an area, an ink, a level) from a closed set of names. No `style`, `className`, colour or size is accepted from a layout, and an unknown value falls back to the default.
114
+ - The look lives only in the kit's CSS and tokens. A different look is a different stylesheet over the same layouts.
115
+
116
+ **2a.** A kit whose pages are drawn on the server draws the same thing on its first pass in the browser.
117
+
118
+ - Nothing that differs between the two — the window's width, a media query, storage, a portal target — may decide a component's first render. Read it through `useSyncExternalStore` with a server answer, or in an effect.
119
+ - A `typeof window` guard around a state initialiser is not a fix, it is the bug: it makes the two sides disagree about the same render, and the terminal throws the page's elements away.
120
+ - What a component writes onto `<html>` from an effect (a palette, a scheme) is not in a drawn page until its script runs. The app reads it off the snapshot and hands it to the document (`renderDocument`'s `htmlAttributes`).
121
+
122
+ **3.** Reusable chrome (dialog frame, panel, drawer) is a fragment composed when an action is loaded (`with: [...]`), not a wrapper component. Modality is arrangement — an action loaded onto an overlay canvas with fragment chrome — never a `$.modalOpen` flag inside an action.
123
+
124
+ **4.** Shell state is the truth.
125
+
126
+ - Routing (D5), if wired, is a data table mapping paths ↔ actions, synced by an adapter; Nova stays URL-agnostic.
127
+ - A **page** is not routing inside the app. It is a separate manifest at a path (`pages`), drawn and let go. A path's parameters seed the canvas the page names — nothing else about a URL reaches an action.
128
+
129
+ **4a.** A page's `<head>` is a node in a layout.
130
+
131
+ - `nova:head` contains the elements a head contains — `nova:title`, `nova:meta`, `nova:link`, `nova:script`. A child's props are that element's attributes, written as given and bound to the action's data like any other node's.
132
+ - Nothing in it is drawn on the screen. Whoever draws the page writes it into the document's `<head>` (`nisc build`/`export`/`start`, moss's `renderDocument`), and in the page the head follows the screen.
133
+ - No hook builds a head and no script rewrites a drawn file.
134
+ - What runs or styles — a script a browser would execute, a stylesheet, `http-equiv` — is never in a layout. It goes in `index.html`, the app's own file, or in the kit component that needs it.
135
+ - A page's canonical address comes from `site` in `nisc.config.ts` and the path.
136
+ - Whether a head sits in the action's own layout or in chrome around it (a fragment, the frame) is arrangement, like everything else.
137
+
138
+ ### Data
139
+
140
+ **5.** All data in and out of an action flows through its declared `endpoints`.
141
+
142
+ - Shaping is declared on the endpoint. A static request body is plain JSON; a body derived from the action's data is a Prism config, kept in a sibling `.prism.ts`.
143
+ - Prefer plain JSON when no mapping is required.
144
+ - Components never shape data.
145
+ - Prism's `$ref` indexes as `$.rows[0].title`; a layout binding, a trigger's `set … from` and an `@event` path index with a dot, `$.rows.0.title` (nova splits on `.`). The wrong spelling reads nothing and draws empty, with no error.
146
+
147
+ **6.** Nova doesn't know Prism: the shell's injected `transform` is the socket that makes Prism endpoint configs work.
148
+
149
+ - Wire it once in setup. Fold ambient app context (the app's "today", the session's principal) into the source there — per session on the server under moss, in the shell factory in a client-degrade app — never into per-action data.
150
+ - The socket takes Prism's `evaluate` as it is (`transform: evaluate`), or a wrapper that adds to the source: `(config, source) => evaluate(config, { ...source, today })`.
151
+ - Hand `evaluate` the config object itself, never a copy of it and never one parsed again: it checks a config the first time it sees the object and only evaluates it after that.
152
+ - A test or a tool that must check everything on every call passes `{ check: 'always' }`.
153
+ - A config that is stored is compiled once and its IR executed (`compile`, `execute`).
154
+
155
+ **7.** An endpoint is a contract, not an implementation (D1, D2).
156
+
157
+ - In-browser, server, or mixed — actions can't tell the difference, and must not be able to.
158
+ - Server functions are endpoints too: the manifest's `functions(session)` seam runs them in-process under the caller's policy.
159
+ - The seam returns a list of `{ id, description, execute }`. The id is what the charter and an `fn:` endpoint name; the description says what the function does and what to send, for the model that writes a call to it. A map of handlers is deprecated.
160
+ - A client-side `fn` registry is the escape hatch for client-degrade apps, and discouraged elsewhere.
161
+
162
+ **7a.** Four of the manifest's code seams are distinct, and app code goes in the one that describes it.
163
+
164
+ - `functions(session)` is for **endpoints** — things an action calls.
165
+ - `onSession(session)` is for per-shell code that is **not** an endpoint: an observer, a roster, an agent watching the screen. Registering a handler nothing calls, to get code to run per session, is a lie about what that code is — use `onSession`.
166
+ - `runs` is the **sink** for model runs, fed by `session.recordRun`.
167
+ - `reconcilers` is for **how a canvas is reconciled**: a function a canvas names with `reconcile`, which decides from a `reconcile` step's rows what that canvas keeps, matches, moves and removes — several cards of one action, matched by a key and kept in the list's order (moss DOCS.md, `reconcilers`). A function that pushes and removes cards itself is not one: each of its moves is a step `back` takes on its own, where everything a reconcile does is one.
168
+ - `onSession` and `functions` both run before the shell finishes building, so neither may touch `session.shell` synchronously. The members of that shell that change what it is made of (`registerAction`, `setLayout`, `addCanvas` and their kin) throw there, and a reconciler is handed that same shell. The whole shell is `unverifiedShell(session)` from `@niscorp/moss/unverified`.
169
+
170
+ **7b.** What is generated while the app runs is saved through `session.artifacts`, not set on the shell. For everything a person saves, of every kind:
171
+
172
+ - No call can name anybody else: moss reads and writes those rows as the caller, and vex keeps them to the caller's own.
173
+ - **Who may save is the charter's**: put the call in a function, and grant the action that calls it to the roles that may.
174
+ - With `runtime.artifactsUnusedMs`, what a person saved and nobody has loaded for that long is deleted, every version of it. What is published never ages.
175
+
176
+ *A person's own layouts*
177
+
178
+ - `session.artifacts.save([{ kind: 'layout', body: { ref: 'action/<the action's id>', layout, use: true } }])` keeps a layout for the session's principal. It is theirs alone, it is drawn on their screens at once with their data kept, and every save is a version (`list`, `history`, `restore`, `reset`).
179
+ - Without `use: true` it is kept and not drawn.
180
+ - The layout of the app's own shell is saved the same way under `ref: 'frame'`, and a canvas's under `ref: 'canvas/<the canvas's id>'`. A page keeps the layouts it declares. A shell manifest with no `layout` (or a canvas with no `actionLayout`) has none to take the place of. A frame that leaves a canvas out is saved as it is, so check that yourself where it matters.
181
+ - A canvas their shell does not declare, that a layout in force for a person has a canvas slot for, is taken out of their shell, with what is mounted on it, once no layout has the slot. Declare a canvas that is to stay.
182
+ - A body moss refuses — a ref no action of theirs keeps a layout under, a component no shell has, a binding to data the action lacks, a control the action listens on left out — rejects with a sentence. Hand it back to whoever wrote the layout.
183
+
184
+ *Published for everybody*
185
+
186
+ - What is for everybody is published from the app's own server code and never from a session: `server.defaults(publisher).save([...])`, with the same kinds, the same bodies and the same five calls.
187
+ - A published layout is drawn for everybody who has the action, under a person's own layout in use and their roles' layout variant, and over the build's.
188
+ - A published action or fragment is given its id by whoever publishes it (`{ kind: 'action', id: 'promo', body }`). The charter grants it by that id, and one under a shipped id replaces the build's for everybody until it is reset.
189
+ - A published read is answered to everybody under its fingerprint.
190
+ - `publisher` is who published, kept with the save: hand it the session's principal.
191
+ - **Who may publish is the charter's** too: put the call in a function and grant the action that calls it to the owners' role.
192
+ - No `userId` is `*`: that is whose the published rows are.
193
+
194
+ *Generated actions and fragments*
195
+
196
+ - An action or a fragment generated while the app runs is saved the same way: `{ kind: 'action', body }` or `{ kind: 'fragment', body }`, the body without an `id`, because moss gives it (`generated.` and a uuid, which `save` answers).
197
+ - It is its owner's alone, and what it defines replays reads and calls the functions its owner's roles grant. Each endpoint is one of:
198
+ - a `POST` to the app's vex route naming one fingerprint, of a read the app ships and its owner may replay or of a read vex wrote that its owner saved;
199
+ - an `fn:` endpoint to a function its owner's roles grant (`session.functions()` lists them with their descriptions: hand that list to the model that writes the action).
200
+ - A function its owner's roles do not grant, a write and any other address are refused with a sentence, and so is a generated action that opens an action its owner does not have.
201
+ - Once it is in the shell it is an action like any other: it emits and listens on channels, and a fragment's steps run inside the action it is wrapped around.
202
+ - What an assistant may generate is the app's to decide, in its prompt and in the function that calls `save`.
203
+ - It is in its owner's shells a moment after `save` answers, not before.
204
+ - Never give an action or a fragment the app ships an id beginning with `generated.`.
205
+
206
+ *Reads vex wrote*
207
+
208
+ - A read vex wrote for `session.answerIntent` is kept the same way, with no body: `session.artifacts.save([{ kind: 'read', id: '<the fingerprint vex answered>', body: undefined }])`. It is answered to that person alone, it survives a schema change that does not touch what it reads, and their generated actions may replay it.
209
+ - `session.answerIntent` also replays a read by its fingerprint, `{ fingerprint, context }`, and answers it with what vex knows of it (the context it binds, what the call left out, its warnings), where the wire answers the rows alone.
210
+
211
+ *Drafts*
212
+
213
+ - What is still being generated, and is to be seen at once, goes into the draft of the one shell it is worked on in. `session.draft.add([...])` takes what `save` takes and answers when that shell has it, so the function opens it on its next line.
214
+ - `session.draft.save()` then keeps all of it in one save, and `discard()` drops it.
215
+ - A draft is saved nowhere and is gone when its shell is.
216
+
217
+ **8.** Writes are endpoints fired by triggers, never inline mutations (D4).
218
+
219
+ - Identity and tenancy are stamped server-side from the session, never client-supplied: a form never carries `owner_id`.
220
+ - What a principal *is* beyond its id — a tenant, an org, a region — is the manifest's `scope(principal)` seam. Moss always injects `{ userId }`, `scope` contributes the rest, and the merged set is what a behavior's `to:` resolves against at execute.
221
+ - The mapping is application knowledge, so the app supplies it; the values are injected server-side and unreferenceable by a request.
222
+
223
+ **9.** Formatting and derivation live in Prism transforms, never in components and never in action code.
224
+
225
+ **9a.** File pickers live in the kit. A file never goes over the socket; the app saves it wherever it wants.
226
+
227
+ ### Principals
81
228
 
82
- 1. Everything visible is an action (`.action.ts`) + JSON layout (`.layout.ts`) loaded onto a canvas. No React views, no app logic in components.
83
- 2. One component registry, assembled once. Primitives are domain-blind: a component name containing a domain noun (`InvoiceRow`, `DealCard`) is a feature component in disguise — wrong. Repeated structure is a data-driven spec prop on a generic primitive (a `Table`'s `columns`), not a new component. A component never imports the shell, actions, or data code; if it needs domain knowledge to render, compute the field upstream in a transform. **Components are configured, never styled:** a prop says what a thing is (an area, an ink, a level) from a closed set of names; no `style`, `className`, colour or size is accepted from a layout, and an unknown value falls back to the default. The look lives only in the kit's CSS and tokens — a different look is a different stylesheet over the same layouts.
84
- 2a. A kit whose pages are drawn on the server draws the same thing on its first pass in the browser. Nothing that differs between the two — the window's width, a media query, storage, a portal target — may decide a component's first render: read it through `useSyncExternalStore` with a server answer, or in an effect. A `typeof window` guard around a state initialiser is not a fix, it is the bug: it makes the two sides disagree about the same render, and the terminal throws the page's elements away. What a component writes onto `<html>` from an effect (a palette, a scheme) is not in a drawn page until its script runs; the app reads it off the snapshot and hands it to the document (`renderDocument`'s `htmlAttributes`).
85
- 3. Reusable chrome (dialog frame, panel, drawer) is a fragment composed when an action is loaded (`with: [...]`), not a wrapper component. Modality is arrangement — an action loaded onto an overlay canvas with fragment chrome — never a `$.modalOpen` flag inside an action.
86
- 4. Shell state is the truth. Routing (D5), if wired, is a data table mapping paths ↔ actions, synced by an adapter; Nova stays URL-agnostic. A **page** is not routing inside the app: it is a separate manifest at a path (`pages`), drawn and let go, and a path's parameters seed the canvas the page names — nothing else about a URL reaches an action.
229
+ **10.** The charter is the app's policy document: role names → glob selections over the app's universes.
87
230
 
88
- 4a. A page's `<head>` is a node in a layout. `nova:head` holds the elements a head holds — `nova:title`, `nova:meta`, `nova:link`, `nova:script` — and a child's props are that element's attributes, written as given and bound to the action's data like any other node's. Nothing in it is drawn on the screen; whoever draws the page writes it into the document's `<head>` (`nisc build`/`export`/`start`, moss's `renderDocument`), and in the page the head follows the screen. No hook builds a head and no script rewrites a drawn file. What runs or styles — a script a browser would execute, a stylesheet, `http-equiv` — is never in a layout: it goes in `index.html`, the app's own file, or in the kit component that needs it. A page's canonical address comes from `site` in `nisc.config.ts` and the path. Whether a head sits in the action's own layout or in chrome around it (a fragment, the frame) is arrangement, like everything else.
231
+ - The universes: `actions` (which action ids exist for a principal), `data` (`table.verb` capabilities, compiled into the Vex `ScopePolicy`; the verbs: `read`, `write.insert`, `write.update`, `write.delete` — `todos.write.update`, not `todos.update`), `functions` (which of the app's functions a principal's shell has: a role with none may call none) and `layouts` (which served layout variants a principal gets, rule 11).
232
+ - Grant each role the functions its actions call, deliberately. Moss refuses to boot and lists every call whose grants miss — for each role on its own, each combination people wear, and `public` — and says where a role allows every function (`'*'`).
233
+ - `server.checkFunctions()` is called once the app has the server and has mounted every route of its own, before it listens (nobody's shell makes its reads in-process, and the server takes no route once it has answered one). It builds nobody's shell once to read the functions and refuses every call to one the app does not have. The `nisc` command calls it itself wherever it boots the app's server.
234
+ - The charter compiles; it never enforces and never shapes. Moss resolves it per principal and refuses to boot incoherent.
235
+ - Assignments (principal → roles) are app data beside it. Row-level semantics the charter can't express are `behaviors`, compiled into the policy.
236
+ - One role name is fixed: a request with no session, and a signed-in principal with no assignment, resolve to `public`, so every charter defines it — `public: []` where it grants nothing. Boot does not check for it; without it those requests fail (`Unknown role "public"`).
89
237
 
90
- **Data**
238
+ **10a.** The `data` universe is the INTROSPECTED database, not your schema file.
91
239
 
92
- 5. All data in and out of an action flows through its declared `endpoints`. Shaping is declared on the endpoint: a static request body is plain JSON; a body derived from the action's data is a Prism config, kept in a sibling `.prism.ts`. Prefer plain JSON when no mapping is required. Components never shape data.
93
- 6. Nova doesn't know Prism: the shell's injected `transform` is the socket that makes Prism endpoint configs work. Wire it once in setup, and fold ambient app context (the app's "today", the session's principal) into the source there — per session on the server under moss, in the shell factory in a client-degrade app — never into per-action data. The socket takes Prism's `evaluate` as it is (`transform: evaluate`), or a wrapper that adds to the source: `(config, source) => evaluate(config, { ...source, today })`. Hand `evaluate` the config object itself, never a copy of it and never one parsed again: it checks a config the first time it sees the object and only evaluates it after that. A test or a tool that must check everything on every call passes `{ check: 'always' }`. A config that is stored is compiled once and its IR executed (`compile`, `execute`).
94
- 7. An endpoint is a contract, not an implementation (D1, D2). In-browser, server, or mixed — actions can't tell the difference, and must not be able to. Server functions are endpoints too: the manifest's `functions(session)` seam runs them in-process under the caller's policy. The seam returns a list of `{ id, description, execute }`: the id is what the charter and an `fn:` endpoint name, and the description says what the function does and what to send, for the model that writes a call to it; a map of handlers is deprecated. A client-side `fn` registry is the escape hatch for client-degrade apps, and discouraged elsewhere.
95
- 7a. The manifest's four code seams are distinct, and app code goes in the one that describes it. `functions(session)` is for **endpoints** — things an action calls. `onSession(session)` is for per-shell code that is **not** an endpoint: an observer, a roster, an agent watching the screen. `runs` is the **sink** for model runs, fed by `session.recordRun`. `reconcilers` is for **how a canvas is reconciled**: a function a canvas names with `reconcile`, which decides from a `reconcile` step's rows what that canvas keeps, matches, moves and removes — several cards of one action, matched by a key and kept in the list's order (moss DOCS.md, `reconcilers`). A function that pushes and removes cards itself is not one: each of its moves is a step `back` takes on its own, where everything a reconcile does is one. Registering a handler nothing calls, to get code to run per session, is a lie about what that code is — use `onSession`. Both it and `functions` run before the shell finishes building, so neither may touch `session.shell` synchronously. The members of that shell that change what it is made of (`registerAction`, `setLayout`, `addCanvas` and their kin) throw there, and a reconciler is handed that same shell; the whole shell is `unverifiedShell(session)` from `@niscorp/moss/unverified`.
96
- 7b. A layout generated while the app runs is saved through `session.artifacts`, not set on the shell. `session.artifacts.save([{ kind: 'layout', body: { ref: 'action/<the action’s id>', layout, use: true } }])` keeps it for the session's principal: it is theirs alone, it is drawn on their screens at once with their data kept, and every save is a version (`list`, `history`, `restore`, `reset`). Without `use: true` it is kept and not drawn. The layout of the app's own shell is saved the same way under `ref: 'frame'`, and a canvas's under `ref: 'canvas/<the canvas’s id>'`: a page keeps the layouts it declares, a shell manifest with no `layout` (or a canvas with no `actionLayout`) has none to take the place of, and a frame that leaves a canvas out is saved as it is, so check that yourself where it matters. A canvas their shell does not declare, that a layout in force for a person has a canvas slot for, is taken out of their shell, with what is mounted on it, once no layout has the slot: declare a canvas that is to stay. No call can name anybody else: moss reads and writes those rows as the caller, and vex keeps them to the caller's own. **Who may save is the charter's**: put the call in a function, and grant the action that calls it to the roles that may. A body moss refuses (a ref no action of theirs keeps a layout under, a component no shell has, a binding to data the action lacks, a control the action listens on left out) rejects with a sentence: hand it back to whoever wrote the layout. With `runtime.artifactsUnusedMs`, what a person saved and nobody has loaded for that long is deleted, every version of it; what is published never ages. What is for everybody is published from the app's own server code and never from a session: `server.defaults(publisher).save([...])`, with the same kinds, the same bodies and the same five calls. A published layout is drawn for everybody who holds the action, under a person's own layout in use and their roles' layout variant, and over the build's. A published action or fragment is given its id by whoever publishes it (`{ kind: 'action', id: 'promo', body }`): the charter grants it by that id, and one under a shipped id replaces the build's for everybody until it is reset. A published read is answered to everybody under its fingerprint. `publisher` is who published, kept with the save: hand it the session's principal. **Who may publish is the charter's** too: put the call in a function and grant the action that calls it to the owners' role. No `userId` is `*`: that is whose the published rows are. An action or a fragment generated while the app runs is saved the same way: `{ kind: 'action', body }` or `{ kind: 'fragment', body }`, the body without an `id`, because moss gives it (`generated.` and a uuid, which `save` answers). It is its owner's alone, and what it defines replays reads and calls the functions its owner's roles grant: each endpoint is a `POST` to the app's vex route naming one fingerprint of a read the app ships and its owner may replay, or of a read vex wrote that its owner saved, or an `fn:` endpoint to a function its owner's roles grant (`session.functions()` lists them with their descriptions: hand that list to the model that writes the action). A read vex wrote for `session.answerIntent` is kept the same way: `session.artifacts.save([{ kind: 'read', id: '<the fingerprint vex answered>' }])`, with no body. It is answered to that person alone, it survives a schema change that does not touch what it reads, and their generated actions may replay it. `session.answerIntent` also replays a read by its fingerprint, `{ fingerprint, context }`, and answers it with what vex knows of it (the context it binds, what the call left out, its warnings), where the wire answers the rows alone. A function its owner's roles do not grant, a write and any other address are refused with a sentence, and so is a generated action that opens an action its owner does not hold. Once it is in the shell it is an action like any other: it emits and listens on channels, and a fragment's steps run inside the action it is wrapped around. What an assistant may generate is the app's to decide, in its prompt and in the function that calls `save`. It is in its owner's shells a moment after `save` answers, not before. What is still being generated, and is to be seen at once, goes into the draft of the one shell it is worked on in: `session.draft.add([...])` takes what `save` takes and answers when that shell has it, so the function opens it on its next line; `session.draft.save()` then keeps all of it in one save, and `discard()` drops it. A draft is saved nowhere and is gone when its shell is. Never give an action or a fragment the app ships an id beginning with `generated.`.
97
- 8. Writes are endpoints fired by triggers, never inline mutations (D4). Identity and tenancy are stamped server-side from the session, never client-supplied: a form never carries `owner_id`. What a principal *is* beyond its id — a tenant, an org, a region — is the manifest's `scope(principal)` seam: moss always injects `{ userId }`, `scope` contributes the rest, and the merged set is what a behavior's `to:` resolves against at execute. The mapping is application knowledge, so the app supplies it; the values are injected server-side and unreferenceable by a request.
98
- 9. Formatting and derivation live in Prism transforms, never in components and never in action code.
99
- 9a. File pickers live in the kit. A file never goes over the socket; the app saves it wherever it wants.
240
+ - It has the engine's own tables too: moss's `integrations` (integration key hashes), `integration_actions`, `moss_generation`, `artifacts`, `artifact_saves`, `sessions` (session token hashes, under moss's credential), the `strata_ledger`, the vex cache.
241
+ - A role granted a data wildcard (`*.read`) denies them explicitly: `data: { allow: ['*.read'], deny: [...] }`. Denies do not inherit, so every role that grants the wildcard denies.
242
+ - A charter check resolves against the universe boot resolves against — the app's migrations and moss's run on a scratch database, then introspected — or it proves nothing about wildcards.
100
243
 
101
- **Principals**
244
+ **11.** Per-principal UI is existence or a served variant, never a conditional.
102
245
 
103
- 10. The charter is the app's policy document: role names → glob selections over the app's universes — `actions` (which action ids exist for a principal), `data` (`table.verb` capabilities, compiled into the Vex `ScopePolicy`) and `functions` (which of the app's functions a principal's shell holds: a role with none may call none). Grant each role the functions its actions call, deliberately: moss refuses to boot and lists every call whose grants miss, for each role on its own, each combination people wear and `public`, and says where a role allows every function (`'*'`); `server.checkFunctions()`, called once the app holds the server and has mounted every route of its own, before it listens (nobody's shell makes its reads in-process, and the server takes no route once it has answered one), builds nobody's shell once to read the functions and refuses every call to one the app does not have. The charter compiles; it never enforces and never shapes. Moss resolves it per principal and refuses to boot incoherent. Assignments (principal → roles) are app data beside it; row-level semantics the charter can't express are `behaviors`, compiled into the policy. One role name is fixed: a request with no session, and a signed-in principal with no assignment, resolve to `public`, so every charter defines it — `public: []` where it grants nothing. Boot does not check for it; without it those requests fail (`Unknown role "public"`).
104
- 10a. The `data` universe is the INTROSPECTED database, not your schema file: it has the engine's own tables too — moss's `integrations` (integration key hashes), `integration_actions`, `moss_generation`, `artifacts`, `artifact_saves`, `sessions` (session token hashes, under moss's credential), the `strata_ledger`, the vex cache. A role granted a data wildcard (`*.read`) denies them explicitly (`data: { allow: ['*.read'], deny: [...] }`; denies do not inherit, so every role that grants the wildcard denies). A charter check resolves against the universe boot resolves against — the app's migrations and moss's run on a scratch database, then introspected — or it proves nothing about wildcards.
105
- 11. Per-principal UI is existence or a served variant, never a conditional. An action a principal lacks does not exist in their shell (ring 1); a different shape of the same action is a served variant (ring 2). Layouts and components never branch on roles or capability data. Ring 1 does the deriving: a canvas's `initial` takes a **candidate list** and the first id the principal actually holds mounts — members boot their home, anonymous boots the login, and nobody configures which. An ungranted candidate simply isn't there.
106
- 11a. Per-principal boot has two hooks, and they are twins. `inputs` derives boot **data** — merged over each canvas's static seed, read from action data downstream. `seeds` derives boot **instances** — which actions to push onto which canvases, computed from the session and its own reads over the session's wire, ring-1-filtered like every other mount. A composed surface (a home, an agent's column) is `seeds` plus a `list` canvas; hand-authoring the same arrangement names it twice. Branching chrome on `inputs` is a stopgap where a served variant doesn't exist yet.
107
- 11b. A page is drawn for whoever asks, and what it has for them is ring 1 like everything else: a strip naming the signed-in person is an action a member is granted, on a canvas whose candidates a stranger is granted none of. A page never knows less about a signed-in person than the app does, and never keeps a shell for them. **Who may keep a drawn page follows from who asked, and from nothing else** — drawn for nobody it is the same for everybody and may be cached or written to a file; drawn for somebody it is theirs. No page, route or app declares which; a static build only ever asks for the page as nobody.
108
- 12. Auth is a session token, nothing else — magic link is the default strategy; there are no username/password pairs in a nisc app if it can be avoided. Login is the anonymous principal's application. Session lifecycle is a **capability, not a channel**: login and sign-out are ordinary `fn:` endpoints calling `session.grant(token)` and `session.revoke()`, and the terminal reconnects as the new principal. The server consumes sessions and never mints identity. A page served by its app does not hold its session: the **browser** does, in a cookie no script can read, which moss writes in its answer to the socket's upgrade and reads for two things only — the upgrade from the app's own page, and choosing whose screen to draw. No route answers to it. Nothing in an app stores a token: not `localStorage`, not a cookie script can read. A sign-in the app answers over HTTP (a redeemed link, a provider's callback) sets that cookie on its response with `sessionCookies(request, token)` and redirects; it never hands the token to the page. A terminal that is not a page of its app (a process, another origin) holds its own token and offers it.
246
+ - An action a principal lacks does not exist in their shell (ring 1). A different shape of the same action is a served variant (ring 2).
247
+ - Layouts and components never branch on roles or capability data.
248
+ - Ring 1 does the deriving: a canvas's `initial` takes a **candidate list**, and the first id the principal is actually granted mounts — members boot their home, anonymous boots the login, and nobody configures which. An ungranted candidate simply isn't there.
109
249
 
110
- **Schemas**
250
+ **11a.** Per-principal boot has two hooks, and they are twins.
111
251
 
112
- 13. Everything that crosses a boundary is parsed by a Zod schema at that boundary. `.strict()` on external input.
113
- 14. An action's openable inputs live in its definition's optional `input` field: a JSON Schema — authored in Zod with `.describe()` on every field, converted with `z.toJSONSchema` — of the `data` keys an opener may seed when loading the action. The fields are a subset of `data`; no seedable keys, no `input`. That schema is the action's public contract, for a nav item, a URL, a command palette, and an agent alike. Catalogs curate ids and descriptions and are resolved per principal (moss serves the resolved catalog); they read `input` off the definition, never restate it.
114
- 15. For any LLM contract, the Zod schema is the single source of truth: constraints in `.describe()`, JSON Schema injected into the prompt at runtime, always minified. No prose "how the DSL works" sections in prompts.
252
+ - `inputs` derives boot **data** — merged over each canvas's static seed, read from action data downstream.
253
+ - `seeds` derives boot **instances** — which actions to push onto which canvases, computed from the session and its own reads over the session's wire, ring-1-filtered like every other mount.
254
+ - A composed surface (a home, an agent's column) is `seeds` plus a `list` canvas; hand-authoring the same arrangement names it twice.
255
+ - Branching chrome on `inputs` is a stopgap where a served variant doesn't exist yet.
115
256
 
116
- **Code**
257
+ **11b.** A page is drawn for whoever asks, and what it has for them is ring 1 like everything else.
117
258
 
118
- 16. `/STYLE_GUIDE.md` applies in full, with two app-level overrides: it is written for the packages, so its "custom error classes for domain errors" does **not** apply here — an app declares no classes at all and throws plain `Error`; and "Package prompts serve every app" binds packages, not apps — an app's prompts may be about the app. What an app measures against a package's agent is fixed in that package only in general form (see that section). Zero-tolerance: `any`, type assertions (`as` — `as const` excepted), non-null `!`, `enum`, classes, default exports, `function` declarations. Deps via `pnpm add` only. Files: `kebab-case.role.ts`. Declared exception: a file that must match an external module's shape (a shim) may break these rules — it says why in a header comment, and reviewers honor it.
259
+ - A strip naming the signed-in person is an action a member is granted, on a canvas whose candidates a stranger is granted none of.
260
+ - A page never knows less about a signed-in person than the app does, and never keeps a shell for them.
261
+ - **Who may keep a drawn page follows from who asked, and from nothing else.** Drawn for nobody, it is the same for everybody and may be cached or written to a file; drawn for somebody, it is theirs.
262
+ - No page, route or app declares which. A static build only ever asks for the page as nobody.
119
263
 
120
- **Versions** (`@niscorp/strata`; the why is `packages/strata/DESIGN.md`)
264
+ **12.** Auth is a session token, nothing else.
121
265
 
122
- 17. No package — and no app, where it can help it — runs DDL outside a strata sequence. Tables change by APPENDING a migration to their owner's sequence; a migration that has run is history, checksummed in the ledger, and editing it makes every database that ran it refuse to boot. The first migration of a sequence may be the old `IF NOT EXISTS` DDL verbatim — split with `sqlSteps(ddl)`, never on every `;` — and that is how an existing database adopts. An app's own tables are its `<app>.app` sequence, handed to moss in `runtime.tables` — with `TIDE_SEQUENCE` (from `@niscorp/tide/postgres`, the store made `migrate: false`) when it keeps tide's tables — and a real database's tables change only through `nisc migrate`: a boot checks them and refuses to start while a migration is pending (`migrations: 'verify'`, the default); only a runtime whose database starts empty every time (PGlite in memory) writes `migrations: 'apply'`. The function that opens a runtime migrates nothing, seeds nothing and calls no `cache.init()`: what it changes itself is changed before the step can check it. A sequence that has run on a database stays in `runtime.tables` even when nothing uses it any more — the run refuses a ledger that records a sequence nobody names (`UNKNOWN_SEQUENCE`) — and its tables go by an appended migration that drops them. One app per database schema: a schema has one ledger. `nisc migrate` refuses a run that removes a table or column or changes a column's type unless it is given `--allow-removal`. Rows an app needs in order to start are written by a migration step, in the same transaction as its tables; a seed that runs at start is for development and demos.
123
- 18. A grammar change is a migration. Changing a schema behind a document kind — nova's actions and layouts, Prism's config, vex's entries, an app kit's component props (`NiscApp.grammars`) — appends to that grammar's sequence: an empty marker for an addition (strict readers must still refuse the newer documents), document steps (a Prism config over ONE node; the grammar's embeddings find every node) for anything else. `pnpm check:grammars` refuses the change until it does, and checks every captured document still upgrades and parses. A grammar version is history — its migrations, and every corpus file captured at an earlier stamp. Its snapshot is its fingerprint: when the grammar did not change but what records it did (a validator describing the same schema differently, strata reading it differently), the current version is re-recorded with `pnpm strata:snapshot --rebaseline` (an app kit: its own snapshot script with `--rebaseline`) in a commit that changes nothing else, and only while the corpus passes — never edited by hand, never answered with a marker.
124
- 19. Stored and submitted documents carry the stamp they were written at and are upgraded where they are read. Ahead of the reader on any grammar the reader was given is refused (`TOO_NEW`), never guessed at: the reader upgrades first — host before add-on, server before terminal. A JSON column an app reads through vex is upgraded by vex: name it once in `upgradedColumns` ("Using Vex"), not in a function around the read.
125
- 20. An app's source records its grammars in `strata.lock.json`. When a grammar moves: `pnpm strata upgrade` writes the exact expected JSON and a report; edit what it lists; `pnpm strata verify` holds the edit to that JSON and only then moves the lock. Never edit the lock by hand, and never "fix" an edit toward a green verify by any route but the expected JSON. `pnpm check:sources` fails an app whose source is behind.
266
+ - Magic link is the default strategy; there are no username/password pairs in a nisc app if it can be avoided. Login is the anonymous principal's application.
267
+ - Session lifecycle is a **capability, not a channel**: login and sign-out are ordinary `fn:` endpoints calling `session.grant(token)` and `session.revoke()`, and the terminal reconnects as the new principal.
268
+ - The server consumes sessions and never mints identity.
269
+ - A page served by its app does not keep its session: the **browser** does, in a cookie no script can read. Moss writes it in its answer to the socket's upgrade and reads it for two things only — the upgrade from the app's own page, and choosing whose screen to draw. No route answers to it.
270
+ - Nothing in an app stores a token: not `localStorage`, not a cookie script can read.
271
+ - A sign-in the app answers over HTTP (a redeemed link, a provider's callback) sets that cookie on its response with `sessionCookies(request, token)` and redirects; it never hands the token to the page.
272
+ - A terminal that is not a page of its app (a process, another origin) keeps its own token and offers it.
273
+
274
+ ### Schemas
275
+
276
+ **13.** Everything that crosses a boundary is parsed by a Zod schema at that boundary. `.strict()` on external input.
277
+
278
+ **14.** An action's openable inputs live in its definition's optional `input` field.
279
+
280
+ - `input` is a JSON Schema — authored in Zod with `.describe()` on every field, converted with `z.toJSONSchema` — of the `data` keys an opener may seed when loading the action.
281
+ - The fields are a subset of `data`. No seedable keys, no `input`.
282
+ - That schema is the action's public contract, for a nav item, a URL, a command palette, and an agent alike.
283
+ - Catalogs curate ids and descriptions and are resolved per principal (moss serves the resolved catalog). They read `input` off the definition, never restate it.
284
+
285
+ **15.** For any LLM contract, the Zod schema is the single source of truth: constraints in `.describe()`, JSON Schema injected into the prompt at runtime, always minified. No prose "how the DSL works" sections in prompts.
286
+
287
+ ### Code
288
+
289
+ **16.** `STYLE_GUIDE.md`, beside this file, applies in full, with two app-level overrides:
290
+
291
+ - It is written for the packages, so its "custom error classes for domain errors" does **not** apply here: an app declares no classes at all and throws plain `Error`.
292
+ - "Package prompts serve every app" binds packages, not apps: an app's prompts may be about the app. What an app measures against a package's agent is fixed in that package only in general form (see that section).
293
+
294
+ Zero-tolerance: `any`, type assertions (`as` and `<T>` — `as const` and `<const>` excepted), non-null `!`, `enum`, classes, default exports, `function` declarations. In an app, the shape check reads these by the compiler (see "Verification"). Deps via `pnpm add` only. Files: `kebab-case.role.ts`.
295
+
296
+ Declared exception: a file that must match an external module's shape (a shim) may break these rules — it says why in a header comment, and reviewers honor it.
297
+
298
+ ### Versions
299
+
300
+ `@niscorp/strata`; the why is `packages/strata/DESIGN.md`.
301
+
302
+ **17.** No package — and no app, where it can help it — runs DDL outside a strata sequence.
303
+
304
+ - Tables change by APPENDING a migration to their owner's sequence. A migration that has run is history, checksummed in the ledger; editing it makes every database that ran it refuse to boot.
305
+ - The first migration of a sequence may be the old `IF NOT EXISTS` DDL verbatim — split with `sqlSteps(ddl)`, never on every `;` — and that is how an existing database adopts.
306
+ - An app's own tables are its `<app>.app` sequence, handed to moss in `runtime.tables` — with `TIDE_SEQUENCE` (from `@niscorp/tide/postgres`, the store made `migrate: false`) when it keeps tide's tables.
307
+ - A real database's tables change only through `nisc migrate`. A boot checks them and refuses to start while a migration is pending (`migrations: 'verify'`, the default). Only a runtime whose database starts empty every time (PGlite in memory) writes `migrations: 'apply'`.
308
+ - The function that opens a runtime migrates nothing, seeds nothing and calls no `cache.init()`: what it changes itself is changed before the step can check it.
309
+ - A sequence that has run on a database stays in `runtime.tables` even when nothing uses it any more — the run refuses a ledger that records a sequence nobody names (`UNKNOWN_SEQUENCE`). Its tables go by an appended migration that drops them.
310
+ - One app per database schema: a schema has one ledger.
311
+ - `nisc migrate` refuses a run that removes a table or column or changes a column's type unless it is given `--allow-removal`.
312
+ - Rows an app needs in order to start are written by a migration step, in the same transaction as its tables. A seed that runs at start is for development and demos.
313
+
314
+ **18.** A grammar change is a migration.
315
+
316
+ - Changing a schema behind a document kind — nova's actions and layouts, Prism's config, vex's entries, an app kit's component props (`NiscApp.grammars`) — appends to that grammar's sequence: an empty marker for an addition (strict readers must still refuse the newer documents), document steps (a Prism config over ONE node; the grammar's embeddings find every node) for anything else.
317
+ - The check refuses the change until it does, and checks every captured document still upgrades and parses. For nisc's own grammars that is `pnpm check:grammars` in the nisc repository. For an app kit's grammar it is the app's own snapshot check, built on `@niscorp/strata/check` (lyceum's `src/dev/kit-check.ts`); nisc ships no such script to an app.
318
+ - A grammar version is history — its migrations, and every corpus file captured at an earlier stamp.
319
+ - Its snapshot is its fingerprint. When the grammar did not change but what records it did (a validator describing the same schema differently, strata reading it differently), the current version is re-recorded — `pnpm strata:snapshot --rebaseline` in the nisc repository, an app kit's own snapshot script with `--rebaseline` — in a commit that changes nothing else, and only while the corpus passes. Never edited by hand, never answered with a marker.
320
+
321
+ **19.** Stored and submitted documents carry the stamp they were written at and are upgraded where they are read. Ahead of the reader on any grammar the reader was given is refused (`TOO_NEW`), never guessed at: the reader upgrades first — host before add-on, server before terminal. A JSON column an app reads through vex is upgraded by vex: name it once in `upgradedColumns` ("Using Vex"), not in a function around the read.
322
+
323
+ **20.** An app's source records its grammars in `strata.lock.json`.
324
+
325
+ - When a grammar moves: the app's `strata` script runs `upgrade` (`npm run strata upgrade`), which writes the exact expected JSON and a report; edit what it lists; `npm run strata verify` checks the edit against that JSON and only then moves the lock.
326
+ - Never edit the lock by hand, and never "fix" an edit toward a green verify by any route but the expected JSON.
327
+ - An app whose source is behind fails its checks: the suite of an app made by `npm create nisc` runs `strata status --check` (in the nisc repository, `pnpm check:sources` runs it over the lab apps).
126
328
 
127
329
  ## A worked trio
128
330
 
129
- One feature — a list you can act on — as the three files it actually is. It replays the `todos/open` entry from "Using Vex" below; nothing else about it is special. Read the rules through this, not around it.
331
+ One feature — a list you can act on — as the three files it actually is, in `src/app/actions/domains/todos/`. It replays the `todos/open` entry from "Using Vex" below; nothing else about it is special. Read the rules through this, not around it.
130
332
 
131
- **`todos.action.ts`** — the definition. Every `data` key carries a default; endpoints declare their shaping; triggers catch refs.
333
+ **`todos.action.ts`** — the definition. Every `data` key carries a default; endpoints declare their shaping; triggers catch refs. It declares no `input`: nothing in it is for an opener to seed (rule 14).
132
334
 
133
335
  ```ts
134
- import { z } from 'zod';
135
336
  import type { ActionDefinition } from '@niscorp/nova';
136
337
  import { todosLayout } from './todos.layout';
137
338
  import { todosPrism, setDonePrism } from './todos.prism';
@@ -140,7 +341,7 @@ export const todosAction: ActionDefinition = {
140
341
  id: 'todos.list',
141
342
  title: 'Todos',
142
343
  // endpoint-fed slots + UI state — every key present, every key defaulted
143
- data: { ownerId: '', rows: [], toggleTodoId: '', toggleDone: false, loading: true },
344
+ data: { rows: [], toggleTodoId: '', toggleDone: false, loading: true, error: '' },
144
345
  layout: todosLayout,
145
346
  // a contract, not an implementation (rule 7): the same action runs
146
347
  // unchanged against moss or against a degrade app's own endpoints
@@ -157,32 +358,25 @@ export const todosAction: ActionDefinition = {
157
358
  do: [
158
359
  { set: 'toggleTodoId', value: '@event.payload.todo_id' },
159
360
  { set: 'toggleDone', value: '@event.payload.next' },
361
+ { set: 'error', value: '' },
160
362
  // writers announce…
161
- { call: 'setDone', onSuccess: [{ call: 'load' }, { emit: { channel: 'todos-changed' } }] },
363
+ { call: 'setDone', onSuccess: [{ call: 'load' }, { emit: { channel: 'todos-changed' } }], onError: [{ set: 'error', value: '{{@error.message}}' }] },
162
364
  ],
163
365
  },
164
366
  // …viewers react — this action displays todos too, so it listens to its own
165
367
  { message: 'todos-changed', do: [{ call: 'load' }] },
166
368
  ],
167
369
  };
168
-
169
- // Rule 14: what an opener may seed, as a JSON Schema. Every field described;
170
- // every field a key of `data` above.
171
- export const todosInputSchema = z.toJSONSchema(
172
- z.object({
173
- ownerId: z.string().optional().describe('Seeded from the session by the chrome; never client-authored.'),
174
- }),
175
- );
176
370
  ```
177
371
 
178
- **`todos.layout.ts`** — JSON. Domain-blind primitives driven by spec props (rule 2); `ref` is what the trigger catches. Component names resolve against the app's registry in `ui/`. Nova ships a headless base set per adapter (`Stack`, `Box`, `Text`, `Input`, `Button`, `Panel`, `JsonTree`, plus the `CanvasSlot` / `ActionSlot` markers) via `registerNovaReactComponents` — but the reference apps take at most the two slot markers and build the rest themselves, because the kit is where the app's look lives (order of work, step 3). Assume every other name here is one you define.
372
+ **`todos.layout.ts`** — JSON. Domain-blind primitives driven by spec props, configured by name, never sized (rule 2); `ref` is what the trigger catches. Component names resolve against the app's registry in `ui/`. Nova ships a headless base set per adapter (`Stack`, `Box`, `Text`, `Input`, `Button`, `Panel`, `JsonTree`, plus the `CanvasSlot` / `ActionSlot` markers) via `registerNovaReactComponents` — but the reference apps take at most the two slot markers and build the rest themselves, because the kit is where the app's look lives (order of work, step 3). Every name here is one you define.
179
373
 
180
374
  ```ts
181
375
  import type { LayoutNode } from '@niscorp/nova';
182
376
 
183
377
  export const todosLayout: LayoutNode = {
184
- component: 'Stack',
185
- props: { gap: 20, maxWidth: 900 },
378
+ component: 'Column',
379
+ props: { gap: 'loose' }, // a name from the kit's closed set, not a size
186
380
  children: [
187
381
  {
188
382
  component: 'Rows', // generic, not TodoRow
@@ -192,11 +386,12 @@ export const todosLayout: LayoutNode = {
192
386
  rowKey: 'todo_id',
193
387
  empty: 'Nothing open.',
194
388
  columns: [ // repeated structure is DATA
195
- { label: 'Todo', w: 1, cell: { kind: 'primary', key: 'title', subKey: 'due_display' } },
196
- { label: 'Done', w: 'auto', cell: { kind: 'switch', key: 'done', ref: 'toggle', label: '' } },
389
+ { label: 'Todo', width: 'fill', cell: { kind: 'primary', key: 'title', subKey: 'due_display' } },
390
+ { label: 'Done', width: 'fit', cell: { kind: 'switch', key: 'done', ref: 'toggle', label: '' } },
197
391
  ],
198
392
  },
199
393
  },
394
+ { if: '$.error', then: { component: 'Text', children: '{{$.error}}' } },
200
395
  ],
201
396
  };
202
397
  ```
@@ -204,11 +399,11 @@ export const todosLayout: LayoutNode = {
204
399
  **`todos.prism.ts`** — the endpoint bodies. A Vex replay is `{ fingerprint, context }`; `$ref` pulls from the action's own data (rule 5).
205
400
 
206
401
  ```ts
207
- import { todosOpen, todoSetDone } from '../../vex/todo.entries';
402
+ import { todosOpen, todoSetDone } from '../../../vex/todo.entries';
208
403
 
209
404
  export const todosPrism = {
210
405
  fingerprint: todosOpen.fingerprint,
211
- context: { ownerId: { $ref: '$.ownerId' } },
406
+ context: {},
212
407
  };
213
408
 
214
409
  export const setDonePrism = {
@@ -217,42 +412,63 @@ export const setDonePrism = {
217
412
  };
218
413
  ```
219
414
 
220
- Note what is absent: no React, no `fetch`, no date formatting, no `if (role === …)`, no `owner_id` on the wire from the client. `due_display` arrives already formatted — that happened in the entry's mapping, upstream (rule 9).
415
+ Note what is absent: no React, no `fetch`, no date formatting, no `if (role === …)`, no sizes in the layout. No owner is on the wire: whose todos these are is not in any request — the charter's `data` grant and the app's `behaviors` keep `todos` to the caller's own rows (rules 8, 10). `due_display` arrives already formatted — that happened in the entry's mapping, upstream (rule 9).
221
416
 
222
417
  ## Using Vex
223
418
 
224
- Whether to use Vex is D3 (reads) and D4 (writes). How to use it is not a choice:
419
+ Whether to use Vex is D3 (reads) and D4 (writes). How to use it is not a choice.
225
420
 
226
- - **Reads the app depends on are deterministic.** Author each one as a seed entry — Vex's own cache row minus the machine-filled bits. `SeedEntry` and `SeedMutation` are exported for exactly this; don't hand-roll a `Pick<>` over the cache types:
421
+ **Reads the app depends on are deterministic.** Author each one as a seed entry — Vex's own cache row minus the machine-filled bits. `SeedEntry` and `SeedMutation` are exported for exactly this; don't hand-roll a `Pick<>` over the cache types:
227
422
 
228
423
  ```ts
229
424
  import type { SeedEntry } from '@niscorp/vex';
425
+ import { dayText } from '../prisms/dates.prism'; // shared helper: returns a Prism config
230
426
 
231
427
  export const todosOpen: SeedEntry = {
232
428
  fingerprint: 'todos/open', // THE cache key — the name every read replays
233
429
  intent: 'List open todos ordered by due date', // one factual sentence — mandatory
234
- shape: [{ todo_id: '', title: '', due_display: '' }], // drives the array-vs-single envelope on replay
430
+ shape: [{ todo_id: '', title: '', done: false, due_date: '', due_display: '' }], // drives the array-vs-single envelope on replay
235
431
  dsl: { // hand-authored; { $context: 'key' } for parameters
236
432
  from: ['todos'],
237
- fields: [{ field: 'todos.id', as: 'todo_id' }, 'todos.title', 'todos.due_date'],
433
+ fields: [{ field: 'todos.id', as: 'todo_id' }, 'todos.title', 'todos.done', 'todos.due_date'],
238
434
  filter: { eq: ['todos.done', false] },
239
435
  sort: [{ field: 'todos.due_date', dir: 'asc' }],
240
436
  limit: 200, // how many rows this list is for — state it on every list
241
437
  },
242
- mapping: { /* Prism over { result }: the rows (array shape) or the one row (object shape); omit when the DSL already aliases to the shape */ },
438
+ mapping: { // Prism over { result, context, scope }: here the rows
439
+ $map: {
440
+ over: { $ref: '$.result' },
441
+ as: 'row',
442
+ body: {
443
+ todo_id: { $get: { from: { $var: 'row' }, path: ['todo_id'] } },
444
+ title: { $get: { from: { $var: 'row' }, path: ['title'] } },
445
+ done: { $get: { from: { $var: 'row' }, path: ['done'] } },
446
+ due_date: { $get: { from: { $var: 'row' }, path: ['due_date'] } },
447
+ due_display: dayText({ $get: { from: { $var: 'row' }, path: ['due_date'] } }),
448
+ },
449
+ },
450
+ },
243
451
  };
244
452
  ```
245
453
 
246
- - **Every list states its `limit`.** A seeded entry reads at most the `limit` it states, and the engine does not lower that number unless the deployment tells it to. A list that states none gets the engine's default of 100 and no more — when exactly that many come back, the reply's `meta.warnings` and the server console say the list may have been cut. That line means the entry is missing a `limit`; write one.
247
- - **Writes are mutation entries in the same store.** A `SeedMutation`: a statement in the closed mutation grammar in place of a query DSL, the same wire shape (`{ fingerprint, context }`). Mutations are replay-only forever — never generated; `lintMutation` runs at seed and throws on a failing statement, and context signatures are derived for discovery.
248
- - **A parent and its children are one batch.** An array of statements runs in one transaction, and a later statement reads the row an earlier one wrote: `{ $returned: 'orders.id' }` is the id the database just generated for the `orders` insert earlier in the same batch, so a generated id reaches the rows that point at it without leaving the server, and the write is all or nothing. The statement it names must write exactly one row, or the whole batch is refused. The reply is every statement's rows in order — and exactly one row comes back as that row, not an array of one.
249
- - **Under moss (the D1 default), hand the entries to `defineApp({ entries })`.** The server derives the data layer: boots the engine, holds the entries and compiles them, serves locked replay-only endpoints, and compiles each principal's `ScopePolicy` from the charter's `data` section. The app never touches an engine, and never writes an entry into vex's cache table itself: entries that arrive while the app runs are handed over with `server.replaceEntries(source, entries)`.
250
- - **A client-degrade app boots its own engine** — database adapter + cache backend + `ScopePolicy` — `introspect()` once at startup, memoized behind a single accessor. Prewarm at boot through the cache backend's own `set()`: key = the entry's `fingerprint`, `prismIr` = `await compile(mapping ?? { $ref: '$.result' })` (`@niscorp/prism`), plus the shape, the schema fingerprint, and `protected: true` — a seeded entry can never be replaced by a stray request. Seed the identity IR for mapping-less entries explicitly — a NULL IR falls through to the LLM mapper. Throw on duplicate names while seeding.
454
+ - **Every list states its `limit`.** A seeded entry reads at most the `limit` it states, and the engine does not lower that number unless the deployment tells it to. A list that states none gets the engine's default of 100 and no more. When exactly that many come back, the reply's `meta.warnings` and the server console say the list may have been cut. That line means the entry is missing a `limit`; write one.
455
+ - **Writes are mutation entries in the same store.** A `SeedMutation`: a statement in the closed mutation grammar in place of a query DSL, the same wire shape (`{ fingerprint, context }`). Mutations are replay-only forever — never generated. `lintMutation` runs at seed and throws on a failing statement, and context signatures are derived for discovery.
456
+ - **A parent and its children are one batch.** An array of statements runs in one transaction, and a later statement reads the row an earlier one wrote. `{ $returned: 'orders.id' }` is the id the database just generated for the `orders` insert earlier in the same batch, so a generated id reaches the rows that point at it without leaving the server, and the write is all or nothing. The statement it names must write exactly one row, or the whole batch is refused. The reply is every statement's rows in order — and exactly one row comes back as that row, not an array of one.
457
+ - **Under moss (the D1 default), hand the entries to `defineApp({ entries })`.** The server derives the data layer: boots the engine, keeps the entries and compiles them, serves locked replay-only endpoints, and compiles each principal's `ScopePolicy` from the charter's `data` section. The app never touches an engine, and never writes an entry into vex's cache table itself: entries that arrive while the app runs are handed over with `server.replaceEntries(source, entries)`.
458
+ - **A client-degrade app boots its own engine** — database adapter + cache backend + `ScopePolicy` — `introspect()` once at startup, memoized behind a single accessor.
459
+ - Prewarm at boot through the cache backend's own `set()`: key = the entry's `fingerprint`, `prismIr` = `await compile(mapping ?? { $ref: '$.result' })` (`@niscorp/prism`), plus the shape, the schema fingerprint, and `protected: true` — a seeded entry can never be replaced by a stray request.
460
+ - Seed the identity IR for mapping-less entries explicitly — a NULL IR falls through to the LLM mapper.
461
+ - Throw on duplicate names while seeding.
462
+ - vex's `seedCache(cache, entries)` compiles each mapping (the identity where there is none) and writes it `protected: true`, but it neither stamps the schema fingerprint nor refuses two entries of one fingerprint (the later replaces the earlier), so a degrade app writes its rows itself, as mythos's `src/vex/prewarm.ts` does.
251
463
  - **The fingerprint is the cache key.** Every entry replays as `{ fingerprint, context }` — no shape, no intent on the wire. Id fields still follow `<entity>_id` (self-describing rows); never a shared `{ value, label }`.
252
464
  - **A JSON column whose values carry a stamp is named once, in `defineApp({ upgradedColumns })`**, keyed by table and column: `{ answers: { plan: { stamp: 'grammar', kind: 'acme.answers/plan' } } }`, or `kind: { grammar, column }` when the row says which kind it is. Only the app's own tables: a feature's tables are its own, and naming one refuses the boot. Its grammar goes in `grammars`. Every read of it, replay or reactive, hands the mapping the value upgraded and the stamp current (rule 19). A read returns it only as one of its own fields, and returns its stamp column (and the kind column) beside it; vex refuses any other read of it when the read is compiled, and moss compiles every seeded read at boot, so such an entry refuses the boot. A row that does not upgrade (written by newer code, `TOO_NEW`; a step that fails, `STEP_FAILED`; a kind no grammar declares, `UNKNOWN_KIND`) refuses the whole read, unless the column says `unreadable: 'omit'` (the row is left out) or `'null'` (the value is null); either is said in `meta.warnings`. vex DOCS.md, "Upgraded columns", has every rule. A client-degrade app hands its engine `upgradedColumns` and `upgrader` (strata's `createUpgrader(...)`) itself.
253
- - **The mapping owns the result shape.** Vex evaluates it over `{ result, context, scope }` and returns the output verbatim — array, object, or scalar. The entry's stored shape picks what `$.result` is: an **array** shape → `$.result` is the rows (map with `$map`, or `{ $ref: '$.result' }` for identity); an **object** shape → `$.result` is the single (first) row, `null` when none came back (read fields as `$.result.monthly`, never `[0, …]`). Formatting (money, dates) lives here, in shared helpers.
465
+ - **The mapping owns the result shape.** Vex evaluates it over `{ result, context, scope }` and returns the output verbatim — array, object, or scalar. The entry's stored shape picks what `$.result` is:
466
+ - an **array** shape → `$.result` is the rows (map with `$map`, or `{ $ref: '$.result' }` for identity);
467
+ - an **object** shape → `$.result` is the single (first) row, `null` when none came back (read fields as `$.result.monthly`, never `[0, …]`).
468
+
469
+ Formatting (money, dates) lives here, in shared helpers.
254
470
  - **App reads are replay-only.** Moss serves its endpoints locked; a client-degrade app passes `{ locked: true }` itself. An unknown fingerprint (a missed prewarm, a discipline break) is a 500, never a silent LLM call. With no AI features, also wire no hooks: warm-only, enforced twice.
255
- - **Live queries are the opt-in LLM path.** Wire `createQueryDsl` / `createShapeMapper` (`@niscorp/vex/agent`) as the engine's `generateDsl` / `mapToShape` hooks; a request without a fingerprint generates, caches, and mints one (`meta.cache.fingerprint`) — embed that to replay the proven query. App reads stay locked and never depend on this path; agents and ad-hoc features do.
471
+ - **Live queries are the opt-in LLM path.** Wire `createQueryDsl` / `createShapeMapper` (`@niscorp/vex/agent`) as the engine's `generateDsl` / `mapToShape` hooks. A request without a fingerprint generates, caches, and mints one (`meta.cache.fingerprint`) — embed that to replay the proven query. App reads stay locked and never depend on this path; agents and ad-hoc features do.
256
472
  - **Freshness is the entry's.** `refresh: 'snapshot'` (the default) answers once; `refresh: 'reactive'` answers again when a write lands on a table the query reads. Declare it on reads that are on screen while others write — a roster, a count, a board. A reactive entry sorts, and reads time from `$scope`, never context.
257
473
  - **Staleness is handled through the slot.** When an entry must change, send its fingerprint with the changed request — the slot regenerates and replaces (protected entries 409 until unprotected). Don't edit cache rows by hand.
258
474
  - **Scope is engine-side.** Access policy lives in the engine's `ScopePolicy` — compiled from the charter under moss — invisible to and unforgeable by query authors, human or LLM.
@@ -263,114 +479,44 @@ Stack-independent conventions:
263
479
 
264
480
  - **Action data = endpoint-fed slots + UI state**, every key with a default. Loading is explicit data (`loading: true`), not Suspense.
265
481
  - **Mount loads; `onSuccess` chains dependent loads.** Each independent section of a detail action is its own endpoint into its own slot.
266
- - **Reactive reads keep screens current; channels are for what is not data.** A vex read whose entry declares `refresh: 'reactive'` answers again, on every screen that has it open, whenever a write lands on a table it reads — nothing announces the change and nothing listens (vex DESIGN.md, "Reactive reads"). Under moss, that is how a screen follows its data. Where a read stays a snapshot, or a client-degrade app has no follower, the older pattern holds: writers announce, viewers react — a successful write emits a channel (`<entity>s-changed`) and every action displaying that entity listens and re-reads. Channels also carry signals that are not data (the deck moving on). No shared stores. A message can carry a payload (`{ emit: { channel, payload } }`, or moss's `shells.deliver(principal, channel, payload)` from the server); a listener reads it as `@event.payload`. A payload says what happened, never data a screen should read: data still reaches a screen through its reads.
482
+ - **Reactive reads keep screens current; channels are for what is not data.**
483
+ - A vex read whose entry declares `refresh: 'reactive'` answers again, on every screen that has it open, whenever a write lands on a table it reads — nothing announces the change and nothing listens (vex DESIGN.md, "Reactive reads"). Under moss, that is how a screen follows its data.
484
+ - Where a read stays a snapshot, or a client-degrade app has no follower: writers announce, viewers react. A successful write emits a channel (`<entity>s-changed`) and every action displaying that entity listens and re-reads.
485
+ - Channels also carry signals that are not data (the deck moving on). No shared stores.
486
+ - A message can carry a payload (`{ emit: { channel, payload } }`, or moss's `shells.deliver(principal, channel, payload)` from the server); a listener reads it as `@event.payload`. A payload says what happened, never data a screen should read: data still reaches a screen through its reads.
267
487
  - **One form action per entity, create and edit.** Loaded bare it creates; loaded with the record's raw fields seeded it edits. Keep raw values (numbers, ISO dates, ids) alongside `*_display` strings so forms round-trip.
268
488
  - **Interaction = `ref` + trigger.** Layout nodes carry `ref`; triggers catch `{ event, ref }` and run steps. Event payloads flow via `@event.payload`; no callbacks in props.
269
- - **A composed surface is rows, not a layout.** Where several things coexist — a home, a launcher strip, an agent's column — use a `list` canvas seeded by `seeds` from resolved rows, and let each action render itself. Which surfaces land where is the *row's* business (its canvas), not a second authored list. Whether an action can appear that way is read off its own contract — an action that declares a collapse key in its `input` can render small, so a surface that ships one joins the composition the moment its rows land, with no registry to update.
270
- - **What should still be there is a row, not a screen.** A server shell is memory: a deploy, a restart or an idle spell replaces it with one built from the manifest and whatever the app reads from rows as it builds — `inputs`, `seeds`, an action's mount hook. So what a person should find again is a row, and an action that shows nothing keeps a canvas on it: its mount reads the row and `replace`s or `reconcile`s the canvas (lyceum's `stage.deck` keeps the stage on the slide its `deck` row names). A screen a person opened that no row describes — a sheet, a record pushed over a list — is gone after a rebuild, with whatever was typed into it. Shell state is the truth of what is on screen now (rule 4); it is not kept.
489
+ - **A composed surface is rows, not a layout.** Where several things coexist — a home, a launcher strip, an agent's column — use a `list` canvas seeded by `seeds` from resolved rows, and let each action render itself. Which surfaces land where is the *row's* business (its canvas), not a second authored list. Whether an action can appear that way is read off its own contract: an action that declares a collapse key in its `input` can render small, so a surface that ships one joins the composition the moment its rows land, with no registry to update.
490
+ - **What should still be there is a row, not a screen.**
491
+ - A server shell is memory. A deploy, a restart or an idle spell replaces it with one built from the manifest and whatever the app reads from rows as it builds — `inputs`, `seeds`, an action's mount hook.
492
+ - So what a person should find again is a row, and an action that shows nothing keeps a canvas on it: its mount reads the row and `replace`s or `reconcile`s the canvas (lyceum's `stage.deck` keeps the stage on the slide its `deck` row names).
493
+ - A screen a person opened that no row describes — a sheet, a record pushed over a list — is gone after a rebuild, with whatever was typed into it.
494
+ - Shell state is the truth of what is on screen now (rule 4); it is not kept.
271
495
  - **What a lost connection looks like is the kit's.** When the socket drops, the last screen stays up while the terminal reconnects, and looks exactly like a live one. Every render target is told the connection's status: a browser target says it on its root element (`data-wire-status`: `connecting`, `open`, `closed`, `incompatible`, `static`) and draws nothing, so the kit's stylesheet decides what `closed` looks like. No action, layout or component prop carries it: the connection is the terminal's, not the app's data.
272
496
  - **Seeds choose their clock.** A seed pins a fixed reference date or shifts with the wall clock — per what the seed is for: a regression fixture pins, a demo that must look alive today shifts. Either way the app compares against injected context (`$.today`, per request under moss) — never a wall-clock read inside a transform, query, or layout.
273
- - **The app is a manifest; only degrade shells are factories.** Under moss the app is `defineApp({...})` and the server builds one durable shell per principal — dev checks boot the same manifest with a dev runtime. A client-degrade app builds its shell as `createAppShell(deps)` with everything environmental injected, so checks construct the real app with real deps and nothing leaks between runs.
274
-
275
- ## Failure modes worth naming
276
-
277
- Four mistakes that have each cost more than the thing they were avoiding. The
278
- first three share one shape — **concluding the system cannot do something without
279
- testing whether it can** — and each produced a workaround larger than the check
280
- would have been. The fourth is what happens on the way back out.
281
-
282
- ### 1. Do not rationalise a limitation into a principle
283
-
284
- While adding per-role reach (`scoping`), the resolver collapsed a principal's
285
- roles into ONE profile and threw when two roles named different ones. That throw
286
- was written up as *"incoherence, not a precedence puzzle — refused, in the same
287
- spirit as two granted layout variants for one action."*
288
-
289
- It is not the same. Two layout variants for one action genuinely conflict — a
290
- screen renders one. Two roles naming different reaches is an instructor who also
291
- trains: staff on the roster, a member in the class. The rule existed to make the
292
- design self-consistent, and the domain broke it within the hour.
293
-
294
- **The tell:** a rule justified by analogy to a different rule, rather than by a
295
- case it would prevent. If you cannot name the bad thing it stops, it is a
296
- limitation wearing a principle's clothes.
297
-
298
- ### 2. Test the mechanism before you blame it
299
-
300
- A charter `deny` was used to stop a grant riding up the role ladder. It appeared
301
- not to survive `extends`, so a table that should have been deleted was kept and
302
- the "limitation" was written into permanent comments as its justification.
303
-
304
- `deny` works exactly as documented — a child re-adds a denied grant, verified in
305
- five lines. What had actually happened: a patch script targeted the wrong role
306
- because line numbers shifted after an earlier edit. The fault was in the edit,
307
- not the engine.
308
-
309
- **The rule:** before documenting a limitation in someone else's package, write
310
- the smallest program that demonstrates it. If that program is hard to write, the
311
- limitation probably is not real.
312
-
313
- ### 3. Believe the schema over the resolver
314
-
315
- The schema splits `staff` and `memberships` into two tables, with a comment
316
- saying why: *a person can be staff at a studio and hold a membership there too.*
317
- The directory above it then flattened every person to one word
318
- (`audienceOf(staffRole) ?? 'member'`), and `assignments` gave each person one
319
- role. The thing the data model deliberately kept apart, the policy layer
320
- collapsed — and three workarounds grew on top of the collapse: an extra scoping
321
- profile, a projection table, and a deny that was never needed.
322
-
323
- **The rule:** when a resolver contradicts a comment in the schema, the schema is
324
- usually right. It was written when somebody was thinking about the domain; the
325
- resolver was written when somebody was thinking about the code.
326
-
327
- ### 4. Undoing a workaround moves the boundary — say where it went
328
-
329
- Deleting the three workarounds was not free, and the free-looking version would
330
- have been the dangerous one. `member_cards` existed so a member could see their
331
- plan and price without holding `subscriptions.read`; deleting it means the member
332
- rung holds that verb, at personal reach. Replaying the revenue fingerprint as a
333
- member therefore returns a *number* rather than a refusal — their own bill, not
334
- the studio's — where before it bounced at the verb.
335
-
336
- That is a real weakening, and it is the right trade: the same verb at two reaches
337
- is the whole design. But it was found by a check going red, not by the reasoning
338
- that authored the change. Two existing checks asserted "refused" and had to be
339
- rewritten to assert "not the studio's figure" — and rewriting a red assertion is
340
- exactly where a leak gets waved through.
341
-
342
- **The rule:** when a check fails because the design moved, do not adjust it to
343
- match the new behaviour. Work out what the old assertion was protecting, then
344
- write the assertion that protects the same thing under the new shape. Here that
345
- meant comparing the member's figure against the owner's rather than testing for a
346
- status code.
347
-
348
- **And check the ones that stayed green.** A check that asserts a *mechanism* can
349
- go on passing while the *consequence* it was standing in for has inverted.
350
- `scoping-check` asserted "an instructor who also trains reads the whole studio" —
351
- green, correct, and describing a screen that was showing him all 93 bookings at
352
- the studio under the heading "what you have booked". Widening reach turned a
353
- true statement about the engine into a false one about the product. After a
354
- change to how far somebody reaches, re-read every assertion that mentions them,
355
- not only the red ones.
356
-
357
- ### The habit that catches all four
358
-
359
- Before building around a constraint, spend five minutes proving it exists. Every
360
- workaround in this list was bigger than its proof would have been, and two of
361
- them were built around constraints that were never there.
362
-
363
- And when you take one out, name what it was holding up. A workaround that was
364
- never needed still moved a boundary while it stood there.
497
+ - **The app is a manifest; only degrade shells are factories.** Under moss the app is `defineApp({...})` and the server builds one durable shell per principal — dev checks boot the same manifest with a dev runtime. A client-degrade app builds its shell in the app's own boot (`boot()` in an app `npm create nisc` makes; mythos's `createAppShell`) — see "The client-degrade path".
498
+
499
+ ## Before working around a limitation
500
+
501
+ Each of these cost more than the check that would have prevented it. The first three share one shape: concluding the system cannot do something without testing whether it can.
502
+
503
+ 1. **Do not turn a limitation into a principle.** A rule earns its place by naming a case it prevents. A rule justified by analogy to a different rule, when you cannot name the bad thing it stops, is a limitation wearing a principle's clothes. For example: two layout variants for one action genuinely conflict, because a screen renders one; two roles of one person that reach different rows do not — someone can be staff in one place and a member in another.
504
+ 2. **Test the mechanism before you blame it.** Before documenting a limitation in someone else's package, write the smallest program that demonstrates it. If that program is hard to write, the limitation probably is not real.
505
+ 3. **Believe the schema over the resolver.** When a resolver contradicts a comment in the schema, the schema is usually right: it was written by somebody thinking about the domain, the resolver by somebody thinking about the code. For example: a schema that keeps two tables apart because one person can be in both is usually right over a resolver that gives each person one role.
506
+ 4. **Undoing a workaround moves a boundary — say where it went.**
507
+ - When a check fails because the design moved, do not adjust it to match the new behaviour: rewriting a red assertion is exactly where a leak gets let through unnoticed. Work out what the old assertion was protecting, then write the assertion that protects the same thing under the new shape — for example, compare what a member reads against the owner's figure rather than testing for a status code.
508
+ - Re-read the checks that stayed green. A check that asserts a *mechanism* can go on passing while the *consequence* it stood for has inverted. After a change to how far somebody reaches, re-read every assertion that mentions them, not only the red ones.
509
+
510
+ The habit that catches all four: before building around a constraint, spend five minutes proving it exists. When you take a workaround out, name what it was keeping in place: a workaround that was never needed still moved a boundary while it was there.
365
511
 
366
512
  ## Layout of an app
367
513
 
368
- One arrangement. `app/` holds **artifacts only**: every file there is pure, schema-valid JSON authored in TS (a check enforces it). Code lives outside `app/` — the environment in `db/`, helpers in `lib/`, the server glue and fns in `server/`, the component kit in `ui/`.
514
+ One arrangement. `app/` has **artifacts only**: every file there is pure, schema-valid JSON authored in TS (a check enforces it). Code lives outside `app/` — the environment in `db/`, helpers in `lib/`, the server glue and fns in `server/`, the component kit in `ui/`.
369
515
 
370
516
  Three naming rules make the tree legible, and they're the same rules the artifact library will type its rows by:
371
517
 
372
518
  - **A folder names the governor** (or, for nova's many kinds, the domain): `charter/` and `vex/` group a library's artifacts; `actions/domains/<x>/` groups a domain's.
373
- - **A suffix names the kind** — the specific artifact type, which is also its library row type: `.action.ts`, `.layout.ts`, `.fragment.ts`, `.prism.ts`, `.entries.ts`. Multi-member kinds (many files, one artifact each) carry it. A file holding several artifacts of one kind pluralizes — `issue.actions.ts`, `arrival.layouts.ts` — which is a legitimate grouping when the artifacts are one feature's set, not a dumping ground.
519
+ - **A suffix names the kind** — the specific artifact type, which is also its library row type: `.action.ts`, `.layout.ts`, `.fragment.ts`, `.prism.ts`, `.entries.ts`. Multi-member kinds (many files, one artifact each) carry it. A file with several artifacts of one kind pluralizes — `issue.actions.ts`, `arrival.layouts.ts` — a legitimate grouping when the artifacts are one feature's set, not a dumping ground.
374
520
  - **A single-document field is named by the field, no suffix**: `charter.ts`, `assignments.ts`, `behaviors.ts`, `resources.ts`, `app.ts`. There's only one — nothing to disambiguate. Index files that assemble a kind are named for it: `action-catalog.ts`, `layout-variants.ts`.
375
521
 
376
522
  There is deliberately **no library suffix** (`.vex.ts`, `.charter.ts`): the suffix names the kind, not the governor — the governor is the folder. `.action.ts` is not `.nova.ts`.
@@ -404,19 +550,23 @@ src/
404
550
  <html>). No production route: `nisc start` serves the built terminal.
405
551
  No dev glue either: `nisc dev` runs the app server inside vite
406
552
  (moss's dev plugin, fed from nisc.config.ts) — vite.config.ts
407
- holds the framework plugin and nothing else
553
+ has the framework plugin and nothing else
408
554
  ui/ the component kit + registry — the only renderer code in the app
409
- dev/ headless checks; strata.ts lists the artifacts for `pnpm strata`
555
+ dev/ headless checks; strata.ts lists the artifacts for the `strata` script
410
556
  main.tsx the terminal entry
411
557
  nisc.config.ts what the app tells the `nisc` command: how it boots, how a screen is
412
- drawn — only if its pages are drawn on the server or built to files
558
+ drawn. Every `nisc` command reads it
413
559
  strata.lock.json which grammar version the source is written in (rule 20) — committed,
414
- moved only by `pnpm strata verify`
560
+ moved only by the `strata` script's `verify`
415
561
  ```
416
562
 
417
- Apps to read: lyceum (`apps/lab/lyceum`) for a moss server app; nisc-website and moccadroid-website for an app with its own shell. atrium, lyra and relay are older: read one for a surface it targets, not as a model.
563
+ Apps to read, in the nisc repository:
564
+
565
+ - lyceum (`apps/lab/lyceum`) for a moss server app.
566
+ - For an app with its own shell: the app `npm create nisc` makes when the shell runs in the browser, and the `@niscorp/cli` README, "An app with its own shell".
567
+ - atrium, lyra and relay (`apps/lab/`) do not follow every rule here: read one for a surface it targets, not as a model.
418
568
 
419
- Why the split: the manifest's data fields are on their way to becoming library rows (deploy = a write, not a rebuild), so keeping them pure and schema-valid now — with `db/` and `lib/` code held firmly outside `app/` — is what makes the tree row-ready. A client-degrade app replaces `server/` with whatever serves its endpoints (per D2) and boots its shell factory from the entry point.
569
+ Why the split: the manifest's data fields are meant to become library rows (deploy = a write, not a rebuild), so keeping them pure and schema-valid — with `db/` and `lib/` code firmly outside `app/` — is what makes the tree row-ready. A client-degrade app replaces `server/` with whatever serves its endpoints (per D2) and boots its shell factory from the entry point.
420
570
 
421
571
  `ui/` is the app's renderer kit, and which renderer is a choice: a React or DOM terminal in a browser, a tty or ink one in a console. The core is surface-blind, so the kit is the only place that isn't — an app targeting two surfaces ships two kits against one registry contract, and nothing above `ui/` changes.
422
572
 
@@ -428,15 +578,18 @@ The degrade is for offline, zero-backend and portable apps — a demo that must
428
578
 
429
579
  What changes is only who assembles and serves:
430
580
 
431
- - **The shell is a factory, not a manifest.** `createAppShell(deps)` builds it in the browser with everything environmental injected — the fetch seam, the app's `today`, the transform socket (rule 6). Nothing environmental is read from module scope, so a check constructs the real app with real deps and nothing leaks between runs.
581
+ - **The shell is a factory, not a manifest.** The app's own boot (`boot()` in an app `npm create nisc` makes; mythos's `createAppShell`) builds it in the browser with everything environmental injected — the fetch seam, the app's `today`, the transform socket (rule 6). Nothing environmental is read from module scope, so a check constructs the real app with real deps and nothing leaks between runs.
432
582
  - **`server/` is replaced by whatever serves the endpoints** (D2): in-memory fixtures, PGlite in the browser, a real backend, or a mix. Endpoints keep their URLs and shapes — that is what makes the posture invisible upstream. The client-side `fn` registry is the escape hatch here and only here (rule 7).
433
- - **The app boots its own Vex engine** — database adapter, cache backend, `ScopePolicy` — `introspect()` once at startup behind a single memoized accessor, prewarming and locking replay itself. See "Using Vex" for the exact seeding contract; under moss the server does all of this, and here the app does.
583
+ - **The app boots its own Vex engine**, prewarming and locking replay itself — see "Using Vex" for the exact seeding contract. Under moss the server does all of this; here the app does.
434
584
  - **`inputs`, `seeds`, `scope`, `onSession` and `runs` have no host.** Whatever they derived, the factory derives at construction. There is no durable per-principal shell and no server-side resolution.
435
- - **The first screen still arrives as markup.** A degrade app is not a blank page until its script runs: `nisc export` runs the app's own boot at build, draws the settled screen to markup, and writes one file per path; the browser entry boots the same shell and adopts it (`@niscorp/cli` README, "An app with its own shell"). The `nisc.config.ts` hands over `shell` (the boot — unmemoized, handed a path and nothing else), `draw` and `adopt`; the build fails unless every path is drawn, whole, the same on a second boot, and adopted clean. That makes the boot's determinism a rule here, not a nicety: no random id or wall-clock read may reach the markup, and a read that answers differently in the page than it did at build is drawn again there — the build names every such read ("opened with …").
585
+ - **The first screen still arrives as markup.** A degrade app is not a blank page until its script runs.
586
+ - `nisc export` runs the app's own boot at build, draws the settled screen to markup, and writes one file per path; the browser entry boots the same shell and adopts it (`@niscorp/cli` README, "An app with its own shell").
587
+ - The `nisc.config.ts` hands over `shell` (the boot — unmemoized, handed a path and nothing else), `draw` and `adopt`. The build fails unless every path is drawn, whole, the same on a second boot, and adopted clean.
588
+ - That makes the boot's determinism a rule here, not a nicety: no random id or wall-clock read may reach the markup. A read that answers differently in the page than it did at build is drawn again there — the build names every such read ("opened with …").
436
589
 
437
590
  Say this out loud in the interview, because it is the part a user cannot infer: **in a degrade app the charter is not enforcement.** Ring 1 still decides what exists in the shell, and that is honest UI, but the data is in the browser and the policy is in the browser with it. Nothing here is a security boundary. An app that needs one needs a server (D1) — offer that rather than a scope rule that looks like a lock.
438
591
 
439
- `fable` and `mythos` predate the `app/`-is-artifacts-only tree above and are arranged differently (`nova/`, `api/`, `vex/`, and mythos's `boot.ts`) — read them for the boot and engine wiring, not for the layout.
592
+ `fable` and `mythos` (`apps/lab/`) are arranged differently from the `app/`-is-artifacts-only tree above (`nova/`, `api/`, `vex/`, and mythos's `boot.ts`) — read them for the boot and engine wiring, not for the layout.
440
593
 
441
594
  ## Order of work
442
595
 
@@ -452,53 +605,17 @@ Each step ends with its checks green and a review (`REVIEW.md`).
452
605
 
453
606
  ## Verification
454
607
 
455
- Every feature ships a headless check: a standalone script under `dev/` that boots the real app — for a moss app, the manifest through `createServer` with a dev runtime; for a degrade app, the shell factory — dispatches events against the shell, asserts on runtime data and the render tree (`@niscorp/nova/reflect` reads a live tree), prints one `[pass]`/`[fail]` line per assertion, and exits non-zero on any failure. No browser, no mocks.
456
-
457
- A `dev/all-checks.ts` runs the suite and is the app's `check` script. It spawns **each check as its own process over its own fresh database** — checks ship the app different histories, and a shared database would make the order of the suite part of its meaning.
608
+ Every feature ships a headless check: a standalone script under `dev/` that
458
609
 
459
- The suite runs a **shape check** too, `src/dev/shape-check.ts`, which hands the app's actions and entries to `runShapeCheck` (`@niscorp/cli/shape`). It reads what behaviour checks cannot see: rule 16 by the compiler, formatting outside Prism, roles read in server code, the kit reaching past its own elements, code in `src/app` called while the app runs, and every server function an action calls, named with what it does that a vex read or write cannot. What the app allows, it names in that file, file by file, with why.
460
-
461
- **Reviewing** is `REVIEW.md`, beside this file: how to run a review, the checklist, what to look for, and how to report — by rule number. Run one after each step of the order of work. A change that makes the app less declarative, less validated, or less observable is wrong even if it works.
610
+ - boots the real app — for a moss app, the manifest through `createServer` with a dev runtime; for a degrade app, the shell factory;
611
+ - dispatches events against the shell;
612
+ - asserts on runtime data and the render tree (`@niscorp/nova/reflect` reads a live tree);
613
+ - prints one `[pass]`/`[fail]` line per assertion, and exits non-zero on any failure.
462
614
 
463
- ## Changing a package
615
+ No browser, no mocks.
464
616
 
465
- **This part is for whoever changes a `@niscorp` package. Everything above it is for whoever builds an app on them.** Read `/STYLE_GUIDE.md`, "The packages are live", before it: what a change may do to an app that works today comes first.
617
+ `src/dev/all-checks.ts` runs the suite; the app's `check` script is `nisc check`, which runs it. It spawns **each check as its own process over its own fresh database** — checks ship the app different histories, and a shared database would make the order of the suite part of its meaning.
466
618
 
467
- **A package is held to the rules nisc sets for apps.** It runs no SQL of its own: its reads and writes are vex entries, as an app's are ("Using Vex"). What crosses a boundary is parsed by a schema (rule 13), rule 16 applies in full, and its tables are strata sequences (rule 17). Moss broke each of them for as long as they were only written down: forty statements sent straight to the pool, one boundary with a schema, 135 exported names of which 71 were imported by nothing, one function of 1,345 lines (the audit is in the history of `docs/plans/moss-refactor.md`). The rules below are what was missing, and each has a build that fails.
619
+ The suite runs a **shape check** too, `src/dev/shape-check.ts`, which hands the app's actions and entries to `runShapeCheck` (`@niscorp/cli/shape`). It reads what behaviour checks cannot see: rule 16 by the compiler, formatting outside Prism, roles read in server code, the kit reading files, the address or elements past its own, code in `src/app` called while the app runs, and every server function an action calls, named with what it does that a vex read or write cannot. What the app allows, it names in that file, file by file, with why.
468
620
 
469
- **A package is made of modules.** A module is a directory under `src/` with an `index.ts`.
470
-
471
- 1. **One door.** Code outside a module imports `../<module>`, never a file inside it.
472
- 2. **Declared dependencies.** Which module may import which is one table, in `scripts/check-modules.mts`, and the table has no cycle. A new import between two modules is a line in that table, in the same change.
473
- 3. **One owner.** Each table and each piece of state that outlives a request belongs to one module. Nobody else writes it.
474
- 4. **Narrow inputs.** A factory takes a typed object of the functions and values it needs. Never the whole manifest, never the whole runtime, never an object that stands in for either.
475
- 5. **Parse where it enters.** A body, a socket message, a row, a fetched payload, a message from another process, a token: parsed by a schema in the module where it enters. No type assertion.
476
- 6. **Nothing flat.** Only `index.ts` sits at the top of `src/`.
477
- 7. **Limits.** A function of up to 200 lines is fine; 300 is the ceiling, for the rare one that reads better whole than cut up. A file is at most 400 lines of code, a line at most 200 wide. Do not split a function or a file to satisfy a number: split it when it has stopped being one thing. The other way round too: a file of a few lines joins the file that uses it, unless it is a published entry point.
478
- 8. **The code speaks.** A comment is there only where the reasoning, a decision or the workings would be misread without it (`/STYLE_GUIDE.md`, "Comments"). No file headers, and no prose on the fields of a type: what an app author needs to know of an exported type is in the package's `DOCS.md`.
479
-
480
- **How something new gets in.** In this order, and before any of it is written:
481
-
482
- 1. Name the question it answers. It goes in the module that owns that question (a package's `DESIGN.md` says which module owns what; moss's is "How the code is laid out").
483
- 2. If it answers none of them, it is a **feature**: a directory of its own, an entry point of its own, and it reaches the core only through a seam. The core never imports it, reads or writes no row of its tables, and holds no setting of its own for it. The tables that are a feature's it names on itself, and its seams reach those and no other.
484
- 3. If the seam it needs is not there, the seam is the first change, on its own, added to the module that owns the answer.
485
- 4. A new export is a decision, not a side effect of a file needing a name: it is a line in the package's `api.txt` in the same change, and it is documented under its entry point.
486
- 5. A statement outside vex is an entry in the ledger of `scripts/check-raw-sql.mts`, with its reason, or it does not exist. The reasons that hold are a credential read before anybody is signed in, an engine's own store, and a migration.
487
- 6. If it fits nowhere, the architecture is wrong. Say so, and propose the refactor before writing the feature. A refactor is considered every time; adding on top of what is there is how the one function got to 1,345 lines.
488
-
489
- A defect found on the way gets a test that fails first. A commit moves code or changes behaviour, never both.
490
-
491
- **The gates.** All four run in `pnpm verify` and in CI.
492
-
493
- | Run | It fails when |
494
- |---|---|
495
- | `pnpm check:modules` | a file other than `index.ts` sits at the top of `src/`; a module imports a file inside another module instead of its door; a module imports one the table does not give it; the table has a cycle; the core imports a feature |
496
- | `pnpm check:api` | an entry point exports a name that is not in the package's `api.txt`, or `api.txt` names one that is no longer exported; an entry writes `export *` |
497
- | `pnpm check:raw-sql` | a file outside the script's ledger holds a statement or a call on a database pool, or a file in the ledger holds more or fewer than its line says |
498
- | `pnpm lint` | in moss's `src/`, or tide's Postgres store or driver: a type assertion other than `as const`; an `any` that becomes a typed value; a written type predicate; a non-null `!`; a `function` declaration; a function over 300 lines, a file over 400 lines of code, a line over 200 wide; an inline directive that switches a rule off |
499
-
500
- The lint reads types, and a type from another package of the repository is read from its `dist`: `pnpm build` first, as `pnpm verify` and CI do.
501
-
502
- Rules 3, 4 and 8 have no gate. They are what a review reads for. What two processes do to each other is in no package's tests either: those run on PGlite, which has one connection.
503
-
504
- `check:raw-sql` sweeps every package but vex and strata, where SQL lives. `check:modules` and `check:api` hold moss. A package joins `check:modules` by being made of modules and getting an entry in `PACKAGES`; it joins `check:api` by an entry in `ENTRIES` and `pnpm check:api --write`.
621
+ **Reviewing** is `REVIEW.md`, beside this file: how to run a review, the checklist, what to look for, and how to report — by rule number. Run one after each step of the order of work. A change that makes the app less declarative, less validated, or less observable is wrong even if it works.