Files

158 lines
7.8 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.