@classytic/primitives 0.15.0 → 0.18.0

package/CHANGELOG.md

@@ -3,6 +3,52 @@
 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.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`)
+
+- **`ApprovalErrorCode` gains `'CHAIN_INCOMPLETE'`** — the single canonical
+  error code for "finalize/commit attempted before the chain reached `approved`".
+  Hosts route it through `rethrowApprovalError` to the `approval.chain_incomplete`
+  wire code so all commit/post/finalize boundaries raise the same structured error.
+- **`assertApproved(chain, message?)`** — canonical finalize-time gate: asserts
+  the chain has reached `approved`, else throws `ApprovalError('CHAIN_INCOMPLETE')`.
+  A `null`/absent chain passes (no chain required). Use at every journal-entry
+  post, PO approve, transfer dispatch, etc. to replace per-domain hand-rolled
+  divergent codes with one definition.
+
+Purely additive — no existing exports changed.
+
 ## [0.15.0] - 2026-07-25
 
 ### Added — `/retention`: `PurgeEvidence` value object

package/dist/approval.d.mts

@@ -83,7 +83,12 @@ interface CreateStepInput {
   readonly requiredApprovals?: number;
   readonly threshold?: ApprovalThreshold;
 }
-type ApprovalErrorCode = 'EMPTY_STEPS' | 'DUPLICATE_STEP_ID' | 'EMPTY_APPROVERS' | 'DUPLICATE_APPROVER_ID' | 'INVALID_QUORUM' | 'UNKNOWN_STEP' | 'UNAUTHORIZED_APPROVER' | 'STEP_NOT_ACTIVE' | 'STEP_ALREADY_DECIDED_BY_APPROVER';
+type ApprovalErrorCode = 'EMPTY_STEPS' | 'DUPLICATE_STEP_ID' | 'EMPTY_APPROVERS' | 'DUPLICATE_APPROVER_ID' | 'INVALID_QUORUM' | 'UNKNOWN_STEP' | 'UNAUTHORIZED_APPROVER' | 'STEP_NOT_ACTIVE' | 'STEP_ALREADY_DECIDED_BY_APPROVER'
+/** A finalize/commit was attempted while the chain has not reached
+ *  `approved` (still `pending`, or `rejected`). The single canonical
+ *  "not yet approved" gate — hosts route it through arc-approval's
+ *  `rethrowApprovalError` to the `approval.chain_incomplete` wire code. */
+| 'CHAIN_INCOMPLETE';
 declare class ApprovalError extends Error {
   readonly name = "ApprovalError";
   readonly code: ApprovalErrorCode;
@@ -123,6 +128,16 @@ declare function applyDecision(chain: ApprovalChain, input: DecisionInput): Appr
  */
 declare function skipStep(chain: ApprovalChain, stepId: string, reason?: string): ApprovalChain;
 declare function isApproved(chain: ApprovalChain): boolean;
+/**
+ * The canonical finalize-time gate: assert `chain` has reached `approved`,
+ * else throw `ApprovalError('CHAIN_INCOMPLETE')`. Use this at every
+ * commit/post/finalize boundary that must not proceed on an unapproved chain
+ * (journal-entry post, PO approve, transfer dispatch, …) so they all raise the
+ * SAME error instead of hand-rolling divergent codes. A `null`/absent chain is
+ * treated as "no chain required" and passes — callers that require a chain
+ * check presence separately.
+ */
+declare function assertApproved(chain: ApprovalChain | null | undefined, message?: string): void;
 declare function isRejected(chain: ApprovalChain): boolean;
 declare function isPending(chain: ApprovalChain): boolean;
 /**
@@ -130,4 +145,4 @@ declare function isPending(chain: ApprovalChain): boolean;
  */
 declare function decisionCount(chain: ApprovalChain): number;
 //#endregion
-export { ApprovalChain, ApprovalDecision, ApprovalError, ApprovalErrorCode, ApprovalStatus, ApprovalStep, ApprovalThreshold, Approver, ChainOrder, CreateChainInput, CreateStepInput, DecisionInput, applyDecision, createChain, decisionCount, isApproved, isPending, isRejected, nextPendingStep, pendingSteps, skipStep };
+export { ApprovalChain, ApprovalDecision, ApprovalError, ApprovalErrorCode, ApprovalStatus, ApprovalStep, ApprovalThreshold, Approver, ChainOrder, CreateChainInput, CreateStepInput, DecisionInput, applyDecision, assertApproved, createChain, decisionCount, isApproved, isPending, isRejected, nextPendingStep, pendingSteps, skipStep };

package/dist/approval.mjs

@@ -115,6 +115,18 @@ function skipStep(chain, stepId, reason) {
 function isApproved(chain) {
 	return chain.status === "approved";
 }
+/**
+* The canonical finalize-time gate: assert `chain` has reached `approved`,
+* else throw `ApprovalError('CHAIN_INCOMPLETE')`. Use this at every
+* commit/post/finalize boundary that must not proceed on an unapproved chain
+* (journal-entry post, PO approve, transfer dispatch, …) so they all raise the
+* SAME error instead of hand-rolling divergent codes. A `null`/absent chain is
+* treated as "no chain required" and passes — callers that require a chain
+* check presence separately.
+*/
+function assertApproved(chain, message) {
+	if (chain != null && !isApproved(chain)) throw new ApprovalError("CHAIN_INCOMPLETE", message ?? `approval chain has not reached 'approved' (status='${chain.status}')`);
+}
 function isRejected(chain) {
 	return chain.status === "rejected";
 }
@@ -143,4 +155,4 @@ function computeChainStatus(steps) {
 	return steps.every((s) => s.status === "approved" || s.status === "skipped") ? "approved" : "pending";
 }
 //#endregion
-export { ApprovalError, applyDecision, createChain, decisionCount, isApproved, isPending, isRejected, nextPendingStep, pendingSteps, skipStep };
+export { ApprovalError, applyDecision, assertApproved, createChain, decisionCount, isApproved, isPending, isRejected, nextPendingStep, pendingSteps, skipStep };

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/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/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 };
 }

package/dist/state-diagram.d.mts

@@ -0,0 +1,68 @@
+import { StateMachine } from "./state-machine.mjs";
+
+//#region src/workflow/state-diagram.d.ts
+interface StateDiagramOptions<TStatus extends string> {
+  /**
+   * The state a new aggregate starts in. Drawn as `[*] --> initial`.
+   *
+   * NOT inferred: a machine's entry point is a domain fact the adjacency list does
+   * not carry. "The state with no inbound transitions" guesses wrong the moment a
+   * machine has a legal return path into its own start (a retry going
+   * `sent → pending`), and silently drawing the wrong entry point is worse than
+   * drawing none.
+   */
+  readonly initial?: TStatus;
+  /**
+   * Highlight one state — "you are here" for an operator looking at a record.
+   */
+  readonly current?: TStatus;
+  /** Diagram title, rendered above the graph. */
+  readonly title?: string;
+  /**
+   * Label a transition, keyed `"from->to"`. For naming the VERB that causes it
+   * (`"sent->acked": "device confirmed"`), which is the part a reader actually
+   * wants and the table cannot know.
+   */
+  readonly labels?: Readonly<Record<string, string>>;
+  /**
+   * Draw `terminal --> [*]` edges. Default true — a reader needs to see which
+   * states end the lifecycle. Turn off for a dense machine where the extra edges
+   * cost more than they explain.
+   */
+  readonly showTerminal?: boolean;
+}
+/**
+ * A `stateDiagram-v2` for this machine.
+ *
+ * Self-transitions are emitted as-is — mermaid draws them as a loop, and they are
+ * meaningful (`sent → sent` is the device-command re-lease after a lapsed lease),
+ * so suppressing them would hide a real rule.
+ */
+declare function toMermaid<TStatus extends string>(machine: StateMachine<TStatus>, options?: StateDiagramOptions<TStatus>): string;
+/** One row of `describeStateMachine` — a table a UI or a doc can render directly. */
+interface StateDescription<TStatus extends string> {
+  readonly status: TStatus;
+  readonly targets: readonly TStatus[];
+  readonly sources: readonly TStatus[];
+  readonly terminal: boolean;
+}
+/**
+ * The machine as data, for a UI that wants a table rather than a picture — an
+ * action bar asking "which transitions are legal from where this record is now"
+ * reads `targets`, and never has to hardcode a list that drifts from the kernel.
+ */
+declare function describeStateMachine<TStatus extends string>(machine: StateMachine<TStatus>): {
+  readonly name: string;
+  readonly states: readonly StateDescription<TStatus>[];
+};
+/**
+ * States that can never be reached from `initial`.
+ *
+ * A design smell worth a CI check: an unreachable state is either a transition
+ * somebody forgot to declare, or dead vocabulary nobody removed. Both are cheap to
+ * find here and expensive to notice in production, where the symptom is a record
+ * that can never leave the state it is stuck in.
+ */
+declare function unreachableStates<TStatus extends string>(machine: StateMachine<TStatus>, initial: TStatus): readonly TStatus[];
+//#endregion
+export { StateDescription, StateDiagramOptions, describeStateMachine, toMermaid, unreachableStates };

package/dist/state-diagram.mjs

@@ -0,0 +1,66 @@
+//#region src/workflow/state-diagram.ts
+/** Mermaid ids must be identifier-safe; domain statuses are usually snake_case. */
+function safeId(status) {
+	const id = status.replace(/[^A-Za-z0-9_]/g, "_");
+	return /^[0-9]/.test(id) ? `s_${id}` : id;
+}
+/**
+* A `stateDiagram-v2` for this machine.
+*
+* Self-transitions are emitted as-is — mermaid draws them as a loop, and they are
+* meaningful (`sent → sent` is the device-command re-lease after a lapsed lease),
+* so suppressing them would hide a real rule.
+*/
+function toMermaid(machine, options = {}) {
+	const { initial, current, title, labels = {}, showTerminal = true } = options;
+	const lines = [];
+	if (title !== void 0) lines.push("---", `title: ${title}`, "---");
+	lines.push("stateDiagram-v2");
+	if (initial !== void 0) lines.push(`    [*] --> ${safeId(initial)}`);
+	const states = Object.keys(machine.transitions).sort();
+	for (const from of states) for (const to of [...machine.validTargets(from)].sort()) {
+		const label = labels[`${from}->${to}`];
+		lines.push(`    ${safeId(from)} --> ${safeId(to)}${label !== void 0 ? `: ${label}` : ""}`);
+	}
+	if (showTerminal) {
+		for (const state of states) if (machine.isTerminal(state)) lines.push(`    ${safeId(state)} --> [*]`);
+	}
+	if (current !== void 0) lines.push("    classDef current fill:#2563eb,stroke:#1e40af,color:#fff,font-weight:bold", `    class ${safeId(current)} current`);
+	return lines.join("\n");
+}
+/**
+* The machine as data, for a UI that wants a table rather than a picture — an
+* action bar asking "which transitions are legal from where this record is now"
+* reads `targets`, and never has to hardcode a list that drifts from the kernel.
+*/
+function describeStateMachine(machine) {
+	const states = Object.keys(machine.transitions).sort();
+	return {
+		name: machine.name,
+		states: states.map((status) => ({
+			status,
+			targets: [...machine.validTargets(status)].sort(),
+			sources: [...machine.validSources(status)].sort(),
+			terminal: machine.isTerminal(status)
+		}))
+	};
+}
+/**
+* States that can never be reached from `initial`.
+*
+* A design smell worth a CI check: an unreachable state is either a transition
+* somebody forgot to declare, or dead vocabulary nobody removed. Both are cheap to
+* find here and expensive to notice in production, where the symptom is a record
+* that can never leave the state it is stuck in.
+*/
+function unreachableStates(machine, initial) {
+	const seen = new Set([initial]);
+	const queue = [initial];
+	while (queue.length > 0) for (const next of machine.validTargets(queue.pop())) if (!seen.has(next)) {
+		seen.add(next);
+		queue.push(next);
+	}
+	return Object.keys(machine.transitions).filter((s) => !seen.has(s)).sort();
+}
+//#endregion
+export { describeStateMachine, toMermaid, unreachableStates };

package/dist/subject.d.mts

@@ -0,0 +1,65 @@
+//#region src/identity/subject.d.ts
+/**
+ * `SubjectRef` — WHO a record is about, polymorphically.
+ *
+ * The pairing `{ subjectModel, subjectRef }` appears across every package that
+ * has to talk about a person without owning them: an attendance punch, an access
+ * entitlement, a device credential, a loyalty balance. Each of those kernels
+ * deliberately keeps the model a plain `string`, because attendance serves
+ * employees, students and gym members and no kernel can know which.
+ *
+ * ## Why this is NOT `ExternalRef`
+ *
+ * `composition/reference.ts` already models `{ sourceId, sourceModel }` — the
+ * identical SHAPE. They are kept apart because they answer different questions and
+ * that difference is load-bearing:
+ *
+ * - `ExternalRef` — "this record CAME FROM there" (an Order, a Stripe charge, a
+ *   Postgres invoice). Provenance. Used for reconciliation and cascades.
+ * - `SubjectRef` — "this record is ABOUT them". Identity. Used for authorization
+ *   and lookup.
+ *
+ * A grant carries both at once and they mean different things: `originModel:
+ * 'Order'` (what paid) and `subjectModel: 'Party'` (who holds it). Collapsing them
+ * into one type would make that sentence unsayable, and renaming the persisted
+ * `subjectModel`/`subjectRef` fields to `sourceModel`/`sourceId` is the harmful
+ * rename — a migration across many collections that buys nothing.
+ *
+ * ## Why a shared type at all
+ *
+ * The pairing spans SERVER and CLIENT. A server writes it when a membership grant
+ * projects an entitlement; a web app writes it when staff bind a card. When the two
+ * disagree nothing throws — the synchronizer matches on both fields, so it finds
+ * ZERO rows, and freezing a membership silently stops touching the member's card.
+ * That bug shipped: a UI hardcoded `'Customer'` against a server writing `'Party'`.
+ * One shared type plus one shared constant per domain is the fix.
+ */
+/** A polymorphic reference to the subject a record is about. */
+interface SubjectRef {
+  /** Logical model / type name — e.g. 'Party', 'Employee', 'Student', 'ApiKey'. */
+  subjectModel: string;
+  /** Opaque identifier of the subject within that model. */
+  subjectRef: string;
+}
+/**
+ * Build a `SubjectRef`, or `null` when the id is absent/blank.
+ *
+ * Returning null rather than a ref containing `"undefined"` or `""` is the whole
+ * point: a malformed binding does not fail loudly, it silently matches nothing
+ * forever — an entitlement nobody holds, a credential no revoke can find.
+ */
+declare function makeSubjectRef(subjectModel: string, id: string | number | null | undefined): SubjectRef | null;
+/**
+ * The canonical `"Model:id"` string form.
+ *
+ * One formatter so log lines, dedupe keys and command payloads agree. Two
+ * hand-rolled variants (`Party:1` vs `party/1`) look equivalent until one is used
+ * as an idempotency key and the other as a lookup.
+ */
+declare function formatSubjectRef(subject: SubjectRef): string;
+/** Exact equality on both halves — never on the id alone. */
+declare function subjectRefsEqual(a: SubjectRef | null, b: SubjectRef | null): boolean;
+/** Structural guard for data crossing a wire. */
+declare function isSubjectRef(value: unknown): value is SubjectRef;
+//#endregion
+export { SubjectRef, formatSubjectRef, isSubjectRef, makeSubjectRef, subjectRefsEqual };

package/dist/subject.mjs

@@ -0,0 +1,40 @@
+//#region src/identity/subject.ts
+/**
+* Build a `SubjectRef`, or `null` when the id is absent/blank.
+*
+* Returning null rather than a ref containing `"undefined"` or `""` is the whole
+* point: a malformed binding does not fail loudly, it silently matches nothing
+* forever — an entitlement nobody holds, a credential no revoke can find.
+*/
+function makeSubjectRef(subjectModel, id) {
+	const subjectRef = id === null || id === void 0 ? "" : String(id).trim();
+	const model = subjectModel.trim();
+	if (subjectRef.length === 0 || model.length === 0) return null;
+	return {
+		subjectModel: model,
+		subjectRef
+	};
+}
+/**
+* The canonical `"Model:id"` string form.
+*
+* One formatter so log lines, dedupe keys and command payloads agree. Two
+* hand-rolled variants (`Party:1` vs `party/1`) look equivalent until one is used
+* as an idempotency key and the other as a lookup.
+*/
+function formatSubjectRef(subject) {
+	return `${subject.subjectModel}:${subject.subjectRef}`;
+}
+/** Exact equality on both halves — never on the id alone. */
+function subjectRefsEqual(a, b) {
+	if (!a || !b) return false;
+	return a.subjectModel === b.subjectModel && a.subjectRef === b.subjectRef;
+}
+/** Structural guard for data crossing a wire. */
+function isSubjectRef(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const v = value;
+	return typeof v.subjectModel === "string" && v.subjectModel.length > 0 && typeof v.subjectRef === "string" && v.subjectRef.length > 0;
+}
+//#endregion
+export { formatSubjectRef, isSubjectRef, makeSubjectRef, subjectRefsEqual };

package/dist/suspension.d.mts

@@ -0,0 +1,151 @@
+import { UtcOffsetMinutes } from "./calendar.mjs";
+import { DateRange } from "./period.mjs";
+import { StatusChangeEntry } from "./status-history.mjs";
+
+//#region src/workflow/suspension.d.ts
+/**
+ * One suspension, past or current.
+ *
+ * `endedAt` absent or `null` means STILL OPEN — counted up to the evaluation
+ * instant, because an open freeze is consuming allowance right now. Treating an
+ * open span as zero is how an indefinite pause looks free.
+ */
+interface SuspensionSpan {
+  readonly startedAt: Date;
+  readonly endedAt?: Date | null;
+  readonly reason?: string;
+}
+/**
+ * The rulebook. Every field optional; an empty policy permits an unbounded pause,
+ * so a host that has not decided yet gets today's (lenient) behaviour rather than
+ * a surprise refusal.
+ */
+interface SuspensionPolicy {
+  /** `false` refuses outright — many gyms allow a freeze only on medical grounds. */
+  readonly allowed?: boolean;
+  /** Total suspended days permitted per period. Omit for unlimited. */
+  readonly maxDaysPerPeriod?: number;
+  /** Length of the allowance period in months. Default 12. */
+  readonly periodMonths?: number;
+  /** Shortest permitted single pause — stops pause-every-weekend gaming. */
+  readonly minDays?: number;
+  /** Longest permitted single pause, independent of the period allowance. */
+  readonly maxDays?: number;
+  /** How many may be open at once. Default 1. */
+  readonly maxConcurrent?: number;
+  /** Days of advance notice required before a pause may start. */
+  readonly noticeDays?: number;
+  /**
+   * Does resuming push the access window out by the frozen duration?
+   *
+   * Carried here because it is the same decision, made by the same person, as the
+   * rest of the pause rules — but note this primitive only REPORTS it. Applying it
+   * is the entitlement kernel's job (`resume({ creditFrozenDays })`), because only
+   * that kernel owns the window.
+   */
+  readonly creditsWindow?: boolean;
+}
+type SuspensionRefusal = 'not_allowed' | 'allowance_exhausted' | 'below_minimum' | 'above_maximum' | 'already_suspended' | 'insufficient_notice';
+interface SuspensionDecision {
+  readonly allowed: boolean;
+  readonly reason: SuspensionRefusal | 'approved';
+  /** Operator-facing explanation. Present on every refusal. */
+  readonly message?: string;
+  /**
+   * When the pause must end — `min(requested end, allowance cap)`.
+   *
+   * `null` only when the policy sets no bound at all. A sweep resumes on this
+   * instant regardless of whether the subject asks.
+   */
+  readonly autoResumeAt?: Date | null;
+  /** Days already consumed in the period containing the requested start. */
+  readonly daysUsedInPeriod: number;
+  /** Remaining allowance, or `null` when unlimited. */
+  readonly daysRemainingInPeriod: number | null;
+}
+interface SuspensionRequest {
+  readonly startsAt: Date;
+  /** Requested end. Omit for open-ended — the allowance then decides. */
+  readonly endsAt?: Date | null;
+  /** When the request is being made, for the notice check. Defaults to `startsAt`. */
+  readonly requestedAt?: Date;
+}
+interface SuspensionEvalOptions {
+  /** Minutes east of UTC for day boundaries — the BUSINESS timezone offset. */
+  readonly offsetMinutes?: UtcOffsetMinutes;
+}
+/** The allowance period containing `at`, as a half-open range. */
+declare function allowancePeriod(at: Date, periodMonths?: number, offsetMinutes?: UtcOffsetMinutes): DateRange;
+/**
+ * Whole days of suspension inside `period`.
+ *
+ * Counts the OVERLAP, not the spans that merely start inside — a freeze running
+ * 15 Dec → 15 Feb must consume only its December days against the period ending in
+ * December. Ignoring that double-counts a straddling pause in both periods and
+ * refuses a member who is within their allowance.
+ */
+declare function suspendedDaysInPeriod(history: readonly SuspensionSpan[], period: DateRange, /** Now — bounds still-open spans. Defaults to the period end. */at?: Date): number;
+/** Is any span still open at `at`? */
+declare function openSpans(history: readonly SuspensionSpan[], at: Date): readonly SuspensionSpan[];
+/**
+ * Decide a pause request, and say when it must end.
+ *
+ * Refusal precedence is deliberate — most categorical first, so the message names
+ * the reason a human would give:
+ *   1. `not_allowed`          — the product has no freeze at all
+ *   2. `already_suspended`    — concurrency
+ *   3. `insufficient_notice`  — asked too late
+ *   4. `below_minimum` / `above_maximum` — this single pause is the wrong length
+ *   5. `allowance_exhausted`  — nothing left in the period
+ */
+declare function evaluateSuspension(request: SuspensionRequest, history: readonly SuspensionSpan[], policy?: SuspensionPolicy, options?: SuspensionEvalOptions): SuspensionDecision;
+/**
+ * Is this open pause past the instant it should have ended?
+ *
+ * What an auto-resume sweep asks. Kept separate from `evaluateSuspension` because
+ * the sweep has an ALREADY-DECIDED `autoResumeAt` and must not re-derive it — the
+ * policy may have changed since the pause began, and silently re-deciding would
+ * move a date the member was told.
+ */
+declare function dueForAutoResume(span: SuspensionSpan & {
+  readonly autoResumeAt?: Date | null;
+}, at: Date): boolean;
+/**
+ * Derive suspension spans from a status log — the seam that makes an allowance
+ * ENFORCEABLE rather than caller-supplied.
+ *
+ * ## Why this exists
+ *
+ * `evaluateSuspension` needs the history of every past pause. Aggregates do not
+ * carry that: they carry a single `suspendedAt` that each new freeze overwrites, so
+ * "60 days per year" is unenforceable — a member could freeze twelve times and the
+ * eleventh looks identical to the first.
+ *
+ * What they DO carry (or should, per `/status-history`) is an append-only status
+ * log. Every pause is already in there as a transition INTO the paused status, and
+ * every resume as the transition out. This turns that log into the spans the
+ * allowance maths needs, so nothing has to be denormalised twice and the two
+ * primitives compose instead of overlapping.
+ *
+ * ## Assumes the log is chronological
+ *
+ * `appendStatus` guarantees that by construction (it appends and computes
+ * `durationInPriorMs` from the previous element), so this does not re-sort — a sort
+ * here would silently paper over a corrupt log that the caller should be told
+ * about, and would cost O(n log n) on a hot read.
+ *
+ * @param pausedStatus the status that MEANS suspended (`'suspended'`, `'paused'`,
+ *   `'on_hold'` — domains name it differently, so it is a parameter)
+ */
+declare function spansFromStatusHistory<TStatus extends string>(history: readonly StatusChangeEntry<TStatus>[], pausedStatus: TStatus, options?: {
+  /**
+   * The aggregate's status NOW. When it is not the paused status, a trailing
+   * paused entry is treated as CLOSED — the log simply has not recorded the
+   * resume yet (a crash between the write and the append). Leaving it open would
+   * charge the member allowance for time they were not frozen.
+   */
+  readonly currentStatus?: TStatus | undefined; /** Closes a genuinely-open trailing span for counting. Defaults to open. */
+  readonly openEndedAt?: Date | undefined;
+}): SuspensionSpan[];
+//#endregion
+export { SuspensionDecision, SuspensionEvalOptions, SuspensionPolicy, SuspensionRefusal, SuspensionRequest, SuspensionSpan, allowancePeriod, dueForAutoResume, evaluateSuspension, openSpans, spansFromStatusHistory, suspendedDaysInPeriod };

package/dist/suspension.mjs

@@ -0,0 +1,194 @@
+import { rangesOverlap } from "./period.mjs";
+import { addMonths, startOfDay } from "./calendar.mjs";
+//#region src/workflow/suspension.ts
+/**
+* Suspension policy — a time-bounded pause with a per-period allowance.
+*
+* ## What this is, and what it is not
+*
+* `/hold` already models a BLOCKING hold: a document cannot progress until someone
+* resolves it (fraud review, customs detention). It has no duration, no allowance
+* and no automatic end, because those are meaningless for a blocker.
+*
+* This models the other thing: a pause the subject is ENTITLED to take, bounded by
+* an allowance, that ends by itself. Three unrelated kernels need exactly that:
+*
+*   - a gym membership freeze — "60 days a year, minimum a week"
+*   - a subscription pause — the Netflix-style hold
+*   - unpaid leave — an annual cap, distinct from accrued paid leave
+*
+* (`hr/leave`'s balance is an accruing PERSISTED document — a different shape.
+* This is pure computation over a history, so it stays a primitive.)
+*
+* ## `autoResumeAt` is the whole point
+*
+* Without a computed end, "pause" is an indefinite free hold. Someone freezes in
+* February and the business quietly stops earning until an audit notices — which
+* is a revenue hole, not a bug report, so nobody files it. `evaluateSuspension`
+* always returns the instant the pause MUST end, so a sweep can resume it whether
+* or not the subject ever comes back.
+*
+* ## Dates
+*
+* Day boundaries come from `/calendar`'s offset-based helpers and periods from
+* `/period` — never server-local getters. A "60 days per year" allowance computed
+* with `getMonth()` shifts with the deploy machine's `TZ`, so the same member would
+* have a different balance in two regions. The offset is a CALLER decision
+* (business timezone), which is why it is a parameter with no default beyond UTC.
+*
+* PURE: no clock reads beyond the `at` you pass, no I/O. The same evaluation runs
+* on the server, in an admin preview, and in a test.
+*/
+const MS_PER_DAY = 1440 * 60 * 1e3;
+/** The allowance period containing `at`, as a half-open range. */
+function allowancePeriod(at, periodMonths = 12, offsetMinutes = 0) {
+	return {
+		start: addMonths(startOfDay(at, offsetMinutes), -periodMonths),
+		end: at
+	};
+}
+/**
+* Whole days of suspension inside `period`.
+*
+* Counts the OVERLAP, not the spans that merely start inside — a freeze running
+* 15 Dec → 15 Feb must consume only its December days against the period ending in
+* December. Ignoring that double-counts a straddling pause in both periods and
+* refuses a member who is within their allowance.
+*/
+function suspendedDaysInPeriod(history, period, at) {
+	const openEnd = at ?? period.end;
+	let ms = 0;
+	for (const span of history) {
+		const spanEnd = span.endedAt ?? openEnd;
+		if (spanEnd.getTime() <= span.startedAt.getTime()) continue;
+		const range = {
+			start: span.startedAt,
+			end: spanEnd
+		};
+		if (!rangesOverlap(range, period)) continue;
+		const from = Math.max(range.start.getTime(), period.start.getTime());
+		const to = Math.min(range.end.getTime(), period.end.getTime());
+		ms += Math.max(0, to - from);
+	}
+	return Math.round(ms / MS_PER_DAY);
+}
+/** Is any span still open at `at`? */
+function openSpans(history, at) {
+	return history.filter((s) => (s.endedAt ?? null) === null && s.startedAt.getTime() <= at.getTime());
+}
+/**
+* Decide a pause request, and say when it must end.
+*
+* Refusal precedence is deliberate — most categorical first, so the message names
+* the reason a human would give:
+*   1. `not_allowed`          — the product has no freeze at all
+*   2. `already_suspended`    — concurrency
+*   3. `insufficient_notice`  — asked too late
+*   4. `below_minimum` / `above_maximum` — this single pause is the wrong length
+*   5. `allowance_exhausted`  — nothing left in the period
+*/
+function evaluateSuspension(request, history, policy = {}, options = {}) {
+	const offset = options.offsetMinutes ?? 0;
+	const periodMonths = policy.periodMonths ?? 12;
+	const daysUsed = suspendedDaysInPeriod(history, allowancePeriod(request.startsAt, periodMonths, offset), request.startsAt);
+	const cap = policy.maxDaysPerPeriod;
+	const remaining = cap === void 0 ? null : Math.max(0, cap - daysUsed);
+	const refuse = (reason, message) => ({
+		allowed: false,
+		reason,
+		message,
+		daysUsedInPeriod: daysUsed,
+		daysRemainingInPeriod: remaining
+	});
+	if (policy.allowed === false) return refuse("not_allowed", "Pausing is not available on this product.");
+	const maxConcurrent = policy.maxConcurrent ?? 1;
+	if (openSpans(history, request.startsAt).length >= maxConcurrent) return refuse("already_suspended", "There is already an active pause.");
+	if (policy.noticeDays !== void 0 && policy.noticeDays > 0) {
+		const requestedAt = request.requestedAt ?? request.startsAt;
+		const noticeGiven = Math.round((startOfDay(request.startsAt, offset).getTime() - startOfDay(requestedAt, offset).getTime()) / MS_PER_DAY);
+		if (noticeGiven < policy.noticeDays) return refuse("insufficient_notice", `${policy.noticeDays} day(s) notice required; ${noticeGiven} given.`);
+	}
+	const requestedDays = request.endsAt != null ? Math.round((request.endsAt.getTime() - request.startsAt.getTime()) / MS_PER_DAY) : null;
+	if (requestedDays !== null) {
+		if (requestedDays <= 0) return refuse("below_minimum", "A pause must end after it starts.");
+		if (policy.minDays !== void 0 && requestedDays < policy.minDays) return refuse("below_minimum", `The shortest pause is ${policy.minDays} day(s); ${requestedDays} requested.`);
+		if (policy.maxDays !== void 0 && requestedDays > policy.maxDays) return refuse("above_maximum", `The longest single pause is ${policy.maxDays} day(s); ${requestedDays} requested.`);
+	}
+	if (remaining !== null && remaining <= 0) return refuse("allowance_exhausted", `The ${periodMonths}-month allowance of ${cap} day(s) is used up.`);
+	const candidates = [];
+	if (request.endsAt != null) candidates.push(request.endsAt.getTime());
+	if (remaining !== null) candidates.push(request.startsAt.getTime() + remaining * MS_PER_DAY);
+	if (policy.maxDays !== void 0) candidates.push(request.startsAt.getTime() + policy.maxDays * MS_PER_DAY);
+	return {
+		allowed: true,
+		reason: "approved",
+		autoResumeAt: candidates.length > 0 ? new Date(Math.min(...candidates)) : null,
+		daysUsedInPeriod: daysUsed,
+		daysRemainingInPeriod: remaining
+	};
+}
+/**
+* Is this open pause past the instant it should have ended?
+*
+* What an auto-resume sweep asks. Kept separate from `evaluateSuspension` because
+* the sweep has an ALREADY-DECIDED `autoResumeAt` and must not re-derive it — the
+* policy may have changed since the pause began, and silently re-deciding would
+* move a date the member was told.
+*/
+function dueForAutoResume(span, at) {
+	if ((span.endedAt ?? null) !== null) return false;
+	const due = span.autoResumeAt ?? null;
+	return due !== null && due.getTime() <= at.getTime();
+}
+/**
+* Derive suspension spans from a status log — the seam that makes an allowance
+* ENFORCEABLE rather than caller-supplied.
+*
+* ## Why this exists
+*
+* `evaluateSuspension` needs the history of every past pause. Aggregates do not
+* carry that: they carry a single `suspendedAt` that each new freeze overwrites, so
+* "60 days per year" is unenforceable — a member could freeze twelve times and the
+* eleventh looks identical to the first.
+*
+* What they DO carry (or should, per `/status-history`) is an append-only status
+* log. Every pause is already in there as a transition INTO the paused status, and
+* every resume as the transition out. This turns that log into the spans the
+* allowance maths needs, so nothing has to be denormalised twice and the two
+* primitives compose instead of overlapping.
+*
+* ## Assumes the log is chronological
+*
+* `appendStatus` guarantees that by construction (it appends and computes
+* `durationInPriorMs` from the previous element), so this does not re-sort — a sort
+* here would silently paper over a corrupt log that the caller should be told
+* about, and would cost O(n log n) on a hot read.
+*
+* @param pausedStatus the status that MEANS suspended (`'suspended'`, `'paused'`,
+*   `'on_hold'` — domains name it differently, so it is a parameter)
+*/
+function spansFromStatusHistory(history, pausedStatus, options = {}) {
+	const spans = [];
+	for (let i = 0; i < history.length; i += 1) {
+		const entry = history[i];
+		if (entry.status !== pausedStatus) continue;
+		const next = history[i + 1];
+		if (next !== void 0) {
+			spans.push({
+				startedAt: entry.occurredAt,
+				endedAt: next.occurredAt,
+				...entry.note !== void 0 ? { reason: entry.note } : {}
+			});
+			continue;
+		}
+		const stillPaused = options.currentStatus === void 0 || options.currentStatus === pausedStatus;
+		spans.push({
+			startedAt: entry.occurredAt,
+			endedAt: stillPaused ? options.openEndedAt ?? null : entry.occurredAt,
+			...entry.note !== void 0 ? { reason: entry.note } : {}
+		});
+	}
+	return spans;
+}
+//#endregion
+export { allowancePeriod, dueForAutoResume, evaluateSuspension, openSpans, spansFromStatusHistory, suspendedDaysInPeriod };

package/package.json

@@ -1,212 +1,224 @@
-{
-  "name": "@classytic/primitives",
-  "version": "0.15.0",
-  "description": "Framework-agnostic TypeScript primitives shared across Classytic packages — Money, events, pagination, tenant config, and other building blocks.",
-  "author": "Classytic",
-  "license": "MIT",
-  "homepage": "https://www.npmjs.com/package/@classytic/primitives",
-  "bugs": {
-    "url": "https://github.com/classytic/primitives/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/classytic/primitives.git"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "type": "module",
-  "sideEffects": false,
-  "engines": {
-    "node": ">=22"
-  },
-  "exports": {
-    "./money": {
-      "types": "./dist/money.d.mts",
-      "default": "./dist/money.mjs"
-    },
-    "./currency": {
-      "types": "./dist/currency.d.mts",
-      "default": "./dist/currency.mjs"
-    },
-    "./unit-cost-rate": {
-      "types": "./dist/unit-cost-rate.d.mts",
-      "default": "./dist/unit-cost-rate.mjs"
-    },
-    "./address": {
-      "types": "./dist/address.d.mts",
-      "default": "./dist/address.mjs"
-    },
-    "./period": {
-      "types": "./dist/period.d.mts",
-      "default": "./dist/period.mjs"
-    },
-    "./calendar": {
-      "types": "./dist/calendar.d.mts",
-      "default": "./dist/calendar.mjs"
-    },
-    "./timezone": {
-      "types": "./dist/timezone.d.mts",
-      "default": "./dist/timezone.mjs"
-    },
-    "./reference": {
-      "types": "./dist/reference.d.mts",
-      "default": "./dist/reference.mjs"
-    },
-    "./context": {
-      "types": "./dist/context.d.mts",
-      "default": "./dist/context.mjs"
-    },
-    "./events": {
-      "types": "./dist/events.d.mts",
-      "default": "./dist/events.mjs"
-    },
-    "./event-infra": {
-      "types": "./dist/event-infra.d.mts",
-      "default": "./dist/event-infra.mjs"
-    },
-    "./outbox": {
-      "types": "./dist/outbox.d.mts",
-      "default": "./dist/outbox.mjs"
-    },
-    "./result": {
-      "types": "./dist/result.d.mts",
-      "default": "./dist/result.mjs"
-    },
-    "./brand": {
-      "types": "./dist/brand.d.mts",
-      "default": "./dist/brand.mjs"
-    },
-    "./split-allocation": {
-      "types": "./dist/split-allocation.d.mts",
-      "default": "./dist/split-allocation.mjs"
-    },
-    "./approval": {
-      "types": "./dist/approval.d.mts",
-      "default": "./dist/approval.mjs"
-    },
-    "./cadence": {
-      "types": "./dist/cadence.d.mts",
-      "default": "./dist/cadence.mjs"
-    },
-    "./hold": {
-      "types": "./dist/hold.d.mts",
-      "default": "./dist/hold.mjs"
-    },
-    "./sla": {
-      "types": "./dist/sla.d.mts",
-      "default": "./dist/sla.mjs"
-    },
-    "./shelf-life": {
-      "types": "./dist/shelf-life.d.mts",
-      "default": "./dist/shelf-life.mjs"
-    },
-    "./person": {
-      "types": "./dist/person.d.mts",
-      "default": "./dist/person.mjs"
-    },
-    "./identity-verification": {
-      "types": "./dist/identity-verification.d.mts",
-      "default": "./dist/identity-verification.mjs"
-    },
-    "./otp": {
-      "types": "./dist/otp.d.mts",
-      "default": "./dist/otp.mjs"
-    },
-    "./state-machine": {
-      "types": "./dist/state-machine.d.mts",
-      "default": "./dist/state-machine.mjs"
-    },
-    "./bank-transaction": {
-      "types": "./dist/bank-transaction.d.mts",
-      "default": "./dist/bank-transaction.mjs"
-    },
-    "./payment-gateway": {
-      "types": "./dist/payment-gateway.d.mts",
-      "default": "./dist/payment-gateway.mjs"
-    },
-    "./payment-method-kind": {
-      "types": "./dist/payment-method-kind.d.mts",
-      "default": "./dist/payment-method-kind.mjs"
-    },
-    "./payment-allocation-status": {
-      "types": "./dist/payment-allocation-status.d.mts",
-      "default": "./dist/payment-allocation-status.mjs"
-    },
-    "./payment-events": {
-      "types": "./dist/payment-events.d.mts",
-      "default": "./dist/payment-events.mjs"
-    },
-    "./phone": {
-      "types": "./dist/phone.d.mts",
-      "default": "./dist/phone.mjs"
-    },
-    "./status-history": {
-      "types": "./dist/status-history.d.mts",
-      "default": "./dist/status-history.mjs"
-    },
-    "./condition": {
-      "types": "./dist/condition.d.mts",
-      "default": "./dist/condition.mjs"
-    },
-    "./mixin": {
-      "types": "./dist/mixin.d.mts",
-      "default": "./dist/mixin.mjs"
-    },
-    "./sla-policy": {
-      "types": "./dist/sla-policy.d.mts",
-      "default": "./dist/sla-policy.mjs"
-    },
-    "./retention": {
-      "types": "./dist/retention.d.mts",
-      "default": "./dist/retention.mjs"
-    },
-    "./canonical": {
-      "types": "./dist/canonical.d.mts",
-      "default": "./dist/canonical.mjs"
-    },
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "tsdown",
-    "dev": "tsdown --watch",
-    "typecheck": "tsc --noEmit",
-    "lint": "biome check src/ tests/",
-    "lint:fix": "biome check --write src/ tests/",
-    "test": "vitest run --project unit --project integration",
-    "test:unit": "vitest run --project unit",
-    "test:integration": "vitest run --project integration",
-    "test:all": "vitest run",
-    "test:watch": "vitest --project unit --project integration",
-    "test:smoke": "node tests/smoke/smoke.mjs",
-    "push": "classytic-push",
-    "prepublishOnly": "npm run typecheck && npm run test && npm run build && npm run test:smoke",
-    "release": "npm run build && npm run typecheck && npm publish --access public"
-  },
-  "devDependencies": {
-    "@biomejs/biome": "^2.4.9",
-    "@classytic/dev-tools": "^0.2.0",
-    "@types/node": "^25.5.0",
-    "tsdown": "^0.21.7",
-    "typescript": "^5.7.0",
-    "vitest": "^3.0.0"
-  },
-  "keywords": [
-    "typescript",
-    "types",
-    "primitives",
-    "money",
-    "currency",
-    "pagination",
-    "domain-event",
-    "tenant",
-    "classytic",
-    "commerce"
-  ]
-}
+{
+  "name": "@classytic/primitives",
+  "version": "0.18.0",
+  "description": "Framework-agnostic TypeScript primitives shared across Classytic packages — Money, events, pagination, tenant config, and other building blocks.",
+  "author": "Classytic",
+  "license": "MIT",
+  "homepage": "https://www.npmjs.com/package/@classytic/primitives",
+  "bugs": {
+    "url": "https://github.com/classytic/primitives/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/classytic/primitives.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    "./money": {
+      "types": "./dist/money.d.mts",
+      "default": "./dist/money.mjs"
+    },
+    "./currency": {
+      "types": "./dist/currency.d.mts",
+      "default": "./dist/currency.mjs"
+    },
+    "./unit-cost-rate": {
+      "types": "./dist/unit-cost-rate.d.mts",
+      "default": "./dist/unit-cost-rate.mjs"
+    },
+    "./address": {
+      "types": "./dist/address.d.mts",
+      "default": "./dist/address.mjs"
+    },
+    "./period": {
+      "types": "./dist/period.d.mts",
+      "default": "./dist/period.mjs"
+    },
+    "./calendar": {
+      "types": "./dist/calendar.d.mts",
+      "default": "./dist/calendar.mjs"
+    },
+    "./timezone": {
+      "types": "./dist/timezone.d.mts",
+      "default": "./dist/timezone.mjs"
+    },
+    "./reference": {
+      "types": "./dist/reference.d.mts",
+      "default": "./dist/reference.mjs"
+    },
+    "./context": {
+      "types": "./dist/context.d.mts",
+      "default": "./dist/context.mjs"
+    },
+    "./events": {
+      "types": "./dist/events.d.mts",
+      "default": "./dist/events.mjs"
+    },
+    "./event-infra": {
+      "types": "./dist/event-infra.d.mts",
+      "default": "./dist/event-infra.mjs"
+    },
+    "./outbox": {
+      "types": "./dist/outbox.d.mts",
+      "default": "./dist/outbox.mjs"
+    },
+    "./result": {
+      "types": "./dist/result.d.mts",
+      "default": "./dist/result.mjs"
+    },
+    "./brand": {
+      "types": "./dist/brand.d.mts",
+      "default": "./dist/brand.mjs"
+    },
+    "./split-allocation": {
+      "types": "./dist/split-allocation.d.mts",
+      "default": "./dist/split-allocation.mjs"
+    },
+    "./approval": {
+      "types": "./dist/approval.d.mts",
+      "default": "./dist/approval.mjs"
+    },
+    "./cadence": {
+      "types": "./dist/cadence.d.mts",
+      "default": "./dist/cadence.mjs"
+    },
+    "./hold": {
+      "types": "./dist/hold.d.mts",
+      "default": "./dist/hold.mjs"
+    },
+    "./sla": {
+      "types": "./dist/sla.d.mts",
+      "default": "./dist/sla.mjs"
+    },
+    "./shelf-life": {
+      "types": "./dist/shelf-life.d.mts",
+      "default": "./dist/shelf-life.mjs"
+    },
+    "./person": {
+      "types": "./dist/person.d.mts",
+      "default": "./dist/person.mjs"
+    },
+    "./identity-verification": {
+      "types": "./dist/identity-verification.d.mts",
+      "default": "./dist/identity-verification.mjs"
+    },
+    "./otp": {
+      "types": "./dist/otp.d.mts",
+      "default": "./dist/otp.mjs"
+    },
+    "./state-machine": {
+      "types": "./dist/state-machine.d.mts",
+      "default": "./dist/state-machine.mjs"
+    },
+    "./bank-transaction": {
+      "types": "./dist/bank-transaction.d.mts",
+      "default": "./dist/bank-transaction.mjs"
+    },
+    "./payment-gateway": {
+      "types": "./dist/payment-gateway.d.mts",
+      "default": "./dist/payment-gateway.mjs"
+    },
+    "./payment-method-kind": {
+      "types": "./dist/payment-method-kind.d.mts",
+      "default": "./dist/payment-method-kind.mjs"
+    },
+    "./payment-allocation-status": {
+      "types": "./dist/payment-allocation-status.d.mts",
+      "default": "./dist/payment-allocation-status.mjs"
+    },
+    "./payment-events": {
+      "types": "./dist/payment-events.d.mts",
+      "default": "./dist/payment-events.mjs"
+    },
+    "./phone": {
+      "types": "./dist/phone.d.mts",
+      "default": "./dist/phone.mjs"
+    },
+    "./status-history": {
+      "types": "./dist/status-history.d.mts",
+      "default": "./dist/status-history.mjs"
+    },
+    "./condition": {
+      "types": "./dist/condition.d.mts",
+      "default": "./dist/condition.mjs"
+    },
+    "./mixin": {
+      "types": "./dist/mixin.d.mts",
+      "default": "./dist/mixin.mjs"
+    },
+    "./sla-policy": {
+      "types": "./dist/sla-policy.d.mts",
+      "default": "./dist/sla-policy.mjs"
+    },
+    "./retention": {
+      "types": "./dist/retention.d.mts",
+      "default": "./dist/retention.mjs"
+    },
+    "./canonical": {
+      "types": "./dist/canonical.d.mts",
+      "default": "./dist/canonical.mjs"
+    },
+    "./package.json": "./package.json",
+    "./state-diagram": {
+      "types": "./dist/state-diagram.d.mts",
+      "default": "./dist/state-diagram.mjs"
+    },
+    "./suspension": {
+      "types": "./dist/suspension.d.mts",
+      "default": "./dist/suspension.mjs"
+    },
+    "./subject": {
+      "types": "./dist/subject.d.mts",
+      "default": "./dist/subject.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/ tests/",
+    "lint:fix": "biome check --write src/ tests/",
+    "test": "vitest run --project unit --project integration",
+    "test:unit": "vitest run --project unit",
+    "test:integration": "vitest run --project integration",
+    "test:all": "vitest run",
+    "test:watch": "vitest --project unit --project integration",
+    "test:smoke": "node tests/smoke/smoke.mjs",
+    "push": "classytic-push",
+    "prepublishOnly": "npm run typecheck && npm run test && npm run build && npm run test:smoke",
+    "release": "npm run build && npm run typecheck && npm publish --access public"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.9",
+    "@classytic/dev-tools": "^0.2.0",
+    "@types/node": "^25.5.0",
+    "tsdown": "^0.21.7",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "keywords": [
+    "typescript",
+    "types",
+    "primitives",
+    "money",
+    "currency",
+    "pagination",
+    "domain-event",
+    "tenant",
+    "classytic",
+    "commerce"
+  ]
+}