@shipload/sdk 1.0.0-next.7 → 1.0.0-next.70

package/src/testing/projection-parity.ts

@@ -0,0 +1,167 @@
+import type {UInt32} from '@wharfkit/antelope'
+import type {ServerContract} from '../contracts'
+import type {ProjectedEntity} from '../scheduling/projection'
+import {type CargoStack, cargoItemToStack, mergeStacks} from '../capabilities/storage'
+
+export interface ContractProjectedState {
+    owner: {toString(): string}
+    coordinates: ServerContract.Types.coordinates
+    energy?: UInt32
+    cargomass: UInt32
+    cargo: ServerContract.Types.cargo_view[]
+    hullmass?: UInt32
+    capacity?: UInt32
+    engines?: ServerContract.Types.movement_stats
+    generator?: ServerContract.Types.energy_stats
+    hauler?: ServerContract.Types.hauler_stats
+    gatherer_lanes: ServerContract.Types.gatherer_lane[]
+    crafter_lanes: ServerContract.Types.crafter_lane[]
+    loader_lanes: ServerContract.Types.loader_lane[]
+}
+
+export interface ProjectionComparisonOptions {
+    step?: number
+}
+
+export function assertProjectionEquals(
+    contract: ContractProjectedState,
+    sdk: ProjectedEntity,
+    options: ProjectionComparisonOptions = {}
+): void {
+    const mismatches: string[] = []
+
+    const record = (name: string, c: unknown, s: unknown) => {
+        if (c !== s) mismatches.push(`  ${name}: contract=${fmt(c)} sdk=${fmt(s)}`)
+    }
+
+    const recordStatBlock = (name: string, c: unknown, s: unknown) => {
+        const cPresent = c !== undefined && c !== null
+        const sPresent = s !== undefined && s !== null
+        if (cPresent !== sPresent) {
+            mismatches.push(
+                `  ${name}: contract=${cPresent ? 'present' : 'absent'} sdk=${sPresent ? 'present' : 'absent'}`
+            )
+            return
+        }
+        if (!cPresent) return
+        const cn = JSON.stringify(normaliseStatBlock(c))
+        const sn = JSON.stringify(normaliseStatBlock(s))
+        if (cn !== sn) mismatches.push(`  ${name}: contract=${cn} sdk=${sn}`)
+    }
+
+    record('coordinates.x', toNum(contract.coordinates.x), Number(sdk.location.x))
+    record('coordinates.y', toNum(contract.coordinates.y), Number(sdk.location.y))
+    record('energy', toNum(contract.energy), Number(sdk.energy))
+    record('cargomass', toNum(contract.cargomass), Number(sdk.cargoMass))
+    record('hullmass', toNum(contract.hullmass), Number(sdk.shipMass))
+    record('capacity', toNum(contract.capacity), sdk.capacity ? Number(sdk.capacity) : undefined)
+
+    recordStatBlock('engines', contract.engines, sdk.engines)
+    recordStatBlock('generator', contract.generator, sdk.generator)
+    recordStatBlock('hauler', contract.hauler, sdk.hauler)
+
+    const normLane = (l: {slot_index?: unknown; [k: string]: unknown}) =>
+        Object.fromEntries(
+            Object.entries(l)
+                .filter(([k]) => k !== 'slot_index')
+                .map(([k, v]) => [k, toNum(v) ?? 0])
+        )
+
+    const compareLanes = (name: string, cLanes: unknown[], sLanes: unknown[]) => {
+        if (cLanes.length !== sLanes.length) {
+            mismatches.push(`  ${name}.length: contract=${cLanes.length} sdk=${sLanes.length}`)
+            return
+        }
+        for (let i = 0; i < cLanes.length; i++) {
+            const cn = JSON.stringify(normLane(cLanes[i] as Record<string, unknown>))
+            const sn = JSON.stringify(normLane(sLanes[i] as Record<string, unknown>))
+            if (cn !== sn) mismatches.push(`  ${name}[${i}]: contract=${cn} sdk=${sn}`)
+        }
+    }
+
+    compareLanes('gatherer_lanes', contract.gatherer_lanes as unknown[], sdk.gathererLanes ?? [])
+    compareLanes('crafter_lanes', contract.crafter_lanes as unknown[], sdk.crafterLanes ?? [])
+    compareLanes('loader_lanes', contract.loader_lanes as unknown[], sdk.loaderLanes ?? [])
+
+    if (contract.cargo.length > 0 || sdk.cargo.length > 0) {
+        const contractCargo = normaliseCargo(mergeContractCargo(contract.cargo))
+        const sdkCargo = normaliseCargo(sdk.cargo)
+        if (contractCargo.length !== sdkCargo.length) {
+            mismatches.push(
+                `  cargo.length: contract=${contractCargo.length} sdk=${sdkCargo.length}`
+            )
+        } else {
+            for (let i = 0; i < contractCargo.length; i++) {
+                const c = contractCargo[i]
+                const s = sdkCargo[i]
+                if (c.itemId !== s.itemId || c.stats !== s.stats || c.quantity !== s.quantity) {
+                    mismatches.push(
+                        `  cargo[${i}]: contract={item:${c.itemId},stats:${c.stats},qty:${c.quantity}} sdk={item:${s.itemId},stats:${s.stats},qty:${s.quantity}}`
+                    )
+                }
+            }
+        }
+    }
+
+    if (mismatches.length > 0) {
+        const header =
+            options.step !== undefined
+                ? `projection divergence at step ${options.step}:`
+                : 'projection divergence:'
+        throw new Error([header, ...mismatches].join('\n'))
+    }
+}
+
+interface NormalisedStack {
+    itemId: number
+    stats: string
+    quantity: string
+}
+
+function mergeContractCargo(cargo: ServerContract.Types.cargo_view[]): CargoStack[] {
+    return cargo.reduce<CargoStack[]>(
+        (acc, row) =>
+            mergeStacks(acc, cargoItemToStack(row as unknown as ServerContract.Types.cargo_item)),
+        []
+    )
+}
+
+function normaliseCargo(cargo: CargoStack[]): NormalisedStack[] {
+    return cargo
+        .map((s) => ({
+            itemId: Number(s.item_id),
+            stats: BigInt(s.stats.toString()).toString(),
+            quantity: BigInt(s.quantity.toString()).toString(),
+        }))
+        .sort(stackSort)
+}
+
+function stackSort(a: NormalisedStack, b: NormalisedStack): number {
+    if (a.itemId !== b.itemId) return a.itemId - b.itemId
+    return a.stats < b.stats ? -1 : a.stats > b.stats ? 1 : 0
+}
+
+function toNum(v: unknown): number | undefined {
+    if (v === undefined || v === null) return undefined
+    if (typeof v === 'number') return v
+    if (typeof v === 'bigint') return Number(v)
+    if (typeof (v as {toNumber?: unknown}).toNumber === 'function') {
+        return (v as {toNumber(): number}).toNumber()
+    }
+    return Number(v as number)
+}
+
+function fmt(v: unknown): string {
+    if (v === undefined) return 'undefined'
+    if (v === null) return 'null'
+    return String(v)
+}
+
+function normaliseStatBlock(block: unknown): Record<string, number> {
+    const out: Record<string, number> = {}
+    const obj = block as Record<string, unknown>
+    for (const k of Object.keys(obj).sort()) {
+        out[k] = toNum(obj[k]) ?? 0
+    }
+    return out
+}

