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

package/src/planner/planner.test.ts

@@ -0,0 +1,319 @@
+import {UInt8, UInt16, UInt32, UInt64} from '@wharfkit/antelope'
+import {expect, test, describe} from 'bun:test'
+import type {GathererStats} from '../types/capabilities'
+import {ServerContract} from '../contracts'
+import {calc_gather_duration} from '../capabilities/gathering'
+import {planParallelGather, planParallelTransfer, type GatherPlanEntity} from './index'
+
+function gathererLane(
+    slotIndex: number,
+    yieldVal: number,
+    drain: number,
+    depth: number
+): ServerContract.Types.gatherer_lane {
+    return ServerContract.Types.gatherer_lane.from({
+        slot_index: UInt8.from(slotIndex),
+        yield: UInt16.from(yieldVal),
+        drain: UInt32.from(drain),
+        depth: UInt16.from(depth),
+        output_pct: UInt16.from(100),
+    })
+}
+
+function loaderLane(
+    slotIndex: number,
+    mass: number,
+    thrust: number
+): ServerContract.Types.loader_lane {
+    return ServerContract.Types.loader_lane.from({
+        slot_index: UInt8.from(slotIndex),
+        mass: UInt32.from(mass),
+        thrust: UInt16.from(thrust),
+        output_pct: UInt16.from(100),
+    })
+}
+
+function energyStats(capacity: number, recharge: number): ServerContract.Types.energy_stats {
+    return ServerContract.Types.energy_stats.from({
+        capacity: UInt32.from(capacity),
+        recharge: UInt32.from(recharge),
+    })
+}
+
+interface EntityOverrides {
+    gatherer_lanes?: ServerContract.Types.gatherer_lane[]
+    loader_lanes?: ServerContract.Types.loader_lane[]
+    generator?: ServerContract.Types.energy_stats
+    energy?: number
+    lanes?: ServerContract.Types.lane[]
+}
+
+function entity(overrides: EntityOverrides = {}): GatherPlanEntity {
+    return {
+        gatherer_lanes: overrides.gatherer_lanes ?? [],
+        loader_lanes: overrides.loader_lanes ?? [],
+        generator: overrides.generator,
+        energy: overrides.energy !== undefined ? UInt16.from(overrides.energy) : undefined,
+        lanes: overrides.lanes ?? [],
+        coordinates: ServerContract.Types.coordinates.from({x: 0, y: 0}),
+        cargo: [],
+        cargomass: UInt32.from(0),
+    }
+}
+
+const NOW = new Date('2026-06-21T00:00:00.000Z')
+
+describe('planParallelGather', () => {
+    test('sanity: single-gatherer qty 20 = ~35s matches calc_gather_duration', () => {
+        const gatherer: GathererStats = {
+            yield: UInt16.from(57),
+            drain: UInt32.from(500),
+            depth: UInt16.from(5000),
+        }
+        const dur = calc_gather_duration(gatherer, 228, 20, 0, 1000)
+        expect(Number(dur)).toBeCloseTo(35, 0)
+    })
+
+    test('two gatherers: quantities proportional to yield, durations within 1s', () => {
+        const YIELD1 = 200
+        const YIELD2 = 400
+        const DEPTH = 5000
+        const DRAIN = 500
+        const QUANTITY = 60
+        const STRATUM = 0
+
+        const e = entity({
+            gatherer_lanes: [
+                gathererLane(0, YIELD1, DRAIN, DEPTH),
+                gathererLane(1, YIELD2, DRAIN, DEPTH),
+            ],
+            generator: energyStats(10000, 100),
+            energy: 10000,
+        })
+
+        const plan = planParallelGather(e, {quantity: QUANTITY}, STRATUM, NOW)
+
+        expect(plan).toHaveLength(2)
+        expect(plan.reduce((s, p) => s + p.quantity, 0)).toBe(QUANTITY)
+
+        const q1 = plan.find((p) => p.slot === 0)!.quantity
+        const q2 = plan.find((p) => p.slot === 1)!.quantity
+        expect(q1 + q2).toBe(QUANTITY)
+        expect(q2 / q1).toBeCloseTo(YIELD2 / YIELD1, 0)
+
+        const ITEM_MASS = 228
+        const RICHNESS = 1000
+        const g1: GathererStats = {
+            yield: UInt16.from(YIELD1),
+            drain: UInt32.from(DRAIN),
+            depth: UInt16.from(DEPTH),
+        }
+        const g2: GathererStats = {
+            yield: UInt16.from(YIELD2),
+            drain: UInt32.from(DRAIN),
+            depth: UInt16.from(DEPTH),
+        }
+        const dur1 = Number(calc_gather_duration(g1, ITEM_MASS, q1, STRATUM, RICHNESS))
+        const dur2 = Number(calc_gather_duration(g2, ITEM_MASS, q2, STRATUM, RICHNESS))
+        expect(Math.abs(dur1 - dur2)).toBeLessThan(1)
+    })
+
+    test("'max' target: uses all reaching lanes, each slot gets >= 1 unit", () => {
+        const e = entity({
+            gatherer_lanes: [gathererLane(0, 200, 500, 5000), gathererLane(1, 300, 500, 5000)],
+            generator: energyStats(10000, 100),
+            energy: 10000,
+        })
+
+        const plan = planParallelGather(e, 'max', 0, NOW)
+
+        expect(plan.length).toBeGreaterThan(0)
+        for (const entry of plan) {
+            expect(entry.quantity).toBeGreaterThanOrEqual(1)
+        }
+    })
+
+    test('energy-starved: drops the lowest-yield lane(s) until the pool sustains the plan', () => {
+        // Full-Q energy: 3 lanes=>144, 2 lanes(drop yield=50)=>120; pool 130 fits 2 but not 3.
+        const e = entity({
+            gatherer_lanes: [
+                gathererLane(0, 50, 10000, 5000),
+                gathererLane(1, 100, 10000, 5000),
+                gathererLane(2, 100, 10000, 5000),
+            ],
+            generator: energyStats(10000, 1),
+            energy: 130,
+        })
+
+        const plan = planParallelGather(e, {quantity: 120}, 0, NOW)
+
+        // Lowest-yield lane (slot 0) dropped; the two yield-100 lanes survive.
+        expect(plan).toHaveLength(2)
+        expect(plan.find((p) => p.slot === 0)).toBeUndefined()
+        expect(plan.reduce((s, p) => s + p.quantity, 0)).toBe(120)
+    })
+
+    test('energy-starved: single lane caps quantity to the sustainable max', () => {
+        // energyPerUnit=1, full Q=120 costs 120 > pool 50, so quantity caps at 50.
+        const e = entity({
+            gatherer_lanes: [gathererLane(0, 100, 10000, 5000)],
+            generator: energyStats(10000, 1),
+            energy: 50,
+        })
+
+        const plan = planParallelGather(e, {quantity: 120}, 0, NOW)
+
+        expect(plan).toHaveLength(1)
+        expect(plan[0].slot).toBe(0)
+        expect(plan[0].quantity).toBe(50)
+    })
+
+    test('energy-starved: projected energy nets out a queued gather task', () => {
+        // A queued task costing 9970 leaves 30 projected energy => quantity caps at 30.
+        const queued = ServerContract.Types.lane.from({
+            lane_key: UInt8.from(0),
+            schedule: {
+                started: NOW.toISOString().slice(0, -1),
+                tasks: [
+                    ServerContract.Types.task.from({
+                        type: UInt8.from(5),
+                        duration: UInt32.from(100),
+                        cancelable: 0,
+                        cargo: [],
+                        entitytarget: {entity_type: 'ship', entity_id: UInt64.from(1)},
+                        energy_cost: UInt32.from(9970),
+                    }),
+                ],
+            },
+        })
+
+        const e = entity({
+            gatherer_lanes: [gathererLane(0, 100, 10000, 5000)],
+            generator: energyStats(10000, 1),
+            energy: 10000,
+            lanes: [queued],
+        })
+
+        const plan = planParallelGather(e, {quantity: 120}, 0, NOW)
+
+        expect(plan).toHaveLength(1)
+        expect(plan[0].quantity).toBe(30)
+    })
+
+    test('stratum filter: shallow lane excluded, only deep lane used', () => {
+        const e = entity({
+            gatherer_lanes: [gathererLane(0, 200, 500, 500), gathererLane(1, 300, 500, 5000)],
+            generator: energyStats(10000, 100),
+            energy: 10000,
+        })
+
+        const plan = planParallelGather(e, {quantity: 10}, 2000, NOW)
+
+        expect(plan).toHaveLength(1)
+        expect(plan[0].slot).toBe(1)
+    })
+
+    test('no reaching gatherers throws', () => {
+        const e = entity({
+            gatherer_lanes: [gathererLane(0, 200, 500, 100)],
+            generator: energyStats(10000, 100),
+            energy: 10000,
+        })
+
+        expect(() => planParallelGather(e, {quantity: 10}, 2000, NOW)).toThrow(
+            'no gatherer reaches this stratum'
+        )
+    })
+
+    test('two identical gatherers: per-lane quantity halved, durations equal and within 1s', () => {
+        const YIELD = 200
+        const DEPTH = 5000
+        const DRAIN = 500
+        const QUANTITY = 60
+        const STRATUM = 0
+
+        const eSingle = entity({
+            gatherer_lanes: [gathererLane(0, YIELD, DRAIN, DEPTH)],
+            generator: energyStats(10000, 100),
+            energy: 10000,
+        })
+        const eDouble = entity({
+            gatherer_lanes: [
+                gathererLane(0, YIELD, DRAIN, DEPTH),
+                gathererLane(1, YIELD, DRAIN, DEPTH),
+            ],
+            generator: energyStats(10000, 100),
+            energy: 10000,
+        })
+
+        const planSingle = planParallelGather(eSingle, {quantity: QUANTITY}, STRATUM, NOW)
+        const planDouble = planParallelGather(eDouble, {quantity: QUANTITY}, STRATUM, NOW)
+
+        expect(planSingle).toHaveLength(1)
+        expect(planDouble).toHaveLength(2)
+
+        const singleQ = planSingle[0].quantity
+        const doubleQ1 = planDouble[0].quantity
+        const doubleQ2 = planDouble[1].quantity
+        expect(doubleQ1 + doubleQ2).toBe(QUANTITY)
+
+        const ITEM_MASS = 228
+        const RICHNESS = 1000
+        const g: GathererStats = {
+            yield: UInt16.from(YIELD),
+            drain: UInt32.from(DRAIN),
+            depth: UInt16.from(DEPTH),
+        }
+        const durSingle = Number(calc_gather_duration(g, ITEM_MASS, singleQ, STRATUM, RICHNESS))
+        const durDouble1 = Number(calc_gather_duration(g, ITEM_MASS, doubleQ1, STRATUM, RICHNESS))
+        const durDouble2 = Number(calc_gather_duration(g, ITEM_MASS, doubleQ2, STRATUM, RICHNESS))
+
+        expect(durDouble1).toBeCloseTo(durSingle / 2, 0)
+        expect(durDouble2).toBeCloseTo(durSingle / 2, 0)
+        expect(Math.abs(durDouble1 - durDouble2)).toBeLessThan(1)
+    })
+})
+
+describe('planParallelTransfer', () => {
+    test('two loader lanes: quantities proportional to thrust, sums to target', () => {
+        const THRUST1 = 100
+        const THRUST2 = 200
+        const QUANTITY = 90
+
+        const e = entity({
+            loader_lanes: [loaderLane(0, 500, THRUST1), loaderLane(1, 500, THRUST2)],
+        })
+
+        const plan = planParallelTransfer(e, {quantity: QUANTITY})
+
+        expect(plan).toHaveLength(2)
+        expect(plan.reduce((s, p) => s + p.quantity, 0)).toBe(QUANTITY)
+
+        const q1 = plan.find((p) => p.slot === 0)!.quantity
+        const q2 = plan.find((p) => p.slot === 1)!.quantity
+        expect(q2 / q1).toBeCloseTo(THRUST2 / THRUST1, 0)
+    })
+
+    test('no loader lanes: returns empty plan', () => {
+        const plan = planParallelTransfer(entity({loader_lanes: []}), {quantity: 10})
+        expect(plan).toHaveLength(0)
+    })
+
+    test('thrust=0 loader lane (no-loader/mobility case): returns empty plan', () => {
+        const plan = planParallelTransfer(entity({loader_lanes: [loaderLane(0, 500, 0)]}), {
+            quantity: 10,
+        })
+        expect(plan).toHaveLength(0)
+    })
+
+    test("'max' target: each loader lane gets >= 1 unit", () => {
+        const e = entity({
+            loader_lanes: [loaderLane(0, 500, 100), loaderLane(1, 500, 200)],
+        })
+        const plan = planParallelTransfer(e, 'max')
+        expect(plan.length).toBeGreaterThan(0)
+        for (const entry of plan) {
+            expect(entry.quantity).toBeGreaterThanOrEqual(1)
+        }
+    })
+})

