@classytic/primitives 0.1.0

package/dist/cadence.d.mts

@@ -0,0 +1,93 @@
+//#region src/cadence.d.ts
+/**
+ * Recurrence spec + pure date arithmetic.
+ *
+ * Describes "every N days", "every weekday", "on the 15th of each month", etc.
+ * Consumed by `@classytic/order` (blanket / recurring orders, subscription
+ * renewal), `@classytic/flow` (replenishment schedules), and
+ * `@classytic/commission` (vesting periods, statement close).
+ *
+ * No cron parser dep — the `cron` kind stores an opaque string that the host
+ * parses with its own library (node-cron, croner, etc.). This keeps primitives
+ * zero-dep and lets hosts pick whatever cron dialect they want.
+ *
+ * @example
+ * const monthly: Cadence = {
+ *   kind: 'monthly',
+ *   interval: 1,
+ *   dayOfMonth: 15,
+ *   startAt: new Date('2026-01-15T00:00:00Z'),
+ * };
+ * nextOccurrence(monthly, new Date('2026-02-20T00:00:00Z'));
+ * // → 2026-03-15T00:00:00Z
+ */
+type CadenceKind = 'daily' | 'weekly' | 'monthly' | 'yearly' | 'cron';
+/** ISO weekday — 1=Mon … 7=Sun. Matches Temporal + ISO 8601. */
+type IsoWeekday = 1 | 2 | 3 | 4 | 5 | 6 | 7;
+interface CadenceBase {
+  readonly interval: number;
+  readonly startAt: Date;
+  readonly endAt?: Date;
+  /**
+   * Optional timezone IANA name (e.g. `Asia/Dhaka`). Pure functions in this
+   * module operate on UTC Date values; the field is carried for the host to
+   * localize occurrences when displaying. Occurrence math here is UTC-based.
+   */
+  readonly timezone?: string;
+}
+interface DailyCadence extends CadenceBase {
+  readonly kind: 'daily';
+}
+interface WeeklyCadence extends CadenceBase {
+  readonly kind: 'weekly';
+  /**
+   * If provided, only these ISO weekdays count as occurrences; the earliest
+   * matching weekday on or after `startAt` is the first occurrence. If omitted,
+   * the weekday of `startAt` is used.
+   */
+  readonly daysOfWeek?: readonly IsoWeekday[];
+}
+interface MonthlyCadence extends CadenceBase {
+  readonly kind: 'monthly';
+  /**
+   * Day of month, 1–31. If the target month has fewer days (e.g. 31st → Feb),
+   * occurrence snaps to the last day of the month.
+   */
+  readonly dayOfMonth: number;
+}
+interface YearlyCadence extends CadenceBase {
+  readonly kind: 'yearly';
+  /** Calendar month 1–12. */
+  readonly month: number;
+  /** Day of month 1–31. Snaps to last day of month if needed (e.g. Feb 29 → Feb 28 in non-leap years). */
+  readonly dayOfMonth: number;
+}
+interface CronCadence extends CadenceBase {
+  readonly kind: 'cron';
+  /** Opaque cron expression — caller parses with its own cron library. */
+  readonly expression: string;
+}
+type Cadence = DailyCadence | WeeklyCadence | MonthlyCadence | YearlyCadence | CronCadence;
+type CadenceErrorCode = 'INVALID_INTERVAL' | 'INVALID_DAY_OF_MONTH' | 'INVALID_MONTH' | 'INVALID_DAYS_OF_WEEK' | 'INVALID_START_AT' | 'INVALID_END_AT' | 'UNSUPPORTED_CRON';
+declare class CadenceError extends Error {
+  readonly name = "CadenceError";
+  readonly code: CadenceErrorCode;
+  constructor(code: CadenceErrorCode, message: string);
+}
+/** Validate a Cadence spec. Call this before storing host-side. */
+declare function validateCadence(c: Cadence): void;
+/**
+ * Next occurrence strictly after `from`. Returns `null` if the cadence has
+ * ended (endAt passed) or the first occurrence is still in the future.
+ *
+ * Cron cadences return `null` — hosts must parse the expression themselves.
+ */
+declare function nextOccurrence(cadence: Cadence, from: Date): Date | null;
+/**
+ * Enumerate occurrences in `[from, to)` inclusive at `from`, exclusive at `to`.
+ * Returns up to `limit` results (default 10_000) to guard against runaway
+ * misconfigured cadences. Cron returns an empty array.
+ */
+declare function occurrencesBetween(cadence: Cadence, from: Date, to: Date, limit?: number): Date[];
+//#endregion
+export { Cadence, CadenceError, CadenceErrorCode, CadenceKind, CronCadence, DailyCadence, IsoWeekday, MonthlyCadence, WeeklyCadence, YearlyCadence, nextOccurrence, occurrencesBetween, validateCadence };

