@classytic/primitives 0.27.0 → 0.29.0

package/dist/idempotency.mjs

@@ -1,6 +1,10 @@
 import { canonicalDigest, canonicalJson } from "./canonical.mjs";
 //#region src/workflow/idempotency.ts
 /**
+* @deprecated Moved to `@classytic/repo-core/idempotency` — the claim contract plus its store
+* port, `runIdempotent`, the reference store and the conformance suite, beside `./lock`. This
+* copy has no consumers and is removed in the next minor.
+*
 * Idempotency claim + lease — the CONTRACT, not the store.
 *
 * ## Why this exists

package/dist/item-stock.d.mts

@@ -0,0 +1,43 @@
+import { SkuFields, StockKey, StockKeySource } from "./item-identity.mjs";
+//#region src/inventory/item-stock.d.ts
+/** One stock row as the summary reads it. */
+interface StockRow {
+  readonly quantity?: number;
+  /** Explicitly `false` deactivates the row. Absent means active. */
+  readonly isActive?: boolean;
+  /** Display cost of one unit, as the source reports it. */
+  readonly costPrice?: number;
+  /** On-hand value at the source's valuation, integer MINOR units; absent = unvalued. */
+  readonly valueMinor?: number;
+  /** Units at or below which the item reads as low (the item-level row's). */
+  readonly reorderPoint?: number;
+}
+/** What a reader shows for an item's stock in one place. */
+interface ItemStock {
+  quantity: number;
+  inStock: boolean;
+  lowStock: boolean;
+  valueMinor?: number;
+  /** Per variant LABEL — a projection of the same rows, not a second source. */
+  variants?: Array<{
+    sku: string;
+    quantity: number;
+    costPrice?: number;
+  }>;
+}
+/** The item shape the summary reads: its id and its variants. */
+interface StockableItem extends StockKeySource {
+  readonly variants?: ReadonlyArray<SkuFields & {
+    readonly sku: string;
+    readonly isActive?: boolean;
+  }> | null;
+}
+/**
+ * The item's stock. `rowOf(null)` is the item-level row (filed under the item's own id);
+ * `rowOf(key)` the row filed under one variant's stock key.
+ */
+declare function itemStockOf(item: StockableItem, rowOf: (stockKey: StockKey | null) => StockRow | undefined, options: {
+  readonly defaultReorderPoint: number;
+}): ItemStock;
+//#endregion
+export { ItemStock, StockRow, StockableItem, itemStockOf };

package/dist/item-stock.mjs

@@ -0,0 +1,67 @@
+import { stockKeyFor } from "./item-identity.mjs";
+//#region src/inventory/item-stock.ts
+/**
+* An item's stock in one place (a branch), from the rows its stock source files under stock keys —
+* the ONE summary every reader shows: the server's product reads and an offline till alike.
+*
+*   itemStockOf(product, (key) => rows.get(key ?? productId), { defaultReorderPoint: 10 })
+*
+* Rows are keyed by STOCK KEY (`stockKeyFor`), and a row reached by two lookups is counted once —
+* a sole variant's key IS the product id, so summing lookups instead of rows doubles it.
+*/
+/**
+* The item's stock. `rowOf(null)` is the item-level row (filed under the item's own id);
+* `rowOf(key)` the row filed under one variant's stock key.
+*/
+function itemStockOf(item, rowOf, options) {
+	const itemId = String(item._id);
+	const variants = item.variants ?? [];
+	const keyOf = (variant) => stockKeyFor({
+		_id: itemId,
+		variants
+	}, {
+		kind: "variant",
+		variant
+	});
+	const rows = /* @__PURE__ */ new Map();
+	const itemRow = rowOf(null);
+	if (itemRow) rows.set(itemId, itemRow);
+	for (const variant of variants) {
+		if (variant.isActive === false) continue;
+		const key = keyOf(variant);
+		const row = rowOf(key);
+		if (!row && rows.has(key)) continue;
+		rows.set(key, row);
+	}
+	let quantity = 0;
+	let valueMinor = 0;
+	for (const row of rows.values()) {
+		if (row?.isActive === false) continue;
+		const rowQuantity = row?.quantity ?? 0;
+		quantity += rowQuantity;
+		if (rowQuantity > 0) valueMinor = row?.valueMinor === void 0 || valueMinor === void 0 ? void 0 : valueMinor + row.valueMinor;
+	}
+	const variantStocks = [];
+	for (const variant of variants) {
+		if (variant.isActive === false) continue;
+		const key = keyOf(variant);
+		if (!rows.has(key)) continue;
+		const row = rows.get(key);
+		if (row?.isActive === false) continue;
+		variantStocks.push({
+			sku: variant.sku,
+			quantity: row?.quantity ?? 0,
+			...row?.costPrice !== void 0 ? { costPrice: row.costPrice } : {}
+		});
+	}
+	const reorderPoint = itemRow?.reorderPoint ?? options.defaultReorderPoint;
+	return {
+		quantity,
+		inStock: quantity > 0,
+		lowStock: quantity > 0 && quantity <= reorderPoint,
+		...quantity > 0 && valueMinor !== void 0 ? { valueMinor } : {},
+		...variantStocks.length ? { variants: variantStocks } : {}
+	};
+}
+//#endregion
+export { itemStockOf };

