@niscorp/nisc 0.9.0 → 0.9.1

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
@@ -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
@@ -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
- A review pass checks, in order:
454
-
455
- 1. Typecheck passes; every dev check passes; the manifest boots — moss refuses an incoherent charter, and a boot refusal is a finding, not an environment problem.
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,22 @@
1
1
  # @niscorp/nisc
2
2
 
3
+ ## 0.9.1
4
+
5
+ ### Patch Changes
6
+
7
+ - 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.
8
+
9
+ `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.
10
+
11
+ **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.
12
+
13
+ - 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.
14
+
15
+ **What to change:** nothing. To review an app, point the reviewing agent at `node_modules/@niscorp/nisc/REVIEW.md`.
16
+
17
+ - Updated dependencies [a7b2a05]
18
+ - @niscorp/cli@0.9.1
19
+
3
20
  ## 0.9.0
4
21
 
5
22
  ### Minor Changes
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): `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.
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.0",
3
+ "version": "0.9.1",
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": {
@@ -20,17 +20,17 @@
20
20
  },
21
21
  "dependencies": {
22
22
  "@niscorp/charter": "0.1.4",
23
- "@niscorp/cli": "0.9.0",
24
23
  "@niscorp/cortex": "0.1.5",
24
+ "@niscorp/cli": "0.9.1",
25
25
  "@niscorp/loom": "0.5.0",
26
26
  "@niscorp/moss": "0.9.0",
27
27
  "@niscorp/nova": "0.5.1",
28
28
  "@niscorp/prism": "0.3.2",
29
29
  "@niscorp/signal": "0.1.8",
30
30
  "@niscorp/solid": "0.1.2",
31
+ "@niscorp/strata": "0.1.8",
31
32
  "@niscorp/tide": "0.1.9",
32
- "@niscorp/vex": "0.4.3",
33
- "@niscorp/strata": "0.1.8"
33
+ "@niscorp/vex": "0.4.3"
34
34
  },
35
35
  "peerDependencies": {
36
36
  "zod": "^4.2.0"