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

package/src/influence/ballot.test.ts

@@ -0,0 +1,103 @@
+import {describe, expect, test} from 'bun:test'
+import {
+    charterEligible,
+    charterEligibleChained,
+    CHARTER_REGISTRY,
+    type CharterWorld,
+} from './charters'
+import {projectBallot} from './ballot'
+
+const NEXUS = 20001
+const DOCK = 30100001
+const WORKSHOP_TUNEUP = 10100201
+const DOCK_TUNEUP = 30100301
+const DEPOT = 40100001
+
+const world: CharterWorld = {built: [{nodeId: 10001, repeats: 0}]}
+
+describe('charterEligibleChained', () => {
+    test('with nothing seated it equals charterEligible', () => {
+        for (const node of CHARTER_REGISTRY) {
+            expect(charterEligibleChained(world, node, [])).toBe(charterEligible(world, node))
+        }
+    })
+
+    test('a seated prerequisite opens a dependent, a seated node closes itself', () => {
+        const tuneup = CHARTER_REGISTRY.find((n) => n.nodeId === DOCK_TUNEUP)!
+        expect(charterEligibleChained(world, tuneup, [])).toBe(false)
+        expect(charterEligibleChained(world, tuneup, [DOCK])).toBe(true)
+        const dock = CHARTER_REGISTRY.find((n) => n.nodeId === DOCK)!
+        expect(charterEligibleChained(world, dock, [DOCK])).toBe(false)
+    })
+})
+
+describe('projectBallot', () => {
+    const voters = [
+        {account: 'carol', weight: 9_000n, picks: [DOCK, DOCK_TUNEUP]},
+        {account: 'dave', weight: 5_000n, picks: [NEXUS, DOCK_TUNEUP]},
+        {account: 'erin', weight: 0n, picks: [NEXUS]},
+    ]
+
+    test('one seat: the heavier pick wins and the frontier carries round weights', () => {
+        const result = projectBallot({world, seats: 1, voters})
+        expect(result.seats).toEqual([{nodeId: DOCK, weight: 9_000n}])
+        const nexus = result.options.find((o) => o.nodeId === NEXUS)!
+        expect(nexus.seat).toBe(0)
+        expect(nexus.weight).toBe(5_000n)
+        const tuneup = result.options.find((o) => o.nodeId === DOCK_TUNEUP)!
+        expect(tuneup.seat).toBe(0)
+        expect(tuneup.weight).toBe(9_000n)
+        expect(result.options.find((o) => o.nodeId === 10001)).toBeUndefined()
+    })
+
+    test('two seats: the dock tune-up chains behind the dock', () => {
+        const result = projectBallot({world, seats: 2, voters})
+        expect(result.seats.map((s) => s.nodeId)).toEqual([DOCK, DOCK_TUNEUP])
+        expect(result.seats[1].weight).toBe(9_000n)
+    })
+
+    test('a tie goes to the lower option id', () => {
+        const tied = [
+            {account: 'a', weight: 100n, picks: [DOCK]},
+            {account: 'b', weight: 100n, picks: [NEXUS]},
+        ]
+        expect(projectBallot({world, seats: 1, voters: tied}).seats[0].nodeId).toBe(NEXUS)
+    })
+
+    test('a zero round ends early and an empty queue stays empty, even with one node left', () => {
+        expect(projectBallot({world, seats: 4, voters}).seats.length).toBe(3)
+        expect(projectBallot({world, seats: 1, voters: []}).seats).toEqual([])
+        const almostDone: CharterWorld = {
+            built: CHARTER_REGISTRY.filter((n) => n.nodeId !== 40100404).map((n) => ({
+                nodeId: n.nodeId,
+                repeats: 0,
+            })),
+        }
+        expect(projectBallot({world: almostDone, seats: 1, voters: []}).seats).toEqual([])
+        expect(
+            projectBallot({
+                world: almostDone,
+                seats: 1,
+                voters: [{account: 'a', weight: 5n, picks: [40100404]}],
+            }).seats
+        ).toEqual([{nodeId: 40100404, weight: 5n}])
+    })
+
+    test('the caller picks are ranked on the options', () => {
+        const result = projectBallot({world, seats: 1, voters, picks: [NEXUS, DOCK]})
+        expect(result.options.find((o) => o.nodeId === NEXUS)!.rank).toBe(1)
+        expect(result.options.find((o) => o.nodeId === DOCK)!.rank).toBe(2)
+        expect(result.options.find((o) => o.nodeId === WORKSHOP_TUNEUP)!.rank).toBe(0)
+    })
+
+    test('a pick slot is consumed by the first eligible option regardless of the voter weight behind it', () => {
+        const scenario = [
+            {account: 'grace', weight: 50n, picks: [NEXUS, DEPOT]},
+            {account: 'frank', weight: 45n, picks: [DEPOT]},
+            {account: 'erin', weight: 0n, picks: [NEXUS, DEPOT]},
+        ]
+        expect(projectBallot({world, seats: 1, voters: scenario}).seats).toEqual([
+            {nodeId: NEXUS, weight: 50n},
+        ])
+    })
+})

