solve-engine 2.25.0 → 2.27.0

package/dist/{PackageRegistry-DT-x32OM.d.ts → PackageRegistry-CNZUwWHJ.d.ts}

@@ -1,15 +1,52 @@
-import { a as PrecedenceParser, b as PrefixParselet, I as InfixParselet } from './Parselet-DqTbbtWA.js';
-import { V as Value, a as ValueType } from './Value-Ds3Gy07C.js';
-import { M as MarkdownLineType, L as Lexer, e as TokenCategory, c as LexerVocabulary } from './Lexer-Bmctxl0n.js';
+import { a as PrecedenceParser, b as PrefixParselet, I as InfixParselet } from './Parselet-Dgymjxzd.js';
+import { M as MarkdownLineType, L as Lexer, e as TokenCategory, c as LexerVocabulary } from './Lexer-DqtnZMC5.js';
 import { IAsyncResolver } from './resolvers.js';
-import { T as TokenFusion, c as TokenNormalizer, a as NormalizerRule } from './TokenNormalizer-CLBtiE8M.js';
-import { D as DependencyGraph, V as VM, a as DagSnapshot, b as EngineContext, S as ScopeManager, P as PluginFunctionHandler } from './ScopeManager-B636am7Y.js';
+import { T as TokenFusion, c as TokenNormalizer, a as NormalizerRule } from './TokenNormalizer-IF7nPRMp.js';
+import { D as DependencyGraph, V as VM, f as DagSnapshot, g as EngineContext, S as ScopeManager, P as PluginFunctionHandler, A as AsConverter } from './VMBuiltins-CZiZRKn-.js';
+import { V as Value, b as ValueType, D as DatetimeGrain } from './Value-BYHw-x7q.js';
 import { a as BytecodeProgram } from './BytecodeBuilder-DSWKZi4f.js';
+import { C as CalendarBackend } from './CalendarBackend-MdS3Bb4P.js';
 import { QueryClient } from '@tanstack/query-core';
