@classytic/primitives 0.19.0 → 0.21.0

package/dist/cadence.d.mts

@@ -1,93 +1,2 @@
-//#region src/scheduling/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
+import { a as CronCadence, c as MonthlyCadence, d as nextOccurrence, f as occurrencesBetween, i as CadenceKind, l as WeeklyCadence, n as CadenceError, o as DailyCadence, p as validateCadence, r as CadenceErrorCode, s as IsoWeekday, t as Cadence, u as YearlyCadence } from "./cadence-5X6TiD49.mjs";
 export { Cadence, CadenceError, CadenceErrorCode, CadenceKind, CronCadence, DailyCadence, IsoWeekday, MonthlyCadence, WeeklyCadence, YearlyCadence, nextOccurrence, occurrencesBetween, validateCadence };

package/dist/cadence.mjs

@@ -1,4 +1,27 @@
+import { addCivilDays, civilDate, civilDateOf, civilDateToInstant, civilDaysBetween, isValidTimeZone, localTimeParts } from "./timezone.mjs";
 //#region src/scheduling/cadence.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
+*/
 var CadenceError = class extends Error {
 	name = "CadenceError";
 	code;
@@ -13,6 +36,7 @@ function validateCadence(c) {
 	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.timezone !== void 0 && !isValidTimeZone(c.timezone)) throw new CadenceError("INVALID_TIMEZONE", `timezone must be a valid IANA zone name (e.g. 'Asia/Dhaka'), got '${c.timezone}'`);
 	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}`);
@@ -61,17 +85,122 @@ function occurrencesBetween(cadence, from, to, limit = 1e4) {
 	return result;
 }
 function stepForward(cadence, from) {
+	const zone = cadence.timezone;
 	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);
+		case "daily": return zone === void 0 ? stepDaily(cadence, from) : stepDailyZoned(cadence, from, zone);
+		case "weekly": return zone === void 0 ? stepWeekly(cadence, from) : stepWeeklyZoned(cadence, from, zone);
+		case "monthly": return zone === void 0 ? stepMonthly(cadence, from) : stepMonthlyZoned(cadence, from, zone);
+		case "yearly": return zone === void 0 ? stepYearly(cadence, from) : stepYearlyZoned(cadence, from, zone);
 		default: return null;
 	}
 }
+/**
+* The anchor's LOCAL wall clock. Seconds and milliseconds come straight from
+* the instant because every modern IANA offset is a whole number of minutes —
+* they are the same in every zone.
+*/
+function wallClockOf(instant, zone) {
+	const cd = civilDateOf(instant, zone);
+	const { hour, minute } = localTimeParts(instant, zone);
+	return {
+		year: Number(cd.slice(0, 4)),
+		month: Number(cd.slice(5, 7)),
+		day: Number(cd.slice(8, 10)),
+		hour,
+		minute,
+		second: instant.getUTCSeconds(),
+		millisecond: instant.getUTCMilliseconds()
+	};
+}
+const pad2 = (n) => String(n).padStart(2, "0");
+function civilOf(year, month, day) {
+	return civilDate(`${String(year).padStart(4, "0")}-${pad2(month)}-${pad2(day)}`);
+}
+/** Bind a local calendar day + the anchor's local time-of-day to an instant. */
+function bindWall(cd, wall, zone) {
+	return civilDateToInstant(cd, zone, {
+		hour: wall.hour,
+		minute: wall.minute,
+		second: wall.second,
+		millisecond: wall.millisecond
+	});
+}
+/** Occurrences are anchor-local-date + n×interval LOCAL days, at the anchor's local time. */
+function stepDailyZoned(c, from, zone) {
+	const wall = wallClockOf(c.startAt, zone);
+	const anchorCd = civilOf(wall.year, wall.month, wall.day);
+	const elapsed = civilDaysBetween(anchorCd, civilDateOf(from, zone));
+	let n = Math.max(0, Math.floor(elapsed / c.interval) * c.interval);
+	for (let i = 0; i < 1e3; i++) {
+		const candidate = bindWall(addCivilDays(anchorCd, n), wall, zone);
+		if (candidate.getTime() > from.getTime()) return candidate;
+		n += c.interval;
+	}
+	return bindWall(addCivilDays(anchorCd, n), wall, zone);
+}
+/** ISO weekday of a civil date — zone-free, a calendar day has a determinate weekday. */
+function isoWeekdayOfCivil(cd) {
+	const utc = Date.UTC(Number(cd.slice(0, 4)), Number(cd.slice(5, 7)) - 1, Number(cd.slice(8, 10)));
+	return (new Date(utc).getUTCDay() + 6) % 7 + 1;
+}
+function stepWeeklyZoned(c, from, zone) {
+	const wall = wallClockOf(c.startAt, zone);
+	const anchorCd = civilOf(wall.year, wall.month, wall.day);
+	const targetDays = c.daysOfWeek ?? [isoWeekdayOfCivil(anchorCd)];
+	let cursor = civilDateOf(from, zone);
+	const maxSteps = Math.max(60, c.interval * 14) + 2;
+	for (let i = 0; i < maxSteps; i++) {
+		if (targetDays.includes(isoWeekdayOfCivil(cursor))) {
+			const weeksSinceAnchor = Math.floor(civilDaysBetween(anchorCd, cursor) / 7);
+			if (weeksSinceAnchor >= 0 && weeksSinceAnchor % c.interval === 0) {
+				const candidate = bindWall(cursor, wall, zone);
+				if (candidate.getTime() > from.getTime()) return candidate;
+			}
+		}
+		cursor = addCivilDays(cursor, 1);
+	}
+	return bindWall(cursor, wall, zone);
+}
+function stepMonthlyZoned(c, from, zone) {
+	const wall = wallClockOf(c.startAt, zone);
+	let candYear = wall.year;
+	let candMonth = wall.month;
+	const fromCd = civilDateOf(from, zone);
+	const monthsDiff = (Number(fromCd.slice(0, 4)) - wall.year) * 12 + (Number(fromCd.slice(5, 7)) - wall.month);
+	if (monthsDiff > 0) {
+		const aligned = Math.floor(monthsDiff / c.interval) * c.interval;
+		const abs = candYear * 12 + (candMonth - 1) + aligned;
+		candYear = Math.floor(abs / 12);
+		candMonth = abs % 12 + 1;
+	}
+	for (let i = 0; i < 1e3; i++) {
+		const day = clampDayOfMonth(c.dayOfMonth, candYear, candMonth - 1);
+		const candidate = bindWall(civilOf(candYear, candMonth, day), wall, zone);
+		if (candidate.getTime() > from.getTime()) return candidate;
+		candMonth += c.interval;
+		while (candMonth > 12) {
+			candMonth -= 12;
+			candYear += 1;
+		}
+	}
+	return bindWall(civilOf(candYear, candMonth, clampDayOfMonth(c.dayOfMonth, candYear, candMonth - 1)), wall, zone);
+}
+function stepYearlyZoned(c, from, zone) {
+	const wall = wallClockOf(c.startAt, zone);
+	let candYear = wall.year;
+	const yearsDiff = Number(civilDateOf(from, zone).slice(0, 4)) - wall.year;
+	if (yearsDiff > 0) candYear += Math.floor(yearsDiff / c.interval) * c.interval;
+	for (let i = 0; i < 1e3; i++) {
+		const day = clampDayOfMonth(c.dayOfMonth, candYear, c.month - 1);
+		const candidate = bindWall(civilOf(candYear, c.month, day), wall, zone);
+		if (candidate.getTime() > from.getTime()) return candidate;
+		candYear += c.interval;
+	}
+	return bindWall(civilOf(candYear, c.month, clampDayOfMonth(c.dayOfMonth, candYear, c.month - 1)), wall, zone);
+}
 function stepDaily(c, from) {
 	const start = c.startAt;
-	const diffDays = Math.floor((from.getTime() - start.getTime()) / (1440 * 60 * 1e3));
+	const diffDays = Math.floor((from.getTime() - start.getTime()) / 864e5);
 	const nextNthDay = Math.floor(diffDays / c.interval) * c.interval + c.interval;
 	const nextMs = start.getTime() + nextNthDay * 24 * 60 * 60 * 1e3;
 	return new Date(nextMs);
@@ -79,7 +208,7 @@ function stepDaily(c, from) {
 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 oneDay = 864e5;
 	const msPerWeek = 7 * oneDay;
 	let cursor = from.getTime() + oneDay;
 	const maxSteps = Math.max(60, c.interval * 14);

package/dist/calendar-DJWSbcgE.d.mts

@@ -0,0 +1,46 @@
+//#region src/scheduling/calendar.d.ts
+/**
+ * Calendar boundaries + arithmetic — the ONE place the stack computes
+ * "start of day / month", weekday, and month/day/year addition, so no package
+ * hand-rolls it with server-LOCAL `Date` methods (`getFullYear`/`getMonth`/
+ * `getDate`/`getDay`), which silently shift with the deploy machine's `TZ` env.
+ *
+ * Every function is PURE and takes a fixed **UTC offset in minutes** (east of
+ * UTC — `360` = UTC+6 / Asia-Dhaka). Same convention as `cadence` / `sla-policy`:
+ * no IANA tz database, no DST. A fixed offset is exact for zones without DST
+ * (e.g. Bangladesh, India, most of Asia) and is what a "daily limit resets at
+ * local midnight" boundary needs. For DST-correct wall-clock math the host
+ * resolves the offset for the instant and passes it in.
+ *
+ * `Date` instants are UTC epoch and timezone-independent — these helpers only
+ * decide WHERE the day/month boundary falls, never how "now" is recorded.
+ *
+ * Resolving that offset from an IANA zone name is `/timezone`'s job — the
+ * two compose: `startOfMonth(instant, zoneOffsetMinutes(instant, zone))`.
+ * For a DST-exact DAY boundary prefer the civil-date round-trip from
+ * `/timezone`: `civilDateToInstant(civilDateOf(instant, zone), zone)`.
+ */
+/** Minutes east of UTC. `0` = UTC, `360` = UTC+6 (Asia/Dhaka), `-300` = UTC-5. */
+type UtcOffsetMinutes = number;
+/**
+ * The absolute instant of local midnight for the day CONTAINING `instant`, in
+ * the given offset. `startOfDay(2026-07-02T03:00Z, 360)` → `2026-07-01T18:00Z`
+ * (Dhaka midnight). With `offsetMinutes = 0` it's plain UTC midnight.
+ */
+declare function startOfDay(instant: Date, offsetMinutes?: UtcOffsetMinutes): Date;
+/** The absolute instant of the first-of-month midnight, in the given offset. */
+declare function startOfMonth(instant: Date, offsetMinutes?: UtcOffsetMinutes): Date;
+/** ISO weekday (1 = Monday … 7 = Sunday) of `instant` in the given offset. */
+declare function isoWeekday(instant: Date, offsetMinutes?: UtcOffsetMinutes): number;
+/** Add whole days as an exact 24h × n duration (offset-agnostic, no DST skew). */
+declare function addDays(instant: Date, days: number): Date;
+/**
+ * Add calendar months in UTC, clamping the day so month-ends never overflow
+ * (`addMonths(Jan 31, 1)` → Feb 28/29). Use for subscription/access periods
+ * instead of local `setMonth(getMonth() + n)`.
+ */
+declare function addMonths(instant: Date, months: number): Date;
+/** Add calendar years in UTC (clamps Feb 29 → Feb 28 on non-leap years). */
+declare function addYears(instant: Date, years: number): Date;
+//#endregion
+export { isoWeekday as a, addYears as i, addDays as n, startOfDay as o, addMonths as r, startOfMonth as s, UtcOffsetMinutes as t };

package/dist/calendar.d.mts

@@ -1,46 +1,2 @@
-//#region src/scheduling/calendar.d.ts
-/**
- * Calendar boundaries + arithmetic — the ONE place the stack computes
- * "start of day / month", weekday, and month/day/year addition, so no package
- * hand-rolls it with server-LOCAL `Date` methods (`getFullYear`/`getMonth`/
- * `getDate`/`getDay`), which silently shift with the deploy machine's `TZ` env.
- *
- * Every function is PURE and takes a fixed **UTC offset in minutes** (east of
- * UTC — `360` = UTC+6 / Asia-Dhaka). Same convention as `cadence` / `sla-policy`:
- * no IANA tz database, no DST. A fixed offset is exact for zones without DST
- * (e.g. Bangladesh, India, most of Asia) and is what a "daily limit resets at
- * local midnight" boundary needs. For DST-correct wall-clock math the host
- * resolves the offset for the instant and passes it in.
- *
- * `Date` instants are UTC epoch and timezone-independent — these helpers only
- * decide WHERE the day/month boundary falls, never how "now" is recorded.
- *
- * Resolving that offset from an IANA zone name is `/timezone`'s job — the
- * two compose: `startOfMonth(instant, zoneOffsetMinutes(instant, zone))`.
- * For a DST-exact DAY boundary prefer the civil-date round-trip from
- * `/timezone`: `civilDateToInstant(civilDateOf(instant, zone), zone)`.
- */
-/** Minutes east of UTC. `0` = UTC, `360` = UTC+6 (Asia/Dhaka), `-300` = UTC-5. */
-type UtcOffsetMinutes = number;
-/**
- * The absolute instant of local midnight for the day CONTAINING `instant`, in
- * the given offset. `startOfDay(2026-07-02T03:00Z, 360)` → `2026-07-01T18:00Z`
- * (Dhaka midnight). With `offsetMinutes = 0` it's plain UTC midnight.
- */
-declare function startOfDay(instant: Date, offsetMinutes?: UtcOffsetMinutes): Date;
-/** The absolute instant of the first-of-month midnight, in the given offset. */
-declare function startOfMonth(instant: Date, offsetMinutes?: UtcOffsetMinutes): Date;
-/** ISO weekday (1 = Monday … 7 = Sunday) of `instant` in the given offset. */
-declare function isoWeekday(instant: Date, offsetMinutes?: UtcOffsetMinutes): number;
-/** Add whole days as an exact 24h × n duration (offset-agnostic, no DST skew). */
-declare function addDays(instant: Date, days: number): Date;
-/**
- * Add calendar months in UTC, clamping the day so month-ends never overflow
- * (`addMonths(Jan 31, 1)` → Feb 28/29). Use for subscription/access periods
- * instead of local `setMonth(getMonth() + n)`.
- */
-declare function addMonths(instant: Date, months: number): Date;
-/** Add calendar years in UTC (clamps Feb 29 → Feb 28 on non-leap years). */
-declare function addYears(instant: Date, years: number): Date;
-//#endregion
+import { a as isoWeekday, i as addYears, n as addDays, o as startOfDay, r as addMonths, s as startOfMonth, t as UtcOffsetMinutes } from "./calendar-DJWSbcgE.mjs";
 export { UtcOffsetMinutes, addDays, addMonths, addYears, isoWeekday, startOfDay, startOfMonth };

package/dist/calendar.mjs

@@ -9,13 +9,13 @@ const DAY_MS = 864e5;
 function startOfDay(instant, offsetMinutes = 0) {
 	const shifted = new Date(instant.getTime() + offsetMinutes * MINUTE_MS);
 	const localMidnightAsUtc = Date.UTC(shifted.getUTCFullYear(), shifted.getUTCMonth(), shifted.getUTCDate());
-	return new Date(localMidnightAsUtc - offsetMinutes * MINUTE_MS);
+	return /* @__PURE__ */ new Date(localMidnightAsUtc - offsetMinutes * MINUTE_MS);
 }
 /** The absolute instant of the first-of-month midnight, in the given offset. */
 function startOfMonth(instant, offsetMinutes = 0) {
 	const shifted = new Date(instant.getTime() + offsetMinutes * MINUTE_MS);
 	const localFirstAsUtc = Date.UTC(shifted.getUTCFullYear(), shifted.getUTCMonth(), 1);
-	return new Date(localFirstAsUtc - offsetMinutes * MINUTE_MS);
+	return /* @__PURE__ */ new Date(localFirstAsUtc - offsetMinutes * MINUTE_MS);
 }
 /** ISO weekday (1 = Monday … 7 = Sunday) of `instant` in the given offset. */
 function isoWeekday(instant, offsetMinutes = 0) {

package/dist/canonical.mjs

@@ -54,6 +54,23 @@ function canonicalize(value, seen) {
 	seen.add(obj);
 	try {
 		if (Array.isArray(value)) return `[${value.map((v) => canonicalize(v, seen)).join(",")}]`;
+		/**
+		* Reject CLASS INSTANCES — the silent-collapse hole.
+		*
+		* `Object.keys()` sees only own enumerable properties, so a `Types.ObjectId`,
+		* a `Buffer`, a `URL` or a hydrated Mongoose subdocument serializes as `{}`
+		* (or as a digit-keyed byte map). The digest then ignores the value entirely:
+		* two manifests referencing DIFFERENT documents hash identically, and the
+		* integrity check this module exists to provide reports "unchanged". That is
+		* the same failure mode the explicit `Date` branch above was written to
+		* prevent, so it gets the same treatment — an unsupported type FAILS.
+		*
+		* Callers holding ORM values project them to plain data first (see
+		* spine-accounting's `plainRef` / `plainSummary`); this makes that discipline
+		* enforced rather than remembered.
+		*/
+		const proto = Object.getPrototypeOf(value);
+		if (proto !== null && proto !== Object.prototype) throw new CanonicalizeError(`class instance '${value.constructor?.name ?? "unknown"}' is not serializable — its own enumerable keys are not its value, so it would digest as {} and silently defeat the checksum. Project it to a plain object first.`);
 		const rec = value;
 		return `{${Object.keys(rec).sort().map((k) => `${JSON.stringify(k)}:${canonicalize(rec[k], seen)}`).join(",")}}`;
 	} finally {

package/dist/condition.mjs

@@ -83,7 +83,7 @@ var ConditionError = class extends Error {
 		this.code = code;
 	}
 };
-const COMPARATORS = new Set([
+const COMPARATORS = /* @__PURE__ */ new Set([
 	"eq",
 	"neq",
 	"gt",
@@ -98,7 +98,7 @@ const COMPARATORS = new Set([
 	"isNull",
 	"isNotNull"
 ]);
-const UNARY_OPS = new Set(["isNull", "isNotNull"]);
+const UNARY_OPS = /* @__PURE__ */ new Set(["isNull", "isNotNull"]);
 /**
 * Validate a condition shape before persisting. Recurses through composites.
 * Throws `ConditionError` so hosts get a stable code + message in API

package/dist/context.d.mts

@@ -1,5 +1,4 @@
 import { IdLike } from "./reference.mjs";
-
 //#region src/composition/context.d.ts
 /**
  * Operation context threaded through package APIs.
@@ -38,6 +37,33 @@ interface OperationContext {
   /** Free-form metadata the host may attach (locale, timezone, user-agent…). */
   metadata?: Readonly<Record<string, unknown>>;
 }
+/**
+ * Structured logger — OBJECT-FIRST (`warn(fields, message)`), the pino / `fastify.log`
+ * convention.
+ *
+ * ## Why this is separate from `ErrorLogger` / `EventLogger`
+ *
+ * Those two (in `primitives/events`) are MESSAGE-FIRST — `error(message, ...args)`, the console
+ * convention — and `EventLogger`'s own docblock notes it mirrors arc's. The two conventions are
+ * not interchangeable: swapping them silently logs an object where a format string was expected,
+ * so a port must say which one it wants.
+ *
+ * This lives here rather than being re-declared per package because it was already declared per
+ * package: an identical object-first shape existed in `spine-kit` as `PlacementLogger`, and the
+ * next package needing one would have made a fourth. A logger is shared vocabulary, not domain.
+ *
+ * `warn`/`error` are required; `info` is OPTIONAL on purpose — a hand-written test logger or a
+ * script's two-method stub is a legitimate caller, and requiring `info` would break every one of
+ * them the day something wanted to log a healthy tick. Reach it as `logger?.info?.(…)`.
+ *
+ * `fastify.log` and a pino instance both satisfy this structurally, so hosts pass `req.log`
+ * with no cast.
+ */
+interface StructuredLogger {
+  warn(fields: Record<string, unknown>, message: string): void;
+  error(fields: Record<string, unknown>, message: string): void;
+  info?(fields: Record<string, unknown>, message: string): void;
+}
 /** An identity shape — useful on audit fields (`createdBy`, `updatedBy`). */
 interface ActorRef {
   id: string;
@@ -45,4 +71,4 @@ interface ActorRef {
   name?: string;
 }
 //#endregion
-export { ActorRef, OperationContext };
+export { ActorRef, OperationContext, StructuredLogger };

package/dist/currency.d.mts

@@ -1,2 +1,2 @@
-import { a as MINOR_UNIT_FACTOR, c as isFxSnapshot, d as toCurrencyCode, i as FxSnapshot, l as minorUnitFactor, n as CURRENCY_PATTERN, o as convertWithSnapshot, r as CurrencyCode, s as isCurrencyCode, t as CURRENCIES, u as reverseWithSnapshot } from "./currency-BCJnJBlb.mjs";
-export { CURRENCIES, CURRENCY_PATTERN, CurrencyCode, FxSnapshot, MINOR_UNIT_FACTOR, convertWithSnapshot, isCurrencyCode, isFxSnapshot, minorUnitFactor, reverseWithSnapshot, toCurrencyCode };
+import { A as convertWithSnapshot, C as CURRENCY_PATTERN, D as FxSnapshot, E as FxRounding, F as minorUnitFactor, I as reverseWithSnapshot, L as toCurrencyCode, M as isCurrencyCode, N as isFxSnapshot, O as InvalidCurrencyCodeError, P as isKnownCurrency, S as CURRENCIES, T as CurrencyMismatchError, j as currencyCode, k as MINOR_UNIT_FACTOR, w as CurrencyCode } from "./money-CfAvfNiM.mjs";
+export { CURRENCIES, CURRENCY_PATTERN, CurrencyCode, CurrencyMismatchError, FxRounding, FxSnapshot, InvalidCurrencyCodeError, MINOR_UNIT_FACTOR, convertWithSnapshot, currencyCode, isCurrencyCode, isFxSnapshot, isKnownCurrency, minorUnitFactor, reverseWithSnapshot, toCurrencyCode };