@classytic/primitives 0.1.0

package/dist/money.mjs

@@ -0,0 +1,131 @@
+import { minorUnitFactor } from "./currency.mjs";
+//#region src/money.ts
+var CurrencyMismatchError = class extends Error {
+	name = "CurrencyMismatchError";
+	left;
+	right;
+	constructor(left, right) {
+		super(`Currency mismatch: ${left} vs ${right}`);
+		this.left = left;
+		this.right = right;
+	}
+};
+/**
+* Construct {@link Money} from an integer minor-unit amount.
+*
+* @throws TypeError if `amount` is not a finite integer.
+*/
+function money(amount, currency) {
+	if (!Number.isFinite(amount) || !Number.isInteger(amount)) throw new TypeError(`Money.amount must be a finite integer in minor units, got ${amount}`);
+	return {
+		amount,
+		currency
+	};
+}
+/**
+* Construct {@link Money} from a major-unit number (e.g. dollars, taka) by
+* scaling to the currency's minor unit and rounding half-away-from-zero.
+*
+* Uses `toPrecision(15)` to strip the trailing-bit noise that appears in
+* multiply-then-round (e.g. `0.1 + 0.2 = 0.30000000000000004`). This is
+* enough for the vast majority of decimals encountered in real-world pricing.
+*
+* **Precision caveat.** A handful of decimals cannot be represented exactly
+* in IEEE 754 and will round to the IEEE-closest integer rather than the
+* mathematically-expected one — e.g. `1.005` is stored as `1.00499999…` and
+* rounds to `100` minor units, not `101`. If you need decimal-exact rounding,
+* construct money from a string or use integer minor units directly via
+* {@link money}.
+*
+* @example
+* fromMajor(19.99, 'USD')      // { amount: 1999, currency: 'USD' }
+* fromMajor(0.1 + 0.2, 'USD')  // { amount: 30,   currency: 'USD' }
+* fromMajor(1500,  'JPY')      // { amount: 1500, currency: 'JPY' }
+*/
+function fromMajor(major, currency) {
+	if (!Number.isFinite(major)) throw new TypeError(`fromMajor received non-finite value: ${major}`);
+	const raw = major * minorUnitFactor(currency);
+	const cleaned = Number(raw.toPrecision(15));
+	return {
+		amount: Math.round(Math.abs(cleaned)) * (cleaned < 0 ? -1 : 1),
+		currency
+	};
+}
+/** Convert {@link Money} back to its major-unit floating-point representation. */
+function toMajor(m) {
+	return m.amount / minorUnitFactor(m.currency);
+}
+function assertSameCurrency(a, b) {
+	if (a.currency !== b.currency) throw new CurrencyMismatchError(a.currency, b.currency);
+}
+function addMoney(a, b) {
+	assertSameCurrency(a, b);
+	return {
+		amount: a.amount + b.amount,
+		currency: a.currency
+	};
+}
+function subtractMoney(a, b) {
+	assertSameCurrency(a, b);
+	return {
+		amount: a.amount - b.amount,
+		currency: a.currency
+	};
+}
+/**
+* Multiply money by a scalar. The result is rounded to an integer number of
+* minor units using half-away-from-zero rounding.
+*/
+function multiplyMoney(m, scalar) {
+	if (!Number.isFinite(scalar)) throw new TypeError(`multiplyMoney received non-finite scalar: ${scalar}`);
+	const raw = m.amount * scalar;
+	return {
+		amount: Math.round(Math.abs(raw)) * (raw < 0 ? -1 : 1),
+		currency: m.currency
+	};
+}
+/** Sum a list of {@link Money}. Returns zero in the given currency for empty input. */
+function sumMoney(values, currency) {
+	return values.reduce((acc, v) => addMoney(acc, v), {
+		amount: 0,
+		currency
+	});
+}
+/** Strict equality (amount and currency both match). */
+function equalsMoney(a, b) {
+	return a.amount === b.amount && a.currency === b.currency;
+}
+/**
+* Ordering predicate. Returns -1, 0, or 1. Throws on currency mismatch — use
+* {@link equalsMoney} for a total equality check across currencies.
+*/
+function compareMoney(a, b) {
+	assertSameCurrency(a, b);
+	if (a.amount < b.amount) return -1;
+	if (a.amount > b.amount) return 1;
+	return 0;
+}
+function isZeroMoney(m) {
+	return m.amount === 0;
+}
+function isPositiveMoney(m) {
+	return m.amount > 0;
+}
+function isNegativeMoney(m) {
+	return m.amount < 0;
+}
+function negateMoney(m) {
+	return {
+		amount: m.amount === 0 ? 0 : -m.amount,
+		currency: m.currency
+	};
+}
+function absMoney(m) {
+	return m.amount < 0 ? negateMoney(m) : m;
+}
+/** Structural type guard. */
+function isMoney(value) {
+	return typeof value === "object" && value !== null && typeof value.amount === "number" && Number.isInteger(value.amount) && typeof value.currency === "string";
+}
+//#endregion
+export { CurrencyMismatchError, absMoney, addMoney, compareMoney, equalsMoney, fromMajor, isMoney, isNegativeMoney, isPositiveMoney, isZeroMoney, money, multiplyMoney, negateMoney, subtractMoney, sumMoney, toMajor };

