solve-engine 2.24.0 → 2.26.0

package/dist/{TokenNormalizer-OTPS0Otq.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
@@ -320,14 +320,16 @@ interface NormalizerOptions {
      */
     onFusion?: (fusion: TokenFusion) => void;
     /**
-     * Try every registered rule at every position, ignoring the shape index.
+     * Try every registered rule at every position, ignoring both the shape
+     * index and the first-token buckets the first call uses.
      *
-     * Diagnostic only, and much slower. It exists so the indexed walk can be
-     * compared against the unindexed one over a corpus: the index is a pure
-     * filter, so the two must agree token for token, and a rule whose declared
+     * Diagnostic only, and much slower. It exists so the filtered walks can be
+     * compared against the exhaustive one over a corpus: each filter is pure,
+     * so all of them must agree token for token, and a rule whose declared
      * {@link NormalizerRule.shape} is too narrow shows up as a difference rather
      * than as a feature that quietly stopped working.
-     * `NormalizerIndexFidelity.spec` is the consumer.
+     * `NormalizerIndexFidelity.spec` and `RuleHintsMatchGuards.spec` are the
+     * consumers.
      *
      * @default false
      */
@@ -393,13 +395,12 @@ declare class TokenNormalizer {
      */
     private sortedRulesCache;
     /**
-     * Per-token-type view of the priority-sorted rules: for a token type, the
-     * rules that could match a token of that type (those with no
-     * {@link NormalizerRule.startTokenTypes} hint, plus those that list the type),
-     * in the same priority order {@link getSortedRules} produces. Built lazily on
-     * the first token of each type and cached, so a document of many number and
-     * operator tokens never re-tries the many rules that only fire on an
-     * identifier. Invalidated alongside {@link sortedRulesCache}.
+     * Per-token-type view of the priority-sorted rules, for the one
+     * {@link normalize} call that runs before the index exists: for a token
+     * type, the rules whose first declared slot admits it (or constrains no
+     * type at all), in the same priority order {@link getSortedRules} produces.
+     * See {@link rulesForTokenType}. Built once per distinct type and cached,
+     * invalidated alongside {@link sortedRulesCache}.
      */
     private rulesByTokenType;
     /**
@@ -421,7 +422,10 @@ declare class TokenNormalizer {
      * what evaluating a single expression on a fresh engine does, would never
      * reach the payback. Skipping the build on the first call keeps that case at
      * the cost it had before the index existed, and a document reaches line two
-     * immediately.
+     * immediately. The first call is not unfiltered, though: it reads the same
+     * first-slot types the index would, through {@link rulesForTokenType}, so a
+     * single expression still skips every rule that could not start at its
+     * tokens.
      */
     private normalizeCalls;
     /**
@@ -467,12 +471,8 @@ declare class TokenNormalizer {
      */
     private getSortedRules;
     /**
-     * The priority-sorted rules to try at a token of `type`: every rule with no
-     * {@link NormalizerRule.startTokenTypes} hint, plus those that list this type.
-     * A rule that declares a different trigger would have returned null here
-     * anyway, so omitting it is behaviour-preserving. Built once per distinct type
-     * and cached, which is what turns the per-position rule scan from "try all R
-     * rules" into "try only the ones that could fire on this token".
+     * The shape index over the priority-sorted rules, built on first use after
+     * a mutation and cached. See {@link RuleIndex}.
      */
     private getRuleIndex;
     /**
@@ -492,16 +492,35 @@ declare class TokenNormalizer {
      * wins on both counts. Worst case is 32 iterations per word of pure integer
      * work.
      *
-     * With `null` (the {@link NormalizerOptions.ignoreRuleIndex} path) it falls
-     * back to the type-bucketed list, which is the behaviour this replaced.
+     * With `null` there is no index to consult, for one of two reasons: this is
+     * the first call, which reads the first-token bucket from
+     * {@link rulesForTokenType}, or {@link NormalizerOptions.ignoreRuleIndex} is
+     * set, which is the exhaustive scan every filter is measured against. Both
+     * hand back a cached list directly, since the caller only reads it.
      *
-     * Returns a buffer reused across positions, so the caller must finish with it
-     * before calling again. Copying the surviving rules out here rather than
-     * yielding them lazily is deliberate twice over: it keeps the mask's own
-     * scratch buffer from being read after the next position overwrites it, and
-     * it avoids a generator on the hottest loop in the pass.
+     * With a mask, returns a buffer reused across positions, so the caller must
+     * finish with it before calling again. Copying the surviving rules out here
+     * rather than yielding them lazily is deliberate twice over: it keeps the
+     * mask's own scratch buffer from being read after the next position
+     * overwrites it, and it avoids a generator on the hottest loop in the pass.
      */
     private rulesAt;
+    /**
+     * The priority-sorted rules that could start at a token of `type`, for the
+     * first {@link normalize} call, which runs before the index is built.
+     *
+     * The filter is the first slot of each rule's {@link effectiveShape}: a rule
+     * naming types there is bucketed under exactly those, and one naming none is
+     * in every bucket. That is the same declaration the index reads at its first
+     * plane, only without the value axis, so a rule the bucket omits is one the
+     * index would omit too, and one that would have returned null here anyway.
+     * An earlier version read only the older `startTokenTypes` hint, which most
+     * rules had by then replaced with a `shape`, so the first call tried nearly
+     * every rule at every position and a fresh engine evaluating one expression
+     * paid several times the rule calls of the second line of a document.
+     *
+     * Built once per distinct type and cached until the rule set changes.
+     */
     private rulesForTokenType;
     /**
      * Get the number of currently registered rules (excludes phrase trie entries).

package/dist/{TokenNormalizer-MXaKLJ_m.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
@@ -320,14 +320,16 @@ interface NormalizerOptions {
      */
     onFusion?: (fusion: TokenFusion) => void;
     /**
-     * Try every registered rule at every position, ignoring the shape index.
+     * Try every registered rule at every position, ignoring both the shape
+     * index and the first-token buckets the first call uses.
      *
-     * Diagnostic only, and much slower. It exists so the indexed walk can be
-     * compared against the unindexed one over a corpus: the index is a pure
-     * filter, so the two must agree token for token, and a rule whose declared
+     * Diagnostic only, and much slower. It exists so the filtered walks can be
+     * compared against the exhaustive one over a corpus: each filter is pure,
+     * so all of them must agree token for token, and a rule whose declared
      * {@link NormalizerRule.shape} is too narrow shows up as a difference rather
      * than as a feature that quietly stopped working.
-     * `NormalizerIndexFidelity.spec` is the consumer.
+     * `NormalizerIndexFidelity.spec` and `RuleHintsMatchGuards.spec` are the
+     * consumers.
      *
      * @default false
      */
@@ -393,13 +395,12 @@ declare class TokenNormalizer {
      */
     private sortedRulesCache;
     /**
-     * Per-token-type view of the priority-sorted rules: for a token type, the
-     * rules that could match a token of that type (those with no
-     * {@link NormalizerRule.startTokenTypes} hint, plus those that list the type),
-     * in the same priority order {@link getSortedRules} produces. Built lazily on
-     * the first token of each type and cached, so a document of many number and
-     * operator tokens never re-tries the many rules that only fire on an
-     * identifier. Invalidated alongside {@link sortedRulesCache}.
+     * Per-token-type view of the priority-sorted rules, for the one
+     * {@link normalize} call that runs before the index exists: for a token
+     * type, the rules whose first declared slot admits it (or constrains no
+     * type at all), in the same priority order {@link getSortedRules} produces.
+     * See {@link rulesForTokenType}. Built once per distinct type and cached,
+     * invalidated alongside {@link sortedRulesCache}.
      */
     private rulesByTokenType;
     /**
@@ -421,7 +422,10 @@ declare class TokenNormalizer {
      * what evaluating a single expression on a fresh engine does, would never
      * reach the payback. Skipping the build on the first call keeps that case at
      * the cost it had before the index existed, and a document reaches line two
-     * immediately.
+     * immediately. The first call is not unfiltered, though: it reads the same
+     * first-slot types the index would, through {@link rulesForTokenType}, so a
+     * single expression still skips every rule that could not start at its
+     * tokens.
      */
     private normalizeCalls;
     /**
@@ -467,12 +471,8 @@ declare class TokenNormalizer {
      */
     private getSortedRules;
     /**
-     * The priority-sorted rules to try at a token of `type`: every rule with no
-     * {@link NormalizerRule.startTokenTypes} hint, plus those that list this type.
-     * A rule that declares a different trigger would have returned null here
-     * anyway, so omitting it is behaviour-preserving. Built once per distinct type
-     * and cached, which is what turns the per-position rule scan from "try all R
-     * rules" into "try only the ones that could fire on this token".
+     * The shape index over the priority-sorted rules, built on first use after
+     * a mutation and cached. See {@link RuleIndex}.
      */
     private getRuleIndex;
     /**
@@ -492,16 +492,35 @@ declare class TokenNormalizer {
      * wins on both counts. Worst case is 32 iterations per word of pure integer
      * work.
      *
-     * With `null` (the {@link NormalizerOptions.ignoreRuleIndex} path) it falls
-     * back to the type-bucketed list, which is the behaviour this replaced.
+     * With `null` there is no index to consult, for one of two reasons: this is
+     * the first call, which reads the first-token bucket from
+     * {@link rulesForTokenType}, or {@link NormalizerOptions.ignoreRuleIndex} is
+     * set, which is the exhaustive scan every filter is measured against. Both
+     * hand back a cached list directly, since the caller only reads it.
      *
-     * Returns a buffer reused across positions, so the caller must finish with it
-     * before calling again. Copying the surviving rules out here rather than
-     * yielding them lazily is deliberate twice over: it keeps the mask's own
-     * scratch buffer from being read after the next position overwrites it, and
-     * it avoids a generator on the hottest loop in the pass.
+     * With a mask, returns a buffer reused across positions, so the caller must
+     * finish with it before calling again. Copying the surviving rules out here
+     * rather than yielding them lazily is deliberate twice over: it keeps the
+     * mask's own scratch buffer from being read after the next position
+     * overwrites it, and it avoids a generator on the hottest loop in the pass.
      */
     private rulesAt;
+    /**
+     * The priority-sorted rules that could start at a token of `type`, for the
+     * first {@link normalize} call, which runs before the index is built.
+     *
+     * The filter is the first slot of each rule's {@link effectiveShape}: a rule
+     * naming types there is bucketed under exactly those, and one naming none is
+     * in every bucket. That is the same declaration the index reads at its first
+     * plane, only without the value axis, so a rule the bucket omits is one the
+     * index would omit too, and one that would have returned null here anyway.
+     * An earlier version read only the older `startTokenTypes` hint, which most
+     * rules had by then replaced with a `shape`, so the first call tried nearly
+     * every rule at every position and a fresh engine evaluating one expression
+     * paid several times the rule calls of the second line of a document.
+     *
+     * Built once per distinct type and cached until the rule set changes.
+     */
     private rulesForTokenType;
     /**
      * Get the number of currently registered rules (excludes phrase trie entries).

package/dist/{ScopeManager-BQBhlDAu.d.ts → VMBuiltins-CZiZRKn-.d.ts}

@@ -1,7 +1,8 @@
-import { V as Value } from './Value-Ds3Gy07C.js';
-import { U as UserFunctionDef, A as AnonymousBodyDef, a as BytecodeProgram } from './BytecodeBuilder-aqVa7Plx.js';
-import { E as EngineError } from './EngineError-D1kXsjIj.js';
-import { D as DiagnosticPipeline } from './pipeline-DTqGLPsV.js';
+import { V as Value } from './Value-BYHw-x7q.js';
+import { U as UserFunctionDef, A as AnonymousBodyDef, a as BytecodeProgram } from './BytecodeBuilder-DSWKZi4f.js';
+import { C as CalendarBackend } from './CalendarBackend-MdS3Bb4P.js';
+import { E as EngineError } from './EngineError-C-kBwYlN.js';
+import { D as DiagnosticPipeline } from './pipeline-Cl7KW8CB.js';
 
 /**
  * Create a new VM instance with the given opcode registry and configurable limits.
@@ -83,6 +84,14 @@ interface LineExecutionContext {
      * message that describes a different fault. Absent means enabled.
      */
     networkEnabled?: boolean;
+    /**
+     * The calendar backend this engine computes dates with (`EngineContext.calendar`).
+     * A plugin function that reads or steps a date computes through it, so the
+     * date it answers agrees with the one the VM's own opcodes would produce.
+     * Absent means the `Date` backend; `calendarOf()` in
+     * `calendar/DateCalendar.ts` resolves either case.
+     */
+    calendar?: CalendarBackend;
     /** Look up another line's cached result by 1-based line number. `undefined` = not evaluated yet (or out of range), distinct from a line that evaluated to an actual `undefined`-like Value, which can't happen (every Value type has a concrete representation). */
     getLineResult?: (lineNumber: number) => Value | undefined;
     /** Whether line `lineNumber` is a blank line or a `#` heading, the stopping condition for "total above"/"sum above"/"average above" aggregation. */
@@ -190,11 +199,13 @@ declare function executeBytecode(bytecode: Bytecode, vm: VM, pipeline?: Diagnost
  * by that engine. Anything that needs one of these registries receives the
  * context rather than importing a singleton.
  *
- * Runtime imports here are restricted to leaf modules of `vm/`. This file is
- * imported by `vm/`, which `engine/` imports in turn, so pulling in anything
- * that reaches back into `engine/` would close a cycle. `OpRegistry` is safe
- * because it imports only types plus the error factory. Everything else arrives
- * through `import type`, which is erased before the code runs.
+ * Runtime imports here are restricted to leaf modules of `vm/` and
+ * `calendar/`. This file is imported by `vm/`, which `engine/` imports in
+ * turn, so pulling in anything that reaches back into `engine/` would close a
+ * cycle. `OpRegistry` is safe because it imports only types plus the error
+ * factory, and the `Date` calendar backend imports nothing of the engine's at
+ * all. Everything else arrives through `import type`, which is erased before
+ * the code runs.
  */
 
 /**
@@ -268,6 +279,18 @@ interface EngineContext {
      * the context is the one object every VM already holds.
      */
     readonly networkEnabled: boolean;
+    /**
+     * The calendar this engine computes dates with, from the engine's
+     * `calendar` option.
+     *
+     * One backend per engine, held here for the same reason the network
+     * switch is: the VM is where a date literal is stepped, a working-day
+     * walk runs and `now` is read, and every plugin function that touches a
+     * date reaches it through the execution context the VM builds from this
+     * one object. Defaults to Temporal where the runtime has it and `Date`
+     * where it does not. See `calendar/resolveCalendar.ts`.
+     */
+    readonly calendar: CalendarBackend;
 }
 
 /**
@@ -705,4 +728,63 @@ declare class ScopeManager {
     clear(): void;
 }
 
-export { type Bytecode as B, DependencyGraph as D, type ExpressionRecord as E, OpRegistry as O, type PluginFunctionHandler as P, ScopeManager as S, type VM as V, type DagSnapshot as a, type EngineContext as b, createVM as c, executeBytecode as e, sharedOpRegistry as s };
+/**
+ * Registry of built-in mathematical functions.
+ * Indexed by the number pushed as an operand of OpCode.CALL_BUILTIN.
+ */
+declare const builtinFunctions: Record<number, (args: Value[]) => Value>;
+/**
+ * Registry of package-registered functions, indexed by the number pushed as an
+ * operand of `OpCode.CALL_PLUGIN`.
+ *
+ * Functions may return a promise. The orchestrator resolves it and re-executes
+ * rather than blocking the VM.
+ *
+ * Populated declaratively via {@link IEnginePackage.pluginFunctions} at
+ * package-registration time. Entries are cleared on unregister.
+ *
+ * @deprecated This is the {@link defaultEngineContext}'s map, kept as a
+ * module-level alias so existing callers keep working during the context
+ * migration. An engine registers into its own context, so writing here affects
+ * only code that has not been migrated. Take an {@link EngineContext} instead.
+ */
+declare const pluginFunctionRegistry: Record<number, PluginFunctionHandler>;
+/**
+ * Allocate a unique index into {@link pluginFunctionRegistry} for a package's
+ * plugin function.
+ *
+ * Call once per function, typically at module scope, right where the
+ * function is defined, and store the result in a constant. Don't hardcode
+ * an index: two packages independently picking the same arbitrary number
+ * would silently overwrite each other's handler in the shared registry.
+ *
+ * @throws If the index pool is exhausted (up to 65536: two opcode-stream bytes
+ *         via CALL_PLUGIN_WIDE, the first 256 via the one-byte CALL_PLUGIN).
+ */
+declare function allocatePluginFunctionIndex(): number;
+/**
+ * The stable index for a package's named plugin function, allocated once per
+ * `${packageName}:${functionName}` and cached process-wide, so the same function
+ * always maps to the same {@link pluginFunctionRegistry} slot no matter which
+ * engine registers it or in what order: the property compiled bytecode, and so
+ * a snapshot, relies on.
+ *
+ * The engine calls this at {@link ExpressionEngine.registerPackage} time for each
+ * entry of a package's `pluginFunctions` record, so a package author names the
+ * function and never sees an index. {@link allocatePluginFunctionIndex} remains
+ * for a host that needs a raw index directly.
+ */
+declare function pluginFunctionIndexFor(qualifiedName: string): number;
+/**
+ * A package-registered `as <name>` converter: the value on the left of `as`
+ * in, the converted value out.
+ *
+ * The optional `context` is the per-line execution context the VM passes to
+ * a plugin function, handed to a converter for the same reason: a converter
+ * that reads a date computes through the engine's calendar backend on it
+ * rather than a module-level default, so `<date> as weekday` and `weekday on
+ * <date>` cannot disagree. A converter that needs nothing from it ignores it.
+ */
+type AsConverter = (value: Value, context?: LineExecutionContext) => Value;
+
+export { type AsConverter as A, type Bytecode as B, DependencyGraph as D, type ExpressionRecord as E, type LineExecutionContext as L, OpRegistry as O, type PluginFunctionHandler as P, ScopeManager as S, type VM as V, allocatePluginFunctionIndex as a, builtinFunctions as b, createVM as c, pluginFunctionRegistry as d, executeBytecode as e, type DagSnapshot as f, type EngineContext as g, pluginFunctionIndexFor as p, sharedOpRegistry as s };

package/dist/{ScopeManager-DrXB3Nvm.d.cts → VMBuiltins-kv4rr0y5.d.cts}

@@ -1,7 +1,8 @@
-import { V as Value } from './Value-Ds3Gy07C.cjs';
-import { U as UserFunctionDef, A as AnonymousBodyDef, a as BytecodeProgram } from './BytecodeBuilder-aqVa7Plx.cjs';
-import { E as EngineError } from './EngineError-D1kXsjIj.cjs';
-import { D as DiagnosticPipeline } from './pipeline-69q2tsLE.cjs';
+import { V as Value } from './Value-BYHw-x7q.cjs';
+import { U as UserFunctionDef, A as AnonymousBodyDef, a as BytecodeProgram } from './BytecodeBuilder-DSWKZi4f.cjs';
+import { C as CalendarBackend } from './CalendarBackend-MdS3Bb4P.cjs';
+import { E as EngineError } from './EngineError-C-kBwYlN.cjs';
+import { D as DiagnosticPipeline } from './pipeline-BYkKNpql.cjs';
 
 /**
  * Create a new VM instance with the given opcode registry and configurable limits.
@@ -83,6 +84,14 @@ interface LineExecutionContext {
      * message that describes a different fault. Absent means enabled.
      */
     networkEnabled?: boolean;
+    /**
+     * The calendar backend this engine computes dates with (`EngineContext.calendar`).
+     * A plugin function that reads or steps a date computes through it, so the
+     * date it answers agrees with the one the VM's own opcodes would produce.
+     * Absent means the `Date` backend; `calendarOf()` in
+     * `calendar/DateCalendar.ts` resolves either case.
+     */
+    calendar?: CalendarBackend;
     /** Look up another line's cached result by 1-based line number. `undefined` = not evaluated yet (or out of range), distinct from a line that evaluated to an actual `undefined`-like Value, which can't happen (every Value type has a concrete representation). */
     getLineResult?: (lineNumber: number) => Value | undefined;
     /** Whether line `lineNumber` is a blank line or a `#` heading, the stopping condition for "total above"/"sum above"/"average above" aggregation. */
@@ -190,11 +199,13 @@ declare function executeBytecode(bytecode: Bytecode, vm: VM, pipeline?: Diagnost
  * by that engine. Anything that needs one of these registries receives the
  * context rather than importing a singleton.
  *
- * Runtime imports here are restricted to leaf modules of `vm/`. This file is
- * imported by `vm/`, which `engine/` imports in turn, so pulling in anything
- * that reaches back into `engine/` would close a cycle. `OpRegistry` is safe
- * because it imports only types plus the error factory. Everything else arrives
- * through `import type`, which is erased before the code runs.
+ * Runtime imports here are restricted to leaf modules of `vm/` and
+ * `calendar/`. This file is imported by `vm/`, which `engine/` imports in
+ * turn, so pulling in anything that reaches back into `engine/` would close a
+ * cycle. `OpRegistry` is safe because it imports only types plus the error
+ * factory, and the `Date` calendar backend imports nothing of the engine's at
+ * all. Everything else arrives through `import type`, which is erased before
+ * the code runs.
  */
 
 /**
@@ -268,6 +279,18 @@ interface EngineContext {
      * the context is the one object every VM already holds.
      */
     readonly networkEnabled: boolean;
+    /**
+     * The calendar this engine computes dates with, from the engine's
+     * `calendar` option.
+     *
+     * One backend per engine, held here for the same reason the network
+     * switch is: the VM is where a date literal is stepped, a working-day
+     * walk runs and `now` is read, and every plugin function that touches a
+     * date reaches it through the execution context the VM builds from this
+     * one object. Defaults to Temporal where the runtime has it and `Date`
+     * where it does not. See `calendar/resolveCalendar.ts`.
+     */
+    readonly calendar: CalendarBackend;
 }
 
 /**
@@ -705,4 +728,63 @@ declare class ScopeManager {
     clear(): void;
 }
 
-export { type Bytecode as B, DependencyGraph as D, type ExpressionRecord as E, OpRegistry as O, type PluginFunctionHandler as P, ScopeManager as S, type VM as V, type DagSnapshot as a, type EngineContext as b, createVM as c, executeBytecode as e, sharedOpRegistry as s };
+/**
+ * Registry of built-in mathematical functions.
+ * Indexed by the number pushed as an operand of OpCode.CALL_BUILTIN.
+ */
+declare const builtinFunctions: Record<number, (args: Value[]) => Value>;
+/**
+ * Registry of package-registered functions, indexed by the number pushed as an
+ * operand of `OpCode.CALL_PLUGIN`.
+ *
+ * Functions may return a promise. The orchestrator resolves it and re-executes
+ * rather than blocking the VM.
+ *
+ * Populated declaratively via {@link IEnginePackage.pluginFunctions} at
+ * package-registration time. Entries are cleared on unregister.
+ *
+ * @deprecated This is the {@link defaultEngineContext}'s map, kept as a
+ * module-level alias so existing callers keep working during the context
+ * migration. An engine registers into its own context, so writing here affects
+ * only code that has not been migrated. Take an {@link EngineContext} instead.
+ */
+declare const pluginFunctionRegistry: Record<number, PluginFunctionHandler>;
+/**
+ * Allocate a unique index into {@link pluginFunctionRegistry} for a package's
+ * plugin function.
+ *
+ * Call once per function, typically at module scope, right where the
+ * function is defined, and store the result in a constant. Don't hardcode
+ * an index: two packages independently picking the same arbitrary number
+ * would silently overwrite each other's handler in the shared registry.
+ *
+ * @throws If the index pool is exhausted (up to 65536: two opcode-stream bytes
+ *         via CALL_PLUGIN_WIDE, the first 256 via the one-byte CALL_PLUGIN).
+ */
+declare function allocatePluginFunctionIndex(): number;
+/**
+ * The stable index for a package's named plugin function, allocated once per
+ * `${packageName}:${functionName}` and cached process-wide, so the same function
+ * always maps to the same {@link pluginFunctionRegistry} slot no matter which
+ * engine registers it or in what order: the property compiled bytecode, and so
+ * a snapshot, relies on.
+ *
+ * The engine calls this at {@link ExpressionEngine.registerPackage} time for each
+ * entry of a package's `pluginFunctions` record, so a package author names the
+ * function and never sees an index. {@link allocatePluginFunctionIndex} remains
+ * for a host that needs a raw index directly.
+ */
+declare function pluginFunctionIndexFor(qualifiedName: string): number;
+/**
+ * A package-registered `as <name>` converter: the value on the left of `as`
+ * in, the converted value out.
+ *
+ * The optional `context` is the per-line execution context the VM passes to
+ * a plugin function, handed to a converter for the same reason: a converter
+ * that reads a date computes through the engine's calendar backend on it
+ * rather than a module-level default, so `<date> as weekday` and `weekday on
+ * <date>` cannot disagree. A converter that needs nothing from it ignores it.
+ */
+type AsConverter = (value: Value, context?: LineExecutionContext) => Value;
+
+export { type AsConverter as A, type Bytecode as B, DependencyGraph as D, type ExpressionRecord as E, type LineExecutionContext as L, OpRegistry as O, type PluginFunctionHandler as P, ScopeManager as S, type VM as V, allocatePluginFunctionIndex as a, builtinFunctions as b, createVM as c, pluginFunctionRegistry as d, executeBytecode as e, type DagSnapshot as f, type EngineContext as g, pluginFunctionIndexFor as p, sharedOpRegistry as s };

package/dist/{VMCheckpoints-C5jC92o3.d.ts → VMCheckpoints-DXze6ypg.d.ts}

@@ -1,6 +1,6 @@
-import { V as Value } from './Value-Ds3Gy07C.js';
-import { V as VM } from './ScopeManager-BQBhlDAu.js';
-import { U as UserFunctionDef } from './BytecodeBuilder-aqVa7Plx.js';
+import { V as Value } from './Value-BYHw-x7q.js';
+import { V as VM } from './VMBuiltins-CZiZRKn-.js';
+import { U as UserFunctionDef } from './BytecodeBuilder-DSWKZi4f.js';
 
 /**
  * A point-in-time snapshot of VM variable state.

package/dist/{VMCheckpoints-BK32PTl2.d.cts → VMCheckpoints-yun4ocSv.d.cts}

@@ -1,6 +1,6 @@
-import { V as Value } from './Value-Ds3Gy07C.cjs';
-import { V as VM } from './ScopeManager-DrXB3Nvm.cjs';
-import { U as UserFunctionDef } from './BytecodeBuilder-aqVa7Plx.cjs';
+import { V as Value } from './Value-BYHw-x7q.cjs';
+import { V as VM } from './VMBuiltins-kv4rr0y5.cjs';
+import { U as UserFunctionDef } from './BytecodeBuilder-DSWKZi4f.cjs';
 
 /**
  * A point-in-time snapshot of VM variable state.

package/dist/{Value-Ds3Gy07C.d.cts → Value-BYHw-x7q.d.cts}

@@ -250,6 +250,23 @@ interface SplitData {
  * switches on `kind` keeps working for the ones it already knows.
  */
 type ChartKind = "sparkline" | "plot";
+/**
+ * What a `Datetime`'s epoch-millisecond payload anchors.
+ *
+ * Three questions share one number and mean different things by it, which is
+ * why the distinction is recorded rather than inferred:
+ *
+ * - `date`: a calendar day, held as its local midnight (`2026-04-03`,
+ *   `3 April 2026`, `03/04/2026`). The time of day carries no meaning.
+ * - `datetime`: a wall-clock reading on a day, in the calendar backend's own
+ *   zone (`2026-04-03T09:30`, `6pm`). The reading is what was named; the
+ *   instant follows from the zone it is read in.
+ * - `instant`: a fixed point on the timeline, named without depending on a
+ *   zone (`2026-04-03T10:30:00Z`, `...+09:00`, `now`).
+ *
+ * See {@link Value.grain} for why the number cannot answer this on its own.
+ */
+type DatetimeGrain = "date" | "datetime" | "instant";
 /**
  * A chart specification: the DATA to draw, never pixels. One shape holds every
  * visual the engine produces, `[1,2,3] as sparkline` and `plot sin(x) from 0 to
@@ -407,6 +424,45 @@ declare class Value {
      * by {@link recycle} alongside the other sidecars.
      */
     decimalPlaces?: number;
+    /**
+     * What this instant anchors: a calendar day, a wall-clock reading on one, or
+     * a fixed point on the timeline.
+     *
+     * The fifth sidecar, the same shape as {@link exact}, {@link rational},
+     * {@link uncertainty} and {@link decimalPlaces} and for the same reason: a
+     * `Datetime`'s payload is epoch milliseconds and has to stay a plain number,
+     * because the arena union, the worker DTO, the snapshot's Datetime variant
+     * and the `Datetime` SUB path all read it as one. The number cannot say
+     * which of three questions it is the answer to, and the difference is not
+     * recoverable from it: `formatDatetime` decides whether to print a time by
+     * testing whether the local hour, minute, second and millisecond are all
+     * zero, which is a guess that `2026-04-03T09:00:00+09:00` under `TZ=UTC`
+     * gets wrong, because the nine o'clock the reader typed IS UTC midnight.
+     *
+     * Set only where the shape is known: a date literal is `'date'`, a
+     * wall-clock literal (`2026-04-03T09:30`, `6pm`) is `'datetime'`, a literal
+     * carrying `Z` or an offset is `'instant'`, and so is `now`. Absent means
+     * not recorded, which every reader treats as an instant rather than
+     * inferring one. Nothing in 2.26.0 displays it: the formatter does not read
+     * it, so every rendered date is byte-identical to 2.25.0. Cleared by
+     * {@link recycle} alongside the other sidecars.
+     */
+    grain?: DatetimeGrain;
+    /**
+     * The zone this instant should be read and displayed in, when the line
+     * named one.
+     *
+     * A zone reference in the encoding `calendar/IntlZone.ts` documents: an IANA
+     * name (`"Asia/Tokyo"`) or a fixed offset (`"UTCOFFSET:540"`). Set by
+     * `<datetime> in <zone>` and by an ISO literal carrying `Z` or an explicit
+     * offset, which names an offset rather than a zone and so records one.
+     * Absent means the value is read in the calendar backend's own zone, which
+     * is what every `Datetime` meant before this sidecar existed. Like
+     * {@link grain} it is recorded and readable in 2.26.0 and read by the
+     * formatter from 3.0. Cleared by {@link recycle} alongside the other
+     * sidecars.
+     */
+    zone?: string;
     constructor(type: ValueType, value: number | bigint | string | boolean | MatrixData | RangeData | ColourData | SplitData | ChartData | IpCidrData | SymbolicNode, unit?: string);
     /**
      * Phase 5.3: Reset all fields for arena reuse.
@@ -533,4 +589,4 @@ declare function colVectorValue(data: readonly number[]): Value;
 /** Create a Range value, a first-class integer range `min:max`, both bounds inclusive. */
 declare function rangeValue(min: number, max: number): Value;
 
-export { type ColourData as C, type IpCidrData as I, type MatrixData as M, type RangeData as R, type SplitData as S, Value as V, ValueType as a, type MatrixEntry as b, bigIntValue as c, colVectorValue as d, rowVectorValue as e, type ChartData as f, type SymbolicNode as g, hexValue as h, type ColourFormat as i, matrixValue as m, numberValue as n, rangeValue as r, stringValue as s, uomValue as u };
+export { type ColourData as C, type DatetimeGrain as D, type IpCidrData as I, type MatrixData as M, type RangeData as R, type SplitData as S, Value as V, type MatrixEntry as a, ValueType as b, bigIntValue as c, colVectorValue as d, rowVectorValue as e, type ChartData as f, type SymbolicNode as g, hexValue as h, type ColourFormat as i, matrixValue as m, numberValue as n, rangeValue as r, stringValue as s, uomValue as u };