From 7c5fb7de389378e20ea60fafe42b1d0646a33570 Mon Sep 17 00:00:00 2001
From: DemchaAV <demchaav@gmail.com>
Date: Fri, 10 Jul 2026 09:16:13 +0100
Subject: [PATCH] test(layout): add jqwik property-based layout invariants

Add the jqwik test dependency (test scope only) and property tests for three
pure layout functions: TokenBreaking.softBreakSegments (split then re-join
reconstructs the token, no empty segment), LayerStackGeometry.zOrder (a stable
permutation of the source indices, ascending by zIndex), and
RowSlots.validateWeightsMatchChildren (throws exactly when the weight count
differs from the child count). Each law is checked over 1000 generated inputs,
complementing the example-based unit tests.
---
 .gitignore                                    |  3 +
 pom.xml                                       | 13 +++
 .../LayoutInvariantsPropertiesTest.java       | 90 +++++++++++++++++++
 3 files changed, 106 insertions(+)
 create mode 100644 src/test/java/com/demcha/compose/document/layout/LayoutInvariantsPropertiesTest.java

diff --git a/.gitignore b/.gitignore
index 69188cc9..a06a2440 100644
--- a/.gitignore
+++ b/.gitignore
@@ -82,3 +82,6 @@ docs/private/
 # test fails, useful for review locally, not part of repo state.
 **/visual-baselines/**/*.actual.png
 **/visual-baselines/**/*.diff.png
+
+# jqwik property-based test replay database — regenerated on every run.
+.jqwik-database
diff --git a/pom.xml b/pom.xml
index dd8ca314..2746963b 100644
--- a/pom.xml
+++ b/pom.xml
@@ -57,6 +57,7 @@
         <mockito.version>5.23.0</mockito.version>
         <byteBuddy.version>1.18.11</byteBuddy.version>
         <archunit.version>1.4.2</archunit.version>
+        <jqwik.version>1.9.3</jqwik.version>
 
         <!-- Bundled fonts / emoji, pulled in at test scope only. Pinned to the
              independent 1.0.0 line (not bumped in engine lockstep); keep in step
@@ -233,6 +234,18 @@
             <scope>test</scope>
         </dependency>
 
+        <!--
+            jqwik drives the property-based layout-invariant tests: pure
+            engine functions (tokenization reconstruction, z-order permutation,
+            row-weight guards) checked against generated inputs. Test scope only.
+        -->
+        <dependency>
+            <groupId>net.jqwik</groupId>
+            <artifactId>jqwik</artifactId>
+            <version>${jqwik.version}</version>
+            <scope>test</scope>
+        </dependency>
+
         <!--
             Benchmark-only comparison dependencies (iText, openHTMLToPDF,
             JasperReports) live in the sibling `benchmarks/` Maven module
diff --git a/src/test/java/com/demcha/compose/document/layout/LayoutInvariantsPropertiesTest.java b/src/test/java/com/demcha/compose/document/layout/LayoutInvariantsPropertiesTest.java
new file mode 100644
index 00000000..107b6a4b
--- /dev/null
+++ b/src/test/java/com/demcha/compose/document/layout/LayoutInvariantsPropertiesTest.java
@@ -0,0 +1,90 @@
+package com.demcha.compose.document.layout;
+
+import net.jqwik.api.ForAll;
+import net.jqwik.api.Property;
+import net.jqwik.api.constraints.Chars;
+import net.jqwik.api.constraints.DoubleRange;
+import net.jqwik.api.constraints.IntRange;
+import net.jqwik.api.constraints.Size;
+import net.jqwik.api.constraints.StringLength;
+
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatCode;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+/**
+ * Property-based coverage of pure engine layout invariants: over many generated
+ * inputs (not a handful of hand-picked examples) these functions must hold their
+ * algebraic contracts. The example-based unit tests ({@code TokenBreakingTest},
+ * {@code LayerStackGeometryTest}, {@code RowSlotsTest}) pin specific cases; these
+ * assert the laws across the whole input space, with jqwik shrinking any
+ * counter-example to its minimal form.
+ */
+class LayoutInvariantsPropertiesTest {
+
+    // ── TokenBreaking.softBreakSegments ──────────────────────────────────────
+
+    /** Splitting a token and re-joining the pieces must reproduce it exactly. */
+    @Property
+    void softBreakSegmentsReconstructTheInput(
+            @ForAll @StringLength(max = 40) @Chars({'a', 'b', 'c', '1', '.', ':', '/', '-'}) String token) {
+        List<String> segments = TokenBreaking.softBreakSegments(token);
+        assertThat(String.join("", segments)).isEqualTo(token);
+    }
+
+    /** No emitted segment is empty for a non-empty token. */
+    @Property
+    void softBreakSegmentsAreNeverEmptyForNonEmptyInput(
+            @ForAll @StringLength(min = 1, max = 40) @Chars({'a', 'b', '.', ':', '/', '-'}) String token) {
+        assertThat(TokenBreaking.softBreakSegments(token))
+                .allSatisfy(segment -> assertThat(segment).isNotEmpty());
+    }
+
+    // ── LayerStackGeometry.zOrder ────────────────────────────────────────────
+
+    /** The z-order is a stable permutation of the source indices, ascending by zIndex. */
+    @Property
+    void zOrderIsAStablePermutationSortedByZIndex(
+            @ForAll @Size(max = 20) List<@IntRange(min = -5, max = 5) Integer> zIndices) {
+        int n = zIndices.size();
+        int[] order = LayerStackGeometry.zOrder(zIndices);
+
+        assertThat(order).hasSize(n);
+        boolean[] seen = new boolean[n];
+        for (int index : order) {
+            assertThat(index).isBetween(0, n - 1);
+            assertThat(seen[index]).as("index %d must appear exactly once", index).isFalse();
+            seen[index] = true;
+        }
+        for (int i = 1; i < n; i++) {
+            int prev = order[i - 1];
+            int cur = order[i];
+            int zPrev = zIndices.get(prev);
+            int zCur = zIndices.get(cur);
+            assertThat(zPrev).as("z-order must be ascending by zIndex").isLessThanOrEqualTo(zCur);
+            if (zPrev == zCur) {
+                assertThat(prev).as("equal zIndex must keep source order").isLessThan(cur);
+            }
+        }
+    }
+
+    // ── RowSlots.validateWeightsMatchChildren ────────────────────────────────
+
+    /** The guard throws exactly when the weight count differs from the child count. */
+    @Property
+    void validateWeightsThrowsExactlyWhenSizesDiffer(
+            @ForAll @Size(max = 10) List<@DoubleRange(min = 0.0, max = 5.0) Double> weights,
+            @ForAll @IntRange(min = 0, max = 10) int childCount) {
+        if (weights.size() == childCount) {
+            assertThatCode(() -> RowSlots.validateWeightsMatchChildren(weights, childCount))
+                    .doesNotThrowAnyException();
+        } else {
+            assertThatThrownBy(() -> RowSlots.validateWeightsMatchChildren(weights, childCount))
+                    .isInstanceOf(IllegalArgumentException.class)
+                    .hasMessageContaining("(" + weights.size() + ")")
+                    .hasMessageContaining("(" + childCount + ")");
+        }
+    }
+}