solve-engine 1.0.1 → 1.1.0

package/dist/{BytecodeBuilder-B0xskcv5.d.cts → BytecodeBuilder-Bp9xeTmX.d.cts}

@@ -23,6 +23,7 @@ declare enum OpCode {
     PUSH_STRING = 13,
     PUSH_BOOLEAN = 14,
     PUSH_VARIABLE = 15,
+    PUSH_DECIMAL = 16,
     ADD = 20,
     SUB = 21,
     MUL = 22,
@@ -31,6 +32,7 @@ declare enum OpCode {
     EXP = 25,
     NEG = 26,
     POS = 27,
+    MAKE_UNCERTAIN = 28,
     LSHIFT = 30,
     RSHIFT = 31,
     URSHIFT = 32,
@@ -66,6 +68,8 @@ declare enum OpCode {
     DATE_NEXT_WEEKDAY = 93,// "next <Weekday>" — the next occurrence strictly after now
     DATE_LAST_WEEKDAY = 94,// "last <Weekday>" — the previous occurrence strictly before now
     DATE_LITERAL = 95,// Push a datetime literal whose epoch-ms was already resolved at parse time (see DateLiteralParselet)
+    DATE_WORKDAY_OFFSET = 96,// "N working days after/before/from <date>" — a business-day walk from the anchor date. One operand byte: 0 forward, 1 backward. Same walk as `<date> + N workdays` (vm/VM.ts's addBusinessDays). See WorkdayOffsetParselet.
+    DATE_WORKDAYS_BETWEEN = 97,// "working days between <date> and <date>" — the count of working days in the inclusive span. See WorkdaysBetweenParselet and vm/BusinessDays.ts's countBusinessDaysBetween.
     RATE_DIV = 110,// Uom ÷ Uom (different measures) -> Rate — the construction op
     RATE_MUL = 111,// Rate × Uom (same measure as denominator) -> plain Uom (denominator cancels)
     RATE_CONVERT = 112,// Rate -> Rate with a rescaled denominator unit (keeps the same real-world rate)

package/dist/{BytecodeBuilder-B0xskcv5.d.ts → BytecodeBuilder-Bp9xeTmX.d.ts}

@@ -23,6 +23,7 @@ declare enum OpCode {
     PUSH_STRING = 13,
     PUSH_BOOLEAN = 14,
     PUSH_VARIABLE = 15,
+    PUSH_DECIMAL = 16,
     ADD = 20,
     SUB = 21,
     MUL = 22,
@@ -31,6 +32,7 @@ declare enum OpCode {
     EXP = 25,
     NEG = 26,
     POS = 27,
+    MAKE_UNCERTAIN = 28,
     LSHIFT = 30,
     RSHIFT = 31,
     URSHIFT = 32,
@@ -66,6 +68,8 @@ declare enum OpCode {
     DATE_NEXT_WEEKDAY = 93,// "next <Weekday>" — the next occurrence strictly after now
     DATE_LAST_WEEKDAY = 94,// "last <Weekday>" — the previous occurrence strictly before now
     DATE_LITERAL = 95,// Push a datetime literal whose epoch-ms was already resolved at parse time (see DateLiteralParselet)
+    DATE_WORKDAY_OFFSET = 96,// "N working days after/before/from <date>" — a business-day walk from the anchor date. One operand byte: 0 forward, 1 backward. Same walk as `<date> + N workdays` (vm/VM.ts's addBusinessDays). See WorkdayOffsetParselet.
+    DATE_WORKDAYS_BETWEEN = 97,// "working days between <date> and <date>" — the count of working days in the inclusive span. See WorkdaysBetweenParselet and vm/BusinessDays.ts's countBusinessDaysBetween.
     RATE_DIV = 110,// Uom ÷ Uom (different measures) -> Rate — the construction op
     RATE_MUL = 111,// Rate × Uom (same measure as denominator) -> plain Uom (denominator cancels)
     RATE_CONVERT = 112,// Rate -> Rate with a rescaled denominator unit (keeps the same real-world rate)

package/dist/{Configuration-B-G5gTRn.d.cts → Configuration-C9W8tJv_.d.cts}

@@ -21,6 +21,28 @@
  *
  * @module Configuration
  */
+/**
+ * A host's test for whether a calendar date is a public holiday, given the
+ * `Date` for that day at local midnight. Return `true` to exclude it from
+ * working-day arithmetic.
+ */
+type HolidayPredicate = (date: Date) => boolean;
+/**
+ * The host-supplied public-holiday calendar, in the same "bring your own data"
+ * shape the stocks and weather packages already use for a host callback (see
+ * `packages/stocks/StocksPackage.ts`): weekends are decidable from the date
+ * alone, holidays are not, so they come from the host or not at all.
+ *
+ * Either a {@link HolidayPredicate}, for a host that computes holidays itself
+ * (an existing library, a region rule), or an iterable of specific dates as
+ * `YYYY-MM-DD` strings, epoch-millisecond numbers or `Date` objects, for a host
+ * that just has a list. Resolved to one internal predicate by
+ * `vm/HolidayCalendar.ts`'s `resolveHolidayPredicate()`.
+ *
+ * Left unset, working-day arithmetic skips weekends only, which is the honest
+ * default: the engine excludes exactly the days it can prove are non-working.
+ */
+type HolidayCalendar = HolidayPredicate | Iterable<string | number | Date>;
 /**
  * Date-related configuration.
  * Controls the bounds and formatting for date/time expression evaluation
@@ -50,6 +72,21 @@ interface DateConfig {
     readonly minOffsetYears: number;
     /** Default date string format for display (moment.js format string) */
     readonly defaultFormat: string;
+    /**
+     * Public-holiday calendar for working-day arithmetic (`N working days after
+     * <date>`, `working days between <date> and <date>`, `<date> + N workdays`).
+     * See {@link HolidayCalendar}.
+     *
+     * Optional and unset by default: with no calendar, working-day arithmetic
+     * skips weekends only. A host that wants holidays excluded too supplies one
+     * here (`new ExpressionEngine("en", false, { date: { holidays } })`), the
+     * same way stocks and weather take a host data source. Threaded into the VM
+     * by `engine/ExpressionEngine.ts` exactly as {@link maxOffsetYears} is,
+     * because working-day math is a VM operation several grammar forms share, so
+     * the calendar has to be one source the VM owns rather than per-package state
+     * the VM cannot see.
+     */
+    readonly holidays?: HolidayCalendar;
 }
 /**
  * Performance-related configuration.
@@ -197,6 +234,21 @@ interface VMConfig {
      * arguments and its result whatever its body says.
      */
     readonly maxFunctionCalls: number;
+    /**
+     * Hard ceiling on how many bisection steps goal seek (`solve line N for
+     * <var> = <target>`, see `packages/goalseek/`) may take before it gives up
+     * with a structured error rather than continuing.
+     *
+     * Goal seek re-evaluates the target line's expression once per step while
+     * narrowing an interval, and an untrusted document must never be able to
+     * make that loop spin. `maxInstructions` bounds each individual
+     * re-evaluation, but not how many of them the search performs, so this is
+     * the tally that bounds the search itself, the same reason `maxFunctionCalls`
+     * exists alongside `maxInstructions`. Bisection halves the interval every
+     * step, so a hundred steps resolves an input to roughly one part in 2^100:
+     * far past any precision a document needs, and a definite stop either way.
+     */
+    readonly maxGoalSeekIterations: number;
 }
 /**
  * Complete engine configuration.
@@ -303,4 +355,4 @@ interface ValidationResult {
     warnings?: string[];
 }
 
-export { ConfigManager as C, DEFAULT_CONFIG as D, type EngineConfig as E, type PerformanceConfig as P, type VMConfig as V, type WorkerConfig as W, type DateConfig as a, type DiagnosticConfig as b, type ValidationConfig as c, type ValidationResult as d };
+export { ConfigManager as C, DEFAULT_CONFIG as D, type EngineConfig as E, type HolidayCalendar as H, type PerformanceConfig as P, type VMConfig as V, type WorkerConfig as W, type DateConfig as a, type DiagnosticConfig as b, type HolidayPredicate as c, type ValidationConfig as d, type ValidationResult as e };

package/dist/{Configuration-B-G5gTRn.d.ts → Configuration-C9W8tJv_.d.ts}

@@ -21,6 +21,28 @@
  *
  * @module Configuration
  */
+/**
+ * A host's test for whether a calendar date is a public holiday, given the
+ * `Date` for that day at local midnight. Return `true` to exclude it from
+ * working-day arithmetic.
+ */
+type HolidayPredicate = (date: Date) => boolean;
+/**
+ * The host-supplied public-holiday calendar, in the same "bring your own data"
+ * shape the stocks and weather packages already use for a host callback (see
+ * `packages/stocks/StocksPackage.ts`): weekends are decidable from the date
+ * alone, holidays are not, so they come from the host or not at all.
+ *
+ * Either a {@link HolidayPredicate}, for a host that computes holidays itself
+ * (an existing library, a region rule), or an iterable of specific dates as
+ * `YYYY-MM-DD` strings, epoch-millisecond numbers or `Date` objects, for a host
+ * that just has a list. Resolved to one internal predicate by
+ * `vm/HolidayCalendar.ts`'s `resolveHolidayPredicate()`.
+ *
+ * Left unset, working-day arithmetic skips weekends only, which is the honest
+ * default: the engine excludes exactly the days it can prove are non-working.
+ */
+type HolidayCalendar = HolidayPredicate | Iterable<string | number | Date>;
 /**
  * Date-related configuration.
  * Controls the bounds and formatting for date/time expression evaluation
@@ -50,6 +72,21 @@ interface DateConfig {
     readonly minOffsetYears: number;
     /** Default date string format for display (moment.js format string) */
     readonly defaultFormat: string;
+    /**
+     * Public-holiday calendar for working-day arithmetic (`N working days after
+     * <date>`, `working days between <date> and <date>`, `<date> + N workdays`).
+     * See {@link HolidayCalendar}.
+     *
+     * Optional and unset by default: with no calendar, working-day arithmetic
+     * skips weekends only. A host that wants holidays excluded too supplies one
+     * here (`new ExpressionEngine("en", false, { date: { holidays } })`), the
+     * same way stocks and weather take a host data source. Threaded into the VM
+     * by `engine/ExpressionEngine.ts` exactly as {@link maxOffsetYears} is,
+     * because working-day math is a VM operation several grammar forms share, so
+     * the calendar has to be one source the VM owns rather than per-package state
+     * the VM cannot see.
+     */
+    readonly holidays?: HolidayCalendar;
 }
 /**
  * Performance-related configuration.
@@ -197,6 +234,21 @@ interface VMConfig {
      * arguments and its result whatever its body says.
      */
     readonly maxFunctionCalls: number;
+    /**
+     * Hard ceiling on how many bisection steps goal seek (`solve line N for
+     * <var> = <target>`, see `packages/goalseek/`) may take before it gives up
+     * with a structured error rather than continuing.
+     *
+     * Goal seek re-evaluates the target line's expression once per step while
+     * narrowing an interval, and an untrusted document must never be able to
+     * make that loop spin. `maxInstructions` bounds each individual
+     * re-evaluation, but not how many of them the search performs, so this is
+     * the tally that bounds the search itself, the same reason `maxFunctionCalls`
+     * exists alongside `maxInstructions`. Bisection halves the interval every
+     * step, so a hundred steps resolves an input to roughly one part in 2^100:
+     * far past any precision a document needs, and a definite stop either way.
+     */
+    readonly maxGoalSeekIterations: number;
 }
 /**
  * Complete engine configuration.
@@ -303,4 +355,4 @@ interface ValidationResult {
     warnings?: string[];
 }
 
-export { ConfigManager as C, DEFAULT_CONFIG as D, type EngineConfig as E, type PerformanceConfig as P, type VMConfig as V, type WorkerConfig as W, type DateConfig as a, type DiagnosticConfig as b, type ValidationConfig as c, type ValidationResult as d };
+export { ConfigManager as C, DEFAULT_CONFIG as D, type EngineConfig as E, type HolidayCalendar as H, type PerformanceConfig as P, type VMConfig as V, type WorkerConfig as W, type DateConfig as a, type DiagnosticConfig as b, type HolidayPredicate as c, type ValidationConfig as d, type ValidationResult as e };

package/dist/{EngineError-LU7W7AgI.d.cts → EngineError-B61GS1jp.d.cts}

@@ -75,12 +75,20 @@ declare const CoreErrorCodes: {
     readonly MAP_REDUCE_ASYNC_UNSUPPORTED: "MAP_REDUCE_ASYNC_UNSUPPORTED";
     /** An algebra verb's expression argument (`BIND_UNKNOWN`'s body) calling an async plugin. Same v1 scope restriction as the two above, and likewise refused at parse time first (`SYMBOLIC_ARGUMENT_MUST_BE_SYNCHRONOUS`, packages/symbolic/). */
     readonly SYMBOLIC_ASYNC_UNSUPPORTED: "SYMBOLIC_ASYNC_UNSUPPORTED";
+    /** `explainLine()` asked to derive a line that resolves data asynchronously (a live-data or async-plugin line). A derivation is a sequence of settled intermediate values, which a pending result has none of, so the line is refused rather than explained with a hole in it. */
+    readonly EXPLAIN_ASYNC_UNSUPPORTED: "EXPLAIN_ASYNC_UNSUPPORTED";
     /** `pushCallFrame()`'s recursion guard, a nested `CALL_USER_FUNCTION` re-enters `executeBytecode()`, so `maxInstructions` alone can't catch e.g. `f(x) = f(x)`; this is the dedicated backstop. `recoverable: true` (the default for `.execution()`), ordinary user-written infinite recursion, not an engine bug; the guard exists precisely so it surfaces as a clear error instead of overflowing the native call stack uncatchably. */
     readonly FUNCTION_RECURSION_LIMIT_EXCEEDED: "FUNCTION_RECURSION_LIMIT_EXCEEDED";
     /** The companion to the code above, and the half it could never see: how MANY user-defined-function calls one evaluation makes, rather than how deeply they nest. A twenty-two-line doubling chain nests twenty-two deep (legal) and makes two million calls (a fatal heap abort). Counted in `vm/AllocationBudget.ts`, because the tally has to survive `executeBytecode()` re-entering itself. Recoverable. */
     readonly FUNCTION_CALL_LIMIT_EXCEEDED: "FUNCTION_CALL_LIMIT_EXCEEDED";
     /** A `<date> + N workdays` offset outside `date.maxOffsetYears`/`minOffsetYears`. Workdays are the one date offset that walks the calendar a day at a time, so the one whose cost is the offset; every other one moves a Date field once. Recoverable. */
     readonly DATE_OFFSET_LIMIT_EXCEEDED: "DATE_OFFSET_LIMIT_EXCEEDED";
+    /** The anchor of `N working days after/before/from <expr>` was not a date (e.g. `5 working days after 3`). The grammar guarantees the count is a number, so this only fires on the anchor. Emitted as a recoverable Error value, not thrown, matching the datetime package's other type guards. See `vm/VM.ts`'s `DATE_WORKDAY_OFFSET` case. */
+    readonly WORKDAY_OFFSET_EXPECTED_DATE: "WORKDAY_OFFSET_EXPECTED_DATE";
+    /** An endpoint of `working days between <expr> and <expr>` was not a date. Recoverable Error value. See `vm/VM.ts`'s `DATE_WORKDAYS_BETWEEN` case. */
+    readonly WORKDAYS_BETWEEN_EXPECTED_DATES: "WORKDAYS_BETWEEN_EXPECTED_DATES";
+    /** The two endpoints of `working days between <expr> and <expr>` are further apart than `date.maxOffsetYears`/`minOffsetYears` allow the count's calendar walk to run. Recoverable Error value, the between-count's equivalent of `DATE_OFFSET_LIMIT_EXCEEDED`. See `vm/VM.ts`'s `DATE_WORKDAYS_BETWEEN` case. */
+    readonly WORKDAYS_BETWEEN_RANGE_TOO_LARGE: "WORKDAYS_BETWEEN_RANGE_TOO_LARGE";
     /** A `<<`/`>>` with a bigint operand whose exact result would pass `MAX_EXACT_SHIFT_BITS`, whichever operand is the bigint. Both spellings refuse as of 1.0.0: a bigint on the left used to fall through to `x * 2^n` in doubles and report a 19,870-digit integer as Infinity. See `vm/VM.ts`'s `bigIntShift()`. Recoverable. */
     readonly BIGINT_SHIFT_LIMIT_EXCEEDED: "BIGINT_SHIFT_LIMIT_EXCEEDED";
     /** The same ceiling for `^`, the operator it was written for: `2n ^ 100000` asks for the same 100,001-bit integer `1n << 100000` does, so the two spellings answer the same way. Also new in 1.0.0, and for the same reason: this used to fall through to the double path and answer Infinity. A fractional or negative exponent (`4n ^ 0.5`, `2n ^ -1`) has no exact answer to bound and still uses the double path. See `vm/VM.ts`'s `MAX_EXACT_POW_BITS`. Recoverable. */
@@ -148,6 +156,12 @@ declare const CoreErrorCodes: {
     readonly THEREFORE_ASYNC_UNSUPPORTED: "THEREFORE_ASYNC_UNSUPPORTED";
     /** Colon-separated numbers that are not a time any clock can show ("24:00", "9:60", "100:5"). Raised by the labeled-line fallback, which used to answer them with whatever stood after the colon. */
     readonly INVALID_TIME_LITERAL: "INVALID_TIME_LITERAL";
+    /** `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. */
+    readonly SNAPSHOT_MALFORMED: "SNAPSHOT_MALFORMED";
+    /** A value the v1 snapshot format cannot yet represent (a symbolic/algebra value, a symbolic matrix cell). Deferred to a follow-up; refused by name rather than dropped silently. */
+    readonly SNAPSHOT_UNSUPPORTED_VALUE: "SNAPSHOT_UNSUPPORTED_VALUE";
     readonly CONFIG_PATH_NOT_FOUND: "CONFIG_PATH_NOT_FOUND";
     readonly INVALID_CONFIG_PATH: "INVALID_CONFIG_PATH";
     readonly CONFIG_SECTION_NOT_FOUND: "CONFIG_SECTION_NOT_FOUND";

package/dist/{EngineError-LU7W7AgI.d.ts → EngineError-B61GS1jp.d.ts}

@@ -75,12 +75,20 @@ declare const CoreErrorCodes: {
     readonly MAP_REDUCE_ASYNC_UNSUPPORTED: "MAP_REDUCE_ASYNC_UNSUPPORTED";
     /** An algebra verb's expression argument (`BIND_UNKNOWN`'s body) calling an async plugin. Same v1 scope restriction as the two above, and likewise refused at parse time first (`SYMBOLIC_ARGUMENT_MUST_BE_SYNCHRONOUS`, packages/symbolic/). */
     readonly SYMBOLIC_ASYNC_UNSUPPORTED: "SYMBOLIC_ASYNC_UNSUPPORTED";
+    /** `explainLine()` asked to derive a line that resolves data asynchronously (a live-data or async-plugin line). A derivation is a sequence of settled intermediate values, which a pending result has none of, so the line is refused rather than explained with a hole in it. */
+    readonly EXPLAIN_ASYNC_UNSUPPORTED: "EXPLAIN_ASYNC_UNSUPPORTED";
     /** `pushCallFrame()`'s recursion guard, a nested `CALL_USER_FUNCTION` re-enters `executeBytecode()`, so `maxInstructions` alone can't catch e.g. `f(x) = f(x)`; this is the dedicated backstop. `recoverable: true` (the default for `.execution()`), ordinary user-written infinite recursion, not an engine bug; the guard exists precisely so it surfaces as a clear error instead of overflowing the native call stack uncatchably. */
     readonly FUNCTION_RECURSION_LIMIT_EXCEEDED: "FUNCTION_RECURSION_LIMIT_EXCEEDED";
     /** The companion to the code above, and the half it could never see: how MANY user-defined-function calls one evaluation makes, rather than how deeply they nest. A twenty-two-line doubling chain nests twenty-two deep (legal) and makes two million calls (a fatal heap abort). Counted in `vm/AllocationBudget.ts`, because the tally has to survive `executeBytecode()` re-entering itself. Recoverable. */
     readonly FUNCTION_CALL_LIMIT_EXCEEDED: "FUNCTION_CALL_LIMIT_EXCEEDED";
     /** A `<date> + N workdays` offset outside `date.maxOffsetYears`/`minOffsetYears`. Workdays are the one date offset that walks the calendar a day at a time, so the one whose cost is the offset; every other one moves a Date field once. Recoverable. */
     readonly DATE_OFFSET_LIMIT_EXCEEDED: "DATE_OFFSET_LIMIT_EXCEEDED";
+    /** The anchor of `N working days after/before/from <expr>` was not a date (e.g. `5 working days after 3`). The grammar guarantees the count is a number, so this only fires on the anchor. Emitted as a recoverable Error value, not thrown, matching the datetime package's other type guards. See `vm/VM.ts`'s `DATE_WORKDAY_OFFSET` case. */
+    readonly WORKDAY_OFFSET_EXPECTED_DATE: "WORKDAY_OFFSET_EXPECTED_DATE";
+    /** An endpoint of `working days between <expr> and <expr>` was not a date. Recoverable Error value. See `vm/VM.ts`'s `DATE_WORKDAYS_BETWEEN` case. */
+    readonly WORKDAYS_BETWEEN_EXPECTED_DATES: "WORKDAYS_BETWEEN_EXPECTED_DATES";
+    /** The two endpoints of `working days between <expr> and <expr>` are further apart than `date.maxOffsetYears`/`minOffsetYears` allow the count's calendar walk to run. Recoverable Error value, the between-count's equivalent of `DATE_OFFSET_LIMIT_EXCEEDED`. See `vm/VM.ts`'s `DATE_WORKDAYS_BETWEEN` case. */
+    readonly WORKDAYS_BETWEEN_RANGE_TOO_LARGE: "WORKDAYS_BETWEEN_RANGE_TOO_LARGE";
     /** A `<<`/`>>` with a bigint operand whose exact result would pass `MAX_EXACT_SHIFT_BITS`, whichever operand is the bigint. Both spellings refuse as of 1.0.0: a bigint on the left used to fall through to `x * 2^n` in doubles and report a 19,870-digit integer as Infinity. See `vm/VM.ts`'s `bigIntShift()`. Recoverable. */
     readonly BIGINT_SHIFT_LIMIT_EXCEEDED: "BIGINT_SHIFT_LIMIT_EXCEEDED";
     /** The same ceiling for `^`, the operator it was written for: `2n ^ 100000` asks for the same 100,001-bit integer `1n << 100000` does, so the two spellings answer the same way. Also new in 1.0.0, and for the same reason: this used to fall through to the double path and answer Infinity. A fractional or negative exponent (`4n ^ 0.5`, `2n ^ -1`) has no exact answer to bound and still uses the double path. See `vm/VM.ts`'s `MAX_EXACT_POW_BITS`. Recoverable. */
@@ -148,6 +156,12 @@ declare const CoreErrorCodes: {
     readonly THEREFORE_ASYNC_UNSUPPORTED: "THEREFORE_ASYNC_UNSUPPORTED";
     /** Colon-separated numbers that are not a time any clock can show ("24:00", "9:60", "100:5"). Raised by the labeled-line fallback, which used to answer them with whatever stood after the colon. */
     readonly INVALID_TIME_LITERAL: "INVALID_TIME_LITERAL";
+    /** `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. */
+    readonly SNAPSHOT_MALFORMED: "SNAPSHOT_MALFORMED";
+    /** A value the v1 snapshot format cannot yet represent (a symbolic/algebra value, a symbolic matrix cell). Deferred to a follow-up; refused by name rather than dropped silently. */
+    readonly SNAPSHOT_UNSUPPORTED_VALUE: "SNAPSHOT_UNSUPPORTED_VALUE";
     readonly CONFIG_PATH_NOT_FOUND: "CONFIG_PATH_NOT_FOUND";
     readonly INVALID_CONFIG_PATH: "INVALID_CONFIG_PATH";
     readonly CONFIG_SECTION_NOT_FOUND: "CONFIG_SECTION_NOT_FOUND";

package/dist/FormattingSettings-CJHyxcYu.d.cts

@@ -0,0 +1,27 @@
+/**
+ * Minimal formatting settings interface for the engine
+ * This allows the engine to format values without depending on app-specific settings
+ */
+interface FormattingSettings {
+    floatResult: {
+        decimalPlaces: number;
+        enableSeperator: boolean;
+    };
+    numberResult: {
+        decimalSeparatorLocale: string;
+    };
+    hexResult: {
+        enablePadding: boolean;
+        paddingZeros: number;
+    };
+    unitOfMeasurementResult: {
+        decimalPlaces: number;
+    };
+    percentageResult: {
+        decimalPlaces: number;
+    };
+}
+/** Formatting used when a host supplies none. */
+declare const DEFAULT_FORMATTING_SETTINGS: FormattingSettings;
+
+export { DEFAULT_FORMATTING_SETTINGS as D, type FormattingSettings as F };

package/dist/FormattingSettings-CJHyxcYu.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Minimal formatting settings interface for the engine
+ * This allows the engine to format values without depending on app-specific settings
+ */
+interface FormattingSettings {
+    floatResult: {
+        decimalPlaces: number;
+        enableSeperator: boolean;
+    };
+    numberResult: {
+        decimalSeparatorLocale: string;
+    };
+    hexResult: {
+        enablePadding: boolean;
+        paddingZeros: number;
+    };
+    unitOfMeasurementResult: {
+        decimalPlaces: number;
+    };
+    percentageResult: {
+        decimalPlaces: number;
+    };
+}
+/** Formatting used when a host supplies none. */
+declare const DEFAULT_FORMATTING_SETTINGS: FormattingSettings;
+
+export { DEFAULT_FORMATTING_SETTINGS as D, type FormattingSettings as F };

package/dist/{Lexer-D78E2yDW.d.cts → Lexer-BOs7euZe.d.cts}

@@ -1,4 +1,4 @@
-import { T as Token } from './Token-BzG5G4ja.cjs';
+import { T as Token } from './Token-B1hdkedD.cjs';
 
 /** Trie node for multi-word phrase matching. */
 interface PhraseNode {
@@ -48,6 +48,22 @@ interface LineClassification {
     skip: boolean;
     /** Whether the line contains inline solve markers (`s`...``) */
     hasInlineSolve: boolean;
+    /**
+     * Offset of the first evaluable character, when structural markup precedes
+     * it. Absolute, in the same coordinates the classification was asked for,
+     * and absent when the whole line is evaluable.
+     *
+     * A list marker is markup, not arithmetic. `- 100 + 20` is a bullet holding
+     * `100 + 20`, but `-` is also a prefix operator, so without this the line
+     * evaluated as negative one hundred and answered -80: a wrong answer that
+     * looks like a right one. `*` and `+` in the same position could not even do
+     * that, one erroring and the other correct by luck, so the three markers
+     * disagreed with each other about the same document.
+     *
+     * Consumers must slice both the text and the token stream from here, or the
+     * two describe different lines.
+     */
+    contentOffset?: number;
 }
 /** Inline solve position with precise coordinates */
 interface InlineSolveSpan {
@@ -207,6 +223,7 @@ declare class ExpressionLexer {
     private len;
     private line;
     private lineStartPos;
+    private groupingStack;
     private keywordMap;
     private mergedKeywords;
     private mergedUnits;
@@ -356,6 +373,20 @@ declare class ExpressionLexer {
      * if the next significant character is '('.
      */
     private isFollowedByLParen;
+    /**
+     * Whether the `(` at `parenPos` opens a function call rather than a bare
+     * grouping, deciding whether a comma inside it is a separator or a thousands
+     * group (see {@link groupingStack}).
+     *
+     * It is a call when the nearest non-whitespace character before it belongs to
+     * the value the call applies to: a closing `)`/`]` (a call on a result), or an
+     * IDENTIFIER (`rgb(`, `vec2(`). A run of digits alone is a number, not an
+     * identifier, so `2(1,000)` is implicit multiplication over the grouping
+     * `(1,000)`, not a call, while `vec2(` and `atan2(` (identifiers that end in a
+     * digit) are calls. A `(` after an operator, a comma, or the line start is a
+     * grouping.
+     */
+    private precededByCallTarget;
     /**
      * Reads an operator/punctuation token.
      * Handles two-char operators (==, !=, >=, <=, **) and the special
@@ -399,6 +430,32 @@ declare class ExpressionLexer {
      * Reads directly from this.input using start/end boundaries.
      * DOES NOT modify this.pos, purely a read-only classifier.
      */
+    /**
+     * Advance past the whitespace after a list marker, and past a task-item
+     * checkbox if one follows.
+     *
+     * The checkbox is included because it is markup by the same argument the
+     * marker is, and because leaving it stopped the line dead: `- [ ] 100 + 20`
+     * lexed `[ ]` as a matrix literal and reported that a matrix cannot be
+     * empty, which tells a user writing a to-do list nothing they can act on.
+     *
+     * @param from - Offset just past the marker character.
+     * @param end - Line end, never read past.
+     * @returns Offset of the first evaluable character.
+     */
+    private skipMarkerGap;
+    /**
+     * The end offset (exclusive) of a `#hex` colour literal starting at `hashPos`,
+     * or -1 if the run there is not one. A colour is `#` followed by EXACTLY 3, 4,
+     * 6 or 8 hex digits (the CSS forms `#rgb`/`#rgba`/`#rrggbb`/`#rrggbbaa`) and
+     * then a boundary, not a longer word or number. This is the one predicate that
+     * carves colours out of the two things `#` otherwise means, a markdown heading
+     * at line start and a comment mid-line, and it is pure character logic so line
+     * classification stays vocabulary-independent. Examples: `#f00`, `#ff0000`,
+     * `#deadbeef` match; `# Heading` (space), `#tag`/`#todo` (non-hex letter),
+     * `#12345` (length 5), `#ff0000zz` (trailing word) do not.
+     */
+    private matchHexColourEnd;
     private classifyFromPositions;
     /**
      * Classify a single line of markdown text.

package/dist/{Lexer-BN5mt30n.d.ts → Lexer-CSI_lwbW.d.ts}

@@ -1,4 +1,4 @@
-import { T as Token } from './Token-BzG5G4ja.js';
+import { T as Token } from './Token-B1hdkedD.js';
 
 /** Trie node for multi-word phrase matching. */
 interface PhraseNode {
@@ -48,6 +48,22 @@ interface LineClassification {
     skip: boolean;
     /** Whether the line contains inline solve markers (`s`...``) */
     hasInlineSolve: boolean;
+    /**
+     * Offset of the first evaluable character, when structural markup precedes
+     * it. Absolute, in the same coordinates the classification was asked for,
+     * and absent when the whole line is evaluable.
+     *
+     * A list marker is markup, not arithmetic. `- 100 + 20` is a bullet holding
+     * `100 + 20`, but `-` is also a prefix operator, so without this the line
+     * evaluated as negative one hundred and answered -80: a wrong answer that
+     * looks like a right one. `*` and `+` in the same position could not even do
+     * that, one erroring and the other correct by luck, so the three markers
+     * disagreed with each other about the same document.
+     *
+     * Consumers must slice both the text and the token stream from here, or the
+     * two describe different lines.
+     */
+    contentOffset?: number;
 }
 /** Inline solve position with precise coordinates */
 interface InlineSolveSpan {
@@ -207,6 +223,7 @@ declare class ExpressionLexer {
     private len;
     private line;
     private lineStartPos;
+    private groupingStack;
     private keywordMap;
     private mergedKeywords;
     private mergedUnits;
@@ -356,6 +373,20 @@ declare class ExpressionLexer {
      * if the next significant character is '('.
      */
     private isFollowedByLParen;
+    /**
+     * Whether the `(` at `parenPos` opens a function call rather than a bare
+     * grouping, deciding whether a comma inside it is a separator or a thousands
+     * group (see {@link groupingStack}).
+     *
+     * It is a call when the nearest non-whitespace character before it belongs to
+     * the value the call applies to: a closing `)`/`]` (a call on a result), or an
+     * IDENTIFIER (`rgb(`, `vec2(`). A run of digits alone is a number, not an
+     * identifier, so `2(1,000)` is implicit multiplication over the grouping
+     * `(1,000)`, not a call, while `vec2(` and `atan2(` (identifiers that end in a
+     * digit) are calls. A `(` after an operator, a comma, or the line start is a
+     * grouping.
+     */
+    private precededByCallTarget;
     /**
      * Reads an operator/punctuation token.
      * Handles two-char operators (==, !=, >=, <=, **) and the special
@@ -399,6 +430,32 @@ declare class ExpressionLexer {
      * Reads directly from this.input using start/end boundaries.
      * DOES NOT modify this.pos, purely a read-only classifier.
      */
+    /**
+     * Advance past the whitespace after a list marker, and past a task-item
+     * checkbox if one follows.
+     *
+     * The checkbox is included because it is markup by the same argument the
+     * marker is, and because leaving it stopped the line dead: `- [ ] 100 + 20`
+     * lexed `[ ]` as a matrix literal and reported that a matrix cannot be
+     * empty, which tells a user writing a to-do list nothing they can act on.
+     *
+     * @param from - Offset just past the marker character.
+     * @param end - Line end, never read past.
+     * @returns Offset of the first evaluable character.
+     */
+    private skipMarkerGap;
+    /**
+     * The end offset (exclusive) of a `#hex` colour literal starting at `hashPos`,
+     * or -1 if the run there is not one. A colour is `#` followed by EXACTLY 3, 4,
+     * 6 or 8 hex digits (the CSS forms `#rgb`/`#rgba`/`#rrggbb`/`#rrggbbaa`) and
+     * then a boundary, not a longer word or number. This is the one predicate that
+     * carves colours out of the two things `#` otherwise means, a markdown heading
+     * at line start and a comment mid-line, and it is pure character logic so line
+     * classification stays vocabulary-independent. Examples: `#f00`, `#ff0000`,
+     * `#deadbeef` match; `# Heading` (space), `#tag`/`#todo` (non-hex letter),
+     * `#12345` (length 5), `#ff0000zz` (trailing word) do not.
+     */
+    private matchHexColourEnd;
     private classifyFromPositions;
     /**
      * Classify a single line of markdown text.

package/dist/PackageCompatibility-B-7rK1TD.d.cts

@@ -0,0 +1,76 @@
+import { I as IEnginePackage } from './PackageRegistry-BHWJP83F.cjs';
+
+/**
+ * Package load-time compatibility checking, the "detect overlapping
+ * logic between packages" SDK surface.
+ *
+ * This engine's package system (`IEnginePackage`) has always had SOME
+ * collision visibility, but it's inconsistent and scattered: `ParseletRegistry`
+ * warns on a token-type overwrite, `asConverterRegistry` warns on a converter
+ * name overwrite, and `PhraseTrie` warns on... nothing at all, a second
+ * package fusing the exact same multi-word phrase to a different token type
+ * silently wins with zero signal, the same class of gap
+ * `ParseletRegistry.registerPrefix()`'s collision-visibility fix closed for
+ * parselets specifically (see `ARCHITECTURE.md`'s punch list). And none of
+ * these existing checks can be run BEFORE registration, they only fire at
+ * the moment a collision actually happens, deep inside a live engine.
+ *
+ * `checkPackageCompatibility()` is a single, pure, side-effect-free function
+ * that statically compares one candidate package's declared descriptor
+ * against a list of already-registered packages' descriptors, across every
+ * collision-capable field `IEnginePackage` has, callable standalone (a host
+ * building a plugin marketplace could run it before ever constructing an
+ * engine) or wired into registration itself (see
+ * `ExpressionEngine.registerPackage()`, which calls this automatically and
+ * logs every conflict found, the "load-up resiliency" half of this
+ * mechanism).
+ *
+ * A real, concrete motivating bug (found the same session this module was
+ * built): the currency package's real `IEnginePackage` descriptor
+ * (`CurrencyPackage.ts`) and its parallel test-harness registration helper
+ * (`parselets/index.ts`'s `registerCurrencyParselets()`) drifted out of sync
+ *, new currency-symbol token types were wired into one but not the other
+ * caught only by a test happening to exercise the stale path. This module
+ * doesn't catch THAT specific class of bug (two hand-written registration
+ * functions for the same logical package diverging is a source-consistency
+ * problem, not a runtime collision), but it DOES catch the more common and
+ * more dangerous sibling: two DIFFERENT, independently-authored packages
+ * unknowingly claiming the same token type, phrase, converter name, plugin
+ * function index, or lexer keyword.
+ */
+/** How serious a detected conflict is. */
+type CompatibilitySeverity = "error" | "warning" | "info";
+/** The category of overlap detected between two packages. */
+type CompatibilityConflictKind = "prefixParseletTokenType" | "infixParseletTokenType" | "phrase" | "converterName" | "pluginFunctionIndex" | "lexerKeyword" | "lexerOperator" | "asyncResolverNamespace" | "tokenCategory";
+/** One way two packages collide, for example claiming the same keyword. */
+interface CompatibilityConflict {
+    kind: CompatibilityConflictKind;
+    severity: CompatibilitySeverity;
+    /** Human-readable description, safe to log directly. */
+    detail: string;
+    /** The two package names involved, [existing, candidate]. */
+    packages: [string, string];
+}
+/** Every conflict found between a candidate package and those already registered. */
+interface CompatibilityReport {
+    /** `false` iff at least one "error"-severity conflict was found. */
+    compatible: boolean;
+    conflicts: CompatibilityConflict[];
+}
+/**
+ * Statically check `candidate` against every package in `existing` for
+ * overlapping/conflicting declarations, across every collision-capable
+ * field `IEnginePackage` has. Pure and side-effect-free, does not touch
+ * any shared registry, does not require a live `ExpressionEngine`.
+ *
+ * @example
+ * ```ts
+ * const report = checkPackageCompatibility(myNewPackage, BUILTIN_PACKAGES);
+ * if (!report.compatible) {
+ *   for (const c of report.conflicts) console.error(c.detail);
+ * }
+ * ```
+ */
+declare function checkPackageCompatibility(candidate: IEnginePackage, existing: IEnginePackage[]): CompatibilityReport;
+
+export { type CompatibilityReport as C, type CompatibilityConflict as a, type CompatibilityConflictKind as b, type CompatibilitySeverity as c, checkPackageCompatibility as d };