package/dist/outbox.d.mts

@@ -0,0 +1,222 @@
+import { DeadLetteredEvent, DomainEvent } from "./events.mjs";
+
+//#region src/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.
+ */
+interface OutboxWriteOptions {
+  /**
+   * Host-provided DB session/transaction handle for atomic writes. Typed as
+   * `unknown` so stores can accept any backend (mongoose session, pg client,
+   * Prisma tx, etc.) without primitives taking a peer dep.
+   */
+  readonly session?: unknown;
+  /** Earliest time the event should be visible to relay workers (for delayed publishing). */
+  readonly visibleAt?: Date;
+  /** Idempotency key — stores that support it should dedupe on this. */
+  readonly dedupeKey?: string;
+  /** Partition / routing key for sharded transports (Kafka, Redis Streams). */
+  readonly partitionKey?: string;
+  /** Arbitrary headers propagated to the transport layer. */
+  readonly headers?: Readonly<Record<string, string>>;
+}
+/**
+ * Options for {@link OutboxStore.claimPending} — lease-based work claim.
+ * Supports safe multi-worker relay: each worker atomically claims a batch
+ * with a lease TTL, preventing duplicate publishes.
+ */
+interface OutboxClaimOptions {
+  /** Max events to claim. */
+  readonly limit?: number;
+  /** Unique identifier for the claiming worker. */
+  readonly consumerId?: string;
+  /** Lease duration in ms — claim is released automatically after this. */
+  readonly leaseMs?: number;
+  /** Only claim events of these types (optional filter). */
+  readonly types?: readonly string[];
+}
+/** Options for {@link OutboxStore.acknowledge}. */
+interface OutboxAcknowledgeOptions {
+  /** Worker identifier — stores may enforce "only owner can ack". */
+  readonly consumerId?: string;
+}
+/** Options for {@link OutboxStore.fail}. */
+interface OutboxFailOptions {
+  /** Worker identifier — stores may enforce "only owner can fail". */
+  readonly consumerId?: string;
+  /** Schedule retry for a later time (implements backoff). */
+  readonly retryAt?: Date;
+  /** Move the event to dead-letter state (no further retries). */
+  readonly deadLetter?: boolean;
+}
+/** Normalized error info passed to {@link OutboxStore.fail}. */
+interface OutboxErrorInfo {
+  readonly message: string;
+  readonly code?: string;
+}
+/** Context passed to {@link OutboxFailurePolicy}. */
+interface OutboxFailureContext {
+  /** The event whose delivery just failed. */
+  readonly event: DomainEvent;
+  /** The error returned by the transport / handler. */
+  readonly error: Error;
+  /**
+   * Attempt count including this failure (1 on the first fail). Tracked
+   * in-process by the relay; accurate within a single relay process, resets
+   * on restart. For durable attempt counts, the policy can query the store.
+   */
+  readonly attempts: number;
+}
+/**
+ * Decision returned by {@link OutboxFailurePolicy} — controls how the relay
+ * calls `store.fail()` for a failed event.
+ */
+interface OutboxFailureDecision {
+  /** Schedule retry for this time. Omit for immediate (next-poll) retry. */
+  readonly retryAt?: Date;
+  /** Move the event to dead-letter state (no further retries). */
+  readonly deadLetter?: boolean;
+}
+/**
+ * Centralised retry/DLQ policy evaluated by the arc relay on every failure.
+ * Returns the options passed to `store.fail()`.
+ *
+ * ```ts
+ * failurePolicy: ({ attempts }) => {
+ *   if (attempts >= 5) return { deadLetter: true };
+ *   return { retryAt: exponentialBackoff({ attempt: attempts }) };
+ * }
+ * ```
+ */
+type OutboxFailurePolicy = (ctx: OutboxFailureContext) => OutboxFailureDecision | Promise<OutboxFailureDecision>;
+/**
+ * Thrown by a store when `acknowledge` / `fail` is called by a consumer that
+ * does not own the event's current lease.
+ *
+ * Stores that enforce lease ownership MUST throw this (not silently return)
+ * so the relay can detect the mismatch and avoid over-counting successful
+ * deliveries.
+ */
+declare class OutboxOwnershipError extends Error {
+  readonly name = "OutboxOwnershipError";
+  readonly eventId: string;
+  readonly attemptedBy: string;
+  readonly currentOwner: string | null;
+  constructor(eventId: string, attemptedBy: string, currentOwner: string | null);
+}
+/** Thrown when an event missing `type` or `meta.id` is passed to the outbox. */
+declare class InvalidOutboxEventError extends Error {
+  readonly name = "InvalidOutboxEventError";
+  constructor(reason: string);
+}
+/**
+ * Durable storage contract for the transactional outbox pattern.
+ *
+ * **Required methods**: `save`, `getPending`, `acknowledge`.
+ *
+ * **Optional capabilities** — stores opt-in to richer semantics:
+ *
+ *   - `claimPending` — lease-based work claim for multi-worker relay
+ *   - `fail` — failure tracking with retry scheduling and dead-letter
+ *   - `getDeadLettered` — typed DLQ replay surface
+ *   - `purge` — acknowledged event cleanup
+ *
+ * Arc's runtime detects capabilities at runtime and degrades gracefully for
+ * legacy stores that only implement the required methods.
+ *
+ * ## Required semantics
+ *
+ * Implementations MUST honor these contracts — arc's relay depends on them
+ * for correctness of at-least-once delivery:
+ *
+ * 1. **`save` must reject invalid events.** If `event.type` or `event.meta.id`
+ *    is missing/empty, throw — do not persist. Callers pre-validate but
+ *    stores should defend against direct-save code paths.
+ *
+ * 2. **`claimPending` must be atomic.** Two workers calling `claimPending`
+ *    concurrently must never receive the same event. SQL: `SELECT ... FOR
+ *    UPDATE SKIP LOCKED`; Mongo: `findOneAndUpdate` with `{ leaseOwner:
+ *    null }` in the match condition.
+ *
+ * 3. **`acknowledge` / `fail` must throw {@link OutboxOwnershipError} on
+ *    ownership mismatch.** When `options.consumerId` is provided and does
+ *    not match the current lease owner, throw — never silently no-op. The
+ *    relay relies on this signal to avoid counting hijacked events as
+ *    successfully relayed.
+ *
+ * 4. **`acknowledge` on an unknown `eventId` is a no-op.** Keeps the relay
+ *    idempotent when the store has been purged or the event was manually
+ *    removed. Do NOT throw `OutboxOwnershipError` in this case.
+ *
+ * 5. **`fail` must deterministically update lease/visibility.** On success,
+ *    the event MUST become re-claimable (immediately or at `retryAt`) or
+ *    transition to dead-letter. Lease owner should be cleared.
+ *
+ * 6. **Malformed events must never be returned by `getPending` /
+ *    `claimPending`.** If the underlying storage has corrupt rows, the
+ *    store is responsible for quarantining them.
+ */
+interface OutboxStore {
+  /**
+   * Save an event to the outbox (typically called inside a business
+   * transaction). MUST reject events missing `type` or `meta.id` — throw
+   * rather than persist.
+   */
+  save(event: DomainEvent, options?: OutboxWriteOptions): Promise<void>;
+  /**
+   * Get pending (unrelayed) events, ordered FIFO. Multi-worker deployments
+   * should prefer {@link OutboxStore.claimPending}. Events returned MUST be
+   * well-formed (valid `type` and `meta.id`).
+   */
+  getPending(limit: number): Promise<DomainEvent[]>;
+  /**
+   * Atomically claim pending events with a lease. Two concurrent callers
+   * must never receive overlapping events. When implemented, the relay
+   * prefers this over `getPending`.
+   */
+  claimPending?(options?: OutboxClaimOptions): Promise<DomainEvent[]>;
+  /**
+   * Mark event as successfully relayed.
+   *
+   * **Ownership contract**: If `options.consumerId` is provided and does
+   * not match the current lease owner, throw {@link OutboxOwnershipError}.
+   * Unknown `eventId` is a no-op.
+   *
+   * @throws {@link OutboxOwnershipError} on ownership mismatch
+   */
+  acknowledge(eventId: string, options?: OutboxAcknowledgeOptions): Promise<void>;
+  /**
+   * Record a relay failure. When implemented, the relay calls this instead
+   * of stopping the batch — enables retry scheduling and DLQ.
+   *
+   * **Ownership contract**: Same as `acknowledge` — throw
+   * {@link OutboxOwnershipError} on mismatch. After a successful call the
+   * lease owner MUST be cleared and the event MUST be re-claimable (at
+   * `retryAt` if provided) or transitioned to dead-letter.
+   *
+   * @throws {@link OutboxOwnershipError} on ownership mismatch
+   */
+  fail?(eventId: string, error: OutboxErrorInfo, options?: OutboxFailOptions): Promise<void>;
+  /**
+   * Return events currently in dead-letter state as typed
+   * {@link DeadLetteredEvent} envelopes. Closes the loop between
+   * `fail({ deadLetter: true })` and the DLQ replay surface. MUST populate
+   * `error`, `attempts`, `firstFailedAt`, `lastFailedAt` from whatever the
+   * store tracked during `fail()` calls. `handlerName` is optional.
+   */
+  getDeadLettered?(limit: number): Promise<DeadLetteredEvent[]>;
+  /**
+   * Purge old **delivered** events. Scoped to `delivered` state only —
+   * pending, failed, or dead-lettered events MUST NOT be removed.
+   *
+   * - MongoDB: typically done via TTL index on `deliveredAt` (zero-code).
+   * - SQL: scheduled `DELETE WHERE status = 'delivered' AND delivered_at < :cutoff`.
+   * - Redis: `EXPIRE` on delivered keys.
+   *
+   * @returns Number of purged events.
+   */
+  purge?(olderThanMs: number): Promise<number>;
+}
+//#endregion
+export { InvalidOutboxEventError, OutboxAcknowledgeOptions, OutboxClaimOptions, OutboxErrorInfo, OutboxFailOptions, OutboxFailureContext, OutboxFailureDecision, OutboxFailurePolicy, OutboxOwnershipError, OutboxStore, OutboxWriteOptions };

