nordisk/edda

Cross-repo from_variant — the design, and why it is not a small edge

Status: FILED AS A DECISION, not implemented. 2026-09-06. Scope: crates/nornir-build-thing (edda), read against dwarves, gunnar, tunnr/tunnr-lockfix, korp.

Three seats derived the same missing capability independently on 2026-09-05/06: tunnr stages /app from a PATH because a variant reference cannot cross repos; korp landed a per-binary variant witness because a path is a string and nothing opened the file at the end of it; the seven korp media had to MOVE REPOS (korp 86bf1a9) because a medium is composed from the artifact its from_variant names and that name resolves inside one repo's set only.

This document answers the four questions and then says why the row is a decision rather than an edge.

1. WHY it cannot cross repos today — and which KIND of limit it is

Not one limit. Three, at three different layers, and only the third is hard.

L1 — the FIELD has no repo half (a vocabulary limit; trivially fixable)

A bare handle. Compare KernelDonor { repo, kernel } (src/installer.rs:153-158) and EdgeDecl { repo, variant, typ } (src/tree.rs:257-264), both of which DO carry the repo half.

L2 — the ROSTER the handle is resolved against is this repo's, at four sites

(a scope limit; mechanically fixable, with one real consequence)

variant.rs:2684  validate_package   self.get(dep).is_none()  -> refuse
variant.rs:2760  validate_container (via variant_deps)       -> refuse
variant.rs:2802  validate_vm        self.get(dep).is_none()  -> refuse
variant.rs:2826  validate_iso       self.get(dep).is_none()  -> refuse

e.g. variant.rs:2830 — "iso '{}': masters cargo variant '{}' which is not declared (known variants: {})".

These are SHAPE-ONLY validators: no disk, no resolver, called on every load. That is why the refusal is loud and early today. A coordinate-shaped from_variant cannot be judged here at all — the donor's declaration is not in hand — so the check necessarily moves to a _in-style validator that takes a resolver (validate_edges_with, variant.rs:3756). Fail-fast degrades unless every door that loads a recipe also calls the resolving validator. That is a real cost, and it is exactly the failure mode gunnar hit in gunnars_todo §11.

L3 — the HAND-OFF has no cross-process form (the hard limit)

stage_variant_artifacts (src/image_build.rs:408) is where "the declaration names a cargo variant" becomes "the image build finds its payload". It takes ONE set and ONE repo_root, resolves the handle at image_build.rs:419:

let v = set.require(vname).with_context(|| {
    format!("{label}: chains cargo variant '{vname}', which this repo does not declare")
})?;

and then builds it in-process (image_build.rs:445-449, provenance::build_variant_with_info / chained_variant_in_container) and takes the artifact path off BuildOutcome::artifacts (provenance.rs:509-510) — what cargo actually wrote, never guessed.

That last sentence is the blocker. The path exists only inside the process that ran the build. There is no published location, and no pin, at which a cargo variant's artifact can be found by anyone else. The two kinds that already have one are precisely the two that already cross a boundary:

Verdict on the kind of limit: it is a PUBLICATION limit, not a path-resolution limit, not a trust limit, and not merely unimplemented. Path resolution is already solved (dwarves::buildthing::resolve_build_thing_from, buildthing.rs:494; BuildVariantSet::validate_edges_in, variant.rs:3815). Trust is already solvable (§3). What is missing is that a cargo variant's built artifact is not an addressable, verifiable thing outside the run that made it.

2. Does kernel_donor generalise? — YES in three of four parts, NO in the fourth

KernelDonor (installer.rs:129-158) is documented as "the rule every cross-repo seam here uses". Its four parts:

So: kernel_donor generalises as a declaration and as a plan — and those halves are already generalised and shipping. It does NOT generalise as a hand-off, and the hand-off is the whole of what from_variant means. from_variant is not "name another artifact"; it is "the payload IS the bytes that artifact is". The edge vocabulary answers the first and is silent on the second.

