.planning/phases/01-stabilize-video-pipeline/01-VERIFICATION.md

@@ -0,0 +1,159 @@
+---
+phase: 01-stabilize-video-pipeline
+verified: 2026-05-16T09:11:33Z
+verifier: gsd-verifier
+goal: The video ring buffer captures the most recent 30 s of the active tab's video continuously across tab switches, with a playable WebM header retained — so that on export the assembled `last_30sec.webm` will play.
+status: human_needed
+axes_total: 10
+axes_passed: 10
+axes_failed: 0
+axes_advisory: 2
+---
+
+# Phase 1: Stabilize Video Pipeline — Goal-Backward Verification
+
+## Phase Goal (verbatim from ROADMAP.md)
+
+> The video ring buffer captures the most recent 30 s of the active tab's video continuously across tab switches, with a playable WebM header retained — so that on export the assembled `last_30sec.webm` will play.
+
+## Verdict
+
+**DELIVERED** — 10 of 10 verification axes PASS against the codebase; phase goal is achieved by the wired implementation, not just by SUMMARY narration. Two **ADVISORY** notes recorded that do not block phase completion. Three **operator-side residue** items remain that THIS verifier cannot validate without a Chrome runtime — these MUST be picked up by Phase 4's SPEC §10 smoke pass.
+
+Status is `human_needed` because the residue items below require a real Chrome operator session (visual picker UX, tab-switch continuity, SW idle survival) — automated codebase verification is exhausted.
+
+---
+
+## Per-Axis Verification Table
+
+| #  | Axis                                              | Evidence (file:line or command)                                                                                                                                                                                  | Verdict   |
+| -- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
+| 1  | "30 s ring buffer" — constants + rotation         | `src/offscreen/recorder.ts:23-29` (`SEGMENT_DURATION_MS=10_000`, `MAX_SEGMENTS=3`, `VIDEO_BUFFER_DURATION_MS = 30_000`); `:86-89` push + shift cap; `:352-355` production rotation evict-oldest                  | PASS      |
+| 2  | "Continuous across tab switches" — no re-acquire  | `grep -RIn "onActivated\|onUpdated\|re-attach\|reAttach" src/` returns **no matches** (exit 1); `src/offscreen/recorder.ts:46` comment pins same-MediaStream across rotations; `getDisplayMedia` is screen/window-scoped per D-01 | PASS      |
+| 3  | "Playable WebM" — D-13 per-segment self-contained | `src/offscreen/recorder.ts:252-302` `startNewSegment` constructs fresh MediaRecorder per rotation; `:349-370` `onSegmentStopped` finalizes & rotates; `tests/offscreen/segment-keyframes.test.ts:195-269` GREEN-pins "each retained segment starts with a keyframe" + 30-s window invariant | PASS      |
+| 4  | "D-12 base64 wire transfer"                       | `src/shared/binary.ts:42-85` round-trip helpers; `src/shared/types.ts:64-68` `TransferredVideoSegment.data: string` (base64); `src/offscreen/recorder.ts:574` `await blobToBase64`; `src/background/index.ts:188` `base64ToBlob`; `tests/offscreen/port-serialization.test.ts` 9 tests GREEN | PASS      |
+| 5  | "T-1-04 sender-id check both ends"                | offscreen-side: `src/offscreen/recorder.ts:465-467` `isFromOwnExtension`, `:646` enforced on onMessage; SW-side: `src/background/index.ts:83-87` rejects port with mismatched sender, `:514-517` rejects onMessage with mismatched sender | PASS      |
+| 6  | "SW respawn safety"                               | `src/background/index.ts:33-35` Promise; `:548-552` `OFFSCREEN_READY` resolves; `:576-595` `hasDocument()` check + early-resolve on detected pre-existing offscreen (CR-03 fix); `:608-613` `indexedDB.deleteDatabase('VideoRecorderDB')` in `onInstalled` | PASS      |
+| 7  | "Manifest aligned"                                | `manifest.json:6-13` lists `desktopCapture` + `offscreen`; **no `tabCapture`**; `grep -RIn "tabCapture\|chrome.alarms" src/` returns **no matches** (exit 1); `chrome.runtime.connect` port replaces alarms keepalive (recorder.ts:606-631 + background/index.ts:78-118) | PASS      |
+| 8  | "Fixture validity"                                | `tests/fixtures/last_30sec.webm` exists (1 633 459 bytes); `ffprobe -v error -f matroska -i ...` → exit 0, empty stderr; codec=vp9 Profile 0, 1142×1038, bt709                                                       | PASS      |
+| 9  | "Acceptance tests aligned"                        | `tests/offscreen/webm-playback.test.ts:94-114` `decodeDryRunStrict` invokes ffmpeg via `spawnSync` and parses stderr for packet-error + ended-prematurely; `npx vitest run` shows both empirical gates execute (988 ms + 914 ms) and PASS | PASS      |
+| 10 | "Code-review aftermath — no regression"           | 7 test files / 40 tests all green; tsc exit 0; type-safety grep clean; `npm run build` exit 0 (60 modules, dist/ produced); sweep commits 08a79a6 (stop-race), 7c91f52 (re-entrance + start-throw + dual-track teardown), 034155b (port-replaced diagnostic) inspected and preserve D-12/D-13 contracts | PASS      |
+
+**Score: 10/10 axes verified.**
+
+---
+
+## Required Artifacts (3-level check)
+
+| Artifact                                | Expected                                                                  | Status   | Details                                                                                                                                                                |
+| --------------------------------------- | ------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/offscreen/recorder.ts`             | getDisplayMedia + D-13 lifecycle + port + handshake                       | VERIFIED | Exists (673 lines, substantive); imported by offscreen/index.html via crxjs; bootstrap() runs on module load; ALL ring-buffer constants, classifier, lifecycle hardening present |
+| `src/background/index.ts`               | SW with port-based fetch, T-1-04 sender check, hasDocument check          | VERIFIED | Exists (618 lines); receives port via onConnect; runs `chrome.offscreen.hasDocument()` on init; CR-03 fix early-resolves `offscreenReady` on detected pre-existing offscreen |
+| `src/shared/binary.ts`                  | D-12 base64 ↔ Blob helpers                                                | VERIFIED | Exists (85 lines); pure, portable (no FileReader); pinned by 9 tests in port-serialization.test.ts                                                                       |
+| `src/shared/types.ts`                   | `VideoSegment` + `TransferredVideoSegment` wire-format                    | VERIFIED | `VideoSegment {data: Blob; timestamp}` + `TransferredVideoSegment {data: string; type; timestamp}` both present; `Message<T = unknown>` post-IN-05                       |
+| `manifest.json`                         | `desktopCapture` + `offscreen` permissions; NO `tabCapture`               | VERIFIED | Confirmed line-by-line                                                                                                                                                  |
+| `tests/offscreen/*.test.ts` (7 files)   | codec-check, handshake, port, port-serialization, segment-keyframes, segment-rotation, webm-playback | VERIFIED | All 7 present; ring-buffer.test.ts retired (IN-03) leaving 7 file × 40-test surface                                                                                       |
+| `tests/fixtures/last_30sec.webm`        | Empirical D-13 regression fixture                                         | VERIFIED | 1 633 459 bytes; vp9 1142×1038; ffprobe + ffmpeg dry-run both exit 0                                                                                                     |
+
+---
+
+## Key Link Verification
+
+| From                                                | To                                          | Via                                                          | Status | Details                                                                                                                                                       |
+| --------------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `offscreen/index.html`                              | `src/offscreen/recorder.ts`                 | `<script type="module" src="./recorder.ts">`                 | WIRED  | Confirmed at `src/offscreen/index.html:8`; crxjs picks up via rollupOptions.input in vite.config.ts                                                              |
+| `recorder.ts: encodeAndSendBuffer`                  | `binary.ts: blobToBase64`                   | `import { blobToBase64 } from '../shared/binary'`            | WIRED  | Imported at `recorder.ts:18`; called at `:574`                                                                                                                  |
+| `background/index.ts: getVideoBufferFromOffscreen`  | `binary.ts: base64ToBlob`                   | `import { base64ToBlob, blobToBase64 } from '../shared/binary'` | WIRED  | Imported at `background/index.ts:2`; called at `:188`; result wrapped in `VideoSegment[]` returned to `saveArchive` → `createArchive` → archive `video/last_30sec.webm` entry |
+| `recorder.ts: connectPort`                          | `background/index.ts: onConnect listener`   | `chrome.runtime.connect({ name: 'video-keepalive' })`        | WIRED  | port name match enforced at `background/index.ts:80-82`; sender-id at `:83-87`                                                                                  |
+| `recorder.ts: bootstrap → sendMessage`              | `background/index.ts: OFFSCREEN_READY case` | `chrome.runtime.sendMessage({ type: 'OFFSCREEN_READY' })`    | WIRED  | resolves `offscreenReady` Promise at `background/index.ts:548-552`                                                                                              |
+| `background/index.ts: startVideoCapture`            | `recorder.ts: startRecording`               | `chrome.runtime.sendMessage({ type: 'START_RECORDING' })`    | WIRED  | recorder.ts dispatches in `onMessage` switch at `:649-654`                                                                                                       |
+
+---
+
+## Data-Flow Trace (Level 4 — Real Data Production)
+
+| Artifact                       | Data Variable                  | Source                                                                  | Produces Real Data           | Status   |
+| ------------------------------ | ------------------------------ | ----------------------------------------------------------------------- | ---------------------------- | -------- |
+| `recorder.ts: segments`        | `let segments: Blob[]`         | `onSegmentStopped → new Blob(currentChunks) → push` driven by MediaRecorder.onstop  | YES — real ~10 s WebM blobs from MediaRecorder | FLOWING  |
+| `recorder.ts: encodeAndSendBuffer` | `transferred[]`            | `await blobToBase64(segment)` per segment, sent over port                | YES — round-trip pinned by tests; empirical fixture proves end-to-end | FLOWING  |
+| `background/index.ts: mergeVideoSegments` | `finalBlob`            | `new Blob(sortedSegments.map(s => s.data))`                              | YES — empirical fixture: 1.6 MB VP9 playable file | FLOWING  |
+| `tests/fixtures/last_30sec.webm` | n/a (empirical fixture)      | regenerated 2026-05-15 (commit cd61cbc) against D-13 recorder           | YES — ffprobe exit 0 + ffmpeg dry-run exit 0 + operator-confirmed Chrome playback | FLOWING  |
+
+---
+
+## Behavioral Spot-Checks
+
+| Behavior                                            | Command                                                                                                              | Result                                                                                                                                                  | Status |
+| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
+| Vitest suite passes                                 | `npx vitest run --reporter=dot`                                                                                      | Test Files 7 passed (7); Tests 40 passed (40); 3.06s                                                                                                     | PASS   |
+| TypeScript type-check passes                        | `npx tsc --noEmit`                                                                                                   | exit 0 (no output)                                                                                                                                       | PASS   |
+| No `as any` or `@ts-ignore` in Phase 1 surface      | `grep -RIn "as any\|@ts-ignore" src/offscreen/ src/background/index.ts src/shared/`                                  | exit 1 (no matches)                                                                                                                                      | PASS   |
+| No `tabCapture` / `chrome.alarms` residue           | `grep -RIn "tabCapture\|chrome.alarms" src/`                                                                         | exit 1 (no matches)                                                                                                                                      | PASS   |
+| No legacy IndexedDB SW plumbing                     | `grep -rn "openIndexedDB\|VideoRecorderDB" src/ --include='*.ts'`                                                    | Only matches: orphan-cleanup `indexedDB.deleteDatabase('VideoRecorderDB')` at `background/index.ts:609-610` (intentional)                                | PASS   |
+| Legacy top-level `offscreen/` directory removed     | `ls offscreen/`                                                                                                       | exit 2 — directory does not exist                                                                                                                       | PASS   |
+| Vite inline-plugin removed                          | `grep -rn "copy-offscreen\|chromeMediaSource" vite.config.ts`                                                        | exit 1 (no matches)                                                                                                                                      | PASS   |
+| Build produces loadable extension                   | `npm run build`                                                                                                       | 60 modules transformed, exit 0; `dist/manifest.json`, `dist/assets/offscreen-*.js`, `dist/assets/index.ts-*.js` (SW) all produced                          | PASS   |
+| Fixture decodable by ffprobe (D-12 gate)            | `ffprobe -v error -f matroska -i tests/fixtures/last_30sec.webm`                                                     | exit 0; empty stderr                                                                                                                                     | PASS   |
+| Fixture passes A3 empirical decode dry-run          | `ffmpeg -nostdin -v warning -i tests/fixtures/last_30sec.webm -f null -`                                              | exit 0; **0** packet errors; **0** "File ended prematurely"; 298 DTS-monotonicity warnings (expected D-13 trade-off) + 1 "File extends beyond end of segment" (advisory, see below) | PASS   |
+
+---
+
+## Requirements Coverage
+
+| Requirement              | Source Plan      | Description                                                                                            | Status     | Evidence                                                                                                                                                                  |
+| ------------------------ | ---------------- | ------------------------------------------------------------------------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| REQ-video-ring-buffer    | Phase 1 (all 7 plans) | 30 s in-memory ring buffer via D-13 restart-segments; `getDisplayMedia` (AMENDED from `chrome.tabCapture`); vp9 @ 400 000 bps | SATISFIED  | All structural + empirical + wiring evidence above; SPEC §10 #2/#3/#7 functionally green at Phase 1 level                                                                  |
+
+**Phase 4 (SPEC §10 smoke) still owns the canonical 9-criterion sweep.** Phase 1 only proved #2/#3/#7 against the codebase + fixture; #1 install, #6 < 5 s export latency, #8 password masking, #9 RAM ceiling, and end-to-end Chrome runtime confirmation remain Phase 4 scope. This is by design per REQUIREMENTS.md line 188.
+
+---
+
+## Anti-Patterns Found
+
+| File                                | Line     | Pattern                                                                            | Severity | Impact                                                                                                                                                                                                       |
+| ----------------------------------- | -------- | ---------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| (none)                              | —        | No TODO/FIXME/XXX/HACK in Phase 1 surface; no `as any` / `@ts-ignore`; no `console.log`-only handlers; no empty `=> {}` rendering paths; no hardcoded empty arrays/objects flowing to user-visible output | —        | Clean.                                                                                                                                                                                                       |
+
+The `ffmpeg` stderr emits a single `File extends beyond end of segment` line — this is **Matroska-demuxer-level informational**, not a decoder error, and is the documented D-13 trade-off (multi-EBML-header concat). Recorded as ADVISORY below, not as an anti-pattern.
+
+---
+
+## Advisory Observations
+
+These do NOT block Phase 1 completion but warrant attention in Phase 4 or Phase 5.
+
+1. **ADV-1: ffmpeg emits one `[in#0/matroska,webm] File extends beyond end of segment` line.** This is the Matroska demuxer noting that the SECOND EBML segment in the concatenated WebM declares a smaller `SegmentSize` than the remaining bytes (because subsequent segments follow). Chrome's MSE pipeline handles this natively — operator-confirmed playback was clean on 2026-05-15. The `webm-playback.test.ts` acceptance gate does NOT assert against this signal (only `packetErrorCount === 0` and `endedPrematurely === false`), so it is correctly NOT a failure. Recommend documenting this signal in the Phase 5 cursor-visibility plan's "expected stderr from ffmpeg dry-run" allow-list to prevent future verifiers from being surprised by it.
+
+2. **ADV-2: `blobToBase64` per-byte concat is O(n²) for large blobs.** WR-06 in REVIEW-FIX.md was pre-approved for Phase 2 deferral with the documented rationale (`String.fromCharCode(...subarray)` apply-spread argument-length limit ~64 KiB). For the current ~1.6 MB fixture this works fine; if recording quality rises (higher bitrate, longer windows, audio in CAP-01) the encode latency could grow non-linearly. Phase 2 quality-bump review should consider chunked-apply at 32 KiB stride per REVIEW.md's WR-06 recommendation.
+
+---
+
+## Operator-Side Residue (UAT scope)
+
+These behaviors CANNOT be verified by this codebase verifier — they require a real Chrome runtime and an operator. Phase 4 SPEC §10 smoke pass MUST cover them:
+
+1. **OPR-1: `getDisplayMedia` picker UX appears and grants stream on operator click.** Chrome's native screen-share picker dialog cannot be driven from Vitest's Node environment. Verification path: load `dist/` unpacked → click extension → observe picker dialog → pick "Entire screen" → confirm "Sharing your screen" indicator appears → SW console shows `[Offscreen:Recorder] Stream created`. (VALIDATION.md §"Manual-Only Verifications" row 1.)
+
+2. **OPR-2: Continuous recording across tab switches under live `getDisplayMedia` stream.** Codebase verification confirms NO per-tab re-acquisition code exists (no `chrome.tabs.onActivated` handlers; recorder retains single `MediaStream` across rotations); this is a SUFFICIENT structural condition. Empirical confirmation that the recording does NOT pause when the operator switches tabs in Chrome requires a live session. Verification path: start recording, switch tabs 3-5 times over 30 s, export, confirm `last_30sec.webm` covers the full 30 s window. (VALIDATION.md §"Manual-Only Verifications" row 2 analogue, applied to amended D-15 semantics.)
+
+3. **OPR-3: SW idle-unload survival.** D-16 + D-17 are structurally satisfied (offscreen owns buffer; long-lived port keeps SW alive; `hasDocument()` + CR-03 handshake fix on SW respawn). Real MV3 SW lifecycle behavior cannot be driven in Vitest. Verification path: DevTools → Extensions → Service Worker → "Force stop" → wait 60 s → click extension save → confirm exported archive contains video segments from before "Force stop". (VALIDATION.md §"Manual-Only Verifications" row 3.)
+
+These three items are Phase 4's territory per ROADMAP.md (Phase 4 success criteria #2 and #4 in particular). This verifier does NOT classify them as Phase 1 gaps — Phase 1's `human_needed` status is the correct routing: ship Phase 1 as DELIVERED in code, hand the operator-side checks to Phase 4 smoke.
+
+---
+
+## Gaps Summary
+
+No gaps. Phase 1's goal — "the video ring buffer captures the most recent 30 s of the active tab's video continuously across tab switches, with a playable WebM header retained — so that on export the assembled `last_30sec.webm` will play" — is achieved by the wired codebase:
+
+- **30 s buffer:** `MAX_SEGMENTS=3 × SEGMENT_DURATION_MS=10_000 = 30_000` ms enforced in production (`onSegmentStopped:352-355`) AND pinned by tests (`segment-rotation.test.ts:84-104`, "caps at MAX_SEGMENTS — 4th push evicts the oldest", "many pushes never exceed the cap").
+- **Continuous across tab switches:** Amended D-01/D-15 semantics under `getDisplayMedia` — no per-tab handlers exist, single MediaStream retained across MediaRecorder rotations (recorder.ts:46 comment + grep evidence).
+- **Playable WebM:** D-13 restart-segments — each segment self-contained with own EBML header + seed keyframe (`startNewSegment:252-302` constructs fresh MediaRecorder per rotation); empirically verified by ffmpeg dry-run exit 0 + 0 packet errors + 0 ended-prematurely.
+- **Assembled `last_30sec.webm` plays:** Empirical fixture `tests/fixtures/last_30sec.webm` (1.6 MB) passes both D-12 (ffprobe) and A3 (ffmpeg) gates, operator-confirmed Chrome playback on 2026-05-15.
+
+The two architectural escalations encountered mid-phase (D-12 binary transfer + A3 keyframe orphan-P-frame) were both anticipated as HIGH-risk in RESEARCH.md and resolved by pre-staged fallbacks (base64 wire format + D-13 restart-segments); both fallbacks are now production code and pinned by tests.
+
+---
+
+_Verified: 2026-05-16T09:11:33Z_
+_Verifier: Claude (gsd-verifier)_