pearcord/pearcord-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document Phase 410 cache-metrics hardening progress.

Browse Source 
Mark P410-03 through P410-11 complete in the roadmap and record logging guidance for new cache-hit/coalescing diagnostics.

Co-authored-by: Cursor <[email protected]>
This commit is contained in:
Raven Scott
2026-06-02 10:41:03 -04:00
co-authored by Cursor
parent 32bcd5b72a
commit 874d012410
2 changed files with 16 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files
LOGGING.md
+4 -1
View File
@@ -101,7 +101,10 @@ If logs show slow `guild.open` / `session.startup` spans (>2s, logged as `WARN`)
**v0.8.642 (Phase 409 perf hardening):** Platform view build now dedupes concurrent in-flight `reaction.list` and `pin.list` fetches for identical channel/context cache keys (`_reactionListPending`, `_pinListPending`) to prevent duplicate list scans in the same render burst. Added cache-hit diagnostics (`reaction.list cache hit`, `reaction.list pending cache hit`, `pin.list cache hit`, `pin.list pending cache hit`). Smokes: `npm run test:platform-reaction-list-cache-full`, `npm run test:platform-pin-list-cache`. **v0.8.642 (Phase 409 perf hardening):** Platform view build now dedupes concurrent in-flight `reaction.list` and `pin.list` fetches for identical channel/context cache keys (`_reactionListPending`, `_pinListPending`) to prevent duplicate list scans in the same render burst. Added cache-hit diagnostics (`reaction.list cache hit`, `reaction.list pending cache hit`, `pin.list cache hit`, `pin.list pending cache hit`). Smokes: `npm run test:platform-reaction-list-cache-full`, `npm run test:platform-pin-list-cache`.
**v0.8.640 (Phase 410):** Added event-driven state batching in worker (`requestEventPushState`) to collapse dense platform event bursts before `pushState`. Added platform pin list cache (`_pinListCache*`) with invalidation on pin write/delete/gossip ingest and broadened reaction cache reuse beyond light polls to reduce repeated list scans. Extended runtime diagnostics with explicit `bootPushCount` / `eventPushCount` / `pollPushCount`, burst-clamp telemetry (`droppedBurstClamped`, `burst.windowMs`, `burst.maxPerWindow`), and unchanged-state suppression telemetry (`droppedUnchanged`) backed by a shallow view hash guard. Smokes: `npm run test:event-state-batching`, `npm run test:platform-pin-list-cache`, `npm run test:platform-reaction-list-cache-full`. **v0.8.643 (Phase 410 perf follow-up):** `pin.list`, `reaction.list`, and `discovery.list` spans now emit explicit cache metadata (`cacheHit`, `source`) for cache/pending/fresh paths. `discovery.list` now coalesces concurrent refreshes behind a shared in-flight promise to avoid duplicate listing scans during overlapping view builds. Dev-log clipboard meta now includes `reactionListCacheSummary`, `pinListCacheSummary`, and `discoveryListCacheSummary` from `view.listCacheMetrics`.
**v0.8.640 (Phase 410):** Added event-driven state batching in worker (`requestEventPushState`) to collapse dense platform event bursts before `pushState`. Added platform pin list cache (`_pinListCache*`) with invalidation on pin write/delete/gossip ingest and broadened reaction cache reuse beyond light polls to reduce repeated list scans. Extended runtime diagnostics with explicit `bootPushCount` / `eventPushCount` / `pollPushCount`, burst-clamp telemetry (`droppedBurstClamped`, `burst.windowMs`, `burst.maxPerWindow`), unchanged-state suppression telemetry (`droppedUnchanged`) backed by a shallow view hash guard, and an in-memory source histogram (`sourceHistogram`) for quick runtime triage. Added bounded `pushState` retry queue controls (`PEARCORD_PUSH_RETRY_DELAY_MS`, `PEARCORD_PUSH_RETRY_MAX_ATTEMPTS`, `PEARCORD_PUSH_RETRY_QUEUE_MAX`) with retry diagnostics (`retryQueued`, `retryDropped`, `retryAttempts`, `retry.queueDepth`). Smokes: `npm run test:event-state-batching`, `npm run test:platform-pin-list-cache`, `npm run test:platform-reaction-list-cache-full`.
Worker boot profiling now emits explicit spans for startup triage: `runtime.boot.loadBootView`, `runtime.boot.onUiReady`, and `runtime.boot.firstFullStateDispatch`. Each span includes bounded/failure metadata so boot regressions can be filtered quickly in diagnostics.
**v0.8.382 (Phase 419):** Dev log clipboard + save JSONL meta include `reactionCount` (emoji pills with count &gt; 0 in active view). **Search-errors** diagnostics filter re-verified. Smokes: `npm run test:dev-log-clipboard-reaction-count`, `npm run test:dev-log-search-errors-bundle`. **v0.8.382 (Phase 419):** Dev log clipboard + save JSONL meta include `reactionCount` (emoji pills with count &gt; 0 in active view). **Search-errors** diagnostics filter re-verified. Smokes: `npm run test:dev-log-clipboard-reaction-count`, `npm run test:dev-log-search-errors-bundle`.
PLATFORM_ROADMAP.md
+12 -9
View File
@@ -5,7 +5,7 @@ Focused roadmap of unfinished items extracted from `PLATFORM_ROADMAP_v0.1-v0.8.6
**Legend:** `[ ]` not started **Legend:** `[ ]` not started
**Legend:** `[SKIP]` skip for now **Legend:** `[SKIP]` skip for now
Unfinished items tracked: **347** Unfinished items tracked: **344**
Skipped items tracked: **1** Skipped items tracked: **1**
--- ---
@@ -28,15 +28,15 @@ Primary in-flight work. Move completed items to `[x]` and add a changelog line.
- [x] **P410-01 Runtime:** Added runtime diagnostics counters (`bootPushCount`, `eventPushCount`, `pollPushCount`) in worker `pushState` flow. - [x] **P410-01 Runtime:** Added runtime diagnostics counters (`bootPushCount`, `eventPushCount`, `pollPushCount`) in worker `pushState` flow.
- [x] **P410-02 Runtime:** Added configurable burst clamp (`PEARCORD_PUSH_BURST_WINDOW_MS`, `PEARCORD_PUSH_BURST_MAX`) with telemetry for dropped bursts. - [x] **P410-02 Runtime:** Added configurable burst clamp (`PEARCORD_PUSH_BURST_WINDOW_MS`, `PEARCORD_PUSH_BURST_MAX`) with telemetry for dropped bursts.
- [ ] **P410-03 Runtime:** Add explicit push-source histogram persisted in memory for quick perf triage. - [x] **P410-03 Runtime:** Added in-memory `sourceHistogram` counters (with start timestamp) to runtime diagnostics for quick push-source triage.
- [x] **P410-04 Runtime:** Added shallow state hash guard and `droppedUnchanged` telemetry to suppress duplicate non-structural state emissions. - [x] **P410-04 Runtime:** Added shallow state hash guard and `droppedUnchanged` telemetry to suppress duplicate non-structural state emissions.
- [ ] **P410-05 Runtime:** Add bounded queue for `pushState` retries when platform view temporarily throws. - [x] **P410-05 Runtime:** Added bounded `pushState` retry queue with configurable delay/attempt/queue caps and retry telemetry.
- [ ] **P410-06 Runtime:** Add boot-path profiling spans for `loadBootView`, `onUiReady`, and first full state dispatch. - [x] **P410-06 Runtime:** Added worker boot-path spans for `loadBootView`, `onUiReady`, and first full state dispatch with bounded/fallback metadata.
- [ ] **P410-07 Platform perf:** Add `pin.list` memoized snapshot path with cache-hit metric in span metadata. - [x] **P410-07 Platform perf:** Added `pin.list` cache-hit/pending-hit span metadata (`cacheHit`, `source`) plus rolling cache metrics.
- [ ] **P410-08 Platform perf:** Add `reaction.list` cache-hit metric in span metadata and dev-log panel summary. - [x] **P410-08 Platform perf:** Added `reaction.list` cache-hit/pending-hit span metadata and surfaced list-cache summaries in UI diagnostics metadata.
- [ ] **P410-09 Platform perf:** Add `discovery.list` cache-hit coalescing to avoid duplicate list calls in one render tick. - [x] **P410-09 Platform perf:** Added `discovery.list` cache-hit/pending-hit coalescing via shared pending promise to suppress duplicate list calls during concurrent view builds.
- [ ] **P410-10 Platform perf:** Add user lookup batching in `_buildView` to reduce per-member `db.get` fanout. - [x] **P410-10 Platform perf:** Batched user lookups in `_buildView` by reusing `_usersById` map for mention-name and member-display derivation paths.
- [ ] **P410-11 Platform perf:** Add channel settings lookup batching to reduce sequential `getChannelSettings` roundtrips. - [x] **P410-11 Platform perf:** Batched channel settings fetches with `Promise.all` instead of sequential `getChannelSettings` calls.
- [ ] **P410-12 Platform perf:** Add optional `view()` detail levels (minimal/light/full/diagnostic) for targeted polling. - [ ] **P410-12 Platform perf:** Add optional `view()` detail levels (minimal/light/full/diagnostic) for targeted polling.
- [ ] **P410-13 Networking:** Add automatic “mesh bounded mode” UI badge with retry countdown and explanation tooltip. - [ ] **P410-13 Networking:** Add automatic “mesh bounded mode” UI badge with retry countdown and explanation tooltip.
- [ ] **P410-14 Networking:** Add smarter retry spacing based on last successful peer contact instead of fixed attempt cadence. - [ ] **P410-14 Networking:** Add smarter retry spacing based on last successful peer contact instead of fixed attempt cadence.
@@ -511,6 +511,9 @@ For deferred items, use `[SKIP]` and include a brief reason inline.
## Changelog ## Changelog
- 2026-06-02 - Completed P410-07 through P410-11: added pin/reaction/discovery list cache-hit span metadata + coalescing metrics, batched `_buildView` user lookups, and parallelized channel settings fetches.
- 2026-06-02 - Completed P410-06 by adding explicit boot profiling spans (`runtime.boot.loadBootView`, `runtime.boot.onUiReady`, `runtime.boot.firstFullStateDispatch`) with bounded/fallback metadata.
- 2026-06-02 - Completed P410-03 and P410-05: added persisted in-memory push-source histogram diagnostics and a bounded `pushState` retry queue with configurable limits.
- 2026-06-02 - Completed P410-01, P410-02, and P410-04 in worker runtime: added explicit boot/event/poll push counters, burst clamping telemetry, and shallow-hash unchanged-state suppression. - 2026-06-02 - Completed P410-01, P410-02, and P410-04 in worker runtime: added explicit boot/event/poll push counters, burst clamping telemetry, and shallow-hash unchanged-state suppression.
- 2026-06-02 - Added governance rules to enforce completing/deferring all pending items before any new phase creation. - 2026-06-02 - Added governance rules to enforce completing/deferring all pending items before any new phase creation.
- 2026-06-02 - Restructured roadmap into `Now` / `Next` / `Backlog`; carried forward unfinished items from `PLATFORM_ROADMAP_v0.1-v0.8.640`. - 2026-06-02 - Restructured roadmap into `Now` / `Next` / `Backlog`; carried forward unfinished items from `PLATFORM_ROADMAP_v0.1-v0.8.640`.