@classytic/primitives 0.11.0 → 0.14.0

package/CHANGELOG.md

@@ -3,6 +3,123 @@
 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.14.0] - 2026-07-23
+
+### Added — `/money`: scalar minor-unit helpers (ledger dialect)
+
+- **`majorToMinorUnits(major, minorUnitDecimals = 2)` /
+  `minorUnitsToMajor(minor, minorUnitDecimals = 2)` /
+  `percentOfMinor(minor, ratePercent)` / `formatMinorUnits(minor,
+  minorUnitDecimals = 2)`** — the currency-neutral, exponent-based scalar
+  dialect used by the double-entry ledger family, extracted from
+  `@classytic/ledger/money` (`fromDecimal`/`toDecimal`/`percentage`/
+  `formatPlain`) so the math has ONE owner (PACKAGE_RULES §8.2).
+  Deliberately different rounding from `fromMajor`: raw IEEE `Math.round`
+  (half-up toward +∞, no `toPrecision` cleaning) — the ledger's
+  characterization-tested wire behavior (`majorToMinorUnits(1.005) === 100`
+  where `fromMajor(1.005,'USD').amount === 101`; `-10.5 → -10`).
+  `percentOfMinor` is the EXACT multiply-then-round form (handles QST
+  9.975 % without bps loss); hosts that snap rates to basis points (be-prod
+  `#shared/money`) layer that policy on top before calling.
+
+### Added — `/event-infra`: shared in-process bus + memory outbox
+
+- **`@classytic/primitives/event-infra`** — the dependency-free reference
+  event RUNTIME every kernel previously copy-pasted (26 drifted
+  `in-process-bus.ts` copies + 15 `outbox-store.ts` copies across
+  `commerce/packages/`, ≈1,600 lines). New subpath (not `/events` or
+  `/outbox`, which stay contract-only per the settled ownership rule; arc
+  keeps the DURABLE runtime — relay, `MongoOutboxStore`, backoff). Exports:
+  - `InProcessEventBus` (+ `createInProcessBus`, `InProcessEventBusOptions`,
+    `ErrorLogger`) — in-process fan-out `EventTransport`, structurally
+    identical to arc's `MemoryEventTransport`. Union of all kernel variants:
+    glob matching via `matchEventPattern`, Set-dedup across patterns,
+    per-handler error isolation with injectable logger (`logger: null` =
+    silent swallow, the cart dialect), `publishMany`, idempotent `close()`.
+    Options: `name` (`'in-process-<kernel>'`), `logLabel` for the error line.
+  - `MemoryOutboxStore` — the test/dev outbox (`save`/`getPending`/
+    `acknowledge`/`purge` + `all()`/`clear()` inspection helpers). Kernels
+    re-export it; production durability stays host-wired.
+  - Kernels keep their public class names as thin subclasses
+    (`class InProcessPosBus extends InProcessEventBus`), so no kernel API
+    changes — the bus swap is internal.
+
+### Added — `/events`: standard context→meta mapping
+
+- **`scopedEventMeta(ctx)` + `createScopedEvent(source, type, payload, ctx?,
+  meta?)` + `EventScopeContext`** — THE context→meta mapping (PACKAGE_RULES
+  §8.3: `organizationId` rides META) extracted from 25 drifted per-kernel
+  `events/helpers.ts` copies. `userId` ← `String(actorId)` falling back to
+  `actorRef` (the commerce dialect), `organizationId` ← stringified,
+  `correlationId` pass-through; absent fields omitted
+  (`exactOptionalPropertyTypes`-safe). Kernel helpers become one-liners:
+  `createPurchaseEvent = (t, p, ctx?, m?) =>
+  createScopedEvent('@classytic/purchase', t, p, ctx, m)`.
+
+### Changed — `EventTransport.subscribe` is now optional
+
+- **`/events` `EventTransport.subscribe?`** — publish-only transports (outbox
+  bridge adapters, host wrappers around a `publish(type, payload, meta)`
+  helper, fire-and-forget pipes) now conform without casting. Hosts were
+  writing `subscribe: undefined as unknown as EventTransport['subscribe']`
+  literals or `as unknown as EventTransport` widenings to inject them into
+  kernels that never call `subscribe` on the injected transport. Consumers
+  that need in-process delivery must guard for an absent `subscribe` — the
+  same "detect and fall back" contract `publishMany` and `deadLetter`
+  already carry (flow's `createSettlementListener` is the reference guard;
+  it has guarded `?.subscribe` since flow 0.5). Kernels subscribing on
+  their OWN in-process bus are unaffected — concrete buses still implement
+  `subscribe`, and a concrete method satisfies an optional member.
+- Audited call sites before the change (`commerce/packages/*/src`,
+  `commerce/spine/packages/*/src`): the `.subscribe` uses on injected
+  transports are pass-through dispatcher methods hosts opt into (crm/party
+  `dispatch.ts`), an already-guarded listener (flow's
+  `createSettlementListener`), and invoice's audit bridge — which only
+  subscribes when `config.audit` is wired. Each of these sources picks up a
+  compile-time "possibly undefined" prompt on its NEXT rebuild against this
+  version, forcing the guard (or a documented throw) exactly where a
+  publish-only transport would have failed at runtime before. No published
+  dist behavior changes.
+
+## [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/event-infra.d.mts

