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

282 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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:
```text
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 `dlopen`s 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
```markdown
---
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
```markdown
## @exec main
`return math.eval(ref("#公式"), {"r": 2}, target="A")`
```
Binds `Builtin { canonical_name: "math.eval" }`.
### 8.3 Import namespace conflict
```markdown
---
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
```markdown
## @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`
```markdown
## @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.