package/src/influence/ballot.ts

@@ -0,0 +1,98 @@
+import {CHARTER_REGISTRY, charterEligibleChained, type CharterWorld} from './charters'
+import {CHARTER_NONE} from './constants'
+
+export interface BallotVoter {
+    account: string
+    weight: bigint
+    picks: number[]
+}
+
+/** Projects a full settlement from scratch; it does not resume an in-flight partial round. */
+export interface BallotInput {
+    world: CharterWorld
+    seats: number
+    voters: BallotVoter[]
+    picks?: number[]
+}
+
+export interface ProjectedSeat {
+    nodeId: number
+    weight: bigint
+}
+
+export interface ProjectedOption {
+    nodeId: number
+    cost: bigint
+    seat: number
+    weight: bigint
+    rank: number
+}
+
+export interface BallotProjection {
+    seats: ProjectedSeat[]
+    options: ProjectedOption[]
+}
+
+function tallyRound(input: BallotInput, seated: number[]): Map<number, bigint> {
+    const tallies = new Map<number, bigint>()
+    for (const voter of input.voters) {
+        for (const pick of voter.picks) {
+            const node = CHARTER_REGISTRY.find((n) => n.nodeId === pick)
+            if (!node || !charterEligibleChained(input.world, node, seated)) continue
+            if (voter.weight > 0n) tallies.set(pick, (tallies.get(pick) ?? 0n) + voter.weight)
+            break
+        }
+    }
+    return tallies
+}
+
+function leader(tallies: Map<number, bigint>): ProjectedSeat | undefined {
+    let winner = CHARTER_NONE
+    let best = 0n
+    for (const [option, weight] of tallies) {
+        if (weight === 0n) continue
+        if (winner === CHARTER_NONE || weight > best || (weight === best && option < winner)) {
+            best = weight
+            winner = option
+        }
+    }
+    return winner === CHARTER_NONE ? undefined : {nodeId: winner, weight: best}
+}
+
+export function projectBallot(input: BallotInput): BallotProjection {
+    const seats: ProjectedSeat[] = []
+    while (seats.length < input.seats) {
+        const seat = leader(
+            tallyRound(
+                input,
+                seats.map((s) => s.nodeId)
+            )
+        )
+        if (!seat) break
+        seats.push(seat)
+    }
+
+    const projected = seats.map((s) => s.nodeId)
+    const next = tallyRound(input, projected)
+    const picks = input.picks ?? []
+
+    const options: ProjectedOption[] = []
+    for (const node of CHARTER_REGISTRY) {
+        const seatIndex = projected.indexOf(node.nodeId)
+        const option: ProjectedOption = {
+            nodeId: node.nodeId,
+            cost: node.cost,
+            seat: seatIndex + 1,
+            weight: 0n,
+            rank: picks.indexOf(node.nodeId) + 1,
+        }
+        if (seatIndex >= 0) {
+            option.weight = seats[seatIndex].weight
+        } else {
+            if (!charterEligibleChained(input.world, node, projected)) continue
+            option.weight = next.get(node.nodeId) ?? 0n
+        }
+        options.push(option)
+    }
+    return {seats, options}
+}

package/src/influence/categories.ts

@@ -0,0 +1,32 @@
+import {categoryFromIndex} from '../data/catalog'
+import type {ResourceCategory} from '../types'
+import {
+    RESOURCE_BIOMASS,
+    RESOURCE_CATEGORY_COUNT,
+    RESOURCE_CRYSTAL,
+    RESOURCE_GAS,
+    RESOURCE_ORE,
+    RESOURCE_REGOLITH,
+} from './constants'
+
+const INDEX_BY_CATEGORY: Record<ResourceCategory, number> = {
+    ore: RESOURCE_ORE,
+    gas: RESOURCE_GAS,
+    regolith: RESOURCE_REGOLITH,
+    biomass: RESOURCE_BIOMASS,
+    crystal: RESOURCE_CRYSTAL,
+}
+
+export function categoryIndex(category: ResourceCategory): number {
+    return INDEX_BY_CATEGORY[category]
+}
+
+export function categoryAtIndex(index: number): ResourceCategory {
+    const category = categoryFromIndex(index)
+    if (!category) throw new Error(`influence: invalid resource category index ${index}`)
+    return category
+}
+
+export function allCategoryIndexes(): number[] {
+    return Array.from({length: RESOURCE_CATEGORY_COUNT}, (_, i) => i)
+}

