@forgezero/runtime 0.1.0

package/dist/finance/tax.d.ts

@@ -0,0 +1,132 @@
+import { type Money, type Rounding } from './money';
+/**
+ * What tax is due, where, and who accounts for it.
+ *
+ * Rates are DATA, never constants here. VAT changes by ministerial decree with
+ * weeks of notice, and a rate compiled into a package means a release to comply
+ * with a law that already applies. What this owns is the mechanism: which
+ * jurisdiction may tax a sale, whether the seller or the buyer accounts for it,
+ * and how the figure is rounded.
+ *
+ * ## The three ways to be zero, which are not the same
+ *
+ *   zero-rated     taxable at 0%. Appears on a return, and input tax is
+ *                  recoverable.
+ *   exempt         outside the tax's scope. Also 0% on the invoice, and input
+ *                  tax is NOT recoverable.
+ *   reverse charge the buyer accounts for it, not the seller. 0% charged, and
+ *                  the invoice must SAY SO or it is not a valid invoice.
+ *
+ * Collapsing them into "tax: 0" produces correct-looking invoices and an
+ * unfilable return. They are distinct here for that reason alone.
+ *
+ * ## Place of supply
+ *
+ * For digital services sold to a consumer, tax is due where the CUSTOMER is,
+ * not where the seller is. Getting this backwards is the single most common
+ * cross-border invoicing error, and it under-collects in exactly the
+ * jurisdictions most likely to audit.
+ */
+export declare class TaxError extends Error {
+    readonly code: 'UNKNOWN_JURISDICTION' | 'BAD_RATE' | 'NO_COUNTRY' | 'INCONSISTENT';
+    constructor(code: 'UNKNOWN_JURISDICTION' | 'BAD_RATE' | 'NO_COUNTRY' | 'INCONSISTENT', message: string);
+}
+export declare const TREATMENTS: readonly ["standard", "zero-rated", "exempt", "reverse-charge", "outside-scope"];
+export type Treatment = (typeof TREATMENTS)[number];
+export interface TaxRate {
+    /** ISO 3166-1 alpha-2, uppercase. */
+    country: string;
+    /** Sub-jurisdiction where one taxes separately — a US state, a CA province. */
+    region?: string;
+    /** `VAT`, `GST`, `sales`. Named because it must appear on the invoice. */
+    label: string;
+    /** Percent as a decimal string: `'0.20'` is 20%. Never a float. */
+    rate: string;
+    /** Businesses in this country may account for it themselves. */
+    reverseChargeAvailable?: boolean;
+}
+export interface Customer {
+    country: string;
+    region?: string;
+    /** A validated registration number. Its PRESENCE is what makes a sale B2B. */
+    taxId?: string;
+}
+export interface Supplier {
+    country: string;
+    region?: string;
+    taxId?: string;
+}
+export interface TaxDecision {
+    treatment: Treatment;
+    /** Where tax is due. Empty when nothing is. */
+    jurisdiction: string;
+    label: string;
+    /** The applied percent. `'0'` for every non-standard treatment. */
+    rate: string;
+    /** Wording the invoice must carry, when the law requires a statement. */
+    note?: string;
+}
+/**
+ * Which treatment applies to this sale.
+ *
+ * `digitalService` matters: for those, place of supply is the CUSTOMER's
+ * country. For anything else it is the supplier's, and the difference decides
+ * which country's rate is charged.
+ */
+export declare function decideTax(args: {
+    supplier: Supplier;
+    customer: Customer;
+    rates: readonly TaxRate[];
+    digitalService?: boolean;
+    /** Countries in a common VAT area, where reverse charge applies between them. */
+    commonArea?: readonly string[];
+}): TaxDecision;
+export interface TaxAmounts {
+    net: Money;
+    tax: Money;
+    gross: Money;
+}
+/**
+ * Split an amount into net, tax and gross.
+ *
+ * `inclusive` says whether the figure already contains the tax. A price
+ * advertised to consumers usually does and a B2B price usually does not, and
+ * applying the wrong one is a percentage-sized error in the direction nobody
+ * notices until a return is filed.
+ *
+ * Rounding is explicit and defaults DOWN — toward under-charging rather than
+ * over-charging, because the second is the one that gets refunded with a
+ * complaint attached.
+ */
+export declare function applyTax(amount: Money, decision: TaxDecision, options?: {
+    inclusive?: boolean;
+    rounding?: Rounding;
+}): TaxAmounts;
+/** A human-readable percent for an invoice line: `'0.20'` becomes `'20%'`. */
+export declare const percent: (rate: string) => string;
+/**
+ * Total several lines, taxing each and summing.
+ *
+ * Per-LINE rounding, then summed — not the reverse. Taxing the total instead
+ * produces a figure that does not equal the sum of the printed lines, and an
+ * invoice whose lines do not add up to its total is one a customer refuses to
+ * pay and an auditor refuses to accept.
+ */
+export declare function totalWithTax(lines: readonly Money[], decision: TaxDecision, options?: {
+    inclusive?: boolean;
+    rounding?: Rounding;
+}): TaxAmounts;
+/** Formatted for a document, so a template never does arithmetic. */
+export declare const describeTax: (amounts: TaxAmounts, decision: TaxDecision) => {
+    net: string;
+    tax: string;
+    gross: string;
+    label: string;
+    rate: string;
+    treatment: "standard" | "zero-rated" | "exempt" | "reverse-charge" | "outside-scope";
+    jurisdiction: string;
+    note: string | undefined;
+};
+/** A rate table entry, validated. */
+export declare function assertTaxRate(rate: TaxRate): void;
+export declare const parseRate: (value: string, asset: string) => Money;

