@jgengine/core 0.29.0 → 0.31.0

package/dist/progression/careerBank.js

@@ -0,0 +1,83 @@
+import { fromMinorUnits, toMinorUnits } from "../economy/currency.js";
+import { charge, createEmptyWallet, grant } from "../economy/wallet.js";
+function sanitizeAmount(value) {
+    return Number.isFinite(value) && value > 0 ? value : 0;
+}
+/**
+ * Money that means something between runs: a persistent balance plus a run's haul that is banked on
+ * a cash-out and lost on a failure. Amounts are snapped to the currency's minor units, so a save
+ * round-trip and a display never drift. Pair it with `economy/upgrades` for a career upgrade tree.
+ *
+ * @capability career-bank persistent career money with a run haul that can be banked or lost
+ */
+export function createCareerBank(config) {
+    const currency = config.currency;
+    const snap = (amount) => fromMinorUnits(currency, toMinorUnits(currency, sanitizeAmount(amount)));
+    const haulCap = config.haulCap === undefined ? Number.POSITIVE_INFINITY : snap(config.haulCap);
+    const walletOf = (bankedAmount) => bankedAmount > 0 ? grant(createEmptyWallet(), currency, bankedAmount) : createEmptyWallet();
+    let wallet = walletOf(snap(config.start ?? 0));
+    let haul = 0;
+    let deposited = 0;
+    let lost = 0;
+    let bestHaul = 0;
+    let runs = 0;
+    const banked = () => wallet.balances[currency.id] ?? 0;
+    if (config.state !== undefined) {
+        wallet = walletOf(snap(config.state.banked));
+        haul = snap(config.state.haul);
+        deposited = snap(config.state.deposited);
+        lost = snap(config.state.lost);
+        bestHaul = snap(config.state.bestHaul);
+        runs = Number.isInteger(config.state.runs) && config.state.runs > 0 ? config.state.runs : 0;
+    }
+    return {
+        currency: () => currency,
+        banked,
+        haul: () => haul,
+        earn(amount) {
+            const added = snap(amount);
+            if (added > 0)
+                haul = snap(Math.min(haul + added, haulCap));
+            return haul;
+        },
+        cashOut() {
+            const held = haul;
+            if (held > 0) {
+                wallet = grant(wallet, currency, held);
+                deposited = snap(deposited + held);
+                bestHaul = Math.max(bestHaul, held);
+            }
+            haul = 0;
+            runs += 1;
+            return { deposited: held, banked: banked() };
+        },
+        loseHaul() {
+            const gone = haul;
+            haul = 0;
+            lost = snap(lost + gone);
+            runs += 1;
+            return { lost: gone, banked: banked() };
+        },
+        spend(amount) {
+            const cost = snap(amount);
+            if (cost <= 0)
+                return false;
+            const paid = charge(wallet, currency, cost);
+            if (paid.status !== "ok")
+                return false;
+            wallet = paid.state;
+            return true;
+        },
+        afford: (amount) => banked() >= snap(amount),
+        counters: () => ({ deposited, lost, bestHaul, runs }),
+        snapshot: () => ({ banked: banked(), haul, deposited, lost, bestHaul, runs }),
+        restore(next) {
+            wallet = walletOf(snap(next.banked));
+            haul = snap(next.haul);
+            deposited = snap(next.deposited);
+            lost = snap(next.lost);
+            bestHaul = snap(next.bestHaul);
+            runs = Number.isInteger(next.runs) && next.runs > 0 ? next.runs : 0;
+        },
+    };
+}

package/dist/progression/gates.d.ts

