[CouchRiv]

What

AGC driver: graphics ABI refers to a replaced shader header

Registering another header for the same code address replaces the first snapshot on main. An ABI that still refers to the first registered header then fails, even when both headers were explicitly registered with different binary types.

Retain each registered header and its prepared state for unchanged code. ABI resolution finds the matching registered header; draws and dispatches select the registered binary type for their stage. Within a type, the last registered header wins as before. Re-registering an identical earlier header makes its original snapshot current again without preparing it again. Changed code invalidates the older registrations.

Unregistered header differences still throw. A geometry front entry matching both type 2 and type 4 is rejected as ambiguous. Main selected the last registration's type instead. HeaderSelection tests this new lookup refusal. Registration and static ABI preparation keep their existing timing; this adds no preparation fallback at draw.

Retained headers live until code replacement or driver shutdown. Keeping their snapshots increases memory use and requires scanning the headers for a code address. Reordering an earlier registration also invalidates the registry's ABI and draw caches, while retaining the prepared artifacts.

Related public report

Public report #2700 records this refusal in Ghost of Yōtei (PPSA26344, 01.008) on Linux with lavapipe. It describes relocated pointer fields without a changed type. This change addresses explicitly registered headers; it does not accept an unregistered relocated copy or establish that the reported title is fixed. Ghost of Yōtei was not run here.

#1837 remains the rule for bound copies differing only in user_data or padding. This retains #639's registration and static ABI preparation.

Tested

CachyOS Linux, GCC Release build, RTX 4070 Ti (NVIDIA 615.78.08), AMD integrated GPU (RADV RAPHAEL_MENDOCINO), and Mesa lavapipe (llvmpipe, LLVM 23.1.1).

• SharedCodeHeaders in agc_driver_prepared_shaders registers one synthetic program as type 2 and type 4, resolves the first header and submits two draws. A third draw uses a newly registered type-2 header with distinct metadata pointers; a fourth follows re-registration of the original header. All complete without an exception. On main de5e541d8 with lavapipe, the two-draw fixture fails at ABI resolution with the replaced-header refusal, before its first draw.
• agc_driver_prepared_publication asserts snapshot selection and lifetime, identical re-registration order, changed-code invalidation and ambiguous type rejection. The prepared shader, graphics, publication and export group passes 10/10 on all three drivers. The draw checks establish successful submission; they do not measure compilation counts.
• Full AGC driver suites (253 selected each): RADV 253 passed; NVIDIA 252 passed and agc_driver_dcc_keys_first_write failed; lavapipe 225 passed, 27 feature skips and agc_driver_f64_fma_subnormals failed. Both failures reproduce with the same error on an isolated build of main de5e541d8.
• A prior RADV run segfaulted in agc_driver; the same test segfaulted on isolated main. The final full RADV run passed it.
• Full build, test-registration check (558 executables, none unregistered), tools/check_conventions.py --base origin/main and git diff --check pass.
• Not tested: Ghost of Yōtei, Windows, console behaviour.

Checklist

• Based on current main; no other open PR implements the same functions
• One topic per PR; follow-ups go in a new PR
• No comments in code except technical debt
• Unimplemented paths throw (NotImplemented_nid_no_patch); silent stubs are listed in TechnicalDebt
• No notes, investigation .md files or images added to the repository (attach them to this PR)
• New third-party code is a submodule built from source
• Generic behaviour, not specific to one title
• Depends on: none (textual overlap only with feat(agc): accept graphics programs without an AGC shader header #1732, feat(agc): run unregistered NGG vertex programs that need a workgroup on the mesh path #1825, fix(agc): route registered NGG workgroups through mesh #2261 and perf(agc): prepare registered shaders outside the publication lock #2363, which change other behaviour; I rebase on whichever merges first)
• AI-assisted: yes

[github-actions]

Other open pull requests touch the same code. Merging one will break the other, or both implement the same thing. If this one builds on them, list them in Depends on.

Pull request	Conflicting files (lines on main)	Same exports	Same new files
#2976	core/libs/prx/libSceAgcDriver/Execution/include/Driver/Shaders/ShaderRegistry.hpp L12, L91-92

[adriadam10]

Checked the diff, prepared_graphics/prepared_publication/prepared_shaders (20 repeats) and the AGC driver ctest scope on current main; all pass, and the new tests don't build without the change.

Added one commit: a bullet in docs/dev/ARCHITECTURE.md describing the per-code header registry (header selection for ABI vs. by binary type for draws, last-wins within a type, invalidation on changed code), since this changes the registry's ownership model.

Merging.