package/src/resolution/resolve-item.ts

@@ -287,7 +287,10 @@ function resolveEntity(
     let moduleSlots: ResolvedModuleSlot[] | undefined
 
     if (stats !== undefined) {
-        const decoded = decodeCraftedItemStats(id, toBigStats(stats))
+        const bigStats = toBigStats(stats)
+        const decoded = decodeCraftedItemStats(id, bigStats)
+        if (decoded.strength === undefined) decoded.strength = decodeStat(bigStats, 0)
+        if (decoded.hardness === undefined) decoded.hardness = decodeStat(bigStats, 2)
         const hullCaps = hullCapsForEntity(id, decoded)
         attributes = [
             {

package/src/scheduling/cancel.test.ts

@@ -26,6 +26,9 @@ function entity(tasks: ReturnType<typeof task>[], startedISO = T0) {
         cargo: [],
         modules: [],
         lanes: [{lane_key: 0, schedule: {started: startedISO, tasks}}],
+        gatherer_lanes: [],
+        crafter_lanes: [],
+        loader_lanes: [],
         holds: [],
     })
 }
@@ -147,6 +150,9 @@ describe('cancelEligibility — effects', () => {
             cargo: [],
             modules: [],
             lanes: [{lane_key: 0, schedule: {started: T0, tasks: [lt]}}],
+            gatherer_lanes: [],
+            crafter_lanes: [],
+            loader_lanes: [],
             holds: [
                 {
                     id: 1,
@@ -176,6 +182,9 @@ describe('cancelEligibility — effects', () => {
             cargo: [],
             modules: [],
             lanes: [{lane_key: 0, schedule: {started: T0, tasks: [lt]}}],
+            gatherer_lanes: [],
+            crafter_lanes: [],
+            loader_lanes: [],
             holds: [
                 {
                     id: 1,
@@ -205,6 +214,9 @@ describe('cancelEligibility — effects', () => {
             cargo: [],
             modules: [],
             lanes: [{lane_key: 0, schedule: {started: T0, tasks: [lt]}}],
+            gatherer_lanes: [],
+            crafter_lanes: [],
+            loader_lanes: [],
             holds: [],
         })
         const plan = cancelEligibility(e, 0, 0, {now: upcoming})
@@ -251,6 +263,9 @@ describe('cancelEligibility — feasibility', () => {
                     schedule: {started: '2026-06-19T00:00:00', tasks: [consumer]},
                 },
             ],
+            gatherer_lanes: [],
+            crafter_lanes: [],
+            loader_lanes: [],
             holds: [],
         })
         expect(cancelEligibility(e, 1, 0, {now: upcoming}).blockedReason).toBe(
@@ -285,6 +300,9 @@ describe('cancelEligibility — feasibility', () => {
                 {lane_key: 1, schedule: {started: '2026-06-19T00:00:00', tasks: [producer]}},
                 {lane_key: 2, schedule: {started: '2026-06-19T00:00:00', tasks: [independent]}},
             ],
+            gatherer_lanes: [],
+            crafter_lanes: [],
+            loader_lanes: [],
             holds: [],
         })
         expect(cancelEligibility(e, 2, 0, {now: upcoming}).ok).toBe(true)
@@ -318,6 +336,9 @@ describe('cancelEligibility — feasibility', () => {
                 {lane_key: 1, schedule: {started: '2026-06-19T00:00:00', tasks: [producer]}},
                 {lane_key: 2, schedule: {started: '2026-06-19T00:00:00', tasks: [consumer]}},
             ],
+            gatherer_lanes: [],
+            crafter_lanes: [],
+            loader_lanes: [],
             holds: [],
         })
         expect(cancelEligibility(e, 1, 0, {now: upcoming}).blockedReason).toBe(

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'
+    )
+})