Design: typed cauldron interactions

Provisional contract for #1323 and parent #854. This note implements no API. Typed registration, handler shape, prediction and atomicity require maintainer approval before code. The merged #1325 table and #1390 journal are foundations, not a mod registrar.

Vanilla and public counterpart

Reproduce the vanilla inspection with python3 tools/rea_vanilla.py class net.minecraft.core.cauldron.CauldronInteractions, then method queries for bootStrap, addDefaultInteractions, fillBucket, emptyBucket, fillWaterInteraction, fillLavaInteraction, fillPowderSnowInteraction, isUnderWater, dyedItemIteration, bannerInteraction and shulkerBoxInteraction. Query net.minecraft.core.cauldron.CauldronInteraction.Dispatcher get and callers of net.minecraft.core.cauldron.CauldronInteraction interact too. These are pinned vanilla 26.3 bytecode queries; no foreign implementation is used.

Dispatcher.get selects the first matching tag, otherwise the exact item, otherwise DEFAULT. Returning TRY_WITH_EMPTY_HAND from the selected tag handler does not resume the item lookup. All registrations in bootStrap and its default-registration helper are covered below:

Lowering level 1 gives an empty cauldron. Bucket and bottle exchanges use ItemUtils.createFilledResult; washing uses its non-limited-creative form for banner/shulker. Preserve survival consumption, creative inventory deduplication where enabled, returned-stack components, inventory insertion and leftover drops. Washing has its cleaning statistic and BLOCK_CHANGE from lowering, with no fluid sound/event. Transfers have their existing statistics, sound and FLUID_PLACE/FLUID_PICKUP; a bottle lowering also has BLOCK_CHANGE. Successful handlers check the same guards on the client but mutate only on the server. This is why a prediction result and an authoritative application are separate operations.

The public NeoForge cauldron documentation describes RegisterCauldronInteractionEvent.Dispatcher on the mod event bus, an identifier for a dispatcher, Interaction registration by dispatcher and item, and registerToAll. Its 26.1 migration primer describes tags preceding items. The accessible documentation is labeled 26.1, not 26.3. Exact NeoForge 26.3 duplicate policy, overlapping-tag order, reload lifetime, side behavior, prediction and rollback guarantees remain unverified; no 26.3 Javadoc contract was established. No NeoForge source or patches were read. The Horizon rules below are proposals, not claims of NeoForge parity.

Verified owners and routes

These file:line anchors describe the inspected base and must be checked again before implementation.

Paths abbreviated as game/ above are under crates/horizon-client/src/. The vanilla caller query identifies AbstractCauldronBlock.useItemOn as the item dispatch moment. Future implementation must test each authority route above and both remote prediction paths.

PR #2835 owns fluid content/capacity, planned game/blocks/machines/cauldron_contents.rs, and native fluid capability integration. That file is absent at this base. Reuse its BlockKey/FluidKey and resolved resource snapshot when integrated; an interaction entry neither registers fluid capacity nor invents a second fluid table. Powder snow need not become a fluid. A fill recipe must respect the registered level schema and content capacity. PR #2697 owns activity/dispatch restructuring, following vocabulary/loading moves. Declare types in vocabulary and generate facade/transport through the owning generator after that work; do not restore old private point registries. Keep future adapters in small dedicated modules: game.rs, native_hooks/shared.rs and modding/api_values.rs must not grow beyond the fork's file-size gate.

Proposed typed registration

One registration moment, provisionally register_cauldron_interaction, corresponding to RegisterCauldronInteractionEvent. Public 26.3 verification remains required: adopt its exact names (Dispatcher and Interaction if verified), side and full contract before shipping, without aliases. No 26.3 counterpart is claimed verified here. Use this moment with typed dispatcher and entry phases if public 26.3 verification requires them. Register by (BlockKey, ItemKey) through a CauldronInteractions registrar with a Host. A custom block opts into a dispatcher explicitly; vanilla blocks come prebound. Several blocks may deliberately share a dispatcher, but binding and conflicts must resolve before publication. A convenience register-to-all expands over the complete prepared dispatcher set, including later mod declarations, never over the live mod list at click time.

