feat(01-01): enforce eight-cell scenario and native evidence completeness

This commit is contained in:
UnixNight committed 2026-11-12 19:10:15 -05:00
1 parent cc4a5a3e92
commit 32a72654e8
5 files changed
+430 -22

No files matched your search

+26 -5
View File
@@ -13,7 +13,8 @@ from pathlib import Path
import sys
from fidelity_receipts import (identify_tree, identify_report, import_receipt,
read_json, stage_original, validate_receipt)
read_json, read_receipt, stage_original, validate_receipt,
audit_receipt_tree, canonical_bytes, MAX_JSON_BYTES)
def main(argv=None):
@@ -32,8 +33,10 @@ def main(argv=None):
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)
validate.add_argument('receipt', type=Path, nargs='?')
validate.add_argument('--root', type=Path)
validate.add_argument('--scenarios', type=Path)
validate.add_argument('--receipts', type=Path)
mode = validate.add_mutually_exclusive_group()
mode.add_argument('--allow-open', action='store_true')
mode.add_argument('--require-complete', action='store_true')
@@ -48,13 +51,31 @@ def main(argv=None):
elif args.command == 'import':
result = import_receipt(args.receipt, args.root, args.output)
else:
result = validate_receipt(read_json(args.receipt), args.root)
if args.scenarios:
if args.receipt or args.root or not args.receipts:
raise ValueError('Scenario validation requires --scenarios PATH --receipts ROOT')
result = audit_receipt_tree(read_json(args.scenarios), args.receipts)
print('Structural readiness: READY; acceptance: ' + ('COMPLETE' if result['complete'] else 'OPEN'))
print('Accepted obligations: {accepted}/{required}'.format(**result))
print('Missing case IDs: ' + ', '.join(result['missing_case_ids']))
for key in ('missing_obligations', 'open_receipts', 'invalid'):
for item in result[key]:
print(key + ': ' + item)
if result['invalid']:
return 2
return 1 if args.require_complete and not result['complete'] else 0
if args.receipt is None or args.root is None or args.receipts:
raise ValueError('Receipt validation requires RECEIPT --root ROOT')
result = validate_receipt(read_receipt(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))
data = canonical_bytes(result)
if len(data) > MAX_JSON_BYTES:
raise ValueError('Result JSON exceeds 4 MiB limit')
print(data.decode(), end='')
return 0
except (ValueError, OSError, KeyError, TypeError) as error:
print('Invalid fidelity evidence: ' + str(error), file=sys.stderr)
+241 -7
View File
@@ -19,6 +19,7 @@ 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
@@ -94,7 +95,7 @@ def relative_name(value):
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(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:
@@ -133,7 +134,7 @@ 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()
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
@@ -148,7 +149,11 @@ def identify_tree(root):
if path.is_symlink():
raise ValueError('Symlink tree member: ' + relative)
if path.is_file():
files.append({'path': relative, **identify_file(path)})
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'])
@@ -278,7 +283,12 @@ def _checked_artifact(item, root):
def _finite(value):
return isinstance(value, (int, float)) and not isinstance(value, bool) and math.isfinite(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):
@@ -309,12 +319,17 @@ def validate_receipt(receipt, root):
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')
@@ -334,10 +349,12 @@ def validate_receipt(receipt, root):
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
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')
@@ -360,9 +377,18 @@ def validate_receipt(receipt, root):
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 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()))
@@ -387,6 +413,8 @@ def validate_receipt(receipt, root):
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'):
@@ -421,9 +449,12 @@ def import_receipt(path, root, output):
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
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')
@@ -517,3 +548,206 @@ def identify_report(package, report=None, executable=None, resources=None, launc
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', '')):
raise ValueError('Missing pristine copy/package session identity')
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')
identified = {item.get('sha256') for item in receipt['identity'].values() if isinstance(item, dict)}
if (continuity['copy_pre_sha256'] not in identified or
continuity['retained_copy_sha256'] not in identified):
raise ValueError('Retained copy state must bind actual hashed identity records')
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