- 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
6.0 KiB
ADR-0056: Explicit extension selection and lock v4
- Status: Accepted (2026-11-21)
- Implements: RFC-EXT-0001 §6 (PR-04)
- Related: ADR-0008/0016/0039, ADR-0054/0055/0057/0058
Context
marqdo-package already locks a reproducible package-instance graph (path and
pinned Git sources) and materializes it under .marqdo/env. Extensions had no
equivalent: plugin/provider/kernel paths were only accepted as repeatable CLI
flags (--plugin, --kernel, --provider). An independent repository could
therefore publish a .mq.md package and a callable/extension artifact, but a
consumer could not record which exact manifest/artifact the project selected,
and a project manifest could not declare activation sources at all.
Copying CLI paths on every run makes deployments non-reproducible and invites a second, hidden package manager. The existing lock is the right place, but its v3 schema has no extension identity.
Decision
1. marqdo.yaml.extensions declares activation sources, never grants
extensions:
plugins:
- from: ./adapter/plugin.yaml
kernels: []
providers:
- from: "@quantum/adapter/provider.json"
Only two from forms exist:
./relative/pathinside the project;@alias/relative/pathinside a declared dependency in the same fixed package graph.
Absolute paths, URLs, globs, .. traversal and implicit discovery are rejected
at manifest validation; the resolved file must be a regular file inside its
owning package. A declaration means "this project activates this extension" —
it never means permission: --allow-plugin/--allow-provider/--allow-foreign
and the capability broker remain separate. pure/strict refuse to activate
project-declared extensions.
CLI flags remain supported as an explicit temporary/dev selection. Selection is
deduplicated by canonical path; the same manifest selected from the project
and the CLI is idempotent, while two different manifests for one package
identity are a deterministic ext.duplicate_callable error.
2. Lock v4 records extension identity
marqdo.lock becomes lock_version: 4. The package-instance graph is
unchanged; a new extensions: array records, per selected source:
- kind: plugin # plugin | kernel | provider
logical_owner: root:example@0.1.0
name: demo.solver
version: 0.1.0
manifest_digest: <sha256 of exact manifest/descriptor bytes>
artifact_digest: <selected target artifact sha256; kernel executable digest>
selected_target: x86_64-unknown-linux-gnu
source: ./adapter/plugin.yaml
The array is sorted by (kind, name, logical_owner). Duplicate identities or
duplicate sources are rejected. manifest_digest/artifact_digest are
integrity values, not publisher authentication; a release signature/trust
root is separate work.
3. Explicit migration, no silent reinterpretation
LockFile::from_yaml of a v3 document returns a deterministic error: lock v3 is
superseded by v4 (extension identities), run marqdo lock to migrate. v1/v2
keep their relock error but now name v4. run/check/sync never rewrite the
lock and never fetch a floating revision.
4. Who verifies what
| Stage | Behaviour |
|---|---|
marqdo lock |
Resolves declared from sources statically, reads manifests and declared artifact digests, writes v4. No extension binary is loaded or executed. |
check |
Loads project + static descriptors and compares declared identities with the lock (ext.extension_lock_mismatch on missing/extra/changed). Never starts a worker; a missing artifact is not fatal for a pure static check. |
sync |
Re-validates declarations against the lock before materializing package content. |
run/call |
Re-verifies the actual artifact bytes/hashes for selected plugins/providers (and the kernel executable) before spawning/loading anything; exact grants are still required. |
inspect --extensions |
Projects declared sources, lock identity, static plugin descriptors and official stdlib aliases; authorization is always not_granted and inspection never executes. |
5. Selection priority and conflicts
- Project declaration (locked) and explicit CLI selection are merged by canonical path; identical identity is idempotent.
- Same package/kernel/provider logical identity with different manifest digest
or artifact digest is an error; no
last wins, no auto-suffix. - Extension logical owners are recorded as package instance ids (root or dependency), so moving the cache/checkout does not change identity.
- A dependency extension cannot escape its package root (
@alias/../is rejected; canonical path must stay under the package root). - Multi-version dependencies remain distinguishable by package instance + alias; the lock records the exact owner.
Consequences
- Third-party
.mq.md/plugin/kernel/provider repositories can publish into a project with a reproducible, auditable selection; checkstays side-effect free while still validating extension identity;- pre-existing projects migrate with one
marqdo lock; their v3 lock is not silently accepted; - the existing package graph, Git pinning, strict
syncand env materialization are unchanged apart from the version bump and new section; - no package registry, network discovery or automatic extension installation is introduced.
Rejected alternatives
- Keep extensions CLI-only. Rejected: projects cannot reproduce/audit the
selection, and
checkcannot validate it. - Put extension paths in the existing
plugins:requirement map. Rejected: it is a version requirement, not a runnable artifact identity, and mixing them would make manifests ambiguous. - Add fields to lock v3 without bumping the version. Rejected by RFC-EXT-0001 §6.3 and the repository's public-lock rule.
- Let extensions be discovered from directories, PATH or an HTTP index. Rejected: implicit discovery is non-deterministic and un-auditable.
- Auto-grant from a manifest declaration. Rejected: selection is not authorization (ADR-0054/0055).