feat[next]: cache manager CLI for the translation caches

[havogt]

Why

gt4py.next keeps two persistent caches side by side under the cache base:

Cache	Where	Holds
Build cache	<program>_pyext_<hash>_<version>/	build artifacts, the compiled library
Translation cache	translation_cache/ (dace), gtfn_cache/ (gtfn)	the already translated program: optimized SDFG / generated sources

The translation cache key covers the program and gt4py.__version__, not the
gt4py sources. Editing a transformation or an optimization pass therefore leaves
the key intact (an editable install only changes its version on a commit — the
dirty marker is a constant .dirty suffix — and a non-editable install never
does). The next run replays the cached translation and skips the pass, while the
build step still recompiles from it and refreshes the library's mtime.

That combination is easy to misread: clearing only the *_pyext_* folder and
observing a rebuilt library looks like proof that a changed pass ran, when it
never executed. It cost four multi-node benchmark jobs and about a day of
investigation once, with two further tells misread along the way (successive SDFG
dumps differing only in guid fields, and debug logging inside the pass
producing no output).

What

gt4py-next-cache (also python -m gt4py.next.gt_cache_manager), mirroring the
existing gt4py.cartesian.gt_cache_manager: stdlib argparse, library functions
plus a __main__ block, no new dependency. It covers both translation caches,
with --backend to narrow and --cache-dir to point at another cache base.

Three sub-commands:

• path — the cache directories this environment resolves, honouring
  GT4PY_BUILD_CACHE_DIR / GT4PY_BUILD_CACHE_LIFETIME. Answers the first
  question everyone has, since the default session lifetime puts the cache in a
  temporary directory that is gone when the process exits.
• list — the entries: backend, key, program, size, mtime; --filter,
  --sort, --json. With --by-program, one row per program plus its build
  folders, which is where the two-cache trap becomes visible. --fail-if-cached
  exits non-zero if anything matched, to gate a job on an empty cache.
• delete — by --key, --program <glob> or --all. Lists what matched,
  then asks [y/N]; per clig.dev it only prompts when stdin
  is a terminal and otherwise requires --yes, so a job file never blocks on a
  prompt (nor crashes on EOF the way pip uninstall does). -n/--dry-run
  previews. Takes the same locking.lock as the runtime (these caches are shared
  between MPI ranks) and leaves build folders alone unless --include-build-dirs.

$ gt4py-next-cache list --by-program
PROGRAM            ENTRIES         BUILDS
lap_program        3 dace, 2 gtfn  0 (+15 stale)
laplap_program     9 dace, 6 gtfn  0 (+15 stale)

WARNING: 2 program(s) have a cached translation but no usable build folder. Their
next run rebuilds the library while the cached translation is replayed, so a fresh
library there would NOT mean a changed pass ran.

What it deliberately does not do: predict. A cache hit is decided by a
fingerprint taken at run time over the lowered program and its arguments
(CachedStep.cache_key), which no tool outside a run can compute. The caches
record only a program name, so everything here is a count of what is on disk.
Read in the one direction that holds: no entries for a program means it will be
re-translated; entries present is a reason to delete, never evidence that a run
replayed. Build folders are the exception in one respect — their name records the
build-cache version, so folders no run here can hit are counted as stale.

Entries are read directly rather than through FileCache, whose __getitem__
deletes what it cannot unpickle — an inspection tool must not do that. A corrupt
or version-skewed entry degrades to <unreadable> instead of crashing.

Cache layout is read from where it is defined instead of being duplicated:
TRANSLATION_CACHE_DIR_NAMES and BINDINGS_NAME_SUFFIX now live next to
get_cache_folder; the compiledb prototype name prefix became a constant so the
shared compiledb folder — named like a program build folder — is neither reported
as a program nor deleted along with one; and the DaCe compile-completion marker
moved to build_data, next to the BuildData status it complements, so "did this
build finish" is answered in one place.

[project.scripts] gains the distribution's first console script, so the tool
is on PATH wherever gt4py is installed — including an icon4py environment on a
cluster, which is where this failure mode actually bites. Named after the
subpackage rather than gt4py-cache because gt4py.cartesian has a separate
cache with its own manager. Happy to add an ADR for the new packaging surface if
reviewers want one.

Also adds an agent skill (.agents/skills/translation-cache/) that fires before
benchmarking a codegen change, states the anti-pattern explicitly (a fresh
library mtime is not evidence a pass ran), and gives the delete/verify recipe plus
the GT4PY_BUILD_CACHE_VERSION_ID alternative.

Verification

• 43 unit tests building real ProgramSource payloads through FileCache:
  path resolution under both lifetimes, empty/missing/populated/corrupt caches,
  grouping and staleness, the confirmation flow (terminal yes/no, EOF, and that a
  non-interactive run never prompts), delete dry-run vs --yes, refusal to touch
  anything outside the cache, and that build folders survive a delete without
  --include-build-dirs.
• Full tests/next_tests/unit_tests: 2211 passed. mypy src/ and pre-commit
  clean.
• Exercised against a real 224-entry icon4py cache written by a different gt4py
  version, and end to end with actual compiles on both backends.

The behavioural claims were measured, not assumed, and two of them corrected the
tool: a re-run with both caches warm rebuilds nothing (26 identical .so mtimes,
184s → 26s), and editing a program's source re-translates it although its entries
still sit there under the unchanged program name.

[havogt]

Note it's not in the script directory in purpose, because you want to run it in the venv where gt4py lives that created the cache dir.

[havogt]

Superseded by #2768 (same content, now on a branch in this repo so it can carry a stack) and #2769 (the cache directory rename on top). Closing to avoid a duplicate; no review had started here.