@nurix/etna 0.19.55 → 0.19.57

package/data/harnesses/apollo/rules/database.md

@@ -1,91 +1,13 @@
 # Database
 
-Fixed conventions for relational schemas in **every** Nurix project — what earns a table, where a fact lives once it does, the key vocabulary, foreign-key doctrine, naming, and column types. A cross-project consistency rule: **one concept, one name, everywhere**. General code naming (variables, files, casing) is [`nomenclature.md`](nomenclature.md); this rule owns the database.
-
-Written for SQLite / Cloudflare D1 + Drizzle (the concrete types below). The names and key vocabulary are engine-agnostic — a Postgres project keeps the same column names and semantics with native types (`uuid`, `timestamptz`, `boolean`).
-
-## What earns a table
-
-A table is the most expensive home for data — a migration to change its shape, a join to read, a mirror to keep in sync. Default to **not** a table — a concept earns one only with at least one property in the left column.
-
-| A table is earned by…                                                      | Lacking all of these, the data belongs in…              |
-| -------------------------------------------------------------------------- | ------------------------------------------------------- |
-| identity minted at **runtime** — a session, an upload                      | —                                                       |
-| variation **per tenant / user** — a workspace's theme                      | —                                                       |
-| **independent addressing** — queried, indexed, or FK'd in isolation        | a **JSON column** on its parent row                     |
-| **concurrency-safe** writes — racing writers must not clobber a shared blob | —                                                       |
-| a **DB-enforced invariant** — immutability trigger, unique, atomic boundary | —                                                       |
-| dev-authored, published on deploy, identical for every tenant — plan tiers | **config / a constants file**, validated at build       |
-| exactly recomputable from other rows — a tenant's usage total              | a **cache** (KV / edge), recomputed on demand           |
-| process state dead once the request completes — a retry count             | a **log or workflow engine**, never the domain DB       |
-| owned by another system-of-record — the payment processor's invoice        | a **reference column** — store the id, not the data     |
-
-Each right-column route is one test: process state — would a product feature break if this vanished the instant the request finished?; derived output — exactly recomputable from other rows + code?; un-addressed detail — is the row ever `SELECT`ed / `JOIN`ed / FK'd alone?; another system's record — does a specialized service (chat, telemetry, object store) already own it?
-
-- **Static vocabulary or a fixed graph → config, not a table** — HTTP status labels, a fixed onboarding funnel. Surface it in code as a constant/type; reifying it into tables plus a seed makes the file and the tables a two-copy sync problem. The refined boundary is § Vocabulary / lookup tables.
-- **History → one immutable log + a mutable head.** Never shatter versioning into per-entity `*_revisions` / `*_revision_sections` tables — snapshot the coherent set into one append-only versions table; current state is a projection of the newest entry. A table that is just "old rows of another table" collapses into the snapshot.
-- **A surviving table names the invariant it buys** — content-addressed immutable rows buy reproducibility, a monotonic sequence buys ordering/sync, an atomic write boundary buys multi-row atomicity. Drop the requirement and the table drops with it.
-
-Table count tracks **requirements, not domain richness** — a rich domain is not entitled to a table per noun.
-
-## State, rules, and history
-
-**One fact has one home, chosen by what kind of fact it is.** Confusing these produces the most common redundant table in a schema — a queue whose rows restate state the entity already carries.
-
-| The fact | Home | Example |
-| --- | --- | --- |
-| What the entity **is now** | a **column on the entity's own row** | `documents.state = 'blocked'` |
-| What may be **done** about that state | **code** — the transition map, the UI's affordances | which inputs unblock a document |
-| What **was done**, and by whom | the **append-only audit log** | an `audit_log` row: `document.override_applied` |
-| What a consumer must **replay in order** | the **sequence log** | an `app_events` row keyed `(app_id, sequence)` |
-
-- **State becomes a column the moment anything selects on it.** `WHERE state = 'blocked'` takes an index; `WHERE json_extract(metadata, '$.state') = 'blocked'` scans the table and is invisible to every schema check. JSON keeps only what § What earns a table leaves it — detail nothing addresses alone.
-- **A pending-work table mirroring row state is the anti-pattern** — `*_actions`, `*_inbox`, `*_flags`. The tell: resolving one of its rows also updates the entity, so two rows answer one question and are free to disagree. The *open question* is a column beside the state (at most one per row ⇒ a column, § A junction spells many-to-many); the *answer given* is an audit-log row.
-- **Legal transitions live in code, never as rows** — a `status_transitions` table is a state machine the database cannot enforce and the code must re-implement anyway to use.
-
-**The two logs are not substitutes**, and no one table serves both:
-
-| | Sequence log | Audit log |
-| --- | --- | --- |
-| Answers | what happened here, **in order** | who did what, **and whether it succeeded** |
-| Ordinal | a **gapless per-entity `sequence`**, allocated from a counter | none — nothing replays it |
-| Scope | one entity, always | any — **including none**: a sign-up predates every tenant |
-| Records | only what **happened** | **attempts too** — `denied`, `failure` |
-| Read by | cursors replaying forward | investigations, at any age |
-
-The bottom two rows are why neither can hold the other's rows: an event at a scope with no entity has no sequence to take, and a refused attempt in a replay stream would have consumers apply something that never happened.
-
-### The audit log's own shape
-
-**An audit log outlives every row it names, so it stores what it needs to stay readable without them.** Both consequences are missing from most first drafts:
-
-- **Denormalize the display at write time** — `actor_label`, `target_label` beside `actor_id` / `target_id`. Ids alone leave the log intact but unreadable once the person or record is deleted, which is the one thing it exists to survive.
-- **Record the attempt, not the success** — `outcome` (`success | failure | denied`) plus a `reason`. Refused sign-ins and permission denials are most of what anyone opens an audit log for; without the column they cannot be written at all.
-- **Keep the columns product-neutral** — `actor_*` · `action` · `outcome` · `target_*` · `scope_path` · `channel` · `source_ip` · `correlation_id` · `changes_json` serve any domain. Per-level tenancy columns tie the log to today's model; a materialized `scope_path` (`workspace:abc/app:def`) makes "everything under this tenant" one prefix scan and survives a new level appearing — at the price of enforcing the hierarchy in code rather than a `CHECK`.
-
-## Scope, not parallel tables
-
-One entity that exists at several scopes is **one table with a nullable scope column** — never one table per scope, and never one table shared across entity families.
-
-- **A table shared by several families carries the union of their columns** — one `settings` table for users, apps, and workspaces. Almost nothing can be `NOT NULL`, the payload lands in JSON beyond every constraint, index, and FK, and a new family widens a table other features already depend on. One table per family.
-- **Two tables declared to have "the same columns" are two schemas maintained by hand** — the drift is silent, surfacing as an incomplete copy, never as an error. Collapse them and discriminate by column.
-- **The scope column is the discriminator** (`app_id IS NULL` = parent scope, set = child scope). Copying a scope is then `INSERT … SELECT` over one table with one column rewritten, so source and target cannot disagree about shape.
-- **A nullable owner column is how a row exists before its owner does** — a pending enrolment or unclaimed record is creatable before the owner is known, which is what lets a `pending_*` / `*_requests` table collapse into the real one.
-- **A reserved row can own the shipped defaults.** A fixed-id "system" parent makes the defaults and a tenant's copy the same kind of row, through the same code. It must then be excluded from every tenant-scoped query — state that invariant where the id is defined.
-
-## Copying rows between scopes
-
-- **A copied junction row is already correct with no remapping** — its endpoints are `slug` references (§ Keys & the shared vocabulary), and a slug means the same thing in every scope. Rewriting ids through a source→copy map is the most error-prone step in a multi-level copy, and a partial failure leaves wiring pointed into another scope rather than raising.
-- **Provenance is a soft reference — no FK.** `source_id` must outlive its referent; an FK would either block the source's deletion or erase the lineage.
-- **Store the source's version at copy time** — `version` + `source_version` make "is an upgrade available" a comparison of two stored values, not a content diff.
-- **A copy is a row, never a live read.** Nothing at the child scope reads the parent's row at runtime; propagation happens only through an explicit re-copy, so a local edit is never silently overwritten.
+Naming and the fixed column vocabulary for relational schemas in **every** Nurix project — one concept, one name, everywhere. Written for SQLite / Cloudflare D1 + Drizzle; a Postgres project keeps the same column names and semantics with native types (`uuid`, `timestamptz`, `boolean`). **Design doctrine — what earns a table, state vs. logs, junctions, FK policy, uniqueness traps — is the `schema-design` skill; consult it before any schema change.**
 
 ## Keys & the shared vocabulary
 
 Three column roles are fixed across every table and every project:
 
 - **`id`** — the primary key, **always a UUID** (`TEXT PRIMARY KEY` on D1, `uuid` on Postgres), never a synthetic or natural key (❌ `type_page_button`, `human:default`). Runtime rows mint a UUIDv7; seed rows derive a deterministic UUIDv5 of the natural key so re-seeds stay stable. **Never** mix synthetic and UUID ids in one table. The single exemption is a log whose **composite key is its ordering** (`PRIMARY KEY (<entity>_id, sequence)`), declared at the table that uses it — everything else, logs included, takes a UUIDv7.
