@shipload/sdk 1.0.0-next.7 → 1.0.0-next.71

package/src/scheduling/availability.test.ts

@@ -0,0 +1,320 @@
+import {describe, expect, test} from 'bun:test'
+import {HoldKind, ServerContract, TaskType} from '../index-module'
+import {
+    calcCounterpartDelivery,
+    cargoReadyAt,
+    type CargoInput,
+    hasIncomingCoupling,
+    hasSourceCoupling,
+    incomingSources,
+    type IncomingSource,
+    projectedCargoAvailableAt,
+    taskCargoEffect,
+} 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 craftTask(
+    cargo: ReturnType<typeof cargoItem>[],
+    couplings: ReturnType<typeof coupling>[]
+) {
+    return ServerContract.Types.task.from({
+        type: TaskType.CRAFT,
+        duration: 60,
+        cancelable: 0,
+        cargo,
+        couplings,
+    })
+}
+
+function entity(
+    cargo: ReturnType<typeof cargoItem>[],
+    tasks: ReturnType<typeof task>[] = [],
+    startedISO = T0
+) {
+    return ServerContract.Types.entity_info.from({
+        projected_at: 0,
+        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)
+    })
+})
+
+describe('clustercraft projection parity', () => {
+    const inputs = [cargoItem(1001, 0, 10), cargoItem(1002, 0, 5)]
+    const output = cargoItem(2001, 0, 1)
+
+    test('own-hold craft: inputs removed, output added', () => {
+        const eff = taskCargoEffect(craftTask([...inputs, output], []))
+        expect(eff.removed.length).toBe(2)
+        expect(eff.added).toEqual([output])
+    })
+
+    test('clustercraft to a target: no crafter debit, no crafter credit', () => {
+        const t = craftTask(
+            [...inputs, output],
+            [coupling(HoldKind.SOURCE), coupling(HoldKind.GATHER)]
+        )
+        expect(hasSourceCoupling(t)).toBe(true)
+        expect(hasIncomingCoupling(t)).toBe(true)
+        const eff = taskCargoEffect(t)
+        expect(eff.removed).toEqual([])
+        expect(eff.added).toEqual([])
+    })
+
+    test('clustercraft with target omitted: output falls back to crafter, still no input debit', () => {
+        const t = craftTask([...inputs, output], [coupling(HoldKind.SOURCE)])
+        expect(hasIncomingCoupling(t)).toBe(false)
+        const eff = taskCargoEffect(t)
+        expect(eff.removed).toEqual([])
+        expect(eff.added).toEqual([output])
+    })
+})
+
+function simpleTask(type: number) {
+    return ServerContract.Types.task.from({
+        type,
+        duration: 60,
+        cancelable: 0,
+        cargo: [cargoItem(401, 0, 100)],
+        couplings: [],
+    })
+}
+
+describe('taskCargoEffect task coverage', () => {
+    test('a contribute removes its cargo', () => {
+        const effect = taskCargoEffect(simpleTask(TaskType.CONTRIBUTE))
+        expect(effect.removed).toHaveLength(1)
+        expect(effect.added).toHaveLength(0)
+    })
+
+    test('a depot store removes its cargo', () => {
+        const effect = taskCargoEffect(simpleTask(TaskType.CIVIC_DEPOSIT))
+        expect(effect.removed).toHaveLength(1)
+        expect(effect.added).toHaveLength(0)
+    })
+
+    test('a depot take adds its cargo', () => {
+        const effect = taskCargoEffect(simpleTask(TaskType.CIVIC_WITHDRAW))
+        expect(effect.added).toHaveLength(1)
+        expect(effect.removed).toHaveLength(0)
+    })
+})
+
+describe('incomingSources', () => {
+    const RECEIVER = 1
+    const SENDER = 2
+
+    function receiver(holds: {id: number; kind: number; from: number; until: string}[]) {
+        const e = entity([])
+        return ServerContract.Types.entity_info.from({
+            projected_at: 0,
+            ...JSON.parse(JSON.stringify(e)),
+            id: RECEIVER,
+            holds: holds.map((h) => ({
+                id: h.id,
+                kind: h.kind,
+                counterpart: {entity_type: 'ship', entity_id: h.from},
+                until: h.until,
+                incoming_mass: 100,
+            })),
+        })
+    }
+
+    function sender(tasks: ReturnType<typeof craftTask>[]) {
+        const e = entity([], [])
+        return ServerContract.Types.entity_info.from({
+            projected_at: 0,
+            ...JSON.parse(JSON.stringify(e)),
+            id: SENDER,
+            lanes: [{lane_key: 0, schedule: {started: T0, tasks}}],
+        })
+    }
+
+    function coupledTo(hold: number, entityId: number, kind: number) {
+        return ServerContract.Types.coupling.from({
+            counterpart: {entity_type: 'ship', entity_id: entityId},
+            hold,
+            kind,
+        })
+    }
+
+    test('a coupled craft output resolves to the receiving hold', () => {
+        const to = receiver([{id: 1, kind: HoldKind.GATHER, from: SENDER, until: T0}])
+        const from = sender([
+            craftTask(
+                [cargoItem(7, 0, 4), cargoItem(9, 0, 1)],
+                [coupledTo(1, RECEIVER, HoldKind.GATHER)]
+            ),
+        ])
+        const sources = incomingSources(to, () => from)
+        expect(sources).toHaveLength(1)
+        // A craft delivers its output slot alone, never its inputs.
+        expect(sources[0].items).toHaveLength(1)
+        expect(sources[0].items[0].item_id.toNumber()).toBe(9)
+        expect(sources[0].holdId).toBe('1')
+    })
+
+    test('a hold whose counterpart is unknown yields nothing', () => {
+        const to = receiver([{id: 1, kind: HoldKind.GATHER, from: SENDER, until: T0}])
+        expect(incomingSources(to, () => undefined)).toHaveLength(0)
+    })
+
+    test('an excluded hold is skipped', () => {
+        const to = receiver([{id: 1, kind: HoldKind.GATHER, from: SENDER, until: T0}])
+        const from = sender([
+            craftTask([cargoItem(9, 0, 1)], [coupledTo(1, RECEIVER, HoldKind.GATHER)]),
+        ])
+        expect(incomingSources(to, () => from, ['1'])).toHaveLength(0)
+    })
+
+    test('a coupling naming another hold does not fill this one', () => {
+        const to = receiver([{id: 1, kind: HoldKind.GATHER, from: SENDER, until: T0}])
+        const from = sender([
+            craftTask([cargoItem(9, 0, 1)], [coupledTo(2, RECEIVER, HoldKind.GATHER)]),
+        ])
+        expect(incomingSources(to, () => from)).toHaveLength(0)
+    })
+
+    test('an outgoing hold kind is not an incoming source', () => {
+        const to = receiver([{id: 1, kind: HoldKind.PULL, from: SENDER, until: T0}])
+        const from = sender([
+            craftTask([cargoItem(9, 0, 1)], [coupledTo(1, RECEIVER, HoldKind.GATHER)]),
+        ])
+        expect(incomingSources(to, () => from)).toHaveLength(0)
+    })
+})

