Files
marqdo-cli/docs/evidence/2026-11-20-worker-provider.md
cflmy 01f6fe46a7 feat(host): add worker resource-provider transport v1
- Add a host-managed helper process speaking framed JSON (4-byte BE length)
  with ping/open/read/write/close/shutdown, max 1 MiB frames and structured
  error mapping (ADR-0035).
- Add StdHost::register_worker_resource_provider using the same protocol,
  kind-conflict and name-grant checks as the in-process provider; pure/strict
  refuse provider kinds.
- Tests spawn a Python helper and cover round-trip, grant/mode denial and
  missing-program failure; no parser/Value/runtime/HostOp change.
- Update ADR/spec/status/README/changelog and evidence; C ABI binding remains
  open.

Gate: fmt, clippy -D warnings, 433 tests passed.
2026-11-20 23:25:09 +08:00

2.0 KiB

RFC-CM CM-A09 evidence: worker resource-provider transport v1

Date: 2026-11-20 (Asia/Shanghai) Repository: marqdo-cli Baseline: 12be02e plus this step's changes. Decision record: ADR-0035 Related: in-process provider, STATUS §5. Scope: trusted host-managed helper process; not a sandbox and not the C ABI binding.

Transport

crates/marqdo-host/src/provider_worker.rs implements the ADR-0035 framed-JSON transport:

4-byte BE length + JSON, max 1 MiB
ping handshake
open  -> token
read  -> bytes+eof
write -> count
close
shutdown on drop

StdHost::register_worker_resource_provider(name, kinds, program, args) spawns the helper and registers it through the same validation/grant path as ADR-0033. The helper token never enters a language Value; the host still issues the opaque ResourceHandle.

Tests

crates/marqdo-host/tests/worker_provider.rs (3 tests):

worker_provider_round_trips_through_framed_json
  Python helper: ping/open/read 5 "hello"/read rest " world" eof/write 3/close;
  second close resource.closed.

worker_provider_registration_requires_a_grant_and_project_mode
  no name grant -> permission.denied; pure/strict -> permission.denied.

missing_worker_program_is_a_structured_error
  non-existent helper -> kernel.unavailable (no fallback).

No runtime, HostOp, Value or parser change was needed; language code still uses resource.*.

Security boundary

The helper runs as the host user with host privileges. Registration is an embedding API, project-mode only, and requires a provider-name grant. It is trusted infrastructure, not an OS sandbox; the untrusted-plugin path remains the separate plugin Worker transport.

Not done

  • C ABI / plugin-Worker binding for ResourceProvider.
  • Provider package installation/signatures/discovery.
  • Untrusted-provider isolation; strict-mode provider support.
  • External DNS/TLS/network endpoint work beyond the IP-literal TCP slice.