@jgengine/core 0.26.0 → 0.28.0

package/dist/economy/loanBook.d.ts

@@ -0,0 +1,182 @@
+import type { TransactionLedger } from "./transactionLedger.js";
+/**
+ * Money in this module is an integer count of **minor units** — cents when the currency has two
+ * decimals, whole coins when it has none. Principal, interest, payments and balances are safe
+ * integers, so a schedule adds up exactly.
+ */
+/** Terms of one loan. Everything a repayment schedule needs, as plain data. */
+export interface LoanTerms {
+    /** Stable id, unique within a loan book. */
+    id: string;
+    /** Integer minor units borrowed; must be `> 0`. */
+    principal: number;
+    /** Interest per period as a fraction of the balance, e.g. `0.05` for 5%. */
+    ratePerPeriod: number;
+    /** Number of scheduled payments; integer `>= 1`. */
+    periods: number;
+    /** Seconds between scheduled payments; must be `> 0`. */
+    periodSeconds: number;
+    /** When the first payment is due, in seconds. */
+    startSeconds: number;
+    /**
+     * `"amortized"` (default) charges interest on the outstanding balance and levels the payment;
+     * `"flat"` charges interest on the original principal and splits principal evenly.
+     */
+    method?: "amortized" | "flat";
+    /** Currency the loan is denominated in; falls back to the book's default. */
+    currency?: string;
+    /** Account that owes and pays; falls back to the book's default. */
+    account?: string;
+}
+/** One scheduled repayment, in integer minor units. */
+export interface LoanPayment {
+    /** 1-based. */
+    index: number;
+    dueSeconds: number;
+    interest: number;
+    principal: number;
+    /** `interest + principal`. */
+    amount: number;
+    /** Remaining principal after this payment. */
+    balanceAfter: number;
+}
+/** A full repayment plan: every payment, its interest/principal split and the running balance. */
+export interface LoanSchedule {
+    id: string;
+    principal: number;
+    method: "amortized" | "flat";
+    payments: readonly LoanPayment[];
+    /** Sum of every payment's interest. */
+    totalInterest: number;
+    /** Sum of every payment. */
+    totalPaid: number;
+}
+/** One live loan: its plan plus how far it has been paid. */
+export interface LoanRecord {
+    id: string;
+    /** The terms it was drawn on, kept whole so a save stores them verbatim. */
+    terms: LoanTerms;
+    principal: number;
+    ratePerPeriod: number;
+    periods: number;
+    currency: string;
+    account: string;
+    schedule: LoanSchedule;
+    /** Payments settled so far. */
+    paid: number;
+    /** Total settled, in minor units, including interest. */
+    paidAmount: number;
+    /** Interest settled so far, in minor units. */
+    interestPaid: number;
+    /** Scheduled payments that came due with no funds, counted once per advance. */
+    missed: number;
+    /** True once `missed` reached the book's limit; a defaulted loan stops being advanced. */
+    defaulted: boolean;
+    /** True once the principal is fully repaid, early or on schedule. */
+    settled: boolean;
+    /** Remaining principal, in minor units. */
+    outstanding: number;
+}
+/** Saved progress of one loan; the schedule is rebuilt from its terms on restore. */
+export interface LoanState {
+    terms: LoanTerms;
+    paid: number;
+    paidAmount: number;
+    interestPaid: number;
+    missed: number;
+    defaulted: boolean;
+    settled: boolean;
+    outstanding: number;
+}
+/** Serializable loan-book state. */
+export interface LoanBookState {
+    loans: readonly LoanState[];
+}
+/** What one {@link LoanBook.advance} settled, and what it could not. */
+export interface LoanAdvanceResult {
+    paid: readonly LoanPayment[];
+    /** Payments that came due with no funds; each counts once per advance. */
+    missed: readonly {
+        id: string;
+        index: number;
+        amount: number;
+    }[];
+    /** Loans that reached the miss limit during this advance. */
+    defaulted: readonly string[];
+}
+/** Counters of a loan book, for a probe or a summary line. */
+export interface LoanBookStats {
+    loans: number;
+    active: number;
+    defaulted: number;
+    settled: number;
+    /** Remaining principal across every loan, in minor units. */
+    outstanding: number;
+    paidAmount: number;
+    interestPaid: number;
+    missed: number;
+}
+/** Outcome of an early repayment. */
+export interface LoanRepayment {
+    ok: boolean;
+    /** Minor units actually applied to principal. */
+    applied: number;
+    outstanding: number;
+    settled: boolean;
+}
+/** Options for {@link createLoanBook}. */
+export interface LoanBookOptions {
+    /** The books every draw, payment and repayment is posted through. */
+    ledger: TransactionLedger;
+    /** Default currency for loans that do not name one. */
+    currency?: string;
+    /** Default owing account for loans that do not name one. */
+    account?: string;
+    /** Due payments that may go unsettled before a loan is defaulted (default `3`). */
+    maxMissed?: number;
+    /** Register a devtools probe under this name reporting {@link LoanBookStats}. */
+    devtoolsName?: string;
+}
+/** The loans a business owes: schedules, interest, arrears and default, posted to a ledger. */
+export interface LoanBook {
+    /** Draw a loan: posts the principal to the borrower's account and schedules the repayments. `null` for unusable terms or an unknown account. */
+    originate(terms: LoanTerms): LoanRecord | null;
+    /** Settle every payment due at or before `nowSeconds`, in loan-id order. */
+    advance(nowSeconds: number): LoanAdvanceResult;
+    /** Pay principal early. Interest already scheduled is unaffected. */
+    repay(loanId: string, amount: number, atSeconds: number): LoanRepayment | null;
+    outstanding(loanId: string): number;
+    /** The next payment due, or `null` when the loan is settled or paid off. */
+    nextPayment(loanId: string): LoanPayment | null;
+    scheduleOf(loanId: string): LoanSchedule | null;
+    loan(loanId: string): LoanRecord | null;
+    loans(): readonly LoanRecord[];
+    snapshot(): LoanBookState;
+    /** Replace state; returns `false` without mutation when the state is malformed. */
+    restore(next: LoanBookState): boolean;
+    stats(): LoanBookStats;
+    reset(): void;
+    /** Drop the devtools probe registered by `devtoolsName`. Safe to call twice. */
+    dispose(): void;
+}
+/**
+ * Build a loan's repayment schedule: one entry per period with its due time, interest/principal
+ * split and the balance left, in integer minor units. An amortized loan levels the payment over
+ * the outstanding balance (`P·i / (1 − (1+i)^−n)`); a flat loan charges interest on the original
+ * principal. Either way the final payment absorbs the rounding, so the principal parts sum to the
+ * principal exactly and the balance ends at zero. Deterministic and pure.
+ *
+ * @capability loan-schedule build a loan's interest and principal repayment schedule in integer minor units
+ */
+export declare function buildLoanSchedule(terms: LoanTerms): LoanSchedule;
+/**
+ * The loans a business owes, over a {@link TransactionLedger}: each draw posts the principal to the
+ * borrower's account, each settled payment posts its interest (`"loan-interest"`) and principal
+ * (`"loan-principal"`) as separate reason-tagged entries, and an early repayment posts
+ * `"loan-repayment"`. A payment that comes due with no funds is left in arrears and counted once
+ * per advance; after `maxMissed` the loan is defaulted and stops being advanced. State is plain
+ * data — `snapshot()` stores terms and progress, and the schedule is rebuilt from the terms.
+ *
+ * @capability loans draw, schedule, service and default a loan with interest, posted to a ledger
+ */
+export declare function createLoanBook(options: LoanBookOptions): LoanBook;