-import { E as EngineError } from './EngineError-fR1K1rvx.js';
-import { a as DiagnosticReportJSON, D as DiagnosticPipeline } from './pipeline-DTqGLPsV.js';
-import { T as Token } from './Token-CbP_OutD.js';
-import { E as EngineConfigOverride, a as EngineConfig } from './Configuration-DnzYPmoK.js';
+import { E as EngineError } from './EngineError-C-kBwYlN.js';
+import { a as DiagnosticReportJSON, D as DiagnosticPipeline } from './pipeline-Cl7KW8CB.js';
+import { T as Token } from './Token-D8f7yaz1.js';
+import { D as DateAmbiguity, E as EngineConfigOverride, a as EngineConfig } from './Configuration-BxriK9Kw.js';
+
+/**
+ * Choosing the calendar backend an engine computes dates with.
+ *
+ * The engine prefers Temporal. Where the runtime has it, dates are computed
+ * on `Temporal` (Chrome, Edge, Firefox and Opera ship it, and Node from 26);
+ * where it does not (Node 22 and 24, Safari, iOS), they are computed on
+ * `Date`, which is what every engine did before the backend existed.
+ *
+ * The engine bundles no polyfill. What it carries is the adapter, a few
+ * kilobytes that translate the backend's plain-number contract onto whichever
+ * implementation is present. A host that wants Temporal on a runtime without
+ * it installs a polyfill itself and passes the backend, which is what the
+ * `solve-engine/temporal` subpath is for.
+ *
+ * The two backends are held to the same answers: `scripts/test-temporal.mjs`
+ * runs the date suites under both, in three time zones, and the differential
+ * suite compares them case by case. That is what makes preferring one safe
+ * rather than a coin toss, because it means a reader on Firefox and a reader
+ * on Safari see the same number.
+ *
+ * @module resolveCalendar
+ */
+
+/**
+ * How an engine picks its calendar backend.
+ *
+ * - `"auto"`, the default: Temporal where the runtime has it, `Date` otherwise.
+ * - `"temporal"`: Temporal, refusing to build an engine on a runtime without
+ *   it rather than quietly computing on `Date`.
+ * - `"date"`: the `Date` backend, whatever the runtime has. What to pin when a
+ *   result must not depend on where it was computed.
+ * - A {@link CalendarBackend}: that backend, for a host supplying its own (a
+ *   polyfill-backed one, or a zone-bound one).
+ */
+type CalendarOption = "auto" | "temporal" | "date" | CalendarBackend;
 
 /**
  * One line's compiled bytecode, plus the variables it reads and writes.
@@ -519,6 +556,8 @@ type SerializedValue = {
 } | {
     t: ValueType.Datetime;
     v: SerializedNumber;
+    g?: DatetimeGrain;
+    z?: string;
 } | {
     t: ValueType.Percentage;
     v: SerializedNumber;
@@ -992,6 +1031,194 @@ interface UnifiedParsingOptions {
     includeDiagnostics?: boolean;
 }
 
+/**
+ * What the host's own locale says about the order the three groups of a
+ * numeric date are written in.
+ *
+ * A reader who types `03/04/2026` means one of two days, and which one is a
+ * question about where they are rather than about the characters. The engine
+ * has never had an answer to that question, so `date.inputOrder` made the host
+ * state it. This module is how a host can instead ask the machine, and it asks
+ * exactly one thing: the day/month/year field order. Never the calendar
+ * system, never the numbering system, never the display language, all of which
+ * the engine decides for itself elsewhere.
+ *
+ * Asked of `Intl` rather than answered from a table of locales. A table goes
+ * stale, and worse, it disagrees with the host's own date pickers on the same
+ * machine: `Intl` is where the operating system's answer already lives, so it
+ * is the only answer that can agree with everything else the reader sees.
+ *
+ * Pure `Intl`, importing nothing of the engine's. That is the constraint
+ * `engine/EngineContext.ts` states for this directory: `calendar/` is imported
+ * by `vm/`, which `engine/` imports, so anything here reaching back into
+ * `engine/` closes a cycle. It sits beside `IntlZone.ts`, already the shared
+ * "ask Intl about zones" module under the same rule.
+ *
+ * Nothing here is called unless a host asked for it. `date.inputOrder` still
+ * defaults to `'auto'`, and only the value `'locale'` reaches this module, so
+ * a default engine constructs no `Intl.DateTimeFormat` on this path at all.
+ *
+ * @module HostLocale
+ */
+/**
+ * The three field orders a Gregorian numeric date can be written in.
+ *
+ * Declared here rather than imported from `constants/Configuration.ts` because
+ * this module may not import from the engine's layers (see the module note),
+ * and because it is a narrower set than `DateInputOrder`: an inference can
+ * only ever produce a concrete order, never `'auto'` and never `'locale'`.
+ */
+type DateFieldOrder = "DMY" | "MDY" | "YMD";
+
+/**
+ * How this engine reads a numeric date literal, decided once and reported.
+ *
+ * `03/04/2026` names one of two days, and the engine has to pick one. Which it
+ * picks has always been settled by `date.inputOrder`, but nothing said so: the
+ * answer came back as a date with no account of how it was read, and a host
+ * had no way to show the reader "day first" or to discover that its own
+ * setting was the reason a document looked wrong.
+ *
+ * This module is the one place that decision is made, so the normaliser that
+ * fuses a literal and the surfaces that explain one cannot disagree about it.
+ * Two halves:
+ *
+ * - The engine-wide one, {@link resolveDateOrderPolicy}, run once per engine
+ *   and reported through `ExpressionEngine.getDateReading()`. It names the
+ *   order AND where the order came from.
+ * - The per-literal one, {@link classifyRun} and {@link readNumericDate},
+ *   which decide what one run of digits means under that order, and, where it
+ *   means nothing, whether saying so is better than answering the arithmetic
+ *   the run is spelled like.
+ * - The sentence, {@link composeReadingNote}, which says the same thing to a
+ *   reader. Composed here so that five hosts do not write five different
+ *   sentences about one fact, and so the note a hover shows and the message a
+ *   refusal carries cannot drift apart.
+ *
+ * @module DateReading
+ */
+
+/** Scoped error codes the datetime package owns (see `errors/ErrorCode.ts` convention). */
+declare const DatetimeErrorCodes: {
+    /**
+     * `date.inputLocale` is not a BCP-47 locale tag (`"en_US"` with an
+     * underscore is the usual mistake). Raised at engine construction, because a
+     * locale that is silently ignored is a date order that is silently wrong.
+     */
+    readonly DATE_INPUT_LOCALE_INVALID: "DATE_INPUT_LOCALE_INVALID";
+    /**
+     * A date-shaped run the resolved order cannot read, which another supported
+     * order can (`12/25/2026` on a day-first engine), or a year-last run on a
+     * year-first engine, which has no day and month roles to apply to it. The
+     * message names the order actually used, the group that broke, the reading
+     * that would work, and the two ways out. A recoverable Error VALUE, never a
+     * throw, and suppressed by `date.onAmbiguous: 'arithmetic'`.
+     */
+    readonly DATE_ORDER_MISMATCH: "DATE_ORDER_MISMATCH";
+    /**
+     * A run whose shape is unmistakably a date attempt and which names no real
+     * day under any reading: `31/04/2026`, `29/02/2026`, `13/13/2026`,
+     * `2026-02-29`, `2026-13-01`. Separate from {@link DATE_ORDER_MISMATCH}
+     * because no change of order fixes it, so the message must not suggest one.
+     */
+    readonly DATE_NOT_A_CALENDAR_DAY: "DATE_NOT_A_CALENDAR_DAY";
+};
+/** Every error code the datetime package's date-reading rules can produce. */
+type DatetimeErrorCode = (typeof DatetimeErrorCodes)[keyof typeof DatetimeErrorCodes];
+/**
+ * An order a literal can actually be read under: the three concrete field
+ * orders, plus `'auto'` for the historic per-separator reading.
+ *
+ * Narrower than `DateInputOrder` on purpose. `'locale'` is a request for an
+ * inference, not an order, and it is resolved away by
+ * {@link resolveDateOrderPolicy} before anything that reads a literal sees it,
+ * so the word cannot reach the normaliser, a worker or a snapshot.
+ */
+type ResolvedDateOrder = "auto" | DateFieldOrder;
+/**
+ * Where a resolved order came from, which is the part a reader needs and a
+ * bug report should carry.
+ *
+ * - `'config'`: the host named `'DMY'`, `'MDY'` or `'YMD'` outright. No
+ *   inference ran and `date.inputLocale` was not consulted.
+ * - `'locale'`: inferred from the tag the host gave in `date.inputLocale`.
+ * - `'host-locale'`: inferred from the tag this machine resolves to.
+ * - `'separator'`: `'auto'`, the historic reading, where a slash date is
+ *   day-first and a hyphen date month-first unless it is ISO-shaped.
+ * - `'fallback'`: an inference was asked for and could not be made, so the
+ *   engine reads dates exactly as an `'auto'` engine does. Visible on purpose:
+ *   this is the case where a host should offer the reader a manual choice.
+ */
+type DateOrderSource = "config" | "locale" | "host-locale" | "separator" | "fallback";
+/**
+ * The reading policy one engine applies to every numeric date literal in every
+ * line it evaluates.
+ *
+ * Resolved once, in the `ExpressionEngine` constructor, and then carried
+ * rather than re-derived: the normaliser rule runs on every keystroke, so an
+ * `Intl` call per literal would be a per-keystroke cost for an answer that
+ * cannot change, and a per-expression bytecode cache keyed on text would go
+ * stale against an order that could.
+ */
+interface DateReadingPolicy {
+    /** The order every ambiguous numeric literal is read under. Never `'locale'`. */
+    readonly order: ResolvedDateOrder;
+    /** Where {@link order} came from. See {@link DateOrderSource}. */
+    readonly orderSource: DateOrderSource;
+    /** The BCP-47 tag the order was inferred from, when it was inferred from one. */
+    readonly locale?: string;
+    /** What a run no order can read does: refuse it, or leave it to arithmetic. From `date.onAmbiguous`. */
+    readonly onAmbiguous: DateAmbiguity;
+}
+/**
+ * How one date literal in one line was read, with the span it occupies and a
+ * sentence a host can show.
+ *
+ * Derived, never stored. A line can hold two literals
+ * (`31/12/2026 - 01/01/2026`), which one value cannot represent, and a derived
+ * date (`03/04/2026 + 1 day`) is no longer the literal that was read, so a
+ * reading recorded on the answer would be right for the common line and
+ * quietly wrong for the rest. It costs a re-lex of the lines a reader actually
+ * asks about, and nothing at all on the rest.
+ */
+interface DateReading {
+    /** The literal exactly as typed, `"03/04/2026"`. */
+    readonly text: string;
+    /** Offset of the first character in the line, for an editor underline. */
+    readonly start: number;
+    /** Offset one past the last character. */
+    readonly end: number;
+    /** The day it was read as, `"2026-04-03"`, or null when the literal was refused. */
+    readonly iso: string | null;
+    /** The order actually applied, or null when no order could be. */
+    readonly order: DateFieldOrder | "ISO" | "spelled" | null;
+    /** Where that order came from. `'iso'` and `'spelled'` mean the literal settled itself. */
+    readonly orderSource: DateOrderSource | "iso" | "spelled";
+    /** The BCP-47 tag the order was inferred from, when it was inferred from one. */
+    readonly locale?: string;
+    /** Whether the other order also names a real day, so the reading is a genuine choice. */
+    readonly contested: boolean;
+    /** Whether a two-digit year was windowed to a century. */
+    readonly shortYear: boolean;
+    /** The ISO of the reading not taken, when {@link contested}. */
+    readonly alternative?: string;
+    /** The error code, when the literal was refused. */
+    readonly problem?: DatetimeErrorCode;
+    /**
+     * The sentence a host shows, composed here rather than assembled by each
+     * host from the parts, so five hosts do not write five different sentences
+     * about one fact.
+     */
+    readonly note: string;
+    /**
+     * Whether the note is worth showing: the reading was contested, a two-digit
+     * year was windowed, or the literal was refused. A boolean the engine
+     * computes rather than a judgement each host re-derives, which is what stops
+     * the note being either wallpaper or absent.
+     */
+    readonly needsNote: boolean;
+}
+
 /**
  * One line of a derivation: a readable account of a single operation and the
  * value it arrives at.
@@ -1484,6 +1711,8 @@ interface EngineRestoreOptions {
     config?: EngineConfigOverride;
     /** Turn on the diagnostic pipeline, as in the constructor's `diagnostics`. */
     diagnostics?: boolean;
