RuntimeError and CallFrame now carry a logical ModuleId and an origin (source/callsite). Errors are attributed at function/body boundaries so the innermost callee module wins; argument-binding errors and host/plugin/foreign boundaries are attributed to the caller callsite without fabricating a foreign stack. The CLI resolves (module_id, span) through LoadedProject::locate instead of indexing every span against the entry file. Unknown modules and out-of-range spans keep the module id and byte span but emit null line/file. Human output and frames now point at the correct file. Record the decision in ADR-0017 and supersede the ADR-0006 limitation. Add an end-to-end imported-module division-by-zero test.
3.7 KiB
ADR-0017: Runtime errors carry logical source locations
Status: Accepted Date: 2026-11-20 Supersedes: the entry-file-only runtime span rule in ADR-0006
Context
Span is a byte range in one source file. The interpreter produced spans in the
module where the failure occurred, but RuntimeError did not record which
module. The CLI therefore rendered every runtime error against the entry file
(crates/cli/src/commands.rs), so an error on line 5 of an imported module
could be reported at line 5 of index.mq.md, or with a meaningless column.
Span alone is not a source location. With package-aware ModuleIds (ADR-0008)
the logical location (ModuleId, Span) is available and stable across physical
paths and package instances.
Decision
1. RuntimeError and CallFrame carry a logical module
marqdo-value::RuntimeError gains:
module_id: Option<String>— canonicalModuleIdcontainingspan;origin: ErrorOrigin—source(Marqdo source) orcallsite(host, plugin or foreign boundary where no callee-internal stack exists).
CallFrame gains module_id: Option<String> for the callsite in the caller.
push_frame(function, span, module_id) records both.
2. Attribution happens at module boundaries, not at every constructor
- Every function body is executed with a known
FunctionId.module. Errors escapingexec_stmtsget that module if they do not already have one, so innermost callee attribution is preserved. - Argument-binding errors are attributed to the caller module at the call site.
- Errors crossing a host/plugin/foreign boundary are marked
origin: callsiteand attributed to the Marqdo callsite module. No foreign-internal stack is fabricated. - Existing
RuntimeError::new(category, span, message)call sites remain valid; attribution is additive.
3. CLI resolution has no entry-file fallback
LoadedProject::locate(module_id, span) parses the logical module, finds the
loaded file, rejects out-of-range spans, and derives line/column with that
file's LineIndex.
Runtime error JSON keeps span: {start, end} and adds module_id, origin,
line, column, file, relative_path. Each frame carries function,
module_id, span, and resolved line/column/file when available. If the
module is unknown or the span is invalid, the fields are absent/null and the
original module id and byte span are still emitted. Never clamp a span or fall
back to the entry file.
Human rendering prints the primary location from the located module. Frames
print their callsite file/line or the logical module@start..end when it cannot
be resolved.
Physical file fields are local convenience for humans; they are not part of
the versioned Analysis/Trace protocols and may differ across machines.
Consequences
- Cross-module runtime diagnostics now point at the module that failed and keep caller frames resolvable, including two package instances that share a relative path.
- Span offsets remain UTF-8 byte offsets into that module's exact source.
- The JSON shape is additive for existing consumers;
span.line/span.filemove to top-levelline/fileand are also duplicated per frame. - Compile-time diagnostics already carried a module; this change brings runtime errors to the same model.
- Any code constructing a synthetic
RuntimeErrorwithout a module still renders with an explicit<unknown>location rather than a guess.
Tests
runtime_error_in_imported_module_reports_that_module(CLI, real binary): division by zero in an imported module reports that module's file and line, both in JSON and human output; the callsite frame points at the entry file.- Existing runtime/conformance tests continue to pass with additive fields.