@classytic/primitives 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -3,6 +3,78 @@
 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.6.0] - 2026-05-17
+
+### Added — five new primitives for CRM / workflow domains
+
+These were extracted after deep-diving Twenty, Huly Platform, Frappe CRM,
+and NocoBase. Each fills a gap the existing primitives didn't cover, and
+each ships under its own flat subpath import (no breaking changes).
+
+- **`/phone`** — `PhoneNumber` value object + `parsePhone(input)` that
+  normalizes free-form input to E.164, captures the country calling code
+  as a discrete field, and reports failures via `Result<PhoneNumber,
+  PhoneError>`. Zero external deps; ITU-T E.164 prefixes inlined. Hosts
+  that want region-of-issue / line-type detection layer on top with
+  libphonenumber-js.
+
+- **`/status-history`** — Generic, immutable status-change log:
+  `StatusChangeEntry<TStatus>`, `appendStatus()`, `timeInStatus()`,
+  `lastTransitionTo()`. Captures `durationInPriorMs` at write time
+  (Frappe's "status change log" pattern), so funnel-velocity dashboards
+  ("avg time in Qualification") work without re-walking timestamps.
+  Pairs naturally with `/state-machine`.
+
+- **`/condition`** — Tiny JSON-serializable predicate DSL: `FieldCondition`
+  (`{ field, op, value }`) composed via `AllCondition` / `AnyCondition`
+  / `NotCondition`, plus a total `evaluate(condition, target)` and a
+  `validateCondition()` for boot-time schema checks. Powers SLA scope
+  filters, drip "if opened/clicked" branches, automation triggers, and
+  permission row-scopes — anywhere a predicate needs to round-trip
+  through a database.
+
+- **`/mixin`** — Additive type composition without subclassing:
+  `withMixin<T, K, M>()` / `getMixin()` / `hasMixin()` / `withoutMixin()`.
+  Lets a `Contact` carry per-domain payloads (`mixins.customer`,
+  `mixins.lead-fit`) on a typed `mixins` namespace without bloating the
+  base type. Distilled from Huly's mixin idea minus the decorators,
+  global hierarchy, and proxies.
+
+- **`/sla-policy`** — Higher-order SLA layered on the existing `/sla`:
+  priority matrix (`urgent` / `high` / `normal` → durations), first-
+  response vs rolling-response semantics, and working-hours window
+  (weekdays + start/end minute + holidays). `defineSLAPolicy()` validates
+  at boot; `evaluateSLAStatus()` produces `{ kind, responseBy,
+  remainingMs, breached }` from a policy + per-entity inputs. The
+  existing simple `/sla` interface is unchanged — `sla-policy` derives
+  concrete `SLA` instances from a policy + priority and delegates to it.
+
+### Changed — source-tree reorganization (no public-surface impact)
+
+The 24 primitive source files moved from a flat `src/*.ts` layout into
+six category folders so the package is self-documenting at the file
+system level:
+
+```
+src/
+  money/           money, currency, split-allocation, bank-transaction, payment-gateway
+  identity/        person, address, phone
+  scheduling/      period, cadence, sla, sla-policy
+  workflow/        state-machine, status-history, approval, hold, condition
+  events/          events, outbox
+  composition/     mixin, reference, context, brand, result
+```
+
+**Public subpath imports are unchanged** — `@classytic/primitives/money`,
+`@classytic/primitives/sla`, etc. still resolve. tsdown emits each entry
+to `dist/<name>.mjs` regardless of source nesting. Existing consumers
+upgrade with `npm install @classytic/primitives@^0.6.0` and a no-op
+diff.
+
+### Dependencies
+
+Still zero runtime deps. Node 22+.
+
 ## [0.5.0] - 2026-05-05
 
 ### Added — `/bank-transaction` subpath

package/dist/address.d.mts

@@ -1,4 +1,4 @@
-//#region src/address.d.ts
+//#region src/identity/address.d.ts
 /**
  * Postal address.
  *

package/dist/address.mjs

@@ -1,4 +1,4 @@
-//#region src/address.ts
+//#region src/identity/address.ts
 function toGeoJsonPoint(p) {
 	return {
 		type: "Point",

package/dist/approval.d.mts

@@ -1,4 +1,4 @@
-//#region src/approval.d.ts
+//#region src/workflow/approval.d.ts
 /**
  * Approval chain value object and pure state-transition helpers.
  *

package/dist/approval.mjs

@@ -1,4 +1,4 @@
-//#region src/approval.ts
+//#region src/workflow/approval.ts
 var ApprovalError = class extends Error {
 	name = "ApprovalError";
 	code;

package/dist/bank-transaction.d.mts

@@ -1,6 +1,6 @@
 import { Money } from "./money.mjs";
 
-//#region src/bank-transaction.d.ts
+//#region src/money/bank-transaction.d.ts
 /**
  * The other side of a bank transaction. All fields optional — different
  * formats populate different subsets:

package/dist/{brand-DApaegoR.d.mts → brand-LLXqoh5J.d.mts}

@@ -1,4 +1,4 @@
-//#region src/brand.d.ts
+//#region src/composition/brand.d.ts
 /**
  * Type utilities for building nominal types and transforming shapes.
  *

package/dist/brand.d.mts

@@ -1,2 +1,2 @@
-import { a as NonEmptyArray, c as Prettify, i as KeysMatching, l as RequireKeys, n as DeepPartial, o as Nullable, r as DeepReadonly, s as OptionalKeys, t as Brand } from "./brand-DApaegoR.mjs";
+import { a as NonEmptyArray, c as Prettify, i as KeysMatching, l as RequireKeys, n as DeepPartial, o as Nullable, r as DeepReadonly, s as OptionalKeys, t as Brand } from "./brand-LLXqoh5J.mjs";
 export { Brand, DeepPartial, DeepReadonly, KeysMatching, NonEmptyArray, Nullable, OptionalKeys, Prettify, RequireKeys };

package/dist/cadence.d.mts

@@ -1,4 +1,4 @@
-//#region src/cadence.d.ts
+//#region src/scheduling/cadence.d.ts
 /**
  * Recurrence spec + pure date arithmetic.
  *

package/dist/cadence.mjs

@@ -1,4 +1,4 @@
-//#region src/cadence.ts
+//#region src/scheduling/cadence.ts
 var CadenceError = class extends Error {
 	name = "CadenceError";
 	code;

package/dist/condition.d.mts

@@ -0,0 +1,76 @@
+//#region src/workflow/condition.d.ts
+/**
+ * Tiny JSON-serializable predicate DSL + evaluator.
+ *
+ * Hosts need to express "when this is true, do that" rules in places that
+ * can't carry code — SLA scope filters, drip-sequence branches ("if opened
+ * within 24h"), automation triggers, permission row-scopes. A 60-line
+ * predicate spec covers every realistic case better than a hand-rolled
+ * SQL-like grammar.
+ *
+ * Two layers:
+ *   1. `Condition` — pure data. JSON-safe. Round-trips through DB.
+ *   2. `evaluate(condition, value)` — pure function. Walks a dotted-path
+ *      expression on `value`, applies the comparator, returns boolean.
+ *
+ * No regex parsing, no AST tooling, no string interpolation — the grammar
+ * is structurally typed and the evaluator is a 30-line switch.
+ *
+ * @example Single comparison
+ *   evaluate({ field: 'status', op: 'eq', value: 'won' }, opportunity);
+ *
+ * @example Composite — drip "if opened in last 7d AND not clicked"
+ *   evaluate(
+ *     {
+ *       all: [
+ *         { field: 'lastOpenedAt', op: 'gte', value: sevenDaysAgo },
+ *         { field: 'lastClickedAt', op: 'isNull' },
+ *       ],
+ *     },
+ *     contactEngagement,
+ *   );
+ */
+/**
+ * Comparators. Kept small — every operator here has a single, unambiguous
+ * semantic across types. `in` accepts an array; `contains` accepts a single
+ * scalar against an array field; `startsWith`/`endsWith` are string-only;
+ * `isNull` / `isNotNull` have no `value`.
+ */
+type Comparator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin' | 'contains' | 'startsWith' | 'endsWith' | 'isNull' | 'isNotNull';
+/** Atomic predicate: extract `field` from the target, compare to `value`. */
+interface FieldCondition {
+  /** Dotted path: `'contact.email'`, `'metadata.utm.source'`, etc. */
+  readonly field: string;
+  readonly op: Comparator;
+  /** Comparand. Omitted for `isNull` / `isNotNull`. */
+  readonly value?: unknown;
+}
+/** All branches must be true. */
+interface AllCondition {
+  readonly all: readonly Condition[];
+}
+/** Any branch true short-circuits true. */
+interface AnyCondition {
+  readonly any: readonly Condition[];
+}
+/** Inverts the wrapped condition. */
+interface NotCondition {
+  readonly not: Condition;
+}
+type Condition = FieldCondition | AllCondition | AnyCondition | NotCondition;
+/** Evaluate a `Condition` against `target`. Total — never throws on shape. */
+declare function evaluate(condition: Condition, target: unknown): boolean;
+type ConditionErrorCode = 'EMPTY' | 'UNKNOWN_SHAPE' | 'INVALID_OP' | 'MISSING_VALUE' | 'EMPTY_GROUP';
+declare class ConditionError extends Error {
+  readonly name = "ConditionError";
+  readonly code: ConditionErrorCode;
+  constructor(code: ConditionErrorCode, message: string);
+}
+/**
+ * Validate a condition shape before persisting. Recurses through composites.
+ * Throws `ConditionError` so hosts get a stable code + message in API
+ * responses (`{ code: 'INVALID_OP', message: '...' }`).
+ */
+declare function validateCondition(condition: Condition): void;
+//#endregion
+export { AllCondition, AnyCondition, Comparator, Condition, ConditionError, ConditionErrorCode, FieldCondition, NotCondition, evaluate, validateCondition };

package/dist/condition.mjs

@@ -0,0 +1,131 @@
+//#region src/workflow/condition.ts
+function isFieldCondition(c) {
+	return typeof c.field === "string" && typeof c.op === "string";
+}
+function isAllCondition(c) {
+	return Array.isArray(c.all);
+}
+function isAnyCondition(c) {
+	return Array.isArray(c.any);
+}
+function isNotCondition(c) {
+	return typeof c.not === "object" && c.not !== null;
+}
+/**
+* Walk a dotted path on `target`. Returns `undefined` when any segment
+* doesn't exist. Treats `null` as a terminal (doesn't try to recurse on it).
+*/
+function getPath(target, path) {
+	if (path === "" || target === null || target === void 0) return void 0;
+	let cursor = target;
+	for (const segment of path.split(".")) {
+		if (cursor === null || cursor === void 0) return void 0;
+		if (typeof cursor !== "object") return void 0;
+		cursor = cursor[segment];
+	}
+	return cursor;
+}
+/** Evaluate a `Condition` against `target`. Total — never throws on shape. */
+function evaluate(condition, target) {
+	if (isAllCondition(condition)) return condition.all.every((c) => evaluate(c, target));
+	if (isAnyCondition(condition)) return condition.any.some((c) => evaluate(c, target));
+	if (isNotCondition(condition)) return !evaluate(condition.not, target);
+	if (isFieldCondition(condition)) return evaluateField(condition, target);
+	return false;
+}
+function evaluateField(c, target) {
+	const lhs = getPath(target, c.field);
+	const rhs = c.value;
+	switch (c.op) {
+		case "eq": return strictEqual(lhs, rhs);
+		case "neq": return !strictEqual(lhs, rhs);
+		case "gt": return compare(lhs, rhs) > 0;
+		case "gte": return compare(lhs, rhs) >= 0;
+		case "lt": return compare(lhs, rhs) < 0;
+		case "lte": return compare(lhs, rhs) <= 0;
+		case "in": return Array.isArray(rhs) && rhs.some((v) => strictEqual(lhs, v));
+		case "nin": return Array.isArray(rhs) && !rhs.some((v) => strictEqual(lhs, v));
+		case "contains": return Array.isArray(lhs) && lhs.some((v) => strictEqual(v, rhs));
+		case "startsWith": return typeof lhs === "string" && typeof rhs === "string" && lhs.startsWith(rhs);
+		case "endsWith": return typeof lhs === "string" && typeof rhs === "string" && lhs.endsWith(rhs);
+		case "isNull": return lhs === null || lhs === void 0;
+		case "isNotNull": return lhs !== null && lhs !== void 0;
+		default: return ((_) => false)(c.op);
+	}
+}
+/**
+* Equality with `Date` awareness. `===` on two `Date` objects with the same
+* millis returns `false`; this normalizes them. Plain primitives use `===`.
+*/
+function strictEqual(a, b) {
+	if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime();
+	if (a instanceof Date && typeof b === "string") return a.toISOString() === b;
+	if (typeof a === "string" && b instanceof Date) return a === b.toISOString();
+	return a === b;
+}
+/**
+* Numeric / chronological comparison. Returns `NaN` (which `compare()`
+* callers handle by returning false for gt/lt/gte/lte) when operands aren't
+* comparable. Dates are compared by their unix timestamp.
+*/
+function compare(a, b) {
+	const av = a instanceof Date ? a.getTime() : a;
+	const bv = b instanceof Date ? b.getTime() : b;
+	if (typeof av === "number" && typeof bv === "number") return av - bv;
+	if (typeof av === "string" && typeof bv === "string") return av < bv ? -1 : av > bv ? 1 : 0;
+	return NaN;
+}
+var ConditionError = class extends Error {
+	name = "ConditionError";
+	code;
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+	}
+};
+const COMPARATORS = new Set([
+	"eq",
+	"neq",
+	"gt",
+	"gte",
+	"lt",
+	"lte",
+	"in",
+	"nin",
+	"contains",
+	"startsWith",
+	"endsWith",
+	"isNull",
+	"isNotNull"
+]);
+const UNARY_OPS = new Set(["isNull", "isNotNull"]);
+/**
+* Validate a condition shape before persisting. Recurses through composites.
+* Throws `ConditionError` so hosts get a stable code + message in API
+* responses (`{ code: 'INVALID_OP', message: '...' }`).
+*/
+function validateCondition(condition) {
+	if (condition === null || typeof condition !== "object") throw new ConditionError("EMPTY", "condition is null or not an object");
+	if (isAllCondition(condition)) {
+		if (condition.all.length === 0) throw new ConditionError("EMPTY_GROUP", "all-group must have at least one branch");
+		condition.all.forEach(validateCondition);
+		return;
+	}
+	if (isAnyCondition(condition)) {
+		if (condition.any.length === 0) throw new ConditionError("EMPTY_GROUP", "any-group must have at least one branch");
+		condition.any.forEach(validateCondition);
+		return;
+	}
+	if (isNotCondition(condition)) {
+		validateCondition(condition.not);
+		return;
+	}
+	if (isFieldCondition(condition)) {
+		if (!COMPARATORS.has(condition.op)) throw new ConditionError("INVALID_OP", `unknown comparator: ${JSON.stringify(condition.op)}`);
+		if (!UNARY_OPS.has(condition.op) && condition.value === void 0) throw new ConditionError("MISSING_VALUE", `comparator '${condition.op}' requires a value`);
+		return;
+	}
+	throw new ConditionError("UNKNOWN_SHAPE", `condition must be a field/all/any/not — got: ${JSON.stringify(condition)}`);
+}
+//#endregion
+export { ConditionError, evaluate, validateCondition };

