fix(sbom, vex, build): keep artifacts with the image in every repository

[reyreavman]

Summary

With --final-repo, the SBOM and VEX of an image existed in exactly one copy, in the final repo: reading them from the stages repo returned nothing, a project where one final image is built from another (fromImage/import) failed with advice to enable SBOM generation that was already enabled, and for a multi-platform image the artifacts were unreachable in the final repo altogether. This PR adds the artifact locality contract (specs/020-sbom-artifact-locality), e2e tests that falsify each breakage, and the fix: artifacts live alongside the image in every registry-backed repository that holds the image.

Repro of the dependent-build failure from a clean checkout: a two-image werf.yaml (base from scratch, app with fromImage: base), build.sbom.enable: true, then werf build --repo <r> --final-repo <rf> against a clean registry fails with the image ... must have an SBOM artifact attached; to generate an SBOM for the image, rebuild it with SBOM generation enabled.

What

Convergence and lookups

• SBOM and VEX converge into the repository the image was built in (the stages repo), regardless of --final-repo; publishing elsewhere can no longer move where artifacts are written.
• A build of dependent final images (fromImage and import) with --final-repo on a clean registry succeeds, and the dependent image's SBOM contains the base image's components.
• The build report still references the final repo when --final-repo is used; werf stage image still prints the stages repo reference.

Placement and propagation

• After a build with --final-repo, werf sbom get and werf attest ls/get/verify return the artifacts against both the stages repo and the final repo.
• For a multi-platform image, each platform manifest digest carries its own SBOM in both repositories; image-level artifacts (VEX) sit on the index digest; werf sbom get --repo <final-repo> --digest <index-digest> --platform <p> returns that platform's SBOM. Previously both platform SBOMs were copied onto the index digest, where the second displaced the first.
• Propagation runs on every build and is idempotent: a repository holding the image without its artifacts is repaired by the next successful build, so the registry state no longer depends on build history.

Copy paths

• Stage copies between repositories (final repo, cache repos) carry the artifacts of every manifest an image index references, and repair a destination that already holds the manifest without its artifacts.
• werf stages copy and bundle copy carry the attached artifacts of the images they transfer.
• The backend-mediated secondary-to-primary copy carries artifacts only when the image digest survived the copy; otherwise nothing is attached whose payload names a different digest, a warning names what was left behind, and werf-generated artifacts are regenerated by convergence in the same run.
• Meta repo migration moves only metadata records, which carry no artifacts; unchanged.

Cleanup

• Cleanup and purge are not changed: they were verified sound (live images protected, only orphaned artifacts collected). The retention e2e pins this.

Verification status

• VERIFIED locally against a live registry (macOS, Docker): dependent images (fromImage+import, both docker backends) and multi-platform placement — red on main, green with the fix.
• UNVERIFIED locally: the cleanup retention e2e needs the amd64-only builder base and runs only in CI.

Why

Two unintended regressions inside PR #225 produced the single-copy state. 55dc5ea4b (content-based tag) stopped storing the final repo descriptor where SBOM propagation read it, silently killing the copy into the final repo. a891ed411 (nil-panic fix) then routed convergence through a shared accessor that prefers the published descriptor, moving the single remaining copy from the stages repo into the final repo. The root defect is one descriptor answering two questions: "the image as published" (what the report needs) and "the image being described" (what convergence and the base/import SBOM lookups need). The fix splits them: contentTagDesc always describes the image in its build repository, the new finalContentTagDesc carries the published final repo descriptor.

The alternative — teaching cleanup to protect the single final-repo copy, as the original review card suggested — was rejected: cleanup was never the problem (it already protects live images), and a single copy stays fragile no matter how careful the cleanup is. The contract and its rationale live in specs/020-sbom-artifact-locality/spec.md.

[reyreavman]

Verification

