Files
marqdo-cli/docs/adr/0056-extension-selection-locking.md
T
cflmy 89555382e0 feat(ext): extension selection + lock v4, inspect --extensions (RFC-EXT-0001 PR-04)
- 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
2026-11-22 00:43:18 +08:00

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/path inside the project;
  • @alias/relative/path inside 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

  1. Project declaration (locked) and explicit CLI selection are merged by canonical path; identical identity is idempotent.
  2. Same package/kernel/provider logical identity with different manifest digest or artifact digest is an error; no last wins, no auto-suffix.
  3. Extension logical owners are recorded as package instance ids (root or dependency), so moving the cache/checkout does not change identity.
  4. A dependency extension cannot escape its package root (@alias/../ is rejected; canonical path must stay under the package root).
  5. 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;
  • check stays 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 sync and 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 check cannot 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).