Use exact typed items for the initial mod surface. Retain vanilla's tag branch in the same dispatcher; do not expose arbitrary mod tag priority until its counterpart contract is verified. Resolve tags against the authoritative prepared tag snapshot on both sides. Exact entries shadowed by the dye tag stay shadowed, even when washing passes.

Refuse duplicate entries (including attempts to replace vanilla entries) with CauldronRegistrationError::Duplicate, identifying both owners. No override flag, priority integer or last-wins behavior. Dependency order and stable declaration order determine diagnostics, not behavior: a conflicting preparation fails publication rather than choosing a winner. Unknown keys refuse admission as UnknownItem, UnknownBlock or UnknownDispatcher; unknown ordinary held items still pass without a new runtime error. These names are proposed API variants. Unsupported native/wasm callback or codec capability refuses registration as UnsupportedCapability, never silently omitting one target.

Build the entire resolved snapshot at resource preparation and reload, validate, then publish atomically with the existing resource/lifecycle holder. Failed reload retains the prior complete snapshot. Capture that holder in a decision; reload or world closure invalidates the decision through existing identity, without adding a cauldron-specific generation counter. Retain old callback code until its in-flight scopes finish. No retained native pointers or wasm callback indices may survive their owner. Client/server synchronize the existing resource generation and require a matching handler build before prediction.

Handler and prediction contract

Proposed API-owned Wire records: CauldronUse (dimension, target position and state, actor handle, hand, complete immutable held stack, underwater/creative flags and resource identity), CauldronDecision, CauldronPlan, CauldronResult and typed refusal/error enums. Use existing ItemKey, BlockKey, state, stack, lifecycle and handle representations; never serialize internal Action, Rust closures, pointers or borrowed Game state. Every field and result must support the same generated Wire boundary for native and wasm. A callable registration references the runtime's owned callback identity, not a function pointer in a packet.

Split decide, fire, apply. A handler receives a callback-scoped read Host with typed HostSide and returns Pass, Consume, or Success plus a bounded plan. Server fire receives a ServerHost with the game's open transaction for additional supported writes. Client prediction receives only ClientHost reads; it cannot mutate inventories, draw authoritative random, send messages, spawn drops or publish effects. No recursive dispatch from decide; refuse same-action reentry as Reentrant, on both targets. Server callbacks are invoked once per attempt, with nested transaction commits merging into the action. Pass discards all staged writes; Consume may stop item use with an empty plan (vanilla underwater behavior).

The plan describes one target block replacement, an optional exchange of one held item for one returned stack, and optional one sound, one fluid game event and up to two statistics (custom cauldron stat and ITEM_USED, preserving vanilla transfer capacity). Lower-fill BLOCK_CHANGE remains a distinct effect. Washing can edit the held components without an exchange. Helpers implement existing filled-result semantics instead of making mods reconstruct creative and overflow rules. More extensive world changes use existing journal-supported Host operations; unsupported operations refuse the action before any escape. No irreversible I/O during callbacks.

Prediction uses the same decision rules and selected entry but computes only result and visual proposal. Do not call the authoritative handler on the client. Missing matching client resources suppress custom prediction and await the server; they do not guess Pass and launch a second bucket use. Server revalidates target, dimension, actor identity, complete stack/components, relevant reads and resource holder before applying. Changed preconditions produce Stale, discard the entire action, and send normal authoritative correction; never recompute a different interaction inside that attempt.

Track speculative visual effects with the existing use/prediction acknowledgement identity. Confirmation reconciles the proposed block and suppresses duplicate local sound; refusal restores the authoritative block. Inventory, statistics, drops and game events are server-only. One server mutation is committed regardless of whether a client predicted. Preserve Success/Consume/TRY_WITH_EMPTY_HAND semantics and swing behavior across both hands; prediction must not cause a second UseItem after a consuming UseOn.

Atomicity, trust and cost

Open an action child transaction before the server handler, under any enclosing Host transaction. Journal the acting player's full inventory/hand/components and supported attachment writes, stage the block through journal_set_block, and queue sounds, statistics, game events and leftover drops. Validate the whole plan before mutation and again after callback writes. Nested success merges into its parent; only successful root commit publishes effects, block logs and outbound changes. Any refusal, stale read, panic, guest trap or outer abort restores the original inventory and block and discards every effect. Do not execute the callback again at root commit.