@@ -0,0 +1,66 @@
+import type { UnlockCatalog } from "../game/unlocks.js";
+import type { Standing, StandingRequirement } from "./standing.js";
+/** What a gate is evaluated against: standing by track and money by currency. */
+export interface GateFacts {
+    standing(trackId: string): number;
+    balance(currency: string): number;
+}
+/** Every condition a gate can require; all named conditions must hold. */
+export interface GateRequirement {
+    standing?: StandingRequirement;
+    /** Smallest balance of `currency` that passes. */
+    balance?: {
+        currency: string;
+        min: number;
+    };
+}
+/**
+ * A milestone: content that opens exactly when its requirements hold and names the unlock it
+ * grants. `unlock` must resolve in the catalog the set is built with, or the set refuses to load.
+ */
+export interface GateDef {
+    id: string;
+    unlock: string;
+    label?: string;
+    category?: string;
+    requires?: GateRequirement;
+}
+/** Which named condition a closed gate still needs. */
+export type GateMiss = "standing" | "balance";
+/** One gate against live facts. */
+export interface GateStatus {
+    gate: GateDef;
+    open: boolean;
+    missing: readonly GateMiss[];
+}
+/** Evaluated gate content: the table, its status against facts, and the grants a caller applies. */
+export interface GateSet {
+    gates(): readonly GateDef[];
+    gate(gateId: string): GateDef | null;
+    status(facts: GateFacts): readonly GateStatus[];
+    isOpen(gateId: string, facts: GateFacts): boolean;
+    open(facts: GateFacts): readonly GateDef[];
+    /** Gates met now whose `unlock` is not in `granted` — the unlocks to grant this pass. */
+    claim(facts: GateFacts, granted: readonly string[]): readonly GateDef[];
+}
+/** Content and the resolvers a {@link GateSet} is built from. */
+export interface GateSetConfig {
+    gates: readonly GateDef[];
+    /** The ids an unlock may resolve to; normally the game's content catalog. */
+    catalog: Pick<UnlockCatalog, "has">;
+    /** The standing a requirement reads; also validates every requirement's track at load. */
+    standing?: Pick<Standing, "hasTrack">;
+}
+/** Read a {@link Standing} and a balance record as {@link GateFacts}. */
+export declare function gateFacts(standing: Pick<Standing, "standing">, actorId: string, balances?: Readonly<Record<string, number>>): GateFacts;
+/** Check an authored gate table against the content it grants; throws `RangeError` naming the gate. */
+export declare function assertGates(config: GateSetConfig): void;
+/**
+ * Authored unlock gates: each one names the unlock it grants and the standing or balance it reads.
+ * Evaluated against caller-supplied facts, so one table serves a single-player save, a server actor
+ * or a probe. Load refuses a gate whose unlock id resolves to nothing (the D3.8 class), so a dead
+ * milestone fails at startup instead of in play. A gate with no requirements is open from the start.
+ *
+ * @capability unlock-gates milestones gated by standing or money, validated against the content they grant
+ */
+export declare function createGateSet(config: GateSetConfig): GateSet;

package/dist/progression/gates.js

