Add local image tagging on shared content storage

[chruffins]

summary

This PR adds server-side support for hypeman tag.

Adds POST /images/{name}/tag: create or update a local tag pointing at an image already present locally, without pulling or reconverting. Stacked on the content-addressed storage groundwork.

• Source may be a tag or digest reference; target must carry a tag (digest targets are rejected).
• Tagging requires the source to be ready (409 otherwise); missing sources return 404, invalid references 400.
• Cross-repository targets promote the digest into shared content first, so every alias resolves to one rootfs copy and GC keeps content alive while any repository tag references it.
• Tag symlinks are staged and renamed atomically, matching the existing last-pull-wins replacement semantics.
• Regenerated lib/oapi/oapi.go via make oapi-generate (pinned oapi-codegen), added the route scope, and registered the endpoint in stainless.yaml for SDK generation.

flows

The existing image-creation path resolves a registry reference, then reuses a local image or queues a pull and conversion:

createImage(name):
  validate tags, platform, and image reference
  resolve the tag or digest against the remote registry
  lock image mutations

  if local metadata exists:
    if ready:
      create or update the local tag reference
      return the image
    if still building:
      record the tag as a pending claim
      return the pending image

  write pending metadata
  create the pending tag reference
  enqueue pull -> unpack -> convert -> finalize
  return the pending image

ImportLocalImage uses the same reuse-or-queue path with a digest supplied by the local OCI cache. Existing lookups resolve a tag symlink or digest, then read metadata; deletion removes references and garbage-collects unreferenced content.

The new tag path operates only on ready local content:

tagImage(source, target):
  parse both references; require a tagged target
  lock image mutations

  resolve a source tag to its local digest, or use the source digest
  read source metadata and require ready status

  if repositories differ:
    promote legacy content into shared content

  atomically create or replace the target tag
  update the target tag generation
  return the source metadata under the target name

It does not contact a registry, pull layers, or reconvert the rootfs. Same-repository tagging only installs the new reference; cross-repository tagging first makes the shared content available.

why

Separates mutable tag references from immutable digest content so many similar images (e.g. app deployments) can share storage and be retagged cheaply — the Docker-style tag-then-push flow.

validation

• go test ./lib/images ./lib/scopes ./lib/builds ./cmd/api -count=1 (includes new unit tests: same-repo tag, digest source, cross-repo promotion + GC, not-ready/not-found/digest-target rejection, atomic tag replacement, handler error mapping, route URL decoding)
• go vet ./... clean
• Full image integration tests run against Docker Hub; instance VM tests require /dev/kvm access not available in this environment.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit ab2c694. Configure here.}

[github-actions]

-->

✱ stlc build

✅ go code · compare

Your SDK build was successful.

generate ✅ → bootstrap ✅ → format ✅

116 files generated at 2598162 (pushed)

go get github.com/kernel/hypeman-go-staging@2598162b30eb24c04f2f6193f658dc74327df882

✅ python code · compare

Your SDK build was successful.

generate ✅ → bootstrap ✅ → format ✅

232 files generated at 08ecfd0 (pushed)

✅ typescript code · compare

Your SDK build was successful.

generate ✅ → bootstrap ✅ → format ✅

138 files generated at 87e952c (pushed)

Diagnostics: ❗ 0 new / 1 total error, 💡 0 new / 5 total note

Level	Code	Message	Targets

Build metadata

Build	bd_76G5D6Pm-boisterous-slug
Timestamp	2026-08-31T23:53:43.492Z
stlc	8413509
Spec hash	1061c067fc80
Config hash	659c3687c3f0

---

This comment is auto-generated by stlc and is kept up to date as you push.
If you push new commits, re-run this workflow to update this comment.
Last updated: 2026-08-31 23:54:07 UTC

[sjmiller609]

changes requested

• lib/images/tag.go:37-40 — replacing a tag does not garbage-collect its previous digest or refresh disk usage. example:

  1. app:stable → sha256:old
  2. app:latest → sha256:new
  3. sha256:old has no other tags
  4. hypeman tag app:latest app:stable changes stable to sha256:new
  5. nothing references sha256:old, but its rootfs remains on disk indefinitely

• openapi.yaml:2671-2701 — the authenticated endpoint omits a 401 response, unlike POST /images. add it so the contract and generated SDK response types cover authentication failures consistently.