@@ -0,0 +1,79 @@
+import { DomainEvent, EventHandler, EventTransport, PublishManyResult } from "./events.mjs";
+import { OutboxAcknowledgeOptions, OutboxStore, OutboxWriteOptions } from "./outbox.mjs";
+
+//#region src/events/event-infra.d.ts
+/** Minimal error-only logger — assignable from `console`, pino, fastify.log. */
+interface ErrorLogger {
+  error(message: string, ...args: unknown[]): void;
+}
+interface InProcessEventBusOptions {
+  /**
+   * Transport name (`EventTransport.name`). Kernels use
+   * `'in-process-<kernel>'`. Default: `'in-process'`.
+   */
+  name?: string;
+  /**
+   * Logger for per-handler error isolation (default: `console`).
+   * Pass `null` to swallow handler errors silently (cart's historical
+   * behavior — event emission never propagates OR logs).
+   */
+  logger?: ErrorLogger | null;
+  /**
+   * Label used in the handler-error log line:
+   * `[<logLabel>] handler error for <event.type>:`. Default: `name`.
+   */
+  logLabel?: string;
+}
+/**
+ * In-process fan-out `EventTransport` — structurally identical to arc's
+ * `MemoryEventTransport`, so the two are interchangeable.
+ *
+ * Semantics (the union of every kernel copy this replaces):
+ *  - Glob matching via {@link matchEventPattern} (exact / `*` / `prefix.*`
+ *    / `prefix:*`).
+ *  - A handler subscribed under multiple matching patterns fires ONCE per
+ *    event (Set-dedup — the majority variant across kernels).
+ *  - Per-handler error isolation: one failing subscriber never crashes
+ *    siblings; the failure is logged (or swallowed with `logger: null`).
+ *  - `publishMany` batches per-event outcomes keyed by `meta.id`.
+ *  - `close()` clears all subscriptions; publish after close is a no-op;
+ *    close is idempotent. NOT durable — engines own it under the fleet
+ *    `ownsBus` convention (PACKAGE_RULES §8.1).
+ */
+declare class InProcessEventBus implements EventTransport {
+  readonly name: string;
+  private handlers;
+  private readonly logger;
+  private readonly logLabel;
+  constructor(options?: InProcessEventBusOptions);
+  publish(event: DomainEvent): Promise<void>;
+  publishMany(events: readonly DomainEvent[]): Promise<PublishManyResult>;
+  subscribe(pattern: string, handler: EventHandler): Promise<() => void>;
+  close(): Promise<void>;
+}
+/** Factory form of {@link InProcessEventBus} for hosts that prefer functions. */
+declare function createInProcessBus(options?: InProcessEventBusOptions): InProcessEventBus;
+/**
+ * In-memory {@link OutboxStore} for tests and local dev. Not for production —
+ * hosts wire arc's `MongoOutboxStore`, a mongokit repo via
+ * `repositoryAsOutboxStore`, or any durable implementation.
+ *
+ * Implements the required trio (`save` / `getPending` / `acknowledge`) plus
+ * optional `purge`. Lease-based methods (`claimPending` / `fail` /
+ * `getDeadLettered`) are intentionally omitted — single-process tests don't
+ * need them, and kernels only call `save()` themselves. `all()` / `clear()`
+ * are test-inspection helpers (not part of the contract).
+ */
+declare class MemoryOutboxStore implements OutboxStore {
+  private events;
+  save(event: DomainEvent, _options?: OutboxWriteOptions): Promise<void>;
+  getPending(limit: number): Promise<DomainEvent[]>;
+  acknowledge(eventId: string, _options?: OutboxAcknowledgeOptions): Promise<void>;
+  purge(olderThanMs: number): Promise<number>;
+  /** Every saved event (acknowledged or not) — test inspection helper. */
+  all(): ReadonlyArray<DomainEvent>;
+  /** Reset the store — test helper. */
+  clear(): void;
+}
+//#endregion
+export { ErrorLogger, InProcessEventBus, InProcessEventBusOptions, MemoryOutboxStore, createInProcessBus };

