[Publication] Generate deterministic fixed-layout EPUB 3 from ordered page collections

[szmyty]

2026-09-28 completion handoff

The bounded ordered-page exporter and its independent validation checkpoints are merged:

Checkpoint	Review PR	Merge commit
#415 canonical ordered collections	#431	de0833de3626a76c90bd89aafc34d08c92680e06
#416 print-interior PDF	#432	b566e815d5fc268403843a5acba0f6e102191733
#417 fixed-layout EPUB generation	#435	eaf3b98d4236a74ba30b6e40456cbf9757675a76
#418 fixed-layout EPUB validation/capability evidence	#436	ff6a76f4bad17541d6554e514ccb345f7c3d3e3c

The #418 review tree was 68d2df152126fda27c0364779294add5a909a2fb. Local Linux validation passed 1,212 workspace tests (nine intentionally ignored), Rust 1.94 MSRV check, Clippy with warnings denied, formatting, golden conformance, crate package verification, and strict docs build. PR-head GitHub CI, docs, and Artifact conformance completed successfully for #431, #432, #435, and #436. Commit Lint failed on each of those review heads; the #436 log specifically rejects its nonconventional commit subject. That historical failure remains recorded rather than being presented as green.

The proven fixed-layout EPUB route accepts a bounded, explicitly ordered homogeneous PNG/JPEG collection. SVG, fixed-layout KEPUB, retailer approval, and actual external EPUBCheck conformance remain outside this claim; the optional provider is typed as unavailable unless independently run. No immutable release is claimed here. The separate #419 release checkpoint remains open and must pass its own release gates before Flow pins a version and digest.

This closes the production exporter milestone. The checkpoint sequence and older rationale remain below.

---

2026-09-22 execution checkpoint

This parent is decomposed into bounded implementation and release checkpoints:

1. #415 — bind ordered collections to canonical planning and execution.
2. #416 — generate deterministic print-interior PDFs as a sibling consumer of [Checkpoint 414.1] Bind ordered collections to canonical planning and execution #415.
3. #417 — generate deterministic EPUB 3.3 fixed-layout packages as a sibling consumer of [Checkpoint 414.1] Bind ordered collections to canonical planning and execution #415.
4. #418 — validate fixed-layout EPUB output and publish exact capability truth.
5. #419 — publish the first verified immutable Renderflow integration-candidate release for downstream Flow consumption.

Execution order is #415 → (#416 and #417) → #418 → #419 → the Flow-owned immutable adapter/proof. #416 and #417 may proceed independently after #415.

#413 is a downstream synthetic-comic and fixture-pack consumer of these production exporters; it does not block #415–#419. #406 remains the parallel/later localization and layered-composition lane and is not required for the default-locale ordered-page exporters.

This checkpoint supersedes older dependency-order implications below while preserving the original issue body as historical scope and rationale.

---

Consumer dependency: incomprisllc/comics#158 (parent milestone incomprisllc/comics#8)

Builds on: #344, #353, #357, #360, #362, #364, #377, #406, and #413.

Observed gap

At Renderflow main 170c3d5985af073d3da8f6ac2e0c4b639cfd2b3e, the exact capability contract reports epub_fixed_layout_generation=false and kepub_fixed_layout_generation=false. The Pandoc route is reflow-only. Spec v2 and Transform v2 model ordered collections, but canonical planning rejects execution unless exactly one artifact source is supplied. Native ebook inspection can observe fixed-layout semantics; it does not generate them.

The safe consumer probe in incomprisllc/comics#93 records this as unsupported. Closed #344/#377, open #406, and deferred fixture work in #413 do not own the production exporter/execution gap below.

Goal

Add one provider-neutral renderflow/v2 + Transform-v2 route that consumes an explicitly ordered, immutable page collection and emits a deterministic EPUB 3.3 fixed-layout artifact. Do not introduce a Comics-only package contract or broaden this into arbitrary directory/glob discovery.

Minimum scope

• Wire a declared kind: collection source through canonical planning/execution. Member IDs, digests, and order must participate in plan, cache, checkpoint, resume, and provenance identity.
• Add an exact capability/adapter such as ebook.generate.epub.fixed-layout for ordered local SVG/PNG/JPEG page assets plus existing publication metadata.
• Emit deterministic bytes: stored first mimetype, normalized member order/timestamps, EPUB 3.3 OPF/XHTML, rendition:layout=pre-paginated, viewport geometry, manifest/spine, TOC/nav, page-list, cover, page-progression/spread policy, and declared accessibility relationships.
• Parse or allowlist SVG/XML safely. Reject external/network resources, unsafe active/entity behavior, malformed content, and unsupported media with typed diagnostics. The current markup-shaped structural probe is not page-safety or conformance evidence.
• Never infer that RTL reading direction mirrors artwork.
• Advertise fixed-layout generation only for this proven route. Keep Pandoc reflow behavior and KEPUB fixed-layout support unchanged.
• Validate with native inspection and optional EPUBCheck v5; unavailable EPUBCheck must remain explicit and cannot pass.

Acceptance criteria

• Two clean builds of the same fixture are byte-identical.
• Source inputs remain unchanged.
• Provenance records complete ordered member lineage.
• Member, order, geometry, or metadata changes invalidate cache/checkpoint evidence.
• A tiny redistribution-safe fixture proves the supported route.
• Negative cases cover missing/duplicate members, wrong order/geometry, unsupported media, malformed/unsafe SVG/XML, external references, missing nav/page-list/accessibility relationships, and unavailable validation.
• No network, upload, retailer, or publication side effects occur.

Non-goals

Layered composition/localization (#406), the full reusable corpus (#413), consumer creative content, Lulu/retailer acceptance, KEPUB fixed layout, release approval/upload, and broad XML/SVG-standard completeness.

Existing DAG, declarative-specification, and plugin/registry decisions appear to cover this implementation. Create a new ADR only if implementation changes a shared contract or authority boundary instead of completing the already-declared collection boundary.