diff --git a/JAVA_MIGRATION.md b/JAVA_MIGRATION.md new file mode 100644 index 0000000..cf59ef2 --- /dev/null +++ b/JAVA_MIGRATION.md @@ -0,0 +1,405 @@ +# Java migration plan and audit findings + +Status: living document +Initial audit: 2026-08-14 +Audited revision: `f10595d` (`master`) + +## Decision summary + +Converting ForgeMultipart to Java is realistic. It should be treated as a staged compatibility migration, not as an automatic source conversion or a ground-up rewrite. + +The main difficulty is preserving behavior and compatibility, not translating Scala syntax. In particular, ForgeMultipart dynamically builds `TileMultipart` subclasses from combinations of part capabilities, and its published bytecode exposes Scala types and Scala compiler artifacts to other mods. + +The current direction is: + +- Preserve observable behavior unless a divergence is an intentional, documented bug fix or performance fix. +- Add clean Java APIs with equivalent features. +- Keep deprecated compatibility bridges for the old Scala-facing API for at least the initial Java release. +- Use the Hodgepodge/GTNH convention for any new Sponge Mixins: UniMixins plus explicit normal, early, and late registration where the target lifecycle requires it. +- Allow GTNHLib as a dependency. Use fastutil selectively for measured primitive-collection or allocation problems, not as a blanket collection replacement. +- Keep ForgeMultipart's runtime composite-tile generator separate from the Sponge Mixin decision until it is proven replaceable. They solve different problems. + +No trustworthy tool will produce a maintainable Java port automatically. A decompiler can help recover control flow or compare generated bytecode, but its output should be used as a reference rather than committed as the implementation. + +## Scope and compatibility target + +“Behave the same” means preserving the following unless a change is explicitly entered in a divergence log: + +- Multipart placement, removal, occlusion, collision, selection, ticking, redstone, rendering, and scheduled-tick behavior. +- Client/server separation and Forge/FML lifecycle timing. +- Part and tile registration order and lookup behavior. +- Part identifiers, NBT keys and structures, saved-world loading, and conversion of existing multipart tiles. +- Packet identifiers, field order, encoding, dispatch timing, and client update behavior. +- Dynamically generated tile interfaces and capabilities expected by parts and integrations. +- Public class names, method descriptors, static entry points, and reflective lookups that supported downstream mods use. +- Behavior in both development and obfuscated production environments. + +Allowed divergences are: + +- Confirmed bug fixes. +- Removal of avoidable allocation, boxing, exception-based control flow, or other performance problems. +- Better failure messages where success-path behavior is unchanged. + +Each divergence should record the old behavior, new behavior, reason, compatibility impact, and how it was manually verified. Unintentional behavior changes are regressions even if the new implementation appears cleaner. + +## Audit findings + +### Codebase size + +At the audited revision: + +| Area | Scala files | Approximate Scala lines | +| --- | ---: | ---: | +| Multipart core | 38 | 4,076 | +| Multipart ASM | 8 | 1,933 | +| Microblocks | 28 | 3,013 | +| **Total** | **74** | **9,022** | + +There are also 19 Java source files with approximately 1,148 lines. The existing README explicitly describes the API as Java-friendly, and the bundled Minecraft multipart implementation already serves as a Java consumer of it. + +The current Scala source compiles successfully with Scala 2.11.5. This gives the migration a working reference implementation rather than requiring recovery of a broken codebase. + +### What Scala currently costs + +The compiled mod contains 635 class files and is approximately 1.64 MiB before its Scala runtime dependency. Compiler-generated artifacts include: + +- 236 `anonfun` closure classes, approximately 448 KiB. +- 39 trait helper `$class` files, approximately 98 KiB. +- 121 object/companion-related class files, approximately 415 KiB. + +These figures support a maintainability and allocation argument for Java, but not the claim that Scala wraps most methods in `try/catch`. + +A scan of 5,126 Scala methods found 52 methods with exception tables and 53 total entries. The important groups were: + +- 33 catch-all/finally handlers, mostly compiler machinery for synchronization and lazy initialization. +- 9 `scala.runtime.NonLocalReturnControl` handlers caused by `return` from inside closures. +- 11 ordinary exception handlers covering `Exception`, `ClassCastException`, `IllegalStateException`, and `IOException`. + +The 222 methods emitted from the Java sources had no exception-table entries in the same scan. + +Exception-table metadata does not impose a meaningful steady-state cost merely by existing. The nine non-local-return sites are different: when the early return is taken, Scala implements it by throwing and catching `NonLocalReturnControl`. Those sites are worth removing, but they do not justify assuming exception overhead across the whole mod. + +### More credible performance risks + +The source and bytecode audit identified allocation patterns that are more plausible performance targets: + +- `TileMultipart.updateEntity()` creates a Scala closure for each ticking multipart tile on each tick, then traverses through `operate(Function1)` and Scala collection machinery. +- `TRedstoneTile` power and connection queries create closures and `scala.runtime.IntRef` boxes in frequently queried code. +- Several Scala 2.11 collection, range, and `JavaConversions` paths create closure objects, boxed primitives, iterators, or temporary collections. +- `TSlottedTile.canAddPart` and several `MicroRecipe` searches use exception-based non-local returns. +- Rendering code in `TileMultipart` already uses cached arrays and `while` loops in important paths. It should be preserved as evidence of deliberate optimization, not mechanically rewritten into streams or higher-level collection pipelines. + +These are static findings, not proof of their share of frame or tick time. Capture profiles and allocation data before and after each relevant migration phase. + +### Runtime code generation is architectural, not incidental + +`MultipartGenerator` selects a tile class from the interfaces required by the parts in a block. `ASMMixinFactory` caches generated constructors by a trait bit set, so class generation is primarily a registration/first-combination cost rather than a per-tick cost. + +`ASMMixinCompiler` already supports two inputs: + +- `registerScalaTrait`, which reads Scala signature data and understands Scala trait output. +- `registerJavaTrait`, which transforms a concrete Java mixin class into the interface/static-helper form used by the generator. + +The Java path rejects Java interfaces, inner classes, abstract classes, static initializers, and constructors with arguments. Those restrictions must be accounted for when converting built-in tile traits, but the path proves that Java implementations can participate in the current composition system. + +`MultipartGenerator.registerPassThroughInterface` also explicitly supports interfaces that generated tiles must expose. This is part of the compatibility surface and must not be lost in a static subclass rewrite. + +The least risky plan is therefore to keep the current composition model during the first Java migration. Port or redesign its ASM implementation only after the rest of the behavior is stable. + +### Public ABI exposes Scala + +Several public descriptors contain Scala runtime types. Examples include: + +- `TileMultipart.partList` exposing `scala.collection.Seq` through generated accessors. +- `TileMultipart.operate` accepting `scala.Function1`. +- Occlusion methods accepting Scala `Seq` values. +- Tile conversion helpers returning `scala.Tuple2`. +- `MultiPartRegistry` overloads accepting Scala `Function2` or `Seq`, and returning `Seq`. +- Scala object singletons (`MODULE$`), companion/static forwarders, and trait `$class` helpers. + +Changing these descriptors directly to `java.util` or `java.util.function` types can cause `NoSuchMethodError`, `NoClassDefFoundError`, or reflective integration failures in already compiled mods. Source compatibility alone is not sufficient. + +This means “all source is Java” and “the Scala runtime is gone” are separate milestones. Deprecated bridges may still require Scala library types even after the implementation is Java. + +## API migration design + +Create a Java-first API with the same capabilities, then make legacy entry points delegate into it. Delegation should have one direction: deprecated Scala bridge to canonical Java implementation. Avoid two independently maintained implementations. + +Candidate mappings, with final names and mutability contracts to be decided from existing behavior: + +| Existing Scala-facing shape | Java-first equivalent | +| --- | --- | +| `Seq` | `List` or a purpose-specific read-only view | +| `Function1` | `Consumer` or direct indexed traversal methods | +| `Function2` factory callbacks | A named Java functional interface with domain-specific arguments and return type | +| `Tuple2` | A small immutable Java result class with named accessors | +| Scala collection overloads in registries | `Collection`, `List`, arrays, or Java `Iterable`, according to actual ordering and mutation semantics | + +Bridge rules: + +- Preserve old JVM descriptors, not merely old source names. +- Mark source-visible legacy APIs deprecated and point their documentation to the Java replacement. +- Preserve ordering, nullability, mutability, exception, and callback timing semantics. +- Keep legacy singleton/static entry points when downstream bytecode may reference them. +- Do not leak new Scala types into the Java API. +- Do not remove Scala library dependencies until an ABI inventory shows that no retained bridge needs them. +- Use `javap` plus an API/ABI comparison tool such as japicmp or Revapi against the reference dev jar at every public-API phase. + +Before implementing bridges, inventory real consumers in the target modpack. Some Scala compiler artifacts may be technically public but unused; others may be load-bearing despite looking internal. + +## Mixin strategy + +Follow the pattern currently used by Hodgepodge for fixed class transformations: + +- Set the GTNH build convention's `usesMixins = true`, which supplies UniMixins integration and declares UniMixins as a required dependency. +- Use a normal/pre-init mixin configuration for transformations that do not require special early or optional-mod timing. +- Use an `IEarlyMixinLoader` configuration only for targets that must be selected before ordinary mod loading. +- Use an `@LateMixin`/`ILateMixinLoader` configuration for optional-mod targets whose presence is known later. +- Centralize selection through the GTNHMixins builder pattern, including side, loaded-coremod, loaded-mod, and configuration gates. +- Keep early and late lists minimal. A mixin should not be early or late merely because those mechanisms are available. +- Prefer Sponge Mixins for fixed transformations of known classes. Retain raw ASM only where a mixin cannot express the required behavior safely. + +The inspected Hodgepodge reference uses: + +- `HodgepodgeCore implements IFMLLoadingPlugin, IEarlyMixinLoader` and delegates early selection to `IMixins.getEarlyMixins(...)`. +- `HodgepodgeLateMixins`, annotated with `@LateMixin`, implementing `ILateMixinLoader` and delegating late selection to `IMixins.getLateMixins(...)`. +- Separate normal, early, and late JSON configurations. +- Explicit dependencies on GTNHMixins and UniMixins. + +Important distinction: Sponge/UniMixins modifies known classes during class loading. ForgeMultipart's current generator creates different tile classes for runtime combinations of part interfaces. The Hodgepodge registration pattern should be used for ordinary patches introduced by this port, but UniMixins is not assumed to replace the composite-tile generator. + +## GTNHLib and fastutil + +GTNHLib is an acceptable dependency for the port. The inspected GTNHLib checkout declares fastutil 8.5.18 as `compileOnlyApi` and uses its dependency-loader/GTNHExtLib arrangement for external runtime libraries. Hodgepodge consumes GTNHLib as an API dependency and imports fastutil through that environment. + +Integration requirements: + +- Select the GTNHLib version aligned with the target pack/release train rather than copying Hodgepodge's current version blindly. +- Verify both compile and production runtime resolution in ForgeMultipart's actual build after adding the dependency. +- Add the Forge mod dependency declaration with a compatible version range. +- Use primitive fastutil collections where they remove boxing or object-key allocation in a demonstrated hot path. +- Prefer JDK collections for small, cold, or API-facing collections unless fastutil provides a concrete benefit. +- Do not expose fastutil implementation classes from the stable public API without a strong reason; ordinary Java interfaces keep consumers decoupled. + +Candidate areas to measure include redstone query state, coordinate-keyed caches, scheduler structures, registry lookups, and render/tile scratch collections. A primitive map is only useful if the key can be represented without first allocating a wrapper such as `BlockCoord`. + +GTNHLib's ASM utilities may also reduce low-level boilerplate when the runtime generator is eventually ported. Evaluate them against the generator's exact needs instead of changing ASM APIs during the earlier source migration. + +## Migration phases + +Every implementation phase follows the same test-first gate: + +1. Write characterization tests against the current Scala implementation for the area about to change. +2. Run them on the untouched implementation and retain any golden fixtures they produce. +3. Commit the tests separately from the port so the baseline is reviewable. +4. Replace the implementation while leaving the tests unchanged. +5. Require the same tests to pass before moving to the next area. + +If a characterization test captures a confirmed bug that the port intentionally fixes, record it in the divergence log and change that expectation in a separate, explicit bug-fix step. This prevents accidental changes from being presented as fixes. + +### Phase 0 — Freeze and measure the reference behavior + +- [x] Produce and retain a reference dev jar from `f10595d` or the selected migration base. +- [ ] Dump the public/protected JVM API and important generated tile class shapes. +- [ ] Inventory downstream mods that compile against or reflect into ForgeMultipart. +- [ ] Record part IDs, NBT layouts, packet layouts, registration order, and side/lifecycle behavior. +- [x] Add a Java-8-compatible JUnit/Jupiter setup to the existing Gradle `test` task. +- [ ] Add a separate Forge integration-test source set/runner for behavior that cannot execute in a plain JVM. +- [x] Write the first characterization suite against the untouched Scala implementation. +- [ ] Create a remaining manual compatibility checklist for rendering, input, and other behavior that cannot be asserted reliably by the automated harness. +- [ ] Capture representative CPU and allocation profiles before optimization work. +- [ ] Start a divergence log; it should initially be empty. + +Exit condition: there is a reproducible behavior and ABI baseline, the test layers run in CI or an equivalent repeatable command, and the initial suite passes against the Scala implementation. + +### Phase 1 — Add infrastructure only when first needed + +- [ ] Add GTNHLib with a pack-aligned version when the first Java migration or data-structure change uses it. +- [ ] Enable UniMixins when the first fixed class transformation is introduced. +- [ ] Copy the Hodgepodge loader/config structure selectively: normal by default, early/late only for demonstrated lifecycle needs. +- [ ] Confirm client and dedicated-server startup after each dependency or loader change. + +Exit condition: dependencies and loaders are present with no unintended gameplay behavior change. + +### Phase 2 — Establish the Java-first API and compatibility bridges + +- [ ] Inventory every public Scala descriptor and compiler-generated entry point used by downstream code. +- [ ] Add ABI snapshots and compiled consumer fixtures before changing public descriptors. +- [ ] Define Java collection, callback, and result types with documented behavior equivalent to the current API. +- [ ] Implement the canonical behavior once in Java. +- [ ] Keep deprecated Scala signatures and singleton/static entry points as thin adapters. +- [ ] Compare the produced jar with the reference API and verify representative Java and Scala consumers can load. + +Exit condition: new code can use a clean Java API while existing supported binaries still link through the deprecated surface. + +### Phase 3 — Convert low-coupling code + +- [ ] Characterize each related leaf group before converting it. +- [ ] Convert constants, value holders, simple utilities, registries, packet data helpers, and leaf classes first. +- [ ] Replace `JavaConversions` with explicit Java collections or controlled adapters. +- [ ] Preserve iteration order and null behavior. +- [ ] Keep mixed Scala/Java compilation working throughout the phase. + +Exit condition: leaf code is Java and no longer generates avoidable Scala closures or collection adapters. + +### Phase 4 — Convert measured hot paths + +- [ ] Characterize result ordering, callback timing, early exits, and edge cases before changing traversal code. +- [ ] Rewrite `TileMultipart.updateEntity()` as allocation-free indexed or array traversal. +- [ ] Rewrite redstone queries without closure allocation or `IntRef` boxing. +- [ ] Replace non-local returns in slot/recipe scans with ordinary Java control flow. +- [ ] Use fastutil only where profiling and data shape justify it. +- [ ] Re-profile the same scenarios and record both improvements and regressions. + +Exit condition: identified steady-state Scala allocation sites are removed with compatible results. + +### Phase 5 — Convert built-in tile traits through the existing Java path + +- [ ] Characterize the interfaces, fields, lifecycle callbacks, and behavior of the Scala-generated pilot tile. +- [ ] Port one simple built-in trait as a pilot using `registerJavaTrait`. +- [ ] Verify generated methods, interfaces, field initialization, lifecycle callbacks, and class caching against the Scala version. +- [ ] Convert remaining traits in small related groups. +- [ ] Document or deliberately relax the Java trait restrictions only when a real trait requires it. +- [ ] Preserve pass-through interface behavior. + +Exit condition: built-in behavior is implemented in Java while the established runtime composition mechanism remains stable. + +### Phase 6 — Convert multipart core and microblocks + +- [ ] Add characterization coverage for each subsystem immediately before its conversion. +- [ ] Convert the central tile, part, registry, placement, rendering, networking, scheduler, and microblock code in dependency order. +- [ ] Treat NBT, packets, registration, client/server separation, and rendering state as compatibility-critical. +- [ ] Keep recipe scan order and output semantics stable while replacing exception-based early exits. +- [ ] Check source and binary compatibility at each public boundary. + +Exit condition: normal runtime implementation is Java; any remaining Scala is isolated to compatibility or ASM support. + +### Phase 7 — Port the ASM subsystem last + +- [ ] Freeze structural and behavioral fixtures for generated classes before changing the compiler. +- [ ] Translate the existing compiler/generator into readable Java while preserving emitted class shapes and cache keys. +- [ ] Evaluate GTNHLib ASM helpers where they reduce boilerplate without altering semantics. +- [ ] Keep Scala-trait registration while deprecated bridges or supported external Scala traits require it. +- [ ] Decide separately whether a future generator design can avoid custom bytecode generation. Do not couple that experiment to the source-language port. + +Exit condition: the composition subsystem is maintainable Java with behavior and generated ABI verified against the reference. + +### Phase 8 — Decide on Scala runtime removal + +- [ ] Measure actual downstream use of Scala descriptors, Scala traits, object singletons, and `$class` helpers. +- [ ] Publish and complete a deprecation window if compatibility policy permits removal. +- [ ] Remove Scala bridges, Scala signature decoding, and the Scala compiler/runtime dependency only in a release allowed to break that ABI. +- [ ] Confirm no Scala types remain in published descriptors or runtime loading paths. + +Exit condition: Scala removal is either completed deliberately or explicitly deferred as the cost of binary compatibility. + +## Risk order + +| Risk | Work | +| --- | --- | +| Low | Leaf utilities, value holders, straightforward packets, isolated Java API facades | +| Medium | Registries, recipes, placement logic, render helpers, schedulers, hot-loop rewrites | +| High | `TileMultipart`, networking/NBT compatibility, tile trait conversion, external API bridges | +| Very high | Runtime composite generator, Scala trait compatibility, removal of Scala runtime | + +The work should move from low to high risk while keeping a buildable mixed-language repository. A one-shot conversion would combine source, ABI, lifecycle, data-format, and bytecode-generation failures and make regressions difficult to localize. + +## Characterization and compatibility test strategy + +Extensive tests are both possible and recommended here. Their purpose is not to prove that the current Scala behavior is ideal; it is to make its observable behavior explicit before translation, so every later difference is intentional. + +The repository currently has no test sources or test dependencies. The GTNH Gradle convention and Scala plugin provide a normal Gradle test path, so no custom framework is needed for deterministic logic. Minecraft 1.7.10 does not provide the modern GameTest framework, therefore game-dependent coverage needs a small Forge integration harness rather than pretending all Minecraft behavior can run in an ordinary unit test. + +### Layer 1 — Plain JVM characterization tests + +Run fast tests through the normal Gradle `test` task, using real implementation classes and small fakes only at world, network, or rendering boundaries. Good targets include: + +- Slot masks, part lookup, occlusion and collision decisions. +- Placement grids, side transforms, microblock shape calculations, and recipe matching. +- Registry ordering, duplicate handling, missing-entry behavior, and callback order. +- Scheduler ordering and cancellation with a deterministic clock or tick source. +- Redstone connection and power matrices for all six sides and relevant masks. +- Packet codec logic that does not require a live channel. +- NBT read/write logic that can use real `NBTTagCompound` values without starting Forge. + +Finite input spaces such as sides, slot masks, and small recipe grids should be covered exhaustively. Larger combinations should use named regression cases plus deterministic property/fuzz tests with a recorded seed. Avoid tests that merely restate the implementation or assert interactions with a large graph of mocks. + +### Layer 2 — Golden compatibility fixtures + +Store compact fixtures under test resources when behavior has a stable serialized or structural representation: + +- Canonicalized NBT trees including names, types, values, missing fields, and legacy data; do not depend on unspecified compound-key iteration order. +- Exact packet bytes for representative updates and malformed/truncated input behavior. +- Part identifiers, registration order, and conversion results. +- Public/protected JVM descriptors and required Scala bridge entry points. +- Generated tile superclass, interfaces, fields, methods, access flags, and cache identity. Compare structure and behavior rather than raw class bytes or constant-pool order. +- Small precompiled Java and Scala consumer fixtures built once against the reference dev jar, then loaded against the migrated jar to catch binary linkage failures that source recompilation would hide. + +Golden fixtures must be reviewed rather than regenerated automatically when they fail. Otherwise an accidental change can silently redefine the baseline. + +### Layer 3 — Real Forge integration tests + +Use a dedicated test mod/source set launched in an actual Forge environment for behavior coupled to FML, the classloader, worlds, or networking. The harness should fail the Gradle task or process when an assertion fails. It should cover: + +- Client and dedicated-server startup, mod lifecycle order, mixin selection, and side-only class safety. +- Registration and creation of representative dynamic tile combinations. +- Add/remove part sequences, ticking, scheduled ticks, redstone neighbor updates, and chunk unload/reload. +- Save with the reference implementation and load with the migrated implementation. +- Server-to-client part description and incremental update packets. +- Loading representative downstream binaries compiled against the reference API. + +Keep this harness narrow: a tiny test mod and deterministic scenarios are preferable to a general automation framework. Run server cases routinely; reserve the slower client cases for changes that touch rendering, client packets, or side-specific initialization. + +### Layer 4 — Irreducible manual and performance checks + +Some behavior remains poorly captured by assertions in a legacy client. Retain focused manual checks for visual correctness, selection boxes, particles, input interaction, resource reload, and third-party rendering compatibility. Screenshot comparisons can help, but GPU and renderer differences make them unsuitable as the only oracle. + +Performance fixes require the same CPU/allocation scenario before and after the change. Functional tests can prove equivalent results, but they cannot prove reduced allocations or better tick time. + +### Coverage rule + +Coverage percentage is not the goal. The required evidence for an area is: + +- Normal behavior, edge cases, invalid input, ordering, and state transitions are represented. +- Compatibility-sensitive bytes, NBT, identifiers, descriptors, and generated interfaces are frozen where applicable. +- At least one real Forge scenario covers code that depends on lifecycle or world state. +- The tests demonstrably pass against the old Scala area before any Java replacement begins. +- The same tests pass unchanged against the Java implementation, except for separately documented bug fixes. + +## Open decisions + +These decisions should be made from ecosystem evidence rather than assumed during translation: + +1. Which existing downstream binaries must keep working without recompilation? +2. Are third-party Scala traits registered through `registerScalaTrait`, or is that path only used internally? +3. How long should deprecated Scala bridges remain supported? +4. Is complete Scala runtime removal required for the first Java release, or is Java-maintainable source the first milestone? +5. Which known bugs are intentionally fixed during the port, and which are preserved until compatibility is established? +6. Which GTNHLib release is the minimum supported version for the target pack? +7. After the Java port is stable, is there enough benefit to redesign runtime tile composition, or should the Java ASM generator remain? + +## Rough effort expectation + +These are order-of-magnitude estimates for one developer familiar with Forge 1.7.10, excluding long ecosystem validation: + +- Targeted performance cleanup while retaining Scala: roughly 3–7 focused days. +- Java implementation while retaining deprecated Scala ABI bridges and the current composition model: roughly 4–8 weeks. +- Full Java implementation plus safe Scala runtime removal and broader compatibility work: roughly 8–14+ weeks. + +These ranges were formed before designing the characterization suite and should now be treated as lower bounds. The tests add deliberate work before each conversion but should replace a substantial amount of later regression debugging. Revise the estimates after the first low-coupling subsystem completes the full characterize-port-compare cycle and after Phase 0 determines how much of the Scala ABI and Scala trait mechanism is used externally. + +## Findings log + +### 2026-08-14 + +- Confirmed that the codebase is feasible to migrate incrementally to Java. +- Confirmed that generalized Scala `try/catch` overhead is not present; only a small set of exception-based non-local returns is relevant. +- Identified closure/boxing/collection allocations as stronger performance candidates. +- Confirmed that the existing runtime compiler already has a Java trait path. +- Confirmed that public bytecode exposes Scala types and compiler artifacts, so bridges and Scala runtime removal must be separate decisions. +- Confirmed Hodgepodge's normal/early/late UniMixins plus GTNHMixins registration pattern as the reference for fixed mixins. +- Confirmed that UniMixins is not a drop-in replacement for ForgeMultipart's runtime composite-tile generator. +- Confirmed GTNHLib as a viable route to fastutil, subject to pack-aligned versioning and runtime-resolution verification. +- Adopted characterization tests against the existing Scala implementation as a prerequisite for each converted area, backed by golden ABI/data fixtures and real Forge integration scenarios where plain JVM tests are insufficient. +- Bootstrapped JUnit Jupiter and passed an eight-case `IDWriter` characterization pilot against the untouched Scala implementation, covering byte/short/int thresholds and exact encoded bytes. +- The pilot found that negative `IDWriter.setMax` values select the byte carrier because Scala 2.11 treats `0xffffffff` as signed `-1`; current registry callers supply non-negative collection sizes, so this is recorded as a dormant edge case and possible deliberate divergence rather than changed during characterization.