Two damages that change the length, truncate and append-junk, with a manifest that says where the outcome depends on the reader

.github/race-weights

@@ -26,6 +26,7 @@ unlisted 0.58
 67.9 TestADeclaredDefaultIsTheOneTheFormatUses
 64.3 TestNoTrackedFileCarriesPrivateContent
 63.8 TestNoGeneratorHoldsTheWholeFileInMemory
+60.8 TestEveryDamageIsRefusedByTheStructuralCheckInEveryFormat
 57.3 TestAFilmSaysItCarriesItsLabelOnlyWhenAPictureShowsItWhole
 55.3 TestAFilmOfANamedSizeKeepsEveryPictureInsideItsReserve
 53.4 TestTheArchiveScanLooksIntoTheArchivesInside

CHANGELOG.md

@@ -16,6 +16,14 @@ because it turns other people's test suites red.
 
 ### Added
 
+- **Two more ways to break a file on purpose: `truncate` and `append-junk`.**
+  `--damage truncate` cuts the end off a file, the way an interrupted upload
+  leaves it, and `--damage append-junk` writes random bytes after its end.
+  Both keep exactly the size you asked for and work with every format. Where
+  readers differ - a text cut short is still text - the manifest says the
+  outcome is `unspecified`, offers both answers in the new `policy_options`
+  field and says why. `tfg damage <id>` lists those formats.
+
 - **tfg is on npm, for tests in Node.**
   `npm install --save-dev testing-files-generator` gives Playwright, Vitest
   and `node:test` a generated set of files, and says what the system under
@@ -65,6 +73,12 @@ because it turns other people's test suites red.
 
 ### Changed
 
+- **`expected: accept` beside a damage is allowed where the outcome depends
+  on your system.** It used to be refused beside every damage. It is still
+  refused where the damage breaks the rules of the format, because nothing
+  that follows them accepts the file, and both the command line and a recipe
+  answer the same.
+
 - **The Windows archive of the window carries Mesa 26.2.4.** The software
   OpenGL renderer in the `opengl` folder, which the window loads only after
   the graphics toolkit could not open a window, or when it is started with

README.md

@@ -482,29 +482,48 @@ the tool holds in memory has a ceiling whatever the archive holds.
 
 ```
 tfg damage [--json]      every damage, with the smallest file it takes and its settings
-tfg damage <id>          what one damage does to the bytes, and what it takes
+tfg damage <id>          what one damage does to the bytes, what it takes, and where the
+                         outcome depends on your system
 ```
 
-A damaged file comes out **exactly** the size you asked for and is one a reader
-refuses, so the manifest records it as expected to be rejected. That is the third
+A damaged file comes out **exactly** the size you asked for. That is the third
 question an upload validator asks - does it open - and until damage arrived every
-file this tool wrote was well formed by definition.
+file this tool wrote was well formed by definition. Three damages work with every
+format:
+
+| damage | what it does |
+|---|---|
+| `zero-head` | overwrites the first bytes with zeros (`bytes`, 8 unless you say otherwise) |
+| `truncate` | cuts the end off, the way an interrupted upload leaves a file (`missing`, the percent of the whole file that is gone, 50 unless you say otherwise) |
+| `append-junk` | writes random bytes after the end (`bytes`, 64 unless you say otherwise) |
+
+Where the damage breaks the rules of the format, the manifest records the file as
+expected to be rejected, with certainty. Where readers differ - a text cut short is
+still text, and most viewers skip bytes after the end of a PNG - it says the outcome
+is `unspecified` and depends on your system, offers both answers in
+`policy_options`, and says why in `detail`. `tfg damage <id>` lists those formats,
+and `tfg damage --json` carries them as `policy_dependent`.
 
 Use them with `tfg generate --damage <id>`, repeatable and applied in the order
 given, or with the `damage` key of a target in a recipe:
 
 ```
 tfg generate --format png --size 20kb --count 10 --damage zero-head:bytes=16
+tfg generate --format zip --size 5mb --damage truncate:missing=30
 ```
 
 The smallest file a damage can be given follows its settings, so the column is
 measured with the defaults. Ask for less and the run is refused before anything is
 written, naming a size that would work.
 
