Files
marqdo-cli/docs/adr/0010-plugin-export-registration.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

4.3 KiB

ADR-0010: Register every plugin export by its complete name

Status: Accepted Date: 2026-11-20

Context

crates/marqdo-host/src/host.rs::load_plugin binds one PluginSlot using manifest.plugin.exports.first(). The namespace is the text before the first . and op_plugin_invoke looks it up with find(namespace). Consequences:

  • a plugin exporting solver.add and graph.search can only be reached through one of the two prefixes;
  • two plugins declaring the same prefix race, and whichever slot was pushed first wins;
  • the frontend has no per-export identity to validate, and a call is effectively "first namespace match".

The M0.6 audit E03 and plan §10 require complete-name registration for every export.

Decision

1. Export registration

StdHost keeps a registry keyed by the complete export name:

struct PluginExport {
    export: String,             // `solver.add`
    package: String,            // `qdqc.solver`
    manifest_digest: String,    // sha256 of the canonical manifest/artifact metadata
    signature: CallableSignature,
    effects: Vec<String>,
    plugin: Rc<LoadedPlugin>,   // shared by all exports of one loaded library
}

Loading a plugin validates the manifest, loads the library once and inserts one entry per export. Insertion is atomic for the whole manifest: if any export is already registered with a different package/manifest, loading fails and the previous registry state is unchanged. A re-load of the identical package+manifest may reuse the existing library.

There is no exports.first() and no namespace-only lookup. A call uses the complete dotted name from CallableId / the IR call site.

2. Aliases

If two packages intentionally provide the same export name, the user must declare an explicit alias in the importing manifest/front matter (for example solver.add as fast.add) or the call is ambiguous. M0.6 may implement only the hard-conflict diagnostic; the alias syntax is additive and must not silently choose a winner.

3. Runtime binding

The frontend resolves solver.add to a CallableDescriptor (ADR-0009) and the runtime passes the CallableId to the host. The host looks up exactly that id; it never re-resolves a bare namespace.

The static descriptor must include the manifest/artifact digest so a call checked against one plugin version is rejected if the installed library changed between check and run.

4. Worker parity

The isolated worker transport (R2) registers the same complete export names and the same descriptor table. A plugin's routing must not depend on whether it is loaded natively or in a worker.

Alternatives

  1. Keep one namespace per plugin and require authors to use one prefix. Rejected: the manifest already permits multiple namespaced exports and the audit found silently unreachable functions.
  2. Let the host pick the first matching namespace. Rejected: nondeterministic and spoofable.
  3. Reject duplicate export prefixes at manifest validation. Rejected: this forbids legitimate multi-package ecosystems and does not solve identical names across different packages.

Compatibility

Existing single-namespace plugins continue to work; their export is registered by complete name. Calls that previously relied on "first prefix" behavior now require the exact export name. No C ABI layout change is needed for native loading. The host's public load_plugin return value becomes a summary of all registered exports rather than one namespace.

Security

Registration is not authorization. The manifest digest is recorded so callers can reject a swapped binary. Capability grants remain per plugin package and are checked on each invocation (ADR-0011). A conflicting export never replaces an existing registration.

Testing

  • one plugin with solver.add + graph.search can call both;
  • two plugins exporting solver.add produce a deterministic conflict and do not overwrite;
  • a plugin manifest with duplicate export names is rejected during validation;
  • a manifest artifact digest mismatch is rejected at load and at call binding;
  • worker and native transports expose the same complete-name table.

Migration & rollout

R2 implements complete-name registration together with the worker transport. spec/plugin-abi.md is updated; the old namespace helper is removed after the new tests pass.