@@ -0,0 +1,88 @@
+/** Read a {@link Standing} and a balance record as {@link GateFacts}. */
+export function gateFacts(standing, actorId, balances = {}) {
+    return {
+        standing: (trackId) => standing.standing(actorId, trackId),
+        balance: (currency) => balances[currency] ?? 0,
+    };
+}
+function check(condition, message) {
+    if (!condition)
+        throw new RangeError(message);
+}
+/** Check an authored gate table against the content it grants; throws `RangeError` naming the gate. */
+export function assertGates(config) {
+    const ids = new Set();
+    for (const gate of config.gates) {
+        const id = gate.id.trim();
+        check(id !== "", "Gate id must not be empty");
+        check(!ids.has(id), `Gate "${id}" is declared twice`);
+        ids.add(id);
+        check(gate.unlock.trim() !== "", `Gate "${id}" names an empty unlock`);
+        check(config.catalog.has(gate.unlock), `Gate "${id}" unlocks unknown id "${gate.unlock}" - the reward resolves to nothing`);
+        const standing = gate.requires?.standing;
+        if (standing !== undefined) {
+            check(standing.trackId.trim() !== "", `Gate "${id}" names an empty standing track`);
+            check(config.standing === undefined || config.standing.hasTrack(standing.trackId), `Gate "${id}" reads unknown standing track "${standing.trackId}"`);
+            if (standing.min !== undefined)
+                check(Number.isFinite(standing.min), `Gate "${id}" standing min must be finite`);
+            if (standing.max !== undefined)
+                check(Number.isFinite(standing.max), `Gate "${id}" standing max must be finite`);
+            check(standing.min === undefined || standing.max === undefined || standing.min <= standing.max, `Gate "${id}" needs standing min <= max`);
+        }
+        const balance = gate.requires?.balance;
+        if (balance !== undefined) {
+            check(balance.currency.trim() !== "", `Gate "${id}" names an empty currency`);
+            check(Number.isFinite(balance.min) && balance.min >= 0, `Gate "${id}" balance min must be finite and >= 0`);
+        }
+    }
+}
+function missingFor(gate, facts) {
+    const missing = [];
+    const standing = gate.requires?.standing;
+    if (standing !== undefined) {
+        const value = facts.standing(standing.trackId);
+        if ((standing.min !== undefined && value < standing.min) || (standing.max !== undefined && value > standing.max)) {
+            missing.push("standing");
+        }
+    }
+    const balance = gate.requires?.balance;
+    if (balance !== undefined && facts.balance(balance.currency) < balance.min)
+        missing.push("balance");
+    return missing;
+}
+/**
+ * Authored unlock gates: each one names the unlock it grants and the standing or balance it reads.
+ * Evaluated against caller-supplied facts, so one table serves a single-player save, a server actor
+ * or a probe. Load refuses a gate whose unlock id resolves to nothing (the D3.8 class), so a dead
+ * milestone fails at startup instead of in play. A gate with no requirements is open from the start.
+ *
+ * @capability unlock-gates milestones gated by standing or money, validated against the content they grant
+ */
+export function createGateSet(config) {
+    assertGates(config);
+    const definitions = config.gates.slice();
+    function statusOf(gate, facts) {
+        const missing = missingFor(gate, facts);
+        return { gate, open: missing.length === 0, missing };
+    }
+    return {
+        gates: () => definitions.slice(),
+        gate: (gateId) => definitions.find((gate) => gate.id === gateId) ?? null,
+        status: (facts) => definitions.map((gate) => statusOf(gate, facts)),
+        isOpen(gateId, facts) {
+            const gate = definitions.find((entry) => entry.id === gateId);
+            return gate === undefined ? false : missingFor(gate, facts).length === 0;
+        },
+        open: (facts) => definitions.filter((gate) => missingFor(gate, facts).length === 0),
+        claim(facts, granted) {
+            const out = [];
+            for (const gate of definitions) {
+                if (granted.includes(gate.unlock))
+                    continue;
+                if (missingFor(gate, facts).length === 0)
+                    out.push(gate);
+            }
+            return out;
+        },
+    };
+}

package/dist/progression/standing.d.ts