package/src/influence/charter-metadata.test.ts

@@ -0,0 +1,136 @@
+import {describe, expect, test} from 'bun:test'
+
+import {CHARTER_REGISTRY, type CharterNode} from './charters'
+import {
+    charterMetadata,
+    charterName,
+    charterSignature,
+    charterSummary,
+    romanNumeral,
+    type CharterSignature,
+} from './charter-metadata'
+
+function nodeById(nodeId: number): CharterNode {
+    const node = CHARTER_REGISTRY.find((candidate) => candidate.nodeId === nodeId)
+    if (!node) throw new Error(`no charter node ${nodeId} in the registry`)
+    return node
+}
+
+function signatureFor(nodeId: number): CharterSignature {
+    const signature = charterSignature(nodeById(nodeId))
+    if (!signature) throw new Error(`no signature for charter node ${nodeId}`)
+    return signature
+}
+
+function sharesWord(name: string, label: string): boolean {
+    const haystack = name.toLowerCase()
+    return label
+        .split(/\s+/)
+        .filter((word) => word.length > 2)
+        .some((word) => haystack.includes(word.toLowerCase()))
+}
+
+describe('charter metadata', () => {
+    test('covers every node in the chain-synced registry', () => {
+        const missing = CHARTER_REGISTRY.filter((node) => !charterMetadata[node.nodeId])
+        expect(missing).toEqual([])
+    })
+
+    test('carries no entry for a node the registry does not define', () => {
+        const known = new Set(CHARTER_REGISTRY.map((node) => node.nodeId))
+        const orphans = Object.keys(charterMetadata)
+            .map(Number)
+            .filter((nodeId) => !known.has(nodeId))
+        expect(orphans).toEqual([])
+    })
+
+    test('every entry has a name and a summary', () => {
+        for (const node of CHARTER_REGISTRY) {
+            expect(charterName(node.nodeId).length).toBeGreaterThan(0)
+            expect(charterSummary(node.nodeId).length).toBeGreaterThan(0)
+        }
+    })
+
+    test('falls back to a node-numbered name for an unknown id', () => {
+        expect(charterName(9999)).toBe('Charter 9999')
+        expect(charterSummary(9999)).toBe('')
+    })
+})
+
+describe('charter names agree with the grant they are derived from', () => {
+    for (const node of CHARTER_REGISTRY) {
+        const signature = signatureFor(node.nodeId)
+        const name = charterName(node.nodeId)
+
+        test(`node ${node.nodeId} names the building it grants (${signature.buildingLabel})`, () => {
+            expect(sharesWord(name, signature.buildingLabel)).toBeTrue()
+        })
+
+        if (signature.kind !== 'gate' && signature.rankCount > 1) {
+            test(`node ${node.nodeId} carries rank ${signature.rank} of ${signature.rankCount}`, () => {
+                expect(name.endsWith(` ${romanNumeral(signature.rank)}`)).toBeTrue()
+            })
+        }
+    }
+})
+
+describe('charter signatures', () => {
+    test('reads the depot level gate from its grant list', () => {
+        expect(signatureFor(40100001)).toEqual({kind: 'gate', buildingLabel: 'Depot', level: 1})
+    })
+
+    test('ranks the depot bays by their prereq chain', () => {
+        expect([40100101, 40100102, 40100103, 40100104].map(signatureFor)).toEqual(
+            [1, 2, 3, 4].map((rank) => ({
+                kind: 'module',
+                buildingLabel: 'Depot',
+                count: 1,
+                rank,
+                rankCount: 4,
+            }))
+        )
+    })
+
+    test('ranks the depot transfer rungs by their prereq chain', () => {
+        expect([40100401, 40100402, 40100403, 40100404].map(signatureFor)).toEqual([
+            {
+                kind: 'rung',
+                buildingLabel: 'Depot',
+                statLabel: 'transfer speed',
+                rank: 1,
+                rankCount: 4,
+            },
+            {
+                kind: 'rung',
+                buildingLabel: 'Depot',
+                statLabel: 'transfer speed',
+                rank: 2,
+                rankCount: 4,
+            },
+            {
+                kind: 'rung',
+                buildingLabel: 'Depot',
+                statLabel: 'transfer speed',
+                rank: 3,
+                rankCount: 4,
+            },
+            {
+                kind: 'rung',
+                buildingLabel: 'Depot',
+                statLabel: 'transfer speed',
+                rank: 4,
+                rankCount: 4,
+            },
+        ])
+    })
+
+    test('ranks the Workshop tune-ups as a four-rung ladder', () => {
+        expect(signatureFor(10100203)).toEqual({
+            kind: 'rung',
+            buildingLabel: 'Workshop',
+            statLabel: 'crafting speed',
+            rank: 3,
+            rankCount: 4,
+        })
+    })
+})

