solve-engine 2.25.0 → 2.27.0

package/dist/DateCalendar-CUGI1fT4.d.cts

@@ -0,0 +1,90 @@
+import { C as CalendarBackend, a as CalendarFields, Z as ZonedFields } from './CalendarBackend-MdS3Bb4P.cjs';
+
+/**
+ * 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 };

package/dist/{EngineError-fR1K1rvx.d.cts → EngineError-C-kBwYlN.d.cts}

@@ -170,6 +170,10 @@ declare const CoreErrorCodes: {
     readonly INVALID_TIME_LITERAL: "INVALID_TIME_LITERAL";
     /** A live-data form evaluated on an engine whose host switched the network off (`network.enabled: false`, see `constants/Configuration.ts`'s `NetworkConfig`). A recoverable Error value, raised by the VM for a currency conversion with no primed rate and for a plugin function that returned a promise, and by `createQueryResolver`'s plugin function when its preflight was skipped. Names the setting, so the reader knows it is policy rather than an outage. */
     readonly NETWORK_DISABLED: "NETWORK_DISABLED";
+    /** `createTemporalCalendar()` was handed something that is not a usable `Temporal` implementation: no `Now.instant`, `Now.timeZoneId`, `Instant.fromEpochMilliseconds` or `PlainDateTime.from`. Raised at construction, naming the missing member, rather than letting the first date computation fail on it obscurely. */
+    readonly TEMPORAL_IMPLEMENTATION_INVALID: "TEMPORAL_IMPLEMENTATION_INVALID";
+    /** The `timeZone` given to `createTemporalCalendar()` is not one the `Temporal` implementation knows. Raised at construction, so a misspelt zone is a configuration error the host sees once, not a `RangeError` from inside every date the engine computes. */
+    readonly TEMPORAL_TIME_ZONE_UNKNOWN: "TEMPORAL_TIME_ZONE_UNKNOWN";
     /** `fromJSON()` handed an object that is not a snapshot at all, or whose serialised-shape version does not match this engine's reader. The versioning gate that refuses an incompatible snapshot clearly rather than restoring it wrongly. See `engine/EngineSnapshot.ts`'s `assertRestorable()`. */
     readonly SNAPSHOT_VERSION_MISMATCH: "SNAPSHOT_VERSION_MISMATCH";
     /** A snapshot with the right envelope but internally inconsistent contents (an unrecognised number sentinel, an unknown value tag). Distinct from a version mismatch: the format is right, the payload is not. */
