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.