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

package/src/derivation/wormhole.ts

@@ -0,0 +1,115 @@
+import type {Checksum256Type} from '@wharfkit/antelope'
+import {hash512} from '../utils/hash'
+
+export const WH = {
+    RSIZE: 75,
+    ZONE: 16384,
+    THRESHOLD: 8192,
+    MIN_REACH: 50000,
+    TRANSIT_SPEED: 500,
+} as const
+
+const HALF = Math.round(Math.log2(WH.ZONE))
+const MASK = WH.ZONE - 1
+
+function roll16(seed: Checksum256Type, str: string): number {
+    const h = hash512(seed, str).array
+    return (h[0] << 8) | h[1]
+}
+function feistelF(seed: Checksum256Type, x: number, round: number, key: string): number {
+    return roll16(seed, `feistel-${key}-${round}-${x}`) & MASK
+}
+export function feistel(seed: Checksum256Type, idx: number, key: string): number {
+    let L = (idx >>> HALF) & MASK
+    let R = idx & MASK
+    for (let r = 0; r < 4; r++) {
+        const nR = L ^ feistelF(seed, R, r, key)
+        L = R
+        R = nR
+    }
+    return (L << HALF) | R
+}
+export function feistelInv(seed: Checksum256Type, idx: number, key: string): number {
+    let L = (idx >>> HALF) & MASK
+    let R = idx & MASK
+    for (let r = 3; r >= 0; r--) {
+        const nL = R ^ feistelF(seed, L, r, key)
+        R = L
+        L = nL
+    }
+    return (L << HALF) | R
+}
+
+type Region = {rx: number; ry: number}
+
+export function regionOf(x: number, y: number): Region {
+    return {rx: Math.floor(x / WH.RSIZE), ry: Math.floor(y / WH.RSIZE)}
+}
+export function partnerRegion(seed: Checksum256Type, R: Region): Region {
+    const qx = Math.floor(R.rx / WH.ZONE)
+    const qy = Math.floor(R.ry / WH.ZONE)
+    const zx = qx * WH.ZONE
+    const zy = qy * WH.ZONE
+    const key = `${qx}:${qy}`
+    const idx = (R.ry - zy) * WH.ZONE + (R.rx - zx)
+    const p = feistelInv(seed, feistel(seed, idx, key) ^ 1, key)
+    return {rx: zx + (p % WH.ZONE), ry: zy + Math.floor(p / WH.ZONE)}
+}
+function regKey(R: Region): string {
+    return `${R.rx}:${R.ry}`
+}
+function pairKey(a: Region, b: Region): string {
+    const ka = regKey(a)
+    const kb = regKey(b)
+    return ka < kb ? `${ka}|${kb}` : `${kb}|${ka}`
+}
+function endpointInRegion(seed: Checksum256Type, R: Region, key: string): {x: number; y: number} {
+    const h = hash512(seed, `wh-endpoint-${key}-${regKey(R)}`).array
+    const ox = ((h[0] << 24) | (h[1] << 16) | (h[2] << 8) | h[3]) >>> 0
+    const oy = ((h[4] << 24) | (h[5] << 16) | (h[6] << 8) | h[7]) >>> 0
+    return {x: R.rx * WH.RSIZE + (ox % WH.RSIZE), y: R.ry * WH.RSIZE + (oy % WH.RSIZE)}
+}
+function dist(a: {x: number; y: number}, b: {x: number; y: number}): number {
+    return Math.sqrt((a.x - b.x) ** 2 + (a.y - b.y) ** 2)
+}
+function wormholeOfRegion(
+    seed: Checksum256Type,
+    R: Region
+): {A: {x: number; y: number}; B: {x: number; y: number}} | null {
+    const P = partnerRegion(seed, R)
+    if (P.rx === R.rx && P.ry === R.ry) return null
+    const key = pairKey(R, P)
+    if (roll16(seed, `wh-exists-${key}`) >= WH.THRESHOLD) return null
+    const A = endpointInRegion(seed, R, key)
+    const B = endpointInRegion(seed, P, key)
+    if (dist(A, B) < WH.MIN_REACH) return null
+    return {A, B}
+}
+export function wormholeAtRegionEndpoint(
+    seed: Checksum256Type,
+    rx: number,
+    ry: number
+): {from: {x: number; y: number}; to: {x: number; y: number}} | null {
+    const w = wormholeOfRegion(seed, {rx, ry})
+    if (!w) return null
+    return {from: w.A, to: w.B}
+}
+export function wormholeAt(
+    seed: Checksum256Type,
+    x: number,
+    y: number
+): {x: number; y: number} | null {
+    const w = wormholeOfRegion(seed, regionOf(x, y))
+    if (!w || w.A.x !== x || w.A.y !== y) return null
+    return w.B
+}
+export function isValidWormholePair(
+    seed: Checksum256Type,
+    ax: number,
+    ay: number,
+    bx: number,
+    by: number
+): boolean {
+    const to = wormholeAt(seed, ax, ay)
+    return to !== null && to.x === bx && to.y === by
+}

