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

package/src/scheduling/cancel.ts

@@ -0,0 +1,254 @@
+import type {ServerContract} from '../contracts'
+import {HoldKind, TaskCancelable, TaskType} from '../types'
+import {calcCargoItemMass} from '../capabilities/storage'
+import {
+    taskCargoEffect,
+    cargoKey,
+    isIncomingCouplingKind,
+    type IncomingSource,
+} 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_STRAND_COUNTERPART = 'WOULD_STRAND_COUNTERPART',
+    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
+    blockedByCounterpart?: EntityRef
+    range: {count: number; taskIndices: number[]}
+    effects: CancelEffects
+}
+export interface CancelEligibilityInput {
+    now: Date
+    counterparts?: Map<string, EntityInfo>
+    counterpartIncoming?: Map<string, readonly IncomingSource[]>
+}
+
+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
+}
+
+// C1: every pending consumer keeps its inputs covered by on-hand + own-lane producers strictly-before + incoming strictly-before.
+function queueFeasible(entity: EntityInfo, incoming: readonly IncomingSource[] = []): boolean {
+    const ordered = schedule.orderedTasks(entity as unknown as Projectable)
+    const base = new Map<string, number>()
+    for (const c of entity.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 ||
+        t.type.toNumber() === TaskType.UPGRADE
+    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 src of incoming) {
+            if (src.until.getTime() >= self.completesAt.getTime()) continue
+            for (const item of src.items) {
+                map.set(cargoKey(item), (map.get(cargoKey(item)) ?? 0) + item.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
+        }
+    }
+    return true
+}
+
+function feasibleAfterCancel(post: EntityInfo): boolean {
+    if (!queueFeasible(post)) 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)
+
+    // cross-entity C1: a counterpart losing this delivery must still feed its own queued consumers.
+    const releasedByCounterpart = new Map<string, {counterpart: EntityRef; holdIds: Set<string>}>()
+    for (const i of taskIndices) {
+        for (const c of tasks[i].couplings ?? []) {
+            if (!isIncomingCouplingKind(c.kind.toNumber())) continue
+            const id = c.counterpart.entity_id.toString()
+            const entry = releasedByCounterpart.get(id) ?? {
+                counterpart: c.counterpart,
+                holdIds: new Set<string>(),
+            }
+            entry.holdIds.add(c.hold.toString())
+            releasedByCounterpart.set(id, entry)
+        }
+    }
+    for (const [counterpartId, released] of releasedByCounterpart) {
+        const counterpart = input.counterparts?.get(counterpartId)
+        if (!counterpart) continue
+        const incoming = (input.counterpartIncoming?.get(counterpartId) ?? []).filter(
+            (src) => !released.holdIds.has(src.holdId)
+        )
+        if (!queueFeasible(counterpart, incoming)) {
+            return {
+                ok: false,
+                blockedReason: CancelBlockReason.WOULD_STRAND_COUNTERPART,
+                blockedByCounterpart: released.counterpart,
+                range,
+                effects: {...EMPTY_EFFECTS},
+            }
+        }
+    }
+
+    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.couplings.length > 0)
+            effects.keepsPlotDeposits = {plot: t.couplings[0].counterpart}
+        for (const c of t.couplings) {
+            const kind = c.kind.toNumber()
+            effects.releasedHolds.push({counterpart: c.counterpart, kind})
+            if (kind === HoldKind.PULL) {
+                effects.refunds.push({giver: c.counterpart, cargo: t.cargo})
+                const giver = input.counterparts?.get(c.counterpart.entity_id.toString())
+                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/cluster-stock.test.ts

@@ -0,0 +1,31 @@
+import {describe, expect, test} from 'bun:test'
+import {ServerContract, TaskType} from '../index-module'
+import {availableForItem} from './availability'
+import {clusterStockAvailable} from './cluster-stock'
+
+const AT = new Date('2026-06-19T00:00:00')
+
+function cargoItem(itemId: number, stats: number, quantity: number) {
+    return ServerContract.Types.cargo_item.from({item_id: itemId, stats, modules: [], quantity})
+}
+
+function member(cargo: ReturnType<typeof cargoItem>[]) {
+    return {cargo, tasks: [], lanes: []} as unknown as Parameters<
+        typeof clusterStockAvailable
+    >[0][number]
+}
+
+describe('clusterStockAvailable', () => {
+    test('sums the same item split across two members', () => {
+        const stock = clusterStockAvailable(
+            [member([cargoItem(1001, 0, 30)]), member([cargoItem(1001, 0, 20)])],
+            AT
+        )
+        expect(availableForItem(stock, 1001)).toBe(50n)
+    })
+
+    test('an empty cluster yields nothing', () => {
+        const stock = clusterStockAvailable([], AT)
+        expect(availableForItem(stock, 1001)).toBe(0n)
+    })
+})

package/src/scheduling/cluster-stock.ts

@@ -0,0 +1,15 @@
+import {type AvailabilityInput, projectedCargoAvailableAt} from './availability'
+
+// Union of every cluster member's present available cargo (present-only; incoming/future not credited).
+export function clusterStockAvailable(
+    members: readonly AvailabilityInput[],
+    at: Date
+): Map<string, bigint> {
+    const total = new Map<string, bigint>()
+    for (const member of members) {
+        for (const [key, qty] of projectedCargoAvailableAt(member, at)) {
+            total.set(key, (total.get(key) ?? 0n) + qty)
+        }
+    }
+    return total
+}

package/src/scheduling/energy.ts

@@ -0,0 +1,47 @@
+import {TaskType} from '../types'
+import {createProjectedEntity, type Projectable} from './projection'
+import {orderedTasks} from './schedule'
+
+export function energyAtTime(entity: Projectable, now: Date): number {
+    const projected = createProjectedEntity(entity)
+    const capacity = projected.generator ? Number(projected.generator.capacity) : undefined
+
+    const clamp = (value: number): number => {
+        const floored = Math.max(0, value)
+        return capacity !== undefined ? Math.min(capacity, floored) : floored
+    }
+
+    let running = Number(projected.energy)
+
+    const ordered = orderedTasks(entity)
+    if (ordered.length === 0) return clamp(running)
+
+    const nowMs = now.getTime()
+
+    for (const {task, startsAt} of ordered) {
+        const duration = task.duration.toNumber()
+        const elapsed = Math.min(
+            Math.max(0, Math.floor((nowMs - startsAt.getTime()) / 1000)),
+            duration
+        )
+        const complete = elapsed >= duration
+        const inProgress = !complete && elapsed > 0 && elapsed < duration
+
+        if (!complete && !inProgress) continue
+
+        const fraction = complete ? 1 : duration === 0 ? 1 : elapsed / duration
+
+        if (task.type.toNumber() === TaskType.RECHARGE) {
+            if (capacity !== undefined) {
+                running = complete ? capacity : running + (capacity - running) * fraction
+            }
+        } else {
+            const cost = Number(task.energy_cost ?? 0)
+            running -= cost * fraction
+        }
+
+        running = clamp(running)
+    }
+
+    return clamp(running)
+}

package/src/scheduling/epoch.ts

@@ -10,6 +10,7 @@ export interface EpochInfo {
 export function getCurrentEpoch(game: PlatformContract.Types.game_row): UInt64 {
     const current = new Date().getTime()
     const difference = (current - game.config.start.toMilliseconds()) / 1000
+    if (difference < 0) return UInt64.from(0)
     const epoch = Math.floor(difference / Number(game.config.epochtime)) + 1
     return UInt64.from(epoch)
 }

package/src/scheduling/idle-resolve.ts

@@ -0,0 +1,45 @@
+import type {Action, UInt64} from '@wharfkit/antelope'
+import type {ServerContract} from '../contracts'
+import type {ActionsManager} from '../managers/actions'
+import {hasResolvable, type ScheduleData} from './schedule'
+
+type EntityInfo = ServerContract.Types.entity_info
+
+export type CounterpartLookup = (entityId: UInt64) => EntityInfo | undefined
+
+export type IdleResolveTarget = ScheduleData & {id: UInt64}
+
+// A hold's driving task lives on its counterpart, so a hold resolves the counterpart, never the blocker.
+export function composeIdleResolve(
+    blocker: IdleResolveTarget,
+    action: Action,
+    actions: ActionsManager,
+    now: Date,
+    lookupCounterpart?: CounterpartLookup
+): Action[] {
+    const ids: UInt64[] = []
+    const seen = new Set<string>()
+
+    const add = (id: UInt64) => {
+        const key = id.toString()
+        if (seen.has(key)) return
+        seen.add(key)
+        ids.push(id)
+    }
+
+    if (hasResolvable(blocker, now)) {
+        add(blocker.id)
+    }
+
+    // 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)
+        }
+    }
+
+    return [...ids.map((id) => actions.resolve(id)), action]
+}

package/src/scheduling/jobs.test.ts

@@ -0,0 +1,49 @@
+import {describe, expect, it} from 'bun:test'
+import {jobStatus, jobStatusLabel, splitJobCargo} from './jobs'
+
+const at = (s: string) => new Date(s)
+
+describe('jobStatus', () => {
+    const job = {startsAt: at('2026-07-26T10:00:00Z'), completesAt: at('2026-07-26T11:00:00Z')}
+    it('is waiting before startsAt', () => {
+        expect(jobStatus(job, at('2026-07-26T09:59:59Z'))).toBe('waiting')
+    })
+    it('is crafting between startsAt and completesAt', () => {
+        expect(jobStatus(job, at('2026-07-26T10:30:00Z'))).toBe('crafting')
+    })
+    it('is ready at or after completesAt', () => {
+        expect(jobStatus(job, at('2026-07-26T11:00:00Z'))).toBe('ready')
+        expect(jobStatus(job, at('2026-07-26T12:00:00Z'))).toBe('ready')
+    })
+    it('is inline while the drop-off is still in the air', () => {
+        const booked = {
+            startsAt: at('1970-01-01T00:00:00Z'),
+            completesAt: at('1970-01-01T00:00:00Z'),
+        }
+        expect(jobStatus({...booked, deposited: false}, at('2026-07-26T10:00:00Z'))).toBe('inline')
+        expect(jobStatus({...job, deposited: true}, at('2026-07-26T10:30:00Z'))).toBe('crafting')
+    })
+    it('labels every state', () => {
+        expect(jobStatusLabel('inline')).toBe('In Line')
+        expect(jobStatusLabel('ready')).toBe('Ready for Pickup')
+    })
+})
+
+describe('splitJobCargo', () => {
+    it('reads an In Line row as inputs with no output', () => {
+        const cargo = [{n: 'a'}, {n: 'b'}] as unknown as Parameters<typeof splitJobCargo>[0]
+        const {output, inputs} = splitJobCargo(cargo, false)
+        expect(output).toBeNull()
+        expect(inputs).toEqual([{n: 'a'}, {n: 'b'}] as never)
+    })
+    it('reads a landed row as the output with no inputs', () => {
+        const cargo = [{n: 'out'}] as unknown as Parameters<typeof splitJobCargo>[0]
+        const {output, inputs} = splitJobCargo(cargo, true)
+        expect(output).toEqual({n: 'out'} as never)
+        expect(inputs).toEqual([] as never)
+    })
+    it('returns null output for empty cargo', () => {
+        expect(splitJobCargo([], true)).toEqual({output: null, inputs: []})
+        expect(splitJobCargo([], false)).toEqual({output: null, inputs: []})
+    })
+})

package/src/scheduling/jobs.ts

@@ -0,0 +1,137 @@
+import type {ServerContract} from '../contracts'
+
+type CargoItem = ServerContract.Types.cargo_item
+
+export interface JobWindow {
+    id: number
+    socket: number
+    owner: string
+    startsAt: Date
+    completesAt: Date
+    recipeId: number
+    quantity: number
+    /** False while the job is In Line: booked, with its inputs still in transit to the building. */
+    deposited: boolean
+    /** Packed stat roll of the job's output, when the source carried the job's cargo. */
+    outputStats?: bigint
+}
+
+export interface JobLaneEntry {
+    kind: 'idle' | 'job'
+    startsAt: Date
+    completesAt: Date
+    job?: JobWindow
+}
+
+export interface JobLane {
+    socket: number
+    entries: JobLaneEntry[]
+}
+
+export const JOB_QUEUE_CAP = 25
+
+function activeOn(jobs: JobWindow[], socket: number, now: Date): JobWindow[] {
+    return jobs
+        .filter((j) => j.socket === socket && j.completesAt > now)
+        .sort((a, b) => a.startsAt.getTime() - b.startsAt.getTime())
+}
+
+export function jobsToLanes(jobs: JobWindow[], socketCount: number, now: Date): JobLane[] {
+    const lanes: JobLane[] = []
+    for (let socket = 0; socket < socketCount; socket++) {
+        const entries: JobLaneEntry[] = []
+        let cursor: Date | null = null
+        for (const j of activeOn(jobs, socket, now)) {
+            if (cursor && j.startsAt > cursor) {
+                entries.push({kind: 'idle', startsAt: cursor, completesAt: j.startsAt})
+            }
+            entries.push({kind: 'job', startsAt: j.startsAt, completesAt: j.completesAt, job: j})
+            cursor = j.completesAt
+        }
+        lanes.push({socket, entries})
+    }
+    return lanes
+}
+
+export function socketTail(jobs: JobWindow[], socket: number, now: Date): Date {
+    const active = activeOn(jobs, socket, now)
+    const last = active[active.length - 1]
+    return last && last.completesAt > now ? last.completesAt : now
+}
+
+export function pickFabricator(
+    jobs: JobWindow[],
+    sockets: Array<{open: boolean}>,
+    durationBySocketMinutes: number[],
+    now: Date
+): {slot: number; startsAt: Date; completesAt: Date} | null {
+    let best: {slot: number; startsAt: Date; completesAt: Date} | null = null
+    for (let slot = 0; slot < sockets.length; slot++) {
+        if (!sockets[slot].open) continue
+        if (activeOn(jobs, slot, now).length >= JOB_QUEUE_CAP) continue
+        const startsAt = socketTail(jobs, slot, now)
+        const completesAt = new Date(startsAt.getTime() + durationBySocketMinutes[slot] * 60_000)
+        if (!best || completesAt < best.completesAt) {
+            best = {slot, startsAt, completesAt}
+        }
+    }
+    return best
+}
+
+export type JobStatus = 'inline' | 'waiting' | 'crafting' | 'ready'
+
+// A job In Line has no window yet, so the window alone would read it as long since ready.
+export function jobStatus(
+    job: {startsAt: Date; completesAt: Date; deposited?: boolean},
+    now: Date
+): JobStatus {
+    if (job.deposited === false) return 'inline'
+    if (now < job.startsAt) return 'waiting'
+    if (now < job.completesAt) return 'crafting'
+    return 'ready'
+}
+
+const JOB_STATUS_LABELS: Record<JobStatus, string> = {
+    inline: 'In Line',
+    waiting: 'Waiting',
+    crafting: 'Crafting',
+    ready: 'Ready for Pickup',
+}
+
+export function jobStatusLabel(status: JobStatus): string {
+    return JOB_STATUS_LABELS[status]
+}
+
+// A row written before the deposited flag existed reads as undefined; those jobs were all deposited.
+export function jobDeposited(value: unknown): boolean {
+    if (value === undefined || value === null) return true
+    return Boolean(value)
+}
+
+// A job row holds the inputs while In Line and the output once its drop-off has landed.
+export function splitJobCargo<T>(
+    cargo: readonly T[],
+    deposited: boolean
+): {output: T | null; inputs: T[]} {
+    if (cargo.length === 0) return {output: null, inputs: []}
+    if (!deposited) return {output: null, inputs: [...cargo]}
+    return {output: cargo[0], inputs: []}
+}
+
+export interface OwnedJob {
+    id: number
+    building: number
+    socket: number
+    shipId: number
+    coords: {x: number; y: number}
+    startsAt: Date
+    completesAt: Date
+    recipeId: number
+    quantity: number
+    status: JobStatus
+    deposited: boolean
+    output: CargoItem | null
+    inputs: CargoItem[]
+    /** Packed stat roll of `output`, so every job shape answers this the same way. */
+    outputStats?: bigint
+}