package/dist/economy/loanBook.js

@@ -0,0 +1,303 @@
+import { devtools } from "../devtools/devtools.js";
+function check(condition, message) {
+    if (!condition)
+        throw new RangeError(message);
+}
+function assertTerms(terms) {
+    check(terms.id.trim() !== "", 'Loan field "id" must not be empty');
+    check(Number.isSafeInteger(terms.principal) && terms.principal > 0, `Loan "${terms.id}" principal must be a positive integer in minor units`);
+    check(Number.isFinite(terms.ratePerPeriod) && terms.ratePerPeriod >= 0, `Loan "${terms.id}" ratePerPeriod must be a non-negative finite number`);
+    check(Number.isInteger(terms.periods) && terms.periods >= 1, `Loan "${terms.id}" periods must be an integer >= 1`);
+    check(Number.isFinite(terms.periodSeconds) && terms.periodSeconds > 0, `Loan "${terms.id}" periodSeconds must be positive`);
+    check(Number.isFinite(terms.startSeconds) && terms.startSeconds >= 0, `Loan "${terms.id}" startSeconds must be a non-negative finite number`);
+    const method = terms.method ?? "amortized";
+    check(method === "amortized" || method === "flat", `Loan "${terms.id}" method must be "amortized" or "flat"`);
+}
+/**
+ * Build a loan's repayment schedule: one entry per period with its due time, interest/principal
+ * split and the balance left, in integer minor units. An amortized loan levels the payment over
+ * the outstanding balance (`P·i / (1 − (1+i)^−n)`); a flat loan charges interest on the original
+ * principal. Either way the final payment absorbs the rounding, so the principal parts sum to the
+ * principal exactly and the balance ends at zero. Deterministic and pure.
+ *
+ * @capability loan-schedule build a loan's interest and principal repayment schedule in integer minor units
+ */
+export function buildLoanSchedule(terms) {
+    assertTerms(terms);
+    const method = terms.method ?? "amortized";
+    const periods = terms.periods;
+    const rate = terms.ratePerPeriod;
+    const level = method === "amortized"
+        ? rate === 0
+            ? terms.principal / periods
+            : (terms.principal * rate) / (1 - (1 + rate) ** -periods)
+        : terms.principal / periods + terms.principal * rate;
+    const payment = Math.max(1, Math.round(level));
+    const payments = [];
+    let balance = terms.principal;
+    let totalInterest = 0;
+    let totalPaid = 0;
+    for (let index = 1; index <= periods; index += 1) {
+        const interest = method === "flat" ? Math.round(terms.principal * rate) : Math.round(balance * rate);
+        let principalPart = method === "flat" ? Math.floor(terms.principal / periods) : payment - interest;
+        if (principalPart <= 0)
+            principalPart = 1;
+        if (index === periods || principalPart > balance)
+            principalPart = balance;
+        balance -= principalPart;
+        const amount = interest + principalPart;
+        totalInterest += interest;
+        totalPaid += amount;
+        payments.push({
+            index,
+            dueSeconds: terms.startSeconds + (index - 1) * terms.periodSeconds,
+            interest,
+            principal: principalPart,
+            amount,
+            balanceAfter: balance,
+        });
+    }
+    return { id: terms.id, principal: terms.principal, method, payments, totalInterest, totalPaid };
+}
+/**
+ * The loans a business owes, over a {@link TransactionLedger}: each draw posts the principal to the
+ * borrower's account, each settled payment posts its interest (`"loan-interest"`) and principal
+ * (`"loan-principal"`) as separate reason-tagged entries, and an early repayment posts
+ * `"loan-repayment"`. A payment that comes due with no funds is left in arrears and counted once
+ * per advance; after `maxMissed` the loan is defaulted and stops being advanced. State is plain
+ * data — `snapshot()` stores terms and progress, and the schedule is rebuilt from the terms.
+ *
+ * @capability loans draw, schedule, service and default a loan with interest, posted to a ledger
+ */
+export function createLoanBook(options) {
+    const ledger = options.ledger;
+    const defaultCurrency = options.currency ?? "credits";
+    const defaultAccount = options.account ?? "business";
+    const maxMissed = Math.max(1, Math.floor(options.maxMissed ?? 3));
+    const records = new Map();
+    const probe = options.devtoolsName === undefined
+        ? null
+        : devtools.probes.register(options.devtoolsName, () => readStats());
+    function readStats() {
+        let active = 0;
+        let defaulted = 0;
+        let settled = 0;
+        let outstanding = 0;
+        let paidAmount = 0;
+        let interestPaid = 0;
+        let missed = 0;
+        for (const loan of records.values()) {
+            if (loan.defaulted)
+                defaulted += 1;
+            else if (loan.settled)
+                settled += 1;
+            else
+                active += 1;
+            outstanding += loan.outstanding;
+            paidAmount += loan.paidAmount;
+            interestPaid += loan.interestPaid;
+            missed += loan.missed;
+        }
+        return { loans: records.size, active, defaulted, settled, outstanding, paidAmount, interestPaid, missed };
+    }
+    function settle(loan, payment, at) {
+        const principalPart = Math.min(payment.principal, loan.outstanding);
+        const total = payment.interest + principalPart;
+        if (total <= 0)
+            return true;
+        if (ledger.balanceOf(loan.account, loan.currency) < total)
+            return false;
+        if (payment.interest > 0) {
+            ledger.post({ at, account: loan.account, currency: loan.currency, amount: -payment.interest, reason: "loan-interest", ref: loan.id });
+        }
+        if (principalPart > 0) {
+            ledger.post({ at, account: loan.account, currency: loan.currency, amount: -principalPart, reason: "loan-principal", ref: loan.id });
+        }
+        loan.outstanding -= principalPart;
+        loan.paidAmount += total;
+        loan.interestPaid += payment.interest;
+        loan.paid += 1;
+        if (loan.outstanding <= 0) {
+            loan.outstanding = 0;
+            loan.settled = true;
+        }
+        return true;
+    }
+    return {
+        originate(terms) {
+            try {
+                assertTerms(terms);
+            }
+            catch {
+                return null;
+            }
+            if (records.has(terms.id))
+                return null;
+            const currency = terms.currency ?? defaultCurrency;
+            const account = terms.account ?? defaultAccount;
+            const draw = ledger.post({ at: terms.startSeconds, account, currency, amount: terms.principal, reason: "loan-draw", ref: terms.id });
+            if (!draw.ok)
+                return null;
+            const schedule = buildLoanSchedule(terms);
+            const loan = {
+                id: terms.id,
+                terms: { ...terms, currency, account },
+                principal: terms.principal,
+                ratePerPeriod: terms.ratePerPeriod,
+                periods: terms.periods,
+                currency,
+                account,
+                schedule,
+                paid: 0,
+                paidAmount: 0,
+                interestPaid: 0,
+                missed: 0,
+                defaulted: false,
+                settled: false,
+                outstanding: terms.principal,
+            };
+            records.set(loan.id, loan);
+            return { ...loan };
+        },
+        advance(nowSeconds) {
+            const paid = [];
+            const missed = [];
+            const defaulted = [];
+            for (const id of [...records.keys()].sort()) {
+                const loan = records.get(id);
+                if (loan.settled || loan.defaulted)
+                    continue;
+                for (;;) {
+                    const payment = loan.schedule.payments[loan.paid];
+                    if (payment === undefined || payment.dueSeconds > nowSeconds)
+                        break;
+                    if (settle(loan, payment, payment.dueSeconds)) {
+                        paid.push(payment);
+                        if (loan.settled)
+                            break;
+                        continue;
+                    }
+                    loan.missed += 1;
+                    missed.push({ id: loan.id, index: payment.index, amount: payment.amount });
+                    if (loan.missed >= maxMissed) {
+                        loan.defaulted = true;
+                        defaulted.push(loan.id);
+                    }
+                    break;
+                }
+            }
+            return { paid, missed, defaulted };
+        },
+        repay(loanId, amount, atSeconds) {
+            const loan = records.get(loanId);
+            if (loan === undefined || loan.settled || loan.defaulted)
+                return null;
+            if (!Number.isSafeInteger(amount) || amount <= 0)
+                return null;
+            const applied = Math.min(amount, loan.outstanding);
+            const result = ledger.post({ at: atSeconds, account: loan.account, currency: loan.currency, amount: -applied, reason: "loan-repayment", ref: loan.id });
+            if (!result.ok)
+                return { ok: false, applied: 0, outstanding: loan.outstanding, settled: loan.settled };
+            loan.outstanding -= applied;
+            loan.paidAmount += applied;
+            if (loan.outstanding <= 0) {
+                loan.outstanding = 0;
+                loan.settled = true;
+            }
+            return { ok: true, applied, outstanding: loan.outstanding, settled: loan.settled };
+        },
+        outstanding(loanId) {
+            return records.get(loanId)?.outstanding ?? 0;
+        },
+        nextPayment(loanId) {
+            const loan = records.get(loanId);
+            if (loan === undefined || loan.settled)
+                return null;
+            return loan.schedule.payments[loan.paid] ?? null;
+        },
+        scheduleOf(loanId) {
+            return records.get(loanId)?.schedule ?? null;
+        },
+        loan(loanId) {
+            const loan = records.get(loanId);
+            return loan === undefined ? null : { ...loan };
+        },
+        loans() {
+            return Array.from(records.values(), (loan) => ({ ...loan }));
+        },
+        snapshot() {
+            return {
+                loans: Array.from(records.values(), (loan) => ({
+                    terms: { ...loan.terms },
+                    paid: loan.paid,
+                    paidAmount: loan.paidAmount,
+                    interestPaid: loan.interestPaid,
+                    missed: loan.missed,
+                    defaulted: loan.defaulted,
+                    settled: loan.settled,
+                    outstanding: loan.outstanding,
+                })),
+            };
+        },
+        restore(next) {
+            if (!Array.isArray(next.loans))
+                return false;
+            const restored = new Map();
+            for (const state of next.loans) {
+                if (!Number.isInteger(state.paid) || state.paid < 0)
+                    return false;
+                if (!Number.isInteger(state.paidAmount) || state.paidAmount < 0)
+                    return false;
+                if (!Number.isInteger(state.interestPaid) || state.interestPaid < 0)
+                    return false;
+                if (!Number.isInteger(state.missed) || state.missed < 0)
+                    return false;
+                if (typeof state.defaulted !== "boolean" || typeof state.settled !== "boolean")
+                    return false;
+                if (!Number.isSafeInteger(state.outstanding) || state.outstanding < 0)
+                    return false;
+                let schedule;
+                try {
+                    schedule = buildLoanSchedule(state.terms);
+                }
+                catch {
+                    return false;
+                }
+                if (state.paid > schedule.payments.length)
+                    return false;
+                if (state.outstanding > state.terms.principal)
+                    return false;
+                if (restored.has(state.terms.id))
+                    return false;
+                restored.set(state.terms.id, {
+                    id: state.terms.id,
+                    terms: { ...state.terms },
+                    principal: state.terms.principal,
+                    ratePerPeriod: state.terms.ratePerPeriod,
+                    periods: state.terms.periods,
+                    currency: state.terms.currency ?? defaultCurrency,
+                    account: state.terms.account ?? defaultAccount,
+                    schedule,
+                    paid: state.paid,
+                    paidAmount: state.paidAmount,
+                    interestPaid: state.interestPaid,
+                    missed: state.missed,
+                    defaulted: state.defaulted,
+                    settled: state.settled,
+                    outstanding: state.outstanding,
+                });
+            }
+            records.clear();
+            for (const [id, loan] of restored)
+                records.set(id, loan);
+            return true;
+        },
+        stats: readStats,
+        reset() {
+            records.clear();
+        },
+        dispose() {
+            probe?.();
+        },
+    };
+}

