@classytic/primitives 0.19.0 → 0.20.0

package/dist/cadence.d.mts

@@ -1,93 +1,2 @@
-//#region src/scheduling/cadence.d.ts
-/**
- * Recurrence spec + pure date arithmetic.
- *
- * Describes "every N days", "every weekday", "on the 15th of each month", etc.
- * Consumed by `@classytic/order` (blanket / recurring orders, subscription
- * renewal), `@classytic/flow` (replenishment schedules), and
- * `@classytic/commission` (vesting periods, statement close).
- *
- * No cron parser dep — the `cron` kind stores an opaque string that the host
- * parses with its own library (node-cron, croner, etc.). This keeps primitives
- * zero-dep and lets hosts pick whatever cron dialect they want.
- *
- * @example
- * const monthly: Cadence = {
- *   kind: 'monthly',
- *   interval: 1,
- *   dayOfMonth: 15,
- *   startAt: new Date('2026-01-15T00:00:00Z'),
- * };
- * nextOccurrence(monthly, new Date('2026-02-20T00:00:00Z'));
- * // → 2026-03-15T00:00:00Z
- */
-type CadenceKind = 'daily' | 'weekly' | 'monthly' | 'yearly' | 'cron';
-/** ISO weekday — 1=Mon … 7=Sun. Matches Temporal + ISO 8601. */
-type IsoWeekday = 1 | 2 | 3 | 4 | 5 | 6 | 7;
-interface CadenceBase {
-  readonly interval: number;
-  readonly startAt: Date;
-  readonly endAt?: Date;
-  /**
-   * Optional timezone IANA name (e.g. `Asia/Dhaka`). Pure functions in this
-   * module operate on UTC Date values; the field is carried for the host to
-   * localize occurrences when displaying. Occurrence math here is UTC-based.
-   */
-  readonly timezone?: string;
-}
-interface DailyCadence extends CadenceBase {
-  readonly kind: 'daily';
-}
-interface WeeklyCadence extends CadenceBase {
-  readonly kind: 'weekly';
-  /**
-   * If provided, only these ISO weekdays count as occurrences; the earliest
-   * matching weekday on or after `startAt` is the first occurrence. If omitted,
-   * the weekday of `startAt` is used.
-   */
-  readonly daysOfWeek?: readonly IsoWeekday[];
-}
-interface MonthlyCadence extends CadenceBase {
-  readonly kind: 'monthly';
-  /**
-   * Day of month, 1–31. If the target month has fewer days (e.g. 31st → Feb),
-   * occurrence snaps to the last day of the month.
-   */
-  readonly dayOfMonth: number;
-}
-interface YearlyCadence extends CadenceBase {
-  readonly kind: 'yearly';
-  /** Calendar month 1–12. */
-  readonly month: number;
-  /** Day of month 1–31. Snaps to last day of month if needed (e.g. Feb 29 → Feb 28 in non-leap years). */
-  readonly dayOfMonth: number;
-}
-interface CronCadence extends CadenceBase {
-  readonly kind: 'cron';
-  /** Opaque cron expression — caller parses with its own cron library. */
-  readonly expression: string;
-}
-type Cadence = DailyCadence | WeeklyCadence | MonthlyCadence | YearlyCadence | CronCadence;
-type CadenceErrorCode = 'INVALID_INTERVAL' | 'INVALID_DAY_OF_MONTH' | 'INVALID_MONTH' | 'INVALID_DAYS_OF_WEEK' | 'INVALID_START_AT' | 'INVALID_END_AT' | 'UNSUPPORTED_CRON';
-declare class CadenceError extends Error {
-  readonly name = "CadenceError";
-  readonly code: CadenceErrorCode;
-  constructor(code: CadenceErrorCode, message: string);
-}
-/** Validate a Cadence spec. Call this before storing host-side. */
-declare function validateCadence(c: Cadence): void;
-/**
- * Next occurrence strictly after `from`. Returns `null` if the cadence has
- * ended (endAt passed) or the first occurrence is still in the future.
- *
- * Cron cadences return `null` — hosts must parse the expression themselves.
- */
-declare function nextOccurrence(cadence: Cadence, from: Date): Date | null;
-/**
- * Enumerate occurrences in `[from, to)` inclusive at `from`, exclusive at `to`.
- * Returns up to `limit` results (default 10_000) to guard against runaway
- * misconfigured cadences. Cron returns an empty array.
- */
-declare function occurrencesBetween(cadence: Cadence, from: Date, to: Date, limit?: number): Date[];
-//#endregion
+import { a as CronCadence, c as MonthlyCadence, d as nextOccurrence, f as occurrencesBetween, i as CadenceKind, l as WeeklyCadence, n as CadenceError, o as DailyCadence, p as validateCadence, r as CadenceErrorCode, s as IsoWeekday, t as Cadence, u as YearlyCadence } from "./cadence-BFQVC1Qp.mjs";
 export { Cadence, CadenceError, CadenceErrorCode, CadenceKind, CronCadence, DailyCadence, IsoWeekday, MonthlyCadence, WeeklyCadence, YearlyCadence, nextOccurrence, occurrencesBetween, validateCadence };

