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

package/src/influence/charters.test.ts

@@ -0,0 +1,112 @@
+import {describe, expect, test} from 'bun:test'
+import {
+    CHARTER_NONE,
+    CIVIC_DEPOT,
+    CIVIC_DOCK,
+    CIVIC_STAT_CRAFT_SPEED,
+    CIVIC_STAT_TRANSFER_SPEED,
+    CIVIC_WORKSHOP,
+} from './constants'
+import {
+    charterEligible,
+    charterIneligible,
+    charterNode,
+    charterBuildingEntity,
+    charterGateNodeFor,
+    charterRungValue,
+    charterSingletonMandate,
+    charterModuleCount,
+    eligibleCharters,
+    type BuiltCharter,
+    type CharterWorld,
+    type WorldBuilding,
+} from './charters'
+
+const WORKSHOP = 10001
+const NEXUS = 20001
+const DOCK = 30100001
+const WORKSHOP_TUNEUP = 10100201
+const DOCK_TUNEUP = 30100301
+const DEPOT = 40100001
+
+const WORKSHOP_ENTITY = 100n
+const DOCK_ENTITY = 300n
+
+function world(built: BuiltCharter[]): CharterWorld {
+    return {built}
+}
+
+function node(nodeId: number) {
+    const found = charterNode(nodeId)
+    if (!found) throw new Error(`registry is missing node ${nodeId}`)
+    return found
+}
+
+function eligibleIds(w: CharterWorld): number[] {
+    return eligibleCharters(w).map((n) => n.nodeId)
+}
+
+describe('charter eligibility mirror', () => {
+    test('an unbuilt world offers only the root', () => {
+        expect(eligibleIds(world([]))).toEqual([WORKSHOP])
+    })
+
+    test('the root is the mandate by the singleton rule with no ballot', () => {
+        expect(charterSingletonMandate(world([]))).toBe(WORKSHOP)
+    })
+
+    test('completing the root opens the fork and closes the singleton path', () => {
+        const built = world([{nodeId: WORKSHOP, repeats: 0}])
+        expect(eligibleIds(built)).toEqual([WORKSHOP_TUNEUP, NEXUS, DOCK, DEPOT])
+        expect(charterSingletonMandate(built)).toBe(CHARTER_NONE)
+    })
+
+    test('a completed charter reports already-taken', () => {
+        const built = world([{nodeId: WORKSHOP, repeats: 0}])
+        expect(charterIneligible(built, node(WORKSHOP))).toBe('already-taken')
+    })
+
+    test('an unmet prereq reports prereq-missing', () => {
+        expect(charterIneligible(world([]), node(NEXUS))).toBe('prereq-missing')
+        expect(charterIneligible(world([]), node(DOCK_TUNEUP))).toBe('prereq-missing')
+    })
+
+    test('a rung is eligible as soon as its prereq is complete', () => {
+        const built = world([{nodeId: WORKSHOP, repeats: 0}])
+        expect(charterEligible(built, node(WORKSHOP_TUNEUP))).toBe(true)
+    })
+
+    test('a level gate is the node that creates its building', () => {
+        expect(charterGateNodeFor(CIVIC_WORKSHOP)?.nodeId).toBe(WORKSHOP)
+        expect(charterGateNodeFor(CIVIC_DOCK)?.nodeId).toBe(DOCK)
+        expect(charterGateNodeFor(CIVIC_DEPOT)?.nodeId).toBe(DEPOT)
+        expect(charterGateNodeFor(99)).toBeUndefined()
+    })
+
+    test('a building resolves to the entity recorded for its kind', () => {
+        const buildings: WorldBuilding[] = [
+            {entityId: WORKSHOP_ENTITY, building: CIVIC_WORKSHOP},
+            {entityId: DOCK_ENTITY, building: CIVIC_DOCK},
+        ]
+        expect(charterBuildingEntity(buildings, CIVIC_WORKSHOP)).toBe(WORKSHOP_ENTITY)
+        expect(charterBuildingEntity(buildings, CIVIC_DEPOT)).toBe(0n)
+        expect(charterBuildingEntity([], CIVIC_DEPOT)).toBe(0n)
+    })
+
+    test('rung values sum over the completed nodes only', () => {
+        const gateOnly = world([{nodeId: WORKSHOP, repeats: 0}])
+        expect(charterRungValue(gateOnly, CIVIC_WORKSHOP, CIVIC_STAT_CRAFT_SPEED)).toBe(200)
+
+        const tuned = world([
+            {nodeId: WORKSHOP, repeats: 0},
+            {nodeId: WORKSHOP_TUNEUP, repeats: 0},
+        ])
+        expect(charterRungValue(tuned, CIVIC_WORKSHOP, CIVIC_STAT_CRAFT_SPEED)).toBe(250)
+        expect(charterRungValue(tuned, CIVIC_DEPOT, CIVIC_STAT_TRANSFER_SPEED)).toBe(0)
+    })
+
+    test('modules sum over the completed nodes only', () => {
+        expect(charterModuleCount(world([]), CIVIC_WORKSHOP)).toBe(0)
+        expect(charterModuleCount(world([{nodeId: WORKSHOP, repeats: 0}]), CIVIC_WORKSHOP)).toBe(5)
+    })
+})

