Write the Test Manual, and make the suite check it

The test system had grown to seven scripts making five genuinely different
kinds of claim, and nothing said which was which. A recorded transcript and a
byte-for-byte comparison against a second implementation both print [ok  ] and
are worth wildly different amounts, so the fourth manual exists to say so: what
each script can and cannot answer, why every determinism rule is there, how to
add a test, and - the part written nowhere else - where the suite is blind.

That last section is the reason for the document. Three buffer overruns into
adjacent variables were all found by a person using the machine and none by the
suite, the sanitizers cannot see them because emulated Data Memory is one
legitimate host array, and there is no second opinion about the CPU at all. A
document listing only strengths teaches the wrong lesson.

The bullets describing each script move out of the README, so docs.sh now reads
the manual for them, and five more numbers in it are settled from the source
rather than trusted: the shape of the manifest, the xfail count, how many
fixture disks makedisks.sh builds, how large the lint baseline is, and the tool
count in either document. Each of the new checks was broken on purpose and
watched to report before being kept, which is the discipline the manual itself
argues for.

Also drops the stale "70 instructions" from instructiontable.py's docstring.
There are 72, and a number that carries no meaning is better removed than
corrected.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E2JrLzFvuFX9fgi1LDRjrW

This commit is contained in:

Anachronaut

2026-08-27 23:52:12 -04:00

co-authored by

Claude Opus 5

parent 79727044b7

commit d6bc416698

4 changed files with 572 additions and 47 deletions

									
										Tests/instructiontable.py
									
		+1
		-1
	
												View File
												
				@@ -1,7 +1,7 @@

				#!/usr/bin/env python3

				"""The instruction table, as the assembler has it.

				The monitor needs the same 70 instructions the assembler does, with the same names and the

				The monitor needs the same instructions the assembler does, with the same names and the

				same lengths, and a disassembler that disagreed with the assembler about how long an

				instruction is would not merely print one thing wrong - it would lose its place and print

				everything after it wrong too. So the table is generated from assembly.c rather than typed