-- **`slug`** — the **stable key rows in another scope reference**: `UNIQUE`, lowercase `snake_case`. A slug means the same thing in every scope, so a slug reference survives a copy with no remapping (§ Copying rows between scopes). ❌ Never rename this role `handle`, `key`, `code`, or `name` in another project.
+- **`slug`** — the **stable key rows in another scope reference**: `UNIQUE`, lowercase `snake_case`. A slug means the same thing in every scope, so a slug reference survives a copy with no remapping — copying between scopes is the `schema-design` skill. ❌ Never rename this role `handle`, `key`, `code`, or `name` in another project.
 - **`label`** — the **human display name** — ❌ never `name`, `title`, or `display_name`.
 
 Reference columns name what they point at: `<entity>_id` for a UUID-PK reference (`user_id`, `app_id`), `<entity>_slug` for a slug reference (`source_slug`).
@@ -96,63 +18,17 @@ Reference columns name what they point at: `<entity>_id` for a UUID-PK reference
 
 **Every inbound FK to a hub table declares a deliberate `ON DELETE`.** A hub (`users`, `devices`, anything several modules point at) collects edges from teams that never meet, and a single `NO ACTION` among them turns deleting the parent into a constraint error naming neither table. Decide per edge: the child dies with the row (`CASCADE`) or survives it (`SET NULL`, which needs a nullable column) — `NO ACTION` on a hub is a deferred outage, not a default.
 
-## A junction spells many-to-many — nothing else
-
-**A `_map` table is the schema's notation for M:N. Using it for 1:M is a category error** — the junction's own uniqueness admits many parents per child, so the "one parent" rule stops being enforced the moment it is written this way. Cardinality decides between the only two shapes:
-
-| Relationship | Shape |
-| --- | --- |
-| **1:M** — the child has exactly one parent | a **reference column on the child** (`agents.routing_slug`), plus an index |
-| **M:N** — both sides have many | a **`<a>_<b>_map` junction** with a composite unique |
-
-- **The test is one question about the child**: can this row ever belong to two parents at once? No ⇒ column. A junction "in case it becomes M:N later" ships the unenforced model today to buy a migration you may never run.
-- **A junction for a 1:M also** makes the association a row that can go missing independently of the child — a child can exist correctly while its wiring does not — and forces a join onto the most common read in the system.
-- **A junction carrying only its two endpoints and timestamps is the tell** — a real M:N junction usually earns its own columns (a role, an order, a status); one that never does is a 1:M waiting to be collapsed into a column.
-- **Collapsing deletes a copy step** — the association travels inside the row it belongs to: no second pass to remap, no copy landing with its wiring half-applied.
-- **A pair already recorded elsewhere needs no table at all.** If an append-only log stores `(parent, child)` on every write, the association table is `SELECT DISTINCT` over that log — a cache free to disagree with the log it derives from (§ What earns a table).
-
-## Foreign keys into and out of append-only tables
-
-**An append-only table can afford no `ON DELETE` action at all, so its references to mutable tables are soft — no FK.** Every option is closed to it:
-
-| Action | Why it fails on an append-only table |
-| --- | --- |
-| `SET NULL` | It is an **UPDATE**. An append-only trigger aborts it, so the parent's deletion fails — with an error naming the trigger, not the constraint. |
-| `CASCADE` | Deletes history to delete a person. The log exists precisely to outlive its subjects. |
-| `NO ACTION` | Makes anyone who ever appeared in the log undeletable — the hub defect above. |
-
-- **`SET NULL` is the trap** — it reads like a safe relaxation of `NO ACTION` and passes review as one.
-- **Record the actor as a plain column** — the same soft-reference treatment provenance gets (`source_id`, `thread_id`). The log keeps naming who acted after the account is gone, which is what an audit trail is for.
-- **`CASCADE` from the append-only side's own parent is still fine** — a cascade is a DELETE, so a `BEFORE UPDATE` trigger never sees it: an App's log dying with the App is legitimate, distinct from erasing a log to delete a person.
-- **State the exemption where it exists.** A catalog whose rows must not disappear under a referencing row (a service definition, a vocabulary) keeps `NO ACTION` deliberately — that guarantee is worth one line saying so.
-
 ## Naming
 
 - **Tables** — `snake_case`, plural noun for what they hold (`users`, `apps`, `devices`).
