@classytic/primitives 0.16.0 → 0.19.0

package/CHANGELOG.md

@@ -3,6 +3,72 @@
 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.19.0] - 2026-08-01
+
+### Added — `./monetization`: canonical pricing classification contract
+
+- **`@classytic/primitives/monetization`** — the single home for how a product
+  is sold and priced, so the classification survives end-to-end across catalog,
+  revenue, order, and entitlement kernels without each maintaining its own enum.
+- **`Monetization`** discriminated union — `FreeMonetization | OneTimeMonetization |
+  SubscriptionMonetization | BundleMonetization | UsageMonetization`, each
+  carrying its own nested pricing shape.
+- **`MONETIZATION_KINDS`** + **`MonetizationKind`** + **`isMonetizationKind`** —
+  exhaustive kind list with runtime guard.
+- Type-guard predicates: **`isFreeMonetization`**, **`isOneTimeMonetization`**,
+  **`isSubscriptionMonetization`**, **`isBundleMonetization`**,
+  **`isUsageMonetization`**.
+- Supporting types: `PriceTier`, `OneTimePricing`, `SubscriptionPlan`,
+  `UsageTier`, `UsageRating`, `DurationUnit`, `MoneyByCurrency`.
+
+### Added — `./proration`: pure proration arithmetic
+
+- **`@classytic/primitives/proration`** — timezone-agnostic, policy-free
+  proration math. Holds no commercial policy (no upgrade/downgrade semantics,
+  no discount or tax logic) — those live in the contract kernel.
+- **`periodProgress(input)`** — fraction of a billing period consumed given
+  start, end, and current instants as `Date`. Returns `PeriodFraction`.
+- **`splitByPeriodFraction(amount, fraction, granularity?)`** — split a `Money`
+  amount into consumed/remaining parts; `granularity: 'whole_day'` (default) or
+  `'exact'`.
+- **`allocateMoneyByFraction(amount, fraction)`** — proportional allocation
+  using the largest-remainder allocator so `consumed + remaining === amount`
+  exactly (no penny drift).
+- **`ProrationError`** + **`ProrationErrorCode`** (`INVALID_PERIOD` |
+  `INVALID_FRACTION`) — typed errors for out-of-range inputs.
+- Supporting types: `PeriodFraction`, `PeriodProgressInput`,
+  `ProrationGranularity`.
+
+## [0.18.0] - 2026-07-29
+
+### Added — `./subject`: `SubjectRef` polymorphic identity pointer
+
+- **`@classytic/primitives/subject`** — `SubjectRef` (`{ subjectModel, subjectRef }`) — WHO a record is about, polymorphically. The pairing spans every kernel that holds data about a person without owning them (attendance, access, loyalty, credentials). Deliberately kept distinct from `ExternalRef` (provenance — "came from") even though the shapes are identical: a grant carries both at once and they mean different things.
+- **`buildSubjectRef(model, id)`** — returns `SubjectRef | null`; `null` when `id` is absent/blank, because a malformed binding silently matches nothing (an entitlement nobody holds, a credential no revoke can find) rather than carrying `"undefined"` as a string.
+- **`SubjectRef`** type exported from `@classytic/primitives/subject`.
+
+### Added — `./state-diagram`: Mermaid diagram from a `StateMachine`
+
+- **`@classytic/primitives/state-diagram`** — `renderStateDiagram(machine, opts?)` — generates a `stateDiagram-v2` Mermaid string from the same `StateMachine` object the runtime CAS enforces. Removes the class of drift where a hand-drawn prose comment diverges from the actual transition table. Pure: string in, string out, no I/O.
+- **`StateDiagramOptions`** — `title?`, `highlight?` (mark specific states), `noteOn?` (per-state annotations).
+
+### Added — `./suspension`: time-bounded suspension/pause policy
+
+- **`@classytic/primitives/suspension`** — pure suspension policy computation (no persistence). Models a pause the subject is ENTITLED to take, bounded by an annual allowance, that ends by itself — distinct from `/hold` (an indefinite blocker needing manual resolution).
+- **`evaluateSuspension(policy, history, opts)`** — always returns `autoResumeAt` (the instant the pause MUST end) so a sweep can resume it whether or not the subject ever comes back. Covers: gym membership freeze, subscription pause, unpaid leave.
+- **`SuspensionPolicy`** — `maxDaysPerPeriod`, `minDurationDays`, `period` ('annual' | 'rolling').
+- **`SuspensionEntry`** — a historical pause record (`startedAt`, `endedAt?`, `reason?`).
+- **`SuspensionResult`** — `autoResumeAt`, `daysUsed`, `daysRemaining`, `status`.
+
+### Added — `OutboxStore.transactionalSave` (`/outbox`)
+
+- **`OutboxStore.transactionalSave?: boolean`** — declares whether `save` enlists `options.session` in the caller's transaction. Absent/`false` = "assume NOT atomic". Set `true` ONLY when `save` passes the session to the same transactional resource the caller writes (e.g. a mongoose model on the same connection). Callers that need atomicity (`@classytic/access`'s `atomically()`) check this flag and fail at boot rather than claiming a guarantee they cannot keep.
+- **`MemoryOutboxStore.transactionalSave = false`** — explicitly declared; an in-memory store cannot participate in a Mongo transaction, so its write survives a rollback.
+
+### Changed — `shelf-life.ts` deduplicates `addDays`
+
+- `addDays` is now imported from `./calendar` instead of being re-defined inline. No behavior change.
+
 ## [0.16.0] - 2026-07-27
 
 ### Added — `assertApproved` + `CHAIN_INCOMPLETE` (`/approval`)