package/dist/cadence.mjs

@@ -0,0 +1,139 @@
+//#region src/cadence.ts
+var CadenceError = class extends Error {
+	name = "CadenceError";
+	code;
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+	}
+};
+/** Validate a Cadence spec. Call this before storing host-side. */
+function validateCadence(c) {
+	if (!Number.isInteger(c.interval) || c.interval < 1) throw new CadenceError("INVALID_INTERVAL", `interval must be a positive integer, got ${c.interval}`);
+	if (Number.isNaN(c.startAt.getTime())) throw new CadenceError("INVALID_START_AT", "startAt is not a valid Date");
+	if (c.endAt && Number.isNaN(c.endAt.getTime())) throw new CadenceError("INVALID_END_AT", "endAt is not a valid Date");
+	if (c.endAt && c.endAt.getTime() < c.startAt.getTime()) throw new CadenceError("INVALID_END_AT", "endAt must be >= startAt");
+	if (c.kind === "weekly" && c.daysOfWeek) {
+		if (c.daysOfWeek.length === 0) throw new CadenceError("INVALID_DAYS_OF_WEEK", "daysOfWeek cannot be empty");
+		for (const d of c.daysOfWeek) if (!Number.isInteger(d) || d < 1 || d > 7) throw new CadenceError("INVALID_DAYS_OF_WEEK", `daysOfWeek entry must be 1–7, got ${d}`);
+	}
+	if (c.kind === "monthly") assertValidDayOfMonth(c.dayOfMonth);
+	if (c.kind === "yearly") {
+		if (!Number.isInteger(c.month) || c.month < 1 || c.month > 12) throw new CadenceError("INVALID_MONTH", `month must be 1–12, got ${c.month}`);
+		assertValidDayOfMonth(c.dayOfMonth);
+	}
+}
+function assertValidDayOfMonth(day) {
+	if (!Number.isInteger(day) || day < 1 || day > 31) throw new CadenceError("INVALID_DAY_OF_MONTH", `dayOfMonth must be 1–31, got ${day}`);
+}
+/**
+* Next occurrence strictly after `from`. Returns `null` if the cadence has
+* ended (endAt passed) or the first occurrence is still in the future.
+*
+* Cron cadences return `null` — hosts must parse the expression themselves.
+*/
+function nextOccurrence(cadence, from) {
+	validateCadence(cadence);
+	if (cadence.kind === "cron") return null;
+	const fromMs = from.getTime();
+	if (cadence.endAt && fromMs >= cadence.endAt.getTime()) return null;
+	const first = cadence.startAt;
+	if (fromMs < first.getTime()) return first;
+	const next = stepForward(cadence, from);
+	if (next === null) return null;
+	if (cadence.endAt && next.getTime() > cadence.endAt.getTime()) return null;
+	return next;
+}
+/**
+* Enumerate occurrences in `[from, to)` inclusive at `from`, exclusive at `to`.
+* Returns up to `limit` results (default 10_000) to guard against runaway
+* misconfigured cadences. Cron returns an empty array.
+*/
+function occurrencesBetween(cadence, from, to, limit = 1e4) {
+	validateCadence(cadence);
+	if (cadence.kind === "cron") return [];
+	const result = [];
+	let cursor = cadence.startAt.getTime() >= from.getTime() ? cadence.startAt : nextOccurrence(cadence, /* @__PURE__ */ new Date(from.getTime() - 1));
+	while (cursor !== null && cursor.getTime() < to.getTime() && result.length < limit) {
+		if (cursor.getTime() >= from.getTime()) result.push(cursor);
+		cursor = nextOccurrence(cadence, cursor);
+	}
+	return result;
+}
+function stepForward(cadence, from) {
+	switch (cadence.kind) {
+		case "daily": return stepDaily(cadence, from);
+		case "weekly": return stepWeekly(cadence, from);
+		case "monthly": return stepMonthly(cadence, from);
+		case "yearly": return stepYearly(cadence, from);
+		default: return null;
+	}
+}
+function stepDaily(c, from) {
+	const start = c.startAt;
+	const diffDays = Math.floor((from.getTime() - start.getTime()) / (1440 * 60 * 1e3));
+	const nextNthDay = Math.floor(diffDays / c.interval) * c.interval + c.interval;
+	const nextMs = start.getTime() + nextNthDay * 24 * 60 * 60 * 1e3;
+	return new Date(nextMs);
+}
+function stepWeekly(c, from) {
+	const anchor = c.startAt;
+	const sortedDays = [...c.daysOfWeek ?? [isoWeekday(anchor)]].sort((a, b) => a - b);
+	const oneDay = 1440 * 60 * 1e3;
+	const msPerWeek = 7 * oneDay;
+	let cursor = from.getTime() + oneDay;
+	const maxSteps = Math.max(60, c.interval * 14);
+	for (let i = 0; i < maxSteps; i++) {
+		const d = new Date(cursor);
+		if (!sortedDays.includes(isoWeekday(d))) {
+			cursor += oneDay;
+			continue;
+		}
+		if (Math.floor((d.getTime() - anchor.getTime()) / msPerWeek) % c.interval === 0 && d.getTime() >= anchor.getTime()) return withTime(d, anchor);
+		cursor += oneDay;
+	}
+	return new Date(cursor);
+}
+function stepMonthly(c, from) {
+	const anchor = c.startAt;
+	const year = from.getUTCFullYear();
+	const monthIdx = from.getUTCMonth();
+	let candYear = anchor.getUTCFullYear();
+	let candMonth = anchor.getUTCMonth();
+	while (true) {
+		const dayClamped = clampDayOfMonth(c.dayOfMonth, candYear, candMonth);
+		const candidate = new Date(Date.UTC(candYear, candMonth, dayClamped, anchor.getUTCHours(), anchor.getUTCMinutes(), anchor.getUTCSeconds(), anchor.getUTCMilliseconds()));
+		if (candidate.getTime() > from.getTime()) return candidate;
+		candMonth += c.interval;
+		while (candMonth > 11) {
+			candMonth -= 12;
+			candYear += 1;
+		}
+		if (candYear - year > 1e4) return candidate;
+	}
+	return new Date(Date.UTC(year, monthIdx, 1));
+}
+function stepYearly(c, from) {
+	const anchor = c.startAt;
+	const anchorYear = anchor.getUTCFullYear();
+	let candYear = anchorYear;
+	while (true) {
+		const dayClamped = clampDayOfMonth(c.dayOfMonth, candYear, c.month - 1);
+		const candidate = new Date(Date.UTC(candYear, c.month - 1, dayClamped, anchor.getUTCHours(), anchor.getUTCMinutes(), anchor.getUTCSeconds(), anchor.getUTCMilliseconds()));
+		if (candidate.getTime() > from.getTime()) return candidate;
+		candYear += c.interval;
+		if (candYear - anchorYear > 1e4) return candidate;
+	}
+}
+function isoWeekday(d) {
+	return (d.getUTCDay() + 6) % 7 + 1;
+}
+function withTime(d, timeSource) {
+	return new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate(), timeSource.getUTCHours(), timeSource.getUTCMinutes(), timeSource.getUTCSeconds(), timeSource.getUTCMilliseconds()));
+}
+function clampDayOfMonth(day, year, monthIdx) {
+	const lastDay = new Date(Date.UTC(year, monthIdx + 1, 0)).getUTCDate();
+	return Math.min(day, lastDay);
+}
+//#endregion
+export { CadenceError, nextOccurrence, occurrencesBetween, validateCadence };

