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

package/src/derivation/rollups.test.ts

@@ -0,0 +1,55 @@
+import {describe, expect, test} from 'bun:test'
+import {ServerContract} from '../contracts'
+import {rollupGatherer, rollupCrafter, rollupLoaders} from './rollups'
+
+const gLane = (slot: number, y: number, d: number, depth: number) =>
+    ServerContract.Types.gatherer_lane.from({
+        slot_index: slot,
+        yield: y,
+        drain: d,
+        depth,
+        output_pct: 100,
+    })
+const cLane = (slot: number, s: number, d: number) =>
+    ServerContract.Types.crafter_lane.from({slot_index: slot, speed: s, drain: d, output_pct: 100})
+const lLane = (slot: number, m: number, t: number) =>
+    ServerContract.Types.loader_lane.from({slot_index: slot, mass: m, thrust: t, output_pct: 100})
+
+describe('rollupGatherer', () => {
+    test('empty → undefined', () => {
+        expect(rollupGatherer([])).toBeUndefined()
+    })
+    test('sums yield/drain, takes MAX depth', () => {
+        const r = rollupGatherer([gLane(2, 300, 1250, 500), gLane(3, 250, 1000, 5495)])!
+        expect(r.yield.toNumber()).toBe(550)
+        expect(r.drain.toNumber()).toBe(2250)
+        expect(r.depth.toNumber()).toBe(5495)
+    })
+    test('clamps summed yield to uint16', () => {
+        const r = rollupGatherer([gLane(2, 60000, 0, 1), gLane(3, 60000, 0, 1)])!
+        expect(r.yield.toNumber()).toBe(65535)
+    })
+})
+
+describe('rollupCrafter', () => {
+    test('empty → undefined', () => {
+        expect(rollupCrafter([])).toBeUndefined()
+    })
+    test('sums speed/drain', () => {
+        const r = rollupCrafter([cLane(2, 100, 30), cLane(3, 140, 25)])!
+        expect(r.speed.toNumber()).toBe(240)
+        expect(r.drain.toNumber()).toBe(55)
+    })
+})
+
+describe('rollupLoaders', () => {
+    test('empty → undefined', () => {
+        expect(rollupLoaders([])).toBeUndefined()
+    })
+    test('integer-averages mass, sums thrust, counts quantity', () => {
+        const r = rollupLoaders([lLane(2, 200, 5), lLane(3, 201, 7)])!
+        expect(r.mass.toNumber()).toBe(200) // floor(401/2)
+        expect(r.thrust.toNumber()).toBe(12)
+        expect(r.quantity.toNumber()).toBe(2)
+    })
+})

package/src/derivation/rollups.ts

