refactor[next]: name the cache layout and give the translation caches one home

[havogt]

The layout of the generated-code cache was spelled out as string literals at the
places that happen to write it:

Literal	Written in
"translation_cache" / "gtfn_cache"	each backend's workflow factory
"_pyext"	cache.get_cache_folder
"compile_commands_cache"	the compiledb build system, as a function-local

Nothing named these, so reading a cache directory meant recognizing conventions
rather than looking them up, and anything outside the writer had to re-spell
them.

.gt4py_cache/
├── translation_cache/                    <- DaCe translation payloads only
├── gtfn_cache/                           <- gtfn translation payloads only
├── lap_program_pyext_<fp>_<version>/     <- build: liblap_program.so, program.sdfgz
└── compile_commands_cache_..._pyext_.../ <- shared compiledb

Each literal becomes a name in the module that owns it: BINDINGS_NAME_SUFFIX,
TRANSLATION_CACHE_DIR_NAME and TRANSLATION_CACHE_BACKENDS in
otf/compilation/cache.py, and COMPILEDB_PROTOTYPE_NAME_PREFIX in the
compiledb build system.

The inconsistent pair gets one home, stage first and backend second, reached
through get_translation_cache_folder(cache_base, backend) so callers no longer
assemble the path:

.gt4py_cache/
└── translation_cache/
    ├── dace/   <hash>.pkl
    └── gtfn/   <hash>.pkl

[edopao]

LGTM, just a minor comment.

[edopao]

The FileCache constructor accepts path: str | os.PathLike, so it should be possible to avoid the str conversion.

[havogt]

Done — dropped the str() in factory.py; FileCache resolves the Path itself. It also removes the extra nesting this diff had introduced.

[edopao]

Same here

[havogt]

Done — dropped the str() in gtfn.py; FileCache resolves the Path itself. It also removes the extra nesting this diff had introduced.

[Copilot]

Pull request overview

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Refactors cache directory naming by centralizing previously inlined literals, and consolidates translation caches into a single parent directory with per-backend subfolders.

Changes:

• Introduces named constants for cache layout (bindings suffix, translation cache dir name, translation backends, compiledb prototype prefix).
• Adds get_translation_cache_folder(cache_base, backend) and updates DaCe/gtfn runners to use it.
• Updates tests to assert the new cache naming/layout behavior.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
tests/next_tests/unit_tests/otf_tests/compilation_tests/test_cache.py	Updates assertions to use named constants and adds coverage for shared translation cache parent dir.
src/gt4py/next/program_processors/runners/gtfn.py	Switches gtfn translation cache path construction to get_translation_cache_folder(...).
src/gt4py/next/program_processors/runners/dace/workflow/factory.py	Switches DaCe translation cache path construction to get_translation_cache_folder(...).
src/gt4py/next/otf/compilation/cache.py	Adds constants and get_translation_cache_folder(...); updates bindings suffix usage in build cache folder naming.
src/gt4py/next/otf/compilation/build_systems/compiledb.py	Names the compiledb synthetic cache folder prefix constant and uses it in name generation.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[havogt]

Thanks — going through the Copilot comments, one of them earned a change and the
rest do not hold. Noting the checks so they are not re-litigated (the review
banner says it ran degraded: "couldn't run its full agentic review because it
didn't start before the timeout").

FileCache may not accept os.PathLike — it does, and this was @edopao's
request on these exact lines:

def __init__(self, path: str | os.PathLike):
    self.path = pathlib.Path(path).resolve()

Verified FileCache(p).path == FileCache(str(p)).path.

get_translation_cache_folder should mkdir and resolve like
get_cache_folder — the useful one, though the conclusion is inverted. Both
concerns are already covered downstream: FileCache.__init__ resolves, and
FileCache.__setitem__ does mkdir(parents=True, exist_ok=True) before writing.
Creating the folder here would be actively wrong: the cache manager in #2768
calls this for inspection, so gt4py-next-cache path --cache-dir <somewhere>
would create directories merely by reporting where they are. That contract was
implicit, so I have documented it:

    Unlike `get_cache_folder`, this only computes a path. The folder is created by
    the cache that writes into it, so that asking where a cache would be does not
    create it — which tools that only inspect a cache rely on.

Path traversal if backend contains ../ — backend is not user-controlled:
two call sites pass string literals, and the CLI takes it from
argparse(choices=[*TRANSLATION_CACHE_BACKENDS, "all"]), which rejects anything
else (--backend '../../etc' → invalid choice). Adding a guard for an
unreachable input is the kind of defensive check this codebase does not carry.

Derive the _pyext part of CACHE_FOLDER_NAME_PATTERN from
BINDINGS_NAME_SUFFIX (raised twice) — the pattern contains no such literal:
(?P<name>.+)_(?P<fingerprint>…)_(?P<version_id>…) absorbs the suffix into
name, which is why consumers strip it with removesuffix. There is nothing to
derive, so there is nothing that can drift.

[havogt]

I did not merge yet, because I want to do it after the release. Also together with possibly moving the build cache directory as well.