package/src/travel/reach.test.ts

@@ -0,0 +1,86 @@
+import {expect, test} from 'bun:test'
+import type {RouteMoverInput} from './route-simulator'
+import {computeGroupPerLegReach, computePerLegReach, type ReachStats} from './reach'
+
+// Type-level: a RouteMoverInput (webapp's mover shape) must satisfy ReachStats with no cast.
+function acceptsReachStats(_s: ReachStats): void {}
+function checkRouteMoverAssignable(m: RouteMoverInput) {
+    acceptsReachStats(m)
+}
+void checkRouteMoverAssignable
+
+test('capacity basis: reach is generator capacity over engine drain, unrounded', () => {
+    const reach = computePerLegReach({generator: {capacity: 550n}, engines: {drain: 100n}})
+    expect(reach).toBe(5.5)
+})
+
+test('capacity basis is the default when opts is omitted', () => {
+    const reach = computePerLegReach({generator: {capacity: 1000n}, engines: {drain: 250n}})
+    expect(reach).toBe(4)
+})
+
+test('current basis prefers generator capacity over current energy, matching the webapp fallback', () => {
+    const reach = computePerLegReach(
+        {generator: {capacity: 1000n}, engines: {drain: 100n}, energy: 250n},
+        {basis: 'current'}
+    )
+    expect(reach).toBe(10)
+})
+
+test('current basis falls back to current energy when there is no generator', () => {
+    const reach = computePerLegReach({engines: {drain: 100n}, energy: 350n}, {basis: 'current'})
+    expect(reach).toBe(3.5)
+})
+
+test('current basis with a lower current energy still returns the capacity-derived reach', () => {
+    const reach = computePerLegReach(
+        {generator: {capacity: 900n}, engines: {drain: 90n}, energy: 90n},
+        {basis: 'current'}
+    )
+    expect(reach).toBe(10)
+    expect(reach).not.toBe(1)
+})
+
+test('capacity basis throws for a generator-less mover', () => {
+    expect(() => computePerLegReach({engines: {drain: 100n}})).toThrow()
+})
+
+test('current basis throws when there is no current energy figure either', () => {
+    expect(() => computePerLegReach({engines: {drain: 100n}}, {basis: 'current'})).toThrow()
+})
+
+test('an empty mover list has zero reach rather than throwing', () => {
+    expect(computeGroupPerLegReach([])).toBe(0)
+})
+
+test('a group with no moving entity has zero reach', () => {
+    const reach = computeGroupPerLegReach([{generator: {capacity: 1000n}}])
+    expect(reach).toBe(0)
+})
+
+test('a RouteMoverInput-shaped mover with hasMovement: false is excluded from the group', () => {
+    const mover: ReachStats = {
+        hasMovement: false,
+        engines: {drain: 100},
+        generator: {capacity: 1000},
+    }
+    expect(computeGroupPerLegReach([mover])).toBe(0)
+})
+
+test('hasMovement defaults to true when absent', () => {
+    const mover: ReachStats = {engines: {drain: 100}, generator: {capacity: 1000}}
+    expect(computeGroupPerLegReach([mover])).toBe(10)
+})
+
+test('group reach is the minimum across movers', () => {
+    const fast: ReachStats = {engines: {drain: 100n}, generator: {capacity: 1000n}}
+    const slow: ReachStats = {engines: {drain: 100n}, generator: {capacity: 550n}}
+    expect(computeGroupPerLegReach([fast, slow])).toBe(5.5)
+})
+
+// Settled by contracts/test/server/reach-parity.test.ts: the contract truncates, so ceiling here would overclaim reach.
+test('rounding: a fractional reach is left unrounded, not ceiled', () => {
+    const reach = computePerLegReach({generator: {capacity: 550n}, engines: {drain: 100n}})
+    expect(reach).not.toBe(Math.ceil(reach))
+    expect(Math.floor(reach)).toBe(5)
+})

