Repository navigation
Remold v0.2.6
v0.2.6 Release Notes
Status: released 2026-11-09 (v0.2.6, GitHub release published; tag 2159d21).
Previous release: v0.2.5 (78673b2).
Highlights
- Two-phase Schema-First redefine closes the read-through window.
redefineClassesreturns before
InitFixhas written the newly added fields, so a reader in that window can observenull/0(a
realNullPointerExceptionon render/logic threads). On the internal batch path (file watch →
processChanges) Remold now commits stage A — the new class structure with the old method
bodies, while constructors and<clinit>keep the new bodies — then patches live instances, then
commits stage C (the new bodies). The old bodies cannot reference fields that did not exist at
compile time, so they cannot read through the window; instances created between A and C are
initialized by the new constructors. Pure method-body edits keep the single-redefine fast path. On by
default;-Dremold.agent.two_phase=falserestores the previous behaviour. - Initializer replay for objects that already exist — both channels opt-in. A double-brace
initializer (new Unit() {{ health = 250; }}) that writes an inherited field, and a Kotlinobject/
top-levelvalholder whose<clinit>runsTurret("duo").apply { health = 250 }, now replay the new
compile-time constant onto live objects. Both are gated by an explicit allowlist
(-Dremold.agent.init_drift.parents=...,-Dremold.agent.init_drift.apply_holders=...; empty = off)
and write through the newHotswapBridge.KIND_CONDITIONAL_EXPECTEDprotocol: a value is written only
while the instance still holds the old constant, so a runtime-modified value (a damaged unit's
health) is never overwritten. Neither channel writesFieldLedgeror changespatchGenerated. - Mixin anonymous-class / inner-class hot-swap. The first anonymous class introduced inside an
@Injecthandler used to kill the reload (Error loading class: Outer$1 (ClassNotFoundException),
theninnerClass is null); editing only the body of an already-loaded generated inner class used to
end in a silent[DYNAMIC-REDEFINE] no-opwhile the old body kept running. Remold now feeds the new
bytes into Mixin's own bytecode provider (MixinBytecodeOverlay, with the upstream negative
ClassInfocache entries evicted) and redefines the generatedTarget$Anonymous$<uuid>class in place
(MixinInnerClassHotSwap,MixinInnerClassSupport). Weaving-generated classes can also register
their bytes incoreBytecodeSources, so Nest scanning and InitFix's constructor-visibility check
resolve them instead of failing closed;refeedForTargetpre-generates a freshly woven target's
synthetic inner classes after weaving and before the InitFix scan, then restoresloadCounterso the
platform still performs the realdefineClass. - Same-shape anonymous-class ambiguity and holder-field naming. When two anonymous classes in one
method share an interface and structure, topology alone can no longer decide and the edit used to be
orphaned. A body-structure similarity tier (anonymous-class references masked, literals excluded,
strict margin, both-way unique) now decides the R2b case; only if it fails does an approved liveness
fallback pair a whole ambiguity group whose old candidates all have zero live instances. The orphan
warning names the holder fields — proven by the assignment flow (NEW <anon> → <init> → PUTFIELD) or
listed as candidates when the field is declared as the anonymous class's supertype/interface (the
Supplier-typed holder case). - Start-up readiness gate and batch stall watchdog.
apigainedHotswapPlugin.isHostReady()
(defaulttrue);StartupGateholds batches until the host says it is ready, with
-Dremold.agent.ready_timeout_ms(default0= never releases on time).BatchWatchdogdumps all
thread stacks once per batch with[HOTSWAP-STALL]when a batch exceeds
-Dremold.agent.batch_stall_ms(default15000, floor5000); the funnel now covers the debounce
batch, the manualtriggerHotswap()entry andretransformLoaded. - Structured batch report, client HotSwap toast, template back on 1.21.1.
apigained
HotswapBatchReportandHotswapBatchListener.afterInternalBatchReport()— batch elapsed time, Mixin
member deltas (with an explicit "delta unknown" state) and InitFix patch counts — populated by the new
coreBatchReportScope. The Fabric template's client toast consumes that report and shows an
explicit "legacy agent" card on the published 0.2.5 agent instead of fabricating zeros. The template
baseline moves back to Minecraft 1.21.1 (yarn 1.21.1+build.3, loader 0.16.9,
fabric-api 0.105.0+1.21.1); the 1.21.4-only client gametest is preserved as the standalone
tests/fabric-gametest-1.21.4/probe. - Class and asset debounce are separate streams. Every
.class/.jarevent resets the Class
quiet window (default lowered to 800 ms); resource/config events use their own 250 ms window
and never postpone a Class batch. A pureDebounceWindowstate machine (unit-tested without sleeping)
decides which stream is due; the manualtriggerHotswap()entry still cancels the pending timer,
clears both deadlines and force-drains all queues. The Gradle DSL gainedassetShakeMs.
Fixes
- Read-through
NullPointerException: a reader running betweenredefineClassesandInitFixobserved
null/0for a newly added field. Closed on the internal batch path by the two-phase redefine
above; the external IDE/JDWP andredefineDynamicchannels still run single-phase and are listed
under Known limits. - Mixin handler's first anonymous class:
ClassNotFoundExceptionforOuter$1followed by
Cannot invoke "ClassInfo.isProbablyStatic()" because "innerClass" is nullno longer happens — the new
bytes are offered to Mixin's bytecode provider beforereloadMixin, and the negativeClassInfo
cache entries are evicted. - Body-only edit of an already-loaded Mixin-generated inner class: used to end in
[DYNAMIC-REDEFINE] no-opwhile the live class kept the old body; the generated
Target$Anonymous$<uuid>class is now redefined in place. The "no-op" line that follows for the
target class is expected and is now explicitly explained in the log. NoClassDefFoundError: LoadedTargetSuppressordisabled both the success and the failure branch of the
Mixin hot-swap handler under a plugin/core version skew. The "target already loaded" suppressor now
crosses the core boundary as plain JDKFunction/Consumermethod references, so the same skew
degrades to a diagnosable "suppression unavailable" path instead of a linkage error.- Same-shape anonymous-class edit: previously orphaned (
topology-equal candidates 2 -> 2, topology-decided 0) with the field-held live instances still running the old body. It is now decided
by body evidence, then by the liveness fallback; the warning names the old classes with their
live-instance counts, the holder fields and the@RemoldReinitescape hatch. - A field whose initializer allocates a Mixin-generated anonymous class was refused on hot reload
(Nest scan incomplete;Field init patch refused ... cannot determine protected status of constructor). Synthetic bytes can now be registered inBytecodeSources, and the diagnostics name
the weaving-generated synthetic class as the cause instead of failing unattributed. - A Mixin name removed from
*.mixins.jsoncould be silently re-registered when its class file was
rewritten; the removal now holds until the name is re-added, and a re-add whose asset event was missed
is re-checked on the next class rewrite (the recorded config path is re-read). On Forge/NeoForge,
ModLauncherClassTrackerSpoofremoves target names fromModLauncherClassTracker.loadedClasses
inside theprepare()window, restores them infinally, and fails closed when the tracker shape is
unknown;ForgeMixinConfigDiffwiresonAssetsChangedto the shared engine. - The batch stall watchdog previously covered only the debounce Class batch (manual
triggerHotswap()
andretransformLoadedwere uncovered). It now arms through a scopedenter/exitAPI with at
most one armed watchdog per batch. - Gradle plugin: the agent JVM arguments were injected only into the loader
clientrun container, so
./gradlew runServer(Fabric Loom / ForgeGradle / ModDevGradle) and Fabric gametest runs
(clientGameTest/gameTest) started without-javaagent. Client, dedicated-server and gametest
runs now receive the same arguments; auto-deploy also wiresrunServer, and the IDEA Loom sync covers
Minecraft_Server.xmlas well asMinecraft_Client.xml. - Release tooling: the Gradle plugin's JitPack publication published the bare version while the packaged
remold.gradle(.kts)shims and both project templates request
com.github.I-hope1.Remold:gradle-plugin:v<version>, so offline /mavenLocalresolution of the
plugin dangled. Publications now use thev-prefixed version,panamagained its missing JitPack
publication, and all consumer coordinates are canonicalized to the real repository account casing
(com.github.I-hope1.Remold), which also removes a Gradle module-metadata group-case mismatch.
Added
api:HotswapBatchReport(immutable, safe to pass across threads;MixinChangewith an explicit
deltaKnownstate,InitFixStatsthat only counts completed patches),
HotswapBatchListener.afterInternalBatchReport(),HotswapPlugin.isHostReady().core:BatchReportScope(per-batch scope collecting elapsed time, redefined classes, Mixin deltas
and InitFix stats),BytecodeSources(JDK-only registration port for weaving-generated class bytes,
consumed byHierarchyTreeOracle.readClassBytes),BatchWatchdog,StartupGate.tests/fabric-mixin-probe/anon/: real Fabric 1.21.1 KnotServer probe with S0–S7 stages (long-lived
field holder,@Unique privateaccess, 1→2 same-shape renumbering, field-initializer constructor
visibility, control stages) plus its own evidence files.tests/fabric-gametest-1.21.4/: standalone 1.21.4 client gametest probe (real item registration,
hotbar model screenshot, real right-click chat assertion); the Toast client entry is intentionally
removed there. Its end-to-endrunClientGameTestevidence is carried over from the 1.21.4 template
round and was not re-run after the move (no display session), so it is not counted as new
verification here.minecraft-fabric-template: clientHotSwapToast/HotSwapToastBridge/HotSwapToastModel
(com.example.client) andHotSwapToastModelTestfor the model formatting rules (unknown values,
delta-known=false, three-line cap).verifyReleaseCoordinates(./gradlew publishToMavenLocal verifyReleaseCoordinates): asserts that
every publishable module has both coordinate families (io.github.i-hope1.remold:*:<ver>and
com.github.I-Hope1.Remold:*:v<ver>) under~/.m2/repository, so a missing/mismatched publication
fails the release instead of silently dangling in the templates.- Gradle DSL:
assetShakeMs(asset quiet-window override, independent of the Class window).
Verification
- JUnit: 597 tests, 0 skipped, 0 failures (
./gradlew check; release window 2026-11-09),
includingverifyTestCountandverifyDocStatusMarkers(all normative docs and sources pass the
status-marker scan). :tests:initFixOracle: all assertions pass (ALL ASSERTIONS PASSED), recorded per feature in
docs/status.md§0.5–§0.7.- Recorded probe evidence from this cycle — each figure is from the named run, nothing is aggregated
across rounds:- two-phase:
TwoPhaseProbe72/0 (realprocessChanges, 50k live instances, concurrent readers:
single-phase stableNullPointerException, two-phase zero),TwoPhaseGuardTest5/0,
StageASkeletonTest11/0. - initializer replay:
KotlinApplyProbe34/0 (JBR 21),ApplyInitializerReplayTest13/0,
DoubleBraceProbe104/0,InitializerReplayTest11/0. - JVM / offset probes:
:tests:p05Probe63/63 on JBR 21 (the JBR 17 CI leg is also 63/63;
JBR 17 has nodeoptimizationlog tag, declared asEVIDENCE-MISSINGrather than a failure),
:tests:offsetStabilityProbe47/47 (JBR 21). - start-up gate / watchdog:
remold.startup.*30 cases, 0 failures. - Mixin internals:
MixinInnerClassHotSwapTest7 cases,NestBytecodeSourcesTest10/0,
AnonClassAmbiguityTest13 cases;NewMixinRegistrarTest6/6. - template toast:
HotSwapToastModelTest10 tests, 0 skipped, 0 failures
(./gradlew build --offline, JBR 21); the template jar containscom/example/client/*and a
cliententrypoint infabric.mod.json.
- two-phase:
- Real containers (recorded evidence in this cycle):
- Fabric 1.21.1 KnotServer (sponge-mixin 0.8.7, JBR 21), anonymous-class probe: S0–S7 all green,
exit 0,EXT_GREEN=1— S4 held-instance body change, S5@Unique privateaccess plus field
patch, S6 1→2 renumber pairing, S7 field-initializer patch on the live instance; controls stable
(tests/fabric-mixin-probe/anon/evidence/anon-ext-green.txt,
anon-f2e2-all-green.txt; merged F2+E2+D2 tree:anon-final-all-green.md.txt). - Same KnotServer, Mixin config diff + new-Mixin registration: five paths pass (config removal → hook
stops, class rewrite after removal ignored, re-add restores, new Mixin on an unloaded target, new
Mixin on an already-loaded target re-woven + redefined) —
tests/fabric-mixin-probe/evidence/newmixin-runtime-20261108.txt. The existing@Inject
self-evolution probe was re-run unchanged after the shared-engine refactor
(inject-evolution-after-ssot.txt,RESULT PASS failures=[]; recorded 2026-11-07). - Real client log (single session, not a synthesized probe) for config removal/re-add: two full
cycles onCreeperEntity(tests/fabric-mixin-probe/evidence/newmixin-client-20261108.txt). This
is an observation, not a counter-based assertion — it does not prove that no hook fired between
removal and re-add (no creeper exploded in that window); the KnotServer probe covers that. - Forge 1.21.1 (
runServer --offline, ForgeGradle 7): stage 1/2 plus config remove/re-add, all probe
checks pass,HALT rc=0,VERDICT GREEN
(tests/fabric-mixin-probe/forge-classinfo/evidence/forge-1.21.1-configdiff-after-fix.txt). - NeoForge 21.1.265 (MC 1.21.1, ModDevGradle 2.0.148, native
META-INF/neoforge.mods.toml[[mixins]]registration): allNP-*checks pass,VERDICT GREEN
(tests/neoforge-mixin-probe/evidence/neoforge-21.1-configdiff-after-fix.txt).
- Fabric 1.21.1 KnotServer (sponge-mixin 0.8.7, JBR 21), anonymous-class probe: S0–S7 all green,
- Mutation checks recorded in this cycle's campaign evidence ledger: three for
MixinInnerClassHotSwap
(ev-20261109021245-983c,ev-20261109021305-bf93,ev-20261109021322-f20e), three for the
same-shape ambiguity tiers (ev-20261109091139-5582,ev-20261109091203-8593,
ev-20261109091253-d347),mut-20261109101806-d693for therefeedForTargetwiring (baseline
exit 0→ mutantexit 3), and the watchdog (4/4) / holder-naming (5/5) checks recorded in
docs/status.md§0.10. The evidence harness itself has known false-PASS / false-kill modes (see
Known limits): every PASS / kill figure above presumes human review of the raw log.
Known limits / manual acceptance
- NeoForge 26.x / FML 10+ is not supported and not verified. That generation removed ModLauncher
(cpw.mods:*is absent from its library list; entry pointnet.neoforged.fml.startup.Client, FML
loader 11.x). The cross-ClassLoader bridge is written against ModLauncher semantics; do not
extrapolate the 21.1 evidence. - NeoForge production installer launch path is not verified. The E2E runs a dev runtime
(ModDevGradle directory classpath). Module ownership can differ in a production launch, so the JPMS
--add-opensrequirement must be re-tested there; the agent prints a precise diagnostic instead of
attempting runtime unsealing. - Real client GUI acceptance is still manual. Container probes cover dedicated servers (Fabric
KnotServer, ForgerunServer); the anonymous-class closed loop has not been re-run on a real client
(IDE + KnotClient), anddocs/acceptance/01-manual-checklist.md(template scenarios 1–8) still has
empty result columns for the user to fill in. The Toast card has only been exercised through
HotSwapToastModelTestand entrypoint/listener registration — actual rendering is not verified in
this environment (no display session). - Anonymous-class structural changes still require a restart. Adding/removing fields or methods on a
Mixin-generated anonymous class is rejected with a directed diagnostic (member names listed) and never
bypasses the layout gate. Undecidable alignments are refused rather than guessed: same-shape edits
whose bodies differ only in literals and whose old class still has live instances are left orphaned,
with a diagnostic naming the holder fields and the@RemoldReinitescape hatch, and
layout-incompatible candidates are skipped with the same warning — the S5 reading of the probe carries
one such[ANON_ALIGN]refusal for the Mixin host's own anonymous classes, and that edit still takes
effect for instances created after the change.ForgeMixinHotSwapis not wired into this inner-class
loop, so the anonymous-class hot-swap is Fabric-only for now. - plugin and core must be released together. The suppressor SPI no longer hard-links a core type,
but aMixinConfigContextconstructor-signature mismatch still throwsNoSuchMethodError; it is
caught per plugin inRemoldAgent.notifyAssetChangesand logged as an error, not swallowed. Version
skew is diagnosable, not supported. BytecodeSourceshas no memory bound. Its key set does not grow across reloads (the generated
unique names are stable), but there is no eviction; re-feeding happens before the schema re-check, so
"the bytes were readable" does not mean "the change took effect".- External IDE/JDWP redefine and the
redefineDynamicsingle-class channel still run single-phase.
The read-through window described in Highlights remains open there: the JVM commits the full new
bytecode first and Remold can only patch afterwards. Fields rejected by the safety gates are not
compensated by two-phase either (restart semantics), and before stage B completes a new constructor
can still read this class's new static fields or another class's not-yet-patched fields. - Two-phase costs two redefines when it triggers (a double JIT deoptimization of compiled code);
pure method-body edits stay single-phase. TheredefineDynamicsingle-class entry also has no
watchdog. plugin-fabric's readiness probe is fail-open and unverified on a real host. The accessor names
(getTicks/getTickCount,world/level) could not be checked against real sources; when
probing fails it returnstrue(treated as ready) and logs one info line.plugin-forgedoes not
implementisHostReady()yet.- The evidence harness itself has recorded false-PASS / false-kill modes (exit code 127 recorded as
a kill, cmd banner-only output recorded as PASS, GradleUP-TO-DATEduplicate stdout hashes treated
as new evidence). Every PASS / kill figure in this document presumes human review of the raw log;
tool-side fixes are tracked indocs/status.md§0.10.
Full history: CHANGELOG.md · Implementation status and residual risks:
docs/status.md.