package/src/influence/charters.ts

@@ -0,0 +1,150 @@
+import chartersJson from '../data/charters.json'
+import {
+    CHARTER_NONE,
+    CIVIC_GRANT_LEVEL_GATE,
+    CIVIC_GRANT_MODULE,
+    CIVIC_GRANT_RUNG,
+} from './constants'
+
+export interface CharterGrant {
+    kind: number
+    building: number
+    stat: number
+    value: number
+}
+
+export interface CharterNode {
+    nodeId: number
+    cost: bigint
+    prereqs: number[]
+    grants: CharterGrant[]
+    exclusionGroup: number
+    repeatCap: number
+}
+
+export const CHARTER_REGISTRY: CharterNode[] = chartersJson.nodes.map((node) => ({
+    nodeId: node.nodeId,
+    cost: BigInt(node.cost),
+    prereqs: [...node.prereqs],
+    grants: node.grants.map((grant) => ({...grant})),
+    exclusionGroup: node.exclusionGroup,
+    repeatCap: node.repeatCap,
+}))
+
+export function charterNode(nodeId: number): CharterNode | undefined {
+    if (nodeId === CHARTER_NONE) return undefined
+    return CHARTER_REGISTRY.find((n) => n.nodeId === nodeId)
+}
+
+export type CharterIneligibility = 'already-taken' | 'prereq-missing'
+
+export const CHARTER_INELIGIBILITY_MESSAGES: Record<CharterIneligibility, string> = {
+    'already-taken': 'charter is already completed at this world',
+    'prereq-missing': 'charter prerequisites are not completed',
+}
+
+export interface BuiltCharter {
+    nodeId: number
+    repeats: number
+}
+
+export interface CharterWorld {
+    built: BuiltCharter[]
+}
+
+export interface WorldBuilding {
+    entityId: bigint
+    building: number
+}
+
+function builtCharter(world: CharterWorld, nodeId: number): BuiltCharter | undefined {
+    return world.built.find((row) => row.nodeId === nodeId)
+}
+
+export function charterGateNodeFor(building: number, level: number = 1): CharterNode | undefined {
+    return CHARTER_REGISTRY.find((node) =>
+        node.grants.some(
+            (grant) =>
+                grant.kind === CIVIC_GRANT_LEVEL_GATE &&
+                grant.building === building &&
+                grant.value === level
+        )
+    )
+}
+
+export function charterBuildingEntity(buildings: WorldBuilding[], building: number): bigint {
+    const record = buildings.find((row) => row.building === building)
+    return record ? record.entityId : 0n
+}
+
+export function charterRungValue(world: CharterWorld, building: number, stat: number): number {
+    let total = 0
+    for (const node of CHARTER_REGISTRY) {
+        if (builtCharter(world, node.nodeId) === undefined) continue
+        for (const grant of node.grants) {
+            if (grant.kind !== CIVIC_GRANT_RUNG) continue
+            if (grant.building !== building || grant.stat !== stat) continue
+            total += grant.value
+        }
+    }
+    return total
+}
+
+export function charterModuleCount(world: CharterWorld, building: number): number {
+    let total = 0
+    for (const node of CHARTER_REGISTRY) {
+        if (builtCharter(world, node.nodeId) === undefined) continue
+        for (const grant of node.grants) {
+            if (grant.kind !== CIVIC_GRANT_MODULE) continue
+            if (grant.building !== building) continue
+            total += grant.value
+        }
+    }
+    return total
+}
+
+export function charterPrereqsMet(world: CharterWorld, node: CharterNode): boolean {
+    return node.prereqs.every(
+        (prereq) => prereq === CHARTER_NONE || builtCharter(world, prereq) !== undefined
+    )
+}
+
+export function charterIneligible(
+    world: CharterWorld,
+    node: CharterNode
+): CharterIneligibility | undefined {
+    if (builtCharter(world, node.nodeId) !== undefined) return 'already-taken'
+    if (!charterPrereqsMet(world, node)) return 'prereq-missing'
+    return undefined
+}
+
+export function charterEligible(world: CharterWorld, node: CharterNode): boolean {
+    return charterIneligible(world, node) === undefined
+}
+
+export function eligibleCharters(world: CharterWorld): CharterNode[] {
+    return CHARTER_REGISTRY.filter((node) => charterEligible(world, node))
+}
+
+export function charterSingletonMandate(world: CharterWorld): number {
+    let only = CHARTER_NONE
+    for (const node of CHARTER_REGISTRY) {
+        if (!charterEligible(world, node)) continue
+        if (only !== CHARTER_NONE) return CHARTER_NONE
+        only = node.nodeId
+    }
+    return only
+}
+
+export function charterEligibleChained(
+    world: CharterWorld,
+    node: CharterNode,
+    seated: number[]
+): boolean {
+    if (builtCharter(world, node.nodeId) !== undefined || seated.includes(node.nodeId)) return false
+    for (const prereq of node.prereqs) {
+        if (prereq === CHARTER_NONE) continue
+        if (builtCharter(world, prereq) === undefined && !seated.includes(prereq)) return false
+    }
+    return true
+}

