Public API contractVerified 2026-08-13Not yet executable

The route-backed azalea scheduler and hexis.foraging.catch_tadpole are implemented in the source foundation; they are not AI-runnable until distributed-build acceptance.

Lua v4 Galatea Workload

The Galatea source foundation now composes tree harvesting with bounded azalea detours and one atomic Tadpole catch action. Lua schedules the activities; Hexis owns pathing, harvesting, aiming, interaction, hotbar safety, and cleanup.

This page remains non-executable until a named distributed build passes controlled live acceptance.

Catch one observed Tadpole

hexis.foraging.catch_tadpole requires both interaction and inventory:

local observed = hexis.world.entities.find({
    area = {kind = "radius", radius = 4.5},
    selector = {type_ids = {"minecraft:tadpole"}},
    limit = 8,
})

local tadpole = observed.entities[1]
if tadpole and tadpole.alive then
    local result = hexis.await(hexis.foraging.catch_tadpole({
        target = {ref = tadpole.ref},
        held = {name_patterns = {"Fishing Net"}},
    }), {timeout = 12})
end

The request has exactly target and held. target has exactly one ref, which contains a UUID id and non-negative world_generation. held has exactly name_patterns: 1 through 16 nonblank strings of at most 128 characters. Unknown or malformed fields are catchable Lua errors before dispatch.

The action's potential resources are exactly CAMERA, ATTACK_USE, and HOTBAR. It first proves that the reference belongs to the current generation and still resolves to a live vanilla minecraft:tadpole. It selects a matching net, aims until the live crosshair hits that exact UUID, sends one vanilla entity use, and observes whether that target disappears. Each aim is bounded to 3 seconds and each post-use disappearance check to 300 milliseconds. It may make at most three uses.

This is one specific bounded transaction. It does not acquire movement, chase a Tadpole, pathfind toward it, substitute another entity, throw arbitrary items, or expose a general fishing API. Lua chooses a nearby candidate from bounded world evidence before invoking it.

Result

A mechanism result has this exact data:

{
    caught = true,
    attempts = 1,
    target = {
        id = "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
        world_generation = 8,
    },
}

attempts is from 0 through 3. caught is true only for ok. When execution reaches a mechanism outcome, data contains exactly caught, attempts, and target. The typed mechanism outcomes are:

Code	Retryable	Meaning
ok	No	The exact Tadpole disappeared after a use
item_not_found	No	No matching fishing net was available or it changed before use
target_lost	Yes	The exact Tadpole disappeared or stopped being a live Tadpole
aim_failed	Yes	Exact crosshair aim or vanilla use could not be completed
timeout	Yes	The Tadpole remained after three uses
busy	Yes	Required Hexis or vanilla use control was unavailable
cancelled	No	The transaction was cancelled

Those mechanism outcomes include caught, attempts, and target. A stale reference instead returns non-retryable world_changed with empty data before controls are acquired. An already-absent target returns retryable target_lost with empty data. Contention before mechanism execution returns retryable busy with empty data. Quarantined controls, mechanism construction failure, or safe-stop failure return non-retryable internal_error with empty data. A host await timeout or explicit cancellation follows the shared lifecycle and can return empty data rather than a mechanism attempt record. Authority/runtime invalidation follows that same lifecycle. A worker interruption not caused by an existing cancellation can instead return retryable cancelled with empty data.

Guarded hotbar restoration

The action records the previous hotbar state while selecting the fishing net. On every terminal path, cleanup releases physical use and camera control before the result becomes visible, then restores the old slot only if the selected slot and net fingerprint still match what this action selected. A manual or later hotbar change wins over stale cleanup.

If safe-stop cannot verify or complete cleanup, the visible result becomes non-retryable internal_error and the shared controls are quarantined. Scripts must not add a second hotbar-restoration path.

Route-backed azalea scheduler

The official Galatea config schema version 2 supplies exactly route, competition_mode, and max_azaleas. route defaults to official:Galatea_Foraging. competition_mode is a boolean that defaults to true. max_azaleas is an integer from 0 through 15 with default 6 and step 1. Workload schema 5 supplies separate tree and Flowering Azalea route filters and exact block-ID priority maps without duplicating the route or azalea cap. The current scheduler:

1. When competition_mode is true, tries an eligible azalea route seed before the next tree. When false, it skips azalea routes and Tadpole catches.
2. Does not start another azalea harvest once the number of successful azalea harvest actions reaches max_azaleas. Each successful action counts once, regardless of blocks_mined; 0 disables azalea detours.
3. Falls through to a tree when no eligible azalea seed exists.
4. Defers further azaleas after a failed or zero-block azalea harvest until a tree succeeds.
5. Applies the bounded azalea retry cooldown to the selected seed.
6. After a successful azalea, observes nearby Tadpoles and attempts only the first returned live candidate.
7. Resets the azalea count and deferral only after a successful nonempty tree harvest.
8. Waits 1 second after a successful zero-block tree result so an empty route cannot create a hot loop.

Eligible seed lists are capped at 128 by the script. Route results are already bounded by the host and filtered by the exact workload entry block type before that host cap. item_not_found disables further fishing-net attempts for the rest of the run; it does not stop tree or azalea harvesting. A retryable catch failure also lets the scheduler continue, while any other non-retryable catch failure stops the run.

Current exclusions

This slice does not yet implement:

• tree_mode, a small-tree mode, or an alternate small-tree schedule;
• stop_at_max_contest, contest score tracking, or automatic stopping at a contest maximum;
• contest detection or automatic selection of competition_mode;
• activation of an axe's held-item ability, including a right-click or throw;
• selling, inventory disposal, or a sell-recovery policy.

competition_mode is only a customer-controlled switch for the bounded azalea and Tadpole scheduler. It is not evidence of those excluded contest features. The exclusions must not be inferred from the existing selectors, routes, or cooldowns; they need separate contracts and acceptance evidence.