package/src/entities/makers.ts

@@ -140,13 +140,40 @@ export function makeEntity(packedItemId: number, state: EntityStateInput): Entit
 
         if (caps.engines) info.engines = caps.engines
         if (caps.generator) info.generator = caps.generator
-        if (caps.gatherer) info.gatherer = caps.gatherer
-        if (caps.loaders) info.loaders = caps.loaders
-        if (caps.crafter) info.crafter = caps.crafter
         if (caps.hauler) info.hauler = caps.hauler
         if (caps.warp) info.warp = caps.warp
+
+        info.gatherer_lanes = (caps.gathererLanes ?? []).map((l) =>
+            ServerContract.Types.gatherer_lane.from({
+                slot_index: l.slotIndex,
+                yield: l.yield,
+                drain: l.drain,
+                depth: l.depth,
+                output_pct: l.outputPct,
+            })
+        )
+        info.crafter_lanes = (caps.crafterLanes ?? []).map((l) =>
+            ServerContract.Types.crafter_lane.from({
+                slot_index: l.slotIndex,
+                speed: l.speed,
+                drain: l.drain,
+                output_pct: l.outputPct,
+            })
+        )
+        info.loader_lanes = (caps.loaderLanes ?? []).map((l) =>
+            ServerContract.Types.loader_lane.from({
+                slot_index: l.slotIndex,
+                mass: l.mass,
+                thrust: l.thrust,
+                output_pct: l.outputPct,
+            })
+        )
     }
 
+    if (!info.gatherer_lanes) info.gatherer_lanes = []
+    if (!info.crafter_lanes) info.crafter_lanes = []
+    if (!info.loader_lanes) info.loader_lanes = []
+
     const entityInfo = ServerContract.Types.entity_info.from(info)
     return new Entity(entityInfo)
 }

package/src/errors.ts

@@ -56,6 +56,8 @@ export const GROUP_HAUL_CAPACITY_EXCEEDED =
     'Group travel requires sufficient hauler capacity for all non-self-propelled entities.'
 export const CANCEL_CONTAINS_GROUPED_TASK =
     'Cannot cancel range containing grouped task - cancel non-grouped tasks first.'
+export const WOULD_STRAND = 'Cancelling this would leave a later task without the cargo it needs.'
+export const WOULD_OVERFILL = 'Cancelling this would overfill the other entity with returned cargo.'
 export const WARP_NO_CAPABILITY = 'Entity does not have warp capability.'
 export const WARP_HAS_SCHEDULE = 'Entity must be idle to warp.'
 export const WARP_HAS_CARGO = 'Entity must have no cargo to warp.'

package/src/index-module.ts

@@ -26,13 +26,11 @@ export type {InstalledModule} from './entities/slot-multiplier'
 
 export type movement_stats = ServerContract.Types.movement_stats
 export type energy_stats = ServerContract.Types.energy_stats
-export type loader_stats = ServerContract.Types.loader_stats
 export type schedule = ServerContract.Types.schedule
 export type lane = ServerContract.Types.lane
 export type task = ServerContract.Types.task
 export type cargo_item = ServerContract.Types.cargo_item
 export type entity_row = ServerContract.Types.entity_row
-export type gatherer_stats = ServerContract.Types.gatherer_stats
 
 export type location_static = ServerContract.Types.location_static
 export type location_derived = ServerContract.Types.location_derived