package/dist/outbox.mjs

@@ -0,0 +1,30 @@
+//#region src/outbox.ts
+/**
+* Thrown by a store when `acknowledge` / `fail` is called by a consumer that
+* does not own the event's current lease.
+*
+* Stores that enforce lease ownership MUST throw this (not silently return)
+* so the relay can detect the mismatch and avoid over-counting successful
+* deliveries.
+*/
+var OutboxOwnershipError = class extends Error {
+	name = "OutboxOwnershipError";
+	eventId;
+	attemptedBy;
+	currentOwner;
+	constructor(eventId, attemptedBy, currentOwner) {
+		super(`Outbox ownership mismatch for event "${eventId}": attempted by "${attemptedBy}", current owner is "${currentOwner ?? "none"}". The lease may have expired and been reclaimed by another worker.`);
+		this.eventId = eventId;
+		this.attemptedBy = attemptedBy;
+		this.currentOwner = currentOwner;
+	}
+};
+/** Thrown when an event missing `type` or `meta.id` is passed to the outbox. */
+var InvalidOutboxEventError = class extends Error {
+	name = "InvalidOutboxEventError";
+	constructor(reason) {
+		super(`Invalid outbox event: ${reason}`);
+	}
+};
+//#endregion
+export { InvalidOutboxEventError, OutboxOwnershipError };