-- **Junction (M:N) tables** — `<entityA>_<entityB>_map`, **always**, even when the join carries its own columns; singular stems, owning/anchor entity first (`app_user_map`, `app_device_map`). ❌ Never a "nice" noun (`members`, `installs`, `memberships`, `enrolments`) — the name must read as a join, and a reviewer should know both sides from it. The `_map` suffix is reserved for genuine M:N (§ A junction spells many-to-many).
+- **Junction (M:N) tables** — `<entityA>_<entityB>_map`, **always**, even when the join carries its own columns; singular stems, owning/anchor entity first (`app_user_map`, `app_device_map`). ❌ Never a "nice" noun (`members`, `installs`, `memberships`, `enrolments`) — the name must read as a join, and a reviewer should know both sides from it. The `_map` suffix is reserved for genuine M:N — the cardinality test that decides junction vs. column is the `schema-design` skill.
 - **Columns** — `snake_case`; booleans `is_*` / `has_*`; timestamps `created_at` / `updated_at`; foreign keys `<entity>_id`.
 - **Indexes** — `<table>_<col(s)>_idx`; unique `<table>_<col(s)>_unique`; a junction's composite unique reads `<table>_<colA>_<colB>_unique` (`app_user_map_app_user_unique`).
 - **Drizzle mirror** — the exported object is the camelCase table name (`app_user_map` → `appUserMap`); column props are the camelCase of the column (`created_at` → `createdAt`). The `sqliteTable("…")` string and every index name must match the DDL (`init.sql`) exactly — the schema-parity boundary.
 
-## Uniqueness with a nullable column
-
-**`UNIQUE (a, b)` does not constrain rows where `b` is `NULL`** — SQL treats every `NULL` as distinct, so a composite unique over a nullable discriminator silently permits exactly the duplicates it was introduced to keep apart. Write one partial index per scope instead:
-
-```sql
-CREATE UNIQUE INDEX <t>_parent_slug_unique ON <t> (parent_id, slug) WHERE child_id IS NULL;
-CREATE UNIQUE INDEX <t>_child_slug_unique  ON <t> (child_id, slug)  WHERE child_id IS NOT NULL;
-```
-
-**Prove a uniqueness claim by inserting the duplicate it forbids** — a schema review cannot tell a firing index from a silent one by reading.
-
 ## Column types (SQLite / D1)
 
 - **Timestamps** — `created_at` + `updated_at`, both `TEXT NOT NULL DEFAULT (datetime('now'))`, on **every** table — except append-only logs, which carry only `created_at`.
 - **Booleans** — `INTEGER` (Drizzle `integer(…, { mode: "boolean" })`); the `is_*` / `has_*` names are § Naming.
 - **JSON** — `TEXT` (Drizzle `text(…, { mode: "json" })`).
 
-## Vocabulary / lookup tables
-
-A controlled vocabulary earns a **table** only when a user row FKs into it and reads its `label` / `description` at runtime — a service catalog rendered in a picker; static dev-authored config nobody references by FK stays **config** (§ What earns a table) — a `doc_type` value list. Enumerable is not tabular, and a `type`-style column validated against the constants file beats an FK to a seeded mirror. An earned table has a fixed shape: `id` (UUID) · `slug` (UNIQUE) · `label` · optional `description` · `status` · timestamps.
-
-- **Seeds are generated, never hand-written** — the source of truth is a CSV or a shared package; a generator emits the `*.seed.sql` with UUIDv5 ids and an idempotent `ON CONFLICT(slug)` upsert that preserves live counts / admin-tuned columns. ❌ Hand-editing seed SQL — regenerate it.

package/data/harnesses/apollo/rules/frontend.md

@@ -1,10 +1,10 @@
 # Frontend
 
-Tailwind v4 + shadcn-based UI conventions for **web** apps — styling, the `@nurix/components` library, the `design.md` token artifact, and design-skill routing — plus the TypeScript conventions every package compiles under. Package versions live in [`general.md`](general.md); the Express server and API envelope in [`express.md`](express.md); workspace layout and consuming `@nurix/*` packages in [`pnpm.md`](pnpm.md); React Native styling is [`react-native.md`](react-native.md).
+Tailwind v4 + shadcn-based UI conventions for **web** apps — styling, the `@nurix/components` library, the `design.md` token artifact, and design-skill routing — plus the TypeScript conventions every package compiles under.
 
 - **Build every UI through the `design` skill** — never hand-roll layouts; the page archetypes, the `design.md` identity system with its token artifact (`design.tokens.css`), and chrome wiring live in the skill.
 - **The brief's stated theme binds** — dark boots dark when the brief says so (recorded in the project's `design.md`); light is the default only when the brief is silent.
-- **`@nurix/components`** is the UI library — import by subpath (`@nurix/components/button`); install, auth, and the no-substitutes guard are [`pnpm.md`](pnpm.md) §3. **Never** `npx shadcn add`, no `components.json` scaffold — consume the prebuilt library (`.tsx`, not `.jsx`).
+- **`@nurix/components`** is the UI library — import by subpath (`@nurix/components/button`). **Never** `npx shadcn add`, no `components.json` scaffold — consume the prebuilt library (`.tsx`, not `.jsx`).
 - Vite: `@tailwindcss/vite` + `@vitejs/plugin-react-swc`. Pin `react` / `react-dom` / `react/jsx-runtime` / `react/jsx-dev-runtime` to the app's single copy via `resolve.alias` — `@nurix/*` ship nested react, and two copies means two hook dispatchers.
 - Tailwind v4 is CSS-only — no `tailwind.config.js`, no PostCSS.
 - CSS entry `globals.css`, imports in order: `@import "./fonts.css"` (`@fontsource` registrations) → the project's `design.tokens.css` (derived from the repo-base `design.md` by the design skill's validator — **never** hand-edited) → `@import "tailwindcss"` → the library's `styles.css` — then `@theme inline {…}` mapping vars to tokens.
@@ -28,5 +28,3 @@ Shared libraries (`@nurix/components`, etc.) are generic on purpose — that's w
 - **Bind a repeated factory once** (preferred): `const col = defineColumn<BriefRow>;` → `col({...})`. Canonical: `modules/briefs/BriefsListPage.tsx`.
 - **Infer JSX type args from props:** `<Table data={rows} columns={columns} />`, not `<Table<BriefRow> …>`.
 - **Anchor with a collection annotation** when nothing else can: `const columns: ColumnDefinition<BriefRow>[] = [...]`.
-
-> Monorepo TS policy (`tsconfig.base.json` + thin per-package `extends`, source-first internal packages, `peerDependencies`, pnpm `catalog:`) lives in [`pnpm.md`](pnpm.md) §2 — it travels with package boundaries.

package/data/harnesses/apollo/rules/general.md

@@ -1,54 +1,32 @@
 # General Standards
 
-Runtime versions, the canonical package list, and GitHub Actions pins — the workspace baseline. Web-frontend/styling conventions are [`frontend.md`](frontend.md); the Express server and the API response envelope are [`express.md`](express.md).
+Runtime versions, package policy, the API response envelope, and GitHub Actions pins — the workspace baseline.
 
 ## Runtime Versions
 
