Implements RFC-EXT-0001 PR-00..PR-07 first pass: - CallSiteKey/CallBindingTable + one frontend binding pass; runtime dispatch by identity - prepare composition root shared by check/run/inspect/Analysis; exact plugin reconciliation - provider.json v2 --provider/--allow-provider worker CLI with fail-closed verification - capability handler registry with real fs.read and audit - verified stdlib public aliases replace print_override/AST scan - docs: specs, ADR-0054/0055/0057/0058, README, CI/release gates, evidence PR-04 extension selection/lock v4 and final frozen-binary evidence remain.
11 KiB
Marqdo callable resolution and binding
Status: normative for the current implementation (ADR-0054/ADR-0058,
RFC-EXT-0001 §4). This document describes the single static resolution used by
check, run, call, inspect and Analysis. There is no second priority
order and no runtime name guessing.
1. Identity
A call is an expression (Expr::Call). Each statically visible call site has a
deterministic key:
CallSiteKey = (module id, function id, span.start, span.end)
The key is independent of the checkout path, package cache location, registration order and map iteration. For a signature-default expression the owning function is the function that declares the default, because the runtime evaluates defaults in that function's empty frame.
A binding is one of:
| Bound target | Meaning |
|---|---|
Builtin { canonical_name } |
fixed language builtin, addressed by its canonical name (never by a user alias) |
Marqdo { function } |
exact FunctionId of a Markdown-defined function, including an official bundled-stdlib public alias |
AbiPlugin { package, export, digest, param_names } |
exact plugin export; digest is the selected, verified artifact SHA-256 and param_names is the manifest order used to normalise positional arguments |
DynamicValue |
the callee is a language value (for example a FunctionRef); resolved at run time from the value, never by name |
CallBindingTable is private IR. It is not serialized into Analysis or Trace.
The public calls[].state/target projection is derived from it (see §6).
2. Resolution matrix
2.1 Unqualified f(...)
In this exact order; the first applicable step decides:
- Local variable. If
fis a parameter or has been assigned anywhere in the function body, the site bindsDynamicValue. At run time the value must be callable (FunctionRefin this release); aText/Map/etc. value iscall.not_callable. This is a language variable rule, not an escape hatch to a plugin. - Official alias or reserved builtin. The registry's builtin table contains fixed builtins and, when the verified bundle is present and the program uses them, official stdlib aliases. An official alias wins over the placeholder builtin of the same name. Third parties cannot insert names here.
- Current namespace function. If the enclosing level-1 namespace
NdeclaresN.f, that function is chosen. - Canonical function name. A function whose canonical name is exactly
f. - Unique local name. A function whose
local_nameisfin exactly one namespace. If two namespaces define the same local name and none of steps 1–4 applies, the call is an error (symbol.unknown, message reports the ambiguity); it is never "first in document order". - Otherwise
symbol.unknown.
2.2 Qualified alias.f(...)
- Local variable named
alias. Ifaliasis a local value, the site bindsDynamicValue;alias.fis ordinary language member access. This cannot become a plugin call. - Explicit import. If the module declares
import: { alias: <target> }, the call binds only a function of that imported module (canonical name first, then unique local name). A missing function issymbol.unknown; it never falls back to a builtin or plugin with the same dotted spelling. - Builtin dotted namespace. Otherwise, an exact builtin
alias.f(for examplemath.eval) bindsBuiltin. - Exact plugin export. Otherwise, if a selected static plugin declares the
complete name
alias.f, the site binds that export. The manifest signature is validated here; no library is loaded. - Otherwise
symbol.unknown.
alias in step 1/2 must be exactly an explicit import or a local value; there
is no implicit namespace search across packages.
2.3 Other callees
some_value.f(...), f_list[i](...), (expr)(...) and any other non-Ident,
non-member-of-Ident callee bind DynamicValue. Only language callables can be
invoked at run time.
2.4 Import namespace conflicts
Before any call is bound, each module's import aliases are checked against:
- builtin dotted namespaces (
alias.must not prefix any builtin name), and - visible plugin dotted namespaces (
alias.must not prefix any selected plugin export).
A collision is ext.import_namespace_conflict at the front-matter import span,
with a rename hint. Example: importing ./math.mq.md as math conflicts with
the builtin namespace math.; rename the alias to mymath. This is a
deliberate 0.x breaking change with no compatibility switch (ADR-0054).
2.5 Duplicate callables
The static table rejects:
- the same complete plugin export declared by two selected packages
(
ext.duplicate_callableat prepare); - a plugin export that equals a builtin name or an official alias
(
ext.duplicate_callable); - two different manifests for the same plugin package identity in one selection
(
ext.duplicate_callable); the exact same package identity is idempotent; - a malformed/ambiguous static table entry (
ext.duplicate_callable).
Order of --plugin flags never decides which declaration wins.
3. Argument checking
3.1 Markdown functions and builtins
CallableSignature::validate_args enforces:
- named arguments must exist exactly once; unknown names are
call.arity; - positional arguments require an explicit language signature and map to the
declared parameter order; overflow is
call.arity; - required parameters without defaults must be supplied; missing is
call.arity; - inferred signatures accept named arguments only (
call.arityotherwise).
Messages are deterministic and identical between check and run.
3.2 ABI plugin exports
- The static manifest signature is authoritative. Unknown, duplicate, missing
or excess arguments are rejected at prepare/bind time (
call.arity); the plugin is never spawned for a statically invalid call. - ABI v1 transports arguments as a named map. Positional arguments are
statically validated and deterministically normalised to the manifest's
declared parameter order at run time. Example:
solver.add(1, b=2)becomes{a:1,b:2}. - Manifest signature default values are rejected in ABI v1 until the wire semantics are versioned; no default is injected at run time.
- A plugin that is declared but not selected (
--pluginmissing) issymbol.unknown; a selected plugin without an exact export descriptor issymbol.unknown. There is no runtime fallback.
4. Run-time reconciliation
run/call performs, in order:
- static prepare (sources, manifests, signatures, binding) — no binary loaded;
- verify each selected artifact path, target and SHA-256;
- verify the
--allow-plugingrant; - load exactly the selected artifacts;
- compare the Host's actual exports with the static descriptors one-to-one
(
name, raw signature, artifact digest, owner package).
A mismatch in step 5 is ext.plugin_binding_mismatch, reported before the
entry function runs. run must never synthesise a missing descriptor or an
empty signature.
5. check versus run
check and run consume the same PreparedProgram binding table. Therefore:
- the same call site has the same
BoundTargetin both; - a statically invalid call fails
checkandrunwith the same diagnostic code and message;runrefuses before any Host side effect; check --pluginreads manifests and signatures only: it neverdlopens a library, spawns a worker or executes a side-effect script; a missing plugin binary is not an error forcheck;--emitAnalysis is derived from the same binding (no second resolver).
6. Analysis projection
calls[] keeps the v2 fields {function, span, callee, state, target}.
state is one of function, builtin, plugin, unresolved; it is now
derived from the binding table:
| Bound target | state |
target |
|---|---|---|
Builtin |
builtin |
canonical builtin name |
Marqdo |
function |
exact FunctionId string |
AbiPlugin |
plugin |
complete export name |
DynamicValue / unbound |
unresolved |
null |
Official stdlib aliases (for example 打印) therefore project as function
targets, because that is the implementation that runs. This is a projection of
the existing fields, not a new public schema. The private CallBindingTable is
never exposed; a future explicit resolved_call_target field would require an
Analysis version bump.
7. Diagnostics
| Code | Stage | Trigger |
|---|---|---|
symbol.unknown |
prepare/bind | no target for the call; ambiguity; unknown imported function; undeclared plugin export |
call.arity |
prepare/bind | bad argument name/number/duplication, invalid positional use |
ext.import_namespace_conflict |
prepare | import alias collides with a builtin/plugin dotted namespace |
ext.duplicate_callable |
prepare | duplicate complete export, builtin shadowing, conflicting package manifests |
ext.plugin_binding_mismatch |
run init | loaded exports/signatures/owner/digest differ from static descriptors |
ext.no_matching_artifact |
manifest read | plugin/provider has no artifact for the current target |
ext.artifact_integrity |
manifest read / run init | sha256 mismatch, path traversal, non-regular file, symlink escape |
call.not_callable |
run | dynamic value is not callable |
internal.error |
run | a call site has no binding (a prepared program must always be complete) |
Existing codes are reused rather than duplicated; ext.capability_handler_unavailable
is internal-only — the public wire code remains capability.unavailable.
8. Examples
8.1 Imported function, no conflict
---
import:
mymath: "./math.mq.md"
---
## @exec main
`return mymath.eval(a=1)`
Binds Marqdo { function: <package instance>::math.mq.md::eval } in both
check and run.
8.2 Builtin without an import
## @exec main
`return math.eval(ref("#公式"), {"r": 2}, target="A")`
Binds Builtin { canonical_name: "math.eval" }.
8.3 Import namespace conflict
---
import:
math: "./math.mq.md"
---
## @exec main
`return math.eval(a=1)`
check fails with ext.import_namespace_conflict; run refuses before
executing anything. Rename the alias.
8.4 Plugin export
## @exec main
`return solver.add(1, b=2)`
- without
--plugin solver/plugin.yamlor with a manifest that does not declaresolver.add:symbol.unknown(no Host fallback); - with the manifest: binds
AbiPlugin { package: "demo.solver", export: "solver.add", digest: "<sha256>", param_names: ["a","b"] }; - with a changed artifact byte:
ext.artifact_integritybefore the entry function; - with a missing
b:call.arityat prepare.
8.5 Dynamic FunctionRef
## @exec 平方
`params(n: Int)`
`return n * n`
## @exec main
`f = ref("#平方")`
`return f(n=4)`
The call site binds DynamicValue; the runtime calls the FunctionRef value.
A Text value in the same position fails call.not_callable and never reaches
the Host.