753 lines
38 KiB
Python
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
|