@xhulz/nina 0.84.0 → 0.85.0

package/releases/0.85.0/surfaces/pii/tree/CLAUDE.md

@@ -0,0 +1,5 @@
+<!-- nina:slot pii.1 -->
+8. **Sensitive personal data is classified, and the classification is enforced.** What counts as sensitive here — identity documents, financial identifiers, anything a person would not expect to be readable by whoever can read a log — is declared in `.claude/architecture.md` § *Privacy*, along with the regime that governs it ({{PRIVACY_REGIME}}). Encrypted at rest. **No sensitive value in a log, an error message, a URL, an analytics event, or an agent transcript** — the places nobody thinks about are exactly the ones that persist. That includes what a library puts in its own errors and prints itself: a database client's error can carry the query and every bound value, and a framework can log a whole error past the logger it was given. A database error is mapped at the data layer to a typed error from a closed list before anything logs or returns it, and a test proves that a bound value it writes reaches no thrown error. **A value absent from an error that never held it proves nothing:** each test that shows a mapper or a sanitizer keeps a value out drives a failure whose raw error carries it — the spec names that failure class and cites where it renders bound values, an error that prints the call or a violation that echoes the input, never one that names only its constraint — and asserts first that the raw, unmapped error of the same operation contains the value, a control kept in memory and never printed; the mutant that copies the raw error's `message`, `cause` or details across turns it red.<!-- nina:why --> In one project a spec proved its error mapper on a foreign-key failure, whose message and details name only the constraint, so no mapper that copied them could turn the test red.<!-- /nina:why --> **A test that proves a value stays out matches by containment** (`String(v).includes(value)`), never by equality: a leak arrives inside an id, a message or a key. It gives each log call in the source a run, counts the console's calls by method and asserts each method the path must not use at zero, and reads at least what the console prints of each entry and each error the runs produce, recursively: every own key, symbols and non-enumerable ones too (`Reflect.ownKeys`), and the entries of every `Map`, `Set`, `Headers` and `URLSearchParams`, unless the spec rules one out in writing. Its controls put their value where the real emitter puts its own, past a call's first argument and among several, and the spec names the window its spy covers and why nothing logs after it. Its forbidden values are the run's own that § *Privacy* keeps out — where it lists what may be logged, every other value the run carries — each with a control that embeds it in a longer string under an allowed key and must fail the check — the values one run adds as much as a shared list's, since a check that folds accents passes every control written in ASCII — and no fixture value inside another's.<!-- nina:why --> In one project an allowlist check that refused only equal values passed a mutant logging `${id}:${amount}`; the next read `Object.keys` and missed an amount on a non-enumerable property and an info log no row inspected; the one after left out a class and four log paths.<!-- /nina:why --> Where what it claims to keep out names a class — an attribute, an amount — it covers every member: a surface with open-ended slots is read whole, never through a list of them — every attribute of every element a rendered page carries, just as every property of an error is — and a sweep that read nothing fails; each forbidden value is looked for in every form the code can give it, formatted and raw; and each state that shows, hides or replaces a value is swept on its own, the one built to withhold it most of all. One mutant puts the value in a slot the check does not name — `data-x` on a page; on an object or an error, a non-enumerable key, a symbol key, a nested object, a `Map` entry, `cause`, the end of `message` or `stack` — and one per field puts that field's raw value in each such slot, on every error the code throws, not only one it builds: one left green is a slot or a form the check misses. The implementer runs them on its mirror, as one block it reuses, before `DIFF-READY`, whatever the step lists, and reports one left green as the row the spec lacks (Hard Rule #17), adding it only in a file the step authorizes.<!-- nina:why --> In one project a walk of own keys missed a `Map`, a symbol key and a nested object, and every control put its value in a call's first argument, where the runtime's loggers put theirs second; then three steps in two days went back from review for a slot no listed mutant tried — an error's `cause`, its `stack`, a hidden key.<!-- /nina:why --><!-- nina:why --> In one project a sweep of `data-testid`, `aria-label` and `title`, proven by mutants in those three, stayed green with the label in a `data-label`; the next swept every attribute for the formatted amounts and missed their raw centavos; the one after swept only the state that shows the figure, and the row built to show none carried it in a `title`.<!-- /nina:why --> Document bytes live only in the object store, referenced by key, never in the database in clear text.
+
+<!-- nina:slot pii.2 -->
+- **personal data**: where it is collected, stored, logged or sent

package/releases/0.85.0/surfaces/prisma/tree/.claude/agents/architect.md

@@ -0,0 +1,2 @@
+<!-- nina:slot prisma.1 -->
+| `prisma-client-api` | a new or changed Prisma query |

package/releases/0.85.0/surfaces/prisma/tree/.claude/agents/dba.md

@@ -0,0 +1,42 @@
+<!-- nina:slot prisma.1 -->
+| `prisma-cli` | **before ANY `prisma` CLI command** — `validate`, `format`, `migrate dev`, `migrate diff`, `migrate deploy`. Flags differ between versions, and one of them (`migrate diff --shadow-database-url` against a live database) destroys the database it points at |
+| `prisma-client-api` | auditing a new or changed query — filters, operators, `$transaction` semantics. Through a driver adapter, cite the adapter's installed source for what a transaction does: the skill describes the default engine, and an adapter can roll back less |
+
+<!-- nina:slot prisma.2 -->
+Neither skill covers a **caching or edge layer sitting on top of the client** — cache strategy,
+edge-client behaviour and the rule about never caching a read that authorizes a write belong to that
+layer's own integration doc, declared like any other integration. A skill does not replace it.
+
+<!-- nina:slot prisma.3 -->
+- **With Prisma, both offline.** Run `pnpm --filter {{DB_PKG_NAME}} exec prisma validate`; it must pass. Then run `prisma migrate diff` in its **offline, file-only form** and read the generated SQL, not just the Prisma delta. Its flags changed in Prisma 7, so read the installed major (`prisma --version`) before writing the command:
+
+   ```
+   # Prisma 6. Compare the PREVIOUS schema against the working one — pure file-to-file, no database.
+   git show HEAD:{{DB_PKG}}/prisma/schema.prisma > /tmp/schema-head.prisma
+   pnpm --filter {{DB_PKG_NAME}} exec prisma migrate diff \
+     --from-schema-datamodel /tmp/schema-head.prisma \
+     --to-schema-datamodel prisma/schema.prisma \
+     --script
+   ```
+
+   From Prisma 7 the two flags are `--from-schema` and `--to-schema`, and the schema engine starts from the
+   datasource in `prisma.config.ts` even for this diff: with none there, it prints nothing and exits 0. For
+   SQLite a placeholder the diff never opens is enough, a `file:` URL under a gitignored directory; for any
+   other provider, find out what the diff opens before you give it one. Never a real database's URL. A first schema has nothing at `HEAD`: diff it `--from-empty`. Compare the output against the
+   hand-written `migration.sql` to confirm the declarative parts match.
+
+   ⚠️ **Do NOT reach for `--from-migrations`.** It looks like the natural choice and it is a trap:
+   Prisma refuses it without a shadow database (`--shadow-database-url`, or from Prisma 7 a
+   `shadowDatabaseUrl` in `prisma.config.ts`), which pushes you toward supplying a database URL — the exact move that destroys databases (below). The file-to-file form above answers the
+   same question with no database involved.
+
+   ⛔ **NEVER point `--shadow-database-url`, `--from-url`, `--to-url`, `--from-schema-datasource` — or, from Prisma 7, a `shadowDatabaseUrl` or the config datasource behind `--from-config-datasource` — at a real database, most of all not the one `{{SECRETS_LOCAL}}` names.** Prisma **executes** the entire migration history against whatever database those flags name, which **DESTROYS ALL DATA** in it. A shadow database must be a disposable, empty database and nothing else. It does not announce itself: the command completes with a reassuring "empty migration" result and no error, having already destroyed everything in the database it was pointed at. If the offline form above cannot answer your question, **STOP and report that to the orchestrator** instead of reaching for a database URL.
+
+<!-- nina:slot prisma.4 -->
+- **Where reads are cached through Prisma Accelerate,** every `findUnique` / `findMany` on a hot read path names its `cacheStrategy` (`ttl` / `swr`), and one that feeds a correctness-critical write names none.
+
+<!-- nina:slot prisma.5 -->
+- **On an edge runtime,** new Prisma code paths use the edge client of the installed major: `@prisma/client/edge` up to Prisma 6; from 7, the client the `prisma-client` generator writes with the platform's `runtime` set, imported from where it is generated — `@prisma/client/edge` fails there with `MODULE_NOT_FOUND`.
+
+<!-- nina:slot prisma.6 -->
+- Run a Prisma command that writes to a real database — `prisma migrate dev`, `migrate deploy`, `migrate reset`, `migrate resolve`, `db push`, `db execute`, `$executeRaw*` — or **any `prisma migrate diff` variant carrying a database URL**, which silently wipes the database it points at.

package/releases/0.85.0/surfaces/prisma/tree/.claude/agents/devops.md

@@ -0,0 +1,11 @@
+<!-- nina:slot prisma.1 -->
+- **`prisma-cli`** — before `migrate deploy` or any other Prisma CLI command against a real database.
+
+<!-- nina:slot prisma.2 -->
+- **Prisma migrations go out with `prisma migrate deploy`**, and nothing else changes a shared database's schema.
+
+<!-- nina:slot prisma.3 -->
+- Run `prisma migrate diff --shadow-database-url <url>` against any live database. It **executes** the migration history against that database, destroying everything in it, and reports success. Use a disposable shadow database or don't run it.
+
+<!-- nina:slot prisma.4 -->
+- Run `prisma migrate reset` against a shared database, ever.

package/releases/0.85.0/surfaces/prisma/tree/.claude/agents/implementer.md

@@ -0,0 +1,2 @@
+<!-- nina:slot prisma.1 -->
+| `prisma-client-api` | a new or changed Prisma query |

package/releases/0.85.0/surfaces/prisma/tree/.claude/agents/integration-tester.md

@@ -0,0 +1,2 @@
+<!-- nina:slot prisma.1 -->
+| `prisma-cli` | a Prisma CLI command |

package/releases/0.85.0/surfaces/prisma/tree/.claude/agents/reviewer.md

@@ -0,0 +1,2 @@
+<!-- nina:slot prisma.1 -->
+| `prisma-client-api` | a new or changed Prisma query |

package/releases/0.85.0/surfaces/prisma/tree/.claude/patterns.md

@@ -0,0 +1,15 @@
+<!-- nina:slot prisma.1 -->
+- **Database table/column names** (Prisma `@map` / `@@map`): `snake_case` in SQL, `camelCase` in TS.
+
+<!-- nina:slot prisma.2 -->
+- Where Prisma reads are cached through Accelerate, `cacheStrategy` lives in `{{DB_PKG}}`: services do not add, strip, or override cache policies.
+
+<!-- nina:slot prisma.3 -->
+
+### Prisma
+
+- Schema lives in `{{DB_PKG}}/prisma/schema.prisma`. Nowhere else.
+- **Never write raw SQL** unless justified in a code comment with perf data.
+- N+1 is solved with `include` / `select`, chosen deliberately.
+- Where reads are cached through Accelerate, every `findUnique` / `findMany` on a hot path defines its `cacheStrategy`, and no direct connection string is embedded in code.
+- Tests run a real Prisma client against a real database; the client is never mocked.

package/releases/0.85.0/surfaces/prisma/tree/CLAUDE.md

@@ -0,0 +1,5 @@
+<!-- nina:slot prisma.1 -->
+| Run any `prisma` CLI command (the database gate, devops, and the integration gate where there is one) | `prisma-cli` | flags differ between versions; `migrate diff --shadow-database-url` against a live DB wiped dev/staging once |
+
+<!-- nina:slot prisma.2 -->
+| Write or audit a Prisma query (architect, implementer, the database gate, reviewer) | `prisma-client-api` | filters, operators, `$transaction` semantics. a caching or edge layer on top of the client is **NOT covered** — its cache strategy belongs to that layer's own integration doc |

package/src/dashboard.mjs

@@ -16,6 +16,7 @@ import { fileURLToPath } from 'node:url';
 import { readProfile } from './paths.mjs';
 import { projectRecords } from './store.mjs';
 import { officeRoutes } from './office.mjs';
+import { DEMO_OFFICE } from './demo.mjs';
 import { listenHere, openInBrowser, refuseElsewhere, untilStopped } from './serve.mjs';
 import { layerRootFor } from './commands/compose.mjs';
 import { taskList } from './commands/runs.mjs';
@@ -30,9 +31,6 @@ const PAGE = join(dirname(fileURLToPath(import.meta.url)), 'dashboard.html');
 /** The port it asks for first, one past the office's. Taken, any free one. */
 export const DASHBOARD_PORT = 6463;
 
-/** How the demo's office plays (`nina dashboard --demo`): its one session, over and over, for a screen left on. */
-export const DEMO_OFFICE = { replay: true, loop: true };
-
 /** How many tasks the tasks tab lists, newest first: a long project's history would otherwise fill the page. */
 const TASKS_SHOWN = 60;
 
@@ -103,19 +101,19 @@ export function dashboardTabs(target, ctx) {
 /**
  * Serves the dashboard: the page at `/`, each tab's data at `/api/<tab>`, and the office at `/office/`.
  *
- * @param {{target: string, ctx: {root: string}, port?: number, tell?: (line: string) => void, replay?: boolean, loop?: boolean, rest?: number}} options -
- *   `tell` is where a failure is said: the terminal by default. `replay`, `loop` and `rest` are the office's
- *   (`officeRoutes`): the demo's plays its one session over and over.
+ * @param {{target: string, ctx: {root: string}, port?: number, tell?: (line: string) => void, replay?: boolean, loop?: boolean, rest?: number, scale?: number}} options -
+ *   `tell` is where a failure is said: the terminal by default. `replay`, `loop`, `rest` and `scale` are the office's
+ *   (`officeRoutes`): the demo's plays its one session over and over (`DEMO_OFFICE`).
  * @returns {Promise<{url: string, close: () => Promise<void>}>}
  */
-export async function serveDashboard({ target, ctx, port = DASHBOARD_PORT, tell = console.error, replay = false, loop = false, rest }) {
+export async function serveDashboard({ target, ctx, port = DASHBOARD_PORT, tell = console.error, replay = false, loop = false, rest, scale }) {
   const tabs = dashboardTabs(target, ctx);
   const room = JSON.stringify({ project: basename(target) }).replace(/</g, '\\u003c');
   const page = readFileSync(PAGE, 'utf8').replace('/*NINA_DASHBOARD*/null', () => room);
   // The office polls its ledger while anyone watches it: made when its tab is first opened, not before.
   let office = null;
   const officeFor = () => {
-    if (!office) office = officeRoutes({ target, replay, loop, ...(rest === undefined ? {} : { rest }) });
+    if (!office) office = officeRoutes({ target, replay, loop, scale, ...(rest === undefined ? {} : { rest }) });
     return office;
   };
   // What failed is said in the terminal that runs the dashboard, and never in the response: an error's message carries

package/src/demo.mjs

@@ -32,6 +32,19 @@ const BESIDE_REVIEW = ['dba'];
 /** A minute. */
 const MIN = 60_000;
 
+/**
+ * How many times faster than it happened the demo's office plays today's session. Squeezed as a replay of a real
+ * session is, each agent sat at its desk for three seconds at most, up again before anyone watching had seen it work;
+ * at this pace each of today's runs, lasting seven to thirteen minutes, sits there for 20 to 40.
+ */
+export const DEMO_PACE = 20;
+
+/** How long each of today's runs stays at its desk in the demo's office, in ms: at least, and at most. */
+export const DEMO_AT_DESK = [20_000, 40_000];
+
+/** How the demo's office plays (`nina dashboard --demo`): its one session, over and over, at `DEMO_PACE`. */
+export const DEMO_OFFICE = { replay: true, loop: true, scale: 1 / DEMO_PACE };
+
 /** A day. */
 const DAY = 86_400_000;
 
@@ -185,10 +198,11 @@ function seeded(seed) {
  *
  * @returns {{runs: object[], end: number}}
  */
-function taskRuns(random, start, { name, noun, design, sendBack = null, between = 0.2 }) {
+function taskRuns(random, start, { name, noun, design, sendBack = null, between = 0.2, works = null }) {
   const runs = [];
   const slug = noun.toLowerCase().replace(/\s+/g, '-');
   const span = (role) => {
+    if (works) return works();
     const [lo, hi] = WORKS[role];
     return Math.round((lo + random() * (hi - lo)) * MIN);
   };
@@ -260,11 +274,14 @@ export function demoSessions(now) {
     }
     sessions.push({ id: sessionId(random), prompt: 'Next feature, please.', at: morning.getTime() - MIN, runs });
   }
-  // Today's: the archive, sent back once, and the list's dates, begun while the archive's tests run. Laid out from zero,
-  // then moved so its last report came in three minutes ago: nothing in it happens after `now`.
-  const archive = taskRuns(seeded(7), MIN, { name: 'Add archiving to notes', noun: 'archive', design: true, sendBack: 'reviewer' });
+  // Today's: the archive, sent back once, and the list's dates, begun while the archive's tests run. Each run lasts what
+  // sits it at its desk for 20 to 40 seconds of the office's replay. Laid out from zero, then moved so its last report
+  // came in three minutes ago: nothing in it happens after `now`.
+  const desk = seeded(13);
+  const works = () => Math.round((DEMO_AT_DESK[0] + desk() * (DEMO_AT_DESK[1] - DEMO_AT_DESK[0])) * DEMO_PACE);
+  const archive = taskRuns(seeded(7), MIN, { name: 'Add archiving to notes', noun: 'archive', design: true, sendBack: 'reviewer', works });
   const qa = archive.runs.at(-1);
-  const dates = taskRuns(seeded(11), qa.start + 1.5 * MIN, { name: 'Fix the dates on the notes list', noun: 'list dates', design: false });
+  const dates = taskRuns(seeded(11), qa.start + 1.5 * MIN, { name: 'Fix the dates on the notes list', noun: 'list dates', design: false, works });
   const runs = [...archive.runs, ...dates.runs].sort((a, b) => a.start - b.start);
   const shift = now - 3 * MIN - Math.max(...runs.map((r) => r.end));
   for (const r of runs) Object.assign(r, { start: r.start + shift, end: r.end + shift });

package/src/office.mjs

@@ -305,6 +305,28 @@ const REPLAY_MIN_GAP_MS = 500;
 /** How long a replay in a loop rests on its last beat before it plays again from the start: the party is seen out. */
 export const LOOP_REST_MS = 8000;
 
+/** The longest a replay at a scale waits between two beats: a lunch break in the session is not a minute of an empty room. */
+const REPLAY_SCALED_MAX_GAP_MS = 45_000;
+
+/**
+ * How long a replay waits after each beat before the next. Each real gap is squeezed to `REPLAY_MIN_GAP_MS` to
+ * `REPLAY_MAX_GAP_MS`, so hours of a session play in minutes; at a `scale` it is the real gap times the scale instead,
+ * so a run stays at its desk in proportion to how long it worked — the demo's, which an audience watches, sit 20 to 40
+ * seconds where a squeezed replay had them up again in three. The owner speaking passes quickly either way: it moves
+ * nobody across the room, and an answer keeps its wait, or the question it answers would not be seen.
+ *
+ * @param {object[]} beats - The beats in the order they are played.
+ * @param {{scale?: number}} [options] - Replay time per real time.
+ * @returns {number[]} The wait after each beat, in ms.
+ */
+export function replayDelays(beats, { scale } = {}) {
+  return beats.map((beat, k) => {
+    const following = beats[k + 1];
+    const gap = following && following.type !== 'owner' ? following.at - beat.at : 0;
+    return scale ? Math.min(REPLAY_SCALED_MAX_GAP_MS, Math.max(REPLAY_MIN_GAP_MS, gap * scale)) : Math.min(REPLAY_MAX_GAP_MS, Math.max(REPLAY_MIN_GAP_MS, gap));
+  });
+}
+
 /**
  * Each run the ledger saw start, in order: when, at which stage, by which agent once known, whether it was a message
  * to a running agent, when it was refused, and when its verdict ended it. The beats and the timeline read the same.
@@ -629,11 +651,12 @@ const send = (res, event, data) => res.write(`event: ${event}\ndata: ${JSON.stri
  * anyone watches live. `serveOffice` mounts them at the root; the dashboard (`nina dashboard`) at `/office/`, where the
  * page's relative `events` reaches `/office/events`.
  *
- * @param {{target: string, wanted?: string, replay?: boolean, loop?: boolean, rest?: number}} options - `loop`: a replay
- *   that ends plays again from the start, for an office left on a screen, after resting `rest` ms on its last beat.
+ * @param {{target: string, wanted?: string, replay?: boolean, loop?: boolean, rest?: number, scale?: number}} options - `loop`: a
+ *   replay that ends plays again from the start, for an office left on a screen, after resting `rest` ms on its last
+ *   beat. `scale`: a replay that keeps the session's proportions at that much replay time per real time (`replayDelays`).
  * @returns {{handle: (req: import('node:http').IncomingMessage, res: import('node:http').ServerResponse, path: string) => boolean, close: () => void}}
  */
-export function officeRoutes({ target, wanted, replay = false, loop = false, rest = LOOP_REST_MS }) {
+export function officeRoutes({ target, wanted, replay = false, loop = false, rest = LOOP_REST_MS, scale }) {
   const room = officeRoom(target);
   const graph = parseGraph(readFileSync(join(target, '.claude', 'graph.md'), 'utf8'));
   // A function, so a `$&` or `$'` in a project's name or its owner's is text and not a replacement pattern.
@@ -718,6 +741,7 @@ export function officeRoutes({ target, wanted, replay = false, loop = false, res
     greet(client, state);
     const heard = clock(state.session);
     const beats = officeBeats(state.entries, graph, Number.POSITIVE_INFINITY, heard);
+    const delays = replayDelays(beats, { scale });
     // The timeline as it stood at each beat: cut from the ledger up to that moment, so a replay tells nothing early.
     const known = names(state.entries);
     const look = looks(state.session);
@@ -745,16 +769,12 @@ export function officeRoutes({ target, wanted, replay = false, loop = false, res
       const beat = beats[i];
       send(client.res, 'beat', beat);
       tell(client, tasksAt(beat.at));
-      i += 1;
-      // The owner speaking moves nobody across the room: it passes quickly. An answer keeps its wait, or the question
-      // it answers would not be seen.
-      const quick = i < beats.length && beats[i].type === 'owner';
-      const gap = i < beats.length && !quick ? beats[i].at - beat.at : 0;
       const timer = setTimeout(() => {
         timers.delete(timer);
         next();
-      }, Math.min(REPLAY_MAX_GAP_MS, Math.max(REPLAY_MIN_GAP_MS, gap)));
+      }, delays[i]);
       timers.add(timer);
+      i += 1;
     };
     next();
   };