PALEOS-API cache resolver

def resolve_paleos_api_unified(
    material: str,
    grid: GridSpec,
    *,
    h2o_table_path: str | None = None,
    force: bool = False,
    n_workers: int = -1,
) -> Path:
    """Return the path to a cached unified PALEOS-API table, regenerating if stale.

    Parameters
    ----------
    material : {'iron', 'mgsio3', 'h2o'}
    grid : GridSpec
    h2o_table_path : str or None
        AQUA table path, passed through to the generator when ``material=='h2o'``.
    force : bool
        If True, regenerate even if a valid cached file exists. Intended for
        debugging / explicit cache-invalidation commands.
    n_workers : int
        Parallelism for the generator on cache-miss. Default ``-1`` =
        ``os.cpu_count()`` (cold-cache builds should use all cores; cache hits
        don't run the generator at all).
    """
    sha = paleos_installed_sha()
    _check_paleos_once(sha)
    build = build_key(material, h2o_table_path)
    sha_s = _sha_short(sha)
    grid_s = grid.hash_short()

    fname = f'unified_{material}_{sha_s}_{build}_{grid_s}.dat'
    path = _cache_root() / fname

    if not force and _header_sha_matches(path, sha, build):
        logger.debug('paleos_api_cache hit: %s', path)
        return path

    logger.info('paleos_api_cache miss: generating %s', path)
    path.parent.mkdir(parents=True, exist_ok=True)
    generate_paleos_api_unified_table(
        material=material,
        out_path=path,
        grid=grid,
        h2o_table_path=h2o_table_path,
        n_workers=n_workers,
    )
    return path

def resolve_paleos_api_2phase_mgsio3(
    grid: GridSpec,
    *,
    force: bool = False,
    n_workers: int = -1,
) -> tuple[Path, Path]:
    """Return (solid_path, liquid_path) for cached 2-phase MgSiO3 tables.

    Regenerates both files as a pair (same SHA + grid_hash) to ensure they
    are always from the same PALEOS commit. If only one side is stale, we
    still regenerate both — the generation cost is O(few min) and pairing
    them guarantees consistency for downstream mushy-zone mixing.

    Parameters
    ----------
    grid : GridSpec
    force : bool
        Regenerate even when cached files look valid.
    n_workers : int
        Parallelism for the generator on cache-miss. Default ``-1`` =
        ``os.cpu_count()``.
    """
    sha = paleos_installed_sha()
    _check_paleos_once(sha)
    build = build_key('mgsio3')
    sha_s = _sha_short(sha)
    grid_s = grid.hash_short()

    solid = _cache_root() / f'2phase_solid_{sha_s}_{build}_{grid_s}.dat'
    liquid = _cache_root() / f'2phase_liquid_{sha_s}_{build}_{grid_s}.dat'

    if (
        not force
        and _header_sha_matches(solid, sha, build)
        and _header_sha_matches(liquid, sha, build)
    ):
        logger.debug('paleos_api_cache 2-phase hit: %s, %s', solid, liquid)
        return solid, liquid

    logger.info('paleos_api_cache 2-phase miss: generating %s + %s', solid, liquid)
    solid.parent.mkdir(parents=True, exist_ok=True)
    generate_paleos_api_2phase_mgsio3_tables(
        out_solid=solid,
        out_liquid=liquid,
        grid=grid,
        n_workers=n_workers,
    )
    return solid, liquid

def resolve_registry_entry(material_dict: dict) -> dict:
    """Materialise ``PALEOS-API:*`` / ``PALEOS-API-2phase:*`` registry entries in place.

    Registry entries for the live-tabulated EoS carry grid + material metadata
    but no file path. This helper detects ``format=='paleos_api'`` or
    ``format=='paleos_api_2phase'`` in either the top-level dict (unified
    materials) or in the ``solid_mantle`` / ``melted_mantle`` sub-dicts
    (2-phase materials), calls the appropriate cache resolver, writes the
    resolved on-disk path into ``eos_file``, and switches ``format`` to the
    matching downstream format (``paleos_unified`` or ``paleos``). Subsequent
    dispatch goes through the normal code path unchanged.

    Rewriting in place (rather than returning a copy) is intentional: the
    registry entry is a mutable dict that downstream consumers hold a
    reference to. Once resolved, further lookups on the same entry are O(1)
    (plain dict access).

    Parameters
    ----------
    material_dict : dict
        A registry entry. For unified materials the dict itself has
        ``format='paleos_api'``. For 2-phase materials the outer dict has
        no ``format`` key but contains ``solid_mantle`` and
        ``melted_mantle`` sub-dicts that each have ``format='paleos_api_2phase'``.

    Returns
    -------
    dict
        The same ``material_dict`` (mutated in place). Returned for chaining.
    """
    if material_dict is None:
        return material_dict

    if material_dict.get('format') == 'paleos_api':
        _resolve_unified_in_place(material_dict)
        return material_dict

    # 2-phase / Tdep layout: sub-dicts per phase.
    for sub_key in ('solid_mantle', 'melted_mantle'):
        sub = material_dict.get(sub_key)
        if isinstance(sub, dict) and sub.get('format') == 'paleos_api_2phase':
            _resolve_2phase_in_place(material_dict)
            break

    return material_dict

def invalidate_cache(material: str | None = None) -> int:
    """Remove cache files for ``material`` (or all if ``None``).

    Returns the number of files removed. Intended for CLI / debugging use.
    """
    root = _cache_root()
    if not root.exists():
        return 0
    removed = 0
    for p in root.iterdir():
        if not p.is_file() or p.suffix != '.dat':
            continue
        if material is not None:
            # Match on the ``_<material>_`` segment (unified) or ``2phase_*`` (all).
            tag_unified = f'unified_{material}_'
            is_match = p.name.startswith(tag_unified)
            if material == 'mgsio3':
                is_match = is_match or p.name.startswith('2phase_')
            if not is_match:
                continue
        try:
            os.remove(p)
            removed += 1
        except OSError as e:
            logger.warning('paleos_api_cache: could not remove %s (%s)', p, e)
    return removed