Skip to content

docs(architecture): retarget the engine documentation to 2.x#438

Merged
DemchaAV merged 1 commit into
developfrom
docs/architecture-2x
Jul 25, 2026
Merged

docs(architecture): retarget the engine documentation to 2.x#438
DemchaAV merged 1 commit into
developfrom
docs/architecture-2x

Conversation

@DemchaAV

Copy link
Copy Markdown
Owner

Why

The architecture pages still describe the Entity/ECS engine removed in 2.0. A reader following them reaches for RenderStream, RenderPassSession, TextComponent, EntityManager, ParentComponent, EntityBounds, ParentContainerUpdater, LayoutTraversalContext, ComputedPosition, Breakable, and the packages engine.core / engine.pagination — none of which exist on any live branch. pagination-ordering.md is the worst case: its entire "Current implementation shape" section documents a priority-based topological walk that no longer runs. The release runbook calls itself the 1.x checklist and points every command at aggregator/pom.xml and -pl ., neither of which is the 2.x layout.

What changed

  • overview.md drops the ECS responsibilities section, names both fixed-layout backends in the pipeline and the package list, and gains a PPTX leg in the diagram. That diagram also had the DOCX edge on the wrong node: DocxSemanticBackend.export takes a DocumentGraph, so it branches off the semantic tree, not off the resolved layout — which is exactly why it cannot reproduce fixed-layout geometry.
  • package-map.md rebuilds the engine table from the live package list (components / debug / font / measurement / render / text), splits the row that claimed render-docx and render-pptx were both semantic exporters, and adds document.backend.fixed.pptx.
  • lifecycle.md loses its v1.2 title, gains the PPTX render path, and states chrome coverage per backend instead of calling metadata and watermarks PDF-only.
  • pagination-ordering.md describes the mechanism that actually runs — a single sequential LayoutCompiler pass whose emission order is render order, with descendants-first a property of the recursion rather than of a sort. Its debugging steps now name the live pagination log events and layoutSnapshot().
  • release-process.md becomes the 2.x checklist: the whole-reactor gate, the 13-pom lockstep list taken from the script's own array, the real staging allow-list including the per-module READMEs, and a branch-flow section describing the standing roles rather than the completed 2.0 transition. It also records two traps: a gate command ending in a pipe reports the pipe's status and hides BUILD FAILURE, and after a version bump every goal resolving train modules from ~/.m2 needs an install first.

BlockText and ContentSize are still live and were left alone, as was the logger category com.demcha.compose.engine.pagination. Two 1.x references are kept deliberately: the backport callout (the 1.x branch genuinely uses aggregator/pom.xml) and the dated v1.6.5 lessons-learned entry.

Verification

  • ./mvnw -B -ntp clean verify — BUILD SUCCESS, 1508 tests, 0 failures.
  • A sweep for every dead identifier listed above returns nothing under docs/architecture/.
  • Every internal link added resolves on disk.

The architecture pages still described the Entity/ECS engine removed in 2.0 and
a PPTX backend that "is roadmap for v1.6+". A reader following them reached for
`RenderStream`, `RenderPassSession`, `TextComponent`, `EntityManager`,
`ParentComponent`, `EntityBounds`, `ParentContainerUpdater`,
`LayoutTraversalContext`, `ComputedPosition`, `Breakable` and the packages
`engine.core` / `engine.pagination` — none of which exist on any live branch.
The release runbook called itself the 1.x checklist and pointed every command at
`aggregator/pom.xml` and `-pl .`, neither of which is the 2.x layout.

Rewrite the stale sections against the code as it is. `overview.md` drops the ECS
responsibilities section, names both fixed-layout backends in the pipeline and the
package list, and gains a PPTX leg in the diagram. That diagram also had the DOCX
edge in the wrong place: `DocxSemanticBackend.export` takes a `DocumentGraph`, so
it branches off the semantic tree, not off the resolved layout — which is exactly
why it cannot reproduce fixed-layout geometry.

`package-map.md` rebuilds the engine table from the live package list
(`components` / `debug` / `font` / `measurement` / `render` / `text`), splits the
render-docx and render-pptx row that claimed both were semantic exporters, and adds
the `document.backend.fixed.pptx` row. `lifecycle.md` loses its v1.2 title, gains
the PPTX render path, and states the chrome coverage per backend instead of calling
metadata and watermarks PDF-only. `pagination-ordering.md` describes the mechanism
that actually runs — a single sequential compile pass whose emission order is render
order — and its debugging steps now name the live pagination log events and
`layoutSnapshot()`.

The runbook becomes the 2.x checklist: the whole-reactor gate, the 13-pom lockstep
list taken from the script's own array, the real staging allow-list including the
per-module READMEs, and a branch-flow section describing the standing roles rather
than the completed 2.0 transition. It also records two traps that cost time this
cycle: a gate command ending in a pipe reports the pipe's status and hides
`BUILD FAILURE`, and after a version bump every goal resolving train modules from
`~/.m2` needs an `install` first.

Verified: full reactor `clean verify` green (1508 tests, 0 failures); no dead
engine identifier remains anywhere under docs/architecture.
@DemchaAV
DemchaAV merged commit ff05e74 into develop Jul 25, 2026
10 checks passed
@DemchaAV
DemchaAV deleted the docs/architecture-2x branch July 25, 2026 08:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant