solve-engine 2.24.0 → 2.26.0

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

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-D1kXsjIj.d.cts → EngineError-C-kBwYlN.d.cts}

@@ -38,6 +38,8 @@ declare const CoreErrorCodes: {
     readonly UNEXPECTED_TRAILING_TOKEN: "UNEXPECTED_TRAILING_TOKEN";
     readonly PARSE_ERROR: "PARSE_ERROR";
     readonly TOO_MANY_NUMERIC_CONSTANTS: "TOO_MANY_NUMERIC_CONSTANTS";
+    /** A raw bytecode operand outside 0 to 255, or a jump patch outside the emitted stream (`parser/BytecodeBuilder.ts`'s `emitIndex`, `emitByte`, `patchJump`). `build()` keeps one byte per operand, so 300 used to become 44 with no error and the program read the wrong constant or plugin function. A package-authoring fault, reported at compile time. */
+    readonly BYTECODE_OPERAND_OUT_OF_RANGE: "BYTECODE_OPERAND_OUT_OF_RANGE";
     readonly TOO_MANY_STRING_CONSTANTS: "TOO_MANY_STRING_CONSTANTS";
     readonly NO_MATCHING_PHRASE_ALTERNATIVE: "NO_MATCHING_PHRASE_ALTERNATIVE";
     readonly INVALID_PHRASE_PATTERN: "INVALID_PHRASE_PATTERN";
@@ -168,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. */
@@ -178,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";
@@ -199,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-D1kXsjIj.d.ts → EngineError-C-kBwYlN.d.ts}

@@ -38,6 +38,8 @@ declare const CoreErrorCodes: {
     readonly UNEXPECTED_TRAILING_TOKEN: "UNEXPECTED_TRAILING_TOKEN";
     readonly PARSE_ERROR: "PARSE_ERROR";
     readonly TOO_MANY_NUMERIC_CONSTANTS: "TOO_MANY_NUMERIC_CONSTANTS";
+    /** A raw bytecode operand outside 0 to 255, or a jump patch outside the emitted stream (`parser/BytecodeBuilder.ts`'s `emitIndex`, `emitByte`, `patchJump`). `build()` keeps one byte per operand, so 300 used to become 44 with no error and the program read the wrong constant or plugin function. A package-authoring fault, reported at compile time. */
+    readonly BYTECODE_OPERAND_OUT_OF_RANGE: "BYTECODE_OPERAND_OUT_OF_RANGE";
     readonly TOO_MANY_STRING_CONSTANTS: "TOO_MANY_STRING_CONSTANTS";
     readonly NO_MATCHING_PHRASE_ALTERNATIVE: "NO_MATCHING_PHRASE_ALTERNATIVE";
     readonly INVALID_PHRASE_PATTERN: "INVALID_PHRASE_PATTERN";
@@ -168,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. */
@@ -178,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";
@@ -199,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-CqagTewQ.d.ts → Lexer-DhGhoAa2.d.cts}

@@ -1,4 +1,5 @@
-import { T as Token } from './Token-CbP_OutD.js';
+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 {
@@ -101,6 +102,14 @@ interface ScanLineResult {
     tokens: Token[];
     /** Inline solve spans found in this line (empty if none). */
     inlineSolves: InlineSolveSpan[];
+    /**
+     * The structured error the tokeniser raised on this line, if it raised one
+     * (an unterminated string literal is the one it can raise today). The line
+     * carries no tokens then, and the rest of the document is unaffected: a
+     * half-typed quote used to escape {@link ExpressionLexer.scanDocument} as
+     * a throw and take every other line's result down with it.
+     */
+    error?: EngineError;
 }
 /**
  * A token, as the lexer produces it.
@@ -120,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.
@@ -208,16 +227,6 @@ interface LexerVocabulary {
  */
 declare class ExpressionLexer {
     private static readonly CHAR_CLASS;
-    /**
-     * Configured TokenLookup from TokenClassRegistry. When set, replaces
-     * the internal keyword map and unit set with registry-built equivalents.
-     * Enables data-driven keyword/unit registration across locale keywords,
-     * provider keywords, and plugins.
-     *
-     * Set at construction time via the constructor parameter. Plugin-registered
-     * keywords/units (via registerVocabulary()) are checked alongside
-     * the configuredLookup, neither source is bypassed.
-     */ private configuredLookup;
     private input;
     private pos;
     private len;
@@ -227,7 +236,16 @@ declare class ExpressionLexer {
     private keywordMap;
     private mergedKeywords;
     private mergedUnits;
-    private pluginKeywordMap;
+    /**
+     * Who registered each plugin keyword, unit and two-character operator, in
+     * registration order. Two packages may claim the same word (the
+     * compatibility index warns, and the last registered wins, as before); the
+     * owner lists make unregistration exact, so removing one package hands the
+     * word back to the other rather than deleting it for both.
+     */
+    private pluginKeywordOwners;
+    private pluginUnitOwners;
+    private pluginOperatorOwners;
     private pluginOperators;
     private pluginUnits;
     private hasPluginOps;
@@ -235,7 +253,7 @@ declare class ExpressionLexer {
     private locale;
     /**
      * Inline solve spans collected during the most recent tokenization pass.
-     * Populated by [Symbol.iterator]() and consumed by scanDocument().
+     * Populated by tokenizeInto() and consumed by scanDocument().
      */
     _inlineSolveSpans: InlineSolveSpan[];
     private pluginRawLinePatterns;
@@ -260,7 +278,14 @@ declare class ExpressionLexer {
     private matchRawLine;
     /** Rebuild merged keyword and unit collections after plugin registration. */
     private rebuildMergedUnits;
-    constructor(localeCode?: string, lookup?: TokenLookup);
+    /**
+     * @param localeCode - Locale whose keyword table seeds the lexer.
+     * @param _lookup - Ignored. The lexer built its keyword, unit and phrase
+     *   tables from the locale and the registered packages and never read the
+     *   lookup it was handed; the parameter stays so existing callers compile.
+     *   @deprecated Removed in 3.0.
+     */
+    constructor(localeCode?: string, _lookup?: TokenLookup);
     /**
      * Register a plugin to extend the lexer with custom tokens.
      *
@@ -276,6 +301,10 @@ declare class ExpressionLexer {
      * that conflicts with a built-in one.
      */
     registerVocabulary(plugin: LexerVocabulary): void;
+    /** Record `owner`'s claim on `key`. The newest claim is the one in force. */
+    private claim;
+    /** Drop `owner`'s claim on `key`, and return the claim now in force, if any is left. */
+    private release;
     /**
      * Unregister a plugin, removing its custom tokens from the lexer.
      *
@@ -307,9 +336,9 @@ declare class ExpressionLexer {
      *   lines that classifyLine() marks as having inline solves.
      *
      * Tokenization is scoped to each line by temporarily restricting
-     * `this.len` to the line end position, so the [Symbol.iterator]
-     * generator naturally stops at the line boundary. After tokenization,
-     * `this.len` is restored and `this.pos` advances past the newline.
+     * `this.len` to the line end position, so tokenizeInto() naturally
+     * stops at the line boundary. After tokenization, `this.len` is
+     * restored and `this.pos` advances past the newline.
      *
      * @param text The full document text (with newlines).
      * @returns Array of ScanLineResult, one per line, in document order.
@@ -318,9 +347,7 @@ declare class ExpressionLexer {
     /**
      * Tokenize an expression string into an array of Tokens.
      *
-     * Delegates to the lazy [Symbol.iterator]() generator and collects all
-     * yielded tokens via Array.from(). For memory-sensitive use cases, prefer
-     * iterating the lexer directly with for...of to avoid array allocation.
+     * Runs {@link tokenizeInto} into a fresh array.
      *
      * Optimizations:
      *  - CHAR_CLASS jump table (Uint8Array) → switch on small integers
@@ -332,20 +359,31 @@ declare class ExpressionLexer {
      */
     tokenizeAll(): Token[];
     /**
-     * Lazy token-by-token generator. Yields each token without allocating an
-     * intermediate Token[] array. Supports for...of and spread usage.
+     * Scan the current input and append every token to `out`.
+     *
+     * This is the scanner itself: {@link tokenizeAll} and the iterator are
+     * thin wrappers over it. It pushes into an array the caller owns rather
+     * than yielding, because a generator paid a resume per token and
+     * `Array.from` a second pass on top, and because a caller that catches a
+     * tokeniser fault (highlighting a line with an unterminated quote) still
+     * holds the tokens read before it.
      *
-     * Usage:
-     *   for (const t of lexer) { ... }  // lazy, no array allocation
-     *   const tokens = [...lexer];       // materializes via spread
-     *   const tokens = lexer.tokenizeAll(); // materializes via Array.from()
+     * IMPORTANT: `this.len` is read ONCE on entry (const len = this.len).
+     * `scanDocument()` relies on this to scope a pass to a single line by
+     * restricting `this.len` to the line end before calling. Do not re-read
+     * `this.len` mid-loop without also updating `scanDocument()`.
      *
-     * IMPORTANT: This generator captures `this.len` ONCE at creation time
-     * (const len = this.len). `scanDocument()` relies on this behavior to
-     * scope tokenization to a single line by temporarily restricting
-     * `this.len` to the line end position before creating the iterator.
-     * Do NOT refactor to re-read `this.len` mid-loop without also updating
-     * `scanDocument()`.
+     * @param out - The array to append to. Left as it was if the input is empty.
+     */
+    tokenizeInto(out: Token[]): void;
+    /**
+     * Iterate the tokens of the current input.
+     *
+     * Runs {@link tokenizeInto} first, so the tokens are the same as before,
+     * but a fault part way through the line is thrown from the first
+     * `next()` rather than at the token it occurred on. A caller that wants
+     * the tokens read before a fault calls {@link tokenizeInto} with its own
+     * array.
      */
     [Symbol.iterator](): Generator<Token, void, undefined>;
     /**
@@ -456,6 +494,27 @@ declare class ExpressionLexer {
      * `#12345` (length 5), `#ff0000zz` (trailing word) do not.
      */
     private matchHexColourEnd;
+    /**
+     * Whether an inline-solve opener (`s` + backtick) occurs in `[from, end)`.
+     *
+     * Bounded by hand rather than written as `input.indexOf("s\`", from)`. This
+     * used to be the `indexOf` form with an `idx < end` check afterwards, which
+     * is correct but not bounded: when {@link scanDocument} is classifying,
+     * `this.input` is the whole document, so a line with no marker scanned to
+     * the END OF THE DOCUMENT before the check could reject the hit. Every line
+     * paid for every line after it, and a whole-document parse was quadratic in
+     * line count (measured at 28.9 us per line at 10,000 lines against 10.1 us
+     * at 1,000, and two thirds of the parse's self time in a profile). A prose
+     * document with many candidate `s` characters was worse still. The
+     * wikilink close in {@link indexOfWithin} had the same shape.
+     */
+    private hasInlineSolveWithin;
+    /**
+     * `input.indexOf(needle, from)` restricted to `[from, end)`, returning -1
+     * when the needle does not occur wholly before `end`. See
+     * {@link hasInlineSolveWithin} for why the plain `indexOf` was not enough.
+     */
+    private indexOfWithin;
     private classifyFromPositions;
     /**
      * Classify a single line of markdown text.
@@ -530,11 +589,11 @@ declare class Lexer {
     private tokenIdx;
     /**
      * @param localeCode - Locale code (e.g., "en", "de"). Defaults to "en".
-     * @param tokenLookup - Optional TokenLookup from TokenClassRegistry.
-     *   When provided, configures ExpressionLexer to use registry-built
-     *   keyword/unit/phrase lookups instead of internal instance maps.
+     * @param _tokenLookup - Ignored. The lexer never read the lookup it was
+     *   handed; the parameter stays so existing callers compile.
+     *   @deprecated Removed in 3.0.
      */
-    constructor(localeCode?: string, tokenLookup?: TokenLookup);
+    constructor(localeCode?: string, _tokenLookup?: TokenLookup);
     reset(input: string, state?: LexerState): void;
     /**
      * Classify a single line of markdown text (Phase B).