@jgengine/core 0.26.0 → 0.28.0

package/dist/economy/market.js

@@ -0,0 +1,248 @@
+import { devtools } from "../devtools/devtools.js";
+function check(condition, message) {
+    if (!condition)
+        throw new RangeError(message);
+}
+function isMinorUnits(value) {
+    return Number.isSafeInteger(value);
+}
+function assertGood(def, config, seen) {
+    check(def.id.trim() !== "", 'Market good field "id" must not be empty');
+    check(!seen.has(def.id), `Market good "${def.id}" is declared twice`);
+    seen.add(def.id);
+    check(isMinorUnits(def.basePrice) && def.basePrice > 0, `Market good "${def.id}" basePrice must be a positive integer in minor units`);
+    check(Number.isInteger(def.stock) && def.stock >= 0, `Market good "${def.id}" stock must be a non-negative integer`);
+    check(Number.isFinite(def.demand) && def.demand >= 0, `Market good "${def.id}" demand must be a non-negative finite number`);
+    const cover = def.coverPeriods ?? config.coverPeriods ?? 4;
+    check(Number.isFinite(cover) && cover > 0, `Market good "${def.id}" coverPeriods must be positive`);
+    const elasticity = def.elasticity ?? config.elasticity ?? 1;
+    check(Number.isFinite(elasticity) && elasticity > 0, `Market good "${def.id}" elasticity must be positive`);
+    const minFactor = def.minFactor ?? config.minFactor ?? 0.25;
+    const maxFactor = def.maxFactor ?? config.maxFactor ?? 4;
+    check(minFactor > 0 && maxFactor >= minFactor, `Market good "${def.id}" needs 0 < minFactor <= maxFactor`);
+    const cost = def.restockCost ?? def.basePrice;
+    check(isMinorUnits(cost) && cost >= 0, `Market good "${def.id}" restockCost must be a non-negative integer in minor units`);
+}
+/** The default price curve: `basePrice × (targetStock / stock)^elasticity`, clamped to the factor bounds. */
+function defaultPrice(input) {
+    const scarcity = input.targetStock / Math.max(1, input.stock);
+    const raw = input.basePrice * scarcity ** input.elasticity;
+    const floor = input.basePrice * input.minFactor;
+    const ceiling = input.basePrice * input.maxFactor;
+    return Math.round(Math.max(floor, Math.min(ceiling, raw)));
+}
+/**
+ * A market whose price comes from supply and demand over finite stock, as plain serializable state.
+ *
+ * The stated curve is `price = clamp(basePrice × (coverPeriods × demand / max(stock, 1))^elasticity)`
+ * between `basePrice × minFactor` and `basePrice × maxFactor`. Both terms are live: selling thins
+ * stock and raises the price, restocking lowers it, and `recordDemand` moves demand from what
+ * buyers actually took and could not take. `priceCurve` replaces the curve, and `retune` changes a
+ * good's policy in play. Money is integer minor units throughout.
+ *
+ * @capability supply-demand-pricing price goods from finite stock and live demand on a stated curve
+ */
+export function createMarket(config = {}) {
+    const records = new Map();
+    const seen = new Set();
+    for (const def of config.goods ?? []) {
+        assertGood(def, config, seen);
+        records.set(def.id, {
+            id: def.id,
+            basePrice: def.basePrice,
+            coverPeriods: def.coverPeriods ?? config.coverPeriods ?? 4,
+            elasticity: def.elasticity ?? config.elasticity ?? 1,
+            minFactor: def.minFactor ?? config.minFactor ?? 0.25,
+            maxFactor: def.maxFactor ?? config.maxFactor ?? 4,
+            restockCost: def.restockCost ?? def.basePrice,
+            stock: def.stock,
+            demand: def.demand,
+        });
+    }
+    const demandSmoothing = config.demandSmoothing ?? 0.5;
+    const unmetDemandFactor = config.unmetDemandFactor ?? 0.5;
+    const curve = config.priceCurve ?? defaultPrice;
+    let counters = { sales: 0, unitsSold: 0, revenue: 0, unmetUnits: 0 };
+    const inputsOf = (record, stock) => ({
+        basePrice: record.basePrice,
+        stock,
+        demand: record.demand,
+        targetStock: record.coverPeriods * record.demand,
+        elasticity: record.elasticity,
+        minFactor: record.minFactor,
+        maxFactor: record.maxFactor,
+    });
+    const priceAt = (record, stock) => Math.round(curve(inputsOf(record, stock)));
+    const readGoods = () => Array.from(records.values(), (record) => ({ id: record.id, stock: record.stock, demand: record.demand }));
+    const probe = config.devtoolsName === undefined
+        ? null
+        : devtools.probes.register(config.devtoolsName, () => readStats());
+    function readStats() {
+        let unitsInStock = 0;
+        let stockValue = 0;
+        for (const record of records.values()) {
+            unitsInStock += record.stock;
+            stockValue += record.stock * priceAt(record, record.stock);
+        }
+        return { goods: records.size, unitsInStock, stockValue, ...counters };
+    }
+    return {
+        priceOf(goodId) {
+            const record = records.get(goodId);
+            return record === undefined ? 0 : priceAt(record, record.stock);
+        },
+        priceAfter(goodId, qty) {
+            const record = records.get(goodId);
+            if (record === undefined)
+                return 0;
+            const moved = Number.isFinite(qty) ? qty : 0;
+            return priceAt(record, Math.max(0, record.stock - moved));
+        },
+        targetStockOf(goodId) {
+            const record = records.get(goodId);
+            return record === undefined ? 0 : record.coverPeriods * record.demand;
+        },
+        stockOf(goodId) {
+            return records.get(goodId)?.stock ?? 0;
+        },
+        demandOf(goodId) {
+            return records.get(goodId)?.demand ?? 0;
+        },
+        restockCostOf(goodId) {
+            return records.get(goodId)?.restockCost ?? 0;
+        },
+        quote(goodId, qty) {
+            const record = records.get(goodId);
+            if (record === undefined)
+                return null;
+            const unitPrice = priceAt(record, record.stock);
+            const served = Math.max(0, Math.min(qty, record.stock));
+            return {
+                goodId,
+                qty,
+                unitPrice,
+                total: unitPrice * served,
+                shortfall: qty - served,
+                nextUnitPrice: priceAt(record, record.stock - served),
+            };
+        },
+        sell(goodId, qty) {
+            const record = records.get(goodId);
+            if (record === undefined)
+                return { ok: false, reason: "unknown-good" };
+            if (!Number.isInteger(qty) || qty < 1)
+                return { ok: false, reason: "invalid-qty" };
+            if (qty > record.stock)
+                return { ok: false, reason: "out-of-stock", shortfall: qty - record.stock };
+            const unitPrice = priceAt(record, record.stock);
+            record.stock -= qty;
+            counters = {
+                sales: counters.sales + 1,
+                unitsSold: counters.unitsSold + qty,
+                revenue: counters.revenue + unitPrice * qty,
+                unmetUnits: counters.unmetUnits,
+            };
+            return { ok: true, goodId, qty, unitPrice, total: unitPrice * qty };
+        },
+        restock(goodId, qty) {
+            const record = records.get(goodId);
+            if (record === undefined)
+                return false;
+            if (!Number.isInteger(qty) || qty < 1)
+                return false;
+            record.stock += qty;
+            return true;
+        },
+        recordDemand(goodId, unitsSold, unitsUnmet = 0) {
+            const record = records.get(goodId);
+            if (record === undefined)
+                return;
+            const sold = Number.isFinite(unitsSold) ? Math.max(0, unitsSold) : 0;
+            const unmet = Number.isFinite(unitsUnmet) ? Math.max(0, unitsUnmet) : 0;
+            const smoothed = record.demand + demandSmoothing * (sold - record.demand);
+            record.demand = Math.max(0, smoothed + unmetDemandFactor * unmet);
+            if (unmet > 0)
+                counters = { ...counters, unmetUnits: counters.unmetUnits + unmet };
+        },
+        setDemand(goodId, demand) {
+            const record = records.get(goodId);
+            if (record === undefined)
+                return;
+            check(Number.isFinite(demand) && demand >= 0, `Market good "${goodId}" demand must be a non-negative finite number`);
+            record.demand = demand;
+        },
+        retune(goodId, patch) {
+            const record = records.get(goodId);
+            if (record === undefined)
+                return false;
+            const merged = {
+                id: goodId,
+                basePrice: patch.basePrice ?? record.basePrice,
+                stock: record.stock,
+                demand: record.demand,
+                coverPeriods: patch.coverPeriods ?? record.coverPeriods,
+                elasticity: patch.elasticity ?? record.elasticity,
+                minFactor: patch.minFactor ?? record.minFactor,
+                maxFactor: patch.maxFactor ?? record.maxFactor,
+                restockCost: patch.restockCost ?? record.restockCost,
+            };
+            try {
+                assertGood(merged, config, new Set());
+            }
+            catch {
+                return false;
+            }
+            record.basePrice = merged.basePrice;
+            record.coverPeriods = merged.coverPeriods ?? record.coverPeriods;
+            record.elasticity = merged.elasticity ?? record.elasticity;
+            record.minFactor = merged.minFactor ?? record.minFactor;
+            record.maxFactor = merged.maxFactor ?? record.maxFactor;
+            record.restockCost = merged.restockCost ?? record.restockCost;
+            return true;
+        },
+        list: readGoods,
+        snapshot() {
+            return { goods: readGoods(), counters: { ...counters } };
+        },
+        restore(next) {
+            if (!Array.isArray(next.goods))
+                return false;
+            const restored = [];
+            for (const good of next.goods) {
+                const record = records.get(good.id);
+                if (record === undefined)
+                    return false;
+                if (!Number.isInteger(good.stock) || good.stock < 0)
+                    return false;
+                if (!Number.isFinite(good.demand) || good.demand < 0)
+                    return false;
+                restored.push({ id: good.id, stock: good.stock, demand: good.demand });
+            }
+            const countersIn = next.counters;
+            if (countersIn === undefined ||
+                !Number.isInteger(countersIn.sales) || countersIn.sales < 0 ||
+                !Number.isInteger(countersIn.unitsSold) || countersIn.unitsSold < 0 ||
+                !isMinorUnits(countersIn.revenue) ||
+                !Number.isInteger(countersIn.unmetUnits) || countersIn.unmetUnits < 0)
+                return false;
+            for (const good of restored) {
+                const record = records.get(good.id);
+                record.stock = good.stock;
+                record.demand = good.demand;
+            }
+            counters = { ...countersIn };
+            return true;
+        },
+        stats: readStats,
+        reset() {
+            for (const record of records.values()) {
+                record.stock = 0;
+                record.demand = 0;
+            }
+            counters = { sales: 0, unitsSold: 0, revenue: 0, unmetUnits: 0 };
+        },
+        dispose() {
+            probe?.();
+        },
+    };
+}

