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

6.4 KiB

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

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>"
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/callable-resolution.md.

2. Foreign kernels

{
  "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"
}
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.

3. Resource providers v2

{
  "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": []
}
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.

4. Reproducible selection: extensions + lock v4

Declare activation sources in the project manifest:

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.

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.

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; the core's evidence generator is tools/ci/verify_extension_contracts.py.