Files
marqdo-cli/spec/callable-resolution.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

11 KiB
Raw Blame History

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:

  1. Local variable. If f is a parameter or has been assigned anywhere in the function body, the site binds DynamicValue. At run time the value must be callable (FunctionRef in this release); a Text/Map/etc. value is call.not_callable. This is a language variable rule, not an escape hatch to a plugin.
  2. 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.
  3. Current namespace function. If the enclosing level-1 namespace N declares N.f, that function is chosen.
  4. Canonical function name. A function whose canonical name is exactly f.
  5. Unique local name. A function whose local_name is f in 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".
  6. Otherwise symbol.unknown.

2.2 Qualified alias.f(...)

  1. Local variable named alias. If alias is a local value, the site binds DynamicValue; alias.f is ordinary language member access. This cannot become a plugin call.
  2. 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 is symbol.unknown; it never falls back to a builtin or plugin with the same dotted spelling.
  3. Builtin dotted namespace. Otherwise, an exact builtin alias.f (for example math.eval) binds Builtin.
  4. 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.
  5. 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_callable at 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.arity otherwise).

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 (--plugin missing) is symbol.unknown; a selected plugin without an exact export descriptor is symbol.unknown. There is no runtime fallback.

4. Run-time reconciliation

run/call performs, in order:

  1. static prepare (sources, manifests, signatures, binding) — no binary loaded;
  2. verify each selected artifact path, target and SHA-256;
  3. verify the --allow-plugin grant;
  4. load exactly the selected artifacts;
  5. 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 BoundTarget in both;
  • a statically invalid call fails check and run with the same diagnostic code and message; run refuses before any Host side effect;
  • check --plugin reads manifests and signatures only: it never dlopens a library, spawns a worker or executes a side-effect script; a missing plugin binary is not an error for check;
  • --emit Analysis 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.yaml or with a manifest that does not declare solver.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_integrity before the entry function;
  • with a missing b: call.arity at 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.