- 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
192 lines
7.8 KiB
Markdown
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.
|