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
2.9 KiB
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
environment_diris an execution binding:- an external provider's absolute
entrypointmust resolve inside the canonicalized environment; otherwise registration/execution fails withForeignError::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.
- an external provider's absolute
- A bound child receives
MARQDO_FOREIGN_ENVand exactly the environment's executable directory onPATH. The hostPATHis not appended. On WindowsSYSTEMROOT/WINDIRare inherited for process creation, not for package resolution. interpreter_version, when declared, is checked against the resolved program's--versionoutput before the program source is executed. A mismatch fails closed.- 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.
- This does not make the child an OS sandbox. Host authorization and
spec/security.mdstill 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_dirwhile 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_executionprovider_outside_pinned_environment_is_rejectedbuiltin_provider_cannot_be_bound_to_an_environmentdeclared_interpreter_version_must_match_the_resolved_program- existing digest/tamper/timeout/registration tests remain green.