solve-engine 2.25.0 → 2.27.0

package/dist/CalendarBackend-MdS3Bb4P.d.cts

@@ -0,0 +1,181 @@
+/**
+ * The calendar the engine computes dates with, behind one interface.
+ *
+ * Every date the engine holds is an instant: epoch milliseconds in a
+ * `Datetime` value, with no zone attached. Every date *question* the engine
+ * answers is a calendar question about that instant: which day it falls on,
+ * what the same wall-clock time a month later is, whether it is a Saturday,
+ * how it is written out. Answering those needs a time zone and a set of
+ * calendar rules, and until this interface existed the answer was always the
+ * JavaScript `Date` object read in the host process's own zone, scattered
+ * across some twenty files.
+ *
+ * A backend gathers those questions into one place so that a different
+ * implementation can answer them. Two ship with the engine. {@link DateCalendar}
+ * is the same `Date` code moved behind these methods and is the default, so
+ * nothing observable changes for a host that configures nothing. The
+ * `Temporal` backend (`solve-engine/temporal`) answers the same questions
+ * through a `Temporal` implementation the host hands it, native or polyfilled,
+ * and carries a time zone of its own rather than the process's; the engine
+ * never imports a polyfill.
+ *
+ * The contract is deliberately narrow. Methods take and return plain numbers
+ * and strings, never a `Date` or a `Temporal` object, so a `Datetime` value's
+ * payload stays a number and no worker message, snapshot or arena entry
+ * changes shape. Arithmetic whose answer does not depend on a zone (a day
+ * number, the days in a month, the ISO week) lives beside the backend in
+ * `calendar/Gregorian.ts` rather than behind it, because sharing one
+ * implementation is what keeps two backends from disagreeing on it.
+ *
+ * The shape is public and settled by the two backends that implement it. A
+ * host may implement the interface directly; a change to it follows the
+ * package's semantic versioning, so a new required method is a major.
+ *
+ * @module CalendarBackend
+ */
+/**
+ * The calendar fields of one instant, read in the backend's zone.
+ *
+ * `month0` counts from zero (January is 0) and `weekday` from Sunday (0) to
+ * Saturday (6), matching `Date` at every internal boundary so a backend cannot
+ * be off by one against the code that reads it. Every field is `NaN` for an
+ * instant the backend cannot represent.
+ */
+interface CalendarFields {
+    readonly year: number;
+    /** Zero-based month: 0 is January, 11 is December. */
+    readonly month0: number;
+    /** Day of the month, from 1. */
+    readonly day: number;
+    /** Day of the week: 0 is Sunday, 6 is Saturday. */
+    readonly weekday: number;
+    readonly hour: number;
+    readonly minute: number;
+    readonly second: number;
+    readonly millisecond: number;
+}
+/**
+ * The calendar fields a named time zone shows for an instant: the date and
+ * the wall-clock time, with the same zero-based month as {@link CalendarFields}.
+ * Sub-second precision is never needed for a zone conversion, so there is no
+ * millisecond field.
+ */
+interface ZonedFields {
+    readonly year: number;
+    /** Zero-based month: 0 is January, 11 is December. */
+    readonly month0: number;
+    /** Day of the month, from 1. */
+    readonly day: number;
+    readonly hour: number;
+    readonly minute: number;
+    readonly second: number;
+}
+/**
+ * The calendar computations the engine performs, as one replaceable unit.
+ *
+ * "Local" throughout means the backend's own zone: the host process's zone for
+ * the `Date` backend, the configured zone for the `Temporal` one. A local
+ * operation that cannot be represented (an instant past the range the backend
+ * supports, a field that is not finite) answers `NaN`, never throws; the
+ * caller decides what an unrepresentable date means for its form.
+ *
+ * The four named-zone methods are the exception, and the contract is stated on
+ * each: a zone name the runtime does not know throws its `RangeError`, as
+ * `Intl` and `Temporal` both do, because a zone reaches the backend only from
+ * the engine's own zone registry and an unknown one is a data fault the caller
+ * should see rather than a `NaN` to display. Callers hand those methods a
+ * finite instant (`now()`, or a literal already checked).
+ */
+interface CalendarBackend {
+    /** The current instant, in epoch milliseconds. Read at evaluation time, never baked into bytecode. */
+    now(): number;
+    /** The local calendar fields of an instant, `weekday` included. See {@link CalendarFields}. */
+    fields(epochMs: number): CalendarFields;
+    /**
+     * Local midnight on a calendar date, in epoch milliseconds.
+     *
+     * Fields overflow the way `Date`'s do (month 12 is January of the next
+     * year, day 0 the last day of the month before), which is what a caller
+     * checking for a rolled-over literal relies on: build the date, read its
+     * fields back, and a 30 February shows up as 1 or 2 March.
+     */
+    localMidnight(year: number, month0: number, day: number): number;
+    /**
+     * A wall-clock time on a calendar date, given as minutes past local
+     * midnight, in epoch milliseconds.
+     *
+     * The minutes name a clock reading, not an elapsed span: 540 minutes is
+     * 09:00 on that date even on a day with a daylight-saving transition,
+     * where 540 minutes of elapsed time from midnight would land at 10:00 or
+     * 08:00.
+     */
+    localWallClock(year: number, month0: number, day: number, minutesPastMidnight: number): number;
+    /**
+     * Move an instant by whole calendar days, holding the local wall-clock
+     * time. A day that contains a daylight-saving transition is 23 or 25
+     * hours long, so this is a field step, not an addition of milliseconds.
+     */
+    addDays(epochMs: number, days: number): number;
+    /**
+     * Move an instant by whole calendar months, holding the local wall-clock
+     * time and clamping the day to the length of the month landed in: 31
+     * January plus a month is 28 February, or 29 in a leap year, never 3 March.
+     */
+    addMonths(epochMs: number, months: number): number;
+    /** The local zone's offset from UTC at an instant, in minutes, positive when ahead of UTC. */
+    utcOffsetMinutes(epochMs: number): number;
+    /**
+     * Parse an ISO 8601 date or date-time string to epoch milliseconds, or
+     * `NaN` when it names no instant.
+     *
+     * A date-only string (`2019-04-01`) is UTC midnight; a date-time with no
+     * offset and no `Z` is local time. Both readings are the ECMAScript ones,
+     * and every backend reproduces them so the two spellings of a literal keep
+     * meaning the same instant whichever backend is in use.
+     */
+    parseIso8601(text: string): number;
+    /** The spelled-out local date in a locale, `Tuesday, March 10, 2026` in `en`. */
+    formatLongDate(epochMs: number, locale: string): string;
+    /** The local time of day in a locale, `9:30:00 AM` in `en`. */
+    formatTimeOfDay(epochMs: number, locale: string): string;
+    /**
+     * A named IANA zone's offset from UTC at an instant, in minutes, positive
+     * when ahead of UTC. Throws the runtime's `RangeError` for a zone it does
+     * not know or an instant it cannot represent.
+     */
+    zoneOffsetMinutes(zone: string, epochMs: number): number;
+    /**
+     * The calendar date and wall-clock time a named IANA zone shows for an
+     * instant. Throws the runtime's `RangeError` for a zone it does not know or
+     * an instant it cannot represent.
+     */
+    fieldsInZone(zone: string, epochMs: number): ZonedFields;
+    /**
+     * The wall-clock time in a named IANA zone, `1:00 AM`, in the `en-US` style
+     * the timezone forms answer in. Throws the runtime's `RangeError` for a
+     * zone it does not know or an instant it cannot represent.
+     */
+    formatTimeInZone(zone: string, epochMs: number): string;
+    /**
+     * The calendar date in a named IANA zone, `July 31, 2026`, in the `en-US`
+     * style the timezone forms answer in. Throws the runtime's `RangeError` for
+     * a zone it does not know or an instant it cannot represent.
+     */
+    formatDateInZone(zone: string, epochMs: number): string;
+    /**
+     * The zone this backend's "local" means, when it can name one.
+     *
+     * Optional, and deliberately so: the interface's own contract says a new
+     * REQUIRED method is a major, and every backend written against the shipped
+     * shape has to keep compiling. A backend that reads the host process's zone
+     * (the default {@link DateCalendar}) leaves it undefined rather than
+     * reporting a zone it does not itself compute in; one built for a named zone
+     * (`dateCalendarInZone`, the `Temporal` backend) returns that IANA name.
+     *
+     * A caller that needs "which zone is local here" and gets `undefined` should
+     * fall back to whatever it meant by local before, never guess a name.
+     */
+    zone?(): string;
+}
+
+export type { CalendarBackend as C, ZonedFields as Z, CalendarFields as a };

