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:
cflmy committed 2026-11-22 00:17:36 +08:00
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
+196
View File
@@ -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.
+105
View File
@@ -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.
+33 -5
View File
@@ -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
View File
@@ -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.
+82
View File
@@ -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`.
+32
View File
@@ -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.
+63
View File
@@ -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" } }
}
}
+30
View File
@@ -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.