The existing journal already buffers cauldron blocks and effects inside a transaction, but the immediate route is not proof that arbitrary mod callbacks are atomic. Before supporting another write domain, prove its undo and publication behavior or return UnsupportedCapability. In lifted passes, defer entity/attachment retirement and journal Remove emission to root commit using the existing lifecycle holder; rollback preserves identity and attachments. Never assign a second generation to restored objects. Refuse saves while an action savepoint is open, including save-all invoked by a handler; extend crates/horizon-client/src/game/world/autosave.rs:6 admit_entity_save (currently a passes_settled check) and audit every save entry so tentative inventory or blocks cannot reach disk. This is a required implementation guarantee, not a claim that every such gate already exists.

Treat decoded plans as untrusted. Validate keys, state property values, current holder, actor scope, hand and stack components before use. Consume count is 0 or 1 and cannot exceed the held count; exchange count obeys the returned item's real stack limit. State must belong to a registered dispatcher and valid property schema; water/snow levels remain 1..3 and lava remains unlayered. Do not impose a smaller capacity than vanilla. Sounds/events/statistics resolve typed keys; reject unknown owned keys, non-finite volume/pitch/positions and out-of-range values rather than clamping malicious data. Proposed sound bounds are volume 0..=1 and pitch 0..=2, preserving these vanilla interactions. Use existing codec/NBT limits for stacks; cap plan at one exchange, block, sound and fluid event, and up to two statistics, with a separate lower-fill event. Finite host-write/nesting budgets must refuse atomically, never truncate valid vanilla work.

Contain native unwinding and wasm traps at callback dispatch, abort the complete action, and apply the runtime's reporting/quarantine policy. A native process abort cannot be recovered. A failing callback must leave the next built-in interaction usable.

This docs-only change has zero runtime cost. Future unused custom dispatch is one indexed (block, item) lookup after the existing constant dye-tag membership test, with no all-mod scan, allocation or Host construction for a miss. Resolve keys, tag membership and register-to-all at preparation. A custom hit pays for one selected handler and bounded plan plus actual journaled writes. Both prediction paths share that indexed dispatcher. Measure miss allocations and callback count before claiming the hot-path requirement complete.

Acceptance matrix for implementation

Vanilla isUnderWater checks the fluid above against FluidTags.WATER; the current game.rs:12350 and remote prediction use an exact water block check. This known discrepancy needs a waterlogged-above oracle case during integration; it is not silently treated as established parity. The immediate adapter also exposes one custom stat while vanilla transfers award ITEM_USED as well: preserve both through the plan and audit the surrounding item-use statistic owner to avoid double awarding.

These are required tests with literal expectations, not checks run by this note. Run on native and wasm and through integrated, LAN, dedicated and fake-player authority routes where applicable.

Proposed stages and open questions

File no issues from this note. First obtain exact public 26.3 event/side semantics and approve this contract with the #2835 and #2697 owners. Second add API-owned vocabulary/Wire records, registration validation and one prepared native/wasm snapshot. Third integrate the shared dispatcher, both prediction paths and mandatory action transaction without growing oversized files. Fourth add real test-mod fixtures, adversarial rollback/reload tests and vanilla oracle coverage for every map/tag branch; then measure the miss path. None of these stages is implemented here.

• Counterpart scope: does public NeoForge 26.3 require arbitrary tag registrations, override, or different event phases/sides? Recommendation: obtain its public contract before freezing names; retain exact-item admission and vanilla tag precedence until then. Do not infer semantics from its implementation.
• Budgets: which shared limits cover additional Host writes and nesting without refusing legitimate vanilla interactions? Recommendation: use existing runtime/codec budgets where sufficient and pin the largest vanilla washing/container fixture before approving numeric journal limits.
• Prediction authority: are read-only custom decisions on both sides acceptable when hidden server state affects eligibility? Recommendation: let the server correct predictions; offer explicit server-only prediction suppression using the same selected entry, never an alternate item-use route. Confirm the missing-client-resource handshake behavior before code.