+    /** The calendar backend for the restored engine, as in the constructor's `calendar`. */
+    calendar?: CalendarOption;
     /**
      * Override the locale the snapshot recorded. Rarely needed: the snapshot's
      * own {@link EngineSnapshot.locale} is used by default, so a restored engine
@@ -1509,6 +1738,28 @@ interface EngineOptions {
     config?: EngineConfigOverride;
     /** Turn on the diagnostic pipeline (per-stage timing and detail). Defaults to `false`. */
     diagnostics?: boolean;
+    /**
+     * The calendar the engine computes dates with: which local day an instant
+     * falls on, what a month later is, whether a day is a Saturday, how a date
+     * is written out. See {@link CalendarBackend}.
+     *
+     * Defaults to the built-in `Date` backend, read in the host process's time
+     * zone, which is what every engine computed with before this option
+     * existed; leaving it unset changes nothing. The `Temporal` backend from
+     * `solve-engine/temporal` carries a time zone of its own.
+     *
+     * Every site the engine owns reads the backend passed here: the VM's date
+     * opcodes, the plugin functions and `as` converters through their
+     * execution context, the rules that fuse a date literal, and the parser
+     * for the forms that read a literal while parsing (`days in <period>`,
+     * the stocks and historical-currency date phrases). Two sites sit outside
+     * the engine and are told separately: `formatValue` takes the backend on
+     * its `FormattingSettings.calendar`, and a worker runtime takes it on
+     * `WorkerRuntimeOptions.calendar`, because a backend is an object of
+     * functions and does not cross the message boundary. The inline offload
+     * worker computes with the `Date` backend.
+     */
+    calendar?: CalendarOption;
     /**
      * Run a few throwaway expressions through the pipeline at construction, so
      * the first real one is not the one that pays for JIT warmup.
@@ -1604,6 +1855,11 @@ declare class ExpressionEngine {
      */
     private readonly context;
     private config;
