Phase 1040: Companion Notification Center — acknowledgeable inbox in the Event Viewer

.planning/PROJECT.md

@@ -52,6 +52,8 @@ The SensorThreshold subsystem has been fully rebooted on a unified `Tag` foundat
 
 **Vocabulary:** `SensorTag`, `StateTag`, `MonitorTag`, `CompositeTag`, `TagRegistry`, `EventBinding`. FastSense API: `addTag(t)`.
 
+**Companion (Phase 1040, 2026-06-02):** the FastSenseCompanion **Event Viewer** now hosts an acknowledgeable notification inbox (`NotificationCenterPane`) as a horizontally-resizable right panel (draggable divider); a toolbar **bell** shows the unacked count + highest-severity color and opens the viewer. Dismiss == shared, audited `EventStore.acknowledgeEvent`.
+
 ## Current Milestone: v2.1 Tag-API Tech Debt Cleanup
 
 **Goal:** Close the 4 non-blocking tech debt items surfaced by the v2.0 milestone audit so the Tag-API codebase is free of dead code, test-skip gaps, and stubbed example demos.
@@ -146,4 +148,4 @@ This document evolves at phase transitions and milestone boundaries.
 4. Update Context with current state
 
 ---
-*Last updated: 2026-04-22 — v2.1 milestone (Tag-API Tech Debt Cleanup) started*
+*Last updated: 2026-06-02 — Phase 1040 (Companion Notification Center) complete*

.planning/ROADMAP.md

@@ -425,3 +425,16 @@ Plans:
 
 Plans:
 - [ ] TBD (promote with /gsd:review-backlog when ready)
+
+### Phase 1040: Companion Notification Center
+
+**Goal:** Add an acknowledgeable in-app notification inbox to `FastSenseCompanion` — a collapsible right-hand `NotificationCenterPane` (toggled by a toolbar bell + unacked-count badge) that live-lists unacknowledged threshold-violation events from the shared `EventStore` and lets operators acknowledge them (dismiss = `EventStore.acknowledgeEvent`, shared + audited). Predominantly a new UI surface over existing event + acknowledge infrastructure.
+**Requirements**: none mapped — 1040-CONTEXT.md locked decisions + the phase GOAL are the contract (must_haves derived in each PLAN)
+**Depends on:** Phase 1039
+**Plans:** 4/4 plans complete
+
+Plans:
+- [x] 1040-01-test-foundation-PLAN.md (Wave 1) — StubEventStore double + NotificationCenterPane static pure-logic helpers + flat test
+- [x] 1040-02-notification-pane-PLAN.md (Wave 2, depends 01) — full detachable inbox pane (attach/detach/refresh/ack/filter/stale/theme) + TestNotificationCenterPane
+- [x] 1040-03-companion-integration-PLAN.md (Wave 3, depends 02) — Companion 4th-column grid + toolbar bell+badge + onLiveTick_ refresh hook + detach wiring
+- [x] 1040-04-companion-tests-verify-PLAN.md (Wave 4, depends 03) — TestFastSenseCompanion toolbar-col updates + 9 integration tests + full-suite gate + human live-verify

.planning/STATE.md

@@ -2,15 +2,14 @@
 gsd_state_version: 1.0
 milestone: v4.0
 milestone_name: Multi-User LAN Concurrency
-status: shipping
-stopped_at: PR #152 ready for merge (v4.0); PR #114 (Phase 1028 perf) shipped 2026-05-19 on parallel branch.
-last_updated: "2026-05-19T10:00:00Z"
-last_activity: 2026-05-19 -- Phase 1028 (Tag update perf — MEX + SIMD) COMPLETE on parallel branch claude/adoring-ishizaka-edc93c; v4.0 milestone separately shipping via PR #152.
+status: verifying
+last_updated: "2026-06-02T11:44:53.304Z"
+last_activity: 2026-06-02
 progress:
-  total_phases: 12
-  completed_phases: 6
-  total_plans: 26
-  completed_plans: 30
+  total_phases: 16
+  completed_phases: 4
+  total_plans: 20
+  completed_plans: 39
 ---
 
 # State
@@ -20,25 +19,27 @@ progress:
 See: .planning/PROJECT.md (updated 2026-05-13)
 
 **Core value:** A MATLAB engineer can ingest a million-sample sensor stream, monitor thresholds, build sub-second-responsive dashboards, and navigate it all from a single Companion app — without leaving MATLAB and without external toolboxes.
-**Current focus:** Phase 1029 — Concurrency Foundation
+**Current focus:** Phase 1040 — companion-notification-center
 
 ## Current Position
 
-Phase: 1028 (tag-update-perf-mex-simd) — COMPLETE 2026-05-19 (this branch)
-Plan: 6 of 6 executed (with 03/04 deferred per Plan 02d data). Shipped plans: 01, 02, 02b, 02d, 05, 06.
+Phase: 1040
+Plan: Not started
 Milestone: v3.0 FastSense Companion — SHIPPED 2026-04-30; v4.0 Multi-User LAN Concurrency — shipping via PR #152 (parallel branch); v1.0 perf line tracks phase 1028 — now COMPLETE via PR #114.
