@shipload/sdk 1.0.0-next.34 → 1.0.0-next.36

package/src/scheduling/cancel.ts

@@ -0,0 +1,209 @@
+import type {ServerContract} from '../contracts'
+import {TaskCancelable, TaskType} from '../types'
+import {calcCargoItemMass} from '../capabilities/storage'
+import {taskCargoEffect, cargoKey} from './availability'
+import * as schedule from './schedule'
+import {validateSchedule, type Projectable} from './projection'
+
+export enum CancelBlockReason {
+    TASK_NEVER = 'TASK_NEVER',
+    BEFORE_START_RUNNING = 'BEFORE_START_RUNNING',
+    DONE = 'DONE',
+    CONTAINS_LINKED_TASK = 'CONTAINS_LINKED_TASK',
+    WOULD_STRAND = 'WOULD_STRAND',
+    WOULD_OVERFILL = 'WOULD_OVERFILL',
+    NOT_OWNER = 'NOT_OWNER',
+}
+
+type Task = InstanceType<typeof ServerContract.Types.task>
+type EntityInfo = InstanceType<typeof ServerContract.Types.entity_info>
+type EntityRef = InstanceType<typeof ServerContract.Types.entity_ref>
+type CargoItem = InstanceType<typeof ServerContract.Types.cargo_item>
+
+export interface CancelRefund {
+    giver: EntityRef
+    cargo: CargoItem[]
+}
+export interface CancelReleasedHold {
+    counterpart: EntityRef
+    kind: number
+}
+export interface CancelEffects {
+    refunds: CancelRefund[]
+    releasedHolds: CancelReleasedHold[]
+    abandonsRunning: boolean
+    keepsPlotDeposits?: {plot: EntityRef}
+    energyForfeited?: number
+}
+export interface CancelPlan {
+    ok: boolean
+    blockedReason?: CancelBlockReason
+    range: {count: number; taskIndices: number[]}
+    effects: CancelEffects
+}
+export interface CancelEligibilityInput {
+    now: Date
+    counterparts?: Map<string, EntityInfo>
+}
+
+const EMPTY_EFFECTS: CancelEffects = {refunds: [], releasedHolds: [], abandonsRunning: false}
+
+function postCancelEntity(entity: EntityInfo, laneKey: number, fromTaskIndex: number): EntityInfo {
+    const clone = (entity.constructor as typeof ServerContract.Types.entity_info).from(
+        JSON.parse(JSON.stringify(entity.toJSON()))
+    ) as EntityInfo
+    const lane = clone.lanes.find((l) => l.lane_key.toNumber() === laneKey)!
+    lane.schedule.tasks = lane.schedule.tasks.slice(0, fromTaskIndex)
+    return clone
+}
+
+function feasibleAfterCancel(post: EntityInfo): boolean {
+    const ordered = schedule.orderedTasks(post as unknown as Projectable)
+    const base = new Map<string, number>()
+    for (const c of post.cargo ?? []) {
+        const k = cargoKey(c)
+        base.set(k, (base.get(k) ?? 0) + c.quantity.toNumber())
+    }
+    const isConsumer = (t: Task) =>
+        t.type.toNumber() === TaskType.CRAFT || t.type.toNumber() === TaskType.UNLOAD
+    for (const self of ordered) {
+        if (!isConsumer(self.task)) continue
+        const map = new Map(base)
+        for (const other of ordered) {
+            if (other.completesAt.getTime() >= self.completesAt.getTime()) continue
+            for (const out of taskCargoEffect(other.task).added) {
+                map.set(cargoKey(out), (map.get(cargoKey(out)) ?? 0) + out.quantity.toNumber())
+            }
+        }
+        for (const other of ordered) {
+            if (other === self) continue
+            for (const inp of taskCargoEffect(other.task).removed) {
+                const cur = map.get(cargoKey(inp)) ?? 0
+                map.set(cargoKey(inp), Math.max(0, cur - inp.quantity.toNumber()))
+            }
+        }
+        for (const inp of taskCargoEffect(self.task).removed) {
+            if ((map.get(cargoKey(inp)) ?? 0) < inp.quantity.toNumber()) return false
+        }
+    }
+    try {
+        validateSchedule(post as unknown as Projectable)
+    } catch {
+        return false
+    }
+    return true
+}
+
+interface Timing {
+    startsAt: number
+    completesAt: number
+    running: boolean
+    done: boolean
+}
+
+function laneTiming(
+    lane: {schedule: {started: {toDate(): Date}; tasks: Task[]}},
+    nowMs: number
+): Timing[] {
+    const startedMs = lane.schedule.started.toDate().getTime()
+    let endSec = 0
+    return lane.schedule.tasks.map((t) => {
+        const startsAt = startedMs + endSec * 1000
+        endSec += t.duration.toNumber()
+        const completesAt = startedMs + endSec * 1000
+        return {
+            startsAt,
+            completesAt,
+            running: nowMs >= startsAt && nowMs < completesAt,
+            done: nowMs >= completesAt,
+        }
+    })
+}
+
+export function cancelEligibility(
+    entity: EntityInfo,
+    laneKey: number,
+    fromTaskIndex: number,
+    input: CancelEligibilityInput
+): CancelPlan {
+    const lane = (entity.lanes ?? []).find((l) => l.lane_key.equals(laneKey))
+    if (!lane || fromTaskIndex < 0 || fromTaskIndex >= lane.schedule.tasks.length) {
+        return {ok: false, range: {count: 0, taskIndices: []}, effects: {...EMPTY_EFFECTS}}
+    }
+
+    const tasks = lane.schedule.tasks
+    const timing = laneTiming(lane, input.now.getTime())
+    const taskIndices: number[] = []
+    for (let i = fromTaskIndex; i < tasks.length; i++) taskIndices.push(i)
+    const range = {count: taskIndices.length, taskIndices}
+
+    const block = (blockedReason: CancelBlockReason): CancelPlan => ({
+        ok: false,
+        blockedReason,
+        range,
+        effects: {...EMPTY_EFFECTS},
+    })
+
+    for (const i of taskIndices) {
+        const t = tasks[i]
+        if (t.entitygroup && !t.entitygroup.equals(0))
+            return block(CancelBlockReason.CONTAINS_LINKED_TASK)
+    }
+
+    for (const i of taskIndices) {
+        const t = tasks[i]
+        if (timing[i].done) return block(CancelBlockReason.DONE)
+        if (t.cancelable.equals(TaskCancelable.NEVER) && !t.type.equals(TaskType.IDLE))
+            return block(CancelBlockReason.TASK_NEVER)
+        if (t.cancelable.equals(TaskCancelable.BEFORE_START) && timing[i].running)
+            return block(CancelBlockReason.BEFORE_START_RUNNING)
+    }
+
+    const post = postCancelEntity(entity, laneKey, fromTaskIndex)
+    if (!feasibleAfterCancel(post)) return block(CancelBlockReason.WOULD_STRAND)
+
+    const effects: CancelEffects = {refunds: [], releasedHolds: [], abandonsRunning: false}
+    let energyForfeited = 0
+    for (const i of taskIndices) {
+        const t = tasks[i]
+        if (timing[i].running && t.cancelable.equals(TaskCancelable.ALWAYS))
+            effects.abandonsRunning = true
+        if (t.energy_cost) energyForfeited += t.energy_cost.toNumber()
+        if (t.type.equals(TaskType.BUILDPLOT) && t.entitytarget)
+            effects.keepsPlotDeposits = {plot: t.entitytarget}
+        if (t.hold && t.entitytarget) {
+            const counterpart = input.counterparts?.get(t.entitytarget.entity_id.toString())
+            const hold =
+                (counterpart?.holds ?? []).find((h) => h.id.equals(t.hold!)) ??
+                (entity.holds ?? []).find((h) => h.id.equals(t.hold!))
+            if (hold) {
+                const kind = hold.kind.toNumber()
+                effects.releasedHolds.push({counterpart: t.entitytarget, kind})
+                if (kind === 1 /* HOLD_PULL */) {
+                    effects.refunds.push({giver: t.entitytarget, cargo: t.cargo})
+                    const giver = counterpart
+                    if (giver) {
+                        const returned = t.cargo.reduce(
+                            (s, c) => s + calcCargoItemMass(c).toNumber(),
+                            0
+                        )
+                        const cap = giver.capacity
+                            ? giver.capacity.toNumber()
+                            : Number.MAX_SAFE_INTEGER
+                        if (giver.cargomass.toNumber() + returned > cap) {
+                            return {
+                                ok: false,
+                                blockedReason: CancelBlockReason.WOULD_OVERFILL,
+                                range,
+                                effects: {...EMPTY_EFFECTS},
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+    if (energyForfeited > 0) effects.energyForfeited = energyForfeited
+
+    return {ok: true, range, effects}
+}

package/src/scheduling/lanes.test.ts

@@ -0,0 +1,249 @@
+import {UInt8, UInt16, UInt64} from '@wharfkit/antelope'
+import {expect, test} from 'bun:test'
+import {encodeStats} from '../derivation/crafting'
+import {computeGathererYield, computeGathererDepth, computeGathererDrain} from '../nft/description'
+import {computeLoaderThrust, computeLoaderMass} from '../nft/description'
+import {computeCrafterSpeed, computeCrafterDrain} from '../nft/description'
+import {applySlotMultiplier} from '../entities/slot-multiplier'
+import {getSlotAmp} from '../entities/slot-multiplier'
+import {getEntityLayout} from '../data/recipes-runtime'
+import {ITEM_GATHERER_T1, ITEM_LOADER_T1, ITEM_CRAFTER_T1} from '../data/item-ids'
+import {
+    workerLaneKey,
+    resolveLaneGatherer,
+    resolveLaneCrafter,
+    resolveLaneLoader,
+    selectGatherLane,
+} from './lanes'
+import {LANE_MOBILITY} from './schedule'
+import type {ServerContract} from '../contracts'
+
+type ModuleEntry = ServerContract.Types.module_entry
+type Lane = ServerContract.Types.lane
+
+// Real gatherer-bearing entity: extractor 10203 has [generator@0, gatherer@1].
+const EXTRACTOR_GATHERER = 10203
+const GATHERER_SLOT_IDX = 1
+const GATHERER_LANE_KEY = GATHERER_SLOT_IDX + 1 // = 2
+
+function makeModuleEntry(itemId: number, stats: bigint): ModuleEntry {
+    return {
+        type: UInt8.from(0),
+        installed: {
+            item_id: UInt16.from(itemId),
+            stats: UInt64.from(stats),
+        },
+    } as unknown as ModuleEntry
+}
+
+function makeBusyLane(laneKey: number): Lane {
+    return {
+        lane_key: UInt8.from(laneKey),
+        schedule: {
+            started: {toDate: () => new Date()} as any,
+            tasks: [{duration: UInt64.from(100)} as any],
+        },
+    } as unknown as Lane
+}
+
+// gatherer: stats = [str=300, tol=200, con=400], tier=1
+const GATH_STR = 300
+const GATH_TOL = 200
+const GATH_CON = 400
+const gathererStats1 = encodeStats([GATH_STR, GATH_TOL, GATH_CON])
+
+// loader: stats = [ins=300, pla=500]
+const LOADER_INS = 300
+const LOADER_PLA = 500
+const loaderStats = encodeStats([LOADER_INS, LOADER_PLA])
+
+// crafter: stats = [rea=400, fin=300]
+const CRAFTER_REA = 400
+const CRAFTER_FIN = 300
+const crafterStats = encodeStats([CRAFTER_REA, CRAFTER_FIN])
+
+// --- resolveLaneGatherer ---
+
+test('resolveLaneGatherer reads the layout slot amp and applies it to yield (parity formula)', () => {
+    // Gatherer at the entity's real gatherer slot (index 1 => laneKey 2); amp comes from getEntityLayout(10203).
+    const modules: ModuleEntry[] = [
+        makeModuleEntry(ITEM_GATHERER_T1, gathererStats1), // slot 0 (generator slot, ignored)
+        makeModuleEntry(ITEM_GATHERER_T1, gathererStats1), // slot 1 (gatherer slot)
+    ]
+    const result = resolveLaneGatherer(modules, EXTRACTOR_GATHERER, GATHERER_LANE_KEY)
+
+    const layout = getEntityLayout(EXTRACTOR_GATHERER)?.slots ?? []
+    const ampFromLayout = getSlotAmp(layout, GATHERER_SLOT_IDX)
+
+    // The resolver routes through the real layout's amp, not a hardcoded 100.
+    expect(result.outputPct).toBe(ampFromLayout)
+    // Yield equals the contract formula clamp_to_uint16(compute_gatherer_yield(str) * amp / 100).
+    expect(result.yield).toBe(applySlotMultiplier(computeGathererYield(GATH_STR), ampFromLayout))
+    expect(result.drain).toBe(computeGathererDrain(GATH_CON))
+    expect(result.depth).toBe(computeGathererDepth(GATH_TOL, 1))
+    expect(result.slotIndex).toBe(GATHERER_SLOT_IDX)
+})
+
+test('resolveLaneGatherer amp-scaling parity holds for a non-100 amp', () => {
+    // Parity for a non-100 amp: clamp_to_uint16(value * amp / 100).
+    expect(applySlotMultiplier(computeGathererYield(GATH_STR), 80)).toBe(
+        Math.min(Math.floor((computeGathererYield(GATH_STR) * 80) / 100), 65535)
+    )
+    expect(applySlotMultiplier(computeGathererYield(GATH_STR), 120)).toBe(
+        Math.floor((computeGathererYield(GATH_STR) * 120) / 100)
+    )
+})
+
+test('resolveLaneGatherer throws on out-of-range laneKey', () => {
+    const modules: ModuleEntry[] = [makeModuleEntry(ITEM_GATHERER_T1, gathererStats1)]
+    expect(() => resolveLaneGatherer(modules, ITEM_GATHERER_T1, 5)).toThrow(
+        'gatherer lane has no module'
+    )
+})
+
+test('resolveLaneGatherer throws on laneKey=0 (slot=255 off-by-one boundary)', () => {
+    const modules: ModuleEntry[] = [makeModuleEntry(ITEM_GATHERER_T1, gathererStats1)]
+    expect(() => resolveLaneGatherer(modules, ITEM_GATHERER_T1, 0)).toThrow(
+        'gatherer lane has no module'
+    )
+})
+
+// --- resolveLaneCrafter ---
+
+test('resolveLaneCrafter returns correct stats for slot 0 (laneKey=1)', () => {
+    const modules: ModuleEntry[] = [makeModuleEntry(ITEM_CRAFTER_T1, crafterStats)]
+    const result = resolveLaneCrafter(modules, ITEM_CRAFTER_T1, 1)
+    const layout = getEntityLayout(ITEM_CRAFTER_T1)?.slots ?? []
+    const amp = getSlotAmp(layout, 0)
+    expect(result.slotIndex).toBe(0)
+    expect(result.speed).toBe(applySlotMultiplier(computeCrafterSpeed(CRAFTER_REA), amp))
+    expect(result.drain).toBe(computeCrafterDrain(CRAFTER_FIN))
+    expect(result.outputPct).toBe(amp)
+})
+
+test('resolveLaneCrafter throws on out-of-range laneKey', () => {
+    const modules: ModuleEntry[] = [makeModuleEntry(ITEM_CRAFTER_T1, crafterStats)]
+    expect(() => resolveLaneCrafter(modules, ITEM_CRAFTER_T1, 5)).toThrow(
+        'crafter lane has no module'
+    )
+})
+
+test('resolveLaneCrafter throws on laneKey=0 (slot=255 off-by-one boundary)', () => {
+    const modules: ModuleEntry[] = [makeModuleEntry(ITEM_CRAFTER_T1, crafterStats)]
+    expect(() => resolveLaneCrafter(modules, ITEM_CRAFTER_T1, 0)).toThrow(
+        'crafter lane has no module'
+    )
+})
+
+// --- resolveLaneLoader ---
+
+test('resolveLaneLoader returns correct stats for slot 0 (laneKey=1)', () => {
+    const modules: ModuleEntry[] = [makeModuleEntry(ITEM_LOADER_T1, loaderStats)]
+    const result = resolveLaneLoader(modules, ITEM_LOADER_T1, 1)
+    const layout = getEntityLayout(ITEM_LOADER_T1)?.slots ?? []
+    const amp = getSlotAmp(layout, 0)
+    expect(result.valid).toBe(true)
+    expect(result.slotIndex).toBe(0)
+    expect(result.thrust).toBe(applySlotMultiplier(computeLoaderThrust(LOADER_PLA), amp))
+    expect(result.mass).toBe(computeLoaderMass(LOADER_INS))
+    expect(result.outputPct).toBe(amp)
+})
+
+test('resolveLaneLoader soft-returns invalid for LANE_MOBILITY (key 0), never throws', () => {
+    const modules: ModuleEntry[] = [makeModuleEntry(ITEM_LOADER_T1, loaderStats)]
+    const result = resolveLaneLoader(modules, ITEM_LOADER_T1, LANE_MOBILITY)
+    expect(result.valid).toBe(false)
+    expect(result.thrust).toBe(0)
+    expect(result.mass).toBe(0)
+})
+
+test('resolveLaneLoader soft-returns invalid for a missing/out-of-range module, never throws', () => {
+    const modules: ModuleEntry[] = [makeModuleEntry(ITEM_LOADER_T1, loaderStats)]
+    const result = resolveLaneLoader(modules, ITEM_LOADER_T1, 5)
+    expect(result.valid).toBe(false)
+    expect(result.thrust).toBe(0)
+    expect(result.mass).toBe(0)
+})
+
+// --- depth-aware workerLaneKey ---
+
+test('workerLaneKey with stratum picks first-free reaching gatherer', () => {
+    const shallowStats = encodeStats([100, 200, 100]) // tol=200 => depth=1500 for tier1
+    const deepStats = encodeStats([100, 900, 100]) // tol=900 => depth=5000 for tier1
+    const modules: ModuleEntry[] = [
+        makeModuleEntry(ITEM_GATHERER_T1, shallowStats),
+        makeModuleEntry(ITEM_GATHERER_T1, deepStats),
+    ]
+    const laneKey = workerLaneKey(modules, 'gatherer', [], 2000)
+    expect(laneKey).toBe(2) // slot 1 => laneKey 2
+})
+
+test('workerLaneKey with stratum: first free reaching is preferred over busy reaching', () => {
+    const deepStats = encodeStats([100, 900, 100]) // tol=900 => depth=5000 for tier1
+    const modules: ModuleEntry[] = [
+        makeModuleEntry(ITEM_GATHERER_T1, deepStats),
+        makeModuleEntry(ITEM_GATHERER_T1, deepStats),
+    ]
+    const lanes: Lane[] = [makeBusyLane(1)] // slot 0 is busy
+    const laneKey = workerLaneKey(modules, 'gatherer', lanes, 2000)
+    expect(laneKey).toBe(2) // slot 1 (laneKey=2) is free and reaching
+})
+
+test('workerLaneKey with stratum: returns lowest reaching (busy) when all reaching are busy', () => {
+    const deepStats = encodeStats([100, 900, 100]) // tol=900 => depth=5000 for tier1
+    const modules: ModuleEntry[] = [
+        makeModuleEntry(ITEM_GATHERER_T1, deepStats),
+        makeModuleEntry(ITEM_GATHERER_T1, deepStats),
+    ]
+    const lanes: Lane[] = [makeBusyLane(1), makeBusyLane(2)]
+    const laneKey = workerLaneKey(modules, 'gatherer', lanes, 2000)
+    expect(laneKey).toBe(1) // lowest reaching is slot 0 => laneKey 1
+})
+
+test('workerLaneKey with stratum throws "no gatherer reaches this stratum" when none reach', () => {
+    const shallowStats = encodeStats([100, 10, 100]) // tol=10 => depth=550 for tier1
+    const modules: ModuleEntry[] = [makeModuleEntry(ITEM_GATHERER_T1, shallowStats)]
+    expect(() => workerLaneKey(modules, 'gatherer', [], 5000)).toThrow(
+        'no gatherer reaches this stratum'
+    )
+})
+
+test('workerLaneKey without stratum still works (non-gatherer path)', () => {
+    const modules: ModuleEntry[] = [makeModuleEntry(ITEM_CRAFTER_T1, crafterStats)]
+    const laneKey = workerLaneKey(modules, 'crafter', [])
+    expect(laneKey).toBe(1)
+})
+
+// --- selectGatherLane: both real error paths ---
+
+test('selectGatherLane auto-pick returns the depth-aware lane', () => {
+    const shallowStats = encodeStats([100, 200, 100]) // depth=1500 for tier1
+    const deepStats = encodeStats([100, 900, 100]) // depth=5000 for tier1
+    const modules: ModuleEntry[] = [
+        makeModuleEntry(ITEM_GATHERER_T1, shallowStats),
+        makeModuleEntry(ITEM_GATHERER_T1, deepStats),
+    ]
+    expect(selectGatherLane(modules, ITEM_GATHERER_T1, [], 2000)).toBe(2)
+})
+
+test('selectGatherLane auto-pick throws "no gatherer reaches this stratum" when none reach', () => {
+    const shallowStats = encodeStats([100, 10, 100]) // depth=550 for tier1
+    const modules: ModuleEntry[] = [makeModuleEntry(ITEM_GATHERER_T1, shallowStats)]
+    expect(() => selectGatherLane(modules, ITEM_GATHERER_T1, [], 5000)).toThrow(
+        'no gatherer reaches this stratum'
+    )
+})
+
+test('selectGatherLane explicit slot returns its laneKey when stratum is within depth', () => {
+    const deepStats = encodeStats([100, 900, 100]) // depth=5000 for tier1
+    const modules: ModuleEntry[] = [makeModuleEntry(ITEM_GATHERER_T1, deepStats)]
+    expect(selectGatherLane(modules, ITEM_GATHERER_T1, [], 2000, 0)).toBe(1) // slot 0 => laneKey 1
+})
+
+test('selectGatherLane explicit slot too shallow throws "stratum exceeds gatherer depth"', () => {
+    const shallowStats = encodeStats([100, 10, 100]) // depth=550 for tier1
+    const modules: ModuleEntry[] = [makeModuleEntry(ITEM_GATHERER_T1, shallowStats)]
+    expect(() => selectGatherLane(modules, ITEM_GATHERER_T1, [], 5000, 0)).toThrow(
+        'stratum exceeds gatherer depth'
+    )
+})

package/src/scheduling/lanes.ts

@@ -1,12 +1,47 @@
 import type {ServerContract} from '../contracts'
 import {getItem} from '../data/catalog'
+import {getEntityLayout} from '../data/recipes-runtime'
+import {decodeStat} from '../derivation/crafting'
+import {gathererDepthForTier} from '../derivation/capabilities'
+import {applySlotMultiplier, getSlotAmp} from '../entities/slot-multiplier'
+import {
+    computeGathererYield,
+    computeGathererDrain,
+    computeLoaderThrust,
+    computeLoaderMass,
+    computeCrafterSpeed,
+    computeCrafterDrain,
+} from '../nft/description'
 import type {ModuleType} from '../types'
-import {getLane, type ScheduleData} from './schedule'
+import {getLane, LANE_MOBILITY, type ScheduleData} from './schedule'
 
 type ModuleEntry = ServerContract.Types.module_entry
 type Lane = ServerContract.Types.lane
 type Schedule = ServerContract.Types.schedule
 
+export interface ResolvedGathererLane {
+    slotIndex: number
+    yield: number
+    drain: number
+    depth: number
+    outputPct: number
+}
+
+export interface ResolvedCrafterLane {
+    slotIndex: number
+    speed: number
+    drain: number
+    outputPct: number
+}
+
+export interface ResolvedLoaderLane {
+    slotIndex: number
+    thrust: number
+    mass: number
+    outputPct: number
+    valid: boolean
+}
+
 export function laneKeyForModule(slotIndex: number): number {
     return slotIndex + 1
 }
@@ -16,11 +51,114 @@ function laneIsFree(lanes: Lane[], laneKey: number): boolean {
     return lane ? lane.schedule.tasks.length === 0 : true
 }
 
+export function resolveLaneGatherer(
+    modules: ModuleEntry[],
+    entityItemId: number,
+    laneKey: number
+): ResolvedGathererLane {
+    const idx = laneKey - 1
+    const installed = idx >= 0 && idx < modules.length ? modules[idx].installed : undefined
+    if (!installed) throw new Error('gatherer lane has no module')
+    const item = getItem(Number(installed.item_id.value ?? installed.item_id))
+    if (item.moduleType !== 'gatherer') throw new Error('lane module is not a gatherer')
+    const stats = BigInt(installed.stats.toString())
+    const str = decodeStat(stats, 0)
+    const tol = decodeStat(stats, 1)
+    const con = decodeStat(stats, 2)
+    const layout = getEntityLayout(entityItemId)?.slots ?? []
+    const amp = getSlotAmp(layout, idx)
+    const yieldVal = applySlotMultiplier(computeGathererYield(str), amp)
+    const drain = computeGathererDrain(con)
+    const depth = gathererDepthForTier(tol, item.tier ?? 1)
+    return {slotIndex: idx, yield: yieldVal, drain, depth, outputPct: amp}
+}
+
+// Encapsulates the gather handler's lane selection (gathering.cpp:108-112): both error paths.
+export function selectGatherLane(
+    modules: ModuleEntry[],
+    entityItemId: number,
+    lanes: Lane[],
+    stratum: number,
+    explicitSlot?: number
+): number {
+    if (explicitSlot !== undefined) {
+        const laneKey = laneKeyForModule(explicitSlot)
+        const lane = resolveLaneGatherer(modules, entityItemId, laneKey)
+        if (stratum > lane.depth) throw new Error('stratum exceeds gatherer depth')
+        return laneKey
+    }
+    return workerLaneKey(modules, 'gatherer', lanes, stratum)
+}
+
+export function resolveLaneCrafter(
+    modules: ModuleEntry[],
+    entityItemId: number,
+    laneKey: number
+): ResolvedCrafterLane {
+    const idx = laneKey - 1
+    const installed = idx >= 0 && idx < modules.length ? modules[idx].installed : undefined
+    if (!installed) throw new Error('crafter lane has no module')
+    const item = getItem(Number(installed.item_id.value ?? installed.item_id))
+    if (item.moduleType !== 'crafter') throw new Error('lane module is not a crafter')
+    const stats = BigInt(installed.stats.toString())
+    const rea = decodeStat(stats, 0)
+    const fin = decodeStat(stats, 1)
+    const layout = getEntityLayout(entityItemId)?.slots ?? []
+    const amp = getSlotAmp(layout, idx)
+    const speed = applySlotMultiplier(computeCrafterSpeed(rea), amp)
+    const drain = computeCrafterDrain(fin)
+    return {slotIndex: idx, speed, drain, outputPct: amp}
+}
+
+// LANE_MOBILITY or a missing module soft-returns valid=false (never throws); callers check `valid`.
+export function resolveLaneLoader(
+    modules: ModuleEntry[],
+    entityItemId: number,
+    laneKey: number
+): ResolvedLoaderLane {
+    if (laneKey === LANE_MOBILITY) {
+        return {slotIndex: -1, thrust: 0, mass: 0, outputPct: 0, valid: false}
+    }
+    const idx = laneKey - 1
+    const installed = idx >= 0 && idx < modules.length ? modules[idx].installed : undefined
+    if (!installed) {
+        return {slotIndex: idx, thrust: 0, mass: 0, outputPct: 0, valid: false}
+    }
+    const stats = BigInt(installed.stats.toString())
+    const ins = decodeStat(stats, 0)
+    const pla = decodeStat(stats, 1)
+    const layout = getEntityLayout(entityItemId)?.slots ?? []
+    const amp = getSlotAmp(layout, idx)
+    const thrust = applySlotMultiplier(computeLoaderThrust(pla), amp)
+    const mass = computeLoaderMass(ins)
+    return {slotIndex: idx, thrust, mass, outputPct: amp, valid: true}
+}
+
 export function workerLaneKey(
     modules: ModuleEntry[],
     moduleSubtype: ModuleType,
-    lanes: Lane[]
+    lanes: Lane[],
+    stratum?: number
 ): number {
+    if (moduleSubtype === 'gatherer' && stratum !== undefined) {
+        let lowestReaching: number | undefined
+        for (let i = 0; i < modules.length; i++) {
+            const installed = modules[i].installed
+            if (!installed) continue
+            const item = getItem(Number(installed.item_id.value ?? installed.item_id))
+            if (item.moduleType !== 'gatherer') continue
+            const stats = BigInt(installed.stats.toString())
+            const tol = decodeStat(stats, 1)
+            const depth = gathererDepthForTier(tol, item.tier ?? 1)
+            if (depth < stratum) continue
+            const laneKey = laneKeyForModule(i)
+            if (lowestReaching === undefined) lowestReaching = laneKey
+            if (laneIsFree(lanes, laneKey)) return laneKey
+        }
+        if (lowestReaching === undefined) throw new Error('no gatherer reaches this stratum')
+        return lowestReaching
+    }
+
     const occupiedMatchingLaneKeys: number[] = []
 
     for (let slotIndex = 0; slotIndex < modules.length; slotIndex++) {