package/src/influence/citizenry.ts

@@ -0,0 +1,38 @@
+import {Checksum256, type Checksum256Type} from '@wharfkit/antelope'
+import {Coordinates, type CoordinatesType, LocationType} from '../types'
+import {hash512, uint16} from '../utils/hash'
+import {deriveLocationStatic, getSystemName} from '../utils/system'
+import citizenryAdjectives from '../data/citizenry-adjectives.json'
+import citizenryNouns from '../data/citizenry-nouns.json'
+
+const CITIZENRY_FORMS: ((world: string, noun: string, adjective: string) => string)[] = [
+    (w, n) => `${w} ${n}`,
+    (w, n, a) => `${a} ${w} ${n}`,
+    (w, n, a) => `${a} ${n} of ${w}`,
+]
+
+const FORMS_WITH_ADJECTIVE = 2
+
+export function citizenryName(
+    gameSeed: Checksum256Type,
+    coordinates: CoordinatesType
+): string | undefined {
+    const coords = Coordinates.from(coordinates)
+    const location = deriveLocationStatic(gameSeed, coords)
+    if (Number(location.type) !== LocationType.PLANET) return undefined
+
+    const world = getSystemName(gameSeed, coords)
+    const roll = hash512(
+        Checksum256.from(gameSeed),
+        `citizenry-${coords.x.toString()}-${coords.y.toString()}`
+    )
+    const form = CITIZENRY_FORMS[roll.array[0] % CITIZENRY_FORMS.length]
+    const noun = citizenryNouns[uint16(roll, 1) % citizenryNouns.length]
+    const adjective = citizenryAdjectives[uint16(roll, 3) % citizenryAdjectives.length]
+    return form(world, noun, adjective)
+}
+
+export function citizenryPatternCount(): number {
+    const plainForms = CITIZENRY_FORMS.length - FORMS_WITH_ADJECTIVE
+    return citizenryNouns.length * (plainForms + FORMS_WITH_ADJECTIVE * citizenryAdjectives.length)
+}

