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

package/src/scheduling/accessor.ts

@@ -1,82 +1,128 @@
 import type {ServerContract} from '../contracts'
 import type {TaskType} from '../types'
-import type {ScheduleData} from './schedule'
-import * as schedule from './schedule'
+import * as core from './lane-core'
+import {
+    activeTasks,
+    getLane,
+    getLanes,
+    hasSchedule,
+    isIdle,
+    LANE_MOBILITY,
+    type LaneView,
+    type ScheduleData,
+} from './schedule'
 
 type Task = ServerContract.Types.task
 
 export class ScheduleAccessor {
-    constructor(private entity: ScheduleData) {}
+    private _laneResolved = false
+    private _lane: LaneView | undefined
+
+    constructor(
+        private entity: ScheduleData,
+        private laneKey: number = LANE_MOBILITY
+    ) {}
+
+    private get lane(): LaneView | undefined {
+        if (!this._laneResolved) {
+            this._lane = getLane(this.entity, this.laneKey)
+            this._laneResolved = true
+        }
+        return this._lane
+    }
+
+    forLane(laneKey: number): ScheduleAccessor {
+        return new ScheduleAccessor(this.entity, laneKey)
+    }
+
+    get lanes(): LaneView[] {
+        return getLanes(this.entity)
+    }
 
     get hasSchedule(): boolean {
-        return schedule.hasSchedule(this.entity)
+        return hasSchedule(this.entity)
     }
 
     get isIdle(): boolean {
-        return schedule.isIdle(this.entity)
+        return isIdle(this.entity)
     }
 
     get tasks(): Task[] {
-        return schedule.getTasks(this.entity)
+        return this.lane?.schedule.tasks ?? []
+    }
+
+    activeTasks(now: Date): Task[] {
+        return activeTasks(this.entity, now)
     }
 
     duration(): number {
-        return schedule.scheduleDuration(this.entity)
+        return this.lane ? core.laneDuration(this.lane.schedule) : 0
     }
 
     elapsed(now: Date): number {
-        return schedule.scheduleElapsed(this.entity, now)
+        return this.lane ? core.laneElapsed(this.lane.schedule, now) : 0
     }
 
     remaining(now: Date): number {
-        return schedule.scheduleRemaining(this.entity, now)
+        return this.lane ? core.laneRemaining(this.lane.schedule, now) : 0
+    }
+
+    startsIn(now: Date): number {
+        return this.lane ? core.laneStartsIn(this.lane.schedule, now) : 0
     }
 
     complete(now: Date): boolean {
-        return schedule.scheduleComplete(this.entity, now)
+        return this.lane ? core.laneComplete(this.lane.schedule, now) : false
     }
 
     currentTaskIndex(now: Date): number {
-        return schedule.currentTaskIndex(this.entity, now)
+        return this.lane ? core.currentTaskIndexForLane(this.lane.schedule, now) : -1
     }
 
     currentTask(now: Date): Task | undefined {
-        return schedule.currentTask(this.entity, now)
+        return this.lane ? core.currentTask(this.lane.schedule, now) : undefined
     }
 
     currentTaskType(now: Date): TaskType | undefined {
-        return schedule.currentTaskType(this.entity, now)
+        return this.lane ? core.currentTaskType(this.lane.schedule, now) : undefined
     }
 
     taskStartTime(index: number): number {
-        return schedule.getTaskStartTime(this.entity, index)
+        return this.lane ? core.laneTaskStartTime(this.lane.schedule, index) : 0
     }
 
     taskElapsed(index: number, now: Date): number {
-        return schedule.getTaskElapsed(this.entity, index, now)
+        return this.lane ? core.laneTaskElapsed(this.lane.schedule, index, now) : 0
     }
 
     taskRemaining(index: number, now: Date): number {
-        return schedule.getTaskRemaining(this.entity, index, now)
+        return this.lane ? core.laneTaskRemaining(this.lane.schedule, index, now) : 0
     }
 
     taskComplete(index: number, now: Date): boolean {
-        return schedule.isTaskComplete(this.entity, index, now)
+        return this.lane ? core.laneTaskComplete(this.lane.schedule, index, now) : false
     }
 
     taskInProgress(index: number, now: Date): boolean {
-        return schedule.isTaskInProgress(this.entity, index, now)
+        return this.lane ? core.laneTaskInProgress(this.lane.schedule, index, now) : false
     }
 
     currentTaskProgress(now: Date): number {
-        return schedule.currentTaskProgress(this.entity, now)
+        return this.lane ? core.currentTaskProgress(this.lane.schedule, now) : 0
+    }
+
+    currentTaskProgressFloat(now: Date): number {
+        return this.lane ? core.currentTaskProgressFloatForLane(this.lane.schedule, now) : 0
     }
 
     progress(now: Date): number {
-        return schedule.scheduleProgress(this.entity, now)
+        return this.lane ? core.laneProgress(this.lane.schedule, now) : 0
     }
 }
 
