fix(delete): don't report an image reclaim that didn't happen (backend#1861)

[LukasWodka]

What this fixes

tracebloc delete's image reclaim printed "Reclaimed tracebloc's downloaded images." whether or not it removed anything. On every install except a Windows GPU host it removes nothing, so an operator offboarding a machine was told disk was freed when the step was a total no-op.

The reported cause was wrong — the pattern is right, the story around it wasn't

The finding was that the scope constant names the wrong registry: imageReference = "ghcr.io/tracebloc/*", while the chart's tracebloc images ship from Docker Hub. The registry facts check out, but the conclusion doesn't. docker images reads the host daemon, and the chart's images are never in it:

• Every chart image (tracebloc/jobs-manager, pods-monitor, resource-monitor, mysql-client), the ingestor Job, and the spawned training images are pulled by containerd inside the k3d node. Nothing in the installer does a host docker pull or a k3d image import for them, so docker images on the host never lists them.
• Their disk is reclaimed by k3d cluster delete — step 3 of the offboard, which runs before this one and takes the node container's image store with it.
• The one tracebloc image that does reach the host daemon is the GPU node image the Windows GPU installer pulls (docker pull ghcr.io/tracebloc/k3s-cuda:<k3s>-cuda-<cuda-base>, and a local docker build under the same name as a fallback). ghcr.io/tracebloc/* matches it.

So the pattern is narrowly correct. The comment, the test, and the success message are what were wrong, and this PR fixes those rather than the constant.

Why widening the pattern would be a mistake — blast radius

Both wider forms were checked against a real daemon holding four Hub tracebloc/* images:

$ docker images --filter=reference='ghcr.io/tracebloc/*' --format '{{.Repository}}:{{.Tag}}'
                      # (empty — current pattern, nothing to reclaim on this host)
$ docker images --filter=reference='docker.io/tracebloc/*' --format '{{.Repository}}:{{.Tag}}'
                      # (empty — the fully-qualified form matches NOTHING)
$ docker images --filter=reference='tracebloc/*' --format '{{.Repository}}:{{.Tag}}'
tracebloc/client-image_classification-cpu:local
tracebloc/base:cpu
tracebloc/client-time_series_classification-cpu:local
tracebloc/mysql-client:latest

• docker.io/tracebloc/* would be inert — a second no-op. The daemon stores Hub images under their short name, so only tracebloc/* matches them.
• tracebloc/* is the only form that matches, and all four images above are locally built dev images the installer never pulled. Widening would make tracebloc delete silently destroy a developer's own builds — real harm, and zero gain, since the host daemon holds no chart image to reclaim in the first place.

Nothing is newly removed by this PR. The scope is byte-for-byte unchanged; only reporting, docs and tests change.

Changes

• imageReference comment — replaces the wrong premise ("the ghcr namespace the installer pulls tracebloc images from") with the host-daemon-vs-node-containerd reason, why widening is wrong in both directions, and the one gap it genuinely cannot cover: a mirror / air-gapped install re-homes the node image onto the operator's own registry host, which a literal pattern can't name.
• PruneImages returns (int, error) — how many references it removed, so the caller can tell a real reclaim from a no-op. A failed rmi returns 0: nothing is claimed reclaimed when the removal that would have reclaimed it didn't succeed.
• delete.go — No tracebloc images left to reclaim. on 0, Reclaimed N tracebloc image(s). otherwise. The failure hint is unchanged. The preview line ("tracebloc's downloaded images") is also unchanged and stays accurate: the offboard does remove the machine's images — via the cluster teardown, which is now stated in RFC-0001 §7.10.
• Tests — the old fixture was ghcr.io/tracebloc/jobs-manager:1.9.5, a name no producer has ever written (jobs-manager is a Hub image and its tag is a channel, not a semver). That fixture is precisely why this survived: it asserted the constant back at itself. Fixtures are now names a producer really publishes, and the new TestImageReferenceScope pins the scope to producer facts in both directions — it must cover the published ghcr node image, and it must not reach Docker Hub's tracebloc/*.
• RFC-0001 §7.10 — corrected: it described the ghcr scope as reclaiming "the tracebloc container images", the same wrong premise.

Evidence

make check (vet + full tests + fmt + file budget + style) and make lint (errcheck, ineffassign, misspell, staticcheck -checks all) are green; gofmt -l ./internal/ is clean. The golden string catalog was regenerated and its diff is exactly the two changed strings.

Mutation testing — each part of the fix deliberately broken, test reddens

1. Widen the pattern to Docker Hub's tracebloc/* (the harmful widening):

--- FAIL: TestImageReferenceScope
    --- FAIL: .../covers_the_images_published_under_the_org's_ghcr_namespace
        imageReference "tracebloc/*" does not cover "ghcr.io/tracebloc/k3s-cuda:v1.29.4-k3s1-cuda-12.4.1-base-ubuntu22.04" — the reclaim would miss an image the installer pulls into the host daemon
    --- FAIL: .../does_not_reach_Docker_Hub's_tracebloc_namespace
        imageReference "tracebloc/*" reaches "tracebloc/jobs-manager:prod" — an offboard must not remove Docker Hub tracebloc images the installer never pulled
        imageReference "tracebloc/*" reaches "tracebloc/client-image_classification-cpu:local" — ...

2. Apply the originally-proposed docker.io/tracebloc/* (the inert widening):

--- FAIL: TestImageReferenceScope/covers_the_images_published_under_the_org's_ghcr_namespace
        imageReference "docker.io/tracebloc/*" does not cover "ghcr.io/tracebloc/k3s-cuda:..." — the reclaim would miss an image the installer pulls into the host daemon

3. Restore the always-claim-success message (else if n == 0 → else if false):

--- FAIL: TestDelete_ImageReclaim_ReportsWhatItDid/nothing_matched:_says_so_instead_of_claiming_a_reclaim
        want "No tracebloc images left to reclaim" in the output, got: ...

4. Claim images reclaimed even when rmi failed (return 0, err → return len(refs), err):

--- FAIL: TestPruneImages/best-effort:_rmi_failure_surfaces_to_the_caller,_and_claims_nothing_removed
        removed count = 1, want 0: the rmi that would have reclaimed it failed

All four restored; suite green.

Confirmed on a real machine, not just reasoned about

The ticket flagged "I did not run tracebloc delete on a real installed machine" as the one thing worth doing before fixing. The repo's own Offboard teardown (k3d) e2e does exactly that: it builds the real binary and runs tracebloc delete --yes --force black-box against a throwaway k3d cluster with a real Helm release installed. Its output on this PR:

  ✔ Uninstalled tracebloc.
  ✔ Removed the local environment.
  · No tracebloc images left to reclaim.
  ✔ Removed local tracebloc data and config.

So on a real Linux host, with a real cluster and a real release, the reclaim matches nothing — the no-op is confirmed end to end, and the offboard now says so instead of claiming it reclaimed disk.

Not covered

• The Windows GPU path — the one platform where the reclaim has something to remove — is still established only from the installer source, not observed. There is no Windows GPU runner.
• The mirror / air-gapped node image is still left behind. It's now documented at imageReference rather than fixed, since the CLI can't name the operator's registry host from a literal pattern.

Closes tracebloc/backend#1861

---

Test plan: make check + make lint, plus the four mutations above.

---

Note

Low Risk
Offboard UX and test/doc changes only; image reclaim scope is unchanged and failures remain best-effort.

Overview
tracebloc delete no longer always prints that disk was reclaimed. PruneImages now returns (int, error) so the CLI can distinguish a real host-daemon cleanup from the usual no-op after cluster teardown.

User output follows the count: No tracebloc images left to reclaim. when nothing matched, Reclaimed N tracebloc image(s). when images were removed, with unchanged guidance on failure. The ghcr.io/tracebloc/* filter is unchanged; docs and comments now explain that chart images live in the k3d node’s containerd (reclaimed by k3d cluster delete) while the host step only targets images like the Windows GPU node image—and why widening to Docker Hub’s tracebloc/* would be unsafe.

Tests use real published image names and add TestImageReferenceScope plus TestDelete_ImageReclaim_ReportsWhatItDid; RFC-0001 §7.10 and golden strings are updated.

^{Reviewed by Cursor Bugbot for commit b829c47. Bugbot is set up for automated code reviews on this repo. Configure here.}

[saadqbal]

Nice, careful PR 👍 The reported cause was chased down to the real one — host daemon vs node containerd — and the fix lands where it belongs: reporting, not the scope constant. Reclaimed N only fires when rmi actually succeeded ((0,err) on failure, (0,nil) on no-op), the no-op path tells the truth, and the new tests cover all three. Good call pinning the scope to producer names in both directions instead of asserting the constant back at itself.