build: restore the core javadoc ratchet, red on CI since 8ff823ec

[dfa1]

CI has been failing on every job of every commit since 8ff823ec — six matrix jobs, all red, on core's failOnWarnings javadoc ratchet. I noticed while trying to merge #346 and found main already red, so this is not a regression from the recent decode work; it predates all of it.

12 warnings, none of them new code:

file	problem
PTypeIO#set	no @param for seg, offset, ptype, bits
PTypeIO#copyArray	no @param for ptype, typedArray, count; no @return
DType#decimal	doc opens with @param, no main description
DType.Extension compact ctor	same
EditionId compact ctor	same
MemorySize compact ctor	same

All are exactly what CLAUDE.md asks for in core ("Every public method: main prose description, @param per parameter, @return").

Why nobody saw it locally

A local ./mvnw verify does not reproduce it. The javadoc plugin's doclint enables its missing group on the Zulu build setup-java resolves for '25'/'26', but not on the Zulu 25.0.2 patch installed on this machine — so the ratchet is genuinely stricter on CI than locally, on the same vendor and major version.

I reproduced it locally with a direct javadoc -Xdoclint:all -sourcepath core/src/main/java io.github.dfa1.vortex.core.io io.github.dfa1.vortex.core.model, which lists exactly the 12 CI reports. That command now reports zero. (It is stricter still than the plugin — it also flags generated core.fbs code that CI does not — so it over-approximates, which is the safe direction for a gate.)

Why fix the tags rather than pin the JDK or relax the ratchet

The tags were genuinely missing; the stricter JDK was right. A check that only fires on some JDKs is still a check worth passing, and the alternative — pinning CI to the JDK that doesn't notice — would leave the docs wrong and the ratchet decorative.

Worth considering separately: the local/CI strictness gap will keep biting. Either the plugin should pass -Xdoclint:all,-missing explicitly so both agree, or the build should pin a JDK patch. I have not done either here — it is a build-policy call, not a bug fix.

./mvnw verify green locally across all 17 modules.

🤖 Generated with Claude Code

[dfa1]

Correction — the explanation in this PR's description is wrong. The fix itself is right (CI went green on all six jobs, and main is green for the first time since 9fcb189), but the cause I gave is not.

I claimed local and CI diverged because setup-java resolves a newer Zulu patch (25.0.4+7) than the 25.0.2 installed here, with stricter doclint. I've now tested that and it is false:

• All three JDKs on this machine — Zulu 25.0.2, GraalVM 25.0.3, OpenJDK 26.0.1 — produce identical doclint output on a synthetic case with the same flags.
• Reverting PTypeIO on this machine and running ./mvnw verify fails locally, with the same warnings CI reported.
• A clean git worktree at 707fca2 (pre-fix main) fails locally with exactly the 12 warnings CI reported.

So local and CI have always been at parity, and ./mvnw verify does catch this. There is no setup gap and nothing to pin — the follow-up I suggested at the bottom of the description (pin a JDK patch, or pass an explicit -Xdoclint) is not needed, and acting on it would have been change based on a wrong diagnosis.

What I cannot explain is why my own ./mvnw verify runs earlier in this session reported BUILD SUCCESS on a tree that demonstrably fails now. I have not reproduced that, and I'm not going to invent a mechanism for it. The practical lesson stands on its own: the gate works, so main going red for as long as it did means nobody was running verify before pushing — which is what the ratchet in 9fcb189 was added to prevent, and it never passed CI on the commit that introduced it.

Also worth noting for anyone reading the history: this PR's commit message carries the same wrong explanation. The change is sound; the reasoning in it is not.