build: enforce javadoc references at verify

CLAUDE.md claimed javadoc was "build-enforced: failOnError +
failOnWarnings". Neither was configured anywhere and the plugin was not
bound to any phase, so nothing ran it. That is how the seven broken
references fixed in the previous commit accumulated unnoticed.

Binds javadoc-no-fork to verify with failOnError=true, so a dangling
[Type#member] link fails the build. verify rather than test, so
contributors running ./mvnw test do not pay for it; the whole reactor
costs ~3s. Confirmed to bite by pointing StructArray at a non-existent
type and watching the build go red.

failOnWarnings stays off globally: 313 warnings predate the check
(performance 100, reader 82, writer 42, fbs-gen 35, csv 34, parquet 14,
cli 6), and gating on them would mean a 313-item cleanup before anything
else can merge. core and fsst are already at zero, so their POMs raise
failOnWarnings to hold that line — a ratchet other modules can join as
they are cleared, rather than one flag day. Confirmed to bite with a
probe class carrying an undocumented parameter.

CLAUDE.md now describes what is actually enforced, where, and why the
two levels differ. It also records that bare `./mvnw javadoc:javadoc`
fails on dependency resolution rather than javadoc (no lifecycle phase
runs, so reactor jars are absent and install is forbidden), and that a
target the module cannot see is an error too — the writer/reader and
fbs-gen/core.fbs cases from the previous commit.

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

Author: dfa1

CLAUDE.md

@@ -289,15 +289,33 @@ single audit found phantom APIs, dead service files, and pre-refactor FQNs acros
   Exception: low-level JDK interop taking `long ns` (`Thread.sleep`, `LockSupport.parkNanos`,
   `System.nanoTime` math) — convert at the call site via `duration.toNanos()`/`toMillis()`.
 
-### Javadoc (build-enforced: `failOnError` + `failOnWarnings`)
+### Javadoc
+
+Run by `javadoc-no-fork` bound to `verify` (~3s across the reactor), so `./mvnw test` skips it
+and `./mvnw verify` enforces it. Two enforcement levels:
+
+- **Everywhere: `failOnError`.** A dangling `[Type#member]` reference fails the build. This is
+  the class of rot that actually accumulates — a refactor renames something and the docs keep
+  pointing at the old name.
+- **`core` and `fsst` only: `failOnWarnings`.** Both are warning-free; their POMs raise the bar
+  to keep them there. The other modules carry 313 pre-existing warnings (missing `@param`,
+  undocumented default constructors) — concentrated in `performance`, `reader`, `writer`,
+  `fbs-gen`, `csv` — so warnings stay non-fatal there until someone clears a module and adds
+  the same override to its POM.
+
+Style rules (aspirational in the un-ratcheted modules, enforced in `core`/`fsst`):
 
 - Every public method: main prose description, `@param` per parameter, `@return` (unless `void`).
   Every public record: `@param` per component on the class doc. `@see`-only counts as no description.
 - All `///` Markdown — **no HTML** (checkstyle `RegexpSingleline` blocks `<p>`,`<ul>`,`<li>`,
   `<strong>`,`<pre>`,`<table>`, …). Use blank `///` for paragraphs, `- ` lists, ` ```java ``` `,
   `**bold**`. Cross-refs `[ClassName#method(ParamType)]` — verify the target exists (wrong refs are
-  **errors**).
-- Check: `./mvnw javadoc:javadoc -pl core` must produce zero output.
+  **errors**). A target the module cannot see is also an error: writer must not link to reader
+  types, and `fbs-gen` must not link to the `core.fbs` classes it generates — name those in
+  backticks instead.
+- Ad-hoc check: `./mvnw package -DskipTests javadoc:javadoc -fae`. The bare
+  `./mvnw javadoc:javadoc` fails on dependency resolution, not javadoc — the goal runs no
+  lifecycle phase, so the reactor jars do not exist and `install` is forbidden.
 
 ### Encoding class structure
 

core/pom.xml

@@ -35,6 +35,16 @@
 
 	<build>
 		<plugins>
+			<!-- Ratchet: core's javadoc is warning-free today, so keep it that way. The
+			     parent leaves failOnWarnings off because 313 warnings predate the check in
+			     other modules; nothing stops the already-clean ones from holding the line. -->
+			<plugin>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-javadoc-plugin</artifactId>
+				<configuration>
+					<failOnWarnings>true</failOnWarnings>
+				</configuration>
+			</plugin>
 			<!-- Publish a test-jar so reader/ and writer/ tests can reuse core test
 			     helpers (DTypes, EncodeTestHelper) without duplication. -->
 			<plugin>

fsst/pom.xml

@@ -28,4 +28,19 @@
 			<scope>test</scope>
 		</dependency>
 	</dependencies>
+
+	<build>
+		<plugins>
+			<!-- Ratchet: fsst's javadoc is warning-free today, so keep it that way. The
+			     parent leaves failOnWarnings off because 313 warnings predate the check in
+			     other modules; nothing stops the already-clean ones from holding the line. -->
+			<plugin>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-javadoc-plugin</artifactId>
+				<configuration>
+					<failOnWarnings>true</failOnWarnings>
+				</configuration>
+			</plugin>
+		</plugins>
+	</build>
 </project>

pom.xml

@@ -424,7 +424,28 @@
 					<version>${maven-javadoc-plugin.version}</version>
 					<configuration>
 						<excludePackageNames>io.github.dfa1.vortex.core.fbs:io.github.dfa1.vortex.core.proto</excludePackageNames>
+						<!-- A dangling [Type#member] reference is a build failure: it means a
+						     refactor renamed or moved something and left the docs pointing at a
+						     type that no longer exists. Four such phantoms accumulated before
+						     this was enforced. Warnings (missing @param, undocumented default
+						     constructors) stay non-fatal for now — 313 of them predate this,
+						     concentrated in performance/reader/writer/fbs-gen/csv. Modules that
+						     are already warning-free raise failOnWarnings in their own POM to
+						     stop the count creeping back up. -->
+						<failOnError>true</failOnError>
+						<failOnWarnings>false</failOnWarnings>
 					</configuration>
+					<executions>
+						<execution>
+							<!-- verify, not test: contributors running ./mvnw test skip it, CI does not.
+							     Costs ~3s across the whole reactor. -->
+							<id>check-javadoc</id>
+							<phase>verify</phase>
+							<goals>
+								<goal>javadoc-no-fork</goal>
+							</goals>
+						</execution>
+					</executions>
 				</plugin>
 				<plugin>
 					<groupId>org.apache.maven.plugins</groupId>
@@ -474,6 +495,10 @@
 				<groupId>org.apache.maven.plugins</groupId>
 				<artifactId>maven-checkstyle-plugin</artifactId>
 			</plugin>
+			<plugin>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-javadoc-plugin</artifactId>
+			</plugin>
 			<plugin>
 				<groupId>org.apache.maven.plugins</groupId>
 				<artifactId>maven-dependency-plugin</artifactId>