package/dist/legal-form.d.mts

@@ -0,0 +1,12 @@
+//#region src/identity/legal-form.d.ts
+/**
+ * The legal form of a person or entity — what the law treats it as, for the reporting company and its
+ * counterparties alike. A sole proprietorship is an `individual`: the business has no legal personality
+ * of its own. Country packs decide what follows from a form (equity accounts, the year-end close, tax).
+ */
+declare const LEGAL_FORMS: readonly ["individual", "partnership", "company", "cooperative", "nonprofit", "government"];
+type LegalForm = (typeof LEGAL_FORMS)[number];
+declare const LEGAL_FORM_LABELS: Readonly<Record<LegalForm, string>>;
+declare function isLegalForm(value: unknown): value is LegalForm;
+//#endregion
+export { LEGAL_FORMS, LEGAL_FORM_LABELS, LegalForm, isLegalForm };

package/dist/legal-form.mjs

@@ -0,0 +1,27 @@
+//#region src/identity/legal-form.ts
+/**
+* The legal form of a person or entity — what the law treats it as, for the reporting company and its
+* counterparties alike. A sole proprietorship is an `individual`: the business has no legal personality
+* of its own. Country packs decide what follows from a form (equity accounts, the year-end close, tax).
+*/
+const LEGAL_FORMS = [
+	"individual",
+	"partnership",
+	"company",
+	"cooperative",
+	"nonprofit",
+	"government"
+];
+const LEGAL_FORM_LABELS = {
+	individual: "Individual / sole proprietorship",
+	partnership: "Partnership firm",
+	company: "Company",
+	cooperative: "Cooperative society",
+	nonprofit: "Nonprofit / NGO / trust",
+	government: "Government body"
+};
+function isLegalForm(value) {
+	return typeof value === "string" && LEGAL_FORMS.includes(value);
+}
+//#endregion
+export { LEGAL_FORMS, LEGAL_FORM_LABELS, isLegalForm };

package/dist/line-settlement.d.mts