package/src/travel/reach.ts

@@ -0,0 +1,34 @@
+export interface ReachStats {
+    generator?: {capacity: bigint | number}
+    engines?: {drain: bigint | number}
+    energy?: bigint | number
+    hasMovement?: boolean
+}
+
+export interface ComputePerLegReachOptions {
+    basis?: 'capacity' | 'current'
+}
+
+export function computePerLegReach(s: ReachStats, opts: ComputePerLegReachOptions = {}): number {
+    const basis = opts.basis ?? 'capacity'
+    const energy =
+        basis === 'capacity' ? s.generator?.capacity : (s.generator?.capacity ?? s.energy)
+    const drain = s.engines?.drain
+    if (energy === undefined || drain === undefined || Number(drain) === 0) {
+        throw new Error('entity has no usable engine/generator (cannot compute per-leg reach)')
+    }
+    return Number(energy) / Number(drain)
+}
+
+export function computeGroupPerLegReach(
+    participants: ReachStats[],
+    opts: ComputePerLegReachOptions = {}
+): number {
+    const movers = participants.filter(
+        (p) => (p.hasMovement ?? true) && p.engines !== undefined && Number(p.engines.drain) !== 0
+    )
+    if (movers.length === 0) {
+        return 0
+    }
+    return Math.min(...movers.map((m) => computePerLegReach(m, opts)))
+}

