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
This commit is contained in:
1 parent
1f6fd644a0
commit
89555382e0
19 files changed
+2240
-63
No files matched your search
+34
-5
@@ -19,6 +19,34 @@ not be read as current status.
|
||||
Status is generated from executed commands and logs; a gate row without a command,
|
||||
log or source path is a defect, not a state.
|
||||
|
||||
## 0.0 RFC-EXT-0001 extensibility closure (current tree)
|
||||
|
||||
Executed on Linux x86_64, Rust 1.100.0, branch `feat/extensible-ecosystem`:
|
||||
|
||||
```text
|
||||
cargo fmt --all -- --check PASS
|
||||
cargo clippy --workspace --all-targets -- -D warnings PASS
|
||||
cargo test --workspace --locked PASS
|
||||
67 test targets: 599 passed, 0 failed
|
||||
cargo build --release --locked -p marqdo-cli PASS
|
||||
```
|
||||
|
||||
Implemented and tested in this tree (PR-00…PR-07; no release claim):
|
||||
|
||||
| Area | State | Tests |
|
||||
|---|---|---|
|
||||
| One `CallableRegistry` + one binding pass; runtime dispatch by `CallSiteKey`; no runtime name fallback; exact plugin reconciliation | **IMPLEMENTED / TESTED** | `callable_resolution` (14), `plugin_worker`, `analysis_trace`, `architecture_boundaries` |
|
||||
| `provider.json` v2 through `--provider`/`--allow-provider`; verified before spawn; sibling helper only | **IMPLEMENTED / TESTED (linux/x86_64)** | `provider_cli` (12); PROV-01…10/13; macOS/Windows FAIL-CLOSED |
|
||||
| `marqdo.yaml.extensions` + lock v4 identity + `inspect --extensions`; CLI/manifest merge and conflicts | **IMPLEMENTED / TESTED** | `extension_selection` (13), `package_env`, package crate tests |
|
||||
| Capability handler registry; `fs.read` real handler; audit/unavailable | **IMPLEMENTED / TESTED** | `marqdo-host` `capability_handlers` (12) |
|
||||
| Official stdlib public aliases; print_override/AST scan/runtime branch removed | **IMPLEMENTED / TESTED** | `stdlib_alias_routing` (5), print/format/Trace goldens |
|
||||
| Independent external repo + frozen-CLI suite (pure pinned Git, plugin, kernel, provider, tool) | **PASS against a development binary; release-binary rerun + SHA-bound manifest pending** | `/root/work/marqdo-extension-conformance` `tests/run_all.py`: all 7 categories PASS |
|
||||
|
||||
Evidence: [`evidence/2026-11-22-ext-implementation.md`](evidence/2026-11-22-ext-implementation.md)
|
||||
and baseline [`evidence/ext-baseline-595279f.md`](evidence/ext-baseline-595279f.md).
|
||||
The RFC-EXT-0001 release gate additionally requires a `--release` frozen-binary
|
||||
rerun and `docs/evidence/extension/<SHA>/manifest.json` on the tagged commit.
|
||||
|
||||
## 0. Language migration completed (RFC-LANG-0002)
|
||||
|
||||
The repository now has **one** language contract, implemented end to end:
|
||||
@@ -215,7 +243,7 @@ This is still a **local VM lane**, not a self-hosted GitHub Actions security URL
|
||||
| 5 | Markdown/power/control-flow corpus | **Green on semantics v2** | 160 AST + 73 semantic + 49 compile-negative + 2 warning + 21 runtime-negative fixtures; `conformance_ast`/`semantics`/`negative` pass |
|
||||
| 6 | Payload/control source spans | **Green on semantics v2** | UTF-8 spans, control-expression offsets and heading boundaries covered by fixtures and CLI tests; old condition headers were removed |
|
||||
| 7 | Independent Tool consumers | **Done locally** | `sample-view`/`sample-knowledge`/`sample-proof` E2E test |
|
||||
| 8 | lock v3 reproducibility | **Implemented; tamper test added** | `package_env` PASS |
|
||||
| 8 | lock v4 reproducibility + extension identities | **Implemented; tamper/migration tests added** | `package_env`, `extension_selection` PASS |
|
||||
| 9 | Analysis/Trace/Tool/ABI/Foreign | **Implemented; supported-matrix bounded** | protocol tests, plugin/worker/foreign tests |
|
||||
| 10 | Linux strict L1 | **Local VM PASS at 5fcc111; remote G3 runner still missing** | 7/7 + positive CLI + strict JSON/inert-`@knowledge`; [`strict-gc-5fcc111`](evidence/2026-11-21-strict-gc-5fcc111.md) |
|
||||
| 11 | Linux strict L2 | **NOT IMPLEMENTED / UNSUPPORTED** | strict rejects Worker/Foreign/native ABI |
|
||||
@@ -233,10 +261,11 @@ This is still a **local VM lane**, not a self-hosted GitHub Actions security URL
|
||||
- Native `**` power is pinned end-to-end: right associativity, unary-minus
|
||||
precedence, parentheses, float negative exponents, branch/loop conditions,
|
||||
Strong+CodeSpan payloads, and inert prose/code fences.
|
||||
- lock v3 full transitive package-instance graph, verified Git cache, strict
|
||||
`sync --locked`, atomic `.marqdo/env` materialization; `run`/`check` never
|
||||
fetch or rewrite the lock. Locked path content tamper is rejected without
|
||||
rewriting the lock or environment.
|
||||
- lock v4 full transitive package-instance graph plus extension identity
|
||||
records, verified Git cache, strict `sync --locked`, atomic `.marqdo/env`
|
||||
materialization; `run`/`check` never fetch or rewrite the lock. Locked path
|
||||
content tamper is rejected without rewriting the lock or environment; lock v3
|
||||
requires an explicit `marqdo lock` migration.
|
||||
- Analysis v2 (logical identity, resources, byte digest) and Trace v2 (module
|
||||
ownership, bounds, truncation, stale detection) with independent Python
|
||||
consumers and JSON Schema validation.
|
||||
|
||||
@@ -0,0 +1,127 @@
|
||||
# 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).
|
||||
+15
-4
@@ -29,7 +29,18 @@ architecture; read them as decision history.
|
||||
[`docs/architecture/CURRENT.md`](../architecture/CURRENT.md); for executed
|
||||
status see [`docs/STATUS.md`](../STATUS.md).
|
||||
|
||||
Files: `0001`–`0050`, plus `0051-byte-exact-http-framing.md` (HTTP framing),
|
||||
`0052-unified-markdown-semantics.md` (current language mapping) and
|
||||
`0053-strict-child-inspection-and-json-failure-contract.md` (strict CI/JSON
|
||||
failure contract).
|
||||
Files: `0001`–`0050`, plus:
|
||||
|
||||
* `0051-byte-exact-http-framing.md` — HTTP framing;
|
||||
* `0052-unified-markdown-semantics.md` — current language mapping;
|
||||
* `0053-strict-child-inspection-and-json-failure-contract.md` — strict CI/JSON
|
||||
failure contract;
|
||||
* `0054-callable-binding-single-source.md` — one registry/binding pass and
|
||||
runtime dispatch by identity;
|
||||
* `0055-resource-provider-cli-v2.md` — `provider.json` v2 through the normal
|
||||
CLI, worker trust boundary;
|
||||
* `0056-extension-selection-locking.md` — `marqdo.yaml.extensions` and lock v4;
|
||||
* `0057-capability-handler-registration.md` — declared capability vs installed
|
||||
handler vs audit;
|
||||
* `0058-stdlib-public-alias.md` — verified stdlib `public_aliases` replace
|
||||
print magic.
|
||||
Reference in new issue
Block a user