Files
ForgeMultipart/JVM_DOWNGRADER_HANDOFF.md
T

211 lines
15 KiB
Markdown

# JVM Downgrader integration handoff
## Current state
The scoped integration is implemented on `algent/java`, building on baseline `65d0cd0`. The three regression fixes
are preserved. `build.gradle` adds two tasks; `StackAnalyserLogic.visitInsn` uses the validated Java 21 pattern switch,
while `JavaTraitRegistration` and `ClassInfoLookup` use Java 21 pattern variables. The nine Scala sources, Scala 2.11.5
dependency, source layout, and normal Gradle entry points remain in place. Production tasks do not read a frozen jar
or any files under `run/jvmdg-trial/`.
The subsequent `StackAnalyser` initializer extraction is recorded in `JAVA_MIGRATION_HANDOFF.md`. The exact-byte
comparisons and frozen-version reproduction below describe checkpoint `5f0e329`; later helper edits need their own
reference comparisons. The current extraction's evidence is in `run/migration-stack-initialization-reference/`.
## Build arrangement
1. Normal Java and joint Scala/Java compilation remain on Java 8. `compileScala` excludes the modern helpers from
javac's inputs, while scalac resolves their declarations through `-sourcepath`. This handles the circular Scala
references without asking Java 8 javac to compile the modern method bodies.
2. `compileModernJava` uses JDK 25 with `--release 21`, against the fresh Java and Scala output directories.
3. `downgradeModernJava` converts the helpers to Java 8. Only the downgraded directory joins the main class outputs,
so tests, Forge, dev/reobfuscated jars, and downstream compilation receive Java 8 bytecode.
The source-path declaration is an explicit Scala-task input. The existing `scalaCompileOptions.force = true` guard
remains to prevent stale joint-compiled Java annotations after generated `Tags.VERSION` changes.
The per-file include/exclude pairs are temporary compiler routing. These Java files still live in the Scala source set,
whose joint compiler would otherwise send them to Java 8 javac. Once the retained Scala/Java dependency cycle is gone,
move the modern cohort behind one source-set or directory boundary; once Scala is gone, compile all Java with the
modern toolchain and remove the exclusions, `-sourcepath` bridge and force guard together.
The bundled `DowngradeFiles` task initially declares outputs only for inputs that already exist during configuration.
`outputs.dirs(outputMap.values())` explicitly declares the directory for clean builds. Raw and downgraded output use
separate directories and normal task dependencies. No stub sources or replacement Scala compiler are needed.
## Modern Java policy and eligibility audit
The consumer-migration checkpoint should follow a bounded modernization pass. The supported runtime goal is the
preferred Java 25 build (2.9.0 beta 3 also supports Java 17 through 26) plus the extended-support Java 8
build. Source modernization is for clearer, safer implementation code; the downgraded artifact remains Java 8
bytecode, so newer syntax alone is not a performance feature.
Use Java 21 as the source ceiling. JVM Downgrader 1.3.5 can accept Java 22 bytecode, but this build's validated
`compileModernJava` task uses `--release 21`, and Java 22 does not add enough here to justify moving the boundary.
Apply these rules:
- Prefer modern syntax in implementation bodies when it removes casts, duplicated branches or error-prone control
flow. Do not rewrite working code solely for style.
- Keep public descriptors, generic signatures and Scala-facing declarations Java-8-shaped. In particular, do not put
records, sealed declarations or modern JDK types on consumer or retained-Scala boundaries.
- Continue using Java 8 library APIs unless a newer API has a concrete benefit and its JVM Downgrader stub/shading and
runtime-provider requirements are deliberately accepted and tested.
- Add source files to the modern task in small independently reviewable batches. Each batch must compare ABI, class
inventory, generated ASM output and relevant behavior before accepting compiler-induced bytecode changes.
- Before marking the branch ready for consumer migration, verify all packaged classes are version 52, no unexpected
JVM Downgrader API references exist, and run the JVM and Forge suites on Java 8 plus packaged smoke tests on the
preferred modern runtime.
### Eligibility result
A disposable clean-build experiment excluded all 224 Java files under `src/main/scala` from joint compilation and
compiled them together through the Java 21 task. All nine retained Scala sources resolved their declarations, all 224
Java sources compiled, JVM Downgrader completed, and packaging/checkstyle completed. This establishes broad technical
eligibility for Java 21 *method bodies*; it does not establish bytecode or behavior equivalence.
The experiment reached 575 passing tests out of 576. The remaining
`MultipartMixinFactoryCharacterizationTest.namesAndFillsThePassThroughTrait` check reported a missing standalone `T`
string constant after the newer javac/JVM Downgrader string-concatenation shape changed. That is exactly why moving all
sources at once is rejected: even source-identical classes can acquire observable bytecode differences that require
individual review. The normal production configuration remains unchanged.
Recommended order:
1. Start with package-private helpers called directly by retained Scala. `JavaTraitRegistration.java` and
`ClassInfoLookup.java` are completed follow-ups; pattern variables remove their checked casts without changing the
Scala-facing declarations. `StackAnalyserLogic.java` remains the original proven example.
2. Continue only where modern syntax produces a concrete control-flow gain. `ScalaSignatureParser.java` is the next
useful candidate because its two result-producing switches can become exhaustive switch expressions.
`ScalaTraitRegistration.java` should not move merely to restyle its erased `Some` checks.
3. Consider public core implementations such as `RedstoneInteractions$.java`, `TileMultipart.java` and the registries
only after the internal batches. Modern method bodies are technically possible, but their published ABI and frozen
behavior make the review cost higher.
4. Defer registered Java trait inputs under `scalatraits/`. Their transformer forbids or rewrites several bytecode
shapes, including inner classes, lambdas, string switches and primitive-array allocation; syntax changes need
transformer-specific fixtures rather than ordinary compilation success.
5. Defer the six `src/main/java` bootstrap/API sources and the separate `src/mixin/java` source. They are not currently
outputs of `downgradeModernJava`, and the simple API declarations have little modernization value. The mixin source
needs an explicit downgraded-output arrangement before using post-Java-8 syntax.
6. Keep Scala companions, `$class` compatibility helpers and other descriptor-preservation facades conservative unless
a specific method body warrants the compiler move. Their binary shape is more valuable than stylistic uniformity.
`RenderPartResolver.java` was initially shortlisted because it is new and package-private in practice, but an isolated
clean trial proved it cannot move alone: joint-compiled `MultipartRenderer$.java` calls it before the modern task runs.
Moving that caller pulls in the public renderer and client-proxy chain. Defer this group until source-layout cleanup can
move the dependency closure without turning one syntax improvement into a broad compiler migration.
The completed `JavaTraitRegistration` batch passes a clean build with all 576 JVM tests and the Java 8 Forge run with
all 289 functional tests. All 450 dev-jar classes remain version 52, the jar has no JVM Downgrader runtime API
references, and all 134 generated ASM dump names and hashes match the pre-change manifest. The helper is absent from
joint output and present only in the raw/downgraded modern directories. Its own class bytes changed as expected under
modern javac/JVM Downgrader, but no source signature or consumer-facing class is changed.
The completed `ClassInfoLookup` batch has the same clean-build, 576-test, Java 8 Forge, 450-class/version-52 and
134-dump results. Its source signatures and package-private visibility are unchanged. JVM Downgrader records nest
metadata as annotations for this helper's anonymous callbacks, but the packaged classes contain no executable JVM
Downgrader API reference and the Java 8 runtime needs no added dependency.
### fastutil audit
GTNHLib 0.11.44 currently contributes `it.unimi.dsi:fastutil:8.5.18` to `compileClasspath`. It does **not** contribute
fastutil to this project's declared `runtimeClasspath`, because GTNHLib is `compileOnly`. Using fastutil from ordinary
FMP code would therefore turn the optional GTNHLib relationship into an undeclared runtime requirement. Do not do that
implicitly; require GTNHLib/fastutil explicitly first if a measured core use justifies it.
The present candidates do not justify that change:
- `JInventoryTile` could replace its temporary `List<Integer>` with `IntArrayList`, but slot lists are small, the code
is a transformer-sensitive registered trait, and the dependency would cost more than the avoided boxing.
- `MultiPartRegistry.nameMap` and `MicroMaterialRegistry.nameMap` could use `Object2IntOpenHashMap`, but they are small,
lifecycle-built registries. Their missing-key behavior is also deliberately characterized. Keep `HashMap`.
- `ControlKeyModifer.map` could use a reference-to-boolean map, but it is publicly exposed as a live `Map` and normally
contains only the connected players. Keep `HashMap`.
- `PacketScheduler` is the only plausible future candidate for an object-to-long map because it accumulates masks and
boxes `long` values. Its collection is private, so a later implementation change can preserve the existing consumer
ABI. Its Scala-map iteration and callback-mutation behavior are intentionally preserved. Defer this completely from
the Java conversion project; revisit only as separately profiled optimization work with a dedicated semantic test
and an explicit runtime dependency decision.
- `TileCache` could only become primitive-keyed by replacing `BlockCoord` with an encoded coordinate. Its live map is
published and its recovery semantics are characterized, so that would be an API/behavior redesign rather than a
fastutil substitution.
Fastutil remains appropriate for a future GTNHLib-gated implementation with a genuinely large or hot primitive
collection, or after FMP deliberately makes it a direct runtime dependency. Its transitive compile availability alone
is not sufficient, and fastutil adoption is out of scope for the Java conversion project.
## Evidence
The actual production patch passes normal and clean builds with 398 freshly compiled JVM tests, 398 frozen JVM
consumer tests, and 237 Java 8 Forge tests, with zero failures/errors/skips. Forge's nested build includes both new
tasks. Spotless and checkstyle pass.
All 445 dev-jar classes remain version 52. With matching version metadata, only `StackAnalyserLogic.class` changes;
all retained Scala classes, ScalaSignature payloads, bridges, models, and other classes are byte-for-byte identical.
The helper itself exactly matches the isolated prototype. All 116 generated ASM dump names and hashes match.
The helper has no JVM Downgrader runtime-stub references, and no runtime dependency was added.
The release jar also contains 445 Java 8 classes, and the sources jar contains the exact modern helper source.
Evidence and runnable checks are under ignored `run/jvmdg-trial/`:
- `production-candidate.log`, `production-clean.log`: actual build/Forge verification.
- `final-normal-build.log`: ordinary build and toolchain inventory without the frozen-version override.
- `integrated-comparison.json`, `verify-integration.ps1`: bytecode, packaging, dump, and test-count checks.
- `frozen-consumers.gradle`: tests using the original compiled JVM consumers.
- `src/`, `reference/`, `artifacts/`: original prototype, frozen baseline, and experiment jars.
- `artifacts/integrated/`, `integrated-test-results/`, `integrated-forge-test-results/`: preserved clean-build evidence.
- `production-integration.patch`: the production changes captured for review.
- `initial-root-handoff.md`: the original handoff before this takeover.
## Limits
Prefer modern syntax where it improves readability and the compilation path supports it, as established by
`5f0e329b`. This can accompany consumer-facing API work without waiting for complete Scala removal. Expand the
scoped path selectively; if parsing, compilation order, ABI or downgrade support blocks a source unit, retain its
working syntax and record the blocker and revisit condition. Do not add fragile workarounds solely for syntax.
The production source tree now contains 231 Java files and nine Scala files / 782 nonblank Scala lines. Of the 224 Java
sources in the Scala source tree, only `StackAnalyserLogic`, `JavaTraitRegistration` and `ClassInfoLookup` bypass joint
compilation. Retained models, trait
metadata, synthetic super accessors, and downstream Scala consumers prevent treating the last nine files as a
mechanical deletion queue. Modern GTNH runtime support does not remove the retained Scala compiler's Java 8
requirement. The main migration plan and working handoff carry the current API/adoption priorities and source counts.
Keep `enableModernJavaSyntax = false`. The global GTNHGradle setting still moves Scala 2.11.5 onto Java 25; the new
helper stage selects its modern compiler explicitly. This supports modern method bodies with declarations that the
old Scala parser understands. Records, sealed declarations, modern API types at Scala boundaries, and references
from joint-compiled Java into the later modern stage need separate compatibility work before expanding the scope.
Modern APIs that downgrade to runtime stubs also require a deliberate runtime-provider decision.
At checkpoint `5f0e329b`, the installed GTNHGradle 2.0.24 build classloader used JVM Downgrader engine/plugin **1.3.5**.
The earlier **1.3.6** number identifies the API dependency configured by global mode, not the engine observed in that
build. The integrated helper's exact match with the original prototype confirmed that its transformation was preserved.
## Reproduce
Normal commands require no init script or special property:
```powershell
.\gradlew.bat --offline build
.\gradlew.bat --offline runFunctionalTestServer
```
For exact frozen-consumer comparison, use the original version string: two frozen tests inlined it. A branch-derived
version otherwise fails those two version assertions. Do not change or recompile the frozen tests to conceal this.
```powershell
$previousTrialVersion = $env:VERSION
try {
$env:VERSION = '1.7.12-git.225+65d0cd0090-dirty'
.\gradlew.bat --stop
.\gradlew.bat --offline -I run/jvmdg-trial/frozen-consumers.gradle clean build jvmdgIntegrationFrozenTest runFunctionalTestServer
.\run\jvmdg-trial\verify-integration.ps1
} finally {
$env:VERSION = $previousTrialVersion
}
```
`sourcepath-probe.gradle` and `integration.gradle` are historical investigation harnesses. The latter duplicates the
adopted task names and must not be loaded alongside the production integration. An init-script-only trial also does
not automatically reach `runFunctionalTestServer`'s nested build; the production patch does.