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

127 lines
6.0 KiB
Markdown

# 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
```yaml
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:
```yaml
- 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).