chore(engine): deprecate the legacy ECS engine packages (F11)

CHANGELOG.md

@@ -117,6 +117,22 @@ Open cycle — bug-fix / housekeeping. Entries land here as they merge.
   resolved by the layout compiler. The method is kept for binary compatibility and
   scheduled for removal in the next major.
 
+- **The legacy ECS engine packages are deprecated.** `com.demcha.compose.engine.core`,
+  `engine.layout` (and `engine.layout.container`), and `engine.pagination` are the
+  original `Entity`-based layout/pagination engine — a parallel second engine
+  whose execution path the canonical pipeline
+  (`GraphCompose.document() → DocumentSession → LayoutCompiler`) never runs; it
+  imports nothing from them directly, and the former `GraphCompose.pdf(...)`
+  entry point has already been removed. The ECS execution engine runs only under
+  the legacy engine regression tests. (One vestigial coupling remains, tracked as
+  a follow-up: the canonical `TextMeasurementSystem` still `extends
+  engine.core.SystemECS` via a no-op `process(...)`.) The
+  packages are now `@Deprecated` (package level, so no deprecation-warning cascade)
+  with corrected package docs, to stop misdirecting contributors into optimizing a
+  dead engine. The genuinely shared engine packages (`engine.components`,
+  `engine.measurement`, `engine.font`, `engine.render`) are **not** deprecated.
+  No public API or behaviour change.
+
 ### Tests / tooling
 
 - **Benchmark regression gate and measurement probe (benchmarks module, not part

src/main/java/com/demcha/compose/engine/core/package-info.java

@@ -1,30 +1,36 @@
 /**
- * Core ECS primitives that hold entity/component graphs and shared traversal
- * state.
+ * Core primitives of the <strong>legacy ECS engine</strong> — entity/component
+ * graphs and shared traversal state for the original {@code Entity}-based
+ * layout / pagination / render pipeline.
  *
- * <p>This package contains the foundation used by the runtime pipeline. In the
- * normal PDF pipeline the high-level flow is:</p>
+ * <p>This is <em>not</em> the engine behind the public API. The canonical
+ * pipeline ({@code GraphCompose.document() -> DocumentSession -> LayoutCompiler
+ * -> LayoutGraph -> PdfFixedLayoutBackend}) in {@code com.demcha.compose.document.*}
+ * imports nothing from this package directly, and the former
+ * {@code GraphCompose.pdf(...)} surface that drove the ECS has been removed. The
+ * ECS <em>execution</em> engine — the {@code EntityManager.processSystems()} loop
+ * and the layout / pagination / render systems it drives — is dead: it runs only
+ * under the legacy engine regression tests.</p>
  *
- * <ol>
- *   <li>builders populate {@code Entity} graphs and attach components</li>
- *   <li>{@code LayoutSystem} resolves geometry, hierarchy depth, and layer order</li>
- *   <li>{@code PageBreaker} assigns final page-aware {@code Placement}</li>
- *   <li>a backend renderer such as {@code PdfRenderingSystemECS} consumes the resolved entities</li>
- * </ol>
+ * <p>One vestigial holdover keeps {@code SystemECS} and {@code EntityManager}
+ * referenced from live code: the canonical
+ * {@code engine.measurement.TextMeasurementSystem} still
+ * {@code extends SystemECS} with a no-op {@code process(EntityManager)}.
+ * Decoupling that base — so {@code engine.core} becomes genuinely unreferenced by
+ * the canonical pipeline — is a tracked follow-up.</p>
  *
- * <p>The package is intentionally split further into subpackages with narrower
- * responsibilities:</p>
+ * <p>The genuinely shared engine packages are elsewhere and are <em>not</em>
+ * deprecated: {@code engine.components} (value types), {@code engine.measurement}
+ * (text-measurement contracts), {@code engine.font}, and
+ * {@code engine.render} (backend-neutral render-pass contracts) are all used by
+ * the canonical pipeline.</p>
  *
- * <ul>
- *   <li>{@code engine.layout}: low-level layout systems</li>
- *   <li>{@code engine.pagination}: page-breaking helpers</li>
- *   <li>{@code engine.measurement}: text measurement contracts</li>
- *   <li>{@code engine.render}: backend-neutral render-pass contracts and dispatch helpers</li>
- * </ul>
- *
- * <p>Project policy is to keep backend-specific lifecycle concerns out of the
- * shared engine layer wherever possible. The engine should reason in terms of
- * resolved geometry, entity ordering, and render-session seams, while PDFBox,
- * DOCX, or PPTX specifics stay in backend-owned packages.</p>
+ * @deprecated Legacy ECS engine, superseded by the canonical
+ *     {@code com.demcha.compose.document.layout} pipeline. No public entry point
+ *     runs it and it is not on the canonical hot path; it is retained only for the
+ *     legacy engine regression tests (aside from the vestigial {@code SystemECS}
+ *     base of {@code TextMeasurementSystem}, a tracked cleanup) — a candidate for
+ *     removal. Do not extend it or spend optimization effort here.
  */
+@Deprecated
 package com.demcha.compose.engine.core;

src/main/java/com/demcha/compose/engine/layout/container/package-info.java

@@ -1,7 +1,14 @@
 /**
- * Internal container layout helpers for alignment, expansion, and module width resolution.
+ * Container layout helpers (alignment, expansion, module-width resolution) of
+ * the <strong>legacy ECS engine</strong>.
  *
- * <p>Ownership: Owned by the shared engine layout pipeline.</p>
- * <p>Extension rules: Extend with deterministic helpers that operate on existing components and traversal snapshots.</p>
+ * <p>Part of the parallel legacy {@code Entity}-based engine; the canonical
+ * {@code com.demcha.compose.document.layout} pipeline does not use it.</p>
+ *
+ * @deprecated Legacy ECS engine, superseded by the canonical
+ *     {@code com.demcha.compose.document.layout} pipeline. Not reachable from
+ *     any public API; retained only for legacy regression tests and a candidate
+ *     for removal. Do not extend it or spend optimization effort here.
  */
-package com.demcha.compose.engine.layout.container;
+@Deprecated
+package com.demcha.compose.engine.layout.container;

src/main/java/com/demcha/compose/engine/layout/package-info.java

@@ -1,7 +1,17 @@
 /**
- * Shared layout systems that turn low-level entities into resolved geometry.
+ * Layout systems of the <strong>legacy ECS engine</strong> — they turn
+ * low-level {@code Entity} graphs into resolved geometry for the original
+ * {@code Entity}-based pipeline.
  *
- * <p>Ownership: Owned by the shared engine layout pipeline.</p>
- * <p>Extension rules: New layout behavior must preserve deterministic traversal and be covered by layout snapshot tests.</p>
+ * <p>Despite the former "shared" framing, the canonical pipeline
+ * ({@code com.demcha.compose.document.layout.LayoutCompiler}) imports nothing
+ * from this package. It is part of the parallel legacy ECS engine reachable
+ * only from the legacy engine regression tests.</p>
+ *
+ * @deprecated Legacy ECS engine, superseded by the canonical
+ *     {@code com.demcha.compose.document.layout} pipeline. Not reachable from
+ *     any public API; retained only for legacy regression tests and a candidate
+ *     for removal. Do not extend it or spend optimization effort here.
  */
-package com.demcha.compose.engine.layout;
+@Deprecated
+package com.demcha.compose.engine.layout;

src/main/java/com/demcha/compose/engine/pagination/package-info.java

@@ -1,25 +1,19 @@
 /**
- * Pagination and page-placement helpers for resolved GraphCompose entities.
+ * Pagination and page-placement helpers of the <strong>legacy ECS engine</strong>.
  *
- * <p>This package owns the logic that runs after layout has produced
- * {@code ComputedPosition} and size metadata but before the renderer writes the
- * final document. Its responsibilities include:</p>
+ * <p>This package paginates the resolved {@code Entity} graph for the original
+ * {@code Entity}-based pipeline ({@code PageBreaker} for the pagination walk,
+ * {@code PageLayoutCalculator} for page-coordinate math, {@code TextBlockProcessor}
+ * for block-text fragmentation, {@code ParentContainerUpdater} for upward
+ * size/position propagation). It is renderer-neutral, but it is part of the
+ * parallel legacy ECS engine: the canonical pipeline
+ * ({@code com.demcha.compose.document.layout}) does its own pagination and
+ * imports nothing here.</p>
  *
- * <ul>
- *   <li>choosing a child-first pagination order for the resolved hierarchy</li>
- *   <li>mapping resolved Y coordinates into page-relative {@code Placement}</li>
- *   <li>splitting breakable content such as block text across pages</li>
- *   <li>propagating child-driven size and page-shift updates into parent containers</li>
- * </ul>
- *
- * <p>The package is intentionally renderer-neutral. It does not open PDF
- * streams, create pages directly, or decide backend drawing policy. Instead it
- * mutates the entity graph so later renderers can consume one deterministic,
- * page-aware layout result.</p>
- *
- * <p>Key classes in this package are {@code PageBreaker} for the pass-level
- * pagination walk, {@code PageLayoutCalculator} for page-coordinate math,
- * {@code TextBlockProcessor} for block-text fragmentation, and
- * {@code ParentContainerUpdater} for upward size/position propagation.</p>
+ * @deprecated Legacy ECS engine, superseded by the canonical
+ *     {@code com.demcha.compose.document.layout} pipeline. Not reachable from
+ *     any public API; retained only for legacy regression tests and a candidate
+ *     for removal. Do not extend it or spend optimization effort here.
  */
+@Deprecated
 package com.demcha.compose.engine.pagination;