-- **Node.js:** 24 LTS
+- **Node.js:** the version pinned in `.nvmrc` / `package.json` `engines` — **never** a hardcoded number, **never** the runner's default. Workflows use `node-version-file: .nvmrc`.
 - **Package manager:** detect from the lockfile — **never** hardcode one.
 - **PostgreSQL:** 17 · **Redis:** 7.x (latest)
 
 ## Packages
 
-**Only** these — no alternatives.
-
-| Package | Version | Use | Don't use |
-| --- | --- | --- | --- |
-| `react` | ^19.2.3 | UI components | — |
-| `vite` | ^8.0.0 | Build tool, dev server | `webpack`, CRA |
-| `tailwindcss` | ^4.1.18 | Styling | `styled-components` |
-| `@vitejs/plugin-react-swc` | ^4.2.2 | JSX compilation | `@vitejs/plugin-react` |
-| `react-router-dom` | ^7.11.0 | Routing | — |
-| `@reduxjs/toolkit` | ^2.11.2 | State management | `zustand`, `jotai` |
-| `react-redux` | ^9.2.0 | Redux React bindings | — |
-| `axios` | ^1.13.2 | HTTP requests | `fetch` |
-| `@microsoft/fetch-event-source` | ^2.0.1 | SSE over POST — streaming agent output | hand-rolled `getReader()` loops, `EventSource` |
-| `date-fns` | ^4.1.0 | Date formatting | `moment`, `dayjs` |
-| `@dnd-kit/core` | ^6.3.1 | Drag and drop | `react-beautiful-dnd` |
-| `@xyflow/react` | ^12.11.0 | Node-based flow charts | `reactflow`, `react-flow-renderer` |
-| `motion` | ^12.23.26 | Animations | `react-spring` |
-| `sonner` | ^2.0.7 | Toast notifications | `react-toastify` |
-| `react-window` | ^2.2.3 | List virtualization | `react-virtualized` |
-| `nanoid` | ^6.0.0 | ID generation | `uuid` |
-| `express` | ^5.2.1 | HTTP server | `fastify`, `koa` |
-| `drizzle-orm` | ^0.45.2 | Database ORM | `prisma`, `sequelize`, `typeorm` |
-| `drizzle-kit` | ^0.31.10 | Schema tooling | — |
-| `zod` | ^4.2.1 | Schema validation | `yup`, `joi` |
-| `jose` | ^6.1.3 | JWT handling | `jsonwebtoken` |
-| `microdiff` | ^1.5.0 | JSON object diffing | `deep-diff`, `just-diff` |
-| `react18-json-view` | ^0.2.9 | JSON tree view | `react-json-view` |
-| `@tiptap/react` | ^3.11.1 | Rich text editor | `slate`, `quill`, `draft-js` |
-| `shiki` | ^4.3.1 | Syntax highlighting | `prism`, `highlight.js` |
-| `lucide-react` | ^1.26.0 | Icons | `react-icons`, `heroicons` |
-| `@pdfme/generator` | ^6.1.12 | PDF generation | `jspdf`, `pdfkit` |
-| `cmdk` | ^1.1.1 | Command palette | `kbar`, `ninja-keys` |
-| `@monaco-editor/react` | ^4.7.0 | Code editor | `codemirror`, `ace` |
-| `localforage` | ^1.10.0 | Client-side storage | `idb`, `dexie` |
-| `react-markdown` | ^10.1.0 | Markdown rendering | `marked`, `markdown-it` |
-| `remark-gfm` | ^4.0.1 | GFM (tables, tasklists) | `remark-github`, custom |
-| `fast-deep-equal` | ^3.1.3 | Deep equality checks | `lodash.isEqual` |
-| `@ngneat/falso` | latest | Fake data generation | `@faker-js/faker`, `chance` |
-| `pino` | ^10.1.0 | Logging | `winston` |
+**Only packages in the approved table** — `.claude/hooks/approved-packages.md`, enforced by the PreToolUse install gate, which names the file on a block. The table changes only by explicit user decision. Test packages install at `latest`; fake data comes from `@ngneat/falso` — **never** `@faker-js/faker` / `chance`.
+
+## API Response Envelope
+
+Success and error share **one** envelope — a cross-service contract clients branch on, so a per-service "improvement" (`success: true`, a boolean `status`, a bare payload) breaks every consumer:
+
+```json
+{
+  "status": 1,
+  "message": "Message sent successfully",
+  "data": { "delivered": [{ "user@example.com": 2 }] }
+}
+```
+
+Error: `{ "status": 0, "message": "Error description", "data": null }`
+
+HTTP codes, default list: `200`, `201` (created), `400`, `401` (not authenticated), `403` (not authorized), `404`, `500` — plus `204`/`304` (null-body responses), `409` (conflicting write), `429` (rate limit), `503` (unhealthy dependency) where the semantics call for them. Middleware- and protocol-emitted codes are exempt from the envelope.
 
 ## GitHub Actions
 
@@ -59,4 +37,4 @@ Pin the major, and check it against the action's releases — a major behind sti
 | `actions/checkout` | v7 | Repo checkout |
 | `actions/setup-node` | v7 | Node toolchain + npm cache |
 
-Set `node-version` from the Runtime Versions block above, **never** from the runner's default.
+Set `node-version` via `node-version-file: .nvmrc`, **never** a hardcoded number and **never** the runner's default.

package/data/harnesses/apollo/rules/nomenclature.md

@@ -1,6 +1,6 @@
 # Nomenclature
 
-Naming and casing for code — identifiers, files, folders. The rationale throughout is consistency: one concept, one name, one casing shape, in every repo that loads this rule. Database naming is not here — see § Database.
+Naming and casing for code — identifiers, files, folders. The rationale throughout is consistency: one concept, one name, one casing shape, in every repo that loads this rule.
 
 Names state intent in full words — clarity over brevity; no abbreviations unless universally understood (`id`, `url` ✅ · `cfg`, `btn`, `idx` ❌).
 
@@ -12,7 +12,7 @@ Names state intent in full words — clarity over brevity; no abbreviations unle
 | `PascalCase` | classes, type definitions, components; the file exporting one | `PaymentProcessor`, `AppsListPage.tsx` |
 | `UPPER_SNAKE_CASE` | constants, environment variables | `MAX_RETRY_COUNT` |
 | `kebab-case` | URLs, CSS class names, HTML IDs, multi-word folders | `user-profile`, `workspace-provisioning/` |
-| `snake_case` | database tables, columns, indexes — § Database | `created_at` |
+| `snake_case` | database tables, columns, indexes | `created_at` |
 
 **A file exporting one component carries that component's name exactly**, so an import names the file it came from; a single-word folder is plain lowercase (`lib`, `surfaces`). ❌ Never `snake_case` a file or folder — that casing belongs to the database.
 
