Files
Neutron/tools/recon/fidelity_receipts.py
T

753 lines
38 KiB
Python

"""Version 1 local fidelity records; hashes establish identity, never gameplay parity.
Receipt state machine: incomplete -> failed or captured -> reviewed. Import is
append-only: an ID can only be reused for exactly the same input bytes. A review
or successful process exit alone cannot accept evidence. Missing/failed/aborted/
skipped observations remain open. Synthetic records belong in a test namespace.
All artifact/identity references are read-only POSIX paths relative to the bundle;
commands are recorded as arrays and are NEVER executed by this module.
Session state is separate: exclusive reservation -> incomplete temporary sibling
-> verified staged tree -> postflight snapshot. A retained run reuses that exact
session/copy lifetime; a fresh run requires a new allocation. Staged is not a
completed gameplay receipt. A killed writer leaves incomplete.json and its lock
for diagnosis; there is deliberately no automatic stale-lock stealing.
Public APIs return JSON-compatible dictionaries and raise ValueError on invalid
input. File-system failures propagate; failed publication preserves diagnostics.
Local cooperative writers are serialized; concurrent hostile filesystem mutation
is outside this offline workflow (revalidate after collection/before review).
"""
import hashlib
import itertools
import json
import math
import ntpath
import os
from pathlib import Path, PurePosixPath
import re
import shutil
import subprocess
import tempfile
import uuid
from datetime import datetime, timezone
SCHEMA_VERSION = 1
MAX_JSON_BYTES = 4 * 1024 * 1024
MAX_FILES = 100000
KINDS = {'static', 'inferred', 'component', 'managed', 'port_fixture',
'native_port', 'original_dxwnd', 'wine', 'cross_publish', 'synthetic'}
STATUSES = {'incomplete', 'failed', 'captured', 'reviewed', 'skipped', 'aborted', 'missing'}
EXECUTION = {'native_port': 'native', 'original_dxwnd': 'dxwnd'}
RECEIPT_TRANSITIONS = {'incomplete': ['failed', 'captured', 'aborted', 'skipped'],
'captured': ['reviewed'], 'reviewed': [], 'failed': [],
'skipped': [], 'aborted': [], 'missing': []}
def utc_now():
return datetime.now(timezone.utc).isoformat()
def canonical_bytes(value):
return (json.dumps(value, sort_keys=True, indent=2, allow_nan=False) + '\n').encode()
def read_json(path):
try:
with Path(path).open('rb') as stream:
data = stream.read(MAX_JSON_BYTES + 1)
if len(data) > MAX_JSON_BYTES:
raise ValueError('JSON exceeds 4 MiB limit')
def unique(pairs):
result = {}
for key, value in pairs:
if key in result:
raise ValueError('Duplicate JSON key: ' + key)
result[key] = value
return result
value = json.loads(data, object_pairs_hook=unique,
parse_constant=lambda s: (_ for _ in ()).throw(ValueError('Nonfinite JSON: ' + s)))
if not isinstance(value, dict):
raise ValueError('JSON root must be an object')
return value
except (OSError, UnicodeError, RecursionError, json.JSONDecodeError) as error:
raise ValueError('Cannot read bounded JSON: ' + str(path)) from error
def identify_file(path):
path = Path(path)
if path.is_symlink() or not path.is_file():
raise ValueError('Expected a regular non-symlink file: ' + str(path))
digest = hashlib.sha256()
size = 0
header = b''
with path.open('rb') as stream:
while block := stream.read(1024 * 1024):
if not header:
header = block[:16]
size += len(block)
digest.update(block)
return {'size': size, 'sha256': digest.hexdigest(), 'header': header.hex()}
def relative_name(value):
if not isinstance(value, str) or not value or len(value) > 4096:
raise ValueError('Reference must be a bounded relative POSIX path')
parts = value.split('/')
if ('\\' in value or ':' in value or value.startswith('/') or
any(ord(c) < 32 or c in '<>"|?*' for c in value) or
any(p in ('', '.', '..') or p.endswith((' ', '.')) for p in parts)):
raise ValueError('Unsafe relative reference: ' + value)
for part in parts:
if part.split('.')[0].upper() in {'CON', 'PRN', 'AUX', 'NUL',
*('COM' + str(i) for i in range(1, 10)),
*('LPT' + str(i) for i in range(1, 10))}:
raise ValueError('Windows device alias in path')
return PurePosixPath(value)
def contained_path(root, value):
name = relative_name(value)
root = Path(root).resolve(strict=True)
target = root.joinpath(*name.parts)
cursor = root
for part in name.parts:
cursor = cursor / part
if cursor.is_symlink():
raise ValueError('Symlink in reference: ' + value)
if not target.resolve().is_relative_to(root):
raise ValueError('Reference escapes root')
return target
def separated_roots(source, output):
source, output = Path(source).resolve(), Path(output).resolve()
# Windows normalization also runs on Linux so transferred roots cannot gain
# a different preservation boundary on a case-insensitive receiving host.
a, b = [ntpath.normcase(str(p)).rstrip('\\/') for p in (source, output)]
if a == b or a.startswith(b + '\\') or b.startswith(a + '\\'):
raise ValueError('Source/output roots overlap or alias')
return source, output
def identify_tree(root):
root = Path(root).resolve(strict=True)
if not root.is_dir():
raise ValueError('Tree root must be a directory')
files, aliases, json_size = [], set(), 0
for directory, dirs, names in os.walk(root, followlinks=False):
for name in sorted(dirs + names):
path = Path(directory) / name
relative = path.relative_to(root).as_posix()
relative_name(relative)
key = relative.casefold()
if key in aliases:
raise ValueError('Case-colliding tree identity: ' + relative)
aliases.add(key)
if len(aliases) > MAX_FILES:
raise ValueError('Tree exceeds entry bound')
if path.is_symlink():
raise ValueError('Symlink tree member: ' + relative)
if path.is_file():
item = {'path': relative, **identify_file(path)}
json_size += len(canonical_bytes(item))
if json_size > MAX_JSON_BYTES:
raise ValueError('Tree identity exceeds JSON size bound')
files.append(item)
elif not path.is_dir():
raise ValueError('Non-regular tree member: ' + relative)
files.sort(key=lambda item: item['path'])
if not files:
raise ValueError('Empty inventories cannot establish identity')
return {'schema_version': 1, 'root': str(root), 'files': files,
'tree_sha256': hashlib.sha256(canonical_bytes(files)).hexdigest()}
def verify_inventory(root, manifest):
"""Use inventory.py's exact files-list comparison, including size/header/order.
Streaming enumeration emits its existing record format without re-generating
or writing the authoritative manifest; root labels are deliberately separate.
"""
baseline = read_json(manifest).get('files')
if not isinstance(baseline, list) or not baseline:
raise ValueError('Recorded inventory is empty or missing')
actual = identify_tree(root)
if actual['files'] != baseline:
raise ValueError('Original inventory differs from recorded baseline')
return actual
def _id(value):
if not isinstance(value, str) or not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9_.-]{0,95}', value):
raise ValueError('Invalid stable ID')
relative_name(value)
return value
def _write_json(path, value):
data = canonical_bytes(value)
if len(data) > MAX_JSON_BYTES:
raise ValueError('Output JSON exceeds bound')
with Path(path).open('xb') as stream:
stream.write(data)
stream.flush()
os.fsync(stream.fileno())
def _reserve(output, record_id):
# The repository's authoritative installation remains protected even when
# an imported bundle comes from an unrelated directory.
original = Path(__file__).resolve().parents[3] / 'Original'
separated_roots(original, output)
output.mkdir(parents=True, exist_ok=True)
lock = output / ('.' + _id(record_id).casefold() + '.lock')
try:
lock.mkdir()
except FileExistsError as error:
raise ValueError('Session/import ID reserved; inspect existing diagnostics') from error
return lock
def _temporary(output, record_id, operation):
temporary = output / ('.' + record_id + '.incomplete-' + uuid.uuid4().hex)
temporary.mkdir()
_write_json(temporary / 'incomplete.json', {'schema_version': 1,
'status': 'incomplete', 'id': record_id, 'operation': operation,
'started_utc': utc_now(), 'diagnostic': 'Publication not completed; do not use as acceptance'})
return temporary
def stage_original(source, manifest, output, session_id):
source, output = separated_roots(source, output)
_id(session_id)
before = verify_inventory(source, manifest)
# No writes before all input roots/inventory checks succeed.
lock = _reserve(output, session_id)
temporary = _temporary(output, session_id, 'stage')
final = output / session_id
if final.exists():
raise ValueError('Session already exists')
try:
game = temporary / 'game'
game.mkdir()
for item in before['files']:
src = contained_path(source, item['path'])
dst = game / item['path']
dst.parent.mkdir(parents=True, exist_ok=True)
shutil.copyfile(src, dst)
pristine = verify_inventory(game, manifest)
after = verify_inventory(source, manifest)
record = {'schema_version': 1, 'session_id': session_id, 'status': 'staged',
'source_root': str(source), 'copy_root': str(final / 'game'),
'original_manifest': identify_file(manifest), 'source_pre': before,
'source_post_stage': after,
'copy_pre': dict(pristine, root=str(final / 'game')),
'staged_utc': utc_now(), 'acceptance': {'state': 'open',
'remaining': ['Staging is not gameplay execution']}}
_write_json(temporary / 'session.json', record)
os.rename(temporary, final)
(final / 'incomplete.json').unlink()
return record
except BaseException:
# Even KeyboardInterrupt leaves the prewritten diagnostic and lock.
raise
def postflight_session(session, source, manifest):
session, source = Path(session).resolve(strict=True), Path(source).resolve(strict=True)
separated_roots(source, session)
staged = read_json(session / 'session.json')
if staged['source_root'] != str(source):
raise ValueError('Source root does not match staged session')
source_post = verify_inventory(source, manifest)
copy_post = identify_tree(session / 'game')
before = {f['path']: f for f in staged['copy_pre']['files']}
after = {f['path']: f for f in copy_post['files']}
return {'schema_version': 1, 'session_id': staged['session_id'],
'source_post': source_post, 'copy_post': copy_post,
'copy_changes': {'added': sorted(after.keys() - before.keys()),
'missing': sorted(before.keys() - after.keys()),
'changed': sorted(k for k in before.keys() & after.keys()
if before[k] != after[k])}}
def _checked_artifact(item, root):
if not isinstance(item, dict):
raise ValueError('Artifact must be an object')
path = contained_path(root, item.get('path'))
actual = identify_file(path)
if item.get('sha256') != actual['sha256'] or item.get('size') != actual['size']:
raise ValueError('Artifact identity mismatch: ' + item['path'])
return path
def _finite(value):
if not isinstance(value, (int, float)) or isinstance(value, bool):
return False
try:
return math.isfinite(value)
except OverflowError:
return False
def validate_receipt(receipt, root):
"""Validate structure/actual files; return accepted plus explicit open reasons.
No execution, parser success, platform label or process exit implies review.
Later acceptance owners must additionally validate full matrix/applicability.
"""
if not isinstance(receipt, dict) or receipt.get('schema_version') != 1:
raise ValueError('Unsupported receipt schema_version')
for key in ('receipt_id', 'session_id', 'case_id'):
_id(receipt.get(key))
kind, status = receipt.get('evidence_kind'), receipt.get('status')
if kind not in KINDS or status not in STATUSES:
raise ValueError('Unknown evidence_kind/status')
platform = receipt.get('platform')
if not isinstance(platform, dict) or not platform.get('os'):
raise ValueError('Platform classification required')
expected = EXECUTION.get(kind, kind)
if platform.get('execution') != expected:
raise ValueError('Evidence kind/platform execution mismatch')
if kind == 'native_port' and platform['os'] not in ('linux', 'windows'):
raise ValueError('Native port requires Linux or Windows identity')
if kind == 'original_dxwnd' and platform['os'] != 'windows':
raise ValueError('DxWnd original requires Windows classification')
if not isinstance(receipt.get('historical'), bool):
raise ValueError('Explicit historical classification required')
for key in ('artifacts', 'derivatives', 'events', 'limitations', 'missing_evidence'):
if not isinstance(receipt.get(key), list) or len(receipt[key]) > 10000:
raise ValueError('Missing or unbounded list: ' + key)
for key in ('limitations', 'missing_evidence'):
if not all(isinstance(item, str) for item in receipt[key]):
raise ValueError('Text list required: ' + key)
invocation = receipt.get('invocation')
if (not isinstance(invocation, dict) or not isinstance(invocation.get('argv'), list)
or not all(isinstance(a, str) for a in invocation['argv'])
or not isinstance(invocation.get('cwd'), str)):
raise ValueError('Invocation requires inert argv array and recorded cwd')
clocks = receipt.get('clocks', {})
if not isinstance(clocks, dict):
raise ValueError('Clocks must be an object')
start, end = clocks.get('monotonic_start'), clocks.get('monotonic_end')
if not _finite(start) or not _finite(end) or start < 0 or end < start:
raise ValueError('Invalid/reset monotonic clocks')
for key in ('wall_start', 'wall_end'):
try:
dt = datetime.fromisoformat(clocks[key].replace('Z', '+00:00'))
if dt.tzinfo is None:
raise ValueError('Timezone required')
except (KeyError, TypeError, AttributeError, ValueError) as error:
raise ValueError('Timezone-aware wall clocks required') from error
artifacts, aliases = {}, set()
for item in receipt['artifacts']:
_checked_artifact(item, root)
key = item['path'].casefold()
if key in aliases:
raise ValueError('Duplicate/case-colliding artifact')
aliases.add(key)
artifacts[item['path']] = item
for derivative in receipt['derivatives']:
if (not isinstance(derivative, dict) or derivative.get('path') not in artifacts or derivative.get('source') not in artifacts
or not derivative.get('tool') or not isinstance(derivative.get('argv'), list)):
raise ValueError('Derivative requires hashed source/output and tool/argv provenance')
for event in receipt['events']:
if not isinstance(event, dict):
raise ValueError('Event must be an object')
artifact = artifacts.get(event.get('artifact'))
if not artifact or not event.get('name') or not event.get('method'):
raise ValueError('Observed event requires media reference/name/method')
for field in ('media_seconds', 'elapsed_seconds', 'uncertainty_seconds'):
if not _finite(event.get(field)) or event[field] < 0:
raise ValueError('Event requires finite nonnegative timing/uncertainty')
duration = artifact.get('duration_seconds')
if not _finite(duration) or event['media_seconds'] > duration:
raise ValueError('Event exceeds identified media duration')
if event['elapsed_seconds'] > end - start:
raise ValueError('Event exceeds recorded monotonic interval')
if 'simulation_tick' in event and (kind == 'original_dxwnd' or
not isinstance(event['simulation_tick'], int) or event['simulation_tick'] < 0):
raise ValueError('Simulation ticks are separate port observations')
if kind == 'original_dxwnd' and event['method'] not in ('manual', 'procedural'):
raise ValueError('Original observation method requires separately proven recorder')
identity = receipt.get('identity')
if not isinstance(identity, dict):
raise ValueError('Identity object required')
for item in identity.values():
if isinstance(item, dict) and 'path' in item:
_checked_artifact(item, root)
reference_aliases = {}
for name in _receipt_paths(receipt):
parts = relative_name(name).parts
for length in range(1, len(parts) + 1):
prefix = '/'.join(parts[:length])
previous = reference_aliases.setdefault(prefix.casefold(), prefix)
if previous != prefix:
raise ValueError('Case-colliding artifact/identity path components')
acceptance = receipt.get('acceptance')
if (not isinstance(acceptance, dict) or acceptance.get('state') not in ('open', 'accepted')
or not isinstance(acceptance.get('remaining'), list)
or not all(isinstance(item, str) for item in acceptance['remaining'])):
raise ValueError('Explicit acceptance state/remaining required')
synthetic = (kind == 'synthetic' or receipt.get('scope') == 'tooling-test' or
any(item.get('synthetic') for item in artifacts.values()))
if synthetic and kind != 'synthetic':
raise ValueError('Synthetic artifacts cannot be relabeled as runtime evidence')
missing = list(receipt['missing_evidence']) + list(acceptance['remaining'])
if kind not in ('native_port', 'original_dxwnd'):
missing.append(kind + ' is not original/native gameplay acceptance')
if receipt['historical']:
missing.append('Historical evidence requires explicit current applicability review')
if status != 'reviewed':
missing.append('Status ' + status + ' has no completed audiovisual review')
required = ['executable', 'package', 'resources', 'launcher', 'source']
if kind == 'original_dxwnd':
required += ['original_pre', 'original_post', 'copy_pre', 'copy_post', 'dxwnd', 'dxwnd_config']
for key in required:
item = identity.get(key)
if not isinstance(item, dict) or 'path' not in item:
missing.append('Missing actual identity: ' + key)
roles = {a.get('role') for a in artifacts.values() if a.get('size', 0) > 0}
for role in ('video', 'audio', 'input_events'):
if role not in roles:
missing.append('Missing evidence artifact: ' + role)
review = receipt.get('review', {})
if not isinstance(review, dict):
raise ValueError('Review must be an object')
if not all(review.get(k) is True for k in ('visible', 'audible', 'ordinary_input', 'human_reviewed')):
missing.append('Actual visible/audible/ordinary-input human review remains open')
if not platform.get('version'):
missing.append('Missing actual OS version')
source = identity.get('source', {})
if (not source.get('commit') or not isinstance(source.get('dirty'), bool)
or not source.get('diff_sha256')):
missing.append('Missing exact source/dirty/diff identity')
if kind == 'native_port' and not all(platform.get(k) for k in ('gpu', 'driver', 'vulkan', 'sdl')):
missing.append('Missing port GPU/driver/Vulkan/SDL provenance')
if kind == 'original_dxwnd' and not receipt.get('wrapper_settings'):
missing.append('Missing actual DxWnd settings/limitations')
missing = list(dict.fromkeys(missing))
if acceptance['state'] == 'accepted' and missing:
raise ValueError('Unsupported acceptance promotion: ' + '; '.join(missing))
return {'valid': True, 'accepted': acceptance['state'] == 'accepted' and not missing,
'evidence_kind': kind, 'status': status, 'missing_evidence': missing,
'receipt_id': receipt['receipt_id']}
def _receipt_paths(receipt):
paths = [item['path'] for item in receipt['artifacts']]
paths += [item['path'] for item in receipt['identity'].values()
if isinstance(item, dict) and 'path' in item]
return sorted(set(paths))
def import_receipt(path, root, output):
root, output = separated_roots(root, output)
path = Path(path).resolve(strict=True)
if not path.is_relative_to(root):
raise ValueError('Receipt input must be contained in bundle')
receipt = read_json(path)
validate_receipt(receipt, root)
with path.open('rb') as stream:
raw = stream.read(MAX_JSON_BYTES + 1)
if len(raw) > MAX_JSON_BYTES:
raise ValueError('Receipt exceeds size limit')
if json.loads(raw) != receipt:
raise ValueError('Receipt changed during import')
receipt_id = _id(receipt['receipt_id'])
if receipt['evidence_kind'] == 'synthetic' and 'test' not in output.name.casefold():
raise ValueError('Synthetic receipt requires a separate test output namespace')
reserved = {'receipt.json', 'receipt.sha256', 'incomplete.json'}
paths = _receipt_paths(receipt)
if any(p.casefold() in reserved for p in paths):
raise ValueError('Artifact collides with publication metadata')
lock = _reserve(output, receipt_id)
final = output / receipt_id
sha = hashlib.sha256(raw).hexdigest()
try:
aliases = [p for p in output.iterdir() if p.name.casefold() == receipt_id.casefold()]
if aliases:
if len(aliases) != 1 or aliases[0].name != receipt_id:
raise ValueError('Case-aliased receipt ID conflict')
existing = final / 'receipt.json'
if existing.read_bytes() != raw:
raise ValueError('Conflicting duplicate receipt ID')
validate_receipt(read_json(existing), final)
if (final / 'receipt.sha256').read_text().strip() != sha:
raise ValueError('Stored receipt hash mismatch')
return {'path': str(existing), 'receipt_sha256': sha, 'duplicate': True}
temporary = _temporary(output, receipt_id, 'import')
for relative in paths:
source = contained_path(root, relative)
target = temporary / relative
target.parent.mkdir(parents=True, exist_ok=True)
shutil.copyfile(source, target)
validate_receipt(receipt, temporary)
with (temporary / 'receipt.json').open('xb') as stream:
stream.write(raw)
stream.flush()
os.fsync(stream.fileno())
(temporary / 'receipt.sha256').write_text(sha + '\n')
os.rename(temporary, final)
(final / 'incomplete.json').unlink()
return {'path': str(final / 'receipt.json'), 'receipt_sha256': sha, 'duplicate': False}
finally:
lock.rmdir()
def _git_output(project, *args):
# Temporary output avoids unbounded capture_output buffers. No shell or
# imported receipt command is executed; every argument here is tool-owned.
with tempfile.TemporaryFile() as stream:
result = subprocess.run(['git', '-C', str(project), *args], stdout=stream,
stderr=subprocess.DEVNULL, timeout=20, check=False)
stream.seek(0)
data = stream.read(MAX_JSON_BYTES + 1)
if result.returncode or len(data) > MAX_JSON_BYTES:
raise ValueError('Git identity unavailable or exceeds bound')
return data
def source_identity(project):
commit = _git_output(project, 'rev-parse', 'HEAD').decode().strip()
status = _git_output(project, 'status', '--porcelain=v1', '--untracked-files=all')
diff = _git_output(project, 'diff', '--binary', 'HEAD')
untracked_names = _git_output(project, 'ls-files', '--others', '--exclude-standard', '-z')
untracked = []
for name in untracked_names.decode('utf8').split('\0'):
if name:
untracked.append({'path': name, **identify_file(contained_path(project, name))})
return {'commit': commit, 'dirty': bool(status),
'diff_sha256': hashlib.sha256(diff).hexdigest(),
'status_sha256': hashlib.sha256(status).hexdigest(),
'untracked_sha256': hashlib.sha256(canonical_bytes(untracked)).hexdigest(),
'untracked_files': untracked}
def identify_report(package, report=None, executable=None, resources=None, launcher=None, project=None):
"""Identify actual on-disk bytes; a report's recorded claims stay historical.
Does not run the package, stamp today's HEAD onto a historical binary, or
promote a report's mentioned artifacts into newly observed runtime evidence.
"""
result = {'schema_version': 1, 'evidence_kind': 'historical_report', 'historical': True,
'acceptance': {'state': 'open'}, 'missing_evidence': [], 'actual': {}}
for label, path, tree in [('package', package, True), ('report', report, False),
('executable', executable, False), ('resources', resources, True),
('launcher', launcher, False)]:
if path is None or not Path(path).exists():
result['missing_evidence'].append(label + ' absent; no identity minted')
continue
result['actual'][label] = identify_tree(path) if tree else dict(identify_file(path), path=str(Path(path).resolve()))
if label == 'report':
with Path(path).open('rb') as stream:
result['recorded_scope'] = stream.read(16384).decode('utf8', 'replace')
result['scope_limit'] = 'Historical text only; referenced artifacts not implicitly verified'
if project:
result['collector_source'] = source_identity(project)
result['missing_evidence'].append('No new runtime execution or current applicability established')
return result
OBLIGATION_IDS = ['continuous', 'dialogue-return', 'bank-left', 'bank-right', 'landing-idle']
SIDE_KEYS = [('original_dxwnd', 'windows'), ('native_port', 'linux'), ('native_port', 'windows')]
BASE_EVENTS = {
'continuous': ['startup', 'control', 'dialogue_start', 'dialogue_end', 'first_neutral_input',
'jump_left', 'bank_left', 'landing_left', 'jump_right', 'bank_right', 'landing',
'idle', 'lab_departure', 'vr04_entry', 'vr04_use', 'return_cleanup', 'lab_return',
'lab_exit', 'outside_arrival'],
'dialogue-return': ['dialogue_start', 'dialogue_end', 'first_neutral_input', 'idle'],
'bank-left': ['jump_left', 'bank_left', 'landing'],
'bank-right': ['jump_right', 'bank_right', 'landing'],
'landing-idle': ['landing', 'idle']}
def validate_scenario_contract(protocol):
if protocol.get('schema_version') != 1:
raise ValueError('Unsupported scenario schema')
cells = protocol.get('cells', [])
expected = sorted('-'.join(parts) for parts in itertools.product(
('fresh', 'retained'), ('natural', 'skipped'), ('ordinary', 'edge')))
if [c.get('id') for c in cells] != expected:
raise ValueError('Required eight uniquely identified, ordered matrix cells are missing/duplicated')
for cell in cells:
if (cell['id'] != '-'.join(cell.get(k, '') for k in ('lifetime', 'dialogue', 'input'))
or cell.get('obligations') != OBLIGATION_IDS):
raise ValueError('Matrix dimensions/obligations do not match stable case ID')
sides = protocol.get('required_sides', [])
if [(s.get('evidence_kind'), s.get('os')) for s in sides] != SIDE_KEYS:
raise ValueError('Original-DxWnd and both native-port sides are separately required')
if len({s.get('id') for s in sides}) != 3:
raise ValueError('Side IDs must be unique')
for key in OBLIGATION_IDS:
obligation = protocol.get('obligations', {}).get(key, {})
if obligation.get('required_events') != BASE_EVENTS[key]:
raise ValueError('Required chronological event protocol missing: ' + key)
if obligation.get('required_artifact_roles') != ['video', 'audio', 'input_events', 'prerequisite']:
raise ValueError('Required artifact obligations missing: ' + key)
if not all(isinstance(obligation.get(k), str) and obligation[k].strip()
for k in ('setup', 'actions', 'end_condition')):
raise ValueError('Executable procedure missing: ' + key)
if protocol['obligations']['continuous'].get('route') != ['lab', 'VR04', 'lab', 'outside']:
raise ValueError('Continuous journey must be lab -> VR04 -> lab -> outside')
if protocol.get('dialogue_events') != {'natural': ['dialogue_end'], 'skipped': ['dialogue_skip', 'dialogue_end']}:
raise ValueError('Natural/skipped dialogue require separate observed boundaries')
if protocol.get('input_events') != {'ordinary': [], 'edge': ['resumed_held_input', 'held_dialogue', 'held_return']}:
raise ValueError('Held input through dialogue/return is required for edge runs')
if set(protocol.get('protected_observations', {})) != {
'tsk_retained_order', 'fresh_direct_scene_order', 'legitimate_landing_bank'}:
raise ValueError('Protected movement observations are missing')
event = protocol.get('event_contract', {})
if (event.get('original_method') != ['manual', 'procedural'] or
event.get('simulation_ticks') != 'separate_port_only'):
raise ValueError('Original annotation and port clock categories must remain distinct')
return {'valid': True, 'cells': 8, 'required': 120}
def required_events(protocol, cell, obligation_id):
events = list(protocol['obligations'][obligation_id]['required_events'])
if 'dialogue_end' in events and cell['dialogue'] == 'skipped':
events.insert(events.index('dialogue_end'), 'dialogue_skip')
if cell['input'] == 'edge':
if 'dialogue_start' in events:
events.insert(events.index('dialogue_start') + 1, 'held_dialogue')
events.insert(events.index('first_neutral_input'), 'resumed_held_input')
if 'return_cleanup' in events:
events.insert(events.index('return_cleanup'), 'held_return')
return events
def _scenario_observation(protocol, cell, receipt):
obligation = receipt['obligation_id']
if receipt.get('scope') != obligation:
raise ValueError('Receipt scope must match its explicit obligation')
events = receipt['events']
required = required_events(protocol, cell, obligation)
# Select in recorded order; repeated names are legitimate only when the
# requested boundaries can still be found without reordering observations.
selected, cursor = [], 0
for name in required:
while cursor < len(events) and events[cursor]['name'] != name:
cursor += 1
if cursor >= len(events):
raise ValueError('Missing/out-of-order event: ' + name)
selected.append(events[cursor])
cursor += 1
elapsed = [e['elapsed_seconds'] for e in events]
if elapsed != sorted(elapsed):
raise ValueError('Event timestamps reset within session')
media_paths = {e['artifact'] for e in selected}
if len(media_paths) != 1:
raise ValueError('continuous/focused observations cannot be disconnected snapshots')
times = [e['media_seconds'] for e in selected]
if times != sorted(times) or times[-1] <= times[0]:
raise ValueError('Media timestamps reset or contain no observed interval')
video = next(a for a in receipt['artifacts'] if a['path'] == selected[0]['artifact'])
if video.get('role') != 'video':
raise ValueError('continuous/focused markers require actual video artifact')
roles = {a.get('role') for a in receipt['artifacts']}
if not set(protocol['obligations'][obligation]['required_artifact_roles']).issubset(roles):
raise ValueError('Missing required scenario artifacts')
continuity = receipt.get('continuity', {})
if (not receipt['clocks'].get('clock_id') or
continuity.get('lifetime_id') != receipt['session_id']):
raise ValueError('One explicit monotonic clock and lifetime identity required')
if continuity.get('prerequisite_artifact') not in {
a['path'] for a in receipt['artifacts'] if a.get('role') == 'prerequisite'}:
raise ValueError('Visible identified prerequisite setup required')
if (not re.fullmatch('[0-9a-f]{64}', continuity.get('copy_pre_sha256', '')) or
continuity['copy_pre_sha256'] != receipt['identity'].get('copy_pre', {}).get('sha256')):
raise ValueError('Copy pre state must bind the actual named copy_pre identity record')
if cell['lifetime'] == 'retained':
if (continuity.get('departure_session_id') != receipt['session_id'] or
continuity.get('return_session_id') != receipt['session_id'] or
not re.fullmatch('[0-9a-f]{64}', continuity.get('retained_copy_sha256', ''))):
raise ValueError('Retained departure/return/copy must preserve the same session')
if continuity['retained_copy_sha256'] != receipt['identity'].get('retained_copy', {}).get('sha256'):
raise ValueError('Retained copy state must bind the actual named retained_copy identity record')
prerequisite = [e for e in events if e['artifact'] == continuity['prerequisite_artifact']]
names = [e['name'] for e in prerequisite]
if ('prerequisite_departure' not in names or 'prerequisite_return' not in names or
names.index('prerequisite_departure') >= names.index('prerequisite_return') or
any(e['elapsed_seconds'] >= selected[0]['elapsed_seconds'] for e in prerequisite)):
raise ValueError('Retained setup requires observed prerequisite departure/return before test')
def audit_scenarios(protocol, records):
"""records is [(receipt_dict, contained_artifact_root), ...]. No writes.
A complete result describes declared/reviewed receipt coverage, not automatic
audiovisual truth or a universal fidelity tolerance. Real capture/review and
current applicability remain the responsibility of the acceptance owner.
"""
validate_scenario_contract(protocol)
cells = {c['id']: c for c in protocol['cells']}
required = {(c, o, kind, os_name) for c in cells for o in OBLIGATION_IDS
for kind, os_name in SIDE_KEYS}
filled, seen, invalid, open_receipts, fresh_sessions = set(), set(), [], [], {}
for receipt, root in records:
label = str(receipt.get('receipt_id', '<missing>'))
try:
result = validate_receipt(receipt, root)
case, obligation = receipt['case_id'], receipt.get('obligation_id')
key = (case, obligation, receipt['evidence_kind'], receipt['platform']['os'])
if key not in required:
raise ValueError('Evidence is not a required original/native matrix slot')
if key in seen:
filled.discard(key)
raise ValueError('Duplicate/conflicting matrix slot; explicitly select applicability first')
seen.add(key)
if not result['accepted']:
open_receipts.append(label + ': ' + '; '.join(result['missing_evidence']))
continue
_scenario_observation(protocol, cells[case], receipt)
if cells[case]['lifetime'] == 'fresh':
session_key = (receipt['evidence_kind'], receipt['platform']['os'], receipt['session_id'])
if session_key in fresh_sessions:
filled.discard(fresh_sessions[session_key])
raise ValueError('fresh runs require independently staged launch/session IDs')
fresh_sessions[session_key] = key
filled.add(key)
except (ValueError, KeyError, TypeError) as error:
invalid.append(label + ': ' + str(error))
gaps = required - filled
side_ids = {(s['evidence_kind'], s['os']): s['id'] for s in protocol['required_sides']}
return {'schema_version': 1, 'structurally_ready': True,
'complete': not gaps and not invalid, 'required': len(required), 'accepted': len(filled),
'missing_case_ids': sorted({g[0] for g in gaps}),
'missing_obligations': sorted('/'.join((c, o, side_ids[(k, os_name)]))
for c, o, k, os_name in gaps),
'open_receipts': open_receipts, 'invalid': invalid}
def audit_receipt_tree(protocol, root):
root = Path(root)
records = []
if root.exists():
# Reuse tree walker safety/bounds without hashing every video a second
# time. Validate each referenced artifact once via validate_receipt.
count = 0
for directory, dirs, files in os.walk(root, followlinks=False):
for name in dirs + files:
count += 1
if count > MAX_FILES or (Path(directory) / name).is_symlink():
raise ValueError('Receipt index unbounded or contains symlinks')
if 'receipt.json' in files:
path = Path(directory) / 'receipt.json'
records.append((read_receipt(path), path.parent))
return audit_scenarios(protocol, records)
def read_receipt(path):
"""Verify the import sidecar when present; raw collector bundles may lack it."""
path = Path(path)
receipt = read_json(path)
sidecar = path.with_name('receipt.sha256')
if sidecar.exists():
if sidecar.is_symlink() or sidecar.stat().st_size > 128:
raise ValueError('Invalid receipt hash sidecar')
if sidecar.read_text().strip() != identify_file(path)['sha256']:
raise ValueError('Receipt byte identity mismatch')
return receipt