@classytic/primitives 0.19.0 → 0.20.0

package/dist/period.mjs

@@ -1,13 +1,93 @@
+import { addCivilDays, civilDate, civilDateOf, civilDateToInstant, isValidTimeZone } from "./timezone.mjs";
 //#region src/scheduling/period.ts
+/**
+* Named accounting / reporting periods, and the ONE place a `Period` becomes a
+* concrete `[start, end)` pair of instants — in a business timezone.
+*
+* ## Why the resolver lives HERE
+*
+* `Period` used to be a bare `{ year, month?, quarter? }` with no timezone and
+* no resolver, so every consumer had to answer "which instants is August?"
+* itself. Two resolvers grew ABOVE the kernels (`@spinekit/kit/period` and
+* be-prod's `business-date`), which meant a kernel could not reach either and
+* re-derived the boundary inline with `Date.UTC`. That is deterministic,
+* TZ-env-proof, reviews clean — and wrong for every deployment not sitting on
+* UTC. Asia/Dhaka is UTC+6, so a UTC month disagrees with the business month at
+* BOTH ends by six hours.
+*
+* Five documented instances of that exact bug, all silent, none of which threw:
+*
+* | where | what it did |
+* |---|---|
+* | `aggregateMonthlyVat` | reported August revenue as July AND dropped early-July revenue entirely |
+* | input-VAT aggregator | credited purchases to the wrong filing month |
+* | Mushak serial year | an invoice issued 01:00 on 1 Jan drew from the OUTGOING year's counter |
+* | sales-fact reconciler | reported total drift for every cell in every window |
+* | analytics "today" | a daily KPI wrong for six hours of every day |
+*
+* The resolution logic below is a MOVE of the proven implementation from
+* `@spinekit/kit`'s `createBusinessCalendar` — same civil-date round-trip, same
+* half-open ranges, same DST-exactness. Layers above should now bind a zone and
+* delegate rather than re-derive.
+*
+* ## DST-exactness
+*
+* Every boundary resolves through `/timezone`'s ICU civil-date primitives
+* (`civilDate` → `civilDateToInstant`), so a day is the day the local clock
+* actually had — never "the previous boundary + 24h", which is an hour off
+* twice a year in any DST zone and silently corrupts a daily rollup on exactly
+* those two days.
+*/
+var DateRangeError = class extends Error {
+	name = "DateRangeError";
+};
+var PeriodError = class extends Error {
+	name = "PeriodError";
+	code;
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+	}
+};
+/**
+* Reject an Invalid Date before it reaches a comparison.
+*
+* Every comparison against `NaN` is `false`, so an unvalidated Invalid Date does
+* not fail here — it answers "not within" and "does not overlap". For the two
+* documented consumers of {@link rangesOverlap} (order booking collision, flow
+* reservation-window collision) "does not overlap" is the PERMISSIVE answer: a
+* corrupt range silently double-books instead of erroring. A range you cannot
+* interpret must fail, not widen.
+*/
+function assertUsableRange(range, label) {
+	const start = range.start?.getTime?.();
+	const end = range.end?.getTime?.();
+	if (!Number.isFinite(start) || !Number.isFinite(end)) throw new DateRangeError(`${label} has a non-finite endpoint (start=${String(range.start)}, end=${String(range.end)}) — an Invalid Date compares false against everything, which would silently report "no overlap".`);
+}
 function isDateRange(value) {
-	return typeof value === "object" && value !== null && value.start instanceof Date && value.end instanceof Date;
+	if (typeof value !== "object" || value === null) return false;
+	const { start, end } = value;
+	return start instanceof Date && end instanceof Date && Number.isFinite(start.getTime()) && Number.isFinite(end.getTime());
 }
