253ac93896
Establish CONTRACTS.md at the EVOLV root as the canonical map of where every contract, rule, and standard lives. Surface it from CLAUDE.md so every fresh agent or colleague lands there first. Reshape .claude/refactor/ to reflect that the platform refactor is done: live standards stay at the top level; the plan artifacts (CONTINUE_HERE.md, TASKS.md) move into Archive/ with WARNING banners. Drop content that drifted out of date or duplicated the new standards stack: - docs/DEVELOPER_GUIDE.md (pre-refactor walkthrough; superseded by wiki/Architecture, wiki/Getting-Started, .claude/rules/node-architecture, .claude/refactor/MODULE_SPLIT + per-node CONTRACT.md + src/commands/). - .agents/decisions/ (15 DECISION files): load-bearing decisions belong in commit messages and PR descriptions; live open items in OPEN_QUESTIONS.md. - .agents/improvements/TOP10_*.md: moved to Archive/. Bump generalFunctions to 49c77f2 — adds CONTRACT.md inside the library: different shape from per-node CONTRACT.md files (library API, not msg.topic), with stability tags and pointers to .claude/refactor/CONTRACTS.md §N. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
120 lines
6.9 KiB
Markdown
120 lines
6.9 KiB
Markdown
# 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.
|