package/dist/pagination.d.mts

@@ -0,0 +1,57 @@
+//#region src/pagination.d.ts
+/**
+ * Pagination and sorting primitives shared between repositories, HTTP
+ * controllers, and SDKs. Shapes mirror `@classytic/mongokit`'s result types so
+ * adapters can flow through without translation.
+ */
+type SortDirection = 'asc' | 'desc' | 1 | -1;
+/**
+ * Sort specification — accepts any of:
+ *  - `'field'` / `'-field'` (Mongoose-style prefix)
+ *  - `['field1', '-field2']`
+ *  - `{ field1: 1, field2: -1 }`
+ */
+type SortSpec = string | ReadonlyArray<string> | Readonly<Record<string, SortDirection>>;
+interface PageParams {
+  page?: number;
+  limit?: number;
+  sort?: SortSpec;
+}
+interface KeysetParams {
+  cursor?: string;
+  limit?: number;
+  sort?: SortSpec;
+}
+/**
+ * Offset-paginated response. Mirrors `mongokit.OffsetPaginationResult<T>`.
+ */
+interface OffsetPage<T> {
+  docs: ReadonlyArray<T>;
+  total: number;
+  page: number;
+  limit: number;
+  pages: number;
+  hasNext: boolean;
+  hasPrev: boolean;
+}
+/**
+ * Cursor-paginated response. Mirrors `mongokit.KeysetPaginationResult<T>`.
+ */
+interface KeysetPage<T> {
+  docs: ReadonlyArray<T>;
+  nextCursor: string | null;
+  prevCursor: string | null;
+  limit: number;
+}
+/** Aggregation-based pagination response. */
+interface AggregatePage<T> {
+  docs: ReadonlyArray<T>;
+  total: number;
+  page: number;
+  limit: number;
+  pages: number;
+}
+declare function emptyOffsetPage<T>(limit?: number): OffsetPage<T>;
+declare function emptyKeysetPage<T>(limit?: number): KeysetPage<T>;
+//#endregion
+export { AggregatePage, KeysetPage, KeysetParams, OffsetPage, PageParams, SortDirection, SortSpec, emptyKeysetPage, emptyOffsetPage };