package/dist/CalendarBackend-MdS3Bb4P.d.ts

@@ -0,0 +1,181 @@
+/**
+ * The calendar the engine computes dates with, behind one interface.
+ *
+ * Every date the engine holds is an instant: epoch milliseconds in a
+ * `Datetime` value, with no zone attached. Every date *question* the engine
+ * answers is a calendar question about that instant: which day it falls on,
+ * what the same wall-clock time a month later is, whether it is a Saturday,
+ * how it is written out. Answering those needs a time zone and a set of
+ * calendar rules, and until this interface existed the answer was always the
+ * JavaScript `Date` object read in the host process's own zone, scattered
+ * across some twenty files.
+ *
+ * A backend gathers those questions into one place so that a different
+ * implementation can answer them. Two ship with the engine. {@link DateCalendar}
+ * is the same `Date` code moved behind these methods and is the default, so
+ * nothing observable changes for a host that configures nothing. The
+ * `Temporal` backend (`solve-engine/temporal`) answers the same questions
+ * through a `Temporal` implementation the host hands it, native or polyfilled,
+ * and carries a time zone of its own rather than the process's; the engine
+ * never imports a polyfill.
+ *
+ * The contract is deliberately narrow. Methods take and return plain numbers
+ * and strings, never a `Date` or a `Temporal` object, so a `Datetime` value's
+ * payload stays a number and no worker message, snapshot or arena entry
+ * changes shape. Arithmetic whose answer does not depend on a zone (a day
+ * number, the days in a month, the ISO week) lives beside the backend in
+ * `calendar/Gregorian.ts` rather than behind it, because sharing one
+ * implementation is what keeps two backends from disagreeing on it.
+ *
+ * The shape is public and settled by the two backends that implement it. A
+ * host may implement the interface directly; a change to it follows the
+ * package's semantic versioning, so a new required method is a major.
+ *
+ * @module CalendarBackend
+ */
+/**
+ * The calendar fields of one instant, read in the backend's zone.
+ *
+ * `month0` counts from zero (January is 0) and `weekday` from Sunday (0) to
+ * Saturday (6), matching `Date` at every internal boundary so a backend cannot
+ * be off by one against the code that reads it. Every field is `NaN` for an
+ * instant the backend cannot represent.
+ */
+interface CalendarFields {
+    readonly year: number;
+    /** Zero-based month: 0 is January, 11 is December. */
+    readonly month0: number;
+    /** Day of the month, from 1. */
+    readonly day: number;
+    /** Day of the week: 0 is Sunday, 6 is Saturday. */
+    readonly weekday: number;
+    readonly hour: number;
+    readonly minute: number;
+    readonly second: number;
+    readonly millisecond: number;
+}
+/**
+ * The calendar fields a named time zone shows for an instant: the date and
+ * the wall-clock time, with the same zero-based month as {@link CalendarFields}.
+ * Sub-second precision is never needed for a zone conversion, so there is no
+ * millisecond field.
+ */
+interface ZonedFields {
+    readonly year: number;
+    /** Zero-based month: 0 is January, 11 is December. */
+    readonly month0: number;
+    /** Day of the month, from 1. */
+    readonly day: number;
+    readonly hour: number;
+    readonly minute: number;
+    readonly second: number;
+}
+/**
+ * The calendar computations the engine performs, as one replaceable unit.
+ *
+ * "Local" throughout means the backend's own zone: the host process's zone for
+ * the `Date` backend, the configured zone for the `Temporal` one. A local
+ * operation that cannot be represented (an instant past the range the backend
+ * supports, a field that is not finite) answers `NaN`, never throws; the
+ * caller decides what an unrepresentable date means for its form.
+ *
+ * The four named-zone methods are the exception, and the contract is stated on
+ * each: a zone name the runtime does not know throws its `RangeError`, as
+ * `Intl` and `Temporal` both do, because a zone reaches the backend only from
+ * the engine's own zone registry and an unknown one is a data fault the caller
+ * should see rather than a `NaN` to display. Callers hand those methods a
+ * finite instant (`now()`, or a literal already checked).
+ */
+interface CalendarBackend {
+    /** The current instant, in epoch milliseconds. Read at evaluation time, never baked into bytecode. */
+    now(): number;
+    /** The local calendar fields of an instant, `weekday` included. See {@link CalendarFields}. */
+    fields(epochMs: number): CalendarFields;
+    /**
+     * Local midnight on a calendar date, in epoch milliseconds.
+     *
+     * Fields overflow the way `Date`'s do (month 12 is January of the next
+     * year, day 0 the last day of the month before), which is what a caller
+     * checking for a rolled-over literal relies on: build the date, read its
+     * fields back, and a 30 February shows up as 1 or 2 March.
+     */
+    localMidnight(year: number, month0: number, day: number): number;
+    /**
+     * A wall-clock time on a calendar date, given as minutes past local
+     * midnight, in epoch milliseconds.
+     *
+     * The minutes name a clock reading, not an elapsed span: 540 minutes is
+     * 09:00 on that date even on a day with a daylight-saving transition,
+     * where 540 minutes of elapsed time from midnight would land at 10:00 or
+     * 08:00.
+     */
+    localWallClock(year: number, month0: number, day: number, minutesPastMidnight: number): number;
+    /**
+     * Move an instant by whole calendar days, holding the local wall-clock
+     * time. A day that contains a daylight-saving transition is 23 or 25
+     * hours long, so this is a field step, not an addition of milliseconds.
+     */
+    addDays(epochMs: number, days: number): number;
+    /**
+     * Move an instant by whole calendar months, holding the local wall-clock
+     * time and clamping the day to the length of the month landed in: 31
+     * January plus a month is 28 February, or 29 in a leap year, never 3 March.
+     */
+    addMonths(epochMs: number, months: number): number;
+    /** The local zone's offset from UTC at an instant, in minutes, positive when ahead of UTC. */
+    utcOffsetMinutes(epochMs: number): number;
+    /**
+     * Parse an ISO 8601 date or date-time string to epoch milliseconds, or
+     * `NaN` when it names no instant.
+     *
+     * A date-only string (`2019-04-01`) is UTC midnight; a date-time with no
+     * offset and no `Z` is local time. Both readings are the ECMAScript ones,
+     * and every backend reproduces them so the two spellings of a literal keep
+     * meaning the same instant whichever backend is in use.
+     */
+    parseIso8601(text: string): number;
+    /** The spelled-out local date in a locale, `Tuesday, March 10, 2026` in `en`. */
+    formatLongDate(epochMs: number, locale: string): string;
+    /** The local time of day in a locale, `9:30:00 AM` in `en`. */
+    formatTimeOfDay(epochMs: number, locale: string): string;
+    /**
+     * A named IANA zone's offset from UTC at an instant, in minutes, positive
+     * when ahead of UTC. Throws the runtime's `RangeError` for a zone it does
+     * not know or an instant it cannot represent.
+     */
+    zoneOffsetMinutes(zone: string, epochMs: number): number;
+    /**
+     * The calendar date and wall-clock time a named IANA zone shows for an
+     * instant. Throws the runtime's `RangeError` for a zone it does not know or
+     * an instant it cannot represent.
+     */
+    fieldsInZone(zone: string, epochMs: number): ZonedFields;
+    /**
+     * The wall-clock time in a named IANA zone, `1:00 AM`, in the `en-US` style
+     * the timezone forms answer in. Throws the runtime's `RangeError` for a
+     * zone it does not know or an instant it cannot represent.
+     */
+    formatTimeInZone(zone: string, epochMs: number): string;
+    /**
+     * The calendar date in a named IANA zone, `July 31, 2026`, in the `en-US`
+     * style the timezone forms answer in. Throws the runtime's `RangeError` for
+     * a zone it does not know or an instant it cannot represent.
+     */
+    formatDateInZone(zone: string, epochMs: number): string;
+    /**
+     * The zone this backend's "local" means, when it can name one.
+     *
+     * Optional, and deliberately so: the interface's own contract says a new
+     * REQUIRED method is a major, and every backend written against the shipped
+     * shape has to keep compiling. A backend that reads the host process's zone
+     * (the default {@link DateCalendar}) leaves it undefined rather than
+     * reporting a zone it does not itself compute in; one built for a named zone
+     * (`dateCalendarInZone`, the `Temporal` backend) returns that IANA name.
+     *
+     * A caller that needs "which zone is local here" and gets `undefined` should
+     * fall back to whatever it meant by local before, never guess a name.
+     */
+    zone?(): string;
+}
+
+export type { CalendarBackend as C, ZonedFields as Z, CalendarFields as a };