package/src/influence/charter-metadata.ts

@@ -0,0 +1,236 @@
+import {CHARTER_REGISTRY, type CharterGrant, type CharterNode} from './charters'
+import {
+    CHARTER_NONE,
+    CIVIC_DEPOT,
+    CIVIC_DOCK,
+    CIVIC_GRANT_LEVEL_GATE,
+    CIVIC_GRANT_MODULE,
+    CIVIC_GRANT_RUNG,
+    CIVIC_NEXUS,
+    CIVIC_STAT_BUILD_SPEED,
+    CIVIC_STAT_CRAFT_SPEED,
+    CIVIC_STAT_STORAGE_CAPACITY,
+    CIVIC_STAT_TRANSFER_SPEED,
+    CIVIC_WORKSHOP,
+} from './constants'
+
+const BUILDING_LABELS: Record<number, string> = {
+    [CIVIC_WORKSHOP]: 'Workshop',
+    [CIVIC_NEXUS]: 'Nexus',
+    [CIVIC_DOCK]: 'Construction Dock',
+    [CIVIC_DEPOT]: 'Depot',
+}
+
+const STAT_LABELS: Record<number, string> = {
+    [CIVIC_STAT_CRAFT_SPEED]: 'crafting speed',
+    [CIVIC_STAT_BUILD_SPEED]: 'build speed',
+    [CIVIC_STAT_TRANSFER_SPEED]: 'transfer speed',
+    [CIVIC_STAT_STORAGE_CAPACITY]: 'storage capacity',
+}
+
+export function civicBuildingLabel(building: number): string {
+    return BUILDING_LABELS[building] ?? `Building ${building}`
+}
+
+export function civicStatLabel(stat: number): string {
+    return STAT_LABELS[stat] ?? `Stat ${stat}`
+}
+
+export interface CharterMeta {
+    name: string
+    summary: string
+}
+
+export const charterMetadata: Record<number, CharterMeta> = {
+    10001: {
+        name: 'Communal Workshop',
+        summary: 'Shared crafting for anyone at this world',
+    },
+    10100201: {
+        name: 'Workshop tune-up I',
+        summary: "Raises the Workshop's Fabricator stats",
+    },
+    10100202: {
+        name: 'Workshop tune-up II',
+        summary: "Raises the Workshop's Fabricator stats",
+    },
+    10100203: {
+        name: 'Workshop tune-up III',
+        summary: "Raises the Workshop's Fabricator stats",
+    },
+    10100204: {
+        name: 'Workshop tune-up IV',
+        summary: "Raises the Workshop's Fabricator stats",
+    },
+    20001: {
+        name: 'Civic Nexus',
+        summary: 'Advances the world to Tier II; wrap items for trade and unwrap them here',
+    },
+    30100001: {
+        name: 'Construction Dock',
+        summary: 'Ships queue here for upgrades',
+    },
+    30100301: {
+        name: 'Dock tune-up I',
+        summary: "Raises the Dock's Assembly Arm stats",
+    },
+    30100302: {
+        name: 'Dock tune-up II',
+        summary: "Raises the Dock's Assembly Arm stats",
+    },
+    30100303: {
+        name: 'Dock tune-up III',
+        summary: "Raises the Dock's Assembly Arm stats",
+    },
+    30100304: {
+        name: 'Dock tune-up IV',
+        summary: "Raises the Dock's Assembly Arm stats",
+    },
+    40100001: {
+        name: 'Public Depot',
+        summary: 'Storage at this world for every player',
+    },
+    40100101: {
+        name: 'Depot Cargo Hold I',
+        summary: 'Raises what each player can keep at the depot',
+    },
+    40100102: {
+        name: 'Depot Cargo Hold II',
+        summary: 'Raises what each player can keep at the depot',
+    },
+    40100103: {
+        name: 'Depot Cargo Hold III',
+        summary: 'Raises what each player can keep at the depot',
+    },
+    40100104: {
+        name: 'Depot Cargo Hold IV',
+        summary: 'Raises what each player can keep at the depot',
+    },
+    40100401: {
+        name: 'Depot Shuttle Bay I',
+        summary: 'Moves cargo in and out of the depot faster',
+    },
+    40100402: {
+        name: 'Depot Shuttle Bay II',
+        summary: 'Moves cargo in and out of the depot faster',
+    },
+    40100403: {
+        name: 'Depot Shuttle Bay III',
+        summary: 'Moves cargo in and out of the depot faster',
+    },
+    40100404: {
+        name: 'Depot Shuttle Bay IV',
+        summary: 'Moves cargo in and out of the depot faster',
+    },
+}
+
+export function charterName(nodeId: number): string {
+    return charterMetadata[nodeId]?.name ?? `Charter ${nodeId}`
+}
+
+export function charterSummary(nodeId: number): string {
+    return charterMetadata[nodeId]?.summary ?? ''
+}
+
+export interface CharterGateSignature {
+    kind: 'gate'
+    buildingLabel: string
+    level: number
+}
+
+export interface CharterModuleSignature {
+    kind: 'module'
+    buildingLabel: string
+    count: number
+    rank: number
+    rankCount: number
+}
+
+export interface CharterRungSignature {
+    kind: 'rung'
+    buildingLabel: string
+    statLabel: string
+    rank: number
+    rankCount: number
+}
+
+export type CharterSignature = CharterGateSignature | CharterModuleSignature | CharterRungSignature
+
+const ROMAN = ['I', 'II', 'III', 'IV', 'V', 'VI', 'VII', 'VIII', 'IX', 'X']
+
+export function romanNumeral(rank: number): string {
+    return ROMAN[rank - 1] ?? String(rank)
+}
+
+function headlineGrant(node: CharterNode): CharterGrant | undefined {
+    return (
+        node.grants.find((grant) => grant.kind === CIVIC_GRANT_LEVEL_GATE) ??
+        node.grants.find((grant) => grant.kind === CIVIC_GRANT_MODULE) ??
+        node.grants.find((grant) => grant.kind === CIVIC_GRANT_RUNG)
+    )
+}
+
+function headlineSiblings(headline: CharterGrant): CharterNode[] {
+    return CHARTER_REGISTRY.filter((other) => {
+        const grant = headlineGrant(other)
+        return (
+            grant !== undefined &&
+            grant.kind === headline.kind &&
+            grant.building === headline.building &&
+            grant.stat === headline.stat
+        )
+    })
+}
+
+function rungRank(node: CharterNode, siblings: CharterNode[]): number {
+    const byId = new Map(siblings.map((sibling) => [sibling.nodeId, sibling]))
+    const seen = new Set<number>([node.nodeId])
+    let current: CharterNode | undefined = node
+    let rank = 1
+    while (current) {
+        const previousId = current.prereqs.find((id) => byId.has(id) && !seen.has(id))
+        if (previousId === undefined) return rank
+        seen.add(previousId)
+        current = byId.get(previousId)
+        rank += 1
+    }
+    return rank
+}
+
+export function charterSignature(node: CharterNode): CharterSignature | undefined {
+    const grant = headlineGrant(node)
+    if (!grant) return undefined
+    if (grant.kind === CIVIC_GRANT_LEVEL_GATE) {
+        return {
+            kind: 'gate',
+            buildingLabel: civicBuildingLabel(grant.building),
+            level: grant.value,
+        }
+    }
+    const siblings = headlineSiblings(grant)
+    if (grant.kind === CIVIC_GRANT_MODULE) {
+        return {
+            kind: 'module',
+            buildingLabel: civicBuildingLabel(grant.building),
+            count: grant.value,
+            rank: rungRank(node, siblings),
+            rankCount: siblings.length,
+        }
+    }
+    return {
+        kind: 'rung',
+        buildingLabel: civicBuildingLabel(grant.building),
+        statLabel: civicStatLabel(grant.stat),
+        rank: rungRank(node, siblings),
+        rankCount: siblings.length,
+    }
+}
+
+for (const node of CHARTER_REGISTRY) {
+    if (node.nodeId === CHARTER_NONE) continue
+    if (!charterMetadata[node.nodeId]) {
+        throw new Error(
+            `Missing charter metadata for node ${node.nodeId}. Add an entry to charter-metadata.ts.`
+        )
+    }
+}