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.
6.7 KiB
6.7 KiB
ADR-0054: One static callable binding, one runtime dispatch
- Status: Accepted (2026-11-21)
- Supersedes the resolution model of ADR-0009/ADR-0010 where they conflict
- Implements: RFC-EXT-0001 §4 (PR-01/PR-02)
Context
The tree had four independent ways to decide what a call means:
marqdo-frontend/src/calls.rschecked a Member call's builtin name before its import alias;marqdo-runtime/src/interpreter.rschecked the import alias before the builtin for the same expression;- the runtime treated an undeclared
alias.nameas a plugin invocation whenprogram.external_callableswas empty ("try it at run time"); marqdo-clisynthesised an empty-parameter descriptor (params: Vec::new()) for exports that were loaded but not statically described.
Consequences observed while building RFC-EXT-0001's fixtures:
checkcould accept a call thatrundispatched to a different implementation (or vice versa);- an unknown symbol failed only at run time, with a Host side effect already attempted;
- an import alias that happened to equal a builtin dotted namespace (
math) silently changed the meaning ofmath.eval(...)depending on the pipeline; - plugin arity/name errors could pass static checking and only fail (or succeed with different arguments) at the ABI boundary.
The language contract (RFC-LANG-0002) already says calls are expressions and
that check and run must agree; the implementation had no such guarantee.
Decision
- One registry.
marqdo_ir::callable::CallableRegistryis the only static table. It contains builtins (including official bundled-stdlib public aliases), module functions keyed by canonical name plus unique local name, and exact plugin exports (namespace.function). Duplicate declarations are rejected when the registry is built; order never decides the answer. - One binding pass.
marqdo_frontend::calls::bind_program_calls(program, registry)walks every statically visible call expression exactly once and producesCallBindingTableplus diagnostics. It replaces the splitvalidate_module/validate_programpriority logic on the CLI path (the standalone frontend keeps a wrapper for single-document tests). The result is installed onProgram::call_bindings. - Deterministic identity. A call site is
(module id, function id, byte span)(CallSiteKey), never a disk path, registration order or hash-map iteration. A bound target is one of:Builtin { canonical_name }— fixed core function;Marqdo { function }— exactFunctionId(module functions and official stdlib aliases such as打印/print→io.mq.md::写值);AbiPlugin { package, export, digest, param_names }— complete export name plus the statically verified artifact digest and manifest argument order;DynamicValue— a language value (for example aFunctionRef); this is the only non-static path and cannot reach an ABI export by name.
- Runtime dispatches by identity.
eval_calllooks up the site's binding and calls the recorded target. It never callsbuiltins::find(qualified), never inspectsexternal_callables.is_empty()and never guesses a plugin. A missing binding is an internal error (internal.error), not a reason to re-resolve. - Prepare finalises once.
marqdo-clihas one composition step (project_prepare::prepare): load sources → read extension descriptors (nodlopen/spawn) → build the registry → bind calls once.check,run/call,inspectand Analysis consume that one prepared program. Static plugin descriptors are inserted before binding, not appended after a first validation. - Exact run-time reconciliation.
runverifies each selected plugin artifact, loads it, then compares the Host's actual exports (name, raw signature, artifact digest, owner package) with the static descriptors one-to-one. Any extra, missing or altered export fails withext.plugin_binding_mismatchbefore the entry function runs. No descriptor is synthesised at run time. - Print is not special.
Program.print_overrideand the runtime打印/printbranch are removed. The builtin placeholder remains only for embedders without the official bundle and fails withkernel.unavailable; the official bundle declares aliases in verified metadata (ADR-0058).
Priority matrix (normative)
See spec/callable-resolution.md for the complete matrix and diagnostics. In
short:
f(...): local variable → official alias/reserved builtin → current namespace → canonical name → unique local name → otherwisesymbol.unknown(ambiguity is an error, never a first-match);alias.f(...): explicit import alias → builtin dotted namespace → exact plugin export → otherwisesymbol.unknown;some_value.f(...): dynamic language dispatch only.
Import aliases that collide with a builtin or plugin dotted namespace are
rejected at prepare with ext.import_namespace_conflict; duplicate plugin
exports are rejected with ext.duplicate_callable.
Consequences
checkandrunnow share binding identity; CALL-01…CALL-16 incrates/cli/tests/callable_resolution.rspin the matrix.- 0.x breaking change: a project importing a module under an alias that equals
a builtin namespace (for example
math) must rename the alias. There is no--legacyswitch and no dual semantics. - Analysis v2's
calls[].state/targetare now projected from the same binding (official aliases appear asfunctiontargets). Analysis v2 schema and fields are otherwise unchanged; privateCallBindingTableis not serialized. - Runtime no longer performs per-call name resolution, so the dynamic path is
limited to language values. A text or map value called as a function is
call.not_callableand never becomes a Host plugin request. - Plugin manifests must be complete before binding: a manifest with a missing or malformed signature is a prepare error; ABI v1 default values are rejected until the wire semantics are versioned.
Rejected alternatives
- Pick a fixed precedence and keep two implementations. Rejected: the RFC requires one static answer, and duplicated precedence is exactly the defect.
- Build the registry lazily in the runtime. Rejected:
checkwould still not prove the binding, and runtime loading would change static resolution. - Keep the empty-
external_callablesfallback for "developer convenience". Rejected: it turns a compile error into a Host call attempt and breakscheck's no-execution guarantee. - Expose
CallableId/CallBindingTablein Analysis v2. Rejected: private IR must not become a public wire contract without a version bump. EOF