Write the public surface down, and check it every build

[tamnd]

This is the stability item on the zu-java scorecard, which the clients spec words as: an API stability gate wired in, the tool that tells a reviewer the public surface moved before a user finds out.

api/surface.txt has one line for every exported type and every member a caller outside the module can name, across dev.zudb and dev.zudb.spi. SurfaceTest regenerates it from the compiled classes and compares. A change to the API is then a change to that file, in the same commit, at the top of the diff, rather than an implementation-looking line somebody waves through.

The file name and the place are zu-go's, deliberately. That repository already keeps api/surface.txt in the shape of the api/go1.N.txt files the language holds itself to, and a reviewer moving between the clients should not have to learn a second mechanism. Write it with mvn -pl zudb test -Dzu.surface.write=true, which is the one command to reach for when the change was meant, and running it is how you say so.

There is no japicmp and no revapi here, and that is on purpose rather than for want of trying. Both compare against a published baseline, and nothing is published yet, so on this repository today they would either compare against nothing or hold the client to a version that does not exist. A checked-in file compares against the last commit instead, which is the thing a reviewer is actually looking at, and it goes on working the same way after the first release.

One thing worth reading in the test. Nothing in the generated file comes from Class.toGenericString, because that method is not the same on every JDK the api job builds for. JDK 21 leaves the sealed marker out of it and JDK 25 puts it in, so the first version of this passed locally and would have gone red on two rows of the matrix for a change nobody made. A gate that cries wolf on the version matrix is a gate people turn off. Everything is spelled out off the class file instead: modifiers masked to what a caller can see, the kind, the type parameters, the permitted subclasses, the supertype and the interfaces, and the same for members. Checked on both JDK 21 and JDK 25 and the output is byte for byte identical.

The failure prints only the lines that moved:

the public surface moved and api/surface.txt did not:
  + method public long dev.zudb.Result.rows()
  - method public long dev.zudb.Result.rowsRenamed()

A name that arrived is a minor release. A name that went or changed shape is a major one, or a mistake.

There is a second test asserting the generator found something, because a generator that quietly found nothing would make every future change pass, and that is the one failure this test cannot report on itself.

No CI change is needed. The api job already runs mvn -pl zudb -am test on 17, 21, 25 and 26-ea, so the gate runs four times per push and reads nothing but the compiled classes, which means it answers on a clone with no library staged and no Rust installed.

Checked on a Linux box: the gate passes, and it bites when the file and the code disagree. The full reactor is green, API, TCK, Panama, JNI, Arrow and benchmarks.

The README gains the inside-the-repository table the other clients have, with the paragraph that says what the file is and how to regenerate it.