Target contractVerified 2026-07-23Not yet executable

First v4 vertical slice and the only domain whose public action name is frozen before implementation.

Navigation Contract

hexis.navigation.go is the first v4 vertical slice. Lua chooses the destination and constraints; Java/native code owns topology, pathfinding, movement, camera assistance, recovery, cancellation, and cleanup.

Request

local action = hexis.navigation.go({
    destination = {
        x = 100.5,
        y = 64,
        z = 200.5,
        dimension = "minecraft:overworld",
    },
    arrive_within = 2,
    mode = "multimodal",
    constraints = {
        avoid_liquids = true,
        max_fall = 3,
        allow_sprint = true,
    },
    recovery = {
        max_replans = 4,
        stuck_timeout = 2.5,
    },
})

Field	Contract
destination	Required Vec3; current dimension is the default
arrive_within	Horizontal distance, default 1.5, range 0.25..16
mode	walk, multimodal, or a pack-supported mode
constraints	Engine-neutral traversal constraints
recovery	Bounded recovery policy, never an unbounded retry loop
scope	Optional owning child scope

Destination is a feet position where the player may stand. Pack locations are resolved before submission into an engine-neutral destination plus adapter edges.

Execution flow

Native walking verifies pack-provided topology edges before execution. Packs may describe teleport or ability edges but cannot bypass ray, reachability, world, cooldown, or resource checks.

Progress

Navigation progress contains:

{
    phase = "moving",
    position = {x = 80.2, y = 64, z = 170.4},
    remaining = 36.7,
    path_kind = "walk",
    replans = 1,
}

Phases are resolving, planning, moving, recovering, and arriving. Progress is rate-limited and may be coalesced.

Result data

Success data contains final_position, distance_remaining, elapsed, path_kinds, replans, and redacted adapter-edge IDs. It never returns the native path graph or protected planner internals.

Navigation adds these stable failure codes:

Code	Retryable	Meaning
TARGET_INVALID	No	Destination cannot be occupied
WRONG_DIMENSION	Sometimes	No supported transition exists
NO_PATH	Sometimes	No route satisfies current evidence
BLOCKED	Yes	Execution could not recover within policy
PACK_EDGE_INVALID	Yes	Adapter edge failed live verification
DESTINATION_MOVED	Yes	Tracked semantic destination changed

Global timeout, cancellation, world, resource, permission, pack, and internal codes also apply.

Resources and arbitration

Navigation holds movement exclusively. It requests camera only when the selected movement strategy requires view control. Camera policy is assist by default and can be none only when the mechanism supports it. Losing either required lease cancels safely and releases held input before completion.

Only one active movement owner may exist. Passive observation scripts remain concurrent because they hold no control resources.

Required Java boundaries

• immutable world snapshots and world generations;
• client-thread gateway for player input and observations;
• native/Java planner cancellation token;
• resource lease acquired before movement starts;
• bounded replanning and stuck recovery;
• adapter-edge validation at the latest world state;
• telemetry keyed by action ID;
• cleanup that does not depend on Lua callbacks.

Acceptance tasks

The page becomes Implemented only after:

1. reachable walking succeeds within tolerance;
2. an impossible destination returns NO_PATH;
3. cancellation during planning and movement releases input within one tick;
4. an obstacle triggers bounded recovery;
5. world unload returns WORLD_CHANGED without leaked workers;
6. a pack teleport edge passes live verification and executes;
7. the same core contract succeeds without a pack in a local-world fixture;
8. two navigation requests produce an explicit resource conflict;
9. an AI selects navigation.go, handles failure, and invents no polling calls;
10. live Minecraft telemetry confirms acceptable client-tick cost.