refactor(build): standard Maven layout — engine in core/, aggregator at the root

.github/workflows/benchmarks-jmh.yml

@@ -45,7 +45,7 @@ jobs:
         run: ./mvnw -B -ntp -f fonts/pom.xml -DskipTests install
 
       - name: Install root artifact (graph-compose + test-jar)
-        run: ./mvnw -B -ntp -DskipTests install -pl .
+        run: ./mvnw -B -ntp -DskipTests install -pl :graph-compose-core
 
       - name: Build the JMH runner jar
         run: ./mvnw -B -ntp -f benchmarks/pom.xml clean package -DskipTests

.github/workflows/ci.yml

@@ -49,7 +49,7 @@ jobs:
         run: |
           ./mvnw -B -ntp clean \
             "-Dtest=EnginePdfBoundaryTest,CanonicalTemplateComposerPdfBoundaryTest,PdfRenderInterfaceGuardTest,DocumentationCoverageTest,DocumentationExamplesTest,CanonicalSurfaceGuardTest,TemplateComposeApiTest,VersionConsistencyGuardTest" \
-            test
+            test -pl :graph-compose-core
 
   changes:
     # Path-based change detection for selective CI on pull requests. Emits the
@@ -84,20 +84,20 @@ jobs:
               - 'mvnw.cmd'
               - '.github/workflows/ci.yml'
             core:
-              - 'src/**'
-              - 'pom.xml'
+              - 'core/src/**'
+              - 'core/pom.xml'
             perf:
-              - 'src/**'
+              - 'core/src/**'
               - 'render-pdf/**'
               - 'templates/**'
               - 'benchmarks/**'
-              - 'pom.xml'
+              - 'core/pom.xml'
             # Published library modules + build toolchain. A change here runs the
             # full JDK matrix (it ships to users across JVMs); a PR touching only
             # the non-published test/build infra (qa, coverage, examples,
             # benchmarks, docs) runs the baseline JDK alone.
             jvm:
-              - 'src/**'
+              - 'core/src/**'
               - 'render-pdf/**'
               - 'render-docx/**'
               - 'render-pptx/**'
@@ -107,7 +107,7 @@ jobs:
               - 'fonts/**'
               - 'emoji/**'
               - 'bundle/**'
-              - 'pom.xml'
+              - 'core/pom.xml'
               - '.mvn/**'
               - 'mvnw'
               - 'mvnw.cmd'
@@ -154,14 +154,15 @@ jobs:
         # the classpath and so cannot live in the engine's own test scope), and the
         # graph-compose-coverage aggregator (report-only JaCoCo over core + qa exec).
         # -am pulls the fonts / emoji upstreams; bundle / examples / benchmarks are excluded.
-        run: ./mvnw -B -ntp -f aggregator/pom.xml clean verify -pl :graph-compose-core,:graph-compose-render-pdf,:graph-compose-render-docx,:graph-compose-render-pptx,:graph-compose-templates,:graph-compose-testing,:graph-compose-qa,:graph-compose-coverage -am
+        run: ./mvnw -B -ntp clean verify -pl :graph-compose-core,:graph-compose-render-pdf,:graph-compose-render-docx,:graph-compose-render-pptx,:graph-compose-templates,:graph-compose-testing,:graph-compose-qa,:graph-compose-coverage -am
 
       - name: Generate Javadoc
         # Run only on the baseline JDK — Javadoc output is identical
         # across JVMs and one pass is enough to catch broken @link
-        # references.
+        # references. Scoped to the engine (its public API is the doclint
+        # gate); a bare reactor pass would also lint the dev-only benchmarks.
         if: matrix.java == '17'
-        run: ./mvnw -B -ntp javadoc:javadoc
+        run: ./mvnw -B -ntp javadoc:javadoc -pl :graph-compose-core
 
       - name: Upload aggregate coverage report
         # Report-only: the cross-module JaCoCo report (core coverage counting the
@@ -209,7 +210,7 @@ jobs:
         run: ./mvnw -B -ntp -f emoji/pom.xml -DskipTests install
 
       - name: Install root artifact (graph-compose-core)
-        run: ./mvnw -B -ntp -DskipTests install -pl .
+        run: ./mvnw -B -ntp -DskipTests install -pl :graph-compose-core
 
       - name: Install graph-compose-render-pdf (the PDF backend the wrapper brings)
         # The graph-compose wrapper depends on render-pdf so a bare graph-compose