+    /**
+     * How this engine reads an ambiguous numeric date literal, resolved once
+     * from `config.date` at construction. See {@link getDateReading}.
+     */
+    private readonly dateReading;
     private diagnosticPipeline;
     /**
      * Direct reference to the timeline collector registered above (when
@@ -1949,6 +2205,61 @@ declare class ExpressionEngine {
      * in effect after merging with DEFAULT_CONFIG.
      */
     getConfig(): EngineConfig;
+    /**
+     * How this engine reads an ambiguous numeric date literal, and where that
+     * reading came from.
+     *
+     * A settings panel renders this ("Dates are read day first, from your
+     * system locale en-GB"), and a bug report should paste it: "why did
+     * `03/04/2026` render as 4 March" is answerable from one line of it and
+     * unanswerable without. `orderSource: 'fallback'` is the visible signal
+     * that an inference was asked for and could not be made, which is the
+     * difference between a decision and a guess, and the case where a host
+     * should offer the reader a manual choice.
+     *
+     * Resolved once at construction from `config.date`, so this is a read of a
+     * settled fact rather than a fresh inference, and two calls on one engine
+     * cannot disagree.
+     *
+     * @returns The frozen policy: the order, its source, and the locale tag it
+     * was inferred from where it was inferred from one.
+     */
+    getDateReading(): DateReadingPolicy;
+    /**
+     * How every date literal in a line was read, with the span each occupies.
+     *
+     * This is what an editor puts behind a hover or an underline, beside the
+     * {@link tokenizeForClassification} it already calls per keystroke. It
+     * lexes and normalises only, so no line is evaluated and no document state
+     * is touched, and it is the only surface that carries source offsets and
+     * the only one that can describe two literals on one line.
+     *
+     * The reading is recomputed rather than remembered. A line can hold two
+     * literals (`31/12/2026 - 01/01/2026`), which one answer cannot represent,
+     * and a derived date (`03/04/2026 + 1 day`) is no longer the literal that
+     * was read, so a reading recorded on the value would be right for the
+     * common line and quietly wrong for the rest. It reaches the same answer
+     * because it calls the same function the normaliser did.
+     *
+     * `needsNote` is the field to branch on: it is true exactly when the
+     * reading was a genuine choice between two real days, when a two-digit
+     * year was windowed to a century, or when the literal was refused. A host
+     * that shows `note` on every date writes wallpaper; a host that shows it
+     * on none leaves the reader to guess.
+     *
+     * @param text - The line to read. Not evaluated.
+     * @returns One record per date literal, in the order they appear.
+     */
+    readDates(text: string): DateReading[];
+    /**
+     * Turns one fused date token back into the reading that produced it.
+     *
+     * The numeric shapes go through `readNumericDate` again, so the account and
+     * the answer are the same decision rather than two that agree by
+     * inspection. Anything else (a spelled-out month, an ISO timestamp) settled
+     * itself, and is described from the instant the token already carries.
+     */
+    private describeDateLiteral;
     /**
      * Get the underlying diagnostic pipeline for advanced usage.
      */