package/src/travel/route-build.test.ts

@@ -0,0 +1,63 @@
+import {expect, test} from 'bun:test'
+import type {Coord, SystemGraph} from './route-planner'
+import {planRouteWithRetry} from './route-build'
+
+function countingGraph(opts: {
+    reachable: boolean
+    nearby: (c: Coord) => {coord: Coord; dist: number}[]
+}): {graph: SystemGraph; hasSystemCalls: () => number} {
+    let calls = 0
+    const graph: SystemGraph = {
+        hasSystem: () => {
+            calls++
+            return opts.reachable
+        },
+        nearby: opts.nearby,
+    }
+    return {graph, hasSystemCalls: () => calls}
+}
+
+test('a route found on the first attempt does not retry', () => {
+    const origin: Coord = {x: 0, y: 0}
+    const dest: Coord = {x: 3, y: 0}
+    const {graph, hasSystemCalls} = countingGraph({reachable: true, nearby: () => []})
+
+    const result = planRouteWithRetry({origin, dest, perLegReach: 5, graph})
+
+    expect(result.ok).toBe(true)
+    expect(hasSystemCalls()).toBe(1)
+})
+
+test('a no-path result widens the corridor and retries until a route is found', () => {
+    const origin: Coord = {x: 0, y: 0}
+    const dest: Coord = {x: 100, y: 0}
+    const mid: Coord = {x: 50, y: 28.4}
+    const perLegReach = 6.4
+
+    const {graph, hasSystemCalls} = countingGraph({
+        reachable: true,
+        nearby: (c) => {
+            if (c.x === origin.x && c.y === origin.y) return [{coord: mid, dist: 0}]
+            if (c.x === mid.x && c.y === mid.y) return [{coord: dest, dist: 0}]
+            return []
+        },
+    })
+
+    const result = planRouteWithRetry({origin, dest, perLegReach, graph})
+
+    expect(result.ok).toBe(true)
+    // Excluded from the default corridor, found once corridorSlack widens to perLegReach * 3.
+    expect(hasSystemCalls()).toBe(2)
+})
+
+test('a non-no-path failure returns immediately without retrying', () => {
+    const origin: Coord = {x: 0, y: 0}
+    const dest: Coord = {x: 100, y: 0}
+    const {graph, hasSystemCalls} = countingGraph({reachable: false, nearby: () => []})
+
+    const result = planRouteWithRetry({origin, dest, perLegReach: 5, graph})
+
+    expect(result.ok).toBe(false)
+    if (!result.ok) expect(result.reason).toBe('empty-destination')
+    expect(hasSystemCalls()).toBe(1)
+})

package/src/travel/route-build.ts

