Files
marqdo-cli/docs/adr/0003-ref-resolution-and-ambiguity.md
T
cflmy 0116160399 docs: formal specs, ADRs, STATUS matrix, contributor guide and honest README
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).
2026-11-20 10:56:26 +08:00

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:

  1. The target must be a Text beginning with #; otherwise symbol.unknown ("must be a #heading anchor"). ref is not a URL resolver and does not cross modules.
  2. The fragment is looked up in the current module's anchor map (Module::anchors, GitHub-style slugs computed in crates/marqdo-frontend/src/units.rs). ref does not fall back to canonical unit names and does not search imported modules.
  3. Collect the resources attributed to the resolved unit (innermost unit by span, crates/marqdo-frontend/src/resources.rs).
    • Exactly 1 → return Formula or Code (with unit and span provenance).
    • 0 → if a function's unit equals the resolved unit, return FunctionRef { module, name }; otherwise symbol.unknown.
    • ≥ 2 → return ref.ambiguous: "#... contains N resources; select one explicitly instead of relying on the first". Never choose a resource.
  4. 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

  1. 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.
  2. 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.
  3. 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 ref them; only the reference is ambiguous.
  4. 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.
  5. Cross-module ref. Rejected for v1: the wire/identity model and ModuleId resolution live in the loader; ref is 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.ambiguous is 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.
  • ref target 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

  • ref is a pure builtin: no host call, no capability required, no side effect. It only returns inert values or a function reference.
  • An inert Formula/Code does 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_error drives a real document through frontend + runtime and asserts the ref.ambiguous code.
  • crates/marqdo-frontend/src/resources.rs tests attribution to innermost functions, multiple resources kept in one unit, and stable SHA-256 code hashes.
  • crates/marqdo-markdown/frontend tests cover anchors and slug collisions.
  • examples/math.mq.md is the positive single-formula case; it runs under marqdo run only via a function (the example itself defines callable functions, no main).
  • Missing anchor/not-a-function cases are covered by the symbol.unknown paths; 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.