@@ -28,7 +28,3 @@ Names state intent in full words — clarity over brevity; no abbreviations unle
 | Event handler | `handle` or `on` prefix | `handleSubmit`, `onPageLoad` |
 | Interface | `I` prefix acceptable; type aliases stay plain | `IConfigOptions`, `AuthResponse` |
 | Async function | verb phrase; `Async` suffix acceptable | `loadConfigAsync` |
-
-## Database
-
-Table, column, index, and key naming for relational schemas — the `id` / `slug` / `label` vocabulary, junction `_map` tables, and Drizzle mirrors — lives in [`database.md`](database.md), which routes general code naming back here.

package/data/harnesses/apollo/rules/pnpm.md

@@ -1,6 +1,6 @@
 # pnpm — `@nurix/*` Workspaces: naming, boundaries, and consuming
 
-How a `@nurix/*` repo is **named**, **structured**, and how its packages are **consumed** — every repo takes the workspace shape, single-package frontends included. Publishing and CLI design live in the `nustack` skill, not here. TypeScript language conventions are [`frontend.md`](frontend.md).
+How a `@nurix/*` repo is **named**, **structured**, and how its packages are **consumed** — every repo takes the workspace shape, single-package frontends included. Publishing and CLI design live in the `nustack` skill, not here.
 
 ---
 
@@ -22,7 +22,7 @@ Every workspace package is scoped **`@nurix/`**; the dot vs. hyphen after the sc
 
 ## 2. Monorepo & package boundaries
 
-- **One `tsconfig.base.json` at the repo root owns TS policy** — the strict set ([`frontend.md`](frontend.md)), `target`, and everything uniform across packages (here, `module`/`moduleResolution`). Each package's `tsconfig.json` `extends` the base and adds only its coordinates (`rootDir`/`outDir`/`include`) and genuine environment overrides (`lib`/`types`/`jsx`; `module`/`moduleResolution` only when the package's module system truly differs). **Never** re-declare or weaken a policy option locally. One exception: a framework that owns its own base (an Astro app on `astro/tsconfigs/strict`).
+- **One `tsconfig.base.json` at the repo root owns TS policy** — the strict set, `target`, and everything uniform across packages (here, `module`/`moduleResolution`). Each package's `tsconfig.json` `extends` the base and adds only its coordinates (`rootDir`/`outDir`/`include`) and genuine environment overrides (`lib`/`types`/`jsx`; `module`/`moduleResolution` only when the package's module system truly differs). **Never** re-declare or weaken a policy option locally. One exception: a framework that owns its own base (an Astro app on `astro/tsconfigs/strict`).
 - **Internal packages are source-first.** A `private: true` package exposes its API via `exports` pointing at source (`"types"`/`"default"` → `./src/index.ts`) — no build step, and no bare `main`/`module` on new packages. One typed subpath per public surface; consumers import the subpath, **never** a deep relative path into another package's `src/`. `types` comes **first** in every subpath block — resolvers take the first matching condition, so a `types` listed after `default` is never reached.
 - **Crossing the publish boundary is the `nustack` skill** — `private: false`, the published manifest, the pipeline.
 - **Single-source shared dep versions with pnpm `catalog:`** — `typescript`, `zod`, `vitest`, `react`, type packages — so every package resolves the same copy and its types stay mutually assignable.

package/data/harnesses/apollo/rules/testing.md

@@ -1,9 +1,44 @@
-# Testing
+# Testing & Verification
 
-Test technology and placement — framework per stack, suite layout, mocking policy; **when** a test is written and how work is proven is [`verification.md`](verification.md), not here. Framework choice is **never** ad hoc and never the user's problem mid-task: detect the stack, use its row; if the repo already has a runner, that runner wins — **never** introduce a second framework beside it.
+**When** work is proven and **which technology** proves it — the standing constraints that bind on every turn. The full lifecycle procedure — deriving a plan's Test Obligations, placing tests in strata, executing the verification gate — is the `testing` skill, invoked at those moments; this rule never restates it.
+
+## Two regimes
+
+**Deferral is a property of plans, not of code.** A plan carries a Test Obligations ledger and a gate that discharges it; nothing else does, so nothing else may defer.
+
+| Regime | During the work | Proven |
+| --- | --- | --- |
+| **Plan-driven build** | No new test files. Code only — the loop stays fast | At the verification gate, before `Status: Complete` |
+| **Bug fix** — a defect in shipped behavior | The regression test ships with the fix | Immediately — it fails before the change, passes after |
+| **Ad-hoc / non-plan change** | The test ships with the change **when it alters promised behavior** — layout, copy, and config tweaks owe none | Immediately, same discipline as a bug fix |
+
+- **A bug fix cannot defer** — "fails before, passes after" is provable afterward only by reverting to the pre-fix ref, a cost nobody pays; capture the property at fix time or lose it.
+- **Ad-hoc work cannot defer — there is no ledger to defer into.** A non-plan change that alters no promised behavior — a pure refactor, a rename — owes no test.
+
+## During the loop
+
+Rules for the plan regime between the plan gate and the verification gate:
+
+- **No new test files** — obligations wait in the plan's ledger (written at the plan gate by the `testing` skill).
+- **Existing tests broken by the plan's intended behavior change are updated to the new contract before any mid-plan commit** — the shared branch never carries a red suite, and an update is never a weakening (§ Discipline).
+- **A defect in the plan's own in-flux code is the loop iterating** — no test, no ledger row. **A pre-existing bug in shipped behavior is the bug-fix regime even mid-plan**: fix it with its regression test now — deferring it to the gate loses "fails before" — or send it to the backlog via Out-of-Scope Discovery. Never fix silently.
+- **The ledger is amendable while the plan is open** — the gate discharges whatever it holds at gate time.
+- **A mid-plan commit is a checkpoint, not a verification claim.**
+
+## The gate
+
+**A discrete, user-triggered step.** When implementation is complete, report it and offer the gate — never run it unbidden, and never flip `Status: Complete` without it. An explicit user acceptance of finished plan work — "ship it", "commit", "looks good" — counts as the trigger; open the gate without asking again. A plan with outstanding obligations stays open, whatever the code does. The procedure — checklist, drive-then-pin ladder, row discharge, what earns a durable test — is the `testing` skill (gate mode).
+
+- **Precondition: the ledger exists.** A plan with no Test Obligations section is blocked at the gate — run the `testing` skill (plan-gate mode) on it first; an empty ledger passes vacuously and the gap surfaces only after the file is frozen.
+- **The verdict is never delegated** (the root policy file § Delegation), and where browser work is main-session-only (its § Runtime Notes), the driving is too. Fan-out may prepare fixtures or draft test bodies; the driving and the verdict stay inline.
+- **The gate needs no stronger tier than the session default** — a standard-tier session suffices whatever tier built the plan; the plan and its ledger carry all the state the gate needs, so gating in a fresh session loses nothing.
+- **Report what happened, including failures.** A gate that reports green while a suite is red is worse than no gate; state the failing test and its output.
+- **Abandonment does not erase debt.** Before `Status: Abandoned` freezes a plan whose code was committed, convert its undischarged rows into backlog items; uncommitted code owes nothing.
 
 ## Frameworks by stack
 
