normalizeUnknownError
function normalizeUnknownError(error): EngineError;Defined in: packages/engine/src/errors/EngineError.ts:297
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.
Both branches state RECOVERABLE explicitly, while keeping the INTERNAL category. The two fields answer different questions and were previously answering the same one:
category INTERNAL whose fault is this? The engine’s. Worth reporting. recoverable is this engine instance still usable? Yes.
Everything reaching here is by definition something the engine did not
anticipate on ONE line, and per-line containment means the next line
evaluates normally, which __tests__/hardening/RobustnessEngineLifecycle
demonstrates over hundreds of alternating failure/success pairs. Reporting
that as isFatal() told a host the opposite, and a host that honours the
name would tear a document down over a single bad line. The “this is an
engine bug rather than your syntax” signal a caller wants for telemetry is
the CATEGORY, which is unchanged.
The flag is written out here rather than inherited from
ErrorFactory.internal(), which now defaults the same way, so that this
function’s contract survives a future change to that default.
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
error | unknown |