@@ -87,6 +85,7 @@ export type {EpochInfo} from './scheduling/epoch'
 export {
     getSystemName,
     hasSystem,
+    getLocationKind,
     getLocationType,
     getLocationTypeName,
     isGatherableLocation,
@@ -157,6 +156,7 @@ export {
     calc_flighttime,
     calc_loader_acceleration,
     calc_loader_flighttime,
+    calc_onesided_duration,
     calc_orbital_altitude,
     calc_rechargetime,
     calc_ship_acceleration,
@@ -164,6 +164,7 @@ export {
     calc_ship_mass,
     calc_ship_rechargetime,
     calc_transfer_duration,
+    calc_transit_duration,
     calculateFlightTime,
     calculateLoadTimeBreakdown,
     calculateRefuelingTime,
@@ -202,8 +203,17 @@ export {
     candidateLaneCompletesAt,
     laneKeyForModule,
     rawScheduleEnd,
+    resolveLaneGatherer,
+    resolveLaneCrafter,
+    resolveLaneLoader,
+    selectGatherLane,
     workerLaneKey,
 } from './scheduling/lanes'
+export type {
+    ResolvedGathererLane,
+    ResolvedCrafterLane,
+    ResolvedLoaderLane,
+} from './scheduling/lanes'
 export {ScheduleAccessor, createScheduleAccessor} from './scheduling/accessor'
 export {InventoryAccessor, createInventoryAccessor} from './entities/inventory-accessor'
 export type {HasCargo} from './entities/inventory-accessor'
@@ -232,6 +242,15 @@ export type {TaskCargoChange, TaskCargoDirection} from './scheduling/task-cargo'
 export {composeIdleResolve} from './scheduling/idle-resolve'
 export type {CounterpartLookup, IdleResolveTarget} from './scheduling/idle-resolve'
 
+export {cancelEligibility, CancelBlockReason} from './scheduling/cancel'
+export type {
+    CancelPlan,
+    CancelEffects,
+    CancelRefund,
+    CancelReleasedHold,
+    CancelEligibilityInput,
+} from './scheduling/cancel'
+
 export {
     projectedCargoAvailableAt,
     availableForItem,
@@ -356,6 +375,19 @@ export {
 } from './derivation/capabilities'
 export type {GathererDepthParams, ComputedCapabilities} from './derivation/capabilities'
 
+export {
+    WH,
+    feistel,
+    feistelInv,
+    regionOf,
+    partnerRegion,
+    wormholeAt,
+    wormholeAtRegionEndpoint,
+    isValidWormholePair,
+} from './derivation/wormhole'
+
+export {rollupGatherer, rollupCrafter, rollupLoaders} from './derivation/rollups'
+
 export {resolveItem} from './resolution/resolve-item'
 export type {
     ResolvedItem,
@@ -460,8 +492,12 @@ export {
 } from './data/tiers'
 
 export {formatMass, formatMassDelta, formatMassScaled, formatLocation} from './format'
+export * from './coordinates'
 
 export {displayName, baseName, describeItem} from './resolution/display-name'
 export type {DescribeOptions} from './resolution/display-name'
 
 export * from './subscriptions'
+
+export {planParallelGather, planParallelTransfer} from './planner'
+export type {LanePlanEntry, PlanTarget, GatherPlanEntity} from './planner'

package/src/managers/actions.ts

@@ -3,8 +3,10 @@ import {
     Checksum256,
     type Checksum256Type,
     Int64,
+    type Int64Type,
     Name,
     type NameType,
+    Transaction,
     UInt8,
     type UInt8Type,
     UInt16,
@@ -37,13 +39,17 @@ export class ActionsManager extends BaseManager {
         })
     }
 
-    grouptravel(entities: EntityRefInput[], destination: CoordinatesType, recharge = true): Action {
-        const entityRefs = entities.map((e) =>
+    private entityRefs(entities: EntityRefInput[]) {
+        return entities.map((e) =>
             ServerContract.Types.entity_ref.from({
                 entity_type: e.entityType,
                 entity_id: UInt64.from(e.entityId),
             })
         )
+    }
+
+    grouptravel(entities: EntityRefInput[], destination: CoordinatesType, recharge = true): Action {
+        const entityRefs = this.entityRefs(entities)
         const x = Int64.from(destination.x)
         const y = Int64.from(destination.y)
 
@@ -55,6 +61,44 @@ export class ActionsManager extends BaseManager {
         })
     }
 
+    transit(shipId: UInt64Type, entrance: CoordinatesType, exit: CoordinatesType): Action {
+        return this.server.action('transit', {
+            id: UInt64.from(shipId),
+            ax: Int64.from(entrance.x),
+            ay: Int64.from(entrance.y),
+            bx: Int64.from(exit.x),
+            by: Int64.from(exit.y),
+        })
+    }
+
+    grouptransit(
+        entities: EntityRefInput[],
+        entrance: CoordinatesType,
+        exit: CoordinatesType
+    ): Action {
+        const entityRefs = this.entityRefs(entities)
+        return this.server.action('grouptransit', {
+            entities: entityRefs,
+            ax: Int64.from(entrance.x),
+            ay: Int64.from(entrance.y),
+            bx: Int64.from(exit.x),
+            by: Int64.from(exit.y),
+        })
+    }
+
+    getwormhole(x: Int64Type, y: Int64Type): Action {
+        return this.server.action('getwormhole', {x: Int64.from(x), y: Int64.from(y)})
+    }
+
+    getdistance(origin: CoordinatesType, destination: CoordinatesType): Action {
+        return this.server.action('getdistance', {
+            ax: Int64.from(origin.x),
+            ay: Int64.from(origin.y),
+            bx: Int64.from(destination.x),
+            by: Int64.from(destination.y),
+        })
+    }
+
     resolve(entityId: UInt64Type, count?: UInt64Type): Action {
         const params: ServerContract.ActionParams.resolve = {
             id: UInt64.from(entityId),
@@ -139,13 +183,39 @@ export class ActionsManager extends BaseManager {
         sourceId: UInt64Type,
         destinationId: UInt64Type,
         stratum: UInt16Type,
-        quantity: UInt32Type
+        quantity: UInt32Type,
+        slot?: UInt8Type
     ): Action {
-        return this.server.action('gather', {
+        const params: ServerContract.ActionParams.gather = {
             source_id: UInt64.from(sourceId),
             destination_id: UInt64.from(destinationId),
             stratum: UInt16.from(stratum),
             quantity: UInt32.from(quantity),
+        }
+        if (slot !== undefined) {
+            params.slot = UInt8.from(slot)
+        }
+        return this.server.action('gather', params)
+    }
+
+    // Packs N gather actions into one Transaction; the wallet/session fills in TAPoS at sign time.
+    bundleGather(
+        gathers: {
+            sourceId: UInt64Type
+            destinationId: UInt64Type
+            stratum: UInt16Type
+            quantity: UInt32Type
+            slot?: UInt8Type
+        }[]
+    ): Transaction {
+        const actions = gathers.map(({sourceId, destinationId, stratum, quantity, slot}) =>
+            this.gather(sourceId, destinationId, stratum, quantity, slot)
+        )
+        return Transaction.from({
+            expiration: 0,
+            ref_block_num: 0,
+            ref_block_prefix: 0,
+            actions,
         })
     }
 
@@ -165,7 +235,8 @@ export class ActionsManager extends BaseManager {
         recipeId: number,
         quantity: number,
         inputs: ServerContract.ActionParams.Type.cargo_item[],
-        target?: UInt64Type
+        target?: UInt64Type,
+        slot?: UInt8Type
     ): Action {
         const params: ServerContract.ActionParams.craft = {
             id: UInt64.from(entityId),
@@ -176,6 +247,9 @@ export class ActionsManager extends BaseManager {
         if (target !== undefined) {
             params.target = UInt64.from(target)
         }
+        if (slot !== undefined) {
+            params.slot = UInt8.from(slot)
+        }
         return this.server.action('craft', params)
     }
 

package/src/managers/construction.ts

@@ -67,8 +67,9 @@ export class ConstructionManager extends BaseManager {
             if (!entity.owner.equals(target.ownerName)) continue
             if (entity.id.equals(target.entityId)) continue
             if (!coordsEqual(entity.coordinates, target.coordinates)) continue
-            const speed = entity.crafter?.speed.toNumber()
-            if (speed === undefined) continue
+            const crafterLanes = entity.crafter_lanes ?? []
+            if (crafterLanes.length === 0) continue
+            const speed = crafterLanes.reduce((s, l) => s + Number(l.speed), 0)
             out.push({
                 entityId: entity.id,
                 entityType: entity.type,
@@ -345,8 +346,9 @@ function partitionSources(
         const reserved = reservedByItemFor(entity)
         const relevant = matchRelevantCargo(entity, target, cargo, reserved)
         if (relevant.length === 0) continue
-        const loaderCount = entity.loaders?.quantity.toNumber() ?? 0
-        const loaderTotalMass = entity.loaders?.mass.toNumber() ?? 0
+        const loaderLanes = entity.loader_lanes ?? []
+        const loaderCount = loaderLanes.length
+        const loaderTotalMass = loaderLanes.reduce((s, l) => s + Number(l.mass), 0)
         const ref: SourceEntityRef = {
             entityId: entity.id,
             name: entity.id.toString(),

package/src/managers/context.ts

@@ -6,6 +6,7 @@ import {GameState} from '../entities/gamestate'
 import {EntitiesManager} from './entities'
 import {PlayersManager} from './players'
 import {LocationsManager} from './locations'
+import {CoordinatesManager} from './coordinates'
 import {EpochsManager} from './epochs'
 import {ActionsManager} from './actions'
 import {NftManager} from './nft'
@@ -15,6 +16,7 @@ export class GameContext {
     private _entities?: EntitiesManager
     private _players?: PlayersManager
     private _locations?: LocationsManager
+    private _coordinates?: CoordinatesManager
     private _epochs?: EpochsManager
     private _actions?: ActionsManager
     private _nft?: NftManager
@@ -52,6 +54,13 @@ export class GameContext {
         return this._locations
     }
 
+    get coordinates(): CoordinatesManager {
+        if (!this._coordinates) {
+            this._coordinates = new CoordinatesManager(this)
+        }
+        return this._coordinates
+    }
+
     get epochs(): EpochsManager {
         if (!this._epochs) {
             this._epochs = new EpochsManager(this)

package/src/managers/coordinates.ts

@@ -0,0 +1,14 @@
+import {BaseManager} from './base'
+import {type CoordinateAddress, decodeAddress, encodeAddressMemo} from '../coordinates'
+
+export class CoordinatesManager extends BaseManager {
+    async encode(x: number, y: number): Promise<CoordinateAddress> {
+        const game = await this.getGame()
+        return encodeAddressMemo(game.config.seed, x, y)
+    }
+
+    async decode(addr: CoordinateAddress): Promise<{x: number; y: number}> {
+        const game = await this.getGame()
+        return decodeAddress(game.config.seed, addr)
+    }
+}

package/src/managers/plot.ts

@@ -5,6 +5,7 @@ import {computeInputMass} from '../derivation/crafting'
 import {calc_craft_duration} from '../capabilities/crafting'
 import {TaskType} from '../types'
 import {BaseManager} from './base'
+import type {CrafterStats} from '../types/capabilities'
 import type {ServerContract} from '../contracts'
 import type {BuildableTarget, ScheduledBuild} from './construction-types'
 
@@ -112,10 +113,7 @@ export class PlotManager extends BaseManager {
         return this.progress(plot, cargo).isComplete
     }
 
-    timeToComplete(
-        plot: ServerContract.Types.entity_info,
-        crafter: ServerContract.Types.crafter_stats
-    ): number {
+    timeToComplete(plot: ServerContract.Types.entity_info, crafter: CrafterStats): number {
         const capacity = Number(plot.capacity?.toString() ?? '0')
         const speed = Number(crafter.speed.toString())
         if (speed === 0) return 0

package/src/nft/description.ts

@@ -15,6 +15,7 @@ import {
     ITEM_CRAFTER_T1,
     ITEM_ENGINE_T1,
     ITEM_EXTRACTOR_T1_PACKED,
+    ITEM_FACTORY_T1_PACKED,
     ITEM_GATHERER_T1,
     ITEM_GENERATOR_T1,
     ITEM_HAULER_T1,
@@ -38,13 +39,23 @@ export function computeBaseHullmass(stats: bigint): number {
 }
 
 export function computeBaseCapacityShip(stats: bigint): number {
-    const s = decodeStat(stats, 0) + decodeStat(stats, 2) + decodeStat(stats, 3)
-    return Math.floor(5_000_000 * 6 ** (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(100_000_000 * 6 ** (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)
@@ -73,6 +84,8 @@ export function entityDisplayName(itemId: number): string {
             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:
@@ -188,8 +201,14 @@ export function buildEntityDescription(
         baseCapacity = computeBaseCapacityShip(hullStats)
     } else if (itemId === ITEM_WAREHOUSE_T1_PACKED) {
         baseCapacity = computeBaseCapacityWarehouse(hullStats)
-    } else if (itemId === ITEM_EXTRACTOR_T1_PACKED) {
-        baseCapacity = computeBaseCapacityShip(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/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)
+}