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 (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

# 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.