Files
marqdo-cli/docs/adr/0020-foreign-environment-binding.md
T
cflmy faa6c95cfe fix(foreign): bind pinned environments to the executed provider
A verified environment_dir was only prepended to PATH, so built-in providers
still ran the host interpreter and external entrypoints could live outside the
verified tree.

- external entrypoints must resolve inside environment_dir
- built-in providers cannot be bound to an environment (fail closed)
- bound children get exactly the environment bin on PATH, no host fallback
- declared interpreter_version is verified against the resolved program
- built-in descriptors now also run environment validation
- ADR-0020 + spec/foreign.md document the binding and limitations
- positive/negative tests for binding, outside-entrypoint, builtin binding and
  version drift
2026-11-20 13:56:08 +08:00

2.9 KiB

ADR-0020: A pinned Foreign environment binds the executed provider

Status: Accepted Date: 2026-11-20 Relates to: ADR-0012, spec/foreign.md §2/§6, stable-release spec §8.3

Context

KernelDescriptor can declare environment_id, environment_digest, environment_dir and interpreter_version. Before this ADR the host verified the environment tree digest and then prepended <env>/bin to PATH, but the executed program was still resolved from the host PATH for built-in providers, and external entrypoints could live outside the verified environment. A manifest could therefore pass integrity verification while a different interpreter (or a host interpreter whose dependencies were not part of the pinned tree) actually ran.

Decision

  1. environment_dir is an execution binding:
    • an external provider's absolute entrypoint must resolve inside the canonicalized environment; otherwise registration/execution fails with ForeignError::Protocol;
    • one of the built-in providers cannot be combined with environment_dir; a pinned interpreter is registered as an explicit external provider whose entrypoint is the interpreter itself.
  2. A bound child receives MARQDO_FOREIGN_ENV and exactly the environment's executable directory on PATH. The host PATH is not appended. On Windows SYSTEMROOT/WINDIR are inherited for process creation, not for package resolution.
  3. interpreter_version, when declared, is checked against the resolved program's --version output before the program source is executed. A mismatch fails closed.
  4. The profile-v1 environment digest keeps rejecting symlinks and special files. A virtualenv whose interpreter is a symlink is not pin-able in this release; this limitation is documented rather than silently resolved.
  5. This does not make the child an OS sandbox. Host authorization and spec/security.md still govern capabilities; strict mode remains refused until its own ADR and security lane pass.

Consequences

  • A verified environment can no longer be decorative: either the program comes from it, or the descriptor is rejected.
  • Existing external descriptors that declared environment_dir while pointing at a host binary must be corrected; this is an intentional fail-closed behavior change, documented in the changelog.
  • uv/npm environment creation remains out of scope; an external provisioner may produce a directory that satisfies this contract.
  • Built-in Python/Node without an environment keep their PATH lookup and install hint.

Tests

crates/marqdo-foreign/tests/provider.rs:

  • pinned_environment_binds_the_provider_and_is_verified_before_execution
  • provider_outside_pinned_environment_is_rejected
  • builtin_provider_cannot_be_bound_to_an_environment
  • declared_interpreter_version_must_match_the_resolved_program
  • existing digest/tamper/timeout/registration tests remain green.