@@ -0,0 +1,77 @@
+import { type ReputationTier } from "../faction/reputation.js";
+/** One standing track: a faction, a district, a licence board — whatever an authored outcome moves. */
+export interface StandingTrackDef {
+    id: string;
+    label?: string;
+    /** Tiers this track crosses, ascending by `min`; defaults to the shared reputation ladder. */
+    tiers?: readonly ReputationTier[];
+    /** Standing every actor starts at (default `0`). */
+    initial?: number;
+    /** Floor and ceiling; omitted means unbounded. */
+    min?: number;
+    max?: number;
+}
+/** One outcome a game can report, and the standing it moves on each track. */
+export interface StandingOutcomeDef {
+    id: string;
+    label?: string;
+    /** Track id → signed standing. A negative number is the fall. */
+    impacts: Readonly<Record<string, number>>;
+}
+/** Authored standing content: the tracks an actor stands with, and the outcomes that move them. */
+export interface StandingConfig {
+    tracks: readonly StandingTrackDef[];
+    outcomes?: readonly StandingOutcomeDef[];
+}
+/** One track's movement, with the tier on both sides so a caller can announce a crossing. */
+export interface StandingChange {
+    trackId: string;
+    before: number;
+    after: number;
+    delta: number;
+    previousTier: string;
+    tier: string;
+}
+/** A threshold on one track, as an unlock or an upgrade reads it. */
+export interface StandingRequirement {
+    trackId: string;
+    /** Smallest standing that passes; omitted means no floor. */
+    min?: number;
+    /** Largest standing that passes; omitted means no ceiling. */
+    max?: number;
+}
+/** Plain JSON state of a {@link Standing}; tracks left at their authored `initial` are absent. */
+export interface StandingState {
+    records: Record<string, Record<string, number>>;
+}
+/**
+ * Live standing over authored tracks, moved by named outcomes or direct adjustments, with the
+ * tier on each track and a serializable snapshot.
+ */
+export interface Standing {
+    tracks(): readonly StandingTrackDef[];
+    hasTrack(trackId: string): boolean;
+    hasOutcome(outcomeId: string): boolean;
+    standing(actorId: string, trackId: string): number;
+    tier(actorId: string, trackId: string): ReputationTier;
+    /** Every track's standing for one actor, authored tracks included at their initial value. */
+    standings(actorId: string): Record<string, number>;
+    /** Apply an authored outcome; returns each track it moved. Throws on an unknown outcome id. */
+    apply(actorId: string, outcomeId: string): readonly StandingChange[];
+    /** Move one track directly; returns the change. Throws on an unknown track id. */
+    adjust(actorId: string, trackId: string, delta: number): StandingChange;
+    meets(actorId: string, requirement: StandingRequirement): boolean;
+    snapshot(): StandingState;
+    restore(next: StandingState): void;
+}
+/** Check authored standing content before use; throws `RangeError` naming the offending field. */
+export declare function assertStandingConfig(config: StandingConfig): void;
+/**
+ * Per-faction or per-district standing that rises and falls from named outcomes, over authored
+ * tracks. Numbers live in the shared reputation ledger (`faction/reputation`); this adds the
+ * authored outcome table, tier-per-track and the one snapshot a save stores. An outcome id or
+ * track id that resolves to nothing throws at the call, so authored content fails loudly.
+ *
+ * @capability standing per-track standing moved by authored outcomes, with tiers and one snapshot
+ */
+export declare function createStanding(config: StandingConfig): Standing;

package/dist/progression/standing.js