+Framework choice is **never** ad hoc and never the user's problem mid-task: detect the stack, use its row; if the repo already has a runner, that runner wins — **never** introduce a second framework beside it.
+
 | Stack | Unit / integration | Component | E2E | HTTP mocking | Don't use |
 | --- | --- | --- | --- | --- | --- |
 | Node + Vite / React (web) | `vitest` | `@testing-library/react` (+ `@testing-library/user-event`, `happy-dom`) | `@playwright/test` | `msw` | `jest`, `mocha`, `jasmine`, `cypress`, `enzyme` |
@@ -12,7 +47,7 @@ Test technology and placement — framework per stack, suite layout, mocking pol
 | Cloudflare Workers | `vitest` + `@cloudflare/vitest-pool-workers` | — | `@playwright/test` against `wrangler dev` | `msw` | `jest` |
 | Rust | `cargo test` (built-in) | — | — | — | — |
 
-Test packages install at `latest` — they sit outside [`general.md`](general.md)'s pinned table. Fake data comes from `@ngneat/falso` — **never** `@faker-js/faker` / `chance` (its row there).
+Test packages install at `latest` — outside the approved-packages pin set. Fake data comes from `@ngneat/falso` — **never** `@faker-js/faker` / `chance`.
 
 ## Conventions
 