@@ -0,0 +1,72 @@
+import {UInt8, UInt16, UInt32} from '@wharfkit/antelope'
+import type {ServerContract} from '../contracts'
+
+export function rollupGatherer(
+    lanes: ServerContract.Types.gatherer_lane[]
+): {yield: UInt16; drain: UInt32; depth: UInt16} | undefined {
+    if (lanes.length === 0) return undefined
+    let totalYield = 0
+    let totalDrain = 0
+    let maxDepth = 0
+    for (const l of lanes) {
+        totalYield += Number(l.yield)
+        totalDrain += Number(l.drain)
+        const d = Number(l.depth)
+        if (d > maxDepth) maxDepth = d
+    }
+    return {
+        yield: UInt16.from(Math.min(totalYield, 65535)),
+        drain: UInt32.from(totalDrain),
+        depth: UInt16.from(maxDepth),
+    }
+}
+
+export function rollupCrafter(
+    lanes: ServerContract.Types.crafter_lane[]
+): {speed: UInt16; drain: UInt32} | undefined {
+    if (lanes.length === 0) return undefined
+    let totalSpeed = 0
+    let totalDrain = 0
+    for (const l of lanes) {
+        totalSpeed += Number(l.speed)
+        totalDrain += Number(l.drain)
+    }
+    return {
+        speed: UInt16.from(Math.min(totalSpeed, 65535)),
+        drain: UInt32.from(totalDrain),
+    }
+}
+
+export function rollupBuilder(
+    lanes: ServerContract.Types.builder_lane[]
+): {speed: UInt16; drain: UInt32} | undefined {
+    if (lanes.length === 0) return undefined
+    let totalSpeed = 0
+    let totalDrain = 0
+    for (const l of lanes) {
+        totalSpeed += Number(l.speed)
+        totalDrain += Number(l.drain)
+    }
+    return {
+        speed: UInt16.from(Math.min(totalSpeed, 65535)),
+        drain: UInt32.from(totalDrain),
+    }
+}
+
+export function rollupLoaders(
+    lanes: ServerContract.Types.loader_lane[]
+): {mass: UInt32; thrust: UInt16; quantity: UInt8} | undefined {
+    if (lanes.length === 0) return undefined
+    const count = lanes.length
+    let totalMass = 0
+    let totalThrust = 0
+    for (const l of lanes) {
+        totalMass += Number(l.mass)
+        totalThrust += Number(l.thrust)
+    }
+    return {
+        mass: UInt32.from(Math.floor(totalMass / count)),
+        thrust: UInt16.from(Math.min(totalThrust, 65535)),
+        quantity: UInt8.from(count),
+    }
+}

package/src/derivation/stars.test.ts

@@ -0,0 +1,67 @@
+import {expect, test} from 'bun:test'
+import {
+    compareByStars,
+    MAX_STARS_PER_STAT,
+    MAX_STAR_RATING,
+    starRating,
+    starsForStat,
+    statMagnitude,
+    STAR_STEP,
+} from './stars'
+
+test('starsForStat bands at the 250 boundaries', () => {
+    expect(starsForStat(0)).toBe(0)
+    expect(starsForStat(1)).toBe(0)
+    expect(starsForStat(249)).toBe(0)
+    expect(starsForStat(250)).toBe(1)
+    expect(starsForStat(499)).toBe(1)
+    expect(starsForStat(500)).toBe(2)
+    expect(starsForStat(749)).toBe(2)
+    expect(starsForStat(750)).toBe(3)
+})
+
+test('starsForStat clamps to MAX_STARS_PER_STAT', () => {
+    expect(starsForStat(999)).toBe(MAX_STARS_PER_STAT)
+    expect(starsForStat(1000)).toBe(MAX_STARS_PER_STAT)
+    expect(starsForStat(10_000)).toBe(MAX_STARS_PER_STAT)
+})
+
+test('starsForStat never goes negative', () => {
+    expect(starsForStat(-50)).toBe(0)
+})
+
+test('starRating sums per-stat stars to a 0-9 grade', () => {
+    expect(starRating(0, 0, 0)).toBe(0)
+    expect(starRating(250, 0, 0)).toBe(1)
+    expect(starRating(750, 750, 750)).toBe(MAX_STAR_RATING)
+    expect(starRating(999, 999, 999)).toBe(MAX_STAR_RATING)
+    expect(starRating(599, 599, 599)).toBe(6)
+    expect(starRating(251, 251, 251)).toBe(3)
+})
+
+test('statMagnitude sums raw values for tiebreaking', () => {
+    expect(statMagnitude(599, 599, 599)).toBe(1797)
+    expect(statMagnitude(251, 251, 251)).toBe(753)
+    expect(statMagnitude(599, 599, 599)).toBeGreaterThan(statMagnitude(251, 251, 251))
+})
+
+test('compareByStars orders by rating desc, then magnitude desc', () => {
+    const rows = [
+        {key: 'low-rating', rating: 3, magnitude: 9000},
+        {key: 'high-rating', rating: 6, magnitude: 300},
+        {key: 'tie-small', rating: 6, magnitude: 600},
+        {key: 'tie-big', rating: 6, magnitude: 900},
+    ]
+    const ordered = [...rows].sort(compareByStars).map((r) => r.key)
+    expect(ordered).toEqual(['tie-big', 'tie-small', 'high-rating', 'low-rating'])
+})
+
+test('compareByStars returns 0 when rating and magnitude are equal', () => {
+    expect(compareByStars({rating: 4, magnitude: 500}, {rating: 4, magnitude: 500})).toBe(0)
+})
+
+test('constants hold their documented values', () => {
+    expect(STAR_STEP).toBe(250)
+    expect(MAX_STARS_PER_STAT).toBe(3)
+    expect(MAX_STAR_RATING).toBe(9)
+})

