Qz-Miner Documentation

The main development JAR (qz_miner-<version>-dev.jar) acts as a joint fingerprint of both the Miner source code and the referenced UILib symbol surface used during compilation.

If you replace a dependency (like UILib) with a version that has the same version number but different content (content drift), the main JAR's SHA256 will change if the changes affect symbols actually referenced by Miner.

Key behaviors to note:

• Expected Behavior: A change in the main JAR's SHA256 after updating a dependency is expected and does not indicate build instability, GC issues, or timestamp jitter.
• Non-sensitive Artifacts: The -dev-dev.jar and -sources.jar artifacts are insensitive to UILib content changes and their SHA256 values should remain stable even if the main JAR changes.
• Symbol Sensitivity: Only changes to symbols (classes/methods) that are actually referenced by the Miner source code will trigger a change in the main JAR's SHA256. Adding new classes or members to UILib that are not used by Miner will not change the main JAR's SHA256.

To prevent future occurrences of target unbinding and state inconsistency, follow these architectural principles:

Best Practices

• Immutable Transaction Chains: Target-driven asynchronous transactions must bind "Input Identity — Candidate — Transaction Expectation" into a single immutable chain. Do not re-read runtime targets mid-transaction.
• Orthogonal Protocol and Inventory Write Authority: Keep client read-only access and server-side single-ledger authority orthogonal. Any re-matching must not append a normal SWAP onto an old ledger.

Required Regression Test Cases

Ensure the following scenarios are covered in testing:

• Target transitions: A→B→C and A→B→A.
• In-flight operations: SWAP/RESTORE during transitions.
• Metadata/Coordinate changes: Same block/meta with different coordinates, or changes in metadata.
• Timing sensitivity: 1/2 tick ABSENT scenarios.
• Priority handling: GUI, re-anchor, FROZEN, and reset priorities.

To prevent item loss and infinite loops, the system uses a four-level fallback mechanism when attempting to release drops. If a level fails, the system increments a failure counter and moves to the next level. If all levels fail, the items are discarded to prevent a dead loop.

The Fallback Hierarchy

1. Level 1: Current Player Position (releaseAtPlayer): Attempts to spawn drops at the player's current location.
2. Level 2: Respawn/World Spawn (releaseAtRespawnOrWorldSpawn): Attempts to spawn at the player's respawn point or the world spawn if the current chunk is unavailable.
3. Level 3: Remembered Target (releaseAtRememberedTarget): Uses a fallback coordinate pre-stored during the initial onHarvestDrops event.
4. Level 4: Discard (discard): If the failure count reaches DROP_RELEASE_MAX_RETRIES (default: 100), the items are discarded with a diagnostic reason (e.g., "world-tick-release-exhausted" or "world-tick-missing-exhausted") to stop the loop.

Implementation Details

• Failure Counting: Failures are tracked via dropReleaseConsecutiveFailures in ChainPlayerState. This counter must be reset using clearRuntimeState when a player respawns, changes dimensions, or relogs to prevent stale counts from affecting new sessions.
• Retry Limit: The constant DROP_RELEASE_MAX_RETRIES = 100 provides a window of approximately 5 seconds (at 20 TPS) for chunks to load before giving up.

In version 4, the handling of takeover requests and publication synchronization has been redesigned to prevent race conditions.

Takeover Request Separation

• TAKEOVER and DECLINE actions are no longer part of the standard actionSequence. They now use a dedicated takeoverRequestId.
• CLOSE, RESTORE, and ABANDON actions can now retire uncommitted waiting gates only after the standard sequence is precisely validated. They are no longer blocked by request-local deadlines or target drift.

Publication Synchronization Rules

• Once a mutation or an ActionResult is in the exact publication pending state, standard lifecycle actions (CLOSE, RESTORE, ABANDON, deadline, release, or IDLE) must not preempt the submission point.
• These actions must wait for the result to be reliably published. Only hard lifecycle events (disconnection, rebirth, dimension switching, or service shutdown) can directly destroy these records.
• This prevents the 'inventory modified but result/ledger forgotten' race condition.

Recovery Behavior

• When waiting for publication, the target remains at peek and the Coordinator returns WAIT. The system does not publish a fake ExecutionAdvanced.
• If full inventory synchronization or the ActionResult sender fails, the system performs an exact retry rather than replaying the mutation.
• For detailed recovery contracts, refer to ERROR-20260725-auto-tool-request-sync-recovery.md.

