compile_overlays.codegen_hash() returns 0 when runtime/include/
overlay_codegen_hash.h is absent. That fallback is correct for its purpose and
should stay: overlay_api.h has the same __has_include fallback, so a runtime
built without the header and a compiler run without the header agree on
cg<N>_00000000_..., and the cache still loads.
It is never correct for a RELEASE. The header is generated by the runtime
BUILD, in runtime.cmake's "Hashing recompiler codegen" step, so a packager that
reads a tree which has not been built yet silently produces a tag with a zeroed
codegen hash: a plausible-looking string naming a namespace the shipped binary
does not read.
MEASURED 2026-09-02 while building the Tomba 2 Linux cache. Deriving the tag
before the runtime build produced
cg10_00000000_gc530dff78_f0
where the correct tag for that same tree, after the build, is
cg10_ecd487f7_gc530dff78_f0
Note what it looks like from the outside: a well-formed tag, the right number
of fields, the right config hash, the right flavor. A packager would happily
stage a whole cache under it and report a shard count. The runtime would ignore
every one of them. Nothing in a build, a configure, a link or a log would say
so -- which is the exact failure shape this bead exists to remove, one field
over from the field that started it.
So `release_stage.py cg-tag` now fails when the codegen hash reads as 0, and
says which header is missing and that the runtime target has to be built first
(the same build that publishes the flavor file the tag also needs). There is no
override: for a release the condition has no correct outcome.
test_release_stage_cache.py gains CodegenHashGuardTest -- refused on an unbuilt
tree, accepted on a built one. 18 cases, all passing.
Bead: beads-eio.3.102
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Matthew Stanley
37b32bdd0c