@@ -0,0 +1,70 @@
+import { Result } from "./result.mjs";
+//#region src/inventory/line-settlement.d.ts
+/**
+ * A document line's quantity, split into OUTCOME buckets — the one definition
+ * of "how much of this line is still open".
+ *
+ * Every kernel that moves goods against a document asks this: an order line is
+ * fulfilled / returned / canceled, a transfer line is received / returned /
+ * written off, a purchase line is received / rejected. The buckets are the
+ * kernel's vocabulary; the arithmetic, the over-settlement guard and the state
+ * derivation are this file's, so no two kernels can answer differently.
+ *
+ * Quantities are whole units. A bucket that is absent counts as zero.
+ */
+interface SettlementLine<B extends string> {
+  /** What the line promised to move. */
+  readonly quantity: number;
+  /** What has been settled so far, per outcome. */
+  readonly settled: Readonly<Partial<Record<B, number>>>;
+}
+type SettlementState = "open" | "partial" | "settled";
+/** Sum of every bucket. */
+declare const settledTotal: <B extends string>(line: SettlementLine<B>) => number;
+/**
+ * `quantity − Σ buckets`. NOT clamped at zero: a negative means the line was
+ * over-settled by data written outside {@link planSettlement}, and hiding it
+ * would erase the only signal that happened.
+ */
+declare const outstandingOf: <B extends string>(line: SettlementLine<B>) => number;
+/** `open` — nothing settled; `settled` — nothing outstanding; otherwise `partial`. */
+declare const settlementState: <B extends string>(line: SettlementLine<B>) => SettlementState;
+/** Every line settled ⇒ `settled`; every line untouched ⇒ `open`; else `partial`. */
+declare const documentSettlementState: <B extends string>(lines: ReadonlyArray<SettlementLine<B>>) => SettlementState;
+/** `true` when every line is settled entirely through `bucket` (e.g. all received, nothing lost). */
+declare const settledEntirelyIn: <B extends string>(lines: ReadonlyArray<SettlementLine<B>>, bucket: B) => boolean;
+type SettlementRefusal = {
+  readonly code: "not_positive_integer";
+  readonly requested: number;
+} | {
+  readonly code: "exceeds_outstanding";
+  readonly requested: number;
+  readonly outstanding: number;
+};
+/**
+ * Settle `quantity` more units into `bucket`, or refuse.
+ *
+ * Refuses a non-positive or fractional quantity and anything above what is
+ * outstanding — an over-settlement is an input error, never silently trimmed.
+ * Use {@link clampSettlement} only where the surface's CONTRACT is "take what fits".
+ */
+declare const planSettlement: <B extends string>(line: SettlementLine<B>, bucket: B, quantity: number) => Result<SettlementLine<B>, SettlementRefusal>;
+/**
+ * Settle up to `requested` units into `bucket`, taking only what is outstanding.
+ * `applied` is what was actually settled; `0` leaves the line unchanged.
+ */
+declare const clampSettlement: <B extends string>(line: SettlementLine<B>, bucket: B, requested: number) => {
+  readonly line: SettlementLine<B>;
+  readonly applied: number;
+};
+/**
+ * The share of a line-level amount (a value or a cost, integer MINOR units) owed by one
+ * settlement batch, given how many units the whole line had settled before and after it.
+ *
+ * `floor(total·after/q) − floor(total·before/q)` TELESCOPES: however a line is split into
+ * batches, and across every outcome bucket, the shares sum to exactly `total` once the line
+ * is fully settled — no remainder to chase, no batch-order dependence.
+ */
+declare const shareOfSettled: (total: number, quantity: number, settledBefore: number, settledAfter: number) => number;
+//#endregion
+export { SettlementLine, SettlementRefusal, SettlementState, clampSettlement, documentSettlementState, outstandingOf, planSettlement, settledEntirelyIn, settledTotal, settlementState, shareOfSettled };

package/dist/line-settlement.mjs