package/dist/economy/transactionLedger.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Money in this module is an integer count of **minor units** — cents when the currency has two
+ * decimals, whole coins when it has none. Every posted amount and every balance is a safe integer,
+ * so a long simulation never accumulates float drift. `currency` is a free string the game owns.
+ */
+/**
+ * One recorded movement of money. Every post keeps the balance it produced and the reason it
+ * happened, so a summary or a post-mortem reads the books rather than reconstructing them.
+ */
+export interface LedgerEntry {
+    /** 1-based, monotonic within the ledger. */
+    seq: number;
+    /** Caller clock, in seconds. */
+    at: number;
+    account: string;
+    currency: string;
+    /** Signed integer minor units; negative debits the account, positive credits it. */
+    amount: number;
+    /** The account's balance in this currency after the entry was applied. */
+    balanceAfter: number;
+    /** Caller-owned reason code — `"sale"`, `"upkeep"`, `"loan-interest"`. Never interpreted here. */
+    reason: string;
+    /** Optional id of what caused the entry — a good, an order, a loan. */
+    ref?: string;
+}
+/** A post to attempt. */
+export interface LedgerPostInput {
+    at: number;
+    account: string;
+    currency: string;
+    /** Signed integer minor units. */
+    amount: number;
+    reason: string;
+    ref?: string;
+    /** `true` allows any negative balance, `{ max }` caps how far into the red the post may go. */
+    overdraft?: boolean | {
+        max: number;
+    };
+}
+/** Outcome of {@link TransactionLedger.post}. A rejection leaves every balance untouched. */
+export type LedgerPostResult = {
+    ok: true;
+    entry: LedgerEntry;
+} | {
+    ok: false;
+    reason: "unknown-account" | "invalid-amount" | "invalid-reason" | "insufficient-funds";
+};
+/** A recurring charge — upkeep, rent, a subscription — settled by {@link TransactionLedger.chargeDue}. */
+export interface RecurringCharge {
+    /** Stable id, unique within the ledger. */
+    id: string;
+    account: string;
+    currency: string;
+    /** Positive integer minor units charged each cadence. */
+    amountPerPeriod: number;
+    /** Cadence in seconds; must be `> 0`. */
+    everySeconds: number;
+    /** First due time in seconds; defaults to the ledger clock when the charge is added. */
+    startSeconds?: number;
+    reason: string;
+    ref?: string;
+    /** How cycles that came due between two advances are settled: `"each"` (default), `"sum"`, `"skip"`. */
+    catchUp?: "each" | "sum" | "skip";
+    /** Due cycles beyond this in one advance are dropped rather than settled. */
+    maxCatchUp?: number;
+}
+/** Mutable per-charge progress, kept apart from the {@link RecurringCharge} definition. */
+export interface ChargeCursor {
+    nextDueSeconds: number;
+    fired: number;
+    /** Cycles that came due and could not be settled for lack of funds. */
+    missed: number;
+    done: boolean;
+}
+/** What one reason code did to the books, kept across entry trimming. */
+export interface LedgerTotals {
+    count: number;
+    /** Sum of the signed amounts posted under this reason, in minor units. */
+    net: number;
+}
+/** Counters of a ledger, for a probe or a summary line. */
+export interface LedgerStats {
+    accounts: number;
+    entries: number;
+    charges: number;
+    seq: number;
+}
+/** Fully serializable ledger state: clock, balances, journal, totals, charges and cursors. */
+export interface LedgerState {
+    nowSeconds: number;
+    accounts: Record<string, Record<string, number>>;
+    entries: readonly LedgerEntry[];
+    totals: Record<string, LedgerTotals>;
+    charges: Record<string, RecurringCharge>;
+    cursors: Record<string, ChargeCursor>;
+    seq: number;
+}
+/** What one {@link TransactionLedger.chargeDue} settled, and what it could not. */
+export interface LedgerAdvanceResult {
+    charged: readonly LedgerEntry[];
+    /** Charges that came due with no funds, and how many cycles were missed. */
+    missed: readonly {
+        id: string;
+        cycles: number;
+    }[];
+}
+/** A filter over the journal. */
+export interface LedgerEntryFilter {
+    account?: string;
+    reason?: string;
+    /** Only entries at or after this time. */
+    since?: number;
+    /** Keep at most this many of the most recent matches. */
+    limit?: number;
+}
+/** Options for {@link createTransactionLedger}. */
+export interface TransactionLedgerOptions {
+    /** Journal entries retained; older ones drop and live on in {@link LedgerTotals} (default `1024`). */
+    maxEntries?: number;
+    /** Safety bound on cycles settled per charge per advance (default `256`). */
+    maxCyclesPerAdvance?: number;
+    /** Register a devtools probe under this name reporting {@link LedgerStats} and per-reason totals. */
+    devtoolsName?: string;
+}
+/** The books: balances with a reason-tagged journal, and recurring charges on a cadence. */
+export interface TransactionLedger {
+    /** Create an account/currency pair, or add a currency to an existing account. An existing balance is kept. */
+    openAccount(account: string, currency: string, initial?: number): void;
+    balanceOf(account: string, currency: string): number;
+    /** Record one movement of money. Rejected without mutation when the account is unknown, the amount unusable, or funds are short. */
+    post(input: LedgerPostInput): LedgerPostResult;
+    /** Register a recurring charge. `false` for a duplicate id or unusable terms. */
+    addCharge(charge: RecurringCharge): boolean;
+    /** Remove a recurring charge and its cursor. `false` if it was not registered. */
+    removeCharge(id: string): boolean;
+    /** Advance the clock, settling every charge due at or before `nowSeconds` in sorted-id order. */
+    chargeDue(nowSeconds: number): LedgerAdvanceResult;
+    /** Journal entries, newest last, filtered and capped. Copies, safe to retain. */
+    entries(filter?: LedgerEntryFilter): LedgerEntry[];
+    /** Per-reason counts and net amounts over the ledger's whole life. */
+    totals(): Record<string, LedgerTotals>;
+    accounts(): Record<string, Record<string, number>>;
+    snapshot(): LedgerState;
+    /** Replace state; returns `false` without mutation when the state is malformed. */
+    restore(next: LedgerState): boolean;
+    stats(): LedgerStats;
+    reset(): void;
+    /** Drop the devtools probe registered by `devtoolsName`. Safe to call twice. */
+    dispose(): void;
+}
+/**
+ * The books a business keeps: per-account, per-currency balances in integer minor units with a
+ * journal that records every movement, the balance it produced and the reason it happened.
+ * {@link TransactionLedger.post} is the one money path — sales, purchases, upkeep and loan
+ * payments all go through it, so nothing moves without a reason on the record.
+ * {@link TransactionLedger.chargeDue} settles recurring charges (upkeep, rent) on their own
+ * cadence, bounded per advance; a cycle with no funds is counted as missed instead of overdrawing.
+ * Journal memory is bounded by `maxEntries`, with `totals()` keeping the per-reason summary beyond it.
+ *
+ * @capability transaction-ledger record every money movement with its reason over per-account integer minor-unit balances
+ */
+export declare function createTransactionLedger(options?: TransactionLedgerOptions): TransactionLedger;