From 89d224226c2f2f2691d5e86d3127f178fde1f64a Mon Sep 17 00:00:00 2001 From: thePR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com> Date: Sun, 14 Jun 2026 15:51:20 -0400 Subject: [PATCH] docs: add KNOWN_BUGS.md (deferred defects); mark P3 complete --- docs/KNOWN_BUGS.md | 87 +++++++++++++++++++++++++++++++++++ docs/README.md | 1 + docs/architecture-refactor.md | 6 +-- 3 files changed, 90 insertions(+), 4 deletions(-) create mode 100644 docs/KNOWN_BUGS.md diff --git a/docs/KNOWN_BUGS.md b/docs/KNOWN_BUGS.md new file mode 100644 index 00000000..32b2445e --- /dev/null +++ b/docs/KNOWN_BUGS.md @@ -0,0 +1,87 @@ +# Known Bugs (deferred) + +Running list of confirmed bugs/limitations found during the data-flow refactor +(see [architecture-refactor.md](./architecture-refactor.md)) that we chose to +fix later rather than block the current phase. Distinct from the *planned* +refactor work in that doc — these are defects. + +> Format: **[severity]** short title — where — what — suggested fix / phase. + +--- + +## Open + +### 1. Logged-out: video grid stays empty until a manual refresh +- **Severity:** medium (first-load UX, logged-out). +- **Where:** initial feed render path (`js/index.js` disclaimer flow → + `viewManager` → `feedCoordinator`); rendering is a side-effect of event + ordering. +- **Symptom:** logged out, after dismissing the disclaimer the grid doesn't + populate until the page is refreshed. +- **Root cause (suspected):** the grid paints as a side-effect of a data event + that can fire before the grid container is mounted (render coupled to event + ordering, not to state). +- **Fix:** P5 — unidirectional flow: render from AppState whenever it changes, + decoupled from event ordering. Could not reproduce headlessly (real-relay + feed returned nothing in the sandbox); reproduce in a real browser first. + +### 2. Residual full-feed reload loop on list-loaded signals +- **Severity:** low–medium (bounded by the 2s throttle, but wasteful — re-fetches + lists ~every 2s while signals keep arriving). +- **Where:** `js/app/authSessionCoordinator.js` `handleBlocksLoaded` (and peers) + call `onVideosShouldRefresh` **unconditionally**; the forced reload re-fetches + the lists, which re-emit "loaded". +- **Fix:** P5 — only trigger a reload when the underlying list data actually + changed (emit-on-change at the list-loaded sources + collapse the refresh + triggers into the Coordinator). + +### 3. Direct-pool-access lint misses bare `pool.sub(` / `pool.list(` +- **Severity:** low (tooling gap — weakens the L1 chokepoint guarantee). +- **Where:** `scripts/check-direct-pool-access.mjs` — regex only matches member + access `.pool.sub(`. Bare local-variable calls slip through, e.g. + `js/nostr/viewEvents.js` and `js/nostr/relayBatchFetcher.js` use `pool.sub(` / + `pool.list(` and are NOT currently flagged or allowlisted. +- **Fix:** broaden the regex to also catch `\bpool\.(sub|list)\(`, then + re-baseline the allowlist (add the now-detected files). Do this alongside P4 + so the allowlist still only shrinks. + +### 4. Interim relay cap is static, not liveness-ranked +- **Severity:** low (acceptable interim). +- **Where:** `js/nostr/client.js` `capSubscribeRelays` — keeps the first 6 + relays (known-good defaults prioritized) but does NOT re-rank by live health. + If a user's first relays are dead, reads degrade until other paths recover. +- **Fix:** P1's deferred `RelayHealth` — rank the subscribe set by rolling + liveness and re-resolve on health changes. + +--- + +## Pre-existing test failures (predate this refactor) + +Confirmed failing at the pre-session baseline (`4bd9503c`) — not caused by the +refactor, but should be triaged. Not in `KNOWN_ISSUES.md`. + +### 5. `tests/nostr-delete-flow.test.mjs` +- "deleted events should not trigger subscription callbacks" — a deleted event + reaches the feed callback (buffer delete-filter or dedupe). Investigate the + `VideoEventBuffer` delete handling. + +### 6. `tests/view-counter.test.mjs` +- "view event should append the session tag when requested" — view-event + **publishing** tag composition (unrelated to the P3 counting refactor). + +### 7. `tests/nostr-count-fallback.test.mjs` +- Fails at baseline; NIP-45 COUNT fallback path. Triage. + +### 8. `tests/nostr/nip07Permissions.test.js` +- `writeStoredNip07Permissions` / `clearStoredNip07Permissions` fail under Node + (no real `localStorage`). Likely environmental — provide a localStorage shim + (see `tests/test-helpers/setup-localstorage.mjs`) or guard the test. + +--- + +## Perf follow-ups (not bugs, but tracked) + +- **One-time login enrichment burst** (~75 REQ frames): batched and O(relays), + settles to idle, but could be trimmed by hydrating only on-screen cards. +- **Remove `js/devReqMonitor.js` import + `scripts/perf/*` diagnostics** in P6 + cleanup once the refactor lands. diff --git a/docs/README.md b/docs/README.md index 1b99bff3..0ab504dd 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,6 +6,7 @@ Welcome to the bitvid documentation. This directory contains detailed architectu - **[Application Coordinators](./app-coordinators.md)**: Overview of the coordinator pattern used to manage app-wide state and services. - **[Data-Flow Refactor — Dev Plan & Spec](./architecture-refactor.md)**: The incremental plan to put all subsystems on a shared, governed relay/data foundation (SubscriptionManager, stores, unidirectional flow). +- **[Known Bugs (deferred)](./KNOWN_BUGS.md)**: Confirmed defects/limitations found during the refactor, queued to fix later. - **[Authentication Architecture](./auth-architecture.md)**: How session management, login flows, and signer integration work. - **[Feed Engine](./feed-engine.md)**: The pipeline for fetching, filtering, scoring, and sorting video feeds. - **[Playback & Fallback](./playback-fallback.md)**: The URL-first playback strategy with WebTorrent fallback orchestration. diff --git a/docs/architecture-refactor.md b/docs/architecture-refactor.md index 88e41171..e7e1a23d 100644 --- a/docs/architecture-refactor.md +++ b/docs/architecture-refactor.md @@ -260,10 +260,8 @@ The mock harness lied because it used **one perfect relay**. New fixtures: ranking deferred — the cap covers the immediate amplifier) - [x] P2 moderation reports batched + re-enabled (single SubscriptionManager sub over the active id set; trusted-mute subs already batched-by-author) -- [ ] P3 view counts batched + re-enabled — requires restructuring - js/viewCounter.js from per-pointer hydrate/live into ONE batched - kind-30079 query bucketed by `#a`, then flip the VideoListView - circuit-breaker back on +- [x] P3 view counts batched + re-enabled — viewCounter shares ONE kind-30079 + sub + backfill bucketed by `#a`; watch page opts into exact NIP-45 COUNT - [ ] P4 lists via stores (follows/hashtags/blocks/watch-history/profiles) - [ ] P5 AppState + Coordinator + unidirectional flow - [ ] P6 cleanup + config relay-set trim + final docs