@@ -0,0 +1,79 @@
+import { err, ok } from "./result.mjs";
+//#region src/inventory/line-settlement.ts
+/** Sum of every bucket. */
+const settledTotal = (line) => Object.values(line.settled).reduce((sum, n) => sum + (n ?? 0), 0);
+/**
+* `quantity − Σ buckets`. NOT clamped at zero: a negative means the line was
+* over-settled by data written outside {@link planSettlement}, and hiding it
+* would erase the only signal that happened.
+*/
+const outstandingOf = (line) => line.quantity - settledTotal(line);
+/** `open` — nothing settled; `settled` — nothing outstanding; otherwise `partial`. */
+const settlementState = (line) => {
+	if (outstandingOf(line) <= 0) return "settled";
+	return settledTotal(line) === 0 ? "open" : "partial";
+};
+/** Every line settled ⇒ `settled`; every line untouched ⇒ `open`; else `partial`. */
+const documentSettlementState = (lines) => {
+	const states = lines.map(settlementState);
+	if (states.every((s) => s === "settled")) return "settled";
+	if (states.every((s) => s === "open")) return "open";
+	return "partial";
+};
+/** `true` when every line is settled entirely through `bucket` (e.g. all received, nothing lost). */
+const settledEntirelyIn = (lines, bucket) => lines.every((l) => (l.settled[bucket] ?? 0) >= l.quantity);
+/**
+* Settle `quantity` more units into `bucket`, or refuse.
+*
+* Refuses a non-positive or fractional quantity and anything above what is
+* outstanding — an over-settlement is an input error, never silently trimmed.
+* Use {@link clampSettlement} only where the surface's CONTRACT is "take what fits".
+*/
+const planSettlement = (line, bucket, quantity) => {
+	if (!Number.isInteger(quantity) || quantity <= 0) return err({
+		code: "not_positive_integer",
+		requested: quantity
+	});
+	const outstanding = outstandingOf(line);
+	if (quantity > outstanding) return err({
+		code: "exceeds_outstanding",
+		requested: quantity,
+		outstanding
+	});
+	return ok(withBucket(line, bucket, quantity));
+};
+/**
+* Settle up to `requested` units into `bucket`, taking only what is outstanding.
+* `applied` is what was actually settled; `0` leaves the line unchanged.
+*/
+const clampSettlement = (line, bucket, requested) => {
+	const applied = Math.max(0, Math.min(Math.trunc(requested), outstandingOf(line)));
+	return {
+		line: applied > 0 ? withBucket(line, bucket, applied) : line,
+		applied
+	};
+};
+/**
+* The share of a line-level amount (a value or a cost, integer MINOR units) owed by one
+* settlement batch, given how many units the whole line had settled before and after it.
+*
+* `floor(total·after/q) − floor(total·before/q)` TELESCOPES: however a line is split into
+* batches, and across every outcome bucket, the shares sum to exactly `total` once the line
+* is fully settled — no remainder to chase, no batch-order dependence.
+*/
+const shareOfSettled = (total, quantity, settledBefore, settledAfter) => {
+	if (!Number.isInteger(total) || total < 0) throw new RangeError(`total must be a non-negative integer, got ${total}`);
+	if (!Number.isInteger(quantity) || quantity <= 0) throw new RangeError(`quantity must be a positive integer, got ${quantity}`);
+	if (!(0 <= settledBefore && settledBefore <= settledAfter && settledAfter <= quantity)) throw new RangeError(`need 0 <= before (${settledBefore}) <= after (${settledAfter}) <= quantity (${quantity})`);
+	const at = (n) => Number(BigInt(total) * BigInt(n) / BigInt(quantity));
+	return at(settledAfter) - at(settledBefore);
+};
+const withBucket = (line, bucket, quantity) => ({
+	quantity: line.quantity,
+	settled: {
+		...line.settled,
+		[bucket]: (line.settled[bucket] ?? 0) + quantity
+	}
+});
+//#endregion
+export { clampSettlement, documentSettlementState, outstandingOf, planSettlement, settledEntirelyIn, settledTotal, settlementState, shareOfSettled };

package/dist/memory-outbox.mjs

@@ -74,7 +74,8 @@ var MemoryOutboxStore = class {
 			entry.fenceToken = (entry.fenceToken ?? 0) + 1;
 			claimed.push({
 				event: entry.event,
-				fencingToken: entry.fenceToken
+				fencingToken: entry.fenceToken,
+				attempts: entry.attempts
 			});
 		}
 		return claimed;

package/dist/monetization.d.mts

@@ -1,4 +1,4 @@
-import { n as Money } from "./money-CfAvfNiM.mjs";
+import { n as Money } from "./money-C9iLWiWR.mjs";
 //#region src/money/monetization.d.ts
 /**
  * A map of currency code → {@link Money} for explicit per-currency pricing.
@@ -17,8 +17,11 @@ type MoneyByCurrency = Record<string, Money>;
  *   - `bundle`       — a composite priced from its members.
  *   - `usage`        — metered / per-seat / consumption (billed per unit or in
  *                      arrears). The extension point for rating models.
+ *   - `pass`         — paid once, grants a TERM, never renews (a course access
+ *                      pass, a gym or transit pass, a parking or day pass, a
+ *                      term licence). See {@link PassMonetization}.
  */
-declare const MONETIZATION_KINDS: readonly ["free", "one_time", "subscription", "bundle", "usage"];
+declare const MONETIZATION_KINDS: readonly ["free", "one_time", "subscription", "bundle", "usage", "pass"];
 type MonetizationKind = (typeof MONETIZATION_KINDS)[number];
 /** True when `value` is one of the canonical kinds. */
 declare function isMonetizationKind(value: unknown): value is MonetizationKind;
