#!/usr/bin/env python3 """Local Linux capture. Collection never grants physical/audible acceptance. Only tool-owned argument arrays execute. Immutable package bytes are checked at both boundaries; output is fresh and disjoint. No original is executed or copied. X11/Pulse are the implemented external recorder sources; unsupported sources produce precise failed receipts rather than dummy fallback recordings. """ import argparse import hashlib import json import math import os from pathlib import Path import platform import re import shutil import signal import subprocess import tempfile import time from fidelity_checkpoint import _package from fidelity_receipts import (MAX_JSON_BYTES, _id, _write_json, canonical_bytes, contained_path, identify_file, import_receipt, read_json, separated_roots, utc_now, validate_receipt, validate_scenario_contract, required_events, _scenario_observation, read_receipt) PROJECT = Path(__file__).resolve().parents[2] MAX_SECONDS = 3600 MAX_LOG = 32 * 1024**2 MAX_MEDIA = 8 * 1024**3 def command_probe(argv, timeout=10): """Bound subprocess lifetime and returned metadata; no unbounded PIPE buffer.""" try: with tempfile.TemporaryFile() as log: process = subprocess.Popen(argv, stdout=log, stderr=log, start_new_session=True) try: code = process.wait(timeout=timeout) except subprocess.TimeoutExpired: os.killpg(process.pid, signal.SIGKILL) process.wait(timeout=5) code = None log.seek(0) data = log.read(MAX_JSON_BYTES + 1) error = 'metadata timeout' if code is None else None if len(data) > MAX_JSON_BYTES: error = 'metadata exceeds 4 MiB'; data = data[:MAX_JSON_BYTES] return {'argv': argv, 'exit_code': code, 'stdout': data.decode('utf8', errors='replace'), 'error': error} except OSError as error: return {'argv': argv, 'exit_code': None, 'stdout': '', 'error': str(error)} def _settings(settings): expected = {'display_method', 'display', 'audio_method', 'audio_source', 'input_method', 'size', 'offset'} if set(settings) != expected or any(not isinstance(v, str) or len(v) > 256 for v in settings.values()): raise ValueError('Settings require exactly the documented bounded string fields') if settings['input_method'] not in ('physical', 'automated', 'headless'): raise ValueError('Unknown input method') if not re.fullmatch(r'[1-9][0-9]{1,3}x[1-9][0-9]{1,3}', settings['size']): raise ValueError('Explicit bounded capture size required') if not re.fullmatch(r'[0-9]{1,5},[0-9]{1,5}', settings['offset']): raise ValueError('Explicit nonnegative X11 offset required') if settings['display'] and not re.fullmatch(r':[0-9]{1,5}(?:\.[0-9]{1,2})?', settings['display']): raise ValueError('Only local X11 displays are supported') if settings['audio_source'] and not re.fullmatch(r'[A-Za-z0-9_.-]{1,200}', settings['audio_source']): raise ValueError('Explicit local Pulse source name required') return dict(settings) def preflight(package, settings, tooling=False, probe=command_probe): settings = _settings(settings) blockers, observations = [], {} package = Path(package).resolve(strict=True) identity = None try: identity = _package(package, 'linux-x64', tooling) if not os.access(package / 'GamePort', os.X_OK): blockers.append('Identified Linux apphost is not executable') except (ValueError, OSError) as error: blockers.append('Package identity: ' + str(error)) if platform.system() != 'Linux': blockers.append('Native Linux host required') for name, argv in {'recorder': ['ffmpeg', '-version'], 'media_probe': ['ffprobe', '-version'], 'pulse_sources': ['pactl', 'list', 'short', 'sources'], 'pulse_sinks': ['pactl', 'list', 'short', 'sinks'], 'gpu': ['lspci', '-nn'], 'vulkan': ['vulkaninfo', '--summary']}.items(): observations[name] = probe(argv, timeout=10) executable = shutil.which(argv[0]) if executable: observations[name]['executable'] = {'path': str(Path(executable).resolve()), **identify_file(Path(executable).resolve())} for name in ('recorder', 'media_probe'): if observations[name]['exit_code'] != 0 or observations[name]['error']: blockers.append('Unavailable local ' + name) if settings['display_method'] != 'x11' or not settings['display']: blockers.append('No selected usable X11 display; Wayland/TTY capture requires a separately verified recorder') else: result = probe(['ffmpeg', '-nostdin', '-hide_banner', '-f', 'x11grab', '-video_size', settings['size'], '-i', settings['display'] + '+' + settings['offset'], '-frames:v', '1', '-f', 'null', '-'], timeout=10) observations['display_probe'] = result if result['exit_code'] != 0 or result['error']: blockers.append('Selected display capture probe failed') source = settings['audio_source'] if settings['audio_method'] != 'pulse' or not source or any(x in source.lower() for x in ('null', 'dummy')): blockers.append('No selected real Pulse audio source; null/dummy output cannot prove audible gameplay') elif observations['pulse_sources']['exit_code'] != 0 or source not in [ line.split()[1] for line in observations['pulse_sources']['stdout'].splitlines() if len(line.split()) >= 2]: blockers.append('Selected Pulse source is unavailable') else: result = probe(['ffmpeg', '-nostdin', '-hide_banner', '-f', 'pulse', '-i', source, '-t', '0.25', '-f', 'null', '-'], timeout=10) observations['audio_probe'] = result if result['exit_code'] != 0 or result['error']: blockers.append('Selected audio capture probe failed') return {'schema_version': 1, 'ready': not blockers, 'blockers': blockers, 'settings': settings, 'package': identity, 'package_root': str(package), 'host': {'system': platform.system(), 'release': platform.release(), 'machine': platform.machine(), 'session_type': os.environ.get('XDG_SESSION_TYPE'), 'display_env_present': bool(os.environ.get('DISPLAY')), 'wayland_env_present': bool(os.environ.get('WAYLAND_DISPLAY'))}, 'observations': observations, 'checked_utc': utc_now(), 'runtime_version_gaps': ['SDL runtime version and active GPU/driver/Vulkan instance require actual game logs'], 'acceptance': {'state': 'open', 'remaining': ['Preflight is not gameplay or audiovisual review']}} def _stop(process): """Signal only a child we own; escalate its own process group after grace.""" try: process.send_signal(signal.SIGINT) process.wait(timeout=5) except subprocess.TimeoutExpired: try: os.killpg(process.pid, signal.SIGKILL) except ProcessLookupError: pass process.wait(timeout=5) except ProcessLookupError: pass def run_capture(package, output, session_id, case_id, scope, settings, seconds=120, tooling=False, probe=command_probe, popen=subprocess.Popen): _id(session_id); _id(case_id) if len(session_id) > 88: raise ValueError('Session ID must leave room for receipt suffix') protocol = read_json(PROJECT / 'docs/evidence/scenarios.json') if case_id not in {c['id'] for c in protocol['cells']} or scope not in protocol['obligations']: raise ValueError('Unknown matrix case or obligation') if not isinstance(seconds, (int, float)) or not math.isfinite(seconds) or not 1 <= seconds <= MAX_SECONDS: raise ValueError('Capture duration must be 1..3600 seconds') package = Path(package).resolve(strict=True) output = Path(output).absolute() if any(p.is_symlink() for p in (output, *output.parents)): raise ValueError('Capture output cannot use symlink aliases') separated_roots(package, output); separated_roots(PROJECT.parent / 'Original', output) if output.exists(): raise ValueError('Capture output must be fresh; use a new session ID') report = preflight(package, settings, tooling, probe) output.mkdir(parents=True) _write_json(output / 'preflight.json', report) identity_dir = output / 'identity'; identity_dir.mkdir() if report['package']: for name in ('GamePort', 'fidelity-build.json', 'BUILD-INFO.txt'): shutil.copyfile(package / name, identity_dir / name) _write_json(identity_dir / 'resources.json', report['package']['resources']) shutil.copyfile(Path(__file__), identity_dir / 'collector.py') start, wall_start = time.monotonic(), utc_now() game = [str(package / 'GamePort'), '--assets', str(package / 'assets'), '--load-save', str(package / 'assets/NewGame.tsk'), '--walk', '--fidelity-output', str(output / 'observer'), '--fidelity-session', session_id, '--fidelity-case', case_id] recorder = ['ffmpeg', '-nostdin', '-hide_banner', '-n', '-f', 'x11grab', '-framerate', '30', '-video_size', settings['size'], '-i', settings['display'] + '+' + settings['offset'], '-f', 'pulse', '-i', settings['audio_source'], '-t', str(seconds), '-vf', 'freezedetect=n=-60dB:d=2', '-c:v', 'ffv1', '-c:a', 'pcm_s16le', '-fs', str(MAX_MEDIA), str(output / 'raw.mkv')] state = {'schema_version': 1, 'session_id': session_id, 'launch_id': session_id, 'clock_id': session_id + '-monotonic', 'case_id': case_id, 'scope': scope, 'package_root': str(package), 'tooling_only': tooling, 'input_method': settings['input_method'], 'settings': settings, 'invocation': {'argv': game, 'cwd': str(package)}, 'recorder_argv': recorder, 'clocks': {'monotonic_start': start, 'monotonic_end': start, 'wall_start': wall_start, 'wall_end': wall_start, 'clock_id': session_id + '-monotonic'}, 'status': 'failed' if not report['ready'] else 'incomplete', 'missing': list(report['blockers']), 'processes': {}} _write_json(output / 'started.json', state) processes = [] try: if report['ready']: env = dict(os.environ, DISPLAY=settings['display'], SDL_VIDEODRIVER='x11') if not tooling and (env.get('SDL_AUDIODRIVER') in ('dummy', 'disk') or env.get('SDL_VIDEODRIVER') == 'dummy'): raise ValueError('Dummy SDL devices cannot be used for native capture') # Explicit source matches the selected real Pulse system, not a dummy inherited backend. env['SDL_AUDIODRIVER'] = 'pulseaudio' with (output / 'recorder.log').open('xb') as recording_log, (output / 'game.log').open('xb') as game_log: recording = popen(recorder, cwd=output, env=env, stdout=recording_log, stderr=subprocess.STDOUT, start_new_session=True) processes.append(recording) child = popen(game, cwd=package, env=env, stdout=game_log, stderr=subprocess.STDOUT, start_new_session=True) processes.append(child) # One deadline covers both children. Logs/media are checked every wait slice. deadline = time.monotonic() + seconds + 3 for name, child_process in (('game', child), ('recorder', recording)): while True: if any(p.stat().st_size > MAX_LOG for p in (output / 'game.log', output / 'recorder.log')): raise ValueError('Capture log exceeds 32 MiB bound') remaining = deadline - time.monotonic() if remaining <= 0: raise subprocess.TimeoutExpired(game, seconds) try: code = child_process.wait(timeout=min(1, remaining)) state['processes'][name] = code break except subprocess.TimeoutExpired: # Doubles and real processes both expose poll; timeout at the # total deadline remains an abort, never a captured outcome. if child_process.poll() is not None: raise state['status'] = 'captured' if all(c == 0 for c in state['processes'].values()) else 'failed' if state['status'] == 'failed': state['missing'].append('Game or recorder exited unsuccessfully') except (KeyboardInterrupt, subprocess.TimeoutExpired): state['status'] = 'aborted'; state['missing'].append('Capture interrupted or duration deadline exceeded') except (OSError, ValueError) as error: state['status'] = 'failed'; state['missing'].append(str(error)) finally: for process in processes: if process.poll() is None or state['status'] == 'aborted': _stop(process) state['clocks'].update(monotonic_end=time.monotonic(), wall_end=utc_now()) _write_json(output / 'session.json', state) return state def collect(run, probe=command_probe, annotations=None): run = Path(run).resolve(strict=True) state, pre = read_json(run / 'session.json'), read_json(run / 'preflight.json') if (run / 'receipt.json').exists(): raise ValueError('Receipt already finalized; preserve history') missing = list(state['missing']) if pre['package']: try: current = _package(Path(state['package_root']), 'linux-x64', state['tooling_only']) if current != pre['package']: raise ValueError('Package changed since launch') except (ValueError, OSError) as error: missing.append('Post-capture package identity failed: ' + str(error)) media = run / 'raw.mkv' duration = None if media.exists() and media.stat().st_size > MAX_MEDIA: missing.append('Raw media exceeds 8 GiB capture bound; preserved locally but excluded from import') elif media.exists() and media.stat().st_size: media_probe = probe(['ffprobe', '-v', 'error', '-show_streams', '-show_format', '-of', 'json', str(media)], timeout=20) _write_json(run / 'media-probe.json', media_probe) try: payload = json.loads(media_probe['stdout']) duration = float(payload['format']['duration']) roles = {s.get('codec_type') for s in payload['streams']} if media_probe['exit_code'] != 0 or media_probe['error'] or not math.isfinite(duration) or duration <= 0: raise ValueError('Invalid media duration/probe') if not {'video', 'audio'}.issubset(roles): raise ValueError('Missing video/audio streams') except (ValueError, KeyError, TypeError) as error: missing.append('Media inspection failed: ' + str(error)); duration = None else: missing.append('Raw video/audio recording missing or empty') log = run / 'recorder.log' if log.exists(): if log.stat().st_size > MAX_LOG: missing.append('Recorder log exceeds bounded inspection') elif 'freeze_start' in log.read_text(errors='replace'): missing.append('Possible frozen media indicator requires actual visual inspection') if not (run / 'observer').exists(): missing.append('Passive observer/input events unavailable') identity = {} identity_dir = run / 'identity' if pre['package']: for key, name in (('executable', 'GamePort'), ('package', 'fidelity-build.json'), ('source', 'BUILD-INFO.txt')): identity[key] = {'path': 'identity/' + name, **identify_file(identity_dir / name)} identity['resources'] = {'path': 'identity/resources.json', **identify_file(identity_dir / 'resources.json')} identity['launcher'] = {'path': 'identity/collector.py', **identify_file(identity_dir / 'collector.py')} note = read_json(annotations) if annotations else {} # Explicit local annotations bind actual files; no imported commands execute. extra_roles = note.get('artifact_roles', {}) if not isinstance(extra_roles, dict) or any(role != 'prerequisite' for role in extra_roles.values()): raise ValueError('Only explicit prerequisite artifact roles can supplement capture roles') for name in extra_roles: identify_file(contained_path(run, name)) for key, name in note.get('identity_files', {}).items(): if key not in ('copy_pre', 'retained_copy', 'copy_post'): raise ValueError('Unsupported annotated copy identity') identity[key] = {'path': name, **identify_file(contained_path(run, name))} artifacts = [] count = 0 for path in run.rglob('*'): count += 1 if count > 10000: raise ValueError('Capture exceeds 10000-entry bound') if path.is_symlink(): raise ValueError('Symlink in capture output') if not path.is_file() or path.is_relative_to(identity_dir): continue bound = MAX_MEDIA if path.suffix == '.mkv' else MAX_LOG if path.stat().st_size > bound: missing.append('Artifact exceeds import bound: ' + path.relative_to(run).as_posix()) continue name = path.relative_to(run).as_posix() role = 'video' if name == 'raw.mkv' else 'input_events' if name.startswith('observer/') else 'diagnostic' role = extra_roles.get(name, role) item = {'path': name, 'role': role, **identify_file(path)} if state['tooling_only']: item['synthetic'] = True if name == 'raw.mkv' and duration is not None: item['duration_seconds'] = duration if role == 'prerequisite' and duration is not None: if item['sha256'] == identify_file(media)['sha256']: item['duration_seconds'] = duration else: inspection = probe(['ffprobe', '-v', 'error', '-show_format', '-of', 'json', str(path)], timeout=20) try: seconds = float(json.loads(inspection['stdout'])['format']['duration']) if inspection['exit_code'] != 0 or inspection['error'] or not math.isfinite(seconds) or seconds <= 0: raise ValueError('Invalid prerequisite media duration') item['duration_seconds'] = seconds except (ValueError, KeyError, TypeError) as error: raise ValueError('Cannot identify prerequisite recording duration') from error artifacts.append(item) artifacts.sort(key=lambda item: item['path']) # The same hashed MKV contains both streams; audio role uses a distinct # byte-identical local alias to satisfy the shared validator's unique paths. if duration is not None: shutil.copyfile(media, run / 'raw-audio.mkv') artifacts.append({'path': 'raw-audio.mkv', 'role': 'audio', 'duration_seconds': duration, **identify_file(run / 'raw-audio.mkv'), **({'synthetic': True} if state['tooling_only'] else {})}) events = note.get('events', []) kind = 'synthetic' if state['tooling_only'] else 'native_port' if state['input_method'] == 'physical' else 'port_fixture' status = state['status'] if status == 'captured' and missing: status = 'failed' receipt = {'schema_version': 1, 'receipt_id': state['session_id'] + '-linux', 'session_id': state['session_id'], 'case_id': state['case_id'], 'scope': state['scope'], 'obligation_id': state['scope'], 'evidence_kind': kind, 'historical': False, 'status': status, 'platform': {'os': 'linux', 'execution': 'native' if kind == 'native_port' else kind}, 'invocation': state['invocation'], 'clocks': state['clocks'], 'identity': identity, 'artifacts': artifacts, 'derivatives': [], 'events': events, 'limitations': ['Collection does not prove visible moving gameplay, physical input or audible output', 'Existing NewGame.tsk entry is not a reconstructed main menu', 'Observer and recording overhead remains part of this identified run'], 'missing_evidence': missing, 'review': {'visible': False, 'audible': False, 'ordinary_input': False, 'human_reviewed': False}, 'capture_methods': state['settings'], 'clock_id': state['clock_id'], 'launch_id': state['launch_id'], 'continuity': note.get('continuity', {}), 'acceptance': {'state': 'open', 'remaining': [ 'Actual moving-content/crop/clock/physical-input/audibility review', 'Observed scenario markers and lifetime/route continuity validation', 'Original-DxWnd and native Windows comparison']}} validate_receipt(receipt, run) _write_json(run / 'receipt.json', receipt) return receipt def matrix(protocol, records=(), previous=None, dependency=None): """Forty Linux obligations with validated append-only attempt history. Previous attempts are re-read and hash-checked, never trusted as acceptance. Distinct failed/incomplete retries require distinct process/session IDs. A shared environment failure is a dependency, not forty fabricated runs. """ validate_scenario_contract(protocol) cells = {c['id']: c for c in protocol['cells']} slots = {(c['id'], o): [] for c in protocol['cells'] for o in c['obligations']} history = [] if previous: if previous.get('schema_version') != 1 or previous.get('side') != 'port-linux-native': raise ValueError('Unrecognized previous Linux matrix') for cell in previous['cells']: for obligation in cell['obligations']: for attempt in obligation['attempts']: path = Path(attempt['receipt_path']) if identify_file(path)['sha256'] != attempt['receipt_sha256']: raise ValueError('Historical receipt bytes changed') history.append((read_receipt(path), path.parent)) seen, sessions = {}, {} for receipt, root in [*history, *records]: root = Path(root).resolve(strict=True) validated = validate_receipt(receipt, root) key = (receipt['case_id'], receipt.get('obligation_id', receipt['scope'])) if key not in slots: raise ValueError('Unknown Linux matrix slot') if receipt['platform']['os'] != 'linux': raise ValueError('Linux matrix requires Linux observations') digest = hashlib.sha256(canonical_bytes(receipt)).hexdigest() record_id, session_id = receipt['receipt_id'], receipt['session_id'] if record_id in seen: if seen[record_id] != digest: raise ValueError('Conflicting immutable receipt ID') continue if session_id in sessions: raise ValueError('A new matrix attempt must use a new launch/session ID') sessions[session_id] = record_id; seen[record_id] = digest reasons = list(validated['missing_evidence']) try: _scenario_observation(protocol, cells[key[0]], receipt) except (ValueError, KeyError, StopIteration) as error: reasons.append('Scenario continuity: ' + str(error)) if receipt['evidence_kind'] != 'native_port': reasons.append('Linux native gameplay requires actual native evidence') path = root / 'receipt.json' if read_receipt(path) != receipt: raise ValueError('Matrix input differs from saved receipt') slots[key].append({'receipt_id': record_id, 'session_id': session_id, 'receipt_path': str(path), 'receipt_sha256': identify_file(path)['sha256'], 'status': receipt['status'], 'evidence_kind': receipt['evidence_kind'], 'accepted': validated['accepted'] and not reasons, 'remaining': list(dict.fromkeys(reasons))}) result_cells, accepted = [], 0 for cell in protocol['cells']: result = {k: cell[k] for k in ('id', 'lifetime', 'dialogue', 'input')} result['procedures'] = { 'lifetime': protocol['lifetime_procedures'][cell['lifetime']], 'dialogue': protocol['dialogue_procedures'][cell['dialogue']], 'input': protocol['input_procedures'][cell['input']]} result['obligations'] = [] for obligation_id in cell['obligations']: attempts = slots[(cell['id'], obligation_id)] done = any(a['accepted'] for a in attempts) accepted += int(done) dependencies = [] if done else list((dependency or {}).get('reasons', [])) if not done: dependencies += ['Actual Linux ' + cell['id'] + '/' + obligation_id + ' recording and physical/audible review'] dependencies += [reason for a in attempts for reason in a['remaining']] result['obligations'].append({'id': obligation_id, 'state': 'accepted' if done else 'open', 'attempts': attempts, 'dependencies': list(dict.fromkeys(dependencies)), 'dependency_receipt_id': (dependency or {}).get('receipt_id'), 'required_events': required_events(protocol, cell, obligation_id), 'route': protocol['obligations'][obligation_id].get('route'), 'procedure': protocol['obligations'][obligation_id]}) result_cells.append(result) return {'schema_version': 1, 'side': 'port-linux-native', 'required': 40, 'accepted': accepted, 'complete': accepted == 40, 'cells': result_cells, 'environment_dependency': dependency, 'acceptance': {'state': 'open', 'remaining': ['Final combined original/native acceptance audit']}} def main(): parser = argparse.ArgumentParser(description=__doc__) sub = parser.add_subparsers(dest='action', required=True) for action in ('preflight', 'run'): command = sub.add_parser(action) command.add_argument('--package', type=Path, required=True) command.add_argument('--settings', type=Path, required=True) if action == 'run': command.add_argument('--output', type=Path, required=True) command.add_argument('--session-id', required=True) command.add_argument('--case-id', required=True) command.add_argument('--scope', required=True) command.add_argument('--seconds', type=float, default=120) command = sub.add_parser('collect') command.add_argument('--run', type=Path, required=True) command.add_argument('--annotations', type=Path) command.add_argument('--import-to', type=Path) command = sub.add_parser('matrix') command.add_argument('--receipt', type=Path, action='append', default=[]) command.add_argument('--previous', type=Path) command.add_argument('--dependency-run', type=Path) command.add_argument('--output', type=Path, required=True) args = parser.parse_args() if args.action == 'preflight': result = preflight(args.package, read_json(args.settings)) elif args.action == 'run': result = run_capture(args.package, args.output, args.session_id, args.case_id, args.scope, read_json(args.settings), args.seconds) elif args.action == 'collect': result = collect(args.run, annotations=args.annotations) if args.import_to: import_receipt(args.run / 'receipt.json', args.run, args.import_to) else: dependency = None if args.dependency_run: path = args.dependency_run / 'receipt.json' receipt = read_receipt(path) validate_receipt(receipt, path.parent) pre = read_json(args.dependency_run / 'preflight.json') if pre['ready'] or not pre['blockers'] or receipt['status'] != 'failed': raise ValueError('Environment dependency requires an actual failed-preflight receipt') dependency = {'receipt_id': receipt['receipt_id'], 'receipt_path': str(path.resolve()), 'receipt_sha256': identify_file(path)['sha256'], 'reasons': pre['blockers']} result = matrix(read_json(PROJECT / 'docs/evidence/scenarios.json'), [(read_receipt(p), p.parent) for p in args.receipt], read_json(args.previous) if args.previous else None, dependency) separated_roots(PROJECT.parent / 'Original', args.output) if any(p.is_symlink() for p in (args.output.absolute(), *args.output.absolute().parents)): raise ValueError('Matrix output cannot use symlink aliases') args.output.parent.mkdir(parents=True, exist_ok=True) _write_json(args.output, result) print(canonical_bytes(result).decode(), end='') return 0 if args.action == 'matrix' or result.get('ready', result.get('status') == 'captured') else 1 if __name__ == '__main__': raise SystemExit(main())