feat(plugin-oci): oci_load tags every image by content

[raphaelvigee]

Based on #159 (oci_load only exists there). Independent of #378 — a sibling, not a link in that stack.

What

tag was required. Now every load also applies a content-addressed tag — the image target's address as a repository, this load's input hash as the tag:

$ heph run //app:load
app/img:9f2c4e1b7a0d3856

tag becomes optional and is applied in addition, never instead.

Why

A tag written in a BUILD file is a moving target. It names whichever image was loaded last, so two branches, two people, or a rebuild after a change all collide on it and docker run app:dev silently runs the wrong thing. It is also unusable from a script, which has to read the log to find out what happened.

The derived tag can't do that: it changes when and only when the image changes, two people on the same commit get the same string, and it can be predicted from the graph instead of discovered after the fact.

The pinned tag is applied first, so an image is never briefly reachable only under a moving name.

The repository follows the image, not the load

//app:load loading //svc/api:img gives svc/api/img, not app/load. The repository names what you are about to run, and nobody names their load target after the image it loads.

Deriving it is not a formatting exercise

A docker reference is much narrower than a heph address — each path component is [a-z0-9]+([._]|__|[-]+[a-z0-9]+)*:

Address	Repository	Why
//cmd/server:img	cmd/server/img
//Cmd/My_Server:Img	cmd/my-server/img	grammar is lowercase alphanumeric
//example.com/svc:img	example-com/svc/img	docker reads a first component containing a dot as a registry host — kept as-is, docker run becomes a network pull from a registry that does not exist
//localhost:img	heph/localhost/img	a host by name alone, same trap
//app:img@v=linux_amd64	app/img-v-linux-amd64	variants are different images; sharing a repository puts two rows in docker images with nothing to tell them apart
//app:___	error at parse	names the way out (give an explicit tag) rather than a reference-format complaint from the daemon later

The repository is resolved in parse. hashin is only known at run time — the engine computes it after parse — so only the repository is in the def.

OCI_LOAD_FORMAT_VERSION 3 → 4.

Tests

9 unit tests covering the mapping table above, plus tag being genuinely optional and the repo tracking the image rather than the load. The daemon-gated test now asserts both tags land in the daemon and that the derived one is a hex hash — with a per-process package so its repository is unique, since the daemon is shared state. That assertion needs a real daemon: the archive carries RepoTags, but a containerd-backed daemon ignores them in favour of the OCI path, so the explicit tagging afterwards is invisible to a fake.

Drive-by: test_real_skopeo_loads_an_oci_archive_into_the_daemon had described skopeo since skopeo stopped being involved. Renamed and re-documented to what it actually covers.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WqQZxsTqanJRWLWdPSchBo