@@ -3267,16 +3578,19 @@ interface IEnginePackage {
      * keyword registration is needed for a custom name: the AS parselet
      * accepts any bare-word token after "as" and reads its raw text.
      *
-     * Each handler is a pure, synchronous `(value: Value) => Value`, for
-     * async conversions (e.g. a live currency-style lookup), use
-     * {@link asyncResolvers} instead.
+     * Each handler is a pure, synchronous `(value: Value, context?) => Value`.
+     * The optional second argument is the same per-line execution context a
+     * plugin function receives; a converter that reads a date takes the
+     * engine's calendar backend from it (`calendarOf(context)`) so it answers
+     * as the engine's own date arithmetic would. For async conversions (e.g. a
+     * live currency-style lookup), use {@link asyncResolvers} instead.
      *
      * @example
      * ```ts
      * asConverters: { roman: (v) => stringValue(toRomanNumeral(v.toNumber())) }
      * ```
      */
-    asConverters?: Record<string, (value: Value) => Value>;
+    asConverters?: Record<string, AsConverter>;
 }
 
-export { type ApplyChangesResult as A, type BatcherMetrics as B, type CompletionItem as C, DocumentModel as D, ExpressionEngine as E, type LineCacheEntryInfo as F, type LineState as G, type LinesUpdatedEvent as H, type IEnginePackage as I, type ParsedLine as J, LanguageService as L, type ParsingResult as P, SNAPSHOT_FORMAT as S, type UnifiedParsingOptions as U, type ViewportRange as V, type EngineOptions as a, type EngineRestoreOptions as b, type EngineSnapshot as c, type Explanation as d, type ExplanationStep as e, SNAPSHOT_VERSION as f, type SerializedAnonymousBody as g, type SerializedBytecode as h, type SerializedDecimal as i, type SerializedLineCacheEntry as j, type SerializedNumber as k, type SerializedRational as l, type SerializedUserFunction as m, type SerializedValue as n, SnapshotErrorCodes as o, type LanguageServiceOptions as p, type SemanticToken as q, type LineChange as r, type InlineSolvePosition as s, type AsyncCachePackageInfo as t, type AsyncErrorEvent as u, AsyncResolutionBatcher as v, type AsyncResolutionEvent as w, type BytecodeCacheEntry as x, type CacheSnapshot as y, type CheckpointSnapshot as z };
+export { type ApplyChangesResult as A, type BatcherMetrics as B, type CompletionItem as C, type DateOrderSource as D, ExpressionEngine as E, type BytecodeCacheEntry as F, type CacheSnapshot as G, type CheckpointSnapshot as H, type IEnginePackage as I, type LineCacheEntryInfo as J, type LineState as K, LanguageService as L, type LinesUpdatedEvent as M, type ParsedLine as N, type ParsingResult as P, type ResolvedDateOrder as R, SNAPSHOT_FORMAT as S, type UnifiedParsingOptions as U, type ViewportRange as V, type EngineOptions as a, type DateReading as b, type DateReadingPolicy as c, type EngineRestoreOptions as d, type EngineSnapshot as e, type Explanation as f, type ExplanationStep as g, SNAPSHOT_VERSION as h, type SerializedAnonymousBody as i, type SerializedBytecode as j, type SerializedDecimal as k, type SerializedLineCacheEntry as l, type SerializedNumber as m, type SerializedRational as n, type SerializedUserFunction as o, type SerializedValue as p, SnapshotErrorCodes as q, type LanguageServiceOptions as r, type SemanticToken as s, DocumentModel as t, type LineChange as u, type InlineSolvePosition as v, type AsyncCachePackageInfo as w, type AsyncErrorEvent as x, AsyncResolutionBatcher as y, type AsyncResolutionEvent as z };

