test: tag Raincloud corpus tests @Tag("raincloud"), excluded by default

.github/workflows/raincloud-conformance.yml

@@ -51,7 +51,7 @@ jobs:
         run: scripts/hydrate-raincloud-corpus.sh --max-mb "${{ github.event.inputs.max-mb || '200' }}"
 
       - name: Run conformance suite
-        run: ./mvnw verify -pl integration -am -Dit.test=RaincloudConformanceIntegrationTest
+        run: ./mvnw verify -pl integration -am -Dvortex.it.excludedGroups= -Dit.test=RaincloudConformanceIntegrationTest
 
       - name: Publish per-slug results to job summary
         if: always()

CLAUDE.md

@@ -63,10 +63,17 @@ Trunk-based. PRs fine but always squash or rebase — no merge commits. Keep com
 ./mvnw verify -pl integration -am          # integration (failsafe, NOT surefire)
 ./mvnw verify -pl integration -am -Dit.test="RustWritesJavaReadsIntegrationTest#method"
 ./bench JavaVsJniReadBenchmark.javaReadVolume   # benchmark — always ClassName.methodName filter
-scripts/hydrate-raincloud-corpus.sh --max-mb 200   # hydrate real-world conformance corpus (#205),
-                                                   # then verify -Dit.test=RaincloudConformanceIntegrationTest
+scripts/hydrate-raincloud-corpus.sh --max-mb 200   # hydrate real-world conformance corpus (#205), then:
+./mvnw verify -pl integration -am -Dvortex.it.excludedGroups= -Dit.test="RaincloudConformanceIntegrationTest"
 ```
 
+The Raincloud corpus tests (`RaincloudConformanceIntegrationTest`,
+`RaincloudSizeComparisonIntegrationTest`) are `@Tag("raincloud")` and excluded from a routine
+`./mvnw verify` (failsafe `excludedGroups`, default `raincloud`) so a plain build never runs the
+real corpus — even on a machine that has hydrated it locally. Opt in with
+`-Dvortex.it.excludedGroups=` (clears the exclusion); this is required *in addition to* `-Dit.test`,
+since the tag filter applies even to an explicitly named class.
+
 Regenerate after editing `.fbs`/`.proto` (both generators are in-house, no external tools):
 
 ```bash

docs/compatibility.md

@@ -55,7 +55,7 @@ oracle) — a zero-diff proves every value survived the Python-write / Java-read
 
 ```bash
 scripts/hydrate-raincloud-corpus.sh --max-mb 200      # cache → mirror → local build
-./mvnw verify -pl integration -am -Dit.test=RaincloudConformanceIntegrationTest
+./mvnw verify -pl integration -am -Dvortex.it.excludedGroups= -Dit.test=RaincloudConformanceIntegrationTest
 ```
 
 Per-slug status lives in `integration/src/test/resources/raincloud/expected-status.csv`

integration/pom.xml

@@ -14,6 +14,11 @@
 
 	<properties>
 		<maven.deploy.skip>true</maven.deploy.skip>
+		<!-- JUnit tags excluded from a routine `./mvnw verify`. Defaults to `raincloud` so the
+		     real-world Raincloud corpus tests never run by default — see the failsafe plugin
+		     config below. Override on the CLI to opt in, e.g. `-Dvortex.it.excludedGroups=`
+		     (empty) runs every tag; a literal pom value could not be cleared this way. -->
+		<vortex.it.excludedGroups>raincloud</vortex.it.excludedGroups>
 	</properties>
 
 	<dependencies>