@@ -103,6 +106,31 @@ interface SubscriptionPlan {
   /** Optional auto-calculated discount vs the highest-frequency plan. */
   readonly discount?: number;
 }
+/**
+ * One buyable term: a price that grants access for a fixed span.
+ *
+ * Shaped like {@link SubscriptionPlan} on purpose (same `duration` +
+ * `durationUnit` vocabulary, so a term means the same thing everywhere) and
+ * kept separate on purpose: a plan carries `trialDays` and a renewal discount,
+ * which are recurring-billing concepts a pass has none of. Reusing the plan
+ * would re-blur the very line this kind exists to draw.
+ */
+interface AccessPass {
+  /** Internal key ('pass-30d', 'season', 'day'). Stable across edits. */
+  readonly key: string;
+  /** Display label ("1 month", "Season pass", "Day pass"). */
+  readonly label: string;
+  /** Price for this term in the default currency. */
+  readonly price: Money;
+  /** Explicit per-currency overrides. */
+  readonly priceByCurrency?: MoneyByCurrency;
+  /** Optional strikethrough / "was" price for this term. */
+  readonly compareAtPrice?: Money;
+  /** Length of access this term buys. */
+  readonly duration: number;
+  /** Unit of that length. */
+  readonly durationUnit: DurationUnit;
+}
 /**
  * One band of a metered rate table.
  *
@@ -180,17 +208,63 @@ interface UsageMonetization {
     readonly durationUnit: DurationUnit;
   };
 }
+/**
+ * Paid once, grants a TERM, never renews.
+ *
+ * The gap this closes: `one_time` prices a thing but says nothing about how
+ * long it is yours, and `subscription` prices a term but means it RECURS. A
+ * prepaid term fits neither, so hosts selling one reached for `subscription`
+ * and then had to explain, wherever the value was read, that it does not
+ * actually renew — a classification that needs a comment to be understood has
+ * already failed, and `toRevenueMonetizationType` would have settled those
+ * sales as subscriptions in the ledger.
+ *
+ * Buying again EXTENDS rather than renewing: nothing schedules a charge, the
+ * buyer chooses when (or whether) to pay for the next term. A perpetual sale
+ * is `one_time`, not a pass with an enormous duration: "forever" is the
+ * absence of a term, not a long one.
+ */
+interface PassMonetization {
+  readonly type: 'pass';
+  /** At least one term. Several means the buyer picks (1 month / 1 year). */
+  readonly passes: readonly AccessPass[];
+}
 /**
  * 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;
+type Monetization = FreeMonetization | OneTimeMonetization | SubscriptionMonetization | BundleMonetization | UsageMonetization | PassMonetization;
 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;
+declare const isPassMonetization: (m: Monetization) => m is PassMonetization;
+/**
+ * A term's length in APPROXIMATE days, for ORDERING AND LABELS ONLY.
+ *
+ * A month is 30 here and a year 365, which is wrong as a date and right as a
+ * comparison: it answers "is this term longer than that one" and "call this
+ * one '6 months'", both of which only need a stable ranking.
+ *
+ * NEVER compute an expiry from it. A term that ENDS on a date must be added
+ * with calendar arithmetic (`addMonths` / `addYears`), or February and leap
+ * years quietly short-change the buyer. That belongs to the host's date
+ * library, not to a pure money value object.
+ */
+declare function approxTermDays(duration: number, unit: DurationUnit): number;
+/**
+ * The term a storefront leads with: the CHEAPEST, ties broken by the shortest
+ * span so the answer is deterministic whatever order the passes were authored
+ * in. One definition, because a card reading the cheapest while a checkout
+ * defaulted to the first is the divergence {@link unitPriceOf} exists to stop.
+ *
+ * The tie-break compares SPANS, not the raw `duration`: "1 year" and "1 month"
+ * are both `duration: 1`, so a number-only comparison ranks them by whichever
+ * happened to be authored first.
+ */
+declare function defaultPassOf(m: PassMonetization): AccessPass | null;
 /** The kind of a monetization value (its discriminant, narrowed to the union). */
 declare const monetizationKindOf: (m: Monetization) => MonetizationKind;
 /**
@@ -205,6 +279,8 @@ declare const monetizationKindOf: (m: Monetization) => MonetizationKind;
  *   - `bundle`       → the FIXED bundle price; `null` in `dynamic` mode (that
  *                      price is computed from the members, not stored here)
  *   - `free`         → `null`
+ *   - `pass`         → the cheapest term's price (the "from" price a
+ *                      storefront leads with), see {@link defaultPassOf}
  *   - `usage`        → `null` — a metered item has no single unit price; it is
  *                      rated per consumption via {@link UsageRating}
  *
@@ -212,7 +288,14 @@ declare const monetizationKindOf: (m: Monetization) => MonetizationKind;
  * 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`). */
