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

A plain `./mvnw verify` silently ran the full real-world Raincloud corpus
whenever a developer had hydrated it locally (via hydrate-raincloud-corpus.sh):
the two Raincloud tests only gated real work behind
`assumeTrue(Files.exists(manifestPath()))`, which is a no-op skip on CI (corpus
never hydrated) but a surprise on a dev machine. In particular
RaincloudSizeComparisonIntegrationTest — documented as purely informational —
does a full Parquet->Vortex re-encode (FSST training, etc.) per slug, costing a
release preflight 15+ minutes of unexpected CPU-heavy work.

Make the exclusion explicit and controllable with JUnit 5 `@Tag`:
- Tag both classes `@Tag("raincloud")`.
- Failsafe `excludedGroups` (integration/pom.xml), bound to a new
  `vortex.it.excludedGroups` property defaulting to `raincloud`, so a routine
  build excludes them from test discovery entirely (stronger than assumeTrue's
  skip) yet the CLI can opt back in.

Verified against a locally hydrated 10-slug corpus:
- `./mvnw verify -pl integration -am` no longer discovers/runs either class.
- Failsafe 3.5.6 applies `excludedGroups` even to an explicitly named
  `-Dit.test=Raincloud...` class, and a literal pom value cannot be cleared
  from the CLI — hence the property indirection. Opting in requires
  `-Dvortex.it.excludedGroups=` in addition to `-Dit.test`. The full
  conformance run (11 tests) passes end-to-end with that flag.

Updated the documented invocations to include the flag: CLAUDE.md Commands
section and the hydrate script's usage/output hints. No CHANGELOG entry:
test/tooling-only churn, no change to shipped artifacts.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: dfa1

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

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,13 @@
 /// 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. Run it explicitly with
+/// `-Dit.test=RaincloudConformanceIntegrationTest` (an explicit class selection overrides
+/// the tag exclusion) or opt every raincloud test back in with `-DexcludedGroups=`.
+@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,13 @@
 /// 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.
+/// Run it explicitly with `-Dit.test=RaincloudSizeComparisonIntegrationTest` or opt every
+/// raincloud test back in with `-DexcludedGroups=`.
+@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