package/dist/context.d.mts

@@ -0,0 +1,48 @@
+import { IdLike } from "./reference.mjs";
+
+//#region src/context.d.ts
+/**
+ * Operation context threaded through package APIs.
+ *
+ * This is NOT the HTTP request context — it's the minimal identity + tracing
+ * bag that a package needs to scope a domain operation. Hosts map their
+ * request context (Arc, Express, tRPC, worker job) to this shape when calling
+ * into a package.
+ *
+ * All fields are optional so packages can run unauthenticated (e.g. in tests,
+ * workers, migration scripts) without a ceremonial context object.
+ */
+interface OperationContext {
+  /** Authenticated principal (user, service account, API key id). */
+  actorId?: IdLike;
+  /** Tenant / organization / branch scope. Interpretation is host-defined. */
+  organizationId?: IdLike;
+  /** Distributed trace identifier (e.g. OpenTelemetry trace-id). */
+  traceId?: string;
+  /** Correlation identifier, typically per logical operation. */
+  correlationId?: string;
+  /** Request identifier (e.g. Fastify `req.id`). */
+  requestId?: string;
+  /** Idempotency key supplied by the caller. */
+  idempotencyKey?: string;
+  /**
+   * Storage-layer session/transaction handle. Opaque here — the consuming
+   * package is expected to know how to use it (e.g. Mongoose `ClientSession`).
+   */
+  session?: unknown;
+  /**
+   * Soft-delete behaviour toggle — packages that expose delete primitives may
+   * respect this. See PACKAGE_RULES.md §10.
+   */
+  mode?: 'soft' | 'hard';
+  /** Free-form metadata the host may attach (locale, timezone, user-agent…). */
+  metadata?: Readonly<Record<string, unknown>>;
+}
+/** An identity shape — useful on audit fields (`createdBy`, `updatedBy`). */
+interface ActorRef {
+  id: string;
+  type?: 'user' | 'service' | 'system' | 'api-key' | string;
+  name?: string;
+}
+//#endregion
+export { ActorRef, OperationContext };