@@ -203,6 +208,16 @@
 					<includes>
 						<include>**/*IntegrationTest.java</include>
 					</includes>
+					<!-- Exclude the real-world Raincloud corpus tests from a routine
+					     `./mvnw verify`: they only do real work when the corpus is hydrated
+					     locally, and the size-comparison test in particular runs a CPU-heavy
+					     Parquet->Vortex re-encode per slug that a developer would not expect
+					     from a default build. Bound to a property (not a literal) so the CLI
+					     can clear it: `-Dvortex.it.excludedGroups=` opts every raincloud test
+					     back in. This exclusion filters even an explicit `-Dit.test=Raincloud...`
+					     class selection, so running a raincloud test always requires clearing
+					     the property as well. -->
+					<excludedGroups>${vortex.it.excludedGroups}</excludedGroups>
 					<argLine>
 						@{argLine}
 						--add-opens java.base/java.nio=ALL-UNNAMED

integration/src/test/java/io/github/dfa1/vortex/integration/RaincloudConformanceIntegrationTest.java

@@ -12,6 +12,7 @@
 import io.github.dfa1.vortex.csv.CsvExporter;
 import io.github.dfa1.vortex.csv.ExportOptions;
 import org.junit.jupiter.api.DynamicTest;
+import org.junit.jupiter.api.Tag;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.TestFactory;
 import org.junit.jupiter.api.parallel.Execution;
@@ -55,6 +56,14 @@
 /// Expected per-slug status lives in `src/test/resources/raincloud/expected-status.csv`.
 /// Known gaps assert that the failure still occurs, so fixing the reader forces the
 /// matrix entry to flip to `ok` in the same change.
+///
+/// Tagged `raincloud` and excluded from the default `./mvnw verify` (via the failsafe
+/// `excludedGroups` configuration) so a routine build never runs the real corpus even on
+/// a developer machine that has hydrated it locally. The exclusion applies even to an
+/// explicit `-Dit.test=RaincloudConformanceIntegrationTest` selection, so running it
+/// requires clearing the tag filter first: `-Dvortex.it.excludedGroups=
+/// -Dit.test=RaincloudConformanceIntegrationTest`.
+@Tag("raincloud")
 class RaincloudConformanceIntegrationTest {
 
     private static final Path DEFAULT_MANIFEST =

integration/src/test/java/io/github/dfa1/vortex/integration/RaincloudSizeComparisonIntegrationTest.java

@@ -2,6 +2,7 @@
 
 import io.github.dfa1.vortex.parquet.ParquetImporter;
 import org.junit.jupiter.api.DynamicTest;
+import org.junit.jupiter.api.Tag;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.TestFactory;
 import org.junit.jupiter.api.parallel.Execution;
@@ -25,6 +26,14 @@
 /// Skipped (visibly) when the corpus is not hydrated — run
 /// `scripts/hydrate-raincloud-corpus.sh` first, or point `RAINCLOUD_CORPUS_MANIFEST`
 /// at a manifest TSV (`slug<TAB>vortex-path<TAB>parquet-path` per line).
+///
+/// Tagged `raincloud` and excluded from the default `./mvnw verify` (via the failsafe
+/// `excludedGroups` configuration): this purely-informational, CPU-heavy re-encode never
+/// gates a routine build, even on a developer machine that has hydrated the corpus locally.
+/// The exclusion applies even to an explicit `-Dit.test=RaincloudSizeComparisonIntegrationTest`
+/// selection, so running it requires clearing the tag filter first:
+/// `-Dvortex.it.excludedGroups= -Dit.test=RaincloudSizeComparisonIntegrationTest`.
+@Tag("raincloud")
 class RaincloudSizeComparisonIntegrationTest {
 
     private static final Path DEFAULT_MANIFEST =

scripts/hydrate-raincloud-corpus.sh

@@ -10,6 +10,11 @@
 # Usage:
 #   scripts/hydrate-raincloud-corpus.sh [--max-mb N] [slug ...]
 #
+# The conformance test is @Tag("raincloud") and excluded from a routine `./mvnw verify`,
+# so after hydrating run it explicitly with the tag exclusion cleared:
+#   ./mvnw verify -pl integration -am -Dvortex.it.excludedGroups= \
+#       -Dit.test=RaincloudConformanceIntegrationTest
+#
 # With no slugs, hydrates every entry of the conformance matrix
 # (integration/src/test/resources/raincloud/expected-status.csv) whose combined
 # artifact size fits --max-mb (default 200; use --max-mb 0 for no size cap — the
@@ -115,4 +120,6 @@ with open(os.environ["MANIFEST"], "w") as manifest:
         hydrated += 1
         print(f"ok   {slug}")
 print(f"\nhydrated={hydrated} skipped={skipped} manifest={os.environ['MANIFEST']}")
+print("run: ./mvnw verify -pl integration -am -Dvortex.it.excludedGroups= "
+      "-Dit.test=RaincloudConformanceIntegrationTest")
 PY