Files
VCCPlusDiagnostics/examples/sound-lab/verify_reports.py
T

167 lines
9.5 KiB
Python

#!/usr/bin/env python3
# SPDX-License-Identifier: GPL-3.0-or-later
"""Read-only post-native Sound Lab qualification checks; no emulator changes."""
from __future__ import annotations
import argparse
import hashlib
import importlib.util
import json
from pathlib import Path
import sys
from typing import Any
_MODULE = Path(__file__).resolve().parent / "host" / "soundlab_reports.py"
_SPEC = importlib.util.spec_from_file_location("soundlab_reports", _MODULE)
reports = importlib.util.module_from_spec(_SPEC)
_SPEC.loader.exec_module(reports)
def sha256(data: bytes) -> str:
return hashlib.sha256(data).hexdigest()
def disk_files(data: bytes) -> dict[str, bytes]:
"""Read all ordinary files after the host extractor validates every active chain."""
reports.extract_reports(data)
files = {}
fat = data[reports.FAT_OFFSET:reports.FAT_OFFSET + 68]
for index in range(72):
offset = reports.DIRECTORY_OFFSET + index * 32
entry = data[offset:offset + 32]
if entry[0] in (0, 0xFF):
continue
base = entry[:8].decode('ascii').rstrip(' ')
extension = entry[8:11].decode('ascii').rstrip(' ')
name = (base + ('.' + extension if extension else '')).upper()
current, chain = entry[13], []
while True:
chain.append(current)
successor = fat[current]
if successor >= 0xC0:
sectors = successor - 0xC0
break
current = successor
last_bytes = int.from_bytes(entry[14:16], 'big')
length = (len(chain) - 1) * 2304 + ((sectors - 1) * 256 + last_bytes if sectors else 0)
files[name] = b''.join(data[reports.granule_offset(g):reports.granule_offset(g) + 2304] for g in chain)[:length]
return files
def qualify(build_dir: Path) -> dict[str, Any]:
manifest_path = build_dir / 'SOUNDLAB-manifest.json'
manifest_bytes = manifest_path.read_bytes()
manifest = json.loads(manifest_bytes)
if not isinstance(manifest, dict) or not isinstance(manifest.get('artifacts'), list):
raise reports.SoundLabError('Build manifest lacks its artifact list')
artifacts = {item['filename'].upper(): item for item in manifest['artifacts']}
pristine_path = build_dir / 'SOUNDLAB.DSK'
pristine_bytes = pristine_path.read_bytes()
artifact = artifacts.get('SOUNDLAB.DSK')
if not artifact or artifact.get('sha256') != sha256(pristine_bytes) or artifact.get('bytes') != len(pristine_bytes):
raise reports.SoundLabError('Pristine SOUNDLAB.DSK does not match build manifest')
pristine = disk_files(pristine_bytes)
protected = {name: data for name, data in pristine.items() if name.endswith(('.BIN', '.BAS'))}
if not protected or 'SOUNDLAB.BIN' not in protected or 'SOUNDLAB.BAS' not in protected:
raise reports.SoundLabError('Pristine disk lacks the declared Sound Lab BIN/BAS files')
for name, data in protected.items():
if name not in artifacts:
continue
source = (build_dir / name).read_bytes()
if artifacts[name].get('sha256') != sha256(source) or artifacts[name].get('bytes') != len(source):
raise reports.SoundLabError(f'Host {name} differs from manifest artifact')
expected = source
if name.endswith('.BAS'):
# build.py uses writecocofile --newlines: a leading empty CR line,
# then every LF-terminated native source line followed by CR.
if not source.endswith(b'\n') or b'\r' in source:
raise reports.SoundLabError(f'Host {name} is not the expected LF-terminated BASIC source')
expected = b'\r' + source.replace(b'\n', b'\r')
if data != expected:
raise reports.SoundLabError(f'Pristine {name} differs from its declared build input conversion')
outcome: dict[str, Any] = {
'schema': 'vccplus.sound-lab.native-report-qualification.v1',
'build_id': manifest.get('build_id'), 'vector_set_crc16': manifest.get('vector_set_crc16'),
'manifest_sha256': sha256(manifest_bytes), 'pristine_disk_sha256': sha256(pristine_bytes),
'protected_files': {name: {'bytes': len(data), 'sha256': sha256(data)} for name, data in sorted(protected.items())},
'runs': {},
'evidence_limits': ['Native emulator checks only; no real-cartridge, FPGA or listening acceptance.',
'HUMAN=UNSURE and NOT_OBSERVED are automation input choices, not a listening verdict.',
'All source disks were read-only host inputs; no source files were modified.']}
extracted: dict[str, dict[str, bytes]] = {}
for label in ('6809', '6309', 'engineering'):
path = build_dir / 'qualification' / (label + '-reports.dsk')
raw = path.read_bytes()
contents = disk_files(raw)
for name, expected in protected.items():
if contents.get(name) != expected:
raise reports.SoundLabError(f'{label}: pristine {name} missing or changed')
selected = reports.extract_reports(raw)
if not selected:
raise reports.SoundLabError(f'{label}: no native report files')
extracted[label] = {item['filename']: item['data'] for item in selected}
run_result = {'disk_sha256': sha256(raw), 'protected_files_unchanged': True, 'reports': [],
'repeat_observed': False, 'unsure_recorded': False, 'human_heard_fabricated': False}
for item in selected:
name = item['filename']
parsed = reports.parse_report(item['data'], name)
identity_issues = reports.validate_manifest(parsed, manifest)
if not parsed['complete'] or not parsed['valid']:
raise reports.SoundLabError(f"{label}/{name}: partial/invalid report: {'; '.join(parsed['issues'])}")
if parsed['integrity'] != {'record_count': 'VERIFIED', 'checksum_crc16': 'VERIFIED'}:
raise reports.SoundLabError(f'{label}/{name}: count/checksum not both verified')
if identity_issues:
raise reports.SoundLabError(f"{label}/{name}: {'; '.join(identity_issues)}")
if parsed['metadata'].get('RUN') != name[3:7]:
raise reports.SoundLabError(f'{label}/{name}: RUN does not match filename')
case_summary = []
for case in parsed['cases']:
if case['human'] == 'HEARD':
raise reports.SoundLabError(f'{label}/{name}/{case["id"]}: native automation must not fabricate HUMAN=HEARD')
run_result['repeat_observed'] |= case['repeat'] > 0
run_result['unsure_recorded'] |= case['human'] == 'UNSURE'
case_summary.append({'case': case['id'], 'repeat': case['repeat'], 'auto': case['auto'], 'human': case['human'],
'vector_crc16': case['fields']['VECTOR_CRC16']})
run_result['reports'].append({'filename': name, 'sha256': item['sha256'], 'bytes': item['byte_count'],
'complete': True, 'integrity': parsed['integrity'], 'cases': case_summary})
if label in ('6809', '6309') and (not run_result['repeat_observed'] or not run_result['unsure_recorded']):
raise reports.SoundLabError(f'{label}: required repeat and UNSURE inputs were not recorded')
outcome['runs'][label] = run_result
for name, data in extracted['6809'].items():
if extracted['engineering'].get(name) != data:
raise reports.SoundLabError(f'Engineering continuation modified or removed original 6809 report {name}')
added = sorted(set(extracted['engineering']) - set(extracted['6809']))
if not added:
raise reports.SoundLabError('Engineering continuation did not create any additional reports')
outcome['engineering_original_reports_byte_identical'] = True
outcome['engineering_new_reports'] = added
outcome['passed'] = True
return outcome
def main(argv: list[str] | None = None) -> int:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('--build-dir', type=Path, default=Path('.build/sound-lab'))
parser.add_argument('--receipt', type=Path, help='Optional JSON receipt; no output files are written by default')
parser.add_argument('--overwrite', action='store_true', help='Explicitly replace an existing regular receipt file')
args = parser.parse_args(argv)
try:
result = qualify(args.build_dir)
if args.receipt:
inputs = [args.build_dir / 'SOUNDLAB-manifest.json', args.build_dir / 'SOUNDLAB.DSK']
inputs.extend(args.build_dir / 'qualification' / f'{label}-reports.dsk' for label in ('6809', '6309', 'engineering'))
if any(args.receipt.resolve() == path.resolve() or (args.receipt.exists() and args.receipt.samefile(path)) for path in inputs):
raise reports.SoundLabError('Receipt would replace an input')
reports.write_outputs({args.receipt: (json.dumps(result, indent=2) + '\n').encode('utf-8')}, args.overwrite)
print(f"PASS Sound Lab reports: build {result['build_id']}; " + ', '.join(f"{label}={len(run['reports'])}" for label, run in result['runs'].items()))
print('Verified complete reports, checksums/counts, manifest identities, repeated/UNSURE inputs, unchanged BIN/BAS and retained originals.')
print('No HUMAN=HEARD result or physical/listening acceptance is claimed.')
return 0
except (OSError, ValueError, KeyError, TypeError) as error:
print(f'Sound Lab report qualification failed: {error}', file=sys.stderr)
return 1
if __name__ == '__main__':
raise SystemExit(main())