#!/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())