Corollary, and it makes the row smaller than it looks in one direction and bigger in another: cross-repo from_variant should not be a new field at all. It is edges.<feature> of typ exe plus a publication rule. The declaration work is zero; the publication work is the row.

3. THE DESIGN

3a. Resolution — where the other repo is found

Reuse, do not invent. The constellation-layout rule, already spelled twice: <parent of repo_root>/<repo> (variant.rs:3815-3826), with dwarves' richer ladder (buildthing.rs:494 resolve_build_thing_from, which also accepts a repo/variant coordinate) as the door's resolver. edda stays dep-light and takes a &dyn Fn(&str) -> Result<PathBuf> exactly as validate_edges_with does; edda never resolves a checkout on its own.

The consumer never builds the donor. This is already a DECIDED rule for the kernel edge (installer.rs:147-152: "A donor is a CONSUMER of the built kernel, never a second builder"), and it must hold here for the same reasons plus one more: stage_variant_artifacts today would otherwise run cargo inside somebody else's checkout, which cargo_container.rs:575 already forbids ("get to edit another repo's checkout"). The donor's variant is built by dwarves buildthing <donor> --variant <v> — as a --build DAG step (build_dag.rs, already generic over typ) or by hand.

3b. Publication — THE NEW THING, and the only new thing

A cargo variant must land somewhere addressable, with a pin, exactly as a kernel does. Proposed, mirroring kernel_output_dir:

<repo_root>/.build-out/<variant>/
    <artifact basename>          the bytes cargo wrote
    <variant>.build-pin.json     BuildPin

BuildPin is not new work either — provenance::BuildOutcome already carries the artifacts and an Attestation; the pin is that attestation plus the artifact's sha256, written to a conventional path. Without this directory there is nothing for a consumer to open, and every alternative (an env var, a staged path, a warehouse lookup) is the workaround being cured.

The ledger seam generalises for free: KernelLedger (kernel.rs:3217) is already a trait so dwarves can serve a pinned artifact from the build ledger before falling back to the donor's local out-dir. ArtifactLedger is the same shape.

3c. Provenance — how a consumer knows the artifact IS the declared variant

Do not invent a second witness format. edda already owns one: contract::Receipt in linker section .nordisk.buildthing (contract.rs:44, contract.rs:189), carrying atom — "The atom this artifact is, e.g. korp-server" (contract.rs:195-196) — plus the build-thing Coordinate { krate, version, hash }, read back without executing the artifact by receipt::read_receipt (receipt.rs:101).

So the consumer's check is three lines: open the pinned artifact, read_receipt, refuse unless receipt.atom == <the declared variant> and receipt.build_thing.krate == "<donor>-build-thing".

Two measured facts make this the right choice rather than a preference:

• korp already built the parallel mechanism, because it could not reach this one. korp/src/variant.rs (origin/main, commit 820660f) embeds KORP-BIN-VARIANT=<name>; padded to 64 bytes via a const fn witness, and its own doc (korp/src/variant.rs:43-50) says the format belongs in edda once if it ever grows a second field. It exists because for weeks the RDP appliance shipped korp-ui (the GPU build) under a path spelled korp-ui-thin.
• The reader korp's doc names DOES NOT EXIST. korp/src/variant.rs:43-50 points at tunnr-build-thing::staged; tunnr has no staged module and no occurrence of KORP-BIN-VARIANT on any ref (git grep -l KORP-BIN-VARIANT $(git for-each-ref …) → empty). The witness is written and read by nobody. A provenance mechanism whose reader is prose is the same defect as the path it replaced, one layer up.

Honest limit, stated: the receipt is a plaintext self-declaration in a section, not a signature. It is proof against the failure that actually happened (the wrong sibling artifact staged under a right-looking name) and not against a hostile editor. That is the correct strength for a build seam between checkouts the same operator owns, and the pin's sha256 covers the accidental half.