package/src/scheduling/availability.ts

@@ -0,0 +1,251 @@
+import type {ServerContract} from '../contracts'
+import {HoldKind, TaskType} from '../types'
+import * as schedule from './schedule'
+import {taskCargoRule} from './task-effects'
+
+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[]
+    removed: CargoItem[]
+}
+
+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 has_source_hold: a HOLD_SOURCE coupling marks an escrowed clustercraft.
+export function hasSourceCoupling(task: Task): boolean {
+    return task.couplings.some((c) => c.kind.toNumber() === HoldKind.SOURCE)
+}
+
+// Mirrors has_incoming_coupling: any PUSH/GATHER/FLIGHT coupling delivers output to a counterpart.
+export function hasIncomingCoupling(task: Task): boolean {
+    return task.couplings.some((c) => isIncomingCouplingKind(c.kind.toNumber()))
+}
+
+// A CRAFT task's output ownership: clustered escrows inputs off other members; own-output lands on the crafter.
+export function craftCargoOwnership(task: Task): {clustered: boolean; ownOutput: boolean} {
+    const clustered = hasSourceCoupling(task)
+    return {
+        clustered,
+        ownOutput: clustered ? !hasIncomingCoupling(task) : task.couplings.length === 0,
+    }
+}
+
+// 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 interface IncomingHoldEntity extends schedule.ScheduleData {
+    id: {toString(): string}
+    holds?: ServerContract.Types.hold[]
+}
+
+// Mirrors incoming_sources: each incoming hold resolved through the counterpart task that will fill it.
+export function incomingSources(
+    entity: IncomingHoldEntity,
+    findCounterpart: (entityId: string) => schedule.ScheduleData | undefined,
+    excludedHoldIds: readonly string[] = []
+): IncomingSource[] {
+    const out: IncomingSource[] = []
+    const excluded = new Set(excludedHoldIds.map((id) => String(id)))
+    const selfId = entity.id.toString()
+    for (const hold of entity.holds ?? []) {
+        if (!isIncomingCouplingKind(hold.kind.toNumber())) continue
+        const holdId = hold.id.toString()
+        if (excluded.has(holdId)) continue
+        const counterpart = findCounterpart(hold.counterpart.entity_id.toString())
+        if (!counterpart) continue
+        let matched = false
+        for (const lane of counterpart.lanes ?? []) {
+            if (matched) break
+            for (const task of lane.schedule.tasks) {
+                if (matched) break
+                for (const coupling of task.couplings) {
+                    if (coupling.hold.toString() !== holdId) continue
+                    if (coupling.counterpart.entity_id.toString() !== selfId) continue
+                    const items = calcCounterpartDelivery(task, coupling)
+                    if (items.length > 0) {
+                        out.push({holdId, until: hold.until.toDate(), items})
+                    }
+                    matched = true
+                    break
+                }
+            }
+        }
+    }
+    return out
+}
+
+export function taskCargoEffect(task: Task): CargoEffect {
+    switch (taskCargoRule(task.type.toNumber())) {
+        case 'all-in':
+        case 'undeploy':
+            return {added: task.cargo, removed: []}
+        case 'all-out':
+            return {added: [], removed: task.cargo}
+        case 'gather':
+            return task.couplings.length > 0
+                ? {added: [], removed: []}
+                : {added: task.cargo, removed: []}
+        case 'craft': {
+            if (task.cargo.length === 0) return {added: [], removed: []}
+            const {clustered, ownOutput} = craftCargoOwnership(task)
+            return {
+                added: ownOutput ? [task.cargo[task.cargo.length - 1]] : [],
+                removed: clustered ? [] : task.cargo.slice(0, -1),
+            }
+        }
+        default:
+            return {added: [], removed: []}
+    }
+}
+
+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,
+    incoming: readonly IncomingSource[] = []
+): Map<string, bigint> {
+    const avail = new Map<string, bigint>()
+
+    for (const item of entity.cargo) {
+        const key = cargoKey(item)
+        avail.set(key, (avail.get(key) ?? 0n) + cargoQuantity(item))
+    }
+
+    // Every scheduled task reserves inputs against the unsettled cargo base, even already-elapsed ones.
+    const tasks = schedule.orderedTasks(entity)
+
+    for (const ordered of tasks) {
+        if (ordered.completesAt.getTime() >= at.getTime()) continue
+
+        for (const item of taskCargoEffect(ordered.task).added) {
+            const key = cargoKey(item)
+            avail.set(key, (avail.get(key) ?? 0n) + cargoQuantity(item))
+        }
+    }
+
+    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)
+            const current = avail.get(key) ?? 0n
+            const quantity = cargoQuantity(item)
+            avail.set(key, current > quantity ? current - quantity : 0n)
+        }
+    }
+
+    return avail
+}
+
+// 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 (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(candidates[candidates.length - 1])
+}
+
+export function availableForItem(avail: Map<string, bigint>, itemId: number): bigint {
+    const prefix = `${itemId}:`
+    let total = 0n
+    for (const [key, quantity] of avail) {
+        if (key.startsWith(prefix)) total += quantity
+    }
+    return total
+}