From 16f5e126bedef919af1377cb0da7146255df0c2b Mon Sep 17 00:00:00 2001 From: Cristian Cerroni Date: Fri, 13 Nov 2026 11:56:08 -0500 Subject: [PATCH] feat(01-06): collect bounded Linux capture and honest failed preflight --- docs/evidence/linux-session.md | 85 ++++++++ scripts/collect-fidelity-linux.sh | 5 + tools/recon/fidelity_capture.py | 349 ++++++++++++++++++++++++++++++ 3 files changed, 439 insertions(+) create mode 100644 docs/evidence/linux-session.md create mode 100644 scripts/collect-fidelity-linux.sh create mode 100644 tools/recon/fidelity_capture.py diff --git a/docs/evidence/linux-session.md b/docs/evidence/linux-session.md new file mode 100644 index 0000000..442808c --- /dev/null +++ b/docs/evidence/linux-session.md @@ -0,0 +1,85 @@ +# Local Linux fidelity capture + +This joins the single final combined session described in +[windows-session.md](windows-session.md). Prepare locally; no early hands-on +session is requested. Every original/native acceptance obligation remains open +until actual evidence and human review. No gameplay/movement reset is added. + +Use the existing sealed Linux package, not a rebuilt or relabeled package. +The 01-05 package is `artifacts/fidelity/01-05-packages/linux-x64`: +source `446930d2a30d6d616c60ac5e59e4169a840bea09`, dirty yes, publish diff +`90cef95669caece53fe2d2c4736cf2ac05ed27f5d25ca03ab572589686bcb73d`. +Its file-list hash is `124cf271e4952f3822eec5c24358447fcffc9e9e1803aded8d96d4d4472dc5a3`. +The collector checks all sealed bytes before launch and collection. Keep output +outside the package and originals, in a fresh session directory. + +Select the actual local X11 display and capture rectangle, real Pulse monitor +source and physical input method. Save a local JSON settings object with these +exact fields (values below are examples, not observed devices): + +```json +{"display_method":"x11","display":":0","audio_method":"pulse", + "audio_source":"actual-device.monitor","input_method":"physical", + "size":"1280x720","offset":"0,0"} +``` + +Inspect `pactl list short sources` and `pactl list short sinks` locally. Null/dummy +devices do not qualify. This collector implements X11/Pulse capture with installed +FFmpeg/ffprobe; it records unsupported Wayland/TTY/dependency conditions as failed +preflight. Do not install or select a guessed alternative automatically. Use a +separately identified existing recorder for unsupported display sources and retain +its actual settings, tool identity, raw recording and timing provenance. + +```sh +bash scripts/collect-fidelity-linux.sh preflight --package artifacts/fidelity/01-05-packages/linux-x64 --settings /local/linux-settings.json +bash scripts/collect-fidelity-linux.sh run --package artifacts/fidelity/01-05-packages/linux-x64 --settings /local/linux-settings.json --output artifacts/fidelity/linux/unique-launch --session-id unique-launch --case-id fresh-natural-ordinary --scope dialogue-return --seconds 120 +bash scripts/collect-fidelity-linux.sh collect --run artifacts/fidelity/linux/unique-launch --import-to artifacts/fidelity/linux-receipts +``` + +Nonzero run/collect exits preserve failure/abort output; inspect it, and collect +the failed run too. Recorder starts before the normal `--load-save NewGame.tsk +--walk` process and passive observer. This is the existing story entry, not an +implemented main menu. Close the game normally before the selected duration. +Both children have one bounded deadline; interruption ends only owned children. +Logs and metadata have explicit bounds; raw recording is capped at 8 GiB. Retain +the entire lossless FFV1/PCM MKV and tail; a detected frozen interval is an open +inspection flag, not a claim of failure or parity derived from a numeric tolerance. + +Collection probes actual streams/duration and hashes logs/media/observer and +package/source/resource identities. The duplicate MKV audio alias preserves exact +bytes for the shared receipt's distinct audio role. No audio normalization, +retiming, crop repair or preview is implicit. If a browser needs a remux/preview, +retain raw media and explicit derivation command/version/hash/time mapping under +the existing shared derivative contract. The local viewer exporter consumes the +imported receipts; actual playback/seeking/audio/crop remain human review gates. + +Record manual event annotations as `{"events":[...]}` using the exact fields in +`scenarios.json`: hashed raw artifact name, media and monotonic elapsed seconds, +method and uncertainty. Supply `collect --annotations /local/annotations.json`. +Port simulation ticks remain separate from raw clocks. Observer gate results +do not prove a physical key was pressed. Automated injection is `port_fixture`; +test doubles are permanently synthetic. No collector output grants acceptance. + +## Actual 2026-11-13 preflight + +The scoped host probe, outside sandbox device restrictions, found a TTY session, +no `DISPLAY` or `WAYLAND_DISPLAY` and no X11 socket. Existing FFmpeg/ffprobe are +available. Pulse exposes only `auto_null` and `auto_null.monitor` (suspended). +No Xvfb or OBS command resolved. A synthetic display or null audio would not +establish the requested normal visible/audible gameplay, so no game/recorder +was launched and no substitute route/media was fabricated. + +The exact failed focused receipt is `linux-01-06-focused-preflight-linux`, at +`artifacts/fidelity/linux/01-06-focused-preflight/receipt.json`, imported into +`artifacts/fidelity/linux-receipts/linux-01-06-focused-preflight-linux/`. +`preflight.json` preserves observed OS, tool versions/hashes, Pulse devices and +available GPU/Vulkan diagnostics; missing SDL/active-instance runtime versions +remain explicit. The selected package/resource seal matches the hash above. +Both the failed result and its import validate structurally, with acceptance open. +Before collection, all 539 original files verified unchanged. + +Required next physical session: provide an actual display/game capture source +and real audible device/monitor source, verify moving unobstructed content and +audio, then record physical normal controls and full tails. Inspect capture cost, +crop/aspect and actual browser playback/seeking separately. Preserve this failed +preflight as history; new attempts use new session IDs and fresh output roots. diff --git a/scripts/collect-fidelity-linux.sh b/scripts/collect-fidelity-linux.sh new file mode 100644 index 0000000..c577efa --- /dev/null +++ b/scripts/collect-fidelity-linux.sh @@ -0,0 +1,5 @@ +#!/usr/bin/env bash +# No build, download, device fallback or acceptance promotion. +set -euo pipefail +task_root="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd)" +exec python3 "$task_root/tools/recon/fidelity_capture.py" "$@" diff --git a/tools/recon/fidelity_capture.py b/tools/recon/fidelity_capture.py new file mode 100644 index 0000000..7ce8ba3 --- /dev/null +++ b/tools/recon/fidelity_capture.py @@ -0,0 +1,349 @@ +#!/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())