package/dist/pagination.mjs

@@ -0,0 +1,22 @@
+//#region src/pagination.ts
+function emptyOffsetPage(limit = 20) {
+	return {
+		docs: [],
+		total: 0,
+		page: 1,
+		limit,
+		pages: 0,
+		hasNext: false,
+		hasPrev: false
+	};
+}
+function emptyKeysetPage(limit = 20) {
+	return {
+		docs: [],
+		nextCursor: null,
+		prevCursor: null,
+		limit
+	};
+}
+//#endregion
+export { emptyKeysetPage, emptyOffsetPage };

package/dist/period.d.mts

@@ -0,0 +1,46 @@
+//#region src/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.
+ */
+interface DateRange {
+  start: Date;
+  end: Date;
+}
+/**
+ * A named accounting / reporting period. At least one of the resolution fields
+ * (`month`, `quarter`) should be set, or `start`/`end` for ad-hoc ranges.
+ */
+interface Period {
+  /** Four-digit calendar year, e.g. 2026. */
+  year: number;
+  /** 1..12. */
+  month?: number;
+  /** 1..4. */
+  quarter?: 1 | 2 | 3 | 4;
+  /** Ad-hoc override — useful when the period spans a non-calendar boundary. */
+  start?: Date;
+  end?: Date;
+}
+declare function isDateRange(value: unknown): value is DateRange;
+/** True if `d` is inclusively within `range`. */
+declare function isWithin(d: Date, range: DateRange): boolean;
+/** Range duration in milliseconds. */
+declare function rangeDurationMs(range: DateRange): number;
+/**
+ * True if two half-open ranges `[start, end)` overlap.
+ *
+ * Note: the `DateRange` shape documents its endpoints as closed, but
+ * overlap-detection queries almost always want half-open semantics so two
+ * adjacent slots (10-11, 11-12) don't register as a conflict. Consumers
+ * needing fully-closed semantics can still use `isWithin` against each
+ * endpoint.
+ *
+ * Used by:
+ *   - `@classytic/order` booking overlap detection
+ *   - `@classytic/flow` reservation window collision
+ *   - promo / offer campaign window overlap checks
+ */
+declare function rangesOverlap(a: DateRange, b: DateRange): boolean;
+//#endregion
+export { DateRange, Period, isDateRange, isWithin, rangeDurationMs, rangesOverlap };

