feat(01-01): stage preserved sessions and import typed hashed receipts

This commit is contained in:
UnixNight committed 2026-11-12 19:02:34 -05:00
1 parent 597caa0b49
commit cd7783ba3a
3 files changed
+605

No files matched your search

+21
View File
@@ -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)
+65
View File
@@ -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())
+519
View File
@@ -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