@classytic/primitives 0.30.0 → 0.31.1

package/CHANGELOG.md

@@ -3,7 +3,56 @@
 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.30.0 — 2026-10-11
+## 0.31.1 — 2026-10-11
+
+### Fixed — `convertWithSnapshot` is exact (`./currency`)
+- The conversion was computed in floating point (`minor / sourceFactor × rate × baseFactor`) and then
+  rounded, so a result that lands EXACTLY on a rounding boundary could round the wrong way. USD 5.30 at
+  110.15 is exactly 583.795 BDT; the float product was 583.79499…, giving 58379 paisa instead of 58380.
+  Over 1..99,999 cents the float form was off by one minor unit for 134 amounts at 110.15, 1,455 at 117.35
+  and 1,379 at 122.35.
+- The rate is now read as the decimal it prints as (`String(rate)`, exponent form included) and the
+  conversion is done in BigInt, rounded once. Signature and rounding modes are unchanged
+  (`half-away-from-zero` default, `floor`, `ceil`).
+- What changes: only results that were wrong. Under `half-away-from-zero`, amounts whose exact value is a
+  half-way point now round away from zero (one minor unit up in magnitude). Under `floor` / `ceil`, amounts
+  whose exact value is an integer are no longer nudged one unit off it (USD 2.20 at 110.15 `ceil` was 24234,
+  now 24233). A negative amount that rounds to zero now returns `0`, not `-0`. Every other result is
+  identical (checked against the float form across ~10.9M amount × rate × currency-pair × mode cases).
+- `convertWithSnapshot` now throws `TypeError` for a non-integer `source.amount` (a `Money` invariant that
+  `money()` already enforces), rather than converting a fractional minor unit.
+- `reverseWithSnapshot` is unchanged.
+
+## 0.31.0 — 2026-10-11
+
+### Added — `./quantity`: the 6-decimal quantity grid for fractional stock and sale quantities
+- `snapQuantity(qty, step?, mode)` (half-even by default), `isOnStep`, `compareQuantity`, `quantitiesEqual`,
+  `quantityToGrid`, `quantityStepToGrid`, `QUANTITY_SCALE` (1,000,000) and `QuantityError`
+  (`NOT_FINITE` / `INVALID_STEP` / `UNSAFE_QUANTITY`).
+- `isOnQuantityGrid(value)`: STRICT, for input boundaries. `isOnStep` snaps first, so
+  `isOnStep(2.3500004, 0.001)` is true; `isOnQuantityGrid(2.3500004)` is false.
+
+### Added — `./usage-pricing`
+- `priceUsage(rating, measured)` prices a measured amount against a `UsageRating` (per-unit, tiered, volume,
+  package; a started unit counts whole; breakdown included), plus `UsageMeasure` / `isUsageMeasure` and
+  `UsagePricingError`.
+
+### Added — the stock unit group on item facts
+- `uomGroupRef` (optional) on `ItemStockSource`, `ProductFacet` and `ItemStockFacts`, and `unitOfMeasureDeclared`
+  (optional) on `ProductFacet` and `ItemStockFacts`. `resolveStockFacts` takes the Item's group, falls back to
+  the product's only when no Item exists, and marks an ungrouped Item under a grouped product
+  `unitOfMeasureDeclared` instead of borrowing the product's group. All fields optional: existing values of these
+  types still type-check.
+
+### Changed — `resolvePriceBasisTotal` accepts a fractional quantity
+- A whole quantity is computed exactly as before, across the full safe-integer range (pinned by a regression
+  test against the previous formula).
+- A fractional quantity on the 6-decimal grid (e.g. `2.35`) is priced exactly: price × quantity on the grid,
+  divided by the measured basis, rounded ONCE half-even. Previously it threw `INVALID_QUANTITY`.
+- Still refused (`INVALID_QUANTITY`): a negative, non-finite or off-grid quantity (a 7th decimal), or a
+  fraction too large to scale exactly.
+
+## 0.30.0 — never published separately; shipped in 0.31.0
 
 ### Added — `./durable-events`: the declaration and the ONE kernel dispatch
 - `EventDurability`, `DurableEventSpec`, `FactExpectation`; `eventIdFor` / `durableEventMeta` (`${name}:v${version}:${occurrence}`); `requireDurableContext` + `NonDurablePublishError`; `UnmanagedSessionError`.

package/dist/bank-transaction.d.mts

@@ -1,4 +1,4 @@
-import { n as Money } from "./money-C9iLWiWR.mjs";
+import { n as Money } from "./money-BGPS_Ena.mjs";
 //#region src/money/bank-transaction.d.ts
 /**
  * The other side of a bank transaction. All fields optional — different

package/dist/currency.d.mts

@@ -1,2 +1,2 @@
-import { A as FxRounding, B as reverseWithSnapshot, D as CURRENCY_PATTERN, E as CURRENCIES, F as currencyCode, I as isCurrencyCode, L as isFxSnapshot, M as InvalidCurrencyCodeError, N as MINOR_UNIT_FACTOR, O as CurrencyCode, P as convertWithSnapshot, R as isKnownCurrency, V as toCurrencyCode, j as FxSnapshot, k as CurrencyMismatchError, z as minorUnitFactor } from "./money-C9iLWiWR.mjs";
+import { A as FxRounding, B as reverseWithSnapshot, D as CURRENCY_PATTERN, E as CURRENCIES, F as currencyCode, I as isCurrencyCode, L as isFxSnapshot, M as InvalidCurrencyCodeError, N as MINOR_UNIT_FACTOR, O as CurrencyCode, P as convertWithSnapshot, R as isKnownCurrency, V as toCurrencyCode, j as FxSnapshot, k as CurrencyMismatchError, z as minorUnitFactor } from "./money-BGPS_Ena.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

@@ -1,3 +1,4 @@
+import { t as roundedDiv } from "./rounded-div-BWJb98Ws.mjs";
 //#region src/money/currency.ts
 /**
 * Common ISO 4217 codes. Non-exhaustive — add more at the consumer level if
@@ -179,6 +180,34 @@ function roundMinor(raw, mode) {
 	if (mode === "ceil") return Math.ceil(raw);
 	return Math.round(Math.abs(raw)) * (raw < 0 ? -1 : 1);
 }
+/** `numerator / denominator` (denominator > 0) landed exactly by `mode`. */
+function divideMinor(numerator, denominator, mode) {
+	if (mode === "half-away-from-zero") return roundedDiv(numerator, denominator, "half-up");
+	const quotient = numerator / denominator;
+	if (numerator % denominator === 0n) return quotient;
+	if (mode === "floor") return numerator < 0n ? quotient - 1n : quotient;
+	return numerator < 0n ? quotient : quotient + 1n;
+}
+const DECIMAL_NUMBER = /^(-?)(\d+)(?:\.(\d+))?(?:e([+-]\d+))?$/;
+/**
+* A finite number as the exact decimal its shortest round-trip string names:
+* `110.15` → `{ int: 11015n, scale: 2 }`, so `110.15` means 110.15, not the
+* binary double nearest to it.
+*/
+function decimalOf(value) {
+	const match = DECIMAL_NUMBER.exec(String(value));
+	if (match === null) throw new TypeError(`Cannot read ${value} as a decimal`);
+	const [, sign, whole, fraction = "", exponent = "0"] = match;
+	const digits = BigInt(`${sign}${whole}${fraction}`);
+	const power = Number(exponent) - fraction.length;
+	return power >= 0 ? {
+		int: digits * 10n ** BigInt(power),
+		scale: 0
+	} : {
+		int: digits,
+		scale: -power
+	};
+}
 /**
 * Apply an {@link FxSnapshot} to a source-currency amount.
 *
@@ -198,12 +227,23 @@ function roundMinor(raw, mode) {
 * (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.
+*
+* ## Exact, rounded once
+*
+* The rate is read as the decimal it prints as and the product is computed in
+* BigInt: `minor × rate × baseFactor / sourceFactor`, rounded once. A float
+* product misses exact half-way points (USD 5.30 × 110.15 = 583.795 BDT
+* computes as 583.79499…), so it rounded to 58379 paisa instead of 58380.
 */
 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}`);
+	if (!Number.isInteger(source.amount)) throw new TypeError(`Money.amount must be an integer in minor units, got ${source.amount}`);
+	const rate = decimalOf(fx.rate);
+	const numerator = BigInt(source.amount) * rate.int * BigInt(minorUnitFactor(fx.baseCurrency));
+	const denominator = BigInt(minorUnitFactor(fx.sourceCurrency)) * 10n ** BigInt(rate.scale);
 	return {
-		amount: roundMinor(source.amount / minorUnitFactor(fx.sourceCurrency) * fx.rate * minorUnitFactor(fx.baseCurrency), options.rounding ?? "half-away-from-zero"),
+		amount: Number(divideMinor(numerator, denominator, options.rounding ?? "half-away-from-zero")),
 		currency: currencyCode(fx.baseCurrency)
 	};
 }

package/dist/item-facts.d.mts

@@ -9,6 +9,8 @@ interface ItemStockSource {
   displayName: string;
   /** The canonical STOCK unit — what quants and moves are balanced in. */
   uom: string;
+  /** The stock unit's UoM group (`_id` or `code`); its base unit is `uom` and its rounding is the posting step. */
+  uomGroupRef?: string | undefined;
   trackingMode: TrackingMode;
   trackingPolicy?: ShelfLifePolicy | undefined;
   /**
@@ -29,6 +31,10 @@ interface ProductFacet {
   sku: string;
   displayName: string;
   uom?: string | undefined;
+  /** Fallback group for a product-only deployment; never read when an Item exists. */
+  uomGroupRef?: string | undefined;
+  /** The product declares a unit of measure, even if its group was lost on the way here. */
+  unitOfMeasureDeclared?: boolean | undefined;
   trackingMode?: TrackingMode | undefined;
   trackingPolicy?: ShelfLifePolicy | undefined;
   catchWeight?: boolean | undefined;
@@ -46,6 +52,14 @@ interface ItemStockFacts {
   trackingMode: TrackingMode;
   trackingPolicy?: ShelfLifePolicy;
   uom: string;
+  /** UoM group whose rounding a posting snaps to. Absent ⇒ the bare quantity grid. */
+  uomGroupRef?: string;
+  /**
+   * A source declared a unit of measure, so a missing `uomGroupRef` must be
+   * REFUSED by the stock engine, never read as "no rounding". Not set by `uom`
+   * alone: every Item has a `uom`.
+   */
+  unitOfMeasureDeclared?: boolean;
   catchWeight?: boolean;
   weightUom?: string;
   weight?: number;
@@ -64,6 +78,11 @@ interface ItemStockFacts {
  * `isActive` follows the ITEM when one exists: a product withdrawn from sale is
  * still stock on a shelf, whereas a retired item is not stockable at all. Taking
  * the product's flag would make unlisting a product silently orphan its stock.
+ *
+ * `uomGroupRef` follows the ITEM when one exists. A product group under an Item
+ * that declares none is never borrowed (its step is in a unit the Item may not
+ * count in): the facts carry `unitOfMeasureDeclared: true` and no group, so the
+ * stock engine refuses the posting until the Item declares its own.
  */
 declare function resolveStockFacts(input: {
   item?: ItemStockSource | null | undefined;

package/dist/item-facts.mjs

@@ -2,6 +2,7 @@
 /** Unit assumed when neither side declares one. A deployment-wide guess, and a bad one — set a real `uom` on the Item. */
 const FALLBACK_UOM = "unit";
 const defined = (key, value) => value === void 0 ? {} : { [key]: value };
+const declaresGroup = (p) => !!p && (p.uomGroupRef !== void 0 || p.unitOfMeasureDeclared === true);
 /**
 * Merge an Item with its Product facet.
 *
@@ -13,6 +14,11 @@ const defined = (key, value) => value === void 0 ? {} : { [key]: value };
 * `isActive` follows the ITEM when one exists: a product withdrawn from sale is
 * still stock on a shelf, whereas a retired item is not stockable at all. Taking
 * the product's flag would make unlisting a product silently orphan its stock.
+*
+* `uomGroupRef` follows the ITEM when one exists. A product group under an Item
+* that declares none is never borrowed (its step is in a unit the Item may not
+* count in): the facts carry `unitOfMeasureDeclared: true` and no group, so the
+* stock engine refuses the posting until the Item declares its own.
 */
 function resolveStockFacts(input) {
 	const { item, product } = input;
@@ -24,6 +30,8 @@ function resolveStockFacts(input) {
 			sku: p.sku,
 			displayName: p.displayName,
 			uom: p.uom ?? FALLBACK_UOM,
+			...defined("uomGroupRef", p.uomGroupRef),
+			...p.unitOfMeasureDeclared === true ? { unitOfMeasureDeclared: true } : {},
 			trackingMode: p.trackingMode ?? "none",
 			...defined("trackingPolicy", p.trackingPolicy),
 			...defined("catchWeight", p.catchWeight),
@@ -39,6 +47,8 @@ function resolveStockFacts(input) {
 		sku: product?.sku ?? item.sku,
 		displayName: product?.displayName ?? item.displayName,
 		uom: item.uom,
+		...defined("uomGroupRef", item.uomGroupRef),
+		...item.uomGroupRef === void 0 && declaresGroup(product) ? { unitOfMeasureDeclared: true } : {},
 		trackingMode: item.trackingMode,
 		...defined("trackingPolicy", item.trackingPolicy),
 		...defined("catchWeight", item.catchWeight),

package/dist/monetization.d.mts

@@ -1,4 +1,4 @@
-import { n as Money } from "./money-C9iLWiWR.mjs";
+import { n as Money } from "./money-BGPS_Ena.mjs";
 //#region src/money/monetization.d.ts
 /**
  * A map of currency code → {@link Money} for explicit per-currency pricing.

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

@@ -172,6 +172,13 @@ type FxRounding = 'half-away-from-zero' | 'floor' | 'ceil';
  * (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.
+ *
+ * ## Exact, rounded once
+ *
+ * The rate is read as the decimal it prints as and the product is computed in
+ * BigInt: `minor × rate × baseFactor / sourceFactor`, rounded once. A float
+ * product misses exact half-way points (USD 5.30 × 110.15 = 583.795 BDT
+ * computes as 583.79499…), so it rounded to 58379 paisa instead of 58380.
  */
 declare function convertWithSnapshot(source: Money, fx: FxSnapshot, options?: {
   rounding?: FxRounding;

package/dist/money.d.mts

@@ -1,2 +1,2 @@
-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";
+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-BGPS_Ena.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/payment-events.d.mts

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

package/dist/payment-gateway.d.mts

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

package/dist/price-basis.d.mts

@@ -8,7 +8,7 @@ type MeasureDimension = 'mass' | 'duration' | 'volume' | 'length' | 'area';
 interface MeasuredPriceBasis {
   readonly kind: 'measured';
   readonly dimension: MeasureDimension;
-  /** Integer unit carried by the line quantity, such as `gram` or `minute`. */
+  /** Unit carried by the line quantity, such as `gram` or `minute`; the quantity may be fractional. */
   readonly quantityUnit: string;
   /** Unit named by the quoted price, such as `kilogram` or `hour`. */
   readonly priceUnit: string;
@@ -25,7 +25,10 @@ declare function fixedPriceBasis(): FixedPriceBasis;
 declare function measuredPriceBasis(dimension: MeasureDimension, quantityUnit: string, priceUnit: string, quantityPerPriceUnit: number): MeasuredPriceBasis;
 /** Structural guard for database and wire boundaries. */
 declare function isPriceBasis(value: unknown): value is PriceBasis;
-/** Extend a minor-unit price using integer quantity and exact half-even rounding. */
+/**
+ * Extend a minor-unit price across a non-negative quantity, exactly, on the 6-dp quantity grid,
+ * rounding once (half-even). A quantity off the grid throws.
+ */
 declare function resolvePriceBasisTotal(unitPriceMinor: number, quantity: number, basis?: PriceBasis): number;
 //#endregion
 export { FixedPriceBasis, MeasureDimension, MeasuredPriceBasis, PriceBasis, PriceBasisError, PriceBasisErrorCode, fixedPriceBasis, isPriceBasis, measuredPriceBasis, resolvePriceBasisTotal };

package/dist/price-basis.mjs

@@ -1,4 +1,5 @@
 import { t as roundedDiv } from "./rounded-div-BWJb98Ws.mjs";
+import { QUANTITY_SCALE, isOnQuantityGrid, quantityToGrid } from "./quantity.mjs";
 //#region src/money/price-basis.ts
 var PriceBasisError = class extends Error {
 	name = "PriceBasisError";
@@ -36,12 +37,17 @@ function isPriceBasis(value) {
 	if (candidate.kind === "fixed") return true;
 	return candidate.kind === "measured" && MEASURE_DIMENSIONS.has(candidate.dimension) && typeof candidate.quantityUnit === "string" && candidate.quantityUnit.trim() !== "" && typeof candidate.priceUnit === "string" && candidate.priceUnit.trim() !== "" && typeof candidate.quantityPerPriceUnit === "number" && Number.isSafeInteger(candidate.quantityPerPriceUnit) && candidate.quantityPerPriceUnit > 0;
 }
-/** Extend a minor-unit price using integer quantity and exact half-even rounding. */
+/**
+* Extend a minor-unit price across a non-negative quantity, exactly, on the 6-dp quantity grid,
+* rounding once (half-even). A quantity off the grid throws.
+*/
 function resolvePriceBasisTotal(unitPriceMinor, quantity, basis = fixedPriceBasis()) {
 	if (!Number.isSafeInteger(unitPriceMinor) || unitPriceMinor < 0) throw new PriceBasisError("INVALID_PRICE", "unitPriceMinor must be a non-negative safe integer");
-	if (!Number.isSafeInteger(quantity) || quantity < 0) throw new PriceBasisError("INVALID_QUANTITY", "quantity must be a non-negative safe integer");
-	const numerator = BigInt(unitPriceMinor) * BigInt(quantity);
-	const denominator = basis.kind === "measured" ? BigInt(basis.quantityPerPriceUnit) : 1n;
+	if (!(quantity >= 0) || !(Number.isSafeInteger(quantity) || isOnQuantityGrid(quantity))) throw new PriceBasisError("INVALID_QUANTITY", `quantity ${quantity} must be a non-negative integer, or a fraction on the 1/${QUANTITY_SCALE} grid`);
+	const whole = Number.isSafeInteger(quantity);
+	const perPriceUnit = basis.kind === "measured" ? BigInt(basis.quantityPerPriceUnit) : 1n;
+	const numerator = BigInt(unitPriceMinor) * (whole ? BigInt(quantity) : quantityToGrid(quantity));
+	const denominator = whole ? perPriceUnit : perPriceUnit * BigInt(QUANTITY_SCALE);
 	const rounded = roundedDiv(numerator, denominator, "half-even");
 	const total = Number(rounded);
 	if (!Number.isSafeInteger(total)) throw new PriceBasisError("UNSAFE_TOTAL", "resolved total exceeds Number.MAX_SAFE_INTEGER");

package/dist/proration.d.mts

@@ -1,4 +1,4 @@
-import { n as Money } from "./money-C9iLWiWR.mjs";
+import { n as Money } from "./money-BGPS_Ena.mjs";
 //#region src/money/proration.d.ts
 /**
  * How to count days within a period.

package/dist/quantity.d.mts

@@ -0,0 +1,38 @@
+import { t as RoundingMode } from "./rounded-div-D7lyJXt8.mjs";
+//#region src/inventory/quantity.d.ts
+/**
+ * Grid units per stock unit. Equal to `unit-cost-rate`'s internal `QTY_SCALE`;
+ * `tests/unit/quantity.test.ts` pins the equality through `extendedAmount`.
+ */
+declare const QUANTITY_SCALE = 1000000;
+type QuantityErrorCode = 'NOT_FINITE' | 'INVALID_STEP' | 'UNSAFE_QUANTITY';
+declare class QuantityError extends Error {
+  readonly name = "QuantityError";
+  readonly code: QuantityErrorCode;
+  constructor(code: QuantityErrorCode, message: string);
+}
+/** A quantity as a signed integer count of grid units (sign-symmetric half-even). */
+declare function quantityToGrid(quantity: number): bigint;
+/** The step in grid units. Refuses a non-positive step, one finer than the grid, or one off it. */
+declare function quantityStepToGrid(step: number): bigint;
+/**
+ * Round `quantity` to the nearest multiple of `step` (default: the bare grid).
+ *
+ * @example snapQuantity(10 - 2.35 - 2.35, 0.001) // 5.3
+ * @example snapQuantity(2.3505, 0.001)           // 2.35 (half-even)
+ */
+declare function snapQuantity(quantity: number, step?: number, mode?: RoundingMode): number;
+/**
+ * Does `value` lie ON the grid (within float noise)? Strict, unlike {@link isOnStep}, which snaps
+ * first: `2.3500004` is off the grid here and on the 0.001 step there. Check this at an input
+ * boundary, where a 7th decimal is a caller error rather than float drift.
+ */
+declare function isOnQuantityGrid(value: number): boolean;
+/** Is `quantity` a whole multiple of `step`, within half a grid unit? */
+declare function isOnStep(quantity: number, step: number): boolean;
+/** Compare two quantities on the grid: equal when they snap to the same grid unit. */
+declare function compareQuantity(a: number, b: number): -1 | 0 | 1;
+/** `compareQuantity(a, b) === 0`. */
+declare function quantitiesEqual(a: number, b: number): boolean;
+//#endregion
+export { QUANTITY_SCALE, QuantityError, QuantityErrorCode, type RoundingMode, compareQuantity, isOnQuantityGrid, isOnStep, quantitiesEqual, quantityStepToGrid, quantityToGrid, snapQuantity };

package/dist/quantity.mjs

@@ -0,0 +1,88 @@
+import { t as roundedDiv } from "./rounded-div-BWJb98Ws.mjs";
+//#region src/inventory/quantity.ts
+/**
+* A decimal stock quantity snapped to its unit's rounding step, on the fixed
+* {@link QUANTITY_SCALE} grid (6 dp — the grid `unit-cost-rate` extends money on).
+*
+* Snap at every write boundary: `10 - 2.35 - 2.35` is `5.300000000000001` in
+* IEEE doubles, and a stored drift never comes back out.
+*
+* Rounding is half-even, the package's money mode: a quantity snap is a
+* per-event normalisation, and half-up biases a running stock balance upward
+* across thousands of weighings.
+*/
+/**
+* Grid units per stock unit. Equal to `unit-cost-rate`'s internal `QTY_SCALE`;
+* `tests/unit/quantity.test.ts` pins the equality through `extendedAmount`.
+*/
+const QUANTITY_SCALE = 1e6;
+var QuantityError = class extends Error {
+	name = "QuantityError";
+	code;
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+	}
+};
+/** A quantity as a signed integer count of grid units (sign-symmetric half-even). */
+function quantityToGrid(quantity) {
+	if (!Number.isFinite(quantity)) throw new QuantityError("NOT_FINITE", `quantity must be finite, got ${quantity}`);
+	const scaled = Math.abs(quantity) * QUANTITY_SCALE;
+	if (!Number.isSafeInteger(Math.ceil(scaled))) throw new QuantityError("UNSAFE_QUANTITY", `quantity ${quantity} exceeds the precise grid range`);
+	const floor = Math.floor(scaled);
+	const frac = scaled - floor;
+	const up = frac > .5 || frac === .5 && floor % 2 === 1;
+	const magnitude = BigInt(up ? floor + 1 : floor);
+	return quantity < 0 ? -magnitude : magnitude;
+}
+function gridToNumber(grid) {
+	const value = Number(grid) / QUANTITY_SCALE;
+	return value === 0 ? 0 : value;
+}
+/** The step in grid units. Refuses a non-positive step, one finer than the grid, or one off it. */
+function quantityStepToGrid(step) {
+	if (!Number.isFinite(step) || step <= 0) throw new QuantityError("INVALID_STEP", `rounding step must be a positive number, got ${step}`);
+	const grid = quantityToGrid(step);
+	const scaled = step * QUANTITY_SCALE;
+	if (grid === 0n || Math.abs(Number(grid) - scaled) > 1e-9 * Math.max(1, scaled)) throw new QuantityError("INVALID_STEP", `rounding step ${step} is not a multiple of 1/${QUANTITY_SCALE}`);
+	return grid;
+}
+/**
+* Round `quantity` to the nearest multiple of `step` (default: the bare grid).
+*
+* @example snapQuantity(10 - 2.35 - 2.35, 0.001) // 5.3
+* @example snapQuantity(2.3505, 0.001)           // 2.35 (half-even)
+*/
+function snapQuantity(quantity, step, mode = "half-even") {
+	const grid = quantityToGrid(quantity);
+	if (step === void 0) return gridToNumber(grid);
+	const stepGrid = quantityStepToGrid(step);
+	return gridToNumber(roundedDiv(grid, stepGrid, mode) * stepGrid);
+}
+/**
+* Does `value` lie ON the grid (within float noise)? Strict, unlike {@link isOnStep}, which snaps
+* first: `2.3500004` is off the grid here and on the 0.001 step there. Check this at an input
+* boundary, where a 7th decimal is a caller error rather than float drift.
+*/
+function isOnQuantityGrid(value) {
+	if (!Number.isFinite(value)) return false;
+	const scaled = value * QUANTITY_SCALE;
+	const grid = Math.round(scaled);
+	return Number.isSafeInteger(grid) && Math.abs(grid - scaled) <= 1e-9 * Math.max(1, Math.abs(scaled));
+}
+/** Is `quantity` a whole multiple of `step`, within half a grid unit? */
+function isOnStep(quantity, step) {
+	return quantityToGrid(quantity) % quantityStepToGrid(step) === 0n;
+}
+/** Compare two quantities on the grid: equal when they snap to the same grid unit. */
+function compareQuantity(a, b) {
+	const ga = quantityToGrid(a);
+	const gb = quantityToGrid(b);
+	return ga === gb ? 0 : ga < gb ? -1 : 1;
+}
+/** `compareQuantity(a, b) === 0`. */
+function quantitiesEqual(a, b) {
+	return compareQuantity(a, b) === 0;
+}
+//#endregion
+export { QUANTITY_SCALE, QuantityError, compareQuantity, isOnQuantityGrid, isOnStep, quantitiesEqual, quantityStepToGrid, quantityToGrid, snapQuantity };

package/dist/rounded-div-D7lyJXt8.d.mts

@@ -0,0 +1,4 @@
+//#region src/money/rounded-div.d.ts
+type RoundingMode = 'half-even' | 'half-up';
+//#endregion
+export { RoundingMode as t };

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

@@ -1,7 +1,5 @@
-import { O as CurrencyCode, t as MinorUnits } from "./money-C9iLWiWR.mjs";
-//#region src/money/rounded-div.d.ts
-type RoundingMode = 'half-even' | 'half-up';
-//#endregion
+import { O as CurrencyCode, t as MinorUnits } from "./money-BGPS_Ena.mjs";
+import { t as RoundingMode } from "./rounded-div-D7lyJXt8.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;

package/dist/unit-cost-rate.mjs

@@ -1,5 +1,5 @@
-import { t as MinorUnits } from "./money-BBOARE5f.mjs";
 import { t as roundedDiv } from "./rounded-div-BWJb98Ws.mjs";
+import { t as MinorUnits } from "./money-BBOARE5f.mjs";
 //#region src/money/unit-cost-rate.ts
 /** Fixed, ecosystem-wide rate scale: 6 decimal places below the minor unit. */
 const RATE_SCALE = 1e6;

package/dist/usage-pricing.d.mts

@@ -0,0 +1,53 @@
+import { n as Money } from "./money-BGPS_Ena.mjs";
+import { UsageRating } from "./monetization.mjs";
+//#region src/money/usage-pricing.d.ts
+/** What ONE unit of a sale line measured: `{ value: 2.3, unit: 'kg' }`. `unit` must equal the rating's `unitLabel`. */
+interface UsageMeasure {
+  readonly value: number;
+  readonly unit: string;
+}
+/** Structural guard for wire and database boundaries: a positive finite value and a non-blank unit. */
+declare function isUsageMeasure(value: unknown): value is UsageMeasure;
+type UsagePricingErrorCode = 'INVALID_MEASURE' | 'INVALID_INCLUDED_UNITS' | 'UNKNOWN_SCHEME' | 'MISSING_PER_UNIT' | 'MISSING_TIERS' | 'INVALID_TIER' | 'MISSING_PACKAGE' | 'INVALID_MONEY' | 'CURRENCY_MISMATCH' | 'EXCEEDS_RATE_TABLE' | 'UNSAFE_TOTAL';
+declare class UsagePricingError extends Error {
+  readonly name = "UsagePricingError";
+  readonly code: UsagePricingErrorCode;
+  constructor(code: UsagePricingErrorCode, message: string);
+}
+/** One priced line of the breakdown. All money fields are integer minor units. */
+interface UsageChargeLine {
+  /** Index into `rating.tiers` for `tiered` / `volume`; `null` for `per_unit` / `package`. */
+  readonly band: number | null;
+  /** Units priced on this line — PACKAGES under the `package` scheme. */
+  readonly quantity: number;
+  /** Rate applied per `quantity` (0 when the band is flat-only). */
+  readonly unitAmount: number;
+  /** Flat charge for landing in the band (0 when none). */
+  readonly flatAmount: number;
+  /** `quantity × unitAmount + flatAmount`. */
+  readonly amount: number;
+}
+/** The priced result and the facts that produced it — freeze this beside the price. */
+interface UsageCharge {
+  readonly scheme: UsageRating['scheme'];
+  readonly measured: number;
+  readonly includedUnits: number;
+  /** Whole units charged after `includedUnits`, rounded up. */
+  readonly billableUnits: number;
+  /** Packages charged — present only under the `package` scheme. */
+  readonly packages?: number;
+  readonly lines: readonly UsageChargeLine[];
+  readonly amount: Money;
+  readonly unitLabel?: string;
+}
+/**
+ * Price `measured` units against `rating`.
+ *
+ * `tiered` (graduated) charges each band for the units that fall inside it, plus the band's
+ * `flatPrice` when any unit lands there. `volume` charges ALL units at the band the total lands
+ * in. A bounded final band refuses a larger amount (`EXCEEDS_RATE_TABLE`) — a courier that does
+ * not carry 40 kg parcels says so, it does not quote them at the last rate.
+ */
+declare function priceUsage(rating: UsageRating, measured: number): UsageCharge;
+//#endregion
+export { UsageCharge, UsageChargeLine, UsageMeasure, UsagePricingError, UsagePricingErrorCode, isUsageMeasure, priceUsage };

package/dist/usage-pricing.mjs

@@ -0,0 +1,150 @@
+//#region src/money/usage-pricing.ts
+/** Structural guard for wire and database boundaries: a positive finite value and a non-blank unit. */
+function isUsageMeasure(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const candidate = value;
+	return typeof candidate.value === "number" && Number.isFinite(candidate.value) && candidate.value > 0 && typeof candidate.unit === "string" && candidate.unit.trim() !== "";
+}
+var UsagePricingError = class extends Error {
+	name = "UsagePricingError";
+	code;
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+	}
+};
+/**
+* Price `measured` units against `rating`.
+*
+* `tiered` (graduated) charges each band for the units that fall inside it, plus the band's
+* `flatPrice` when any unit lands there. `volume` charges ALL units at the band the total lands
+* in. A bounded final band refuses a larger amount (`EXCEEDS_RATE_TABLE`) — a courier that does
+* not carry 40 kg parcels says so, it does not quote them at the last rate.
+*/
+function priceUsage(rating, measured) {
+	if (typeof measured !== "number" || !Number.isFinite(measured) || measured < 0) throw new UsagePricingError("INVALID_MEASURE", `measured must be a finite number >= 0, got ${String(measured)}`);
+	const includedUnits = rating.includedUnits ?? 0;
+	if (typeof includedUnits !== "number" || !Number.isFinite(includedUnits) || includedUnits < 0) throw new UsagePricingError("INVALID_INCLUDED_UNITS", `includedUnits must be a finite number >= 0, got ${String(includedUnits)}`);
+	const over = Number((measured - includedUnits).toPrecision(12));
+	const billableUnits = over > 0 ? Math.ceil(over) : 0;
+	const base = {
+		scheme: rating.scheme,
+		measured,
+		includedUnits,
+		billableUnits,
+		...rating.unitLabel !== void 0 ? { unitLabel: rating.unitLabel } : {}
+	};
+	switch (rating.scheme) {
+		case "per_unit": {
+			const rate = requireMoney(rating.perUnit, "MISSING_PER_UNIT", "per_unit needs perUnit");
+			const lines = billableUnits > 0 ? [line(null, billableUnits, rate.amount, 0)] : [];
+			return {
+				...base,
+				lines,
+				amount: total(lines, rate.currency)
+			};
+		}
+		case "package": {
+			if (!Number.isSafeInteger(rating.packageSize) || (rating.packageSize ?? 0) <= 0) throw new UsagePricingError("MISSING_PACKAGE", "package needs packageSize as a positive integer");
+			const price = requireMoney(rating.packagePrice, "MISSING_PACKAGE", "package needs packagePrice");
+			const packages = Math.ceil(billableUnits / rating.packageSize);
+			const lines = packages > 0 ? [line(null, packages, price.amount, 0)] : [];
+			return {
+				...base,
+				packages,
+				lines,
+				amount: total(lines, price.currency)
+			};
+		}
+		case "tiered":
+		case "volume": {
+			const { tiers, currency } = validTiers(rating.tiers);
+			const lines = rating.scheme === "tiered" ? graduated(tiers, billableUnits) : volume(tiers, billableUnits);
+			return {
+				...base,
+				lines,
+				amount: total(lines, currency)
+			};
+		}
+		default: {
+			const unknownScheme = rating.scheme;
+			throw new UsagePricingError("UNKNOWN_SCHEME", `unknown usage scheme: ${String(unknownScheme)}`);
+		}
+	}
+}
+function requireMoney(value, code, message) {
+	if (!value) throw new UsagePricingError(code, message);
+	assertMoney(value);
+	return value;
+}
+function assertMoney(value) {
+	if (!Number.isSafeInteger(value.amount) || value.amount < 0 || typeof value.currency !== "string") throw new UsagePricingError("INVALID_MONEY", `a rate must be a non-negative integer minor amount with a currency, got ${JSON.stringify(value)}`);
+}
+function validTiers(tiers) {
+	if (!Array.isArray(tiers) || tiers.length === 0) throw new UsagePricingError("MISSING_TIERS", "tiered and volume schemes need at least one tier");
+	let currency;
+	let previous = 0;
+	tiers.forEach((tier, i) => {
+		if (tier.perUnit === void 0 && tier.flatPrice === void 0) throw new UsagePricingError("INVALID_TIER", `tier ${i} has neither perUnit nor flatPrice`);
+		for (const money of [tier.perUnit, tier.flatPrice]) {
+			if (money === void 0) continue;
+			assertMoney(money);
+			if (currency === void 0) currency = money.currency;
+			else if (money.currency !== currency) throw new UsagePricingError("CURRENCY_MISMATCH", `tier ${i} is in ${money.currency}, the table in ${currency}`);
+		}
+		if (tier.upTo === void 0) {
+			if (i !== tiers.length - 1) throw new UsagePricingError("INVALID_TIER", `tier ${i} is open-ended but is not the last tier`);
+			return;
+		}
+		if (!Number.isSafeInteger(tier.upTo) || tier.upTo <= previous) throw new UsagePricingError("INVALID_TIER", `tier ${i} upTo must be an integer above the previous bound ${previous}, got ${String(tier.upTo)}`);
+		previous = tier.upTo;
+	});
+	return {
+		tiers,
+		currency
+	};
+}
+function graduated(tiers, units) {
+	const lines = [];
+	let floor = 0;
+	for (let i = 0; i < tiers.length && floor < units; i++) {
+		const tier = tiers[i];
+		const ceiling = tier.upTo ?? Number.POSITIVE_INFINITY;
+		const inBand = Math.min(units, ceiling) - floor;
+		lines.push(line(i, inBand, tier.perUnit?.amount ?? 0, tier.flatPrice?.amount ?? 0));
+		floor = ceiling;
+	}
+	if (floor < units) throw exceeds(units, floor);
+	return lines;
+}
+function volume(tiers, units) {
+	if (units === 0) return [];
+	const band = tiers.findIndex((tier) => tier.upTo === void 0 || units <= tier.upTo);
+	if (band === -1) throw exceeds(units, tiers[tiers.length - 1]?.upTo ?? 0);
+	const tier = tiers[band];
+	return [line(band, units, tier.perUnit?.amount ?? 0, tier.flatPrice?.amount ?? 0)];
+}
+function exceeds(units, limit) {
+	return new UsagePricingError("EXCEEDS_RATE_TABLE", `${units} units exceed the rate table's last bound ${limit}`);
+}
+function line(band, quantity, unitAmount, flatAmount) {
+	const amount = quantity * unitAmount + flatAmount;
+	if (!Number.isSafeInteger(amount)) throw new UsagePricingError("UNSAFE_TOTAL", "usage charge exceeds Number.MAX_SAFE_INTEGER");
+	return {
+		band,
+		quantity,
+		unitAmount,
+		flatAmount,
+		amount
+	};
+}
+function total(lines, currency) {
+	const amount = lines.reduce((sum, l) => sum + l.amount, 0);
+	if (!Number.isSafeInteger(amount)) throw new UsagePricingError("UNSAFE_TOTAL", "usage charge exceeds Number.MAX_SAFE_INTEGER");
+	return {
+		amount,
+		currency
+	};
+}
+//#endregion
+export { UsagePricingError, isUsageMeasure, priceUsage };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/primitives",
-  "version": "0.30.0",
+  "version": "0.31.1",
   "description": "Framework-agnostic TypeScript primitives shared across Classytic packages — Money, events, pagination, tenant config, and other building blocks.",
   "author": "Classytic",
   "license": "MIT",
@@ -297,6 +297,16 @@
       "types": "./dist/signed-token.d.mts",
       "default": "./dist/signed-token.mjs"
     },
+    "./quantity": {
+      "@classytic/source": "./src/inventory/quantity.ts",
+      "types": "./dist/quantity.d.mts",
+      "default": "./dist/quantity.mjs"
+    },
+    "./usage-pricing": {
+      "@classytic/source": "./src/money/usage-pricing.ts",
+      "types": "./dist/usage-pricing.d.mts",
+      "default": "./dist/usage-pricing.mjs"
+    },
     "./item-stock": {
       "@classytic/source": "./src/inventory/item-stock.ts",
       "types": "./dist/item-stock.d.mts",