feat(01-06): collect bounded Linux capture and honest failed preflight

This commit is contained in:
UnixNight committed 2026-11-13 11:56:08 -05:00
1 parent 9c59f60b50
commit 16f5e126be
3 files changed
+439

No files matched your search

+349
View File
@@ -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())