package/dist/event-infra.mjs

@@ -0,0 +1,109 @@
+import { matchEventPattern } from "./events.mjs";
+//#region src/events/event-infra.ts
+/**
+* In-process fan-out `EventTransport` — structurally identical to arc's
+* `MemoryEventTransport`, so the two are interchangeable.
+*
+* Semantics (the union of every kernel copy this replaces):
+*  - Glob matching via {@link matchEventPattern} (exact / `*` / `prefix.*`
+*    / `prefix:*`).
+*  - A handler subscribed under multiple matching patterns fires ONCE per
+*    event (Set-dedup — the majority variant across kernels).
+*  - Per-handler error isolation: one failing subscriber never crashes
+*    siblings; the failure is logged (or swallowed with `logger: null`).
+*  - `publishMany` batches per-event outcomes keyed by `meta.id`.
+*  - `close()` clears all subscriptions; publish after close is a no-op;
+*    close is idempotent. NOT durable — engines own it under the fleet
+*    `ownsBus` convention (PACKAGE_RULES §8.1).
+*/
+var InProcessEventBus = class {
+	name;
+	handlers = /* @__PURE__ */ new Map();
+	logger;
+	logLabel;
+	constructor(options = {}) {
+		this.name = options.name ?? "in-process";
+		this.logger = options.logger === null ? null : options.logger ?? console;
+		this.logLabel = options.logLabel ?? this.name;
+	}
+	async publish(event) {
+		const matched = /* @__PURE__ */ new Set();
+		for (const [pattern, set] of this.handlers.entries()) if (matchEventPattern(pattern, event.type)) for (const h of set) matched.add(h);
+		for (const handler of matched) try {
+			await handler(event);
+		} catch (err) {
+			this.logger?.error(`[${this.logLabel}] handler error for ${event.type}:`, err);
+		}
+	}
+	async publishMany(events) {
+		const results = /* @__PURE__ */ new Map();
+		for (const event of events) try {
+			await this.publish(event);
+			results.set(event.meta.id, null);
+		} catch (err) {
+			results.set(event.meta.id, err instanceof Error ? err : new Error(String(err)));
+		}
+		return results;
+	}
+	async subscribe(pattern, handler) {
+		let set = this.handlers.get(pattern);
+		if (!set) {
+			set = /* @__PURE__ */ new Set();
+			this.handlers.set(pattern, set);
+		}
+		set.add(handler);
+		return () => {
+			const s = this.handlers.get(pattern);
+			if (!s) return;
+			s.delete(handler);
+			if (s.size === 0) this.handlers.delete(pattern);
+		};
+	}
+	async close() {
+		this.handlers.clear();
+	}
+};
+/** Factory form of {@link InProcessEventBus} for hosts that prefer functions. */
+function createInProcessBus(options) {
+	return new InProcessEventBus(options);
+}
+/**
+* In-memory {@link OutboxStore} for tests and local dev. Not for production —
+* hosts wire arc's `MongoOutboxStore`, a mongokit repo via
+* `repositoryAsOutboxStore`, or any durable implementation.
+*
+* Implements the required trio (`save` / `getPending` / `acknowledge`) plus
+* optional `purge`. Lease-based methods (`claimPending` / `fail` /
+* `getDeadLettered`) are intentionally omitted — single-process tests don't
+* need them, and kernels only call `save()` themselves. `all()` / `clear()`
+* are test-inspection helpers (not part of the contract).
+*/
+var MemoryOutboxStore = class {
+	events = [];
+	async save(event, _options) {
+		this.events.push({ event });
+	}
+	async getPending(limit) {
+		return this.events.filter((e) => !e.acknowledgedAt).slice(0, limit).map((e) => e.event);
+	}
+	async acknowledge(eventId, _options) {
+		const entry = this.events.find((e) => e.event.meta.id === eventId);
+		if (entry) entry.acknowledgedAt = /* @__PURE__ */ new Date();
+	}
+	async purge(olderThanMs) {
+		const cutoff = Date.now() - olderThanMs;
+		const before = this.events.length;
+		this.events = this.events.filter((e) => !e.acknowledgedAt || e.acknowledgedAt.getTime() >= cutoff);
+		return before - this.events.length;
+	}
+	/** Every saved event (acknowledged or not) — test inspection helper. */
+	all() {
+		return this.events.map((e) => e.event);
+	}
+	/** Reset the store — test helper. */
+	clear() {
+		this.events = [];
+	}
+};
+//#endregion
+export { InProcessEventBus, MemoryOutboxStore, createInProcessBus };