@@ -0,0 +1,151 @@
+import { createReputationLedger, DEFAULT_REPUTATION_TIERS, } from "../faction/reputation.js";
+function check(condition, message) {
+    if (!condition)
+        throw new RangeError(message);
+}
+function isFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+/** Check authored standing content before use; throws `RangeError` naming the offending field. */
+export function assertStandingConfig(config) {
+    const trackIds = new Set();
+    for (const track of config.tracks) {
+        const id = track.id.trim();
+        check(id !== "", "Standing track id must not be empty");
+        check(!trackIds.has(id), `Standing track "${id}" is declared twice`);
+        trackIds.add(id);
+        if (track.min !== undefined)
+            check(isFiniteNumber(track.min), `Standing track "${id}" min must be finite`);
+        if (track.max !== undefined)
+            check(isFiniteNumber(track.max), `Standing track "${id}" max must be finite`);
+        check(track.min === undefined || track.max === undefined || track.min <= track.max, `Standing track "${id}" needs min <= max`);
+        if (track.initial !== undefined) {
+            check(isFiniteNumber(track.initial), `Standing track "${id}" initial must be finite`);
+            check((track.min === undefined || track.initial >= track.min) && (track.max === undefined || track.initial <= track.max), `Standing track "${id}" initial ${track.initial} is outside its bounds`);
+        }
+        const tiers = track.tiers ?? DEFAULT_REPUTATION_TIERS;
+        check(tiers.length > 0, `Standing track "${id}" needs at least one tier`);
+        const tierIds = new Set();
+        for (const tier of tiers) {
+            check(tier.id.trim() !== "", `Standing track "${id}" has a tier with an empty id`);
+            check(!tierIds.has(tier.id), `Standing track "${id}" declares tier "${tier.id}" twice`);
+            check(isFiniteNumber(tier.min), `Standing track "${id}" tier "${tier.id}" min must be finite`);
+            tierIds.add(tier.id);
+        }
+    }
+    const outcomeIds = new Set();
+    for (const outcome of config.outcomes ?? []) {
+        const id = outcome.id.trim();
+        check(id !== "", "Standing outcome id must not be empty");
+        check(!outcomeIds.has(id), `Standing outcome "${id}" is declared twice`);
+        outcomeIds.add(id);
+        const impacts = Object.entries(outcome.impacts);
+        check(impacts.length > 0, `Standing outcome "${id}" moves no track`);
+        for (const [trackId, delta] of impacts) {
+            check(trackIds.has(trackId), `Standing outcome "${id}" names unknown track "${trackId}"`);
+            check(isFiniteNumber(delta), `Standing outcome "${id}" impact on "${trackId}" must be finite`);
+        }
+    }
+}
+/**
+ * Per-faction or per-district standing that rises and falls from named outcomes, over authored
+ * tracks. Numbers live in the shared reputation ledger (`faction/reputation`); this adds the
+ * authored outcome table, tier-per-track and the one snapshot a save stores. An outcome id or
+ * track id that resolves to nothing throws at the call, so authored content fails loudly.
+ *
+ * @capability standing per-track standing moved by authored outcomes, with tiers and one snapshot
+ */
+export function createStanding(config) {
+    assertStandingConfig(config);
+    const tracks = new Map();
+    for (const track of config.tracks)
+        tracks.set(track.id, track);
+    const outcomes = new Map();
+    for (const outcome of config.outcomes ?? [])
+        outcomes.set(outcome.id, outcome);
+    const ledgers = new Map();
+    for (const track of config.tracks) {
+        ledgers.set(track.id, createReputationLedger({
+            tiers: track.tiers ?? DEFAULT_REPUTATION_TIERS,
+            initial: { [track.id]: track.initial ?? 0 },
+            ...(track.min === undefined ? {} : { min: track.min }),
+            ...(track.max === undefined ? {} : { max: track.max }),
+        }));
+    }
+    function ledgerFor(trackId) {
+        const ledger = ledgers.get(trackId);
+        if (ledger === undefined)
+            throw new RangeError(`Standing track "${trackId}" is not authored`);
+        return ledger;
+    }
+    return {
+        tracks: () => config.tracks.slice(),
+        hasTrack: (trackId) => tracks.has(trackId),
+        hasOutcome: (outcomeId) => outcomes.has(outcomeId),
+        standing(actorId, trackId) {
+            return ledgerFor(trackId).standing(actorId, trackId);
+        },
+        tier: (actorId, trackId) => ledgerFor(trackId).tier(actorId, trackId),
+        standings(actorId) {
+            const out = {};
+            for (const trackId of ledgers.keys())
+                out[trackId] = ledgerFor(trackId).standing(actorId, trackId);
+            return out;
+        },
+        apply(actorId, outcomeId) {
+            const outcome = outcomes.get(outcomeId);
+            if (outcome === undefined)
+                throw new RangeError(`Standing outcome "${outcomeId}" is not authored`);
+            const changes = [];
+            for (const [trackId, delta] of Object.entries(outcome.impacts)) {
+                const ledger = ledgerFor(trackId);
+                const before = ledger.standing(actorId, trackId);
+                const previousTier = ledger.tier(actorId, trackId).id;
+                ledger.gain(actorId, trackId, delta);
+                const after = ledger.standing(actorId, trackId);
+                changes.push({ trackId, before, after, delta: after - before, previousTier, tier: ledger.tier(actorId, trackId).id });
+            }
+            return changes;
+        },
+        adjust(actorId, trackId, delta) {
+            const ledger = ledgerFor(trackId);
+            const before = ledger.standing(actorId, trackId);
+            const previousTier = ledger.tier(actorId, trackId).id;
+            ledger.gain(actorId, trackId, delta);
+            const after = ledger.standing(actorId, trackId);
+            return { trackId, before, after, delta: after - before, previousTier, tier: ledger.tier(actorId, trackId).id };
+        },
+        meets(actorId, requirement) {
+            const value = ledgerFor(requirement.trackId).standing(actorId, requirement.trackId);
+            return (requirement.min === undefined || value >= requirement.min) && (requirement.max === undefined || value <= requirement.max);
+        },
+        snapshot() {
+            const records = {};
+            for (const [trackId, ledger] of ledgers) {
+                for (const [actorId, row] of Object.entries(ledger.snapshot().records)) {
+                    const target = records[actorId] ?? (records[actorId] = {});
+                    const value = row[trackId];
+                    if (value !== undefined)
+                        target[trackId] = value;
+                }
+            }
+            return { records };
+        },
+        restore(next) {
+            const byTrack = new Map();
+            for (const [actorId, row] of Object.entries(next.records ?? {})) {
+                for (const [trackId, value] of Object.entries(row)) {
+                    if (!ledgers.has(trackId) || !isFiniteNumber(value))
+                        continue;
+                    const target = byTrack.get(trackId);
+                    if (target === undefined)
+                        byTrack.set(trackId, { [actorId]: { [trackId]: value } });
+                    else
+                        target[actorId] = { [trackId]: value };
+                }
+            }
+            for (const [trackId, ledger] of ledgers)
+                ledger.restore({ records: byTrack.get(trackId) ?? {} });
+        },
+    };
+}

