@forgezero/runtime 0.1.0

package/dist/finance/derive.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Declaring a value ForgeZero generates rather than the tenant supplying.
+ *
+ * A tenant that holds a signing key holds the whole risk of holding a signing
+ * key: it appears in their backups, their logs, their heap dumps and their
+ * environment variables. The alternative is that they never have it. They
+ * declare which chain they have activated, ForgeZero derives the key from the
+ * realm master seed, and the only thing that ever crosses back is an ADDRESS.
+ *
+ * This module is the pure half — the specification and the path arithmetic. It
+ * cannot derive anything, because it has no seed and must not: this runs in a
+ * browser and in a tenant's process, and neither is a place a master seed
+ * belongs. The platform half does the derivation and the signing.
+ *
+ * ## Deterministic, so a lost row is not lost money
+ *
+ * The path is a function of the declared fields. Losing the database row loses
+ * the metadata and not the key — re-declaring the same chain and index derives
+ * the same address, and whatever was sent to it is reachable again. A random
+ * key stored next to the row would make that row the only copy.
+ */
+export declare class DeriveError extends Error {
+    readonly code: 'BAD_SPEC' | 'BAD_INDEX' | 'UNSUPPORTED_SCHEME';
+    constructor(code: 'BAD_SPEC' | 'BAD_INDEX' | 'UNSUPPORTED_SCHEME', message: string);
+}
+/** Curves a chain actually verifies against. */
+export declare const SCHEMES: readonly ["secp256k1", "ed25519"];
+export type Scheme = (typeof SCHEMES)[number];
+/**
+ * Who generates the key, which is a real trade-off and not a default.
+ *
+ *   derived    ForgeZero generates it from the realm master seed, on demand,
+ *              and stores NOTHING. There is no key at rest to steal, and a lost
+ *              row is recoverable because the key is a function of the seed and
+ *              the path. The cost: the platform can always regenerate it, so
+ *              the tenant's key is only as private as the ceremony guarding the
+ *              seed.
+ *
+ *   supplied   the tenant generates it — on their own hardware, in their own
+ *              ceremony, however they like — and the vault encrypts and stores
+ *              it. The platform could never have produced this key, which is
+ *              exactly the point for a tenant who needs that to be true. The
+ *              cost: there is now a copy at rest, and losing it loses the key,
+ *              because nothing can regenerate what the platform never derived.
+ *
+ * Both sign the same way and neither ever returns the private half. The choice
+ * is about who is CAPABLE of generating the key, not about how it is used.
+ */
+export declare const CUSTODY: readonly ["derived", "supplied"];
+export type Custody = (typeof CUSTODY)[number];
+/**
+ * How one platform-managed field is produced.
+ *
+ * Carried in the JSON Schema under `x-fz-derive`, so the schema stays the one
+ * description of an entry — a separate list of "which fields are magic" is a
+ * second source of truth that drifts the first time somebody edits one.
+ */
+export interface DeriveSpec {
+    /** Defaults to `derived`: nothing at rest is the safer default to forget. */
+    custody?: Custody;
+    scheme: Scheme;
+    /** BIP-44 coin type. 60 is every EVM chain, 0 is Bitcoin. Derived only. */
+    coinType?: number;
+    account?: number;
+    change?: 0 | 1;
+    /** Address index. Taken from a sibling field when `indexFrom` is set. */
+    index?: number;
+    /**
+     * Read the index from another field of the same entry.
+     *
+     * Lets one schema describe a whole series — a tenant adds an entry with
+     * `index: 7` rather than authoring a seventh schema.
+     */
+    indexFrom?: string;
+    /** What comes back to the tenant. Never the private key, under any value. */
+    expose?: 'address' | 'publicKey';
+}
+export declare const custodyOf: (spec: DeriveSpec) => Custody;
+export declare function assertDeriveSpec(spec: DeriveSpec): void;
+/**
+ * The BIP-44 path this spec resolves to, for one entry's data.
+ *
+ * `m / 44' / coin' / account' / change / index`. Purpose, coin and account are
+ * hardened; change and index are not, so a watch-only public key can enumerate
+ * addresses without exposing the account.
+ */
+export declare function pathFor(spec: DeriveSpec, data?: Record<string, unknown>): string;
+/** The `x-fz-derive` annotation on one property, if it carries one. */
+export declare function deriveSpecOf(property: unknown): DeriveSpec | undefined;
+export interface DerivedField {
+    /** Dotted path into the entry's data. */
+    path: string;
+    spec: DeriveSpec;
+}
+/**
+ * Every field of a schema that ForgeZero fills in.
+ *
+ * Read from the schema rather than configured alongside it, so a field cannot
+ * be derived in one place and expected from the tenant in another.
+ */
+export declare function derivedFields(schema: unknown, prefix?: string): DerivedField[];
+/**
+ * Fields a tenant must NOT send.
+ *
+ * Only the DERIVED ones. Accepting a value for a derived field would let a
+ * caller substitute their own key for the platform's — the entry would look
+ * identical and every signature would come from a key the tenant controls.
+ *
+ * A `supplied` field is the opposite: the tenant is REQUIRED to send it, once,
+ * and it is sealed on arrival.
+ */
+export declare const derivedPaths: (schema: unknown) => readonly string[];
+/** Fields the tenant generates and the vault only seals. */
+export declare const suppliedPaths: (schema: unknown) => readonly string[];
+export declare const DERIVE_KEYWORD: "x-fz-derive";

