feat(ext): single callable binding, provider v2 CLI, capability handlers, stdlib aliases
Implements RFC-EXT-0001 PR-00..PR-07 first pass: - CallSiteKey/CallBindingTable + one frontend binding pass; runtime dispatch by identity - prepare composition root shared by check/run/inspect/Analysis; exact plugin reconciliation - provider.json v2 --provider/--allow-provider worker CLI with fail-closed verification - capability handler registry with real fs.read and audit - verified stdlib public aliases replace print_override/AST scan - docs: specs, ADR-0054/0055/0057/0058, README, CI/release gates, evidence PR-04 extension selection/lock v4 and final frozen-binary evidence remain.
This commit is contained in:
1 parent
9aa536c2c9
commit
1f6fd644a0
54 files changed
+8710
-828
No files matched your search
@@ -0,0 +1,125 @@
|
||||
# ADR-0054: One static callable binding, one runtime dispatch
|
||||
|
||||
- Status: Accepted (2026-11-21)
|
||||
- Supersedes the resolution model of ADR-0009/ADR-0010 where they conflict
|
||||
- Implements: RFC-EXT-0001 §4 (PR-01/PR-02)
|
||||
|
||||
## Context
|
||||
|
||||
The tree had four independent ways to decide what a call means:
|
||||
|
||||
1. `marqdo-frontend/src/calls.rs` checked a Member call's builtin name before
|
||||
its import alias;
|
||||
2. `marqdo-runtime/src/interpreter.rs` checked the import alias before the
|
||||
builtin for the same expression;
|
||||
3. the runtime treated an undeclared `alias.name` as a plugin invocation when
|
||||
`program.external_callables` was empty ("try it at run time");
|
||||
4. `marqdo-cli` synthesised an empty-parameter descriptor (`params: Vec::new()`)
|
||||
for exports that were loaded but not statically described.
|
||||
|
||||
Consequences observed while building RFC-EXT-0001's fixtures:
|
||||
|
||||
* `check` could accept a call that `run` dispatched to a different
|
||||
implementation (or vice versa);
|
||||
* an unknown symbol failed only at run time, with a Host side effect already
|
||||
attempted;
|
||||
* an import alias that happened to equal a builtin dotted namespace (`math`)
|
||||
silently changed the meaning of `math.eval(...)` depending on the pipeline;
|
||||
* plugin arity/name errors could pass static checking and only fail (or
|
||||
succeed with different arguments) at the ABI boundary.
|
||||
|
||||
The language contract (RFC-LANG-0002) already says calls are expressions and
|
||||
that `check` and `run` must agree; the implementation had no such guarantee.
|
||||
|
||||
## Decision
|
||||
|
||||
1. **One registry.** `marqdo_ir::callable::CallableRegistry` is the only static
|
||||
table. It contains builtins (including official bundled-stdlib public
|
||||
aliases), module functions keyed by canonical name plus unique local name,
|
||||
and exact plugin exports (`namespace.function`). Duplicate declarations are
|
||||
rejected when the registry is built; order never decides the answer.
|
||||
2. **One binding pass.** `marqdo_frontend::calls::bind_program_calls(program,
|
||||
registry)` walks every statically visible call expression exactly once and
|
||||
produces `CallBindingTable` plus diagnostics. It replaces the split
|
||||
`validate_module`/`validate_program` priority logic on the CLI path (the
|
||||
standalone frontend keeps a wrapper for single-document tests). The result
|
||||
is installed on `Program::call_bindings`.
|
||||
3. **Deterministic identity.** A call site is
|
||||
`(module id, function id, byte span)` (`CallSiteKey`), never a disk path,
|
||||
registration order or hash-map iteration. A bound target is one of:
|
||||
* `Builtin { canonical_name }` — fixed core function;
|
||||
* `Marqdo { function }` — exact `FunctionId` (module functions and official
|
||||
stdlib aliases such as `打印`/`print` → `io.mq.md::写值`);
|
||||
* `AbiPlugin { package, export, digest, param_names }` — complete export
|
||||
name plus the statically verified artifact digest and manifest argument
|
||||
order;
|
||||
* `DynamicValue` — a language value (for example a `FunctionRef`); this is
|
||||
the **only** non-static path and cannot reach an ABI export by name.
|
||||
4. **Runtime dispatches by identity.** `eval_call` looks up the site's binding
|
||||
and calls the recorded target. It never calls `builtins::find(qualified)`,
|
||||
never inspects `external_callables.is_empty()` and never guesses a plugin.
|
||||
A missing binding is an internal error (`internal.error`), not a reason to
|
||||
re-resolve.
|
||||
5. **Prepare finalises once.** `marqdo-cli` has one composition step
|
||||
(`project_prepare::prepare`): load sources → read extension descriptors
|
||||
(no `dlopen`/spawn) → build the registry → bind calls once. `check`,
|
||||
`run`/`call`, `inspect` and Analysis consume that one prepared program.
|
||||
Static plugin descriptors are inserted before binding, not appended after a
|
||||
first validation.
|
||||
6. **Exact run-time reconciliation.** `run` verifies each selected plugin
|
||||
artifact, loads it, then compares the Host's actual exports (name, raw
|
||||
signature, artifact digest, owner package) with the static descriptors
|
||||
one-to-one. Any extra, missing or altered export fails with
|
||||
`ext.plugin_binding_mismatch` before the entry function runs. No descriptor
|
||||
is synthesised at run time.
|
||||
7. **Print is not special.** `Program.print_override` and the runtime
|
||||
`打印`/`print` branch are removed. The builtin placeholder remains only for
|
||||
embedders without the official bundle and fails with
|
||||
`kernel.unavailable`; the official bundle declares aliases in verified
|
||||
metadata (ADR-0058).
|
||||
|
||||
## Priority matrix (normative)
|
||||
|
||||
See `spec/callable-resolution.md` for the complete matrix and diagnostics. In
|
||||
short:
|
||||
|
||||
* `f(...)`: local variable → official alias/reserved builtin → current
|
||||
namespace → canonical name → unique local name → otherwise
|
||||
`symbol.unknown` (ambiguity is an error, never a first-match);
|
||||
* `alias.f(...)`: explicit import alias → builtin dotted namespace → exact
|
||||
plugin export → otherwise `symbol.unknown`;
|
||||
* `some_value.f(...)`: dynamic language dispatch only.
|
||||
|
||||
Import aliases that collide with a builtin or plugin dotted namespace are
|
||||
rejected at prepare with `ext.import_namespace_conflict`; duplicate plugin
|
||||
exports are rejected with `ext.duplicate_callable`.
|
||||
|
||||
## Consequences
|
||||
|
||||
* `check` and `run` now share binding identity; CALL-01…CALL-16 in
|
||||
`crates/cli/tests/callable_resolution.rs` pin the matrix.
|
||||
* 0.x breaking change: a project importing a module under an alias that equals
|
||||
a builtin namespace (for example `math`) must rename the alias. There is no
|
||||
`--legacy` switch and no dual semantics.
|
||||
* Analysis v2's `calls[].state/target` are now projected from the same binding
|
||||
(official aliases appear as `function` targets). Analysis v2 schema and
|
||||
fields are otherwise unchanged; private `CallBindingTable` is not serialized.
|
||||
* Runtime no longer performs per-call name resolution, so the dynamic path is
|
||||
limited to language values. A text or map value called as a function is
|
||||
`call.not_callable` and never becomes a Host plugin request.
|
||||
* Plugin manifests must be complete before binding: a manifest with a missing
|
||||
or malformed signature is a prepare error; ABI v1 default values are
|
||||
rejected until the wire semantics are versioned.
|
||||
|
||||
## Rejected alternatives
|
||||
|
||||
* **Pick a fixed precedence and keep two implementations.** Rejected: the RFC
|
||||
requires one static answer, and duplicated precedence is exactly the defect.
|
||||
* **Build the registry lazily in the runtime.** Rejected: `check` would still
|
||||
not prove the binding, and runtime loading would change static resolution.
|
||||
* **Keep the empty-`external_callables` fallback for "developer convenience".**
|
||||
Rejected: it turns a compile error into a Host call attempt and breaks
|
||||
`check`'s no-execution guarantee.
|
||||
* **Expose `CallableId`/`CallBindingTable` in Analysis v2.** Rejected:
|
||||
private IR must not become a public wire contract without a version bump.
|
||||
EOF
|
||||
@@ -0,0 +1,196 @@
|
||||
# ADR-0055: Resource Provider v2 through the normal CLI
|
||||
|
||||
Status: **Accepted**
|
||||
Date: 2026-11-21
|
||||
Relates to: RFC-EXT-0001 §5/§16/§18, ADR-0033, ADR-0034, ADR-0035, ADR-0036,
|
||||
ADR-0037, ADR-0038, ADR-0021 (strict L1), ADR-0052 (single Markdown semantics)
|
||||
Specs: `spec/resource-provider-v2.md`
|
||||
Implementation: `crates/cli/src/provider_manifest.rs`,
|
||||
`crates/cli/src/commands/sandbox.rs`, `crates/cli/src/commands/run.rs`,
|
||||
`crates/cli/src/main.rs`, `crates/cli/tests/provider_cli.rs`
|
||||
|
||||
## Context
|
||||
|
||||
The host already implements versioned resource-provider registration
|
||||
(`register_resource_provider`, `register_worker_resource_provider`,
|
||||
`register_c_resource_provider`, `register_provider_package`) and
|
||||
`resource.open` dispatches unknown kinds through that registry with a provider
|
||||
name grant (ADR-0033/0035/0036/0037/0038). What was missing was a **public
|
||||
composition-root entry point**: `main.rs`/`SandboxSettings`/`run.rs` had no
|
||||
`--provider`/`--allow-provider`, so an external repository could not use a new
|
||||
resource kind on a frozen `marqdo` binary without patching and rebuilding the
|
||||
CLI (RFC-EXT-0001 EXT-07).
|
||||
|
||||
The existing `marqdo.provider` manifest (`schema_version: 1`, ADR-0037) is a
|
||||
host-embedding installation format: `name/kinds/abi/library`, no `version`, no
|
||||
targeted artifact digest and no transport. It cannot support portable,
|
||||
integrity-checked CLI loading. RFC-EXT-0001 §5.3 asks for a v2 document rather
|
||||
than silently overloading v1. It also requires that selecting an extension is
|
||||
not authorizing it, that `pure`/`strict` keep failing closed, and that no new
|
||||
`HostOp`/builtin/business branch is introduced.
|
||||
|
||||
This ADR records the PR-03 decision on the current branch.
|
||||
|
||||
## Decision
|
||||
|
||||
### 1. CLI surface and ordering
|
||||
|
||||
`--provider PATH` (repeatable, a `provider.json` file) and
|
||||
`--allow-provider NAME` (repeatable, exact name) are added to `SandboxArgs`, so
|
||||
they are shared by `run` and `call` only. `check`/`inspect` do not declare them
|
||||
and never read a provider manifest. `SandboxSettings` carries
|
||||
`providers: Vec<PathBuf>` and `allow_provider: Vec<String>`; the `project`
|
||||
capability set calls the existing `Capabilities::allow_resource_provider(name)`
|
||||
for each grant.
|
||||
|
||||
Run ordering follows RFC-EXT-0001 §18.2: `prepare` (no provider work) →
|
||||
diagnostics → mode/strict preflight → capabilities → host assembly and budgets
|
||||
→ kernels → **all provider manifests/targets/artifacts/grants/duplicate kinds
|
||||
verified and plugin artifacts verified** → plugin workers loaded and exports
|
||||
reconciled → provider helpers spawned → entry-function check → execute. No
|
||||
worker (plugin or provider) starts before every T6/T6b verification passes, and
|
||||
the main function never runs after a provider failure.
|
||||
|
||||
`pure` and `strict` reject both flags in preflight (`cli.invalid_grants` /
|
||||
`strict.unsupported_grant`, exit 2) without silently switching to `project`.
|
||||
`--allow-provider` rejects wildcards (`*`, `?`, `[`, `]`) and empty names; a
|
||||
grant that matches no selected manifest is `ext.provider_grant_unmatched`
|
||||
(exit 2). A `--provider` selected without its exact grant is
|
||||
`permission.denied` (exit 1) before the helper is spawned.
|
||||
|
||||
### 2. Strict v2 manifest parser
|
||||
|
||||
New `crates/cli/src/provider_manifest.rs` owns the document, separate from the
|
||||
plugin `plugin.yaml` parser:
|
||||
|
||||
* accepts exactly `schema = "marqdo.provider"`, `schema_version = 2`,
|
||||
`abi = "c-abi-1"`, `transport = "worker"`; other versions/ABIs/transports are
|
||||
`ext.unsupported_provider_schema` (no silent migration, no v1 fallback from
|
||||
the CLI);
|
||||
* strict dotted lowercase name/kind grammar, strict SemVer, non-empty unique
|
||||
non-reserved kinds, bounded counts, known/vendor `permissions_requested`
|
||||
declarations only, optional non-executable `metadata`;
|
||||
* unknown top-level/artifact fields are rejected (`ext.manifest_invalid`);
|
||||
* artifacts need unique parseable targets and 64-lowercase-hex sha256;
|
||||
the current `HostTarget` artifact is selected (`ext.no_matching_artifact`
|
||||
when absent), resolved inside the manifest bundle (absolute/`..`/symlink
|
||||
escape/non-regular/size limit/sha mismatch → `ext.artifact_integrity`);
|
||||
* duplicate names with different manifest digests (`ext.duplicate_provider`)
|
||||
and duplicate kinds across providers (`ext.duplicate_provider_kind`) are
|
||||
deterministic because paths are canonicalised, sorted and de-duplicated
|
||||
before conflict detection.
|
||||
|
||||
`VerifiedProvider` is the static `{name, kinds, manifest_path, base_dir,
|
||||
manifest_digest, transport, selected_artifact_path/relative/sha256/target,
|
||||
version}` record. It is still declaration/verification only: no `dlopen`, no
|
||||
spawn, no grant.
|
||||
|
||||
### 3. Activation reuses the existing host API
|
||||
|
||||
`load_resource_provider_into_host(host, verified, allow_provider)` repeats the
|
||||
exact grant check, re-verifies the manifest digest and the artifact
|
||||
(regular file, containment, size, sha256) immediately before use, resolves the
|
||||
helper, and calls **the existing**
|
||||
`StdHost::register_worker_resource_provider(name, kinds, helper, [artifact])`.
|
||||
It never falls back to `register_c_resource_provider`,
|
||||
`register_provider_package`, in-process native loading or another provider.
|
||||
`resource.open` still re-checks the provider name grant in the Host. Provider
|
||||
registration keeps using `register_provider_checked` for name/kind/duplicate
|
||||
validation, so no second provider registry is introduced.
|
||||
|
||||
### 4. Helper resolution and platform claim
|
||||
|
||||
The helper is resolved only as a sibling of the running `marqdo` executable:
|
||||
`<exe dir>/marqdo-provider-worker[.exe]`. `PATH`, the current directory,
|
||||
environment overrides and downloads are not consulted. Missing/non-regular
|
||||
helper, spawn failure or failed `ping` → `ext.worker_unavailable` (exit 1).
|
||||
|
||||
The `worker` transport is claimed only on **linux/x86_64**; every other target
|
||||
returns `ext.platform_unsupported` (exit 1) instead of pretending success.
|
||||
Release artifacts must ship the helper next to the CLI for the same target
|
||||
triple. macOS/Windows stay buildable and explicitly unsupported until they have
|
||||
a native fixture and release evidence (RFC-EXT-0001 §5.6).
|
||||
|
||||
### 5. No new host op or language surface
|
||||
|
||||
There is no new `HostOp`, builtin, `resource_request` string branch, `Value`
|
||||
variant or Markdown syntax. A provider kind is still an argument to
|
||||
`resource.open("<kind>", descriptor, rights)`; the only change is the CLI
|
||||
composition root that selects, verifies and authorizes the existing host
|
||||
transport. Provider tokens stay inside the helper; the language sees only the
|
||||
opaque Host `Resource` handle. Worker errors are structured `RuntimeError`s
|
||||
surfaced as CLI errors — the CLI never panics on a helper crash/timeout.
|
||||
|
||||
### 6. Tests
|
||||
|
||||
`crates/cli/tests/provider_cli.rs` drives the real CLI binary with a real C
|
||||
`c-abi-1` sensor library and the real `marqdo-provider-worker` helper built by
|
||||
cargo and installed next to the CLI (the same layout a release tarball uses;
|
||||
production resolution is not weakened for tests). Coverage: PROV-01/02/03/04/
|
||||
05/06/07/08/09/10/13, plus `check` refusing the flag. Marker files written by
|
||||
the C library's ABI-version hook prove whether a worker actually started, so
|
||||
"no worker on unauthorized/invalid input" is evidence, not an assertion about
|
||||
code paths.
|
||||
|
||||
## Consequences
|
||||
|
||||
* A third party can add a new resource kind to a frozen `marqdo` binary through
|
||||
`provider.json` v2 + `--provider` + `--allow-provider`, without a core
|
||||
rebuild, new builtin or new CLI command.
|
||||
* v1 `marqdo.provider` remains a host-embedding format; CLI users get a clear
|
||||
`ext.unsupported_provider_schema` instead of a silently unverified load.
|
||||
* Integrity hashing raises the cost of accidental corruption/tampering but is
|
||||
not a trust root; a compromised or malicious helper still runs with the
|
||||
user's privileges. Documentation states this explicitly.
|
||||
* `pure`/`strict` semantics and the existing resource/provider host contracts
|
||||
are unchanged (strict still L1-only and fail-closed).
|
||||
* The provider helper becomes a release artifact that must be packaged next to
|
||||
the CLI; a missing helper is a first-class, deterministic error.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
1. **Reuse `plugin.yaml`/plugin ABI directly for providers.** Rejected: a
|
||||
resource provider's contract is open/read/write/close with provider-private
|
||||
tokens and stream kinds, not callable exports; sharing the manifest/ABI
|
||||
parser would conflate two independent protocols (RFC-EXT-0001 §1.3).
|
||||
2. **Extend v1 in place with optional `version`/`artifacts`.** Rejected:
|
||||
v1 is host-embedding installation metadata and is already accepted by
|
||||
`register_provider_package`; silently changing its meaning or accepting a
|
||||
half-populated v1 would break the frozen ADR-0037 contract. v2 is explicit.
|
||||
3. **Allow in-process C ABI loading when the worker helper is missing.**
|
||||
Rejected: it would silently lower the process boundary and RFC-EXT-0001
|
||||
§5.2/§5.4 forbids falling back to Native. `ext.worker_unavailable` is the
|
||||
correct fail-closed result.
|
||||
4. **PATH lookup for `marqdo-provider-worker`.** Rejected: `PATH` is
|
||||
attacker-controlled state and would make the executed artifact
|
||||
non-deterministic; the sibling rule binds the helper to the release.
|
||||
5. **Register providers lazily at the first `resource.open`.** Rejected for
|
||||
this slice: authorization and integrity must be decided before the main
|
||||
function executes, and the existing host API is synchronous spawn-on-register.
|
||||
6. **Accept a `*` provider grant for developer convenience.** Rejected: grants
|
||||
are exact names (RFC-EXT-0001 §5.2); wildcards would let a typo authorize an
|
||||
arbitrary selected provider.
|
||||
|
||||
## Deviations recorded
|
||||
|
||||
* `ext.manifest_invalid`, `ext.duplicate_provider` and
|
||||
`ext.provider_grant_unmatched` are **additive** `ext.*` codes beyond the list
|
||||
frozen in RFC-EXT-0001 §18.1. The frozen list has no generic malformed-v2
|
||||
code, no duplicate-provider-name code and no unmatched-grant code; reusing
|
||||
`ext.unsupported_provider_schema`/`ext.duplicate_provider_kind` for these
|
||||
would report the wrong reason. They follow the same `ext.` naming and exit
|
||||
code contract and are frozen by this ADR.
|
||||
* `ext.artifact_integrity` failures exit 1 (load/verify), while static
|
||||
manifest-selection failures exit 2, matching RFC-EXT-0001's exit-code
|
||||
guidance; plugin artifact checking already uses the same split.
|
||||
* Only linux/x86_64 is claimed for the provider `worker` transport in this
|
||||
release (RFC-EXT-0001 §5.6 permits this explicit platform limit; Windows and
|
||||
macOS return `ext.platform_unsupported`).
|
||||
|
||||
## Verification
|
||||
|
||||
`crates/cli/tests/provider_cli.rs` (12 real tests, linux/x86_64) plus
|
||||
`crates/cli/src/provider_manifest.rs` unit tests pass; `spec/security.md`,
|
||||
`spec/resource-provider-v2.md` and the README provider section document the
|
||||
same contract. Evidence is recorded in the PR-03 task report (commands, exit
|
||||
codes, per-PROV matrix).
|
||||
@@ -0,0 +1,229 @@
|
||||
# ADR-0057: Trusted capability-handler registration
|
||||
|
||||
Status: **Accepted**
|
||||
Date: 2026-11-21
|
||||
Implements: RFC-EXT-0001 §7 (PR-05)
|
||||
Extends: ADR-0011 (capability broker)
|
||||
Scope: `crates/marqdo-host/src/capability.rs` (host-internal registry)
|
||||
|
||||
## Context
|
||||
|
||||
ADR-0011 introduced `CapabilityBroker` with two separate ideas but only one
|
||||
implementation path:
|
||||
|
||||
* `decide()` answered "is this capability granted?" from `Capabilities` and a
|
||||
trusted vendor-policy allow-list; and
|
||||
* `execute()` special-cased the single real core implementation (`fs.read`)
|
||||
inline, returning `capability.unavailable` for everything else.
|
||||
|
||||
That shape is why adding a capability looked like a one-line allow-list edit,
|
||||
and it made "declared in policy" and "can actually execute" the same object.
|
||||
RFC-EXT-0001 §7.1/§7.2 requires the chain:
|
||||
|
||||
```text
|
||||
manifest requests capability
|
||||
-> operator/CLI grants it
|
||||
-> broker asks: is a trusted handler installed?
|
||||
-> handler re-checks owner/grant/scope/budget
|
||||
-> handler executes
|
||||
-> audit { identity, effect, decision, duration, trace_id }
|
||||
```
|
||||
|
||||
A name in an allow-list must never be enough to execute, and a capability with
|
||||
no executor must never look like an empty success.
|
||||
|
||||
## Decision
|
||||
|
||||
### 1. Two independent registries
|
||||
|
||||
`CapabilityBroker` keeps:
|
||||
|
||||
* `vendor_policy: BTreeSet<String>` — names the trusted host *policy* accepts
|
||||
(from `allow_vendor`); and
|
||||
* `handlers: BTreeMap<String, HandlerEntry>` — names that have an explicitly
|
||||
registered trusted executor.
|
||||
|
||||
`HandlerEntry` additionally carries an optional exact trusted package binding
|
||||
(`None` = authorized by the capability grant alone).
|
||||
|
||||
The two sets cannot substitute for each other:
|
||||
|
||||
* vendor capability without a policy entry -> `permission.denied`
|
||||
(declaration is not a grant; CAP-01);
|
||||
* vendor policy entry without a handler -> `capability.unavailable` (CAP-02);
|
||||
* core capability granted by `Capabilities` but without a handler ->
|
||||
`capability.unavailable` (CAP-12).
|
||||
|
||||
### 2. Handler interface
|
||||
|
||||
```rust
|
||||
pub struct CapabilityRequest<'a> {
|
||||
pub package_instance: &'a str, // trusted identity from the host, not wire data
|
||||
pub capability: &'a str,
|
||||
pub payload: &'a [u8],
|
||||
pub trace_id: &'a str,
|
||||
}
|
||||
|
||||
pub trait CapabilityHandler: Send {
|
||||
fn name(&self) -> &str;
|
||||
fn execute(
|
||||
&mut self,
|
||||
request: &CapabilityRequest<'_>,
|
||||
capabilities: &Capabilities,
|
||||
budget: &mut Budget,
|
||||
) -> Result<Vec<u8>, PluginError>;
|
||||
}
|
||||
```
|
||||
|
||||
The registry key is `handler.name()`, so the handler's declared capability can
|
||||
never disagree with the name it is registered under (the RFC's "declared
|
||||
protocol mismatch" rejection cannot occur by construction).
|
||||
|
||||
Registration is host-only; there is no wire path from a plugin manifest to this
|
||||
API. `register_handler` installs a handler usable by any package holding a
|
||||
grant; `register_package_handler(package, handler)` binds it to one exact
|
||||
trusted package identity and denies every other claimed package (CAP-03, the
|
||||
"trust the package the host loaded, not a self-reported name" rule of §7.4).
|
||||
|
||||
### 3. Registration validation
|
||||
|
||||
`register_handler` / `register_package_handler` reject:
|
||||
|
||||
| condition | stable code |
|
||||
|---|---|
|
||||
| empty name, surrounding whitespace, or not a core/vendor name | `capability.handler_invalid` |
|
||||
| name under a reserved host prefix (`marqdo.`, `host.`) | `capability.handler_reserved` |
|
||||
| name already registered (including the built-in `fs.read`) | `capability.handler_conflict` |
|
||||
|
||||
A rejected handler is never installed. The component that constructs the
|
||||
broker is the trust boundary: only trusted host/embedder code can register, so
|
||||
"untrusted source" is rejected by the absence of an API rather than a flag.
|
||||
|
||||
### 4. Fixed execution chain and audit
|
||||
|
||||
`execute()` is one function with one order:
|
||||
|
||||
1. `decide()` — `Capabilities`, vendor policy, request payload shape;
|
||||
2. handler installed? — otherwise audit `unavailable`, return
|
||||
`capability.unavailable`;
|
||||
3. package-bound handler owns the claimed package? — otherwise audit `denied`,
|
||||
return `permission.denied`;
|
||||
4. handler executes under the broker `Budget` and the broker reply limit;
|
||||
5. audit one entry with `package`, `capability`, `decision`
|
||||
(`granted`/`denied`/`unavailable`), reason and `duration_micros`.
|
||||
|
||||
`authorize()` remains the grant decision only (`granted`/`denied`); it never
|
||||
executes and therefore cannot demonstrate an executor. This keeps the
|
||||
authorization and execution questions separate and auditable.
|
||||
|
||||
The reply is bounded by `reply_limit` (default
|
||||
`MAX_CAPABILITY_REPLY_BYTES`) and oversize replies are `resource.exhausted`
|
||||
(CAP-06). Handlers also receive `&mut Budget`, so an embedder can wire the
|
||||
per-run budget and handlers can charge fuel/output (tested). Response payloads
|
||||
are never written to the audit log, so file contents and request secrets stay
|
||||
out of it (CAP-09).
|
||||
|
||||
### 5. `fs.read` becomes the first standard handler
|
||||
|
||||
The former inline `fs.read` match arm moved into `FsReadHandler`, installed by
|
||||
`CapabilityBroker::with_fs(fs)`. It:
|
||||
|
||||
* resolves the path with `ProjectFs::resolve` (absolute paths, `..`, empty
|
||||
paths rejected) **before** I/O;
|
||||
* re-checks `Capabilities::check_read` against the normalized
|
||||
project-relative path at the execution point, so the grant is enforced on the
|
||||
same path the filesystem uses;
|
||||
* reads through `ProjectFs` (regular file, UTF-8, project root, 8 MiB limit).
|
||||
|
||||
`with_fs` still installs exactly one handler; `capability_broker.rs` and
|
||||
`host.rs` call sites are unchanged. Every other core capability and every
|
||||
vendor capability without a registered handler keeps returning
|
||||
`capability.unavailable`; nothing returns an empty `Ok` as a stand-in for
|
||||
"implemented".
|
||||
|
||||
## RFC deviations (explicit)
|
||||
|
||||
1. **`EffectiveGrant` -> `Capabilities`; `ResourceBudget` -> `Budget`.** The
|
||||
RFC (§7.2) says these are design-interface names and the implementation must
|
||||
reuse the existing grant and limit structures instead of building a second
|
||||
permission system; that is exactly what happened.
|
||||
2. **`CapabilityError` -> `PluginError`.** The capability bridge across the
|
||||
plugin/worker ABI already uses `marqdo_plugin_abi::PluginError`; reusing it
|
||||
avoids a second error taxonomy. Codes remain the stable contract.
|
||||
3. **`trace_id` is plumbed through `CapabilityRequest` and settable with
|
||||
`with_trace_id`, but the host wiring is a follow-up.** `host.rs` does not set
|
||||
it yet, so audit entries from the current CLI plugin path have an empty
|
||||
trace id. Wiring it requires the run/session id from `ExecutionContext`,
|
||||
which is outside this PR's write scope.
|
||||
4. **`resource.exhausted` preserves the broker code but not the runtime
|
||||
category.** `PluginError` kind `Capability` maps to
|
||||
`RuntimeError` category `PermissionDenied` in `host.rs::map_plugin_error`.
|
||||
The stable code is `resource.exhausted` (what CAP-06 asserts at the broker
|
||||
boundary); teaching the host mapping about a resource-limit plugin code is a
|
||||
follow-up because `host.rs` is outside this PR's scope.
|
||||
5. **`CapabilityBroker` is no longer `Clone`** because it owns `Box<dyn
|
||||
CapabilityHandler>`. No in-tree caller cloned it; a future embedder that
|
||||
needs a clone should share the broker behind the same lock instead, which is
|
||||
also what the one-call-at-a-time ABI requires.
|
||||
|
||||
## Alternatives
|
||||
|
||||
1. Keep the closed match arm and add capabilities to it. Rejected: every
|
||||
vendor operation would need a core release and the broker would still have
|
||||
no separation between "granted" and "executable".
|
||||
2. Treat a vendor policy entry as proof of an executor. Rejected: that is the
|
||||
exact "declaration becomes privilege" failure the RFC forbids; CAP-02 locks
|
||||
it out.
|
||||
3. Register handlers by `(name, package)` strings only and trust the caller's
|
||||
package argument. Rejected: a wire-supplied package name must not authorize
|
||||
anything; package-bound registration pins the identity the host selected at
|
||||
load time.
|
||||
4. Give every core capability an empty handler so `execute()` always returns
|
||||
`Ok`. Rejected: it converts "not implemented" into a silent success, the
|
||||
failure mode RFC §7.1 calls out.
|
||||
|
||||
## Compatibility
|
||||
|
||||
* Existing `Capabilities`, `with_fs`, `with_audit`, `allow_vendor`,
|
||||
`authorize`, `execute` and `capability_audit()` call sites are unchanged;
|
||||
`host.rs` needed no edit.
|
||||
* One observable change: a vendor capability without a trusted policy entry is
|
||||
now `permission.denied` instead of `capability.unavailable`. This matches
|
||||
ADR-0011 ("a missing grant is `permission.denied`") and RFC CAP-01.
|
||||
* `CapabilityAudit` gained `duration_micros`; all fields remain public and the
|
||||
existing tests that read `package`/`capability`/`decision` compile unchanged.
|
||||
* `CapabilityBroker` lost `Clone` (see deviation 5).
|
||||
* No ABI, wire, manifest or CLI change.
|
||||
|
||||
## Security
|
||||
|
||||
* Registration is a trusted-host operation with no manifest/wire entry point;
|
||||
a plugin cannot install, replace or enumerate handlers.
|
||||
* Package-bound handlers reject cross-package impersonation even when policy
|
||||
and grant match.
|
||||
* `fs.read` keeps `ProjectFs` root confinement, glob scope and size limits; the
|
||||
grant is re-checked on the normalized path at the execution point.
|
||||
* Audit records decisions and durations but never payload contents.
|
||||
* This remains a cooperative in-process API contract, not an OS sandbox: a
|
||||
native plugin can still issue direct syscalls. The registry narrows what the
|
||||
host will *do on request*; it does not confine plugin memory or syscalls.
|
||||
|
||||
## Testing
|
||||
|
||||
`crates/marqdo-host/tests/capability_handlers.rs` covers CAP-01..CAP-12:
|
||||
policy-vs-handler separation, package binding, registration rejection, real
|
||||
`fs.read` scope enforcement, reply budget and handler budget charging, forged
|
||||
and replayed handles, audit hygiene, resource-stream regression smoke, project
|
||||
mode not being OS-strict, and "no handler is never a silent success".
|
||||
Unit tests in `capability.rs` keep the `CORE_CAPABILITIES` list in sync with
|
||||
`decide()` and assert that the built-in `fs.read` handler is installed by
|
||||
`with_fs`.
|
||||
|
||||
## Migration & rollout
|
||||
|
||||
`with_fs` installs the migrated `fs.read` handler automatically, so existing
|
||||
plugin loads keep working. Future core capabilities migrate by adding a handler
|
||||
and registering it in the trusted composition root; until then they remain
|
||||
`capability.unavailable`. Vendor operations that need a non-streaming API
|
||||
should first use the existing `resource.open/read/write/close` stream path
|
||||
(RFC-EXT-0001 §7.3) instead of registering a new host handler.
|
||||
@@ -0,0 +1,105 @@
|
||||
# ADR-0058: Official stdlib public aliases replace print magic
|
||||
|
||||
- Status: Accepted (2026-11-21)
|
||||
- Implements: RFC-EXT-0001 §8 (PR-06)
|
||||
- Related: ADR-0028/0030/0031/0039, ADR-0054
|
||||
|
||||
## Context
|
||||
|
||||
`打印`/`print` were implemented twice:
|
||||
|
||||
1. `crates/cli/src/loader.rs::program_uses_print` walked the entire AST, and if
|
||||
any function called `打印`/`print` it injected the bundled
|
||||
`stdlib/io.mq.md` module and set `Program.print_override` to its `写值`
|
||||
function;
|
||||
2. `crates/marqdo-runtime/src/interpreter.rs` contained a `打印`/`print`
|
||||
special case that redirected to the override, while the builtin table also
|
||||
contained a placeholder `打印` entry.
|
||||
|
||||
Copying this pattern to the next official high-level function (formatting,
|
||||
console input, …) would add one AST scanner and one runtime branch per name.
|
||||
The RFC forbids that ("为标准库每个高级函数复制 print_override 模式"), while
|
||||
also requiring byte-identical output and no new Host op.
|
||||
|
||||
## Decision
|
||||
|
||||
1. **Verified metadata.** The bundled `stdlib/stdlib.json` declares
|
||||
|
||||
```json
|
||||
"public_aliases": [
|
||||
{
|
||||
"public_names": ["print", "打印"],
|
||||
"target_module": "io.mq.md",
|
||||
"target_function": "写值",
|
||||
"expected_signature": "params(值)",
|
||||
"effects": ["host"]
|
||||
}
|
||||
],
|
||||
"aliases_digest": "sha256:<64 lowercase hex>"
|
||||
```
|
||||
|
||||
`aliases_digest` is the SHA-256 of the canonical binary encoding: for each
|
||||
alias sorted by `(target_module, target_function)`, the module bytes, NUL,
|
||||
the function bytes, NUL, then every public name in sorted order followed by
|
||||
NUL. The same encoding is implemented by `tools/pack-stdlib.py` and
|
||||
`crates/cli/src/stdlib.rs::aliases_digest`; `stdlib.json` cannot be edited
|
||||
without updating the digest, and the loader verifies both digests before any
|
||||
module loads. Metadata is integrity-checked, not signed: a SHA-256 proves
|
||||
content equality, not publisher identity.
|
||||
2. **Lazy, generic loading.** The loader reads the metadata, decides whether the
|
||||
program references any public alias name (a generic identifier scan, not a
|
||||
per-function hard code), and only then loads the declared target module.
|
||||
The target signature is checked against `expected_signature`; a mismatch is
|
||||
a load error. A program without `打印`/`print` keeps its previous module
|
||||
graph and startup cost.
|
||||
3. **Ordinary Marqdo binding.** For each used alias the loader produces an
|
||||
`OfficialAlias { public_names, function, signature, owner_package,
|
||||
effects_requested }`; `project_prepare` registers it in the
|
||||
`CallableRegistry`. The binding pass targets
|
||||
`Marqdo { function: <stdlib instance>::io.mq.md::写值 }`. The runtime calls
|
||||
an ordinary Markdown function; it has no print branch.
|
||||
4. **Reserved names stay reserved.** Official aliases may replace the builtin
|
||||
placeholder for the same public name. Third-party registry insertion rejects
|
||||
builtin *and* official-alias names (`ext.duplicate_callable`), so no plugin
|
||||
or imported module can claim `打印`/`print`, `std.*` or `marqdo.*`.
|
||||
`plugin.yaml` still rejects reserved export prefixes at manifest validation.
|
||||
5. **No Host print operation.** Output continues to flow through
|
||||
`io.写值` → `format.显示` → UTF-8 bytes → `Memory` →
|
||||
`resource.write(stdout)`. There is no `HostOp::Print` and no second
|
||||
formatter. Unbundled embedders that call the placeholder builtin receive
|
||||
`kernel.unavailable`.
|
||||
6. **Removed code.** `program_uses_print`, `stmts_use_print`,
|
||||
`expr_uses_print`, `Program.print_override`, the runtime redirect branch and
|
||||
the whole-AST print scanner are deleted. A structural test
|
||||
(`architecture_boundaries.rs::callable_binding_is_the_only_static_resolution_path`)
|
||||
fails if they reappear.
|
||||
|
||||
## Consequences
|
||||
|
||||
* `打印` and `print` are now ordinary calls in Analysis/Trace: the call target
|
||||
is the stdlib function, `state` is `function`, and no synthetic `builtin`
|
||||
target is reported for the alias.
|
||||
* Output must stay byte-identical. `crates/cli/tests/stdlib_alias_routing.rs`
|
||||
plus the existing print/format/Trace goldens pin this; a diff is a blocking
|
||||
regression, not an acceptable "new design".
|
||||
* A tampered alias table (metadata digest or expected signature) is rejected
|
||||
before module loading; `stdlib.json` and the `.mq.md` tree remain separately
|
||||
digest-pinned, and `tools/pack-stdlib.py` refuses to build an inconsistent
|
||||
bundle.
|
||||
* The generic metadata path is the only place a future official high-level name
|
||||
needs to be declared locally. Any *new language syntax* still requires a
|
||||
language RFC; aliases cannot change `@exec`/`@knowledge` semantics.
|
||||
|
||||
## Rejected alternatives
|
||||
|
||||
* **Keep `print_override` and add a second alias for another function.**
|
||||
Rejected: it multiplies hard-coded scans/branches and violates RFC-EXT-0001
|
||||
§8 and §14.10.
|
||||
* **Move the print formatter into the Host as a `Print` op.** Rejected: it
|
||||
would reintroduce an un-audited output path and duplicate the stdlib
|
||||
formatter; output is a resource write.
|
||||
* **Let third-party packages register `print`/`打印` aliases.** Rejected:
|
||||
official public names are a language surface, not an extension registry.
|
||||
* **Put the alias table in Rust `match` arms instead of metadata.** Rejected:
|
||||
the table must be versioned with the verified bundle so a stale/mixed bundle
|
||||
cannot run a different function.
|
||||
@@ -15,6 +15,15 @@ replace `spec/` or a recorded test log.
|
||||
> bundled `stdlib/` implement it. The workspace gate is green at `9c1723d`;
|
||||
> rollout evidence and historical banners are indexed in
|
||||
> [`../migration/README.md`](../migration/README.md).
|
||||
>
|
||||
> **Extensibility closure (RFC-EXT-0001).** The current tree implements the
|
||||
> single static callable binding (ADR-0054), official stdlib public aliases
|
||||
> replacing print magic (ADR-0058), third-party resource providers through the
|
||||
> normal CLI (ADR-0055), and the capability-handler registry (ADR-0057). The
|
||||
> extension selection/lock v4 composition and the frozen external-binary
|
||||
> evidence are tracked as remaining PR-04/PR-08 work, not claimed here. The
|
||||
> normative resolution contract is
|
||||
> [`spec/callable-resolution.md`](../../spec/callable-resolution.md).
|
||||
|
||||
## 1. Four state dimensions
|
||||
|
||||
@@ -25,7 +34,7 @@ platform".
|
||||
| Dimension | Current state | Source |
|
||||
|---|---|---|
|
||||
| Implemented | Rust workspace `0.1.0`: RFC-LANG-0002 Markdown/frontend/IR, v2 statement parser, tree-walk runtime, `Memory`, capability host, Tool/Analysis/Trace, Plugin ABI, Foreign kernels, migrated bundled stdlib, CLI composition root | `Cargo.toml`, `crates/`, `stdlib/` |
|
||||
| Tested locally | `cargo test --workspace --locked`: **507 passed, 0 failed, 2 ignored** on Linux x86_64 at the baseline; fmt and clippy clean | `docs/STATUS.md` §0, `docs/evidence/2026-11-21-semantics-v2-green.md` |
|
||||
| Tested locally | `cargo test --workspace --locked`: **584 passed, 0 failed** across 66 targets on Linux x86_64 in the RFC-EXT-0001 tree; fmt and clippy clean. Historical baseline: 507 passed at `9c1723d`. | `docs/STATUS.md`, `docs/evidence/2026-11-22-ext-implementation.md` |
|
||||
| Bundled stdlib released | In-repo bundle `marqdo-stdlib@0.1.0`, SHA-256 digest verified before loading; it is **not** an external registry package | `stdlib/stdlib.json`, `stdlib/README.md` |
|
||||
| Multi-platform verified | Linux local gate is the only executed lane here; Windows/macOS native lanes are **UNVERIFIED**, and the GitHub security lane remains a **VM-only** gate | `docs/STATUS.md` §1, §4 |
|
||||
|
||||
@@ -53,6 +62,12 @@ OS / external services / devices
|
||||
|
||||
CLI is only the composition root: parse arguments, load the project,
|
||||
assemble Host + Runtime, route output, exit with a status.
|
||||
`project_prepare::prepare` is the single finalisation step: it loads sources,
|
||||
reads static extension descriptors (never `dlopen`/spawn), builds the unique
|
||||
`CallableRegistry`, binds every call site once and hands the same
|
||||
`PreparedProgram` to `check`/`run`/`call`/`inspect`/Analysis. The runtime
|
||||
dispatches only by the resulting `CallBindingTable`; it never re-resolves a
|
||||
name or guesses a plugin.
|
||||
Callable Plugin / Foreign kernel / Tool Protocol are separate extension
|
||||
categories; they do not enter the standard library or the language IR.
|
||||
```
|
||||
@@ -112,7 +127,10 @@ review RFC, not a new crate per provider.
|
||||
| network endpoints | `tcp`/`udp`/`tcp-listener`/`tls` open + `resource.accept`; exact host grant, DNS after grant, TLS certificate validation | implemented (project mode) | `resource_streams` |
|
||||
| `std:net/http` | byte-exact HTTP/1.1 parse/build; chunk sizes are byte counts; text wrapper compatible | implemented (pure `.mq.md`) | `stdlib_http` |
|
||||
| HTTP/1.1 | `stdlib/net/http.mq.md`: status/header/chunked-byte parse, request build | implemented over an already-authorized TCP stream; not a DNS/TLS client | `stdlib_http`, `http_over_tcp`, `stdlib_product` |
|
||||
| print | bundled `io.mq.md`/`console.mq.md` through `resource.write`; legacy `HostOp::Print` removed | implemented (Compat-C) | `print_routing`, `stdlib_product` |
|
||||
| print / official stdlib aliases | `打印`/`print` are verified `stdlib.json` public aliases bound to `io.mq.md::写值`; ordinary Marqdo calls, no `print_override`, no runtime branch, no `HostOp::Print` | implemented (ADR-0058) | `stdlib_alias_routing`, `print_routing`, `stdlib_product` |
|
||||
| callable resolution | one registry + one `bind_program_calls` pass; `check`/`run`/`inspect`/Analysis share `CallSiteKey` bindings; plugin exports reconcile exactly with static manifests; no runtime name fallback | implemented (ADR-0054) | `callable_resolution`, `plugin_worker`, `analysis_trace` |
|
||||
| resource provider v2 CLI | `--provider`/`--allow-provider` select and authorize a `provider.json` schema-2 `c-abi-1` worker artifact; manifest/artifact/grants/duplicate kinds verified before spawn; sibling helper only | implemented linux/x86_64; other platforms fail closed (ADR-0055) | `provider_cli` |
|
||||
| capability handlers | trusted handler registry executes granted capabilities under budget/audit; missing handler is `capability.unavailable`; `fs.read` is the first real handler | implemented (ADR-0057) | `capability_handlers` |
|
||||
| strict mode | only the pure/Math execution path and the built-in stdout console channel; project/foreign/plugin/tool/trace/file/network grants are rejected | implemented L1; L2 not implemented | `tests/security`, `resource_streams`, `stdlib_product` |
|
||||
|
||||
## 4. Extension path classification
|
||||
@@ -120,9 +138,10 @@ review RFC, not a new crate per provider.
|
||||
| Extension path | Responsibility | State |
|
||||
|---|---|---|
|
||||
| Tool Protocol | external `marqdo` CLI tools, inspect/verify/IDE commands; versioned manifest and install/remove | implemented v1; not a standard-I/O replacement inside a user program |
|
||||
| Callable Plugin ABI | native callable functions and controlled experimental acceleration | implemented v1 (native + worker); not an ordinary JSON/CSV formatter |
|
||||
| Resource Provider | new resource kinds/devices/network/file endpoints | implemented v1 in-process, worker and trusted C ABI; not one provider per high-level algorithm |
|
||||
| Foreign kernel | explicit cross-language compatibility for Python/Node one-shot execution | implemented; not a Marqdo implementation of common algorithms |
|
||||
| Callable Plugin ABI | native callable functions and controlled experimental acceleration | implemented v1 (native + worker); static manifest is the contract and run reconciles exports exactly; not an ordinary JSON/CSV formatter |
|
||||
| Resource Provider | new resource kinds/devices/network/file endpoints | v2 CLI entry implemented for trusted worker transport on linux/x86_64 (ADR-0055); v1 in-process/trusted C ABI remain embedder APIs; not one provider per high-level algorithm |
|
||||
| Foreign kernel | explicit cross-language compatibility for Python/Node one-shot execution | implemented; registry accepts an explicitly declared unknown language; not a Marqdo implementation of common algorithms |
|
||||
| Official stdlib public alias | language-surface aliases such as `打印`/`print` declared in verified bundle metadata | implemented (ADR-0058); third parties cannot claim these names |
|
||||
| Shared registry/policy/budget/audit/trace | package/adapter identity, descriptor/version checks, per-request grants, timeouts, error classes and trace metadata | housed inside `marqdo-host`; do not invent a shared binary ABI for function calls and resource streams |
|
||||
|
||||
## 5. Gap and closure backlog
|
||||
@@ -146,6 +165,9 @@ that a phase is complete.
|
||||
| P3 | No concurrency tasks, atomics or cancellable long-running scheduling | open; separate ADR |
|
||||
| P3 | No native optimizer/JIT or columnar numeric backend | open; benchmark-first |
|
||||
| P3 | Windows Native/Worker ABI is unsupported; macOS/Windows CI is unverified | open |
|
||||
| P0 | RFC-EXT-0001 PR-04: `marqdo.yaml.extensions` + lock v4 extension selection, CLI composition-root wiring, `inspect --extensions` | **open / in progress** |
|
||||
| P0 | RFC-EXT-0001 PR-08: frozen release binary, external conformance rerun, SHA-bound evidence manifest, final docs/status convergence | **open / in progress** |
|
||||
| P1 | Provider worker transport only linux/x86_64; macOS/Windows provider lanes fail closed | open; separate platform work |
|
||||
|
||||
## 6. Documentation governance
|
||||
|
||||
@@ -184,3 +206,9 @@ that a phase is complete.
|
||||
- [ADR-0052: byte-exact HTTP framing](../adr/0051-byte-exact-http-framing.md) — accepted byte-list HTTP/1.1 parser/builder.
|
||||
- [Compute-machine RFC-0001](../MARQDO_COMPUTE_MACHINE_RFC_0001.md) and [core/stdlib RFC-0002](../MARQDO_COMPUTE_CORE_STDLIB_MIGRATION_RFC_0002.md) — design input.
|
||||
- [Architecture audit and refactor RFC](Marqdo_CLI_Latest_Architecture_Audit_and_Refactor_RFC.md) — review input for this migration.
|
||||
- [RFC-EXT-0001](RFC-EXT-0001.md) — extensibility closure task specification (implementation status tracked here and in STATUS).
|
||||
- [ADR-0054: single callable binding](../adr/0054-callable-binding-single-source.md) — one registry/binding pass, runtime dispatch by identity.
|
||||
- [ADR-0055: resource provider CLI v2](../adr/0055-resource-provider-cli-v2.md) — provider v2 manifest/worker CLI closure and trust boundary.
|
||||
- [ADR-0057: capability handler registration](../adr/0057-capability-handler-registration.md) — declared capability vs installed handler vs audit.
|
||||
- [ADR-0058: stdlib public aliases](../adr/0058-stdlib-public-alias.md) — verified metadata replaces print magic.
|
||||
- [`spec/callable-resolution.md`](../../spec/callable-resolution.md) and [`spec/resource-provider-v2.md`](../../spec/resource-provider-v2.md) — normative extension boundaries.
|
||||
+42
@@ -72,3 +72,45 @@ cargo build --release --locked -p marqdo-cli
|
||||
The ignored `.secrets/dev.env` may contain a Woodpecker API token for local
|
||||
queries/triggers. The token is not needed by the pipeline itself and must never
|
||||
be committed.
|
||||
|
||||
## External extension evidence (RFC-EXT-0001 PR-07/PR-08)
|
||||
|
||||
A release candidate must also prove that a **frozen** CLI binary can use
|
||||
extensions from physically separate repositories without modifying or
|
||||
rebuilding this workspace. This is a new necessary condition; it does **not**
|
||||
replace the security/platform/performance gates above.
|
||||
|
||||
Required inputs:
|
||||
|
||||
* a release build of this commit: `cargo build --release --locked -p marqdo-cli`;
|
||||
* the provider helper shipped next to it for the same target:
|
||||
`marqdo-provider-worker` (the provider transport resolves only that sibling;
|
||||
no `PATH` fallback);
|
||||
* a clean checkout of the external fixture repository
|
||||
`https://git.cflmy.cn/cflmy/marqdo-extension-conformance`.
|
||||
|
||||
Generation and validation:
|
||||
|
||||
```bash
|
||||
CLI="$(realpath target/release/marqdo)"
|
||||
python3 tools/ci/verify_extension_contracts.py \
|
||||
--cli "$CLI" \
|
||||
--fixtures /path/to/marqdo-extension-conformance
|
||||
python3 tools/ci/verify_extension_contracts.py \
|
||||
--validate docs/evidence/extension/<40-hex-source-SHA>/manifest.json
|
||||
```
|
||||
|
||||
The generator hashes the CLI before and after the external suite, records the
|
||||
source SHA and fixture repo SHA, and refuses to write evidence for a changed
|
||||
binary, a dirty fixture checkout, a `FAIL`, or an unexplained
|
||||
`UNSUPPORTED`/`SKIPPED` result. The external suite itself
|
||||
(`tests/run_all.py` in that repository) uses only `$MARQDO_BIN` (absolute),
|
||||
never Cargo, and covers: pinned-Git `.mq.md` package, worker ABI plugin,
|
||||
unknown foreign kernel, provider v2 worker, and an independent Analysis/Trace
|
||||
consumer.
|
||||
|
||||
The schema is [`evidence/extension/schema.json`](evidence/extension/schema.json);
|
||||
the generator is `tools/ci/verify_extension_contracts.py`. A manifest whose
|
||||
`tested_sha` is not the release SHA is invalid. Platform-specific results must
|
||||
be reported as `UNSUPPORTED` (for example provider worker on non-linux/x86_64);
|
||||
a Linux PASS never substitutes for a macOS/Windows lane.
|
||||
@@ -0,0 +1,195 @@
|
||||
# RFC-EXT-0001 implementation evidence (P0 core + PR-03/05/06/07 first pass)
|
||||
|
||||
Status: **partial, honest record.** PR-00/01/02/03/05/06 are implemented and
|
||||
tested on Linux x86_64 in this tree; PR-04 (extension selection/lock v4) and the
|
||||
final frozen-release evidence are still in progress. This document is not a
|
||||
release claim. The authoritative executed status is regenerated in
|
||||
`docs/STATUS.md` and `docs/evidence/extension/<SHA>/manifest.json`.
|
||||
|
||||
## 1. Identity and environment
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| Trees | `/root/work/marqdo-cli` (branch `feat/extensible-ecosystem`) and separate `/root/work/marqdo-extension-conformance` |
|
||||
| Baseline | `595279fe38048b52b96d9ff1e7d57a867ec5c4c6`; green baseline in `docs/evidence/ext-baseline-595279f.md` |
|
||||
| Rust | `rustc 1.100.0`, `cargo 1.100.0` |
|
||||
| OS / arch | Linux x86_64 |
|
||||
| Commands | logged under `.cache/ext/` (gitignored) |
|
||||
|
||||
No commit SHA is claimed for the implementation yet: work is uncommitted on the
|
||||
feature branch, so this file cannot be a same-SHA release artifact.
|
||||
|
||||
## 2. Executed workspace gate (current tree)
|
||||
|
||||
```text
|
||||
cargo fmt --all -- --check PASS (exit 0)
|
||||
cargo clippy --workspace --all-targets -- -D warnings PASS (exit 0)
|
||||
cargo test --workspace --locked PASS (exit 0)
|
||||
66 test targets: 584 passed, 0 failed, 0 ignored
|
||||
```
|
||||
|
||||
Targeted new suites:
|
||||
|
||||
```text
|
||||
cargo test -p marqdo-cli --test callable_resolution 14 passed
|
||||
cargo test -p marqdo-cli --test stdlib_alias_routing 5 passed
|
||||
cargo test -p marqdo-cli --test provider_cli 12 passed
|
||||
cargo test -p marqdo-cli --test analysis_trace 7 passed
|
||||
cargo test -p marqdo-cli --test plugin_worker 4 passed
|
||||
cargo test -p marqdo-cli --test print_routing 2 passed
|
||||
cargo test -p marqdo-cli --test architecture_boundaries 9 passed
|
||||
cargo test -p marqdo-host (includes capability_handlers 12)
|
||||
```
|
||||
|
||||
## 3. What was implemented (source paths)
|
||||
|
||||
### PR-01/02 — one static binding, bound runtime dispatch
|
||||
|
||||
* `crates/marqdo-ir/src/call_binding.rs` — `CallSiteKey`, `BoundTarget`
|
||||
(`Builtin`/`Marqdo`/`AbiPlugin`/`DynamicValue`), deterministic
|
||||
`CallBindingTable`, unit tests.
|
||||
* `crates/marqdo-ir/src/callable.rs` — `try_from_program` (rejects duplicate
|
||||
exports instead of first-wins), `OfficialAlias` registration, dotted-prefix
|
||||
conflict helpers, `function_id`.
|
||||
* `crates/marqdo-frontend/src/calls.rs` — the single `bind_program_calls` pass,
|
||||
RFC priority matrix, import namespace conflicts, exact plugin signature
|
||||
validation; `validate_module` is a standalone-frontend wrapper.
|
||||
* `crates/marqdo-frontend/src/analyze.rs` — `analyze_source_for_program` defers
|
||||
call checking to the composition root; standalone `analyze_source` keeps its
|
||||
single-document checks for the conformance corpora.
|
||||
* `crates/marqdo-runtime/src/interpreter.rs` — dispatch by `CallSiteKey`; the
|
||||
unknown-plugin fallback, `print_override` branch and dead `resolve_function`
|
||||
are removed; bound ABI calls normalise positional arguments to manifest order.
|
||||
* `crates/cli/src/extension_descriptors.rs` — static plugin manifest reading
|
||||
(no `dlopen`/spawn), signature parsing (defaults rejected), bundle-relative
|
||||
path checks, artifact sha helpers.
|
||||
* `crates/cli/src/project_prepare.rs` — one `prepare()`: load → descriptors →
|
||||
registry → bind once → `PreparedProgram`; diagnostics are appended once.
|
||||
* `crates/cli/src/commands/{check,run,inspect}.rs` + `loader.rs` — all consume
|
||||
`prepare_project`; `run` verifies artifacts before load and reconciles the
|
||||
Host exports one-to-one (`ext.plugin_binding_mismatch` on any difference).
|
||||
* `crates/cli/src/analysis.rs` — Analysis `calls[].state/target` are projected
|
||||
from the same binding table (no second resolver).
|
||||
* `crates/cli/tests/callable_resolution.rs` — CALL-01/02/03/04/05/06/07/08/09/
|
||||
11/12/13/14/15/16 as black-box CLI tests (CALL-10 has unit coverage in
|
||||
`commands/run.rs` for missing/extra runtime exports).
|
||||
|
||||
Normative docs: `spec/callable-resolution.md`, `docs/adr/0054-*`,
|
||||
`spec/plugin-abi.md` §12, `spec/analysis-v2.md` calls note.
|
||||
|
||||
### PR-03 — resource provider v2 through the normal CLI
|
||||
|
||||
* `crates/cli/src/main.rs` — repeatable `--provider PATH` and
|
||||
`--allow-provider NAME` on `run`/`call` only.
|
||||
* `crates/cli/src/commands/sandbox.rs` — grants map to
|
||||
`allow_resource_provider`; `pure`/`strict` preflight refuse the flags;
|
||||
wildcards rejected.
|
||||
* `crates/cli/src/provider_manifest.rs` — strict schema v2 parser/verifier,
|
||||
target selection, bundle containment, sha256, reserved-kind rejection,
|
||||
duplicate kind/provider checks, sibling `marqdo-provider-worker` resolution
|
||||
(no `PATH` fallback; `ext.worker_unavailable`/`ext.platform_unsupported`).
|
||||
* `crates/cli/src/commands/run.rs` — verify all manifests/artifacts/grants and
|
||||
duplicate kinds before spawning; spawn only granted+verified providers; no
|
||||
native fallback; no new `HostOp`/`resource_request` branch.
|
||||
* Tests: `crates/cli/tests/provider_cli.rs` (real C sensor + real worker
|
||||
helper), 12 tests; `spec/resource-provider-v2.md`, ADR-0055, README section.
|
||||
|
||||
Provider evidence recorded by the PR-03 implementer:
|
||||
|
||||
| ID | Result | Evidence summary |
|
||||
|---|---|---|
|
||||
| PROV-01 | PASS | exit 0, `count=5`, `eof=true`, one worker/open/close marker |
|
||||
| PROV-02 | PASS | exit 1 `permission.denied`; helper never started |
|
||||
| PROV-03 | PASS | exit 2 `ext.provider_grant_unmatched`; no worker |
|
||||
| PROV-04 | PASS | exit 2 `ext.duplicate_provider_kind`; no worker |
|
||||
| PROV-05 | PASS | one provider, two kinds, counts `[5,2]`, both closed |
|
||||
| PROV-06 | PASS | `stdio/file/tcp/tls/udp/tcp-listener` rejected `ext.manifest_invalid` |
|
||||
| PROV-07 | PASS | sha mismatch / symlink escape / `..` → `ext.artifact_integrity` before spawn |
|
||||
| PROV-08 | PASS | `ext.no_matching_artifact` |
|
||||
| PROV-09 | PASS | v1 → `ext.unsupported_provider_schema`, no migration |
|
||||
| PROV-10 | PASS | pure `cli.invalid_grants`, strict `strict.unsupported_grant`, `*` rejected |
|
||||
| PROV-13 | PASS | sibling helper missing → `ext.worker_unavailable`, PATH helper unused |
|
||||
|
||||
Platform: provider worker transport is claimed **linux/x86_64 only**; macOS and
|
||||
Windows are explicitly `UNSUPPORTED`/fail-closed (`ext.platform_unsupported`),
|
||||
not claimed supported. PROV-11/12/14/15 belong to host-protocol and PR-07
|
||||
external closure and are not claimed by the PR-03 CLI matrix.
|
||||
|
||||
### PR-05 — capability handler registry
|
||||
|
||||
`crates/marqdo-host/src/capability.rs` now has a trusted handler directory,
|
||||
`fs.read` as a real handler, decide → handler-installed → execute under budget →
|
||||
audit with duration; missing handler stays `capability.unavailable`, duplicate/
|
||||
reserved/empty registrations are rejected. `crates/marqdo-host/tests/
|
||||
capability_handlers.rs` has 12 CAP tests (CAP-01…CAP-12); ADR-0057 and
|
||||
`spec/security.md` updated. `cargo test -p marqdo-host` PASS.
|
||||
|
||||
### PR-06 — official stdlib public aliases
|
||||
|
||||
`stdlib/stdlib.json` declares `public_aliases` (`print`/`打印` →
|
||||
`io.mq.md::写值`) and `aliases_digest`; `crates/cli/src/stdlib.rs` verifies the
|
||||
metadata digest and expected target signature; `loader.rs` loads the target
|
||||
module only when the alias name is referenced and produces `OfficialAlias`
|
||||
records; `project_prepare` registers them and the binding pass targets the
|
||||
ordinary `Marqdo` function. `program_uses_print`, `Program.print_override`, the
|
||||
runtime print branch and the AST scanner are deleted; the placeholder builtin
|
||||
still fails with `kernel.unavailable` for unbundled embedders. Tests:
|
||||
`crates/cli/tests/stdlib_alias_routing.rs` (5) + existing print/format/Trace
|
||||
goldens; the stdlib fixture aliases that collided with builtin namespaces
|
||||
(`table`/`text`/`fs`) were renamed and the bundle digest regenerated.
|
||||
`tools/pack-stdlib.py` verifies `aliases_digest` before packaging.
|
||||
ADR-0058 documents the decision.
|
||||
|
||||
### PR-07 (first pass) — independent external repository
|
||||
|
||||
`/root/work/marqdo-extension-conformance` is a separate Git repository (own
|
||||
history, remote `https://git.cflmy.cn/cflmy/marqdo-extension-conformance`,
|
||||
pushed; commit `b729afc` at the time of this record). It contains:
|
||||
|
||||
* `pure-lib/` + `consumer/` with a pinned full-SHA Git dependency;
|
||||
* `plugin/` — real C ABI v1 worker plugin, three exports under two prefixes;
|
||||
* `kernel/` — `mocklang` provider with a language the CLI does not know;
|
||||
* `provider/` — `provider.json` v2 + real C ABI sensor library;
|
||||
* `tool/` — stdlib-only Python consumer of Analysis v2 / Trace v2;
|
||||
* `tests/run_all.py`, `tests/verify_frozen_cli.py`, `CONTRACT.md`,
|
||||
`.github/workflows/conformance.yml`.
|
||||
|
||||
Provisional run against the current development binary (debug build, not a
|
||||
release candidate):
|
||||
|
||||
```text
|
||||
[PASS] plugin_worker, callable_registry, foreign_kernel,
|
||||
resource_provider_cli, package_pinned_git,
|
||||
tool_analysis_consumer, negative_security
|
||||
(all categories PASS; frozen CLI sha256 recorded in evidence/results.json)
|
||||
```
|
||||
|
||||
This is **not** final PR-07/PR-08 evidence: the binary was not a `--release`
|
||||
candidate, and `tools/ci/verify_extension_contracts.py` has not yet emitted a
|
||||
`docs/evidence/extension/<SHA>/manifest.json`. The external suite will be rerun
|
||||
against the frozen release binary after PR-04 lands.
|
||||
|
||||
## 4. Known gaps / deviations (not hidden)
|
||||
|
||||
1. **PR-04 not landed yet.** `marqdo.yaml.extensions` and lock v4 are still in
|
||||
progress; the CLI composition root for extension selection is not wired.
|
||||
2. **Provider platform claims are Linux x86_64 only**; macOS/Windows are
|
||||
explicitly unsupported for the worker transport. The RFC's mac/Windows
|
||||
provider lanes are not claimed.
|
||||
3. **Additive provider error codes** `ext.manifest_invalid`,
|
||||
`ext.duplicate_provider`, `ext.provider_grant_unmatched` were added because
|
||||
the RFC's frozen code list has no precise code for malformed v2, duplicate
|
||||
provider names, or an unmatched `--allow-provider`; documented in
|
||||
`spec/resource-provider-v2.md` and ADR-0055.
|
||||
4. **`--allow-provider` without a selected manifest** aborts with
|
||||
`permission.denied` before spawning rather than silently ignoring the grant
|
||||
(needed to satisfy PROV-02 with the existing spawn-on-register Host API).
|
||||
5. **Analysis v2 `calls[].state/target` semantics changed for official aliases**
|
||||
(print now projects as a `function` target). This is a projection of
|
||||
existing fields, documented in `spec/analysis-v2.md`/ADR-0054/ADR-0058;
|
||||
there is no v3 bump and the private binding table is not exposed.
|
||||
6. **CALL-10's host-side mismatches** are unit-tested for missing/extra exports;
|
||||
a live TOCTOU signature/digest mismatch is covered by artifact-tamper tests
|
||||
plus exact reconciliation, not by swapping a manifest mid-run.
|
||||
7. Full `--release` build, frozen external rerun, SHA-bound evidence manifest,
|
||||
docs/STATUS/CURRENT/COMPATIBILITY/CHANGELOG finalisation remain for PR-08.
|
||||
@@ -0,0 +1,82 @@
|
||||
# RFC-EXT-0001 baseline audit — `595279f`
|
||||
|
||||
Status: **baseline evidence recorded before implementation.** This is not a
|
||||
release claim and none of the new RFC-EXT-0001 behaviour existed at this SHA.
|
||||
|
||||
## 1. Identity and environment
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| Repository | `cflmy/marqdo-cli` (private remote `https://git.cflmy.cn/cflmy/marqdo-cli`) |
|
||||
| Baseline commit | `595279fe38048b52b96d9ff1e7d57a867ec5c4c6` (`master`, 2026-11-21) |
|
||||
| Working branch | `feat/extensible-ecosystem` |
|
||||
| Rust | `rustc 1.100.0 (0ef1bc386 2026-11-09)` |
|
||||
| Cargo | `cargo 1.100.0 (3acc79c0c 2026-11-05)` |
|
||||
| OS / arch | Linux `x86_64` (Ubuntu container) |
|
||||
| Local homes | `RUSTUP_HOME=.rustup-home`, `CARGO_HOME=.cargo-home` |
|
||||
| Command log | `.cache/ext/baseline.log` (local, gitignored) |
|
||||
|
||||
## 2. Executed gate (same SHA, before any RFC-EXT-0001 edit)
|
||||
|
||||
```text
|
||||
cargo fmt --all -- --check exit 0 PASS
|
||||
cargo clippy --workspace --all-targets -- -D warnings exit 0 PASS
|
||||
cargo test --workspace --locked exit 0 PASS
|
||||
62 test targets: 521 passed, 0 failed, 2 ignored
|
||||
```
|
||||
|
||||
The RFC §2.2 static inventory commands were also run and their findings are
|
||||
recorded in §3. A green baseline is only the starting point, not evidence for
|
||||
any new feature.
|
||||
|
||||
## 3. Source facts at the baseline (RFC §2.1 refresh)
|
||||
|
||||
Each row was checked against the actual tree, not against the RFC prose. None of
|
||||
the rows was `already_closed` at `595279f`.
|
||||
|
||||
| ID | Observed at `595279f` | Impact | RFC treatment |
|
||||
|---|---|---|---|
|
||||
| EXT-01 | `marqdo-frontend/src/units.rs` `SemanticMode` is `Exec`/`Knowledge` only; unknown `@xxx` is `sem.invalid_mode_marker` | third parties cannot add an execution mode (intended closure) | keep; metadata is inert Markdown |
|
||||
| EXT-02 | `frontend/src/calls.rs` checks Member builtin before import; `runtime/src/interpreter.rs` checks import before builtin | check and run can bind different targets | PR-01/02 single binding |
|
||||
| EXT-03 | `ir/src/callable.rs` has `CallableRegistry` but calls still use `builtins::find` and runtime fallbacks | registry was not the single truth | PR-01/02 |
|
||||
| EXT-04 | interpreter tolerated undeclared `alias.name` as a plugin call when `external_callables` was empty | static-unknown symbol failed only at run time | PR-02 remove fallback |
|
||||
| EXT-05 | `cli/src/commands/run.rs` synthesised `params: Vec::new()` descriptors for loaded exports | manifest/runtime signature could differ silently | PR-02 exact reconciliation |
|
||||
| EXT-06 | `loader.rs` validated the program before the CLI appended static plugin descriptors, then validated again | duplicated diagnostics and ordering hazards | PR-01 single `prepare` finalize |
|
||||
| EXT-07 | `host/src/host/providers.rs` has Rust/C/Worker provider registration; CLI had no `--provider` | providers were only reachable by trusted embedders | PR-03 |
|
||||
| EXT-08 | `host/src/capability.rs::execute` implemented only `fs.read`; other names returned unavailable | declaring a capability did not mean executing it | PR-05 handler registry |
|
||||
| EXT-09 | `host/src/host.rs::resource_request` has per-string built-in operations | adding a non-streaming operation required core edits | PR-03/05; keep core operations |
|
||||
| EXT-10 | `cli/src/loader.rs::program_uses_print` injected `stdlib/io.mq.md` and set `Program.print_override`; runtime special-cased `打印/print` | migrating another stdlib function by copying this pattern would hard-code every name | PR-06 public aliases |
|
||||
| EXT-11 | `foreign/src/lib.rs::KernelRegistry` supports unknown languages; old `normalize_language` only knows Python/Node | registry is the execution path, legacy helper is display-only | keep registry as the only query |
|
||||
| EXT-12 | Plugin ABI v1 Native/Worker implemented; Wasm unsupported; Tool Protocol tested | do not rebuild plugin/tool platform | keep + add identity reconciliation |
|
||||
| EXT-13 | `package/src/lib.rs` supports path + pinned `git` + package instances; `stdlib/` is a verified bundle | real `.mq.md` source decoupling exists | keep + external black-box test |
|
||||
| EXT-14 | strict L1 permits only limited pure computation and stdout and rejects Worker/Foreign/Provider | project mode is not an OS sandbox | keep fail-closed; strict L2 is a separate RFC |
|
||||
|
||||
## 4. Issues reproduced while recording this baseline
|
||||
|
||||
They were reproduced while writing the RFC acceptance fixtures; all are fixed by
|
||||
the PR series recorded later in `docs/STATUS.md` and
|
||||
`docs/evidence/extension/<SHA>/manifest.json`:
|
||||
|
||||
1. **Duplicate resolution (EXT-02/03/04).** A fixture with an import alias that
|
||||
matched a builtin dotted namespace (`import: {math: ./math.mq.md}` plus
|
||||
`math.eval(...)`) had no deterministic binding rule; the frontend checked the
|
||||
builtin while the runtime checked the import first.
|
||||
2. **Runtime plugin guessing (EXT-04).** `solver.add(...)` without `--plugin`
|
||||
reached the runtime and attempted `PluginInvoke` instead of failing during
|
||||
`check` with `symbol.unknown`.
|
||||
3. **Synthesised plugin signatures (EXT-05).** `run` could execute a plugin
|
||||
export whose static descriptor had an empty parameter list, so an arity or
|
||||
position/name mismatch was only discovered (or not) at the ABI boundary.
|
||||
4. **Print magic (EXT-10).** `打印`/`print` were routed by a whole-AST
|
||||
`program_uses_print` scan plus a runtime name special case; there was no
|
||||
generic de-magicking path for a second official stdlib function.
|
||||
5. **Provider CLI gap (EXT-07).** There was no `--provider`/`--allow-provider`;
|
||||
an external `provider.json` could not be used through the shipped binary.
|
||||
|
||||
## 5. Not claimed by this baseline
|
||||
|
||||
* No `--provider`/`--allow-provider` existed; strict L2 remains unimplemented.
|
||||
* No frozen-binary external repository evidence existed.
|
||||
* No `docs/evidence/extension/<SHA>/manifest.json` existed.
|
||||
* G3 remote security and G4 performance status is unchanged by this document;
|
||||
see `docs/STATUS.md` and `docs/releasing.md`.
|
||||
@@ -0,0 +1,32 @@
|
||||
# External-extension evidence
|
||||
|
||||
RFC-EXT-0001 §10.2/§11.3 requires SHA-bound proof that an **unchanged** CLI
|
||||
binary can use extensions from physically separate Git repositories. This
|
||||
directory holds that evidence.
|
||||
|
||||
* `schema.json` — JSON Schema for the evidence manifest.
|
||||
* `<40-hex-source-SHA>/manifest.json` — generated by
|
||||
`tools/ci/verify_extension_contracts.py`; never hand-written.
|
||||
|
||||
Generation (from a clean fixture checkout and a release build of this repo):
|
||||
|
||||
```bash
|
||||
cargo build --release --locked -p marqdo-cli
|
||||
CLI="$(realpath target/release/marqdo)"
|
||||
python3 tools/ci/verify_extension_contracts.py \
|
||||
--cli "$CLI" \
|
||||
--fixtures /path/to/marqdo-extension-conformance
|
||||
python3 tools/ci/verify_extension_contracts.py \
|
||||
--validate docs/evidence/extension/<SHA>/manifest.json
|
||||
```
|
||||
|
||||
The generator refuses to write evidence when:
|
||||
|
||||
* the CLI binary hash changes between the start and end of the suite;
|
||||
* the fixture repository has uncommitted changes;
|
||||
* a required result is missing or `FAIL`;
|
||||
* `UNSUPPORTED`/`SKIPPED` is recorded without `--allow-unverified` and a report
|
||||
entry explaining the platform limitation.
|
||||
|
||||
A local or container run is **not** a substitute for the release gates in
|
||||
`docs/releasing.md` (G3/G4), and no tag is created by this evidence.
|
||||
@@ -0,0 +1,63 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "https://marqdo.dev/schemas/extension-evidence-v1.json",
|
||||
"title": "Marqdo external-extension evidence manifest",
|
||||
"description": "SHA-bound evidence that independent repositories can use the frozen CLI without modifying or recompiling marqdo-cli (RFC-EXT-0001 §11.3). Generated by tools/ci/verify_extension_contracts.py; never hand-edited.",
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": [
|
||||
"schema",
|
||||
"schema_version",
|
||||
"tested_sha",
|
||||
"cli_binary_sha256",
|
||||
"fixture_repo_sha",
|
||||
"os",
|
||||
"arch",
|
||||
"results",
|
||||
"commands",
|
||||
"failures",
|
||||
"unverified"
|
||||
],
|
||||
"properties": {
|
||||
"schema": { "const": "marqdo.extension-evidence" },
|
||||
"schema_version": { "const": 1 },
|
||||
"tested_sha": {
|
||||
"type": "string",
|
||||
"pattern": "^[0-9a-f]{40}$",
|
||||
"description": "Exact marqdo-cli source commit the frozen binary was built from."
|
||||
},
|
||||
"cli_binary_sha256": {
|
||||
"type": "string",
|
||||
"pattern": "^[0-9a-f]{64}$"
|
||||
},
|
||||
"fixture_repo_sha": {
|
||||
"type": "string",
|
||||
"pattern": "^[0-9a-f]{40}$"
|
||||
},
|
||||
"os": { "type": "string", "enum": ["linux", "macos", "windows"] },
|
||||
"arch": { "type": "string" },
|
||||
"results": {
|
||||
"type": "object",
|
||||
"additionalProperties": {
|
||||
"type": "string",
|
||||
"enum": ["PASS", "FAIL", "UNSUPPORTED", "SKIPPED"]
|
||||
},
|
||||
"required": [
|
||||
"callable_registry",
|
||||
"plugin_worker",
|
||||
"foreign_kernel",
|
||||
"resource_provider_cli",
|
||||
"package_pinned_git",
|
||||
"tool_analysis_consumer",
|
||||
"negative_security"
|
||||
]
|
||||
},
|
||||
"commands": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"minItems": 1
|
||||
},
|
||||
"failures": { "type": "array", "items": { "type": "string" } },
|
||||
"unverified": { "type": "array", "items": { "type": "string" } }
|
||||
}
|
||||
}
|
||||
@@ -129,3 +129,33 @@ self-hosted G-C URL. See
|
||||
delete the failing test.
|
||||
- If the security gate regresses: set strict back to `Unavailable`, publish a
|
||||
security note, and do not claim isolation until the lane is green again.
|
||||
|
||||
## 7. Extension-ecosystem gate (RFC-EXT-0001)
|
||||
|
||||
Before a tag, in addition to §3 and §4:
|
||||
|
||||
1. `cargo build --release --locked -p marqdo-cli` and build
|
||||
`-p marqdo-provider-worker`; ship both binaries in the release archive for
|
||||
the same target. A provider request without the sibling helper must fail
|
||||
with `ext.worker_unavailable` — never fall back to `PATH`.
|
||||
2. Run the external frozen-binary suite from
|
||||
`https://git.cflmy.cn/cflmy/marqdo-extension-conformance` against the exact
|
||||
release binaries and generate
|
||||
`docs/evidence/extension/<40-hex-source-SHA>/manifest.json` with
|
||||
`tools/ci/verify_extension_contracts.py`. The manifest must validate against
|
||||
`docs/evidence/extension/schema.json`, its `tested_sha` must equal the
|
||||
tagged commit, and every mandatory result must be `PASS` on the claimed
|
||||
platform. `UNSUPPORTED` is allowed only for a platform explicitly excluded
|
||||
from the support matrix in `COMPATIBILITY.md`.
|
||||
3. `check`/`run`/`inspect`/Analysis share one prepared call binding
|
||||
(`spec/callable-resolution.md`); `check` never loads an extension binary;
|
||||
plugin exports reconcile exactly with static manifests; official stdlib
|
||||
aliases are verified metadata with byte-identical print output.
|
||||
4. Existing gates remain mandatory and unchanged: G3 strict isolation evidence,
|
||||
G4 measured performance on the fixed node, native platform lanes, schema
|
||||
consumers and `tools/ci/release_evidence.py`. The extension evidence is an
|
||||
additional gate; it never substitutes for them, and local/container smoke is
|
||||
not a release claim.
|
||||
5. If any extension gate is missing or mismatched, the release decision is
|
||||
**DO NOT RELEASE**. Tagging and asset publication still require explicit
|
||||
owner approval.
|
||||
Reference in new issue
Block a user