package/dist/context.mjs

@@ -0,0 +1 @@
+export {};

package/dist/currency.d.mts

@@ -0,0 +1,110 @@
+import { t as Brand } from "./brand-DApaegoR.mjs";
+
+//#region src/currency.d.ts
+/**
+ * ISO 4217 currency code (3 uppercase letters).
+ *
+ * Branded `string` — any 3-letter string is structurally valid, but the brand
+ * prevents accidental mixing with raw strings. Use {@link toCurrencyCode} to
+ * construct one safely.
+ */
+type CurrencyCode = Brand<string, 'CurrencyCode'>;
+/**
+ * Common ISO 4217 codes. Non-exhaustive — add more at the consumer level if
+ * needed. Listed here because shared-types ships with these by default.
+ */
+declare const CURRENCIES: {
+  readonly USD: "USD";
+  readonly EUR: "EUR";
+  readonly GBP: "GBP";
+  readonly JPY: "JPY";
+  readonly CNY: "CNY";
+  readonly INR: "INR";
+  readonly BDT: "BDT";
+  readonly AED: "AED";
+  readonly SAR: "SAR";
+  readonly PKR: "PKR";
+  readonly NPR: "NPR";
+  readonly LKR: "LKR";
+  readonly MYR: "MYR";
+  readonly SGD: "SGD";
+  readonly AUD: "AUD";
+  readonly CAD: "CAD";
+  readonly CHF: "CHF";
+  readonly HKD: "HKD";
+  readonly THB: "THB";
+  readonly IDR: "IDR";
+};
+/**
+ * Number of minor units per major unit for common currencies.
+ *
+ * ISO 4217 defines most currencies with 2 decimal places (cents). A few are
+ * zero-decimal (JPY, KRW) or three-decimal (BHD, KWD, JOD). When a currency
+ * isn't in this table, {@link minorUnitFactor} returns 100 as the safe default.
+ */
+declare const MINOR_UNIT_FACTOR: Readonly<Record<string, number>>;
+/**
+ * Narrow a raw string to a {@link CurrencyCode}. Returns `null` if the string
+ * is not a valid ISO 4217 format (3 uppercase letters). This does not verify
+ * the code is registered with ISO — use your own whitelist for that.
+ */
+declare function toCurrencyCode(value: string): CurrencyCode | null;
+/** Type predicate for `unknown` input. */
+declare function isCurrencyCode(value: unknown): value is CurrencyCode;
+/**
+ * Minor units per major unit (e.g. 100 for USD, 1 for JPY, 1000 for KWD).
+ * Falls back to 100 when the currency is unknown — matches the ISO 4217 default.
+ */
+declare function minorUnitFactor(currency: string): number;
+/**
+ * Frozen FX conversion record — the cost of record for cross-currency
+ * transactions. Stored alongside a base-currency amount at the seam where
+ * currency crossed (procurement receipt, landed-cost entry, foreign refund).
+ *
+ * Invariant: once written, never mutated. Revaluation is a new snapshot on
+ * a new document — rewriting an existing snapshot corrupts audit history.
+ *
+ * `rate` is expressed as: 1 sourceCurrency = rate * baseCurrency
+ * (e.g. USD→BDT at 110 means rate = 110, so sourceAmount 10 USD → baseAmount 1100 BDT).
+ * This matches how banks quote — the source is the "from" currency.
+ */
+interface FxSnapshot {
+  /** Currency the transaction was invoiced / quoted in. ISO 4217. */
+  sourceCurrency: string;
+  /** Organisation's functional currency the base amount is expressed in. */
+  baseCurrency: string;
+  /** 1 unit of sourceCurrency equals this many units of baseCurrency. */
+  rate: number;
+  /** When the rate was captured — NOT when the document was last touched. */
+  snapshotAt: Date;
+  /**
+   * Optional provenance tag — e.g. 'manual', 'bangladesh-bank',
+   * 'openexchangerates.org', 'supplier-invoice'. Free-form; hosts use it for
+   * audit filtering and re-pricing policy.
+   */
+  source?: string;
+}
+/**
+ * Apply an {@link FxSnapshot} to a source-currency amount. Returns the
+ * equivalent base-currency amount. No rounding — callers that persist into
+ * an integer minor-unit column must round explicitly with a deterministic
+ * rule (`Math.round`, banker's rounding, floor for duty-conservative
+ * postings, etc.).
+ */
+declare function convertWithSnapshot(sourceAmount: number, fx: FxSnapshot): number;
+/**
+ * Reverse an {@link FxSnapshot} — reconstruct the source-currency amount
+ * from a stored base amount. Useful for reporting "cost in original
+ * currency". Not round-trip safe under rounding; prefer storing the
+ * original source amount alongside the base amount when audit fidelity
+ * matters.
+ */
+declare function reverseWithSnapshot(baseAmount: number, fx: FxSnapshot): number;
+/**
+ * Structural validation — checks shape only. Does NOT verify the rate is
+ * economically sensible (8.5 USD→BDT would pass this check). Host-level
+ * guards / anomaly detection handle that.
+ */
+declare function isFxSnapshot(value: unknown): value is FxSnapshot;
+//#endregion
+export { CURRENCIES, CurrencyCode, FxSnapshot, MINOR_UNIT_FACTOR, convertWithSnapshot, isCurrencyCode, isFxSnapshot, minorUnitFactor, reverseWithSnapshot, toCurrencyCode };

