@niscorp/nisc 0.9.0 → 0.9.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +11 -21
- package/CHANGELOG.md +46 -0
- package/README.md +3 -2
- package/REVIEW.md +81 -0
- package/package.json +12 -12
package/AGENTS.md
CHANGED
|
@@ -4,6 +4,8 @@
|
|
|
4
4
|
|
|
5
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.
|
|
6
6
|
|
|
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
|
+
|
|
7
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.
|
|
8
10
|
|
|
9
11
|
## The thesis
|
|
@@ -98,7 +100,7 @@ Pick per need; every piece works standalone. Nova is the only mandatory one for
|
|
|
98
100
|
**Principals**
|
|
99
101
|
|
|
100
102
|
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"`).
|
|
101
|
-
10a. The `data` universe is the INTROSPECTED database, not your schema file: it
|
|
103
|
+
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.
|
|
102
104
|
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.
|
|
103
105
|
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.
|
|
104
106
|
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.
|
|
@@ -117,7 +119,7 @@ Pick per need; every piece works standalone. Nova is the only mandatory one for
|
|
|
117
119
|
**Versions** (`@niscorp/strata`; the why is `packages/strata/DESIGN.md`)
|
|
118
120
|
|
|
119
121
|
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.
|
|
120
|
-
18. A grammar change is a migration. Changing a schema behind a document kind — nova's actions and layouts, Prism's config, 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.
|
|
122
|
+
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.
|
|
121
123
|
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.
|
|
122
124
|
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.
|
|
123
125
|
|
|
@@ -172,7 +174,7 @@ export const todosInputSchema = z.toJSONSchema(
|
|
|
172
174
|
);
|
|
173
175
|
```
|
|
174
176
|
|
|
175
|
-
**`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
|
|
177
|
+
**`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.
|
|
176
178
|
|
|
177
179
|
```ts
|
|
178
180
|
import type { LayoutNode } from '@niscorp/nova';
|
|
@@ -432,7 +434,7 @@ What changes is only who assembles and serves:
|
|
|
432
434
|
|
|
433
435
|
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.
|
|
434
436
|
|
|
435
|
-
`fable` and `mythos` predate the `app/`-is-artifacts-only tree above and are arranged differently (`nova/`, `api/`, `vex/`, `boot.ts`) — read them for the boot and engine wiring, not for the layout.
|
|
437
|
+
`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.
|
|
436
438
|
|
|
437
439
|
## Order of work
|
|
438
440
|
|
|
@@ -444,29 +446,17 @@ Say this out loud in the interview, because it is the part a user cannot infer:
|
|
|
444
446
|
6. **Writes** — per D4, with change channels; prove one round-trip: create → announce → re-read.
|
|
445
447
|
7. **Checks and polish** — a dev check per feature; empty states, skeletons, transitions last.
|
|
446
448
|
|
|
449
|
+
Each step ends with its checks green and a review (`REVIEW.md`).
|
|
450
|
+
|
|
447
451
|
## Verification
|
|
448
452
|
|
|
449
453
|
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.
|
|
450
454
|
|
|
451
455
|
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.
|
|
452
456
|
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
2. No renderer code (JSX, a tty kit) outside `ui/` and the entry point. `server/document.ts` hands the kit's registry to moss to draw a page with; it imports the kit and contains no renderer code of its own. No `fetch` outside the endpoint layer, except to send a file (rule 9a). No formatting (`Intl`, `toLocaleString`, date libs) outside Prism transforms.
|
|
457
|
-
3. Every action an opener loads with input declares it in the definition's `input`, and the declared fields are a subset of the action's `data` keys.
|
|
458
|
-
4. Every displayer of an entity stays current after a write: its read is `refresh: 'reactive'`, or the write's success path emits a change channel the displayer listens to.
|
|
459
|
-
5. No component name contains a domain noun; no component imports shell, action, or data code.
|
|
460
|
-
6. No layout or component branches on roles or capability data (rule 11) — per-principal difference is existence or a served variant.
|
|
461
|
-
6a. Every artifact the manifest carries is pure JSON and parses its schema — a function, a `Date`, an `undefined`, or a class instance in an artifact is a code file masquerading as data. The manifest's declared code fields (`scope`, `identity`, `phrases`, `functions`, `onSession`, `runs`, `reconcilers`, a reaction's `run`, `features`, and the shell's `inputs` and `seeds` hooks) are the only exceptions; they live outside the artifact tree and are validated by running, not by this check. Moss reads the manifest by a schema when it is handed to `createServer` and refuses to boot on one that does not parse, a code field that is not a function included; this check finds it before a boot does.
|
|
462
|
-
6b. Session code sits in the seam that describes it (rule 7a): no handler registered on `functions` that nothing calls. Tenancy resolves through `scope` and engine-side behaviors, never from a request field.
|
|
463
|
-
6c. No role holding a data wildcard reaches the engine's tables, and the charter check resolves against the universe boot does (rule 10a).
|
|
464
|
-
6d. Where pages are drawn on the server: a check opens the drawn page with the real wire and target and the terminal adopts it with nothing said (rule 2a), at every window width the kit distinguishes; a page drawn for somebody goes out `private, no-store`; and every sign-in the app answers over HTTP sets the session cookie on its response and hands the page nothing (rule 12).
|
|
465
|
-
7. Style guide bans (rule 16): `any`, `enum`, classes, default exports, `function` declarations by grep; type assertions and non-null `!` at the lint/typecheck level — grep can't tell negation from assertion. Declared shim exceptions are honored.
|
|
466
|
-
8. Decision points: each of D1–D5 is recorded in the app's `PLAN.md` with its tier — answered, delegated by name, or derived — never assumed silently.
|
|
467
|
-
9. Versions (rules 17–20): `pnpm check:grammars` and `pnpm check:sources` pass; no DDL outside a sequence; no edited migration, snapshot, early-stamp corpus file or hand-moved lock.
|
|
468
|
-
|
|
469
|
-
Report violations by rule number. A change that makes the app less declarative, less validated, or less observable is wrong even if it works.
|
|
457
|
+
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.
|
|
458
|
+
|
|
459
|
+
**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.
|
|
470
460
|
|
|
471
461
|
## Changing a package
|
|
472
462
|
|
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,51 @@
|
|
|
1
1
|
# @niscorp/nisc
|
|
2
2
|
|
|
3
|
+
## 0.9.2
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- efd576c: The rulebook catches up: `REVIEW.md`'s versions item names the check an app runs (`strata status --check`), not this repository's scripts; `AGENTS.md` lists moss's `artifacts` and `artifact_saves` among the engine's tables and vex's entries among the document kinds, and no longer speaks of exemplars; the README lists `REVIEW.md`.
|
|
8
|
+
|
|
9
|
+
**What to change:** nothing. Documentation only.
|
|
10
|
+
|
|
11
|
+
- Updated dependencies [febd8b7]
|
|
12
|
+
- Updated dependencies [41ac0c7]
|
|
13
|
+
- Updated dependencies [efd5d03]
|
|
14
|
+
- Updated dependencies [501e355]
|
|
15
|
+
- Updated dependencies [e4dfb25]
|
|
16
|
+
- Updated dependencies [4e76fe8]
|
|
17
|
+
- Updated dependencies [a2d2df0]
|
|
18
|
+
- Updated dependencies [2a44642]
|
|
19
|
+
- Updated dependencies [2fc1bf0]
|
|
20
|
+
- Updated dependencies [d70f22c]
|
|
21
|
+
- @niscorp/charter@0.1.5
|
|
22
|
+
- @niscorp/cortex@0.1.6
|
|
23
|
+
- @niscorp/moss@0.9.1
|
|
24
|
+
- @niscorp/nova@0.5.2
|
|
25
|
+
- @niscorp/prism@0.3.3
|
|
26
|
+
- @niscorp/signal@0.1.9
|
|
27
|
+
- @niscorp/solid@0.1.3
|
|
28
|
+
- @niscorp/strata@0.1.9
|
|
29
|
+
- @niscorp/tide@0.1.10
|
|
30
|
+
- @niscorp/vex@0.4.4
|
|
31
|
+
|
|
32
|
+
## 0.9.1
|
|
33
|
+
|
|
34
|
+
### Patch Changes
|
|
35
|
+
|
|
36
|
+
- a7b2a05: A shape check, `runShapeCheck` from the new entry `@niscorp/cli/shape`: it reads an app's source and its actions for what its own checks cannot see — rule 16 by the TypeScript compiler, formatting outside Prism, roles read in server code, the kit reading files, the address or the document, code in `src/app` called while the app runs — and fails on every server function an action calls that the app has not named with why it is not a vex read or write. What an app allows, it names per rule and per file, each with its reason. It reads with the app's own TypeScript (6.x) and adds no dependency.
|
|
37
|
+
|
|
38
|
+
`create-nisc` writes it into every app as `src/dev/shape-check.ts`, run by `npm run check`. The rulebook's "Verification" and `REVIEW.md` say what it does.
|
|
39
|
+
|
|
40
|
+
**What to change:** nothing; an app that does not call it is not checked. To check an app made before this, copy `src/dev/shape-check.ts` from a new one, add it to `src/dev/all-checks.ts`, and name what it reports.
|
|
41
|
+
|
|
42
|
+
- f826860: `REVIEW.md`, beside `AGENTS.md`: a guide for an agent reviewing a nisc app, written to be run on its own — how to run a review, the counts that say where an app has drifted, the checklist, what to look for, and how to report by rule number. The checklist is the one `AGENTS.md`'s "Verification" carried; "Verification" now points to it. `AGENTS.md` says near its top to build with it and review with `REVIEW.md`, after each step of the order of work, not only at the end.
|
|
43
|
+
|
|
44
|
+
**What to change:** nothing. To review an app, point the reviewing agent at `node_modules/@niscorp/nisc/REVIEW.md`.
|
|
45
|
+
|
|
46
|
+
- Updated dependencies [a7b2a05]
|
|
47
|
+
- @niscorp/cli@0.9.1
|
|
48
|
+
|
|
3
49
|
## 0.9.0
|
|
4
50
|
|
|
5
51
|
### Minor Changes
|
package/README.md
CHANGED
|
@@ -24,8 +24,9 @@ refuses a plan that is missing either the approval or this.
|
|
|
24
24
|
## The rulebook
|
|
25
25
|
|
|
26
26
|
It also carries the rules a nisc application is built by, for the versions it
|
|
27
|
-
pins: [`AGENTS.md`](AGENTS.md)
|
|
28
|
-
work,
|
|
27
|
+
pins: [`AGENTS.md`](AGENTS.md) (the decision points, the rules, the order of
|
|
28
|
+
work), [`REVIEW.md`](REVIEW.md) (what a review checks) and
|
|
29
|
+
[`STYLE_GUIDE.md`](STYLE_GUIDE.md). They are
|
|
29
30
|
written for the coding agent building the app as much as for a person. An app
|
|
30
31
|
made by `npm create nisc` has a short `AGENTS.md` of its own that points here,
|
|
31
32
|
so the rules it follows are always the ones for what it has installed.
|
package/REVIEW.md
ADDED
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
# Reviewing a nisc application
|
|
2
|
+
|
|
3
|
+
For an agent asked to review an app built on nisc. It is made to be run on its own: read this, the app's `PLAN.md` and its own `AGENTS.md`, and the app. Open the rulebook (`AGENTS.md`, beside this file) and a package's docs only where a finding needs a rule's exact words. Rule numbers here are the rulebook's.
|
|
4
|
+
|
|
5
|
+
A review answers one question: **does the app do what it does as data, or did code grow where data belongs?** An app can pass every one of its own checks and still fail that: its checks test what it does, not how it does it. Every finding under "What to look for" was found in an app whose checks were all green.
|
|
6
|
+
|
|
7
|
+
**Review early and often.** Run a review after each step of the order of work (the rulebook's "Order of work"), not only at the end: a drift found after the data layer is one read moved; found after the actions, it is every screen built on it. An app made by `npm create nisc` ships the reviewer as a Claude Code agent, `.claude/agents/nisc-reviewer.md`.
|
|
8
|
+
|
|
9
|
+
## How to run it
|
|
10
|
+
|
|
11
|
+
1. **The gates.** The app's typecheck and its check suite (`npm run typecheck`, `npm run check`), which runs its shape check (`src/dev/shape-check.ts`) beside its own checks. An app without one is a finding: copy it from a new app (`npm create nisc`). Read what its `functions` and `allow` say, too: an allowance with a weak reason is a finding the gate cannot see. A red gate is the first finding; a boot refusal is a finding, not an environment problem. Then take the counts in "Measure first": they say where to read.
|
|
12
|
+
2. **Read in this order:** the charter, the entries, three actions of different kinds (a list, a form, a screen only some roles hold), the server's functions, the kit. The order follows where a fault costs most.
|
|
13
|
+
3. **Go through the checklist,** then **what to look for**.
|
|
14
|
+
4. **Verify before you report.** A finding is a hypothesis until the code shows it: open the file and quote the line.
|
|
15
|
+
5. **Never adjust a check to make a finding go away.** A check that has to change is rewritten to protect what it protected (the rulebook's failure mode 4).
|
|
16
|
+
|
|
17
|
+
## Measure first
|
|
18
|
+
|
|
19
|
+
These numbers are not rules. They say where a design has drifted. In the lab apps vex replays outnumber function calls: lyceum 55 to 37, lyra 149 to 24, atrium 103 to 11. The shape check prints the first two.
|
|
20
|
+
|
|
21
|
+
| Count | How | Drift when |
|
|
22
|
+
|---|---|---|
|
|
23
|
+
| `fn:` endpoints against vex replays | `grep -rhoE "\bfn: *'" src/app` and `grep -rhoE "url: *'/api/[a-z/]*vex'" src/app` | functions outnumber replays |
|
|
24
|
+
| entries with a `mapping` | `grep -rn "mapping:" src/app/vex` | none, while the server formats |
|
|
25
|
+
| formatting outside Prism | `grep -rn "Intl\.\|toLocale" src/server src/app src/ui` | any |
|
|
26
|
+
| `executeAs` inside `functions(session)` | read each: is the role it names wider than the person's? | a person's read served by a machine role |
|
|
27
|
+
| roles read in code | `grep -rn "session.roles\|principal.roles" src/server` | any outside where a principal is resolved |
|
|
28
|
+
| the address and the DOM in the kit | `grep -rn "location\.\|history\.\|querySelector" src/ui` | any outside a declared routing adapter |
|
|
29
|
+
| files read into data | `grep -rn "FileReader\|readAsDataURL" src/ui` | any |
|
|
30
|
+
|
|
31
|
+
## The checklist
|
|
32
|
+
|
|
33
|
+
1. Typecheck passes; every dev check passes; the manifest boots — moss refuses an incoherent charter.
|
|
34
|
+
2. No renderer code (JSX, a tty kit) outside `ui/` and the entry point. `server/document.ts` hands the kit's registry to moss to draw a page with; it imports the kit and contains no renderer code of its own. No `fetch` outside the endpoint layer, except to send a file (rule 9a). No formatting (`Intl`, `toLocaleString`, date libs) outside Prism transforms.
|
|
35
|
+
3. Every action an opener loads with input declares it in the definition's `input`, and the declared fields are a subset of the action's `data` keys (rule 14).
|
|
36
|
+
4. Every displayer of an entity stays current after a write: its read is `refresh: 'reactive'`, or the write's success path emits a change channel the displayer listens to.
|
|
37
|
+
5. No component name contains a domain noun; no component imports shell, action, or data code (rule 2).
|
|
38
|
+
6. No layout or component branches on roles or capability data (rule 11) — per-principal difference is existence or a served variant.
|
|
39
|
+
- **a.** Every artifact the manifest carries is pure JSON and parses its schema — a function, a `Date`, an `undefined`, or a class instance in an artifact is a code file masquerading as data. The manifest's declared code fields (`scope`, `identity`, `phrases`, `functions`, `onSession`, `runs`, `reconcilers`, a reaction's `run`, `features`, and the shell's `inputs` and `seeds` hooks) are the only exceptions; they live outside the artifact tree and are validated by running, not by this check. Moss reads the manifest by a schema when it is handed to `createServer` and refuses to boot on one that does not parse, a code field that is not a function included; this check finds it before a boot does.
|
|
40
|
+
- **b.** Session code sits in the seam that describes it (rule 7a): no handler registered on `functions` that nothing calls. Tenancy resolves through `scope` and engine-side behaviors, never from a request field.
|
|
41
|
+
- **c.** No role holding a data wildcard reaches the engine's tables, and the charter check resolves against the universe boot does (rule 10a).
|
|
42
|
+
- **d.** Where pages are drawn on the server: a check opens the drawn page with the real wire and target and the terminal adopts it with nothing said (rule 2a), at every window width the kit distinguishes; a page drawn for somebody goes out `private, no-store`; and every sign-in the app answers over HTTP sets the session cookie on its response and hands the page nothing (rule 12).
|
|
43
|
+
7. Style guide bans (rule 16): `any`, `enum`, classes, default exports, `function` declarations, type assertions and non-null `!` — read by the compiler, not by grep, which cannot tell negation from assertion. Declared shim exceptions are honored.
|
|
44
|
+
8. Decision points: each of D1–D5 is recorded in the app's `PLAN.md` with its tier — answered, delegated by name, or derived — never assumed silently.
|
|
45
|
+
9. Versions (rules 17–20): the check suite's `strata status --check` passes (the source is written at the installed grammars, `strata.lock.json`); no DDL outside a sequence; no edited migration, snapshot, early-stamp corpus file or hand-moved lock.
|
|
46
|
+
|
|
47
|
+
## What to look for
|
|
48
|
+
|
|
49
|
+
**The data path (the thesis; rules 5, 7, 9, 10).** A read is a vex entry replayed by the action that shows it, under the person's own policy. A function is the escape hatch: mail, signing, files, push, a model, parsing an upload, what lives in the person's shell rather than in rows, a write that may touch only some columns, a refusal no row rule or mutation `where` can say. For each function an action calls, ask what it does that an entry cannot. A function that replays entries and reshapes their rows is a read in disguise, and it costs three things at once:
|
|
50
|
+
|
|
51
|
+
- **policy:** it runs as whatever role it names, so the charter's grants and reach for the person gate nothing. Find each machine role a person's function uses, and what it reaches that the person should not (*a teacher reading every class's attendance through a function that runs as the doorkeeper*);
|
|
52
|
+
- **freshness:** a `refresh: 'reactive'` entry behind a function answers once; nothing follows it;
|
|
53
|
+
- **formatting:** its words are built in TypeScript, where Prism cannot check them.
|
|
54
|
+
|
|
55
|
+
**Formatting (rule 9).** Dates, times, counts, money and sentences built from data are Prism, in an entry's `mapping` or an endpoint's `response`. The app's "today" is in the reads' scope (the `scope` seam), never a wall-clock read.
|
|
56
|
+
|
|
57
|
+
**Per-principal UI (rule 11).** A flag a function computes from the person's roles (`canChange`, `isStaff`) that a layout branches on is a conditional. It is existence (an action only some hold) or a served variant.
|
|
58
|
+
|
|
59
|
+
**`src/app` is data (checklist 6a).** Every export there is a value that serializes. A function exported from `src/app` that runs while the app runs — a layout builder called per request, a helper the server imports — is code in the artifact tree, even if everything the manifest carries passes the purity check. A builder run once as its module loads is allowed but is not row-ready: note it, as minor.
|
|
60
|
+
|
|
61
|
+
**The kit (rules 1, 2, 2a, 4, 9a).** Components are domain-blind and configured: no domain word in a component's name or in the names of its tones and sizes; no app logic deciding what happens next; no reading another component's elements; no module-level state carrying coordination between components; no file sent over the socket; no address read to choose what an action shows.
|
|
62
|
+
|
|
63
|
+
**Writes (rule 8, D4).** Identity is the session's. An id from the request names a subject only where the caller's role may act on others; check that the function checks it, or that the entry's reach does.
|
|
64
|
+
|
|
65
|
+
**HTTP routes (rules 9a, 12).** List every route the app mounts. Legitimate: sign-in redemption, pairing, sending and serving files. A GET that writes, a route that answers to the session cookie for anything but a file, or data that should go over the socket is a finding.
|
|
66
|
+
|
|
67
|
+
**Boundaries (rule 13).** What enters from outside is parsed, `.strict()` where it is external input. A `looseObject` on a function's input is acceptable when the function is handed a whole card's data; on a form or a route it is not.
|
|
68
|
+
|
|
69
|
+
**Versions and startup (rules 17, 20).** DDL only in a strata sequence, appended; rows an app needs to start are a migration step, not a boot-time write; timers doing scheduled work belong in tide.
|
|
70
|
+
|
|
71
|
+
**The app's own documents.** `AGENTS.md` and `PLAN.md` say how the app works. Read one of their claims against the code for every part you review. A document that describes a design the code has left is a finding — the next agent builds on it — and so is code kept alive only by the checks.
|
|
72
|
+
|
|
73
|
+
## Report
|
|
74
|
+
|
|
75
|
+
```
|
|
76
|
+
Verdict: one paragraph — how far the app is from what nisc intends, and the one change that moves it most.
|
|
77
|
+
Strong: … Medium: … Minor: … Done right: …
|
|
78
|
+
Each: [rule] file:line — evidence — cost.
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Rank by cost: **strong** is the thesis or a security boundary (who sees what they should not), **medium** a rule broken locally (what goes stale, what cannot be checked), **minor** style. Say briefly what is done right. A change that makes the app less declarative, less validated, or less observable is wrong even if it works.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@niscorp/nisc",
|
|
3
|
-
"version": "0.9.
|
|
3
|
+
"version": "0.9.2",
|
|
4
4
|
"description": "The nisc platform as one known-compatible set: every @niscorp package, each pinned to the exact version it was released with.",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"repository": {
|
|
@@ -19,18 +19,18 @@
|
|
|
19
19
|
"node": ">=22.12"
|
|
20
20
|
},
|
|
21
21
|
"dependencies": {
|
|
22
|
-
"@niscorp/charter": "0.1.
|
|
23
|
-
"@niscorp/cli": "0.9.
|
|
24
|
-
"@niscorp/cortex": "0.1.
|
|
22
|
+
"@niscorp/charter": "0.1.5",
|
|
23
|
+
"@niscorp/cli": "0.9.1",
|
|
24
|
+
"@niscorp/cortex": "0.1.6",
|
|
25
25
|
"@niscorp/loom": "0.5.0",
|
|
26
|
-
"@niscorp/moss": "0.9.
|
|
27
|
-
"@niscorp/
|
|
28
|
-
"@niscorp/
|
|
29
|
-
"@niscorp/
|
|
30
|
-
"@niscorp/solid": "0.1.
|
|
31
|
-
"@niscorp/tide": "0.1.
|
|
32
|
-
"@niscorp/vex": "0.4.
|
|
33
|
-
"@niscorp/
|
|
26
|
+
"@niscorp/moss": "0.9.1",
|
|
27
|
+
"@niscorp/prism": "0.3.3",
|
|
28
|
+
"@niscorp/signal": "0.1.9",
|
|
29
|
+
"@niscorp/strata": "0.1.9",
|
|
30
|
+
"@niscorp/solid": "0.1.3",
|
|
31
|
+
"@niscorp/tide": "0.1.10",
|
|
32
|
+
"@niscorp/vex": "0.4.4",
|
|
33
|
+
"@niscorp/nova": "0.5.2"
|
|
34
34
|
},
|
|
35
35
|
"peerDependencies": {
|
|
36
36
|
"zod": "^4.2.0"
|