Files
marqdo-cli/docs/developers/extensions.md
T
cflmy 2c7c4f31e7
Linux strict security lane (G-C) / strict isolation escape matrix (push) Waiting to run
ci/woodpecker/push/main Pipeline was successful
ci/woodpecker/manual/performance Pipeline was successful
CI / fmt + clippy + test (Linux x86_64) (push) Waiting to run
CI / schema instance validation + consumers (push) Waiting to run
CI / runtime contract (macos-latest) (push) Waiting to run
CI / runtime contract (windows-latest) (push) Waiting to run
release(3.0.0-beta.1): product version migration, beta gates, archive tooling and developer docs
REL-01: workspace/CLI/Analysis product version 3.0.0-beta.1 with updated
Cargo.lock; project.marqdo is enforced against the running core with
package.marqdo_range_invalid/package.marqdo_incompatible fail-closed
diagnostics; Tool SemVer prerelease negotiation tests; init template and
examples use the beta range. Verify init derives the project name from the
target directory instead of falling back to 'example'.

REL-02: beta support matrix is Linux x86_64 only; macOS/Windows are explicitly
experimental/unclaimed; strict policy and G4 Beta-only WARN are documented for
the release evidence.

REL-03: deterministic release packaging (tools/release/package.py) ships the
CLI and provider worker together with SOURCE_SHA, RELEASE_INFO.json,
known-limitations, specs, developer docs, examples incl. built plugin/provider
artifacts and consumers; tools/release/smoke.py cold-install tests the archive.

REL-04: docs/developers entry pages; corrected and self-contained third-party
integration handbook; stale Proposed/native-only/informational spec claims
fixed; release/status/compatibility/changelog/releasing docs updated.

REL-05: release_evidence.py gains an explicit beta profile
(BETA_RELEASE_CANDIDATE) distinct from the stable profile; Woodpecker build
step now packages and smoke-tests the archive on every pipeline.

Adds a runnable Resource Provider v2 example and corrects check --emit to
Analysis v2.
2026-11-22 02:31:32 +08:00

166 lines
6.4 KiB
Markdown