package/dist/finance/tax.js

@@ -0,0 +1,291 @@
+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/money.ts
+class MoneyError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "MoneyError";
+  }
+}
+var ASSETS = [
+  { code: "USDT", decimals: 6 },
+  { code: "USDC", decimals: 6 },
+  { code: "BTC", decimals: 8 },
+  { code: "ETH", decimals: 18 },
+  { code: "BNB", decimals: 18 },
+  { code: "EUR", decimals: 2 },
+  { code: "USD", decimals: 2 }
+];
+var REGISTRY = new Map(ASSETS.map((asset) => [asset.code, asset]));
+function defineAsset(spec) {
+  if (spec.decimals < 0 || spec.decimals > 30 || !Number.isInteger(spec.decimals)) {
+    throw new MoneyError("UNKNOWN_ASSET", `${spec.code}: decimals must be an integer 0–30.`);
+  }
+  REGISTRY.set(spec.code, spec);
+}
+function assetSpec(code) {
+  const spec = REGISTRY.get(code);
+  if (!spec)
+    throw new MoneyError("UNKNOWN_ASSET", `Unknown asset "${code}". Call defineAsset first.`);
+  return spec;
+}
+var money = (units, asset) => {
+  assetSpec(asset);
+  return { units, asset };
+};
+var zero = (asset) => money(0n, asset);
+function parseAmount(value, asset) {
+  const spec = assetSpec(asset);
+  const text = value.trim();
+  if (!/^-?\d+(\.\d+)?$/.test(text)) {
+    throw new MoneyError("NOT_FINITE", `"${value}" is not a plain decimal amount.`);
+  }
+  const negative = text.startsWith("-");
+  const [whole, fraction = ""] = text.replace("-", "").split(".");
+  if (fraction.length > spec.decimals) {
+    throw new MoneyError("PRECISION_LOSS", `${asset} has ${spec.decimals} decimals; "${value}" has ${fraction.length}.`);
+  }
+  const padded = fraction.padEnd(spec.decimals, "0");
+  const units = BigInt(whole + padded);
+  return { units: negative ? -units : units, asset };
+}
+function formatAmount(amount, options = {}) {
+  const spec = assetSpec(amount.asset);
+  const negative = amount.units < 0n;
+  const digits = (negative ? -amount.units : amount.units).toString().padStart(spec.decimals + 1, "0");
+  const whole = digits.slice(0, digits.length - spec.decimals);
+  let fraction = spec.decimals === 0 ? "" : digits.slice(digits.length - spec.decimals);
+  if (options.trim && fraction)
+    fraction = fraction.replace(/0+$/, "");
+  return `${negative ? "-" : ""}${whole}${fraction ? `.${fraction}` : ""}`;
+}
+function sameAsset(a, b) {
+  if (a.asset !== b.asset) {
+    throw new MoneyError("ASSET_MISMATCH", `Cannot combine ${a.asset} and ${b.asset}.`);
+  }
+}
+function add(a, b) {
+  sameAsset(a, b);
+  return { units: a.units + b.units, asset: a.asset };
+}
+function subtract(a, b) {
+  sameAsset(a, b);
+  return { units: a.units - b.units, asset: a.asset };
+}
+var negate = (amount) => ({ units: -amount.units, asset: amount.asset });
+var abs = (amount) => ({
+  units: amount.units < 0n ? -amount.units : amount.units,
+  asset: amount.asset
+});
+var isZero = (amount) => amount.units === 0n;
+var isNegative = (amount) => amount.units < 0n;
+function compare(a, b) {
+  sameAsset(a, b);
+  return a.units < b.units ? -1 : a.units > b.units ? 1 : 0;
+}
+var equals = (a, b) => a.asset === b.asset && a.units === b.units;
+var ROUNDING = ["down", "up", "half-up"];
+function divideRounded(numerator, denominator, mode) {
+  if (denominator === 0n)
+    throw new MoneyError("DIVIDE_BY_ZERO", "Division by zero.");
+  const negative = numerator < 0n !== denominator < 0n;
+  const a = numerator < 0n ? -numerator : numerator;
+  const b = denominator < 0n ? -denominator : denominator;
+  const quotient = a / b;
+  const remainder = a % b;
+  if (remainder === 0n)
+    return negative ? -quotient : quotient;
+  let result = quotient;
+  if (mode === "up")
+    result += 1n;
+  else if (mode === "half-up" && remainder * 2n >= b)
+    result += 1n;
+  return negative ? -result : result;
+}
+function mulRate(amount, rate, mode = "down") {
+  if (!/^-?\d+(\.\d+)?$/.test(rate.trim())) {
+    throw new MoneyError("NOT_FINITE", `"${rate}" is not a plain decimal rate.`);
+  }
+  const [whole, fraction = ""] = rate.trim().replace("-", "").split(".");
+  const scale = 10n ** BigInt(fraction.length);
+  const scaled = BigInt(whole + fraction) * (rate.trim().startsWith("-") ? -1n : 1n);
+  return { units: divideRounded(amount.units * scaled, scale, mode), asset: amount.asset };
+}
+function convert(amount, to, rate, mode = "down") {
+  const from = assetSpec(amount.asset);
+  const target = assetSpec(to);
+  const asTarget = mulRate({ units: amount.units, asset: to }, rate, mode);
+  const shift = target.decimals - from.decimals;
+  if (shift === 0)
+    return asTarget;
+  if (shift > 0)
+    return { units: asTarget.units * 10n ** BigInt(shift), asset: to };
+  return { units: divideRounded(asTarget.units, 10n ** BigInt(-shift), mode), asset: to };
+}
+function allocate(amount, parts) {
+  if (parts < 1)
+    throw new MoneyError("NOT_FINITE", "Cannot allocate into fewer than one part.");
+  const each = divideRounded(amount.units, BigInt(parts), "down");
+  const allocated = Array.from({ length: parts }, () => each);
+  let remainder = amount.units - each * BigInt(parts);
+  const step = remainder < 0n ? -1n : 1n;
+  for (let index = 0;remainder !== 0n; index = (index + 1) % parts) {
+    allocated[index] += step;
+    remainder -= step;
+  }
+  return allocated.map((units) => ({ units, asset: amount.asset }));
+}
+function toStep(amount, step, mode = "down") {
+  const stepUnits = parseAmount(step, amount.asset).units;
+  if (stepUnits <= 0n)
+    throw new MoneyError("NOT_FINITE", "A step must be positive.");
+  return { units: divideRounded(amount.units, stepUnits, mode) * stepUnits, asset: amount.asset };
+}
+var VERSION = "0.1.0";
+
+// src/finance/tax.ts
+class TaxError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "TaxError";
+  }
+}
+var TREATMENTS = ["standard", "zero-rated", "exempt", "reverse-charge", "outside-scope"];
+var normaliseCountry = (value, what) => {
+  if (!value || !/^[A-Za-z]{2}$/.test(value)) {
+    throw new TaxError("NO_COUNTRY", `${what} needs a two-letter country code.`);
+  }
+  return value.toUpperCase();
+};
+var findRate = (rates, country, region) => {
+  const regional = region ? rates.find((r) => r.country === country && r.region?.toUpperCase() === region.toUpperCase()) : undefined;
+  return regional ?? rates.find((r) => r.country === country && !r.region);
+};
+function decideTax(args) {
+  const supplierCountry = normaliseCountry(args.supplier.country, "The supplier");
+  const customerCountry = normaliseCountry(args.customer.country, "The customer");
+  const domestic = supplierCountry === customerCountry;
+  const area = (args.commonArea ?? []).map((c) => c.toUpperCase());
+  const bothInArea = area.includes(supplierCountry) && area.includes(customerCountry);
+  const place = args.digitalService && !domestic ? customerCountry : supplierCountry;
+  const region = place === customerCountry ? args.customer.region : args.supplier.region;
+  const rate = findRate(args.rates, place, region);
+  if (domestic) {
+    if (!rate) {
+      throw new TaxError("UNKNOWN_JURISDICTION", `No rate is configured for ${place}.`);
+    }
+    return {
+      treatment: "standard",
+      jurisdiction: rate.region ? `${place}-${rate.region}` : place,
+      label: rate.label,
+      rate: rate.rate
+    };
+  }
+  if (bothInArea && args.customer.taxId && rate?.reverseChargeAvailable !== false) {
+    return {
+      treatment: "reverse-charge",
+      jurisdiction: customerCountry,
+      label: rate?.label ?? "VAT",
+      rate: "0",
+      note: "Reverse charge: the customer accounts for the tax."
+    };
+  }
+  if (bothInArea) {
+    if (!rate) {
+      throw new TaxError("UNKNOWN_JURISDICTION", `No rate is configured for ${place}.`);
+    }
+    return {
+      treatment: "standard",
+      jurisdiction: place,
+      label: rate.label,
+      rate: rate.rate
+    };
+  }
+  return {
+    treatment: "outside-scope",
+    jurisdiction: "",
+    label: rate?.label ?? "",
+    rate: "0",
+    note: "Outside the scope of tax in the supplier country."
+  };
+}
+function applyTax(amount, decision, options = {}) {
+  const rate = Number(decision.rate);
+  if (!Number.isFinite(rate) || rate < 0 || rate > 1) {
+    throw new TaxError("BAD_RATE", `${decision.rate} is not a rate between 0 and 1.`);
+  }
+  if (rate === 0) {
+    return { net: amount, tax: zero(amount.asset), gross: amount };
+  }
+  const bp = BigInt(Math.round(rate * 1e4));
+  if (options.inclusive) {
+    const net = amount.units * 10000n / (10000n + bp);
+    const netMoney = { units: net, asset: amount.asset };
+    return { net: netMoney, tax: subtract(amount, netMoney), gross: amount };
+  }
+  const tax = { units: amount.units * bp / 10000n, asset: amount.asset };
+  return { net: amount, tax, gross: add(amount, tax) };
+}
+var percent = (rate) => {
+  const value = Number(rate) * 100;
+  return `${Number.isInteger(value) ? value : value.toFixed(2)}%`;
+};
+function totalWithTax(lines, decision, options = {}) {
+  if (lines.length === 0) {
+    throw new TaxError("INCONSISTENT", "An invoice needs at least one line.");
+  }
+  const asset = lines[0].asset;
+  let net = zero(asset);
+  let tax = zero(asset);
+  for (const line of lines) {
+    if (line.asset !== asset) {
+      throw new TaxError("INCONSISTENT", `Lines mix ${asset} and ${line.asset}.`);
+    }
+    const amounts = applyTax(line, decision, options);
+    net = add(net, amounts.net);
+    tax = add(tax, amounts.tax);
+  }
+  return { net, tax, gross: add(net, tax) };
+}
+var describeTax = (amounts, decision) => ({
+  net: formatAmount(amounts.net),
+  tax: formatAmount(amounts.tax),
+  gross: formatAmount(amounts.gross),
+  label: decision.label,
+  rate: percent(decision.rate),
+  treatment: decision.treatment,
+  jurisdiction: decision.jurisdiction,
+  note: decision.note
+});
+function assertTaxRate(rate) {
+  normaliseCountry(rate.country, "A rate");
+  const value = Number(rate.rate);
+  if (!Number.isFinite(value) || value < 0 || value > 1) {
+    throw new TaxError("BAD_RATE", `${rate.country}: ${rate.rate} is not a rate between 0 and 1.`);
+  }
+  if (!rate.label) {
+    throw new TaxError("BAD_RATE", `${rate.country}: a rate needs a label for the invoice.`);
+  }
+}
+var parseRate = (value, asset) => parseAmount(value, asset);
+export {
+  totalWithTax,
+  percent,
+  parseRate,
+  describeTax,
+  decideTax,
+  assertTaxRate,
+  applyTax,
+  TaxError,
+  TREATMENTS
+};

