feat(01-02): export and serve validated local media pairs

This commit is contained in:
UnixNight committed 2026-11-12 19:34:06 -05:00
1 parent 488c904807
commit 49f874e64c
6 files changed
+465 -3

No files matched your search

+4 -3
View File
@@ -1,7 +1,8 @@
import test from 'node:test'; import nodeTest from 'node:test';
import assert from 'node:assert/strict'; import assert from 'node:assert/strict';
import {pathToFileURL} from 'node:url';
import {existsSync} from 'node:fs'; 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 modulePath = new URL('../tools/recon/fidelity_viewer/viewer.mjs', import.meta.url);
const api = existsSync(modulePath) ? await import(modulePath) : {}; 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'); assert.equal(typeof api.renderCapabilities, 'function');
}); });
test('suite executes a positive declared count', () => { test('suite executes a positive declared count', () => {
assert.ok(6 > 0); assert.ok(declared >= 6, 'runner must register a positive number of behavior tests');
}); });
+3
View File
@@ -146,6 +146,9 @@ class FidelityReview(unittest.TestCase):
value['limitations'].append(hostile) value['limitations'].append(hostile)
raw = self.original.parent / 'raw.json' raw = self.original.parent / 'raw.json'
raw.write_text(json.dumps(value)) 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) data = self.api().export_review(raw, None, self.output)
self.assertIn(hostile, data['sides']['original']['limitations']) self.assertIn(hostile, data['sides']['original']['limitations'])
self.assertNotIn(hostile, (self.output / 'index.html').read_text()) self.assertNotIn(hostile, (self.output / 'index.html').read_text())
+280
View File
@@ -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()
+40
View File
@@ -0,0 +1,40 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>GamePort · Fidelity review</title>
<link rel="stylesheet" href="style.css">
<script type="module" src="viewer.mjs"></script>
</head>
<body>
<header><p class="eyebrow">NEUTRON GAMEPORT / LOCAL EVIDENCE</p><h1>Paired recording review</h1>
<p id="scope">Loading local review…</p><p class="notice">Acceptance OPEN · export and fixture playback do not establish original or native gameplay parity.</p></header>
<main>
<section aria-label="Paired recordings" class="pair">
<article id="original-panel"><h2>Original reference</h2><p class="classification"></p>
<video id="original" controls preload="metadata" playsinline muted></video>
<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>
<p class="missing"></p><output class="clock"></output><div class="links"></div></article>
</section>
<section class="review-controls" aria-label="Review controls">
<label>Observed event <select id="events"><option value="">Choose an event</option></select></label>
<button id="play" type="button">Play pair at 1×</button><button id="pause" type="button">Pause pair</button>
<label>Soundtrack <select id="audio"><option value="none">Muted</option><option value="original">Original</option><option value="port">Port</option></select></label>
<label>Review volume <input id="gain" type="range" min="0" max="1" step="0.05" value="1"></label>
<output id="gain-label">Unadjusted · 1.00</output>
<p id="state" role="status" aria-live="polite"></p><p id="drift"></p>
</section>
<section aria-label="Optional review aids"><h2>Review aids</h2>
<label><input id="annotations" type="checkbox"> Show event annotations</label>
<label><input id="difference" type="checkbox"> Show lossless still difference</label>
<p id="difference-state">Differences require matched lossless frame identity, viewport and crop metadata.</p>
<div id="annotation-layer" hidden></div><canvas id="difference-layer" hidden aria-label="Optional lossless still difference"></canvas>
<p>Raw recordings above remain unobstructed. Differences are review aids; lossy video is not a numerical fidelity measure.</p>
</section>
<section id="capabilities" aria-label="Capability evidence"></section>
</main>
</body>
</html>
+26
View File
@@ -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; } }
+112
View File
@@ -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();