@shipload/sdk 1.0.0-next.65 → 1.0.0-next.66

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.`
+        )
+    }
+}

package/src/influence/charters.test.ts

@@ -1,31 +1,39 @@
 import {describe, expect, test} from 'bun:test'
-import {CHARTER_NONE} from './constants'
+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,
-    charterSpawnNodeFor,
-    effectiveMandate,
+    charterModuleCount,
     eligibleCharters,
     type BuiltCharter,
     type CharterWorld,
+    type WorldBuilding,
 } from './charters'
 
-const WORKSHOP = 1
-const NEXUS = 2
-const DOCK = 3
-const WORKSHOP_TUNEUP = 4
-const DOCK_TUNEUP = 5
-const DEPOT = 6
+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
-const DEPOT_ENTITY = 600n
 
-function world(built: BuiltCharter[], present?: bigint[]): CharterWorld {
-    if (!present) return {built}
-    return {built, entityExists: (id) => present.includes(id)}
+function world(built: BuiltCharter[]): CharterWorld {
+    return {built}
 }
 
 function node(nodeId: number) {
@@ -48,13 +56,13 @@ describe('charter eligibility mirror', () => {
     })
 
     test('completing the root opens the fork and closes the singleton path', () => {
-        const built = world([{nodeId: WORKSHOP, entityId: WORKSHOP_ENTITY}])
-        expect(eligibleIds(built)).toEqual([NEXUS, DOCK, WORKSHOP_TUNEUP, DEPOT])
+        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, entityId: WORKSHOP_ENTITY}])
+        const built = world([{nodeId: WORKSHOP, repeats: 0}])
         expect(charterIneligible(built, node(WORKSHOP))).toBe('already-taken')
     })
 
@@ -63,64 +71,42 @@ describe('charter eligibility mirror', () => {
         expect(charterIneligible(world([]), node(DOCK_TUNEUP))).toBe('prereq-missing')
     })
 
-    test('a refit whose spawned target is gone reports refit-target-missing', () => {
-        const built = [{nodeId: WORKSHOP, entityId: WORKSHOP_ENTITY}]
-        expect(charterEligible(world(built, [WORKSHOP_ENTITY]), node(WORKSHOP_TUNEUP))).toBe(true)
-        expect(charterIneligible(world(built, []), node(WORKSHOP_TUNEUP))).toBe(
-            'refit-target-missing'
-        )
-    })
-
-    test('a demolished target can empty an otherwise singleton eligible set', () => {
-        const built = [
-            {nodeId: WORKSHOP, entityId: WORKSHOP_ENTITY},
-            {nodeId: NEXUS, entityId: 200n},
-            {nodeId: DOCK, entityId: DOCK_ENTITY},
-            {nodeId: DOCK_TUNEUP, entityId: 0n},
-            {nodeId: DEPOT, entityId: DEPOT_ENTITY},
-        ]
-        expect(charterSingletonMandate(world(built, [WORKSHOP_ENTITY, DOCK_ENTITY]))).toBe(
-            WORKSHOP_TUNEUP
-        )
-        expect(charterSingletonMandate(world(built, [DOCK_ENTITY]))).toBe(CHARTER_NONE)
-    })
-
-    test('an absent entity predicate trusts the charter record', () => {
-        const built = world([{nodeId: WORKSHOP, entityId: WORKSHOP_ENTITY}])
+    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('refit targets resolve through the node that spawns the item', () => {
-        expect(charterSpawnNodeFor(node(WORKSHOP_TUNEUP).effect.targetItemId)?.nodeId).toBe(
-            WORKSHOP
-        )
-        expect(charterSpawnNodeFor(node(DOCK_TUNEUP).effect.targetItemId)?.nodeId).toBe(DOCK)
-        expect(charterSpawnNodeFor(0)).toBeUndefined()
+    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()
     })
-})
-
-describe('effective mandate', () => {
-    const forked = world([{nodeId: WORKSHOP, entityId: WORKSHOP_ENTITY}])
 
-    test('a stored choice holds inside its own epoch', () => {
-        expect(effectiveMandate({chosen: DOCK, chosenEpoch: 7}, forked, 7)).toBe(DOCK)
+    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('the same stored choice expires one epoch later', () => {
-        expect(effectiveMandate({chosen: DOCK, chosenEpoch: 7}, forked, 8)).toBe(CHARTER_NONE)
-    })
+    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)
 
-    test('an expired choice falls through to the singleton rule', () => {
-        const unbuilt = world([])
-        expect(effectiveMandate({chosen: NEXUS, chosenEpoch: 7}, unbuilt, 8)).toBe(WORKSHOP)
+        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('a cleared pair reads the singleton rule', () => {
-        expect(effectiveMandate({chosen: CHARTER_NONE, chosenEpoch: 0}, world([]), 3)).toBe(
-            WORKSHOP
-        )
-        expect(effectiveMandate({chosen: CHARTER_NONE, chosenEpoch: 0}, forked, 3)).toBe(
-            CHARTER_NONE
-        )
+    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)
     })
 })