Files
Neutron/tools/recon/fidelity_ledger.py
T

435 lines
25 KiB
Python

"""Version 1 capability ledger: source reports are evidence, never new executions.
The authoritative JSON retains all records. Current means applicable to an explicit
content/platform/scope target, including named historical targets; it never means
the newest date or current Git HEAD. A report's identity is not a runtime identity.
Real receipt references are revalidated through fidelity_receipts. Missing captures
remain open. Render/export are generated views, not independent status sources.
Only cooperative local filesystem use is supported; revalidate after changes.
No commands from imported data are executed. No network or package dependencies.
"""
import argparse
import copy
import hashlib
import html
import json
from pathlib import Path
import re
import subprocess
import sys
from urllib.parse import quote
# A bundled CLI must not create bytecode inside the sealed checkpoint.
if __name__ == '__main__':
sys.dont_write_bytecode = True
from fidelity_receipts import (KINDS, MAX_JSON_BYTES, canonical_bytes, contained_path,
identify_file, read_json, validate_receipt)
PROJECT = Path(__file__).resolve().parents[2]
GROUPS = ('movement', 'contacts', 'gadgets', 'progression', 'visuals', 'audio')
IMPACTS = {'blocking': 0, 'disruptive': 1, 'subtle': 2, 'missing_verification': 3}
EXCLUDED = {'original', 'artifacts', 'dist', '.git', '.tools', '.nuget', '.aws', '.codex', '.agents'}
ID = re.compile(r'^[A-Za-z0-9][A-Za-z0-9._:-]{0,159}$')
HASH = re.compile(r'^[a-f0-9]{64}$')
def _text(value, name):
if not isinstance(value, str) or not value.strip() or len(value) > 16384 or '\0' in value:
raise ValueError('Missing or unbounded text: ' + name)
return value
def _id(value):
if not isinstance(value, str) or not ID.fullmatch(value):
raise ValueError('Invalid stable ID')
return value
def _list(value, name, nonempty=False):
if not isinstance(value, list) or len(value) > 4096 or (nonempty and not value):
raise ValueError('Missing or unbounded array: ' + name)
return value
def _bounded(value, depth=0):
if depth > 24:
raise ValueError('Ledger nesting exceeds bound')
if isinstance(value, dict):
if len(value) > 128: raise ValueError('Object exceeds field bound')
for key, item in value.items():
_text(key, 'field name')
_bounded(item, depth + 1)
elif isinstance(value, list):
_list(value, 'array')
for item in value: _bounded(item, depth + 1)
elif isinstance(value, str):
if len(value) > 16384 or '\0' in value: raise ValueError('Text exceeds bound')
elif value is not None and not isinstance(value, (int, float, bool)):
raise ValueError('Non-JSON value')
def _deduplicate(rows, key):
found = {}
for row in rows:
if not isinstance(row, dict): raise ValueError('Expected record object')
identity = _id(row.get(key))
if identity in found and canonical_bytes(found[identity]) != canonical_bytes(row):
raise ValueError('Conflicting duplicate ' + key + ': ' + identity)
found[identity] = row
return [found[key] for key in sorted(found)]
def _identity(record):
content = record.get('content')
if not isinstance(content, dict) or not content:
raise ValueError('Explicit content identity required')
for key, value in content.items():
if not key.endswith('_sha256') or not isinstance(value, str) or not HASH.fullmatch(value):
raise ValueError('Content identities must be actual SHA-256 declarations')
platform = record.get('platform')
if not isinstance(platform, dict): raise ValueError('Platform object required')
_text(platform.get('os'), 'platform.os')
_text(platform.get('execution'), 'platform.execution')
scope = _list(record.get('scope'), 'scope', True)
for item in scope: _text(item, 'scope item')
if len(scope) != len(set(scope)): raise ValueError('Duplicate scope')
return canonical_bytes([content, platform, sorted(scope)])
def select_current_evidence(records, target):
"""Select exact content/platform/scope matches, ignoring docs/source timestamps.
A changed runtime, resource or package digest, missing identity field or
different platform/scope cannot inherit proof. Caller validates the graph.
"""
identity = _identity(target)
records = _deduplicate(records, 'id')
superseded = {old for record in records for old in record.get('supersedes', [])}
return [record for record in records if record.get('status') == 'current'
and record['id'] not in superseded and _identity(record) == identity]
def _tracked(project):
result = subprocess.run(['git', '-C', str(project), 'ls-files', '-z'],
capture_output=True, check=True, timeout=20)
if len(result.stdout) > MAX_JSON_BYTES: raise ValueError('Source inventory exceeds bound')
return set(result.stdout.decode('utf8').split('\0'))
def _source(project, link, tracked):
if not isinstance(link, dict): raise ValueError('Source link must be an object')
_text(link.get('label'), 'source label')
path = contained_path(project, link.get('path'))
name = path.relative_to(project).as_posix()
if name.split('/')[0].lower() in EXCLUDED:
raise ValueError('Original/generated/private source link forbidden')
if name not in tracked or not path.is_file(): raise ValueError('Dead tracked source link: ' + name)
if path.stat().st_size > 1024 * 1024: raise ValueError('Source text exceeds 1 MiB')
raw = path.read_bytes()
raw.decode('utf8')
if b'\0' in raw: raise ValueError('Source link must be UTF-8 text')
digest = hashlib.sha256(raw).hexdigest()
if 'sha256' in link and digest != link['sha256']: raise ValueError('Source hash mismatch: ' + name)
return name
def checkpoint_rows(path):
"""Identity every system/ownership table row and numbered assumption.
Exact line/paragraph bytes are hashed so reconciliation must be reviewed
when its source changes. Top-level narrative remains in the linked report.
"""
text = Path(path).read_text()
result, section = {}, None
for line in text.splitlines():
if line.startswith('| ID / system |'): section = 'system'
elif line.startswith('| State / owner |'): section = 'ownership'
elif line.startswith('#'): section = None
elif section and line.startswith('|') and not line.startswith('|---'):
key = section + ':' + line.split('|')[1].strip()
if key in result: raise ValueError('Ambiguous checkpoint row: ' + key)
result[key] = hashlib.sha256(line.encode()).hexdigest()
marker = '## Assumptions and symptom-level adapters to replace'
if marker not in text: raise ValueError('Missing checkpoint assumptions section')
assumptions = text.split(marker, 1)[1].split('\n## ', 1)[0]
for match in re.finditer(r'^([1-9][0-9]*)\. (.*(?:\n(?!\n|[1-9][0-9]*\. ).*)*)', assumptions, re.M):
result['assumption:' + match[1]] = hashlib.sha256(match[0].encode()).hexdigest()
return result
def _records(row, project, tracked):
records = _deduplicate(_list(row.get('evidence'), 'evidence'), 'id')
_deduplicate(records, 'receipt_id')
by_id = {record['id']: record for record in records}
superseded = set()
claims = {}
for record in records:
identity = _identity(record)
kind = record.get('evidence_kind')
if kind not in KINDS: raise ValueError('Invalid receipt classification')
platform = record['platform']
execution = platform['execution']
if kind == 'native_port' and (execution != 'native' or platform['os'] not in {'linux', 'windows'}):
raise ValueError('Native/fixture classification cannot use Wine or source proof')
if kind == 'port_fixture' and (execution not in {'native', 'port_fixture'} or platform['os'] not in {'linux', 'windows'}):
raise ValueError('Fixture classification requires its declared port host')
if kind in {'component', 'managed', 'synthetic'} and execution != kind:
raise ValueError('Component/managed/synthetic evidence must retain its execution category')
if kind == 'inferred' and execution not in {'static', 'inferred'}:
raise ValueError('Inference cannot become runtime proof')
if kind == 'original_dxwnd' and (platform['os'] != 'windows' or execution != 'dxwnd'):
raise ValueError('Original DxWnd requires Windows/DxWnd')
if kind == 'wine' and execution != 'wine': raise ValueError('Wine must stay Wine')
if kind == 'cross_publish' and execution != 'cross_publish': raise ValueError('Cross-publish is not execution')
if kind == 'static' and execution != 'static': raise ValueError('Static evidence must stay static')
if record.get('status') not in {'current', 'historical', 'superseded'}:
raise ValueError('Invalid applicability status')
if not isinstance(record.get('historical'), bool): raise ValueError('Historical flag required')
_text(record.get('revision'), 'evidence revision')
_text(record.get('method'), 'observation method')
_source(project, {'label': 'Evidence report', 'path': record.get('report_path')}, tracked)
if 'report_sha256' in record['content']:
report = contained_path(project, record['report_path'])
if identify_file(report)['sha256'] != record['content']['report_sha256']:
raise ValueError('Report content identity mismatch')
claim = record.get('claim')
if not isinstance(claim, dict): raise ValueError('Evidence claim required')
_text(claim.get('key'), 'claim key')
_text(claim.get('result'), 'claim result')
parents = _list(record.get('supersedes'), 'supersedes')
if parents: _text(record.get('reason'), 'supersession reason')
for old in parents:
if old not in by_id: raise ValueError('Unknown supersedes ID: ' + str(old))
if by_id[old]['status'] != 'superseded': raise ValueError('Superseded record must retain explicit label')
superseded.add(old)
if record['status'] == 'current':
key = (identity, claim['key'])
if key in claims and claims[key] != claim['result']:
raise ValueError('Contradictory current claim: ' + claim['key'])
claims[key] = claim['result']
for gap in _list(record.get('missing_evidence'), 'missing evidence'):
_text(gap, 'missing evidence')
for artifact in _list(record.get('artifacts'), 'artifacts'):
path = contained_path(project, artifact.get('path'))
if path.relative_to(project).parts[0] != 'artifacts':
raise ValueError('Local evidence artifacts must stay under artifacts/')
if not path.is_file():
_text(artifact.get('missing_reason'), 'missing artifact reason')
else:
actual = identify_file(path)
if actual['sha256'] != artifact.get('sha256') or actual['size'] != artifact.get('size'):
raise ValueError('Artifact identity mismatch: ' + artifact['path'])
if 'receipt_path' in record:
receipt_path = contained_path(project, record['receipt_path'])
receipt = read_json(receipt_path)
validate_receipt(receipt, receipt_path.parent)
if receipt['receipt_id'] != record['receipt_id'] or receipt['evidence_kind'] != kind:
raise ValueError('Receipt reference identity/classification mismatch')
receipt_scope = receipt['scope'] if isinstance(receipt['scope'], list) else [receipt['scope']]
if (receipt['platform'] != record['platform'] or sorted(receipt_scope) != sorted(record['scope'])
or receipt['historical'] != record['historical']):
raise ValueError('Receipt reference platform/scope/history mismatch')
if record['content'].get('receipt_sha256') != identify_file(receipt_path)['sha256']:
raise ValueError('Receipt reference requires its exact content digest')
visiting, visited = set(), set()
def visit(identifier):
if identifier in visiting: raise ValueError('Supersession cycle')
if identifier in visited: return
visiting.add(identifier)
for parent in by_id[identifier]['supersedes']: visit(parent)
visiting.remove(identifier)
visited.add(identifier)
for identifier in by_id: visit(identifier)
for record in records:
if record['status'] == 'superseded' and record['id'] not in superseded:
raise ValueError('Superseded history requires explicit successor/reason')
return records
def validate_ledger(data, project=PROJECT, requirements=None):
"""Return counted structural coverage; no runtime acceptance is inferred."""
project = Path(project).resolve(strict=True)
_bounded(data)
if len(canonical_bytes(data)) > MAX_JSON_BYTES: raise ValueError('Ledger exceeds 4 MiB')
if data.get('schema_version') != 1: raise ValueError('Unsupported ledger version')
rows = _deduplicate(_list(data.get('capabilities'), 'capabilities', True), 'id')
tracked = _tracked(project)
scenarios = read_json(project / 'docs/evidence/scenarios.json')
scenario_ids = {cell['id'] for cell in scenarios['cells']}
mapped, groups, all_records = set(), set(), []
for row in rows:
if row.get('group') not in GROUPS: raise ValueError('Unknown capability group')
groups.add(row['group'])
for key in ('summary', 'verified_scope'): _text(row.get(key), key)
for key in ('differences',):
for item in _list(row.get(key), key, True): _text(item, key)
for req in _list(row.get('requirement_ids'), 'requirements', True):
if not isinstance(req, str) or not re.fullmatch(r'[A-Z]+-[0-9]{2}', req): raise ValueError('Invalid requirement ID')
mapped.add(req)
acceptance = row.get('acceptance')
if not isinstance(acceptance, dict) or acceptance.get('status') != 'open':
raise ValueError('Full-game acceptance remains open until the separate identified audit')
for item in _list(acceptance.get('remaining'), 'remaining acceptance', True): _text(item, 'remaining acceptance')
for link in _list(row.get('source_links'), 'source links', True): _source(project, link, tracked)
for scenario in _list(row.get('scenario_ids'), 'scenario IDs'):
if scenario not in scenario_ids: raise ValueError('Unknown scenario ID')
implementation = row.get('implementation')
if not isinstance(implementation, dict): raise ValueError('Implementation metadata required')
_text(implementation.get('revision'), 'implementation revision')
if implementation.get('status') not in {'bounded', 'unimplemented', 'tooling'}:
raise ValueError('Implementation must distinguish bounded/unimplemented/tooling')
for path in _list(implementation.get('paths'), 'implementation paths'):
_source(project, {'label': 'Implementation', 'path': path}, tracked)
records = _records(row, project, tracked)
all_records.extend(records)
targets = _deduplicate(_list(row.get('targets'), 'applicability targets'), 'id')
for target in targets: _identity(target)
for record in records:
if record['status'] == 'current' and not any(record in select_current_evidence(records, target) for target in targets):
raise ValueError('Current record has no matching explicit applicability target')
discrepancies = _deduplicate(_list(row.get('discrepancies'), 'discrepancies'), 'id')
for gap in discrepancies:
if gap.get('impact') not in IMPACTS: raise ValueError('Invalid discrepancy impact')
_text(gap.get('summary'), 'discrepancy summary')
_deduplicate(all_records, 'id')
_deduplicate(all_records, 'receipt_id')
expected = set()
if requirements is not None:
expected = set(re.findall(r'^- \[[ x]\] \*\*([A-Z]+-[0-9]{2})\*\*:', Path(requirements).read_text(), re.M))
if not expected or expected != mapped: raise ValueError('Unmapped or unknown requirements: ' + str(sorted(expected ^ mapped)))
if groups != set(GROUPS): raise ValueError('All six capability groups are required')
if requirements is not None or 'reconciliation' in data:
expected_rows = checkpoint_rows(project / 'docs/checkpoint/coverage.md')
reconciliation = _list(data.get('reconciliation'), 'checkpoint reconciliation', True)
actual_rows = {}
for record in reconciliation:
source_row = _text(record.get('source_row'), 'source row')
if source_row in actual_rows: raise ValueError('Duplicate source reconciliation row')
actual_rows[source_row] = record.get('source_sha256')
if record.get('source_path') != 'docs/checkpoint/coverage.md': raise ValueError('Wrong checkpoint source')
_source(project, {'label': 'Checkpoint', 'path': record['source_path']}, tracked)
for identifier in _list(record.get('capability_ids'), 'reconciled capability IDs', True):
if identifier not in {row['id'] for row in rows}: raise ValueError('Unknown reconciled capability')
capability = next(row for row in rows if row['id'] == identifier)
if not any(link['path'] == record['source_path'] for link in capability['source_links']):
raise ValueError('Reconciled capability must link the retained checkpoint source')
if actual_rows != expected_rows: raise ValueError('Missing, stale or extra checkpoint source-row reconciliation')
return {'capabilities': len(rows), 'requirements': len(expected or mapped),
'unmapped': len(expected - mapped), 'groups': len(groups),
'reconciled_rows': len(data.get('reconciliation', [])), 'acceptance': 'OPEN'}
def export_ledger(data, project=PROJECT, requirements=None):
counts = validate_ledger(data, project, requirements)
result = copy.deepcopy(data)
rows = _deduplicate(result['capabilities'], 'id')
for row in rows:
row['evidence'] = _deduplicate(row['evidence'], 'id')
selected = {record['id'] for target in row['targets']
for record in select_current_evidence(row['evidence'], target)}
row['current'] = [r for r in row['evidence'] if r['id'] in selected]
row['history'] = [r for r in row['evidence'] if r['id'] not in selected]
row['discrepancies'] = sorted(row['discrepancies'], key=lambda r: (IMPACTS[r['impact']], r['id']))
def order(row):
priority = min((IMPACTS[r['impact']] for r in row['discrepancies']), default=4)
return (GROUPS.index(row['group']), priority, row['id'])
result['capabilities'] = sorted(rows, key=order)
result['counts'] = counts
return result
def _escape(value):
return html.escape(str(value), quote=True).replace('|', '|').replace('`', '`')
def render_markdown(data, project=PROJECT, requirements=None):
model = export_ledger(data, project, requirements)
counts = model['counts']
lines = ['# Capability evidence ledger', '',
'Generated by tools/recon/fidelity_ledger.py from [capabilities.json](capabilities.json).', '',
f"Capabilities: {counts['capabilities']}; requirements: {counts['requirements']}; unmapped: {counts['unmapped']}. Acceptance: **OPEN**.", '',
'Current means exact named content/platform/scope applicability, including explicitly historical bytes. '
'A report link is not a new execution; date or docs HEAD never promotes proof. '
'Original-DxWnd/native matrix acceptance remains **0/120** until identified captures and review.', '',
'Regenerate and validate locally:', '', '```sh',
'python3 tools/recon/fidelity_ledger.py validate --ledger docs/evidence/capabilities.json --requirements .planning/REQUIREMENTS.md',
'python3 tools/recon/fidelity_ledger.py render --ledger docs/evidence/capabilities.json --output docs/evidence/README.md',
'python3 tools/recon/fidelity_ledger.py export --ledger docs/evidence/capabilities.json --output artifacts/fidelity/review/ledger.json',
'python3 tools/recon/fidelity_review.py export --ledger artifacts/fidelity/review/ledger.json --output artifacts/fidelity/review/new-review',
'```', '',
'Omitting recordings creates an explicitly missing-media review. Add --original and --port imported receipt.json paths when available. '
'Scenario IDs link to the [eight-cell protocol](scenarios.json). Ledger evidence summaries are typed report records; '
'only receipt_path entries reference imported version 1 receipts. Missing local artifacts retain their reasons. '
'Source/implementation links are tracked bounded UTF-8 text; viewer export copies them into its contained sources/ tree.', '']
for group in GROUPS:
rows = [row for row in model['capabilities'] if row['group'] == group]
if not rows: continue
lines.extend(['## ' + group.title(), ''])
for row in rows:
lines.extend(['### ' + _escape(row['id']), '', '**Working behavior:** ' + _escape(row['summary']), '',
'**Verified scope/platform:** ' + _escape(row['verified_scope']), '',
'**Known differences:** ' + '; '.join(map(_escape, row['differences'])), '',
'**Remaining acceptance — OPEN:** ' + '; '.join(map(_escape, row['acceptance']['remaining'])), '',
'**Requirements:** ' + ', '.join(row['requirement_ids']) + ' · **Implementation:** ' + _escape(row['implementation']), '',
'**Sources:** ' + ', '.join('[' + _escape(link['label']) + '](../../' + quote(link['path'], safe='/') + ')' for link in row['source_links']), '',
'**Scenarios:** ' + ', '.join('[' + _escape(scenario) + '](scenarios.json)' for scenario in row['scenario_ids']), '',
'**Current applicable evidence (only the targets below):**', ''])
lines.extend(['- ' + _escape(json.dumps(record, sort_keys=True)) for record in row['current']] or ['- No matching identified evidence; acceptance remains open.'])
lines.extend(['', '**Explicit applicability targets:** ' + _escape(row['targets']), '',
'<details><summary>History — exact revisions and supersession retained</summary>', ''])
lines.extend(['- ' + _escape(json.dumps(record, sort_keys=True)) for record in row['history']] or ['- No superseded evidence recorded.'])
lines.extend(['', '</details>', '', '**Player-impact discrepancies:**', ''])
lines.extend('- **' + gap['impact'] + '** · ' + _escape(gap['id']) + ': ' + _escape(gap['summary']) for gap in row['discrepancies'])
lines.append('')
if model.get('reconciliation'):
lines.extend(['## Source-row reconciliation', '', 'Every checkpoint row remains explicitly linked; continuation reports refine its claims.', ''])
for record in model['reconciliation']:
lines.append('- ' + _escape(record['source_row']) + ' → ' + ', '.join(map(_escape, record['capability_ids'])) + ' · [retained source](../../' + quote(record['source_path'], safe='/') + ')')
return '\n'.join(lines) + '\n'
def _write(path, raw):
path = Path(path)
resolved = path.resolve()
if not (resolved.is_relative_to(PROJECT) or resolved.is_relative_to(Path('/tmp'))):
raise ValueError('Generated output must remain in project or local /tmp')
if any(part.lower() in {'original', '.git'} for part in path.parts):
raise ValueError('Cannot write originals or Git metadata')
cursor = path.absolute()
for part in [cursor, *cursor.parents]:
if part.is_symlink(): raise ValueError('Output cannot traverse symlinks')
path.parent.mkdir(parents=True, exist_ok=True)
path.write_bytes(raw)
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('command', choices=['validate', 'render', 'export'])
parser.add_argument('--ledger', type=Path, required=True)
parser.add_argument('--requirements', type=Path)
parser.add_argument('--output', type=Path)
args = parser.parse_args()
try:
data = read_json(args.ledger)
requirements = args.requirements
if requirements is None and 'reconciliation' in data:
requirements = PROJECT / '.planning/REQUIREMENTS.md'
counts = validate_ledger(data, PROJECT, requirements)
if args.command != 'validate':
if args.output is None: raise ValueError('--output required')
if args.output.resolve() == args.ledger.resolve(): raise ValueError('Cannot overwrite authoritative ledger')
raw = (render_markdown(data, PROJECT, requirements).encode() if args.command == 'render'
else canonical_bytes(export_ledger(data, PROJECT, requirements)))
_write(args.output, raw)
print(' '.join(f'{key}={value}' for key, value in counts.items()))
return 0
except (ValueError, OSError, UnicodeError, subprocess.SubprocessError, TypeError, KeyError, RecursionError) as error:
print('Ledger invalid: ' + str(error), file=sys.stderr)
return 2
if __name__ == '__main__':
raise SystemExit(main())