Files
marqdo-cli/docs/adr/0012-external-kernel-provider.md
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.6 KiB

ADR-0012: External foreign-kernel providers

Status: Accepted Date: 2026-11-20

Context

marqdo-foreign hard-codes SUPPORTED_LANGUAGES = ["python", "javascript"] and normalize_language/program_candidates branch on those names. Adding R, Julia or SQL requires changing the crate and shipping a new interpreter even though foreign kernels are optional, externally installed programs.

The M0.6 plan (E05, R2) requires a provider registry. A provider is an execution kernel for an inert Code value, not a CLI Tool and not a C ABI plugin.

Decision

1. Descriptor and protocol

pub struct KernelDescriptor {
    pub provider_id: String,       // `python`, `javascript`, `mocklang`
    pub languages: Vec<String>,    // accepted code-fence labels/aliases
    pub wire_version: u32,         // 1 for the current typed JSON envelope
    pub entrypoint: PathBuf,       // trusted provider executable/script path
    pub digest: Option<String>,    // content digest of the provider program
    pub permissions_requested: Vec<String>,
}

Providers implement the existing foreign wire protocol: one request envelope on stdin, stdout must be exactly one typed wire value for call, stderr and a non-zero exit are errors. A provider receives no secret environment beyond PATH unless explicitly granted.

2. Registry

marqdo_foreign::KernelRegistry is constructed by the host/CLI:

  • built-in providers are registered for python/python3/py and javascript/js/node/nodejs with their existing one-shot command lines;
  • additional providers come from an explicit, versioned kernel.json descriptor (or a future marqdo.yaml kernel section);
  • registration is static, explicit and user-controlled; no PATH scan for arbitrary providers and no automatic download.

Lookup happens only when foreign.run/foreign.call is explicitly invoked. Parsing/rendering a python/r/unknown fence always yields an inert Code value; an unregistered label is legal until execution, then kernel.unavailable.

3. Isolation and authorization

A provider process is a foreign kernel, never the Marqdo interpreter. Spawning requires allow_foreign (or an explicit kernel grant). The host applies timeout, output cap, process-tree cleanup and environment clearing as today. A provider descriptor's permissions_requested is advisory and cannot grant filesystem/network access; any such access must be implemented by the provider inside the same OS-level limits as other foreign processes.

Tool Protocol is deliberately separate: a CLI Tool is a user-invoked native program; a Kernel Provider executes code requested by an .mq.md program. They do not share registries or trust decisions.

4. Versioning

wire_version must equal the host's supported version (1) or execution fails with kernel.wire_version. The language labels are case-insensitive and trimmed; duplicate labels across providers are a registration conflict. The existing Python/Node detection remains as the built-in provider implementation, not a special case in the call path.

Alternatives

  1. Keep the hard-coded language list. Rejected by E05.
  2. Let a provider be any executable found on PATH by language name. Rejected: PATH hijacking and implicit execution.
  3. Reuse the C ABI plugin manifest. Rejected: different trust model, lifecycle and wire protocol.
  4. Execute unknown languages via a generic shell. Rejected: no explicit provider, no deterministic protocol, no capability boundary.

Compatibility

foreign.run/call keep their names and wire protocol. Existing Python/Node programs behave the same. Unknown labels remain inert values; only an explicit call errors. A future registry source can add providers without changing the interpreter.

Security

A provider is untrusted code by default. The host does not treat a descriptor as a sandbox; it applies the same child-process limits and explicit grant. A descriptor cannot grant itself core capabilities, and a tool cannot become a kernel provider implicitly.

Testing

  • register mocklang without changing marqdo-foreign and execute a typed call, with timeout/output-limit/denial cases;
  • unregistered label yields kernel.unavailable only on call;
  • duplicate language labels and wire-version mismatch are rejected;
  • built-in Python/Node tests continue to pass when the interpreters exist.

Migration & rollout

R2 introduces the registry and converts Python/Node to built-in descriptors. R5 may add a declarative kernel section to project/environment sync. No new CLI top-level command is added; execution still goes through run/call.