package/dist/finance/derive.js

@@ -0,0 +1,116 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined")
+    return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/finance/derive.ts
+class DeriveError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "DeriveError";
+  }
+}
+var SCHEMES = ["secp256k1", "ed25519"];
+var CUSTODY = ["derived", "supplied"];
+var HARDENED = 2147483648;
+var assertIndex = (value, what) => {
+  if (!Number.isInteger(value) || value < 0 || value >= HARDENED) {
+    throw new DeriveError("BAD_INDEX", `${what} must be an integer in 0..${HARDENED - 1}.`);
+  }
+  return value;
+};
+var custodyOf = (spec) => spec.custody ?? "derived";
+function assertDeriveSpec(spec) {
+  if (!SCHEMES.includes(spec.scheme)) {
+    throw new DeriveError("UNSUPPORTED_SCHEME", `${spec.scheme} is not a supported curve.`);
+  }
+  if (custodyOf(spec) === "supplied") {
+    if (spec.coinType !== undefined || spec.index !== undefined || spec.indexFrom) {
+      throw new DeriveError("BAD_SPEC", "A supplied key has no derivation path; drop coinType, index and indexFrom.");
+    }
+    return;
+  }
+  if (spec.coinType === undefined) {
+    throw new DeriveError("BAD_SPEC", "A derived key needs a coinType.");
+  }
+  assertIndex(spec.coinType, "coinType");
+  if (spec.account !== undefined)
+    assertIndex(spec.account, "account");
+  if (spec.index !== undefined)
+    assertIndex(spec.index, "index");
+  if (spec.change !== undefined && spec.change !== 0 && spec.change !== 1) {
+    throw new DeriveError("BAD_SPEC", "change is 0 (external) or 1 (internal).");
+  }
+  if (spec.index === undefined && !spec.indexFrom) {
+    throw new DeriveError("BAD_SPEC", "A spec needs an index, or a field to read one from.");
+  }
+  if (spec.index !== undefined && spec.indexFrom) {
+    throw new DeriveError("BAD_SPEC", "Give an index or an indexFrom, never both.");
+  }
+}
+function pathFor(spec, data = {}) {
+  assertDeriveSpec(spec);
+  if (custodyOf(spec) === "supplied") {
+    throw new DeriveError("BAD_SPEC", "A supplied key has no derivation path.");
+  }
+  let index = spec.index;
+  if (spec.indexFrom) {
+    const raw = data[spec.indexFrom];
+    const value = typeof raw === "string" ? Number(raw) : raw;
+    if (typeof value !== "number") {
+      throw new DeriveError("BAD_INDEX", `${spec.indexFrom} is not a number on this entry.`);
+    }
+    index = assertIndex(value, spec.indexFrom);
+  }
+  const account = spec.account ?? 0;
+  const change = spec.change ?? 0;
+  return `m/44'/${spec.coinType}'/${account}'/${change}/${index}`;
+}
+function deriveSpecOf(property) {
+  if (typeof property !== "object" || property === null)
+    return;
+  const spec = property["x-fz-derive"];
+  if (typeof spec !== "object" || spec === null)
+    return;
+  const parsed = spec;
+  assertDeriveSpec(parsed);
+  return parsed;
+}
+function derivedFields(schema, prefix = "") {
+  if (typeof schema !== "object" || schema === null)
+    return [];
+  const properties = schema.properties;
+  if (!properties)
+    return [];
+  const out = [];
+  for (const [name, property] of Object.entries(properties)) {
+    const path = prefix ? `${prefix}.${name}` : name;
+    const spec = deriveSpecOf(property);
+    if (spec)
+      out.push({ path, spec });
+    else
+      out.push(...derivedFields(property, path));
+  }
+  return out;
+}
+var derivedPaths = (schema) => derivedFields(schema).filter((field) => custodyOf(field.spec) === "derived").map((field) => field.path);
+var suppliedPaths = (schema) => derivedFields(schema).filter((field) => custodyOf(field.spec) === "supplied").map((field) => field.path);
+var DERIVE_KEYWORD = "x-fz-derive";
+export {
+  suppliedPaths,
+  pathFor,
+  derivedPaths,
+  derivedFields,
+  deriveSpecOf,
+  custodyOf,
+  assertDeriveSpec,
+  SCHEMES,
+  DeriveError,
+  DERIVE_KEYWORD,
+  CUSTODY
+};