package/dist/{Configuration-DnzYPmoK.d.cts → Configuration-BxriK9Kw.d.cts}

@@ -58,11 +58,25 @@ type HolidayCalendar = HolidayPredicate | Iterable<string | number | Date>;
  *   a host can match its readers' locale. `'MDY'` is what lets a US reader's
  *   `12/25/2023` parse, which `'auto'` refuses because the slash defaults to
  *   day-first.
+ * - `'locale'`: the order the reader's own machine writes dates in, asked of
+ *   `Intl` once per engine (see `calendar/HostLocale.ts`). Where that cannot
+ *   be answered, the engine reads dates exactly as `'auto'` does and reports
+ *   the fact through `ExpressionEngine.getDateReading()`, rather than guessing.
+ *   A host that is not the reader (a server rendering someone else's document)
+ *   names the reader instead, through {@link DateConfig.inputLocale}.
  *
- * Only the all-numeric literals are affected. A spelled-out month (`March 9,
- * 2024`) is never ambiguous, and an ISO timestamp is always read as ISO.
+ * Only ambiguous literals are affected. A spelled-out month (`March 9, 2024`)
+ * is never ambiguous; nor is a hyphen literal with a four-digit leading group
+ * (`2024-03-09`), which has no reading but year-month-day and is read as ISO
+ * under every order, timestamp or not.
  */
-type DateInputOrder = 'auto' | 'DMY' | 'MDY' | 'YMD';
+type DateInputOrder = 'auto' | 'locale' | 'DMY' | 'MDY' | 'YMD';
+/**
+ * What a date-shaped numeric run the configured order cannot read does: report
+ * the problem, or fall through to the arithmetic it is spelled like. See
+ * {@link DateConfig.onAmbiguous}.
+ */
+type DateAmbiguity = 'refuse' | 'arithmetic';
 /** Date-related engine configuration: offset limits, input order, holidays. */
 interface DateConfig {
     /**
@@ -70,6 +84,51 @@ interface DateConfig {
      * `'auto'` (by separator, the historic behaviour). See {@link DateInputOrder}.
      */
     readonly inputOrder: DateInputOrder;
+    /**
+     * The BCP-47 tag `'locale'` reads the order from, `"en-US"` or `"de-DE"`.
+     * Unset, the host machine is asked.
+     *
+     * Read ONLY when {@link inputOrder} is `'locale'`. Setting it beside any
+     * other order changes no result: a field that quietly switched inference on
+     * would make the predictable mistake a wrong reading rather than no change.
+     * Its shape is checked wherever it is set, though, and a tag `Intl` refuses
+     * (`"en_US"`, with an underscore) raises `DATE_INPUT_LOCALE_INVALID` at
+     * construction, because a locale silently ignored is a date order silently
+     * wrong.
+     *
+     * Deliberately separate from the engine's `locale` option, which is a
+     * language (`'en' | 'de' | 'fr'`) and carries no region. Day/month order is a
+     * region question: a bare `en` probes as month-first while a UK machine
+     * resolves to `en-GB` and probes as day-first, so wiring the two together
+     * would flip every existing British engine to month-first.
+     */
+    readonly inputLocale?: string;
+    /**
+     * What a date-shaped numeric run the resolved order cannot read does.
+     * Defaults to `'refuse'`.
+     *
+     * - `'refuse'`: the line reports a structured Error value naming the
+     *   problem, DATE_ORDER_MISMATCH when another order would have read it and
+     *   DATE_NOT_A_CALENDAR_DAY when no order names a real day. `12/25/2026` on
+     *   a day-first engine says there is no month 25, rather than answering
+     *   0.00.
+     * - `'arithmetic'`: the run falls through to the division or subtraction it
+     *   is spelled like, which is what every version before this one did.
+     *   `12/25/2026` is 0.00 again, and `2026-02-29` is 1,995.
+     *
+     * The refusal is scoped to runs nobody writes as arithmetic: a two-step
+     * chain ending in a four-digit denominator (`03/04/2026` as division is
+     * 0.0004), and an ISO-shaped hyphen run. A four-digit LEADING group is
+     * ordinary arithmetic (`1000/10/5` is 20, `1024/8/2` is 64) and is never
+     * refused, and neither is a run whose groups are all one or two digits
+     * (`12/13/14` stays 0.07), because a two-digit year is too weak a signal to
+     * hang a refusal on.
+     *
+     * The one refusal this setting does not restore is the dot form
+     * (`25.12.2026` under a month-first order): its only other outcome is a
+     * parse error, and an error is not an answer.
+     */
+    readonly onAmbiguous: DateAmbiguity;
     /**
      * How far forward a date offset whose COST grows with the offset may reach,
      * in years. Enforced by `vm/VM.ts`'s `addBusinessDays()`.
@@ -439,4 +498,4 @@ interface ValidationResult {
     warnings?: string[];
 }
 
-export { ConfigManager as C, DEFAULT_CONFIG as D, type EngineConfigOverride as E, type HolidayCalendar as H, type PerformanceConfig as P, type VMConfig as V, type WorkerConfig as W, type EngineConfig as a, type DateConfig as b, type DiagnosticConfig as c, type HolidayPredicate as d, type ValidationConfig as e, type ValidationResult as f };
+export { ConfigManager as C, type DateAmbiguity as D, type EngineConfigOverride as E, type HolidayCalendar as H, type PerformanceConfig as P, type VMConfig as V, type WorkerConfig as W, type EngineConfig as a, DEFAULT_CONFIG as b, type DateConfig as c, type DiagnosticConfig as d, type HolidayPredicate as e, type ValidationConfig as f, type ValidationResult as g };

package/dist/{Configuration-DnzYPmoK.d.ts → Configuration-BxriK9Kw.d.ts}

@@ -58,11 +58,25 @@ type HolidayCalendar = HolidayPredicate | Iterable<string | number | Date>;
  *   a host can match its readers' locale. `'MDY'` is what lets a US reader's
  *   `12/25/2023` parse, which `'auto'` refuses because the slash defaults to
  *   day-first.
+ * - `'locale'`: the order the reader's own machine writes dates in, asked of
+ *   `Intl` once per engine (see `calendar/HostLocale.ts`). Where that cannot
+ *   be answered, the engine reads dates exactly as `'auto'` does and reports
+ *   the fact through `ExpressionEngine.getDateReading()`, rather than guessing.
+ *   A host that is not the reader (a server rendering someone else's document)
+ *   names the reader instead, through {@link DateConfig.inputLocale}.
  *
- * Only the all-numeric literals are affected. A spelled-out month (`March 9,
- * 2024`) is never ambiguous, and an ISO timestamp is always read as ISO.
+ * Only ambiguous literals are affected. A spelled-out month (`March 9, 2024`)
+ * is never ambiguous; nor is a hyphen literal with a four-digit leading group
+ * (`2024-03-09`), which has no reading but year-month-day and is read as ISO
+ * under every order, timestamp or not.
  */
-type DateInputOrder = 'auto' | 'DMY' | 'MDY' | 'YMD';
+type DateInputOrder = 'auto' | 'locale' | 'DMY' | 'MDY' | 'YMD';
+/**
+ * What a date-shaped numeric run the configured order cannot read does: report
+ * the problem, or fall through to the arithmetic it is spelled like. See
+ * {@link DateConfig.onAmbiguous}.
+ */
+type DateAmbiguity = 'refuse' | 'arithmetic';
 /** Date-related engine configuration: offset limits, input order, holidays. */
 interface DateConfig {
     /**
@@ -70,6 +84,51 @@ interface DateConfig {
      * `'auto'` (by separator, the historic behaviour). See {@link DateInputOrder}.
      */
     readonly inputOrder: DateInputOrder;
+    /**
+     * The BCP-47 tag `'locale'` reads the order from, `"en-US"` or `"de-DE"`.
+     * Unset, the host machine is asked.
+     *
+     * Read ONLY when {@link inputOrder} is `'locale'`. Setting it beside any
+     * other order changes no result: a field that quietly switched inference on
+     * would make the predictable mistake a wrong reading rather than no change.
+     * Its shape is checked wherever it is set, though, and a tag `Intl` refuses
+     * (`"en_US"`, with an underscore) raises `DATE_INPUT_LOCALE_INVALID` at
+     * construction, because a locale silently ignored is a date order silently
+     * wrong.
+     *
+     * Deliberately separate from the engine's `locale` option, which is a
+     * language (`'en' | 'de' | 'fr'`) and carries no region. Day/month order is a
+     * region question: a bare `en` probes as month-first while a UK machine
+     * resolves to `en-GB` and probes as day-first, so wiring the two together
+     * would flip every existing British engine to month-first.
+     */
+    readonly inputLocale?: string;
+    /**
+     * What a date-shaped numeric run the resolved order cannot read does.
+     * Defaults to `'refuse'`.
+     *
+     * - `'refuse'`: the line reports a structured Error value naming the
+     *   problem, DATE_ORDER_MISMATCH when another order would have read it and
+     *   DATE_NOT_A_CALENDAR_DAY when no order names a real day. `12/25/2026` on
+     *   a day-first engine says there is no month 25, rather than answering
+     *   0.00.
+     * - `'arithmetic'`: the run falls through to the division or subtraction it
+     *   is spelled like, which is what every version before this one did.
+     *   `12/25/2026` is 0.00 again, and `2026-02-29` is 1,995.
+     *
+     * The refusal is scoped to runs nobody writes as arithmetic: a two-step
+     * chain ending in a four-digit denominator (`03/04/2026` as division is
+     * 0.0004), and an ISO-shaped hyphen run. A four-digit LEADING group is
+     * ordinary arithmetic (`1000/10/5` is 20, `1024/8/2` is 64) and is never
+     * refused, and neither is a run whose groups are all one or two digits
+     * (`12/13/14` stays 0.07), because a two-digit year is too weak a signal to
+     * hang a refusal on.
+     *
+     * The one refusal this setting does not restore is the dot form
+     * (`25.12.2026` under a month-first order): its only other outcome is a
+     * parse error, and an error is not an answer.
+     */
+    readonly onAmbiguous: DateAmbiguity;
     /**
      * How far forward a date offset whose COST grows with the offset may reach,
      * in years. Enforced by `vm/VM.ts`'s `addBusinessDays()`.
@@ -439,4 +498,4 @@ interface ValidationResult {
     warnings?: string[];
 }
 
-export { ConfigManager as C, DEFAULT_CONFIG as D, type EngineConfigOverride as E, type HolidayCalendar as H, type PerformanceConfig as P, type VMConfig as V, type WorkerConfig as W, type EngineConfig as a, type DateConfig as b, type DiagnosticConfig as c, type HolidayPredicate as d, type ValidationConfig as e, type ValidationResult as f };
+export { ConfigManager as C, type DateAmbiguity as D, type EngineConfigOverride as E, type HolidayCalendar as H, type PerformanceConfig as P, type VMConfig as V, type WorkerConfig as W, type EngineConfig as a, DEFAULT_CONFIG as b, type DateConfig as c, type DiagnosticConfig as d, type HolidayPredicate as e, type ValidationConfig as f, type ValidationResult as g };

package/dist/DateCalendar-B85t6Vk6.d.ts

@@ -0,0 +1,90 @@
+import { C as CalendarBackend, a as CalendarFields, Z as ZonedFields } from './CalendarBackend-MdS3Bb4P.js';
+
+/**
+ * The default {@link CalendarBackend}: the JavaScript `Date` object, read in
+ * the host process's time zone, with `Intl.DateTimeFormat` for named zones.
+ *
+ * This is the calendar code the engine has always run, moved behind the
+ * interface method by method rather than rewritten, so a host that configures
+ * nothing sees the same instants and the same strings it did before the
+ * backend existed. Where `Date` has a quirk (a two-digit year in a
+ * constructor maps to the 1900s, an out-of-range instant answers `NaN`), the
+ * quirk is kept here deliberately: the point of this backend is to be the
+ * behaviour the `Temporal` backend is measured against, not to improve on it.
+ *
+ * It stays the default because it is the one calendar every supported runtime
+ * has. `Temporal` ships unflagged in Node 26 and in current Chrome, Firefox
+ * and Deno, but not in Safari or in the Node 22 and 24 the engine supports,
+ * and the smallest polyfill adds about twenty kilobytes gzipped to a bundle
+ * that a host doing plain arithmetic never needs. A host that wants
+ * `Temporal` opts in through the engine's `calendar` option with the backend
+ * from `solve-engine/temporal`, and pays for it only then.
+ */
+declare class DateCalendar implements CalendarBackend {
+    now(): number;
+    fields(epochMs: number): CalendarFields;
+    localMidnight(year: number, month0: number, day: number): number;
+    localWallClock(year: number, month0: number, day: number, minutesPastMidnight: number): number;
+    addDays(epochMs: number, days: number): number;
+    addMonths(epochMs: number, months: number): number;
+    utcOffsetMinutes(epochMs: number): number;
+    parseIso8601(text: string): number;
+    formatLongDate(epochMs: number, locale: string): string;
+    formatTimeOfDay(epochMs: number, locale: string): string;
+    zoneOffsetMinutes(zone: string, epochMs: number): number;
+    fieldsInZone(zone: string, epochMs: number): ZonedFields;
+    formatTimeInZone(zone: string, epochMs: number): string;
+    formatDateInZone(zone: string, epochMs: number): string;
+}
+/**
+ * The one `Date` backend, shared by every engine that configures no other.
+ *
+ * Stateless, so sharing is safe: it holds no zone of its own and reads the
+ * process's. It is also what the sites with no engine in hand use (the
+ * normaliser rules that fuse a literal, `days in <period>`, the stocks and
+ * historical-currency date phrases, and `formatValue`), which is why an
+ * engine's own backend is the default here rather than a second copy.
+ */
+declare const DATE_CALENDAR: CalendarBackend;
+/**
+ * The backend a plugin function or converter should compute with: the one
+ * on its execution context, or the `Date` backend when the handler was
+ * called with no context (a direct call from a test, or an `as` converter
+ * invoked outside the VM).
+ *
+ * @param context - The execution context the handler received, if any.
+ * @returns The engine's backend when the context carries one, else {@link DATE_CALENDAR}.
+ */
+declare function calendarOf(context?: {
+    readonly calendar?: CalendarBackend;
+}): CalendarBackend;
+/**
+ * A `Date` backend that computes in a named time zone rather than the host
+ * process's.
+ *
+ * This is how a host pins the zone the engine reads dates in, and it is the
+ * only knob for it: the zone belongs to the calendar backend, which already
+ * owns what "local" means, so there is deliberately no `date.zone` config
+ * field to drift against it.
+ *
+ * ```ts
+ * import { createEngine, dateCalendarInZone } from "solve-engine";
+ * const engine = createEngine({ calendar: dateCalendarInZone("Asia/Tokyo") });
+ * ```
+ *
+ * It ships on the `Date` backend on purpose. `Temporal` is undefined on Node
+ * 24 and in Safari, so "pass a `Temporal` backend" would put the zone out of
+ * reach for most hosts today; `Temporal` stays an accuracy upgrade for the
+ * ambiguous wall clocks around a daylight-saving transition, never a
+ * prerequisite for naming a zone at all.
+ *
+ * @param zone - An IANA zone name, e.g. `"Asia/Tokyo"`.
+ * @returns A backend whose local zone is that one.
+ * @throws A `DATE_ZONE_UNKNOWN` config error when this runtime's `Intl` does
+ *   not know the zone. Refused here rather than per line, because a backend
+ *   that cannot compute in the zone it was asked for must not quietly answer
+ *   in another one.
+ */
+declare function dateCalendarInZone(zone: string): CalendarBackend;
+
+export { DATE_CALENDAR as D, DateCalendar as a, calendarOf as c, dateCalendarInZone as d };