@shipload/sdk 1.0.0-next.2 → 1.0.0-next.20

package/src/resolution/resolve-item.ts

@@ -26,8 +26,9 @@ import {
     computeLoaderCapabilities,
     computeShipHullCapabilities,
     computeWarehouseHullCapabilities,
-} from '../entities/ship-deploy'
-import {computeContainerCapabilities, computeContainerT2Capabilities} from '../entities/container'
+    computeContainerCapabilities,
+    computeContainerT2Capabilities,
+} from '../derivation/capabilities'
 import {
     categoryColors,
     categoryIcons,
@@ -39,6 +40,7 @@ import type {ServerContract} from '../contracts'
 import {
     ITEM_CONTAINER_T1_PACKED,
     ITEM_CONTAINER_T2_PACKED,
+    ITEM_EXTRACTOR_T1_PACKED,
     ITEM_SHIP_T1_PACKED,
     ITEM_WAREHOUSE_T1_PACKED,
 } from '../data/item-ids'
@@ -155,7 +157,8 @@ function resolveComponent(id: number, stats?: UInt64Type): ResolvedItem {
 
 function computeCapabilityGroup(
     moduleType: number,
-    stats: Record<string, number>
+    stats: Record<string, number>,
+    tier: number
 ): ResolvedAttributeGroup | undefined {
     switch (moduleType) {
         case MODULE_ENGINE: {
@@ -179,14 +182,13 @@ function computeCapabilityGroup(
             }
         }
         case MODULE_GATHERER: {
-            const caps = computeGathererCapabilities(stats)
+            const caps = computeGathererCapabilities(stats, tier)
             return {
                 capability: 'Gatherer',
                 attributes: [
                     {label: 'Yield', value: caps.yield},
                     {label: 'Drain', value: caps.drain},
                     {label: 'Depth', value: caps.depth},
-                    {label: 'Speed', value: caps.speed},
                 ],
             }
         }
@@ -223,10 +225,11 @@ function computeCapabilityGroup(
             }
         }
         case MODULE_STORAGE: {
-            const str = stats.strength ?? 500
-            const hrd = stats.hardness ?? 500
-            const sat = stats.saturation ?? 500
-            const statSum = str + hrd + sat
+            const str = stats.strength
+            const den = stats.density
+            const hrd = stats.hardness
+            const sat = stats.saturation
+            const statSum = str + den + hrd + sat
             const pct = 10 + Math.floor((statSum * 10) / 2997)
             return {capability: 'Storage', attributes: [{label: 'Capacity Bonus', value: pct}]}
         }
@@ -241,7 +244,7 @@ function resolveModule(id: number, stats?: UInt64Type): ResolvedItem {
     if (stats !== undefined) {
         const decoded = decodeCraftedItemStats(id, toBigStats(stats))
         const modType = getModuleCapabilityType(id)
-        const group = computeCapabilityGroup(modType, decoded)
+        const group = computeCapabilityGroup(modType, decoded, item.tier)
         if (group) attributes = [group]
     }
     return {
@@ -268,6 +271,8 @@ function hullCapsForEntity(
             return computeShipHullCapabilities(decoded)
         case ITEM_WAREHOUSE_T1_PACKED:
             return computeWarehouseHullCapabilities(decoded)
+        case ITEM_EXTRACTOR_T1_PACKED:
+            return computeShipHullCapabilities(decoded)
         case ITEM_CONTAINER_T1_PACKED:
             return computeContainerCapabilities(decoded)
         case ITEM_CONTAINER_T2_PACKED:
@@ -310,13 +315,16 @@ function resolveEntity(
                 const modStats = BigInt(mod.installed.stats.toString())
                 const decodedStats = decodeCraftedItemStats(modItemId, modStats)
                 const modType = getModuleCapabilityType(modItemId)
-                const group = computeCapabilityGroup(modType, decodedStats)
                 let modName = 'Module'
+                let modTier = 1
                 try {
-                    modName = getItem(modItemId).name
+                    const modItem = getItem(modItemId)
+                    modName = modItem.name
+                    modTier = modItem.tier
                 } catch {
                     modName = itemMetadata[modItemId]?.name ?? 'Module'
                 }
+                const group = computeCapabilityGroup(modType, decodedStats, modTier)
                 return {
                     name: modName,
                     installed: true,

package/src/scheduling/accessor.ts

@@ -72,6 +72,10 @@ export class ScheduleAccessor {
         return schedule.currentTaskProgress(this.entity, now)
     }
 
+    currentTaskProgressFloat(now: Date): number {
+        return schedule.currentTaskProgressFloat(this.entity, now)
+    }
+
     progress(now: Date): number {
         return schedule.scheduleProgress(this.entity, now)
     }

package/src/scheduling/projection.ts

@@ -14,10 +14,12 @@ import {
     RECIPE_INPUTS_INSUFFICIENT,
     RECIPE_INPUTS_INVALID,
     RECIPE_NOT_FOUND,
-    SHIP_CARGO_NOT_LOADED,
+    ENTITY_CARGO_NOT_LOADED,
 } from '../errors'
-import {getRecipe, type RecipeInput} from '../data/recipes-runtime'
-import {getItem} from '../data/catalog'
+import {getEntityLayout, getRecipe, type RecipeInput} from '../data/recipes-runtime'
+import {computeEntityCapabilities} from '../derivation/capabilities'
+import {decodeCraftedItemStats} from '../derivation/crafting'
+import {packedModulesToInstalled, type InstalledModule} from '../entities/slot-multiplier'
 import {distanceBetweenCoordinates, lerp} from '../travel/travel'
 import {
     calcStacksMass,
@@ -63,19 +65,74 @@ export interface Projectable extends ScheduleData {
     cargo: ServerContract.Types.cargo_item[]
     cargomass: UInt32
     owner?: Name
+    stats?: bigint
+    item_id?: number | UInt16
+    modules?: ServerContract.Types.module_entry[] | InstalledModule[]
 }
 
-function getHullMass(entity: Projectable): UInt32 {
-    return UInt32.from(entity.hullmass ?? 0)
+function toInstalledModules(
+    modules: ServerContract.Types.module_entry[] | InstalledModule[]
+): InstalledModule[] {
+    if (modules.length > 0 && 'itemId' in modules[0]) {
+        return modules as InstalledModule[]
+    }
+    return packedModulesToInstalled(modules as ServerContract.Types.module_entry[])
+}
+
+interface ProjectedCaps {
+    hullmass?: UInt32
+    capacity?: UInt32
+    engines?: ServerContract.Types.movement_stats
+    generator?: ServerContract.Types.energy_stats
+    loaders?: ServerContract.Types.loader_stats
+    hauler?: ServerContract.Types.hauler_stats
+}
+
+function recomputeCaps(entity: Projectable): ProjectedCaps | undefined {
+    if (
+        entity.item_id === undefined ||
+        entity.modules === undefined ||
+        entity.stats === undefined
+    ) {
+        return undefined
+    }
+
+    const itemId = Number(
+        typeof entity.item_id === 'number' ? entity.item_id : entity.item_id.value
+    )
+    const hullStats = decodeCraftedItemStats(itemId, entity.stats)
+    const layout = getEntityLayout(itemId)?.slots ?? []
+    const installed = toInstalledModules(entity.modules)
+    const caps = computeEntityCapabilities(hullStats, itemId, installed, layout)
+
+    return {
+        hullmass: UInt32.from(caps.hullmass),
+        capacity: UInt32.from(caps.capacity),
+        engines: caps.engines ? ServerContract.Types.movement_stats.from(caps.engines) : undefined,
+        generator: caps.generator
+            ? ServerContract.Types.energy_stats.from(caps.generator)
+            : undefined,
+        loaders: caps.loaders ? ServerContract.Types.loader_stats.from(caps.loaders) : undefined,
+        hauler: caps.hauler ? ServerContract.Types.hauler_stats.from(caps.hauler) : undefined,
+    }
 }
 
 export function createProjectedEntity(entity: Projectable): ProjectedEntity {
-    const shipMass = getHullMass(entity)
-    const loaders = entity.loaders
-    const engines = entity.engines
-    const generator = entity.generator
-    const hauler = entity.hauler
-    const capacity = entity.capacity
+    const needsRecompute =
+        entity.hullmass === undefined ||
+        entity.loaders === undefined ||
+        entity.engines === undefined ||
+        entity.generator === undefined ||
+        entity.hauler === undefined ||
+        entity.capacity === undefined
+    const caps = needsRecompute ? recomputeCaps(entity) : undefined
+
+    const shipMass = UInt32.from(entity.hullmass ?? caps?.hullmass ?? 0)
+    const loaders = entity.loaders ?? caps?.loaders
+    const engines = entity.engines ?? caps?.engines
+    const generator = entity.generator ?? caps?.generator
+    const hauler = entity.hauler ?? caps?.hauler
+    const capacity = entity.capacity ?? caps?.capacity
 
     const cargo: CargoStack[] = entity.cargo.map(cargoItemToStack)
 
@@ -255,7 +312,6 @@ function applyTask(projected: ProjectedEntity, task: ServerContract.Types.task):
             applyAddCargoTask(projected, task)
             break
         case TaskType.UNLOAD:
-        case TaskType.WRAP:
             applyRemoveCargoTask(projected, task)
             break
         case TaskType.GATHER:
@@ -267,6 +323,9 @@ function applyTask(projected: ProjectedEntity, task: ServerContract.Types.task):
         case TaskType.DEPLOY:
             applyDeployTask(projected, task)
             break
+        case TaskType.UNDEPLOY:
+        case TaskType.DEMOLISH:
+            break
     }
 }
 
@@ -342,19 +401,10 @@ function validateCraftTask(task: ServerContract.Types.task, projected: Projected
         let matched = false
         for (let ri = 0; ri < recipe.length; ri++) {
             const req = recipe[ri]
-            if ('itemId' in req) {
-                if (input.item_id.toNumber() === req.itemId) {
-                    groupedInputs[ri].push(input)
-                    matched = true
-                    break
-                }
-            } else {
-                const item = getItem(input.item_id)
-                if (item.category === req.category && item.tier === req.tier) {
-                    groupedInputs[ri].push(input)
-                    matched = true
-                    break
-                }
+            if (input.item_id.toNumber() === req.itemId) {
+                groupedInputs[ri].push(input)
+                matched = true
+                break
             }
         }
         if (!matched) throw new Error(RECIPE_INPUTS_INVALID)
@@ -385,7 +435,7 @@ function validateCraftTask(task: ServerContract.Types.task, projected: Projected
                 break
             }
         }
-        if (!found) throw new Error(SHIP_CARGO_NOT_LOADED)
+        if (!found) throw new Error(ENTITY_CARGO_NOT_LOADED)
     }
 }
 
@@ -436,7 +486,6 @@ export function projectEntityAt(entity: Projectable, now: Date): ProjectedEntity
                 if (taskComplete) applyAddCargoTask(projected, task)
                 break
             case TaskType.UNLOAD:
-            case TaskType.WRAP:
                 if (taskComplete) applyRemoveCargoTask(projected, task)
                 break
             case TaskType.GATHER:
@@ -448,6 +497,9 @@ export function projectEntityAt(entity: Projectable, now: Date): ProjectedEntity
             case TaskType.DEPLOY:
                 if (taskComplete) applyDeployTask(projected, task)
                 break
+            case TaskType.UNDEPLOY:
+            case TaskType.DEMOLISH:
+                break
         }
     }
 

package/src/scheduling/schedule.ts

@@ -77,7 +77,7 @@ export function currentTaskIndex(entity: ScheduleData, now: Date): number {
         timeAccum += taskDuration
     }
 
-    return entity.schedule.tasks.length - 1
+    return -1
 }
 
 export function currentTask(entity: ScheduleData, now: Date): Task | undefined {
@@ -147,6 +147,20 @@ export function currentTaskProgress(entity: ScheduleData, now: Date): number {
     return Math.min(1, elapsed / duration)
 }
 
+export function currentTaskProgressFloat(entity: ScheduleData, now: Date): number {
+    if (!entity.schedule || entity.schedule.tasks.length === 0) return 0
+    const index = currentTaskIndex(entity, now)
+    if (index < 0) return 0
+    const task = entity.schedule.tasks[index]
+    const durationMs = task.duration.toNumber() * 1000
+    if (durationMs === 0) return 1
+    const startedMs = entity.schedule.started.toDate().getTime()
+    const taskStartMs = startedMs + getTaskStartTime(entity, index) * 1000
+    const elapsedMs = now.getTime() - taskStartMs
+    if (elapsedMs <= 0) return 0
+    return Math.min(1, elapsedMs / durationMs)
+}
+
 export function scheduleProgress(entity: ScheduleData, now: Date): number {
     const duration = scheduleDuration(entity)
     if (duration === 0) return hasSchedule(entity) ? 1 : 0

package/src/scheduling/task-cargo.ts

@@ -0,0 +1,46 @@
+import type {ServerContract} from '../contracts'
+import {TaskType} from '../types'
+
+export type TaskCargoDirection = 'in' | 'out'
+
+export interface TaskCargoChange {
+    direction: TaskCargoDirection
+    item_id: number
+    stats: bigint
+    modules: ServerContract.Types.module_entry[]
+    quantity: number
+}
+
+function toChange(
+    item: ServerContract.Types.cargo_item,
+    direction: TaskCargoDirection
+): TaskCargoChange {
+    return {
+        direction,
+        item_id: Number(item.item_id),
+        stats: BigInt(item.stats.toString()),
+        modules: item.modules ?? [],
+        quantity: Number(item.quantity),
+    }
+}
+
+export function taskCargoChanges(task: ServerContract.Types.task): TaskCargoChange[] {
+    const items = task.cargo ?? []
+    if (items.length === 0) return []
+    switch (Number(task.type)) {
+        case TaskType.LOAD:
+        case TaskType.UNWRAP:
+            return items.map((i) => toChange(i, 'in'))
+        case TaskType.GATHER:
+            return task.entitytarget ? [] : items.map((i) => toChange(i, 'in'))
+        case TaskType.UNLOAD:
+            return items.map((i) => toChange(i, 'out'))
+        case TaskType.CRAFT:
+            return [
+                ...items.slice(0, -1).map((i) => toChange(i, 'out')),
+                toChange(items[items.length - 1], 'in'),
+            ]
+        default:
+            return []
+    }
+}

package/src/shipload.ts

@@ -9,6 +9,7 @@ import type {PlayersManager} from './managers/players'
 import type {LocationsManager} from './managers/locations'
 import type {EpochsManager} from './managers/epochs'
 import type {ActionsManager} from './managers/actions'
+import type {NftManager} from './managers/nft'
 import type {SubscriptionsManager} from './subscriptions/manager'
 import type {GameState} from './entities/gamestate'
 
@@ -107,6 +108,10 @@ export class Shipload {
         return this._context.actions
     }
 
+    get nft(): NftManager {
+        return this._context.nft
+    }
+
     get subscriptions(): SubscriptionsManager {
         return this._context.subscriptions
     }

package/src/subscriptions/manager.ts

@@ -13,12 +13,10 @@ import type {
     WireEntity,
 } from './types'
 import {mapEntity, parseWireEntity} from './mappers'
-import type {Ship} from '../entities/ship'
-import type {Warehouse} from '../entities/warehouse'
-import type {Container} from '../entities/container'
+import type {Entity} from '../entities/entity'
 
-export type SubscriptionEntityType = 'ship' | 'warehouse' | 'container'
-export type EntityInstance = Ship | Warehouse | Container
+export type SubscriptionEntityType = 'ship' | 'warehouse' | 'container' | 'nexus'
+export type EntityInstance = Entity
 
 export interface SubscriptionsOptions {
     url: string
@@ -34,6 +32,12 @@ export interface BoundsSubscriptionHandle {
     current: Map<number, EntityInstance>
 }
 
+export interface OwnerSubscriptionHandle {
+    readonly subId: string
+    unsubscribe(): void
+    current: Map<number, EntityInstance>
+}
+
 export interface EntitySubscriptionHandle {
     readonly subId: string
     readonly entityType: SubscriptionEntityType
@@ -62,7 +66,7 @@ export class SubscriptionsManager {
             onSnapshot?: (entities: EntityInstance[]) => void
             onUpdate?: (entity: EntityInstance) => void
             onBoundsDelta?: (entered: EntityInstance[], exited: number[]) => void
-            handle: BoundsSubscriptionHandle
+            handle: BoundsSubscriptionHandle | OwnerSubscriptionHandle
         }
     >()
     private subCounter = 0
@@ -162,6 +166,36 @@ export class SubscriptionsManager {
         return handle
     }
 
+    subscribeOwner(
+        owner: string,
+        handlers: {
+            onSnapshot?: (entities: EntityInstance[]) => void
+            onUpdate?: (entity: EntityInstance) => void
+        } = {}
+    ): OwnerSubscriptionHandle {
+        const subId = this.generateSubID('own')
+        const msg: SubscribeMessage = {
+            type: 'subscribe',
+            sub_id: subId,
+            owner,
+        }
+        const handle: OwnerSubscriptionHandle = {
+            subId,
+            unsubscribe: () => this.unsubscribeBounds(subId),
+            current: new Map(),
+        }
+        this.boundsSubs.set(subId, {
+            bounds: undefined,
+            owner,
+            prioritizeOwner: undefined,
+            onSnapshot: handlers.onSnapshot,
+            onUpdate: handlers.onUpdate,
+            handle,
+        })
+        this.sendMessage(msg)
+        return handle
+    }
+
     private unsubscribeBounds(subId: string) {
         this.boundsSubs.delete(subId)
         this.sendMessage({type: 'unsubscribe', sub_id: subId})

package/src/subscriptions/mappers.ts

@@ -1,14 +1,9 @@
 import {ServerContract} from '../contracts'
-import {Ship} from '../entities/ship'
-import {Warehouse} from '../entities/warehouse'
-import {Container} from '../entities/container'
+import {Entity} from '../entities/entity'
 import type {WireEntity} from './types'
 
-export function mapEntity(ei: ServerContract.Types.entity_info): Ship | Warehouse | Container {
-    if (ei.type.equals('ship')) return new Ship(ei)
-    if (ei.type.equals('warehouse')) return new Warehouse(ei)
-    if (ei.type.equals('container')) return new Container(ei)
-    throw new Error(`mapEntity: unknown entity type ${ei.type.toString()}`)
+export function mapEntity(ei: ServerContract.Types.entity_info): Entity {
+    return new Entity(ei)
 }
 
 export function parseWireEntity(raw: WireEntity): ServerContract.Types.entity_info {

package/src/subscriptions/types.ts

@@ -39,7 +39,7 @@ export type UnsubscribeMessage = {
 export type SubscribeEntityMessage = {
     type: 'subscribe_entity'
     sub_id: string
-    entity_type: 'ship' | 'warehouse' | 'container'
+    entity_type: 'ship' | 'warehouse' | 'container' | 'nexus'
     entity_id: string
 }
 
@@ -80,10 +80,11 @@ export type AckMessage = {
 
 export type WireEntity = Record<string, unknown> & {
     type: number
-    type_name: 'ship' | 'warehouse' | 'container'
+    type_name: 'ship' | 'warehouse' | 'container' | 'nexus'
     id: string | number
     owner: string
     coordinates: WireCoordinates
+    item_id: number
 }
 
 export type SnapshotMessage = {

package/src/testing/catalog-hash.ts

@@ -0,0 +1,19 @@
+import {createHash} from 'node:crypto'
+import {readFileSync} from 'node:fs'
+
+export const CATALOG_FILES_REL = [
+    'items.json',
+    'recipes.json',
+    'entities.json',
+    'kind-registry.json',
+    'item-ids.ts',
+] as const
+
+export function computeCatalogHash(filePaths: ReadonlyArray<string>): string {
+    const hash = createHash('sha256')
+    for (const p of filePaths) {
+        hash.update(readFileSync(p))
+        hash.update('\0')
+    }
+    return hash.digest('hex')
+}

package/src/testing/index.ts

@@ -0,0 +1,2 @@
+export * from './catalog-hash'
+export * from './projection-parity'

package/src/testing/projection-parity.ts

@@ -0,0 +1,143 @@
+import type {UInt16, UInt32} from '@wharfkit/antelope'
+import type {ServerContract} from '../contracts'
+import type {ProjectedEntity} from '../scheduling/projection'
+import {type CargoStack, cargoItemToStack, mergeStacks} from '../capabilities/storage'
+
+export interface ContractProjectedState {
+    owner: {toString(): string}
+    coordinates: ServerContract.Types.coordinates
+    energy?: UInt16
+    cargomass: UInt32
+    cargo: ServerContract.Types.cargo_view[]
+    hullmass?: UInt32
+    capacity?: UInt32
+    engines?: ServerContract.Types.movement_stats
+    loaders?: ServerContract.Types.loader_stats
+    generator?: ServerContract.Types.energy_stats
+    hauler?: ServerContract.Types.hauler_stats
+}
+
+export interface ProjectionComparisonOptions {
+    step?: number
+}
+
+export function assertProjectionEquals(
+    contract: ContractProjectedState,
+    sdk: ProjectedEntity,
+    options: ProjectionComparisonOptions = {}
+): void {
+    const mismatches: string[] = []
+
+    const record = (name: string, c: unknown, s: unknown) => {
+        if (c !== s) mismatches.push(`  ${name}: contract=${fmt(c)} sdk=${fmt(s)}`)
+    }
+
+    const recordStatBlock = (name: string, c: unknown, s: unknown) => {
+        const cPresent = c !== undefined && c !== null
+        const sPresent = s !== undefined && s !== null
+        if (cPresent !== sPresent) {
+            mismatches.push(
+                `  ${name}: contract=${cPresent ? 'present' : 'absent'} sdk=${sPresent ? 'present' : 'absent'}`
+            )
+            return
+        }
+        if (!cPresent) return
+        const cn = JSON.stringify(normaliseStatBlock(c))
+        const sn = JSON.stringify(normaliseStatBlock(s))
+        if (cn !== sn) mismatches.push(`  ${name}: contract=${cn} sdk=${sn}`)
+    }
+
+    record('coordinates.x', toNum(contract.coordinates.x), Number(sdk.location.x))
+    record('coordinates.y', toNum(contract.coordinates.y), Number(sdk.location.y))
+    record('energy', toNum(contract.energy), Number(sdk.energy))
+    record('cargomass', toNum(contract.cargomass), Number(sdk.cargoMass))
+    record('hullmass', toNum(contract.hullmass), Number(sdk.shipMass))
+    record('capacity', toNum(contract.capacity), sdk.capacity ? Number(sdk.capacity) : undefined)
+
+    recordStatBlock('engines', contract.engines, sdk.engines)
+    recordStatBlock('loaders', contract.loaders, sdk.loaders)
+    recordStatBlock('generator', contract.generator, sdk.generator)
+    recordStatBlock('hauler', contract.hauler, sdk.hauler)
+
+    if (contract.cargo.length > 0 || sdk.cargo.length > 0) {
+        const contractCargo = normaliseCargo(mergeContractCargo(contract.cargo))
+        const sdkCargo = normaliseCargo(sdk.cargo)
+        if (contractCargo.length !== sdkCargo.length) {
+            mismatches.push(
+                `  cargo.length: contract=${contractCargo.length} sdk=${sdkCargo.length}`
+            )
+        } else {
+            for (let i = 0; i < contractCargo.length; i++) {
+                const c = contractCargo[i]
+                const s = sdkCargo[i]
+                if (c.itemId !== s.itemId || c.stats !== s.stats || c.quantity !== s.quantity) {
+                    mismatches.push(
+                        `  cargo[${i}]: contract={item:${c.itemId},stats:${c.stats},qty:${c.quantity}} sdk={item:${s.itemId},stats:${s.stats},qty:${s.quantity}}`
+                    )
+                }
+            }
+        }
+    }
+
+    if (mismatches.length > 0) {
+        const header =
+            options.step !== undefined
+                ? `projection divergence at step ${options.step}:`
+                : 'projection divergence:'
+        throw new Error([header, ...mismatches].join('\n'))
+    }
+}
+
+interface NormalisedStack {
+    itemId: number
+    stats: string
+    quantity: string
+}
+
+function mergeContractCargo(cargo: ServerContract.Types.cargo_view[]): CargoStack[] {
+    return cargo.reduce<CargoStack[]>(
+        (acc, row) =>
+            mergeStacks(acc, cargoItemToStack(row as unknown as ServerContract.Types.cargo_item)),
+        []
+    )
+}
+
+function normaliseCargo(cargo: CargoStack[]): NormalisedStack[] {
+    return cargo
+        .map((s) => ({
+            itemId: Number(s.item_id),
+            stats: BigInt(s.stats.toString()).toString(),
+            quantity: BigInt(s.quantity.toString()).toString(),
+        }))
+        .sort(stackSort)
+}
+
+function stackSort(a: NormalisedStack, b: NormalisedStack): number {
+    if (a.itemId !== b.itemId) return a.itemId - b.itemId
+    return a.stats < b.stats ? -1 : a.stats > b.stats ? 1 : 0
+}
+
+function toNum(v: unknown): number | undefined {
+    if (v === undefined || v === null) return undefined
+    if (typeof v === 'number') return v
+    if (typeof v === 'bigint') return Number(v)
+    if (typeof (v as {toNumber?: unknown}).toNumber === 'function') {
+        return (v as {toNumber(): number}).toNumber()
+    }
+    return Number(v as number)
+}
+
+function fmt(v: unknown): string {
+    if (v === undefined) return 'undefined'
+    if (v === null) return 'null'
+    return String(v)
+}
+
+function normaliseStatBlock(block: unknown): Record<string, number> {
+    const out: Record<string, number> = {}
+    const obj = block as Record<string, unknown>
+    for (const k of Object.keys(obj).sort()) {
+        out[k] = toNum(obj[k]) ?? 0
+    }
+    return out
+}