package/dist/context.d.mts

@@ -1,6 +1,6 @@
 import { IdLike } from "./reference.mjs";
 
-//#region src/context.d.ts
+//#region src/composition/context.d.ts
 /**
  * Operation context threaded through package APIs.
  *

package/dist/{currency-rgUAn5KM.d.mts → currency-B4rSdN7D.d.mts}

@@ -1,6 +1,6 @@
-import { t as Brand } from "./brand-DApaegoR.mjs";
+import { t as Brand } from "./brand-LLXqoh5J.mjs";
 
-//#region src/currency.d.ts
+//#region src/money/currency.d.ts
 /**
  * ISO 4217 currency code (3 uppercase letters).
  *

package/dist/currency.d.mts

@@ -1,2 +1,2 @@
-import { a as convertWithSnapshot, c as minorUnitFactor, i as MINOR_UNIT_FACTOR, l as reverseWithSnapshot, n as CurrencyCode, o as isCurrencyCode, r as FxSnapshot, s as isFxSnapshot, t as CURRENCIES, u as toCurrencyCode } from "./currency-rgUAn5KM.mjs";
+import { a as convertWithSnapshot, c as minorUnitFactor, i as MINOR_UNIT_FACTOR, l as reverseWithSnapshot, n as CurrencyCode, o as isCurrencyCode, r as FxSnapshot, s as isFxSnapshot, t as CURRENCIES, u as toCurrencyCode } from "./currency-B4rSdN7D.mjs";
 export { CURRENCIES, CurrencyCode, FxSnapshot, MINOR_UNIT_FACTOR, convertWithSnapshot, isCurrencyCode, isFxSnapshot, minorUnitFactor, reverseWithSnapshot, toCurrencyCode };

package/dist/currency.mjs

@@ -1,4 +1,4 @@
-//#region src/currency.ts
+//#region src/money/currency.ts
 /**
 * Common ISO 4217 codes. Non-exhaustive — add more at the consumer level if
 * needed. Listed here because shared-types ships with these by default.

package/dist/events.d.mts

@@ -1,4 +1,4 @@
-//#region src/events.d.ts
+//#region src/events/events.d.ts
 /**
  * Domain event transport primitives.
  *

package/dist/events.mjs

@@ -1,4 +1,4 @@
-//#region src/events.ts
+//#region src/events/events.ts
 /**
 * Build a {@link DomainEvent} with auto-filled `id` + `timestamp`. All other
 * `EventMeta` fields are caller-controlled and override the defaults if

package/dist/hold.d.mts

@@ -1,4 +1,4 @@
-//#region src/hold.d.ts
+//#region src/workflow/hold.d.ts
 /**
  * Hold reason value object + collection helpers.
  *

package/dist/hold.mjs

@@ -1,4 +1,4 @@
-//#region src/hold.ts
+//#region src/workflow/hold.ts
 var HoldError = class extends Error {
 	name = "HoldError";
 	code;

package/dist/mixin.d.mts

@@ -0,0 +1,73 @@
+//#region src/composition/mixin.d.ts
+/**
+ * Additive composition for domain entities — without subclassing.
+ *
+ * Most mixin system (good idea, heavy implementation) lets a `Contact`
+ * become a `Contact & Customer` without rewriting the type or copying
+ * fields. We replicate the GOOD bit (additive type composition stored as
+ * nested data) with none of the bad bits (no decorators, no global class
+ * registry, no proxies).
+ *
+ * Pattern: store mixin payloads on a known well-typed key (`mixins.customer`,
+ * `mixins.lead-fit`, …) instead of spreading them onto the entity root. This
+ * keeps the base type stable and lets each mixin own its own keyspace —
+ * additive schema evolution without breaking exhaustiveness.
+ *
+ * @example
+ *   import { withMixin, getMixin, hasMixin } from '@classytic/primitives/mixin';
+ *
+ *   interface Contact { id: string; name: string; mixins?: Record<string, unknown>; }
+ *   interface CustomerFacts { lifetimeValue: number; firstOrderAt: Date; }
+ *
+ *   const c: Contact = { id: 'c1', name: 'Acme' };
+ *   const enriched = withMixin<Contact, 'customer', CustomerFacts>(c, 'customer', {
+ *     lifetimeValue: 9200,
+ *     firstOrderAt: new Date('2024-09-12'),
+ *   });
+ *
+ *   getMixin<CustomerFacts>(enriched, 'customer')?.lifetimeValue; // 9200
+ *   hasMixin(enriched, 'customer');                               // true
+ *
+ *   // Domain stays exhaustive — the base type didn't change, only the
+ *   // optional `mixins` namespace did.
+ */
+/**
+ * Marker interface — entities that participate in the mixin protocol declare
+ * `mixins?: Mixinable['mixins']`. Hosts can opt in retroactively by widening
+ * their existing types via intersection.
+ */
+interface Mixinable {
+  readonly mixins?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Result type: the base `T` with `mixins[K]` typed as `M`. The intersection
+ * keeps callers exhaustive over the original entity while exposing the
+ * mixin payload through a well-typed accessor.
+ */
+type WithMixin<T, K extends string, M> = T & {
+  readonly mixins: Readonly<Record<string, unknown>> & { readonly [P in K]: M };
+};
+/**
+ * Attach (or overwrite) a mixin on a base entity. Returns a NEW object —
+ * never mutates. The other mixins on the entity are preserved by spread.
+ *
+ * Type-level: caller picks the mixin key and the mixin payload shape; we
+ * intersect them into the return type so chained reads stay precise.
+ */
+declare function withMixin<T extends Mixinable, K extends string, M>(base: T, key: K, data: M): WithMixin<T, K, M>;
+/**
+ * Pull a mixin payload off an entity by key. Returns `null` (not `undefined`)
+ * so call sites can use `??` to fall through to a default without ambiguity
+ * with a real `undefined` field on the payload itself.
+ */
+declare function getMixin<M>(entity: Mixinable, key: string): M | null;
+/** Cheap presence check — useful for `if (hasMixin(c, 'customer')) …` branches. */
+declare function hasMixin(entity: Mixinable, key: string): boolean;
+/**
+ * Remove a mixin. Returns a new entity. No-op if the mixin isn't present.
+ * Useful for migrations / GDPR scrubs ("remove `customer` payload but keep
+ * the base `Contact` row").
+ */
+declare function withoutMixin<T extends Mixinable>(entity: T, key: string): T;
+//#endregion
+export { Mixinable, WithMixin, getMixin, hasMixin, withMixin, withoutMixin };

package/dist/mixin.mjs

@@ -0,0 +1,47 @@
+//#region src/composition/mixin.ts
+/**
+* Attach (or overwrite) a mixin on a base entity. Returns a NEW object —
+* never mutates. The other mixins on the entity are preserved by spread.
+*
+* Type-level: caller picks the mixin key and the mixin payload shape; we
+* intersect them into the return type so chained reads stay precise.
+*/
+function withMixin(base, key, data) {
+	return {
+		...base,
+		mixins: {
+			...base.mixins ?? {},
+			[key]: data
+		}
+	};
+}
+/**
+* Pull a mixin payload off an entity by key. Returns `null` (not `undefined`)
+* so call sites can use `??` to fall through to a default without ambiguity
+* with a real `undefined` field on the payload itself.
+*/
+function getMixin(entity, key) {
+	if (entity.mixins === void 0 || entity.mixins === null) return null;
+	const found = entity.mixins[key];
+	return found === void 0 ? null : found;
+}
+/** Cheap presence check — useful for `if (hasMixin(c, 'customer')) …` branches. */
+function hasMixin(entity, key) {
+	return entity.mixins !== void 0 && entity.mixins !== null && entity.mixins[key] !== void 0;
+}
+/**
+* Remove a mixin. Returns a new entity. No-op if the mixin isn't present.
+* Useful for migrations / GDPR scrubs ("remove `customer` payload but keep
+* the base `Contact` row").
+*/
+function withoutMixin(entity, key) {
+	if (!hasMixin(entity, key)) return entity;
+	const next = { ...entity.mixins };
+	delete next[key];
+	return {
+		...entity,
+		mixins: next
+	};
+}
+//#endregion
+export { getMixin, hasMixin, withMixin, withoutMixin };

package/dist/money.d.mts

@@ -1,6 +1,6 @@
-import { n as CurrencyCode } from "./currency-rgUAn5KM.mjs";
+import { n as CurrencyCode } from "./currency-B4rSdN7D.mjs";
 
-//#region src/money.d.ts
+//#region src/money/money.d.ts
 /**
  * Wire-format monetary amount: integer minor units, branded with a phantom
  * currency type so calls like `formatBdt(usdValue)` fail at compile time.

package/dist/money.mjs

@@ -1,5 +1,5 @@
 import { minorUnitFactor } from "./currency.mjs";
-//#region src/money.ts
+//#region src/money/money.ts
 /**
 * Cast a raw number to {@link MinorUnits}. Pass the currency as the second
 * argument to fix the phantom type. With no second arg, `MinorUnits<string>`

package/dist/outbox.d.mts

@@ -1,6 +1,6 @@
 import { DeadLetteredEvent, DomainEvent } from "./events.mjs";
 
-//#region src/outbox.d.ts
+//#region src/events/outbox.d.ts
 /**
  * Options passed to {@link OutboxStore.save} for richer write semantics.
  * Stores may ignore fields they don't support — contract is best-effort.

package/dist/outbox.mjs

@@ -1,4 +1,4 @@
-//#region src/outbox.ts
+//#region src/events/outbox.ts
 /**
 * Thrown by a store when `acknowledge` / `fail` is called by a consumer that
 * does not own the event's current lease.

package/dist/payment-gateway.d.mts

@@ -1,6 +1,6 @@
 import { Money } from "./money.mjs";
 
-//#region src/payment-gateway.d.ts
+//#region src/money/payment-gateway.d.ts
 /**
  * Static capability declaration — providers expose this so the engine
  * can branch on what's supported (e.g. skip the refund button for

package/dist/period.d.mts

@@ -1,4 +1,4 @@
-//#region src/period.d.ts
+//#region src/scheduling/period.d.ts
 /**
  * A closed date range `[start, end]`. Both endpoints inclusive — consumers
  * decide whether to treat them as `[start, end)` at the query layer.

package/dist/period.mjs

@@ -1,4 +1,4 @@
-//#region src/period.ts
+//#region src/scheduling/period.ts
 function isDateRange(value) {
 	return typeof value === "object" && value !== null && value.start instanceof Date && value.end instanceof Date;
 }

package/dist/person.d.mts

@@ -1,4 +1,4 @@
-//#region src/person.d.ts
+//#region src/identity/person.d.ts
 /**
  * Structured person name. Handles the parts most locales need; domains that
  * require more (per-locale honorifics, patronymics) extend from here.

package/dist/person.mjs

@@ -1,4 +1,4 @@
-//#region src/person.ts
+//#region src/identity/person.ts
 function formatFullName(name) {
 	return [
 		name.prefix,

package/dist/phone.d.mts

@@ -0,0 +1,47 @@
+import { Result } from "./result.mjs";
+
+//#region src/identity/phone.d.ts
+type PhoneErrorCode = 'EMPTY' | 'MISSING_PLUS' | 'NOT_E164' | 'TOO_SHORT' | 'TOO_LONG';
+declare class PhoneError extends Error {
+  readonly name = "PhoneError";
+  readonly code: PhoneErrorCode;
+  constructor(code: PhoneErrorCode, message: string);
+}
+/**
+ * Parsed phone number. Stored E.164 (always begins with `+`, digits only after).
+ * `callingCode` is the 1–3 digit country dial code (`'1'` US, `'44'` UK,
+ * `'880'` BD, etc.) — useful for routing without re-parsing.
+ *
+ * Construction goes through `parsePhone()` (never assemble by hand) so the
+ * invariants are guaranteed by the parser.
+ */
+interface PhoneNumber {
+  readonly e164: string;
+  readonly callingCode: string;
+  /** The national-number portion (digits after the calling code). */
+  readonly nationalNumber: string;
+}
+/**
+ * Parse free-form phone input into a normalized `PhoneNumber`. Accepts:
+ *   - `'+14155550182'`           → e164 unchanged
+ *   - `'+1 (415) 555-0182'`     → strips spaces / punctuation
+ *   - `'+1.415.555.0182'`        → strips dots
+ *
+ * Rejects anything without a leading `+` — we don't guess the country.
+ * If the host knows the user's region, prepend the code before calling.
+ */
+declare function parsePhone(input: string): Result<PhoneNumber, PhoneError>;
+/** Convenience: returns the E.164 string. Useful when piping to a transport. */
+declare function formatPhone(phone: PhoneNumber): string;
+/**
+ * Best-effort national-format render: groups the national number into 3-digit
+ * blocks. Not locale-aware — for display polish, hosts should format per
+ * region. Useful as a default in admin UIs.
+ *
+ * @example formatNational(parsePhone('+14155550182').value!) → '+1 415 555 0182'
+ */
+declare function formatNational(phone: PhoneNumber): string;
+/** Type guard. */
+declare function isPhoneNumber(value: unknown): value is PhoneNumber;
+//#endregion
+export { PhoneError, PhoneErrorCode, PhoneNumber, formatNational, formatPhone, isPhoneNumber, parsePhone };