@@ -0,0 +1,60 @@
+import {calc_rechargetime} from './travel'
+import {MAX_LEGS, planRoute} from './route-planner'
+import type {
+    Coord,
+    RouteHeuristicCost,
+    RouteLegCost,
+    RouteResult,
+    SystemGraph,
+} from './route-planner'
+import {simulateRoute} from './route-simulator'
+import type {RouteMoverInput} from './route-simulator'
+
+export function planRouteWithRetry(input: {
+    origin: Coord
+    dest: Coord
+    perLegReach: number
+    graph: SystemGraph
+    maxLegs?: number
+    legCost?: RouteLegCost
+    heuristicCost?: RouteHeuristicCost
+}): RouteResult {
+    const args = {...input, maxLegs: input.maxLegs ?? MAX_LEGS}
+    const first = planRoute(args)
+    if (first.ok || first.reason !== 'no-path') return first
+    const widened = planRoute({...args, corridorSlack: input.perLegReach * 3})
+    if (widened.ok || widened.reason !== 'no-path') return widened
+    // The chain imposes no corridor, only per-hop reach, so exhaust the graph (nodeBudget-bounded) before declaring no-path.
+    return planRoute({...args, corridorSlack: Number.POSITIVE_INFINITY})
+}
+
+export function contractRouteLegCost(movers: readonly RouteMoverInput[]): RouteLegCost {
+    return ({from, to, isDestination}) => {
+        const sim = simulateRoute([...movers], [to], from, true)
+        const leg = sim.legs[0]
+        if (!sim.reachable || !leg) return null
+
+        let rechargeAfter = 0
+        for (const mover of movers) {
+            if (!mover.hasMovement || !mover.generator) continue
+            const cost = leg.energyCostByMover[String(mover.ref.entityId)] ?? 0
+            rechargeAfter = Math.max(
+                rechargeAfter,
+                Number(
+                    calc_rechargetime(
+                        mover.generator.capacity,
+                        Math.max(0, mover.generator.capacity - cost),
+                        mover.generator.recharge
+                    )
+                )
+            )
+        }
+
+        return leg.flightSeconds + (isDestination ? 0 : rechargeAfter)
+    }
+}
+
+export function contractRouteHeuristic(movers: readonly RouteMoverInput[]): RouteHeuristicCost {
+    return (from, dest) =>
+        simulateRoute([...movers], [dest], from, true).legs[0]?.flightSeconds ?? 0
+}

package/src/travel/route-planner.ts

