@shipload/sdk 1.0.0-next.4 → 1.0.0-next.41

package/src/nft/description.ts

@@ -4,6 +4,8 @@ import {
     MODULE_ENGINE,
     MODULE_GATHERER,
     MODULE_GENERATOR,
+    MODULE_BATTERY,
+    MODULE_HAULER,
     MODULE_LOADER,
     MODULE_STORAGE,
     MODULE_WARP,
@@ -13,8 +15,12 @@ import {
     ITEM_CONTAINER_T2_PACKED,
     ITEM_CRAFTER_T1,
     ITEM_ENGINE_T1,
+    ITEM_EXTRACTOR_T1_PACKED,
+    ITEM_FACTORY_T1_PACKED,
     ITEM_GATHERER_T1,
     ITEM_GENERATOR_T1,
+    ITEM_HAULER_T1,
+    ITEM_BATTERY_T1,
     ITEM_LOADER_T1,
     ITEM_SHIP_T1_PACKED,
     ITEM_STORAGE_T1,
@@ -22,6 +28,8 @@ import {
     ITEM_WARP_T1,
 } from '../data/item-ids'
 import {decodeStat} from '../derivation/crafting'
+import {gathererDepthForTier} from '../derivation/capabilities'
+import {getItem} from '../data/catalog'
 
 function idiv(a: number, b: number): number {
     return Math.floor(a / b)
@@ -29,33 +37,68 @@ function idiv(a: number, b: number): number {
 
 export function computeBaseHullmass(stats: bigint): number {
     const density = decodeStat(stats, 1)
-    return 25000 + 75 * density
+    return 100000 - 75 * density
 }
 
 export function computeBaseCapacityShip(stats: bigint): number {
-    const s = decodeStat(stats, 0) + decodeStat(stats, 2) + decodeStat(stats, 3)
-    return Math.floor(1_000_000 * 10 ** (s / 2997))
+    const s = decodeStat(stats, 0) + decodeStat(stats, 2)
+    return Math.floor(5_000_000 * 6 ** (s / 1998))
+}
+
+export function computeBaseCapacityContainer(stats: bigint): number {
+    const s = decodeStat(stats, 0) + decodeStat(stats, 2)
+    return Math.floor(22_000_000 * 6 ** (s / 1998))
+}
+
+export function computeBaseCapacityContainerT2(stats: bigint): number {
+    const s = decodeStat(stats, 0) + decodeStat(stats, 2)
+    return Math.floor(24_000_000 * 6 ** (s / 2947))
 }
 
 export function computeBaseCapacityWarehouse(stats: bigint): number {
-    const s = decodeStat(stats, 0) + decodeStat(stats, 2) + decodeStat(stats, 3)
-    return Math.floor(20_000_000 * 10 ** (s / 2997))
+    const s = decodeStat(stats, 0) + decodeStat(stats, 2)
+    return Math.floor(100_000_000 * 6 ** (s / 1998))
 }
 
 export const computeEngineThrust = (vol: number): number => 400 + idiv(vol * 3, 4)
-export const computeEngineDrain = (thm: number): number => Math.max(30, 50 - idiv(thm, 70))
-export const computeGeneratorCap = (com: number): number => 300 + idiv(com, 6)
-export const computeGeneratorRech = (fin: number): number => 1 + idiv(fin * 3, 1000)
+export const computeEngineDrain = (thm: number): number => 2 * Math.max(30, 50 - idiv(thm, 70))
+export const ENGINE_DRAIN_BASE = 118
+export const ENGINE_DRAIN_REF_THRUST = 775
+export const ENGINE_DRAIN_REF_THM = 500
+
+export const computeTravelDrain = (totalThrust: number, avgThm: number): number => {
+    if (totalThrust <= 0) return 0
+    const num = ENGINE_DRAIN_BASE * ENGINE_DRAIN_REF_THRUST * computeEngineDrain(avgThm)
+    const den = totalThrust * computeEngineDrain(ENGINE_DRAIN_REF_THM)
+    return idiv(num, den)
+}
+export const computeGeneratorCap = (com: number): number => 950 + idiv(com, 2)
+export const computeGeneratorRech = (fin: number): number => 2 * (1 + idiv(fin * 3, 1000))
 export const computeGathererYield = (str: number): number => 200 + str
 export const computeGathererDrain = (con: number): number =>
-    Math.max(250, 1250 - idiv(con * 25, 20))
-export const computeGathererDepth = (tol: number): number => 200 + idiv(tol * 3, 2)
-export const computeGathererSpeed = (ref: number): number => 100 + idiv(ref * 4, 5)
+    2 * Math.max(250, 1250 - idiv(con * 25, 20))
+export const computeGathererDepth = (tol: number, tier: number): number =>
+    gathererDepthForTier(tol, tier)
 export const computeLoaderMass = (ins: number): number => Math.max(200, 2000 - ins * 2)
-export const computeLoaderThrust = (pla: number): number => 1 + idiv(pla, 500)
+export const computeLoaderThrust = (pla: number): number => 1 + idiv(pla * pla, 10000)
 export const computeCrafterSpeed = (rea: number): number => 100 + idiv(rea * 4, 5)
 export const computeCrafterDrain = (fin: number): number => Math.max(5, 30 - idiv(fin, 33))
+export const computeHaulerCapacity = (fin: number): number => Math.max(1, 1 + idiv(fin, 400))
+export const computeHaulerEfficiency = (con: number): number => 2000 + con * 6
+export const computeHaulerDrain = (com: number): number => Math.max(3, 15 - idiv(com, 80))
 export const computeWarpRange = (stat: number): number => 100 + stat * 3
+export const computeCargoBayCapacity = (
+    strength: number,
+    density: number,
+    hardness: number,
+    cohesion: number
+): number => 10_000_000 + idiv((strength + density + hardness + cohesion) * 50_000_000, 3996)
+export const computeBatteryBankCapacity = (
+    volatility: number,
+    thermal: number,
+    plasticity: number,
+    insulation: number
+): number => 2_500 + idiv((volatility + thermal + plasticity + insulation) * 7_500, 3996)
 
 export function entityDisplayName(itemId: number): string {
     switch (itemId) {
@@ -63,6 +106,10 @@ export function entityDisplayName(itemId: number): string {
             return 'Ship'
         case ITEM_WAREHOUSE_T1_PACKED:
             return 'Warehouse'
+        case ITEM_EXTRACTOR_T1_PACKED:
+            return 'Extractor'
+        case ITEM_FACTORY_T1_PACKED:
+            return 'Factory'
         case ITEM_CONTAINER_T1_PACKED:
             return 'Container'
         case ITEM_CONTAINER_T2_PACKED:
@@ -85,9 +132,13 @@ export function moduleDisplayName(itemId: number): string {
         case ITEM_CRAFTER_T1:
             return 'Crafter'
         case ITEM_STORAGE_T1:
-            return 'Storage'
+            return 'Cargo Bay'
+        case ITEM_HAULER_T1:
+            return 'Hauler'
         case ITEM_WARP_T1:
             return 'Warp'
+        case ITEM_BATTERY_T1:
+            return 'Battery Bank'
         default:
             return 'Module'
     }
@@ -119,11 +170,12 @@ export function formatModuleLine(slot: number, itemId: number, stats: bigint): s
         case MODULE_GATHERER: {
             const str = decodeStat(stats, 0)
             const tol = decodeStat(stats, 1)
-            const con = decodeStat(stats, 3)
-            const ref = decodeStat(stats, 4)
+            const con = decodeStat(stats, 2)
+            const tier = getItem(itemId).tier
             out += `  Yield ${computeGathererYield(str)}  Depth ${computeGathererDepth(
-                tol
-            )}  Speed ${computeGathererSpeed(ref)}  Drain ${computeGathererDrain(con)}`
+                tol,
+                tier
+            )}  Drain ${computeGathererDrain(con)}`
             break
         }
         case MODULE_LOADER: {
@@ -134,17 +186,23 @@ export function formatModuleLine(slot: number, itemId: number, stats: bigint): s
         }
         case MODULE_CRAFTER: {
             const rea = decodeStat(stats, 0)
-            const com = decodeStat(stats, 1)
-            out += `  Speed ${computeCrafterSpeed(rea)}  Drain ${computeCrafterDrain(com)}`
+            const con = decodeStat(stats, 1)
+            out += `  Speed ${computeCrafterSpeed(rea)}  Drain ${computeCrafterDrain(con)}`
             break
         }
         case MODULE_STORAGE: {
             const str = decodeStat(stats, 0)
-            const fin = decodeStat(stats, 2)
-            const sat = decodeStat(stats, 3)
-            const sum = str + fin + sat
-            const pct = 10 + idiv(sum * 10, 2997)
-            out += `  +${pct}% capacity`
+            const den = decodeStat(stats, 1)
+            const hrd = decodeStat(stats, 2)
+            const com = decodeStat(stats, 3)
+            out += `  Cargo Capacity ${computeCargoBayCapacity(str, den, hrd, com)}`
+            break
+        }
+        case MODULE_HAULER: {
+            const res = decodeStat(stats, 0)
+            const pla = decodeStat(stats, 1)
+            const ref = decodeStat(stats, 2)
+            out += `  Capacity ${computeHaulerCapacity(res)}  Efficiency ${computeHaulerEfficiency(pla)}  Drain ${computeHaulerDrain(ref)}`
             break
         }
         case MODULE_WARP: {
@@ -152,6 +210,14 @@ export function formatModuleLine(slot: number, itemId: number, stats: bigint): s
             out += `  Range ${computeWarpRange(stat)}`
             break
         }
+        case MODULE_BATTERY: {
+            const vol = decodeStat(stats, 0)
+            const thm = decodeStat(stats, 1)
+            const pla = decodeStat(stats, 2)
+            const ins = decodeStat(stats, 3)
+            out += `  Energy Capacity ${computeBatteryBankCapacity(vol, thm, pla, ins)}`
+            break
+        }
     }
     return out
 }
@@ -168,6 +234,14 @@ export function buildEntityDescription(
         baseCapacity = computeBaseCapacityShip(hullStats)
     } else if (itemId === ITEM_WAREHOUSE_T1_PACKED) {
         baseCapacity = computeBaseCapacityWarehouse(hullStats)
+    } else if (
+        itemId === ITEM_EXTRACTOR_T1_PACKED ||
+        itemId === ITEM_FACTORY_T1_PACKED ||
+        itemId === ITEM_CONTAINER_T1_PACKED
+    ) {
+        baseCapacity = computeBaseCapacityContainer(hullStats)
+    } else if (itemId === ITEM_CONTAINER_T2_PACKED) {
+        baseCapacity = computeBaseCapacityContainerT2(hullStats)
     }
 
     let out = entityDisplayName(itemId)

package/src/nft/index.ts

@@ -1,2 +1,5 @@
 export * from './deserializers'
 export * from './description'
+export * from './atomicdata'
+export * from './atomicassets'
+export * from './buildImmutableData'

package/src/planner/index.ts

@@ -0,0 +1,127 @@
+import type {GathererStats} from '../types/capabilities'
+import type {ServerContract} from '../contracts'
+import {
+    calc_gather_duration,
+    calc_gather_energy,
+    GATHER_MASS_DIVISOR,
+} from '../capabilities/gathering'
+import {projectRemainingAt, type Projectable} from '../scheduling/projection'
+
+export interface LanePlanEntry {
+    slot: number
+    quantity: number
+}
+
+export type PlanTarget = {quantity: number} | 'max'
+
+export interface GatherPlanEntity extends Projectable {
+    gatherer_lanes: ServerContract.Types.gatherer_lane[]
+    loader_lanes: ServerContract.Types.loader_lane[]
+}
+
+// massFactor=1 so plan-time cost is conservative; on-chain recomputes with real mass/richness.
+const PLAN_ITEM_MASS = GATHER_MASS_DIVISOR
+const PLAN_RICHNESS = 1000
+
+// 'max' ceiling; Phase 3 passes a real reserve/capacity cap instead.
+const MAX_PLAN_QTY = 10000
+
+function gatherEnergyCost(
+    lane: ServerContract.Types.gatherer_lane,
+    quantity: number,
+    stratum: number
+): number {
+    const stats = lane as unknown as GathererStats
+    const dur = Number(
+        calc_gather_duration(stats, PLAN_ITEM_MASS, quantity, stratum, PLAN_RICHNESS)
+    )
+    return Number(calc_gather_energy(stats, dur))
+}
+
+function allocateProportional(
+    lanes: {slot: number; weight: number}[],
+    total: number
+): LanePlanEntry[] {
+    if (lanes.length === 0) return []
+    const weightSum = lanes.reduce((s, l) => s + l.weight, 0)
+    if (weightSum === 0) return []
+
+    const entries: LanePlanEntry[] = lanes.map((l) => ({
+        slot: l.slot,
+        quantity: Math.floor((total * l.weight) / weightSum),
+    }))
+
+    let remainder = total - entries.reduce((s, e) => s + e.quantity, 0)
+    for (let i = 0; remainder > 0; i = (i + 1) % entries.length) {
+        entries[i].quantity++
+        remainder--
+    }
+
+    return entries
+}
+
+export function planParallelGather(
+    entity: GatherPlanEntity,
+    target: PlanTarget,
+    stratum: number,
+    now: Date
+): LanePlanEntry[] {
+    const reaching = entity.gatherer_lanes.filter((l) => l.depth.toNumber() >= stratum)
+    if (reaching.length === 0) throw new Error('no gatherer reaches this stratum')
+
+    // Projected energy nets out already-queued/in-flight task costs (contract projected_energy()).
+    const energy = entity.generator ? Number(projectRemainingAt(entity, now).energy) : Infinity
+
+    const requestedQty = target === 'max' ? MAX_PLAN_QTY : (target as {quantity: number}).quantity
+
+    // Ascending by yield so slice(1) sheds the lowest-yield lane first when energy-starved.
+    let activeLanes = reaching.slice().sort((a, b) => a.yield.toNumber() - b.yield.toNumber())
+
+    while (activeLanes.length > 0) {
+        const laneWeights = activeLanes.map((l) => ({
+            slot: l.slot_index.toNumber(),
+            weight: l.yield.toNumber(),
+        }))
+
+        const proposed = allocateProportional(laneWeights, requestedQty)
+
+        const totalEnergyCost = proposed.reduce((sum, entry) => {
+            const lane = activeLanes.find((l) => l.slot_index.toNumber() === entry.slot)!
+            return sum + gatherEnergyCost(lane, entry.quantity, stratum)
+        }, 0)
+
+        if (totalEnergyCost <= energy) {
+            return proposed.filter((e) => e.quantity > 0)
+        }
+
+        if (activeLanes.length === 1) {
+            const lane = activeLanes[0]
+            const energyPerUnit = gatherEnergyCost(lane, 1, stratum)
+            if (energyPerUnit === 0) return proposed.filter((e) => e.quantity > 0)
+            const maxQty = Math.min(requestedQty, Math.floor(energy / energyPerUnit))
+            if (maxQty <= 0) return []
+            return [{slot: lane.slot_index.toNumber(), quantity: maxQty}]
+        }
+
+        activeLanes = activeLanes.slice(1)
+    }
+
+    return []
+}
+
+export function planParallelTransfer(
+    entity: GatherPlanEntity,
+    target: PlanTarget
+): LanePlanEntry[] {
+    const lanes = entity.loader_lanes.filter((l) => l.thrust.toNumber() > 0)
+    if (lanes.length === 0) return []
+
+    const requestedQty = target === 'max' ? MAX_PLAN_QTY : (target as {quantity: number}).quantity
+
+    const laneWeights = lanes.map((l) => ({
+        slot: l.slot_index.toNumber(),
+        weight: l.thrust.toNumber(),
+    }))
+
+    return allocateProportional(laneWeights, requestedQty).filter((e) => e.quantity > 0)
+}

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