@@ -21,3 +56,9 @@ Test packages install at `latest` — they sit outside [`general.md`](general.md
 - **Unit and E2E trees stay separate.** Vitest/Jest suites in `tests/`; Playwright/Maestro suites in `e2e/` with their own config — **never** mixed into the unit runner's glob.
 - **No test doubles for what you own.** Prefer real instances — in-memory SQLite for drizzle, the actual Express app via `supertest` — over mocks; mock **only** true externals (network via `msw`, time via the runner's fake timers).
 - **Determinism.** No real network, no real time, no shared mutable state between tests; every test **must** pass alone and in any order.
+
+## Discipline
+
+- **Never weaken, skip, or delete a test to mask an unexplained failure.** When a plan or LLD intentionally changes behavior, updating the affected tests to the new contract is part of that change.
+- **A behavior that is compiler-guarded owes no test** — if it cannot ship green-but-broken, a test adds cost and no safety.
+- **Throwaway checks are not tests.** Temporary scripts written to drive a change live in scratch space and are deleted — never committed into the test tree.

package/data/harnesses/apollo/skills/documentation/references/instruction-style.md

@@ -24,6 +24,7 @@ Policy files (`CLAUDE.md`, rules) are declarative — assertion bullets and tabl
 ## Routing
 
 - **Link, don't copy — one canonical source per topic.** `CLAUDE.md` is a **router, not a manual**: per workflow, when to enter, what to dispatch, where the output lands — mechanics live in the agent or skill file, which loads only when it runs.
+- **A rule never references a sibling rule.** Rules co-load, so pointing at one from another routes a reader to text already in front of them — noise that also drifts the moment either file moves. State what the rule owns, self-contained; the only outward links a rule carries are to skills and agents, whose bodies do *not* co-load. Routing downward from `CLAUDE.md` to a rule is fine — that is the router doing its job.
 - **Cut generic engineering advice.** Agents already know how to code; keep only what is true of *this* stack and not derivable by looking at it.
 - **Keep load-bearing rules even when project-specific.** Genericizing is for reference material, not guardrails — deleting a hard rule removes a constraint the agent will otherwise violate.
 

package/data/harnesses/apollo/skills/documentation/templates/plan.md

@@ -1,10 +1,10 @@
 # Plan (docs/history/plans/YYYY-MM-DD-feature-name.md)
 
-Record. Use for: every implementation plan. Plans are created here directly with `Status: Draft`; after approval the plan gates (`boundary`, then `test-plan`) run against the still-`Draft` file, the status flips to `Status: In Progress` at the first implementation step, and the file freezes at `Status: Complete` or `Status: Abandoned`. Once frozen, never edit — write a new dated plan if scope changes. The plan records the journey; the truth it implemented lives on in the feature doc and any AD it touched.
+Record. Use for: every implementation plan. Plans are created here directly with `Status: Draft`; after approval the plan gates (`boundary`, then `testing` plan-gate mode) run against the still-`Draft` file, the status flips to `Status: In Progress` at the first implementation step, and the file freezes at `Status: Complete` or `Status: Abandoned`. Once frozen, never edit — write a new dated plan if scope changes. The plan records the journey; the truth it implemented lives on in the feature doc and any AD it touched.
 
-The `boundary` skill parses the **Proposed Changes** sections to check boundary impact before execution, and the `test-plan` skill writes a **Test Obligations** section into the plan at the same gate. Keep that structure stable — section headings and bullet shape are load-bearing for the parsers, and the Test Obligations table is the ledger the verification gate discharges before the plan may reach `Status: Complete`.
+The `boundary` skill parses the **Proposed Changes** sections to check boundary impact before execution, and the `testing` skill (plan-gate mode) writes a **Test Obligations** section into the plan at the same gate. Keep that structure stable — section headings and bullet shape are load-bearing for the parsers, and the Test Obligations table is the ledger the verification gate discharges before the plan may reach `Status: Complete`.
 
-The **`Gates:`** line is machine-read: the compliance hook greps exactly the forms below, and implementation edits are blocked while a segment reads `pending`. Each gate skill rewrites only its own segment when it runs — `boundary` to `Boundary: passed YYYY-MM-DD` or `Boundary: blocked YYYY-MM-DD`; `test-plan` to `Test-plan: written YYYY-MM-DD (N rows)`. Never hand-edit the line to skip a gate.
+The **`Gates:`** line is machine-read: the compliance hook greps exactly the forms below, and implementation edits are blocked while a segment reads `pending`. Each gate skill rewrites only its own segment when it runs — `boundary` to `Boundary: passed YYYY-MM-DD` or `Boundary: blocked YYYY-MM-DD`; `testing` (plan-gate mode) to `Test-plan: written YYYY-MM-DD (N rows)` — the segment label stays `Test-plan`, greppable. Never hand-edit the line to skip a gate.
 
 ```
 # {Feature Name}
@@ -52,7 +52,7 @@ Why this work is happening *now*. Link to the spec for *what* we're building; th
 
 ## Test Obligations
 
-<!-- Written by the `test-plan` skill at the plan gate (after `boundary`). One row per
+<!-- Written by the `testing` skill (plan-gate mode) at the plan gate (after `boundary`). One row per
      promised behavior: layer · target file · oracle · fixtures. Amendable while the
      plan is open; discharged at the verification gate. Do not hand-author. -->
 

package/data/harnesses/apollo/skills/schema-design/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: schema-design
+description: "Use when designing or altering a relational schema — a new table, column, index, junction, migration, or seed — or reviewing one. Owns the design doctrine: what earns a table, where a fact lives (state column vs. sequence log vs. audit log), scope columns over parallel tables, junction = M:N only, FK policy including append-only tables, uniqueness with nullable columns, vocabulary tables, copying rows between scopes. Naming and column types stay in the `database.md` rule. Triggers on 'new table', 'schema', 'migration', 'add a column', 'junction table', 'foreign key', 'audit log', 'versioning'."
+---
+
+# Schema Design — the doctrine
+
+You decide **what earns a table and where a fact lives** — for every Nurix relational schema, engine-agnostic (written for SQLite / Cloudflare D1 + Drizzle; a Postgres project keeps the same names and semantics with native types). Naming, the `id`/`slug`/`label` vocabulary, and column types are the `database.md` rule and are never restated here — this skill owns the design arguments consulted at schema-change time.
+
+Apply the sections below to the change in hand; when reviewing, report violations with the section that names them.
+
+## What earns a table
+
+A table is the most expensive home for data — a migration to change its shape, a join to read, a mirror to keep in sync. Default to **not** a table — a concept earns one only with at least one property in the left column.
+
+| A table is earned by…                                                      | Lacking all of these, the data belongs in…              |
+| -------------------------------------------------------------------------- | ------------------------------------------------------- |
+| identity minted at **runtime** — a session, an upload                      | —                                                       |
+| variation **per tenant / user** — a workspace's theme                      | —                                                       |
+| **independent addressing** — queried, indexed, or FK'd in isolation        | a **JSON column** on its parent row                     |
+| **concurrency-safe** writes — racing writers must not clobber a shared blob | —                                                       |
+| a **DB-enforced invariant** — immutability trigger, unique, atomic boundary | —                                                       |
+| dev-authored, published on deploy, identical for every tenant — plan tiers | **config / a constants file**, validated at build       |
+| exactly recomputable from other rows — a tenant's usage total              | a **cache** (KV / edge), recomputed on demand           |
+| process state dead once the request completes — a retry count             | a **log or workflow engine**, never the domain DB       |
+| owned by another system-of-record — the payment processor's invoice        | a **reference column** — store the id, not the data     |
+
+Each right-column route is one test: process state — would a product feature break if this vanished the instant the request finished?; derived output — exactly recomputable from other rows + code?; un-addressed detail — is the row ever `SELECT`ed / `JOIN`ed / FK'd alone?; another system's record — does a specialized service (chat, telemetry, object store) already own it?
+
+- **Static vocabulary or a fixed graph → config, not a table** — HTTP status labels, a fixed onboarding funnel. Surface it in code as a constant/type; reifying it into tables plus a seed makes the file and the tables a two-copy sync problem. The refined boundary is § Vocabulary / lookup tables.
+- **History → one immutable log + a mutable head.** Never shatter versioning into per-entity `*_revisions` / `*_revision_sections` tables — snapshot the coherent set into one append-only versions table; current state is a projection of the newest entry. A table that is just "old rows of another table" collapses into the snapshot.
+- **A surviving table names the invariant it buys** — content-addressed immutable rows buy reproducibility, a monotonic sequence buys ordering/sync, an atomic write boundary buys multi-row atomicity. Drop the requirement and the table drops with it.
+
+Table count tracks **requirements, not domain richness** — a rich domain is not entitled to a table per noun.
+
+## State, rules, and history
+
+**One fact has one home, chosen by what kind of fact it is.** Confusing these produces the most common redundant table in a schema — a queue whose rows restate state the entity already carries.
+
+| The fact | Home | Example |
+| --- | --- | --- |
+| What the entity **is now** | a **column on the entity's own row** | `documents.state = 'blocked'` |
+| What may be **done** about that state | **code** — the transition map, the UI's affordances | which inputs unblock a document |
+| What **was done**, and by whom | the **append-only audit log** | an `audit_log` row: `document.override_applied` |
+| What a consumer must **replay in order** | the **sequence log** | an `app_events` row keyed `(app_id, sequence)` |
+
+- **State becomes a column the moment anything selects on it.** `WHERE state = 'blocked'` takes an index; `WHERE json_extract(metadata, '$.state') = 'blocked'` scans the table and is invisible to every schema check. JSON keeps only what § What earns a table leaves it — detail nothing addresses alone.
+- **A pending-work table mirroring row state is the anti-pattern** — `*_actions`, `*_inbox`, `*_flags`. The tell: resolving one of its rows also updates the entity, so two rows answer one question and are free to disagree. The *open question* is a column beside the state (at most one per row ⇒ a column, § A junction spells many-to-many); the *answer given* is an audit-log row.
+- **Legal transitions live in code, never as rows** — a `status_transitions` table is a state machine the database cannot enforce and the code must re-implement anyway to use.
+
+**The two logs are not substitutes**, and no one table serves both:
+
+| | Sequence log | Audit log |
+| --- | --- | --- |
+| Answers | what happened here, **in order** | who did what, **and whether it succeeded** |
+| Ordinal | a **gapless per-entity `sequence`**, allocated from a counter | none — nothing replays it |
+| Scope | one entity, always | any — **including none**: a sign-up predates every tenant |
+| Records | only what **happened** | **attempts too** — `denied`, `failure` |
+| Read by | cursors replaying forward | investigations, at any age |
+
+The bottom two rows are why neither can hold the other's rows: an event at a scope with no entity has no sequence to take, and a refused attempt in a replay stream would have consumers apply something that never happened.
+
+### The audit log's own shape
+
+**An audit log outlives every row it names, so it stores what it needs to stay readable without them.** Both consequences are missing from most first drafts:
+
+- **Denormalize the display at write time** — `actor_label`, `target_label` beside `actor_id` / `target_id`. Ids alone leave the log intact but unreadable once the person or record is deleted, which is the one thing it exists to survive.
+- **Record the attempt, not the success** — `outcome` (`success | failure | denied`) plus a `reason`. Refused sign-ins and permission denials are most of what anyone opens an audit log for; without the column they cannot be written at all.
+- **Keep the columns product-neutral** — `actor_*` · `action` · `outcome` · `target_*` · `scope_path` · `channel` · `source_ip` · `correlation_id` · `changes_json` serve any domain. Per-level tenancy columns tie the log to today's model; a materialized `scope_path` (`workspace:abc/app:def`) makes "everything under this tenant" one prefix scan and survives a new level appearing — at the price of enforcing the hierarchy in code rather than a `CHECK`.
+
+## Scope, not parallel tables
+
+One entity that exists at several scopes is **one table with a nullable scope column** — never one table per scope, and never one table shared across entity families.
+
+- **A table shared by several families carries the union of their columns** — one `settings` table for users, apps, and workspaces. Almost nothing can be `NOT NULL`, the payload lands in JSON beyond every constraint, index, and FK, and a new family widens a table other features already depend on. One table per family.
+- **Two tables declared to have "the same columns" are two schemas maintained by hand** — the drift is silent, surfacing as an incomplete copy, never as an error. Collapse them and discriminate by column.
+- **The scope column is the discriminator** (`app_id IS NULL` = parent scope, set = child scope). Copying a scope is then `INSERT … SELECT` over one table with one column rewritten, so source and target cannot disagree about shape.
+- **A nullable owner column is how a row exists before its owner does** — a pending enrolment or unclaimed record is creatable before the owner is known, which is what lets a `pending_*` / `*_requests` table collapse into the real one.
+- **A reserved row can own the shipped defaults.** A fixed-id "system" parent makes the defaults and a tenant's copy the same kind of row, through the same code. It must then be excluded from every tenant-scoped query — state that invariant where the id is defined.
+
+## Copying rows between scopes
+
+- **A copied junction row is already correct with no remapping** — its endpoints are `slug` references (§ Keys & the shared vocabulary), and a slug means the same thing in every scope. Rewriting ids through a source→copy map is the most error-prone step in a multi-level copy, and a partial failure leaves wiring pointed into another scope rather than raising.
+- **Provenance is a soft reference — no FK.** `source_id` must outlive its referent; an FK would either block the source's deletion or erase the lineage.
+- **Store the source's version at copy time** — `version` + `source_version` make "is an upgrade available" a comparison of two stored values, not a content diff.
+- **A copy is a row, never a live read.** Nothing at the child scope reads the parent's row at runtime; propagation happens only through an explicit re-copy, so a local edit is never silently overwritten.
+
+## A junction spells many-to-many — nothing else
+
+**A `_map` table is the schema's notation for M:N. Using it for 1:M is a category error** — the junction's own uniqueness admits many parents per child, so the "one parent" rule stops being enforced the moment it is written this way. Cardinality decides between the only two shapes:
+
+| Relationship | Shape |
+| --- | --- |
+| **1:M** — the child has exactly one parent | a **reference column on the child** (`agents.routing_slug`), plus an index |
+| **M:N** — both sides have many | a **`<a>_<b>_map` junction** with a composite unique |
+
+- **The test is one question about the child**: can this row ever belong to two parents at once? No ⇒ column. A junction "in case it becomes M:N later" ships the unenforced model today to buy a migration you may never run.
+- **A junction for a 1:M also** makes the association a row that can go missing independently of the child — a child can exist correctly while its wiring does not — and forces a join onto the most common read in the system.
+- **A junction carrying only its two endpoints and timestamps is the tell** — a real M:N junction usually earns its own columns (a role, an order, a status); one that never does is a 1:M waiting to be collapsed into a column.
+- **Collapsing deletes a copy step** — the association travels inside the row it belongs to: no second pass to remap, no copy landing with its wiring half-applied.
+- **A pair already recorded elsewhere needs no table at all.** If an append-only log stores `(parent, child)` on every write, the association table is `SELECT DISTINCT` over that log — a cache free to disagree with the log it derives from (§ What earns a table).
+
+## Foreign keys into and out of append-only tables
+
+**An append-only table can afford no `ON DELETE` action at all, so its references to mutable tables are soft — no FK.** Every option is closed to it:
+
+| Action | Why it fails on an append-only table |
+| --- | --- |
+| `SET NULL` | It is an **UPDATE**. An append-only trigger aborts it, so the parent's deletion fails — with an error naming the trigger, not the constraint. |
+| `CASCADE` | Deletes history to delete a person. The log exists precisely to outlive its subjects. |
+| `NO ACTION` | Makes anyone who ever appeared in the log undeletable — the hub defect above. |
+
+- **`SET NULL` is the trap** — it reads like a safe relaxation of `NO ACTION` and passes review as one.
+- **Record the actor as a plain column** — the same soft-reference treatment provenance gets (`source_id`, `thread_id`). The log keeps naming who acted after the account is gone, which is what an audit trail is for.
+- **`CASCADE` from the append-only side's own parent is still fine** — a cascade is a DELETE, so a `BEFORE UPDATE` trigger never sees it: an App's log dying with the App is legitimate, distinct from erasing a log to delete a person.
+- **State the exemption where it exists.** A catalog whose rows must not disappear under a referencing row (a service definition, a vocabulary) keeps `NO ACTION` deliberately — that guarantee is worth one line saying so.
+
+## Uniqueness with a nullable column
+
+**`UNIQUE (a, b)` does not constrain rows where `b` is `NULL`** — SQL treats every `NULL` as distinct, so a composite unique over a nullable discriminator silently permits exactly the duplicates it was introduced to keep apart. Write one partial index per scope instead:
+
+```sql
+CREATE UNIQUE INDEX <t>_parent_slug_unique ON <t> (parent_id, slug) WHERE child_id IS NULL;
+CREATE UNIQUE INDEX <t>_child_slug_unique  ON <t> (child_id, slug)  WHERE child_id IS NOT NULL;
+```
+
+**Prove a uniqueness claim by inserting the duplicate it forbids** — a schema review cannot tell a firing index from a silent one by reading.
+
+## Vocabulary / lookup tables
+
+A controlled vocabulary earns a **table** only when a user row FKs into it and reads its `label` / `description` at runtime — a service catalog rendered in a picker; static dev-authored config nobody references by FK stays **config** (§ What earns a table) — a `doc_type` value list. Enumerable is not tabular, and a `type`-style column validated against the constants file beats an FK to a seeded mirror. An earned table has a fixed shape: `id` (UUID) · `slug` (UNIQUE) · `label` · optional `description` · `status` · timestamps.
+
+- **Seeds are generated, never hand-written** — the source of truth is a CSV or a shared package; a generator emits the `*.seed.sql` with UUIDv5 ids and an idempotent `ON CONFLICT(slug)` upsert that preserves live counts / admin-tuned columns. ❌ Hand-editing seed SQL — regenerate it.
+
+## Run
+
+1. **Route every new fact through § What earns a table** — default to *not* a table; name the left-column property that earns one, or the right-column home it takes instead.
+2. **Classify every fact by § State, rules, and history** — now-state → entity column; rules → code; what-was-done → audit log; replayable → sequence log.
+3. **Check cardinality before any junction** (§ A junction spells many-to-many) and every FK's `ON DELETE` (§ Keys, § Append-only).
+4. **Prove uniqueness claims by inserting the forbidden duplicate** — a schema review cannot tell a firing index from a silent one by reading.
+5. **Report as a findings list** — one line per violation: the section, the table/column, the fix.