@@ -267,7 +268,7 @@ jobs:
   binary-compat:
     name: Binary Compatibility (japicmp vs pom baseline)
     # japicmp diffs the graph-compose-core public surface, so it only matters
-    # when the core module (root `src/**` or `pom.xml`) changed.
+    # when the core module (`core/src/**` or `core/pom.xml`) changed.
     if: github.event_name == 'pull_request' && needs.changes.outputs.core == 'true'
     needs: [architecture-and-documentation-guards, changes]
     runs-on: ubuntu-latest
@@ -287,20 +288,20 @@ jobs:
 
       - name: Compare public API against baseline
         # The `japicmp` profile resolves the baseline release pinned
-        # by the `japicmp.baseline` property in pom.xml (via the
+        # by the `japicmp.baseline` property in core/pom.xml (via the
         # profile-local JitPack repository) and diffs it against the
         # freshly-built artifact. Fails the job on any binary-
         # incompatible modification to the public surface. Source-
         # incompatible changes are reported only (phased policy).
         # See CHANGELOG v1.6.6 "Build" notes for the policy rationale.
-        run: ./mvnw -B -ntp -DskipTests -P japicmp verify -pl .
+        run: ./mvnw -B -ntp -DskipTests -P japicmp verify -pl :graph-compose-core
 
       - name: Upload japicmp report
         if: always()
         uses: actions/upload-artifact@v7
         with:
           name: japicmp-report-${{ github.run_id }}