@@ -0,0 +1,288 @@
+import {nearbyWormholes, wormholeAt} from '../derivation/wormhole'
+import {Checksum256, type Checksum256Type} from '@wharfkit/antelope'
+
+export interface Coord {
+    x: number
+    y: number
+}
+
+export interface Neighbor {
+    coord: Coord
+    dist: number
+}
+
+export interface SystemGraph {
+    hasSystem(c: Coord): boolean
+    nearby(c: Coord, reachTiles: number): Neighbor[]
+}
+
+export interface RoutePlan {
+    ok: true
+    waypoints: Coord[]
+    legs: number
+    totalDistance: number
+}
+
+export interface RouteLegInput {
+    from: Coord
+    to: Coord
+    distance: number
+    isDestination: boolean
+}
+
+/**
+ * Returns the elapsed-time search cost for a leg, or null when the leg is not contract-feasible.
+ */
+export type RouteLegCost = (leg: RouteLegInput) => number | null
+export type RouteHeuristicCost = (from: Coord, dest: Coord) => number
+
+export type RouteFailureReason = 'empty-destination' | 'no-path' | 'max-legs'
+
+export interface RouteFailure {
+    ok: false
+    reason: RouteFailureReason
+    furthest?: Coord
+    legsNeeded?: number
+    partialWaypoints?: Coord[]
+}
+
+export type RouteResult = RoutePlan | RouteFailure
+
+export interface PlanRouteParams {
+    origin: Coord
+    dest: Coord
+    perLegReach: number
+    graph: SystemGraph
+    corridorSlack?: number
+    nodeBudget?: number
+    maxLegs?: number
+    legCost?: RouteLegCost
+    heuristicCost?: RouteHeuristicCost
+}
+
+const key = (c: Coord): string => `${c.x},${c.y}`
+const sameCoord = (a: Coord, b: Coord): boolean => a.x === b.x && a.y === b.y
+const dist = (a: Coord, b: Coord): number => Math.hypot(a.x - b.x, a.y - b.y)
+
+export const MAX_LEGS = 12
+
+export function planRoute(params: PlanRouteParams): RouteResult {
+    const {origin, dest, perLegReach, graph} = params
+    const corridorSlack = params.corridorSlack ?? perLegReach
+    const nodeBudget = params.nodeBudget ?? 5000
+    const maxLegs = params.maxLegs ?? MAX_LEGS
+
+    if (!graph.hasSystem(dest)) {
+        return {ok: false, reason: 'empty-destination'}
+    }
+
+    const straightLine = dist(origin, dest)
+    if (straightLine <= perLegReach) {
+        const directCost = params.legCost?.({
+            from: origin,
+            to: dest,
+            distance: straightLine,
+            isDestination: true,
+        })
+        if (directCost !== null) {
+            return {ok: true, waypoints: [dest], legs: 1, totalDistance: straightLine}
+        }
+    }
+    const heuristic = (c: Coord): number =>
+        params.heuristicCost?.(c, dest) ??
+        (params.legCost ? 0 : Math.ceil(dist(c, dest) / perLegReach))
+
+    const gScore = new Map<string, number>([[key(origin), 0]])
+    const cameFrom = new Map<string, Coord>()
+    const frontier: {coord: Coord; legs: number; cost: number; f: number; remaining: number}[] = [
+        {coord: origin, legs: 0, cost: 0, f: heuristic(origin), remaining: straightLine},
+    ]
+
+    let furthest = origin
+    let furthestRemaining = dist(origin, dest)
+    let expansions = 0
+    let cappedByMaxLegs = false
+
+    while (frontier.length > 0) {
+        let bestIdx = 0
+        for (let i = 1; i < frontier.length; i++) {
+            const a = frontier[i]
+            const b = frontier[bestIdx]
+            if (a.f < b.f || (a.f === b.f && a.remaining < b.remaining)) {
+                bestIdx = i
+            }
+        }
+        const current = frontier.splice(bestIdx, 1)[0]
+        if (current.cost !== gScore.get(key(current.coord))) continue
+
+        if (sameCoord(current.coord, dest)) {
+            return reconstruct(cameFrom, origin, dest)
+        }
+
+        if (current.remaining < furthestRemaining) {
+            furthestRemaining = current.remaining
+            furthest = current.coord
+        }
+
+        if (++expansions > nodeBudget) break
+
+        for (const n of graph.nearby(current.coord, perLegReach)) {
+            const inCorridor =
+                dist(origin, n.coord) + dist(n.coord, dest) <= straightLine + corridorSlack
+            if (!inCorridor) continue
+
+            const tentativeLegs = current.legs + 1
+            if (tentativeLegs > maxLegs) {
+                cappedByMaxLegs = true
+                continue
+            }
+            const evaluatedCost = params.legCost?.({
+                from: current.coord,
+                to: n.coord,
+                distance: n.dist,
+                isDestination: sameCoord(n.coord, dest),
+            })
+            if (evaluatedCost === null) continue
+            const legCost = evaluatedCost ?? 1
+            if (!(legCost >= 0) || !Number.isFinite(legCost)) continue
+            const nk = key(n.coord)
+            const nextCost = current.cost + legCost
+            if (nextCost < (gScore.get(nk) ?? Infinity)) {
+                gScore.set(nk, nextCost)
+                cameFrom.set(nk, current.coord)
+                const remaining = dist(n.coord, dest)
+                frontier.push({
+                    coord: n.coord,
+                    legs: tentativeLegs,
+                    cost: nextCost,
+                    f: nextCost + heuristic(n.coord),
+                    remaining,
+                })
+            }
+        }
+    }
+
+    if (cappedByMaxLegs) {
+        return {
+            ok: false,
+            reason: 'max-legs',
+            furthest,
+            partialWaypoints: reconstructWaypoints(cameFrom, origin, furthest),
+        }
+    }
+    return {
+        ok: false,
+        reason: 'no-path',
+        furthest,
+        partialWaypoints: reconstructWaypoints(cameFrom, origin, furthest),
+    }
+}
+
+function reconstructWaypoints(cameFrom: Map<string, Coord>, origin: Coord, target: Coord): Coord[] {
+    if (sameCoord(target, origin)) return []
+    const path: Coord[] = [target]
+    let cur = target
+    while (!sameCoord(cur, origin)) {
+        const prev = cameFrom.get(key(cur))
+        if (!prev) break
+        path.unshift(prev)
+        cur = prev
+    }
+    return path.slice(1)
+}
+
+function reconstruct(cameFrom: Map<string, Coord>, origin: Coord, dest: Coord): RoutePlan {
+    const path: Coord[] = [dest]
+    let cur = dest
+    let totalDistance = 0
+    while (!sameCoord(cur, origin)) {
+        const prev = cameFrom.get(key(cur))
+        if (!prev) break
+        totalDistance += dist(prev, cur)
+        path.unshift(prev)
+        cur = prev
+    }
+    const waypoints = path.slice(1)
+    return {ok: true, waypoints, legs: waypoints.length, totalDistance}
+}
+
+export interface ScanProvider {
+    getLocationType(seedHex: string, x: number, y: number): number
+    systemsInBox(
+        seedHex: string,
+        xMin: number,
+        yMin: number,
+        xMax: number,
+        yMax: number
+    ): {x: number; y: number; locType: number}[]
+}
+
+// Keyed by provider identity, so pass a stable one (the `@shipload/sdk/scan` namespace).
+const graphCache = new WeakMap<ScanProvider, Map<string, SystemGraph>>()
+
+export function sdkSystemGraph(seed: Checksum256Type, scan: ScanProvider): SystemGraph {
+    const s = Checksum256.from(seed)
+    const seedHex = s.toString()
+    let bySeed = graphCache.get(scan)
+    if (!bySeed) {
+        bySeed = new Map()
+        graphCache.set(scan, bySeed)
+    }
+    const cached = bySeed.get(seedHex)
+    if (cached) return cached
+    const graph = wasmSystemGraph(s, seedHex, scan)
+    bySeed.set(seedHex, graph)
+    return graph
+}
+
+const SCAN_BUCKET = 48
+
+function wasmSystemGraph(s: Checksum256, seedHex: string, scan: ScanProvider): SystemGraph {
+    // Per-bucket system cache: reused across the overlapping node queries A* makes (and across routes).
+    const bucketCache = new Map<string, {x: number; y: number}[]>()
+    const bucketSystems = (bx: number, by: number): {x: number; y: number}[] => {
+        const k = `${bx},${by}`
+        let v = bucketCache.get(k)
+        if (v === undefined) {
+            const xMin = bx * SCAN_BUCKET
+            const yMin = by * SCAN_BUCKET
+            v = scan
+                .systemsInBox(seedHex, xMin, yMin, xMin + SCAN_BUCKET - 1, yMin + SCAN_BUCKET - 1)
+                .map((cell) => ({x: cell.x, y: cell.y}))
+            bucketCache.set(k, v)
+        }
+        return v
+    }
+    return {
+        hasSystem: (c) =>
+            scan.getLocationType(seedHex, c.x, c.y) !== 0 || wormholeAt(s, c.x, c.y) !== null,
+        nearby: (c, reachTiles) => {
+            const r = Math.floor(reachTiles)
+            const seen = new Set<string>([`${c.x},${c.y}`])
+            const out: Neighbor[] = []
+            const bx0 = Math.floor((c.x - r) / SCAN_BUCKET)
+            const bx1 = Math.floor((c.x + r) / SCAN_BUCKET)
+            const by0 = Math.floor((c.y - r) / SCAN_BUCKET)
+            const by1 = Math.floor((c.y + r) / SCAN_BUCKET)
+            for (let bx = bx0; bx <= bx1; bx++) {
+                for (let by = by0; by <= by1; by++) {
+                    for (const cell of bucketSystems(bx, by)) {
+                        const dist = Math.hypot(cell.x - c.x, cell.y - c.y)
+                        if (dist > reachTiles) continue
+                        const k = `${cell.x},${cell.y}`
+                        if (seen.has(k)) continue
+                        seen.add(k)
+                        out.push({coord: {x: cell.x, y: cell.y}, dist})
+                    }
+                }
+            }
+            for (const coord of nearbyWormholes(s, c.x, c.y, reachTiles)) {
+                const k = `${coord.x},${coord.y}`
+                if (seen.has(k)) continue
+                seen.add(k)
+                out.push({coord, dist: Math.hypot(coord.x - c.x, coord.y - c.y)})
+            }
+            return out
+        },
+    }
+}