package/dist/currency.mjs

@@ -0,0 +1,116 @@
+//#region src/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.
+*/
+const CURRENCIES = {
+	USD: "USD",
+	EUR: "EUR",
+	GBP: "GBP",
+	JPY: "JPY",
+	CNY: "CNY",
+	INR: "INR",
+	BDT: "BDT",
+	AED: "AED",
+	SAR: "SAR",
+	PKR: "PKR",
+	NPR: "NPR",
+	LKR: "LKR",
+	MYR: "MYR",
+	SGD: "SGD",
+	AUD: "AUD",
+	CAD: "CAD",
+	CHF: "CHF",
+	HKD: "HKD",
+	THB: "THB",
+	IDR: "IDR"
+};
+/**
+* Number of minor units per major unit for common currencies.
+*
+* ISO 4217 defines most currencies with 2 decimal places (cents). A few are
+* zero-decimal (JPY, KRW) or three-decimal (BHD, KWD, JOD). When a currency
+* isn't in this table, {@link minorUnitFactor} returns 100 as the safe default.
+*/
+const MINOR_UNIT_FACTOR = {
+	USD: 100,
+	EUR: 100,
+	GBP: 100,
+	JPY: 1,
+	CNY: 100,
+	INR: 100,
+	BDT: 100,
+	AED: 100,
+	SAR: 100,
+	PKR: 100,
+	NPR: 100,
+	LKR: 100,
+	MYR: 100,
+	SGD: 100,
+	AUD: 100,
+	CAD: 100,
+	CHF: 100,
+	HKD: 100,
+	THB: 100,
+	IDR: 100,
+	KRW: 1,
+	VND: 1,
+	BHD: 1e3,
+	KWD: 1e3,
+	JOD: 1e3,
+	OMR: 1e3,
+	TND: 1e3
+};
+const CURRENCY_PATTERN = /^[A-Z]{3}$/;
+/**
+* Narrow a raw string to a {@link CurrencyCode}. Returns `null` if the string
+* is not a valid ISO 4217 format (3 uppercase letters). This does not verify
+* the code is registered with ISO — use your own whitelist for that.
+*/
+function toCurrencyCode(value) {
+	return CURRENCY_PATTERN.test(value) ? value : null;
+}
+/** Type predicate for `unknown` input. */
+function isCurrencyCode(value) {
+	return typeof value === "string" && CURRENCY_PATTERN.test(value);
+}
+/**
+* Minor units per major unit (e.g. 100 for USD, 1 for JPY, 1000 for KWD).
+* Falls back to 100 when the currency is unknown — matches the ISO 4217 default.
+*/
+function minorUnitFactor(currency) {
+	return MINOR_UNIT_FACTOR[currency] ?? 100;
+}
+/**
+* Apply an {@link FxSnapshot} to a source-currency amount. Returns the
+* equivalent base-currency amount. No rounding — callers that persist into
+* an integer minor-unit column must round explicitly with a deterministic
+* rule (`Math.round`, banker's rounding, floor for duty-conservative
+* postings, etc.).
+*/
+function convertWithSnapshot(sourceAmount, fx) {
+	return sourceAmount * fx.rate;
+}
+/**
+* Reverse an {@link FxSnapshot} — reconstruct the source-currency amount
+* from a stored base amount. Useful for reporting "cost in original
+* currency". Not round-trip safe under rounding; prefer storing the
+* original source amount alongside the base amount when audit fidelity
+* matters.
+*/
+function reverseWithSnapshot(baseAmount, fx) {
+	if (fx.rate === 0) throw new Error("FxSnapshot.rate must be non-zero");
+	return baseAmount / fx.rate;
+}
+/**
+* Structural validation — checks shape only. Does NOT verify the rate is
+* economically sensible (8.5 USD→BDT would pass this check). Host-level
+* guards / anomaly detection handle that.
+*/
+function isFxSnapshot(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const v = value;
+	return typeof v.sourceCurrency === "string" && typeof v.baseCurrency === "string" && typeof v.rate === "number" && Number.isFinite(v.rate) && v.rate > 0 && v.snapshotAt instanceof Date;
+}
+//#endregion
+export { CURRENCIES, MINOR_UNIT_FACTOR, convertWithSnapshot, isCurrencyCode, isFxSnapshot, minorUnitFactor, reverseWithSnapshot, toCurrencyCode };

