fix(runtime): resolve runtime errors against their logical module (B-08)
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.
This commit is contained in:
1 parent
6fed396d20
commit
509bdb1bf6
8 files changed
+390
-38
No files matched your search
@@ -89,12 +89,30 @@ missing-edge fail-closed, root-manifest invalidation, strict sync without
|
||||
`--locked`, full-closure env materialization, missing-lock and deleted-edge CLI
|
||||
failures.
|
||||
|
||||
### S2-A/H1-B record (current)
|
||||
|
||||
Runtime errors now carry a logical source location (ADR-0017):
|
||||
|
||||
* `RuntimeError.module_id`, `origin` (`source`/`callsite`), and
|
||||
`CallFrame.module_id`; attribution happens at function/module boundaries so
|
||||
the innermost callee module wins.
|
||||
* Host/plugin/foreign errors are marked as callsite errors without fabricating
|
||||
a foreign stack.
|
||||
* `LoadedProject::locate(module_id, span)` resolves the owning file and line;
|
||||
the CLI no longer falls back to the entry file. Unknown modules or
|
||||
out-of-range spans emit module/span with null line/file.
|
||||
* Human and JSON output report the failing module; caller frames resolve their
|
||||
own callsite modules.
|
||||
* CLI test `runtime_error_in_imported_module_reports_that_module` reproduces
|
||||
B-08 end to end with the real binary.
|
||||
|
||||
### M0.6 implementation progress
|
||||
|
||||
| Step | State | Evidence |
|
||||
|---|---|---|
|
||||
| S0/H0 CI baseline | **Done locally** | B-01 fixed in `crates/cli/tests/properties.rs`; fresh-clone path no longer needs an empty directory; full local gate green (see §S0/H0) |
|
||||
| S1/H1-A lock v3 graph | **Done** | ADR-0016; full-closure `marqdo.lock` v3; fail-closed edge lookup; strict non-rewriting `sync`; verified Git cache; unified file-set profile (see §S1/H1-A) |
|
||||
| S2-A/H1-B source locations | **Done** | ADR-0017; `RuntimeError`/`CallFrame` carry `module_id`; callsite origin; CLI module-aware resolution with no entry fallback (see §S2-A/H1-B) |
|
||||
| R0 baseline + ADRs | **Done** | this section; `docs/adr/0008`–`0012`; full workspace gate |
|
||||
| R1 package-aware identity + callable registry | **Done for statics; superseded by S1 lock v3** | `ModuleId { instance, relative_path }`; `PackageResolver` path sources; lock v3 transitive graph (ADR-0016) replaces the flat v2 lock; `CallableRegistry` for builtins/marqdo/declared ABI exports; external manifest wiring is R2 |
|
||||
| R2 ABI/Kernel/Broker | **Done (worker = crash isolation)** | `KernelRegistry` external providers; complete-name export routing; `CapabilityBroker`; static `check --plugin`; multi-export C test; isolated worker with timeout/crash tests; host handle table. Native/worker are not an OS sandbox |
|
||||
|
||||
@@ -108,11 +108,12 @@ implementation). Consumers should accept both names or key on the presence of
|
||||
`diagnostics`/`value`; this is a known quirk.
|
||||
|
||||
`run`/`call` (failure): `{"command":"run","success":false,"stdout":...,
|
||||
"error":{"code":"...","message":"...","span":{"line":..,"column":..,"file":..},
|
||||
"frames":[...]},"trace":[...]}`. Runtime error spans are currently resolved
|
||||
against the **entry file** only, even when the error came from an imported
|
||||
module; frames carry function names, not module ids. This is a known precision
|
||||
limitation.
|
||||
"error":{"code":"...","origin":"source|callsite","module_id":"...",
|
||||
"span":{"start":..,"end":..},"line":..,"column":..,"file":..,
|
||||
"frames":[...]},"trace":[...]}`. Runtime locations are resolved against the
|
||||
logical module that produced the error (ADR-0017); there is no entry-file
|
||||
fallback. Unknown modules or invalid spans leave line/column/file null while
|
||||
keeping the module id and byte span.
|
||||
|
||||
`plugin inspect`:
|
||||
|
||||
@@ -209,8 +210,9 @@ The CLI itself does not change the AST. What it exposes:
|
||||
* `crates/cli/src/output.rs` has no unit tests; diagnostic JSON is exercised
|
||||
through check/run smoke tests.
|
||||
* Add contract tests for: exit codes per failure class, stdout/stderr
|
||||
separation, JSON key presence, `call --json` command naming, and runtime
|
||||
error span from a non-entry module before calling the schema "final".
|
||||
separation, JSON key presence, `call --json` command naming. Runtime errors
|
||||
from a non-entry module are covered by
|
||||
`runtime_error_in_imported_module_reports_that_module` (ADR-0017).
|
||||
|
||||
## Migration & rollout
|
||||
|
||||
|
||||
@@ -0,0 +1,82 @@
|
||||
# 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 `ModuleId`s (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>` — canonical `ModuleId` containing `span`;
|
||||
* `origin: ErrorOrigin` — `source` (Marqdo source) or `callsite` (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
|
||||
escaping `exec_stmts` get 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: callsite`
|
||||
and 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.file`
|
||||
move to top-level `line`/`file` and 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 `RuntimeError` without 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.
|
||||
Reference in new issue
Block a user