feat(deferred): ${src://…} — the sandbox path of an artifact

[raphaelvigee]

Implements ${src://pkg:name} — the sandbox path of a producer's artifact, where ${read://pkg:name} (#456) is its contents. Stacked on #456.

target(name = "parser", driver = "bash", deps = [file("grammar.y")],
       out = "parser.c", run = "bison -o $OUT $SRC")

target(name = "app", driver = "exec",
       run = ["cc", "-o", "$OUT", "${src://gen:parser.c}"])

This is $SRC_<GROUP> finally available in an exec argv — where there is no shell to expand it in — and without a deps entry to keep in sync with the reference that uses it. Both kinds may name an output group (${src://tools:cli|bin}) through TargetAddr::parse, the same function deps goes through, so a reference and a dep agree about what an address is.

A third cell

(hashed, staged) is the deps cell, and an edge there is also merged by collect_transitive_deps: the producer's transitive tools, deps and env follow into the consumer, and apply_transitive folds those env values into the consumer's def hash by reading std::env::var. So ${src://tools:go} on a producer declaring transitive = {"env": {"GOFLAGS": pass}} would move the consumer's cache key with the host's GOFLAGS — for a target that only wanted a filename.

ref	hashed	staged	transitives
${read://x:y}	yes	no	no
${src://x:y}	yes	yes	no ← new
deps	yes	yes	yes

Writing a path expression asks for a path, so the edge carries an annotation collect_transitive_deps skips. Take the artifact as an ordinary deps entry when you do want the environment. This was put to the user as a design decision rather than settled in the implementation.

Substituted host-side, and why that mattered

The path is the one value the host cannot compute in execute: it exists only once the artifact is staged, and under FUSE sandbox_dir is redirected after the host has set it. So invoke_inner completes it — still host-side, before anything crosses the plugin ABI.

That placement is load-bearing. crates/driver-support is statically linked into every plugin cdylib, so putting the substitution inside a ManagedDriver implementation would version it with each plugin: an older cdylib would advertise accepts_deferred: true (it has a Deferred field for read) and then run the command with ${src://x:y} as a literal argv element. That is the silent-literal class this whole mechanism exists to remove, reintroduced one crate down.

The completion is one pass over the author's text: the host hands the field over whole, together with the read values it also names, rather than half-substituting and re-scanning later. A second pass would read a producer's own bytes as references — what hcore::template is single-pass to prevent.

No ABI change. deferred_pending is a Rust-only field on RunRequest, consumed before serialisation; ABI_SEMVER stays where #456 left it, and abi-check.sh reports no surface change.

A dedup bug this exposed

inputs_for_labelled keyed on the producer's address alone. collect sorts refs by their whole field text, so "${read://a:b}" sorted before "${src://a:b}" — the read edge won, the artifact was never staged, and ${src://a:b} resolved to a path that did not exist. Which of the two survived depended on the surrounding literal characters. The key is now (address, staged), and the test asserts both sort orders.

Refusals

• A producer emitting several files has no single path: the error lists them, checked against the staged file list so the message is what is actually there, and points at |<group>.
• A producer emitting nothing: there is no path to substitute.
• ${src:} in a credential declaration is refused at parse — a credential is a document the host reads, not a target that runs, so there is no sandbox for a path to point into.

Nothing is reserved any more: RESERVED_LATER and its second per-get_def config walk are gone.

Review board

The design for this went to product-vision, hermeticity, compatibility and feature-quality before any code. ${src:} came back HERMETIC WITH EXEMPTIONS, and both exemptions were put to the user rather than settled here — the absolute-vs-relative path form (absolute, matching $SRC_<GROUP>; an e2e test asserts the two produce byte-identical strings) and the transitive-merge question above. The host-side substitution point and the (address, staged) dedup key are direct board findings.

The same review blocked ${env:NAME} on three counts, and it is not in this PR — see #456, which documents the pass_env + ${read:} composition that replaces it with better provenance.

Tests

Six new e2e tests: the path resolves to a file that is really there; ${src:} and $SRC_<GROUP> agree byte for byte; the producer's transitive env does not follow; a multi-file producer names its files; |group narrows one; a credential refuses it. Plus unit tests for the two cells, the dedup in both sort orders, group parsing, and that no bash brace form is collected. example/deferred/version-bytes is a worked exec consumer.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01Jr413rT5LPhzVYo6QFckDm

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