package/dist/cadence.mjs

@@ -1,4 +1,27 @@
+import { addCivilDays, civilDate, civilDateOf, civilDateToInstant, civilDaysBetween, isValidTimeZone, localTimeParts } from "./timezone.mjs";
 //#region src/scheduling/cadence.ts
+/**
+* Recurrence spec + pure date arithmetic.
+*
+* Describes "every N days", "every weekday", "on the 15th of each month", etc.
+* Consumed by `@classytic/order` (blanket / recurring orders, subscription
+* renewal), `@classytic/flow` (replenishment schedules), and
+* `@classytic/commission` (vesting periods, statement close).
+*
+* No cron parser dep — the `cron` kind stores an opaque string that the host
+* parses with its own library (node-cron, croner, etc.). This keeps primitives
+* zero-dep and lets hosts pick whatever cron dialect they want.
+*
+* @example
+* const monthly: Cadence = {
+*   kind: 'monthly',
+*   interval: 1,
+*   dayOfMonth: 15,
+*   startAt: new Date('2026-01-15T00:00:00Z'),
+* };
+* nextOccurrence(monthly, new Date('2026-02-20T00:00:00Z'));
+* // → 2026-03-15T00:00:00Z
+*/
 var CadenceError = class extends Error {
 	name = "CadenceError";
 	code;
@@ -13,6 +36,7 @@ function validateCadence(c) {
 	if (Number.isNaN(c.startAt.getTime())) throw new CadenceError("INVALID_START_AT", "startAt is not a valid Date");
 	if (c.endAt && Number.isNaN(c.endAt.getTime())) throw new CadenceError("INVALID_END_AT", "endAt is not a valid Date");
 	if (c.endAt && c.endAt.getTime() < c.startAt.getTime()) throw new CadenceError("INVALID_END_AT", "endAt must be >= startAt");
+	if (c.timezone !== void 0 && !isValidTimeZone(c.timezone)) throw new CadenceError("INVALID_TIMEZONE", `timezone must be a valid IANA zone name (e.g. 'Asia/Dhaka'), got '${c.timezone}'`);
 	if (c.kind === "weekly" && c.daysOfWeek) {
 		if (c.daysOfWeek.length === 0) throw new CadenceError("INVALID_DAYS_OF_WEEK", "daysOfWeek cannot be empty");
 		for (const d of c.daysOfWeek) if (!Number.isInteger(d) || d < 1 || d > 7) throw new CadenceError("INVALID_DAYS_OF_WEEK", `daysOfWeek entry must be 1–7, got ${d}`);
@@ -61,14 +85,119 @@ function occurrencesBetween(cadence, from, to, limit = 1e4) {
 	return result;
 }
 function stepForward(cadence, from) {
+	const zone = cadence.timezone;
 	switch (cadence.kind) {
-		case "daily": return stepDaily(cadence, from);
-		case "weekly": return stepWeekly(cadence, from);
-		case "monthly": return stepMonthly(cadence, from);
-		case "yearly": return stepYearly(cadence, from);
+		case "daily": return zone === void 0 ? stepDaily(cadence, from) : stepDailyZoned(cadence, from, zone);
+		case "weekly": return zone === void 0 ? stepWeekly(cadence, from) : stepWeeklyZoned(cadence, from, zone);
+		case "monthly": return zone === void 0 ? stepMonthly(cadence, from) : stepMonthlyZoned(cadence, from, zone);
+		case "yearly": return zone === void 0 ? stepYearly(cadence, from) : stepYearlyZoned(cadence, from, zone);
 		default: return null;
 	}
 }
+/**
+* The anchor's LOCAL wall clock. Seconds and milliseconds come straight from
+* the instant because every modern IANA offset is a whole number of minutes —
+* they are the same in every zone.
+*/
+function wallClockOf(instant, zone) {
+	const cd = civilDateOf(instant, zone);
+	const { hour, minute } = localTimeParts(instant, zone);
+	return {
+		year: Number(cd.slice(0, 4)),
+		month: Number(cd.slice(5, 7)),
+		day: Number(cd.slice(8, 10)),
+		hour,
+		minute,
+		second: instant.getUTCSeconds(),
+		millisecond: instant.getUTCMilliseconds()
+	};
+}
+const pad2 = (n) => String(n).padStart(2, "0");
+function civilOf(year, month, day) {
+	return civilDate(`${String(year).padStart(4, "0")}-${pad2(month)}-${pad2(day)}`);
+}
+/** Bind a local calendar day + the anchor's local time-of-day to an instant. */
+function bindWall(cd, wall, zone) {
+	return civilDateToInstant(cd, zone, {
+		hour: wall.hour,
+		minute: wall.minute,
+		second: wall.second,
+		millisecond: wall.millisecond
+	});
+}
+/** Occurrences are anchor-local-date + n×interval LOCAL days, at the anchor's local time. */
+function stepDailyZoned(c, from, zone) {
+	const wall = wallClockOf(c.startAt, zone);
+	const anchorCd = civilOf(wall.year, wall.month, wall.day);
+	const elapsed = civilDaysBetween(anchorCd, civilDateOf(from, zone));
+	let n = Math.max(0, Math.floor(elapsed / c.interval) * c.interval);
+	for (let i = 0; i < 1e3; i++) {
+		const candidate = bindWall(addCivilDays(anchorCd, n), wall, zone);
+		if (candidate.getTime() > from.getTime()) return candidate;
+		n += c.interval;
+	}
+	return bindWall(addCivilDays(anchorCd, n), wall, zone);
+}
+/** ISO weekday of a civil date — zone-free, a calendar day has a determinate weekday. */
+function isoWeekdayOfCivil(cd) {
+	const utc = Date.UTC(Number(cd.slice(0, 4)), Number(cd.slice(5, 7)) - 1, Number(cd.slice(8, 10)));
+	return (new Date(utc).getUTCDay() + 6) % 7 + 1;
+}
+function stepWeeklyZoned(c, from, zone) {
+	const wall = wallClockOf(c.startAt, zone);
+	const anchorCd = civilOf(wall.year, wall.month, wall.day);
+	const targetDays = c.daysOfWeek ?? [isoWeekdayOfCivil(anchorCd)];
+	let cursor = civilDateOf(from, zone);
+	const maxSteps = Math.max(60, c.interval * 14) + 2;
+	for (let i = 0; i < maxSteps; i++) {
+		if (targetDays.includes(isoWeekdayOfCivil(cursor))) {
+			const weeksSinceAnchor = Math.floor(civilDaysBetween(anchorCd, cursor) / 7);
+			if (weeksSinceAnchor >= 0 && weeksSinceAnchor % c.interval === 0) {
+				const candidate = bindWall(cursor, wall, zone);
+				if (candidate.getTime() > from.getTime()) return candidate;
+			}
+		}
+		cursor = addCivilDays(cursor, 1);
+	}
+	return bindWall(cursor, wall, zone);
+}
+function stepMonthlyZoned(c, from, zone) {
+	const wall = wallClockOf(c.startAt, zone);
+	let candYear = wall.year;
+	let candMonth = wall.month;
+	const fromCd = civilDateOf(from, zone);
+	const monthsDiff = (Number(fromCd.slice(0, 4)) - wall.year) * 12 + (Number(fromCd.slice(5, 7)) - wall.month);
+	if (monthsDiff > 0) {
+		const aligned = Math.floor(monthsDiff / c.interval) * c.interval;
+		const abs = candYear * 12 + (candMonth - 1) + aligned;
+		candYear = Math.floor(abs / 12);
+		candMonth = abs % 12 + 1;
+	}
+	for (let i = 0; i < 1e3; i++) {
+		const day = clampDayOfMonth(c.dayOfMonth, candYear, candMonth - 1);
+		const candidate = bindWall(civilOf(candYear, candMonth, day), wall, zone);
+		if (candidate.getTime() > from.getTime()) return candidate;
+		candMonth += c.interval;
+		while (candMonth > 12) {
+			candMonth -= 12;
+			candYear += 1;
+		}
+	}
+	return bindWall(civilOf(candYear, candMonth, clampDayOfMonth(c.dayOfMonth, candYear, candMonth - 1)), wall, zone);
+}
+function stepYearlyZoned(c, from, zone) {
+	const wall = wallClockOf(c.startAt, zone);
+	let candYear = wall.year;
+	const yearsDiff = Number(civilDateOf(from, zone).slice(0, 4)) - wall.year;
+	if (yearsDiff > 0) candYear += Math.floor(yearsDiff / c.interval) * c.interval;
+	for (let i = 0; i < 1e3; i++) {
+		const day = clampDayOfMonth(c.dayOfMonth, candYear, c.month - 1);
+		const candidate = bindWall(civilOf(candYear, c.month, day), wall, zone);
+		if (candidate.getTime() > from.getTime()) return candidate;
+		candYear += c.interval;
+	}
+	return bindWall(civilOf(candYear, c.month, clampDayOfMonth(c.dayOfMonth, candYear, c.month - 1)), wall, zone);
+}
 function stepDaily(c, from) {
 	const start = c.startAt;
 	const diffDays = Math.floor((from.getTime() - start.getTime()) / (1440 * 60 * 1e3));

package/dist/calendar-B6fm-FbR.d.mts

@@ -0,0 +1,46 @@
+//#region src/scheduling/calendar.d.ts
+/**
+ * Calendar boundaries + arithmetic — the ONE place the stack computes
+ * "start of day / month", weekday, and month/day/year addition, so no package
+ * hand-rolls it with server-LOCAL `Date` methods (`getFullYear`/`getMonth`/
+ * `getDate`/`getDay`), which silently shift with the deploy machine's `TZ` env.
+ *
+ * Every function is PURE and takes a fixed **UTC offset in minutes** (east of
+ * UTC — `360` = UTC+6 / Asia-Dhaka). Same convention as `cadence` / `sla-policy`:
+ * no IANA tz database, no DST. A fixed offset is exact for zones without DST
+ * (e.g. Bangladesh, India, most of Asia) and is what a "daily limit resets at
+ * local midnight" boundary needs. For DST-correct wall-clock math the host
+ * resolves the offset for the instant and passes it in.
+ *
+ * `Date` instants are UTC epoch and timezone-independent — these helpers only
+ * decide WHERE the day/month boundary falls, never how "now" is recorded.
+ *
+ * Resolving that offset from an IANA zone name is `/timezone`'s job — the
+ * two compose: `startOfMonth(instant, zoneOffsetMinutes(instant, zone))`.
+ * For a DST-exact DAY boundary prefer the civil-date round-trip from
+ * `/timezone`: `civilDateToInstant(civilDateOf(instant, zone), zone)`.
+ */
+/** Minutes east of UTC. `0` = UTC, `360` = UTC+6 (Asia/Dhaka), `-300` = UTC-5. */
+type UtcOffsetMinutes = number;
+/**
+ * The absolute instant of local midnight for the day CONTAINING `instant`, in
+ * the given offset. `startOfDay(2026-07-02T03:00Z, 360)` → `2026-07-01T18:00Z`
+ * (Dhaka midnight). With `offsetMinutes = 0` it's plain UTC midnight.
+ */
+declare function startOfDay(instant: Date, offsetMinutes?: UtcOffsetMinutes): Date;
+/** The absolute instant of the first-of-month midnight, in the given offset. */
+declare function startOfMonth(instant: Date, offsetMinutes?: UtcOffsetMinutes): Date;
+/** ISO weekday (1 = Monday … 7 = Sunday) of `instant` in the given offset. */
+declare function isoWeekday(instant: Date, offsetMinutes?: UtcOffsetMinutes): number;
+/** Add whole days as an exact 24h × n duration (offset-agnostic, no DST skew). */
+declare function addDays(instant: Date, days: number): Date;
+/**
+ * Add calendar months in UTC, clamping the day so month-ends never overflow
+ * (`addMonths(Jan 31, 1)` → Feb 28/29). Use for subscription/access periods
+ * instead of local `setMonth(getMonth() + n)`.
+ */
+declare function addMonths(instant: Date, months: number): Date;
+/** Add calendar years in UTC (clamps Feb 29 → Feb 28 on non-leap years). */
+declare function addYears(instant: Date, years: number): Date;
+//#endregion
+export { isoWeekday as a, addYears as i, addDays as n, startOfDay as o, addMonths as r, startOfMonth as s, UtcOffsetMinutes as t };

package/dist/calendar.d.mts

@@ -1,46 +1,2 @@
-//#region src/scheduling/calendar.d.ts
-/**
- * Calendar boundaries + arithmetic — the ONE place the stack computes
- * "start of day / month", weekday, and month/day/year addition, so no package
- * hand-rolls it with server-LOCAL `Date` methods (`getFullYear`/`getMonth`/
- * `getDate`/`getDay`), which silently shift with the deploy machine's `TZ` env.
- *
- * Every function is PURE and takes a fixed **UTC offset in minutes** (east of
- * UTC — `360` = UTC+6 / Asia-Dhaka). Same convention as `cadence` / `sla-policy`:
- * no IANA tz database, no DST. A fixed offset is exact for zones without DST
- * (e.g. Bangladesh, India, most of Asia) and is what a "daily limit resets at
- * local midnight" boundary needs. For DST-correct wall-clock math the host
- * resolves the offset for the instant and passes it in.
- *
- * `Date` instants are UTC epoch and timezone-independent — these helpers only
- * decide WHERE the day/month boundary falls, never how "now" is recorded.
- *
- * Resolving that offset from an IANA zone name is `/timezone`'s job — the
- * two compose: `startOfMonth(instant, zoneOffsetMinutes(instant, zone))`.
- * For a DST-exact DAY boundary prefer the civil-date round-trip from
- * `/timezone`: `civilDateToInstant(civilDateOf(instant, zone), zone)`.
- */
-/** Minutes east of UTC. `0` = UTC, `360` = UTC+6 (Asia/Dhaka), `-300` = UTC-5. */
-type UtcOffsetMinutes = number;
-/**
- * The absolute instant of local midnight for the day CONTAINING `instant`, in
- * the given offset. `startOfDay(2026-07-02T03:00Z, 360)` → `2026-07-01T18:00Z`
- * (Dhaka midnight). With `offsetMinutes = 0` it's plain UTC midnight.
- */
-declare function startOfDay(instant: Date, offsetMinutes?: UtcOffsetMinutes): Date;
-/** The absolute instant of the first-of-month midnight, in the given offset. */
-declare function startOfMonth(instant: Date, offsetMinutes?: UtcOffsetMinutes): Date;
-/** ISO weekday (1 = Monday … 7 = Sunday) of `instant` in the given offset. */
-declare function isoWeekday(instant: Date, offsetMinutes?: UtcOffsetMinutes): number;
-/** Add whole days as an exact 24h × n duration (offset-agnostic, no DST skew). */
-declare function addDays(instant: Date, days: number): Date;
-/**
- * Add calendar months in UTC, clamping the day so month-ends never overflow
- * (`addMonths(Jan 31, 1)` → Feb 28/29). Use for subscription/access periods
- * instead of local `setMonth(getMonth() + n)`.
- */
-declare function addMonths(instant: Date, months: number): Date;
-/** Add calendar years in UTC (clamps Feb 29 → Feb 28 on non-leap years). */
-declare function addYears(instant: Date, years: number): Date;
-//#endregion
+import { a as isoWeekday, i as addYears, n as addDays, o as startOfDay, r as addMonths, s as startOfMonth, t as UtcOffsetMinutes } from "./calendar-B6fm-FbR.mjs";
 export { UtcOffsetMinutes, addDays, addMonths, addYears, isoWeekday, startOfDay, startOfMonth };

package/dist/canonical.mjs

@@ -54,6 +54,23 @@ function canonicalize(value, seen) {
 	seen.add(obj);
 	try {
 		if (Array.isArray(value)) return `[${value.map((v) => canonicalize(v, seen)).join(",")}]`;
+		/**
+		* Reject CLASS INSTANCES — the silent-collapse hole.
+		*
+		* `Object.keys()` sees only own enumerable properties, so a `Types.ObjectId`,
+		* a `Buffer`, a `URL` or a hydrated Mongoose subdocument serializes as `{}`
+		* (or as a digit-keyed byte map). The digest then ignores the value entirely:
+		* two manifests referencing DIFFERENT documents hash identically, and the
+		* integrity check this module exists to provide reports "unchanged". That is
+		* the same failure mode the explicit `Date` branch above was written to
+		* prevent, so it gets the same treatment — an unsupported type FAILS.
+		*
+		* Callers holding ORM values project them to plain data first (see
+		* spine-accounting's `plainRef` / `plainSummary`); this makes that discipline
+		* enforced rather than remembered.
+		*/
+		const proto = Object.getPrototypeOf(value);
+		if (proto !== null && proto !== Object.prototype) throw new CanonicalizeError(`class instance '${value.constructor?.name ?? "unknown"}' is not serializable — its own enumerable keys are not its value, so it would digest as {} and silently defeat the checksum. Project it to a plain object first.`);
 		const rec = value;
 		return `{${Object.keys(rec).sort().map((k) => `${JSON.stringify(k)}:${canonicalize(rec[k], seen)}`).join(",")}}`;
 	} finally {

package/dist/context.d.mts

@@ -38,6 +38,33 @@ interface OperationContext {
   /** Free-form metadata the host may attach (locale, timezone, user-agent…). */
   metadata?: Readonly<Record<string, unknown>>;
 }
+/**
+ * Structured logger — OBJECT-FIRST (`warn(fields, message)`), the pino / `fastify.log`
+ * convention.
+ *
+ * ## Why this is separate from `ErrorLogger` / `EventLogger`
+ *
+ * Those two (in `primitives/events`) are MESSAGE-FIRST — `error(message, ...args)`, the console
+ * convention — and `EventLogger`'s own docblock notes it mirrors arc's. The two conventions are
+ * not interchangeable: swapping them silently logs an object where a format string was expected,
+ * so a port must say which one it wants.
+ *
+ * This lives here rather than being re-declared per package because it was already declared per
+ * package: an identical object-first shape existed in `spine-kit` as `PlacementLogger`, and the
+ * next package needing one would have made a fourth. A logger is shared vocabulary, not domain.
+ *
+ * `warn`/`error` are required; `info` is OPTIONAL on purpose — a hand-written test logger or a
+ * script's two-method stub is a legitimate caller, and requiring `info` would break every one of
+ * them the day something wanted to log a healthy tick. Reach it as `logger?.info?.(…)`.
+ *
+ * `fastify.log` and a pino instance both satisfy this structurally, so hosts pass `req.log`
+ * with no cast.
+ */
+interface StructuredLogger {
+  warn(fields: Record<string, unknown>, message: string): void;
+  error(fields: Record<string, unknown>, message: string): void;
+  info?(fields: Record<string, unknown>, message: string): void;
+}
 /** An identity shape — useful on audit fields (`createdBy`, `updatedBy`). */
 interface ActorRef {
   id: string;
@@ -45,4 +72,4 @@ interface ActorRef {
   name?: string;
 }
 //#endregion
-export { ActorRef, OperationContext };
+export { ActorRef, OperationContext, StructuredLogger };

package/dist/currency.d.mts

@@ -1,2 +1,2 @@
-import { a as MINOR_UNIT_FACTOR, c as isFxSnapshot, d as toCurrencyCode, i as FxSnapshot, l as minorUnitFactor, n as CURRENCY_PATTERN, o as convertWithSnapshot, r as CurrencyCode, s as isCurrencyCode, t as CURRENCIES, u as reverseWithSnapshot } from "./currency-BCJnJBlb.mjs";
-export { CURRENCIES, CURRENCY_PATTERN, CurrencyCode, FxSnapshot, MINOR_UNIT_FACTOR, convertWithSnapshot, isCurrencyCode, isFxSnapshot, minorUnitFactor, reverseWithSnapshot, toCurrencyCode };
+import { A as convertWithSnapshot, C as CURRENCY_PATTERN, D as FxSnapshot, E as FxRounding, F as minorUnitFactor, I as reverseWithSnapshot, L as toCurrencyCode, M as isCurrencyCode, N as isFxSnapshot, O as InvalidCurrencyCodeError, P as isKnownCurrency, S as CURRENCIES, T as CurrencyMismatchError, j as currencyCode, k as MINOR_UNIT_FACTOR, w as CurrencyCode } from "./money-DPo9fLBi.mjs";
+export { CURRENCIES, CURRENCY_PATTERN, CurrencyCode, CurrencyMismatchError, FxRounding, FxSnapshot, InvalidCurrencyCodeError, MINOR_UNIT_FACTOR, convertWithSnapshot, currencyCode, isCurrencyCode, isFxSnapshot, isKnownCurrency, minorUnitFactor, reverseWithSnapshot, toCurrencyCode };

package/dist/currency.mjs

@@ -26,11 +26,20 @@ const CURRENCIES = {
 	IDR: "IDR"
 };
 /**
-* Number of minor units per major unit for common currencies.
+* Number of minor units per major unit, by ISO 4217 code.
 *
-* ISO 4217 defines most currencies with 2 decimal places (cents). A few are
-* zero-decimal (JPY, KRW) or three-decimal (BHD, KWD, JOD). When a currency
-* isn't in this table, {@link minorUnitFactor} returns 100 as the safe default.
+* **This table must list EVERY currency whose exponent is not 2.** ISO 4217
+* defaults to 2 decimals, and {@link minorUnitFactor} falls back to 100 for a
+* code it does not know — which is correct for the ~150 two-decimal currencies
+* and catastrophically wrong for the others. A missing zero-decimal entry does
+* not throw: it makes `fromMajor(1500, 'GNF')` store 150 000 minor units, a
+* 100× error that reads as a plausible number all the way to the gateway.
+*
+* So the exceptions are enumerated EXHAUSTIVELY (all 0-, 3- and 4-decimal
+* codes), leaving the `?? 100` fallback reachable only by a code that is not a
+* real ISO 4217 currency — a typo, a lowercased code, or a placeholder. The
+* two-decimal entries below are redundant with the default and kept only as
+* documentation of the common set.
 */
 const MINOR_UNIT_FACTOR = {
 	USD: 100,
@@ -53,13 +62,31 @@ const MINOR_UNIT_FACTOR = {
 	HKD: 100,
 	THB: 100,
 	IDR: 100,
+	BIF: 1,
+	CLP: 1,
+	DJF: 1,
+	GNF: 1,
+	ISK: 1,
+	KMF: 1,
 	KRW: 1,
+	PYG: 1,
+	RWF: 1,
+	UGX: 1,
+	UYI: 1,
 	VND: 1,
+	VUV: 1,
+	XAF: 1,
+	XOF: 1,
+	XPF: 1,
 	BHD: 1e3,
-	KWD: 1e3,
+	IQD: 1e3,
 	JOD: 1e3,
+	KWD: 1e3,
+	LYD: 1e3,
 	OMR: 1e3,
-	TND: 1e3
+	TND: 1e3,
+	CLF: 1e4,
+	UYW: 1e4
 };
 /**
 * ISO 4217 format — 3 uppercase letters. Exported so consumers can embed
@@ -78,26 +105,107 @@ const CURRENCY_PATTERN = /^[A-Z]{3}$/;
 function toCurrencyCode(value) {
 	return CURRENCY_PATTERN.test(value) ? value : null;
 }
+/**
+* Validate + brand, or throw. The constructor form — same relationship to
+* {@link toCurrencyCode} that `civilDate` has to `isCivilDate`.
+*
+* `Money` carries a {@link CurrencyCode}, not a bare string, and this is where
+* an untrusted value earns the brand. Rejecting `'jpy'` here matters: lowercase
+* misses {@link MINOR_UNIT_FACTOR}, so it silently becomes a 2-decimal currency
+* and every JPY amount is off by 100×.
+*/
+function currencyCode(value) {
+	const code = toCurrencyCode(value);
+	if (code === null) throw new InvalidCurrencyCodeError(value);
+	return code;
+}
+var InvalidCurrencyCodeError = class extends Error {
+	name = "InvalidCurrencyCodeError";
+	value;
+	constructor(value) {
+		super(`Invalid ISO 4217 currency code '${value}' — expected three uppercase letters. A code that misses the minor-unit table is assumed to have two decimals, which is a 100× error for JPY-style currencies.`);
+		this.value = value;
+	}
+};
+/**
+* Raised when an operation combines two currencies.
+*
+* Declared HERE rather than in `/money` so the FX seam below can throw it
+* without a runtime import back into `/money` (which imports
+* {@link minorUnitFactor} from this file). `/money` re-exports it, so
+* `import { CurrencyMismatchError } from '@classytic/primitives/money'` still
+* resolves.
+*/
+var CurrencyMismatchError = class extends Error {
+	name = "CurrencyMismatchError";
+	left;
+	right;
+	constructor(left, right) {
+		super(`Currency mismatch: ${left} vs ${right}`);
+		this.left = left;
+		this.right = right;
+	}
+};
 /** Type predicate for `unknown` input. */
 function isCurrencyCode(value) {
 	return typeof value === "string" && CURRENCY_PATTERN.test(value);
 }
 /**
-* Minor units per major unit (e.g. 100 for USD, 1 for JPY, 1000 for KWD).
-* Falls back to 100 when the currency is unknown — matches the ISO 4217 default.
+* Minor units per major unit (100 for USD, 1 for JPY, 1000 for KWD, 10 000 for CLF).
+*
+* Falls back to 100 for an unlisted code — the ISO 4217 default exponent. Because
+* {@link MINOR_UNIT_FACTOR} enumerates every non-2-decimal currency, that fallback
+* is now only reached by codes that are not ISO 4217 currencies at all; use
+* {@link isKnownCurrency} at a config/boot boundary if you need to reject those
+* rather than assume two decimals for them.
 */
 function minorUnitFactor(currency) {
 	return MINOR_UNIT_FACTOR[currency] ?? 100;
 }
 /**
-* Apply an {@link FxSnapshot} to a source-currency amount. Returns the
-* equivalent base-currency amount. No rounding — callers that persist into
-* an integer minor-unit column must round explicitly with a deterministic
-* rule (`Math.round`, banker's rounding, floor for duty-conservative
-* postings, etc.).
+* Does {@link MINOR_UNIT_FACTOR} carry an explicit exponent for this code?
+*
+* `false` means {@link minorUnitFactor} would ASSUME two decimals. That
+* assumption is right for an ordinary ISO 4217 code and wrong by 100× for a
+* mistyped or lowercased one (`'jpy'`), so a boot-time config validator that
+* accepts an operator-supplied currency should gate on this instead of letting
+* the default answer for it.
 */
-function convertWithSnapshot(sourceAmount, fx) {
-	return sourceAmount * fx.rate;
+function isKnownCurrency(currency) {
+	return Object.hasOwn(MINOR_UNIT_FACTOR, currency);
+}
+function roundMinor(raw, mode) {
+	if (mode === "floor") return Math.floor(raw);
+	if (mode === "ceil") return Math.ceil(raw);
+	return Math.round(Math.abs(raw)) * (raw < 0 ? -1 : 1);
+}
+/**
+* Apply an {@link FxSnapshot} to a source-currency amount.
+*
+* ## Why this takes `Money` and not a number
+*
+* It used to take a bare `number`, which meant nothing could check the amount
+* was denominated in `fx.sourceCurrency`. Applying a USD→BDT snapshot to a EUR
+* amount type-checked, ran, and returned a plausible wrong number — the
+* arithmetic is identical, only the meaning is wrong, so no test that asserts a
+* total would notice. Taking `Money` lets the seam enforce its own
+* precondition: a mismatch throws {@link CurrencyMismatchError}.
+*
+* ## Minor-unit exponents are handled
+*
+* The rate is quoted in MAJOR units (1 source = `rate` base), while `Money`
+* holds minor units, and the two currencies need not share an exponent
+* (USD has 2, JPY has 0). The conversion therefore goes
+* `minor → major → ×rate → base minor`, not a naive `amount × rate`, which is
+* off by 100× for any pair whose exponents differ.
+*/
+function convertWithSnapshot(source, fx, options = {}) {
+	if (source.currency !== fx.sourceCurrency) throw new CurrencyMismatchError(source.currency, fx.sourceCurrency);
+	if (!Number.isFinite(fx.rate)) throw new TypeError(`FxSnapshot.rate must be finite, got ${fx.rate}`);
+	return {
+		amount: roundMinor(source.amount / minorUnitFactor(fx.sourceCurrency) * fx.rate * minorUnitFactor(fx.baseCurrency), options.rounding ?? "half-away-from-zero"),
+		currency: currencyCode(fx.baseCurrency)
+	};
 }
 /**
 * Reverse an {@link FxSnapshot} — reconstruct the source-currency amount
@@ -105,10 +213,17 @@ function convertWithSnapshot(sourceAmount, fx) {
 * currency". Not round-trip safe under rounding; prefer storing the
 * original source amount alongside the base amount when audit fidelity
 * matters.
+*
+* Symmetrically guarded: a base amount that is not in `fx.baseCurrency` throws
+* rather than dividing by a rate that does not describe it.
 */
-function reverseWithSnapshot(baseAmount, fx) {
-	if (fx.rate === 0) throw new Error("FxSnapshot.rate must be non-zero");
-	return baseAmount / fx.rate;
+function reverseWithSnapshot(base, fx, options = {}) {
+	if (base.currency !== fx.baseCurrency) throw new CurrencyMismatchError(base.currency, fx.baseCurrency);
+	if (fx.rate === 0 || !Number.isFinite(fx.rate)) throw new TypeError(`FxSnapshot.rate must be a non-zero finite number, got ${fx.rate}`);
+	return {
+		amount: roundMinor(base.amount / minorUnitFactor(fx.baseCurrency) / fx.rate * minorUnitFactor(fx.sourceCurrency), options.rounding ?? "half-away-from-zero"),
+		currency: currencyCode(fx.sourceCurrency)
+	};
 }
 /**
 * Structural validation — checks shape only. Does NOT verify the rate is
@@ -121,4 +236,4 @@ function isFxSnapshot(value) {
 	return typeof v.sourceCurrency === "string" && typeof v.baseCurrency === "string" && typeof v.rate === "number" && Number.isFinite(v.rate) && v.rate > 0 && v.snapshotAt instanceof Date;
 }
 //#endregion
-export { CURRENCIES, CURRENCY_PATTERN, MINOR_UNIT_FACTOR, convertWithSnapshot, isCurrencyCode, isFxSnapshot, minorUnitFactor, reverseWithSnapshot, toCurrencyCode };
+export { CURRENCIES, CURRENCY_PATTERN, CurrencyMismatchError, InvalidCurrencyCodeError, MINOR_UNIT_FACTOR, convertWithSnapshot, currencyCode, isCurrencyCode, isFxSnapshot, isKnownCurrency, minorUnitFactor, reverseWithSnapshot, toCurrencyCode };