format/zip: an archive that holds real files, exact to the byte

The fourth format and the first container. The entries are not random bytes -
they are real generated files of another format, each one valid on its own.
Asking for five PDFs of 200 kB inside a 3 MB archive gives exactly 3 145 728
bytes, and every extracted PDF opens.

ZIP is the only Tier 1 format whose padding channel has a ceiling, so it is
the only one that really needs both stages of the size strategy: the archive
comment up to 65 535 bytes, then a stored entry above it. Measured: 7-Zip
reports no warning at any comment size up to the limit, and the entry
overhead is a constant plus twice the name length, with data and comment both
counting one for one. Everything is stored rather than compressed, so the
size is a linear function of the parts and planning computes it exactly.

The interesting part is what was removed rather than added.

This project had designed the engine to inject a child producing function
into the archive generator, so the archive would not reach upwards for the
engine. The reasoning was right that reaching for the engine breaks the
layering. The conclusion was wrong: an archive needs the registry and another
generator, and both already sit on its own layer, where a sideways edge is
allowed. So the injection solved a problem that does not exist. It was
removed before it was written and the architecture note now says so.

An abstraction built ahead of a need is a cost, not a safeguard.

Verified with 7-Zip, Windows Explorer, the built in Expand-Archive, and by
extracting the contents and opening them with a PDF reader.

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

Author: donislawdev

CHANGELOG-DEV.md

@@ -6,6 +6,33 @@ configuration, architectural decisions. Anything a user would notice goes to
 
 ## Unreleased
 
+### 2026-08-01 - ZIP, and an abstraction that turned out unnecessary
+
+- `zip` is the fourth generator and the first container. Entries are real
+  generated files of another format, each valid on its own.
+- **The two stage padding strategy in its pure form.** ZIP is the only Tier 1
+  format whose padding channel has a ceiling, so it is the only one that
+  really needs both stages: the archive comment up to 65 535 bytes, then a
+  stored entry above it. Measured: 7-Zip reports no warning at any comment
+  size up to the limit.
+- Everything is stored rather than compressed, so the archive size is a
+  linear function of its parts and planning computes it exactly. Measured:
+  entry overhead is a constant plus twice the name length, data and comment
+  both count one for one.
+- **The child generator injection this project designed was not needed.** The
+  architecture note had the engine injecting a child producing function into
+  the archive generator, to avoid the archive reaching upwards for the
+  engine. Reaching for the engine would indeed have broken the layering - but
+  an archive needs the registry and another generator, and both sit on its
+  own layer. format.Get is a sideways edge that was already allowed. The
+  machinery was removed before it was written and the note corrected.
+- `entry_size` accepts the same size syntax as --size. Anything else would
+  have meant entry_size=200kb failing while size=200kb works.
+- Nesting an archive inside an archive is refused for now, because it needs a
+  depth limit first and there is none.
+- Guards: 33, all green with four formats registered. Five mutations of the
+  ZIP generator all turn them red.
+
 ### 2026-08-01 - PDF, and an assumption of ours disproved
 
 - `pdf` is the third generator. Exact size, byte determinism, pages and page

CHANGELOG.md

@@ -12,8 +12,12 @@ because it turns other people's test suites red.
 
 ### Added
 
-- `tfg generate` produces **text, PNG and PDF files** of an exact size. Ask
-  for 10 485 761 bytes and you get exactly that.
+- `tfg generate` produces **text, PNG, PDF and ZIP files** of an exact size.
+  Ask for 10 485 761 bytes and you get exactly that.
+- **A ZIP holds real generated files, not random bytes.**
+  `--set entries=5 --set entry_format=pdf --set entry_size=200kb` gives an
+  archive whose five entries are valid PDFs that open on their own. Checked
+  with 7-Zip, Windows Explorer and by extracting and opening the contents.
 - PDF takes `--set pages=` and `--set page_size=` (A4, A3, A5, Letter,
   Legal). The label goes in the page footer and in the document title.
   Checked against Xpdf, exiftool and the Windows PDF renderer.

internal/format/all/all.go

@@ -11,4 +11,5 @@ import (
 	_ "github.com/donislawdev/TestingFilesGenerator/internal/format/pdf"
 	_ "github.com/donislawdev/TestingFilesGenerator/internal/format/png"
 	_ "github.com/donislawdev/TestingFilesGenerator/internal/format/txt"
+	_ "github.com/donislawdev/TestingFilesGenerator/internal/format/zip"
 )