Files
marqdo-cli/docs/adr/0055-resource-provider-cli-v2.md
T
cflmy 1f6fd644a0 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.
2026-11-22 00:17:36 +08:00

197 lines
11 KiB
Markdown

# 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).