docs(ext): finalize extension selection/lock v4 docs, STATUS, CURRENT, COMPATIBILITY, CHANGELOG

This commit is contained in:
cflmy committed 2026-11-22 00:45:20 +08:00
1 parent 89555382e0
commit 6a7bb983c3
4 files changed
+105 -17

No files matched your search

+28
View File
@@ -435,6 +435,34 @@ manifest is the static contract: `run` verifies the loaded artifact and its
exports/signatures match the manifest exactly exports/signatures match the manifest exactly
(`ext.plugin_binding_mismatch` otherwise) and never synthesises a signature. (`ext.plugin_binding_mismatch` otherwise) and never synthesises a signature.
#### Declaring extensions in the project (lock v4)
A project can declare explicit activation sources and lock their identity; a
declaration is visibility/activation, never a grant:
```yaml
extensions:
plugins:
- from: ./adapter/plugin.yaml
kernels: []
providers:
- from: "@vendor/device/provider.json"
```
```bash
marqdo lock # writes lock_version: 4 with manifest/artifact identities
marqdo inspect index.mq.md --extensions --json # identity + lock status, no execution
```
Only `./relative/path` (project) and `@alias/relative/path` (declared
dependency) are accepted; absolute paths, URLs, globs and `..` are rejected.
`check`/`sync` compare the declaration with the lock
(`ext.extension_lock_mismatch`), `run` additionally re-verifies the real
artifact bytes, and `pure`/`strict` refuse project-declared third-party
extensions. Lock v3 requires an explicit `marqdo lock` migration. See
[`spec/extension-selection.md`](spec/extension-selection.md) and
[`docs/adr/0056-extension-selection-locking.md`](docs/adr/0056-extension-selection-locking.md).
#### Official stdlib aliases, no print magic #### Official stdlib aliases, no print magic
`打印`/`print` are declared in the verified `stdlib/stdlib.json` `打印`/`print` are declared in the verified `stdlib/stdlib.json`
+11 -8
View File
@@ -19,11 +19,13 @@ replace `spec/` or a recorded test log.
> **Extensibility closure (RFC-EXT-0001).** The current tree implements the > **Extensibility closure (RFC-EXT-0001).** The current tree implements the
> single static callable binding (ADR-0054), official stdlib public aliases > single static callable binding (ADR-0054), official stdlib public aliases
> replacing print magic (ADR-0058), third-party resource providers through the > replacing print magic (ADR-0058), third-party resource providers through the
> normal CLI (ADR-0055), and the capability-handler registry (ADR-0057). The > normal CLI (ADR-0055), the capability-handler registry (ADR-0057), and
> extension selection/lock v4 composition and the frozen external-binary > explicit extension selection with lock v4 (ADR-0056). The remaining PR-08
> evidence are tracked as remaining PR-04/PR-08 work, not claimed here. The > action is a SHA-bound frozen-release rerun of the external conformance suite
> normative resolution contract is > on the tagged commit; the suite PASSes against the release build of this tree.
> [`spec/callable-resolution.md`](../../spec/callable-resolution.md). > Normative boundaries: [`spec/callable-resolution.md`](../../spec/callable-resolution.md),
> [`spec/extension-selection.md`](../../spec/extension-selection.md),
> [`spec/resource-provider-v2.md`](../../spec/resource-provider-v2.md).
## 1. Four state dimensions ## 1. Four state dimensions
@@ -34,7 +36,7 @@ platform".
| Dimension | Current state | Source | | Dimension | Current state | Source |
|---|---|---| |---|---|---|
| Implemented | Rust workspace `0.1.0`: RFC-LANG-0002 Markdown/frontend/IR, v2 statement parser, tree-walk runtime, `Memory`, capability host, Tool/Analysis/Trace, Plugin ABI, Foreign kernels, migrated bundled stdlib, CLI composition root | `Cargo.toml`, `crates/`, `stdlib/` | | Implemented | Rust workspace `0.1.0`: RFC-LANG-0002 Markdown/frontend/IR, v2 statement parser, tree-walk runtime, `Memory`, capability host, Tool/Analysis/Trace, Plugin ABI, Foreign kernels, migrated bundled stdlib, CLI composition root | `Cargo.toml`, `crates/`, `stdlib/` |
| Tested locally | `cargo test --workspace --locked`: **584 passed, 0 failed** across 66 targets on Linux x86_64 in the RFC-EXT-0001 tree; fmt and clippy clean. Historical baseline: 507 passed at `9c1723d`. | `docs/STATUS.md`, `docs/evidence/2026-11-22-ext-implementation.md` | | Tested locally | `cargo test --workspace --locked`: **599 passed, 0 failed** across 67 targets on Linux x86_64 in the RFC-EXT-0001 tree; fmt and clippy clean. Historical baseline: 507 passed at `9c1723d`. | `docs/STATUS.md`, `docs/evidence/2026-11-22-ext-implementation.md` |
| Bundled stdlib released | In-repo bundle `marqdo-stdlib@0.1.0`, SHA-256 digest verified before loading; it is **not** an external registry package | `stdlib/stdlib.json`, `stdlib/README.md` | | Bundled stdlib released | In-repo bundle `marqdo-stdlib@0.1.0`, SHA-256 digest verified before loading; it is **not** an external registry package | `stdlib/stdlib.json`, `stdlib/README.md` |
| Multi-platform verified | Linux local gate is the only executed lane here; Windows/macOS native lanes are **UNVERIFIED**, and the GitHub security lane remains a **VM-only** gate | `docs/STATUS.md` §1, §4 | | Multi-platform verified | Linux local gate is the only executed lane here; Windows/macOS native lanes are **UNVERIFIED**, and the GitHub security lane remains a **VM-only** gate | `docs/STATUS.md` §1, §4 |
@@ -142,6 +144,7 @@ review RFC, not a new crate per provider.
| Resource Provider | new resource kinds/devices/network/file endpoints | v2 CLI entry implemented for trusted worker transport on linux/x86_64 (ADR-0055); v1 in-process/trusted C ABI remain embedder APIs; not one provider per high-level algorithm | | Resource Provider | new resource kinds/devices/network/file endpoints | v2 CLI entry implemented for trusted worker transport on linux/x86_64 (ADR-0055); v1 in-process/trusted C ABI remain embedder APIs; not one provider per high-level algorithm |
| Foreign kernel | explicit cross-language compatibility for Python/Node one-shot execution | implemented; registry accepts an explicitly declared unknown language; not a Marqdo implementation of common algorithms | | Foreign kernel | explicit cross-language compatibility for Python/Node one-shot execution | implemented; registry accepts an explicitly declared unknown language; not a Marqdo implementation of common algorithms |
| Official stdlib public alias | language-surface aliases such as `打印`/`print` declared in verified bundle metadata | implemented (ADR-0058); third parties cannot claim these names | | Official stdlib public alias | language-surface aliases such as `打印`/`print` declared in verified bundle metadata | implemented (ADR-0058); third parties cannot claim these names |
| Extension selection / lock v4 | `marqdo.yaml.extensions` activation sources; lock v4 manifest+artifact identity; `inspect --extensions` | implemented (ADR-0056); declaration is never a grant, `pure`/`strict` refuse third-party activation |
| Shared registry/policy/budget/audit/trace | package/adapter identity, descriptor/version checks, per-request grants, timeouts, error classes and trace metadata | housed inside `marqdo-host`; do not invent a shared binary ABI for function calls and resource streams | | Shared registry/policy/budget/audit/trace | package/adapter identity, descriptor/version checks, per-request grants, timeouts, error classes and trace metadata | housed inside `marqdo-host`; do not invent a shared binary ABI for function calls and resource streams |
## 5. Gap and closure backlog ## 5. Gap and closure backlog
@@ -165,8 +168,8 @@ that a phase is complete.
| P3 | No concurrency tasks, atomics or cancellable long-running scheduling | open; separate ADR | | P3 | No concurrency tasks, atomics or cancellable long-running scheduling | open; separate ADR |
| P3 | No native optimizer/JIT or columnar numeric backend | open; benchmark-first | | P3 | No native optimizer/JIT or columnar numeric backend | open; benchmark-first |
| P3 | Windows Native/Worker ABI is unsupported; macOS/Windows CI is unverified | open | | P3 | Windows Native/Worker ABI is unsupported; macOS/Windows CI is unverified | open |
| P0 | RFC-EXT-0001 PR-04: `marqdo.yaml.extensions` + lock v4 extension selection, CLI composition-root wiring, `inspect --extensions` | **open / in progress** | | P0 | RFC-EXT-0001 PR-04: `marqdo.yaml.extensions` + lock v4 extension selection, CLI composition-root wiring, `inspect --extensions` | **implemented/tested**; see `spec/extension-selection.md`, ADR-0056, `extension_selection` tests |
| P0 | RFC-EXT-0001 PR-08: frozen release binary, external conformance rerun, SHA-bound evidence manifest, final docs/status convergence | **open / in progress** | | P0 | RFC-EXT-0001 PR-08: frozen release binary rerun on the tagged commit + SHA-bound evidence manifest | **remaining release step** (`tools/ci/verify_extension_contracts.py`) |
| P1 | Provider worker transport only linux/x86_64; macOS/Windows provider lanes fail closed | open; separate platform work | | P1 | Provider worker transport only linux/x86_64; macOS/Windows provider lanes fail closed | open; separate platform work |
## 6. Documentation governance ## 6. Documentation governance
+35 -8
View File
@@ -1,8 +1,8 @@
# RFC-EXT-0001 implementation evidence (P0 core + PR-03/05/06/07 first pass) # RFC-EXT-0001 implementation evidence (P0 core + PR-03/05/06/07 first pass)
Status: **partial, honest record.** PR-00/01/02/03/05/06 are implemented and Status: **honest record of the implementation tree.** PR-00/01/02/03/04/05/06
tested on Linux x86_64 in this tree; PR-04 (extension selection/lock v4) and the are implemented and tested on Linux x86_64; PR-07/PR-08 additional work is the
final frozen-release evidence are still in progress. This document is not a SHA-bound evidence manifest and the tagged-release rerun. This document is not a
release claim. The authoritative executed status is regenerated in release claim. The authoritative executed status is regenerated in
`docs/STATUS.md` and `docs/evidence/extension/<SHA>/manifest.json`. `docs/STATUS.md` and `docs/evidence/extension/<SHA>/manifest.json`.
@@ -25,7 +25,7 @@ feature branch, so this file cannot be a same-SHA release artifact.
cargo fmt --all -- --check PASS (exit 0) cargo fmt --all -- --check PASS (exit 0)
cargo clippy --workspace --all-targets -- -D warnings PASS (exit 0) cargo clippy --workspace --all-targets -- -D warnings PASS (exit 0)
cargo test --workspace --locked PASS (exit 0) cargo test --workspace --locked PASS (exit 0)
66 test targets: 584 passed, 0 failed, 0 ignored 67 test targets: 599 passed, 0 failed, 0 ignored
``` ```
Targeted new suites: Targeted new suites:
@@ -35,6 +35,7 @@ cargo test -p marqdo-cli --test callable_resolution 14 passed
cargo test -p marqdo-cli --test stdlib_alias_routing 5 passed cargo test -p marqdo-cli --test stdlib_alias_routing 5 passed
cargo test -p marqdo-cli --test provider_cli 12 passed cargo test -p marqdo-cli --test provider_cli 12 passed
cargo test -p marqdo-cli --test analysis_trace 7 passed cargo test -p marqdo-cli --test analysis_trace 7 passed
cargo test -p marqdo-cli --test extension_selection 13 passed
cargo test -p marqdo-cli --test plugin_worker 4 passed cargo test -p marqdo-cli --test plugin_worker 4 passed
cargo test -p marqdo-cli --test print_routing 2 passed cargo test -p marqdo-cli --test print_routing 2 passed
cargo test -p marqdo-cli --test architecture_boundaries 9 passed cargo test -p marqdo-cli --test architecture_boundaries 9 passed
@@ -169,10 +170,35 @@ candidate, and `tools/ci/verify_extension_contracts.py` has not yet emitted a
`docs/evidence/extension/<SHA>/manifest.json`. The external suite will be rerun `docs/evidence/extension/<SHA>/manifest.json`. The external suite will be rerun
against the frozen release binary after PR-04 lands. against the frozen release binary after PR-04 lands.
## 3a. PR-04 — extension selection and lock v4
* `crates/marqdo-package/src/lib.rs`: `ExtensionKind`/`ExtensionSource`/
`Extensions` with only `./path` and `@alias/path` forms; lock v4
`LockedExtension` identity records, deterministic ordering, duplicate/
idempotent merge, `validate_extension_selection`/`validate_extension_declarations`,
explicit v3 migration error.
* `PackageResolver::resolve_extension_sources`: resolves to canonical regular
files inside the owning package (project or dependency), no execution.
* `crates/cli/src/project_prepare.rs`: merges project-declared plugin sources
with `--plugin`, compares declared identity with the lock, fails closed with
`ext.extension_lock_mismatch`; `pure`/`strict` refuse activation in `run`.
* `crates/cli/src/extension_selection.rs`: static identity computation for
plugin/kernel/provider manifests (declared digests; no binary execution).
* `crates/cli/src/commands/package.rs`: `lock` writes v4 extension identities;
`sync` validates declarations/identity before materialization.
* `crates/cli/src/commands/inspect.rs`: new `inspect --extensions` reports
declared sources, lock status, static plugin descriptors and stdlib aliases;
authorization is always `not_granted`.
* Tests: `crates/cli/tests/extension_selection.rs` (13), `crates/marqdo-package`
unit tests; docs `spec/extension-selection.md`, `spec/package-format.md` v4,
ADR-0056.
## 4. Known gaps / deviations (not hidden) ## 4. Known gaps / deviations (not hidden)
1. **PR-04 not landed yet.** `marqdo.yaml.extensions` and lock v4 are still in 1. **Frozen release evidence is not yet bound to a tagged SHA.** The external
progress; the CLI composition root for extension selection is not wired. suite PASSes against a `--release` build of this tree, but
`docs/evidence/extension/<SHA>/manifest.json` must be regenerated on the
final release commit and every mandatory result must be PASS there.
2. **Provider platform claims are Linux x86_64 only**; macOS/Windows are 2. **Provider platform claims are Linux x86_64 only**; macOS/Windows are
explicitly unsupported for the worker transport. The RFC's mac/Windows explicitly unsupported for the worker transport. The RFC's mac/Windows
provider lanes are not claimed. provider lanes are not claimed.
@@ -191,5 +217,6 @@ against the frozen release binary after PR-04 lands.
6. **CALL-10's host-side mismatches** are unit-tested for missing/extra exports; 6. **CALL-10's host-side mismatches** are unit-tested for missing/extra exports;
a live TOCTOU signature/digest mismatch is covered by artifact-tamper tests a live TOCTOU signature/digest mismatch is covered by artifact-tamper tests
plus exact reconciliation, not by swapping a manifest mid-run. plus exact reconciliation, not by swapping a manifest mid-run.
7. Full `--release` build, frozen external rerun, SHA-bound evidence manifest, 7. Remaining PR-08 step: regenerate the SHA-bound external evidence on the
docs/STATUS/CURRENT/COMPATIBILITY/CHANGELOG finalisation remain for PR-08. tagged release commit (the generator refuses a dirty checkout), then run the
existing G3/G4/native lanes; local/container smoke is not a release claim.
+31 -1
View File
@@ -161,6 +161,15 @@ def main() -> int:
parser.add_argument("--out", type=Path, help="Evidence manifest output path") parser.add_argument("--out", type=Path, help="Evidence manifest output path")
parser.add_argument("--validate", type=Path, help="Only validate an existing manifest") parser.add_argument("--validate", type=Path, help="Only validate an existing manifest")
parser.add_argument("--allow-unverified", action="store_true", help="Record UNSUPPORTED/SKIPPED without failing") parser.add_argument("--allow-unverified", action="store_true", help="Record UNSUPPORTED/SKIPPED without failing")
parser.add_argument(
"--tested-sha",
help="Require the source checkout HEAD to be exactly this 40-hex SHA before testing",
)
parser.add_argument(
"--allow-dirty-source",
action="store_true",
help="Development only: permit a dirty source checkout (never valid for release evidence)",
)
args = parser.parse_args() args = parser.parse_args()
if args.validate: if args.validate:
@@ -192,8 +201,29 @@ def main() -> int:
print("error: fixture repository has uncommitted changes", file=sys.stderr) print("error: fixture repository has uncommitted changes", file=sys.stderr)
return 2 return 2
source_repo = args.source_repo.resolve()
if not args.allow_dirty_source:
dirty = subprocess.run(
["git", "-C", str(source_repo), "status", "--porcelain"],
capture_output=True,
text=True,
check=True,
).stdout.strip()
if dirty:
print(
"error: source checkout has uncommitted changes; release evidence must "
"name a committed SHA (use --allow-dirty-source only for local development)",
file=sys.stderr,
)
return 2
cli_before = sha256_file(cli) cli_before = sha256_file(cli)
tested_sha = git_sha(args.source_repo.resolve()) tested_sha = git_sha(source_repo)
if args.tested_sha and args.tested_sha != tested_sha:
print(
f"error: --tested-sha {args.tested_sha} does not match checkout HEAD {tested_sha}",
file=sys.stderr,
)
return 2
fixture_sha = git_sha(fixtures) fixture_sha = git_sha(fixtures)
ok, results, commands = run_suite(fixtures, cli) ok, results, commands = run_suite(fixtures, cli)
cli_after = sha256_file(cli) cli_after = sha256_file(cli)