- 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)
112 lines
4.6 KiB
Markdown
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`.
|