EVOLV/.claude/refactor/Archive/CONTINUE_HERE.md

# Continue here (fresh-context entry point) — ARCHIVED

> [!WARNING]
> **ARCHIVED — the refactor described here landed on `development` in May 2026.**
> This file describes the *plan* and the *deferred work as of 2026-05-11*. It is
> retained for history. For current work, start at [`../../../CONTRACTS.md`](../../../CONTRACTS.md)
> (EVOLV root) and the live standards in [`../`](../).

Original intro: read this file first if you're picking up the EVOLV refactor
in a fresh session. It points at the durable plan and lists what's left.

## Read in order

1. `README.md` — refactor overview + the 11-phase plan
2. `CONVENTIONS.md` — code style, file/function size, naming, testing
3. `CONTRACTS.md` — the API shapes (BaseNodeAdapter, BaseDomain, commandRegistry, ChildRouter, UnitPolicy, statusBadge, LatestWinsGate, HealthStatus)
4. `MODULE_SPLIT.md` — per-node module layout
5. `TASKS.md` — phased plan; **Phases 1-11 are done** as of 2026-05-11
6. `OPEN_QUESTIONS.md` — the live decisions log; most entries are RESOLVED
7. `WIKI_TEMPLATE.md` + `WIKI_HOME_TEMPLATE.md` — the wiki shape every node uses

## Current state (verify with `npm run test:platform` from EVOLV root)

- **823 platform tests pass, 0 fail** across 12 submodules.
- All 12 submodules + parent EVOLV are on `development` branches at
  `gitea.wbd-rd.nl/RnD/*` — never merged to `main` yet.
- Docker stack runs natively in WSL via `docker compose up -d` (compose v2
  plugin installed at `~/.docker/cli-plugins/docker-compose`).
- Every node has `wiki/Home.md` with the 14-section visual-first template;
  topic-contract + data-model sections auto-regenerate via
  `npm run wiki:all` in each submodule.

## What's NOT done (deferred, in priority order)

### 1. B5 — `reactor` `boundary-conditions` feature branch merge (BIG)

`origin/boundary-conditions` in `nodes/reactor/` is **8 commits ahead** of
main, never merged before the refactor. Carries improved upstream/downstream
boundary-condition handling, multi-parent support, and grid-position refactor.
50 files changed, +2570 / -4151 lines. Conflicts heavily with the post-refactor
`kinetics/{cstr,pfr,baseEngine}.js` structure.

**Approach:** same pattern that worked for pumpingStation `basin-docs-update`:
- `cd nodes/reactor && git merge --no-commit --no-ff origin/boundary-conditions`
- Resolve the ~4-6 conflicting files by keeping the refactor's BaseDomain +
  kinetics/ structure, porting the boundary-condition behavior into
  `kinetics/baseEngine.js` (BC application) + `kinetics/pfr.js` (grid).
- All 46 reactor tests must stay green; ideally pick up any new tests the
  branch added.

Domain owner: needs to be in the loop. mathjs load means each test pass takes
~15s — budget accordingly.

### 2. Phase 8 — `development → main` PRs (human review)

12 submodules + parent. Suggested merge order:
- `generalFunctions` first (everything depends on it)
- All 11 node submodules (any order)
- Parent `EVOLV` last (carries the submodule pointers)

Each PR opened via gitea UI. Confirm Docker E2E per-node before merging
(load `examples/0X-*.json` flows, verify behaviour). Squash or rebase per
your team convention.

### 3. Small follow-ups still in `OPEN_QUESTIONS.md`

These are individually small (≤ half-day each):

| Entry | Action |
|---|---|
| pumpingStation `overfillVol` alias | Drop the parallel `overfillVol → highVolumeSafetyVol` alias in `src/basin/thresholdValidator.js`. Same shape as the already-done `overfillLevel` drop. |
| MGC `calcGroupEfficiency.maxEfficiency` naming | `maxEfficiency` actually returns the mean. Rename to `meanEfficiency` everywhere; update call sites + downstream telemetry consumers (search the platform for the key). |
| `predictionHealth` migration in rotatingMachine | Decide where `confidence` (numeric 0..1) lives now that HealthStatus is standardised. Default chosen: keep as sibling field on the drift container, not inside HealthStatus. Implement the migration if/when rotatingMachine drift output gets a v2 contract. |
| dashboardAPI no BaseDomain | Documented in OPEN_QUESTIONS. dashboardAPI is a passive HTTP server; doesn't fit BaseDomain. Confirm with team whether to revisit. |
| measurement legacy property mirrors | The new specificClass kept some legacy `inputValue`/`outputAbs` getter/setter mirrors for back-compat. Decide if any can be removed in a v2. |
| measurement `handleScaling` mutates `config.scaling` | Channel's `_applyScaling` mutates its own config copy when input range collapses; bridged via a 2-line mirror-back to `config.scaling`. Decide if Channel should not mutate at all, OR if the bridge is the right contract. |
| MGC `calcAbsoluteTotals` pressure-key coupling | Implicitly assumes flow.inputCurve and power.inputCurve keys are paired. Add a guard or document. |
| rotatingMachine `_pendingExtras` constructor workaround | The 3-positional-arg constructor (`machineConfig, stateConfig, errorMetricsConfig`) is bridged via a `Machine._pendingExtras` static stash from buildDomainConfig. Cleaner approach: include state + errorMetrics in the validated config schema directly. |
| reactor schema enum lowercases `reactor_type` | The validator lowercases enum values; `_buildEngine` upper-cases before switching as a guard. Standardise schema enum casing — drop the guard. |
| reactor mathjs runtime (~13s per test file) | Hoist a single mathjs instance at module top OR switch to tree-shaken mathjs subset. Drops test suite runtime from ~3 min to ~10 s. |
| valveGroupControl `set.position` placeholder | Currently a debug-logged no-op. Implement or remove. |

### 4. Phase 9 follow-ups (wiki cosmetics)

These came up during the wiki rollout:

- **Header banner auto-stamping**: `WIKI_TEMPLATE.md` instructs writers to put the
  git short hash + regen date in the header. `wikiGen.js` doesn't currently
  rewrite that banner. Either add a banner-rewrite or change the template to
  "manually set when authoring".
- **Curve-data-model auto-gen warnings**: rotatingMachine + valve emit
  `Asset 'Unknown' not found` to stderr when wikiGen instantiates the domain
  with no curve. Either suppress the noise (catch in wikiGen) or document.
- **Data-model AUTOGEN "sample value" placeholder**: Most nodes' `getOutput()`
  is trivially small in a stub-construction context (no children registered).
  Template should explicitly tell authors to supplement with a hand-curated
  concrete sample block under the markers.

## How to verify nothing has rotted

```bash
# From /mnt/d/gitea/EVOLV:

# 1. fetch latest from origin
git fetch --recurse-submodules

# 2. confirm everything still green
npm run test:platform     # expect 823 / 0

# 3. confirm Docker still healthy (if compose stack is running)
docker compose ps
curl -sf http://localhost:1880/nodes | wc -c     # > 0 means Node-RED is up

# 4. confirm submodule branches are still development
git submodule foreach --quiet 'echo "$name $(git rev-parse --abbrev-ref HEAD)"'
```

If any of those drift from the expected state, that's the first thing to
investigate before touching new work.