Second honest limit: embed_build_receipt!() is deployed unevenly — dwarves emits it (dwarves/src/main.rs:8398), gunnar and korp only READ it in tests (gunnar/crates/gunnar-recipe/tests/cli_matrix.rs:303, korp/crates/korp-build-thing/tests/cli_matrix.rs:202). A donor variant that carries no receipt cannot be a cross-repo from_variant donor. That is a precondition to enforce at declaration time, not a warning at stage time.

3d. Schema — and what an OLD reader does with it

RECIPE_SCHEMA = 4 (schema.rs:131), first reader 0.1.14 (schema.rs:178-179). If the capability is spelled as edges (§2's corollary) then no new vocabulary is added at all and this section is about a hole that already exists:

edges has no arm in required_by (schema.rs:263-354). grep -n edges src/schema.rs → nothing. So a recipe declaring edges emits schema = 1 (the floor), and IsoBuild / InstallerBuild / ContainerBuild are not deny_unknown_fields (schema.rs:59-67) — an older reader silently drops the whole edge table. That is R3's own named disease, live today: tunnr-lockfix/.nornir/build-variants.toml:459,473,487,501 declares four [build.kernel.edges.toolchain] tables under no schema header at all.

The fix is a required_by arm naming each edge ("[build.<kind>.edges.<feature>] on '<variant>'"), RECIPE_SCHEMA = 5, and FIRST_READER += (5, "0.1.15").

It is not a tonight edit. FIRST_READER may not name a version that does not exist — the module says so in its own words about the 0.1.11 gap (schema.rs:147-155: "Naming 0.1.11 here would make the refusal message a lie") — so the arm forces nornir-build-thing 0.1.14 → 0.1.15, a crate ~20 manifests across the constellation depend on. And it converts a silent drop into a loud whole-file refusal for every stale installed forge, which is the 2026-09-05 gunnar outage replayed on tunnr (schema.rs:100-120). Correct by doctrine; a release event in practice; Rickard's call, not a lane's.

3e. Failure — it must refuse loudly, never silently produce nothing

Five refusals, each naming a different repair. Modelled one-for-one on resolve_built_kernel's four (kernel.rs:3186-3198), which is the proven shape:

Two rules govern all five:

1. Refuse before building anything. The cheap gate above the expensive one, for the reason dwarves/src/assemble_cell.rs:490-500 measures: 18 m 29 s of cargo before a missing admin_key was mentioned.
2. A missing donor is never a skip and never an empty payload. Today's iso.rs:458-462 ("needs a kernel, a staging tree, or a from_variant to be bootable") is the local version of the property; the cross-repo version must be at least as loud, because the failure is now REMOTE and the operator has no reason to look in the other checkout unless told to.

4. VERDICT — filed, not implemented

The row is one publication convention (§3b) away from being small, and that convention is a build-system-wide decision: where a cargo variant's artifact lands, what pins it, whether the ledger or the out-dir is authoritative, and which repos must start emitting a receipt before they may be donors. Landing half of it — a coordinate-shaped from_variant whose validator moves off the load path (§1/L2) and whose hand-off has nowhere to read from (§1/L3) — would trade a loud workaround for a quiet gap in the build system of five repos. The three seats' workarounds are honest and they hold; nothing is on fire.

What is genuinely small and separable, in dependency order:

1. The required_by arm for edges + the 0.1.15 bump (§3d) — needed by anything that spells a cross-repo edge, and it repairs a live silent drop in tunnr-lockfix. Blocked only on the version bump being sanctioned.
2. korp's witness → contract::Receipt (§3c), and a real reader on tunnr's side. Today the guard korp documents does not exist on any tunnr ref.
3. .build-out/<variant>/ + BuildPin written by build_variant_with_info (§3b). Additive, no schema, no declaration change, useful on its own.

With 1–3 landed, cross-repo from_variant is edges.<feature> typ = "exe" plus a stage_variant_artifacts that takes (set, root) per dep instead of one pair — which IS a small edge, then.