As of 2026-09-11, the multi-baseline matrix mechanism in Qz-Miner has been retired. The project has moved from a matrix-based compatibility commitment to a single-baseline declaration.

Key Changes:

• Single Source of Truth: The GTNH baseline is now declared via a single value in dependencies.gradle using the elytraModpackVersion block.
• Removed Files/Tasks:
  • gradle/gtnh-baselines.json is no longer used.
  • scripts/verify-gtnh-baselines.ps1 has been deleted.
  • The verifyGtnhBaseline task in build.gradle.kts has been deleted.
  • branch-ci.yml no longer contains a baseline matrix or the prepare-baselines step.
  • release-tags.yml no longer parses baseline lists.
• Removed CLI Parameters: The following parameters are no longer passed during CI:
  • -Pelytra.manifest.version
  • -Pqz.gtnh.*

Current Compatibility Model: Compatibility is now verified via source-level checks (ensuring zero static linking to GTNH-side components) and dual-baseline testing (compileJava and compileTestJava) for versions like 2.9.0-beta-2/beta-3. Note that runtime verification on actual hardware is not performed.

When designing inventory transactions to avoid lease and anchor mismatches, follow these best practices:

1. Separate Semantic Comparisons: Do not reuse a single comparison function for different purposes. Explicitly name and test fresh exact (for request freshness) and lease role (for cross-round ownership).
2. Comprehensive Test Matrix: Ensure tests cover:
   • Dynamic content changes (NBT, etc.).
   • stable subtype changes.
   • Empty slot occupation.
   • sameRole but stale intent.
   • ABANDON identity mismatches and idempotent replays.
3. Empty Slot Lease Assertions: Tests for empty slot leases must assert that after a swap, the reference sets remain unchanged, and no items are merged, overwritten, or swallowed.
4. Explicit Termination: Transactions that cannot be safely compensated must have an explicit, auditable, and zero-side-effect termination action. Never rely on a standard CLOSE to implicitly clear a ledger.

When working with GregTech (GT) MetaTile entities, you must adhere to specific API contracts regarding bidirectional binding to prevent Tile Entity (TE) failure and crashes.

Binding Methods

• setMetaTileEntity(IMetaTileEntity): Performs a unidirectional binding (base $\rightarrow$ meta). Using this alone will result in getBaseMetaTileEntity() returning null, causing NPEs in disconnect()/connect() and making the TE invalid.
• setBaseMetaTileEntity(IGregTechTileEntity): Performs a bidirectional binding. This is the required method for replacing MetaTile instances to ensure both sides of the relationship are aware of each other.

Connection State Management

GT cable and pipe connection states are managed via a public byte mConnections bitmask rather than a complex state machine.

• To restore connections during a replacement, you should directly copy the mConnections value from the old entity to the new one.
• After updating the bitmask, you must call GregTechAPI.causeCableUpdate to rebuild the energy network graph (Node/NodePath).
• Visual synchronization (textures/client-side updates) is handled by updating the mID and calling issueTextureUpdate and issueTileUpdate.

To prevent identity loss during asynchronous planning, Qz-Miner uses an immutable pure value called TileIdentityToken. This token is designed to capture the identity of a TileEntity at the exact moment of the event.

Key Characteristics of TileIdentityToken

• Immutable and Pure: It does not contain references to TileEntity, World, Block, NBT, Class, or coordinates.
• States: It uses three possible states:
  • PRESENT: The identity was successfully captured.
  • ABSENT: No identity was present.
  • UNRESOLVED: The identity could not be determined (e.g., due to an adapter failure).

Implementation Requirements for Developers

• Capture Timing: For BreakEvent, the seed TileEntity must be read on the server's main thread and immediately converted into a token.
• Right-Click Resolution: For right-click interactions, you must resolve the semantic target before publishing the event:
  • For non-liquid BLOCKs: Use the event coordinates.
  • For AIR: You must use a side-neutral raycast to resolve the BLOCK hit. Never use the placeholder AIR coordinates as a seed.
  • For liquid BLOCKs/AIR: Use a raycast that includes liquids.
• Propagation: Once captured, the Block, complete non-negative int metadata, and the TileEntityToken must be frozen and propagated through the state machine. The planning bridge must prioritize this frozen triplet over subsequent world reads.
• Error Handling: If a reading error occurs, the state must be set to UNRESOLVED. Do not attempt to overwrite or guess the value using later world states in the next tick.