package/dist/finance/discounts.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Promotions and coupons, as arithmetic over integer minor units.
+ *
+ * Two rules carry this module, and both exist because the alternative is a
+ * customer-visible number that nobody can reproduce:
+ *
+ *   they NEVER stack — the single best offer applies
+ *   the result is never negative, and never more than what was owed
+ *
+ * Stacking is where discount systems become unexplainable. Two 50% offers
+ * applied in sequence make 75%, applied together make 100%, and which one a
+ * customer got depends on the order rows came back from a database. Picking one
+ * winner means the invoice can always be explained in a sentence.
+ *
+ * ## Integers throughout
+ *
+ * `Math.round(price * 0.15)` on a float is how an invoice ends in a fraction of
+ * a cent that reconciliation then argues about. Percentages are applied as
+ * `amount * bp / 10_000` on bigints, and the rounding is stated rather than
+ * inherited.
+ */
+export declare class DiscountError extends Error {
+    readonly code: 'BAD_RATE' | 'BAD_AMOUNT' | 'BAD_CODE' | 'BAD_WINDOW';
+    constructor(code: 'BAD_RATE' | 'BAD_AMOUNT' | 'BAD_CODE' | 'BAD_WINDOW', message: string);
+}
+export type DiscountKind = 'percentage' | 'fixed';
+export interface Promotion {
+    /** What a customer types, or the internal name of a seasonal offer. */
+    code: string;
+    label: string;
+    kind: DiscountKind;
+    /**
+     * Basis points for a percentage (1500 = 15%), or minor units for a fixed
+     * amount. Basis points rather than a percent so 12.5% is expressible without
+     * a float anywhere near money.
+     */
+    value: number;
+    /** Epoch seconds. A promotion outside its window does not apply. */
+    startsAtSec?: number;
+    endsAtSec?: number;
+    /** Applies only to invoices at or above this subtotal, in minor units. */
+    minimumAmount?: number;
+    /** A cap on a percentage discount, in minor units. */
+    maximumDiscount?: number;
+    /** Total redemptions allowed. `undefined` is unlimited. */
+    maxRedemptions?: number;
+    redemptions?: number;
+    /** Set when an offer is withdrawn. Kept rather than deleted — invoices refer to it. */
+    withdrawnAtSec?: number;
+    /**
+     * Applies with nobody typing anything.
+     *
+     * A seasonal offer is automatic; a coupon is not. The distinction matters
+     * because an automatic promotion is not once-per-tenant — it is a price for
+     * a period, and treating it as a coupon would let the first invoice of a
+     * quarter consume it for everybody.
+     */
+    automatic?: boolean;
+}
+export interface AppliedDiscount {
+    code: string;
+    label: string;
+    /** Minor units taken off. Never negative, never more than the subtotal. */
+    amount: number;
+    /** What the customer pays after it. */
+    total: number;
+}
+/** Why a promotion did not apply. Returned, not thrown — a miss is normal. */
+export type Ineligibility = 'not-started' | 'expired' | 'withdrawn' | 'below-minimum' | 'exhausted';
+/**
+ * The discount one promotion would take off, before any comparison.
+ *
+ * A percentage rounds DOWN. Rounding a discount up gives away a unit of currency
+ * per invoice, forever, and nobody notices until it is a line in an audit.
+ */
+export declare function discountFor(promotion: Promotion, subtotal: number): number;
+/** Is this promotion usable right now, for this subtotal? */
+export declare function ineligibility(promotion: Promotion, subtotal: number, nowSec: number): Ineligibility | null;
+/**
+ * Pick the single best applicable promotion.
+ *
+ * Never a sum. Ties break on the code so the same inputs always produce the same
+ * winner — an invoice that names a different promotion on a rerun is one nobody
+ * can reconcile, even when the amount matches.
+ */
+export declare function bestDiscount(promotions: readonly Promotion[], subtotal: number, nowSec?: number): AppliedDiscount | null;
+/**
+ * Codes are compared case-insensitively and without spaces.
+ *
+ * People type what was printed on a card. Refusing `SPRING 25` because it was
+ * stored as `spring25` is a support ticket, not a security control — there is
+ * no secret here, only a name.
+ */
+export declare const normaliseCode: (code: string) => string;
+/** A code somebody may type. Refused early so it never reaches a lookup. */
+export declare function assertCode(code: string): void;
+/** A window that ends before it starts is a promotion nobody can ever use. */
+export declare function assertWindow(promotion: Pick<Promotion, 'startsAtSec' | 'endsAtSec'>): void;

