From 49f874e64cb836862fc05cc895ee666ee1201838 Mon Sep 17 00:00:00 2001 From: Cristian Cerroni Date: Thu, 12 Nov 2026 19:34:06 -0500 Subject: [PATCH] feat(01-02): export and serve validated local media pairs --- tests/fidelity-viewer.test.mjs | 7 +- tests/test_fidelity_review.py | 3 + tools/recon/fidelity_review.py | 280 +++++++++++++++++++++++++ tools/recon/fidelity_viewer/index.html | 40 ++++ tools/recon/fidelity_viewer/style.css | 26 +++ tools/recon/fidelity_viewer/viewer.mjs | 112 ++++++++++ 6 files changed, 465 insertions(+), 3 deletions(-) create mode 100644 tools/recon/fidelity_review.py create mode 100644 tools/recon/fidelity_viewer/index.html create mode 100644 tools/recon/fidelity_viewer/style.css create mode 100644 tools/recon/fidelity_viewer/viewer.mjs diff --git a/tests/fidelity-viewer.test.mjs b/tests/fidelity-viewer.test.mjs index 36faddd..c40644b 100644 --- a/tests/fidelity-viewer.test.mjs +++ b/tests/fidelity-viewer.test.mjs @@ -1,7 +1,8 @@ -import test from 'node:test'; +import nodeTest from 'node:test'; import assert from 'node:assert/strict'; -import {pathToFileURL} from 'node:url'; 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) : {}; @@ -54,5 +55,5 @@ test('capability navigation is supplied through a renderer', () => { assert.equal(typeof api.renderCapabilities, 'function'); }); test('suite executes a positive declared count', () => { - assert.ok(6 > 0); + assert.ok(declared >= 6, 'runner must register a positive number of behavior tests'); }); diff --git a/tests/test_fidelity_review.py b/tests/test_fidelity_review.py index 6478c5a..235cd2e 100644 --- a/tests/test_fidelity_review.py +++ b/tests/test_fidelity_review.py @@ -146,6 +146,9 @@ class FidelityReview(unittest.TestCase): 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()) diff --git a/tools/recon/fidelity_review.py b/tools/recon/fidelity_review.py new file mode 100644 index 0000000..7774701 --- /dev/null +++ b/tools/recon/fidelity_review.py @@ -0,0 +1,280 @@ +"""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 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', + 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') + # Source links are references, never commands or remote URLs. Only exported + # media/receipt links are clickable; source paths remain inert navigation text. + return data + + +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') + model = {'schema_version': 1, 'case_id': present[0]['case_id'] if present else 'empty', + 'sides': sides, 'events': _events(sides), 'ledger': _ledger(ledger), + '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' + # Imported HTML/SVG/scripts never become active same-origin content. + if name not in STATIC 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 (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) as error: + parser.exit(2, 'Review error: ' + str(error) + '\n') + + +if __name__ == '__main__': + main() diff --git a/tools/recon/fidelity_viewer/index.html b/tools/recon/fidelity_viewer/index.html new file mode 100644 index 0000000..c777fb8 --- /dev/null +++ b/tools/recon/fidelity_viewer/index.html @@ -0,0 +1,40 @@ + + + + + + GamePort · Fidelity review + + + + +

NEUTRON GAMEPORT / LOCAL EVIDENCE

Paired recording review

+

Loading local review…

Acceptance OPEN · export and fixture playback do not establish original or native gameplay parity.

+
+
+

Original reference

+ +

+

Port recording

+ +

+
+
+ + + + + Unadjusted · 1.00 +

+
+

Review aids

+ + +

Differences require matched lossless frame identity, viewport and crop metadata.

+ +

Raw recordings above remain unobstructed. Differences are review aids; lossy video is not a numerical fidelity measure.

+
+
+
+ + diff --git a/tools/recon/fidelity_viewer/style.css b/tools/recon/fidelity_viewer/style.css new file mode 100644 index 0000000..ab8f989 --- /dev/null +++ b/tools/recon/fidelity_viewer/style.css @@ -0,0 +1,26 @@ +: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; } +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; } } diff --git a/tools/recon/fidelity_viewer/viewer.mjs b/tools/recon/fidelity_viewer/viewer.mjs new file mode 100644 index 0000000..486f89c --- /dev/null +++ b/tools/recon/fidelity_viewer/viewer.mjs @@ -0,0 +1,112 @@ +// 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 (/[\\:?#<>"\u0000-\u0020]/.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 media = {original, port}; + let problem = '', selected = null; + const snapshot = () => ({problem, selected}); + const notify = () => onChange(snapshot()); + const pause = () => { for (const m of Object.values(media)) if (m) m.pause(); notify(); }; + const fail = message => { problem = message; pause(); }; + for (const [side, m] of Object.entries(media)) { + if (!m) continue; + m.muted = true; + m.playbackRate = 1; + m.addEventListener('waiting', () => fail(side + ' buffering')); + m.addEventListener('error', () => fail(side + ' decoding/media error')); + } + 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; } + try { + for (const m of Object.values(media)) m.playbackRate = 1; + const results = await Promise.allSettled(Object.values(media).map(m => m.play())); + 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}; +} + +function element(doc, tag, text) { const node = doc.createElement(tag); node.textContent = text; return node; } + +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; } + for (const row of rows) { + const article = doc.createElement('article'); + 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))); + const history = doc.createElement('details'); + history.append(element(doc, 'summary', 'History / superseded evidence'), element(doc, 'p', JSON.stringify(row.history))); + article.append(history); container.append(article); + } +} + +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; + 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 controller = createPairController({...media, onChange: state => { + doc.querySelector('#state').textContent = state.problem || 'Paused or playing at actual recording speed'; + }}); + 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); + renderCapabilities(doc.querySelector('#capabilities'), model.ledger); + } catch (error) { doc.querySelector('#scope').textContent = 'Review unavailable: ' + error.message; } +} +if (typeof document !== 'undefined') mount();