diff --git a/crates/marqdo-frontend/src/calls.rs b/crates/marqdo-frontend/src/calls.rs
index 1b77b9c..223e729 100644
--- a/crates/marqdo-frontend/src/calls.rs
+++ b/crates/marqdo-frontend/src/calls.rs
@@ -268,6 +268,21 @@ impl<'a> CallChecker<'a> {
}
}
}
+ // A declared ABI export is a static descriptor: validate
+ // its signature here, without loading the shared library.
+ if let Some(program) = self.program {
+ if let Some(descriptor) = program.external_callable(&qualified) {
+ if let Err(message) =
+ descriptor.signature.validate_args(args, &qualified)
+ {
+ self.diagnostics.push(
+ Diagnostic::error(codes::CALL_ARITY, Some(span), message)
+ .with_hint("check the plugin manifest export signature"),
+ );
+ }
+ return;
+ }
+ }
}
self.expr(base);
}
@@ -437,6 +452,52 @@ mod tests {
assert!(diagnostics.iter().any(|d| d.code == codes::SYMBOL_UNKNOWN));
}
+ #[test]
+ fn declared_plugin_export_is_checked_statically() {
+ use marqdo_ir::callable::{
+ CallableDescriptor, CallableId, CallableOrigin, CallableSignature,
+ };
+ let module = make_module(vec![function(
+ "main",
+ &[],
+ SignatureKind::Explicit,
+ vec![return_call("solver.add(a=1)")],
+ )]);
+ let mut program = marqdo_ir::Program::default();
+ program.modules.insert(module.id.clone(), module.clone());
+ program.external_callables.push(CallableDescriptor {
+ id: CallableId("plugin:demo:solver.add".into()),
+ public_name: "solver.add".into(),
+ owner_package: "demo".into(),
+ signature: CallableSignature {
+ params: vec![
+ Param {
+ name: "a".into(),
+ span: Span::new(0, 0),
+ type_annotation: None,
+ default: None,
+ },
+ Param {
+ name: "b".into(),
+ span: Span::new(0, 0),
+ type_annotation: None,
+ default: None,
+ },
+ ],
+ kind: SignatureKind::Explicit,
+ },
+ effects_requested: vec!["host".into()],
+ origin: CallableOrigin::AbiPlugin {
+ package: "demo".into(),
+ export: "solver.add".into(),
+ },
+ implementation_digest: None,
+ source_span: None,
+ });
+ let diagnostics = validate_program(&program);
+ assert!(diagnostics.iter().any(|(_, d)| d.code == codes::CALL_ARITY));
+ }
+
#[test]
fn inferred_signature_requires_named_arguments() {
let callee = function("f", &["n"], SignatureKind::Inferred, vec![]);
diff --git a/crates/marqdo-ir/src/callable.rs b/crates/marqdo-ir/src/callable.rs
new file mode 100644
index 0000000..824a4c9
--- /dev/null
+++ b/crates/marqdo-ir/src/callable.rs
@@ -0,0 +1,361 @@
+//! Unified callable descriptors and lookup (ADR-0009).
+//!
+//! The language keeps builtins closed and functions defined by Markdown
+//! headings, but the *resolution* layer is shared by the frontend, the runtime
+//! and plugin export registration. A descriptor carries a static signature and
+//! an explicit origin; it never grants authority by itself.
+
+use std::collections::BTreeMap;
+use std::fmt;
+
+use serde::{Deserialize, Serialize};
+
+use crate::{builtins, Function, Module, ModuleId, Param, Program, SignatureKind};
+use marqdo_span::Span;
+
+/// Globally unique callable identity.
+#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
+pub struct CallableId(pub String);
+
+impl fmt::Display for CallableId {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ f.write_str(&self.0)
+ }
+}
+
+/// Where the implementation lives.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+pub enum CallableOrigin {
+ /// A fixed language builtin.
+ Builtin,
+ /// A function defined by a Markdown heading.
+ Marqdo,
+ /// An export declared by a plugin manifest.
+ AbiPlugin {
+ /// Plugin package name.
+ package: String,
+ /// Complete dotted export name.
+ export: String,
+ },
+}
+
+/// Static signature used for checking calls before execution.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct CallableSignature {
+ /// Parameters in declaration order.
+ pub params: Vec,
+ /// Explicit signatures allow positional arguments; inferred do not.
+ pub kind: SignatureKind,
+}
+
+impl CallableSignature {
+ /// Validate an argument list by name/position and arity.
+ pub fn validate_args(
+ &self,
+ args: &[marqdo_expression::Arg],
+ display: &str,
+ ) -> Result<(), String> {
+ let mut provided = Vec::new();
+ let mut positional = 0usize;
+ for arg in args {
+ match &arg.name {
+ Some(name) => {
+ if !self.params.iter().any(|param| ¶m.name == name) {
+ return Err(format!("`{display}` has no parameter named `{name}`"));
+ }
+ if provided.contains(name) {
+ return Err(format!("duplicate argument `{name}`"));
+ }
+ provided.push(name.clone());
+ }
+ None => {
+ if self.kind != SignatureKind::Explicit {
+ return Err(format!(
+ "`{display}` has an inferred signature and only accepts named arguments"
+ ));
+ }
+ let Some(param) = self.params.get(positional) else {
+ return Err(format!(
+ "`{display}` accepts at most {} positional arguments",
+ self.params.len()
+ ));
+ };
+ if provided.contains(¶m.name) {
+ return Err(format!("duplicate argument `{}`", param.name));
+ }
+ provided.push(param.name.clone());
+ positional += 1;
+ }
+ }
+ }
+ for param in &self.params {
+ if param.default.is_none() && !provided.iter().any(|name| name == ¶m.name) {
+ return Err(format!(
+ "`{display}` is missing required argument `{}`",
+ param.name
+ ));
+ }
+ }
+ Ok(())
+ }
+}
+
+/// One statically visible callable.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct CallableDescriptor {
+ /// Globally unique id.
+ pub id: CallableId,
+ /// Name used from the language surface.
+ pub public_name: String,
+ /// Owning package instance (`core` for builtins).
+ pub owner_package: String,
+ /// Signature.
+ pub signature: CallableSignature,
+ /// Conservative effect request summary; not proof of purity.
+ #[serde(default)]
+ pub effects_requested: Vec,
+ /// Implementation origin.
+ pub origin: CallableOrigin,
+ /// Content digest of the implementation, when known.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub implementation_digest: Option,
+ /// Declaration source location, when known.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub source_span: Option,
+}
+
+impl CallableDescriptor {
+ /// Whether this is a builtin.
+ pub fn is_builtin(&self) -> bool {
+ matches!(self.origin, CallableOrigin::Builtin)
+ }
+}
+
+/// Deterministic callable index for one program or module.
+#[derive(Debug, Clone, Default)]
+pub struct CallableRegistry {
+ builtins: BTreeMap,
+ functions: BTreeMap>,
+ external: BTreeMap,
+}
+
+impl CallableRegistry {
+ /// Build a registry containing builtins plus every function in `module`.
+ pub fn for_module(module: &Module) -> Self {
+ let mut registry = Self::default();
+ registry.add_builtins();
+ registry.add_module(module);
+ registry
+ }
+
+ /// Build a registry for all modules and declared external descriptors.
+ pub fn from_program(program: &Program) -> Self {
+ let mut registry = Self::default();
+ registry.add_builtins();
+ for module in program.modules.values() {
+ registry.add_module(module);
+ }
+ for descriptor in &program.external_callables {
+ // Conflicting declarations are reported by the loader; keep the
+ // first deterministic entry here rather than overwriting silently.
+ registry
+ .external
+ .entry(descriptor.public_name.clone())
+ .or_insert_with(|| descriptor.clone());
+ }
+ registry
+ }
+
+ /// Look up a builtin by canonical name or alias.
+ pub fn builtin(&self, name: &str) -> Option<&CallableDescriptor> {
+ self.builtins.get(name)
+ }
+
+ /// Look up an ABI export by complete dotted name.
+ pub fn external(&self, name: &str) -> Option<&CallableDescriptor> {
+ self.external.get(name)
+ }
+
+ /// Look up a function in a module by canonical name, then unique local name.
+ pub fn function(&self, module: &ModuleId, name: &str) -> Option<&CallableDescriptor> {
+ let table = self.functions.get(module)?;
+ table.get(name)
+ }
+
+ /// Iterate external descriptors deterministically.
+ pub fn externals(&self) -> impl Iterator- {
+ self.external.values()
+ }
+
+ /// Insert an external descriptor, rejecting duplicate public names.
+ pub fn insert_external(&mut self, descriptor: CallableDescriptor) -> Result<(), String> {
+ if self.builtins.contains_key(&descriptor.public_name) {
+ return Err(format!(
+ "external callable `{}` conflicts with a builtin",
+ descriptor.public_name
+ ));
+ }
+ if self.external.contains_key(&descriptor.public_name) {
+ return Err(format!(
+ "external callable `{}` is declared more than once",
+ descriptor.public_name
+ ));
+ }
+ self.external
+ .insert(descriptor.public_name.clone(), descriptor);
+ Ok(())
+ }
+
+ fn add_builtins(&mut self) {
+ for builtin in builtins::BUILTINS {
+ let descriptor = builtin_descriptor(builtin);
+ self.builtins
+ .insert(builtin.name.to_string(), descriptor.clone());
+ for alias in builtin.aliases {
+ self.builtins
+ .insert((*alias).to_string(), descriptor.clone());
+ }
+ }
+ }
+
+ fn add_module(&mut self, module: &Module) {
+ let mut table = BTreeMap::new();
+ for function in &module.functions {
+ let descriptor = function_descriptor(module, function);
+ table.insert(function.id.name.clone(), descriptor.clone());
+ }
+ // A local name is only a stable key when it is unique in the module.
+ for function in &module.functions {
+ let local_matches = module
+ .functions
+ .iter()
+ .filter(|candidate| candidate.local_name == function.local_name)
+ .count();
+ if local_matches == 1 {
+ if let Some(descriptor) = table.get(&function.id.name).cloned() {
+ table
+ .entry(function.local_name.clone())
+ .or_insert(descriptor);
+ }
+ }
+ }
+ self.functions.insert(module.id.clone(), table);
+ }
+}
+
+fn builtin_descriptor(builtin: &builtins::Builtin) -> CallableDescriptor {
+ CallableDescriptor {
+ id: CallableId(format!("builtin:{}", builtin.name)),
+ public_name: builtin.name.to_string(),
+ owner_package: "core".to_string(),
+ signature: CallableSignature {
+ params: builtin
+ .params
+ .iter()
+ .map(|param| Param {
+ name: param.name.to_string(),
+ span: Span::default(),
+ type_annotation: None,
+ default: None,
+ })
+ .collect(),
+ kind: SignatureKind::Explicit,
+ },
+ effects_requested: if builtin.effectful {
+ vec!["host".to_string()]
+ } else {
+ Vec::new()
+ },
+ origin: CallableOrigin::Builtin,
+ implementation_digest: None,
+ source_span: None,
+ }
+}
+
+fn function_descriptor(module: &Module, function: &Function) -> CallableDescriptor {
+ CallableDescriptor {
+ id: CallableId(format!("marqdo:{}", function.id)),
+ public_name: function.id.name.clone(),
+ owner_package: module.id.instance.clone(),
+ signature: CallableSignature {
+ params: function.params.clone(),
+ kind: function.signature,
+ },
+ effects_requested: vec!["unknown".to_string()],
+ origin: CallableOrigin::Marqdo,
+ implementation_digest: None,
+ source_span: Some(function.heading_span),
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use crate::Module;
+
+ fn empty_module(id: &str) -> Module {
+ Module {
+ id: ModuleId::from(id),
+ units: Vec::new(),
+ functions: Vec::new(),
+ imports: Vec::new(),
+ resources: Vec::new(),
+ anchors: BTreeMap::new(),
+ }
+ }
+
+ #[test]
+ fn builtins_are_registered_with_aliases() {
+ let registry = CallableRegistry::for_module(&empty_module("index.mq.md"));
+ assert_eq!(registry.builtin("print").unwrap().id.0, "builtin:打印");
+ assert_eq!(registry.builtin("打印").unwrap().id.0, "builtin:打印");
+ assert!(registry.builtin("nope").is_none());
+ assert!(registry
+ .builtin("print")
+ .unwrap()
+ .effects_requested
+ .contains(&"host".to_string()));
+ }
+
+ #[test]
+ fn external_names_must_be_unique_and_not_shadow_builtins() {
+ let mut registry = CallableRegistry::for_module(&empty_module("index.mq.md"));
+ let descriptor = CallableDescriptor {
+ id: CallableId("plugin:demo:solver.add".into()),
+ public_name: "solver.add".into(),
+ owner_package: "demo".into(),
+ signature: CallableSignature {
+ params: Vec::new(),
+ kind: SignatureKind::Explicit,
+ },
+ effects_requested: Vec::new(),
+ origin: CallableOrigin::AbiPlugin {
+ package: "demo".into(),
+ export: "solver.add".into(),
+ },
+ implementation_digest: None,
+ source_span: None,
+ };
+ registry.insert_external(descriptor.clone()).unwrap();
+ assert!(registry.insert_external(descriptor).is_err());
+ let mut shadow = CallableDescriptor {
+ id: CallableId("plugin:demo:print".into()),
+ public_name: "print".into(),
+ owner_package: "demo".into(),
+ signature: CallableSignature {
+ params: Vec::new(),
+ kind: SignatureKind::Explicit,
+ },
+ effects_requested: Vec::new(),
+ origin: CallableOrigin::AbiPlugin {
+ package: "demo".into(),
+ export: "print".into(),
+ },
+ implementation_digest: None,
+ source_span: None,
+ };
+ shadow.public_name = "print".into();
+ assert!(registry.insert_external(shadow).is_err());
+ }
+}
diff --git a/crates/marqdo-ir/src/lib.rs b/crates/marqdo-ir/src/lib.rs
index e7c7930..aa8ab5f 100644
--- a/crates/marqdo-ir/src/lib.rs
+++ b/crates/marqdo-ir/src/lib.rs
@@ -17,6 +17,7 @@ use marqdo_span::Span;
use serde::{Deserialize, Serialize};
pub mod builtins;
+pub mod callable;
/// Canonical logical identity of a module: package instance plus a path
/// relative to that package's module root.
@@ -477,6 +478,10 @@ pub struct Program {
/// Resolved import edges.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub resolved_imports: Vec,
+ /// Explicit external callable descriptors (plugin manifests). They are
+ /// metadata only: `check` never loads a library.
+ #[serde(default, skip_serializing_if = "Vec::is_empty")]
+ pub external_callables: Vec,
}
impl Program {
@@ -502,6 +507,18 @@ impl Program {
.find(|edge| &edge.from == from && edge.alias == alias)
.map(|edge| &edge.to)
}
+
+ /// Static external callable descriptor by complete dotted name.
+ pub fn external_callable(&self, name: &str) -> Option<&callable::CallableDescriptor> {
+ self.external_callables
+ .iter()
+ .find(|descriptor| descriptor.public_name == name)
+ }
+
+ /// Build the unified callable registry for this program.
+ pub fn callable_registry(&self) -> callable::CallableRegistry {
+ callable::CallableRegistry::from_program(self)
+ }
}
#[cfg(test)]
diff --git a/docs/STATUS.md b/docs/STATUS.md
index 79e7a22..cb6d6d7 100644
--- a/docs/STATUS.md
+++ b/docs/STATUS.md
@@ -40,7 +40,7 @@ providers).
| Step | State | Evidence |
|---|---|---|
| R0 baseline + ADRs | **Done** | this section; `docs/adr/0008`–`0012`; full workspace gate |
-| R1 package-aware identity | **In progress** | `ModuleId { instance, relative_path }`; `PackageResolver` path sources; `lock_version: 2` with v1 migration; tests in `marqdo-package` |
+| R1 package-aware identity + callable registry | **Done for statics** | `ModuleId { instance, relative_path }`; `PackageResolver` path sources; `lock_version: 2` with v1 migration; `CallableRegistry` for builtins/marqdo/declared ABI exports; external manifest wiring is R2 |
| R2 ABI/Kernel/Broker | Not started | — |
| R3 Tool Protocol | Not started | — |
| R4 Analysis/Trace v1 | Not started | — |