feat(01-03): trace corrected TSK order through capability evidence
This commit is contained in:
1 parent
ded848f78e
commit
e6713ead48
4 files changed
+715
-1
No files matched your search
@@ -0,0 +1,367 @@
|
||||
"""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
|
||||
|
||||
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 _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 in {'native_port', 'port_fixture'} and (execution != 'native' or platform['os'] not in {'linux', 'windows'}):
|
||||
raise ValueError('Native/fixture classification cannot use Wine or source proof')
|
||||
if kind == 'original_dxwnd' and platform != {'os': 'windows', '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)
|
||||
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')
|
||||
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 = 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)
|
||||
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')
|
||||
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')
|
||||
return {'capabilities': len(rows), 'requirements': len(expected or mapped),
|
||||
'unmapped': len(expected - mapped), 'groups': len(groups), '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)
|
||||
counts = validate_ledger(data, PROJECT, args.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, args.requirements).encode() if args.command == 'render'
|
||||
else canonical_bytes(export_ledger(data, PROJECT, args.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())
|
||||
Reference in new issue
Block a user