# Plugins, foreign kernels, resource providers and lock v4
Three independent extension kinds share one principle: **selection is not
authorization**. A manifest makes a name visible; the user still grants the
exact name or flag at run time. None of these extensions may add a language
keyword or a built-in function to the core.
| Kind | Descriptor | Execution form | Authorization |
|---|---|---|---|
| Callable plugin | `plugin.yaml` (Plugin ABI v1) | native in-process **only with trust**, or worker child process | `--plugin PATH` + `--allow-plugin NAME` (+ `--trust-native-plugin` for native) |
| Foreign kernel | `kernel.json` (Foreign wire v1) | one-shot child process | `--kernel PATH` + `--allow-foreign` |
| Resource provider | `provider.json` (Provider manifest v2) | `marqdo-provider-worker` + C ABI v1 library in a child process | `--provider PATH` + `--allow-provider NAME` |
`pure` and `strict` refuse all three. Worker/child-process transports are crash
isolation, **not** OS sandboxes; a C ABI is not a sandbox.
## 1. Callable plugins
```yaml
plugin:
name: demo.solver
version: 0.1.0 # plugin package version (independent axis)
abi: "^1.0" # Plugin ABI major 1
kind: worker # native | worker; wasm is rejected
exports:
- name: solver.add
signature: "($a: Int, $b: Int) -> Int"
requires:
- math.compute
artifacts:
- target: x86_64-unknown-linux-gnu
file: libsolver.so
sha256: "<64 lowercase hex of the actual artifact>"
```
```bash
marqdo plugin inspect path/to/plugin.yaml # static; never loads the library
marqdo check index.mq.md --plugin path/to/plugin.yaml
marqdo run index.mq.md --plugin path/to/plugin.yaml --allow-plugin demo.solver
```
- `check --plugin` validates the manifest and export signatures without loading
the artifact; `run` verifies target triple, file SHA-256, grant, and then
reconciles loaded exports/signatures/owners/digests one-to-one with the
manifest (`ext.plugin_binding_mismatch` on any difference).
- Calls use named arguments; positional arguments are normalised to manifest
order but ABI v1 configuration defaults are rejected.
- `kind: native` shares the host address space and can crash or compromise it;
it requires the explicit unsafe `--trust-native-plugin`. `kind: worker` runs
the same library in a child process with framed JSON and timeouts; the C ABI
header/SDK is `include/marqdo_plugin_abi_v1.h` and `crates/marqdo-plugin-sdk`.
- A runnable host-built example is `examples/plugin-demo/` (native) and its
generated manifest; the release archive includes the built artifact.
- Normative contract: [`../../spec/plugin-abi.md`](../../spec/plugin-abi.md),
[`../../spec/callable-resolution.md`](../../spec/callable-resolution.md).
## 2. Foreign kernels
```json
{
"provider_id": "mocklang",
"languages": ["mocklang", "mock"],
"wire_version": 1,
"entrypoint": "./mocklang",
"permissions_requested": [],
"digest": "<sha256 of the executable/environment artifact>",
"environment_id": "mocklang-env-1"
}
```
```bash
marqdo run demo.mq.md --kernel path/to/kernel.json --allow-foreign
```
Fenced `Code` and `Formula` values are inert; the program must call
`foreign.run`/`foreign.call` explicitly. The host refuses unauthorized
execution, digest mismatch, unexpected exit, timeout and an incompatible wire
version. Add a language tag by writing a provider, not by adding an
`if language == …` branch to the core. Example:
`examples/kernel-mock/`. Normative contract:
[`../../spec/foreign.md`](../../spec/foreign.md).
## 3. Resource providers v2
```json
{
"schema": "marqdo.provider",
"schema_version": 2,
"name": "demo.sensor",
"version": "0.1.0",
"abi": "c-abi-1",
"transport": "worker",
"kinds": ["demo.sensor"],
"artifacts": [{
"target": "x86_64-unknown-linux-gnu",
"path": "lib/libsensor.so",
"sha256": "<64 lowercase hex>"
}],
"permissions_requested": []
}
```
```bash
marqdo run demo.mq.md \
--provider path/to/provider.json \
--allow-provider demo.sensor
```
The program still uses the ordinary language surface
`resource.open("demo.sensor", "unit-1", ["read"])` plus
`resource.read/write/close` and `Memory` for bytes. There is no provider-specific
keyword or built-in. The selected provider is verified (schema version, target,
artifact SHA-256, duplicate kind, grant) before the sibling
`marqdo-provider-worker` starts; a missing helper is
`ext.worker_unavailable` and never falls back to `PATH` or in-process loading.
Linux x86_64 only for this beta; not an OS sandbox. Runnable example:
`examples/provider-demo/` (build with its `build.sh`; the tracked manifest has a
zero digest template). Normative contract:
[`../../spec/resource-provider-v2.md`](../../spec/resource-provider-v2.md).
## 4. Reproducible selection: `extensions` + lock v4
Declare activation sources in the project manifest:
```yaml
extensions:
plugins:
- from: ./adapter/plugin.yaml
kernels: []
providers:
- from: "@vendor/device/provider.json"
```
`from` is exactly `./relative/path` inside the project or
`@alias/relative/path` inside a declared dependency. Absolute/rooted paths,
URLs, globs, `..`, symlink escapes and duplicate entries are rejected; the
alias must exist in `dependencies`.
```bash
marqdo lock
marqdo inspect index.mq.md --extensions --json # identities + lock status; no execution
```
`lock` records manifest and artifact identities (including the selected target)
in lock v4. `check`/`sync` compare the declaration to the lock
(`ext.extension_lock_mismatch`), and `run` re-verifies the real artifact bytes
before starting a worker. Lock v3 gets an explicit `marqdo lock` migration error.
Normative contract:
[`../../spec/extension-selection.md`](../../spec/extension-selection.md).
## 5. Frozen-binary test matrix
Your external repository must pass with an unchanged CLI binary:
- positive: pinned pure library; plugin under correct grant; kernel under
`--allow-foreign`; provider under `--allow-provider`; extension selection
locked and re-verified;
- negative: wrong export/arity, duplicate export, missing/edited artifact,
digest or target mismatch, missing helper, unauthorized grant, wrong lock
version, unknown schema major, worker crash/timeout — all must fail with
their documented diagnostics and no silent fallback.
The reference suite is
[`marqdo-extension-conformance`](https://git.cflmy.cn/cflmy/marqdo-extension-conformance);
the core's evidence generator is `tools/ci/verify_extension_contracts.py`.