#!/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 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) 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}, '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: 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')} artifacts = [] for path in sorted(run.rglob('*')): if path.is_symlink(): raise ValueError('Symlink in capture output') if not path.is_file() or path.is_relative_to(identity_dir): continue name = path.relative_to(run).as_posix() role = 'video' if name == 'raw.mkv' else 'input_events' if name.startswith('observer/') else 'diagnostic' 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 artifacts.append(item) # 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 = [] if annotations: note = read_json(annotations) events = note.get('events', []) # Annotations carry observed markers, never review/acceptance promotion. 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'], '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'], '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 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) 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) else: result = collect(args.run, annotations=args.annotations) if args.import_to: import_receipt(args.run / 'receipt.json', args.run, args.import_to) print(canonical_bytes(result).decode(), end='') return 0 if result.get('ready', result.get('status') == 'captured') else 1 if __name__ == '__main__': raise SystemExit(main())