feat(ext): single callable binding, provider v2 CLI, capability handlers, stdlib aliases
Implements RFC-EXT-0001 PR-00..PR-07 first pass: - CallSiteKey/CallBindingTable + one frontend binding pass; runtime dispatch by identity - prepare composition root shared by check/run/inspect/Analysis; exact plugin reconciliation - provider.json v2 --provider/--allow-provider worker CLI with fail-closed verification - capability handler registry with real fs.read and audit - verified stdlib public aliases replace print_override/AST scan - docs: specs, ADR-0054/0055/0057/0058, README, CI/release gates, evidence PR-04 extension selection/lock v4 and final frozen-binary evidence remain.
This commit is contained in:
1 parent
9aa536c2c9
commit
1f6fd644a0
54 files changed
+8710
-828
No files matched your search
@@ -0,0 +1,125 @@
|
||||
# ADR-0054: One static callable binding, one runtime dispatch
|
||||
|
||||
- Status: Accepted (2026-11-21)
|
||||
- Supersedes the resolution model of ADR-0009/ADR-0010 where they conflict
|
||||
- Implements: RFC-EXT-0001 §4 (PR-01/PR-02)
|
||||
|
||||
## Context
|
||||
|
||||
The tree had four independent ways to decide what a call means:
|
||||
|
||||
1. `marqdo-frontend/src/calls.rs` checked a Member call's builtin name before
|
||||
its import alias;
|
||||
2. `marqdo-runtime/src/interpreter.rs` checked the import alias before the
|
||||
builtin for the same expression;
|
||||
3. the runtime treated an undeclared `alias.name` as a plugin invocation when
|
||||
`program.external_callables` was empty ("try it at run time");
|
||||
4. `marqdo-cli` synthesised an empty-parameter descriptor (`params: Vec::new()`)
|
||||
for exports that were loaded but not statically described.
|
||||
|
||||
Consequences observed while building RFC-EXT-0001's fixtures:
|
||||
|
||||
* `check` could accept a call that `run` dispatched to a different
|
||||
implementation (or vice versa);
|
||||
* an unknown symbol failed only at run time, with a Host side effect already
|
||||
attempted;
|
||||
* an import alias that happened to equal a builtin dotted namespace (`math`)
|
||||
silently changed the meaning of `math.eval(...)` depending on the pipeline;
|
||||
* plugin arity/name errors could pass static checking and only fail (or
|
||||
succeed with different arguments) at the ABI boundary.
|
||||
|
||||
The language contract (RFC-LANG-0002) already says calls are expressions and
|
||||
that `check` and `run` must agree; the implementation had no such guarantee.
|
||||
|
||||
## Decision
|
||||
|
||||
1. **One registry.** `marqdo_ir::callable::CallableRegistry` is the only static
|
||||
table. It contains builtins (including official bundled-stdlib public
|
||||
aliases), module functions keyed by canonical name plus unique local name,
|
||||
and exact plugin exports (`namespace.function`). Duplicate declarations are
|
||||
rejected when the registry is built; order never decides the answer.
|
||||
2. **One binding pass.** `marqdo_frontend::calls::bind_program_calls(program,
|
||||
registry)` walks every statically visible call expression exactly once and
|
||||
produces `CallBindingTable` plus diagnostics. It replaces the split
|
||||
`validate_module`/`validate_program` priority logic on the CLI path (the
|
||||
standalone frontend keeps a wrapper for single-document tests). The result
|
||||
is installed on `Program::call_bindings`.
|
||||
3. **Deterministic identity.** A call site is
|
||||
`(module id, function id, byte span)` (`CallSiteKey`), never a disk path,
|
||||
registration order or hash-map iteration. A bound target is one of:
|
||||
* `Builtin { canonical_name }` — fixed core function;
|
||||
* `Marqdo { function }` — exact `FunctionId` (module functions and official
|
||||
stdlib aliases such as `打印`/`print` → `io.mq.md::写值`);
|
||||
* `AbiPlugin { package, export, digest, param_names }` — complete export
|
||||
name plus the statically verified artifact digest and manifest argument
|
||||
order;
|
||||
* `DynamicValue` — a language value (for example a `FunctionRef`); this is
|
||||
the **only** non-static path and cannot reach an ABI export by name.
|
||||
4. **Runtime dispatches by identity.** `eval_call` looks up the site's binding
|
||||
and calls the recorded target. It never calls `builtins::find(qualified)`,
|
||||
never inspects `external_callables.is_empty()` and never guesses a plugin.
|
||||
A missing binding is an internal error (`internal.error`), not a reason to
|
||||
re-resolve.
|
||||
5. **Prepare finalises once.** `marqdo-cli` has one composition step
|
||||
(`project_prepare::prepare`): load sources → read extension descriptors
|
||||
(no `dlopen`/spawn) → build the registry → bind calls once. `check`,
|
||||
`run`/`call`, `inspect` and Analysis consume that one prepared program.
|
||||
Static plugin descriptors are inserted before binding, not appended after a
|
||||
first validation.
|
||||
6. **Exact run-time reconciliation.** `run` verifies each selected plugin
|
||||
artifact, loads it, then compares the Host's actual exports (name, raw
|
||||
signature, artifact digest, owner package) with the static descriptors
|
||||
one-to-one. Any extra, missing or altered export fails with
|
||||
`ext.plugin_binding_mismatch` before the entry function runs. No descriptor
|
||||
is synthesised at run time.
|
||||
7. **Print is not special.** `Program.print_override` and the runtime
|
||||
`打印`/`print` branch are removed. The builtin placeholder remains only for
|
||||
embedders without the official bundle and fails with
|
||||
`kernel.unavailable`; the official bundle declares aliases in verified
|
||||
metadata (ADR-0058).
|
||||
|
||||
## Priority matrix (normative)
|
||||
|
||||
See `spec/callable-resolution.md` for the complete matrix and diagnostics. In
|
||||
short:
|
||||
|
||||
* `f(...)`: local variable → official alias/reserved builtin → current
|
||||
namespace → canonical name → unique local name → otherwise
|
||||
`symbol.unknown` (ambiguity is an error, never a first-match);
|
||||
* `alias.f(...)`: explicit import alias → builtin dotted namespace → exact
|
||||
plugin export → otherwise `symbol.unknown`;
|
||||
* `some_value.f(...)`: dynamic language dispatch only.
|
||||
|
||||
Import aliases that collide with a builtin or plugin dotted namespace are
|
||||
rejected at prepare with `ext.import_namespace_conflict`; duplicate plugin
|
||||
exports are rejected with `ext.duplicate_callable`.
|
||||
|
||||
## Consequences
|
||||
|
||||
* `check` and `run` now share binding identity; CALL-01…CALL-16 in
|
||||
`crates/cli/tests/callable_resolution.rs` pin the matrix.
|
||||
* 0.x breaking change: a project importing a module under an alias that equals
|
||||
a builtin namespace (for example `math`) must rename the alias. There is no
|
||||
`--legacy` switch and no dual semantics.
|
||||
* Analysis v2's `calls[].state/target` are now projected from the same binding
|
||||
(official aliases appear as `function` targets). Analysis v2 schema and
|
||||
fields are otherwise unchanged; private `CallBindingTable` is not serialized.
|
||||
* Runtime no longer performs per-call name resolution, so the dynamic path is
|
||||
limited to language values. A text or map value called as a function is
|
||||
`call.not_callable` and never becomes a Host plugin request.
|
||||
* Plugin manifests must be complete before binding: a manifest with a missing
|
||||
or malformed signature is a prepare error; ABI v1 default values are
|
||||
rejected until the wire semantics are versioned.
|
||||
|
||||
## Rejected alternatives
|
||||
|
||||
* **Pick a fixed precedence and keep two implementations.** Rejected: the RFC
|
||||
requires one static answer, and duplicated precedence is exactly the defect.
|
||||
* **Build the registry lazily in the runtime.** Rejected: `check` would still
|
||||
not prove the binding, and runtime loading would change static resolution.
|
||||
* **Keep the empty-`external_callables` fallback for "developer convenience".**
|
||||
Rejected: it turns a compile error into a Host call attempt and breaks
|
||||
`check`'s no-execution guarantee.
|
||||
* **Expose `CallableId`/`CallBindingTable` in Analysis v2.** Rejected:
|
||||
private IR must not become a public wire contract without a version bump.
|
||||
EOF
|
||||
@@ -0,0 +1,196 @@
|
||||
# ADR-0055: Resource Provider v2 through the normal CLI
|
||||
|
||||
Status: **Accepted**
|
||||
Date: 2026-11-21
|
||||
Relates to: RFC-EXT-0001 §5/§16/§18, ADR-0033, ADR-0034, ADR-0035, ADR-0036,
|
||||
ADR-0037, ADR-0038, ADR-0021 (strict L1), ADR-0052 (single Markdown semantics)
|
||||
Specs: `spec/resource-provider-v2.md`
|
||||
Implementation: `crates/cli/src/provider_manifest.rs`,
|
||||
`crates/cli/src/commands/sandbox.rs`, `crates/cli/src/commands/run.rs`,
|
||||
`crates/cli/src/main.rs`, `crates/cli/tests/provider_cli.rs`
|
||||
|
||||
## Context
|
||||
|
||||
The host already implements versioned resource-provider registration
|
||||
(`register_resource_provider`, `register_worker_resource_provider`,
|
||||
`register_c_resource_provider`, `register_provider_package`) and
|
||||
`resource.open` dispatches unknown kinds through that registry with a provider
|
||||
name grant (ADR-0033/0035/0036/0037/0038). What was missing was a **public
|
||||
composition-root entry point**: `main.rs`/`SandboxSettings`/`run.rs` had no
|
||||
`--provider`/`--allow-provider`, so an external repository could not use a new
|
||||
resource kind on a frozen `marqdo` binary without patching and rebuilding the
|
||||
CLI (RFC-EXT-0001 EXT-07).
|
||||
|
||||
The existing `marqdo.provider` manifest (`schema_version: 1`, ADR-0037) is a
|
||||
host-embedding installation format: `name/kinds/abi/library`, no `version`, no
|
||||
targeted artifact digest and no transport. It cannot support portable,
|
||||
integrity-checked CLI loading. RFC-EXT-0001 §5.3 asks for a v2 document rather
|
||||
than silently overloading v1. It also requires that selecting an extension is
|
||||
not authorizing it, that `pure`/`strict` keep failing closed, and that no new
|
||||
`HostOp`/builtin/business branch is introduced.
|
||||
|
||||
This ADR records the PR-03 decision on the current branch.
|
||||
|
||||
## Decision
|
||||
|
||||
### 1. CLI surface and ordering
|
||||
|
||||
`--provider PATH` (repeatable, a `provider.json` file) and
|
||||
`--allow-provider NAME` (repeatable, exact name) are added to `SandboxArgs`, so
|
||||
they are shared by `run` and `call` only. `check`/`inspect` do not declare them
|
||||
and never read a provider manifest. `SandboxSettings` carries
|
||||
`providers: Vec<PathBuf>` and `allow_provider: Vec<String>`; the `project`
|
||||
capability set calls the existing `Capabilities::allow_resource_provider(name)`
|
||||
for each grant.
|
||||
|
||||
Run ordering follows RFC-EXT-0001 §18.2: `prepare` (no provider work) →
|
||||
diagnostics → mode/strict preflight → capabilities → host assembly and budgets
|
||||
→ kernels → **all provider manifests/targets/artifacts/grants/duplicate kinds
|
||||
verified and plugin artifacts verified** → plugin workers loaded and exports
|
||||
reconciled → provider helpers spawned → entry-function check → execute. No
|
||||
worker (plugin or provider) starts before every T6/T6b verification passes, and
|
||||
the main function never runs after a provider failure.
|
||||
|
||||
`pure` and `strict` reject both flags in preflight (`cli.invalid_grants` /
|
||||
`strict.unsupported_grant`, exit 2) without silently switching to `project`.
|
||||
`--allow-provider` rejects wildcards (`*`, `?`, `[`, `]`) and empty names; a
|
||||
grant that matches no selected manifest is `ext.provider_grant_unmatched`
|
||||
(exit 2). A `--provider` selected without its exact grant is
|
||||
`permission.denied` (exit 1) before the helper is spawned.
|
||||
|
||||
### 2. Strict v2 manifest parser
|
||||
|
||||
New `crates/cli/src/provider_manifest.rs` owns the document, separate from the
|
||||
plugin `plugin.yaml` parser:
|
||||
|
||||
* accepts exactly `schema = "marqdo.provider"`, `schema_version = 2`,
|
||||
`abi = "c-abi-1"`, `transport = "worker"`; other versions/ABIs/transports are
|
||||
`ext.unsupported_provider_schema` (no silent migration, no v1 fallback from
|
||||
the CLI);
|
||||
* strict dotted lowercase name/kind grammar, strict SemVer, non-empty unique
|
||||
non-reserved kinds, bounded counts, known/vendor `permissions_requested`
|
||||
declarations only, optional non-executable `metadata`;
|
||||
* unknown top-level/artifact fields are rejected (`ext.manifest_invalid`);
|
||||
* artifacts need unique parseable targets and 64-lowercase-hex sha256;
|
||||
the current `HostTarget` artifact is selected (`ext.no_matching_artifact`
|
||||
when absent), resolved inside the manifest bundle (absolute/`..`/symlink
|
||||
escape/non-regular/size limit/sha mismatch → `ext.artifact_integrity`);
|
||||
* duplicate names with different manifest digests (`ext.duplicate_provider`)
|
||||
and duplicate kinds across providers (`ext.duplicate_provider_kind`) are
|
||||
deterministic because paths are canonicalised, sorted and de-duplicated
|
||||
before conflict detection.
|
||||
|
||||
`VerifiedProvider` is the static `{name, kinds, manifest_path, base_dir,
|
||||
manifest_digest, transport, selected_artifact_path/relative/sha256/target,
|
||||
version}` record. It is still declaration/verification only: no `dlopen`, no
|
||||
spawn, no grant.
|
||||
|
||||
### 3. Activation reuses the existing host API
|
||||
|
||||
`load_resource_provider_into_host(host, verified, allow_provider)` repeats the
|
||||
exact grant check, re-verifies the manifest digest and the artifact
|
||||
(regular file, containment, size, sha256) immediately before use, resolves the
|
||||
helper, and calls **the existing**
|
||||
`StdHost::register_worker_resource_provider(name, kinds, helper, [artifact])`.
|
||||
It never falls back to `register_c_resource_provider`,
|
||||
`register_provider_package`, in-process native loading or another provider.
|
||||
`resource.open` still re-checks the provider name grant in the Host. Provider
|
||||
registration keeps using `register_provider_checked` for name/kind/duplicate
|
||||
validation, so no second provider registry is introduced.
|
||||
|
||||
### 4. Helper resolution and platform claim
|
||||
|
||||
The helper is resolved only as a sibling of the running `marqdo` executable:
|
||||
`<exe dir>/marqdo-provider-worker[.exe]`. `PATH`, the current directory,
|
||||
environment overrides and downloads are not consulted. Missing/non-regular
|
||||
helper, spawn failure or failed `ping` → `ext.worker_unavailable` (exit 1).
|
||||
|
||||
The `worker` transport is claimed only on **linux/x86_64**; every other target
|
||||
returns `ext.platform_unsupported` (exit 1) instead of pretending success.
|
||||
Release artifacts must ship the helper next to the CLI for the same target
|
||||
triple. macOS/Windows stay buildable and explicitly unsupported until they have
|
||||
a native fixture and release evidence (RFC-EXT-0001 §5.6).
|
||||
|
||||
### 5. No new host op or language surface
|
||||
|
||||
There is no new `HostOp`, builtin, `resource_request` string branch, `Value`
|
||||
variant or Markdown syntax. A provider kind is still an argument to
|
||||
`resource.open("<kind>", descriptor, rights)`; the only change is the CLI
|
||||
composition root that selects, verifies and authorizes the existing host
|
||||
transport. Provider tokens stay inside the helper; the language sees only the
|
||||
opaque Host `Resource` handle. Worker errors are structured `RuntimeError`s
|
||||
surfaced as CLI errors — the CLI never panics on a helper crash/timeout.
|
||||
|
||||
### 6. Tests
|
||||
|
||||
`crates/cli/tests/provider_cli.rs` drives the real CLI binary with a real C
|
||||
`c-abi-1` sensor library and the real `marqdo-provider-worker` helper built by
|
||||
cargo and installed next to the CLI (the same layout a release tarball uses;
|
||||
production resolution is not weakened for tests). Coverage: PROV-01/02/03/04/
|
||||
05/06/07/08/09/10/13, plus `check` refusing the flag. Marker files written by
|
||||
the C library's ABI-version hook prove whether a worker actually started, so
|
||||
"no worker on unauthorized/invalid input" is evidence, not an assertion about
|
||||
code paths.
|
||||
|
||||
## Consequences
|
||||
|
||||
* A third party can add a new resource kind to a frozen `marqdo` binary through
|
||||
`provider.json` v2 + `--provider` + `--allow-provider`, without a core
|
||||
rebuild, new builtin or new CLI command.
|
||||
* v1 `marqdo.provider` remains a host-embedding format; CLI users get a clear
|
||||
`ext.unsupported_provider_schema` instead of a silently unverified load.
|
||||
* Integrity hashing raises the cost of accidental corruption/tampering but is
|
||||
not a trust root; a compromised or malicious helper still runs with the
|
||||
user's privileges. Documentation states this explicitly.
|
||||
* `pure`/`strict` semantics and the existing resource/provider host contracts
|
||||
are unchanged (strict still L1-only and fail-closed).
|
||||
* The provider helper becomes a release artifact that must be packaged next to
|
||||
the CLI; a missing helper is a first-class, deterministic error.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
1. **Reuse `plugin.yaml`/plugin ABI directly for providers.** Rejected: a
|
||||
resource provider's contract is open/read/write/close with provider-private
|
||||
tokens and stream kinds, not callable exports; sharing the manifest/ABI
|
||||
parser would conflate two independent protocols (RFC-EXT-0001 §1.3).
|
||||
2. **Extend v1 in place with optional `version`/`artifacts`.** Rejected:
|
||||
v1 is host-embedding installation metadata and is already accepted by
|
||||
`register_provider_package`; silently changing its meaning or accepting a
|
||||
half-populated v1 would break the frozen ADR-0037 contract. v2 is explicit.
|
||||
3. **Allow in-process C ABI loading when the worker helper is missing.**
|
||||
Rejected: it would silently lower the process boundary and RFC-EXT-0001
|
||||
§5.2/§5.4 forbids falling back to Native. `ext.worker_unavailable` is the
|
||||
correct fail-closed result.
|
||||
4. **PATH lookup for `marqdo-provider-worker`.** Rejected: `PATH` is
|
||||
attacker-controlled state and would make the executed artifact
|
||||
non-deterministic; the sibling rule binds the helper to the release.
|
||||
5. **Register providers lazily at the first `resource.open`.** Rejected for
|
||||
this slice: authorization and integrity must be decided before the main
|
||||
function executes, and the existing host API is synchronous spawn-on-register.
|
||||
6. **Accept a `*` provider grant for developer convenience.** Rejected: grants
|
||||
are exact names (RFC-EXT-0001 §5.2); wildcards would let a typo authorize an
|
||||
arbitrary selected provider.
|
||||
|
||||
## Deviations recorded
|
||||
|
||||
* `ext.manifest_invalid`, `ext.duplicate_provider` and
|
||||
`ext.provider_grant_unmatched` are **additive** `ext.*` codes beyond the list
|
||||
frozen in RFC-EXT-0001 §18.1. The frozen list has no generic malformed-v2
|
||||
code, no duplicate-provider-name code and no unmatched-grant code; reusing
|
||||
`ext.unsupported_provider_schema`/`ext.duplicate_provider_kind` for these
|
||||
would report the wrong reason. They follow the same `ext.` naming and exit
|
||||
code contract and are frozen by this ADR.
|
||||
* `ext.artifact_integrity` failures exit 1 (load/verify), while static
|
||||
manifest-selection failures exit 2, matching RFC-EXT-0001's exit-code
|
||||
guidance; plugin artifact checking already uses the same split.
|
||||
* Only linux/x86_64 is claimed for the provider `worker` transport in this
|
||||
release (RFC-EXT-0001 §5.6 permits this explicit platform limit; Windows and
|
||||
macOS return `ext.platform_unsupported`).
|
||||
|
||||
## Verification
|
||||
|
||||
`crates/cli/tests/provider_cli.rs` (12 real tests, linux/x86_64) plus
|
||||
`crates/cli/src/provider_manifest.rs` unit tests pass; `spec/security.md`,
|
||||
`spec/resource-provider-v2.md` and the README provider section document the
|
||||
same contract. Evidence is recorded in the PR-03 task report (commands, exit
|
||||
codes, per-PROV matrix).
|
||||
@@ -0,0 +1,229 @@
|
||||
# ADR-0057: Trusted capability-handler registration
|
||||
|
||||
Status: **Accepted**
|
||||
Date: 2026-11-21
|
||||
Implements: RFC-EXT-0001 §7 (PR-05)
|
||||
Extends: ADR-0011 (capability broker)
|
||||
Scope: `crates/marqdo-host/src/capability.rs` (host-internal registry)
|
||||
|
||||
## Context
|
||||
|
||||
ADR-0011 introduced `CapabilityBroker` with two separate ideas but only one
|
||||
implementation path:
|
||||
|
||||
* `decide()` answered "is this capability granted?" from `Capabilities` and a
|
||||
trusted vendor-policy allow-list; and
|
||||
* `execute()` special-cased the single real core implementation (`fs.read`)
|
||||
inline, returning `capability.unavailable` for everything else.
|
||||
|
||||
That shape is why adding a capability looked like a one-line allow-list edit,
|
||||
and it made "declared in policy" and "can actually execute" the same object.
|
||||
RFC-EXT-0001 §7.1/§7.2 requires the chain:
|
||||
|
||||
```text
|
||||
manifest requests capability
|
||||
-> operator/CLI grants it
|
||||
-> broker asks: is a trusted handler installed?
|
||||
-> handler re-checks owner/grant/scope/budget
|
||||
-> handler executes
|
||||
-> audit { identity, effect, decision, duration, trace_id }
|
||||
```
|
||||
|
||||
A name in an allow-list must never be enough to execute, and a capability with
|
||||
no executor must never look like an empty success.
|
||||
|
||||
## Decision
|
||||
|
||||
### 1. Two independent registries
|
||||
|
||||
`CapabilityBroker` keeps:
|
||||
|
||||
* `vendor_policy: BTreeSet<String>` — names the trusted host *policy* accepts
|
||||
(from `allow_vendor`); and
|
||||
* `handlers: BTreeMap<String, HandlerEntry>` — names that have an explicitly
|
||||
registered trusted executor.
|
||||
|
||||
`HandlerEntry` additionally carries an optional exact trusted package binding
|
||||
(`None` = authorized by the capability grant alone).
|
||||
|
||||
The two sets cannot substitute for each other:
|
||||
|
||||
* vendor capability without a policy entry -> `permission.denied`
|
||||
(declaration is not a grant; CAP-01);
|
||||
* vendor policy entry without a handler -> `capability.unavailable` (CAP-02);
|
||||
* core capability granted by `Capabilities` but without a handler ->
|
||||
`capability.unavailable` (CAP-12).
|
||||
|
||||
### 2. Handler interface
|
||||
|
||||
```rust
|
||||
pub struct CapabilityRequest<'a> {
|
||||
pub package_instance: &'a str, // trusted identity from the host, not wire data
|
||||
pub capability: &'a str,
|
||||
pub payload: &'a [u8],
|
||||
pub trace_id: &'a str,
|
||||
}
|
||||
|
||||
pub trait CapabilityHandler: Send {
|
||||
fn name(&self) -> &str;
|
||||
fn execute(
|
||||
&mut self,
|
||||
request: &CapabilityRequest<'_>,
|
||||
capabilities: &Capabilities,
|
||||
budget: &mut Budget,
|
||||
) -> Result<Vec<u8>, PluginError>;
|
||||
}
|
||||
```
|
||||
|
||||
The registry key is `handler.name()`, so the handler's declared capability can
|
||||
never disagree with the name it is registered under (the RFC's "declared
|
||||
protocol mismatch" rejection cannot occur by construction).
|
||||
|
||||
Registration is host-only; there is no wire path from a plugin manifest to this
|
||||
API. `register_handler` installs a handler usable by any package holding a
|
||||
grant; `register_package_handler(package, handler)` binds it to one exact
|
||||
trusted package identity and denies every other claimed package (CAP-03, the
|
||||
"trust the package the host loaded, not a self-reported name" rule of §7.4).
|
||||
|
||||
### 3. Registration validation
|
||||
|
||||
`register_handler` / `register_package_handler` reject:
|
||||
|
||||
| condition | stable code |
|
||||
|---|---|
|
||||
| empty name, surrounding whitespace, or not a core/vendor name | `capability.handler_invalid` |
|
||||
| name under a reserved host prefix (`marqdo.`, `host.`) | `capability.handler_reserved` |
|
||||
| name already registered (including the built-in `fs.read`) | `capability.handler_conflict` |
|
||||
|
||||
A rejected handler is never installed. The component that constructs the
|
||||
broker is the trust boundary: only trusted host/embedder code can register, so
|
||||
"untrusted source" is rejected by the absence of an API rather than a flag.
|
||||
|
||||
### 4. Fixed execution chain and audit
|
||||
|
||||
`execute()` is one function with one order:
|
||||
|
||||
1. `decide()` — `Capabilities`, vendor policy, request payload shape;
|
||||
2. handler installed? — otherwise audit `unavailable`, return
|
||||
`capability.unavailable`;
|
||||
3. package-bound handler owns the claimed package? — otherwise audit `denied`,
|
||||
return `permission.denied`;
|
||||
4. handler executes under the broker `Budget` and the broker reply limit;
|
||||
5. audit one entry with `package`, `capability`, `decision`
|
||||
(`granted`/`denied`/`unavailable`), reason and `duration_micros`.
|
||||
|
||||
`authorize()` remains the grant decision only (`granted`/`denied`); it never
|
||||
executes and therefore cannot demonstrate an executor. This keeps the
|
||||
authorization and execution questions separate and auditable.
|
||||
|
||||
The reply is bounded by `reply_limit` (default
|
||||
`MAX_CAPABILITY_REPLY_BYTES`) and oversize replies are `resource.exhausted`
|
||||
(CAP-06). Handlers also receive `&mut Budget`, so an embedder can wire the
|
||||
per-run budget and handlers can charge fuel/output (tested). Response payloads
|
||||
are never written to the audit log, so file contents and request secrets stay
|
||||
out of it (CAP-09).
|
||||
|
||||
### 5. `fs.read` becomes the first standard handler
|
||||
|
||||
The former inline `fs.read` match arm moved into `FsReadHandler`, installed by
|
||||
`CapabilityBroker::with_fs(fs)`. It:
|
||||
|
||||
* resolves the path with `ProjectFs::resolve` (absolute paths, `..`, empty
|
||||
paths rejected) **before** I/O;
|
||||
* re-checks `Capabilities::check_read` against the normalized
|
||||
project-relative path at the execution point, so the grant is enforced on the
|
||||
same path the filesystem uses;
|
||||
* reads through `ProjectFs` (regular file, UTF-8, project root, 8 MiB limit).
|
||||
|
||||
`with_fs` still installs exactly one handler; `capability_broker.rs` and
|
||||
`host.rs` call sites are unchanged. Every other core capability and every
|
||||
vendor capability without a registered handler keeps returning
|
||||
`capability.unavailable`; nothing returns an empty `Ok` as a stand-in for
|
||||
"implemented".
|
||||
|
||||
## RFC deviations (explicit)
|
||||
|
||||
1. **`EffectiveGrant` -> `Capabilities`; `ResourceBudget` -> `Budget`.** The
|
||||
RFC (§7.2) says these are design-interface names and the implementation must
|
||||
reuse the existing grant and limit structures instead of building a second
|
||||
permission system; that is exactly what happened.
|
||||
2. **`CapabilityError` -> `PluginError`.** The capability bridge across the
|
||||
plugin/worker ABI already uses `marqdo_plugin_abi::PluginError`; reusing it
|
||||
avoids a second error taxonomy. Codes remain the stable contract.
|
||||
3. **`trace_id` is plumbed through `CapabilityRequest` and settable with
|
||||
`with_trace_id`, but the host wiring is a follow-up.** `host.rs` does not set
|
||||
it yet, so audit entries from the current CLI plugin path have an empty
|
||||
trace id. Wiring it requires the run/session id from `ExecutionContext`,
|
||||
which is outside this PR's write scope.
|
||||
4. **`resource.exhausted` preserves the broker code but not the runtime
|
||||
category.** `PluginError` kind `Capability` maps to
|
||||
`RuntimeError` category `PermissionDenied` in `host.rs::map_plugin_error`.
|
||||
The stable code is `resource.exhausted` (what CAP-06 asserts at the broker
|
||||
boundary); teaching the host mapping about a resource-limit plugin code is a
|
||||
follow-up because `host.rs` is outside this PR's scope.
|
||||
5. **`CapabilityBroker` is no longer `Clone`** because it owns `Box<dyn
|
||||
CapabilityHandler>`. No in-tree caller cloned it; a future embedder that
|
||||
needs a clone should share the broker behind the same lock instead, which is
|
||||
also what the one-call-at-a-time ABI requires.
|
||||
|
||||
## Alternatives
|
||||
|
||||
1. Keep the closed match arm and add capabilities to it. Rejected: every
|
||||
vendor operation would need a core release and the broker would still have
|
||||
no separation between "granted" and "executable".
|
||||
2. Treat a vendor policy entry as proof of an executor. Rejected: that is the
|
||||
exact "declaration becomes privilege" failure the RFC forbids; CAP-02 locks
|
||||
it out.
|
||||
3. Register handlers by `(name, package)` strings only and trust the caller's
|
||||
package argument. Rejected: a wire-supplied package name must not authorize
|
||||
anything; package-bound registration pins the identity the host selected at
|
||||
load time.
|
||||
4. Give every core capability an empty handler so `execute()` always returns
|
||||
`Ok`. Rejected: it converts "not implemented" into a silent success, the
|
||||
failure mode RFC §7.1 calls out.
|
||||
|
||||
## Compatibility
|
||||
|
||||
* Existing `Capabilities`, `with_fs`, `with_audit`, `allow_vendor`,
|
||||
`authorize`, `execute` and `capability_audit()` call sites are unchanged;
|
||||
`host.rs` needed no edit.
|
||||
* One observable change: a vendor capability without a trusted policy entry is
|
||||
now `permission.denied` instead of `capability.unavailable`. This matches
|
||||
ADR-0011 ("a missing grant is `permission.denied`") and RFC CAP-01.
|
||||
* `CapabilityAudit` gained `duration_micros`; all fields remain public and the
|
||||
existing tests that read `package`/`capability`/`decision` compile unchanged.
|
||||
* `CapabilityBroker` lost `Clone` (see deviation 5).
|
||||
* No ABI, wire, manifest or CLI change.
|
||||
|
||||
## Security
|
||||
|
||||
* Registration is a trusted-host operation with no manifest/wire entry point;
|
||||
a plugin cannot install, replace or enumerate handlers.
|
||||
* Package-bound handlers reject cross-package impersonation even when policy
|
||||
and grant match.
|
||||
* `fs.read` keeps `ProjectFs` root confinement, glob scope and size limits; the
|
||||
grant is re-checked on the normalized path at the execution point.
|
||||
* Audit records decisions and durations but never payload contents.
|
||||
* This remains a cooperative in-process API contract, not an OS sandbox: a
|
||||
native plugin can still issue direct syscalls. The registry narrows what the
|
||||
host will *do on request*; it does not confine plugin memory or syscalls.
|
||||
|
||||
## Testing
|
||||
|
||||
`crates/marqdo-host/tests/capability_handlers.rs` covers CAP-01..CAP-12:
|
||||
policy-vs-handler separation, package binding, registration rejection, real
|
||||
`fs.read` scope enforcement, reply budget and handler budget charging, forged
|
||||
and replayed handles, audit hygiene, resource-stream regression smoke, project
|
||||
mode not being OS-strict, and "no handler is never a silent success".
|
||||
Unit tests in `capability.rs` keep the `CORE_CAPABILITIES` list in sync with
|
||||
`decide()` and assert that the built-in `fs.read` handler is installed by
|
||||
`with_fs`.
|
||||
|
||||
## Migration & rollout
|
||||
|
||||
`with_fs` installs the migrated `fs.read` handler automatically, so existing
|
||||
plugin loads keep working. Future core capabilities migrate by adding a handler
|
||||
and registering it in the trusted composition root; until then they remain
|
||||
`capability.unavailable`. Vendor operations that need a non-streaming API
|
||||
should first use the existing `resource.open/read/write/close` stream path
|
||||
(RFC-EXT-0001 §7.3) instead of registering a new host handler.
|
||||
@@ -0,0 +1,105 @@
|
||||
# ADR-0058: Official stdlib public aliases replace print magic
|
||||
|
||||
- Status: Accepted (2026-11-21)
|
||||
- Implements: RFC-EXT-0001 §8 (PR-06)
|
||||
- Related: ADR-0028/0030/0031/0039, ADR-0054
|
||||
|
||||
## Context
|
||||
|
||||
`打印`/`print` were implemented twice:
|
||||
|
||||
1. `crates/cli/src/loader.rs::program_uses_print` walked the entire AST, and if
|
||||
any function called `打印`/`print` it injected the bundled
|
||||
`stdlib/io.mq.md` module and set `Program.print_override` to its `写值`
|
||||
function;
|
||||
2. `crates/marqdo-runtime/src/interpreter.rs` contained a `打印`/`print`
|
||||
special case that redirected to the override, while the builtin table also
|
||||
contained a placeholder `打印` entry.
|
||||
|
||||
Copying this pattern to the next official high-level function (formatting,
|
||||
console input, …) would add one AST scanner and one runtime branch per name.
|
||||
The RFC forbids that ("为标准库每个高级函数复制 print_override 模式"), while
|
||||
also requiring byte-identical output and no new Host op.
|
||||
|
||||
## Decision
|
||||
|
||||
1. **Verified metadata.** The bundled `stdlib/stdlib.json` declares
|
||||
|
||||
```json
|
||||
"public_aliases": [
|
||||
{
|
||||
"public_names": ["print", "打印"],
|
||||
"target_module": "io.mq.md",
|
||||
"target_function": "写值",
|
||||
"expected_signature": "params(值)",
|
||||
"effects": ["host"]
|
||||
}
|
||||
],
|
||||
"aliases_digest": "sha256:<64 lowercase hex>"
|
||||
```
|
||||
|
||||
`aliases_digest` is the SHA-256 of the canonical binary encoding: for each
|
||||
alias sorted by `(target_module, target_function)`, the module bytes, NUL,
|
||||
the function bytes, NUL, then every public name in sorted order followed by
|
||||
NUL. The same encoding is implemented by `tools/pack-stdlib.py` and
|
||||
`crates/cli/src/stdlib.rs::aliases_digest`; `stdlib.json` cannot be edited
|
||||
without updating the digest, and the loader verifies both digests before any
|
||||
module loads. Metadata is integrity-checked, not signed: a SHA-256 proves
|
||||
content equality, not publisher identity.
|
||||
2. **Lazy, generic loading.** The loader reads the metadata, decides whether the
|
||||
program references any public alias name (a generic identifier scan, not a
|
||||
per-function hard code), and only then loads the declared target module.
|
||||
The target signature is checked against `expected_signature`; a mismatch is
|
||||
a load error. A program without `打印`/`print` keeps its previous module
|
||||
graph and startup cost.
|
||||
3. **Ordinary Marqdo binding.** For each used alias the loader produces an
|
||||
`OfficialAlias { public_names, function, signature, owner_package,
|
||||
effects_requested }`; `project_prepare` registers it in the
|
||||
`CallableRegistry`. The binding pass targets
|
||||
`Marqdo { function: <stdlib instance>::io.mq.md::写值 }`. The runtime calls
|
||||
an ordinary Markdown function; it has no print branch.
|
||||
4. **Reserved names stay reserved.** Official aliases may replace the builtin
|
||||
placeholder for the same public name. Third-party registry insertion rejects
|
||||
builtin *and* official-alias names (`ext.duplicate_callable`), so no plugin
|
||||
or imported module can claim `打印`/`print`, `std.*` or `marqdo.*`.
|
||||
`plugin.yaml` still rejects reserved export prefixes at manifest validation.
|
||||
5. **No Host print operation.** Output continues to flow through
|
||||
`io.写值` → `format.显示` → UTF-8 bytes → `Memory` →
|
||||
`resource.write(stdout)`. There is no `HostOp::Print` and no second
|
||||
formatter. Unbundled embedders that call the placeholder builtin receive
|
||||
`kernel.unavailable`.
|
||||
6. **Removed code.** `program_uses_print`, `stmts_use_print`,
|
||||
`expr_uses_print`, `Program.print_override`, the runtime redirect branch and
|
||||
the whole-AST print scanner are deleted. A structural test
|
||||
(`architecture_boundaries.rs::callable_binding_is_the_only_static_resolution_path`)
|
||||
fails if they reappear.
|
||||
|
||||
## Consequences
|
||||
|
||||
* `打印` and `print` are now ordinary calls in Analysis/Trace: the call target
|
||||
is the stdlib function, `state` is `function`, and no synthetic `builtin`
|
||||
target is reported for the alias.
|
||||
* Output must stay byte-identical. `crates/cli/tests/stdlib_alias_routing.rs`
|
||||
plus the existing print/format/Trace goldens pin this; a diff is a blocking
|
||||
regression, not an acceptable "new design".
|
||||
* A tampered alias table (metadata digest or expected signature) is rejected
|
||||
before module loading; `stdlib.json` and the `.mq.md` tree remain separately
|
||||
digest-pinned, and `tools/pack-stdlib.py` refuses to build an inconsistent
|
||||
bundle.
|
||||
* The generic metadata path is the only place a future official high-level name
|
||||
needs to be declared locally. Any *new language syntax* still requires a
|
||||
language RFC; aliases cannot change `@exec`/`@knowledge` semantics.
|
||||
|
||||
## Rejected alternatives
|
||||
|
||||
* **Keep `print_override` and add a second alias for another function.**
|
||||
Rejected: it multiplies hard-coded scans/branches and violates RFC-EXT-0001
|
||||
§8 and §14.10.
|
||||
* **Move the print formatter into the Host as a `Print` op.** Rejected: it
|
||||
would reintroduce an un-audited output path and duplicate the stdlib
|
||||
formatter; output is a resource write.
|
||||
* **Let third-party packages register `print`/`打印` aliases.** Rejected:
|
||||
official public names are a language surface, not an extension registry.
|
||||
* **Put the alias table in Rust `match` arms instead of metadata.** Rejected:
|
||||
the table must be versioned with the verified bundle so a stale/mixed bundle
|
||||
cannot run a different function.
|
||||
Reference in new issue
Block a user