Complete the documentation set for the M0.5 toolchain, grounded in the code: - spec/references.md: import/reference/call edges, identities, loader rules, anchors, `ref` resolution/ambiguity, `check --refs` validation. - spec/value-wire.md: exact wire_version 1 typed encoding, integer-as-decimal string rule, special floats, limits and exact float round-trip. - spec/security.md: modes (strict refuses without OS isolation), capabilities, path rules, budgets, tracing, foreign process caveats, plugin trust. - spec/package-format.md: marqdo.yaml/lock formats, validation, lock/sync, unsupported registry/git/environment work. - spec/plugin-abi.md: ABI v1 layout/ownership/negotiation, manifest/artifact rules, wire envelopes, loader lifecycle, trust boundary, SDK/C demo, and the implemented CLI plugin-invocation flow with its limitations. - spec/math.md and spec/foreign.md: the implemented math subset and the foreign request/response/timeout/capability contract. - docs/adr/0001..0007: accepted decisions for the span foundation, inert executables outside function bodies, ref ambiguity (S-07), strict refusal, AST normalization, CLI contract and BigInt/typed wire (S-08). - docs/contributor-guide.md: repo map, workflow, fixture/golden updates, quality gate, ADR/commit policy. - docs/STATUS.md: P0-P7 matrix with evidence, open items and the blueprint §18 Alpha checklist (conclusion: not yet Alpha-complete), including known divergences rather than overclaims. - README.md rewritten from "design-only starter" to the working implementation with quickstart, implemented phases, deliberate limits and doc index. - AGENTS.md: updated pointers/workflow only; architectural rules unchanged. - Consistency fixes in spec/mapping.md/evaluation.md (inert emph outside functions, unsupported math.simplify/differentiate).
6.7 KiB
ADR-0003: ref resolution order and ref.ambiguous (S-07)
Status: Accepted Date: 2026-11-20
Context
ref("#anchor") is the only way to turn a heading range into an inert
resource value (Formula or Code) or a FunctionRef. The blueprint
(§5.2, unresolved issue S-07) is explicit that a heading range can contain
several formulas or code fences, and that the implementation must never
silently pick the first one:
一个范围存在多段公式时,默认对象选择必须是明确规则(例如禁止无选择器,要求
math.formulas(ref(...))列出候选;不选"第一条")。
The failing example is easy to write:
## f
### 公式
$$a = 1$$
$$b = 2$$
**x = ref("#公式")**
If ref returned a = 1, the program would be non-deterministic with respect
to document structure (insert an earlier formula and the meaning changes) and
would hide a genuine authoring error.
At the same time the common case — one formula per heading — must stay simple;
requiring a selector for every reference would make examples/math.mq.md
awkward.
Decision
crates/marqdo-runtime/src/builtins_impl.rs::resolve_ref implements this
algorithm:
- The target must be a
Textbeginning with#; otherwisesymbol.unknown("must be a#headinganchor").refis not a URL resolver and does not cross modules. - The fragment is looked up in the current module's anchor map
(
Module::anchors, GitHub-style slugs computed incrates/marqdo-frontend/src/units.rs).refdoes not fall back to canonical unit names and does not search imported modules. - Collect the resources attributed to the resolved unit (innermost unit by
span,
crates/marqdo-frontend/src/resources.rs).- Exactly 1 → return
FormulaorCode(withunitandspanprovenance). - 0 → if a function's unit equals the resolved unit, return
FunctionRef { module, name }; otherwisesymbol.unknown. - ≥ 2 → return
ref.ambiguous: "#...contains N resources; select one explicitly instead of relying on the first". Never choose a resource.
- Exactly 1 → return
- Function references are callable through the normal call path; formulas and
code remain inert until
math.eval/foreign.*is explicitly called (those are separately capability-checked).
Resource attribution is deterministic: a resource belongs to its innermost
enclosing heading unit, resources keep document order, and a resource is a
Markdown math/math_block or code_block node (inline code is not a
resource).
The ref.ambiguous category is ErrorCategory::RefAmbiguous with the stable
code ref.ambiguous (crates/marqdo-value/src/error.rs).
Alternatives
- First resource wins (blueprint's rejected baseline). Rejected by S-07: document edits would silently change program meaning, and there is no diagnostic for the author.
- Always require a selector argument
(
ref("#f", selector="second")). Rejected for M0.5: no selector syntax or addressing scheme is specified yet, and the single-resource case is by far the common one. A future ADR can add an explicit selector while keeping the ambiguity rule. - Error on every heading with ≥ 2 resources at compile time, even if never
referenced. Rejected: a document may legitimately contain several formulas
for prose and never
refthem; only the reference is ambiguous. - Return a list of all candidates. Rejected for v1: it changes the return
type and forces every caller to handle a selector; a dedicated API
(
math.formulas(ref(...))) would be a new spec, not a silent widening. - Cross-module
ref. Rejected for v1: the wire/identity model andModuleIdresolution live in the loader;refis a pure runtime builtin over the current module. Cross-module resources are an open item.
Markdown AST shape
heading(level=2) "f"
heading(level=3) "公式"
math_block "/$$ a = 1 $$/" -> Resource::Formula { unit: <#f/公式> }
math_block "/$$ b = 2 $$/" -> Resource::Formula { unit: <#f/公式> }
paragraph -> strong("x = ref(\"#公式\")")
Anchors are separate from unit paths: #公式 is a GitHub slug for the heading
name, while the canonical UnitId is <module>#f/公式. Colliding slugs get
-1/-2 suffixes; canonical ids never do.
Compatibility
ref.ambiguousis a stable runtime code; callers may branch on it.- The single-resource and function-reference cases are frozen. Adding a selector must be additive (new argument or new builtin) and must not change the ≥ 2 error into a silent choice.
reftarget syntax (#fragment) is frozen; changing it to accept file paths would need a new ADR.- No package/ABI/wire change: formula/code values already carry
unit/span/content_hash.
Example behavior, verified by
crates/marqdo-runtime/tests/interpreter.rs::ambiguous_ref_resource_is_an_error:
$ marqdo run index.mq.md # heading with two $$...$$ blocks and ref("#公式")
runtime error[ref.ambiguous]: `#公式` contains 2 resources; select one explicitly instead of relying on the first
Security
refis a pure builtin: no host call, no capability required, no side effect. It only returns inert values or a function reference.- An inert
Formula/Codedoes not execute. Evaluation/execution requires a separate explicit call (math.eval,foreign.run/call), which is capability checked at the host boundary. - Refusing ambiguity prevents a class of "wrong formula executed" mistakes, which matters for scientific documents where formulas are evidence.
Testing
crates/marqdo-runtime/tests/interpreter.rs::ambiguous_ref_resource_is_an_errordrives a real document through frontend + runtime and asserts theref.ambiguouscode.crates/marqdo-frontend/src/resources.rstests attribution to innermost functions, multiple resources kept in one unit, and stable SHA-256 code hashes.crates/marqdo-markdown/frontendtests cover anchors and slug collisions.examples/math.mq.mdis the positive single-formula case; it runs undermarqdo runonly via a function (the example itself defines callable functions, nomain).- Missing anchor/not-a-function cases are covered by the
symbol.unknownpaths; conformance fixtures are being added by the fixtures workstream.
Migration & rollout
No migration needed for documents with exactly one resource per referenced
heading. Documents that relied on "first formula" behavior (there are none in
the examples) must split headings or wait for an explicit selector API. If a
selector is added later, keep ref("#...") behavior unchanged and introduce
the selector as a new argument/builtin, with tests for both the ambiguous and
the selected case.