-/** True if `d` is inclusively within `range`. */
+/**
+* True if `d` is inclusively within `range`.
+*
+* @throws DateRangeError if `d` or either endpoint is an Invalid Date.
+*/
 function isWithin(d, range) {
-	return d.getTime() >= range.start.getTime() && d.getTime() <= range.end.getTime();
+	const t = d?.getTime?.();
+	if (!Number.isFinite(t)) throw new DateRangeError(`isWithin received a non-finite instant: ${String(d)}`);
+	assertUsableRange(range, "range");
+	return t >= range.start.getTime() && t <= range.end.getTime();
 }
-/** Range duration in milliseconds. */
+/**
+* Range duration in milliseconds.
+*
+* @throws DateRangeError if either endpoint is an Invalid Date (which would
+*   otherwise return `NaN` and propagate silently into a duration total).
+*/
 function rangeDurationMs(range) {
+	assertUsableRange(range, "range");
 	return range.end.getTime() - range.start.getTime();
 }
 /**
@@ -23,9 +103,240 @@ function rangeDurationMs(range) {
 *   - `@classytic/order` booking overlap detection
 *   - `@classytic/flow` reservation window collision
 *   - promo / offer campaign window overlap checks
+*
+* @throws DateRangeError if either range carries an Invalid Date. For all three
+*   consumers above, `false` is the PERMISSIVE answer — "no conflict, go ahead
+*   and book" — so a range we cannot read must not be allowed to produce it.
 */
 function rangesOverlap(a, b) {
+	assertUsableRange(a, "range a");
+	assertUsableRange(b, "range b");
 	return a.start.getTime() < b.end.getTime() && b.start.getTime() < a.end.getTime();
 }
+const pad2 = (n) => String(n).padStart(2, "0");
+function assertZone(timezone) {
+	if (typeof timezone !== "string" || timezone.length === 0) throw new PeriodError("MISSING_TIMEZONE", `A business period needs an IANA timezone (e.g. 'Asia/Dhaka'); received ${String(timezone)}. Resolving without one would silently answer in UTC, which is a different month at both ends for every deployment that isn't on UTC.`);
+	if (!isValidTimeZone(timezone)) throw new PeriodError("MISSING_TIMEZONE", `Unknown IANA timezone '${timezone}'. A misread zone resolves to a plausible but different calendar.`);
+	return timezone;
+}
+function assertYear(year) {
+	if (!Number.isInteger(year) || year < 1 || year > 9999) throw new PeriodError("INVALID_FIELD", `year must be an integer in [1, 9999], got ${String(year)}`);
+	return year;
+}
+function assertMonth(month) {
+	if (!Number.isInteger(month) || month < 1 || month > 12) throw new PeriodError("INVALID_FIELD", `month must be an integer in [1, 12], got ${String(month)}`);
+	return month;
+}
+function assertQuarter(quarter) {
+	if (!Number.isInteger(quarter) || quarter < 1 || quarter > 4) throw new PeriodError("INVALID_FIELD", `quarter must be an integer in [1, 4], got ${String(quarter)}`);
+	return quarter;
+}
+/**
+* The first instant of a local calendar day, in `timezone`. DST-exact — the
+* civil-date round-trip resolves the offset AT local midnight, not at "now".
+*/
+function dayStart(date, timezone) {
+	return civilDateToInstant(civilDate(date), assertZone(timezone));
+}
+/** Half-open `[start, end)` range covering one local calendar day. */
+function resolveDay(date, timezone) {
+	const zone = assertZone(timezone);
+	const cd = civilDate(date);
+	return {
+		start: dayStart(cd, zone),
+		end: dayStart(addCivilDays(cd, 1), zone)
+	};
+}
+/**
+* Half-open `[start, end)` range covering one local calendar month.
+* `resolveMonth(2026, 8, 'Asia/Dhaka')` →
+* `[2026-07-31T18:00Z, 2026-08-31T18:00Z)` — the DHAKA month, six hours off
+* the UTC one at both ends.
+*/
+function resolveMonth(year, month, timezone) {
+	const zone = assertZone(timezone);
+	const y = assertYear(year);
+	const m = assertMonth(month);
+	return {
+		start: dayStart(`${y}-${pad2(m)}-01`, zone),
+		end: m === 12 ? dayStart(`${y + 1}-01-01`, zone) : dayStart(`${y}-${pad2(m + 1)}-01`, zone)
+	};
+}
+/** Half-open `[start, end)` range covering one local calendar quarter. */
+function resolveQuarter(year, quarter, timezone) {
+	const zone = assertZone(timezone);
+	const y = assertYear(year);
+	const firstMonth = (assertQuarter(quarter) - 1) * 3 + 1;
+	return {
+		start: resolveMonth(y, firstMonth, zone).start,
+		end: resolveMonth(y, firstMonth + 2, zone).end
+	};
+}
+/** Half-open `[start, end)` range covering one local calendar year. */
+function resolveYear(year, timezone) {
+	const zone = assertZone(timezone);
+	const y = assertYear(year);
+	return {
+		start: dayStart(`${y}-01-01`, zone),
+		end: dayStart(`${y + 1}-01-01`, zone)
+	};
+}
+/**
+* Half-open range spanning two local dates, INCLUSIVE of both days — what an
+* operator means by "1st to 31st". The half-open end is therefore the start of
+* the day AFTER `to`.
+*/
+function resolveDateSpan(from, to, timezone) {
+	const zone = assertZone(timezone);
+	const start = dayStart(civilDate(from), zone);
+	const end = dayStart(addCivilDays(civilDate(to), 1), zone);
+	if (end.getTime() < start.getTime()) throw new PeriodError("INVALID_FIELD", `date span '${from}'..'${to}' ends before it starts`);
+	return {
+		start,
+		end
+	};
+}
+/** Which resolution shape this period carries. Throws when it carries two. */
+function granularityOf(period) {
+	const hasAdHoc = period.start !== void 0 || period.end !== void 0;
+	const hasMonth = period.month !== void 0;
+	const hasQuarter = period.quarter !== void 0;
+	if ([
+		hasAdHoc,
+		hasMonth,
+		hasQuarter
+	].filter(Boolean).length > 1) throw new PeriodError("AMBIGUOUS_PERIOD", `Period declares more than one resolution shape (month=${String(period.month)}, quarter=${String(period.quarter)}, start=${String(period.start)}, end=${String(period.end)}). Two possible answers to "which instants is this?" must not be silently reduced to one — set exactly one of month, quarter, or start+end.`);
+	if (hasAdHoc) {
+		if (period.start === void 0 || period.end === void 0) throw new PeriodError("INCOMPLETE_RANGE", "An ad-hoc Period needs BOTH start and end; a half-supplied range would resolve as an open-ended one.");
+		return "custom";
+	}
+	if (hasMonth) return "month";
+	if (hasQuarter) return "quarter";
+	return "year";
+}
+/**
+* Resolve the zone a period must be read in.
+*
+* `period.timezone` is the zone the period was DEFINED in; `timezone` is the
+* caller's (usually the deployment default). Supplying both with different
+* values is a bug — one of them is describing a different calendar than the
+* data was computed against — so it throws rather than picking a winner.
+*/
+function periodTimeZone(period, timezone) {
+	const own = period.timezone;
+	if (own !== void 0 && timezone !== void 0 && own !== timezone) throw new PeriodError("TIMEZONE_CONFLICT", `Period is defined in '${own}' but was asked to resolve in '${timezone}'. These are different calendars; silently choosing one produces a plausible range for the wrong month.`);
+	return assertZone(own ?? timezone);
+}
+/**
+* `Period` → half-open `[start, end)` instants, in a business timezone.
+*
+* The single derivation every kernel, module and host should reach for.
+*
+* ```ts
+* resolvePeriod({ year: 2026, month: 8 }, 'Asia/Dhaka');
+* // → [2026-07-31T18:00:00Z, 2026-08-31T18:00:00Z)
+* ```
+*
+* An ad-hoc period (`start` + `end`) needs no zone and is returned verbatim
+* after an Invalid-Date check.
+*/
+function resolvePeriod(period, timezone) {
+	const granularity = granularityOf(period);
+	if (granularity === "custom") {
+		const range = {
+			start: period.start,
+			end: period.end
+		};
+		assertUsableRange(range, "ad-hoc period");
+		return range;
+	}
+	const zone = periodTimeZone(period, timezone);
+	if (granularity === "month") return resolveMonth(period.year, period.month, zone);
+	if (granularity === "quarter") return resolveQuarter(period.year, period.quarter, zone);
+	return resolveYear(period.year, zone);
+}
+/**
+* The LAST instant of a half-open range — `end - 1ms`.
+*
+* For the `$lte` call sites that predate half-open ranges. Derived from the
+* resolved end rather than `start + 24h - 1`, so it stays DST-exact.
+*/
+function inclusiveEnd(range) {
+	assertUsableRange(range, "range");
+	return /* @__PURE__ */ new Date(range.end.getTime() - 1);
+}
+/**
+* The period an INSTANT falls in, on the local calendar.
+*
+* The inverse of {@link resolvePeriod}, and the answer to "which filing month
+* is this posting in?" — asked at local midnight ±6h, `getUTCMonth()` answers a
+* different month. The returned period carries the zone it was derived in, so
+* a later `resolvePeriod` cannot re-read it against a different calendar.
+*/
+function periodOf(instant, granularity, timezone) {
+	const zone = assertZone(timezone);
+	const cd = civilDateOf(instant, zone);
+	const year = Number(cd.slice(0, 4));
+	const month = Number(cd.slice(5, 7));
+	if (granularity === "year") return {
+		year,
+		timezone: zone
+	};
+	if (granularity === "quarter") return {
+		year,
+		quarter: Math.floor((month - 1) / 3) + 1,
+		timezone: zone
+	};
+	return {
+		year,
+		month,
+		timezone: zone
+	};
+}
+const YEAR_RE = /^(\d{4})$/;
+const MONTH_RE = /^(\d{4})-(\d{2})$/;
+const QUARTER_RE = /^(\d{4})-Q([1-4])$/;
+const CIVIL_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+/**
+* Parse a period LABEL — `'2026'`, `'2026-08'`, `'2026-Q3'`.
+*
+* Case-sensitive on the `Q` and strictly anchored: a label this cannot read
+* throws instead of degrading to the year it could see. A `'YYYY-MM-DD'` is
+* rejected with a pointer to {@link resolveDay}, because a `Period` has no day
+* field and quietly reading it as its month is a 30× widening of the range.
+*/
+function parsePeriod(label, timezone) {
+	const withZone = (p) => timezone === void 0 ? p : {
+		...p,
+		timezone: assertZone(timezone)
+	};
+	const text = String(label);
+	const month = MONTH_RE.exec(text);
+	if (month) return withZone({
+		year: assertYear(Number(month[1])),
+		month: assertMonth(Number(month[2]))
+	});
+	const quarter = QUARTER_RE.exec(text);
+	if (quarter) return withZone({
+		year: assertYear(Number(quarter[1])),
+		quarter: assertQuarter(Number(quarter[2]))
+	});
+	const year = YEAR_RE.exec(text);
+	if (year) return withZone({ year: assertYear(Number(year[1])) });
+	if (CIVIL_DATE_RE.test(text)) throw new PeriodError("INVALID_LABEL", `'${text}' is a civil DATE, not a period label. A Period has no day field, so reading it as its month would widen the range ~30×. Use resolveDay('${text}', timezone).`);
+	throw new PeriodError("INVALID_LABEL", `Invalid period label '${text}' — expected 'YYYY', 'YYYY-MM' or 'YYYY-Qn'.`);
+}
+/**
+* `Period` → its canonical label. Round-trips through {@link parsePeriod}.
+* Throws for an ad-hoc period, which has no label — format its endpoints.
+*/
+function formatPeriod(period) {
+	const granularity = granularityOf(period);
+	const year = assertYear(period.year);
+	if (granularity === "month") return `${year}-${pad2(assertMonth(period.month))}`;
+	if (granularity === "quarter") return `${year}-Q${assertQuarter(period.quarter)}`;
+	if (granularity === "year") return String(year);
+	throw new PeriodError("INVALID_LABEL", "An ad-hoc Period (start + end) has no canonical label.");
+}
 //#endregion
-export { isDateRange, isWithin, rangeDurationMs, rangesOverlap };
+export { DateRangeError, PeriodError, dayStart, formatPeriod, granularityOf, inclusiveEnd, isDateRange, isWithin, parsePeriod, periodOf, periodTimeZone, rangeDurationMs, rangesOverlap, resolveDateSpan, resolveDay, resolveMonth, resolvePeriod, resolveQuarter, resolveYear };

package/dist/person-parse.d.mts

@@ -0,0 +1,82 @@
+import { PersonName } from "./person.mjs";
+
+//#region src/identity/person-parse.d.ts
+/**
+ * Does this `PersonName` carry at least one usable, non-empty name part?
+ *
+ * Used by both the customer-model virtuals (`fullName` / `displayName`) and
+ * any code path that needs to decide "is this customer effectively unnamed".
+ * Defends against the legacy data shape and any future write that lands an
+ * all-empty `{ given: '', family: '' }`. Without this, `formatDisplayName`
+ * from `@classytic/primitives` returns the literal string `"undefined
+ * undefined"` for empty names — a bug we've patched at the write boundary
+ * but keep guarding at the read boundary too (defense in depth).
+ */
+declare function hasUsableName(name: PersonName | undefined | null): boolean;
+/**
+ * Detect a "looks like an identifier, not a person name" string.
+ *
+ * Better Auth signs OAuth users in with `user.name` populated from the
+ * provider — but Apple-private-relay / Google-custom-name flows (and our
+ * own guest-checkout fallback) sometimes put the BA `user.id` string into
+ * `user.name`. That id is a 20-char base64-url-safe nanoid like
+ * `gcqAUBgGpRnDZbyPgKbS`, and storing it as `name.given` leaks the
+ * internal id into the dashboard customers table.
+ *
+ * Heuristic (cheap, no false-positives observed on real BD names):
+ *   - 12+ chars
+ *   - no whitespace (real "full names" have spaces; single-name locales
+ *     are usually < 12 chars: "Sadman", "Nirjhar", "Subarna", etc.)
+ *   - at least 3 uppercase AND 3 lowercase letters (Title-Case names
+ *     don't qualify — "Sadman Chowdhury" has 2 uppercase chars; even
+ *     the longest single Bangla romanisation rarely hits 3+ uppercase
+ *     in one token)
+ *   - OR a bare 24-char lowercase hex (ObjectId)
+ *
+ * If a real name ever gets misclassified, the customer can edit it from
+ * the profile page and the heuristic only runs at create / link time.
+ */
+declare function looksLikeIdentifierNotName(value: string): boolean;
+/**
+ * Pick a display fallback when `user.name` is missing or token-like.
+ * Prefers the email local-part (capitalised) so customers see a recognisable
+ * label in the dashboard instead of "Unknown" or a leaked id.
+ */
+declare function fallbackNameFromUser(user: {
+  name?: string;
+  email?: string;
+}, defaultLabel: string): string;
+/**
+ * Sanitize a display-name string before it gets snapshotted into a
+ * derivative collection (order, invoice, shipment, transaction, etc.).
+ *
+ * The customer-creation boundary (`customer.repository.ts`) already
+ * scrubs token-shaped names. This helper is the second line of defence
+ * for write paths that copy `customer.name` somewhere else — if the
+ * source ever regressed, the snapshot still wouldn't carry the leak.
+ *
+ * Returns:
+ *   - the trimmed input when it's a real-looking name
+ *   - `fallback` when the input is empty, undefined, or token-shaped
+ *
+ * Caller is responsible for picking a sensible `fallback` (e.g. the
+ * email local-part, "Customer", "Walk-in", etc.).
+ */
+declare function sanitizeDisplayName(value: string | undefined | null, fallback: string): string;
+/**
+ * Split a flat "Full Name" string into a structured `PersonName`.
+ *
+ * Callers at the auth / POS boundary pass flat names; storage is structured.
+ * Single-token names go in `given` with an empty `family` (many BD and
+ * single-name locales store a single name, which is valid).
+ *
+ * `user` (optional) supplies an `email` so we can derive a sensible display
+ * fallback when the input is empty or looks like a BA user id rather than
+ * a real name. Without `user`, the static `fallback` arg is the floor.
+ */
+declare function nameFromString(flat: string | undefined, fallback: string, user?: {
+  name?: string;
+  email?: string;
+}): PersonName;
+//#endregion
+export { fallbackNameFromUser, hasUsableName, looksLikeIdentifierNotName, nameFromString, sanitizeDisplayName };

package/dist/person-parse.mjs

@@ -0,0 +1,109 @@
+//#region src/identity/person-parse.ts
+/**
+* Does this `PersonName` carry at least one usable, non-empty name part?
+*
+* Used by both the customer-model virtuals (`fullName` / `displayName`) and
+* any code path that needs to decide "is this customer effectively unnamed".
+* Defends against the legacy data shape and any future write that lands an
+* all-empty `{ given: '', family: '' }`. Without this, `formatDisplayName`
+* from `@classytic/primitives` returns the literal string `"undefined
+* undefined"` for empty names — a bug we've patched at the write boundary
+* but keep guarding at the read boundary too (defense in depth).
+*/
+function hasUsableName(name) {
+	if (!name) return false;
+	return Boolean(name.preferred?.trim() || name.given?.trim() || name.family?.trim() || name.middle?.trim() || name.prefix?.trim() || name.suffix?.trim());
+}
+/**
+* Detect a "looks like an identifier, not a person name" string.
+*
+* Better Auth signs OAuth users in with `user.name` populated from the
+* provider — but Apple-private-relay / Google-custom-name flows (and our
+* own guest-checkout fallback) sometimes put the BA `user.id` string into
+* `user.name`. That id is a 20-char base64-url-safe nanoid like
+* `gcqAUBgGpRnDZbyPgKbS`, and storing it as `name.given` leaks the
+* internal id into the dashboard customers table.
+*
+* Heuristic (cheap, no false-positives observed on real BD names):
+*   - 12+ chars
+*   - no whitespace (real "full names" have spaces; single-name locales
+*     are usually < 12 chars: "Sadman", "Nirjhar", "Subarna", etc.)
+*   - at least 3 uppercase AND 3 lowercase letters (Title-Case names
+*     don't qualify — "Sadman Chowdhury" has 2 uppercase chars; even
+*     the longest single Bangla romanisation rarely hits 3+ uppercase
+*     in one token)
+*   - OR a bare 24-char lowercase hex (ObjectId)
+*
+* If a real name ever gets misclassified, the customer can edit it from
+* the profile page and the heuristic only runs at create / link time.
+*/
+function looksLikeIdentifierNotName(value) {
+	if (!value) return false;
+	if (/^[a-f0-9]{24}$/.test(value)) return true;
+	if (value.length < 12) return false;
+	if (/\s/.test(value)) return false;
+	const upper = (value.match(/[A-Z]/g) ?? []).length;
+	const lower = (value.match(/[a-z]/g) ?? []).length;
+	return upper >= 3 && lower >= 3;
+}
+/**
+* Pick a display fallback when `user.name` is missing or token-like.
+* Prefers the email local-part (capitalised) so customers see a recognisable
+* label in the dashboard instead of "Unknown" or a leaked id.
+*/
+function fallbackNameFromUser(user, defaultLabel) {
+	const email = user.email?.trim();
+	if (email?.includes("@")) {
+		const cleaned = (email.split("@", 1)[0] ?? "").replace(/[^a-zA-Z]+/g, " ").trim();
+		if (cleaned.length >= 2) return cleaned.split(/\s+/).map((part) => part.charAt(0).toUpperCase() + part.slice(1).toLowerCase()).join(" ");
+	}
+	return defaultLabel;
+}
+/**
+* Sanitize a display-name string before it gets snapshotted into a
+* derivative collection (order, invoice, shipment, transaction, etc.).
+*
+* The customer-creation boundary (`customer.repository.ts`) already
+* scrubs token-shaped names. This helper is the second line of defence
+* for write paths that copy `customer.name` somewhere else — if the
+* source ever regressed, the snapshot still wouldn't carry the leak.
+*
+* Returns:
+*   - the trimmed input when it's a real-looking name
+*   - `fallback` when the input is empty, undefined, or token-shaped
+*
+* Caller is responsible for picking a sensible `fallback` (e.g. the
+* email local-part, "Customer", "Walk-in", etc.).
+*/
+function sanitizeDisplayName(value, fallback) {
+	const trimmed = (value ?? "").trim();
+	if (!trimmed) return fallback;
+	if (looksLikeIdentifierNotName(trimmed)) return fallback;
+	return trimmed;
+}
+/**
+* Split a flat "Full Name" string into a structured `PersonName`.
+*
+* Callers at the auth / POS boundary pass flat names; storage is structured.
+* Single-token names go in `given` with an empty `family` (many BD and
+* single-name locales store a single name, which is valid).
+*
+* `user` (optional) supplies an `email` so we can derive a sensible display
+* fallback when the input is empty or looks like a BA user id rather than
+* a real name. Without `user`, the static `fallback` arg is the floor.
+*/
+function nameFromString(flat, fallback, user) {
+	const trimmed = (flat ?? "").trim();
+	const parts = (trimmed && !looksLikeIdentifierNotName(trimmed) ? trimmed : user ? fallbackNameFromUser(user, fallback) : fallback).split(/\s+/);
+	if (parts.length <= 1) return {
+		given: parts[0] ?? fallback,
+		family: ""
+	};
+	const family = parts.pop() ?? "";
+	return {
+		given: parts.join(" "),
+		family
+	};
+}
+//#endregion
+export { fallbackNameFromUser, hasUsableName, looksLikeIdentifierNotName, nameFromString, sanitizeDisplayName };

