16 — The tools: 220 in the box, 5 written today, 3 repaired, and one that was retired yesterday and un-retired this morning
Measure: every .py file in tools/ classified into exactly one class, with
the classification asserted rather than eyeballed. toolclass.py refuses to
print its table if any file is unclassified or classified twice, and it refused
twice this session before the classes were rewritten.
python tools/toolclass.py
tools/*.py on disk : 220
tools named in a class : 220
distinct tools classified : 220
| class | count |
|---|---|
| written for this object | 5 |
| inherited, repaired or extended for this object | 3 |
| inherited and used unmodified | 22 |
| inherited, superseded by something written this session | 47 |
| inherited, applicable here, not needed | 71 |
| inherited and misleading here | 45 |
| does not apply: no Macintosh side, no installation, no hybrid volume | 27 |
| total | 220 |
72 of 220 — 32.7 % — would not apply or would mislead on this object. That is the ordinary rate for this collection and it is printed every session for the same reason: a toolbox that only reports its successes is a toolbox that has stopped being audited.
Every one of them exists because this object is two discs, or because a CAPCOM container on it had no reader anywhere.
discpair.py — the session. It partitions the union of two trees into four
disjoint classes — identical by hash, same path with different bytes, only on A,
only on B — and asserts that the partition closes on both sides before it
prints anything. It takes a rename map on the command line, because PL0 and
PL1 are the structural counterparts of each other and comparing them under
their own names would report a hundred per cent divergence between directories
that are 2.6 % the same. The map is printed in the output so the reader can see
which comparison was made. It is also what found the briefing's largest error:
the claim that forty-nine COMMON files differ between the discs, where the
truth is zero.
sapread.py — a reader for a container that had to be derived. Eight bytes,
then one or more self-delimiting RIFF….WAVE chunks. The finding is that the
first dword is a bit mask rather than a count — WEAPON01.SAP carries 481,
which has five bits set, and holds five streams — and the tool asserts
popcount(mask0) + popcount(mask1) == streams walked on every file. It passes on
1,495 of 1,495. Behind it is a Microsoft ADPCM decoder written from the
published definition, reading the seven coefficient pairs out of each file's own
fmt chunk rather than hard-coding them, vectorised across blocks (which are
independent) and checked against a scalar reference before any census runs:
validate: …/WEAPON01.SAP
vectorised block == scalar reference 19/19
If that check fails, the tool refuses to census.
binindex.py — classifies .BIN by signature rather than by name, because
on this object .BIN is 55.7755 % of the product and is six unrelated things.
For the one of the six that is an indexed archive it derives and verifies the
offset table, requiring table bytes + payload bytes = file size with residue 0.
It found three different padding conventions where the first file opened showed
one, and it reports the convention per file instead of assuming it.
emdhead.py — derives the model container from the population rather than
from one file, by testing a single equation on every member of three extensions,
and separates two claims that are usually conflated: the TMD magic bytes are
present (139 of 169 files) and a TMD header validates there (0 of 169).
On this object those give different answers, which is the whole point.
dirclock.py — exists because yesterday's seconds-parity proof does not work
here and something had to replace it. It asks two questions of a volume — does
the mastering program's own clock ever emit an odd second, and are the directory
records dated before the burn — and declines to conclude anything when neither
test fires. On these discs the first fires and the second refutes the
hypothesis it was built to support, which is the best a test can do.
Each repair carries an assertion that fails loudly. None of them was patched without one.
recdates.py read the ISO 9660 user area at offset 16. That is Mode 1. In
Mode 2 Form 1 the payload begins at 24, after eight bytes of subheader, so the
tool read eight bytes of subheader plus 2,040 bytes of payload, found no CD001
anywhere, and stopped with no primary volume descriptor. It now derives the
offset from sector zero's own mode byte and refuses to guess if the byte is
neither 1 nor 2. Regression-tested against the Mode 1 disc it was written for:
still 3,436 records, still 1,102 distinct timestamps, still 798 at midnight.
threeclocks.py is the dangerous one and it failed in the way this branch
keeps warning itself about. It keyed clock A on the raw ISO file identifier,
which carries the version suffix ;1; every extractor in this repository strips
that suffix; so nothing matched, and the tool's response to matching nothing was
to substitute the extracted files' filesystem mtime and print a full page of
results:
records matched: 0 of 2194; 2194 fell back to the filesystem mtime
directory clock spans : 2026-09-01 23:04:51 .. 2026-09-01 23:04:55 0 days
REGIST/DIRECTX/DRIVERS/ENG/TMV1.MPD A 2026-09-01 B 1995-06-30 -11386 days
Every figure in it was a comparison between a 1995 driver and the moment of extraction, and every one of them was formatted to three decimal places. The repair normalises the key and adds a refusal: if an image was named and not one of its records attached, the tool dies rather than print. After it, 2,194 of 2,194 and 2,224 of 2,224 attach, and both numbers are quoted in 02 so a reader can check that the page below them means anything.
avicheck.py counted 00dc and 00db, which is what Video for Windows
writes and what every reader expects. Indeo 5 on this object writes 00iv.
Unchanged, the tool reported frames counted in movi: 0 … DISAGREE on 32 files
of 32 — a number, formatted correctly, meaning nothing. It now takes the stream
index from the header, counts every chunk belonging to the video stream, and
prints the full inventory of chunk ids it saw so that the next unfamiliar
fourcc is visible rather than silently zero:
movi chunk ids, all files : 00iv x30335, 01wb x24626, JUNK x106
rawcensus.py and xa.py were written for Mode 2 Form 1. Yesterday, on a Mode 1
disc, rawcensus.py --validate verified its own arithmetic on 64 of 64 sectors
and matched the disc on 0 of 64, because Mode 1 computes its error-detection
code over bytes 0..2063 and Mode 2 Form 1 over 16..2071. It was superseded by
mode1.py, written that afternoon.
Today both discs are Mode 2 Form 1 and rawcensus.py runs unmodified, passing
both halves of its self-check at the first attempt and censusing 629,766 sectors
with zero mismatches of any kind. mode1.py, twenty-four hours old, is
inapplicable and was not adapted — adapting it would have produced a second
tool that does what the first one already does correctly.
A tool in this box has now been retired and un-retired inside two consecutive sessions. It is the first time, it is worth exactly one paragraph, and the reason it is worth that paragraph is that it is evidence the toolbox measures discs rather than carrying opinions about them.
This is the class the collection keeps for its own protection, and this session produced four unusually clean specimens.
| tool | what it would have said | how it fails |
|---|---|---|
mode1.py |
nothing — no CD001 at offset 16 |
loudly, by one byte in each of 629,766 sectors |
avicheck.py |
0 frames, DISAGREE on 32 of 32 |
silently, with a number |
threeclocks.py |
a page of 2026 dates | silently, with confidence |
pakdec.py |
ValueError on 224 of 224 .ADT |
loudly, and honestly |
Two loud, two silent, and the two silent ones are the ones that cost time. The
rule the branch has arrived at, after three sessions of this, is the one written
into threeclocks.py's new assertion: a tool that finds nothing is not a tool
that says zero, and the number of records it attached has to be printed above
the results, not inferred from them.
pakdec.py deserves its own sentence because its failure is the useful kind.
It decompressed 1,112 of 1,112 files with residue zero yesterday and raises
ValueError on all forty .ADT files tried here. That is not a defect; it is
the tool correctly reporting that .ADT is a different algorithm from .PAK
despite sharing a role, a directory and the RC#### naming scheme. Its
method — entropy, four-byte repeats, size alignment, tail periodicity, the
first nine bits — is what was reused in 08, and four of
its five indicators fired. Its code was not.
authenticode.py earns a footnote too. Pointed at every .BIN on the disc,
including the 222 that are not executables, it read arbitrary bytes as a
certificate directory and reported tables of 2,210,490,023 bytes at offset
719,977,532 in a 258,359-byte file. It was then pointed only at files
pecensus.py confirms are PE, and reported three signed binaries on Leon and two
on Claire. The tool is not wrong — it was given a file that is not a PE — but a
tool that produces a nine-digit certificate table from a TIM is a tool whose
inputs need a gate, and the gate is now in the command line rather than in the
tool.
Each one asserts something and dies rather than print a plausible table:
| tool | the assertion |
|---|---|
discpair.py |
identical + same-name + only-A == files(A), and the mirror for B |
sapread.py |
vectorised decoder == scalar reference, before any census; then popcount(mask) == streams per file |
binindex.py |
table bytes + payload bytes == file size, residue 0, per archive |
emdhead.py |
dword0 == size − 4×dword1 on every file of a family, or it is a coincidence and is reported as one |
dirclock.py |
neither test fired → prints "proves nothing either way" and stops |
And two inherited ones gained a contract they did not have:
| tool | the new assertion |
|---|---|
recdates.py |
sector 0's mode byte is 1 or 2, or refuse to guess the user-area offset |
threeclocks.py |
at least one directory record attached, or refuse to print |