EVOLV/wiki/Glossary.md

# Glossary

![code-ref](https://img.shields.io/badge/code--ref-9ab9f6b-blue)

> [!NOTE]
> S88, EVOLV runtime, wastewater, pump / hydraulics, control, and project terms. Use this page as a dictionary while reading the other wiki pages.

---

## S88 — ISA-88 batch control

```mermaid
flowchart TB
    enterprise["Enterprise"]
    site["Site"]
    area["Area"]
    pc["Process Cell"]
    unit["Unit"]
    em["Equipment Module"]
    cm["Control Module"]

    enterprise --> site --> area --> pc --> unit --> em --> cm

    class enterprise,site neutral
    class area area
    class pc pc
    class unit unit
    class em equip
    class cm ctrl

    classDef neutral fill:#dddddd
    classDef area fill:#0f52a5,color:#fff
    classDef pc fill:#0c99d9,color:#fff
    classDef unit fill:#50a8d9,color:#000
    classDef equip fill:#86bbdd,color:#000
    classDef ctrl fill:#a9daee,color:#000
```

| Term | Meaning in EVOLV |
|:---|:---|
| Area | Plant section. Reserved — no node implements it yet |
| Process Cell (PC) | Self-contained sub-process. pumpingStation is the only PC-level node |
| Unit (UN) | One major piece of equipment or a coordinator. MGC, VGC, reactor, settler, monster |
| Equipment Module (EM) | A single piece of equipment. rotatingMachine, valve, diffuser |
| Control Module (CM) | A single sensor or actuator. measurement |
| softwareType | The node's S88 type. Used by `ChildRouter` to match `child.register` |

---

## EVOLV runtime

| Term | Meaning |
|:---|:---|
| BaseDomain | Base class for every specificClass. Owns `measurements`, `router`, `emitter`, `logger` |
| BaseNodeAdapter | Base class for every nodeClass. Bridges Node-RED to specificClass via `commandRegistry` |
| specificClass | Pure-JS domain logic. No `RED.*` imports. Unit-testable in isolation |
| nodeClass | Node-RED adapter — input routing, tick loop, port wiring, status badge |
| ChildRouter | Declarative matcher for `child.register`. `router.onRegister(swType, handler)` |
| commandRegistry | Inbound-msg dispatcher. Topic to descriptor; resolves aliases, coerces units |
| UnitPolicy | Per-node declaration of canonical (internal) and output units |
| MeasurementContainer | Chainable measurement store. Keys: `<type>.<variant>.<position>.<childId>` |
| statusBadge | Composes `node.status({fill, shape, text})` from a HealthStatus |
| HealthStatus | `{level: 0..3, flags, message, source}` &mdash; standardised health summary |
| LatestWinsGate | Mutex with supersede semantics. Superseded calls resolve with `{superseded: true}` |
| outputUtils | Port-0 delta compression and Port-1 line-protocol formatting |
| tick | 1 Hz update loop. Opt-in via `static tickInterval = N` on nodeClass |
| `'output-changed'` | Event the specificClass fires on `this.emitter` when public state shifts |
| `getOutput()` | Domain method returning the current snapshot &mdash; fed to `outputUtils` |
| `getFlattenedOutput()` | Measurements with dot-flattened keys (4-segment `type.variant.position.childId`) |

---

## Topic prefixes

See [Topic Conventions](Topic-Conventions) for the full reference.

| Prefix | Direction | Idempotent |
|:---|:---|:---|
| `set.` | in | Yes |
| `cmd.` | in | No (side-effects) |
| `data.` | in / out | n/a |
| `query.` | in | Yes (read-only) |
| `child.` | in (parent) | Yes (id-keyed) |
| `evt.` | out | n/a |

---

## Wastewater treatment terms

| Term | Meaning |
|:---|:---|
| WWTP | Wastewater Treatment Plant |
| Influent / Effluent | Inlet / outlet stream of a process unit |
| Activated Sludge | Biological process &mdash; bacteria consume organic matter under aeration. Modelled by ASM1, ASM3 |
| MLSS | Mixed Liquor Suspended Solids &mdash; biomass concentration in the reactor |
| RAS | Return Activated Sludge &mdash; settled sludge pumped back from settler to reactor |
| WAS | Waste Activated Sludge &mdash; excess sludge removed from the system |
| TSS | Total Suspended Solids |
| COD / BOD | Chemical / Biological Oxygen Demand &mdash; organic load metrics |
| NH4 / NO3 | Ammonium / Nitrate &mdash; N species, key for nitrification / denitrification |
| DO | Dissolved Oxygen (mg/L). Setpoint typically around 2 mg/L in aerated zones |
| K_La | Volumetric mass-transfer coefficient (oxygen transfer rate / driving force) |
| OTR | Oxygen Transfer Rate &mdash; diffuser's output to the reactor |
| HRT / SRT | Hydraulic / Sludge Retention Time |
| F/M ratio | Food-to-microorganism ratio |
| Composite sample | A sample built over time, often flow-proportional &mdash; what monster simulates |

See [ASM Models](Concept-ASM-Models) for biological kinetics in detail.

---

## Pump / hydraulics terms

| Term | Meaning |
|:---|:---|
| BEP | Best Efficiency Point &mdash; operating point with minimum energy per unit flow |
| NPSH | Net Positive Suction Head &mdash; pressure margin to avoid cavitation |
| Affinity laws | Q proportional N, H proportional N-squared, P proportional N-cubed &mdash; how flow / head / power scale with pump speed |
| Characteristic curve | Q to H (or Q to P, Q to efficiency) graph supplied by the pump manufacturer |
| NCog | Normalised cost-of-going metric used by MGC for switching stability |
| Wet-well basin | Buffer volume on a lift station &mdash; what pumpingStation models |
| Setpoint | Commanded value (e.g. flow setpoint = 12 m3/h) |
| Demand | Integrated requirement (e.g. parent's "need this much flow now") |

See [Pump Affinity Laws](Concept-Pump-Affinity-Laws) and [BEP Gravitation Proof](Finding-BEP-Gravitation-Proof).

---

## Control / signal-processing terms

| Term | Meaning |
|:---|:---|
| PID | Proportional-Integral-Derivative controller |
| Anti-windup | Prevents the integral term from growing unboundedly when the actuator saturates |
| Hysteresis | Switching threshold with a deadband (e.g. start at 80%, stop at 30%) |
| Schmitt trigger | Hysteresis-based binary switch (used for `stopLevel` in pumpingStation) |
| Smoothing | Filtering noise (moving average, exponential, Savitzky-Golay) |
| Outlier detection | Identifying readings outside expected variance |
| FSM | Finite State Machine &mdash; discrete states + transitions |

See [PID Control Theory](Concept-PID-Control-Theory) and [Signal Processing &mdash; Sensors](Concept-Signal-Processing-Sensors).

---

## Project terms

| Term | Meaning |
|:---|:---|
| Tier 1&ndash;4 | Refactor phases. See [Home](Home) Refactor status |
| Wave A / B / C | Sub-batches of submodule pointer bumps during the refactor |
| OPEN_QUESTIONS.md | Live decisions log at `.claude/refactor/OPEN_QUESTIONS.md` |
| CONTRACTS.md | API shapes at `.claude/refactor/CONTRACTS.md` |
| MODULE_SPLIT.md | Per-node concern layout at `.claude/refactor/MODULE_SPLIT.md` |
| CONVENTIONS.md | Code style and naming at `.claude/refactor/CONVENTIONS.md` |
| WIKI_TEMPLATE.md | Per-node 14-section template at `.claude/refactor/WIKI_TEMPLATE.md` |
| AUTOGEN block | Sections regenerated by `npm run wiki:all`. Do not hand-edit between markers |

---

## Related pages

| Page | Why |
|:---|:---|
| [Home](Home) | Top-level node map |
| [Architecture](Architecture) | Runtime concepts in context |
| [Topic Conventions](Topic-Conventions) | Full topic / unit / colour reference |
| [Topology Patterns](Topology-Patterns) | Terms used in plant scenarios |