package/dist/{Parselet-BawfGuTF.d.cts → Parselet-DF3864la.d.cts}

@@ -1,6 +1,7 @@
 import { B as BytecodeBuilder } from './BytecodeBuilder-DSWKZi4f.cjs';
-import { T as Token } from './Token-CbP_OutD.cjs';
-import { D as DiagnosticPipeline } from './pipeline-69q2tsLE.cjs';
+import { T as Token } from './Token-D8f7yaz1.cjs';
+import { D as DiagnosticPipeline } from './pipeline-BYkKNpql.cjs';
+import { C as CalendarBackend } from './CalendarBackend-MdS3Bb4P.cjs';
 
 /**
  * Dual-keyed ParseletRegistry, accepts both string token types and
@@ -153,6 +154,15 @@ declare class PrecedenceParser {
     private readonly decimalSeparator;
     /** The locale's thousands separator, cached from {@link localeCode}. */
     private readonly thousandsSeparator;
+    /**
+     * The calendar backend of the engine this parser belongs to, for the few
+     * parselets that read a fused date literal or the current year while
+     * parsing (`days in <period>`, the stocks and historical-currency date
+     * phrases). The literal was built through the same backend by the
+     * normaliser, so reading it back here through any other could name the
+     * wrong day. The `Date` backend for a parser built outside an engine.
+     */
+    private readonly calendar;
     /**
      * The binding power the current infix parselet is being invoked at, i.e. the
      * `minBp` of the expression it sits inside. Set immediately before each Tier-2
@@ -195,9 +205,15 @@ declare class PrecedenceParser {
     private static readonly INFIX_OPCODE;
     /** Shared with every BytecodeBuilder so a nested-body builder resolves plugin calls by name. */
     private pluginFunctionIndex?;
