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

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.

A target now takes damage, as a list from the first day because composition is
a requirement rather than an extension:

    damage: [zero-head]
    damage: [{type: zero-head, bytes: 16}]

and on the command line --damage zero-head:bytes=16, repeatable and applied in
the order given. The file still comes out exactly the size asked for. The
manifest records what was done to it and says the file is expected to be
rejected.

zero-head is the one damage in this build. It was chosen because all twenty
four formats have a judge that refuses the result and because it does not
change the length, so it does not touch the size arithmetic.

Three things the architecture note said turned out to be wrong, and each
changed the design rather than only the prose.

A witness is not a property of the pair (format, damage). It is a function of
the format, the damage, the SIZE and the parameter VALUES. Measured:
truncate-half has witnesses at 20 kB and none at 4 B, and zeroing one byte has
20 witnesses of 24 where four bytes have all of them. That is why the bytes
parameter 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 whether it moved
anything, not the engine - and it answers per step, because two damages can
cancel out. Measured that this is reachable rather than theoretical: ico, avif
and jxl all begin with zero bytes.

The collision between an automatic expectation and one written in a recipe was
settled nowhere. It is now a refusal, and only for accept: reject is what
damage means, while sanitize and unspecified are both sensible questions about
a broken file.

Damage sits between the generator and the counter, which gives three things
without building them: the checksum describes the bytes on disk, the existing
size check counts the FINAL bytes, and progress counts what will really be
there.

Nineteen guards, nineteen 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.

Three types moved state out rather than growing past the crowding band, and one
of them turned out to be a better shape 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.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: donislawdev

.github/workflows/ci.yml

@@ -600,7 +600,7 @@ jobs:
         # in somebody else's file.
         run: |
           set -euo pipefail
-          watched='internal/format/registry.go cmd/tfg/main.go internal/gui/window/run.go internal/audit/parallel.go internal/engine/parallel.go go.mod'
+          watched='internal/format/registry.go internal/damage/damage.go cmd/tfg/main.go internal/gui/window/run.go internal/audit/parallel.go internal/engine/parallel.go go.mod'
           # On a pull request there is no "before" - the field belongs to a push
           # - so this asked for something empty and every pull request answered
           # "touched". That quietly undid the decision of 2026-08-20, because

CHANGELOG.md

@@ -58,6 +58,44 @@ because it turns other people's test suites red.
 
 ### Added
 
+- **Files can be broken on purpose.** A target takes `damage`, and the files it
+  produces are ones a reader refuses:
+
+  ```yaml
+  targets:
+    - id: broken-uploads
+      format: png
+      size: 20kb
+      count: 10
+      damage: [zero-head]
+  ```
+
+  or from the command line, repeatable and applied in the order given:
+
+  ```
+  tfg generate --format png --size 20kb --damage zero-head:bytes=16
+  ```
+
+  Until now every file this tool wrote was well formed, so the third question
+  an upload validator asks - "does it open" - was one nothing here could put to
+  it.
+
+  The file still comes out **exactly** the size you asked for. What changes is
+  the content, and the manifest records what was done to it and says the file
+  is expected to be rejected.
+
+  There is one damage in this release, `zero-head`, which overwrites the
+  opening bytes with zeros. It was chosen because all twenty four formats have
+  something that refuses the result - measured, not assumed - and because it
+  does not change the length. `tfg formats` is unchanged and no existing file
+  moves a byte: a run that does not ask for damage goes down the path it always
+  did.
+
+  Two things it refuses rather than doing quietly. A file smaller than the
+  damage is refused before anything is written, naming a size that would work.
+  And a damage that would leave the bytes untouched stops the run, because a
+  whole file described as broken is worse than no file at all.
+
 - **HTML files can be a fragment instead of a whole page.** A new setting on
   `html`: `structure`, which takes `document` or `fragment`. It defaults to the
   whole page these files have always been, so a recipe that says nothing gets

internal/cli/cli.go