• Ran the new entries against a local registry:2 with REGISTRY_STORAGE_DELETE_ENABLED=true: task test:e2e paths="./test/e2e/sbom/..." labelFilter="final-repo && cleanup" parallel=1. Two defects in the test itself surfaced this way and are fixed in the diff: the in-tree bare remote failing giterminism, and stage image output needing --log-quiet plus last-line parsing because the test helper returns combined stdout+stderr.
• Not run: a green pass. The host is arm64 and the fixture's builder base (registry.deckhouse.io/container-factory) is amd64-only, so the build stops at image ... does not match the specified platform (linux/arm64/v8). The pre-existing final-repo entries fail identically on this host, so the blocker is the machine, not the new test.
• Mutation: not run, for the same reason. The mutation to try once CI is green: make cleanupFinalStages delete unconditionally instead of protecting stages found in the stages repo, and confirm the first sbom get from the final repo after cleanup fails.

Review focus

• The retention precondition. The test asserts the SBOM survives, so it only means something while the image is genuinely in use — that rests on the commit being reachable from origin/main. If werf's git-history retention treats this setup as unreachable, every entry would still pass for the wrong reason: nothing would be there to delete. Worth confirming against the cleanup log that the stage was evaluated and kept, not skipped.

Follow-up

• File a bug: with --final-repo, the VEX artifact is published only into the stages repo. vexStep.Converge targets the repository from the stages stage descriptor, and convergeVexByImagesSets runs after the SBOM propagation step, so nothing carries VEX into the final repo.
• File a bug: for multi-platform builds the SBOM is not propagated into the final repo. PropagateArtifacts reads the final stage descriptor from the per-platform stage image, which is only set on the single-platform path, so the copy is skipped.
• Extend this suite with the equivalent VEX retention case once the first item is fixed; asserting it today would only lock in the missing artifact.

[reyreavman]

Verification

• Local e2e against a live registry:2 (macOS, Docker backends): task test:e2e paths="./test/e2e/sbom/..." labelFilter="final-repo && (dependent || multiplatform)" parallel=1 — 6/6 specs, red on main before the fix, green after. This is the mutation evidence for the new tests: each suite demonstrably distinguishes the broken state from the fixed one.
• The original dependent-images entries were green on main for the wrong reason: the fixture's base image inherited the io.deckhouse.internal.builder label from the trusted builder base, and WERF_E2E_ALLOW_LOCAL_BUILDER_IMAGES degraded the failed base-SBOM lookup into a silent skip, while the asserted base packages surfaced via the filesystem scan rather than the merge. The fixtures were rebuilt from scratch images, which leaves no escape.
• Multi-platform placement was pinned by registry inspection of a local reproduction: on main, the final repo held one artifact on the index digest (linux/arm64 — the second platform's copy displaced the first via the type+image-name replace key), platform manifest digests held none in the final repo, and the stages repo was correct.
• Full unit suite green (72 suites). Scoped task lint:golangci-lint on every touched package: 0 issues.
• Not run: full-repo task lint:golangci-lint — fails on this host with a pre-existing pkg/deno/embed_darwin_arm64.go: no matching files found typecheck (missing local embed asset, reproduced on a clean tree without these changes).
• Not run locally: the cleanup retention e2e (final-repo && cleanup) — its fixture needs the amd64-only builder base; CI settles it. It read the SBOM from the final repo and failed against the stages repo on main; with the fix both reads must pass.

Review focus

• The multi-platform propagation assumes the registry-level index copy into the final repo preserves platform manifest digests, and attaches per-platform artifacts digest-to-digest on that basis. Verified empirically on registry:2; worth confirming there is no in-scope path that rewrites an index's children.
• CopyFromStorage now copies attached artifacts also when the destination already holds the manifest (repair semantics). That adds a fallback-index HEAD/GET per stage copy on the already-present path — mostly cache refills. If that shows up in build timings, the guard belongs in CopyAllAttachedArtifacts, not in the callers.
• The secondary→primary digest-compare rule leaves user-signed attestations behind when the digest changed, with a warning. The wording of that warning is user-facing; check it reads right in a real log.

Follow-up

• Re-run the full e2e matrix in CI (this PR): retention/cleanup suite is the one local runs cannot cover.
• Extend the VEX e2e suite with a final-repo read-back case, mirroring test/e2e/sbom/final_repo_test.go — VEX now travels with propagation, but no e2e asserts it from the final repo yet.
• Enable the pending multi-platform SBOM entries (native-chroot/native-rootless) once SBOM generation works on Buildah.
• Consider a werf.io-facing note: with --final-repo, artifacts are now present in both repositories; registry storage grows accordingly.