-    constructor(parseletRegistry: ParseletRegistry, maxDepth?: number, localeCode?: string, pluginFunctionIndex?: ReadonlyMap<string, number>);
+    constructor(parseletRegistry: ParseletRegistry, maxDepth?: number, localeCode?: string, pluginFunctionIndex?: ReadonlyMap<string, number>, calendar?: CalendarBackend);
     /** Get locale code for NumberParselet to normalize separators */
     getLocaleCode(): string;
+    /**
+     * The calendar backend a parselet reads a date with at parse time: the
+     * engine's own, so a fused literal reads back through the backend that
+     * built it. See the field's doc for the sites that need it.
+     */
+    getCalendar(): CalendarBackend;
     /**
      * Set the diagnostic pipeline for parselet matching events.
      * Cleared after each non-cached parse to avoid holding refs.

package/dist/{Parselet-DqTbbtWA.d.ts → Parselet-Dgymjxzd.d.ts}

@@ -1,6 +1,7 @@
 import { B as BytecodeBuilder } from './BytecodeBuilder-DSWKZi4f.js';
-import { T as Token } from './Token-CbP_OutD.js';
-import { D as DiagnosticPipeline } from './pipeline-DTqGLPsV.js';
+import { T as Token } from './Token-D8f7yaz1.js';
+import { D as DiagnosticPipeline } from './pipeline-Cl7KW8CB.js';
+import { C as CalendarBackend } from './CalendarBackend-MdS3Bb4P.js';
 
 /**
  * Dual-keyed ParseletRegistry, accepts both string token types and
@@ -153,6 +154,15 @@ declare class PrecedenceParser {
     private readonly decimalSeparator;
     /** The locale's thousands separator, cached from {@link localeCode}. */
     private readonly thousandsSeparator;