package/dist/finance/discounts.js

@@ -0,0 +1,90 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined")
+    return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/finance/discounts.ts
+class DiscountError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "DiscountError";
+  }
+}
+function discountFor(promotion, subtotal) {
+  if (!Number.isInteger(subtotal) || subtotal < 0) {
+    throw new DiscountError("BAD_AMOUNT", "A subtotal is a whole number of minor units.");
+  }
+  if (!Number.isInteger(promotion.value) || promotion.value < 0) {
+    throw new DiscountError("BAD_RATE", `"${promotion.value}" is not a usable discount value.`);
+  }
+  if (promotion.kind === "percentage") {
+    if (promotion.value > 1e4) {
+      throw new DiscountError("BAD_RATE", "A percentage discount cannot exceed 100% (10000bp).");
+    }
+    const raw = Number(BigInt(subtotal) * BigInt(promotion.value) / 10000n);
+    const capped = promotion.maximumDiscount ?? Number.POSITIVE_INFINITY;
+    return Math.min(raw, capped, subtotal);
+  }
+  return Math.min(promotion.value, subtotal);
+}
+function ineligibility(promotion, subtotal, nowSec) {
+  if (promotion.withdrawnAtSec !== undefined && nowSec >= promotion.withdrawnAtSec) {
+    return "withdrawn";
+  }
+  if (promotion.startsAtSec !== undefined && nowSec < promotion.startsAtSec)
+    return "not-started";
+  if (promotion.endsAtSec !== undefined && nowSec >= promotion.endsAtSec)
+    return "expired";
+  if (promotion.minimumAmount !== undefined && subtotal < promotion.minimumAmount) {
+    return "below-minimum";
+  }
+  if (promotion.maxRedemptions !== undefined && (promotion.redemptions ?? 0) >= promotion.maxRedemptions) {
+    return "exhausted";
+  }
+  return null;
+}
+function bestDiscount(promotions, subtotal, nowSec = Math.floor(Date.now() / 1000)) {
+  let best = null;
+  for (const promotion of promotions) {
+    if (ineligibility(promotion, subtotal, nowSec) !== null)
+      continue;
+    const amount = discountFor(promotion, subtotal);
+    if (amount <= 0)
+      continue;
+    if (best === null || amount > best.amount || amount === best.amount && promotion.code < best.code) {
+      best = {
+        code: promotion.code,
+        label: promotion.label,
+        amount,
+        total: subtotal - amount
+      };
+    }
+  }
+  return best;
+}
+var normaliseCode = (code) => code.replace(/\s+/g, "").toUpperCase();
+function assertCode(code) {
+  const normalised = normaliseCode(code);
+  if (!/^[A-Z0-9][A-Z0-9-]{1,31}$/.test(normalised)) {
+    throw new DiscountError("BAD_CODE", "A code is 2–32 characters: letters, digits and hyphens.");
+  }
+}
+function assertWindow(promotion) {
+  if (promotion.startsAtSec !== undefined && promotion.endsAtSec !== undefined && promotion.endsAtSec <= promotion.startsAtSec) {
+    throw new DiscountError("BAD_WINDOW", "A promotion must be usable for a positive interval.");
+  }
+}
+export {
+  normaliseCode,
+  ineligibility,
+  discountFor,
+  bestDiscount,
+  assertWindow,
+  assertCode,
+  DiscountError
+};

package/dist/finance/ledger.d.ts

