solve-engine 2.24.0 → 2.26.0

package/dist/{BytecodeBuilder-aqVa7Plx.d.cts → BytecodeBuilder-DSWKZi4f.d.cts}

@@ -199,6 +199,8 @@ declare class BytecodeBuilder {
     private numbers;
     private strings;
     private stringIndex;
+    /** Value (or {@link NEGATIVE_ZERO_KEY}) to its slot in `numbers`, so a repeated literal is emitted once. */
+    private numberIndex;
     private _hasAsync;
     private userFunctionBodies;
     private anonymousBodies;
@@ -222,17 +224,17 @@ declare class BytecodeBuilder {
     /** Emit an {@link OpCode} instruction. */
     emitOpcode(op: OpCode): void;
     /**
-     * Emit a numeric literal: appends `n` to the program's constant pool and
-     * writes its index into the opcode stream (read back by the VM as e.g.
-     * `PUSH_NUMBER <idx>`).
+     * Emit a numeric literal: interns `n` into the program's constant pool
+     * (deduplicated, like {@link emitString}) and writes its index into the
+     * opcode stream (read back by the VM as e.g. `PUSH_NUMBER <idx>`).
      *
-     * Numeric constants are NOT deduplicated (unlike {@link emitString})
-     * every call appends a new entry, so an expression with more than
-     * {@link MAX_CONSTANT_POOL_INDEX}+1 distinct numeric-literal occurrences
-     * throws rather than silently wrapping the index (see
-     * `MAX_CONSTANT_POOL_INDEX`'s doc for what that would otherwise do).
+     * Deduplicated so that the 256-entry pool counts distinct values rather
+     * than occurrences: a long line of repeated literals used to exhaust it
+     * long before it held 256 different numbers. Negative zero keeps its own
+     * slot, because `1 / -0` is not `1 / 0`; NaN shares one, since every NaN
+     * reads the same.
      *
-     * @throws If the constant pool would exceed 256 entries.
+     * @throws If the pool would exceed 256 distinct entries.
      */
     emitNumber(n: number): void;
     /**

package/dist/{BytecodeBuilder-aqVa7Plx.d.ts → BytecodeBuilder-DSWKZi4f.d.ts}

@@ -199,6 +199,8 @@ declare class BytecodeBuilder {
     private numbers;
     private strings;
     private stringIndex;
+    /** Value (or {@link NEGATIVE_ZERO_KEY}) to its slot in `numbers`, so a repeated literal is emitted once. */
+    private numberIndex;
     private _hasAsync;
     private userFunctionBodies;
     private anonymousBodies;
@@ -222,17 +224,17 @@ declare class BytecodeBuilder {
     /** Emit an {@link OpCode} instruction. */
     emitOpcode(op: OpCode): void;
     /**
-     * Emit a numeric literal: appends `n` to the program's constant pool and
-     * writes its index into the opcode stream (read back by the VM as e.g.
-     * `PUSH_NUMBER <idx>`).
+     * Emit a numeric literal: interns `n` into the program's constant pool
+     * (deduplicated, like {@link emitString}) and writes its index into the
+     * opcode stream (read back by the VM as e.g. `PUSH_NUMBER <idx>`).
      *
-     * Numeric constants are NOT deduplicated (unlike {@link emitString})
-     * every call appends a new entry, so an expression with more than
-     * {@link MAX_CONSTANT_POOL_INDEX}+1 distinct numeric-literal occurrences
-     * throws rather than silently wrapping the index (see
-     * `MAX_CONSTANT_POOL_INDEX`'s doc for what that would otherwise do).
+     * Deduplicated so that the 256-entry pool counts distinct values rather
+     * than occurrences: a long line of repeated literals used to exhaust it
+     * long before it held 256 different numbers. Negative zero keeps its own
+     * slot, because `1 / -0` is not `1 / 0`; NaN shares one, since every NaN
+     * reads the same.
      *
-     * @throws If the constant pool would exceed 256 entries.
+     * @throws If the pool would exceed 256 distinct entries.
      */
     emitNumber(n: number): void;
     /**

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 };