package/dist/period.mjs

@@ -0,0 +1,31 @@
+//#region src/period.ts
+function isDateRange(value) {
+	return typeof value === "object" && value !== null && value.start instanceof Date && value.end instanceof Date;
+}
+/** True if `d` is inclusively within `range`. */
+function isWithin(d, range) {
+	return d.getTime() >= range.start.getTime() && d.getTime() <= range.end.getTime();
+}
+/** Range duration in milliseconds. */
+function rangeDurationMs(range) {
+	return range.end.getTime() - range.start.getTime();
+}
+/**
+* True if two half-open ranges `[start, end)` overlap.
+*
+* Note: the `DateRange` shape documents its endpoints as closed, but
+* overlap-detection queries almost always want half-open semantics so two
+* adjacent slots (10-11, 11-12) don't register as a conflict. Consumers
+* needing fully-closed semantics can still use `isWithin` against each
+* endpoint.
+*
+* Used by:
+*   - `@classytic/order` booking overlap detection
+*   - `@classytic/flow` reservation window collision
+*   - promo / offer campaign window overlap checks
+*/
+function rangesOverlap(a, b) {
+	return a.start.getTime() < b.end.getTime() && b.start.getTime() < a.end.getTime();
+}
+//#endregion
+export { isDateRange, isWithin, rangeDurationMs, rangesOverlap };

package/dist/person.d.mts

