diff --git a/.planning/phases/01-reproducible-fidelity-baseline/01-02-SUMMARY.md b/.planning/phases/01-reproducible-fidelity-baseline/01-02-SUMMARY.md new file mode 100644 index 0000000..4b6c087 --- /dev/null +++ b/.planning/phases/01-reproducible-fidelity-baseline/01-02-SUMMARY.md @@ -0,0 +1,176 @@ +--- +phase: 01-reproducible-fidelity-baseline +plan: "02" +subsystem: testing +tags: [python, native-media, node, local-http, fidelity, evidence] +requires: + - phase: 01-01 + provides: Version 1 validated hashed receipts and scenario contract +provides: + - Self-contained review export with contained read-only loopback GET/HEAD ranges + - Independent event seeks, raw clocks, drift, exclusive audio and preserved tails + - Capability navigation with validated copied source text and explicit missing states +affects: [01-03, 01-05, 01-06, 01-07] +tech-stack: + added: [] + patterns: [stdlib-only export, native browser media, independent clocks, opt-in review aids, built-in Node tests] +key-files: + created: + - tools/recon/fidelity_review.py + - tools/recon/fidelity_viewer/index.html + - tools/recon/fidelity_viewer/viewer.mjs + - tools/recon/fidelity_viewer/style.css + - tests/test_fidelity_review.py + - tests/fidelity-viewer.test.mjs + modified: [] +key-decisions: + - "Review exports always retain OPEN acceptance; synthetic/history labels and absent original/native recordings stay explicit." + - "Pair playback uses rate 1 with separately observed event anchors, independent clocks, visible drift and explicit recovery; longer tails remain playable." + - "Capability source links are copied only from contained tracked bounded UTF-8 text; the viewer activates only exporter-validated local hrefs." +requirements-completed: [EVID-02, EVID-03, EVID-04] +requirements-acceptance: "OPEN: assigned tooling contributions only; shared EVID IDs remain Pending and real runtime coverage remains 0/120." +coverage: + - id: contained-review + description: Validated receipt export, contained HTTP seeking and local source links + requirement: EVID-02 + verification: + - kind: integration + ref: tests/test_fidelity_review.py + status: pass + human_judgment: false + - id: paired-controller + description: Event alignment, raw clocks, drift, exclusive audio, failure states and optional aids + requirement: EVID-03 + verification: + - kind: unit + ref: tests/fidelity-viewer.test.mjs + status: pass + - kind: automated_ui + ref: artifacts/fidelity/viewer-smoke-final/browser-result.json + status: pass + human_judgment: false + - id: real-audiovisual-review + description: Actual original/native recordings, audible source switching and browser/codec judgment + requirement: EVID-04 + verification: [] + human_judgment: true + rationale: "Headless synthetic playback verifies tooling only. Actual identified original/native media and audible review belong to the final combined session." +actuals: + tokens: 18814 + tasks: 2 + commits: 4 + basis: "ceil(chars/4) over the realized six-file production/test diff, excluding planning metadata" +plan_head_before: 6be848480288480208ac737c953b7c9bfc82bd84 +plan_head_after: 91da92f17d93ba80ead87f92cf4714b6635133bb +duration: 16 min +started: 2026-11-13T00:30:27Z +completed: 2026-11-13 +status: complete +--- + +# Phase 01 Plan 02: Local Paired Review Summary + +**Contained hashed-media export and actual-speed paired playback expose event/playback drift, exclusive audio, optional still differences and complete recording tails.** + +## Performance + +- Measured implementation window: first persisted RED evidence at 00:30:27 UTC through final verification at 00:46:15 UTC, rounded to 16 minutes. Required setup/context reads preceded this measurement. +- Two tasks; six source/test files; four task commits measured from the persisted ledger. +- Final exact checks: 21 Python review tests, 5.234 seconds including process startup; 27 Node tests, 0.120 seconds. Combined fidelity discovery: 72 tests, 6.318 seconds. Original inventory: 539 unchanged files, 0.268 seconds. +- Full logs and command/exit/time records: ignored `artifacts/fidelity/verification/01-02-*`. + +## Accomplishments + +- A real subprocess exports imported hashed receipts into a new self-contained directory. Tests read both media links and event metadata over actual loopback HTTP, including HEAD, prefix/open/suffix ranges and invalid-range rejection. +- Both recordings seek to their own observed markers after metadata/seek readiness. Explicit play preserves rate 1, and raw elapsed clocks, event offsets, event drift plus uncertainty, and browser playback drift remain separately visible. No follower seeks, duration normalization or retiming occur. +- Dedicated keyboard-accessible per-side play/pause/seek controls coexist with exclusive soundtrack selection and visibly labeled review-only volume. Buffering, missing media, decoding failure, play rejection, stale asynchronous actions and asymmetric endings remain explicit; the full longer tail can resume. +- Annotations and lossless image differences begin off and leave raw captures unobstructed. Difference eligibility requires identified PNGs, source-media hashes, corresponding observed event timestamps, matching dimensions/viewport/aspect/crop and successful image decoding. Differences have no numerical fidelity score. +- Capability navigation preserves supplied facts/current evidence/history, orders discrepancies by impact, and links copied validated source text. Empty ledger and missing-source states remain explicit. + +## Task Commits + +1. Task 01-02-01 RED: `488c904` — specify contained paired media review. +2. Task 01-02-01 GREEN: `49f874e` — export and serve validated local media pairs. +3. Task 01-02-02 RED: `75d7ca4` — specify truthful timing, audio and failure states. +4. Task 01-02-02 GREEN: `91da92f` — preserve clocks, exclusive audio and complete review tails. + +Normal hooks ran with scoped staging. No tracked files were deleted. The primary owns milestone review and push; this executor did not push. + +## Local Invocation and Interfaces + +```sh +python3 tools/recon/fidelity_review.py export \ + --original PATH/TO/IMPORTED-ORIGINAL/receipt.json \ + --port PATH/TO/IMPORTED-PORT/receipt.json \ + --ledger PATH/TO/CAPABILITY-EXPORT.json \ + --output artifacts/fidelity/review/NEW-PAIR +python3 tools/recon/fidelity_review.py serve \ + --root artifacts/fidelity/review/NEW-PAIR --port 8765 +``` + +Open `http://127.0.0.1:8765/`. Either receipt and the ledger may be omitted; absent evidence stays visible. Output must be a new directory. Invalid input exits 2. Serving requires a generated `.review-root.json` manifest and only binds `127.0.0.1`; it never serves the repository or Original directory. The exporter copies/revalidates bytes, retains raw artifacts/derivative ancestry, and never executes receipt argv. Failed publication retains its incomplete temporary sibling. + +Python APIs: `export_review(original, port, output, ledger=None)` returns the model; `make_server(root, port=8765, host='127.0.0.1')` returns an owned `ThreadingHTTPServer`. The caller closes/shuts down that server. The generated root contains `review.json`, the three viewer files, side-specific receipt/artifacts and optional `sources/` text. + +`review.json` version 1 contains `case_id`, `sides.original/port`, corresponding `events`, `ledger`, and explicit OPEN acceptance. Side records preserve kind/platform/scope/history/limits/identities, hashed `artifacts` with local `url`, selected `media`, observed `events`, `derivatives`, `receipt_url`, missing evidence and warnings. Only markers on the selected video/explicit preview are seekable; a preview without its own observed correspondence has visible gaps. Same case/scope and unambiguous event names are required. No timestamps are inferred from derivatives. + +ES module exports: `createPairController`, `safeLocalURL`, `differenceEligibility`, `framePair`, `renderCapabilities`. Controller methods are `selectEvent`, `play`, `playSide`, `seekSide`, `pause`, `snapshot`, `setAudio`, `setGain`, `setOverlay`, `dispose`; media elements and change callback are injected for testing. Volume starts at 1 and can be attenuated from 0 to 1. Both sources are muted before audio selection; dedicated UI controls prevent native media controls independently enabling another soundtrack. + +Optional PNG artifact metadata is `frame: {lossless,event,media_sha256,media_seconds,viewport:[w,h],crop:[x,y,w,h],width,height}`. It binds an identified PNG to its own selected source media and observed marker; unmatched provenance/dimensions disable the aid. PNG decoding must agree with declared dimensions. Raw video remains available, and still differences are review aids even when extracted from lossy video. + +The coordinated ledger input contract is `{schema_version:1, capabilities:[...]}` with SKELETON fields `id/group/requirement_ids/summary/verified_scope/differences/acceptance/source_links/scenario_ids/evidence/current/history/discrepancies`. Evidence/current/history are rendered read-only without inventing acceptance facts. `source_links` entries are `{label,path,sha256?}` with repo-relative paths. Export resolves containment, rejects symlinks/private/generated/original roots, requires tracked non-NUL UTF-8 text at most 1 MiB, and verifies optional hashes. Exported links add `{href,validated_local,sha256,size,missing}`; only validated `sources/...` hrefs become links. Safe missing/untracked references have `href:null`, `validated_local:false`, and a visible reason. Other imported HTML/commands remain inert. + +## Browser and Evidence Limits + +Installed Chromium `157.0.8103.38` decoded local synthetic VP8/Vorbis recordings through the real server. A loopback CDP check verified `.500/.750` event seeks while paused, subsequent actual-speed playback, original/port mute exclusivity, visible volume adjustment, opt-in annotations/difference canvas, a 390px layout without horizontal overflow, and explicit longer-tail playback after the 3.003-second recording ended while the 5.003-second recording retained its tail. The copied source-document link returned HTTP 200. No page runtime exceptions were observed. + +Ignored evidence is in `artifacts/fidelity/viewer-smoke-final/browser-result.json` and `browser.png`; fixture generation/CDP scripts are retained alongside them. The final generated synthetic viewer is `test-review-v3/` within that directory. Synthetic moving patterns and tones are labeled throughout, and no genuine original reference is implied. Browser media state checks do not prove audible hardware output or human audiovisual adequacy. + +The genuine existing port output `artifacts/window-transitions/2-VR04-1280x720.png` was hashed/imported separately as **historical port_fixture** evidence and exported to `historical-review/`. Chromium displayed its historical label, raw still link, missing playable video and missing original reference. This does not establish a new runtime/source revision or applicability receipt. + +Actual original-DxWnd, native Linux/Windows scenario recordings, codec variation and audible judgment remain for the one final combined session. Acceptance stays OPEN at 0/120 real obligations. Shared EVID IDs are not marked complete. No gameplay/runtime/package code, originals or shared receipt/scenario implementation changed; no game, DxWnd, Wine, GPU, managed build or Windows execution was performed here. + +## TDD Gate Compliance + +- Task 1: `artifacts/fidelity/tdd/01-02-01-red.json` retains the complete actual unittest report. The named CLI round-trip target failed its intended CLI-presence assertion before implementation. The classifier returned `RED_EVIDENCE_OK`; semantic inspection confirmed a behavior assertion rather than import/setup failure. The tracer's exact 15-Python/6-Node checks passed again before task 2. +- Task 2: `artifacts/fidelity/tdd/01-02-02-red.json` retains complete TAP. The named buffering test failed because replay incorrectly returned true while readyState was 2. The classifier returned `RED_EVIDENCE_OK`; other absent-API failures were retained rather than used as target evidence. Final suites pass 21 Python and 27 Node tests, with a dynamic minimum registered-count assertion. +- Each RED commit precedes its GREEN in ancestry. No separate refactor was needed. No skipped/todo tests or unrun planned automated checks remain. + +## Deviations from Plan + +No scope or architecture changes. The initial stylesheet was included with the tracer so its exported review tree was self-contained. The primary confirmed the exact tracked source-link normalization for plan 01-03 during implementation; this fulfills the planned capability navigation boundary without shared schema edits. + +## Threat/Test Coverage + +| Threat | Controls and evidence | +|---|---| +| T-01-04 | Generated-root manifest allowlist, actual hashes, loopback-only bind, resolved containment, symlink rejection, no listings, GET/HEAD-only reads, bounded single ranges; real HTTP negative/range tests | +| T-01-05 | Text rendering, relative URL allowlist, no imported HTML/argv execution, CSP/nosniff, imported active documents downloaded inertly, validated copied text sources; hostile-label/path/document tests | +| T-01-06 | Explicit category/history/missing labels, independent clocks, rate 1, separate drift/uncertainty, no auto-acceptance; controller/browser/classification tests | +| T-01-SC | Browser/Node/Python built-ins only; no npm/pip installation. Existing ffmpeg produced ignored synthetic smoke media. | + +## Threat Flags + +| Flag | File | Description | +|---|---|---| +| threat_flag: file-access | tools/recon/fidelity_review.py | Ledger source references cross the repository-text→generated-review boundary. Contained tracked bounded UTF-8-only copies, excluded roots, optional hash checks, inert text MIME and the generated manifest mitigate this planned navigation surface. | + +The cooperative offline filesystem boundary matches the shared receipt module; hostile concurrent filesystem replacement is outside that model. Re-export/revalidate after evidence changes. Native media/browser codec support remains a runtime review condition. + +## Issues Encountered + +The sandbox blocks loopback sockets and causes Node's child test runner to report one file-only result. Authorized local-test escalation produced the real named counts and HTTP results; the file-only result was not counted as validation. A browser-cancelled read exposed a broken-pipe retry; the handler now ends disconnected responses cleanly. Newer seek actions supersede stale metadata waits without cancelling the current action. These fixes remain within planned failure handling. + +No implementation stubs remain. Deliberately absent media/ledger states are implemented outcomes, not mock gameplay data. `tools.yaml`, the transient milestone lock and other owners' files were preserved. + +## User Setup Required + +None for the local tool checks. The planned combined hands-on original/native/audio session remains open; no earlier user execution request was created. + +## Next Phase Readiness + +Plan 01-03 can emit the coordinated capability/source-link contract; later checkpoint/capture/import plans can supply real receipts. The primary owns root continuity documents, integrated runtime regression gates and push. The existing gameplay and platform evidence limits remain binding. + +## Self-Check: PASSED + +All six created files exist. All four task commits are ancestors of HEAD and evaluation-scope resolves them on this branch. Exact counted plan checks, all 72 fidelity tests, whitespace checks and the 539-file preservation command pass. No tracked deletions, skipped tests or unexplained new untracked outputs were introduced; generated media/receipts stay ignored.