Replace the Strong/Emph/List/Quote mapping in place with the single @exec/@knowledge heading-mode model, unified payload carriers and keyword control flow. - add the authoritative RFC, ADR-0052 and a historical ADR index - rewrite spec/mapping.md and spec/expression.ebnf as the normative mapping/statement grammar; update evaluation, references, math, foreign, package-format, plugin-abi, security and schema notes - rewrite README, AGENTS, COMPATIBILITY and CHANGELOG for the breaking language change; update the architecture index/overview and active docs - mark superseded planning docs, compute RFCs, evidence and syntax-role ADRs as historical/superseded without rewriting their decisions - add migration guide, per-file inventory and dev-only audit scripts The frontend/stdlib migration is completed in the following commits; this commit contains documentation only.
19 KiB
Marqdo References, Imports and Calls
Status: current contract; breaking syntax revision (RFC-LANG-0002).
Import/reference/call identity, lock and resolution rules are unchanged; the
source spelling of a function heading and a call statement changed. See
spec/mapping.md for the current AST→program mapping.
Normative implementation:
| Concern | Code |
|---|---|
| Front matter parsing | crates/marqdo-markdown/src/frontmatter.rs |
| Module loading, project root, cycles | crates/cli/src/loader.rs |
| Module/Unit/Function identities | crates/marqdo-ir/src/lib.rs |
| Heading scopes, modes, anchors | crates/marqdo-frontend/src/units.rs |
| Resource collection and attribution | crates/marqdo-frontend/src/resources.rs |
| Executable payload → statement mapping | crates/marqdo-frontend/src/map.rs |
ref(...) runtime resolution |
crates/marqdo-runtime/src/builtins_impl.rs |
Static link graph (inspect --refs) |
crates/cli/src/commands.rs |
| Cross-module call validation | crates/marqdo-frontend/src/calls.rs |
This file complements mapping.md (AST roles) and
package-format.md (manifest/lock file).
1. Three edge kinds, never conflated
Blueprint §4.1 distinguishes three relations. The implementation keeps them separate and only the call edge can execute code.
| Edge | Written as | Resolved when | Executes? |
|---|---|---|---|
| Import | YAML front matter import: mapping |
module load / static analysis | No. Imported modules only register definitions; their main never runs. |
| Reference | Markdown [label](url) |
inspect --refs (static graph) |
No. Rendered/read as documentation only. |
| Call | a CallExpr in an executable payload, e.g. `f(...)`, **f(...)**, *f(...)* or > **f(...)** |
static validation, then execution | Yes, at runtime, through the interpreter. |
Consequences:
- A Markdown link never calls, imports or loads anything.
[计算作用力](#计算作用力)is a reference;`计算作用力()`in an Exec section is a call. - The block quote itself never creates a call.
> print(1)is inert prose;> **print(1)**contains a call payload. ref("#anchor")is a runtime builtin, not an import; it only resolves an inert resource or function reference in the running module.- The reference graph is static metadata and creates no proof obligation.
2. Canonical identities
These types live in crates/marqdo-ir/src/lib.rs.
2.1 ModuleId
pub struct ModuleId {
pub instance: String, // logical package instance
pub relative_path: String, // path inside the package module root
}
- Canonical display/wire form:
<instance>::<relative_path>, for exampleroot:default::index.mq.mdordep:geometry@0.1.0#0123456789ab::index.mq.md. - A bare path without
::is accepted by the parser asroot:defaultfor standalone documents and tests, but writers always emit the canonical form. - The instance is a logical identity (ADR-0008):
root:<project-name>@<version>,root:defaultwithout a manifest, ordep:<name>@<version>#<content-digest-prefix>for a resolved dependency. Physical cache paths and source kinds (path/git) are not part of identity; moving a cache does not change a module id, while a different locked version or content does. crates/marqdo-package::PackageResolverresolves path/Git sources and returnsResolvedPackage;crates/cli/src/loader.rsconsumes that result and rejects paths outside the package'smodule_root(entry: fatal load error; imported module:module.unresolveddiagnostic). The loader never branches onpath/gititself.- Module ids use
BTreeMapordering, so program iteration and JSON output are deterministic.
2.2 UnitId
pub struct UnitId { pub module: ModuleId, pub path: Vec<String> }
- One addressable heading range.
pathis the canonical heading path from the outermost heading to this unit (root unit has an empty path). - Canonical heading names are NFC-normalized, trimmed, with internal
whitespace collapsed to one space (
marqdo_markdown::normalize_name). - A heading mode declaration (
@exec/@knowledge) is stripped before normalization.## @exec mainhas the semantic namemain; the declaration is never part of aUnitId,FunctionIdor anchor. Displayrenders<module>#<path joined by '/'>; the root unit renders as<module>#.UnitKindisroot,namespace(#),function(##Exec) orsection(###+). A Knowledge H2 is an addressable knowledge unit, not afunction. Sections are addressable but not callable.
2.3 FunctionId
pub struct FunctionId { pub module: ModuleId, pub name: String }
nameis the namespace-qualified canonical function name:ns.fnwhen the level-2 heading is inside a level-1 namespace, otherwisefn(crates/marqdo-frontend/src/units.rs).Displayis<module>::<name>.- A function heading under a namespace yields both
FunctionId.name(ns.fn) andFunction.local_name(fn) plusnamespace: Some("ns"). - Lookup (
Module::function) first matchesid.name, then a uniquelocal_name; if several namespaces define the same local name the lookup returnsNonerather than guessing. - No overloads: duplicate canonical names in one scope are hard errors
(
sem.duplicate_unit_name, "duplicate heading name ... in the same scope") and are never auto-suffixed.
2.4 Anchors are a separate namespace, not identity
UnitIndex.anchors: BTreeMap<String, UnitId> maps GitHub-style heading slugs
to units (crates/marqdo-frontend/src/units.rs::github_slug):
- digits/letters/
_are kept and lowercased; spaces,-and tabs become-; all other punctuation is dropped; - collisions receive
-1,-2, ... suffixes in document order (separate counters per base slug); - anchors exist for navigation and
ref("#..."); they are not identity. Internal ids stay canonical, so a heading rename is a link-breaking change but never changes the canonical unit path.
3. Front matter imports
Imports exist only as an explicit YAML mapping in the document's front matter (recognized by the Markdown profile only at the start of the file):
---
import:
geometry: "@geometry"
util: "./lib/util.mq.md"
---
# @exec main
Parsing rules (crates/marqdo-markdown/src/frontmatter.rs::imports):
- the
importkey must be a mapping of string alias → string target; - aliases must be non-empty and unique within the document;
- any other front matter key is metadata for tools and is ignored by the
interpreter; invalid YAML is a
frontmatter.invaliddiagnostic, never silently dropped; - the removed
marqdo_semantics/syntaxkeys are not metadata that may be ignored: seeing them issem.unsupported_version_directivebecause they would otherwise look like a syntax selector; - imports are never inferred: a link, a file name or a directory scan does not create an import;
- the diagnostic span recorded for all imports of a file is the whole front
matter span (
ImportDecl.span).
3.1 Target forms
Loader::resolve_import recognizes exactly three forms:
| Target | Resolution |
|---|---|
@dependency |
Look up the alias after @ in marqdo.yaml dependencies. The dependency must declare a path source. Resolve project_root / path; if it is a directory, append index.mq.md; canonicalize. A git-only dependency cannot be resolved in this build (dependency.path is None → unresolved). |
std:<relative> |
Resolve inside the verified bundled standard library (ADR-0028). Print-using programs additionally get the bundled io module as the Compat-B 打印 destination (ADR-0030); this is not an implicit user import. The target must stay inside the bundle; ../absolute paths are rejected; .mq.md is appended when absent. The bundle's declared digest is verified before any module loads. No network/package manager is consulted. |
any other string (intended: ./file.mq.md) |
Join the string to the importing file's directory, then canonicalize. There is no extension inference, no search path and no fallback to a package directory. |
The resulting file is loaded as a module. If it canonicalizes outside the
project root, the loader reports "outside the project root" and the import
becomes a module.unresolved diagnostic.
3.2 Loader rules
crates/cli/src/loader.rs implements a static, non-executing load:
- Project root discovery (
marqdo_package::discover_root): walk up from the entry file (starting at its parent directory) to the nearest directory containingmarqdo.yaml; if none is found, the entry file's parent directory is the root. There is no--projectflag in this build and nested project boundaries are not diagnosed — the nearest manifest wins (open item). - Manifest is optional at run time; if a
marqdo.yamlexists in the root it is parsed and validated. An invalid manifest is a fatal load error (exit code 2), not a diagnostic list. - Entry module is loaded first;
Program.main_moduleis set to its module id. - Imports are processed depth-first in front matter order. Each import target is resolved as in §3.1, then loaded recursively.
- Cycle detection uses the path stack: if the canonical target path is
already being loaded, the importing file gets a
module.cyclediagnostic ("import ... creates an import cycle") and the import edge is skipped. Modules are otherwise loaded once; a second import of an already-loaded module reuses it. - Definitions only: loading parses, indexes and analyzes source. No
function is called, no
mainis run, no foreign/plugin code is touched. - After loading,
calls::validate_programvalidates cross-module and qualified-builtin calls and attaches diagnostics to the emitting file. - Diagnostics are collected in deterministic (load) order; the CLI renders them on stderr (or as JSON).
Failure mapping: a failure to load the entry file or read the manifest is a
fatal load error (exit 2, error: ... on stderr). A failure to resolve
an imported module becomes a module.unresolved diagnostic on the
importing file and check/run then exit 1 (run refuses to execute a project
with compile errors).
4. Markdown reference edges (inspect --refs)
marqdo inspect <file> --refs walks every link node in the entry document
and prints/writes an edge array (crates/cli/src/commands.rs::refs_json,
resolve_link). Each edge has:
{
"source": "references.mq.md",
"url": "./math.mq.md#计算圆面积",
"span": {"start": 54, "end": 95},
"resolved": true,
"target_module": "math.mq.md",
"target_unit": "math.mq.md#数学/计算圆面积"
}
Resolution rules:
#fragment→ look up the entry module's anchors, then fall back to a unit whose canonical name equals the fragment.http:///https://URL → counted as resolved with no local target. External links are never downloaded, imported or executed.- anything else → split optional
#fragment, canonicalize the path relative to the entry file's directory, require the target to be inside the project root, derive itsModuleId, and look up anchors/names in that module. If the target module is not imported, its source is read and analyzed statically on demand (analyze_source) so broken anchors can be detected without execution. resolved: falsemeans the file or anchor could not be resolved.
Current limitations (documented, not hidden):
check --refsvalidates every loaded document's link nodes and reports broken same-document anchors, missing files and missing target anchors asref.unresolvederrors, changing the command's exit status. Plaincheck(without--refs) does not treat reference problems as errors, because links are static knowledge references rather than execution inputs.inspect --refsprints the edge graph for the entry document only; other loaded modules are still covered bycheck --refs.- The graph is not emitted for call edges or import edges; imports are visible
through module counts/
inspectsummaries, calls throughinspect --ir.
5. ref("#anchor") runtime semantics
ref is a pure builtin (crates/marqdo-ir/src/builtins.rs,
crates/marqdo-runtime/src/builtins_impl.rs::resolve_ref). It never evaluates
the referenced resource and requires no capability.
Signature: ref(target: Text) -> Formula | Code | FunctionRef.
Algorithm:
targetmust start with#; otherwisesymbol.unknownwith the message "ref target ... must be a#headinganchor". It is not a URL resolver.- The fragment is looked up only in the running module's anchor map
(
Module::anchors). In this buildrefdoes not fall back to canonical unit names and does not search imported modules; a fragment that is not a GitHub slug yieldssymbol.unknown("no heading matches ..."). - The matching unit's resources (
Module::resources_of, computed from the unit's heading range) are examined:- exactly one resource →
Formula { latex, display, unit }orCode { language, source, content_hash, unit }.unitis theUnitId::Displaystring. - zero resources → if a function's unit equals the resolved unit, return
a
FunctionRef; otherwisesymbol.unknown. - more than one resource →
ref.ambiguouswith the message "#...contains N resources; select one explicitly instead of relying on the first". The runtime never picks the first resource. This is blueprint issue S-07 and is frozen by ADR-0003.
- exactly one resource →
- Resource attribution (
resources.rs): a formula or code fence belongs to the innermost enclosing heading unit by source span; resources are kept in document order. Markdownmath/math_blockandcode_blocknodes become resources; inlinecodespans do not.
Example (from examples/math.mq.md):
# @knowledge 数学
## @knowledge 圆面积公式
$$
A = \pi r^2
$$
## @exec 计算圆面积
`params(r: Number)`
`面积 = math.eval(ref("#圆面积公式"), {"r": r}, target="A")`
`return 面积`
ref("#圆面积公式") resolves the single formula under that heading; the
formula is still inert until math.eval consumes it.
5.1 Error model of ref
| Situation | Runtime code |
|---|---|
target not starting with # |
symbol.unknown |
| no anchor/unit matches | symbol.unknown |
| unit has no formula/code/function | symbol.unknown |
| unit has ≥ 2 resources | ref.ambiguous |
| module not present in the program | symbol.unknown |
ref.unresolved (crates/marqdo-value/src/diagnostic.rs) is a compile-time
code used by check --refs link validation (and by stale pre-RFC link-call
fixtures), not by the ref builtin. There is no link-form call in the current
language.
6. Call edges
6.1 Expression calls
Inside a function body, CallExpr nodes call:
- a local function (same module, namespace-aware resolution: current namespace first, then canonical name, then a unique local name);
- an imported function through its alias:
geometry.圆面积(r=2); - a builtin (
打印,math.eval, ...) by canonical name or alias; - a
FunctionRefvalue obtained earlier (for example fromref).
Static validation (crates/marqdo-frontend/src/calls.rs) checks arity,
argument names and the named-only rule for inferred signatures. Type errors are
runtime concerns in v1.
6.2 Calls written in payloads
A call is a statement or expression inside an executable payload, for example
`f(...)`, **f(...)**, *f(...)* or > **f(...)**. Its result is
discarded unless it is used by an assignment or another expression.
The old link-form block-quote call (> [label](#anchor)(args)) is removed
with the previous syntax; a block quote is now an ordinary container and its
plain content is inert. Migrate such a call to an ordinary payload call. If the
target can only be expressed as a link in the old form and no stable function
reference exists, stop and require a manual rewrite; do not generate a call the
new grammar cannot express.
Notes:
- a call expression with no arguments still writes
(); a bare function value is not a call; http(s)link targets are never downloaded or called;- cross-module calls go through an import alias expression
(
geometry.f(...)), never through a Markdown link.
6.3 Imported alias calls
At runtime an alias call resolves via Program::resolve_import to the target
module id; an unresolved alias is symbol.unknown. The static validator
checks the target module exists and the function/arity match when the whole
program is loaded, and emits symbol.unknown for an unknown function.
7. Diagnostics for references/imports
| Code | Severity | Where produced |
|---|---|---|
module.unresolved |
error | loader (bad import target) |
module.cycle |
error | loader |
ref.unresolved |
error | check --refs link validation, stale link-form call fixtures |
ref.ambiguous |
runtime error | ref builtin (≥ 2 resources) |
symbol.unknown |
error / runtime error | static call validation; ref anchor miss at runtime |
frontmatter.invalid |
error | analyser (bad YAML/import shape) |
sem.invalid_mode_marker |
error | heading mode declaration (see mapping.md §8) |
sem.empty_unit_name |
error | heading mode declaration with no name |
sem.duplicate_unit_name |
error | duplicate canonical heading/unit name in one scope |
sem.exec_without_function |
error | Exec payload with no owning Exec H2 |
sem.unsupported_version_directive |
error | legacy marqdo_semantics/syntax-selection front matter |
The previous markdown.invalid_construct role errors (Strong/Emph/List/Quote
shape, empty or duplicate heading names) are replaced by the sem.* codes and
the heading-name validation in mapping.md; runtime shape errors keep their
existing runtime.* codes.
8. Current limitations (open ADR candidates)
ref("#...")is module-local and has no cross-module form; there is no documented syntax for referencing a resource in an imported module.- Ordinary Markdown link resolution is inspection-only;
checkdoes not validate links and there is no--refsflag oncheck. - Markdown links never call; the removed link-form block-quote call has no replacement link syntax (use a payload call).
- Headings inside container blocks or fenced code never create units, and a heading whose semantic name is empty is a hard error rather than an ignored heading.
- Anchor lookup in
refdoes not fall back to canonical unit names, whileinspect --refsdoes. This asymmetry is intentional for the frozen build but should be unified by a future ADR. - A legacy front matter key such as
marqdo_semanticsis rejected (sem.unsupported_version_directive); it is not a syntax selector.