+/**
+ * The strikethrough / MSRP price, for the kinds that carry one.
+ *
+ * Always paired with whatever {@link unitPriceOf} returned, so a card can
+ * never strike through the "was" of one term beside the price of another:
+ * `one_time` compares against its base price, `pass` against the term
+ * `defaultPassOf` picked.
+ */
 declare function compareAtPriceOf(m: Monetization): Money | null;
 /**
  * `@classytic/revenue`'s coarse wire enum. `purchase` is the paid-once case that
@@ -224,10 +307,13 @@ 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").
+ * (one_time, bundle, a usage charge and a pass are all "a purchase
+ * happened"). A `pass` in particular must NOT land on `subscription`: nothing
+ * schedules a renewal, and a ledger that thinks otherwise forecasts revenue
+ * that will never be billed.
  */
 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, UPFRONT_COLLECTION_MODES, UpfrontCollectionMode, UsageMonetization, UsageRating, UsageTier, compareAtPriceOf, fromRevenueMonetizationType, isBundleMonetization, isFreeMonetization, isMonetizationKind, isOneTimeMonetization, isSubscriptionMonetization, isUpfrontCollectionMode, isUsageMonetization, monetizationKindOf, toRevenueMonetizationType, unitPriceOf };
+export { AccessPass, BundleMonetization, DurationUnit, FreeMonetization, MONETIZATION_KINDS, Monetization, MonetizationKind, MoneyByCurrency, OneTimeMonetization, OneTimePricing, PassMonetization, PriceTier, RevenueMonetizationType, SubscriptionMonetization, SubscriptionPlan, UPFRONT_COLLECTION_MODES, UpfrontCollectionMode, UsageMonetization, UsageRating, UsageTier, approxTermDays, compareAtPriceOf, defaultPassOf, fromRevenueMonetizationType, isBundleMonetization, isFreeMonetization, isMonetizationKind, isOneTimeMonetization, isPassMonetization, isSubscriptionMonetization, isUpfrontCollectionMode, isUsageMonetization, monetizationKindOf, toRevenueMonetizationType, unitPriceOf };

package/dist/monetization.mjs

@@ -8,13 +8,17 @@
 *   - `bundle`       — a composite priced from its members.
 *   - `usage`        — metered / per-seat / consumption (billed per unit or in
 *                      arrears). The extension point for rating models.
+*   - `pass`         — paid once, grants a TERM, never renews (a course access
+*                      pass, a gym or transit pass, a parking or day pass, a
+*                      term licence). See {@link PassMonetization}.
 */
 const MONETIZATION_KINDS = [
 	"free",
 	"one_time",
 	"subscription",
 	"bundle",
-	"usage"
+	"usage",
+	"pass"
 ];
 const MONETIZATION_KIND_SET = new Set(MONETIZATION_KINDS);
 /** True when `value` is one of the canonical kinds. */