package/dist/progression/upgrades.d.ts

@@ -0,0 +1,70 @@
+import { type Curve } from "../game/progression.js";
+import type { Standing, StandingRequirement } from "./standing.js";
+/**
+ * One upgrade node. Its price is the shared progression {@link Curve} evaluated at the rank being
+ * bought, so a game authors one curve and every rank of every node follows it.
+ */
+export interface UpgradeNodeDef {
+    id: string;
+    label?: string;
+    /** Cost of rank `n`, priced by this curve at `n` (1-based). */
+    cost: Curve;
+    /** Ranks purchasable (default `1`). */
+    maxRank?: number;
+    /** Node ids that must be owned before this one can be bought. */
+    requires?: readonly string[];
+    standing?: StandingRequirement;
+}
+/** Plain JSON state: node id → ranks owned. Nodes at rank `0` are absent. */
+export interface UpgradeState {
+    ranks: Readonly<Record<string, number>>;
+}
+/** Why a purchase was refused; the tree is left untouched on any rejection. */
+export type UpgradeRejection = "unknown-node" | "max-rank" | "missing-prerequisites" | "standing" | "insufficient-funds";
+/** Result of {@link UpgradeTree.buy}: the rank reached and what it cost, or why it was refused. */
+export type UpgradeBuy = {
+    ok: true;
+    nodeId: string;
+    rank: number;
+    cost: number;
+} | {
+    ok: false;
+    reason: UpgradeRejection;
+};
+/** Authored upgrade nodes with a per-node cost curve, prerequisites, a standing gate and one snapshot. */
+export interface UpgradeTree {
+    nodes(): readonly UpgradeNodeDef[];
+    node(nodeId: string): UpgradeNodeDef | null;
+    /** Ranks owned for `nodeId`; `0` when unknown or unowned. */
+    rank(nodeId: string): number;
+    maxRank(nodeId: string): number;
+    /** Price of `rank` (default: the next rank), or `null` when unknown or past the cap. */
+    costOf(nodeId: string, rank?: number): number | null;
+    /** What buying the next rank needs, without changing anything. */
+    canBuy(nodeId: string, actorId: string): UpgradeBuy;
+    /** Buy the next rank, charging `pay` only after every gate passes. */
+    buy(nodeId: string, actorId: string, pay: (cost: number) => boolean): UpgradeBuy;
+    owned(): readonly string[];
+    spendTotal(): number;
+    snapshot(): UpgradeState;
+    restore(next: UpgradeState): void;
+}
+/** Authored nodes plus the standing a node's requirement reads. */
+export interface UpgradeTreeConfig {
+    nodes: readonly UpgradeNodeDef[];
+    /** The standing a node's requirement reads, for both validation and purchase. */
+    standing?: Pick<Standing, "hasTrack" | "standing">;
+    /** Rehydrate from a prior {@link UpgradeTree.snapshot}. */
+    state?: UpgradeState;
+}
+/** Check authored upgrade nodes; throws `RangeError` naming the offending node or field. */
+export declare function assertUpgrades(config: UpgradeTreeConfig): void;
+/**
+ * An upgrade tree whose prices come from the shared curve primitive: each node authors one cost
+ * curve, each rank is that curve at the rank, and a purchase passes prerequisites, a standing gate
+ * and the caller's own payment step. State is one rank map that JSON round-trips, so a career save
+ * stores what a player paid for rather than the arithmetic behind it.
+ *
+ * @capability upgrade-tree ranked upgrades priced by a cost curve, gated by prerequisites and standing
+ */
+export declare function createUpgradeTree(config: UpgradeTreeConfig): UpgradeTree;