package/dist/finance/transfers.d.ts

@@ -0,0 +1,153 @@
+import { Refusal } from '@forgezero/access';
+import { type Money } from './money';
+/**
+ * Deposits and withdrawals as ORDERED PIPELINES, not as functions.
+ *
+ * The seam exists before the thing that plugs into it, and that ordering is the
+ * whole point. AML screening is deferred, but the position it will occupy —
+ * first, before anything else looks at the transfer — is decided now. Adding a
+ * first-position check to a function later means editing every path money
+ * takes, and the one path somebody misses is the one that matters.
+ *
+ * So a transfer runs a list of stages. Adding screening later is registering a
+ * stage. Nothing in deposit or withdrawal code changes.
+ *
+ * ## Stages refuse the way routes refuse
+ *
+ * A stage throws `Refusal` from `@forgezero/access`, which already carries a
+ * status, a code, details and a retryable flag — and the HTTP pipeline already
+ * knows how to turn one into a response. So a screening hit and a route denial
+ * are the same shape, are logged the same way, and reach a client the same way.
+ * Inventing a second failure type here would mean translating between them at
+ * every boundary, and a translation layer is where a `retryable` flag gets lost.
+ *
+ * ## What this does NOT do
+ *
+ * No balance movement, no persistence, no ordering. Postings belong to
+ * `./ledger` and ordering belongs to the queue keyed by account owner. This
+ * decides only whether a transfer may proceed, and records why not.
+ */
+export declare const DIRECTIONS: readonly ["deposit", "withdrawal"];
+export type Direction = (typeof DIRECTIONS)[number];
+export interface Transfer {
+    direction: Direction;
+    /** The account owner. Also the queue key the caller should be holding. */
+    owner: string;
+    amount: Money;
+    /** Chain, venue, or wherever this is coming from or going to. */
+    network?: string;
+    /** Destination for a withdrawal, source for a deposit. */
+    address?: string;
+    /** On-chain transaction hash, once one exists. */
+    txHash?: string;
+    /** Idempotency key. The queue's `dedupeKey` for this transfer. */
+    reference: string;
+    atMs: number;
+    /** Anything a stage wants to pass to a later one. */
+    context?: Record<string, unknown>;
+}
+/**
+ * One check.
+ *
+ * Returning normally means "proceed". Throwing `Refusal` stops the transfer
+ * with a reason a client can read. A stage may also return a patch, which is
+ * merged into `context` for later stages — that is how screening passes a risk
+ * score to an approval stage without either knowing about the other.
+ */
+export interface Stage {
+    name: string;
+    /**
+     * Where this runs. Lower numbers first, ties broken by registration order.
+     *
+     * Explicit rather than array position, because the ordering IS the security
+     * property here and a list somebody reorders while tidying is a screening
+     * check that silently moved behind the balance check.
+     */
+    order: number;
+    directions?: readonly Direction[];
+    run(transfer: Transfer): Promise<void | Record<string, unknown>> | void | Record<string, unknown>;
+}
+/** Reserved for the check that must always be first. */
+export declare const SCREENING_ORDER = 0;
+export interface StageOutcome {
+    stage: string;
+    ok: boolean;
+    ms: number;
+    code?: string;
+}
+export interface PipelineResult {
+    ok: boolean;
+    transfer: Transfer;
+    stages: StageOutcome[];
+    /** The refusal that stopped it. Absent when it passed. */
+    refusal?: Refusal;
+}
+export declare class PipelineError extends Error {
+    readonly code: 'DUPLICATE_STAGE' | 'NO_SCREENING';
+    constructor(code: 'DUPLICATE_STAGE' | 'NO_SCREENING', message: string);
+}
+/**
+ * Build a pipeline from stages.
+ *
+ * `requireScreening` is off by default and ON for production wiring: a platform
+ * that has decided it needs AML should fail to start rather than run without
+ * it. A missing screening stage is exactly the kind of omission that is
+ * invisible until somebody audits, so it is expressible as a boot-time
+ * assertion rather than a runbook item.
+ */
+export declare function createTransferPipeline(options: {
+    stages: readonly Stage[];
+    requireScreening?: boolean;
+    now?: () => number;
+    /** Called for every stage, passed or refused. The audit hook. */
+    onStage?: (outcome: StageOutcome, transfer: Transfer) => void;
+}): {
+    stages: {
+        name: string;
+        order: number;
+    }[];
+    /**
+     * Run every stage that applies, in order, stopping at the first refusal.
+     *
+     * First refusal, not all of them: the stages are a sequence where each may
+     * depend on the last having passed, so continuing past one would run checks
+     * against a transfer that has already been rejected — and report failures
+     * that are consequences rather than causes.
+     */
+    run(transfer: Transfer): Promise<PipelineResult>;
+};
+export type TransferPipeline = ReturnType<typeof createTransferPipeline>;
+/**
+ * The AML placeholder.
+ *
+ * Registered at order 0 and currently passes everything, which is what the
+ * owner asked for. Its value is entirely in existing: the position is agreed,
+ * the audit trail already records it running, and replacing the body later
+ * changes no caller.
+ *
+ * `allow` is a parameter rather than a hard-coded `true` so a test can prove
+ * the pipeline actually stops on a screening refusal — a stage that has never
+ * refused anything is a stage nobody knows works.
+ */
+export declare const screeningStage: (check?: (transfer: Transfer) => Promise<boolean> | boolean) => Stage;
+/** Amount bounds, per direction. */
+export declare const limitsStage: (limits: {
+    min?: Money;
+    max?: Money;
+    directions?: readonly Direction[];
+}) => Stage;
+/**
+ * Enough available balance, for a withdrawal.
+ *
+ * Available, never total — a check against total lets a withdrawal spend what
+ * an open order has already committed. Runs AFTER screening, deliberately: a
+ * screened-out transfer should not reveal whether the balance was sufficient.
+ */
+export declare const balanceStage: (available: (transfer: Transfer) => Promise<Money> | Money) => Stage;
+/** Hold a withdrawal for a human above a threshold. */
+export declare const approvalStage: (args: {
+    threshold: Money;
+    isApproved: (transfer: Transfer) => Promise<boolean> | boolean;
+}) => Stage;
+/** Refuse while an account is frozen for non-payment. */
+export declare const notFrozenStage: (isFrozen: (owner: string) => Promise<boolean> | boolean) => Stage;