-          path: target/japicmp/**
+          path: core/target/japicmp/**
           if-no-files-found: ignore
 
   perf-smoke:
@@ -331,7 +332,7 @@ jobs:
         run: ./mvnw -B -ntp -f fonts/pom.xml -DskipTests install
 
       - name: Install root artifact
-        run: ./mvnw -B -ntp -DskipTests install -pl .
+        run: ./mvnw -B -ntp -DskipTests install -pl :graph-compose-core
 
       - name: Install graph-compose-render-pdf (consumed by the benchmarks module)
         # benchmarks call buildPdf and reference the PDF backend types directly, so
@@ -426,7 +427,7 @@ jobs:
         run: ./mvnw -B -ntp -f fonts/pom.xml -DskipTests install
 
       - name: Install root artifact
-        run: ./mvnw -B -ntp -DskipTests install -pl .
+        run: ./mvnw -B -ntp -DskipTests install -pl :graph-compose-core
 
       - name: Install graph-compose-render-pdf (consumed by the benchmarks module)
         # benchmarks call buildPdf and reference the PDF backend types directly, so

.github/workflows/codeql.yml

@@ -51,10 +51,10 @@ jobs:
           queries: security-and-quality
 
       - name: Build (library module only)
-        # `-pl .` scopes the analysis to the published artifact and matches
+        # `-pl :graph-compose-core` scopes the analysis to the published artifact and matches
         # the canonical verify gate. Examples/benchmarks are intentionally
         # excluded — they ship no production code.
-        run: ./mvnw -B -ntp -DskipTests -pl . package
+        run: ./mvnw -B -ntp -DskipTests -pl :graph-compose-core package
 
       - name: Perform CodeQL analysis
         uses: github/codeql-action/analyze@v4

.github/workflows/publish.yml

@@ -93,7 +93,7 @@ jobs:
         # depth against a tag pushed from a broken branch by mistake.
         # The publish step below would also fail at signing/upload,
         # but failing here surfaces a clearer error.
-        run: ./mvnw -B -ntp clean verify -pl .
+        run: ./mvnw -B -ntp clean verify -pl :graph-compose-core
 
       - name: Publish engine to Maven Central
         # Activates the release profile (sources + javadoc + gpg sign +
@@ -102,7 +102,7 @@ jobs:
         # which blocks until Sonatype's validator confirms validation.
         # The release profile also disables the tests-jar execution, so
         # only the main + sources + javadoc + pom artefacts are uploaded.
-        run: ./mvnw -B -ntp -P release -DskipTests -Dgpg.skip=false deploy
+        run: ./mvnw -B -ntp -f core/pom.xml -P release -DskipTests -Dgpg.skip=false deploy
         env:
           CENTRAL_USERNAME: ${{ secrets.CENTRAL_USERNAME }}
           CENTRAL_TOKEN: ${{ secrets.CENTRAL_TOKEN }}

.github/workflows/release.yml

@@ -45,7 +45,7 @@ jobs:
           cache: maven
 
       - name: Verify (gate the release on a green build)
-        run: ./mvnw -B -ntp clean verify -pl .
+        run: ./mvnw -B -ntp clean verify -pl :graph-compose-core
 
       - name: Extract CHANGELOG section for the tag
         id: notes

.gitignore

@@ -37,6 +37,7 @@ build/
 ### Mac OS ###
 .DS_Store
 /logs/
+core/logs/
 benchmarks/logs/
 qa/logs/
 render-pdf/logs/

CONTRIBUTING.md

@@ -102,32 +102,32 @@ At the **2.0 GA** merge the branches take their long-term roles:
 
 ## Repository map
 
-- `src/main/java/com/demcha/compose/document/api`, `document.dsl`, `document.node`, `document.style`, `document.table`, `document.image`, `document.output`, `document.exceptions`, `document.snapshot`
+- `core/src/main/java/com/demcha/compose/document/api`, `document.dsl`, `document.node`, `document.style`, `document.table`, `document.image`, `document.output`, `document.exceptions`, `document.snapshot`
   Public canonical authoring surface — `DocumentSession`, the DSL builders, semantic node records, public style values, table types, image types, backend-neutral output options (metadata / watermark / protection / header-footer), and snapshot DTOs
-- `src/main/java/com/demcha/compose/document/layout`
+- `core/src/main/java/com/demcha/compose/document/layout`
   Canonical functional layout pipeline: `LayoutCompiler`, `BuiltInNodeDefinitions`, `TableLayoutSupport`, `PreparedNode`, `PlacedFragment`
 - `render-pdf/src/main/java/com/demcha/compose/document/backend/fixed/pdf` — module **graph-compose-render-pdf**
   PDF backend: `PdfFixedLayoutBackend`, fragment handlers, and the option translators that bridge canonical types to PDFBox
 - `render-docx/` and `render-pptx/` — modules **graph-compose-render-docx** / **graph-compose-render-pptx**
   Semantic exporters `DocxSemanticBackend` (Apache POI based) and `PptxSemanticBackend` (manifest skeleton), under `com.demcha.compose.document.backend.semantic.{docx,pptx}`
 - `templates/src/main/java/com/demcha/compose/document/templates/*` — module **graph-compose-templates**
   Built-in templates (CV, cover letter, invoice, proposal, weekly schedule), DTOs, themes, registries, and scene composition helpers
-- `src/main/java/com/demcha/compose/document/showcase`
+- `core/src/main/java/com/demcha/compose/document/showcase`
   `FontShowcase` (bundled-font preview renderer) — stays in the core engine
-- `src/main/java/com/demcha/compose/engine/*`
+- `core/src/main/java/com/demcha/compose/engine/*`
   Internal shared engine foundation under the canonical surface (measure, paginate, place, render). Not part of the recommended public API
-- `src/main/java/com/demcha/compose/font`
+- `core/src/main/java/com/demcha/compose/font`
   Public font registry, `FontName`, default fonts
-- `src/test/java/com/demcha/documentation/*`
+- `core/src/test/java/com/demcha/documentation/*`
   Examples used to keep README/documentation snippets honest
-- `src/test/java/com/demcha/compose/engine/integration/*`
+- `core/src/test/java/com/demcha/compose/engine/integration/*`
   End-to-end behaviour checks for the engine foundation's layout, pagination, and rendering paths
-- `src/test/java/com/demcha/compose/document/*`
+- `core/src/test/java/com/demcha/compose/document/*`
   Canonical API, DSL, layout, backend, and template tests
 - `assets/readme/*`
   Screenshots used by the README
-- `aggregator/pom.xml`
-  Maven reactor (aggregator POM); release tooling propagates the version bump across all modules through it in one pass
+- `pom.xml`
+  The repository-root Maven reactor (aggregator POM); release tooling propagates the version bump across all modules through it in one pass. The engine itself lives in `core/pom.xml` (`graph-compose-core`)
 - `baselines/`
   Committed performance-benchmark baselines: `current-speed-full.json` is the median reference the `11-verdict-current-speed` gate judges runs against; `BASELINE_SUMMARY.md` / `COMPARISON.md` are historical pre-optimization snapshots
 
@@ -196,7 +196,7 @@ not need any of them.
 - Builders and layout code get text width and line metrics from
   `TextMeasurementSystem`, not from the active renderer, `PdfFont`,
   or PDFBox objects.
-- Keep `src/main/java/com/demcha/compose/engine/components/*` free of
+- Keep `core/src/main/java/com/demcha/compose/engine/components/*` free of
   `org.apache.pdfbox` and `com.demcha.compose.engine.render.pdf`
   imports.
 - When you add a new fragment kind, register its handler with
@@ -219,13 +219,13 @@ Keep the entity core thin:
 The rules above are enforced by tests:
 
 - canonical surface guards:
-  [CanonicalSurfaceGuardTest.java](./src/test/java/com/demcha/documentation/CanonicalSurfaceGuardTest.java),
-  [PublicApiNoEngineLeakTest.java](./src/test/java/com/demcha/documentation/PublicApiNoEngineLeakTest.java),
-  [SemanticLayerNoPdfBoxDependencyTest.java](./src/test/java/com/demcha/documentation/SemanticLayerNoPdfBoxDependencyTest.java),
+  [CanonicalSurfaceGuardTest.java](./core/src/test/java/com/demcha/documentation/CanonicalSurfaceGuardTest.java),
+  [PublicApiNoEngineLeakTest.java](./core/src/test/java/com/demcha/documentation/PublicApiNoEngineLeakTest.java),
+  [SemanticLayerNoPdfBoxDependencyTest.java](./core/src/test/java/com/demcha/documentation/SemanticLayerNoPdfBoxDependencyTest.java),
   [DocumentationExamplesTest.java](qa/src/test/java/com/demcha/documentation/DocumentationExamplesTest.java),
-  [DocumentationCoverageTest.java](./src/test/java/com/demcha/documentation/DocumentationCoverageTest.java)
+  [DocumentationCoverageTest.java](./core/src/test/java/com/demcha/documentation/DocumentationCoverageTest.java)
 - engine internals guards:
-  [EnginePdfBoundaryTest.java](./src/test/java/com/demcha/compose/engine/architecture/EnginePdfBoundaryTest.java),
+  [EnginePdfBoundaryTest.java](./core/src/test/java/com/demcha/compose/engine/architecture/EnginePdfBoundaryTest.java),
   [PdfRenderInterfaceGuardTest.java](render-pdf/src/test/java/com/demcha/compose/engine/render/pdf/PdfRenderInterfaceGuardTest.java)
 
 ## Adding a new feature
@@ -323,7 +323,7 @@ marker, a new layout system, a new render-pass session):
 
 For text-heavy primitives, also read:
 
-- [TextMeasurementSystem.java](./src/main/java/com/demcha/compose/engine/measurement/TextMeasurementSystem.java)
+- [TextMeasurementSystem.java](./core/src/main/java/com/demcha/compose/engine/measurement/TextMeasurementSystem.java)
 - [docs/architecture/overview.md](./docs/architecture/overview.md)
 - [docs/contributing/implementation-guide.md](./docs/contributing/implementation-guide.md)
 
@@ -338,12 +338,12 @@ Choose the smallest tests that match the change:
 - For README or docs examples:
   [DocumentationExamplesTest.java](qa/src/test/java/com/demcha/documentation/DocumentationExamplesTest.java)
 - For engine/backend boundary changes:
-  [EnginePdfBoundaryTest.java](./src/test/java/com/demcha/compose/engine/architecture/EnginePdfBoundaryTest.java)
+  [EnginePdfBoundaryTest.java](./core/src/test/java/com/demcha/compose/engine/architecture/EnginePdfBoundaryTest.java)
   [PdfRenderInterfaceGuardTest.java](render-pdf/src/test/java/com/demcha/compose/engine/render/pdf/PdfRenderInterfaceGuardTest.java)
 - For PDF fragment-handler dispatch changes:
   [PdfRenderInterfaceGuardTest.java](render-pdf/src/test/java/com/demcha/compose/engine/render/pdf/PdfRenderInterfaceGuardTest.java)
 - For layout/positioning behavior:
-  [ComputedPositionTest.java](./src/test/java/com/demcha/compose/engine/components/layout/ComputedPositionTest.java)
+  [ComputedPositionTest.java](./core/src/test/java/com/demcha/compose/engine/components/layout/ComputedPositionTest.java)
 - For pagination and multi-page behavior:
   [PaginationEdgeCaseTest.java](qa/src/test/java/com/demcha/compose/document/api/PaginationEdgeCaseTest.java)
 - For Templates v2 CV / cover-letter presets: