@classytic/primitives 0.7.2 → 0.9.0

package/CHANGELOG.md

@@ -3,6 +3,35 @@
 Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 adhering to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.9.0] - 2026-07-02
+
+### Added — `/timezone`: IANA resolution + civil dates (the door for `/calendar`'s escape hatch)
+
+`/calendar` owns wall-clock ARITHMETIC over a fixed `UtcOffsetMinutes` and
+tells hosts to "resolve the offset for the instant and pass it in" — but the
+stack had no shared resolver, so consumers hand-rolled `Intl.DateTimeFormat`
+(three divergent copies found: catalog ×2, be-prod POS). `/timezone` is that
+resolver — zero-dep (Intl IS the ICU tz database), Temporal-shaped names for
+a future mechanical migration:
+
+- **`zoneOffsetMinutes(instant, zone)`** — per-instant, DST-exact offset;
+  composes directly with `/calendar`: `startOfMonth(i, zoneOffsetMinutes(i, z))`.
+- **`localTimeParts(instant, zone)`** — `{ isoWeekday, hour, minute,
+  minutesOfDay }` in the zone; what pricing windows / slot grids /
+  working-hours checks evaluate against (canonicalizes catalog's resolvers).
+- **`CivilDate`** (branded `'YYYY-MM-DD'`) + `civilDate` / `isCivilDate` /
+  `civilDateOf(instant, zone)` / `civilDateToInstant(cd, zone, time?)`
+  (two-pass DST-safe) / `addCivilDays` / `civilDaysBetween` — the type for
+  hotel nights, POS business dates, VAT filing years. Lexicographic ==
+  chronological, so it's a range-queryable Mongo string key.
+- **`isValidTimeZone(zone)`** — boot-time host-config validation;
+  **`listTimeZones()`** + **`zoneOffsetLabel(instant, zone)`** — the data
+  source + label for Google-Calendar-style zone pickers, straight from ICU
+  (`Intl.supportedValuesOf`), no bundled list to go stale.
+- `TimeZoneError`; formatter instances cached per zone.
+
+No arithmetic here (that stays in `/calendar`) — resolution only.
+
 ## [0.7.2] - 2026-05-30
 
 ### Added — `BankTransaction` per-account routing + pending lifecycle fields

package/dist/calendar.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 { UtcOffsetMinutes, addDays, addMonths, addYears, isoWeekday, startOfDay, startOfMonth };

package/dist/calendar.mjs

@@ -0,0 +1,47 @@
+//#region src/scheduling/calendar.ts
+const MINUTE_MS = 6e4;
+const DAY_MS = 864e5;
+/**
+* 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.
+*/
+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);
+}
+/** 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);
+}
+/** ISO weekday (1 = Monday … 7 = Sunday) of `instant` in the given offset. */
+function isoWeekday(instant, offsetMinutes = 0) {
+	return (new Date(instant.getTime() + offsetMinutes * MINUTE_MS).getUTCDay() + 6) % 7 + 1;
+}
+/** Add whole days as an exact 24h × n duration (offset-agnostic, no DST skew). */
+function addDays(instant, days) {
+	return new Date(instant.getTime() + days * DAY_MS);
+}
+/**
+* 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)`.
+*/
+function addMonths(instant, months) {
+	const d = new Date(instant.getTime());
+	const day = d.getUTCDate();
+	d.setUTCDate(1);
+	d.setUTCMonth(d.getUTCMonth() + months);
+	const daysInTarget = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + 1, 0)).getUTCDate();
+	d.setUTCDate(Math.min(day, daysInTarget));
+	return d;
+}
+/** Add calendar years in UTC (clamps Feb 29 → Feb 28 on non-leap years). */
+function addYears(instant, years) {
+	return addMonths(instant, years * 12);
+}
+//#endregion
+export { addDays, addMonths, addYears, isoWeekday, startOfDay, startOfMonth };

package/dist/shelf-life.d.mts

@@ -0,0 +1,114 @@
+//#region src/scheduling/shelf-life.d.ts
+/**
+ * Shelf-life / lot-tracking policy + pure expiry-date derivation.
+ *
+ * Describes whether a SKU is tracked by lot/serial, whether it carries an
+ * expiration date, and the day-offsets used to derive the four lifecycle
+ * dates of a freshly-received lot. The *policy* is product-level metadata
+ * (owned by a catalog); the *derived dates* are per-lot facts (owned by a
+ * WMS). This module is the shared contract both speak so the shape can't
+ * drift between packages.
+ *
+ * Modeled on Odoo's `product_expiry` addon, which puts `tracking` +
+ * `use_expiration_date` and four integer day-deltas on `product.template`,
+ * then computes four dates on each `stock.lot`:
+ *
+ *   expiration = receivedAt + shelfLifeDays
+ *   bestBefore = expiration − bestBeforeDays   (still safe, starts deteriorating)
+ *   removal    = expiration − removalDays      (stop selling — FEFO sorts on THIS)
+ *   alert      = expiration − alertDays         (raise a reminder)
+ *
+ * Consumed by `@classytic/catalog` (variant tracking policy) and
+ * `@classytic/flow` (lot date derivation at receipt, FEFO, fresh-on-hand).
+ *
+ * Zero-dep, pure UTC day arithmetic — safe in unit tests with no clock.
+ *
+ * @example
+ * const policy: ShelfLifePolicy = {
+ *   mode: 'lot',
+ *   useExpiration: true,
+ *   shelfLifeDays: 540,   // 18-month medicine
+ *   removalDays: 30,      // pull 30 days before expiry
+ *   alertDays: 60,        // remind 60 days before expiry
+ * };
+ * deriveShelfLifeDates(new Date('2026-01-01T00:00:00Z'), policy);
+ * // → { expiresAt: 2027-06-25…, removalDate: 2027-05-26…, alertDate: 2027-04-26… }
+ */
+/** How a SKU's stock identity is tracked. Mirrors Odoo `product.tracking`. */
+type TrackingMode = 'none' | 'lot' | 'serial';
+interface ShelfLifePolicy {
+  /** `'none'` = tracked by quantity only; `'lot'` = batch; `'serial'` = unique unit. */
+  readonly mode: TrackingMode;
+  /**
+   * When `true`, received lots carry an expiration date and the freshness
+   * lifecycle (best-before / removal / alert) applies. When `false`, the
+   * SKU may still be lot/serial tracked for traceability but has no expiry.
+   */
+  readonly useExpiration: boolean;
+  /**
+   * Total shelf life in days: `expiration = receivedAt + shelfLifeDays`.
+   * Omit to require a manual expiration date at receipt (no auto-derivation).
+   */
+  readonly shelfLifeDays?: number;
+  /** Days before expiration when goods start deteriorating (best-before / use date). */
+  readonly bestBeforeDays?: number;
+  /**
+   * Days before expiration when goods must be pulled from sellable stock.
+   * This is the FEFO sort key and the fresh-on-hand cutoff — NOT the
+   * expiration date itself.
+   */
+  readonly removalDays?: number;
+  /** Days before expiration when an expiry reminder should fire. */
+  readonly alertDays?: number;
+}
+/** The four lifecycle dates of a received lot. All optional — only what the policy can derive. */
+interface ShelfLifeDates {
+  readonly expiresAt?: Date;
+  readonly bestBeforeDate?: Date;
+  readonly removalDate?: Date;
+  readonly alertDate?: Date;
+}
+interface DeriveOptions {
+  /**
+   * Explicit expiration date — overrides `shelfLifeDays` derivation (manual
+   * receiving, GS1-scanned expiry). The other three dates are then offset
+   * back from THIS date, matching Odoo's edit-expiration behavior.
+   */
+  readonly expiresAt?: Date;
+}
+type ShelfLifeErrorCode = 'INVALID_MODE' | 'INVALID_DAYS' | 'INVALID_RECEIVED_AT' | 'INVALID_EXPIRES_AT';
+declare class ShelfLifeError extends Error {
+  readonly name = "ShelfLifeError";
+  readonly code: ShelfLifeErrorCode;
+  constructor(code: ShelfLifeErrorCode, message: string);
+}
+/** True when the policy requires lot OR serial identity (i.e. lots get created). */
+declare function isTracked(policy: ShelfLifePolicy): boolean;
+/** True when received lots carry an expiration date. */
+declare function isExpiryTracked(policy: ShelfLifePolicy): boolean;
+/** Validate a policy. Call before storing host-side. */
+declare function validateShelfLifePolicy(policy: ShelfLifePolicy): void;
+/**
+ * Derive the four lifecycle dates for a lot received at `receivedAt`.
+ *
+ * Returns an empty object when the policy does not track expiry (`mode:
+ * 'none'` or `useExpiration: false`) and no explicit `expiresAt` override is
+ * given. Each of the three sub-dates is emitted only when both an expiration
+ * date resolves AND the corresponding offset is present in the policy.
+ *
+ * Offsets are clamped to never produce a date before `receivedAt` (an offset
+ * larger than the shelf life would otherwise yield a removal date in the
+ * past on day one).
+ */
+declare function deriveShelfLifeDates(receivedAt: Date, policy: ShelfLifePolicy, opts?: DeriveOptions): ShelfLifeDates;
+type ShelfLifeStatus = 'none' | 'fresh' | 'alert' | 'removed' | 'expired';
+/**
+ * Classify a lot's freshness as of `asOf`. `'removed'` means past its removal
+ * date (excluded from fresh-on-hand even though not yet expired); `'expired'`
+ * means past the hard expiration date. Returns `'none'` when no dates apply.
+ *
+ * Precedence (most severe first): expired > removed > alert > fresh.
+ */
+declare function shelfLifeStatus(dates: ShelfLifeDates, asOf: Date): ShelfLifeStatus;
+//#endregion
+export { DeriveOptions, ShelfLifeDates, ShelfLifeError, ShelfLifeErrorCode, ShelfLifePolicy, ShelfLifeStatus, TrackingMode, deriveShelfLifeDates, isExpiryTracked, isTracked, shelfLifeStatus, validateShelfLifePolicy };

package/dist/shelf-life.mjs

@@ -0,0 +1,88 @@
+//#region src/scheduling/shelf-life.ts
+var ShelfLifeError = class extends Error {
+	name = "ShelfLifeError";
+	code;
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+	}
+};
+const DAY_MS = 1440 * 60 * 1e3;
+const TRACKING_MODES = [
+	"none",
+	"lot",
+	"serial"
+];
+/** True when the policy requires lot OR serial identity (i.e. lots get created). */
+function isTracked(policy) {
+	return policy.mode !== "none";
+}
+/** True when received lots carry an expiration date. */
+function isExpiryTracked(policy) {
+	return policy.mode !== "none" && policy.useExpiration;
+}
+/** Validate a policy. Call before storing host-side. */
+function validateShelfLifePolicy(policy) {
+	if (!TRACKING_MODES.includes(policy.mode)) throw new ShelfLifeError("INVALID_MODE", `mode must be one of ${TRACKING_MODES.join(", ")}, got ${String(policy.mode)}`);
+	for (const [key, val] of [
+		["shelfLifeDays", policy.shelfLifeDays],
+		["bestBeforeDays", policy.bestBeforeDays],
+		["removalDays", policy.removalDays],
+		["alertDays", policy.alertDays]
+	]) {
+		if (val === void 0) continue;
+		if (!Number.isFinite(val) || val < 0) throw new ShelfLifeError("INVALID_DAYS", `${key} must be a non-negative number, got ${String(val)}`);
+	}
+}
+/**
+* Derive the four lifecycle dates for a lot received at `receivedAt`.
+*
+* Returns an empty object when the policy does not track expiry (`mode:
+* 'none'` or `useExpiration: false`) and no explicit `expiresAt` override is
+* given. Each of the three sub-dates is emitted only when both an expiration
+* date resolves AND the corresponding offset is present in the policy.
+*
+* Offsets are clamped to never produce a date before `receivedAt` (an offset
+* larger than the shelf life would otherwise yield a removal date in the
+* past on day one).
+*/
+function deriveShelfLifeDates(receivedAt, policy, opts = {}) {
+	validateShelfLifePolicy(policy);
+	if (Number.isNaN(receivedAt.getTime())) throw new ShelfLifeError("INVALID_RECEIVED_AT", "receivedAt is not a valid Date");
+	if (opts.expiresAt && Number.isNaN(opts.expiresAt.getTime())) throw new ShelfLifeError("INVALID_EXPIRES_AT", "opts.expiresAt is not a valid Date");
+	let expiresAt;
+	if (opts.expiresAt) expiresAt = opts.expiresAt;
+	else if (isExpiryTracked(policy) && policy.shelfLifeDays !== void 0) expiresAt = addDays(receivedAt, policy.shelfLifeDays);
+	if (!expiresAt) return {};
+	const floor = receivedAt.getTime();
+	const offsetBack = (days) => days === void 0 ? void 0 : new Date(Math.max(floor, expiresAt.getTime() - days * DAY_MS));
+	return {
+		expiresAt,
+		...defined("bestBeforeDate", offsetBack(policy.bestBeforeDays)),
+		...defined("removalDate", offsetBack(policy.removalDays)),
+		...defined("alertDate", offsetBack(policy.alertDays))
+	};
+}
+/**
+* Classify a lot's freshness as of `asOf`. `'removed'` means past its removal
+* date (excluded from fresh-on-hand even though not yet expired); `'expired'`
+* means past the hard expiration date. Returns `'none'` when no dates apply.
+*
+* Precedence (most severe first): expired > removed > alert > fresh.
+*/
+function shelfLifeStatus(dates, asOf) {
+	const now = asOf.getTime();
+	if (!dates.expiresAt && !dates.removalDate && !dates.alertDate) return "none";
+	if (dates.expiresAt && now >= dates.expiresAt.getTime()) return "expired";
+	if (dates.removalDate && now >= dates.removalDate.getTime()) return "removed";
+	if (dates.alertDate && now >= dates.alertDate.getTime()) return "alert";
+	return "fresh";
+}
+function addDays(d, days) {
+	return new Date(d.getTime() + days * DAY_MS);
+}
+function defined(key, val) {
+	return val === void 0 ? {} : { [key]: val };
+}
+//#endregion
+export { ShelfLifeError, deriveShelfLifeDates, isExpiryTracked, isTracked, shelfLifeStatus, validateShelfLifePolicy };

package/dist/timezone.d.mts

@@ -0,0 +1,100 @@
+import { t as Brand } from "./brand-LLXqoh5J.mjs";
+import { IsoWeekday } from "./cadence.mjs";
+import { UtcOffsetMinutes } from "./calendar.mjs";
+
+//#region src/scheduling/timezone.d.ts
+declare class TimeZoneError extends Error {
+  constructor(message: string);
+}
+/**
+ * Is `zone` a valid IANA timezone name on this runtime's ICU data?
+ * Use at BOOT to validate host config (an offer's `timezone`, an org
+ * setting) — fail loud at wiring time, not on the first localized read.
+ */
+declare function isValidTimeZone(zone: string): boolean;
+/**
+ * Every IANA timezone name this runtime supports — the data source for a
+ * Google-Calendar-style zone picker. Straight from ICU via
+ * `Intl.supportedValuesOf` (Node >= 18); no bundled tz list to go stale.
+ *
+ * UIs typically label each entry with its current offset:
+ * `listTimeZones().map((z) => ({ zone: z, label: zoneOffsetLabel(now, z) }))`.
+ */
+declare function listTimeZones(): readonly string[];
+/**
+ * The zone's UTC offset AT `instant`, in minutes east of UTC — DST-exact.
+ * `zoneOffsetMinutes(july, 'Europe/London')` → 60; `(january, …)` → 0;
+ * `(any, 'Asia/Dhaka')` → 360.
+ *
+ * This is the value `/calendar`'s docstring tells hosts to "resolve and pass
+ * in": `startOfMonth(instant, zoneOffsetMinutes(instant, zone))`.
+ */
+declare function zoneOffsetMinutes(instant: Date, zone: string): UtcOffsetMinutes;
+/**
+ * The zone's offset label AT `instant` — `'GMT+06:00'` / `'GMT-05:30'` /
+ * `'GMT'`. Ready-made display text for zone pickers.
+ */
+declare function zoneOffsetLabel(instant: Date, zone: string): string;
+interface LocalTimeParts {
+  /** ISO weekday in the zone — 1=Mon … 7=Sun (matches `/cadence`). */
+  isoWeekday: IsoWeekday;
+  /** Hour of day in the zone, 0–23. */
+  hour: number;
+  /** Minute of hour, 0–59. */
+  minute: number;
+  /** `hour * 60 + minute` — the shape "HH:MM window" checks want. */
+  minutesOfDay: number;
+}
+/**
+ * The wall-clock weekday + time of `instant` in `zone` — what pricing
+ * schedules ("peak Fri 17:00–22:00"), slot grids, and working-hours checks
+ * evaluate against. DST-exact per instant.
+ */
+declare function localTimeParts(instant: Date, zone: string): LocalTimeParts;
+/**
+ * A calendar day — `'YYYY-MM-DD'` — with NO time and NO zone until one is
+ * bound. The type for hotel nights, POS business dates, statement periods,
+ * VAT filing years. Lexicographic order == chronological order, so it's
+ * index- and range-query-friendly as a Mongo string key.
+ */
+type CivilDate = Brand<string, 'CivilDate'>;
+/** Runtime guard for external input. */
+declare function isCivilDate(value: unknown): value is CivilDate;
+/** Validate + brand a `'YYYY-MM-DD'` string. Throws on malformed input. */
+declare function civilDate(value: string): CivilDate;
+/**
+ * The calendar day `instant` falls on IN `zone` — e.g. the POS business
+ * date: `civilDateOf(new Date(), 'Asia/Dhaka')`. Never depends on the
+ * server's TZ env.
+ */
+declare function civilDateOf(instant: Date, zone: string): CivilDate;
+/**
+ * Bind a civil date (+ optional wall time) to a zone → the exact instant.
+ * `civilDateToInstant(night, hotelZone, { hour: 14 })` = check-in instant;
+ * with no `time`, local midnight — the DST-exact "start of that day in that
+ * zone".
+ *
+ * Two-pass offset resolution: the offset is looked up AT the candidate
+ * instant, then re-checked, so days where a DST transition sits between the
+ * wall time and the first guess still resolve correctly. Honest limit: a
+ * wall time that does not exist (inside a spring-forward gap) resolves to
+ * the instant the shifted clock reaches — the same choice Temporal's
+ * `disambiguation: 'compatible'` makes.
+ */
+declare function civilDateToInstant(cd: CivilDate, zone: string, time?: {
+  hour?: number;
+  minute?: number;
+}): Date;
+/**
+ * Pure calendar-day arithmetic — `addCivilDays('2026-02-28', 1)` →
+ * `'2026-03-01'`. Zone-free by definition (a civil date has no zone);
+ * use it to iterate hotel nights / statement days.
+ */
+declare function addCivilDays(cd: CivilDate, days: number): CivilDate;
+/**
+ * Whole days from `a` to `b` (positive when `b` is later) — the NIGHTS
+ * count for a `[checkIn, checkOut)` stay expressed as civil dates.
+ */
+declare function civilDaysBetween(a: CivilDate, b: CivilDate): number;
+//#endregion
+export { CivilDate, LocalTimeParts, TimeZoneError, addCivilDays, civilDate, civilDateOf, civilDateToInstant, civilDaysBetween, isCivilDate, isValidTimeZone, listTimeZones, localTimeParts, zoneOffsetLabel, zoneOffsetMinutes };

package/dist/timezone.mjs

@@ -0,0 +1,238 @@
+//#region src/scheduling/timezone.ts
+const MINUTE_MS = 6e4;
+var TimeZoneError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "TimeZoneError";
+	}
+};
+const offsetFormatters = /* @__PURE__ */ new Map();
+const partsFormatters = /* @__PURE__ */ new Map();
+const civilFormatters = /* @__PURE__ */ new Map();
+function offsetFormatter(zone) {
+	let fmt = offsetFormatters.get(zone);
+	if (!fmt) {
+		fmt = new Intl.DateTimeFormat("en-US", {
+			timeZone: zone,
+			timeZoneName: "longOffset"
+		});
+		offsetFormatters.set(zone, fmt);
+	}
+	return fmt;
+}
+function partsFormatter(zone) {
+	let fmt = partsFormatters.get(zone);
+	if (!fmt) {
+		fmt = new Intl.DateTimeFormat("en-US", {
+			timeZone: zone,
+			weekday: "short",
+			hour: "2-digit",
+			minute: "2-digit",
+			hour12: false
+		});
+		partsFormatters.set(zone, fmt);
+	}
+	return fmt;
+}
+function civilFormatter(zone) {
+	let fmt = civilFormatters.get(zone);
+	if (!fmt) {
+		fmt = new Intl.DateTimeFormat("en-CA", {
+			timeZone: zone,
+			year: "numeric",
+			month: "2-digit",
+			day: "2-digit"
+		});
+		civilFormatters.set(zone, fmt);
+	}
+	return fmt;
+}
+/**
+* Is `zone` a valid IANA timezone name on this runtime's ICU data?
+* Use at BOOT to validate host config (an offer's `timezone`, an org
+* setting) — fail loud at wiring time, not on the first localized read.
+*/
+function isValidTimeZone(zone) {
+	if (typeof zone !== "string" || zone.length === 0) return false;
+	try {
+		offsetFormatter(zone);
+		return true;
+	} catch {
+		offsetFormatters.delete(zone);
+		return false;
+	}
+}
+let cachedZones;
+/**
+* Every IANA timezone name this runtime supports — the data source for a
+* Google-Calendar-style zone picker. Straight from ICU via
+* `Intl.supportedValuesOf` (Node >= 18); no bundled tz list to go stale.
+*
+* UIs typically label each entry with its current offset:
+* `listTimeZones().map((z) => ({ zone: z, label: zoneOffsetLabel(now, z) }))`.
+*/
+function listTimeZones() {
+	if (cachedZones) return cachedZones;
+	const intl = Intl;
+	if (typeof intl.supportedValuesOf !== "function") throw new TimeZoneError("Intl.supportedValuesOf is unavailable on this runtime (requires Node >= 18 / a modern browser). Upgrade the runtime or supply a static zone list.");
+	cachedZones = Object.freeze(intl.supportedValuesOf("timeZone"));
+	return cachedZones;
+}
+const OFFSET_RE = /GMT(?:([+-])(\d{2}):(\d{2}))?/;
+/**
+* The zone's UTC offset AT `instant`, in minutes east of UTC — DST-exact.
+* `zoneOffsetMinutes(july, 'Europe/London')` → 60; `(january, …)` → 0;
+* `(any, 'Asia/Dhaka')` → 360.
+*
+* This is the value `/calendar`'s docstring tells hosts to "resolve and pass
+* in": `startOfMonth(instant, zoneOffsetMinutes(instant, zone))`.
+*/
+function zoneOffsetMinutes(instant, zone) {
+	const label = zoneOffsetLabel(instant, zone);
+	const m = OFFSET_RE.exec(label);
+	if (!m) throw new TimeZoneError(`Unparseable offset '${label}' for zone '${zone}'.`);
+	if (m[1] === void 0) return 0;
+	return (m[1] === "-" ? -1 : 1) * (Number(m[2]) * 60 + Number(m[3]));
+}
+/**
+* The zone's offset label AT `instant` — `'GMT+06:00'` / `'GMT-05:30'` /
+* `'GMT'`. Ready-made display text for zone pickers.
+*/
+function zoneOffsetLabel(instant, zone) {
+	let fmt;
+	try {
+		fmt = offsetFormatter(zone);
+	} catch {
+		offsetFormatters.delete(zone);
+		throw new TimeZoneError(`Invalid IANA timezone: '${zone}'.`);
+	}
+	const part = fmt.formatToParts(instant).find((p) => p.type === "timeZoneName");
+	if (!part) throw new TimeZoneError(`Runtime produced no offset part for zone '${zone}'.`);
+	return part.value;
+}
+const WEEKDAY_TO_ISO = {
+	Mon: 1,
+	Tue: 2,
+	Wed: 3,
+	Thu: 4,
+	Fri: 5,
+	Sat: 6,
+	Sun: 7
+};
+/**
+* The wall-clock weekday + time of `instant` in `zone` — what pricing
+* schedules ("peak Fri 17:00–22:00"), slot grids, and working-hours checks
+* evaluate against. DST-exact per instant.
+*/
+function localTimeParts(instant, zone) {
+	let fmt;
+	try {
+		fmt = partsFormatter(zone);
+	} catch {
+		partsFormatters.delete(zone);
+		throw new TimeZoneError(`Invalid IANA timezone: '${zone}'.`);
+	}
+	let weekday;
+	let hour;
+	let minute;
+	for (const part of fmt.formatToParts(instant)) if (part.type === "weekday") weekday = part.value;
+	else if (part.type === "hour") hour = Number(part.value);
+	else if (part.type === "minute") minute = Number(part.value);
+	const isoWeekday = weekday !== void 0 ? WEEKDAY_TO_ISO[weekday] : void 0;
+	if (isoWeekday === void 0 || hour === void 0 || minute === void 0) throw new TimeZoneError(`Runtime produced incomplete wall parts for zone '${zone}'.`);
+	const h = hour === 24 ? 0 : hour;
+	return {
+		isoWeekday,
+		hour: h,
+		minute,
+		minutesOfDay: h * 60 + minute
+	};
+}
+const CIVIL_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
+/** Runtime guard for external input. */
+function isCivilDate(value) {
+	if (typeof value !== "string") return false;
+	const m = CIVIL_RE.exec(value);
+	if (!m) return false;
+	const y = Number(m[1]);
+	const mo = Number(m[2]);
+	const d = Number(m[3]);
+	if (mo < 1 || mo > 12 || d < 1) return false;
+	return d <= new Date(Date.UTC(y, mo, 0)).getUTCDate();
+}
+/** Validate + brand a `'YYYY-MM-DD'` string. Throws on malformed input. */
+function civilDate(value) {
+	if (!isCivilDate(value)) throw new TimeZoneError(`Invalid civil date '${value}' — expected 'YYYY-MM-DD'.`);
+	return value;
+}
+/**
+* The calendar day `instant` falls on IN `zone` — e.g. the POS business
+* date: `civilDateOf(new Date(), 'Asia/Dhaka')`. Never depends on the
+* server's TZ env.
+*/
+function civilDateOf(instant, zone) {
+	let fmt;
+	try {
+		fmt = civilFormatter(zone);
+	} catch {
+		civilFormatters.delete(zone);
+		throw new TimeZoneError(`Invalid IANA timezone: '${zone}'.`);
+	}
+	let y = "";
+	let m = "";
+	let d = "";
+	for (const part of fmt.formatToParts(instant)) if (part.type === "year") y = part.value;
+	else if (part.type === "month") m = part.value;
+	else if (part.type === "day") d = part.value;
+	return civilDate(`${y.padStart(4, "0")}-${m}-${d}`);
+}
+/**
+* Bind a civil date (+ optional wall time) to a zone → the exact instant.
+* `civilDateToInstant(night, hotelZone, { hour: 14 })` = check-in instant;
+* with no `time`, local midnight — the DST-exact "start of that day in that
+* zone".
+*
+* Two-pass offset resolution: the offset is looked up AT the candidate
+* instant, then re-checked, so days where a DST transition sits between the
+* wall time and the first guess still resolve correctly. Honest limit: a
+* wall time that does not exist (inside a spring-forward gap) resolves to
+* the instant the shifted clock reaches — the same choice Temporal's
+* `disambiguation: 'compatible'` makes.
+*/
+function civilDateToInstant(cd, zone, time = {}) {
+	const m = CIVIL_RE.exec(cd);
+	if (!m) throw new TimeZoneError(`Invalid civil date '${cd}'.`);
+	const hour = time.hour ?? 0;
+	const minute = time.minute ?? 0;
+	const wallAsUtc = Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3]), hour, minute);
+	const firstOffset = zoneOffsetMinutes(new Date(wallAsUtc), zone);
+	let instantMs = wallAsUtc - firstOffset * MINUTE_MS;
+	const refined = zoneOffsetMinutes(new Date(instantMs), zone);
+	if (refined !== firstOffset) instantMs = wallAsUtc - refined * MINUTE_MS;
+	return new Date(instantMs);
+}
+/**
+* Pure calendar-day arithmetic — `addCivilDays('2026-02-28', 1)` →
+* `'2026-03-01'`. Zone-free by definition (a civil date has no zone);
+* use it to iterate hotel nights / statement days.
+*/
+function addCivilDays(cd, days) {
+	const m = CIVIL_RE.exec(cd);
+	if (!m) throw new TimeZoneError(`Invalid civil date '${cd}'.`);
+	const d = new Date(Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3]) + days));
+	return civilDate(`${String(d.getUTCFullYear()).padStart(4, "0")}-${String(d.getUTCMonth() + 1).padStart(2, "0")}-${String(d.getUTCDate()).padStart(2, "0")}`);
+}
+/**
+* Whole days from `a` to `b` (positive when `b` is later) — the NIGHTS
+* count for a `[checkIn, checkOut)` stay expressed as civil dates.
+*/
+function civilDaysBetween(a, b) {
+	const pa = CIVIL_RE.exec(a);
+	const pb = CIVIL_RE.exec(b);
+	if (!pa || !pb) throw new TimeZoneError(`Invalid civil date '${!pa ? a : b}'.`);
+	const ma = Date.UTC(Number(pa[1]), Number(pa[2]) - 1, Number(pa[3]));
+	const mb = Date.UTC(Number(pb[1]), Number(pb[2]) - 1, Number(pb[3]));
+	return Math.round((mb - ma) / 864e5);
+}
+//#endregion
+export { TimeZoneError, addCivilDays, civilDate, civilDateOf, civilDateToInstant, civilDaysBetween, isCivilDate, isValidTimeZone, listTimeZones, localTimeParts, zoneOffsetLabel, zoneOffsetMinutes };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/primitives",
-  "version": "0.7.2",
+  "version": "0.9.0",
   "description": "Framework-agnostic TypeScript primitives shared across Classytic packages — Money, events, pagination, tenant config, and other building blocks.",
   "author": "Classytic",
   "license": "MIT",
@@ -37,6 +37,14 @@
       "types": "./dist/period.d.mts",
       "default": "./dist/period.mjs"
     },
+    "./calendar": {
+      "types": "./dist/calendar.d.mts",
+      "default": "./dist/calendar.mjs"
+    },
+    "./timezone": {
+      "types": "./dist/timezone.d.mts",
+      "default": "./dist/timezone.mjs"
+    },
     "./reference": {
       "types": "./dist/reference.d.mts",
       "default": "./dist/reference.mjs"
@@ -81,6 +89,10 @@
       "types": "./dist/sla.d.mts",
       "default": "./dist/sla.mjs"
     },
+    "./shelf-life": {
+      "types": "./dist/shelf-life.d.mts",
+      "default": "./dist/shelf-life.mjs"
+    },
     "./person": {
       "types": "./dist/person.d.mts",
       "default": "./dist/person.mjs"