diff --git a/tests/test_fidelity_sessions.py b/tests/test_fidelity_sessions.py index 035a8eb..e99dc1d 100644 --- a/tests/test_fidelity_sessions.py +++ b/tests/test_fidelity_sessions.py @@ -242,6 +242,27 @@ class FidelitySessions(unittest.TestCase): value['schema_version'] = 99 path.write_text(json.dumps(value)) self.assertNotEqual(self.cli('validate', path, '--root', bundle).returncode, 0) + + def test_historical_report_hashes_actual_bytes_and_retains_missing(self): + api = self.api() + report = self.base / 'report.md' + report.write_text('Historical Wine/component evidence; native Windows open') + result = api.identify_report(self.original, report, self.original / 'game.exe', + self.base / 'missing-resources') + self.assertTrue(result['historical']) + self.assertEqual(result['actual']['executable']['sha256'], self.files[0]['sha256']) + self.assertIn('Historical Wine/component', result['recorded_scope']) + self.assertTrue(any('resources absent' in s for s in result['missing_evidence'])) + + def test_cli_hostile_output_and_tampering_exit_nonzero(self): + result = self.cli('stage', '--source', self.original, '--manifest', self.manifest, + '--output', self.original / 'illegal', '--session-id', 'new') + self.assertNotEqual(result.returncode, 0) + self.assertFalse((self.original / 'illegal').exists()) + bundle, path, _ = self.fixture_receipt() + (bundle / 'port.txt').write_text('changed') + self.assertNotEqual(self.cli('import', path, '--root', bundle, + '--output', self.base / 'test-index').returncode, 0) path.write_bytes(b' ' * (4 * 1024 * 1024 + 1)) self.assertNotEqual(self.cli('validate', path, '--root', bundle).returncode, 0) diff --git a/tools/recon/fidelity.py b/tools/recon/fidelity.py new file mode 100644 index 0000000..19e0a61 --- /dev/null +++ b/tools/recon/fidelity.py @@ -0,0 +1,65 @@ +#!/usr/bin/env python3 +"""Local preserved-session and typed evidence CLI (never launches originals). + +Examples: stage --source ../Original --manifest docs/original-manifest.json +--output artifacts/fidelity/sessions --session-id fresh-001; identify dist/linux-x64; +import BUNDLE/receipt.json --root BUNDLE --output artifacts/fidelity/receipts; +validate RECEIPT --root IMPORTED_DIR --allow-open. Synthetic imports require a +separate output directory whose name contains 'test'. All outputs remain local. +""" +import argparse +import json +from pathlib import Path +import sys + +from fidelity_receipts import (identify_tree, identify_report, import_receipt, + read_json, stage_original, validate_receipt) + + +def main(argv=None): + parser = argparse.ArgumentParser(description=__doc__) + sub = parser.add_subparsers(dest='command', required=True) + stage = sub.add_parser('stage') + for flag in ('source', 'manifest', 'output'): + stage.add_argument('--' + flag, type=Path, required=True) + stage.add_argument('--session-id', required=True) + identify = sub.add_parser('identify') + identify.add_argument('path', type=Path) + for flag in ('report', 'executable', 'resources', 'launcher', 'project'): + identify.add_argument('--' + flag, type=Path) + imp = sub.add_parser('import') + imp.add_argument('receipt', type=Path) + imp.add_argument('--root', type=Path, required=True) + imp.add_argument('--output', type=Path, required=True) + validate = sub.add_parser('validate') + validate.add_argument('receipt', type=Path) + validate.add_argument('--root', type=Path, required=True) + mode = validate.add_mutually_exclusive_group() + mode.add_argument('--allow-open', action='store_true') + mode.add_argument('--require-complete', action='store_true') + args = parser.parse_args(argv) + try: + if args.command == 'stage': + result = stage_original(args.source, args.manifest, args.output, args.session_id) + elif args.command == 'identify': + result = identify_report(args.path, args.report, args.executable, args.resources, + args.launcher, args.project) if any( + getattr(args, k) is not None for k in ('report', 'executable', 'resources', 'launcher', 'project')) else identify_tree(args.path) + elif args.command == 'import': + result = import_receipt(args.receipt, args.root, args.output) + else: + result = validate_receipt(read_json(args.receipt), args.root) + print('Receipt {receipt_id}: {evidence_kind}, status={status}'.format(**result)) + print('Acceptance: ' + ('ACCEPTED' if result['accepted'] else 'OPEN')) + for missing in result['missing_evidence']: + print('Missing/open: ' + str(missing)) + return 1 if args.require_complete and not result['accepted'] else 0 + print(json.dumps(result, indent=2, allow_nan=False)) + return 0 + except (ValueError, OSError, KeyError, TypeError) as error: + print('Invalid fidelity evidence: ' + str(error), file=sys.stderr) + return 2 + + +if __name__ == '__main__': + sys.exit(main()) diff --git a/tools/recon/fidelity_receipts.py b/tools/recon/fidelity_receipts.py new file mode 100644 index 0000000..9d8bbad --- /dev/null +++ b/tools/recon/fidelity_receipts.py @@ -0,0 +1,519 @@ +"""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 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(c in value for c in '\x00\r\n') 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 = [], set() + 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(): + files.append({'path': relative, **identify_file(path)}) + 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): + return isinstance(value, (int, float)) and not isinstance(value, bool) and math.isfinite(value) + + +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) + 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', {}) + 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 (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']: + 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) + acceptance = receipt.get('acceptance') + if (not isinstance(acceptance, dict) or acceptance.get('state') not in ('open', 'accepted') + or not isinstance(acceptance.get('remaining'), list)): + 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 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) + raw = path.read_bytes() # bounded by read_json above; re-check below against races + if len(raw) > MAX_JSON_BYTES: + raise ValueError('Receipt exceeds size limit') + 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