solve-engine 1.0.0-beta.0 → 1.0.0-beta.2

package/dist/EngineError-DvPSnhZi.d.cts

@@ -0,0 +1,304 @@
+/**
+ * The built-in error-code catalog, one typed const object per domain
+ * unioned together here for autocomplete/exhaustiveness in core engine
+ * code. Deliberately NOT one central enum: `IEnginePackage` is documented
+ * public SDK surface for third-party packages (see `api/PackageRegistry.ts`),
+ * and a closed enum would block an external package author from defining
+ * their own codes without editing this file. `EngineError.code`'s runtime
+ * type stays `string` for exactly that reason. This catalog is for the
+ * codes THIS repo owns and wants collision/typo checking on (see
+ * `__tests__/errors/ErrorCodeCatalog.spec.ts`), not a hard runtime
+ * whitelist.
+ *
+ * As each package migrates to `Result<void, EngineError>` (see this
+ * session's error-handling-refactor plan, Phase 5), it should export its
+ * own small `XxxErrorCodes` const object co-located with its parselets
+ * exactly like `CoreErrorCodes` below, just scoped to one domain, and get
+ * unioned into `ErrorCode` here. Until a package migrates, its existing
+ * free-string codes keep working (ErrorFactory accepts any string); they
+ * just aren't caught by the catalog's uniqueness/orphan checks yet.
+ */
+/**
+ * Codes used directly by the parser/VM/engine/errors layers themselves
+ * confirmed against the current source, not aspirational. Grouped by
+ * pipeline stage via the comments, not a naming prefix (these predate any
+ * naming convention and renaming them is out of scope for introducing the
+ * catalog, only NEW codes need to follow a scoped/prefixed style, see
+ * `STACK_UNDERFLOW` etc. below).
+ */
+declare const CoreErrorCodes: {
+    readonly INVALID_NUMBER_LITERAL: "INVALID_NUMBER_LITERAL";
+    readonly NO_PREFIX_PARSELET: "NO_PREFIX_PARSELET";
+    readonly UNEXPECTED_END_OF_INPUT: "UNEXPECTED_END_OF_INPUT";
+    readonly UNEXPECTED_TOKEN_TYPE: "UNEXPECTED_TOKEN_TYPE";
+    readonly NESTING_DEPTH_EXCEEDED: "NESTING_DEPTH_EXCEEDED";
+    readonly UNEXPECTED_END: "UNEXPECTED_END";
+    readonly UNEXPECTED_TRAILING_TOKEN: "UNEXPECTED_TRAILING_TOKEN";
+    readonly PARSE_ERROR: "PARSE_ERROR";
+    readonly TOO_MANY_NUMERIC_CONSTANTS: "TOO_MANY_NUMERIC_CONSTANTS";
+    readonly TOO_MANY_STRING_CONSTANTS: "TOO_MANY_STRING_CONSTANTS";
+    readonly NO_MATCHING_PHRASE_ALTERNATIVE: "NO_MATCHING_PHRASE_ALTERNATIVE";
+    readonly INVALID_PHRASE_PATTERN: "INVALID_PHRASE_PATTERN";
+    readonly PHRASE_KEYWORD_MISMATCH: "PHRASE_KEYWORD_MISMATCH";
+    /** User-defined-function definition parsing (`f(x, y) = ...`), an invalid token where a parameter name was expected. */
+    readonly USER_FUNCTION_INVALID_PARAM_NAME: "USER_FUNCTION_INVALID_PARAM_NAME";
+    /** `f() = ...` with zero parameters, indistinguishable from a plain no-arg function call, so rejected at definition time. */
+    readonly USER_FUNCTION_NO_PARAMS: "USER_FUNCTION_NO_PARAMS";
+    /** A user-defined function body calling an async plugin (weather/stocks/currency/...), rejected at definition time; v1 scope excludes async function bodies. */
+    readonly FUNCTION_BODY_MUST_BE_SYNCHRONOUS: "FUNCTION_BODY_MUST_BE_SYNCHRONOUS";
+    /** `BytecodeBuilder`'s `userFunctionBodies` side-table exceeding its capacity. Same class as `TOO_MANY_NUMERIC_CONSTANTS`/`TOO_MANY_STRING_CONSTANTS` below. */
+    readonly TOO_MANY_FUNCTION_DEFINITIONS: "TOO_MANY_FUNCTION_DEFINITIONS";
+    /** `BytecodeBuilder`'s `anonymousBodies` side-table (map/reduce inline transform bodies) exceeding its capacity. Same class as `TOO_MANY_FUNCTION_DEFINITIONS` above. */
+    readonly TOO_MANY_ANONYMOUS_BODIES: "TOO_MANY_ANONYMOUS_BODIES";
+    readonly EVALUATION_ERROR: "EVALUATION_ERROR";
+    readonly INSTRUCTION_LIMIT_EXCEEDED: "INSTRUCTION_LIMIT_EXCEEDED";
+    readonly STACK_LIMIT_EXCEEDED: "STACK_LIMIT_EXCEEDED";
+    /** New this phase. See `VM.ts`'s `safePop()`: a stack-underflow (corrupted bytecode, a buggy plugin) is now a controlled EngineError instead of a raw TypeError. Always `recoverable: false` (internal invariant violation). */
+    readonly STACK_UNDERFLOW: "STACK_UNDERFLOW";
+    readonly UNDEFINED_VARIABLE: "UNDEFINED_VARIABLE";
+    /** New this phase, the Tier-2/`LOAD_GLOBAL_VAR` hardening: a global variable read before its async preflight resolved, surfaced as a controlled error instead of pushing `undefined`. */
+    readonly GLOBAL_VARIABLE_NOT_RESOLVED: "GLOBAL_VARIABLE_NOT_RESOLVED";
+    readonly UNKNOWN_FUNCTION: "UNKNOWN_FUNCTION";
+    /** `unwrapEvalResult()`'s pending-when-expecting-value case, a caller-contract violation, not user-input. */
+    readonly UNEXPECTED_PENDING_RESULT: "UNEXPECTED_PENDING_RESULT";
+    /** User-defined-function call/definition errors (`CALL_USER_FUNCTION`/`DEFINE_USER_FUNCTION` opcodes), calling a name with no matching definition, calling with the wrong argument count, and the deliberate v1 restriction that a function body can't itself contain async work. */
+    readonly UNDEFINED_FUNCTION: "UNDEFINED_FUNCTION";
+    readonly FUNCTION_ARITY_MISMATCH: "FUNCTION_ARITY_MISMATCH";
+    readonly USER_FUNCTION_ASYNC_UNSUPPORTED: "USER_FUNCTION_ASYNC_UNSUPPORTED";
+    /** A map/reduce transform body (inline expression or user-defined function) calling an async plugin. Same v1 scope restriction as `USER_FUNCTION_ASYNC_UNSUPPORTED` above, enforced both at parse time (`MAP_REDUCE_TRANSFORM_MUST_BE_SYNCHRONOUS`, packages/mapreduce/) and as a defense-in-depth runtime backstop here. */
+    readonly MAP_REDUCE_ASYNC_UNSUPPORTED: "MAP_REDUCE_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";
+    /** `DEFINE_USER_FUNCTION`'s body-index lookup failing, a compiler/VM invariant violation (the opcode stream referenced a `userFunctionBodies` slot that doesn't exist), never a user-input error. */
+    readonly INTERNAL_MISSING_FUNCTION_BODY: "INTERNAL_MISSING_FUNCTION_BODY";
+    /** `MAP_INVOKE`/`REDUCE_INVOKE`'s anonymous-body-index lookup failing. Same class as `INTERNAL_MISSING_FUNCTION_BODY` above, for the `anonymousBodies` side-table instead of `userFunctionBodies`. */
+    readonly INTERNAL_MISSING_ANONYMOUS_BODY: "INTERNAL_MISSING_ANONYMOUS_BODY";
+    /** A coefficient grew past `RATIONAL_MAX_BITS`, e.g. repeated exact elimination multiplying denominators together. */
+    readonly SYMBOLIC_RATIONAL_OVERFLOW: "SYMBOLIC_RATIONAL_OVERFLOW";
+    /** `NaN` or `±Infinity` reaching a symbolic expression, neither of which has an exact rational value. */
+    readonly SYMBOLIC_NONFINITE_OPERAND: "SYMBOLIC_NONFINITE_OPERAND";
+    /** Division by an exactly-zero rational. Exact, unlike the double comparison it replaced, which could not distinguish a true zero from `5.551e-17`. */
+    readonly SYMBOLIC_DIVISION_BY_ZERO: "SYMBOLIC_DIVISION_BY_ZERO";
+    /** A tree exceeding `SYMBOLIC_MAX_NODES` entering the simplifier. */
+    readonly SYMBOLIC_NODE_LIMIT_EXCEEDED: "SYMBOLIC_NODE_LIMIT_EXCEEDED";
+    /** A builtin with no symbolic reading (`min`, `random`, the finance block, ...) applied to an expression still containing an unknown. Returned rather than computing against `toNumber()`'s placeholder zero. */
+    readonly SYMBOLIC_UNSUPPORTED_FUNCTION: "SYMBOLIC_UNSUPPORTED_FUNCTION";
+    /** The rational-root search exceeding `FACTOR_MAX_ROOT_CANDIDATES`. The candidate set is the product of two divisor sets, so a highly-composite coefficient escapes quickly. */
+    readonly SYMBOLIC_FACTOR_LIMIT_EXCEEDED: "SYMBOLIC_FACTOR_LIMIT_EXCEEDED";
+    /** An equation outside what the solver attempts: not a polynomial, above the degree ceiling, or non-linear in the unknown while another unknown is present. */
+    readonly SYMBOLIC_SOLVE_UNSUPPORTED: "SYMBOLIC_SOLVE_UNSUPPORTED";
+    /** `solve`'s second argument not being a bare name. */
+    readonly SOLVE_REQUIRES_VARIABLE_NAME: "SOLVE_REQUIRES_VARIABLE_NAME";
+    /** A derivative order outside 0..`DERIVATIVE_MAX_ORDER`. */
+    readonly SYMBOLIC_DERIVATIVE_ORDER_LIMIT: "SYMBOLIC_DERIVATIVE_ORDER_LIMIT";
+    /** An expression with no known elementary antiderivative. Reported rather than approximated, since a wrong integral is indistinguishable from a right one at the point of use. */
+    readonly SYMBOLIC_INTEGRAL_UNSUPPORTED: "SYMBOLIC_INTEGRAL_UNSUPPORTED";
+    /** A Taylor degree outside 0..`TAYLOR_MAX_DEGREE`. */
+    readonly SYMBOLIC_TAYLOR_DEGREE_LIMIT: "SYMBOLIC_TAYLOR_DEGREE_LIMIT";
+    /** A Taylor coefficient that does not reduce to an exact number at the expansion point. */
+    readonly SYMBOLIC_TAYLOR_INEXACT: "SYMBOLIC_TAYLOR_INEXACT";
+    /** An algebra verb's variable-name argument not being a bare name. */
+    readonly SYMBOLIC_REQUIRES_VARIABLE_NAME: "SYMBOLIC_REQUIRES_VARIABLE_NAME";
+    /** `jacobian` called with expressions containing no unknown to differentiate against. */
+    readonly SYMBOLIC_JACOBIAN_NO_VARIABLES: "SYMBOLIC_JACOBIAN_NO_VARIABLES";
+    /** A finite number whose decimal form could not be read back, which the regex covering every `Number.prototype.toString` output should make unreachable. */
+    readonly INTERNAL_RATIONAL_PARSE: "INTERNAL_RATIONAL_PARSE";
+    readonly EXPRESSION_TOO_LONG: "EXPRESSION_TOO_LONG";
+    readonly EXPRESSION_TOO_COMPLEX: "EXPRESSION_TOO_COMPLEX";
+    readonly NORMALIZED_TOKEN_LIMIT_EXCEEDED: "NORMALIZED_TOKEN_LIMIT_EXCEEDED";
+    /** `"=>"` with nothing before it, needs an expression or variable name to solve/simplify. */
+    readonly THEREFORE_REQUIRES_EXPRESSION: "THEREFORE_REQUIRES_EXPRESSION";
+    /** A `"=>"`-triggered expression called an async plugin (weather/stocks/currency). Same v1 scope restriction as user-function/map-reduce bodies. */
+    readonly THEREFORE_ASYNC_UNSUPPORTED: "THEREFORE_ASYNC_UNSUPPORTED";
+    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";
+    readonly CONFIG_PROPERTY_NOT_FOUND: "CONFIG_PROPERTY_NOT_FOUND";
+    readonly PLUGIN_OPERATOR_COLLISION: "PLUGIN_OPERATOR_COLLISION";
+    readonly PLUGIN_KEYWORD_COLLISION: "PLUGIN_KEYWORD_COLLISION";
+    readonly PLUGIN_UNIT_COLLISION: "PLUGIN_UNIT_COLLISION";
+    /** A package's declared `IEnginePackage.engineVersion` semver range doesn't satisfy the running engine's ENGINE_VERSION. See api/EngineVersionCompatibility.ts. */
+    readonly PACKAGE_ENGINE_VERSION_MISMATCH: "PACKAGE_ENGINE_VERSION_MISMATCH";
+    /** A package's declared `IEnginePackage.engineVersion` isn't a parseable semver range at all (a typo in the package's own descriptor). */
+    readonly PACKAGE_ENGINE_VERSION_INVALID_RANGE: "PACKAGE_ENGINE_VERSION_INVALID_RANGE";
+    /** `OpRegistry.allocateOpcode()`'s dynamic opcode pool (started at 201) exhausted, too many packages calling it. */
+    readonly OPCODE_POOL_EXHAUSTED: "OPCODE_POOL_EXHAUSTED";
+    /** `VMBuiltins.allocatePluginFunctionIndex()`'s 0-255 index pool (a single opcode-stream byte) exhausted. */
+    readonly PLUGIN_FUNCTION_INDEX_POOL_EXHAUSTED: "PLUGIN_FUNCTION_INDEX_POOL_EXHAUSTED";
+    readonly INVALID_RATE_UNIT: "INVALID_RATE_UNIT";
+    readonly INVALID_TIMECODE_UNIT: "INVALID_TIMECODE_UNIT";
+    readonly UNEXPECTED_ERROR: "UNEXPECTED_ERROR";
+    readonly UNKNOWN_ERROR: "UNKNOWN_ERROR";
+};
+/** Every error code the engine's own layers can produce, from {@link CoreErrorCodes}. */
+type CoreErrorCode = (typeof CoreErrorCodes)[keyof typeof CoreErrorCodes];
+/**
+ * The aggregated catalog type. Currently just `CoreErrorCode`, union in
+ * each package's own code-object type here as Phase 5 converts it, e.g.
+ * `CoreErrorCode | WeatherErrorCode | StocksErrorCode | ...`.
+ */
+type ErrorCode = CoreErrorCode;
+
+/**
+ * The engine's structured error type, the "Rust/Go-style, verbose, easy to
+ * tell the issue" half of the error-handling redesign (the other half is
+ * `Result.ts`).
+ *
+ * Historical note: an earlier version of this class (`UnifiedErrorFramework.ts`,
+ * still the import path most of the codebase uses. See that file, now a
+ * pure re-export barrel) had a much larger field set (`severity`,
+ * `recovery`, a 5-value enum, `ErrorRecoveryManager`) that was almost
+ * entirely dead: nothing downstream ever read `.severity`/`.recovery`,
+ * only `.message` reliably survived to a caller. This version is smaller
+ * and deliberately keeps only fields something actually consumes.
+ */
+
+/** A character-offset (and optional line/col) span into the original expression text, for a future "underline the offending token" UI, not yet wired to one. */
+interface SourceSpan {
+    start: number;
+    end: number;
+    line?: number;
+    col?: number;
+}
+/**
+ * Error classification, kept from the original framework, now actually
+ * consulted: it's the `format()` header and lets host code group errors
+ * by pipeline stage without string-matching `.code`.
+ */
+declare enum ErrorCategory {
+    /** Errors during expression parsing. */
+    PARSING = "PARSING",
+    /** Errors during bytecode execution. */
+    EXECUTION = "EXECUTION",
+    /** Errors from input validation (safety limits, config). */
+    VALIDATION = "VALIDATION",
+    /** Errors from external services/APIs (currency rates, weather, stocks). */
+    EXTERNAL = "EXTERNAL",
+    /** Internal engine invariant violations. See `recoverable`'s doc comment. */
+    INTERNAL = "INTERNAL",
+    /** Configuration errors. */
+    CONFIG = "CONFIG"
+}
+/** Fields accepted when constructing an {@link EngineError}. */
+interface EngineErrorInit {
+    /** Catalog code. See `errors/ErrorCode.ts`. Not a free string: every code used by a BUILT-IN package should be registered there so `ErrorCodeCatalog.spec.ts` can catch collisions/typos. Third-party packages may still use any string here, `EngineError.code`'s runtime type is `string`. */
+    code: ErrorCode | (string & {});
+    /** Short, single-line, `Error.message`-compatible. Existing `.toThrow(/pattern/)`/`.message` assertions keep working against this field, richer detail goes in `expected`/`found`/`suggestion`, not crammed into this string. */
+    message: string;
+    /** What the parser/validator/VM expected to see, in plain words, e.g. "a city name", "a 4-digit year", "end of expression". */
+    expected?: string;
+    /** What was actually found instead, e.g. "end of expression", `NUMBER "5"`, the offending token's literal text. */
+    found?: string;
+    /** An actionable, worked-example fix, e.g. `e.g. "weather in London"`. Mirrors this codebase's best existing messages (`WEATHER_EXPECTED_CITY`, `AS_CONVERTER_EXPECTED_NAME`). */
+    suggestion?: string;
+    /**
+     * `true` (the default) for every EXPECTED failure mode of user input or
+     * environment, bad syntax, an unknown variable/function, a safety limit
+     * exceeded, an external API being down. `false` is reserved for genuine
+     * ENGINE-INTERNAL invariant violations (corrupted bytecode, a stack
+     * underflow from a buggy plugin, an "impossible" state)
+     * `ErrorFactory.internal()`/`.config()` default to `false`, every other
+     * factory method defaults to `true`.
+     *
+     * This does NOT gate "does evaluation of the rest of the document
+     * continue", with this engine's per-line containment, it always does
+     * even for a `recoverable: false` error (see `ARCHITECTURE.md`'s
+     * async-batcher/Tier-2 hardening notes). It gates MESSAGE FRAMING and
+     * telemetry: "fix your syntax" vs. "this is an engine bug, worth
+     * reporting". See `EngineError.isFatal()`.
+     */
+    recoverable?: boolean;
+    /** Character-offset span into the source expression, when available. Not yet threaded through every call site, populate opportunistically, don't block on retrofitting every existing throw site. */
+    span?: SourceSpan;
+    /** Free-form structured context. The one field the pre-existing framework's real consumer (`ThreeTierEvaluator.ts`'s DAG-preservation-on-compile-error path) actually reads, kept name- and shape-compatible on purpose. */
+    context?: Record<string, unknown>;
+    /** The underlying error this one wraps, if any, passed straight through to native `Error.cause` (ES2022), so Node's default printer, most loggers, and `instanceof Error` tooling understand the chain for free. */
+    cause?: unknown;
+}
+/**
+ * The engine's structured error type. Still a real `Error` subclass (so
+ * `throw`/`catch`/`instanceof Error` all keep working exactly as before),
+ * but now every field except the removed `severity`/`recovery` pair is
+ * something real code reads.
+ */
+declare class EngineError extends Error {
+    readonly category: ErrorCategory;
+    readonly code: string;
+    readonly expected?: string;
+    readonly found?: string;
+    readonly suggestion?: string;
+    readonly recoverable: boolean;
+    readonly span?: SourceSpan;
+    readonly context?: Record<string, unknown>;
+    readonly timestamp: Date;
+    /**
+     * Set explicitly (not via `super(message, {cause})`). This repo's
+     * `tsconfig.json` targets ES6/ES5-ES7 lib, which predates TypeScript's
+     * ES2022 `Error` constructor `cause`-option overload. `Error.prototype.cause`
+     * is still a real runtime feature in every target this engine actually
+     * runs in (Node 16.9+, all evergreen browsers, Electron/Obsidian's
+     * bundled Chromium) regardless of the TS lib target used to type-check
+     * against it, assigning it directly gets the same Node-printer/logger
+     * interop with no build-config change needed.
+     */
+    readonly cause?: unknown;
+    constructor(category: ErrorCategory, init: EngineErrorInit);
+    /** `!recoverable`. See `EngineErrorInit.recoverable`'s doc comment for what this actually gates (message framing/telemetry, not whether evaluation continues). */
+    isFatal(): boolean;
+    /** Walk `.cause` repeatedly, collecting the full chain (this error first). */
+    causeChain(): unknown[];
+    /**
+     * Rust/Go-style multi-line renderer, the NEW thing a host/CLI/test
+     * reaches for when it wants the full, verbose picture, as distinct from
+     * `.message` (kept short and stable for existing assertions). Example:
+     *
+     * ```
+     * error[WEATHER_EXPECTED_CITY]: Expected a city name after "weather in"
+     *   expected: a city name
+     *   found: end of expression
+     *   suggestion: e.g. "weather in London"
+     * ```
+     */
+    format(): string;
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Factory for creating classified `EngineError`s. Every method accepts
+ * EITHER the original, minimal 3-arg shape (`code, message, context?`
+ * every existing call site across the codebase keeps compiling unchanged)
+ * OR the richer `EngineErrorInit` object (for `expected`/`found`/
+ * `suggestion`/`recoverable`/`span`/`cause`), upgrade a call site to the
+ * richer form only when you're already touching it, no separate churn
+ * pass required.
+ */
+declare class ErrorFactory {
+    private static build;
+    static validation(code: string, message: string, context?: Record<string, unknown>): EngineError;
+    static validation(init: EngineErrorInit): EngineError;
+    static parsing(code: string, message: string, context?: Record<string, unknown>): EngineError;
+    static parsing(init: EngineErrorInit): EngineError;
+    static execution(code: string, message: string, context?: Record<string, unknown>): EngineError;
+    static execution(init: EngineErrorInit): EngineError;
+    static external(code: string, message: string, context?: Record<string, unknown>): EngineError;
+    static external(init: EngineErrorInit): EngineError;
+    /** Defaults `recoverable: false`, reserve for genuine engine-internal invariant violations, not user-input errors. */
+    static internal(code: string, message: string, context?: Record<string, unknown>): EngineError;
+    static internal(init: EngineErrorInit): EngineError;
+    /** Defaults `recoverable: false`, a bad config is an environment-setup problem, not a per-line user-input error. */
+    static config(code: string, message: string, context?: Record<string, unknown>): EngineError;
+    static config(init: EngineErrorInit): EngineError;
+}
+/**
+ * Normalize any thrown value into an `EngineError`, an `EngineError`
+ * passes through as-is; a plain `Error` gets wrapped (message preserved,
+ * original attached via `cause`); anything else becomes a generic
+ * "unknown error" wrapping the stringified value. Used at every
+ * throw-space/Result-space boundary (`Result.tryCatch`'s default
+ * `normalize`, the VM's outer execution try/catch, `AsyncResolutionBatcher`'s
+ * per-line containment) so a raw `TypeError` from a genuine engine bug
+ * still surfaces as a structured, catalogued error instead of an opaque
+ * uncaught exception.
+ */
+declare function normalizeUnknownError(error: unknown): EngineError;
+
+export { type CoreErrorCode as C, EngineError as E, type SourceSpan as S, CoreErrorCodes as a, type EngineErrorInit as b, ErrorCategory as c, type ErrorCode as d, ErrorFactory as e, normalizeUnknownError as n };

package/dist/EngineError-DvPSnhZi.d.ts

@@ -0,0 +1,304 @@
+/**
+ * The built-in error-code catalog, one typed const object per domain
+ * unioned together here for autocomplete/exhaustiveness in core engine
+ * code. Deliberately NOT one central enum: `IEnginePackage` is documented
+ * public SDK surface for third-party packages (see `api/PackageRegistry.ts`),
+ * and a closed enum would block an external package author from defining
+ * their own codes without editing this file. `EngineError.code`'s runtime
+ * type stays `string` for exactly that reason. This catalog is for the
+ * codes THIS repo owns and wants collision/typo checking on (see
+ * `__tests__/errors/ErrorCodeCatalog.spec.ts`), not a hard runtime
+ * whitelist.
+ *
+ * As each package migrates to `Result<void, EngineError>` (see this
+ * session's error-handling-refactor plan, Phase 5), it should export its
+ * own small `XxxErrorCodes` const object co-located with its parselets
+ * exactly like `CoreErrorCodes` below, just scoped to one domain, and get
+ * unioned into `ErrorCode` here. Until a package migrates, its existing
+ * free-string codes keep working (ErrorFactory accepts any string); they
+ * just aren't caught by the catalog's uniqueness/orphan checks yet.
+ */
+/**
+ * Codes used directly by the parser/VM/engine/errors layers themselves
+ * confirmed against the current source, not aspirational. Grouped by
+ * pipeline stage via the comments, not a naming prefix (these predate any
+ * naming convention and renaming them is out of scope for introducing the
+ * catalog, only NEW codes need to follow a scoped/prefixed style, see
+ * `STACK_UNDERFLOW` etc. below).
+ */
+declare const CoreErrorCodes: {
+    readonly INVALID_NUMBER_LITERAL: "INVALID_NUMBER_LITERAL";
+    readonly NO_PREFIX_PARSELET: "NO_PREFIX_PARSELET";
+    readonly UNEXPECTED_END_OF_INPUT: "UNEXPECTED_END_OF_INPUT";
+    readonly UNEXPECTED_TOKEN_TYPE: "UNEXPECTED_TOKEN_TYPE";
+    readonly NESTING_DEPTH_EXCEEDED: "NESTING_DEPTH_EXCEEDED";
+    readonly UNEXPECTED_END: "UNEXPECTED_END";
+    readonly UNEXPECTED_TRAILING_TOKEN: "UNEXPECTED_TRAILING_TOKEN";
+    readonly PARSE_ERROR: "PARSE_ERROR";
+    readonly TOO_MANY_NUMERIC_CONSTANTS: "TOO_MANY_NUMERIC_CONSTANTS";
+    readonly TOO_MANY_STRING_CONSTANTS: "TOO_MANY_STRING_CONSTANTS";
+    readonly NO_MATCHING_PHRASE_ALTERNATIVE: "NO_MATCHING_PHRASE_ALTERNATIVE";
+    readonly INVALID_PHRASE_PATTERN: "INVALID_PHRASE_PATTERN";
+    readonly PHRASE_KEYWORD_MISMATCH: "PHRASE_KEYWORD_MISMATCH";
+    /** User-defined-function definition parsing (`f(x, y) = ...`), an invalid token where a parameter name was expected. */
+    readonly USER_FUNCTION_INVALID_PARAM_NAME: "USER_FUNCTION_INVALID_PARAM_NAME";
+    /** `f() = ...` with zero parameters, indistinguishable from a plain no-arg function call, so rejected at definition time. */
+    readonly USER_FUNCTION_NO_PARAMS: "USER_FUNCTION_NO_PARAMS";
+    /** A user-defined function body calling an async plugin (weather/stocks/currency/...), rejected at definition time; v1 scope excludes async function bodies. */
+    readonly FUNCTION_BODY_MUST_BE_SYNCHRONOUS: "FUNCTION_BODY_MUST_BE_SYNCHRONOUS";
+    /** `BytecodeBuilder`'s `userFunctionBodies` side-table exceeding its capacity. Same class as `TOO_MANY_NUMERIC_CONSTANTS`/`TOO_MANY_STRING_CONSTANTS` below. */
+    readonly TOO_MANY_FUNCTION_DEFINITIONS: "TOO_MANY_FUNCTION_DEFINITIONS";
+    /** `BytecodeBuilder`'s `anonymousBodies` side-table (map/reduce inline transform bodies) exceeding its capacity. Same class as `TOO_MANY_FUNCTION_DEFINITIONS` above. */
+    readonly TOO_MANY_ANONYMOUS_BODIES: "TOO_MANY_ANONYMOUS_BODIES";
+    readonly EVALUATION_ERROR: "EVALUATION_ERROR";
+    readonly INSTRUCTION_LIMIT_EXCEEDED: "INSTRUCTION_LIMIT_EXCEEDED";
+    readonly STACK_LIMIT_EXCEEDED: "STACK_LIMIT_EXCEEDED";
+    /** New this phase. See `VM.ts`'s `safePop()`: a stack-underflow (corrupted bytecode, a buggy plugin) is now a controlled EngineError instead of a raw TypeError. Always `recoverable: false` (internal invariant violation). */
+    readonly STACK_UNDERFLOW: "STACK_UNDERFLOW";
+    readonly UNDEFINED_VARIABLE: "UNDEFINED_VARIABLE";
+    /** New this phase, the Tier-2/`LOAD_GLOBAL_VAR` hardening: a global variable read before its async preflight resolved, surfaced as a controlled error instead of pushing `undefined`. */
+    readonly GLOBAL_VARIABLE_NOT_RESOLVED: "GLOBAL_VARIABLE_NOT_RESOLVED";
+    readonly UNKNOWN_FUNCTION: "UNKNOWN_FUNCTION";
+    /** `unwrapEvalResult()`'s pending-when-expecting-value case, a caller-contract violation, not user-input. */
+    readonly UNEXPECTED_PENDING_RESULT: "UNEXPECTED_PENDING_RESULT";
+    /** User-defined-function call/definition errors (`CALL_USER_FUNCTION`/`DEFINE_USER_FUNCTION` opcodes), calling a name with no matching definition, calling with the wrong argument count, and the deliberate v1 restriction that a function body can't itself contain async work. */
+    readonly UNDEFINED_FUNCTION: "UNDEFINED_FUNCTION";
+    readonly FUNCTION_ARITY_MISMATCH: "FUNCTION_ARITY_MISMATCH";
+    readonly USER_FUNCTION_ASYNC_UNSUPPORTED: "USER_FUNCTION_ASYNC_UNSUPPORTED";
+    /** A map/reduce transform body (inline expression or user-defined function) calling an async plugin. Same v1 scope restriction as `USER_FUNCTION_ASYNC_UNSUPPORTED` above, enforced both at parse time (`MAP_REDUCE_TRANSFORM_MUST_BE_SYNCHRONOUS`, packages/mapreduce/) and as a defense-in-depth runtime backstop here. */
+    readonly MAP_REDUCE_ASYNC_UNSUPPORTED: "MAP_REDUCE_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";
+    /** `DEFINE_USER_FUNCTION`'s body-index lookup failing, a compiler/VM invariant violation (the opcode stream referenced a `userFunctionBodies` slot that doesn't exist), never a user-input error. */
+    readonly INTERNAL_MISSING_FUNCTION_BODY: "INTERNAL_MISSING_FUNCTION_BODY";
+    /** `MAP_INVOKE`/`REDUCE_INVOKE`'s anonymous-body-index lookup failing. Same class as `INTERNAL_MISSING_FUNCTION_BODY` above, for the `anonymousBodies` side-table instead of `userFunctionBodies`. */
+    readonly INTERNAL_MISSING_ANONYMOUS_BODY: "INTERNAL_MISSING_ANONYMOUS_BODY";
+    /** A coefficient grew past `RATIONAL_MAX_BITS`, e.g. repeated exact elimination multiplying denominators together. */
+    readonly SYMBOLIC_RATIONAL_OVERFLOW: "SYMBOLIC_RATIONAL_OVERFLOW";
+    /** `NaN` or `±Infinity` reaching a symbolic expression, neither of which has an exact rational value. */
+    readonly SYMBOLIC_NONFINITE_OPERAND: "SYMBOLIC_NONFINITE_OPERAND";
+    /** Division by an exactly-zero rational. Exact, unlike the double comparison it replaced, which could not distinguish a true zero from `5.551e-17`. */
+    readonly SYMBOLIC_DIVISION_BY_ZERO: "SYMBOLIC_DIVISION_BY_ZERO";
+    /** A tree exceeding `SYMBOLIC_MAX_NODES` entering the simplifier. */
+    readonly SYMBOLIC_NODE_LIMIT_EXCEEDED: "SYMBOLIC_NODE_LIMIT_EXCEEDED";
+    /** A builtin with no symbolic reading (`min`, `random`, the finance block, ...) applied to an expression still containing an unknown. Returned rather than computing against `toNumber()`'s placeholder zero. */
+    readonly SYMBOLIC_UNSUPPORTED_FUNCTION: "SYMBOLIC_UNSUPPORTED_FUNCTION";
+    /** The rational-root search exceeding `FACTOR_MAX_ROOT_CANDIDATES`. The candidate set is the product of two divisor sets, so a highly-composite coefficient escapes quickly. */
+    readonly SYMBOLIC_FACTOR_LIMIT_EXCEEDED: "SYMBOLIC_FACTOR_LIMIT_EXCEEDED";
+    /** An equation outside what the solver attempts: not a polynomial, above the degree ceiling, or non-linear in the unknown while another unknown is present. */
+    readonly SYMBOLIC_SOLVE_UNSUPPORTED: "SYMBOLIC_SOLVE_UNSUPPORTED";
+    /** `solve`'s second argument not being a bare name. */
+    readonly SOLVE_REQUIRES_VARIABLE_NAME: "SOLVE_REQUIRES_VARIABLE_NAME";
+    /** A derivative order outside 0..`DERIVATIVE_MAX_ORDER`. */
+    readonly SYMBOLIC_DERIVATIVE_ORDER_LIMIT: "SYMBOLIC_DERIVATIVE_ORDER_LIMIT";
+    /** An expression with no known elementary antiderivative. Reported rather than approximated, since a wrong integral is indistinguishable from a right one at the point of use. */
+    readonly SYMBOLIC_INTEGRAL_UNSUPPORTED: "SYMBOLIC_INTEGRAL_UNSUPPORTED";
+    /** A Taylor degree outside 0..`TAYLOR_MAX_DEGREE`. */
+    readonly SYMBOLIC_TAYLOR_DEGREE_LIMIT: "SYMBOLIC_TAYLOR_DEGREE_LIMIT";
+    /** A Taylor coefficient that does not reduce to an exact number at the expansion point. */
+    readonly SYMBOLIC_TAYLOR_INEXACT: "SYMBOLIC_TAYLOR_INEXACT";
+    /** An algebra verb's variable-name argument not being a bare name. */
+    readonly SYMBOLIC_REQUIRES_VARIABLE_NAME: "SYMBOLIC_REQUIRES_VARIABLE_NAME";
+    /** `jacobian` called with expressions containing no unknown to differentiate against. */
+    readonly SYMBOLIC_JACOBIAN_NO_VARIABLES: "SYMBOLIC_JACOBIAN_NO_VARIABLES";
+    /** A finite number whose decimal form could not be read back, which the regex covering every `Number.prototype.toString` output should make unreachable. */
+    readonly INTERNAL_RATIONAL_PARSE: "INTERNAL_RATIONAL_PARSE";
+    readonly EXPRESSION_TOO_LONG: "EXPRESSION_TOO_LONG";
+    readonly EXPRESSION_TOO_COMPLEX: "EXPRESSION_TOO_COMPLEX";
+    readonly NORMALIZED_TOKEN_LIMIT_EXCEEDED: "NORMALIZED_TOKEN_LIMIT_EXCEEDED";
+    /** `"=>"` with nothing before it, needs an expression or variable name to solve/simplify. */
+    readonly THEREFORE_REQUIRES_EXPRESSION: "THEREFORE_REQUIRES_EXPRESSION";
+    /** A `"=>"`-triggered expression called an async plugin (weather/stocks/currency). Same v1 scope restriction as user-function/map-reduce bodies. */
+    readonly THEREFORE_ASYNC_UNSUPPORTED: "THEREFORE_ASYNC_UNSUPPORTED";
+    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";
+    readonly CONFIG_PROPERTY_NOT_FOUND: "CONFIG_PROPERTY_NOT_FOUND";
+    readonly PLUGIN_OPERATOR_COLLISION: "PLUGIN_OPERATOR_COLLISION";
+    readonly PLUGIN_KEYWORD_COLLISION: "PLUGIN_KEYWORD_COLLISION";
+    readonly PLUGIN_UNIT_COLLISION: "PLUGIN_UNIT_COLLISION";
+    /** A package's declared `IEnginePackage.engineVersion` semver range doesn't satisfy the running engine's ENGINE_VERSION. See api/EngineVersionCompatibility.ts. */
+    readonly PACKAGE_ENGINE_VERSION_MISMATCH: "PACKAGE_ENGINE_VERSION_MISMATCH";
+    /** A package's declared `IEnginePackage.engineVersion` isn't a parseable semver range at all (a typo in the package's own descriptor). */
+    readonly PACKAGE_ENGINE_VERSION_INVALID_RANGE: "PACKAGE_ENGINE_VERSION_INVALID_RANGE";
+    /** `OpRegistry.allocateOpcode()`'s dynamic opcode pool (started at 201) exhausted, too many packages calling it. */
+    readonly OPCODE_POOL_EXHAUSTED: "OPCODE_POOL_EXHAUSTED";
+    /** `VMBuiltins.allocatePluginFunctionIndex()`'s 0-255 index pool (a single opcode-stream byte) exhausted. */
+    readonly PLUGIN_FUNCTION_INDEX_POOL_EXHAUSTED: "PLUGIN_FUNCTION_INDEX_POOL_EXHAUSTED";
+    readonly INVALID_RATE_UNIT: "INVALID_RATE_UNIT";
+    readonly INVALID_TIMECODE_UNIT: "INVALID_TIMECODE_UNIT";
+    readonly UNEXPECTED_ERROR: "UNEXPECTED_ERROR";
+    readonly UNKNOWN_ERROR: "UNKNOWN_ERROR";
+};
+/** Every error code the engine's own layers can produce, from {@link CoreErrorCodes}. */
+type CoreErrorCode = (typeof CoreErrorCodes)[keyof typeof CoreErrorCodes];
+/**
+ * The aggregated catalog type. Currently just `CoreErrorCode`, union in
+ * each package's own code-object type here as Phase 5 converts it, e.g.
+ * `CoreErrorCode | WeatherErrorCode | StocksErrorCode | ...`.
+ */
+type ErrorCode = CoreErrorCode;
+
+/**
+ * The engine's structured error type, the "Rust/Go-style, verbose, easy to
+ * tell the issue" half of the error-handling redesign (the other half is
+ * `Result.ts`).
+ *
+ * Historical note: an earlier version of this class (`UnifiedErrorFramework.ts`,
+ * still the import path most of the codebase uses. See that file, now a
+ * pure re-export barrel) had a much larger field set (`severity`,
+ * `recovery`, a 5-value enum, `ErrorRecoveryManager`) that was almost
+ * entirely dead: nothing downstream ever read `.severity`/`.recovery`,
+ * only `.message` reliably survived to a caller. This version is smaller
+ * and deliberately keeps only fields something actually consumes.
+ */
+
+/** A character-offset (and optional line/col) span into the original expression text, for a future "underline the offending token" UI, not yet wired to one. */
+interface SourceSpan {
+    start: number;
+    end: number;
+    line?: number;
+    col?: number;
+}
+/**
+ * Error classification, kept from the original framework, now actually
+ * consulted: it's the `format()` header and lets host code group errors
+ * by pipeline stage without string-matching `.code`.
+ */
+declare enum ErrorCategory {
+    /** Errors during expression parsing. */
+    PARSING = "PARSING",
+    /** Errors during bytecode execution. */
+    EXECUTION = "EXECUTION",
+    /** Errors from input validation (safety limits, config). */
+    VALIDATION = "VALIDATION",
+    /** Errors from external services/APIs (currency rates, weather, stocks). */
+    EXTERNAL = "EXTERNAL",
+    /** Internal engine invariant violations. See `recoverable`'s doc comment. */
+    INTERNAL = "INTERNAL",
+    /** Configuration errors. */
+    CONFIG = "CONFIG"
+}
+/** Fields accepted when constructing an {@link EngineError}. */
+interface EngineErrorInit {
+    /** Catalog code. See `errors/ErrorCode.ts`. Not a free string: every code used by a BUILT-IN package should be registered there so `ErrorCodeCatalog.spec.ts` can catch collisions/typos. Third-party packages may still use any string here, `EngineError.code`'s runtime type is `string`. */
+    code: ErrorCode | (string & {});
+    /** Short, single-line, `Error.message`-compatible. Existing `.toThrow(/pattern/)`/`.message` assertions keep working against this field, richer detail goes in `expected`/`found`/`suggestion`, not crammed into this string. */
+    message: string;
+    /** What the parser/validator/VM expected to see, in plain words, e.g. "a city name", "a 4-digit year", "end of expression". */
+    expected?: string;
+    /** What was actually found instead, e.g. "end of expression", `NUMBER "5"`, the offending token's literal text. */
+    found?: string;
+    /** An actionable, worked-example fix, e.g. `e.g. "weather in London"`. Mirrors this codebase's best existing messages (`WEATHER_EXPECTED_CITY`, `AS_CONVERTER_EXPECTED_NAME`). */
+    suggestion?: string;
+    /**
+     * `true` (the default) for every EXPECTED failure mode of user input or
+     * environment, bad syntax, an unknown variable/function, a safety limit
+     * exceeded, an external API being down. `false` is reserved for genuine
+     * ENGINE-INTERNAL invariant violations (corrupted bytecode, a stack
+     * underflow from a buggy plugin, an "impossible" state)
+     * `ErrorFactory.internal()`/`.config()` default to `false`, every other
+     * factory method defaults to `true`.
+     *
+     * This does NOT gate "does evaluation of the rest of the document
+     * continue", with this engine's per-line containment, it always does
+     * even for a `recoverable: false` error (see `ARCHITECTURE.md`'s
+     * async-batcher/Tier-2 hardening notes). It gates MESSAGE FRAMING and
+     * telemetry: "fix your syntax" vs. "this is an engine bug, worth
+     * reporting". See `EngineError.isFatal()`.
+     */
+    recoverable?: boolean;
+    /** Character-offset span into the source expression, when available. Not yet threaded through every call site, populate opportunistically, don't block on retrofitting every existing throw site. */
+    span?: SourceSpan;
+    /** Free-form structured context. The one field the pre-existing framework's real consumer (`ThreeTierEvaluator.ts`'s DAG-preservation-on-compile-error path) actually reads, kept name- and shape-compatible on purpose. */
+    context?: Record<string, unknown>;
+    /** The underlying error this one wraps, if any, passed straight through to native `Error.cause` (ES2022), so Node's default printer, most loggers, and `instanceof Error` tooling understand the chain for free. */
+    cause?: unknown;
+}
+/**
+ * The engine's structured error type. Still a real `Error` subclass (so
+ * `throw`/`catch`/`instanceof Error` all keep working exactly as before),
+ * but now every field except the removed `severity`/`recovery` pair is
+ * something real code reads.
+ */
+declare class EngineError extends Error {
+    readonly category: ErrorCategory;
+    readonly code: string;
+    readonly expected?: string;
+    readonly found?: string;
+    readonly suggestion?: string;
+    readonly recoverable: boolean;
+    readonly span?: SourceSpan;
+    readonly context?: Record<string, unknown>;
+    readonly timestamp: Date;
+    /**
+     * Set explicitly (not via `super(message, {cause})`). This repo's
+     * `tsconfig.json` targets ES6/ES5-ES7 lib, which predates TypeScript's
+     * ES2022 `Error` constructor `cause`-option overload. `Error.prototype.cause`
+     * is still a real runtime feature in every target this engine actually
+     * runs in (Node 16.9+, all evergreen browsers, Electron/Obsidian's
+     * bundled Chromium) regardless of the TS lib target used to type-check
+     * against it, assigning it directly gets the same Node-printer/logger
+     * interop with no build-config change needed.
+     */
+    readonly cause?: unknown;
+    constructor(category: ErrorCategory, init: EngineErrorInit);
+    /** `!recoverable`. See `EngineErrorInit.recoverable`'s doc comment for what this actually gates (message framing/telemetry, not whether evaluation continues). */
+    isFatal(): boolean;
+    /** Walk `.cause` repeatedly, collecting the full chain (this error first). */
+    causeChain(): unknown[];
+    /**
+     * Rust/Go-style multi-line renderer, the NEW thing a host/CLI/test
+     * reaches for when it wants the full, verbose picture, as distinct from
+     * `.message` (kept short and stable for existing assertions). Example:
+     *
+     * ```
+     * error[WEATHER_EXPECTED_CITY]: Expected a city name after "weather in"
+     *   expected: a city name
+     *   found: end of expression
+     *   suggestion: e.g. "weather in London"
+     * ```
+     */
+    format(): string;
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Factory for creating classified `EngineError`s. Every method accepts
+ * EITHER the original, minimal 3-arg shape (`code, message, context?`
+ * every existing call site across the codebase keeps compiling unchanged)
+ * OR the richer `EngineErrorInit` object (for `expected`/`found`/
+ * `suggestion`/`recoverable`/`span`/`cause`), upgrade a call site to the
+ * richer form only when you're already touching it, no separate churn
+ * pass required.
+ */
+declare class ErrorFactory {
+    private static build;
+    static validation(code: string, message: string, context?: Record<string, unknown>): EngineError;
+    static validation(init: EngineErrorInit): EngineError;
+    static parsing(code: string, message: string, context?: Record<string, unknown>): EngineError;
+    static parsing(init: EngineErrorInit): EngineError;
+    static execution(code: string, message: string, context?: Record<string, unknown>): EngineError;
+    static execution(init: EngineErrorInit): EngineError;
+    static external(code: string, message: string, context?: Record<string, unknown>): EngineError;
+    static external(init: EngineErrorInit): EngineError;
+    /** Defaults `recoverable: false`, reserve for genuine engine-internal invariant violations, not user-input errors. */
+    static internal(code: string, message: string, context?: Record<string, unknown>): EngineError;
+    static internal(init: EngineErrorInit): EngineError;
+    /** Defaults `recoverable: false`, a bad config is an environment-setup problem, not a per-line user-input error. */
+    static config(code: string, message: string, context?: Record<string, unknown>): EngineError;
+    static config(init: EngineErrorInit): EngineError;
+}
+/**
+ * Normalize any thrown value into an `EngineError`, an `EngineError`
+ * passes through as-is; a plain `Error` gets wrapped (message preserved,
+ * original attached via `cause`); anything else becomes a generic
+ * "unknown error" wrapping the stringified value. Used at every
+ * throw-space/Result-space boundary (`Result.tryCatch`'s default
+ * `normalize`, the VM's outer execution try/catch, `AsyncResolutionBatcher`'s
+ * per-line containment) so a raw `TypeError` from a genuine engine bug
+ * still surfaces as a structured, catalogued error instead of an opaque
+ * uncaught exception.
+ */
+declare function normalizeUnknownError(error: unknown): EngineError;
+
+export { type CoreErrorCode as C, EngineError as E, type SourceSpan as S, CoreErrorCodes as a, type EngineErrorInit as b, ErrorCategory as c, type ErrorCode as d, ErrorFactory as e, normalizeUnknownError as n };