@@ -71,6 +75,50 @@ 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";
+const isPassMonetization = (m) => m.type === "pass";
+const APPROX_DAYS_PER_UNIT = {
+	day: 1,
+	week: 7,
+	month: 30,
+	year: 365
+};
+/**
+* A term's length in APPROXIMATE days, for ORDERING AND LABELS ONLY.
+*
+* A month is 30 here and a year 365, which is wrong as a date and right as a
+* comparison: it answers "is this term longer than that one" and "call this
+* one '6 months'", both of which only need a stable ranking.
+*
+* NEVER compute an expiry from it. A term that ENDS on a date must be added
+* with calendar arithmetic (`addMonths` / `addYears`), or February and leap
+* years quietly short-change the buyer. That belongs to the host's date
+* library, not to a pure money value object.
+*/
+function approxTermDays(duration, unit) {
+	return duration * APPROX_DAYS_PER_UNIT[unit];
+}
+/**
+* The term a storefront leads with: the CHEAPEST, ties broken by the shortest
+* span so the answer is deterministic whatever order the passes were authored
+* in. One definition, because a card reading the cheapest while a checkout
+* defaulted to the first is the divergence {@link unitPriceOf} exists to stop.
+*
+* The tie-break compares SPANS, not the raw `duration`: "1 year" and "1 month"
+* are both `duration: 1`, so a number-only comparison ranks them by whichever
+* happened to be authored first.
+*/
+function defaultPassOf(m) {
+	let best = null;
+	let bestSpan = Number.POSITIVE_INFINITY;
+	for (const pass of m.passes) {
+		const span = approxTermDays(pass.duration, pass.durationUnit);
+		if (best === null || pass.price.amount < best.price.amount || pass.price.amount === best.price.amount && span < bestSpan) {
+			best = pass;
+			bestSpan = span;
+		}
+	}
+	return best;
+}
 /** The kind of a monetization value (its discriminant, narrowed to the union). */
 const monetizationKindOf = (m) => m.type;
 /**
@@ -85,6 +133,8 @@ const monetizationKindOf = (m) => m.type;
 *   - `bundle`       → the FIXED bundle price; `null` in `dynamic` mode (that
 *                      price is computed from the members, not stored here)
 *   - `free`         → `null`
+*   - `pass`         → the cheapest term's price (the "from" price a
+*                      storefront leads with), see {@link defaultPassOf}
 *   - `usage`        → `null` — a metered item has no single unit price; it is
 *                      rated per consumption via {@link UsageRating}
 *
@@ -96,18 +146,31 @@ function unitPriceOf(m) {
 		case "one_time": return m.pricing.basePrice;
 		case "subscription": return m.plans[0]?.price ?? null;
 		case "bundle": return m.basePrice ?? null;
+		case "pass": return defaultPassOf(m)?.price ?? null;
 		case "free":
 		case "usage": return null;
 	}
 }
-/** The strikethrough / MSRP price, if the kind carries one (only `one_time`). */
+/**
+* The strikethrough / MSRP price, for the kinds that carry one.
+*
+* Always paired with whatever {@link unitPriceOf} returned, so a card can
+* never strike through the "was" of one term beside the price of another:
+* `one_time` compares against its base price, `pass` against the term
+* `defaultPassOf` picked.
+*/
 function compareAtPriceOf(m) {
-	return m.type === "one_time" ? m.pricing.compareAtPrice ?? null : null;
+	if (m.type === "one_time") return m.pricing.compareAtPrice ?? null;
+	if (m.type === "pass") return defaultPassOf(m)?.compareAtPrice ?? null;
+	return 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").
+* (one_time, bundle, a usage charge and a pass are all "a purchase
+* happened"). A `pass` in particular must NOT land on `subscription`: nothing
+* schedules a renewal, and a ledger that thinks otherwise forecasts revenue
+* that will never be billed.
 */
 function toRevenueMonetizationType(kind) {
 	if (kind === "free") return "free";
@@ -121,4 +184,4 @@ function fromRevenueMonetizationType(type) {
 	return "one_time";
 }
 //#endregion
-export { MONETIZATION_KINDS, UPFRONT_COLLECTION_MODES, compareAtPriceOf, fromRevenueMonetizationType, isBundleMonetization, isFreeMonetization, isMonetizationKind, isOneTimeMonetization, isSubscriptionMonetization, isUpfrontCollectionMode, isUsageMonetization, monetizationKindOf, toRevenueMonetizationType, unitPriceOf };
+export { MONETIZATION_KINDS, UPFRONT_COLLECTION_MODES, approxTermDays, compareAtPriceOf, defaultPassOf, fromRevenueMonetizationType, isBundleMonetization, isFreeMonetization, isMonetizationKind, isOneTimeMonetization, isPassMonetization, isSubscriptionMonetization, isUpfrontCollectionMode, isUsageMonetization, monetizationKindOf, toRevenueMonetizationType, unitPriceOf };