damage: files can be broken on purpose, and something has to refuse them

[donislawdev]

The tool answered questions about size and about name. It did not answer the third question an upload validator asks - does it open - because every file it wrote was well formed by definition.

targets:
  - id: broken-uploads
    format: png
    size: 20kb
    damage: [zero-head]

tfg generate --format png --size 20kb --damage zero-head:bytes=16

The file still comes out exactly the size asked for. The manifest records what was done and says the file is expected to be rejected.

Three things the architecture note got wrong

Each changed the design, not only the prose. All three were found by measuring rather than by reading.

A witness is not a property of the pair. It is a function of (format, damage, size, parameter values):

	20 kB	300 B	4 B
zero-head (8 B)	24/24	9/9	2/2
truncate-half	22/24	8/9	0/2

bytes zeroed	witnesses of 24
1	20
2	20
4	24

That is why bytes starts at 4. The bound belongs to somebody else's reader, the same rule the column ceiling followed.

"The comparison is free because we compute the checksum anyway" was false. The write path computes ONE checksum, so before-and-after would cost a second sha256 per file. The damage knows for free instead - zero-head has to read the bytes before it overwrites them. So the damage answers, not the engine, and it answers per step because two damages can cancel out.

Reachable rather than theoretical: ico, avif and jxl all begin with zero bytes, so a small zero-head on them really is idle.

The expected collision was settled nowhere. The regression surface says an expectation from a recipe reaches the manifest unchanged; the note said reject is set automatically. It is now a refusal, and only for accept - sanitize and unspecified are both sensible questions about a broken file.

Where it sits

generator -> DAMAGE -> counter -> MultiWriter( buffered -> file, h )

Three things fall out without being built: the checksum describes the bytes on disk, the existing counter.n != Plan.Bytes check counts the FINAL bytes, and progress counts what will really be there.

Evidence

• 16 guards, 17 mutations, all caught. The one worth naming is the reverse of every other oracle guard here: it asks whether a judge REFUSES what we wrote, and its control runs first, because without it the test passes for a build whose judge refuses everything.
• Full suite green, ok internal/guard 264.4s. journey.py 300 of 300.
• D1 parity: the not-reachable list went from 11 to 10 rather than growing - the window offers the menu, draws the parameters from the declaration, and a guard presses it and reads the bytes back.
• A run with no damage is untouched: the manifest key is absent rather than empty, and manifest_version stays 1.0.

What this cost, and it is worth reading

Three types would have grown past the crowding band, and that count only goes down. Two of them became better shapes anyway: SizeIsRange, SizeMin and SizeMax were always one statement, so engine.Target and recipe.Target now carry a SizeRange.

⚠ That refactor invalidated six mutation entries and only staleness.py said so. A pattern that no longer matches reports SKIP, which reads as proven. Re-targeted and re-run: 20 entries across 12 guards, all still caught.

⚠ One of my own new mutations came back NOT CAUGHT, and it was a statement about the mutation rather than the code - it targeted Error(), which a recipe never calls, because a recipe reports through What/Why/Instead.

Known limits, written down rather than left to be found

• No tfg damage command. The first version of the flag help pointed at one, which was a promise of something that does not exist - the help now lists the names from the registry instead. The real asymmetry stays: the window draws a damage's parameters, the command line shows only names. First thing for stage 2.
• The window takes one damage. The chain carries more and a recipe writes more.
• truncate, the flipped bit, format-aware damage and archive members are all out of stage 1, with reasons in the document.

Analysis, measurements and everything not checked: docs/CORRUPTION-ARCHITECTURE-2026-09-08.md, sections 13 and 14.

🤖 Generated with Claude Code