Java Core Report — the third core, built in isolation

Date: 2026-09-29 · Status: Draft 1 · Purpose: the deliverable docs/17-m2-implementer-brief.md §5 asks of every core, for the Java core (docs/27-core-java.md, workstream WS-I): the isolation statement with its single-implementer statement (docs/26 §2.2), the result, the divergence list (delivered even though it is empty), every place the specification or a design document was ambiguous, silent or wrong even where the guess was right, the dependency deviations from docs/27 §2, and the resolution of its [VERIFY] flags. It is written in the shape of docs/18-m2-report.md, the TypeScript core’s report, and styled after docs/06-verification-log.md.

The code: core/java/. The report: ./gradlew -q vectors, emitting the docs/14 §4 report. The record, stage by stage: docs/27 §8, and the WS-I entries of docs/07 §7 dated 2026-09-23 to 2026-09-29.

1. Isolation statement

The prohibition of docs/17 §1, extended by docs/26 §2.2 to the Phase 2 cores, was followed: core/python/**, core/typescript/**, core/dotnet/** and tools/vector-gen/** were not opened, read, grepped or listed by any session that wrote this core. Each stage’s docs/07 §7 entry says so. The implementer’s reading path is the one at the top of docs/27: docs/02 (the authority), docs/27, docs/08 §4–§6, docs/09, docs/14 §4, docs/17, and vectors/ itself.

The read inputs are not only the specification. Three of them carry more than the spec, and each is named here, as docs/26 §2.2 requires:

1. docs/27 itself. Its header says what its authors read: the 2026-09-19 design reviewer read the TypeScript harness (core/typescript/tests/harness/run.ts), and the session that wrote the document had read small ranges of that harness, of core/typescript/src/registry.ts and of core/python/tests/run_vectors.py while implementing G26. Where docs/27 states a fact about the shipped cores, it cites a document for it, but the facts reached this core through a document whose authors had read code.
2. docs/18, the TypeScript core’s report, is cited from docs/27 and was within reach. Several of its pins are the pins this core declares: decrypt-order and aad-mismatch (D-02), api-boundary-order (D-04), and the refusal of a configured 0xFF02 (D-12). Agreement between the two cores on those pins is therefore not independent evidence, and should not be read as two implementers reaching one answer.
3. docs/10 §4–§7 and docs/11 §4–§7, the other two binding documents, were read at S5 for the shape of the blind-index API (docs/07 §7, 2026-09-27, the S5 entry). Binding documents are specifications, not implementations, but the API shape they describe was the other cores’ before it was this one’s.

Disclosures. Everything below reached a WS-I session by a route other than a checkout of the forbidden trees. None of it is a value, a label, an encoding or an order that a vector checks. Each is recorded, so the record is complete rather than merely clean:

No Java code was written from any of them. X-4 is the one that shaped this core: the skewed field would otherwise have waited for a vector or a doc fix, and J-06 says what the gap was.

Single-implementer statement, in docs/18 §1’s form. This core was written by an AI assistant (Claude), in a sequence of sessions directed by the project’s maintainer, each without the earlier sessions’ context beyond the repository and the tracker. The Python core, the TypeScript core and the vector generator were, per the repository’s log, written by the same maintainer with the same class of assistant in earlier sessions, and docs/18 §1 says the same of the TypeScript core. The isolation is therefore at the level of sessions, not authors: no session that wrote this core had the others’ contents in memory, and a hard prohibition kept it from reading them. docs/25 §6 records that this weakens the independence claim, and docs/26 §2.2 that Phase 2 does not change the arrangement. What the protocol can still find is an ambiguity in the specification, because two sessions reading an unclear clause can resolve it differently, and §3 lists every place that happened or could have. What it cannot find is a misreading the assistant makes the same way every time: the same reader cannot find their own misreading, and three cores agreeing on it would look exactly like three cores agreeing on the truth. §3’s entries are the clauses a human reviewer should check with that risk in mind.

The order of work docs/17 §3 requires was followed: each module was written from the specification first, the vectors were run once the code compiled, and no constant, label, order or encoding was adjusted to make a vector pass. §2 is the result.

2. Result

Every vector in every file listed in MANIFEST.files passes, in both directions where the family requires it. The mismatch list is empty: at each stage that ran vectors, every value passed on the first run (docs/07 §7: S4a and S4b, 2026-09-25; S5 and S6, 2026-09-27; the declaration vectors, 2026-09-27; S7, 2026-09-28). S4b’s first run had seven failures, all the harness’s own: it read a context from the is_ciphertext vectors, which carry none.

On the head that adds this report, ./gradlew -q vectors prints vector suite 0.10.0-provisional: 193 results, 193 pass, 0 fail, 0 skipped; 3 out-of-band; L0 true, and exits 0.

compare_result_ids.py --cores python,typescript,java finds the 193 synchronous and 3 out-of-band result ids identical across the three cores (cross-core-result-ids, in CI since S6). In the cross job (docs/14 §3), the Java consumer decrypts and re-derives every case of all five producers’ documents, its own included (16 envelope and 11 index cases from each core, 6 and 6 from Django, 11 and 7 from Prisma), and the Python and TypeScript consumers decrypt and re-derive the Java document: the three-core 3×3 that docs/26 §3 asks of P2-M1, inside the five-by-three job (docs/07 §7, 2026-09-28, the S7 entry).

Beyond the vectors, ./gradlew build runs 535 tests (172 in fieldseal-core, 361 in the testing module, and one each in unarmedTest and freshJvmTest, which run in JVMs of their own), none failing. They cover what vectors cannot express (docs/17 §5 item 3): the §4.8 arming gate and what it deliberately does not gate, the §10.3 read modes, the docs/08 §6 arming gate of the testing artifact and the rule that production encrypt takes no caller-supplied nonce or seed (PublicSurfaceTest), the order of refusals at the API boundary, the length seam with zero provider calls, key-material ownership, the cache and providers, the docs/09 §1 dependency rules, and the vendored Unicode tables against ICU4J over every code point. core/java/scripts/bite_checks.py holds one mutation per guard; each must turn its tests red after a green control run. The count on this report’s final head is in its PR and its docs/07 §7 entry.

What this does and does not establish. A third implementation, written without reading the other two, agrees with them byte for byte on every published expected value of the pinned suite, and decrypts what they write and they what it writes. That is L0 conformance to the provisional suite 0xFF01 at 0.10.0-provisional, not to any frozen format: none exists until Gate 0b (PRD §8). Its two length-bound entries are passes through a seam, not direct: byte[] lengths are int, so a 2³¹-byte operand does not exist on this platform and the refusal is proven on synthetic operands through the pipeline every public entry point enters (docs/27 §6.2, §6.5). Any level claim quoted outside the report names them (docs/14 §4). And §1 says what kind of independence the agreement has.

Also added at S8, for G14. docs/27 §5.2 had promised to record what this core accepts as a KDF info, so that G14’s resolution (#43) can be checked against it. It accepts any length: HKDF is written over Mac, which caps nothing, and canonical_context and the AAD are refused only past Integer.MAX_VALUE bytes, as an OutOfMemoryError (CanonicalContext, by the same rule as the codec’s, docs/27 §6.1). That last clause is by construction and not tested, since a test would need arrays of 2 GiB. What is tested is LargeContextTest: 70,000-byte tenant_id and row_id, past the 1,024-byte and 32 KiB caps spec §6.1 names, round-trip through encrypt, decrypt and rotate; the last byte of tenant_id changes the index key, which never carries row_id (spec §7.2); and the last byte of each field changes the record key. Only the last byte is varied, so the tests show that the end of a 70,000-byte field reaches the derivation, past both caps, not that every byte before it does. A bite entry that caps info at 1,024 bytes turns the last two red and leaves the round trip green, because the AAD still carries the whole context.

3. Divergences and ambiguities

The brief’s list (docs/17 §3): for every mismatch, the vector id, the computed and expected values, the clause, and the cause. There were no mismatches. The table is the other half of the deliverable: every place the specification, the vectors or a design document was ambiguous, silent, contradictory or wrong, including where the guess was right. The kinds are those of docs/18 §3, with one added: spec gap (the spec should say it), vector or doc drift (the vectors or a document disagree with the spec or with each other), binding-doc bug (docs/27 was wrong; its header says such a bug belongs here), and pin (a choice the spec leaves open, declared or tested).

Nothing above changed a byte of the envelope. The two that could split cores on real data without any vector noticing are J-11 and J-18, and J-09 joins them the day a second suite can be written. The one that most weakens the protocol’s evidence is not in the table: it is §1’s note that several pins were within reach in docs/18.

4. Dependency deviations and the [VERIFY] sweep

docs/27 §2’s dependency choices were kept: the JDK for AES-256-GCM, HMAC-SHA-512, constant-time comparison and the CSPRNG; HKDF written over Mac; BouncyCastle bcprov-jdk18on 1.86 for Argon2id only, the core’s one runtime dependency since S5; JUnit, jqwik, Jackson, ArchUnit and ICU4J 78.3 for tests only. The deviations, each with its reason:

Every [VERIFY] in docs/27 was resolved at S2 (docs/07 §7, 2026-09-24): GCM through JCA at docs/27 §5.1’s offsets, the empty-salt trap of SecretKeySpec, the strict UTF-8 decoder, BouncyCastle’s Argon2id against all 12 raw values at both pinned cost points, and the runners’ memory, confirmed; SunJCE’s decrypt buffering, corrected (J-16); BouncyCastle’s salt copies and bc-fips’s lack of Argon2, answered. A second library fact was corrected at S6 (J-16). Found without being asked: SunJCE zero-fills a failed tag’s output range; BouncyCastle caps Argon2 memory at 2²⁴ KiB through a system property; and on Temurin 21.0.12 the largest byte[] is 2³¹−3, both locally and on CI’s runner (docs/27 §6.1). No [VERIFY] flag remains in docs/27.

5. Conformance claim

L0 against provisional suite 0xFF01 at vector_suite_version 0.10.0-provisional, from a report with fail: 0, skipped: 0, provisional_suites: true, every out-of-band entry pass with its basis (the length-bound pair through the seam, the lone-surrogate entry directly), and the six mandatory pinned_decisions keys declared. Per spec §4.8 the claim names the provisional identifier and is not restated against a registered one; per PRD §8 it is not a claim against a frozen format, because none exists. No adapter level is claimed. async_companions: false.

6. What was not done

• Suite 0xFF02. Registered and unbuilt while G7 is open; configuring it is a ConfigurationError naming G7.
• The metrics hook of docs/09 §2, and background refresh for the envelope provider, which fails closed and refreshes only through warm.
• A lock-free or fine-grained cache. The DekCache has one lock for the whole cache, short of docs/09 §8.3’s “lock-free or fine-grained-locked reads”; a recorded deviation (docs/27 §5.5).
• Narrowing the per-decrypt DEK copies the envelope provider hands out: #200.
• No mlock and no swap protection, as in the other cores (docs/27 §5.4).
• The other halves of #225 (the Python and TypeScript backing tests), which are separate sessions under the isolation rule.
• Publication. Nothing is on Maven Central, and the group id needs its namespace verified before anything is published under it (docs/27 §0.3). A release would be an experimental pre-1.0 one under PRD §8’s five conditions.
• A test of the OutOfMemoryError past the array limit for an oversized context (J-18): it would need arrays of 2 GiB.

7. Recommended follow-ups, in order of how much they protect the central claim

1. A second human implementer, or Gate 0b. §1’s single-implementer statement is the report’s largest limit, and docs/26 §6 says that only these two fix it.
2. Decide #213 before a second suite or the Hibernate adapter’s registry check, since the answer decides whether a write-suite change re-keys every index (J-09).
3. Pin J-11 and J-04 in vectors: a lone-surrogate and a malformed-UTF-8 value under bucket, and a 0x02 envelope of exactly 111 bytes.
4. Settle G14 (J-18) and G5’s AAD_MISMATCH question (J-19) at Gate 0b; this report gives the Java core’s side of each.
5. Write J-01, J-02 and J-14 into docs/09, so that the .NET and Go cores meet them as rules rather than as failing builds.
6. Fix the two drifts in docs/08 (J-12, J-15), and move the Unicode pin (#209) once ICU4J and Node ICU carry Unicode 18.

View source: docs/28-java-core-report.md