@classytic/primitives 0.24.0 → 0.26.0

package/CHANGELOG.md

@@ -3,6 +3,29 @@
 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.26.0] — 2026-08-27
+
+### Added
+
+- **`./deadline` subpath** — `Deadline` value type + helpers for date-bounded
+  obligations (reservations, SLA windows, contract terms).
+- **`./stock-level` subpath** — canonical stock-level representation and helpers.
+- **`./item-facts` subpath** — cross-kernel item fact contract (weight, dimensions,
+  hazmat flags) that catalog declares and logistics/inventory reads.
+- **`StockKey` branded type** (`./item-identity`) — prevents a bare merchandising
+  label or ObjectId being passed where a quant key is expected; the only source is
+  `stockKeyOf()` / `requireStockKey()`. Return types of both functions updated.
+- **Upfront collection policy** (`./monetization`) — `UpfrontCollectionPolicy`
+  (`'full_payment' | 'deposit' | 'deferred'`) + `UPFRONT_COLLECTION_POLICIES`
+  const. Cross-kernel: catalog declares the policy, order turns it into tenders,
+  revenue settles them.
+
+## [0.25.0] - 2026-08-24
+
+### Added
+
+- **`@classytic/primitives/item-identity` subpath** — `SkuFields`, `stockKeyOf`, `skuDisplay`. `sku` is a label; `skuRef` is the stock identity — the two fall back in opposite directions and getting one backwards type-checks while returning a plausible wrong string. `stockKeyOf` resolves `skuRef ?? sku ?? fallback` (the key to reserve, decrement and post against); `skuDisplay` resolves `skuLabel ?? sku ?? skuRef` (what a human reads). Canonicalises the per-package `variantSku || String(productId)` derivations into one place.
+
 ## [0.24.0] - 2026-08-24
 
 ### Added — `@classytic/primitives/address`: capture-format system

package/README.md

