feat(exec-runner): runner-declared env, Go knobs, and examples

[raphaelvigee]

On top of #414. Two commits, reviewable separately: a runner can now declare its own environment, and the Go plugin gets the two knobs that make runners usable there.

1. A runner declares env / pass_env / runtime_env / runtime_pass_env

The same four keys a target has. The split between them is where the cache key is drawn:

key	resolved	in the key
env	at capture, literal	yes
pass_env	at capture, from the host	yes — the value is baked in
runtime_env	at spawn, literal	the declaration only
runtime_pass_env	at spawn, from the host	the name only

The last row is the one that matters. SSH_AUTH_SOCK and DOCKER_HOST differ per machine and per login; passing them with pass_env bakes one machine's value into the environment's identity and hands every other machine a cache key that lies about what produced the artifact. runtime_pass_env reads them at spawn, so they reach the process and never the key. "*" is the same escape hatch a target has.

The declarations themselves are hashed either way — they live in the runner target's artifact, and that artifact is the environment's identity. heph will not claim two differently-declared environments are the same one, and will not put ambient host state in the key either.

Everything a runner declares sits underneath what the target set itself, wildcard included — a runner that could overwrite $OUT, $SRC or a target's own env would silently change what the target builds. Asserted directly.

SessionEnv lives in the contract, so every runner gets it; devenv populates it from four new spec keys. SNAPSHOT_FORMAT_VERSION → 3.

2. Go: goenv, and a runner for test execution

Two knobs, deliberately separate, because how it was built and how it runs are different questions.

goenv (provider option) — environment for the Go toolchain: go list, the compiler, the assembler. GOPRIVATE, GOFLAGS, a corporate GOPROXY.

Injected into each target's spec where it is hashed, not applied behind the drivers' backs. A knob that changed compiler input without moving the key would hand every machine artifacts built under settings the key does not record. GO_COMPILE_FORMAT_VERSION → 5, GO_GOLIST_FORMAT_VERSION → 18; both frozen def-hash goldens failed on the bump, which is what they are for.

One choke point (the provider's get) rather than the two dozen places a spec is built — a knob that reached most of them would be worse than one that reached none, because the gap surfaces as a cache hit on an archive built under different settings.

An allowlist decides who gets it: go_compile, go_golist. go_toolchain downloads an SDK and go_testmain writes a file — giving them an environment they never use would key them on it for nothing and re-key everything downstream. Lint/format exec heph-govet, not go.

Within a driver goenv is applied first, so GOROOT/GOOS/GOARCH/GOWORK=off win — those make the build hermetic and match the variant, and letting config override them would build something other than the address asked for, under that address's key.

provider_state(provider="go", test={"runner": "//:devenv"}) — the exec environment the test binary runs in. Joins the existing test = {...} map beside env/pass_env/pre_run, same allowlist that rejects typos, rather than inventing a second place to configure tests.

Only test/xtest take it. A test binary often wants a database client or a browser on PATH; the build wants the hermetic toolchain and nothing else. One environment for both would either leak the runtime's tools into every compile's key or force the build environment onto the test.

Examples

example/exec_runner/BUILD exercises what this stack added: selection and runner = None; a tool that resolves only under the runner and the same target failing without it; the four declared keys; a target overriding its runner; session mode providing a shell function snapshot mode cannot — with the snapshot counterpart kept as an expected failure, so the difference is visible rather than described.

Also fixes the example workspace, which has not loaded since #397 removed the sh driver: .hephconfig2 still listed builtin: sh, so every heph command run there failed at config load.

Where a runner comes from, per target type

Target type	How a runner is set
BUILD-authored (bash, exec, http_fetch, nix, …)	runner = //pkg:name, or runner = None
The runner target itself	n/a — excluded from defaultRunner so it cannot become its own dependency
Go test / xtest (+_race)	provider_state(test={"runner": …})
Go go_compile / go_golist	inherits defaultRunner; environment shaped by goenv
Go go_toolchain / go_testmain / lint / format	inherits defaultRunner; no goenv
Other provider-emitted (@heph/fs, group, hostbin, oci_*)	inherits defaultRunner

runner: None on a TargetSpec means unauthored, not local — which is why provider-emitted targets inherit defaultRunner. That reaches go_compile, and plugin-go is cdylib-only, so that path works only because of #411's positive ack.

Known gap: go_lint/go_format inherit defaultRunner but get no goenv, since they exec heph-govet rather than go. If heph-govet needs a corporate GOPROXY, that wants its own knob.

Tests

26 in exec-runner (the four-key layering, "*", and the target-wins-over-everything case), 10 in plugin-devenv, 481 in plugin-go, plus e2e. lint clean.

_{Stack created with GitHub Stacks CLI • Give Feedback 💬}