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

package/src/scheduling/cancel.test.ts

@@ -0,0 +1,327 @@
+import {describe, expect, test} from 'bun:test'
+import {ServerContract, TaskType, TaskCancelable} from '../index-module'
+import {cancelEligibility, CancelBlockReason} from './cancel'
+
+const T0 = '2026-06-19T00:00:00'
+
+function task(over: Partial<{type: number; duration: number; cancelable: number; group: number}>) {
+    return ServerContract.Types.task.from({
+        type: over.type ?? TaskType.TRAVEL,
+        duration: over.duration ?? 100,
+        cancelable: over.cancelable ?? TaskCancelable.BEFORE_START,
+        cargo: [],
+        ...(over.group ? {entitygroup: over.group} : {}),
+    })
+}
+
+function entity(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: [],
+        modules: [],
+        lanes: [{lane_key: 0, schedule: {started: startedISO, tasks}}],
+        holds: [],
+    })
+}
+
+describe('cancelEligibility — local gates', () => {
+    const now = new Date('2026-06-19T00:00:10.000Z') // 10s in: task 0 running, task 1 upcoming
+
+    test('cancelling the last upcoming task: ok, count 1', () => {
+        const e = entity([task({}), task({})])
+        const plan = cancelEligibility(e, 0, 1, {now})
+        expect(plan.ok).toBe(true)
+        expect(plan.range.count).toBe(1)
+        expect(plan.range.taskIndices).toEqual([1])
+    })
+
+    test('NEVER task is blocked', () => {
+        const e = entity([
+            task({}),
+            task({cancelable: TaskCancelable.NEVER, type: TaskType.GATHER}),
+        ])
+        expect(cancelEligibility(e, 0, 1, {now}).blockedReason).toBe(CancelBlockReason.TASK_NEVER)
+    })
+
+    test('BEFORE_START task that is running is blocked', () => {
+        const e = entity([task({cancelable: TaskCancelable.BEFORE_START, duration: 100})])
+        // task 0 is running at now=10s
+        expect(cancelEligibility(e, 0, 0, {now}).blockedReason).toBe(
+            CancelBlockReason.BEFORE_START_RUNNING
+        )
+    })
+
+    test('done task is blocked', () => {
+        const e = entity([task({duration: 5})]) // completes at 5s, now=10s
+        expect(cancelEligibility(e, 0, 0, {now}).blockedReason).toBe(CancelBlockReason.DONE)
+    })
+
+    test('unknown lane: count 0, ok false', () => {
+        const e = entity([task({})])
+        const plan = cancelEligibility(e, 9, 0, {now})
+        expect(plan.ok).toBe(false)
+        expect(plan.range.count).toBe(0)
+    })
+
+    test('multi-task range: 4 tasks, fromIndex 1 yields count 3', () => {
+        const e = entity([
+            task({duration: 100}),
+            task({cancelable: TaskCancelable.ALWAYS, duration: 100}),
+            task({cancelable: TaskCancelable.ALWAYS, duration: 100}),
+            task({cancelable: TaskCancelable.ALWAYS, duration: 100}),
+        ])
+        const plan = cancelEligibility(e, 0, 1, {now})
+        expect(plan.ok).toBe(true)
+        expect(plan.range.count).toBe(3)
+        expect(plan.range.taskIndices).toEqual([1, 2, 3])
+    })
+})
+
+describe('cancelEligibility — linked tasks', () => {
+    const now = new Date('2026-06-19T00:00:10.000Z')
+    test('range containing a linked (entitygroup) task is blocked', () => {
+        const e = entity([task({}), task({group: 42}), task({})])
+        expect(cancelEligibility(e, 0, 0, {now}).blockedReason).toBe(
+            CancelBlockReason.CONTAINS_LINKED_TASK
+        )
+    })
+    test('task after the linked one cancels normally', () => {
+        const e = entity([task({}), task({group: 42}), task({})])
+        expect(cancelEligibility(e, 0, 2, {now}).ok).toBe(true)
+    })
+})
+
+const HOLD_PULL = 1
+function loadTask(giverType: string, giverId: number, holdId: number, qty: number) {
+    return ServerContract.Types.task.from({
+        type: TaskType.LOAD,
+        duration: 100,
+        cancelable: TaskCancelable.ALWAYS,
+        cargo: [{item_id: 7, stats: 0, modules: [], quantity: qty}],
+        entitytarget: {entity_type: giverType, entity_id: giverId},
+        hold: holdId,
+    })
+}
+
+describe('cancelEligibility — effects', () => {
+    const now = new Date('2026-06-19T00:00:10.000Z')
+
+    test('abandonsRunning true when the front of range is a running ALWAYS task', () => {
+        const e = entity([
+            task({cancelable: TaskCancelable.ALWAYS, type: TaskType.RECHARGE, duration: 100}),
+        ])
+        expect(cancelEligibility(e, 0, 0, {now}).effects.abandonsRunning).toBe(true)
+    })
+
+    test('buildplot cancel reports keepsPlotDeposits', () => {
+        const e = entity([
+            ServerContract.Types.task.from({
+                type: TaskType.BUILDPLOT,
+                duration: 100,
+                cancelable: TaskCancelable.ALWAYS,
+                cargo: [],
+                entitytarget: {entity_type: 'plot', entity_id: 55},
+            }),
+        ])
+        const plan = cancelEligibility(e, 0, 0, {now})
+        expect(plan.effects.keepsPlotDeposits?.plot.entity_id.toNumber()).toBe(55)
+    })
+
+    test('PULL load cancel refunds cargo to the giver', () => {
+        const lt = loadTask('warehouse', 6, 1, 4)
+        const upcoming = new Date('2026-06-18T23:59:50.000Z')
+        const e = 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: [],
+            modules: [],
+            lanes: [{lane_key: 0, schedule: {started: T0, tasks: [lt]}}],
+            holds: [
+                {
+                    id: 1,
+                    kind: HOLD_PULL,
+                    counterpart: {entity_type: 'warehouse', entity_id: 6},
+                    until: T0,
+                    incoming_mass: 0,
+                },
+            ],
+        })
+        const plan = cancelEligibility(e, 0, 0, {now: upcoming})
+        expect(plan.effects.refunds[0]?.giver.entity_id.toNumber()).toBe(6)
+        expect(plan.effects.refunds[0]?.cargo[0].quantity.toNumber()).toBe(4)
+    })
+
+    test('PULL load cancel populates releasedHolds with kind and counterpart', () => {
+        const lt = loadTask('warehouse', 6, 1, 4)
+        const upcoming = new Date('2026-06-18T23:59:50.000Z')
+        const e = 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: [],
+            modules: [],
+            lanes: [{lane_key: 0, schedule: {started: T0, tasks: [lt]}}],
+            holds: [
+                {
+                    id: 1,
+                    kind: HOLD_PULL,
+                    counterpart: {entity_type: 'warehouse', entity_id: 6},
+                    until: T0,
+                    incoming_mass: 0,
+                },
+            ],
+        })
+        const plan = cancelEligibility(e, 0, 0, {now: upcoming})
+        expect(plan.effects.releasedHolds[0]?.kind).toBe(1)
+        expect(plan.effects.releasedHolds[0]?.counterpart.entity_id.toNumber()).toBe(6)
+    })
+
+    test('unresolvable hold emits no releasedHolds entry', () => {
+        const lt = loadTask('warehouse', 6, 99, 4)
+        const upcoming = new Date('2026-06-18T23:59:50.000Z')
+        const e = 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: [],
+            modules: [],
+            lanes: [{lane_key: 0, schedule: {started: T0, tasks: [lt]}}],
+            holds: [],
+        })
+        const plan = cancelEligibility(e, 0, 0, {now: upcoming})
+        expect(plan.effects.releasedHolds).toHaveLength(0)
+    })
+})
+
+describe('cancelEligibility — feasibility', () => {
+    const upcoming = new Date('2026-06-18T23:59:50.000Z')
+
+    test('WOULD_STRAND when cancelling a producer a later consumer needs', () => {
+        const producer = ServerContract.Types.task.from({
+            type: TaskType.LOAD,
+            duration: 50,
+            cancelable: TaskCancelable.ALWAYS,
+            cargo: [{item_id: 7, stats: 0, modules: [], quantity: 2}],
+        })
+        const consumer = ServerContract.Types.task.from({
+            type: TaskType.CRAFT,
+            duration: 50,
+            cancelable: TaskCancelable.ALWAYS,
+            cargo: [
+                {item_id: 7, stats: 0, modules: [], quantity: 2},
+                {item_id: 9, stats: 0, modules: [], quantity: 1},
+            ],
+        })
+        const e = ServerContract.Types.entity_info.from({
+            type: 'ship',
+            id: 1,
+            owner: 'player.gm',
+            entity_name: 'S',
+            coordinates: {x: 0, y: 0, z: 0},
+            item_id: 1,
+            cargomass: 0,
+            cargo: [],
+            modules: [],
+            lanes: [
+                {
+                    lane_key: 1,
+                    schedule: {started: '2026-06-19T00:00:00', tasks: [producer]},
+                },
+                {
+                    lane_key: 2,
+                    schedule: {started: '2026-06-19T00:00:00', tasks: [consumer]},
+                },
+            ],
+            holds: [],
+        })
+        expect(cancelEligibility(e, 1, 0, {now: upcoming}).blockedReason).toBe(
+            CancelBlockReason.WOULD_STRAND
+        )
+    })
+
+    test('benign cancel on independent lane does NOT strand', () => {
+        const producer = ServerContract.Types.task.from({
+            type: TaskType.LOAD,
+            duration: 50,
+            cancelable: TaskCancelable.ALWAYS,
+            cargo: [{item_id: 7, stats: 0, modules: [], quantity: 2}],
+        })
+        const independent = ServerContract.Types.task.from({
+            type: TaskType.TRAVEL,
+            duration: 50,
+            cancelable: TaskCancelable.ALWAYS,
+            cargo: [],
+        })
+        const e = ServerContract.Types.entity_info.from({
+            type: 'ship',
+            id: 1,
+            owner: 'player.gm',
+            entity_name: 'S',
+            coordinates: {x: 0, y: 0, z: 0},
+            item_id: 1,
+            cargomass: 0,
+            cargo: [],
+            modules: [],
+            lanes: [
+                {lane_key: 1, schedule: {started: '2026-06-19T00:00:00', tasks: [producer]}},
+                {lane_key: 2, schedule: {started: '2026-06-19T00:00:00', tasks: [independent]}},
+            ],
+            holds: [],
+        })
+        expect(cancelEligibility(e, 2, 0, {now: upcoming}).ok).toBe(true)
+    })
+
+    test('WOULD_STRAND when cancelling producer of a MODULAR cargo the consumer needs', () => {
+        const moduledCargo = {item_id: 7, stats: 0, modules: [{type: 3}], quantity: 2}
+        const producer = ServerContract.Types.task.from({
+            type: TaskType.LOAD,
+            duration: 50,
+            cancelable: TaskCancelable.ALWAYS,
+            cargo: [moduledCargo],
+        })
+        const consumer = ServerContract.Types.task.from({
+            type: TaskType.CRAFT,
+            duration: 50,
+            cancelable: TaskCancelable.ALWAYS,
+            cargo: [moduledCargo, {item_id: 9, stats: 0, modules: [], quantity: 1}],
+        })
+        const e = ServerContract.Types.entity_info.from({
+            type: 'ship',
+            id: 1,
+            owner: 'player.gm',
+            entity_name: 'S',
+            coordinates: {x: 0, y: 0, z: 0},
+            item_id: 1,
+            cargomass: 0,
+            cargo: [],
+            modules: [],
+            lanes: [
+                {lane_key: 1, schedule: {started: '2026-06-19T00:00:00', tasks: [producer]}},
+                {lane_key: 2, schedule: {started: '2026-06-19T00:00:00', tasks: [consumer]}},
+            ],
+            holds: [],
+        })
+        expect(cancelEligibility(e, 1, 0, {now: upcoming}).blockedReason).toBe(
+            CancelBlockReason.WOULD_STRAND
+        )
+    })
+})