package/dist/progression/upgrades.js

@@ -0,0 +1,128 @@
+import { evalCurve } from "../game/progression.js";
+function check(condition, message) {
+    if (!condition)
+        throw new RangeError(message);
+}
+/** Check authored upgrade nodes; throws `RangeError` naming the offending node or field. */
+export function assertUpgrades(config) {
+    const nodes = new Set();
+    for (const node of config.nodes) {
+        const id = node.id.trim();
+        check(id !== "", "Upgrade node id must not be empty");
+        check(!nodes.has(id), `Upgrade node "${id}" is declared twice`);
+        nodes.add(id);
+        const maxRank = node.maxRank ?? 1;
+        check(Number.isInteger(maxRank) && maxRank >= 1, `Upgrade node "${id}" maxRank must be an integer >= 1`);
+        for (let rank = 1; rank <= maxRank; rank += 1) {
+            const cost = evalCurve(node.cost, rank);
+            check(Number.isFinite(cost) && cost >= 0, `Upgrade node "${id}" cost at rank ${rank} must be finite and >= 0`);
+        }
+        const standing = node.standing;
+        if (standing !== undefined) {
+            check(standing.trackId.trim() !== "", `Upgrade node "${id}" names an empty standing track`);
+            check(config.standing === undefined || config.standing.hasTrack(standing.trackId), `Upgrade node "${id}" reads unknown standing track "${standing.trackId}"`);
+            check(standing.min === undefined || standing.max === undefined || standing.min <= standing.max, `Upgrade node "${id}" needs standing min <= max`);
+        }
+    }
+    for (const node of config.nodes) {
+        check(!(node.requires ?? []).includes(node.id), `Upgrade node "${node.id}" requires itself`);
+        for (const required of node.requires ?? []) {
+            check(nodes.has(required), `Upgrade node "${node.id}" requires unknown node "${required}"`);
+        }
+    }
+}
+/**
+ * An upgrade tree whose prices come from the shared curve primitive: each node authors one cost
+ * curve, each rank is that curve at the rank, and a purchase passes prerequisites, a standing gate
+ * and the caller's own payment step. State is one rank map that JSON round-trips, so a career save
+ * stores what a player paid for rather than the arithmetic behind it.
+ *
+ * @capability upgrade-tree ranked upgrades priced by a cost curve, gated by prerequisites and standing
+ */
+export function createUpgradeTree(config) {
+    assertUpgrades(config);
+    const definitions = config.nodes.slice();
+    const byId = new Map();
+    for (const node of definitions)
+        byId.set(node.id, node);
+    const ranks = new Map();
+    let spent = 0;
+    function load(state) {
+        ranks.clear();
+        spent = 0;
+        for (const [nodeId, rank] of Object.entries(state.ranks ?? {})) {
+            const node = byId.get(nodeId);
+            if (node === undefined || !Number.isInteger(rank) || rank <= 0)
+                continue;
+            const capped = Math.min(rank, node.maxRank ?? 1);
+            ranks.set(nodeId, capped);
+            for (let index = 1; index <= capped; index += 1)
+                spent += evalCurve(node.cost, index);
+        }
+    }
+    if (config.state !== undefined)
+        load(config.state);
+    const rankOf = (nodeId) => ranks.get(nodeId) ?? 0;
+    function costAt(node, rank) {
+        if (!Number.isInteger(rank) || rank < 1 || rank > (node.maxRank ?? 1))
+            return null;
+        return evalCurve(node.cost, rank);
+    }
+    function checkBuy(node, actorId) {
+        const current = rankOf(node.id);
+        if (current >= (node.maxRank ?? 1))
+            return { ok: false, reason: "max-rank" };
+        const missing = (node.requires ?? []).filter((required) => rankOf(required) < 1);
+        if (missing.length > 0)
+            return { ok: false, reason: "missing-prerequisites" };
+        const standing = node.standing;
+        if (standing !== undefined) {
+            const reader = config.standing;
+            if (reader === undefined)
+                return { ok: false, reason: "standing" };
+            const value = reader.standing(actorId, standing.trackId);
+            if ((standing.min !== undefined && value < standing.min) || (standing.max !== undefined && value > standing.max)) {
+                return { ok: false, reason: "standing" };
+            }
+        }
+        const cost = costAt(node, current + 1);
+        if (cost === null)
+            return { ok: false, reason: "max-rank" };
+        return { ok: true, nodeId: node.id, rank: current + 1, cost };
+    }
+    return {
+        nodes: () => definitions.slice(),
+        node: (nodeId) => byId.get(nodeId) ?? null,
+        rank: rankOf,
+        maxRank: (nodeId) => byId.get(nodeId)?.maxRank ?? 0,
+        costOf(nodeId, rank) {
+            const node = byId.get(nodeId);
+            if (node === undefined)
+                return null;
+            return costAt(node, rank ?? rankOf(nodeId) + 1);
+        },
+        canBuy: (nodeId, actorId) => {
+            const node = byId.get(nodeId);
+            if (node === undefined)
+                return { ok: false, reason: "unknown-node" };
+            return checkBuy(node, actorId);
+        },
+        buy(nodeId, actorId, pay) {
+            const node = byId.get(nodeId);
+            if (node === undefined)
+                return { ok: false, reason: "unknown-node" };
+            const checkResult = checkBuy(node, actorId);
+            if (!checkResult.ok)
+                return checkResult;
+            if (!pay(checkResult.cost))
+                return { ok: false, reason: "insufficient-funds" };
+            ranks.set(nodeId, checkResult.rank);
+            spent += checkResult.cost;
+            return checkResult;
+        },
+        owned: () => Array.from(ranks.keys()),
+        spendTotal: () => spent,
+        snapshot: () => ({ ranks: Object.fromEntries(ranks) }),
+        restore: load,
+    };
+}