diff --git a/docs/evidence/README.md b/docs/evidence/README.md new file mode 100644 index 0000000..1921f4e --- /dev/null +++ b/docs/evidence/README.md @@ -0,0 +1,56 @@ +# Capability evidence ledger + +Generated by tools/recon/fidelity_ledger.py from [capabilities.json](capabilities.json). + +Capabilities: 1; requirements: 2; unmapped: 0. 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. + +## Movement + +### startup-order + +**Working behavior:** TSK-backed first-story input order is already corrected: retained Jimmy updates before level-game input. Direct fresh scenes keep fresh insertion order; legitimate landing bank and all movement/rotation algorithms are preserved. + +**Verified scope/platform:** Source/data lifetime proof; historical ea04210 Linux SDL/Vulkan Carl fixture (first neutral tick, 300 idle, held return) and standalone four-readback replay. Historical Wine64 is preliminary; whole-original/native Windows comparison remains open. + +**Known differences:** Source allocation diagnostic required an OS repaint acknowledgement and black frames/timing perturbation; it is not playable original Carl evidence.; Bounded fixture input is not the complete physical-input lab→VR04→lab→outside matrix. Current package924ad2f differs from ea04210; later matching readbacks do not promote all runtime bytes. + +**Remaining acceptance — OPEN:** Identified whole-original DxWnd Carl natural/skip and fresh/retained audiovisual comparison; Current native Windows and native Linux full matrix with actual input/audio and human review; 0/120 accepted obligations; Preserve normal landing bank, fresh direct-scene order and independent airborne behavior + +**Requirements:** MOVE-04, MOVE-05 · **Implementation:** {'revision': 'ea04210f524faae7dc1caff8afbc608fbb8144f4', 'paths': ['src/GamePort/Program.cs'], 'status': 'bounded', 'note': 'story || carriedSave != null; unchanged Program source through ledger work'} + +**Sources:** [TSK source lifetime and bounded runtime receipt](../../docs/gameplay/main-menu-player-lifetime.md), [Exact implementation owner](../../src/GamePort/Program.cs), [Platform/history reconciliation](../../docs/compatibility.md), [Checkpoint coverage rows](../../docs/checkpoint/coverage.md) + +**Scenarios:** [fresh-natural-ordinary](scenarios.json), [fresh-skipped-edge](scenarios.json), [retained-natural-ordinary](scenarios.json), [retained-skipped-edge](scenarios.json) + +**Current applicable evidence (only the targets below):** + +- {"artifacts": [{"path": "artifacts/main-menu-player-lifetime/package-identity.json", "sha256": "6b1c7ab40f26f489d0bc272d6e2962adc257f32d42e8cd78755f5a135f512e8c", "size": 845}, {"path": "artifacts/main-menu-player-lifetime/package-verification.json", "sha256": "e8a180991c35f279726c595a70ed32c4ab06df0381d59169735edebf86554e31", "size": 2548}, {"path": "artifacts/main-menu-player-lifetime/native-control-final.log", "sha256": "46efc999b3d2d78b1eef3b3dea9d8fee188202c1556dc1d40751e6ee555f8548", "size": 1901}, {"path": "artifacts/main-menu-player-lifetime/package-control-standalone.log", "sha256": "09fa452577bbd66b9275cb83045db6b3a117913ec415f5fb6ae52e9a174790e0", "size": 1950}, {"path": "artifacts/main-menu-player-lifetime/native-control-final.returned.ppm", "sha256": "2aa0156b1ee0de50a54808cfaac8acd6b9df5c3d947c7fa4f2ee08e6a814e238", "size": 6220817}, {"missing_reason": "No usable whole-original Carl recording exists in this checkpoint", "path": "artifacts/fidelity/captures/original-carl-reference.webm"}, {"missing_reason": "Native Windows Carl recording has not been collected", "path": "artifacts/fidelity/captures/windows-native-carl-reference.webm"}], "claim": {"key": "neutral-return", "result": "First input and 300 idle ticks upright; preserved heading/body/fire; four standalone readbacks identical. Development validation zero errors; standalone validation disabled."}, "content": {"package_report_sha256": "6b1c7ab40f26f489d0bc272d6e2962adc257f32d42e8cd78755f5a135f512e8c", "runtime_sha256": "9bee85197c0d7322dc67a8c1aedbe700cf63083f91f99161dd4533c2585501e5", "verification_report_sha256": "e8a180991c35f279726c595a70ed32c4ab06df0381d59169735edebf86554e31"}, "evidence_kind": "port_fixture", "historical": true, "id": "tsk-linux-fixture-ea04210", "method": "Historical native Linux SDL/Vulkan control fixture and standalone replay, recorded report/logs; no new execution", "missing_evidence": ["No complete original Carl capture", "No current native Windows comparison"], "platform": {"execution": "native", "os": "linux"}, "reason": null, "receipt_id": "tsk-linux-fixture-ea04210", "report_path": "docs/gameplay/main-menu-player-lifetime.md", "revision": "ea04210f524faae7dc1caff8afbc608fbb8144f4", "scope": ["Carl first neutral input and 300 idle ticks; held movement return"], "status": "current", "supersedes": []} +- {"addresses": ["46BF2F..46C00A", "460A50..460A6A", "43B5A0", "46E38B/46E45A"], "artifacts": [{"path": "artifacts/main-menu-player-lifetime/source.json", "sha256": "abfeef8fb990e39e6e7f9395aae8fc8111e8038d92f5c0673a2db7505ec61070", "size": 37630}], "claim": {"key": "initial-story-order", "result": "Retained Jimmy precedes new level-game input; already corrected"}, "content": {"implementation_sha256": "2ea2e4cee3816337765b3cb4c07bc9b2a226a4c0951d0f4a7d9e2eb2f8b09e5d", "report_sha256": "956dc37ab40b0701564faf7fb227163cd1b7d118aeb73c9847c51f9f9ac61ce9"}, "evidence_kind": "static", "historical": false, "id": "tsk-source-order-ea04210", "method": "Guarded source/data report, not a new execution", "missing_evidence": ["No complete original Carl capture", "No current native Windows comparison"], "original_sha256": "f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8", "platform": {"execution": "static", "os": "source"}, "rea_evidence": "ev_0d64cc58fa8f5573fc8e61e0f2c20e36288099212bd2257d3a3121361fd6c904", "reason": "Successful TSK requires existing Jimmy; background Level1D constructs him and ordinary loader retains registry node.", "receipt_id": "tsk-source-order-ea04210", "report_path": "docs/gameplay/main-menu-player-lifetime.md", "revision": "ea04210f524faae7dc1caff8afbc608fbb8144f4", "scope": ["successful TSK story entry; direct-fresh distinction"], "status": "current", "supersedes": ["tsk-fresh-assumption-dae13ac"]} + +**Explicit applicability targets:** [{'id': 'source-order-at-ledger-import', 'content': {'report_sha256': '956dc37ab40b0701564faf7fb227163cd1b7d118aeb73c9847c51f9f9ac61ce9', 'implementation_sha256': '2ea2e4cee3816337765b3cb4c07bc9b2a226a4c0951d0f4a7d9e2eb2f8b09e5d'}, 'platform': {'os': 'source', 'execution': 'static'}, 'scope': ['successful TSK story entry; direct-fresh distinction']}, {'id': 'historical-linux-ea04210-only', 'content': {'runtime_sha256': '9bee85197c0d7322dc67a8c1aedbe700cf63083f91f99161dd4533c2585501e5', 'package_report_sha256': '6b1c7ab40f26f489d0bc272d6e2962adc257f32d42e8cd78755f5a135f512e8c', 'verification_report_sha256': 'e8a180991c35f279726c595a70ed32c4ab06df0381d59169735edebf86554e31'}, 'platform': {'os': 'linux', 'execution': 'native'}, 'scope': ['Carl first neutral input and 300 idle ticks; held movement return']}] + +
History — exact revisions and supersession retained + +- {"artifacts": [], "claim": {"key": "initial-story-order", "result": "Prior port incorrectly treated first TSK story as fresh registry order; source report explicitly corrects this"}, "content": {"implementation_sha256": "2ea2e4cee3816337765b3cb4c07bc9b2a226a4c0951d0f4a7d9e2eb2f8b09e5d", "report_sha256": "956dc37ab40b0701564faf7fb227163cd1b7d118aeb73c9847c51f9f9ac61ce9"}, "evidence_kind": "inferred", "historical": true, "id": "tsk-fresh-assumption-dae13ac", "method": "Prior narrative retained from source report; never accepted as source fact", "missing_evidence": ["No complete original Carl capture", "No current native Windows comparison"], "platform": {"execution": "static", "os": "source"}, "reason": null, "receipt_id": "tsk-fresh-assumption-dae13ac", "report_path": "docs/gameplay/main-menu-player-lifetime.md", "revision": "dae13ace7391671aee7082c662bb798b285b9124", "scope": ["successful TSK story entry; direct-fresh distinction"], "status": "superseded", "supersedes": []} +- {"artifacts": [{"path": "artifacts/main-menu-player-lifetime/package-verification.json", "sha256": "e8a180991c35f279726c595a70ed32c4ab06df0381d59169735edebf86554e31", "size": 2548}], "claim": {"key": "wine-control", "result": "Historical isolated Wine64 fixture exits 0; preliminary compatibility only"}, "content": {"package_report_sha256": "6b1c7ab40f26f489d0bc272d6e2962adc257f32d42e8cd78755f5a135f512e8c", "runtime_sha256": "24e1f01be497b920eab005608cf04c8838894d9e63404008c674990627bbc989", "verification_report_sha256": "e8a180991c35f279726c595a70ed32c4ab06df0381d59169735edebf86554e31"}, "evidence_kind": "wine", "historical": true, "id": "tsk-wine64-ea04210", "method": "Reported Wine64 fixture; not native Windows; package verification report retained", "missing_evidence": ["No complete original Carl capture", "No current native Windows comparison"], "platform": {"execution": "wine", "os": "windows"}, "reason": null, "receipt_id": "tsk-wine64-ea04210", "report_path": "docs/gameplay/main-menu-player-lifetime.md", "revision": "ea04210f524faae7dc1caff8afbc608fbb8144f4", "scope": ["32-frame packaged Carl/control fixture"], "status": "historical", "supersedes": []} + +
+ +**Player-impact discrepancies:** + +- **missing_verification** · startup-native-windows: ea04210 Wine64/cross-publish never establishes current native Windows acceptance. +- **missing_verification** · startup-original-reference: Whole-original Carl playback has not been captured; background allocation is narrower evidence. + diff --git a/docs/evidence/capabilities.json b/docs/evidence/capabilities.json new file mode 100644 index 0000000..2543f77 --- /dev/null +++ b/docs/evidence/capabilities.json @@ -0,0 +1,291 @@ +{ + "schema_version": 1, + "description": "Authoritative capability-first evidence records. All full-game and matrix acceptance remains open. Report summaries do not create new execution receipts.", + "capabilities": [ + { + "id": "startup-order", + "group": "movement", + "requirement_ids": [ + "MOVE-04", + "MOVE-05" + ], + "summary": "TSK-backed first-story input order is already corrected: retained Jimmy updates before level-game input. Direct fresh scenes keep fresh insertion order; legitimate landing bank and all movement/rotation algorithms are preserved.", + "verified_scope": "Source/data lifetime proof; historical ea04210 Linux SDL/Vulkan Carl fixture (first neutral tick, 300 idle, held return) and standalone four-readback replay. Historical Wine64 is preliminary; whole-original/native Windows comparison remains open.", + "differences": [ + "Source allocation diagnostic required an OS repaint acknowledgement and black frames/timing perturbation; it is not playable original Carl evidence.", + "Bounded fixture input is not the complete physical-input lab→VR04→lab→outside matrix. Current package924ad2f differs from ea04210; later matching readbacks do not promote all runtime bytes." + ], + "acceptance": { + "status": "open", + "remaining": [ + "Identified whole-original DxWnd Carl natural/skip and fresh/retained audiovisual comparison", + "Current native Windows and native Linux full matrix with actual input/audio and human review; 0/120 accepted obligations", + "Preserve normal landing bank, fresh direct-scene order and independent airborne behavior" + ] + }, + "source_links": [ + { + "label": "TSK source lifetime and bounded runtime receipt", + "path": "docs/gameplay/main-menu-player-lifetime.md" + }, + { + "label": "Exact implementation owner", + "path": "src/GamePort/Program.cs" + }, + { + "label": "Platform/history reconciliation", + "path": "docs/compatibility.md" + }, + { + "label": "Checkpoint coverage rows", + "path": "docs/checkpoint/coverage.md" + } + ], + "scenario_ids": [ + "fresh-natural-ordinary", + "fresh-skipped-edge", + "retained-natural-ordinary", + "retained-skipped-edge" + ], + "implementation": { + "revision": "ea04210f524faae7dc1caff8afbc608fbb8144f4", + "paths": [ + "src/GamePort/Program.cs" + ], + "status": "bounded", + "note": "story || carriedSave != null; unchanged Program source through ledger work" + }, + "targets": [ + { + "id": "source-order-at-ledger-import", + "content": { + "report_sha256": "956dc37ab40b0701564faf7fb227163cd1b7d118aeb73c9847c51f9f9ac61ce9", + "implementation_sha256": "2ea2e4cee3816337765b3cb4c07bc9b2a226a4c0951d0f4a7d9e2eb2f8b09e5d" + }, + "platform": { + "os": "source", + "execution": "static" + }, + "scope": [ + "successful TSK story entry; direct-fresh distinction" + ] + }, + { + "id": "historical-linux-ea04210-only", + "content": { + "runtime_sha256": "9bee85197c0d7322dc67a8c1aedbe700cf63083f91f99161dd4533c2585501e5", + "package_report_sha256": "6b1c7ab40f26f489d0bc272d6e2962adc257f32d42e8cd78755f5a135f512e8c", + "verification_report_sha256": "e8a180991c35f279726c595a70ed32c4ab06df0381d59169735edebf86554e31" + }, + "platform": { + "os": "linux", + "execution": "native" + }, + "scope": [ + "Carl first neutral input and 300 idle ticks; held movement return" + ] + } + ], + "evidence": [ + { + "id": "tsk-fresh-assumption-dae13ac", + "receipt_id": "tsk-fresh-assumption-dae13ac", + "evidence_kind": "inferred", + "method": "Prior narrative retained from source report; never accepted as source fact", + "revision": "dae13ace7391671aee7082c662bb798b285b9124", + "historical": true, + "content": { + "report_sha256": "956dc37ab40b0701564faf7fb227163cd1b7d118aeb73c9847c51f9f9ac61ce9", + "implementation_sha256": "2ea2e4cee3816337765b3cb4c07bc9b2a226a4c0951d0f4a7d9e2eb2f8b09e5d" + }, + "platform": { + "os": "source", + "execution": "static" + }, + "scope": [ + "successful TSK story entry; direct-fresh distinction" + ], + "status": "superseded", + "claim": { + "key": "initial-story-order", + "result": "Prior port incorrectly treated first TSK story as fresh registry order; source report explicitly corrects this" + }, + "supersedes": [], + "reason": null, + "artifacts": [], + "missing_evidence": [ + "No complete original Carl capture", + "No current native Windows comparison" + ], + "report_path": "docs/gameplay/main-menu-player-lifetime.md" + }, + { + "id": "tsk-source-order-ea04210", + "receipt_id": "tsk-source-order-ea04210", + "evidence_kind": "static", + "method": "Guarded source/data report, not a new execution", + "revision": "ea04210f524faae7dc1caff8afbc608fbb8144f4", + "historical": false, + "content": { + "report_sha256": "956dc37ab40b0701564faf7fb227163cd1b7d118aeb73c9847c51f9f9ac61ce9", + "implementation_sha256": "2ea2e4cee3816337765b3cb4c07bc9b2a226a4c0951d0f4a7d9e2eb2f8b09e5d" + }, + "platform": { + "os": "source", + "execution": "static" + }, + "scope": [ + "successful TSK story entry; direct-fresh distinction" + ], + "status": "current", + "claim": { + "key": "initial-story-order", + "result": "Retained Jimmy precedes new level-game input; already corrected" + }, + "supersedes": [ + "tsk-fresh-assumption-dae13ac" + ], + "reason": "Successful TSK requires existing Jimmy; background Level1D constructs him and ordinary loader retains registry node.", + "artifacts": [ + { + "path": "artifacts/main-menu-player-lifetime/source.json", + "sha256": "abfeef8fb990e39e6e7f9395aae8fc8111e8038d92f5c0673a2db7505ec61070", + "size": 37630 + } + ], + "missing_evidence": [ + "No complete original Carl capture", + "No current native Windows comparison" + ], + "report_path": "docs/gameplay/main-menu-player-lifetime.md", + "addresses": [ + "46BF2F..46C00A", + "460A50..460A6A", + "43B5A0", + "46E38B/46E45A" + ], + "original_sha256": "f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8", + "rea_evidence": "ev_0d64cc58fa8f5573fc8e61e0f2c20e36288099212bd2257d3a3121361fd6c904" + }, + { + "id": "tsk-linux-fixture-ea04210", + "receipt_id": "tsk-linux-fixture-ea04210", + "evidence_kind": "port_fixture", + "method": "Historical native Linux SDL/Vulkan control fixture and standalone replay, recorded report/logs; no new execution", + "revision": "ea04210f524faae7dc1caff8afbc608fbb8144f4", + "historical": true, + "content": { + "runtime_sha256": "9bee85197c0d7322dc67a8c1aedbe700cf63083f91f99161dd4533c2585501e5", + "package_report_sha256": "6b1c7ab40f26f489d0bc272d6e2962adc257f32d42e8cd78755f5a135f512e8c", + "verification_report_sha256": "e8a180991c35f279726c595a70ed32c4ab06df0381d59169735edebf86554e31" + }, + "platform": { + "os": "linux", + "execution": "native" + }, + "scope": [ + "Carl first neutral input and 300 idle ticks; held movement return" + ], + "status": "current", + "claim": { + "key": "neutral-return", + "result": "First input and 300 idle ticks upright; preserved heading/body/fire; four standalone readbacks identical. Development validation zero errors; standalone validation disabled." + }, + "supersedes": [], + "reason": null, + "artifacts": [ + { + "path": "artifacts/main-menu-player-lifetime/package-identity.json", + "sha256": "6b1c7ab40f26f489d0bc272d6e2962adc257f32d42e8cd78755f5a135f512e8c", + "size": 845 + }, + { + "path": "artifacts/main-menu-player-lifetime/package-verification.json", + "sha256": "e8a180991c35f279726c595a70ed32c4ab06df0381d59169735edebf86554e31", + "size": 2548 + }, + { + "path": "artifacts/main-menu-player-lifetime/native-control-final.log", + "sha256": "46efc999b3d2d78b1eef3b3dea9d8fee188202c1556dc1d40751e6ee555f8548", + "size": 1901 + }, + { + "path": "artifacts/main-menu-player-lifetime/package-control-standalone.log", + "sha256": "09fa452577bbd66b9275cb83045db6b3a117913ec415f5fb6ae52e9a174790e0", + "size": 1950 + }, + { + "path": "artifacts/main-menu-player-lifetime/native-control-final.returned.ppm", + "sha256": "2aa0156b1ee0de50a54808cfaac8acd6b9df5c3d947c7fa4f2ee08e6a814e238", + "size": 6220817 + }, + { + "path": "artifacts/fidelity/captures/original-carl-reference.webm", + "missing_reason": "No usable whole-original Carl recording exists in this checkpoint" + }, + { + "path": "artifacts/fidelity/captures/windows-native-carl-reference.webm", + "missing_reason": "Native Windows Carl recording has not been collected" + } + ], + "missing_evidence": [ + "No complete original Carl capture", + "No current native Windows comparison" + ], + "report_path": "docs/gameplay/main-menu-player-lifetime.md" + }, + { + "id": "tsk-wine64-ea04210", + "receipt_id": "tsk-wine64-ea04210", + "evidence_kind": "wine", + "method": "Reported Wine64 fixture; not native Windows; package verification report retained", + "revision": "ea04210f524faae7dc1caff8afbc608fbb8144f4", + "historical": true, + "content": { + "runtime_sha256": "24e1f01be497b920eab005608cf04c8838894d9e63404008c674990627bbc989", + "package_report_sha256": "6b1c7ab40f26f489d0bc272d6e2962adc257f32d42e8cd78755f5a135f512e8c", + "verification_report_sha256": "e8a180991c35f279726c595a70ed32c4ab06df0381d59169735edebf86554e31" + }, + "platform": { + "os": "windows", + "execution": "wine" + }, + "scope": [ + "32-frame packaged Carl/control fixture" + ], + "status": "historical", + "claim": { + "key": "wine-control", + "result": "Historical isolated Wine64 fixture exits 0; preliminary compatibility only" + }, + "supersedes": [], + "reason": null, + "artifacts": [ + { + "path": "artifacts/main-menu-player-lifetime/package-verification.json", + "sha256": "e8a180991c35f279726c595a70ed32c4ab06df0381d59169735edebf86554e31", + "size": 2548 + } + ], + "missing_evidence": [ + "No complete original Carl capture", + "No current native Windows comparison" + ], + "report_path": "docs/gameplay/main-menu-player-lifetime.md" + } + ], + "discrepancies": [ + { + "id": "startup-original-reference", + "impact": "missing_verification", + "summary": "Whole-original Carl playback has not been captured; background allocation is narrower evidence." + }, + { + "id": "startup-native-windows", + "impact": "missing_verification", + "summary": "ea04210 Wine64/cross-publish never establishes current native Windows acceptance." + } + ] + } + ] +} diff --git a/tests/test_fidelity_ledger.py b/tests/test_fidelity_ledger.py index ed8237b..5b9cea3 100644 --- a/tests/test_fidelity_ledger.py +++ b/tests/test_fidelity_ledger.py @@ -84,7 +84,7 @@ class LedgerTests(unittest.TestCase): for link in nav['source_links']: self.assertTrue((Path(temporary) / 'review' / link['href']).is_file()) self.assertIn('native Windows', str(nav['acceptance'])) - self.assertEqual(loaded['acceptance']['status'], 'open') + self.assertEqual(loaded['acceptance']['state'], 'open') def test_empty_ledger_fails(self): with self.assertRaises(ValueError): self.api().validate_ledger(ledger(), ROOT) diff --git a/tools/recon/fidelity_ledger.py b/tools/recon/fidelity_ledger.py new file mode 100644 index 0000000..86996d8 --- /dev/null +++ b/tools/recon/fidelity_ledger.py @@ -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']), '', + '
History — exact revisions and supersession retained', '']) + lines.extend(['- ' + _escape(json.dumps(record, sort_keys=True)) for record in row['history']] or ['- No superseded evidence recorded.']) + lines.extend(['', '
', '', '**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())