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

+37
View File
@@ -5,6 +5,43 @@ currently `0.1.0`; no release tag has been cut. Dates use ISO 8601.
## Unreleased (stabilization candidate)
### Breaking changes — extensibility closure (RFC-EXT-0001)
Implements [`docs/architecture/RFC-EXT-0001.md`](docs/architecture/RFC-EXT-0001.md)
(ADR-0054/0055/0056/0057/0058). 0.x breaking changes:
- **One callable resolution.** `check`/`run`/`call`/`inspect`/Analysis share a
single registry and binding pass (`CallSiteKey`). The runtime no longer
re-resolves names or guesses a plugin when no descriptor is loaded. An import
alias that collides with a builtin/plugin dotted namespace (for example
importing a module as `math`) is now `ext.import_namespace_conflict`; rename
the alias. Unknown plugin exports are `symbol.unknown` at compile time.
- **Exact plugin binding.** A plugin manifest is the static signature contract;
`run` verifies artifact bytes and reconciles exports/signatures/owners/digests
one-to-one (`ext.plugin_binding_mismatch`). Empty/synthesised signatures are
gone; ABI v1 signature defaults are rejected; positional arguments are
normalised to manifest order.
- **Lock v4.** `marqdo.lock` upgrades to `lock_version: 4` with an `extensions:`
identity table. Lock v3 is rejected with an explicit `marqdo lock` migration
error; it is never reinterpreted silently. Projects can declare explicit
activation sources under `marqdo.yaml.extensions` (`./path` or `@alias/path`
only); a declaration is not a grant.
- **Analysis calls projection.** `calls[].state/target` now come from the same
binding; official stdlib aliases such as `打印` project as `function` targets.
Analysis v2 schema/version are unchanged and the private binding table is not
serialized.
- **Print magic removed.** `打印`/`print` are verified `stdlib.json`
`public_aliases` bound to `io.mq.md::写值`; `Program.print_override`, the
AST-wide print scan and the runtime print branch are deleted. Output bytes are
unchanged; programs without print do not load the stdlib module graph.
- **Third-party resource providers via CLI.** `--provider PATH` /
`--allow-provider NAME` on `run`/`call` select and authorize a
`provider.json` schema-2 worker artifact; verified before spawn; pure/strict
refuse; linux/x86_64 only (other platforms fail closed).
- **Capability handler registry.** Granted capabilities execute only through a
trusted installed handler under budget/audit; a declared-but-unhandled
capability stays `capability.unavailable`.
### Breaking changes — language source syntax (RFC-LANG-0002)
**The `.mq.md` source language changed incompatibly. Old source files are not
+30 -7
View File
@@ -1,9 +1,10 @@
# Compatibility and support matrix
Snapshot: workspace version **0.1.0**, language SHA **`9c1723d`**, security SHA
**`8af7262`**, no release tag cut. This file records what was actually verified and separates it
from what is only implemented. Executed status is in
[`docs/STATUS.md`](docs/STATUS.md).
Snapshot: workspace version **0.1.0**, RFC-EXT-0001 tree on
`feat/extensible-ecosystem`, no release tag cut. This file records what was
actually verified and separates it from what is only implemented. Executed
status is in [`docs/STATUS.md`](docs/STATUS.md); SHA-bound external evidence is
under [`docs/evidence/extension/`](docs/evidence/extension/README.md).
## Language source syntax (breaking change)
@@ -47,11 +48,15 @@ Consequences for compatibility:
|---|---|---|
| Markdown profile | `marqdo.md.v1` | Frozen parser/options. The RFC-LANG-0002 mapping rewrite keeps this profile; the source-language break is tracked above, not by a new profile id. |
| Language / CLI | workspace `0.1.0` | Pre-1.0. The `.mq.md` source language changed incompatibly (RFC-LANG-0002); there is no old-syntax execution path. CLI flags may change with a changelog note; `strict` refusal is contractual. |
| `marqdo.lock` | v3 | v1/v2 are rejected with a relock instruction; `run`/`call`/`check` never rewrite or fetch the lock. |
| `marqdo.lock` | v4 | v3 is rejected with an explicit `marqdo lock` migration error; v1/v2 are rejected with a relock instruction; `run`/`call`/`check` never rewrite or fetch the lock. `extensions:` records manifest/artifact identity (integrity, not publisher auth). |
| Analysis | v2 | Consumers reject unknown majors; incompatible field changes require v3. |
| Trace | v2 | Binds to the exact Analysis bytes; unknown majors rejected. |
| CLI Tool | v1 | Manifest schema, SemVer negotiation and whole-bundle digest are stable for v1. |
| Plugin ABI | v1 | Struct layout/version negotiation frozen; `--trust-native-plugin` is required for in-process loading. |
| Plugin ABI | v1 | Struct layout/version negotiation frozen; `--trust-native-plugin` is required for in-process loading. The static manifest signature is authoritative; `run` reconciles loaded exports/signatures/owners/artifact digests exactly (`ext.plugin_binding_mismatch`); ABI v1 defaults are rejected. |
| Resource Provider manifest | v2 | `schema_version: 2`, `abi: c-abi-1`, `transport: worker`; v1 is rejected (`ext.unsupported_provider_schema`), no silent migration. CLI `--provider`/`--allow-provider`; trusted worker, not an OS sandbox. |
| Callable resolution | ADR-0054 | One registry + one binding pass; `check` and `run` bind the same `CallSiteKey`; no runtime name fallback. Import aliases colliding with builtin/plugin dotted namespaces are rejected. |
| Analysis `calls[].state/target` | v2 (projection) | Now projected from the unique binding; official stdlib aliases appear as `function`. Schema/version unchanged; private binding table not serialized. |
| Extension selection | lock v4 | `marqdo.yaml.extensions` only `./path` or `@alias/path`; declaration is not a grant; declared identity must match the lock (`ext.extension_lock_mismatch`). |
| Foreign wire | v1 | One-shot request envelope; provider descriptors are explicit. |
## Platform / feature evidence
@@ -67,7 +72,13 @@ portable/tested locally but the native platform lane has not run here;
| Addressable `Memory` P1 (ADR-0022) | PASS | UNVERIFIED | UNVERIFIED |
| Resource streams CM-A06 (ADR-0025/0026: stdout + project file read/write) | PASS | UNVERIFIED | **FAIL-CLOSED** (`strict` refuses resource opens) |
| `run` / `call` / `check` / `inspect` / `fmt` | PASS | UNVERIFIED | UNVERIFIED |
| lock v3 path/Git graph + sync + tamper | PASS | UNVERIFIED | UNVERIFIED |
| lock v4 path/Git graph + sync + tamper | PASS | UNVERIFIED | UNVERIFIED |
| Extension selection/lock v4 (`extensions:`, identities, `inspect --extensions`) | PASS | UNVERIFIED | UNVERIFIED |
| Callable single binding + `ext.import_namespace_conflict`/`symbol.unknown`/plugin reconciliation | PASS | UNVERIFIED | UNVERIFIED |
| Official stdlib public aliases (print de-magic; byte-identical output) | PASS | UNVERIFIED | UNVERIFIED |
| Resource Provider v2 CLI (`--provider`/`--allow-provider`, worker helper) | PASS (linux/x86_64; real C sensor + helper) | **FAIL-CLOSED** (`ext.platform_unsupported`) | **UNSUPPORTED** |
| Capability handler registry (`fs.read` handler, audit, unavailable) | PASS | UNVERIFIED | UNVERIFIED |
| External conformance repository (`marqdo-extension-conformance`, frozen CLI) | PASS (provisional development binary; release rerun pending) | UNVERIFIED | UNVERIFIED |
| Analysis v2 / Trace v2 + Python consumers | PASS | UNVERIFIED | UNVERIFIED |
| Tool Protocol v1 + 3 independent consumers | PASS | UNVERIFIED | UNVERIFIED |
| Native ABI (`plugin inspect`, trusted call) | PASS (C fixture) | UNVERIFIED (host-native fixture) | **UNSUPPORTED** |
@@ -107,6 +118,18 @@ reproduce the Windows checkout byte behavior.
permits user, mount, PID and network namespaces. See
[`docs/security-gate.md`](docs/security-gate.md) and ADR-0021.
## RFC-EXT-0001 platform statements
* Provider worker transport: linux/x86_64 only; macOS/Windows return
`ext.platform_unsupported` (compile-only, fail-closed). The RFC's macOS
provider lane is **not claimed**.
* Windows Native/Worker ABI remains **UNSUPPORTED**; a Linux PASS does not
substitute for it.
* `strict` L1 continues to refuse plugins/providers/foreign kernels; strict L2
is not implemented. A worker is a trusted process, not an OS sandbox.
* The external conformance suite is a mandatory **additional** release gate
(`docs/releasing.md` §7); it does not replace G3/G4/native lanes.
## Explicitly unsupported in this candidate
- Pre-RFC `.mq.md` source syntax (Strong-execute / Emph-return / ordered-list
+115 -8
View File
@@ -17,24 +17,31 @@ pub struct InspectFlags {
pub refs: bool,
/// Show platform capability report.
pub platform: bool,
/// Show declared/loaded extension identities (never grants).
pub extensions: bool,
}
pub fn inspect(file: Option<&Path>, flags: &InspectFlags, json: bool) -> i32 {
let prepared = match prepare_project(file, json, &[]) {
pub fn inspect(file: Option<&Path>, flags: &InspectFlags, json: bool, plugins: &[PathBuf]) -> i32 {
let prepared = match prepare_project(file, json, plugins) {
Ok(prepared) => prepared,
Err(code) => return code,
};
let project = prepared.loaded;
let project = &prepared.loaded;
let entry = project.entry_file();
let module = &entry.analysis.module;
let selected_any =
flags.ast || flags.units || flags.signature || flags.ir || flags.refs || flags.platform;
let selected_any = flags.ast
|| flags.units
|| flags.signature
|| flags.ir
|| flags.refs
|| flags.platform
|| flags.extensions;
if json {
let mut object = serde_json::Map::new();
object.insert("command".into(), json!("inspect"));
object.insert("module".into(), json!(entry.module_id.to_string()));
if !selected_any {
object.insert("summary".into(), summary_json(&project));
object.insert("summary".into(), summary_json(project));
}
if flags.ast {
object.insert(
@@ -58,7 +65,7 @@ pub fn inspect(file: Option<&Path>, flags: &InspectFlags, json: bool) -> i32 {
);
}
if flags.refs {
object.insert("refs".into(), json!(refs_json(&project)));
object.insert("refs".into(), json!(refs_json(project)));
}
if flags.platform {
object.insert(
@@ -66,6 +73,9 @@ pub fn inspect(file: Option<&Path>, flags: &InspectFlags, json: bool) -> i32 {
serde_json::to_value(PlatformCapabilities::detect()).unwrap_or_default(),
);
}
if flags.extensions {
object.insert("extensions".into(), extensions_json(&prepared, project));
}
output::print_json(&serde_json::Value::Object(object));
return 0;
}
@@ -120,7 +130,7 @@ pub fn inspect(file: Option<&Path>, flags: &InspectFlags, json: bool) -> i32 {
if flags.refs {
println!(
"{}",
serde_json::to_string_pretty(&refs_json(&project)).unwrap_or_default()
serde_json::to_string_pretty(&refs_json(project)).unwrap_or_default()
);
}
if flags.platform {
@@ -129,5 +139,102 @@ pub fn inspect(file: Option<&Path>, flags: &InspectFlags, json: bool) -> i32 {
serde_json::to_string_pretty(&PlatformCapabilities::detect()).unwrap_or_default()
);
}
if flags.extensions {
let value = extensions_json(&prepared, project);
println!(
"{}",
serde_json::to_string_pretty(&value).unwrap_or_default()
);
}
0
}
/// Static extension identity projection for `inspect --extensions`.
///
/// Reports declared sources, lock identity, static plugin descriptors and
/// official stdlib aliases. It deliberately never shows environment variables,
/// secrets, binary contents or an authorization result beyond
/// `not_granted` (inspection does not grant anything).
fn extensions_json(
prepared: &crate::project_prepare::PreparedProgram,
project: &crate::loader::LoadedProject,
) -> serde_json::Value {
let root = project.root.as_path();
let relative = |path: &Path| {
path.strip_prefix(root)
.map(|value| value.to_string_lossy().to_string())
.unwrap_or_else(|_| path.to_string_lossy().to_string())
};
let declared: Vec<serde_json::Value> = project
.extension_sources
.iter()
.map(|extension| {
let identity = prepared.extension_identities.iter().find(|identity| {
identity.kind == extension.kind
&& identity.source == extension.from
&& identity.logical_owner == extension.logical_owner
});
let locked = project.lock.as_ref().is_some_and(|lock| {
identity.is_some_and(|identity| {
lock.extension(identity.kind, &identity.name, &identity.logical_owner)
.is_some()
})
});
json!({
"kind": extension.kind.as_str(),
"source": extension.from,
"path": relative(&extension.path),
"logical_owner": extension.logical_owner,
"name": identity.map(|identity| identity.name.clone()),
"version": identity.map(|identity| identity.version.clone()),
"manifest_digest": identity.map(|identity| identity.manifest_digest.clone()),
"artifact_digest": identity.map(|identity| identity.artifact_digest.clone()),
"selected_target": identity.map(|identity| identity.selected_target.clone()),
"status": if locked { "locked" } else { "unlocked" },
"authorization": "not_granted",
})
})
.collect();
let plugins: Vec<serde_json::Value> = prepared
.plugins
.plugins
.iter()
.map(|plugin| {
json!({
"package": plugin.package,
"version": plugin.version,
"kind": plugin.kind.as_str(),
"manifest_path": relative(&plugin.manifest_path),
"manifest_digest": plugin.manifest_sha256,
"selected_target": plugin.artifact_target,
"artifact_digest": plugin.artifact_sha256,
"artifact_path": relative(&plugin.artifact_path()),
"exports": plugin.exports.iter().map(|export| json!({
"name": export.name,
"signature": export.signature,
})).collect::<Vec<_>>(),
"validation": "static_manifest_ok",
"authorization": "not_granted",
})
})
.collect();
let aliases: Vec<serde_json::Value> = project
.official_aliases
.iter()
.map(|alias| {
json!({
"public_names": alias.public_names,
"target": alias.function.to_string(),
"owner_package": alias.owner_package,
"source": "verified stdlib bundle",
"authorization": "official_bundle",
})
})
.collect();
json!({
"declared": declared,
"plugins": plugins,
"stdlib_aliases": aliases,
"note": "inspect never loads or executes an extension and never grants a permission",
})
}
+60 -13
View File
@@ -1,6 +1,7 @@
//! Package lock/sync/add/remove commands.
use super::*;
use crate::extension_selection;
/// `marqdo lock`.
pub fn lock(json: bool) -> i32 {
@@ -18,19 +19,40 @@ pub fn lock(json: bool) -> i32 {
return 2;
}
};
let graph =
match marqdo_package::PackageResolver::new(root.clone(), Some(manifest.clone()), None)
.with_fetch(true)
.with_unlocked(true)
.resolve_lock_graph()
{
Ok(graph) => graph,
Err(error) => {
eprintln!("error: {error}");
return 1;
}
};
let lockfile = graph.lock;
let resolver = marqdo_package::PackageResolver::new(root.clone(), Some(manifest.clone()), None)
.with_fetch(true)
.with_unlocked(true);
let graph = match resolver.resolve_lock_graph() {
Ok(graph) => graph,
Err(error) => {
eprintln!("error: {error}");
return 1;
}
};
let mut lockfile = graph.lock;
// Lock v4: record the exact extension identity declared by the project.
// Reading manifests/declared digests is static; no binary is loaded and no
// grant is implied.
let extension_sources = match resolver.resolve_extension_sources() {
Ok(sources) => sources,
Err(error) => {
eprintln!("error: extension selection: {error}");
return 1;
}
};
let identities = match extension_selection::extension_identities(&extension_sources) {
Ok(identities) => identities,
Err(error) => {
eprintln!("error[{}]: {}", error.code, error.message);
return error.exit_code;
}
};
for identity in identities {
if let Err(error) = lockfile.merge_extension(identity) {
eprintln!("error[ext.extension_lock_mismatch]: {error}");
return 1;
}
}
let path = root.join(marqdo_package::LOCK_FILE);
if let Err(error) = write_atomic(&path, lockfile.to_yaml().as_bytes()) {
eprintln!("error: cannot write {}: {error}", path.display());
@@ -41,6 +63,7 @@ pub fn lock(json: bool) -> i32 {
"command": "lock",
"success": true,
"packages": lockfile.packages,
"extensions": lockfile.extensions,
}));
} else {
println!(
@@ -90,6 +113,30 @@ pub fn sync(locked: bool, json: bool) -> i32 {
let resolver =
marqdo_package::PackageResolver::new(root, Some(manifest.clone()), Some(lockfile.clone()))
.with_fetch(!locked);
// Verify the declared extension selection against the lock before using
// any materialized content. A missing/changed identity fails closed.
let extension_sources = match resolver.resolve_extension_sources() {
Ok(sources) => sources,
Err(error) => {
eprintln!("error: extension selection: {error}");
return 1;
}
};
let identities = match extension_selection::extension_identities(&extension_sources) {
Ok(identities) => identities,
Err(error) => {
eprintln!("error[{}]: {}", error.code, error.message);
return error.exit_code;
}
};
if let Err(error) = lockfile.validate_extension_declarations(&manifest) {
eprintln!("error[ext.extension_lock_mismatch]: {error}");
return 1;
}
if let Err(error) = extension_selection::validate_against_lock(&lockfile, &identities) {
eprintln!("error[{}]: {}", error.code, error.message);
return error.exit_code;
}
if let Err(error) = resolver.materialize_env(&lockfile) {
eprintln!("error: cannot materialize project environment: {error}");
return 1;
+40 -2
View File
@@ -20,6 +20,7 @@ pub fn execute(
Ok(prepared) => prepared,
Err(code) => return code,
};
let extension_sources = prepared.loaded.extension_sources.clone();
let project = prepared.loaded;
let static_plugins = prepared.plugins;
if project.has_errors() {
@@ -51,6 +52,43 @@ pub fn execute(
return 2;
}
};
// A project-declared extension is activation, not authorization, but it is
// still third-party executable code. `pure`/`strict` never activate it.
if !extension_sources.is_empty() && mode != SandboxMode::Project {
let code = if mode == SandboxMode::Strict {
"strict.unsupported_grant"
} else {
"cli.invalid_grants"
};
let message = format!(
"this project declares {} extension activation source(s) in {}; \
--mode {} cannot activate third-party extensions. Use --mode project \
with explicit grants, or remove the extensions block",
extension_sources.len(),
marqdo_package::MANIFEST_FILE,
settings.mode
);
emit_error(json, command_name, code, &message);
return 2;
}
let mut kernel_paths = settings.kernels.clone();
kernel_paths.extend(
extension_sources
.iter()
.filter(|extension| extension.kind == marqdo_package::ExtensionKind::Kernel)
.map(|extension| extension.path.clone()),
);
kernel_paths.sort();
kernel_paths.dedup();
let mut provider_paths = settings.providers.clone();
provider_paths.extend(
extension_sources
.iter()
.filter(|extension| extension.kind == marqdo_package::ExtensionKind::Provider)
.map(|extension| extension.path.clone()),
);
provider_paths.sort();
provider_paths.dedup();
if mode == SandboxMode::Strict {
if let Err(error) = settings.strict_preflight() {
emit_error(json, command_name, "strict.unsupported_grant", &error);
@@ -121,7 +159,7 @@ pub fn execute(
if let Some(timeout) = settings.timeout {
host.budget.deadline = Some(Instant::now() + Duration::from_secs(timeout));
}
for kernel_path in &settings.kernels {
for kernel_path in &kernel_paths {
if let Err(error) = load_kernel_descriptor(&mut host, kernel_path) {
if json {
output::print_json(&json!({"success": false, "error": error}));
@@ -139,7 +177,7 @@ pub fn execute(
// current target artifact, check the exact grant and reject duplicate
// names/kinds *before* any provider or plugin worker process is spawned
// (RFC-EXT-0001 §5.4.6/§18.2 T6–T7).
let providers = match provider_manifest::read_provider_manifests(&settings.providers) {
let providers = match provider_manifest::read_provider_manifests(&provider_paths) {
Ok(providers) => providers,
Err(error) => {
emit_prepare_error(json, command_name, &error);
+318
View File
@@ -0,0 +1,318 @@
//! Extension selection identities (RFC-EXT-0001 §6, ADR-0056).
//!
//! `marqdo.yaml.extensions` declares activation sources; the lock file records
//! the exact selected identity (manifest digest, artifact digest, target).
//! This module computes those identities from static manifests only:
//!
//! * it never `dlopen`s a library, spawns a worker or runs a script;
//! * it reads the declared artifact SHA-256 (plus the manifest bytes) so
//! `check`/`sync` can compare against the lock without requiring a built
//! binary; `run` separately verifies the actual artifact bytes before use.
//!
//! A declaration is visibility/activation, never a grant. Grants stay in
//! `--allow-plugin`/`--allow-provider`/`--allow-foreign` and the capability
//! broker.
use std::collections::BTreeSet;
use marqdo_package::{ExtensionKind, LockedExtension, ResolvedExtension};
use sha2::{Digest, Sha256};
use crate::extension_descriptors::PrepareError;
/// Compute the declared identity of every resolved extension source.
///
/// Duplicate `(kind, name, logical_owner)` identities with different digests
/// are rejected deterministically; the same identity declared twice is
/// idempotent.
pub fn extension_identities(
resolved: &[ResolvedExtension],
) -> Result<Vec<LockedExtension>, PrepareError> {
let mut identities = Vec::new();
let mut seen: BTreeSet<(ExtensionKind, String, String)> = BTreeSet::new();
for extension in resolved {
let identity = match extension.kind {
ExtensionKind::Plugin => plugin_identity(extension)?,
ExtensionKind::Provider => provider_identity(extension)?,
ExtensionKind::Kernel => kernel_identity(extension)?,
};
let key = (
identity.kind,
identity.name.clone(),
identity.logical_owner.clone(),
);
if !seen.insert(key.clone()) {
let existing = identities
.iter()
.find(|item: &&LockedExtension| {
item.kind == key.0 && item.name == key.1 && item.logical_owner == key.2
})
.expect("identity was inserted with its key");
if existing == &identity {
continue;
}
return Err(PrepareError::option(
"ext.duplicate_callable",
format!(
"extension {} `{}` for owner `{}` is declared with two different manifests",
key.0, key.1, key.2
),
));
}
identities.push(identity);
}
identities.sort_by(|left, right| {
(&left.kind, &left.name, &left.logical_owner).cmp(&(
&right.kind,
&right.name,
&right.logical_owner,
))
});
Ok(identities)
}
fn plugin_identity(extension: &ResolvedExtension) -> Result<LockedExtension, PrepareError> {
let manifest_bytes = std::fs::read(&extension.path).map_err(|error| {
PrepareError::option(
"ext.manifest_unreadable",
format!(
"cannot read plugin manifest `{}`: {error}",
extension.path.display()
),
)
})?;
let manifest = marqdo_plugin_abi::PluginManifest::load(&extension.path)
.map_err(|error| PrepareError::option(error.code.clone(), error.message.clone()))?;
manifest
.validate()
.map_err(|error| PrepareError::option(error.code.clone(), error.message.clone()))?;
let host = marqdo_plugin_abi::HostTarget::current();
let artifact = manifest
.resolve_artifact(&host)
.map_err(|error| PrepareError::option("ext.no_matching_artifact", error.message))?;
Ok(LockedExtension {
kind: ExtensionKind::Plugin,
logical_owner: extension.logical_owner.clone(),
name: manifest.plugin.name.clone(),
version: manifest.plugin.version.clone(),
manifest_digest: hex(&Sha256::digest(&manifest_bytes)),
artifact_digest: artifact.sha256.clone(),
selected_target: host.triple().to_string(),
source: extension.from.clone(),
})
}
fn provider_identity(extension: &ResolvedExtension) -> Result<LockedExtension, PrepareError> {
let manifest_bytes = std::fs::read(&extension.path).map_err(|error| {
PrepareError::option(
"ext.manifest_unreadable",
format!(
"cannot read provider manifest `{}`: {error}",
extension.path.display()
),
)
})?;
let manifest: serde_json::Value = serde_json::from_slice(&manifest_bytes).map_err(|error| {
PrepareError::option(
"ext.manifest_unreadable",
format!(
"invalid provider manifest `{}`: {error}",
extension.path.display()
),
)
})?;
if manifest.get("schema").and_then(serde_json::Value::as_str) != Some("marqdo.provider") {
return Err(PrepareError::option(
"ext.manifest_invalid",
format!(
"`{}` must declare schema `marqdo.provider`",
extension.path.display()
),
));
}
if manifest
.get("schema_version")
.and_then(serde_json::Value::as_u64)
!= Some(2)
{
return Err(PrepareError::option(
"ext.unsupported_provider_schema",
format!(
"`{}` is not a provider schema version 2 manifest; run `marqdo lock` only with v2",
extension.path.display()
),
));
}
let name = manifest
.get("name")
.and_then(serde_json::Value::as_str)
.ok_or_else(|| {
PrepareError::option(
"ext.manifest_invalid",
format!("`{}` has no name", extension.path.display()),
)
})?;
let version = manifest
.get("version")
.and_then(serde_json::Value::as_str)
.ok_or_else(|| {
PrepareError::option(
"ext.manifest_invalid",
format!("`{}` has no version", extension.path.display()),
)
})?;
let target = marqdo_plugin_abi::HostTarget::current()
.triple()
.to_string();
let artifacts = manifest
.get("artifacts")
.and_then(serde_json::Value::as_array)
.ok_or_else(|| {
PrepareError::option(
"ext.manifest_invalid",
format!("`{}` has no artifacts array", extension.path.display()),
)
})?;
let artifact = artifacts
.iter()
.find(|artifact| {
artifact.get("target").and_then(serde_json::Value::as_str) == Some(&target)
})
.ok_or_else(|| {
PrepareError::option(
"ext.no_matching_artifact",
format!("provider `{name}` has no artifact for target `{target}`"),
)
})?;
let sha256 = artifact
.get("sha256")
.and_then(serde_json::Value::as_str)
.ok_or_else(|| {
PrepareError::option(
"ext.manifest_invalid",
format!("provider `{name}` artifact has no sha256"),
)
})?;
if sha256.len() != 64 || !sha256.bytes().all(|byte| byte.is_ascii_hexdigit()) {
return Err(PrepareError::option(
"ext.manifest_invalid",
format!("provider `{name}` artifact sha256 is not 64 hex characters"),
));
}
Ok(LockedExtension {
kind: ExtensionKind::Provider,
logical_owner: extension.logical_owner.clone(),
name: name.to_string(),
version: version.to_string(),
manifest_digest: hex(&Sha256::digest(&manifest_bytes)),
artifact_digest: sha256.to_ascii_lowercase(),
selected_target: target,
source: extension.from.clone(),
})
}
fn kernel_identity(extension: &ResolvedExtension) -> Result<LockedExtension, PrepareError> {
let manifest_bytes = std::fs::read(&extension.path).map_err(|error| {
PrepareError::option(
"ext.manifest_unreadable",
format!(
"cannot read kernel descriptor `{}`: {error}",
extension.path.display()
),
)
})?;
let manifest: serde_json::Value = serde_json::from_slice(&manifest_bytes).map_err(|error| {
PrepareError::option(
"ext.manifest_unreadable",
format!(
"invalid kernel descriptor `{}`: {error}",
extension.path.display()
),
)
})?;
let name = manifest
.get("provider_id")
.and_then(serde_json::Value::as_str)
.ok_or_else(|| {
PrepareError::option(
"ext.manifest_invalid",
format!("`{}` has no provider_id", extension.path.display()),
)
})?;
let wire_version = manifest
.get("wire_version")
.and_then(serde_json::Value::as_u64)
.ok_or_else(|| {
PrepareError::option(
"ext.manifest_invalid",
format!("`{}` has no wire_version", extension.path.display()),
)
})?;
if wire_version != 1 {
return Err(PrepareError::option(
"ext.manifest_invalid",
format!("kernel descriptor `{name}` uses unsupported wire_version {wire_version}"),
));
}
let digest = manifest
.get("digest")
.and_then(serde_json::Value::as_str)
.ok_or_else(|| {
PrepareError::option(
"ext.manifest_invalid",
format!("kernel descriptor `{name}` has no digest"),
)
})?;
if digest.len() != 64 || !digest.bytes().all(|byte| byte.is_ascii_hexdigit()) {
return Err(PrepareError::option(
"ext.manifest_invalid",
format!("kernel descriptor `{name}` digest is not 64 hex characters"),
));
}
let entrypoint = manifest
.get("entrypoint")
.and_then(serde_json::Value::as_str)
.ok_or_else(|| {
PrepareError::option(
"ext.manifest_invalid",
format!("kernel descriptor `{name}` has no entrypoint"),
)
})?;
// The descriptor's entrypoint is package/descriptor-relative or absolute
// (existing foreign.md contract). Reject explicit path escaping here.
if entrypoint.is_empty() {
return Err(PrepareError::option(
"ext.manifest_invalid",
format!("kernel descriptor `{name}` has an empty entrypoint"),
));
}
Ok(LockedExtension {
kind: ExtensionKind::Kernel,
logical_owner: extension.logical_owner.clone(),
name: name.to_string(),
version: format!("wire:{wire_version}"),
manifest_digest: hex(&Sha256::digest(&manifest_bytes)),
artifact_digest: digest.to_ascii_lowercase(),
selected_target: marqdo_plugin_abi::HostTarget::current()
.triple()
.to_string(),
source: extension.from.clone(),
})
}
/// Validate that the lock still describes the current declared selection.
pub fn validate_against_lock(
lock: &marqdo_package::LockFile,
identities: &[LockedExtension],
) -> Result<(), PrepareError> {
lock.validate_extension_selection(identities)
.map_err(|message| PrepareError::load("ext.extension_lock_mismatch", message))
}
fn hex(bytes: &[u8]) -> String {
let mut out = String::with_capacity(bytes.len() * 2);
for byte in bytes {
out.push_str(&format!("{byte:02x}"));
}
out
}
+14 -1
View File
@@ -163,6 +163,12 @@ pub struct LoadedProject {
/// These are ordinary `Marqdo` bindings; the runtime has no print special
/// case and no `Program.print_override`.
pub official_aliases: Vec<marqdo_ir::callable::OfficialAlias>,
/// Project manifest, when the entry belongs to a project.
pub manifest: Option<Manifest>,
/// Verified lock file, when present (lock v4).
pub lock: Option<LockFile>,
/// Resolved `marqdo.yaml.extensions` activation sources (static paths only).
pub extension_sources: Vec<marqdo_package::ResolvedExtension>,
}
impl LoadedProject {
@@ -271,7 +277,7 @@ pub fn load(entry: &Path) -> Result<LoadedProject, String> {
}
None
};
let resolver = PackageResolver::new(root.clone(), manifest.clone(), lock);
let resolver = PackageResolver::new(root.clone(), manifest.clone(), lock.clone());
let entry_module = resolver.resolve_entry(&entry)?;
let stdlib = StdlibBundle::discover().map_err(|error| format!("stdlib: {error}"))?;
let mut loader = Loader {
@@ -290,6 +296,10 @@ pub fn load(entry: &Path) -> Result<LoadedProject, String> {
// the target module/function; only aliases the program actually references
// load their module, and the runtime binds them as ordinary Marqdo calls.
let official_aliases = loader.load_official_aliases()?;
let extension_sources = loader
.resolver
.resolve_extension_sources()
.map_err(|error| format!("extension selection: {error}"))?;
let stdlib_info = loader.stdlib.as_ref().map(|bundle| StdlibInfo {
version: bundle.version().to_string(),
@@ -314,6 +324,9 @@ pub fn load(entry: &Path) -> Result<LoadedProject, String> {
diagnostics: loader.diagnostics,
stdlib: stdlib_info,
official_aliases,
manifest,
lock,
extension_sources,
})
}
+9 -1
View File
@@ -8,6 +8,7 @@ mod analysis;
mod args;
mod commands;
mod extension_descriptors;
mod extension_selection;
mod loader;
mod output;
mod project_prepare;
@@ -261,6 +262,12 @@ struct InspectArgs {
/// Print sandbox/platform capability report.
#[arg(long)]
platform: bool,
/// Print declared/loaded extension identities (never grants).
#[arg(long)]
extensions: bool,
/// Explicitly selected plugin manifest for extension inspection (repeatable).
#[arg(long = "plugin", value_name = "PATH")]
plugin: Vec<PathBuf>,
/// Machine readable JSON output.
#[arg(long)]
json: bool,
@@ -421,8 +428,9 @@ fn dispatch() -> i32 {
ir: args.ir,
refs: args.refs,
platform: args.platform,
extensions: args.extensions,
};
commands::inspect(args.file.as_deref(), &flags, args.json)
commands::inspect(args.file.as_deref(), &flags, args.json, &args.plugin)
}
Command::Run(args) => commands::execute(
args.file.as_deref(),
+50 -2
View File
@@ -14,8 +14,10 @@
use std::path::PathBuf;
use marqdo_ir::callable::CallableRegistry;
use marqdo_package::{ExtensionKind, LockedExtension};
use crate::extension_descriptors::{read_plugin_descriptors, PrepareError, StaticPluginSet};
use crate::extension_selection;
use crate::loader::{self, FileDiagnostic, LoadedProject};
/// Options that influence static preparation.
@@ -37,6 +39,11 @@ pub struct PreparedProgram {
/// evidence) can report the same static table without rebuilding it.
#[allow(dead_code)]
pub registry: CallableRegistry,
/// Static identities of the declared extensions, already compared with the
/// lock when one is present (never grants). Consumed by
/// `inspect --extensions` and evidence.
#[allow(dead_code)]
pub extension_identities: Vec<LockedExtension>,
}
/// Prepare one document without executing any project or extension code.
@@ -49,8 +56,48 @@ pub fn prepare(
let mut loaded = loader::load(file.unwrap_or_else(|| std::path::Path::new("index.mq.md")))
.map_err(|message| default_load_error(&message))?;
// T2: extension descriptors are read from manifests only.
let plugins = read_plugin_descriptors(&options.plugins)?;
// T2: extension descriptors are read from manifests only. Explicit CLI
// `--plugin` paths are merged with the project's declared and locked
// activation sources; CLI paths remain a development form and grant
// nothing by themselves.
let mut plugin_paths = options.plugins.clone();
for extension in &loaded.extension_sources {
if extension.kind == ExtensionKind::Plugin {
plugin_paths.push(extension.path.clone());
}
}
plugin_paths.sort();
plugin_paths.dedup();
let plugins = read_plugin_descriptors(&plugin_paths)?;
// T3a: declared extensions must have a locked identity (lock v4). The
// declaration is activation, not authorization; a mismatched/missing lock
// is fail-closed rather than silently "latest".
let extension_identities =
extension_selection::extension_identities(&loaded.extension_sources)?;
if !loaded.extension_sources.is_empty() {
match &loaded.lock {
Some(lock) => {
lock.validate_extension_declarations(
loaded
.manifest
.as_ref()
.expect("extension sources require a project manifest"),
)
.map_err(|message| PrepareError::load("ext.extension_lock_mismatch", message))?;
extension_selection::validate_against_lock(lock, &extension_identities)?;
}
None => {
return Err(PrepareError::load(
"ext.extension_lock_mismatch",
format!(
"the project declares {} extension(s) but marqdo.lock is missing; run `marqdo lock` first",
loaded.extension_sources.len()
),
));
}
}
}
// T3: unique static table. Duplicate exports/builtin shadowing are rejected
// before any call site can be bound.
@@ -126,6 +173,7 @@ pub fn prepare(
loaded,
plugins,
registry,
extension_identities,
})
}
+495
View File
@@ -0,0 +1,495 @@
//! Extension selection and lock v4 conformance (RFC-EXT-0001 §6.6).
//!
//! These are black-box CLI tests: `marqdo.yaml.extensions` declares activation
//! sources, `marqdo lock` records their exact identity, and `check`/`run`
//! compare the current declaration with the lock before using any extension.
#![cfg(unix)]
use std::path::{Path, PathBuf};
use std::process::{Command, Output};
use std::sync::atomic::{AtomicU32, Ordering};
use marqdo_plugin_abi::{sha256_file, HostTarget};
static COUNTER: AtomicU32 = AtomicU32::new(0);
struct TempDir(PathBuf);
impl TempDir {
fn new(tag: &str) -> Self {
let id = COUNTER.fetch_add(1, Ordering::Relaxed);
let path = std::env::temp_dir().join(format!(
"marqdo-ext-selection-{}-{id}-{tag}",
std::process::id()
));
std::fs::create_dir_all(&path).unwrap();
Self(path)
}
fn path(&self) -> &Path {
&self.0
}
}
impl Drop for TempDir {
fn drop(&mut self) {
let _ = std::fs::remove_dir_all(&self.0);
}
}
fn repo() -> PathBuf {
Path::new(env!("CARGO_MANIFEST_DIR"))
.parent()
.unwrap()
.parent()
.unwrap()
.to_path_buf()
}
fn cli(args: &[&str], dir: &Path) -> Output {
Command::new(env!("CARGO_BIN_EXE_marqdo"))
.args(args)
.current_dir(dir)
.output()
.unwrap()
}
fn stderr(output: &Output) -> String {
String::from_utf8_lossy(&output.stderr).to_string()
}
fn stdout(output: &Output) -> String {
String::from_utf8_lossy(&output.stdout).to_string()
}
fn have_cc() -> bool {
Command::new("cc")
.arg("--version")
.output()
.map(|output| output.status.success())
.unwrap_or(false)
}
fn library_name() -> &'static str {
if cfg!(target_os = "macos") {
"plugin.dylib"
} else {
"plugin.so"
}
}
fn compile_plugin(dir: &Path) -> PathBuf {
let output = dir.join(library_name());
let flags: &[&str] = if cfg!(target_os = "macos") {
&["-dynamiclib", "-fPIC"]
} else {
&["-shared", "-fPIC"]
};
let status = Command::new("cc")
.args(["-std=c11", "-O2"])
.args(flags)
.arg("-I")
.arg(repo().join("include"))
.arg(repo().join("examples/plugin-demo/solver.c"))
.arg("-o")
.arg(&output)
.status()
.expect("cc");
assert!(status.success(), "cc failed");
output
}
fn write_plugin_manifest(adapter: &Path, artifact: &Path) {
let sha = sha256_file(artifact).unwrap();
std::fs::write(
adapter.join("plugin.yaml"),
format!(
r#"plugin:
name: demo.solver
version: 0.1.0
abi: "^1.0"
kind: worker
exports:
- name: solver.add
signature: "($a: Int, $b: Int) -> Int"
requires:
- math.compute
artifacts:
- target: {}
file: {}
sha256: "{sha}"
"#,
HostTarget::current().triple(),
artifact.file_name().unwrap().to_string_lossy()
),
)
.unwrap();
}
fn write_project(project: &Path, extension_yaml: &str) {
std::fs::create_dir_all(project.join("adapter")).unwrap();
std::fs::write(
project.join("marqdo.yaml"),
format!("project:\n name: ext-project\n version: 0.1.0\n{extension_yaml}"),
)
.unwrap();
std::fs::write(
project.join("index.mq.md"),
"## @exec main\n\n`return solver.add(a=20, b=22)`\n",
)
.unwrap();
}
/// Build a project with one worker plugin declared through `extensions:`.
fn plugin_project(tag: &str) -> Option<TempDir> {
if !have_cc() {
eprintln!("skipping: cc is unavailable");
return None;
}
let project = TempDir::new(tag);
let artifact = compile_plugin(&project.path().join("adapter").create_dir_all_ok());
write_plugin_manifest(&project.path().join("adapter"), &artifact);
write_project(
project.path(),
"extensions:\n plugins:\n - from: ./adapter/plugin.yaml\n",
);
Some(project)
}
fn lock(project: &Path) -> Output {
cli(&["lock"], project)
}
#[test]
fn declared_plugin_extension_locks_and_runs() {
let Some(project) = plugin_project("positive") else {
return;
};
let locked = lock(project.path());
assert_eq!(locked.status.code(), Some(0), "{}", stderr(&locked));
let lock_text = std::fs::read_to_string(project.path().join("marqdo.lock")).unwrap();
assert!(lock_text.contains("lock_version: 4"));
assert!(lock_text.contains("kind: plugin"));
assert!(lock_text.contains("source: ./adapter/plugin.yaml"));
let check = cli(&["check", "index.mq.md"], project.path());
assert_eq!(check.status.code(), Some(0), "{}", stderr(&check));
let run = cli(
&["run", "index.mq.md", "--allow-plugin", "demo.solver"],
project.path(),
);
assert_eq!(run.status.code(), Some(0), "{}", stderr(&run));
}
#[test]
fn declared_extension_without_a_lock_is_fail_closed() {
let Some(project) = plugin_project("no-lock") else {
return;
};
let check = cli(&["check", "index.mq.md"], project.path());
assert_eq!(check.status.code(), Some(1), "{}", stderr(&check));
assert!(
stderr(&check).contains("ext.extension_lock_mismatch"),
"{}",
stderr(&check)
);
assert!(stderr(&check).contains("marqdo lock"), "{}", stderr(&check));
}
#[test]
fn changed_manifest_after_lock_is_rejected() {
let Some(project) = plugin_project("manifest-change") else {
return;
};
assert_eq!(lock(project.path()).status.code(), Some(0));
let adapter = project.path().join("adapter");
let manifest = std::fs::read_to_string(adapter.join("plugin.yaml")).unwrap();
std::fs::write(
adapter.join("plugin.yaml"),
manifest.replace("version: 0.1.0", "version: 0.2.0"),
)
.unwrap();
let check = cli(&["check", "index.mq.md"], project.path());
assert_eq!(check.status.code(), Some(1), "{}", stderr(&check));
assert!(
stderr(&check).contains("ext.extension_lock_mismatch"),
"{}",
stderr(&check)
);
}
#[test]
fn changed_artifact_after_lock_fails_before_main_runs() {
let Some(project) = plugin_project("artifact-change") else {
return;
};
assert_eq!(lock(project.path()).status.code(), Some(0));
let artifact = project.path().join("adapter").join(library_name());
let mut bytes = std::fs::read(&artifact).unwrap();
bytes.push(0);
std::fs::write(&artifact, bytes).unwrap();
let run = cli(
&["run", "index.mq.md", "--allow-plugin", "demo.solver"],
project.path(),
);
assert_eq!(run.status.code(), Some(1), "{}", stderr(&run));
assert!(
stderr(&run).contains("ext.artifact_integrity"),
"{}",
stderr(&run)
);
assert!(stdout(&run).is_empty());
}
#[test]
fn extension_source_traversal_is_rejected_at_load() {
let project = TempDir::new("traversal");
write_project(
project.path(),
"extensions:\n plugins:\n - from: ../escape/plugin.yaml\n",
);
let check = cli(&["check", "index.mq.md"], project.path());
assert_eq!(check.status.code(), Some(2), "{}", stderr(&check));
assert!(
stderr(&check).contains("extension") || stderr(&check).contains("must stay inside"),
"{}",
stderr(&check)
);
}
#[test]
fn undeclared_dependency_alias_is_rejected() {
let project = TempDir::new("alias");
write_project(
project.path(),
"extensions:\n plugins:\n - from: \"@missing/plugin.yaml\"\n",
);
let check = cli(&["check", "index.mq.md"], project.path());
assert_eq!(check.status.code(), Some(2), "{}", stderr(&check));
assert!(
stderr(&check).contains("not a declared dependency"),
"{}",
stderr(&check)
);
}
#[test]
fn lock_v3_is_rejected_with_an_explicit_migration() {
let Some(project) = plugin_project("v3") else {
return;
};
let lock_path = project.path().join("marqdo.lock");
std::fs::write(
&lock_path,
"lock_version: 3\ncontent_profile_version: 1\nroot:\n package: root:ext-project@0.1.0\n manifest_digest: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\npackages: []\nroot_dependencies: {}\n",
)
.unwrap();
let check = cli(&["check", "index.mq.md"], project.path());
assert!(!check.status.success(), "{}", stderr(&check));
assert!(
stderr(&check).contains("lock v3 is superseded by lock v4"),
"{}",
stderr(&check)
);
assert!(!stdout(&check).contains("ok"));
}
#[test]
fn pure_and_strict_refuse_project_declared_extensions() {
let Some(project) = plugin_project("modes") else {
return;
};
assert_eq!(lock(project.path()).status.code(), Some(0));
let pure = cli(&["run", "index.mq.md", "--mode", "pure"], project.path());
assert_eq!(pure.status.code(), Some(2), "{}", stderr(&pure));
let strict = cli(&["run", "index.mq.md", "--mode", "strict"], project.path());
assert_eq!(strict.status.code(), Some(2), "{}", stderr(&strict));
}
#[test]
fn provider_extension_is_locked_but_still_requires_an_exact_grant() {
let project = TempDir::new("provider");
std::fs::create_dir_all(project.path().join("vendor/lib")).unwrap();
let artifact = project.path().join("vendor/lib/libsensor.so");
std::fs::write(&artifact, b"fixture provider artifact").unwrap();
let sha = sha256_file(&artifact).unwrap();
std::fs::write(
project.path().join("vendor/provider.json"),
format!(
r#"{{
"schema": "marqdo.provider",
"schema_version": 2,
"name": "demo.sensor",
"version": "0.1.0",
"abi": "c-abi-1",
"transport": "worker",
"kinds": ["demo.sensor"],
"artifacts": [{{"target": "{}", "path": "lib/libsensor.so", "sha256": "{sha}"}}],
"permissions_requested": []
}}"#,
HostTarget::current().triple()
),
)
.unwrap();
write_project(
project.path(),
"extensions:\n providers:\n - from: ./vendor/provider.json\n",
);
std::fs::write(
project.path().join("index.mq.md"),
"## @exec main\n\n`流 = resource.open(\"demo.sensor\", \"unit-1\", [\"read\"])`\n\n`return resource.close(流)`\n",
)
.unwrap();
let locked = lock(project.path());
assert_eq!(locked.status.code(), Some(0), "{}", stderr(&locked));
let lock_text = std::fs::read_to_string(project.path().join("marqdo.lock")).unwrap();
assert!(lock_text.contains("kind: provider"));
// Locked identity is not a grant: the provider is selected from the
// manifest but `--allow-provider` is still required before any worker.
let no_grant = cli(&["run", "index.mq.md"], project.path());
assert_eq!(no_grant.status.code(), Some(1), "{}", stderr(&no_grant));
assert!(
stderr(&no_grant).contains("permission.denied"),
"{}",
stderr(&no_grant)
);
}
trait CreateDirOk {
fn create_dir_all_ok(&self) -> PathBuf;
}
impl CreateDirOk for PathBuf {
fn create_dir_all_ok(&self) -> PathBuf {
std::fs::create_dir_all(self).unwrap();
self.clone()
}
}
#[test]
fn inspect_extensions_reports_lock_identity_without_executing() {
let Some(project) = plugin_project("inspect") else {
return;
};
assert_eq!(lock(project.path()).status.code(), Some(0));
let artifact = project.path().join("adapter").join(library_name());
std::fs::remove_file(&artifact).unwrap();
// Inspection is static: a missing artifact does not prevent identity
// reporting, and no worker is started.
let output = cli(
&["inspect", "index.mq.md", "--extensions", "--json"],
project.path(),
);
assert_eq!(output.status.code(), Some(0), "{}", stderr(&output));
let report: serde_json::Value = serde_json::from_str(&stdout(&output)).unwrap();
let declared = report["extensions"]["declared"].as_array().unwrap();
assert_eq!(declared.len(), 1);
assert_eq!(declared[0]["kind"], "plugin");
assert_eq!(declared[0]["status"], "locked");
assert_eq!(declared[0]["authorization"], "not_granted");
assert_eq!(declared[0]["name"], "demo.solver");
let plugins = report["extensions"]["plugins"].as_array().unwrap();
assert_eq!(plugins[0]["package"], "demo.solver");
assert_eq!(plugins[0]["exports"][0]["name"], "solver.add");
assert_eq!(plugins[0]["authorization"], "not_granted");
}
#[test]
fn cli_and_manifest_selection_of_the_same_plugin_is_idempotent() {
let Some(project) = plugin_project("idempotent") else {
return;
};
assert_eq!(lock(project.path()).status.code(), Some(0));
let adapter = project.path().join("adapter");
let check = cli(
&[
"check",
"index.mq.md",
"--plugin",
adapter.to_str().unwrap(),
],
project.path(),
);
assert_eq!(check.status.code(), Some(0), "{}", stderr(&check));
}
#[test]
fn two_different_manifests_for_one_package_conflict() {
let Some(project) = plugin_project("conflict") else {
return;
};
let second = project.path().join("adapter-v2");
std::fs::create_dir_all(&second).unwrap();
let artifact = project.path().join("adapter").join(library_name());
std::fs::copy(&artifact, second.join(library_name())).unwrap();
write_plugin_manifest(&second, &second.join(library_name()));
let manifest = std::fs::read_to_string(second.join("plugin.yaml")).unwrap();
std::fs::write(
second.join("plugin.yaml"),
manifest.replace("version: 0.1.0", "version: 0.2.0"),
)
.unwrap();
let check = cli(
&[
"check",
"index.mq.md",
"--plugin",
project.path().join("adapter").to_str().unwrap(),
"--plugin",
second.to_str().unwrap(),
],
project.path(),
);
assert_eq!(check.status.code(), Some(2), "{}", stderr(&check));
assert!(
stderr(&check).contains("ext.duplicate_callable"),
"{}",
stderr(&check)
);
}
#[test]
fn declared_kernel_extension_is_activated_from_the_manifest() {
let project = TempDir::new("kernel");
std::fs::create_dir_all(project.path().join("kernel")).unwrap();
let provider = project.path().join("kernel/mocklang");
std::fs::write(
&provider,
"#!/bin/sh\ncat >/dev/null\nprintf '%s' '{\"type\":\"int\",\"decimal\":\"42\"}'\n",
)
.unwrap();
#[cfg(unix)]
{
use std::os::unix::fs::PermissionsExt;
std::fs::set_permissions(&provider, std::fs::Permissions::from_mode(0o755)).unwrap();
}
let digest = sha256_file(&provider).unwrap();
std::fs::write(
project.path().join("kernel/kernel.json"),
format!(
r#"{{
"provider_id": "mocklang-provider",
"languages": ["mocklang-only"],
"wire_version": 1,
"entrypoint": "{}",
"permissions_requested": [],
"digest": "{digest}"
}}"#,
provider.display()
),
)
.unwrap();
write_project(
project.path(),
"extensions:\n kernels:\n - from: ./kernel/kernel.json\n",
);
std::fs::write(
project.path().join("index.mq.md"),
"## @exec main\n\n`结果 = foreign.call(ref(\"#代码\"), {})`\n\n`return 结果`\n\n### @knowledge 代码\n\n```mocklang-only\ninert\n```\n",
)
.unwrap();
assert_eq!(lock(project.path()).status.code(), Some(0));
let lock_text = std::fs::read_to_string(project.path().join("marqdo.lock")).unwrap();
assert!(lock_text.contains("kind: kernel"));
let run = cli(&["run", "index.mq.md", "--allow-foreign"], project.path());
assert_eq!(run.status.code(), Some(0), "{}", stderr(&run));
}
+1 -1
View File
@@ -170,7 +170,7 @@ fn pinned_git_dependency_locks_syncs_and_runs() {
String::from_utf8_lossy(&lock.stderr)
);
let lock_text = std::fs::read_to_string(root.join("marqdo.lock")).unwrap();
assert!(lock_text.contains("lock_version: 3"));
assert!(lock_text.contains("lock_version: 4"));
assert!(lock_text.contains("root_dependencies:"));
assert!(lock_text.contains("instance_id: dep:remote@0.3.0#"));
assert!(lock_text.contains("kind: git"));
+642 -7
View File
@@ -116,6 +116,233 @@ pub struct NetRequests {
pub hosts: Vec<String>,
}
/// Extension category explicitly selected by a project manifest
/// (RFC-EXT-0001 §6).
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum ExtensionKind {
/// Callable ABI plugin (`plugin.yaml`).
Plugin,
/// Foreign kernel descriptor (`kernel.json`).
Kernel,
/// Resource provider manifest (`provider.json`).
Provider,
}
impl ExtensionKind {
/// Stable lowercase name used in lock files and diagnostics.
pub const fn as_str(self) -> &'static str {
match self {
ExtensionKind::Plugin => "plugin",
ExtensionKind::Kernel => "kernel",
ExtensionKind::Provider => "provider",
}
}
/// Parse the stable lowercase name.
pub fn parse(value: &str) -> Option<Self> {
match value {
"plugin" => Some(ExtensionKind::Plugin),
"kernel" => Some(ExtensionKind::Kernel),
"provider" => Some(ExtensionKind::Provider),
_ => None,
}
}
}
impl std::fmt::Display for ExtensionKind {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.write_str(self.as_str())
}
}
/// One explicit extension activation source.
///
/// Allowed forms are deliberately narrow (RFC-EXT-0001 §6.3):
///
/// * `./relative/path` — a regular file inside the current project;
/// * `@alias/relative/path` — a regular file inside a locked dependency.
///
/// Absolute paths, `..` traversal, HTTP(S) URLs, globs and implicit searches
/// are rejected. A declaration is activation/visibility, never a grant.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ExtensionSource {
/// Declared source string.
pub from: String,
}
impl ExtensionSource {
/// Parse and validate the source form.
pub fn resolve(
&self,
dependencies: &BTreeMap<String, Dependency>,
) -> Result<ResolvedExtensionSource, String> {
let value = self.from.trim();
if value.is_empty() {
return Err("extension `from` must not be empty".to_string());
}
if let Some(rest) = value.strip_prefix("./") {
let relative = safe_relative(rest, "extension source")?;
return Ok(ResolvedExtensionSource::ProjectRelative(relative));
}
if let Some(rest) = value.strip_prefix('@') {
let (alias, relative) = rest.split_once('/').ok_or_else(|| {
format!("extension source `{value}` must be `@alias/relative/path`")
})?;
if alias.is_empty() {
return Err(format!("extension source `{value}` has an empty alias"));
}
if !dependencies.contains_key(alias) {
return Err(format!(
"extension source `{value}` uses `@{alias}`, which is not a declared dependency"
));
}
let relative = safe_relative(relative, "extension source")?;
return Ok(ResolvedExtensionSource::Dependency {
alias: alias.to_string(),
relative,
});
}
Err(format!(
"extension source `{value}` must be `./relative/path` or `@alias/relative/path`; absolute paths, URLs and implicit discovery are not allowed"
))
}
}
/// A resolved extension activation source (regular file inside a package).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ResolvedExtension {
/// Extension category declared by the manifest block.
pub kind: ExtensionKind,
/// Declared `from` string (identity key in the lock).
pub from: String,
/// Canonical manifest/descriptor file path.
pub path: PathBuf,
/// Logical owner package instance (`root:...` or a dependency instance id).
pub logical_owner: String,
/// Canonical package root that contains the file.
pub package_root: PathBuf,
}
/// A parsed extension source relative to a project or dependency.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ResolvedExtensionSource {
/// `./relative/path` below the project root.
ProjectRelative(PathBuf),
/// `@alias/relative/path` below a declared dependency.
Dependency {
/// Dependency alias.
alias: String,
/// Package-relative path.
relative: PathBuf,
},
}
fn resolve_extension_file(
package_root: &Path,
relative: &Path,
kind: ExtensionKind,
from: &str,
) -> Result<PathBuf, String> {
let candidate = package_root.join(relative);
let canonical = candidate.canonicalize().map_err(|error| {
format!(
"cannot open {kind} extension source `{from}` at `{}`: {error}",
candidate.display()
)
})?;
if !canonical.starts_with(package_root) {
return Err(format!(
"{kind} extension source `{from}` escapes its owning package"
));
}
let metadata = std::fs::metadata(&canonical)
.map_err(|error| format!("cannot stat {kind} extension source `{from}`: {error}"))?;
if !metadata.is_file() {
return Err(format!(
"{kind} extension source `{from}` must be a regular file"
));
}
Ok(canonical)
}
fn safe_relative(value: &str, what: &str) -> Result<PathBuf, String> {
if value.is_empty() {
return Err(format!("{what} path must not be empty"));
}
let mut normalised = PathBuf::new();
for component in Path::new(value).components() {
match component {
std::path::Component::Normal(part) => normalised.push(part),
std::path::Component::CurDir => {}
std::path::Component::ParentDir
| std::path::Component::RootDir
| std::path::Component::Prefix(_) => {
return Err(format!(
"{what} path `{value}` must stay inside its package (no `..`, absolute or rooted paths)"
))
}
}
}
if normalised.as_os_str().is_empty() {
return Err(format!("{what} path must not be empty"));
}
Ok(normalised)
}
/// The `extensions:` block of `marqdo.yaml` (explicit activation sources).
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct Extensions {
/// Callable plugin manifests.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub plugins: Vec<ExtensionSource>,
/// Foreign kernel descriptors.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub kernels: Vec<ExtensionSource>,
/// Resource provider manifests.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub providers: Vec<ExtensionSource>,
}
impl Extensions {
/// Whether no extension is declared.
pub fn is_empty(&self) -> bool {
self.plugins.is_empty() && self.kernels.is_empty() && self.providers.is_empty()
}
/// Iterate `(kind, source)` in deterministic kind order.
pub fn iter(&self) -> impl Iterator<Item = (ExtensionKind, &ExtensionSource)> {
self.plugins
.iter()
.map(|source| (ExtensionKind::Plugin, source))
.chain(
self.kernels
.iter()
.map(|source| (ExtensionKind::Kernel, source)),
)
.chain(
self.providers
.iter()
.map(|source| (ExtensionKind::Provider, source)),
)
}
fn validate(&self, dependencies: &BTreeMap<String, Dependency>) -> Result<(), String> {
let mut seen: std::collections::BTreeSet<(ExtensionKind, String)> =
std::collections::BTreeSet::new();
for (kind, source) in self.iter() {
source.resolve(dependencies)?;
if !seen.insert((kind, source.from.clone())) {
return Err(format!(
"{kind} extension source `{}` is declared more than once",
source.from
));
}
}
Ok(())
}
}
/// The `marqdo.yaml` project manifest.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Manifest {
@@ -130,6 +357,9 @@ pub struct Manifest {
/// Capability requests.
#[serde(default, skip_serializing_if = "CapabilityRequests::is_empty")]
pub capabilities: CapabilityRequests,
/// Explicit extension activation sources (never authorization).
#[serde(default, skip_serializing_if = "Option::is_none")]
pub extensions: Option<Extensions>,
}
/// A requested plugin (installation is not authorization).
@@ -173,6 +403,9 @@ impl Manifest {
));
}
}
if let Some(extensions) = &self.extensions {
extensions.validate(&self.dependencies)?;
}
Ok(())
}
@@ -192,6 +425,7 @@ impl Manifest {
dependencies: BTreeMap::new(),
plugins: BTreeMap::new(),
capabilities: CapabilityRequests::default(),
extensions: None,
}
}
}
@@ -392,6 +626,59 @@ impl PackageResolver {
&self.root
}
/// Resolve and validate every `marqdo.yaml.extensions` source to a real
/// regular file inside its owning package (RFC-EXT-0001 §6.3).
///
/// This is pure static path resolution: no extension binary is loaded, no
/// script is executed and no grant is implied. Resolution order is sorted by
/// `(kind, from)` so the resulting fact table never depends on YAML order.
pub fn resolve_extension_sources(&self) -> Result<Vec<ResolvedExtension>, String> {
let Some(manifest) = &self.manifest else {
return Ok(Vec::new());
};
let Some(extensions) = &manifest.extensions else {
return Ok(Vec::new());
};
let root = self
.root
.canonicalize()
.map_err(|error| format!("cannot resolve project root: {error}"))?;
let owner = root_instance(Some(manifest));
let mut resolved = Vec::new();
for (kind, source) in extensions.iter() {
match source.resolve(&manifest.dependencies)? {
ResolvedExtensionSource::ProjectRelative(relative) => {
let path = resolve_extension_file(&root, &relative, kind, &source.from)?;
resolved.push(ResolvedExtension {
kind,
from: source.from.clone(),
path,
logical_owner: owner.clone(),
package_root: root.clone(),
});
}
ResolvedExtensionSource::Dependency { alias, relative } => {
let module = self.resolve_alias(&alias)?;
let package_root =
module.package.module_root.canonicalize().map_err(|error| {
format!("cannot resolve package root for dependency `{alias}`: {error}")
})?;
let path =
resolve_extension_file(&package_root, &relative, kind, &source.from)?;
resolved.push(ResolvedExtension {
kind,
from: source.from.clone(),
path,
logical_owner: module.package.instance_id.clone(),
package_root,
});
}
}
}
resolved.sort_by(|left, right| (&left.kind, &left.from).cmp(&(&right.kind, &right.from)));
Ok(resolved)
}
/// The project manifest, if the entry is part of a project.
pub fn manifest(&self) -> Option<&Manifest> {
self.manifest.as_ref()
@@ -849,6 +1136,7 @@ impl PackageResolver {
},
packages,
root_dependencies,
extensions: Vec::new(),
};
lock.validate()?;
Ok(ResolvedLockGraph {
@@ -1115,7 +1403,7 @@ fn package_name_version(manifest: &Option<Manifest>, alias: &str) -> (String, St
}
/// Lock format version written by this build.
pub const LOCK_VERSION: u32 = 3;
pub const LOCK_VERSION: u32 = 4;
/// One package instance in `marqdo.lock` v3.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
@@ -1138,7 +1426,7 @@ pub struct LockedPackage {
pub dependencies: BTreeMap<String, String>,
}
/// A structured package source in lock v3.
/// A structured package source in lock v4.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum LockedSource {
@@ -1194,7 +1482,7 @@ impl LockedSource {
}
}
/// Root entry of a lock v3 graph.
/// Root entry of a lock v4 graph.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct LockedRoot {
/// Logical root package instance (`root:<name>@<version>`).
@@ -1212,6 +1500,32 @@ impl Default for LockedRoot {
}
}
/// One locked extension identity (lock v4).
///
/// Records the exact selected extension source, manifest digest, artifact
/// digest and target so a later `run` can prove it uses the same bytes the
/// project locked. A lock is identity, not authorization: grants remain
/// separate CLI/operator decisions.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct LockedExtension {
/// Extension category.
pub kind: ExtensionKind,
/// Owner package instance (`root:...` or a dependency instance id).
pub logical_owner: String,
/// Stable declared name (plugin package, kernel provider id, provider name).
pub name: String,
/// Declared extension version.
pub version: String,
/// SHA-256 of the exact manifest file bytes (lowercase hex).
pub manifest_digest: String,
/// SHA-256 of the selected target artifact (lowercase hex).
pub artifact_digest: String,
/// Selected host target triple.
pub selected_target: String,
/// Source string as declared in `marqdo.yaml.extensions`.
pub source: String,
}
/// The `marqdo.lock` package-instance graph.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct LockFile {
@@ -1227,6 +1541,9 @@ pub struct LockFile {
/// Root alias -> target package instance.
#[serde(default)]
pub root_dependencies: BTreeMap<String, String>,
/// Locked extension identities, sorted by `(kind, name, logical_owner)`.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub extensions: Vec<LockedExtension>,
}
impl Default for LockFile {
@@ -1237,6 +1554,7 @@ impl Default for LockFile {
root: LockedRoot::default(),
packages: Vec::new(),
root_dependencies: BTreeMap::new(),
extensions: Vec::new(),
}
}
}
@@ -1264,7 +1582,7 @@ pub fn manifest_digest(manifest: &Manifest) -> String {
}
impl LockFile {
/// Parse and validate a lockfile. Only lock v3 is accepted.
/// Parse and validate a lockfile. Only lock v4 is accepted.
pub fn from_yaml(yaml: &str) -> Result<Self, String> {
#[derive(Deserialize)]
struct VersionProbe {
@@ -1273,8 +1591,13 @@ impl LockFile {
let probe: VersionProbe =
serde_yaml::from_str(yaml).map_err(|error| format!("invalid {LOCK_FILE}: {error}"))?;
if probe.lock_version != LOCK_VERSION {
if probe.lock_version == LOCK_VERSION - 1 {
return Err(format!(
"lock v3 is superseded by lock v4 (extension identities); run `marqdo lock` to migrate explicitly. {LOCK_FILE} was not rewritten"
));
}
return Err(format!(
"unsupported lock_version {}; lock v3 is required. Run `marqdo lock` to regenerate the graph",
"unsupported lock_version {}; lock v{LOCK_VERSION} is required. Run `marqdo lock` to regenerate the graph",
probe.lock_version
));
}
@@ -1282,6 +1605,7 @@ impl LockFile {
serde_yaml::from_str(yaml).map_err(|error| format!("invalid {LOCK_FILE}: {error}"))?;
lock.packages
.sort_by(|a, b| a.instance_id.cmp(&b.instance_id));
lock.sort_extensions();
lock.validate()?;
Ok(lock)
}
@@ -1299,6 +1623,7 @@ impl LockFile {
sorted
.packages
.sort_by(|a, b| a.instance_id.cmp(&b.instance_id));
sorted.sort_extensions();
serde_yaml::to_string(&sorted).unwrap_or_default()
}
@@ -1309,6 +1634,115 @@ impl LockFile {
hex::encode(hasher.finalize())
}
fn sort_extensions(&mut self) {
self.extensions.sort_by(|left, right| {
(&left.kind, &left.name, &left.logical_owner).cmp(&(
&right.kind,
&right.name,
&right.logical_owner,
))
});
}
/// Look up one locked extension identity.
pub fn extension(
&self,
kind: ExtensionKind,
name: &str,
logical_owner: &str,
) -> Option<&LockedExtension> {
self.extensions.iter().find(|extension| {
extension.kind == kind
&& extension.name == name
&& extension.logical_owner == logical_owner
})
}
/// Compare an actual extension selection with the lock (RFC-EXT-0001 §6.4).
///
/// The same complete identity and digests are idempotent; any missing,
/// extra or changed identity is an error. The caller turns this into
/// `ext.extension_lock_mismatch`; this layer returns a descriptive string.
pub fn validate_extension_selection(&self, actual: &[LockedExtension]) -> Result<(), String> {
let mut seen: BTreeSet<(ExtensionKind, String, String)> = BTreeSet::new();
for extension in actual {
let key = (
extension.kind,
extension.name.clone(),
extension.logical_owner.clone(),
);
if !seen.insert(key.clone()) {
return Err(format!(
"extension {} `{}` for owner `{}` is selected more than once",
key.0, key.1, key.2
));
}
match self.extension(key.0, &key.1, &key.2) {
Some(locked) if locked == extension => {}
Some(locked) => {
return Err(format!(
"extension {} `{}` identity mismatch: lock has manifest {} artifact {} target {}, selection has manifest {} artifact {} target {}",
key.0,
key.1,
locked.manifest_digest,
locked.artifact_digest,
locked.selected_target,
extension.manifest_digest,
extension.artifact_digest,
extension.selected_target
))
}
None => {
return Err(format!(
"extension {} `{}` for owner `{}` is not present in {LOCK_FILE}; run `marqdo lock` and pass the selected manifest explicitly",
key.0, key.1, key.2
))
}
}
}
for locked in &self.extensions {
if !seen.contains(&(
locked.kind,
locked.name.clone(),
locked.logical_owner.clone(),
)) {
return Err(format!(
"locked extension {} `{}` for owner `{}` is not selected in this run",
locked.kind, locked.name, locked.logical_owner
));
}
}
Ok(())
}
/// Insert one exact extension identity; identical insertion is idempotent.
pub fn merge_extension(&mut self, extension: LockedExtension) -> Result<(), String> {
match self.extension(
extension.kind,
&extension.name,
&extension.logical_owner,
) {
Some(existing) if existing == &extension => Ok(()),
Some(existing) => Err(format!(
"extension {} `{}` for owner `{}` already has manifest {} artifact {} target {}; refusing to replace it with manifest {} artifact {} target {}",
extension.kind,
extension.name,
extension.logical_owner,
existing.manifest_digest,
existing.artifact_digest,
existing.selected_target,
extension.manifest_digest,
extension.artifact_digest,
extension.selected_target
)),
None => {
self.extensions.push(extension);
self.sort_extensions();
Ok(())
}
}
}
/// Find a locked package by instance id.
pub fn package(&self, instance_id: &str) -> Option<&LockedPackage> {
self.packages
@@ -1445,6 +1879,112 @@ impl LockFile {
));
}
}
let mut extension_keys = BTreeSet::new();
let mut extension_sources = BTreeSet::new();
for extension in &self.extensions {
if !extension_keys.insert((
extension.kind,
extension.name.clone(),
extension.logical_owner.clone(),
)) {
return Err(format!(
"duplicate extension {} `{}` for owner `{}` in {LOCK_FILE}",
extension.kind, extension.name, extension.logical_owner
));
}
if extension.name.trim().is_empty() {
return Err("lock extension name must not be empty".to_string());
}
if extension.version.trim().is_empty() {
return Err(format!(
"extension {} `{}` has an empty version",
extension.kind, extension.name
));
}
if extension.logical_owner.trim().is_empty() {
return Err(format!(
"extension {} `{}` has an empty logical_owner",
extension.kind, extension.name
));
}
if !is_hex_digest(&extension.manifest_digest) {
return Err(format!(
"extension {} `{}` manifest_digest is not a 64-character lowercase hex digest",
extension.kind, extension.name
));
}
if !is_hex_digest(&extension.artifact_digest) {
return Err(format!(
"extension {} `{}` artifact_digest is not a 64-character lowercase hex digest",
extension.kind, extension.name
));
}
if extension.selected_target.trim().is_empty() {
return Err(format!(
"extension {} `{}` has an empty selected_target",
extension.kind, extension.name
));
}
if extension.source.trim().is_empty() {
return Err(format!(
"extension {} `{}` has an empty source",
extension.kind, extension.name
));
}
if !extension_sources.insert((extension.kind, extension.source.clone())) {
return Err(format!(
"extension {} source `{}` is locked more than once",
extension.kind, extension.source
));
}
}
Ok(())
}
/// Validate that locked extensions match the manifest declarations.
///
/// Declaration is activation, not authorization; this only checks identity
/// bookkeeping. A manifest that declares an extension without a lock entry
/// (or vice versa) requires an explicit `marqdo lock`.
pub fn validate_extension_declarations(&self, manifest: &Manifest) -> Result<(), String> {
let declared: Vec<(ExtensionKind, String)> = manifest
.extensions
.as_ref()
.map(|extensions| {
extensions
.iter()
.map(|(kind, source)| (kind, source.from.trim().to_string()))
.collect()
})
.unwrap_or_default();
if declared.is_empty() && !self.extensions.is_empty() {
return Err(format!(
"{LOCK_FILE} records extension(s) but the manifest declares none; run `marqdo lock`"
));
}
for (kind, source) in &declared {
let found = self
.extensions
.iter()
.any(|extension| &extension.kind == kind && &extension.source == source);
if !found {
return Err(format!(
"extension {kind} source `{source}` is declared but not locked; run `marqdo lock`"
));
}
}
for extension in &self.extensions {
if !declared
.iter()
.any(|(kind, source)| kind == &extension.kind && source == &extension.source)
{
return Err(format!(
"locked extension {} source `{}` is not declared by the manifest; run `marqdo lock`",
extension.kind, extension.source
));
}
}
Ok(())
}
@@ -1555,6 +2095,7 @@ capabilities:
dependencies: BTreeMap::new(),
},
],
extensions: Vec::new(),
root_dependencies: BTreeMap::from([
(
"a".to_string(),
@@ -1576,13 +2117,107 @@ capabilities:
}
#[test]
fn v1_and_v2_locks_are_rejected_with_a_relock_hint() {
fn old_locks_are_rejected_with_an_explicit_migration() {
for version in [1, 2] {
let yaml = format!("lock_version: {version}\npackages: []\n");
let error = LockFile::from_yaml(&yaml).unwrap_err();
assert!(error.contains("lock v3 is required"), "{error}");
assert!(error.contains("lock v4 is required"), "{error}");
assert!(error.contains("marqdo lock"), "{error}");
}
// v3 is the immediately previous public format: the error must say the
// migration is explicit, not silently reinterpret the document.
let error = LockFile::from_yaml("lock_version: 3\npackages: []\n").unwrap_err();
assert!(
error.contains("lock v3 is superseded by lock v4"),
"{error}"
);
assert!(error.contains("run `marqdo lock`"), "{error}");
}
#[test]
fn extensions_manifest_sources_are_narrow_and_validated() {
let yaml = "project:\n name: p\n version: 0.1.0\ndependencies:\n q:\n path: ./q\nextensions:\n plugins:\n - from: ./adapter/plugin.yaml\n kernels: []\n providers:\n - from: \"@q/adapter/provider.json\"\n";
let manifest = Manifest::from_yaml(yaml).unwrap();
let extensions = manifest.extensions.as_ref().unwrap();
assert_eq!(extensions.plugins.len(), 1);
assert_eq!(extensions.providers.len(), 1);
let resolved = extensions.plugins[0]
.resolve(&manifest.dependencies)
.unwrap();
assert_eq!(
resolved,
ResolvedExtensionSource::ProjectRelative(PathBuf::from("adapter/plugin.yaml"))
);
for bad in [
"extensions:\n plugins:\n - from: /abs/plugin.yaml\n",
"extensions:\n plugins:\n - from: https://example/plugin.yaml\n",
"extensions:\n plugins:\n - from: ../escape/plugin.yaml\n",
"extensions:\n plugins:\n - from: \"@missing/plugin.yaml\"\n",
"extensions:\n plugins:\n - from: \"@q/../../escape\"\n",
"extensions:\n plugins:\n - from: \"\"\n",
] {
let yaml = format!(
"project:\n name: p\n version: 0.1.0\ndependencies:\n q:\n path: ./q\n{bad}"
);
assert!(
Manifest::from_yaml(&yaml).is_err(),
"extension source must be rejected: {bad}"
);
}
}
fn sample_extension(name: &str, digest: char) -> LockedExtension {
LockedExtension {
kind: ExtensionKind::Plugin,
logical_owner: "root:p@0.1.0".into(),
name: name.into(),
version: "0.1.0".into(),
manifest_digest: digest.to_string().repeat(64),
artifact_digest: "b".repeat(64),
selected_target: "x86_64-unknown-linux-gnu".into(),
source: format!("./adapter/{name}/plugin.yaml"),
}
}
#[test]
fn lock_v4_extension_identity_is_deterministic_and_exact() {
let mut lock = LockFile::default();
lock.root.manifest_digest = "a".repeat(64);
lock.merge_extension(sample_extension("demo.ext", 'a'))
.unwrap();
lock.merge_extension(sample_extension("demo.ext", 'a'))
.unwrap();
assert_eq!(lock.extensions.len(), 1);
assert!(lock
.merge_extension(sample_extension("demo.ext", 'c'))
.is_err());
let second = sample_extension("other.ext", 'd');
lock.merge_extension(second.clone()).unwrap();
assert_eq!(lock.extensions[0].name, "demo.ext");
let yaml = lock.to_yaml();
let parsed = LockFile::from_yaml(&yaml).unwrap();
assert_eq!(parsed, lock);
assert!(parsed
.validate_extension_selection(&[
sample_extension("demo.ext", 'a'),
sample_extension("other.ext", 'd'),
])
.is_ok());
assert!(parsed
.validate_extension_selection(&[sample_extension("demo.ext", 'a')])
.is_err());
assert!(parsed
.validate_extension_selection(&[
sample_extension("demo.ext", 'a'),
sample_extension("other.ext", 'd'),
sample_extension("extra.ext", 'e'),
])
.is_err());
let mut changed = sample_extension("demo.ext", 'a');
changed.artifact_digest = "f".repeat(64);
assert!(parsed
.validate_extension_selection(&[changed, sample_extension("other.ext", 'd')])
.is_err());
}
#[test]
+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.
+1 -1
View File
@@ -1,4 +1,4 @@
lock_version: 3
lock_version: 4
content_profile_version: 1
root:
package: root:multi-module@0.1.0
+1 -1
View File
@@ -1,4 +1,4 @@
lock_version: 3
lock_version: 4
content_profile_version: 1
root:
package: root:multi-version@0.1.0
+191
View File
@@ -0,0 +1,191 @@
# 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.
+60 -10
View File
@@ -1,10 +1,12 @@
# Marqdo Project Package Format v3
# Marqdo Project Package Format v4
Status: **lock_version 3 package-instance graph as implemented by S1
(ADR-0016).** Path and pinned Git sources, transitive closure locking,
fail-closed locked resolution, strict `sync`, and content-profile-1 file-set
hashing/materialization are implemented. Registries and SemVer solving remain
out of scope; see §8.
Status: **lock_version 4 package-instance graph plus extension identities
(RFC-EXT-0001 §6, ADR-0056).** Path and pinned Git sources, transitive closure
locking, fail-closed locked resolution, strict `sync`, content-profile-1
file-set hashing/materialization, and explicit `extensions:` activation
sources/identities are implemented. Registries and SemVer solving remain out of
scope; see §8. Lock v3 is rejected with an explicit `marqdo lock` migration
error; it is never reinterpreted silently.
Implementation: `crates/marqdo-package/src/lib.rs` (manifest/lock types and
validation), `crates/cli/src/commands.rs` (`init`, `add`, `remove`, `lock`,
@@ -46,6 +48,12 @@ capabilities: # requests only; not grants
net:
hosts: []
process: false
extensions: # explicit activation sources; never grants
plugins:
- from: ./adapter/plugin.yaml
kernels: []
providers:
- from: "@quantum/adapter/provider.json"
```
### 2.1 Fields
@@ -62,6 +70,7 @@ capabilities: # requests only; not grants
| `capabilities.fs.read` / `.write` | list of strings | no | requested project-relative globs |
| `capabilities.net.hosts` | list of strings | no | requested hosts |
| `capabilities.process` | bool | no | requested process execution |
| `extensions.plugins[]` / `.kernels[]` / `.providers[]` | `{from}` | no | explicit extension activation sources; `from` is `./relative/path` in the project or `@alias/relative/path` in a declared dependency. The alias must be in `dependencies`. Absolute paths, URLs, globs and `..` traversal are rejected. A declaration is not a grant. |
Unknown fields are ignored (the types do not `deny_unknown_fields`). Duplicate
YAML keys follow `serde_yaml` behavior (last one wins); there is no duplicate-key
@@ -78,7 +87,12 @@ validates:
* neither → error "must declare a path or a pinned git source";
* `git` without `rev` → error requiring an exact revision;
* an absolute `path` → error "path must be project-relative";
* for every plugin requirement, `version` is non-empty.
* for every plugin requirement, `version` is non-empty;
* every `extensions.*[].from` is one of the two allowed forms and resolves to a
regular file inside its owning package; duplicates within a kind are
rejected; `@alias` must name a declared dependency. Resolution happens when
the project is loaded (`PackageResolver::resolve_extension_sources`), not in
plain `Manifest::validate`.
Note: a *git* dependency passes manifest validation when pinned, but the
dependency is not resolvable or lockable in this build (§5).
@@ -92,11 +106,13 @@ grants (`spec/security.md` §2). `net` has no implementing host op, and
## 3. `marqdo.lock`
`lock_version: 3` records the complete package-instance closure reachable from
the root manifest. Packages are sorted by `instance_id`:
`lock_version: 4` records the complete package-instance closure reachable from
the root manifest plus the exact identity of every declared extension.
Packages are sorted by `instance_id`; extensions by `(kind, name,
logical_owner)`:
```yaml
lock_version: 3
lock_version: 4
content_profile_version: 1
root:
package: root:quantum@0.1.0
@@ -124,8 +140,42 @@ packages:
dependencies: {}
root_dependencies:
math: dep:math@1.0.0#9e2...
extensions:
- kind: plugin
logical_owner: root:quantum@0.1.0
name: demo.solver
version: 0.1.0
manifest_digest: 4f5c... # sha256 of the exact plugin.yaml bytes
artifact_digest: 9e2... # selected target artifact sha256
selected_target: x86_64-unknown-linux-gnu
source: ./adapter/plugin.yaml
```
An extension lock record binds:
* `kind` — `plugin` | `kernel` | `provider`;
* `logical_owner` — root instance or dependency package instance id;
* `name` / `version` — stable declared identity (kernel descriptors have no
version, so the lock records `wire:<n>`);
* `manifest_digest` — SHA-256 of the exact manifest/descriptor bytes;
* `artifact_digest` — declared selected-target artifact SHA-256 (for a kernel,
the pinned provider executable digest);
* `selected_target` — the host triple selected at lock time;
* `source` — the `from` string exactly as declared.
`marqdo lock` records these identities statically (no extension is executed).
`check`/`sync` compare the current declaration to the lock and fail with
`ext.extension_lock_mismatch` on a missing, extra or changed identity; `run`
additionally verifies the real artifact bytes before starting any worker.
`extensions` is omitted when no extension is declared.
### 3.1 Lock v3 migration
`from_yaml` of a v3 document returns a deterministic error: lock v3 is
superseded by v4 (extension identities), and the user must run `marqdo lock`
to migrate explicitly. No v3 field is silently reinterpreted. Lock v1/v2 keep
their existing relock error with the v4 requirement.
| Field | Semantics |
|---|---|
| `lock_version` | writers emit `3`; readers accept only `3` and tell v1/v2 users to run `marqdo lock` |