Files
marqdo-cli/docs/adr/0009-unified-callable-resolution.md
T
cflmy 66476fbbfb docs(m0.6): integrate plan and freeze R0 baseline decisions
- move the revision package into docs/ and spec/, preserving all content
- record the M0.6 plan/audit cross-references and Proposed status
- correct stale STATUS claims about CI, console capability and check --refs
- add Accepted ADRs 0008-0012 for package identity, callable resolution,
  plugin export routing, capability broker and kernel providers
- record the passing R0 baseline gate (fmt, clippy, workspace tests)
2026-11-20 11:34:45 +08:00

149 lines
5.7 KiB
Markdown

# ADR-0009: One callable resolver for builtins, Marqdo functions and ABI exports
Status: **Accepted**
Date: 2026-11-20
## Context
M0.5 resolves calls in three unrelated places:
* `crates/marqdo-ir/src/builtins.rs::BUILTINS` plus
`crates/marqdo-frontend/src/calls.rs` for static validation;
* `crates/marqdo-runtime/src/builtins_impl.rs::dispatch` for builtin execution;
* `crates/marqdo-runtime/src/interpreter.rs` for Marqdo function lookup, with an
ad-hoc fallback that sends any unknown `alias.name` member call to the host as
a trusted plugin call.
Adding one external function therefore risks touching the builtin table, the
frontend, the runtime and the host. The frontend cannot statically validate a
plugin call because it has no descriptor for the export, and the runtime decides
by "first builtin/function/plugin that matches".
M0.6 R1/R2 require a single static description and a single runtime binding
path. The language expression grammar and control flow remain fixed; only the
symbol layer becomes registry-driven.
## Decision
### 1. Descriptor
`marqdo-ir::callable` defines:
```rust
pub struct CallableId(pub String); // canonical, globally unique
pub enum CallableOrigin {
Builtin,
Marqdo, // a FunctionId
AbiPlugin { package: String, export: String },
}
pub struct CallableDescriptor {
pub id: CallableId,
pub public_name: String, // `print`, `数学.阶乘`, `solver.add`
pub owner_package: PackageInstanceId,
pub signature: CallableSignature,
pub effects_requested: Vec<String>,
pub origin: CallableOrigin,
pub implementation_digest: Option<String>,
pub source_span: Option<Span>,
}
pub struct CallableSignature {
pub params: Vec<Param>,
pub kind: SignatureKind,
pub result: Option<String>,
}
```
Builtins keep their static `BUILTINS` table: they are part of the language, not
an extension point. The table is wrapped in descriptors; it is not copied into
every plugin.
### 2. Resolution
`CallableRegistry` is built deterministically from:
1. builtin descriptors (fixed, reserved names);
2. all program functions (canonical and unique local names);
3. explicitly declared external descriptors supplied by the CLI/package layer
from plugin manifests (never by loading a dynamic library during `check`).
Rules:
* fully qualified names are unique; duplicate external names are a hard
conflict, unless the caller explicitly aliases one (`solver.add as add`);
* an unknown function is a compile error, never "try builtins/plugin at
runtime";
* `check` validates arity/parameter names from the static descriptor for every
origin, including ABI exports;
* `run` binds the already-resolved `CallableId` and dispatches by origin;
* `Host` still performs capability authorization at the actual effect, based on
the package/plugin identity and the current execution context.
The existing `BUILTINS` list remains a closed language set. Third-party
extensions never edit it, `calls.rs` match arms or
`builtins_impl.rs::dispatch`.
### 3. Plugin calls
A plugin descriptor is derived from `plugin.yaml` exports
(`name`, `signature`, package, digest). `check --plugin <manifest>` (or a
manifest declared in `marqdo.yaml`) may add these descriptors statically without
loading any shared library. The runtime uses the export's complete dotted name
(`solver.add`), not only the first prefix.
A call form `solver.add(a=1, b=2)` resolves to a `CallableDescriptor` whose
origin is `AbiPlugin`. If no descriptor was declared, it is `symbol.unknown`;
it is not sent to the host speculatively.
### 4. Effects
`effects_requested` is a conservative static summary used for reporting and
permission prompts. It is not proof that an implementation is pure. At
execution the host checks the actual `HostOp` against grants; a manifest cannot
grant itself a capability.
## Alternatives
1. One global dynamic map of strings. Rejected: no static signature, no arity
checks, and unknown names would silently resolve after deployment.
2. Keep three lookup sites and synchronise them by convention. Rejected: the
M0.5 audit (E02) shows they already diverge.
3. Make builtins dynamic too. Rejected: builtins are language semantics and
their list is deliberately closed. Only the resolver is unified.
4. Let `run` probe ABI exports at execution time without a static descriptor.
Rejected: `check` must be able to reject bad calls and must never `dlopen`.
## Compatibility
`BUILTINS`, names and arity stay unchanged. Existing Marqdo function calls keep
working through the registry. Unknown calls that M0.5 treated as plugin calls now
require a declared plugin descriptor; this is a deliberate diagnostic
improvement, not a language change. JSON diagnostics keep stable codes and add
`callable.unknown`/`callable.ambiguous` only where the old code had no specific
answer.
## Security
The registry is metadata, not authority. A descriptor only says "this callable
exists and has this signature"; the host checks `check_plugin`, the package
identity and the current `ExecutionContext` before invoking native code.
`check` must not load a dynamic library, spawn a kernel or execute imported
modules.
## Testing
* frontend tests: builtin/function/plugin descriptors, duplicate qualified
names, aliasing, unknown member calls, arity errors;
* runtime tests: bound `CallableId` dispatch for all three origins;
* CLI contract test: a plugin export's signature is rejected statically before
any library is loaded;
* a plugin with two prefixes exercises both descriptors.
## Migration & rollout
R1 introduces the descriptor/registry and builtin+function resolution. R2 adds
ABI export descriptors, multi-export routing and the capability broker. The
old ad-hoc plugin fallback is removed when the R2 tests prove the replacement.