package/src/influence/civic-shuttle.test.ts

@@ -0,0 +1,202 @@
+import {UInt8, UInt16, UInt32, UInt64} from '@wharfkit/antelope'
+import {expect, test} from 'bun:test'
+import type {ServerContract} from '../contracts'
+import {encodeStats} from '../derivation/crafting'
+import {ITEM_DEPOT_T1_PACKED, ITEM_LOADER_T1, ITEM_STORAGE_T1} from '../data/item-ids'
+import {JOB_QUEUE_CAP} from '../scheduling/jobs'
+import {HoldKind, TaskType} from '../types'
+import {
+    civicShuttleBays,
+    civicTransfersAtCap,
+    civicTransfersFrom,
+    pendingCivicTransfers,
+    selectCivicShuttleBay,
+    CIVIC_TRANSFER_PER_PLAYER_CAP,
+} from './civic-shuttle'
+
+type Lane = ServerContract.Types.lane
+type ModuleEntry = ServerContract.Types.module_entry
+type Task = ServerContract.Types.task
+
+const T0 = new Date('2026-01-01T00:00:00.000Z')
+const loaderStats = encodeStats([300, 500])
+const storageStats = encodeStats([300, 300])
+
+function makeModuleEntry(itemId: number, stats: bigint): ModuleEntry {
+    return {
+        type: UInt8.from(0),
+        installed: {item_id: UInt16.from(itemId), stats: UInt64.from(stats)},
+    } as unknown as ModuleEntry
+}
+
+// The live Depot layout: two loader bays then four storage.
+function depotModules(): ModuleEntry[] {
+    return [
+        makeModuleEntry(ITEM_LOADER_T1, loaderStats),
+        makeModuleEntry(ITEM_LOADER_T1, loaderStats),
+        makeModuleEntry(ITEM_STORAGE_T1, storageStats),
+        makeModuleEntry(ITEM_STORAGE_T1, storageStats),
+        makeModuleEntry(ITEM_STORAGE_T1, storageStats),
+        makeModuleEntry(ITEM_STORAGE_T1, storageStats),
+    ]
+}
+
+function shuttleTask(senderId: number, receiverId: number, group?: number): Task {
+    return {
+        type: UInt8.from(TaskType.SHUTTLE),
+        duration: UInt32.from(60),
+        cancelable: UInt8.from(2),
+        cargo: [],
+        couplings: [
+            {
+                counterpart: {entity_id: UInt64.from(senderId), entity_type: UInt8.from(1)},
+                hold: UInt64.from(1),
+                kind: UInt8.from(HoldKind.PULL),
+            },
+            {
+                counterpart: {entity_id: UInt64.from(receiverId), entity_type: UInt8.from(1)},
+                hold: UInt64.from(1),
+                kind: UInt8.from(HoldKind.PUSH),
+            },
+        ],
+        entitygroup: group === undefined ? undefined : UInt64.from(group),
+    } as unknown as Task
+}
+
+function makeLane(laneKey: number, tasks: Task[]): Lane {
+    return {
+        lane_key: UInt8.from(laneKey),
+        schedule: {started: {toDate: () => T0}, tasks},
+    } as unknown as Lane
+}
+
+test('civicShuttleBays lists both Depot bays with their queue depth', () => {
+    const lanes = [makeLane(1, [shuttleTask(20, 21)])]
+    const bays = civicShuttleBays(depotModules(), ITEM_DEPOT_T1_PACKED, lanes, T0)
+    expect(bays.map((b) => b.laneKey)).toEqual([1, 2])
+    expect(bays.map((b) => b.slotIndex)).toEqual([0, 1])
+    expect(bays[0].queued).toBe(1)
+    expect(bays[1].queued).toBe(0)
+    expect(bays.every((b) => !b.full)).toBe(true)
+    expect(bays.every((b) => b.thrust > 0 && b.mass > 0)).toBe(true)
+})
+
+test('a bay is full at the job queue cap', () => {
+    const filled = Array.from({length: JOB_QUEUE_CAP}, () => shuttleTask(20, 21))
+    const bays = civicShuttleBays(depotModules(), ITEM_DEPOT_T1_PACKED, [makeLane(1, filled)], T0)
+    expect(bays[0].full).toBe(true)
+    expect(bays[1].full).toBe(false)
+})
+
+const AFTER = new Date(T0.getTime() + 3_600_000)
+
+test('a landed booking leaves the bay free, since booking clears it', () => {
+    const filled = Array.from({length: JOB_QUEUE_CAP}, () => shuttleTask(20, 21))
+    const lanes = [makeLane(1, filled)]
+    const bays = civicShuttleBays(depotModules(), ITEM_DEPOT_T1_PACKED, lanes, AFTER)
+    expect(bays[0].queued).toBe(0)
+    expect(bays[0].full).toBe(false)
+    expect(selectCivicShuttleBay(depotModules(), ITEM_DEPOT_T1_PACKED, lanes, AFTER)?.laneKey).toBe(
+        1
+    )
+})
+
+test('a bay part-way through its queue counts only what is still unfinished', () => {
+    const lanes = [makeLane(1, [shuttleTask(20, 21), shuttleTask(22, 23), shuttleTask(24, 25)])]
+    const bays = civicShuttleBays(
+        depotModules(),
+        ITEM_DEPOT_T1_PACKED,
+        lanes,
+        new Date(T0.getTime() + 90_000)
+    )
+    expect(bays[0].queued).toBe(2)
+})
+
+test('a landed transfer is listed for settling but is not callable', () => {
+    const lanes = [makeLane(1, [shuttleTask(20, 21)])]
+    const [transfer] = pendingCivicTransfers({lanes} as never, AFTER)
+    expect(transfer.isTail).toBe(true)
+    expect(transfer.complete).toBe(true)
+    expect(transfer.callable).toBe(false)
+})
+
+test('landed transfers do not count against the per-player cap', () => {
+    const mine = Array.from({length: CIVIC_TRANSFER_PER_PLAYER_CAP}, (_, i) =>
+        shuttleTask(20 + i, 50)
+    )
+    const senderIds = mine.map((_, i) => 20 + i)
+    const at = {lanes: [makeLane(1, mine)]} as never
+    expect(civicTransfersAtCap(at, senderIds, T0)).toBe(true)
+    expect(civicTransfersAtCap(at, senderIds, AFTER)).toBe(false)
+    expect(civicTransfersFrom(at, senderIds, AFTER).length).toBe(CIVIC_TRANSFER_PER_PLAYER_CAP)
+})
+
+test('selectCivicShuttleBay takes the first free bay, then the lowest occupied one', () => {
+    const modules = depotModules()
+    expect(selectCivicShuttleBay(modules, ITEM_DEPOT_T1_PACKED, [], T0)?.laneKey).toBe(1)
+
+    const firstBusy = [makeLane(1, [shuttleTask(20, 21)])]
+    expect(selectCivicShuttleBay(modules, ITEM_DEPOT_T1_PACKED, firstBusy, T0)?.laneKey).toBe(2)
+
+    const bothBusy = [makeLane(1, [shuttleTask(20, 21)]), makeLane(2, [shuttleTask(22, 23)])]
+    expect(selectCivicShuttleBay(modules, ITEM_DEPOT_T1_PACKED, bothBusy, T0)?.laneKey).toBe(1)
+})
+
+test('selectCivicShuttleBay returns nothing when the building has no loaders', () => {
+    const modules = [makeModuleEntry(ITEM_STORAGE_T1, storageStats)]
+    expect(selectCivicShuttleBay(modules, ITEM_DEPOT_T1_PACKED, [], T0)).toBeUndefined()
+})
+
+test('pendingCivicTransfers reports the bay, both counterparties, and the tail', () => {
+    const lanes = [
+        makeLane(1, [shuttleTask(20, 21), shuttleTask(22, 23)]),
+        makeLane(2, [shuttleTask(24, 25)]),
+    ]
+    const transfers = pendingCivicTransfers({lanes} as never, T0)
+    expect(transfers.length).toBe(3)
+
+    const first = transfers.find((t) => String(t.senderId) === '20')!
+    expect(first.laneKey).toBe(1)
+    expect(String(first.receiverId)).toBe('21')
+    expect(first.isTail).toBe(false)
+    expect(first.callable).toBe(false)
+    expect(first.startsAt).toEqual(T0)
+    expect(first.completesAt).toEqual(new Date(T0.getTime() + 60_000))
+
+    const second = transfers.find((t) => String(t.senderId) === '22')!
+    expect(second.isTail).toBe(true)
+    expect(second.callable).toBe(true)
+
+    const onBayTwo = transfers.find((t) => String(t.senderId) === '24')!
+    expect(onBayTwo.laneKey).toBe(2)
+    expect(onBayTwo.callable).toBe(true)
+})
+
+test('a grouped tail transfer is not callable', () => {
+    const lanes = [makeLane(1, [shuttleTask(20, 21, 7)])]
+    const [transfer] = pendingCivicTransfers({lanes} as never, T0)
+    expect(transfer.isTail).toBe(true)
+    expect(transfer.callable).toBe(false)
+})
+
+test('civicTransfersFrom counts only the ships a player sends from', () => {
+    const lanes = [
+        makeLane(1, [shuttleTask(20, 21), shuttleTask(30, 31)]),
+        makeLane(2, [shuttleTask(22, 23)]),
+    ]
+    const entity = {lanes} as never
+    expect(civicTransfersFrom(entity, [20, 22], T0).length).toBe(2)
+    expect(civicTransfersFrom(entity, [30], T0).length).toBe(1)
+    expect(civicTransfersFrom(entity, [99], T0).length).toBe(0)
+})
+
+test('civicTransfersAtCap trips at the per-player cap', () => {
+    const mine = Array.from({length: CIVIC_TRANSFER_PER_PLAYER_CAP}, (_, i) =>
+        shuttleTask(20 + i, 50)
+    )
+    const senderIds = mine.map((_, i) => 20 + i)
+    const under = {lanes: [makeLane(1, mine.slice(0, -1))]} as never
+    const at = {lanes: [makeLane(1, mine)]} as never
+    expect(civicTransfersAtCap(under, senderIds, T0)).toBe(false)
+    expect(civicTransfersAtCap(at, senderIds, T0)).toBe(true)
+})

