docs(architecture): retarget the engine documentation to 2.x#438
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 packagesengine.core/engine.pagination— none of which exist on any live branch.pagination-ordering.mdis 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 ataggregator/pom.xmland-pl ., neither of which is the 2.x layout.What changed
overview.mddrops 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.exporttakes aDocumentGraph, so it branches off the semantic tree, not off the resolved layout — which is exactly why it cannot reproduce fixed-layout geometry.package-map.mdrebuilds 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 addsdocument.backend.fixed.pptx.lifecycle.mdloses 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.mddescribes the mechanism that actually runs — a single sequentialLayoutCompilerpass 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 andlayoutSnapshot().release-process.mdbecomes 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 hidesBUILD FAILURE, and after a version bump every goal resolving train modules from~/.m2needs aninstallfirst.BlockTextandContentSizeare still live and were left alone, as was the logger categorycom.demcha.compose.engine.pagination. Two 1.x references are kept deliberately: the backport callout (the1.xbranch genuinely usesaggregator/pom.xml) and the dated v1.6.5 lessons-learned entry.Verification
./mvnw -B -ntp clean verify— BUILD SUCCESS, 1508 tests, 0 failures.docs/architecture/.