@terreno/mcp 57.19.2 → 57.21.0

package/src/docs/versioned/57.20.0/implementationPlans/charts-and-dashboards.md

@@ -0,0 +1,247 @@
+# Implementation Plan: Charts and dashboard primitives
+
+**Status:** In progress  
+**Branch:** `cursor/charts-and-dashboards-2bc3`  
+**Owner:** —  
+**Created:** 2026-09-10  
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1175 (this feature **closes** that issue; implementation PRs use `Fixes #1175`)  
+**Task list:** [charts-and-dashboards.md](../tasks/charts-and-dashboards.md)  
+**Depends on:** —  
+**RTK deprecation flag:** None  
+**Program:** [B2B platform](b2b-platform-program.md) track E  
+
+## Goal
+
+Ship themed, universal chart and dashboard layout primitives in `@terreno/ui` so B2B
+admin and product screens can compose line, bar, area, and donut charts without a
+third-party chart API leaking into app code.
+
+Rendering is **owned SVG** on `react-native-svg` (already used for icons). Public
+components are `LineChart`, `BarChart`, `AreaChart`, `DonutChart`, and `DashboardGrid`.
+Proof is demo stories plus docs. No example-frontend screen and no comms-dashboard
+wiring in this slice.
+
+## Non-Goals
+
+- `victory-native`, Skia canvas charts, `react-native-gifted-charts`, `react-native-chart-kit`, WebView/ECharts.
+- Example-frontend dashboard screen.
+- Comms admin stats charts (comms IP already defers to this item; a later comms task consumes these primitives).
+- Zoom, pan, brush, stacked/grouped multi-series cartesian, combo charts, maps, heatmaps.
+- A new `DashboardCard` (reuse `Card`).
+- Dark-mode palette work (`dark-mode-theme`); charts read `useTheme()` so they follow when that ships.
+- Implementing the approved composition grammar in the visual-regression slice (Phase 6).
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| Public exports | Named `LineChart`, `BarChart`, `AreaChart`, `DonutChart`. No `Chart` dispatcher. Remove the commented `export * from "./Chart"` stub. |
+| First consumer | Demo stories only. |
+| Interactivity | Legend plus press (native) / hover (web) tooltip. No zoom/pan. |
+| Dashboard layout | `DashboardGrid` with responsive column counts; children are existing `Card`s. |
+| Engine | Owned `react-native-svg` primitives in `@terreno/ui`. Not victory-native, not a wrap. |
+| Series model | Single series this slice: `data: {label: string; value: number}[]`. Donut uses the same points as slices (`color?` optional per slice). Multi-series cartesian is future work. |
+| Math | Private `d3-scale` + `d3-shape` in `ui/` only (single-package; raw versions, not catalog unless a second package needs them). Do not export d3 types. |
+| Axis labels | Overlay `@terreno/ui` `Text` (theme fonts). Do not draw axis copy with SVG `<Text>` as the primary path. |
+| Tooltip chrome | Terreno `Tooltip` when a mark can be the child; otherwise an internal overlay `Box`+`Text` at the hit point with the same copy (`label: value`). |
+| Empty / loading | Empty `data` → `Text` (`emptyText`, default `"No data"`). `loading` → `Spinner`. |
+| Colors | Theme tokens: series/slice fills from `primary` / `secondary` / `accent` / `error` (and tints). Grid/axis from `border` / `text.secondaryDark`. Optional `color` on a donut slice overrides. |
+| Packaging | Chart components join the existing lazy root boundary (`heavyOptionalExports`). `DashboardGrid` stays eager (layout only). Subpaths `@terreno/ui/LineChart` etc. remain direct. |
+| Dates | `label` is a display string. Callers format with Luxon before passing. No `Date` objects in props. |
+| Visual proof | Rendered PNG goldens via `bun run ui:charts:compare`, not React JSON snapshots. |
+
+## Architecture
+
+```
+@terreno/ui
+  LineChart / BarChart / AreaChart / DonutChart
+    ChartFrame (Box + sized Svg + overlay Text axes + legend + tooltip)
+      charts/scales.ts   d3-scale linear / band (private)
+      charts/paths.ts    d3-shape line / area / arc (private)
+      charts/theme.ts    useTheme → stroke / fill / grid / axis
+  DashboardGrid
+    Box wrap + width percent from breakpoint column count
+```
+
+### Public props (minimal)
+
+```typescript
+interface ChartPoint {
+  label: string;
+  value: number;
+  color?: string; // donut slice override
+}
+
+interface CartesianChartProps {
+  data: ChartPoint[];
+  height?: number; // default 200
+  legendLabel?: string;
+  emptyText?: string;
+  loading?: boolean;
+  accessibilityLabel?: string;
+  testID?: string;
+}
+
+interface DashboardGridProps {
+  columns?: {sm?: number; md?: number; lg?: number}; // default 1 / 2 / 3
+  gap?: SignedUpTo12;
+  children: React.ReactNode;
+  testID?: string;
+}
+```
+
+Cartesian charts share `CartesianChartProps`. `DonutChart` uses the same `data` as slices
+(ignore `legendLabel`; legend is one row per slice).
+
+Layout: `Box` around an `Svg` with a stable `viewBox`. Plot geometry is SVG. Tick labels
+sit in `Box` rows/columns around the plot so Nunito/Titillium apply. Legend is a wrapping
+`Box` of color swatch + `Text` below the plot.
+
+Hit testing: map press/hover location to the nearest point (cartesian) or slice (donut).
+Web uses hover in; native uses press. Tooltip copy is `{label}: {value}` (no extra
+formatting unless `value` is shown with a caller-supplied `formatValue?: (n) => string`,
+default `String(n)`).
+
+### File layout
+
+| Path | Role |
+|------|------|
+| `ui/src/charts/types.ts` | `ChartPoint` and shared props (not a public barrel) |
+| `ui/src/charts/scales.ts` | Private scale helpers + unit tests |
+| `ui/src/charts/paths.ts` | Private path helpers + unit tests |
+| `ui/src/charts/theme.ts` | Theme → paint |
+| `ui/src/charts/ChartFrame.tsx` | Shared frame (not exported from package root) |
+| `ui/src/LineChart.tsx` | Public line |
+| `ui/src/BarChart.tsx` | Public bar |
+| `ui/src/AreaChart.tsx` | Public area |
+| `ui/src/DonutChart.tsx` | Public donut |
+| `ui/src/DashboardGrid.tsx` | Public grid |
+| `ui/src/index.tsx` | Eager `DashboardGrid`; lazy chart named exports |
+| `ui/src/lazyBoundaries/heavyOptionalExports.tsx` | Chart lazy factories |
+| `ui/package.json` | `d3-scale`, `d3-shape` (+ types) |
+
+No `ui/src/charts/index.ts` barrel (Biome `noBarrelFile`).
+
+### Dependencies
+
+`react-native-svg` is already a `ui` dependency. Add `d3-scale` and `d3-shape` to `ui/`
+only. Do not add `victory-native`. Import-benchmark and `RootImportRegression` must show
+chart implementation modules off the cold `@terreno/ui` root graph (same pattern as
+`GPTChat`).
+
+### Chart visual regression
+
+JSON snapshots of the React tree do not prove paint. The demo hosts
+`/demo/chart-visual-gallery` (easy → hard fixtures in
+`demo/chartVisual/fixtureCatalog.ts`). `bun run ui:charts:compare` launches Chromium,
+screenshots each `[data-testid=chart-visual-<id>]`, and pixel-diffs against
+`demo/rendered-snapshots/<id>.png`. Failures write
+`demo/chart-visual-output/{actual,diff,report.json}`. Agents follow
+`review-chart-visuals`. `bun run ui:charts:update-snapshots` rewrites goldens after an
+intentional visual change.
+
+### Testing
+
+Bun + `@testing-library/react-native` + `renderWithTheme`. Assert:
+
+- Empty and loading states by text / `testID`.
+- One mark per `data` item (`testID` suffix by index or label).
+- Tooltip copy after press (native) or hover where the test renderer allows.
+- Legend label / slice labels.
+- Scale/path helpers with numeric fixtures (no renderer).
+- `DashboardGrid`: child count and `testID`; width math via style when observable.
+
+Do not mock `react-native-svg` unless a helper is untestable; prefer querying `testID`s
+on wrapper `Box`es if SVG nodes are opaque in happy-dom.
+
+### Demo
+
+Stories: `LineChart`, `BarChart`, `AreaChart`, `DonutChart`, `DashboardGrid` (grid of
+`Card`s each holding a chart). Register in `demoConfig.tsx` so the demo coverage
+allowlist passes. Static fixture data only.
+
+## Models / APIs / Notifications
+
+None.
+
+## UI
+
+Universal React Native + web. No admin-v2 `home.slots` work. Comms dashboard is a future
+consumer, not this IP.
+
+## Phases
+
+1. **Tracer:** private scales/paths/theme + `LineChart` (tooltip, legend, empty/loading) +
+   tests + demo story + reference stub.
+2. **Sibling charts:** `BarChart`, `AreaChart`, `DonutChart` on the same frame.
+3. **DashboardGrid** + composing demo story.
+4. **Packaging + docs:** lazy root exports, import regression, Diátaxis pages, TypeDoc,
+   changelog fragment, seed links, rules/skill mentions.
+5. **Rendered visual regression:** gallery + compare command + `review-chart-visuals` skill.
+6. **Composition grammar (approved, not this slice):** declarative children (`Chart`,
+   `ChartTitle`, cartesian/polar, series, axes, grid, legend, tooltip, data labels,
+   reference line/band). Keyed rows + `dataKey`. Facades stay additive `{label,value}`.
+   Tooltip overlay + footer (facades keep footer). Colors: theme tokens + hex.
+   `data`/`xKey` on `Chart`/`ChartCartesian`/`ChartPolar`. Grouped bars unless `stackId`.
+
+## Feature Flags & Migrations
+
+None. Additive public components. Not a major.
+
+## Activity Log & User Updates
+
+None.
+
+## Not Included / Future Work
+
+- Ops-dashboard parity (scorecards, comparison sparklines, additive multi-series, donut centers, spanning grid, table chrome) — [`dashboard-chart-parity.md`](dashboard-chart-parity.md).
+- Composition grammar (Phase 6) — recorded Grow decisions; implement on a follow-up Pick. Not required for the How’s it going dashboard.
+- Multi-series cartesian via additive `series` lands in `dashboard-chart-parity`; grammar `dataKey` / `stackId` remains later.
+- Wiring `CommsDashboardScreen` charts to the stats endpoint.
+- Example-frontend dashboard.
+- Zoom/pan.
+- Victory/Skia renderer if a later product needs GPU-scale series (thousands of points).
+
+## Files to Create / Modify
+
+See the task list. Docs created or updated in-slice:
+
+- `docs/how-to/charts-and-dashboards.md` (create)
+- `docs/how-to/README.md` (link)
+- `docs/explanation/charts.md` (create — why owned SVG, not victory-native)
+- `docs/explanation/README.md` (link)
+- `docs/reference/ui.md` (Display exports + example)
+- `docs/explanation/roadmap-seed-issues.md` (`charts-and-dashboards` IP/task links)
+- `docs/implementationPlans/b2b-platform-program.md` / `comms-admin-dashboard.md` (pointer only if they still say “charts later” without a path)
+- `.rulesync/rules/ui/00-ui.mdc` (export list)
+- `changelog/unreleased/charts-and-dashboards.md`
+- TypeDoc props so `docs-audit` is clean after `bun run website:generate`
+
+## Task List
+
+[docs/tasks/charts-and-dashboards.md](../tasks/charts-and-dashboards.md)
+
+## Acceptance Criteria
+
+- [ ] `LineChart`, `BarChart`, `AreaChart`, `DonutChart`, and `DashboardGrid` are
+      importable from `@terreno/ui` and from component subpaths.
+- [ ] Charts render with `react-native-svg`; `victory-native` is not a dependency.
+- [ ] Single-series `{label, value}[]` is the only cartesian data contract.
+- [ ] Empty and loading states are visible; tooltip + legend work (press native, hover web).
+- [ ] Theme tokens drive default paints; overlay axis labels use `Text`.
+- [ ] Chart implementations are lazy on the package root; `DashboardGrid` is eager.
+- [ ] Focused bun tests cover scales, empty/loading, mark counts, tooltip copy, grid columns.
+- [ ] Demo stories exist for all five exports and are registered.
+- [ ] How-to, explanation, and `docs/reference/ui.md` describe the API; TypeDoc props exist.
+- [ ] `bun test` (ui affected files), `bun run compile` in `ui`, and demo compile succeed.
+- [ ] Frontend verification: demo stories exercised on web; artifacts on the implementation PR.
+- [x] `bun run ui:charts:compare` matches `demo/rendered-snapshots/` for the gallery.
+
+## Risks
+
+| Risk | Mitigation |
+|------|------------|
+| happy-dom SVG nodes hard to query | `testID` on `Box` wrappers around marks; helper unit tests for path strings |
+| Hover vs press tooltip | Shared hit-test helper; platform-specific event wiring; tests cover press at minimum |
+| Root import size | Lazy boundary + `performance:imports` / `RootImportRegression` |
+| d3 + RN types | Confine d3 to `charts/scales.ts` and `charts/paths.ts` |

