feat(01-02): preserve clocks exclusive audio and complete review tails

This commit is contained in:
UnixNight committed 2026-11-12 19:46:04 -05:00
1 parent 75d7ca4279
commit 91da92f17d
6 files changed
+505 -47

No files matched your search

+58
View File
@@ -209,6 +209,64 @@ test('nonfinite elapsed or uncertainty is rejected before seeking', async () =>
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');
});
+76 -2
View File
@@ -130,12 +130,14 @@ class FidelityReview(unittest.TestCase):
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.assertRaises(ValueError): self.api().export_review(raw, None, self.output)
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()
@@ -155,11 +157,60 @@ class FidelityReview(unittest.TestCase):
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.assertRaises(ValueError): self.api().export_review(raw, None, self.output)
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)
@@ -211,6 +262,29 @@ class FidelityReview(unittest.TestCase):
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()
+55 -7
View File
@@ -14,6 +14,7 @@ import os
from pathlib import Path
import re
import shutil
import subprocess
import tempfile
from urllib.parse import quote, unquote, urlsplit
@@ -53,6 +54,8 @@ def _side(path, side):
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'))
@@ -73,13 +76,48 @@ def _events(sides):
def _ledger(path):
if path is None:
return {'schema_version': 1, 'capabilities': []}
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')
# Source links are references, never commands or remote URLs. Only exported
# media/receipt links are clickable; source paths remain inert navigation text.
return data
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):
@@ -98,8 +136,10 @@ def export_review(original, port, output, ledger=None):
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(ledger),
'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:
@@ -195,8 +235,10 @@ class ReviewHandler(BaseHTTPRequestHandler):
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 (mime.startswith(('video/', 'audio/')) or
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')
@@ -221,6 +263,10 @@ class ReviewHandler(BaseHTTPRequestHandler):
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)
@@ -272,8 +318,10 @@ def main():
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) as error:
except (ValueError, OSError, subprocess.SubprocessError) as error:
parser.exit(2, 'Review error: ' + str(error) + '\n')
except KeyboardInterrupt:
parser.exit(0)
if __name__ == '__main__':
+7 -2
View File
@@ -13,10 +13,14 @@
<main>
<section aria-label="Paired recordings" class="pair">
<article id="original-panel"><h2>Original reference</h2><p class="classification"></p>
<video id="original" controls preload="metadata" playsinline muted></video>
<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" controls preload="metadata" playsinline muted></video>
<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">
@@ -26,6 +30,7 @@
<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>
+2
View File
@@ -19,6 +19,8 @@ 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; }
+307 -36
View File
@@ -2,74 +2,289 @@
export function safeLocalURL(value) {
if (typeof value !== 'string' || value.length > 4096 || !value) throw Error('Missing local link');
const decoded = decodeURIComponent(value);
if (/[\\:?#<>"\u0000-\u0020]/.test(decoded) || decoded.startsWith('/') ||
if (/[?#]/.test(value) || /[\\:<>"\u0000-\u001f]/.test(decoded) || decoded.startsWith('/') ||
decoded.split('/').some(p => !p || p === '.' || p === '..')) throw Error('Unsafe local link');
return value;
}
export function createPairController({original, port, onChange = () => {}}) {
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;
const snapshot = () => ({problem, selected});
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 = () => { for (const m of Object.values(media)) if (m) m.pause(); notify(); };
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.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.addEventListener('waiting', () => fail(side + ' buffering'));
m.addEventListener('error', () => fail(side + ' decoding/media error'));
m.currentTime = value;
await waitUntil(m, () => !m.seeking, ['seeked'], 'Seek');
}
async function selectEvent(event) {
pause();
for (const side of ['original', 'port']) {
const m = media[side], marker = event?.[side];
if (!m || !marker || !Number.isFinite(marker.media_seconds) || marker.media_seconds < 0 ||
marker.media_seconds > m.duration) throw Error('Missing or out-of-range corresponding event');
}
for (const side of ['original', 'port']) {
media[side].playbackRate = 1;
media[side].currentTime = event[side].media_seconds;
}
selected = event; problem = ''; notify();
}
async function play() {
if (!original || !port) { fail('Missing recording'); return false; }
const token = generation;
selecting = true; problem = 'Waiting for event seek readiness'; notify();
try {
for (const m of Object.values(media)) m.playbackRate = 1;
const results = await Promise.allSettled(Object.values(media).map(m => m.play()));
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; }
}
return {selectEvent, play, pause, snapshot};
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(', ')),
element(doc, 'p', 'Verified scope: ' + JSON.stringify(row.verified_scope)),
element(doc, 'p', 'Differences: ' + JSON.stringify(row.differences)),
element(doc, 'p', 'Acceptance: ' + JSON.stringify(row.acceptance)),
element(doc, 'p', 'Current evidence: ' + JSON.stringify(row.current)),
element(doc, 'p', 'Scenarios: ' + row.scenario_ids.join(', ')),
element(doc, 'p', 'Source references: ' + JSON.stringify(row.source_links)));
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'), element(doc, 'p', JSON.stringify(row.history)));
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 {
@@ -83,7 +298,7 @@ async function mount() {
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;
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(' · ');
@@ -93,9 +308,44 @@ async function mount() {
panel.querySelector('.links').append(a);
}
}
const controller = createPairController({...media, onChange: state => {
doc.querySelector('#state').textContent = state.problem || 'Paused or playing at actual recording speed';
}});
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); });
@@ -106,6 +356,27 @@ async function mount() {
});
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; }
}