@classytic/primitives 0.27.0 → 0.29.0

package/dist/money-BBOARE5f.mjs

@@ -0,0 +1,204 @@
+import { CurrencyMismatchError, currencyCode, isCurrencyCode, minorUnitFactor } from "./currency.mjs";
+//#region src/money/cash-destination.ts
+/**
+* WHERE received cash landed, as an INTENT — never a chart-of-accounts code.
+*
+* The one vocabulary a request body, a domain event, a client SDK and a
+* settlement dialog all speak. The accounting tier maps an intent to whatever
+* account the active chart assigns, so a chart renumber cannot reach any of
+* them. A literal code in a client once named a bank account the chart had
+* already renumbered, and every settlement it sent was refused.
+*
+* `cash` — the business's bank / current account, the default for a courier
+*          remittance, a card payout or a transfer.
+* `petty_cash` — cash in hand, for an in-person handover at the till.
+*/
+const CASH_DESTINATIONS = ["cash", "petty_cash"];
+function isCashDestination(value) {
+	return typeof value === "string" && CASH_DESTINATIONS.includes(value);
+}
+/** Human label for a destination — the ONE place the wording lives. */
+function cashDestinationLabel(destination) {
+	switch (destination) {
+		case "cash": return "Bank account";
+		case "petty_cash": return "Cash in hand";
+		default: throw new Error(`unknown cash destination ${String(destination)}`);
+	}
+}
+//#endregion
+//#region src/money/money.ts
+/**
+* Cast a raw number to {@link MinorUnits}. Pass the currency as the second
+* argument to fix the phantom type. With no second arg, `MinorUnits<string>`
+* — useful for generic SDK boundaries that don't know the currency yet.
+*
+* @example
+* MinorUnits(489900, 'BDT')   // typed MinorUnits<'BDT'>
+* MinorUnits(199, 'USD')      // typed MinorUnits<'USD'>
+*/
+function MinorUnits(amount, _currency) {
+	return amount;
+}
+/**
+* Construct {@link Money} from an integer minor-unit amount.
+*
+* @throws TypeError if `amount` is not a finite integer.
+* @throws InvalidCurrencyCodeError if `currency` is not ISO 4217 format.
+*/
+function money(amount, currency) {
+	if (!Number.isFinite(amount) || !Number.isInteger(amount)) throw new TypeError(`Money.amount must be a finite integer in minor units, got ${amount}`);
+	return {
+		amount,
+		currency: currencyCode(currency)
+	};
+}
+/**
+* Construct {@link Money} from a major-unit number (e.g. dollars, taka) by
+* scaling to the currency's minor unit and rounding half-away-from-zero.
+*
+* Uses `toPrecision(15)` to strip the trailing-bit noise that appears in
+* multiply-then-round (e.g. `0.1 + 0.2 = 0.30000000000000004`). This is
+* enough for the vast majority of decimals encountered in real-world pricing.
+*
+* **Precision caveat.** A handful of decimals cannot be represented exactly
+* in IEEE 754 and will round to the IEEE-closest integer rather than the
+* mathematically-expected one — e.g. `1.005` is stored as `1.00499999…` and
+* rounds to `100` minor units, not `101`. If you need decimal-exact rounding,
+* construct money from a string or use integer minor units directly via
+* {@link money}.
+*
+* @example
+* fromMajor(19.99, 'USD')      // { amount: 1999, currency: 'USD' }
+* fromMajor(0.1 + 0.2, 'USD')  // { amount: 30,   currency: 'USD' }
+* fromMajor(1500,  'JPY')      // { amount: 1500, currency: 'JPY' }
+*/
+function fromMajor(major, currency) {
+	if (!Number.isFinite(major)) throw new TypeError(`fromMajor received non-finite value: ${major}`);
+	const raw = major * minorUnitFactor(currency);
+	const cleaned = Number(raw.toPrecision(15));
+	return {
+		amount: Math.round(Math.abs(cleaned)) * (cleaned < 0 ? -1 : 1),
+		currency: currencyCode(currency)
+	};
+}
+/** Convert {@link Money} back to its major-unit floating-point representation. */
+function toMajor(m) {
+	return m.amount / minorUnitFactor(m.currency);
+}
+function assertSameCurrency(a, b) {
+	if (a.currency !== b.currency) throw new CurrencyMismatchError(a.currency, b.currency);
+}
+function addMoney(a, b) {
+	assertSameCurrency(a, b);
+	return {
+		amount: a.amount + b.amount,
+		currency: a.currency
+	};
+}
+function subtractMoney(a, b) {
+	assertSameCurrency(a, b);
+	return {
+		amount: a.amount - b.amount,
+		currency: a.currency
+	};
+}
+/**
+* Multiply money by a scalar. The result is rounded to an integer number of
+* minor units using half-away-from-zero rounding.
+*/
+function multiplyMoney(m, scalar) {
+	if (!Number.isFinite(scalar)) throw new TypeError(`multiplyMoney received non-finite scalar: ${scalar}`);
+	const raw = m.amount * scalar;
+	return {
+		amount: Math.round(Math.abs(raw)) * (raw < 0 ? -1 : 1),
+		currency: m.currency
+	};
+}
+/** Sum a list of {@link Money}. Returns zero in the given currency for empty input. */
+function sumMoney(values, currency) {
+	return values.reduce((acc, v) => addMoney(acc, v), {
+		amount: 0,
+		currency: currencyCode(currency)
+	});
+}
+/** Strict equality (amount and currency both match). */
+function equalsMoney(a, b) {
+	return a.amount === b.amount && a.currency === b.currency;
+}
+/**
+* Ordering predicate. Returns -1, 0, or 1. Throws on currency mismatch — use
+* {@link equalsMoney} for a total equality check across currencies.
+*/
+function compareMoney(a, b) {
+	assertSameCurrency(a, b);
+	if (a.amount < b.amount) return -1;
+	if (a.amount > b.amount) return 1;
+	return 0;
+}
+function isZeroMoney(m) {
+	return m.amount === 0;
+}
+function isPositiveMoney(m) {
+	return m.amount > 0;
+}
+function isNegativeMoney(m) {
+	return m.amount < 0;
+}
+function negateMoney(m) {
+	return {
+		amount: m.amount === 0 ? 0 : -m.amount,
+		currency: m.currency
+	};
+}
+function absMoney(m) {
+	return m.amount < 0 ? negateMoney(m) : m;
+}
+/**
+* Decimal major-unit number → integer minor units by decimal exponent.
+* Rounding: raw IEEE `Math.round` — half-up toward +∞ (so `-10.5 → -10`),
+* documented above. Throws when the result leaves the safe-integer range
+* (also catches `NaN`/`Infinity` inputs).
+*
+* @example
+* majorToMinorUnits(10.5)      // 1050
+* majorToMinorUnits(1000, 0)   // 1000 (JPY-style)
+* majorToMinorUnits(1.005)     // 100 — IEEE, see note above
+*/
+function majorToMinorUnits(major, minorUnitDecimals = 2) {
+	const factor = 10 ** minorUnitDecimals;
+	const minor = Math.round(major * factor);
+	if (!Number.isSafeInteger(minor)) throw new RangeError(`Amount ${major} exceeds safe integer limit when converted to minor units. Max safe amount: ${Number.MAX_SAFE_INTEGER / factor}`);
+	return minor;
+}
+/** Integer minor units → decimal major-unit number by decimal exponent: `1050 → 10.5`. */
+function minorUnitsToMajor(minor, minorUnitDecimals = 2) {
+	return minor / 10 ** minorUnitDecimals;
+}
+/**
+* Percentage of an integer minor-unit amount → integer minor units.
+* EXACT multiply-then-round: `Math.round((minor × ratePercent) / 100)` —
+* one rounding point, half-up toward +∞. Handles genuinely fractional rates
+* (QST 9.975 %) without precision loss: `percentOfMinor(20000, 9.975) === 1995`.
+*
+* Hosts whose domain guarantees at-most-2-decimal rates MAY snap the rate to
+* integer basis points BEFORE calling (be-prod's `#shared/money` seam does) —
+* that is host policy layered on top, not part of this primitive.
+*/
+function percentOfMinor(minor, ratePercent) {
+	if (!Number.isFinite(minor) || !Number.isFinite(ratePercent)) throw new TypeError(`percentOfMinor received non-finite input: minor=${minor}, ratePercent=${ratePercent}`);
+	return Math.round(minor * ratePercent / 100);
+}
+/**
+* Integer minor units → plain decimal string (no currency symbol, no locale):
+* `formatMinorUnits(10550) → "105.50"`, `formatMinorUnits(1000, 0) → "1000"`.
+* For localized currency strings use `Intl.NumberFormat` at the display layer.
+*/
+function formatMinorUnits(minor, minorUnitDecimals = 2) {
+	return minorUnitsToMajor(minor, minorUnitDecimals).toFixed(minorUnitDecimals);
+}
+/** Structural type guard. */
+function isMoney(value) {
+	return typeof value === "object" && value !== null && typeof value.amount === "number" && Number.isInteger(value.amount) && isCurrencyCode(value.currency);
+}
+//#endregion
+export { isCashDestination as C, cashDestinationLabel as S, percentOfMinor as _, equalsMoney as a, toMajor as b, isMoney as c, isZeroMoney as d, majorToMinorUnits as f, negateMoney as g, multiplyMoney as h, compareMoney as i, isNegativeMoney as l, money as m, absMoney as n, formatMinorUnits as o, minorUnitsToMajor as p, addMoney as r, fromMajor as s, MinorUnits as t, isPositiveMoney as u, subtractMoney as v, CASH_DESTINATIONS as x, sumMoney as y };