-Status: Phase 1028 closed. WithIO `tickMin` reduced 4497 ms → 3603 ms (−19.9%) on Octave Linux x86_64 CI run 26089658442, almost entirely from Plan 02d's in-memory prior-state cache. Plan 06 ships per-tick fs-stat coalescing reducing 1600 → 1 syscalls/tick (−99.94% mechanism-level; wall-time +3.2% within variance on tmpfs CI). PR #114 carries the phase. Follow-up candidates for a future perf phase: in-memory propagation refactor; `containers.Map` → struct-array refactor; `.mat` save-side optimization. K2/K3/K4 deferred per data (target regions bucket as 0 ms post-cache).
-Last activity: 2026-05-29 - Completed 260529-fnt (via /gsd:fast): FunctionTransport adapter — reuse an external/company MATLAB mailer as a NotificationService Transport, no SMTP config
+Status: Phase complete — ready for verification
+Last activity: 2026-06-02
 
 ### Note on parallel v4.0 work (main branch state)
 
 While Phase 1028 was in flight on this branch, main shipped v4.0 Multi-User LAN Concurrency (phases 1029-1033) via PR #152. The two efforts touched some shared files (`LiveTagPipeline.m`, `build_mex.m`) — merged here on this commit with both feature sets preserved:
+
 - Plan 02d in-memory prior-state cache + Plan 06 fs-stat coalescing live in the single-user code path of `LiveTagPipeline.processTag_`.
 - v4.0 cluster-mode (TagWriteCoordinator + AtomicWriter) lives in the `if obj.IsClusterMode_` branch.
 - `bench_tag_pipeline_1k` continues to drive the single-user path (no SharedRoot set).
 - v4.0's STATE.md / ROADMAP.md entries (phases 1029-1033 Complete) preserved verbatim; phase 1028 Complete entry added alongside.
 
 Three main PRs touched files v4.0 also modified — all auto/manually merged without functional conflict:
+
 - PR #143 (260513-s0y) — Tile + Close all toolbar buttons. Tracking fixes (syncOpenedFigures_ Engines_ walk, public trackOpenedFigure hook, de-maximize + Units=pixels coercion) live alongside v4.0 cluster-mode wiring.
 - PR #149 (260519-bs4) — Tag Status Table window. TagStatusTableWindow handle + Tags toolbar button live alongside v4.0 cluster-mode + pipeline-observer state.
 