@@ -1,160 +1,160 @@
-# @classytic/primitives
-
-[![Sponsor](https://img.shields.io/github/sponsors/classytic?style=flat-square&label=Sponsor&logo=GitHub&color=EA4AAA)](https://github.com/sponsors/classytic)
-
-Framework-agnostic TypeScript primitives shared across Classytic packages.
-Zero runtime dependencies. ESM only. Node 22+.
-
-These are the building blocks every Classytic package speaks in common:
-`Money`, `DomainEvent`, `OperationContext`, polymorphic references. When a
-package duplicates one of these shapes, it drifts — this package exists so it
-doesn't.
-
-> **Canonical-contract relocations in 0.3.0.** Three modules moved out to
-> `@classytic/repo-core` so kits and arc see one source of truth instead of
-> two:
-> - **Pagination** (`OffsetPaginationResult`, `KeysetPaginationResult`,
->   `AggregatePaginationResult`, `PaginationResult`, `toCanonicalList()`) →
->   `@classytic/repo-core/pagination`.
-> - **Tenant config** (`TenantConfig`, `TenantStrategy`, `TenantFieldType`,
->   `resolveTenantConfig`, `DEFAULT_TENANT_CONFIG`, `ResolvedTenantConfig`) →
->   `@classytic/repo-core/tenant`. Mongokit and sqlitekit's
->   `MultiTenantOptions extends Pick<TenantConfig, ...>`.
-> - **Error contracts** (`HttpError` throwable, `ErrorContract` wire shape,
->   `ErrorDetail`, `ErrorCode`, `ERROR_CODES`, `toErrorContract()`,
->   `statusToErrorCode()`) → `@classytic/repo-core/errors`.
->   `ArcError implements HttpError`.
->
-> Events stay here. `@classytic/primitives/events` remains the canonical
-> source for `EventMeta`, `DomainEvent`, `EventHandler`, `EventLogger`,
-> `EventTransport`, `DeadLetteredEvent`, `PublishManyResult`, `createEvent`,
-> `createChildEvent`, `matchEventPattern`. Arc 2.12 re-exports only the
-> runtime `MemoryEventTransport`.
-
-## Install
-
-```bash
-npm install @classytic/primitives
-```
-
-## Use
-
-Prefer **subpath imports** — each concern is its own entry point, types erase
-at compile time, runtime helpers are tiny.
-
-```ts
-import { addMoney, fromMajor, type Money } from '@classytic/primitives/money';
-import { createEvent, type DomainEvent, type EventTransport } from '@classytic/primitives/events';
-import type { OperationContext } from '@classytic/primitives/context';
-import { allocate, type SplitResult } from '@classytic/primitives/split-allocation';
-// Tenant config, error contracts, and pagination now live in repo-core:
-import { resolveTenantConfig, type TenantConfig } from '@classytic/repo-core/tenant';
-import type { HttpError, ErrorContract } from '@classytic/repo-core/errors';
-import type {
-  OffsetPaginationResult, KeysetPaginationResult, AggregatePaginationResult,
-} from '@classytic/repo-core/pagination';
-```
-
-There is intentionally **no root barrel** — a barrel forces the Node ESM
-loader and TypeScript compiler to walk every module on a single convenience
-import, which slows CI and pulls unused code into the consumer's graph. Use
-subpath imports only.
-
-## What's inside
-
-| Subpath | Ships |
-|---|---|
-| `/money` | `Money`, `fromMajor`, `toMajor`, `addMoney`, `subtractMoney`, `multiplyMoney`, `sumMoney`, `equalsMoney`, `compareMoney`, `negateMoney`, `absMoney`, `isMoney`, `CurrencyMismatchError` |
-| `/currency` | `CurrencyCode` brand, `CURRENCIES`, `MINOR_UNIT_FACTOR`, `minorUnitFactor`, `isKnownCurrency`, `toCurrencyCode`, `currencyCode`, `isCurrencyCode`, `InvalidCurrencyCodeError`, `CurrencyMismatchError`, `FxSnapshot`, `convertWithSnapshot`, `reverseWithSnapshot`, `FxRounding` |
-| `/address` | `Address`, `ContactAddress`, `GeoPoint`, `GeoJsonPoint`, `toGeoJsonPoint`, `fromGeoJsonPoint` |
-| `/period` | `DateRange`, `Period`, `isDateRange`, `isWithin`, `rangeDurationMs`, `rangesOverlap`, `DateRangeError` — **plus timezone-aware resolution**: `resolvePeriod`, `resolveDay`, `resolveMonth`, `resolveQuarter`, `resolveYear`, `resolveDateSpan`, `dayStart`, `periodOf`, `parsePeriod`, `formatPeriod`, `granularityOf`, `periodTimeZone`, `inclusiveEnd`, `PeriodError` |
-| `/reference` | `ExternalRef`, `ObjectIdLike`, `IdLike`, `DocumentRef`, `idToString`, `isExternalRef` |
-| `/context` | `OperationContext`, `ActorRef` |
-| `/events` | `DomainEvent`, `EventMeta`, `EventHandler`, `EventLogger`, `EventTransport`, `DeadLetteredEvent`, `PublishManyResult`, `createEvent`, `createChildEvent`, `matchEventPattern` |
-| `/result` | `Result<T, E>`, `ok`, `err`, `isOk`, `isErr`, `mapResult`, `mapError`, `unwrap` |
-| `/brand` | `Brand<T, B>`, `Prettify`, `DeepPartial`, `DeepReadonly`, `RequireKeys`, `OptionalKeys`, `Nullable`, `KeysMatching`, `NonEmptyArray` |
-| `/split-allocation` | `allocate`, `isBalanced`, `SplitAllocationError`, `SplitMethod`, `SplitSubject`, `SplitPart`, `SplitResult` |
-| `/idempotency` | `decideClaim`, `completeClaim`, `renewLease`, `identityKey`, `sameIdentity`, `fingerprintRequest`, `newLeaseToken`, `isLeaseExpired`, `holdsLease`, `isInFlight`, `DEFAULT_LEASE_MS`, `IdempotencyClaim`, `ClaimOutcome`, `ClaimResult`, `ClaimState`, `IdempotencyIdentity`, `IdempotencyError` |
-| `/approval` | `createChain`, `applyDecision`, `skipStep`, `nextPendingStep`, `pendingSteps`, `isApproved`, `assertApproved`, `assertApprovedIfPresent`, `isRejected`, `isPending`, `decisionCount`, `ApprovalError`, `ApprovalChain`, `ApprovalStep`, `ApprovalDecision`, `Approver`, `ApprovalThreshold` |
-| `/cadence` | `nextOccurrence`, `occurrencesBetween`, `validateCadence`, `CadenceError`, `Cadence`, `DailyCadence`, `WeeklyCadence`, `MonthlyCadence`, `YearlyCadence`, `CronCadence`, `IsoWeekday` |
-| `/hold` | `addHold`, `resolveHold`, `activeHolds`, `resolvedHolds`, `isOnHold`, `hasActiveHoldOfCode`, `HoldError`, `HoldReason`, `HoldActor` |
-| `/sla` | `breachedAt`, `remainingMs`, `elapsedMs`, `isBreached`, `consumedFraction`, `validateSLA`, `SLAError`, `SLA`, `BreachPolicy` |
-
-## Design
-
-### Money — integer minor units, always
-
-```ts
-import { fromMajor, addMoney, toMajor } from '@classytic/primitives/money';
-
-const subtotal = fromMajor(19.99, 'USD');     // { amount: 1999, currency: 'USD' }
-const shipping = fromMajor(5.00,  'USD');     // { amount: 500,  currency: 'USD' }
-const total    = addMoney(subtotal, shipping); // { amount: 2499, currency: 'USD' }
-toMajor(total);                                // 24.99
-```
-
-`Money.amount` is always an integer in the currency's minor unit — `1` = one
-cent for USD, one yen for JPY, one fils for KWD. Mixing currencies throws
-`CurrencyMismatchError`. This eliminates the float-rounding drift that happens
-when every package rolls its own `{ amount: number, currency: string }`.
-
-### DomainEvent — structurally identical to Arc
-
-```ts
-import { createEvent, type EventTransport } from '@classytic/primitives/events';
-
-const event = createEvent('order:placed', { orderId: 'ord_123' }, {
-  organizationId: ctx.organizationId,
-  userId: ctx.actorId,
-  correlationId: ctx.correlationId,
-});
-
-await transport.publish(event);
-```
-
-Shape matches `@classytic/arc`'s `DomainEvent` exactly — any Arc transport
-(memory, Redis pub/sub, Redis Streams, Kafka) plugs into a package expecting
-this interface without adapters. See PACKAGE_RULES.md §11.
-
-### TenantConfig — moved to `@classytic/repo-core/tenant`
-
-```ts
-import { resolveTenantConfig } from '@classytic/repo-core/tenant';
-
-const tenant = resolveTenantConfig(config.tenant);
-// { enabled: true, tenantField: 'organizationId', fieldType: 'objectId',
-//   ref: 'organization', contextKey: 'organizationId', required: true }
-```
-
-Mongokit's `MultiTenantOptions` and sqlitekit's equivalent both
-`extends Pick<TenantConfig, ...>` from repo-core — pass the resolved config
-straight into `multiTenantPlugin(resolved)`.
-
-### ExternalRef — polymorphic, framework-free
-
-```ts
-interface ExternalRef {
-  sourceId: string;
-  sourceModel: string;
-}
-```
-
-For references that cross trust boundaries (another package, another service,
-Stripe, Postgres) — paired with a host-implemented `SourceBridge`. Works for
-ObjectId, UUID, Stripe ID, anything. See PACKAGE_RULES.md §7.
-
-## What's not here (on purpose)
-
-- **Mongoose types** — use `ObjectIdLike` from `/reference`. Any Mongoose
-  `Types.ObjectId` satisfies it structurally.
-- **Transaction / Order / Cart shapes** — those are domain types, not
-  primitives. They live in their respective packages.
-- **Error subclasses** — throw plain `Error`s; hosts serialize them into
-  `ErrorContract` (from `@classytic/repo-core/errors`) at the HTTP boundary
-  via `toErrorContract(err)`.
-- **Runtime currency database** — ship a whitelist at the app layer if you
-  need one. `MINOR_UNIT_FACTOR` covers common cases.
-
-## License
-
-MIT © Classytic
+# @classytic/primitives
+
+[![Sponsor](https://img.shields.io/github/sponsors/classytic?style=flat-square&label=Sponsor&logo=GitHub&color=EA4AAA)](https://github.com/sponsors/classytic)
+
+Framework-agnostic TypeScript primitives shared across Classytic packages.
+Zero runtime dependencies. ESM only. Node 22+.
+
+These are the building blocks every Classytic package speaks in common:
+`Money`, `DomainEvent`, `OperationContext`, polymorphic references. When a
+package duplicates one of these shapes, it drifts — this package exists so it
+doesn't.
+
+> **Canonical-contract relocations in 0.3.0.** Three modules moved out to
+> `@classytic/repo-core` so kits and arc see one source of truth instead of
+> two:
+> - **Pagination** (`OffsetPaginationResult`, `KeysetPaginationResult`,
+>   `AggregatePaginationResult`, `PaginationResult`, `toCanonicalList()`) →
+>   `@classytic/repo-core/pagination`.
+> - **Tenant config** (`TenantConfig`, `TenantStrategy`, `TenantFieldType`,
+>   `resolveTenantConfig`, `DEFAULT_TENANT_CONFIG`, `ResolvedTenantConfig`) →
+>   `@classytic/repo-core/tenant`. Mongokit and sqlitekit's
+>   `MultiTenantOptions extends Pick<TenantConfig, ...>`.
+> - **Error contracts** (`HttpError` throwable, `ErrorContract` wire shape,
+>   `ErrorDetail`, `ErrorCode`, `ERROR_CODES`, `toErrorContract()`,
+>   `statusToErrorCode()`) → `@classytic/repo-core/errors`.
+>   `ArcError implements HttpError`.
+>
+> Events stay here. `@classytic/primitives/events` remains the canonical
+> source for `EventMeta`, `DomainEvent`, `EventHandler`, `EventLogger`,
+> `EventTransport`, `DeadLetteredEvent`, `PublishManyResult`, `createEvent`,
+> `createChildEvent`, `matchEventPattern`. Arc 2.12 re-exports only the
+> runtime `MemoryEventTransport`.
+
+## Install
+
+```bash
+npm install @classytic/primitives
+```
+
+## Use
+
+Prefer **subpath imports** — each concern is its own entry point, types erase
+at compile time, runtime helpers are tiny.
+
+```ts
+import { addMoney, fromMajor, type Money } from '@classytic/primitives/money';
+import { createEvent, type DomainEvent, type EventTransport } from '@classytic/primitives/events';
+import type { OperationContext } from '@classytic/primitives/context';
+import { allocate, type SplitResult } from '@classytic/primitives/split-allocation';
+// Tenant config, error contracts, and pagination now live in repo-core:
+import { resolveTenantConfig, type TenantConfig } from '@classytic/repo-core/tenant';
+import type { HttpError, ErrorContract } from '@classytic/repo-core/errors';
+import type {
+  OffsetPaginationResult, KeysetPaginationResult, AggregatePaginationResult,
+} from '@classytic/repo-core/pagination';
+```
+
+There is intentionally **no root barrel** — a barrel forces the Node ESM
+loader and TypeScript compiler to walk every module on a single convenience
+import, which slows CI and pulls unused code into the consumer's graph. Use
+subpath imports only.
+
+## What's inside
+
+| Subpath | Ships |
+|---|---|
+| `/money` | `Money`, `fromMajor`, `toMajor`, `addMoney`, `subtractMoney`, `multiplyMoney`, `sumMoney`, `equalsMoney`, `compareMoney`, `negateMoney`, `absMoney`, `isMoney`, `CurrencyMismatchError` |
+| `/currency` | `CurrencyCode` brand, `CURRENCIES`, `MINOR_UNIT_FACTOR`, `minorUnitFactor`, `isKnownCurrency`, `toCurrencyCode`, `currencyCode`, `isCurrencyCode`, `InvalidCurrencyCodeError`, `CurrencyMismatchError`, `FxSnapshot`, `convertWithSnapshot`, `reverseWithSnapshot`, `FxRounding` |
+| `/address` | `Address`, `ContactAddress`, `GeoPoint`, `GeoJsonPoint`, `toGeoJsonPoint`, `fromGeoJsonPoint` |
+| `/period` | `DateRange`, `Period`, `isDateRange`, `isWithin`, `rangeDurationMs`, `rangesOverlap`, `DateRangeError` — **plus timezone-aware resolution**: `resolvePeriod`, `resolveDay`, `resolveMonth`, `resolveQuarter`, `resolveYear`, `resolveDateSpan`, `dayStart`, `periodOf`, `parsePeriod`, `formatPeriod`, `granularityOf`, `periodTimeZone`, `inclusiveEnd`, `PeriodError` |
+| `/reference` | `ExternalRef`, `ObjectIdLike`, `IdLike`, `DocumentRef`, `idToString`, `isExternalRef` |
+| `/context` | `OperationContext`, `ActorRef` |
+| `/events` | `DomainEvent`, `EventMeta`, `EventHandler`, `EventLogger`, `EventTransport`, `DeadLetteredEvent`, `PublishManyResult`, `createEvent`, `createChildEvent`, `matchEventPattern` |
+| `/result` | `Result<T, E>`, `ok`, `err`, `isOk`, `isErr`, `mapResult`, `mapError`, `unwrap` |
+| `/brand` | `Brand<T, B>`, `Prettify`, `DeepPartial`, `DeepReadonly`, `RequireKeys`, `OptionalKeys`, `Nullable`, `KeysMatching`, `NonEmptyArray` |
+| `/split-allocation` | `allocate`, `isBalanced`, `SplitAllocationError`, `SplitMethod`, `SplitSubject`, `SplitPart`, `SplitResult` |
+| `/idempotency` | `decideClaim`, `completeClaim`, `renewLease`, `identityKey`, `sameIdentity`, `fingerprintRequest`, `newLeaseToken`, `isLeaseExpired`, `holdsLease`, `isInFlight`, `DEFAULT_LEASE_MS`, `IdempotencyClaim`, `ClaimOutcome`, `ClaimResult`, `ClaimState`, `IdempotencyIdentity`, `IdempotencyError` |
+| `/approval` | `createChain`, `applyDecision`, `skipStep`, `nextPendingStep`, `pendingSteps`, `isApproved`, `assertApproved`, `assertApprovedIfPresent`, `isRejected`, `isPending`, `decisionCount`, `ApprovalError`, `ApprovalChain`, `ApprovalStep`, `ApprovalDecision`, `Approver`, `ApprovalThreshold` |
+| `/cadence` | `nextOccurrence`, `occurrencesBetween`, `validateCadence`, `CadenceError`, `Cadence`, `DailyCadence`, `WeeklyCadence`, `MonthlyCadence`, `YearlyCadence`, `CronCadence`, `IsoWeekday` |
+| `/hold` | `addHold`, `resolveHold`, `activeHolds`, `resolvedHolds`, `isOnHold`, `hasActiveHoldOfCode`, `HoldError`, `HoldReason`, `HoldActor` |
+| `/sla` | `breachedAt`, `remainingMs`, `elapsedMs`, `isBreached`, `consumedFraction`, `validateSLA`, `SLAError`, `SLA`, `BreachPolicy` |
+
+## Design
+
+### Money — integer minor units, always
+
+```ts
+import { fromMajor, addMoney, toMajor } from '@classytic/primitives/money';
+
+const subtotal = fromMajor(19.99, 'USD');     // { amount: 1999, currency: 'USD' }
+const shipping = fromMajor(5.00,  'USD');     // { amount: 500,  currency: 'USD' }
+const total    = addMoney(subtotal, shipping); // { amount: 2499, currency: 'USD' }
+toMajor(total);                                // 24.99
+```
+
+`Money.amount` is always an integer in the currency's minor unit — `1` = one
+cent for USD, one yen for JPY, one fils for KWD. Mixing currencies throws
+`CurrencyMismatchError`. This eliminates the float-rounding drift that happens
+when every package rolls its own `{ amount: number, currency: string }`.
+
+### DomainEvent — structurally identical to Arc
+
+```ts
+import { createEvent, type EventTransport } from '@classytic/primitives/events';
+
+const event = createEvent('order:placed', { orderId: 'ord_123' }, {
+  organizationId: ctx.organizationId,
+  userId: ctx.actorId,
+  correlationId: ctx.correlationId,
+});
+
+await transport.publish(event);
+```
+
+Shape matches `@classytic/arc`'s `DomainEvent` exactly — any Arc transport
+(memory, Redis pub/sub, Redis Streams, Kafka) plugs into a package expecting
+this interface without adapters. See PACKAGE_RULES.md §11.
+
+### TenantConfig — moved to `@classytic/repo-core/tenant`
+
+```ts
+import { resolveTenantConfig } from '@classytic/repo-core/tenant';
+
+const tenant = resolveTenantConfig(config.tenant);
+// { enabled: true, tenantField: 'organizationId', fieldType: 'objectId',
+//   ref: 'organization', contextKey: 'organizationId', required: true }
+```
+
+Mongokit's `MultiTenantOptions` and sqlitekit's equivalent both
+`extends Pick<TenantConfig, ...>` from repo-core — pass the resolved config
+straight into `multiTenantPlugin(resolved)`.
+
+### ExternalRef — polymorphic, framework-free
+
+```ts
+interface ExternalRef {
+  sourceId: string;
+  sourceModel: string;
+}
+```
+
+For references that cross trust boundaries (another package, another service,
+Stripe, Postgres) — paired with a host-implemented `SourceBridge`. Works for
+ObjectId, UUID, Stripe ID, anything. See PACKAGE_RULES.md §7.
+
+## What's not here (on purpose)
+
+- **Mongoose types** — use `ObjectIdLike` from `/reference`. Any Mongoose
+  `Types.ObjectId` satisfies it structurally.
+- **Transaction / Order / Cart shapes** — those are domain types, not
+  primitives. They live in their respective packages.
+- **Error subclasses** — throw plain `Error`s; hosts serialize them into
+  `ErrorContract` (from `@classytic/repo-core/errors`) at the HTTP boundary
+  via `toErrorContract(err)`.
+- **Runtime currency database** — ship a whitelist at the app layer if you
+  need one. `MINOR_UNIT_FACTOR` covers common cases.
+
+## License
+
+MIT © Classytic

package/dist/deadline.d.mts

@@ -0,0 +1,16 @@
+//#region src/composition/deadline.d.ts
+/**
+ * Race a promise against a deadline without leaking the loser.
+ *
+ * A call that can hang — no throw, no response, the underlying layer just
+ * never settles — must not block its caller forever. Nothing here cancels
+ * the original promise; it keeps running after the deadline, so its eventual
+ * settlement is swallowed rather than surfaced a second time to a caller
+ * that already moved on.
+ */
+declare class DeadlineExceededError extends Error {
+  constructor(label: string, timeoutMs: number);
+}
+declare function withDeadline<T>(promise: Promise<T>, timeoutMs: number, label: string): Promise<T>;
+//#endregion
+export { DeadlineExceededError, withDeadline };

package/dist/deadline.mjs

@@ -0,0 +1,31 @@
+//#region src/composition/deadline.ts
+/**
+* Race a promise against a deadline without leaking the loser.
+*
+* A call that can hang — no throw, no response, the underlying layer just
+* never settles — must not block its caller forever. Nothing here cancels
+* the original promise; it keeps running after the deadline, so its eventual
+* settlement is swallowed rather than surfaced a second time to a caller
+* that already moved on.
+*/
+var DeadlineExceededError = class extends Error {
+	constructor(label, timeoutMs) {
+		super(`${label} timed out after ${timeoutMs}ms`);
+		this.name = "DeadlineExceededError";
+	}
+};
+function withDeadline(promise, timeoutMs, label) {
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => reject(new DeadlineExceededError(label, timeoutMs)), timeoutMs);
+		timer.unref?.();
+		promise.then((value) => {
+			clearTimeout(timer);
+			resolve(value);
+		}, (err) => {
+			clearTimeout(timer);
+			reject(err);
+		});
+	});
+}
+//#endregion
+export { DeadlineExceededError, withDeadline };

package/dist/item-facts.d.mts

@@ -0,0 +1,73 @@
+import { ShelfLifePolicy } from "./shelf-life.mjs";
+//#region src/inventory/item-facts.d.ts
+/** Coarse lot/serial tracking. `trackingPolicy.mode` wins when both are set. */
+type TrackingMode = "none" | "lot" | "serial";
+/** The stock facts an Item contributes. Persistence and classification are the owning package's. */
+interface ItemStockSource {
+  skuRef: string;
+  sku: string;
+  displayName: string;
+  /** The canonical STOCK unit — what quants and moves are balanced in. */
+  uom: string;
+  trackingMode: TrackingMode;
+  trackingPolicy?: ShelfLifePolicy | undefined;
+  /**
+   * Variable-weight item (deli, meat, loose produce): a measured weight is
+   * captured per received lot while the piece count stays the stock dimension.
+   */
+  catchWeight?: boolean | undefined;
+  weightUom?: string | undefined;
+  weight?: number | undefined;
+  volume?: number | undefined;
+  barcode?: string[] | undefined;
+  /** Retired items are not stockable. Independent of whether a Product sells. */
+  isActive: boolean;
+}
+/** The merchandising side. Every stock fact is optional — the Item owns those. */
+interface ProductFacet {
+  skuRef: string;
+  sku: string;
+  displayName: string;
+  uom?: string | undefined;
+  trackingMode?: TrackingMode | undefined;
+  trackingPolicy?: ShelfLifePolicy | undefined;
+  catchWeight?: boolean | undefined;
+  weightUom?: string | undefined;
+  weight?: number | undefined;
+  volume?: number | undefined;
+  barcode?: string[] | undefined;
+  isActive?: boolean | undefined;
+}
+/** The resolved answer. `@classytic/flow`'s `SkuDetails` IS this type. */
+interface ItemStockFacts {
+  skuRef: string;
+  sku: string;
+  displayName: string;
+  trackingMode: TrackingMode;
+  trackingPolicy?: ShelfLifePolicy;
+  uom: string;
+  catchWeight?: boolean;
+  weightUom?: string;
+  weight?: number;
+  volume?: number;
+  barcode?: string[];
+  isActive: boolean;
+}
+/**
+ * Merge an Item with its Product facet.
+ *
+ * - **Neither** ⇒ `null`. An unknown SKU is ordinary (a deleted line), not an error.
+ * - **Product only** ⇒ the product's own facts — every deployment before an Item exists.
+ * - **Item only** ⇒ the item's facts. A raw material nobody sells.
+ * - **Both** ⇒ stock facts from the Item, name and label from the Product.
+ *
+ * `isActive` follows the ITEM when one exists: a product withdrawn from sale is
+ * still stock on a shelf, whereas a retired item is not stockable at all. Taking
+ * the product's flag would make unlisting a product silently orphan its stock.
+ */
+declare function resolveStockFacts(input: {
+  item?: ItemStockSource | null | undefined;
+  product?: ProductFacet | null | undefined;
+}): ItemStockFacts | null;
+//#endregion
+export { ItemStockFacts, ItemStockSource, ProductFacet, TrackingMode, resolveStockFacts };

package/dist/item-facts.mjs

@@ -0,0 +1,53 @@
+//#region src/inventory/item-facts.ts
+/** Unit assumed when neither side declares one. A deployment-wide guess, and a bad one — set a real `uom` on the Item. */
+const FALLBACK_UOM = "unit";
+const defined = (key, value) => value === void 0 ? {} : { [key]: value };
+/**
+* Merge an Item with its Product facet.
+*
+* - **Neither** ⇒ `null`. An unknown SKU is ordinary (a deleted line), not an error.
+* - **Product only** ⇒ the product's own facts — every deployment before an Item exists.
+* - **Item only** ⇒ the item's facts. A raw material nobody sells.
+* - **Both** ⇒ stock facts from the Item, name and label from the Product.
+*
+* `isActive` follows the ITEM when one exists: a product withdrawn from sale is
+* still stock on a shelf, whereas a retired item is not stockable at all. Taking
+* the product's flag would make unlisting a product silently orphan its stock.
+*/
+function resolveStockFacts(input) {
+	const { item, product } = input;
+	if (!item && !product) return null;
+	if (!item) {
+		const p = product;
+		return {
+			skuRef: p.skuRef,
+			sku: p.sku,
+			displayName: p.displayName,
+			uom: p.uom ?? FALLBACK_UOM,
+			trackingMode: p.trackingMode ?? "none",
+			...defined("trackingPolicy", p.trackingPolicy),
+			...defined("catchWeight", p.catchWeight),
+			...defined("weightUom", p.weightUom),
+			...defined("weight", p.weight),
+			...defined("volume", p.volume),
+			...defined("barcode", p.barcode),
+			isActive: p.isActive ?? true
+		};
+	}
+	return {
+		skuRef: item.skuRef,
+		sku: product?.sku ?? item.sku,
+		displayName: product?.displayName ?? item.displayName,
+		uom: item.uom,
+		trackingMode: item.trackingMode,
+		...defined("trackingPolicy", item.trackingPolicy),
+		...defined("catchWeight", item.catchWeight),
+		...defined("weightUom", item.weightUom),
+		...defined("weight", item.weight),
+		...defined("volume", item.volume),
+		...defined("barcode", item.barcode),
+		isActive: item.isActive
+	};
+}
+//#endregion
+export { resolveStockFacts };

package/dist/item-identity.d.mts

@@ -0,0 +1,61 @@
+import { t as Brand } from "./brand-Lj_75Y_r.mjs";
+//#region src/identity/item-identity.d.ts
+/**
+ * A resolved STOCK key — the string quants, moves and reservations are keyed by.
+ *
+ * Branded so a port that moves stock cannot accept a bare string: the only way
+ * to obtain one is {@link stockKeyOf} / {@link requireStockKey}, which apply the
+ * `skuRef ?? sku` rule. A merchandising label passed where a stock key belongs
+ * finds no quant and reports "out of stock" against a full shelf.
+ */
+type StockKey = Brand<string, "StockKey">;
+/** Identifier fields a record may carry — each shape populates a different subset. */
+interface SkuFields {
+  /** Merchandising label — mutable, human-facing. */
+  sku?: string | undefined;
+  /** Stock/ledger identity — immutable, keys quants and moves. */
+  skuRef?: string | undefined;
+  /** Label resolved server-side for a read model keyed by `skuRef`. */
+  skuLabel?: string | undefined;
+}
+/**
+ * The STOCK key to reserve, decrement and post against: `skuRef ?? sku`,
+ * falling back to `fallback` (typically the owning entity's `_id`) when the
+ * record carries neither — the shape every "variant, else the product"
+ * ledger key already re-derives by hand across three packages.
+ *
+ * `undefined` = the record carries neither AND no `fallback` was given —
+ * malformed, not untracked. Use {@link requireStockKey} where that must stop
+ * the write.
+ */
+declare function stockKeyOf(item: SkuFields, fallback?: string | {
+  toString(): string;
+}): StockKey | undefined;
+/**
+ * {@link stockKeyOf} that THROWS. Use wherever the key feeds a stock movement:
+ * a reservation on `undefined` returns "out of stock" instead of failing.
+ */
+declare function requireStockKey(item: SkuFields, context?: string): StockKey;
+/** What a surface should render for an item, and whether it had a real label. */
+interface SkuDisplay {
+  /** Best human-facing value. `undefined` = no identifier at all; render a dash. */
+  label: string | undefined;
+  /** The stock identity, for subtext or copy-to-clipboard. */
+  ref: string | undefined;
+  /**
+   * TRUE when `label` is really the `ref` (nothing resolved). Style it as an id
+   * — monospace, muted — never as a SKU.
+   */
+  isRefFallback: boolean;
+}
+/** What to SHOW: `skuLabel ?? sku ?? skuRef`. The ref is returned alongside,
+ * never dropped — it is the join key an operator quotes. */
+declare function skuDisplay(item: SkuFields): SkuDisplay;
+/**
+ * Looks like an opaque id (24-char hex) rather than a merchandising code.
+ * PRESENTATION HINT ONLY — never branch stock logic on it; a deployment may key
+ * quants by any stable string.
+ */
+declare function looksLikeOpaqueId(value: string | undefined): boolean;
+//#endregion
+export { SkuDisplay, SkuFields, StockKey, looksLikeOpaqueId, requireStockKey, skuDisplay, stockKeyOf };

package/dist/item-identity.mjs

@@ -0,0 +1,50 @@
+//#region src/identity/item-identity.ts
+const nonEmpty = (value) => typeof value === "string" && value.trim().length > 0 ? value : void 0;
+/**
+* The STOCK key to reserve, decrement and post against: `skuRef ?? sku`,
+* falling back to `fallback` (typically the owning entity's `_id`) when the
+* record carries neither — the shape every "variant, else the product"
+* ledger key already re-derives by hand across three packages.
+*
+* `undefined` = the record carries neither AND no `fallback` was given —
+* malformed, not untracked. Use {@link requireStockKey} where that must stop
+* the write.
+*/
+function stockKeyOf(item, fallback) {
+	return nonEmpty(item.skuRef) ?? nonEmpty(item.sku) ?? (fallback !== void 0 ? String(fallback) : void 0);
+}
+/**
+* {@link stockKeyOf} that THROWS. Use wherever the key feeds a stock movement:
+* a reservation on `undefined` returns "out of stock" instead of failing.
+*/
+function requireStockKey(item, context) {
+	const key = stockKeyOf(item);
+	if (key === void 0) throw new Error(`stock key missing: neither skuRef nor sku is set${context ? ` (${context})` : ""}`);
+	return key;
+}
+/** What to SHOW: `skuLabel ?? sku ?? skuRef`. The ref is returned alongside,
+* never dropped — it is the join key an operator quotes. */
+function skuDisplay(item) {
+	const ref = nonEmpty(item.skuRef);
+	const label = nonEmpty(item.skuLabel) ?? nonEmpty(item.sku);
+	if (label !== void 0) return {
+		label,
+		ref,
+		isRefFallback: false
+	};
+	return {
+		label: ref,
+		ref,
+		isRefFallback: ref !== void 0
+	};
+}
+/**
+* Looks like an opaque id (24-char hex) rather than a merchandising code.
+* PRESENTATION HINT ONLY — never branch stock logic on it; a deployment may key
+* quants by any stable string.
+*/
+function looksLikeOpaqueId(value) {
+	return typeof value === "string" && /^[0-9a-f]{24}$/i.test(value);
+}
+//#endregion
+export { looksLikeOpaqueId, requireStockKey, skuDisplay, stockKeyOf };

package/dist/monetization.d.mts

@@ -22,6 +22,45 @@ declare const MONETIZATION_KINDS: readonly ["free", "one_time", "subscription",
 type MonetizationKind = (typeof MONETIZATION_KINDS)[number];
 /** True when `value` is one of the canonical kinds. */
 declare function isMonetizationKind(value: unknown): value is MonetizationKind;
+/**
+ * HOW MUCH of a price is collected at the point of sale.
+ *
+ * Distinct from every neighbouring vocabulary, which is why it is its own:
+ *
+ *   - order's `PAYMENT_TERMS` (`prepaid` | `collect_on_delivery`) says WHEN.
+ *   - `PaymentAllocationStatus` (`partial`, `allocated`…) says how much of a
+ *     RECEIVED payment has been applied to what it settles.
+ *   - revenue's `PARTIALLY_REFUNDED` is a transaction's own state.
+ *
+ * None of them answers "what do we charge this customer right now", and a host
+ * that guesses charges either nothing or everything — opposite answers to the
+ * same question.
+ *
+ * It lives here, beside {@link MONETIZATION_KINDS}, for the reason stated in
+ * catalog's barrel: monetization is a CROSS-KERNEL contract. Catalog declares
+ * the policy on a product, order turns it into tenders, revenue settles them.
+ * Three packages reading one definition, none re-exporting it.
+ *
+ *   - `full_payment` — the whole price, before the sale completes.
+ *   - `deposit`      — a fixed amount now, the balance outstanding on the
+ *                      order and settled later by another tender. One provider
+ *                      line instead of two, which matters when card fees are
+ *                      charged per transaction.
+ *   - `pay_later`    — nothing now. The order still records what is owed.
+ *
+ * ABSENCE means `full_payment` — the behaviour before this existed — so no
+ * stored record changes meaning when a build that knows this field ships.
+ */
+declare const UPFRONT_COLLECTION_MODES: readonly ["full_payment", "deposit", "pay_later"];
+type UpfrontCollectionMode = (typeof UPFRONT_COLLECTION_MODES)[number];
+/**
+ * Narrow an unknown value to a collection mode.
+ *
+ * Readers MUST treat `false` as UNKNOWN, never as `full_payment`: a record
+ * written by a build that knows a mode this one does not has not said "charge
+ * everything", and assuming so takes money nobody agreed to.
+ */
+declare function isUpfrontCollectionMode(value: unknown): value is UpfrontCollectionMode;
 /** A quantity-based price break. `price` (fixed override) XOR `discountPercent`. */
 interface PriceTier {
   /** Minimum quantity to qualify. */
@@ -191,4 +230,4 @@ declare function toRevenueMonetizationType(kind: MonetizationKind): RevenueMonet
 /** 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 };
+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 };

package/dist/monetization.mjs

@@ -21,6 +21,51 @@ const MONETIZATION_KIND_SET = new Set(MONETIZATION_KINDS);
 function isMonetizationKind(value) {
 	return typeof value === "string" && MONETIZATION_KIND_SET.has(value);
 }
+/**
+* HOW MUCH of a price is collected at the point of sale.
+*
+* Distinct from every neighbouring vocabulary, which is why it is its own:
+*
+*   - order's `PAYMENT_TERMS` (`prepaid` | `collect_on_delivery`) says WHEN.
+*   - `PaymentAllocationStatus` (`partial`, `allocated`…) says how much of a
+*     RECEIVED payment has been applied to what it settles.
+*   - revenue's `PARTIALLY_REFUNDED` is a transaction's own state.
+*
+* None of them answers "what do we charge this customer right now", and a host
+* that guesses charges either nothing or everything — opposite answers to the
+* same question.
+*
+* It lives here, beside {@link MONETIZATION_KINDS}, for the reason stated in
+* catalog's barrel: monetization is a CROSS-KERNEL contract. Catalog declares
+* the policy on a product, order turns it into tenders, revenue settles them.
+* Three packages reading one definition, none re-exporting it.
+*
+*   - `full_payment` — the whole price, before the sale completes.
+*   - `deposit`      — a fixed amount now, the balance outstanding on the
+*                      order and settled later by another tender. One provider
+*                      line instead of two, which matters when card fees are
+*                      charged per transaction.
+*   - `pay_later`    — nothing now. The order still records what is owed.
+*
+* ABSENCE means `full_payment` — the behaviour before this existed — so no
+* stored record changes meaning when a build that knows this field ships.
+*/
+const UPFRONT_COLLECTION_MODES = [
+	"full_payment",
+	"deposit",
+	"pay_later"
+];
+const UPFRONT_COLLECTION_MODE_SET = new Set(UPFRONT_COLLECTION_MODES);
+/**
+* Narrow an unknown value to a collection mode.
+*
+* Readers MUST treat `false` as UNKNOWN, never as `full_payment`: a record
+* written by a build that knows a mode this one does not has not said "charge
+* everything", and assuming so takes money nobody agreed to.
+*/
+function isUpfrontCollectionMode(value) {
+	return typeof value === "string" && UPFRONT_COLLECTION_MODE_SET.has(value);
+}
 const isFreeMonetization = (m) => m.type === "free";
 const isOneTimeMonetization = (m) => m.type === "one_time";
 const isSubscriptionMonetization = (m) => m.type === "subscription";
@@ -76,4 +121,4 @@ function fromRevenueMonetizationType(type) {
 	return "one_time";
 }
 //#endregion
-export { MONETIZATION_KINDS, compareAtPriceOf, fromRevenueMonetizationType, isBundleMonetization, isFreeMonetization, isMonetizationKind, isOneTimeMonetization, isSubscriptionMonetization, isUsageMonetization, monetizationKindOf, toRevenueMonetizationType, unitPriceOf };
+export { MONETIZATION_KINDS, UPFRONT_COLLECTION_MODES, compareAtPriceOf, fromRevenueMonetizationType, isBundleMonetization, isFreeMonetization, isMonetizationKind, isOneTimeMonetization, isSubscriptionMonetization, isUpfrontCollectionMode, isUsageMonetization, monetizationKindOf, toRevenueMonetizationType, unitPriceOf };

package/dist/stock-level.d.mts

@@ -0,0 +1,59 @@
+import { t as Brand } from "./brand-Lj_75Y_r.mjs";
+//#region src/inventory/stock-level.d.ts
+/**
+ * Stock quantities as NOMINAL types, so "how many are there" and "how many may
+ * I still promise" cannot be passed for one another.
+ *
+ * They are different questions with the same JavaScript type, and every layer
+ * re-derived the relationship between them: the flow ledger, the catalog
+ * bridge, the quant invariants, and the storefront cache each knew that
+ * available is on-hand minus reserved, and one of them still shipped on-hand
+ * into a field named `totalAvailable` — so the shop advertised units already
+ * held in someone else's cart and checkout refused the sale it had promised.
+ *
+ * Same fix as money's `MinorUnits<C>` brand, and for the same reason: a unit
+ * confusion that a reviewer must notice becomes one the compiler refuses.
+ * Zero runtime cost — the brands erase at compile time.
+ */
+/** Units physically present. INCLUDES units promised to open carts. */
+type OnHand = Brand<number, "OnHand">;
+/** Units held against an owner (cart, order, move group) — present, not free. */
+type Reserved = Brand<number, "Reserved">;
+/**
+ * Units that may still be promised to a NEW buyer: `onHand - reserved`.
+ *
+ * Constructible only via {@link sellable}, which is what makes passing on-hand
+ * where sellable is required a type error rather than an oversell.
+ */
+type Sellable = Brand<number, "Sellable">;
+/** What a location holds, as the ledger records it. */
+interface StockLevel {
+  readonly onHand: OnHand;
+  readonly reserved: Reserved;
+}
+declare const onHand: (n: number) => OnHand;
+declare const reserved: (n: number) => Reserved;
+/**
+ * The ONE definition of sellable stock.
+ *
+ * Deliberately NOT clamped at zero. Writing stock off below what is already
+ * reserved (goods damaged after being promised) is a real state, not an error —
+ * you cannot un-promise a cart. A negative reads as OVERSOLD, and every
+ * consumer already treats `<= 0` as unsellable; clamping would erase the only
+ * signal operations has that the condition exists.
+ */
+declare const sellable: (level: StockLevel) => Sellable;
+/** `true` when more is promised than is physically present. */
+declare const isOversold: (level: StockLevel) => boolean;
+/**
+ * Build a level from a ledger row, whatever it calls its fields.
+ *
+ * A quant reports all three; `available` is IGNORED on purpose and recomputed,
+ * so a source whose stored total has drifted cannot import that drift.
+ */
+declare const levelOf: (row: {
+  quantityOnHand?: number;
+  quantityReserved?: number;
+}) => StockLevel;
+//#endregion
+export { OnHand, Reserved, Sellable, StockLevel, isOversold, levelOf, onHand, reserved, sellable };

package/dist/stock-level.mjs

@@ -0,0 +1,27 @@
+//#region src/inventory/stock-level.ts
+const onHand = (n) => n;
+const reserved = (n) => n;
+/**
+* The ONE definition of sellable stock.
+*
+* Deliberately NOT clamped at zero. Writing stock off below what is already
+* reserved (goods damaged after being promised) is a real state, not an error —
+* you cannot un-promise a cart. A negative reads as OVERSOLD, and every
+* consumer already treats `<= 0` as unsellable; clamping would erase the only
+* signal operations has that the condition exists.
+*/
+const sellable = (level) => level.onHand - level.reserved;
+/** `true` when more is promised than is physically present. */
+const isOversold = (level) => sellable(level) < 0;
+/**
+* Build a level from a ledger row, whatever it calls its fields.
+*
+* A quant reports all three; `available` is IGNORED on purpose and recomputed,
+* so a source whose stored total has drifted cannot import that drift.
+*/
+const levelOf = (row) => ({
+	onHand: onHand(row.quantityOnHand ?? 0),
+	reserved: reserved(row.quantityReserved ?? 0)
+});
+//#endregion
+export { isOversold, levelOf, onHand, reserved, sellable };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/primitives",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "description": "Framework-agnostic TypeScript primitives shared across Classytic packages — Money, events, pagination, tenant config, and other building blocks.",
   "author": "Classytic",
   "license": "MIT",
@@ -185,6 +185,10 @@
       "types": "./dist/mixin.d.mts",
       "default": "./dist/mixin.mjs"
     },
+    "./deadline": {
+      "types": "./dist/deadline.d.mts",
+      "default": "./dist/deadline.mjs"
+    },
     "./sla-policy": {
       "types": "./dist/sla-policy.d.mts",
       "default": "./dist/sla-policy.mjs"
@@ -209,6 +213,18 @@
     "./subject": {
       "types": "./dist/subject.d.mts",
       "default": "./dist/subject.mjs"
+    },
+    "./item-identity": {
+      "types": "./dist/item-identity.d.mts",
+      "default": "./dist/item-identity.mjs"
+    },
+    "./stock-level": {
+      "types": "./dist/stock-level.d.mts",
+      "default": "./dist/stock-level.mjs"
+    },
+    "./item-facts": {
+      "types": "./dist/item-facts.d.mts",
+      "default": "./dist/item-facts.mjs"
     }
   },
   "files": [