A family: register verified payloads with the ecosystem's own mechanism instead of copying them out

[avrabe]

Prompted by the maintainer liking criticalup's link feature (v1.5.0):
criticalup link create registers the pinned toolchain as a real rustup
toolchain, so cargo +ferrocene build works. It is interoperability instead of
replacement — plug into the ecosystem's own mechanism rather than only owning
PATH.

varve borrows the rustup pattern (shims that re-resolve the pin per working
directory, REQ-SHIM-002) but has no rustup integration.

The distinction worth naming

Everything varve offers a consumer today is an export: export-cargo,
export-vsix, export-sdk, export-bazel, export-bazel-distdir,
export-crates-vendor. All materialise a copy out of the store.

A link would register a pointer, so the other tool reads varve's
verified bytes in place. Three consequences, and they get more valuable as
payloads get bigger:

• No duplication. Copying a 2 GB SDK tree, or rustdoc for a workspace, to
  use it is a real cost (see verify and inspect are single-threaded and silent: ~9s on a 2 GB SDK layer vs <1s without one #141, where 2 GB already costs ~9s just to hash).
• The pin stays authoritative. Switch layers and a link follows; a copy does
  not. write_export_stamp exists precisely because an exported directory goes
  stale the moment the pin moves — a link has no staleness to stamp.
• One less place for the bytes to be wrong. A copy can be edited after
  export and still look exported.

Candidates, most valuable first

1. varve link rustup — the direct analogue, and the one that buys the
most: every IDE, rust-analyzer, and CI that already speaks rustup would then
consume varve-verified bytes with no varve-specific support.

Honest caveat: there is nothing to link today. The pulseengine realm carries
pulseengine tools (rivet, synth, meld, kilnd, loom, wsc, spar…), not
rustc/cargo. This becomes real when a realm carries a Rust toolchain — and
the obvious candidate is Ferrocene itself, pinned and verified by varve and
registered into rustup. Worth considering separately; not assumed here.

Second caveat: rustup toolchain link expects a toolchain-shaped directory
(bin/rustc, lib/, …). varve's store is payloads/<name>/<version>, which is
not that shape. So this needs a shaped view — a small tree of symlinks into
the verified store. That is a link in the truest sense: no bytes duplicated, and
the bytes that are read are the verified ones.

2. varve link cargo — instead of export-cargo materialising a registry,
point .cargo/config.toml source-replacement at the store directly.

3. varve link code — instead of export-vsix writing .vsix files for
code --install-extension, install from the store.

Immediate, in-scope consequence

REQ-LAYERDOCS-001's viewer (varve-serve) should read the store, not an
export. That is this idea applied at once, and it is strictly better for a
1.2 MB traceability bundle and much better for rustdoc. varve export-docs
stays, for handing a copy to someone or publishing a CI artifact — the two
answer different questions.

Not asking for a design

What this issue asks is whether link becomes a first-class family beside
export, and if so whether rustup is the first one — which likely depends on
whether a realm will carry a Rust toolchain.

Source: https://criticalup.ferrocene.dev/ (and criticalup CHANGELOG v1.5.0)

[avrabe]

Bazel is the strongest case for link, not the weakest

Asked by the maintainer. Bazel fits this better than rustup does, and the reason
is structural: Bazel's repository cache is already content-addressed by
sha256, which is exactly what varve's store is. varve knows every payload's
sha256 because it is in the signed manifest.

Contrast with rustup, where toolchain link wants a toolchain-shaped
directory (bin/rustc, lib/, …) that varve's payloads/<name>/<version>
layout is not — so that one needs a shaped symlink tree first. For Bazel there
is no shape to invent: the key is the digest.

What we have today

export-bazel-distdir materialises a copy of the layer's .crate tarballs
and you build with --distdir=<DIR>. export-bazel compiles a checksum
registry. Both are exports. Nothing in the tree mentions --repository_cache,
--override_repository or new_local_repository — I checked.

The link-shaped mechanisms Bazel already offers

1. --repository_cache — the high-value one. Bazel looks up downloads in a
content-addressable cache keyed by sha256. Seed it with symlinks into the
verified store and bazel build resolves those archives with no network, no
--distdir flag, and no copied bytes.

The property that makes this genuinely good rather than merely cheaper: Bazel
re-hashes what it finds there. So the link cannot smuggle wrong bytes — varve's
signed claim and Bazel's independent check have to agree, and if they ever
disagree Bazel refuses. Two independent verifications of the same bytes is a
better position than one.

(The exact on-disk layout of that cache — I believe content_addressable/sha256/ <hex>/file — must be confirmed against Bazel's source before anything is
written, not taken from memory. Writing into another tool's cache directory on a
guessed layout is exactly the kind of thing that half-works.)

2. --override_repository=<name>=<path> — points a repository at a local
directory with no copy. This is the right answer for tree payloads: an sdk
or wit payload could be consumed in place instead of via export-sdk. Emitting
a .bazelrc fragment of these is a small, honest deliverable.

3. new_local_repository / bzlmod local registry (--registry=file://…) —
for serving modules offline from the store rather than a copied registry.

Caveats to state plainly

• A repository cache is a cache: Bazel may prune it, so a seeded link is not
  a durable pin. It accelerates and de-duplicates; it does not replace the
  distdir path for a hermetic air-gapped build. Both should exist.
• Writing into a directory another tool owns is mildly invasive and needs to be
  opt-in and reversible.
• export-bazel-distdir should stay. A distdir you can hand to an air-gapped
  machine is a different deliverable from a cache you seed on your own.

Suggested shape

• varve link bazel-cache — seed the repository cache by symlink, keyed on the
  signed digest.
• varve link bazel-repo — emit --override_repository lines for tree payloads.

This also connects to the org's Bazel work already tracked: air-gap rules_rust
(REQ-VENDOR-002 still owes BUILD files on top of the vendor tree) and the
rules_wasm_component checksum-registry contract that export-bazel serves.

[avrabe]

This belongs on the phased consumer API, and our own repos must be the first consumer

Per the maintainer. varve-core::consumer (REQ-CONSUMERAPI-001) is already the
staged surface for this: VERSION, PIN_MANIFEST_VERSION readable as a value
rather than only as an error string — so a consumer built once and run for months
can record "I met a pin newer than I know" as a fact — and PayloadStatus, whose
variants exist so that "I could not find it" and "I found it and it did not
verify" can never be confused. A link capability should extend that, phased,
not arrive as a CLI-only side door.

And the with-device lesson applies directly, which is the part worth writing
down. with-device disappeared from the realm because nothing compared the old
payload list against the new one; the absence was invisible from inside and a
consumer found it by upgrading. It cost three releases to put right
(v0.34.0–v0.34.1) once found.

The same exposure is here in a different shape. Adding link support that nothing
in our own repos actually consumes produces a capability carried by no artifact
— which is this month's recurring defect, four times over: release implemented
in the wrong assembler, the hub staged from the wrong directory, the realm root
behind an env-only reader, the version check running after the tag. Each was
real, correct, tested, and reachable by nothing that mattered.

So the acceptance condition for any link work should be a named real
consumer, not a passing test:

• bazel-cache → one of the org's Bazel repos builds offline with the cache
  seeded and --distdir removed, proving the link is what resolved it.
• bazel-repo → an sdk or wit tree consumed in place by a real target,
  rather than via export-sdk.
• rustup → only once a realm actually carries a Rust toolchain; until then
  there is nothing to link and building it would be speculative.

If no repo is ready to consume a given link, that is the signal to not build it
yet rather than to build it and wait.

[avrabe]

Triaged at v0.36.0 planning: not in a release until a consumer is named.

The acceptance condition recorded above is a named real consumer in our own
repositories, not a passing test — the with-device lesson, where a capability
nothing consumed went missing and a consumer found it by upgrading. No repository
has yet been named as ready to consume a link:

• bazel-cache needs an org Bazel repo willing to build offline with the cache
  seeded and --distdir removed;
• bazel-repo needs a real target consuming an sdk or wit tree in place;
• rustup needs a realm that carries a Rust toolchain, which none does.

Building any of these first would produce exactly the thing this month kept
finding: a capability that is real, tested, documented, and reachable by
nothing. When a consumer is named, this becomes a requirement and gets a release.

One adjacent note for whoever picks it up: v0.36.0 brings crates into the layer
(REQ-CRATEPAYLOAD-001), which is the prerequisite for any bazel-cache link
over .crate archives — so that is the natural moment to ask the Bazel repos
whether they want it.