@@ -180,6 +184,8 @@ declare const CoreErrorCodes: {
     readonly INVALID_CONFIG_PATH: "INVALID_CONFIG_PATH";
     readonly CONFIG_SECTION_NOT_FOUND: "CONFIG_SECTION_NOT_FOUND";
     readonly CONFIG_PROPERTY_NOT_FOUND: "CONFIG_PROPERTY_NOT_FOUND";
+    /** `calendar: "temporal"` was asked for on a runtime with no `Temporal`. Refused rather than silently computing on `Date`, because a host that named Temporal did so to be sure what it was computing on. Recoverable. */
+    readonly CALENDAR_TEMPORAL_UNAVAILABLE: "CALENDAR_TEMPORAL_UNAVAILABLE";
     readonly PLUGIN_OPERATOR_COLLISION: "PLUGIN_OPERATOR_COLLISION";
     readonly PLUGIN_KEYWORD_COLLISION: "PLUGIN_KEYWORD_COLLISION";
     readonly PLUGIN_UNIT_COLLISION: "PLUGIN_UNIT_COLLISION";
@@ -201,11 +207,32 @@ declare const CoreErrorCodes: {
 /** Every error code the engine's own layers can produce, from {@link CoreErrorCodes}. */
 type CoreErrorCode = (typeof CoreErrorCodes)[keyof typeof CoreErrorCodes];
 /**
- * The aggregated catalog type. Currently just `CoreErrorCode`, union in
- * each package's own code-object type here as Phase 5 converts it, e.g.
- * `CoreErrorCode | WeatherErrorCode | StocksErrorCode | ...`.
+ * Codes for the datetime forms whose failure is raised OUTSIDE the datetime
+ * package.
+ *
+ * These sit here rather than beside the datetime parselets, which is where a
+ * package's own code object belongs, because the two sites that raise them are
+ * `vm/VM.ts` (the `in <zone>` branch of the unit-conversion opcode) and
+ * `calendar/DateCalendar.ts` (the zone-bound backend factory), and neither may
+ * import from `packages/`. A code object in the datetime package would put the
+ * name a core file needs on the wrong side of that line.
+ */
+declare const DatetimeErrorCodes: {
+    /** `2026-04-03 in Atlantis`: a Datetime met `in <name>` and the name is neither a zone this engine knows nor a unit. Before this code the epoch-millisecond payload was simply labelled with the name, and the line answered a fourteen-digit quantity in a unit called Atlantis. */
+    readonly DATETIME_ZONE_UNKNOWN: "DATETIME_ZONE_UNKNOWN";
+    /** `2026-04-03 in furlongs`: the same handler, where the name IS a real unit. Separate from `DATETIME_ZONE_UNKNOWN` because the two mistakes have different fixes: one is a misspelt zone, the other is a category error, and a message that suggests checking the spelling of `furlongs` would be no help at all. */
+    readonly DATETIME_NOT_CONVERTIBLE: "DATETIME_NOT_CONVERTIBLE";
+    /** `dateCalendarInZone("Europe/Atlantis")`: the zone-bound `Date` backend factory, given a zone this runtime's `Intl` cannot format with. Raised at construction rather than per line, because a backend that cannot compute in the zone it was asked for must not silently answer in another one. */
+    readonly DATE_ZONE_UNKNOWN: "DATE_ZONE_UNKNOWN";
+};
+/** Every code from {@link DatetimeErrorCodes}. */
+type DatetimeErrorCode = (typeof DatetimeErrorCodes)[keyof typeof DatetimeErrorCodes];
+/**
+ * The aggregated catalog type. Currently `CoreErrorCode` and
+ * `DatetimeErrorCode`, union in each package's own code-object type here as
+ * Phase 5 converts it, e.g. `CoreErrorCode | WeatherErrorCode | ...`.
  */
-type ErrorCode = CoreErrorCode;
+type ErrorCode = CoreErrorCode | DatetimeErrorCode;
 
 /**
  * The engine's structured error type, the "Rust/Go-style, verbose, easy to

package/dist/{EngineError-fR1K1rvx.d.ts → EngineError-C-kBwYlN.d.ts}

@@ -170,6 +170,10 @@ declare const CoreErrorCodes: {
     readonly INVALID_TIME_LITERAL: "INVALID_TIME_LITERAL";
     /** A live-data form evaluated on an engine whose host switched the network off (`network.enabled: false`, see `constants/Configuration.ts`'s `NetworkConfig`). A recoverable Error value, raised by the VM for a currency conversion with no primed rate and for a plugin function that returned a promise, and by `createQueryResolver`'s plugin function when its preflight was skipped. Names the setting, so the reader knows it is policy rather than an outage. */
     readonly NETWORK_DISABLED: "NETWORK_DISABLED";
+    /** `createTemporalCalendar()` was handed something that is not a usable `Temporal` implementation: no `Now.instant`, `Now.timeZoneId`, `Instant.fromEpochMilliseconds` or `PlainDateTime.from`. Raised at construction, naming the missing member, rather than letting the first date computation fail on it obscurely. */
+    readonly TEMPORAL_IMPLEMENTATION_INVALID: "TEMPORAL_IMPLEMENTATION_INVALID";
+    /** The `timeZone` given to `createTemporalCalendar()` is not one the `Temporal` implementation knows. Raised at construction, so a misspelt zone is a configuration error the host sees once, not a `RangeError` from inside every date the engine computes. */
+    readonly TEMPORAL_TIME_ZONE_UNKNOWN: "TEMPORAL_TIME_ZONE_UNKNOWN";
     /** `fromJSON()` handed an object that is not a snapshot at all, or whose serialised-shape version does not match this engine's reader. The versioning gate that refuses an incompatible snapshot clearly rather than restoring it wrongly. See `engine/EngineSnapshot.ts`'s `assertRestorable()`. */
     readonly SNAPSHOT_VERSION_MISMATCH: "SNAPSHOT_VERSION_MISMATCH";
     /** A snapshot with the right envelope but internally inconsistent contents (an unrecognised number sentinel, an unknown value tag). Distinct from a version mismatch: the format is right, the payload is not. */
@@ -180,6 +184,8 @@ declare const CoreErrorCodes: {
     readonly INVALID_CONFIG_PATH: "INVALID_CONFIG_PATH";
     readonly CONFIG_SECTION_NOT_FOUND: "CONFIG_SECTION_NOT_FOUND";
     readonly CONFIG_PROPERTY_NOT_FOUND: "CONFIG_PROPERTY_NOT_FOUND";
+    /** `calendar: "temporal"` was asked for on a runtime with no `Temporal`. Refused rather than silently computing on `Date`, because a host that named Temporal did so to be sure what it was computing on. Recoverable. */
+    readonly CALENDAR_TEMPORAL_UNAVAILABLE: "CALENDAR_TEMPORAL_UNAVAILABLE";
     readonly PLUGIN_OPERATOR_COLLISION: "PLUGIN_OPERATOR_COLLISION";
     readonly PLUGIN_KEYWORD_COLLISION: "PLUGIN_KEYWORD_COLLISION";
     readonly PLUGIN_UNIT_COLLISION: "PLUGIN_UNIT_COLLISION";
@@ -201,11 +207,32 @@ declare const CoreErrorCodes: {
 /** Every error code the engine's own layers can produce, from {@link CoreErrorCodes}. */
 type CoreErrorCode = (typeof CoreErrorCodes)[keyof typeof CoreErrorCodes];
 /**
- * The aggregated catalog type. Currently just `CoreErrorCode`, union in
- * each package's own code-object type here as Phase 5 converts it, e.g.
- * `CoreErrorCode | WeatherErrorCode | StocksErrorCode | ...`.
+ * Codes for the datetime forms whose failure is raised OUTSIDE the datetime
+ * package.
+ *
+ * These sit here rather than beside the datetime parselets, which is where a
+ * package's own code object belongs, because the two sites that raise them are
+ * `vm/VM.ts` (the `in <zone>` branch of the unit-conversion opcode) and
+ * `calendar/DateCalendar.ts` (the zone-bound backend factory), and neither may
+ * import from `packages/`. A code object in the datetime package would put the
+ * name a core file needs on the wrong side of that line.
+ */
+declare const DatetimeErrorCodes: {
+    /** `2026-04-03 in Atlantis`: a Datetime met `in <name>` and the name is neither a zone this engine knows nor a unit. Before this code the epoch-millisecond payload was simply labelled with the name, and the line answered a fourteen-digit quantity in a unit called Atlantis. */
+    readonly DATETIME_ZONE_UNKNOWN: "DATETIME_ZONE_UNKNOWN";
+    /** `2026-04-03 in furlongs`: the same handler, where the name IS a real unit. Separate from `DATETIME_ZONE_UNKNOWN` because the two mistakes have different fixes: one is a misspelt zone, the other is a category error, and a message that suggests checking the spelling of `furlongs` would be no help at all. */
+    readonly DATETIME_NOT_CONVERTIBLE: "DATETIME_NOT_CONVERTIBLE";
+    /** `dateCalendarInZone("Europe/Atlantis")`: the zone-bound `Date` backend factory, given a zone this runtime's `Intl` cannot format with. Raised at construction rather than per line, because a backend that cannot compute in the zone it was asked for must not silently answer in another one. */
+    readonly DATE_ZONE_UNKNOWN: "DATE_ZONE_UNKNOWN";
+};
+/** Every code from {@link DatetimeErrorCodes}. */
+type DatetimeErrorCode = (typeof DatetimeErrorCodes)[keyof typeof DatetimeErrorCodes];
+/**
+ * The aggregated catalog type. Currently `CoreErrorCode` and
+ * `DatetimeErrorCode`, union in each package's own code-object type here as
+ * Phase 5 converts it, e.g. `CoreErrorCode | WeatherErrorCode | ...`.
  */
-type ErrorCode = CoreErrorCode;
+type ErrorCode = CoreErrorCode | DatetimeErrorCode;
 
 /**
  * The engine's structured error type, the "Rust/Go-style, verbose, easy to

package/dist/{FormattingSettings-bRKjU7wI.d.ts → FormattingSettings-ByO-4wiM.d.cts}

@@ -1,3 +1,5 @@
+import { C as CalendarBackend } from './CalendarBackend-MdS3Bb4P.cjs';
+
 /**
  * How a Datetime value is rendered.
  *
@@ -15,6 +17,18 @@ type DateOutputFormat = "long" | "iso" | "dmy" | "mdy";
  * This allows the engine to format values without depending on app-specific settings
  */
 interface FormattingSettings {
+    /**
+     * The calendar backend a date is written out through: which local day and
+     * wall-clock time an instant shows as. Pass the same backend the engine
+     * was given as its `calendar` option, so a date displays in the zone it
+     * was computed in. Absent means the built-in `Date` backend, the process's
+     * own zone, which is what every engine computes with by default.
+     *
+     * A backend is an object of functions, so it cannot cross a `postMessage`
+     * boundary: a worker runtime takes its backend from `WorkerRuntimeOptions`
+     * and applies it to the formatting it receives.
+     */
+    calendar?: CalendarBackend;
     floatResult: {
         decimalPlaces: number;
         enableSeperator: boolean;

package/dist/{FormattingSettings-bRKjU7wI.d.cts → FormattingSettings-CvCzAfsz.d.ts}

@@ -1,3 +1,5 @@
+import { C as CalendarBackend } from './CalendarBackend-MdS3Bb4P.js';
+
 /**
  * How a Datetime value is rendered.
  *
@@ -15,6 +17,18 @@ type DateOutputFormat = "long" | "iso" | "dmy" | "mdy";
  * This allows the engine to format values without depending on app-specific settings
  */
 interface FormattingSettings {
+    /**
+     * The calendar backend a date is written out through: which local day and
+     * wall-clock time an instant shows as. Pass the same backend the engine
+     * was given as its `calendar` option, so a date displays in the zone it
+     * was computed in. Absent means the built-in `Date` backend, the process's
+     * own zone, which is what every engine computes with by default.
+     *
+     * A backend is an object of functions, so it cannot cross a `postMessage`
+     * boundary: a worker runtime takes its backend from `WorkerRuntimeOptions`
+     * and applies it to the formatting it receives.
+     */
+    calendar?: CalendarBackend;
     floatResult: {
         decimalPlaces: number;
         enableSeperator: boolean;

package/dist/{Lexer-aB95pjoX.d.cts → Lexer-DhGhoAa2.d.cts}

@@ -1,5 +1,5 @@
-import { T as Token } from './Token-CbP_OutD.cjs';
-import { E as EngineError } from './EngineError-fR1K1rvx.cjs';
+import { T as Token } from './Token-D8f7yaz1.cjs';
+import { E as EngineError } from './EngineError-C-kBwYlN.cjs';
 
 /** Trie node for multi-word phrase matching. */
 interface PhraseNode {
@@ -129,9 +129,19 @@ declare class LexerToken implements Token {
     col: number;
     /** See {@link Token.sourceEnd}. Set only on normalizer-fused tokens. */
     sourceEnd?: number | undefined;
+    /** See {@link Token.fault}. Set only on a fused token standing for a run the engine refuses to read. */
+    fault?: {
+        readonly code: string;
+        readonly message: string;
+    } | undefined;
     constructor(type: string, typeId: number, value: string, text: string, offset: number, lineBreaks: number, line: number, col: number, 
     /** See {@link Token.sourceEnd}. Set only on normalizer-fused tokens. */
-    sourceEnd?: number | undefined);
+    sourceEnd?: number | undefined, 
+    /** See {@link Token.fault}. Set only on a fused token standing for a run the engine refuses to read. */
+    fault?: {
+        readonly code: string;
+        readonly message: string;
+    } | undefined);
 }
 /**
  * Plugin interface for extending the ExpressionLexer with custom tokens.

package/dist/{Lexer-Bmctxl0n.d.ts → Lexer-DqtnZMC5.d.ts}

@@ -1,5 +1,5 @@
-import { T as Token } from './Token-CbP_OutD.js';
-import { E as EngineError } from './EngineError-fR1K1rvx.js';
+import { T as Token } from './Token-D8f7yaz1.js';
+import { E as EngineError } from './EngineError-C-kBwYlN.js';
 
 /** Trie node for multi-word phrase matching. */
 interface PhraseNode {
@@ -129,9 +129,19 @@ declare class LexerToken implements Token {
     col: number;
     /** See {@link Token.sourceEnd}. Set only on normalizer-fused tokens. */
     sourceEnd?: number | undefined;
+    /** See {@link Token.fault}. Set only on a fused token standing for a run the engine refuses to read. */
+    fault?: {
+        readonly code: string;
+        readonly message: string;
+    } | undefined;
     constructor(type: string, typeId: number, value: string, text: string, offset: number, lineBreaks: number, line: number, col: number, 
     /** See {@link Token.sourceEnd}. Set only on normalizer-fused tokens. */
-    sourceEnd?: number | undefined);
+    sourceEnd?: number | undefined, 
+    /** See {@link Token.fault}. Set only on a fused token standing for a run the engine refuses to read. */
+    fault?: {
+        readonly code: string;
+        readonly message: string;
+    } | undefined);
 }
 /**
  * Plugin interface for extending the ExpressionLexer with custom tokens.

package/dist/{PackageCompatibility-CUVg8tmt.d.cts → PackageCompatibility-CNiTtC6S.d.cts}

@@ -1,4 +1,4 @@
-import { I as IEnginePackage } from './PackageRegistry-Dvn4i2QK.cjs';
+import { I as IEnginePackage } from './PackageRegistry-BHBCFswo.cjs';
 
 /**
  * Package load-time compatibility checking, the "detect overlapping

package/dist/{PackageCompatibility-BludTs7v.d.ts → PackageCompatibility-fj_f7uqC.d.ts}

@@ -1,4 +1,4 @@
-import { I as IEnginePackage } from './PackageRegistry-DT-x32OM.js';
+import { I as IEnginePackage } from './PackageRegistry-CNZUwWHJ.js';
 
 /**
  * Package load-time compatibility checking, the "detect overlapping