package/src/derivation/stars.ts

@@ -0,0 +1,25 @@
+export const STAR_STEP = 250
+export const MAX_STARS_PER_STAT = 3
+export const MAX_STAR_RATING = MAX_STARS_PER_STAT * 3
+
+export function starsForStat(value: number): number {
+    return Math.max(0, Math.min(MAX_STARS_PER_STAT, Math.floor(value / STAR_STEP)))
+}
+
+export function starRating(stat1: number, stat2: number, stat3: number): number {
+    return starsForStat(stat1) + starsForStat(stat2) + starsForStat(stat3)
+}
+
+export function statMagnitude(stat1: number, stat2: number, stat3: number): number {
+    return stat1 + stat2 + stat3
+}
+
+export interface StarSortable {
+    rating: number
+    magnitude: number
+}
+
+// Star-quality ordering shared by every "sort by stars" surface: rating desc, then total sum of stats desc.
+export function compareByStars(a: StarSortable, b: StarSortable): number {
+    return b.rating - a.rating || b.magnitude - a.magnitude
+}

package/src/derivation/stat-scaling.ts

@@ -0,0 +1,12 @@
+export const MODULE_STAT_SCALING_ANCHOR = 213
+export const MODULE_STAT_SCALING_POST_ANCHOR_PERCENT = 40
+
+export function computeEffectiveModuleStat(stat: number): number {
+    if (stat <= MODULE_STAT_SCALING_ANCHOR) return stat
+    return (
+        MODULE_STAT_SCALING_ANCHOR +
+        Math.floor(
+            ((stat - MODULE_STAT_SCALING_ANCHOR) * MODULE_STAT_SCALING_POST_ANCHOR_PERCENT) / 100
+        )
+    )
+}

package/src/derivation/stats.ts

@@ -25,8 +25,7 @@ const ORE_STATS: StatDefinition[] = [
         key: 'density',
         label: 'Density',
         abbreviation: 'DEN',
-        purpose: 'Mass per unit',
-        inverted: true,
+        purpose: 'Structural integrity — higher rolls produce lighter hulls',
     },
 ]
 
