158 lines
7.8 KiB
Markdown
158 lines
7.8 KiB
Markdown
# 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.
|