package/dist/proration.d.mts

@@ -1,4 +1,4 @@
-import { Money } from "./money.mjs";
+import { n as Money } from "./money-DPo9fLBi.mjs";
 
 //#region src/money/proration.d.ts
 /**
@@ -33,7 +33,7 @@ interface PeriodProgressInput {
   /** Day-counting granularity. Default `'whole_day'`. */
   readonly granularity?: ProrationGranularity;
 }
-type ProrationErrorCode = 'INVALID_PERIOD' | 'INVALID_FRACTION';
+type ProrationErrorCode = 'INVALID_PERIOD' | 'INVALID_FRACTION' | 'ALLOCATION_INVARIANT';
 declare class ProrationError extends Error {
   readonly name = "ProrationError";
   readonly code: ProrationErrorCode;

package/dist/proration.mjs

@@ -82,20 +82,32 @@ function splitByPeriodFraction(amount, fraction) {
 		id: "remaining",
 		weight: fraction.remainingDays
 	}], "by-weight");
-	const consumed = result.parts.find((p) => p.id === "consumed")?.amount ?? 0;
-	const remaining = result.parts.find((p) => p.id === "remaining")?.amount ?? 0;
 	return {
 		consumed: {
-			amount: consumed,
+			amount: requirePart(result, "consumed"),
 			currency: amount.currency
 		},
 		remaining: {
-			amount: remaining,
+			amount: requirePart(result, "remaining"),
 			currency: amount.currency
 		}
 	};
 }
 /**
+* Read one allocated part by id, or THROW.
+*
+* This used to be `…?.amount ?? 0`. A missing part is not "no money" — it is a
+* broken allocator, and defaulting it to zero turns that into a silently
+* plausible number: the unused-value credit on a plan change becomes 0 and the
+* customer is quietly not credited. Nothing downstream can tell that apart from
+* a genuinely fully-consumed period.
+*/
+function requirePart(result, id) {
+	const part = result.parts.find((p) => p.id === id);
+	if (part === void 0) throw new ProrationError("ALLOCATION_INVARIANT", `allocator returned no part '${id}' (got: ${result.parts.map((p) => p.id).join(", ") || "none"})`);
+	return part.amount;
+}
+/**
 * Allocate the `fraction`-weighted part of a `Money` amount, drift-free — the
 * complement (`1 - fraction`) is discarded but computed so rounding is exact
 * against the whole. `fraction` must be in `[0, 1]`.
@@ -106,13 +118,13 @@ function splitByPeriodFraction(amount, fraction) {
 function allocateMoneyByFraction(amount, fraction) {
 	if (!Number.isFinite(fraction) || fraction < 0 || fraction > 1) throw new ProrationError("INVALID_FRACTION", `fraction must be in [0, 1], got ${fraction}`);
 	return {
-		amount: allocate(amount.amount, [{
+		amount: requirePart(allocate(amount.amount, [{
 			id: "part",
 			weight: fraction
 		}, {
 			id: "rest",
 			weight: 1 - fraction
-		}], "by-weight").parts.find((p) => p.id === "part")?.amount ?? 0,
+		}], "by-weight"), "part"),
 		currency: amount.currency
 	};
 }

package/dist/sla-policy.d.mts

@@ -1,4 +1,4 @@
-import { IsoWeekday } from "./cadence.mjs";
+import { s as IsoWeekday } from "./cadence-BFQVC1Qp.mjs";
 import { SLA } from "./sla.mjs";
 
 //#region src/scheduling/sla-policy.d.ts

package/dist/state-machine.mjs

@@ -149,6 +149,19 @@ function defineStateMachine(definition) {
 */
 async function assertAndClaim(machine, repo, id, args) {
 	const sources = Array.isArray(args.from) ? args.from : [args.from];
+	/**
+	* An EMPTY source list must never reach `claim()`.
+	*
+	* `validSources(to)` returns `[]` for a status nothing transitions into, and
+	* the multi-source idiom in the docblock above (`from: machine.validSources(x)`)
+	* makes that easy to hit. With `[]` the assert loop below runs ZERO times — the
+	* domain check silently does not happen — and the CAS is then handed an empty
+	* allow-list. Mongo's `$in: []` matches nothing so today that fails closed and
+	* looks exactly like a race-loss (`null`), which is the wrong diagnosis; a kit
+	* that read an empty list as "no constraint" would fail OPEN and claim from any
+	* state at all. An empty allow-list must never mean "any".
+	*/
+	if (sources.length === 0) throw new IllegalTransitionError(machine.name, id, "(none)", args.to);
 	for (const from of sources) machine.assertTransition(id, from, args.to);
 	return repo.claim(id, {
 		from: Array.isArray(args.from) ? args.from : args.from,

package/dist/suspension.d.mts

@@ -1,4 +1,4 @@
-import { UtcOffsetMinutes } from "./calendar.mjs";
+import { t as UtcOffsetMinutes } from "./calendar-B6fm-FbR.mjs";
 import { DateRange } from "./period.mjs";
 import { StatusChangeEntry } from "./status-history.mjs";