package/dist/economy/market.d.ts

@@ -0,0 +1,161 @@
+/**
+ * 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 price, cost and total is a safe integer, so a
+ * simulation never accumulates float drift; the caller converts at the display boundary.
+ */
+/** One traded good: its reference price, finite stock, demand and price-curve policy. */
+export interface MarketGoodDef {
+    /** Stable id, unique within a market. */
+    id: string;
+    /** Price per unit at the reference stock, in integer minor units. */
+    basePrice: number;
+    /** Units on hand; a non-negative integer. Finite by construction. */
+    stock: number;
+    /** Units buyers want per period at `basePrice`; a non-negative finite number. */
+    demand: number;
+    /** Periods of demand the market wants to hold in stock (default `4`). */
+    coverPeriods?: number;
+    /** Curve exponent: how hard price reacts to a stock/demand gap (default `1`). */
+    elasticity?: number;
+    /** Floor on the price as a fraction of `basePrice` (default `0.25`). */
+    minFactor?: number;
+    /** Ceiling on the price as a fraction of `basePrice` (default `4`). */
+    maxFactor?: number;
+    /** What one unit costs the caller from the market's supplier, in minor units (default `basePrice`). */
+    restockCost?: number;
+}
+/** The mutable half of a good: what a save stores, with the definition kept as authored data. */
+export interface MarketGoodState {
+    id: string;
+    stock: number;
+    demand: number;
+}
+/** Counters and stocks of a market, for a probe or a summary line. */
+export interface MarketStats {
+    goods: number;
+    unitsInStock: number;
+    /** Sum of `stock × price` over every good, in minor units. */
+    stockValue: number;
+    sales: number;
+    unitsSold: number;
+    /** Gross takings, in minor units. */
+    revenue: number;
+    /** Units buyers asked for that stock could not serve. */
+    unmetUnits: number;
+}
+/** Everything a price curve reads: the good's resolved policy plus its live stock and demand. */
+export interface MarketPriceInput {
+    basePrice: number;
+    stock: number;
+    demand: number;
+    /** `coverPeriods × demand` — the stock at which price is `basePrice`. */
+    targetStock: number;
+    elasticity: number;
+    minFactor: number;
+    maxFactor: number;
+}
+/** Serializable market state: the mutable half of every good plus the running counters. */
+export interface MarketSnapshot {
+    goods: readonly MarketGoodState[];
+    counters: {
+        sales: number;
+        unitsSold: number;
+        revenue: number;
+        unmetUnits: number;
+    };
+}
+/** Options for {@link createMarket}: the goods and the price/demand policy they share. */
+export interface MarketConfig {
+    goods?: readonly MarketGoodDef[];
+    /** Periods of demand held in stock when a good does not name its own; default `4`. */
+    coverPeriods?: number;
+    /** Curve exponent when a good does not name its own; default `1`. */
+    elasticity?: number;
+    minFactor?: number;
+    maxFactor?: number;
+    /** Fraction of the gap between current and observed demand adopted per {@link Market.recordDemand} (default `0.5`). */
+    demandSmoothing?: number;
+    /** Weight added to demand per unit buyers asked for and did not get (default `0.5`). */
+    unmetDemandFactor?: number;
+    /** Replace the default price curve; receives the good's resolved inputs. */
+    priceCurve?: (input: MarketPriceInput) => number;
+    /** Register a devtools probe under this name reporting {@link MarketStats}. */
+    devtoolsName?: string;
+}
+/** A served sale: what the buyer paid per unit and in total, in minor units. */
+export interface MarketSale {
+    ok: true;
+    goodId: string;
+    qty: number;
+    unitPrice: number;
+    total: number;
+}
+/** Why a sale could not be served. */
+export interface MarketSaleRejection {
+    ok: false;
+    reason: "unknown-good" | "invalid-qty" | "out-of-stock";
+    /** Units the market could not cover; only present for `"out-of-stock"`. */
+    shortfall?: number;
+}
+/** A sale outcome: the price the buyers paid, or why it could not be served. */
+export type MarketSaleResult = MarketSale | MarketSaleRejection;
+/** A non-mutating read of what a sale would cost and how it would move the price. */
+export interface MarketQuote {
+    goodId: string;
+    qty: number;
+    unitPrice: number;
+    total: number;
+    /** Units that could not be covered from stock. */
+    shortfall: number;
+    /** Unit price after the sale, from the curve — the supply term moving. */
+    nextUnitPrice: number;
+}
+/** A live market: prices from supply and demand over finite stock, with serializable state. */
+export interface Market {
+    /** Unit price in integer minor units. */
+    priceOf(goodId: string): number;
+    /** Price after `qty` more units left stock (a negative `qty` is a delivery), without mutating. */
+    priceAfter(goodId: string, qty: number): number;
+    /** `coverPeriods × demand` — the stock the market wants on hand. */
+    targetStockOf(goodId: string): number;
+    stockOf(goodId: string): number;
+    demandOf(goodId: string): number;
+    /** What one unit costs from the supplier, in minor units. */
+    restockCostOf(goodId: string): number;
+    /** What a sale of `qty` would cost and do to the price; `null` for an unknown good. */
+    quote(goodId: string, qty: number): MarketQuote | null;
+    /** Serve `qty` units to buyers: decrements finite stock and returns the price they paid. */
+    sell(goodId: string, qty: number): MarketSaleResult;
+    /** Take delivery of `qty` units from the supplier, lowering the price. `false` for an unknown good or bad count. */
+    restock(goodId: string, qty: number): boolean;
+    /**
+     * Fold one period of observed buying into demand: smooths it toward what sold and adds
+     * `unmetDemandFactor × unitsUnmet`. This is the demand term of the price curve moving.
+     */
+    recordDemand(goodId: string, unitsSold: number, unitsUnmet?: number): void;
+    /** Set demand directly, e.g. from an authored scenario. */
+    setDemand(goodId: string, demand: number): void;
+    /** Change a good's price policy in play. `false` for an unknown good or an unusable patch. */
+    retune(goodId: string, patch: Partial<Omit<MarketGoodDef, "id" | "stock" | "demand">>): boolean;
+    /** Every good's mutable state, in insertion order. */
+    list(): MarketGoodState[];
+    snapshot(): MarketSnapshot;
+    /** Replace state; returns `false` without mutation when the snapshot is malformed or names an unknown good. */
+    restore(next: MarketSnapshot): boolean;
+    stats(): MarketStats;
+    reset(): void;
+    /** Drop the devtools probe registered by `devtoolsName`. Safe to call twice. */
+    dispose(): void;
+}
+/**
+ * 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 declare function createMarket(config?: MarketConfig): Market;