package/dist/events.d.mts

@@ -179,8 +179,18 @@ interface EventTransport {
   /**
    * Subscribe to a glob pattern — exact match, `*`, or `resource.*`. Returns
    * an unsubscribe function.
+   *
+   * Optional (0.13.0): publish-only transports — outbox bridge adapters,
+   * host wrappers around a `publish(type, payload, meta)` helper, fire-and-
+   * forget pipes into Kafka/webhooks — are legitimate `EventTransport`s.
+   * Consumers that need in-process delivery MUST guard (`transport.subscribe
+   * ? … : throw/fallback`) the same way they already do for the optional
+   * `publishMany` / `deadLetter` members (see flow's
+   * `ConsignmentService.createSettlementListener` for the reference guard).
+   * Kernels subscribing on their OWN in-process bus (which always implements
+   * `subscribe`) are unaffected.
    */
-  subscribe(pattern: string, handler: EventHandler): Promise<() => void>;
+  subscribe?(pattern: string, handler: EventHandler): Promise<() => void>;
   /**
    * Route a permanently-failed event to the transport's dead-letter sink
    * (Kafka DLQ topic, SQS DLQ, Redis Stream `PEL` timeout handler, etc.).
@@ -227,6 +237,54 @@ declare function createEvent<T>(type: string, payload: T, meta?: Partial<EventMe
  * // reserved.meta.userId        === user.id   (inherited)
  */
 declare function createChildEvent<T>(parent: DomainEvent, type: string, payload: T, meta?: Partial<EventMeta>): DomainEvent<T>;
+/**
+ * The context slice {@link createScopedEvent} maps into {@link EventMeta}.
+ *
+ * Structurally satisfied by primitives' `OperationContext` (actorId /
+ * organizationId as IdLike) AND by the commerce `actorRef` dialect used by
+ * cart/promo/crm — so every kernel context threads straight through.
+ */
+interface EventScopeContext {
+  /** Authenticated principal id (`OperationContext.actorId` shape). */
+  actorId?: string | number | {
+    toString(): string;
+  } | undefined;
+  /** Commerce actor-reference dialect (`user:123`, `guest:abc`). Used when `actorId` is absent. */
+  actorRef?: string | undefined;
+  /** Tenant / organization / branch scope — rides `meta.organizationId` (META, never payload). */
+  organizationId?: string | {
+    toString(): string;
+  } | undefined;
+  /** Correlation id threaded across the causal chain. */
+  correlationId?: string | undefined;
+}
+/**
+ * Map an operation context onto event META — THE standard context→meta
+ * mapping (PACKAGE_RULES §8.3: `organizationId` rides META). Extracted from
+ * 25 drifted per-kernel `events/helpers.ts` copies.
+ *
+ *  - `userId`  ← `String(ctx.actorId)`, falling back to `ctx.actorRef`
+ *  - `organizationId` ← `String(ctx.organizationId)`
+ *  - `correlationId`  ← `ctx.correlationId`
+ *
+ * Absent fields are OMITTED (not set to `undefined`) so the result spreads
+ * cleanly under `exactOptionalPropertyTypes`.
+ */
+declare function scopedEventMeta(ctx?: EventScopeContext): Partial<EventMeta>;
+/**
+ * Build a {@link DomainEvent} scoped to an emitting package and an operation
+ * context — the shared core behind every kernel's `createXEvent` helper.
+ *
+ * ```ts
+ * // purchase/src/events/helpers.ts becomes:
+ * export const createPurchaseEvent = <T>(type, payload, ctx?, meta?) =>
+ *   createScopedEvent('@classytic/purchase', type, payload, ctx, meta);
+ * ```
+ *
+ * Precedence: defaults (id/timestamp) < `source` < context mapping < caller
+ * `meta` — identical to the hand-rolled helpers this replaces.
+ */
+declare function createScopedEvent<T>(source: string, type: string, payload: T, ctx?: EventScopeContext, meta?: Partial<EventMeta>): DomainEvent<T>;
 /**
  * Match an event name against a glob pattern. Implements the same rules as
  * arc's `MemoryEventTransport`:
@@ -237,4 +295,4 @@ declare function createChildEvent<T>(parent: DomainEvent, type: string, payload:
  */
 declare function matchEventPattern(pattern: string, type: string): boolean;
 //#endregion
-export { DeadLetteredEvent, DomainEvent, EventHandler, EventLogger, EventMeta, EventTransport, PublishManyResult, createChildEvent, createEvent, matchEventPattern };
+export { DeadLetteredEvent, DomainEvent, EventHandler, EventLogger, EventMeta, EventScopeContext, EventTransport, PublishManyResult, createChildEvent, createEvent, createScopedEvent, matchEventPattern, scopedEventMeta };

package/dist/events.mjs

@@ -64,6 +64,47 @@ function createChildEvent(parent, type, payload, meta) {
 	};
 }
 /**
+* Map an operation context onto event META — THE standard context→meta
+* mapping (PACKAGE_RULES §8.3: `organizationId` rides META). Extracted from
+* 25 drifted per-kernel `events/helpers.ts` copies.
+*
+*  - `userId`  ← `String(ctx.actorId)`, falling back to `ctx.actorRef`
+*  - `organizationId` ← `String(ctx.organizationId)`
+*  - `correlationId`  ← `ctx.correlationId`
+*
+* Absent fields are OMITTED (not set to `undefined`) so the result spreads
+* cleanly under `exactOptionalPropertyTypes`.
+*/
+function scopedEventMeta(ctx) {
+	if (!ctx) return {};
+	const meta = {};
+	const actor = ctx.actorId ?? ctx.actorRef;
+	if (actor !== void 0) meta.userId = String(actor);
+	if (ctx.organizationId !== void 0) meta.organizationId = String(ctx.organizationId);
+	if (ctx.correlationId !== void 0) meta.correlationId = ctx.correlationId;
+	return meta;
+}
+/**
+* Build a {@link DomainEvent} scoped to an emitting package and an operation
+* context — the shared core behind every kernel's `createXEvent` helper.
+*
+* ```ts
+* // purchase/src/events/helpers.ts becomes:
+* export const createPurchaseEvent = <T>(type, payload, ctx?, meta?) =>
+*   createScopedEvent('@classytic/purchase', type, payload, ctx, meta);
+* ```
+*
+* Precedence: defaults (id/timestamp) < `source` < context mapping < caller
+* `meta` — identical to the hand-rolled helpers this replaces.
+*/
+function createScopedEvent(source, type, payload, ctx, meta) {
+	return createEvent(type, payload, {
+		source,
+		...scopedEventMeta(ctx),
+		...meta
+	});
+}
+/**
 * Match an event name against a glob pattern. Implements the same rules as
 * arc's `MemoryEventTransport`:
 *   - `*` matches anything
@@ -87,4 +128,4 @@ function randomEventId() {
 	});
 }
 //#endregion
-export { createChildEvent, createEvent, matchEventPattern };
+export { createChildEvent, createEvent, createScopedEvent, matchEventPattern, scopedEventMeta };

package/dist/money.d.mts

@@ -104,7 +104,38 @@ declare function isPositiveMoney(m: Money): boolean;
 declare function isNegativeMoney(m: Money): boolean;
 declare function negateMoney(m: Money): Money;
 declare function absMoney(m: Money): Money;
+/**
+ * Decimal major-unit number → integer minor units by decimal exponent.
+ * Rounding: raw IEEE `Math.round` — half-up toward +∞ (so `-10.5 → -10`),
+ * documented above. Throws when the result leaves the safe-integer range
+ * (also catches `NaN`/`Infinity` inputs).
+ *
+ * @example
+ * majorToMinorUnits(10.5)      // 1050
+ * majorToMinorUnits(1000, 0)   // 1000 (JPY-style)
+ * majorToMinorUnits(1.005)     // 100 — IEEE, see note above
+ */
+declare function majorToMinorUnits(major: number, minorUnitDecimals?: number): number;
+/** Integer minor units → decimal major-unit number by decimal exponent: `1050 → 10.5`. */
+declare function minorUnitsToMajor(minor: number, minorUnitDecimals?: number): number;
+/**
+ * Percentage of an integer minor-unit amount → integer minor units.
+ * EXACT multiply-then-round: `Math.round((minor × ratePercent) / 100)` —
+ * one rounding point, half-up toward +∞. Handles genuinely fractional rates
+ * (QST 9.975 %) without precision loss: `percentOfMinor(20000, 9.975) === 1995`.
+ *
+ * Hosts whose domain guarantees at-most-2-decimal rates MAY snap the rate to
+ * integer basis points BEFORE calling (be-prod's `#shared/money` seam does) —
+ * that is host policy layered on top, not part of this primitive.
+ */
+declare function percentOfMinor(minor: number, ratePercent: number): number;
+/**
+ * Integer minor units → plain decimal string (no currency symbol, no locale):
+ * `formatMinorUnits(10550) → "105.50"`, `formatMinorUnits(1000, 0) → "1000"`.
+ * For localized currency strings use `Intl.NumberFormat` at the display layer.
+ */
+declare function formatMinorUnits(minor: number, minorUnitDecimals?: number): string;
 /** Structural type guard. */
 declare function isMoney(value: unknown): value is Money;
 //#endregion