@@ -113,6 +114,7 @@ Phase 1019 [██████████] 100% (3/3 plans complete in Phase 10
 - 2026-04-29 — v3.0 phase 1023 added (Industrial Plant Demo Integration): wraps `demo/industrial_plant/run_demo.m` in `FastSenseCompanion`; 4 new COMPDEMO REQ-IDs; total now 6 phases / 32 REQ-IDs
 - 2026-05-13 — Milestone v4.0 Multi-User LAN Concurrency started; PROJECT.md updated, REQUIREMENTS.md created (14 P1 REQ-IDs across CONC/IDENT/EVTLOG/ACK/OPS categories; 6 P2 deferred to v4.1); research/ phase produced SUMMARY/STACK/FEATURES/ARCHITECTURE/PITFALLS markdown
 - 2026-05-13 — v4.0 roadmap created: 5 phases (1029-1033) covering all 14 P1 REQ-IDs, full coverage no orphans; phase structure mirrors research-recommended build order (Foundation → TagWriteCoordinator → EventLog → Single-Source Events → Companion Integration); three PITFALLS corrections (OFD locks, mtime heartbeat, lock-serialised appends) baked into Phase 1029 success criteria
+- 2026-06-02 — Phase 1040 added: Companion Notification Center (acknowledgeable in-app inbox pane in `FastSenseCompanion`; design brainstormed in-session and approved; EventStore-backed feed, dismiss = `acknowledgeEvent`, new collapsible right column + toolbar bell badge; `1040-CONTEXT.md` written)
 
 ### Phase Numbering Note
 

.planning/phases/1040-companion-notification-center/1040-01-SUMMARY.md

@@ -0,0 +1,99 @@
+---
+phase: 1040-companion-notification-center
+plan: 01
+subsystem: testing
+tags: [matlab, notification-center, eventstore, test-double, pure-logic, tdd]
+
+requires:
+  - phase: 1032-ack-events
+    provides: EventStore.acknowledgeEvent + Event.AckedAt (unacked filter key)
+provides:
+  - StubEventStore test double (getEvents/numEvents/acknowledgeEvent + ThrowOnGet_/ThrowOnAck_)
+  - NotificationCenterPane class shell + 7 static pure-logic helpers (filter/sort/diff/badge)
+  - Flat headless test pinning all helper + stub semantics
+affects: [1040-02-notification-pane, 1040-03-companion-integration, 1040-04-companion-tests-verify]
+
+tech-stack:
+  added: []
+  patterns:
+    - "Interface-first TDD: static pure-logic helpers as the contract before any UI"
+    - "Stub-with-failure-switches test double (ThrowOnGet_/ThrowOnAck_) modeled on CaptureNotificationService"
+
+key-files:
+  created:
+    - tests/StubEventStore.m
+    - libs/FastSenseCompanion/NotificationCenterPane.m
+    - tests/test_notification_center_pane.m
+  modified: []
+
+key-decisions:
+  - "Event fixtures use the real 6-arg constructor Event(start,end,sensor,label,thresholdValue,direction); the planning docs' 4-arg shorthand does not construct (direction is required + validated against {'upper','lower'})"
+  - "filterUnacked_ treats both empty AND all-NaN AckedAt as unacked, mirroring Event.computeDisplayState"
+  - "diffIds_ is order-insensitive via sort(ids(:)) with {} guards so identical sets in any order report no change (no badge flicker)"
+
+patterns-established:
+  - "NotificationCenterPane.<helper> static call surface — the pane's pure logic is callable + testable without a uifigure"
+
+requirements-completed: []
+
+duration: ~15 min
+completed: 2026-06-02
+---
+
+# Phase 1040 Plan 01: Test Foundation Summary
+
+**StubEventStore test double + the NotificationCenterPane pure-logic core (7 static helpers: unacked filter incl. NaN, newest-first sort, order-insensitive id-diff, severity/badge mapping), pinned by an 18-assertion headless flat test.**
+
+## Performance
+
+- **Duration:** ~15 min
+- **Completed:** 2026-06-02
+- **Tasks:** 3
+- **Files modified:** 3 (all created)
+
+## Accomplishments
+- `tests/StubEventStore.m` — fake EventStore handle with `ThrowOnGet_`/`ThrowOnAck_` switches that drive the stale-read and ack-race paths later plans need.
+- `libs/FastSenseCompanion/NotificationCenterPane.m` — class shell (events block + full private property declaration) plus 7 pure static helpers; no UI primitives instantiated.
+- `tests/test_notification_center_pane.m` — 18 headless assertions covering the stub round-trip + ack-race throw and all 7 helpers; runs green in milliseconds.
+
+## Task Commits
+
+1. **Task 1: StubEventStore test double** — `2b51ac88` (test)
+2. **Task 2: NotificationCenterPane static pure-logic helpers** — `3a05c8c6` (feat)
+3. **Task 3: flat pure-logic test** — `bd19fb85` (test)
+
+## Files Created/Modified
+- `tests/StubEventStore.m` — `classdef StubEventStore < handle`; getEvents/numEvents/acknowledgeEvent; records acked ids + mutates AckedAt.
+- `libs/FastSenseCompanion/NotificationCenterPane.m` — shell + filterUnacked_/sortNewestFirst_/maxSeverity_/idsOf_/diffIds_/badgeText_/badgeColor_.
+- `tests/test_notification_center_pane.m` — flat function test (`add_companion_path` + local `check`), prints "All 18 tests passed."
+
+## Decisions Made
+- See key-decisions frontmatter. The Event 6-arg constructor correction is the most consequential — Plans 02/04 build Event fixtures and must use the full signature.
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 3 - Blocking] Event constructor requires 6 args, not the 4 shown in the plan**
+- **Found during:** Task 3 (writing the flat test)
+- **Issue:** The plan's `<interfaces>` block and Task 3 examples construct `Event(startTime, endTime, sensorName, thresholdLabel)` (4 args). The real `Event` constructor is `Event(startTime, endTime, sensorName, thresholdLabel, thresholdValue, direction)` and throws if `direction` is missing/not in `{'upper','lower'}` — the 4-arg form cannot construct.
+- **Fix:** Built all test fixtures with the full 6-arg signature (e.g. `Event(30, NaN, 'P-101', 'HighPressure', 100, 'upper')`).
+- **Files modified:** tests/test_notification_center_pane.m
+- **Verification:** Test runs green (18/18).
+- **Committed in:** bd19fb85
+
+---
+
+**Total deviations:** 1 auto-fixed (1 blocking).
+**Impact on plan:** No scope change — only the fixture construction syntax. Carries forward to Plans 02 + 04 (their Event fixtures need the same 6-arg form).
+
+## Issues Encountered
+None. (Note: the plan's strict "no UI primitives" grep matches doc-comment mentions of `uifigure`/`uitable` in the property block, but a call-syntax grep confirms **zero** actual UI primitive calls — pure logic only.)
+
+## Next Phase Readiness
+- Plan 02 can extend `NotificationCenterPane` with the attach/detach/refresh/ack lifecycle on top of the static helpers; `StubEventStore` is ready to drive the headless suite.
+- No blockers.
+
+---
+*Phase: 1040-companion-notification-center*
+*Completed: 2026-06-02*