package/src/scheduling/cancel.ts

@@ -0,0 +1,209 @@
+import type {ServerContract} from '../contracts'
+import {TaskCancelable, TaskType} from '../types'
+import {calcCargoItemMass} from '../capabilities/storage'
+import {taskCargoEffect, cargoKey} from './availability'
+import * as schedule from './schedule'
+import {validateSchedule, type Projectable} from './projection'
+
+export enum CancelBlockReason {
+    TASK_NEVER = 'TASK_NEVER',
+    BEFORE_START_RUNNING = 'BEFORE_START_RUNNING',
+    DONE = 'DONE',
+    CONTAINS_LINKED_TASK = 'CONTAINS_LINKED_TASK',
+    WOULD_STRAND = 'WOULD_STRAND',
+    WOULD_OVERFILL = 'WOULD_OVERFILL',
+    NOT_OWNER = 'NOT_OWNER',
+}
+
+type Task = InstanceType<typeof ServerContract.Types.task>
+type EntityInfo = InstanceType<typeof ServerContract.Types.entity_info>
+type EntityRef = InstanceType<typeof ServerContract.Types.entity_ref>
+type CargoItem = InstanceType<typeof ServerContract.Types.cargo_item>
+
+export interface CancelRefund {
+    giver: EntityRef
+    cargo: CargoItem[]
+}
+export interface CancelReleasedHold {
+    counterpart: EntityRef
+    kind: number
+}
+export interface CancelEffects {
+    refunds: CancelRefund[]
+    releasedHolds: CancelReleasedHold[]
+    abandonsRunning: boolean
+    keepsPlotDeposits?: {plot: EntityRef}
+    energyForfeited?: number
+}
+export interface CancelPlan {
+    ok: boolean
+    blockedReason?: CancelBlockReason
+    range: {count: number; taskIndices: number[]}
+    effects: CancelEffects
+}
+export interface CancelEligibilityInput {
+    now: Date
+    counterparts?: Map<string, EntityInfo>
+}
+
+const EMPTY_EFFECTS: CancelEffects = {refunds: [], releasedHolds: [], abandonsRunning: false}
+
+function postCancelEntity(entity: EntityInfo, laneKey: number, fromTaskIndex: number): EntityInfo {
+    const clone = (entity.constructor as typeof ServerContract.Types.entity_info).from(
+        JSON.parse(JSON.stringify(entity.toJSON()))
+    ) as EntityInfo
+    const lane = clone.lanes.find((l) => l.lane_key.toNumber() === laneKey)!
+    lane.schedule.tasks = lane.schedule.tasks.slice(0, fromTaskIndex)
+    return clone
+}
+
+function feasibleAfterCancel(post: EntityInfo): boolean {
+    const ordered = schedule.orderedTasks(post as unknown as Projectable)
+    const base = new Map<string, number>()
+    for (const c of post.cargo ?? []) {
+        const k = cargoKey(c)
+        base.set(k, (base.get(k) ?? 0) + c.quantity.toNumber())
+    }
+    const isConsumer = (t: Task) =>
+        t.type.toNumber() === TaskType.CRAFT || t.type.toNumber() === TaskType.UNLOAD
+    for (const self of ordered) {
+        if (!isConsumer(self.task)) continue
+        const map = new Map(base)
+        for (const other of ordered) {
+            if (other.completesAt.getTime() >= self.completesAt.getTime()) continue
+            for (const out of taskCargoEffect(other.task).added) {
+                map.set(cargoKey(out), (map.get(cargoKey(out)) ?? 0) + out.quantity.toNumber())
+            }
+        }
+        for (const other of ordered) {
+            if (other === self) continue
+            for (const inp of taskCargoEffect(other.task).removed) {
+                const cur = map.get(cargoKey(inp)) ?? 0
+                map.set(cargoKey(inp), Math.max(0, cur - inp.quantity.toNumber()))
+            }
+        }
+        for (const inp of taskCargoEffect(self.task).removed) {
+            if ((map.get(cargoKey(inp)) ?? 0) < inp.quantity.toNumber()) return false
+        }
+    }
+    try {
+        validateSchedule(post as unknown as Projectable)
+    } catch {
+        return false
+    }
+    return true
+}
+
+interface Timing {
+    startsAt: number
+    completesAt: number
+    running: boolean
+    done: boolean
+}
+
+function laneTiming(
+    lane: {schedule: {started: {toDate(): Date}; tasks: Task[]}},
+    nowMs: number
+): Timing[] {
+    const startedMs = lane.schedule.started.toDate().getTime()
+    let endSec = 0
+    return lane.schedule.tasks.map((t) => {
+        const startsAt = startedMs + endSec * 1000
+        endSec += t.duration.toNumber()
+        const completesAt = startedMs + endSec * 1000
+        return {
+            startsAt,
+            completesAt,
+            running: nowMs >= startsAt && nowMs < completesAt,
+            done: nowMs >= completesAt,
+        }
+    })
+}
+
+export function cancelEligibility(
+    entity: EntityInfo,
+    laneKey: number,
+    fromTaskIndex: number,
+    input: CancelEligibilityInput
+): CancelPlan {
+    const lane = (entity.lanes ?? []).find((l) => l.lane_key.equals(laneKey))
+    if (!lane || fromTaskIndex < 0 || fromTaskIndex >= lane.schedule.tasks.length) {
+        return {ok: false, range: {count: 0, taskIndices: []}, effects: {...EMPTY_EFFECTS}}
+    }
+
+    const tasks = lane.schedule.tasks
+    const timing = laneTiming(lane, input.now.getTime())
+    const taskIndices: number[] = []
+    for (let i = fromTaskIndex; i < tasks.length; i++) taskIndices.push(i)
+    const range = {count: taskIndices.length, taskIndices}
+
+    const block = (blockedReason: CancelBlockReason): CancelPlan => ({
+        ok: false,
+        blockedReason,
+        range,
+        effects: {...EMPTY_EFFECTS},
+    })
+
+    for (const i of taskIndices) {
+        const t = tasks[i]
+        if (t.entitygroup && !t.entitygroup.equals(0))
+            return block(CancelBlockReason.CONTAINS_LINKED_TASK)
+    }
+
+    for (const i of taskIndices) {
+        const t = tasks[i]
+        if (timing[i].done) return block(CancelBlockReason.DONE)
+        if (t.cancelable.equals(TaskCancelable.NEVER) && !t.type.equals(TaskType.IDLE))
+            return block(CancelBlockReason.TASK_NEVER)
+        if (t.cancelable.equals(TaskCancelable.BEFORE_START) && timing[i].running)
+            return block(CancelBlockReason.BEFORE_START_RUNNING)
+    }
+
+    const post = postCancelEntity(entity, laneKey, fromTaskIndex)
+    if (!feasibleAfterCancel(post)) return block(CancelBlockReason.WOULD_STRAND)
+
+    const effects: CancelEffects = {refunds: [], releasedHolds: [], abandonsRunning: false}
+    let energyForfeited = 0
+    for (const i of taskIndices) {
+        const t = tasks[i]
+        if (timing[i].running && t.cancelable.equals(TaskCancelable.ALWAYS))
+            effects.abandonsRunning = true
+        if (t.energy_cost) energyForfeited += t.energy_cost.toNumber()
+        if (t.type.equals(TaskType.BUILDPLOT) && t.entitytarget)
+            effects.keepsPlotDeposits = {plot: t.entitytarget}
+        if (t.hold && t.entitytarget) {
+            const counterpart = input.counterparts?.get(t.entitytarget.entity_id.toString())
+            const hold =
+                (counterpart?.holds ?? []).find((h) => h.id.equals(t.hold!)) ??
+                (entity.holds ?? []).find((h) => h.id.equals(t.hold!))
+            if (hold) {
+                const kind = hold.kind.toNumber()
+                effects.releasedHolds.push({counterpart: t.entitytarget, kind})
+                if (kind === 1 /* HOLD_PULL */) {
+                    effects.refunds.push({giver: t.entitytarget, cargo: t.cargo})
+                    const giver = counterpart
+                    if (giver) {
+                        const returned = t.cargo.reduce(
+                            (s, c) => s + calcCargoItemMass(c).toNumber(),
+                            0
+                        )
+                        const cap = giver.capacity
+                            ? giver.capacity.toNumber()
+                            : Number.MAX_SAFE_INTEGER
+                        if (giver.cargomass.toNumber() + returned > cap) {
+                            return {
+                                ok: false,
+                                blockedReason: CancelBlockReason.WOULD_OVERFILL,
+                                range,
+                                effects: {...EMPTY_EFFECTS},
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+    if (energyForfeited > 0) effects.energyForfeited = energyForfeited
+
+    return {ok: true, range, effects}
+}

package/src/scheduling/idle-resolve.ts

@@ -31,13 +31,14 @@ export function composeIdleResolve(
         add(blocker.id)
     }
 
-    for (const hold of blocker.holds ?? []) {
-        const counterpartId = hold.counterpart.entity_id
-        if (lookupCounterpart) {
+    // Without a lookup we cannot confirm the counterpart has a completed task, so skip it.
+    if (lookupCounterpart) {
+        for (const hold of blocker.holds ?? []) {
+            const counterpartId = hold.counterpart.entity_id
             const counterpart = lookupCounterpart(counterpartId)
             if (!counterpart || !hasResolvable(counterpart, now)) continue
+            add(counterpartId)
         }
-        add(counterpartId)
     }
 
     return [...ids.map((id) => actions.resolve(id)), action]

package/src/scheduling/projection.ts

@@ -303,6 +303,7 @@ function applyTask(projected: ProjectedEntity, task: ServerContract.Types.task):
             break
         case TaskType.TRAVEL:
         case TaskType.WARP:
+        case TaskType.TRANSIT:
             applyFlightTask(projected, task, {complete: true})
             break
         case TaskType.LOAD:
@@ -461,6 +462,7 @@ export function projectEntityAt(entity: Projectable, now: Date): ProjectedEntity
                 break
             case TaskType.TRAVEL:
             case TaskType.WARP:
+            case TaskType.TRANSIT:
                 applyFlightTask(projected, task, {complete: taskComplete, progress})
                 break
             case TaskType.LOAD:

package/src/scheduling/schedule.ts

@@ -294,7 +294,9 @@ function entityDoesTaskType(entity: ScheduleData, taskType: TaskType, now: Date)
 
 export function isInFlight(entity: ScheduleData, now: Date): boolean {
     const lane = mobilityLane(entity)
-    return lane ? core.currentTaskType(lane.schedule, now) === TaskType.TRAVEL : false
+    if (!lane) return false
+    const t = core.currentTaskType(lane.schedule, now)
+    return t === TaskType.TRAVEL || t === TaskType.TRANSIT
 }
 
 export function isRecharging(entity: ScheduleData, now: Date): boolean {