A listing says what is left of the disk, and what will fit

dir said what was there and nothing about what was left. SplitDisk has
printed the free figure since it was written, so the machine's own
listing was the poorer of the two implementations at describing the same
disk.

  43 files, 3 directories
  46 of 64 entries, 1893 blocks free

Entries first, because they are the ceiling nobody notices until they hit
it: a disk of small files runs out of directory slots long before it runs
out of blocks.

COUNTED RATHER THAN ASKED. The superblock keeps a free count and this
file calls it "a note rather than the truth" in three places. sbfsSpace
reads the whole directory table instead, which costs a read per directory
block and is the answer rather than a guess. SplitDisk goes on reading
the note and saying when it is stale, which is the right place for that
check - the host tool is what you audit a disk with.

---- And it is a fact about the disk, not about where you are ----

The first version added the blocks up as the LISTING walked past them,
which cost no extra read and was wrong: that walk stops only on entries
in the working directory, so the same disk came out as 1,996 blocks free
from the root and 2,025 from /Apps. Comparing against SplitDisk is what
said so, which is what having two implementations is for.

---- The longest run, which is what decides whether a file fits ----

  4 of 16 entries, 37 blocks free
  the longest run is 25

Files are laid down contiguously, so the free total does not say whether
a file will fit. Both implementations learn it, from one specification.

Said only when it differs from the free total. Deleting is what fragments
a contiguous store, and a disk that has only been appended to has one gap
at the end - so on a healthy disk this is silent, and a line that appears
only when something is wrong is a line somebody reads.

There is no sort on this machine and the entries are in no order, so a
candidate walks the disk: each pass finds the used extent nearest at or
after it, and anything the candidate stands inside pushes it to the far
end and starts the pass again. The same trick allocating uses. So it
costs a pass per gap rather than per file - nearly nothing on a disk with
one gap, more the more fragmented the disk is, which is the right way
round.

holes.img is six files with the second and fourth deleted, because no
other disk here can show any of this: none of them has ever had anything
deleted from it.

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

Programs/CosmOS/README.md

@@ -693,6 +693,55 @@ compares the images byte for byte. Every field one writes and the other only rea
 checked there and nowhere else: which entry a thing lands in, which block, what a
 directory's unused fields hold, the version, the free count.
 
+### What A Listing Says About The Disk:
+
+`dir` ends with what is there and what is left:
+
+```text
+43 files, 3 directories
+46 of 64 entries, 1893 blocks free
+```
+
+**Entries come first because they are the ceiling nobody notices until they hit it.** A disk
+of small files runs out of directory slots long before it runs out of blocks, and saying both
+means never having to work out which one is about to bite.
+
+**The free figure is counted, not asked for.** The superblock keeps a free count and
+`sbfs.asm` calls it *"a note rather than the truth"* in three separate places; `sbfsSpace`
+reads the whole directory table instead, which costs a read per directory block and is the
+answer rather than a guess. SplitDisk reads the note as well and says so when the two
+disagree, which is the right place for that check: the host tool is what you audit a disk
+with, and this is what you work on one with.
+
+**And it is a fact about the disk, not about where you are standing.** The first version of
+this added the blocks up as the listing walked past them, which cost nothing extra and was
+wrong - that walk stops only on entries in the working directory, so the same disk came out as
+1,996 blocks free from the root and 2,025 from `/Apps`. The two implementations of this format
+disagreeing is what said so.
+
+A third line appears when it needs to:
+
+```text
+4 of 16 entries, 37 blocks free
+the longest run is 25
+```
+
+**Files are laid down contiguously**, so the free total is not what decides whether a file
+will fit - the longest unbroken run is. A disk with a thousand blocks free in ten pieces
+refuses a file of two hundred, and nothing else in the listing would hint at it.
+
+**It is said only when it differs from the free total**, which on a healthy disk it does not.
+Deleting is what fragments a contiguous store, and a disk that has only been appended to has
+one gap, at the end. A line printed under every listing saying the same number twice is noise;
+one that appears only when something is wrong is a line somebody reads.
+
+Finding it costs a pass of the directory table per gap. There is no sort on this machine and
+the entries are in no order, so a candidate walks the disk instead: each pass looks for the
+used extent nearest at or after it, and anything the candidate is standing inside pushes it to
+the far end and starts the pass again - the same trick allocating uses, for the same reason.
+So the measurement costs almost nothing on a disk with one gap and more the more fragmented
+the disk is, which is the right way round: it is slow exactly when it has something to say.
+
 ### Starting An Application By Name:
 
 A word the shell has no command for is not immediately an error. Before saying so, the