diff --git a/.claude/refactor/CONTINUE_HERE.md b/.claude/refactor/CONTINUE_HERE.md new file mode 100644 index 0000000..6030cb3 --- /dev/null +++ b/.claude/refactor/CONTINUE_HERE.md @@ -0,0 +1,113 @@ +# Continue here (fresh-context entry point) + +**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. diff --git a/.claude/refactor/README.md b/.claude/refactor/README.md index 75a3467..0a99088 100644 --- a/.claude/refactor/README.md +++ b/.claude/refactor/README.md @@ -4,6 +4,11 @@ This directory holds the durable plan and conventions for the platform-wide refactor of the EVOLV Node-RED nodes. Anyone (human or agent) working on this refactor reads these files first. +> **Fresh context? Start here:** read **[`CONTINUE_HERE.md`](./CONTINUE_HERE.md)** first. +> It explains the current state (Phases 1–11 done, 823 platform tests green), +> lists the deferred work in priority order, and points at the specific +> `OPEN_QUESTIONS.md` entries that still need action. + ## Goals 1. **Eliminate boilerplate** — every nodeClass today is ~80% identical.