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

112 lines
4.6 KiB
Markdown

# 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
```rust
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`.