-export function createScheduleAccessor(entity: ScheduleData): ScheduleAccessor {
-    return new ScheduleAccessor(entity)
+export function createScheduleAccessor(
+    entity: ScheduleData,
+    laneKey: number = LANE_MOBILITY
+): ScheduleAccessor {
+    return new ScheduleAccessor(entity, laneKey)
 }

package/src/scheduling/availability.ts

@@ -0,0 +1,108 @@
+import type {ServerContract} from '../contracts'
+import {TaskType} from '../types'
+import * as schedule from './schedule'
+
+type Task = ServerContract.Types.task
+type CargoItem = ServerContract.Types.cargo_item
+
+export interface CargoEffect {
+    added: CargoItem[]
+    removed: CargoItem[]
+}
+
+export interface AvailabilityInput extends schedule.ScheduleData {
+    cargo: CargoItem[]
+}
+
+export function taskCargoEffect(task: Task): CargoEffect {
+    switch (task.type.toNumber()) {
+        case TaskType.LOAD:
+        case TaskType.UNWRAP:
+        case TaskType.UNDEPLOY:
+            return {added: task.cargo, removed: []}
+        case TaskType.UNLOAD:
+            return {added: [], removed: task.cargo}
+        case TaskType.GATHER:
+            return task.entitytarget ? {added: [], removed: []} : {added: task.cargo, removed: []}
+        case TaskType.CRAFT:
+            if (task.cargo.length === 0) return {added: [], removed: []}
+            return {added: [task.cargo[task.cargo.length - 1]], removed: task.cargo.slice(0, -1)}
+        case TaskType.DEPLOY:
+            return task.cargo.length > 0
+                ? {added: [], removed: [task.cargo[0]]}
+                : {added: [], removed: []}
+        default:
+            return {added: [], removed: []}
+    }
+}
+
+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 : ''
+    if (modules.length === 0 && normalizedEntityId === '') return base
+    return `${base}:modules=${JSON.stringify(modules)}:entity=${normalizedEntityId}`
+}
+
+function cargoQuantity(item: CargoItem): bigint {
+    return BigInt(item.quantity.toString())
+}
+
+export function projectedCargoAvailableAt(
+    entity: AvailabilityInput,
+    at: Date
+): 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 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
+}
+
+// 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
+    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())
+                break
+            }
+        }
+    }
+    return new Date(readyMs)
+}
+
+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
+}

package/src/scheduling/cancel.test.ts

@@ -0,0 +1,348 @@
+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}}],
+        gatherer_lanes: [],
+        crafter_lanes: [],
+        loader_lanes: [],
+        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]}}],
+            gatherer_lanes: [],
+            crafter_lanes: [],
+            loader_lanes: [],
+            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]}}],
+            gatherer_lanes: [],
+            crafter_lanes: [],
+            loader_lanes: [],
+            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]}}],
+            gatherer_lanes: [],
+            crafter_lanes: [],
+            loader_lanes: [],
+            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]},
+                },
+            ],
+            gatherer_lanes: [],
+            crafter_lanes: [],
+            loader_lanes: [],
+            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]}},
+            ],
+            gatherer_lanes: [],
+            crafter_lanes: [],
+            loader_lanes: [],
+            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]}},
+            ],
+            gatherer_lanes: [],
+            crafter_lanes: [],
+            loader_lanes: [],
+            holds: [],
+        })
+        expect(cancelEligibility(e, 1, 0, {now: upcoming}).blockedReason).toBe(
+            CancelBlockReason.WOULD_STRAND
+        )
+    })
+})