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).
158 lines
6.7 KiB
Markdown
158 lines
6.7 KiB
Markdown
# 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:
|
|
|
|
```markdown
|
|
## 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
|
|
|
|
```text
|
|
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`:
|
|
|
|
```text
|
|
$ 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.
|