Merge pull request #50 from HanSur94/claude/reverent-bohr

v2.0: Tag-Based Domain Model — unified Tag foundation

Author: HanSur94

.planning/PROJECT.md

@@ -41,6 +41,23 @@ Users can organize complex dashboards into navigable sections and pop out any wi
 ### Active
 
 - ✓ Dashboard performance optimization: theme caching, O(1) widget dispatch, single-pass live tick, in-place resize, visibility page switch — v1.0 Performance
+- ✓ Tag-based domain model: unified `Tag` foundation, `TagRegistry`, `MonitorTag` derived time-series, `CompositeTag` aggregation — v2.0
+- ✓ Events attached to tags with FastSense overlay rendering — v2.0
+
+## Current State
+
+**Shipped:** v2.0 Tag-Based Domain Model (2026-04-17)
+
+The SensorThreshold subsystem has been fully rebooted on a unified `Tag` foundation. Legacy `Sensor`/`Threshold`/`StateChannel`/`CompositeThreshold` classes are deleted. All consumers (FastSenseWidget, dashboard widgets, EventDetection, LiveEventPipeline) operate through the Tag API (`addTag`, `getXY`, `valueAt`). Events bind to tags via `EventBinding` registry and render as toggleable round markers in FastSense.
+
+**Vocabulary:** `SensorTag`, `StateTag`, `MonitorTag`, `CompositeTag`, `TagRegistry`, `EventBinding`. FastSense API: `addTag(t)`.
+
+**Next milestone candidates:**
+- Asset hierarchy (Asset tree, templates, tag-to-asset binding, browse rollups)
+- Custom event GUI (click-drag region selection in FastSense → label dialog)
+- Calc tags / formula evaluator for arbitrary derived tags
+- Tri-state / continuous severity MonitorTag output
+- WebBridge parity for Tag API features
 
 ### Out of Scope
 
@@ -95,6 +112,11 @@ Users can organize complex dashboards into navigable sections and pop out any wi
 | repositionPanels for onResize | In-place panel repositioning vs destroy+recreate; fallback to rerenderWidgets on missing handles | ✓ Good |
 | switchPage visibility toggle | Hide/show panels instead of full rerender; pre-allocate all page panels at render() | ✓ Good |
 | Single-pass onLiveTick with updateLiveTimeRangeFrom | One activePageWidgets() call, merged mark-dirty+refresh loop | ✓ Good |
+| v2.0 reboot under unified `Tag` root (Option 2) | No-users codebase; preserves design wins from 1001-1003 as concepts; cleanest end state vs. interface-shim approach (Option 3) | Pending v2.0 |
+| Vocabulary: `Tag` suffix on all primitives (`SensorTag`, `MonitorTag`, ...) | Trendminer-faithful; uniform mental model; `addTag()` API replaces `addSensor()` | Pending v2.0 |
+| Single `TagRegistry` (replaces `SensorRegistry` + `ThresholdRegistry`) | One namespace, one search surface; fewer parallel singletons | Pending v2.0 |
+| MonitorTag as full time-series signal (not current-state only) | Plottable, persistable, event-detectable; reuses existing infrastructure | Pending v2.0 |
+| Defer asset hierarchy (D), custom event GUI (F), calc tags (G) to later milestones | Ambitious tier (A+B+C+E) is shippable on its own; D/F/G are independent additions | Pending v2.0 |
 
 ## Evolution
 
@@ -114,4 +136,4 @@ This document evolves at phase transitions and milestone boundaries.
 4. Update Context with current state
 
 ---
-*Last updated: 2026-04-04 after v1.0 performance optimization milestone*
+*Last updated: 2026-04-16 — v2.0 milestone (Tag-Based Domain Model) initialized*

.planning/ROADMAP.md