-export { CurrencyMismatchError, MinorUnits, Money, absMoney, addMoney, compareMoney, equalsMoney, fromMajor, isMoney, isNegativeMoney, isPositiveMoney, isZeroMoney, money, multiplyMoney, negateMoney, subtractMoney, sumMoney, toMajor };
+export { CurrencyMismatchError, MinorUnits, Money, absMoney, addMoney, compareMoney, equalsMoney, formatMinorUnits, fromMajor, isMoney, isNegativeMoney, isPositiveMoney, isZeroMoney, majorToMinorUnits, minorUnitsToMajor, money, multiplyMoney, negateMoney, percentOfMinor, subtractMoney, sumMoney, toMajor };

package/dist/money.mjs

@@ -135,9 +135,52 @@ function negateMoney(m) {
 function absMoney(m) {
 	return m.amount < 0 ? negateMoney(m) : m;
 }
+/**
+* Decimal major-unit number → integer minor units by decimal exponent.
+* Rounding: raw IEEE `Math.round` — half-up toward +∞ (so `-10.5 → -10`),
+* documented above. Throws when the result leaves the safe-integer range
+* (also catches `NaN`/`Infinity` inputs).
+*
+* @example
+* majorToMinorUnits(10.5)      // 1050
+* majorToMinorUnits(1000, 0)   // 1000 (JPY-style)
+* majorToMinorUnits(1.005)     // 100 — IEEE, see note above
+*/
+function majorToMinorUnits(major, minorUnitDecimals = 2) {
+	const factor = 10 ** minorUnitDecimals;
+	const minor = Math.round(major * factor);
+	if (!Number.isSafeInteger(minor)) throw new RangeError(`Amount ${major} exceeds safe integer limit when converted to minor units. Max safe amount: ${Number.MAX_SAFE_INTEGER / factor}`);
+	return minor;
+}
+/** Integer minor units → decimal major-unit number by decimal exponent: `1050 → 10.5`. */
+function minorUnitsToMajor(minor, minorUnitDecimals = 2) {
+	return minor / 10 ** minorUnitDecimals;
+}
+/**
+* Percentage of an integer minor-unit amount → integer minor units.
+* EXACT multiply-then-round: `Math.round((minor × ratePercent) / 100)` —
+* one rounding point, half-up toward +∞. Handles genuinely fractional rates
+* (QST 9.975 %) without precision loss: `percentOfMinor(20000, 9.975) === 1995`.
+*
+* Hosts whose domain guarantees at-most-2-decimal rates MAY snap the rate to
+* integer basis points BEFORE calling (be-prod's `#shared/money` seam does) —
+* that is host policy layered on top, not part of this primitive.
+*/
+function percentOfMinor(minor, ratePercent) {
+	if (!Number.isFinite(minor) || !Number.isFinite(ratePercent)) throw new TypeError(`percentOfMinor received non-finite input: minor=${minor}, ratePercent=${ratePercent}`);
+	return Math.round(minor * ratePercent / 100);
+}
+/**
+* Integer minor units → plain decimal string (no currency symbol, no locale):
+* `formatMinorUnits(10550) → "105.50"`, `formatMinorUnits(1000, 0) → "1000"`.
+* For localized currency strings use `Intl.NumberFormat` at the display layer.
+*/
+function formatMinorUnits(minor, minorUnitDecimals = 2) {
+	return minorUnitsToMajor(minor, minorUnitDecimals).toFixed(minorUnitDecimals);
+}
 /** Structural type guard. */
 function isMoney(value) {
 	return typeof value === "object" && value !== null && typeof value.amount === "number" && Number.isInteger(value.amount) && typeof value.currency === "string";
 }
 //#endregion
-export { CurrencyMismatchError, MinorUnits, absMoney, addMoney, compareMoney, equalsMoney, fromMajor, isMoney, isNegativeMoney, isPositiveMoney, isZeroMoney, money, multiplyMoney, negateMoney, subtractMoney, sumMoney, toMajor };
+export { CurrencyMismatchError, MinorUnits, absMoney, addMoney, compareMoney, equalsMoney, formatMinorUnits, fromMajor, isMoney, isNegativeMoney, isPositiveMoney, isZeroMoney, majorToMinorUnits, minorUnitsToMajor, money, multiplyMoney, negateMoney, percentOfMinor, subtractMoney, sumMoney, toMajor };

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.14.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"
@@ -57,6 +61,10 @@
       "types": "./dist/events.d.mts",
       "default": "./dist/events.mjs"
     },
+    "./event-infra": {
+      "types": "./dist/event-infra.d.mts",
+      "default": "./dist/event-infra.mjs"
+    },
     "./outbox": {
       "types": "./dist/outbox.d.mts",
       "default": "./dist/outbox.mjs"