@@ -0,0 +1,44 @@
+//#region src/person.d.ts
+/**
+ * Structured person name. Handles the parts most locales need; domains that
+ * require more (per-locale honorifics, patronymics) extend from here.
+ */
+interface PersonName {
+  given: string;
+  family: string;
+  /** Middle name(s), as a single string preserving author's formatting. */
+  middle?: string;
+  /** Title prefix — Mr./Dr./Eng./etc. */
+  prefix?: string;
+  /** Suffix — Jr./Sr./PhD/etc. */
+  suffix?: string;
+  /** Preferred display name when it differs from formal given/family. */
+  preferred?: string;
+}
+declare function formatFullName(name: PersonName): string;
+declare function formatDisplayName(name: PersonName): string;
+/**
+ * Contact channels for a person. Prefer E.164 for phone when possible.
+ *
+ * The work-vs-personal split exists because compliance / off-boarding flows
+ * (HR) distinguish them, and because marketing opt-outs are per-channel.
+ */
+interface ContactInfo {
+  email?: string;
+  personalEmail?: string;
+  phone?: string;
+  alternatePhone?: string;
+}
+interface EmergencyContact {
+  name: string;
+  relationship: string;
+  phone: string;
+  email?: string;
+}
+/**
+ * Gender as an open string — common values enumerated for tooling, but the
+ * shape accepts any string to stay inclusive and locale-flexible.
+ */
+type Gender = 'male' | 'female' | 'other' | 'prefer-not-to-say' | (string & {});
+//#endregion
+export { ContactInfo, EmergencyContact, Gender, PersonName, formatDisplayName, formatFullName };

package/dist/person.mjs

@@ -0,0 +1,16 @@
+//#region src/person.ts
+function formatFullName(name) {
+	return [
+		name.prefix,
+		name.given,
+		name.middle,
+		name.family,
+		name.suffix
+	].filter((p) => Boolean(p?.trim())).join(" ");
+}
+function formatDisplayName(name) {
+	if (name.preferred?.trim()) return name.preferred;
+	return `${name.given} ${name.family}`.trim();
+}
+//#endregion
+export { formatDisplayName, formatFullName };

package/dist/reference.d.mts

@@ -0,0 +1,39 @@
+//#region src/reference.d.ts
+/**
+ * Minimal structural type for any ID object with a `.toString()` method. Does
+ * NOT depend on `mongoose` — `Types.ObjectId` satisfies this shape
+ * automatically, as do UUIDs from `uuid`, KSUIDs, ULIDs, etc.
+ *
+ * Use this wherever you'd otherwise import `Types.ObjectId` but don't want to
+ * force a runtime dependency on Mongoose.
+ */
+interface ObjectIdLike {
+  toString(): string;
+  toHexString?(): string;
+}
+/** A value that can be used as an identifier — raw string or object-id-like. */
+type IdLike = string | ObjectIdLike;
+/** Coerce any {@link IdLike} to its canonical string form. */
+declare function idToString(id: IdLike): string;
+/**
+ * Polymorphic external reference — points at a resource that may live in
+ * another package, another service, or a different data store altogether.
+ *
+ * Paired with a host-implemented `SourceBridge` (see PACKAGE_RULES.md §7),
+ * this pattern works across single-Mongo, microservice, and mixed-datastore
+ * deployments.
+ */
+interface ExternalRef {
+  /** Opaque identifier — hex ObjectId, UUID, Stripe ID, or any other format. */
+  sourceId: string;
+  /** Logical model / type name — e.g. 'Order', 'StripeCharge', 'PostgresInvoice'. */
+  sourceModel: string;
+}
+/** Typed reference to a document in a specific Mongo collection by ObjectId. */
+interface DocumentRef {
+  collection: string;
+  id: string;
+}
+declare function isExternalRef(value: unknown): value is ExternalRef;
+//#endregion
+export { DocumentRef, ExternalRef, IdLike, ObjectIdLike, idToString, isExternalRef };

package/dist/reference.mjs

@@ -0,0 +1,10 @@
+//#region src/reference.ts
+/** Coerce any {@link IdLike} to its canonical string form. */
+function idToString(id) {
+	return typeof id === "string" ? id : id.toString();
+}
+function isExternalRef(value) {
+	return typeof value === "object" && value !== null && typeof value.sourceId === "string" && typeof value.sourceModel === "string";
+}
+//#endregion
+export { idToString, isExternalRef };