@@ -0,0 +1,93 @@
+# Milestone v2.0: Tag-Based Domain Model
+
+**Status:** ✅ SHIPPED 2026-04-17
+**Phases:** 1004-1011 (8 phases)
+**Total Plans:** 27
+**Commits:** 119
+**Files Changed:** 224 (13,799 insertions, 10,747 deletions — net +3,052 lines)
+**Timeline:** 2026-04-16 → 2026-04-17
+
+## Overview
+
+Reboot the SensorThreshold subsystem on a unified `Tag` foundation. Everything is a Tag — `Sensor`/`Threshold`/`StateChannel`/`CompositeThreshold` rewritten as Tag subclasses (`SensorTag`, `StateTag`, `MonitorTag`, `CompositeTag`). New primitives deliver derived time-series health signals. Events bind to tags and overlay in FastSense. Strangler-fig sequencing: parallel hierarchy phases 1004-1008, consumer migration phase 1009, event binding phase 1010, legacy deletion phase 1011.
+
+## Key Accomplishments
+
+1. **Unified Tag foundation** — `Tag` abstract base class with `TagRegistry` singleton, two-phase JSON deserializer, label/metadata/criticality support. Proven Octave-safe throw-from-base pattern.
+2. **MonitorTag derived signals** — Lazy-by-default 0/1 binary time series from any parent Tag + condition function. Debounce (ISA-18.2 MinDuration), hysteresis (alarm-on/alarm-off), streaming `appendData` for live pipelines, opt-in disk persistence.
+3. **CompositeTag aggregation** — 7 modes (AND/OR/MAJORITY/COUNT/WORST/SEVERITY/USER_FN) via vectorized merge-sort streaming. Key-equality cycle detection. 0.125x output-size ratio at 8×100k children (Pitfall 3 gate).
+4. **Event↔Tag binding** — Many-to-many `EventBinding` registry replacing denormalized carrier strings. `Event.TagKeys` cell. `Tag.addManualEvent` convenience. FastSense `renderEventLayer_` draws toggleable round markers.
+5. **Full consumer migration** — Every widget (FastSenseWidget, MultiStatusWidget, IconCardWidget, EventTimelineWidget, SensorDetailPlot) + EventDetector + LiveEventPipeline migrated to Tag API. 0.3% tick overhead.
+6. **Clean legacy deletion** — 8 legacy classes + 13 private helpers + 37 legacy-only test files deleted. Golden integration test rewritten to Tag API with preserved assertion semantics. Net -3,995 lines in libs/.
+
+## Phases
+
+### Phase 1004: Tag Foundation + Golden Test
+**Goal**: Establish parallel Tag hierarchy and untouchable regression guard.
+**Plans**: 3 (Tag base + MockTag, TagRegistry + two-phase loader, Golden test + budget verification)
+**Key deliverables**: Tag.m (6 abstract-by-convention stubs), TagRegistry.m (CRUD + query + loadFromStructs), TestGoldenIntegration.m
+**Completed**: 2026-04-16
+
+### Phase 1005: SensorTag + StateTag (data carriers)
+**Goal**: Port raw-data half of domain into Tag subclasses with polymorphic FastSense.addTag.
+**Plans**: 3 (SensorTag composition wrapper, StateTag ZOH valueAt, FastSense.addTag dispatcher)
+**Key deliverables**: SensorTag.m (HAS-A Sensor delegate), StateTag.m (ZOH), FastSense.addTag (getKind dispatch)
+**Completed**: 2026-04-16
+
+### Phase 1006: MonitorTag (lazy, in-memory)
+**Goal**: First-class derived signal replacing Sensor.resolve() side-effect pipeline.
+**Plans**: 3 (Core lazy memoize + observer hook, Debounce + hysteresis + events, Integration + bench)
+**Key deliverables**: MonitorTag.m (500 SLOC), SensorTag/StateTag listener hooks, bench: 3.3x faster than legacy
+**Completed**: 2026-04-16
+
+### Phase 1007: MonitorTag streaming + persistence
+**Goal**: Opt-in performance/persistence levers for live pipelines.
+**Plans**: 3 (appendData streaming, Persist + FastSenseDataStore monitors API, Bench)
+**Key deliverables**: appendData with boundary-state continuity, storeMonitor/loadMonitor/clearMonitor, bench: 11.1x speedup
+**Completed**: 2026-04-16
+
+### Phase 1008: CompositeTag
+**Goal**: Aggregate MonitorTags/CompositeTags via merge-sort streaming with 7 aggregation modes.
+**Plans**: 3 (Core + addChild + cycle DFS, Merge-sort + ALIGN + 3-deep round-trip, Integration + bench)
+**Key deliverables**: CompositeTag.m (vectorized sort merge), valueAt fast-path, bench: 53ms at 8×100k
+**Completed**: 2026-04-16
+
+### Phase 1009: Consumer migration (one widget at a time)
+**Goal**: Migrate every consumer to Tag API — one widget per commit, green CI each.
+**Plans**: 4 (FastSense layer, Dashboard widgets, EventDetection + LEP appendData wire-up, Bench)
+**Key deliverables**: 19 production files cleaned, LiveEventPipeline MonitorTargets, bench: 0.3% overhead
+**Completed**: 2026-04-17
+
+### Phase 1010: Event ↔ Tag binding + FastSense overlay
+**Goal**: Replace denormalized Event carriers with EventBinding registry; render event markers.
+**Plans**: 3 (Event.TagKeys + EventBinding, Tag.addManualEvent + renderEventLayer_, Bench)
+**Key deliverables**: EventBinding.m singleton, Event.TagKeys/Severity/Category, FastSense renderEventLayer_
+**Completed**: 2026-04-17
+
+### Phase 1011: Cleanup — collapse parallel hierarchy + delete legacy
+**Goal**: Delete 8 legacy classes, rewrite golden test, ship unified Tag-only domain.
+**Plans**: 5 (SensorTag inline + delete classes, Delete tests, Consumer branch removal, Example migration, Golden rewrite + grep audit)
+**Key deliverables**: 8 classes deleted, 37 test files deleted, golden rewritten, net -3,995 lines in libs/
+**Completed**: 2026-04-17
+
+## Milestone Summary
+
+### Key Decisions
+- Strangler-fig sequencing (parallel hierarchy → consumer migration → deletion)
+- Composition over inheritance for SensorTag (HAS-A Sensor delegate, later inlined)
+- Lazy-by-default MonitorTag (Pitfall 2 discipline)
+- Key-equality cycle detection (Octave SIGILL avoidance)
+- Vectorized sort-based merge for CompositeTag (pointer-loop too slow)
+- Event.TagKeys via EventBinding registry (no handle cross-references)
+- Separate renderEventLayer_ (no render-path pollution)
+
+### Tech Debt (from audit)
+1. EventDetector.detect(tag, threshold) references deleted Threshold API — dead code
+2. DashboardSerializer .m export doesn't handle source.type='tag' — JSON works
+3. 93 MATLAB-only test refs to deleted Threshold class in 42 suite files
+
+### Performance Gates (all passed)
+- Pitfall 3: CompositeTag 0.125x output ratio, 53ms compute
+- Pitfall 9 (Phase 1006): MonitorTag 3.3x faster than legacy Sensor.resolve
+- Pitfall 9 (Phase 1007): appendData 11.1x speedup vs full recompute
+- Pitfall 9 (Phase 1009): Consumer migration 0.3% tick overhead