@@ -74,10 +73,11 @@ const GAS_STATS: StatDefinition[] = [
 
 const REGOLITH_STATS: StatDefinition[] = [
     {
-        key: 'composition',
-        label: 'Composition',
-        abbreviation: 'COM',
-        purpose: 'Mineral/metal mix — drives sensor, chip, and optic crafting quality',
+        key: 'cohesion',
+        label: 'Cohesion',
+        abbreviation: 'COH',
+        purpose:
+            'Binding strength of the loose aggregate; higher cohesion yields more rigid frames and hulls',
     },
     {
         key: 'hardness',

package/src/derivation/strata.ts

@@ -1,5 +1,5 @@
-import type {Checksum256Type} from '@wharfkit/antelope'
-import type {CoordinatesType} from '../types'
+import {Checksum256, type Checksum256Type} from '@wharfkit/antelope'
+import {Coordinates, type CoordinatesType} from '../types'
 import {deriveLocationStatic} from '../utils/system'
 import {deriveLocationSize} from './location-size'
 import {deriveResourceStats, deriveStratum, type ResourceStats} from './stratum'
@@ -26,9 +26,11 @@ export function deriveStrata(
     if (size === 0) return []
 
     const subtype = Number(loc.subtype)
+    const seed = Checksum256.from(epochSeed)
+    const at = Coordinates.from(coords)
     const out: DerivedStratum[] = []
     for (let i = 0; i < size; i++) {
-        const s = deriveStratum(epochSeed, coords, i, locType, subtype, size)
+        const s = deriveStratum(seed, at, i, locType, subtype, size)
         if (s.reserve === 0) continue
         out.push({
             index: i,

package/src/derivation/stratum.ts

@@ -1,14 +1,22 @@
 import {Bytes, Checksum256, type Checksum256Type} from '@wharfkit/antelope'
 import {hash512} from '../utils/hash'
 import {Coordinates, type CoordinatesType} from '../types'
-import {getEligibleResources, getResourceWeight, YIELD_THRESHOLD} from './resources'
-import {RESERVE_TIERS, rollTier, rollWithinTier} from './tiers'
+import {getItem} from '../data/catalog'
+import {getEligibleResources, getResourceWeight, yieldThresholdAt} from './resources'
+import {
+    RESERVE_TIERS,
+    rollTier,
+    rollWithinTier,
+    applyResourceTierMultiplier,
+    type ReserveTier,
+} from './tiers'
 
 export interface StratumInfo {
     itemId: number
     seed: bigint
     richness: number
     reserve: number
+    tier: ReserveTier
 }
 
 export interface ResourceStats {
@@ -33,18 +41,11 @@ export function deriveStratum(
 
     const rawReserve = ((bytes[0] << 24) | (bytes[1] << 16) | (bytes[2] << 8) | bytes[3]) >>> 0
 
-    let reserve = 0
-    if (rawReserve <= YIELD_THRESHOLD) {
-        const tierRoll = ((bytes[18] << 8) | bytes[19]) >>> 0
-        const withinRoll = ((bytes[20] << 8) | bytes[21]) >>> 0
-        const tier = rollTier(tierRoll, stratum)
-        reserve = rollWithinTier(withinRoll, RESERVE_TIERS[tier])
-    }
-
-    if (reserve === 0) return {itemId: 0, seed: 0n, richness: 0, reserve: 0}
+    if (rawReserve > yieldThresholdAt(stratum))
+        return {itemId: 0, seed: 0n, richness: 0, reserve: 0, tier: 'small'}
 
     const eligible = getEligibleResources(locationType, subtype, stratum)
-    if (eligible.length === 0) return {itemId: 0, seed: 0n, richness: 0, reserve: 0}
+    if (eligible.length === 0) return {itemId: 0, seed: 0n, richness: 0, reserve: 0, tier: 'small'}
 
     const resourceRoll = ((bytes[4] << 24) | (bytes[5] << 16) | (bytes[6] << 8) | bytes[7]) >>> 0
 
@@ -66,6 +67,13 @@ export function deriveStratum(
         }
     }
 
+    const tierRoll = ((bytes[18] << 8) | bytes[19]) >>> 0
+    const withinRoll = ((bytes[20] << 8) | bytes[21]) >>> 0
+    const tier = rollTier(tierRoll, stratum)
+    const selected = getItem(selectedItemId)
+    const baseReserve = rollWithinTier(withinRoll, RESERVE_TIERS[tier], selected.mass)
+    const reserve = applyResourceTierMultiplier(baseReserve, selected.tier)
+
     const seedBigInt =
         (BigInt(bytes[8]) << 56n) |
         (BigInt(bytes[9]) << 48n) |
@@ -76,17 +84,13 @@ export function deriveStratum(
         (BigInt(bytes[14]) << 8n) |
         BigInt(bytes[15])
 
-    const rawRichness = (bytes[16] << 8) | bytes[17]
-    const normalized = rawRichness / 65535
-    const baseRichness = Math.floor(normalized * normalized * 999) + 1
-
-    let depthBonus = 0
-    if (stratum > 1) {
-        depthBonus = (50 * Math.log(stratum)) / Math.log(65535)
-    }
-    const richness = Math.min(Math.floor(baseRichness + depthBonus), 1000)
+    let byteSum = 0
+    for (let i = 22; i <= 33; i++) byteSum += bytes[i]
+    const z = (byteSum - 1530) / 256
+    const roll = 500 + 100 * z
+    const richness = Math.max(1, Math.min(999, Math.round(roll)))
 
-    return {itemId: selectedItemId, seed: seedBigInt, richness, reserve}
+    return {itemId: selectedItemId, seed: seedBigInt, richness, reserve, tier}
 }
 
 /**

package/src/derivation/tiers.ts

@@ -1,3 +1,5 @@
+import {getItem} from '../data/catalog'
+
 export type ReserveTier = 'small' | 'medium' | 'large' | 'massive' | 'motherlode'
 
 export interface TierRange {
@@ -6,11 +8,11 @@ export interface TierRange {
 }
 
 export const RESERVE_TIERS: Record<ReserveTier, TierRange> = {
-    small: {min: 15, max: 60},
-    medium: {min: 100, max: 200},
-    large: {min: 400, max: 700},
-    massive: {min: 1000, max: 2500},
-    motherlode: {min: 4000, max: 10000},
+    small: {min: 36_000, max: 144_000},
+    medium: {min: 240_000, max: 480_000},
+    large: {min: 960_000, max: 1_680_000},
+    massive: {min: 2_400_000, max: 6_000_000},
+    motherlode: {min: 9_600_000, max: 24_000_000},
 }
 
 const SHALLOW_THRESHOLDS = {
@@ -47,8 +49,39 @@ export function rollTier(tierRoll: number, stratum: number): ReserveTier {
     return 'motherlode'
 }
 
-export function rollWithinTier(withinRoll: number, range: TierRange): number {
+export function rollWithinTier(
+    withinRoll: number,
+    range: TierRange,
+    resourceUnitMass: number
+): number {
     const u = withinRoll / 65535
     const skewed = u * u
-    return Math.floor(range.min + skewed * (range.max - range.min))
+    const depositMass = range.min + skewed * (range.max - range.min)
+    return Math.max(1, Math.floor(depositMass / resourceUnitMass))
+}
+
+// Must mirror the contract tier-multiplier table in tiers.hpp byte-for-byte; values are in tenths (T1..T10).
+export const RESOURCE_TIER_MULT_TENTHS = [200, 154, 118, 91, 70, 54, 41, 32, 24, 19] as const
+
+export function applyResourceTierMultiplier(units: number, resourceTier: number): number {
+    const idx = resourceTier < 1 ? 0 : resourceTier > 10 ? 9 : resourceTier - 1
+    const scaled = Math.floor((units * RESOURCE_TIER_MULT_TENTHS[idx]) / 10)
+    return scaled > 0 ? scaled : 1
+}
+
+const RESERVE_TIER_ENTRIES = Object.entries(RESERVE_TIERS) as Array<[ReserveTier, TierRange]>
+
+export function tierOfReserve(reserve: number, itemId: number): ReserveTier | null {
+    if (reserve <= 0) return null
+    const item = getItem(itemId)
+    if (item.mass <= 0) return null
+    // Reverse the resource-tier multiplier so bands read relative to the resource tier.
+    const idx = item.tier < 1 ? 0 : item.tier > 10 ? 9 : item.tier - 1
+    const baseReserve = (reserve * 10) / RESOURCE_TIER_MULT_TENTHS[idx]
+    const impliedMassLow = baseReserve * item.mass
+    const impliedMassHigh = impliedMassLow + item.mass
+    for (const [tier, range] of RESERVE_TIER_ENTRIES) {
+        if (impliedMassHigh > range.min && impliedMassLow <= range.max) return tier
+    }
+    return null
 }

package/src/derivation/upgrades.ts

@@ -0,0 +1,14 @@
+import recipes from '../data/recipes.json'
+import type {Recipe} from '../data/recipes-runtime'
+
+const bySource = new Map<number, Recipe[]>()
+for (const r of recipes as Recipe[]) {
+    if (r.sourceSubclass === undefined) continue
+    const list = bySource.get(r.sourceSubclass) ?? []
+    list.push(r)
+    bySource.set(r.sourceSubclass, list)
+}
+
+export function eligibleUpgrades(entityItemId: number): Recipe[] {
+    return bySource.get(entityItemId) ?? []
+}

package/src/derivation/wormhole.ts

@@ -0,0 +1,154 @@
+import type {Checksum256Type} from '@wharfkit/antelope'
+import {hash512} from '../utils/hash'
+import {COORD_MAX, COORD_MIN} from '../coordinates/constants'
+
+export const WH = {
+    RSIZE: 75,
+    ZONE: 16384,
+    THRESHOLD: 8192,
+    MIN_REACH: 50000,
+    TRANSIT_SPEED: 500,
+} as const
+
+const HALF = Math.round(Math.log2(WH.ZONE))
+const MASK = WH.ZONE - 1
+
+function roll16(seed: Checksum256Type, str: string): number {
+    const h = hash512(seed, str).array
+    return (h[0] << 8) | h[1]
+}
+function feistelF(seed: Checksum256Type, x: number, round: number, key: string): number {
+    return roll16(seed, `feistel-${key}-${round}-${x}`) & MASK
+}
+export function feistel(seed: Checksum256Type, idx: number, key: string): number {
+    let L = (idx >>> HALF) & MASK
+    let R = idx & MASK
+    for (let r = 0; r < 4; r++) {
+        const nR = L ^ feistelF(seed, R, r, key)
+        L = R
+        R = nR
+    }
+    return (L << HALF) | R
+}
+export function feistelInv(seed: Checksum256Type, idx: number, key: string): number {
+    let L = (idx >>> HALF) & MASK
+    let R = idx & MASK
+    for (let r = 3; r >= 0; r--) {
+        const nL = R ^ feistelF(seed, L, r, key)
+        R = L
+        L = nL
+    }
+    return (L << HALF) | R
+}
+
+type Region = {rx: number; ry: number}
+
+export function regionOf(x: number, y: number): Region {
+    return {rx: Math.floor(x / WH.RSIZE), ry: Math.floor(y / WH.RSIZE)}
+}
+export function partnerRegion(seed: Checksum256Type, R: Region): Region {
+    const qx = Math.floor(R.rx / WH.ZONE)
+    const qy = Math.floor(R.ry / WH.ZONE)
+    const zx = qx * WH.ZONE
+    const zy = qy * WH.ZONE
+    const key = `${qx}:${qy}`
+    const idx = (R.ry - zy) * WH.ZONE + (R.rx - zx)
+    const p = feistelInv(seed, feistel(seed, idx, key) ^ 1, key)
+    return {rx: zx + (p % WH.ZONE), ry: zy + Math.floor(p / WH.ZONE)}
+}
+function regKey(R: Region): string {
+    return `${R.rx}:${R.ry}`
+}
+function pairKey(a: Region, b: Region): string {
+    const ka = regKey(a)
+    const kb = regKey(b)
+    return ka < kb ? `${ka}|${kb}` : `${kb}|${ka}`
+}
+function endpointInRegion(seed: Checksum256Type, R: Region, key: string): {x: number; y: number} {
+    const h = hash512(seed, `wh-endpoint-${key}-${regKey(R)}`).array
+    const ox = ((h[0] << 24) | (h[1] << 16) | (h[2] << 8) | h[3]) >>> 0
+    const oy = ((h[4] << 24) | (h[5] << 16) | (h[6] << 8) | h[7]) >>> 0
+    return {x: R.rx * WH.RSIZE + (ox % WH.RSIZE), y: R.ry * WH.RSIZE + (oy % WH.RSIZE)}
+}
+function dist(a: {x: number; y: number}, b: {x: number; y: number}): number {
+    return Math.sqrt((a.x - b.x) ** 2 + (a.y - b.y) ** 2)
+}
+function inBounds(c: {x: number; y: number}): boolean {
+    return c.x >= COORD_MIN && c.x <= COORD_MAX && c.y >= COORD_MIN && c.y <= COORD_MAX
+}
+type RegionWormhole = {A: {x: number; y: number}; B: {x: number; y: number}} | null
+
+// ~11 sha512 rolls per region; pure in (seed, region), so memoized for A* neighbor probes.
+const regionCache = new Map<string, RegionWormhole>()
+const REGION_CACHE_MAX = 16384
+
+function wormholeOfRegion(seed: Checksum256Type, R: Region): RegionWormhole {
+    const cacheKey = `${seed}:${R.rx}:${R.ry}`
+    const cached = regionCache.get(cacheKey)
+    if (cached !== undefined) return cached
+    const result = deriveWormholeOfRegion(seed, R)
+    if (regionCache.size >= REGION_CACHE_MAX) regionCache.clear()
+    regionCache.set(cacheKey, result)
+    return result
+}
+
+function deriveWormholeOfRegion(seed: Checksum256Type, R: Region): RegionWormhole {
+    const P = partnerRegion(seed, R)
+    if (P.rx === R.rx && P.ry === R.ry) return null
+    const key = pairKey(R, P)
+    if (roll16(seed, `wh-exists-${key}`) >= WH.THRESHOLD) return null
+    const A = endpointInRegion(seed, R, key)
+    const B = endpointInRegion(seed, P, key)
+    if (!inBounds(A) || !inBounds(B)) return null
+    if (dist(A, B) < WH.MIN_REACH) return null
+    return {A, B}
+}
+export function wormholeAtRegionEndpoint(
+    seed: Checksum256Type,
+    rx: number,
+    ry: number
+): {from: {x: number; y: number}; to: {x: number; y: number}} | null {
+    const w = wormholeOfRegion(seed, {rx, ry})
+    if (!w) return null
+    return {from: w.A, to: w.B}
+}
+export function wormholeAt(
+    seed: Checksum256Type,
+    x: number,
+    y: number
+): {x: number; y: number} | null {
+    const w = wormholeOfRegion(seed, regionOf(x, y))
+    if (!w || w.A.x !== x || w.A.y !== y) return null
+    return w.B
+}
+
+// Wormhole mouths (the local A endpoint) within reachTiles of (x,y); regions are RSIZE-wide so only a few overlap.
+export function nearbyWormholes(
+    seed: Checksum256Type,
+    x: number,
+    y: number,
+    reachTiles: number
+): {x: number; y: number}[] {
+    const min = regionOf(x - reachTiles, y - reachTiles)
+    const max = regionOf(x + reachTiles, y + reachTiles)
+    const out: {x: number; y: number}[] = []
+    for (let rx = min.rx; rx <= max.rx; rx++) {
+        for (let ry = min.ry; ry <= max.ry; ry++) {
+            const w = wormholeOfRegion(seed, {rx, ry})
+            if (!w) continue
+            if (w.A.x === x && w.A.y === y) continue
+            if (dist({x, y}, w.A) <= reachTiles) out.push(w.A)
+        }
+    }
+    return out
+}
+export function isValidWormholePair(
+    seed: Checksum256Type,
+    ax: number,
+    ay: number,
+    bx: number,
+    by: number
+): boolean {
+    const to = wormholeAt(seed, ax, ay)
+    return to !== null && to.x === bx && to.y === by
+}