@@ -0,0 +1,221 @@
+import { type Money } from './money';
+/**
+ * Balances, as postings.
+ *
+ * **This module contains no concurrency control, and that is the design.**
+ *
+ * `@forgezero/runtime/queue` already claims a KEY rather than a message and
+ * carries a `dedupeKey`, which gives the two properties people build a ledger
+ * lock to get: two writes to one account run one after the other because they
+ * share a key, and a retried operation is recognised rather than repeated. A
+ * second mechanism next to that is not extra safety — it is a second thing to
+ * get right, and it is the one that ends up subtly wrong.
+ *
+ * So every write here is expected to be inside `drainKey(accountOwner)`, and
+ * this module is a data model: entries that sum to zero, balances derived from
+ * them.
+ *
+ * ## A hold is a posting, not a lock
+ *
+ * "Available" versus "total" is the reason ledgers grow locking code. Here an
+ * owner has sub-accounts — `available` and `held` — and placing a hold is a
+ * posting between them. `availableOf()` is then an ordinary balance query, and
+ * `requireBalance` in `@forgezero/access/conditions` (which already checks
+ * available rather than total) is the guard with no new code at all.
+ *
+ * ## Why double entry rather than a balance column
+ *
+ * A single column loses the ability to answer *why*. Every movement here has a
+ * counterparty and every transaction sums to zero, so a discrepancy names the
+ * posting that caused it instead of appearing as a number nobody can
+ * reconstruct. It is also what makes a commission split provable: platform
+ * revenue, referrer share and user debit are three legs of one transaction that
+ * must balance, so a split that loses a unit cannot be committed at all.
+ */
+export declare class LedgerError extends Error {
+    readonly code: 'UNBALANCED' | 'EMPTY_TRANSACTION' | 'MIXED_ASSETS' | 'ZERO_ENTRY' | 'UNKNOWN_ACCOUNT' | 'INSUFFICIENT_AVAILABLE';
+    constructor(code: 'UNBALANCED' | 'EMPTY_TRANSACTION' | 'MIXED_ASSETS' | 'ZERO_ENTRY' | 'UNKNOWN_ACCOUNT' | 'INSUFFICIENT_AVAILABLE', message: string);
+}
+/**
+ * The sub-accounts every owner has.
+ *
+ *   available  spendable now
+ *   held       committed to something open — an order, a pending withdrawal
+ *
+ * Splitting them is what removes the need for a lock: the question "is there
+ * enough?" becomes a balance read on one sub-account rather than a balance read
+ * plus a reservation somewhere else.
+ */
+export declare const BUCKETS: readonly ["available", "held"];
+export type Bucket = (typeof BUCKETS)[number];
+/**
+ * Where money can sit.
+ *
+ * `external` is the counterparty for anything crossing the system boundary — a
+ * chain deposit, a card payment. Without it a deposit has one leg and cannot
+ * balance, which is how single-column ledgers start.
+ */
+export declare const ACCOUNT_KINDS: readonly ["user", "platform", "external"];
+export type AccountKind = (typeof ACCOUNT_KINDS)[number];
+export interface AccountRef {
+    kind: AccountKind;
+    /** User key, or a platform account name like `revenue` or `promotions`. */
+    owner: string;
+    bucket?: Bucket;
+}
+/** Canonical string form, so an account is comparable and indexable. */
+export declare const accountId: (account: AccountRef) => string;
+export declare function parseAccount(id: string): AccountRef;
+/**
+ * The queue key for any write touching this account.
+ *
+ * The OWNER, not the sub-account: moving between an owner's available and held
+ * buckets must serialise against every other write for that owner, or a hold
+ * and a withdrawal can interleave and both see the same available balance.
+ *
+ * Exported so callers cannot invent their own convention — two call sites
+ * disagreeing about the key is the same as having no key.
+ */
+export declare const queueKeyFor: (account: AccountRef) => string;
+export interface Entry {
+    account: AccountRef;
+    /** Positive credits the account, negative debits it. */
+    amount: Money;
+}
+export interface Transaction {
+    /**
+     * The idempotency key, and the queue's `dedupeKey`.
+     *
+     * A retry carrying the same reference is the same transaction. This is the
+     * field that makes a redelivered deposit a no-op rather than a double credit.
+     */
+    reference: string;
+    /** `deposit`, `order.fill`, `commission`, `bonus` — read during an incident. */
+    kind: string;
+    entries: readonly Entry[];
+    atMs: number;
+    memo?: string;
+}
+/**
+ * Every transaction sums to zero, per asset.
+ *
+ * Per asset, not overall: a transaction moving BTC and USDT in one breath would
+ * otherwise "balance" by cancelling unrelated currencies against each other,
+ * which is not balance, it is an accident that adds to zero.
+ */
+export declare function assertBalanced(transaction: Pick<Transaction, 'entries'>): void;
+/** Two legs: one account credited, another debited, same asset. */
+export declare function transfer(args: {
+    reference: string;
+    kind: string;
+    from: AccountRef;
+    to: AccountRef;
+    amount: Money;
+    atMs: number;
+    memo?: string;
+}): Transaction;
+/**
+ * Place a hold: available → held, same owner.
+ *
+ * Not a lock. After this posting `availableOf()` returns less, so the next
+ * balance check sees the reduced figure with no reservation table, no expiry
+ * sweeper and no way for a crashed process to strand funds behind a lease.
+ */
+export declare const placeHold: (args: {
+    reference: string;
+    owner: string;
+    kind?: AccountKind;
+    amount: Money;
+    atMs: number;
+    memo?: string;
+}) => Transaction;
+/** Release a hold: held → available. The order was cancelled, nothing moved. */
+export declare const releaseHold: (args: {
+    reference: string;
+    owner: string;
+    kind?: AccountKind;
+    amount: Money;
+    atMs: number;
+}) => Transaction;
+/**
+ * Capture a hold: held → somewhere else. The thing it was held for happened.
+ *
+ * Deliberately separate from `releaseHold`. Collapsing them into one "resolve"
+ * with a flag is how a cancellation ends up paying somebody: the two have
+ * opposite effects and should not share a code path.
+ */
+export declare const captureHold: (args: {
+    reference: string;
+    owner: string;
+    kind?: AccountKind;
+    to: AccountRef;
+    amount: Money;
+    atMs: number;
+    memo?: string;
+}) => Transaction;
+/**
+ * Sum entries into a balance per account and asset.
+ *
+ * Derived rather than stored, because a stored balance and its postings can
+ * disagree — and when they do, nobody can say which is right. Production reads
+ * a cached figure the store maintains; this is what proves the cache correct.
+ */
+export declare function balancesFrom(transactions: readonly Transaction[]): Map<string, Map<string, Money>>;
+export declare function balanceOf(balances: Map<string, Map<string, Money>>, account: AccountRef, asset: string): Money;
+/** Spendable now. What `requireBalance` should be given as `available`. */
+export declare const availableOf: (balances: Map<string, Map<string, Money>>, owner: string, asset: string, kind?: AccountKind) => Money;
+export declare const heldOf: (balances: Map<string, Map<string, Money>>, owner: string, asset: string, kind?: AccountKind) => Money;
+/** Available plus held. What the owner has, not what they can spend. */
+export declare const totalOf: (balances: Map<string, Map<string, Money>>, owner: string, asset: string, kind?: AccountKind) => Money;
+export interface TrialBalance {
+    ok: boolean;
+    perAsset: {
+        asset: string;
+        total: bigint;
+        accounts: number;
+    }[];
+    /** Assets that do not sum to zero, with the discrepancy. */
+    discrepancies: {
+        asset: string;
+        off: bigint;
+    }[];
+}
+/**
+ * Does the whole book balance?
+ *
+ * The check that finds a bug rather than preventing one. Every transaction is
+ * validated on the way in, so a non-zero total here means something wrote
+ * around this module or a row was edited — which is exactly the class of
+ * problem that is invisible until a customer notices.
+ *
+ * Run it on a schedule. A book that balanced yesterday and does not today has a
+ * bounded set of transactions to inspect; one nobody checks has a year of them.
+ */
+export declare function trialBalance(transactions: readonly Transaction[]): TrialBalance;
+/**
+ * A human-readable statement for one account.
+ *
+ * Ordered by time with a running balance, because the question during a dispute
+ * is never "what is the balance" — it is "when did it become that".
+ */
+export declare function statement(transactions: readonly Transaction[], account: AccountRef, asset: string): {
+    atMs: number;
+    reference: string;
+    kind: string;
+    amount: string;
+    balance: string;
+}[];
+/**
+ * Would this leave the account short?
+ *
+ * A convenience for a caller that already holds the balances. The real guard is
+ * `requireBalance` at the route, which returns the right status and the right
+ * body; this exists so a job — which has no request to refuse — can make the
+ * same check without inventing a second answer.
+ */
+export declare function assertAvailable(balances: Map<string, Map<string, Money>>, args: {
+    owner: string;
+    amount: Money;
+    kind?: AccountKind;
+}): void;
+export declare const VERSION = "0.1.0";