Freedom Lib

This file bundles the run from v0.5.1 through v0.7.1. Broad-strokes summary below.

New primitive: LiquidHandlerPrimitive (v0.7.0)

A self-driving liquid neutralization primitive. Given a target liquid cell, it classifies the surrounding body and picks a strategy automatically:

• FILL — for open-topped basins with a rim: mob walks to the bank and pours gravel to fill every cell (source and flowing), bottom-up
• PLUG — for enclosed, wall-embedded, or elevated sources: mob climbs a self-fusing freedom:climb_scaffold column on the source's open side, seals it with cobblestone, then descends
• Works on both water and lava
• Waterlog-aware teardown — clears any held source water when the PLUG column comes down
• Placement-only climb — never breaks blocks (returns BLOCKED on obstruction)
• Per-cell protection checks — refuse-whole-op for the PLUG column, skip-cell for the FILL pour
• Bounded v1 envelope — basin ≤64 cells, source cluster ≤4; larger bodies decline UNREACHABLE

New: NO-OP gate-failure diagnostics (v0.6.0 + v0.6.1)

Rate-limited log lines now show WHY each registered primitive declined to fire when a mob's stuck-detection tick produces no action:

[Freedom NO-OP] entity=… uuid=… pos=(x,y,z) stuckTicks=N source=<tag> gates=[scaffold-stack=cardinals=3/4; climb-assist=noTargetPos]

• Scrapeable reason vocabulary: cardinals=N/4, noOpenSky, nonSturdyFloor, stepUpAvail, occupied, protected:feet/protected:head, noTargetPos, noTwoBlockWall, yDelta=..., targetDirectlyAbove, waterloggedHost
• PassageNavigator gate tokens added (v0.6.1): noPatrolTarget, notDefenderSource, tooFar, tooClose
• Backed by EscapePrimitive.gateFailureReason(entity, ctx) — a default null interface method primitives override to explain their gate. Runs only on the rate-limited NO-OP path; zero cost when everything is firing.

Correctness fixes

ScaffoldStack (v0.5.2 + v0.7.1)

• HEAD protection check — now checks the mob's head cell against the host's protection predicate, not just the feet cell (blitz fix)
• Head rung placement — places on a passable non-air head cell rather than assuming air (fixes rescue failures under snow / carpet / trapdoor overheads)

ClimbAssist

• Session-total climb cap — cap now correctly bounds total climb distance across a session, not per-tick (was allowing unbounded stacking)

BreakBlockPrimitive

• Reach validation — properly validates the caller-supplied reach-squared parameter
• Reach-anchor javadoc — clarifies the eye-anchored measurement to avoid caller confusion

Multiple primitives (v0.5.3)

• destroyBlock result honoring — rescue and dig primitives now correctly propagate the destroyBlock success/failure back to the Result enum instead of silently continuing

SealAdjacentLiquidPrimitive

• Seal-eligible protected cell counting — only counts cells that could actually be sealed, not every protected cell in the scan volume (produces correct SEALED_PARTIAL results)

Server-lifecycle safety (v0.7.1)

• Server-stop cleanup — per-primitive tracker maps and rate-limit maps clear cleanly on server stop, preventing stale-state leaks across shutdown → restart cycles

Refactoring / cleanup

• Dead code removal — dropped the unused isVanillaScaffolding helper and stale @SuppressWarnings annotations
• FILL comparator hoisting — hoisted out of the tick loop; BlockPos stored in HandleRecord for allocation reduction in LiquidHandler