package/dist/event-infra.d.mts

@@ -98,6 +98,16 @@ declare function createInProcessBus(options?: InProcessEventBusOptions): InProce
  * are test-inspection helpers (not part of the contract).
  */
 declare class MemoryOutboxStore implements OutboxStore {
+  /**
+   * Deliberately NOT transactional — and saying so is the point.
+   *
+   * This store pushes onto an in-process array, which no database transaction
+   * can roll back. If a caller's Mongo write aborts after `save`, the event
+   * SURVIVES here and describes something that never happened. Declaring
+   * `false` lets a caller that needs real atomicity (`@classytic/access`) refuse
+   * at boot instead of silently inheriting a ghost-event path.
+   */
+  readonly transactionalSave = false;
   private events;
   save(event: DomainEvent, _options?: OutboxWriteOptions): Promise<void>;
   getPending(limit: number): Promise<DomainEvent[]>;

package/dist/event-infra.mjs

@@ -89,6 +89,16 @@ function createInProcessBus(options) {
 * are test-inspection helpers (not part of the contract).
 */
 var MemoryOutboxStore = class {
+	/**
+	* Deliberately NOT transactional — and saying so is the point.
+	*
+	* This store pushes onto an in-process array, which no database transaction
+	* can roll back. If a caller's Mongo write aborts after `save`, the event
+	* SURVIVES here and describes something that never happened. Declaring
+	* `false` lets a caller that needs real atomicity (`@classytic/access`) refuse
+	* at boot instead of silently inheriting a ghost-event path.
+	*/
+	transactionalSave = false;
 	events = [];
 	async save(event, _options) {
 		this.events.push({ event });

package/dist/monetization.d.mts

@@ -0,0 +1,195 @@
+import { Money } from "./money.mjs";
+
+//#region src/money/monetization.d.ts
+/**
+ * A map of currency code → {@link Money} for explicit per-currency pricing.
+ * Explicit entries always win over a currency-conversion fallback.
+ *
+ * Canonical home (was hand-declared in `@classytic/catalog`; re-exported there
+ * for back-compat). Belongs with money because it is a money-shaped value.
+ */
+type MoneyByCurrency = Record<string, Money>;
+/**
+ * The canonical monetization kinds. Order is stable; append only.
+ *
+ *   - `free`         — no charge.
+ *   - `one_time`     — charged once (catalog `one_time`; revenue `purchase`).
+ *   - `subscription` — recurring plan / membership.
+ *   - `bundle`       — a composite priced from its members.
+ *   - `usage`        — metered / per-seat / consumption (billed per unit or in
+ *                      arrears). The extension point for rating models.
+ */
+declare const MONETIZATION_KINDS: readonly ["free", "one_time", "subscription", "bundle", "usage"];
+type MonetizationKind = (typeof MONETIZATION_KINDS)[number];
+/** True when `value` is one of the canonical kinds. */
+declare function isMonetizationKind(value: unknown): value is MonetizationKind;
+/** A quantity-based price break. `price` (fixed override) XOR `discountPercent`. */
+interface PriceTier {
+  /** Minimum quantity to qualify. */
+  readonly minQuantity: number;
+  /** Fixed override price for this tier. */
+  readonly price?: Money;
+  /** OR a percentage discount (0–100). Mutually exclusive with `price`. */
+  readonly discountPercent?: number;
+}
+interface OneTimePricing {
+  /** Required base (list) price. */
+  readonly basePrice: Money;
+  /** Default currency (redundant with `basePrice.currency`, indexed for queries). */
+  readonly currency: string;
+  /** Optional strikethrough / MSRP price. */
+  readonly compareAtPrice?: Money;
+  /** Explicit per-currency price overrides. */
+  readonly priceByCurrency?: MoneyByCurrency;
+  /** Optional cost (role-gated — filtered for non-finance readers). */
+  readonly costPrice?: Money;
+  /** Optional volume tiers (quantity-based discounts). */
+  readonly tiers?: readonly PriceTier[];
+}
+type DurationUnit = 'day' | 'week' | 'month' | 'year';
+interface SubscriptionPlan {
+  /** Internal key ('monthly', 'quarterly', 'annual'). */
+  readonly key: string;
+  /** Display label ("Monthly", "Annual (save 20%)"). */
+  readonly label: string;
+  /** Base price for this plan in the default currency. */
+  readonly price: Money;
+  /** Explicit per-currency overrides. */
+  readonly priceByCurrency?: MoneyByCurrency;
+  /** Billing cycle length. */
+  readonly duration: number;
+  /** Unit of the billing cycle. */
+  readonly durationUnit: DurationUnit;
+  /** Optional free trial length in days. */
+  readonly trialDays?: number;
+  /** Optional auto-calculated discount vs the highest-frequency plan. */
+  readonly discount?: number;
+}
+/**
+ * One band of a metered rate table.
+ *
+ * `upTo` is the inclusive upper bound of the band; omit it for the final,
+ * open-ended band. Within a band either a `perUnit` rate applies (per metered
+ * unit) or a `flatPrice` (a stairstep charge for landing in the band).
+ */
+interface UsageTier {
+  readonly upTo?: number;
+  readonly perUnit?: Money;
+  readonly flatPrice?: Money;
+}
+/**
+ * How a metered unit is priced. One `scheme`, composed with the fields it needs
+ * — this single shape covers per-seat, metered, graduated, volume, package and
+ * base-plus-overage without a separate kind for each.
+ *
+ *   - `per_unit` — price × quantity (per-seat licensing, flat metering).
+ *   - `tiered`   — graduated: each unit priced at the rate of the band it falls in.
+ *   - `volume`   — the WHOLE quantity priced at the band the total lands in.
+ *   - `package`  — priced per package of `packageSize` units.
+ *
+ * `includedUnits` are free before metering starts (base-plus-overage when paired
+ * with {@link UsageMonetization.baseFee}).
+ */
+interface UsageRating {
+  readonly scheme: 'per_unit' | 'tiered' | 'volume' | 'package';
+  /** Flat per-unit rate (`per_unit` scheme). */
+  readonly perUnit?: Money;
+  /** Rate table (`tiered` / `volume` schemes). */
+  readonly tiers?: readonly UsageTier[];
+  /** Units per package and the package price (`package` scheme). */
+  readonly packageSize?: number;
+  readonly packagePrice?: Money;
+  /** Free units before metering starts (base-plus-overage). */
+  readonly includedUnits?: number;
+  /** Display label for one unit ("seat", "GB", "call", "visit"). */
+  readonly unitLabel?: string;
+}
+interface FreeMonetization {
+  readonly type: 'free';
+}
+interface OneTimeMonetization {
+  readonly type: 'one_time';
+  readonly pricing: OneTimePricing;
+}
+interface SubscriptionMonetization {
+  readonly type: 'subscription';
+  /** At least one plan is required. */
+  readonly plans: readonly SubscriptionPlan[];
+}
+interface BundleMonetization {
+  readonly type: 'bundle';
+  /** Optional fixed bundle price (overrides the dynamic sum). */
+  readonly basePrice?: Money;
+  /** How bundle pricing is computed. */
+  readonly pricingMode: 'fixed' | 'dynamic';
+  /** For `dynamic` mode, an optional 0–100 discount on the members' sum. */
+  readonly dynamicDiscountPercent?: number;
+}
+/**
+ * Metered / consumption pricing. The extension point for per-seat, metered,
+ * graduated, volume, package and base-plus-overage — all via {@link UsageRating}
+ * so the classification does not grow one kind per rating model.
+ */
+interface UsageMonetization {
+  readonly type: 'usage';
+  /** Optional recurring base fee charged regardless of usage (base + overage). */
+  readonly baseFee?: Money;
+  /** How each metered unit is priced. */
+  readonly rating: UsageRating;
+  /** Settlement cadence when usage is billed in arrears. */
+  readonly billingPeriod?: {
+    readonly duration: number;
+    readonly durationUnit: DurationUnit;
+  };
+}
+/**
+ * The canonical monetization value object. The `type` discriminant selects the
+ * pricing detail. Matches `@classytic/catalog`'s existing discriminants (so no
+ * data migration) plus `usage`.
+ */
+type Monetization = FreeMonetization | OneTimeMonetization | SubscriptionMonetization | BundleMonetization | UsageMonetization;
+declare const isFreeMonetization: (m: Monetization) => m is FreeMonetization;
+declare const isOneTimeMonetization: (m: Monetization) => m is OneTimeMonetization;
+declare const isSubscriptionMonetization: (m: Monetization) => m is SubscriptionMonetization;
+declare const isBundleMonetization: (m: Monetization) => m is BundleMonetization;
+declare const isUsageMonetization: (m: Monetization) => m is UsageMonetization;
+/** The kind of a monetization value (its discriminant, narrowed to the union). */
+declare const monetizationKindOf: (m: Monetization) => MonetizationKind;
+/**
+ * The single headline unit price for a monetization, or `null` when there isn't
+ * one. This is the ONE place that decides "which number is the price" per kind,
+ * so a cart line, an order snapshot and a storefront card never re-`switch` on
+ * `type` and drift (a host that read `plans[0].price` while another read
+ * `plans[1]` is exactly the divergence this prevents).
+ *
+ *   - `one_time`     → the base (list) price
+ *   - `subscription` → the first plan's price (the default / most-frequent plan)
+ *   - `bundle`       → the FIXED bundle price; `null` in `dynamic` mode (that
+ *                      price is computed from the members, not stored here)
+ *   - `free`         → `null`
+ *   - `usage`        → `null` — a metered item has no single unit price; it is
+ *                      rated per consumption via {@link UsageRating}
+ *
+ * Exhaustive on purpose: a new kind fails to compile here until it declares how
+ * it prices, instead of silently returning `null`.
+ */
+declare function unitPriceOf(m: Monetization): Money | null;
+/** The strikethrough / MSRP price, if the kind carries one (only `one_time`). */
+declare function compareAtPriceOf(m: Monetization): Money | null;
+/**
+ * `@classytic/revenue`'s coarse wire enum. `purchase` is the paid-once case that
+ * the rest of the ecosystem calls `one_time`. Kept as its own type so revenue's
+ * PERSISTED values never have to change — only the mapping to the canonical kind
+ * lives here, in one place, instead of an implicit hand-conversion per call site.
+ */
+type RevenueMonetizationType = 'free' | 'purchase' | 'subscription';
+/**
+ * Canonical kind → revenue wire type. Everything that is not `free` or
+ * `subscription` settles as a `purchase` in revenue's ledger vocabulary
+ * (one_time, bundle, and a usage charge are all "a purchase happened").
+ */
+declare function toRevenueMonetizationType(kind: MonetizationKind): RevenueMonetizationType;
+/** Revenue wire type → canonical kind (`purchase` → `one_time`). */
+declare function fromRevenueMonetizationType(type: RevenueMonetizationType): MonetizationKind;
+//#endregion
+export { BundleMonetization, DurationUnit, FreeMonetization, MONETIZATION_KINDS, Monetization, MonetizationKind, MoneyByCurrency, OneTimeMonetization, OneTimePricing, PriceTier, RevenueMonetizationType, SubscriptionMonetization, SubscriptionPlan, UsageMonetization, UsageRating, UsageTier, compareAtPriceOf, fromRevenueMonetizationType, isBundleMonetization, isFreeMonetization, isMonetizationKind, isOneTimeMonetization, isSubscriptionMonetization, isUsageMonetization, monetizationKindOf, toRevenueMonetizationType, unitPriceOf };

package/dist/monetization.mjs

@@ -0,0 +1,79 @@
+//#region src/money/monetization.ts
+/**
+* The canonical monetization kinds. Order is stable; append only.
+*
+*   - `free`         — no charge.
+*   - `one_time`     — charged once (catalog `one_time`; revenue `purchase`).
+*   - `subscription` — recurring plan / membership.
+*   - `bundle`       — a composite priced from its members.
+*   - `usage`        — metered / per-seat / consumption (billed per unit or in
+*                      arrears). The extension point for rating models.
+*/
+const MONETIZATION_KINDS = [
+	"free",
+	"one_time",
+	"subscription",
+	"bundle",
+	"usage"
+];
+const MONETIZATION_KIND_SET = new Set(MONETIZATION_KINDS);
+/** True when `value` is one of the canonical kinds. */
+function isMonetizationKind(value) {
+	return typeof value === "string" && MONETIZATION_KIND_SET.has(value);
+}
+const isFreeMonetization = (m) => m.type === "free";
+const isOneTimeMonetization = (m) => m.type === "one_time";
+const isSubscriptionMonetization = (m) => m.type === "subscription";
+const isBundleMonetization = (m) => m.type === "bundle";
+const isUsageMonetization = (m) => m.type === "usage";
+/** The kind of a monetization value (its discriminant, narrowed to the union). */
+const monetizationKindOf = (m) => m.type;
+/**
+* The single headline unit price for a monetization, or `null` when there isn't
+* one. This is the ONE place that decides "which number is the price" per kind,
+* so a cart line, an order snapshot and a storefront card never re-`switch` on
+* `type` and drift (a host that read `plans[0].price` while another read
+* `plans[1]` is exactly the divergence this prevents).
+*
+*   - `one_time`     → the base (list) price
+*   - `subscription` → the first plan's price (the default / most-frequent plan)
+*   - `bundle`       → the FIXED bundle price; `null` in `dynamic` mode (that
+*                      price is computed from the members, not stored here)
+*   - `free`         → `null`
+*   - `usage`        → `null` — a metered item has no single unit price; it is
+*                      rated per consumption via {@link UsageRating}
+*
+* Exhaustive on purpose: a new kind fails to compile here until it declares how
+* it prices, instead of silently returning `null`.
+*/
+function unitPriceOf(m) {
+	switch (m.type) {
+		case "one_time": return m.pricing.basePrice;
+		case "subscription": return m.plans[0]?.price ?? null;
+		case "bundle": return m.basePrice ?? null;
+		case "free":
+		case "usage": return null;
+	}
+}
+/** The strikethrough / MSRP price, if the kind carries one (only `one_time`). */
+function compareAtPriceOf(m) {
+	return m.type === "one_time" ? m.pricing.compareAtPrice ?? null : null;
+}
+/**
+* Canonical kind → revenue wire type. Everything that is not `free` or
+* `subscription` settles as a `purchase` in revenue's ledger vocabulary
+* (one_time, bundle, and a usage charge are all "a purchase happened").
+*/
+function toRevenueMonetizationType(kind) {
+	if (kind === "free") return "free";
+	if (kind === "subscription") return "subscription";
+	return "purchase";
+}
+/** Revenue wire type → canonical kind (`purchase` → `one_time`). */
+function fromRevenueMonetizationType(type) {
+	if (type === "free") return "free";
+	if (type === "subscription") return "subscription";
+	return "one_time";
+}
+//#endregion
+export { MONETIZATION_KINDS, compareAtPriceOf, fromRevenueMonetizationType, isBundleMonetization, isFreeMonetization, isMonetizationKind, isOneTimeMonetization, isSubscriptionMonetization, isUsageMonetization, monetizationKindOf, toRevenueMonetizationType, unitPriceOf };

package/dist/outbox.d.mts

@@ -158,6 +158,31 @@ declare class InvalidOutboxEventError extends Error {
  *    store is responsible for quarantining them.
  */
 interface OutboxStore {
+  /**
+   * Declares that `save` ENLISTS `options.session` in the caller's transaction,
+   * so the event row and the caller's domain write commit or roll back together.
+   *
+   * ## Why this must be declared rather than assumed
+   *
+   * `OutboxWriteOptions.session` is documented above as BEST-EFFORT — "stores may
+   * ignore fields they don't support". That is the right contract for a
+   * multi-backend interface, but it means a caller cannot infer atomicity from
+   * the mere presence of an outbox. A Redis-backed store, a store on a second
+   * Mongo connection, or one that simply drops the option will happily persist an
+   * event for a domain write that later rolls back — a GHOST event describing
+   * something that never happened. For an access-control or ledger consumer that
+   * is worse than a lost event, because downstream acts on it.
+   *
+   * Absent or `false` therefore means "assume NOT atomic". Callers that need the
+   * guarantee (see `@classytic/access`'s `atomically()`) check this flag and say
+   * so plainly at boot rather than claiming a property they cannot keep.
+   *
+   * Set `true` ONLY when `save` passes the session through to the same
+   * transactional resource the caller is writing (e.g. a mongoose model on the
+   * SAME connection). An in-memory store must NOT set it: it cannot participate
+   * in a Mongo transaction, so its write survives a rollback.
+   */
+  readonly transactionalSave?: boolean;
   /**
    * Save an event to the outbox (typically called inside a business
    * transaction). MUST reject events missing `type` or `meta.id` — throw

package/dist/proration.d.mts

@@ -0,0 +1,76 @@
+import { Money } from "./money.mjs";
+
+//#region src/money/proration.d.ts
+/**
+ * How to count days within a period.
+ *
+ * - `'whole_day'` (default) — integer calendar-day counts. Callers normalize
+ *   `periodStart`/`periodEnd`/`asOf` to business-local midnight first, so this
+ *   matches "day-of-month" proration (the Stripe default, how ~99% of SaaS
+ *   bill). `periodDays` is clamped to `>= 1`.
+ * - `'exact'` — fractional wall-clock day counts (`ms / 86_400_000`). Use when
+ *   cycles are short and a partial day must be billed precisely.
+ */
+type ProrationGranularity = 'whole_day' | 'exact';
+/** The elapsed/remaining split of a billing period at a change instant. */
+interface PeriodFraction {
+  /** Total days in the period. `>= 1` for `whole_day`; `> 0` for `exact`. */
+  readonly periodDays: number;
+  /** Days consumed as of the change instant, clamped to `[0, periodDays]`. */
+  readonly elapsedDays: number;
+  /** `periodDays - elapsedDays`. */
+  readonly remainingDays: number;
+  /** `remainingDays / periodDays`, in `[0, 1]`. */
+  readonly remainingFraction: number;
+}
+interface PeriodProgressInput {
+  /** Period start instant (business-tz-normalized by the caller). */
+  readonly periodStart: Date;
+  /** Period end instant — must be strictly after `periodStart`. */
+  readonly periodEnd: Date;
+  /** The change/quote instant. Clamped into `[periodStart, periodEnd]`. */
+  readonly asOf: Date;
+  /** Day-counting granularity. Default `'whole_day'`. */
+  readonly granularity?: ProrationGranularity;
+}
+type ProrationErrorCode = 'INVALID_PERIOD' | 'INVALID_FRACTION';
+declare class ProrationError extends Error {
+  readonly name = "ProrationError";
+  readonly code: ProrationErrorCode;
+  constructor(code: ProrationErrorCode, message: string);
+}
+/**
+ * Compute how much of a period is elapsed vs remaining at `asOf`.
+ *
+ * `asOf` before the period start ⇒ nothing elapsed (full remaining);
+ * `asOf` after the period end ⇒ fully elapsed (nothing remaining).
+ *
+ * @throws ProrationError('INVALID_PERIOD') if a date is invalid or
+ *   `periodEnd <= periodStart`.
+ */
+declare function periodProgress(input: PeriodProgressInput): PeriodFraction;
+/**
+ * Split a `Money` amount into its consumed and remaining parts across a
+ * {@link PeriodFraction}, drift-free: `consumed.amount + remaining.amount ===
+ * amount.amount` exactly (largest-remainder allocation). Sign is preserved, so
+ * a negative amount (a reversal) splits symmetrically.
+ *
+ * This is the load-bearing primitive for proration: the "unused value" a
+ * plan-change credits is `remaining`; the "already-consumed value" is
+ * `consumed`.
+ */
+declare function splitByPeriodFraction(amount: Money, fraction: PeriodFraction): {
+  readonly consumed: Money;
+  readonly remaining: Money;
+};
+/**
+ * Allocate the `fraction`-weighted part of a `Money` amount, drift-free — the
+ * complement (`1 - fraction`) is discarded but computed so rounding is exact
+ * against the whole. `fraction` must be in `[0, 1]`.
+ *
+ * @throws ProrationError('INVALID_FRACTION') if `fraction` is outside `[0, 1]`
+ *   or not finite.
+ */
+declare function allocateMoneyByFraction(amount: Money, fraction: number): Money;
+//#endregion
+export { PeriodFraction, PeriodProgressInput, ProrationError, ProrationErrorCode, ProrationGranularity, allocateMoneyByFraction, periodProgress, splitByPeriodFraction };

package/dist/proration.mjs

@@ -0,0 +1,120 @@
+import { allocate } from "./split-allocation.mjs";
+//#region src/money/proration.ts
+/**
+* Pure proration ARITHMETIC — fraction / period / allocation / rounding only.
+*
+* This module deliberately holds **no commercial policy**. It does not know
+* what "an upgrade" is, whether a discount is creditable, how tax is treated,
+* or whether a downgrade yields cash vs store credit. Those decisions live in
+* the subscription/contract kernel (`@classytic/contract`
+* `calculatePlanChangeProration(...)`), which composes these primitives.
+*
+* It is also **timezone-agnostic**: callers pass already-resolved `Date`
+* instants (normalized to the deployment's business timezone via
+* `@classytic/primitives/timezone` upstream). This module never reads a clock
+* and never applies an offset — pass instants, get numbers.
+*
+* Money is integer minor units throughout; splits use the largest-remainder
+* allocator so `consumed + remaining === amount` exactly, with no penny drift.
+*/
+const MS_PER_DAY = 864e5;
+var ProrationError = class extends Error {
+	name = "ProrationError";
+	code;
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+	}
+};
+function isValidDate(d) {
+	return d instanceof Date && !Number.isNaN(d.getTime());
+}
+/**
+* Compute how much of a period is elapsed vs remaining at `asOf`.
+*
+* `asOf` before the period start ⇒ nothing elapsed (full remaining);
+* `asOf` after the period end ⇒ fully elapsed (nothing remaining).
+*
+* @throws ProrationError('INVALID_PERIOD') if a date is invalid or
+*   `periodEnd <= periodStart`.
+*/
+function periodProgress(input) {
+	const { periodStart, periodEnd, asOf, granularity = "whole_day" } = input;
+	if (!isValidDate(periodStart) || !isValidDate(periodEnd) || !isValidDate(asOf)) throw new ProrationError("INVALID_PERIOD", "periodStart, periodEnd and asOf must be valid Dates");
+	const startMs = periodStart.getTime();
+	const endMs = periodEnd.getTime();
+	if (endMs <= startMs) throw new ProrationError("INVALID_PERIOD", `periodEnd (${periodEnd.toISOString()}) must be after periodStart (${periodStart.toISOString()})`);
+	const clampedAsOfMs = Math.min(Math.max(asOf.getTime(), startMs), endMs);
+	const rawPeriodDays = (endMs - startMs) / MS_PER_DAY;
+	const rawElapsedDays = (clampedAsOfMs - startMs) / MS_PER_DAY;
+	let periodDays;
+	let elapsedDays;
+	if (granularity === "whole_day") {
+		periodDays = Math.max(1, Math.round(rawPeriodDays));
+		elapsedDays = Math.min(periodDays, Math.max(0, Math.round(rawElapsedDays)));
+	} else {
+		periodDays = rawPeriodDays;
+		elapsedDays = Math.min(periodDays, Math.max(0, rawElapsedDays));
+	}
+	const remainingDays = periodDays - elapsedDays;
+	return {
+		periodDays,
+		elapsedDays,
+		remainingDays,
+		remainingFraction: remainingDays / periodDays
+	};
+}
+/**
+* Split a `Money` amount into its consumed and remaining parts across a
+* {@link PeriodFraction}, drift-free: `consumed.amount + remaining.amount ===
+* amount.amount` exactly (largest-remainder allocation). Sign is preserved, so
+* a negative amount (a reversal) splits symmetrically.
+*
+* This is the load-bearing primitive for proration: the "unused value" a
+* plan-change credits is `remaining`; the "already-consumed value" is
+* `consumed`.
+*/
+function splitByPeriodFraction(amount, fraction) {
+	const result = allocate(amount.amount, [{
+		id: "consumed",
+		weight: fraction.elapsedDays
+	}, {
+		id: "remaining",
+		weight: fraction.remainingDays
+	}], "by-weight");
+	const consumed = result.parts.find((p) => p.id === "consumed")?.amount ?? 0;
+	const remaining = result.parts.find((p) => p.id === "remaining")?.amount ?? 0;
+	return {
+		consumed: {
+			amount: consumed,
+			currency: amount.currency
+		},
+		remaining: {
+			amount: remaining,
+			currency: amount.currency
+		}
+	};
+}
+/**
+* Allocate the `fraction`-weighted part of a `Money` amount, drift-free — the
+* complement (`1 - fraction`) is discarded but computed so rounding is exact
+* against the whole. `fraction` must be in `[0, 1]`.
+*
+* @throws ProrationError('INVALID_FRACTION') if `fraction` is outside `[0, 1]`
+*   or not finite.
+*/
+function allocateMoneyByFraction(amount, fraction) {
+	if (!Number.isFinite(fraction) || fraction < 0 || fraction > 1) throw new ProrationError("INVALID_FRACTION", `fraction must be in [0, 1], got ${fraction}`);
+	return {
+		amount: allocate(amount.amount, [{
+			id: "part",
+			weight: fraction
+		}, {
+			id: "rest",
+			weight: 1 - fraction
+		}], "by-weight").parts.find((p) => p.id === "part")?.amount ?? 0,
+		currency: amount.currency
+	};
+}
+//#endregion
+export { ProrationError, allocateMoneyByFraction, periodProgress, splitByPeriodFraction };

package/dist/shelf-life.mjs

@@ -1,4 +1,40 @@
+import { addDays } from "./calendar.mjs";
 //#region src/scheduling/shelf-life.ts
+/**
+* Shelf-life / lot-tracking policy + pure expiry-date derivation.
+*
+* Describes whether a SKU is tracked by lot/serial, whether it carries an
+* expiration date, and the day-offsets used to derive the four lifecycle
+* dates of a freshly-received lot. The *policy* is product-level metadata
+* (owned by a catalog); the *derived dates* are per-lot facts (owned by a
+* WMS). This module is the shared contract both speak so the shape can't
+* drift between packages.
+*
+* Modeled on Odoo's `product_expiry` addon, which puts `tracking` +
+* `use_expiration_date` and four integer day-deltas on `product.template`,
+* then computes four dates on each `stock.lot`:
+*
+*   expiration = receivedAt + shelfLifeDays
+*   bestBefore = expiration − bestBeforeDays   (still safe, starts deteriorating)
+*   removal    = expiration − removalDays      (stop selling — FEFO sorts on THIS)
+*   alert      = expiration − alertDays         (raise a reminder)
+*
+* Consumed by `@classytic/catalog` (variant tracking policy) and
+* `@classytic/flow` (lot date derivation at receipt, FEFO, fresh-on-hand).
+*
+* Zero-dep, pure UTC day arithmetic — safe in unit tests with no clock.
+*
+* @example
+* const policy: ShelfLifePolicy = {
+*   mode: 'lot',
+*   useExpiration: true,
+*   shelfLifeDays: 540,   // 18-month medicine
+*   removalDays: 30,      // pull 30 days before expiry
+*   alertDays: 60,        // remind 60 days before expiry
+* };
+* deriveShelfLifeDates(new Date('2026-01-01T00:00:00Z'), policy);
+* // → { expiresAt: 2027-06-25…, removalDate: 2027-05-26…, alertDate: 2027-04-26… }
+*/
 var ShelfLifeError = class extends Error {
 	name = "ShelfLifeError";
 	code;
@@ -78,9 +114,6 @@ function shelfLifeStatus(dates, asOf) {
 	if (dates.alertDate && now >= dates.alertDate.getTime()) return "alert";
 	return "fresh";
 }
-function addDays(d, days) {
-	return new Date(d.getTime() + days * DAY_MS);
-}
 function defined(key, val) {
 	return val === void 0 ? {} : { [key]: val };
 }