# Sound Lab host reports `python3 soundlab_reports.py` requires Python 3.10 or later and only the standard library. It reads existing disk images and report files; it does not run the emulator, touch a mounted disk, contact a service or modify source inputs. ## Extract and preserve reports Quit or safely eject/save the writable diagnostic disk first, then copy it to a host working folder. Extract from that saved copy: ```sh python3 examples/sound-lab/host/soundlab_reports.py extract /path/to/SOUNDLAB.DSK \ --output /path/to/run-exports ``` The input must be a raw, single-sided, standard 35-track Disk BASIC disk image: 35 tracks × 18 sectors × 256 bytes = 161,280 bytes. DMK, images with headers and other geometries are rejected rather than guessed. Selected filenames are `SND0000.TXT` through `SND9999.TXT`, case-insensitively. Reports must have the Disk BASIC ASCII flag `FF`; the guest writes directory type 3 (text). The tool preserves every selected file's exact bytes, normalizes its output filename to uppercase, and writes `extraction.json` with the original disk's SHA-256, each report's SHA-256/byte count and its granule chain. Validation covers the directory, file type/ASCII flag, final-sector byte count, FAT values, fragmented chains, cycles, free granules in a file chain, duplicate names, unsafe names and crosslinks involving *any* active file. The directory track is excluded from granule addressing. Unclaimed FAT allocations are allowed because interrupted writes can leave them; the extractor does not repair them. It validates filesystem structure, not the authenticity of the disk's contents. An existing output is never replaced implicitly. Prefer a fresh output folder for each run. `--overwrite` permits replacement of ordinary output files only; symlinks, inputs and hardlinks to inputs are still rejected. Keep the source `.DSK` and extracted `.TXT` as original evidence. The extractor never reformats, repairs or writes back to the disk. ## Convert and compare ```sh python3 examples/sound-lab/host/soundlab_reports.py convert \ /path/to/run-exports/SND0001.TXT --output /path/to/readable-run \ --manifest .build/sound-lab/SOUNDLAB-manifest.json python3 examples/sound-lab/host/soundlab_reports.py compare \ /path/to/vcc/SND0001.TXT /path/to/real-coco/SND0001.TXT \ --output /path/to/comparison \ --manifest .build/sound-lab/SOUNDLAB-manifest.json ``` Conversion writes JSON, CSV and a self-contained readable HTML file. The JSON retains all recorded run metadata and per-case fields; CSV keeps raw timing/status fields as columns. The HTML escapes report text and includes no scripts or remote assets. No audio files or listening claims are manufactured. The optional authoritative manifest has this supported structure (other fields such as artifact hashes may also be present): ```json { "build_id": "BUILD-IDENTITY", "vector_set_crc16": "1234", "vectors": [{"case_id": "TON01-A", "crc16": "7ABC"}] } ``` The vector list may alternatively be an object such as `"vectors": {"TON01-A": "7ABC"}`. CRC values in the manifest may be four-digit hex strings, strings prefixed with `0x`, or JSON integers. Use ordinary four-digit hex in report records. Uppercase manifest keys `BUILD_ID` and `VECTOR_SET_CRC16` are accepted aliases. A manifest binds the guest's short build and vector IDs to the host build receipt; a CRC is not a cryptographic signature. The separate artifact hashes establish which binary/disk bytes were built. Comparison requires the same nonempty `BUILD_ID`, `VECTOR_SET_CRC16` and matching per-case `VECTOR_CRC16`. With a manifest, both reports must match its declared identities too. Without one, the result explicitly states `identity_basis=REPORT_CLAIMS_ONLY`. Different/missing identities, missing cases, partial reports or failed integrity checks produce `NOT_COMPARABLE`, with the recorded evidence still shown. Comparable cases show `SAME` or `DIFFERENT` and list differing metrics, raw status, timings or notes. Matching these values does **not** establish matching audible output or equal analog timing precision. `AUTO` and `HUMAN` are separate columns. `AUTO=OBSERVED` never becomes `HUMAN=HEARD`. Missing outcomes remain `UNKNOWN`; unknown timing resolution stays unknown. The tool checks report consistency and identities; it does not certify the author's automatic verdict or make hardware pass/fail assertions. Exit status is 0 for successful valid conversion/comparison or extraction, 1 for an unreadable/unsupported input or refused output, and 2 when result files were written but evidence is partial, invalid or not comparable. Inspect the JSON/HTML issues instead of treating exit 2 as a completed run. Optional absent checksum or count fields are explicitly `NOT_PROVIDED`, never `VERIFIED`. ## SOUNDLAB-1 record contract The first nonblank line is exactly `FORMAT=SOUNDLAB-1`. Subsequent ordinary lines contain space-separated `KEY=VALUE` tokens with uppercase keys and nonempty values. Values containing whitespace belong in escaped `NOTE` records. CRLF is preferred; LF is accepted. Bare CR, non-ASCII bytes and unescaped control characters are rejected. Empty/whitespace-only lines are ignored for record counts and checksums. Unknown metadata and per-case keys are retained for forward-compatible evidence. A different `FORMAT` requires a new parser version. A header declares the run, target and build/vector identity. A case starts with `CASE=... VECTOR_CRC16=HHHH AUTO=... HUMAN=...`; subsequent lines carry its metrics. `ENDCASE` must match that case's identity. A per-case `REPEAT=0` field identifies the first attempt, `REPEAT=1` the next, and so on. Each `(CASE, REPEAT)` pair must be unique within a report. Omitted `REPEAT` defaults to 0 for early SOUNDLAB-1 compatibility. Attempts are retained separately in JSON/CSV/HTML and compared by that pair, even if recorded in a different order. An interrupted case/run is preserved and marked incomplete. Case IDs and outcome enumerations compare case-insensitively; the original text/fields remain available. Allowed automatic values: `PASS`, `FAIL`, `OBSERVED`, `TIMEOUT`, `NOT_RUN`, `NOT_APPLICABLE`. Allowed human values: `HEARD`, `WRONG`, `NO_SOUND`, `UNSURE`, `NOT_OBSERVED`, `SKIPPED`. An optional note consists of two consecutive records inside a case: ```text NOTE_LENGTH=18 NOTE=FIRST LINE\nSECOND!\n ``` `NOTE_LENGTH` counts decoded ASCII **bytes**, not the serialized escape length. Escapes are `\\`, `\n`, `\r`, `\t` and `\xHH` (ASCII 00–7F). `NOTE=` consumes the rest of its line, including spaces. Length mismatch, unknown escapes, a dangling length or a note outside a case is reported as invalid/incomplete evidence. A finished run ends with one footer, with no following nonblank records: ```text ENDRUN=0001 COMPLETE=YES RECORD_COUNT=8 CHECKSUM_CRC16=1234 ``` The run number must match `RUN`. `COMPLETE=NO` explicitly retains an interrupted run. Footer integrity fields are optional for interoperability; the diagnostic writer supplies both. `RECORD_COUNT` is the number of preceding nonblank lines, including `FORMAT` and every case, note and `ENDCASE` line, excluding the footer. `CHECKSUM_CRC16` is CRC-16/CCITT-FALSE: polynomial `1021`, initial `FFFF`, no reflection, no final XOR. It covers those same original nonblank lines joined with CRLF, **including a final CRLF**, and excludes the footer. Lowercase and uppercase hex are equivalent. Example footer values above are schematic. ## ROM-free checks ```sh python3 -m unittest discover -s examples/sound-lab/tests -p test_reports.py -v ``` The authored fixtures cover fragmented disks across the reserved track, full sectors/granules, truncation, malformed FAT and loops/crosslinks, report end markers, notes, count/checksum validation, independent outcome comparisons, manifest identities, raw metric differences and output preservation. They use no private ROMs, real reports or actual hardware recordings.