package/src/influence/civic-shuttle.ts

@@ -0,0 +1,142 @@
+import type {UInt64} from '@wharfkit/antelope'
+import type {ServerContract} from '../contracts'
+import {getItem} from '../data/catalog'
+import {JOB_QUEUE_CAP} from '../scheduling/jobs'
+import {laneKeyForModule, resolveLaneLoader} from '../scheduling/lanes'
+import {orderedTasks, type ScheduleData} from '../scheduling/schedule'
+import {HoldKind, TaskType} from '../types'
+
+type CargoItem = ServerContract.Types.cargo_item
+type Lane = ServerContract.Types.lane
+type ModuleEntry = ServerContract.Types.module_entry
+
+export const CIVIC_TRANSFER_PER_PLAYER_CAP = 4
+
+export interface CivicShuttleBay {
+    laneKey: number
+    slotIndex: number
+    thrust: number
+    mass: number
+    outputPct: number
+    queued: number
+    full: boolean
+}
+
+// a landed booking clears during the next civicshuttle, so only unfinished tasks occupy a bay
+function unfinishedTasks(lane: Lane | undefined, now: Date): number {
+    if (!lane) return 0
+    const startedMs = lane.schedule.started.toDate().getTime()
+    const nowMs = now.getTime()
+    let endSec = 0
+    let count = 0
+    for (const task of lane.schedule.tasks) {
+        endSec += task.duration.toNumber()
+        if (startedMs + endSec * 1000 > nowMs) count++
+    }
+    return count
+}
+
+export function civicShuttleBays(
+    modules: ModuleEntry[],
+    entityItemId: number,
+    lanes: Lane[],
+    now: Date = new Date()
+): CivicShuttleBay[] {
+    const bays: CivicShuttleBay[] = []
+    for (let slotIndex = 0; slotIndex < modules.length; slotIndex++) {
+        const installed = modules[slotIndex].installed
+        if (!installed) continue
+        if (getItem(installed.item_id).moduleType !== 'loader') continue
+        const laneKey = laneKeyForModule(slotIndex)
+        const loader = resolveLaneLoader(modules, entityItemId, laneKey)
+        const lane = lanes.find((l) => l.lane_key.toNumber() === laneKey)
+        const queued = unfinishedTasks(lane, now)
+        bays.push({
+            laneKey,
+            slotIndex,
+            thrust: loader.thrust,
+            mass: loader.mass,
+            outputPct: loader.outputPct,
+            queued,
+            full: queued >= JOB_QUEUE_CAP,
+        })
+    }
+    return bays
+}
+
+// Mirrors worker_lane_key_or_mobility for loaders: first free bay, else the lowest bay.
+export function selectCivicShuttleBay(
+    modules: ModuleEntry[],
+    entityItemId: number,
+    lanes: Lane[],
+    now: Date = new Date()
+): CivicShuttleBay | undefined {
+    const bays = civicShuttleBays(modules, entityItemId, lanes, now)
+    return bays.find((bay) => bay.queued === 0) ?? bays[0]
+}
+
+export interface PendingCivicTransfer {
+    laneKey: number
+    taskIndex: number
+    senderId: UInt64
+    receiverId: UInt64
+    cargo: CargoItem[]
+    startsAt: Date
+    completesAt: Date
+    isTail: boolean
+    complete: boolean
+    callable: boolean
+}
+
+export function pendingCivicTransfers(
+    entity: ScheduleData,
+    now: Date = new Date()
+): PendingCivicTransfer[] {
+    const tailIndex = new Map<number, number>()
+    for (const l of entity.lanes ?? []) {
+        tailIndex.set(l.lane_key.toNumber(), l.schedule.tasks.length - 1)
+    }
+    const out: PendingCivicTransfer[] = []
+    for (const entry of orderedTasks(entity)) {
+        if (entry.task.type.toNumber() !== TaskType.SHUTTLE) continue
+        const pull = entry.task.couplings.find((c) => c.kind.toNumber() === HoldKind.PULL)
+        const push = entry.task.couplings.find((c) => c.kind.toNumber() === HoldKind.PUSH)
+        if (!pull || !push) continue
+        const isTail = tailIndex.get(entry.laneKey) === entry.taskIndex
+        const complete = entry.completesAt.getTime() <= now.getTime()
+        out.push({
+            laneKey: entry.laneKey,
+            taskIndex: entry.taskIndex,
+            senderId: pull.counterpart.entity_id,
+            receiverId: push.counterpart.entity_id,
+            cargo: entry.task.cargo,
+            startsAt: entry.startsAt,
+            completesAt: entry.completesAt,
+            isTail,
+            complete,
+            callable: isTail && !complete && !entry.task.entitygroup,
+        })
+    }
+    return out
+}
+
+// Mirrors civic_transfers_for: the sender side of every shuttle the building holds, by owner.
+export function civicTransfersFrom(
+    entity: ScheduleData,
+    senderIds: Array<UInt64 | string | number>,
+    now: Date = new Date()
+): PendingCivicTransfer[] {
+    const owned = new Set(senderIds.map((id) => String(id)))
+    return pendingCivicTransfers(entity, now).filter((t) => owned.has(String(t.senderId)))
+}
+
+export function civicTransfersAtCap(
+    entity: ScheduleData,
+    senderIds: Array<UInt64 | string | number>,
+    now: Date = new Date()
+): boolean {
+    return (
+        civicTransfersFrom(entity, senderIds, now).filter((t) => !t.complete).length >=
+        CIVIC_TRANSFER_PER_PLAYER_CAP
+    )
+}