package/dist/errors.d.mts

@@ -0,0 +1,50 @@
+//#region src/errors.d.ts
+/**
+ * Standard error contract — a framework-agnostic JSON shape that maps cleanly
+ * to HTTP responses, worker failure logs, and inter-service errors. Matches
+ * RFC 7807 (`application/problem+json`) loosely.
+ *
+ * Packages should throw `Error` instances. Hosts (HTTP adapters, workers)
+ * serialize those errors into this shape on the wire.
+ */
+interface ErrorContract {
+  /** Machine-readable, hierarchical code — e.g. 'order.validation.missing_line'. */
+  code: string;
+  /** Human-readable, safe-for-client message. */
+  message: string;
+  /** Suggested HTTP status code — hosts may override. */
+  status?: number;
+  /** Field-scoped validation errors. */
+  details?: ReadonlyArray<ErrorDetail>;
+  /** Correlation / trace identifier for support lookups. */
+  correlationId?: string;
+  /** Non-PII metadata (safe to log, safe to return to clients). */
+  meta?: Readonly<Record<string, unknown>>;
+}
+interface ErrorDetail {
+  /** Dot-path pointer to the offending field, e.g. 'lines.0.quantity'. */
+  path?: string;
+  code: string;
+  message: string;
+  meta?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Canonical error codes. Packages add their own (`order.validation.*`,
+ * `payment.gateway.*`) — these are the cross-cutting ones.
+ */
+declare const ERROR_CODES: {
+  readonly VALIDATION: "validation_error";
+  readonly NOT_FOUND: "not_found";
+  readonly CONFLICT: "conflict";
+  readonly UNAUTHORIZED: "unauthorized";
+  readonly FORBIDDEN: "forbidden";
+  readonly RATE_LIMITED: "rate_limited";
+  readonly IDEMPOTENCY_CONFLICT: "idempotency_conflict";
+  readonly PRECONDITION_FAILED: "precondition_failed";
+  readonly INTERNAL: "internal_error";
+  readonly UNAVAILABLE: "service_unavailable";
+  readonly TIMEOUT: "timeout";
+};
+type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
+//#endregion
+export { ERROR_CODES, ErrorCode, ErrorContract, ErrorDetail };

package/dist/errors.mjs

@@ -0,0 +1,20 @@
+//#region src/errors.ts
+/**
+* Canonical error codes. Packages add their own (`order.validation.*`,
+* `payment.gateway.*`) — these are the cross-cutting ones.
+*/
+const ERROR_CODES = {
+	VALIDATION: "validation_error",
+	NOT_FOUND: "not_found",
+	CONFLICT: "conflict",
+	UNAUTHORIZED: "unauthorized",
+	FORBIDDEN: "forbidden",
+	RATE_LIMITED: "rate_limited",
+	IDEMPOTENCY_CONFLICT: "idempotency_conflict",
+	PRECONDITION_FAILED: "precondition_failed",
+	INTERNAL: "internal_error",
+	UNAVAILABLE: "service_unavailable",
+	TIMEOUT: "timeout"
+};
+//#endregion
+export { ERROR_CODES };