+    /**
+     * The calendar backend of the engine this parser belongs to, for the few
+     * parselets that read a fused date literal or the current year while
+     * parsing (`days in <period>`, the stocks and historical-currency date
+     * phrases). The literal was built through the same backend by the
+     * normaliser, so reading it back here through any other could name the
+     * wrong day. The `Date` backend for a parser built outside an engine.
+     */
+    private readonly calendar;
     /**
      * The binding power the current infix parselet is being invoked at, i.e. the
      * `minBp` of the expression it sits inside. Set immediately before each Tier-2
@@ -195,9 +205,15 @@ declare class PrecedenceParser {
     private static readonly INFIX_OPCODE;
     /** Shared with every BytecodeBuilder so a nested-body builder resolves plugin calls by name. */
     private pluginFunctionIndex?;
-    constructor(parseletRegistry: ParseletRegistry, maxDepth?: number, localeCode?: string, pluginFunctionIndex?: ReadonlyMap<string, number>);
+    constructor(parseletRegistry: ParseletRegistry, maxDepth?: number, localeCode?: string, pluginFunctionIndex?: ReadonlyMap<string, number>, calendar?: CalendarBackend);
     /** Get locale code for NumberParselet to normalize separators */
     getLocaleCode(): string;
+    /**
+     * The calendar backend a parselet reads a date with at parse time: the
+     * engine's own, so a fused literal reads back through the backend that
+     * built it. See the field's doc for the sites that need it.
+     */
+    getCalendar(): CalendarBackend;
     /**
      * Set the diagnostic pipeline for parselet matching events.
      * Cleared after each non-cached parse to avoid holding refs.

package/dist/{Token-CbP_OutD.d.cts → Token-D8f7yaz1.d.cts}

@@ -33,6 +33,23 @@ interface Token {
      * the one thing the parser will see rather than as its parts.
      */
     sourceEnd?: number;
+    /**
+     * Why a fused token stands for something the engine refuses to read, when
+     * it does.
+     *
+     * Set by a normaliser rule that has decided a run is not what it is spelled
+     * like and will not be read as arithmetic either: a date literal naming no
+     * real day. The parselet for the fused type turns it into an Error value.
+     *
+     * Carried here rather than packed into `value`, because `value` is what a
+     * parse error and the editor's per-keystroke token API print, and a reader
+     * shown `{"code":"...","message":"..."}` is being shown the engine's
+     * internals. `value` stays the text the reader typed.
+     */
+    fault?: {
+        readonly code: string;
+        readonly message: string;
+    };
 }
 /**
  * Canonical token type name constants.

package/dist/{Token-CbP_OutD.d.ts → Token-D8f7yaz1.d.ts}

@@ -33,6 +33,23 @@ interface Token {
      * the one thing the parser will see rather than as its parts.
      */
     sourceEnd?: number;
+    /**
+     * Why a fused token stands for something the engine refuses to read, when
+     * it does.
+     *
+     * Set by a normaliser rule that has decided a run is not what it is spelled
+     * like and will not be read as arithmetic either: a date literal naming no
+     * real day. The parselet for the fused type turns it into an Error value.
+     *
+     * Carried here rather than packed into `value`, because `value` is what a
+     * parse error and the editor's per-keystroke token API print, and a reader
+     * shown `{"code":"...","message":"..."}` is being shown the engine's
+     * internals. `value` stays the text the reader typed.
+     */
+    fault?: {
+        readonly code: string;
+        readonly message: string;
+    };
 }
 /**
  * Canonical token type name constants.

package/dist/{TokenNormalizer-CLBtiE8M.d.ts → TokenNormalizer-IF7nPRMp.d.ts}

@@ -1,4 +1,4 @@
-import { T as Token } from './Token-CbP_OutD.js';
+import { T as Token } from './Token-D8f7yaz1.js';
 
 /**
  * NormalizerRule, pluggable token normalization rule for the

package/dist/{TokenNormalizer-CjTDmHgB.d.cts → TokenNormalizer-Pe3_390t.d.cts}

@@ -1,4 +1,4 @@
-import { T as Token } from './Token-CbP_OutD.cjs';
+import { T as Token } from './Token-D8f7yaz1.cjs';
 
 /**
  * NormalizerRule, pluggable token normalization rule for the