---
phase: 02-stabilize-export-pipeline
plan: 01
type: tdd
wave: 1
depends_on: []
files_modified:
- tests/background/blob-url-download.test.ts
- tests/background/meta-json-urls-schema.test.ts
- tests/build/strict-meta-json-validation.test.ts
autonomous: true
requirements:
- REQ-archive-export-latency
- REQ-meta-json-schema
tags:
- tdd
- red-tests
- blob-url-migration
- meta-json-urls-array
- schema-validation
- p0-6
- p1-10
- wave-0
must_haves:
truths:
- "Three RED test files exist and fail under the current HEAD (cc042a5) with concrete failure messages, NOT timeouts or missing imports."
- "blob-url-download.test.ts pins downloadArchive() calling chrome.downloads.download with url starting with 'blob:' (not 'data:application/zip;base64,')."
- "meta-json-urls-schema.test.ts pins SessionMetadata.urls as string[], createArchive emitting meta.json with urls (not url), AND the F2-pinned empty-tracker contract (urls: [] for whole-desktop-no-tab sessions; NO sentinel fallback)."
- "strict-meta-json-validation.test.ts pins ISO-8601 Z-suffix timestamp, urls is an Array of filter-matching URLs (empty PERMITTED per F2 resolution), semver extensionVersion, non-negative totalEvents, exactly 8 fields."
- "All 3 files use Vitest describe+it patterns matching existing tests/background/*.test.ts conventions (vi.fn() chrome.* stubs; jsdom or node env per existing patterns)."
- "Tier-1 FORBIDDEN_HOOK_STRINGS unit-test gate remains GREEN (12 entries unchanged — this plan adds no test-hook symbols)."
- "153/153 baseline vitest count rises to 153 + N (where N = number of new it() blocks; expected ~16 after F2 added Test 5 to meta-json-urls-schema.test.ts)."
artifacts:
- path: "tests/background/blob-url-download.test.ts"
provides: "RED pin: downloadArchive calls chrome.downloads.download({ url: blob:..., filename })"
min_lines: 80
contains: "describe.*blob.*url|chrome.downloads.download"
- path: "tests/background/meta-json-urls-schema.test.ts"
provides: "RED pin: SessionMetadata.urls: string[] + createArchive emits meta.json.urls"
min_lines: 60
contains: "urls.*string\\[\\]|meta\\.json"
- path: "tests/build/strict-meta-json-validation.test.ts"
provides: "RED pin: 8-field schema with ISO-8601 + semver + non-empty urls[] + non-negative totalEvents"
min_lines: 80
contains: "ISO-8601|semver|urls"
key_links:
- from: "tests/background/blob-url-download.test.ts"
to: "src/background/index.ts:downloadArchive"
via: "vi.mocked(chrome.downloads.download) inspection of first-call args[0].url prefix"
pattern: "chrome\\.downloads\\.download.*url.*blob:"
- from: "tests/background/meta-json-urls-schema.test.ts"
to: "src/background/index.ts:createArchive + src/shared/types.ts:SessionMetadata"
via: "createArchive() returns Blob; unzip via JSZip; read meta.json; assert .urls is Array, .url is undefined"
pattern: "metadata\\.urls|metadata\\.url"
- from: "tests/build/strict-meta-json-validation.test.ts"
to: "meta.json wire shape (post-Plan 02-03)"
via: "regex assertions on timestamp / version / totalEvents + Array.isArray(urls) + Object.keys(meta).length === 8"
pattern: "Object\\.keys.*length.*8|Array\\.isArray.*urls"
---
Wave 0 RED gate for Phase 2: three failing test files that pin the locked
decisions D-P2-01 (Blob URL download), D-P2-02 (meta.json urls[] migration),
and D-P2-03's schema-validation workstream. These tests MUST be RED at the
end of this plan and MUST flip GREEN as Plans 02-02 and 02-03 land
implementation.
Purpose: pin the contracts BEFORE any production code changes (TDD discipline
matching Plan 01-02 Wave 0 precedent). Without RED tests committed first,
nothing forces D-P2-01/D-P2-02/D-P2-03 to be implemented exactly as locked —
silent partial implementation could land otherwise.
Output:
- tests/background/blob-url-download.test.ts (RED — pins D-P2-01)
- tests/background/meta-json-urls-schema.test.ts (RED — pins D-P2-02)
- tests/build/strict-meta-json-validation.test.ts (RED — pins D-P2-03 schema)
- vitest count rises by N RED tests (acceptable RED window — closed by Plans 02-02 + 02-03 within the same Phase 2 execution)
@$HOME/.claude/get-shit-done/workflows/execute-plan.md
@$HOME/.claude/get-shit-done/templates/summary.md
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/REQUIREMENTS.md
@.planning/STATE.md
@.planning/phases/02-stabilize-export-pipeline/02-CONTEXT.md
# Source under test
@src/background/index.ts
@src/shared/types.ts
@src/shared/binary.ts
# Precedent for RED test style (Plan 01-02 Wave 0 + Plan 01-08 webm-remux deps test)
@.planning/phases/01-stabilize-video-pipeline/01-08-SUMMARY.md
From src/shared/types.ts (CURRENT — pre-Plan-02-03):
```typescript
export interface SessionMetadata {
timestamp: string;
url: string; // ← D-P2-02 MIGRATES THIS to urls: string[]
userAgent: string;
extensionVersion: string;
videoBufferSeconds: number;
logDurationMinutes: number;
totalEvents: number;
}
```
From src/background/index.ts:695-718 (CURRENT downloadArchive — pre-Plan-02-02):
```typescript
async function downloadArchive(archiveBlob: Blob) {
const filename = `session_report_${dateStr}_${timeStr}.zip`;
const base64 = await blobToBase64(archiveBlob);
const url = `data:application/zip;base64,${base64}`; // ← D-P2-01 MIGRATES THIS to blob:URL
await chrome.downloads.download({ url, filename, saveAs: false });
}
```
From src/background/index.ts:608-692 (CURRENT createArchive — pre-Plan-02-03):
```typescript
async function createArchive(videoBufferResponse, rrwebEvents, userEvents, screenshot): Promise {
// ... assembles zip ...
const metadata: SessionMetadata = {
timestamp: new Date().toISOString(),
url: new URL(chrome.runtime.getURL('')).origin, // ← D-P2-02 MIGRATES TO urls: string[]
userAgent: navigator.userAgent,
extensionVersion: manifest.version,
videoBufferSeconds: 30,
logDurationMinutes: 10,
totalEvents: rrwebEvents.length + userEvents.length
};
zip.file('meta.json', JSON.stringify(metadata, null, 2));
const archiveBlob = await zip.generateAsync({ type: 'blob' });
return archiveBlob;
}
```
Existing test conventions (read these for stub patterns):
- `tests/background/save-archive-does-not-stop-recording.test.ts` — chrome.runtime + chrome.downloads stub pattern
- `tests/background/webm-remux.test.ts` — JSZip + Blob unzip pattern
- `tests/build/no-remote-fonts.test.ts` — post-build dist/ scan pattern (model for strict-meta-json-validation.test.ts STRUCTURE; this plan's variant scans createArchive's output, not dist/)
Task 1: RED — blob-url-download.test.ts pins D-P2-01
tests/background/blob-url-download.test.ts
- Test 1 ("downloadArchive calls chrome.downloads.download with a blob: URL, NOT a data:application/zip;base64, URL"):
stub chrome.downloads.download via vi.fn(); invoke downloadArchive(testBlob); assert
mockDownload.mock.calls[0][0].url starts with 'blob:' AND does NOT start with 'data:application/zip;base64,'.
- Test 2 ("downloadArchive completes within 5000ms for a 6 MB archive"):
build a synthetic 6 MB Blob (above Chrome's ~2 MB data-URL cap that motivates D-P2-01);
measure performance.now() before/after downloadArchive; assert delta < 5000.
- Test 3 ("URL.revokeObjectURL is scheduled for the minted URL after chrome.downloads.onChanged 'complete' event"):
stub chrome.downloads.onChanged.addListener via vi.fn(); invoke downloadArchive(testBlob);
simulate the listener callback firing with {state: {current: 'complete'}, id: };
assert URL.revokeObjectURL was called with the same url passed to chrome.downloads.download.
- All 3 tests MUST fail under current HEAD with `url` starting with `data:application/zip;base64,`
(Test 1), exceeding the 5000ms budget for the 6 MB case OR throwing "Network error" if Chrome's
data-URL cap rejects (Test 2 — accept either failure mode as the RED signal), and NEVER calling
URL.revokeObjectURL because the current path doesn't mint one (Test 3).
Create `tests/background/blob-url-download.test.ts` per the behavior block above.
Follow `tests/background/save-archive-does-not-stop-recording.test.ts` for the chrome.* stub pattern
(vi.stubGlobal('chrome', { runtime: ..., downloads: { download: vi.fn(), onChanged: { addListener: vi.fn() } } })).
Use `import { downloadArchive } from '../../src/background/index'` ONLY IF downloadArchive is exported;
if NOT, the test imports an internal-helper-export OR uses the saveArchive path with chrome.downloads.download
spy — pick whichever the existing save-archive test uses. Document the choice in a comment block.
Use jsdom env (default in vitest.config.ts) so URL.createObjectURL + URL.revokeObjectURL are available.
For Test 2's 6 MB blob: `new Blob([new Uint8Array(6 * 1024 * 1024)], { type: 'application/zip' })`.
Per D-P2-01 — this test pins downloadArchive's WIRE FORMAT (blob: vs data:), the LATENCY
PROPERTY (which only Blob URL achieves for >2 MB archives), and the LIFECYCLE
(URL.revokeObjectURL hooked to chrome.downloads.onChanged 'complete'). The implementation
in Plan 02-02 will mint the Blob URL inside the offscreen document (D-P2-01) and pass it
back to the SW via a new port-bridge message; this test does not encode HOW the URL is
minted, only WHAT the SW downloadArchive call site sends to chrome.downloads.download.
npx vitest run tests/background/blob-url-download.test.ts 2>&1 | grep -E "(FAIL|RED|failed)" | head -5
File `tests/background/blob-url-download.test.ts` exists, exports 3 it() blocks under a
single describe, ALL 3 fail with concrete assertion errors (NOT import errors / NOT timeouts).
`npx vitest run tests/background/blob-url-download.test.ts --reporter=verbose` shows
3 failed tests with assertion messages identifying the wrong url prefix / latency / missing revoke.
Commit message: `test(02-01): RED — pin Blob URL download contract (D-P2-01)`.
Task 2: RED — meta-json-urls-schema.test.ts pins D-P2-02
tests/background/meta-json-urls-schema.test.ts
- Test 1 ("SessionMetadata.urls is string[], SessionMetadata.url does not exist"):
`import type { SessionMetadata } from '../../src/shared/types'`; use a `satisfies` check
OR a `const _check: SessionMetadata['urls'] extends string[] ? true : false = true` pattern
so the test is compile-time-checked AND runtime-introspectable. RED state: TypeScript
tsc compile of this test currently fails because `urls` is not on SessionMetadata yet.
Wrap the type-level check in a runtime `expect(true).toBe(true)` so the failure mode is
"tsc compile failure" → flips GREEN after Plan 02-03 amends types.ts.
- Test 2 ("createArchive emits meta.json with `urls: string[]`, not `url: string`"):
stub chrome.runtime.getManifest + navigator.userAgent + the offscreen video-buffer fetch
(return a minimal 1-segment VideoBufferResponse so remux doesn't blow up — reuse pattern
from webm-remux.test.ts); invoke createArchive(); extract meta.json from the returned
Blob via JSZip.loadAsync + zip.file('meta.json').async('string') + JSON.parse;
assert `Array.isArray(meta.urls) === true` AND `meta.url === undefined`.
- Test 3 ("meta.json.urls is deduplicated and ordered first-seen-first"):
mock the tab-tracking source (chrome.tabs.query OR a yet-to-be-implemented module helper —
see "module seam" note below); inject 3 tab URL events: A, B, A;
assert `meta.urls` equals `['A', 'B']` (dedup; A appears once; first-seen order preserved).
- Test 4 ("chrome:// and about: URLs are filtered out; chrome-extension:// included"):
inject 4 events: 'https://example.com', 'chrome://newtab', 'about:blank',
'chrome-extension://abc/popup.html'; assert `meta.urls` equals
`['https://example.com', 'chrome-extension://abc/popup.html']` (per CONTEXT.md
"URL filter" specifics block).
- Test 5 ("empty-tracker → meta.urls === []", per F2 plan-checker iteration 1):
mock the tab-tracking source to return an EMPTY array (whole-desktop-no-tab session);
invoke createArchive; assert `meta.urls` is EXACTLY `[]` (empty Array; not undefined; not
`[extension-origin-URL]`; not `null`). This pins the F2 resolution: NO sentinel fallback.
The empty array is the canonical representation of a whole-desktop recording with no browser
tabs open at SAVE time.
- All 5 tests MUST fail under current HEAD: Test 1 via tsc compile failure (urls missing on type);
Test 2 via `meta.url` present + `meta.urls` undefined; Test 3+4+5 via the tab-tracking module
not existing yet (these will throw import errors — acceptable as the RED signal).
Create `tests/background/meta-json-urls-schema.test.ts` per the behavior block above.
Module seam for tab tracking: assume Plan 02-03 will introduce a new module (planner-suggested name:
`src/background/tab-url-tracker.ts`) exporting `getTabUrlsSeen(): string[]`. The test imports
this seam by name; the absence of the module at the current HEAD is the RED signal for Tests 3+4.
Document the seam name + expected export in a block comment at the top of the test file so Plan
02-03 implements against the same shape.
For Test 2's createArchive invocation: pattern after `tests/background/webm-remux.test.ts` and
`tests/background/save-archive-does-not-stop-recording.test.ts` — stub VideoBufferResponse with
a single 1-byte segment (createArchive's remux path needs at least 1 to not throw
EmptyVideoBufferError; use a pre-baked fixture Blob OR mock remuxSegments via vi.spyOn).
Per D-P2-02 — this test pins the SHAPE (urls: string[] not url: string), the DEDUP+ORDER semantics
(first-seen-first), and the FILTER (exclude chrome:// + about:; include chrome-extension://) verbatim
from CONTEXT.md `` block. The implementation in Plan 02-03 implements the tab-tracker
+ amends types.ts + amends createArchive's meta.json construction.
npx vitest run tests/background/meta-json-urls-schema.test.ts 2>&1 | grep -E "(FAIL|RED|failed|TS\d+)" | head -10
File exists, 5 it() blocks under a single describe. Test 1 fails via tsc compile error on missing
`urls` field. Tests 2-5 fail with assertion errors OR import errors (latter for the missing
tab-url-tracker module). NONE pass under current HEAD.
Commit message: `test(02-01): RED — pin meta.json urls[] schema + dedup/filter + empty-tracker semantics (D-P2-02 + F2)`.
Task 3: RED — strict-meta-json-validation.test.ts pins D-P2-03 schema
tests/build/strict-meta-json-validation.test.ts
- Test 1 ("meta.json has exactly 8 fields"): Object.keys(meta).length === 8.
- Test 2 ("timestamp is ISO-8601 with Z suffix"):
`/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z$/.test(meta.timestamp)`.
- Test 3 ("urls is an Array of valid URLs; empty IS PERMITTED for whole-desktop sessions"):
`Array.isArray(meta.urls) && meta.urls.every(u => /^(https?|chrome-extension):\/\//.test(u))`.
Per F2 (plan-checker iteration 1 resolution): the empty-tracker case is MEANINGFUL (whole-desktop
recording with no browser tabs open). The strict-validation rule from D-P2-03 ("urls array
non-empty") is RELAXED to PERMIT empty arrays here; CONTEXT.md `` permissive clause
wins over the original D-P2-03 strict clause. Operator empirical workflow (Plan 02-04 Task 4
Step 2) verifies the non-empty case via the multi-tab path. Document this resolution inline
in the test as a block comment citing both CONTEXT.md sources AND the F2 plan-checker
iteration 1 decision.
- Test 4 ("extensionVersion matches semver"): `/^\d+\.\d+\.\d+$/.test(meta.extensionVersion)`.
- Test 5 ("totalEvents is non-negative integer"):
`Number.isInteger(meta.totalEvents) && meta.totalEvents >= 0`.
- Test 6 ("videoBufferSeconds is exactly 30"): per CON-meta-json-schema verbatim.
- Test 7 ("logDurationMinutes is exactly 10"): per CON-meta-json-schema verbatim.
- Test 8 ("no extra fields"): Object.keys(meta).every(k => EXPECTED_KEYS.includes(k))
where EXPECTED_KEYS = ['timestamp','urls','userAgent','extensionVersion','videoBufferSeconds','logDurationMinutes','totalEvents'] PLUS one of {schemaVersion?, archiveVersion?} ← reserve one slot for the 8th field. The current schema has 7; D-P2-03 says "8 fields exact". DECIDED INLINE: the 8th field is `urls` REPLACING `url` (net +0 → still 7 fields), BUT D-P2-03 explicitly says "8 fields exact". RESOLUTION: read the test as the strict-validation TARGET; the missing 8th field is the SHIPPING DECISION that Plan 02-03 must make and implement (planner suggests `schemaVersion: '2'` to mark the breaking-change cutover; documented as the implementer-choice in Plan 02-03). The RED test file embeds the EXPECTED_KEYS list including `schemaVersion` so Plan 02-03 has zero ambiguity.
- All 8 tests MUST fail under current HEAD (the createArchive meta.json shape doesn't match
most assertions — it has `url:string`, no `urls`, no `schemaVersion`, and 7 fields).
Create `tests/build/strict-meta-json-validation.test.ts` per the behavior block above.
Pattern after `tests/build/no-remote-fonts.test.ts` (a `tests/build/` validator) and
`tests/background/save-archive-does-not-stop-recording.test.ts` (createArchive invocation +
JSZip extract pattern). The test invokes createArchive() via the same path as Task 2's
`meta-json-urls-schema.test.ts`, extracts meta.json, JSON.parses it, and runs all 8 strict
schema checks.
The EXPECTED_KEYS constant at the top of the test:
```typescript
const EXPECTED_KEYS = [
'timestamp', 'urls', 'userAgent', 'extensionVersion',
'videoBufferSeconds', 'logDurationMinutes', 'totalEvents', 'schemaVersion',
];
```
The 8th field `schemaVersion` is the planner-suggested marker for the D-P2-02 url→urls
breaking-change cutover. Plan 02-03's implementer COMMITS to adding `schemaVersion: '2'`
as a constant in src/background/index.ts; the test pins this so Plan 02-03 cannot land
a 7-field meta.json that satisfies Tests 1-7 but fails the "exactly 8 fields" + "no extra fields"
pair. (Plan-checker may revise this — the 8th field name is a TENTATIVE PLANNER PICK;
if Plan 02-03's implementer or Plan 02-04 has a stronger argument for a different 8th
field name, this test file becomes the canonical place to amend.)
Add a block comment at the top citing CONTEXT.md D-P2-03 + REQUIREMENTS.md REQ-meta-json-schema
as the contract source, and noting the planner-resolved tension between Tests 3's non-empty
rule (per D-P2-03) and the CONTEXT.md `` permissive empty-array clause.
npx vitest run tests/build/strict-meta-json-validation.test.ts 2>&1 | grep -E "(FAIL|RED|failed)" | head -10
File exists, 8 it() blocks under a single describe. ALL 8 fail (current meta.json has 7 fields
+ `url:string` instead of `urls:string[]` + no `schemaVersion`).
Commit message: `test(02-01): RED — pin strict 8-field meta.json schema validation (D-P2-03)`.
## Trust Boundaries
| Boundary | Description |
|----------|-------------|
| test author → test runtime | Test code controls chrome.* stubs; only the SW/offscreen surfaces under test are exercised |
| createArchive output → JSZip parse | meta.json wire shape; D-P2-03 schema validation prevents downstream consumers (UAT harness, future SRV-* upload) from receiving malformed metadata |
## STRIDE Threat Register
| Threat ID | Category | Component | Disposition | Mitigation Plan |
|-----------|----------|-----------|-------------|-----------------|
| T-02-01-01 | Tampering | RED test as silent-skip risk (skip(true) / it.skip pattern slipping in) | mitigate | All 15 tests in this plan use bare `it()` + concrete expect()s; no `describe.skip` or `it.skip`. Plan-checker verifies grep -c "\.skip" $files == 0. |
| T-02-01-02 | Repudiation | RED tests committed without RED proof (CI shows GREEN because test imports failed silently) | mitigate | Task verify> blocks run `npx vitest run ` and grep for "FAIL" — proves RED state at commit time. Plan 02-02 + 02-03 implementers prove GREEN-flip via same grep with "PASS". |
| T-02-01-03 | Information Disclosure | Test creates real `meta.json` containing real `chrome.runtime.id` extension origin URL | accept | Tests run in jsdom + stubbed chrome.runtime.getURL returning fake 'https://test/'. Real origin never reaches test fixtures. |
- `npx vitest run tests/background/blob-url-download.test.ts` → 3 RED.
- `npx vitest run tests/background/meta-json-urls-schema.test.ts` → 5 RED (includes F2 empty-tracker → urls:[] pin).
- `npx vitest run tests/build/strict-meta-json-validation.test.ts` → 8 RED (Test 3 RELAXED to permit empty urls[]).
- `npm test` → previously-153 GREEN + N RED (16 ± 1 RED from this plan). Acceptable window —
Plans 02-02 + 02-03 close all RED before phase closure.
- `grep -c '\.skip' tests/background/blob-url-download.test.ts tests/background/meta-json-urls-schema.test.ts tests/build/strict-meta-json-validation.test.ts` → 0.
- Tier-1 grep gate: `npx vitest run tests/background/no-test-hooks-in-prod-bundle.test.ts` GREEN
(unchanged at 12 FORBIDDEN_HOOK_STRINGS — this plan touches NO production code, only test fixtures).
1. Three RED test files exist with concrete failure messages under current HEAD.
2. `meta-json-urls-schema.test.ts` Test 1 fails at the TypeScript-compile layer (proves the type
migration is genuinely required, not just a runtime field rename).
3. Tier-1 grep gate (12 FORBIDDEN_HOOK_STRINGS) remains GREEN.
4. UAT harness (24/24 GREEN baseline) UNCHANGED by this plan (test-only changes).
5. Commits land with `test(02-01): RED — ...` prefix matching Plan 01-02 / 01-13 RED-test precedent.