@classytic/primitives 0.29.0 → 0.31.0

package/dist/outbox.d.mts

@@ -141,6 +141,23 @@ declare class OutboxOwnershipError extends Error {
   readonly currentOwner: string | null;
   constructor(eventId: string, attemptedBy: string, currentOwner: string | null);
 }
+/**
+ * Thrown by `save` when a row with this event id already exists with a DIFFERENT payload.
+ * A same-id, same-payload save is an idempotent success; a different payload is two
+ * occurrences minted onto one id, and dropping either one loses money silently.
+ */
+declare class OutboxConflictError extends Error {
+  readonly name = "OutboxConflictError";
+  readonly code = "outbox.conflict";
+  readonly eventId: string;
+  readonly eventType: string;
+  constructor(eventId: string, eventType: string);
+}
+/**
+ * Order-independent fingerprint of an event payload as it travels (JSON: `Date` becomes its
+ * ISO string, `undefined` drops). Stores compare it on a duplicate id; see {@link OutboxConflictError}.
+ */
+declare function outboxPayloadFingerprint(event: DomainEvent): string;
 /** Thrown when an event missing `type` or `meta.id` is passed to the outbox. */
 declare class InvalidOutboxEventError extends Error {
   readonly name = "InvalidOutboxEventError";
@@ -235,7 +252,8 @@ interface OutboxStore {
   /**
    * Save an event to the outbox (typically called inside a business
    * transaction). MUST reject events missing `type` or `meta.id` — throw
-   * rather than persist.
+   * rather than persist. A second save of an existing `meta.id` is a no-op when
+   * the payload matches, and throws {@link OutboxConflictError} when it does not.
    */
   save(event: DomainEvent, options?: OutboxWriteOptions): Promise<void>;
   /**
@@ -267,6 +285,12 @@ interface OutboxStore {
    * @throws {@link OutboxOwnershipError} on ownership mismatch
    */
   acknowledge(eventId: string, options?: OutboxAcknowledgeOptions): Promise<void>;
+  /**
+   * Mark every listed event delivered in ONE write — what a unit of work's post-commit flush
+   * calls, so N delivered events cost one command, not N. Unleased rows only (no fencing);
+   * unknown or already-delivered ids are ignored.
+   */
+  acknowledgeMany?(eventIds: readonly string[]): Promise<void>;
   /**
    * Record a relay failure. When implemented, the relay calls this instead
    * of stopping the batch — enables retry scheduling and DLQ.
@@ -335,4 +359,4 @@ interface OutboxStore {
   oldestPendingAgeMs?(): Promise<number | null>;
 }
 //#endregion
-export { InvalidOutboxEventError, OUTBOX_STATUSES, OutboxAcknowledgeOptions, OutboxClaimOptions, OutboxClaimedEvent, OutboxErrorInfo, OutboxFailOptions, OutboxFailureContext, OutboxFailureDecision, OutboxFailurePolicy, OutboxOwnershipError, OutboxStatus, OutboxStore, OutboxWriteOptions };
+export { InvalidOutboxEventError, OUTBOX_STATUSES, OutboxAcknowledgeOptions, OutboxClaimOptions, OutboxClaimedEvent, OutboxConflictError, OutboxErrorInfo, OutboxFailOptions, OutboxFailureContext, OutboxFailureDecision, OutboxFailurePolicy, OutboxOwnershipError, OutboxStatus, OutboxStore, OutboxWriteOptions, outboxPayloadFingerprint };

package/dist/outbox.mjs

@@ -1,5 +1,23 @@
+import { canonicalDigest } from "./canonical.mjs";
 //#region src/events/outbox.ts
 /**
+* Transactional outbox CONTRACT — the canonical owner. `@classytic/arc`
+* re-exports this; it keeps no copy of its own.
+*
+* Contract surface only: {@link OutboxStore}, its option types, the
+* {@link OutboxFailurePolicy} retry/DLQ contract, and the error classes.
+*
+* The split exists because a domain package MUST NOT peer-dep arc. Owning the
+* contract here lets a package write `implements OutboxStore` and hand the
+* result to arc's `new EventOutbox({ store })`, and since arc re-exports these
+* exact classes, `instanceof OutboxOwnershipError` works across the boundary.
+*
+* Runtimes live elsewhere: the DURABLE one (`EventOutbox` relay, Mongo store,
+* backoff, Fastify wiring) in `@classytic/arc/events`; the dependency-free
+* in-process reference (kernel bus + memory store, for tests/dev) in
+* `@classytic/primitives/event-infra`.
+*/
+/**
 * Thrown by a store when `acknowledge` / `fail` is called by a consumer that
 * does not own the event's current lease.
 *
@@ -19,6 +37,30 @@ var OutboxOwnershipError = class extends Error {
 		this.currentOwner = currentOwner;
 	}
 };
+/**
+* Thrown by `save` when a row with this event id already exists with a DIFFERENT payload.
+* A same-id, same-payload save is an idempotent success; a different payload is two
+* occurrences minted onto one id, and dropping either one loses money silently.
+*/
+var OutboxConflictError = class extends Error {
+	name = "OutboxConflictError";
+	code = "outbox.conflict";
+	eventId;
+	eventType;
+	constructor(eventId, eventType) {
+		super(`Outbox already holds event "${eventId}" (${eventType}) with a different payload — two occurrences share one id. Derive the occurrence from the aggregate id plus the step.`);
+		this.eventId = eventId;
+		this.eventType = eventType;
+	}
+};
+/**
+* Order-independent fingerprint of an event payload as it travels (JSON: `Date` becomes its
+* ISO string, `undefined` drops). Stores compare it on a duplicate id; see {@link OutboxConflictError}.
+*/
+function outboxPayloadFingerprint(event) {
+	const wire = JSON.parse(JSON.stringify(event.payload ?? null));
+	return canonicalDigest(wire);
+}
 /** Thrown when an event missing `type` or `meta.id` is passed to the outbox. */
 var InvalidOutboxEventError = class extends Error {
 	name = "InvalidOutboxEventError";
@@ -90,4 +132,4 @@ const OUTBOX_STATUSES = [
 	"dead_letter"
 ];
 //#endregion
-export { InvalidOutboxEventError, OUTBOX_STATUSES, OutboxOwnershipError };
+export { InvalidOutboxEventError, OUTBOX_STATUSES, OutboxConflictError, OutboxOwnershipError, outboxPayloadFingerprint };

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/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/split-allocation.d.mts

@@ -60,7 +60,7 @@ interface SplitResult {
   readonly method: SplitMethod;
   readonly parts: readonly SplitPart[];
 }
-type SplitAllocationErrorCode = 'INVALID_TOTAL' | 'EMPTY_SUBJECTS' | 'INVALID_WEIGHT' | 'INVALID_PERCENT' | 'ZERO_WEIGHT_SUM' | 'DUPLICATE_SUBJECT_ID';
+type SplitAllocationErrorCode = 'INVALID_TOTAL' | 'EMPTY_SUBJECTS' | 'INVALID_WEIGHT' | 'INVALID_PERCENT' | 'ZERO_WEIGHT_SUM' | 'DUPLICATE_SUBJECT_ID' | 'DISCOUNT_EXCEEDS_BASE';
 declare class SplitAllocationError extends Error {
   readonly name = "SplitAllocationError";
   readonly code: SplitAllocationErrorCode;
@@ -80,5 +80,23 @@ declare class SplitAllocationError extends Error {
 declare function allocate(total: number, subjects: readonly SplitSubject[], method: SplitMethod): SplitResult;
 /** True if `sum(parts[i].amount) === result.total`. Useful as an assertion in host code. */
 declare function isBalanced(result: SplitResult): boolean;
+/** A line a document-level discount may be spread over. */
+interface DiscountSubject {
+  readonly id: string;
+  /** The line's value before the discount, integer minor units (non-negative). */
+  readonly weight: number;
+  /** `false` for a line the discount was never computed on (a delivery charge, an auto-added fee). Absent ⇒ eligible. */
+  readonly discountable?: boolean;
+}
+/**
+ * THE discount allocation: spread a document-level discount over its eligible lines, by value,
+ * exact largest remainder. Every document that splits one discount — the order, its invoice,
+ * its credit notes, a return's value — calls this, so they agree to the minor unit.
+ *
+ * Returns a FULL map in input order: every subject id, `0` for an ineligible or zero-weight one.
+ * `0` discount allocates zeros; a discount equal to the eligible base allocates all of it; a
+ * discount above it throws `DISCOUNT_EXCEEDS_BASE` — the figures disagree.
+ */
+declare function allocateDiscount(discount: number, subjects: readonly DiscountSubject[]): ReadonlyMap<string, number>;
 //#endregion
-export { SplitAllocationError, SplitAllocationErrorCode, SplitMethod, SplitPart, SplitResult, SplitSubject, allocate, isBalanced };
+export { DiscountSubject, SplitAllocationError, SplitAllocationErrorCode, SplitMethod, SplitPart, SplitResult, SplitSubject, allocate, allocateDiscount, isBalanced };

package/dist/split-allocation.mjs

@@ -88,6 +88,7 @@ function resolveWeights(subjects, method) {
 function distribute(total, weights) {
 	const weightSum = weights.reduce((a, b) => a + b, 0);
 	if (weightSum === 0) return weights.map(() => 0);
+	if (weights.every(Number.isSafeInteger) && Number.isSafeInteger(weightSum)) return distributeExact(total, weights, weightSum);
 	const raw = weights.map((w) => total * w / weightSum);
 	const floored = raw.map((r) => Math.floor(r));
 	const residue = total - floored.reduce((a, b) => a + b, 0);
@@ -107,9 +108,64 @@ function distribute(total, weights) {
 	}
 	return result;
 }
+/**
+* Largest remainder in exact integer arithmetic, for integer weights (minor-unit amounts). Shares
+* and remainders are compared as BigInt quotients of one denominator, so neither the floor nor the
+* remainder ranking can drift once `total × weight` passes 2^53.
+*/
+function distributeExact(total, weights, weightSum) {
+	const t = BigInt(total);
+	const d = BigInt(weightSum);
+	const shares = weights.map((w) => {
+		const n = t * BigInt(w);
+		return {
+			floor: n / d,
+			rem: n % d
+		};
+	});
+	const result = shares.map((s) => Number(s.floor));
+	const residue = total - result.reduce((a, b) => a + b, 0);
+	const order = shares.map((s, i) => ({
+		i,
+		rem: s.rem
+	})).sort((a, b) => a.rem === b.rem ? a.i - b.i : a.rem > b.rem ? -1 : 1);
+	for (let k = 0; k < residue; k++) {
+		const entry = order[k];
+		if (entry === void 0) throw new Error("split-allocation invariant: residue exceeds the subject count");
+		result[entry.i] = (result[entry.i] ?? 0) + 1;
+	}
+	return result;
+}
 /** True if `sum(parts[i].amount) === result.total`. Useful as an assertion in host code. */
 function isBalanced(result) {
 	return result.parts.reduce((acc, p) => acc + p.amount, 0) === result.total;
 }
+/**
+* THE discount allocation: spread a document-level discount over its eligible lines, by value,
+* exact largest remainder. Every document that splits one discount — the order, its invoice,
+* its credit notes, a return's value — calls this, so they agree to the minor unit.
+*
+* Returns a FULL map in input order: every subject id, `0` for an ineligible or zero-weight one.
+* `0` discount allocates zeros; a discount equal to the eligible base allocates all of it; a
+* discount above it throws `DISCOUNT_EXCEEDS_BASE` — the figures disagree.
+*/
+function allocateDiscount(discount, subjects) {
+	if (!Number.isInteger(discount) || discount < 0) throw new SplitAllocationError("INVALID_TOTAL", `discount must be a non-negative integer, got ${discount}`);
+	const out = /* @__PURE__ */ new Map();
+	for (const s of subjects) {
+		if (out.has(s.id)) throw new SplitAllocationError("DUPLICATE_SUBJECT_ID", `duplicate subject id: ${s.id}`);
+		if (!Number.isFinite(s.weight) || s.weight < 0) throw new SplitAllocationError("INVALID_WEIGHT", `subject ${s.id}: weight must be a non-negative number`);
+		out.set(s.id, 0);
+	}
+	const eligible = subjects.filter((s) => s.discountable !== false && s.weight > 0);
+	const base = eligible.reduce((sum, s) => sum + s.weight, 0);
+	if (discount > base) throw new SplitAllocationError("DISCOUNT_EXCEEDS_BASE", `discount ${discount} exceeds the discountable base ${base}`);
+	if (discount === 0) return out;
+	for (const part of allocate(discount, eligible.map((s) => ({
+		id: s.id,
+		weight: s.weight
+	})), "by-value").parts) out.set(part.id, part.amount);
+	return out;
+}
 //#endregion
-export { SplitAllocationError, allocate, isBalanced };
+export { SplitAllocationError, allocate, allocateDiscount, isBalanced };

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 { 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/usage-pricing.d.mts

@@ -0,0 +1,53 @@
+import { n as Money } from "./money-C9iLWiWR.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.29.0",
+  "version": "0.31.0",
   "description": "Framework-agnostic TypeScript primitives shared across Classytic packages — Money, events, pagination, tenant config, and other building blocks.",
   "author": "Classytic",
   "license": "MIT",
@@ -96,6 +96,11 @@
       "types": "./dist/memory-outbox.d.mts",
       "default": "./dist/memory-outbox.mjs"
     },
+    "./durable-events": {
+      "@classytic/source": "./src/events/durable.ts",
+      "types": "./dist/durable-events.d.mts",
+      "default": "./dist/durable-events.mjs"
+    },
     "./event-infra": {
       "@classytic/source": "./src/events/event-infra.ts",
       "types": "./dist/event-infra.d.mts",
@@ -292,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",