@@ -16,6 +16,7 @@ import (
 	"strings"
 	"syscall"
 
+	"github.com/donislawdev/TestingFilesGenerator/internal/damage"
 	"github.com/donislawdev/TestingFilesGenerator/internal/engine"
 	"github.com/donislawdev/TestingFilesGenerator/internal/format"
 	_ "github.com/donislawdev/TestingFilesGenerator/internal/format/all"
@@ -268,6 +269,70 @@ func (p propertyFlag) Set(v string) error {
 	return nil
 }
 
+// repeatedFlags are the flags a person may write more than once.
+//
+// One piece rather than two fields on the options struct, because the type was
+// at the crowding band and the answer to that is to move state out. They belong
+// together anyway: both map onto a block of a recipe rather than onto a single
+// line of one.
+type repeatedFlags struct {
+	props  propertyFlag
+	damage damageFlag
+}
+
+// damageFlag collects repeated --damage entries, in the order they were given.
+//
+// A list rather than a map, which is the difference from --set beside it:
+// order is part of what a chain of damages means, and the same damage twice
+// with different settings is a legitimate thing to ask for. --set refuses a
+// repeat because one of two values would be lost silently, and here neither is.
+//
+// The settings ride after a colon so one entry stays one argument:
+//
+//	--damage zero-head
+//	--damage zero-head:bytes=16
+//	--damage zero-head:bytes=16,other=2
+type damageFlag struct{ chain damage.Chain }
+
+func (d *damageFlag) String() string { return d.chain.String() }
+
+func (d *damageFlag) Set(v string) error {
+	id, settings, hasSettings := strings.Cut(v, ":")
+	if id == "" {
+		return fmt.Errorf("expected the name of a damage, got %q", v)
+	}
+	values, err := damageSettings(id, settings, hasSettings)
+	if err != nil {
+		return err
+	}
+	d.chain = append(d.chain, damage.Spec{ID: id, Values: values})
+	return nil
+}
+
+// damageSettings reads the name=value pairs after the colon.
+//
+// Its own function rather than a block inside Set, because the shape gates
+// count how deep a reader has to follow and this was the third level.
+func damageSettings(id, settings string, stated bool) (damage.Values, error) {
+	values := damage.Values{}
+	if !stated {
+		return values, nil
+	}
+	for _, pair := range strings.Split(settings, ",") {
+		key, value, found := strings.Cut(pair, "=")
+		if !found || key == "" {
+			return nil, fmt.Errorf("expected name=value after the colon, got %q", pair)
+		}
+		if _, exists := values[key]; exists {
+			// The same reason --set gives: one of the two would be lost and
+			// nobody would know which.
+			return nil, fmt.Errorf("%s is set more than once on %s", key, id)
+		}
+		values[key] = value
+	}
+	return values, nil
+}
+
 // args2 rebuilds the command as it would have to be typed to run again.
 //
 // It goes into the manifest, where its whole job is to be re-runnable, and it

internal/cli/errors.go

@@ -12,6 +12,7 @@ import (
 	"syscall"
 
 	"github.com/donislawdev/TestingFilesGenerator/internal/audit"
+	"github.com/donislawdev/TestingFilesGenerator/internal/damage"
 	"github.com/donislawdev/TestingFilesGenerator/internal/engine"
 	"github.com/donislawdev/TestingFilesGenerator/internal/format"
 	"github.com/donislawdev/TestingFilesGenerator/internal/manifest"
@@ -201,6 +202,21 @@ func classifyRequest(err error) (int, bool) {
 	if errors.As(err, &unknownPreset) {
 		return ExitUsage, true
 	}
+	// A damage this build does not know is a typo in the invocation, the same
+	// class as an unknown preset - a recipe naming one is refused while the
+	// recipe is read, so anything reaching here came off the command line.
+	var unknownDamage *damage.UnknownError
+	if errors.As(err, &unknownDamage) {
+		return ExitUsage, true
+	}
+	// A file smaller than the damage it was given is the same class as a size
+	// below a format's minimum: the request is well formed and nothing here can
+	// deliver it. It gets the same code for that reason rather than by
+	// resemblance.
+	var tooSmall *damage.TooSmallError
+	if errors.As(err, &tooSmall) {
+		return ExitFormat, true
+	}
 	if code, ok := classifyFormat(err); ok {
 		return code, true
 	}

internal/cli/generate.go

@@ -11,6 +11,7 @@ import (
 	"strings"
 
 	"github.com/donislawdev/TestingFilesGenerator/internal/core"
+	"github.com/donislawdev/TestingFilesGenerator/internal/damage"
 	"github.com/donislawdev/TestingFilesGenerator/internal/engine"
 	"github.com/donislawdev/TestingFilesGenerator/internal/format"
 	"github.com/donislawdev/TestingFilesGenerator/internal/manifest"
@@ -37,7 +38,11 @@ type generateOpts struct {
 	clean          bool
 	dryRun         bool
 	asJSON         bool
-	props          propertyFlag
+	// The flags a person may write more than once, in one piece rather than
+	// two fields. They are one thing on the screen and one thing in a recipe -
+	// what was stated repeatedly - and grouping them is what moving state out
+	// means when a type is at the crowding band.
+	repeated repeatedFlags
 }
 
 func generateFlagSet(errOut io.Writer, g *generateOpts) (*flag.FlagSet, func(io.Writer)) {
@@ -65,8 +70,19 @@ func generateFlagSet(errOut io.Writer, g *generateOpts) (*flag.FlagSet, func(io.
 	// Twenty five formats with a dozen properties each would give a surface
 	// nobody reads in --help, and this maps one to one onto the properties
 	// block of a recipe, so both surfaces speak the same words.
-	g.props = propertyFlag{}
-	fs.Var(&g.props, "set", "format property, repeatable: --set width=1920 --set height=1080")
+	g.repeated.props = propertyFlag{}
+	fs.Var(&g.repeated.props, "set", "format property, repeatable: --set width=1920 --set height=1080")
+
+	// Repeatable like --set, and for the same reason, but a list rather than a
+	// map: the order damages are applied in is part of what they mean.
+	// The names come from the registry rather than being typed here. The first
+	// version of this line ended "run tfg damage to see what there is" and
+	// there is no such command - a sentence in shipped help promising
+	// something that does not exist, which is the class this project calls
+	// prose with an expiry date. Built from Names() it cannot say that again.
+	fs.Var(&g.repeated.damage, "damage", "break the files on purpose, repeatable and applied in order: "+
+		"--damage zero-head, or --damage zero-head:bytes=16. This build has: "+
+		strings.Join(damage.Names(), ", "))
 
 	usage := func(w io.Writer) {
 		fmt.Fprint(w, `tfg generate - produce files.
@@ -312,15 +328,14 @@ func targetsFromFlags(g *generateOpts, given map[string]bool, errOut io.Writer)
 		ID:             g.id,
 		Format:         g.formatID,
 		Sizes:          sizes,
-		SizeIsRange:    g.sizeRange != "",
-		SizeMin:        rangeLow,
-		SizeMax:        rangeHigh,
+		Range:          engine.SizeRange{Used: g.sizeRange != "", Min: rangeLow, Max: rangeHigh},
 		BoundaryLimit:  boundaryLimit,
 		NameTmpl:       g.name,
 		Label:          !g.clean,
 		Expected:       g.expected,
 		ExpectedReason: g.expectedReason,
-		Properties:     g.props,
+		Properties:     g.repeated.props,
+		Damage:         g.repeated.damage.chain,
 	}}, ExitOK
 }
 
@@ -599,16 +614,15 @@ func engineTarget(t recipe.Target, label bool) engine.Target {
 		Sizes:            t.Sizes,
 		Contains:         contentsOf(t),
 		SizeFromContents: t.SizeFromContents,
-		SizeIsRange:      t.SizeIsRange,
-		SizeMin:          t.SizeMin,
-		SizeMax:          t.SizeMax,
+		Range:            engine.SizeRange(t.Range),
 		BoundaryLimit:    t.BoundaryLimit,
 		NameTmpl:         t.Name,
 		Label:            label,
 		Expected:         t.Expected,
 		ExpectedReason:   t.ExpectedReason,
 		Group:            t.Group,
 		Properties:       t.Properties,
+		Damage:           t.Damage,
 	}
 }