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:
cflmy committed 2026-11-22 00:43:18 +08:00
1 parent 1f6fd644a0
commit 89555382e0
19 files changed
+2240 -63

No files matched your search

+34 -5
View File
@@ -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
View File
@@ -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.