-Asking for `--expected accept` beside a damage is refused too, because nothing
-could meet it. Write `sanitize` if the system under test is meant to repair the
-file, or `unspecified` if that is the question you are asking - both of those,
-and `reject`, work as they always did.
+Asking for `--expected accept` beside a damage that breaks the rules of the
+format is refused too, because nothing that follows them accepts the file. Where
+the outcome depends on your system, `accept` is allowed and records your policy.
+Write `sanitize` if the system under test is meant to repair the file, or
+`unspecified` if that is the question you are asking - both of those, and
+`reject`, work as they always did. `truncate` placed after `append-junk` is
+refused, because it would cut away the bytes that were added, and so is a damage
+that changes the length of an archive that takes its size from what it holds.
 
 ## 📜 Recipes
 
@@ -948,8 +967,10 @@ rounding are the two things this tool will not do.
 
 Yes. Add `--damage zero-head` and the file comes out at exactly the size you
 asked for with its first bytes overwritten by zeros, so a reader turns it away,
-and the manifest says your system should reject it. [`tfg damage`](#tfg-damage)
-lists what this build can do and what each damage takes.
+and the manifest says your system should reject it. `--damage truncate` cuts the
+end off and `--damage append-junk` writes bytes after it, still at the size you
+asked for. [`tfg damage`](#tfg-damage) lists what this build can do, what each
+damage takes, and where the outcome depends on your system.
 
 ```
 tfg generate --format png --size 2mb --damage zero-head --out ./out

internal/cli/damagecmd.go

@@ -5,6 +5,7 @@ import (
 	"flag"
 	"fmt"
 	"io"
+	"slices"
 	"strings"
 
 	"github.com/donislawdev/TestingFilesGenerator/internal/core"
@@ -32,6 +33,24 @@ type damageEntry struct {
 	// took 3286.
 	SmallestFileBytes int64           `json:"smallest_file_bytes"`
 	Parameters        []propertyEntry `json:"parameters,omitempty"`
+	// PolicyDependent is every format where the manifest says the outcome
+	// of this damage depends on the reader, with why.
+	//
+	// Always present, empty for a damage that breaks the rules of every
+	// format, so a script reads one key for every damage rather than asking
+	// whether it is there. Owner's call on 2026-11-10: every pair makes a
+	// file, and this is how a script learns before generating which files the
+	// manifest will be certain about.
+	PolicyDependent []policyEntry `json:"policy_dependent"`
+}
+
+// policyEntry is one format where a damage leaves the outcome to the reader.
+type policyEntry struct {
+	Format string `json:"format"`
+	// Settings narrows the entry to files whose setting holds one of these
+	// values. Absent when it covers every file of the format.
+	Settings map[string][]string `json:"settings,omitempty"`
+	Reason   string              `json:"reason"`
 }
 
 // damageEntryFor is one damage as a script sees it.
@@ -43,10 +62,43 @@ func damageEntryFor(d damage.Descriptor) damageEntry {
 			Unit: p.Unit, Choices: p.Choices, Default: p.Default, Detail: p.Detail,
 		})
 	}
+	policy := make([]policyEntry, 0, len(d.Policy))
+	for _, c := range d.Policy {
+		policy = append(policy, policyEntry{Format: c.Format, Settings: c.When, Reason: c.Why})
+	}
 	return damageEntry{
 		ID: d.ID, Detail: d.Detail,
-		SmallestFileBytes: defaultFloor(d), Parameters: params,
+		SmallestFileBytes: defaultFloor(d), Parameters: params, PolicyDependent: policy,
+	}
+}
+
+// policyFormats is the formats where a damage leaves the outcome to the
+// reader, as a person reads them in a list: a format narrowed to some of its
+// settings says which.
+func policyFormats(d damage.Descriptor) string {
+	names := make([]string, 0, len(d.Policy))
+	for _, c := range d.Policy {
+		names = append(names, c.Format+settingsNarrowing(c.When))
+	}
+	return strings.Join(names, ", ")
+}
+
+// settingsNarrowing is " (encoding utf-16be or utf-16le)" for a case narrowed
+// to some values of a setting, and nothing for one that covers the format.
+func settingsNarrowing(when map[string][]string) string {
+	if len(when) == 0 {
+		return ""
+	}
+	names := make([]string, 0, len(when))
+	for name := range when {
+		names = append(names, name)
+	}
+	slices.Sort(names)
+	parts := make([]string, 0, len(names))
+	for _, name := range names {
+		parts = append(parts, name+" "+strings.Join(when[name], " or "))
 	}
+	return " (" + strings.Join(parts, ", ") + ")"
 }
 
 // defaultFloor is the smallest file this damage takes when nobody states a
@@ -87,6 +139,21 @@ func describeOneDamage(d damage.Descriptor, out io.Writer) {
 		d.ID, core.ExactBytes(defaultFloor(d)))
 	fmt.Fprintf(out, "  %s\n", d.Detail)
 
+	describeDamageSettings(d, out)
+
+	if len(d.Policy) == 0 {
+		fmt.Fprint(out, "\nIn every format the manifest expects the damaged file to be rejected.\n")
+		return
+	}
+	fmt.Fprint(out, "\nThe manifest expects the damaged file to be rejected, except in these formats,\nwhere it says the outcome depends on your system:\n")
+	for _, c := range d.Policy {
+		fmt.Fprintf(out, "  %s\n      %s\n", c.Format+settingsNarrowing(c.When), c.Why)
+	}
+}
+
+// describeDamageSettings prints what one damage takes, with the flag a person
+// would type.
+func describeDamageSettings(d damage.Descriptor, out io.Writer) {
 	if len(d.Parameters) == 0 {
 		fmt.Fprint(out, "\nThis damage takes no settings.\n")
 		return
@@ -122,17 +189,22 @@ func listDamages(out io.Writer) {
 		// reads "zero-head" and knows what comes out - so a list of names
 		// would say no more than the --damage flag help already says.
 		fmt.Fprintf(out, "    %s\n", d.Detail)
+		if len(d.Policy) > 0 {
+			fmt.Fprintf(out, "    Depends on your system in: %s\n", policyFormats(d))
+		}
 	}
-	fmt.Fprint(out, "\nRun \"tfg damage <id>\" for what one damage takes.\n")
-	fmt.Fprint(out, "The smallest file is what the default settings need.\n")
+	fmt.Fprint(out, "\nRun \"tfg damage <id>\" for what one damage takes and why the outcome depends on your system where it does.\n")
+	fmt.Fprint(out, "The smallest file is what the default settings need. A format can need more, because some damages start from a larger file.\n")
 }
 
 func damageUsage(w io.Writer, fs *flag.FlagSet, errOut io.Writer) {
 	fmt.Fprint(w, `tfg damage - list the ways this build can break a file on purpose.
 
-A damaged file comes out exactly the size you asked for and is one a reader
-refuses, so the manifest records it as expected to be rejected. Use them with
-"tfg generate --damage <id>" or with the damage key of a recipe.
+A damaged file comes out exactly the size you asked for. Where the damage
+breaks the rules of the format, the manifest expects the file to be rejected.
+Where readers differ - a text cut short is still text - it says the outcome
+depends on your system, and why. Use them with "tfg generate --damage <id>"
+or with the damage key of a recipe.
 
 Usage:
   tfg damage

internal/cli/errors.go

@@ -276,6 +276,18 @@ func classifyRequest(err error) (int, bool) {
 	if errors.As(err, &impossible) {
 		return ExitUsage, true
 	}
+	// The same class, for the same reason: a list of damages that cuts away
+	// what it added, and a damage that changes the length of an archive sized
+	// by what it holds, are wrong whatever format or size is asked for. The fix
+	// is in the invocation - the order of the flags, or a size.
+	var eaten *damage.EatenError
+	if errors.As(err, &eaten) {
+		return ExitUsage, true
+	}
+	var unsized *damage.NeedsSizeError
+	if errors.As(err, &unsized) {
+		return ExitUsage, true
+	}
 	if code, ok := classifyFormat(err); ok {
 		return code, true
 	}

internal/core/seed.go

@@ -74,6 +74,24 @@ func SizeSeed(targetSeed uint64, index int) uint64 {
 	return binary.BigEndian.Uint64(h.Sum(nil)[:8])
 }
 
+// DamageSeed derives the seed one damage uses for one file, from the file's
+// seed and the damage's place in its chain.
+//
+// Its own separator byte, for the reason SizeSeed has one: the bytes a damage
+// writes and the bytes the generator wrote are two questions about the same
+// file, and drawing both from one state would tie the junk appended to a file
+// to the content before it. The place in the chain is what gives two of the
+// same damage on one file two different results.
+func DamageSeed(fileSeed uint64, place int) uint64 {
+	h := sha256.New()
+	var buf [8]byte
+	binary.BigEndian.PutUint64(buf[:], fileSeed)
+	h.Write(buf[:])
+	h.Write([]byte{2})
+	h.Write([]byte(strconv.Itoa(place)))
+	return binary.BigEndian.Uint64(h.Sum(nil)[:8])
+}
+
 // NewRand returns the random source for one file.
 //
 // It is deterministic given the seed and it is not shared between files. A