EngineErrorInit
Defined in: packages/engine/src/errors/EngineError.ts:46
Fields accepted when constructing an EngineError.
Properties
Section titled “Properties”cause?
Section titled “cause?”optional cause?: unknown;Defined in: packages/engine/src/errors/EngineError.ts:88
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.
code: | CoreErrorCode | string & {};Defined in: packages/engine/src/errors/EngineError.ts:48
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.
context?
Section titled “context?”optional context?: Record<string, unknown>;Defined in: packages/engine/src/errors/EngineError.ts:86
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.
expected?
Section titled “expected?”optional expected?: string;Defined in: packages/engine/src/errors/EngineError.ts:52
What the parser/validator/VM expected to see, in plain words, e.g. “a city name”, “a 4-digit year”, “end of expression”.
found?
Section titled “found?”optional found?: string;Defined in: packages/engine/src/errors/EngineError.ts:54
What was actually found instead, e.g. “end of expression”, NUMBER "5", the offending token’s literal text.
message
Section titled “message”message: string;Defined in: packages/engine/src/errors/EngineError.ts:50
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.
recoverable?
Section titled “recoverable?”optional recoverable?: boolean;Defined in: packages/engine/src/errors/EngineError.ts:82
Whether this engine instance is still usable. true for everything that
went wrong on ONE line, whether the line’s fault (bad syntax, an unknown
variable, a safety limit exceeded), the environment’s (an external API
down), or the engine’s own (corrupted bytecode, a stack underflow from a
buggy plugin). false is for the far rarer case where there is no working
engine to go on with: a configuration or package-registration failure,
which is what ErrorFactory.config() is for and the only factory method
that still defaults to it.
The category answers a different question, and the two used to be answered
as one. Category INTERNAL says whose fault this is, the engine’s, worth
reporting as a bug. recoverable says whether the host may carry on, and
after an internal slip on one line it may:
__tests__/hardening/RobustnessEngineLifecycle.spec.ts alternates a
throwing line with a good one five hundred times and every answer stays
correct. Reporting that as isFatal() told a host the opposite, and a host
that honours the name would tear a document down over one bad line.
This has never gated “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 what a host is TOLD. See
EngineError.isFatal.
optional span?: SourceSpan;Defined in: packages/engine/src/errors/EngineError.ts:84
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.
suggestion?
Section titled “suggestion?”optional suggestion?: string;Defined in: packages/engine/src/errors/EngineError.ts:56
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).