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}})); await assert.rejects(controller.selectEvent({...marker, original: {...marker.original, ...patch}}));
assert.equal(original.currentTime, 0); 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', () => { test('suite executes at least sixteen registered behavior tests', () => {
assert.ok(declared >= 16, 'runner must register at least sixteen 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() with self.assertRaises(ValueError): self.export()
def test_traversal_absolute_remote_and_symlink_references_rejected(self): 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'): for path in ('../secret', '/secret', 'C:/secret', 'https://host/a', 'a\\b'):
value = copy.deepcopy(self.value) value = copy.deepcopy(self.value)
value['artifacts'][0]['path'] = path value['artifacts'][0]['path'] = path
raw = self.original.parent / 'raw.json' raw = self.original.parent / 'raw.json'
raw.write_text(json.dumps(value)) 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').unlink()
(self.original.parent / 'video.wav').symlink_to(self.port.parent / 'video.wav') (self.original.parent / 'video.wav').symlink_to(self.port.parent / 'video.wav')
with self.assertRaises(ValueError): self.export() with self.assertRaises(ValueError): self.export()
@@ -155,11 +157,60 @@ class FidelityReview(unittest.TestCase):
self.assertNotIn('innerHTML', (self.output / 'viewer.mjs').read_text()) self.assertNotIn('innerHTML', (self.output / 'viewer.mjs').read_text())
def test_event_out_of_range_rejected(self): def test_event_out_of_range_rejected(self):
(self.original.parent / 'receipt.sha256').unlink()
value = copy.deepcopy(self.value) value = copy.deepcopy(self.value)
value['events'][0]['media_seconds'] = 3 value['events'][0]['media_seconds'] = 3
raw = self.original.parent / 'raw.json' raw = self.original.parent / 'raw.json'
raw.write_text(json.dumps(value)) 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): def test_existing_or_overlapping_output_rejected(self):
with self.assertRaises(ValueError): self.api().export_review(self.original, self.port, self.original.parent) 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.assertEqual(response.headers['X-Content-Type-Options'], 'nosniff')
self.assertIn("default-src 'none'", response.headers['Content-Security-Policy']) 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__': if __name__ == '__main__':
unittest.main() unittest.main()
+55 -7
View File
@@ -14,6 +14,7 @@ import os
from pathlib import Path from pathlib import Path
import re import re
import shutil import shutil
import subprocess
import tempfile import tempfile
from urllib.parse import quote, unquote, urlsplit from urllib.parse import quote, unquote, urlsplit
@@ -53,6 +54,8 @@ def _side(path, side):
derivatives=value['derivatives'], receipt_url=prefix + 'receipt.json', derivatives=value['derivatives'], receipt_url=prefix + 'receipt.json',
missing_evidence=validation['missing_evidence'], missing_evidence=validation['missing_evidence'],
missing='' if media else 'Missing ' + side + ' playable video/preview', 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']}) acceptance={'state': 'open', 'remaining': ['Review export is not acceptance']})
copies = [(contained_path(path.parent, name), prefix + name) for name in sorted(paths)] copies = [(contained_path(path.parent, name), prefix + name) for name in sorted(paths)]
copies.append((path, prefix + 'receipt.json')) copies.append((path, prefix + 'receipt.json'))
@@ -73,13 +76,48 @@ def _events(sides):
def _ledger(path): def _ledger(path):
if path is None: if path is None:
return {'schema_version': 1, 'capabilities': []} return {'schema_version': 1, 'capabilities': []}, []
data = read_json(path) data = read_json(path)
if data.get('schema_version') != 1 or not isinstance(data.get('capabilities'), list): if data.get('schema_version') != 1 or not isinstance(data.get('capabilities'), list):
raise ValueError('Unsupported capability export') raise ValueError('Unsupported capability export')
# Source links are references, never commands or remote URLs. Only exported result = subprocess.run(['git', '-C', str(PROJECT), 'ls-files', '-z'],
# media/receipt links are clickable; source paths remain inert navigation text. capture_output=True, check=True, timeout=20)
return data 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): 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] present = [s for s in sides.values() if 'case_id' in s]
if len({(s['case_id'], s['scope']) for s in present}) > 1: if len({(s['case_id'], s['scope']) for s in present}) > 1:
raise ValueError('Paired receipts must describe the same case and scope') 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', 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']}} 'acceptance': {'state': 'open', 'remaining': ['Actual identified runtime and audiovisual review required']}}
encoded = canonical_bytes(model) encoded = canonical_bytes(model)
if len(encoded) > MAX_JSON_BYTES: if len(encoded) > MAX_JSON_BYTES:
@@ -195,8 +235,10 @@ class ReviewHandler(BaseHTTPRequestHandler):
self.send_response(status) self.send_response(status)
mime = 'text/javascript' if name.endswith('.mjs') else mimetypes.guess_type(name)[0] mime = 'text/javascript' if name.endswith('.mjs') else mimetypes.guess_type(name)[0]
mime = mime or 'application/octet-stream' 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. # 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 in ('image/png', 'image/jpeg', 'image/webp', 'application/json')):
mime = 'application/octet-stream' mime = 'application/octet-stream'
self.send_header('Content-Disposition', 'attachment') 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-Range', f'bytes */{size}')
self.send_header('Content-Length', '0') self.send_header('Content-Length', '0')
self.end_headers() 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): except (ValueError, UnicodeError, OSError):
self.send_error(403) self.send_error(403)
@@ -272,8 +318,10 @@ def main():
with make_server(args.root, args.port) as server: 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) print(f'Local review: http://127.0.0.1:{server.server_port}/ — acceptance OPEN', flush=True)
server.serve_forever() server.serve_forever()
except (ValueError, OSError) as error: except (ValueError, OSError, subprocess.SubprocessError) as error:
parser.exit(2, 'Review error: ' + str(error) + '\n') parser.exit(2, 'Review error: ' + str(error) + '\n')
except KeyboardInterrupt:
parser.exit(0)
if __name__ == '__main__': if __name__ == '__main__':
+7 -2
View File
@@ -13,10 +13,14 @@
<main> <main>
<section aria-label="Paired recordings" class="pair"> <section aria-label="Paired recordings" class="pair">
<article id="original-panel"><h2>Original reference</h2><p class="classification"></p> <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> <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> <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> <p class="missing"></p><output class="clock"></output><div class="links"></div></article>
</section> </section>
<section class="review-controls" aria-label="Review controls"> <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> <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> <output id="gain-label">Unadjusted · 1.00</output>
<p id="state" role="status" aria-live="polite"></p><p id="drift"></p> <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>
<section aria-label="Optional review aids"><h2>Review aids</h2> <section aria-label="Optional review aids"><h2>Review aids</h2>
<label><input id="annotations" type="checkbox"> Show event annotations</label> <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; } .links { display: flex; flex-wrap: wrap; gap: .7rem; margin-top: .5rem; }
.classification { min-height: 3em; overflow-wrap: anywhere; } .classification { min-height: 3em; overflow-wrap: anywhere; }
output { font-variant-numeric: tabular-nums; } 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; } canvas { max-width: 100%; background: #000; }
details { margin: .5rem 0; } details { margin: .5rem 0; }
summary { cursor: pointer; } summary { cursor: pointer; }
+307 -36
View File
@@ -2,74 +2,289 @@
export function safeLocalURL(value) { export function safeLocalURL(value) {
if (typeof value !== 'string' || value.length > 4096 || !value) throw Error('Missing local link'); if (typeof value !== 'string' || value.length > 4096 || !value) throw Error('Missing local link');
const decoded = decodeURIComponent(value); 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'); decoded.split('/').some(p => !p || p === '.' || p === '..')) throw Error('Unsafe local link');
return value; 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}; const media = {original, port};
let problem = '', selected = null; let problem = '', selected = null, gain = 1, audio = 'none', generation = 0;
const snapshot = () => ({problem, selected}); 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 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(); }; 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)) { for (const [side, m] of Object.entries(media)) {
if (!m) continue; 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.playbackRate = 1;
m.addEventListener('waiting', () => fail(side + ' buffering')); m.currentTime = value;
m.addEventListener('error', () => fail(side + ' decoding/media error')); await waitUntil(m, () => !m.seeking, ['seeked'], 'Seek');
} }
async function selectEvent(event) { async function selectEvent(event) {
pause(); pause();
for (const side of ['original', 'port']) { const token = generation;
const m = media[side], marker = event?.[side]; selecting = true; problem = 'Waiting for event seek readiness'; notify();
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; }
try { try {
for (const m of Object.values(media)) m.playbackRate = 1; for (const side of ['original', 'port']) {
const results = await Promise.allSettled(Object.values(media).map(m => m.play())); 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'); const rejected = results.find(r => r.status === 'rejected');
if (rejected) throw rejected.reason; if (rejected) throw rejected.reason;
problem = ''; notify(); return true; problem = ''; notify(); return true;
} catch (error) { fail('Play rejected: ' + error.message); return false; } } 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 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) { export function renderCapabilities(container, ledger) {
const doc = container.ownerDocument; const doc = container.ownerDocument;
container.replaceChildren(element(doc, 'h2', 'Capability evidence')); container.replaceChildren(element(doc, 'h2', 'Capability evidence'));
const rows = ledger?.capabilities ?? []; const rows = ledger?.capabilities ?? [];
if (!rows.length) { container.append(element(doc, 'p', 'No capability ledger supplied. Acceptance remains open.')); return; } 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) { for (const row of rows) {
const article = doc.createElement('article'); 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), 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', 'Requirements: ' + (row.requirement_ids ?? []).join(', ')));
element(doc, 'p', 'Verified scope: ' + JSON.stringify(row.verified_scope)), const impact = {blocking: 0, disruptive: 1, subtle: 2, missing_verification: 3};
element(doc, 'p', 'Differences: ' + JSON.stringify(row.differences)), const discrepancies = [...(row.discrepancies ?? [])].sort((a, b) =>
element(doc, 'p', 'Acceptance: ' + JSON.stringify(row.acceptance)), (impact[a.impact] ?? 4) - (impact[b.impact] ?? 4) || String(a.id).localeCompare(String(b.id)));
element(doc, 'p', 'Current evidence: ' + JSON.stringify(row.current)), for (const [label, value] of [['Verified scope', row.verified_scope], ['Known differences', row.differences],
element(doc, 'p', 'Scenarios: ' + row.scenario_ids.join(', ')), ['Acceptance conditions', row.acceptance], ['Current applicable evidence', row.current],
element(doc, 'p', 'Source references: ' + JSON.stringify(row.source_links))); ['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'); 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); 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() { async function mount() {
const doc = document; const doc = document;
try { try {
@@ -83,7 +298,7 @@ async function mount() {
const m = doc.querySelector('#' + side); const m = doc.querySelector('#' + side);
media[side] = data.media ? m : null; media[side] = data.media ? m : null;
if (data.media) m.src = safeLocalURL(data.media.url); 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', panel.querySelector('.classification').textContent = [data.evidence_kind ?? 'missing',
JSON.stringify(data.platform ?? {}), data.scope ?? '', data.historical ? 'HISTORICAL' : '', JSON.stringify(data.platform ?? {}), data.scope ?? '', data.historical ? 'HISTORICAL' : '',
...(data.limitations ?? [])].join(' · '); ...(data.limitations ?? [])].join(' · ');
@@ -93,9 +308,44 @@ async function mount() {
panel.querySelector('.links').append(a); panel.querySelector('.links').append(a);
} }
} }
const controller = createPairController({...media, onChange: state => { const frames = framePair(model);
doc.querySelector('#state').textContent = state.problem || 'Paused or playing at actual recording speed'; 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'); const events = doc.querySelector('#events');
model.events.forEach((event, i) => { const option = element(doc, 'option', event.name + 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); }); (!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('#play').addEventListener('click', () => controller.play());
doc.querySelector('#pause').addEventListener('click', controller.pause); 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); renderCapabilities(doc.querySelector('#capabilities'), model.ledger);
} catch (error) { doc.querySelector('#scope').textContent = 'Review unavailable: ' + error.message; } } catch (error) { doc.querySelector('#scope').textContent = 'Review unavailable: ' + error.message; }
} }