Inventory and Banking

Purpose

This report maps DreamBot inventory, equipment, bank-cache, and task-preparation behavior to current n3Plugins owners. The full development plan defines phase order and full parity scope.

The port must preserve the old builder's required, tolerated, protected, equipped, and acquisition policies. It must delete DreamBot widget/cache mechanics and avoid adding another suite-wide item-state cache.

Item-state reads

n3Plugins exposes two distinct read surfaces:

Need	Owner	Contract
Current visible inventory widget entries	Inventory or inventory queries	Reads the visible inventory through the client thread. Use when an action needs a widget.
Known/unknown inventory, equipment, and bank observations	SdkEvents.playerItemState()	Event-backed ItemContainerChanged snapshots with timestamps and separate container identity.
Result-aware inventory action	Api.actions.InventoryActions	Reports target, tab, pacing, dispatch, and failure status.
Result-aware bank action	Api.actions.BankActions and related domain owners	Reports bank readiness, item, quantity, mode, dispatch, and failure status.

InventoryActions delegates to Inventory; it does not read SdkEvents snapshots. Equipment does not exist.

Use event-backed state for preparation and postcondition logic:

PlayerItemStateSnapshot items = SdkEvents.playerItemState();
PlayerItemContainerSnapshot inventory = items.getInventory();
PlayerItemContainerSnapshot equipment = items.getEquipment();
PlayerItemContainerSnapshot bank = items.getBank();

if (!inventory.isKnown() || !equipment.isKnown()) {
    return CarouselResult.stay("item_state_unknown", "Waiting for item containers");
}

A bank snapshot can remain unknown until RuneLite observes the bank container in the current session. Treat unknown as unknown. An unknown or stale bank snapshot does not mean the bank is empty or lacks an item.

Required item contracts

Each AIO module declares four separate item sets:

• Required inventory: items and minimum quantities needed in inventory.
• Required equipment: item and slot requirements that must pass before execution.
• Tolerated inventory: items that may remain but do not satisfy a requirement.
• Protected items: items that banking, dropping, or liquidation must not remove for the active or enabled future tasks.

Do not compress these into one keep-list. The old builder uses the distinctions to avoid gear dump loops, supply dead ends, and liquidation of future requirements.

Module preparation must return one of these decisions:

• Ready from current inventory and equipment.
• Needs bank observation or reconciliation.
• Needs GE or other acquisition.
• Blocked until a known cooldown or external state changes.
• Terminal failure with an actionable reason.

No evaluator branch may fall through without one of those outcomes.

Bank workflow translation

DreamBot code performs procedural bank calls and blocking waits:

if (!Bank.isOpen()) {
    Bank.open();
    Sleep.sleepUntil(Bank::isOpen, 3000);
}
Bank.depositAllExcept("Rune axe");
Bank.withdraw("Tinderbox", 1);

The current n3 workflow accepts SDK loadouts:

InventoryLoadout inventory = new InventoryLoadout();
inventory.add(LoadoutItem.builder(ItemID.TINDERBOX).amount(1).build());

BankRestockPlan plan = BankRestockPlan.builder()
        .inventoryLoadout(inventory)
        .build();

TypesafeCarouselStateMachine<BankWorkflowBuilder.BankRestockState> bankWorkflow =
        BankWorkflowBuilder.create(plan);

BankRestockPlan.Builder exposes inventoryLoadout(...), equipmentLoadout(...), and reconcile(...). It does not expose name-based .keep(...) or .withdraw(...) methods. CarouselResult.delegateTo(...) does not exist. A parent controller or pipeline must retain and pulse the child machine, inspect its WorkflowStatus, and verify the resulting item state.

Use BankRestockPlan.builder().reconcile(inventory, equipment) when both loadouts must match. Follow the Fighter and Inventory Setups consumers before adding another reconciliation path.

What shared banking replaces

Delete these DreamBot-specific mechanics:

• Bank.resetCache() and local DreamBot bank-cache freshness bookkeeping.
• Blocking bank-open, withdraw, deposit, equip, and close waits.
• Raw DreamBot bank widget access.
• Separate action pacing and repeated-click throttles.
• Duplicate bank-object selection and walking when openNearestAccessible() owns the complete requirement.

Preserve these policies:

• Unknown-aware bank reads.
• Required, tolerated, protected, and equipped item distinctions.
• Inventory-first, then bank equipment selection.
• Task-switch preparation and the taskPrepared readiness gate.
• Deposit-box-only Mining flow at Port Sarim.
• Contextual bank choice when the shared accessible-bank selector lacks the old requirement.
• GE acquisition and blocked-task handoff.
• Atomic bank close and later-tick equipment verification.
• Protection against the old withdraw, deposit, GE loop.

BankWorkflowBuilder handles common open, deposit, withdraw, close, and equip states. It does not replace AIO funding, protected-item, tolerated-item, contextual-bank, deposit-box, or task-selection policy by itself.

Preparation flow

Use this order for a task switch:

1. Read current inventory and equipment observations.
2. Resolve the selected module's current required, tolerated, protected, and equipment contracts.
3. Satisfy carried equipment before assuming a bank visit is required.
4. Open the nearest catalog-authorized, route-reachable bank when reconciliation needs it.
5. Refresh the bank observation and distinguish unknown state from known missing items.
6. Reconcile inventory and equipment one action per tick.
7. Close the bank on its own tick.
8. Observe inventory and equipment after closure.
9. Mark the task prepared only after the observed loadout passes.
10. Route missing owned items to acquisition or block the module with a reason.

The controller must not start module execution from a successful bank dispatch or a completed child workflow whose postcondition has not been observed.

Economy handoff

The old builder combines banking with funding and GE decisions. Keep that boundary explicit in n3Plugins:

• Banking reconciles items already owned.
• Acquisition obtains missing items under budget, buy-limit, cooldown, and protected-item rules.
• The scheduler blocks or reroutes a module when acquisition cannot make progress.
• A fresh item observation after collection or withdrawal establishes ownership.

Do not make BankWorkflowBuilder fetch prices, liquidate items, place offers, or select tasks.

Tests

Add focused tests for:

• Unknown inventory, equipment, and bank state.
• Known bank missing an item.
• Carried equipment satisfying a requirement without a bank visit.
• Slot-aware equipment mismatch.
• Required, tolerated, and protected item behavior.
• Stackable quantities and partial inventory quantities.
• Deposit, withdraw, equip, and close dispatch followed by a later observation.
• Port Sarim deposit-box-only flow.
• Insufficient funds, buy-limit block, acquisition cooldown, and all-blocked scheduling.
• Restart, hop, logout, and bank-snapshot invalidation.
• Regression for the withdraw, deposit, GE loop.

Live acceptance must observe the final inventory and equipment loadout. Opening a bank, issuing a withdrawal, or completing static workflow tests does not prove task preparation.