package/dist/{money-CfAvfNiM.d.mts → money-C9iLWiWR.d.mts}

@@ -196,6 +196,26 @@ declare function reverseWithSnapshot(base: Money, fx: FxSnapshot, options?: {
  */
 declare function isFxSnapshot(value: unknown): value is FxSnapshot;
 //#endregion
+//#region src/money/cash-destination.d.ts
+/**
+ * WHERE received cash landed, as an INTENT — never a chart-of-accounts code.
+ *
+ * The one vocabulary a request body, a domain event, a client SDK and a
+ * settlement dialog all speak. The accounting tier maps an intent to whatever
+ * account the active chart assigns, so a chart renumber cannot reach any of
+ * them. A literal code in a client once named a bank account the chart had
+ * already renumbered, and every settlement it sent was refused.
+ *
+ * `cash` — the business's bank / current account, the default for a courier
+ *          remittance, a card payout or a transfer.
+ * `petty_cash` — cash in hand, for an in-person handover at the till.
+ */
+declare const CASH_DESTINATIONS: readonly ["cash", "petty_cash"];
+type CashDestination = (typeof CASH_DESTINATIONS)[number];
+declare function isCashDestination(value: unknown): value is CashDestination;
+/** Human label for a destination — the ONE place the wording lives. */
+declare function cashDestinationLabel(destination: CashDestination): string;
+//#endregion
 //#region src/money/money.d.ts
 /**
  * Wire-format monetary amount: integer minor units, branded with a phantom
@@ -343,4 +363,4 @@ declare function formatMinorUnits(minor: number, minorUnitDecimals?: number): st
 /** Structural type guard. */
 declare function isMoney(value: unknown): value is Money;
 //#endregion
-export { convertWithSnapshot as A, CURRENCY_PATTERN as C, FxSnapshot as D, FxRounding as E, minorUnitFactor as F, reverseWithSnapshot as I, toCurrencyCode as L, isCurrencyCode as M, isFxSnapshot as N, InvalidCurrencyCodeError as O, isKnownCurrency as P, CURRENCIES as S, CurrencyMismatchError as T, negateMoney as _, compareMoney as a, sumMoney as b, fromMajor as c, isPositiveMoney as d, isZeroMoney as f, multiplyMoney as g, money as h, addMoney as i, currencyCode as j, MINOR_UNIT_FACTOR as k, isMoney as l, minorUnitsToMajor as m, Money as n, equalsMoney as o, majorToMinorUnits as p, absMoney as r, formatMinorUnits as s, MinorUnits as t, isNegativeMoney as u, percentOfMinor as v, CurrencyCode as w, toMajor as x, subtractMoney as y };
+export { FxRounding as A, reverseWithSnapshot as B, CashDestination as C, CURRENCY_PATTERN as D, CURRENCIES as E, currencyCode as F, isCurrencyCode as I, isFxSnapshot as L, InvalidCurrencyCodeError as M, MINOR_UNIT_FACTOR as N, CurrencyCode as O, convertWithSnapshot as P, isKnownCurrency as R, CASH_DESTINATIONS as S, isCashDestination as T, toCurrencyCode as V, negateMoney as _, compareMoney as a, sumMoney as b, fromMajor as c, isPositiveMoney as d, isZeroMoney as f, multiplyMoney as g, money as h, addMoney as i, FxSnapshot as j, CurrencyMismatchError as k, isMoney as l, minorUnitsToMajor as m, Money as n, equalsMoney as o, majorToMinorUnits as p, absMoney as r, formatMinorUnits as s, MinorUnits as t, isNegativeMoney as u, percentOfMinor as v, cashDestinationLabel as w, toMajor as x, subtractMoney as y, minorUnitFactor as z };

package/dist/money.d.mts

@@ -1,2 +1,2 @@
-import { T as CurrencyMismatchError, _ as negateMoney, a as compareMoney, b as sumMoney, c as fromMajor, d as isPositiveMoney, f as isZeroMoney, g as multiplyMoney, h as money, i as addMoney, l as isMoney, m as minorUnitsToMajor, n as Money, o as equalsMoney, p as majorToMinorUnits, r as absMoney, s as formatMinorUnits, t as MinorUnits, u as isNegativeMoney, v as percentOfMinor, x as toMajor, y as subtractMoney } from "./money-CfAvfNiM.mjs";
-export { CurrencyMismatchError, MinorUnits, Money, absMoney, addMoney, compareMoney, equalsMoney, formatMinorUnits, fromMajor, isMoney, isNegativeMoney, isPositiveMoney, isZeroMoney, majorToMinorUnits, minorUnitsToMajor, money, multiplyMoney, negateMoney, percentOfMinor, subtractMoney, sumMoney, toMajor };
+import { C as CashDestination, S as CASH_DESTINATIONS, T as isCashDestination, _ as negateMoney, a as compareMoney, b as sumMoney, c as fromMajor, d as isPositiveMoney, f as isZeroMoney, g as multiplyMoney, h as money, i as addMoney, k as CurrencyMismatchError, l as isMoney, m as minorUnitsToMajor, n as Money, o as equalsMoney, p as majorToMinorUnits, r as absMoney, s as formatMinorUnits, t as MinorUnits, u as isNegativeMoney, v as percentOfMinor, w as cashDestinationLabel, x as toMajor, y as subtractMoney } from "./money-C9iLWiWR.mjs";
+export { CASH_DESTINATIONS, type CashDestination, CurrencyMismatchError, MinorUnits, Money, absMoney, addMoney, cashDestinationLabel, compareMoney, equalsMoney, formatMinorUnits, fromMajor, isCashDestination, isMoney, isNegativeMoney, isPositiveMoney, isZeroMoney, majorToMinorUnits, minorUnitsToMajor, money, multiplyMoney, negateMoney, percentOfMinor, subtractMoney, sumMoney, toMajor };

package/dist/money.mjs

@@ -1,177 +1,3 @@
-import { CurrencyMismatchError, currencyCode, isCurrencyCode, minorUnitFactor } from "./currency.mjs";
-//#region src/money/money.ts
-/**
-* Cast a raw number to {@link MinorUnits}. Pass the currency as the second
-* argument to fix the phantom type. With no second arg, `MinorUnits<string>`
-* — useful for generic SDK boundaries that don't know the currency yet.
-*
-* @example
-* MinorUnits(489900, 'BDT')   // typed MinorUnits<'BDT'>
-* MinorUnits(199, 'USD')      // typed MinorUnits<'USD'>
-*/
-function MinorUnits(amount, _currency) {
-	return amount;
-}
-/**
-* Construct {@link Money} from an integer minor-unit amount.
-*
-* @throws TypeError if `amount` is not a finite integer.
-* @throws InvalidCurrencyCodeError if `currency` is not ISO 4217 format.
-*/
-function money(amount, currency) {
-	if (!Number.isFinite(amount) || !Number.isInteger(amount)) throw new TypeError(`Money.amount must be a finite integer in minor units, got ${amount}`);
-	return {
-		amount,
-		currency: currencyCode(currency)
-	};
-}
-/**
-* Construct {@link Money} from a major-unit number (e.g. dollars, taka) by
-* scaling to the currency's minor unit and rounding half-away-from-zero.
-*
-* Uses `toPrecision(15)` to strip the trailing-bit noise that appears in
-* multiply-then-round (e.g. `0.1 + 0.2 = 0.30000000000000004`). This is
-* enough for the vast majority of decimals encountered in real-world pricing.
-*
-* **Precision caveat.** A handful of decimals cannot be represented exactly
-* in IEEE 754 and will round to the IEEE-closest integer rather than the
-* mathematically-expected one — e.g. `1.005` is stored as `1.00499999…` and
-* rounds to `100` minor units, not `101`. If you need decimal-exact rounding,
-* construct money from a string or use integer minor units directly via
-* {@link money}.
-*
-* @example
-* fromMajor(19.99, 'USD')      // { amount: 1999, currency: 'USD' }
-* fromMajor(0.1 + 0.2, 'USD')  // { amount: 30,   currency: 'USD' }
-* fromMajor(1500,  'JPY')      // { amount: 1500, currency: 'JPY' }
-*/
-function fromMajor(major, currency) {
-	if (!Number.isFinite(major)) throw new TypeError(`fromMajor received non-finite value: ${major}`);
-	const raw = major * minorUnitFactor(currency);
-	const cleaned = Number(raw.toPrecision(15));
-	return {
-		amount: Math.round(Math.abs(cleaned)) * (cleaned < 0 ? -1 : 1),
-		currency: currencyCode(currency)
-	};
-}
-/** Convert {@link Money} back to its major-unit floating-point representation. */
-function toMajor(m) {
-	return m.amount / minorUnitFactor(m.currency);
-}
-function assertSameCurrency(a, b) {
-	if (a.currency !== b.currency) throw new CurrencyMismatchError(a.currency, b.currency);
-}
-function addMoney(a, b) {
-	assertSameCurrency(a, b);
-	return {
-		amount: a.amount + b.amount,
-		currency: a.currency
-	};
-}
-function subtractMoney(a, b) {
-	assertSameCurrency(a, b);
-	return {
-		amount: a.amount - b.amount,
-		currency: a.currency
-	};
-}
-/**
-* Multiply money by a scalar. The result is rounded to an integer number of
-* minor units using half-away-from-zero rounding.
-*/
-function multiplyMoney(m, scalar) {
-	if (!Number.isFinite(scalar)) throw new TypeError(`multiplyMoney received non-finite scalar: ${scalar}`);
-	const raw = m.amount * scalar;
-	return {
-		amount: Math.round(Math.abs(raw)) * (raw < 0 ? -1 : 1),
-		currency: m.currency
-	};
-}
-/** Sum a list of {@link Money}. Returns zero in the given currency for empty input. */
-function sumMoney(values, currency) {
-	return values.reduce((acc, v) => addMoney(acc, v), {
-		amount: 0,
-		currency: currencyCode(currency)
-	});
-}
-/** Strict equality (amount and currency both match). */
-function equalsMoney(a, b) {
-	return a.amount === b.amount && a.currency === b.currency;
-}
-/**
-* Ordering predicate. Returns -1, 0, or 1. Throws on currency mismatch — use
-* {@link equalsMoney} for a total equality check across currencies.
-*/
-function compareMoney(a, b) {
-	assertSameCurrency(a, b);
-	if (a.amount < b.amount) return -1;
-	if (a.amount > b.amount) return 1;
-	return 0;
-}
-function isZeroMoney(m) {
-	return m.amount === 0;
-}
-function isPositiveMoney(m) {
-	return m.amount > 0;
-}
-function isNegativeMoney(m) {
-	return m.amount < 0;
-}
-function negateMoney(m) {
-	return {
-		amount: m.amount === 0 ? 0 : -m.amount,
-		currency: m.currency
-	};
-}
-function absMoney(m) {
-	return m.amount < 0 ? negateMoney(m) : m;
-}
-/**
-* Decimal major-unit number → integer minor units by decimal exponent.
-* Rounding: raw IEEE `Math.round` — half-up toward +∞ (so `-10.5 → -10`),
-* documented above. Throws when the result leaves the safe-integer range
-* (also catches `NaN`/`Infinity` inputs).
-*
-* @example
-* majorToMinorUnits(10.5)      // 1050
-* majorToMinorUnits(1000, 0)   // 1000 (JPY-style)
-* majorToMinorUnits(1.005)     // 100 — IEEE, see note above
-*/
-function majorToMinorUnits(major, minorUnitDecimals = 2) {
-	const factor = 10 ** minorUnitDecimals;
-	const minor = Math.round(major * factor);
-	if (!Number.isSafeInteger(minor)) throw new RangeError(`Amount ${major} exceeds safe integer limit when converted to minor units. Max safe amount: ${Number.MAX_SAFE_INTEGER / factor}`);
-	return minor;
-}
-/** Integer minor units → decimal major-unit number by decimal exponent: `1050 → 10.5`. */
-function minorUnitsToMajor(minor, minorUnitDecimals = 2) {
-	return minor / 10 ** minorUnitDecimals;
-}
-/**
-* Percentage of an integer minor-unit amount → integer minor units.
-* EXACT multiply-then-round: `Math.round((minor × ratePercent) / 100)` —
-* one rounding point, half-up toward +∞. Handles genuinely fractional rates
-* (QST 9.975 %) without precision loss: `percentOfMinor(20000, 9.975) === 1995`.
-*
-* Hosts whose domain guarantees at-most-2-decimal rates MAY snap the rate to
-* integer basis points BEFORE calling (be-prod's `#shared/money` seam does) —
-* that is host policy layered on top, not part of this primitive.
-*/
-function percentOfMinor(minor, ratePercent) {
-	if (!Number.isFinite(minor) || !Number.isFinite(ratePercent)) throw new TypeError(`percentOfMinor received non-finite input: minor=${minor}, ratePercent=${ratePercent}`);
-	return Math.round(minor * ratePercent / 100);
-}
-/**
-* Integer minor units → plain decimal string (no currency symbol, no locale):
-* `formatMinorUnits(10550) → "105.50"`, `formatMinorUnits(1000, 0) → "1000"`.
-* For localized currency strings use `Intl.NumberFormat` at the display layer.
-*/
-function formatMinorUnits(minor, minorUnitDecimals = 2) {
-	return minorUnitsToMajor(minor, minorUnitDecimals).toFixed(minorUnitDecimals);
-}
-/** Structural type guard. */
-function isMoney(value) {
-	return typeof value === "object" && value !== null && typeof value.amount === "number" && Number.isInteger(value.amount) && isCurrencyCode(value.currency);
-}
-//#endregion
-export { CurrencyMismatchError, MinorUnits, absMoney, addMoney, compareMoney, equalsMoney, formatMinorUnits, fromMajor, isMoney, isNegativeMoney, isPositiveMoney, isZeroMoney, majorToMinorUnits, minorUnitsToMajor, money, multiplyMoney, negateMoney, percentOfMinor, subtractMoney, sumMoney, toMajor };
+import { CurrencyMismatchError } from "./currency.mjs";
+import { C as isCashDestination, S as cashDestinationLabel, _ as percentOfMinor, a as equalsMoney, b as toMajor, c as isMoney, d as isZeroMoney, f as majorToMinorUnits, g as negateMoney, h as multiplyMoney, i as compareMoney, l as isNegativeMoney, m as money, n as absMoney, o as formatMinorUnits, p as minorUnitsToMajor, r as addMoney, s as fromMajor, t as MinorUnits, u as isPositiveMoney, v as subtractMoney, x as CASH_DESTINATIONS, y as sumMoney } from "./money-BBOARE5f.mjs";
+export { CASH_DESTINATIONS, CurrencyMismatchError, MinorUnits, absMoney, addMoney, cashDestinationLabel, compareMoney, equalsMoney, formatMinorUnits, fromMajor, isCashDestination, isMoney, isNegativeMoney, isPositiveMoney, isZeroMoney, majorToMinorUnits, minorUnitsToMajor, money, multiplyMoney, negateMoney, percentOfMinor, subtractMoney, sumMoney, toMajor };

package/dist/outbox.d.mts

@@ -46,6 +46,20 @@ interface OutboxClaimOptions {
 interface OutboxClaimedEvent {
   readonly event: DomainEvent;
   readonly fencingToken: number;
+  /**
+   * DURABLE delivery-attempt count for this event, INCLUDING the claim that
+   * returned it (1 on the first claim). Optional: stores that persist a
+   * per-row counter report it; stores that don't leave it absent.
+   *
+   * Why it exists: a relay can only count failures in its own memory, and
+   * that count is wrong in exactly the cases a failure policy exists for.
+   * A poison event that crashes the relay restarts at 1 on every boot, so
+   * `attempts >= 5 → deadLetter` never fires; and across N relays sharing a
+   * store, each counts its own attempts, so "5" means 5×N. The store already
+   * increments a counter atomically inside the claim — reporting it here is
+   * what lets the policy see the true number.
+   */
+  readonly attempts?: number;
 }
 /** Options for {@link OutboxStore.acknowledge}. */
 interface OutboxAcknowledgeOptions {
@@ -81,9 +95,12 @@ interface OutboxFailureContext {
   /** The error returned by the transport / handler. */
   readonly error: Error;
   /**
-   * Attempt count including this failure (1 on the first fail). Tracked
-   * in-process by the relay; accurate within a single relay process, resets
-   * on restart. For durable attempt counts, the policy can query the store.
+   * Attempt count including this failure (1 on the first fail).
+   *
+   * DURABLE when the store reports {@link OutboxClaimedEvent.attempts} from a
+   * fenced claim — survives relay restarts and is shared by every relay on the
+   * store. Otherwise the relay's in-process count: accurate within one relay
+   * process, reset on restart. Relays take the larger of the two.
    */
   readonly attempts: number;
 }

package/dist/payment-events.d.mts

@@ -1,4 +1,4 @@
-import { n as Money } from "./money-CfAvfNiM.mjs";
+import { n as Money } from "./money-C9iLWiWR.mjs";
 import { PaymentMethodKind } from "./payment-method-kind.mjs";
 import { ProviderUnknownCause } from "./payment-gateway.mjs";
 //#region src/events/payment-events.d.ts
@@ -119,6 +119,9 @@ interface PaymentRefundedPayload {
   refundId: string;
   providerRef?: string;
   providerCode: string;
+  /** How the original payment moved — money goes back the way it came, so this places the refund too. */
+  methodKind: PaymentMethodKind;
+  methodCode?: string;
   /** Amount refunded in this event — may be less than the original payment. */
   refundedAmount: Money;
   /** Original payment total — present so consumers can compute remaining refundable without a Payment lookup. */
@@ -142,6 +145,9 @@ interface PaymentReversedPayload {
   paymentId: string;
   providerRef?: string;
   providerCode: string;
+  /** How the payment being unwound moved. */
+  methodKind: PaymentMethodKind;
+  methodCode?: string;
   /** Amount being unwound — equals the original payment for full reversal, less for partial. */
   reversedAmount: Money;
   /** Original payment total — present so consumers can detect partial vs full without a Payment lookup. */

package/dist/payment-gateway.d.mts

@@ -1,4 +1,4 @@
-import { n as Money } from "./money-CfAvfNiM.mjs";
+import { n as Money } from "./money-C9iLWiWR.mjs";
 import { PaymentMethodKind } from "./payment-method-kind.mjs";
 //#region src/money/payment-gateway.d.ts
 /**

package/dist/period.d.mts

@@ -123,6 +123,27 @@ declare function resolveMonth(year: number, month: number, timezone: string): Da
 declare function resolveQuarter(year: number, quarter: 1 | 2 | 3 | 4, timezone: string): DateRange;
 /** Half-open `[start, end)` range covering one local calendar year. */
 declare function resolveYear(year: number, timezone: string): DateRange;
+/** A fiscal year: the calendar year it starts in, its label, and its half-open local range. */
+interface FiscalYear {
+  startYear: number;
+  /** `2026-27` for a year starting mid-calendar-year; `2026` for one starting in January. */
+  label: string;
+  range: DateRange;
+}
+/** Half-open range of the fiscal year starting on the 1st of `startMonth` of `startYear`, local to `timezone`. */
+declare function resolveFiscalYear(startYear: number, opts: {
+  startMonth: number;
+  timezone: string;
+}): DateRange;
+/**
+ * The fiscal year `date` falls in — 1 July–30 June (Bangladesh, Australia), 1 April–31 March (India),
+ * 1 January (most) — decided on the LOCAL calendar day in `timezone`, so the last evening of June in Dhaka
+ * is still the old year.
+ */
+declare function fiscalYearOf(date: Date, opts: {
+  startMonth: number;
+  timezone: string;
+}): FiscalYear;
 /**
  * Half-open range spanning two local dates, INCLUSIVE of both days — what an
  * operator means by "1st to 31st". The half-open end is therefore the start of
@@ -209,4 +230,4 @@ declare function parsePeriod(label: string, timezone?: string): Period;
  */
 declare function formatPeriod(period: Period): string;
 //#endregion
-export { DateRange, DateRangeError, Period, PeriodError, PeriodErrorCode, PeriodGranularity, dayStart, formatPeriod, granularityOf, inclusiveEnd, isDateRange, isWithin, parsePeriod, periodOf, periodTimeZone, rangeDurationMs, rangesOverlap, resolveDateSpan, resolveDay, resolveMonth, resolvePeriod, resolveQuarter, resolveYear, shiftPeriod };
+export { DateRange, DateRangeError, FiscalYear, Period, PeriodError, PeriodErrorCode, PeriodGranularity, dayStart, fiscalYearOf, formatPeriod, granularityOf, inclusiveEnd, isDateRange, isWithin, parsePeriod, periodOf, periodTimeZone, rangeDurationMs, rangesOverlap, resolveDateSpan, resolveDay, resolveFiscalYear, resolveMonth, resolvePeriod, resolveQuarter, resolveYear, shiftPeriod };

package/dist/period.mjs

@@ -181,6 +181,35 @@ function resolveYear(year, timezone) {
 		end: dayStart(`${y + 1}-01-01`, zone)
 	};
 }
+/** Half-open range of the fiscal year starting on the 1st of `startMonth` of `startYear`, local to `timezone`. */
+function resolveFiscalYear(startYear, opts) {
+	const zone = assertZone(opts.timezone);
+	const y = assertYear(startYear);
+	const m = assertMonth(opts.startMonth);
+	return {
+		start: dayStart(`${y}-${pad2(m)}-01`, zone),
+		end: dayStart(`${y + 1}-${pad2(m)}-01`, zone)
+	};
+}
+/**
+* The fiscal year `date` falls in — 1 July–30 June (Bangladesh, Australia), 1 April–31 March (India),
+* 1 January (most) — decided on the LOCAL calendar day in `timezone`, so the last evening of June in Dhaka
+* is still the old year.
+*/
+function fiscalYearOf(date, opts) {
+	const zone = assertZone(opts.timezone);
+	const m = assertMonth(opts.startMonth);
+	const [y, mm] = String(civilDateOf(date, zone)).split("-").map(Number);
+	const startYear = mm >= m ? y : y - 1;
+	return {
+		startYear,
+		label: m === 1 ? String(startYear) : `${startYear}-${pad2((startYear + 1) % 100)}`,
+		range: resolveFiscalYear(startYear, {
+			startMonth: m,
+			timezone: zone
+		})
+	};
+}
 /**
 * Half-open range spanning two local dates, INCLUSIVE of both days — what an
 * operator means by "1st to 31st". The half-open end is therefore the start of
@@ -388,4 +417,4 @@ function formatPeriod(period) {
 	throw new PeriodError("INVALID_LABEL", "An ad-hoc Period (start + end) has no canonical label.");
 }
 //#endregion
-export { DateRangeError, PeriodError, dayStart, formatPeriod, granularityOf, inclusiveEnd, isDateRange, isWithin, parsePeriod, periodOf, periodTimeZone, rangeDurationMs, rangesOverlap, resolveDateSpan, resolveDay, resolveMonth, resolvePeriod, resolveQuarter, resolveYear, shiftPeriod };
+export { DateRangeError, PeriodError, dayStart, fiscalYearOf, formatPeriod, granularityOf, inclusiveEnd, isDateRange, isWithin, parsePeriod, periodOf, periodTimeZone, rangeDurationMs, rangesOverlap, resolveDateSpan, resolveDay, resolveFiscalYear, resolveMonth, resolvePeriod, resolveQuarter, resolveYear, shiftPeriod };

package/dist/phone.d.mts

@@ -40,7 +40,19 @@ declare function formatPhone(phone: PhoneNumber): string;
  * @example formatNational(parsePhone('+14155550182').value!) → '+1 415 555 0182'
  */
 declare function formatNational(phone: PhoneNumber): string;
+/**
+ * Prefix of a stored PLACEHOLDER phone: a record whose `phone` is required and
+ * unique but was created before a number was known gets `pending_<id>`. It means
+ * "no number collected" — never a number to show, dial, dedupe or search on.
+ */
+declare const PLACEHOLDER_PHONE_PREFIX = "pending_";
+/** Mint the placeholder for a phone-less record — unique per `id`. */
+declare function placeholderPhone(id: string): string;
+/** True for a stored placeholder (see {@link PLACEHOLDER_PHONE_PREFIX}); whitespace-tolerant. */
+declare function isPlaceholderPhone(value: unknown): boolean;
+/** A stored phone worth showing: trimmed, or `null` for empty or a placeholder. */
+declare function shownPhone(value: unknown): string | null;
 /** Type guard. */
 declare function isPhoneNumber(value: unknown): value is PhoneNumber;
 //#endregion
-export { PhoneError, PhoneErrorCode, PhoneNumber, formatNational, formatPhone, isPhoneNumber, parsePhone };
+export { PLACEHOLDER_PHONE_PREFIX, PhoneError, PhoneErrorCode, PhoneNumber, formatNational, formatPhone, isPhoneNumber, isPlaceholderPhone, parsePhone, placeholderPhone, shownPhone };

package/dist/phone.mjs

@@ -302,9 +302,29 @@ function formatNational(phone) {
 	const groups = phone.nationalNumber.match(/.{1,3}/g) ?? [];
 	return `+${phone.callingCode} ${groups.join(" ")}`.trim();
 }
+/**
+* Prefix of a stored PLACEHOLDER phone: a record whose `phone` is required and
+* unique but was created before a number was known gets `pending_<id>`. It means
+* "no number collected" — never a number to show, dial, dedupe or search on.
+*/
+const PLACEHOLDER_PHONE_PREFIX = "pending_";
+/** Mint the placeholder for a phone-less record — unique per `id`. */
+function placeholderPhone(id) {
+	return `${PLACEHOLDER_PHONE_PREFIX}${id}`;
+}
+/** True for a stored placeholder (see {@link PLACEHOLDER_PHONE_PREFIX}); whitespace-tolerant. */
+function isPlaceholderPhone(value) {
+	return typeof value === "string" && value.trim().startsWith("pending_");
+}
+/** A stored phone worth showing: trimmed, or `null` for empty or a placeholder. */
+function shownPhone(value) {
+	if (typeof value !== "string") return null;
+	const v = value.trim();
+	return v && !isPlaceholderPhone(v) ? v : null;
+}
 /** Type guard. */
 function isPhoneNumber(value) {
 	return typeof value === "object" && value !== null && typeof value.e164 === "string" && typeof value.callingCode === "string" && typeof value.nationalNumber === "string" && value.e164.startsWith("+");
 }
 //#endregion
-export { PhoneError, formatNational, formatPhone, isPhoneNumber, parsePhone };
+export { PLACEHOLDER_PHONE_PREFIX, PhoneError, formatNational, formatPhone, isPhoneNumber, isPlaceholderPhone, parsePhone, placeholderPhone, shownPhone };

package/dist/proration.d.mts

@@ -1,4 +1,4 @@
-import { n as Money } from "./money-CfAvfNiM.mjs";
+import { n as Money } from "./money-C9iLWiWR.mjs";
 //#region src/money/proration.d.ts
 /**
  * How to count days within a period.
@@ -62,6 +62,16 @@ declare function splitByPeriodFraction(amount: Money, fraction: PeriodFraction):
   readonly consumed: Money;
   readonly remaining: Money;
 };
+/**
+ * The share of `total` carried by `part` of `whole`, in integer minor units — the VAT on a partial
+ * refund, the tax on one tender of a split sale. Largest-remainder rounding, so the share and its
+ * complement sum to `total` exactly; `part === whole` returns `total` untouched.
+ *
+ * @throws ProrationError('INVALID_FRACTION') when an input is not an integer, `whole` is not
+ *   positive, or `part` lies outside `[0, whole]` — a refund larger than its payment is a defect
+ *   upstream, and clamping it would book a plausible number.
+ */
+declare function apportion(total: number, part: number, whole: number): number;
 /**
  * Allocate the `fraction`-weighted part of a `Money` amount, drift-free — the
  * complement (`1 - fraction`) is discarded but computed so rounding is exact
@@ -72,4 +82,4 @@ declare function splitByPeriodFraction(amount: Money, fraction: PeriodFraction):
  */
 declare function allocateMoneyByFraction(amount: Money, fraction: number): Money;
 //#endregion
-export { PeriodFraction, PeriodProgressInput, ProrationError, ProrationErrorCode, ProrationGranularity, allocateMoneyByFraction, periodProgress, splitByPeriodFraction };
+export { PeriodFraction, PeriodProgressInput, ProrationError, ProrationErrorCode, ProrationGranularity, allocateMoneyByFraction, apportion, periodProgress, splitByPeriodFraction };