@classytic/primitives 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -3,6 +3,45 @@
 Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 adhering to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.13.0] - 2026-07-22
+
+### Added — `/unit-cost-rate`: exact per-unit monetary rates (bigint-safe)
+
+- **`@classytic/primitives/unit-cost-rate`** — fractional per-unit monetary
+  rates stored as scaled integers (`scaledAmount = minorPerUnit × RATE_SCALE`,
+  `RATE_SCALE = 1_000_000`). Solves the WAC / FIFO valuation problem where
+  dividing a total by a fractional quantity yields a sub-minor-unit rate
+  (100 paisa ÷ 3 units = 33.333… paisa/unit) that must not lose precision.
+  Exports:
+  - `unitCostRate(minorPerUnit, currency)` — direct rate constructor
+  - `unitCostRateFromTotal(totalMinor, quantity, currency)` — WAC/FIFO
+    constructor; bigint-safe, QTY_SCALE grid for fractional quantities
+  - `extendedAmount(rate, qty, mode?)` — the ONE rate→total rounding boundary;
+    bigint multiplication to keep large amounts exact; default `'half-even'`
+    (banker's rounding), `'half-up'` available for legacy parity
+  - `rateMinorPerUnit(rate)` — display helper (fractional number, NOT for math)
+  - `isUnitCostRate(value)` — structural type guard
+  - `UnitCostRate<C>` interface, `UnitCostRateError`, `UnitCostRateErrorCode`,
+    `RoundingMode`, `RATE_SCALE`
+  - For distributing a top-down charge across lines with no lost minor unit,
+    compose with `allocate` from `@classytic/primitives/split-allocation`.
+
+### Changed — `/outbox` is now the canonical contract owner
+
+- **`@classytic/primitives/outbox` owns the transactional-outbox contract.**
+  Previously this file was documented as a mirror of `@classytic/arc`'s copy
+  ("arc is source of truth, keep bit-identical") while arc's docs said the
+  opposite — a manual-sync drift risk. Settled: primitives owns pure
+  cross-package contracts (events + outbox); arc owns runtime behavior
+  (`EventOutbox` relay, stores, backoff, Fastify integration) and, from
+  arc 2.24+, imports + re-exports this contract instead of duplicating it.
+- **Cross-package `instanceof` now works.** Because arc re-exports these exact
+  `OutboxOwnershipError` / `InvalidOutboxEventError` classes, a store built
+  against primitives throws the same class identity arc's relay catches.
+  Under the old duplication, arc's `instanceof` checks silently missed
+  primitives-thrown ownership errors.
+- No export names or signatures changed — contract surface is identical.
+
 ## [0.11.0] - 2026-07-08
 
 ### Added — eKYC vocabulary + secure OTP primitive

package/dist/unit-cost-rate.d.mts

@@ -0,0 +1,56 @@
+import { r as CurrencyCode } from "./currency-BCJnJBlb.mjs";
+import { MinorUnits } from "./money.mjs";
+
+//#region src/money/unit-cost-rate.d.ts
+/** Fixed, ecosystem-wide rate scale: 6 decimal places below the minor unit. */
+declare const RATE_SCALE = 1000000;
+/** Half-to-even (banker's) is the default; half-up available for legacy parity. */
+type RoundingMode = 'half-even' | 'half-up';
+/**
+ * Minor units per unit, stored as an integer scaled by {@link RATE_SCALE}.
+ * `scale` is carried so a value is self-describing on the wire even if
+ * `RATE_SCALE` ever changes; it is always `RATE_SCALE` today.
+ */
+interface UnitCostRate<C extends string = string> {
+  /** Integer: minor units per unit × `scale`. */
+  readonly scaledAmount: number;
+  readonly currency: C | CurrencyCode | string;
+  /** Always {@link RATE_SCALE}. */
+  readonly scale: number;
+}
+type UnitCostRateErrorCode = 'NOT_FINITE' | 'NEGATIVE' | 'NOT_INTEGER' | 'UNSAFE_INTEGER' | 'NON_POSITIVE_QUANTITY';
+declare class UnitCostRateError extends Error {
+  readonly name = "UnitCostRateError";
+  readonly code: UnitCostRateErrorCode;
+  constructor(code: UnitCostRateErrorCode, message: string);
+}
+/**
+ * Construct a rate from a (possibly fractional) minor-units-per-unit value.
+ *
+ * @example unitCostRate(33.3333, 'BDT') // { scaledAmount: 33_333_300, ... }
+ */
+declare function unitCostRate<C extends string = string>(minorPerUnit: number, currency: C): UnitCostRate<C>;
+/**
+ * Weighted-average constructor: the rate implied by an integer minor-unit
+ * `totalMinor` spread over a (possibly fractional) `quantity`. This is the WAC
+ * / layer-average rate. Overflow-safe via bigint; quantity rounded to the
+ * {@link QTY_SCALE} grid.
+ *
+ * @example unitCostRateFromTotal(100, 3, 'BDT') // 33.333… paisa/unit
+ */
+declare function unitCostRateFromTotal<C extends string = string>(totalMinor: number, quantity: number, currency: C): UnitCostRate<C>;
+/**
+ * The extended monetary amount for `quantity` units at `rate`, rounded to
+ * integer {@link MinorUnits} — the ONE rate→total rounding boundary.
+ *
+ * `round(quantity × scaledAmount / RATE_SCALE)`, computed in bigint so large
+ * amounts never lose precision. A fractional quantity is honoured to
+ * {@link QTY_SCALE} precision.
+ */
+declare function extendedAmount<C extends string = string>(rate: UnitCostRate<C>, quantity: number, mode?: RoundingMode): MinorUnits<C>;
+/** The rate as a plain (fractional) minor-units-per-unit number — for display only. */
+declare function rateMinorPerUnit(rate: UnitCostRate): number;
+/** Structural guard. */
+declare function isUnitCostRate(value: unknown): value is UnitCostRate;
+//#endregion
+export { RATE_SCALE, RoundingMode, UnitCostRate, UnitCostRateError, UnitCostRateErrorCode, extendedAmount, isUnitCostRate, rateMinorPerUnit, unitCostRate, unitCostRateFromTotal };

package/dist/unit-cost-rate.mjs

@@ -0,0 +1,116 @@
+import { MinorUnits } from "./money.mjs";
+//#region src/money/unit-cost-rate.ts
+/** Fixed, ecosystem-wide rate scale: 6 decimal places below the minor unit. */
+const RATE_SCALE = 1e6;
+/**
+* Quantity scale used internally so a fractional quantity (e.g. `2.5`, a UoM
+* split) participates in exact integer/bigint arithmetic. 6 dp of quantity
+* precision — quantities finer than 1e-6 unit are rounded to this grid.
+*/
+const QTY_SCALE = 1e6;
+const DEFAULT_ROUNDING = "half-even";
+var UnitCostRateError = class extends Error {
+	name = "UnitCostRateError";
+	code;
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+	}
+};
+function assertSafe(scaled) {
+	if (!Number.isFinite(scaled)) throw new UnitCostRateError("NOT_FINITE", `unit cost rate is not finite: ${scaled}`);
+	if (!Number.isSafeInteger(scaled)) throw new UnitCostRateError("UNSAFE_INTEGER", `scaled unit cost ${scaled} exceeds Number.MAX_SAFE_INTEGER — value too large for this rate scale`);
+}
+/**
+* Scale a (possibly fractional) quantity onto the {@link QTY_SCALE} grid as a
+* bigint. Guards against a quantity so large that `quantity × QTY_SCALE` loses
+* integer precision as a double BEFORE reaching bigint (≈ >9e9 units).
+*/
+function scaleQuantity(quantity) {
+	const q = Math.round(quantity * QTY_SCALE);
+	if (!Number.isSafeInteger(q)) throw new UnitCostRateError("UNSAFE_INTEGER", `quantity ${quantity} is too large to scale precisely — exceeds safe-integer range`);
+	return BigInt(q);
+}
+/**
+* Construct a rate from a (possibly fractional) minor-units-per-unit value.
+*
+* @example unitCostRate(33.3333, 'BDT') // { scaledAmount: 33_333_300, ... }
+*/
+function unitCostRate(minorPerUnit, currency) {
+	if (!Number.isFinite(minorPerUnit)) throw new UnitCostRateError("NOT_FINITE", `minorPerUnit is not finite: ${minorPerUnit}`);
+	if (minorPerUnit < 0) throw new UnitCostRateError("NEGATIVE", `unit cost cannot be negative: ${minorPerUnit}`);
+	const scaledAmount = Math.round(minorPerUnit * RATE_SCALE);
+	assertSafe(scaledAmount);
+	return {
+		scaledAmount,
+		currency,
+		scale: RATE_SCALE
+	};
+}
+/**
+* Weighted-average constructor: the rate implied by an integer minor-unit
+* `totalMinor` spread over a (possibly fractional) `quantity`. This is the WAC
+* / layer-average rate. Overflow-safe via bigint; quantity rounded to the
+* {@link QTY_SCALE} grid.
+*
+* @example unitCostRateFromTotal(100, 3, 'BDT') // 33.333… paisa/unit
+*/
+function unitCostRateFromTotal(totalMinor, quantity, currency) {
+	if (!Number.isInteger(totalMinor)) throw new UnitCostRateError("NOT_INTEGER", `totalMinor must be integer minor units: ${totalMinor}`);
+	if (!Number.isFinite(quantity) || quantity <= 0) throw new UnitCostRateError("NON_POSITIVE_QUANTITY", `quantity must be > 0, got ${quantity}`);
+	const qScaled = scaleQuantity(quantity);
+	const numerator = BigInt(totalMinor) * BigInt(RATE_SCALE) * BigInt(QTY_SCALE);
+	const scaled = Number(roundedDiv(numerator, qScaled, "half-even"));
+	assertSafe(scaled);
+	return {
+		scaledAmount: scaled,
+		currency,
+		scale: RATE_SCALE
+	};
+}
+/**
+* The extended monetary amount for `quantity` units at `rate`, rounded to
+* integer {@link MinorUnits} — the ONE rate→total rounding boundary.
+*
+* `round(quantity × scaledAmount / RATE_SCALE)`, computed in bigint so large
+* amounts never lose precision. A fractional quantity is honoured to
+* {@link QTY_SCALE} precision.
+*/
+function extendedAmount(rate, quantity, mode = DEFAULT_ROUNDING) {
+	if (!Number.isFinite(quantity) || quantity < 0) throw new UnitCostRateError("NON_POSITIVE_QUANTITY", `quantity must be >= 0, got ${quantity}`);
+	const qScaled = scaleQuantity(quantity);
+	const numerator = BigInt(rate.scaledAmount) * qScaled;
+	const denominator = BigInt(rate.scale) * BigInt(QTY_SCALE);
+	const minor = Number(roundedDiv(numerator, denominator, mode));
+	if (!Number.isSafeInteger(minor)) throw new UnitCostRateError("UNSAFE_INTEGER", `extended amount ${minor} exceeds safe integer range`);
+	return MinorUnits(minor, rate.currency);
+}
+/** The rate as a plain (fractional) minor-units-per-unit number — for display only. */
+function rateMinorPerUnit(rate) {
+	return rate.scaledAmount / rate.scale;
+}
+/** Structural guard. */
+function isUnitCostRate(value) {
+	return typeof value === "object" && value !== null && Number.isInteger(value.scaledAmount) && typeof value.currency === "string" && typeof value.scale === "number";
+}
+/**
+* Rounded integer division of two bigints, `numerator / denominator`
+* (`denominator > 0`), honouring the rounding mode at the exact half.
+* Sign-safe for negative numerators.
+*/
+function roundedDiv(numerator, denominator, mode) {
+	const neg = numerator < 0n;
+	const n = neg ? -numerator : numerator;
+	const q = n / denominator;
+	const remainder = n - q * denominator;
+	if (remainder === 0n) return neg ? -q : q;
+	const twiceRem = remainder * 2n;
+	let up;
+	if (twiceRem > denominator) up = true;
+	else if (twiceRem < denominator) up = false;
+	else up = mode === "half-up" ? true : q % 2n !== 0n;
+	const result = up ? q + 1n : q;
+	return neg ? -result : result;
+}
+//#endregion
+export { RATE_SCALE, UnitCostRateError, extendedAmount, isUnitCostRate, rateMinorPerUnit, unitCostRate, unitCostRateFromTotal };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/primitives",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Framework-agnostic TypeScript primitives shared across Classytic packages — Money, events, pagination, tenant config, and other building blocks.",
   "author": "Classytic",
   "license": "MIT",
@@ -29,6 +29,10 @@
       "types": "./dist/currency.d.mts",
       "default": "./dist/currency.mjs"
     },
+    "./unit-cost-rate": {
+      "types": "./dist/unit-cost-rate.d.mts",
+      "default": "./dist/unit-cost-rate.mjs"
+    },
     "./address": {
       "types": "./dist/address.d.mts",
       "default": "./dist/address.mjs"