Compare commits

..
6 Commits
9 changed files with 1535 additions and 10 deletions

No files matched your search

+3 -3
View File
@@ -39,12 +39,12 @@ Integer phases are planned work; decimal phases may be inserted for urgent recov
2. A tester can reproduce identified whole-original reference scenarios from an isolated generated installation and inspect corresponding input/events, images and audio where applicable; unavailable execution keeps this criterion open. 2. A tester can reproduce identified whole-original reference scenarios from an isolated generated installation and inspect corresponding input/events, images and audio where applicable; unavailable execution keeps this criterion open.
3. A reviewer can trace every full-game capability from original evidence through current implementation, platform receipts, discrepancies and its remaining acceptance condition. 3. A reviewer can trace every full-game capability from original evidence through current implementation, platform receipts, discrepancies and its remaining acceptance condition.
4. Testers can repeat the same baseline movement/route scenarios on native Linux and native Windows with exact revision identities; Wine/cross-publish receipts remain separately labeled and cannot close missing native execution. 4. Testers can repeat the same baseline movement/route scenarios on native Linux and native Windows with exact revision identities; Wine/cross-publish receipts remain separately labeled and cannot close missing native execution.
**Plans:** 1/7 plans executed **Plans:** 2/7 plans executed
**Wave 1** **Wave 1**
- [x] 01-01-PLAN.md - [x] 01-01-PLAN.md
**Wave 2** *(blocked on Wave 1 completion)* **Wave 2** *(blocked on Wave 1 completion)*
- [ ] 01-02-PLAN.md - [x] 01-02-PLAN.md
- [ ] 01-03-PLAN.md - [ ] 01-03-PLAN.md
- [ ] 01-04-PLAN.md - [ ] 01-04-PLAN.md
@@ -151,7 +151,7 @@ Execution follows 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8, subject to the ex
| Phase | Plans Complete | Status | Completed | | Phase | Plans Complete | Status | Completed |
|-------|----------------|--------|-----------| |-------|----------------|--------|-----------|
| 1. Reproducible Fidelity Baseline | 1/7 | In Progress | - | | 1. Reproducible Fidelity Baseline | 2/7 | In Progress | - |
| 2. Faithful Movement and Scene Handoffs | 0/TBD | Not started | - | | 2. Faithful Movement and Scene Handoffs | 0/TBD | Not started | - |
| 3. Original Actors, Hazards and Combat | 0/TBD | Not started | - | | 3. Original Actors, Hazards and Combat | 0/TBD | Not started | - |
| 4. Complete Gadget and Vehicle Use | 0/TBD | Not started | - | | 4. Complete Gadget and Vehicle Use | 0/TBD | Not started | - |
+10 -7
View File
@@ -3,16 +3,16 @@ gsd_state_version: "1.0"
current_phase: 01 current_phase: 01
current_phase_name: Reproducible Fidelity Baseline current_phase_name: Reproducible Fidelity Baseline
status: executing status: executing
stopped_at: Completed 01-01-PLAN.md stopped_at: Completed 01-02-PLAN.md
last_updated: "2026-11-13T00:13:22.917Z" last_updated: "2026-11-13T00:48:47.486Z"
last_activity: 2026-11-12 last_activity: 2026-11-12
last_activity_desc: Phase 01 execution started last_activity_desc: Phase 01 execution started
state_head: ac958e1962f381804f6a5ad6bf9ea2559a652fff state_head: a789bfa942693507c3e8d487710f3b5dcbc7e270
progress: progress:
total_phases: 8 total_phases: 8
completed_phases: 0 completed_phases: 0
total_plans: 7 total_plans: 7
completed_plans: 1 completed_plans: 2
percent: 0 percent: 0
--- ---
@@ -28,7 +28,7 @@ See: .planning/PROJECT.md (updated 2026-11-12)
## Current Position ## Current Position
Phase: 01 (Reproducible Fidelity Baseline) — EXECUTING Phase: 01 (Reproducible Fidelity Baseline) — EXECUTING
Plan: 2 of 7 Plan: 3 of 7
Status: Ready to execute Status: Ready to execute
Last activity: 2026-11-12 — Phase 01 execution started Last activity: 2026-11-12 — Phase 01 execution started
@@ -50,6 +50,7 @@ Recent trend: No execution plans completed in this roadmap. Existing project wor
| Plan | Duration | Tasks | Files | | Plan | Duration | Tasks | Files |
|------|----------|-------|-------| |------|----------|-------|-------|
| Phase 01 P01 | 16 min | 2 tasks | 5 files | | Phase 01 P01 | 16 min | 2 tasks | 5 files |
| Phase 01 P02 | 16 min | 2 tasks | 6 files |
## Accumulated Context ## Accumulated Context
@@ -63,6 +64,8 @@ Recent trend: No execution plans completed in this roadmap. Existing project wor
- [Phase 01]: Version 1 typed hashed receipts keep category, history and actual bytes separate from acceptance; structural readiness never substitutes for native/reference execution. - [Phase 01]: Version 1 typed hashed receipts keep category, history and actual bytes separate from acceptance; structural readiness never substitutes for native/reference execution.
- [Phase 01]: All eight lifetime/dialogue/input cells require continuous plus four focused obligations on three original/native sides, totaling 120 independently audited obligations. - [Phase 01]: All eight lifetime/dialogue/input cells require continuous plus four focused obligations on three original/native sides, totaling 120 independently audited obligations.
- [Phase 01]: Retained observations require one session, observed prerequisite departure/return and hashed copy state; each fresh run uses an independent launch/session identity. - [Phase 01]: Retained observations require one session, observed prerequisite departure/return and hashed copy state; each fresh run uses an independent launch/session identity.
- [Phase 01]: Paired review preserves actual speed, separate raw clocks, explicit event and playback drift, exclusive audio and complete recording tails; export never promotes runtime acceptance.
- [Phase 01]: Capability source links are normalized to contained tracked bounded UTF-8 text copies and activated only through exporter-validated local hrefs.
### Pending Todos ### Pending Todos
@@ -89,6 +92,6 @@ No original-required category deferred outside full reconstruction. Later phases
## Session Continuity ## Session Continuity
Last session: 2026-11-13T00:13:05.517Z Last session: 2026-11-13T00:48:47.461Z
Stopped at: Completed 01-01-PLAN.md Stopped at: Completed 01-02-PLAN.md
Resume file: None Resume file: None
@@ -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.
+272
View File
@@ -0,0 +1,272 @@
import nodeTest from 'node:test';
import assert from 'node:assert/strict';
import {existsSync} from 'node:fs';
let declared = 0;
function test(name, action) { declared++; return nodeTest(name, action); }
const modulePath = new URL('../tools/recon/fidelity_viewer/viewer.mjs', import.meta.url);
const api = existsSync(modulePath) ? await import(modulePath) : {};
class Media extends EventTarget {
currentTime = 0; duration = 20; playbackRate = 1; muted = false; volume = 1;
readyState = 4; paused = true; ended = false; seeking = false; error = null;
failPlay = false;
pause() { this.paused = true; }
async play() { if (this.failPlay) throw Error('blocked'); this.paused = false; }
emit(name) { this.dispatchEvent(new Event(name)); }
}
function pair() {
assert.equal(typeof api.createPairController, 'function', 'paired media controller must exist');
const original = new Media(), port = new Media();
const controller = api.createPairController({original, port});
return {original, port, controller};
}
const marker = {name: 'landing', original: {media_seconds: 2, elapsed_seconds: 2, uncertainty_seconds: .02},
port: {media_seconds: 3, elapsed_seconds: 3.2, uncertainty_seconds: .03}};
test('event selection seeks independent observed times and waits for explicit play', async () => {
const {controller, original, port} = pair();
await controller.selectEvent(marker);
assert.equal(original.currentTime, 2); assert.equal(port.currentTime, 3);
assert.ok(original.paused && port.paused);
await controller.play();
assert.equal(original.playbackRate, 1); assert.equal(port.playbackRate, 1);
assert.ok(!original.paused && !port.paused);
});
test('invalid or unmatched event cannot seek either recording', async () => {
const {controller, original} = pair();
for (const invalid of [{...marker, port: null}, {...marker, original: {...marker.original, media_seconds: Infinity}},
{...marker, port: {...marker.port, media_seconds: 99}}]) {
await assert.rejects(controller.selectEvent(invalid));
assert.equal(original.currentTime, 0);
}
});
test('play rejection pauses both and names the cause', async () => {
const {controller, original, port} = pair(); port.failPlay = true;
assert.equal(await controller.play(), false);
assert.ok(original.paused && port.paused);
assert.match(controller.snapshot().problem, /play.*blocked/i);
});
test('relative artifact links reject remote and active URL schemes', () => {
assert.equal(typeof api.safeLocalURL, 'function');
assert.equal(api.safeLocalURL('sides/port/trace.json'), 'sides/port/trace.json');
for (const value of ['https://host/x', 'javascript:alert(1)', '//host/x', '../x', '/etc/passwd', '%2e%2e/x'])
assert.throws(() => api.safeLocalURL(value));
});
test('capability navigation is supplied through a renderer', () => {
assert.equal(typeof api.renderCapabilities, 'function');
});
test('raw elapsed, event drift and playback drift are distinct', async () => {
const {controller, original, port} = pair();
await controller.selectEvent(marker);
original.currentTime = 5; port.currentTime = 6.25;
const s = controller.snapshot();
assert.equal(s.sides.original.recording_seconds, 5);
assert.equal(s.sides.port.recording_seconds, 6.25);
assert.equal(s.sides.original.aligned_elapsed, 3);
assert.equal(s.sides.port.aligned_elapsed, 3.25);
assert.ok(Math.abs(s.eventDrift.seconds - 1.2) < 1e-9);
assert.equal(s.eventDrift.uncertainty_seconds, .05);
assert.equal(s.playbackDrift, .25);
});
test('no selected event means no invented drift', () => {
const {controller} = pair();
assert.equal(controller.snapshot().eventDrift, null);
assert.equal(controller.snapshot().playbackDrift, null);
});
test('exclusive soundtrack switch mutes both before selecting one', () => {
const {controller, original, port} = pair();
assert.ok(original.muted && port.muted);
controller.setAudio('original');
assert.ok(!original.muted && port.muted);
controller.setAudio('port');
assert.ok(original.muted && !port.muted);
controller.setAudio('none');
assert.ok(original.muted && port.muted);
assert.throws(() => controller.setAudio('external'));
});
test('gain is unadjusted by default and visibly review-only when changed', () => {
const {controller, original, port} = pair();
assert.equal(controller.snapshot().gain, 1);
assert.equal(controller.snapshot().gainAdjusted, false);
controller.setGain(.4);
assert.equal(original.volume, .4); assert.equal(port.volume, .4);
assert.equal(controller.snapshot().gainAdjusted, true);
assert.match(controller.snapshot().gainLabel, /review-only/i);
for (const value of [-1, 2, NaN]) assert.throws(() => controller.setGain(value));
});
test('buffering pauses both; explicit recovered play stays at rate one', async () => {
const {controller, original, port} = pair();
await controller.play(); port.readyState = 2; port.emit('waiting');
assert.ok(original.paused && port.paused);
assert.match(controller.snapshot().problem, /port.*buffer/i);
assert.equal(await controller.play(), false);
port.readyState = 4; port.emit('canplay');
assert.ok(original.paused && port.paused, 'readiness must not auto-resume');
assert.equal(await controller.play(), true);
assert.equal(port.playbackRate, 1);
});
test('decode failure is visible and blocks play', async () => {
const {controller, original, port} = pair();
port.error = {code: 3}; port.emit('error');
assert.ok(original.paused && port.paused);
assert.match(controller.snapshot().problem, /port.*decod/i);
assert.equal(await controller.play(), false);
});
test('missing media blocks pair but preserves manual available-side playback', async () => {
const port = new Media();
const controller = api.createPairController({original: null, port});
assert.equal(await controller.play(), false);
assert.match(controller.snapshot().problem, /missing/i);
assert.equal(await controller.playSide('port'), true);
assert.equal(controller.snapshot().sides.original.state, 'missing');
});
test('asymmetric end pauses pair and allows the complete longer tail', async () => {
const {controller, original, port} = pair();
await controller.play(); original.currentTime = original.duration; original.ended = true;
original.emit('ended');
assert.ok(port.paused);
assert.match(controller.snapshot().problem, /tail/i);
assert.equal(await controller.play(), true);
assert.equal(original.currentTime, 20); assert.ok(!port.paused);
port.currentTime = port.duration; port.ended = true; port.emit('ended');
assert.equal(await controller.play(), false);
});
test('manual play and seek never force the other recording to follow', async () => {
const {controller, original, port} = pair();
await controller.selectEvent(marker);
assert.equal(await controller.playSide('port'), true);
assert.ok(original.paused && !port.paused);
await controller.seekSide('port', 8);
assert.equal(original.currentTime, 2); assert.equal(port.currentTime, 8);
assert.ok(original.paused && port.paused);
});
test('external rate changes are corrected to actual speed without seeking', () => {
const {controller, original, port} = pair();
original.currentTime = 7; port.currentTime = 9;
port.playbackRate = 1.5; port.emit('ratechange');
assert.equal(port.playbackRate, 1);
assert.equal(port.currentTime, 9); assert.equal(original.currentTime, 7);
controller.pause();
});
test('event selection waits for asynchronous metadata and seek readiness', async () => {
const original = new Media(), port = new Media(); original.readyState = port.readyState = 0;
let t = 0;
Object.defineProperty(port, 'currentTime', {get: () => t, set: value => {
t = value; port.seeking = true;
setTimeout(() => {port.seeking = false; port.emit('seeked');}, 5);
}});
const controller = api.createPairController({original, port, timeoutMs: 100});
let finished = false;
const seek = controller.selectEvent(marker).then(() => {finished = true;});
await new Promise(resolve => setTimeout(resolve, 2));
assert.equal(finished, false); assert.equal(t, 0);
original.readyState = port.readyState = 4; original.emit('loadedmetadata'); port.emit('loadedmetadata');
await seek;
assert.equal(finished, true); assert.equal(port.currentTime, 3);
assert.ok(original.paused && port.paused);
});
test('seek timeout reports the cause and leaves pair paused', async () => {
const original = new Media(), port = new Media(); port.readyState = 0;
const controller = api.createPairController({original, port, timeoutMs: 10});
await assert.rejects(controller.selectEvent(marker), /readiness|metadata|timed out/i);
assert.match(controller.snapshot().problem, /readiness|metadata|timed out/i);
assert.ok(original.paused && port.paused);
});
test('buffering during a pending play cannot be erased by promise completion', async () => {
const {controller, original, port} = pair();
let release;
port.play = () => new Promise(resolve => { release = () => {port.paused = false; resolve();}; });
const playing = controller.play();
port.readyState = 2; port.emit('waiting'); release();
assert.equal(await playing, false);
assert.ok(original.paused && port.paused);
assert.match(controller.snapshot().problem, /buffer/i);
});
test('overlays start off and unsupported differences explain their gate', () => {
const {controller} = pair();
assert.deepEqual(controller.snapshot().overlays, {annotations: false, difference: false});
controller.setOverlay('annotations', true);
assert.equal(controller.snapshot().overlays.annotations, true);
assert.throws(() => controller.setOverlay('difference', true), /lossless|frame/i);
assert.equal(controller.snapshot().overlays.difference, false);
});
const frame = (sha = 'a'.repeat(64)) => ({url: 'sides/original/still.png', sha256: sha, size: 100,
frame: {lossless: true, event: 'landing', media_sha256: 'b'.repeat(64), media_seconds: 2,
viewport: [640, 480], crop: [0, 0, 640, 480], width: 640, height: 480}});
test('lossless differences need matched frame event viewport aspect and crop', () => {
assert.equal(typeof api.differenceEligibility, 'function');
const a = frame(), b = frame('c'.repeat(64));
assert.equal(api.differenceEligibility(a, b).eligible, true);
for (const patch of [{viewport: [800, 600]}, {crop: [1, 0, 639, 480]},
{event: 'jump'}, {lossless: false}, {media_sha256: null}]) {
const result = api.differenceEligibility(a, {...b, frame: {...b.frame, ...patch}});
assert.equal(result.eligible, false);
assert.ok(result.reason.length);
}
});
test('nonfinite elapsed or uncertainty is rejected before seeking', async () => {
const {controller, original} = pair();
for (const patch of [{elapsed_seconds: NaN}, {uncertainty_seconds: -1}])
await assert.rejects(controller.selectEvent({...marker, original: {...marker.original, ...patch}}));
assert.equal(original.currentTime, 0);
});
class Node {
children = []; textContent = '';
constructor(tag, ownerDocument) { this.tag = tag; this.ownerDocument = ownerDocument; }
append(...items) { this.children.push(...items); }
replaceChildren(...items) { this.children = items; }
get text() { return this.textContent + this.children.map(c => c.text).join(' '); }
}
test('capability renderer preserves facts, impact order, history and inert hostile text', () => {
const doc = {createElement: tag => new Node(tag, doc)};
const container = new Node('section', doc);
api.renderCapabilities(container, {capabilities: [{id: 'move', group: 'movement',
summary: '<script>malicious()</script>', requirement_ids: ['MOVE-01'],
verified_scope: 'bounded fixture', differences: ['unverified'], acceptance: {state: 'open'},
source_links: ['javascript:bad()'], scenario_ids: ['case-a'], current: ['native receipt'],
history: [{superseded: true, revision: 'old'}],
discrepancies: [{id: 'b', impact: 'subtle'}, {id: 'a', impact: 'blocking'}]}]});
assert.match(container.text, /<script>malicious\(\)<\/script>/);
assert.match(container.text, /MOVE-01/); assert.match(container.text, /superseded/);
assert.ok(container.text.indexOf('blocking') < container.text.indexOf('subtle'));
assert.ok(container.children.some(c => c.children?.some(n => n.tag === 'details')));
assert.equal(container.children.some(c => c.tag === 'script'), false);
});
test('empty capability export has an explicit open state', () => {
const doc = {createElement: tag => new Node(tag, doc)};
const container = new Node('section', doc);
api.renderCapabilities(container, {capabilities: []});
assert.match(container.text, /No capability ledger supplied.*open/);
});
test('percent-encoded local filenames remain inert and usable', () => {
assert.equal(api.safeLocalURL('sides/port/frame%20one%23.png'), 'sides/port/frame%20one%23.png');
assert.throws(() => api.safeLocalURL('sides/port/frame.png?redirect=http://host'));
});
test('difference frame must match its own observed source event and timestamp', () => {
const a = frame(), b = frame('c'.repeat(64));
const side = artifact => ({media: {path: 'video.webm', sha256: 'b'.repeat(64), duration_seconds: 10},
artifacts: [artifact], events: [{name: 'landing', artifact: 'video.webm', media_seconds: 2}]});
const model = {sides: {original: side(a), port: side(b)}};
assert.equal(api.framePair(model).port, b);
model.sides.port.events[0].media_seconds = 3;
assert.equal(api.framePair(model).port, undefined);
model.sides.port.events[0].media_seconds = 2;
model.sides.port.media.sha256 = 'd'.repeat(64);
assert.equal(api.framePair(model).port, undefined);
});
test('a newer event seek supersedes pending metadata without cancelling the newer action', async () => {
const original = new Media(), port = new Media(); original.readyState = port.readyState = 0;
const controller = api.createPairController({original, port, timeoutMs: 100});
const old = controller.selectEvent(marker).catch(error => error);
const next = {...marker, name: 'idle', original: {...marker.original, media_seconds: 4}, port: {...marker.port, media_seconds: 5}};
const recent = controller.selectEvent(next);
original.readyState = port.readyState = 4; original.emit('loadedmetadata'); port.emit('loadedmetadata');
assert.match((await old).message, /cancelled/);
await recent;
assert.equal(original.currentTime, 4); assert.equal(port.currentTime, 5);
assert.equal(controller.snapshot().selected.name, 'idle');
assert.equal(controller.snapshot().selecting, false);
assert.equal(await controller.play(), true);
});
test('suite executes at least sixteen registered behavior tests', () => {
assert.ok(declared >= 16, 'runner must register at least sixteen tests');
});
+290
View File
@@ -0,0 +1,290 @@
"""Synthetic media tests prove local review plumbing, never game acceptance."""
import copy
import importlib
import json
from pathlib import Path
import subprocess
import sys
import tempfile
import threading
import unittest
import urllib.error
import urllib.request
import wave
ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT / 'tools/recon'))
import fidelity_receipts as receipts
try:
review = importlib.import_module('fidelity_review')
except ModuleNotFoundError:
review = None
def fixture(base, side):
bundle = base / side
bundle.mkdir()
for name in ('video.wav', 'audio.wav'):
with wave.open(str(bundle / name), 'wb') as stream:
stream.setparams((1, 2, 8000, 0, 'NONE', 'uncompressed'))
stream.writeframes(b'\0\0' * 16000)
(bundle / 'trace.json').write_text('{"fixture": true}')
items = [dict(receipts.identify_file(bundle / name), path=name, role=role,
synthetic=True, **({'duration_seconds': 2} if role != 'input_events' else {}))
for name, role in [('video.wav', 'video'), ('audio.wav', 'audio'),
('trace.json', 'input_events')]]
value = dict(schema_version=1, receipt_id='test-' + side, session_id='test-session',
case_id='test-only', evidence_kind='synthetic', status='captured',
scope='tooling-test', historical=False, identity={},
platform={'os': 'test', 'execution': 'synthetic'},
invocation={'argv': ['fixture'], 'cwd': '.'},
clocks={'wall_start': '2026-01-01T00:00:00Z',
'wall_end': '2026-01-01T00:00:02Z',
'monotonic_start': 0, 'monotonic_end': 2},
artifacts=items, derivatives=[],
events=[dict(name='landing', artifact='video.wav', media_seconds=0.5,
elapsed_seconds=0.5, method='procedural', uncertainty_seconds=0.02)],
limitations=['Synthetic silent audio fixture; no original execution'],
missing_evidence=[], acceptance={'state': 'open', 'remaining': ['Real capture required']})
path = bundle / 'receipt.json'
path.write_text(json.dumps(value))
imported = receipts.import_receipt(path, bundle, base / 'test-imports')
return Path(imported['path']), value
class FidelityReview(unittest.TestCase):
def setUp(self):
self.temp = tempfile.TemporaryDirectory(prefix='fidelity-review-test-')
self.addCleanup(self.temp.cleanup)
self.base = Path(self.temp.name)
self.original, self.value = fixture(self.base, 'original')
self.port, _ = fixture(self.base, 'port')
self.output = self.base / 'test-review'
def api(self):
self.assertIsNotNone(review, 'contained review export/server must exist')
return review
def export(self, **kwargs):
return self.api().export_review(kwargs.pop('original', self.original),
kwargs.pop('port', self.port), self.output, **kwargs)
def server(self):
server = self.api().make_server(self.output, port=0)
thread = threading.Thread(target=server.serve_forever, daemon=True)
thread.start()
self.addCleanup(server.server_close)
self.addCleanup(thread.join, 2)
self.addCleanup(server.shutdown)
return 'http://127.0.0.1:' + str(server.server_port)
def request(self, url, method='GET', headers=None):
request = urllib.request.Request(url, method=method, headers=headers or {})
try:
return urllib.request.urlopen(request, timeout=3)
except urllib.error.HTTPError as error:
return error
def test_cli_import_export_http_round_trip(self):
cli = ROOT / 'tools/recon/fidelity_review.py'
self.assertTrue(cli.is_file(), 'review CLI must export an imported pair')
result = subprocess.run([sys.executable, str(cli), 'export', '--original', str(self.original),
'--port', str(self.port), '--output', str(self.output)],
capture_output=True, text=True, timeout=15)
self.assertEqual(result.returncode, 0, result.stderr)
url = self.server()
with self.request(url + '/review.json') as response:
model = json.load(response)
self.assertEqual(model['acceptance']['state'], 'open')
self.assertEqual(model['events'][0]['name'], 'landing')
for side in ('original', 'port'):
self.assertEqual(model['sides'][side]['evidence_kind'], 'synthetic')
with self.request(url + '/' + model['sides'][side]['media']['url']) as response:
self.assertTrue(response.read().startswith(b'RIFF'))
def test_export_keeps_raw_derivatives_and_links(self):
data = self.export()
for side in data['sides'].values():
self.assertEqual({x['role'] for x in side['artifacts']}, {'video', 'audio', 'input_events'})
self.assertTrue((self.output / side['receipt_url']).is_file())
self.assertEqual(side['derivatives'], [])
def test_missing_original_explicit(self):
data = self.export(original=None)
self.assertIn('Missing original', data['sides']['original']['missing'])
self.assertIsNone(data['sides']['original']['media'])
def test_empty_review_is_explicit(self):
data = self.export(original=None, port=None)
self.assertEqual(data['events'], [])
self.assertEqual(data['acceptance']['state'], 'open')
def test_tampered_artifact_rejected(self):
(self.port.parent / 'video.wav').write_bytes(b'changed')
with self.assertRaises(ValueError): self.export()
self.assertFalse(self.output.exists())
def test_tampered_receipt_sidecar_rejected(self):
self.port.write_text('{}')
with self.assertRaises(ValueError): self.export()
def test_traversal_absolute_remote_and_symlink_references_rejected(self):
(self.original.parent / 'receipt.sha256').unlink()
for path in ('../secret', '/secret', 'C:/secret', 'https://host/a', 'a\\b'):
value = copy.deepcopy(self.value)
value['artifacts'][0]['path'] = path
raw = self.original.parent / 'raw.json'
raw.write_text(json.dumps(value))
with self.assertRaisesRegex(ValueError, 'reference|Reference'):
self.api().export_review(raw, None, self.output)
(self.original.parent / 'video.wav').unlink()
(self.original.parent / 'video.wav').symlink_to(self.port.parent / 'video.wav')
with self.assertRaises(ValueError): self.export()
def test_labels_are_json_text_never_interpolated_html(self):
value = copy.deepcopy(self.value)
hostile = '</script><img src=x onerror=alert(1)>'
value['limitations'].append(hostile)
raw = self.original.parent / 'raw.json'
raw.write_text(json.dumps(value))
# A new collector bundle has no import sidecar; do not reuse another
# receipt's immutable metadata identity for this changed observation.
(self.original.parent / 'receipt.sha256').unlink()
data = self.api().export_review(raw, None, self.output)
self.assertIn(hostile, data['sides']['original']['limitations'])
self.assertNotIn(hostile, (self.output / 'index.html').read_text())
self.assertNotIn('innerHTML', (self.output / 'viewer.mjs').read_text())
def test_event_out_of_range_rejected(self):
(self.original.parent / 'receipt.sha256').unlink()
value = copy.deepcopy(self.value)
value['events'][0]['media_seconds'] = 3
raw = self.original.parent / 'raw.json'
raw.write_text(json.dumps(value))
with self.assertRaisesRegex(ValueError, 'exceeds'):
self.api().export_review(raw, None, self.output)
def test_duplicate_event_is_ambiguous_not_silently_selected(self):
(self.original.parent / 'receipt.sha256').unlink()
value = copy.deepcopy(self.value)
value['events'].append(copy.deepcopy(value['events'][0]))
raw = self.original.parent / 'raw.json'
raw.write_text(json.dumps(value))
with self.assertRaisesRegex(ValueError, 'Ambiguous'):
self.api().export_review(raw, None, self.output)
def test_cross_case_pair_rejected(self):
(self.original.parent / 'receipt.sha256').unlink()
value = copy.deepcopy(self.value)
value['case_id'] = 'other-case'
raw = self.original.parent / 'raw.json'
raw.write_text(json.dumps(value))
with self.assertRaisesRegex(ValueError, 'same case'):
self.api().export_review(raw, self.port, self.output)
def test_lossless_stills_and_derivative_ancestry_remain_linked(self):
(self.original.parent / 'receipt.sha256').unlink()
value = copy.deepcopy(self.value)
# A byte-identified derivative record tests ancestry retention only;
# browser/PNG validation is separately required before image differences.
(self.original.parent / 'still.png').write_bytes(b'test-only not a PNG')
value['artifacts'].append(dict(receipts.identify_file(self.original.parent / 'still.png'),
path='still.png', role='lossless_still', synthetic=True))
value['derivatives'].append({'path': 'still.png', 'source': 'video.wav',
'tool': 'synthetic fixture', 'argv': ['inert']})
raw = self.original.parent / 'raw.json'
raw.write_text(json.dumps(value))
data = self.api().export_review(raw, None, self.output)
self.assertEqual(data['sides']['original']['derivatives'], value['derivatives'])
self.assertTrue((self.output / 'sides/original/still.png').is_file())
def test_imported_active_document_served_as_attachment(self):
(self.original.parent / 'receipt.sha256').unlink()
value = copy.deepcopy(self.value)
artifact = self.original.parent / 'untrusted.html'
artifact.write_text('<script>alert(1)</script>')
value['artifacts'].append(dict(receipts.identify_file(artifact), path='untrusted.html', role='note'))
raw = self.original.parent / 'raw.json'
raw.write_text(json.dumps(value))
self.api().export_review(raw, None, self.output)
with self.request(self.server() + '/sides/original/untrusted.html') as response:
self.assertEqual(response.headers['Content-Type'], 'application/octet-stream')
self.assertEqual(response.headers['Content-Disposition'], 'attachment')
def test_existing_or_overlapping_output_rejected(self):
with self.assertRaises(ValueError): self.api().export_review(self.original, self.port, self.original.parent)
self.export()
with self.assertRaises(ValueError): self.export()
def test_head_and_ranges_seek_actual_bytes(self):
data = self.export()
url = self.server() + '/' + data['sides']['port']['media']['url']
for range_value, expected in [('bytes=0-3', b'RIFF'), ('bytes=-4', b'\0' * 4),
('bytes=4-', (self.port.parent / 'video.wav').read_bytes()[4:])]:
with self.request(url, headers={'Range': range_value}) as response:
self.assertEqual(response.status, 206)
self.assertEqual(response.read(), expected)
self.assertIn('Content-Range', response.headers)
with self.request(url, 'HEAD', {'Range': 'bytes=0-3'}) as response:
self.assertEqual(response.status, 206)
self.assertEqual(response.headers['Content-Length'], '4')
self.assertEqual(response.read(), b'')
def test_bad_ranges_return_416(self):
self.export()
url = self.server() + '/index.html'
for value in ('bytes=9-2', 'bytes=999999-', 'bytes=0-1,4-5', 'bytes=-0', 'nonsense'):
with self.request(url, headers={'Range': value}) as response:
self.assertEqual(response.status, 416)
def test_server_rejects_escape_symlink_and_directory(self):
self.export()
(self.output / 'escape').symlink_to(self.port.parent / 'video.wav')
url = self.server()
for path in ('/%2e%2e/tools.yaml', '/escape', '/sides/', '/%2fetc/passwd'):
with self.request(url + path) as response:
self.assertIn(response.status, (400, 403, 404))
def test_write_methods_forbidden(self):
self.export()
url = self.server()
for method in ('POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'):
with self.request(url + '/review.json', method) as response:
self.assertEqual(response.status, 405)
def test_only_generated_root_loopback_and_security_headers(self):
with self.assertRaises(ValueError): self.api().make_server(ROOT, port=0)
self.export()
with self.assertRaises(ValueError): self.api().make_server(self.output, port=0, host='0.0.0.0')
with self.request(self.server() + '/') as response:
self.assertEqual(response.status, 200)
self.assertEqual(response.headers['X-Content-Type-Options'], 'nosniff')
self.assertIn("default-src 'none'", response.headers['Content-Security-Policy'])
def test_ledger_sources_are_validated_copied_and_linked(self):
ledger = self.base / 'ledger.json'
ledger.write_text(json.dumps({'schema_version': 1, 'capabilities': [{'id': 'test', 'source_links':
[{'label': 'Progress', 'path': 'docs/progress.md'}, {'label': 'Missing', 'path': 'docs/absent-fixture.md'}]}]}))
data = self.export(ledger=ledger)
links = data['ledger']['capabilities'][0]['source_links']
self.assertTrue(links[0]['validated_local'])
self.assertEqual((self.output / links[0]['href']).read_bytes(), (ROOT / 'docs/progress.md').read_bytes())
self.assertIsNone(links[1]['href'])
self.assertIn('Missing', links[1]['missing'])
with self.request(self.server() + '/' + links[0]['href']) as response:
self.assertEqual(response.headers['Content-Type'], 'text/plain; charset=utf-8')
self.assertTrue(response.read())
def test_ledger_source_paths_and_mismatched_hashes_rejected(self):
ledger = self.base / 'ledger.json'
for path in ('../Original/game.exe', 'https://host/a', '.git/config', 'artifacts/test.log'):
ledger.write_text(json.dumps({'schema_version': 1, 'capabilities': [{'source_links': [{'label': 'bad', 'path': path}]}]}))
with self.assertRaises(ValueError): self.export(ledger=ledger)
ledger.write_text(json.dumps({'schema_version': 1, 'capabilities': [{'source_links':
[{'label': 'bad hash', 'path': 'docs/progress.md', 'sha256': '0' * 64}]}]}))
with self.assertRaisesRegex(ValueError, 'hash mismatch'): self.export(ledger=ledger)
if __name__ == '__main__':
unittest.main()
+328
View File
@@ -0,0 +1,328 @@
"""Export validated local receipts; serve only the generated, read-only tree.
CLI: export --original IMPORT/receipt.json --port IMPORT/receipt.json --output NEW
serve --root NEW [--port 8765]
Either side may be omitted. Exports are review aids, never acceptance receipts.
The cooperative offline filesystem boundary matches fidelity_receipts: revalidate
before review; hostile concurrent filesystem replacement is outside this model.
"""
import argparse
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
import json
import mimetypes
import os
from pathlib import Path
import re
import shutil
import subprocess
import tempfile
from urllib.parse import quote, unquote, urlsplit
from fidelity_receipts import (MAX_JSON_BYTES, canonical_bytes, contained_path,
identify_file, read_json, read_receipt, separated_roots,
validate_receipt)
VIEWER = Path(__file__).with_name('fidelity_viewer')
PROJECT = Path(__file__).resolve().parents[2]
STATIC = ('index.html', 'viewer.mjs', 'style.css')
MAX_RANGE = 16 * 1024 * 1024
def _side(path, side):
if path is None:
return {'missing': 'Missing ' + side + ' reference recording', 'media': None,
'artifacts': [], 'events': [], 'derivatives': []}, []
path = Path(path)
if path.is_symlink():
raise ValueError('Receipt must not be a symlink')
path = path.resolve(strict=True)
value = read_receipt(path)
validation = validate_receipt(value, path.parent)
prefix = 'sides/' + side + '/'
paths = {a['path'] for a in value['artifacts']}
paths.update(a['path'] for a in value['identity'].values() if isinstance(a, dict) and 'path' in a)
if any(name.casefold() in ('receipt.json', 'receipt.sha256') for name in paths):
raise ValueError('Artifact collides with exported receipt')
artifacts = [dict(a, url=quote(prefix + a['path'], safe='/')) for a in value['artifacts']]
videos = [a for a in artifacts if a['role'] in ('video', 'preview')]
# A preview is explicit derivative provenance; a raw recording remains linked.
media = next((a for a in videos if a['role'] == 'preview'), next(iter(videos), None))
events = [e for e in value['events'] if media and e['artifact'] == media['path']]
result = {key: value.get(key) for key in ('receipt_id', 'session_id', 'case_id', 'scope',
'evidence_kind', 'status', 'platform', 'historical', 'limitations', 'identity', 'clocks')}
result.update(artifacts=artifacts, media=media, events=events,
derivatives=value['derivatives'], receipt_url=prefix + 'receipt.json',
missing_evidence=validation['missing_evidence'],
missing='' if media else 'Missing ' + side + ' playable video/preview',
reference_warning=('No genuine original reference: this is ' + value['evidence_kind'] + ' evidence')
if side == 'original' and value['evidence_kind'] != 'original_dxwnd' else '',
acceptance={'state': 'open', 'remaining': ['Review export is not acceptance']})
copies = [(contained_path(path.parent, name), prefix + name) for name in sorted(paths)]
copies.append((path, prefix + 'receipt.json'))
return result, copies
def _events(sides):
indexed = {}
for side, record in sides.items():
seen = set()
for event in record['events']:
if event['name'] in seen:
raise ValueError('Ambiguous duplicate event on selected media: ' + event['name'])
seen.add(event['name'])
indexed.setdefault(event['name'], {'name': event['name'], 'original': None, 'port': None})[side] = event
return list(indexed.values())
def _ledger(path):
if path is None:
return {'schema_version': 1, 'capabilities': []}, []
data = read_json(path)
if data.get('schema_version') != 1 or not isinstance(data.get('capabilities'), list):
raise ValueError('Unsupported capability export')
result = subprocess.run(['git', '-C', str(PROJECT), 'ls-files', '-z'],
capture_output=True, check=True, timeout=20)
if len(result.stdout) > MAX_JSON_BYTES:
raise ValueError('Tracked source inventory exceeds bound')
tracked = set(result.stdout.decode('utf8').split('\0'))
copies = {}
for capability in data['capabilities']:
if not isinstance(capability, dict) or not isinstance(capability.get('source_links', []), list):
raise ValueError('Capability source_links must be an array')
links = []
for item in capability.get('source_links', []):
if not isinstance(item, dict) or not isinstance(item.get('label'), str):
raise ValueError('Source link requires label and repo-relative path')
source = contained_path(PROJECT, item.get('path'))
relative = source.relative_to(PROJECT).as_posix()
if relative.split('/')[0] in {'Original', 'original', 'artifacts', 'dist', '.git', '.tools', '.nuget'}:
raise ValueError('Source links cannot expose original/generated/private roots')
link = {'label': item['label'], 'path': relative, 'href': None,
'validated_local': False, 'missing': None}
if relative not in tracked or not source.is_file():
link['missing'] = 'Missing tracked source reference; acceptance remains open'
else:
actual = identify_file(source)
if actual['size'] > 1024 * 1024:
raise ValueError('Source text exceeds 1 MiB bound')
text = source.read_bytes()
text.decode('utf8')
if b'\0' in text:
raise ValueError('Source reference must be text, not an executable or package')
if item.get('sha256') and item['sha256'] != actual['sha256']:
raise ValueError('Source reference hash mismatch')
exported = 'sources/' + relative
copies[exported] = source
link.update(href=quote(exported, safe='/'), validated_local=True,
sha256=actual['sha256'], size=actual['size'])
links.append(link)
capability['source_links'] = links
return data, [(source, name) for name, source in sorted(copies.items())]
def export_review(original, port, output, ledger=None):
"""Return review model and atomically publish a NEW self-contained directory."""
output = Path(output)
if output.is_symlink() or output.exists():
raise ValueError('Review output must be a new directory')
output = output.resolve()
separated_roots(PROJECT.parent / 'Original', output)
sides, copies = {}, []
for side, path in [('original', original), ('port', port)]:
if path:
separated_roots(Path(path).resolve().parent, output)
sides[side], files = _side(path, side)
copies += files
present = [s for s in sides.values() if 'case_id' in s]
if len({(s['case_id'], s['scope']) for s in present}) > 1:
raise ValueError('Paired receipts must describe the same case and scope')
ledger_model, source_copies = _ledger(ledger)
copies += source_copies
model = {'schema_version': 1, 'case_id': present[0]['case_id'] if present else 'empty',
'sides': sides, 'events': _events(sides), 'ledger': ledger_model,
'acceptance': {'state': 'open', 'remaining': ['Actual identified runtime and audiovisual review required']}}
encoded = canonical_bytes(model)
if len(encoded) > MAX_JSON_BYTES:
raise ValueError('Review JSON exceeds bound')
output.parent.mkdir(parents=True, exist_ok=True)
temporary = Path(tempfile.mkdtemp(prefix='.' + output.name + '-incomplete-', dir=output.parent))
# Failure retains the temporary tree for diagnosis; never partially publish.
(temporary / 'incomplete.json').write_text('{"status":"incomplete"}\n')
for source, relative in copies:
target = temporary / relative
target.parent.mkdir(parents=True, exist_ok=True)
shutil.copyfile(source, target)
if identify_file(source) != identify_file(target):
raise ValueError('Artifact changed during review copy')
for name in STATIC:
shutil.copyfile(VIEWER / name, temporary / name)
(temporary / 'review.json').write_bytes(encoded)
files = list(STATIC) + ['review.json'] + [name for _, name in copies]
manifest = {'schema_version': 1, 'tool': 'fidelity_review', 'files':
[dict(path=name, **identify_file(temporary / name)) for name in files]}
(temporary / '.review-root.json').write_bytes(canonical_bytes(manifest))
(temporary / 'incomplete.json').unlink()
# Recheck the receipt/artifact copies with the shared validator at publication.
for side in ('original', 'port'):
receipt = temporary / 'sides' / side / 'receipt.json'
if receipt.exists():
validate_receipt(read_receipt(receipt), receipt.parent)
if output.exists():
raise ValueError('Review output allocated by another writer')
os.rename(temporary, output)
return model
class ReviewHandler(BaseHTTPRequestHandler):
"""No directory listing, upload, repository root, symlink or remote access."""
def log_message(self, *_args):
pass
def end_headers(self):
self.send_header('X-Content-Type-Options', 'nosniff')
self.send_header('Content-Security-Policy', "default-src 'none'; script-src 'self'; style-src 'self'; "
"media-src 'self'; img-src 'self'; connect-src 'self'; base-uri 'none'; "
"frame-ancestors 'none'; form-action 'none'; object-src 'none'")
self.send_header('Referrer-Policy', 'no-referrer')
self.send_header('Cache-Control', 'no-store')
super().end_headers()
def do_GET(self):
self._read(False)
def do_HEAD(self):
self._read(True)
def _reject(self):
self.send_response(405)
self.send_header('Allow', 'GET, HEAD')
self.send_header('Content-Length', '0')
self.end_headers()
do_POST = do_PUT = do_DELETE = do_PATCH = do_OPTIONS = do_TRACE = do_CONNECT = _reject
def _read(self, head):
try:
parsed = urlsplit(self.path)
if parsed.scheme or parsed.netloc or parsed.query or parsed.fragment:
raise ValueError('Only generated local paths are readable')
name = unquote(parsed.path, errors='strict')
name = 'index.html' if name == '/' else name.removeprefix('/')
path = contained_path(self.server.root, name)
if name not in self.server.allowed or not path.is_file():
self.send_error(404)
return
size = path.stat().st_size
start, end, status = 0, size - 1, 200
range_value = self.headers.get('Range')
if range_value:
match = re.fullmatch(r'bytes=([0-9]{0,20})-([0-9]{0,20})', range_value)
if not match or not any(match.groups()) or size == 0:
raise IndexError('Invalid range')
left, right = match.groups()
if left:
start = int(left)
end = min(int(right), size - 1) if right else size - 1
else:
suffix = int(right)
if suffix <= 0:
raise IndexError('Invalid suffix')
start = max(0, size - suffix)
if start >= size or start > end:
raise IndexError('Unsatisfiable range')
end = min(end, start + MAX_RANGE - 1)
status = 206
self.send_response(status)
mime = 'text/javascript' if name.endswith('.mjs') else mimetypes.guess_type(name)[0]
mime = mime or 'application/octet-stream'
if name.startswith('sources/'):
mime = 'text/plain; charset=utf-8'
# Imported HTML/SVG/scripts never become active same-origin content.
if name not in STATIC and not name.startswith('sources/') and not (mime.startswith(('video/', 'audio/')) or
mime in ('image/png', 'image/jpeg', 'image/webp', 'application/json')):
mime = 'application/octet-stream'
self.send_header('Content-Disposition', 'attachment')
self.send_header('Content-Type', mime)
self.send_header('Accept-Ranges', 'bytes')
self.send_header('Content-Length', str(max(0, end - start + 1)))
if status == 206:
self.send_header('Content-Range', f'bytes {start}-{end}/{size}')
self.end_headers()
if not head:
with path.open('rb') as stream:
stream.seek(start)
remaining = end - start + 1
while remaining > 0:
block = stream.read(min(65536, remaining))
if not block:
break
self.wfile.write(block)
remaining -= len(block)
except IndexError:
self.send_response(416)
self.send_header('Content-Range', f'bytes */{size}')
self.send_header('Content-Length', '0')
self.end_headers()
except (BrokenPipeError, ConnectionResetError):
# Browsers cancel range reads while seeking; the response has already
# started. A second error response would itself write to a dead peer.
return
except (ValueError, UnicodeError, OSError):
self.send_error(403)
def make_server(root, port=8765, host='127.0.0.1'):
if host != '127.0.0.1':
raise ValueError('Viewer binds literal IPv4 loopback only')
root = Path(root)
if root.is_symlink():
raise ValueError('Review root must not be a symlink')
root = root.resolve(strict=True)
separated_roots(PROJECT.parent / 'Original', root)
manifest = read_json(contained_path(root, '.review-root.json'))
if manifest.get('tool') != 'fidelity_review' or manifest.get('schema_version') != 1:
raise ValueError('Only generated review trees can be served')
allowed = set()
for item in manifest.get('files', []):
path = contained_path(root, item['path'])
actual = identify_file(path)
if item['sha256'] != actual['sha256'] or item['size'] != actual['size']:
raise ValueError('Generated review changed; export again')
allowed.add(item['path'])
if not set(STATIC + ('review.json',)).issubset(allowed):
raise ValueError('Incomplete generated review')
server = ThreadingHTTPServer((host, port), ReviewHandler)
server.daemon_threads = True
server.root, server.allowed = root, allowed
return server
def main():
parser = argparse.ArgumentParser(description=__doc__)
commands = parser.add_subparsers(dest='command', required=True)
export = commands.add_parser('export')
export.add_argument('--original', type=Path)
export.add_argument('--port', type=Path)
export.add_argument('--output', type=Path, required=True)
export.add_argument('--ledger', type=Path)
serve = commands.add_parser('serve')
serve.add_argument('--root', type=Path, required=True)
serve.add_argument('--port', type=int, default=8765)
args = parser.parse_args()
try:
if args.command == 'export':
model = export_review(args.original, args.port, args.output, args.ledger)
print(json.dumps({'path': str(args.output / 'index.html'),
'events': len(model['events']), 'acceptance': 'OPEN'}))
else:
with make_server(args.root, args.port) as server:
print(f'Local review: http://127.0.0.1:{server.server_port}/ — acceptance OPEN', flush=True)
server.serve_forever()
except (ValueError, OSError, subprocess.SubprocessError) as error:
parser.exit(2, 'Review error: ' + str(error) + '\n')
except KeyboardInterrupt:
parser.exit(0)
if __name__ == '__main__':
main()
+45
View File
@@ -0,0 +1,45 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>GamePort · Fidelity review</title>
<link rel="stylesheet" href="style.css">
<script type="module" src="viewer.mjs"></script>
</head>
<body>
<header><p class="eyebrow">NEUTRON GAMEPORT / LOCAL EVIDENCE</p><h1>Paired recording review</h1>
<p id="scope">Loading local review…</p><p class="notice">Acceptance OPEN · export and fixture playback do not establish original or native gameplay parity.</p></header>
<main>
<section aria-label="Paired recordings" class="pair">
<article id="original-panel"><h2>Original reference</h2><p class="classification"></p>
<video id="original" preload="metadata" playsinline muted></video>
<button class="side-play" type="button">Play original only</button><button class="side-pause" type="button">Pause</button>
<label>Original elapsed seek <input class="seek" aria-label="Seek original recording" type="range" min="0" max="0" value="0" step="0.01"></label>
<p class="missing"></p><output class="clock"></output><div class="links"></div></article>
<article id="port-panel"><h2>Port recording</h2><p class="classification"></p>
<video id="port" preload="metadata" playsinline muted></video>
<button class="side-play" type="button">Play port only</button><button class="side-pause" type="button">Pause</button>
<label>Port elapsed seek <input class="seek" aria-label="Seek port recording" type="range" min="0" max="0" value="0" step="0.01"></label>
<p class="missing"></p><output class="clock"></output><div class="links"></div></article>
</section>
<section class="review-controls" aria-label="Review controls">
<label>Observed event <select id="events"><option value="">Choose an event</option></select></label>
<button id="play" type="button">Play pair at 1×</button><button id="pause" type="button">Pause pair</button>
<label>Soundtrack <select id="audio"><option value="none">Muted</option><option value="original">Original</option><option value="port">Port</option></select></label>
<label>Review volume <input id="gain" type="range" min="0" max="1" step="0.05" value="1"></label>
<output id="gain-label">Unadjusted · 1.00</output>
<p id="state" role="status" aria-live="polite"></p><p id="drift"></p>
<p>Event selection pauses and seeks each observed marker. Playback resumes only when you press Play. Each recording keeps its complete duration at 1×.</p>
</section>
<section aria-label="Optional review aids"><h2>Review aids</h2>
<label><input id="annotations" type="checkbox"> Show event annotations</label>
<label><input id="difference" type="checkbox"> Show lossless still difference</label>
<p id="difference-state">Differences require matched lossless frame identity, viewport and crop metadata.</p>
<div id="annotation-layer" hidden></div><canvas id="difference-layer" hidden aria-label="Optional lossless still difference"></canvas>
<p>Raw recordings above remain unobstructed. Differences are review aids; lossy video is not a numerical fidelity measure.</p>
</section>
<section id="capabilities" aria-label="Capability evidence"></section>
</main>
</body>
</html>
+28
View File
@@ -0,0 +1,28 @@
:root { color-scheme: dark; font: 16px/1.5 system-ui, sans-serif; background: #111820; color: #e4ecf2; }
body { margin: 0 auto; max-width: 1600px; padding: 1.5rem; }
header { border-bottom: 1px solid #455669; margin-bottom: 1.5rem; }
h1 { font-size: clamp(1.7rem, 3vw, 2.6rem); margin: .3rem 0; }
h2 { font-size: 1.25rem; }
.eyebrow { letter-spacing: .1em; color: #9acac1; font-size: .8rem; }
.notice, .missing { color: #f5cf92; }
.pair { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 1.5rem; }
article, section.review-controls { background: #1a2530; border: 1px solid #455669; border-radius: .5rem; padding: 1rem; }
video { display: block; width: 100%; max-height: 65vh; background: #070a0f; }
section { margin-bottom: 1.5rem; }
label { display: inline-flex; align-items: center; gap: .5rem; margin: .5rem .75rem .5rem 0; }
button, select, input { font: inherit; }
button, select { color: inherit; background: #253e4d; border: 1px solid #809fae; border-radius: .3rem; padding: .5rem; }
button { cursor: pointer; margin: .3rem; }
button:disabled { opacity: .5; cursor: default; }
:focus-visible { outline: 3px solid #efc573; outline-offset: 3px; }
a { color: #9ad9e9; overflow-wrap: anywhere; }
.links { display: flex; flex-wrap: wrap; gap: .7rem; margin-top: .5rem; }
.classification { min-height: 3em; overflow-wrap: anywhere; }
output { font-variant-numeric: tabular-nums; }
dt { font-weight: 600; color: #acd0db; } dd { margin-left: 1rem; overflow-wrap: anywhere; }
h4 { margin: .8rem 0 .3rem; } ul { padding-left: 1.3rem; }
canvas { max-width: 100%; background: #000; }
details { margin: .5rem 0; }
summary { cursor: pointer; }
[hidden] { display: none !important; }
@media (max-width: 760px) { body { padding: .7rem; } .pair { grid-template-columns: 1fr; } label { display: flex; } }
+383
View File
@@ -0,0 +1,383 @@
// Native media, independent clocks. No follower seek or rate-based correction.
export function safeLocalURL(value) {
if (typeof value !== 'string' || value.length > 4096 || !value) throw Error('Missing local link');
const decoded = decodeURIComponent(value);
if (/[?#]/.test(value) || /[\\:<>"\u0000-\u001f]/.test(decoded) || decoded.startsWith('/') ||
decoded.split('/').some(p => !p || p === '.' || p === '..')) throw Error('Unsafe local link');
return value;
}
const finiteNonnegative = value => typeof value === 'number' && Number.isFinite(value) && value >= 0;
const sha = value => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
export function differenceEligibility(original, port) {
for (const a of [original, port]) {
const f = a?.frame;
if (!f || !sha(a.sha256) || !sha(f.media_sha256) || !f.lossless ||
!a.url?.toLowerCase().endsWith('.png') || !finiteNonnegative(f.media_seconds) ||
typeof f.event !== 'string' || !f.event || !(a.size > 0))
return {eligible: false, reason: 'Missing identified lossless PNG frame and source-media provenance'};
try { safeLocalURL(a.url); } catch { return {eligible: false, reason: 'Unsafe frame link'}; }
if (![f.width, f.height].every(n => Number.isInteger(n) && n > 0 && n <= 8192) ||
!Array.isArray(f.viewport) || f.viewport.length !== 2 ||
!f.viewport.every(n => Number.isInteger(n) && n > 0 && n <= 8192) ||
!Array.isArray(f.crop) || f.crop.length !== 4 ||
!f.crop.every(n => Number.isInteger(n) && n >= 0) ||
f.crop[2] !== f.width || f.crop[3] !== f.height ||
f.crop[0] + f.width > f.viewport[0] || f.crop[1] + f.height > f.viewport[1])
return {eligible: false, reason: 'Invalid frame dimensions, viewport or crop'};
}
const a = original.frame, b = port.frame;
if (a.event !== b.event || a.width !== b.width || a.height !== b.height ||
JSON.stringify(a.viewport) !== JSON.stringify(b.viewport) || JSON.stringify(a.crop) !== JSON.stringify(b.crop))
return {eligible: false, reason: 'Frame event, viewport/aspect or crop mismatch'};
return {eligible: true, reason: 'Matched identified lossless stills; review aid only'};
}
export function createPairController({original, port, onChange = () => {}, timeoutMs = 5000, frames = {}}) {
const media = {original, port};
let problem = '', selected = null, gain = 1, audio = 'none', generation = 0;
let selecting = false;
const overlays = {annotations: false, difference: false};
const listeners = [];
function snapshot() {
const sides = {};
for (const [side, m] of Object.entries(media)) {
sides[side] = {recording_seconds: m?.currentTime ?? null, duration: m?.duration ?? null,
aligned_elapsed: m && selected?.[side] ? m.currentTime - selected[side].media_seconds : null,
state: !m ? 'missing' : m.error ? 'decoding error' : m.currentTime >= m.duration ? 'ended' :
m.seeking ? 'seeking' : m.readyState < 3 ? 'buffering' : m.paused ? 'paused' : 'playing'};
}
return {problem, selected, sides, gain, audio, gainAdjusted: gain !== 1,
gainLabel: gain === 1 ? 'Unadjusted · 1.00' : 'Review-only volume · ' + gain.toFixed(2),
overlays: {...overlays}, selecting,
eventDrift: selected ? {seconds: selected.port.elapsed_seconds - selected.original.elapsed_seconds,
uncertainty_seconds: selected.original.uncertainty_seconds + selected.port.uncertainty_seconds} : null,
playbackDrift: selected && original && port ? sides.port.aligned_elapsed - sides.original.aligned_elapsed : null};
}
const notify = () => onChange(snapshot());
const pause = () => { generation++; selecting = false; for (const m of Object.values(media)) if (m) m.pause(); notify(); };
const fail = message => { problem = message; pause(); };
function listen(m, event, callback) {
m.addEventListener(event, callback); listeners.push(() => m.removeEventListener(event, callback));
}
function setAudio(side) {
if (!['none', 'original', 'port'].includes(side)) throw Error('Unknown soundtrack');
for (const m of Object.values(media)) if (m && !m.muted) m.muted = true;
audio = side;
if (media[side]) media[side].muted = false;
notify();
}
function setGain(value) {
if (!finiteNonnegative(value) || value > 1) throw Error('Review volume must be between zero and one');
gain = value;
for (const m of Object.values(media)) if (m && m.volume !== gain) m.volume = gain;
notify();
}
for (const [side, m] of Object.entries(media)) {
if (!m) continue;
m.muted = true; m.volume = 1; m.playbackRate = 1;
for (const event of ['waiting', 'stalled']) listen(m, event, () => {
if (!selecting) fail(side + ' buffering; wait for readiness then explicitly play');
});
listen(m, 'error', () => fail(side + ' decoding/media error (code ' + (m.error?.code ?? 'unknown') + ')'));
listen(m, 'ended', () => fail(side + ' ended; the other recording tail remains playable'));
listen(m, 'ratechange', () => { if (m.playbackRate !== 1) m.playbackRate = 1; notify(); });
for (const event of ['timeupdate', 'canplay', 'pause', 'playing', 'seeked']) listen(m, event, notify);
// The UI has dedicated audio controls and per-side play/seek controls.
// Guard external unmute changes as well; never enable a second soundtrack.
listen(m, 'volumechange', () => {
if (!m.muted && audio !== side) { m.muted = true; }
if (m.volume !== gain) m.volume = gain;
notify();
});
}
function waitUntil(m, ready, events, label) {
if (m.error) return Promise.reject(Error('Decode failure during ' + label));
if (ready()) return Promise.resolve();
return new Promise((resolve, reject) => {
let timer;
const clean = () => { clearTimeout(timer); for (const event of [...events, 'error']) m.removeEventListener(event, check); };
const check = () => {
if (m.error) { clean(); reject(Error('Decode failure during ' + label)); }
else if (ready()) { clean(); resolve(); }
};
for (const event of [...events, 'error']) m.addEventListener(event, check);
timer = setTimeout(() => { clean(); reject(Error(label + ' readiness timed out')); }, timeoutMs);
check();
});
}
async function seek(m, value) {
m.playbackRate = 1;
m.currentTime = value;
await waitUntil(m, () => !m.seeking, ['seeked'], 'Seek');
}
async function selectEvent(event) {
pause();
const token = generation;
selecting = true; problem = 'Waiting for event seek readiness'; notify();
try {
for (const side of ['original', 'port']) {
const marker = event?.[side];
if (!media[side] || !marker || !['media_seconds', 'elapsed_seconds', 'uncertainty_seconds']
.every(key => finiteNonnegative(marker[key]))) throw Error('Missing or invalid corresponding event');
}
await Promise.all(Object.values(media).map(m => waitUntil(m, () => m.readyState >= 1,
['loadedmetadata', 'durationchange', 'canplay'], 'Metadata')));
if (token !== generation) throw Error('Event selection cancelled');
for (const side of ['original', 'port']) {
if (!Number.isFinite(media[side].duration) || event[side].media_seconds > media[side].duration)
throw Error('Out-of-range corresponding event');
}
await Promise.all(Object.entries(media).map(([side, m]) => seek(m, event[side].media_seconds)));
if (token !== generation) throw Error('Event selection cancelled');
selected = structuredClone(event); problem = '';
} catch (error) { if (token === generation) fail(error.message); throw error; }
finally { if (token === generation) selecting = false; notify(); }
}
async function seekSide(side, seconds) {
pause();
const m = media[side];
if (!m || !finiteNonnegative(seconds) || !Number.isFinite(m.duration) || seconds > m.duration)
throw Error('Invalid manual seek');
try { await seek(m, seconds); problem = ''; notify(); }
catch (error) { fail(error.message); throw error; }
}
async function start(sides) {
if (selecting) { problem = 'Event seek still pending'; notify(); return false; }
const active = sides.filter(side => media[side] && media[side].currentTime < media[side].duration);
for (const side of active) {
const m = media[side];
if (m.error) { fail(side + ' decoding/media error'); return false; }
if (m.readyState < 3 || m.seeking) { fail(side + ' buffering or seeking; explicit recovery required'); return false; }
}
if (!active.length) { fail('Recordings ended or not ready; seek to review again'); return false; }
const token = ++generation;
try {
const results = await Promise.allSettled(active.map(side => {
media[side].playbackRate = 1;
return media[side].play();
}));
if (generation !== token) { for (const m of Object.values(media)) m?.pause(); notify(); return false; }
const rejected = results.find(r => r.status === 'rejected');
if (rejected) throw rejected.reason;
problem = ''; notify(); return true;
} catch (error) { fail('Play rejected: ' + error.message); return false; }
}
async function play() {
if (!original || !port) { fail('Missing recording; available side has manual controls'); return false; }
return start(['original', 'port']);
}
async function playSide(side) {
if (!media[side]) { fail('Missing ' + side + ' recording'); return false; }
pause();
return start([side]);
}
function setOverlay(name, enabled) {
if (!Object.hasOwn(overlays, name)) throw Error('Unknown overlay');
if (name === 'difference' && enabled) {
const eligible = differenceEligibility(frames.original, frames.port);
if (!eligible.eligible) throw Error(eligible.reason);
}
overlays[name] = Boolean(enabled); notify();
}
function dispose() {
pause(); for (const remove of listeners) remove();
}
return {selectEvent, play, playSide, seekSide, pause, snapshot, setAudio, setGain, setOverlay, dispose};
}
function element(doc, tag, text) { const node = doc.createElement(tag); node.textContent = text; return node; }
function describe(doc, value) {
if (Array.isArray(value)) {
const list = doc.createElement('ul');
for (const item of value) { const li = doc.createElement('li'); li.append(describe(doc, item)); list.append(li); }
if (!value.length) list.append(element(doc, 'li', 'None recorded'));
return list;
}
if (value && typeof value === 'object') {
const list = doc.createElement('dl');
for (const [key, item] of Object.entries(value)) {
const dd = doc.createElement('dd'); dd.append(describe(doc, item));
list.append(element(doc, 'dt', key.replaceAll('_', ' ')), dd);
}
return list;
}
return element(doc, 'span', value == null ? 'Unrecorded' : String(value));
}
export function renderCapabilities(container, ledger) {
const doc = container.ownerDocument;
container.replaceChildren(element(doc, 'h2', 'Capability evidence'));
const rows = ledger?.capabilities ?? [];
if (!rows.length) { container.append(element(doc, 'p', 'No capability ledger supplied. Acceptance remains open.')); return; }
const nav = doc.createElement('nav'); nav.setAttribute?.('aria-label', 'Browse gameplay capabilities');
for (const row of rows) {
const a = element(doc, 'a', row.group + ' · ' + row.id);
a.href = '#capability-' + encodeURIComponent(row.id); nav.append(a, element(doc, 'span', ' · '));
}
container.append(nav);
for (const row of rows) {
const article = doc.createElement('article');
article.id = 'capability-' + encodeURIComponent(row.id);
article.append(element(doc, 'h3', row.group + ' · ' + row.id), element(doc, 'p', row.summary),
element(doc, 'p', 'Requirements: ' + (row.requirement_ids ?? []).join(', ')));
const impact = {blocking: 0, disruptive: 1, subtle: 2, missing_verification: 3};
const discrepancies = [...(row.discrepancies ?? [])].sort((a, b) =>
(impact[a.impact] ?? 4) - (impact[b.impact] ?? 4) || String(a.id).localeCompare(String(b.id)));
for (const [label, value] of [['Verified scope', row.verified_scope], ['Known differences', row.differences],
['Acceptance conditions', row.acceptance], ['Current applicable evidence', row.current],
['Discrepancies by impact', discrepancies], ['Scenarios', row.scenario_ids]]) {
article.append(element(doc, 'h4', label), describe(doc, value));
}
article.append(element(doc, 'h4', 'Source evidence'));
for (const link of row.source_links ?? []) {
if (link.validated_local === true && typeof link.href === 'string' && link.href.startsWith('sources/')) {
try {
const a = element(doc, 'a', link.label + ' · ' + link.path);
a.href = safeLocalURL(link.href); a.target = '_blank'; a.rel = 'noopener'; article.append(a);
} catch { article.append(element(doc, 'p', 'Invalid local source link')); }
} else article.append(element(doc, 'p', (link.label ?? String(link)) + ' · ' + (link.path ?? '') +
' · ' + (link.missing ?? 'Source reference not bundled; acceptance remains open')));
}
const history = doc.createElement('details');
history.append(element(doc, 'summary', 'History / superseded evidence'), describe(doc, row.history));
article.append(history); container.append(article);
}
}
export function framePair(model) {
const candidates = {};
for (const side of ['original', 'port']) {
const s = model.sides[side];
candidates[side] = s.artifacts.filter(a => a.frame && a.frame.media_sha256 === s.media?.sha256 &&
finiteNonnegative(a.frame.media_seconds) && a.frame.media_seconds <= s.media.duration_seconds &&
s.events.some(e => e.name === a.frame.event && e.artifact === s.media.path &&
e.media_seconds === a.frame.media_seconds));
}
for (const a of candidates.original) for (const b of candidates.port) {
if (differenceEligibility(a, b).eligible) return {original: a, port: b};
}
return {original: candidates.original[0], port: candidates.port[0]};
}
async function drawDifference(canvas, frames) {
const eligible = differenceEligibility(frames.original, frames.port);
if (!eligible.eligible) throw Error(eligible.reason);
const images = await Promise.all([frames.original, frames.port].map(a => new Promise((resolve, reject) => {
const image = new Image(); image.onload = () => resolve(image);
image.onerror = () => reject(Error('Lossless still failed to decode'));
image.src = safeLocalURL(a.url);
})));
const {width, height} = frames.original.frame;
if (images.some(i => i.naturalWidth !== width || i.naturalHeight !== height))
throw Error('Decoded still dimensions disagree with identified metadata');
canvas.width = width; canvas.height = height;
const context = canvas.getContext('2d', {willReadFrequently: true});
context.drawImage(images[0], 0, 0);
const a = context.getImageData(0, 0, width, height);
context.drawImage(images[1], 0, 0);
const b = context.getImageData(0, 0, width, height);
for (let i = 0; i < a.data.length; i += 4) {
for (let c = 0; c < 3; c++) a.data[i + c] = Math.abs(a.data[i + c] - b.data[i + c]);
a.data[i + 3] = 255;
}
context.putImageData(a, 0, 0);
}
async function mount() {
const doc = document;
try {
const response = await fetch('review.json');
if (!response.ok) throw Error('Review JSON unavailable');
const model = await response.json();
doc.querySelector('#scope').textContent = 'Case: ' + model.case_id;
const media = {};
for (const side of ['original', 'port']) {
const data = model.sides[side], panel = doc.querySelector('#' + side + '-panel');
const m = doc.querySelector('#' + side);
media[side] = data.media ? m : null;
if (data.media) m.src = safeLocalURL(data.media.url);
panel.querySelector('.missing').textContent = [data.missing, data.reference_warning].filter(Boolean).join(' · ');
panel.querySelector('.classification').textContent = [data.evidence_kind ?? 'missing',
JSON.stringify(data.platform ?? {}), data.scope ?? '', data.historical ? 'HISTORICAL' : '',
...(data.limitations ?? [])].join(' · ');
for (const artifact of data.artifacts) {
const a = element(doc, 'a', artifact.role + ' · ' + artifact.path);
a.href = safeLocalURL(artifact.url); a.target = '_blank'; a.rel = 'noopener';
panel.querySelector('.links').append(a);
}
}
const frames = framePair(model);
const format = n => Number.isFinite(n) ? n.toFixed(3) + ' s' : 'unrecorded';
function display(state) {
doc.querySelector('#state').textContent = state.problem || 'Review at actual recording speed · 1×';
doc.querySelector('#gain-label').textContent = state.gainLabel;
for (const side of ['original', 'port']) {
const panel = doc.querySelector('#' + side + '-panel'), clock = state.sides[side];
panel.querySelector('.clock').textContent = 'Recording elapsed ' + format(clock.recording_seconds) +
' / ' + format(clock.duration) + ' · Event offset ' + format(clock.aligned_elapsed) + ' · ' + clock.state;
const seek = panel.querySelector('.seek');
seek.max = String(Number.isFinite(clock.duration) ? clock.duration : 0);
seek.value = String(clock.recording_seconds ?? 0);
}
doc.querySelector('#drift').textContent = state.eventDrift ?
'Observed scenario-event drift (port − original): ' + format(state.eventDrift.seconds) +
' ± ' + format(state.eventDrift.uncertainty_seconds) +
' · Browser playback drift after selected anchors: ' + format(state.playbackDrift) :
'Select corresponding observed markers to see scenario-event and playback drift separately.';
}
const controller = createPairController({...media, frames, onChange: display});
display(controller.snapshot());
for (const side of ['original', 'port']) {
const panel = doc.querySelector('#' + side + '-panel');
panel.querySelector('.side-play').disabled = !media[side];
panel.querySelector('.seek').disabled = !media[side];
panel.querySelector('.side-play').addEventListener('click', () => controller.playSide(side));
panel.querySelector('.side-pause').addEventListener('click', controller.pause);
panel.querySelector('.seek').addEventListener('change', async event => {
try { await controller.seekSide(side, Number(event.target.value)); }
catch (error) { doc.querySelector('#state').textContent = error.message; }
});
const receipt = model.sides[side].receipt_url;
if (receipt) {
const a = element(doc, 'a', 'Receipt / raw and derivative provenance');
a.href = safeLocalURL(receipt); a.target = '_blank'; a.rel = 'noopener';
panel.querySelector('.links').append(a);
}
}
const events = doc.querySelector('#events');
model.events.forEach((event, i) => { const option = element(doc, 'option', event.name +
(!event.original || !event.port ? ' · missing correspondence' : '')); option.value = String(i); events.append(option); });
events.addEventListener('change', async () => {
if (events.value === '') return;
try { await controller.selectEvent(model.events[Number(events.value)]); }
catch (error) { doc.querySelector('#state').textContent = error.message; }
});
doc.querySelector('#play').addEventListener('click', () => controller.play());
doc.querySelector('#pause').addEventListener('click', controller.pause);
doc.querySelector('#audio').addEventListener('change', event => controller.setAudio(event.target.value));
doc.querySelector('#gain').addEventListener('input', event => controller.setGain(Number(event.target.value)));
const annotations = doc.querySelector('#annotation-layer');
annotations.textContent = model.events.map(e => e.name + ' · Original ' + format(e.original?.media_seconds) +
' · Port ' + format(e.port?.media_seconds)).join(' | ');
doc.querySelector('#annotations').addEventListener('change', event => {
controller.setOverlay('annotations', event.target.checked); annotations.hidden = !event.target.checked;
});
const eligibility = differenceEligibility(frames.original, frames.port);
doc.querySelector('#difference-state').textContent = eligibility.reason;
doc.querySelector('#difference').addEventListener('change', async event => {
const canvas = doc.querySelector('#difference-layer');
try {
controller.setOverlay('difference', event.target.checked);
if (event.target.checked) await drawDifference(canvas, frames);
canvas.hidden = !event.target.checked;
} catch (error) {
event.target.checked = false; controller.setOverlay('difference', false); canvas.hidden = true;
doc.querySelector('#difference-state').textContent = error.message;
}
});
renderCapabilities(doc.querySelector('#capabilities'), model.ledger);
} catch (error) { doc.querySelector('#scope').textContent = 'Review unavailable: ' + error.message; }
}
if (typeof document !== 'undefined') mount();