@shipload/sdk 1.0.0-next.56 → 1.0.0-next.57

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@shipload/sdk",
     "description": "SDKs for Shipload",
-    "version": "1.0.0-next.56",
+    "version": "1.0.0-next.57",
     "homepage": "https://github.com/shipload/toolkit/tree/master/packages/sdk",
     "repository": {
         "type": "git",

package/src/capabilities/craftable.test.ts

@@ -0,0 +1,82 @@
+import {describe, expect, test} from 'bun:test'
+import {ServerContract} from '../contracts'
+import {UInt16, UInt32, UInt64} from '@wharfkit/antelope'
+import {
+    ITEM_ENGINE_T1,
+    ITEM_GENERATOR_T1,
+    ITEM_CRAFTER_T1,
+    ITEM_PLASMA_CELL,
+    ITEM_SHIP_T1_PACKED,
+} from '../data/item-ids'
+import {getRecipe} from '../data/recipes-runtime'
+import {encodeStats} from '../derivation/crafting'
+import {rollupCrafter} from '../derivation/rollups'
+import {makeEntity} from '../entities/makers'
+import type {IncomingSource} from '../scheduling/availability'
+import {maxCraftable} from './craftable'
+
+const NOW = new Date('2026-06-11T17:06:40.000Z')
+
+function ship(cargo: ServerContract.Types.cargo_item[] = []) {
+    return makeEntity(ITEM_SHIP_T1_PACKED, {
+        id: 99,
+        owner: 'tester.gm',
+        name: 'Craft Tester',
+        coordinates: {x: 0, y: 0},
+        hullmass: 200_000,
+        capacity: 8_000_000,
+        cargomass: 0,
+        energy: 500_000,
+        modules: [
+            {itemId: ITEM_GENERATOR_T1, stats: encodeStats([999, 999])},
+            {itemId: ITEM_CRAFTER_T1, stats: encodeStats([999, 999])},
+        ],
+        cargo,
+    })
+}
+
+function crafterSpeed(entity: ReturnType<typeof ship>): number {
+    return rollupCrafter(entity.crafter_lanes)!.speed.toNumber()
+}
+
+function plasmaCell(quantity: number) {
+    return ServerContract.Types.cargo_item.from({
+        item_id: UInt16.from(ITEM_PLASMA_CELL),
+        quantity: UInt32.from(quantity),
+        stats: UInt64.from(0),
+        modules: [],
+    })
+}
+
+describe('maxCraftable — incoming', () => {
+    test('on-hand-only baseline stays 0 for an empty-cargo entity', () => {
+        const recipe = getRecipe(ITEM_ENGINE_T1)!
+        const entity = ship([])
+        expect(maxCraftable(entity, recipe, crafterSpeed(entity), NOW)).toBe(0)
+    })
+
+    test('incoming source alone covers the recipe inputs', () => {
+        const recipe = getRecipe(ITEM_ENGINE_T1)!
+        const entity = ship([])
+        const incoming: IncomingSource[] = [
+            {holdId: '1', until: new Date(NOW.getTime() - 1000), items: [plasmaCell(1800)]},
+        ]
+
+        expect(maxCraftable(entity, recipe, crafterSpeed(entity), NOW)).toBe(0)
+        expect(maxCraftable(entity, recipe, crafterSpeed(entity), NOW, incoming)).toBe(3)
+    })
+
+    test('an incoming source arriving well after craft completion still resolves (eventually craftable)', () => {
+        const recipe = getRecipe(ITEM_ENGINE_T1)!
+        const entity = ship([])
+        const farFuture: IncomingSource[] = [
+            {
+                holdId: '1',
+                until: new Date(NOW.getTime() + 1_000_000_000),
+                items: [plasmaCell(1800)],
+            },
+        ]
+
+        expect(maxCraftable(entity, recipe, crafterSpeed(entity), NOW, farFuture)).toBe(3)
+    })
+})

package/src/capabilities/craftable.ts

@@ -1,8 +1,14 @@
 import type {ServerContract} from '../contracts'
 import {getItem} from '../data/catalog'
 import type {Recipe} from '../data/recipes-runtime'
-import {availableForItem, cargoReadyAt, projectedCargoAvailableAt} from '../scheduling/availability'
+import {
+    availableForItem,
+    projectedCargoAvailableAt,
+    taskCargoEffect,
+    type IncomingSource,
+} from '../scheduling/availability'
 import {candidateLaneCompletesAt, workerLaneKey} from '../scheduling/lanes'
+import * as schedule from '../scheduling/schedule'
 import type {ScheduleData} from '../scheduling/schedule'
 import {calc_craft_duration} from './crafting'
 
@@ -14,11 +20,35 @@ export interface CraftableEntity extends ScheduleData {
     modules: ModuleEntry[]
 }
 
+// Recipe inputs aren't stat-pinned (any variant counts, mirroring availableForItem's item-id aggregation).
+function itemReadyAt(
+    entity: CraftableEntity,
+    itemIds: readonly number[],
+    incoming: readonly IncomingSource[]
+): Date {
+    let readyMs = 0
+    for (const ordered of schedule.orderedTasks(entity)) {
+        for (const item of taskCargoEffect(ordered.task).added) {
+            if (itemIds.includes(item.item_id.toNumber())) {
+                readyMs = Math.max(readyMs, ordered.completesAt.getTime())
+                break
+            }
+        }
+    }
+    for (const src of incoming) {
+        if (src.items.some((item) => itemIds.includes(item.item_id.toNumber()))) {
+            readyMs = Math.max(readyMs, src.until.getTime())
+        }
+    }
+    return new Date(readyMs)
+}
+
 export function maxCraftable(
     entity: CraftableEntity,
     recipe: Recipe,
     crafterSpeed: number,
-    now: Date
+    now: Date,
+    incoming: readonly IncomingSource[] = []
 ): number {
     if (recipe.inputs.length === 0) return 0
 
@@ -30,12 +60,13 @@ export function maxCraftable(
     const crafterLane = workerLaneKey(entity.modules, 'crafter', entity.lanes ?? [])
     const naiveCompletesAt = candidateLaneCompletesAt(entity, crafterLane, perUnitDuration, now)
     const laneStartMs = naiveCompletesAt.getTime() - perUnitDuration * 1000
-    const readyMs = cargoReadyAt(
+    const readyMs = itemReadyAt(
         entity,
-        recipe.inputs.map((input) => input.itemId)
+        recipe.inputs.map((input) => input.itemId),
+        incoming
     ).getTime()
     const completesAt = new Date(Math.max(laneStartMs, readyMs) + perUnitDuration * 1000)
-    const availability = projectedCargoAvailableAt(entity, completesAt)
+    const availability = projectedCargoAvailableAt(entity, completesAt, incoming)
 
     let maxUnits: bigint | undefined
     for (const input of recipe.inputs) {

package/src/derivation/crafting.test.ts

@@ -0,0 +1,17 @@
+import {describe, expect, test} from 'bun:test'
+import {usedInputStatKeys} from './crafting'
+import {ITEM_BUILDER_T1} from '../data/item-ids'
+
+describe('usedInputStatKeys', () => {
+    test('maps each input to the stat keys the blend actually consumes', () => {
+        // Ceramic.hardness feeds the output's resonance slot; a name match would miss it.
+        expect(usedInputStatKeys(ITEM_BUILDER_T1)).toEqual([
+            ['resonance'],
+            ['hardness', 'fineness'],
+        ])
+    })
+
+    test('returns an empty array for an unknown recipe', () => {
+        expect(usedInputStatKeys(999999)).toEqual([])
+    })
+})

package/src/derivation/crafting.ts

@@ -66,6 +66,24 @@ function keyForRecipeInputStat(recipe: Recipe, inputIndex: number, statIndex: nu
     return innerKeys[statIndex] ?? ''
 }
 
+export function usedInputStatKeys(outputItemId: number): string[][] {
+    const recipe = getRecipe(outputItemId)
+    if (!recipe) return []
+    const usedIdx = recipe.inputs.map(() => new Set<number>())
+    for (const slot of recipe.statSlots) {
+        for (const src of slot.sources) {
+            usedIdx[src.inputIndex]?.add(src.statIndex)
+        }
+    }
+    return recipe.inputs.map((input, i) => {
+        const keys = getItemStatKeys(input.itemId)
+        return [...usedIdx[i]]
+            .sort((a, b) => a - b)
+            .map((idx) => keys[idx] ?? '')
+            .filter(Boolean)
+    })
+}
+
 export function decodeCraftedItemStats(itemId: number, stats: bigint): Record<string, number> {
     const keys = getItemStatKeys(itemId)
     const result: Record<string, number> = {}

package/src/index-module.ts

@@ -319,7 +319,11 @@ export {
     availableForItem,
     cargoReadyAt,
     taskCargoEffect,
+    calcCounterpartDelivery,
+    cargoKey,
+    cargoInputKey,
 } from './scheduling/availability'
+export type {CargoInput, IncomingSource} from './scheduling/availability'
 
 export {maxCraftable} from './capabilities/craftable'
 
@@ -412,6 +416,7 @@ export {
     decodeStat,
     decodeStats,
     decodeCraftedItemStats,
+    usedInputStatKeys,
     blendStacks,
     computeComponentStats,
     blendComponentStacks,

package/src/scheduling/availability.test.ts

@@ -0,0 +1,157 @@
+import {describe, expect, test} from 'bun:test'
+import {HoldKind, ServerContract, TaskType} from '../index-module'
+import {
+    calcCounterpartDelivery,
+    cargoReadyAt,
+    type CargoInput,
+    type IncomingSource,
+    projectedCargoAvailableAt,
+} from './availability'
+
+const T0 = '2026-06-19T00:00:00'
+const EPOCH = new Date(0)
+
+function cargoItem(itemId: number, stats: number, quantity: number) {
+    return ServerContract.Types.cargo_item.from({item_id: itemId, stats, modules: [], quantity})
+}
+
+function task(over: {type?: number; duration?: number; cargo?: ReturnType<typeof cargoItem>[]}) {
+    return ServerContract.Types.task.from({
+        type: over.type ?? TaskType.LOAD,
+        duration: over.duration ?? 60,
+        cancelable: 0,
+        cargo: over.cargo ?? [],
+        couplings: [],
+    })
+}
+
+function coupling(kind: number) {
+    return ServerContract.Types.coupling.from({
+        counterpart: {entity_type: 'ship', entity_id: 2},
+        hold: 1,
+        kind,
+    })
+}
+
+function entity(
+    cargo: ReturnType<typeof cargoItem>[],
+    tasks: ReturnType<typeof task>[] = [],
+    startedISO = T0
+) {
+    return ServerContract.Types.entity_info.from({
+        type: 'ship',
+        id: 1,
+        owner: 'player.gm',
+        entity_name: 'Ship 1',
+        coordinates: {x: 0, y: 0, z: 0},
+        item_id: 1,
+        cargomass: 0,
+        cargo: cargo.map((c) => ({
+            item_id: c.item_id,
+            stats: c.stats,
+            modules: c.modules,
+            quantity: c.quantity,
+            id: 0,
+        })),
+        modules: [],
+        lanes: [{lane_key: 0, schedule: {started: startedISO, tasks}}],
+        gatherer_lanes: [],
+        crafter_lanes: [],
+        builder_lanes: [],
+        loader_lanes: [],
+        holds: [],
+    })
+}
+
+describe('cargoReadyAt', () => {
+    test('on-hand covers demand → epoch', () => {
+        const e = entity([cargoItem(7, 0, 10)])
+        const demand: CargoInput[] = [{itemId: 7, stats: 0n, quantity: 5}]
+        expect(cargoReadyAt(e, demand)).toEqual(EPOCH)
+    })
+
+    test('own-lane LOAD covers demand → its completion', () => {
+        const loadCompletesAt = new Date('2026-06-19T00:01:00.000Z')
+        const e = entity(
+            [],
+            [task({type: TaskType.LOAD, duration: 60, cargo: [cargoItem(7, 0, 10)]})]
+        )
+        const demand: CargoInput[] = [{itemId: 7, stats: 0n, quantity: 5}]
+        expect(cargoReadyAt(e, demand)).toEqual(loadCompletesAt)
+    })
+
+    test('incoming source covers demand → its until', () => {
+        const until = new Date('2026-06-19T00:00:30.000Z')
+        const e = entity([])
+        const incoming: IncomingSource[] = [{holdId: '1', until, items: [cargoItem(7, 0, 10)]}]
+        const demand: CargoInput[] = [{itemId: 7, stats: 0n, quantity: 5}]
+        expect(cargoReadyAt(e, demand, incoming)).toEqual(until)
+    })
+
+    test('on-hand covers demand; unrelated same-item different-stats inflow does not delay readiness', () => {
+        const laterCompletesAt = new Date('2026-06-19T00:01:00.000Z')
+        const e = entity(
+            [cargoItem(7, 0, 10)],
+            [task({type: TaskType.LOAD, duration: 60, cargo: [cargoItem(7, 99, 10)]})]
+        )
+        const demand: CargoInput[] = [{itemId: 7, stats: 0n, quantity: 5}]
+        const result = cargoReadyAt(e, demand)
+        expect(result).toEqual(EPOCH)
+        expect(result).not.toEqual(laterCompletesAt)
+    })
+})
+
+describe('calcCounterpartDelivery', () => {
+    test('coupled CRAFT task returns output cargo only', () => {
+        const output = cargoItem(9, 0, 1)
+        const t = task({
+            type: TaskType.CRAFT,
+            cargo: [cargoItem(7, 0, 2), cargoItem(8, 0, 1), output],
+        })
+        const result = calcCounterpartDelivery(t, coupling(HoldKind.PUSH))
+        expect(result.length).toBe(1)
+        expect(result[0].item_id.toNumber()).toBe(9)
+    })
+
+    test('CRAFT task with empty cargo returns []', () => {
+        const t = task({type: TaskType.CRAFT, cargo: []})
+        expect(calcCounterpartDelivery(t, coupling(HoldKind.PUSH))).toEqual([])
+    })
+
+    test('coupled UNLOAD task returns whole cargo', () => {
+        const t = task({type: TaskType.UNLOAD, cargo: [cargoItem(7, 0, 2), cargoItem(8, 0, 1)]})
+        const result = calcCounterpartDelivery(t, coupling(HoldKind.GATHER))
+        expect(result.length).toBe(2)
+    })
+
+    test('non-incoming coupling kind returns []', () => {
+        const t = task({type: TaskType.UNLOAD, cargo: [cargoItem(7, 0, 2)]})
+        expect(calcCounterpartDelivery(t, coupling(HoldKind.PULL))).toEqual([])
+    })
+})
+
+describe('projectedCargoAvailableAt — incoming', () => {
+    const until = new Date('2026-06-19T00:00:30.000Z')
+
+    function incomingFor(qty: number): IncomingSource[] {
+        return [{holdId: '1', until, items: [cargoItem(7, 0, qty)]}]
+    }
+
+    test('credits an incoming source strictly before its until', () => {
+        const e = entity([])
+        const avail = projectedCargoAvailableAt(e, new Date(until.getTime() + 1), incomingFor(10))
+        expect(avail.get('7:0')).toBe(10n)
+    })
+
+    test('does not credit an incoming source at exactly its until', () => {
+        const e = entity([])
+        const avail = projectedCargoAvailableAt(e, until, incomingFor(10))
+        expect(avail.get('7:0') ?? 0n).toBe(0n)
+    })
+
+    test('does not credit an incoming source before its until', () => {
+        const e = entity([])
+        const avail = projectedCargoAvailableAt(e, new Date(until.getTime() - 1), incomingFor(10))
+        expect(avail.get('7:0') ?? 0n).toBe(0n)
+    })
+})

package/src/scheduling/availability.ts

@@ -1,9 +1,11 @@
 import type {ServerContract} from '../contracts'
-import {TaskType} from '../types'
+import {HoldKind, TaskType} from '../types'
 import * as schedule from './schedule'
 
 type Task = ServerContract.Types.task
+type Coupling = ServerContract.Types.coupling
 type CargoItem = ServerContract.Types.cargo_item
+type ModuleEntry = ServerContract.Types.module_entry
 
 export interface CargoEffect {
     added: CargoItem[]
@@ -14,6 +16,35 @@ export interface AvailabilityInput extends schedule.ScheduleData {
     cargo: CargoItem[]
 }
 
+export interface CargoInput {
+    itemId: number
+    stats: bigint
+    modules?: ModuleEntry[]
+    quantity: number
+}
+
+export interface IncomingSource {
+    holdId: string
+    until: Date
+    items: CargoItem[]
+}
+
+const INCOMING_COUPLING_KINDS = new Set<number>([HoldKind.PUSH, HoldKind.GATHER, HoldKind.FLIGHT])
+
+// Mirrors is_incoming_hold_kind: PUSH/GATHER/FLIGHT couplings deliver to the counterpart.
+export function isIncomingCouplingKind(kind: number): boolean {
+    return INCOMING_COUPLING_KINDS.has(kind)
+}
+
+// Mirrors calc_counterpart_delivery: incoming-kind couplings only; a coupled CRAFT yields its output slot.
+export function calcCounterpartDelivery(task: Task, coupling: Coupling): CargoItem[] {
+    if (!isIncomingCouplingKind(coupling.kind.toNumber())) return []
+    if (task.type.toNumber() === TaskType.CRAFT) {
+        return task.cargo.length === 0 ? [] : [task.cargo[task.cargo.length - 1]]
+    }
+    return task.cargo
+}
+
 export function taskCargoEffect(task: Task): CargoEffect {
     switch (task.type.toNumber()) {
         case TaskType.LOAD:
@@ -21,6 +52,7 @@ export function taskCargoEffect(task: Task): CargoEffect {
         case TaskType.UNDEPLOY:
             return {added: task.cargo, removed: []}
         case TaskType.UNLOAD:
+        case TaskType.UPGRADE:
             return {added: [], removed: task.cargo}
         case TaskType.GATHER:
             return task.couplings.length > 0
@@ -37,22 +69,34 @@ export function taskCargoEffect(task: Task): CargoEffect {
     }
 }
 
-export function cargoKey(item: CargoItem): string {
-    const base = `${item.item_id.toNumber()}:${item.stats.toString()}`
-    const modules = item.modules ?? []
-    const entityId = item.entity_id?.toString()
-    const normalizedEntityId = entityId && entityId !== '0' ? entityId : ''
+function refKey(itemId: number, stats: bigint, modules: ModuleEntry[], entityId: string): string {
+    const base = `${itemId}:${stats.toString()}`
+    const normalizedEntityId = entityId !== '0' ? entityId : ''
     if (modules.length === 0 && normalizedEntityId === '') return base
     return `${base}:modules=${JSON.stringify(modules)}:entity=${normalizedEntityId}`
 }
 
+export function cargoKey(item: CargoItem): string {
+    return refKey(
+        item.item_id.toNumber(),
+        BigInt(item.stats.toString()),
+        item.modules ?? [],
+        item.entity_id?.toString() ?? ''
+    )
+}
+
+export function cargoInputKey(input: CargoInput): string {
+    return refKey(input.itemId, input.stats, input.modules ?? [], '')
+}
+
 function cargoQuantity(item: CargoItem): bigint {
     return BigInt(item.quantity.toString())
 }
 
 export function projectedCargoAvailableAt(
     entity: AvailabilityInput,
-    at: Date
+    at: Date,
+    incoming: readonly IncomingSource[] = []
 ): Map<string, bigint> {
     const avail = new Map<string, bigint>()
 
@@ -73,6 +117,14 @@ export function projectedCargoAvailableAt(
         }
     }
 
+    for (const src of incoming) {
+        if (src.until.getTime() >= at.getTime()) continue
+        for (const item of src.items) {
+            const key = cargoKey(item)
+            avail.set(key, (avail.get(key) ?? 0n) + cargoQuantity(item))
+        }
+    }
+
     for (const ordered of tasks) {
         for (const item of taskCargoEffect(ordered.task).removed) {
             const key = cargoKey(item)
@@ -85,18 +137,47 @@ export function projectedCargoAvailableAt(
     return avail
 }
 
-// Latest completion among scheduled tasks producing any of the given inputs (a craft starts no earlier).
-export function cargoReadyAt(entity: AvailabilityInput, inputItemIds: readonly number[]): Date {
-    let readyMs = 0
+// Earliest-sufficient candidate (epoch, own-lane producer completions, incoming untils); else the latest candidate.
+export function cargoReadyAt(
+    entity: AvailabilityInput,
+    inputs: readonly CargoInput[],
+    incoming: readonly IncomingSource[] = []
+): Date {
+    const demand = new Map<string, bigint>()
+    for (const input of inputs) {
+        const key = cargoInputKey(input)
+        demand.set(key, (demand.get(key) ?? 0n) + BigInt(input.quantity))
+    }
+
+    const candidates: number[] = [0]
     for (const ordered of schedule.orderedTasks(entity)) {
         for (const item of taskCargoEffect(ordered.task).added) {
-            if (inputItemIds.includes(item.item_id.toNumber())) {
-                readyMs = Math.max(readyMs, ordered.completesAt.getTime())
+            if (demand.has(cargoKey(item))) {
+                candidates.push(ordered.completesAt.getTime())
+                break
+            }
+        }
+    }
+    for (const src of incoming) {
+        if (src.items.some((item) => demand.has(cargoKey(item)))) {
+            candidates.push(src.until.getTime())
+        }
+    }
+    candidates.sort((a, b) => a - b)
+
+    for (const candidateMs of candidates) {
+        // +1ms mirrors the contract's candidate+1µs probe: inclusive at the candidate instant.
+        const available = projectedCargoAvailableAt(entity, new Date(candidateMs + 1), incoming)
+        let sufficient = true
+        for (const [key, quantity] of demand) {
+            if ((available.get(key) ?? 0n) < quantity) {
+                sufficient = false
                 break
             }
         }
+        if (sufficient) return new Date(candidateMs)
     }
-    return new Date(readyMs)
+    return new Date(candidates[candidates.length - 1])
 }
 
 export function availableForItem(avail: Map<string, bigint>, itemId: number): bigint {