- marqdo.yaml.extensions accepts only ./path or @alias/path, resolves to a regular file inside its owning package, never grants - lock_version 4 records plugin/kernel/provider manifest+artifact identity; v3 requires explicit 'marqdo lock' migration; sync/check/run compare identity - check stays static; run re-verifies artifact bytes; pure/strict refuse - inspect --extensions reports declared/locked identity, plugin descriptors and stdlib aliases with authorization 'not_granted' - black-box extension_selection suite (13) + package-layer tests; specs/ADR-0056 - workspace gate: fmt/clippy clean, 599 passed across 67 targets
7.8 KiB
Marqdo extension selection and lock v4
Status: implemented (RFC-EXT-0001 §6, ADR-0056). This is the normative
contract for marqdo.yaml.extensions, marqdo.lock extension identities, and
how lock/sync/check/run/inspect treat them.
1. Scope
An extension is one of:
| Kind | Manifest/descriptor | Execution form |
|---|---|---|
plugin |
plugin.yaml (Plugin ABI v1) |
native/worker callable plugin |
kernel |
kernel.json (Foreign wire v1) |
one-shot child process |
provider |
provider.json (Resource Provider v2) |
worker helper + C ABI library |
Extension selection is distinct from extension authorization: selecting a
manifest makes its names visible and allows run to consider it. It never
creates a grant, loads a library, starts a worker or executes a script. Actual
permissions are the CLI grants plus the capability broker at the effect site.
2. Project manifest
extensions:
plugins:
- from: ./adapter/plugin.yaml
kernels:
- from: "@quantum/adapter/kernel.json"
providers:
- from: "@quantum/adapter/provider.json"
Rules:
fromis exactly one of:./relative/path— below the project root;@alias/relative/path— below a dependency declared independenciesin the same project.
- Absolute/rooted paths,
http(s)://URLs, globs, empty strings,.-only paths and anyParentDir(..) component are rejected. The alias must exist independencies. - The resolved path must be a regular file whose canonical form stays inside its owning package root (project root or dependency package root). Symlink escapes are rejected.
- Duplicate
(kind, from)entries are rejected. - A dependency's extension file is identified by the dependency package
instance id (
dep:name@version#content-digest), never by a physical cache path. - Unknown YAML fields are ignored by the parser, but they never imply execution or authorization.
The existing plugins: block is a version requirement and is not a
runnable artifact; it remains declarative only.
3. Lock v4
lock_version: 4
content_profile_version: 1
root:
package: root:example@0.1.0
manifest_digest: <64 hex>
packages: []
root_dependencies: {}
extensions:
- kind: plugin
logical_owner: root:example@0.1.0
name: demo.solver
version: 0.1.0
manifest_digest: <64 hex>
artifact_digest: <64 hex>
selected_target: x86_64-unknown-linux-gnu
source: ./adapter/plugin.yaml
| Field | Rule |
|---|---|
kind |
plugin | kernel | provider; unknown values are rejected |
logical_owner |
non-empty package instance id, root or dependency |
name |
stable declared name; for a kernel, provider_id |
version |
declared SemVer/string; a kernel has no version field, so wire:<n> |
manifest_digest |
SHA-256 of the exact manifest/descriptor bytes (lowercase hex) |
artifact_digest |
declared selected-target artifact SHA-256; for a kernel the pinned provider executable digest |
selected_target |
host target triple selected at lock time |
source |
from string exactly as declared |
- Extensions are sorted by
(kind, name, logical_owner); the whole array is omitted when empty. - Duplicate
(kind, name, logical_owner)or duplicate(kind, source)is an error. manifest_digest/artifact_digestare integrity values. They are not signatures and do not establish publisher identity.- Lock v3 is rejected with an explicit migration message; run
marqdo lock. No v3 field is reinterpreted as v4 and the lock is not rewritten implicitly.
4. Stage behaviour
4.1 marqdo lock
- Resolves the package graph as before.
- Resolves every
extensionssource to a canonical regular file. - Reads each manifest/descriptor statically and computes the identity above.
- Rejects missing files, malformed manifests, unsupported provider/kernel schema versions, missing current-target artifacts and duplicate identities.
- Writes lock v4 atomically. It never loads a shared library, starts a helper or executes a kernel.
4.2 marqdo sync [--locked]
- Loads and validates the lock (v3 → explicit migration error).
- Resolves the current declared sources and computes their identities.
- Compares the declared selection with the lock (same rules as §4.3).
--lockedforbids fetching; any lock/graph mismatch is fail-closed.
sync materializes package content but does not authorize or execute an
extension binary.
4.3 marqdo check
check:
- loads sources, static manifests and the lock;
- compares declared extension identity with the lock and fails with
ext.extension_lock_mismatchon a missing/extra/changed identity; - may read manifests and declared digests, but never loads a plugin library, starts a provider worker, spawns a foreign kernel or runs a side-effect script;
- does not require a plugin/provider/kernel artifact file to exist for the
static check path (execution-artifact verification belongs to
run).
4.4 marqdo run / marqdo call
Before the entry function runs:
prepareperforms the same static binding and lock comparison ascheck.- The merged selection (project declaration + explicit CLI flags) determines which plugin/provider/kernel descriptors are considered.
- Real artifact bytes/hashes, bundle containment, target and exact grants are verified before any worker/library/kernel is started.
- A failed verification produces a structured
ext.*error and the main function does not run. There is no fallback to "latest", PATH discovery or a trusted in-process native provider.
--mode pure and --mode strict reject project-declared extension activation
(cli.invalid_grants / strict.unsupported_grant) before any extension is
used.
5. Selection priority and conflicts
- Project declaration and CLI selection are merged and deduplicated by canonical path.
- Identical logical identity + digests is idempotent.
- Same package/kernel/provider logical identity with different manifest or
artifact digest is
ext.duplicate_callable(prepare) — never last-wins and never auto-suffixed. - Two providers declaring the same resource kind is
ext.duplicate_provider_kind(before spawn). - Ordering of CLI flags and YAML entries never decides which implementation is used.
6. inspect --extensions
inspect FILE --extensions [--json] [--plugin PATH] prints:
- declared sources with
kind,source, package-relativepath, logical owner and resolution status (locked/unlocked); - the locked identity fields when available;
- static plugin descriptors (package/version/kind/target/artifact digest/
manifest digest/exports), validation
static_manifest_ok; - official stdlib public aliases (
stdlib_aliases) with the verified target.
Authorization is reported as not_granted; inspection never grants, loads or
executes anything. Environment variables, secrets and binary contents are never
printed.
7. Diagnostics
| Code | Stage | Trigger |
|---|---|---|
ext.extension_lock_mismatch |
prepare/sync | declared selection missing from lock, extra locked extension, changed manifest/artifact identity, or extensions declared without a lock |
ext.duplicate_callable |
prepare | two different manifests for one package identity, or duplicate callable names |
ext.duplicate_provider_kind |
prepare/run init | two providers declare the same resource kind |
ext.no_matching_artifact |
identity/manifest read | no artifact for the current target |
ext.artifact_integrity |
run init | artifact bytes/hash/containment mismatch |
project.lock |
load | lock v3/older version, malformed lock |
project.manifest |
load | invalid extensions source form, missing file, alias not declared |
Exit codes follow the CLI convention: manifest/option errors are 2, load/
verify/runtime errors are 1; check exit code is 1 on any compile/load
error, 0 on success.