# DESIGN-SYSTEM-SPEC.md
**Contract for the PURE Design System registry + its auto-build cron.** Lane A (Design) owns the component files + the hub (`/pure-components.html`); Code owns the registry table, RPCs, and cron. Contract-first, idempotent, reversible.

Project `mbnakfrkfwxinhxlisyq` · branch `Testin.MikeSupabase`. Hub is admin-gated. The `pure_components` registry **doubles as the shared-globals registry for `mcp_contract_check`** (two files claiming one `window.*` global = fail the pre-push gate — this is what would have caught the `pure-table.js` collision).

---

## 1. Table — `public.pure_components`
The hub reads this directly (`GET /pure_components?select=*&order=pri.asc`) and merges live rows over its built-in `DS_REGISTRY` seed by `id`. Fail-soft until it exists.

```sql
create table if not exists public.pure_components (
  id         text primary key,                 -- slug, e.g. 'toggles'
  cat        text not null default 'Core UI',  -- one of the hub CATS
  name       text not null,
  file       text default '',                  -- canonical file that owns it (e.g. 'pure-controls.js')
  global     text default '',                  -- window.* it registers, if any (feeds contract-check)
  status     text not null default 'queued'    -- 'done' | 'build' | 'queued'
               check (status in ('done','build','queued')),
  pri        int  default 99,                  -- build order for the cron (lower first)
  desc       text default '',
  link       text default '',
  owner_hat  text default 'Design',
  updated_at timestamptz not null default now(),
  updated_by text default 'system'
);
alter table public.pure_components enable row level security;
create policy pc_read on public.pure_components for select using (auth.role()='authenticated');
grant select on public.pure_components to authenticated;
-- writes via the RPCs below only
```
Seed = the ~54 rows in the hub's `DS_REGISTRY` (id/cat/name/file/status/pri/desc). `on conflict (id) do nothing` so re-runs never clobber admin edits.

## 2. RPCs (gated, audited)
| RPC | Args | Effect |
|---|---|---|
| `mcp_ds_next` | *(none)* | returns the lowest-`pri` row where `status='queued'` (the next to build). |
| `mcp_ds_stage` | `p_id` | mark `status='build'`, audit. Cron calls this when it picks an item + scaffolds a stub file. |
| `mcp_ds_complete` | `p_id, p_file, p_global` | mark `status='done'`, set file/global, audit. Called when the component ships + verifies. |
| `mcp_ds_upsert` | `p_id,p_cat,p_name,p_file,p_status,p_pri,p_desc,p_link` | admin edit from Component Studio. |
| `mcp_contract_check` | *(none)* | for each row with a non-empty `global`, verify exactly one live file registers it; fail on dup/missing. Add to the pre-push gate + a nightly cron. |

## 3. Cron — `design_system_autobuild`
- **Schedule:** every 4h, **off-hours only 8pm–8am CT**, via `mcp_cron_ct_window(hour,dow)` (Code's DST-correct gate). ~3 runs/night.
- **Body (one item per run):** `mcp_ds_next` → if none, exit. Else `mcp_ds_stage(id)` → post a board ticket `ds-<id>` (title, acceptance = "canonical file + hub row done + no console errors + contract-check passes") → notify the design lane. When the agent/Poppy ships the file and it verifies, call `mcp_ds_complete(id,file,global)`. **Never batch** — strictly one build in flight; the hub's "Next" + progress bar reflect the queue.
- **Stop condition:** runs until every row is `done` (queue clear), then no-ops.

## 4. The reusable pattern — `queue_cron_autobuild` (commit to `pure_memory.routine`)
Generalize this for **any** big backlog, not just components:
> **Scope the whole list into a registry table → order by priority → a cron works it ONE item per run, off-hours → do → stage → complete → repeat → until clear.** Control surface = the relevant hub (admin-editable). Reuse for: design-system components (`pure_components` / `design_system_autobuild`), security level-ups (`pure_security_posture`), standards sweeps, and future queues. Same shape every time: `*_next / *_stage / *_complete` + an off-hours CT-gated cron.

## 5. Change log
- 2026-06-30 — Lane A: hub registry (~54 items, 20 done) + auto-build control live at `/pure-components.html`; `pure_components` greenfield (no collision). FE fail-soft until table + RPCs land.