package/src/docs/versioned/57.20.0/implementationPlans/circleci-pr-speed-loop.md

@@ -0,0 +1,293 @@
+# Implementation Plan: CircleCI PR Speed Loop
+
+**Status:** In progress — iteration 0 (instrumentation) in review; iteration 1 picks the first lever
+**Owner:** Josh
+**Goal:** cut CircleCI wall-clock time for an **average PR** by **40% (≤ 5.7 min)**
+or to **under 4 min**, whichever comes first, without weakening any gate.
+**Driver:** run as a long-lived loop. `/terreno-scan:loop` with this document as
+the charter fits. Each iteration ships one PR-sized change through Pick → Roast →
+Brew → Taste.
+
+## Metric
+
+**PR CI wall clock:** from the first `ci/circleci:` status on a PR's head commit
+to the last terminal status of a test or build job. Excluded from the end time:
+`approve`, `architectural-pr-review`, `dco`, `deploy-*` previews, and
+`serial-*` deploy-group statuses. Those are review bots and previews, not tests.
+
+**Average PR:** a merged PR that touches **≤ 3 top-level directories**, not
+counting `docs/`, `website/`, or dot-directories (so `changelog/` counts).
+44 of the last 60 merged PRs qualify, and the median PR touches 2. PRs touching more than 3
+directories are tracked but do not count toward the goal.
+
+**Reported value:** the median over the last 20 qualifying merged PRs, plus the
+median of the benchmark set (below) for each experiment.
+
+### Baseline (last 60 merged PRs, measured 2026-10-25)
+
+| | Median | p25 | p75 |
+|---|---|---|---|
+| Average PRs (≤ 3 directories, n = 44) | **9.5 min** | — | — |
+| All PRs (n = 60) | 10.3 min | 5.9 min | 12.1 min |
+
+**Target:** median ≤ **5.7 min** (40% faster). If it gets there, keep going
+toward **≤ 4.0 min** only while iterations still pay off (see stop rules).
+
+Job that finished last on average PRs:
+
+| Job | PRs where it was last | Median duration | Median start after pipeline start |
+|---|---|---|---|
+| `e2e-app` | 13 / 44 | 4.0 min | 6.3 min (waits on `e2e-prepare`, 5.4 min) |
+| `api-ci` | 10 / 44 | 10.8 min | 1.0 min |
+| `repo-policies` | 5 / 44 | — | — |
+| `mcp-server-docker` | 4 / 44 | — | — |
+| `maestro-e2e` | 3 / 44 | 8.9 min | 0.9 min |
+| `new-file-coverage` | 3 / 44 | 3.5 min | 0.5 min |
+
+Other long jobs that can become last once these shrink:
+
+| Job | Median duration |
+|---|---|
+| `example-backend-docker` | 7.6 min |
+| `admin-spa-integration` | 6.0 min |
+| `ai-ci` | 5.9 min |
+| `admin-spa-ci` | 4.9 min |
+| `example-backend-ci` | 4.3 min |
+
+The setup workflow (path filtering plus continuation) costs about 0.6–1.0 min
+before any job starts. The 4-minute target needs that cut too.
+
+## Guardrails
+
+The loop may change anything in CI: config, resource classes, caching,
+parallelism, job graph, test runners, and test code. It may **not**:
+
+1. Delete, skip, or `.skip` a test. The one exception is a selection mechanism
+   (TIA, path filtering, the e2e affected gate) whose shadow run proves zero
+   misses over at least 2 weeks.
+2. Lower a coverage threshold, or move a blocking gate to post-merge. That
+   covers the 95% package gate, the 90% new-file gate, Knip zero findings, the
+   dependency-cruiser baseline, lint, and typecheck.
+3. Mark a flaky test as allowed-to-fail. Fix it or quarantine it with a
+   tracking issue, and count the quarantine as a regression for this goal.
+4. Make `master` or release pipelines less safe. `master` still runs
+   everything.
+5. Raise CircleCI spend more than **25%** per average PR without Josh's
+   approval. Report credits per average PR in every iteration.
+
+## The loop
+
+Each iteration is one PR. Keep going until a stop rule fires.
+
+1. **Measure.** Run `bun run ci:wall-clock --limit 20` for the rolling median
+   and the last-job histogram. Pull per-job step timings from
+   the CircleCI API (`CIRCLECI_TOKEN`; slug in `docs/how-to/circleci.md`) for
+   the top 2 critical-path jobs.
+2. **Pick the lever.** Take the job that is most often last. Choose the
+   highest-expected-gain lever for it from the backlog, or a new one found in
+   step 1. Write the hypothesis in the ledger, e.g. "caching the `bun install`
+   store cuts `api-ci` by 50 s".
+3. **Build it** on `ci-speed/<n>-<slug>` with Pick → Roast. Config changes
+   need `scripts/check-circleci-parity` and `circleci config validate` to pass.
+4. **Benchmark.** Run the [benchmark set](#benchmark-set) against the branch
+   and against `master` in the same hour, 2 runs each. The result is the
+   median of each case's median.
+5. **Decide.**
+   - **Keep:** benchmark median improves by **≥ 5%** (≈ 30 s) with every
+     guardrail intact. Brew → Taste → merge.
+   - **Drop:** under 5%, or any guardrail broken. Record why in the ledger and
+     close the PR.
+6. **Re-measure** after merge on the next 20 qualifying real PRs. Update the
+   ledger and the baseline table.
+7. **Loop.**
+
+### Stop rules
+
+- **Done:** the rolling real-PR median is ≤ 5.7 min (or ≤ 4.0 min) for 20
+  qualifying PRs in a row. Post a final report.
+- **Stalled:** 3 iterations in a row each gain under 5%. Escalate to Josh with
+  the current critical path, the levers tried, and the next options with their
+  cost (e.g. bigger resource classes, a paid feature, dropping a job from PRs
+  with proof).
+- **Blocked:** a lever needs a guardrail exception or a spend increase over
+  25%. Ask Josh.
+
+### Benchmark set
+
+Five recent average PRs whose code still reverts cleanly on `master`. They
+cover the jobs that most often finish last (`api-ci` and the e2e chain). Refresh
+them with `bun run ci:bench --suggest-cases` every 10 iterations, or sooner when
+a case replays as `invalid`.
+
+| Case | Shape | PR |
+|---|---|---|
+| `api-only` | `api` feature (plus changelog and docs) | #1491 |
+| `api-syncdb` | `api` plus `syncdb` | #1555 |
+| `ui-only` | `ui` component fix | #1567 |
+| `admin-example` | `admin-frontend` plus `example-frontend` | #1540 |
+| `small-package` | `create-terreno-app` | #1599 |
+
+Mechanics: `bun run ci:bench --branch <branch> --label <iteration>` (see
+[benchmark a CI change](../how-to/circleci.md#benchmark-a-ci-change)). For each
+case it opens two draft PRs labelled `ci-bench`, waits for CircleCI to settle,
+records the metric, and closes both PRs:
+
+- **Control:** `master` with the case's code hunks reverted.
+- **Treatment:** the branch under test with the case's code hunks reverted.
+
+The case list lives in `scripts/ci/bench/cases.ts`.
+
+### Ledger
+
+Append one row per iteration. Never edit past rows.
+
+| # | Date | Lever | Target job | Bench before → after | Real-PR median after | Credits/avg PR | Kept? | PR |
+|---|---|---|---|---|---|---|---|---|
+| 0 | 2026-10-25 | Baseline | — | — | 9.5 min | TBD | — | — |
+| 0 | 2026-10-26 | Instrumentation (`ci:wall-clock`, `ci:bench`) | — | `api-only` on master: 11.6 min (1 run, last job `api-ci`) | 9.5 min | TBD (needs CircleCI token) | Yes | this PR |
+
+## Lever backlog
+
+The order is a starting point. Re-rank every iteration from fresh step
+timings.
+
+### Iteration 0 — Instrumentation (½ day, required first)
+
+- Add `bun run ci:wall-clock` (`scripts/ci/ciWallClock/`), with tests, from
+  the measurement used for the baseline above.
+- Add `bun run ci:bench` (`scripts/ci/bench/`).
+- Pull step-level timings for `api-ci`, `e2e-prepare`, `e2e-app`,
+  `maestro-e2e`, and `example-backend-docker`. Record how much of each is
+  checkout, `bun install`, dependency compile, lint, typecheck, and tests.
+
+### e2e chain (`e2e-prepare` 5.4 min → `e2e-app` 4.0 min)
+
+- **Cache the Expo web export**, keyed on a hash of the inputs it reads
+  (`example-frontend`, the workspace packages it bundles, `bun.lock`). On a
+  hit, `e2e-prepare` skips `bun expo export`. The e2e affected gate already
+  computes the reachable input set (`scripts/ci/e2eAffected`), so reuse it for
+  the cache key.
+- Build `e2e-prepare` in parallel with lint and compile, not after them, and
+  start shards as soon as their artifact exists.
+- Rebalance or split `e2e-app`, the slowest shard, using Playwright timing
+  data. Static splitting is free with `circleci testsuite`.
+
+### `api-ci` (10.8 min)
+
+- Split lint, typecheck, and tests into parallel jobs. The test step alone is
+  about 4 min locally.
+- Static test splitting across `parallelism: 2–3` nodes. This needs the
+  coverage-splice work below, so each node's LCOV can combine into one exact
+  report.
+- Make every test file pass alone. 10 `api` files fail today, mostly 5 s
+  `beforeAll` timeouts. Splitting and TIA both need this.
+- **Test impact analysis**, piloted as described in
+  [Appendix A](#appendix-a--smarter-testing-findings). The simulation selects
+  about 46% of `api` test time on a typical PR.
+
+### Every job
+
+- Cache the `bun install` store. All jobs install without a cache today.
+- Cache workspace `dist/` output from `compile_packages`, keyed by each
+  package's source hash.
+- Right-size resource classes for jobs on the critical path. `large` costs
+  2× `medium` credits per minute but can halve CPU-bound steps. Check against
+  guardrail 5.
+- Shorten the setup workflow: path filtering plus continuation takes about
+  0.6–1.0 min.
+
+### `maestro-e2e` (8.9 min), `example-backend-docker` (7.6 min), `admin-spa-integration` (6.0 min)
+
+- Reuse the Expo export cache from the e2e chain in `maestro-e2e` and
+  `admin-spa-integration`.
+- Tighten path filters. Check these run only when their inputs change.
+- `example-backend-docker`: make better use of layer cache through BuildKit
+  `--cache-from` on a registry image. Docker Layer Caching costs 200 credits
+  per job, so compare costs first.
+
+## Appendix A — Smarter Testing findings
+
+Source docs:
+[get started](https://circleci.com/docs/guides/test/getting-started-with-smarter-testing/),
+[test impact analysis](https://circleci.com/docs/guides/test/set-up-test-impact-analysis/),
+[`test-suites.yml` reference](https://circleci.com/docs/reference/testsuite-configuration-reference/),
+[overview and credit charge](https://circleci.com/docs/guides/test/smarter-testing-overview/).
+
+**How it works.** `.circleci/test-suites.yml` defines suites with `discover`
+(lists test atoms, here files) and `run` (gets `<< test.atoms >>` and writes
+`<< outputs.junit >>`). An optional `analysis` command is the run command with
+coverage, writing `<< outputs.lcov >>` one atom at a time. The job step becomes
+`circleci testsuite run "<suite>"`, run from the package root.
+
+- **Analysis** runs on `master` and records which files each atom covers.
+- **Selection** runs on PRs. It runs new atoms, atoms that failed last time,
+  and atoms whose covered files changed. `full-test-run-paths` and
+  `test-selection-rules` cover what coverage cannot see.
+- **Free:** `testsuite run`, static splitting, rerun-only-failed, and test
+  uploads.
+- **Charged:** TIA, dynamic splitting, dynamic parallelism, and auto-rerun, at
+  3,000 credits per 100k atoms above the plan allowance. Estimated $1–3 a month
+  for us.
+
+**Bun compatibility (verified locally).**
+`bun test --reporter=junit --reporter-outfile=…` writes JUnit, and
+`bun test --coverage --coverage-reporter=lcov --coverage-dir=<dir> <atom>`
+writes a usable LCOV. Bun writes to a directory, so `analysis` needs a wrapper
+that moves `lcov.info` to `<< outputs.lcov >>`.
+
+**Selection simulation.** I ran each `api` and `ui` test file alone with
+coverage, then replayed the last 60 PR merges per package (version bumps
+excluded):
+
+| | `api` | `ui` |
+|---|---|---|
+| Atoms | 149 | 201 |
+| Full suite, local | 3 m 49 s | 1 m 14 s |
+| Analysis, one atom at a time | 17 min serial | 55 s at 4-way |
+| Atoms failing when run alone | 10 | 1 |
+| PRs forced to a full run | 19 / 60 | 14 / 60 |
+| Mean / median share of test time selected | 46% / 39% | 43% / 43% |
+
+Hub files limit the savings. In `api`, `logger.ts` and `requestContext.ts`
+are covered by 149/149 atoms and `errors.ts` by 131. Coverage also cannot see
+across packages: every `bunfig.toml` ignores `../**` and dependencies resolve
+to `dist/`. Each downstream suite therefore needs `full-test-run-paths` for
+its upstream packages. Whether paths outside the CLI's working directory are
+allowed must be checked with `circleci testsuite doctor`.
+
+**Coverage splicing (keeps gates blocking and exact).** The PR job builds a
+whole-package LCOV, then runs the unchanged 95% gate, the 90% new-file gate,
+and the Codecov upload on it.
+
+- **Changed files** (vs merge base) come from the PR's selected run. All atoms
+  covering them run in one `bun test` process, so those files are exact.
+- **Unchanged files** come from `master`'s full-run LCOV at the merge base,
+  using the per-file maximum with the PR run.
+- **Wiring:** `master` saves `coverage/lcov.info` via `save_cache`, keyed
+  `cov-base-<pkg>-{{ checksum "base-sha.txt" }}`. The PR job writes the merge
+  base to `base-sha.txt` and restores that key.
+- **Fallback:** if there is no baseline, or a full-run path changed, run the
+  full coverage suite as today.
+
+Why per-file and not per-atom: Bun reports a different set of instrumented
+lines per process, and writes only `FNF`/`FNH` totals, not which functions
+ran. Merging the 149 per-atom `api` reports gave 95.24% functions vs 98.95%
+real.
+
+Validated on `ui`: baseline at `7fc9843c^`, PR at HEAD, 9 changed files,
+16/201 atoms selected (7.9 s vs 74 s). The spliced report matched the full run
+exactly: 211/211 files, lines 99.25% = 99.25%, functions 98.61% = 98.61%.
+
+Known gap: an unchanged file can lose coverage when a changed file stops
+calling it. The `master` full run catches this right after merge and must
+comment on the PR.
+
+**TIA pilot steps (when the loop picks this lever).**
+1. Add the suite with `test-impact-analysis: true`,
+   `test-analysis-duration: 20`, and `full-test-run-paths`. Run analysis as a
+   non-blocking `master` job.
+2. Shadow it on PRs for 2 weeks. `list-tests` records what would be selected,
+   while the full suite still runs. Compare spliced LCOV against full LCOV,
+   file by file.
+3. Make it blocking only with zero selection misses, zero splice mismatches,
+   and a median test-step saving of at least 40%.

package/src/docs/versioned/57.20.0/implementationPlans/collection-registry.md

@@ -0,0 +1,133 @@
+# One collection registry
+
+**Status:** Complete  
+**Branch:** `cursor/architecture-ips-a7ec`  
+**Owner:** —  
+**Created:** 2026-08-24  
+**Architecture source:** [modular-api-design.md](../explanation/modular-api-design.md), [model-router-mcp.md](model-router-mcp.md), [admin-improvements.md](admin-improvements.md)  
+**Task list:** [collection-registry.md](../tasks/collection-registry.md)  
+**Depends on:** [unified-mutation-executors.md](unified-mutation-executors.md) (soft — writes already one pipeline; registry does not need to wait on MCP adapters, but avoid teaching two write paths)  
+**Unlocks:** simpler RBAC option injection; [describe-model-schema.md](describe-model-schema.md) can hang metadata on the descriptor
+
+## Goal
+
+Register a modelRouter collection once. MCP, realtime, and Sync stop each owning a process-global array plus `update*RegistryOptions` after TerrenoApp injects `accessControl`.
+
+`modelRouter` today (`api/src/api.ts`): `registerMCPModel` / `registerRealtime` / `registerSync` at call time, then `updateMCPRegistryOptions` / `updateRealtimeRegistryOptions` / `updateSyncRegistryOptions` in `_buildModelRouter` when options are enriched. RBAC and MCP work keep touching all three.
+
+## Non-Goals
+
+- A fourth parallel registry.
+- Redesigning MCP tool JSON, Socket.IO payloads, or the Sync protocol.
+- Merging admin’s `AdminApp` model list into this registry in v1 (admin still has its own config; a later task may read the descriptor).
+- Replacing `ModelRouterOptions` with a new public options type in one PR (options bag can stay; the **runtime catalog** is what unifies).
+- Splitting TerrenoApp into Options/Middleware/Hooks files ([ModularAPI.md](ModularAPI.md) file-split is explicitly not this IP).
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| Interface shape | **A — `CollectionRegistry` keyed by route path**, holding `{path, model, options, surfaces}`. Surfaces keep **read helpers** (`getMCPRegistry()`, `findRealtimeByCollectionName()`, …) as views. Not B (event bus / subscribe API) — one extra indirection, same data. |
+| Identity | Primary key: `routePath` (e.g. `/todos`). MCP’s `modelName` index is a secondary lookup that must not diverge. |
+| Option patch | `replaceCollectionOptions(routePath, options)` updates the single record. Surface `update*RegistryOptions` become one-line wrappers or are deleted in the contract phase. |
+| Custom MCP tools | Stay on a **separate** `mcpCustomTools` list. They are not collections. |
+| Sync-only validation | `registerSync` schema checks (`deleted`, `_syncSeq`, scope fields) and index tracking stay in `api/src/sync/registry.ts` **functions** called from `CollectionRegistry.register` when `options.sync` is set. Do not lose those guards. |
+| Compatibility | Public exports `registerMCPModel`, `registerRealtime`, `registerSync`, `clear*Registry` remain until the contract phase, implemented as wrappers. Tests migrate to `clearCollectionRegistry()`; wrappers keep calling it. |
+| Tests | One registry clear in test setup; existing MCP/realtime/sync tests keep working through wrappers in Phase 1. |
+
+## Interface shapes considered
+
+**A (chosen).**
+
+```typescript
+interface CollectionRecord<T = unknown> {
+  routePath: string;
+  model: Model<T>;
+  options: ModelRouterOptions<T>;
+  surfaces: {mcp: boolean; realtime: boolean; sync: boolean};
+}
+
+registerCollection({routePath, model, options}): void
+replaceCollectionOptions(routePath, options): void
+getCollection(routePath): CollectionRecord | undefined
+listCollections(): CollectionRecord[]
+```
+
+**B (rejected).** Surfaces subscribe `onCollection(record)`. Requires teardown, ordering, and still stores the same records.
+
+## Architecture
+
+```
+Before:
+  modelRouter → registerMCP + registerRealtime + registerSync
+             → later updateMCP* + updateRealtime* + updateSync*
+
+After:
+  modelRouter → CollectionRegistry.register(descriptor)
+  TerrenoApp.build → CollectionRegistry.replaceOptions(path, enriched)
+  MCP / realtime / sync read views of the same records
+```
+
+`api/src/mcp/registry.ts` (~70 lines) and `api/src/realtime/registry.ts` (~78 lines) are nearly the same array + update-by-key. `api/src/sync/registry.ts` adds contract validation and index promises — keep that logic, not the duplicated options pointer.
+
+## Docs in this slice
+
+| Page | Change |
+|------|--------|
+| `docs/explanation/modular-api-design.md` | Collection catalog is the runtime seam for surfaces. |
+| `docs/reference/api.md` | `modelRouter` registers one collection; MCP/realtime/sync flags attach surfaces. |
+| MCP / realtime / sync reference sections | Registration is not a separate app-facing API. |
+
+## Testing
+
+Seam: `registerCollection` + `replaceCollectionOptions`. Tests:
+
+- Register with `mcp` + `sync`; `getMCPRegistry()` and sync lookup see the same `options` object identity after replace.
+- `replaceCollectionOptions` on unknown path is a no-op (current update* behavior).
+- Sync still throws on missing `deleted` / `_syncSeq` at register time.
+- Existing realtime/MCP/sync integration tests pass without behavior change.
+
+## Risks
+
+| Risk | Mitigation |
+|------|------------|
+| Startup order / TerrenoApp.build | Keep register-then-replace; do not require all modelRouters to be three-arg form beyond today’s warnings. |
+| Test isolation | `clearCollectionRegistry()` clears all surfaces; wrappers’ `clearMCPRegistry` etc. call it **or** clear only that view — **Decision: clear all** so tests cannot leave a stale MCP entry after a sync-only clear. Update tests that assumed independent clears. |
+| Export churn | Wrappers stay through one minor release; changelog lists wrappers as deprecated internals if they were public. |
+
+## Phases
+
+1. Add `CollectionRegistry`; `modelRouter` writes it **and** still calls existing register functions (dual-write). Tests prove options identity after replace on the new registry.
+2. Point MCP/realtime/sync lookups at the registry; delete duplicate arrays. Keep wrapper function names.
+3. Delete dual-write; `update*RegistryOptions` become wrappers. Docs + changelog.
+
+## Feature Flags & Migrations
+
+No runtime flag. Dual-write in Phase 1 is the migration.
+
+## Not Included / Future Work
+
+- Admin `models[]` reading `CollectionRegistry`.
+- Per-app registry instance (today is process-global, matching current registries). A TerrenoApp-scoped map is a later seam if two apps share a process.
+
+## Files to Create / Modify
+
+- `api/src/collectionRegistry.ts` (new)
+- `api/src/api.ts` — register/replace
+- `api/src/mcp/registry.ts`, `api/src/realtime/registry.ts`, `api/src/sync/registry.ts` — views + sync validation
+- Tests that `clearMCPRegistry` / `clearRealtimeRegistry` / `clearSyncRegistry`
+- `api/src/index.ts` exports if any new public names
+- Docs listed above
+
+## Acceptance Criteria
+
+- [ ] One in-memory catalog holds collection options for MCP, realtime, and sync.
+- [ ] TerrenoApp option enrichment updates that catalog once per path.
+- [ ] Sync schema/index guards still fail fast at startup.
+- [ ] Independent `clearMCPRegistry()` in a test cannot leave realtime entries pointing at old options (documented clear-all behavior, tests updated).
+- [ ] No behavior change to MCP tools, socket events, or sync protocol.
+- [ ] Docs describe the catalog; `bun test` for api mcp/realtime/sync registries passes.
+
+## Task List
+
+[docs/tasks/collection-registry.md](../tasks/collection-registry.md)