Files
marqdo-cli/spec/extension-selection.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

192 lines
7.8 KiB
Markdown

# 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
```yaml
extensions:
plugins:
- from: ./adapter/plugin.yaml
kernels:
- from: "@quantum/adapter/kernel.json"
providers:
- from: "@quantum/adapter/provider.json"
```
Rules:
1. `from` is exactly one of:
* `./relative/path` — below the project root;
* `@alias/relative/path` — below a dependency declared in
`dependencies` in the same project.
2. Absolute/rooted paths, `http(s)://` URLs, globs, empty strings, `.`-only
paths and any `ParentDir` (`..`) component are rejected. The alias must
exist in `dependencies`.
3. 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.
4. Duplicate `(kind, from)` entries are rejected.
5. A dependency's extension file is identified by the dependency package
instance id (`dep:name@version#content-digest`), never by a physical cache
path.
6. 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
```yaml
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_digest` are 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`
1. Resolves the package graph as before.
2. Resolves every `extensions` source to a canonical regular file.
3. Reads each manifest/descriptor statically and computes the identity above.
4. Rejects missing files, malformed manifests, unsupported provider/kernel
schema versions, missing current-target artifacts and duplicate identities.
5. Writes lock v4 atomically. It never loads a shared library, starts a helper
or executes a kernel.
### 4.2 `marqdo sync [--locked]`
1. Loads and validates the lock (v3 → explicit migration error).
2. Resolves the current declared sources and computes their identities.
3. Compares the declared selection with the lock (same rules as §4.3).
4. `--locked` forbids 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_mismatch` on 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:
1. `prepare` performs the same static binding and lock comparison as `check`.
2. The merged selection (project declaration + explicit CLI flags) determines
which plugin/provider/kernel descriptors are considered.
3. Real artifact bytes/hashes, bundle containment, target and exact grants are
verified before any worker/library/kernel is started.
4. 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
1. Project declaration and CLI selection are merged and deduplicated by
canonical path.
2. Identical logical identity + digests is idempotent.
3. Same package/kernel/provider logical identity with different manifest or
artifact digest is `ext.duplicate_callable` (prepare) — never last-wins and
never auto-suffixed.
4. Two providers declaring the same resource kind is
`ext.duplicate_provider_kind` (before spawn).
5. 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-relative `path`, 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.