Files
marqdo-cli/docs/adr/0054-callable-binding-single-source.md
T
cflmy 1f6fd644a0 feat(ext): single callable binding, provider v2 CLI, capability handlers, stdlib aliases
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.
2026-11-22 00:17:36 +08:00

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:

  1. marqdo-frontend/src/calls.rs checked a Member call's builtin name before its import alias;
  2. marqdo-runtime/src/interpreter.rs checked the import alias before the builtin for the same expression;
  3. the runtime treated an undeclared alias.name as a plugin invocation when program.external_callables was empty ("try it at run time");
  4. marqdo-cli synthesised 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:

  • check could accept a call that run dispatched 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 of math.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

  1. One registry. marqdo_ir::callable::CallableRegistry is 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.
  2. One binding pass. marqdo_frontend::calls::bind_program_calls(program, registry) walks every statically visible call expression exactly once and produces CallBindingTable plus diagnostics. It replaces the split validate_module/validate_program priority logic on the CLI path (the standalone frontend keeps a wrapper for single-document tests). The result is installed on Program::call_bindings.
  3. 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 } — exact FunctionId (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 a FunctionRef); this is the only non-static path and cannot reach an ABI export by name.
  4. Runtime dispatches by identity. eval_call looks up the site's binding and calls the recorded target. It never calls builtins::find(qualified), never inspects external_callables.is_empty() and never guesses a plugin. A missing binding is an internal error (internal.error), not a reason to re-resolve.
  5. Prepare finalises once. marqdo-cli has one composition step (project_prepare::prepare): load sources → read extension descriptors (no dlopen/spawn) → build the registry → bind calls once. check, run/call, inspect and Analysis consume that one prepared program. Static plugin descriptors are inserted before binding, not appended after a first validation.
  6. Exact run-time reconciliation. run verifies 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 with ext.plugin_binding_mismatch before the entry function runs. No descriptor is synthesised at run time.
  7. Print is not special. Program.print_override and the runtime 打印/print branch are removed. The builtin placeholder remains only for embedders without the official bundle and fails with kernel.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 → otherwise symbol.unknown (ambiguity is an error, never a first-match);
  • alias.f(...): explicit import alias → builtin dotted namespace → exact plugin export → otherwise symbol.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

  • check and run now share binding identity; CALL-01…CALL-16 in crates/cli/tests/callable_resolution.rs pin 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 --legacy switch and no dual semantics.
  • Analysis v2's calls[].state/target are now projected from the same binding (official aliases appear as function targets). Analysis v2 schema and fields are otherwise unchanged; private CallBindingTable is 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_callable and 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: check would still not prove the binding, and runtime loading would change static resolution.
  • Keep the empty-external_callables fallback for "developer convenience". Rejected: it turns a compile error into a Host call attempt and breaks check's no-execution guarantee.
  • Expose CallableId/CallBindingTable in Analysis v2. Rejected: private IR must not become a public wire contract without a version bump. EOF