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

62 lines
2.9 KiB
Markdown

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