Yeraze
diff --git a/‎docs/internal/dev-notes/MESHCORE_ANALYZER_OBSERVER_EPIC.md‎
Lines changed: 20 additions & 5 deletions b/‎docs/internal/dev-notes/MESHCORE_ANALYZER_OBSERVER_EPIC.md‎
Lines changed: 20 additions & 5 deletions
@@ -1,6 +1,6 @@
 # MeshCore Analyzer Observer MQTT Output — Epic Plan (#4457)
 
-**Status:** Phase 1 complete (PR pending) — Phase 2 next
+**Status:** Phase 2 complete (PR pending) — Phase 3 (UI + docs) next
 **Issue:** #4457 — publish packets heard by a MeshCore Companion source to a MeshCore Analyzer-compatible MQTT broker, so the node counts as an observer without a second app fighting over the serial port.
 **Scope guard:** observation-only. MeshMonitor publishes; it never subscribes to or injects broker traffic into the mesh. The broker's admin-only `serial/commands` remote-serial feature is out of scope.
 
@@ -47,10 +47,10 @@ Upstream issue michaelhart/meshcore-mqtt-broker#9 has no reply. We built the con
 - **Exit:** config + key round-trip through the API with secrets redacted; full suite green; merged PR.
 
 ### Phase 2 — Observer publisher service
-- [ ] `meshcoreObserverPublisher` per source: `manager.on('ota_packet')`, analyzer-contract packet JSON (decoder lib for hash/decode/advert privacy), publish via `MqttBrokerClient` (wss), retained `/status` + LWT, token renewal, reconnect via coordinator.
-- [ ] Lifecycle: start/stop with manager + restart on config change; observer status in `getStatus()` (connected, publishes, lastPublishAt, lastError).
-- [ ] Tests with mocked broker; per-source isolation.
-- **Exit:** live end-to-end against local `meshcore-mqtt-broker` (Docker, `test` region): token auth accepted, packets + status seen by a subscriber; merged PR.
+- [x] `meshcoreObserverPublisher` per source: `manager.on('ota_packet')`, analyzer-contract packet JSON (hash/decode implemented ourselves, not the decoder lib — see deviations (a)/(b); no advert privacy filter — see deviation (c)), publish via `MqttBrokerClient` (ws/wss), retained `/status` + explicit graceful-offline (LWT alone is broker-filtered — see deviation (e)), token renewal, reconnect via coordinator.
+- [x] Lifecycle: start/stop with manager + restart on config change (plus the hot-swap follow-up, deviation (f)); observer status in `getStatus()` (connected, publishes, lastPublishAt, lastError).
+- [x] Tests with mocked broker; per-source isolation.
+- **Exit:** live end-to-end against local `meshcore-mqtt-broker` (Docker, `test` region): token auth accepted, packets + status seen by a subscriber; merged PR. — **Done 2026-07-31**, run against a real companion (Yeraze MC Sandbox) instead of a synthetic feed; all 10 §8 criteria passed (see deviation (j)).
 
 ### Phase 3 — Frontend UI + docs
 - [ ] Observer fieldset in the MeshCore source modal: enable, broker URL, IATA, audience, fetch-key-from-device button + paste fallback, key-stored indicator.
@@ -71,3 +71,18 @@ Upstream issue michaelhart/meshcore-mqtt-broker#9 has no reply. We built the con
 - **Route-test harness gap.** `harness.grant()` collides with the `permissions` table's `UNIQUE(user_id, resource, sourceId)` index when granting read then write separately. Tests needing both use a local `grantReadWrite()` helper that writes one row with both flags set.
 - **Known gap (accepted).** A `meshcore_observer_keys` row orphans on source delete, same as `source_pki_keys` today. Cascade cleanup is deferred to its own change.
 - **Phase 2 seam.** `mintObserverTokenForSource()` is intentionally unrouted — Phase 2's publisher is its first consumer.
+
+### Phase 2
+
+- **(a)** The decoder library's `messageHash` (`@michaelhart/meshcore-decoder`'s `calculateMessageHash`) is a 32-bit djb2-style rolling hash, **not** `Packet::calculatePacketHash`. The analyzer contract's `hash` field is SHA-256-derived and 16 upper-hex chars, so we implement it ourselves rather than call the decoder lib (spec D-2).
+- **(b)** We decode the path/payload boundary with the **packed** `path_len` byte (`hashSize=(b>>6)+1`, `hopCount=b&0x3f`), not the reference's plain byte-count read. The two are byte-identical for 1-byte hash mode (effectively all real traffic); a named test pins the divergence for multi-byte hash mode, where the reference is simply wrong against firmware `Packet.h` (spec D-3).
+- **(c)** The reference publishes **no decoded advert fields** on the wire — its "advert opt-in privacy filter" (`name.endswith('^')`) has zero observable effect, since `format_packet_data()` never merges the advert decode into the payload. We match the wire: no advert fields, no filter implemented (spec D-4).
+- **(d)** Timestamps are emitted as UTC ISO-8601 with `Z` (`new Date().toISOString()`), a deliberate deviation from the reference's naive local `datetime.now().isoformat()` — naive local time is undisambiguatable and the broker itself parses timestamps with `new Date(...)` (spec D-8).
+- **(e)** The broker's stale-status filter suppresses the LWT on an ungraceful disconnect, so graceful stop publishes an explicit `offline` status before closing the socket (§2.4). This required a fix to `MqttBrokerClient.disconnect()`: the original force-end path discarded the queued offline publish, so a new `disconnect({flush: true})` (2s force-end fallback) is used, exclusively by `publisher.stop()`.
+- **(f)** `reconfigureObserver` hot-swap shipped (closes the Phase 1 follow-up) — toggling `observer.enabled` or its config no longer bounces the MeshCore radio link. Verified live: no reconnect logged for an observer-only config change.
+- **(g)** The reference's nameless-advert bug (`payload_value["name"]` unguarded, raising `KeyError`, swallowed by an outer `except`, degrading the packet to `route="U"`/`packet_type="0"`/`payload_len="0"`) is **not** replicated — our decode is total and never degrades a well-formed advert.
+- **(h)** The token renewal predicate subtracts the check interval as well as the expiry threshold, closing the reference's ~55-minute post-expiry hole (same three constants as the reference, different comparison — spec §3.2/§6).
+- **(i)** E2E against real hardware surfaced two live-only bugs invisible to the unit suite: a bare `require()` broke in the bundled ESM server (fixed via `createRequire`), and `firmware_version` doubled the `v` prefix because the device already reports its version with a leading `v` (fixed by not re-prepending it).
+- **(j)** E2E performed 2026-07-31 against a real companion (Yeraze MC Sandbox) and `meshcore-mqtt-broker` run from source (not a synthetic feed). All 10 §8 criteria passed: auth with correct audience; online status with retain-strip; packets with the full string-typed contract; hash independently verified; `path` present only on route D; no topic normalization; publisher never subscribes; graceful offline delivered after the flush fix; hot-swap with zero device bounce; bad audience produces a clean `lastError` and a single rejection with no reconnect storm.
+
+**Superseded checklist text (Phase 2, above):** the Phase 2 checklist item's parenthetical "(decoder lib for hash/decode/advert privacy)" is superseded by deviations (a)-(c) — hash/decode are hand-rolled, not decoder-lib calls, and no advert privacy filter exists. Its "reconnect via coordinator" wording refers only to the `MqttBrokerClient`'s own reconnect backoff, not to observer-toggle behavior, which is covered separately by the hot-swap in deviation (f); see also Phase 1's now-closed "Restart hook" note above.