core.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
 
"""!
@file core.py
@brief A comprehensive conductor script for the PICurv simulation platform.
 
This script acts as the central user interface for running simulations,
managing configurations, and orchestrating the entire end-to-end workflow.
It translates user-friendly YAML files into C-solver compatible control files,
supports full multi-block configurations, and provides live log streaming.
It features intelligent, content-based config file discovery and robustly
manages data I/O paths for the post-processor. It also supports Slurm job
generation/submission and parameter sweeps via job arrays.
"""
 
import yaml
import sys
import os
import argparse
import subprocess
import shutil
import glob
import csv
import json
import hashlib
import functools
import itertools
import re
import shlex
import copy
import contextlib
import math
import difflib
import warnings
from datetime import datetime
from io import StringIO
import time
import filecmp
import importlib.util
import errno
import tempfile
from pathlib import Path
from xml.etree import ElementTree
 
try:
    from .storage import (
        StorageError,
        cold_study_members,
        restore_cold_study_members,
        is_artifact_cold,
        read_artifact_identity,
        STORAGE_LOCK_FILENAME,
        STORAGE_STATE_FILENAME,
        require_storage_payload_local,
        runtime_stage_lock,
        storage_state_summary,
        _rebase_restored_text_paths,
    )
except ImportError:
    # White-box tests also load core.py directly rather than as a package module. The
    # storage package resolves its own siblings by relative import, so it is loaded by
    # putting its parent on the path rather than by file location.
    _package_parent = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
    if _package_parent not in sys.path:
        sys.path.insert(0, _package_parent)
    _storage_module = importlib.import_module("picurv_cli.storage")
    StorageError = _storage_module.StorageError
    cold_study_members = _storage_module.cold_study_members
    restore_cold_study_members = _storage_module.restore_cold_study_members
    is_artifact_cold = _storage_module.is_artifact_cold
    read_artifact_identity = _storage_module.read_artifact_identity
    STORAGE_LOCK_FILENAME = _storage_module.STORAGE_LOCK_FILENAME
    STORAGE_STATE_FILENAME = _storage_module.STORAGE_STATE_FILENAME
    require_storage_payload_local = _storage_module.require_storage_payload_local
    runtime_stage_lock = _storage_module.runtime_stage_lock
    storage_state_summary = _storage_module.storage_state_summary
    _rebase_restored_text_paths = _storage_module._rebase_restored_text_paths
 
_NUMPY_MODULE = None
_MATPLOTLIB_PYPLOT = None
 
 
class _LazyNumpyProxy:
    """!
    @brief Module-like proxy that preserves `picurv.np` without eager import.
    """
 
    def __getattr__(self, name):
        """!
        @brief Resolve a NumPy attribute on first use.
        @param[in] name NumPy attribute name.
        @return Requested NumPy attribute.
        """
        return getattr(require_numpy(), name)
 
 
np = _LazyNumpyProxy()
 
 
def _prune_incompatible_python_site_paths(paths):
    """!
    @brief Remove site-package paths for a different Python major/minor version.
    @param[in] paths Candidate sys.path entries.
    @return Filtered path list.
    """
    current = (sys.version_info[0], sys.version_info[1])
    pattern = re.compile(r"python(?:-)?(\d+)\.(\d+)", re.IGNORECASE)
    filtered = []
    for path in paths:
        text = str(path)
        match = pattern.search(text)
        if match:
            path_version = (int(match.group(1)), int(match.group(2)))
            if path_version != current and ("site-packages" in text or "dist-packages" in text):
                continue
        filtered.append(path)
    return filtered
 
 
def _drop_imported_package(package_name: str):
    """!
    @brief Remove a failed/partial import package tree from sys.modules.
    @param[in] package_name Top-level package name.
    """
    prefix = package_name + "."
    for module_name in list(sys.modules):
        if module_name == package_name or module_name.startswith(prefix):
            sys.modules.pop(module_name, None)
 
 
def require_numpy():
    """!
    @brief Import NumPy only for commands that need numeric reductions.
    @return Imported NumPy module.
    """
    global _NUMPY_MODULE
    if _NUMPY_MODULE is not None:
        return _NUMPY_MODULE
    try:
        import numpy
    except Exception as exc:
        first_error = exc
        original_path = list(sys.path)
        try:
            _drop_imported_package("numpy")
            sys.path = _prune_incompatible_python_site_paths(original_path)
            import numpy
        except Exception as retry_exc:
            raise RuntimeError(
                "NumPy is required for this operation, but no compatible NumPy "
                "could be imported for this Python interpreter. PICurv ignored "
                "site-packages paths for other Python versions and retried. "
                f"First error: {first_error}. Retry error: {retry_exc}"
            ) from retry_exc
        finally:
            sys.path = original_path
    _NUMPY_MODULE = numpy
    return _NUMPY_MODULE
 
 
def optional_matplotlib_pyplot():
    """!
    @brief Import matplotlib.pyplot lazily for study plot generation.
    @return matplotlib.pyplot when available, otherwise None.
    """
    global _MATPLOTLIB_PYPLOT
    if _MATPLOTLIB_PYPLOT is not None:
        return _MATPLOTLIB_PYPLOT
    original_path = list(sys.path)
    try:
        import matplotlib.pyplot as pyplot
    except Exception:
        try:
            _drop_imported_package("matplotlib")
            sys.path = _prune_incompatible_python_site_paths(original_path)
            import matplotlib.pyplot as pyplot
        except Exception:
            return None
        finally:
            sys.path = original_path
    _MATPLOTLIB_PYPLOT = pyplot
    return _MATPLOTLIB_PYPLOT
 
# --- Global Path Definitions ---
# The implementation package and source-tree entrypoint live in picurv_cli/,
# while generators/ owns standalone generators.
PACKAGE_PATH = os.path.dirname(os.path.realpath(__file__))
PACKAGE_PROJECT_ROOT = os.path.dirname(PACKAGE_PATH)
INVOKED_SCRIPT_DIR = os.environ.get(
    "_PICURV_INVOKED_SCRIPT_DIR",
    PACKAGE_PATH,
)
SCRIPT_PATH = os.environ.get(
    "_PICURV_SCRIPT_PATH",
    PACKAGE_PATH,
)
PROJECT_ROOT = os.path.dirname(SCRIPT_PATH)
GENERATORS_PATH = os.path.join(PACKAGE_PROJECT_ROOT, "generators")
if os.path.basename(SCRIPT_PATH) == "bin":
    DEFAULT_BIN_DIR = SCRIPT_PATH
else:
    DEFAULT_BIN_DIR = os.path.join(PROJECT_ROOT, "bin")
 
VERSION_FILE = os.path.join(PACKAGE_PROJECT_ROOT, "VERSION")
 
 
def _read_release_version() -> str:
    """!
    @brief Read the single release version shared by every PICurv executable.
    @return Release version from VERSION, or a safe development fallback.
    """
    configured = os.environ.get("PICURV_RELEASE_VERSION")
    if configured:
        return configured.strip()
    try:
        with open(VERSION_FILE, "r", encoding="utf-8") as stream:
            value = stream.read().strip()
    except OSError:
        value = "0.0.0"
    return value or "0.0.0"
 
 
def _git_output(*arguments) -> "str | None":
    """!
    @brief Run one git command in the source checkout.
    @param[in] arguments Git arguments.
    @return Stripped standard output, or None when git is unavailable or the command fails.
    """
    try:
        result = subprocess.run(["git", *arguments], cwd=PACKAGE_PROJECT_ROOT,
                                text=True, capture_output=True, check=False)
    except OSError:
        return None
    return result.stdout.strip() if result.returncode == 0 else None
 
 
def _source_build_identity(release_version: str) -> dict:
    """!
    @brief Resolve reproducible release, commit, and dirty-tree build identity.
    @details One `git describe --long --dirty` gives the commit, its distance from the
             release tag, and whether tracked files differ from it (untracked files are
             ignored, as `git status --untracked-files=no` did). Only when the tag is
             missing does it fall back to the commit, a dirty check, and the commit count.
             On a cold network filesystem each git call costs seconds, which is why this is
             reached lazily through picurv_build() rather than at import.
    @param[in] release_version Release version read from VERSION.
    @return Mapping suitable for manifests and user-facing status output.
    """
    identity = {
        "release_version": release_version,
        "version": release_version,
        "git_commit": None,
        "git_short_commit": None,
        "dirty": None,
        "build_id": release_version,
        "dev_distance": None,
        "released": False,
    }
    described = _git_output("describe", "--tags", "--long", "--dirty", "--abbrev=40",
                            "--match", f"v{release_version}")
    match = re.match(r"^v.+-(\d+)-g([0-9a-f]{40})(-dirty)?$", described or "")
    if match:
        identity["dev_distance"] = int(match.group(1))
        identity["git_commit"] = match.group(2)
        identity["dirty"] = bool(match.group(3))
    else:
        # No tag for this release yet: every commit is development toward it.
        identity["git_commit"] = _git_output("rev-parse", "HEAD")
        status = _git_output("status", "--porcelain", "--untracked-files=no")
        identity["dirty"] = None if status is None else bool(status)
        count = _git_output("rev-list", "--count", "HEAD")
        if count is not None and count.isdigit():
            identity["dev_distance"] = int(count)
    if identity["git_commit"]:
        identity["git_short_commit"] = identity["git_commit"][:12]
    # Commits since the release tag, so a development build is visibly ahead of the
    # release it names rather than claiming to be that release.
    identity["released"] = identity["dev_distance"] == 0 and not identity["dirty"]
    if identity["git_short_commit"]:
        development = "" if identity["dev_distance"] in (0, None) else f".dev{identity['dev_distance']}"
        suffix = f"{development}+g{identity['git_short_commit']}"
        if identity["dirty"]:
            suffix += ".dirty"
        identity["build_id"] = release_version + suffix
        identity["version"] = identity["build_id"]
    return identity
 
 
@functools.lru_cache(maxsize=None)
def picurv_build() -> dict:
    """!
    @brief The conductor's own build identity, resolved on first use and kept for the process.
    @details Commands that only parse, validate, or scaffold never touch git; manifests,
             locks, and `picurv version` do, once. Callers that store it copy it.
    @return The cached identity mapping from _source_build_identity().
    """
    return _source_build_identity(PICURV_RELEASE_VERSION)
 
 
PICURV_RELEASE_VERSION = _read_release_version()
CASE_ORIGIN_METADATA_FILENAME = ".picurv-origin.json"
WORKSPACE_CONFIG_FILENAME = ".picurv-workspace.yml"
WORKSPACE_SCHEMA_VERSION = 1
RUN_MANIFEST_SCHEMA_VERSION = 3
ASSET_MANIFEST_SCHEMA_VERSION = 1
ASSET_LOCK_SCHEMA_VERSION = 1
RUNTIME_EXECUTION_CONFIG_FILENAME = ".picurv-execution.yml"
LEGACY_LOCAL_RUNTIME_CONFIG_FILENAME = ".picurv-local.yml"
RUNTIME_EXECUTION_EXAMPLE_FILENAME = "execution.example.yml"
RUNTIME_EXECUTION_CONFIG_FILENAMES = (
    RUNTIME_EXECUTION_CONFIG_FILENAME,
    LEGACY_LOCAL_RUNTIME_CONFIG_FILENAME,
)
 
DEFAULT_RUNTIME_EXECUTION_CONFIG_TEMPLATE = """# Optional shared runtime launcher overrides.
# This file is safe to leave unchanged on ordinary local machines.
# Edit it only when your site needs custom MPI launcher tokens.
#
# Precedence:
#   - local/login-node runs: local_execution -> default_execution -> built-in mpiexec
#   - generated cluster jobs: cluster.yml.execution -> cluster_execution -> default_execution -> built-in srun
#
# Example override:
# default_execution:
#   launcher: "mpirun"
#   launcher_args:
#     - --bind-to
#     - none
default_execution: {}
 
local_execution: {}
 
cluster_execution: {}
"""
 
CLUSTER_TEMPLATE_PLACEHOLDER_ACCOUNT = "my_project_account"
CLUSTER_TEMPLATE_PLACEHOLDER_MAIL = "user@example.edu"
 
DEFAULT_WALLTIME_GUARD_POLICY = {
    "enabled": True,
    "warmup_steps": 10,
    "multiplier": 2.0,
    "min_seconds": 60.0,
    "estimator_alpha": 0.35,
}
WALLTIME_GUARD_ENV_JOB_START_EPOCH = "PICURV_JOB_START_EPOCH"
WALLTIME_GUARD_ENV_LIMIT_SECONDS = "PICURV_WALLTIME_LIMIT_SECONDS"
POST_RESUME_STATE_FILENAME = "post.resume.json"
POST_LOCK_FILENAME = "post.lock"
POST_LOCK_METADATA_FILENAME = "post.lock.json"
POST_LOCK_WRAPPER_FILENAME = "post_lock_wrapper.py"
POST_RESUME_SCHEMA_VERSION = 2
# Keys that choose which steps are processed or where they are read from, not what a
# step's output contains; a step's record stays valid across a change to any of them.
POST_RECIPE_SIGNATURE_EXCLUDED_KEYS = {"startTime", "endTime", "timeStep", "source_directory"}
CHECKPOINT_FORMAT = "picurv-checkpoint"
CHECKPOINT_VERSION = 1
CHECKPOINT_STEP_WIDTH = 12
CHECKPOINT_REQUIRED_EULERIAN_FIELDS = {"Ucat", "Ucont", "Ucont_rm1", "P", "Nvert"}
 
WORKSPACE_DIRECTORY_LAYOUT = (
    "config",
    "config/studies",
    "config/grids",
    "config/initial_conditions",
    "config/inlet_profiles",
    "inputs",
    "inputs/grids",
    "inputs/initial_conditions",
    "inputs/inlet_profiles",
    "inputs/reference_fields",
    "assets",
    "assets/objects",
    "assets/objects/grids",
    "assets/objects/initial_conditions",
    "assets/objects/inlet_profiles",
    "assets/sets",
    "runs",
    "studies",
)
 
RUN_DIRECTORY_LAYOUT = (
    "config",
    "config/history",
    "config/post-recipes",
    "inputs",
    "inputs/grid",
    "inputs/initial_condition",
    "inputs/inlet_profiles",
    "inputs/restart",
    "output",
    "output/checkpoints",
    "output/analysis",
    "output/analysis/metrics",
    "output/analysis/statistics",
    "output/analysis/spectra",
    "output/analysis/plots",
    "output/visualization",
    "logs",
    "scheduler",
)
 
CANONICAL_RUN_PATHS = {
    "config": "config",
    "inputs": "inputs",
    "restart": "inputs/restart",
    "output": "output",
    "checkpoints": "output/checkpoints",
    "analysis": "output/analysis",
    "metrics": "output/analysis/metrics",
    "statistics": "output/analysis/statistics",
    "spectra": "output/analysis/spectra",
    "plots": "output/analysis/plots",
    "visualization": "output/visualization",
    "logs": "logs",
    "scheduler": "scheduler",
}
 
#: Run-relative path of the staged initial-condition spectrum. It sits beside the
#: post-produced spectra but is a reference overlay, not a selectable spectrum task.
INITIAL_CONDITION_SPECTRUM_RELPATH = os.path.join(
    CANONICAL_RUN_PATHS["spectra"], "initial_condition_spectrum.csv"
)
 
_WORKSPACE_ARTIFACT_ROOT_VALUES = {"runs", "studies"}
_ASSET_SOURCE_REFERENCE_KEYS = {
    "source_file", "path", "config_file", "field_file", "grid_file", "source_case", "script"
}
_PYTHON_INITIAL_CONDITION_PROVIDERS = {"ic_gen", "spectral_random_velocity", "resampled_velocity",
                                       "channel_spectral_velocity", "duct_spectral_velocity",
                                       "stability_mode_velocity"}
#: Providers `ic.gen` runs from structured parameters, each with a measured initial spectrum.
SPECTRAL_IC_PROVIDERS = ("spectral_random_velocity", "resampled_velocity",
                         "channel_spectral_velocity", "duct_spectral_velocity", "stability_mode_velocity")
#: Of those, the triply periodic ones, whose initial spectrum is shell-averaged.
SHELL_SPECTRUM_IC_PROVIDERS = ("spectral_random_velocity", "resampled_velocity")
#: Parameters `spectral_random_velocity` accepts.
SPECTRAL_RANDOM_VELOCITY_PARAMS = frozenset(
    {"field", "seed", "random", "spectrum", "projection", "normalization", "remove_mean"}
)
#: Parameters `resampled_velocity` accepts.
RESAMPLED_VELOCITY_PARAMS = frozenset(
    {"field", "source_file", "format", "cells", "box_length", "sample_offset", "layout", "filter",
     "projection", "remove_mean"}
)
#: `resampled_velocity` layout and projection choices.
RESAMPLED_VELOCITY_FASTEST_AXES = ("x", "z")
RESAMPLED_VELOCITY_COMPONENT_LAYOUTS = ("interleaved", "separate")
RESAMPLED_VELOCITY_RAW_DTYPES = ("float32", "float64")
RESAMPLED_VELOCITY_BYTE_ORDERS = ("little", "big", "native")
RESAMPLED_VELOCITY_PROJECTIONS = ("picurv_discrete", "continuum", "none")
#: Source containers `resampled_velocity` reads, and the layout keys each accepts.
RESAMPLED_VELOCITY_LAYOUT_KEYS = {
    "raw": {"fastest_axis", "components", "dtype", "byte_order", "header_bytes"},
    "npy": {"fastest_axis", "components"},
    "npz": {"fastest_axis", "components", "datasets"},
    "hdf5": {"fastest_axis", "components", "datasets"},
}
_FILE_BACKED_GRID_VALUES = {"file", "grid_gen"}
_WORKSPACE_MANAGED_PATHS = {"assets", "inputs", "runs", "studies"}
_VENDORABLE_CONFIG_REFERENCE_KEYS = {"config_file", "script"}
_PLAIN_FILENAME_SENTINELS = {"", ".", ".."}
_VERSION_BUILD_ACTIONS = {"install", "activate"}
 
 
def _find_named_file_upwards(start: str, filename: str):
    """!
    @brief Find a named file at or above an arbitrary filesystem anchor.
    @param[in] start File or directory from which to search.
    @param[in] filename Basename to locate.
    @return Absolute path when found, otherwise None.
    """
    current = os.path.abspath(start or os.getcwd())
    if os.path.isfile(current):
        current = os.path.dirname(current)
    while True:
        candidate = os.path.join(current, filename)
        if os.path.isfile(candidate):
            return candidate
        parent = os.path.dirname(current)
        if parent == current:
            return None
        current = parent
 
 
def find_workspace_root(*anchors):
    """!
    @brief Locate the nearest initialized PICurv workspace for supplied anchors.
    @param[in] anchors Candidate config, run, study, or current-working-directory paths.
    @return Workspace root path when found, otherwise None.
    """
    for anchor in anchors or (os.getcwd(),):
        if not anchor:
            continue
        found = _find_named_file_upwards(str(anchor), WORKSPACE_CONFIG_FILENAME)
        if found:
            return os.path.dirname(found)
    return None
 
 
def load_workspace_config(workspace_root: str) -> dict:
    """!
    @brief Load and validate the immutable workspace identity/configuration file.
    @param[in] workspace_root Initialized workspace directory.
    @return Parsed workspace configuration mapping.
    """
    path = os.path.join(os.path.abspath(workspace_root), WORKSPACE_CONFIG_FILENAME)
    payload = read_yaml_file(path)
    if payload.get("schema_version") != WORKSPACE_SCHEMA_VERSION:
        raise ValueError(
            f"{path}: unsupported workspace schema_version "
            f"{payload.get('schema_version')!r}; expected {WORKSPACE_SCHEMA_VERSION}."
        )
    errors: list = []
    _validate_yaml_schema_keys(payload, _WORKSPACE_SCHEMA, path, errors)
    if errors:
        raise ValueError("\n".join(errors))
    return payload
 
 
def enforce_workspace_version(workspace_root: str) -> dict:
    """!
    @brief Enforce an optional workspace PICurv version requirement.
    @param[in] workspace_root Initialized workspace directory.
    @return Current build identity after successful validation.
    """
    payload = load_workspace_config(workspace_root)
    software = payload.get("software") or {}
    requirement = software.get("picurv") if isinstance(software, dict) else None
    if requirement in (None, ""):
        return dict(picurv_build())
    try:
        from packaging.specifiers import SpecifierSet
        from packaging.version import Version
        requirement_text = str(requirement).strip()
        if not any(token in requirement_text for token in "<>=!~"):
            requirement_text = "==" + requirement_text
        matches = Version(PICURV_RELEASE_VERSION) in SpecifierSet(requirement_text)
    except Exception as exc:
        raise ValueError(
            f"{WORKSPACE_CONFIG_FILENAME}: software.picurv={requirement!r} is not a valid "
            "version or version range."
        ) from exc
    if not matches:
        raise ValueError(
            f"Workspace requires PICurv {requirement!r}, but the active release is "
            f"{PICURV_RELEASE_VERSION} (build {picurv_build()['build_id']}).\n"
            f"Activate a matching installation with 'picurv versions activate <version>' "
            "and retry.\n"
            f"Note: {PACKAGE_PROJECT_ROOT} is a single shared installation. Activating "
            "re-points every workspace and every unpinned job that resolves executables "
            "from it, so two workspaces pinned to different releases cannot both be "
            "satisfied at once. A run staged with --pin-executables keeps its own copy and "
            "survives an activation."
        )
    return dict(picurv_build())
 
 
def enforce_reproducibility_policy(workspace_root: str) -> dict:
    """!
    @brief Enforce an optional workspace policy demanding a clean, released build.
 
    @details Exploratory work should stay frictionless, so this is opt-in: a workspace
             running a campaign that will be published sets it once, and PICurv then
             refuses to stage from a modified or untagged tree instead of recording the
             compromise in a manifest nobody reads until later.
    @param[in] workspace_root Initialized workspace directory, or None.
    @return The resolved policy mapping, empty when none is configured.
    @throws ValueError when the active build does not satisfy the configured policy.
    """
    if not workspace_root:
        return {}
    payload = load_workspace_config(workspace_root)
    policy = payload.get("reproducibility") or {}
    if not isinstance(policy, dict) or not policy:
        return {}
    if policy.get("require_clean_release"):
        problems = []
        if picurv_build().get("dirty"):
            problems.append("the source tree has uncommitted changes")
        if picurv_build().get("dev_distance"):
            problems.append(
                f"HEAD is {picurv_build()['dev_distance']} commit(s) past the "
                f"v{PICURV_RELEASE_VERSION} release tag"
            )
        elif picurv_build().get("dev_distance") is None:
            problems.append("the release tag could not be resolved from this checkout")
        if problems:
            raise ValueError(
                f"{WORKSPACE_CONFIG_FILENAME} sets reproducibility.require_clean_release, "
                f"but this build is {picurv_build()['build_id']}: " + "; ".join(problems) + ".\n"
                "Commit and tag the release, or clear the policy for exploratory work."
            )
    if policy.get("pin_executables"):
        identities = runtime_build_identities()
        stale = [
            name for name, identity in sorted(identities.items())
            if identity.get("available") and not identity.get("matches_source")
        ]
        unavailable = [
            name for name, identity in sorted(identities.items())
            if not identity.get("available")
        ]
        if stale or unavailable:
            detail = []
            if stale:
                detail.append("built from another revision: " + ", ".join(stale))
            if unavailable:
                detail.append("no build identity available: " + ", ".join(unavailable))
            commands = sorted({rebuild_command(name, identities[name]) for name in stale + unavailable})
            raise ValueError(
                f"{WORKSPACE_CONFIG_FILENAME} sets reproducibility.pin_executables, but "
                "the executables do not match the active source (" + "; ".join(detail) + ").\n"
                "Rebuild with " + " and ".join(f"'{command}'" for command in commands)
                + " so the run records the build that produced it."
            )
    return dict(policy)
 
 
def resolve_workspace_path(anchor_file: str, candidate: str, *, allow_external: bool = False) -> str:
    """!
    @brief Resolve a user path against its workspace and reject implicit escapes.
    @param[in] anchor_file Config file whose workspace owns the reference.
    @param[in] candidate Workspace-relative path text.
    @param[in] allow_external Whether an explicit import/reference operation permits an absolute path.
    @return Absolute resolved path.
    """
    if not isinstance(candidate, str) or not candidate.strip():
        raise ValueError("Referenced path must be a non-empty string.")
    text = os.path.expanduser(candidate.strip())
    workspace_root = find_workspace_root(anchor_file)
    if not workspace_root:
        return os.path.abspath(text if os.path.isabs(text) else os.path.join(os.path.dirname(os.path.abspath(anchor_file)), text))
    if os.path.isabs(text):
        if allow_external:
            return os.path.abspath(text)
        raise ValueError(
            f"{anchor_file}: absolute path {candidate!r} is not allowed in workspace configuration; "
            "import it with 'picurv inputs import' or use an explicit reference-mode import."
        )
    resolved = os.path.abspath(os.path.join(workspace_root, text))
    if os.path.commonpath([workspace_root, resolved]) != os.path.abspath(workspace_root):
        raise ValueError(
            f"{anchor_file}: path {candidate!r} escapes the workspace; parent traversal is not allowed."
        )
    if resolved.endswith(".reference.yml") and os.path.isfile(resolved):
        pointer = read_yaml_file(resolved)
        external = pointer.get("picurv_external_reference") if isinstance(pointer, dict) else None
        if not isinstance(external, str) or not os.path.isabs(external):
            raise ValueError(f"Invalid external-reference descriptor: {resolved}")
        if not os.path.isfile(external):
            raise ValueError(f"Registered external input is unavailable: {external}")
        return external
    return resolved
 
 
def ensure_workspace_layout(workspace_root: str) -> None:
    """!
    @brief Materialize the uniform, cheap directory skeleton for one workspace.
    @param[in] workspace_root Workspace root to initialize.
    """
    for relative in WORKSPACE_DIRECTORY_LAYOUT:
        os.makedirs(os.path.join(workspace_root, *relative.split("/")), exist_ok=True)
 
 
def initialize_workspace_root(workspace_root: str, template_name: str) -> str:
    """!
    @brief Create the workspace skeleton and its identity file at one root.
    @param[in] workspace_root Workspace root to initialize.
    @param[in] template_name Example template the workspace was created from.
    @return Path to the written workspace configuration file.
    """
    workspace_root = os.path.abspath(workspace_root)
    ensure_workspace_layout(workspace_root)
    config_path = os.path.join(workspace_root, WORKSPACE_CONFIG_FILENAME)
    write_yaml_file(config_path, {
        "schema_version": WORKSPACE_SCHEMA_VERSION,
        "workspace": {
            "id": os.path.basename(workspace_root),
            "template": template_name,
            "created_at": datetime.now().astimezone().isoformat(),
        },
        "software": {},
        "paths": {
            "config": "config",
            "inputs": "inputs",
            "assets": "assets",
            "runs": "runs",
            "studies": "studies",
        },
    })
    return config_path
 
 
def ensure_run_layout(run_dir: str) -> None:
    """!
    @brief Materialize the uniform, cheap directory skeleton for one run.
    @param[in] run_dir Run root to initialize.
    """
    for relative in RUN_DIRECTORY_LAYOUT:
        os.makedirs(os.path.join(run_dir, *relative.split("/")), exist_ok=True)
 
 
#: Top-level directory names a run owns. Anything else beside them is a peer PICurv
#: does not route, cannot classify for storage, and will not prune.
RUN_DIRECTORY_ROOTS = frozenset(
    relative.split("/")[0] for relative in RUN_DIRECTORY_LAYOUT
)
 
#: Files a run legitimately carries at its own root. Storage's own markers are added
#: at validation time, so this stays the list of what the conductor writes.
RUN_ROOT_ALLOWED_FILES = frozenset({"manifest.json"})
 
 
def validate_run_directory_structure(run_dir: str) -> tuple:
    """!
    @brief Refuse a run whose root has grown a directory the layout does not define.
 
    @details The run topology is a contract: `manifest.json` publishes it, the solver's
             reserved-directory guard defends it, and storage classifies against it. A
             directory beside `output/` breaks all three at once - it is routed by
             nothing, classified as `unclassified`, and therefore archived forever and
             pruned never. Catching it when the run is staged or resumed is the only
             point where the answer is still "move it", rather than "it is already in
             every archive of this run".
 
             Unexpected *files* are reported and allowed. A stray note at a run root
             costs nothing and refusing to resume a long campaign over one would be a
             worse failure than the one being prevented.
    @param[in] run_dir Run root to check.
    @return Tuple of (errors, warnings) as human-readable message lists.
    """
    root = os.path.abspath(run_dir)
    if not os.path.isdir(root):
        return [], []
    allowed_files = set(RUN_ROOT_ALLOWED_FILES) | {
        STORAGE_STATE_FILENAME, STORAGE_LOCK_FILENAME,
    }
    errors, warnings = [], []
    for name in sorted(os.listdir(root)):
        path = os.path.join(root, name)
        if os.path.isdir(path) and not os.path.islink(path):
            if name not in RUN_DIRECTORY_ROOTS:
                errors.append(
                    f"{run_dir}: '{name}/' is not part of the run layout. Scientific "
                    f"output belongs under {CANONICAL_RUN_PATHS['checkpoints']}, "
                    f"{CANONICAL_RUN_PATHS['analysis']}, or "
                    f"{CANONICAL_RUN_PATHS['visualization']}; move or remove '{name}/' "
                    f"before running. Run-owned roots are: "
                    + ", ".join(sorted(RUN_DIRECTORY_ROOTS)) + "."
                )
        elif name not in allowed_files:
            warnings.append(
                f"{run_dir}: unexpected file '{name}' at the run root. It is archived "
                "as unclassified and never pruned."
            )
    return errors, warnings
 
 
def enforce_run_directory_structure(run_dir: str) -> None:
    """!
    @brief Apply `validate_run_directory_structure()` as a refusal at run time.
    @param[in] run_dir Run root to check.
    @return None. Exits non-zero when the run root carries a directory outside the layout.
    """
    errors, warnings = validate_run_directory_structure(run_dir)
    for message in warnings:
        print(f"[WARNING] {message}", file=sys.stderr)
    if not errors:
        return
    for message in errors:
        emit_structured_error(
            ERROR_CODE_CFG_INCONSISTENT_COMBO,
            key="run_layout",
            file_path=os.path.abspath(run_dir),
            message=message,
            hint="Move the directory under output/ or out of the run, then retry.",
        )
    sys.exit(1)
 
 
def case_run_label(case_cfg: dict, case_path: str) -> str:
    """!
    @brief Resolve the stable human-facing portion of a generated run identifier.
    @param[in] case_cfg Parsed case configuration.
    @param[in] case_path Source case YAML path.
    @return Filesystem-safe case title, name, or source stem.
    """
    metadata = case_cfg.get("metadata") or {}
    candidate = (
        case_cfg.get("title")
        or (metadata.get("title") if isinstance(metadata, dict) else None)
        or (metadata.get("name") if isinstance(metadata, dict) else None)
        or Path(case_path).stem
    )
    label = re.sub(r"[^A-Za-z0-9_.-]+", "-", str(candidate).strip()).strip("-.")
    return label or "case"
 
 
def allocate_generated_run_id(runs_root: str, case_cfg: dict, case_path: str) -> str:
    """!
    @brief Build the generated run identity, disambiguating a same-second collision.
 
    @details The identity is `<run label>_<timestamp>` at one-second resolution, so two
             runs of the same case launched back to back - a script, or a smoke
             sequence - would otherwise name the same directory. Creating a run never
             writes into an existing one, so the identity is advanced instead of the
             launch being refused for a clock artifact.
    @param[in] runs_root Directory generated runs are created beneath.
    @param[in] case_cfg Parsed case configuration supplying the run label.
    @param[in] case_path Case path, for the label's fallback.
    @return Run identity that does not currently exist under `runs_root`.
    """
    base = f"{case_run_label(case_cfg, case_path)}_{datetime.now().strftime('%Y%m%d-%H%M%S')}"
    run_id, suffix = base, 1
    while os.path.exists(os.path.join(runs_root, run_id)):
        suffix += 1
        run_id = f"{base}-{suffix}"
    return run_id
 
 
def discard_unused_run_directory(run_dir: str, *, created: bool, staged: bool = False) -> bool:
    """!
    @brief Remove a generated run directory that never received any content.
 
    @details Only a directory this invocation created, and which still holds no files,
             is removed: an existing run, or one that already produced output, is never
             touched by a staging failure. With @p staged the directory may hold the files
             this invocation staged, for a refusal after staging but before any launch.
    @param[in] run_dir Run directory that was about to be staged.
    @param[in] created Whether this invocation created the directory.
    @param[in] staged Whether files this invocation staged, and nothing else, may be present.
    @return True when the directory was removed.
    """
    if not created or not os.path.isdir(run_dir):
        return False
    for _root, _dirs, files in os.walk(run_dir):
        if files and not staged:
            return False
    shutil.rmtree(run_dir, ignore_errors=True)
    return True
 
 
def _file_sha256(path: str):
    """!
    @brief Content digest of one file, or None when it cannot be read.
    @param[in] path File to digest.
    @return Hex digest, or None.
    """
    digest = hashlib.sha256()
    try:
        with open(path, "rb") as stream:
            for block in iter(lambda: stream.read(1024 * 1024), b""):
                digest.update(block)
    except OSError:
        return None
    return digest.hexdigest()
 
 
def build_software_lock(run_dir: "str | None" = None) -> dict:
    """!
    @brief Capture the exact software identity a run is about to execute with.
 
    @details The release and commit say which source is checked out; they do not say
             which bytes ran. Hashing the executables and the generators pins that, so
             a queued job rebuilt out from under it is detectable afterwards rather
             than merely suspected.
    @param[in] run_dir Run whose pinned executables are hashed; the installation's when None.
    @return Software lock mapping.
    """
    lock = {
        "schema_version": 1,
        "picurv_version": PICURV_RELEASE_VERSION,
        "build_id": picurv_build().get("build_id"),
        "git_commit": picurv_build().get("git_commit"),
        "git_dirty": picurv_build().get("dirty"),
        "captured_at": datetime.now().astimezone().isoformat(),
        "executables": {},
        "generators": {},
        "environment": _toolchain_identity(),
    }
    for name in RUN_EXECUTABLE_NAMES:
        path = run_executable_path(run_dir, name)
        identity = read_binary_build_identity(path)
        lock["executables"][name] = {
            "path": path,
            "sha256": _file_sha256(path),
            "build_id": identity.get("build_id"),
            "matches_source": identity.get("matches_source"),
            "petsc": identity.get("petsc"),
        }
    conductor = os.path.join(PACKAGE_PROJECT_ROOT, "picurv_cli", "core.py")
    lock["python_conductor_sha256"] = _file_sha256(conductor)
    if os.path.isdir(GENERATORS_PATH):
        for entry in sorted(os.listdir(GENERATORS_PATH)):
            candidate = os.path.join(GENERATORS_PATH, entry)
            if os.path.isfile(candidate):
                lock["generators"][entry] = _file_sha256(candidate)
    return lock
 
 
def _toolchain_identity() -> dict:
    """!
    @brief Best-effort record of the PETSc, MPI, and compiler in the shell staging the run.
    @details This is the staging environment, which need not be what the binaries were
             built against; each executable's own PETSc is recorded from its build stamp.
    @return Mapping of what could be determined; absent keys mean it could not be read.
    """
    identity = {}
    petsc_dir = os.environ.get("PETSC_DIR")
    if petsc_dir:
        identity["petsc_dir"] = petsc_dir
        version_header = os.path.join(petsc_dir, "include", "petscversion.h")
        try:
            with open(version_header, "r", encoding="utf-8", errors="replace") as stream:
                numbers = {}
                for line in stream:
                    match = re.match(
                        r"#define\s+PETSC_VERSION_(MAJOR|MINOR|SUBMINOR)\s+(\d+)", line
                    )
                    if match:
                        numbers[match.group(1)] = match.group(2)
                if len(numbers) == 3:
                    identity["petsc_version"] = (
                        f"{numbers['MAJOR']}.{numbers['MINOR']}.{numbers['SUBMINOR']}"
                    )
        except OSError:
            pass
    if os.environ.get("PETSC_ARCH"):
        identity["petsc_arch"] = os.environ["PETSC_ARCH"]
    for tool, key in (("mpiexec", "mpi"), ("mpicc", "compiler")):
        executable = shutil.which(tool)
        if not executable:
            continue
        try:
            result = subprocess.run(
                [executable, "--version"], text=True, capture_output=True, timeout=20, check=False
            )
        except (OSError, subprocess.SubprocessError):
            continue
        first = (result.stdout or result.stderr or "").strip().splitlines()
        if first:
            identity[key] = first[0][:200]
    return identity
 
 
def write_software_lock(run_dir: str) -> str:
    """!
    @brief Write the run's software lock beside its asset lock.
    @param[in] run_dir Run directory receiving the lock.
    @return Path to the written lock.
    """
    path = os.path.join(run_dir, CANONICAL_RUN_PATHS["inputs"], "software.lock.json")
    os.makedirs(os.path.dirname(path), exist_ok=True)
    write_json_file(path, build_software_lock(run_dir))
    return path
 
 
def workspace_artifact_root(workspace_root: str, kind: str) -> str:
    """!
    @brief Return the canonical workspace-owned root for runs or studies.
    @param[in] workspace_root Initialized workspace, or None for standalone mode.
    @param[in] kind Either runs or studies.
    @return Absolute artifact root.
    """
    if kind not in _WORKSPACE_ARTIFACT_ROOT_VALUES:
        raise ValueError(f"Unsupported workspace artifact kind: {kind}")
    if workspace_root:
        return os.path.join(os.path.abspath(workspace_root), kind)
    return os.path.abspath(kind)
 
 
def _relative_to_workspace(path: str, workspace_root: str):
    """!
    @brief Return a portable workspace-relative path when possible.
    @param[in] path Path to normalize.
    @param[in] workspace_root Optional initialized workspace root.
    @return Workspace-relative POSIX path, absolute path, or None.
    """
    if not path:
        return None
    absolute = os.path.abspath(path)
    if workspace_root and os.path.commonpath([absolute, workspace_root]) == os.path.abspath(workspace_root):
        return os.path.relpath(absolute, workspace_root).replace(os.sep, "/")
    return absolute
 
 
def snapshot_run_configuration(run_dir: str, source_paths: dict,
                               continuation: bool = False) -> dict:
    """!
    @brief Snapshot editable YAML inputs without erasing prior continuation state.
    @param[in] run_dir Owning run directory.
    @param[in] source_paths Role-to-source-path mapping.
    @param[in] continuation Whether this is a continuation configuration revision.
    @return Active snapshot metadata.
    """
    config_root = os.path.join(run_dir, "config")
    os.makedirs(config_root, exist_ok=True)
    previous = _read_json_if_exists(os.path.join(config_root, "active.json")) or {}
    revision = None
    destination_root = config_root
    if continuation:
        revision = datetime.now().strftime("%Y%m%d-%H%M%S-%f")
        destination_root = os.path.join(config_root, "history", revision)
        os.makedirs(destination_root, exist_ok=False)
    snapshots = {}
    for role, source in source_paths.items():
        if not source:
            continue
        source = os.path.abspath(source)
        suffix = os.path.splitext(source)[1] or ".yml"
        name = f"{role}{suffix}" if role != "cluster" else "cluster.yml"
        destination = os.path.join(destination_root, name)
        shutil.copy2(source, destination)
        snapshots[role] = os.path.relpath(destination, run_dir).replace(os.sep, "/")
    active = {
        "schema_version": 1,
        "revision": revision or "initial",
        "updated_at": datetime.now().astimezone().isoformat(),
        "files": snapshots,
    }
    if continuation and isinstance(previous.get("executables"), dict):
        # A continuation changes what is configured, not which build runs it. The pin
        # moves only when the caller re-pins, which records a new executables entry.
        active["executables"] = previous["executables"]
    write_json_file(os.path.join(config_root, "active.json"), active)
    return active
 
 
#: Run records a continuation's staging rewrites in place, relative to the run directory.
CONTINUATION_STAGED_RECORDS = ("config/active.json", "manifest.json",
                               "inputs/assets.lock.yml", "inputs/software.lock.json")
 
 
def capture_continuation_records(run_dir: str, restart_dir: str) -> dict:
    """!
    @brief Save what a continuation's staging changes, so a refusal can undo it.
    @details Staging rewrites the records in CONTINUATION_STAGED_RECORDS and materializes
             the restart checkpoint into the run's restart input, so both are captured
             before restart resolution runs.
    @param[in] run_dir Existing run directory.
    @param[in] restart_dir The run's restart input directory.
    @return Saved state for restore_continuation_records().
    """
    records = {}
    for relative in CONTINUATION_STAGED_RECORDS:
        path = os.path.join(run_dir, *relative.split("/"))
        records[relative] = open(path, "rb").read() if os.path.isfile(path) else None
    checkpoints = os.path.join(restart_dir, "checkpoints")
    return {"records": records, "checkpoints": checkpoints,
            "checkpoint_entries": set(os.listdir(checkpoints)) if os.path.isdir(checkpoints) else None}
 
 
def restore_continuation_records(run_dir: str, saved: dict, revision: str):
    """!
    @brief Undo a refused continuation's staging: restore its records, drop its revision.
    @details Removes the restart checkpoints staging materialized; everything else a
             continuation stages, including pinned executables, lives in the revision
             directory, so removing it leaves the run as it was.
    @param[in] run_dir Existing run directory.
    @param[in] saved State returned by capture_continuation_records().
    @param[in] revision Configuration revision the refused staging created.
    """
    checkpoints, before = saved["checkpoints"], saved["checkpoint_entries"]
    if os.path.isdir(checkpoints):
        for entry in set(os.listdir(checkpoints)) - (before or set()):
            shutil.rmtree(os.path.join(checkpoints, entry), ignore_errors=True)
        if before is None and not os.listdir(checkpoints):
            os.rmdir(checkpoints)
    for relative, content in saved["records"].items():
        path = os.path.join(run_dir, *relative.split("/"))
        if content is None:
            if os.path.isfile(path):
                os.remove(path)
        else:
            with open(path, "wb") as stream:
                stream.write(content)
    shutil.rmtree(os.path.join(run_dir, "config", "history", revision), ignore_errors=True)
 
 
def load_active_run_configuration(run_dir: str) -> dict:
    """!
    @brief Load the active immutable configuration revision for a run.
    @param[in] run_dir Run directory.
    @return Role-to-absolute-path mapping.
    """
    config_root = os.path.join(os.path.abspath(run_dir), "config")
    active = _read_json_if_exists(os.path.join(config_root, "active.json"))
    if isinstance(active, dict) and isinstance(active.get("files"), dict):
        return {
            role: os.path.join(run_dir, *relative.split("/"))
            for role, relative in active["files"].items()
            if isinstance(relative, str)
        }
    return {
        role: os.path.join(config_root, f"{role}.yml")
        for role in ("case", "solver", "monitor", "cluster")
        if os.path.isfile(os.path.join(config_root, f"{role}.yml"))
    }
 
 
#: Native executables a run launches, and therefore the ones a run pins.
RUN_EXECUTABLE_NAMES = ("simulator", "postprocessor")
 
 
def load_run_executables(run_dir: str) -> dict:
    """!
    @brief Return the executables a run is pinned to, as recorded by its active configuration.
    @param[in] run_dir Run directory.
    @return Mapping of executable name to its recorded entry, with `path` made absolute;
            empty when the run launches the installation's executables.
    """
    active = _read_json_if_exists(os.path.join(os.path.abspath(run_dir), "config", "active.json"))
    recorded = active.get("executables") if isinstance(active, dict) else None
    if not isinstance(recorded, dict):
        return {}
    pinned = {}
    for name, entry in recorded.items():
        if isinstance(entry, dict) and isinstance(entry.get("path"), str):
            pinned[name] = dict(entry, path=os.path.join(os.path.abspath(run_dir), *entry["path"].split("/")))
    return pinned
 
 
def run_executable_path(run_dir: "str | None", name: str) -> str:
    """!
    @brief Resolve the executable a run launches: its pinned copy, else the installation's.
    @param[in] run_dir Run directory, or None when no run exists yet.
    @param[in] name `simulator` or `postprocessor`.
    @return Absolute executable path.
    @throws ValueError when the run records a pinned copy that is no longer on disk.
    """
    pinned = load_run_executables(run_dir).get(name) if run_dir else None
    if not pinned:
        return resolve_runtime_executable(name)
    if not os.path.isfile(pinned["path"]):
        raise ValueError(
            f"{run_dir} is pinned to {pinned['path']}, which no longer exists. Restore it "
            "from the run's archive, or re-pin with --pin-executables to run the current build."
        )
    return pinned["path"]
 
 
def pin_run_executables(run_dir: str, revision: str) -> dict:
    """!
    @brief Copy the installation's executables into a run's configuration revision.
 
    @details The installation's `bin/` is rebuilt in place, so a job that resolves its
             executable there when it starts runs whatever was built last, not what was
             staged. The copy lives under `config/`, which storage retains as essential
             and the solver refuses to write into, and `active.json` records it so every
             later stage of the run - continuation, post-processing - launches the same
             build. Each copy is written beside its destination and renamed into place.
    @param[in] run_dir Run directory.
    @param[in] revision Active configuration revision (`initial` or a continuation id).
    @return Recorded executables mapping, keyed by executable name; an executable that
            has not been built is left unpinned with a warning, as staging treats it today.
    """
    run_root = os.path.abspath(run_dir)
    config_root = os.path.join(run_root, "config")
    target = (os.path.join(config_root, "bin") if revision == "initial"
              else os.path.join(config_root, "history", revision, "bin"))
    recorded = {}
    for name in RUN_EXECUTABLE_NAMES:
        source = resolve_runtime_executable(name)
        if not os.path.isfile(source):
            print(f"[WARNING] {name} is not built at {source}, so it is not pinned; a stage that "
                  "launches it will use whatever is there when it starts.", file=sys.stderr)
            continue
        os.makedirs(target, exist_ok=True)
        destination = os.path.join(target, name)
        partial = destination + ".partial"
        shutil.copy2(source, partial)
        os.replace(partial, destination)
        identity = read_binary_build_identity(destination)
        recorded[name] = {
            "path": os.path.relpath(destination, run_root).replace(os.sep, "/"),
            "pinned_from": source,
            "sha256": _file_sha256(destination),
            "build_id": identity.get("build_id"),
            "version_line": identity.get("version_line"),
            "identity_reason": None if identity.get("available") else identity.get("reason"),
        }
    if not recorded:
        return {}
    active_path = os.path.join(config_root, "active.json")
    active = _read_json_if_exists(active_path) or {"schema_version": 1, "revision": revision, "files": {}}
    active["executables"] = recorded
    active["updated_at"] = datetime.now().astimezone().isoformat()
    write_json_file(active_path, active)
    return recorded
 
 
def plan_run_executable_paths(run_dir: str, args, workspace_root: "str | None") -> dict:
    """!
    @brief Predict, without writing, which executables staging would give a run.
    @details Mirrors `apply_run_executable_pinning()` for `run --dry-run`: an existing
             pin is kept unless re-pinned, a new pin lands in the configuration revision
             staging would create, and otherwise the installation's executables run.
    @param[in] run_dir Run directory the plan targets.
    @param[in] args Parsed command arguments.
    @param[in] workspace_root Owning workspace, or None.
    @return Mapping with `pinning` (`kept`, `new`, or `none`) and per-executable `paths`.
    """
    existing = load_run_executables(run_dir) if os.path.isdir(run_dir) else {}
    if existing and getattr(args, "pin_executables", None) is not True:
        return {"pinning": "kept", "paths": {name: entry["path"] for name, entry in existing.items()}}
    if resolve_executable_pinning(args, workspace_root):
        revision_root = (os.path.join(run_dir, "config") if not existing
                         and not getattr(args, "continue_run", False)
                         else os.path.join(run_dir, "config", "history", "<new-revision>"))
        return {"pinning": "new",
                "paths": {name: os.path.join(revision_root, "bin", name) for name in RUN_EXECUTABLE_NAMES}}
    return {"pinning": "none",
            "paths": {name: resolve_runtime_executable(name) for name in RUN_EXECUTABLE_NAMES}}
 
 
def resolve_executable_pinning(args, workspace_root: "str | None") -> bool:
    """!
    @brief Decide whether staging pins the installation's executables into the run.
    @details Pinning is opt-in: an explicit `--pin-executables`/`--no-pin-executables`
             wins, then the workspace's `reproducibility.pin_executables`. Unpinned jobs
             are still protected by the job-start identity check, which stops a job whose
             executable was rebuilt after staging instead of running the new build.
    @param[in] args Parsed command arguments.
    @param[in] workspace_root Owning workspace, or None.
    @return True to pin, False not to.
    """
    explicit = getattr(args, "pin_executables", None)
    if explicit is not None:
        return bool(explicit)
    if workspace_root:
        policy = load_workspace_config(workspace_root).get("reproducibility") or {}
        if isinstance(policy, dict):
            return bool(policy.get("pin_executables"))
    return False
 
 
def apply_run_executable_pinning(run_dir: str, revision: str, args,
                                 workspace_root: "str | None") -> dict:
    """!
    @brief Pin, keep, or refuse the run's executables before anything records them.
    @details A run already pinned keeps its build unless the caller explicitly re-pins,
             so a continuation or post-processing pass cannot silently switch builds.
             Refusing `--no-pin-executables` on a pinned run keeps the run's records
             describing one build rather than a pin nobody launched.
    @param[in] run_dir Run directory.
    @param[in] revision Active configuration revision.
    @param[in] args Parsed command arguments.
    @param[in] workspace_root Owning workspace, or None.
    @return The run's pinned executables; empty when it launches the installation's.
    @throws ValueError when `--no-pin-executables` is given for a pinned run.
    """
    explicit = getattr(args, "pin_executables", None)
    existing = load_run_executables(run_dir)
    if existing and explicit is not True:
        if explicit is False:
            build = existing.get("simulator", {}).get("build_id") or "a pinned build"
            raise ValueError(
                f"{run_dir} is pinned to {build}. --no-pin-executables would launch the "
                "installation's build instead while the run still records the pin; re-pin "
                "with --pin-executables to move this run to the current build."
            )
        build = existing.get("simulator", {}).get("build_id") or "unknown build"
        print(f"[INFO] Launching the run's pinned executables ({build}).")
        return existing
    if not resolve_executable_pinning(args, workspace_root):
        return {}
    recorded = pin_run_executables(run_dir, revision)
    if not recorded:
        return {}
    first = next(iter(recorded.values()))
    build = first.get("build_id") or "build identity unavailable"
    print(f"[INFO] Pinned {', '.join(sorted(recorded))} into "
          f"{os.path.dirname(first['path'])}/ ({build}).")
    return load_run_executables(run_dir)
 
 
def archive_active_generated_configuration(run_dir: str, paths: list) -> dict:
    """!
    @brief Preserve generated control sidecars beside a continuation's YAML revision.
    @param[in] run_dir Owning run.
    @param[in] paths Generated control and sidecar paths.
    @return Updated active configuration record.
    """
    config_root = os.path.join(os.path.abspath(run_dir), "config")
    active_path = os.path.join(config_root, "active.json")
    active = _read_json_if_exists(active_path) or {"schema_version": 1, "revision": "initial", "files": {}}
    revision = active.get("revision", "initial")
    target_root = config_root if revision == "initial" else os.path.join(config_root, "history", revision)
    os.makedirs(target_root, exist_ok=True)
    files = active.setdefault("files", {})
    for source in paths:
        if not source or not os.path.isfile(source):
            continue
        source = os.path.abspath(source)
        destination = os.path.join(target_root, os.path.basename(source))
        if source != destination:
            shutil.copy2(source, destination)
        relative = os.path.relpath(destination, run_dir).replace(os.sep, "/")
        if destination.endswith(".control"):
            files["control"] = relative
        else:
            files.setdefault("generated", []).append(relative)
    active["updated_at"] = datetime.now().astimezone().isoformat()
    write_json_file(active_path, active)
    return active
 
 
#: Storage states in which a run's heavy payload is no longer wholly local. A component
#: absent under one of these was archived, not skipped.
STORAGE_OFFLOADED_STATES = frozenset({"COLD", "PARTIAL"})
 
#: Lifecycle states a run component can be in, as reported by the run manifest.
RUN_COMPONENT_STATES = (
    "not_requested", "planned", "running", "partial", "complete", "failed", "offloaded",
)
 
#: Run components, their canonical home, and the retention class storage applies.
RUN_COMPONENT_LAYOUT = (
    ("configuration", "config", "essential"),
    ("inputs", "inputs", "essential"),
    ("checkpoints", "output/checkpoints", "policy"),
    ("analysis", "output/analysis", "derived"),
    ("field_statistics", "output/analysis/statistics", "derived"),
    ("spectra", "output/analysis/spectra", "derived"),
    ("visualization", "output/visualization", "derived"),
    ("logs", "logs", "essential"),
    ("scheduler", "scheduler", "essential"),
)
 
 
def _run_component_states(run_dir: str, stages_requested: dict) -> dict:
    """!
    @brief Report each run component's home, retention class, and lifecycle state.
 
    @details The skeleton is created whole, so an empty directory says nothing about
             whether its contents were requested. This is where that question is
             answered, and it is answered for every component whether or not it ran.
    @param[in] run_dir Run directory being described.
    @param[in] stages_requested Mapping of requested stage names to booleans.
    @return Component name to `{path, retention, state}` mapping.
    """
    marker = storage_state_summary(run_dir) if os.path.isdir(run_dir) else {"state": "LOCAL"}
    offloaded = marker.get("state") in STORAGE_OFFLOADED_STATES
    solve_requested = bool(stages_requested.get("solve"))
    post_requested = bool(stages_requested.get("post_process"))
    requested = {
        "configuration": True,
        "inputs": True,
        "logs": True,
        "scheduler": True,
        "checkpoints": solve_requested,
        "analysis": post_requested,
        "field_statistics": post_requested,
        "spectra": post_requested,
        "visualization": post_requested,
    }
    components = {}
    for name, relative, retention in RUN_COMPONENT_LAYOUT:
        path = os.path.join(run_dir, *relative.split("/"))
        populated = False
        if os.path.isdir(path):
            populated = any(files for _root, _dirs, files in os.walk(path))
        if populated:
            state = "offloaded" if offloaded and retention != "essential" else "complete"
        elif not requested.get(name, False):
            state = "not_requested"
        elif offloaded:
            state = "offloaded"
        else:
            state = "planned"
        components[name] = {"path": relative, "retention": retention, "state": state}
    return components
 
 
def build_run_lineage(parent_run_dir: str, checkpoint_step: int, *, workspace_root=None,
                      statistics_state=None, requested_source=None) -> dict:
    """!
    @brief Record which run and which checkpoint a branched run was started from.
 
    @details Without this a branch is indistinguishable from a fresh run: the copied
             bundle under `inputs/restart/` carries the parent's geometry and software
             identity but never says which run produced it, so the trajectory a result
             belongs to cannot be reconstructed after the fact.
 
             The parent's own manifest is asked for its identity rather than its
             directory name, so a parent that was renamed or restored under another
             name is still named correctly here.
    @param[in] parent_run_dir Absolute path to the run being branched from.
    @param[in] checkpoint_step Checkpoint step the branch starts from.
    @param[in] workspace_root Optional workspace root, to record a portable path.
    @param[in] statistics_state Resolved field-statistics decision for the branch.
    @param[in] requested_source What the user asked for, e.g. "latest" or a path.
    @return JSON-serializable lineage record.
    """
    parent_identity = read_artifact_identity(parent_run_dir)
    return {
        "relationship": "branch",
        "parent_run_id": parent_identity["run_id"],
        "parent_study_id": parent_identity["study_id"] if parent_identity["case_id"] else None,
        "parent_case_id": parent_identity["case_id"],
        "parent_identity_source": parent_identity["identity_source"],
        "parent_path": _relative_to_workspace(parent_run_dir, workspace_root),
        "checkpoint_step": int(checkpoint_step),
        "statistics_state": statistics_state,
        "requested_source": requested_source,
        "recorded_at": datetime.now().astimezone().isoformat(),
    }
 
 
def build_run_manifest(run_dir: str, run_id: str, *, workspace_root=None,
                       launch_mode: str = "local", num_procs: int = 1,
                       post_num_procs: int = 1, stages_requested=None,
                       stages_completed=None, inputs=None, asset_lock=None,
                       submission=None, lineage=None, artifact_type: str = "run",
                       study_id=None, case_id=None) -> dict:
    """!
    @brief Build the authoritative run identity, topology, and lifecycle manifest.
    @param[in] run_dir Owning run directory.
    @param[in] run_id Stable run identity.
    @param[in] workspace_root Optional initialized workspace root.
    @param[in] launch_mode Local or scheduler-backed launch mode.
    @param[in] num_procs Effective solver process count.
    @param[in] post_num_procs Effective post-process count.
    @param[in] stages_requested Requested stage mapping.
    @param[in] stages_completed Completed or submitted stage names.
    @param[in] inputs Active configuration identities.
    @param[in] asset_lock Resolved run asset lock.
    @param[in] submission Scheduler submission metadata.
    @param[in] lineage Where this run's initial state came from; see `build_run_lineage()`.
    @param[in] artifact_type "run" for a standalone run, "study-case" for a study member.
    @param[in] study_id Owning study identity, for a study member.
    @param[in] case_id Member identity within its study.
    @return JSON-serializable run manifest.
    """
    existing = _read_json_if_exists(os.path.join(run_dir, "manifest.json")) or {}
    created_at = existing.get("created_at") or datetime.now().astimezone().isoformat()
    # The manifest describes the run, not the latest invocation: a post-only pass over a
    # solved run keeps the solve it records, and each stage keeps the rank count it ran on.
    requested_now = dict(stages_requested or {})
    stages_requested = {stage: bool(requested_now.get(stage) or (existing.get("stages_requested") or {}).get(stage))
                        for stage in {**(existing.get("stages_requested") or {}), **requested_now}}
    stages_completed = list(dict.fromkeys(
        list(existing.get("stages_completed_or_submitted") or []) + list(stages_completed or [])))
    if not requested_now.get("solve") and "solver_num_procs" in existing:
        num_procs = existing["solver_num_procs"]
    if not requested_now.get("post_process") and "post_num_procs" in existing:
        post_num_procs = existing["post_num_procs"]
    payload = {
        "schema_version": RUN_MANIFEST_SCHEMA_VERSION,
        "artifact_type": artifact_type,
        "run_id": run_id,
        "study_id": study_id,
        "case_id": case_id,
        "created_at": created_at,
        "updated_at": datetime.now().astimezone().isoformat(),
        "workspace": (
            (load_workspace_config(workspace_root).get("workspace") or {})
            if workspace_root else None
        ),
        "software": dict(picurv_build()),
        # The conductor's identity says which source staged the run; the binaries'
        # says which build produced its checkpoints. They can differ - an edited C
        # tree that was never rebuilt - so provenance records both.
        "binaries": runtime_build_identities(run_dir=run_dir),
        "launch_mode": launch_mode,
        "num_procs": num_procs,
        "solver_num_procs": num_procs,
        "post_num_procs": post_num_procs,
        "stages_requested": stages_requested or {},
        "stages_completed_or_submitted": stages_completed or [],
        "inputs": inputs or {},
        "paths": dict(CANONICAL_RUN_PATHS),
        # Where the run lived when its files were generated; adopt_relocated_artifact()
        # compares it with where the run is now.
        "root_path": os.path.abspath(run_dir),
        # Fixed schema, every component present whatever happened, so a reader never
        # has to distinguish "absent because it was not asked for" from "absent because
        # it failed" by looking for empty directories.
        "components": _run_component_states(run_dir, stages_requested or {}),
        "assets": (asset_lock or {}).get("assets", {}),
        "runtime_providers": (asset_lock or {}).get("runtime_providers", {}),
        # Always present, so a reader distinguishes "this run began from nothing" from
        # "this manifest predates lineage" by the value rather than by the key's absence.
        # A re-staged continuation keeps the lineage recorded when the run was created:
        # what a run branched from does not change because it was resumed.
        "lineage": lineage or existing.get("lineage") or {"relationship": "root"},
        "submission": submission or {},
    }
    return payload
 
 
def _recorded_run_root(run_dir: str):
    """!
    @brief Return the location a run's generated files refer to.
    @details Runs staged before the manifest recorded `root_path` are read from the
             active control file, whose generated input paths all start at the run root.
    @param[in] run_dir Current run directory.
    @return Recorded absolute root, or None when it cannot be determined.
    """
    manifest = _read_json_if_exists(os.path.join(run_dir, "manifest.json")) or {}
    if manifest.get("root_path"):
        return manifest["root_path"]
    control = auto_identify_run_inputs(os.path.join(run_dir, CANONICAL_RUN_PATHS["config"]))[2]
    if not (control and os.path.isfile(control)):
        return None
    markers = tuple(f"/{CANONICAL_RUN_PATHS[key]}/" for key in ("config", "inputs"))
    with open(control, "r", encoding="utf-8", errors="replace") as stream:
        for line in stream:
            for token in line.split()[1:]:
                for marker in markers:
                    if not (token.startswith("/") and marker in token):
                        continue
                    candidate, rest = token.split(marker, 1)
                    # Only a path that names a file of this run identifies its old root;
                    # an external input that merely contains the same segment does not.
                    if os.path.exists(os.path.join(run_dir, marker.strip("/"), rest)):
                        return candidate
    return None
 
 
def adopt_relocated_artifact(root: str, kind: str = "run", dry_run: bool = False) -> int:
    """!
    @brief Point a moved run's or study's generated files at where it now lives.
    @details Generated control files, recipes, scheduler scripts, and case indexes hold
             absolute paths, so a run or study moved or copied to another directory would
             otherwise launch against its old location. The rewrite is the one a
             relocated storage restore applies, after which the recorded root is updated.
    @param[in] root Current run or study directory.
    @param[in] kind "run" or "study".
    @param[in] dry_run Report the relocation without rewriting anything.
    @return Number of files rewritten (0 when the artifact has not moved).
    """
    root = os.path.abspath(root)
    if kind == "study":
        manifest_path = os.path.join(root, "study_manifest.json")
        recorded = ((_read_json_if_exists(manifest_path) or {}).get("paths") or {}).get("study_dir")
    else:
        manifest_path = os.path.join(root, "manifest.json")
        recorded = _recorded_run_root(root)
    if not recorded or os.path.realpath(recorded) == os.path.realpath(root) or recorded == root:
        return 0
    if dry_run:
        print(f"[WARNING] This {kind} was moved from {recorded}; a real invocation first updates "
              "its generated files to the new location.", file=sys.stderr)
        return 0
    changed = _rebase_restored_text_paths(root, [(recorded, root)])
    manifest = _read_json_if_exists(manifest_path)
    if isinstance(manifest, dict):
        if kind == "study":
            manifest.setdefault("paths", {})["study_dir"] = root
        else:
            manifest["root_path"] = root
        write_json_file(manifest_path, manifest)
    print(f"[INFO] This {kind} was moved from {recorded}; updated {len(changed)} generated "
          "file(s) to its new location.")
    return len(changed)
 
 
def _checkpoint_bundle_path(source_dir: str, step: int) -> str:
    """!
    @brief Resolve a run/output root or an exact checkpoint bundle.
    @param[in] source_dir Run/output root or exact bundle path.
    @param[in] step Checkpoint step to resolve.
    @return Absolute path to the checkpoint bundle.
    """
    source_dir = os.path.abspath(source_dir)
    if os.path.isfile(os.path.join(source_dir, "checkpoint.meta")):
        return source_dir
    return os.path.join(source_dir, "checkpoints", f"step_{step:0{CHECKPOINT_STEP_WIDTH}d}")
 
 
def _read_checkpoint_options(metadata_path: str) -> dict:
    """!
    @brief Parse the deliberately small PETSc-options checkpoint manifest.
    @param[in] metadata_path Path to checkpoint.meta.
    @return Mapping of option names to scalar text values.
    """
    options = {}
    with open(metadata_path, "r", encoding="utf-8") as stream:
        for line_number, raw_line in enumerate(stream, start=1):
            tokens = shlex.split(raw_line, comments=True, posix=True)
            if not tokens:
                continue
            if len(tokens) != 2 or not tokens[0].startswith("-"):
                raise ValueError(
                    f"Invalid checkpoint metadata line {line_number} in {metadata_path}."
                )
            key = tokens[0][1:]
            if key in options:
                raise ValueError(f"Duplicate checkpoint metadata key '-{key}' in {metadata_path}.")
            options[key] = tokens[1]
    return options
 
 
class CheckpointIndexWidthError(ValueError):
    """!
    @brief A committed checkpoint written by a PETSc of the other index width than the driven solver's.
    @details Raised instead of a plain ValueError so a scan for usable checkpoints reports it
             rather than skipping the checkpoint as if it were incomplete.
    """
 
 
def validate_committed_checkpoint(source_dir: str, step: int, require_particles: bool = False) -> dict:
    """!
    @brief Validate one committed bundle using the same manifest contract as C.
    @param[in] source_dir Run/output root or exact bundle path.
    @param[in] step Expected checkpoint step.
    @param[in] require_particles Whether particle restart payloads are required.
    @return Validated bundle path, metadata, and payload inventory.
    """
    bundle = _checkpoint_bundle_path(source_dir, step)
    metadata_path = os.path.join(bundle, "checkpoint.meta")
    commit_path = os.path.join(bundle, "COMMITTED")
    if not os.path.isfile(metadata_path) or not os.path.isfile(commit_path):
        raise ValueError(f"No committed checkpoint for step {step}: {bundle}")
 
    with open(commit_path, "r", encoding="ascii") as stream:
        expected_digest = stream.read().strip()
    if not re.fullmatch(r"[0-9a-fA-F]{64}", expected_digest):
        raise ValueError(f"Invalid checkpoint commit marker: {commit_path}")
    with open(metadata_path, "rb") as stream:
        actual_digest = hashlib.sha256(stream.read()).hexdigest()
    if actual_digest.lower() != expected_digest.lower():
        raise ValueError(f"Checkpoint metadata hash mismatch: {bundle}")
 
    options = _read_checkpoint_options(metadata_path)
    try:
        saved_version = int(options.get("checkpoint_version", "-1"))
        saved_step = int(options.get("checkpoint_step", "-1"))
        payload_count = int(options.get("checkpoint_payload_count", "-1"))
        particle_count = int(options.get("checkpoint_particle_count", "-1"))
        block_count = int(options.get("checkpoint_block_count", "-1"))
        float(options["checkpoint_time"])
    except (KeyError, TypeError, ValueError) as exc:
        raise ValueError(f"Checkpoint metadata is incomplete or malformed: {metadata_path}") from exc
    if options.get("checkpoint_format") != CHECKPOINT_FORMAT or saved_version != CHECKPOINT_VERSION:
        raise ValueError(f"Unsupported checkpoint format/version: {metadata_path}")
    if saved_step != step:
        raise ValueError(f"Checkpoint records step {saved_step}, expected {step}: {bundle}")
    # Checked once the command has selected its build; restart resolution validates before
    # selecting, and selection then takes this checkpoint's width, so the two agree.
    saved_index_bytes = int(options.get("checkpoint_petsc_index_bytes", "4"))
    solver_index_bytes = _SELECTED_PETSC_INDEX_BYTES or saved_index_bytes
    if saved_index_bytes != solver_index_bytes:
        raise CheckpointIndexWidthError(
            f"Checkpoint {bundle} was written by a PETSc with {8 * saved_index_bytes}-bit indices, but this "
            f"picurv drives a {8 * solver_index_bytes}-bit-index build ({resolve_runtime_executable('simulator')}). "
            f"Restart or post-process it with the PICurv built on a {8 * saved_index_bytes}-bit-index PETSc.")
    if payload_count <= 0 or particle_count < 0 or block_count <= 0:
        raise ValueError(f"Checkpoint inventory counts are invalid: {metadata_path}")
 
    payloads = []
    for index in range(payload_count):
        prefix = f"checkpoint_payload_{index}_"
        relative_path = options.get(prefix + "path")
        try:
            expected_bytes = int(options[prefix + "bytes"])
        except (KeyError, TypeError, ValueError) as exc:
            raise ValueError(f"Checkpoint payload {index} has invalid metadata: {metadata_path}") from exc
        if not relative_path or os.path.isabs(relative_path) or ".." in relative_path.split("/"):
            raise ValueError(f"Checkpoint payload {index} has an unsafe path: {relative_path!r}")
        payload_path = os.path.join(bundle, *relative_path.split("/"))
        if not os.path.isfile(payload_path) or os.path.getsize(payload_path) != expected_bytes:
            raise ValueError(f"Checkpoint payload is missing or truncated: {payload_path}")
        payloads.append({
            "path": relative_path,
            "kind": options.get(prefix + "kind"),
            "field": options.get(prefix + "field"),
            "block": options.get(prefix + "block"),
        })
 
    for block in range(block_count):
        fields = {
            item["field"] for item in payloads
            if item["kind"] == "eulerian" and item["block"] == str(block)
        }
        missing = CHECKPOINT_REQUIRED_EULERIAN_FIELDS - fields
        if missing:
            raise ValueError(
                f"Checkpoint block {block} is missing required Eulerian field(s): "
                f"{', '.join(sorted(missing))}."
            )
    particle_payloads = [item for item in payloads if item["kind"] == "particle"]
    has_particles = options.get("checkpoint_particles", "false").lower() == "true"
    if (not has_particles and particle_count != 0) or (has_particles and not particle_payloads):
        raise ValueError(f"Checkpoint particle inventory is inconsistent: {metadata_path}")
    if require_particles and not has_particles:
        raise ValueError(f"Checkpoint step {step} does not contain particle state: {bundle}")
 
    return {
        "bundle": bundle,
        "metadata": options,
        "payloads": payloads,
        "has_particles": has_particles,
        "particle_count": particle_count,
    }
 
 
def _scan_committed_checkpoint_steps(source_dir: str, require_particles: bool = False) -> "set[int]":
    """!
    @brief Return only fully validated, committed checkpoint steps.
    @param[in] source_dir Run/output root containing checkpoints.
    @param[in] require_particles Whether particle restart payloads are required.
    @return Set of valid committed step numbers.
    """
    checkpoints_dir = os.path.join(os.path.abspath(source_dir), "checkpoints")
    if not os.path.isdir(checkpoints_dir):
        return set()
    pattern = re.compile(rf"^step_(\d{{{CHECKPOINT_STEP_WIDTH}}})$")
    steps = set()
    for name in os.listdir(checkpoints_dir):
        match = pattern.fullmatch(name)
        if not match:
            continue
        step = int(match.group(1))
        try:
            validate_committed_checkpoint(source_dir, step, require_particles=require_particles)
        except CheckpointIndexWidthError:
            raise
        except ValueError:
            continue
        steps.add(step)
    return steps
 
 
def parse_slurm_time_limit_to_seconds(time_text: str) -> int:
    """!
    @brief Parse a Slurm time-limit string into total seconds.
    @param[in] time_text Argument passed to `parse_slurm_time_limit_to_seconds()`.
    @return Value returned by `parse_slurm_time_limit_to_seconds()`.
    """
    text = str(time_text).strip()
    if not text:
        raise ValueError("time limit cannot be empty")
 
    days = 0
    clock_text = text
    if "-" in text:
        day_text, clock_text = text.split("-", 1)
        if not day_text.isdigit():
            raise ValueError(f"invalid day field '{day_text}'")
        days = int(day_text)
        if not clock_text:
            raise ValueError("missing time portion after day field")
 
    parts = clock_text.split(":")
    if len(parts) > 3:
        raise ValueError(f"unsupported time format '{time_text}'")
    if any(part == "" for part in parts):
        raise ValueError(f"malformed time field '{time_text}'")
    if any(not part.isdigit() for part in parts):
        raise ValueError(f"non-numeric time field '{time_text}'")
 
    nums = [int(part) for part in parts]
    if days > 0:
        if len(nums) == 1:
            hours, minutes, seconds = nums[0], 0, 0
        elif len(nums) == 2:
            hours, minutes = nums
            seconds = 0
        else:
            hours, minutes, seconds = nums
    else:
        if len(nums) == 1:
            hours, minutes, seconds = 0, nums[0], 0
        elif len(nums) == 2:
            hours = 0
            minutes, seconds = nums
        else:
            hours, minutes, seconds = nums
 
    if minutes >= 60 or seconds >= 60:
        raise ValueError(f"minutes and seconds must be < 60 in '{time_text}'")
    if days == 0 and len(nums) == 3 and hours < 0:
        raise ValueError(f"hours must be non-negative in '{time_text}'")
 
    total_seconds = (((days * 24) + hours) * 60 + minutes) * 60 + seconds
    if total_seconds <= 0:
        raise ValueError("time limit must be positive")
    return total_seconds
 
 
def resolve_walltime_guard_policy(cluster_cfg: "dict | None") -> "dict | None":
    """!
    @brief Resolve the effective Slurm walltime-guard policy for generated solver jobs.
    @param[in] cluster_cfg Argument passed to `resolve_walltime_guard_policy()`.
    @return Value returned by `resolve_walltime_guard_policy()`.
    """
    if not isinstance(cluster_cfg, dict):
        return None
 
    scheduler = cluster_cfg.get("scheduler", {}) or {}
    if str(scheduler.get("type", "slurm")).lower() != "slurm":
        return None
 
    execution = cluster_cfg.get("execution", {}) or {}
    guard_cfg = execution.get("walltime_guard")
    if guard_cfg is None:
        guard_cfg = {}
    elif not isinstance(guard_cfg, dict):
        raise ValueError("execution.walltime_guard must be a mapping when provided")
 
    policy = copy.deepcopy(DEFAULT_WALLTIME_GUARD_POLICY)
    policy.update(guard_cfg)
    policy["enabled"] = bool(policy["enabled"])
    policy["warmup_steps"] = int(policy["warmup_steps"])
    policy["multiplier"] = float(policy["multiplier"])
    policy["min_seconds"] = float(policy["min_seconds"])
    policy["estimator_alpha"] = float(policy["estimator_alpha"])
    return policy
 
 
def build_walltime_guard_exports(cluster_cfg: "dict | None") -> dict:
    """!
    @brief Build shell-evaluated environment exports for the runtime walltime guard.
    @param[in] cluster_cfg Argument passed to `build_walltime_guard_exports()`.
    @return Value returned by `build_walltime_guard_exports()`.
    """
    policy = resolve_walltime_guard_policy(cluster_cfg)
    if not policy or not policy.get("enabled", False):
        return {}
    walltime_limit_seconds = parse_slurm_time_limit_to_seconds(cluster_cfg.get("resources", {}).get("time", ""))
    return {
        WALLTIME_GUARD_ENV_JOB_START_EPOCH: "$(date +%s)",
        WALLTIME_GUARD_ENV_LIMIT_SECONDS: str(walltime_limit_seconds),
    }
 
#: PetscInt width of the build the current command drives, chosen once per command by
#: `select_petsc_index_bytes()`; None keeps the default 32-bit `simulator`/`postprocessor`.
_SELECTED_PETSC_INDEX_BYTES = None
 
 
def resolve_runtime_executable(executable_name: str) -> str:
    """!
    @brief Resolve solver/post executable path, preferring local sibling binaries.
    @details A command that selected the 64-bit-index build resolves `simulator64` and
             `postprocessor64`, which `make INDEX_BITS=64` installs beside the 32-bit pair.
    @param[in] executable_name `simulator` or `postprocessor`.
    @return Absolute executable path.
    """
    if _SELECTED_PETSC_INDEX_BYTES == 8 and executable_name in RUN_EXECUTABLE_NAMES:
        executable_name += "64"
    local_candidate = os.path.join(INVOKED_SCRIPT_DIR, executable_name)
    if os.path.isfile(local_candidate):
        return os.path.abspath(local_candidate)
    return os.path.join(DEFAULT_BIN_DIR, executable_name)
 
 
#: Identity a native executable prints for `--version`:
#: `<name> <release>[.dev<N>]+g<commit>[.dirty]`; executables built before the `.dev<N>` stamp omit it.
_BINARY_VERSION_PATTERN = re.compile(
    r"^(?P<name>\S+)\s+(?P<version>(?P<release>[^+\s]+?)(?:\.dev\d+)?)\+g(?P<commit>[0-9a-f]+)(?P<dirty>\.dirty)?\s*$"
)
#: Second `--version` line: the PETSc the executable was compiled against (src/setup.c).
_BINARY_PETSC_PATTERN = re.compile(
    r"^petsc (?P<version>\S+) (?P<mode>debug|optimized)(?: (?P<indices>int32|int64))? (?P<arch>\S*) (?P<dir>.*)$"
)
#: Bytes of a PetscInt for each index width a PETSc stamp can name.
PETSC_INDEX_BYTES = {"int32": 4, "int64": 8}
#: Marker in front of the same text inside the executable, readable without running it.
_BINARY_PETSC_STAMP_MARKER = b"PICURV_PETSC_BUILD:"
#: Marker of the build-identity stamp in an executable (src/setup.c, picurv_build_stamp).
_BINARY_BUILD_STAMP_MARKER = b"PICURV_BUILD:"
 
 
def _parse_binary_petsc_line(line: str) -> "dict | None":
    """!
    @brief Parse the PETSc build line a native executable reports.
    @param[in] line `petsc <version> <debug|optimized> [int32|int64] <arch> <dir>`.
    @return Mapping with version, mode, indices, arch, and dir, or None when the line is not
            one. A binary built before the index width was stamped is 32-bit; `indices_stamped`
            records whether the line named it, so the line can be rebuilt exactly.
    """
    match = _BINARY_PETSC_PATTERN.match((line or "").strip())
    if not match:
        return None
    parsed = {key: match.group(key) for key in ("version", "mode", "arch", "dir")}
    parsed["indices_stamped"] = match.group("indices") is not None
    parsed["indices"] = match.group("indices") or "int32"
    return parsed
 
 
def read_binary_petsc_stamp(executable_path: str) -> "dict | None":
    """!
    @brief Read the PETSc build stamp from an executable's bytes, without running it.
    @details A binary built against one PETSc and started against another cannot run
             `--version` at all, which is exactly when knowing its PETSc matters.
    @param[in] executable_path Path to `simulator` or `postprocessor`.
    @return The parsed stamp, or None when the file carries none (built before it existed).
    """
    try:
        with open(executable_path, "rb") as stream:
            data = stream.read()
    except OSError:
        return None
    start = data.find(_BINARY_PETSC_STAMP_MARKER)
    if start < 0:
        return None
    start += len(_BINARY_PETSC_STAMP_MARKER)
    text = data[start:start + 4096].split(b"\0", 1)[0].split(b"\n", 1)[0]
    return _parse_binary_petsc_line(text.decode("utf-8", errors="replace"))
 
 
def resolved_petsc_library(executable_path: str) -> "str | None":
    """!
    @brief The PETSc shared library the dynamic loader would give this executable when picurv launches it.
    @details Uses `ldd` on the current shell's library path with the executable's own PETSc
             lib/ first, as launches and job scripts put it; returns None where `ldd` is
             unavailable or the executable links PETSc statically.
    @param[in] executable_path Path to `simulator` or `postprocessor`.
    @return Absolute library path, `not found`, or None.
    """
    ldd = shutil.which("ldd")
    if not ldd:
        return None
    env = dict(os.environ)
    library_dir = executable_petsc_library_dir(executable_path)
    if library_dir:
        env["LD_LIBRARY_PATH"] = os.pathsep.join(filter(None, (library_dir, env.get("LD_LIBRARY_PATH"))))
    try:
        result = subprocess.run([ldd, executable_path], text=True, capture_output=True,
                                timeout=20, check=False, env=env)
    except (OSError, subprocess.SubprocessError):
        return None
    for line in (result.stdout or "").splitlines():
        name, _, target = line.strip().partition("=>")
        if not name.strip().startswith("libpetsc"):
            continue
        target = target.strip()
        if target.startswith("not found"):
            return "not found"
        return target.split(" (")[0].strip() or None
    return None
 
 
def petsc_library_mismatch(petsc: "dict | None", library: "str | None") -> bool:
    """!
    @brief Whether the library the loader resolves lies outside the PETSc the binary was built against.
    @param[in] petsc Stamp from `read_binary_petsc_stamp()` or the `--version` line.
    @param[in] library Path from `resolved_petsc_library()`.
    @return True only when both are known and the library is not under the build's tree.
    """
    if not petsc or not petsc.get("dir") or not library:
        return False
    if library == "not found":
        return True
    build_root = os.path.realpath(os.path.join(petsc["dir"], petsc.get("arch") or ""))
    return not os.path.realpath(library).startswith(build_root.rstrip(os.sep) + os.sep)
 
 
def _read_binary_build_stamp(executable_path: str) -> "dict | None":
    """!
    @brief Read the build identity stamped into an executable's bytes, without running it.
    @details src/setup.c stores `PICURV_BUILD:<version> <commit> <dirty>` beside the PETSc
             stamp. Running `--version` on a login node starts the dynamic loader against a
             cold filesystem, tens of seconds; reading the file costs one read.
    @param[in] executable_path Path to `simulator` or `postprocessor`.
    @return The identity mapping `read_binary_build_identity()` returns, or None for a binary
            built before the stamp existed.
    """
    try:
        with open(executable_path, "rb") as stream:
            data = stream.read()
    except OSError:
        return None
    start = data.find(_BINARY_BUILD_STAMP_MARKER)
    if start < 0:
        return None
    fields = data[start + len(_BINARY_BUILD_STAMP_MARKER):start + 512].split(b"\0", 1)[0].decode(
        "utf-8", errors="replace").split()
    if len(fields) != 3 or not re.fullmatch(r"[0-9a-f]+", fields[1]) or fields[2] not in ("true", "false"):
        return None
    version, commit, dirty = fields[0], fields[1][:12], fields[2] == "true"
    release = re.sub(r"\.dev\d+$", "", version)
    petsc = read_binary_petsc_stamp(executable_path)
    if petsc is None:
        return None
    # Exactly what `--version` prints (src/setup.c), which the job-start check compares with.
    name = os.path.basename(executable_path)
    version_line = (f"{name} {version}+g{commit}{'.dirty' if dirty else ''}\n"
                    f"petsc {petsc['version']} {petsc['mode']}"
                    f"{' ' + petsc['indices'] if petsc.get('indices_stamped') else ''} {petsc['arch']} {petsc['dir']}")
    return {
        "available": True,
        "path": executable_path,
        "version_line": version_line,
        "release_version": release,
        "git_commit": commit,
        "dirty": dirty,
        "build_id": f"{version}+g{commit}{'.dirty' if dirty else ''}",
        "petsc": petsc,
        "identity_source": "stamp",
    }
 
 
def read_binary_build_identity(executable_path: str) -> dict:
    """!
    @brief Read the build identity a native executable was compiled with.
 
    @details The Makefile stamps the release, commit, and dirty state into the
             binaries, and they are written into every checkpoint manifest. Reading it
             back is what makes the run manifest's provenance a statement about the
             binary that ran rather than about whatever source happens to be checked
             out when the conductor is invoked.
    @param[in] executable_path Path to `simulator` or `postprocessor`.
    @return Identity mapping, or an `available: False` mapping when it cannot be read.
    """
    if not os.path.isfile(executable_path) or not os.access(executable_path, os.X_OK):
        return {"available": False, "reason": "not built", "path": executable_path}
    stamped = _read_binary_build_stamp(executable_path)
    if stamped is not None:
        return stamped
    try:
        result = subprocess.run(
            [executable_path, "--version"], text=True, capture_output=True, timeout=30,
        )
    except (OSError, subprocess.SubprocessError) as exc:
        return {"available": False, "reason": str(exc), "path": executable_path}
    if result.returncode != 0:
        # A binary that cannot start - typically its shared libraries are not loadable
        # in this shell - is not the same failure as one that predates the identity
        # flag, and recording it as such hides a broken staging environment.
        detail = (result.stderr or result.stdout or "").strip().splitlines()
        return {"available": False,
                "reason": f"--version exited {result.returncode}"
                          + (f": {detail[0]}" if detail else ""),
                "path": executable_path,
                "petsc": read_binary_petsc_stamp(executable_path)}
    lines = (result.stdout or "").strip().splitlines()
    match = _BINARY_VERSION_PATTERN.match(lines[0] if lines else "")
    if not match:
        # A binary from before the identity flag existed, or a wrapper that prints
        # something else. Recorded as unavailable rather than guessed at.
        return {"available": False, "reason": "no build identity reported",
                "path": executable_path}
    return {
        "available": True,
        "path": executable_path,
        "version_line": (result.stdout or "").strip(),
        "release_version": match.group("release"),
        "git_commit": match.group("commit"),
        "dirty": bool(match.group("dirty")),
        "build_id": (
            f"{match.group('version')}+g{match.group('commit')}"
            f"{'.dirty' if match.group('dirty') else ''}"
        ),
        "petsc": _parse_binary_petsc_line(lines[1]) if len(lines) > 1 else None,
    }
 
 
def runtime_build_identities(source_identity: "dict | None" = None,
                             run_dir: "str | None" = None) -> dict:
    """!
    @brief Read the build identity of every native executable a run would launch.
    @param[in] source_identity Source identity to compare against; defaults to the
                               identity this process computed at startup.
    @param[in] run_dir Run whose pinned executables are read; the installation's when None,
                       which also lists the 64-bit-index pair (`simulator64`,
                       `postprocessor64`) when it is built.
    @return Mapping of executable name to its identity, each carrying `matches_source`.
    """
    source_identity = source_identity or picurv_build()
    identities = {}
    source_commit = str(source_identity.get("git_commit") or "")
    paths = {name: run_executable_path(run_dir, name) for name in RUN_EXECUTABLE_NAMES}
    if run_dir is None and _SELECTED_PETSC_INDEX_BYTES is None:
        for name in RUN_EXECUTABLE_NAMES:
            wide = os.path.join(os.path.dirname(paths[name]), name + "64")
            if os.path.isfile(wide):
                paths[name + "64"] = wide
    for name, path in paths.items():
        identity = read_binary_build_identity(path)
        if identity.get("available"):
            # The stamped commit is abbreviated, so compare on the prefix it carries.
            identity["matches_source"] = bool(
                source_commit
                and source_commit.startswith(identity["git_commit"])
                and identity["dirty"] == bool(source_identity.get("dirty"))
            )
        identities[name] = identity
    return identities
 
 
def rebuild_command(name: str, identity: dict) -> str:
    """!
    @brief The command that rebuilds one native executable.
    @details The 64-bit-index pair needs `INDEX_BITS=64` and its own PETSc, named from the
             executable's PETSc stamp when it has one; a plain build makes the 32-bit pair.
    @param[in] name Executable name, such as `simulator64`.
    @param[in] identity Identity mapping from `read_binary_build_identity()`.
    @return Shell command text.
    """
    if not name.endswith("64"):
        return "picurv build"
    petsc = identity.get("petsc") or {}
    command = f"picurv build INDEX_BITS=64 PETSC_DIR={petsc.get('dir') or '<64-bit PETSc>'}"
    return command + (f" PETSC_ARCH={petsc['arch']}" if petsc.get("arch") else "")
 
 
def build_identity_problems(identities: dict, workspace_requirement=None,
                            source_identity: "dict | None" = None) -> list:
    """!
    @brief Report every reason the active build identity is not internally coherent.
 
    @details The conductor, the simulator, and the postprocessor are three artifacts
             that must agree before a run's provenance means anything. This states the
             disagreements rather than printing them, so `version status` can exit on
             them while ordinary staging only warns.
    @param[in] identities Mapping returned by `runtime_build_identities()`.
    @param[in] workspace_requirement Optional `software.picurv` constraint to check.
    @param[in] source_identity Source identity the executables must match; defaults to
                               the identity this process computed at startup.
    @return Human-readable problem descriptions; empty when the build is coherent.
    """
    source_identity = source_identity or picurv_build()
    problems = []
    for name, identity in sorted(identities.items()):
        if not identity.get("available"):
            problems.append(
                f"{name}: no build identity available ({identity.get('reason', 'unknown')}); "
                f"rebuild with '{rebuild_command(name, identity)}'."
            )
        elif not identity.get("matches_source"):
            problems.append(
                f"{name}: built from {identity['build_id']}, but the active source is "
                f"{source_identity['build_id']}; rebuild with '{rebuild_command(name, identity)}'."
            )
    if workspace_requirement not in (None, ""):
        try:
            from packaging.specifiers import SpecifierSet
            from packaging.version import Version
            requirement_text = str(workspace_requirement).strip()
            if not any(token in requirement_text for token in "<>=!~"):
                requirement_text = "==" + requirement_text
            satisfied = Version(PICURV_RELEASE_VERSION) in SpecifierSet(requirement_text)
        except Exception:
            problems.append(
                f"workspace: software.picurv={workspace_requirement!r} is not a valid "
                "version or version range."
            )
        else:
            if not satisfied:
                problems.append(
                    f"workspace: requires PICurv {workspace_requirement!r}, but the active "
                    f"release is {PICURV_RELEASE_VERSION}."
                )
    return problems
 
 
def warn_on_stale_runtime_binaries(identities: dict) -> list:
    """!
    @brief Report native executables whose build identity is not the active source.
    @details An executable whose identity cannot be read is reported too: the manifest
             would otherwise record "unavailable" for a run with no word at staging.
    @param[in] identities Mapping returned by `runtime_build_identities()`.
    @return Names of executables that disagree with the active source identity.
    """
    stale = [name for name, identity in sorted(identities.items())
             if identity.get("available") and not identity.get("matches_source")]
    for name in stale:
        print(
            f"[WARNING] {name} was built from {identities[name]['build_id']}, but the active "
            f"source is {picurv_build()['build_id']}. Checkpoints will record the binary's "
            f"identity, not the source's. Rebuild with '{rebuild_command(name, identities[name])}'.",
            file=sys.stderr,
        )
    for name, identity in sorted(identities.items()):
        if identity.get("available"):
            continue
        print(
            f"[WARNING] The build identity of {name} could not be read "
            f"({identity.get('reason', 'unknown')}); this run's manifest will not record "
            f"which build it used. Path: {identity.get('path')}",
            file=sys.stderr,
        )
    return stale
 
# Standardized error codes used for CLI/validation reporting.
ERROR_CODE_CLI_USAGE_INVALID = "CLI_USAGE_INVALID"
ERROR_CODE_CFG_MISSING_SECTION = "CFG_MISSING_SECTION"
ERROR_CODE_CFG_MISSING_KEY = "CFG_MISSING_KEY"
ERROR_CODE_CFG_INVALID_TYPE = "CFG_INVALID_TYPE"
ERROR_CODE_CFG_INVALID_VALUE = "CFG_INVALID_VALUE"
ERROR_CODE_CFG_FILE_NOT_FOUND = "CFG_FILE_NOT_FOUND"
ERROR_CODE_CFG_GRID_PARSE = "CFG_GRID_PARSE"
ERROR_CODE_CFG_INCONSISTENT_COMBO = "CFG_INCONSISTENT_COMBO"
ERROR_CODE_DEPENDENCY_MISSING = "DEPENDENCY_MISSING"
 
RESTART_RUN_DIR_REQUIRED_MESSAGE = (
    "--continue and --restart-from both require an existing run directory. "
    "Use --continue --run-dir <run_dir> to resume in place, or "
    "--restart-from <run_dir> to create a new run."
)
 
_ERROR_HINTS = {
    ERROR_CODE_CLI_USAGE_INVALID: "Run 'picurv <command> --help' to see valid argument combinations.",
    ERROR_CODE_CFG_MISSING_SECTION: "Add the missing section using examples/master_template/*.yml as reference.",
    ERROR_CODE_CFG_MISSING_KEY: "Add the missing key in the referenced YAML file.",
    ERROR_CODE_CFG_INVALID_TYPE: "Fix the value type to match the documented schema in docs/pages/14_Config_Contract.md.",
    ERROR_CODE_CFG_INVALID_VALUE: "Adjust the value to a supported range/enum from the config reference pages.",
    ERROR_CODE_CFG_FILE_NOT_FOUND: "Fix the path or create the missing file before running again.",
    ERROR_CODE_CFG_GRID_PARSE: "Validate grid file format and numeric payload (block count, dims, coordinates).",
    ERROR_CODE_CFG_INCONSISTENT_COMBO: "Fix conflicting options/keys so the configuration is internally consistent.",
    ERROR_CODE_DEPENDENCY_MISSING: "Install the named optional dependency for the Python interpreter used by picurv.",
}
#: Hint for a refused restart: the flags and the case key that choose its source and step.
_RESTART_HINT = ("Check --restart-from, --continue and --run-dir against the source run's committed "
                 "checkpoints and run_control.start_step in case.yml.")
#: Hint for a workflow refused because the payload it reads is in cold storage.
_STORAGE_RESTORE_HINT = ("Run the restore command in the message; 'picurv storage status --run-dir "
                         "<run>' shows what is local.")
#: Hint for a --study-dir that is not a study `picurv sweep` created.
_STUDY_DIR_HINT = "Pass a study directory that 'picurv sweep' created (studies/<study_id>)."
 
 
def _sanitize_error_field(value) -> str:
    """!
    @brief Normalize error fields into a single-line string.
    @param[in] value Argument passed to `_sanitize_error_field()`.
    @return Value returned by `_sanitize_error_field()`.
    """
    if value is None:
        return "-"
    text = str(value).strip()
    if not text:
        return "-"
    return " ".join(text.splitlines())
 
 
def emit_structured_error(code: str, key: str = "-", file_path: str = "-",
                          message: str = "", hint: str = None, stream=None):
    """!
    @brief Emit one standardized error line for tooling and users.
    @param[in] code Argument passed to `emit_structured_error()`.
    @param[in] key Argument passed to `emit_structured_error()`.
    @param[in] file_path Argument passed to `emit_structured_error()`.
    @param[in] message Argument passed to `emit_structured_error()`.
    @param[in] hint Argument passed to `emit_structured_error()`.
    @param[in] stream Argument passed to `emit_structured_error()`.
    """
    if stream is None:
        stream = sys.stderr
    resolved_hint = hint if hint is not None else _ERROR_HINTS.get(code, "-")
    print(
        f"ERROR {_sanitize_error_field(code)} | "
        f"key={_sanitize_error_field(key)} | "
        f"file={_sanitize_error_field(file_path)} | "
        f"message={_sanitize_error_field(message)} | "
        f"hint={_sanitize_error_field(resolved_hint)}",
        file=stream,
    )
 
 
def fail_cli_usage(message: str, hint: str = None):
    """!
    @brief Emit a structured CLI usage error and exit with code 2.
    @details Without a @p hint, the default names the command the user ran.
    @param[in] message Argument passed to `fail_cli_usage()`.
    @param[in] hint Argument passed to `fail_cli_usage()`.
    """
    command = next((token for token in sys.argv[1:] if not token.startswith("-")), "")
    emit_structured_error(
        ERROR_CODE_CLI_USAGE_INVALID,
        key="-",
        file_path="-",
        message=message,
        hint=hint or _ERROR_HINTS[ERROR_CODE_CLI_USAGE_INVALID].replace(
            "<command>", command if re.fullmatch(r"[a-z][a-z-]*", command) else "<command>"),
    )
    sys.exit(2)
 
 
def _split_error_file_and_message(raw_error: str):
    """!
    @brief Separate a validation error into its source-file and message fields when possible.
    @param[in] raw_error Validation error text, optionally beginning with a file path and colon.
    @return A pair containing the detected file path (or ``-``) and the message text.
    """
    text = str(raw_error).strip()
    match = re.match(r"^(?P<file>[^:]+):\s*(?P<msg>.+)$", text)
    if not match:
        return "-", text
    file_candidate = match.group("file").strip()
    msg = match.group("msg").strip()
    known_suffixes = (".yml", ".yaml", ".cfg", ".picgrid", ".control", ".run", ".txt")
    if "/" in file_candidate or file_candidate.endswith(known_suffixes):
        return file_candidate, msg
    return "-", text
 
 
def _extract_key_path(message: str) -> str:
    """!
    @brief Best-effort key-path extraction from free-form validation messages.
    @param[in] message Argument passed to `_extract_key_path()`.
    @return Value returned by `_extract_key_path()`.
    """
    dotted = re.search(r"\b([A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z0-9_\[\]-]+)+)\b", message)
    if dotted:
        return dotted.group(1)
 
    bracketed = re.search(r"\b([A-Za-z_][A-Za-z0-9_]*\[[^\]]+\](?:\[[^\]]+\])*)\b", message)
    if bracketed:
        return bracketed.group(1)
 
    quoted = re.findall(r"'([A-Za-z0-9_.\[\]-]+)'", message)
    for token in quoted:
        if "." in token or "[" in token or token.isidentifier():
            return token
    return "-"
 
 
def _classify_error_code(message: str) -> str:
    """!
    @brief Map existing validation/error messages to the standardized code set.
    @param[in] message Argument passed to `_classify_error_code()`.
    @return Value returned by `_classify_error_code()`.
    """
    msg = message.lower()
    if "missing required section" in msg:
        return ERROR_CODE_CFG_MISSING_SECTION
    if "missing required key" in msg or "missing key" in msg:
        return ERROR_CODE_CFG_MISSING_KEY
    if "not found" in msg or "does not exist" in msg:
        return ERROR_CODE_CFG_FILE_NOT_FOUND
    if "invalid dimensions line" in msg or "invalid coordinate row" in msg or "grid file" in msg:
        return ERROR_CODE_CFG_GRID_PARSE
    if (
        "must both be periodic" in msg
        or "inconsistent periodicity" in msg
        or "mismatch" in msg
        or "requires --" in msg
        or "must be 1 (auto) or exactly" in msg
    ):
        return ERROR_CODE_CFG_INCONSISTENT_COMBO
    if (
        "must be a mapping" in msg
        or "must be a list" in msg
        or "must be a string" in msg
        or "must be a boolean" in msg
        or "must be either" in msg
    ):
        return ERROR_CODE_CFG_INVALID_TYPE
    if "unsupported key" in msg or "unsupported top-level section" in msg:
        return ERROR_CODE_CFG_INVALID_VALUE
    return ERROR_CODE_CFG_INVALID_VALUE
 
# ==============================================================================
# HELPER FUNCTIONS
# ==============================================================================
 
def read_yaml_file(filepath: str) -> dict:
    """!
    @brief Safely reads a YAML file and returns its content.
    @param[in] filepath Path to the YAML file.
    @return A dictionary containing the parsed YAML content.
    @throws SystemExit if the file is not found or cannot be parsed.
    """
    if not os.path.exists(filepath):
        emit_structured_error(
            ERROR_CODE_CFG_FILE_NOT_FOUND,
            key="-",
            file_path=filepath,
            message="Configuration file not found.",
        )
        sys.exit(1)
    try:
        with open(filepath, 'r') as f:
            return yaml.safe_load(f)
    except yaml.YAMLError as e:
        emit_structured_error(
            ERROR_CODE_CFG_INVALID_VALUE,
            key="-",
            file_path=filepath,
            message=f"YAML parse error: {e}",
            hint="Fix YAML syntax/indentation and retry validation.",
        )
        sys.exit(1)
 
def write_yaml_file(filepath: str, data: dict):
    """!
    @brief Write YAML with stable ordering for generated study artifacts.
    @param[in] filepath Argument passed to `write_yaml_file()`.
    @param[in] data Argument passed to `write_yaml_file()`.
    """
    path = os.path.abspath(filepath)
    os.makedirs(os.path.dirname(path), exist_ok=True)
    temporary = f"{path}.tmp.{os.getpid()}"
    with open(temporary, "w") as f:
        yaml.safe_dump(data, f, sort_keys=False)
        f.flush()
        os.fsync(f.fileno())
    os.replace(temporary, path)
 
def write_json_file(filepath: str, payload: dict):
    """!
    @brief Write JSON metadata/manifests with a stable, readable format.
    @param[in] filepath Argument passed to `write_json_file()`.
    @param[in] payload Argument passed to `write_json_file()`.
    """
    path = os.path.abspath(filepath)
    os.makedirs(os.path.dirname(path), exist_ok=True)
    temporary = f"{path}.tmp.{os.getpid()}"
    with open(temporary, "w") as f:
        json.dump(payload, f, indent=2, sort_keys=True)
        f.write("\n")
        f.flush()
        os.fsync(f.fileno())
    os.replace(temporary, path)
 
 
def write_runtime_execution_file(filepath: str, template_source_path: str = None) -> str:
    """!
    @brief Write a default runtime execution config, copying a source template when available.
    @param[in] filepath Argument passed to `write_runtime_execution_file()`.
    @param[in] template_source_path Argument passed to `write_runtime_execution_file()`.
    @return Value returned by `write_runtime_execution_file()`.
    """
    os.makedirs(os.path.dirname(filepath), exist_ok=True)
 
    if template_source_path and os.path.isfile(template_source_path):
        shutil.copy2(template_source_path, filepath)
        return filepath
 
    with open(filepath, "w", encoding="utf-8") as f:
        f.write(DEFAULT_RUNTIME_EXECUTION_CONFIG_TEMPLATE)
    return filepath
 
 
def _launcher_arg_contains_whitespace(token) -> bool:
    """!
    @brief Return True when a launcher arg token contains embedded whitespace and should be split.
    @param[in] token Argument passed to `_launcher_arg_contains_whitespace()`.
    @return Value returned by `_launcher_arg_contains_whitespace()`.
    """
    return isinstance(token, str) and any(ch.isspace() for ch in token.strip())
 
 
def resolve_runtime_execution_seed_source(source_project_root: str) -> "str | None":
    """!
    @brief Prefer repo-local ignored runtime config, then tracked example, then built-in defaults.
    @param[in] source_project_root Argument passed to `resolve_runtime_execution_seed_source()`.
    @return Value returned by `resolve_runtime_execution_seed_source()`.
    """
    source_root_abs = os.path.abspath(source_project_root)
    repo_local_runtime = os.path.join(source_root_abs, RUNTIME_EXECUTION_CONFIG_FILENAME)
    if os.path.isfile(repo_local_runtime):
        return repo_local_runtime
 
    tracked_example = os.path.join(
        source_root_abs,
        "config",
        "runtime",
        RUNTIME_EXECUTION_EXAMPLE_FILENAME,
    )
    if os.path.isfile(tracked_example):
        return tracked_example
    return None
 
 
def ensure_case_runtime_execution_config(case_dir: str, source_project_root: str, overwrite: bool = False) -> dict:
    """!
    @brief Create case-local runtime execution config if missing, seeded from repo-local config when available.
    @param[in] case_dir Argument passed to `ensure_case_runtime_execution_config()`.
    @param[in] source_project_root Argument passed to `ensure_case_runtime_execution_config()`.
    @param[in] overwrite Argument passed to `ensure_case_runtime_execution_config()`.
    @return Value returned by `ensure_case_runtime_execution_config()`.
    """
    case_dir_abs = os.path.abspath(case_dir)
    dest_path = os.path.join(case_dir_abs, RUNTIME_EXECUTION_CONFIG_FILENAME)
    if os.path.exists(dest_path) and not overwrite:
        return {
            "path": dest_path,
            "created": False,
            "seed_source": None,
        }
 
    seed_source = resolve_runtime_execution_seed_source(source_project_root)
    write_runtime_execution_file(dest_path, seed_source)
    return {
        "path": dest_path,
        "created": True,
        "seed_source": seed_source,
    }
 
 
def is_project_root(candidate: str) -> bool:
    """!
    @brief Return True when a directory looks like the PICurv source repository root.
    @param[in] candidate Argument passed to `is_project_root()`.
    @return Value returned by `is_project_root()`.
    """
    if not candidate:
        return False
    candidate_abs = os.path.abspath(candidate)
    return (
        os.path.isfile(os.path.join(candidate_abs, "Makefile"))
        and os.path.isdir(os.path.join(candidate_abs, "src"))
        and os.path.isdir(os.path.join(candidate_abs, "include"))
        and os.path.isdir(os.path.join(candidate_abs, "picurv_cli"))
    )
 
 
def _iter_parent_dirs(start_path: str):
    """!
    @brief Yield a path and all of its parents up to filesystem root.
    @param[in] start_path Argument passed to `_iter_parent_dirs()`.
    """
    current = os.path.abspath(start_path)
    if os.path.isfile(current):
        current = os.path.dirname(current)
    while True:
        yield current
        parent = os.path.dirname(current)
        if parent == current:
            break
        current = parent
 
 
def find_project_root_upwards(start_path: str):
    """!
    @brief Search upward from an anchor and return the first matching project root.
    @param[in] start_path Argument passed to `find_project_root_upwards()`.
    @return Value returned by `find_project_root_upwards()`.
    """
    if not start_path:
        return None
    for directory in _iter_parent_dirs(start_path):
        if is_project_root(directory):
            return directory
    return None
 
 
def discover_local_project_root(*extra_anchors):
    """!
    @brief Best-effort source repo discovery from runtime anchors.
    @param[in] extra_anchors Argument passed to `discover_local_project_root()`.
    @return Value returned by `discover_local_project_root()`.
    """
    anchors = list(extra_anchors) + [os.getcwd(), INVOKED_SCRIPT_DIR, SCRIPT_PATH, PROJECT_ROOT]
    seen = set()
    for anchor in anchors:
        if not anchor:
            continue
        anchor_abs = os.path.abspath(anchor)
        if anchor_abs in seen:
            continue
        seen.add(anchor_abs)
        project_root = find_project_root_upwards(anchor_abs)
        if project_root:
            return project_root
    return None
 
 
def find_case_origin_metadata_file(case_dir_hint: str = None):
    """!
    @brief Find the nearest case-origin metadata file from known runtime anchors.
    @details An explicit case directory is the only anchor searched, so a wrong one cannot
             fall back to the case in the working directory.
    @param[in] case_dir_hint Argument passed to `find_case_origin_metadata_file()`.
    @return Value returned by `find_case_origin_metadata_file()`.
    @throws ValueError when @p case_dir_hint is given but is not a directory.
    """
    if case_dir_hint and not os.path.isdir(case_dir_hint):
        raise ValueError(f"Case directory does not exist: {os.path.abspath(case_dir_hint)}")
    search_roots = []
    for candidate in (case_dir_hint,) if case_dir_hint else (os.getcwd(), INVOKED_SCRIPT_DIR):
        if not candidate:
            continue
        abs_candidate = os.path.abspath(candidate)
        if abs_candidate not in search_roots:
            search_roots.append(abs_candidate)
 
    for root in search_roots:
        for directory in _iter_parent_dirs(root):
            metadata_path = os.path.join(directory, CASE_ORIGIN_METADATA_FILENAME)
            if os.path.isfile(metadata_path):
                return metadata_path
    return None
 
 
def load_case_origin_metadata(case_dir_hint: str = None):
    """!
    @brief Load case-origin metadata if present, returning (case_dir, metadata_path, payload).
    @param[in] case_dir_hint Argument passed to `load_case_origin_metadata()`.
    @return Value returned by `load_case_origin_metadata()`.
    """
    metadata_path = find_case_origin_metadata_file(case_dir_hint)
    if not metadata_path:
        return None, None, None
    try:
        with open(metadata_path, "r", encoding="utf-8") as f:
            payload = json.load(f)
        if not isinstance(payload, dict):
            raise ValueError("Case origin metadata must be a JSON object.")
    except Exception as exc:
        raise ValueError(f"Failed to read case origin metadata at {metadata_path}: {exc}") from exc
    return os.path.dirname(metadata_path), metadata_path, payload
 
 
def find_runtime_execution_config_file(*anchors):
    """!
    @brief Find the nearest optional execution config from runtime/case anchors.
    @param[in] anchors Argument passed to `find_runtime_execution_config_file()`.
    @return Value returned by `find_runtime_execution_config_file()`.
    """
    seen = set()
    search_roots = []
    for candidate in list(anchors) + [os.getcwd(), INVOKED_SCRIPT_DIR]:
        if not candidate:
            continue
        current = os.path.abspath(candidate)
        if os.path.isfile(current):
            current = os.path.dirname(current)
        if current in seen:
            continue
        seen.add(current)
        search_roots.append(current)
 
    seen_dirs = set()
    for root in search_roots:
        for directory in _iter_parent_dirs(root):
            if directory in seen_dirs:
                continue
            seen_dirs.add(directory)
            for filename in RUNTIME_EXECUTION_CONFIG_FILENAMES:
                config_path = os.path.join(directory, filename)
                if os.path.isfile(config_path):
                    return config_path
    return None
 
 
def _normalize_execution_override_section(payload: dict, section_name: str, config_path: str, config_label: str) -> dict:
    """!
    @brief Validate one execution override section while preserving missing-vs-empty semantics.
    @param[in] payload Argument passed to `_normalize_execution_override_section()`.
    @param[in] section_name Argument passed to `_normalize_execution_override_section()`.
    @param[in] config_path Argument passed to `_normalize_execution_override_section()`.
    @param[in] config_label Argument passed to `_normalize_execution_override_section()`.
    @return Value returned by `_normalize_execution_override_section()`.
    """
    section = payload.get(section_name)
    if section is None:
        return {"launcher": None, "launcher_args": None}
    if not isinstance(section, dict):
        raise ValueError(f"{config_label} at {config_path}: {section_name} must be a mapping.")
 
    launcher = section.get("launcher")
    if launcher is not None and not isinstance(launcher, str):
        raise ValueError(f"{config_label} at {config_path}: {section_name}.launcher must be a string.")
 
    launcher_args = None
    if "launcher_args" in section:
        launcher_args = section.get("launcher_args", [])
        if launcher_args is None:
            launcher_args = []
        if not isinstance(launcher_args, list):
            raise ValueError(f"{config_label} at {config_path}: {section_name}.launcher_args must be a list.")
        for i, token in enumerate(launcher_args):
            if not isinstance(token, (str, int, float)):
                raise ValueError(
                    f"{config_label} at {config_path}: {section_name}.launcher_args[{i}] "
                    "must be a scalar CLI token."
                )
            if _launcher_arg_contains_whitespace(token):
                raise ValueError(
                    f"{config_label} at {config_path}: {section_name}.launcher_args[{i}] "
                    "must be a single CLI token; split whitespace-separated arguments into separate list items."
                )
        launcher_args = [str(x) for x in launcher_args]
 
    return {
        "launcher": launcher,
        "launcher_args": launcher_args,
    }
 
 
def load_runtime_execution_config(config_search_anchor: str = None, extra_search_anchors=None):
    """!
    @brief Load optional shared execution launcher config from the nearest runtime config file.
    @param[in] config_search_anchor Argument passed to `load_runtime_execution_config()`.
    @param[in] extra_search_anchors Argument passed to `load_runtime_execution_config()`.
    @return Value returned by `load_runtime_execution_config()`.
    """
    anchors = []
    if config_search_anchor is not None:
        anchors.append(config_search_anchor)
    if extra_search_anchors:
        anchors.extend(extra_search_anchors)
 
    config_path = find_runtime_execution_config_file(*anchors)
    if not config_path:
        return None, {}
 
    try:
        with open(config_path, "r", encoding="utf-8") as f:
            payload = yaml.safe_load(f) or {}
    except yaml.YAMLError as exc:
        raise ValueError(f"{os.path.basename(config_path)} YAML parse error at {config_path}: {exc}") from exc
 
    if not isinstance(payload, dict):
        raise ValueError(f"{os.path.basename(config_path)} at {config_path} must be a YAML mapping.")
 
    return config_path, {
        "default_execution": _normalize_execution_override_section(
            payload,
            "default_execution",
            config_path,
            os.path.basename(config_path),
        ),
        "local_execution": _normalize_execution_override_section(
            payload,
            "local_execution",
            config_path,
            os.path.basename(config_path),
        ),
        "cluster_execution": _normalize_execution_override_section(
            payload,
            "cluster_execution",
            config_path,
            os.path.basename(config_path),
        ),
    }
 
 
def merge_execution_overrides(base: "dict | None", override: "dict | None") -> dict:
    """!
    @brief Merge execution overrides, letting explicit override values win key-by-key.
    @param[in] base Argument passed to `merge_execution_overrides()`.
    @param[in] override Argument passed to `merge_execution_overrides()`.
    @return Value returned by `merge_execution_overrides()`.
    """
    base = base or {}
    override = override or {}
 
    launcher = override.get("launcher")
    if launcher is None:
        launcher = base.get("launcher")
 
    launcher_args = override.get("launcher_args")
    if launcher_args is None:
        launcher_args = base.get("launcher_args")
 
    return {
        "launcher": launcher,
        "launcher_args": None if launcher_args is None else [str(x) for x in launcher_args],
    }
 
 
def resolve_runtime_execution_context(runtime_execution_cfg: dict, context: str) -> dict:
    """!
    @brief Resolve default plus context-specific execution overrides.
    @param[in] runtime_execution_cfg Argument passed to `resolve_runtime_execution_context()`.
    @param[in] context Argument passed to `resolve_runtime_execution_context()`.
    @return Value returned by `resolve_runtime_execution_context()`.
    """
    if context not in LAUNCH_MODES:
        raise ValueError(f"Unsupported execution context '{context}'.")
    return merge_execution_overrides(
        runtime_execution_cfg.get("default_execution"),
        runtime_execution_cfg.get(f"{context}_execution"),
    )
 
 
def get_git_commit(repo_root: str = None) -> str:
    """!
    @brief Best-effort git commit lookup for run/study manifests and case metadata.
    @param[in] repo_root Argument passed to `get_git_commit()`.
    @return Value returned by `get_git_commit()`.
    """
    cwd = repo_root or PROJECT_ROOT
    try:
        result = subprocess.run(
            ["git", "rev-parse", "HEAD"],
            cwd=cwd,
            text=True,
            capture_output=True,
            check=False
        )
        if result.returncode == 0:
            return result.stdout.strip()
    except Exception:
        pass
    return None
 
 
def write_case_origin_metadata(case_dir: str, source_project_root: str, template_name: str = None,
                               existing: dict = None, template_managed_files=None):
    """!
    @brief Create or refresh case-origin metadata for repo-aware case maintenance commands.
    @param[in] case_dir Argument passed to `write_case_origin_metadata()`.
    @param[in] source_project_root Argument passed to `write_case_origin_metadata()`.
    @param[in] template_name Argument passed to `write_case_origin_metadata()`.
    @param[in] existing Argument passed to `write_case_origin_metadata()`.
    @param[in] template_managed_files Argument passed to `write_case_origin_metadata()`.
    @return Value returned by `write_case_origin_metadata()`.
    """
    payload = dict(existing or {})
    if "initialized_at" not in payload:
        payload["initialized_at"] = datetime.now().isoformat()
    payload["source_repo_root"] = os.path.abspath(source_project_root)
    if template_name:
        payload["template_name"] = template_name
    if template_managed_files is not None:
        payload["template_managed_files"] = sorted(set(str(p) for p in template_managed_files))
    payload["last_known_source_git_commit"] = get_git_commit(source_project_root)
    metadata_path = os.path.join(os.path.abspath(case_dir), CASE_ORIGIN_METADATA_FILENAME)
    write_json_file(metadata_path, payload)
    return metadata_path, payload
 
 
#: A `make` variable assignment such as `SYSTEM=cluster` or `CFLAGS+=-g`.
_MAKE_ASSIGNMENT_PATTERN = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*[:+?]?=.*$")
 
 
def make_args_include_explicit_goal(make_args: "list[str]") -> bool:
    """!
    @brief Return True when make args contain an explicit target rather than only options/assignments.
    @param[in] make_args Argument passed to `make_args_include_explicit_goal()`.
    @return Value returned by `make_args_include_explicit_goal()`.
    """
    if not make_args:
        return False
 
    options_with_value = {
        "-C", "-f", "-I", "-j", "-l", "-o", "-W",
        "--directory", "--file", "--makefile", "--include-dir", "--jobs",
        "--load-average", "--max-load", "--old-file", "--assume-old",
        "--what-if", "--new-file", "--assume-new",
    }
 
    skip_next = False
    for token in make_args:
        if skip_next:
            skip_next = False
            continue
        if token in options_with_value:
            skip_next = True
            continue
        if token.startswith("-"):
            continue
        if _MAKE_ASSIGNMENT_PATTERN.match(token):
            continue
        return True
    return False
 
 
def resolve_case_origin_context(case_dir_hint: str = None, source_root_override: str = None, template_name_override: str = None):
    """!
    @brief Resolve case directory, source repo root, and optional template metadata.
    @param[in] case_dir_hint Argument passed to `resolve_case_origin_context()`.
    @param[in] source_root_override Argument passed to `resolve_case_origin_context()`.
    @param[in] template_name_override Argument passed to `resolve_case_origin_context()`.
    @return Value returned by `resolve_case_origin_context()`.
    """
    metadata_case_dir, metadata_path, metadata = load_case_origin_metadata(case_dir_hint)
 
    if metadata_case_dir:
        case_dir = metadata_case_dir
    else:
        case_dir = os.path.abspath(case_dir_hint or os.getcwd())
 
    source_project_root = source_root_override
    if source_project_root:
        source_project_root = os.path.abspath(source_project_root)
    elif isinstance(metadata, dict) and isinstance(metadata.get("source_repo_root"), str):
        source_project_root = os.path.abspath(metadata["source_repo_root"])
    else:
        source_project_root = discover_local_project_root(case_dir)
 
    template_name = template_name_override
    if not template_name and isinstance(metadata, dict):
        template_name = metadata.get("template_name")
 
    return {
        "case_dir": case_dir,
        "metadata_path": metadata_path,
        "metadata": metadata or {},
        "source_project_root": source_project_root,
        "template_name": template_name,
    }
 
 
def require_project_root(candidate: str, purpose: str):
    """!
    @brief Validate that a source repo root was resolved and is structurally valid.
    @param[in] candidate Argument passed to `require_project_root()`.
    @param[in] purpose Argument passed to `require_project_root()`.
    @return Value returned by `require_project_root()`.
    """
    if not candidate:
        raise ValueError(
            f"Could not determine the PICurv source repository for {purpose}. "
            "Run this command from an initialized case directory or pass --source-root."
        )
    candidate_abs = os.path.abspath(candidate)
    if not is_project_root(candidate_abs):
        raise ValueError(
            f"Resolved source repository for {purpose} is not a valid PICurv root: {candidate_abs}"
        )
    return candidate_abs
 
 
def require_existing_case_dir(case_dir: str, purpose: str, source_project_root: str = None):
    """!
    @brief Validate that a target case directory exists and is not the source repo root.
    @param[in] case_dir Argument passed to `require_existing_case_dir()`.
    @param[in] purpose Argument passed to `require_existing_case_dir()`.
    @param[in] source_project_root Argument passed to `require_existing_case_dir()`.
    @return Value returned by `require_existing_case_dir()`.
    """
    if not case_dir:
        raise ValueError(f"Could not determine the case directory for {purpose}. Pass --case-dir.")
    case_dir_abs = os.path.abspath(case_dir)
    if not os.path.isdir(case_dir_abs):
        raise ValueError(f"Case directory for {purpose} does not exist: {case_dir_abs}")
    if source_project_root and os.path.abspath(source_project_root) == case_dir_abs:
        raise ValueError(
            f"Refusing to run {purpose} against the source repository root itself: {case_dir_abs}"
        )
    return case_dir_abs
 
 
def resolve_template_directory(source_project_root: str, template_name: str):
    """!
    @brief Resolve an example template directory inside the source repository.
    @param[in] source_project_root Argument passed to `resolve_template_directory()`.
    @param[in] template_name Argument passed to `resolve_template_directory()`.
    @return Value returned by `resolve_template_directory()`.
    """
    if not template_name:
        raise ValueError(
            "Template name is required for config sync. Re-run with --template-name or from a case initialized by current picurv."
        )
    template_dir = os.path.join(source_project_root, "examples", template_name)
    if not os.path.isdir(template_dir):
        raise ValueError(f"Case template '{template_name}' not found at '{template_dir}'")
    return template_dir
 
 
def list_template_relative_files(template_dir: str, excluded_rel_paths=None):
    """!
    @brief List all files in a template directory as case-relative paths.
    @param[in] template_dir Argument passed to `list_template_relative_files()`.
    @param[in] excluded_rel_paths Argument passed to `list_template_relative_files()`.
    @return Value returned by `list_template_relative_files()`.
    """
    template_dir_abs = os.path.abspath(template_dir)
    if not os.path.isdir(template_dir_abs):
        raise ValueError(f"Template directory not found: {template_dir_abs}")
    excluded = set(excluded_rel_paths or [])
    relative_paths = []
    for root, _, files in os.walk(template_dir_abs):
        rel_root = os.path.relpath(root, template_dir_abs)
        for filename in sorted(files):
            rel_path = filename if rel_root == "." else os.path.join(rel_root, filename)
            if rel_path in excluded:
                continue
            relative_paths.append(rel_path)
    return relative_paths
 
 
def render_template_workspace(template_dir: str, template_name: str, destination: str) -> dict:
    """!
    @brief Render an example template into the canonical workspace layout at a new path.
    @details This is the one transformation `init` applies to a template: copy it, drop the
             execution example, then relocate and rewrite its files through
             organize_initialized_workspace(). `sync-config` and `status-source` render the
             current template the same way, so all three agree on where each file lives and
             what it contains.
    @param[in] template_dir Example template directory to render.
    @param[in] template_name Example template identity.
    @param[in] destination Path to render into; it must not exist.
    @return The layout mapping returned by organize_initialized_workspace().
    """
    shutil.copytree(template_dir, destination)
    copied_runtime_example = os.path.join(destination, RUNTIME_EXECUTION_EXAMPLE_FILENAME)
    if os.path.isfile(copied_runtime_example):
        os.remove(copied_runtime_example)
    return organize_initialized_workspace(destination, template_name, source_template_root=template_dir)
 
 
def list_rendered_template_files(rendered_root: str) -> list:
    """!
    @brief List the template-managed files of a rendered workspace, workspace-relative.
    @details The workspace identity file is excluded: it records when and where the
             workspace was created, which is the workspace's own state, not the template's.
    @param[in] rendered_root Root produced by render_template_workspace().
    @return Sorted workspace-relative paths.
    """
    return sorted(
        rel for rel in list_template_relative_files(rendered_root)
        if rel != WORKSPACE_CONFIG_FILENAME
    )
 
 
def list_source_binaries(source_project_root: str):
    """!
    @brief List binary artifacts currently available in the source repo bin directory.
    @param[in] source_project_root Argument passed to `list_source_binaries()`.
    @return Value returned by `list_source_binaries()`.
    """
    source_bin_dir = os.path.join(os.path.abspath(source_project_root), "bin")
    if not os.path.isdir(source_bin_dir):
        raise ValueError(f"Source bin directory not found: {source_bin_dir}. Run 'picurv build' first.")
    binaries = sorted(
        f for f in os.listdir(source_bin_dir)
        if os.path.isfile(os.path.join(source_bin_dir, f)) and f != "picurv"
    )
    if not binaries:
        raise ValueError(f"Source bin directory contains no files: {source_bin_dir}")
    return source_bin_dir, binaries
 
 
def sync_case_binaries(case_dir: str, source_project_root: str):
    """!
    @brief Copy current source-repo binaries into a case directory for version-pinning.
    @param[in] case_dir Argument passed to `sync_case_binaries()`.
    @param[in] source_project_root Argument passed to `sync_case_binaries()`.
    @return Value returned by `sync_case_binaries()`.
    """
    case_dir_abs = os.path.abspath(case_dir)
    os.makedirs(case_dir_abs, exist_ok=True)
    source_bin_dir, binaries = list_source_binaries(source_project_root)
    copied = []
    for binary_name in binaries:
        source_path = os.path.join(source_bin_dir, binary_name)
        dest_path = os.path.join(case_dir_abs, binary_name)
        shutil.copy2(source_path, dest_path)
        copied.append(dest_path)
    return copied
 
 
def sync_case_template_files(case_dir: str, template_dir: str, overwrite: bool = False,
                             prune: bool = False, managed_rel_paths=None, template_name: str = None):
    """!
    @brief Sync template files into a case directory, preserving modified files unless overwrite is requested.
    @param[in] case_dir Argument passed to `sync_case_template_files()`.
    @param[in] template_dir Argument passed to `sync_case_template_files()`.
    @param[in] overwrite Argument passed to `sync_case_template_files()`.
    @param[in] prune Argument passed to `sync_case_template_files()`.
    @param[in] managed_rel_paths Argument passed to `sync_case_template_files()`.
    @param[in] template_name Template identity; defaults to the template directory name.
    @return Value returned by `sync_case_template_files()`.
    @details Files are compared with a fresh rendering of the template in the workspace
             layout `init` creates, so a case file is matched with the template file it
             was made from, under its workspace name and rewritten contents.
    """
    case_dir_abs = os.path.abspath(case_dir)
    template_dir_abs = os.path.abspath(template_dir)
    if not os.path.isdir(template_dir_abs):
        raise ValueError(f"Template directory not found: {template_dir_abs}")
    template_name = template_name or os.path.basename(template_dir_abs)
 
    summary = {
        "copied": [],
        "overwritten": [],
        "skipped_modified": [],
        "unchanged": [],
        "pruned": [],
        "prune_requested_without_tracking": False,
    }
    with tempfile.TemporaryDirectory(prefix="picurv-template-") as scratch:
        rendered_root = os.path.join(scratch, os.path.basename(case_dir_abs) or "workspace")
        render_template_workspace(template_dir_abs, template_name, rendered_root)
        current_template_files = list_rendered_template_files(rendered_root)
        for rel_path in current_template_files:
            src_path = os.path.join(rendered_root, rel_path)
            dest_path = os.path.join(case_dir_abs, rel_path)
            os.makedirs(os.path.dirname(dest_path), exist_ok=True)
 
            if not os.path.exists(dest_path):
                shutil.copy2(src_path, dest_path)
                summary["copied"].append(dest_path)
                continue
 
            if filecmp.cmp(src_path, dest_path, shallow=False):
                summary["unchanged"].append(dest_path)
                continue
 
            if overwrite:
                shutil.copy2(src_path, dest_path)
                summary["overwritten"].append(dest_path)
            else:
                summary["skipped_modified"].append(dest_path)
    current_template_set = set(current_template_files)
 
    managed_set = set(managed_rel_paths or [])
    if prune:
        if not managed_set:
            summary["prune_requested_without_tracking"] = True
        for rel_path in sorted(managed_set - current_template_set):
            dest_path = os.path.join(case_dir_abs, rel_path)
            if os.path.isfile(dest_path):
                os.remove(dest_path)
                summary["pruned"].append(dest_path)
 
    summary["template_managed_files"] = current_template_files
    return summary
 
 
def compute_case_source_status(case_dir: str, source_project_root: str, template_name: str = None, metadata: dict = None):
    """!
    @brief Compute source/case drift across commits, binaries, and template-managed files.
    @param[in] case_dir Argument passed to `compute_case_source_status()`.
    @param[in] source_project_root Argument passed to `compute_case_source_status()`.
    @param[in] template_name Argument passed to `compute_case_source_status()`.
    @param[in] metadata Argument passed to `compute_case_source_status()`.
    @return Value returned by `compute_case_source_status()`.
    """
    case_dir_abs = os.path.abspath(case_dir)
    source_root_abs = os.path.abspath(source_project_root)
    metadata = metadata or {}
    status = {
        "case_dir": case_dir_abs,
        "source_repo_root": source_root_abs,
        "metadata_present": bool(metadata),
        "template_name": template_name,
        "last_known_source_git_commit": metadata.get("last_known_source_git_commit"),
        "current_source_git_commit": get_git_commit(source_root_abs),
    }
    status["source_commit_changed"] = (
        bool(status["last_known_source_git_commit"])
        and bool(status["current_source_git_commit"])
        and status["last_known_source_git_commit"] != status["current_source_git_commit"]
    )
 
    binary_status = {
        "source_bin_present": False,
        "source_bin_missing": [],
        "case_bin_missing": [],
        "case_bin_different": [],
        "case_bin_current": [],
    }
    try:
        source_bin_dir, binaries = list_source_binaries(source_root_abs)
        binary_status["source_bin_present"] = True
        for binary_name in binaries:
            source_path = os.path.join(source_bin_dir, binary_name)
            case_path = os.path.join(case_dir_abs, binary_name)
            if not os.path.isfile(case_path):
                binary_status["case_bin_missing"].append(binary_name)
            elif filecmp.cmp(source_path, case_path, shallow=False):
                binary_status["case_bin_current"].append(binary_name)
            else:
                binary_status["case_bin_different"].append(binary_name)
    except ValueError as exc:
        binary_status["source_bin_missing"].append(str(exc))
    status["binaries"] = binary_status
 
    config_status = {
        "template_available": False,
        "template_files": [],
        "case_missing_files": [],
        "case_modified_files": [],
        "case_current_files": [],
        "template_removed_since_last_sync": [],
        "tracking_available": isinstance(metadata.get("template_managed_files"), list),
    }
    if template_name:
        try:
            template_dir = resolve_template_directory(source_root_abs, template_name)
            with tempfile.TemporaryDirectory(prefix="picurv-template-") as scratch:
                rendered_root = os.path.join(scratch, os.path.basename(case_dir_abs) or "workspace")
                render_template_workspace(template_dir, template_name, rendered_root)
                template_files = list_rendered_template_files(rendered_root)
                config_status["template_available"] = True
                config_status["template_files"] = template_files
                for rel_path in template_files:
                    src_path = os.path.join(rendered_root, rel_path)
                    case_path = os.path.join(case_dir_abs, rel_path)
                    if not os.path.isfile(case_path):
                        config_status["case_missing_files"].append(rel_path)
                    elif filecmp.cmp(src_path, case_path, shallow=False):
                        config_status["case_current_files"].append(rel_path)
                    else:
                        config_status["case_modified_files"].append(rel_path)
            managed_files = metadata.get("template_managed_files")
            if isinstance(managed_files, list):
                config_status["template_removed_since_last_sync"] = sorted(set(managed_files) - set(template_files))
        except ValueError:
            pass
    status["config"] = config_status
 
    case_runtime_cfg = os.path.join(case_dir_abs, RUNTIME_EXECUTION_CONFIG_FILENAME)
    repo_runtime_seed = os.path.join(source_root_abs, RUNTIME_EXECUTION_CONFIG_FILENAME)
    runtime_status = {
        "case_config_present": os.path.isfile(case_runtime_cfg),
        "repo_seed_present": os.path.isfile(repo_runtime_seed),
        "case_matches_repo_seed": False,
    }
    if runtime_status["case_config_present"] and runtime_status["repo_seed_present"]:
        runtime_status["case_matches_repo_seed"] = filecmp.cmp(
            case_runtime_cfg,
            repo_runtime_seed,
            shallow=False,
        )
    status["runtime_execution"] = runtime_status
    return status
 
 
def print_case_source_status(status: dict):
    """!
    @brief Render human-readable source/case drift details.
    @param[in] status Argument passed to `print_case_source_status()`.
    """
    print(f"[INFO] Case directory     : {status['case_dir']}")
    print(f"[INFO] Source repo        : {status['source_repo_root']}")
    print(f"[INFO] Template           : {status.get('template_name') or '(unknown)'}")
    if status.get("last_known_source_git_commit"):
        print(f"[INFO] Last synced commit : {status['last_known_source_git_commit']}")
    if status.get("current_source_git_commit"):
        print(f"[INFO] Current src commit : {status['current_source_git_commit']}")
    print(f"[INFO] Source changed     : {'yes' if status.get('source_commit_changed') else 'no'}")
 
    binaries = status["binaries"]
    if binaries["source_bin_present"] and not (binaries["case_bin_current"] or binaries["case_bin_different"]):
        print("[INFO] Binaries           : not pinned (the installation's executables are used)")
    elif binaries["source_bin_present"]:
        print(
            f"[INFO] Binaries           : current={len(binaries['case_bin_current'])} "
            f"changed={len(binaries['case_bin_different'])} missing={len(binaries['case_bin_missing'])}"
        )
    else:
        print("[INFO] Binaries           : source bin/ unavailable")
 
    config = status["config"]
    if config["template_available"]:
        print(
            f"[INFO] Template files     : current={len(config['case_current_files'])} "
            f"modified={len(config['case_modified_files'])} missing={len(config['case_missing_files'])}"
        )
        if config["tracking_available"]:
            print(f"[INFO] Prune candidates   : {len(config['template_removed_since_last_sync'])}")
        else:
            print("[INFO] Prune candidates   : tracking unavailable")
    elif status.get("template_name"):
        print("[INFO] Template files     : template unavailable in source repo")
 
    runtime_cfg = status.get("runtime_execution", {})
    print(
        f"[INFO] Runtime config     : case={'yes' if runtime_cfg.get('case_config_present') else 'no'} "
        f"repo-seed={'yes' if runtime_cfg.get('repo_seed_present') else 'no'} "
        f"matches-repo-seed={'yes' if runtime_cfg.get('case_matches_repo_seed') else 'no'}"
    )
 
 
def status_source_command(args):
    """!
    @brief Report source/case drift for an initialized case directory.
    @param[in] args Command-line style argument list supplied to the function.
    """
    try:
        context = resolve_case_origin_context(
            case_dir_hint=getattr(args, "case_dir", None),
            source_root_override=getattr(args, "source_root", None),
            template_name_override=getattr(args, "template_name", None),
        )
        source_project_root = require_project_root(context["source_project_root"], "status-source")
        case_dir = require_existing_case_dir(context["case_dir"], "status-source", source_project_root)
        status = compute_case_source_status(
            case_dir,
            source_project_root,
            template_name=context.get("template_name"),
            metadata=context.get("metadata"),
        )
    except ValueError as exc:
        print(f"[FATAL] {exc}", file=sys.stderr)
        sys.exit(1)
 
    if getattr(args, "output_format", "text") == "json":
        print(json.dumps(status, indent=2, sort_keys=True))
        return
    print_case_source_status(status)
 
def resolve_path(anchor_file: str, candidate: str) -> str:
    """!
    @brief Resolve a potentially relative path against a source YAML file path.
    @param[in] anchor_file Argument passed to `resolve_path()`.
    @param[in] candidate Argument passed to `resolve_path()`.
    @return Value returned by `resolve_path()`.
    """
    if candidate is None:
        return None
    return resolve_workspace_path(anchor_file, candidate)
 
 
POST_RUN_CONTROL_ALIASES = {
    "start_step": ("start_step", "startTime"),
    "end_step": ("end_step", "endTime"),
    "step_interval": ("step_interval", "timeStep"),
}
 
 
GRID_GENERATOR_HYPHEN_KEY_HINTS = {
    "config-file": "config_file",
    "grid-type": "grid_type",
    "cli-args": "cli_args",
}
 
#: Generator keys that used to name their own output destinations. PICurv owns where
#: generated artifacts go, so accepting these would let a configuration file create a
#: competing output directory outside the asset store.
RETIRED_GENERATOR_DESTINATION_KEYS = ("output_file", "stats_file", "vts_file",
                                      "output-file", "stats-file", "vts-file")
 
 
def _mapping_value_with_aliases(mapping: dict, *keys, default=None):
    """!
    @brief Return the first defined value from a mapping across alias keys.
    @param[in] mapping Argument passed to `_mapping_value_with_aliases()`.
    @param[in] default Argument passed to `_mapping_value_with_aliases()`.
    @param[in] keys Argument passed to `_mapping_value_with_aliases()`.
    @return Value returned by `_mapping_value_with_aliases()`.
    """
    if not isinstance(mapping, dict):
        return default
    for key in keys:
        if key in mapping:
            return mapping.get(key)
    return default
 
 
def get_post_run_control_value(post_cfg: dict, canonical_key: str, default=None):
    """!
    @brief Resolve post run_control values with backwards-compatible legacy aliases.
    @param[in] post_cfg Argument passed to `get_post_run_control_value()`.
    @param[in] canonical_key Argument passed to `get_post_run_control_value()`.
    @param[in] default Argument passed to `get_post_run_control_value()`.
    @return Value returned by `get_post_run_control_value()`.
    """
    aliases = POST_RUN_CONTROL_ALIASES.get(canonical_key, (canonical_key,))
    rc = post_cfg.get("run_control", {})
    return _mapping_value_with_aliases(rc, *aliases, default=default)
 
 
def warn_on_grid_generator_hyphen_keys(generator: dict, case_path: str, warnings: list) -> None:
    """!
    @brief Warn when grid.generator uses unsupported hyphenated wrapper keys.
    @param[in] generator grid.generator mapping from case.yml.
    @param[in] case_path Case file path for diagnostics.
    @param[in,out] warnings Warning list to append to.
    """
    if not isinstance(generator, dict):
        return
    for bad_key, expected_key in GRID_GENERATOR_HYPHEN_KEY_HINTS.items():
        if bad_key in generator and bad_key != expected_key:
            warnings.append(
                f"{case_path}: grid.generator.{bad_key} is ignored; use grid.generator.{expected_key}."
            )
 
 
#: Destination keys a generated initial condition once accepted. Its payload, summary and
#: spectrum always land at fixed paths in the asset store, so these were read and ignored.
RETIRED_INITIAL_CONDITION_DESTINATION_KEYS = ("output_file", "summary_json", "spectrum_csv")
 
 
def retired_destination_message(label: str, key: str) -> str:
    """!
    @brief Explain why a generator may not choose its own output destination.
    @param[in] label Dotted configuration path of the mapping carrying the key.
    @param[in] key The refused destination key.
    @return The refusal message, shared by every generator that once took one.
    """
    return (
        f"'{label}.{key}' is no longer accepted. PICurv chooses where generated artifacts "
        "go; the published asset carries the payload, its preview, and its validation record."
    )
 
 
def reject_generator_destination_keys(generator, case_path: str, label: str) -> list:
    """!
    @brief Reject generator settings that try to choose their own output destination.
    @param[in] generator Generator mapping from the case configuration.
    @param[in] case_path Case file path for diagnostics.
    @param[in] label Dotted configuration path being checked, for the message.
    @return List of error strings.
    """
    if not isinstance(generator, dict):
        return []
    return [
        f"  {case_path}: {retired_destination_message(label, key)}"
        for key in RETIRED_GENERATOR_DESTINATION_KEYS if key in generator
    ]
 
 
def get_post_source_data(post_cfg: dict):
    """!
    @brief Return source_data as a mapping when valid, else an empty mapping.
    @param[in] post_cfg Argument passed to `get_post_source_data()`.
    @return Value returned by `get_post_source_data()`.
    """
    source_cfg = post_cfg.get("source_data", {})
    if isinstance(source_cfg, dict):
        return source_cfg
    return {}
 
 
def get_post_source_directory_template(post_cfg: dict, default: str = "<solver_output_dir>") -> str:
    """!
    @brief Resolve the source directory template from source_data with a safe default.
    @param[in] post_cfg Argument passed to `get_post_source_directory_template()`.
    @param[in] default Argument passed to `get_post_source_directory_template()`.
    @return Value returned by `get_post_source_directory_template()`.
    """
    return get_post_source_data(post_cfg).get("directory", default)
 
 
def get_post_input_extensions(post_cfg: dict):
    """!
    @brief Return post input_extensions, preferring io.* and tolerating legacy source_data.* placement.
    @param[in] post_cfg Argument passed to `get_post_input_extensions()`.
    @return Value returned by `get_post_input_extensions()`.
    """
    io_cfg = post_cfg.get("io", {})
    io_ext = io_cfg.get("input_extensions") if isinstance(io_cfg, dict) else None
    if isinstance(io_ext, dict):
        return io_ext
 
    source_ext = get_post_source_data(post_cfg).get("input_extensions")
    if isinstance(source_ext, dict):
        return source_ext
 
    return {}
 
 
def get_post_statistics_task_tokens(post_cfg: dict):
    """!
    @brief Return normalized statistics pipeline tokens that will be written into post.run.
    @param[in] post_cfg Argument passed to `get_post_statistics_task_tokens()`.
    @return Value returned by `get_post_statistics_task_tokens()`.
    """
    stats_cfg = post_cfg.get("statistics_pipeline")
    stats_entries = []
    if isinstance(stats_cfg, list):
        stats_entries = stats_cfg
    elif isinstance(stats_cfg, dict):
        stats_entries = stats_cfg.get("tasks", [])
 
    tokens = []
    for entry in stats_entries:
        if isinstance(entry, str):
            task_name = entry
        elif isinstance(entry, dict):
            task_name = entry.get("task")
        else:
            continue
        try:
            tokens.append(normalize_statistics_task(task_name))
        except ValueError:
            continue
    return tokens
 
 
def get_monitor_output_directory(monitor_cfg: dict, default: str = "output") -> str:
    """!
    @brief Resolve the solver output root from monitor.yml, preserving the default layout.
    @param[in] monitor_cfg Argument passed to `get_monitor_output_directory()`.
    @param[in] default Argument passed to `get_monitor_output_directory()`.
    @return Value returned by `get_monitor_output_directory()`.
    """
    del monitor_cfg, default
    return CANONICAL_RUN_PATHS["output"]
 
 
def get_post_statistics_output_prefix(post_cfg: dict, default: str = "Stats") -> str:
    """!
    @brief Resolve the statistics CSV prefix, preserving legacy top-level override support.
    @param[in] post_cfg Argument passed to `get_post_statistics_output_prefix()`.
    @param[in] default Argument passed to `get_post_statistics_output_prefix()`.
    @return Value returned by `get_post_statistics_output_prefix()`.
    """
    stats_cfg = post_cfg.get("statistics_pipeline")
    if isinstance(stats_cfg, dict):
        prefix = stats_cfg.get("output_prefix")
        if isinstance(prefix, str) and prefix.strip():
            return prefix.strip()
 
    legacy_prefix = post_cfg.get("statistics_output_prefix")
    if isinstance(legacy_prefix, str) and legacy_prefix.strip():
        return legacy_prefix.strip()
 
    return default
 
 
def resolve_post_statistics_output_prefix(post_cfg: dict, monitor_cfg=None, default: str = "Stats") -> str:
    """!
    @brief Resolve the runtime statistics prefix, routing bare basenames under the monitor output root.
    @param[in] post_cfg Argument passed to `resolve_post_statistics_output_prefix()`.
    @param[in] monitor_cfg Optional monitor configuration used to anchor the default statistics home.
    @param[in] default Argument passed to `resolve_post_statistics_output_prefix()`.
    @return Value returned by `resolve_post_statistics_output_prefix()`.
    """
    prefix = get_post_statistics_output_prefix(post_cfg, default=default).strip()
    if os.path.isabs(prefix):
        return prefix
 
    if os.path.dirname(prefix):
        return prefix
 
    del monitor_cfg
    return os.path.join(CANONICAL_RUN_PATHS["statistics"], prefix)
 
 
def get_post_statistics_output_artifacts(post_cfg: dict, run_dir: str, monitor_cfg=None):
    """!
    @brief Predict statistics CSV output paths relative to the postprocessor runtime cwd.
    @param[in] post_cfg Argument passed to `get_post_statistics_output_artifacts()`.
    @param[in] run_dir Argument passed to `get_post_statistics_output_artifacts()`.
    @param[in] monitor_cfg Optional monitor configuration used to anchor the default statistics home.
    @return Value returned by `get_post_statistics_output_artifacts()`.
    """
    if not isinstance((post_cfg or {}).get("_picurv_paths"), dict):
        post_cfg, _ = apply_canonical_post_paths(post_cfg, run_dir)
    token_to_suffix = {
        "ComputeMSD": "_msd.csv",
    }
    prefix = resolve_post_statistics_output_prefix(post_cfg, monitor_cfg)
    if os.path.isabs(prefix):
        base_path = os.path.abspath(prefix)
    else:
        base_path = os.path.abspath(os.path.join(run_dir, prefix))
 
    output_paths = []
    for token in get_post_statistics_task_tokens(post_cfg):
        suffix = token_to_suffix.get(token)
        if suffix:
            output_paths.append(base_path + suffix)
 
    return list(dict.fromkeys(output_paths))
 
 
#: Spectra tasks a post recipe may request, with the preconditions each needs.
#:
#: `requires_uniform_cartesian` is checked against the staged PICGRID and
#: `requires_periodic_geometric` against the resolved boundary conditions, both
#: before any field is read. A task whose preconditions the case cannot meet is
#: refused at validation rather than producing a curve with no meaning: a spectrum
#: needs the transform direction to be uniformly spaced, periodic, and statistically
#: homogeneous. Wall-bounded Cartesian cases may transform only their periodic axes.
POST_SPECTRA_TASKS = {
    "plane_spectrum": {"requires_single_block": True, "fields": ("Ucat",)},
    "line_spectrum": {"requires_single_block": True, "fields": ("Ucat",)},
    "shell_spectrum": {
        "requires_uniform_cartesian": True,
        "requires_periodic_geometric": True,
        "requires_single_block": True,
        "fields": ("Ucat",),
    },
}
 
#: Binning abscissae a spectra task may request.
POST_SPECTRA_SYMBOLS = ("continuum", "discrete")
 
#: Fluctuation definitions a spectra task may request. `window:<name>` is accepted
#: as a prefixed form and resolved against the accumulated windows.
POST_SPECTRA_MEAN_MODES = ("none", "domain", "sample")
 
 
#: Derived outputs a post recipe may request from an accumulated window.
POST_FIELD_STATISTICS_OUTPUTS = ("mean", "reynolds_stress", "rms", "tke", "flux", "point_variance")
#: Outputs written when a recipe names none: every output except the opt-in `point_variance`,
#: which in a profile answers a different question from `rms` (page 10, profiles).
POST_FIELD_STATISTICS_DEFAULT_OUTPUTS = POST_FIELD_STATISTICS_OUTPUTS[:-1]
 
#: Output formats a post recipe may request. `vtk` writes the derived fields; `csv`
#: appends one convergence row per processed step.
POST_FIELD_STATISTICS_FORMATS = ("vtk", "csv")
 
# ---------------------------------------------------------------------------
# Authoritative public choice sets.
#
# Each of these was a literal written inline at its point of use, which made it
# invisible to the capability census: a set nobody can enumerate is a set nobody can
# document. Naming them here is the discovery contract - the census enumerates
# module-level names with these suffixes and demands a classification for each.
# ---------------------------------------------------------------------------
 
#: How the grid reaches the solver.
GRID_MODES = ("file", "programmatic_c", "grid_gen")
 
#: Flow dimensionality. `2D` does not change the grid: it zeroes the i-direction row of
#: the momentum right-hand side (`-TwoD 1`), so the i velocity component never evolves.
DOMAIN_DIMENSIONALITY_MODES = ("3D", "2D")
 
#: Geometries the bundled grid generator can produce.
GRID_GENERATOR_TYPES = ("box", "sweep")
 
#: Cross-sections a swept duct may carry. `circle` is the square-to-disc map, not an
#: O-grid: `Metric.c`'s `cgrid` branch for a circumferential seam is reachable only via
#: `programmatic_c`'s `cgrids` flag, and even there `src/grid.c` never builds anything
#: but a Cartesian box, so no path produces real O-grid coordinates to seam.
GRID_CROSS_SECTION_KINDS = ("rectangle", "circle")
 
#: Segment kinds a piecewise wall-height field accepts. A wall is built from these end to
#: end, so a step is one entry in a list rather than a geometry of its own.
GRID_WALL_SEGMENT_KINDS = ("flat", "step", "ramp", "arc", "sine", "gaussian", "hill")
 
#: Centreline segment kinds a swept path accepts.
GRID_PATH_SEGMENT_KINDS = ("straight", "arc")
 
#: Placement and similarity operations applied after a geometry map.
GRID_TRANSFORM_KINDS = ("anchor", "translate", "scale", "rotate", "mirror", "permute", "reverse")
 
#: Whether a run seeds particles afresh or restores them from a checkpoint.
PARTICLE_RESTART_MODES = ("init", "load")
 
#: Eulerian post-processing kernels selectable per pipeline entry.
POST_EULERIAN_PIPELINE_TASKS = ("q_criterion", "normalize_field", "nodal_average")
 
#: Lagrangian post-processing kernels selectable per pipeline entry.
POST_LAGRANGIAN_PIPELINE_TASKS = ("specific_ke",)
 
#: Study shapes `picurv sweep` knows how to expand and aggregate.
STUDY_TYPES = ("grid_independence", "timestep_independence", "sensitivity")
 
#: Preconditioning models for the Newton-Krylov momentum solve.
NEWTON_KRYLOV_PRECONDITIONER_MODELS = ("none", "frozen_momentum_jacobian")
 
#: Matrix structures a Newton-Krylov preconditioner model may assemble. Determined by
#: the model rather than chosen independently: `frozen_momentum_jacobian` requires
#: `point_block`, and `none` accepts no structure at all.
NEWTON_KRYLOV_PRECONDITIONER_STRUCTURES = ("none", "point_block")
 
#: Outer preconditioners the Poisson solve accepts. One canonical value today; the
#: census fails if this grows without a capability family being registered for it.
POISSON_PRECONDITIONER_TYPES = ("multigrid",)
 
#: Accepted spellings for the Poisson outer preconditioner.
POISSON_PRECONDITIONER_SPELLINGS = {"mg": "multigrid", "pcmg": "multigrid"}
 
# Storage compression policies live in picurv_cli/storage.py, which owns them; core
# imports storage, so declaring them here would be a cycle.
 
#: How a prescribed Eulerian field is supplied.
PRESCRIBED_FLOW_SOURCE_TYPES = ("file", "generated", "field_slice")
 
#: Analytic scalar profiles the verification source may generate.
VERIFICATION_SCALAR_PROFILES = ("CONSTANT", "LINEAR_X", "SIN_PRODUCT")
 
#: Scalar-transport parameters and the runtime flag each becomes. The Schmidt numbers are
#: positive and set particle diffusivity; `iem_constant` is C_IEM in the IEM mixing rate
#: Omega = C_IEM Gamma / Delta^2 (runtime default 2.0), and 0 switches micromixing off so a
#: particle scalar is a passive label.
SCALAR_TRANSPORT_FLAGS = {
    "schmidt_number": "-schmidt_number",
    "turbulent_schmidt_number": "-turb_schmidt_number",
    "iem_constant": "-iem_constant",
}
 
#: Where each scalar-transport parameter lives in case.yml: the molecular Schmidt number is a
#: fluid property, the turbulent one a parameter of the subgrid model, and C_IEM a parameter
#: of the particle mixing model. solver.yml `scalar_transport` is their deprecated location.
SCALAR_TRANSPORT_CASE_PATHS = {
    "schmidt_number": ("properties", "fluid"),
    "turbulent_schmidt_number": ("models", "physics", "turbulence"),
    "iem_constant": ("models", "physics", "particles"),
}
 
 
def resolve_scalar_transport(case_cfg: dict, solver_cfg: dict, warn: bool = False) -> dict:
    """!
    @brief Resolve the scalar-transport parameters from case.yml or their deprecated location.
    @details Each parameter is read from its case.yml location (SCALAR_TRANSPORT_CASE_PATHS)
             or, as a deprecated alias, from solver.yml `scalar_transport`. Setting one in both
             places is refused rather than resolved by precedence.
    @param[in] case_cfg Parsed case configuration.
    @param[in] solver_cfg Parsed solver configuration.
    @param[in] warn Print a deprecation warning for each parameter read from solver.yml.
    @return Mapping of parameter name to validated value, for the parameters that are set.
    @throws ValueError for a malformed, duplicated, or out-of-range parameter.
    """
    legacy = (solver_cfg or {}).get("scalar_transport") or {}
    if not isinstance(legacy, dict):
        raise ValueError("solver.yml scalar_transport must be a mapping when provided.")
    unknown = sorted(set(legacy) - set(SCALAR_TRANSPORT_FLAGS))
    if unknown:
        raise ValueError(f"solver.yml scalar_transport has unsupported key(s): {unknown}. "
                         f"Use one of {sorted(SCALAR_TRANSPORT_FLAGS)}, in case.yml.")
    values = {}
    for key, path in SCALAR_TRANSPORT_CASE_PATHS.items():
        node = case_cfg or {}
        for part in path:
            node = node.get(part) if isinstance(node, dict) else None
        case_label = ".".join(path + (key,))
        in_case = isinstance(node, dict) and key in node
        if in_case and key in legacy:
            raise ValueError(f"{key} is set in case.yml ({case_label}) and in its deprecated "
                             f"solver.yml location (scalar_transport.{key}); keep only the case.yml one.")
        if not in_case and key not in legacy:
            continue
        raw, label = (node[key], f"case.yml {case_label}") if in_case else \
                     (legacy[key], f"solver.yml scalar_transport.{key}")
        try:
            value = _to_finite_float(raw, label) if key == "iem_constant" else float(raw)
        except (TypeError, ValueError) as exc:
            raise ValueError(f"{label} must be numeric.") from exc
        # iem_constant = 0 switches micromixing off; the Schmidt numbers divide.
        if value < 0.0 or (value == 0.0 and key != "iem_constant"):
            raise ValueError(f"{label} must be {'non-negative' if key == 'iem_constant' else 'positive'}.")
        if not in_case and warn:
            print(f"[WARNING] solver.yml scalar_transport.{key} is deprecated; set it in case.yml "
                  f"as {case_label}.", file=sys.stderr)
        values[key] = value
    return values
 
#: Image formats `picurv sweep` can render study plots in.
STUDY_PLOT_FORMATS = ("png", "pdf", "svg")
 
#: How much per-timestep profiling output the monitor emits.
PROFILING_TIMESTEP_MODES = ("off", "selected", "all")
 
#: Solver functions renamed by the Poisson rewrite (0d34592). Function lists in monitor.yml
#: match names exactly, so an old name would select nothing; it is translated instead.
RENAMED_MONITOR_FUNCTIONS = {
    "PoissonSolver_MG": "PoissonSolver_Multigrid",
    "Projection": "ProjectVelocity",
    "PoissonLHSNew": "AssemblePoissonOperator",
    "PoissonRHS": "ComputePoissonRHS",
}
 
#: Solver functions the Poisson rewrite removed; nothing logs or profiles under these names.
REMOVED_MONITOR_FUNCTIONS = (
    "CorrectChannelFluxProfile", "VolumeFlux", "VolumeFlux_rev", "FullyBlocked",
    "MyNvertRestriction", "MyRestriction", "MyInterpolation", "PoissonNullSpaceFunction",
    "GridRestriction", "SetupSolverParameters",
)
 
#: Krylov methods for which a `gmres.restart` parameter is meaningful.
GMRES_RESTART_METHODS = ("gmres", "fgmres", "lgmres")
 
#: Outer Poisson Krylov methods verified against the multigrid preconditioner, with the
#: PETSc options that make each stop on the true residual. The preconditioner is not a
#: single fixed linear operator, which only a flexible method tolerates: under gmres,
#: lgmres and bcgs - left- or right-preconditioned - the Krylov residual fell to 1e-12
#: while the true residual stalled near 1e-3 and the projection left a divergence of 2e-4.
#: CG keeps its left preconditioner and is told to monitor the unpreconditioned norm. Any
#: other KSP type is reachable only through petsc_passthrough_options, unverified.
POISSON_KSP_METHODS = {
    "fgmres": {},
    "cg": {"-ps_ksp_norm_type": "unpreconditioned"},
}
 
#: Methods refused with a specific reason rather than the generic unverified message.
POISSON_KSP_REFUSED = {
    "gmres": "is not flexible",
    "lgmres": "is not flexible",
    "bcgs": "is not flexible",
}
 
#: Analytical solution types the Eulerian source can impose.
ANALYTICAL_SOLUTION_TYPES = ("TGV3D", "ZERO_FLOW", "UNIFORM_FLOW")
 
#: Legacy capitalised spellings of the field-initialisation mode, still accepted and
#: resolved through normalize_field_init_mode.
LEGACY_FIELD_INIT_SPELLINGS = ("Zero", "Constant", "Poiseuille")
 
#: Discrete operators the solenoidal projection may use.
PROJECTION_OPERATORS = ("continuum", "picurv_discrete")
 
#: Where `picurv sweep` reads a declared metric from.
METRIC_SOURCE_KINDS = ("statistics_csv", "csv", "log_regex", "log")
 
#: Where a run is launched.
LAUNCH_MODES = ("local", "cluster")
 
 
 
def normalize_post_spectra_config(post_cfg: dict) -> dict:
    """!
    @brief Validate and canonicalize the spectra block of post.yml.
 
    @details The recipe chooses what to measure; whether the case *can* support that
             measurement is a separate question answered by
             `validate_post_spectra_preconditions()`, which needs the grid and the
             boundary conditions. Keeping the two apart means a recipe stays valid on
             its own terms even when it is read without a case beside it.
 
    @param[in] post_cfg Parsed post-processing configuration.
    @return Normalized mapping with an output prefix and a list of tasks.
    @throws ValueError on a malformed or inconsistent recipe.
    """
    raw = (post_cfg or {}).get("spectra")
    if raw is None:
        return {"output_prefix": "Spectrum", "tasks": []}
    if not isinstance(raw, dict):
        raise ValueError("'spectra' must be a mapping.")
 
    prefix = raw.get("output_prefix", "Spectrum")
    if not isinstance(prefix, str) or not prefix.strip():
        raise ValueError("'spectra.output_prefix' must be a non-empty string.")
 
    tasks = raw.get("tasks")
    if not isinstance(tasks, list) or not tasks:
        raise ValueError("'spectra.tasks' must be a non-empty list.")
 
    cleaned = []
    seen = []
    for position, entry in enumerate(tasks):
        if not isinstance(entry, dict):
            raise ValueError(f"spectra task {position}: each task must be a mapping.")
        name = entry.get("task")
        if not isinstance(name, str) or name not in POST_SPECTRA_TASKS:
            raise ValueError(
                f"spectra task {position}: unknown task {name!r}. "
                f"Available tasks: {sorted(POST_SPECTRA_TASKS)}."
            )
        spec = POST_SPECTRA_TASKS[name]
 
        field = entry.get("field", spec["fields"][0])
        if field not in spec["fields"]:
            raise ValueError(
                f"spectra task '{name}': field {field!r} is not supported. "
                f"Supported fields: {list(spec['fields'])}."
            )
 
        block = entry.get("block", 0)
        if not isinstance(block, int) or isinstance(block, bool) or block < 0:
            raise ValueError(f"spectra task '{name}': 'block' must be a non-negative integer.")
 
        symbol = entry.get("symbol", "continuum")
        if symbol not in POST_SPECTRA_SYMBOLS:
            raise ValueError(
                f"spectra task '{name}': unknown symbol {symbol!r}. "
                f"Available symbols: {list(POST_SPECTRA_SYMBOLS)}."
            )
 
        subtract_mean = entry.get("subtract_mean", "none")
        if not isinstance(subtract_mean, str) or not subtract_mean.strip():
            raise ValueError(f"spectra task '{name}': 'subtract_mean' must be a string.")
        subtract_mean = subtract_mean.strip()
        if subtract_mean.startswith("window:"):
            window_name = subtract_mean.split(":", 1)[1].strip()
            if not window_name:
                raise ValueError(
                    f"spectra task '{name}': 'subtract_mean: window:<name>' needs a window name."
                )
        elif subtract_mean not in POST_SPECTRA_MEAN_MODES:
            raise ValueError(
                f"spectra task '{name}': unknown subtract_mean {subtract_mean!r}. "
                f"Use one of {list(POST_SPECTRA_MEAN_MODES)} or 'window:<name>'."
            )
 
        # A window mean is only worth subtracting once the window has converged, so the
        # bundle the mean is read from is chosen separately from the step being
        # transformed. Left unset, each step uses its own bundle, whose running mean is
        # undefined at the moment the window activates.
        mean_source_step = entry.get("mean_source_step")
        if mean_source_step is not None:
            if (not isinstance(mean_source_step, int) or isinstance(mean_source_step, bool)
                    or mean_source_step < 0):
                raise ValueError(
                    f"spectra task '{name}': 'mean_source_step' must be a non-negative integer."
                )
            if not subtract_mean.startswith("window:"):
                raise ValueError(
                    f"spectra task '{name}': 'mean_source_step' only applies to "
                    f"'subtract_mean: window:<name>'."
                )
 
        reference = entry.get("reference")
        if reference is not None and (not isinstance(reference, str) or not reference.strip()):
            raise ValueError(f"spectra task '{name}': 'reference' must be a non-empty string.")
 
        selection = {}
        if name != "shell_spectrum":
            axes = entry.get("axes")
            fixed = entry.get("fixed_indices")
            count = 2 if name == "plane_spectrum" else 1
            if (not isinstance(axes, list) or len(axes) != count or any(a not in ("i", "j", "k") for a in axes)
                    or len(set(axes)) != count or not isinstance(fixed, dict)
                    or set(fixed) != set("ijk")-set(axes)
                    or any(isinstance(i, bool) or not isinstance(i, int) or i < 0 for i in fixed.values())):
                raise ValueError(f"{name} requires {count} distinct axes and zero-based fixed_indices on all remaining axes.")
            if symbol != "continuum":
                raise ValueError("plane/line spectra require symbol: continuum.")
            selection = {"axes": sorted(axes), "fixed_indices": dict(sorted(fixed.items()))}
        elif subtract_mean == "sample" or "axes" in entry or "fixed_indices" in entry:
            raise ValueError("shell_spectrum does not accept sample subtraction or plane/line selections.")
        # Each task writes its own file, so a repeat would overwrite its own output.
        identity = (name, field, block, symbol, json.dumps(selection, sort_keys=True))
        if identity in seen:
            raise ValueError(
                f"spectra recipe lists task '{name}' for field {field} on block {block} "
                f"with symbol '{symbol}' more than once."
            )
        seen.append(identity)
        cleaned.append({
            "task": name,
            **selection,
            "field": field,
            "block": block,
            "symbol": symbol,
            "subtract_mean": subtract_mean,
            "mean_source_step": mean_source_step,
            "reference": reference.strip() if isinstance(reference, str) else None,
        })
 
    return {"output_prefix": prefix.strip(), "tasks": cleaned}
 
 
def validate_post_spectra_preconditions(spectra_cfg: dict, case_cfg: dict, post_path: str) -> list:
    """!
    @brief Check spectra tasks against what the case can actually support.
 
    @details Runs before any field is read, so a case with no homogeneous direction is
             refused rather than yielding a curve that means nothing. Only the checks
             the case file can answer are made here: periodicity and block count. Grid
             uniformity is enforced by `generators/spectra.gen`, which reads the staged
             PICGRID and is the only place the real node coordinates are known.
 
    @param[in] spectra_cfg Normalized spectra recipe.
    @param[in] case_cfg Parsed case configuration.
    @param[in] post_path Post recipe path, for error messages.
    @return List of formatted error strings; empty when every task is supportable.
    """
    errors = []
    if not spectra_cfg.get("tasks"):
        return errors
 
    try:
        prepared_blocks = validate_and_prepare_boundary_conditions(case_cfg)
    except ValueError:
        # The case file reports its own boundary-condition errors; do not repeat them.
        return errors
 
    block_count = int((case_cfg.get("models", {}) or {}).get("domain", {}).get("blocks", 1))
    periodic_faces = {}
    for block_index, block_bcs in enumerate(prepared_blocks):
        faces = {entry.get("face") for entry in block_bcs if entry.get("type") == "PERIODIC"}
        periodic_faces[block_index] = faces
 
    # run_post_spectra_stage reads the staged PICGRID, which only file and grid_gen
    # grids provide; refuse here rather than after the solve has run.
    grid_mode = str((case_cfg.get("grid", {}) or {}).get("mode", "")).strip()
    if grid_mode == "programmatic_c":
        errors.append(
            f"  {post_path}: spectra need a staged PICGRID, which grid.mode 'programmatic_c' "
            "does not provide. Use grid.mode 'grid_gen' or 'file' for a case whose spectra "
            "are measured."
        )
        return errors
 
    all_faces = {"-Xi", "+Xi", "-Eta", "+Eta", "-Zeta", "+Zeta"}
    for task_cfg in spectra_cfg["tasks"]:
        spec = POST_SPECTRA_TASKS[task_cfg["task"]]
        label = f"spectra task '{task_cfg['task']}'"
 
        if spec.get("requires_single_block") and block_count != 1:
            errors.append(
                f"  {post_path}: {label} requires a single-block domain; this case has "
                f"{block_count} blocks."
            )
 
        block = task_cfg["block"]
        if block >= block_count:
            errors.append(
                f"  {post_path}: {label} targets block {block}, but the case defines "
                f"{block_count} block(s)."
            )
            continue
 
        if task_cfg["task"] != "shell_spectrum":
            if (case_cfg.get("models", {}).get("physics", {}).get("fsi", {}) or {}).get("immersed", False):
                errors.append(f"  {post_path}: {label} does not support immersed masks.")
            names = {"i": "Xi", "j": "Eta", "k": "Zeta"}
            needed = {sign+names[a] for a in task_cfg["axes"] for sign in ("-", "+")}
            if not needed <= periodic_faces.get(block, set()):
                errors.append(f"  {post_path}: {label} requires PERIODIC boundaries on its transform axes.")
        if spec.get("requires_periodic_geometric"):
            missing = sorted(all_faces - periodic_faces.get(block, set()))
            if missing:
                errors.append(
                    f"  {post_path}: {label} requires every face of block {block} to be "
                    f"PERIODIC, because a shell-averaged spectrum is only defined for a "
                    f"triply periodic homogeneous box. Non-periodic faces: {missing}."
                )
    return errors
 
 
def _resolve_spectra_payload(bundle: dict, kind: str, field: str, block: int) -> str:
    """!
    @brief Locate one checkpoint payload by its inventory entry rather than by path shape.
    @param[in] bundle Validated checkpoint bundle mapping.
    @param[in] kind Payload kind recorded in the inventory.
    @param[in] field Payload field name recorded in the inventory.
    @param[in] block Block index the payload belongs to.
    @return Absolute path to the payload file.
    @throws ValueError when the bundle carries no such payload.
    """
    for payload in bundle["payloads"]:
        if (payload["kind"] == kind and payload["field"] == field
                and payload["block"] == str(block)):
            return os.path.join(bundle["bundle"], *payload["path"].split("/"))
    raise ValueError(
        f"checkpoint {os.path.basename(bundle['bundle'])} carries no {kind} payload "
        f"'{field}' for block {block}."
    )
 
 
def _spectra_mean_arguments(task_cfg: dict, bundle: dict, mean_bundle: dict = None) -> list:
    """!
    @brief Build the generator arguments implementing a task's fluctuation choice.
    @param[in] task_cfg Normalized spectra task.
    @param[in] bundle Validated checkpoint bundle for the step being transformed.
    @param[in] mean_bundle Bundle supplying the window mean; defaults to @p bundle.
    @return Argument list to append to the generator command.
    @throws ValueError when a named window is absent from the bundle.
    """
    mode = task_cfg["subtract_mean"]
    if not mode.startswith("window:"):
        return ["--subtract-mean", mode]
    window = mode.split(":", 1)[1].strip()
    block = task_cfg["block"]
    source = mean_bundle or bundle
    mean_path = _resolve_spectra_payload(source, "mean", f"{window}/{task_cfg['field']}_mean", block)
    count_path = _resolve_spectra_payload(source, "occupancy", f"{window}/count", block)
    return ["--subtract-mean", "field", "--mean-file", mean_path, "--count-file", count_path]
 
 
#: Scalar columns the spectra stage records once per processed step.
POST_SPECTRA_SCALAR_COLUMNS = (
    "resolved_kinetic_energy", "spectrum_total_energy", "parseval_residual",
    "spectrum_peak_k", "zero_mode_energy", "integral_length_scale",
    "taylor_microscale", "dissipation_over_viscosity",
)
 
 
#: Stages `picurv run --post-process` can execute, in the order they are listed.
POST_STAGE_NAMES = ("fields", "spectra", "reducers")
 
 
def resolve_post_stage_selection(only) -> set:
    """!
    @brief Resolve the `--only` selector into the set of post stages to execute.
    @param[in] only Comma-separated selector text, or None for every stage.
    @return Set of stage names.
    @throws ValueError when the selector names an unknown or empty stage.
    """
    if not only:
        return set(POST_STAGE_NAMES)
    requested = [token.strip() for token in str(only).split(",")]
    if not all(requested):
        raise ValueError("--only must not contain an empty stage name.")
    unknown = sorted({token for token in requested if token not in POST_STAGE_NAMES})
    if unknown:
        raise ValueError(
            f"--only names unknown post stage(s) {unknown}. "
            f"Available stages: {list(POST_STAGE_NAMES)}."
        )
    return set(requested)
 
 
def run_post_spectra_stage(run_dir: str, post_cfg: dict, monitor_cfg: dict,
                           source_dir: str, steps, quiet: bool = False,
                           plan: "dict | None" = None, recompute: bool = False) -> dict:
    """!
    @brief Measure spectra for every requested task across a window of committed steps.
 
    @details One spectrum per step per task, because a spectrum is a property of one
             state: averaging across steps would be wrong for a decaying flow, where
             every step is a different statistical state. Results are written in long
             form so a family of curves stays one file, alongside a scalar history that
             plots through the ordinary series machinery.
 
    @param[in] run_dir Run directory receiving the output.
    @param[in] post_cfg Parsed post-processing configuration.
    @param[in] monitor_cfg Parsed monitor configuration anchoring the output root.
    @param[in] source_dir Directory holding the committed checkpoints.
    @param[in] steps Iterable of checkpoint steps to process, in order.
    @param[in] quiet Suppress progress reporting.
    @param[in] plan Post plan whose recipe state records each measured step; with it, a
                    step whose rows are still valid (classify_post_step()) is not
                    measured again. None measures every committed step given.
    @param[in] recompute Measure every committed step even when its rows are valid.
    @return Summary with the written paths and the steps actually processed.
    @throws ValueError when the generator fails or a requested payload is absent.
    """
    spectra = normalize_post_spectra_config(post_cfg)
    if not spectra["tasks"]:
        return {"tasks": [], "steps": [], "artifacts": []}
 
    script = os.path.join(GENERATORS_PATH, "spectra.gen")
    if not os.path.isfile(script):
        raise ValueError(f"spectra.gen script not found: {script}")
    staged_grid = os.path.join(run_dir, "inputs", "grid", "grid.run")
    if not os.path.isfile(staged_grid):
        raise ValueError(f"spectra require a staged PICGRID at {staged_grid}.")
 
    output_dir = os.path.join(
        os.path.abspath(run_dir), resolve_recipe_spectra_output_dir(post_cfg, monitor_cfg)
    )
    os.makedirs(output_dir, exist_ok=True)
 
    # Spectra are computed from the staged non-dimensional field on the staged
    # non-dimensional grid, so physical units are the generator's to apply. The run's
    # own configuration snapshot is the authority for the scales it used.
    scale_arguments = []
    # Checkpoint times are solver time; a dimensionalized result reports physical time.
    time_scale = 1.0
    if bool((post_cfg.get("global_operations") or {}).get("dimensionalize", False)):
        active_case = load_active_run_configuration(run_dir).get("case")
        case_path = os.path.join(run_dir, active_case) if active_case else None
        if case_path and os.path.isfile(case_path):
            scaling = resolve_fluid_scaling(read_yaml_file(case_path))
            scale_arguments = [
                "--velocity-ref", repr(float(scaling["velocity_ref"])),
                "--length-ref", repr(float(scaling["length_ref"])),
            ]
            time_scale = reference_scale(TIME, scaling)
        elif not quiet:
            print("[WARNING] Spectra: dimensionalize was requested but this run carries no "
                  "readable case snapshot; results stay non-dimensional.", file=sys.stderr)
 
    requested = sorted(set(int(step) for step in steps))
    signature = compute_post_spectra_signature(spectra)
    records = {}
    if plan is not None:
        # Steps whose rows are still valid are not measured again; unrecorded rows are
        # adopted on the same terms as field output (classify_post_step()).
        existing = _read_post_records(plan['resume_state_path'])[1]
        # Each task writes a spectrum and a history file; a step is measured only when
        # both of every task's files hold it.
        spectra_files = [
            os.path.join(output_dir, f"{post_spectra_task_basename(task, spectra['output_prefix'])}{suffix}.csv")
            for task in spectra["tasks"] for suffix in ("", "_history")
        ]
        measured = set.intersection(*(_scan_post_statistics_csv_steps(path) for path in spectra_files))
        pending = []
        for step in requested:
            record = existing.get(str(step))
            commit = _checkpoint_commit(source_dir, step)
            reason = classify_post_step(record, spectra_files if step in measured else None,
                                        commit, signature, recompute)
            if reason is not None:
                pending.append(step)
            elif record is None:
                records[step] = {"recipe": signature, "checkpoint": commit[0] if commit else None}
        if not quiet and len(pending) != len(requested):
            print(f"[INFO] Spectra: {len(requested) - len(pending)} requested step(s) are up to date.")
        try:
            require_storage_payload_local(run_dir, "spectra", checkpoints=pending)
        except StorageError as exc:
            raise ValueError(str(exc)) from exc
        requested = pending
        if not requested:
            persist_post_resume_state(run_dir, plan, spectra=records)
            return {"tasks": [], "steps": [], "artifacts": []}
    # The requested window is what the recipe asks for, not what exists. Like the field
    # stage, only committed checkpoints are measured: a window reaching past the last
    # committed checkpoint is normal while a solve is still running, and is not an error.
    available = _scan_committed_checkpoint_steps(source_dir)
    ordered_steps = [step for step in requested if step in available]
    if not ordered_steps:
        if not quiet:
            print("[INFO] Spectra: no step needing measurement has a committed checkpoint "
                  "yet; nothing measured.")
        if plan is not None:
            persist_post_resume_state(run_dir, plan, spectra=records)
        return {"tasks": [], "steps": [], "artifacts": []}
    if not quiet and len(ordered_steps) != len(requested):
        print(f"[INFO] Spectra: {len(ordered_steps)} of {len(requested)} step(s) needing "
              f"measurement are committed; measuring those.")
    artifacts = []
    for task_cfg in spectra["tasks"]:
        basename = post_spectra_task_basename(task_cfg, spectra["output_prefix"])
        spectrum_path = os.path.join(output_dir, f"{basename}.csv")
        scalar_path = os.path.join(output_dir, f"{basename}_history.csv")
        spectrum_rows = []
        scalar_rows = []
        mean_bundle = None
        if task_cfg["mean_source_step"] is not None:
            mean_bundle = validate_committed_checkpoint(source_dir, task_cfg["mean_source_step"])
 
        for step in ordered_steps:
            bundle = validate_committed_checkpoint(source_dir, step)
            time = float(bundle["metadata"]["checkpoint_time"]) * time_scale
            field_path = _resolve_spectra_payload(
                bundle, "eulerian", task_cfg["field"], task_cfg["block"]
            )
            cmd = [sys.executable, script, task_cfg["task"].replace("_", "-"),
                   "--field-file", field_path, "--source-grid", staged_grid,
                   "--block", str(task_cfg["block"]), "--symbol", task_cfg["symbol"]]
            if task_cfg["task"] != "shell_spectrum":
                cmd.extend(["--axes", *task_cfg["axes"], "--fixed-indices", json.dumps(task_cfg["fixed_indices"])])
            cmd.extend(_spectra_mean_arguments(task_cfg, bundle, mean_bundle))
            cmd.extend(scale_arguments)
            cmd.extend(petsc_index_arguments(int(bundle["metadata"].get("checkpoint_petsc_index_bytes", "4"))))
            result = subprocess.run(cmd, text=True, capture_output=True)
            if result.returncode != 0:
                details = (result.stderr or result.stdout or "").strip()
                raise ValueError(
                    f"spectra task '{task_cfg['task']}' failed at step {step} with exit code "
                    f"{result.returncode}. Details:\n{details}"
                )
            summary = json.loads(result.stdout)
            for row in summary.get("sampled_spectrum", summary.get("shell_spectrum")):
                spectrum_rows.append({"step": step, "time": time, **row})
            scalar_columns = (POST_SPECTRA_SCALAR_COLUMNS if task_cfg["task"] == "shell_spectrum"
                              else ("resolved_kinetic_energy", "parseval_residual"))
            scalar_rows.append({"step": step, "time": time,
                                **{name: summary[name] for name in scalar_columns}})
 
        spectrum_fields = ("step", "time", *summary.get("spectrum_columns", ("k", "energy")))
        scalar_fields = ("step", "time") + scalar_columns
        # Only the steps that were missing or stale are measured; keep the rows already
        # written for every other step, replacing only those re-measured now.
        remeasured = set(ordered_steps)
        spectrum_rows = _merge_spectra_rows(spectrum_path, spectrum_fields, remeasured, spectrum_rows)
        scalar_rows = _merge_spectra_rows(scalar_path, scalar_fields, remeasured, scalar_rows)
        with open(spectrum_path, "w", newline="", encoding="utf-8") as stream:
            writer = csv.DictWriter(stream, fieldnames=spectrum_fields)
            writer.writeheader()
            writer.writerows(spectrum_rows)
        with open(scalar_path, "w", newline="", encoding="utf-8") as stream:
            writer = csv.DictWriter(stream, fieldnames=scalar_fields)
            writer.writeheader()
            writer.writerows(scalar_rows)
        artifacts.extend([spectrum_path, scalar_path])
        if not quiet:
            print(f"[INFO] Spectra: measured {len(ordered_steps)} step(s) for task "
                  f"'{task_cfg['task']}'; {os.path.relpath(spectrum_path, run_dir)} now holds "
                  f"{len(scalar_rows)} step(s)")
 
    if plan is not None:
        for step in ordered_steps:
            commit = _checkpoint_commit(source_dir, step)
            records[step] = {"recipe": signature, "checkpoint": commit[0] if commit else None}
        persist_post_resume_state(run_dir, plan, spectra=records)
    return {
        "tasks": [entry["task"] for entry in spectra["tasks"]],
        "steps": ordered_steps,
        "artifacts": artifacts,
    }
 
 
#: Reducer tasks a post recipe may request. Each runs a `generators/reduce.gen`
#: subcommand over the field-statistics profiles of one window or ensemble.
#: `retains` is how many directions the profile must keep, and `axis_key` the task key
#: naming the one it keeps (`wall_axis`) or the one it merged (`stream_axis`).
POST_REDUCER_TASKS = {
    "wall_profile": {"command": "wall-profile", "retains": 1, "axis_key": "wall_axis", "default_axis": "j"},
    "cross_section": {"command": "cross-section", "retains": 2, "axis_key": "stream_axis", "default_axis": "k"},
    "profile_series": {"command": "profile-series", "retains": 1, "axis_key": None, "default_axis": None},
}
 
#: Where a wall reducer takes its friction velocity from, and what each needs: a metrics
#: source averages over the window's effective bounds, so it needs a run window rather
#: than an ensemble; a direct source takes the recipe's `value`.
POST_REDUCER_FRICTION_SOURCES = {
    "first_cell": {"needs": None},
    "driven_flow": {"needs": "window"},
    "wall_model": {"needs": "window"},
    "body_force": {"needs": "value"},
    "u_tau": {"needs": "value"},
}
 
#: Index axis -> the axis token `reduce.gen` takes.
_REDUCER_AXIS_TOKENS = {"i": "Xi", "j": "Eta", "k": "Zeta"}
 
 
def normalize_post_reducers_config(post_cfg: dict) -> dict:
    """!
    @brief Validate and canonicalize the reducers block of post.yml.
    @details A reducer reads the profiles `field_statistics` writes, so each task names a
             window or ensemble of the same recipe, and the recipe's `homogeneous` must
             leave the directions the task needs.
    @param[in] post_cfg Parsed post-processing configuration.
    @return Mapping with the canonical task list.
    """
    raw = (post_cfg or {}).get("reducers")
    if raw is None:
        return {"tasks": []}
    if not isinstance(raw, dict) or not isinstance(raw.get("tasks"), list) or not raw["tasks"]:
        raise ValueError("'reducers' must be a mapping with a non-empty 'tasks' list.")
    statistics = normalize_post_field_statistics_config(post_cfg)
    windows = set(statistics["windows"])
    owners = windows | {ensemble["name"] for ensemble in statistics["ensembles"]}
    retained = [axis for axis in ("i", "j", "k") if axis not in statistics["homogeneous"]]
    tasks = []
    for index, entry in enumerate(raw["tasks"]):
        if not isinstance(entry, dict):
            raise ValueError(f"'reducers.tasks[{index}]' must be a mapping.")
        name = entry.get("task")
        if not isinstance(name, str) or name not in POST_REDUCER_TASKS:
            raise ValueError(f"reducer task {name!r} is unknown. Available tasks: {sorted(POST_REDUCER_TASKS)}.")
        spec = POST_REDUCER_TASKS[name]
        label = f"reducer '{name}'"
        source = entry.get("source")
        if not isinstance(source, str) or source not in owners:
            raise ValueError(f"{label}: 'source' must name a field_statistics window or ensemble of this "
                             f"recipe (got {source!r}; available: {sorted(owners)}).")
        if "csv" not in statistics["formats"] or len(retained) != spec["retains"]:
            raise ValueError(f"{label} reads a profile keeping {spec['retains']} direction(s), so "
                             f"field_statistics needs 'csv' in formats and 'homogeneous' leaving that "
                             f"many (it leaves {retained}).")
        task = {"task": name, "source": source}
        if spec["axis_key"]:
            axis = entry.get(spec["axis_key"], spec["default_axis"])
            if axis not in _REDUCER_AXIS_TOKENS:
                raise ValueError(f"{label}: '{spec['axis_key']}' must be one of i, j, k (got {axis!r}).")
            kept = axis in retained
            if kept != (spec["axis_key"] == "wall_axis"):
                raise ValueError(f"{label}: the profile {'must keep' if not kept else 'must merge over'} "
                                 f"'{axis}', but 'homogeneous' is {statistics['homogeneous']}.")
            task[spec["axis_key"]] = axis
            stream = entry.get("stream_axis", "k")
            if stream not in _REDUCER_AXIS_TOKENS or stream == task.get("wall_axis"):
                raise ValueError(f"{label}: 'stream_axis' must be i, j or k and differ from the wall axis.")
            task["stream_axis"] = stream
            friction = entry.get("friction_velocity", "first_cell")
            if friction not in POST_REDUCER_FRICTION_SOURCES or (name == "cross_section" and friction == "wall_model"):
                raise ValueError(f"{label}: 'friction_velocity' must be one of "
                                 f"{[f for f in POST_REDUCER_FRICTION_SOURCES if name != 'cross_section' or f != 'wall_model']} "
                                 f"(got {friction!r}).")
            needs = POST_REDUCER_FRICTION_SOURCES.get(friction, {}).get("needs")
            if needs == "window" and source not in windows:
                raise ValueError(f"{label}: friction_velocity '{friction}' averages over a run window's time "
                                 f"bounds, so 'source' must be a run window, not an ensemble.")
            task["friction_velocity"] = friction
            if needs == "value":
                value = entry.get("value")
                if not isinstance(value, (int, float)) or isinstance(value, bool) or value <= 0:
                    raise ValueError(f"{label}: friction_velocity '{friction}' needs a positive 'value'.")
                task["value"] = float(value)
            if name == "cross_section":
                task["fold"] = bool(entry.get("fold", True))
            if name == "wall_profile" and entry.get("half_height") is not None:
                task["half_height"] = float(entry["half_height"])
        tasks.append(task)
    return {"tasks": tasks}
 
 
def run_post_reducers_stage(run_dir: str, post_cfg: dict, quiet: bool = False) -> list:
    """!
    @brief Run every reducer task over the profiles the recipe has written.
    @details Reducers read only small CSVs, so every profile present is reduced again on
             each invocation rather than tracked step by step. Inputs come from the run:
             the viscosity and reference scales from its case snapshot, the grid it was
             staged with, a window's effective bounds from each step's `checkpoint.meta`,
             and the runtime metrics CSVs.
    @param[in] run_dir Run directory.
    @param[in] post_cfg Post recipe with canonical paths applied.
    @param[in] quiet Suppress progress reporting.
    @return Absolute paths written.
    @throws ValueError when a reducer fails.
    """
    tasks = normalize_post_reducers_config(post_cfg)["tasks"]
    if not tasks:
        return []
    run_dir = os.path.abspath(run_dir)
    if not isinstance((post_cfg or {}).get("_picurv_paths"), dict):
        post_cfg, _ = apply_canonical_post_paths(post_cfg, run_dir)
    script = os.path.join(GENERATORS_PATH, "reduce.gen")
    grid = os.path.join(run_dir, "inputs", "grid", "grid.run")
    case_path = load_active_run_configuration(run_dir).get("case")
    case_cfg = read_yaml_file(case_path) if case_path and os.path.isfile(case_path) else {}
    scaling = resolve_fluid_scaling(case_cfg)
    dimensional = bool((post_cfg.get("global_operations") or {}).get("dimensionalize", False))
    velocity_scale = scaling["velocity_ref"] if dimensional else 1.0
    dt_physical = float((case_cfg.get("run_control") or {}).get("dt_physical", 0.0) or 0.0)
    step_time = dt_physical if dimensional else dt_physical / reference_scale(TIME, scaling)
    prefix = os.path.join(run_dir, post_cfg["_picurv_paths"]["field_statistics_prefix"])
    output_root = os.path.join(run_dir, CANONICAL_RUN_PATHS["output"])
    lineage = resolve_run_lineage(run_dir)
    written = []
 
    def lineage_metrics(name):
        """!
        @brief List a metrics CSV across the restart lineage, root to leaf.
        @details A window carried into a branched run spans its ancestors' time, whose
                 metrics rows are in their own files. Each ancestor's file is limited to
                 the steps up to the checkpoint its child branched from.
        @param[in] name Metrics CSV basename.
        @return `path` or `path@last_step` entries for every segment holding the file.
        """
        entries = []
        for index, segment in enumerate(lineage):
            path = os.path.join(segment["run_dir"], CANONICAL_RUN_PATHS["metrics"], name)
            if not os.path.isfile(path):
                continue
            child = lineage[index + 1] if index + 1 < len(lineage) else None
            entries.append(f"{path}@{child['fork_step']}" if child else path)
        return entries or [os.path.join(run_dir, CANONICAL_RUN_PATHS["metrics"], name)]
 
    def run(arguments, label):
        """!
        @brief Run one reduce.gen subcommand, failing with its own diagnostics.
        @param[in] arguments Subcommand and its arguments.
        @param[in] label Reducer and step named in a failure.
        """
        result = subprocess.run([sys.executable, script, *arguments], text=True, capture_output=True)
        if result.returncode != 0:
            raise ValueError(f"reducer {label} failed with exit code {result.returncode}:\n"
                             f"{(result.stderr or result.stdout).strip()}")
 
    for task in tasks:
        family = f"{prefix}_profile_{task['source']}"
        if task["task"] == "profile_series":
            output = f"{family}_history.csv"
            if _scan_post_vtk_steps(family, "csv"):
                run(["profile-series", "--profile-prefix", family, "--dt", repr(step_time),
                     "--output", output], f"profile_series of '{task['source']}'")
                written.append(output)
            continue
        friction = {"first_cell": [], "body_force": ["--body-force", repr(task.get("value"))],
                    "u_tau": ["--u-tau", repr(task.get("value"))],
                    "driven_flow": ["--driven-flow-csv", *lineage_metrics("driven_flow.csv")],
                    "wall_model": ["--wall-model-csv", *lineage_metrics("wall_model.csv")]}[task["friction_velocity"]]
        for step, path in sorted(_scan_post_vtk_steps(family, "csv").items()):
            arguments = [POST_REDUCER_TASKS[task["task"]]["command"], "--profile", path, "--grid", grid,
                         "--window", task["source"], "--viscosity",
                         repr(scaling["nondimensional_kinematic_viscosity"]),
                         "--velocity-scale", repr(velocity_scale),
                         "--stream-axis", _REDUCER_AXIS_TOKENS[task["stream_axis"]], *friction]
            metadata = os.path.join(_checkpoint_bundle_path(output_root, step), "checkpoint.meta")
            options = _read_checkpoint_options(metadata) if os.path.isfile(metadata) else {}
            for index in range(int(options.get("checkpoint_statistics_window_count", 0) or 0)):
                key = f"checkpoint_statistics_window_{index}_"
                if options.get(key + "name") == task["source"]:
                    arguments += ["--window-start", options[key + "effective_start"],
                                  "--window-end", options[key + "effective_end"],
                                  "--window-note", f"{options.get(key + 'state')}, "
                                                   f"{options.get(key + 'sample_count')} samples"]
            if task["task"] == "wall_profile":
                output = f"{prefix}_wall_profile_{task['source']}_{step}.csv"
                arguments += ["--wall-axis", _REDUCER_AXIS_TOKENS[task["wall_axis"]], "--output", output]
                if "half_height" in task:
                    arguments += ["--half-height", repr(task["half_height"])]
                written.append(output)
            else:
                output = f"{prefix}_cross_section_{task['source']}_{step}"
                arguments += ["--output-prefix", output] + ([] if task["fold"] else ["--no-fold"])
                written.append(output + "_cross_section.csv")
            run(arguments, f"{task['task']} of '{task['source']}' at step {step}")
    if not quiet:
        for path in written:
            print(f"[INFO] Reducer output: {os.path.relpath(path)}")
    return written
 
 
def _merge_spectra_rows(path: str, fieldnames: tuple, remeasured: set, new_rows: list) -> list:
    """!
    @brief Combine newly measured spectra rows with those already written for other steps.
    @details The file belongs to one recipe, whose identity covers the spectra settings, so
             its existing rows come from the same measurement. Rows for a re-measured step
             are replaced; rows for every other step are kept. A file whose columns differ
             is not merged: it was written by another format and is rewritten whole.
    @param[in] path Existing CSV path, which may be absent.
    @param[in] fieldnames Columns the new rows carry.
    @param[in] remeasured Steps measured in this invocation.
    @param[in] new_rows Rows measured in this invocation.
    @return All rows, ordered by step with each step's rows in their measured order.
    """
    kept = []
    try:
        with open(path, newline="", encoding="utf-8") as stream:
            reader = csv.DictReader(stream)
            if tuple(reader.fieldnames or ()) == tuple(fieldnames):
                kept = [row for row in reader if int(row["step"]) not in remeasured]
    except FileNotFoundError:
        pass
    return sorted(kept + list(new_rows), key=lambda row: int(row["step"]))
 
 
def compute_post_spectra_signature(spectra_cfg: dict) -> str:
    """!
    @brief Reduce a normalized spectra recipe to a stable identity string.
    @param[in] spectra_cfg Normalized spectra recipe.
    @return Hex digest covering every choice that changes the produced spectra.
    """
    payload = json.dumps(spectra_cfg, sort_keys=True, separators=(",", ":")).encode("utf-8")
    return hashlib.sha256(payload).hexdigest()[:16]
 
 
def resolve_post_spectra_output_dir(monitor_cfg=None) -> str:
    """!
    @brief Resolve the run-relative directory spectra CSVs are written to.
    @param[in] monitor_cfg Optional monitor configuration anchoring the output root.
    @return Run-relative directory path.
    """
    del monitor_cfg
    return CANONICAL_RUN_PATHS["spectra"]
 
 
def resolve_recipe_spectra_output_dir(post_cfg: dict, monitor_cfg=None) -> str:
    """!
    @brief Resolve the canonical spectra directory for one versioned recipe.
    @param[in] post_cfg Parsed runtime post config.
    @param[in] monitor_cfg Optional monitor config for standalone compatibility.
    @return Run-relative spectra directory.
    """
    internal = (post_cfg or {}).get("_picurv_paths", {}) or {}
    return internal.get("spectra") or resolve_post_spectra_output_dir(monitor_cfg)
 
 
def get_post_spectra_output_artifacts(post_cfg: dict, run_dir: str, monitor_cfg=None) -> list:
    """!
    @brief Predict the spectra CSV paths a recipe will write.
    @param[in] post_cfg Parsed post-processing configuration.
    @param[in] run_dir Run directory the recipe operates on.
    @param[in] monitor_cfg Optional monitor configuration anchoring the output root.
    @return Absolute CSV paths, one per task, in recipe order.
    """
    try:
        spectra = normalize_post_spectra_config(post_cfg)
    except ValueError:
        # The recipe reports its own errors during validation; predict nothing here.
        return []
    if not spectra["tasks"]:
        return []
    base = os.path.join(os.path.abspath(run_dir), resolve_recipe_spectra_output_dir(post_cfg, monitor_cfg))
    paths = []
    for task_cfg in spectra["tasks"]:
        name = post_spectra_task_basename(task_cfg, spectra["output_prefix"])
        paths.append(os.path.join(base, f"{name}.csv"))
    return list(dict.fromkeys(paths))
 
 
def post_spectra_task_basename(task_cfg: dict, output_prefix: str) -> str:
    """!
    @brief Build the file basename one normalized spectra task writes.
    @param[in] task_cfg Normalized task mapping.
    @param[in] output_prefix Recipe output prefix.
    @return Basename without directory or extension.
    """
    parts = [output_prefix, task_cfg["task"], task_cfg["field"],
             f"block{task_cfg['block']:04d}", task_cfg["symbol"]]
    if task_cfg["task"] != "shell_spectrum":
        parts.extend(["".join(task_cfg["axes"]), *[f"{a}{i}" for a,i in task_cfg["fixed_indices"].items()]])
    return "_".join(parts)
 
 
def _normalize_post_statistics_ensembles(raw) -> list:
    """!
    @brief Validate and canonicalize the ensembles a post recipe defines.
    @details An ensemble is a window over one instant: its samples are the particles in
             each cell, or each cell's own state, at the step being processed. It is
             defined in the recipe rather than the run, because it needs no state
             accumulated during the solve.
    @param[in] raw The recipe's `field_statistics.ensembles` list, or None.
    @return List of ensembles with name, source, fields and covariances.
    """
    if raw is None:
        return []
    if not isinstance(raw, list):
        raise ValueError("'field_statistics.ensembles' must be a list.")
    ensembles = []
    for index, entry in enumerate(raw):
        if not isinstance(entry, dict):
            raise ValueError(f"'field_statistics.ensembles[{index}]' must be a mapping.")
        name = entry.get("name")
        if not isinstance(name, str) or not name.strip():
            raise ValueError(f"'field_statistics.ensembles[{index}]' needs a non-empty 'name'.")
        name = name.strip()
        if any(existing["name"] == name for existing in ensembles):
            raise ValueError(f"field statistics ensemble '{name}' is defined more than once.")
        source = entry.get("source")
        if source not in POST_STATISTICS_ENSEMBLE_SOURCES:
            raise ValueError(
                f"field statistics ensemble '{name}': 'source' must be one of "
                f"{list(POST_STATISTICS_ENSEMBLE_SOURCES)} (got {source!r})."
            )
        fields, covariances = _normalize_statistics_requests(
            f"field statistics ensemble '{name}'", entry.get("fields"), entry.get("covariances"),
            _ensemble_source_fields(source))
        ensembles.append({"name": name, "source": source, "fields": fields, "covariances": covariances})
    return ensembles
 
 
def normalize_post_field_statistics_config(post_cfg: dict) -> dict:
    """!
    @brief Validate and canonicalize the field_statistics block of post.yml.
 
    @details The recipe names windows rather than redescribing them, because the
             window definitions already reach the post-processor through the run's
             solver control. Validation therefore covers the recipe's own choices
             only; a name no window matches is caught in C against the resolved list,
             which is the only place the real set is known.
 
    @param[in] post_cfg Parsed post-processing configuration.
    @return Value returned by `normalize_post_field_statistics_config()`.
    """
    raw = (post_cfg or {}).get("field_statistics")
    if raw is None:
        return {"windows": [], "ensembles": [], "homogeneous": [], "source_step": None,
                "outputs": [], "formats": []}
    if not isinstance(raw, dict):
        raise ValueError("'field_statistics' must be a mapping.")
 
    ensembles = _normalize_post_statistics_ensembles(raw.get("ensembles"))
    windows = raw.get("windows", [] if ensembles else None)
    if not isinstance(windows, list) or not (windows or ensembles):
        raise ValueError("'field_statistics.windows' must be a non-empty list of window names "
                         "unless 'ensembles' defines what to derive.")
    cleaned = []
    for entry in windows:
        if not isinstance(entry, str) or not entry.strip():
            raise ValueError("'field_statistics.windows' entries must be non-empty window names.")
        name = entry.strip()
        # Each window writes its own file, so a repeat would overwrite its own output.
        if name in cleaned:
            raise ValueError(f"field statistics recipe lists window '{name}' more than once.")
        cleaned.append(name)
    for ensemble in ensembles:
        if ensemble["name"] in cleaned:
            raise ValueError(f"field statistics ensemble '{ensemble['name']}' has the name of a "
                             "requested window; both would write the same files.")
 
    label = ", ".join(cleaned + [ensemble["name"] for ensemble in ensembles])
    source_step = raw.get("source_step")
    if source_step is not None:
        if not isinstance(source_step, int) or isinstance(source_step, bool) or source_step < 0:
            raise ValueError(
                f"field statistics recipe for [{label}]: 'source_step' must be a non-negative "
                f"integer (got {source_step!r})."
            )
 
    outputs = raw.get("outputs", list(POST_FIELD_STATISTICS_DEFAULT_OUTPUTS))
    if not isinstance(outputs, list) or not outputs:
        raise ValueError(f"field statistics recipe for [{label}]: 'outputs' must be a non-empty list.")
    unknown = [item for item in outputs if item not in POST_FIELD_STATISTICS_OUTPUTS]
    if unknown:
        raise ValueError(
            f"field statistics recipe for [{label}]: unknown outputs {unknown}. "
            f"Available outputs: {list(POST_FIELD_STATISTICS_OUTPUTS)}."
        )
    if len(set(outputs)) != len(outputs):
        raise ValueError(f"field statistics recipe for [{label}]: 'outputs' lists a duplicate.")
 
    formats = raw.get("formats", ["vtk"])
    if not isinstance(formats, list) or not formats:
        raise ValueError(f"field statistics recipe for [{label}]: 'formats' must be a non-empty list.")
    unknown = [item for item in formats if item not in POST_FIELD_STATISTICS_FORMATS]
    if unknown:
        raise ValueError(
            f"field statistics recipe for [{label}]: unknown formats {unknown}. "
            f"Available formats: {list(POST_FIELD_STATISTICS_FORMATS)}."
        )
    if len(set(formats)) != len(formats):
        raise ValueError(f"field statistics recipe for [{label}]: 'formats' lists a duplicate.")
 
    homogeneous = raw.get("homogeneous", [])
    if (not isinstance(homogeneous, list) or any(axis not in ("i", "j", "k") for axis in homogeneous)
            or len(set(homogeneous)) != len(homogeneous)):
        raise ValueError(
            f"field statistics recipe for [{label}]: 'homogeneous' must list distinct axes from "
            f"['i', 'j', 'k'] (got {homogeneous!r})."
        )
    # An ensemble has no convergence history, so its CSV output is the profile alone.
    if ensembles and "csv" in formats and not homogeneous:
        raise ValueError(
            f"field statistics recipe for [{label}]: an ensemble writes CSV only as a profile, "
            "so 'csv' needs 'homogeneous' to name the directions to merge over."
        )
 
    return {
        "windows": cleaned,
        "ensembles": ensembles,
        "homogeneous": [axis for axis in ("i", "j", "k") if axis in homogeneous],
        "source_step": source_step,
        "outputs": list(outputs),
        "formats": list(formats),
    }
 
 
def _post_window_derived_field_count(window_cfg: dict, outputs: list, eligible: dict = None) -> int:
    """!
    @brief Count the derived fields one window would produce for a set of outputs.
 
    @details Mirrors the resolution the C derivation performs, so a recipe that would
             produce an empty file is refused before the run rather than after it. Each
             output resolves against what the window accumulated: a window keeping only
             first moments has no stresses, RMS, or turbulent kinetic energy to give.
 
    @param[in] window_cfg Normalized window definition from monitor.yml.
    @param[in] outputs Requested output kinds.
    @param[in] eligible Field table the window's fields are named from; the Eulerian
                        table when None.
    @return Value returned by `_post_window_derived_field_count()`.
    """
    eligible = STATISTICS_ELIGIBLE_FIELDS if eligible is None else eligible
    fields = window_cfg.get("fields", []) or []
    covariances = window_cfg.get("covariances", []) or []
    with_second = [f for f in fields if "second" in (f.get("moments") or [])]
    total = 0
    for kind in outputs:
        if kind == "mean":
            total += len(fields)
        elif kind == "reynolds_stress":
            for entry in with_second:
                dof = eligible[entry["field"]]["components"]
                total += 6 if dof == 3 else 1
        elif kind == "rms":
            for entry in with_second:
                total += eligible[entry["field"]]["components"]
        elif kind == "tke":
            total += sum(1 for entry in with_second
                         if eligible[entry["field"]]["components"] == 3)
        elif kind == "flux":
            total += len(covariances)
    return total
 
 
def _post_requests_field_statistics(post_cfg: dict) -> bool:
    """!
    @brief Return whether the current post recipe derives accumulated field statistics.
    @param[in] post_cfg Argument passed to `_post_requests_field_statistics()`.
    @return Value returned by `_post_requests_field_statistics()`.
    """
    try:
        config = normalize_post_field_statistics_config(post_cfg)
        return bool(config["windows"] or config["ensembles"])
    except ValueError:
        # Malformed configuration is reported by validation, not by this predicate.
        return False
 
 
def get_post_field_statistics_artifacts(post_cfg: dict, run_dir: str):
    """!
    @brief Predict the per-window statistics artifacts a recipe will produce.
    @details Returns one entry per window and format, so resume tracking can tell a
             half-finished window from a completed one.
    @param[in] post_cfg Parsed post-processing configuration.
    @param[in] run_dir Run directory the outputs are written under.
    @return List of (kind, path_prefix, window) tuples; kind is 'vtk', 'csv' (a history
            shared by every step) or 'profile' (a prefix taking `_<step>.csv`). window is
            None for a recipe ensemble, which every processed step produces.
    """
    config = normalize_post_field_statistics_config(post_cfg)
    if not (config["windows"] or config["ensembles"]):
        return []
    io_cfg = post_cfg.get("io", {}) or {}
    internal = (post_cfg or {}).get("_picurv_paths", {}) or {}
    visualization_dir = _post_output_directory_abs(run_dir, post_cfg)
    visualization_prefix = io_cfg.get("output_filename_prefix", "Field")
    csv_prefix_path = None
    if internal.get("field_statistics_prefix"):
        csv_prefix_path = os.path.join(run_dir, internal["field_statistics_prefix"])
    csv_base = csv_prefix_path or os.path.join(visualization_dir, str(visualization_prefix))
    artifacts = []
    # An ensemble is built from the step itself, so every processed step produces it;
    # its entries carry no window, which marks them as always expected.
    owners = [(window, window) for window in config["windows"]]
    owners += [(ensemble["name"], None) for ensemble in config["ensembles"]]
    for name, window in owners:
        if "vtk" in config["formats"]:
            artifacts.append(("vtk", os.path.join(
                visualization_dir, f"{visualization_prefix}_statistics_{name}"
            ), window))
        if "csv" in config["formats"] and window is not None:
            artifacts.append(("csv", f"{csv_base}_statistics_{name}.csv", window))
        if "csv" in config["formats"] and config["homogeneous"]:
            artifacts.append(("profile", f"{csv_base}_profile_{name}", window))
    return artifacts
 
 
def build_post_recipe_config(post_cfg: dict, monitor_cfg=None) -> dict:
    """!
    @brief Build the flat key=value mapping consumed by the C post-processor.
    @param[in] post_cfg Argument passed to `build_post_recipe_config()`.
    @param[in] monitor_cfg Optional parsed monitor YAML configuration dictionary.
    @return Value returned by `build_post_recipe_config()`.
    """
    c_config = {}
 
    c_config['startTime'] = get_post_run_control_value(post_cfg, 'start_step', 0)
    c_config['endTime'] = get_post_run_control_value(post_cfg, 'end_step', 0)
    c_config['timeStep'] = get_post_run_control_value(post_cfg, 'step_interval', 1)
 
    eulerian_pipeline_parts = []
    dimensionalize = bool(post_cfg.get('global_operations', {}).get('dimensionalize', False))
    if dimensionalize:
        # A setting rather than a pipeline stage: loaded fields are scaled as they are
        # read, derived statistics in the accumulator, particles after their MSD, and
        # spectra in their generator, each once, where the value is produced.
        c_config['dimensionalize'] = 'true'
 
    for task in post_cfg.get('eulerian_pipeline', []):
        task_name = task.get('task')
        if task_name == 'q_criterion':
            eulerian_pipeline_parts.append('ComputeQCriterion')
        elif task_name == 'normalize_field':
            field = task.get('field', 'P')
            eulerian_pipeline_parts.append(f'NormalizeRelativeField:{field}')
            ref_point = task.get('reference_point', [1, 1, 1])
            c_config['reference_ip'] = ref_point[0]
            c_config['reference_jp'] = ref_point[1]
            c_config['reference_kp'] = ref_point[2]
        elif task_name == 'nodal_average':
            in_field = task.get('input_field')
            out_field = task.get('output_field')
            if in_field and out_field:
                eulerian_pipeline_parts.append(f'CellToNodeAverage:{in_field}>{out_field}')
 
    if eulerian_pipeline_parts:
        c_config['process_pipeline'] = ";".join(eulerian_pipeline_parts)
 
    lagrangian_pipeline_parts = []
    for task in post_cfg.get('lagrangian_pipeline', []):
        task_name = task.get('task')
        if task_name == 'specific_ke':
            in_field = task.get('input_field')
            out_field = task.get('output_field')
            if in_field and out_field:
                lagrangian_pipeline_parts.append(f'ComputeSpecificKE:{in_field}>{out_field}')
    if lagrangian_pipeline_parts:
        c_config['particle_pipeline'] = ";".join(lagrangian_pipeline_parts)
 
    statistics_pipeline_parts = get_post_statistics_task_tokens(post_cfg)
    statistics_output_prefix = None
    stats_cfg = post_cfg.get('statistics_pipeline')
    if isinstance(stats_cfg, dict):
        statistics_output_prefix = stats_cfg.get('output_prefix')
 
    if statistics_pipeline_parts:
        c_config['statistics_pipeline'] = ";".join(statistics_pipeline_parts)
        statistics_output_prefix = resolve_post_statistics_output_prefix(post_cfg, monitor_cfg)
    elif statistics_output_prefix is None:
        statistics_output_prefix = post_cfg.get('statistics_output_prefix')
    if statistics_output_prefix:
        c_config['statistics_output_prefix'] = statistics_output_prefix
 
    io = post_cfg.get('io', {})
    internal_paths = post_cfg.get('_picurv_paths', {}) or {}
    field_statistics = normalize_post_field_statistics_config(post_cfg)
    if field_statistics["windows"] or field_statistics["ensembles"]:
        c_config['field_statistics_windows'] = ",".join(field_statistics["windows"])
        c_config['field_statistics_outputs'] = ",".join(field_statistics["outputs"])
        c_config['field_statistics_formats'] = ",".join(field_statistics["formats"])
        # An omitted source step means each processed step derives from its own
        # bundle, which is what turns a multi-step recipe into a convergence history.
        if field_statistics["source_step"] is not None:
            c_config['field_statistics_source_step'] = field_statistics["source_step"]
        if internal_paths.get("field_statistics_prefix"):
            c_config['field_statistics_output_prefix'] = internal_paths["field_statistics_prefix"]
        if field_statistics["homogeneous"]:
            c_config['field_statistics_homogeneous'] = ",".join(field_statistics["homogeneous"])
        # Ensemble lines are the run windows' option families under the ensemble kind;
        # the post-processor forwards them to the window parser it shares.
        if field_statistics["ensembles"]:
            c_config['field_statistics_ensemble_count'] = len(field_statistics["ensembles"])
        for index, ensemble in enumerate(field_statistics["ensembles"]):
            prefix = f"field_statistics_ensemble_{index}"
            c_config[f'{prefix}_name'] = ensemble["name"]
            c_config[f'{prefix}_source'] = ensemble["source"]
            c_config[f'{prefix}_field_count'] = len(ensemble["fields"])
            for field_index, field_entry in enumerate(ensemble["fields"]):
                c_config[f'{prefix}_field_{field_index}_name'] = field_entry["field"]
                c_config[f'{prefix}_field_{field_index}_moments'] = ",".join(field_entry["moments"])
            c_config[f'{prefix}_covariance_count'] = len(ensemble["covariances"])
            for pair_index, pair in enumerate(ensemble["covariances"]):
                c_config[f'{prefix}_covariance_{pair_index}'] = f"{pair[0]},{pair[1]}"
 
    c_config['output_prefix'] = io.get('output_directory', 'viz') + '/' + io.get('output_filename_prefix', 'Field')
    c_config['particle_output_prefix'] = io.get('output_directory', 'viz') + '/' + io.get('particle_filename_prefix', 'Particle')
    c_config['output_particles'] = io.get('output_particles', False)
    c_config['particle_output_freq'] = io.get('particle_subsampling_frequency', 1)
    c_config['output_fields_instantaneous'] = ",".join(io.get('eulerian_fields', []))
    c_config['particle_fields_instantaneous'] = ",".join(io.get('particle_fields', []))
    input_extensions = get_post_input_extensions(post_cfg)
    if isinstance(input_extensions, dict):
        for extension_name in ('eulerian', 'particle'):
            extension = input_extensions.get(extension_name)
            if extension and str(extension).strip().lstrip('.').lower() != 'dat':
                raise ValueError(
                    f"post input extension '{extension_name}' must be 'dat'; "
                    "committed checkpoint payload names are fixed."
                )
 
    source_directory = get_post_source_directory_template(post_cfg, default=None)
    if source_directory is not None:
        c_config['source_directory'] = source_directory
 
    # Spectra run in the conductor's Python stage, but the recipe fingerprint is
    # computed over this mapping, so the block has to be represented here or a
    # changed spectra recipe would leave its steps' records looking valid. The C
    # post-processor accepts and ignores the key.
    spectra = normalize_post_spectra_config(post_cfg)
    if spectra["tasks"]:
        c_config['spectra_signature'] = compute_post_spectra_signature(spectra)
 
    return c_config
 
 
def compute_post_recipe_id(post_cfg: dict) -> str:
    """!
    @brief Compute a stable human-readable identity for one post recipe.
    @param[in] post_cfg Parsed post configuration before runtime path injection.
    @return Filesystem-safe recipe identity.
    """
    normalized = copy.deepcopy(post_cfg or {})
    normalized.pop("_picurv_paths", None)
    # source_data.directory is always replaced by the run's own output, so an absent
    # block and an emptied one are the same recipe; both hash as the emptied form that
    # every earlier recipe, which carried the directory, reduced to.
    source = normalized.setdefault("source_data", {})
    if isinstance(source, dict):
        source.pop("directory", None)
    io = normalized.get("io")
    label = "post"
    if isinstance(io, dict):
        io.pop("output_directory", None)
        # ParaView collection generation changes only how existing VTK artifacts are
        # indexed.  It must not split an otherwise identical computational recipe,
        # especially when a child enables lineage indexing for an ancestor whose VTK
        # files predate the option.
        io.pop("paraview_series", None)
        raw_label = io.get("output_filename_prefix")
        if isinstance(raw_label, str) and raw_label.strip():
            label = re.sub(r"[^A-Za-z0-9_.-]+", "-", raw_label.strip()).strip("-") or "post"
    run_control = normalized.get("run_control")
    if isinstance(run_control, dict):
        for key in POST_RUN_CONTROL_ALIASES["start_step"] + POST_RUN_CONTROL_ALIASES["end_step"]:
            run_control.pop(key, None)
    # Reducers read the recipe's outputs without changing them, so adding or revising
    # one must not move the recipe to a new home and recompute every field.
    normalized.pop("reducers", None)
    digest = hashlib.sha256(
        json.dumps(normalized, sort_keys=True, separators=(",", ":")).encode("utf-8")
    ).hexdigest()[:12]
    return f"{label}-{digest}"
 
 
def apply_canonical_post_paths(post_cfg: dict, run_dir: str) -> "tuple[dict, str]":
    """!
    @brief Route every post artifact into its fixed analysis or visualization home.
    @param[in] post_cfg Parsed user recipe.
    @param[in] run_dir Run receiving derived artifacts.
    @return Runtime-only config copy and stable recipe id.
    """
    recipe_id = compute_post_recipe_id(post_cfg)
    runtime = copy.deepcopy(post_cfg)
    if not isinstance(runtime.get("source_data"), dict):
        runtime["source_data"] = {}
    runtime["source_data"]["directory"] = os.path.join(
        os.path.abspath(run_dir), CANONICAL_RUN_PATHS["output"]
    )
    io = runtime.setdefault("io", {})
    io["output_directory"] = os.path.join(CANONICAL_RUN_PATHS["visualization"], recipe_id)
    output_prefix = io.get("output_filename_prefix", "Field")
    stats_cfg = runtime.get("statistics_pipeline")
    if isinstance(stats_cfg, dict):
        basename = stats_cfg.get("output_prefix", "Stats")
        stats_cfg["output_prefix"] = os.path.join(
            CANONICAL_RUN_PATHS["statistics"], recipe_id, os.path.basename(str(basename))
        )
    runtime["_picurv_paths"] = {
        "recipe_id": recipe_id,
        "recipe_root": os.path.join("config", "post-recipes", recipe_id),
        "visualization": io["output_directory"],
        "statistics": os.path.join(CANONICAL_RUN_PATHS["statistics"], recipe_id),
        "field_statistics_prefix": os.path.join(
            CANONICAL_RUN_PATHS["statistics"], recipe_id, str(output_prefix)
        ),
        "spectra": os.path.join(CANONICAL_RUN_PATHS["spectra"], recipe_id),
    }
    return runtime, recipe_id
 
 
def normalize_post_recipe_signature(recipe_cfg: dict) -> dict:
    """!
    @brief Normalize post recipe settings into a stable signature mapping.
    @param[in] recipe_cfg Argument passed to `normalize_post_recipe_signature()`.
    @return Value returned by `normalize_post_recipe_signature()`.
    """
    signature = {}
    for key, value in (recipe_cfg or {}).items():
        if key in POST_RECIPE_SIGNATURE_EXCLUDED_KEYS or value is None:
            continue
        if isinstance(value, bool):
            text = 'true' if value else 'false'
        else:
            text = str(value).strip()
            if text.lower() in {'true', 'false'}:
                text = text.lower()
        if text:
            signature[str(key)] = text
    return signature
 
 
def compute_post_recipe_fingerprint(recipe_cfg: dict) -> "tuple[dict, str]":
    """!
    @brief Return normalized recipe signature plus SHA-256 fingerprint.
    @param[in] recipe_cfg Argument passed to `compute_post_recipe_fingerprint()`.
    @return Value returned by `compute_post_recipe_fingerprint()`.
    """
    signature = normalize_post_recipe_signature(recipe_cfg)
    payload = json.dumps(signature, sort_keys=True, separators=(',', ':')).encode('utf-8')
    return signature, hashlib.sha256(payload).hexdigest()
 
 
def get_post_resume_state_path(run_dir: str, post_cfg: dict = None) -> str:
    """!
    @brief Return the JSON resume metadata path for a run directory.
    @param[in] run_dir Argument passed to `get_post_resume_state_path()`.
    @param[in] post_cfg Optional versioned post recipe configuration.
    @return Value returned by `get_post_resume_state_path()`.
    """
    if post_cfg is None:
        return os.path.join(run_dir, 'config', POST_RESUME_STATE_FILENAME)
    return os.path.join(get_post_recipe_root(run_dir, post_cfg), "state.json")
 
 
def get_post_recipe_root(run_dir: str, post_cfg: dict) -> str:
    """!
    @brief Return the versioned run-local control directory for one post recipe.
    @param[in] run_dir Owning run root.
    @param[in] post_cfg Runtime post config with canonical paths, or a user recipe.
    @return Absolute recipe control directory.
    """
    internal = (post_cfg or {}).get("_picurv_paths", {}) or {}
    recipe_id = internal.get("recipe_id") or compute_post_recipe_id(post_cfg)
    return os.path.join(os.path.abspath(run_dir), "config", "post-recipes", recipe_id)
 
 
def get_post_lock_paths(run_dir: str, recipe_id: str = None) -> dict:
    """!
    @brief Return lock-wrapper related paths for a run directory.
    @param[in] run_dir Argument passed to `get_post_lock_paths()`.
    @param[in] recipe_id Optional stable recipe identity used to scope the lock.
    @return Value returned by `get_post_lock_paths()`.
    """
    scheduler_dir = os.path.join(run_dir, 'scheduler')
    suffix = f".{recipe_id}" if recipe_id else ""
    return {
        'lock_file': os.path.join(scheduler_dir, f"post{suffix}.lock"),
        'metadata_file': os.path.join(scheduler_dir, f"post{suffix}.lock.json"),
        'wrapper_path': os.path.join(scheduler_dir, POST_LOCK_WRAPPER_FILENAME),
    }
 
 
def _post_output_directory_abs(run_dir: str, post_cfg: dict) -> str:
    """!
    @brief Resolve the absolute post output directory for the current recipe.
    @param[in] run_dir Argument passed to `_post_output_directory_abs()`.
    @param[in] post_cfg Argument passed to `_post_output_directory_abs()`.
    @return Value returned by `_post_output_directory_abs()`.
    """
    io_cfg = post_cfg.get('io', {}) or {}
    internal = (post_cfg or {}).get("_picurv_paths", {}) or {}
    relative = internal.get("visualization") or io_cfg.get('output_directory')
    if not relative:
        relative = os.path.join(CANONICAL_RUN_PATHS["visualization"], compute_post_recipe_id(post_cfg))
    return os.path.abspath(os.path.join(run_dir, relative))
 
 
def _post_requests_eulerian_output(post_cfg: dict) -> bool:
    """!
    @brief Return whether the current post recipe expects Eulerian VTK output artifacts.
    @param[in] post_cfg Argument passed to `_post_requests_eulerian_output()`.
    @return Value returned by `_post_requests_eulerian_output()`.
    """
    io_cfg = post_cfg.get('io', {}) or {}
    return bool(io_cfg.get('eulerian_fields'))
 
 
def _post_requests_particle_output(post_cfg: dict) -> bool:
    """!
    @brief Return whether the current post recipe expects particle VTP output artifacts.
    @param[in] post_cfg Argument passed to `_post_requests_particle_output()`.
    @return Value returned by `_post_requests_particle_output()`.
    """
    io_cfg = post_cfg.get('io', {}) or {}
    return bool(io_cfg.get('output_particles')) and bool(io_cfg.get('particle_fields'))
 
 
POST_PARAVIEW_SERIES_SCOPES = {"run", "lineage"}
 
 
def normalize_post_paraview_series_config(post_cfg: dict) -> dict:
    """!
    @brief Normalize the optional ParaView collection policy in a post recipe.
    @param[in] post_cfg Parsed post-processing configuration.
    @return Mapping with enabled and scope keys.
    """
    raw = ((post_cfg or {}).get("io") or {}).get("paraview_series")
    if raw is None:
        return {"enabled": False, "scope": "run"}
    if isinstance(raw, bool):
        return {"enabled": raw, "scope": "lineage" if raw else "run"}
    if not isinstance(raw, dict):
        raise ValueError("'io.paraview_series' must be a boolean or mapping.")
    enabled = raw.get("enabled", True)
    scope = str(raw.get("scope", "lineage")).strip().lower()
    if not isinstance(enabled, bool):
        raise ValueError("'io.paraview_series.enabled' must be a boolean.")
    if scope not in POST_PARAVIEW_SERIES_SCOPES:
        raise ValueError("'io.paraview_series.scope' must be 'run' or 'lineage'.")
    return {"enabled": enabled, "scope": scope}
 
 
def _resolve_lineage_parent_run(child_run_dir: str, lineage: dict) -> str:
    """!
    @brief Resolve and identity-check one recorded lineage parent.
    @param[in] child_run_dir Child run directory used to resolve workspace-relative paths.
    @param[in] lineage Recorded branch-lineage mapping.
    @return Absolute path to the identity-matched parent run.
    """
    recorded = lineage.get("parent_path")
    parent_id = lineage.get("parent_run_id")
    if not recorded or not parent_id:
        raise ValueError(f"Run lineage is missing parent_path or parent_run_id: {child_run_dir}")
    if os.path.isabs(str(recorded)):
        candidates = [os.path.abspath(str(recorded))]
    else:
        workspace_root = find_workspace_root(child_run_dir)
        candidates = ([os.path.abspath(os.path.join(workspace_root, str(recorded)))]
                      if workspace_root else [])
    workspace_root = find_workspace_root(child_run_dir)
    if workspace_root:
        runs_root = os.path.join(workspace_root, "runs")
        if os.path.isdir(runs_root):
            candidates.extend(
                os.path.join(runs_root, name) for name in os.listdir(runs_root)
                if os.path.isdir(os.path.join(runs_root, name))
            )
    seen = set()
    for candidate in candidates:
        candidate = os.path.abspath(candidate)
        if candidate in seen or not os.path.isdir(candidate):
            continue
        seen.add(candidate)
        try:
            identity = read_artifact_identity(candidate)
        except (OSError, ValueError, KeyError):
            continue
        if identity.get("run_id") == parent_id:
            return candidate
    raise ValueError(
        f"Lineage parent '{parent_id}' for run '{os.path.basename(child_run_dir)}' "
        f"could not be resolved from recorded path '{recorded}'."
    )
 
 
def resolve_run_lineage(run_dir: str, scope: str = "lineage") -> list:
    """!
    @brief Return root-to-leaf run segments, for a ParaView collection or a reducer's metrics.
    @param[in] run_dir Leaf run whose lineage is resolved.
    @param[in] scope Either run-local or full-lineage collection scope.
    @return Ordered run-segment mappings from root to leaf.
    @details Each entry carries the run path, manifest, and the checkpoint at which
             that run branched from its parent. Cycles and unresolved parents fail.
    """
    current = os.path.abspath(run_dir)
    reverse = []
    seen_ids = set()
    while True:
        manifest = _read_json_if_exists(os.path.join(current, "manifest.json")) or {}
        run_id = manifest.get("run_id") or os.path.basename(current)
        if run_id in seen_ids:
            chain = " -> ".join([entry["run_id"] for entry in reversed(reverse)] + [run_id])
            raise ValueError(f"Cycle detected while resolving visualization lineage: {chain}")
        seen_ids.add(run_id)
        lineage = manifest.get("lineage") or {"relationship": "root"}
        reverse.append({
            "run_dir": current,
            "run_id": run_id,
            "manifest": manifest,
            "lineage": lineage,
            "fork_step": (int(lineage["checkpoint_step"])
                          if lineage.get("relationship") == "branch" else None),
        })
        if scope == "run" or lineage.get("relationship") != "branch":
            break
        current = _resolve_lineage_parent_run(current, lineage)
    return list(reversed(reverse))
 
 
def _existing_pvd_times(pvd_path: str) -> dict:
    """!
    @brief Read step-to-time fallbacks from an existing PVD collection.
    @param[in] pvd_path Existing collection path.
    @return Mapping from output step to physical time.
    """
    if not os.path.isfile(pvd_path):
        return {}
    try:
        root = ElementTree.parse(pvd_path).getroot()
    except (ElementTree.ParseError, OSError):
        return {}
    result = {}
    for dataset in root.findall(".//DataSet"):
        filename = os.path.basename(dataset.get("file", ""))
        match = re.search(r"_(\d+)\.(?:vts|vtp)$", filename)
        try:
            if match:
                result[int(match.group(1))] = float(dataset.get("timestep"))
        except (TypeError, ValueError):
            continue
    return result
 
 
def _checkpoint_time_for_series(run_dir: str, step: int, fallback: dict, time_scale: float = 1.0) -> float:
    """!
    @brief Read the authoritative time of one visualization frame.
    @details Checkpoints record solver time. A dimensionalized recipe writes physical
             frames, so its collection reports physical time: the checkpoint time
             multiplied by the owning run's reference time.
    @param[in] run_dir Run owning the frame.
    @param[in] step Frame checkpoint step.
    @param[in] fallback Existing collection times, already in the collection's units,
               used after checkpoint pruning.
    @param[in] time_scale Factor from solver time to the collection's time unit.
    @return Frame time in the collection's unit system.
    """
    metadata_path = os.path.join(
        run_dir, CANONICAL_RUN_PATHS["checkpoints"],
        f"step_{step:0{CHECKPOINT_STEP_WIDTH}d}", "checkpoint.meta",
    )
    commit_path = os.path.join(os.path.dirname(metadata_path), "COMMITTED")
    if os.path.isfile(metadata_path) and os.path.isfile(commit_path):
        options = _read_checkpoint_options(metadata_path)
        try:
            recorded_step = int(options["checkpoint_step"])
            physical_time = float(options["checkpoint_time"])
        except (KeyError, TypeError, ValueError) as exc:
            raise ValueError(f"Checkpoint time metadata is malformed: {metadata_path}") from exc
        if recorded_step != step or not math.isfinite(physical_time):
            raise ValueError(f"Checkpoint time metadata does not match step {step}: {metadata_path}")
        return physical_time * time_scale
    if step in fallback:
        return float(fallback[step])
    raise ValueError(
        f"Visualization frame at step {step} has no locally available checkpoint time in "
        f"'{run_dir}'. Restore its checkpoints or retain an existing PVD carrying the time."
    )
 
 
def _write_pvd_collection(path: str, entries: list) -> None:
    """!
    @brief Atomically write one VTK Collection file.
    @param[in] path Destination PVD path.
    @param[in] entries Ordered frame mappings.
    @return None.
    """
    root = ElementTree.Element("VTKFile", {
        "type": "Collection", "version": "0.1", "byte_order": "LittleEndian",
    })
    collection = ElementTree.SubElement(root, "Collection")
    base = os.path.dirname(os.path.abspath(path))
    for entry in entries:
        ElementTree.SubElement(collection, "DataSet", {
            "timestep": format(float(entry["time"]), ".17g"),
            "group": "", "part": "0",
            "file": os.path.relpath(entry["path"], base).replace(os.sep, "/"),
        })
    content = '<?xml version="1.0"?>\n' + ElementTree.tostring(root, encoding="unicode") + "\n"
    os.makedirs(base, exist_ok=True)
    temporary = f"{path}.tmp.{os.getpid()}"
    try:
        with open(temporary, "w", encoding="utf-8") as stream:
            stream.write(content)
            stream.flush()
            os.fsync(stream.fileno())
        os.replace(temporary, path)
    finally:
        if os.path.exists(temporary):
            os.unlink(temporary)
 
 
def _lineage_reset_index(segments: list, family: str) -> int:
    """!
    @brief Return the first segment belonging to one continuous artifact family.
    @param[in] segments Root-to-leaf lineage segments.
    @param[in] family Artifact family being indexed.
    @return Index of the first segment after the last relevant reset.
    """
    start = 0
    for index, segment in enumerate(segments[1:], start=1):
        if family == "particle":
            case_path = os.path.join(segment["run_dir"], "config", "case.yml")
            case_cfg = read_yaml_file(case_path) if os.path.isfile(case_path) else {}
            particles = (((case_cfg.get("models") or {}).get("physics") or {}).get("particles") or {})
            if str(particles.get("restart_mode", "init")).strip().lower() != "load":
                start = index
        elif family == "statistics":
            if str(segment["lineage"].get("statistics_state", "reset")).lower() != "carry":
                start = index
    return start
 
 
def finalize_post_paraview_series(run_dir: str, post_cfg: dict) -> list:
    """!
    @brief Build physical-time ParaView collections from current or lineage VTK output.
    @param[in] run_dir Leaf run receiving the collection.
    @param[in] post_cfg Parsed post-processing recipe.
    @return Absolute PVD paths written. Disabled recipes return an empty list.
    """
    policy = normalize_post_paraview_series_config(post_cfg)
    if not policy["enabled"]:
        return []
    run_dir = os.path.abspath(run_dir)
    if not isinstance((post_cfg or {}).get("_picurv_paths"), dict):
        post_cfg, _ = apply_canonical_post_paths(post_cfg, run_dir)
    recipe_id = post_cfg["_picurv_paths"]["recipe_id"]
    requested_start, requested_end, _interval = resolve_post_requested_window(
        post_cfg,
        read_yaml_file(os.path.join(run_dir, "config", "case.yml")),
    )
    segments = resolve_run_lineage(run_dir, policy["scope"])
    io_cfg = post_cfg.get("io", {}) or {}
    families = []
    if _post_requests_eulerian_output(post_cfg):
        families.append(("field", io_cfg.get("output_filename_prefix", "Field"), "vts"))
    if _post_requests_particle_output(post_cfg):
        families.append(("particle", io_cfg.get("particle_filename_prefix", "Particle"), "vtp"))
    for kind, prefix_path, _window in get_post_field_statistics_artifacts(post_cfg, run_dir):
        if kind == "vtk":
            families.append(("statistics", os.path.basename(prefix_path), "vts"))
 
    # Each run's frames are timed by that run's own reference time, so a lineage stays
    # physically continuous even across runs whose scales differ.
    dimensionalize = bool((post_cfg.get("global_operations") or {}).get("dimensionalize", False))
 
    def segment_time_scale(segment: dict) -> float:
        """!
        @brief Return the factor from one lineage run's solver time to the collection's time.
        @param[in] segment Lineage segment.
        @return Reference time of the run when dimensionalizing, otherwise 1.
        """
        if not dimensionalize:
            return 1.0
        case_path = os.path.join(segment["run_dir"], "config", "case.yml")
        return reference_scale(TIME, resolve_reference_scales(read_yaml_file(case_path)))
 
    written = []
    for family, prefix, extension in families:
        active_segments = segments[_lineage_reset_index(segments, family):]
        entries = []
        for index, segment in enumerate(active_segments):
            lower = requested_start
            if segment["fork_step"] is not None:
                lower = max(lower, int(segment["fork_step"]))
            upper = requested_end
            if index + 1 < len(active_segments):
                upper = min(upper, int(active_segments[index + 1]["fork_step"]) - 1)
            if lower > upper:
                continue
            viz_dir = os.path.join(
                segment["run_dir"], CANONICAL_RUN_PATHS["visualization"], recipe_id
            )
            pvd_path = os.path.join(viz_dir, f"{prefix}.pvd")
            fallback = _existing_pvd_times(pvd_path)
            pattern = re.compile(rf"^{re.escape(prefix)}_(\d+)\.{re.escape(extension)}$")
            found = []
            if os.path.isdir(viz_dir):
                for name in os.listdir(viz_dir):
                    match = pattern.match(name)
                    if match and lower <= int(match.group(1)) <= upper:
                        found.append((int(match.group(1)), os.path.join(viz_dir, name)))
            if not found and index + 1 < len(active_segments):
                raise ValueError(
                    f"Lineage run '{segment['run_id']}' has no {prefix} visualization "
                    f"frames for its required segment {lower}..{upper} and recipe '{recipe_id}'."
                )
            for step, frame_path in sorted(found):
                entries.append({
                    "step": step,
                    "time": _checkpoint_time_for_series(segment["run_dir"], step, fallback,
                                                        segment_time_scale(segment)),
                    "path": os.path.abspath(frame_path),
                    "run_id": segment["run_id"],
                })
        if not entries:
            continue
        for previous, current in zip(entries, entries[1:]):
            if current["time"] <= previous["time"]:
                raise ValueError(
                    f"ParaView series time is not strictly increasing: {previous['run_id']} "
                    f"step {previous['step']} has {previous['time']:.17g}, followed by "
                    f"{current['run_id']} step {current['step']} at {current['time']:.17g}."
                )
        output_dir = _post_output_directory_abs(run_dir, post_cfg)
        output_path = os.path.join(output_dir, f"{prefix}.pvd")
        _write_pvd_collection(output_path, entries)
        print(
            f"[SUCCESS] Wrote ParaView {family} series: {output_path} "
            f"({len(entries)} frame(s), time {entries[0]['time']:.17g}..{entries[-1]['time']:.17g})"
        )
        written.append(output_path)
    return written
 
 
def _post_finalize_python_source() -> str:
    """!
    @brief Return the importable serial finalizer used by generated jobs.
    @return Python source suitable for a serial interpreter invocation.
    """
    package_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
    return (
        "import os,sys;"
        f"sys.path.insert(0,{package_root!r});"
        "from picurv_cli.core import read_yaml_file,apply_canonical_post_paths,finalize_post_outputs;"
        "run=os.path.abspath(sys.argv[1]);cfg=read_yaml_file(sys.argv[2]);"
        "cfg,_=apply_canonical_post_paths(cfg,run);finalize_post_outputs(run,cfg,(sys.argv[3] if len(sys.argv)>3 else '').split(','))"
    )
 
 
def build_post_finalize_command(run_dir: str, archived_post_path: str, post_cfg: dict,
                                post_stages=POST_STAGE_NAMES) -> list:
    """!
    @brief Build the serial post-success command for staged execution.
    @details It runs after the field post-processor succeeds, in the conductor or in the
             submitted job, so whatever reads the field stage's output belongs here: the
             ParaView collections and the reducers.
    @param[in] run_dir Run receiving the collection.
    @param[in] archived_post_path Archived post recipe read by the finalizer.
    @param[in] post_cfg Parsed post-processing recipe.
    @param[in] post_stages Selected post stages; reducers run only when selected.
    @return Command tokens, or an empty list when there is nothing to finalize.
    """
    reducers = "reducers" in post_stages and bool(normalize_post_reducers_config(post_cfg)["tasks"])
    if not normalize_post_paraview_series_config(post_cfg)["enabled"] and not reducers:
        return []
    return [
        sys.executable, "-c", _post_finalize_python_source(),
        os.path.abspath(run_dir), os.path.abspath(archived_post_path),
        "reducers" if reducers else "-",
    ]
 
 
def finalize_post_outputs(run_dir: str, post_cfg: dict, stages) -> None:
    """!
    @brief Run every serial step that reads a successful field stage's output.
    @param[in] run_dir Run directory.
    @param[in] post_cfg Recipe with canonical paths applied.
    @param[in] stages Stage names the finalizer covers beyond the collections.
    @return None.
    """
    finalize_post_paraview_series(run_dir, post_cfg)
    if "reducers" in stages:
        run_post_reducers_stage(run_dir, post_cfg)
 
 
def _post_requests_statistics(post_cfg: dict) -> bool:
    """!
    @brief Return whether the current post recipe expects statistics CSV artifacts.
    @param[in] post_cfg Argument passed to `_post_requests_statistics()`.
    @return Value returned by `_post_requests_statistics()`.
    """
    return bool(get_post_statistics_task_tokens(post_cfg))
 
 
def _post_needs_particle_source(post_cfg: dict) -> bool:
    """!
    @brief Return whether the current post recipe requires particle source files to be present.
    @param[in] post_cfg Argument passed to `_post_needs_particle_source()`.
    @return Value returned by `_post_needs_particle_source()`.
    """
    io_cfg = post_cfg.get('io', {}) or {}
    return bool(io_cfg.get('output_particles')) or bool(post_cfg.get('lagrangian_pipeline')) or _post_requests_statistics(post_cfg)
 
 
def _iter_post_steps(start_step: int, end_step: int, step_interval: int):
    """!
    @brief Yield configured post-processing steps inclusively.
    @param[in] start_step Argument passed to `_iter_post_steps()`.
    @param[in] end_step Argument passed to `_iter_post_steps()`.
    @param[in] step_interval Argument passed to `_iter_post_steps()`.
    """
    if step_interval <= 0 or end_step < start_step:
        return
    step = start_step
    while step <= end_step:
        yield step
        step += step_interval
 
 
def resolve_post_requested_window(post_cfg: dict, case_cfg: dict = None) -> "tuple[int, int, int]":
    """!
    @brief Resolve post requested start/end/interval, expanding end=-1 via case.yml when available.
    @param[in] post_cfg Argument passed to `resolve_post_requested_window()`.
    @param[in] case_cfg Optional case configuration for end-step expansion.
    @return Value returned by `resolve_post_requested_window()`.
    """
    start_step = int(get_post_run_control_value(post_cfg, 'start_step', 0) or 0)
    end_step = int(get_post_run_control_value(post_cfg, 'end_step', 0) or 0)
    step_interval = int(get_post_run_control_value(post_cfg, 'step_interval', 1))
    if step_interval <= 0:
        raise ValueError('run_control.step_interval must be positive.')
    if end_step < 0 and case_cfg:
        case_run = case_cfg.get('run_control', {}) or {}
        case_start = int(case_run.get('start_step', 0) or 0)
        case_total = int(case_run.get('total_steps', 0) or 0)
        end_step = case_start + case_total
    return start_step, end_step, step_interval
 
 
def resolve_post_owned_start(run_dir: str, post_cfg: dict, requested_start: int,
                             step_interval: int) -> int:
    """!
    @brief Intersect a recipe's logical cadence with this run's branch.
    @details A branch run holds checkpoints only from the step it forked at, so steps
             before it belong to its ancestors and never appear here; the run's window
             starts at its first cadence step at or after the fork.
    @param[in] run_dir Run whose branch ownership is inspected.
    @param[in] post_cfg Parsed post-processing recipe.
    @param[in] requested_start Logical recipe start step.
    @param[in] step_interval Logical recipe cadence.
    @return First cadence step owned by the run.
    """
    del post_cfg
    manifest = _read_json_if_exists(os.path.join(run_dir, "manifest.json")) or {}
    lineage = manifest.get("lineage") or {}
    if lineage.get("relationship") != "branch":
        return requested_start
    fork_step = int(lineage["checkpoint_step"])
    if fork_step <= requested_start:
        return requested_start
    intervals = (fork_step - requested_start + step_interval - 1) // step_interval
    return requested_start + intervals * step_interval
 
 
def prepare_effective_post_config(post_cfg: dict, resolved_source_dir: str, start_step: int = None, end_step: int = None) -> dict:
    """!
    @brief Return a copy of post_cfg with resolved source dir and optional effective bounds.
    @param[in] post_cfg Argument passed to `prepare_effective_post_config()`.
    @param[in] resolved_source_dir Argument passed to `prepare_effective_post_config()`.
    @param[in] start_step Argument passed to `prepare_effective_post_config()`.
    @param[in] end_step Argument passed to `prepare_effective_post_config()`.
    @return Value returned by `prepare_effective_post_config()`.
    """
    effective_cfg = copy.deepcopy(post_cfg)
    if not isinstance(effective_cfg.get('source_data'), dict):
        effective_cfg['source_data'] = {}
    effective_cfg['source_data']['directory'] = resolved_source_dir
    rc = effective_cfg.setdefault('run_control', {})
    if start_step is not None:
        rc['start_step'] = int(start_step)
    if end_step is not None:
        rc['end_step'] = int(end_step)
    return effective_cfg
 
 
def _scan_post_vtk_steps(prefix_path: str, extension: str) -> "dict[int, str]":
    """!
    @brief Collect the VTK files named with a prefix, step suffix, and extension.
    @param[in] prefix_path Output path prefix before the numeric step suffix.
    @param[in] extension VTK file extension to match without its leading dot.
    @return Mapping of each step number to its file path in the prefix directory.
    """
    directory = os.path.dirname(prefix_path)
    if not os.path.isdir(directory):
        return {}
    basename = os.path.basename(prefix_path)
    pattern = re.compile(rf'^{re.escape(basename)}_(\d+)\.{re.escape(extension)}$')
    steps = {}
    for name in os.listdir(directory):
        match = pattern.match(name)
        if match:
            steps[int(match.group(1))] = os.path.join(directory, name)
    return steps
 
 
def _scan_post_statistics_csv_steps(csv_path: str) -> "set[int]":
    """!
    @brief Scan step ids from the first CSV column of a statistics artifact.
    @param[in] csv_path Argument passed to `_scan_post_statistics_csv_steps()`.
    @return Value returned by `_scan_post_statistics_csv_steps()`.
    """
    if not os.path.isfile(csv_path):
        return set()
    steps = set()
    with open(csv_path, 'r', encoding='utf-8', errors='replace', newline='') as f:
        reader = csv.reader(f)
        for row in reader:
            if not row:
                continue
            head = str(row[0]).strip().lower()
            if head in {'step', 'timestep', 'time_step'}:
                continue
            step_val = _parse_int_loose(row[0])
            if step_val is not None:
                steps.add(step_val)
    return steps
 
 
def collect_post_completion_families(run_dir: str, post_cfg: dict, monitor_cfg=None) -> "list[tuple]":
    """!
    @brief Collect the output files each output family of the current recipe holds per step.
    @param[in] run_dir Argument passed to `collect_post_completion_families()`.
    @param[in] post_cfg Argument passed to `collect_post_completion_families()`.
    @param[in] monitor_cfg Optional parsed monitor YAML configuration dictionary.
    @return (step-to-path mapping, window, per_step) per family; window names the
            field-statistics window a family belongs to, or is None for a family every
            processed step must produce; per_step is False for a CSV shared by all steps.
    """
    io_cfg = post_cfg.get('io', {}) or {}
    output_dir_abs = _post_output_directory_abs(run_dir, post_cfg)
    families = []
 
    def csv_family(path):
        """!
        @brief Map every step a shared CSV holds to that CSV.
        @param[in] path CSV artifact path.
        @return Mapping of step to the CSV path.
        """
        return {step: path for step in _scan_post_statistics_csv_steps(path)}
 
    if _post_requests_eulerian_output(post_cfg):
        prefix = os.path.join(output_dir_abs, io_cfg.get('output_filename_prefix', 'Field'))
        families.append((_scan_post_vtk_steps(prefix, 'vts'), None, True))
 
    if _post_requests_particle_output(post_cfg):
        prefix = os.path.join(output_dir_abs, io_cfg.get('particle_filename_prefix', 'Particle'))
        families.append((_scan_post_vtk_steps(prefix, 'vtp'), None, True))
 
    for stats_path in get_post_statistics_output_artifacts(post_cfg, run_dir, monitor_cfg):
        families.append((csv_family(stats_path), None, False))
 
    # Each window and format is its own family, so a run that produced the Eulerian
    # fields but not the statistics is not mistaken for a completed step.
    for kind, path, window in get_post_field_statistics_artifacts(post_cfg, run_dir):
        if kind == 'vtk':
            families.append((_scan_post_vtk_steps(path, 'vts'), window, True))
        elif kind == 'profile':
            families.append((_scan_post_vtk_steps(path, 'csv'), window, True))
        else:
            families.append((csv_family(path), window, False))
 
    return families
 
 
def _field_statistics_window_samples(run_dir: str, step: int):
    """!
    @brief Read each field-statistics window's sample count from one committed checkpoint.
    @param[in] run_dir Run directory whose output holds the checkpoint.
    @param[in] step Checkpoint step.
    @return Mapping of window name to sample count, or None when the metadata is absent
            (never written, pruned, or offloaded).
    """
    metadata = os.path.join(
        _checkpoint_bundle_path(os.path.join(run_dir, CANONICAL_RUN_PATHS["output"]), step),
        "checkpoint.meta",
    )
    if not os.path.isfile(metadata):
        return None
    options = _read_checkpoint_options(metadata)
    samples = {}
    for index in range(int(options.get("checkpoint_statistics_window_count", 0) or 0)):
        name = options.get(f"checkpoint_statistics_window_{index}_name")
        if name is not None:
            samples[name] = int(options.get(f"checkpoint_statistics_window_{index}_sample_count", 0) or 0)
    return samples
 
 
def post_step_outputs(run_dir: str, post_cfg: dict, monitor_cfg=None):
    """!
    @brief Return a lookup of the output files one step of the current recipe holds.
    @details A step is complete when every family it must produce has its output. The
             post-processor writes a statistics window's output at a step only if the
             window had accumulated a sample in the bundle it reads, the pinned
             source_step or the step itself, so a window that had not opened yet is not
             required there.
    @param[in] run_dir Run whose output is inspected.
    @param[in] post_cfg Runtime recipe with canonical paths.
    @param[in] monitor_cfg Parsed monitor configuration.
    @return Function mapping a step to (per-step files, shared files), or None when the
            step lacks an output it must have.
    """
    families = collect_post_completion_families(run_dir, post_cfg, monitor_cfg)
    pinned = normalize_post_field_statistics_config(post_cfg).get("source_step")
    sample_cache = {}
 
    def expected(window, step):
        """!
        @brief Whether a family's output must exist at this step.
        @param[in] window Field-statistics window the family belongs to, or None.
        @param[in] step Processed step.
        @return True when the family is always required or its window had samples.
        """
        if window is None:
            return True
        source = int(pinned) if pinned is not None else step
        if source not in sample_cache:
            sample_cache[source] = _field_statistics_window_samples(run_dir, source)
        samples = sample_cache[source]
        # Without the checkpoint's record the output cannot be ruled out, so it stays required.
        return samples is None or samples.get(window, 0) > 0
 
    def outputs(step):
        """!
        @brief Collect one step's output files.
        @param[in] step Processed step.
        @return (per-step files, shared files), or None when an expected output is missing.
        """
        own, shared = [], []
        for mapping, window, per_step in families:
            if step in mapping:
                (own if per_step else shared).append(mapping[step])
            elif expected(window, step):
                return None
        return own, shared
 
    return outputs
 
 
def _nearest_step(steps: "set[int]", target: int):
    """!
    @brief Return the complete source step nearest to a target step.
    @param[in] steps Candidate step numbers.
    @param[in] target Target step number.
    @return Nearest candidate, or None when no candidates exist.
    """
    if not steps:
        return None
    return min(steps, key=lambda step: (abs(step - target), step))
 
 
def _format_optional_step(step) -> str:
    """!
    @brief Format an optional step number for user-facing diagnostics.
    @param[in] step Step number or None.
    @return Printable step text.
    """
    return 'none' if step is None else str(step)
 
 
def _scan_complete_source_steps(source_dir: str, monitor_cfg: dict, post_cfg: dict) -> "tuple[set[int], dict]":
    """!
    @brief Scan source artifacts and return steps with every file required by the recipe.
    @param[in] source_dir Source output root directory.
    @param[in] monitor_cfg Parsed monitor configuration.
    @param[in] post_cfg Parsed post-processing configuration.
    @return Tuple of complete source steps and source path metadata.
    """
    del monitor_cfg
    require_particles = _post_needs_particle_source(post_cfg)
    complete_steps = _scan_committed_checkpoint_steps(
        source_dir, require_particles=require_particles
    )
    return complete_steps, {
        'source_dir': os.path.abspath(source_dir),
        'require_particles': require_particles,
    }
 
 
def _expected_source_paths_for_step(step: int, source_scan: dict, post_cfg: dict) -> "list[str]":
    """!
    @brief Build required source file paths for a single post-processing step.
    @param[in] step Requested step number.
    @param[in] source_scan Metadata returned by `_scan_complete_source_steps()`.
    @param[in] post_cfg Parsed post-processing configuration.
    @return Required source artifact paths.
    """
    del post_cfg
    bundle = _checkpoint_bundle_path(source_scan['source_dir'], step)
    paths = [os.path.join(bundle, 'checkpoint.meta'), os.path.join(bundle, 'COMMITTED')]
    if source_scan.get('require_particles'):
        paths.append(os.path.join(bundle, 'particles', 'position.dat'))
    return paths
 
 
def detect_post_source_frontier(source_dir: str, monitor_cfg: dict, post_cfg: dict, start_step: int, end_step: int, step_interval: int) -> dict:
    """!
    @brief Detect the highest contiguous fully available source step for live post-processing.
    @param[in] source_dir Argument passed to `detect_post_source_frontier()`.
    @param[in] monitor_cfg Argument passed to `detect_post_source_frontier()`.
    @param[in] post_cfg Argument passed to `detect_post_source_frontier()`.
    @param[in] start_step Argument passed to `detect_post_source_frontier()`.
    @param[in] end_step Argument passed to `detect_post_source_frontier()`.
    @param[in] step_interval Argument passed to `detect_post_source_frontier()`.
    @return Value returned by `detect_post_source_frontier()`.
    """
    diagnostic = {
        'first_requested_step': start_step,
        'first_incomplete_step': None,
        'missing_files_for_first_incomplete_step': [],
        'closest_complete_step_to_start': None,
        'closest_complete_step_to_end': None,
    }
    if step_interval <= 0 or end_step < start_step or not os.path.isdir(source_dir):
        return {
            'frontier_step': None,
            'diagnostic': diagnostic,
        }
 
    complete_steps, source_scan = _scan_complete_source_steps(source_dir, monitor_cfg, post_cfg)
    diagnostic['closest_complete_step_to_start'] = _nearest_step(complete_steps, start_step)
    diagnostic['closest_complete_step_to_end'] = _nearest_step(complete_steps, end_step)
 
    frontier = None
    for step in _iter_post_steps(start_step, end_step, step_interval):
        try:
            validate_committed_checkpoint(
                source_dir, step,
                require_particles=source_scan.get('require_particles', False),
            )
        except CheckpointIndexWidthError:
            raise
        except ValueError:
            expected_paths = _expected_source_paths_for_step(step, source_scan, post_cfg)
            diagnostic['first_incomplete_step'] = step
            diagnostic['missing_files_for_first_incomplete_step'] = [
                os.path.relpath(path, source_dir) for path in expected_paths if not os.path.isfile(path)
            ]
            if not diagnostic['missing_files_for_first_incomplete_step']:
                diagnostic['missing_files_for_first_incomplete_step'] = [
                    os.path.relpath(_checkpoint_bundle_path(source_dir, step), source_dir)
                    + ' (invalid bundle)'
                ]
            break
        frontier = step
    return {
        'frontier_step': frontier,
        'diagnostic': diagnostic,
    }
 
 
def _read_post_records(state_path: str) -> "tuple[dict, dict]":
    """!
    @brief Read the per-step output records a recipe's state holds.
    @param[in] state_path The recipe's state.json.
    @return (field-stage records, spectra records), each keyed by the step as text; both
            empty for a state written before records existed.
    """
    state = _read_json_if_exists(state_path)
    if not isinstance(state, dict) or state.get("schema_version") != POST_RESUME_SCHEMA_VERSION:
        return {}, {}
    return dict(state.get("steps") or {}), dict(state.get("spectra") or {})
 
 
def persist_post_resume_state(run_dir: str, plan: dict, steps=None, spectra=None):
    """!
    @brief Write a recipe's state: the window last planned and its per-step output records.
    @param[in] run_dir Run the recipe belongs to.
    @param[in] plan Plan from build_post_execution_plan().
    @param[in] steps Field-stage records to merge in, keyed by step, or None.
    @param[in] spectra Spectra records to merge in, keyed by step, or None.
    @return Path of the written state file.
    """
    state_path = plan.get("resume_state_path") or get_post_resume_state_path(run_dir)
    field_records, spectra_records = _read_post_records(state_path)
    field_records.update({str(step): record for step, record in (steps or {}).items()})
    spectra_records.update({str(step): record for step, record in (spectra or {}).items()})
    write_json_file(state_path, {
        'schema_version': POST_RESUME_SCHEMA_VERSION,
        'run_id': plan.get('run_id'),
        'recipe_fingerprint': plan.get('recipe_fingerprint'),
        'recipe_signature': plan.get('recipe_signature'),
        'requested_start_step': plan.get('requested_start_step'),
        'requested_end_step': plan.get('requested_end_step'),
        'step_interval': plan.get('step_interval'),
        'source_directory': plan.get('source_data_directory'),
        'updated_at': datetime.now().isoformat(),
        'steps': dict(sorted(field_records.items(), key=lambda item: int(item[0]))),
        'spectra': dict(sorted(spectra_records.items(), key=lambda item: int(item[0]))),
    })
    return state_path
 
 
def _checkpoint_commit(source_dir: str, step: int):
    """!
    @brief Identify one committed checkpoint by its commit marker.
    @param[in] source_dir Output root holding the checkpoints.
    @param[in] step Checkpoint step.
    @return (marker digest, marker modification time), or None when the checkpoint is not
            local (never written, archived, or pruned).
    """
    marker = os.path.join(_checkpoint_bundle_path(source_dir, step), "COMMITTED")
    try:
        with open(marker, "r", encoding="ascii") as stream:
            return stream.read().strip(), os.stat(marker).st_mtime
    except OSError:
        return None
 
 
def classify_post_step(record, files, commit, recipe: str, recompute: bool = False) -> "str | None":
    """!
    @brief Decide whether one step's existing output is still valid.
    @details Output stays valid while it was made by the same recipe from the checkpoint
             now on disk. The build that made it does not invalidate it: a rebuild changes
             every binary's hash, and redoing a whole window after each one is what
             `--recompute` is for. Output without a record (written before records
             existed, or by a job killed before it could record) is accepted when it is
             newer than its checkpoint, or when the checkpoint is no longer local.
    @param[in] record The step's record, or None.
    @param[in] files Files the step's output consists of, or None when any is missing.
    @param[in] commit Checkpoint identity from _checkpoint_commit(), or None.
    @param[in] recipe Current recipe fingerprint.
    @param[in] recompute Whether the invocation regenerates every step.
    @return None when the output is valid, else the reason it must be (re)made:
            `missing`, `recompute`, `recipe`, or `checkpoint`.
    """
    if files is None or (not files and record is None):
        return "missing"
    if recompute:
        return "recompute"
    if record is None:
        if commit is None or min(os.path.getmtime(path) for path in files) >= commit[1]:
            return None
        return "checkpoint"
    if record.get("recipe") != recipe:
        return "recipe"
    if commit is not None and record.get("checkpoint") not in (None, commit[0]):
        return "checkpoint"
    return None
 
 
def warn_overlapping_post_recipes(run_dir: str, post_cfg: dict, plan: dict, post_stages) -> None:
    """!
    @brief Warn when another recipe in this run already produced outputs this one repeats.
    @details A recipe writes one file per step holding all its fields, so a recipe that
             repeats another's fields recomputes them rather than reusing them. The
             warning names the shared fields and statistics windows and the overlapping
             steps, so the new outputs can go into a recipe of their own instead.
    @param[in] run_dir Run being post-processed.
    @param[in] post_cfg Runtime recipe with canonical paths.
    @param[in] plan Plan from build_post_execution_plan().
    @param[in] post_stages Selected post stages.
    @return None.
    """
    if 'fields' not in post_stages:
        return
    current_id = ((post_cfg.get("_picurv_paths") or {}).get("recipe_id")
                  or compute_post_recipe_id(post_cfg))
    steps = set(plan['steps_to_process'])
    fields = set(((post_cfg.get('io') or {}).get('eulerian_fields')) or [])
    windows = set(normalize_post_field_statistics_config(post_cfg)["windows"])
    root = os.path.join(os.path.abspath(run_dir), "config", "post-recipes")
    if not steps or not (fields or windows) or not os.path.isdir(root):
        return
    for other_id in sorted(os.listdir(root)):
        archived = os.path.join(root, other_id, "post.yml")
        if other_id == current_id or not os.path.isfile(archived):
            continue
        try:
            other_cfg, resolved_id = apply_canonical_post_paths(read_yaml_file(archived), run_dir)
        except Exception:  # an unreadable archived recipe says nothing about overlap
            continue
        if resolved_id != other_id:
            continue
        labels, done = [], set()
        shared_fields = fields & set(((other_cfg.get('io') or {}).get('eulerian_fields')) or [])
        if shared_fields:
            prefix = os.path.join(_post_output_directory_abs(run_dir, other_cfg),
                                  (other_cfg.get('io') or {}).get('output_filename_prefix', 'Field'))
            found = steps & _scan_post_vtk_steps(prefix, 'vts').keys()
            if found:
                labels.append(f"fields {', '.join(sorted(shared_fields))}")
                done |= found
        shared_windows = []
        for kind, path, window in get_post_field_statistics_artifacts(other_cfg, run_dir):
            if kind == 'vtk' and window in windows:
                found = steps & _scan_post_vtk_steps(path, 'vts').keys()
                if found:
                    shared_windows.append(window)
                    done |= found
        if shared_windows:
            labels.append(f"statistics windows {', '.join(shared_windows)}")
        if labels:
            print(f"[WARNING] Recipe {other_id} already produced {'; '.join(labels)} for "
                  f"{len(done)} of these steps ({min(done)}..{max(done)}); this recipe computes "
                  "them again. If only some outputs are new, a recipe holding just those avoids "
                  "the repeat.", file=sys.stderr)
 
 
def _build_post_lock_wrapper_source() -> str:
    """!
    @brief Return the Python wrapper that runs one post job under an exclusive lock.
    @details Given `--post-recipe`, the wrapper plans the job's steps as it starts
             (prepare_post_job()), skips the postprocessor when none need work, and
             records the steps produced when the postprocessor exits, even on failure
             (finish_post_job()). It imports the conductor from this installation, so it
             must run under the conductor's interpreter.
    @return Value returned by `_build_post_lock_wrapper_source()`.
    """
    package_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
    return """#!/usr/bin/env python3
import argparse
import fcntl
import json
import os
import socket
import subprocess
import sys
import time
 
PICURV_PACKAGE_ROOT = """ + repr(package_root) + """
 
 
def main():
    parser = argparse.ArgumentParser(description='PICurv post-stage lock wrapper')
    parser.add_argument('--lock-file', required=True)
    parser.add_argument('--metadata-file', required=True)
    parser.add_argument('--run-dir', required=True)
    parser.add_argument('--recipe-fingerprint', default='')
    parser.add_argument('--post-recipe')
    parser.add_argument('--postprocessor')
    parser.add_argument('--recompute', action='store_true')
    parser.add_argument('--success-command-json')
    parser.add_argument('command', nargs=argparse.REMAINDER)
    args = parser.parse_args()
 
    command = list(args.command or [])
    if not command or command[0] != '--':
        parser.error("expected '-- <command ...>' after wrapper arguments")
    command = command[1:]
 
    os.makedirs(os.path.dirname(args.lock_file), exist_ok=True)
    fd = os.open(args.lock_file, os.O_RDWR | os.O_CREAT, 0o644)
    try:
        fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
    except BlockingIOError:
        owner = None
        try:
            with open(args.metadata_file, 'r', encoding='utf-8') as handle:
                owner = json.load(handle)
        except Exception:
            owner = None
        if owner:
            print(
                f"[FATAL] Post stage already active for {args.run_dir} "
                f"(pid={owner.get('pid')}, host={owner.get('host')}, started_at={owner.get('started_at')}).",
                file=sys.stderr,
            )
        else:
            print(f"[FATAL] Post stage already active for {args.run_dir}.", file=sys.stderr)
        return 2
 
    metadata = {
        'pid': os.getpid(),
        'host': socket.gethostname(),
        'started_at': time.strftime('%Y-%m-%dT%H:%M:%S%z'),
        'run_dir': args.run_dir,
        'recipe_fingerprint': args.recipe_fingerprint,
        'command': command,
    }
    with open(args.metadata_file, 'w', encoding='utf-8') as handle:
        json.dump(metadata, handle, indent=2, sort_keys=True)
        handle.write('\\n')
 
    try:
        planned = None
        if args.post_recipe:
            sys.path.insert(0, PICURV_PACKAGE_ROOT)
            from picurv_cli.core import finish_post_job, prepare_post_job
            planned = prepare_post_job(args.run_dir, args.post_recipe, args.postprocessor,
                                       recompute=args.recompute)
            sys.stdout.flush()
        if planned != 0:
            result = None
            try:
                result = subprocess.run(command)
            finally:
                if args.post_recipe:
                    finish_post_job(args.run_dir, args.post_recipe,
                                    exited_cleanly=result is not None and result.returncode == 0)
                    sys.stdout.flush()
            if result.returncode != 0:
                return int(result.returncode)
        else:
            print('[INFO] Every requested step with a committed checkpoint is up to date; '
                  'the postprocessor is not launched.')
        if args.success_command_json:
            success_command = json.loads(args.success_command_json)
            if not isinstance(success_command, list) or not success_command:
                print('[FATAL] Invalid post success command.', file=sys.stderr)
                return 2
            result = subprocess.run([str(token) for token in success_command])
            return int(result.returncode)
        return 0
    finally:
        try:
            os.remove(args.metadata_file)
        except FileNotFoundError:
            pass
        os.close(fd)
 
 
if __name__ == '__main__':
    raise SystemExit(main())
"""
 
 
def ensure_post_lock_wrapper(run_dir: str) -> str:
    """!
    @brief Ensure the lock wrapper exists for a run directory and return its path.
    @param[in] run_dir Argument passed to `ensure_post_lock_wrapper()`.
    @return Value returned by `ensure_post_lock_wrapper()`.
    """
    paths = get_post_lock_paths(run_dir)
    wrapper_path = paths['wrapper_path']
    content = _build_post_lock_wrapper_source()
    existing_content = None
    os.makedirs(os.path.dirname(wrapper_path), exist_ok=True)
    if os.path.isfile(wrapper_path):
        with open(wrapper_path, 'r', encoding='utf-8', errors='replace') as f:
            existing_content = f.read()
    if existing_content != content:
        with open(wrapper_path, 'w', encoding='utf-8') as f:
            f.write(content)
        os.chmod(wrapper_path, 0o755)
    return wrapper_path
 
 
def build_post_locked_command(run_dir: str, recipe_fingerprint: str, wrapped_command: list,
                              create_wrapper: bool = True,
                              success_command: "list | None" = None,
                              post_recipe: "str | None" = None,
                              postprocessor: "str | None" = None,
                              recompute: bool = False) -> "tuple[list, dict]":
    """!
    @brief Wrap a postprocessor command behind the run-dir-scoped lock wrapper.
    @param[in] run_dir Argument passed to `build_post_locked_command()`.
    @param[in] recipe_fingerprint Argument passed to `build_post_locked_command()`.
    @param[in] wrapped_command Argument passed to `build_post_locked_command()`.
    @param[in] create_wrapper Argument passed to `build_post_locked_command()`.
    @param[in] success_command Optional serial command run under the same lock after success.
    @param[in] post_recipe Recipe whose steps the wrapper plans at launch; None runs the
                           command as given.
    @param[in] postprocessor Postprocessor the command launches, recorded with its output.
    @param[in] recompute Regenerate every step whose checkpoint is committed.
    @return Value returned by `build_post_locked_command()`.
    """
    lock_paths = get_post_lock_paths(run_dir)
    wrapper_path = ensure_post_lock_wrapper(run_dir) if create_wrapper else lock_paths['wrapper_path']
    command = [
        sys.executable, wrapper_path,
        '--lock-file', lock_paths['lock_file'],
        '--metadata-file', lock_paths['metadata_file'],
        '--run-dir', run_dir,
        '--recipe-fingerprint', recipe_fingerprint,
    ]
    if post_recipe:
        command += ['--post-recipe', os.path.abspath(post_recipe),
                    '--postprocessor', os.path.abspath(postprocessor)]
        if recompute:
            command.append('--recompute')
    if success_command:
        command += ['--success-command-json', json.dumps(list(success_command))]
    command += ['--'] + list(wrapped_command)
    return command, lock_paths
 
 
def run_post_finalize_locked(run_dir: str, recipe_fingerprint: str,
                             finalize_command: list) -> None:
    """!
    @brief Refresh a collection-only result under the ordinary post writer lock.
    @param[in] run_dir Run whose post writer lock is acquired.
    @param[in] recipe_fingerprint Recipe identity recorded in lock metadata.
    @param[in] finalize_command Serial collection finalizer command.
    @return None.
    """
    if not finalize_command:
        return
    command, _ = build_post_locked_command(
        run_dir, recipe_fingerprint, [sys.executable, "-c", "pass"],
        create_wrapper=True, success_command=finalize_command,
    )
    result = subprocess.run(command, cwd=run_dir)
    if result.returncode != 0:
        raise ValueError(
            f"Post finalization (ParaView series, reducers) failed with exit code {result.returncode}."
        )
 
 
def build_post_execution_plan(
    run_dir: str,
    run_id: str,
    case_cfg: dict,
    monitor_cfg: dict,
    post_cfg: dict,
    recompute: bool = False,
    allow_source_frontier_scan: bool = True,
    postprocessor_sha: "str | None" = None,
) -> dict:
    """!
    @brief Decide which steps of a recipe's window one invocation processes.
    @details Every requested step is classified by classify_post_step(): valid output is
             kept, and missing or stale output is (re)made once its checkpoint is
             committed. Steps need not be contiguous. When the solver stage has not run
             yet the source scan is deferred and every step without valid output is
             planned; the post job plans again when it starts (prepare_post_job()).
    @param[in] run_dir Run being post-processed.
    @param[in] run_id Run identity recorded in the recipe state.
    @param[in] case_cfg Parsed case configuration.
    @param[in] monitor_cfg Parsed monitor configuration.
    @param[in] post_cfg Parsed post recipe.
    @param[in] recompute Regenerate every step whose checkpoint is committed.
    @param[in] allow_source_frontier_scan False when the solver stage has not produced output yet.
    @param[in] postprocessor_sha Hash of the postprocessor that would run, used only to
                                 report valid output another build made.
    @return Plan mapping; see the keys of the returned dictionary.
    """
    if not isinstance((post_cfg or {}).get("_picurv_paths"), dict):
        post_cfg, _ = apply_canonical_post_paths(post_cfg, run_dir)
    requested_start_step, requested_end_step, step_interval = resolve_post_requested_window(post_cfg, case_cfg)
    owned_start_step = resolve_post_owned_start(
        run_dir, post_cfg, requested_start_step, step_interval
    )
    resolved_source_dir = _resolve_post_source_directory_preview(run_dir, monitor_cfg, post_cfg)
    resolved_post_cfg = prepare_effective_post_config(post_cfg, resolved_source_dir)
    recipe_cfg = build_post_recipe_config(resolved_post_cfg, monitor_cfg)
    recipe_signature, recipe_fingerprint = compute_post_recipe_fingerprint(recipe_cfg)
    state_path = get_post_resume_state_path(run_dir, resolved_post_cfg)
    records, _ = _read_post_records(state_path)
 
    source_frontier_deferred = not allow_source_frontier_scan
    available = None
    source_frontier_step = None
    source_frontier_diagnostic = None
    if not source_frontier_deferred:
        available = _scan_committed_checkpoint_steps(
            resolved_source_dir, require_particles=_post_needs_particle_source(resolved_post_cfg)
        )
        source_frontier_info = detect_post_source_frontier(
            resolved_source_dir, monitor_cfg, resolved_post_cfg,
            owned_start_step, requested_end_step, step_interval,
        )
        source_frontier_step = source_frontier_info['frontier_step']
        source_frontier_diagnostic = source_frontier_info['diagnostic']
 
    outputs = post_step_outputs(run_dir, resolved_post_cfg, monitor_cfg)
    process, unavailable, reasons, adopted = [], [], {}, {}
    current = other_build = 0
    for step in _iter_post_steps(owned_start_step, requested_end_step, step_interval):
        record = records.get(str(step))
        found = outputs(step)
        files = None if found is None else found[0] + found[1]
        commit = _checkpoint_commit(resolved_source_dir, step)
        reason = classify_post_step(record, files, commit, recipe_fingerprint, recompute)
        if reason is None:
            current += 1
            if record is None:
                record = adopted[step] = {
                    "recipe": recipe_fingerprint,
                    "checkpoint": commit[0] if commit else None,
                    "postprocessor": None,
                }
            if postprocessor_sha and record.get("postprocessor") != postprocessor_sha:
                other_build += 1
        elif available is None or step in available:
            process.append(step)
            reasons[reason] = reasons.get(reason, 0) + 1
        else:
            unavailable.append(step)
 
    skip_reason = None
    if not process:
        if not unavailable:
            skip_reason = 'already-complete-window'
        elif current:
            skip_reason = 'already-caught-up-to-current-source-frontier'
        else:
            skip_reason = 'nothing-available-yet'
    effective_start_step = process[0] if process else None
    effective_end_step = process[-1] if process else None
    effective_post_cfg = None
    if skip_reason is None:
        effective_post_cfg = prepare_effective_post_config(
            post_cfg, resolved_source_dir,
            start_step=effective_start_step, end_step=effective_end_step,
        )
 
    return {
        'run_id': run_id,
        'recompute': bool(recompute),
        'requested_start_step': requested_start_step,
        'requested_end_step': requested_end_step,
        'owned_start_step': owned_start_step,
        'step_interval': step_interval,
        'source_data_directory': resolved_source_dir,
        'recipe_config': recipe_cfg,
        'recipe_signature': recipe_signature,
        'recipe_fingerprint': recipe_fingerprint,
        'resume_state_path': state_path,
        'steps_to_process': process,
        'steps_unavailable': unavailable,
        'steps_current': current,
        'steps_other_build': other_build,
        'process_reasons': reasons,
        'adopted_records': adopted,
        'source_frontier_step': source_frontier_step,
        'source_frontier_diagnostic': source_frontier_diagnostic,
        'source_frontier_deferred': source_frontier_deferred,
        'source_committed_count': None if available is None else len(available),
        'source_latest_step': max(available) if available else None,
        'effective_start_step': effective_start_step,
        'effective_end_step': effective_end_step,
        'skip_reason': skip_reason,
        'resolved_post_cfg': resolved_post_cfg,
        'effective_post_cfg': effective_post_cfg,
        # The lock build_post_locked_command() takes: one post writer per run.
        'lock_paths': get_post_lock_paths(run_dir),
    }
 
 
POST_PROCESS_REASON_LABELS = {
    "missing": "no output yet",
    "recipe": "recipe changed",
    "checkpoint": "checkpoint changed",
    "recompute": "--recompute",
}
 
 
def report_post_plan(plan: dict) -> None:
    """!
    @brief Print which steps a post plan processes, keeps, and waits for.
    @param[in] plan Plan from build_post_execution_plan().
    @return None.
    """
    process = plan['steps_to_process']
    if plan['source_frontier_deferred']:
        print(f"[INFO] Post steps: {len(process)} planned; the post job decides when it starts, "
              "after the solver has written them.")
        return
    why = ", ".join(f"{count} {POST_PROCESS_REASON_LABELS.get(reason, reason)}"
                    for reason, count in sorted(plan['process_reasons'].items()))
    span = f" ({process[0]}..{process[-1]}; {why})" if process else ""
    print(f"[INFO] Post steps: {len(process)} to process{span}, {plan['steps_current']} up to date, "
          f"{len(plan['steps_unavailable'])} without a committed checkpoint.")
    if plan['steps_other_build']:
        print(f"[INFO] {plan['steps_other_build']} up-to-date step(s) were made by another or an "
              "unrecorded postprocessor build and are kept; --recompute regenerates them.")
 
 
def get_post_step_list_path(run_dir: str, post_cfg: dict) -> str:
    """!
    @brief Return the file naming the steps a launched post job processes.
    @param[in] run_dir Run directory.
    @param[in] post_cfg Runtime recipe with canonical paths.
    @return Absolute path; a companion `<path>.json` holds what recording needs.
    """
    return os.path.abspath(os.path.join(get_post_recipe_root(run_dir, post_cfg), "post.steps"))
 
 
def _load_post_job_configs(run_dir: str, post_recipe_path: str) -> "tuple[dict, dict, dict]":
    """!
    @brief Load the configuration a post job needs from the run it runs in.
    @param[in] run_dir Run directory.
    @param[in] post_recipe_path The recipe the job was staged with.
    @return (case configuration, monitor configuration, runtime recipe with canonical paths).
    """
    case_path, monitor_path, _ = auto_identify_run_inputs(os.path.join(run_dir, "config"))
    if not (case_path and monitor_path):
        raise ValueError(f"Could not identify the case and monitor files of {run_dir}.")
    post_cfg, _ = apply_canonical_post_paths(read_yaml_file(post_recipe_path), run_dir)
    return read_yaml_file(case_path), read_yaml_file(monitor_path), post_cfg
 
 
def prepare_post_job(run_dir: str, post_recipe_path: str, postprocessor: str,
                     recompute: bool = False) -> int:
    """!
    @brief Decide, as a post job starts, which steps it processes.
    @details Runs under the post lock immediately before the postprocessor, so a job
             staged long before it runs still skips output produced in the meantime and
             sees checkpoints the solver has written since. Writes the step list the
             postprocessor reads, and records what finish_post_job() needs.
    @param[in] run_dir Run directory.
    @param[in] post_recipe_path The recipe the job was staged with.
    @param[in] postprocessor Postprocessor executable the job launches.
    @param[in] recompute Regenerate every step whose checkpoint is committed.
    @return Number of steps to process; 0 means the postprocessor need not run.
    """
    run_dir = os.path.abspath(run_dir)
    case_cfg, monitor_cfg, post_cfg = _load_post_job_configs(run_dir, post_recipe_path)
    try:
        run_id = read_artifact_identity(run_dir)["run_id"]
    except Exception:
        run_id = os.path.basename(run_dir)
    sha = _file_sha256(postprocessor)
    plan = build_post_execution_plan(run_dir, run_id, case_cfg, monitor_cfg, post_cfg,
                                     recompute=recompute, postprocessor_sha=sha)
    report_post_plan(plan)
    persist_post_resume_state(run_dir, plan, steps=plan['adopted_records'])
    list_path = get_post_step_list_path(run_dir, post_cfg)
    steps = plan['steps_to_process'] if plan['skip_reason'] is None else []
    if not steps:
        for path in (list_path, list_path + ".json"):
            if os.path.exists(path):
                os.remove(path)
        return 0
    outputs = post_step_outputs(run_dir, plan['resolved_post_cfg'], monitor_cfg)
    before = {}
    for step in steps:
        found = outputs(step)
        before[str(step)] = {path: os.stat(path).st_mtime_ns
                             for path in (found[0] + found[1] if found else [])}
    write_json_file(list_path + ".json", {
        "postprocessor": sha,
        "outputs_before": before,
        "plan": {key: plan[key] for key in (
            "run_id", "recipe_fingerprint", "recipe_signature", "requested_start_step",
            "requested_end_step", "step_interval", "source_data_directory", "resume_state_path")},
    })
    with open(list_path, "w", encoding="utf-8") as stream:
        stream.write("".join(f"{step}\n" for step in steps))
    return len(steps)
 
 
def finish_post_job(run_dir: str, post_recipe_path: str, exited_cleanly: bool = False) -> int:
    """!
    @brief Record, after a post job ends, which steps it produced.
    @details Runs whether or not the postprocessor succeeded, so the steps a failed or
             interrupted job completed are kept. A step is credited only when all its
             output exists and was written by this job.
    @param[in] run_dir Run directory.
    @param[in] post_recipe_path The recipe the job was staged with.
    @param[in] exited_cleanly Whether the postprocessor exited with status zero; a clean
                              exit that left an expected output unwritten is reported.
    @return Number of steps recorded.
    """
    run_dir = os.path.abspath(run_dir)
    _case_cfg, monitor_cfg, post_cfg = _load_post_job_configs(run_dir, post_recipe_path)
    list_path = get_post_step_list_path(run_dir, post_cfg)
    job = _read_json_if_exists(list_path + ".json")
    if not isinstance(job, dict):
        return 0
    plan = job["plan"]
    source = plan["source_data_directory"]
    runtime_cfg = prepare_effective_post_config(post_cfg, source)
    outputs = post_step_outputs(run_dir, runtime_cfg, monitor_cfg)
    records = {}
    incomplete = []
    for step_text, before in job["outputs_before"].items():
        step = int(step_text)
        found = outputs(step)
        if found is None:
            incomplete.append(step)
            continue
        # A shared CSV changes with every step, so it proves a step was written only
        # when the step has no file of its own.
        written = found[0] or found[1]
        if not written or any(before.get(path) == os.stat(path).st_mtime_ns for path in written):
            continue
        commit = _checkpoint_commit(source, step)
        records[step] = {
            "recipe": plan["recipe_fingerprint"],
            "checkpoint": commit[0] if commit else None,
            "postprocessor": job["postprocessor"],
        }
    persist_post_resume_state(run_dir, plan, steps=records)
    for path in (list_path, list_path + ".json"):
        if os.path.exists(path):
            os.remove(path)
    print(f"[INFO] Post job recorded {len(records)} of {len(job['outputs_before'])} planned step(s).")
    # A postprocessor that does not know a recipe key ignores it and still exits
    # cleanly, so a step can finish without an output the recipe expects. That is
    # what a pinned executable older than the recipe looks like.
    if incomplete and exited_cleanly:
        try:
            executable = run_executable_path(run_dir, "postprocessor")
        except ValueError:
            executable = "the run's postprocessor"
        print(f"[WARNING] The postprocessor exited cleanly, but {len(incomplete)} planned step(s) "
              f"lack an output this recipe expects (first: step {min(incomplete)}). It may "
              f"predate a requested output: {executable} ignores recipe keys it does not know. "
              "Check its build with 'picurv version', or post-process a branch of the run "
              "built from the current source.", file=sys.stderr)
    return len(records)
 
 
def needs_restart_source(case_cfg: dict, solver_cfg: dict) -> bool:
    """!
    @brief Return True when the solver requires restart data from disk.
    @details Correctly identifies that analytical + init + start_step > 0 does NOT
             need a restart source (C code never reads from restart_dir in that case).
    @param[in] case_cfg Parsed case YAML dictionary.
    @param[in] solver_cfg Parsed solver YAML dictionary.
    @return True if a restart source (--restart-from or --continue) is required.
    """
    try:
        start_step = int(case_cfg.get("run_control", {}).get("start_step", 0) or 0)
    except (TypeError, ValueError):
        start_step = 0
    eulerian_source = str(
        (solver_cfg.get("operation_mode", {}) or {}).get("eulerian_field_source", "solve")
    ).strip().lower()
    particle_restart_mode = str(
        (case_cfg.get("models", {}).get("physics", {}).get("particles", {}) or {}).get("restart_mode", "init")
    ).strip().lower()
    euler_needs = (eulerian_source == "load") or (eulerian_source == "solve" and start_step > 0)
    particle_needs = (particle_restart_mode == "load")
    return euler_needs or particle_needs
 
 
def resolve_run_output_dir(run_dir: str, monitor_cfg: dict) -> str:
    """!
    @brief Resolve the output data directory within a run directory.
    @param[in] run_dir Path to the run directory.
    @param[in] monitor_cfg Parsed monitor YAML dictionary.
    @return Absolute path to the output directory.
    """
    del monitor_cfg
    return os.path.abspath(os.path.join(run_dir, CANONICAL_RUN_PATHS["output"]))
 
 
def resolve_run_restart_dir(run_dir: str, monitor_cfg: dict) -> str:
    """!
    @brief Resolve the restart staging directory within a run directory.
    @param[in] run_dir Path to the run directory.
    @param[in] monitor_cfg Parsed monitor YAML dictionary.
    @return Absolute path to the restart directory.
    """
    del monitor_cfg
    return os.path.abspath(os.path.join(run_dir, CANONICAL_RUN_PATHS["restart"]))
 
 
def compute_physical_case_identity(case_cfg: dict) -> str:
    """!
    @brief Compute the hidden identity used to guard in-place continuation.
    @details Run length/timestep controls, the MPI domain decomposition, and particle
             load-vs-init policy do not define the physical case. All other case.yml
             content does. Checkpoints are decomposition-independent, so a run may
             continue on a different rank layout.
    @param[in] case_cfg Parsed case configuration.
    @return Lowercase SHA-256 identity of normalized physical-case content.
    """
    normalized = copy.deepcopy(case_cfg)
    if isinstance(normalized, dict):
        normalized.pop("run_control", None)
        grid = normalized.get("grid")
        if isinstance(grid, dict):
            for key in GRID_DA_PROCESSOR_KEYS:
                grid.pop(key, None)
            if isinstance(grid.get("programmatic_settings"), dict):
                for key in GRID_DA_PROCESSOR_KEYS:
                    grid["programmatic_settings"].pop(key, None)
        particles = (((normalized.get("models") or {}).get("physics") or {}).get("particles"))
        if isinstance(particles, dict):
            particles.pop("restart_mode", None)
    payload = json.dumps(
        normalized, sort_keys=True, separators=(",", ":"), ensure_ascii=False
    ).encode("utf-8")
    return hashlib.sha256(payload).hexdigest()
 
 
def validate_continue_case_identity(run_dir: str, case_cfg: dict) -> None:
    """!
    @brief Reject in-place continuation when the physical case has changed.
    @param[in] run_dir Existing run directory being continued.
    @param[in] case_cfg Newly requested case configuration.
    @return None.
    """
    saved_case_path = os.path.join(run_dir, "config", "case.yml")
    if not os.path.isfile(saved_case_path):
        raise ValueError(f"--continue run is missing its saved case.yml: {saved_case_path}")
    saved_case = read_yaml_file(saved_case_path)
    if compute_physical_case_identity(saved_case) != compute_physical_case_identity(case_cfg):
        raise ValueError(
            "--continue cannot change the physical case. Change only run_control, the "
            "da_processors layout, solver.yml, monitor.yml, or post.yml; use --restart-from "
            "for a new case branch."
        )
 
 
def populate_restart_directory(source_output: str, target_restart: str, start_step: int,
                               monitor_cfg: dict, end_step: "int | None" = None,
                               materialize: bool = True):
    """!
    @brief Atomically materialize an immutable checkpoint interval into a run.
    @param[in] source_output Path to the source output directory containing checkpoint data.
    @param[in] target_restart Path to the target restart directory to populate.
    @param[in] start_step First checkpoint step to materialize.
    @param[in] monitor_cfg Parsed monitor YAML dictionary (for subdirectory names).
    @param[in] end_step Optional inclusive last checkpoint step.
    @param[in] materialize Whether to copy the bundles, or only validate and resolve
               the path a real run would use. The dry-run planner needs the second:
               it reports what a run would refuse, and promises to write nothing.
    @return Canonical restart root containing committed checkpoint bundles.
    """
    del monitor_cfg
    checkpoints_root = os.path.join(os.path.abspath(target_restart), "checkpoints")
    if materialize:
        os.makedirs(checkpoints_root, exist_ok=True)
    final_step = start_step if end_step is None else end_step
    if final_step < start_step:
        raise ValueError("Restart checkpoint interval end must not precede its start.")
    for step in range(start_step, final_step + 1):
        source = validate_committed_checkpoint(source_output, step)["bundle"]
        if not materialize:
            continue
        destination = os.path.join(
            checkpoints_root, f"step_{step:0{CHECKPOINT_STEP_WIDTH}d}"
        )
        if os.path.isdir(destination):
            validate_committed_checkpoint(destination, step)
            print(f"[INFO] Reusing committed restart bundle: {destination}")
            continue
        temporary = os.path.join(
            checkpoints_root,
            f".step_{step:0{CHECKPOINT_STEP_WIDTH}d}.copying.{os.getpid()}",
        )
        if os.path.exists(temporary):
            raise ValueError(f"Restart staging path already exists: {temporary}")
        try:
            os.makedirs(temporary)
            for current, dirnames, filenames in os.walk(source):
                relative = os.path.relpath(current, source)
                target_dir = temporary if relative == "." else os.path.join(temporary, relative)
                os.makedirs(target_dir, exist_ok=True)
                for dirname in dirnames:
                    os.makedirs(os.path.join(target_dir, dirname), exist_ok=True)
                for filename in filenames:
                    _materialize_asset_file(
                        os.path.join(current, filename), os.path.join(target_dir, filename)
                    )
            validate_committed_checkpoint(temporary, step)
            os.replace(temporary, destination)
        except Exception:
            if os.path.isdir(temporary):
                shutil.rmtree(temporary)
            raise
        print(f"[INFO] Materialized committed restart bundle for step {step}: {destination}")
    return os.path.abspath(target_restart)
 
 
def validate_eulerian_checkpoint(source_dir: str, step: int, monitor_cfg: dict):
    """!
    @brief Validate the mandatory Eulerian field set required by `ReadSimulationFields()`.
    @param[in] source_dir Root directory containing the Eulerian subdirectory.
    @param[in] step Checkpoint step to validate.
    @param[in] monitor_cfg Monitor configuration defining the Eulerian subdirectory.
    @return Validated checkpoint description.
    @throws ValueError if any mandatory Eulerian field is absent.
    """
    del monitor_cfg
    return validate_committed_checkpoint(source_dir, step)
 
 
def detect_last_checkpoint_step(output_dir: str):
    """!
    @brief Scan output directory for the highest step number available.
    @details Ignores incomplete temporary directories and invalid bundles.
    @param[in] output_dir Path to the output directory.
    @return The highest step number found, or None if no checkpoints exist.
    """
    steps = _scan_committed_checkpoint_steps(output_dir)
    return max(steps) if steps else None
 
 
def detect_case_completion_status(run_dir: str, monitor_cfg: dict, target_final_step: int) -> dict:
    """!
    @brief Determine whether a study case is complete, partially complete, or empty.
    @param[in] run_dir Path to the case run directory.
    @param[in] monitor_cfg Parsed monitor YAML dictionary.
    @param[in] target_final_step The step number the case should reach for completion.
    @return Dictionary with keys 'last_step' (int or None), 'target_step' (int),
            and 'status' ('complete', 'partial', or 'empty').
    """
    output_dir = resolve_run_output_dir(run_dir, monitor_cfg)
    last_step = detect_last_checkpoint_step(output_dir)
    if last_step is not None and last_step >= target_final_step:
        status = "complete"
    elif last_step is not None:
        status = "partial"
    else:
        status = "empty"
    return {"last_step": last_step, "target_step": target_final_step, "status": status}
 
 
def validate_load_mode_step_range(source_output: str, start_step: int, total_steps: int, monitor_cfg: dict):
    """!
    @brief Validate that all required eulerian step files exist for "load" mode.
    @details Checks that ufield files exist for every step from start_step through
             start_step + total_steps (inclusive). Reports missing steps clearly.
    @param[in] source_output Path to the output directory containing eulerian data.
    @param[in] start_step First step that will be loaded.
    @param[in] total_steps Number of steps to run.
    @param[in] monitor_cfg Parsed monitor YAML dictionary (for subdirectory names).
    """
    missing = []
    for step in range(start_step, start_step + total_steps + 1):
        try:
            validate_eulerian_checkpoint(source_output, step, monitor_cfg)
        except CheckpointIndexWidthError:
            raise
        except ValueError:
            missing.append(step)
 
    if missing:
        sample = missing[:3] + (["..."] if len(missing) > 6 else []) + missing[-3:]
        raise ValueError(
            f"Eulerian 'load' mode: {len(missing)} committed checkpoint(s) missing in {source_output}. "
            f"Missing steps include: {sample}"
        )
 
 
def validate_particle_checkpoint(source_dir: str, start_step: int, monitor_cfg: dict):
    """!
    @brief Validate that particle checkpoint files exist for the given step.
    @details Checks that at least a position file exists at the expected step in
             the particle subdirectory.
    @param[in] source_dir Path to the directory containing the particle subdirectory.
    @param[in] start_step The step number whose particle checkpoint is expected.
    @param[in] monitor_cfg Parsed monitor YAML dictionary (for subdirectory names).
    @return Validated checkpoint description.
    """
    del monitor_cfg
    return validate_committed_checkpoint(source_dir, start_step, require_particles=True)
 
 
def read_monitor_from_run(run_dir: str) -> dict:
    """!
    @brief Read the monitor.yml from a run directory's config/ subdirectory.
    @param[in] run_dir Path to the run directory.
    @return Parsed monitor YAML dictionary.
    """
    monitor_path = os.path.join(run_dir, "config", "monitor.yml")
    if not os.path.isfile(monitor_path):
        raise ValueError(f"Run directory is missing config/monitor.yml: {monitor_path}")
    return read_yaml_file(monitor_path)
 
 
def resolve_latest_restart_run(case_cfg: dict, case_path: str, start_step: int) -> str:
    """!
    @brief Select the newest local workspace run compatible with a requested restart.
    @param[in] case_cfg Current case configuration.
    @param[in] case_path Current case path.
    @param[in] start_step Required committed checkpoint.
    @return Absolute source run directory.
    """
    workspace_root = find_workspace_root(case_path, os.getcwd())
    if not workspace_root:
        raise ValueError("--from latest requires an initialized workspace.")
    current_graph = build_case_asset_graph(case_cfg, case_path)
    current_grid = next(
        (item for item in current_graph.get("providers", []) if item.get("kind") == "grid"),
        None,
    )
    candidates = []
    for candidate in Path(workspace_root, "runs").iterdir():
        if not candidate.is_dir():
            continue
        manifest = _read_json_if_exists(str(candidate / "manifest.json")) or {}
        lock = read_yaml_file(str(candidate / "inputs" / "assets.lock.yml")) \
            if (candidate / "inputs" / "assets.lock.yml").is_file() else {}
        locked_grid = (lock.get("assets") or {}).get("grid")
        runtime_grid = (lock.get("runtime_providers") or {}).get("grid")
        if current_grid:
            recorded_hash = None
            if isinstance(locked_grid, dict):
                recorded_hash = locked_grid.get("provider_spec_sha256")
            elif isinstance(runtime_grid, dict):
                recorded_hash = runtime_grid.get("provider_spec_sha256")
            if recorded_hash and recorded_hash != current_grid.get("spec_sha256"):
                continue
        output_root = candidate / CANONICAL_RUN_PATHS["output"]
        try:
            validate_committed_checkpoint(str(output_root), start_step)
        except CheckpointIndexWidthError:
            raise
        except (OSError, ValueError):
            continue
        ordering = manifest.get("updated_at") or manifest.get("created_at") or ""
        candidates.append((ordering, candidate.stat().st_mtime_ns, str(candidate)))
    if not candidates:
        raise ValueError(
            f"No local workspace run has a compatible committed checkpoint at step {start_step}. "
            "Restore a run from storage first, or name one explicitly with --from <run-dir>."
        )
    candidates.sort(reverse=True)
    selected = candidates[0][2]
    print(f"[INFO] Selected latest compatible restart run: {os.path.relpath(selected, workspace_root)}")
    return selected
 
 
def resolve_restart_source(args, case_cfg: dict, solver_cfg: dict, monitor_cfg: dict,
                           run_dir: str, materialize: bool = True):
    """!
    @brief Resolve the restart source directory based on --restart-from or --continue CLI flags.
    @details Implements the full restart resolution logic including smart resolution for
             --continue (checks restart/ first for user-curated data, falls back to output/)
             and direct reference for eulerian "load" mode.
    @param[in] args Parsed CLI arguments (must have restart_from, continue_run, run_dir attrs).
    @param[in] case_cfg Parsed case YAML dictionary.
    @param[in] solver_cfg Parsed solver YAML dictionary.
    @param[in] monitor_cfg Parsed monitor YAML dictionary.
    @param[in] run_dir Path to the current run directory.
    @param[in] materialize Whether to copy restart bundles into the run. The dry-run
               planner passes False: it still validates and resolves, but writes nothing.
    @return Tuple of (restart_source_dir, continue_mode, lineage) where restart_source_dir
            is the resolved path (or None), continue_mode is a boolean, and lineage is the
            branch provenance record from `build_run_lineage()`, or None when this run did
            not branch from another.
    """
    try:
        start_step = int(case_cfg.get("run_control", {}).get("start_step", 0) or 0)
    except (TypeError, ValueError):
        start_step = 0
    try:
        total_steps = int(case_cfg.get("run_control", {}).get("total_steps", 0) or 0)
    except (TypeError, ValueError):
        total_steps = 0
 
    eulerian_source = str(
        (solver_cfg.get("operation_mode", {}) or {}).get("eulerian_field_source", "solve")
    ).strip().lower()
 
    particle_restart_mode = str(
        (case_cfg.get("models", {}).get("physics", {}).get("particles", {}) or {}).get("restart_mode", "init")
    ).strip().lower()
    particle_needs = (particle_restart_mode == "load")
 
    requires_source = needs_restart_source(case_cfg, solver_cfg)
    restart_from = getattr(args, 'restart_from', None)
    continue_run = getattr(args, 'continue_run', False)
 
    if restart_from and continue_run:
        raise ValueError("--restart-from and --continue are mutually exclusive.")
 
    # The named run must exist before its start step can mean anything.
    if continue_run and getattr(args, 'run_dir', None) and not os.path.isdir(args.run_dir):
        raise ValueError(f"--run-dir does not exist: {os.path.abspath(args.run_dir)}")
    if continue_run and start_step <= 0:
        raise ValueError(
            "--continue with --solve requires run_control.start_step > 0; "
            "start_step=0 is a fresh start. Omit --continue to start a fresh run."
        )
 
    if restart_from:
        requested_restart_source = str(restart_from)
        if str(restart_from).strip().lower() == "latest":
            restart_from = resolve_latest_restart_run(
                case_cfg, getattr(args, "case", "case.yml"), start_step
            )
        # A branch may follow a different physical trajectory than the samples already
        # collected, so the retention of the parent's windows is the user's decision and
        # not a default's. Silently resetting reports a sample count that describes a
        # shorter average than the user expects; silently carrying averages two
        # different flows together. Neither is safe to guess, so the flag is required
        # whenever there are windows to decide about.
        requested_statistics_state = getattr(args, "statistics_state", None)
        statistics_enabled = normalize_field_statistics_config(monitor_cfg or {})["enabled"]
        if requested_statistics_state is None:
            if statistics_enabled:
                raise ValueError(
                    "A branched restart of a run with field_statistics.enabled: true must "
                    "state what happens to the parent's accumulated windows. Pass "
                    "--statistics-state reset to discard them and start the averages over, "
                    "or --statistics-state carry to resume compatible saved window state."
                )
            requested_statistics_state = "reset"
        statistics_state = str(requested_statistics_state).lower()
        if statistics_state == "carry" and not statistics_enabled:
            raise ValueError("--statistics-state carry requires field_statistics.enabled: true.")
        # Carried windows are read from the source checkpoint even when nothing else is:
        # an analytical Eulerian source restores no fields, but its statistics still
        # live in that bundle, and an unstaged restart directory fails at start-up.
        if statistics_state == "carry":
            requires_source = True
 
        # === MODE 1: New run, restart from another run ===
        source_run = os.path.abspath(restart_from)
        if not os.path.isdir(source_run):
            raise ValueError(f"--restart-from run directory does not exist: {source_run}")
        try:
            require_storage_payload_local(source_run, "--restart-from", checkpoint=start_step)
        except StorageError as exc:
            raise ValueError(str(exc)) from exc
        source_monitor = read_monitor_from_run(source_run)
        source_output = resolve_run_output_dir(source_run, source_monitor)
        if not os.path.isdir(source_output):
            raise ValueError(f"Source output directory does not exist: {source_output}")
        lineage = build_run_lineage(
            source_run, start_step,
            workspace_root=find_workspace_root(run_dir),
            statistics_state=statistics_state,
            requested_source=requested_restart_source,
        )
 
        if not requires_source:
            # R7: analytical + init — warn that --restart-from is unused
            print(
                "[WARNING] --restart-from has no effect: an analytical flow with freshly "
                "initialized particles reads no restart data.",
                file=sys.stderr,
            )
            return None, False, None
 
        if eulerian_source == "load":
            # A load-mode run may consume a complete saved sequence. Materialize it
            # into this run so storage never depends on another run remaining local.
            validate_load_mode_step_range(source_output, start_step, total_steps, source_monitor)
            target_restart = resolve_run_restart_dir(run_dir, monitor_cfg)
            restart_root = populate_restart_directory(
                source_output, target_restart, start_step, monitor_cfg,
                end_step=start_step + total_steps, materialize=materialize,
            )
            if particle_needs:
                validate_particle_checkpoint(
                    restart_root if materialize else source_output, start_step, monitor_cfg
                )
            return restart_root, False, lineage
        else:
            # Materialize one immutable bundle into the new run's restart input.
            target_restart = resolve_run_restart_dir(run_dir, monitor_cfg)
            restart_root = populate_restart_directory(
                source_output, target_restart, start_step, monitor_cfg,
                materialize=materialize,
            )
            if particle_needs:
                validate_particle_checkpoint(
                    restart_root if materialize else source_output, start_step, monitor_cfg
                )
            return restart_root, False, lineage
 
    elif continue_run:
        # === MODE 2: Continue in-place ===
        continue_run_dir = getattr(args, 'run_dir', None)
        if not continue_run_dir:
            raise ValueError(RESTART_RUN_DIR_REQUIRED_MESSAGE)
        continue_run_dir = os.path.abspath(continue_run_dir)
        try:
            require_storage_payload_local(continue_run_dir, "--continue", checkpoint=start_step)
        except StorageError as exc:
            raise ValueError(str(exc)) from exc
        validate_continue_case_identity(continue_run_dir, case_cfg)
 
        source_output = resolve_run_output_dir(continue_run_dir, monitor_cfg)
        last_step = detect_last_checkpoint_step(source_output)
        # The solver never overwrites a committed checkpoint, so continuing from an earlier
        # one would keep the old states after it and mix two histories in one run.
        if last_step is not None and start_step < last_step:
            raise ValueError(
                f"--continue starts at step {start_step}, but this run already has committed "
                f"checkpoints through step {last_step}. Continuing in place from an earlier "
                "checkpoint would keep the later ones from the old trajectory. Set "
                f"run_control.start_step to {last_step} to extend the run, or branch a new run "
                f"from step {start_step} with --restart-from {continue_run_dir}."
            )
        if last_step is not None and start_step > last_step:
            raise ValueError(
                f"--continue starts at step {start_step}, but this run's last committed "
                f"checkpoint is step {last_step}. Set run_control.start_step to {last_step}."
            )
 
        if eulerian_source == "load":
            # Preserve the saved sequence under the run's immutable restart input.
            validate_load_mode_step_range(source_output, start_step, total_steps, monitor_cfg)
            target_restart = resolve_run_restart_dir(run_dir, monitor_cfg)
            restart_root = populate_restart_directory(
                source_output, target_restart, start_step, monitor_cfg,
                end_step=start_step + total_steps, materialize=materialize,
            )
            if particle_needs:
                validate_particle_checkpoint(
                    restart_root if materialize else source_output, start_step, monitor_cfg
                )
            return restart_root, True, None
        elif not requires_source:
            # C6: analytical + init — only log-append behavior, no data needed
            return None, True, None
        else:
            # In-place continuation also uses the fixed restart-input home. Reflink or
            # hardlink materialization normally makes this metadata-cheap.
            target_restart = resolve_run_restart_dir(run_dir, monitor_cfg)
            restart_root = populate_restart_directory(
                source_output, target_restart, start_step, monitor_cfg,
                materialize=materialize,
            )
            validate_committed_checkpoint(
                restart_root if materialize else source_output, start_step,
                require_particles=particle_needs,
            )
            return restart_root, True, None
 
    elif requires_source:
        raise ValueError(
            "Restart data required but no source specified. Use:\n"
            "  --restart-from <run_dir>  (new run from another run's data)\n"
            "  --continue --run-dir <run_dir>  (resume in same directory)"
        )
 
    return None, False, None
 
def absolutize_case_external_paths(case_cfg: dict, case_anchor_path: str):
    """!
    @brief Convert external grid/generator paths in case config to absolute paths.
    @param[in] case_cfg Argument passed to `absolutize_case_external_paths()`.
    @param[in] case_anchor_path Argument passed to `absolutize_case_external_paths()`.
    """
    # Initialized workspaces deliberately keep portable, root-relative paths in
    # every materialized study member.  The run/study directory remains below
    # the workspace, so normal resolution can still find the owning manifest.
    if find_workspace_root(case_anchor_path):
        return
    grid_cfg = case_cfg.get("grid", {})
    if not isinstance(grid_cfg, dict):
        return
    mode = grid_cfg.get("mode")
    if mode == "file":
        source_file = grid_cfg.get("source_file")
        if isinstance(source_file, str):
            grid_cfg["source_file"] = resolve_path(case_anchor_path, source_file)
    elif mode == "grid_gen":
        gen = grid_cfg.get("generator", {})
        if isinstance(gen, dict):
            for key in ("script", "config_file"):
                val = gen.get(key)
                if isinstance(val, str):
                    gen[key] = resolve_path(case_anchor_path, val)
    ic = (case_cfg.get("properties", {}) or {}).get("initial_conditions", {})
    if isinstance(ic, dict):
        if str(ic.get("mode", "")).strip().lower() == "file":
            source_file = ic.get("source_file")
            if isinstance(source_file, str):
                ic["source_file"] = resolve_path(case_anchor_path, source_file)
        elif str(ic.get("generator", "")).strip().lower() == "ic_gen":
            params = ic.get("params", {})
            if isinstance(params, dict):
                for key in ("script", "config_file"):
                    value = params.get(key)
                    if isinstance(value, str):
                        params[key] = resolve_path(case_anchor_path, value)
    boundary_conditions = case_cfg.get("boundary_conditions", [])
    blocks = boundary_conditions if boundary_conditions and isinstance(boundary_conditions[0], list) else [boundary_conditions]
    for block in blocks:
        if not isinstance(block, list):
            continue
        for bc in block:
            if not isinstance(bc, dict) or str(bc.get("handler", "")).strip().lower() != "prescribed_flow":
                continue
            source = ((bc.get("params") or {}).get("source") or {})
            if not isinstance(source, dict):
                continue
            source_type = str(source.get("type", "")).strip().lower()
            if source_type == "file":
                keys = ("path",)
            elif source_type == "generated":
                keys = ("script",)
            elif source_type == "field_slice":
                keys = ("script", "field_file", "grid_file", "source_case")
            else:
                keys = ()
            for key in keys:
                value = source.get(key)
                if isinstance(value, str):
                    source[key] = resolve_path(case_anchor_path, value)
 
 
def prepare_case_for_continuation(run_dir: str, case_id: str, last_step: int,
                                   target_final_step: int, cluster_cfg: dict):
    """!
    @brief Set up a partially-completed study case for continuation in-place.
    @details Updates the case config with new start_step/total_steps, sets particle
             restart_mode to 'load' if checkpoint exists, populates the restart
             directory, and regenerates the solver control file with continue_mode.
             Delegates all restart resolution to resolve_restart_source().
    @param[in] run_dir Path to the case run directory.
    @param[in] case_id The case identifier (e.g. 'case_0002').
    @param[in] last_step The last checkpoint step found in the output directory.
    @param[in] target_final_step The step number the case should reach for completion.
    @param[in] cluster_cfg Parsed cluster YAML dictionary (for num_procs, walltime guard).
    @return The absolute path to the regenerated control file.
    """
    config_dir = os.path.join(run_dir, "config")
    case_cfg = read_yaml_file(os.path.join(config_dir, "case.yml"))
    solver_cfg = read_yaml_file(os.path.join(config_dir, "solver.yml"))
    monitor_cfg = read_yaml_file(os.path.join(config_dir, "monitor.yml"))
 
    remaining = target_final_step - last_step
    case_cfg["run_control"]["start_step"] = last_step
    case_cfg["run_control"]["total_steps"] = remaining
    print(f"[INFO] {case_id}: updating start_step={last_step}, total_steps={remaining}")
 
    output_dir = resolve_run_output_dir(run_dir, monitor_cfg)
    particles_cfg = (case_cfg.get("models", {}).get("physics", {}) or {}).get("particles")
    checkpoint_has_particles = False
    try:
        checkpoint_has_particles = validate_committed_checkpoint(
            output_dir, last_step, require_particles=True
        )["has_particles"]
    except CheckpointIndexWidthError:
        raise
    except ValueError:
        checkpoint_has_particles = False
    if particles_cfg is not None and checkpoint_has_particles:
        current_mode = str(particles_cfg.get("restart_mode", "init")).strip().lower()
        if current_mode != "load":
            particles_cfg["restart_mode"] = "load"
            print(f"[INFO] {case_id}: setting particle restart_mode='load' (checkpoint found)")
 
    write_yaml_file(os.path.join(config_dir, "case.yml"), case_cfg)
 
    mock_args = argparse.Namespace(restart_from=None, continue_run=True, run_dir=run_dir)
    restart_source_dir, continue_mode, _lineage = resolve_restart_source(
        mock_args, case_cfg, solver_cfg, monitor_cfg, run_dir
    )
 
    source_files = {
        'Case': os.path.join(config_dir, "case.yml"),
        'Solver': os.path.join(config_dir, "solver.yml"),
        'Monitor': os.path.join(config_dir, "monitor.yml"),
    }
    monitor_files = prepare_monitor_files(run_dir, case_id, monitor_cfg, source_files)
    cluster_tasks = get_cluster_total_tasks(cluster_cfg)
    configs = {
        "case": case_cfg, "case_path": source_files['Case'],
        "solver": solver_cfg, "solver_path": source_files['Solver'],
        "monitor": monitor_cfg, "monitor_path": source_files['Monitor'],
        "walltime_guard_policy": resolve_walltime_guard_policy(cluster_cfg),
        "cluster_cfg": cluster_cfg,
    }
    control_file = generate_solver_control_file(
        run_dir, case_id, configs, cluster_tasks, monitor_files,
        restart_source_dir=restart_source_dir, continue_mode=continue_mode,
    )
    print(f"[SUCCESS] {case_id}: regenerated control file for continuation")
    return control_file
 
 
def is_valid_email(email: str) -> bool:
    """!
    @brief Lightweight email validation for scheduler notifications.
    @param[in] email Argument passed to `is_valid_email()`.
    @return Value returned by `is_valid_email()`.
    """
    if not isinstance(email, str):
        return False
    pattern = r"^[^@\s]+@[^@\s]+\.[^@\s]+$"
    return re.match(pattern, email.strip()) is not None
 
def normalize_statistics_task(task_name: str) -> str:
    """!
    @brief Normalizes user-facing statistics task names to C pipeline keywords.
    @param[in] task_name Task name from YAML.
    @return Canonical keyword accepted by C statistics pipeline.
    @throws ValueError if task is unsupported.
    """
    # Only implemented statistics kernels belong here.
    if task_name is None:
        raise ValueError("statistics task cannot be None")
    normalized = str(task_name).strip().lower().replace("-", "_").replace(" ", "_")
    if normalized != "msd":
        raise ValueError(f"Unsupported statistics task '{task_name}'. Currently supported: 'msd'.")
    return "ComputeMSD"
 
def _iter_nonempty_noncomment_lines(file_obj):
    """!
    @brief Yield (lineno, stripped_line) for non-empty, non-comment lines.
    @param[in] file_obj Argument passed to `_iter_nonempty_noncomment_lines()`.
    """
    for lineno, raw in enumerate(file_obj, start=1):
        line = raw.strip()
        if not line or line.startswith("#"):
            continue
        yield lineno, line
 
PICGRID_FLOAT_FORMAT = ".17e"
 
 
def format_picgrid_coordinate(value: float) -> str:
    """!
    @brief Format a coordinate with round-trip-safe binary64 precision.
    @param[in] value Coordinate value.
    @return Formatted coordinate.
    """
    return format(value, PICGRID_FLOAT_FORMAT)
 
 
def validate_and_nondimensionalize_picgrid(source_grid: str, dest_grid: str, L_ref: float, expected_nblk: int = None) -> dict:
    """!
    @brief Validates PICGRID payload and writes a non-dimensionalized copy.
    @details Requires canonical PICGRID input with leading "PICGRID" token.
             Output is always written in canonical PICGRID format with header and per-block dims.
    @param[in] source_grid Input grid file path.
    @param[in] dest_grid Output grid file path.
    @param[in] L_ref Reference length for non-dimensionalization.
    @param[in] expected_nblk Optional expected block count.
    @return Summary dictionary with nblk, dims, and total_nodes.
    @throws ValueError on malformed grid.
    """
    if L_ref == 0.0:
        raise ValueError("length_ref must be non-zero when processing grid coordinates.")
    if not os.path.isfile(source_grid):
        raise ValueError(f"Grid file not found: {source_grid}")
 
    with open(source_grid, "r") as fin:
        line_iter = _iter_nonempty_noncomment_lines(fin)
        try:
            _, first_token = next(line_iter)
        except StopIteration:
            raise ValueError(f"Grid file '{source_grid}' is empty.")
 
        if first_token != "PICGRID":
            raise ValueError(
                f"Grid file '{source_grid}' must begin with the canonical PICGRID header token."
            )
        try:
            _, nblk_line = next(line_iter)
        except StopIteration:
            raise ValueError(f"Grid file '{source_grid}' missing block count after PICGRID header.")
 
        try:
            nblk = int(nblk_line)
        except ValueError:
            raise ValueError(f"Invalid block count '{nblk_line}' in grid file '{source_grid}'.")
        if nblk <= 0:
            raise ValueError(f"Grid file '{source_grid}' has non-positive block count: {nblk}.")
        if expected_nblk is not None and nblk != expected_nblk:
            raise ValueError(
                f"Grid file block count mismatch: case expects {expected_nblk}, grid contains {nblk}."
            )
 
        dims = []
        for bi in range(nblk):
            try:
                lineno, dim_line = next(line_iter)
            except StopIteration:
                raise ValueError(f"Grid file '{source_grid}' missing dimensions for block {bi}.")
            parts = dim_line.split()
            if len(parts) != 3:
                raise ValueError(
                    f"Invalid dimensions line at {source_grid}:{lineno}. Expected 3 integers, got: '{dim_line}'."
                )
            try:
                im, jm, km = (int(parts[0]), int(parts[1]), int(parts[2]))
            except ValueError:
                raise ValueError(
                    f"Invalid dimensions line at {source_grid}:{lineno}. Non-integer values: '{dim_line}'."
                )
            if im <= 0 or jm <= 0 or km <= 0:
                raise ValueError(
                    f"Invalid block dimensions at {source_grid}:{lineno}: ({im}, {jm}, {km}). Must be > 0."
                )
            dims.append((im, jm, km))
 
        total_nodes_expected = sum(im * jm * km for (im, jm, km) in dims)
        os.makedirs(os.path.dirname(dest_grid), exist_ok=True)
        with open(dest_grid, "w") as fout:
            fout.write("PICGRID\n")
            fout.write(f"{nblk}\n")
            for (im, jm, km) in dims:
                fout.write(f"{im} {jm} {km}\n")
 
            total_nodes_seen = 0
            for lineno, coord_line in line_iter:
                parts = coord_line.split()
                if len(parts) != 3:
                    raise ValueError(
                        f"Invalid coordinate row at {source_grid}:{lineno}. Expected 3 floats, got: '{coord_line}'."
                    )
                try:
                    x = float(parts[0]) / L_ref
                    y = float(parts[1]) / L_ref
                    z = float(parts[2]) / L_ref
                except ValueError:
                    raise ValueError(
                        f"Invalid coordinate row at {source_grid}:{lineno}. Non-numeric values: '{coord_line}'."
                    )
                total_nodes_seen += 1
                if total_nodes_seen > total_nodes_expected:
                    raise ValueError(
                        f"Grid file '{source_grid}' has more coordinates ({total_nodes_seen}) than expected ({total_nodes_expected})."
                    )
                fout.write(
                    f"{format_picgrid_coordinate(x)} {format_picgrid_coordinate(y)} "
                    f"{format_picgrid_coordinate(z)}\n"
                )
 
        if total_nodes_seen != total_nodes_expected:
            raise ValueError(
                f"Grid file '{source_grid}' has {total_nodes_seen} coordinates, expected {total_nodes_expected} from header."
            )
 
    return {"nblk": nblk, "dims": dims, "total_nodes": total_nodes_expected}
 
def read_picgrid_header_dimensions(source_grid: str, expected_nblk: int = None) -> list:
    """!
    @brief Read only the canonical PICGRID header dimensions.
    @param[in] source_grid Input grid file path.
    @param[in] expected_nblk Optional expected block count.
    @return List of (IM, JM, KM) node-count tuples.
    @throws ValueError on malformed header.
    """
    if not os.path.isfile(source_grid):
        raise ValueError(f"Grid file not found: {source_grid}")
 
    with open(source_grid, "r") as fin:
        line_iter = _iter_nonempty_noncomment_lines(fin)
        try:
            _, first_token = next(line_iter)
        except StopIteration:
            raise ValueError(f"Grid file '{source_grid}' is empty.")
        if first_token != "PICGRID":
            raise ValueError(f"Grid file '{source_grid}' must begin with the canonical PICGRID header token.")
 
        try:
            _, nblk_line = next(line_iter)
            nblk = int(nblk_line)
        except StopIteration:
            raise ValueError(f"Grid file '{source_grid}' missing block count after PICGRID header.")
        except ValueError:
            raise ValueError(f"Invalid block count '{nblk_line}' in grid file '{source_grid}'.")
        if nblk <= 0:
            raise ValueError(f"Grid file '{source_grid}' has non-positive block count: {nblk}.")
        if expected_nblk is not None and nblk != expected_nblk:
            raise ValueError(f"Grid file block count mismatch: case expects {expected_nblk}, grid contains {nblk}.")
 
        dims = []
        for bi in range(nblk):
            try:
                lineno, dim_line = next(line_iter)
            except StopIteration:
                raise ValueError(f"Grid file '{source_grid}' missing dimensions for block {bi}.")
            parts = dim_line.split()
            if len(parts) != 3:
                raise ValueError(
                    f"Invalid dimensions line at {source_grid}:{lineno}. Expected 3 integers, got: '{dim_line}'."
                )
            try:
                im, jm, km = (int(parts[0]), int(parts[1]), int(parts[2]))
            except ValueError:
                raise ValueError(
                    f"Invalid dimensions line at {source_grid}:{lineno}. Non-integer values: '{dim_line}'."
                )
            if im <= 0 or jm <= 0 or km <= 0:
                raise ValueError(
                    f"Invalid block dimensions at {source_grid}:{lineno}: ({im}, {jm}, {km}). Must be > 0."
                )
            dims.append((im, jm, km))
 
    return dims
 
def validate_and_nondimensionalize_picslice(source_slice: str, dest_slice: str, U_ref: float,
                                            expected_dims: tuple = None) -> dict:
    """!
    @brief Validate a canonical PICSLICE payload and write a solver-scale copy.
    @param[in] source_slice Input PICSLICE path.
    @param[in] dest_slice Output staged PICSLICE path.
    @param[in] U_ref Reference velocity for non-dimensionalization.
    @param[in] expected_dims Optional expected (n1, n2) slice dimensions.
    @return Summary dictionary with frame_count, dims, value_count, min_speed, max_speed.
    @throws ValueError on malformed slice.
    """
    if U_ref == 0.0:
        raise ValueError("velocity_ref must be non-zero when processing PICSLICE speeds.")
    if not os.path.isfile(source_slice):
        raise ValueError(f"PICSLICE file not found: {source_slice}")
 
    with open(source_slice, "r") as fin:
        line_iter = _iter_nonempty_noncomment_lines(fin)
        try:
            _, first_token = next(line_iter)
        except StopIteration:
            raise ValueError(f"PICSLICE file '{source_slice}' is empty.")
        if first_token != "PICSLICE":
            raise ValueError(f"PICSLICE file '{source_slice}' must begin with the canonical PICSLICE header token.")
 
        try:
            _, frame_line = next(line_iter)
            frame_count = int(frame_line)
        except StopIteration:
            raise ValueError(f"PICSLICE file '{source_slice}' missing frame count after PICSLICE header.")
        except ValueError:
            raise ValueError(f"Invalid frame count '{frame_line}' in PICSLICE file '{source_slice}'.")
        if frame_count != 1:
            raise ValueError(
                f"PICSLICE file '{source_slice}' has frame count {frame_count}; PICurv reads exactly one frame."
            )
 
        try:
            lineno, dim_line = next(line_iter)
        except StopIteration:
            raise ValueError(f"PICSLICE file '{source_slice}' missing slice dimensions.")
        parts = dim_line.split()
        if len(parts) != 2:
            raise ValueError(
                f"Invalid PICSLICE dimensions at {source_slice}:{lineno}. Expected 2 integers, got: '{dim_line}'."
            )
        try:
            n1, n2 = (int(parts[0]), int(parts[1]))
        except ValueError:
            raise ValueError(
                f"Invalid PICSLICE dimensions at {source_slice}:{lineno}. Non-integer values: '{dim_line}'."
            )
        if n1 <= 0 or n2 <= 0:
            raise ValueError(f"Invalid PICSLICE dimensions at {source_slice}:{lineno}: ({n1}, {n2}). Must be > 0.")
        if expected_dims is not None and (n1, n2) != tuple(expected_dims):
            raise ValueError(
                f"PICSLICE dimension mismatch for '{source_slice}': expected {tuple(expected_dims)}, found {(n1, n2)}."
            )
 
        values = []
        for lineno, value_line in line_iter:
            parts = value_line.split()
            if len(parts) != 1:
                raise ValueError(
                    f"Invalid PICSLICE value row at {source_slice}:{lineno}. Expected 1 float, got: '{value_line}'."
                )
            try:
                value = float(parts[0])
            except ValueError:
                raise ValueError(f"Invalid PICSLICE value at {source_slice}:{lineno}: '{value_line}'.")
            if not math.isfinite(value):
                raise ValueError(f"PICSLICE value at {source_slice}:{lineno} must be finite.")
            if value < 0.0:
                raise ValueError(f"PICSLICE value at {source_slice}:{lineno} must be nonnegative.")
            values.append(value)
 
    expected_count = n1 * n2
    if len(values) != expected_count:
        raise ValueError(
            f"PICSLICE file '{source_slice}' has {len(values)} values, expected {expected_count} from dimensions {(n1, n2)}."
        )
 
    os.makedirs(os.path.dirname(dest_slice), exist_ok=True)
    with open(dest_slice, "w") as fout:
        fout.write("PICSLICE\n")
        fout.write("1\n")
        fout.write(f"{n1} {n2}\n")
        for value in values:
            fout.write(f"{value / U_ref:.8e}\n")
 
    return {
        "frame_count": frame_count,
        "dims": (n1, n2),
        "value_count": len(values),
        "min_speed": min(values) if values else 0.0,
        "max_speed": max(values) if values else 0.0,
    }
 
def _face_artifact_token(face: str) -> str:
    """!
    @brief Convert a BC face token into a filesystem-friendly artifact token.
    @param[in] face Canonical face token such as -Zeta.
    @return Filesystem-friendly face token.
    """
    return face.replace("+", "pos").replace("-", "neg")
 
def _resolve_run_artifact_path(run_dir: str, configured_path: str, default_path: str,
                               default_to_config_dir: bool = False) -> str:
    """!
    @brief Resolve a run artifact path with run-dir-relative defaults.
    @param[in] run_dir Run/precompute directory root.
    @param[in] configured_path Optional user-provided artifact path.
    @param[in] default_path Default path relative to run_dir.
    @param[in] default_to_config_dir If true, bare relative names are placed under config/.
    @return Absolute artifact path.
    """
    path = configured_path if configured_path else default_path
    if not isinstance(path, str) or not path.strip():
        raise ValueError("generated profile output_file must be a non-empty path when provided.")
    path = path.strip()
    if os.path.isabs(path):
        return os.path.abspath(path)
    if default_to_config_dir and os.path.dirname(path) == "":
        path = os.path.join("config", path)
    return os.path.abspath(os.path.join(run_dir, path))
 
def _resolve_generator_script(configured_script: str, case_path: str, default_name: str) -> str:
    """!
    @brief Resolve an optional generator script override or repository default.
    @param[in] configured_script Optional absolute or case-relative script path.
    @param[in] case_path Current case.yml path used to anchor relative overrides.
    @param[in] default_name Repository generator filename under GENERATORS_PATH.
    @return Absolute generator script path.
    """
    if configured_script is None:
        return os.path.join(GENERATORS_PATH, default_name)
    if not isinstance(configured_script, str) or not configured_script.strip():
        raise ValueError(f"Generator script override for {default_name} must be a non-empty path.")
    script = configured_script.strip()
    case_dir = os.path.dirname(os.path.abspath(case_path)) if case_path else os.getcwd()
    return _resolve_case_relative_path(script, case_dir)
 
def _normalize_square_duct_poiseuille_params(params, field_name: str) -> dict:
    """!
    @brief Validate square-duct Poiseuille generator parameters.
    @param[in] params Generator params mapping.
    @param[in] field_name Human-readable YAML field name for diagnostics.
    @return Normalized params.
    """
    if params is None:
        params = {}
    if not isinstance(params, dict):
        raise ValueError(f"{field_name}.params must be a mapping when provided.")
    unknown = sorted(set(params.keys()) - {"bulk_velocity", "n_terms"})
    if unknown:
        raise ValueError(f"Unknown keys in {field_name}.params: {unknown}. Allowed: ['bulk_velocity', 'n_terms'].")
    bulk_velocity = _to_float(params.get("bulk_velocity", 1.0), f"{field_name}.params.bulk_velocity")
    if bulk_velocity <= 0.0:
        raise ValueError(f"{field_name}.params.bulk_velocity must be positive.")
    try:
        n_terms = int(params.get("n_terms", 101))
    except (TypeError, ValueError):
        raise ValueError(f"{field_name}.params.n_terms must be a positive odd integer.")
    if n_terms <= 0 or n_terms % 2 == 0:
        raise ValueError(f"{field_name}.params.n_terms must be a positive odd integer.")
    return {"bulk_velocity": bulk_velocity, "n_terms": n_terms}
 
GENERATED_PROFILE_GENERATORS = {"square_duct_poiseuille"}
 
def _normalize_field_slice_source(source, field_name: str) -> dict:
    """!
    @brief Validate a prescribed_flow field_slice source block.
    @param[in] source Source mapping from case.yml.
    @param[in] field_name Human-readable YAML path for diagnostics.
    @return Normalized source mapping.
    """
    allowed = {
        "type",
        "script",
        "field_file",
        "grid_file",
        "source_case",
        "velocity_scale",
        "source_block",
        "slice",
    }
    if "output_file" in source:
        raise ValueError(retired_destination_message(field_name, "output_file"))
    unknown = sorted(set(source.keys()) - allowed)
    if unknown:
        raise ValueError(f"Unknown keys in {field_name}: {unknown}. Allowed: {sorted(allowed)}.")
    field_file = source.get("field_file")
    grid_file = source.get("grid_file")
    if not isinstance(field_file, str) or not field_file.strip():
        raise ValueError(f"{field_name}.field_file must be a non-empty path.")
    if not isinstance(grid_file, str) or not grid_file.strip():
        raise ValueError(f"{field_name}.grid_file must be a non-empty path.")
    if source.get("source_case") is None and source.get("velocity_scale") is None:
        raise ValueError(f"{field_name} requires source_case or velocity_scale.")
 
    normalized = {
        "type": "field_slice",
        "field_file": field_file.strip(),
        "grid_file": grid_file.strip(),
        "slice": _normalize_field_slice_selector(source.get("slice"), f"{field_name}.slice"),
    }
    if source.get("script") is not None:
        script = source.get("script")
        if not isinstance(script, str) or not script.strip():
            raise ValueError(f"{field_name}.script must be a non-empty path when provided.")
        normalized["script"] = script.strip()
    if source.get("source_case") is not None:
        source_case = source.get("source_case")
        if not isinstance(source_case, str) or not source_case.strip():
            raise ValueError(f"{field_name}.source_case must be a non-empty path when provided.")
        normalized["source_case"] = source_case.strip()
    if source.get("velocity_scale") is not None:
        velocity_scale = _to_float(source.get("velocity_scale"), f"{field_name}.velocity_scale")
        if velocity_scale <= 0.0:
            raise ValueError(f"{field_name}.velocity_scale must be positive.")
        normalized["velocity_scale"] = velocity_scale
    if source.get("source_block") is not None:
        try:
            source_block = int(source.get("source_block"))
        except (TypeError, ValueError):
            raise ValueError(f"{field_name}.source_block must be a non-negative integer.")
        if source_block < 0:
            raise ValueError(f"{field_name}.source_block must be a non-negative integer.")
        normalized["source_block"] = source_block
    return normalized
 
def _normalize_field_slice_selector(slice_cfg, field_name: str) -> dict:
    """!
    @brief Validate the field_slice slice selector.
    @param[in] slice_cfg Slice selector mapping.
    @param[in] field_name Human-readable YAML path for diagnostics.
    @return Normalized selector mapping.
    """
    if not isinstance(slice_cfg, dict):
        raise ValueError(f"{field_name} must be a mapping.")
    orientation = str(slice_cfg.get("orientation", "opposite")).strip().lower()
    if orientation not in {"opposite", "same"}:
        raise ValueError(f"{field_name}.orientation must be 'opposite' or 'same'.")
    normal_tolerance = _to_float(slice_cfg.get("normal_tolerance", 0.99), f"{field_name}.normal_tolerance")
    if normal_tolerance <= 0.0 or normal_tolerance > 1.0:
        raise ValueError(f"{field_name}.normal_tolerance must be in the range (0, 1].")
 
    if slice_cfg.get("face") is not None:
        unknown = sorted(set(slice_cfg.keys()) - {"face", "orientation", "normal_tolerance"})
        if unknown:
            raise ValueError(
                f"Unknown keys in {field_name}: {unknown}. "
                "Use either face or axis/index/normal, plus orientation/normal_tolerance."
            )
        face = str(slice_cfg.get("face", "")).strip()
        if face.lower() not in BC_FACE_MAP:
            raise ValueError(f"{field_name}.face must be one of {sorted(BC_FACE_MAP.values())}.")
        return {
            "face": BC_FACE_MAP[face.lower()],
            "orientation": orientation,
            "normal_tolerance": normal_tolerance,
        }
 
    required = {"axis", "index", "normal"}
    missing = sorted(key for key in required if slice_cfg.get(key) is None)
    if missing:
        raise ValueError(f"{field_name} requires either face or axis/index/normal; missing {missing}.")
    unknown = sorted(set(slice_cfg.keys()) - {"axis", "index", "normal", "orientation", "normal_tolerance"})
    if unknown:
        raise ValueError(
            f"Unknown keys in {field_name}: {unknown}. "
            "Use either face or axis/index/normal, plus orientation/normal_tolerance."
        )
    axis = str(slice_cfg.get("axis", "")).strip()
    axis_map = {"xi": "Xi", "eta": "Eta", "zeta": "Zeta"}
    if axis.lower() not in axis_map:
        raise ValueError(f"{field_name}.axis must be one of Xi, Eta, Zeta.")
    normal = str(slice_cfg.get("normal", "")).strip()
    if normal.lower() not in BC_FACE_MAP:
        raise ValueError(f"{field_name}.normal must be one of {sorted(BC_FACE_MAP.values())}.")
    normal = BC_FACE_MAP[normal.lower()]
    if normal[1:].lower() != axis.lower():
        raise ValueError(f"{field_name}.normal must use the same axis as {field_name}.axis.")
    try:
        index = int(slice_cfg.get("index"))
    except (TypeError, ValueError):
        raise ValueError(f"{field_name}.index must be an integer.")
    if index < 0:
        raise ValueError(f"{field_name}.index must be non-negative.")
    return {
        "axis": axis_map[axis.lower()],
        "index": index,
        "normal": normal,
        "orientation": orientation,
        "normal_tolerance": normal_tolerance,
    }
 
def generate_square_duct_poiseuille_picslice(output_path: str, dims: tuple, params: dict,
                                             target_grid: str = None, target_block: int = 0,
                                             target_face: str = None, script: str = None,
                                             case_path: str = None) -> dict:
    """!
    @brief Generate a dimensional canonical PICSLICE for square-duct Poiseuille flow.
    @param[in] output_path Path to write.
    @param[in] dims PICSLICE dimensions in face storage order (n1, n2).
    @param[in] params Normalized generator params.
    @param[in] target_grid Optional canonical target PICGRID for grid-aware sampling.
    @param[in] target_block Target block index when `target_grid` is provided.
    @param[in] target_face Target inlet face when `target_grid` is provided.
    @param[in] script Optional profile.gen-compatible script override.
    @param[in] case_path Current case.yml path used to anchor relative script overrides.
    @return Summary dictionary.
    """
    n1, n2 = tuple(dims)
    profilegen_script = _resolve_generator_script(script, case_path, "profile.gen")
    if not os.path.isfile(profilegen_script):
        raise ValueError(f"profile.gen script not found: {profilegen_script}")
    cmd = [
        sys.executable,
        profilegen_script,
        "square_duct_poiseuille",
        "--output",
        output_path,
        "--dims",
        str(n1),
        str(n2),
        "--bulk-velocity",
        str(float(params["bulk_velocity"])),
        "--n-terms",
        str(int(params["n_terms"])),
    ]
    if target_grid:
        cmd.extend([
            "--target-grid",
            target_grid,
            "--target-block",
            str(int(target_block)),
            f"--target-face={target_face}",
        ])
    result = subprocess.run(cmd, text=True, capture_output=True)
    if result.returncode != 0:
        details = (result.stderr or result.stdout or "").strip()
        raise ValueError(f"profile.gen failed with exit code {result.returncode}. Details:\n{details}")
    try:
        summary = json.loads((result.stdout or "").strip().splitlines()[-1])
    except (IndexError, json.JSONDecodeError) as exc:
        raise ValueError(f"profile.gen did not emit valid JSON summary. Output:\n{result.stdout}") from exc
    summary["dims"] = tuple(summary["dims"])
    return summary
 
def generate_field_slice_picslice(output_path: str, expected_dims: tuple, source: dict,
                                  target_grid: str, target_face: str, target_block: int,
                                  case_path: str) -> dict:
    """!
    @brief Invoke profile.gen to extract a field_slice PICSLICE artifact.
    @param[in] output_path Path to write.
    @param[in] expected_dims Expected PICSLICE dimensions.
    @param[in] source Normalized field_slice source mapping.
    @param[in] target_grid Target canonical PICGRID path.
    @param[in] target_face Target inlet face token.
    @param[in] target_block Target block index.
    @param[in] case_path Path to current case.yml for relative source resolution.
    @return Summary dictionary from profile.gen.
    """
    case_dir = os.path.dirname(os.path.abspath(case_path)) if case_path else os.getcwd()
    field_file = _resolve_case_relative_path(source["field_file"], case_dir)
    source_grid = _resolve_case_relative_path(source["grid_file"], case_dir)
    velocity_scale = _resolve_field_slice_velocity_scale(source, case_dir)
    profilegen_script = _resolve_generator_script(source.get("script"), case_path, "profile.gen")
    if not os.path.isfile(profilegen_script):
        raise ValueError(f"profile.gen script not found: {profilegen_script}")
    n1, n2 = tuple(expected_dims)
    slice_cfg = source["slice"]
    cmd = [
        sys.executable,
        profilegen_script,
        "field-slice",
        "--output",
        output_path,
        "--field-file",
        field_file,
        "--source-grid",
        source_grid,
        "--target-grid",
        target_grid,
        "--source-block",
        str(int(source.get("source_block", 0))),
        "--target-block",
        str(int(target_block)),
        f"--target-face={target_face}",
        "--orientation",
        slice_cfg["orientation"],
        "--normal-tolerance",
        str(float(slice_cfg["normal_tolerance"])),
        "--velocity-scale",
        str(float(velocity_scale)),
        "--expected-dims",
        str(n1),
        str(n2),
        *petsc_index_arguments(payload_petsc_index_bytes(field_file)),
    ]
    if "face" in slice_cfg:
        cmd.append(f"--slice-face={slice_cfg['face']}")
    else:
        cmd.extend([
            "--slice-axis",
            slice_cfg["axis"],
            "--slice-index",
            str(int(slice_cfg["index"])),
            f"--slice-normal={slice_cfg['normal']}",
        ])
    result = subprocess.run(cmd, text=True, capture_output=True)
    if result.returncode != 0:
        details = (result.stderr or result.stdout or "").strip()
        raise ValueError(f"profile.gen field-slice failed with exit code {result.returncode}. Details:\n{details}")
    try:
        summary = json.loads((result.stdout or "").strip().splitlines()[-1])
    except (IndexError, json.JSONDecodeError) as exc:
        raise ValueError(f"profile.gen field-slice did not emit valid JSON summary. Output:\n{result.stdout}") from exc
    summary["dims"] = tuple(summary["dims"])
    return summary
 
def _resolve_case_relative_path(path_value: str, case_dir: str) -> str:
    """!
    @brief Resolve a path relative to the current case directory.
    @param[in] path_value Path from case.yml.
    @param[in] case_dir Current case directory.
    @return Absolute path.
    """
    if not isinstance(path_value, str) or not path_value.strip():
        raise ValueError("path value must be a non-empty string.")
    workspace_root = find_workspace_root(case_dir)
    if workspace_root:
        if os.path.isabs(path_value):
            raise ValueError(
                f"absolute path {path_value!r} is not allowed in workspace case configuration; "
                "use 'picurv inputs import --mode reference' for an explicit external reference."
            )
        resolved = os.path.abspath(os.path.join(workspace_root, path_value))
        if os.path.commonpath([workspace_root, resolved]) != os.path.abspath(workspace_root):
            raise ValueError(f"path {path_value!r} escapes the workspace.")
        if resolved.endswith(".reference.yml") and os.path.isfile(resolved):
            pointer = read_yaml_file(resolved)
            external = pointer.get("picurv_external_reference") if isinstance(pointer, dict) else None
            if not isinstance(external, str) or not os.path.isabs(external):
                raise ValueError(f"Invalid external-reference descriptor: {resolved}")
            if not os.path.isfile(external):
                raise ValueError(f"Registered external input is unavailable: {external}")
            return external
        return resolved
    if os.path.isabs(path_value):
        return os.path.abspath(path_value)
    return os.path.abspath(os.path.join(case_dir, path_value))
 
def _resolve_field_slice_velocity_scale(source: dict, case_dir: str) -> float:
    """!
    @brief Resolve field_slice dimensional velocity scale.
    @param[in] source Normalized field_slice source mapping.
    @param[in] case_dir Current case directory.
    @return Positive velocity scale.
    """
    if source.get("velocity_scale") is not None:
        return float(source["velocity_scale"])
    source_case = _resolve_case_relative_path(source["source_case"], case_dir)
    source_case_cfg = read_yaml_file(source_case)
    try:
        velocity_scale = _to_float(
            source_case_cfg.get("properties", {}).get("scaling", {}).get("velocity_ref"),
            "source_case.properties.scaling.velocity_ref",
        )
    except AttributeError as exc:
        raise ValueError("source_case must contain properties.scaling.velocity_ref.") from exc
    if velocity_scale <= 0.0:
        raise ValueError("source_case.properties.scaling.velocity_ref must be positive.")
    return velocity_scale
 
def resolve_target_grid_for_field_slice(case_cfg: dict, case_path: str, run_dir: str) -> str:
    """!
    @brief Resolve the target canonical PICGRID path needed for field_slice normals.
    @param[in] case_cfg Parsed current case config.
    @param[in] case_path Current case.yml path.
    @param[in] run_dir Current run/precompute directory.
    @return Absolute target PICGRID path.
    """
    grid_cfg = case_cfg.get("grid", {}) or {}
    grid_mode = grid_cfg.get("mode")
    case_dir = os.path.dirname(os.path.abspath(case_path)) if case_path else os.getcwd()
    if grid_mode == "file":
        source_grid = grid_cfg.get("source_file")
        if not isinstance(source_grid, str) or not source_grid.strip():
            raise ValueError("grid.source_file is required for field_slice target-grid normals.")
        source_grid = _resolve_case_relative_path(source_grid, case_dir)
        return source_grid
    if grid_mode == "grid_gen":
        candidate = os.path.abspath(os.path.join(run_dir, "inputs", "grid", "grid.generated.picgrid"))
        if os.path.isfile(candidate):
            return candidate
        staged = os.path.join(run_dir, "inputs", "grid", "grid.run")
        if os.path.isfile(staged):
            return staged
        raise ValueError("field_slice requires the generated target PICGRID to exist before profile extraction.")
    raise ValueError(
        f"field_slice requires grid.mode 'file' or 'grid_gen' for target-grid normals; got '{grid_mode}'."
    )
 
def resolve_target_grid_for_generated_profile(case_cfg: dict, case_path: str, run_dir: str) -> str:
    """!
    @brief Resolve the target canonical PICGRID for generated profile sampling.
    @details The simulator builds a programmatic_c grid itself, so no grid file exists
             here. The profile is sampled instead on the bridge PICGRID that a Python
             initial condition already uses, written with the solver's own node formula.
             Without a grid the generator could only sample uniform logical points and
             normalize to the continuous-area mean, which delivered about 2/n too much
             flux on n cells across (programmatic-inlet-flux-2026-09-18).
    @param[in] case_cfg Parsed current case config.
    @param[in] case_path Current case.yml path.
    @param[in] run_dir Current run/precompute directory.
    @return Absolute target PICGRID path.
    """
    grid_cfg = case_cfg.get("grid", {}) or {}
    if grid_cfg.get("mode") == "programmatic_c":
        bridge = os.path.abspath(os.path.join(run_dir, "inputs", "grid", "grid.run"))
        if not os.path.isfile(bridge):
            generate_picgrid_from_programmatic_settings(
                grid_cfg.get("programmatic_settings", {}), bridge,
                input_reference_scale(("case", "grid", "programmatic_settings", "xMins"),
                                      resolve_reference_scales(case_cfg)),
            )
        return bridge
    return resolve_target_grid_for_field_slice(case_cfg, case_path, run_dir)
 
def write_profile_info(config_dir: str, summaries: list) -> str:
    """!
    @brief Write a profile.info summary for generated inlet profiles.
    @param[in] config_dir Run/precompute config directory.
    @param[in] summaries Generated profile summaries.
    @return Path to profile.info.
    """
    info_path = os.path.join(config_dir, "profile.info")
    os.makedirs(config_dir, exist_ok=True)
    with open(info_path, "w") as fout:
        fout.write("# PICurv generated profile summary\n")
        fout.write(f"profile_count = {len(summaries)}\n\n")
        for idx, summary in enumerate(summaries):
            dims = summary.get("dims", (0, 0))
            fout.write(f"[profile_{idx}]\n")
            fout.write(f"generator = {summary.get('generator')}\n")
            fout.write(f"block = {summary.get('block')}\n")
            fout.write(f"face = {summary.get('face')}\n")
            fout.write(f"dimensions = {dims[0]} {dims[1]}\n")
            if summary.get("bulk_velocity") is not None:
                fout.write(f"bulk_velocity = {summary.get('bulk_velocity'):.16e}\n")
            if summary.get("n_terms") is not None:
                fout.write(f"n_terms = {summary.get('n_terms')}\n")
            fout.write(f"mean_speed = {summary.get('mean_speed'):.16e}\n")
            if "area_mean_speed" in summary:
                fout.write(f"area_mean_speed = {summary.get('area_mean_speed'):.16e}\n")
            if "discrete_mean_speed" in summary:
                fout.write(f"discrete_mean_speed = {summary.get('discrete_mean_speed'):.16e}\n")
            fout.write(f"min_speed = {summary.get('min_speed'):.16e}\n")
            fout.write(f"max_speed = {summary.get('max_speed'):.16e}\n")
            if summary.get("umax_over_ubulk") is not None:
                fout.write(f"umax_over_ubulk = {summary.get('umax_over_ubulk'):.16e}\n")
            for key in (
                "normalization",
                "sampling",
                "area_weighted_mean_before_normalization",
                "area_weighted_mean_after_normalization",
                "total_inlet_area",
                "face_area_min",
                "face_area_max",
                "source_field",
                "source_grid",
                "target_grid",
                "source_block",
                "target_block",
                "target_face",
                "source_slice",
                "orientation",
                "normal_tolerance",
                "normal_dot",
                "velocity_scale",
            ):
                if key in summary:
                    fout.write(f"{key} = {summary.get(key)}\n")
            fout.write(f"output_file = {summary.get('path')}\n\n")
    return info_path
 
#: Generator flags whose values are drawn from a closed choice set. Checking them where
#: the case is validated turns a mid-run subprocess failure into a startup error.
GRID_GENERATOR_CHOICE_FLAGS = {
    "--cross-section": GRID_CROSS_SECTION_KINDS,
}
 
#: Generator flags taking an ordered `kind:key=value` list whose kinds are closed.
GRID_GENERATOR_SPEC_FLAGS = {
    "--wall-j-lo": GRID_WALL_SEGMENT_KINDS,
    "--wall-j-hi": GRID_WALL_SEGMENT_KINDS,
    "--wall-j-lo-span": GRID_WALL_SEGMENT_KINDS,
    "--wall-j-hi-span": GRID_WALL_SEGMENT_KINDS,
    "--cross-section-scale": GRID_WALL_SEGMENT_KINDS,
    "--path": GRID_PATH_SEGMENT_KINDS,
    "--transforms": GRID_TRANSFORM_KINDS,
}
 
 
def validate_grid_generator_cli_args(cli_args, case_path: str) -> list:
    """!
    @brief Check closed-choice values inside the generator's opaque token list.
    @details `cli_args` is passed through to grid.gen untouched, so a misspelled geometry
             selector there is only discovered when the subprocess exits nonzero partway
             into a run. The generator remains the authority; this reports the same set
             earlier, and stays silent on anything it does not recognize.
    @param[in] cli_args Raw token list from grid.generator.cli_args.
    @param[in] case_path Case file path for diagnostics.
    @return List of error strings.
    """
    if not isinstance(cli_args, list):
        return []
    tokens = [str(token) for token in cli_args]
    errors = []
    for index, token in enumerate(tokens):
        values = []
        for follower in tokens[index + 1:]:
            if follower.startswith("--"):
                break
            values.append(follower)
        if token in GRID_GENERATOR_CHOICE_FLAGS:
            allowed = GRID_GENERATOR_CHOICE_FLAGS[token]
            for value in values[:1]:
                if value not in allowed:
                    errors.append(
                        f"  {case_path}: grid.generator.cli_args {token} must be one of "
                        f"{list(allowed)} (got '{value}')."
                    )
        elif token in GRID_GENERATOR_SPEC_FLAGS:
            allowed = GRID_GENERATOR_SPEC_FLAGS[token]
            for value in values:
                kind = value.split(":", 1)[0]
                if kind not in allowed:
                    errors.append(
                        f"  {case_path}: grid.generator.cli_args {token} entry '{value}' "
                        f"names '{kind}', which is not one of {list(allowed)}."
                    )
    return errors
 
 
def run_grid_generator(case_path: str, run_dir: str, grid_cfg: dict,
                       case_cfg: dict = None) -> str:
    """!
    @brief Runs generators/grid.gen to produce a PICGRID file for this run.
    @param[in] case_path Path to case.yml (used for relative path resolution).
    @param[in] run_dir Run directory path.
    @param[in] grid_cfg The grid config section from case.yml.
    @param[in] case_cfg Parsed case configuration, when available. Its reference scales
                        are handed to the generator so the quality report can carry
                        solver and wall units. Reporting only: the generator never scales
                        coordinates, which validate_and_nondimensionalize_picgrid does
                        once for every grid regardless of origin.
    @return Absolute path to generated dimensional PICGRID file.
    @throws ValueError on invalid config or generator failure.
    """
    generator = grid_cfg.get("generator", {})
    if not isinstance(generator, dict):
        raise ValueError("grid.generator must be a mapping when grid.mode is 'grid_gen'.")
 
    case_dir = os.path.dirname(os.path.abspath(case_path))
    gridgen_script = generator.get("script", os.path.join(GENERATORS_PATH, "grid.gen"))
    if generator.get("script"):
        gridgen_script = _resolve_case_relative_path(gridgen_script, case_dir)
    else:
        gridgen_script = os.path.abspath(gridgen_script)
    if not os.path.isfile(gridgen_script):
        raise ValueError(f"grid.gen script not found: {gridgen_script}")
 
    config_file = generator.get("config_file")
    if not config_file:
        raise ValueError("grid.generator.config_file is required when grid.mode is 'grid_gen'.")
    config_file = _resolve_case_relative_path(config_file, case_dir)
    if not os.path.isfile(config_file):
        raise ValueError(f"grid.generator.config_file not found: {config_file}")
 
    output_file = os.path.abspath(os.path.join(run_dir, "inputs", "grid", "grid.generated.picgrid"))
    os.makedirs(os.path.dirname(output_file), exist_ok=True)
 
    grid_type = generator.get("grid_type")
    cli_args = generator.get("cli_args", [])
    if cli_args is None:
        cli_args = []
    if not isinstance(cli_args, list):
        raise ValueError("grid.generator.cli_args must be a list of CLI tokens.")
 
    cmd = [sys.executable, gridgen_script, "-c", config_file]
    if grid_type:
        cmd.append(str(grid_type))
    cmd.extend([str(token) for token in cli_args])
    cmd.extend(["--output", output_file])
 
    # Destinations are PICurv's, not the user's. Inspection material is produced
    # unconditionally so a published asset is always something the user can look at,
    # rather than only when a configuration file happened to name an output path.
    vts_file = os.path.abspath(
        os.path.join(run_dir, "output", "visualization", "precompute", "grid.vts")
    )
    os.makedirs(os.path.dirname(vts_file), exist_ok=True)
    cmd.extend(["--vts", vts_file])
 
    stats_file = os.path.abspath(
        os.path.join(run_dir, "output", "analysis", "metrics", "grid.info")
    )
    os.makedirs(os.path.dirname(stats_file), exist_ok=True)
    cmd.extend(["--stats-file", stats_file])
 
    # The case already knows these; the generator would otherwise report a grid in metres
    # with no way to say what it becomes downstream. Resolution is best-effort: a case
    # that omits them still gets its grid, just without the derived-unit sections.
    if case_cfg:
        try:
            scaling = resolve_fluid_scaling(case_cfg)
        except (KeyError, ValueError, TypeError):
            scaling = None
        if scaling:
            cmd.extend(["--length-ref", repr(scaling["length_ref"]),
                        "--velocity-ref", repr(scaling["velocity_ref"]),
                        "--nu", repr(scaling["physical_kinematic_viscosity"])])
 
    print(f"[INFO] Grid generator command: {' '.join(cmd)}")
    result = subprocess.run(cmd, cwd=case_dir, text=True, capture_output=True)
    if result.returncode != 0:
        stderr = (result.stderr or "").strip()
        stdout = (result.stdout or "").strip()
        details = stderr if stderr else stdout
        raise ValueError(
            f"grid.gen failed with exit code {result.returncode}. Details:\n{details}"
        )
    if result.stdout:
        print(result.stdout.strip())
    if result.stderr:
        print(result.stderr.strip())
 
    if not os.path.isfile(output_file):
        raise ValueError(f"grid.gen did not produce expected output file: {output_file}")
 
    return output_file
 
 
BC_FACE_MAP = {
    "-xi": "-Xi",
    "+xi": "+Xi",
    "-eta": "-Eta",
    "+eta": "+Eta",
    "-zeta": "-Zeta",
    "+zeta": "+Zeta",
}
 
# Canonical BC selector maps. Add new values only with matching C parser/factory support.
BC_TYPE_MAP = {
    "wall": "WALL",
    "inlet": "INLET",
    "outlet": "OUTLET",
    "periodic": "PERIODIC",
}
 
# What a particle crossing a boundary face becomes: mirrored back about the face plane,
# removed as having left the domain, or (periodic faces only) re-entered through the paired
# face. Each handler states its default; a BC entry may override it with `particle_policy`.
PARTICLE_BOUNDARY_POLICIES = ("reflect", "remove", "wrap")
 
BC_HANDLER_SPECS = {
    # Only handlers that are implemented end-to-end in current C path are allowed.
    "noslip": {
        "types": {"WALL"},
        "particle_policy": "reflect",
        "required_params": set(),
        "optional_params": set(),
    },
    # Impenetrable and shear-free; also the condition at a plane of symmetry.
    "free_slip": {
        "types": {"WALL"},
        "particle_policy": "reflect",
        "required_params": set(),
        "optional_params": set(),
    },
    "constant_velocity": {
        "types": {"INLET"},
        "particle_policy": "remove",
        "required_params": {"vx", "vy", "vz"},
        "optional_params": set(),
    },
    "conservation": {
        "types": {"OUTLET"},
        "particle_policy": "remove",
        "required_params": set(),
        "optional_params": set(),
    },
    "parabolic": {
        "types": {"INLET"},
        "particle_policy": "remove",
        "required_params": {"v_max"},
        "optional_params": set(),
    },
    "prescribed_flow": {
        "types": {"INLET"},
        "particle_policy": "remove",
        "required_params": {"source"},
        "optional_params": set(),
    },
    "geometric": {
        "types": {"PERIODIC"},
        "particle_policy": "wrap",
        "required_params": set(),
        "optional_params": set(),
    },
    "constant_flux": {
        "types": {"PERIODIC"},
        "particle_policy": "wrap",
        "required_params": {"target_flux"},
        "optional_params": {"enforce_seam_flux", "apply_trim"},
    },
    # Derives its own target from the initial condition, so it takes no target_flux.
    "initial_flux": {
        "types": {"PERIODIC"},
        "particle_policy": "wrap",
        "required_params": set(),
        "optional_params": {"enforce_seam_flux", "apply_trim"},
    },
}
 
_NUMERIC_BC_PARAMS = {"vx", "vy", "vz", "v_max", "target_flux"}
_BOOL_BC_PARAMS = {"enforce_seam_flux", "apply_trim"}
 
# Deprecated BC param spellings -> canonical name. `apply_trim` said that
# something was trimmed but not what or why; `enforce_seam_flux` names the
# quantity it holds on target. Both are accepted; bcs.run carries the canonical
# name, and the C side also falls back to the old spelling for archived files.
_DEPRECATED_BC_PARAM_ALIASES = {"apply_trim": "enforce_seam_flux"}
 
def _normalize_prescribed_flow_source(source, field_name: str) -> dict:
    """!
    @brief Validate the structured source block for prescribed_flow BCs.
    @param[in] source Source mapping from case.yml.
    @param[in] field_name Human-readable YAML path for diagnostics.
    @return Normalized source mapping.
    @throws ValueError on invalid source contract.
    """
    if not isinstance(source, dict):
        raise ValueError(f"{field_name} must be a mapping with type: file, generated, or field_slice.")
    source_type = str(source.get("type", "")).strip().lower()
    if source_type == "file":
        path = source.get("path")
        if not isinstance(path, str) or not path.strip():
            raise ValueError(f"{field_name}.path must be a non-empty file path.")
        unknown = sorted(set(source.keys()) - {"type", "path"})
        if unknown:
            raise ValueError(f"Unknown keys in {field_name}: {unknown}. Allowed: ['path', 'type'].")
        return {"type": "file", "path": path.strip()}
 
    if source_type == "generated":
        generator = str(source.get("generator", "")).strip().lower()
        if generator not in GENERATED_PROFILE_GENERATORS:
            raise ValueError(
                f"{field_name}.generator must be one of {sorted(GENERATED_PROFILE_GENERATORS)} "
                f"(got '{source.get('generator')}')."
            )
        if "output_file" in source:
            raise ValueError(retired_destination_message(field_name, "output_file"))
        unknown = sorted(set(source.keys()) - {"type", "generator", "script", "params"})
        if unknown:
            raise ValueError(
                f"Unknown keys in {field_name}: {unknown}. "
                "Allowed: ['generator', 'params', 'script', 'type']."
            )
        normalized = {
            "type": "generated",
            "generator": generator,
            "params": _normalize_square_duct_poiseuille_params(source.get("params", {}), field_name),
        }
        script = source.get("script")
        if script is not None:
            if not isinstance(script, str) or not script.strip():
                raise ValueError(f"{field_name}.script must be a non-empty path when provided.")
            normalized["script"] = script.strip()
        return normalized
 
    if source_type == "field_slice":
        return _normalize_field_slice_source(source, field_name)
 
    raise ValueError(f"{field_name}.type must be 'file', 'generated', or 'field_slice'.")
 
def _bc_profile_expected_dims(face: str, block_dims: tuple) -> tuple:
    """!
    @brief Return expected PICSLICE dimensions for a face and block node dimensions.
    @param[in] face Canonical BC face token.
    @param[in] block_dims (IM, JM, KM) node counts.
    @return (n1, n2) dimensions in profile storage order.
    """
    im, jm, km = block_dims
    if min(im, jm, km) < 2:
        raise ValueError(
            f"Block dimensions {block_dims} are too small for an inlet profile; each axis needs at least 2 nodes."
        )
    if face in {"-Xi", "+Xi"}:
        return (km - 1, jm - 1)
    if face in {"-Eta", "+Eta"}:
        return (km - 1, im - 1)
    if face in {"-Zeta", "+Zeta"}:
        return (jm - 1, im - 1)
    raise ValueError(f"Unsupported face '{face}' for prescribed_flow profile dimensions.")
 
def resolve_grid_block_dimensions_for_profiles(case_cfg: dict, case_path: str, run_dir: str = None) -> list:
    """!
    @brief Resolve per-block node dimensions for prescribed inlet profile validation.
    @param[in] case_cfg Parsed case.yml configuration.
    @param[in] case_path Path to case.yml for relative path resolution.
    @param[in] run_dir Current run directory, used for optional generated grid outputs.
    @return List of (IM, JM, KM) node-count tuples.
    @throws ValueError when dimensions cannot be resolved.
    """
    num_blocks = int(case_cfg.get('models', {}).get('domain', {}).get('blocks', 1))
    grid_cfg = case_cfg.get("grid", {})
    grid_mode = grid_cfg.get("mode")
    case_dir = os.path.dirname(os.path.abspath(case_path)) if case_path else os.getcwd()
 
    if grid_mode == "programmatic_c":
        settings = grid_cfg.get("programmatic_settings", {})
        dims_by_axis = []
        for key in ("im", "jm", "km"):
            raw = settings.get(key)
            if raw is None:
                raise ValueError(f"grid.programmatic_settings.{key} is required for prescribed_flow profiles.")
            if isinstance(raw, list):
                if len(raw) != num_blocks:
                    raise ValueError(
                        f"grid.programmatic_settings.{key} has {len(raw)} entries, expected {num_blocks} blocks."
                    )
                values = raw
            else:
                values = [raw] * num_blocks
            try:
                values = [int(v) + 1 for v in values]
            except (TypeError, ValueError):
                raise ValueError(f"grid.programmatic_settings.{key} values must be positive integer cell counts.")
            if any(v <= 1 for v in values):
                raise ValueError(f"grid.programmatic_settings.{key} values must be positive integer cell counts.")
            dims_by_axis.append(values)
        return list(zip(dims_by_axis[0], dims_by_axis[1], dims_by_axis[2]))
 
    if grid_mode == "file":
        source_grid = grid_cfg.get("source_file")
        if not isinstance(source_grid, str) or not source_grid.strip():
            raise ValueError("grid.source_file is required for file-grid prescribed_flow profile validation.")
        source_grid = _resolve_case_relative_path(source_grid, case_dir)
        return read_picgrid_header_dimensions(source_grid, expected_nblk=num_blocks)
 
    if grid_mode == "grid_gen":
        candidates = []
        if run_dir:
            candidates.append(os.path.join(run_dir, "inputs", "grid", "grid.generated.picgrid"))
            candidates.append(os.path.join(run_dir, "inputs", "grid", "grid.run"))
        for candidate in candidates:
            if os.path.isfile(candidate):
                return read_picgrid_header_dimensions(candidate, expected_nblk=num_blocks)
        raise ValueError(
            "prescribed_flow profile dimension validation for grid.mode='grid_gen' requires an existing generated "
            "PICGRID output. Run or stage the grid first, or use grid.mode='file' with the generated .picgrid."
        )
 
    raise ValueError(f"Unsupported grid.mode '{grid_mode}' for prescribed_flow profile validation.")
 
def materialize_generated_prescribed_flow_profiles(run_dir: str, case_cfg: dict, case_path: str,
                                                   profile_grid_dims: list = None) -> list:
    """!
    @brief Generate dimensional PICSLICE artifacts for generated/field_slice prescribed_flow sources.
    @param[in] run_dir Run/precompute directory root.
    @param[in] case_cfg Parsed case.yml.
    @param[in] case_path Path to case.yml for relative grid/source resolution.
    @param[in] profile_grid_dims Optional pre-resolved block node dimensions.
    @return List of generated profile summaries.
    """
    prepared_blocks = validate_and_prepare_boundary_conditions(case_cfg)
    if not any(
        bc.get("handler") == "prescribed_flow"
        and ((bc.get("params") or {}).get("source") or {}).get("type") in PRESCRIBED_FLOW_SOURCE_TYPES[1:]
        for block in prepared_blocks for bc in block
    ):
        return []
    if profile_grid_dims is None:
        profile_grid_dims = resolve_grid_block_dimensions_for_profiles(case_cfg, case_path, run_dir)
 
    profile_dir = os.path.join(run_dir, "inputs", "inlet_profiles")
    target_grid = None
    generated_target_grid = None
    summaries = []
    for block_idx, block in enumerate(prepared_blocks):
        for bc in block:
            if bc.get("handler") != "prescribed_flow":
                continue
            source = (bc.get("params") or {}).get("source", {})
            if source.get("type") not in PRESCRIBED_FLOW_SOURCE_TYPES[1:]:
                continue
            face = bc["face"]
            dims = _bc_profile_expected_dims(face, profile_grid_dims[block_idx])
            face_token = _face_artifact_token(face)
            suffix = "generated" if source.get("type") == "generated" else "sliced"
            output_path = os.path.join(
                profile_dir,
                f"inlet_profile_block{block_idx}_{face_token}.{suffix}.dimensional.picslice",
            )
            if source.get("type") == "generated" and source["generator"] == "square_duct_poiseuille":
                if generated_target_grid is None:
                    generated_target_grid = resolve_target_grid_for_generated_profile(case_cfg, case_path, run_dir)
                summary = generate_square_duct_poiseuille_picslice(
                    output_path,
                    dims,
                    source["params"],
                    target_grid=generated_target_grid,
                    target_block=block_idx,
                    target_face=face,
                    script=source.get("script"),
                    case_path=case_path,
                )
            elif source.get("type") == "generated":
                raise ValueError(f"Unsupported generated profile generator '{source['generator']}'.")
            else:
                if target_grid is None:
                    target_grid = resolve_target_grid_for_field_slice(case_cfg, case_path, run_dir)
                summary = generate_field_slice_picslice(
                    output_path,
                    dims,
                    source,
                    target_grid,
                    face,
                    block_idx,
                    case_path,
                )
            summary.update({"block": block_idx, "face": face})
            summaries.append(summary)
            print(
                f"[SUCCESS] Materialized prescribed_flow profile for block {block_idx}, face {face}: "
                f"{os.path.relpath(output_path)} dims={summary['dims']}"
            )
 
    if summaries:
        info_path = write_profile_info(profile_dir, summaries)
        print(f"[SUCCESS] Wrote generated profile summary: {os.path.relpath(info_path)}")
    return summaries
 
def _to_float(value, field_name: str) -> float:
    """!
    @brief Convert a YAML scalar to float with a clear error message.
    @param[in] value Argument passed to `_to_float()`.
    @param[in] field_name Argument passed to `_to_float()`.
    @return Value returned by `_to_float()`.
    """
    try:
        return float(value)
    except (TypeError, ValueError):
        raise ValueError(f"'{field_name}' must be numeric (got {value!r}).")
 
 
def _to_finite_float(value, field_name: str) -> float:
    """!
    @brief Convert a non-boolean YAML scalar to a finite float.
    @param[in] value Raw YAML scalar.
    @param[in] field_name User-facing configuration path.
    @return Finite floating-point value.
    """
    if isinstance(value, bool):
        raise ValueError(f"'{field_name}' must be numeric, not boolean.")
    parsed = _to_float(value, field_name)
    if not math.isfinite(parsed):
        raise ValueError(f"'{field_name}' must be finite (got {value!r}).")
    return parsed
 
def _to_bool(value, field_name: str) -> bool:
    """!
    @brief Convert a YAML scalar/string to bool with a clear error message.
    @param[in] value Argument passed to `_to_bool()`.
    @param[in] field_name Argument passed to `_to_bool()`.
    @return Value returned by `_to_bool()`.
    """
    if isinstance(value, bool):
        return value
    if isinstance(value, str):
        raw = value.strip().lower()
        if raw in {"true", "1", "yes"}:
            return True
        if raw in {"false", "0", "no"}:
            return False
    raise ValueError(f"'{field_name}' must be boolean (got {value!r}).")
 
def normalize_boundary_conditions_layout(all_blocks_bcs, num_blocks: int):
    """!
    @brief Normalize boundary_conditions to list-of-lists form and validate block count.
    @param[in] all_blocks_bcs Argument passed to `normalize_boundary_conditions_layout()`.
    @param[in] num_blocks Argument passed to `normalize_boundary_conditions_layout()`.
    @return Value returned by `normalize_boundary_conditions_layout()`.
    """
    if not all_blocks_bcs:
        raise ValueError("The 'boundary_conditions' section in case.yml is empty.")
 
    is_simple_list = isinstance(all_blocks_bcs[0], dict)
    if num_blocks == 1 and is_simple_list:
        all_blocks_bcs = [all_blocks_bcs]
    elif is_simple_list and num_blocks > 1:
        raise ValueError(
            f"case.yml declares {num_blocks} blocks but boundary_conditions is a single face-list. "
            "Use a list-of-lists, one inner list per block."
        )
 
    if len(all_blocks_bcs) != num_blocks:
        raise ValueError(
            f"Mismatch: case.yml declares {num_blocks} block(s) but found {len(all_blocks_bcs)} BC definitions."
        )
    return all_blocks_bcs
 
def _les_periodic_axes(case_cfg: dict) -> set:
    """!
    @brief Reports which logical axes a case declares periodic on both faces.
    @param[in] case_cfg Parsed case.yml mapping.
    @return Set of axis letters drawn from {'i', 'j', 'k'}.
    """
    axis_faces = {"i": ("-Xi", "+Xi"), "j": ("-Eta", "+Eta"), "k": ("-Zeta", "+Zeta")}
    declared = {}
    entries = case_cfg.get("boundary_conditions") or []
    if entries and isinstance(entries[0], list):
        entries = entries[0]
    for entry in entries:
        if isinstance(entry, dict):
            declared[str(entry.get("face"))] = str(entry.get("type", "")).upper()
    return {
        axis for axis, faces in axis_faces.items()
        if all(declared.get(face) == "PERIODIC" for face in faces)
    }
 
 
#: Refused whenever a case carries a RANS block. The k-omega transport update was never
#: written and its fields were never allocated, so the closure was removed on 2026-09-22
#: and the subsystem returned to `planned`; src/guide.md records the hooks that went with
#: it. The message names the status rather than leaving a silently ignored block.
RANS_PLANNED_REFUSAL = (
    "models.physics.turbulence.rans is not accepted: RANS closures are planned, not "
    "implemented. No transport equation was ever solved for them, and the selector and "
    "its dead hooks were removed. Remove the block; use models.physics.turbulence.les, "
    "or run laminar."
)
 
 
def validate_wall_model_pairing(case_cfg: dict, les_cfg, wall_cfg,
                                case_path: str, errors: list, warnings: list):
    """!
    @brief Rejects wall-model selections that no turbulence treatment can support.
 
    A wall model replaces the near-wall flow with an analytic profile so that the
    boundary layer need not be resolved. That only means something if the unresolved
    motions are modelled somewhere. Three combinations cannot be, and each fails here
    rather than after the mesh is built.
 
    @param case_cfg Parsed case configuration, read for the Reynolds number.
    @param les_cfg  `models.physics.turbulence.les`, or None.
    @param wall_cfg `models.physics.turbulence.wall_function`, or None.
    @param case_path Case path, for message prefixes.
    @param errors   Collected blocking messages, appended to.
    @param warnings Collected advisory messages, appended to.
    """
    if not isinstance(wall_cfg, dict):
        return
    if not bool(wall_cfg.get('enabled', False)):
        return
 
    try:
        model = normalize_wall_function_model(wall_cfg.get('model', 'log_law'))
    except ValueError:
        return  # The selector's own validation already reported this.
 
    les_on = isinstance(les_cfg, dict) and bool(les_cfg.get('enabled', False)) \
        and str(les_cfg.get('model', 'dynamic_smagorinsky')).strip().lower() != 'none'
    # A wall model with nothing to sit on. The convective scheme here is QUICK, whose
    # dissipation is linear and upwind-biased; it is not a limiter-based scheme whose
    # truncation error stands in for a subgrid stress, so there is no implicit LES to
    # appeal to.
    if not les_on:
        errors.append(
            f"  {case_path}: models.physics.turbulence.wall_function is enabled with no "
            "turbulence model. A wall model supplies the stress of a boundary layer it "
            "does not resolve, which needs the unresolved motions modelled somewhere. "
            "This solver has no implicit-LES scheme to supply that - its convection is "
            "QUICK, whose numerical dissipation is not a subgrid model - so enable "
            "models.physics.turbulence.les, or resolve the wall and disable the wall "
            "function.")
 
    # A wall law describes a turbulent boundary layer. Below transition there is no
    # inertial region for it to stand on, and it would impose a profile the flow does not
    # have. The threshold is deliberately far below any transitional value, so that it
    # only catches cases that are unambiguously laminar.
    reynolds = _case_reynolds_number(case_cfg)
    if reynolds is not None and reynolds < 1000.0:
        errors.append(
            f"  {case_path}: models.physics.turbulence.wall_function is enabled at "
            f"Reynolds number {reynolds:g}, which is laminar. The log law and the "
            "Werner-Wengle power law both describe a turbulent boundary layer; at this "
            "Reynolds number there is no inertial region for either to represent, and "
            "the model would impose a profile the flow does not have. Resolve the wall "
            "instead.")
 
 
def _case_reynolds_number(case_cfg: dict):
    """!
    @brief Reynolds number implied by a case's scaling and fluid properties.
    @param case_cfg Parsed case configuration.
    @return The Reynolds number, or None when the inputs are absent or unusable.
    """
    try:
        props = case_cfg.get('properties', {}) or {}
        scaling = props.get('scaling', {}) or {}
        fluid = props.get('fluid', {}) or {}
        density = float(fluid.get('density'))
        viscosity = float(fluid.get('viscosity'))
        length_ref = float(scaling.get('length_ref'))
        velocity_ref = float(scaling.get('velocity_ref'))
    except (TypeError, ValueError):
        return None
    if viscosity <= 0.0:
        return None
    return density * velocity_ref * length_ref / viscosity
 
 
def validate_les_configuration(case_cfg: dict, les_cfg: dict, case_path: str,
                               errors: list, warnings: list):
    """!
    @brief Checks the structured LES block for values the closure cannot honour.
    @param[in] case_cfg Parsed case.yml mapping, used to read declared periodicity.
    @param[in] les_cfg Parsed `models.physics.turbulence.les` mapping.
    @param[in] case_path Case file path used to prefix diagnostics.
    @param[out] errors List collecting blocking validation failures.
    @param[out] warnings List collecting advisory messages.
    @return None; findings are appended to `errors` and `warnings`.
    """
    def _numeric(container, key, path, minimum=None, exclusive_minimum=None):
        """!
        @brief Reads one numeric key and records a range or type failure against it.
        @param[in] container Mapping holding the key.
        @param[in] key Key to read; absent keys are accepted silently.
        @param[in] path Dotted key path used in diagnostics.
        @param[in] minimum Inclusive lower bound, or None to impose none.
        @param[in] exclusive_minimum Exclusive lower bound, or None to impose none.
        @return The parsed value, or None when the key is absent or unparseable.
        """
        if key not in container:
            return None
        try:
            value = float(container[key])
        except (TypeError, ValueError):
            errors.append(f"  {case_path}: {path} must be numeric.")
            return None
        if minimum is not None and value < minimum:
            errors.append(f"  {case_path}: {path} must be at least {minimum}.")
        if exclusive_minimum is not None and value <= exclusive_minimum:
            errors.append(f"  {case_path}: {path} must be greater than {exclusive_minimum}.")
        return value
 
    if 'enabled' in les_cfg and not isinstance(les_cfg['enabled'], bool):
        errors.append(f"  {case_path}: models.physics.turbulence.les.enabled must be true or false.")
 
    _numeric(les_cfg, 'constant_cs', "models.physics.turbulence.les.constant_cs", minimum=0.0)
    _numeric(les_cfg, 'vreman_coefficient', "models.physics.turbulence.les.vreman_coefficient", minimum=0.0)
    _numeric(les_cfg, 'wale_coefficient', "models.physics.turbulence.les.wale_coefficient", minimum=0.0)
 
    if 'dynamic_frequency' in les_cfg:
        try:
            if int(les_cfg['dynamic_frequency']) <= 0:
                errors.append(f"  {case_path}: models.physics.turbulence.les.dynamic_frequency must be positive.")
        except (TypeError, ValueError):
            errors.append(f"  {case_path}: models.physics.turbulence.les.dynamic_frequency must be an integer.")
 
    for key, normalizer in (('filter_width', normalize_les_filter_width),):
        if key in les_cfg:
            try:
                normalizer(les_cfg[key])
            except ValueError as exc:
                errors.append(f"  {case_path}: {exc}")
 
    periodic = _les_periodic_axes(case_cfg)
 
    test_filter = les_cfg.get('test_filter')
    if test_filter is not None:
        if not isinstance(test_filter, dict):
            test_filter = {'kernel': test_filter}
        if 'kernel' in test_filter:
            try:
                kernel = normalize_les_test_filter(test_filter['kernel'])
            except ValueError as exc:
                errors.append(f"  {case_path}: {exc}")
            else:
                # The Simpson stencil collapses onto the central eta-plane, which is
                # only a valid average when xi and zeta are homogeneous.
                if kernel == 1 and not {"i", "k"} <= periodic:
                    errors.append(
                        f"  {case_path}: models.physics.turbulence.les.test_filter.kernel "
                        "'simpson_ik' assumes the xi and zeta directions are homogeneous, but "
                        "this case does not declare both of them PERIODIC. Use "
                        "'volume_weighted_box' instead."
                    )
        # A test filter no wider than the grid filter leaves the dynamic procedure with
        # nothing to measure, because both terms of the model tensor coincide.
        _numeric(test_filter, 'width_ratio',
                 "models.physics.turbulence.les.test_filter.width_ratio", exclusive_minimum=1.0)
 
    averaging = les_cfg.get('averaging')
    if averaging is not None:
        if not isinstance(averaging, dict):
            averaging = {'mode': averaging}
        mode = None
        if 'mode' in averaging:
            try:
                mode = normalize_les_averaging_mode(averaging['mode'])
            except ValueError as exc:
                errors.append(f"  {case_path}: {exc}")
        directions = None
        if 'directions' in averaging:
            try:
                directions = normalize_les_averaging_directions(averaging['directions'])
            except ValueError as exc:
                errors.append(f"  {case_path}: {exc}")
            else:
                if not directions:
                    errors.append(
                        f"  {case_path}: models.physics.turbulence.les.averaging.directions "
                        "cannot be empty; omit the key to use the periodic axes."
                    )
                if mode is not None and mode != 1:
                    errors.append(
                        f"  {case_path}: models.physics.turbulence.les.averaging.directions "
                        "applies only to mode 'homogeneous'; local and global averaging choose "
                        "their own directions."
                    )
                for axis in directions:
                    if axis not in periodic:
                        warnings.append(
                            f"{case_path}: models.physics.turbulence.les.averaging.directions "
                            f"names '{axis}', which this case does not declare PERIODIC. "
                            "Averaging assumes the flow is statistically homogeneous there."
                        )
        if mode == 1 and directions is None and not periodic:
            errors.append(
                f"  {case_path}: models.physics.turbulence.les.averaging.mode 'homogeneous' "
                "derives its directions from the periodic boundary pairs, and this case declares "
                "none. Name the directions explicitly or use 'local'."
            )
 
    clipping = les_cfg.get('clipping')
    if clipping is not None:
        if not isinstance(clipping, dict):
            clipping = {'mode': clipping}
        mode = None
        if 'mode' in clipping:
            try:
                mode = normalize_les_clip_mode(clipping['mode'])
            except ValueError as exc:
                errors.append(f"  {case_path}: {exc}")
        _numeric(clipping, 'max_cs', "models.physics.turbulence.les.clipping.max_cs", minimum=0.0)
        _numeric(clipping, 'min_viscosity_ratio',
                 "models.physics.turbulence.les.clipping.min_viscosity_ratio", minimum=0.0)
        if 'max_cs' in clipping and mode is not None and mode != 0:
            errors.append(
                f"  {case_path}: models.physics.turbulence.les.clipping.max_cs applies only to "
                "mode 'clamp'; 'positive' and 'signed' impose no upper bound. Remove the key or "
                "select mode 'clamp'."
            )
 
    # The dynamic procedure's controls have no meaning for a prescribed coefficient.
    # Only an explicitly named constant model triggers this: a template that documents
    # every key while LES is switched off should not be rejected on an inferred default.
    try:
        model_code = normalize_les_model(les_cfg['model']) if 'model' in les_cfg else None
    except ValueError:
        model_code = None
    if model_code in LES_MODEL_OWNED_KEYS and les_cfg.get('enabled', True):
        # Each model's own parameters are refused under any other, so a key that would be
        # silently ignored at runtime fails at validation instead. filter_width is shared
        # by every model that takes a scalar width; Vreman resolves each direction from
        # the cell's own edges and takes none.
        model_name = LES_MODEL_NAMES[model_code]
        for owner, keys in LES_MODEL_OWNED_KEYS.items():
            if owner == model_code:
                continue
            for key in keys:
                if key in les_cfg:
                    errors.append(
                        f"  {case_path}: models.physics.turbulence.les.{key} configures "
                        f"{LES_MODEL_KEY_OWNER_DESCRIPTIONS[owner]} and cannot be used with "
                        f"model '{model_name}'."
                    )
        if model_code == 3 and 'filter_width' in les_cfg:
            errors.append(
                f"  {case_path}: models.physics.turbulence.les.filter_width cannot be used with "
                "model 'vreman', which weights each grid direction by the cell's own edge "
                "rather than by one scalar width."
            )
 
 
def validate_and_prepare_boundary_conditions(case_cfg: dict):
    """!
    @brief Validate BC entries against currently supported C-side handlers/types and
    @details return normalized entries ready for bcs.run generation.
    @param[in] case_cfg Argument passed to `validate_and_prepare_boundary_conditions()`.
    @return Value returned by `validate_and_prepare_boundary_conditions()`.
    """
    num_blocks = int(case_cfg.get('models', {}).get('domain', {}).get('blocks', 1))
    scales = resolve_reference_scales(case_cfg)
 
    all_blocks_bcs = normalize_boundary_conditions_layout(case_cfg.get('boundary_conditions', []), num_blocks)
    prepared_blocks = []
 
    expected_faces = {"-Xi", "+Xi", "-Eta", "+Eta", "-Zeta", "+Zeta"}
    axis_pairs = [("-Xi", "+Xi"), ("-Eta", "+Eta"), ("-Zeta", "+Zeta")]
 
    for bi, block_bcs in enumerate(all_blocks_bcs):
        if not isinstance(block_bcs, list):
            raise ValueError(f"boundary_conditions[{bi}] must be a list of face configs.")
 
        prepared_block = []
        seen_faces = {}
 
        for idx, bc in enumerate(block_bcs):
            if not isinstance(bc, dict):
                raise ValueError(f"boundary_conditions[{bi}][{idx}] must be a mapping.")
 
            for req in ("face", "type", "handler"):
                if req not in bc:
                    raise ValueError(f"boundary_conditions[{bi}][{idx}] missing required key '{req}'.")
 
            face_raw = str(bc["face"]).strip()
            face_key = face_raw.lower()
            face = BC_FACE_MAP.get(face_key)
            if face is None:
                raise ValueError(
                    f"Unsupported BC face '{face_raw}' at boundary_conditions[{bi}][{idx}]. "
                    f"Supported: {sorted(expected_faces)}."
                )
            if face in seen_faces:
                raise ValueError(f"Duplicate face '{face}' in boundary_conditions[{bi}] (entries {seen_faces[face]} and {idx}).")
            seen_faces[face] = idx
 
            bc_type_raw = str(bc["type"]).strip()
            bc_type = BC_TYPE_MAP.get(bc_type_raw.lower())
            # A symmetry plane is a free-slip wall; the separate type was retired.
            if bc_type_raw.lower() == "symmetry":
                raise ValueError(
                    f"BC type 'symmetry' for face {face} in block {bi} is retired: a symmetry plane "
                    "is a free-slip wall, so use type 'wall' with handler 'free_slip'."
                )
            if bc_type is None:
                raise ValueError(
                    f"Unsupported BC type '{bc_type_raw}' for face {face} in block {bi}. "
                    f"Supported: {sorted(set(BC_TYPE_MAP.values()))}."
                )
 
            handler = str(bc["handler"]).strip().lower()
            handler_spec = BC_HANDLER_SPECS.get(handler)
            if handler_spec is None:
                raise ValueError(
                    f"Unsupported BC handler '{bc['handler']}' for face {face} in block {bi}. "
                    f"Supported now: {sorted(BC_HANDLER_SPECS.keys())}."
                )
            if bc_type not in handler_spec["types"]:
                raise ValueError(
                    f"Invalid BC combination on block {bi}, face {face}: type '{bc_type}' cannot use handler '{handler}'."
                )
 
            params = bc.get("params", {})
            if params is None:
                params = {}
            if not isinstance(params, dict):
                raise ValueError(f"'params' for block {bi}, face {face} must be a mapping.")
 
            # Reject unsupported older structured keys explicitly.
            if "vector" in params or "velocity" in params:
                raise ValueError(
                    f"Unsupported older params key ('vector'/'velocity') found on block {bi}, face {face}. "
                    "Use scalar keys 'vx', 'vy', 'vz'."
                )
 
            required = handler_spec["required_params"]
            optional = handler_spec["optional_params"]
            allowed = required | optional
 
            missing = sorted(required - set(params.keys()))
            if missing:
                raise ValueError(
                    f"Missing required params for handler '{handler}' on block {bi}, face {face}: {missing}."
                )
            unknown = sorted(set(params.keys()) - allowed)
            if unknown:
                raise ValueError(
                    f"Unknown params for handler '{handler}' on block {bi}, face {face}: {unknown}. "
                    f"Allowed: {sorted(allowed)}."
                )
 
            converted_params = {}
            for key, value in params.items():
                if key in _NUMERIC_BC_PARAMS:
                    converted_params[key] = quantity_to_solver_units(
                        value, BC_PARAM_QUANTITIES[key], scales,
                        f"boundary_conditions[{bi}][{idx}].params.{key}")
                elif key in _BOOL_BC_PARAMS:
                    canonical = _DEPRECATED_BC_PARAM_ALIASES.get(key, key)
                    if canonical != key:
                        if canonical in params:
                            raise ValueError(
                                f"boundary_conditions[{bi}][{idx}].params sets both '{key}' and its "
                                f"replacement '{canonical}'. Use '{canonical}' only."
                            )
                        print(
                            f"[WARNING] boundary_conditions[{bi}][{idx}].params.{key} is deprecated; "
                            f"use '{canonical}'. It enables the local seam-flux correction on the "
                            "periodic boundary plane, on top of the body force that sustains the bulk "
                            "flow. See docs/pages/54_Geometric_Periodic_Boundaries.md.",
                            file=sys.stderr,
                        )
                    converted_params[canonical] = _to_bool(
                        value, f"boundary_conditions[{bi}][{idx}].params.{key}")
                elif handler == "prescribed_flow" and key == "source":
                    converted_params[key] = _normalize_prescribed_flow_source(
                        value, f"boundary_conditions[{bi}][{idx}].params.source"
                    )
                else:
                    # Defensive fallback; should not happen due unknown-key gate above.
                    converted_params[key] = value
 
            policy = str(bc.get("particle_policy", handler_spec["particle_policy"])).strip().lower()
            if policy not in PARTICLE_BOUNDARY_POLICIES:
                raise ValueError(
                    f"Unsupported particle_policy '{bc.get('particle_policy')}' for face {face} in block {bi}. "
                    f"Supported: {list(PARTICLE_BOUNDARY_POLICIES)}."
                )
            if (policy == "wrap") != (bc_type == "PERIODIC"):
                raise ValueError(
                    f"boundary_conditions[{bi}][{idx}].particle_policy '{policy}' does not fit a {bc_type} face: "
                    "PERIODIC faces wrap particles to the paired face, and only they can."
                )
            converted_params["particle_policy"] = policy
 
            prepared_block.append({
                "face": face,
                "type": bc_type,
                "handler": handler,
                "params": converted_params,
            })
 
        missing_faces = sorted(expected_faces - set(seen_faces.keys()))
        if missing_faces:
            raise ValueError(
                f"boundary_conditions[{bi}] is incomplete. Missing faces: {missing_faces}. "
                "Provide all six faces explicitly."
            )
 
        # Pairwise periodic consistency checks.
        face_map = {entry["face"]: entry for entry in prepared_block}
        for neg_face, pos_face in axis_pairs:
            neg = face_map[neg_face]
            pos = face_map[pos_face]
            neg_periodic = (neg["type"] == "PERIODIC")
            pos_periodic = (pos["type"] == "PERIODIC")
            if neg_periodic != pos_periodic:
                raise ValueError(
                    f"Inconsistent periodicity in block {bi}: {neg_face} and {pos_face} must both be PERIODIC or neither."
                )
 
            driven_handlers = {"constant_flux", "initial_flux"}
            if (neg["handler"] in driven_handlers) or (pos["handler"] in driven_handlers):
                if neg["handler"] != pos["handler"]:
                    raise ValueError(
                        f"In block {bi}, driven periodic handlers on {neg_face}/{pos_face} must match exactly."
                    )
                if not (neg_periodic and pos_periodic):
                    raise ValueError(
                        f"In block {bi}, driven periodic handler '{neg['handler']}' requires PERIODIC type on both faces."
                    )
 
        prepared_blocks.append(prepared_block)
 
    return prepared_blocks
 
 
def _schema_path_text(path: tuple) -> str:
    """!
    @brief Render an internal schema path tuple as a user-facing YAML path.
    @param[in] path Internal path tuple.
    @return Dotted YAML path.
    """
    return ".".join(part for part in path if part != "[]") or "<root>"
 
 
def _lookup_allowed_schema_keys(schema: dict, path: tuple):
    """!
    @brief Return allowed keys for a path, honoring '*' dynamic mapping entries.
    @param[in] schema Role schema mapping.
    @param[in] path Internal path tuple.
    @return Allowed key set, None for free-form mappings, or False when path is not schema-checked.
    """
    if path in schema:
        return schema[path]
    for idx, part in enumerate(path):
        if part == "[]":
            continue
        candidate = path[:idx] + ("*",) + path[idx + 1:]
        if candidate in schema:
            return schema[candidate]
    return False
 
 
def _schema_key_hint(schema: dict, path: tuple, key: str, allowed: set) -> str:
    """!
    @brief Build a concise typo or hierarchy hint for an unsupported YAML key.
    @param[in] schema Role schema mapping.
    @param[in] path Current internal YAML path tuple.
    @param[in] key Unsupported YAML key.
    @param[in] allowed Allowed keys at the current path.
    @return Optional hint string.
    """
    hints = []
    allowed_strings = sorted(str(item) for item in allowed)
    lower_matches = [item for item in allowed_strings if item.lower() == key.lower()]
    close_matches = lower_matches or difflib.get_close_matches(key, allowed_strings, n=1, cutoff=0.80)
    if close_matches:
        hints.append(f"Did you mean '{close_matches[0]}'?")
 
    valid_paths = []
    for schema_path, schema_allowed in schema.items():
        if schema_path == path or not schema_allowed:
            continue
        if key in schema_allowed:
            valid_paths.append(_schema_path_text(schema_path))
    if valid_paths:
        hints.append(f"This key is valid at: {', '.join(sorted(valid_paths))}.")
 
    return " ".join(hints)
 
 
def _validate_yaml_schema_keys(cfg, schema: dict, file_path: str, errors: list, path: tuple = ()) -> None:
    """!
    @brief Reject unsupported YAML keys before they can be silently ignored by staging.
    @param[in] cfg Parsed YAML node.
    @param[in] schema Role schema mapping.
    @param[in] file_path Source file path for diagnostics.
    @param[in,out] errors Validation error accumulator.
    @param[in] path Current internal YAML path tuple.
    """
    if isinstance(cfg, dict):
        allowed = _lookup_allowed_schema_keys(schema, path)
        if allowed is not False and allowed is not None:
            unknown = sorted(str(key) for key in cfg.keys() if key not in allowed)
            for key in unknown:
                hint = _schema_key_hint(schema, path, key, allowed)
                hint_text = f" {hint}" if hint else ""
                errors.append(
                    f"  {file_path}: unsupported key at {_schema_path_text(path)}: '{key}'. "
                    f"Allowed keys: {sorted(allowed)}.{hint_text}"
                )
        if allowed is None:
            return
        for key, value in cfg.items():
            _validate_yaml_schema_keys(value, schema, file_path, errors, path + (key,))
    elif isinstance(cfg, list) and _lookup_allowed_schema_keys(schema, path + ("[]",)) is not False:
        for item in cfg:
            _validate_yaml_schema_keys(item, schema, file_path, errors, path + ("[]",))
    elif (isinstance(cfg, (str, int, float, list)) and not isinstance(cfg, bool)
          and path and path[-1] != "[]" and _lookup_allowed_schema_keys(schema, path) is not False):
        # A section given as a string, number or list would reach code that reads it as a
        # mapping. A boolean is left alone: several sections take true/false as shorthand
        # (models.physics.turbulence.les, io.paraview_series). So are list items, some of
        # which accept a scalar shorthand (a study metric name).
        errors.append(
            f"  {file_path}: '{_schema_path_text(path)}' must be a mapping, not "
            f"{type(cfg).__name__} {cfg!r}."
        )
    elif isinstance(cfg, list):
        for item in cfg:
            _validate_yaml_schema_keys(item, schema, file_path, errors, path + ("[]",))
 
 
_CASE_SCHEMA = {
    (): {
        "title", "properties", "run_control", "grid", "models", "boundary_conditions", "solver_parameters",
    },
    ("run_control",): {"start_step", "total_steps", "dt_physical"},
    ("properties",): {"scaling", "fluid", "initial_conditions"},
    ("properties", "scaling"): {"length_ref", "velocity_ref"},
    ("properties", "fluid"): {"density", "viscosity", "schmidt_number"},
    ("properties", "initial_conditions"): {
        "mode", "generator", "params", "field", "source_file",
        "source_case", "velocity_scale", "length_scale",
        "u_physical", "v_physical", "w_physical", "peak_velocity_physical",
        "velocity_physical", "flow_direction",
    },
    ("properties", "initial_conditions", "params"): None,
    ("grid",): {
        "mode", "source_file", "programmatic_settings", "generator",
        "da_processors_x", "da_processors_y", "da_processors_z",
    },
    ("grid", "programmatic_settings"): {
        "im", "jm", "km", "xMins", "xMaxs", "yMins", "yMaxs", "zMins", "zMaxs",
        "rxs", "rys", "rzs", "cgrids",
        "da_processors_x", "da_processors_y", "da_processors_z",
    },
    ("grid", "generator"): {
        "script", "config_file", "grid_type", "cli_args", "output_file", "stats_file", "vts_file",
        # Retained so existing warning behavior for typo-prone hyphen keys is not bypassed.
        "config-file", "grid-type", "output-file", "stats-file", "vts-file",
    },
    ("models",): {"domain", "physics"},
    ("models", "domain"): {"blocks"},
    ("models", "physics"): {"dimensionality", "fsi", "particles", "turbulence"},
    ("models", "physics", "fsi"): {"immersed", "moving_fsi"},
    ("models", "physics", "particles"): {"count", "init_mode", "restart_mode", "point_source", "random_seed",
                                         "fields", "iem_constant"},
    ("models", "physics", "particles", "fields"): None,
    ("models", "physics", "particles", "point_source"): {"x", "y", "z"},
    # 'rans' stays listed so a case carrying it gets the planned-status refusal rather
    # than a generic unknown-key error; nothing translates it.
    ("models", "physics", "turbulence"): {"les", "rans", "wall_function", "turbulent_schmidt_number"},
    ("models", "physics", "turbulence", "les"): {
        "enabled", "model", "constant_cs", "vreman_coefficient", "wale_coefficient",
        "dynamic_frequency", "filter_width",
        "test_filter", "averaging", "clipping", "gradient_model", "diagnostics",
    },
    ("models", "physics", "turbulence", "les", "test_filter"): {"kernel", "width_ratio"},
    ("models", "physics", "turbulence", "les", "averaging"): {"mode", "directions"},
    ("models", "physics", "turbulence", "les", "clipping"): {
        "mode", "max_cs", "min_viscosity_ratio",
    },
    ("models", "physics", "turbulence", "les", "gradient_model"): {"enabled"},
    ("models", "physics", "turbulence", "les", "diagnostics"): {
        "enabled", "cadence", "yoshizawa_ci",
    },
    ("models", "physics", "turbulence", "rans"): {"enabled", "model"},
    ("models", "physics", "turbulence", "wall_function"): {"enabled", "model", "roughness_height"},
    ("boundary_conditions", "[]"): {"face", "type", "handler", "params", "particle_policy"},
    ("boundary_conditions", "[]", "[]"): {"face", "type", "handler", "params", "particle_policy"},
    ("boundary_conditions", "[]", "params"): None,
    ("boundary_conditions", "[]", "[]", "params"): None,
    ("solver_parameters",): None,
}
 
 
_SOLVER_SCHEMA = {
    (): {
        "operation_mode", "strategy", "tolerances", "momentum_solver", "poisson_solver",
        "pressure_solver", "interpolation", "petsc_passthrough_options", "verification",
        "scalar_transport",
    },
    ("operation_mode",): {"eulerian_field_source", "analytical_type", "uniform_flow"},
    ("operation_mode", "uniform_flow"): {"u", "v", "w"},
    ("strategy",): {"momentum_solver", "central_diff"},
    ("tolerances",): {
        "max_iterations", "absolute_tol", "relative_tol", "step_tol",
        "residual_absolute_tol", "residual_relative_tol",
    },
    ("momentum_solver",): {
        "type", "dual_time_picard_jameson_rk", "dual_time_picard_rk4", "newton_krylov",
    },
    ("momentum_solver", "dual_time_picard_jameson_rk"): {
        "max_pseudo_steps", "absolute_tol", "relative_tol", "step_tol", "pseudo_cfl",
        "jameson_residual_noise_allowance_factor", "rk4_residual_noise_allowance_factor",
        "ratio_ema_alpha",
    },
    ("momentum_solver", "dual_time_picard_jameson_rk", "pseudo_cfl"): {
        "initial", "minimum", "maximum", "growth_factor", "reduction_factor",
    },
    ("momentum_solver", "dual_time_picard_rk4"): {
        "max_pseudo_steps", "absolute_tol", "relative_tol", "step_tol", "pseudo_cfl",
        "jameson_residual_noise_allowance_factor", "rk4_residual_noise_allowance_factor",
        "ratio_ema_alpha",
    },
    ("momentum_solver", "dual_time_picard_rk4", "pseudo_cfl"): {
        "initial", "minimum", "maximum", "growth_factor", "reduction_factor",
    },
    ("momentum_solver", "newton_krylov"): {
        "jacobian", "preconditioner", "nonlinear_solver", "linear_solver",
    },
    ("momentum_solver", "newton_krylov", "jacobian"): {"type", "finite_difference"},
    ("momentum_solver", "newton_krylov", "jacobian", "finite_difference"): {"mode"},
    ("momentum_solver", "newton_krylov", "preconditioner"): {"model", "structure"},
    ("momentum_solver", "newton_krylov", "preconditioner", "structure"): {"type"},
    ("momentum_solver", "newton_krylov", "nonlinear_solver"): {
        "method", "absolute_tolerance", "relative_tolerance", "step_tolerance",
        "max_iterations", "line_search", "eisenstat_walker",
    },
    ("momentum_solver", "newton_krylov", "nonlinear_solver", "line_search"): {"type"},
    ("momentum_solver", "newton_krylov", "nonlinear_solver", "eisenstat_walker"): {
        "enabled", "version", "initial_relative_tolerance", "maximum_relative_tolerance",
        "gamma", "exponent", "safeguard_exponent", "safeguard_threshold",
    },
    ("momentum_solver", "newton_krylov", "linear_solver"): {
        "method", "absolute_tolerance", "relative_tolerance", "max_iterations",
        "gmres", "preconditioner",
    },
    ("momentum_solver", "newton_krylov", "linear_solver", "gmres"): {"restart"},
    ("momentum_solver", "newton_krylov", "linear_solver", "preconditioner"): {"type"},
    ("poisson_solver",): {
        "method", "absolute_tolerance", "relative_tolerance", "max_iterations", "tolerance",
        "gmres", "preconditioner", "multigrid",
    },
    ("pressure_solver",): {
        "method", "absolute_tolerance", "relative_tolerance", "max_iterations", "tolerance",
        "gmres", "preconditioner", "multigrid",
    },
    ("poisson_solver", "gmres"): {"restart"},
    ("pressure_solver", "gmres"): {"restart"},
    ("poisson_solver", "preconditioner"): {"type"},
    ("pressure_solver", "preconditioner"): {"type"},
    ("poisson_solver", "multigrid"): {
        "levels", "pre_sweeps", "post_sweeps", "cycle", "mode", "semi_coarsening", "level_solvers",
    },
    ("pressure_solver", "multigrid"): {
        "levels", "pre_sweeps", "post_sweeps", "cycle", "mode", "semi_coarsening", "level_solvers",
    },
    ("poisson_solver", "multigrid", "semi_coarsening"): {"i", "j", "k"},
    ("pressure_solver", "multigrid", "semi_coarsening"): {"i", "j", "k"},
    ("poisson_solver", "multigrid", "level_solvers", "*"): {
        "method", "preconditioner", "ksp_type", "pc_type", "max_it", "rtol", "atol",
    },
    ("pressure_solver", "multigrid", "level_solvers", "*"): {
        "method", "preconditioner", "ksp_type", "pc_type", "max_it", "rtol", "atol",
    },
    ("interpolation",): {"method"},
    ("petsc_passthrough_options",): None,
    ("verification",): {"sources"},
    ("verification", "sources"): {"diffusivity", "scalar"},
    ("verification", "sources", "diffusivity"): {"mode", "profile", "gamma0", "slope_x"},
    ("verification", "sources", "scalar"): {
        "mode", "profile", "value", "phi0", "slope_x", "amplitude", "kx", "ky", "kz",
    },
    ("scalar_transport",): set(SCALAR_TRANSPORT_FLAGS),
}
 
 
_MONITOR_SCHEMA = {
    (): {
        "logging", "profiling", "diagnostics", "io", "solver_monitoring", "solution_monitoring",
        "field_statistics",
    },
    ("logging",): {"verbosity", "enabled_functions", "trace_particles"},
    ("profiling",): {"timestep_output", "final_summary", "helpers"},
    ("profiling", "timestep_output"): {"mode", "functions"},
    ("profiling", "final_summary"): {"enabled"},
    ("diagnostics",): {"petsc", "runtime_memory_log", "les"},
    ("diagnostics", "les"): {"enabled", "cadence", "yoshizawa_ci"},
    ("diagnostics", "petsc"): {
        "info", "malloc_debug", "malloc_test", "malloc_dump", "malloc_view", "malloc_view_threshold",
        "memory_view", "log_view", "log_view_memory", "log_all", "log_trace",
        "objects_dump", "options_left",
    },
    ("diagnostics", "petsc", "info"): {"enabled", "classes"},
    ("diagnostics", "runtime_memory_log"): {"enabled"},
    ("io",): {
        "data_output_frequency", "particle_console_output_frequency", "particle_log_interval",
        "statistics_console_output_frequency", "write_initial_checkpoint", "write_final_checkpoint",
    },
    ("solver_monitoring",): {"momentum", "poisson", "petsc_passthrough_options"},
    ("solver_monitoring", "momentum"): {
        "newton_krylov_history", "snes_monitor", "snes_converged_reason",
        "ksp_monitor", "ksp_converged_reason",
    },
    ("solver_monitoring", "poisson"): {"pic_true_residual", "true_residual", "converged_reason", "view"},
    ("solver_monitoring", "petsc_passthrough_options"): None,
    ("solution_monitoring",): {"convergence"},
    ("solution_monitoring", "convergence"): {
        "enabled", "mode", "periodic_deterministic", "statistical_steady",
    },
    ("solution_monitoring", "convergence", "periodic_deterministic"): {"period_steps"},
    ("solution_monitoring", "convergence", "statistical_steady"): {"window_steps"},
    ("field_statistics",): {"enabled", "windows"},
    ("field_statistics", "windows", "[]"): {
        "name", "start_time", "end_time", "weighting",
        "step_cadence", "time_cadence", "fields", "covariances",
    },
    ("field_statistics", "windows", "[]", "fields", "[]"): {"field", "moments"},
}
 
 
#: Eulerian fields a statistics window may accumulate, with the subsystem each needs.
#:
#: This is a curated subset of the typed catalog rather than a mirror of it. Averaging
#: a grid metric is meaningless, and a face-staggered field has no single pointwise
#: location, so offering the whole catalog would only move the rejection later and
#: make it harder to read. `tests/test_cli_smoke.py` asserts every entry here still
#: exists in `src/field_catalog.c` with the layout recorded, so the two cannot drift.
STATISTICS_ELIGIBLE_FIELDS = {
    "Ucat": {"components": 3, "requires": None},
    "P": {"components": 1, "requires": None},
    "Nvert": {"components": 1, "requires": None},
    "Phi": {"components": 1, "requires": None},
    "Psi": {"components": 1, "requires": "particles"},
    "ParticleCount": {"components": 1, "requires": "particles"},
    "Nu_t": {"components": 1, "requires": "turbulence"},
    "CS": {"components": 1, "requires": "les"},
}
 
#: Particle fields a recipe ensemble may sample. Each is accumulated onto the Eulerian
#: field its particle-catalog entry scatters to, which also names its derived outputs.
STATISTICS_PARTICLE_FIELDS = {
    "Psi": {"components": 1, "requires": "particles", "target": "Psi"},
    "velocity": {"components": 3, "requires": "particles", "target": "Ucat"},
}
 
#: Sources a recipe ensemble may draw its samples from: the particles in each cell, or
#: each cell's own state.
POST_STATISTICS_ENSEMBLE_SOURCES = ("particles", "eulerian")
 
 
def _ensemble_source_fields(source: str) -> dict:
    """!
    @brief Return the field table an ensemble of one source names its fields from.
    @param[in] source One of `POST_STATISTICS_ENSEMBLE_SOURCES`.
    @return The particle or the Eulerian statistics field table.
    """
    return STATISTICS_PARTICLE_FIELDS if source == "particles" else STATISTICS_ELIGIBLE_FIELDS
 
 
#: Moment names one field may request. Higher moments cannot be recovered from
#: centered state after the fact, so they need their own accumulation rather than
#: an extension of this list.
STATISTICS_MOMENT_NAMES = ("first", "second")
 
#: Weighting modes a window may select.
STATISTICS_WEIGHTING_MODES = ("sample", "physical_time")
 
 
_POST_SCHEMA = {
    (): {
        "run_control", "source_data", "global_operations", "eulerian_pipeline",
        "lagrangian_pipeline", "statistics_pipeline", "statistics_output_prefix",
        "field_statistics", "spectra", "reducers", "io",
    },
    ("field_statistics",): {"windows", "ensembles", "homogeneous", "source_step", "outputs", "formats"},
    ("field_statistics", "ensembles", "[]"): {"name", "source", "fields", "covariances"},
    ("field_statistics", "ensembles", "[]", "fields", "[]"): {"field", "moments"},
    ("spectra",): {"output_prefix", "tasks"},
    ("reducers",): {"tasks"},
    ("reducers", "tasks", "[]"): {
        "task", "source", "wall_axis", "stream_axis", "friction_velocity", "value", "fold", "half_height",
    },
    ("spectra", "tasks", "[]"): {
        "task", "field", "block", "symbol", "subtract_mean", "mean_source_step",
        "reference", "axes", "fixed_indices",
    },
    ("run_control",): {
        "start_step", "end_step", "step_interval", "startTime", "endTime", "timeStep",
    },
    ("source_data",): {"directory", "input_extensions"},
    ("source_data", "input_extensions"): {"eulerian", "particle"},
    ("global_operations",): {"dimensionalize"},
    ("eulerian_pipeline", "[]"): {"task", "input_field", "output_field", "field", "reference_point"},
    ("lagrangian_pipeline", "[]"): {"task", "input_field", "output_field"},
    ("statistics_pipeline",): {"output_prefix", "tasks"},
    ("statistics_pipeline", "tasks", "[]"): {"task"},
    ("io",): {
        "output_directory", "output_filename_prefix", "particle_filename_prefix", "output_particles",
        "particle_subsampling_frequency", "input_extensions",
        "eulerian_fields", "particle_fields", "paraview_series",
    },
    ("io", "input_extensions"): {"eulerian", "particle"},
    ("io", "paraview_series"): {"enabled", "scope"},
}
 
 
_CLUSTER_SCHEMA = {
    (): {"scheduler", "resources", "notifications", "execution"},
    ("scheduler",): {"type"},
    ("resources",): {"account", "partition", "nodes", "ntasks_per_node", "mem", "time"},
    ("notifications",): {"mail_user", "mail_type"},
    ("execution",): {
        "module_setup", "launcher", "launcher_args", "extra_sbatch", "walltime_guard", "decomposition",
    },
    ("execution", "decomposition"): {"i", "j", "k"},
    ("execution", "extra_sbatch"): None,
    ("execution", "walltime_guard"): {
        "enabled", "warmup_steps", "multiplier", "min_seconds", "estimator_alpha",
    },
}
 
 
_STUDY_SCHEMA = {
    (): {
        "title", "base_configs", "study_type", "parameters", "parameter_sets", "metrics", "plotting", "execution",
    },
    ("base_configs",): {"case", "solver", "monitor", "post"},
    ("parameters",): None,
    ("parameter_sets", "[]"): None,
    ("metrics", "[]"): {
        "name", "source", "file_glob", "column", "regex", "reduction", "normalize_by_parameter",
        "numerator_column", "denominator_column", "denominator_floor",
        "plot_label", "label", "units",
    },
    ("plotting",): {"enabled", "output_format"},
    ("execution",): {"max_concurrent_array_tasks"},
}
 
 
_WORKSPACE_SCHEMA = {
    (): {"schema_version", "workspace", "software", "paths", "reproducibility"},
    ("workspace",): {"id", "template", "created_at"},
    ("software",): {"picurv"},
    ("paths",): {"config", "inputs", "assets", "runs", "studies"},
    ("reproducibility",): {"require_clean_release", "pin_executables"},
}
 
 
# Directories the run owns and writes into. `log` is the safety-critical one: the C
# runtime calls PetscRMTree on it at the start of a fresh solve, so a value that
# escapes the run directory means the solver recursively deletes whatever is there.
#: Physical dimensions, as exponents of the reference length, velocity, and density.
#:
#: Every input a user writes is physical, and it becomes a solver value by one division,
#: by `length_ref**a * velocity_ref**b * density**c` for dimension `(a, b, c)`. The C
#: field catalogs carry the same triple for the reverse conversion in post-processing,
#: so the two directions use one vocabulary. See docs/pages/19_Nondimensionalization.md.
DIMENSIONLESS = (0, 0, 0)
LENGTH = (1, 0, 0)
VELOCITY = (0, 1, 0)
TIME = (1, -1, 0)
WAVENUMBER = (-1, 0, 0)
VOLUME_FLUX = (2, 1, 0)
DIFFUSIVITY = (1, 1, 0)
PRESSURE = (0, 2, 1)
DENSITY = (0, 0, 1)
DYNAMIC_VISCOSITY = (1, 1, 1)
 
#: Where an input's conversion to solver units happens. `cli` converts the value while
#: writing the control file; `c` converts it in the runtime (programmatic grid bounds,
#: which have no staging step); `staging` scales a file payload as it is staged; `provider`
#: means a generator receives the reference scales and emits solver units; `reference`
#: marks the inputs that define the scales themselves; `passthrough` marks raw solver
#: flags, which are expert input in solver units by definition; `evaluator` means the
#: runtime evaluates an expression at physical coordinates and divides its value by the
#: target field's reference scale. An empty string means there is nothing to convert.
INPUT_CONVERSION_SITES = ("cli", "c", "staging", "provider", "evaluator", "reference", "passthrough", "")
 
NOT_A_QUANTITY = (None, "")
UNITLESS = (DIMENSIONLESS, "")
 
#: The physical dimension of every configuration input, and where it is converted.
#:
#: Keys are the configuration role followed by the same path tuples the key schemas use.
#: An entry for an interior path covers every leaf beneath it; that form is reserved for
#: subtrees that are inherently free of physical quantities (numerical controls, logging,
#: selectors). `tests/test_units_and_scaling.py` requires every schema leaf, every BC
#: handler parameter, and every initial-condition generator parameter to be covered, so a
#: new key cannot be added without deciding what it measures.
INPUT_QUANTITIES = {
    # ----- case.yml -----
    ("case", "title"): NOT_A_QUANTITY,
    ("case", "run_control", "start_step"): NOT_A_QUANTITY,
    ("case", "run_control", "total_steps"): NOT_A_QUANTITY,
    ("case", "run_control", "dt_physical"): (TIME, "cli"),
    ("case", "properties", "scaling", "length_ref"): (LENGTH, "reference"),
    ("case", "properties", "scaling", "velocity_ref"): (VELOCITY, "reference"),
    ("case", "properties", "fluid", "density"): (DENSITY, "reference"),
    ("case", "properties", "fluid", "viscosity"): (DYNAMIC_VISCOSITY, "reference"),
    ("case", "properties", "fluid", "schmidt_number"): UNITLESS,
    ("case", "properties", "initial_conditions", "mode"): NOT_A_QUANTITY,
    ("case", "properties", "initial_conditions", "generator"): NOT_A_QUANTITY,
    ("case", "properties", "initial_conditions", "field"): NOT_A_QUANTITY,
    ("case", "properties", "initial_conditions", "flow_direction"): NOT_A_QUANTITY,
    # The payload's dimension follows its field: velocity for Ucat, volume flux for Ucont.
    ("case", "properties", "initial_conditions", "source_file"): (None, "staging"),
    ("case", "properties", "initial_conditions", "source_case"): NOT_A_QUANTITY,
    ("case", "properties", "initial_conditions", "velocity_scale"): (VELOCITY, "reference"),
    ("case", "properties", "initial_conditions", "length_scale"): (LENGTH, "reference"),
    ("case", "properties", "initial_conditions", "u_physical"): (VELOCITY, "cli"),
    ("case", "properties", "initial_conditions", "v_physical"): (VELOCITY, "cli"),
    ("case", "properties", "initial_conditions", "w_physical"): (VELOCITY, "cli"),
    ("case", "properties", "initial_conditions", "velocity_physical"): (VELOCITY, "cli"),
    ("case", "properties", "initial_conditions", "peak_velocity_physical"): (VELOCITY, "cli"),
    ("case", "grid", "mode"): NOT_A_QUANTITY,
    ("case", "grid", "source_file"): (LENGTH, "staging"),
    ("case", "grid", "da_processors_x"): NOT_A_QUANTITY,
    ("case", "grid", "da_processors_y"): NOT_A_QUANTITY,
    ("case", "grid", "da_processors_z"): NOT_A_QUANTITY,
    ("case", "grid", "programmatic_settings", "im"): NOT_A_QUANTITY,
    ("case", "grid", "programmatic_settings", "jm"): NOT_A_QUANTITY,
    ("case", "grid", "programmatic_settings", "km"): NOT_A_QUANTITY,
    ("case", "grid", "programmatic_settings", "cgrids"): NOT_A_QUANTITY,
    ("case", "grid", "programmatic_settings", "da_processors_x"): NOT_A_QUANTITY,
    ("case", "grid", "programmatic_settings", "da_processors_y"): NOT_A_QUANTITY,
    ("case", "grid", "programmatic_settings", "da_processors_z"): NOT_A_QUANTITY,
    ("case", "grid", "programmatic_settings", "rxs"): UNITLESS,
    ("case", "grid", "programmatic_settings", "rys"): UNITLESS,
    ("case", "grid", "programmatic_settings", "rzs"): UNITLESS,
    ("case", "grid", "programmatic_settings", "xMins"): (LENGTH, "c"),
    ("case", "grid", "programmatic_settings", "xMaxs"): (LENGTH, "c"),
    ("case", "grid", "programmatic_settings", "yMins"): (LENGTH, "c"),
    ("case", "grid", "programmatic_settings", "yMaxs"): (LENGTH, "c"),
    ("case", "grid", "programmatic_settings", "zMins"): (LENGTH, "c"),
    ("case", "grid", "programmatic_settings", "zMaxs"): (LENGTH, "c"),
    # grid.gen writes a physical PICGRID, which is staged like a file grid.
    ("case", "grid", "generator"): (LENGTH, "staging"),
    ("case", "models", "domain", "blocks"): NOT_A_QUANTITY,
    ("case", "models", "physics", "dimensionality"): NOT_A_QUANTITY,
    ("case", "models", "physics", "fsi"): NOT_A_QUANTITY,
    ("case", "models", "physics", "particles", "count"): NOT_A_QUANTITY,
    ("case", "models", "physics", "particles", "init_mode"): NOT_A_QUANTITY,
    ("case", "models", "physics", "particles", "restart_mode"): NOT_A_QUANTITY,
    ("case", "models", "physics", "particles", "random_seed"): NOT_A_QUANTITY,
    ("case", "models", "physics", "particles", "iem_constant"): UNITLESS,
    ("case", "models", "physics", "particles", "point_source", "x"): (LENGTH, "cli"),
    ("case", "models", "physics", "particles", "point_source", "y"): (LENGTH, "cli"),
    ("case", "models", "physics", "particles", "point_source", "z"): (LENGTH, "cli"),
    # Expressions at physical coordinates; each value is in its field's physical units.
    ("case", "models", "physics", "particles", "fields"): (None, "evaluator"),
    # Model constants, ratios, cadences, and selectors: nothing here carries a unit.
    ("case", "models", "physics", "turbulence", "les"): UNITLESS,
    ("case", "models", "physics", "turbulence", "rans"): NOT_A_QUANTITY,
    ("case", "models", "physics", "turbulence", "turbulent_schmidt_number"): UNITLESS,
    ("case", "models", "physics", "turbulence", "wall_function", "enabled"): NOT_A_QUANTITY,
    ("case", "models", "physics", "turbulence", "wall_function", "model"): NOT_A_QUANTITY,
    ("case", "models", "physics", "turbulence", "wall_function", "roughness_height"): (LENGTH, "cli"),
    ("case", "boundary_conditions", "[]", "face"): NOT_A_QUANTITY,
    ("case", "boundary_conditions", "[]", "type"): NOT_A_QUANTITY,
    ("case", "boundary_conditions", "[]", "handler"): NOT_A_QUANTITY,
    ("case", "boundary_conditions", "[]", "particle_policy"): NOT_A_QUANTITY,
    ("case", "boundary_conditions", "[]", "[]", "face"): NOT_A_QUANTITY,
    ("case", "boundary_conditions", "[]", "[]", "type"): NOT_A_QUANTITY,
    ("case", "boundary_conditions", "[]", "[]", "handler"): NOT_A_QUANTITY,
    ("case", "boundary_conditions", "[]", "[]", "particle_policy"): NOT_A_QUANTITY,
    ("case", "solver_parameters"): (None, "passthrough"),
    # ----- solver.yml -----
    ("solver", "operation_mode", "eulerian_field_source"): NOT_A_QUANTITY,
    ("solver", "operation_mode", "analytical_type"): NOT_A_QUANTITY,
    ("solver", "operation_mode", "uniform_flow", "u"): (VELOCITY, "cli"),
    ("solver", "operation_mode", "uniform_flow", "v"): (VELOCITY, "cli"),
    ("solver", "operation_mode", "uniform_flow", "w"): (VELOCITY, "cli"),
    # Iteration controls act on residuals the solver forms in its own units.
    ("solver", "strategy"): NOT_A_QUANTITY,
    ("solver", "tolerances"): UNITLESS,
    ("solver", "momentum_solver"): UNITLESS,
    ("solver", "poisson_solver"): UNITLESS,
    ("solver", "pressure_solver"): UNITLESS,
    ("solver", "interpolation"): NOT_A_QUANTITY,
    ("solver", "petsc_passthrough_options"): (None, "passthrough"),
    ("solver", "verification", "sources", "diffusivity", "mode"): NOT_A_QUANTITY,
    ("solver", "verification", "sources", "diffusivity", "profile"): NOT_A_QUANTITY,
    ("solver", "verification", "sources", "diffusivity", "gamma0"): (DIFFUSIVITY, "cli"),
    # Gamma = gamma0 + slope_x * x, so the slope is a diffusivity per length.
    ("solver", "verification", "sources", "diffusivity", "slope_x"): (VELOCITY, "cli"),
    ("solver", "verification", "sources", "scalar", "mode"): NOT_A_QUANTITY,
    ("solver", "verification", "sources", "scalar", "profile"): NOT_A_QUANTITY,
    ("solver", "verification", "sources", "scalar", "value"): UNITLESS,
    ("solver", "verification", "sources", "scalar", "phi0"): UNITLESS,
    ("solver", "verification", "sources", "scalar", "amplitude"): UNITLESS,
    ("solver", "verification", "sources", "scalar", "slope_x"): (WAVENUMBER, "cli"),
    ("solver", "verification", "sources", "scalar", "kx"): (WAVENUMBER, "cli"),
    ("solver", "verification", "sources", "scalar", "ky"): (WAVENUMBER, "cli"),
    ("solver", "verification", "sources", "scalar", "kz"): (WAVENUMBER, "cli"),
    ("solver", "scalar_transport"): UNITLESS,
    # ----- monitor.yml -----
    ("monitor", "logging"): NOT_A_QUANTITY,
    ("monitor", "profiling"): NOT_A_QUANTITY,
    ("monitor", "diagnostics"): NOT_A_QUANTITY,
    ("monitor", "io"): NOT_A_QUANTITY,
    ("monitor", "solver_monitoring"): NOT_A_QUANTITY,
    ("monitor", "solution_monitoring"): NOT_A_QUANTITY,
    ("monitor", "field_statistics", "enabled"): NOT_A_QUANTITY,
    ("monitor", "field_statistics", "windows", "[]", "name"): NOT_A_QUANTITY,
    ("monitor", "field_statistics", "windows", "[]", "weighting"): NOT_A_QUANTITY,
    ("monitor", "field_statistics", "windows", "[]", "step_cadence"): NOT_A_QUANTITY,
    ("monitor", "field_statistics", "windows", "[]", "start_time"): (TIME, "cli"),
    ("monitor", "field_statistics", "windows", "[]", "end_time"): (TIME, "cli"),
    ("monitor", "field_statistics", "windows", "[]", "time_cadence"): (TIME, "cli"),
    ("monitor", "field_statistics", "windows", "[]", "fields"): NOT_A_QUANTITY,
    ("monitor", "field_statistics", "windows", "[]", "covariances"): NOT_A_QUANTITY,
    # ----- post.yml: steps, indices, selectors, and names only -----
    ("post",): NOT_A_QUANTITY,
}
 
#: Boundary-condition handler parameters (the free-form `params` mapping of a face).
BC_PARAM_QUANTITIES = {
    "vx": (VELOCITY, "cli"),
    "vy": (VELOCITY, "cli"),
    "vz": (VELOCITY, "cli"),
    "v_max": (VELOCITY, "cli"),
    "target_flux": (VOLUME_FLUX, "cli"),
    "enforce_seam_flux": NOT_A_QUANTITY,
    "apply_trim": NOT_A_QUANTITY,
    # Every profile source stages a velocity PICSLICE: a file or generated profile is
    # physical, and a field_slice declares the scales it was written in.
    "source": (VELOCITY, "staging"),
}
 
#: Initial-condition generator parameters (`properties.initial_conditions.params`), by
#: generator. Nested mappings use dotted names.
IC_PARAM_QUANTITIES = {
    "zero": {},
    "constant": {
        "u_physical": (VELOCITY, "cli"), "v_physical": (VELOCITY, "cli"),
        "w_physical": (VELOCITY, "cli"), "velocity_physical": (VELOCITY, "cli"),
        "flow_direction": NOT_A_QUANTITY,
    },
    "streamwise_constant": {
        "velocity_physical": (VELOCITY, "cli"), "flow_direction": NOT_A_QUANTITY,
    },
    "poiseuille": {
        "peak_velocity_physical": (VELOCITY, "cli"), "flow_direction": NOT_A_QUANTITY,
    },
    "ic_gen": {
        "field": NOT_A_QUANTITY, "script": NOT_A_QUANTITY, "cli_args": NOT_A_QUANTITY,
        # Expressions are written in physical coordinates and physical values.
        "config_file": (None, "provider"),
    },
    "spectral_random_velocity": {
        "field": NOT_A_QUANTITY, "seed": NOT_A_QUANTITY, "remove_mean": NOT_A_QUANTITY,
        "random.distribution": NOT_A_QUANTITY, "random.mean": (VELOCITY, "cli"),
        "spectrum.type": NOT_A_QUANTITY,
        "spectrum.k0": (WAVENUMBER, "cli"), "spectrum.k_cut": (WAVENUMBER, "cli"),
        "projection.type": NOT_A_QUANTITY, "projection.operator": NOT_A_QUANTITY,
        "normalization.type": NOT_A_QUANTITY, "normalization.target": (VELOCITY, "cli"),
    },
}
IC_PARAM_QUANTITIES["resampled_velocity"] = {
    "field": NOT_A_QUANTITY, "format": NOT_A_QUANTITY, "cells": NOT_A_QUANTITY,
    "sample_offset": NOT_A_QUANTITY, "projection": NOT_A_QUANTITY, "remove_mean": NOT_A_QUANTITY,
    # The source file holds physical velocities; the provider divides them by velocity_ref.
    "source_file": (VELOCITY, "provider"),
    "box_length": (LENGTH, "cli"),
    "layout.fastest_axis": NOT_A_QUANTITY, "layout.components": NOT_A_QUANTITY,
    "layout.dtype": NOT_A_QUANTITY, "layout.byte_order": NOT_A_QUANTITY,
    "layout.header_bytes": NOT_A_QUANTITY, "layout.datasets": NOT_A_QUANTITY,
    "filter.type": NOT_A_QUANTITY, "filter.cutoff": (WAVENUMBER, "cli"), "filter.width": (LENGTH, "cli"),
}
IC_PARAM_QUANTITIES["channel_spectral_velocity"] = IC_PARAM_QUANTITIES["duct_spectral_velocity"] = {
    "field": NOT_A_QUANTITY, "seed": NOT_A_QUANTITY, "streamwise_axis": NOT_A_QUANTITY,
    "wall_axes": NOT_A_QUANTITY, "wall_modes": NOT_A_QUANTITY, "initial_spectra": NOT_A_QUANTITY,
    "bulk_velocity": (VELOCITY, "cli"), "perturbation_rms": (VELOCITY, "cli"),
    "spectrum.type": NOT_A_QUANTITY,
    "spectrum.k0": (WAVENUMBER, "cli"), "spectrum.k_cut": (WAVENUMBER, "cli"),
}
IC_PARAM_QUANTITIES["stability_mode_velocity"] = {
    "field": NOT_A_QUANTITY, "streamwise_axis": NOT_A_QUANTITY, "cross_axis": NOT_A_QUANTITY,
    "equation": NOT_A_QUANTITY, "eigen_points": NOT_A_QUANTITY, "initial_spectra": NOT_A_QUANTITY,
    # The expression is physical in both coordinate and value; the provider scales both.
    "base_profile": (VELOCITY, "provider"),
    "velocity_difference": (VELOCITY, "cli"),
    # Mode and noise amplitudes are fractions of the velocity difference; phases are radians.
    "modes": NOT_A_QUANTITY,
    "noise.rms": NOT_A_QUANTITY, "noise.seed": NOT_A_QUANTITY, "noise.wall_modes": NOT_A_QUANTITY,
    "noise.planar": NOT_A_QUANTITY, "noise.spectrum.type": NOT_A_QUANTITY,
    "noise.spectrum.k0": (WAVENUMBER, "cli"), "noise.spectrum.k_cut": (WAVENUMBER, "cli"),
}
 
 
def input_quantity(path: tuple) -> tuple:
    """!
    @brief Return the `(dimension, conversion site)` recorded for one configuration input.
    @param[in] path Role followed by the schema path, e.g. `("case", "run_control", "dt_physical")`.
    @return The entry for the path, or for its nearest covering ancestor.
    @throws KeyError when no entry covers the path.
    """
    for length in range(len(path), 0, -1):
        entry = INPUT_QUANTITIES.get(tuple(path[:length]))
        if entry is not None:
            return entry
    raise KeyError(f"No physical dimension is recorded for input {'.'.join(map(str, path))}.")
 
 
def reference_scale(dimension: tuple, scales: dict) -> float:
    """!
    @brief Return the factor that turns a physical quantity of this dimension into solver units.
    @param[in] dimension `(length, velocity, density)` exponents.
    @param[in] scales Mapping with `length_ref` and `velocity_ref`, and `density` when used.
    @return `length_ref**a * velocity_ref**b * density**c`.
    """
    length, velocity, density = dimension
    factor = float(scales["length_ref"]) ** length * float(scales["velocity_ref"]) ** velocity
    if density:
        factor *= float(scales["density"]) ** density
    return factor
 
 
def input_reference_scale(path: tuple, scales: dict) -> float:
    """!
    @brief Return the reference scale of one recorded input, for converting a whole payload.
    @details File payloads (grids, inlet profiles) are converted element by element by
             their own readers; this gives them the one factor their recorded dimension
             implies, so they do not restate the dimension.
    @param[in] path Role and schema path of the input.
    @param[in] scales Reference scales, as returned by `resolve_reference_scales()`.
    @return The reference scale of the input's recorded dimension.
    """
    dimension, _site = input_quantity(path)
    if dimension is None:
        raise ValueError(f"Input {'.'.join(map(str, path[1:]))} has no fixed dimension.")
    return reference_scale(dimension, scales)
 
 
def quantity_to_solver_units(value, quantity: tuple, scales: dict, label: str):
    """!
    @brief Convert a physical value, or a list of them, by one recorded quantity entry.
    @param[in] value Physical value as written by the user.
    @param[in] quantity `(dimension, conversion site)` entry from a dimension table.
    @param[in] scales Reference scales, as returned by `resolve_reference_scales()`.
    @param[in] label Configuration path, for diagnostics.
    @return The value divided by its dimension's reference scale.
    @throws ValueError when the entry records no fixed dimension.
    """
    dimension, _site = quantity
    if dimension is None:
        raise ValueError(f"Input {label} has no fixed dimension to convert.")
    factor = reference_scale(dimension, scales)
    if isinstance(value, (list, tuple)):
        return [_to_finite_float(item, label) / factor for item in value]
    return _to_finite_float(value, label) / factor
 
 
def to_solver_units(value, path: tuple, scales: dict):
    """!
    @brief Convert one physical configuration value, or a list of them, to solver units.
    @param[in] value Physical value as written by the user.
    @param[in] path Role and schema path whose recorded dimension governs the conversion.
    @param[in] scales Reference scales, as returned by `resolve_reference_scales()`.
    @return The value divided by its dimension's reference scale.
    @throws ValueError when the path records no fixed dimension.
    """
    return quantity_to_solver_units(value, input_quantity(path), scales,
                                    ".".join(str(part) for part in path[1:]))
 
 
def resolve_reference_scales(case_cfg: dict) -> dict:
    """!
    @brief Resolve the reference length and velocity (and density, when given) of a case.
    @details This is the part of the scaling contract every conversion needs. It does not
             require the fluid block, so boundary-condition preparation can use it before
             the full fluid contract is validated.
    @param[in] case_cfg Parsed case configuration.
    @return Mapping with `length_ref`, `velocity_ref`, and optionally `density`.
    @throws ValueError when a reference scale is missing, non-finite, or not positive.
    """
    scaling = ((case_cfg.get("properties") or {}).get("scaling") or {})
    length_ref = _to_finite_float(scaling.get("length_ref"), "properties.scaling.length_ref")
    velocity_ref = _to_finite_float(scaling.get("velocity_ref"), "properties.scaling.velocity_ref")
    if length_ref <= 0.0 or velocity_ref <= 0.0:
        raise ValueError("properties.scaling.length_ref and velocity_ref must be positive.")
    scales = {"length_ref": length_ref, "velocity_ref": velocity_ref}
    density = ((case_cfg.get("properties") or {}).get("fluid") or {}).get("density")
    if density is not None:
        scales["density"] = _to_finite_float(density, "properties.fluid.density")
    return scales
 
 
RUN_OWNED_DIRECTORY_KEYS = ("log", "output")
UNSAFE_PATHS_OVERRIDE_KEY = "allow_unsafe_paths"
 
# Directory names the run tree already owns. A run-owned directory must not collide
# with one of these: the log directory in particular is recursively deleted at the
# start of a fresh solve, so pointing it at `config` would destroy the run's own
# provenance before the solver had produced anything.
RESERVED_RUN_DIRECTORY_NAMES = ("config", "scheduler", "checkpoints", "visualization")
 
# Defaults the runtime uses when a run-owned directory is not configured. An omitted
# key is not absent at runtime, so collision checks must resolve these first.
RUN_DIRECTORY_DEFAULTS = {"log": "logs", "output": "output"}
 
# Runtime flags that select run-owned directories. The workspace contract owns them;
# raw passthrough must not replace the canonical values emitted by the generator.
RESERVED_DIRECTORY_FLAGS = (
    "-log_dir", "-output_dir", "-restart_dir", "-analysis_dir",
    "-allow_unsafe_log_dir",
)
 
# PETSc indirection that could reintroduce a reserved flag without naming it. An
# options file or an alias is evaluated by PETSc itself, so its contents are outside
# every check this module performs.
RESERVED_INDIRECTION_FLAGS = ("-options_file", "-options_file_yaml", "-alias")
 
 
# Characters that cannot survive a PETSc options line unambiguously. A run
# subdirectory name containing whitespace, quotes, or a comment marker either needs
# quoting the generator does not apply, or changes how PETSc tokenizes the line.
# Rejecting them keeps the generated control file unambiguous by construction.
UNSAFE_DIRECTORY_CHARACTERS = ('"', "'", "#", "\n", "\r", "\t")
 
 
def directory_value_charset_problem(value: str) -> str:
    """!
    @brief Describe why a directory value cannot be written to a PETSc options line.
    @param[in] value Configured directory value.
    @return Human-readable reason, or an empty string when the value is safe.
    """
    if any(character.isspace() for character in value):
        return "contains whitespace"
    for character in UNSAFE_DIRECTORY_CHARACTERS:
        if character in value:
            label = {'"': "a double quote", "'": "a single quote", "#": "a comment marker"}.get(
                character, "a control character"
            )
            return f"contains {label}"
    return ""
 
 
def classify_run_directory_value(value) -> str:
    """!
    @brief Classify a configured run directory value.
 
    @details Containment is judged lexically against the run directory, because the run
             directory does not exist yet at validation time. Beyond escaping, a value
             is rejected when it resolves to the run root itself: the log directory is
             recursively deleted on a fresh solve, so `.` or `a/..` would delete the run.
    @param[in] value Configured directory value from monitor `io.directories`.
    @return One of "contained", "escaping", "tilde", "run_root", or "invalid".
    """
    if not isinstance(value, str) or not value.strip():
        return "invalid"
    candidate = value.strip()
    # `~` is its own verdict because nothing expands it anywhere in the pipeline. The
    # control file is read by PETSc, not by a shell, and both the planner and the C
    # runtime treat a value not starting with `/` as relative to the run - so `~/logs`
    # names a literal `~` directory inside the run tree.
    #
    # It was worse before this verdict existed: physical containment classified `~` as
    # an authorizable external absolute location by expanding it, while every layer
    # that actually used the value treated it literally. The two disagreed about which
    # directory was being deleted. The fix is to refuse the value, not to expand it -
    # expanding it in one layer would only move the disagreement.
    if candidate.startswith("~"):
        return "tilde"
    if os.path.isabs(candidate):
        return "escaping"
    normalized = os.path.normpath(candidate)
    if normalized == os.pardir or normalized.startswith(os.pardir + os.sep):
        return "escaping"
    if normalized in (".", ""):
        return "run_root"
    return "contained"
 
 
def normalized_run_directory(value: str) -> str:
    """!
    @brief Normalized, comparable form of a contained run directory value.
    @param[in] value Configured directory value.
    @return Normalized relative path.
    """
    return os.path.normpath(str(value).strip()).replace(os.sep, "/")
 
 
def paths_overlap(first: str, second: str) -> bool:
    """!
    @brief Whether two run-relative directories are the same or nested in one another.
    @param[in] first Normalized directory.
    @param[in] second Normalized directory.
    @return True when one contains the other.
    """
    if first == second:
        return True
    return first.startswith(second + "/") or second.startswith(first + "/")
 
 
def resolve_unsafe_paths_override(dirs: dict, monitor_path: str) -> tuple:
    """!
    @brief Resolve the unsafe-paths override, requiring a real YAML boolean.
 
    @details A truthy string such as "false" must never enable an override that permits
             a destructive path. Only a genuine boolean `true` enables it; any other
             type is a configuration error rather than a silent interpretation.
    @param[in] dirs The `io.directories` mapping.
    @param[in] monitor_path Path to the monitor file, for error messages.
    @return Tuple of (enabled, errors).
    """
    if UNSAFE_PATHS_OVERRIDE_KEY not in dirs:
        return False, []
    raw = dirs[UNSAFE_PATHS_OVERRIDE_KEY]
    if raw is True:
        return True, []
    if raw is False:
        return False, []
    return False, [
        f"  {monitor_path}: 'io.directories.{UNSAFE_PATHS_OVERRIDE_KEY}' must be a YAML boolean "
        f"(true or false), got {raw!r}. Quoted strings and numbers are rejected so a value like "
        f"\"false\" cannot silently enable an unsafe path."
    ]
 
 
def evaluate_run_directories(values: dict, override: bool, explicit: set = None) -> tuple:
    """!
    @brief Apply every run-directory safety rule to a set of effective directory values.
 
    @details Single source of truth for the rules, shared by configuration validation and
             submission preflight so the two cannot drift apart. Callers must pass
             *effective* values with defaults filled in.
 
             Two classes of finding are distinguished. **Waivable** findings concern a
             deliberate external location; `allow_unsafe_paths` downgrades those to
             warnings. **Non-waivable** findings concern self-destruction or a value that
             cannot be written unambiguously - the run root itself, a reserved run
             directory, log/output overlap, and malformed characters. The override was
             granted for deliberate external storage, never for deleting the run's own
             config or emitting an ambiguous option line, so those stay errors.
    @param[in] values Effective mapping of directory key to configured value.
    @param[in] override Whether the unsafe-paths override is enabled.
    @param[in] explicit Keys the user actually configured; the rest are reported as defaults.
    @return Tuple of (errors, warnings) as bare messages without a file prefix.
    """
    errors: list = []
    warnings: list = []
    configured_keys = set(values) if explicit is None else set(explicit)
 
    def waivable(message: str) -> None:
        """!
        @brief Record a finding the unsafe-paths override may downgrade.
        @param[in] message Finding text.
        @return None.
        """
        if override:
            warnings.append(
                f"{message} Allowed only because '{UNSAFE_PATHS_OVERRIDE_KEY}: true' is set."
            )
        else:
            errors.append(
                f"{message} Use a directory inside the run tree, or set "
                f"'io.directories.{UNSAFE_PATHS_OVERRIDE_KEY}: true' to override deliberately."
            )
 
    def fatal(message: str) -> None:
        """!
        @brief Record a finding the override must never waive.
        @param[in] message Finding text.
        @return None.
        """
        errors.append(f"{message} This cannot be overridden.")
 
    destructive_note = (
        "On a fresh solve the runtime RECURSIVELY DELETES this directory before writing to it."
    )
    resolved: dict = {}
    for key in RUN_OWNED_DIRECTORY_KEYS:
        if key not in values:
            continue
        raw = values[key]
        detail = destructive_note if key == "log" else (
            "Run output must stay inside the run directory so it can be archived and restored."
        )
        if not isinstance(raw, str) or not raw.strip():
            fatal(f"'io.directories.{key}' must be a non-empty relative path (got {raw!r}).")
            continue
 
        # Both axes are reported. Escaping is the safety-critical property and leads,
        # but character problems are non-waivable, so a value that is both must not be
        # able to slip through by overriding only the escape.
        verdict = classify_run_directory_value(raw)
        charset_problem = directory_value_charset_problem(raw)
        if charset_problem:
            fatal(
                f"'io.directories.{key}' = {raw!r} {charset_problem}. Run directory names must be "
                f"writable to a PETSc options line without quoting; use a plain relative path such "
                f"as 'logs' or 'diagnostics/run1'."
            )
        if verdict == "tilde":
            fatal(
                f"'io.directories.{key}' = {raw!r} starts with '~', which nothing expands. "
                f"The control file is read by PETSc rather than by a shell, and the C "
                f"runtime resolves a value not starting with '/' relative to the run - so "
                f"this would be planned as one directory and deleted as another. Give a "
                f"real absolute path if an external location is intended. This cannot be "
                f"overridden."
            )
            continue
        if verdict == "escaping":
            if not (isinstance(raw, str) and raw.strip().startswith("/")):
                fatal(
                    f"'io.directories.{key}' = {raw!r} escapes the run directory by relative "
                    f"traversal. {detail} A relative escape lands among sibling runs and study "
                    f"members, so it is never authorizable; give an absolute path if an external "
                    f"location is genuinely intended."
                )
                continue
            # No `continue`: an authorized absolute path must still face the
            # non-waivable checks below, or it could target a run-owned directory such
            # as `/abs/run/config`.
            waivable(f"'io.directories.{key}' = {raw!r} escapes the run directory. {detail}")
        if verdict == "run_root":
            fatal(
                f"'io.directories.{key}' = {raw!r} resolves to the run directory itself. "
                + (destructive_note + " That would delete the entire run."
                   if key == "log" else "Run output must live in its own subdirectory.")
            )
            continue
        if charset_problem:
            continue
        normalized = normalized_run_directory(raw)
        resolved[key] = normalized
        # Every segment is checked, not just the first: `./config`, `output/sub`, and
        # `/abs/run/config` all target run-owned directories.
        segments = [s for s in normalized.split("/") if s not in ("", ".")]
        hit = next((s for s in segments if s in RESERVED_RUN_DIRECTORY_NAMES), None)
        if hit:
            fatal(
                f"'io.directories.{key}' = {raw!r} targets the reserved run directory "
                f"'{hit}'. " + (destructive_note if key == "log"
                                else "That directory is owned by the run tree.")
            )
 
    if "log" in resolved and "output" in resolved and paths_overlap(resolved["log"], resolved["output"]):
        log_source = "" if "log" in configured_keys else " (default)"
        out_source = "" if "output" in configured_keys else " (default)"
        fatal(
            f"'io.directories.log' ({resolved['log']!r}{log_source}) and 'io.directories.output' "
            f"({resolved['output']!r}{out_source}) overlap. {destructive_note} "
            f"That would delete solver output."
        )
    return errors, warnings
 
 
# Typed physical verdicts. Waivability is decided on the verdict, never on a substring
# of the message: a finding reading "resolves to the run directory itself" contains no
# word like "escapes", so message matching silently downgraded self-destruction to a
# warning. Message text is for humans; these constants are for the rule.
PHYSICAL_VERDICT_CONTAINED = "contained"
PHYSICAL_VERDICT_RUN_ROOT = "run_root"
PHYSICAL_VERDICT_ANCESTOR = "ancestor"
PHYSICAL_VERDICT_RELATIVE_ESCAPE = "relative_escape"
PHYSICAL_VERDICT_EXTERNAL_ABSOLUTE = "external_absolute"
 
# The only verdict an explicit authorization may waive. An external absolute location
# is a deliberate, if dangerous, choice. Deleting the run itself, or an ancestor of it,
# or following a relative symlink out of the tree, are not choices anyone makes on
# purpose, so no authorization reaches them.
WAIVABLE_PHYSICAL_VERDICTS = frozenset({PHYSICAL_VERDICT_EXTERNAL_ABSOLUTE})
 
 
def classify_physical_containment(run_dir: str, values: dict) -> list:
    """!
    @brief Classify where each run-owned directory physically lands.
 
    @details Lexical containment is not enough: a contained name can be a symlink to an
             external directory, and `PetscRMTree` follows symlinks. This resolves the
             real path - including any symlinked ancestor - and reports a typed verdict
             so the caller can apply the waiver rule structurally.
    @param[in] run_dir Run directory the values are relative to.
    @param[in] values Effective directory mapping.
    @return List of (key, verdict, message) for every value that is not contained.
    """
    findings: list = []
    try:
        root = os.path.realpath(run_dir)
    except OSError:
        return findings
    for key in RUN_OWNED_DIRECTORY_KEYS:
        raw = values.get(key)
        if not isinstance(raw, str) or not raw.strip():
            continue
        text = raw.strip()
        # Whether the *value* was given as an absolute location, which is the only form
        # an authorization can cover. A relative name that resolves outside the tree got
        # there through a symlink, and that is never what an operator asked for.
        # Only a real absolute path can be waived. `~` is refused before this point by
        # the lexical rules, and is not expanded here either: an earlier version did
        # expand it, which made this layer reason about a home directory no other layer
        # ever resolves.
        absolute = text.startswith("/")
        candidate = os.path.join(run_dir, text)
        real = os.path.realpath(candidate)
 
        if real == root:
            findings.append((key, PHYSICAL_VERDICT_RUN_ROOT,
                f"'io.directories.{key}' = {raw!r} resolves to the run directory itself "
                f"({real!r}); deleting it would destroy the run. This cannot be overridden."))
        elif real == os.sep or root.startswith(real.rstrip(os.sep) + os.sep):
            findings.append((key, PHYSICAL_VERDICT_ANCESTOR,
                f"'io.directories.{key}' = {raw!r} resolves to {real!r}, which CONTAINS the run "
                f"directory {root!r}. The runtime deletes this path recursively, so it would "
                f"destroy the run and everything beside it. This cannot be overridden."))
        elif real.startswith(root + os.sep):
            continue
        elif absolute:
            findings.append((key, PHYSICAL_VERDICT_EXTERNAL_ABSOLUTE,
                f"'io.directories.{key}' = {raw!r} resolves to {real!r}, which is outside the run "
                f"directory {root!r}. The runtime deletes its log directory recursively."))
        else:
            findings.append((key, PHYSICAL_VERDICT_RELATIVE_ESCAPE,
                f"'io.directories.{key}' = {raw!r} is a relative name that resolves to {real!r}, "
                f"outside the run directory {root!r} - a symlink leads out of the tree. A "
                f"relative escape is never authorizable; name an absolute path if an external "
                f"location is genuinely intended. This cannot be overridden."))
    return findings
 
 
def check_physical_containment(run_dir: str, values: dict) -> list:
    """!
    @brief Human-readable physical containment violations.
    @param[in] run_dir Run directory the values are relative to.
    @param[in] values Effective directory mapping.
    @return Violation lines.
    """
    return [message for _, _, message in classify_physical_containment(run_dir, values)]
 
 
def effective_run_directories(configured: dict) -> dict:
    """!
    @brief Fill in defaults for run-owned directories that were not configured.
 
    @details An omitted key is not absent at runtime, it takes its default. Checking
             only explicit keys would miss `log: output`, which collides with the
             default output directory and would delete solver output.
    @param[in] configured Configured directory mapping, possibly partial.
    @return Effective mapping with defaults applied.
    """
    effective = dict(RUN_DIRECTORY_DEFAULTS)
    for key in RUN_OWNED_DIRECTORY_KEYS:
        if key in configured:
            effective[key] = configured[key]
    return effective
 
 
def validate_run_directory_containment(monitor_cfg: dict, monitor_path: str) -> tuple:
    """!
    @brief Classify legacy directory values as defense-in-depth during validation.
    @details The monitor schema rejects this removed surface. Keeping the stricter
             classifier here ensures malformed or manually constructed configurations
             still receive the safety findings that protect recursive log cleanup.
    @param[in] monitor_cfg Parsed monitor YAML dictionary.
    @param[in] monitor_path Path to the monitor file, for error messages.
    @return Tuple of (errors, warnings).
    """
    io_cfg = (monitor_cfg or {}).get("io") or {}
    dirs = io_cfg.get("directories")
    if not isinstance(dirs, dict):
        return [], []
    override, override_errors = resolve_unsafe_paths_override(dirs, monitor_path)
    errors, warnings = evaluate_run_directories(
        effective_run_directories(dirs), override, explicit=set(dirs)
    )
    return (
        override_errors + [f"  {monitor_path}: {message}" for message in errors],
        [f"  {monitor_path}: {message}" for message in warnings],
    )
 
 
def validate_reserved_directory_flags(config: dict, config_path: str, label: str) -> list:
    """!
    @brief Reject raw PETSc passthrough options that set run-owned directories.
 
    @details Passthrough surfaces emit `{flag: value}` verbatim into the generated
             control file. Run-owned path flags are reserved for the fixed workspace
             topology and may only be emitted by the generator.
    @param[in] config Parsed configuration mapping to scan.
    @param[in] config_path Path to the file, for error messages.
    @param[in] label Human-readable description of the surface being scanned.
    @return Violation lines.
    """
    violations: list = []
 
    def scan(node, trail: str) -> None:
        """!
        @brief Walk the mapping looking for reserved flags used as keys.
        @param[in] node Current mapping, list, or scalar node.
        @param[in] trail Dotted path to the current node, for error messages.
        @return None.
        """
        if isinstance(node, dict):
            for key, value in node.items():
                token = key.strip() if isinstance(key, str) else key
                if token in RESERVED_DIRECTORY_FLAGS:
                    violations.append(
                        f"  {config_path}: {label} sets the reserved flag '{token}' at "
                        f"{trail or '<root>'}. Run directories are fixed by the workspace "
                        "contract; raw passthrough cannot override them."
                    )
                elif token in RESERVED_INDIRECTION_FLAGS:
                    violations.append(
                        f"  {config_path}: {label} sets '{token}' at {trail or '<root>'}. PETSc "
                        f"evaluates that indirection itself, so its contents cannot be checked "
                        "here and could reintroduce a run-directory flag. Remove the indirection."
                    )
                scan(value, f"{trail}.{key}" if trail else str(key))
        elif isinstance(node, list):
            for index, item in enumerate(node):
                scan(item, f"{trail}[{index}]")
 
    scan(config, "")
    return violations
 
 
def physical_units_transition_notices(case_cfg: dict, solver_cfg: dict, monitor_cfg: dict) -> list:
    """!
    @brief Name the inputs whose meaning changed when every input became physical.
    @details These inputs were once read in solver units. At unit reference scales the
             two readings coincide, so a notice is only needed when the scales differ
             from one; it says which values are now divided by a reference scale.
    @param[in] case_cfg Parsed case configuration.
    @param[in] solver_cfg Parsed solver configuration.
    @param[in] monitor_cfg Parsed monitor configuration.
    @return Warning lines, empty when the case uses unit reference scales.
    """
    try:
        scales = resolve_reference_scales(case_cfg)
    except (ValueError, TypeError, AttributeError):
        return []
    if scales["length_ref"] == 1.0 and scales["velocity_ref"] == 1.0:
        return []
    physics = ((case_cfg.get("models") or {}).get("physics") or {})
    ic = ((case_cfg.get("properties") or {}).get("initial_conditions") or {})
    operation = (solver_cfg or {}).get("operation_mode") or {}
    windows = (((monitor_cfg or {}).get("field_statistics") or {}).get("windows") or [])
    changed = []
    if isinstance((physics.get("particles") or {}).get("point_source"), dict):
        changed.append("models.physics.particles.point_source")
    wall_cfg = (physics.get("turbulence") or {}).get("wall_function")
    if isinstance(wall_cfg, dict) and "roughness_height" in wall_cfg:
        changed.append("models.physics.turbulence.wall_function.roughness_height")
    if str(ic.get("mode", "")).strip().lower() == "file":
        changed.append("properties.initial_conditions (mode: file payload)")
    if str(ic.get("generator", "")).strip().lower().replace("-", "_") in _PYTHON_INITIAL_CONDITION_PROVIDERS:
        changed.append(f"properties.initial_conditions.params ({ic.get('generator')})")
    if isinstance(operation, dict) and operation.get("uniform_flow"):
        changed.append("operation_mode.uniform_flow")
    if ((solver_cfg or {}).get("verification") or {}).get("sources"):
        changed.append("verification.sources")
    if any(isinstance(window, dict) and ({"start_time", "end_time", "time_cadence"} & set(window))
           for window in windows):
        changed.append("field_statistics.windows[].{start_time,end_time,time_cadence}")
    if not changed:
        return []
    return [
        f"Physical units: with length_ref={scales['length_ref']:g} and "
        f"velocity_ref={scales['velocity_ref']:g}, these inputs are read as physical values and "
        f"converted to solver units: {', '.join(changed)}. Inputs written in solver units "
        f"before this rule must be converted; see docs/pages/19_Nondimensionalization.md."
    ]
 
 
def validate_simulation_configs(case_cfg: dict, solver_cfg: dict, monitor_cfg: dict,
                                case_path: str, solver_path: str, monitor_path: str,
                                restart_source_given: bool = False):
    """!
    @brief Validates every configuration a simulation run consumes, before any work is done.
    @details Covers the three roles the solver is launched with: the case, the solver,
             and the monitor. Only one of those is a solver configuration, which is
             why this is not named for the solver; the monitor in particular carries
             observation and field-statistics contracts that have nothing to do with
             the numerical scheme.
 
             Checks required sections, required keys, physical sanity, and the
             cross-file combinations no single file can rule out. Post-processing
             configuration is validated separately by `validate_post_config()`.
    @param[in] case_cfg    Parsed case YAML dictionary.
    @param[in] solver_cfg  Parsed solver YAML dictionary.
    @param[in] monitor_cfg Parsed monitor YAML dictionary.
    @param[in] case_path   Path to case file (for error messages).
    @param[in] solver_path Path to solver file (for error messages).
    @param[in] monitor_path Path to monitor file (for error messages).
    @param[in] restart_source_given Whether the invocation names a restart source
                                    (--restart-from or --continue), which silences the
                                    reminder that the case needs one.
    @throws SystemExit on validation failure.
    """
    errors = []
    warnings = []
    warnings.extend(physical_units_transition_notices(case_cfg, solver_cfg, monitor_cfg))
    errors.extend(validate_reserved_directory_flags(
        case_cfg, case_path, "case solver_parameters / passthrough"))
    errors.extend(validate_reserved_directory_flags(
        solver_cfg, solver_path, "solver petsc_passthrough_options"))
    eulerian_source_mode = "solve"
 
    legacy_models = case_cfg.get("models") if isinstance(case_cfg, dict) else None
    legacy_statistics = legacy_models.get("statistics") if isinstance(legacy_models, dict) else None
    if legacy_statistics is not None:
        errors.append(
            f"  {case_path}: 'models.statistics' was removed with the legacy averaging system. "
            "Use instantaneous output and offline postprocessing until the replacement "
            "field-statistics pipeline is available."
        )
    if isinstance(solver_cfg, dict) and "solution_convergence" in solver_cfg:
        errors.append(
            f"  {solver_path}: 'solution_convergence' moved to "
            "monitor.yml -> solution_monitoring.convergence."
        )
    if errors:
        _print_validation_errors(errors)
 
    _validate_yaml_schema_keys(case_cfg, _CASE_SCHEMA, case_path, errors)
    _validate_yaml_schema_keys(solver_cfg, _SOLVER_SCHEMA, solver_path, errors)
    _validate_yaml_schema_keys(monitor_cfg, _MONITOR_SCHEMA, monitor_path, errors)
 
    # --- case.yml: required top-level sections ---
    required_case_sections = ['properties', 'run_control', 'grid', 'models', 'boundary_conditions']
    for section in required_case_sections:
        if section not in case_cfg:
            errors.append(f"  {case_path}: missing required section '{section}'.")
 
    if errors:
        _print_validation_errors(errors)
 
    # --- case.yml: properties sub-keys ---
    props = case_cfg.get('properties', {})
    for group, keys in [('scaling', ['length_ref', 'velocity_ref']),
                        ('fluid', ['density', 'viscosity'])]:
        sub = props.get(group, {})
        if not sub:
            errors.append(f"  {case_path}: missing 'properties.{group}' section.")
        else:
            for k in keys:
                if k not in sub:
                    errors.append(f"  {case_path}: missing key 'properties.{group}.{k}'.")
 
    # --- case.yml: run_control sub-keys ---
    rc = case_cfg.get('run_control', {})
    for k in ['start_step', 'total_steps', 'dt_physical']:
        if k not in rc:
            errors.append(f"  {case_path}: missing key 'run_control.{k}'.")
 
    # --- Physical sanity checks ---
    # Each value is checked for its type here: later stages convert them with int()/float()
    # and would otherwise stop with a Python error instead of naming the key.
    for key, value, positive in (
        ('properties.fluid.density', props.get('fluid', {}).get('density', 0), True),
        ('properties.fluid.viscosity', props.get('fluid', {}).get('viscosity', 0), False),
        ('run_control.dt_physical', rc.get('dt_physical', 0), True),
    ):
        if not isinstance(value, (int, float)) or isinstance(value, bool):
            errors.append(f"  {case_path}: '{key}' must be a number (got {value!r}).")
        elif positive and value <= 0:
            errors.append(f"  {case_path}: '{key}' must be positive (got {value}).")
        elif value < 0:
            errors.append(f"  {case_path}: '{key}' must be non-negative (got {value}).")
    particles_count = (((case_cfg.get('models') or {}).get('physics') or {}).get('particles') or {}).get('count', 0)
    for key, value in (('run_control.start_step', rc.get('start_step', 0)),
                       ('run_control.total_steps', rc.get('total_steps', 0)),
                       ('models.physics.particles.count', particles_count)):
        if not isinstance(value, int) or isinstance(value, bool) or value < 0:
            errors.append(f"  {case_path}: '{key}' must be a non-negative integer (got {value!r}).")
    if errors:
        _print_validation_errors(errors)
 
    # --- case.yml: grid mode ---
    grid_cfg = case_cfg.get('grid', {})
    grid_mode = grid_cfg.get('mode')
    valid_grid_modes = list(GRID_MODES)
    if grid_mode not in valid_grid_modes:
        errors.append(f"  {case_path}: 'grid.mode' must be one of {valid_grid_modes} (got '{grid_mode}').")
    elif grid_mode == 'file':
        source_file = grid_cfg.get('source_file')
        if not source_file:
            errors.append(f"  {case_path}: 'grid.source_file' is required when grid.mode is 'file'.")
        else:
            try:
                source_abs = resolve_workspace_path(case_path, source_file)
            except ValueError as exc:
                errors.append(f"  {case_path}: {exc}")
            else:
                if not os.path.isfile(source_abs):
                    errors.append(f"  {case_path}: grid.source_file does not exist: {source_abs}")
    elif grid_mode == 'programmatic_c':
        grid_settings = grid_cfg.get('programmatic_settings')
        if not grid_settings:
            errors.append(f"  {case_path}: 'grid.programmatic_settings' is required when grid.mode is 'programmatic_c'.")
        elif not isinstance(grid_settings, dict):
            errors.append(f"  {case_path}: 'grid.programmatic_settings' must be a mapping.")
    elif grid_mode == 'grid_gen':
        gen_cfg = grid_cfg.get('generator')
        if not isinstance(gen_cfg, dict):
            errors.append(f"  {case_path}: 'grid.generator' must be a mapping when grid.mode is 'grid_gen'.")
        else:
            warn_on_grid_generator_hyphen_keys(gen_cfg, case_path, warnings)
            errors.extend(
                reject_generator_destination_keys(gen_cfg, case_path, "grid.generator")
            )
 
            config_file = gen_cfg.get('config_file')
            if not config_file:
                errors.append(f"  {case_path}: 'grid.generator.config_file' is required for grid.mode='grid_gen'.")
            else:
                try:
                    config_abs = resolve_workspace_path(case_path, config_file)
                except ValueError as exc:
                    errors.append(f"  {case_path}: {exc}")
                else:
                    if not os.path.isfile(config_abs):
                        errors.append(f"  {case_path}: grid.generator.config_file does not exist: {config_abs}")
 
            grid_type = gen_cfg.get('grid_type')
            if grid_type is not None and str(grid_type) not in GRID_GENERATOR_TYPES:
                errors.append(f"  {case_path}: grid.generator.grid_type must be one of "
                              f"{list(GRID_GENERATOR_TYPES)} (got '{grid_type}').")
 
            # cli_args is an opaque token list handed straight to the generator, so a bad
            # geometry selector inside it would otherwise surface as a nonzero subprocess
            # exit in the middle of a run rather than as a validation error before one.
            errors.extend(validate_grid_generator_cli_args(gen_cfg.get('cli_args'), case_path))
 
            cli_args = gen_cfg.get('cli_args', [])
            if cli_args is not None and not isinstance(cli_args, list):
                errors.append(f"  {case_path}: grid.generator.cli_args must be a list of CLI tokens.")
    try:
        resolve_grid_da_processor_layout(grid_cfg)
    except ValueError as e:
        errors.append(f"  {case_path}: {e}")
 
    # --- case.yml: boundary_conditions strict validation ---
    prepared_blocks = None
    try:
        prepared_blocks = validate_and_prepare_boundary_conditions(case_cfg)
    except ValueError as e:
        errors.append(f"  {case_path}: {e}")
 
    # --- case.yml: initial_conditions mode-aware validation ---
    ic = props.get('initial_conditions', {})
    resolved_ic = None
    try:
        ic_start_step = int((case_cfg.get("run_control", {}) or {}).get("start_step", 0) or 0)
    except (TypeError, ValueError):
        ic_start_step = 0
    try:
        ic_eulerian_source = normalize_eulerian_field_source(
            (solver_cfg.get("operation_mode", {}) or {}).get("eulerian_field_source", "solve")
        )
    except ValueError:
        # The solver-specific validation below reports an invalid source value.
        # Keep IC validation independent of that diagnostic.
        ic_eulerian_source = "solve"
    ic_is_authoritative = ic_eulerian_source == "solve" and ic_start_step == 0
    if not ic:
        errors.append(f"  {case_path}: missing 'properties.initial_conditions' section.")
    elif not isinstance(ic, dict):
        errors.append(f"  {case_path}: 'properties.initial_conditions' must be a mapping.")
    elif 'mode' not in ic:
        errors.append(
            f"  {case_path}: missing key 'properties.initial_conditions.mode'. "
            "Specify 'generated' or 'file' explicitly."
        )
    elif ic_is_authoritative:
        try:
            scaling_contract = resolve_fluid_scaling(case_cfg)
            resolved_ic = resolve_initial_condition_config(
                ic, prepared_blocks, scales=scaling_contract,
                provider_context={"kinematic_viscosity": scaling_contract["nondimensional_kinematic_viscosity"]},
            )
        except KeyError as e:
            errors.append(f"  {case_path}: missing key 'properties.initial_conditions.{e.args[0]}'.")
        except ValueError as e:
            errors.append(f"  {case_path}: {e}")
    if ic_is_authoritative and resolved_ic and resolved_ic.get("kind") == "stability_mode_velocity":
        dimensionality = str((((case_cfg.get("models", {}) or {}).get("physics", {}) or {})
                             .get("dimensionality", "3D"))).strip().upper()
        smv = resolved_ic["params"]
        if dimensionality == "2D" and ("i" in (smv["streamwise_axis"], smv["cross_axis"])
                                       or not (smv.get("noise") or {"planar": True})["planar"]):
            errors.append(f"  {case_path}: stability_mode_velocity in 2D mode needs i as the normal axis "
                          "(streamwise and cross axes j and k) and noise.planar: true.")
    if (ic_is_authoritative and resolved_ic and
            GENERATED_IC_PROVIDERS.get(resolved_ic.get("kind"), {}).get("requires_fresh_3d")):
        if resolved_ic["kind"] in ("channel_spectral_velocity", "duct_spectral_velocity"):
            if (case_cfg.get("models", {}).get("physics", {}).get("fsi", {}) or {}).get("immersed", False):
                errors.append(f"  {case_path}: wall spectral ICs do not support immersed geometry.")
        dimensionality = str((((case_cfg.get("models", {}) or {}).get("physics", {}) or {})
                             .get("dimensionality", "3D"))).strip().upper()
        if dimensionality != "3D":
            errors.append(f"  {case_path}: {resolved_ic['label']} requires models.physics.dimensionality: 3D.")
        if grid_mode == "programmatic_c":
            settings = grid_cfg.get("programmatic_settings", {}) or {}
            ratios = [settings.get(key, 1.0) for key in ("rxs", "rys", "rzs")]
            try:
                if any(abs(float(value) - 1.0) > 1.0e-12 for value in ratios):
                    errors.append(f"  {case_path}: {resolved_ic['label']} requires uniform programmatic spacing (rxs/rys/rzs: 1.0).")
            except (TypeError, ValueError):
                pass
    generated_profile = any(
        bc.get("handler") == "prescribed_flow"
        and ((bc.get("params") or {}).get("source") or {}).get("type") == "generated"
        for block in (prepared_blocks or []) for bc in block
    )
    if grid_mode == 'programmatic_c' and (
            generated_profile or (resolved_ic and is_generated_ic_provider(resolved_ic))):
        try:
            validate_programmatic_bridge_grid_settings(grid_cfg.get('programmatic_settings'))
        except ValueError as e:
            errors.append(f"  {case_path}: {e}")
 
    # --- case.yml: particle initialization validation ---
    particles_cfg = case_cfg.get('models', {}).get('physics', {}).get('particles', {})
    if particles_cfg and not isinstance(particles_cfg, dict):
        errors.append(f"  {case_path}: 'models.physics.particles' must be a mapping.")
    elif isinstance(particles_cfg, dict):
        init_mode_raw = particles_cfg.get('init_mode', 'Surface')
        try:
            pinit_code = normalize_particle_init_mode(init_mode_raw)
        except ValueError as e:
            errors.append(f"  {case_path}: {e}")
            pinit_code = None
 
        # One base seed drives every particle random stream - initial placement, inlet
        # re-placement, and Brownian motion - so identical inputs on the same rank count
        # reproduce. Omitted, the runtime uses 12345.
        random_seed = particles_cfg.get('random_seed')
        if random_seed is not None and (isinstance(random_seed, bool) or not isinstance(random_seed, int)
                                        or not 0 <= random_seed <= 2147483647):
            errors.append(
                f"  {case_path}: models.physics.particles.random_seed must be an integer from 0 to "
                f"2147483647 (got {random_seed!r})."
            )
 
        restart_mode = particles_cfg.get('restart_mode')
        if restart_mode is not None and str(restart_mode).lower() not in PARTICLE_RESTART_MODES:
            errors.append(
                f"  {case_path}: models.physics.particles.restart_mode must be 'init' or 'load' (got '{restart_mode}')."
            )
        elif 'restart_mode' not in particles_cfg:
            try:
                start_step = int(rc.get('start_step', 0))
                particle_count = int(particles_cfg.get('count', 0) or 0)
            except (TypeError, ValueError):
                start_step = 0
                particle_count = 0
            if start_step > 0 and particle_count > 0:
                warnings.append(
                    f"{case_path}: models.physics.particles.restart_mode is omitted for a particle restart "
                    "(run_control.start_step > 0, count > 0). C will default to 'load'."
                )
 
        if pinit_code == 2:
            point_cfg = particles_cfg.get('point_source', {})
            if not isinstance(point_cfg, dict):
                errors.append(f"  {case_path}: models.physics.particles.point_source must be a mapping when init_mode is PointSource.")
            else:
                for coord in ('x', 'y', 'z'):
                    if coord not in point_cfg:
                        errors.append(
                            f"  {case_path}: models.physics.particles.point_source.{coord} is required when init_mode is PointSource."
                        )
 
        if 'fields' in particles_cfg:
            try:
                particle_fields = normalize_particle_fields(particles_cfg['fields'])
            except ValueError as e:
                errors.append(f"  {case_path}: {e}")
                particle_fields = []
            if particle_fields and int(particles_cfg.get('count', 0) or 0) <= 0:
                errors.append(f"  {case_path}: models.physics.particles.fields needs particles (count > 0).")
            if particle_fields and ((solver_cfg.get('verification') or {}).get('sources') or {}).get('scalar'):
                errors.append(
                    f"  {case_path}: models.physics.particles.fields cannot be combined with "
                    f"{solver_path} verification.sources.scalar, which prescribes Psi at every step.")
            if pinit_code == 2:
                for entry in particle_fields:
                    if not any(re.search(r"\b(uniform|normal)\s*\‍(", e) for e in entry["expressions"]):
                        warnings.append(
                            f"{case_path}: models.physics.particles.fields.{entry['name']} has no random draw, "
                            "but init_mode is PointSource: every particle starts at one point and gets the "
                            "same value. Use a constant, or uniform()/normal() for per-particle values.")
            try:
                resumes = int(rc.get('start_step', 0)) > 0
            except (TypeError, ValueError):
                resumes = False
            if particle_fields and resumes and str(particles_cfg.get('restart_mode', 'load')).lower() == 'load':
                warnings.append(
                    f"{case_path}: models.physics.particles.fields is ignored when particles are restored "
                    "(restart_mode: load); their values come from the checkpoint.")
 
    # --- case.yml: domain and physics switches ---
    # Multi-block coupling, immersed boundaries and moving bodies are planned, not
    # implemented. The switches stay in the schema so that setting one fails here with a
    # reason, rather than as an unknown key or, worse, as a run that solves a different
    # problem: the solver would accept all three and silently ignore what they promise.
    models_cfg = case_cfg.get('models', {}) or {}
    domain_cfg = models_cfg.get('domain', {}) or {}
    physics_cfg = models_cfg.get('physics', {}) or {}
    try:
        block_count = int(domain_cfg.get('blocks', 1))
    except (TypeError, ValueError):
        block_count = None
    if block_count != 1:
        errors.append(
            f"  {case_path}: models.domain.blocks must be 1 (got {domain_cfg.get('blocks')!r}). "
            "Multi-block domains are planned, not implemented: no solver exchanges data across "
            "the faces blocks share, so each block would be solved as an isolated domain."
        )
    fsi_cfg = physics_cfg.get('fsi', {}) or {}
    if not isinstance(fsi_cfg, dict):
        errors.append(f"  {case_path}: 'models.physics.fsi' must be a mapping.")
    else:
        for key, feature in (('immersed', 'An immersed boundary'),
                             ('moving_fsi', 'Moving-body fluid-structure interaction')):
            if fsi_cfg.get(key):
                errors.append(
                    f"  {case_path}: models.physics.fsi.{key} must be false. {feature} is planned, "
                    "not implemented: no body geometry is loaded, and the interpolation that would "
                    "impose one on the flow was never ported."
                )
    dimensionality = str(physics_cfg.get('dimensionality', '3D')).strip()
    if dimensionality not in DOMAIN_DIMENSIONALITY_MODES:
        errors.append(
            f"  {case_path}: models.physics.dimensionality must be one of "
            f"{list(DOMAIN_DIMENSIONALITY_MODES)} (got '{dimensionality}')."
        )
 
    # --- case.yml: turbulence model validation ---
    turbulence_cfg = case_cfg.get('models', {}).get('physics', {}).get('turbulence', {})
    if turbulence_cfg is not None and not isinstance(turbulence_cfg, dict):
        errors.append(f"  {case_path}: 'models.physics.turbulence' must be a mapping.")
    elif isinstance(turbulence_cfg, dict) and turbulence_cfg:
        try:
            # Only the selectors are checked here and the flags are discarded, so unit
            # scales stand in for the case's, whose own validation runs separately.
            append_turbulence_flags(case_cfg.get('models', {}), [],
                                    {"length_ref": 1.0, "velocity_ref": 1.0})
        except ValueError as e:
            errors.append(f"  {case_path}: {e}")
 
        les_cfg = turbulence_cfg.get('les')
        rans_cfg = turbulence_cfg.get('rans')
        wall_cfg = turbulence_cfg.get('wall_function')
 
        if isinstance(les_cfg, dict):
            validate_les_configuration(case_cfg, les_cfg, case_path, errors, warnings)
 
        validate_wall_model_pairing(case_cfg, les_cfg, wall_cfg, case_path,
                                    errors, warnings)
 
        if rans_cfg is not None:
            errors.append(f"  {case_path}: {RANS_PLANNED_REFUSAL}")
 
        if isinstance(wall_cfg, dict):
            if 'enabled' in wall_cfg and not isinstance(wall_cfg['enabled'], bool):
                errors.append(f"  {case_path}: models.physics.turbulence.wall_function.enabled must be true or false.")
            if 'roughness_height' in wall_cfg:
                try:
                    value = float(wall_cfg['roughness_height'])
                    if value < 0.0:
                        errors.append(f"  {case_path}: models.physics.turbulence.wall_function.roughness_height must be nonnegative.")
                except (TypeError, ValueError):
                    errors.append(f"  {case_path}: models.physics.turbulence.wall_function.roughness_height must be numeric.")
                # Only the log law has a roughness formulation. Werner-Wengle has no
                # roughness term and Cabot discards the argument, so accepting the key
                # for either would silently ignore a value the user set deliberately.
                try:
                    wall_model = normalize_wall_function_model(wall_cfg.get('model'))
                except ValueError:
                    wall_model = None
                if wall_model in (2, 3):
                    errors.append(
                        f"  {case_path}: models.physics.turbulence.wall_function.roughness_height "
                        "applies only to model 'log_law'; 'werner' has no roughness formulation and "
                        "'cabot' ignores it. Remove the key or select 'log_law'.")
 
    # --- solver.yml: basic structure ---
    if not isinstance(solver_cfg, dict) or not solver_cfg:
        errors.append(f"  {solver_path}: solver config is empty or not a valid YAML mapping.")
    else:
        strategy_cfg = solver_cfg.get('strategy', {})
        if not isinstance(strategy_cfg, dict):
            errors.append(f"  {solver_path}: 'strategy' must be a mapping.")
        elif 'implicit' in strategy_cfg:
            errors.append(
                f"  {solver_path}: unsupported old key 'strategy.implicit' is not supported. "
                "Use 'strategy.momentum_solver' with named solver values."
            )
        if isinstance(strategy_cfg, dict) and 'momentum_solver' in strategy_cfg:
            try:
                normalize_momentum_solver_type(strategy_cfg['momentum_solver'])
            except ValueError as e:
                errors.append(f"  {solver_path}: {e}")
 
        op_mode_cfg = solver_cfg.get('operation_mode', {})
        if op_mode_cfg is not None and not isinstance(op_mode_cfg, dict):
            errors.append(f"  {solver_path}: 'operation_mode' must be a mapping when provided.")
        elif isinstance(op_mode_cfg, dict):
            eulerian_source_mode = None
            normalized_analytical_type = None
            if 'eulerian_field_source' in op_mode_cfg:
                try:
                    eulerian_source_mode = normalize_eulerian_field_source(op_mode_cfg.get('eulerian_field_source'))
                except ValueError as e:
                    errors.append(f"  {solver_path}: {e}")
 
            analytical_type = op_mode_cfg.get('analytical_type')
            if analytical_type is not None:
                try:
                    normalized_analytical_type = normalize_analytical_type(analytical_type)
                except ValueError as e:
                    errors.append(f"  {solver_path}: {e}")
                else:
                    uniform_flow_cfg = op_mode_cfg.get('uniform_flow')
                    if uniform_flow_cfg is not None and not isinstance(uniform_flow_cfg, dict):
                        errors.append(f"  {solver_path}: 'operation_mode.uniform_flow' must be a mapping when provided.")
                    elif normalized_analytical_type == "UNIFORM_FLOW":
                        if not isinstance(uniform_flow_cfg, dict):
                            errors.append(
                                f"  {solver_path}: operation_mode.uniform_flow is required when "
                                "operation_mode.analytical_type is 'UNIFORM_FLOW'."
                            )
                        else:
                            for coord in ("u", "v", "w"):
                                if coord not in uniform_flow_cfg:
                                    errors.append(
                                        f"  {solver_path}: operation_mode.uniform_flow.{coord} is required for UNIFORM_FLOW."
                                    )
                                else:
                                    try:
                                        float(uniform_flow_cfg[coord])
                                    except (TypeError, ValueError):
                                        errors.append(
                                            f"  {solver_path}: operation_mode.uniform_flow.{coord} must be numeric."
                                        )
                    elif uniform_flow_cfg is not None:
                        errors.append(
                            f"  {solver_path}: operation_mode.uniform_flow is only valid when "
                            "operation_mode.analytical_type is 'UNIFORM_FLOW'."
                        )
 
            if eulerian_source_mode == "analytical":
                effective_analytical_type = normalized_analytical_type or "TGV3D"
                if effective_analytical_type == "TGV3D":
                    # programmatic_c: the solver assigns the [0, 2*pi] TGV domain itself.
                    # file: the given grid is kept and the field is evaluated at its cell centres.
                    if grid_mode not in (GRID_MODES[1], GRID_MODES[0]):
                        errors.append(
                            f"  {case_path}: analytical type '{effective_analytical_type}' requires grid.mode "
                            "'programmatic_c' (solver-assigned TGV domain) or 'file' (a grid file the field "
                            "is evaluated on)."
                        )
                    elif grid_mode == 'programmatic_c' and isinstance(grid_cfg.get('programmatic_settings'), dict):
                        missing_dims = [key for key in ('im', 'jm', 'km') if key not in grid_cfg['programmatic_settings']]
                        if missing_dims:
                            errors.append(
                                f"  {case_path}: grid.programmatic_settings must include {missing_dims} when "
                                f"operation_mode.analytical_type resolves to '{effective_analytical_type}'."
                            )
                else:
                    if grid_mode not in (GRID_MODES[1], GRID_MODES[0]):
                        errors.append(
                            f"  {case_path}: grid.mode '{grid_mode}' is not supported when "
                            f"operation_mode.analytical_type is '{effective_analytical_type}'. "
                            "Use 'programmatic_c' or 'file'."
                        )
                    elif grid_mode == 'programmatic_c' and isinstance(grid_cfg.get('programmatic_settings'), dict):
                        missing_dims = [key for key in ('im', 'jm', 'km') if key not in grid_cfg['programmatic_settings']]
                        if missing_dims:
                            errors.append(
                                f"  {case_path}: grid.programmatic_settings must include {missing_dims} when "
                                f"operation_mode.analytical_type is '{effective_analytical_type}' and "
                                "grid.mode is 'programmatic_c'."
                            )
 
        verification_cfg = solver_cfg.get('verification', {})
        if verification_cfg is not None and not isinstance(verification_cfg, dict):
            errors.append(f"  {solver_path}: 'verification' must be a mapping when provided.")
        elif isinstance(verification_cfg, dict) and verification_cfg:
            sources_cfg = verification_cfg.get('sources', {})
            if sources_cfg is not None and not isinstance(sources_cfg, dict):
                errors.append(f"  {solver_path}: 'verification.sources' must be a mapping when provided.")
            elif isinstance(sources_cfg, dict) and sources_cfg:
                diff_cfg = sources_cfg.get('diffusivity')
                scalar_cfg = sources_cfg.get('scalar')
 
                if diff_cfg is not None:
                    if not isinstance(diff_cfg, dict):
                        errors.append(f"  {solver_path}: 'verification.sources.diffusivity' must be a mapping.")
                    else:
                        if eulerian_source_mode != "analytical":
                            errors.append(
                                f"  {solver_path}: verification.sources.diffusivity is only valid when "
                                "operation_mode.eulerian_field_source is 'analytical'."
                            )
                        mode = diff_cfg.get('mode')
                        profile = diff_cfg.get('profile')
                        if str(mode).strip().lower() != "analytical":
                            errors.append(
                                f"  {solver_path}: verification.sources.diffusivity.mode must be 'analytical'."
                            )
                        if str(profile).strip().upper() != "LINEAR_X":
                            errors.append(
                                f"  {solver_path}: verification.sources.diffusivity.profile must be 'LINEAR_X'."
                            )
                        for key in ("gamma0", "slope_x"):
                            if key not in diff_cfg:
                                errors.append(
                                    f"  {solver_path}: verification.sources.diffusivity.{key} is required."
                                )
                            else:
                                try:
                                    float(diff_cfg[key])
                                except (TypeError, ValueError):
                                    errors.append(
                                        f"  {solver_path}: verification.sources.diffusivity.{key} must be numeric."
                                    )
 
                if scalar_cfg is not None:
                    if not isinstance(scalar_cfg, dict):
                        errors.append(f"  {solver_path}: 'verification.sources.scalar' must be a mapping.")
                    else:
                        if eulerian_source_mode != "analytical":
                            errors.append(
                                f"  {solver_path}: verification.sources.scalar is only valid when "
                                "operation_mode.eulerian_field_source is 'analytical'."
                            )
                        mode = scalar_cfg.get('mode')
                        profile = str(scalar_cfg.get('profile', '')).strip().upper()
                        if str(mode).strip().lower() != "analytical":
                            errors.append(
                                f"  {solver_path}: verification.sources.scalar.mode must be 'analytical'."
                            )
                        if profile not in VERIFICATION_SCALAR_PROFILES:
                            errors.append(
                                f"  {solver_path}: verification.sources.scalar.profile must be one of CONSTANT, LINEAR_X, SIN_PRODUCT."
                            )
                        required_scalar_keys = {
                            "CONSTANT": ("value",),
                            "LINEAR_X": ("phi0", "slope_x"),
                            "SIN_PRODUCT": ("amplitude", "kx", "ky", "kz"),
                        }.get(profile, ())
                        for key in required_scalar_keys:
                            if key not in scalar_cfg:
                                errors.append(
                                    f"  {solver_path}: verification.sources.scalar.{key} is required for profile '{profile}'."
                                )
                            else:
                                try:
                                    float(scalar_cfg[key])
                                except (TypeError, ValueError):
                                    errors.append(
                                        f"  {solver_path}: verification.sources.scalar.{key} must be numeric."
                                    )
 
                unknown_source_keys = sorted(set(sources_cfg.keys()) - {"diffusivity", "scalar"})
                if unknown_source_keys:
                    errors.append(
                        f"  {solver_path}: unsupported verification.sources entries: {unknown_source_keys}. "
                        "Currently supported: 'diffusivity', 'scalar'."
                    )
            unknown_verification_keys = sorted(set(verification_cfg.keys()) - {"sources"})
            if unknown_verification_keys:
                errors.append(
                    f"  {solver_path}: unsupported verification keys: {unknown_verification_keys}. "
                    "Currently supported: 'sources'."
                )
 
        try:
            resolve_scalar_transport(case_cfg, solver_cfg, warn=True)
        except ValueError as exc:
            errors.append(f"  {solver_path}: {exc}")
        try:
            resolve_les_diagnostics(case_cfg, monitor_cfg, warn=True)
        except ValueError as exc:
            errors.append(f"  {monitor_path}: {exc}")
 
        tolerances_cfg = solver_cfg.get('tolerances', {})
        if tolerances_cfg is not None and not isinstance(tolerances_cfg, dict):
            errors.append(f"  {solver_path}: 'tolerances' must be a mapping when provided.")
        elif isinstance(tolerances_cfg, dict):
            for key in ("absolute_tol", "relative_tol", "residual_absolute_tol", "residual_relative_tol"):
                if key in tolerances_cfg:
                    try:
                        float(tolerances_cfg[key])
                    except (TypeError, ValueError):
                        errors.append(f"  {solver_path}: tolerances.{key} must be numeric.")
 
        ms_cfg = solver_cfg.get('momentum_solver', {})
        if ms_cfg is not None and not isinstance(ms_cfg, dict):
            errors.append(f"  {solver_path}: 'momentum_solver' must be a mapping when provided.")
        elif isinstance(ms_cfg, dict):
            unsupported_flat_keys = {
                'max_pseudo_steps', 'absolute_tol', 'relative_tol', 'step_tol',
                'pseudo_cfl', 'jameson_residual_noise_allowance_factor',
                'rk4_residual_noise_allowance_factor'
            }
            present_unsupported = sorted(unsupported_flat_keys.intersection(ms_cfg.keys()))
            if present_unsupported:
                errors.append(
                    f"  {solver_path}: unsupported flat keys in 'momentum_solver' are not supported: {present_unsupported}. "
                    "Use solver-specific sub-blocks (e.g., momentum_solver.dual_time_picard_jameson_rk)."
                )
 
            allowed_ms_keys = {'dual_time_picard_jameson_rk', 'dual_time_picard_rk4', 'newton_krylov'}
            unknown_ms_keys = sorted(set(ms_cfg.keys()) - allowed_ms_keys)
            if unknown_ms_keys:
                errors.append(
                    f"  {solver_path}: unsupported momentum_solver blocks/keys: {unknown_ms_keys}. "
                    "Currently supported: 'dual_time_picard_jameson_rk' and 'newton_krylov'."
                )
            if 'dual_time_picard_jameson_rk' in ms_cfg and 'dual_time_picard_rk4' in ms_cfg:
                errors.append(
                    f"  {solver_path}: use only momentum_solver.dual_time_picard_jameson_rk; "
                    "do not also set its deprecated dual_time_picard_rk4 alias."
                )
 
            selected_solver = None
            if isinstance(strategy_cfg, dict) and 'momentum_solver' in strategy_cfg:
                try:
                    selected_solver = normalize_momentum_solver_type(strategy_cfg['momentum_solver'])
                except ValueError:
                    pass
            if selected_solver is None:
                selected_solver = "DUALTIME_PICARD_JAMESON_RK"
 
            has_dualtime_block = (
                'dual_time_picard_jameson_rk' in ms_cfg or 'dual_time_picard_rk4' in ms_cfg
            )
            if selected_solver != "DUALTIME_PICARD_JAMESON_RK" and has_dualtime_block:
                errors.append(
                    f"  {solver_path}: momentum_solver.dual_time_picard_jameson_rk is set but selected solver is "
                    f"{selected_solver}. Solver-specific blocks must match the selected solver."
                )
 
            newton_cfg = ms_cfg.get('newton_krylov')
            if newton_cfg is not None:
                if selected_solver != "newton_krylov":
                    errors.append(
                        f"  {solver_path}: momentum_solver.newton_krylov is set but selected solver is "
                        f"{selected_solver}. Solver-specific blocks must match the selected solver."
                    )
                try:
                    validate_newton_krylov_config(newton_cfg)
                except ValueError as exc:
                    errors.append(f"  {solver_path}: {exc}")
 
            dt_picard_cfg = ms_cfg.get('dual_time_picard_jameson_rk', ms_cfg.get('dual_time_picard_rk4'))
            if dt_picard_cfg is not None:
                if not isinstance(dt_picard_cfg, dict):
                    errors.append(f"  {solver_path}: momentum_solver.dual_time_picard_jameson_rk must be a mapping.")
                else:
                    allowed_dt_keys = {
                        'max_pseudo_steps', 'absolute_tol', 'relative_tol', 'step_tol',
                        'pseudo_cfl', 'jameson_residual_noise_allowance_factor',
                        'rk4_residual_noise_allowance_factor', 'ratio_ema_alpha'
                    }
                    unknown_dt_keys = sorted(set(dt_picard_cfg.keys()) - allowed_dt_keys)
                    if unknown_dt_keys:
                        errors.append(
                            f"  {solver_path}: unsupported keys in momentum_solver.dual_time_picard_jameson_rk: {unknown_dt_keys}."
                        )
                    if ('jameson_residual_noise_allowance_factor' in dt_picard_cfg and
                            'rk4_residual_noise_allowance_factor' in dt_picard_cfg):
                        errors.append(
                            f"  {solver_path}: use only jameson_residual_noise_allowance_factor; "
                            "do not also set its deprecated rk4_residual_noise_allowance_factor alias."
                        )
                    if 'pseudo_cfl' in dt_picard_cfg:
                        pcfl_cfg = dt_picard_cfg['pseudo_cfl']
                        if not isinstance(pcfl_cfg, dict):
                            errors.append(f"  {solver_path}: momentum_solver.dual_time_picard_jameson_rk.pseudo_cfl must be a mapping.")
                        else:
                            allowed_pcfl_keys = {'initial', 'minimum', 'maximum', 'growth_factor', 'reduction_factor'}
                            unknown_pcfl_keys = sorted(set(pcfl_cfg.keys()) - allowed_pcfl_keys)
                            if unknown_pcfl_keys:
                                errors.append(
                                    f"  {solver_path}: unsupported keys in momentum_solver.dual_time_picard_jameson_rk.pseudo_cfl: {unknown_pcfl_keys}."
                                )
                            numeric_pcfl = {}
                            for key in allowed_pcfl_keys:
                                if key in pcfl_cfg:
                                    try:
                                        numeric_pcfl[key] = float(pcfl_cfg[key])
                                    except (TypeError, ValueError):
                                        errors.append(
                                            f"  {solver_path}: momentum_solver.dual_time_picard_jameson_rk.pseudo_cfl.{key} must be numeric."
                                        )
                            if numeric_pcfl.get('minimum', 1.0) <= 0.0:
                                errors.append(f"  {solver_path}: pseudo_cfl.minimum must be positive.")
                            if numeric_pcfl.get('growth_factor', 1.0) < 1.0:
                                errors.append(f"  {solver_path}: pseudo_cfl.growth_factor must be at least 1.")
                            reduction = numeric_pcfl.get('reduction_factor', 1.0)
                            if reduction <= 0.0 or reduction >= 1.0:
                                errors.append(f"  {solver_path}: pseudo_cfl.reduction_factor must be in (0, 1).")
                            if all(key in numeric_pcfl for key in ('minimum', 'initial', 'maximum')):
                                if not numeric_pcfl['minimum'] <= numeric_pcfl['initial'] <= numeric_pcfl['maximum']:
                                    errors.append(f"  {solver_path}: pseudo_cfl requires minimum <= initial <= maximum.")
                    noise_key = (
                        'jameson_residual_noise_allowance_factor'
                        if 'jameson_residual_noise_allowance_factor' in dt_picard_cfg
                        else 'rk4_residual_noise_allowance_factor'
                    )
                    if noise_key in dt_picard_cfg:
                        try:
                            if float(dt_picard_cfg[noise_key]) < 1.0:
                                errors.append(f"  {solver_path}: {noise_key} must be at least 1.")
                        except (TypeError, ValueError):
                            errors.append(f"  {solver_path}: {noise_key} must be numeric.")
                    if 'ratio_ema_alpha' in dt_picard_cfg:
                        try:
                            alpha_val = float(dt_picard_cfg['ratio_ema_alpha'])
                            if not 0.0 <= alpha_val <= 1.0:
                                errors.append(f"  {solver_path}: ratio_ema_alpha must be in [0, 1].")
                        except (TypeError, ValueError):
                            errors.append(f"  {solver_path}: ratio_ema_alpha must be numeric.")
 
    # --- solver.yml: interpolation section ---
    interp_cfg = solver_cfg.get('interpolation', {}) if isinstance(solver_cfg, dict) else {}
    if interp_cfg is not None and not isinstance(interp_cfg, dict):
        errors.append(f"  {solver_path}: 'interpolation' must be a mapping when provided.")
    elif isinstance(interp_cfg, dict) and 'method' in interp_cfg:
        try:
            interp_code = normalize_interpolation_method(interp_cfg['method'])
        except ValueError as e:
            errors.append(f"  {solver_path}: {e}")
        else:
            # FaceFlux reads the face fluxes; the analytical types other than UNIFORM_FLOW set Ucat only.
            op_mode = solver_cfg.get('operation_mode') if isinstance(solver_cfg.get('operation_mode'), dict) else {}
            if (interp_code == 2 and str(op_mode.get('eulerian_field_source', 'solve')).strip().lower() == 'analytical'
                    and str(op_mode.get('analytical_type', 'TGV3D')).strip().upper() != 'UNIFORM_FLOW'):
                errors.append(
                    f"  {solver_path}: interpolation.method 'FaceFlux' needs the face fluxes the flow is "
                    f"built from, which analytical type '{op_mode.get('analytical_type', 'TGV3D')}' does not set; "
                    "use 'Trilinear', or the UNIFORM_FLOW analytical type.")
 
    # --- monitor.yml: basic structure ---
    if not isinstance(monitor_cfg, dict) or not monitor_cfg:
        errors.append(f"  {monitor_path}: monitor config is empty or not a valid YAML mapping.")
    else:
        io_cfg = monitor_cfg.get('io', {})
        freq = io_cfg.get('data_output_frequency')
        if freq is not None and (not isinstance(freq, int) or freq <= 0):
            errors.append(f"  {monitor_path}: 'io.data_output_frequency' must be a positive integer (got {freq}).")
        for key in ('write_initial_checkpoint', 'write_final_checkpoint'):
            if key in io_cfg and not isinstance(io_cfg[key], bool):
                errors.append(f"  {monitor_path}: 'io.{key}' must be true or false (got {io_cfg[key]!r}).")
        try:
            physics_cfg = (case_cfg.get('models') or {}).get('physics') if isinstance(case_cfg, dict) and isinstance(case_cfg.get('models') or {}, dict) else None
            particles_cfg = physics_cfg.get('particles') if isinstance(physics_cfg, dict) else None
            particle_count = particles_cfg.get('count', 0) if isinstance(particles_cfg, dict) else 0
            if resolve_traced_particle_ids(monitor_cfg) and not particle_count:
                errors.append(f"  {monitor_path}: 'logging.trace_particles' needs particles; "
                              "models.physics.particles.count is 0.")
        except ValueError as e:
            errors.append(f"  {monitor_path}: {e}")
        particle_console_freq = io_cfg.get('particle_console_output_frequency')
        if particle_console_freq is not None and (not isinstance(particle_console_freq, int) or particle_console_freq < 0):
            errors.append(
                f"  {monitor_path}: 'io.particle_console_output_frequency' must be a non-negative integer "
                f"(got {particle_console_freq})."
            )
        containment_errors, containment_warnings = validate_run_directory_containment(
            monitor_cfg, monitor_path
        )
        errors.extend(containment_errors)
        warnings.extend(containment_warnings)
        errors.extend(validate_reserved_directory_flags(
            monitor_cfg, monitor_path, "monitor passthrough"))
        try:
            resolve_profiling_config(monitor_cfg)
        except ValueError as e:
            errors.append(f"  {monitor_path}: {e}")
        try:
            resolve_diagnostics_config(monitor_cfg)
        except ValueError as e:
            errors.append(f"  {monitor_path}: {e}")
        try:
            resolve_solver_monitoring_flags(monitor_cfg)
        except ValueError as e:
            errors.append(f"  {monitor_path}: {e}")
        try:
            normalize_solution_monitoring_config(monitor_cfg)
        except ValueError as e:
            errors.append(f"  {monitor_path}: {e}")
        statistics_console_freq = io_cfg.get('statistics_console_output_frequency')
        if statistics_console_freq is not None and (
                not isinstance(statistics_console_freq, int)
                or isinstance(statistics_console_freq, bool)
                or statistics_console_freq < 0):
            errors.append(
                f"  {monitor_path}: 'io.statistics_console_output_frequency' must be a non-negative "
                f"integer (got {statistics_console_freq})."
            )
        try:
            normalize_field_statistics_config(monitor_cfg, case_cfg)
        except ValueError as e:
            errors.append(f"  {monitor_path}: {e}")
 
    if not errors and not restart_source_given:
        if needs_restart_source(case_cfg, solver_cfg):
            warnings.append(
                f"{case_path}: This configuration requires restart data (start_step > 0, "
                "eulerian_field_source='load', or particle restart_mode='load'). "
                "Use --restart-from or --continue when running."
            )
 
    if errors:
        _print_validation_errors(errors)
    for warning in warnings:
        print(f"[WARNING] {warning}", file=sys.stderr)
 
 
def check_post_checkpoint_cadence_alignment(post_cfg: dict, monitor_cfg: dict, post_path: str,
                                            monitor_path: str = "monitor.yml") -> "tuple[list, list]":
    """!
    @brief Report post step selections that cannot land on a committed checkpoint.
 
    @details The post-processor reads committed bundles, and the solver commits one
             every `io.data_output_frequency` completed steps. A `step_interval` that
             is not a multiple of that cadence therefore asks for steps that were
             never written: those steps wait forever for a checkpoint, and far less
             than the recipe requested is processed. That is only
             discovered after a solve has already run, so it is caught here instead.
 
             The solver also commits the initial and final states off cadence, which
             is why a misaligned `start_step` is a warning rather than an error: it
             may legitimately be the run's initial or final step. A bounded selection
             containing only one checkpoint has no stride to align; its interval must
             still be positive. Multi-checkpoint selections retain the cadence check.
 
    @param[in] post_cfg     Parsed post-processing configuration.
    @param[in] monitor_cfg  Parsed monitor configuration governing the source run.
    @param[in] post_path    Path to the post file, for error messages.
    @param[in] monitor_path Path to the monitor file, for error messages.
    @return `(errors, warnings)`, each a list of message strings. Both are empty when
            the comparison cannot be made, because the inputs that would make it
            meaningful are validated and reported elsewhere.
    """
    errors = []
    warnings = []
    if not isinstance(post_cfg, dict) or not isinstance(monitor_cfg, dict):
        return errors, warnings
 
    io_cfg = monitor_cfg.get("io") or {}
    if not isinstance(io_cfg, dict):
        return errors, warnings
    try:
        cadence = int(io_cfg["data_output_frequency"])
    except (KeyError, TypeError, ValueError):
        # A missing or malformed cadence is reported by the monitor's own checks.
        return errors, warnings
    # A disabled cadence commits only the initial and final states, so there is no
    # stride to align to.
    if cadence <= 0:
        return errors, warnings
 
    try:
        start_step, end_step, step_interval = resolve_post_requested_window(post_cfg)
    except (TypeError, ValueError):
        # Reported by the run_control checks, which run against the same values.
        return errors, warnings
 
    single_checkpoint = end_step >= start_step and end_step - start_step < step_interval
    if not single_checkpoint and step_interval % cadence != 0:
        suggestion = max(cadence, (step_interval // cadence) * cadence)
        errors.append(
            f"  {post_path}: 'run_control.step_interval' is {step_interval}, which is not a "
            f"multiple of 'io.data_output_frequency' ({cadence}) in {monitor_path}. The solver "
            f"only commits a checkpoint every {cadence} steps, so most requested steps were "
            f"never written and post-processing would stop at the first missing one. Use "
            f"{suggestion}, or another multiple of {cadence}, or lower the monitor cadence."
        )
 
    if start_step > 0 and start_step % cadence != 0:
        warnings.append(
            f"{post_path}: 'run_control.start_step' is {start_step}, which is not a multiple of "
            f"'io.data_output_frequency' ({cadence}) in {monitor_path}. That step only exists if "
            f"it is the run's initial or final step, which is committed off cadence."
        )
 
    return errors, warnings
 
 
def validate_post_config(post_cfg: dict, post_path: str, monitor_cfg: dict = None, case_cfg: dict = None):
    """!
    @brief Validates the post-processing config before running the post-processor.
    @param[in] post_cfg  Parsed post-processing YAML dictionary.
    @param[in] post_path Path to post file (for error messages).
    @param[in] monitor_cfg Parsed monitor configuration, when available. Two checks
                           span both files: field statistics, where post.yml names
                           the windows and monitor.yml decides what each accumulates,
                           and step cadence, where monitor.yml decides which steps
                           exist to be read. Both run only when the monitor is known.
    @param[in] case_cfg Parsed case configuration, when available. Spectra
                        preconditions need the boundary conditions and block count, so
                        they are checked only when the case is known; validating a
                        recipe on its own still checks it on its own terms.
    @throws SystemExit on validation failure.
    """
    errors = []
    warnings = []
 
    _validate_yaml_schema_keys(post_cfg, _POST_SCHEMA, post_path, errors)
 
    try:
        recipe = normalize_post_field_statistics_config(post_cfg)
    except ValueError as e:
        recipe = None
        errors.append(f"  {post_path}: {e}")
 
    try:
        spectra_recipe = normalize_post_spectra_config(post_cfg)
    except ValueError as e:
        spectra_recipe = None
        errors.append(f"  {post_path}: {e}")
    if recipe is not None:
        try:
            normalize_post_reducers_config(post_cfg)
        except ValueError as e:
            errors.append(f"  {post_path}: {e}")
    if spectra_recipe and spectra_recipe["tasks"] and case_cfg is not None:
        errors.extend(validate_post_spectra_preconditions(spectra_recipe, case_cfg, post_path))
    if recipe and recipe["windows"] and monitor_cfg is not None:
        try:
            configured = normalize_field_statistics_config(monitor_cfg)
        except ValueError:
            # The monitor file reports its own errors; do not repeat them here.
            configured = None
        if configured is not None:
            if not configured["enabled"]:
                errors.append(
                    f"  {post_path}: field statistics are requested, but "
                    "'field_statistics.enabled' is not set in the monitor configuration, so no "
                    "window is accumulated."
                )
            else:
                by_name = {window["name"]: window for window in configured["windows"]}
                for name in recipe["windows"]:
                    if name not in by_name:
                        errors.append(
                            f"  {post_path}: field-statistics window '{name}' is not defined in "
                            f"the monitor configuration. Defined windows: {sorted(by_name)}."
                        )
                    elif _post_window_derived_field_count(by_name[name], recipe["outputs"]) == 0:
                        errors.append(
                            f"  {post_path}: outputs {recipe['outputs']} produce no field for "
                            f"window '{name}'; it accumulates none of the state they need. Add "
                            "'second' to a field's moments for stresses, RMS, or turbulent "
                            "kinetic energy, or a covariance for a flux."
                        )
 
    for ensemble in (recipe or {}).get("ensembles", []):
        eligible = _ensemble_source_fields(ensemble["source"])
        if _post_window_derived_field_count(ensemble, recipe["outputs"], eligible) == 0:
            errors.append(
                f"  {post_path}: outputs {recipe['outputs']} produce no field for ensemble "
                f"'{ensemble['name']}'; add 'second' to a field's moments or a covariance."
            )
        if case_cfg is not None:
            requirements = {eligible[entry["field"]]["requires"] for entry in ensemble["fields"]}
            for requirement in sorted(r for r in requirements if r):
                if not _statistics_subsystem_available(case_cfg, requirement):
                    errors.append(
                        f"  {post_path}: ensemble '{ensemble['name']}' needs the '{requirement}' "
                        "subsystem, which is not enabled for this case."
                    )
 
    if not isinstance(post_cfg, dict) or not post_cfg:
        errors.append(f"  {post_path}: post-processing config is empty or not a valid YAML mapping.")
        _print_validation_errors(errors)
 
    # --- run_control ---
    if 'run_control' not in post_cfg:
        errors.append(f"  {post_path}: missing required section 'run_control'.")
    else:
        rc = post_cfg.get('run_control', {})
        if not isinstance(rc, dict):
            errors.append(f"  {post_path}: 'run_control' must be a mapping.")
        else:
            for canonical_key, aliases in POST_RUN_CONTROL_ALIASES.items():
                if not any(alias in rc for alias in aliases):
                    alias_list = "', '".join(aliases)
                    errors.append(
                        f"  {post_path}: missing required key 'run_control.{canonical_key}' "
                        f"(accepted aliases: '{alias_list}')."
                    )
                    continue
                raw_value = _mapping_value_with_aliases(rc, *aliases)
                try:
                    value = int(raw_value)
                    if canonical_key == "step_interval" and value <= 0:
                        errors.append(f"  {post_path}: 'run_control.step_interval' must be positive.")
                except (TypeError, ValueError):
                    alias_name = next((alias for alias in aliases if alias in rc), canonical_key)
                    errors.append(
                        f"  {post_path}: 'run_control.{alias_name}' must be an integer-compatible value."
                    )
 
    # --- io section ---
    io_cfg = post_cfg.get('io', {})
    source_cfg = post_cfg.get('source_data')
    if source_cfg is not None and not isinstance(source_cfg, dict):
        errors.append(f"  {post_path}: 'source_data' must be a mapping when provided.")
    global_ops = post_cfg.get('global_operations')
    if global_ops is not None:
        if not isinstance(global_ops, dict):
            errors.append(f"  {post_path}: 'global_operations' must be a mapping when provided.")
        elif 'dimensionalize' in global_ops and not isinstance(global_ops.get('dimensionalize'), bool):
            errors.append(f"  {post_path}: 'global_operations.dimensionalize' must be a boolean.")
    if not io_cfg:
        errors.append(f"  {post_path}: missing required section 'io'.")
    elif not isinstance(io_cfg, dict):
        errors.append(f"  {post_path}: 'io' must be a mapping.")
    else:
        for k in ['output_filename_prefix']:
            if k not in io_cfg:
                errors.append(f"  {post_path}: missing required key 'io.{k}'.")
        for key_name in ('output_directory', 'output_filename_prefix', 'particle_filename_prefix'):
            if key_name in io_cfg and not isinstance(io_cfg.get(key_name), str):
                errors.append(f"  {post_path}: 'io.{key_name}' must be a string when provided.")
        # The conductor files every post artifact by recipe identity, which excludes
        # this key, so two recipes differing only in it write over each other.
        if 'output_directory' in io_cfg:
            warnings.append(
                f"{post_path}: 'io.output_directory' is ignored; post output goes to the run's "
                "visualization and analysis directories under the recipe's identity, so recipes "
                "differing only in this key share one home and overwrite each other. Change "
                "'io.output_filename_prefix' to keep them apart."
            )
        if 'output_particles' in io_cfg and not isinstance(io_cfg.get('output_particles'), bool):
            errors.append(f"  {post_path}: 'io.output_particles' must be a boolean when provided.")
        try:
            normalize_post_paraview_series_config(post_cfg)
        except ValueError as exc:
            errors.append(f"  {post_path}: {exc}")
        particle_subsampling_frequency = io_cfg.get('particle_subsampling_frequency')
        if particle_subsampling_frequency is not None:
            if not isinstance(particle_subsampling_frequency, int) or particle_subsampling_frequency <= 0:
                errors.append(
                    f"  {post_path}: 'io.particle_subsampling_frequency' must be a positive integer when provided."
                )
        input_extensions = io_cfg.get('input_extensions')
        source_input_extensions = get_post_source_data(post_cfg).get('input_extensions')
        if input_extensions is not None:
            if not isinstance(input_extensions, dict):
                errors.append(f"  {post_path}: 'io.input_extensions' must be a mapping when provided.")
            else:
                for ext_key in ('eulerian', 'particle'):
                    ext_val = input_extensions.get(ext_key)
                    if ext_val is not None and not isinstance(ext_val, str):
                        errors.append(f"  {post_path}: 'io.input_extensions.{ext_key}' must be a string extension.")
                    elif ext_val is not None and str(ext_val).strip().lstrip('.').lower() != 'dat':
                        errors.append(
                            f"  {post_path}: 'io.input_extensions.{ext_key}' must be 'dat'; "
                            "committed checkpoint payload names are fixed."
                        )
        if source_input_extensions is not None:
            if not isinstance(source_input_extensions, dict):
                errors.append(f"  {post_path}: 'source_data.input_extensions' must be a mapping when provided.")
            else:
                for ext_key in ('eulerian', 'particle'):
                    ext_val = source_input_extensions.get(ext_key)
                    if ext_val is not None and not isinstance(ext_val, str):
                        errors.append(
                            f"  {post_path}: 'source_data.input_extensions.{ext_key}' must be a string extension."
                        )
                    elif ext_val is not None and str(ext_val).strip().lstrip('.').lower() != 'dat':
                        errors.append(
                            f"  {post_path}: 'source_data.input_extensions.{ext_key}' must be 'dat'; "
                            "committed checkpoint payload names are fixed."
                        )
 
        for list_key in ('eulerian_fields', 'particle_fields'):
            list_val = io_cfg.get(list_key)
            if list_val is not None and (not isinstance(list_val, list)
                                         or not all(isinstance(item, str) for item in list_val)):
                errors.append(f"  {post_path}: 'io.{list_key}' must be a list of field names when provided.")
        # The nodal_average inputs are computed at cell centres, and a .vts carries point data
        # only: the writer skips them, so a listed one would silently never reach the file.
        eulerian_fields = io_cfg.get('eulerian_fields')
        for cell_field in ('Ucat', 'P', 'Psi', 'Qcrit'):
            if isinstance(eulerian_fields, list) and cell_field in eulerian_fields:
                after = " after q_criterion" if cell_field == 'Qcrit' else ""
                errors.append(
                    f"  {post_path}: 'io.eulerian_fields' lists '{cell_field}', which is cell-centred and "
                    f"cannot be written as point data. Add a nodal_average task (input_field: {cell_field}, "
                    f"output_field: {cell_field}_nodal){after} and write '{cell_field}_nodal'."
                )
 
    # --- Check eulerian_pipeline entries have 'task' key ---
    eulerian_pipeline = post_cfg.get('eulerian_pipeline', [])
    if eulerian_pipeline is not None and not isinstance(eulerian_pipeline, list):
        errors.append(f"  {post_path}: 'eulerian_pipeline' must be a list when provided.")
        eulerian_pipeline = []
    for i, entry in enumerate(eulerian_pipeline):
        if not isinstance(entry, dict) or 'task' not in entry:
            errors.append(f"  {post_path}: 'eulerian_pipeline[{i}]' is missing the 'task' key. "
                          "Check YAML indentation (each entry needs '- task: ...' with proper spacing).")
            continue
        task_name = entry.get('task')
        if task_name == 'q_criterion':
            continue
        if task_name == 'nodal_average':
            in_field = entry.get('input_field')
            out_field = entry.get('output_field')
            if not isinstance(in_field, str) or not in_field.strip():
                errors.append(f"  {post_path}: 'eulerian_pipeline[{i}].input_field' must be a non-empty string.")
            if not isinstance(out_field, str) or not out_field.strip():
                errors.append(f"  {post_path}: 'eulerian_pipeline[{i}].output_field' must be a non-empty string.")
            if isinstance(in_field, str) and isinstance(out_field, str) and in_field == out_field:
                errors.append(
                    f"  {post_path}: 'eulerian_pipeline[{i}]' nodal_average input and output fields must differ."
                )
            continue
        if task_name == 'normalize_field':
            field = entry.get('field', 'P')
            if not isinstance(field, str) or not field.strip():
                errors.append(f"  {post_path}: 'eulerian_pipeline[{i}].field' must be a non-empty string.")
            elif field != 'P':
                errors.append(
                    f"  {post_path}: 'eulerian_pipeline[{i}].field' currently only supports 'P' "
                    f"(got '{field}')."
                )
            reference_point = entry.get('reference_point', [1, 1, 1])
            if not isinstance(reference_point, (list, tuple)) or len(reference_point) != 3:
                errors.append(
                    f"  {post_path}: 'eulerian_pipeline[{i}].reference_point' must be a 3-item list."
                )
            else:
                for rp_idx, coord in enumerate(reference_point):
                    try:
                        int(coord)
                    except (TypeError, ValueError):
                        errors.append(
                            f"  {post_path}: 'eulerian_pipeline[{i}].reference_point[{rp_idx}]' "
                            "must be integer-compatible."
                        )
            continue
        errors.append(
            f"  {post_path}: unsupported eulerian task '{task_name}' at eulerian_pipeline[{i}]. "
            f"Available tasks: {list(POST_EULERIAN_PIPELINE_TASKS)}."
        )
 
    # --- Check lagrangian_pipeline entries have 'task' key ---
    lagrangian_pipeline = post_cfg.get('lagrangian_pipeline', [])
    if lagrangian_pipeline is not None and not isinstance(lagrangian_pipeline, list):
        errors.append(f"  {post_path}: 'lagrangian_pipeline' must be a list when provided.")
        lagrangian_pipeline = []
    for i, entry in enumerate(lagrangian_pipeline):
        if not isinstance(entry, dict) or 'task' not in entry:
            errors.append(f"  {post_path}: 'lagrangian_pipeline[{i}]' is missing the 'task' key.")
            continue
        task_name = entry.get('task')
        if task_name == 'specific_ke':
            in_field = entry.get('input_field')
            out_field = entry.get('output_field')
            if not isinstance(in_field, str) or not in_field.strip():
                errors.append(f"  {post_path}: 'lagrangian_pipeline[{i}].input_field' must be a non-empty string.")
            if not isinstance(out_field, str) or not out_field.strip():
                errors.append(f"  {post_path}: 'lagrangian_pipeline[{i}].output_field' must be a non-empty string.")
            continue
        errors.append(
            f"  {post_path}: unsupported lagrangian task '{task_name}' at lagrangian_pipeline[{i}]."
        )
 
    # --- Check statistics pipeline entries ---
    stats_cfg = post_cfg.get('statistics_pipeline')
    stats_entries = []
    if stats_cfg is not None:
        if isinstance(stats_cfg, list):
            stats_entries = stats_cfg
        elif isinstance(stats_cfg, dict):
            stats_entries = stats_cfg.get('tasks', [])
            if not isinstance(stats_entries, list):
                errors.append(f"  {post_path}: 'statistics_pipeline.tasks' must be a list.")
            stats_output_prefix = stats_cfg.get('output_prefix')
            if stats_output_prefix is not None and not isinstance(stats_output_prefix, str):
                errors.append(f"  {post_path}: 'statistics_pipeline.output_prefix' must be a string.")
        else:
            errors.append(
                f"  {post_path}: 'statistics_pipeline' must be either a list of tasks or a mapping with a 'tasks' list."
            )
        for i, entry in enumerate(stats_entries):
            if isinstance(entry, str):
                task_name = entry
            elif isinstance(entry, dict) and 'task' in entry:
                task_name = entry.get('task')
            else:
                errors.append(
                    f"  {post_path}: statistics task entry {i} must be either a string or a mapping with key 'task'."
                )
                continue
            try:
                normalize_statistics_task(task_name)
            except ValueError as e:
                errors.append(f"  {post_path}: {e}")
 
    # MSD measures displacement from the configured point source, not from each
    # particle's own start. Any other seeding leaves that point unset - the coordinate
    # origin - and the statistic measures distance from the origin instead. With no
    # particles the task writes nothing, so only a seeded case is refused.
    if case_cfg is not None and "ComputeMSD" in get_post_statistics_task_tokens(post_cfg):
        particles_cfg = (((case_cfg.get('models') or {}).get('physics') or {}).get('particles') or {})
        try:
            particle_count = int(particles_cfg.get('count', 0) or 0)
        except (TypeError, ValueError):
            particle_count = 0
        init_mode = particles_cfg.get('init_mode', 'Surface')
        try:
            is_point_source = normalize_particle_init_mode(init_mode) == 2
        except ValueError:
            is_point_source = True  # the case file reports its own init_mode error
        if particle_count > 0 and not is_point_source:
            errors.append(
                f"  {post_path}: statistics task 'msd' measures displacement from "
                f"models.physics.particles.point_source, so it requires init_mode: PointSource "
                f"(the case seeds with '{init_mode}')."
            )
 
    legacy_stats_output_prefix = post_cfg.get('statistics_output_prefix')
    if legacy_stats_output_prefix is not None and not isinstance(legacy_stats_output_prefix, str):
        errors.append(f"  {post_path}: 'statistics_output_prefix' must be a string when provided.")
 
    # Runs last so it reports against values the run_control checks above have
    # already established are integers.
    cadence_errors, cadence_warnings = check_post_checkpoint_cadence_alignment(
        post_cfg, monitor_cfg, post_path)
    errors.extend(cadence_errors)
    warnings.extend(cadence_warnings)
 
    if errors:
        _print_validation_errors(errors)
    for warning in warnings:
        print(f"[WARNING] {warning}", file=sys.stderr)
 
def validate_cluster_config(cluster_cfg: dict, cluster_path: str):
    """!
    @brief Validate Slurm scheduler configuration from cluster.yml.
    @param[in] cluster_cfg Argument passed to `validate_cluster_config()`.
    @param[in] cluster_path Argument passed to `validate_cluster_config()`.
    """
    errors = []
    warnings = []
    _validate_yaml_schema_keys(cluster_cfg, _CLUSTER_SCHEMA, cluster_path, errors)
    if not isinstance(cluster_cfg, dict) or not cluster_cfg:
        errors.append(f"  {cluster_path}: cluster config is empty or not a valid YAML mapping.")
        _print_validation_errors(errors)
 
    scheduler = cluster_cfg.get("scheduler", {})
    if not isinstance(scheduler, dict):
        errors.append(f"  {cluster_path}: 'scheduler' must be a mapping.")
    else:
        scheduler_type = scheduler.get("type", "slurm")
        if str(scheduler_type).lower() != "slurm":
            errors.append(f"  {cluster_path}: scheduler.type must be 'slurm' in v1 (got '{scheduler_type}').")
 
    resources = cluster_cfg.get("resources", {})
    if not isinstance(resources, dict):
        errors.append(f"  {cluster_path}: 'resources' must be a mapping.")
    else:
        for req in ("account", "nodes", "ntasks_per_node", "mem", "time"):
            if req not in resources:
                errors.append(f"  {cluster_path}: missing required key 'resources.{req}'.")
        for int_key in ("nodes", "ntasks_per_node"):
            if int_key in resources:
                val = resources.get(int_key)
                if not isinstance(val, int) or val <= 0:
                    errors.append(f"  {cluster_path}: resources.{int_key} must be a positive integer (got {val}).")
        for str_key in ("account", "mem", "time", "partition"):
            if str_key in resources and resources.get(str_key) is not None:
                if not isinstance(resources.get(str_key), str):
                    errors.append(f"  {cluster_path}: resources.{str_key} must be a string when provided.")
        if isinstance(resources.get("time"), str):
            try:
                parse_slurm_time_limit_to_seconds(resources["time"])
            except ValueError as exc:
                errors.append(
                    f"  {cluster_path}: resources.time must be a supported finite Slurm time string ({exc})."
                )
        account = resources.get("account")
        if account == CLUSTER_TEMPLATE_PLACEHOLDER_ACCOUNT:
            warnings.append(
                f"{cluster_path}: resources.account still uses the sample placeholder "
                f"'{CLUSTER_TEMPLATE_PLACEHOLDER_ACCOUNT}'. Edit the cluster profile before submission."
            )
 
    notifications = cluster_cfg.get("notifications", {})
    if notifications is not None and not isinstance(notifications, dict):
        errors.append(f"  {cluster_path}: 'notifications' must be a mapping when provided.")
    elif isinstance(notifications, dict):
        mail_user = notifications.get("mail_user")
        if mail_user is not None and not is_valid_email(mail_user):
            errors.append(f"  {cluster_path}: notifications.mail_user is not a valid email '{mail_user}'.")
        if mail_user == CLUSTER_TEMPLATE_PLACEHOLDER_MAIL:
            warnings.append(
                f"{cluster_path}: notifications.mail_user still uses the sample placeholder "
                f"'{CLUSTER_TEMPLATE_PLACEHOLDER_MAIL}'. Edit the cluster profile before submission."
            )
        mail_type = notifications.get("mail_type")
        if mail_type is not None and not isinstance(mail_type, str):
            errors.append(f"  {cluster_path}: notifications.mail_type must be a string when provided.")
 
    execution = cluster_cfg.get("execution", {})
    if execution is not None and not isinstance(execution, dict):
        errors.append(f"  {cluster_path}: 'execution' must be a mapping when provided.")
    elif isinstance(execution, dict):
        module_setup = execution.get("module_setup", [])
        if module_setup is not None and not isinstance(module_setup, list):
            errors.append(f"  {cluster_path}: execution.module_setup must be a list of shell lines.")
        elif isinstance(module_setup, list):
            for i, line in enumerate(module_setup):
                if not isinstance(line, str):
                    errors.append(f"  {cluster_path}: execution.module_setup[{i}] must be a string.")
 
        launcher = execution.get("launcher")
        if launcher is not None and not isinstance(launcher, str):
            errors.append(f"  {cluster_path}: execution.launcher must be a string when provided.")
        launcher_args = execution.get("launcher_args")
        if launcher_args is not None and not isinstance(launcher_args, list):
            errors.append(f"  {cluster_path}: execution.launcher_args must be a list of CLI tokens.")
        elif isinstance(launcher_args, list):
            for i, token in enumerate(launcher_args):
                if not isinstance(token, (str, int, float)):
                    errors.append(f"  {cluster_path}: execution.launcher_args[{i}] must be a scalar CLI token.")
                elif _launcher_arg_contains_whitespace(token):
                    errors.append(
                        f"  {cluster_path}: execution.launcher_args[{i}] must be a single CLI token; "
                        "split whitespace-separated arguments into separate list items."
                    )
        if (launcher is None or isinstance(launcher, str)) and (launcher_args is None or isinstance(launcher_args, list)):
            try:
                normalize_cluster_launcher(execution)
            except ValueError as exc:
                errors.append(f"  {cluster_path}: {exc}.")
 
        extra_sbatch = execution.get("extra_sbatch")
        if extra_sbatch is not None and not isinstance(extra_sbatch, (dict, list)):
            errors.append(f"  {cluster_path}: execution.extra_sbatch must be a mapping or list when provided.")
 
        walltime_guard = execution.get("walltime_guard")
        if walltime_guard is not None and not isinstance(walltime_guard, dict):
            errors.append(f"  {cluster_path}: execution.walltime_guard must be a mapping when provided.")
        elif isinstance(walltime_guard, dict):
            enabled = walltime_guard.get("enabled")
            if enabled is not None and not isinstance(enabled, bool):
                errors.append(f"  {cluster_path}: execution.walltime_guard.enabled must be boolean when provided.")
 
            warmup_steps = walltime_guard.get("warmup_steps")
            if warmup_steps is not None and (not isinstance(warmup_steps, int) or isinstance(warmup_steps, bool) or warmup_steps <= 0):
                errors.append(
                    f"  {cluster_path}: execution.walltime_guard.warmup_steps must be a positive integer when provided."
                )
 
            multiplier = walltime_guard.get("multiplier")
            if multiplier is not None:
                if isinstance(multiplier, bool) or not isinstance(multiplier, (int, float)) or multiplier <= 0.0:
                    errors.append(
                        f"  {cluster_path}: execution.walltime_guard.multiplier must be a positive number when provided."
                    )
                elif float(multiplier) > 5.0:
                    errors.append(
                        f"  {cluster_path}: execution.walltime_guard.multiplier must be <= 5.0 (got {multiplier})."
                    )
 
            min_seconds = walltime_guard.get("min_seconds")
            if min_seconds is not None and (
                isinstance(min_seconds, bool) or not isinstance(min_seconds, (int, float)) or float(min_seconds) <= 0.0
            ):
                errors.append(
                    f"  {cluster_path}: execution.walltime_guard.min_seconds must be a positive number when provided."
                )
 
            estimator_alpha = walltime_guard.get("estimator_alpha")
            if estimator_alpha is not None:
                if isinstance(estimator_alpha, bool) or not isinstance(estimator_alpha, (int, float)):
                    errors.append(
                        f"  {cluster_path}: execution.walltime_guard.estimator_alpha must be a number in (0, 1] when provided."
                    )
                elif float(estimator_alpha) <= 0.0 or float(estimator_alpha) > 1.0:
                    errors.append(
                        f"  {cluster_path}: execution.walltime_guard.estimator_alpha must be in (0, 1] (got {estimator_alpha})."
                    )
 
    if warnings:
        for warning in warnings:
            print(f"[WARNING] {warning}", file=sys.stderr)
 
    if errors:
        _print_validation_errors(errors)
 
def validate_study_config(study_cfg: dict, study_path: str, skip_base_file_check: bool = False):
    """!
    @brief Validate sweep/study specification from study.yml.
    @param[in] study_cfg Argument passed to `validate_study_config()`.
    @param[in] study_path Argument passed to `validate_study_config()`.
    @param[in] skip_base_file_check When True, skip file-existence check for base_configs paths.
    """
    errors = []
    _validate_yaml_schema_keys(study_cfg, _STUDY_SCHEMA, study_path, errors)
    if not isinstance(study_cfg, dict) or not study_cfg:
        errors.append(f"  {study_path}: study config is empty or not a valid YAML mapping.")
        _print_validation_errors(errors)
 
    base_cfgs = study_cfg.get("base_configs")
    if not isinstance(base_cfgs, dict):
        errors.append(f"  {study_path}: missing required mapping 'base_configs'.")
    else:
        for req in ("case", "solver", "monitor", "post"):
            path_val = base_cfgs.get(req)
            if not path_val or not isinstance(path_val, str):
                errors.append(f"  {study_path}: base_configs.{req} must be a path string.")
            elif not skip_base_file_check:
                resolved = resolve_path(study_path, path_val)
                if not os.path.isfile(resolved):
                    errors.append(f"  {study_path}: base_configs.{req} does not exist: {resolved}")
 
    study_type = study_cfg.get("study_type")
    allowed_types = set(STUDY_TYPES)
    if study_type not in allowed_types:
        errors.append(
            f"  {study_path}: study_type must be one of {sorted(allowed_types)} (got '{study_type}')."
        )
 
    parameters = study_cfg.get("parameters")
    parameter_sets = study_cfg.get("parameter_sets")
    allowed_roots = {"case", "solver", "monitor", "post"}
    if bool(parameters) == bool(parameter_sets):
        errors.append(f"  {study_path}: provide exactly one of 'parameters' or 'parameter_sets'.")
    elif parameter_sets:
        if not isinstance(parameter_sets, list) or not parameter_sets:
            errors.append(f"  {study_path}: 'parameter_sets' must be a non-empty list of key->value mappings.")
        else:
            for set_index, param_set in enumerate(parameter_sets):
                if not isinstance(param_set, dict) or not param_set:
                    errors.append(
                        f"  {study_path}: parameter_sets[{set_index}] must be a non-empty mapping of key->value overrides."
                    )
                    continue
                for key, value in param_set.items():
                    if not isinstance(key, str) or "." not in key:
                        errors.append(
                            f"  {study_path}: parameter_sets[{set_index}] key '{key}' must use '<target>.<yaml.path>' format."
                        )
                        continue
                    root = key.split(".", 1)[0]
                    if root not in allowed_roots:
                        errors.append(
                            f"  {study_path}: parameter_sets[{set_index}] key '{key}' must start with one of {sorted(allowed_roots)}."
                        )
                    if isinstance(value, (dict, list)):
                        errors.append(
                            f"  {study_path}: parameter_sets[{set_index}] value for '{key}' must be a scalar, not {type(value).__name__}."
                        )
    else:
        if not isinstance(parameters, dict) or not parameters:
            errors.append(f"  {study_path}: 'parameters' must be a non-empty mapping of key->list.")
        else:
            for key, values in parameters.items():
                if not isinstance(key, str) or "." not in key:
                    errors.append(
                        f"  {study_path}: parameter key '{key}' must use '<target>.<yaml.path>' format."
                    )
                    continue
                root = key.split(".", 1)[0]
                if root not in allowed_roots:
                    errors.append(
                        f"  {study_path}: parameter key '{key}' must start with one of {sorted(allowed_roots)}."
                    )
                if not isinstance(values, list) or len(values) == 0:
                    errors.append(f"  {study_path}: parameters.{key} must be a non-empty list.")
 
    metrics = study_cfg.get("metrics", [])
    if metrics is not None and not isinstance(metrics, list):
        errors.append(f"  {study_path}: 'metrics' must be a list when provided.")
    elif isinstance(metrics, list):
        for i, metric in enumerate(metrics):
            if isinstance(metric, str):
                continue
            if not isinstance(metric, dict):
                errors.append(
                    f"  {study_path}: metrics[{i}] must be a string or mapping."
                )
                continue
            if "name" not in metric:
                errors.append(f"  {study_path}: metrics[{i}] missing required key 'name'.")
            if "source" not in metric:
                errors.append(f"  {study_path}: metrics[{i}] missing required key 'source'.")
            if str(metric.get("source", "")).strip().lower() in METRIC_SOURCE_KINDS[2:]:
                # extract_metric_from_log reads group(1); without it every case scores empty.
                regex = metric.get("regex")
                try:
                    has_group = isinstance(regex, str) and re.compile(regex).groups >= 1
                except re.error:
                    has_group = False
                if not has_group:
                    errors.append(
                        f"  {study_path}: metrics[{i}].regex must be a valid regular expression "
                        "with a capture group for the value when source is a log."
                    )
            for label_key in ("plot_label", "label", "units"):
                label_value = metric.get(label_key)
                if label_value is not None and (not isinstance(label_value, str) or not label_value.strip()):
                    errors.append(
                        f"  {study_path}: metrics[{i}].{label_key} must be a non-empty string when provided."
                    )
 
    plotting = study_cfg.get("plotting", {})
    if plotting is not None and not isinstance(plotting, dict):
        errors.append(f"  {study_path}: 'plotting' must be a mapping when provided.")
    elif isinstance(plotting, dict):
        enabled = plotting.get("enabled")
        if enabled is not None and not isinstance(enabled, bool):
            errors.append(f"  {study_path}: plotting.enabled must be boolean when provided.")
        output_format = plotting.get("output_format")
        if output_format is not None and output_format not in STUDY_PLOT_FORMATS:
            errors.append(f"  {study_path}: plotting.output_format must be one of ['png','pdf','svg'].")
 
    execution = study_cfg.get("execution", {})
    if execution is not None and not isinstance(execution, dict):
        errors.append(f"  {study_path}: 'execution' must be a mapping when provided.")
    elif isinstance(execution, dict):
        max_conc = execution.get("max_concurrent_array_tasks")
        if max_conc is not None and (not isinstance(max_conc, int) or max_conc <= 0):
            errors.append(
                f"  {study_path}: execution.max_concurrent_array_tasks must be a positive integer when provided."
            )
 
    if errors:
        _print_validation_errors(errors)
 
def _deep_set(container: dict, dotted_path: str, value):
    """!
    @brief Set nested dictionary value, creating intermediate maps when needed.
    @param[in] container Argument passed to `_deep_set()`.
    @param[in] dotted_path Argument passed to `_deep_set()`.
    @param[in] value Argument passed to `_deep_set()`.
    """
    keys = dotted_path.split(".")
    current = container
    for key in keys[:-1]:
        if key not in current or not isinstance(current[key], dict):
            current[key] = {}
        current = current[key]
    current[keys[-1]] = value
 
def expand_parameter_matrix(parameters: dict) -> list:
    """!
    @brief Expand study parameter lists into cartesian-product combinations.
    @param[in] parameters Argument passed to `expand_parameter_matrix()`.
    @return Value returned by `expand_parameter_matrix()`.
    """
    param_keys = list(parameters.keys())
    all_values = [parameters[k] for k in param_keys]
    combos = []
    for combo in itertools.product(*all_values):
        combos.append(dict(zip(param_keys, combo)))
    return combos
 
 
def expand_study_parameter_combinations(study_cfg: dict) -> list:
    """!
    @brief Expand either cartesian-study parameters or explicit parameter sets.
    @param[in] study_cfg Argument passed to `expand_study_parameter_combinations()`.
    @return Value returned by `expand_study_parameter_combinations()`.
    """
    parameter_sets = study_cfg.get("parameter_sets")
    if parameter_sets:
        return [dict(param_set) for param_set in parameter_sets]
    return expand_parameter_matrix(study_cfg.get("parameters") or {})
 
 
def flatten_study_parameters(parameters: dict) -> dict:
    """!
    @brief Flatten grouped study overrides into scalar dotted-path columns.
 
    @details A grouped override such as `case.run_control: {dt_physical: ...}`
             materializes correctly in case YAML but is not a useful CSV cell or
             plot coordinate. Flattening preserves the actual varied variables.
 
    @param[in] parameters One expanded study parameter combination.
    @return Flat dotted-path-to-scalar mapping.
    """
    flattened = {}
 
    def visit(prefix, value):
        """!
        @brief Recursively flatten one grouped override value.
        @param[in] prefix Current dotted parameter path.
        @param[in] value Scalar or nested mapping at the current path.
        """
        if isinstance(value, dict):
            for child, child_value in value.items():
                visit(f"{prefix}.{child}" if prefix else str(child), child_value)
        else:
            flattened[prefix] = value
 
    for key, value in (parameters or {}).items():
        visit(str(key), value)
    return flattened
 
 
def get_study_parameter_keys(study_cfg: dict) -> list:
    """!
    @brief Collect ordered parameter keys from either cross-product parameter expansions or explicit parameter sets.
    @param[in] study_cfg Argument passed to `get_study_parameter_keys()`.
    @return Value returned by `get_study_parameter_keys()`.
    """
    parameters = study_cfg.get("parameters")
    if isinstance(parameters, dict) and parameters:
        keys = []
        for key, candidates in parameters.items():
            candidate_dicts = [value for value in candidates if isinstance(value, dict)] if isinstance(candidates, list) else []
            expanded = []
            for value in candidate_dicts:
                for flat_key in flatten_study_parameters({key: value}):
                    if flat_key not in expanded:
                        expanded.append(flat_key)
            for flat_key in expanded or [key]:
                if flat_key not in keys:
                    keys.append(flat_key)
        return keys
 
    keys = []
    parameter_sets = study_cfg.get("parameter_sets") or []
    for param_set in parameter_sets:
        if not isinstance(param_set, dict):
            continue
        for key in flatten_study_parameters(param_set):
            if key not in keys:
                keys.append(key)
    return keys
 
 
def get_cluster_total_tasks(cluster_cfg: dict) -> int:
    """!
    @brief Return cluster total tasks.
    @param[in] cluster_cfg Argument passed to `get_cluster_total_tasks()`.
    @return Value returned by `get_cluster_total_tasks()`.
    """
    resources = cluster_cfg.get("resources", {})
    return int(resources.get("nodes", 1)) * int(resources.get("ntasks_per_node", 1))
 
def normalize_extension(ext: str) -> str:
    """!
    @brief Canonicalize a user-supplied filename extension by trimming whitespace and leading dots.
    @param[in] ext Argument passed to `normalize_extension()`.
    @return Value returned by `normalize_extension()`.
    """
    if ext is None:
        return None
    return str(ext).strip().lstrip(".")
 
def resolve_conductor_entry_point() -> list:
    """!
    @brief Resolve how to invoke this conductor again from a batch script.
 
    @details Prefers the `bin/picurv` wrapper, which selects the managed Python
             environment a cluster node needs, and falls back to the running
             interpreter with the package entry point when that wrapper is absent.
 
    @return Argv prefix that re-invokes the conductor.
    """
    wrapper = os.path.join(PACKAGE_PROJECT_ROOT, "bin", "picurv")
    if os.path.isfile(wrapper) and os.access(wrapper, os.X_OK):
        return [wrapper]
    return [sys.executable, os.path.join(PACKAGE_PROJECT_ROOT, "picurv_cli", "picurv")]
 
 
def build_spectra_follow_command(run_dir: str, post_path: str, post_cfg: dict,
                                 recompute: bool = False) -> list:
    """!
    @brief Build the batch-script step that measures spectra after the field stage.
 
    @details Spectra are a serial pass over committed checkpoints, so the command is
             returned bare rather than wrapped in the MPI launcher: run under `srun`
             with the post stage's task count it would become one identical copy per
             task, each writing the same files.
 
    @param[in] run_dir Run directory the batch job operates on.
    @param[in] post_path Post recipe path, reachable from the compute node.
    @param[in] post_cfg Effective post configuration.
    @param[in] recompute Re-measure steps whose spectra are still valid.
    @return Argv list, or an empty list when the recipe requests no spectra.
    """
    try:
        spectra = normalize_post_spectra_config(post_cfg)
    except ValueError:
        # Validation reports recipe errors; do not raise a second time here.
        return []
    if not spectra["tasks"]:
        return []
    return resolve_conductor_entry_point() + [
        "run", "--post-process", "--only", "spectra",
        "--run-dir", os.path.abspath(run_dir),
        "--post", os.path.abspath(post_path),
    ] + (["--recompute"] if recompute else [])
 
 
def executable_petsc_library_dir(executable_path: str) -> "str | None":
    """!
    @brief The lib/ directory of the PETSc an executable was built against, from its stamp.
    @details Both PETSc index widths name their library libpetsc.so.MAJOR.MINOR, so the loader
             takes whichever comes first on LD_LIBRARY_PATH; launching with this directory first
             gives each executable its own PETSc whatever modules the job loaded.
    @param[in] executable_path Path to `simulator`, `postprocessor` or their 64-bit pair.
    @return Absolute directory, or None when the stamp does not name one.
    """
    petsc = read_binary_petsc_stamp(executable_path) if os.path.isfile(executable_path) else None
    if not petsc or not petsc.get("dir"):
        return None
    library_dir = os.path.join(petsc["dir"], petsc.get("arch") or "", "lib")
    return os.path.normpath(library_dir) if os.path.isdir(library_dir) else None
 
 
def petsc_library_path_lines(library_dir: "str | None") -> list:
    """!
    @brief Shell lines putting one PETSc's lib/ first on LD_LIBRARY_PATH, after module setup.
    @param[in] library_dir From `executable_petsc_library_dir()`, or None for no change.
    @return Script lines.
    """
    if not library_dir:
        return []
    return [f'export LD_LIBRARY_PATH={shlex.quote(library_dir)}"${{LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}}"']
 
 
def executable_identity_check_lines(executable: str, expected_version_line: "str | None",
                                    pinned: bool = False) -> list:
    """!
    @brief Shell lines that compare an executable's reported identity with the staged one.
 
    @details A job resolves its executable when it starts, which can be long after it
             was staged. The installation's `bin/` may have been rebuilt in between, and
             a job that silently runs the new build produces checkpoints that disagree
             with the run's manifest. The lines run after module setup, because
             `--version` still needs the executable's shared libraries, and before the
             launcher, so a mismatch stops the job before any rank starts. When staging
             could not read an identity there is nothing to compare, so the reported one
             is only logged.
    @param[in] executable Executable path, emitted verbatim when it is a shell variable.
    @param[in] expected_version_line Exact `--version` output captured at staging, or None.
    @param[in] pinned Whether the executable is the run's own pinned copy.
    @return Script lines.
    """
    token = executable if executable.startswith("$") else shlex.quote(executable)
    lines = [
        f'PICURV_EXECUTABLE_IDENTITY=$({token} --version 2>&1) || {{ '
        f'echo "[FATAL] {executable} --version failed: ${{PICURV_EXECUTABLE_IDENTITY}}" >&2; exit 1; }}',
        'echo "[$(date)] Executable identity: ${PICURV_EXECUTABLE_IDENTITY}"',
    ]
    if not expected_version_line:
        lines.append('echo "[$(date)] No identity was readable at staging, so none is compared."')
        return lines
    remedy = (
        "The run's pinned copy was replaced after staging; restore it or re-pin the run."
        if pinned else
        "It was rebuilt after staging; restage the job, or stage with --pin-executables so "
        "the run keeps its own copy."
    )
    lines.extend([
        f"PICURV_STAGED_IDENTITY={shlex.quote(expected_version_line)}",
        'if [ "${PICURV_EXECUTABLE_IDENTITY}" != "${PICURV_STAGED_IDENTITY}" ]; then',
        f'  echo "[FATAL] {executable} reports ${{PICURV_EXECUTABLE_IDENTITY}}, but this job was '
        f'staged against ${{PICURV_STAGED_IDENTITY}}. {remedy}" >&2',
        "  exit 1",
        "fi",
    ])
    return lines
 
 
def render_slurm_script(
    script_path: str,
    job_name: str,
    cluster_cfg: dict,
    command: list,
    workdir: str,
    stdout_path: str,
    stderr_path: str = None,
    env_vars: dict = None,
    shell_env_vars: dict = None,
    array_spec: str = None,
    follow_commands: list = None,
    identity_check: "tuple | None" = None,
):
    """!
    @brief Render a Slurm batch script for a single command.
    @param[in] script_path Argument passed to `render_slurm_script()`.
    @param[in] job_name Argument passed to `render_slurm_script()`.
    @param[in] cluster_cfg Argument passed to `render_slurm_script()`.
    @param[in] command Argument passed to `render_slurm_script()`.
    @param[in] workdir Argument passed to `render_slurm_script()`.
    @param[in] stdout_path Argument passed to `render_slurm_script()`.
    @param[in] stderr_path Argument passed to `render_slurm_script()`.
    @param[in] env_vars Argument passed to `render_slurm_script()`.
    @param[in] shell_env_vars Argument passed to `render_slurm_script()`.
    @param[in] array_spec Argument passed to `render_slurm_script()`.
    @param[in] follow_commands Commands to run after the launched one, each an argv
                               list. They run in the batch shell rather than under the
                               MPI launcher, so a serial step does not become one copy
                               per task. Supplying any of them drops the `exec`.
    @param[in] identity_check `(executable, expected --version line, pinned)` checked
                              before launch; see `executable_identity_check_lines()`.
    """
    resources = cluster_cfg.get("resources", {})
    notifications = cluster_cfg.get("notifications", {}) or {}
    execution = cluster_cfg.get("execution", {}) or {}
    extra_sbatch = execution.get("extra_sbatch")
    module_setup = execution.get("module_setup", []) or []
 
    if stderr_path is None:
        stderr_path = stdout_path.replace(".out", ".err")
 
    lines = [
        "#!/bin/bash",
        f"#SBATCH --job-name={job_name}",
        f"#SBATCH --nodes={resources['nodes']}",
        f"#SBATCH --ntasks-per-node={resources['ntasks_per_node']}",
        f"#SBATCH --mem={resources['mem']}",
        f"#SBATCH --time={resources['time']}",
        f"#SBATCH --output={stdout_path}",
        f"#SBATCH --error={stderr_path}",
        f"#SBATCH --account={resources['account']}",
    ]
    partition = resources.get("partition")
    if partition:
        lines.append(f"#SBATCH --partition={partition}")
    if array_spec:
        lines.append(f"#SBATCH --array={array_spec}")
    mail_user = notifications.get("mail_user")
    mail_type = notifications.get("mail_type")
    if mail_user:
        lines.append(f"#SBATCH --mail-user={mail_user}")
    if mail_type:
        lines.append(f"#SBATCH --mail-type={mail_type}")
 
    if isinstance(extra_sbatch, dict):
        for key, value in extra_sbatch.items():
            flag = str(key)
            if not flag.startswith("--"):
                flag = f"--{flag}"
            if isinstance(value, bool):
                if value:
                    lines.append(f"#SBATCH {flag}")
            elif value is not None:
                lines.append(f"#SBATCH {flag}={value}")
    elif isinstance(extra_sbatch, list):
        for token in extra_sbatch:
            lines.append(f"#SBATCH {token}")
 
    lines.extend(
        [
            "",
            "set -euo pipefail",
            "",
            f"cd {shlex.quote(workdir)}",
            'echo "[$(date)] Starting job ${SLURM_JOB_NAME} (${SLURM_JOB_ID})"',
            'echo "[$(date)] Working directory: $PWD"',
        ]
    )
 
    if shell_env_vars:
        for key, value in shell_env_vars.items():
            lines.append(f"export {key}={value}")
 
    for setup_line in module_setup:
        lines.append(str(setup_line))
 
    if env_vars:
        for key, value in env_vars.items():
            lines.append(f"export {key}={shlex.quote(str(value))}")
 
    if identity_check:
        lines.extend(petsc_library_path_lines(executable_petsc_library_dir(identity_check[0])))
        lines.extend(executable_identity_check_lines(*identity_check))
 
    cmd = " ".join(shlex.quote(str(tok)) for tok in command)
    if follow_commands:
        # `exec` would replace the shell and the trailing commands would never run.
        # `set -e` is already in effect, so a failure in the launched command aborts
        # the job before anything downstream of it executes.
        lines.append(cmd)
        for follow in follow_commands:
            lines.append(" ".join(shlex.quote(str(tok)) for tok in follow))
    else:
        lines.append(f"exec {cmd}")
 
    os.makedirs(os.path.dirname(script_path), exist_ok=True)
    with open(script_path, "w") as f:
        f.write("\n".join(lines) + "\n")
    os.chmod(script_path, 0o755)
 
def split_launcher_tokens(
    launcher: "str | None",
    launcher_args: "list | None" = None,
    label: str = "launcher",
) -> "tuple[str | None, list[str]]":
    """!
    @brief Canonicalize launcher config into executable token plus argv-style flags.
    @param[in] launcher Argument passed to `split_launcher_tokens()`.
    @param[in] launcher_args Argument passed to `split_launcher_tokens()`.
    @param[in] label Argument passed to `split_launcher_tokens()`.
    @return Value returned by `split_launcher_tokens()`.
    """
    normalized_args = [str(x) for x in (launcher_args or [])]
 
    if launcher is None:
        return None, normalized_args
 
    try:
        launcher_tokens = shlex.split(str(launcher))
    except ValueError as exc:
        raise ValueError(f"{label} is not shell-parseable: {exc}") from exc
 
    if not launcher_tokens:
        return None, normalized_args
 
    return launcher_tokens[0], launcher_tokens[1:] + normalized_args
 
 
def normalize_cluster_launcher(execution: dict) -> "tuple[str | None, list[str]]":
    """!
    @brief Canonicalize cluster launcher config into executable token plus argv-style flags.
    @param[in] execution Argument passed to `normalize_cluster_launcher()`.
    @return Value returned by `normalize_cluster_launcher()`.
    """
    return split_launcher_tokens(
        execution.get("launcher"),
        execution.get("launcher_args") or [],
        label="execution.launcher",
    )
 
 
def strip_launcher_size_flags(launcher_name: str, launcher_args: "list[str]") -> "list[str]":
    """!
    @brief Remove explicit MPI task-count flags from known launchers.
    @param[in] launcher_name Basename-normalized launcher executable.
    @param[in] launcher_args Launcher argument list.
    @return Filtered launcher arguments with explicit size flags removed.
    """
    filtered = []
    idx = 0
    while idx < len(launcher_args):
        token = str(launcher_args[idx])
 
        if launcher_name == "srun":
            if token in {"-n", "--ntasks"}:
                idx += 2
                continue
            if token.startswith("--ntasks="):
                idx += 1
                continue
        elif launcher_name in {"mpiexec", "mpirun"}:
            if token in {"-n", "-np"}:
                idx += 2
                continue
            if token.startswith("-n=") or token.startswith("-np="):
                idx += 1
                continue
 
        filtered.append(token)
        idx += 1
 
    return filtered
 
 
def build_local_launch_command(
    executable: str,
    executable_args: list,
    num_procs: int,
    config_search_anchor: str = None,
    allow_single_rank_launcher_override: bool = False,
    force_num_procs: "int | None" = None,
) -> list:
    """!
    @brief Build local launcher command, allowing env or shared config overrides for login-node MPI quirks.
    @param[in] executable Argument passed to `build_local_launch_command()`.
    @param[in] executable_args Argument passed to `build_local_launch_command()`.
    @param[in] num_procs Argument passed to `build_local_launch_command()`.
    @param[in] config_search_anchor Argument passed to `build_local_launch_command()`.
    @param[in] allow_single_rank_launcher_override When true, explicit launcher overrides also apply to 1-rank commands.
    @param[in] force_num_procs Optional explicit MPI rank count override applied after stripping conflicting launcher size flags.
    @return Value returned by `build_local_launch_command()`.
    """
    target_num_procs = force_num_procs if force_num_procs is not None else num_procs
    command = [executable] + executable_args
    if target_num_procs <= 1 and not allow_single_rank_launcher_override:
        return command
 
    launcher_override = os.environ.get("PICURV_MPI_LAUNCHER")
    if launcher_override is None:
        launcher_override = os.environ.get("MPI_LAUNCHER")
 
    try:
        if launcher_override is not None:
            explicit_launcher_config = True
            launcher, launcher_args = split_launcher_tokens(
                launcher_override,
                label="local MPI launcher override",
            )
        else:
            _, runtime_execution_cfg = load_runtime_execution_config(config_search_anchor)
            local_execution = resolve_runtime_execution_context(runtime_execution_cfg, "local")
            configured_launcher = local_execution.get("launcher")
            configured_args = local_execution.get("launcher_args") or []
            explicit_launcher_config = configured_launcher is not None or bool(configured_args)
            if target_num_procs <= 1 and not explicit_launcher_config:
                return command
            launcher, launcher_args = split_launcher_tokens(
                configured_launcher if configured_launcher is not None else "mpiexec",
                configured_args,
                label="local_execution.launcher",
            )
    except ValueError as exc:
        print(f"[FATAL] {exc}", file=sys.stderr)
        sys.exit(1)
 
    if not launcher:
        return command
 
    launcher_name = os.path.basename(launcher).lower()
    if force_num_procs is not None:
        launcher_args = strip_launcher_size_flags(launcher_name, launcher_args)
    prefix = [launcher] + launcher_args
 
    if launcher_name == "srun":
        has_n = any(token in {"-n", "--ntasks"} for token in launcher_args)
        if not has_n:
            prefix += ["-n", str(target_num_procs)]
    elif launcher_name in {"mpiexec", "mpirun"}:
        has_n = any(token in {"-n", "-np"} for token in launcher_args)
        if not has_n:
            prefix += ["-n", str(target_num_procs)]
 
    return prefix + command
 
def restart_grid_inputs(run_dir: str, case_cfg: dict) -> dict:
    """!
    @brief The inputs a run's geometry is derived from, to compare across a restart.
    @details The solver compares the checkpoint's geometry, which it hashes from the built
             grid, only after the job has started. These inputs determine that geometry
             within one build, so a difference is worth saying at staging: a staged
             `inputs/grid/grid.run` (file and generated grids, already non-dimensional)
             by content, otherwise the grid section without its rank layout and the
             length scale; and the periodic faces of every block.
    @param[in] run_dir Run whose staged grid is read.
    @param[in] case_cfg That run's case configuration.
    @return Mapping of input name to a comparable value.
    """
    staged = os.path.join(run_dir, "inputs", "grid", "grid.run")
    grid = {key: value for key, value in (case_cfg.get("grid") or {}).items()
            if not str(key).startswith("da_processors_")}
    try:
        periodic = [sorted(bc["face"] for bc in block if bc["type"] == "PERIODIC")
                    for block in validate_and_prepare_boundary_conditions(case_cfg)]
    except (ValueError, KeyError, TypeError):
        periodic = None
    inputs = {"periodic faces": periodic}
    if os.path.isfile(staged):
        inputs["grid file"] = _file_sha256(staged)
    else:
        inputs["grid"] = grid
        inputs["length_ref"] = ((case_cfg.get("properties") or {}).get("scaling") or {}).get("length_ref")
    return inputs
 
 
def warn_on_restart_grid_change(source_inputs: dict, branch_inputs: dict):
    """!
    @brief Warn at staging when a restart's grid inputs differ from its source run's.
    @param[in] source_inputs restart_grid_inputs() of the run that wrote the checkpoint.
    @param[in] branch_inputs restart_grid_inputs() of the staged restart.
    @return Names of the inputs that differ.
    """
    changed = sorted(name for name in set(source_inputs) | set(branch_inputs)
                     if source_inputs.get(name) != branch_inputs.get(name))
    if changed:
        print(f"[WARNING] This restart's grid inputs differ from the source run's ({', '.join(changed)}). "
              "The solver refuses a checkpoint whose geometry differs, but only once the job has "
              "started and built the grid.", file=sys.stderr)
    return changed
 
 
def check_restart_continuation(solver_exe: str, solver_args: list, run_dir: str,
                               config_search_anchor: str = None):
    """!
    @brief Ask the simulator whether a staged restart's carried statistics windows can continue.
    @details Runs the simulator's restart check on one rank. It parses the run's control
             file and compares each window with the source checkpoint's manifest exactly
             as the restart will, but builds no grid, so it costs about a second and runs
             on a login node whatever the production rank count. Passing it does not
             replace the full check at solver start, which also compares geometry.
    @param[in] solver_exe Simulator executable the run will launch.
    @param[in] solver_args Simulator arguments the run will launch with.
    @param[in] run_dir Staged run directory, the simulator's working directory.
    @param[in] config_search_anchor Path from which the local launcher configuration is found.
    @return None when the windows can continue, else the simulator's own reason.
    """
    command = build_local_launch_command(
        solver_exe, solver_args + ["-restart_check_only", "true"], 1,
        config_search_anchor=config_search_anchor,
        allow_single_rank_launcher_override=True, force_num_procs=1,
    )
    result = _run_captured_command(command, run_dir)
    if result.returncode == 0:
        print("[INFO] Statistics continuation check passed.")
        return None
    # PETSc prints a banner, its generic error class, then the simulator's own message.
    messages = [line.split("PETSC ERROR:", 1)[1].strip()
                for line in (result.stdout + result.stderr).splitlines() if "PETSC ERROR:" in line]
    messages = [m for m in messages if m and not m.startswith("-")]
    return (messages[1] if len(messages) > 1 else messages[0] if messages
            else (result.stderr or result.stdout).strip() or f"exit status {result.returncode}")
 
 
def resolve_cluster_execution(cluster_cfg: dict, config_search_anchor: str = None, extra_search_anchors=None) -> dict:
    """!
    @brief Resolve cluster execution launcher settings from shared runtime config plus cluster.yml overrides.
    @param[in] cluster_cfg Argument passed to `resolve_cluster_execution()`.
    @param[in] config_search_anchor Argument passed to `resolve_cluster_execution()`.
    @param[in] extra_search_anchors Argument passed to `resolve_cluster_execution()`.
    @return Value returned by `resolve_cluster_execution()`.
    """
    _, runtime_execution_cfg = load_runtime_execution_config(config_search_anchor, extra_search_anchors=extra_search_anchors)
    shared_cluster_execution = resolve_runtime_execution_context(runtime_execution_cfg, "cluster")
    execution = cluster_cfg.get("execution", {}) or {}
    cluster_override = {
        "launcher": execution.get("launcher") if "launcher" in execution else None,
        "launcher_args": execution.get("launcher_args") if "launcher_args" in execution else None,
    }
    return merge_execution_overrides(shared_cluster_execution, cluster_override)
 
 
def build_cluster_launch_command(
    cluster_cfg: dict,
    executable: str,
    executable_args: list,
    config_search_anchor: str = None,
    extra_search_anchors=None,
    force_num_procs: "int | None" = None,
) -> list:
    """!
    @brief Build scheduler launcher command from cluster config plus optional shared execution defaults.
    @param[in] cluster_cfg Argument passed to `build_cluster_launch_command()`.
    @param[in] executable Argument passed to `build_cluster_launch_command()`.
    @param[in] executable_args Argument passed to `build_cluster_launch_command()`.
    @param[in] config_search_anchor Argument passed to `build_cluster_launch_command()`.
    @param[in] extra_search_anchors Argument passed to `build_cluster_launch_command()`.
    @param[in] force_num_procs Optional explicit MPI rank count override applied after stripping conflicting launcher size flags.
    @return Value returned by `build_cluster_launch_command()`.
    """
    try:
        execution = resolve_cluster_execution(
            cluster_cfg,
            config_search_anchor=config_search_anchor,
            extra_search_anchors=extra_search_anchors,
        )
        launcher, launcher_args = split_launcher_tokens(
            execution.get("launcher") if execution.get("launcher") is not None else "srun",
            execution.get("launcher_args") or [],
            label="cluster execution launcher",
        )
    except ValueError as exc:
        print(f"[FATAL] {exc}", file=sys.stderr)
        sys.exit(1)
 
    ntasks = int(force_num_procs) if force_num_procs is not None else get_cluster_total_tasks(cluster_cfg)
    launcher_name = launcher.lower() if launcher else ""
    if force_num_procs is not None:
        launcher_args = strip_launcher_size_flags(launcher_name, launcher_args)
 
    if launcher and launcher_name == "srun":
        has_n = any(token in {"-n", "--ntasks"} for token in launcher_args)
        cmd = ["srun"] + launcher_args
        if not has_n:
            cmd += ["-n", str(ntasks)]
        return cmd + [executable] + executable_args
 
    if launcher and launcher_name == "mpirun":
        has_np = any(token in {"-np", "-n"} for token in launcher_args)
        cmd = ["mpirun"] + launcher_args
        if not has_np:
            cmd += ["-np", str(ntasks)]
        return cmd + [executable] + executable_args
 
    if launcher and launcher_name == "mpiexec":
        has_np = any(token in {"-np", "-n"} for token in launcher_args)
        cmd = ["mpiexec"] + launcher_args
        if not has_np:
            cmd += ["-np", str(ntasks)]
        return cmd + [executable] + executable_args
 
    # Custom launcher or no launcher.
    cmd = []
    if launcher:
        cmd.append(str(launcher))
    cmd += launcher_args
    cmd += [executable] + executable_args
    return cmd
 
def parse_slurm_job_id(sbatch_output: str) -> str:
    """!
    @brief Extract numeric job id from standard sbatch output.
    @param[in] sbatch_output Argument passed to `parse_slurm_job_id()`.
    @return Value returned by `parse_slurm_job_id()`.
    """
    match = re.search(r"Submitted batch job\s+(\d+)", sbatch_output or "")
    return match.group(1) if match else None
 
#: Slurm end states after which an `afterok` dependency can never be satisfied.
_SLURM_FAILED_END_STATES = {
    "FAILED", "CANCELLED", "TIMEOUT", "OUT_OF_MEMORY", "NODE_FAIL", "PREEMPTED",
    "BOOT_FAIL", "DEADLINE",
}
 
 
def slurm_job_end_state(job_id: str) -> "tuple[str, str | None]":
    """!
    @brief Whether a recorded Slurm job (or array) is still queued, and how it ended if not.
    @details Slurm forgets a finished job after its MinJobAge, and a dependency on a job it
             no longer knows is rejected, so a stage submitted long after the job it waits
             for must not depend on it. `squeue` answers for live jobs; `sacct` for ended ones.
    @param[in] job_id Recorded job id; for an array, the array's id covers every task.
    @return `("active", state)`, `("completed", "COMPLETED")`, `("failed", state)`,
            `("unknown", state-or-None)` when the job is not queued but `sacct` cannot say how
            it ended, or `("unchecked", None)` where `squeue` is unavailable.
    """
    squeue = shutil.which("squeue")
    if not squeue:
        return "unchecked", None
    result = subprocess.run([squeue, "-h", "-j", str(job_id), "-o", "%T"],
                            text=True, capture_output=True, check=False)
    live = [line.strip() for line in (result.stdout or "").splitlines() if line.strip()]
    if result.returncode == 0 and live:
        return "active", live[0]
    sacct = shutil.which("sacct")
    if not sacct:
        return "unknown", None
    result = subprocess.run([sacct, "-n", "-X", "-P", "-j", str(job_id), "-o", "State"],
                            text=True, capture_output=True, check=False)
    # "CANCELLED by 123" carries the canceller; the state is the first word.
    states = [line.split()[0] for line in (result.stdout or "").splitlines() if line.strip()]
    if result.returncode != 0 or not states:
        return "unknown", None
    failed = [state for state in states if state in _SLURM_FAILED_END_STATES]
    if failed:
        return "failed", failed[0]
    if all(state == "COMPLETED" for state in states):
        return "completed", "COMPLETED"
    # A state sacct reports for a job squeue no longer lists, such as a transient one.
    return "unknown", states[0]
 
 
def submit_sbatch(script_path: str, dependency: str = None, dependency_type: str = "afterok") -> dict:
    """!
    @brief Submit sbatch script and return submission metadata.
    @param[in] script_path Argument passed to `submit_sbatch()`.
    @param[in] dependency Argument passed to `submit_sbatch()`.
    @param[in] dependency_type Slurm dependency type (default: afterok). Common values: afterok, afterany.
    @return Value returned by `submit_sbatch()`.
    """
    cmd = ["sbatch"]
    if dependency:
        cmd.append(f"--dependency={dependency_type}:{dependency}")
    cmd.append(script_path)
    result = subprocess.run(cmd, text=True, capture_output=True, check=False)
    metadata = {
        "command": cmd,
        "returncode": result.returncode,
        "stdout": (result.stdout or "").strip(),
        "stderr": (result.stderr or "").strip(),
        "script": script_path,
    }
    if result.returncode != 0:
        print(f"[FATAL] sbatch submission failed for {script_path}\n{metadata['stderr']}", file=sys.stderr)
        sys.exit(result.returncode)
    metadata["job_id"] = parse_slurm_job_id(metadata["stdout"])
    if not metadata["job_id"]:
        print(
            f"[FATAL] Could not parse Slurm job id from sbatch output: {metadata['stdout']}",
            file=sys.stderr
        )
        sys.exit(1)
    return metadata
 
 
def _print_validation_errors(errors: list):
    """!
    @brief Prints validation errors and exits.
    @param[in] errors List of error message strings.
    """
    print(f"\n[FATAL] Configuration validation failed with {len(errors)} issue(s):", file=sys.stderr)
    for raw_error in errors:
        file_path, message = _split_error_file_and_message(raw_error)
        key_path = _extract_key_path(message)
        code = _classify_error_code(message)
        emit_structured_error(code, key=key_path, file_path=file_path, message=message)
    print(
        "\nHint: See examples/master_template/ for valid config structure and "
        "docs/pages/14_Config_Contract.md for key-level contract details.",
        file=sys.stderr,
    )
    sys.exit(1)
 
 
def generate_header(run_id: str, source_files: dict) -> str:
    """!
    @brief Creates a standard header block for all generated files.
    @param[in] run_id The unique identifier for the current simulation run.
    @param[in] source_files A dictionary of source profile files used.
    @return A formatted string containing the header.
    """
    header_parts = [
        "# ==============================================================================",
        "#                AUTO-GENERATED CONFIGURATION FILE",
        "# ------------------------------------------------------------------------------",
        f"#   Run ID:       {run_id}",
        f"#   Timestamp:    {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}",
        "#",
        "#   Source Configuration:"
    ]
    for name, path in source_files.items():
        header_parts.append(f"#     - {name:<12}: {os.path.basename(path)}")
    header_parts.extend([
        "#",
        "#   DO NOT EDIT THIS FILE MANUALLY. IT IS A MACHINE-READABLE ARTIFACT.",
        "# ==============================================================================\n"
    ])
    return "\n".join(header_parts)
 
def generate_simple_list_file(run_dir: str, run_id: str, cfg: dict, section: str, key: str,
                              filename: str, header_sources: dict,
                              config_dir: str = None) -> str:
    """!
    @brief Generic function to create a file containing a simple list of strings.
    @param[in] run_dir The path to the main run directory.
    @param[in] run_id The unique identifier for the run.
    @param[in] cfg The dictionary containing the configuration data.
    @param[in] section The top-level key in the cfg dictionary.
    @param[in] key The second-level key whose value is the list of strings.
    @param[in] filename The name of the file to generate (e.g., 'whitelist.run').
    @param[in] header_sources A dictionary of source files for the header.
    @param[in] config_dir Optional configuration revision directory.
    @return The absolute path to the generated file.
    """
    print(f"[INFO] Generating {filename}...")
    config_dir = config_dir or os.path.join(run_dir, "config")
    os.makedirs(config_dir, exist_ok=True)
    file_path = os.path.join(config_dir, filename)
    
    lines = [generate_header(run_id, header_sources)]
    items = cfg.get(section, {}).get(key, [])
    lines.extend(items)
 
    with open(file_path, "w") as f: f.write("\n".join(lines))
    print(f"[SUCCESS] Generated {filename}: {os.path.relpath(file_path)}")
    return os.path.abspath(file_path)
 
 
def normalize_monitor_function_names(names: list, field_name: str) -> list:
    """!
    @brief Translate renamed solver functions in a monitor.yml function list.
    @param[in] names Function names as written in monitor.yml.
    @param[in] field_name YAML path of the list, used in warnings.
    @return The list with renamed functions replaced and removed ones dropped.
    @details Logging and profiling select functions by exact name, so a stale name
             silently selects nothing. Renamed functions are mapped to their current
             names and removed ones dropped, each with a warning.
    """
    normalized = []
    for name in names or []:
        if name in RENAMED_MONITOR_FUNCTIONS:
            current = RENAMED_MONITOR_FUNCTIONS[name]
            print(f"[WARNING] {field_name}: '{name}' was renamed to '{current}'; using '{current}'.",
                  file=sys.stderr)
            name = current
        elif name in REMOVED_MONITOR_FUNCTIONS:
            print(f"[WARNING] {field_name}: '{name}' no longer exists (removed by the Poisson "
                  "rewrite, 0d34592); dropping it.", file=sys.stderr)
            continue
        if name not in normalized:
            normalized.append(name)
    return normalized
 
 
def has_explicit_monitor_whitelist(monitor_cfg: dict) -> bool:
    """!
    @brief Return True when logging.enabled_functions contains at least one entry.
    @param[in] monitor_cfg Argument passed to `has_explicit_monitor_whitelist()`.
    @return Value returned by `has_explicit_monitor_whitelist()`.
    """
    items = monitor_cfg.get("logging", {}).get("enabled_functions", [])
    return bool(items)
 
 
#: Fixed names of the solver records under a run's `logs/`.
RUNTIME_MEMORY_FILE = "Runtime_Memory.csv"
PROFILING_TIMESTEP_FILE = "Profiling_Timestep_Summary.csv"
 
 
def resolve_profiling_config(monitor_cfg: dict) -> dict:
    """!
    @brief Resolve profiling reporting config from monitor.yml.
    @param[in] monitor_cfg Argument passed to `resolve_profiling_config()`.
    @return Value returned by `resolve_profiling_config()`.
    """
    profiling_cfg = monitor_cfg.get("profiling", {}) or {}
    timestep_cfg = profiling_cfg.get("timestep_output")
    final_cfg = profiling_cfg.get("final_summary")
 
    if timestep_cfg is None:
        mode = "off"
        functions = []
    else:
        if not isinstance(timestep_cfg, dict):
            raise ValueError("monitor.profiling.timestep_output must be a mapping when provided.")
        mode = str(timestep_cfg.get("mode", "off")).lower()
        functions = timestep_cfg.get("functions", [])
 
    if mode not in PROFILING_TIMESTEP_MODES:
        raise ValueError("monitor.profiling.timestep_output.mode must be one of ['off', 'selected', 'all'].")
    if functions is None:
        functions = []
    if not isinstance(functions, list):
        raise ValueError("monitor.profiling.timestep_output.functions must be a list of function names.")
    if not all(isinstance(item, str) and item.strip() for item in functions):
        raise ValueError("monitor.profiling.timestep_output.functions entries must be non-empty strings.")
    if mode == "selected" and not functions:
        raise ValueError("monitor.profiling.timestep_output.functions must be non-empty when mode is 'selected'.")
    if mode != "selected" and functions:
        raise ValueError("monitor.profiling.timestep_output.functions is only valid when mode is 'selected'.")
    functions = normalize_monitor_function_names(functions, "monitor.profiling.timestep_output.functions")
    if mode == "selected" and not functions:
        raise ValueError("monitor.profiling.timestep_output.functions lists only functions that no longer exist.")
 
    if final_cfg is None:
        final_enabled = True
    elif isinstance(final_cfg, dict):
        final_enabled = bool(final_cfg.get("enabled", True))
    else:
        raise ValueError("monitor.profiling.final_summary must be a mapping when provided.")
 
    # Per-particle and per-cell helper timers are off unless named here, or 'all'.
    helpers = profiling_cfg.get("helpers", [])
    if helpers is None:
        helpers = []
    if isinstance(helpers, str):
        if helpers.strip().lower() != "all":
            raise ValueError("monitor.profiling.helpers must be 'all' or a list of function names.")
        helpers = ["all"]
    elif not isinstance(helpers, list) or not all(isinstance(item, str) and item.strip() for item in helpers):
        raise ValueError("monitor.profiling.helpers must be 'all' or a list of non-empty function names.")
    elif helpers != ["all"]:
        helpers = normalize_monitor_function_names(helpers, "monitor.profiling.helpers")
        if any("," in item or item.strip() != item for item in helpers):
            raise ValueError("monitor.profiling.helpers names must not contain commas or surrounding spaces.")
 
    return {
        "mode": mode,
        "functions": functions,
        "final_summary_enabled": final_enabled,
        "helpers": helpers,
    }
 
 
DIAGNOSTICS_PETSC_KEYS = {
    "info",
    "malloc_debug",
    "malloc_test",
    "malloc_dump",
    "malloc_view",
    "malloc_view_threshold",
    "memory_view",
    "log_view",
    "log_view_memory",
    "log_all",
    "log_trace",
    "objects_dump",
    "options_left",
}
 
 
def _diagnostic_info(value) -> dict:
    """!
    @brief Validate PETSc info logging configuration.
    @param[in] value Boolean or structured PETSc info configuration.
    @return Normalized enabled/class-filter mapping.
    """
    if isinstance(value, bool):
        return {"enabled": value, "classes": []}
    if value is None:
        return {"enabled": False, "classes": []}
    if not isinstance(value, dict):
        raise ValueError("monitor.diagnostics.petsc.info must be boolean, null, or a mapping.")
    unknown = sorted(set(value) - {"enabled", "classes"})
    if unknown:
        raise ValueError(f"monitor.diagnostics.petsc.info has unsupported key(s): {unknown}.")
    enabled = value.get("enabled", True)
    classes = value.get("classes", [])
    if not isinstance(enabled, bool):
        raise ValueError("monitor.diagnostics.petsc.info.enabled must be boolean.")
    if not isinstance(classes, list) or not all(
        isinstance(item, str) and item.strip() and "," not in item and ":" not in item
        for item in classes
    ):
        raise ValueError(
            "monitor.diagnostics.petsc.info.classes must be a list of non-empty PETSc class names."
        )
    return {"enabled": enabled, "classes": [item.strip() for item in classes]}
 
 
def _diagnostic_bool_or_path(value, key: str):
    """!
    @brief Validate a diagnostics value that can be false, true, or a path/viewer string.
    @param[in] value Candidate value.
    @param[in] key Diagnostics key used in error messages.
    @return Normalized value.
    """
    if isinstance(value, bool) or value is None:
        return value
    if isinstance(value, str) and value.strip():
        return value.strip()
    raise ValueError(f"monitor.diagnostics.petsc.{key} must be boolean, null, or a non-empty string.")
 
 
def _diagnostic_bool(value, key: str) -> bool:
    """!
    @brief Validate a diagnostics boolean value.
    @param[in] value Candidate value.
    @param[in] key Diagnostics key used in error messages.
    @return Boolean value.
    """
    if isinstance(value, bool):
        return value
    raise ValueError(f"monitor.diagnostics.petsc.{key} must be boolean.")
 
 
def _diagnostic_bool_or_all(value, key: str):
    """!
    @brief Validate a diagnostics value that can be false, true, or "all".
    @param[in] value Candidate value.
    @param[in] key Diagnostics key used in error messages.
    @return Normalized value.
    """
    if isinstance(value, bool) or value is None:
        return value
    if isinstance(value, str) and value.strip().lower() == "all":
        return "all"
    raise ValueError(f"monitor.diagnostics.petsc.{key} must be boolean, null, or 'all'.")
 
 
def _diagnostic_default_file(run_dir: str, filename: str) -> str:
    """!
    @brief Return an absolute run-local diagnostics file path.
    @param[in] run_dir Run directory.
    @param[in] filename Diagnostics filename.
    @return Absolute diagnostics path under the run logs directory.
    """
    return os.path.abspath(os.path.join(run_dir, CANONICAL_RUN_PATHS["logs"], filename))
 
 
def _diagnostic_resolve_path_or_default(value, run_dir: str, default_filename: str):
    """!
    @brief Resolve true/string diagnostics values to a concrete file path.
    @param[in] value Boolean/string diagnostics value.
    @param[in] run_dir Run directory.
    @param[in] default_filename Default file name when value is true.
    @return False, or an absolute/explicit path string.
    """
    if value is True:
        return _diagnostic_default_file(run_dir, default_filename)
    if isinstance(value, str):
        if os.path.isabs(value) or value.startswith(":"):
            return value
        return os.path.abspath(os.path.join(run_dir, "logs", value))
    return False
 
 
def resolve_diagnostics_config(monitor_cfg: dict, run_dir: "str | None" = None, stage_label: str = "Solver") -> dict:
    """!
    @brief Resolve monitor diagnostics config and default run-local log paths.
    @param[in] monitor_cfg Parsed monitor.yml mapping.
    @param[in] run_dir Optional run directory for default artifact paths.
    @param[in] stage_label Solver/PostProcessor suffix used for PETSc output defaults.
    @return Normalized diagnostics config.
    """
    diagnostics_cfg = (monitor_cfg.get("diagnostics", {}) or {}) if isinstance(monitor_cfg, dict) else {}
    if not isinstance(diagnostics_cfg, dict):
        raise ValueError("monitor.diagnostics must be a mapping when provided.")
 
    petsc_raw = diagnostics_cfg.get("petsc", {}) or {}
    if not isinstance(petsc_raw, dict):
        raise ValueError("monitor.diagnostics.petsc must be a mapping when provided.")
    unknown = sorted(set(petsc_raw.keys()) - DIAGNOSTICS_PETSC_KEYS)
    if unknown:
        raise ValueError(f"monitor.diagnostics.petsc has unsupported key(s): {unknown}.")
 
    petsc = {
        "info": _diagnostic_info(petsc_raw.get("info", False)),
        "malloc_debug": _diagnostic_bool(petsc_raw.get("malloc_debug", False), "malloc_debug"),
        "malloc_test": _diagnostic_bool(petsc_raw.get("malloc_test", False), "malloc_test"),
        "malloc_dump": _diagnostic_bool(petsc_raw.get("malloc_dump", False), "malloc_dump"),
        "malloc_view": _diagnostic_bool_or_path(petsc_raw.get("malloc_view", False), "malloc_view"),
        "malloc_view_threshold": petsc_raw.get("malloc_view_threshold"),
        "memory_view": _diagnostic_bool(petsc_raw.get("memory_view", False), "memory_view"),
        "log_view": _diagnostic_bool_or_path(petsc_raw.get("log_view", False), "log_view"),
        "log_view_memory": _diagnostic_bool(petsc_raw.get("log_view_memory", False), "log_view_memory"),
        "log_all": _diagnostic_bool(petsc_raw.get("log_all", False), "log_all"),
        "log_trace": _diagnostic_bool_or_path(petsc_raw.get("log_trace", False), "log_trace"),
        "objects_dump": _diagnostic_bool_or_all(petsc_raw.get("objects_dump", False), "objects_dump"),
        "options_left": petsc_raw.get("options_left"),
    }
    if petsc["malloc_view_threshold"] is not None and not isinstance(petsc["malloc_view_threshold"], (int, float)):
        raise ValueError("monitor.diagnostics.petsc.malloc_view_threshold must be numeric or null.")
    if petsc["options_left"] is not None and not isinstance(petsc["options_left"], bool):
        raise ValueError("monitor.diagnostics.petsc.options_left must be boolean or null.")
 
    memory_raw = diagnostics_cfg.get("runtime_memory_log", {}) or {}
    if not isinstance(memory_raw, dict):
        raise ValueError("monitor.diagnostics.runtime_memory_log must be a mapping when provided.")
    # `file` is refused by the monitor schema; a stored run's config may still carry it.
    memory_unknown = sorted(set(memory_raw.keys()) - {"enabled", "file"})
    if memory_unknown:
        raise ValueError(f"monitor.diagnostics.runtime_memory_log has unsupported key(s): {memory_unknown}.")
    memory_enabled = memory_raw.get("enabled", True)
    if not isinstance(memory_enabled, bool):
        raise ValueError("monitor.diagnostics.runtime_memory_log.enabled must be boolean.")
 
    resolved_petsc = dict(petsc)
    artifacts = []
    if run_dir:
        suffix = "PostProcessor" if stage_label == "PostProcessor" else "Solver"
        resolved_petsc["info"] = False
        defaults = {
            "malloc_view": f"PETSc_MallocView_{suffix}.log",
            "log_view": f"PETSc_LogView_{suffix}.log",
            "log_trace": f"PETSc_LogTrace_{suffix}.log",
        }
        if petsc["info"]["enabled"]:
            info_path = _diagnostic_default_file(run_dir, f"PETSc_Info_{suffix}.log")
            classes = petsc["info"]["classes"]
            resolved_petsc["info"] = info_path + (f":{','.join(classes)}" if classes else "")
            # PetscInfoSetFile appends the emitting MPI rank (for example `.0`).
            artifacts.append(f"{info_path}.*")
        for key, default_name in defaults.items():
            resolved_value = _diagnostic_resolve_path_or_default(petsc[key], run_dir, default_name)
            if key == "log_view" and resolved_value and isinstance(resolved_value, str) and not resolved_value.startswith(":"):
                resolved_value = f":{resolved_value}"
            resolved_petsc[key] = resolved_value
            if resolved_value and isinstance(resolved_value, str) and not resolved_value.startswith(":"):
                artifacts.append(resolved_value)
            elif resolved_value and isinstance(resolved_value, str) and resolved_value.startswith(":"):
                artifacts.append(resolved_value[1:])
        if memory_enabled:
            artifacts.append(
                os.path.abspath(os.path.join(
                    run_dir, CANONICAL_RUN_PATHS["logs"], RUNTIME_MEMORY_FILE
                ))
            )
 
    return {
        "petsc": resolved_petsc,
        "runtime_memory_log": {"enabled": memory_enabled},
        "artifacts": artifacts,
    }
 
 
def build_petsc_diagnostics_args(monitor_cfg: dict, run_dir: str, stage_label: str) -> list:
    """!
    @brief Build PETSc diagnostics command-line arguments for a run stage.
    @param[in] monitor_cfg Parsed monitor.yml mapping.
    @param[in] run_dir Run directory used to resolve default diagnostics files.
    @param[in] stage_label Stage label for default output names.
    @return List of executable arguments.
    """
    diagnostics = resolve_diagnostics_config(monitor_cfg, run_dir, stage_label)
    petsc = diagnostics["petsc"]
    args = []
    if petsc["info"]:
        args.extend(["-info", str(petsc["info"])])
    if petsc["malloc_debug"]:
        args.append("-malloc_debug")
    if petsc["malloc_test"]:
        args.append("-malloc_test")
    for key, flag in (
        ("malloc_dump", "-malloc_dump"),
        ("malloc_view", "-malloc_view"),
        ("memory_view", "-memory_view"),
        ("log_view", "-log_view"),
        ("log_trace", "-log_trace"),
        ("objects_dump", "-objects_dump"),
    ):
        value = petsc.get(key)
        if value is True:
            args.append(flag)
        elif value:
            args.extend([flag, str(value)])
    if petsc["malloc_view_threshold"] is not None:
        args.extend(["-malloc_view_threshold", str(petsc["malloc_view_threshold"])])
    if petsc["log_view_memory"]:
        args.append("-log_view_memory")
    if petsc["log_all"]:
        args.append("-log_all")
    if petsc["options_left"] is not None:
        args.extend(["-options_left", "true" if petsc["options_left"] else "false"])
    elif stage_label == "PostProcessor":
        # The postprocessor reads the solver's control file, so every solver-only option
        # would be reported as unused on each run; left unset, the report is turned off.
        args.extend(["-options_left", "false"])
    return args
 
 
def _statistics_subsystem_available(case_cfg: dict, requirement) -> bool:
    """!
    @brief Report whether the subsystem a statistics field depends on is active.
    @param[in] case_cfg Parsed case configuration.
    @param[in] requirement Subsystem key from `STATISTICS_ELIGIBLE_FIELDS`, or None.
    @return Value returned by `_statistics_subsystem_available()`.
    """
    if requirement is None:
        return True
    physics = ((case_cfg or {}).get("models", {}) or {}).get("physics", {}) or {}
    if requirement == "particles":
        particles = physics.get("particles", {}) or {}
        try:
            return int(particles.get("count", 0) or 0) > 0
        except (TypeError, ValueError):
            return False
    turbulence = physics.get("turbulence", {}) or {}
    les_on = bool((turbulence.get("les", {}) or {}).get("enabled", False))
    if requirement == "les":
        return les_on
    if requirement == "turbulence":
        return les_on
    return False
 
 
def normalize_field_statistics_config(monitor_cfg: dict, case_cfg: dict = None) -> dict:
    """!
    @brief Validate and canonicalize the field-statistics block of monitor.yml.
 
    @details Rejects every condition the field-statistics contract forbids, naming the
             offending window so a message points at one entry rather than the block.
             Returns a canonical form the flag resolver serializes without further
             interpretation, so validation and emission cannot disagree.
 
    @param[in] monitor_cfg Parsed monitor configuration.
    @param[in] case_cfg Parsed case configuration, used to check that each field's
                        subsystem is active. Subsystem checks are skipped when None.
    @return Value returned by `normalize_field_statistics_config()`.
    """
    raw = (monitor_cfg or {}).get("field_statistics")
    if raw is None:
        return {"enabled": False, "windows": []}
    if not isinstance(raw, dict):
        raise ValueError("'field_statistics' must be a mapping.")
 
    enabled = raw.get("enabled", False)
    if not isinstance(enabled, bool):
        raise ValueError("'field_statistics.enabled' must be true or false.")
    windows_raw = raw.get("windows", []) or []
    if not isinstance(windows_raw, list):
        raise ValueError("'field_statistics.windows' must be a list.")
    if enabled and not windows_raw:
        raise ValueError("'field_statistics.enabled' is true but no window is defined.")
 
    windows = []
    seen_names = set()
    for index, window in enumerate(windows_raw):
        if not isinstance(window, dict):
            raise ValueError(f"'field_statistics.windows[{index}]' must be a mapping.")
        name = window.get("name")
        if not isinstance(name, str) or not name.strip():
            raise ValueError(f"'field_statistics.windows[{index}]' needs a non-empty 'name'.")
        name = name.strip()
        # Window names identify saved state across a restart, so a duplicate would
        # make two windows indistinguishable in the checkpoint.
        if name in seen_names:
            raise ValueError(f"field statistics window '{name}' is defined more than once.")
        seen_names.add(name)
 
        start_time = window.get("start_time")
        if not isinstance(start_time, (int, float)) or isinstance(start_time, bool):
            raise ValueError(f"field statistics window '{name}': 'start_time' must be a number.")
        end_time = window.get("end_time")
        if end_time is not None:
            if not isinstance(end_time, (int, float)) or isinstance(end_time, bool):
                raise ValueError(f"field statistics window '{name}': 'end_time' must be a number.")
            if float(end_time) <= float(start_time):
                raise ValueError(
                    f"field statistics window '{name}': 'end_time' ({end_time}) must be greater "
                    f"than 'start_time' ({start_time})."
                )
 
        weighting = window.get("weighting")
        if weighting not in STATISTICS_WEIGHTING_MODES:
            raise ValueError(
                f"field statistics window '{name}': 'weighting' must be one of "
                f"{list(STATISTICS_WEIGHTING_MODES)} (got {weighting!r})."
            )
 
        has_step = "step_cadence" in window and window["step_cadence"] is not None
        has_time = "time_cadence" in window and window["time_cadence"] is not None
        if has_step == has_time:
            raise ValueError(
                f"field statistics window '{name}': set exactly one of 'step_cadence' and "
                "'time_cadence'."
            )
        step_cadence = None
        time_cadence = None
        if has_step:
            step_cadence = window["step_cadence"]
            if not isinstance(step_cadence, int) or isinstance(step_cadence, bool) or step_cadence <= 0:
                raise ValueError(
                    f"field statistics window '{name}': 'step_cadence' must be a positive integer "
                    f"(got {step_cadence!r})."
                )
        else:
            time_cadence = window["time_cadence"]
            if (not isinstance(time_cadence, (int, float)) or isinstance(time_cadence, bool)
                    or float(time_cadence) <= 0.0):
                raise ValueError(
                    f"field statistics window '{name}': 'time_cadence' must be a positive number "
                    f"(got {time_cadence!r})."
                )
 
        fields, covariances = _normalize_statistics_requests(
            f"field statistics window '{name}'", window.get("fields"), window.get("covariances"),
            STATISTICS_ELIGIBLE_FIELDS, case_cfg)
 
        windows.append({
            "name": name,
            "start_time": float(start_time),
            "end_time": None if end_time is None else float(end_time),
            "weighting": weighting,
            "step_cadence": step_cadence,
            "time_cadence": None if time_cadence is None else float(time_cadence),
            "fields": fields,
            "covariances": covariances,
        })
 
    return {"enabled": bool(enabled), "windows": windows}
 
 
def _normalize_statistics_requests(label: str, fields_raw, covariances_raw, eligible: dict, case_cfg=None):
    """!
    @brief Validate and canonicalize the fields and covariances one window or ensemble requests.
    @param[in] label Owner named in error messages, such as `field statistics window 'w'`.
    @param[in] fields_raw The requested fields list of the owner.
    @param[in] covariances_raw The requested covariance pairs of the owner, or None.
    @param[in] eligible Fields the owner may name, with component counts and requirements.
    @param[in] case_cfg Parsed case configuration for subsystem checks, or None to skip them.
    @return Tuple of the canonical field entries and covariance pairs.
    """
    if not isinstance(fields_raw, list) or not fields_raw:
        raise ValueError(f"{label}: 'fields' must be a non-empty list.")
    fields = []
    for field_entry in fields_raw:
        if not isinstance(field_entry, dict):
            raise ValueError(f"{label}: each 'fields' entry must be a mapping.")
        field_name = field_entry.get("field")
        if not isinstance(field_name, str) or field_name not in eligible:
            raise ValueError(
                f"{label}: field {field_name!r} cannot be accumulated. "
                f"Available fields: {sorted(eligible)}."
            )
        requirement = eligible[field_name]["requires"]
        if case_cfg is not None and not _statistics_subsystem_available(case_cfg, requirement):
            raise ValueError(
                f"{label}: field '{field_name}' requires the "
                f"'{requirement}' subsystem, which is not enabled for this case."
            )
        if any(existing["field"] == field_name for existing in fields):
            raise ValueError(
                f"{label}: field '{field_name}' is listed more than once."
            )
        moments = field_entry.get("moments")
        if not isinstance(moments, list) or not moments:
            raise ValueError(
                f"{label}: field '{field_name}' needs a non-empty "
                "'moments' list."
            )
        unknown = [m for m in moments if m not in STATISTICS_MOMENT_NAMES]
        if unknown:
            raise ValueError(
                f"{label}: field '{field_name}' requests unknown "
                f"moments {unknown}. Available moments: {list(STATISTICS_MOMENT_NAMES)}."
            )
        # The first moment is always kept, because every centered product is
        # measured against it.
        fields.append({"field": field_name, "moments": ["first"] + (["second"] if "second" in moments else [])})
 
    covariances_raw = covariances_raw or []
    if not isinstance(covariances_raw, list):
        raise ValueError(f"{label}: 'covariances' must be a list.")
    requested = {entry["field"] for entry in fields}
    covariances = []
    for pair in covariances_raw:
        if not isinstance(pair, list) or len(pair) != 2:
            raise ValueError(
                f"{label}: each covariance must be a pair of field names."
            )
        first, second = pair
        for member in (first, second):
            if not isinstance(member, str) or member not in eligible:
                raise ValueError(
                    f"{label}: covariance member {member!r} cannot be "
                    f"accumulated. Available fields: {sorted(eligible)}."
                )
        if first == second:
            raise ValueError(
                f"{label}: covariance ['{first}', '{second}'] pairs a "
                "field with itself; request that through moments: [second] instead."
            )
        missing = sorted({first, second} - requested)
        if missing:
            raise ValueError(
                f"{label}: covariance ['{first}', '{second}'] needs "
                f"{missing} in 'fields' as well, because a co-moment is centered against their means."
            )
        # Two three-component fields would need a full nine-component tensor,
        # which nothing allocates.
        if (eligible[first]["components"] == 3
                and eligible[second]["components"] == 3):
            raise ValueError(
                f"{label}: covariance ['{first}', '{second}'] pairs two "
                "vector fields, which is not supported."
            )
        if sorted((first, second)) in [sorted(existing) for existing in covariances]:
            raise ValueError(
                f"{label}: covariance ['{first}', '{second}'] is "
                "requested more than once."
            )
        covariances.append([first, second])
 
    return fields, covariances
 
 
def resolve_field_statistics_flags(monitor_cfg: dict, case_cfg: dict = None) -> list:
    """!
    @brief Serialize field-statistics configuration into control-file option lines.
    @details A window list is variable arity, so its option names are constructed from
             the index. Each name belongs to a family declared in the ingress audit
             manifest.
    @param[in] monitor_cfg Parsed monitor configuration.
    @param[in] case_cfg Parsed case configuration, for subsystem availability checks.
    @return Value returned by `resolve_field_statistics_flags()`.
    """
    config = normalize_field_statistics_config(monitor_cfg, case_cfg)
    if not config["enabled"]:
        return []
 
    # Window times are physical; the runtime compares them against its own clock, which
    # is in solver time, so each is divided by the reference time L_ref / U_ref.
    scales = resolve_reference_scales(case_cfg or {})
    window_path = ("monitor", "field_statistics", "windows", "[]")
 
    def solver_time(key: str, value: float) -> float:
        """!
        @brief Convert one physical window time to solver time.
        @param[in] key Window key, for the recorded dimension.
        @param[in] value Physical time.
        @return Solver time.
        """
        return to_solver_units(value, window_path + (key,), scales)
 
    lines = ["-field_statistics_enabled true",
             f"-field_statistics_window_count {len(config['windows'])}"]
    for index, window in enumerate(config["windows"]):
        prefix = f"-field_statistics_window_{index}"
        lines.append(f"{prefix}_name {window['name']}")
        lines.append(f"{prefix}_start_time {solver_time('start_time', window['start_time'])!r}")
        # An absent end time is what makes a window open ended, so the option is
        # omitted rather than given a sentinel value.
        if window["end_time"] is not None:
            lines.append(f"{prefix}_end_time {solver_time('end_time', window['end_time'])!r}")
        lines.append(f"{prefix}_weighting {window['weighting']}")
        if window["step_cadence"] is not None:
            lines.append(f"{prefix}_step_cadence {window['step_cadence']}")
        else:
            lines.append(f"{prefix}_time_cadence {solver_time('time_cadence', window['time_cadence'])!r}")
        lines.append(f"{prefix}_field_count {len(window['fields'])}")
        for field_index, field_entry in enumerate(window["fields"]):
            lines.append(f"{prefix}_field_{field_index}_name {field_entry['field']}")
            lines.append(f"{prefix}_field_{field_index}_moments {','.join(field_entry['moments'])}")
        lines.append(f"{prefix}_covariance_count {len(window['covariances'])}")
        for pair_index, pair in enumerate(window["covariances"]):
            lines.append(f"{prefix}_covariance_{pair_index} {pair[0]},{pair[1]}")
    return lines
 
 
def resolve_statistics_console_output_frequency(io_cfg: dict) -> "int | None":
    """!
    @brief Resolve the statistics console cadence, mirroring the particle one.
    @param[in] io_cfg Parsed monitor `io` block.
    @return Value returned by `resolve_statistics_console_output_frequency()`.
    """
    if 'statistics_console_output_frequency' in io_cfg:
        return io_cfg['statistics_console_output_frequency']
    return io_cfg.get('data_output_frequency')
 
 
def normalize_solution_monitoring_config(monitor_cfg: dict) -> dict:
    """!
    @brief Validate and canonicalize physical-solution convergence monitoring.
    @param[in] monitor_cfg Parsed monitor.yml mapping.
    @return Canonical solution-monitoring configuration.
    @throws ValueError when convergence settings are invalid.
    """
    if not isinstance(monitor_cfg, dict):
        raise ValueError("monitor.yml must be a mapping before solution monitoring can be normalized.")
    monitoring = monitor_cfg.get("solution_monitoring", {}) or {}
    if not isinstance(monitoring, dict):
        raise ValueError("solution_monitoring must be a mapping when provided.")
    convergence = monitoring.get("convergence", {}) or {}
    if not isinstance(convergence, dict):
        raise ValueError("solution_monitoring.convergence must be a mapping when provided.")
    enabled = convergence.get("enabled", True)
    if not isinstance(enabled, bool):
        raise ValueError("solution_monitoring.convergence.enabled must be boolean.")
    mode = normalize_solution_convergence_mode(convergence.get("mode", "steady_deterministic"))
    normalized = {"enabled": enabled, "mode": mode.lower()}
    periodic_cfg = convergence.get("periodic_deterministic")
    statistical_cfg = convergence.get("statistical_steady")
    if mode == "PERIODIC_DETERMINISTIC":
        if not isinstance(periodic_cfg, dict):
            raise ValueError(
                "solution_monitoring.convergence.periodic_deterministic is required for periodic_deterministic mode."
            )
        period_steps = periodic_cfg.get("period_steps")
        if isinstance(period_steps, bool) or not isinstance(period_steps, int) or period_steps <= 0:
            raise ValueError(
                "solution_monitoring.convergence.periodic_deterministic.period_steps must be a positive integer."
            )
        normalized["periodic_deterministic"] = {"period_steps": period_steps}
    elif periodic_cfg is not None:
        raise ValueError(
            "solution_monitoring.convergence.periodic_deterministic is only valid for periodic_deterministic mode."
        )
    if mode == "STATISTICAL_STEADY":
        if not isinstance(statistical_cfg, dict):
            raise ValueError(
                "solution_monitoring.convergence.statistical_steady is required for statistical_steady mode."
            )
        window_steps = statistical_cfg.get("window_steps")
        if isinstance(window_steps, bool) or not isinstance(window_steps, int) or window_steps <= 0:
            raise ValueError(
                "solution_monitoring.convergence.statistical_steady.window_steps must be a positive integer."
            )
        normalized["statistical_steady"] = {"window_steps": window_steps}
    elif statistical_cfg is not None:
        raise ValueError(
            "solution_monitoring.convergence.statistical_steady is only valid for statistical_steady mode."
        )
    return {"convergence": normalized}
 
 
def resolve_solution_monitoring_flags(monitor_cfg: dict) -> dict:
    """!
    @brief Translate solution-monitoring YAML into the existing C convergence flags.
    @param[in] monitor_cfg Parsed monitor.yml mapping.
    @return Mapping of convergence options to explicit runtime values.
    """
    convergence = normalize_solution_monitoring_config(monitor_cfg)["convergence"]
    flags = {
        "-solution_convergence_enabled": "true" if convergence["enabled"] else "false",
        "-solution_convergence_mode": f'"{normalize_solution_convergence_mode(convergence["mode"])}"',
    }
    if "periodic_deterministic" in convergence:
        flags["-solution_convergence_period_steps"] = convergence["periodic_deterministic"]["period_steps"]
    if "statistical_steady" in convergence:
        flags["-solution_convergence_window_steps"] = convergence["statistical_steady"]["window_steps"]
    return flags
 
 
def prepare_monitor_files(run_dir: str, run_id: str, monitor_cfg: dict, source_files: dict,
                          config_dir: str = None) -> dict:
    """!
    @brief Generate monitor sidecar files and resolve profiling reporting behavior.
    @param[in] run_dir Argument passed to `prepare_monitor_files()`.
    @param[in] run_id Argument passed to `prepare_monitor_files()`.
    @param[in] monitor_cfg Argument passed to `prepare_monitor_files()`.
    @param[in] source_files Argument passed to `prepare_monitor_files()`.
    @param[in] config_dir Optional configuration revision directory.
    @return Value returned by `prepare_monitor_files()`.
    """
    print("[INFO] Generating monitoring files...")
 
    whitelist_path = None
    if has_explicit_monitor_whitelist(monitor_cfg):
        enabled = normalize_monitor_function_names(
            monitor_cfg["logging"]["enabled_functions"], "monitor.logging.enabled_functions")
        whitelist_path = generate_simple_list_file(
            run_dir, run_id, {"logging": {"enabled_functions": enabled}}, "logging", "enabled_functions",
            "whitelist.run", source_files, config_dir=config_dir,
        )
    else:
        print("[INFO] logging.enabled_functions is empty; omitting whitelist.run so the C runtime uses its default allow-list.")
 
    profiling_cfg = resolve_profiling_config(monitor_cfg)
 
    profile_path = None
    if profiling_cfg["mode"] == "selected":
        profile_path = generate_simple_list_file(
            run_dir,
            run_id,
            {"profiling": {"selected_functions": profiling_cfg["functions"]}},
            "profiling",
            "selected_functions",
            "profile.run",
            source_files,
            config_dir=config_dir,
        )
    else:
        print(f"[INFO] profiling.timestep_output.mode is '{profiling_cfg['mode']}'; no profile.run function list is needed.")
 
    return {
        "whitelist": whitelist_path,
        "profile": profile_path,
        "profiling": profiling_cfg,
    }
 
def generate_multi_block_bcs(run_dir: str, run_id: str, case_cfg: dict, source_files: dict,
                             config_dir: str = None) -> list:
    """!
    @brief Parses multi-block BCs from YAML, generates a .run file for each block,
           and returns a list of their absolute paths.
    @details Handles both simple list format (for single-block cases) and a
             list-of-lists (for multi-block cases) for boundary conditions.
    @param[in] run_dir The path to the main run directory.
    @param[in] run_id The unique identifier for the run.
    @param[in] case_cfg The parsed case.yml configuration dictionary.
    @param[in] source_files A dictionary of source files for the header.
    @param[in] config_dir Optional configuration revision directory.
    @return A list of absolute paths to the generated BC files.
    @throws ValueError if the number of BC definitions does not match the number of blocks.
    """
    print("[INFO] Generating boundary condition files...")
    config_dir = config_dir or os.path.join(run_dir, "config")
    os.makedirs(config_dir, exist_ok=True)
    profile_dir = os.path.join(run_dir, "inputs", "inlet_profiles")
    os.makedirs(profile_dir, exist_ok=True)
    num_blocks = int(case_cfg.get('models', {}).get('domain', {}).get('blocks', 1))
    prepared_blocks = validate_and_prepare_boundary_conditions(case_cfg)
    case_path = source_files.get("Case") if source_files else None
    profile_grid_dims = None
    # Every profile source stages a physical velocity PICSLICE.
    profile_velocity_scale = reference_scale(BC_PARAM_QUANTITIES["source"][0], resolve_reference_scales(case_cfg))
 
    if any(bc.get("handler") == "prescribed_flow" for block in prepared_blocks for bc in block):
        profile_grid_dims = resolve_grid_block_dimensions_for_profiles(case_cfg, case_path, run_dir)
 
    generated_files = []
    generated_profile_summaries = []
    generated_target_grid = None
    field_slice_target_grid = None
    for i, block_bcs_list in enumerate(prepared_blocks):
        file_name = "bcs.run" if num_blocks == 1 else f"bcs_block{i}.run"
        bcs_file_path = os.path.join(config_dir, file_name)
        bcs_lines = [generate_header(run_id, source_files)]
 
        for bc in block_bcs_list:
            face, bc_type, handler = bc['face'], bc['type'], bc['handler']
            params = dict(bc.get('params') or {})
            if handler == "prescribed_flow":
                source = params.pop("source")
                expected_dims = _bc_profile_expected_dims(face, profile_grid_dims[i])
                staged_name = f"inlet_profile_block{i}_{face.replace('+', 'pos').replace('-', 'neg')}.picslice"
                staged_path = os.path.join(profile_dir, staged_name)
                if os.path.isfile(staged_path):
                    with open(staged_path, "r", encoding="utf-8") as stream:
                        header = [line.strip() for line in stream if line.strip() and not line.lstrip().startswith("#")]
                    if len(header) < 3 or header[0] != "PICSLICE":
                        raise ValueError(f"Locked inlet profile is not a PICSLICE file: {staged_path}")
                    try:
                        actual_dims = tuple(int(token) for token in header[2].split())
                    except ValueError as exc:
                        raise ValueError(f"Locked inlet profile has invalid dimensions: {staged_path}") from exc
                    if actual_dims != tuple(expected_dims):
                        raise ValueError(
                            f"Locked inlet profile {staged_path} has dimensions {actual_dims}; "
                            f"expected {tuple(expected_dims)}."
                        )
                    print(
                        f"[INFO] Reusing locked prescribed_flow profile for block {i}, "
                        f"face {face}: {os.path.relpath(staged_path)}"
                    )
                    params["source_file"] = os.path.abspath(staged_path)
                    source = None
                elif source["type"] == "file":
                    source_path = _resolve_case_relative_path(
                        source["path"], os.path.dirname(os.path.abspath(case_path))
                    )
                elif source["type"] == "generated":
                    source_path = os.path.join(
                        profile_dir,
                        f"inlet_profile_block{i}_{_face_artifact_token(face)}.generated.dimensional.picslice",
                    )
                    if os.path.abspath(source_path) == os.path.abspath(staged_path):
                        raise ValueError(
                            f"Generated profile output_file for block {i}, face {face} must differ from staged solver profile."
                        )
                    if source["generator"] == "square_duct_poiseuille":
                        if generated_target_grid is None:
                            generated_target_grid = resolve_target_grid_for_generated_profile(case_cfg, case_path, run_dir)
                        summary = generate_square_duct_poiseuille_picslice(
                            source_path,
                            expected_dims,
                            source["params"],
                            target_grid=generated_target_grid,
                            target_block=i,
                            target_face=face,
                            script=source.get("script"),
                            case_path=case_path,
                        )
                    else:
                        raise ValueError(f"Unsupported generated profile generator '{source['generator']}'.")
                    summary.update({"block": i, "face": face})
                    generated_profile_summaries.append(summary)
                elif source["type"] == "field_slice":
                    source_path = os.path.join(
                        profile_dir,
                        f"inlet_profile_block{i}_{_face_artifact_token(face)}.sliced.dimensional.picslice",
                    )
                    if os.path.abspath(source_path) == os.path.abspath(staged_path):
                        raise ValueError(
                            f"field_slice output_file for block {i}, face {face} must differ from staged solver profile."
                        )
                    if field_slice_target_grid is None:
                        field_slice_target_grid = resolve_target_grid_for_field_slice(case_cfg, case_path, run_dir)
                    summary = generate_field_slice_picslice(
                        source_path,
                        expected_dims,
                        source,
                        field_slice_target_grid,
                        face,
                        i,
                        case_path,
                    )
                    summary.update({"block": i, "face": face})
                    generated_profile_summaries.append(summary)
                elif source is not None:
                    raise ValueError(f"Unsupported prescribed_flow source type '{source.get('type')}'.")
                if source is not None:
                    summary = validate_and_nondimensionalize_picslice(source_path, staged_path, profile_velocity_scale, expected_dims)
                    print(
                        f"[SUCCESS] Staged prescribed_flow profile for block {i}, face {face}: "
                        f"{os.path.relpath(staged_path)} dims={summary['dims']}"
                    )
                    params["source_file"] = os.path.abspath(staged_path)
            params_str = ""
            if params:
                parts = []
                for k, v in params.items():
                    if isinstance(v, bool):
                        value_str = "true" if v else "false"
                    else:
                        value_str = str(v)
                    parts.append(f"{k}={value_str}")
                params_str = " ".join(parts)
            bcs_lines.append(f"{face:<20s} {bc_type:<12s} {handler:<20s} {params_str}")
        
        with open(bcs_file_path, "w") as f: f.write("\n".join(bcs_lines))
        
        print(f"[SUCCESS] Generated BCs for Block {i}: {os.path.relpath(bcs_file_path)}")
        generated_files.append(os.path.abspath(bcs_file_path))
 
    if generated_profile_summaries:
        info_path = write_profile_info(profile_dir, generated_profile_summaries)
        print(f"[SUCCESS] Wrote generated profile summary: {os.path.relpath(info_path)}")
        
    return generated_files
 
def format_flag_value(value):
    """!
    @brief Converts Python types to C-style command-line flag values.
    @param[in] value The Python object to convert (bool, list, or other).
    @return A string representation suitable for a C command-line parser.
    """
    if isinstance(value, bool):
        return "1" if value else "0"
    if isinstance(value, list):
        return ",".join(map(str, value))
    return str(value)
 
def translate_programmatic_grid_settings(grid_settings: dict) -> dict:
    """!
    @brief Return programmatic-grid settings translated to the C node-count contract.
    @param[in] grid_settings Argument passed to `translate_programmatic_grid_settings()`.
    @return Value returned by `translate_programmatic_grid_settings()`.
    """
    translated = dict(grid_settings)
    for dim_key in ("im", "jm", "km"):
        if dim_key in translated:
            raw_val = translated[dim_key]
            if not isinstance(raw_val, int) or raw_val <= 0:
                raise ValueError(
                    f"grid.programmatic_settings.{dim_key} must be a positive integer cell count "
                    f"(got {raw_val!r})."
                )
            translated[dim_key] = raw_val + 1
    return translated
 
 
PROGRAMMATIC_BRIDGE_GRID_KEYS = (
    "im", "jm", "km",
    "xMins", "xMaxs", "yMins", "yMaxs", "zMins", "zMaxs",
    "rxs", "rys", "rzs",
)
 
 
def validate_programmatic_bridge_grid_settings(raw_settings: dict) -> None:
    """!
    @brief Validate the scalar programmatic grid settings the bridge PICGRID is built from.
    @details A Python generator - an initial condition or a generated inlet profile - runs
             as a separate process and reads the programmatic grid from that bridge, which
             supports one block with scalar settings.
    @param[in] raw_settings programmatic_settings dict from case.yml.
    @throws ValueError when required scalar settings are missing or invalid.
    """
    if not isinstance(raw_settings, dict):
        raise ValueError(
            "grid.programmatic_settings must be a mapping when a Python generator reads the grid."
        )
 
    missing = [key for key in PROGRAMMATIC_BRIDGE_GRID_KEYS if key not in raw_settings]
    if missing:
        raise ValueError(
            "grid.programmatic_settings must include "
            f"{missing} when grid.mode is 'programmatic_c' and a Python generator reads the grid."
        )
 
    for key in ("im", "jm", "km"):
        value = raw_settings[key]
        if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
            raise ValueError(
                f"grid.programmatic_settings.{key} must be a positive scalar integer cell count "
                "when a Python generator reads the programmatic_c grid."
            )
 
    for key in ("xMins", "xMaxs", "yMins", "yMaxs", "zMins", "zMaxs", "rxs", "rys", "rzs"):
        value = raw_settings[key]
        if isinstance(value, (list, tuple, dict, bool)):
            raise ValueError(
                f"grid.programmatic_settings.{key} must be a scalar numeric value "
                "when a Python generator reads the programmatic_c grid."
            )
        try:
            numeric = float(value)
        except (TypeError, ValueError):
            raise ValueError(
                f"grid.programmatic_settings.{key} must be a scalar numeric value "
                "when a Python generator reads the programmatic_c grid."
            )
        if not math.isfinite(numeric):
            raise ValueError(
                f"grid.programmatic_settings.{key} must be finite "
                "when a Python generator reads the programmatic_c grid."
            )
        if key in {"rxs", "rys", "rzs"} and numeric <= 0.0:
            raise ValueError(
                f"grid.programmatic_settings.{key} must be positive "
                "when a Python generator reads the programmatic_c grid."
            )
 
 
def generate_picgrid_from_programmatic_settings(raw_settings: dict, dest_path: str, L_ref: float) -> dict:
    """!
    @brief Generate a canonical PICGRID file from programmatic Cartesian grid settings.
    @details Implements the same coordinate formula as ComputeStretchedCoord in src/grid.c.
             im/jm/km in raw_settings are cell counts; node counts are im+1, jm+1, km+1.
    @param[in] raw_settings programmatic_settings dict from case.yml.
    @param[in] dest_path Destination PICGRID file path.
    @param[in] L_ref Reference length for nondimensionalization (must be non-zero).
    @return Summary dict: nblk, dims [(IM, JM, KM)], total_nodes.
    """
    validate_programmatic_bridge_grid_settings(raw_settings)
    if L_ref == 0.0:
        raise ValueError("length_ref must be non-zero for programmatic grid generation.")
    IM = int(raw_settings.get("im", 0)) + 1
    JM = int(raw_settings.get("jm", 0)) + 1
    KM = int(raw_settings.get("km", 0)) + 1
    if IM < 2 or JM < 2 or KM < 2:
        raise ValueError(
            f"programmatic_settings im/jm/km must each be >= 1 "
            f"(got im={IM-1}, jm={JM-1}, km={KM-1})."
        )
    x_min = float(raw_settings.get("xMins", 0.0))
    x_max = float(raw_settings.get("xMaxs", 1.0))
    y_min = float(raw_settings.get("yMins", 0.0))
    y_max = float(raw_settings.get("yMaxs", 1.0))
    z_min = float(raw_settings.get("zMins", 0.0))
    z_max = float(raw_settings.get("zMaxs", 1.0))
    rx = float(raw_settings.get("rxs", 1.0))
    ry = float(raw_settings.get("rys", 1.0))
    rz = float(raw_settings.get("rzs", 1.0))
 
    def _stretched(idx, N, length, r):
        """!
        @brief Mirror of ComputeStretchedCoord from src/grid.c.
        @param[in] idx Node index along the axis.
        @param[in] N Total node count along the axis.
        @param[in] length Physical length of the axis.
        @param[in] r Geometric stretching ratio.
        @return Coordinate offset from the axis minimum.
        """
        frac = idx / (N - 1.0)
        if abs(r - 1.0) < 1.0e-9:
            return length * frac
        return length * (r ** frac - 1.0) / (r - 1.0)
 
    Lx, Ly, Lz = x_max - x_min, y_max - y_min, z_max - z_min
    os.makedirs(os.path.dirname(dest_path), exist_ok=True)
    with open(dest_path, "w") as fout:
        fout.write("PICGRID\n1\n")
        fout.write(f"{IM} {JM} {KM}\n")
        for k in range(KM):
            z = (z_min + _stretched(k, KM, Lz, rz)) / L_ref
            for j in range(JM):
                y = (y_min + _stretched(j, JM, Ly, ry)) / L_ref
                for i in range(IM):
                    x = (x_min + _stretched(i, IM, Lx, rx)) / L_ref
                    fout.write(
                        f"{format_picgrid_coordinate(x)} {format_picgrid_coordinate(y)} "
                        f"{format_picgrid_coordinate(z)}\n"
                    )
    total_nodes = IM * JM * KM
    return {"nblk": 1, "dims": [(IM, JM, KM)], "total_nodes": total_nodes}
 
 
GRID_DA_PROCESSOR_KEYS = ("da_processors_x", "da_processors_y", "da_processors_z")
 
 
def resolve_grid_da_processor_layout(grid_cfg: dict) -> dict:
    """!
    @brief Resolve optional global DMDA layout, preferring grid-level keys over legacy nested keys.
    @param[in] grid_cfg Argument passed to `resolve_grid_da_processor_layout()`.
    @return Value returned by `resolve_grid_da_processor_layout()`.
    """
    top_level = {}
    legacy = {}
 
    for key in GRID_DA_PROCESSOR_KEYS:
        value = grid_cfg.get(key)
        if isinstance(value, (list, tuple)):
            raise ValueError(
                f"grid.{key} must be a scalar integer. "
                "Per-block MPI decomposition is not implemented on the C side; DMDA layout is global."
            )
        if value is not None:
            if not isinstance(value, int) or value <= 0:
                raise ValueError(f"grid.{key} must be a positive integer when provided (got {value}).")
            top_level[key] = value
 
    legacy_settings = grid_cfg.get("programmatic_settings")
    if isinstance(legacy_settings, dict):
        for key in GRID_DA_PROCESSOR_KEYS:
            value = legacy_settings.get(key)
            if isinstance(value, (list, tuple)):
                raise ValueError(
                    f"grid.programmatic_settings.{key} must be a scalar integer. "
                    "Per-block MPI decomposition is not implemented on the C side; DMDA layout is global."
                )
            if value is not None:
                if not isinstance(value, int) or value <= 0:
                    raise ValueError(
                        f"grid.programmatic_settings.{key} must be a positive integer when provided (got {value})."
                    )
                legacy[key] = value
 
    resolved = {}
    for key in GRID_DA_PROCESSOR_KEYS:
        top_value = top_level.get(key)
        legacy_value = legacy.get(key)
        if top_value is not None and legacy_value is not None and top_value != legacy_value:
            raise ValueError(
                f"grid.{key} conflicts with legacy grid.programmatic_settings.{key}; "
                "define the processor layout in only one place."
            )
        if top_value is not None:
            resolved[key] = top_value
        elif legacy_value is not None:
            resolved[key] = legacy_value
 
    return resolved
 
 
def resolve_grid_node_dims(case_cfg: dict, case_path: str,
                           staged_grid: "str | None" = None) -> "list | None":
    """!
    @brief Per-block (IM, JM, KM) node counts the solver will read, without building the grid.
    @details A staged PICGRID, when one exists, is authoritative. Otherwise a file grid's
             header is read, a programmatic grid's cell counts are converted to nodes,
             and a `grid_gen` grid's cell counts are resolved by grid.gen's own
             parameter precedence without generating any coordinates.
    @param[in] case_cfg Parsed case configuration.
    @param[in] case_path Path to case.yml, for case-relative paths.
    @param[in] staged_grid Already staged `inputs/grid/grid.run`, if any.
    @return List of node-count tuples, or None when the dimensions cannot be determined.
    """
    grid_cfg = case_cfg.get("grid") or {}
    expected_nblk = int(((case_cfg.get("models") or {}).get("domain") or {}).get("blocks", 1))
    case_dir = os.path.dirname(os.path.abspath(case_path))
    mode = grid_cfg.get("mode")
    try:
        if staged_grid and os.path.isfile(staged_grid):
            return read_picgrid_header_dimensions(staged_grid, expected_nblk)
        if mode == "file":
            return read_picgrid_header_dimensions(
                _resolve_case_relative_path(grid_cfg["source_file"], case_dir), expected_nblk)
        if mode == "programmatic_c":
            settings = translate_programmatic_grid_settings(grid_cfg.get("programmatic_settings") or {})
            return [(settings["im"], settings["jm"], settings["km"])]
        if mode == "grid_gen":
            generator = grid_cfg.get("generator") or {}
            if generator.get("script"):
                return None
            tokens = ["-c", _resolve_case_relative_path(generator["config_file"], case_dir)]
            if generator.get("grid_type"):
                tokens.append(str(generator["grid_type"]))
            tokens.extend(str(token) for token in (generator.get("cli_args") or []))
            grid_gen = load_generator_module("grid.gen", "picurv_grid_generator")
            with contextlib.redirect_stdout(StringIO()), contextlib.redirect_stderr(StringIO()):
                _, params = grid_gen.resolve_grid_parameters(tokens)
            return [(params.ncells_i + 1, params.ncells_j + 1, params.ncells_k + 1)]
    except (SystemExit, Exception):
        # Staging reports a malformed grid in its own terms; this check only adds to it.
        return None
    return None
 
 
def case_declares_periodic_axis(case_cfg: dict) -> bool:
    """!
    @brief Whether any face of any block is PERIODIC, which sets the DMDA stencil width.
    @param[in] case_cfg Parsed case configuration.
    @return True when grid setup will use stencil width 3 on every axis.
    """
    try:
        blocks = validate_and_prepare_boundary_conditions(case_cfg)
    except ValueError:
        return False
    return any(entry.get("type") == "PERIODIC" for block in blocks for entry in block)
 
 
def da_processor_layout_problems(grid_cfg: dict, num_procs: "int | None",
                                 block_dims: "list | None" = None, solver_cfg: "dict | None" = None,
                                 any_periodic: bool = False, source: "str | None" = None) -> list:
    """!
    @brief Problems with a user-set DMDA layout that would abort grid setup.
    @details Mirrors `InitializeAllGridDMs()` in src/grid.c: each coarser level holds
             (IM + 1) / 2 nodes on an axis that is not semi-coarsened, the DMDA carries
             IM + 1 points, and PETSc's default split gives the smallest rank
             points // ranks of them. Grid setup requires that to reach the stencil
             width, which is 3 on every axis when any face is periodic and 2 otherwise.
             Only the coarsest level can fail, because every finer level is aligned to
             twice its widths.
    @param[in] grid_cfg The case's grid block.
    @param[in] num_procs MPI processes the solve will launch, or None when unknown (validate
               without a cluster profile), which skips only the product check.
    @param[in] block_dims Per-block node counts, or None to skip the multigrid check.
    @param[in] solver_cfg Parsed solver.yml, for the multigrid levels and semi-coarsening.
    @param[in] any_periodic Whether any face is PERIODIC.
    @param[in] source Where the layout was given, as `--ni/--nj/--nk` or
               `cluster.yml execution.decomposition`; None for case.yml's own keys.
    @return List of messages; empty when the layout is usable or not set.
    """
    layout = resolve_grid_da_processor_layout(grid_cfg)
    if source == "--ni/--nj/--nk":
        names = dict(zip(GRID_DA_PROCESSOR_KEYS, ("--ni", "--nj", "--nk")))
        together = "--ni x --nj x --nk"
    elif source:
        names = {key: f"{source}.{axis}" for key, axis in zip(GRID_DA_PROCESSOR_KEYS, "ijk")}
        together = f"{source} (i, j, k)"
    else:
        names = {key: f"grid.{key}" for key in GRID_DA_PROCESSOR_KEYS}
        together = "grid.da_processors_x/y/z"
    if not layout or (num_procs is not None and num_procs <= 1):
        return []
    problems = []
    if num_procs is not None and all(layout.get(key) is not None for key in GRID_DA_PROCESSOR_KEYS):
        total_layout = 1
        for key in GRID_DA_PROCESSOR_KEYS:
            total_layout *= layout[key]
        if total_layout != num_procs:
            printable = " x ".join(str(layout[key]) for key in GRID_DA_PROCESSOR_KEYS)
            problems.append(
                "DMDA processor layout mismatch: "
                f"{together} is {printable} (product {total_layout}), "
                f"but this run requests {num_procs} MPI processes. "
                "Give values whose product equals the requested MPI process count, or "
                "remove all three settings to let PICurv choose the layout."
            )
    if not block_dims:
        return problems
    multigrid = (((solver_cfg or {}).get("poisson_solver") or {}).get("multigrid") or {})
    levels = int(multigrid.get("levels", 3))
    semi = multigrid.get("semi_coarsening") or {}
    stencil = 3 if any_periodic else 2
    for block, dims in enumerate(block_dims):
        for axis, key, nodes in zip("ijk", GRID_DA_PROCESSOR_KEYS, dims):
            ranks = layout.get(key)
            if ranks is None:
                continue
            coarse = nodes
            if str(semi.get(axis, False)).strip().lower() not in ("true", "1", "yes"):
                for _ in range(levels - 1):
                    coarse = (coarse + 1) // 2
            points = coarse + 1
            if points // ranks < stencil:
                problems.append(
                    f"{names[key]} = {ranks} is too many ranks for block {block}'s "
                    f"{axis} axis at {levels} multigrid levels: the coarsest level has "
                    f"{points} points there, so a rank gets {points // ranks}, below the "
                    f"stencil width {stencil}"
                    + (" (3 on every axis because a face is PERIODIC)" if any_periodic else "")
                    + f". Grid setup would abort with 'Local width ... is smaller than "
                    f"stencil width'. Use at most {max(points // stencil, 1)} rank(s) on "
                    "this axis, or lower poisson_solver.multigrid.levels."
                )
    return problems
 
 
def normalize_decomposition_args(args) -> None:
    """!
    @brief Resolve `-n` and the optional `--ni/--nj/--nk` of `picurv run` into one rank count.
    @details The three counts go together. Given them, `-n` defaults to their product and
             must equal it when also given; without them, `-n` defaults to 1. Sets
             `args.num_procs` and `args.decomposition` (a tuple or None).
    @param[in,out] args Parsed `picurv run` arguments.
    """
    parts = [getattr(args, key, None) for key in ("ni", "nj", "nk")]
    args.decomposition = None
    if any(part is not None for part in parts):
        if any(part is None or part <= 0 for part in parts):
            fail_cli_usage("--ni, --nj and --nk are given together, as positive integers.")
        product = parts[0] * parts[1] * parts[2]
        if args.num_procs is None:
            args.num_procs = product
        elif args.num_procs != product:
            fail_cli_usage(f"--ni x --nj x --nk is {parts[0]} x {parts[1]} x {parts[2]} = {product} ranks, "
                           f"but -n is {args.num_procs}; give one or make them agree.")
        args.decomposition = tuple(parts)
    if args.num_procs is None:
        args.num_procs = 1
    if args.num_procs < 1:
        fail_cli_usage("-n must be a positive integer.")
 
 
def _decomposition_layout(layout) -> dict:
    """!
    @brief Express an (ni, nj, nk) tuple as the da_processors mapping the layout checks read.
    @param[in] layout Rank counts along i, j, k.
    @return {"da_processors_x": ni, "da_processors_y": nj, "da_processors_z": nk}.
    """
    return dict(zip(GRID_DA_PROCESSOR_KEYS, layout))
 
 
def choose_decomposition(num_procs: int, block_dims: list, solver_cfg: "dict | None",
                         any_periodic: bool):
    """!
    @brief Choose the MPI decomposition of a structured grid for a rank count.
    @details Every ordered (ni, nj, nk) with product `num_procs` that grid setup accepts at
             the multigrid levels in use (da_processor_layout_problems) is a candidate. The
             one cutting the least grid area between ranks wins, so a thin axis, such as the
             i axis of a 2D case, is not split while another can be; ties go to the most even
             split, then to more ranks on k, then on j.
    @param[in] num_procs MPI ranks.
    @param[in] block_dims Per-block node counts.
    @param[in] solver_cfg Parsed solver.yml, for the multigrid levels and semi-coarsening.
    @param[in] any_periodic Whether any face is PERIODIC, which sets the stencil width.
    @return (ni, nj, nk), or None when no decomposition is feasible.
    """
    best = None
    for ni in range(1, num_procs + 1):
        if num_procs % ni:
            continue
        for nj in range(1, num_procs // ni + 1):
            if (num_procs // ni) % nj:
                continue
            layout = (ni, nj, num_procs // ni // nj)
            if da_processor_layout_problems(_decomposition_layout(layout), num_procs, block_dims,
                                            solver_cfg, any_periodic):
                continue
            cut = imbalance = 0.0
            for dims in block_dims:
                cells = [max(d - 1, 1) for d in dims]
                cut += sum((layout[a] - 1) * cells[(a + 1) % 3] * cells[(a + 2) % 3] for a in range(3))
                largest = 1.0
                for a in range(3):
                    largest *= -(-cells[a] // layout[a])
                imbalance = max(imbalance, largest * num_procs / (cells[0] * cells[1] * cells[2]))
            key = (cut, imbalance, -layout[2], -layout[1])
            if best is None or key < best[0]:
                best = (key, layout)
    return best[1] if best else None
 
 
def resolve_decomposition(num_procs: int, grid_cfg: dict, block_dims: "list | None",
                          solver_cfg: "dict | None", any_periodic: bool,
                          explicit=None, cluster_cfg: "dict | None" = None) -> dict:
    """!
    @brief Resolve the MPI decomposition a stage launches with.
    @details In order of precedence: `--ni/--nj/--nk`, cluster.yml
             `execution.decomposition`, the deprecated case.yml `grid.da_processors_*`, and
             otherwise choose_decomposition(). A set layout must multiply to the rank count
             and pass the multigrid check. When the grid's size cannot be known before the
             run, PETSc chooses.
    @param[in] num_procs MPI ranks of the stage.
    @param[in] grid_cfg The case's grid block.
    @param[in] block_dims Per-block node counts, or None when unknown.
    @param[in] solver_cfg Parsed solver.yml.
    @param[in] any_periodic Whether any face is PERIODIC.
    @param[in] explicit (ni, nj, nk) from the command line, or None.
    @param[in] cluster_cfg Parsed cluster.yml, or None.
    @return {"layout": (ni, nj, nk) or None, "source": str, "problems": [str]}.
    """
    if num_procs <= 1:
        return {"layout": (1, 1, 1), "source": "serial", "problems": []}
    layout, source = None, None
    if explicit:
        layout, source = tuple(explicit), "--ni/--nj/--nk"
    elif isinstance(((cluster_cfg or {}).get("execution") or {}).get("decomposition"), dict):
        spec = cluster_cfg["execution"]["decomposition"]
        if not all(isinstance(spec.get(axis), int) and spec.get(axis) > 0 for axis in "ijk"):
            return {"layout": None, "source": "cluster.yml",
                    "problems": ["cluster.yml execution.decomposition needs positive integers i, j and k."]}
        layout, source = (spec["i"], spec["j"], spec["k"]), "cluster.yml execution.decomposition"
    else:
        legacy = resolve_grid_da_processor_layout(grid_cfg or {})
        if legacy:
            print("[WARNING] case.yml grid.da_processors_x/y/z is deprecated; give the decomposition "
                  "with --ni/--nj/--nk or cluster.yml execution.decomposition.", file=sys.stderr)
            if len(legacy) == 3:
                layout, source = tuple(legacy[key] for key in GRID_DA_PROCESSOR_KEYS), "case.yml (deprecated)"
            else:
                problems = da_processor_layout_problems(grid_cfg, num_procs, block_dims, solver_cfg, any_periodic)
                return {"layout": None, "partial": legacy, "source": "case.yml (deprecated, partial)",
                        "problems": problems}
    if layout is not None:
        return {"layout": layout, "source": source,
                "problems": da_processor_layout_problems(
                    _decomposition_layout(layout), num_procs, block_dims, solver_cfg, any_periodic,
                    None if source.startswith("case.yml") else source)}
    if not block_dims:
        return {"layout": None, "source": "PETSc (grid size unknown before the run)", "problems": []}
    layout = choose_decomposition(num_procs, block_dims, solver_cfg, any_periodic)
    if layout is None:
        feasible = [n for n in range(max(num_procs - 16, 2), num_procs + 17)
                    if choose_decomposition(n, block_dims, solver_cfg, any_periodic)]
        nearest = sorted(feasible, key=lambda n: (abs(n - num_procs), n))[:3]
        return {"layout": None, "source": "auto", "problems": [
            f"No decomposition of {num_procs} ranks fits this grid at its multigrid levels "
            f"(each rank needs at least the stencil width of points on the coarsest level). "
            + (f"Rank counts that fit nearby: {', '.join(map(str, sorted(nearest)))}." if nearest
               else "Lower poisson_solver.multigrid.levels or refine the grid.")]}
    return {"layout": layout, "source": "auto", "problems": []}
 
 
def _decomposition_record(resolved: "dict | None") -> "dict | None":
    """!
    @brief The JSON-serializable record of a resolved decomposition for run metadata.
    @param[in] resolved Result of resolve_decomposition(), or None.
    @return {"layout": [ni, nj, nk] or None, "source": str}, or None.
    """
    if not resolved:
        return None
    return {"layout": list(resolved["layout"]) if resolved.get("layout") else None,
            "source": resolved["source"]}
 
 
def describe_decomposition(resolved: dict, num_procs: int) -> str:
    """!
    @brief One line stating the decomposition a stage launches with.
    @param[in] resolved Result of resolve_decomposition().
    @param[in] num_procs MPI ranks of the stage.
    @return Human-readable description.
    """
    if resolved.get("problems"):
        return f"MPI decomposition: none usable for {num_procs} rank(s) ({resolved['source']})."
    if resolved.get("layout") is None:
        return f"MPI decomposition: chosen by PETSc for {num_procs} rank(s) ({resolved['source']})."
    ni, nj, nk = resolved["layout"]
    return f"MPI decomposition: {ni} x {nj} x {nk} (i x j x k) for {num_procs} rank(s), from {resolved['source']}."
 
 
def append_grid_da_processor_layout(control_lines: list, grid_cfg: dict, num_procs: int,
                                    block_dims: "list | None" = None,
                                    solver_cfg: "dict | None" = None,
                                    any_periodic: bool = False,
                                    explicit=None, cluster_cfg: "dict | None" = None) -> dict:
    """!
    @brief Resolve the solver's MPI decomposition, report it, and append its flags.
    @param[in] control_lines Control-file lines to extend.
    @param[in] grid_cfg The case's grid block.
    @param[in] num_procs MPI ranks of the solve.
    @param[in] block_dims Per-block node counts, for the multigrid check and the choice.
    @param[in] solver_cfg Parsed solver.yml, for the multigrid levels.
    @param[in] any_periodic Whether any face is PERIODIC.
    @param[in] explicit (ni, nj, nk) from the command line, or None.
    @param[in] cluster_cfg Parsed cluster.yml, or None.
    @return The resolved decomposition (resolve_decomposition()).
    @throws ValueError when the decomposition would abort grid setup or none fits.
    """
    resolved = resolve_decomposition(num_procs, grid_cfg, block_dims, solver_cfg, any_periodic,
                                     explicit, cluster_cfg)
    if resolved["problems"]:
        raise ValueError(" ".join(resolved["problems"]))
    print(f"[INFO] {describe_decomposition(resolved, num_procs)}")
    layout = resolved.get("layout")
    if num_procs > 1 and layout is not None:
        control_lines.extend(f"-{key} {value}" for key, value in zip(GRID_DA_PROCESSOR_KEYS, layout))
    elif num_procs > 1 and resolved.get("partial"):
        control_lines.extend(f"-{key} {value}" for key, value in resolved["partial"].items())
    return resolved
 
def normalize_momentum_solver_type(value: str) -> str:
    """!
    @brief Maps canonical user-facing momentum solver names to C-enum CLI values.
    @param[in] value Canonical momentum solver string from YAML.
    @return Canonical value accepted by -mom_solver_type.
    @throws ValueError if the input cannot be mapped.
    """
    # Only implemented YAML values belong here. Extend only with matching C enum/parser/dispatch support.
    if value is None:
        raise ValueError("momentum solver type cannot be None")
 
    raw = str(value).strip()
    mapped = {
        "Explicit RK4": "EXPLICIT_RK",
        "Dual Time Picard Jameson RK": "DUALTIME_PICARD_JAMESON_RK",
        "Dual Time Picard RK4": "DUALTIME_PICARD_JAMESON_RK",
        "Newton Krylov": "newton_krylov",
    }.get(raw)
    if mapped is None:
        raise ValueError(
            f"Unknown momentum solver '{value}'. Use one of: "
            "'Explicit RK4', 'Dual Time Picard Jameson RK', 'Newton Krylov'."
        )
    return mapped
 
 
def validate_newton_krylov_config(cfg: dict) -> dict:
    """!
    @brief Validate and normalize the structured Newton--Krylov solver block.
    @param[in] cfg Structured `momentum_solver.newton_krylov` mapping.
    @return Normalized copy containing only supported structured fields.
    """
    root = "momentum_solver.newton_krylov"
    if not isinstance(cfg, dict):
        raise ValueError(f"{root} must be a mapping.")
 
    unknown = sorted(set(cfg) - {
        "jacobian", "preconditioner", "nonlinear_solver", "linear_solver",
    })
    if unknown:
        raise ValueError(f"{root} has unsupported key(s): {unknown}.")
 
    normalized = {}
 
    def _mapping(parent: dict, key: str, path: str) -> dict:
        """!
        @brief Read and validate one optional nested Newton mapping.
        @param[in] parent Parent mapping.
        @param[in] key Nested key to read.
        @param[in] path User-facing YAML path for errors.
        @return Nested mapping, or an empty mapping when omitted.
        """
        value = parent.get(key, {})
        if value is None or not isinstance(value, dict):
            raise ValueError(f"{path} must be a mapping when provided.")
        return value
 
    def _method(value, path: str) -> str:
        """!
        @brief Normalize one nonempty PETSc solver/type token.
        @param[in] value YAML token value.
        @param[in] path User-facing YAML path for errors.
        @return Lowercase PETSc token.
        """
        if not isinstance(value, str) or not value.strip():
            raise ValueError(f"{path} must be a non-empty string.")
        return value.strip().lower()
 
    def _tolerance(value, path: str):
        """!
        @brief Validate one finite nonnegative tolerance.
        @param[in] value YAML tolerance value.
        @param[in] path User-facing YAML path for errors.
        @return Original validated value.
        """
        if isinstance(value, bool):
            raise ValueError(f"{path} must be numeric and nonnegative.")
        try:
            numeric = float(value)
        except (TypeError, ValueError) as exc:
            raise ValueError(f"{path} must be numeric and nonnegative.") from exc
        if not math.isfinite(numeric) or numeric < 0.0:
            raise ValueError(f"{path} must be numeric and nonnegative.")
        return value
 
    def _positive_integer(value, path: str):
        """!
        @brief Validate one positive integer count.
        @param[in] value YAML count value.
        @param[in] path User-facing YAML path for errors.
        @return Original validated integer.
        """
        if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
            raise ValueError(f"{path} must be a positive integer.")
        return value
 
    jacobian_path = f"{root}.jacobian"
    if "jacobian" not in cfg:
        normalized["jacobian"] = {
            "type": "finite_difference",
            "finite_difference": {"mode": "matrix_free"},
        }
    else:
        jacobian = _mapping(cfg, "jacobian", jacobian_path)
        unknown = sorted(set(jacobian) - {"type", "finite_difference"})
        if unknown:
            raise ValueError(f"{jacobian_path} has unsupported key(s): {unknown}.")
        if "type" not in jacobian:
            raise ValueError(f"{jacobian_path}.type is required when {jacobian_path} is provided.")
        jacobian_type = _method(jacobian["type"], f"{jacobian_path}.type")
        if jacobian_type == "frozen_momentum_approximation":
            raise ValueError(
                f"{jacobian_path}.type 'frozen_momentum_approximation' is not implemented."
            )
        if jacobian_type != "finite_difference":
            raise ValueError(
                f"{jacobian_path}.type currently supports only 'finite_difference' "
                f"(got '{jacobian_type}')."
            )
        finite_difference_path = f"{jacobian_path}.finite_difference"
        if "finite_difference" not in jacobian:
            raise ValueError(
                f"{finite_difference_path} is required when {jacobian_path}.type is "
                "'finite_difference'."
            )
        finite_difference = _mapping(
            jacobian, "finite_difference", finite_difference_path
        )
        unknown = sorted(set(finite_difference) - {"mode"})
        if unknown:
            raise ValueError(f"{finite_difference_path} has unsupported key(s): {unknown}.")
        if "mode" not in finite_difference:
            raise ValueError(f"{finite_difference_path}.mode is required.")
        finite_difference_mode = _method(
            finite_difference["mode"], f"{finite_difference_path}.mode"
        )
        if finite_difference_mode == "colored_sparse":
            raise ValueError(
                f"{finite_difference_path}.mode 'colored_sparse' is not implemented."
            )
        if finite_difference_mode != "matrix_free":
            raise ValueError(
                f"{finite_difference_path}.mode currently supports only 'matrix_free' "
                f"(got '{finite_difference_mode}')."
            )
        normalized["jacobian"] = {
            "type": jacobian_type,
            "finite_difference": {"mode": finite_difference_mode},
        }
 
    preconditioner = _mapping(
        cfg, "preconditioner", f"{root}.preconditioner"
    ) if "preconditioner" in cfg else {}
    preconditioner_path = f"{root}.preconditioner"
    unknown = sorted(set(preconditioner) - {"model", "structure"})
    if unknown:
        raise ValueError(f"{preconditioner_path} has unsupported key(s): {unknown}.")
    if "preconditioner" in cfg and "model" not in preconditioner:
        raise ValueError(
            f"{preconditioner_path}.model is required when {preconditioner_path} is provided."
        )
    model = _method(preconditioner.get("model", "none"), f"{preconditioner_path}.model")
    if model not in NEWTON_KRYLOV_PRECONDITIONER_MODELS:
        raise ValueError(
            f"{preconditioner_path}.model supports only 'none' or 'frozen_momentum_jacobian'."
        )
    structure = _mapping(
        preconditioner, "structure", f"{preconditioner_path}.structure"
    ) if "structure" in preconditioner else {}
    unknown = sorted(set(structure) - {"type"})
    if unknown:
        raise ValueError(f"{preconditioner_path}.structure has unsupported key(s): {unknown}.")
    structure_type = _method(
        structure.get("type", "none"), f"{preconditioner_path}.structure.type"
    )
    if structure_type not in NEWTON_KRYLOV_PRECONDITIONER_STRUCTURES:
        raise ValueError(
            f"{preconditioner_path}.structure.type supports only 'none' or 'point_block'."
        )
    if model == "none" and structure:
        raise ValueError(f"{preconditioner_path}.model 'none' does not accept a matrix structure.")
    if model == "frozen_momentum_jacobian" and structure_type != "point_block":
        raise ValueError(
            f"{preconditioner_path}.model 'frozen_momentum_jacobian' requires "
            f"{preconditioner_path}.structure.type 'point_block'."
        )
    normalized["preconditioner"] = {
        "model": model,
        "structure": {"type": structure_type},
    }
 
    nonlinear = _mapping(cfg, "nonlinear_solver", f"{root}.nonlinear_solver")
    nonlinear_path = f"{root}.nonlinear_solver"
    unknown = sorted(set(nonlinear) - {
        "method", "absolute_tolerance", "relative_tolerance", "step_tolerance",
        "max_iterations", "line_search", "eisenstat_walker",
    })
    if unknown:
        raise ValueError(f"{nonlinear_path} has unsupported key(s): {unknown}.")
    nonlinear_out = {}
    if "method" in nonlinear:
        nonlinear_out["method"] = _method(nonlinear["method"], f"{nonlinear_path}.method")
    for key in ("absolute_tolerance", "relative_tolerance", "step_tolerance"):
        if key in nonlinear:
            nonlinear_out[key] = _tolerance(nonlinear[key], f"{nonlinear_path}.{key}")
    if "max_iterations" in nonlinear:
        nonlinear_out["max_iterations"] = _positive_integer(
            nonlinear["max_iterations"], f"{nonlinear_path}.max_iterations"
        )
    if "line_search" in nonlinear:
        line_search = _mapping(nonlinear, "line_search", f"{nonlinear_path}.line_search")
        unknown = sorted(set(line_search) - {"type"})
        if unknown:
            raise ValueError(f"{nonlinear_path}.line_search has unsupported key(s): {unknown}.")
        nonlinear_out["line_search"] = {}
        if "type" in line_search:
            nonlinear_out["line_search"]["type"] = _method(
                line_search["type"], f"{nonlinear_path}.line_search.type"
            )
    if "eisenstat_walker" in nonlinear:
        ew_path = f"{nonlinear_path}.eisenstat_walker"
        ew = _mapping(nonlinear, "eisenstat_walker", ew_path)
        ew_keys = {
            "enabled", "version", "initial_relative_tolerance",
            "maximum_relative_tolerance", "gamma", "exponent",
            "safeguard_exponent", "safeguard_threshold",
        }
        unknown = sorted(set(ew) - ew_keys)
        if unknown:
            raise ValueError(f"{ew_path} has unsupported key(s): {unknown}.")
        enabled = ew.get("enabled", True)
        if not isinstance(enabled, bool):
            raise ValueError(f"{ew_path}.enabled must be boolean.")
        if not enabled and set(ew) - {"enabled"}:
            raise ValueError(f"{ew_path} parameters require enabled: true.")
        ew_out = {"enabled": enabled}
        if "version" in ew:
            version = ew["version"]
            if isinstance(version, bool) or not isinstance(version, int) or version not in {1, 2, 3, 4}:
                raise ValueError(f"{ew_path}.version must be one of 1, 2, 3, or 4.")
            ew_out["version"] = version
        bounds = {
            "initial_relative_tolerance": (0.0, 1.0, False, True),
            "maximum_relative_tolerance": (0.0, 1.0, False, True),
            "gamma": (0.0, 1.0, False, False),
            "exponent": (1.0, 2.0, True, False),
            "safeguard_threshold": (0.0, 1.0, True, True),
        }
        for key, (lower, upper, lower_open, upper_open) in bounds.items():
            if key not in ew:
                continue
            value = _tolerance(ew[key], f"{ew_path}.{key}")
            numeric = float(value)
            valid_lower = numeric > lower if lower_open else numeric >= lower
            valid_upper = numeric < upper if upper_open else numeric <= upper
            if not (valid_lower and valid_upper):
                brackets = ("(" if lower_open else "[") + f"{lower}, {upper}" + (")" if upper_open else "]")
                raise ValueError(f"{ew_path}.{key} must be in {brackets}.")
            ew_out[key] = value
        if "safeguard_exponent" in ew:
            ew_out["safeguard_exponent"] = _tolerance(
                ew["safeguard_exponent"], f"{ew_path}.safeguard_exponent"
            )
        nonlinear_out["eisenstat_walker"] = ew_out
    normalized["nonlinear_solver"] = nonlinear_out
 
    linear = _mapping(cfg, "linear_solver", f"{root}.linear_solver")
    linear_path = f"{root}.linear_solver"
    unknown = sorted(set(linear) - {
        "method", "absolute_tolerance", "relative_tolerance", "max_iterations",
        "gmres", "preconditioner",
    })
    if unknown:
        raise ValueError(f"{linear_path} has unsupported key(s): {unknown}.")
    linear_out = {}
    method = "gmres"
    if "method" in linear:
        method = _method(linear["method"], f"{linear_path}.method")
        linear_out["method"] = method
    for key in ("absolute_tolerance", "relative_tolerance"):
        if key in linear:
            linear_out[key] = _tolerance(linear[key], f"{linear_path}.{key}")
    if "max_iterations" in linear:
        linear_out["max_iterations"] = _positive_integer(
            linear["max_iterations"], f"{linear_path}.max_iterations"
        )
    if "gmres" in linear:
        gmres = _mapping(linear, "gmres", f"{linear_path}.gmres")
        unknown = sorted(set(gmres) - {"restart"})
        if unknown:
            raise ValueError(f"{linear_path}.gmres has unsupported key(s): {unknown}.")
        linear_out["gmres"] = {}
        if "restart" in gmres:
            if method not in GMRES_RESTART_METHODS:
                raise ValueError(
                    f"{linear_path}.gmres.restart is valid only when {linear_path}.method "
                    "is one of 'gmres', 'fgmres', or 'lgmres'."
                )
            linear_out["gmres"]["restart"] = _positive_integer(
                gmres["restart"], f"{linear_path}.gmres.restart"
            )
    if "preconditioner" in linear:
        compatibility_pc = _mapping(linear, "preconditioner", f"{linear_path}.preconditioner")
        unknown = sorted(set(compatibility_pc) - {"type"})
        if unknown:
            raise ValueError(f"{linear_path}.preconditioner has unsupported key(s): {unknown}.")
        if "type" in compatibility_pc:
            pc_type = _method(compatibility_pc["type"], f"{linear_path}.preconditioner.type")
            if pc_type != "none":
                raise ValueError(
                    f"{linear_path}.preconditioner.type is a deprecated compatibility alias "
                    "and supports only 'none'."
                )
            if "preconditioner" in cfg and model != "none":
                raise ValueError(
                    f"{linear_path}.preconditioner.type 'none' conflicts with "
                    f"{preconditioner_path}.model '{model}'."
                )
            warnings.warn(
                f"{linear_path}.preconditioner.type is deprecated; use "
                f"{preconditioner_path}.model: none.",
                FutureWarning,
                stacklevel=3,
            )
    normalized["linear_solver"] = linear_out
    return normalized
 
def normalize_solution_convergence_mode(value: str) -> str:
    """!
    @brief Normalizes the solution-convergence mode selector to the C-side canonical string.
    @param[in] value Human-readable solution-convergence mode selector.
    @return Canonical string accepted by `-solution_convergence_mode`.
    @throws ValueError if the input cannot be mapped.
    """
    if value is None:
        raise ValueError("solution_convergence.mode cannot be None")
 
    normalized = str(value).strip().lower().replace("-", "_").replace(" ", "_")
    aliases = {
        "steady_deterministic": "STEADY_DETERMINISTIC",
        "periodic_deterministic": "PERIODIC_DETERMINISTIC",
        "statistical_steady": "STATISTICAL_STEADY",
        "transient": "TRANSIENT",
    }
    mapped = aliases.get(normalized)
    if mapped is None:
        raise ValueError(
            f"Unknown solution_convergence.mode '{value}'. Use one of: "
            "'steady_deterministic', 'periodic_deterministic', 'statistical_steady', 'transient'."
        )
    return mapped
 
def normalize_field_init_mode(value: str) -> int:
    """!
    @brief Maps canonical field init mode names to C enum/int codes (-finit).
    @param[in] value Canonical field initialization mode.
    @return Canonical integer code accepted by -finit.
    @throws ValueError if the input cannot be mapped.
    """
    # Canonical selector map for field initialization modes.
    if value is None:
        raise ValueError("field initialization mode cannot be None")
 
    mapped = {
        "Zero": 0,
        "Constant": 1,
        "Poiseuille": 2,
    }.get(str(value).strip())
    if mapped is None:
        raise ValueError(
            f"Unknown initial_conditions mode '{value}'. Use one of: 'Zero', 'Constant', 'Poiseuille'."
        )
    return mapped
 
def normalize_initial_condition_field(value: str) -> "tuple[str, int]":
    """!
    @brief Normalize a file IC field selector to its staged basename and C enum value.
    @param[in] value User-facing Ucat or Ucont selector.
    @return Tuple of staged field basename and C enum value.
    """
    normalized = str(value or "").strip().lower()
    if normalized == "ucat":
        return "ufield", 0
    if normalized == "ucont":
        return "vfield", 1
    raise ValueError("initial_conditions.field must be 'Ucat' or 'Ucont'.")
 
 
#: Physical dimension of a staged initial-condition payload, by C field code.
IC_PAYLOAD_DIMENSIONS = {0: VELOCITY, 1: VOLUME_FLUX}
 
 
def resolve_ic_payload_provenance(ic: dict, field_code: int) -> dict:
    """!
    @brief Resolve which scales a file-backed initial condition was written in.
    @details A payload is physical unless it declares otherwise. A field saved by an
             earlier run is in that run's solver units, so it names the case that wrote
             it (`source_case`) or gives its scales directly, the same way a
             `field_slice` inlet profile does.
    @param[in] ic Initial-condition YAML mapping.
    @param[in] field_code C field code: 0 for Ucat, 1 for Ucont.
    @return Mapping with `source_case`, or `velocity_scale` and `length_scale`, or empty.
    @throws ValueError on a conflicting, incomplete, or invalid declaration.
    """
    source_case = ic.get("source_case")
    has_scale = any(key in ic for key in ("velocity_scale", "length_scale"))
    if source_case is not None:
        if has_scale:
            raise ValueError("initial_conditions: give source_case or velocity_scale/length_scale, not both.")
        if not isinstance(source_case, str) or not source_case.strip():
            raise ValueError("initial_conditions.source_case must be a non-empty path.")
        return {"source_case": source_case.strip()}
    if not has_scale:
        return {}
    if "velocity_scale" not in ic:
        raise ValueError("initial_conditions.length_scale requires velocity_scale.")
    provenance = {"velocity_scale": _to_finite_float(ic["velocity_scale"], "initial_conditions.velocity_scale"),
                  "length_scale": 1.0}
    if field_code == 1:
        if "length_scale" not in ic:
            raise ValueError("initial_conditions.length_scale is required for a Ucont payload in solver units.")
        provenance["length_scale"] = _to_finite_float(ic["length_scale"], "initial_conditions.length_scale")
    elif "length_scale" in ic:
        raise ValueError("initial_conditions.length_scale applies only to a Ucont payload.")
    if provenance["velocity_scale"] <= 0.0 or provenance["length_scale"] <= 0.0:
        raise ValueError("initial_conditions.velocity_scale and length_scale must be positive.")
    return provenance
 
 
def ic_payload_divisor(resolved_ic: dict, case_dir: str) -> float:
    """!
    @brief Return the factor a file-backed initial condition is divided by when staged.
    @details A physical payload is divided by its dimension's reference scale. A payload in
             another run's solver units is first returned to physical units by that run's
             scale, so the two factors combine into one ratio.
    @param[in] resolved_ic Resolved `mode: file` initial condition.
    @param[in] case_dir Directory that relative `source_case` paths resolve against.
    @return Positive divisor; 1.0 when the payload already matches this case's solver units.
    """
    dimension = IC_PAYLOAD_DIMENSIONS[resolved_ic["field_code"]]
    provenance = resolved_ic.get("payload_provenance") or {}
    source_scales = {"length_ref": 1.0, "velocity_ref": 1.0}
    if "source_case" in provenance:
        source_path = _resolve_case_relative_path(provenance["source_case"], case_dir)
        source_scales = resolve_reference_scales(read_yaml_file(source_path))
    elif provenance:
        source_scales = {"length_ref": provenance["length_scale"], "velocity_ref": provenance["velocity_scale"]}
    return reference_scale(dimension, resolved_ic["scales"]) / reference_scale(dimension, source_scales)
 
GENERATED_IC_PROVIDERS = {
    "channel_spectral_velocity": {"requires_grid": True, "requires_fresh_3d": True},
    "duct_spectral_velocity": {"requires_grid": True, "requires_fresh_3d": True},
    "stability_mode_velocity": {"requires_grid": True},
    "ic_gen": {
        "requires_grid": True,
        "diagnostic_artifacts": (),
    },
    "spectral_random_velocity": {
        "requires_grid": True,
        "requires_periodic_geometric": True,
        "requires_fresh_3d": True,
        "diagnostic_artifacts": (
            ("summary_json", os.path.join(CANONICAL_RUN_PATHS["metrics"], "initial_condition_summary.json")),
            ("spectrum_csv", INITIAL_CONDITION_SPECTRUM_RELPATH),
        ),
    },
}
GENERATED_IC_PROVIDERS["resampled_velocity"] = GENERATED_IC_PROVIDERS["spectral_random_velocity"]
 
 
def is_generated_ic_provider(resolved_ic: dict) -> bool:
    """!
    @brief Return whether a resolved IC is backed by a registered file generator.
    @param[in] resolved_ic Resolved initial-condition contract.
    @return True for a registered generated-file provider.
    """
    return resolved_ic.get("kind") in GENERATED_IC_PROVIDERS
 
 
def resolve_fluid_scaling(case_cfg: dict) -> dict:
    """!
    @brief Resolve the shared physical and nondimensional fluid scaling contract.
    @param[in] case_cfg Parsed case configuration.
    @return Resolved scaling, viscosity, and Reynolds-number quantities.
    """
    properties = case_cfg["properties"]
    scaling = properties["scaling"]
    fluid = properties["fluid"]
    length_ref = _to_finite_float(scaling["length_ref"], "properties.scaling.length_ref")
    velocity_ref = _to_finite_float(scaling["velocity_ref"], "properties.scaling.velocity_ref")
    density = _to_finite_float(fluid["density"], "properties.fluid.density")
    dynamic_viscosity = _to_finite_float(fluid["viscosity"], "properties.fluid.viscosity")
    if length_ref <= 0.0 or velocity_ref <= 0.0 or density <= 0.0 or dynamic_viscosity < 0.0:
        raise ValueError("length_ref, velocity_ref, and density must be positive; viscosity must be non-negative.")
    reynolds = density*velocity_ref*length_ref/dynamic_viscosity if dynamic_viscosity else float("inf")
    return {
        "length_ref": length_ref, "velocity_ref": velocity_ref, "density": density,
        "dynamic_viscosity": dynamic_viscosity, "reynolds": reynolds,
        "physical_kinematic_viscosity": dynamic_viscosity/density,
        "nondimensional_kinematic_viscosity": dynamic_viscosity/(density*velocity_ref*length_ref),
    }
 
 
def load_generator_module(script_name: str, module_name: str):
    """!
    @brief Load one of the extensionless scripts under `generators/` as a module.
    @param[in] script_name File name under `generators/`, e.g. `ic.gen`.
    @param[in] module_name Name to register the loaded module under.
    @return Loaded module.
    """
    from importlib.machinery import SourceFileLoader
    loader = SourceFileLoader(module_name, os.path.join(GENERATORS_PATH, script_name))
    spec = importlib.util.spec_from_loader(loader.name, loader)
    module = importlib.util.module_from_spec(spec)
    loader.exec_module(module)
    return module
 
 
def load_ic_generator_module():
    """!
    @brief Load `generators/ic.gen`, which owns the expression language and the IC providers.
    @return Loaded module.
    """
    return load_generator_module("ic.gen", "picurv_ic_generator")
 
 
#: Particle fields a case may give an initial value, with their component counts: the
#: fields the particle carries (catalog capability `USER_INITIALIZE`). Every other particle
#: field is re-derived from the Eulerian fields or from particle location, so a configured
#: value would not survive. `tests/test_particle_fields.py` checks this against the catalog.
PARTICLE_SETTABLE_FIELDS = {"Psi": 1}
 
 
def normalize_particle_fields(fields_cfg) -> list:
    """!
    @brief Validate `models.physics.particles.fields` and lower each value to expressions.
    @details A value is a number, an expression, or a mapping with `params` and either
             `value` or `background` with `regions`; a field with several components takes a
             list of values, one per component. Expressions use physical coordinates
             `x y z`, domain-normalized `xn yn zn`, `pid`, and physical time `t`, and may
             draw with `uniform()`/`normal()`.
    @param[in] fields_cfg The `fields` mapping.
    @return List of `{"name", "expressions"}` in configuration order.
    @throws ValueError on an unknown field, a wrong component count, or an invalid value.
    """
    if not isinstance(fields_cfg, dict) or not fields_cfg:
        raise ValueError("models.physics.particles.fields must be a non-empty mapping of field names to values.")
    ic_gen = load_ic_generator_module()
    normalized = []
    for name, spec in fields_cfg.items():
        if name not in PARTICLE_SETTABLE_FIELDS:
            raise ValueError(
                f"models.physics.particles.fields.{name}: not a field a case can set; the runtime "
                f"re-derives it. Settable fields: {sorted(PARTICLE_SETTABLE_FIELDS)}.")
        components = PARTICLE_SETTABLE_FIELDS[name]
        specs = spec if components > 1 else [spec]
        if not isinstance(specs, list) or len(specs) != components:
            raise ValueError(f"models.physics.particles.fields.{name} takes {components} component values.")
        expressions = [
            ic_gen.lower_value(item, ic_gen.PARTICLE_EXPRESSION_NAMES, random=True,
                               where=f"models.physics.particles.fields.{name}")
            for item in specs
        ]
        normalized.append({"name": name, "expressions": expressions})
    return normalized
 
 
def ic_provider_params_to_solver_units(generator: str, params: dict, scales: dict) -> dict:
    """!
    @brief Convert a provider's validated physical parameters to solver units.
    @details Providers work on the staged nondimensional grid, so every dimensional
             parameter recorded in `IC_PARAM_QUANTITIES` is converted before the provider
             runs. Nested mappings are addressed by dotted name.
    @param[in] generator Provider identifier.
    @param[in] params Validated parameter mapping in physical units.
    @param[in] scales Reference scales, as returned by `resolve_reference_scales()`.
    @return A copy of the mapping with dimensional values in solver units.
    """
    converted = copy.deepcopy(params)
    for name, quantity in IC_PARAM_QUANTITIES[generator].items():
        if quantity[1] != "cli":
            continue
        *parents, leaf = name.split(".")
        holder = converted
        for parent in parents:
            holder = holder.get(parent) if isinstance(holder, dict) else None
        if isinstance(holder, dict) and leaf in holder:
            holder[leaf] = quantity_to_solver_units(
                holder[leaf], quantity, scales, f"initial_conditions.params.{name}")
    return converted
 
 
def resolve_resampled_velocity_params(params: dict, prepared_blocks, scales: dict, provider_context=None) -> dict:
    """!
    @brief Validate `resampled_velocity` parameters and convert them to the provider contract.
    @details The provider brings an external triply periodic velocity field onto the case's
             grid. Its box must be the case's box; the source's container, layout, and sample
             positions are declared because no standard format records them all.
    @param[in] params Raw provider parameters, physical units.
    @param[in] prepared_blocks Normalized boundary-condition blocks.
    @param[in] scales Reference scales.
    @param[in] provider_context Optional conductor-derived provider context.
    @return Resolved initial-condition contract; `source_file` stays as written and is
            resolved against the workspace when the provider runs.
    """
    name = "resampled_velocity"
    if prepared_blocks and len(prepared_blocks) != 1:
        raise ValueError(f"{name} requires exactly one grid block.")
    if not prepared_blocks or len(prepared_blocks[0]) != 6 or any(
        bc.get("type") != "PERIODIC" or bc.get("handler") != "geometric" for bc in prepared_blocks[0]
    ):
        raise ValueError(f"{name} requires PERIODIC/geometric boundaries on all six faces; "
                         "wall-bounded sources are not supported yet.")
    unknown = sorted(set(params) - RESAMPLED_VELOCITY_PARAMS)
    if unknown:
        raise ValueError(f"{name} has unsupported params: {unknown}.")
    # Ucont is the default: face-centre samples projected with PICurv's face-difference
    # operator keep the most energy through the runtime's reconstruction and need the
    # smallest projection; Ucat stages cell centres like the synthetic providers do.
    field_name, field_code = normalize_initial_condition_field(params.get("field", "Ucont"))
    source_file = params.get("source_file")
    if not isinstance(source_file, str) or not source_file.strip():
        raise ValueError(f"{name} requires params.source_file, the field to import.")
    fmt = str(params.get("format", "")).lower()
    if fmt not in RESAMPLED_VELOCITY_LAYOUT_KEYS:
        raise ValueError(f"{name} params.format must be one of {sorted(RESAMPLED_VELOCITY_LAYOUT_KEYS)}.")
    cells = params.get("cells")
    if cells is not None:
        if (not isinstance(cells, list) or len(cells) != 3
                or any(isinstance(c, bool) or not isinstance(c, int) or c < 4 for c in cells)):
            raise ValueError(f"{name} params.cells must list the source's sample counts along x, y, z, "
                             "each an integer of at least 4.")
    elif fmt == "raw":
        raise ValueError(f"{name} with format: raw requires params.cells, the sample counts along x, y, z.")
    box = params.get("box_length")
    if not isinstance(box, list) or len(box) != 3:
        raise ValueError(f"{name} requires params.box_length: the source's periods along x, y, z, "
                         "in physical length.")
    box = [_to_finite_float(value, f"initial_conditions.params.box_length[{index}]")
           for index, value in enumerate(box)]
    if any(value <= 0 for value in box):
        raise ValueError(f"{name} params.box_length values must be positive.")
    offset = params.get("sample_offset", 0.0)
    offset = offset if isinstance(offset, list) else [offset, offset, offset]
    if len(offset) != 3:
        raise ValueError(f"{name} params.sample_offset is one number or three, along x, y, z.")
    offset = [_to_finite_float(value, f"initial_conditions.params.sample_offset[{index}]")
              for index, value in enumerate(offset)]
    if any(value < 0.0 or value >= 1.0 for value in offset):
        raise ValueError(f"{name} params.sample_offset is a fraction of the source spacing in [0, 1): "
                         "0 for samples on the box origin, 0.5 for cell centres.")
    layout = params.get("layout", {})
    if not isinstance(layout, dict):
        raise ValueError(f"{name} params.layout must be a mapping.")
    extra = sorted(set(layout) - RESAMPLED_VELOCITY_LAYOUT_KEYS[fmt])
    if extra:
        raise ValueError(f"{name} layout keys {extra} do not apply to format: {fmt}; "
                         f"it accepts {sorted(RESAMPLED_VELOCITY_LAYOUT_KEYS[fmt])}.")
    normalized_layout = {"fastest_axis": str(layout.get("fastest_axis", "x")).lower(),
                         "components": str(layout.get("components", "interleaved")).lower()}
    if normalized_layout["fastest_axis"] not in RESAMPLED_VELOCITY_FASTEST_AXES:
        raise ValueError(f"{name} layout.fastest_axis must be x (x varies fastest) or z.")
    if normalized_layout["components"] not in RESAMPLED_VELOCITY_COMPONENT_LAYOUTS:
        raise ValueError(f"{name} layout.components must be interleaved (u, v, w at each point) "
                         "or separate (all u, then all v, then all w).")
    if fmt == "raw":
        dtype = str(layout.get("dtype", "")).lower()
        if dtype not in RESAMPLED_VELOCITY_RAW_DTYPES:
            raise ValueError(f"{name} format: raw requires layout.dtype: float32 or float64.")
        byte_order = str(layout.get("byte_order", "native")).lower()
        if byte_order not in RESAMPLED_VELOCITY_BYTE_ORDERS:
            raise ValueError(f"{name} layout.byte_order must be little, big, or native.")
        header = layout.get("header_bytes", 0)
        if isinstance(header, bool) or not isinstance(header, int) or header < 0:
            raise ValueError(f"{name} layout.header_bytes must be a non-negative integer.")
        normalized_layout.update({"dtype": dtype, "byte_order": byte_order, "header_bytes": header})
    elif "datasets" in RESAMPLED_VELOCITY_LAYOUT_KEYS[fmt]:
        datasets = layout.get("datasets")
        if (not isinstance(datasets, list) or len(datasets) not in (1, 3)
                or any(not isinstance(item, str) or not item for item in datasets)):
            raise ValueError(f"{name} format: {fmt} requires layout.datasets: one array name, "
                             "or three for u, v, w.")
        normalized_layout["datasets"] = list(datasets)
    filter_cfg = params.get("filter", {"type": "none"})
    if not isinstance(filter_cfg, dict):
        raise ValueError(f"{name} params.filter must be a mapping.")
    filter_type = str(filter_cfg.get("type", "none")).lower()
    expected = {"none": set(), "sharp": {"cutoff"}, "gaussian": {"width"}, "box": {"width"}}
    if filter_type not in expected:
        raise ValueError(f"{name} filter.type must be one of {sorted(expected)}.")
    if set(filter_cfg) - {"type"} != expected[filter_type]:
        raise ValueError(f"{name} filter.type: {filter_type} takes exactly "
                         f"{sorted(expected[filter_type]) or 'no parameters'}.")
    normalized_filter = {"type": filter_type}
    for key in expected[filter_type]:
        value = _to_finite_float(filter_cfg[key], f"initial_conditions.params.filter.{key}")
        if value <= 0:
            raise ValueError(f"{name} filter.{key} must be positive.")
        normalized_filter[key] = value
    projection = str(params.get("projection", "picurv_discrete")).lower()
    if projection not in RESAMPLED_VELOCITY_PROJECTIONS:
        raise ValueError(f"{name} params.projection must be picurv_discrete, continuum, or none.")
    remove_mean = params.get("remove_mean", True)
    if not isinstance(remove_mean, bool):
        raise ValueError(f"{name} params.remove_mean must be boolean.")
    normalized = {"field": "Ucont" if field_code == 1 else "Ucat", "source_file": source_file,
                  "format": fmt, "box_length": box,
                  "sample_offset": offset, "layout": normalized_layout, "filter": normalized_filter,
                  "projection": projection, "remove_mean": remove_mean}
    if cells is not None:
        normalized["cells"] = list(cells)
    resolved = ic_provider_params_to_solver_units(name, normalized, scales)
    resolved["velocity_divisor"] = float(scales["velocity_ref"])
    return {"finit": 4, "cli_params": {}, "kind": name, "label": name,
            "field_name": field_name, "field_code": field_code,
            "provider_context": dict(provider_context or {}), "params": resolved}
 
 
def normalize_ic_initial_spectra(requested, excluded_axes, generator, required):
    """!
    @brief Validate the spectra a structured IC provider measures on its own output.
    @param[in] requested `params.initial_spectra` as written, or None.
    @param[in] excluded_axes Axes the spectra must not transform (walls, cross-stream).
    @param[in] generator Provider identifier, for messages.
    @param[in] required Whether a nonempty list is mandatory.
    @return Normalized spectrum tasks (an empty list when optional and absent).
    @throws ValueError on an absent required list or an unsupported task.
    """
    if requested is None and not required:
        return []
    if not isinstance(requested, list) or not requested:
        raise ValueError(f"{generator} requires params.initial_spectra: a nonempty list of "
                         "plane_spectrum or line_spectrum tasks over the periodic axes.")
    spectra = normalize_post_spectra_config({"spectra": {"tasks": requested}})
    for task in spectra["tasks"]:
        if task["task"] == "shell_spectrum" or set(task["axes"]) & set(excluded_axes):
            raise ValueError(f"initial spectra must transform only periodic axes of the {generator} IC.")
        if task["block"] != 0 or task["subtract_mean"].startswith("window:") or task["reference"]:
            raise ValueError("initial spectra require block 0, no window mean, and no reference.")
    return spectra["tasks"]
 
 
def resolve_initial_condition_config(ic: dict, prepared_blocks, scales: dict, provider_context=None) -> dict:
    """!
    @brief Resolve legacy and structured initial-condition YAML into one launcher contract.
    @details Every value the user writes is physical; the resolved contract carries solver
             units, or the scales a provider or the staging step needs to reach them.
    @param[in] ic Initial-condition YAML mapping.
    @param[in] prepared_blocks Normalized boundary-condition blocks.
    @param[in] scales Reference scales, as returned by `resolve_reference_scales()`.
    @param[in] provider_context Optional conductor-derived provider context.
    @return Normalized launcher initial-condition contract.
    """
    if not isinstance(ic, dict):
        raise ValueError("properties.initial_conditions must be a mapping.")
    mode = str(ic.get("mode", "")).strip()
 
    # Backward-compatible legacy spelling.
    if mode in LEGACY_FIELD_INIT_SPELLINGS:
        finit_code = normalize_field_init_mode(mode)
        params = resolve_ic_cli_params(ic, finit_code, prepared_blocks, scales)
        if finit_code == 1 and params.pop("ic_coordinate_system", 0) == 1:
            finit_code = 3
        return {"finit": finit_code, "cli_params": params, "kind": "builtin", "label": mode}
 
    normalized_mode = mode.lower().replace("-", "_").replace(" ", "_")
    if normalized_mode == "file":
        if prepared_blocks and len(prepared_blocks) > 1:
            raise ValueError("File-backed initial conditions currently support single-block cases only.")
        source_file = ic.get("source_file")
        if not isinstance(source_file, str) or not source_file.strip():
            raise ValueError("initial_conditions.source_file is required when mode is 'file'.")
        field_name, field_code = normalize_initial_condition_field(ic.get("field"))
        return {
            "finit": 4, "cli_params": {}, "kind": "file", "label": "file",
            "source_file": source_file.strip(), "field_name": field_name, "field_code": field_code,
            "payload_provenance": resolve_ic_payload_provenance(ic, field_code),
            "scales": dict(scales),
        }
    if normalized_mode != "generated":
        raise ValueError("initial_conditions.mode must be 'generated' or 'file'.")
 
    generator = str(ic.get("generator", "")).strip().lower().replace("-", "_").replace(" ", "_")
    params = ic.get("params", {})
    if not isinstance(params, dict):
        raise ValueError("initial_conditions.params must be a mapping.")
    for key in RETIRED_INITIAL_CONDITION_DESTINATION_KEYS:
        if key in params:
            raise ValueError(retired_destination_message("initial_conditions.params", key))
    if generator == "ic_gen":
        if prepared_blocks and len(prepared_blocks) > 1:
            raise ValueError("File-backed initial conditions currently support single-block cases only.")
        script = params.get("script")
        if script is not None and (not isinstance(script, str) or not script.strip()):
            raise ValueError("initial_conditions.params.script must be a non-empty path when provided.")
        field_name, field_code = normalize_initial_condition_field(params.get("field"))
        config_file = params.get("config_file")
        if not isinstance(config_file, str) or not config_file.strip():
            raise ValueError("initial_conditions.params.config_file is required for generator 'ic_gen'.")
        cli_args = params.get("cli_args", [])
        if cli_args is None:
            cli_args = []
        if not isinstance(cli_args, list):
            raise ValueError("initial_conditions.params.cli_args must be a list.")
        return {
            "finit": 4, "cli_params": {}, "kind": "ic_gen", "label": "ic_gen",
            "field_name": field_name, "field_code": field_code,
            "config_file": config_file.strip(),
            "script": script.strip() if script is not None else None,
            "cli_args": cli_args,
            "scales": dict(scales),
        }
 
    if generator in ("channel_spectral_velocity", "duct_spectral_velocity"):
        normalized = load_ic_generator_module().validate_wall_spectral_params(params, generator)
        if not prepared_blocks or len(prepared_blocks) != 1:
            raise ValueError("wall spectral IC requires exactly one block with resolved boundaries.")
        face_axes = {"Xi": "i", "Eta": "j", "Zeta": "k"}
        faces = prepared_blocks[0]
        if len(faces) != 6:
            raise ValueError("wall spectral IC requires all six boundary faces.")
        for bc in faces:
            axis = face_axes[bc["face"][1:]]
            if axis in normalized["wall_axes"]:
                # The perturbation vanishes at the wall, which every wall handler admits.
                valid = bc["type"] == "WALL" and "WALL" in BC_HANDLER_SPECS.get(bc["handler"], {}).get("types", ())
            else:
                valid = bc["type"] == "PERIODIC" and bc["handler"] in ("geometric", "constant_flux", "initial_flux")
                if axis != normalized["streamwise_axis"]:
                    valid = valid and bc["handler"] == "geometric"
            if not valid:
                raise ValueError("wall spectral IC requires wall pairs (no-slip or free-slip) and periodic remaining axes, driven only streamwise.")
        normalized["initial_spectra"] = normalize_ic_initial_spectra(
            normalized.get("initial_spectra"), normalized["wall_axes"], generator, required=True)
        return {"finit": 4, "cli_params": {}, "kind": generator, "label": generator,
                "field_name": "ufield", "field_code": 0,
                "params": ic_provider_params_to_solver_units(generator, normalized, scales),
                "provider_context": dict(provider_context or {})}
 
    if generator == "stability_mode_velocity":
        normalized = load_ic_generator_module().validate_stability_mode_params(params)
        if not prepared_blocks or len(prepared_blocks) != 1:
            raise ValueError("stability_mode_velocity requires exactly one block with resolved boundaries.")
        face_axes = {"Xi": "i", "Eta": "j", "Zeta": "k"}
        faces = prepared_blocks[0]
        if len(faces) != 6:
            raise ValueError("stability_mode_velocity requires all six boundary faces.")
        for bc in faces:
            cross = face_axes[bc["face"][1:]] == normalized["cross_axis"]
            if cross == (bc["type"] == "PERIODIC") or (not cross and bc["handler"] != "geometric"):
                raise ValueError("stability_mode_velocity requires geometric periodic streamwise and normal axes "
                                 "and non-periodic cross-stream faces.")
        if "initial_spectra" in normalized:
            normalized["initial_spectra"] = normalize_ic_initial_spectra(
                normalized["initial_spectra"], [normalized["cross_axis"]], generator, required=False)
        context = dict(provider_context or {})
        # The base profile is an expression of physical quantities; the provider applies these.
        context.update({"length_ref": scales["length_ref"], "velocity_ref": scales["velocity_ref"]})
        return {"finit": 4, "cli_params": {}, "kind": generator, "label": generator,
                "field_name": "ufield", "field_code": 0,
                "params": ic_provider_params_to_solver_units(generator, normalized, scales),
                "provider_context": context}
 
    if generator == "resampled_velocity":
        return resolve_resampled_velocity_params(params, prepared_blocks, scales, provider_context)
 
    if generator == "spectral_random_velocity":
        if prepared_blocks and len(prepared_blocks) != 1:
            raise ValueError("spectral_random_velocity requires exactly one grid block.")
        if not prepared_blocks or len(prepared_blocks[0]) != 6 or any(
            bc.get("type") != "PERIODIC" or bc.get("handler") != "geometric"
            for bc in prepared_blocks[0]
        ):
            raise ValueError("spectral_random_velocity requires PERIODIC/geometric boundaries on all six faces.")
        unknown = sorted(set(params) - SPECTRAL_RANDOM_VELOCITY_PARAMS)
        if unknown:
            raise ValueError(f"spectral_random_velocity has unsupported params: {unknown}.")
        field_name, field_code = normalize_initial_condition_field(params.get("field", "Ucat"))
        if field_code != 0:
            raise ValueError("spectral_random_velocity supports only params.field: Ucat.")
        seed = params.get("seed", 12345)
        if isinstance(seed, bool) or not isinstance(seed, int):
            raise ValueError("spectral_random_velocity params.seed must be an integer.")
        random_cfg = params.get("random", {})
        if not isinstance(random_cfg, dict) or set(random_cfg) - {"distribution", "mean"}:
            raise ValueError("spectral_random_velocity params.random supports only distribution and mean.")
        distribution = str(random_cfg.get("distribution", "gaussian")).lower()
        if distribution != "gaussian":
            raise ValueError("spectral_random_velocity supports only random.distribution: gaussian.")
        mean = random_cfg.get("mean", [0.0, 0.0, 0.0])
        if not isinstance(mean, list) or len(mean) != 3:
            raise ValueError("spectral_random_velocity random.mean must be a three-component list.")
        mean = [_to_finite_float(value, f"initial_conditions.params.random.mean[{index}]")
                for index, value in enumerate(mean)]
        spectrum = params.get("spectrum", {})
        if not isinstance(spectrum, dict):
            raise ValueError("spectral_random_velocity params.spectrum must be a mapping.")
        spectrum_type = str(spectrum.get("type", "white")).lower()
        if spectrum_type == "white":
            if set(spectrum) - {"type"}:
                raise ValueError("white spectrum supports only type.")
            normalized_spectrum = {"type": "white"}
        elif spectrum_type == "k4_exponential":
            if set(spectrum) - {"type", "k0", "k_cut"} or "k0" not in spectrum or "k_cut" not in spectrum:
                raise ValueError("k4_exponential spectrum requires only type, k0, and k_cut.")
            normalized_spectrum = {"type": "k4_exponential",
                                   "k0": _to_finite_float(spectrum["k0"], "initial_conditions.params.spectrum.k0"),
                                   "k_cut": _to_finite_float(spectrum["k_cut"], "initial_conditions.params.spectrum.k_cut")}
        else:
            raise ValueError("spectrum.type must be 'white' or 'k4_exponential'.")
        if any(value <= 0 for key, value in normalized_spectrum.items() if key != "type"):
            raise ValueError("spectrum k0 and k_cut values must be positive.")
        projection = params.get("projection", {"type": "none"})
        if not isinstance(projection, dict) or set(projection) - {"type", "operator"}:
            raise ValueError("projection supports only type and operator.")
        projection_type = str(projection.get("type", "none")).lower()
        if projection_type == "none" and "operator" not in projection:
            normalized_projection = {"type": "none"}
        elif projection_type == "solenoidal" and str(projection.get("operator", "")).lower() in PROJECTION_OPERATORS:
            normalized_projection = {"type": "solenoidal", "operator": str(projection["operator"]).lower()}
        else:
            raise ValueError("projection must be none, or solenoidal with continuum/picurv_discrete operator.")
        normalization = params.get("normalization", {"type": "none"})
        if not isinstance(normalization, dict) or set(normalization) - {"type", "target"}:
            raise ValueError("normalization supports only type and target.")
        normalization_type = str(normalization.get("type", "none")).lower()
        if normalization_type == "none" and "target" not in normalization:
            normalized_normalization = {"type": "none"}
        elif normalization_type == "component_rms" and "target" in normalization:
            target = _to_finite_float(normalization["target"], "initial_conditions.params.normalization.target")
            if target <= 0:
                raise ValueError("component_rms normalization.target must be positive.")
            normalized_normalization = {"type": "component_rms", "target": target}
        else:
            raise ValueError("normalization must be none or component_rms with target.")
        remove_mean = params.get("remove_mean", True)
        if not isinstance(remove_mean, bool):
            raise ValueError("spectral_random_velocity remove_mean must be boolean.")
        context = dict(provider_context or {})
        return {
            "finit": 4, "cli_params": {}, "kind": "spectral_random_velocity", "label": "spectral_random_velocity",
            "field_name": field_name, "field_code": field_code, "provider_context": context,
            "params": ic_provider_params_to_solver_units(
                "spectral_random_velocity",
                {"field": "Ucat", "seed": seed,
                 "random": {"distribution": distribution, "mean": mean},
                 "spectrum": normalized_spectrum, "projection": normalized_projection,
                 "normalization": normalized_normalization, "remove_mean": remove_mean},
                scales),
        }
 
    generator_modes = {
        "zero": (0, "Zero"),
        "constant": (1, "Constant"),
        "streamwise_constant": (3, "Constant"),
        "poiseuille": (2, "Poiseuille"),
    }
    if generator not in generator_modes:
        raise ValueError(
            "initial_conditions.generator must be one of: zero, constant, "
            "streamwise_constant, poiseuille, ic_gen, spectral_random_velocity, resampled_velocity, "
            "channel_spectral_velocity, duct_spectral_velocity, stability_mode_velocity."
        )
    finit_code, legacy_mode = generator_modes[generator]
    legacy_ic = dict(params)
    legacy_ic["mode"] = legacy_mode
    cli_params = resolve_ic_cli_params(
        legacy_ic,
        1 if finit_code == 3 else finit_code,
        prepared_blocks,
        scales,
    )
    cli_params.pop("ic_coordinate_system", None)
    return {"finit": finit_code, "cli_params": cli_params, "kind": "builtin", "label": generator}
 
def runtime_petsc_index_bytes() -> int:
    """!
    @brief Bytes of a PetscInt in the PETSc the solver this conductor drives was built on.
    @details PETSc binary files store their sizes as PetscInt and do not record the width, so
             a file staged for the solver must use the solver's (PETSc's own PetscBinaryIO
             reads it from the build configuration the same way). An unbuilt or unstamped
             solver counts as 32-bit, PETSc's default.
    @return 4 or 8.
    """
    if _SELECTED_PETSC_INDEX_BYTES is not None:
        return _SELECTED_PETSC_INDEX_BYTES
    petsc = read_binary_petsc_stamp(resolve_runtime_executable("simulator")) or {}
    return PETSC_INDEX_BYTES.get(petsc.get("indices", "int32"), 4)
 
 
#: PetscInt widths, in bits, a PICurv build can use (`make INDEX_BITS=...`, `--petsc-index-bits`).
PETSC_INDEX_BITS_CHOICES = ("32", "64")
#: Largest PetscInt of a 32-bit-index PETSc; any one object past it needs the 64-bit build.
PETSC_MAX_INT_32BIT = 2**31 - 1
#: Widest per-particle field (particle_field_catalog.c) and per-node grid field PICurv creates:
#: coordinates and velocities have 3 components, the statistics workspace 6 (grid.c, fda6).
PARTICLE_FIELD_MAX_COMPONENTS = 3
GRID_FIELD_MAX_COMPONENTS = 3
STATISTICS_FIELD_COMPONENTS = 6
 
 
def requested_petsc_index_bytes(args=None) -> "int | None":
    """!
    @brief The index width a command was told to use: `--petsc-index-bits`, else `PICURV_PETSC_INDEX_BITS`.
    @param[in] args Parsed command arguments, or None.
    @return 4, 8, or None when neither names one.
    """
    bits = getattr(args, "petsc_index_bits", None) if args is not None else None
    bits = bits or os.environ.get("PICURV_PETSC_INDEX_BITS") or None
    if bits is None:
        return None
    if str(bits).strip() not in PETSC_INDEX_BITS_CHOICES:
        raise ValueError(f"PETSc index bits must be 32 or 64, not {bits!r}.")
    return 4 if str(bits).strip() == "32" else 8
 
 
def required_petsc_index_bytes(case_cfg: dict, case_path: str, monitor_cfg: "dict | None",
                               staged_grid: "str | None" = None) -> "tuple[int, str]":
    """!
    @brief The PetscInt width a new run needs, from its particle count and grid size.
    @details One PETSc object of more than PETSC_MAX_INT_32BIT entries needs 64-bit indices:
             a particle field (particles x 3) or a grid field (DA nodes x 3, or x 6 with field
             statistics). The solver checks the same limits when it creates them, so an
             underestimate here is refused at setup rather than run.
    @param[in] case_cfg Parsed case configuration.
    @param[in] case_path Path to case.yml.
    @param[in] monitor_cfg Parsed monitor configuration, for field statistics.
    @param[in] staged_grid Staged PICGRID, if any.
    @return (4 or 8, reason).
    """
    particles = (((case_cfg.get("models") or {}).get("physics") or {}).get("particles") or {})
    particle_entries = int(particles.get("count", 0) or 0) * PARTICLE_FIELD_MAX_COMPONENTS
    statistics = bool(monitor_cfg) and normalize_field_statistics_config(monitor_cfg, case_cfg)["enabled"]
    components = STATISTICS_FIELD_COMPONENTS if statistics else GRID_FIELD_MAX_COMPONENTS
    grid_entries = max([(im + 1) * (jm + 1) * (km + 1) * components
                        for im, jm, km in resolve_grid_node_dims(case_cfg, case_path, staged_grid) or []] or [0])
    if particle_entries > PETSC_MAX_INT_32BIT:
        return 8, f"{particle_entries:,} particle-field entries exceed the 32-bit limit {PETSC_MAX_INT_32BIT:,}"
    if grid_entries > PETSC_MAX_INT_32BIT:
        return 8, f"{grid_entries:,} grid-field entries exceed the 32-bit limit {PETSC_MAX_INT_32BIT:,}"
    return 4, "particle and grid fields fit 32-bit indices"
 
 
def checkpoint_source_petsc_index_bytes(source_dir: str) -> "int | None":
    """!
    @brief PetscInt width the committed checkpoints under a run output root were written with.
    @details Every checkpoint of a run shares its build's width; one written before the width
             was recorded is 32-bit.
    @param[in] source_dir Run output root holding `checkpoints/`.
    @return 4 or 8, or None when it holds no committed checkpoint.
    """
    root = os.path.join(os.path.abspath(source_dir), "checkpoints")
    for name in sorted(os.listdir(root), reverse=True) if os.path.isdir(root) else []:
        metadata = os.path.join(root, name, "checkpoint.meta")
        if os.path.isfile(os.path.join(root, name, "COMMITTED")) and os.path.isfile(metadata):
            return int(_read_checkpoint_options(metadata).get("checkpoint_petsc_index_bytes", "4"))
    return None
 
 
def select_petsc_index_bytes(index_bytes: int, reason: str) -> int:
    """!
    @brief Make the current command drive the build of one PetscInt width.
    @details `resolve_runtime_executable()` and `runtime_petsc_index_bytes()` follow it, so the
             executables staged, pinned and launched, and every PETSc file the conductor writes
             or validates for them, agree. Refuses a width whose executables are not built.
    @param[in] index_bytes 4 or 8.
    @param[in] reason Why, for the message.
    @return index_bytes.
    """
    global _SELECTED_PETSC_INDEX_BYTES
    _SELECTED_PETSC_INDEX_BYTES = index_bytes
    if index_bytes == 8:
        missing = [path for path in (resolve_runtime_executable(name) for name in RUN_EXECUTABLE_NAMES)
                   if not os.path.isfile(path)]
        if missing:
            raise ValueError(
                f"This run needs the 64-bit-index build ({reason}), which is not built: missing "
                f"{', '.join(missing)}. Build it with `make INDEX_BITS=64 PETSC_DIR=<64-bit-index PETSc> "
                f"[PETSC_ARCH=...] all`.")
        # stderr, so a dry-run's JSON plan on stdout stays parseable.
        print(f"[INFO] Using the 64-bit-index build: {reason}.", file=sys.stderr)
    return index_bytes
 
 
def select_run_petsc_index_bytes(args, case_cfg: dict, case_path: str, monitor_cfg: "dict | None",
                                 restart_source_dir: "str | None" = None) -> int:
    """!
    @brief Choose and select the PetscInt width a run's solve stage needs.
    @details A restart or continuation keeps the width its source checkpoint was written with;
             a new run uses 32-bit unless a particle or grid field outgrows it. An explicit
             `--petsc-index-bits` or `PICURV_PETSC_INDEX_BITS` wins, except against a checkpoint.
    @param[in] args Parsed command arguments.
    @param[in] case_cfg Parsed case configuration.
    @param[in] case_path Path to case.yml.
    @param[in] monitor_cfg Parsed monitor configuration.
    @param[in] restart_source_dir Restart source output root, if any.
    @return 4 or 8.
    """
    requested = requested_petsc_index_bytes(args)
    if restart_source_dir:
        recorded = checkpoint_source_petsc_index_bytes(restart_source_dir)
        if recorded is not None:
            if requested is not None and requested != recorded:
                raise ValueError(
                    f"--petsc-index-bits {8 * requested} conflicts with the restart source {restart_source_dir}, "
                    f"whose checkpoints were written with {8 * recorded}-bit indices.")
            return select_petsc_index_bytes(recorded, f"its restart source was written with {8 * recorded}-bit indices")
    needed, reason = required_petsc_index_bytes(case_cfg, case_path, monitor_cfg)
    if requested == 4 and needed == 8:
        raise ValueError(f"--petsc-index-bits 32 cannot run this case: {reason}.")
    if requested is not None:
        return select_petsc_index_bytes(requested, f"{8 * requested}-bit indices were requested")
    return select_petsc_index_bytes(needed, reason)
 
 
def select_existing_run_petsc_index_bytes(run_dir: str, args=None) -> int:
    """!
    @brief Select the PetscInt width an existing run was staged with, for its later stages.
    @details The width staging recorded in `config/active.json`, else its checkpoints' width,
             else 32-bit. A conflicting explicit request is refused.
    @param[in] run_dir Run directory.
    @param[in] args Parsed command arguments, or None.
    @return 4 or 8.
    """
    active = _read_json_if_exists(os.path.join(os.path.abspath(run_dir), "config", "active.json")) or {}
    recorded = active.get("petsc_index_bytes")
    if recorded is None:
        recorded = checkpoint_source_petsc_index_bytes(os.path.join(run_dir, CANONICAL_RUN_PATHS["output"]))
    requested = requested_petsc_index_bytes(args)
    if recorded is not None and requested is not None and requested != int(recorded):
        raise ValueError(f"--petsc-index-bits {8 * requested} conflicts with {run_dir}, staged with "
                         f"{8 * int(recorded)}-bit indices.")
    width = int(recorded) if recorded is not None else (requested or 4)
    return select_petsc_index_bytes(width, f"{run_dir} was staged with {8 * width}-bit indices")
 
 
def record_run_petsc_index_bytes(run_dir: str) -> None:
    """!
    @brief Record in `config/active.json` the PetscInt width the current command selected.
    @param[in] run_dir Run directory.
    @return None.
    """
    active_path = os.path.join(os.path.abspath(run_dir), "config", "active.json")
    active = _read_json_if_exists(active_path)
    if isinstance(active, dict):
        active["petsc_index_bytes"] = _SELECTED_PETSC_INDEX_BYTES or 4
        write_json_file(active_path, active)
 
 
def payload_petsc_index_bytes(path: str) -> int:
    """!
    @brief PetscInt width of a PETSc payload: as its checkpoint recorded it, else the driven solver's.
    @details A committed checkpoint's `checkpoint.meta` records the width it was written with
             (`-checkpoint_petsc_index_bytes`; absent in checkpoints written before it existed,
             which are 32-bit). A payload outside any checkpoint is read as the driven solver
             would read it.
    @param[in] path Payload path.
    @return 4 or 8.
    """
    directory = os.path.dirname(os.path.abspath(path))
    for _ in range(4):
        metadata = os.path.join(directory, "checkpoint.meta")
        if os.path.isfile(metadata):
            return int(_read_checkpoint_options(metadata).get("checkpoint_petsc_index_bytes", "4"))
        directory = os.path.dirname(directory)
    return runtime_petsc_index_bytes()
 
 
def petsc_index_arguments(index_bytes: int) -> list:
    """!
    @brief Generator arguments naming a PetscInt width; none for PETSc's default 32-bit.
    @details Kept empty at 4 bytes so a user's replacement generator script that predates the
             option keeps working for every 32-bit build.
    @param[in] index_bytes 4 or 8.
    @return Argument list.
    """
    return [] if index_bytes == 4 else ["--petsc-index-bytes", str(index_bytes)]
 
 
def validate_petsc_vec_binary(path: str, index_bytes: "int | None" = None) -> dict:
    """!
    @brief Validate the basic PETSc binary VecView envelope used by ReadFieldData.
    @param[in] path PETSc binary vector path.
    @param[in] index_bytes PetscInt width of the reading build; the driven solver's when None.
    @return Summary containing the absolute path, scalar count and index width.
    """
    import struct
    index_bytes = index_bytes or runtime_petsc_index_bytes()
    header_bytes = 2 * index_bytes
    with open(path, "rb") as fin:
        header = fin.read(header_bytes)
        if len(header) != header_bytes:
            raise ValueError(f"PETSc Vec file is too short: {path}")
        class_id, scalar_count = struct.unpack(">ii" if index_bytes == 4 else ">qq", header)
        payload = fin.read()
    if class_id != 1211214 or scalar_count < 0 or len(payload) != scalar_count * 8:
        raise ValueError(
            f"Invalid PETSc Vec file {path} for a PETSc with {index_bytes}-byte indices; a file "
            f"written for the other index width (or truncated) does not fit its header.")
    return {"path": os.path.abspath(path), "scalar_count": scalar_count, "index_bytes": index_bytes}
 
 
def write_scaled_petsc_vec_binary(source: str, destination: str, divisor: float) -> dict:
    """!
    @brief Copy a PETSc binary Vec, dividing every scalar by one factor.
    @details Used to stage a physical payload in solver units. The envelope is the one
             `validate_petsc_vec_binary()` accepts: a big-endian class id and count of the
             solver's index width, followed by big-endian doubles.
    @param[in] source Validated PETSc binary vector path.
    @param[in] destination Path to write the scaled vector to.
    @param[in] divisor Reference scale the payload is divided by.
    @return Summary of the destination, as `validate_petsc_vec_binary()` reports it.
    """
    from array import array
    index_bytes = validate_petsc_vec_binary(source)["index_bytes"]
    with open(source, "rb") as fin:
        header = fin.read(2 * index_bytes)
        values = array("d")
        values.frombytes(fin.read())
    if sys.byteorder == "little":
        values.byteswap()
    for index, value in enumerate(values):
        values[index] = value / divisor
    if sys.byteorder == "little":
        values.byteswap()
    with open(destination, "wb") as fout:
        fout.write(header)
        fout.write(values.tobytes())
    return validate_petsc_vec_binary(destination, index_bytes)
 
def initial_condition_diagnostic_paths(run_dir, resolved_ic):
    """!
    @brief Resolve spectral IC artifacts through the canonical run layout, also for dry runs.
    @param[in] run_dir Run or asset-build root.
    @param[in] resolved_ic Normalized file-backed IC provider.
    @return Canonical diagnostic artifact paths, including each sample CSV and JSON.
    """
    if resolved_ic["kind"] not in SPECTRAL_IC_PROVIDERS:
        return []
    paths = [os.path.join(run_dir, CANONICAL_RUN_PATHS["metrics"], "initial_condition_summary.json")]
    if resolved_ic["kind"] in SHELL_SPECTRUM_IC_PROVIDERS:
        return paths + [os.path.join(run_dir, INITIAL_CONDITION_SPECTRUM_RELPATH)]
    for task in resolved_ic["params"].get("initial_spectra", []):
        base = post_spectra_task_basename(task, "initial_condition")
        paths.extend([os.path.join(run_dir, CANONICAL_RUN_PATHS["spectra"], base+suffix) for suffix in (".csv", ".json")])
    return paths
 
 
def run_initial_spectrum_generator(field_path: str, staged_grid: str,
                                   spectrum_path: str, case_dir: str, task_cfg=None) -> str:
    """!
    @brief Measure the shell-averaged spectrum of a staged initial condition.
 
    The spectrum has a single implementation in `generators/spectra.gen`, so the
    conductor measures the generated field rather than asking the initial-condition
    generator to report a spectrum it would have to bin itself.
 
    @param[in] field_path    Generated PETSc binary Ucat path.
    @param[in] staged_grid   Staged canonical PICGRID path.
    @param[in] spectrum_path Destination `k,energy` CSV path.
    @param[in] case_dir      Working directory for the subprocess.
    @param[in] task_cfg Optional normalized plane/line task; None retains DIT shell measurement.
    @return Absolute path to the written spectrum CSV.
    @throws ValueError when the generator is missing or fails.
    """
    script = os.path.join(GENERATORS_PATH, "spectra.gen")
    if not os.path.isfile(script):
        raise ValueError(f"spectra.gen script not found: {script}")
    command = task_cfg["task"].replace("_", "-") if task_cfg else "shell-spectrum"
    cmd = [sys.executable, script, command,
           "--field-file", field_path, "--source-grid", staged_grid,
           "--spectrum-csv", spectrum_path, *petsc_index_arguments(runtime_petsc_index_bytes())]
    if task_cfg:
        cmd.extend(["--axes", *task_cfg["axes"], "--fixed-indices", json.dumps(task_cfg["fixed_indices"]),
                    "--subtract-mean", task_cfg["subtract_mean"], "--summary-json", os.path.splitext(spectrum_path)[0]+".json"])
    result = subprocess.run(cmd, cwd=case_dir, text=True, capture_output=True)
    if result.returncode != 0:
        details = (result.stderr or result.stdout or "").strip()
        raise ValueError(
            f"initial-condition spectrum failed with exit code {result.returncode}. Details:\n{details}"
        )
    return os.path.abspath(spectrum_path)
 
 
def run_initial_condition_generator(case_path: str, run_dir: str, resolved_ic: dict) -> str:
    """!
    @brief Run the repository IC generator.
    @param[in] case_path Source case YAML path.
    @param[in] run_dir Run or precompute output directory.
    @param[in] resolved_ic Normalized external-generator contract.
    @return Generated PETSc vector path.
    """
    case_dir = os.path.dirname(os.path.abspath(case_path))
    if resolved_ic["kind"] in SPECTRAL_IC_PROVIDERS:
        script = os.path.join(GENERATORS_PATH, "ic.gen")
        output_path = os.path.join(run_dir, "inputs", "initial_condition", "initial_condition.generated.dat")
        os.makedirs(os.path.dirname(output_path), exist_ok=True)
        staged_grid = os.path.join(run_dir, "inputs", "grid", "grid.run")
        if not os.path.isfile(staged_grid):
            raise ValueError(f"{resolved_ic['kind']} requires a staged PICGRID at inputs/grid/grid.run.")
        summary_path = os.path.join(run_dir, "output", "analysis", "metrics", "initial_condition_summary.json")
        spectrum_path = os.path.join(run_dir, INITIAL_CONDITION_SPECTRUM_RELPATH)
        os.makedirs(os.path.dirname(summary_path), exist_ok=True)
        os.makedirs(os.path.dirname(spectrum_path), exist_ok=True)
        provider_params = resolved_ic["params"]
        provider_context = dict(resolved_ic.get("provider_context", {}))
        measured_field = output_path
        if resolved_ic["kind"] == "resampled_velocity" and provider_params.get("field") == "Ucont":
            # Staged fluxes are not a velocity; the spectrum is measured on the velocity the
            # runtime reconstructs from them, written beside the output and removed after.
            measured_field = os.path.join(os.path.dirname(output_path), ".runtime_ucat_for_spectrum.dat")
            provider_context["runtime_ucat_output"] = measured_field
        if resolved_ic["kind"] == "resampled_velocity":
            # The source is a workspace input, resolved here so the provider is handed one
            # absolute path; a reference-mode import resolves to its external target.
            provider_params = dict(provider_params)
            provider_params["source_file"] = resolve_workspace_path(case_path, provider_params["source_file"])
            if not os.path.isfile(provider_params["source_file"]):
                raise ValueError(f"resampled_velocity source file not found: {provider_params['source_file']}")
        cmd = [sys.executable, script, "--generator", resolved_ic["kind"],
               "--grid", staged_grid, "--output", output_path,
               "--params-json", json.dumps(provider_params, sort_keys=True),
               "--context-json", json.dumps(provider_context, sort_keys=True),
               "--summary-json", summary_path, *petsc_index_arguments(runtime_petsc_index_bytes())]
        result = subprocess.run(cmd, cwd=case_dir, text=True, capture_output=True)
        if result.returncode != 0:
            details = (result.stderr or result.stdout or "").strip()
            raise ValueError(f"{resolved_ic['kind']} failed with exit code {result.returncode}. Details:\n{details}")
        validate_petsc_vec_binary(output_path)
        if resolved_ic["kind"] in SHELL_SPECTRUM_IC_PROVIDERS:
            try:
                run_initial_spectrum_generator(measured_field, staged_grid, spectrum_path, case_dir)
            finally:
                if measured_field != output_path and os.path.exists(measured_field):
                    os.remove(measured_field)
        else:
            paths = initial_condition_diagnostic_paths(run_dir, resolved_ic)
            for task, path in zip(resolved_ic["params"].get("initial_spectra", []), paths[1::2]):
                run_initial_spectrum_generator(output_path, staged_grid, path, case_dir, task)
        return output_path
    script = _resolve_generator_script(resolved_ic.get("script"), case_path, "ic.gen")
    config_file = resolved_ic["config_file"]
    config_file = _resolve_case_relative_path(config_file, case_dir)
    if not os.path.isfile(script):
        raise ValueError(f"ic.gen script not found: {script}")
    if not os.path.isfile(config_file):
        raise ValueError(f"initial-condition generator config file not found: {config_file}")
    output_path = os.path.join(run_dir, "inputs", "initial_condition", "initial_condition.generated.dat")
    os.makedirs(os.path.dirname(output_path), exist_ok=True)
    cmd = [sys.executable, script, "-c", config_file, "--field",
           "Ucat" if resolved_ic["field_code"] == 0 else "Ucont",
           "--output", output_path, *petsc_index_arguments(runtime_petsc_index_bytes())]
    staged_grid = os.path.join(run_dir, "inputs", "grid", "grid.run")
    if os.path.isfile(staged_grid):
        cmd.extend(["--grid", staged_grid])
    # Expressions are written in physical units; the generator is given the scales and
    # writes solver units, like every other initial-condition provider.
    cmd.extend(["--length-ref", repr(float(resolved_ic["scales"]["length_ref"])),
                "--velocity-ref", repr(float(resolved_ic["scales"]["velocity_ref"]))])
    cmd.extend(str(token) for token in resolved_ic.get("cli_args", []))
    result = subprocess.run(cmd, cwd=case_dir, text=True, capture_output=True)
    if result.returncode != 0:
        details = (result.stderr or result.stdout or "").strip()
        raise ValueError(f"ic.gen failed with exit code {result.returncode}. Details:\n{details}")
    validate_petsc_vec_binary(output_path)
    return output_path
 
def _check_file_ic_matches_grid(payload: dict, staged_grid: str, resolved_ic: dict) -> None:
    """!
    @brief Refuse a `mode: file` payload sized for another grid, and say what imports one.
    @details `mode: file` reads its vector verbatim, so it must already be laid out for this
             grid: one value per component per cell including one dummy layer. The runtime
             would refuse a mismatch at startup; staging refuses it first and names
             `resampled_velocity`, which brings a field from another grid onto this one.
             Programmatic grids are not staged here, so they keep the runtime check.
    @param[in] payload Header summary from `validate_petsc_vec_binary()`.
    @param[in] staged_grid Staged PICGRID path, if the grid is file-backed.
    @param[in] resolved_ic Normalized file-backed IC contract.
    """
    if not os.path.isfile(staged_grid):
        return
    dims = read_picgrid_header_dimensions(staged_grid)
    if len(dims) != 1:
        return
    im, jm, km = dims[0]
    expected = (im + 1) * (jm + 1) * (km + 1) * 3
    if payload["scalar_count"] != expected:
        raise ValueError(
            f"Initial-condition file {payload['path']} holds {payload['scalar_count']} values; this grid "
            f"({im - 1}x{jm - 1}x{km - 1} cells) needs {expected} for {resolved_ic.get('field_name', 'the field')}. "
            "mode: file reads a field already laid out for this grid. To bring in a field from another "
            "grid or format, use generator: resampled_velocity."
        )
 
 
def stage_initial_condition_file(run_dir: str, case_path: str, resolved_ic: dict) -> dict:
    """!
    @brief Materialize and stage one file-backed IC in ReadFieldData's expected layout.
    @param[in] run_dir Run or precompute output directory.
    @param[in] case_path Source case YAML path.
    @param[in] resolved_ic Normalized file-backed IC contract.
    @return Source, staged path, and staging-directory summary.
    """
    stage_dir = os.path.join(run_dir, "inputs", "initial_condition")
    os.makedirs(stage_dir, exist_ok=True)
    staged_path = os.path.join(stage_dir, f"{resolved_ic['field_name']}00000_0.dat")
    if os.path.isfile(staged_path):
        validate_petsc_vec_binary(staged_path)
        summary = {
            "source": os.path.abspath(staged_path),
            "staged": os.path.abspath(staged_path),
            "directory": os.path.abspath(stage_dir),
            "reused": True,
        }
        if resolved_ic["kind"] in SPECTRAL_IC_PROVIDERS:
            summary["diagnostics"] = initial_condition_diagnostic_paths(run_dir, resolved_ic)
        return summary
    divisor = 1.0
    if is_generated_ic_provider(resolved_ic):
        # Providers are handed the scales they need and write solver units.
        source_path = run_initial_condition_generator(case_path, run_dir, resolved_ic)
    else:
        case_dir = os.path.dirname(os.path.abspath(case_path))
        source_path = _resolve_case_relative_path(resolved_ic["source_file"], case_dir)
        if not os.path.isfile(source_path):
            raise ValueError(f"Initial-condition source file not found: {source_path}")
        payload = validate_petsc_vec_binary(source_path)
        _check_file_ic_matches_grid(payload, os.path.join(run_dir, "inputs", "grid", "grid.run"), resolved_ic)
        divisor = ic_payload_divisor(resolved_ic, case_dir)
    if divisor != 1.0:
        write_scaled_petsc_vec_binary(source_path, staged_path, divisor)
    elif os.path.abspath(source_path) != os.path.abspath(staged_path):
        shutil.copy2(source_path, staged_path)
    summary = {"source": os.path.abspath(source_path), "staged": os.path.abspath(staged_path),
               "directory": os.path.abspath(stage_dir), "payload_divisor": divisor}
    if resolved_ic["kind"] in SPECTRAL_IC_PROVIDERS:
        summary["diagnostics"] = initial_condition_diagnostic_paths(run_dir, resolved_ic)
    return summary
 
def normalize_flow_direction_token(value: str) -> int:
    """!
    @brief Maps a face-token flow direction string to the C FlowDirection enum integer.
    @param[in] value One of '+Xi', '-Xi', '+Eta', '-Eta', '+Zeta', '-Zeta'.
    @return Integer 0-5 matching the FlowDirection enum.
    @throws ValueError on unknown value.
    """
    mapped = {
        "+Xi": 0, "-Xi": 1,
        "+Eta": 2, "-Eta": 3,
        "+Zeta": 4, "-Zeta": 5,
    }.get(str(value).strip())
    if mapped is None:
        raise ValueError(
            f"Unknown initial_conditions.flow_direction '{value}'. "
            "Use one of: '+Xi', '-Xi', '+Eta', '-Eta', '+Zeta', '-Zeta'."
        )
    return mapped
 
def _ic_has_inlet(prepared_blocks) -> bool:
    """!
    @brief Return True if any prepared BC block contains an INLET face.
    @param[in] prepared_blocks List of prepared BC lists (one per domain block).
    @return True if at least one INLET entry exists across all blocks.
    """
    if not prepared_blocks:
        return False
    for block_bcs in prepared_blocks:
        for entry in block_bcs:
            if entry.get("type") == "INLET":
                return True
    return False
 
def resolve_ic_cli_params(ic: dict, finit_code: int, prepared_blocks, scales: dict) -> dict:
    """!
    @brief Resolve all IC parameters and return a dict of PETSc option values.
    @param[in] ic The properties.initial_conditions mapping.
    @param[in] finit_code Normalized -finit integer code.
    @param[in] prepared_blocks Normalized BC blocks (may be None).
    @param[in] scales Reference scales, as returned by `resolve_reference_scales()`.
    @return Dict with keys matching PETSc option names (without leading dash).
    @throws KeyError if a required key is absent.
    @throws ValueError on invalid combinations or values.
    """
    result = {}
 
    if finit_code == 0:
        return result
 
    if finit_code == 1:  # Constant
        has_cartesian   = any(k in ic for k in ("u_physical", "v_physical", "w_physical"))
        has_curvilinear = "velocity_physical" in ic
 
        if has_cartesian and has_curvilinear:
            raise ValueError(
                "initial_conditions: cannot mix u/v/w_physical (cartesian) and "
                "velocity_physical (curvilinear) — use one or the other."
            )
 
        if has_curvilinear:  # curvilinear: scalar speed along flow_direction axis
            cs_code = 1
            result["ic_coordinate_system"] = cs_code
            try:
                vel_phys = float(ic["velocity_physical"])
            except (TypeError, ValueError) as exc:
                raise ValueError(
                    f"Invalid value for initial_conditions.velocity_physical: {ic['velocity_physical']!r}. "
                    "Expected a numeric value."
                ) from exc
            result["ic_velocity_physical"] = to_solver_units(
                vel_phys, ("case", "properties", "initial_conditions", "velocity_physical"), scales)
 
            if "flow_direction" in ic:
                result["flow_direction"] = normalize_flow_direction_token(ic["flow_direction"])
            elif not _ic_has_inlet(prepared_blocks):
                raise ValueError(
                    "initial_conditions.flow_direction is required for curvilinear Constant IC "
                    "when no INLET face exists."
                )
 
        else:  # cartesian: u/v/w_physical → Cart2Contra (default when no velocity_physical)
            if "flow_direction" in ic:
                raise ValueError(
                    "initial_conditions.flow_direction is not valid for cartesian Constant IC. "
                    "Use velocity_physical + flow_direction for curvilinear mode."
                )
            cs_code = 0
            result["ic_coordinate_system"] = cs_code
            u, v, w = parse_initial_velocity_components(ic, finit_code, require_explicit=True)
            ic_path = ("case", "properties", "initial_conditions")
            result["ucont_x"] = to_solver_units(u, ic_path + ("u_physical",), scales)
            result["ucont_y"] = to_solver_units(v, ic_path + ("v_physical",), scales)
            result["ucont_z"] = to_solver_units(w, ic_path + ("w_physical",), scales)
 
    elif finit_code == 2:  # Poiseuille
        if any(k in ic for k in ("u_physical", "v_physical", "w_physical")):
            raise ValueError(
                "For Poiseuille mode, use peak_velocity_physical, not u_physical/v_physical/w_physical."
            )
        if "velocity_physical" in ic:
            raise ValueError(
                "For Poiseuille mode, use peak_velocity_physical, not velocity_physical."
            )
        if "peak_velocity_physical" not in ic:
            raise KeyError("peak_velocity_physical")
        try:
            peak = float(ic["peak_velocity_physical"])
        except (TypeError, ValueError) as exc:
            raise ValueError(
                f"Invalid value for initial_conditions.peak_velocity_physical: "
                f"{ic['peak_velocity_physical']!r}. Expected a numeric value."
            ) from exc
        result["ic_velocity_physical"] = to_solver_units(
            peak, ("case", "properties", "initial_conditions", "peak_velocity_physical"), scales)
 
        if "flow_direction" in ic:
            fd_int = normalize_flow_direction_token(ic["flow_direction"])
            # Cross-check: explicit flow_direction must align with INLET face if one exists
            if _ic_has_inlet(prepared_blocks):
                inlet_axis = infer_unique_inlet_axis_from_prepared_bcs(prepared_blocks)
                fd_axis_name = {0: "x", 1: "y", 2: "z"}.get(fd_int // 2, "?")
                if inlet_axis and fd_axis_name != inlet_axis:
                    token = ic["flow_direction"]
                    raise ValueError(
                        f"initial_conditions.flow_direction '{token}' (axis '{fd_axis_name}') "
                        f"does not match INLET face axis '{inlet_axis}'."
                    )
            result["flow_direction"] = fd_int
        elif not _ic_has_inlet(prepared_blocks):
            raise ValueError(
                "initial_conditions.flow_direction is required for Poiseuille IC "
                "when no INLET face exists."
            )
 
    return result
 
def normalize_eulerian_field_source(value: str) -> str:
    """!
    @brief Normalizes the Eulerian field source selector to the C-side canonical string.
    @param[in] value Human-readable or enum-like Eulerian field source.
    @return Canonical string accepted by `-euler_field_source`.
    @throws ValueError if the input cannot be mapped.
    """
    if value is None:
        raise ValueError("eulerian_field_source cannot be None")
 
    normalized = str(value).strip().lower().replace("-", "_").replace(" ", "_")
    aliases = {
        "solve": "solve",
        "load": "load",
        "analytical": "analytical",
    }
    mapped = aliases.get(normalized)
    if mapped is None:
        raise ValueError(
            f"Unknown operation_mode.eulerian_field_source '{value}'. "
            "Use one of: 'solve', 'load', 'analytical'."
        )
    return mapped
 
 
def initial_condition_is_authoritative(case_cfg: dict, solver_cfg: dict) -> bool:
    """!
    @brief Whether the configured initial condition is the field the solver starts from.
    @details A restart (start_step > 0) starts from saved state, and the load and
             analytical Eulerian sources supply their own field, so in each of those the
             configured initial condition is never read.
    @param[in] case_cfg Parsed case configuration.
    @param[in] solver_cfg Parsed solver configuration.
    @return True only for a fresh solve.
    """
    source = normalize_eulerian_field_source(
        ((solver_cfg or {}).get("operation_mode", {}) or {}).get("eulerian_field_source", "solve")
    )
    start_step = int(((case_cfg or {}).get("run_control", {}) or {}).get("start_step", 0) or 0)
    return source == "solve" and start_step == 0
 
 
def unused_asset_kinds(case_cfg: dict, solver_cfg: dict) -> tuple:
    """!
    @brief Asset kinds a run with these configurations would build but never read.
    @param[in] case_cfg Parsed case configuration.
    @param[in] solver_cfg Parsed solver configuration.
    @return Kinds to leave out of the run's asset materialization.
    """
    return () if initial_condition_is_authoritative(case_cfg, solver_cfg) else ("initial-condition",)
 
 
def normalize_analytical_type(value: str) -> str:
    """!
    @brief Normalizes the analytical solution selector to the C-side canonical string.
    @param[in] value Human-readable analytical solution selector.
    @return Canonical string accepted by `-analytical_type`.
    @throws ValueError if the input cannot be mapped.
    """
    # Canonical selector map for analytical solution selectors.
    if value is None:
        raise ValueError("analytical_type cannot be None")
 
    normalized = str(value).strip().upper().replace("-", "_").replace(" ", "_")
    if normalized not in ANALYTICAL_SOLUTION_TYPES:
        raise ValueError(
            f"Unknown operation_mode.analytical_type '{value}'. "
            "Use one of: 'TGV3D', 'ZERO_FLOW', 'UNIFORM_FLOW'."
        )
    return normalized
 
def parse_initial_velocity_components(initial_conditions: dict, finit_code: int, *, require_explicit: bool) -> "tuple[float, float, float]":
    """!
    @brief Parse initial-condition velocity components with mode-aware defaults.
    @param[in] initial_conditions The `properties.initial_conditions` mapping from case.yml.
    @param[in] finit_code Normalized `-finit` integer code.
    @param[in] require_explicit If True, all three component keys must be present.
    @return Tuple `(u, v, w)` in physical units.
    @throws KeyError if a required component key is missing.
    @throws ValueError if a component cannot be converted to float.
    """
    component_keys = ("u_physical", "v_physical", "w_physical")
    components = []
    for key in component_keys:
        if key not in initial_conditions:
            if require_explicit:
                raise KeyError(key)
            raw_value = 0.0
        else:
            raw_value = initial_conditions[key]
        try:
            components.append(float(raw_value))
        except (TypeError, ValueError) as exc:
            raise ValueError(
                f"Invalid value for properties.initial_conditions.{key}: {raw_value!r}. Expected a numeric value."
            ) from exc
    return tuple(components)
 
def infer_unique_inlet_axis_from_prepared_bcs(prepared_blocks: list) -> "str | None":
    """!
    @brief Infer the unique inlet axis across all blocks using C-side "primary inlet" ordering.
    @param[in] prepared_blocks Normalized BC blocks from `validate_and_prepare_boundary_conditions`.
    @return One of `"x"`, `"y"`, `"z"` if unique, `None` if no inlet exists.
    @throws ValueError if different blocks imply different inlet axes.
    """
    face_order = ("-Xi", "+Xi", "-Eta", "+Eta", "-Zeta", "+Zeta")
    face_axis = {
        "-Xi": "x", "+Xi": "x",
        "-Eta": "y", "+Eta": "y",
        "-Zeta": "z", "+Zeta": "z",
    }
 
    inlet_axes = set()
    for block_bcs in prepared_blocks:
        face_map = {entry["face"]: entry for entry in block_bcs}
        for face in face_order:
            entry = face_map.get(face)
            if entry and entry["type"] == "INLET":
                inlet_axes.add(face_axis[face])
                break
 
    if not inlet_axes:
        return None
    if len(inlet_axes) != 1:
        raise ValueError(
            "properties.initial_conditions.peak_velocity_physical requires all blocks to have a primary INLET "
            f"on the same axis. Found axes: {sorted(inlet_axes)}. Use u_physical/v_physical/w_physical instead."
        )
    return next(iter(inlet_axes))
 
def normalize_particle_init_mode(value: str) -> int:
    """!
    @brief Maps canonical particle init mode names to C enum/int codes (-pinit).
    @param[in] value Canonical particle initialization mode.
    @return Canonical integer code accepted by -pinit.
    @throws ValueError if the input cannot be mapped.
    """
    # Canonical selector map for particle initialization modes.
    if value is None:
        raise ValueError("particle init mode cannot be None")
 
    name = str(value).strip()
    # SurfaceEdges was a diagnostic pattern whose placement depended on the rank layout.
    if name == "SurfaceEdges":
        raise ValueError(
            "particle init_mode 'SurfaceEdges' is retired: use 'Surface' for inlet seeding, "
            "or 'PointSource' to place particles at a chosen point."
        )
    mapped = {
        "Surface": 0,
        "Volume": 1,
        "PointSource": 2,
    }.get(name)
    if mapped is None:
        raise ValueError(
            f"Unknown particle init_mode '{value}'. Use one of: "
            "'Surface', 'Volume', 'PointSource'."
        )
    return mapped
 
def normalize_interpolation_method(value: str) -> int:
    """!
    @brief Maps interpolation method names to C enum/int codes (-interpolation_method).
    @param[in] value Canonical interpolation method name.
    @return Integer code accepted by -interpolation_method.
    @throws ValueError if the input cannot be mapped.
    """
    if value is None:
        raise ValueError("interpolation method cannot be None")
 
    mapped = {
        "Trilinear": 0,
        "CornerAveraged": 1,
        "FaceFlux": 2,
    }.get(str(value).strip())
    if mapped is None:
        raise ValueError(
            f"Unknown interpolation_method '{value}'. Use one of: "
            "'Trilinear', 'CornerAveraged', 'FaceFlux'."
        )
    return mapped
 
#: Canonical spelling of each LES model code, for diagnostics.
LES_MODEL_NAMES = {1: "constant_smagorinsky", 2: "dynamic_smagorinsky", 3: "vreman", 4: "wale"}
 
#: Parameters that configure exactly one LES model and are refused under the others.
LES_MODEL_OWNED_KEYS = {
    1: ("constant_cs",),
    2: ("dynamic_frequency", "test_filter", "averaging", "clipping"),
    3: ("vreman_coefficient",),
    4: ("wale_coefficient",),
}
 
#: How a model's own parameters are described when they are refused elsewhere.
LES_MODEL_KEY_OWNER_DESCRIPTIONS = {
    1: "the constant Smagorinsky coefficient",
    2: "the dynamic procedure",
    3: "the Vreman model",
    4: "the WALE model",
}
 
 
def normalize_les_model(value) -> int:
    """!
    @brief Maps LES model selectors to C enum/int codes (-les).
    @param[in] value LES selector name or legacy integer/bool value.
    @return Integer code accepted by -les.
    @throws ValueError if the input cannot be mapped.
    """
    if isinstance(value, bool):
        return 1 if value else 0
    if isinstance(value, int):
        if value in (0, 1, 2, 3, 4):
            return value
        raise ValueError("models.physics.turbulence.les must be 0-4, false/true, or a supported model block.")
    if value is None:
        raise ValueError("LES model cannot be None")
 
    key = str(value).strip().lower().replace("-", "_").replace(" ", "_")
    mapped = {
        "none": 0,
        "off": 0,
        "disabled": 0,
        "no_les": 0,
        "constant": 1,
        "constant_smagorinsky": 1,
        "smagorinsky": 1,
        "dynamic": 2,
        "dynamic_smagorinsky": 2,
        "vreman": 3,
        "wale": 4,
    }.get(key)
    if mapped is None:
        raise ValueError(
            f"Unknown LES model '{value}'. Use one of: 'none', "
            "'constant_smagorinsky', 'dynamic_smagorinsky', 'vreman', 'wale'."
        )
    return mapped
 
def normalize_les_test_filter(value) -> int:
    """!
    @brief Maps LES test-filter kernel names to the C -les_test_filter_kernel flag.
    @param[in] value Test-filter selector name or integer code.
    @return 0 for the volume-weighted box filter, 1 for the i/k Simpson filter.
    @throws ValueError if the input cannot be mapped.
    """
    if isinstance(value, bool):
        raise ValueError("models.physics.turbulence.les.test_filter.kernel must name a filter, not a boolean.")
    if isinstance(value, int):
        if value in (0, 1):
            return value
        raise ValueError("models.physics.turbulence.les.test_filter.kernel must be 0, 1, or a supported filter name.")
    if value is None:
        raise ValueError("LES test_filter.kernel cannot be None")
 
    key = str(value).strip().lower().replace("-", "_").replace(" ", "_")
    mapped = {
        "volume_weighted_box": 0,
        "box": 0,
        "simpson_ik": 1,
    }.get(key)
    if mapped is None:
        raise ValueError(
            f"Unknown LES test filter kernel '{value}'. Use one of: "
            "'volume_weighted_box', 'simpson_ik'."
        )
    return mapped
 
def normalize_les_filter_width(value) -> int:
    """!
    @brief Maps LES grid-filter-width model names to the C -les_filter_width flag.
    @param[in] value Filter-width model name or integer code.
    @return 0 for cube-root volume, 1 for the geometric mean of the cell extents,
            2 for the longest cell extent, 3 for the Scotti aspect-ratio correction.
    @throws ValueError if the input cannot be mapped.
    """
    if isinstance(value, bool):
        raise ValueError("models.physics.turbulence.les.filter_width must name a model, not a boolean.")
    if isinstance(value, int):
        if value in (0, 1, 2, 3):
            return value
        raise ValueError("models.physics.turbulence.les.filter_width must be 0, 1, 2, 3, or a supported model name.")
    if value is None:
        raise ValueError("LES filter_width cannot be None")
 
    key = str(value).strip().lower().replace("-", "_").replace(" ", "_")
    mapped = {
        "cube_root_volume": 0,
        "geometric_mean": 1,
        "max_edge": 2,
        "scotti": 3,
    }.get(key)
    if mapped is None:
        raise ValueError(
            f"Unknown LES filter width model '{value}'. Use one of: "
            "'cube_root_volume', 'geometric_mean', 'max_edge', 'scotti'."
        )
    return mapped
 
def normalize_les_averaging_mode(value) -> int:
    """!
    @brief Maps LES coefficient-averaging mode names to the C -les_averaging_mode flag.
    @param[in] value Averaging mode name or integer code.
    @return 0 for pointwise local averaging, 1 for homogeneous directions, 2 for the
            whole block.
    @throws ValueError if the input cannot be mapped.
    """
    if isinstance(value, bool):
        raise ValueError("models.physics.turbulence.les.averaging.mode must name a mode, not a boolean.")
    if isinstance(value, int):
        if value in (0, 1, 2):
            return value
        raise ValueError("models.physics.turbulence.les.averaging.mode must be 0, 1, 2, or a supported mode name.")
    if value is None:
        raise ValueError("LES averaging.mode cannot be None")
 
    key = str(value).strip().lower().replace("-", "_").replace(" ", "_")
    mapped = {
        "local": 0,
        "homogeneous": 1,
        "global": 2,
    }.get(key)
    if mapped is None:
        raise ValueError(
            f"Unknown LES averaging mode '{value}'. Use one of: "
            "'local', 'homogeneous', 'global'."
        )
    return mapped
 
def normalize_les_clip_mode(value) -> int:
    """!
    @brief Maps LES coefficient-limiting mode names to the C -les_clip_mode flag.
    @param[in] value Clipping mode name or integer code.
    @return 0 to clamp into [0, max_cs^2], 1 to discard negatives only, 2 to keep the
            signed coefficient so backscatter survives.
    @throws ValueError if the input cannot be mapped.
    """
    if isinstance(value, bool):
        raise ValueError("models.physics.turbulence.les.clipping.mode must name a mode, not a boolean.")
    if isinstance(value, int):
        if value in (0, 1, 2):
            return value
        raise ValueError("models.physics.turbulence.les.clipping.mode must be 0, 1, 2, or a supported mode name.")
    if value is None:
        raise ValueError("LES clipping.mode cannot be None")
 
    key = str(value).strip().lower().replace("-", "_").replace(" ", "_")
    mapped = {
        "clamp": 0,
        "clip_negative": 1,
        "none": 2,
    }.get(key)
    if mapped is None:
        raise ValueError(
            f"Unknown LES clipping mode '{value}'. Use one of: "
            "'clamp', 'clip_negative', 'none'."
        )
    return mapped
 
#: The logical grid directions an LES averaging set may span, in canonical order.
LES_AVERAGING_DIRECTION_AXES = ("i", "j", "k")
 
def normalize_les_averaging_directions(value) -> str:
    """!
    @brief Maps a list of homogeneous logical directions to the C flag's string form.
    @param[in] value List or string naming a subset of the i, j, and k directions.
    @return The selected directions as a canonically ordered subset of "ijk".
    @throws ValueError if a direction is unknown or repeated.
    """
    if value is None:
        return ""
    if isinstance(value, str):
        tokens = [token for token in value.strip().lower()]
    elif isinstance(value, (list, tuple)):
        tokens = [str(token).strip().lower() for token in value]
    else:
        raise ValueError(
            "models.physics.turbulence.les.averaging.directions must be a list such as [i, k]."
        )
 
    selected = []
    for token in tokens:
        if token not in LES_AVERAGING_DIRECTION_AXES:
            raise ValueError(
                f"Unknown LES averaging direction '{token}'. Use a subset of ['i', 'j', 'k']."
            )
        if token in selected:
            raise ValueError(
                f"LES averaging direction '{token}' is repeated; list each direction once."
            )
        selected.append(token)
    return "".join(axis for axis in LES_AVERAGING_DIRECTION_AXES if axis in selected)
 
def normalize_wall_function_model(value) -> int:
    """!
    @brief Maps wall-function model selectors to the C -wallfunction flag.
    @param[in] value Wall-function selector name, or None for the default.
    @return Integer code accepted by -wallfunction; 1 log law, 2 Werner-Wengle, 3 Cabot.
    @throws ValueError if the input cannot be mapped.
    """
    if value is None:
        return 1
    if isinstance(value, bool):
        raise ValueError("models.physics.turbulence.wall_function.model must name a model, not a boolean.")
    if isinstance(value, int):
        if value in (1, 2, 3):
            return value
        raise ValueError("models.physics.turbulence.wall_function.model must be 1, 2, 3, or a supported model name.")
    key = str(value).strip().lower().replace("-", "_").replace(" ", "_")
    mapped = {
        "log_law": 1,
        "loglaw": 1,
        "werner": 2,
        "werner_wengle": 2,
        "cabot": 3,
    }.get(key)
    if mapped is None:
        raise ValueError(
            "Unknown wall_function model '%s'. Use one of: 'log_law', 'werner', 'cabot'." % value)
    return mapped
 
def resolve_enabled_flag(cfg: dict, path: str, default: bool = True) -> bool:
    """!
    @brief Resolves a structured `enabled` flag and rejects non-boolean values.
    @param[in] cfg Mapping that may contain `enabled`.
    @param[in] path Human-readable config path for diagnostics.
    @param[in] default Value used when `enabled` is omitted.
    @return Boolean enabled state.
    @throws ValueError if `enabled` is not a YAML boolean.
    """
    if 'enabled' not in cfg:
        return default
    if not isinstance(cfg['enabled'], bool):
        raise ValueError(f"{path}.enabled must be true or false.")
    return cfg['enabled']
 
def append_les_parameter_flags(les_cfg: dict, control_lines: list):
    """!
    @brief Appends the LES closure parameter flags from a structured les block.
    @param[in] les_cfg Parsed `models.physics.turbulence.les` mapping.
    @param[out] control_lines A list of strings to which C-flags will be appended.
    @throws ValueError if a selector name or nested block shape is unsupported.
    """
    if 'constant_cs' in les_cfg:
        control_lines.append(f"-les_constant_cs {format_flag_value(les_cfg['constant_cs'])}")
    if 'vreman_coefficient' in les_cfg:
        control_lines.append(f"-les_vreman_coefficient {format_flag_value(les_cfg['vreman_coefficient'])}")
    if 'wale_coefficient' in les_cfg:
        control_lines.append(f"-les_wale_coefficient {format_flag_value(les_cfg['wale_coefficient'])}")
    if 'dynamic_frequency' in les_cfg:
        control_lines.append(f"-les_dynamic_frequency {format_flag_value(les_cfg['dynamic_frequency'])}")
    if 'filter_width' in les_cfg:
        control_lines.append(f"-les_filter_width {normalize_les_filter_width(les_cfg['filter_width'])}")
 
    # A bare string is accepted as shorthand for naming only the kernel, matching the
    # way the les block itself accepts either a scalar or a mapping.
    test_filter = les_cfg.get('test_filter')
    if test_filter is not None:
        if not isinstance(test_filter, dict):
            test_filter = {'kernel': test_filter}
        if 'kernel' in test_filter:
            control_lines.append(
                f"-les_test_filter_kernel {normalize_les_test_filter(test_filter['kernel'])}")
        if 'width_ratio' in test_filter:
            control_lines.append(
                f"-les_test_filter_width_ratio {format_flag_value(test_filter['width_ratio'])}")
 
    averaging = les_cfg.get('averaging')
    if averaging is not None:
        if not isinstance(averaging, dict):
            averaging = {'mode': averaging}
        if 'mode' in averaging:
            control_lines.append(
                f"-les_averaging_mode {normalize_les_averaging_mode(averaging['mode'])}")
        if 'directions' in averaging:
            directions = normalize_les_averaging_directions(averaging['directions'])
            if directions:
                control_lines.append(f"-les_averaging_directions {directions}")
 
    clipping = les_cfg.get('clipping')
    if clipping is not None:
        if not isinstance(clipping, dict):
            clipping = {'mode': clipping}
        if 'mode' in clipping:
            control_lines.append(f"-les_clip_mode {normalize_les_clip_mode(clipping['mode'])}")
        if 'max_cs' in clipping:
            control_lines.append(f"-les_clip_max_cs {format_flag_value(clipping['max_cs'])}")
        if 'min_viscosity_ratio' in clipping:
            control_lines.append(
                f"-les_min_viscosity_ratio {format_flag_value(clipping['min_viscosity_ratio'])}")
 
    gradient_model = les_cfg.get('gradient_model')
    if gradient_model is not None:
        if not isinstance(gradient_model, dict):
            gradient_model = {'enabled': gradient_model}
        enabled = resolve_enabled_flag(gradient_model,
                                       "models.physics.turbulence.les.gradient_model")
        control_lines.append(f"-les_gradient_model {1 if enabled else 0}")
 
def resolve_les_diagnostics(case_cfg: dict, monitor_cfg: dict, warn: bool = False) -> "dict | None":
    """!
    @brief Resolve the LES diagnostic log settings from monitor.yml or their deprecated location.
    @details The log is observation, not physics, so it is configured in monitor.yml
             `diagnostics.les`; case.yml `models.physics.turbulence.les.diagnostics` is read as a
             deprecated alias. Setting both is refused. `yoshizawa_ci` only scales the subgrid
             kinetic energy the log reports, so it belongs with the log.
    @param[in] case_cfg Parsed case configuration.
    @param[in] monitor_cfg Parsed monitor configuration.
    @param[in] warn Print a deprecation warning when the case.yml location is used.
    @return {"enabled", optional "cadence", optional "yoshizawa_ci"}, or None when unset.
    @throws ValueError for a duplicated, malformed, or out-of-range setting.
    """
    monitor_value = (((monitor_cfg or {}).get("diagnostics") or {}).get("les")
                     if isinstance((monitor_cfg or {}).get("diagnostics"), dict) else None)
    les_cfg = ((((case_cfg or {}).get("models") or {}).get("physics") or {}).get("turbulence") or {}).get("les")
    case_value = les_cfg.get("diagnostics") if isinstance(les_cfg, dict) else None
    if monitor_value is not None and case_value is not None:
        raise ValueError("LES diagnostics are set in monitor.yml (diagnostics.les) and in their deprecated "
                         "case.yml location (models.physics.turbulence.les.diagnostics); keep only monitor.yml.")
    value, label = ((monitor_value, "monitor.yml diagnostics.les") if monitor_value is not None
                    else (case_value, "case.yml models.physics.turbulence.les.diagnostics"))
    if value is None:
        return None
    if not isinstance(value, dict):
        value = {"enabled": value}
    unknown = sorted(set(value) - {"enabled", "cadence", "yoshizawa_ci"})
    if unknown:
        raise ValueError(f"{label} has unsupported key(s): {unknown}. Use enabled, cadence, yoshizawa_ci.")
    resolved = {"enabled": resolve_enabled_flag(value, label)}
    if "cadence" in value:
        if isinstance(value["cadence"], bool) or not isinstance(value["cadence"], int) or value["cadence"] <= 0:
            raise ValueError(f"{label}.cadence must be a positive integer.")
        resolved["cadence"] = value["cadence"]
    if "yoshizawa_ci" in value:
        try:
            ci = _to_finite_float(value["yoshizawa_ci"], f"{label}.yoshizawa_ci")
        except (TypeError, ValueError) as exc:
            raise ValueError(f"{label}.yoshizawa_ci must be numeric.") from exc
        if ci < 0.0:
            raise ValueError(f"{label}.yoshizawa_ci must be non-negative.")
        resolved["yoshizawa_ci"] = ci
    if monitor_value is None and warn:
        print("[WARNING] case.yml models.physics.turbulence.les.diagnostics is deprecated; "
              "set it in monitor.yml as diagnostics.les.", file=sys.stderr)
    return resolved
 
 
def append_les_diagnostics_flags(diagnostics: "dict | None", control_lines: list):
    """!
    @brief Append the LES diagnostic log flags resolved by resolve_les_diagnostics().
    @param[in] diagnostics Resolved settings, or None to append nothing.
    @param[out] control_lines A list of strings to which C-flags will be appended.
    """
    if diagnostics is None:
        return
    control_lines.append(f"-les_diagnostics {'true' if diagnostics['enabled'] else 'false'}")
    if "cadence" in diagnostics:
        control_lines.append(f"-les_diagnostics_cadence {format_flag_value(diagnostics['cadence'])}")
    if "yoshizawa_ci" in diagnostics:
        control_lines.append(f"-les_yoshizawa_ci {format_flag_value(diagnostics['yoshizawa_ci'])}")
 
def append_turbulence_flags(models: dict, control_lines: list, scales: dict = None):
    """!
    @brief Appends turbulence model flags from legacy or structured case.yml blocks.
    @param[in] models Parsed case.yml `models` mapping.
    @param[out] control_lines A list of strings to which C-flags will be appended.
    @param[in] scales The case's reference scales. Required only when a physical
               roughness height is set.
    @throws RuntimeError when a roughness height is set and no scales were supplied.
    """
    turbulence_cfg = models.get('physics', {}).get('turbulence', {})
    if not turbulence_cfg:
        return
    if not isinstance(turbulence_cfg, dict):
        raise ValueError("models.physics.turbulence must be a mapping.")
 
    les_cfg = turbulence_cfg.get('les')
    rans_cfg = turbulence_cfg.get('rans')
    wall_cfg = turbulence_cfg.get('wall_function')
    les_code = None
 
    if isinstance(les_cfg, dict):
        enabled = resolve_enabled_flag(les_cfg, "models.physics.turbulence.les")
        model_value = les_cfg.get('model', 'constant_smagorinsky')
        les_code = normalize_les_model(model_value) if enabled else 0
        control_lines.append(f"-les {les_code}")
        append_les_parameter_flags(les_cfg, control_lines)
    elif les_cfg is not None:
        les_code = normalize_les_model(les_cfg)
        control_lines.append(f"-les {les_code}")
 
    if rans_cfg is not None:
        raise ValueError(RANS_PLANNED_REFUSAL)
 
    if isinstance(wall_cfg, dict):
        enabled = resolve_enabled_flag(wall_cfg, "models.physics.turbulence.wall_function")
        # The flag carries the model, with zero meaning disabled, so a selector change
        # reaches the runtime instead of being validated and dropped.
        wall_model = normalize_wall_function_model(wall_cfg.get('model'))
        control_lines.append(f"-wallfunction {wall_model if enabled else 0}")
        if 'roughness_height' in wall_cfg:
            if scales is None:
                raise RuntimeError("wall_function.roughness_height is a physical length and needs the case reference scales.")
            roughness = to_solver_units(
                wall_cfg['roughness_height'],
                ("case", "models", "physics", "turbulence", "wall_function", "roughness_height"), scales)
            control_lines.append(f"-wall_roughness {format_flag_value(roughness)}")
    elif wall_cfg is not None:
        control_lines.append(f"-wallfunction {format_flag_value(wall_cfg)}")
 
def control_value(value, context: str):
    """!
    @brief Guard a value that is written verbatim into the generated control file.
 
    @details PETSc reads the control file line by line, so a value containing a newline
             writes additional option lines - which defeats every key-based check by
             smuggling a whole new flag. Rejecting the value is the only safe handling;
             there is no quoting that makes a multi-line option meaningful.
    @param[in] value Configured value destined for a control line.
    @param[in] context YAML path, for the error message.
    @return The value unchanged when it is safe to emit.
    @throws SystemExit when the value would inject an option line.
    """
    text = str(value)
    if any(character in text for character in ("\n", "\r")):
        print(
            f"[FATAL] {context} contains a newline. Values written to the generated control "
            f"file must occupy a single line; a multi-line value would inject additional "
            f"PETSc options.",
            file=sys.stderr,
        )
        sys.exit(1)
    return value
 
 
def append_passthrough_flags(control_lines: list, options: dict):
    """!
    @brief Appends raw CLI flags to the control list from a {flag: value} dict.
    @details Boolean `true` is emitted as a switch with no value. Boolean `false`
             is skipped. All other values are emitted as "<flag> <value>".
    @param[out] control_lines The destination list of control-file lines.
    @param[in] options Mapping of raw CLI flags to values.
    """
    if not options:
        return
    for flag, value in options.items():
        if isinstance(flag, str) and flag.strip() in RESERVED_DIRECTORY_FLAGS:
            # Defense in depth: validation rejects these, but the emitter must never
            # write a run-directory flag from an unvalidated passthrough surface.
            raise ValueError(
                f"Refusing to emit reserved directory flag '{flag.strip()}' from passthrough "
                "options; run directories are fixed by the workspace contract."
            )
        if isinstance(value, bool):
            if value:
                control_lines.append(str(flag))
            continue
        control_lines.append(
            f"{flag} {control_value(format_flag_value(value), f'passthrough option {flag}')}"
        )
 
 
SOLVER_MONITORING_POISSON_FLAG_MAP = {
    "pic_true_residual": "-ps_ksp_pic_monitor_true_residual",
    "true_residual": "-ps_ksp_monitor_true_residual",
    "converged_reason": "-ps_ksp_converged_reason",
    "view": "-ps_ksp_view",
}
 
SOLVER_MONITORING_MOMENTUM_FLAG_MAP = {
    "newton_krylov_history": "-mom_nk_pic_monitor",
    "snes_monitor": "-mom_nk_snes_monitor",
    "snes_converged_reason": "-mom_nk_snes_converged_reason",
    "ksp_monitor": "-mom_nk_ksp_monitor",
    "ksp_converged_reason": "-mom_nk_ksp_converged_reason",
}
 
 
def resolve_solver_monitoring_flags(monitor_cfg: dict) -> dict:
    """!
    @brief Resolve human-readable solver monitoring YAML to raw control flags.
    @param[in] monitor_cfg Parsed monitor.yml mapping.
    @return Mapping of raw C/PETSc flags to values.
    """
    solver_mon_cfg = monitor_cfg.get("solver_monitoring", {}) if isinstance(monitor_cfg, dict) else {}
    if solver_mon_cfg is None:
        return {}
    if not isinstance(solver_mon_cfg, dict):
        raise ValueError("monitor.solver_monitoring must be a mapping when provided.")
 
    flags = {}
 
    momentum_cfg = solver_mon_cfg.get("momentum", {})
    if momentum_cfg is None:
        momentum_cfg = {}
    if not isinstance(momentum_cfg, dict):
        raise ValueError("monitor.solver_monitoring.momentum must be a mapping when provided.")
    unknown_momentum = sorted(set(momentum_cfg.keys()) - set(SOLVER_MONITORING_MOMENTUM_FLAG_MAP.keys()))
    if unknown_momentum:
        raise ValueError(f"monitor.solver_monitoring.momentum has unsupported key(s): {unknown_momentum}.")
    for key, flag in SOLVER_MONITORING_MOMENTUM_FLAG_MAP.items():
        if key in momentum_cfg:
            value = momentum_cfg[key]
            if not isinstance(value, bool):
                raise ValueError(f"monitor.solver_monitoring.momentum.{key} must be boolean.")
            flags[flag] = value
 
    poisson_cfg = solver_mon_cfg.get("poisson", {})
    if poisson_cfg is None:
        poisson_cfg = {}
    if not isinstance(poisson_cfg, dict):
        raise ValueError("monitor.solver_monitoring.poisson must be a mapping when provided.")
    unknown_poisson = sorted(set(poisson_cfg.keys()) - set(SOLVER_MONITORING_POISSON_FLAG_MAP.keys()))
    if unknown_poisson:
        raise ValueError(f"monitor.solver_monitoring.poisson has unsupported key(s): {unknown_poisson}.")
    for key, flag in SOLVER_MONITORING_POISSON_FLAG_MAP.items():
        if key in poisson_cfg:
            value = poisson_cfg[key]
            if not isinstance(value, bool):
                raise ValueError(f"monitor.solver_monitoring.poisson.{key} must be boolean.")
            flags[flag] = value
 
    passthrough = solver_mon_cfg.get("petsc_passthrough_options", {})
    if passthrough is None:
        passthrough = {}
    if not isinstance(passthrough, dict):
        raise ValueError("monitor.solver_monitoring.petsc_passthrough_options must be a mapping when provided.")
    flags.update(passthrough)
 
    legacy_raw = {
        key: value
        for key, value in solver_mon_cfg.items()
        if isinstance(key, str) and key.startswith("-")
    }
    flags.update(legacy_raw)
 
    unknown_top = sorted(
        key
        for key in solver_mon_cfg.keys()
        if key not in {"momentum", "poisson", "petsc_passthrough_options"} and not (isinstance(key, str) and key.startswith("-"))
    )
    if unknown_top:
        raise ValueError(
            "monitor.solver_monitoring has unsupported key(s): "
            f"{unknown_top}. Use 'momentum'/'poisson' for structured monitors or "
            "'petsc_passthrough_options' for raw PETSc flags."
        )
 
    return flags
 
 
MAX_TRACED_PARTICLES = 64  # PICURV_MAX_TRACED_PARTICLES in include/variables.h
 
 
def resolve_traced_particle_ids(monitor_cfg: dict) -> list:
    """!
    @brief Return the sorted, distinct particle IDs of `logging.trace_particles`.
    @param[in] monitor_cfg Parsed monitor configuration.
    @return Sorted list of non-negative integer IDs; empty when tracing is off.
    @throws ValueError When the value is not a list of at most 64 non-negative integers.
    """
    logging_cfg = monitor_cfg.get('logging') if isinstance(monitor_cfg, dict) else None
    if not isinstance(logging_cfg, dict) or logging_cfg.get('trace_particles') is None:
        return []
    raw = logging_cfg['trace_particles']
    if not isinstance(raw, list) or any(isinstance(pid, bool) or not isinstance(pid, int) or pid < 0 for pid in raw):
        raise ValueError("'logging.trace_particles' must be a list of non-negative integer particle IDs "
                         f"(got {raw!r}).")
    traced = sorted(set(raw))
    if len(traced) > MAX_TRACED_PARTICLES:
        raise ValueError(f"'logging.trace_particles' accepts at most {MAX_TRACED_PARTICLES} particle IDs "
                         f"(got {len(traced)}).")
    return traced
 
 
def resolve_particle_console_output_frequency(io_cfg: dict) -> "int | None":
    """!
    @brief Return the effective particle-console snapshot cadence from monitor.yml.
    @param[in] io_cfg Argument passed to `resolve_particle_console_output_frequency()`.
    @return Value returned by `resolve_particle_console_output_frequency()`.
    """
    if 'particle_console_output_frequency' in io_cfg:
        return io_cfg['particle_console_output_frequency']
    return io_cfg.get('data_output_frequency')
 
def parse_and_add_model_flags(case_cfg: dict, control_lines: list):
    """!
    @brief Parses the 'models' section of case.yml and adds corresponding C-solver flags.
    @param[in] case_cfg The parsed case.yml configuration dictionary.
    @param[out] control_lines A list of strings to which C-flags will be appended.
    """
    models = case_cfg.get('models', {})
    FLAG_MAP = {
        'domain': {'blocks': '-nblk'},
        'physics.fsi': {'immersed': '-imm', 'moving_fsi': '-fsi'},
        'physics.particles': {'count': '-numParticles', 'random_seed': '-particle_random_seed'},
    }
    for section_path, flags in FLAG_MAP.items():
        current_level = models
        try:
            for key in section_path.split('.'): current_level = current_level[key]
            for yaml_key, flag in flags.items():
                if yaml_key in current_level:
                    control_lines.append(f"{flag} {format_flag_value(current_level[yaml_key])}")
        except KeyError: continue
 
    wall_cfg = (((models.get('physics') or {}).get('turbulence') or {}).get('wall_function'))
    needs_scales = isinstance(wall_cfg, dict) and 'roughness_height' in wall_cfg
    append_turbulence_flags(models, control_lines,
                            resolve_reference_scales(case_cfg) if needs_scales else None)
 
    if models.get('physics', {}).get('dimensionality') == '2D':
        control_lines.append("-TwoD 1")
    
    particles_cfg = models.get('physics', {}).get('particles', {})
    p_init_mode_str = particles_cfg.get('init_mode', 'Surface')
    pinit_code = normalize_particle_init_mode(p_init_mode_str)
    control_lines.append(f"-pinit {pinit_code}")
    print(f"  - Particle Initialization Mode: {p_init_mode_str} (Code: {pinit_code})")
 
    if pinit_code == 2:
        point_cfg = particles_cfg.get('point_source', {})
        if not isinstance(point_cfg, dict):
            raise ValueError("models.physics.particles.point_source must be a mapping when init_mode is PointSource.")
        scales = resolve_reference_scales(case_cfg)
        point_path = ("case", "models", "physics", "particles", "point_source")
        try:
            psrc = [to_solver_units(point_cfg[axis], point_path + (axis,), scales) for axis in ("x", "y", "z")]
        except (KeyError, TypeError, ValueError):
            raise ValueError("PointSource init_mode requires numeric point_source.{x,y,z} values.")
        for axis, value in zip(("x", "y", "z"), psrc):
            control_lines.append(f"-psrc_{axis} {value}")
        print(f"  - Particle Point Source: ({point_cfg['x']}, {point_cfg['y']}, {point_cfg['z']}) "
              f"-> solver units ({psrc[0]}, {psrc[1]}, {psrc[2]})")
 
    if particles_cfg.get('fields'):
        particle_fields = normalize_particle_fields(particles_cfg['fields'])
        control_lines.append(f"-particle_fields_count {len(particle_fields)}")
        for index, entry in enumerate(particle_fields):
            control_lines.append(f"-particle_fields_{index}_name {entry['name']}")
            for component, expression in enumerate(entry["expressions"]):
                text = control_value(expression, f"models.physics.particles.fields.{entry['name']}")
                control_lines.append(f"-particle_fields_{index}_expr_{component} \"{text}\"")
            print(f"  - Particle Field Initial Value: {entry['name']} = {' ; '.join(entry['expressions'])}")
 
    p_restart_mode = particles_cfg.get('restart_mode')
    if p_restart_mode:
        p_restart_mode_normalized = str(p_restart_mode).lower()
        if p_restart_mode_normalized not in PARTICLE_RESTART_MODES:
            raise ValueError(f"Unknown particle restart_mode '{p_restart_mode}'. Options are 'init' or 'load'.")
        control_lines.append(f"-particle_restart_mode \"{p_restart_mode}\"")
 
# PETSc KSP types whose iteration adapts to the input vector. Any of these used as
# the multigrid coarse solve (level_0) makes the MG preconditioner a nonlinear
# operator; see docs/pages/25_Pressure_Poisson_GMRES_Multigrid.md.
KRYLOV_KSP_TYPES = {
    "gmres", "fgmres", "lgmres", "dgmres", "pgmres", "gcr",
    "cg", "cgne", "cgs", "bcgs", "ibcgs", "fbcgs", "fbcgsr", "bcgsl",
    "tfqmr", "tcqmr", "minres", "symmlq", "cr", "lsqr", "pipecg", "pipefgmres",
}
 
def parse_solver_config(solver_cfg: dict, scales: dict = None, case_cfg: dict = None) -> dict:
    """!
    @brief Parses the structured solver.yml into a flat dictionary of {flag: value}.
    @param[in] solver_cfg The parsed solver.yml configuration dictionary.
    @param[in] scales The case's reference scales. Required only when solver.yml sets a
               dimensional value, which is physical and is converted here.
    @param[in] case_cfg The parsed case.yml, which holds the scalar-transport parameters.
    @return A dictionary where keys are C-solver flags and values are the corresponding settings.
    """
    flags = {}
 
    def solver_value(path: tuple, value) -> float:
        """!
        @brief Convert one solver.yml value by its recorded dimension.
        @param[in] path Schema path under solver.yml.
        @param[in] value Value as written.
        @return The value in solver units.
        @throws RuntimeError when the value is dimensional and no scales were supplied; that
                is a caller error, kept distinct from the ValueError of an invalid value.
        """
        full_path = ("solver",) + path
        if input_quantity(full_path)[0] == DIMENSIONLESS:
            return _to_finite_float(value, ".".join(path))
        if scales is None:
            raise RuntimeError(f"{'.'.join(path)} is a physical value and needs the case reference scales.")
        return to_solver_units(value, full_path, scales)
    if 'operation_mode' in solver_cfg and isinstance(solver_cfg['operation_mode'], dict):
        op_mode = solver_cfg['operation_mode']
        if 'eulerian_field_source' in op_mode:
            normalized_source = normalize_eulerian_field_source(op_mode.get('eulerian_field_source'))
            flags['-euler_field_source'] = f"\"{normalized_source}\""
        if 'analytical_type' in op_mode and op_mode.get('analytical_type') is not None:
            normalized_analytical_type = normalize_analytical_type(op_mode.get('analytical_type'))
            flags['-analytical_type'] = f"\"{normalized_analytical_type}\""
            if normalized_analytical_type == "UNIFORM_FLOW":
                uniform_flow_cfg = op_mode.get('uniform_flow', {})
                if not isinstance(uniform_flow_cfg, dict):
                    raise ValueError("operation_mode.uniform_flow must be a mapping when analytical_type is 'UNIFORM_FLOW'.")
                try:
                    for component in ("u", "v", "w"):
                        flags[f'-analytical_uniform_{component}'] = solver_value(
                            ("operation_mode", "uniform_flow", component), uniform_flow_cfg[component])
                except KeyError as exc:
                    raise ValueError(f"operation_mode.uniform_flow.{exc.args[0]} is required when analytical_type is 'UNIFORM_FLOW'.") from exc
                except (TypeError, ValueError) as exc:
                    raise ValueError("operation_mode.uniform_flow.{u,v,w} must be numeric when analytical_type is 'UNIFORM_FLOW'.") from exc
 
    verification_cfg = solver_cfg.get('verification', {})
    if verification_cfg:
        if not isinstance(verification_cfg, dict):
            raise ValueError("verification must be a mapping when provided.")
        sources_cfg = verification_cfg.get('sources', {})
        if not isinstance(sources_cfg, dict):
            raise ValueError("verification.sources must be a mapping when provided.")
        diff_cfg = sources_cfg.get('diffusivity')
        if diff_cfg is not None:
            if not isinstance(diff_cfg, dict):
                raise ValueError("verification.sources.diffusivity must be a mapping.")
            try:
                flags['-verification_diffusivity_mode'] = f"\"{str(diff_cfg['mode']).strip().lower()}\""
                flags['-verification_diffusivity_profile'] = f"\"{str(diff_cfg['profile']).strip().upper()}\""
                for key in ("gamma0", "slope_x"):
                    flags[f'-verification_diffusivity_{key}'] = solver_value(
                        ("verification", "sources", "diffusivity", key), diff_cfg[key])
            except KeyError as exc:
                raise ValueError(f"verification.sources.diffusivity.{exc.args[0]} is required.") from exc
            except (TypeError, ValueError) as exc:
                raise ValueError("verification.sources.diffusivity.{gamma0,slope_x} must be numeric and mode/profile must be scalar strings.") from exc
 
        scalar_cfg = sources_cfg.get('scalar')
        if scalar_cfg is not None:
            if not isinstance(scalar_cfg, dict):
                raise ValueError("verification.sources.scalar must be a mapping.")
            try:
                flags['-verification_scalar_mode'] = f"\"{str(scalar_cfg['mode']).strip().lower()}\""
                flags['-verification_scalar_profile'] = f"\"{str(scalar_cfg['profile']).strip().upper()}\""
            except KeyError as exc:
                raise ValueError(f"verification.sources.scalar.{exc.args[0]} is required.") from exc
 
            scalar_numeric_keys = {
                'CONSTANT': ('value',),
                'LINEAR_X': ('phi0', 'slope_x'),
                'SIN_PRODUCT': ('amplitude', 'kx', 'ky', 'kz'),
            }
            profile = str(scalar_cfg.get('profile', '')).strip().upper()
            for key in scalar_numeric_keys.get(profile, ()):
                try:
                    flags[f'-verification_scalar_{key}'] = solver_value(
                        ("verification", "sources", "scalar", key), scalar_cfg[key])
                except KeyError as exc:
                    raise ValueError(f"verification.sources.scalar.{exc.args[0]} is required.") from exc
                except (TypeError, ValueError) as exc:
                    raise ValueError(f"verification.sources.scalar.{key} must be numeric.") from exc
 
    for key, value in resolve_scalar_transport(case_cfg, solver_cfg).items():
        flags[SCALAR_TRANSPORT_FLAGS[key]] = value
 
    selected_solver = None
    if 'strategy' in solver_cfg:
        s = solver_cfg['strategy']
        if 'central_diff' in s:
            flags['-central'] = format_flag_value(s['central_diff'])
        # Preferred selector.
        if 'momentum_solver' in s:
            selected_solver = normalize_momentum_solver_type(s['momentum_solver'])
        elif 'implicit' in s:
            raise ValueError("Legacy key 'strategy.implicit' is not supported. Use 'strategy.momentum_solver'.")
 
    def _warn_inactive_absolute_tol(cfg: dict, where: str):
        """!
        @brief Warn when absolute_tol is set but cannot affect convergence.
 
        absolute_tol bounds the velocity update. Since |dU| ~ dtau*|R|, bounding it
        absolutely is a disguised, step-size-dependent residual bound, so it takes no
        part once a residual tolerance is active -- which is now the default. Setting it
        therefore has no effect, and silently ineffective knobs are what this warning
        exists to prevent. See docs/pages/24_Dual_Time_Picard_Jameson_RK.md.
        @param[in] cfg Tolerance mapping to inspect for `absolute_tol` and the residual keys.
        @param[in] where Config path used to locate the offending key in the warning text.
        @return None; emits a warning on stderr when `absolute_tol` cannot take effect.
        """
        if 'absolute_tol' not in cfg:
            return
        # Residual convergence is enabled unless BOTH residual tolerances are explicitly
        # non-positive; their defaults (1e-8 / 1e-3) are positive.
        def _off(key):
            """!
            @brief Report whether a residual tolerance is explicitly disabled.
            @param[in] key Residual tolerance key to inspect.
            @return True when the key is present and non-positive.
            """
            v = cfg.get(key, None)
            try:
                return v is not None and float(v) <= 0.0
            except (TypeError, ValueError):
                return False
        if _off('residual_absolute_tol') and _off('residual_relative_tol'):
            return
        print(
            f"[WARNING] {where}.absolute_tol is set but takes no part in convergence while a "
            "residual tolerance is active (the default). It is retained only for the legacy "
            "update-only branch, which can converge falsely when dtau collapses. To control "
            "accuracy use residual_relative_tol / residual_absolute_tol. See "
            "docs/pages/24_Dual_Time_Picard_Jameson_RK.md.",
            file=sys.stderr,
        )
 
    ms = solver_cfg.get('momentum_solver', {})
    if selected_solver is None:
        selected_solver = "DUALTIME_PICARD_JAMESON_RK"
    flags['-mom_solver_type'] = f"\"{selected_solver}\""
 
    if 'tolerances' in solver_cfg:
        t = solver_cfg['tolerances']
        tol_map = {
            'max_iterations': '-mom_max_pseudo_steps',
            'absolute_tol': '-mom_atol',
            'relative_tol': '-mom_rtol',
            'residual_absolute_tol': '-mom_resid_atol',
            'residual_relative_tol': '-mom_resid_rtol',
            'step_tol': '-imp_stol'
        }
        for key, flag in tol_map.items():
            if key in t:
                flags[flag] = t[key]
        _warn_inactive_absolute_tol(t, "tolerances")
 
    def _append_dualtime_options(cfg: dict):
        """!
        @brief Append dualtime options.
        @param[in] cfg Argument passed to `_append_dualtime_options()`.
        """
        if 'max_pseudo_steps' in cfg:
            flags['-mom_max_pseudo_steps'] = cfg['max_pseudo_steps']
        if 'absolute_tol' in cfg:
            flags['-mom_atol'] = cfg['absolute_tol']
            _warn_inactive_absolute_tol(
                {**solver_cfg.get('tolerances', {}), **cfg},
                "momentum_solver.dual_time_picard_jameson_rk")
        if 'relative_tol' in cfg:
            flags['-mom_rtol'] = cfg['relative_tol']
        if 'step_tol' in cfg:
            flags['-imp_stol'] = cfg['step_tol']
        if 'pseudo_cfl' in cfg:
            pcfl = cfg['pseudo_cfl']
            if 'initial' in pcfl:
                flags['-pseudo_cfl'] = pcfl['initial']
            if 'minimum' in pcfl:
                flags['-min_pseudo_cfl'] = pcfl['minimum']
            if 'maximum' in pcfl:
                flags['-max_pseudo_cfl'] = pcfl['maximum']
            if 'growth_factor' in pcfl:
                flags['-pseudo_cfl_growth_factor'] = pcfl['growth_factor']
            if 'reduction_factor' in pcfl:
                flags['-pseudo_cfl_reduction_factor'] = pcfl['reduction_factor']
        if 'jameson_residual_noise_allowance_factor' in cfg:
            flags['-mom_dt_jameson_residual_norm_noise_allowance_factor'] = cfg['jameson_residual_noise_allowance_factor']
        elif 'rk4_residual_noise_allowance_factor' in cfg:
            flags['-mom_dt_jameson_residual_norm_noise_allowance_factor'] = cfg['rk4_residual_noise_allowance_factor']
        if 'ratio_ema_alpha' in cfg:
            flags['-mom_ratio_ema_alpha'] = cfg['ratio_ema_alpha']
 
    def _append_newton_krylov_options(cfg: dict):
        """!
        @brief Append validated structured Newton--Krylov PETSc options.
        @param[in] cfg Structured Newton--Krylov mapping.
        """
        cfg = validate_newton_krylov_config(cfg)
        jacobian = cfg["jacobian"]
        flags["-mom_nk_jacobian_type"] = jacobian["type"]
        flags["-mom_nk_jacobian_fd_mode"] = jacobian["finite_difference"]["mode"]
        preconditioner = cfg["preconditioner"]
        flags["-mom_nk_preconditioner_model"] = preconditioner["model"]
        flags["-mom_nk_preconditioner_structure"] = preconditioner["structure"]["type"]
        nonlinear = cfg["nonlinear_solver"]
        nonlinear_map = {
            "method": "-mom_nk_snes_type",
            "absolute_tolerance": "-mom_nk_snes_atol",
            "relative_tolerance": "-mom_nk_snes_rtol",
            "step_tolerance": "-mom_nk_snes_stol",
            "max_iterations": "-mom_nk_snes_max_it",
        }
        for key, flag in nonlinear_map.items():
            if key in nonlinear:
                flags[flag] = nonlinear[key]
        line_search = nonlinear.get("line_search", {})
        if "type" in line_search:
            flags["-mom_nk_snes_linesearch_type"] = line_search["type"]
        ew = nonlinear.get("eisenstat_walker")
        if ew:
            flags["-mom_nk_snes_ksp_ew"] = ew["enabled"]
            if ew["enabled"]:
                ew_map = {
                    "version": "-mom_nk_snes_ksp_ew_version",
                    "initial_relative_tolerance": "-mom_nk_snes_ksp_ew_rtol0",
                    "maximum_relative_tolerance": "-mom_nk_snes_ksp_ew_rtolmax",
                    "gamma": "-mom_nk_snes_ksp_ew_gamma",
                    "exponent": "-mom_nk_snes_ksp_ew_alpha",
                    "safeguard_exponent": "-mom_nk_snes_ksp_ew_alpha2",
                    "safeguard_threshold": "-mom_nk_snes_ksp_ew_threshold",
                }
                for key, flag in ew_map.items():
                    if key in ew:
                        flags[flag] = ew[key]
 
        linear = cfg["linear_solver"]
        linear_map = {
            "method": "-mom_nk_ksp_type",
            "absolute_tolerance": "-mom_nk_ksp_atol",
            "relative_tolerance": "-mom_nk_ksp_rtol",
            "max_iterations": "-mom_nk_ksp_max_it",
        }
        for key, flag in linear_map.items():
            if key in linear:
                flags[flag] = linear[key]
        gmres = linear.get("gmres", {})
        if "restart" in gmres:
            flags["-mom_nk_ksp_gmres_restart"] = gmres["restart"]
 
    if isinstance(ms, dict):
        allowed_ms_keys = {'type', 'dual_time_picard_jameson_rk', 'dual_time_picard_rk4', 'newton_krylov'}
        unknown_ms_keys = sorted(set(ms.keys()) - allowed_ms_keys)
        if unknown_ms_keys:
            raise ValueError(
                f"Unsupported momentum_solver keys/blocks: {unknown_ms_keys}. "
                "Currently supported blocks: 'dual_time_picard_jameson_rk' and 'newton_krylov'."
            )
 
        if 'dual_time_picard_jameson_rk' in ms and 'dual_time_picard_rk4' in ms:
            raise ValueError(
                "Use only momentum_solver.dual_time_picard_jameson_rk; "
                "do not also set its deprecated dual_time_picard_rk4 alias."
            )
        dt_picard_cfg = ms.get('dual_time_picard_jameson_rk', ms.get('dual_time_picard_rk4'))
        if dt_picard_cfg is not None:
            if selected_solver != "DUALTIME_PICARD_JAMESON_RK":
                raise ValueError(
                    f"momentum_solver.dual_time_picard_jameson_rk is set but selected solver is {selected_solver}."
                )
            if not isinstance(dt_picard_cfg, dict):
                raise ValueError("momentum_solver.dual_time_picard_jameson_rk must be a mapping.")
            if ('jameson_residual_noise_allowance_factor' in dt_picard_cfg and
                    'rk4_residual_noise_allowance_factor' in dt_picard_cfg):
                raise ValueError(
                    "Use only jameson_residual_noise_allowance_factor; "
                    "do not also set its deprecated rk4_residual_noise_allowance_factor alias."
                )
            _append_dualtime_options(dt_picard_cfg)
        newton_cfg = ms.get('newton_krylov')
        if newton_cfg is not None:
            if selected_solver != "newton_krylov":
                raise ValueError(
                    f"momentum_solver.newton_krylov is set but selected solver is {selected_solver}."
                )
            _append_newton_krylov_options(newton_cfg)
    def _normalize_poisson_method(value) -> str:
        """!
        @brief Normalize a user-facing Poisson linear-solver method name.
        @param[in] value Method value from the solver YAML.
        @return Lowercase PETSc KSP method token.
        """
        method = str(value).strip().lower()
        if not method:
            raise ValueError("poisson_solver.method cannot be empty.")
        if method in POISSON_KSP_REFUSED:
            raise ValueError(
                f"poisson_solver.method '{method}' {POISSON_KSP_REFUSED[method]}: PICurv's "
                "multigrid preconditioner is not a single fixed linear operator, and with it "
                f"'{method}' reports convergence while the true residual stalls, so the "
                "projection uses the wrong pressure. Use 'fgmres' (default) or 'cg'."
            )
        if method not in POISSON_KSP_METHODS:
            raise ValueError(
                f"poisson_solver.method '{method}' is not one of {sorted(POISSON_KSP_METHODS)}, "
                "the methods verified with the multigrid preconditioner. Another PETSc KSP type "
                "can still be set through petsc_passthrough_options (-ps_ksp_type), unverified."
            )
        return method
 
    def _normalize_poisson_preconditioner(value) -> str:
        """!
        @brief Normalize and validate the outer Poisson preconditioner name.
        @param[in] value Preconditioner value from the solver YAML.
        @return PETSc PC token for the supported outer preconditioner.
        """
        pc = str(value).strip().lower()
        pc = POISSON_PRECONDITIONER_SPELLINGS.get(pc, pc)
        if pc not in POISSON_PRECONDITIONER_TYPES:
            raise ValueError(
                "poisson_solver.preconditioner.type currently supports only 'multigrid'. "
                "The runtime Poisson solver still assumes PETSc PCMG setup."
            )
        return "mg"
 
    def _warn_if_krylov_coarse_solver(ksp_type, source_key: str):
        """!
        @brief Warn when the coarsest multigrid level is given a Krylov solver.
        @param[in] ksp_type PETSc KSP token configured for `level_0`.
        @param[in] source_key Name of the source YAML block, used in the message.
        @details level_0 is the coarse solve at the base of the V-cycle, not a
                 smoother. A Krylov method there makes the multigrid
                 preconditioner a nonlinear operator, which decouples the outer
                 KSP's tracked residual from the true residual b-Ax. This stays a
                 warning rather than an error because it remains legitimate at
                 large scale when tolerances are set against the true residual.
        """
        if str(ksp_type).strip().lower() not in KRYLOV_KSP_TYPES:
            return
        print(
            f"[WARNING] {source_key}.multigrid.level_solvers.level_0.method = '{ksp_type}' "
            "is a Krylov method. level_0 is the multigrid COARSE SOLVE, not a smoother, "
            "so a Krylov method there makes the preconditioner nonlinear and the outer "
            "KSP's tracked residual can stop matching the true residual b-Ax. "
            "Prefer {method: preonly, preconditioner: redundant}. If this is deliberate, "
            "enable solver_monitoring.poisson.pic_true_residual and set tolerances against "
            "the true residual. See docs/pages/25_Pressure_Poisson_GMRES_Multigrid.md.",
            file=sys.stderr,
        )
 
    def _poisson_level_number(level_name) -> int:
        """!
        @brief Extract the numeric suffix from a `level_N` multigrid level key.
        @param[in] level_name YAML level key supplied by the user.
        @return Numeric level suffix.
        """
        text = str(level_name).strip()
        match = re.fullmatch(r"level_(\d+)", text)
        if not match:
            raise ValueError(f"Invalid Poisson multigrid level name '{level_name}'. Expected 'level_N'.")
        return int(match.group(1))
 
    def _append_poisson_solver_flags(ps: dict, source_key: str):
        """!
        @brief Append structured Poisson solver options to the flat PETSc flag map.
        @param[in] ps The `poisson_solver` or legacy `pressure_solver` mapping.
        @param[in] source_key Name of the source YAML block, used in error messages.
        """
        if not isinstance(ps, dict):
            raise ValueError(f"{source_key} must be a mapping when provided.")
 
        method = None
        if 'method' in ps:
            method = _normalize_poisson_method(ps['method'])
            flags['-ps_ksp_type'] = method
            flags.update(POISSON_KSP_METHODS[method])
        if 'absolute_tolerance' in ps:
            flags['-ps_ksp_atol'] = ps['absolute_tolerance']
        if 'relative_tolerance' in ps:
            flags['-ps_ksp_rtol'] = ps['relative_tolerance']
        if 'max_iterations' in ps:
            flags['-ps_ksp_max_it'] = ps['max_iterations']
        if 'tolerance' in ps:
            raise ValueError(
                f"{source_key}.tolerance is not a solver control: the runtime read it and never "
                "used it. Use absolute_tolerance (-> -ps_ksp_atol) and relative_tolerance "
                "(-> -ps_ksp_rtol), which the Poisson KSP applies."
            )
 
        gmres_cfg = ps.get('gmres', {})
        if gmres_cfg is not None:
            if not isinstance(gmres_cfg, dict):
                raise ValueError(f"{source_key}.gmres must be a mapping when provided.")
            if 'restart' in gmres_cfg:
                if method is None:
                    method = _normalize_poisson_method(ps.get('method', 'fgmres'))
                    flags.setdefault('-ps_ksp_type', method)
                if method not in GMRES_RESTART_METHODS:
                    raise ValueError(
                        f"{source_key}.gmres.restart is valid only when {source_key}.method "
                        "is one of 'gmres', 'fgmres', or 'lgmres'."
                    )
                flags['-ps_ksp_gmres_restart'] = gmres_cfg['restart']
 
        preconditioner_cfg = ps.get('preconditioner', {})
        if preconditioner_cfg:
            if not isinstance(preconditioner_cfg, dict):
                raise ValueError(f"{source_key}.preconditioner must be a mapping when provided.")
            if 'type' in preconditioner_cfg:
                flags['-ps_pc_type'] = _normalize_poisson_preconditioner(preconditioner_cfg['type'])
 
        if 'multigrid' in ps:
            mg = ps['multigrid']
            if not isinstance(mg, dict):
                raise ValueError(f"{source_key}.multigrid must be a mapping when provided.")
            mg_map = {'levels': '-mg_level', 'pre_sweeps': '-mg_pre_it', 'post_sweeps': '-mg_post_it'}
            for key, flag in mg_map.items():
                if key in mg: flags[flag] = mg[key]
            if 'cycle' in mg:
                cycle = str(mg['cycle']).strip().lower()
                if cycle not in {"v"}:
                    raise ValueError(f"{source_key}.multigrid.cycle currently supports only 'v'.")
            if 'mode' in mg:
                mode = str(mg['mode']).strip().lower()
                if mode not in {"multiplicative"}:
                    raise ValueError(f"{source_key}.multigrid.mode currently supports only 'multiplicative'.")
            if 'semi_coarsening' in mg:
                sc = mg['semi_coarsening']
                if not isinstance(sc, dict):
                    raise ValueError(f"{source_key}.multigrid.semi_coarsening must be a mapping when provided.")
                if 'i' in sc: flags['-mg_i_semi'] = format_flag_value(sc['i'])
                if 'j' in sc: flags['-mg_j_semi'] = format_flag_value(sc['j'])
                if 'k' in sc: flags['-mg_k_semi'] = format_flag_value(sc['k'])
            if 'level_solvers' in mg:
                level_solvers = mg['level_solvers']
                if not isinstance(level_solvers, dict):
                    raise ValueError(f"{source_key}.multigrid.level_solvers must be a mapping when provided.")
                for level_name, settings in level_solvers.items():
                    if not isinstance(settings, dict):
                        raise ValueError(f"{source_key}.multigrid.level_solvers.{level_name} must be a mapping.")
                    level_num = _poisson_level_number(level_name)
                    for key, value in settings.items():
                        # PETSc prefixes every per-level KSP control with ksp_; emitted
                        # bare, max_it/rtol/atol were left unused and silently ignored.
                        mapped_key = {
                            'method': 'ksp_type', 'preconditioner': 'pc_type',
                            'max_it': 'ksp_max_it', 'rtol': 'ksp_rtol', 'atol': 'ksp_atol',
                        }.get(key, key)
                        # PETSc names the coarsest solver separately from positive levels.
                        if level_num == 0:
                            prefix = "-ps_mg_coarse_"
                            if mapped_key == 'ksp_type':
                                _warn_if_krylov_coarse_solver(value, source_key)
                        else:
                            prefix = f"-ps_mg_levels_{level_num}_"
                        flags[f"{prefix}{mapped_key}"] = format_flag_value(value)
 
    if 'poisson_solver' in solver_cfg and 'pressure_solver' in solver_cfg:
        if solver_cfg['poisson_solver'] != solver_cfg['pressure_solver']:
            raise ValueError(
                "Both 'poisson_solver' and legacy 'pressure_solver' are present with different values. "
                "Use 'poisson_solver' only, or make the legacy alias identical."
            )
    poisson_cfg = solver_cfg.get('poisson_solver', solver_cfg.get('pressure_solver'))
    if poisson_cfg is not None:
        source_key = 'poisson_solver' if 'poisson_solver' in solver_cfg else 'pressure_solver'
        _append_poisson_solver_flags(poisson_cfg, source_key)
    interp_cfg = solver_cfg.get('interpolation', {})
    if isinstance(interp_cfg, dict):
        interp_method_str = interp_cfg.get('method', 'Trilinear')
    else:
        interp_method_str = 'Trilinear'
    interp_code = normalize_interpolation_method(interp_method_str)
    flags['-interpolation_method'] = interp_code
    print(f"  - Interpolation Method: {interp_method_str} (Code: {interp_code})")
 
    if 'petsc_passthrough_options' in solver_cfg:
        passthrough = solver_cfg['petsc_passthrough_options']
        if passthrough is None:
            passthrough = {}
        if not isinstance(passthrough, dict):
            raise ValueError("petsc_passthrough_options must be a mapping when provided.")
        if passthrough:
            for key, value in passthrough.items():
                if str(key).strip() == "-ps_mg_coarse_ksp_type":
                    _warn_if_krylov_coarse_solver(value, "petsc_passthrough_options")
                flags[key] = value if isinstance(value, bool) else format_flag_value(value)
    summary_bits = []
    if '-ps_ksp_type' in flags:
        summary_bits.append(f"method={flags['-ps_ksp_type']}")
    if '-ps_ksp_atol' in flags:
        summary_bits.append(f"atol={flags['-ps_ksp_atol']}")
    if '-ps_ksp_rtol' in flags:
        summary_bits.append(f"rtol={flags['-ps_ksp_rtol']}")
    if '-ps_ksp_max_it' in flags:
        summary_bits.append(f"max_it={flags['-ps_ksp_max_it']}")
    if '-mg_level' in flags:
        summary_bits.append(f"mg_levels={flags['-mg_level']}")
    if summary_bits:
        print(f"  - Poisson Solver: {', '.join(summary_bits)}")
    if selected_solver == "DUALTIME_PICARD_JAMESON_RK":
        dualtime_bits = []
        for label, flag in (
            ("initial_pseudo_cfl", "-pseudo_cfl"),
            ("pseudo_cfl_range", None),
            ("max_pseudo_steps", "-mom_max_pseudo_steps"),
        ):
            if flag and flag in flags:
                dualtime_bits.append(f"{label}={flags[flag]}")
            elif label == "pseudo_cfl_range" and "-min_pseudo_cfl" in flags and "-max_pseudo_cfl" in flags:
                dualtime_bits.append(f"pseudo_cfl_range=[{flags['-min_pseudo_cfl']}, {flags['-max_pseudo_cfl']}]")
        print("  - Momentum Solver: Dual Time Picard Jameson RK" +
              (f" ({', '.join(dualtime_bits)})" if dualtime_bits else ""))
    elif selected_solver == "newton_krylov":
        newton_bits = []
        for label, flag in (
            ("jacobian", "-mom_nk_jacobian_type"),
            ("nonlinear", "-mom_nk_snes_type"),
            ("linear", "-mom_nk_ksp_type"),
            ("preconditioner", "-mom_nk_preconditioner_model"),
        ):
            if flag in flags:
                newton_bits.append(f"{label}={flags[flag]}")
        print("  - Momentum Solver: Newton Krylov" +
              (f" ({', '.join(newton_bits)})" if newton_bits else " (PETSc defaults)"))
    else:
        print("  - Momentum Solver: Explicit RK (no pseudo-time controller)")
    return flags
 
def generate_solver_control_file(run_dir, run_id, configs, num_procs, monitor_files,
                                 restart_source_dir=None, continue_mode=False,
                                 config_dir: str = None):
    """!
    @brief Generates the main .control file for the C-solver.
    @details Orchestrates the conversion of all YAML configurations (case, solver, monitor)
    into a single, machine-readable file of command-line flags.
    @param[in] run_dir Argument passed to `generate_solver_control_file()`.
    @param[in] run_id Argument passed to `generate_solver_control_file()`.
    @param[in] configs Argument passed to `generate_solver_control_file()`.
    @param[in] num_procs Argument passed to `generate_solver_control_file()`.
    @param[in] monitor_files Argument passed to `generate_solver_control_file()`.
    @param[in] restart_source_dir Argument passed to `generate_solver_control_file()`.
    @param[in] continue_mode If True, appends -continue_mode flag for the C solver.
    @param[in] config_dir Optional configuration revision directory.
    @return Value returned by `generate_solver_control_file()`.
    """
    print("[INFO] Generating master solver control file...")
    case_cfg, solver_cfg, monitor_cfg = configs['case'], configs['solver'], configs['monitor']
    source_files = {'Case': configs['case_path'], 'Solver': configs['solver_path'], 'Monitor': configs['monitor_path']}
    
    control_lines = []
    try:
        props, run_ctrl = case_cfg['properties'], case_cfg['run_control']
        scales, fluid, ic = props['scaling'], props['fluid'], props['initial_conditions']
        prepared_blocks = validate_and_prepare_boundary_conditions(case_cfg)
        fluid_scaling = resolve_fluid_scaling(case_cfg)
        L_ref = fluid_scaling["length_ref"]
        U_ref = fluid_scaling["velocity_ref"]
        rho = fluid_scaling["density"]
        reynolds = fluid_scaling["reynolds"]
        dt_nondim = to_solver_units(run_ctrl['dt_physical'], ("case", "run_control", "dt_physical"), fluid_scaling)
        grid_length_scale = input_reference_scale(("case", "grid", "source_file"), fluid_scaling)
        print(f"  - Reynolds Number (Re) = {reynolds:.4f}")
        print(f"  - Non-Dimensional dt*  = {dt_nondim:.6f}")
        eulerian_source = normalize_eulerian_field_source(
            (solver_cfg.get("operation_mode", {}) or {}).get("eulerian_field_source", "solve")
        )
        start_step = int(run_ctrl.get("start_step", 0) or 0)
        ic_is_authoritative = eulerian_source == "solve" and start_step == 0
        ic_cli = []
        if ic_is_authoritative:
            resolved_ic = resolve_initial_condition_config(
                ic, prepared_blocks, fluid_scaling,
                provider_context={"kinematic_viscosity": fluid_scaling["nondimensional_kinematic_viscosity"]},
            )
            finit_mode_str = resolved_ic["label"]
            finit_code = resolved_ic["finit"]
            ic_params = resolved_ic["cli_params"]
            print(f"  - Initial Condition: {finit_mode_str} (Code: {finit_code})")
            if "ucont_x" in ic_params:
                ic_cli.extend([
                    f"-ucont_x {ic_params['ucont_x']}",
                    f"-ucont_y {ic_params['ucont_y']}",
                    f"-ucont_z {ic_params['ucont_z']}",
                ])
            if "ic_velocity_physical" in ic_params:
                ic_cli.append(f"-ic_velocity_physical {ic_params['ic_velocity_physical']}")
            if "flow_direction" in ic_params:
                ic_cli.append(f"-flow_direction {ic_params['flow_direction']}")
        else:
            source = (f"the run starts from the checkpoint at step {start_step}" if start_step > 0
                      else f"eulerian_field_source={eulerian_source!r} reads stored fields")
            print(f"[INFO] Initial condition not applied: {source}.")
            finit_code = 0
            resolved_ic = None
        control_lines.extend([
            f"-start_step {run_ctrl['start_step']}", f"-totalsteps {run_ctrl['total_steps']}",
            f"-ren {reynolds}", f"-dt {dt_nondim}", f"-finit {finit_code}",
            *ic_cli,
            f"-scaling_L_ref {L_ref}", f"-scaling_U_ref {U_ref}", f"-scaling_rho_ref {rho}"
        ])
    except (KeyError, TypeError, ZeroDivisionError, ValueError) as e:
        print(f"[FATAL] Error processing case.yml: {e}", file=sys.stderr)
        sys.exit(1)
        
    # --- CORRECTED: Add paths for whitelist and profile files ---
    if monitor_files.get("whitelist"):
        control_lines.append(f"-whitelist_config_file {monitor_files['whitelist']}")
    if monitor_files.get("profile"):
        control_lines.append(f"-profile_config_file {monitor_files['profile']}")
    append_passthrough_flags(control_lines, resolve_solution_monitoring_flags(monitor_cfg))
    control_lines.extend(resolve_field_statistics_flags(monitor_cfg, case_cfg))
    profiling_cfg = monitor_files.get("profiling", {})
    control_lines.append(f"-profiling_timestep_mode {profiling_cfg.get('mode', 'off')}")
    control_lines.append(f"-profiling_final_summary {str(bool(profiling_cfg.get('final_summary_enabled', True))).lower()}")
    if profiling_cfg.get("helpers"):
        control_lines.append(f"-profiling_helpers {','.join(profiling_cfg['helpers'])}")
    diagnostics_cfg = resolve_diagnostics_config(monitor_cfg)
    memory_log_cfg = diagnostics_cfg["runtime_memory_log"]
    control_lines.append(f"-runtime_memory_log_enabled {str(bool(memory_log_cfg.get('enabled', True))).lower()}")
 
    walltime_guard_policy = configs.get("walltime_guard_policy")
    if walltime_guard_policy is not None:
        control_lines.extend(
            [
                f"-walltime_guard_enabled {str(bool(walltime_guard_policy.get('enabled', False))).lower()}",
                f"-walltime_guard_warmup_steps {int(walltime_guard_policy.get('warmup_steps', DEFAULT_WALLTIME_GUARD_POLICY['warmup_steps']))}",
                f"-walltime_guard_multiplier {float(walltime_guard_policy.get('multiplier', DEFAULT_WALLTIME_GUARD_POLICY['multiplier']))}",
                f"-walltime_guard_min_seconds {float(walltime_guard_policy.get('min_seconds', DEFAULT_WALLTIME_GUARD_POLICY['min_seconds']))}",
                f"-walltime_guard_estimator_alpha {float(walltime_guard_policy.get('estimator_alpha', DEFAULT_WALLTIME_GUARD_POLICY['estimator_alpha']))}",
            ]
        )
    
    grid_cfg = case_cfg.get('grid', {})
    grid_mode = grid_cfg.get('mode')
    expected_nblk = int(case_cfg.get('models', {}).get('domain', {}).get('blocks', 1))
 
    if grid_mode == 'file':
        print("[INFO] Grid Mode: Using external file...")
        case_file_dir = os.path.dirname(configs['case_path'])
        nondim_grid_path = os.path.join(run_dir, "inputs", "grid", "grid.run")
        if os.path.isfile(nondim_grid_path):
            print(f"[INFO] Reusing locked grid asset: {os.path.relpath(nondim_grid_path)}")
            control_lines.append(f"-grid_file {nondim_grid_path}")
        else:
            source_grid = _resolve_case_relative_path(grid_cfg['source_file'], case_file_dir)
            grid_for_validation = source_grid
            try:
                summary = validate_and_nondimensionalize_picgrid(
                    grid_for_validation, nondim_grid_path, grid_length_scale, expected_nblk=expected_nblk
                )
                print(
                    f"[SUCCESS] Validated and non-dimensionalized grid: {os.path.relpath(nondim_grid_path)} "
                    f"(nblk={summary['nblk']}, total_nodes={summary['total_nodes']})"
                )
                control_lines.append(f"-grid_file {nondim_grid_path}")
            except Exception as e:
                print(f"[FATAL] Failed to process grid file '{source_grid}': {e}", file=sys.stderr)
                sys.exit(1)
    elif grid_mode == 'grid_gen':
        nondim_grid_path = os.path.join(run_dir, "inputs", "grid", "grid.run")
        if os.path.isfile(nondim_grid_path):
            print(f"[INFO] Grid Mode: grid.gen, reusing locked grid asset: {os.path.relpath(nondim_grid_path)}")
            control_lines.append(f"-grid_file {nondim_grid_path}")
        else:
            print("[INFO] Grid Mode: Generating external grid via grid.gen...")
            try:
                # grid.gen already converts ncells_* inputs into node-count PICGRID dims.
                generated_grid = run_grid_generator(
                    configs['case_path'], run_dir, grid_cfg, case_cfg=case_cfg)
                summary = validate_and_nondimensionalize_picgrid(
                    generated_grid, nondim_grid_path, grid_length_scale, expected_nblk=expected_nblk
                )
                print(
                    f"[SUCCESS] grid.gen output validated and non-dimensionalized: {os.path.relpath(nondim_grid_path)} "
                    f"(nblk={summary['nblk']}, total_nodes={summary['total_nodes']})"
                )
                control_lines.append(f"-grid_file {nondim_grid_path}")
            except Exception as e:
                print(f"[FATAL] Grid generation failed: {e}", file=sys.stderr)
                sys.exit(1)
    elif grid_mode == 'programmatic_c':
        print("[INFO] Grid Mode: Programmatic C...")
        grid_settings = translate_programmatic_grid_settings(grid_cfg.get('programmatic_settings', {}))
        control_lines.append("-grid")
        for p_key in GRID_DA_PROCESSOR_KEYS:
            grid_settings.pop(p_key, None)
        for key, value in grid_settings.items(): control_lines.append(f"-{key} {format_flag_value(value)}")
        if resolved_ic and is_generated_ic_provider(resolved_ic) and ic_is_authoritative:
            # The simulator builds this grid itself and never reads a file for it; this
            # bridge exists only so the Python IC generator (a separate process) can see
            # the same node coordinates. generate_picgrid_from_programmatic_settings uses
            # the identical formula as ComputeStretchedCoord in src/grid.c, so the two are
            # guaranteed to agree. Nothing above is changed: -grid_file is never emitted,
            # so the solver still builds its own grid exactly as before.
            nondim_grid_path = os.path.join(run_dir, "inputs", "grid", "grid.run")
            if not os.path.isfile(nondim_grid_path):
                try:
                    generate_picgrid_from_programmatic_settings(
                        grid_cfg.get('programmatic_settings', {}), nondim_grid_path,
                        input_reference_scale(("case", "grid", "programmatic_settings", "xMins"), fluid_scaling),
                    )
                    print(
                        "[SUCCESS] Materialized a bridge grid for the Python initial-condition "
                        f"provider: {os.path.relpath(nondim_grid_path)}"
                    )
                except Exception as e:
                    print(f"[FATAL] Failed to materialize bridge grid for initial-condition generator: {e}",
                          file=sys.stderr)
                    sys.exit(1)
    else:
        raise ValueError(f"Unknown or missing grid mode '{grid_mode}' in case.yml.")
 
    if resolved_ic and (resolved_ic["kind"] == "file" or is_generated_ic_provider(resolved_ic)):
        try:
            staged_ic = stage_initial_condition_file(run_dir, configs["case_path"], resolved_ic)
        except Exception as e:
            print(f"[FATAL] Failed to stage initial condition: {e}", file=sys.stderr)
            sys.exit(1)
        control_lines.extend([
            f"-ic_field {resolved_ic['field_code']}",
            f"-ic_dir {staged_ic['directory']}",
        ])
        print(f"  - Staged initial condition: {os.path.relpath(staged_ic['staged'])}")
 
    try:
        bcs_files = generate_multi_block_bcs(
            run_dir, run_id, case_cfg, source_files, config_dir=config_dir
        )
    except ValueError as e:
        print(f"[FATAL] Invalid boundary_conditions in case.yml: {e}", file=sys.stderr)
        sys.exit(1)
    control_lines.append(f"-bcs_files \"{','.join(bcs_files)}\"")
 
    configs["decomposition_resolved"] = append_grid_da_processor_layout(
        control_lines, grid_cfg, num_procs,
        block_dims=resolve_grid_node_dims(
            case_cfg, configs["case_path"], os.path.join(run_dir, "inputs", "grid", "grid.run")),
        solver_cfg=solver_cfg, any_periodic=case_declares_periodic_axis(case_cfg),
        explicit=configs.get("decomposition"), cluster_cfg=configs.get("cluster_cfg"))
    
    parse_and_add_model_flags(case_cfg, control_lines)
    append_les_diagnostics_flags(resolve_les_diagnostics(case_cfg, configs.get('monitor') or {}), control_lines)
    
    if 'solver_parameters' in case_cfg:
        params = case_cfg['solver_parameters']
        if params:
            for key, value in params.items():
                control_lines.append(f"{key} {format_flag_value(value)}")
 
    try:
        solver_flags = parse_solver_config(solver_cfg, resolve_reference_scales(case_cfg), case_cfg)
    except ValueError as e:
        print(f"[FATAL] Invalid solver.yml settings: {e}", file=sys.stderr)
        sys.exit(1)
    append_passthrough_flags(control_lines, solver_flags)
 
    try:
        solver_monitoring_flags = resolve_solver_monitoring_flags(monitor_cfg)
    except ValueError as e:
        print(f"[FATAL] Invalid monitor.yml solver_monitoring settings: {e}", file=sys.stderr)
        sys.exit(1)
    # Monitors for a solver that does not run would hand PETSc options nothing reads: the
    # momentum ones are Newton-Krylov's, and neither momentum nor Poisson solves when the
    # Eulerian field is loaded or analytical.
    solves_flow = solver_flags.get('-euler_field_source', '"solve"') == '"solve"'
    if not solves_flow:
        inactive = [flag for flag in (*SOLVER_MONITORING_MOMENTUM_FLAG_MAP.values(),
                                      *SOLVER_MONITORING_POISSON_FLAG_MAP.values())
                    if solver_monitoring_flags.pop(flag, None) is not None]
        if inactive:
            print("[INFO] monitor.yml solver_monitoring applies to solved flow only; not passed "
                  "with a loaded or analytical Eulerian field.")
    elif solver_flags.get('-mom_solver_type') != '"newton_krylov"':
        inactive = [flag for flag in SOLVER_MONITORING_MOMENTUM_FLAG_MAP.values()
                    if solver_monitoring_flags.pop(flag, None) is not None]
        if inactive:
            print("[INFO] monitor.yml solver_monitoring.momentum applies to Newton-Krylov only; "
                  "not passed to this momentum solver.")
    append_passthrough_flags(control_lines, solver_monitoring_flags)
    
    io_cfg = monitor_cfg.get('io', {})
    particle_console_output_freq = resolve_particle_console_output_frequency(io_cfg)
    if 'data_output_frequency' in io_cfg: control_lines.append(f"-tio {io_cfg['data_output_frequency']}")
    # The run's first and last states are checkpointed unless turned off; cadence and
    # signal checkpoints do not depend on these.
    for key in ('write_initial_checkpoint', 'write_final_checkpoint'):
        if key in io_cfg:
            control_lines.append(f"-{key} {str(bool(io_cfg[key])).lower()}")
    if particle_console_output_freq is not None:
        control_lines.append(f"-particle_console_output_freq {particle_console_output_freq}")
    statistics_console_output_freq = resolve_statistics_console_output_frequency(io_cfg)
    if statistics_console_output_freq is not None:
        control_lines.append(f"-statistics_console_output_freq {statistics_console_output_freq}")
    if 'particle_log_interval' in io_cfg: control_lines.append(f"-logfreq {io_cfg['particle_log_interval']}")
    traced = resolve_traced_particle_ids(monitor_cfg)
    if traced:
        control_lines.append(f"-picurv_trace_particles {','.join(str(pid) for pid in traced)}")
    if restart_source_dir:
        expected_restart = os.path.abspath(
            os.path.join(run_dir, CANONICAL_RUN_PATHS["restart"])
        )
        if os.path.abspath(restart_source_dir) != expected_restart:
            raise ValueError(
                "Restart data was not materialized in the canonical run input: "
                f"expected {expected_restart}, got {restart_source_dir}."
            )
    if continue_mode:
        control_lines.append("-continue_mode true")
    elif str(configs.get("statistics_state", "reset")).lower() == "carry":
        control_lines.append("-field_statistics_continue true")
 
    # Emitted last, and always: PETSc takes the final occurrence of an option, so a
    # validated directory written here wins over anything earlier in the file. Writing
    # them unconditionally also removes the "omitted default" gap, where an absent flag
    # let an environment variable or PETSc configuration choose the directory instead.
    control_lines.append("")
    control_lines.append("# Canonical run-owned directories are fixed by the workspace contract.")
    control_lines.append(f"-output_dir {CANONICAL_RUN_PATHS['output']}")
    control_lines.append(f"-restart_dir {CANONICAL_RUN_PATHS['restart']}")
    control_lines.append(f"-log_dir {CANONICAL_RUN_PATHS['logs']}")
    control_lines.append(f"-analysis_dir {CANONICAL_RUN_PATHS['metrics']}")
 
    final_content = generate_header(run_id, source_files) + "\n".join(control_lines)
    config_dir = config_dir or os.path.join(run_dir, "config")
    os.makedirs(config_dir, exist_ok=True)
    control_file_path = os.path.join(config_dir, f"{run_id}.control")
    with open(control_file_path, "w") as f: f.write(final_content)
    print(f"[SUCCESS] Generated solver control file: {os.path.relpath(control_file_path)}")
    return os.path.abspath(control_file_path)
 
def resolve_post_decomposition(run_dir: str, num_procs: int, explicit=None,
                               cluster_cfg: "dict | None" = None) -> dict:
    """!
    @brief Resolve the postprocessor's MPI decomposition from the run's staged configuration.
    @details The postprocessor builds the same grid hierarchy as the solve, from the run's
             active case and solver files and its staged grid, so its decomposition is
             resolved like the solve's, for its own rank count.
    @param[in] run_dir Run directory.
    @param[in] num_procs MPI ranks of the post-processing stage.
    @param[in] explicit (ni, nj, nk) from the command line, or None.
    @param[in] cluster_cfg Parsed cluster.yml, or None.
    @return The resolved decomposition (resolve_decomposition()).
    """
    active = load_active_run_configuration(run_dir)
    case_cfg = read_yaml_file(active["case"]) if active.get("case") and os.path.isfile(active["case"]) else {}
    solver_cfg = read_yaml_file(active["solver"]) if active.get("solver") and os.path.isfile(active["solver"]) else {}
    block_dims = resolve_grid_node_dims(case_cfg, active.get("case") or os.path.join(run_dir, "config", "case.yml"),
                                        os.path.join(run_dir, "inputs", "grid", "grid.run"))
    return resolve_decomposition(num_procs, case_cfg.get("grid") or {}, block_dims, solver_cfg,
                                 case_declares_periodic_axis(case_cfg), explicit, cluster_cfg)
 
 
def generate_post_recipe_file(run_dir: str, run_id: str, post_cfg: dict, source_files: dict, monitor_cfg=None,
                              decomposition: "dict | None" = None) -> str:
    """!
    @brief Generates a key=value config file (post.run) for the C post-processor.
    @details Translates the structured post-processing YAML into the specific flat
             key-value format required by the C executable, including complex,
             semicolon-separated pipeline strings.
    @param[in] run_dir The path to the main run directory.
    @param[in] run_id The unique identifier for the run.
    @param[in] post_cfg The parsed post-profile YAML configuration dictionary.
    @param[in] source_files A dictionary of source files for the header.
    @param[in] monitor_cfg Optional parsed monitor YAML configuration dictionary.
    @param[in] decomposition The postprocessor's resolved decomposition (resolve_post_decomposition()),
               or None to let PETSc decide.
    @return The absolute path to the generated post.run recipe file.
    """
    print("[INFO] Generating post-processor recipe file (post.run)...")
    if not isinstance((post_cfg or {}).get("_picurv_paths"), dict):
        post_cfg, _ = apply_canonical_post_paths(post_cfg, run_dir)
    config_dir = get_post_recipe_root(run_dir, post_cfg)
    os.makedirs(config_dir, exist_ok=True)
    post_recipe_path = os.path.join(config_dir, "post.run")
 
    lines = [generate_header(run_id, source_files)]
    c_config = build_post_recipe_config(post_cfg, monitor_cfg)
 
    for key, value in c_config.items():
        if value is not None and str(value) != "":
            lines.append(f"{key} = {value}")
    # The steps themselves are decided when the job starts (prepare_post_job()).
    lines.append(f"step_list_file = {get_post_step_list_path(run_dir, post_cfg)}")
    if decomposition and decomposition.get("layout") and decomposition["layout"] != (1, 1, 1):
        lines.append("da_processors = " + " ".join(str(v) for v in decomposition["layout"]))
 
    with open(post_recipe_path, "w") as f:
        f.write("\n".join(lines))
    print(f"[SUCCESS] Generated post-processor recipe: {os.path.relpath(post_recipe_path)}")
    return os.path.abspath(post_recipe_path)
 
def execute_command(command: list, run_dir: str, log_filename: str, monitor_cfg: dict = None):
    """!
    @brief Executes a command, streaming its output to the console and a log file.
    @details ...
    If None, the process inherits the parent's environment directly.
    @param[in] command Argument passed to `execute_command()`.
    @param[in] run_dir Argument passed to `execute_command()`.
    @param[in] log_filename Argument passed to `execute_command()`.
    @param[in] monitor_cfg Argument passed to `execute_command()`.
    """
    log_path = resolve_command_log_path(run_dir, log_filename)
    os.makedirs(os.path.dirname(log_path), exist_ok=True)
 
    print(f"[INFO] Launching Command...\n  > {format_command_for_display(command)}")
    print(f"       Log file: {os.path.relpath(log_path)}")
    print("-" * 60)
 
    # --- Environment Handling ---
    popen_kwargs = {
        "stdout": subprocess.PIPE, "stderr": subprocess.STDOUT,
        "cwd": run_dir, "bufsize": 1, "universal_newlines": True,
        "encoding": 'utf-8', "errors": 'replace'
    }
 
    run_env = os.environ.copy()
    if monitor_cfg:
        verbosity = monitor_cfg.get('logging', {}).get('verbosity', 'INFO').upper()
        run_env['LOG_LEVEL'] = verbosity
        print(f"[INFO] Log level: {verbosity}")
    # The launched executable's own PETSc first, as job scripts do (petsc_library_path_lines()).
    for token in command:
        library_dir = executable_petsc_library_dir(str(token)) if os.path.isabs(str(token)) else None
        if library_dir:
            run_env["LD_LIBRARY_PATH"] = library_dir + (":" + run_env["LD_LIBRARY_PATH"]
                                                        if run_env.get("LD_LIBRARY_PATH") else "")
            break
    popen_kwargs['env'] = run_env
 
    print("-" * 60)
    try:
        # Pass the constructed keyword arguments dictionary to Popen
        process = subprocess.Popen(command, **popen_kwargs)
 
        with open(log_path, "w") as log_file:
            for line in process.stdout:
                sys.stdout.write(line)
                log_file.write(line)
        process.wait()
        return_code = process.returncode
        print("-" * 60)
        if return_code == 0:
            print(f"[SUCCESS] Execution finished successfully.")
        else:
            print(f"[FATAL] Execution failed with exit code {return_code}. Check log: {os.path.relpath(log_path)}", file=sys.stderr)
            sys.exit(return_code)
    except FileNotFoundError:
        print(f"[FATAL] Command not found or is not executable: '{command[0]}'", file=sys.stderr)
        print("        Please check that the path is correct and the file has execute permissions.", file=sys.stderr)
        sys.exit(1)
    except Exception as e:
        print(f"[FATAL] An unexpected error occurred during execution: {e}", file=sys.stderr)
        sys.exit(1)
 
 
def format_command_for_display(command: list) -> str:
    """!
    @brief Render a shell-safe command string for console and log output.
    @param[in] command Argument passed to `format_command_for_display()`.
    @return Value returned by `format_command_for_display()`.
    """
    return " ".join(shlex.quote(str(part)) for part in command)
 
 
def resolve_command_log_path(run_dir: str, log_filename: str) -> str:
    """!
    @brief Resolve a command log filename relative to the run directory.
    @param[in] run_dir Argument passed to `resolve_command_log_path()`.
    @param[in] log_filename Argument passed to `resolve_command_log_path()`.
    @return Value returned by `resolve_command_log_path()`.
    """
    if os.path.dirname(log_filename):
        return os.path.join(run_dir, log_filename)
    return os.path.join(run_dir, "logs", log_filename)
 
 
class CommandExecutionError(RuntimeError):
    """!
    @brief Raised when an external command exits unsuccessfully.
    """
 
    def __init__(self, command: list, returncode: int, details: str = None):
        """!
        @brief Initialize a command execution error.
        @param[in] command Argument passed to `__init__()`.
        @param[in] returncode Argument passed to `__init__()`.
        @param[in] details Argument passed to `__init__()`.
        """
        self.command = command
        self.returncode = returncode
        self.details = details
        detail_suffix = f": {details}" if details else ""
        super().__init__(
            f"Command failed with exit code {returncode}: {format_command_for_display(command)}{detail_suffix}"
        )
 
 
class PlotDependencyError(RuntimeError):
    """!
    @brief Raised when plot.gen reports a missing optional dependency.
    """
 
 
def _run_captured_command(command: list, run_dir: str) -> subprocess.CompletedProcess:
    """!
    @brief Run a command and capture combined stdout/stderr details for later inspection.
    @param[in] command Argument passed to `_run_captured_command()`.
    @param[in] run_dir Argument passed to `_run_captured_command()`.
    @return Value returned by `_run_captured_command()`.
    """
    try:
        return subprocess.run(
            command,
            cwd=run_dir,
            text=True,
            capture_output=True,
            check=False,
            encoding="utf-8",
            errors="replace",
        )
    except FileNotFoundError as exc:
        raise CommandExecutionError(command, 1, f"Command not found or is not executable: '{command[0]}'") from exc
 
 
def _require_successful_command(command: list, result: subprocess.CompletedProcess):
    """!
    @brief Raise `CommandExecutionError` when a captured command failed.
    @param[in] command Argument passed to `_require_successful_command()`.
    @param[in] result Argument passed to `_require_successful_command()`.
    """
    if result.returncode == 0:
        return
    details = (result.stderr or result.stdout).strip()
    raise CommandExecutionError(command, result.returncode, details or None)
 
 
def _capture_command_stdout(command: list, run_dir: str) -> str:
    """!
    @brief Run a command, require success, and return stripped stdout text.
    @param[in] command Argument passed to `_capture_command_stdout()`.
    @param[in] run_dir Argument passed to `_capture_command_stdout()`.
    @return Value returned by `_capture_command_stdout()`.
    """
    result = _run_captured_command(command, run_dir)
    _require_successful_command(command, result)
    return result.stdout.strip()
 
 
def _stream_command_to_console_and_log(command: list, run_dir: str, log_file):
    """!
    @brief Stream command output to stdout and an already-open log file.
    @param[in] command Argument passed to `_stream_command_to_console_and_log()`.
    @param[in] run_dir Argument passed to `_stream_command_to_console_and_log()`.
    @param[in] log_file Argument passed to `_stream_command_to_console_and_log()`.
    """
    display = format_command_for_display(command)
    print(f"[INFO] Running: {display}")
    log_file.write(f"$ {display}\n")
    log_file.flush()
 
    popen_kwargs = {
        "stdout": subprocess.PIPE,
        "stderr": subprocess.STDOUT,
        "cwd": run_dir,
        "bufsize": 1,
        "universal_newlines": True,
        "encoding": "utf-8",
        "errors": "replace",
    }
 
    try:
        process = subprocess.Popen(command, **popen_kwargs)
    except FileNotFoundError as exc:
        raise CommandExecutionError(command, 1, f"Command not found or is not executable: '{command[0]}'") from exc
 
    with process:
        for line in process.stdout:
            sys.stdout.write(line)
            log_file.write(line)
    return_code = process.wait()
    log_file.write("\n")
    log_file.flush()
    if return_code != 0:
        raise CommandExecutionError(command, return_code)
 
 
def _get_git_head_state(run_dir: str) -> dict:
    """!
    @brief Capture the current git HEAD branch name and commit hash.
    @param[in] run_dir Argument passed to `_get_git_head_state()`.
    @return Value returned by `_get_git_head_state()`.
    """
    head_commit = _capture_command_stdout(["git", "rev-parse", "--verify", "HEAD"], run_dir)
    branch_result = _run_captured_command(["git", "symbolic-ref", "--quiet", "--short", "HEAD"], run_dir)
    branch_name = branch_result.stdout.strip() if branch_result.returncode == 0 else None
    return {"branch": branch_name, "commit": head_commit}
 
 
def _get_local_branches_with_upstreams(run_dir: str) -> "list[tuple[str, str | None]]":
    """!
    @brief Return local branch names plus their configured upstreams.
    @param[in] run_dir Argument passed to `_get_local_branches_with_upstreams()`.
    @return Value returned by `_get_local_branches_with_upstreams()`.
    """
    output = _capture_command_stdout(
        ["git", "for-each-ref", "--sort=refname", "--format=%(refname:short)\t%(upstream:short)", "refs/heads"],
        run_dir,
    )
    branches = []
    for line in output.splitlines():
        if not line.strip():
            continue
        branch_name, _, upstream_name = line.partition("\t")
        branches.append((branch_name, upstream_name or None))
    return branches
 
 
def _working_tree_has_tracked_changes(run_dir: str) -> bool:
    """!
    @brief Return `True` when the repository has staged or unstaged tracked changes.
    @param[in] run_dir Argument passed to `_working_tree_has_tracked_changes()`.
    @return Value returned by `_working_tree_has_tracked_changes()`.
    """
    command = ["git", "status", "--porcelain", "--untracked-files=no"]
    result = _run_captured_command(command, run_dir)
    _require_successful_command(command, result)
    return bool(result.stdout.strip())
 
 
def _attempt_pull_cleanup(run_dir: str, rebase: bool, log_file):
    """!
    @brief Best-effort cleanup after a failed `git pull` so the original branch can be restored.
    @param[in] run_dir Argument passed to `_attempt_pull_cleanup()`.
    @param[in] rebase Argument passed to `_attempt_pull_cleanup()`.
    @param[in] log_file Argument passed to `_attempt_pull_cleanup()`.
    """
    cleanup_command = ["git", "rebase", "--abort"] if rebase else ["git", "merge", "--abort"]
    result = _run_captured_command(cleanup_command, run_dir)
    if result.returncode == 0:
        print(f"[INFO] Cleaned up the interrupted {'rebase' if rebase else 'merge'} state.")
        log_file.write(f"$ {format_command_for_display(cleanup_command)}\n")
        if result.stdout:
            sys.stdout.write(result.stdout)
            log_file.write(result.stdout)
        if result.stderr:
            sys.stderr.write(result.stderr)
            log_file.write(result.stderr)
        log_file.write("\n")
        log_file.flush()
        return
 
    details = (result.stderr or result.stdout).strip()
    if details:
        message = (
            f"[WARNING] Could not clean up a failed {'rebase' if rebase else 'merge'} automatically: {details}"
        )
        print(message, file=sys.stderr)
        log_file.write(message + "\n")
        log_file.flush()
 
 
def _restore_git_head(run_dir: str, original_head: dict, log_file):
    """!
    @brief Restore the repository back to the branch or detached commit it started on.
    @param[in] run_dir Argument passed to `_restore_git_head()`.
    @param[in] original_head Argument passed to `_restore_git_head()`.
    @param[in] log_file Argument passed to `_restore_git_head()`.
    """
    current_state = _get_git_head_state(run_dir)
    if original_head["branch"]:
        if current_state["branch"] == original_head["branch"]:
            return
        _stream_command_to_console_and_log(["git", "checkout", original_head["branch"]], run_dir, log_file)
        return
 
    if current_state["branch"] is None and current_state["commit"] == original_head["commit"]:
        return
    _stream_command_to_console_and_log(["git", "checkout", "--detach", original_head["commit"]], run_dir, log_file)
 
 
def _refuse_detached_source_checkout(source_project_root: str, action: str) -> None:
    """!
    @brief Refuse a branch pull when the source checkout is pinned to a detached commit.
 
    @details `versions install` and `versions activate` leave the checkout detached on
             the version they built. A branch pull there either fails inside Git or, in
             the multi-branch path, updates the branches and then restores the detached
             commit, so the active code never changes while the command reports success.
             A directory that is not a Git checkout is left for the Git command to report.
    @param[in] source_project_root PICurv source checkout to inspect.
    @param[in] action User-facing command name.
    @throws ValueError when HEAD is detached.
    """
    branch = _run_captured_command(["git", "symbolic-ref", "--quiet", "--short", "HEAD"], source_project_root)
    if branch.returncode == 0:
        return
    commit = _run_captured_command(["git", "rev-parse", "--short=12", "--verify", "HEAD"], source_project_root)
    if commit.returncode != 0:
        return
    raise ValueError(
        f"{action}: the source checkout at {source_project_root} is pinned to commit "
        f"{commit.stdout.strip()}, not a branch, so a branch pull would not change the code "
        "that runs.\n"
        "        Install a newer version with 'picurv versions install <tag-or-commit>', "
        "or check out a branch (for example 'git checkout main') to follow it."
    )
 
 
def pull_all_source_branches(run_dir: str, log_filename: str, rebase: bool = True):
    """!
    @brief Refresh every local tracking branch in the source repository, then restore the starting branch.
    @param[in] run_dir Argument passed to `pull_all_source_branches()`.
    @param[in] log_filename Argument passed to `pull_all_source_branches()`.
    @param[in] rebase Argument passed to `pull_all_source_branches()`.
    """
    log_path = resolve_command_log_path(run_dir, log_filename)
    os.makedirs(os.path.dirname(log_path), exist_ok=True)
 
    print("\n" + "="*23 + " PULL SOURCE STAGE " + "="*22)
    print("[INFO] Refreshing all local source branches that track an upstream.")
    print(f"       Log file: {os.path.relpath(log_path)}")
    print("-" * 60)
 
    try:
        original_head = _get_git_head_state(run_dir)
        if _working_tree_has_tracked_changes(run_dir):
            raise RuntimeError(
                "Multi-branch pull requires a clean tracked working tree in the source repository. "
                "Commit or stash those changes first, or rerun with --current-branch-only."
            )
        branches = _get_local_branches_with_upstreams(run_dir)
    except (CommandExecutionError, RuntimeError) as exc:
        print(f"[FATAL] {exc}", file=sys.stderr)
        sys.exit(getattr(exc, "returncode", 1))
 
    if not branches:
        print("[FATAL] No local branches were found in the source repository.", file=sys.stderr)
        sys.exit(1)
 
    if original_head["branch"]:
        branches = [item for item in branches if item[0] != original_head["branch"]] + [
            item for item in branches if item[0] == original_head["branch"]
        ]
 
    skipped_branches = []
    current_operation = None
    pull_error = None
    restore_error = None
 
    with open(log_path, "w", encoding="utf-8") as log_file:
        log_file.write(f"# PICurv pull-source all-branch sync\n")
        log_file.write(f"# repository: {os.path.abspath(run_dir)}\n")
        log_file.write(f"# started: {datetime.now().isoformat()}\n")
        log_file.write(
            f"# original head: {original_head['branch'] if original_head['branch'] else original_head['commit']}\n\n"
        )
 
        try:
            for branch_name, upstream_name in branches:
                if not upstream_name:
                    warning = f"[WARNING] Skipping branch '{branch_name}' because it has no configured upstream."
                    print(warning, file=sys.stderr)
                    log_file.write(warning + "\n")
                    skipped_branches.append(branch_name)
                    continue
 
                print(f"[INFO] Refreshing branch '{branch_name}' from '{upstream_name}'.")
                log_file.write(f"[INFO] Refreshing branch '{branch_name}' from '{upstream_name}'.\n")
 
                current_operation = f"checkout:{branch_name}"
                _stream_command_to_console_and_log(["git", "checkout", branch_name], run_dir, log_file)
 
                pull_command = ["git", "pull"]
                if rebase:
                    pull_command.append("--rebase")
                current_operation = f"pull:{branch_name}"
                _stream_command_to_console_and_log(pull_command, run_dir, log_file)
                current_operation = None
        except CommandExecutionError as exc:
            pull_error = exc
            if current_operation and current_operation.startswith("pull:"):
                _attempt_pull_cleanup(run_dir, rebase, log_file)
        finally:
            try:
                _restore_git_head(run_dir, original_head, log_file)
            except CommandExecutionError as exc:
                restore_error = exc
 
    print("-" * 60)
    if pull_error:
        if restore_error:
            print(
                f"[FATAL] Multi-branch pull failed and the original branch could not be restored. "
                f"Check log: {os.path.relpath(log_path)}",
                file=sys.stderr,
            )
            sys.exit(restore_error.returncode)
        print(
            f"[FATAL] Multi-branch pull failed. Original branch restored. "
            f"Check log: {os.path.relpath(log_path)}",
            file=sys.stderr,
        )
        sys.exit(pull_error.returncode)
 
    if restore_error:
        print(
            f"[FATAL] Branch updates completed, but the original branch could not be restored. "
            f"Check log: {os.path.relpath(log_path)}",
            file=sys.stderr,
        )
        sys.exit(restore_error.returncode)
 
    if skipped_branches:
        print(f"[WARNING] Skipped branches with no upstream: {', '.join(skipped_branches)}", file=sys.stderr)
    print("[SUCCESS] All local tracking branches are up to date.")
 
def auto_identify_run_inputs(config_dir: str):
    """!
    @brief Auto-detect case.yml, monitor.yml, and *.control in a run config directory.
    @param[in] config_dir Argument passed to `auto_identify_run_inputs()`.
    @return Value returned by `auto_identify_run_inputs()`.
    """
    run_dir = os.path.dirname(os.path.abspath(config_dir))
    active = load_active_run_configuration(run_dir)
    if active:
        case_path = active.get("case")
        monitor_path = active.get("monitor")
        solver_control_path = active.get("control")
        if all(path and os.path.isfile(path) for path in (case_path, monitor_path, solver_control_path)):
            return case_path, monitor_path, solver_control_path
    all_yml_files = glob.glob(os.path.join(config_dir, "*.yml"))
    case_path, monitor_path = None, None
    for f_path in all_yml_files:
        try:
            content = read_yaml_file(f_path)
            if not isinstance(content, dict):
                continue
            if 'models' in content and 'boundary_conditions' in content:
                case_path = f_path
            elif 'io' in content and 'logging' in content:
                monitor_path = f_path
        except Exception as e:
            print(f"[WARNING] Could not parse or inspect '{f_path}': {e}", file=sys.stderr)
    try:
        solver_control_path = glob.glob(os.path.join(config_dir, "*.control"))[0]
    except IndexError:
        solver_control_path = None
    return case_path, monitor_path, solver_control_path
 
def resolve_post_source_directory(run_dir: str, monitor_cfg: dict, post_cfg: dict, strict: bool = True) -> str:
    """!
    @brief Resolve post source directory token and optionally enforce existence.
    @param[in] run_dir Argument passed to `resolve_post_source_directory()`.
    @param[in] monitor_cfg Argument passed to `resolve_post_source_directory()`.
    @param[in] post_cfg Argument passed to `resolve_post_source_directory()`.
    @param[in] strict Argument passed to `resolve_post_source_directory()`.
    @return Value returned by `resolve_post_source_directory()`.
    """
    solver_output_dir_abs = os.path.join(run_dir, CANONICAL_RUN_PATHS["output"])
    source_dir_template = get_post_source_directory_template(post_cfg)
    if source_dir_template == '<solver_output_dir>':
        resolved_source_dir = solver_output_dir_abs
        print(f"[INFO] Post-processor source data: {os.path.relpath(resolved_source_dir)}")
    else:
        resolved_source_dir = os.path.abspath(os.path.join(run_dir, source_dir_template))
        print(f"[INFO] Post-processor source data (user-defined): {os.path.relpath(resolved_source_dir)}")
 
    if strict and (not os.path.isdir(resolved_source_dir) or not os.listdir(resolved_source_dir)):
        print(
            f"[FATAL] Source data directory for post-processing not found or empty: {os.path.relpath(resolved_source_dir)}",
            file=sys.stderr
        )
        sys.exit(1)
    if not strict and (not os.path.isdir(resolved_source_dir) or not os.listdir(resolved_source_dir)):
        print("[WARNING] Source data directory is not available yet; keeping deferred path for scheduled post job.")
    return resolved_source_dir
 
def render_slurm_array_stage_script(
    script_path: str,
    job_name: str,
    cluster_cfg: dict,
    array_spec: str,
    case_index_tsv: str,
    stage: str,
    solver_exe: str,
    post_exe: str,
    stdout_path: str,
    stderr_path: str,
    expected_version_line: "str | None" = None,
):
    """!
    @brief Render array script that maps SLURM_ARRAY_TASK_ID to per-case run artifacts.
    @param[in] script_path Argument passed to `render_slurm_array_stage_script()`.
    @param[in] job_name Argument passed to `render_slurm_array_stage_script()`.
    @param[in] cluster_cfg Argument passed to `render_slurm_array_stage_script()`.
    @param[in] array_spec Argument passed to `render_slurm_array_stage_script()`.
    @param[in] case_index_tsv Argument passed to `render_slurm_array_stage_script()`.
    @param[in] stage Argument passed to `render_slurm_array_stage_script()`.
    @param[in] solver_exe Argument passed to `render_slurm_array_stage_script()`.
    @param[in] post_exe Argument passed to `render_slurm_array_stage_script()`.
    @param[in] stdout_path Argument passed to `render_slurm_array_stage_script()`.
    @param[in] stderr_path Argument passed to `render_slurm_array_stage_script()`.
    @param[in] expected_version_line `--version` output the stage's executable reported
                                     at staging; checked before launch in every task.
    @return Value returned by `render_slurm_array_stage_script()`.
    """
    effective_cluster_cfg = cluster_cfg
    resources = effective_cluster_cfg.get("resources", {})
    notifications = effective_cluster_cfg.get("notifications", {}) or {}
    execution = effective_cluster_cfg.get("execution", {}) or {}
    module_setup = execution.get("module_setup", []) or []
    extra_sbatch = execution.get("extra_sbatch")
 
    lines = [
        "#!/bin/bash",
        f"#SBATCH --job-name={job_name}",
        f"#SBATCH --nodes={resources['nodes']}",
        f"#SBATCH --ntasks-per-node={resources['ntasks_per_node']}",
        f"#SBATCH --mem={resources['mem']}",
        f"#SBATCH --time={resources['time']}",
        f"#SBATCH --output={stdout_path}",
        f"#SBATCH --error={stderr_path}",
        f"#SBATCH --account={resources['account']}",
        f"#SBATCH --array={array_spec}",
    ]
    partition = resources.get("partition")
    if partition:
        lines.append(f"#SBATCH --partition={partition}")
    mail_user = notifications.get("mail_user")
    mail_type = notifications.get("mail_type")
    if mail_user:
        lines.append(f"#SBATCH --mail-user={mail_user}")
    if mail_type:
        lines.append(f"#SBATCH --mail-type={mail_type}")
    if isinstance(extra_sbatch, dict):
        for key, value in extra_sbatch.items():
            flag = str(key)
            if not flag.startswith("--"):
                flag = f"--{flag}"
            if isinstance(value, bool):
                if value:
                    lines.append(f"#SBATCH {flag}")
            elif value is not None:
                lines.append(f"#SBATCH {flag}={value}")
    elif isinstance(extra_sbatch, list):
        for token in extra_sbatch:
            lines.append(f"#SBATCH {token}")
 
    lines.extend([
        "",
        "set -euo pipefail",
        "",
        f'CASE_INDEX_FILE={shlex.quote(case_index_tsv)}',
        'LINE=$(sed -n "$((SLURM_ARRAY_TASK_ID + 1))p" "$CASE_INDEX_FILE")',
        'if [ -z "$LINE" ]; then',
        '  echo "No case entry for array index ${SLURM_ARRAY_TASK_ID}" >&2',
        '  exit 1',
        "fi",
        "IFS=$'\\t' read -r CASE_INDEX CASE_ID RUN_DIR CONTROL_FILE POST_RECIPE_FILE LOG_LEVEL POST_PREFIX SOLVE_DIAGNOSTIC_ARGS POST_DIAGNOSTIC_ARGS <<< \"$LINE\"",
        'cd "$RUN_DIR"',
        'echo "[$(date)] Starting case ${CASE_ID} (array index ${SLURM_ARRAY_TASK_ID})"',
    ])
 
    if stage == "solve":
        walltime_guard_exports = build_walltime_guard_exports(effective_cluster_cfg)
        for key, value in walltime_guard_exports.items():
            lines.append(f"export {key}={value}")
 
    lines.append('export LOG_LEVEL="${LOG_LEVEL}"')
 
    for setup_line in module_setup:
        lines.append(str(setup_line))
 
    stage_exe = solver_exe if stage == "solve" else post_exe
    # A pinned `$RUN_DIR/...` copy is the installation's binary, so its PETSc is the installation's.
    lines.extend(petsc_library_path_lines(executable_petsc_library_dir(
        stage_exe if not stage_exe.startswith("$") else
        resolve_runtime_executable("simulator" if stage == "solve" else "postprocessor"))))
    lines.extend(executable_identity_check_lines(
        stage_exe, expected_version_line, pinned=stage_exe.startswith("$RUN_DIR/")
    ))
 
    if stage == "solve":
        cmd = build_cluster_launch_command(
            effective_cluster_cfg,
            solver_exe,
            ["-control_file", "$CONTROL_FILE"]
        )
    else:
        cmd = build_cluster_launch_command(
            effective_cluster_cfg,
            post_exe,
            ["-control_file", "$CONTROL_FILE", "-postprocessing_config_file", "$POST_RECIPE_FILE"],
            force_num_procs=get_cluster_total_tasks(effective_cluster_cfg),
        )
 
    # Keep shell variables unresolved inside sbatch script.
    def _token(tok: str) -> str:
        """!
        @brief Preserve shell-variable tokens while safely quoting literal command arguments for an sbatch script.
        @param[in] tok Argument passed to `_token()`.
        @return Value returned by `_token()`.
        """
        if tok.startswith("$"):
            return tok
        return shlex.quote(str(tok))
 
    diag_var = "${SOLVE_DIAGNOSTIC_ARGS}" if stage == "solve" else "${POST_DIAGNOSTIC_ARGS}"
    command_text = " ".join(_token(t) for t in cmd)
    executable_token = _token(solver_exe if stage == "solve" else post_exe)
    # Diagnostic args must be executable args, not launcher args. Insert them
    # immediately before the executable's normal control/recipe options.
    if executable_token and command_text.count(executable_token) == 1:
        command_text = command_text.replace(f"{executable_token} ", f"{executable_token} {diag_var} ", 1)
    if stage == "post":
        # A member's post runs under the same lock wrapper as a standalone run, which
        # plans the steps as the task starts, so a continued study skips every member
        # step whose output is up to date.
        lock_paths = get_post_lock_paths("$RUN_DIR")
        lines.append(
            f"{shlex.quote(sys.executable)} \"{lock_paths['wrapper_path']}\" "
            f"--lock-file \"{lock_paths['lock_file']}\" "
            f"--metadata-file \"{lock_paths['metadata_file']}\" "
            f"--run-dir \"$RUN_DIR\" --post-recipe \"$RUN_DIR/config/post.yml\" "
            f"--postprocessor {executable_token} -- {command_text}"
        )
        # Study members are ordinary root runs, but their post recipes may request the
        # same run-local physical-time PVD product and reducers as standalone runs.
        # Keep this serial and downstream of the MPI postprocessor.
        lines.append(
            f"{shlex.quote(sys.executable)} -c {shlex.quote(_post_finalize_python_source())} "
            '"$RUN_DIR" "$RUN_DIR/config/post.yml" reducers'
        )
    else:
        lines.append(f"exec {command_text}")
 
    os.makedirs(os.path.dirname(script_path), exist_ok=True)
    with open(script_path, "w") as f:
        f.write("\n".join(lines) + "\n")
    os.chmod(script_path, 0o755)
 
 
def render_metrics_aggregate_script(
    script_path: str,
    job_name: str,
    cluster_cfg: dict,
    study_dir: str,
    picurv_path: str,
):
    """!
    @brief Generate a single-node sbatch script that runs metrics aggregation.
    @param[in] script_path Path to write the sbatch script.
    @param[in] job_name Slurm job name.
    @param[in] cluster_cfg Parsed cluster YAML dictionary.
    @param[in] study_dir Absolute path to the study directory.
    @param[in] picurv_path Absolute path to the picurv script.
    """
    resources = cluster_cfg.get("resources", {})
    notifications = cluster_cfg.get("notifications", {}) or {}
    execution = cluster_cfg.get("execution", {}) or {}
    module_setup = execution.get("module_setup", []) or []
 
    scheduler_dir = os.path.join(study_dir, "scheduler")
    lines = [
        "#!/bin/bash",
        f"#SBATCH --job-name={job_name}",
        "#SBATCH --nodes=1",
        "#SBATCH --ntasks-per-node=1",
        "#SBATCH --mem=4G",
        "#SBATCH --time=00:10:00",
        f"#SBATCH --output={os.path.join(scheduler_dir, 'metrics_%j.out')}",
        f"#SBATCH --error={os.path.join(scheduler_dir, 'metrics_%j.err')}",
        f"#SBATCH --account={resources['account']}",
    ]
    partition = resources.get("partition")
    if partition:
        lines.append(f"#SBATCH --partition={partition}")
    mail_user = notifications.get("mail_user")
    mail_type = notifications.get("mail_type")
    if mail_user:
        lines.append(f"#SBATCH --mail-user={mail_user}")
    if mail_type:
        lines.append(f"#SBATCH --mail-type={mail_type}")
 
    lines.extend([
        "",
        "set -euo pipefail",
        'echo "[$(date)] Running metrics aggregation"',
        "",
    ])
    for setup_line in module_setup:
        lines.append(str(setup_line))
 
    lines.append(
        f"exec {shlex.quote(picurv_path)} sweep --reaggregate"
        f" --study-dir {shlex.quote(study_dir)}"
    )
 
    os.makedirs(os.path.dirname(script_path), exist_ok=True)
    with open(script_path, "w") as f:
        f.write("\n".join(lines) + "\n")
    os.chmod(script_path, 0o755)
 
 
def reduce_metric_values(values, reduction: str):
    """!
    @brief Reduce a metric series to one scalar according to the requested reducer.
    @param[in] values Sequence of numeric values.
    @param[in] reduction Reduction keyword.
    @return Value returned by `reduce_metric_values()`.
    """
    if not values:
        return None
    np = require_numpy()
    reduction = str(reduction).lower()
    if reduction == "mean":
        return float(np.mean(values))
    if reduction == "min":
        return float(np.min(values))
    if reduction == "max":
        return float(np.max(values))
    if reduction == "p95":
        return float(np.percentile(values, 95.0))
    return float(values[-1])
 
 
def extract_metric_from_csv(case_dir: str, spec: dict):
    """!
    @brief Extract a scalar metric from a CSV source.
    @param[in] case_dir Argument passed to `extract_metric_from_csv()`.
    @param[in] spec Argument passed to `extract_metric_from_csv()`.
    @return Value returned by `extract_metric_from_csv()`.
    """
    file_glob = spec.get("file_glob", "**/*_msd.csv")
    candidates = sorted(glob.glob(os.path.join(case_dir, file_glob), recursive=True))
    if not candidates:
        return None
    csv_path = candidates[0]
    rows = []
    with open(csv_path, "r", newline="") as f:
        reader = csv.DictReader(f)
        if reader.fieldnames:
            for row in reader:
                rows.append(row)
            if not rows:
                return None
            column = spec.get("column")
            numerator_column = spec.get("numerator_column")
            denominator_column = spec.get("denominator_column")
            denominator_floor = float(spec.get("denominator_floor", 0.0) or 0.0)
            if not column and not numerator_column:
                for name in reversed(reader.fieldnames):
                    if name and name.lower() not in {"step", "time", "timestep", "physical_time"}:
                        column = name
                        break
            if not column and not numerator_column:
                return None
            values = []
            for row in rows:
                try:
                    if numerator_column:
                        numerator = float(row[numerator_column])
                        denominator = float(row[denominator_column])
                        denominator = max(denominator_floor, denominator)
                        if denominator == 0.0:
                            continue
                        values.append(numerator / denominator)
                    else:
                        values.append(float(row[column]))
                except Exception:
                    continue
        else:
            return None
    return reduce_metric_values(values, spec.get("reduction", "last"))
 
 
def extract_metric_from_log(case_dir: str, spec: dict):
    """!
    @brief Extract a scalar metric from a log file using regex.
    @param[in] case_dir Argument passed to `extract_metric_from_log()`.
    @param[in] spec Argument passed to `extract_metric_from_log()`.
    @return Value returned by `extract_metric_from_log()`.
    """
    file_glob = spec.get("file_glob", "logs/*.log")
    regex = spec.get("regex")
    if not regex:
        return None
    candidates = sorted(glob.glob(os.path.join(case_dir, file_glob), recursive=True))
    if not candidates:
        return None
    pattern = re.compile(regex)
    values = []
    for path in candidates:
        try:
            with open(path, "r", encoding="utf-8", errors="replace") as f:
                for line in f:
                    m = pattern.search(line)
                    if m:
                        try:
                            values.append(float(m.group(1)))
                        except Exception:
                            pass
        except OSError:
            continue
    return reduce_metric_values(values, spec.get("reduction", "last"))
 
 
def normalize_metric_spec(metric):
    """!
    @brief Normalize study metric definitions to a common dictionary form.
    @param[in] metric Argument passed to `normalize_metric_spec()`.
    @return Value returned by `normalize_metric_spec()`.
    """
    if isinstance(metric, str):
        if metric.lower() in {"msd", "msd_final"}:
            return {
                "name": "msd_final",
                "source": "statistics_csv",
                "file_glob": "**/*_msd.csv",
                # Named, not left to the last-column fallback, which is frac_3sigma_pct.
                "column": "MSD_total",
                "reduction": "last",
            }
        return {"name": metric, "source": "log_regex", "regex": metric}
    return dict(metric)
 
def _read_previous_metric_rows(results_dir: str) -> dict:
    """!
    @brief Read the metrics table an earlier aggregation wrote, keyed by case id.
    @param[in] results_dir Study analysis directory holding metrics_table.csv.
    @return Mapping of case id to its previously recorded row, empty when absent.
    """
    path = os.path.join(results_dir, "metrics_table.csv")
    if not os.path.isfile(path):
        return {}
    try:
        with open(path, "r", encoding="utf-8", newline="") as stream:
            return {
                row["case_id"]: row for row in csv.DictReader(stream) if row.get("case_id")
            }
    except (OSError, ValueError):
        return {}
 
 
def aggregate_study_metrics(study_cfg: dict, cases: list, results_dir: str) -> str:
    """!
    @brief Collect metric values from generated case directories into one CSV.
    @param[in] study_cfg Argument passed to `aggregate_study_metrics()`.
    @param[in] cases Argument passed to `aggregate_study_metrics()`.
    @param[in] results_dir Argument passed to `aggregate_study_metrics()`.
    @return Value returned by `aggregate_study_metrics()`.
    """
    metrics = study_cfg.get("metrics", [])
    if not metrics:
        metrics = ["msd_final"]
    normalized_specs = [normalize_metric_spec(m) for m in metrics]
 
    # A member whose payload was archived cannot be re-measured. Its previously
    # aggregated values are the correct answer for it, so they are carried forward
    # rather than overwritten with blanks or the whole table refused.
    preserved = _read_previous_metric_rows(results_dir)
    rows = []
    for case in cases:
        row = {"case_id": case["case_id"]}
        flat_parameters = flatten_study_parameters(case.get("parameters", {}))
        for p_key, p_val in flat_parameters.items():
            row[p_key] = p_val
        if is_artifact_cold(case["run_dir"]):
            retained = preserved.get(case["case_id"])
            if retained:
                for spec in normalized_specs:
                    name = spec.get("name", "metric")
                    row[name] = retained.get(name)
                row["_source"] = "retained"
                rows.append(row)
                continue
            print(
                f"[WARNING] {case['case_id']} is in cold storage and no previous metrics "
                "row was found; its values are reported as unavailable.",
                file=sys.stderr,
            )
            for spec in normalized_specs:
                row[spec.get("name", "metric")] = None
            rows.append(row)
            continue
        for spec in normalized_specs:
            name = spec.get("name", "metric")
            source = str(spec.get("source", "")).lower()
            if source in METRIC_SOURCE_KINDS[:2]:
                value = extract_metric_from_csv(case["run_dir"], spec)
            elif source in METRIC_SOURCE_KINDS[2:]:
                value = extract_metric_from_log(case["run_dir"], spec)
            else:
                value = None
 
            normalize_key = spec.get("normalize_by_parameter")
            if value is not None and normalize_key:
                denom = flat_parameters.get(normalize_key)
                try:
                    denom = float(denom)
                except Exception:
                    denom = None
                if denom not in (None, 0.0):
                    value = float(value) / denom
                else:
                    value = None
 
            row[name] = value
        rows.append(row)
 
    if not rows:
        return None
 
    all_keys = []
    seen = set()
    for row in rows:
        for k in row.keys():
            if k not in seen:
                seen.add(k)
                all_keys.append(k)
 
    os.makedirs(results_dir, exist_ok=True)
    out_csv = os.path.join(results_dir, "metrics_table.csv")
    with open(out_csv, "w", newline="") as f:
        writer = csv.DictWriter(f, fieldnames=all_keys)
        writer.writeheader()
        writer.writerows(rows)
    metric_names = [spec.get("name", "metric") for spec in normalized_specs]
    if any(row.get(name) is not None for row in rows for name in metric_names):
        print(f"[SUCCESS] Aggregated metrics table: {os.path.relpath(out_csv)}")
    else:
        # At submission no member has run; the metrics job fills the table later.
        print(f"[INFO] Initialized metrics table (no member has produced metrics yet): "
              f"{os.path.relpath(out_csv)}")
    return out_csv
 
_STUDY_REPORT_COLORS = (
    "#0072B2", "#D55E00", "#009E73", "#CC79A7",
    "#E69F00", "#56B4E9", "#332288", "#999999",
)
 
 
def _study_parameter_label(key: str) -> str:
    """!
    @brief Return a concise report label for a study parameter path.
    @param[in] key Dotted study parameter path.
    @return Report-facing axis or legend label.
    """
    exact = {
        "case.run_control.dt_physical": "Physical timestep, Δt",
        "case.models.physics.particles.count": "Particle count",
        "solver.operation_mode.uniform_flow.u": "Uniform-flow velocity, u",
        "case.grid.programmatic_settings.im": "Grid nodes in i, Nᵢ",
        "case.grid.programmatic_settings.jm": "Grid nodes in j, Nⱼ",
        "case.grid.programmatic_settings.km": "Grid nodes in k, Nₖ",
    }
    return exact.get(key, _humanize_plot_identifier(key))
 
 
def _study_metric_label(study_cfg: dict, metric: str) -> str:
    """!
    @brief Resolve an optional configured metric label or humanize its name.
    @param[in] study_cfg Parsed study configuration.
    @param[in] metric Metric column name.
    @return Report-facing metric label.
    """
    for raw_spec in study_cfg.get("metrics", []) or []:
        spec = normalize_metric_spec(raw_spec)
        if spec.get("name") != metric:
            continue
        label = spec.get("plot_label") or spec.get("label")
        units = spec.get("units")
        base = str(label) if label else _humanize_plot_identifier(metric)
        return f"{base} ({units})" if units else base
    return _humanize_plot_identifier(metric)
 
 
def _numeric_study_column(rows: list, key: str) -> "list | None":
    """!
    @brief Parse one complete, finite numeric study-table column.
    @param[in] rows Metrics-table rows.
    @param[in] key Column name.
    @return Numeric values, or None when the column is incomplete or nonnumeric.
    """
    values = []
    for row in rows:
        try:
            value = float(row[key])
        except (KeyError, TypeError, ValueError):
            return None
        if not math.isfinite(value):
            return None
        values.append(value)
    return values
 
 
def _infer_study_plot_axis(study_cfg: dict, rows: list) -> "dict | None":
    """!
    @brief Infer the scientifically meaningful independent variable of a study.
    @param[in] study_cfg Parsed study configuration.
    @param[in] rows Metrics-table rows.
    @return Axis metadata, or None when no numeric independent variable exists.
    """
    params = [key for key in get_study_parameter_keys(study_cfg) if rows and key in rows[0]]
    if not params or not rows:
        return None
 
    grid_keys = (
        "case.grid.programmatic_settings.im",
        "case.grid.programmatic_settings.jm",
        "case.grid.programmatic_settings.km",
    )
    if study_cfg.get("study_type") == "grid_independence" and all(key in params for key in grid_keys):
        columns = [_numeric_study_column(rows, key) for key in grid_keys]
        if all(column is not None for column in columns):
            values = [
                (columns[0][index] * columns[1][index] * columns[2][index]) ** (1.0 / 3.0)
                for index in range(len(rows))
            ]
            return {
                "key": "characteristic_grid_resolution",
                "label": "Characteristic grid resolution, (NᵢNⱼNₖ)¹⁄³",
                "slug": "characteristic_grid_resolution",
                "values": values,
                "contributors": set(grid_keys),
            }
 
    preferred = []
    if study_cfg.get("study_type") == "timestep_independence":
        preferred = [key for key in params if key.endswith(".dt_physical")]
    numeric = []
    for key in preferred + [key for key in params if key not in preferred]:
        values = _numeric_study_column(rows, key)
        if values is not None:
            numeric.append((key, values, len(set(values))))
    if not numeric:
        return None
    varied = [candidate for candidate in numeric if candidate[2] > 1]
    key, values, _unique = (varied or numeric)[0]
    return {
        "key": key,
        "label": _study_parameter_label(key),
        "slug": re.sub(r"[^A-Za-z0-9_.-]+", "_", key),
        "values": values,
        "contributors": {key},
    }
 
 
def infer_plot_x_axis(study_cfg: dict, rows: list):
    """!
    @brief Infer x-axis key/values for study plots.
    @param[in] study_cfg Argument passed to `infer_plot_x_axis()`.
    @param[in] rows Argument passed to `infer_plot_x_axis()`.
    @return Value returned by `infer_plot_x_axis()`.
    """
    axis = _infer_study_plot_axis(study_cfg, rows)
    if axis is None:
        return None, None
    return axis["label"], axis["values"]
 
 
def _format_study_group_value(value) -> str:
    """!
    @brief Format a secondary study parameter compactly for a legend.
    @param[in] value Parameter value.
    @return Compact report string.
    """
    try:
        number = float(value)
    except (TypeError, ValueError):
        return str(value)
    if number.is_integer():
        return f"{int(number):,}"
    return f"{number:g}"
 
 
def _study_plot_groups(study_cfg: dict, rows: list, axis: dict, metric: str) -> list:
    """!
    @brief Group metric points by any secondary varied study parameters.
    @param[in] study_cfg Parsed study configuration.
    @param[in] rows Metrics-table rows.
    @param[in] axis Inferred independent-axis metadata.
    @param[in] metric Metric column name.
    @return Labeled point groups.
    """
    param_keys = [key for key in get_study_parameter_keys(study_cfg) if rows and key in rows[0]]
    secondary = []
    for key in param_keys:
        if key in axis["contributors"]:
            continue
        values = {str(row.get(key)) for row in rows}
        # A control coupled one-to-one with x (for example total_steps paired
        # with dt to keep physical duration fixed, or particle count paired with
        # grid size to keep PPC fixed) describes the same study trajectory. It
        # must not split that trajectory into one-point pseudo-series.
        if 1 < len(values) < len(rows):
            secondary.append(key)
 
    groups = {}
    for row_index, row in enumerate(rows):
        try:
            y_value = float(row[metric])
        except (KeyError, TypeError, ValueError):
            continue
        if not math.isfinite(y_value):
            continue
        identity = tuple(row.get(key) for key in secondary)
        groups.setdefault(identity, []).append([axis["values"][row_index], y_value])
 
    result = []
    for identity, points in groups.items():
        points.sort(key=lambda point: point[0])
        label = ", ".join(
            f"{_study_parameter_label(key)} = {_format_study_group_value(value)}"
            for key, value in zip(secondary, identity)
        )
        result.append({"label": label or "Study cases", "points": points})
    return result
 
 
def _study_use_log_scale(values: list, semantic_hint: bool = False) -> bool:
    """!
    @brief Use log scaling only for positive data spanning a meaningful range.
    @param[in] values Candidate axis values.
    @param[in] semantic_hint Whether the quantity is conventionally read logarithmically.
    @return True when logarithmic scaling improves interpretation.
    """
    if not values or any(value <= 0.0 for value in values):
        return False
    ratio = max(values) / min(values)
    return ratio >= (20.0 if semantic_hint else 100.0)
 
 
def _study_linear_y_limits(values: list) -> "tuple[float, float] | None":
    """!
    @brief Build padded linear limits that include zero for non-negative metrics.
    @param[in] values Finite metric values.
    @return Lower and upper limits, or None for an empty sequence.
    """
    if not values:
        return None
    lower, upper = min(values), max(values)
    if lower >= 0.0:
        lower = 0.0
    span = upper - lower
    padding = max(span * 0.06, abs(upper) * 0.02, 1.0e-12)
    return (lower, upper + padding) if lower == 0.0 else (lower - padding, upper + padding)
 
def generate_study_plots(study_cfg: dict, metrics_csv: str, plots_dir: str):
    """!
    @brief Generate metric-vs-parameter plots for completed studies.
    @param[in] study_cfg Argument passed to `generate_study_plots()`.
    @param[in] metrics_csv Argument passed to `generate_study_plots()`.
    @param[in] plots_dir Argument passed to `generate_study_plots()`.
    @return Value returned by `generate_study_plots()`.
    """
    plotting_cfg = study_cfg.get("plotting", {}) or {}
    if plotting_cfg.get("enabled", True) is False:
        print("[INFO] Plotting disabled by study.yml.")
        return []
    plt = optional_matplotlib_pyplot()
    if plt is None:
        print("[WARNING] matplotlib not available; skipping plot generation.")
        return []
    if not metrics_csv or not os.path.isfile(metrics_csv):
        return []
 
    with open(metrics_csv, "r", newline="") as f:
        reader = csv.DictReader(f)
        rows = list(reader)
    if not rows:
        return []
 
    axis = _infer_study_plot_axis(study_cfg, rows)
    if axis is None:
        print("[WARNING] Could not infer numeric x-axis for plots; skipping.")
        return []
 
    configured_metrics = study_cfg.get("metrics", []) or ["msd_final"]
    metric_keys = [
        normalize_metric_spec(metric).get("name", "metric") for metric in configured_metrics
        if normalize_metric_spec(metric).get("name", "metric") in rows[0]
    ]
 
    out_format = plotting_cfg.get("output_format", "png")
    os.makedirs(plots_dir, exist_ok=True)
    generated = []
    for metric in metric_keys:
        groups = _study_plot_groups(study_cfg, rows, axis, metric)
        if not groups:
            continue
        all_x = [point[0] for group in groups for point in group["points"]]
        all_y = [point[1] for group in groups for point in group["points"]]
        metric_label = _study_metric_label(study_cfg, metric)
        metric_hint = metric.lower()
        y_log = _study_use_log_scale(
            all_y,
            any(token in metric_hint for token in ("error", "residual", "drift", "msd")),
        )
        x_log = _study_use_log_scale(all_x)
        grid_cross_product = (
            study_cfg.get("study_type") == "grid_independence"
            and bool(study_cfg.get("parameters")) and len(axis["contributors"]) == 3
            and sum(
                len(set(float(row[key]) for row in rows)) > 1
                for key in axis["contributors"]
            ) > 1
        )
 
        plt.figure(figsize=(9.2, 5.5), facecolor="white")
        for index, group in enumerate(groups):
            x_values = [point[0] for point in group["points"]]
            y_values = [point[1] for point in group["points"]]
            repeated_x = len(set(x_values)) != len(x_values)
            plt.plot(
                x_values, y_values,
                color=_STUDY_REPORT_COLORS[index % len(_STUDY_REPORT_COLORS)],
                marker="o", markersize=5.2, markeredgewidth=0.7,
                linewidth=0.0 if repeated_x or grid_cross_product else 1.8,
                linestyle="none" if repeated_x or grid_cross_product else "-",
                label=group["label"],
            )
        plt.xlabel(axis["label"], fontsize=11)
        plt.ylabel(metric_label, fontsize=11)
        study_label = {
            "grid_independence": "Grid-independence study",
            "timestep_independence": "Timestep-independence study",
            "sensitivity": "Sensitivity study",
        }.get(study_cfg.get("study_type"), "Parameter study")
        plt.title(f"{metric_label} vs. {axis['label']}\n{study_label}", fontsize=13, loc="left", pad=12)
        if x_log and hasattr(plt, "xscale"):
            plt.xscale("log")
        if y_log:
            plt.yscale("log")
        elif hasattr(plt, "ylim"):
            limits = _study_linear_y_limits(all_y)
            if limits:
                plt.ylim(*limits)
        if hasattr(plt, "tick_params"):
            plt.tick_params(axis="both", which="major", labelsize=9.5)
        plt.grid(True, alpha=0.24, which="major", linewidth=0.7)
        if x_log or y_log:
            plt.grid(True, alpha=0.08, which="minor", linewidth=0.5)
        if len(groups) > 1:
            plt.legend(
                loc="upper left", bbox_to_anchor=(1.01, 1.0), borderaxespad=0.0,
                frameon=False, title="Fixed parameters", fontsize=9, title_fontsize=9.5,
            )
            plt.tight_layout(rect=(0.0, 0.0, 0.76, 1.0))
        else:
            plt.tight_layout()
        safe_metric = re.sub(r"[^A-Za-z0-9_.-]+", "_", metric)
        out_path = os.path.join(plots_dir, f"{safe_metric}_vs_{axis['slug']}.{out_format}")
        plt.savefig(out_path, dpi=240, bbox_inches="tight", facecolor="white")
        plt.close()
        generated.append(out_path)
    if generated:
        print(f"[SUCCESS] Generated {len(generated)} plot(s) in {os.path.relpath(plots_dir)}")
    return generated
 
 
def _command_to_string(command_tokens: list) -> str:
    """!
    @brief Render a command list as a shell-safe display string.
    @param[in] command_tokens Argument passed to `_command_to_string()`.
    @return Value returned by `_command_to_string()`.
    """
    return " ".join(shlex.quote(str(tok)) for tok in command_tokens)
 
 
def _resolve_post_source_directory_preview(run_dir: str, monitor_cfg: dict, post_cfg: dict) -> str:
    """!
    @brief Resolve post source directory without side effects or stdout/stderr output.
    @param[in] run_dir Argument passed to `_resolve_post_source_directory_preview()`.
    @param[in] monitor_cfg Argument passed to `_resolve_post_source_directory_preview()`.
    @param[in] post_cfg Argument passed to `_resolve_post_source_directory_preview()`.
    @return Value returned by `_resolve_post_source_directory_preview()`.
    """
    solver_output_dir_abs = os.path.join(run_dir, CANONICAL_RUN_PATHS["output"])
    source_dir_template = get_post_source_directory_template(post_cfg)
    if source_dir_template == '<solver_output_dir>':
        return solver_output_dir_abs
    return os.path.abspath(os.path.join(run_dir, source_dir_template))
 
 
def build_run_dry_plan(args) -> dict:
    """!
    @brief Build a no-write execution plan for `run --dry-run`.
    @param[in] args Command-line style argument list supplied to the function.
    @return Value returned by `build_run_dry_plan()`.
    """
    plan = {
        "mode": "dry-run",
        "created_at": datetime.now().isoformat(),
        "warnings": [],
        "inputs": {},
        "stages": {},
        "artifacts": [],
    }
 
    if args.dry_run and args.no_submit:
        plan["warnings"].append("--dry-run takes precedence over --no-submit; no files will be written.")
 
    cluster_mode = bool(getattr(args, "cluster", None))
    cluster_cfg = None
    cluster_path = None
    solver_num_procs_effective = args.num_procs
    post_num_procs_effective = args.num_procs
    run_id = None
    run_dir = None
    solver_control_path = None
    loaded_case_cfg = None
    loaded_monitor_cfg = None
    resolved_restart_source_dir = None
 
    if cluster_mode:
        cluster_path = os.path.abspath(args.cluster)
        cluster_cfg = read_yaml_file(cluster_path)
        validate_cluster_config(cluster_cfg, cluster_path)
        scheduler_type = str(cluster_cfg.get("scheduler", {}).get("type", "slurm")).lower()
        if args.scheduler and args.scheduler.lower() != scheduler_type:
            emit_structured_error(
                ERROR_CODE_CFG_INCONSISTENT_COMBO,
                key="scheduler.type",
                file_path=cluster_path,
                message=f"--scheduler={args.scheduler} does not match cluster.yml scheduler.type={scheduler_type}.",
            )
            sys.exit(1)
        if scheduler_type != "slurm":
            emit_structured_error(
                ERROR_CODE_CFG_INVALID_VALUE,
                key="scheduler.type",
                file_path=cluster_path,
                message=f"Unsupported scheduler '{scheduler_type}'. Only Slurm is supported.",
            )
            sys.exit(1)
        cluster_tasks = get_cluster_total_tasks(cluster_cfg)
        if (args.solve or args.post_process) and args.num_procs not in (1, cluster_tasks):
            emit_structured_error(
                ERROR_CODE_CFG_INCONSISTENT_COMBO,
                key="resources.ntasks_per_node",
                file_path=cluster_path,
                message=(
                    "--num-procs must be 1 (auto) or "
                    f"exactly nodes*ntasks_per_node ({cluster_tasks}) in cluster mode."
                ),
            )
            sys.exit(1)
        if args.solve:
            solver_num_procs_effective = cluster_tasks
        if args.post_process:
            post_num_procs_effective = cluster_tasks
        plan["launch_mode"] = "slurm"
        plan["inputs"]["cluster"] = cluster_path
    else:
        if getattr(args, "scheduler", None):
            fail_cli_usage("--scheduler requires --cluster in this version.")
        plan["launch_mode"] = "local"
 
    # --- Guard: restart flags without --solve ---
    if not args.solve:
        if getattr(args, 'restart_from', None):
            print("[WARNING] --restart-from has no effect without --solve and will be ignored.", file=sys.stderr)
        if getattr(args, 'continue_run', False):
            print("[WARNING] --continue only extends a solve in place and is ignored here. "
                  "Post-processing always skips steps whose output is up to date; drop "
                  "--continue from post-only commands.", file=sys.stderr)
 
    if args.solve:
        case_path = os.path.abspath(args.case)
        workspace_root = find_workspace_root(case_path, args.solver, args.monitor, os.getcwd())
        if workspace_root:
            enforce_workspace_version(workspace_root)
            enforce_reproducibility_policy(workspace_root)
        solver_path = os.path.abspath(args.solver)
        monitor_path = os.path.abspath(args.monitor)
        loaded_case_cfg = read_yaml_file(case_path)
        solver_cfg = read_yaml_file(solver_path)
        loaded_monitor_cfg = read_yaml_file(monitor_path)
        validate_simulation_configs(
            loaded_case_cfg, solver_cfg, loaded_monitor_cfg, case_path, solver_path, monitor_path,
            restart_source_given=bool(getattr(args, 'restart_from', None) or getattr(args, 'continue_run', False)),
        )
 
        continue_mode = getattr(args, 'continue_run', False)
 
        if continue_mode:
            # --continue reuses existing run directory
            if not args.run_dir:
                fail_cli_usage(RESTART_RUN_DIR_REQUIRED_MESSAGE)
            run_dir = os.path.abspath(args.run_dir)
            if not os.path.isdir(run_dir):
                emit_structured_error(
                    ERROR_CODE_CFG_FILE_NOT_FOUND,
                    key="run-dir",
                    file_path=run_dir,
                    message="Specified run directory not found.",
                )
                sys.exit(1)
            adopt_relocated_artifact(run_dir, dry_run=True)
            run_id = os.path.basename(run_dir)
        else:
            runs_root = workspace_artifact_root(workspace_root, "runs")
            run_id = allocate_generated_run_id(runs_root, loaded_case_cfg, case_path)
            run_dir = os.path.join(runs_root, run_id)
 
        try:
            resolved_restart_source_dir, is_continue, planned_lineage = resolve_restart_source(
                args, loaded_case_cfg, solver_cfg, loaded_monitor_cfg, run_dir,
                materialize=False,
            )
            plan["lineage"] = planned_lineage or {"relationship": "root"}
            planned_index_bytes = select_run_petsc_index_bytes(
                args, loaded_case_cfg, case_path, loaded_monitor_cfg, resolved_restart_source_dir)
        except ValueError as e:
            emit_structured_error(
                ERROR_CODE_CFG_INCONSISTENT_COMBO,
                key="restart",
                file_path=case_path,
                message=str(e),
                hint=_STORAGE_RESTORE_HINT if isinstance(e.__cause__, StorageError) else _RESTART_HINT,
            )
            sys.exit(1)
 
        config_dir = os.path.join(run_dir, "config")
        scheduler_dir = os.path.join(run_dir, "scheduler")
        # Report the directories the run will ACTUALLY use, not the defaults. A plan
        # that hides a configured path cannot warn about where output really lands -
        # and the fresh-run log directory is deleted recursively by the C runtime.
        _plan_dirs = {}
        logs_dir = os.path.join(run_dir, CANONICAL_RUN_PATHS["logs"])
        planned_output_dir = os.path.join(run_dir, CANONICAL_RUN_PATHS["output"])
        solver_control_path = os.path.join(config_dir, f"{run_id}.control")
        profile_path = os.path.join(config_dir, "profile.run")
        profiling_preview = resolve_profiling_config(loaded_monitor_cfg)
 
        plan["run_id_preview"] = run_id
        plan["run_dir_preview"] = run_dir
        # A layout the coarsest multigrid level cannot hold aborts grid setup on the
        # cluster, after the queue wait; it is decidable here from the grid's size.
        block_dims = resolve_grid_node_dims(
            loaded_case_cfg, case_path,
            os.path.join(run_dir, "inputs", "grid", "grid.run") if continue_mode else None)
        decomposition = resolve_decomposition(
            solver_num_procs_effective, loaded_case_cfg.get("grid") or {}, block_dims, solver_cfg,
            case_declares_periodic_axis(loaded_case_cfg), getattr(args, "decomposition", None),
            cluster_cfg if cluster_mode else None)
        plan.setdefault("blocking", []).extend(decomposition["problems"])
        plan["decomposition"] = {"layout": list(decomposition["layout"]) if decomposition.get("layout") else None,
                                 "source": decomposition["source"],
                                 "summary": describe_decomposition(decomposition, solver_num_procs_effective)}
        if block_dims is None and solver_num_procs_effective > 1:
            plan["warnings"].append(
                "Could not determine the grid's dimensions without building it, so the "
                "decomposition was not checked against the multigrid levels.")
        # A plan that omits what a real run would refuse is not a plan. The run
        # directory does not exist yet, but `realpath` still normalizes it, so the
        # run-root and ancestor verdicts are decidable here.
        _authorized, _ = resolve_unsafe_paths_override(_plan_dirs, "monitor.yml")
        plan.setdefault("blocking", [])
        # A run resumed into a directory that grew an unrouted peer would be refused,
        # so the plan has to say so rather than promising a launch that will not happen.
        structure_errors, structure_warnings = validate_run_directory_structure(run_dir)
        plan["blocking"].extend(structure_errors)
        plan["warnings"].extend(structure_warnings)
        for _key, _verdict, _message in classify_physical_containment(
                run_dir, effective_run_directories(_plan_dirs)):
            if _authorized and _verdict in WAIVABLE_PHYSICAL_VERDICTS:
                plan["warnings"].append(f"{_message} Allowed only because "
                                        f"'allow_unsafe_paths: true' is set.")
            else:
                plan["blocking"].append(_message)
        plan["inputs"].update({"case": case_path, "solver": solver_path, "monitor": monitor_path})
        asset_plan = plan_run_assets(
            loaded_case_cfg, case_path, unused_asset_kinds(loaded_case_cfg, solver_cfg)
        )
        plan["asset_actions"] = [
            {"kind": item["kind"], "provider": item["provider"], "action": item["action"]}
            for item in asset_plan["actions"]
        ]
        runtime_kinds = {
            item["kind"] for item in asset_plan["actions"]
            if item["execution"] == "runtime-c"
        }
        for item in asset_plan["actions"]:
            blocked_dependencies = runtime_kinds.intersection(item.get("dependencies", []))
            if item["execution"] == "precomputable" and blocked_dependencies:
                plan["blocking"].append(
                    f"{item['kind']}={item['provider']} requires a file-backed "
                    f"{', '.join(sorted(blocked_dependencies))}, but that dependency is generated "
                    "only inside the simulator. Select a precomputable provider for the dependency."
                )
        plan["artifacts"].extend(
            [
                run_dir,
                *(os.path.join(run_dir, *relative.split("/"))
                  for relative in RUN_DIRECTORY_LAYOUT),
                os.path.join(config_dir, "case.yml"),
                os.path.join(config_dir, "solver.yml"),
                os.path.join(config_dir, "monitor.yml"),
                os.path.join(config_dir, "active.json"),
                os.path.join(run_dir, CANONICAL_RUN_PATHS["inputs"], "assets.lock.yml"),
                solver_control_path,
                os.path.join(run_dir, "manifest.json"),
            ]
        )
        add_planned_grid_artifacts(plan, loaded_case_cfg, run_dir)
        add_planned_profile_artifacts(plan, loaded_case_cfg, run_dir)
        add_planned_initial_condition_artifacts(plan, loaded_case_cfg, solver_cfg, run_dir)
        if has_explicit_monitor_whitelist(loaded_monitor_cfg):
            plan["artifacts"].append(os.path.join(config_dir, "whitelist.run"))
        if profiling_preview["mode"] == "selected":
            plan["artifacts"].append(profile_path)
        solve_diagnostics = resolve_diagnostics_config(loaded_monitor_cfg, run_dir, "Solver")
        plan["artifacts"].extend(solve_diagnostics["artifacts"])
        if cluster_mode:
            plan["artifacts"].append(os.path.join(config_dir, "cluster.yml"))
            plan["artifacts"].append(os.path.join(scheduler_dir, "submission.json"))
 
        executable_plan = plan_run_executable_paths(run_dir, args, workspace_root)
        solver_exe = executable_plan["paths"]["simulator"]
        if executable_plan["pinning"] == "new":
            plan["artifacts"].extend(executable_plan["paths"].values())
        solver_args = build_petsc_diagnostics_args(loaded_monitor_cfg, run_dir, "Solver") + ["-control_file", solver_control_path]
        if cluster_mode:
            solver_script = os.path.join(scheduler_dir, "solver.sbatch")
            solver_cmd = build_cluster_launch_command(
                cluster_cfg,
                solver_exe,
                solver_args,
                config_search_anchor=case_path,
                extra_search_anchors=[cluster_path],
            )
            plan["artifacts"].append(solver_script)
            plan["stages"]["solve"] = {
                "mode": "slurm",
                "script": solver_script,
                "num_procs_effective": solver_num_procs_effective,
                "launch_command": solver_cmd,
                "launch_command_string": _command_to_string(solver_cmd),
            }
        else:
            solver_cmd = build_local_launch_command(
                solver_exe,
                solver_args,
                solver_num_procs_effective,
                config_search_anchor=case_path,
            )
            solver_stream_log = os.path.join(scheduler_dir, f"{run_id}_solver.log")
            plan["artifacts"].append(solver_stream_log)
            plan["stages"]["solve"] = {
                "mode": "local",
                "num_procs_effective": solver_num_procs_effective,
                "stream_log": solver_stream_log,
                "launch_command": solver_cmd,
                "launch_command_string": _command_to_string(solver_cmd),
            }
        plan["stages"]["solve"]["executable_pinning"] = executable_plan["pinning"]
        plan["stages"]["solve"]["petsc_index_bits"] = 8 * planned_index_bytes
        planned_run_control = loaded_case_cfg.get("run_control") or {}
        plan["stages"]["solve"]["start_step"] = int(planned_run_control.get("start_step", 0) or 0)
        plan["stages"]["solve"]["end_step"] = (plan["stages"]["solve"]["start_step"]
                                               + int(planned_run_control.get("total_steps", 0) or 0))
        if resolved_restart_source_dir:
            plan["stages"]["solve"]["restart_source_directory"] = resolved_restart_source_dir
        if is_continue:
            plan["stages"]["solve"]["continue_mode"] = True
 
    if args.post_process:
        post_path = os.path.abspath(args.post)
        plan["inputs"]["post"] = post_path
        post_cfg = read_yaml_file(post_path)
        validate_post_config(post_cfg, post_path, loaded_monitor_cfg, loaded_case_cfg)
 
        if args.run_dir:
            run_dir = os.path.abspath(args.run_dir)
            if not os.path.isdir(run_dir):
                emit_structured_error(
                    ERROR_CODE_CFG_FILE_NOT_FOUND,
                    key="run-dir",
                    file_path=run_dir,
                    message="Specified run directory not found.",
                )
                sys.exit(1)
            adopt_relocated_artifact(run_dir, dry_run=True)
            run_id = os.path.basename(run_dir)
        elif not args.solve:
            fail_cli_usage("--post-process requires --run-dir when not used with --solve.")
 
        if args.run_dir:
            config_dir = os.path.join(run_dir, "config")
            case_path, monitor_path, solver_control_path = auto_identify_run_inputs(config_dir)
            if not all([case_path, monitor_path, solver_control_path]):
                emit_structured_error(
                    ERROR_CODE_CFG_MISSING_KEY,
                    key="run_dir.config",
                    file_path=config_dir,
                    message=(
                        "Could not auto-identify required run inputs "
                        "(case.yml/monitor.yml/*.control) in run config directory."
                    ),
                )
                sys.exit(1)
            loaded_case_cfg = read_yaml_file(case_path)
            loaded_monitor_cfg = read_yaml_file(monitor_path)
        else:
            config_dir = os.path.join(run_dir, "config")
            case_path = os.path.join(config_dir, "case.yml")
            monitor_path = os.path.join(config_dir, "monitor.yml")
            if solver_control_path is None:
                solver_control_path = os.path.join(config_dir, f"{run_id}.control")
 
        post_cfg, recipe_id = apply_canonical_post_paths(post_cfg, run_dir)
        allow_source_frontier_scan = not args.solve
        recompute = bool(getattr(args, 'recompute_post', False))
        if args.solve:
            post_exe = executable_plan["paths"]["postprocessor"]
        else:
            try:
                select_existing_run_petsc_index_bytes(run_dir, args)
            except ValueError as e:
                emit_structured_error(ERROR_CODE_CFG_INCONSISTENT_COMBO, key="petsc_index_bits",
                                      file_path=run_dir, message=str(e))
                sys.exit(1)
            post_exe = run_executable_path(run_dir, "postprocessor")
        post_plan = build_post_execution_plan(
            run_dir,
            run_id,
            loaded_case_cfg,
            loaded_monitor_cfg,
            post_cfg,
            recompute=recompute,
            allow_source_frontier_scan=allow_source_frontier_scan,
            postprocessor_sha=_file_sha256(post_exe),
        )
 
        if args.solve:
            post_decomposition = resolve_decomposition(
                post_num_procs_effective, loaded_case_cfg.get("grid") or {}, block_dims, solver_cfg,
                case_declares_periodic_axis(loaded_case_cfg), getattr(args, "decomposition", None),
                cluster_cfg if cluster_mode else None)
        else:
            post_decomposition = resolve_post_decomposition(
                run_dir, post_num_procs_effective, getattr(args, "decomposition", None),
                cluster_cfg if cluster_mode else None)
        plan.setdefault("blocking", []).extend(
            problem for problem in post_decomposition["problems"] if problem not in plan["blocking"])
        plan["post_decomposition"] = {
            "layout": list(post_decomposition["layout"]) if post_decomposition.get("layout") else None,
            "source": post_decomposition["source"],
            "summary": describe_decomposition(post_decomposition, post_num_procs_effective)}
 
        post_recipe_path = os.path.join(get_post_recipe_root(run_dir, post_cfg), "post.run")
        archived_post_path = os.path.join(get_post_recipe_root(run_dir, post_cfg), "post.yml")
        post_finalize_command = build_post_finalize_command(run_dir, archived_post_path, post_cfg)
        output_dir_rel = post_cfg.get("io", {}).get("output_directory")
        output_prefix = post_cfg.get("io", {}).get("output_filename_prefix")
        if not output_prefix:
            emit_structured_error(
                ERROR_CODE_CFG_MISSING_KEY,
                key="io.output_filename_prefix",
                file_path=post_path,
                message="Missing required post output filename prefix.",
            )
            sys.exit(1)
        output_dir_abs = os.path.abspath(os.path.join(run_dir, output_dir_rel))
        statistics_output_paths = get_post_statistics_output_artifacts(post_cfg, run_dir, loaded_monitor_cfg)
        post_diagnostics = resolve_diagnostics_config(loaded_monitor_cfg, run_dir, "PostProcessor")
        plan["artifacts"].extend(post_diagnostics["artifacts"])
        post_args = build_petsc_diagnostics_args(loaded_monitor_cfg, run_dir, "PostProcessor") + [
            "-control_file",
            solver_control_path,
            "-postprocessing_config_file",
            post_recipe_path,
        ]
        plan["artifacts"].extend([
            post_recipe_path,
            archived_post_path,
            output_dir_abs,
            post_plan["resume_state_path"],
            post_plan["lock_paths"]["wrapper_path"],
            post_plan["lock_paths"]["lock_file"],
            post_plan["lock_paths"]["metadata_file"],
        ])
        plan["artifacts"].extend(statistics_output_paths)
        if post_finalize_command:
            io_cfg = post_cfg.get("io", {}) or {}
            if _post_requests_eulerian_output(post_cfg):
                plan["artifacts"].append(os.path.join(
                    output_dir_abs, f"{io_cfg.get('output_filename_prefix', 'Field')}.pvd"
                ))
            if _post_requests_particle_output(post_cfg):
                plan["artifacts"].append(os.path.join(
                    output_dir_abs, f"{io_cfg.get('particle_filename_prefix', 'Particle')}.pvd"
                ))
 
        stage_meta = {
            "source_data_directory": post_plan["source_data_directory"],
            "requested_start_step": post_plan["requested_start_step"],
            "requested_end_step": post_plan["requested_end_step"],
            "step_interval": post_plan["step_interval"],
            "recompute": recompute,
            "steps_to_process": post_plan["steps_to_process"],
            "steps_current": post_plan["steps_current"],
            "steps_other_build": post_plan["steps_other_build"],
            "steps_unavailable": post_plan["steps_unavailable"],
            "process_reasons": post_plan["process_reasons"],
            "source_frontier_step": post_plan["source_frontier_step"],
            "source_frontier_diagnostic": post_plan["source_frontier_diagnostic"],
            "source_frontier_deferred": post_plan["source_frontier_deferred"],
            "effective_start_step": post_plan["effective_start_step"],
            "effective_end_step": post_plan["effective_end_step"],
            "skip_reason": post_plan["skip_reason"],
            "post_skipped_as_complete": post_plan["skip_reason"] == "already-complete-window",
            "recipe_fingerprint": post_plan["recipe_fingerprint"],
            "num_procs_effective": post_num_procs_effective,
            "finalize_command": post_finalize_command,
        }
 
        if post_plan["skip_reason"] is None:
            if cluster_mode:
                scheduler_dir = os.path.join(run_dir, "scheduler")
                post_script = os.path.join(scheduler_dir, "post.sbatch")
                post_cluster_cfg = cluster_cfg
                raw_post_cmd = build_cluster_launch_command(
                    post_cluster_cfg,
                    post_exe,
                    post_args,
                    config_search_anchor=case_path,
                    extra_search_anchors=[cluster_path],
                    force_num_procs=post_num_procs_effective,
                )
                post_cmd, _ = build_post_locked_command(
                    run_dir,
                    post_plan["recipe_fingerprint"],
                    raw_post_cmd,
                    create_wrapper=False,
                    success_command=post_finalize_command,
                    post_recipe=archived_post_path,
                    postprocessor=post_exe,
                    recompute=recompute,
                )
                plan["artifacts"].append(post_script)
                stage_meta.update({
                    "mode": "slurm",
                    "script": post_script,
                    "launch_command": post_cmd,
                    "launch_command_string": _command_to_string(post_cmd),
                })
            else:
                raw_post_cmd = build_local_launch_command(
                    post_exe,
                    post_args,
                    post_num_procs_effective,
                    config_search_anchor=case_path,
                    allow_single_rank_launcher_override=True,
                    force_num_procs=post_num_procs_effective,
                )
                post_cmd, _ = build_post_locked_command(
                    run_dir,
                    post_plan["recipe_fingerprint"],
                    raw_post_cmd,
                    create_wrapper=False,
                    success_command=post_finalize_command,
                    post_recipe=archived_post_path,
                    postprocessor=post_exe,
                    recompute=recompute,
                )
                post_stream_log = os.path.join(run_dir, "scheduler", f"{run_id}_{output_prefix}.log")
                plan["artifacts"].append(post_stream_log)
                stage_meta.update({
                    "mode": "local",
                    "stream_log": post_stream_log,
                    "launch_command": post_cmd,
                    "launch_command_string": _command_to_string(post_cmd),
                })
        else:
            stage_meta.update({
                "mode": "slurm" if cluster_mode else "local",
                "launch_command": [],
                "launch_command_string": "",
            })
 
        plan["stages"]["post-process"] = stage_meta
 
    # Preserve insertion order while removing duplicates.
    deduped = []
    seen = set()
    for item in plan["artifacts"]:
        if item not in seen:
            seen.add(item)
            deduped.append(item)
    plan["artifacts"] = deduped
    if run_id and "run_id_preview" not in plan:
        plan["run_id_preview"] = run_id
    if run_dir and "run_dir_preview" not in plan:
        plan["run_dir_preview"] = run_dir
    plan["solver_num_procs_effective"] = solver_num_procs_effective
    plan["post_num_procs_effective"] = post_num_procs_effective
    plan["num_procs_effective"] = solver_num_procs_effective
    return plan
 
 
def add_planned_grid_artifacts(plan: dict, case_cfg: dict, run_dir: str) -> None:
    """!
    @brief Add grid-mode-specific staged artifacts to a dry-run plan.
    @param[in,out] plan Dry-run plan to update.
    @param[in] case_cfg Parsed case configuration.
    @param[in] run_dir Preview run directory for relative artifact resolution.
    """
    grid_cfg = case_cfg.get("grid", {})
    if not isinstance(grid_cfg, dict):
        return
 
    mode = grid_cfg.get("mode")
    grid_dir = os.path.join(run_dir, "inputs", "grid")
 
    if mode == "file":
        plan["artifacts"].append(os.path.join(grid_dir, "grid.run"))
    elif mode == "grid_gen":
        generator = grid_cfg.get("generator", {})
        if not isinstance(generator, dict):
            return
        plan["artifacts"].extend([
            os.path.join(grid_dir, "grid.run"),
            os.path.join(grid_dir, "grid.generated.picgrid"),
            os.path.join(run_dir, "output", "analysis", "metrics", "grid.info"),
            os.path.join(run_dir, "output", "visualization", "precompute", "grid.vts"),
        ])
 
def add_planned_profile_artifacts(plan: dict, case_cfg: dict, run_dir: str) -> None:
    """!
    @brief Add generated prescribed-flow profile artifacts to a dry-run plan.
    @param[in,out] plan Dry-run plan to update.
    @param[in] case_cfg Parsed case configuration.
    @param[in] run_dir Preview run directory.
    """
    try:
        prepared_blocks = validate_and_prepare_boundary_conditions(case_cfg)
    except ValueError:
        return
    profile_dir = os.path.join(run_dir, "inputs", "inlet_profiles")
    has_generated = False
    for block_idx, block in enumerate(prepared_blocks):
        for bc in block:
            if bc.get("handler") != "prescribed_flow":
                continue
            source = (bc.get("params") or {}).get("source", {})
            if source.get("type") not in PRESCRIBED_FLOW_SOURCE_TYPES[1:]:
                continue
            has_generated = True
            face_token = _face_artifact_token(bc["face"])
            suffix = "generated" if source.get("type") == "generated" else "sliced"
            generated_path = os.path.join(
                profile_dir, f"inlet_profile_block{block_idx}_{face_token}.{suffix}.dimensional.picslice"
            )
            staged_path = os.path.join(profile_dir, f"inlet_profile_block{block_idx}_{face_token}.picslice")
            plan["artifacts"].append(generated_path)
            plan["artifacts"].append(staged_path)
    if has_generated:
        plan["artifacts"].append(os.path.join(profile_dir, "profile.info"))
 
def add_planned_initial_condition_artifacts(plan: dict, case_cfg: dict, solver_cfg: dict, run_dir: str) -> None:
    """!
    @brief Add authoritative file-backed initial-condition artifacts to a dry-run plan.
    @param[in,out] plan Dry-run plan receiving artifact paths.
    @param[in] case_cfg Parsed case configuration.
    @param[in] solver_cfg Parsed solver configuration.
    @param[in] run_dir Planned run directory.
    """
    source = normalize_eulerian_field_source(
        (solver_cfg.get("operation_mode", {}) or {}).get("eulerian_field_source", "solve")
    )
    start_step = int((case_cfg.get("run_control", {}) or {}).get("start_step", 0) or 0)
    if source != "solve" or start_step != 0:
        return
    try:
        fluid_scaling = resolve_fluid_scaling(case_cfg)
        resolved = resolve_initial_condition_config(
            (case_cfg.get("properties", {}) or {}).get("initial_conditions", {}),
            validate_and_prepare_boundary_conditions(case_cfg),
            scales=fluid_scaling,
            provider_context={"kinematic_viscosity": fluid_scaling["nondimensional_kinematic_viscosity"]},
        )
    except (KeyError, ValueError):
        return
    if resolved["kind"] != "file" and not is_generated_ic_provider(resolved):
        return
    initial_dir = os.path.join(run_dir, "inputs", "initial_condition")
    plan["artifacts"].append(
        os.path.join(initial_dir, f"{resolved['field_name']}00000_0.dat")
    )
    if is_generated_ic_provider(resolved):
        if (case_cfg.get("grid", {}) or {}).get("mode") == "programmatic_c":
            plan["artifacts"].append(os.path.join(run_dir, "inputs", "grid", "grid.run"))
        plan["artifacts"].append(os.path.join(initial_dir, "initial_condition.generated.dat"))
        plan["artifacts"].extend(initial_condition_diagnostic_paths(run_dir, resolved))
 
 
def render_run_dry_plan(plan: dict, output_format: str = "text"):
    """!
    @brief Render dry-run plan in human or JSON format.
    @param[in] plan Dry-run plan produced by build_run_dry_plan().
    @param[in] output_format Either "text" or "json".
    @return 1 when the plan carries blocking findings, 0 otherwise.
    """
    if output_format == "json":
        print(json.dumps(plan, indent=2, sort_keys=True))
        return 1 if plan.get("blocking") else 0
 
    for message in plan.get("warnings", []):
        print(f"[WARNING]   {message}", file=sys.stderr)
    if plan.get("blocking"):
        print("[FATAL] This configuration would be refused. The plan below is what the "
              "run WOULD do; it will not get that far:", file=sys.stderr)
        for message in plan["blocking"]:
            print(f"  {message}", file=sys.stderr)
 
    print("\n" + "=" * 60)
    print("                      DRY-RUN PLAN")
    print("=" * 60)
    print(f"  Launch mode     : {plan.get('launch_mode')}")
    print(f"  Created at      : {plan.get('created_at')}")
    if plan.get("run_id_preview"):
        print(f"  Run ID preview  : {plan.get('run_id_preview')}")
    if plan.get("run_dir_preview"):
        print(f"  Run dir preview : {plan.get('run_dir_preview')}")
    lineage = plan.get("lineage") or {}
    if lineage.get("relationship") == "branch":
        print(f"  Branched from   : {lineage.get('parent_run_id')} "
              f"@ step {lineage.get('checkpoint_step')} "
              f"(statistics: {lineage.get('statistics_state')})")
    planned_stages = plan.get("stages") or {}
    if "solve" in planned_stages:
        print(f"  Solver MPI procs: {plan.get('solver_num_procs_effective')}")
        if "start_step" in planned_stages["solve"]:
            print(f"  Solver steps    : {planned_stages['solve']['start_step']} -> "
                  f"{planned_stages['solve']['end_step']}")
    if "post-process" in planned_stages:
        print(f"  Post MPI procs  : {plan.get('post_num_procs_effective')}")
    for key, label in (("decomposition", "Solver"), ("post_decomposition", "Post")):
        if plan.get(key):
            print(f"  {label} {plan[key]['summary']}")
    if plan.get("warnings"):
        print("  Warnings        :")
        for warning in plan["warnings"]:
            print(f"    - {warning}")
 
    if plan.get("inputs"):
        print("\n  Inputs:")
        for key, value in plan["inputs"].items():
            print(f"    - {key}: {value}")
 
    if plan.get("stages"):
        print("\n  Planned stage commands:")
        for stage, details in plan["stages"].items():
            print(f"    - {stage} ({details.get('mode')}):")
            if details.get('skip_reason'):
                print(f"      skipped: {details.get('skip_reason')}")
            else:
                print(f"      {details.get('launch_command_string')}")
 
    if plan.get("asset_actions"):
        print("\n  Asset resolution:")
        for item in plan["asset_actions"]:
            print(f"    - {item['kind']}: {item['action']} ({item['provider']})")
 
    diagnostics_artifacts = [item for item in plan.get("artifacts", []) if "PETSc_" in os.path.basename(str(item)) or os.path.basename(str(item)) == RUNTIME_MEMORY_FILE]
    if diagnostics_artifacts:
        print("\n  Diagnostics artifacts:")
        for artifact in diagnostics_artifacts:
            print(f"    - {artifact}")
 
    print("\n  Planned artifacts (no files created in dry-run):")
    for artifact in plan.get("artifacts", []):
        print(f"    - {artifact}")
    print("=" * 60)
 
 
def validate_workflow(args):
    """!
    @brief Implements `picurv validate` without launching solver/post workflows.
    @param[in] args Command-line style argument list supplied to the function.
    """
    checked = []
    solver_group_selected = any([args.case, args.solver, args.monitor])
    any_group_selected = solver_group_selected or any([args.post, args.cluster, args.study])
    case_path = None
    cluster_path = None
 
    if getattr(args, 'continue_run', False) and not getattr(args, 'run_dir', None):
        fail_cli_usage(RESTART_RUN_DIR_REQUIRED_MESSAGE)
    if not any_group_selected:
        fail_cli_usage(
            "validate requires at least one config group. Provide solver trio and/or --post/--cluster/--study.",
            hint="Example: picurv validate --case case.yml --solver solver.yml --monitor monitor.yml --post post.yml",
        )
 
    if solver_group_selected and not all([args.case, args.solver, args.monitor]):
        fail_cli_usage("When solver validation is requested, --case, --solver, and --monitor are all required.")
 
    # --- Guard: restart flags without solver group ---
    restart_from = getattr(args, 'restart_from', None)
    continue_run = getattr(args, 'continue_run', False)
    run_dir_val = getattr(args, 'run_dir', None)
    if not solver_group_selected:
        if restart_from:
            print("[WARNING] --restart-from has no effect without --case/--solver/--monitor and will be ignored.", file=sys.stderr)
        if continue_run:
            print("[WARNING] --continue validates a solve continued in place and needs "
                  "--case/--solver/--monitor; it is ignored here.", file=sys.stderr)
 
    monitor_cfg = None
    case_cfg = None
    if solver_group_selected:
        case_path = os.path.abspath(args.case)
        solver_path = os.path.abspath(args.solver)
        monitor_path = os.path.abspath(args.monitor)
        case_cfg = read_yaml_file(case_path)
        solver_cfg = read_yaml_file(solver_path)
        monitor_cfg = read_yaml_file(monitor_path)
        validate_simulation_configs(
            case_cfg, solver_cfg, monitor_cfg, case_path, solver_path, monitor_path,
            restart_source_given=bool(restart_from or continue_run),
        )
        checked.extend([case_path, solver_path, monitor_path])
 
        # Validate restart flags if provided
        if restart_from or continue_run:
            target_run_dir = os.path.abspath(run_dir_val) if run_dir_val else os.path.abspath("runs/_validate_dummy")
            try:
                resolve_restart_source(args, case_cfg, solver_cfg, monitor_cfg, target_run_dir)
                print("[SUCCESS] Restart source validation passed.")
            except ValueError as e:
                print(f"[FATAL] Restart validation failed: {e}", file=sys.stderr)
                sys.exit(1)
 
    post_cfg = None
    if args.post:
        post_path = os.path.abspath(args.post)
        post_cfg = read_yaml_file(post_path)
        validate_post_config(post_cfg, post_path, monitor_cfg, case_cfg)
        checked.append(post_path)
 
    cluster_cfg = None
    if args.cluster:
        cluster_path = os.path.abspath(args.cluster)
        cluster_cfg = read_yaml_file(cluster_path)
        validate_cluster_config(cluster_cfg, cluster_path)
        checked.append(cluster_path)
 
    # The rank layout that run --dry-run checks; without a cluster profile the process
    # count is unknown, so only each axis is checked against the coarsest multigrid level.
    if solver_group_selected:
        grid_cfg = case_cfg.get("grid") or {}
        block_dims = resolve_grid_node_dims(case_cfg, case_path)
        if cluster_cfg:
            tasks = get_cluster_total_tasks(cluster_cfg)
            decomposition = resolve_decomposition(tasks, grid_cfg, block_dims, solver_cfg,
                                                  case_declares_periodic_axis(case_cfg), None, cluster_cfg)
            layout_problems = decomposition["problems"]
            if not layout_problems:
                print(f"[INFO] {describe_decomposition(decomposition, tasks)}")
        else:
            layout_problems = da_processor_layout_problems(
                grid_cfg, None, block_dims, solver_cfg, case_declares_periodic_axis(case_cfg))
        if layout_problems:
            emit_structured_error(
                ERROR_CODE_CFG_INCONSISTENT_COMBO,
                key="grid.da_processors",
                file_path=case_path,
                message=" ".join(layout_problems),
            )
            sys.exit(1)
        if block_dims is None and resolve_grid_da_processor_layout(grid_cfg):
            print(f"[WARNING] {case_path}: could not determine the grid's dimensions without building "
                  "it, so the da_processors layout was not checked against the multigrid levels.",
                  file=sys.stderr)
 
    try:
        runtime_execution_path, _ = load_runtime_execution_config(
            case_path,
            extra_search_anchors=[cluster_path] if cluster_path else None,
        )
    except ValueError as exc:
        emit_structured_error(
            ERROR_CODE_CFG_INVALID_VALUE,
            key="runtime_execution",
            file_path=case_path or cluster_path or os.getcwd(),
            message=str(exc),
        )
        sys.exit(1)
    if runtime_execution_path:
        checked.append(runtime_execution_path)
 
    study_cfg = None
    if args.study:
        study_path = os.path.abspath(args.study)
        study_cfg = read_yaml_file(study_path)
        validate_study_config(study_cfg, study_path)
        checked.append(study_path)
 
    if post_cfg is not None and run_dir_val:
        post_path = os.path.abspath(args.post)
        validate_run_dir = os.path.abspath(run_dir_val)
        if os.path.isdir(validate_run_dir):
            monitor_for_post = monitor_cfg if solver_group_selected else None
            if monitor_for_post is None:
                config_dir_candidate = os.path.join(validate_run_dir, "config")
                monitor_candidate = os.path.join(config_dir_candidate, "monitor.yml")
                if os.path.isfile(monitor_candidate):
                    monitor_for_post = read_yaml_file(monitor_candidate)
            if monitor_for_post is not None:
                resolved_source = _resolve_post_source_directory_preview(validate_run_dir, monitor_for_post, post_cfg)
                if os.path.isdir(resolved_source) and os.listdir(resolved_source):
                    print(f"[SUCCESS] Post-processor source data directory exists: {resolved_source}")
                else:
                    print(f"[WARNING] Post-processor source data directory is missing or empty: {resolved_source}", file=sys.stderr)
 
    if post_cfg is not None:
        # apply_canonical_post_paths always reads the run's own output, so a configured
        # directory is never used; say so instead of checking that it exists.
        source_dir = (post_cfg.get("source_data") or {}).get("directory")
        if source_dir and source_dir != "<solver_output_dir>":
            print(f"[WARNING] {os.path.abspath(args.post)}: source_data.directory '{source_dir}' is "
                  "ignored; post-processing always reads the run's own output. Remove the key.",
                  file=sys.stderr)
 
    if args.strict and study_cfg is not None:
        study_path = os.path.abspath(args.study)
        base_cfgs = study_cfg.get("base_configs", {})
        if isinstance(base_cfgs, dict):
            base_case_path = resolve_path(study_path, base_cfgs.get("case"))
            base_solver_path = resolve_path(study_path, base_cfgs.get("solver"))
            base_monitor_path = resolve_path(study_path, base_cfgs.get("monitor"))
            base_post_path = resolve_path(study_path, base_cfgs.get("post"))
            if all([base_case_path, base_solver_path, base_monitor_path]):
                validate_simulation_configs(
                    read_yaml_file(base_case_path),
                    read_yaml_file(base_solver_path),
                    read_yaml_file(base_monitor_path),
                    base_case_path,
                    base_solver_path,
                    base_monitor_path,
                )
            if base_post_path:
                validate_post_config(read_yaml_file(base_post_path), base_post_path,
                                     read_yaml_file(base_monitor_path) if base_monitor_path else None,
                                     read_yaml_file(base_case_path) if base_case_path else None)
 
    print(f"[SUCCESS] Validation completed for {len(checked)} file(s).")
    for path in checked:
        print(f"  - {path}")
 
ASSET_KIND_DIRECTORIES = {
    "grid": "grids",
    "initial-condition": "initial_conditions",
    "inlet-profiles": "inlet_profiles",
}
 
 
def _asset_file_sha256(path: str) -> str:
    """!
    @brief Hash an asset source or payload without loading it into memory.
    @param[in] path File to hash.
    @return Lowercase SHA-256 digest.
    """
    digest = hashlib.sha256()
    with open(path, "rb") as stream:
        for block in iter(lambda: stream.read(8 * 1024 * 1024), b""):
            digest.update(block)
    return digest.hexdigest()
 
 
def _stable_mapping_sha256(payload) -> str:
    """!
    @brief Hash a JSON-compatible value with deterministic serialization.
    @param[in] payload Value to hash.
    @return Lowercase SHA-256 digest.
    """
    encoded = json.dumps(payload, sort_keys=True, separators=(",", ":"), default=str).encode("utf-8")
    return hashlib.sha256(encoded).hexdigest()
 
 
def _provider_source_fingerprints(value, case_path: str, key: str = "") -> dict:
    """!
    @brief Hash every existing file explicitly referenced by an asset provider.
    @param[in] value Provider subtree to inspect.
    @param[in] case_path Owning case configuration path.
    @param[in] key Current dotted key for diagnostics.
    @return Mapping of dotted path identity to path/content fingerprint.
    """
    result = {}
    if isinstance(value, dict):
        for child_key, child in value.items():
            dotted = f"{key}.{child_key}" if key else str(child_key)
            result.update(_provider_source_fingerprints(child, case_path, dotted))
        return result
    if isinstance(value, list):
        for index, child in enumerate(value):
            result.update(_provider_source_fingerprints(child, case_path, f"{key}[{index}]"))
        return result
    basename = key.rsplit(".", 1)[-1]
    if basename not in _ASSET_SOURCE_REFERENCE_KEYS or not isinstance(value, str) or not value.strip():
        return result
    try:
        resolved = resolve_workspace_path(case_path, value)
    except ValueError:
        return result
    if os.path.isfile(resolved):
        workspace_root = find_workspace_root(case_path)
        display = (
            os.path.relpath(resolved, workspace_root).replace(os.sep, "/")
            if workspace_root and os.path.commonpath([workspace_root, resolved]) == workspace_root
            else resolved
        )
        result[key] = {"path": display, "sha256": _asset_file_sha256(resolved)}
    return result
 
 
def build_case_asset_graph(case_cfg: dict, case_path: str) -> dict:
    """!
    @brief Classify case inputs into precomputable or simulator-runtime providers.
    @param[in] case_cfg Parsed case configuration.
    @param[in] case_path Owning case YAML path.
    @return Provider graph with stable identities and explicit dependencies.
    """
    providers = []
    grid_cfg = copy.deepcopy(case_cfg.get("grid", {}) or {})
    grid_mode = str(grid_cfg.get("mode", "")).strip().lower()
    if isinstance(grid_cfg.get("generator"), dict):
        grid_cfg["generator"].pop("output_file", None)
        grid_cfg["generator"].pop("vts_file", None)
        grid_cfg["generator"].pop("stats_file", None)
    grid_provider = {
        "kind": "grid",
        "provider": grid_mode or "missing",
        "execution": "runtime-c" if grid_mode == "programmatic_c" else "precomputable",
        "dependencies": [],
        "spec": grid_cfg,
    }
    providers.append(grid_provider)
 
    initial = copy.deepcopy(
        ((case_cfg.get("properties") or {}).get("initial_conditions") or {})
    )
    initial_mode = str(initial.get("mode", "generated")).strip().lower()
    initial_generator = str(initial.get("generator", "constant")).strip().lower()
    generated_python = (
        initial_mode == "generated"
        and initial_generator in _PYTHON_INITIAL_CONDITION_PROVIDERS
    )
    initial_provider = {
        "kind": "initial-condition",
        "provider": "file" if initial_mode == "file" else initial_generator,
        "execution": "precomputable" if initial_mode == "file" or generated_python else "runtime-c",
        "dependencies": ["grid"] if generated_python else [],
        "spec": initial,
    }
    providers.append(initial_provider)
 
    inlet_specs = []
    raw_blocks = case_cfg.get("boundary_conditions") or []
    if raw_blocks and isinstance(raw_blocks[0], dict):
        raw_blocks = [raw_blocks]
    for block_index, block in enumerate(raw_blocks):
        for entry in block or []:
            if not isinstance(entry, dict) or str(entry.get("handler", "")).strip().lower() != "prescribed_flow":
                continue
            source = copy.deepcopy(((entry.get("params") or {}).get("source") or {}))
            inlet_specs.append({"block": block_index, "face": entry.get("face"), "source": source})
    if inlet_specs:
        field_slice = any((item.get("source") or {}).get("type") == "field_slice" for item in inlet_specs)
        providers.append({
            "kind": "inlet-profiles",
            "provider": "prescribed-flow",
            "execution": "precomputable",
            "dependencies": ["grid"] if field_slice or grid_mode in _FILE_BACKED_GRID_VALUES else [],
            "spec": inlet_specs,
        })
 
    # A provider's identity has to cover every case value its build reads, not only its
    # own configuration subtree. The grid build nondimensionalizes by
    # properties.scaling.length_ref and validates against the declared block count;
    # both are outside `grid:`, and a change to either produces different payload bytes
    # from an identical provider spec. Left out, the staleness check reports `reuse`
    # and the solver silently receives geometry scaled by the wrong reference length.
    scaling = (case_cfg.get("properties") or {}).get("scaling") or {}
    fluid = (case_cfg.get("properties") or {}).get("fluid") or {}
    domain_blocks = (case_cfg.get("models") or {}).get("domain", {}).get("blocks", 1)
    build_contexts = {
        "grid": {
            "length_ref": scaling.get("length_ref"),
            "blocks": domain_blocks,
        },
        # The IC build resolves fluid scaling and the prepared boundary conditions.
        "initial-condition": {
            "length_ref": scaling.get("length_ref"),
            "velocity_ref": scaling.get("velocity_ref"),
            "density": fluid.get("density"),
            "viscosity": fluid.get("viscosity"),
            "boundary_conditions": case_cfg.get("boundary_conditions"),
        },
        # Profile generation dimensionalizes against the same scaling contract. On a
        # programmatic_c grid, which is not an asset the profile can depend on, it samples
        # the bridge built from programmatic_settings, so those settings are read too.
        "inlet-profiles": {
            "length_ref": scaling.get("length_ref"),
            "velocity_ref": scaling.get("velocity_ref"),
            "blocks": domain_blocks,
            "programmatic_settings": (
                grid_cfg.get("programmatic_settings") if grid_mode == "programmatic_c" else None
            ),
        },
    }
 
    # Hash in dependency order so a provider built on top of another re-identifies when
    # the thing it was built from changes.
    by_kind = {provider["kind"]: provider for provider in providers}
    resolved_order = sorted(
        providers, key=lambda provider: len(provider.get("dependencies") or [])
    )
    for provider in resolved_order:
        provider["build_context"] = build_contexts.get(provider["kind"], {})
        provider["source_files"] = _provider_source_fingerprints(provider["spec"], case_path)
        provider["software"] = {
            "release_version": PICURV_RELEASE_VERSION,
            "git_commit": picurv_build().get("git_commit"),
        }
        provider["spec_sha256"] = _stable_mapping_sha256({
            "kind": provider["kind"],
            "provider": provider["provider"],
            "spec": provider["spec"],
            "build_context": provider["build_context"],
            "source_files": provider["source_files"],
            "software": provider["software"],
            "dependencies": {
                name: by_kind[name].get("spec_sha256")
                for name in (provider.get("dependencies") or [])
                if name in by_kind
            },
        })
    return {
        "case_sha256": _stable_mapping_sha256(case_cfg),
        "providers": providers,
    }
 
 
def _asset_selection(graph: dict, requested=None, *, precomputable_only: bool = False) -> list:
    """!
    @brief Resolve requested asset kinds plus dependency closure.
    @param[in] graph Provider graph returned by build_case_asset_graph.
    @param[in] requested Optional iterable of requested kind names.
    @param[in] precomputable_only Exclude runtime-C providers for normal-run staging.
    @return Ordered provider list.
    """
    by_kind = {item["kind"]: item for item in graph["providers"]}
    requested_set = set(requested or by_kind)
    unknown = requested_set - set(by_kind)
    if unknown:
        raise ValueError(
            f"No configured provider exists for asset kind(s): {sorted(unknown)}. "
            f"Configured kinds: {sorted(by_kind)}."
        )
    closure = set()
 
    def add(kind):
        """!
        @brief Add one requested asset kind and its dependency closure.
        @param[in] kind Asset kind to include.
        @return None.
        """
        if kind in closure:
            return
        closure.add(kind)
        for dependency in by_kind[kind].get("dependencies", []):
            if dependency in by_kind:
                add(dependency)
 
    for kind in requested_set:
        add(kind)
    selected = [item for item in graph["providers"] if item["kind"] in closure]
    if precomputable_only:
        selected = [item for item in selected if item["execution"] == "precomputable"]
    return selected
 
 
def _asset_payload_files(build_root: str, kind: str) -> list:
    """!
    @brief Enumerate canonical files belonging to one asset kind in a build tree.
    @param[in] build_root Temporary run-like build root.
    @param[in] kind Asset kind.
    @return Absolute payload file paths.
    """
    roots = {
        "grid": ["inputs/grid", "output/analysis/metrics", "output/visualization/precompute"],
        "initial-condition": ["inputs/initial_condition", "output/analysis/spectra", "output/analysis/metrics"],
        "inlet-profiles": ["inputs/inlet_profiles"],
    }[kind]
    result = []
    for relative in roots:
        root = Path(build_root, *relative.split("/"))
        if root.is_dir():
            result.extend(str(path) for path in sorted(root.rglob("*")) if path.is_file())
    intermediate_names = {
        "grid": {"grid.generated.picgrid", "grid.converted.picgrid"},
        "initial-condition": {"initial_condition.generated.dat"},
        "inlet-profiles": set(),
    }[kind]
    return [
        path for path in dict.fromkeys(result)
        if os.path.basename(path) not in intermediate_names
    ]
 
 
def _build_selected_asset_payloads(build_root: str, case_cfg: dict, case_path: str,
                                   selected: list) -> dict:
    """!
    @brief Execute existing generators into one isolated run-like build tree.
    @param[in] build_root Temporary output root.
    @param[in] case_cfg Parsed case config.
    @param[in] case_path Owning case path.
    @param[in] selected Ordered selected providers.
    @return Asset-kind to generated file list.
    """
    ensure_run_layout(build_root)
    selected_kinds = {item["kind"] for item in selected}
    payloads = {}
 
    def fingerprint(kind):
        """!
        @brief Snapshot current payload checksums for one asset kind.
        @param[in] kind Asset kind to inspect.
        @return Absolute-path to checksum mapping.
        """
        return {
            path: _asset_file_sha256(path)
            for path in _asset_payload_files(build_root, kind)
        }
 
    def record_changes(kind, before):
        """!
        @brief Record files created or changed by one provider stage.
        @param[in] kind Asset kind whose build just completed.
        @param[in] before Pre-build checksum mapping.
        @return None.
        """
        after = fingerprint(kind)
        payloads[kind] = [
            path for path, digest in after.items()
            if before.get(path) != digest
        ]
 
    grid_cfg = case_cfg.get("grid", {}) or {}
    expected_nblk = int((case_cfg.get("models", {}) or {}).get("domain", {}).get("blocks", 1))
    staged_grid = os.path.join(build_root, "inputs", "grid", "grid.run")
    if "grid" in selected_kinds:
        before = fingerprint("grid")
        if grid_cfg.get("mode") in _FILE_BACKED_GRID_VALUES:
            grid_length_scale = input_reference_scale(("case", "grid", "source_file"),
                                                      resolve_reference_scales(case_cfg))
        if grid_cfg.get("mode") == "grid_gen":
            generated = run_grid_generator(case_path, build_root, grid_cfg, case_cfg=case_cfg)
            validate_and_nondimensionalize_picgrid(
                generated, staged_grid, grid_length_scale, expected_nblk=expected_nblk
            )
        elif grid_cfg.get("mode") == "file":
            source = _resolve_case_relative_path(
                grid_cfg.get("source_file"), os.path.dirname(os.path.abspath(case_path))
            )
            validate_and_nondimensionalize_picgrid(
                source, staged_grid, grid_length_scale, expected_nblk=expected_nblk
            )
        record_changes("grid", before)
 
    if "inlet-profiles" in selected_kinds:
        before = fingerprint("inlet-profiles")
        generate_multi_block_bcs(
            build_root, "asset-build", case_cfg,
            {"Case": case_path},
        )
        record_changes("inlet-profiles", before)
 
    if "initial-condition" in selected_kinds:
        before = fingerprint("initial-condition")
        fluid_scaling = resolve_fluid_scaling(case_cfg)
        resolved_ic = resolve_initial_condition_config(
            (case_cfg.get("properties", {}) or {}).get("initial_conditions", {}),
            validate_and_prepare_boundary_conditions(case_cfg),
            scales=fluid_scaling,
            provider_context={
                "kinematic_viscosity": fluid_scaling["nondimensional_kinematic_viscosity"]
            },
        )
        if (grid_cfg.get("mode") == "programmatic_c" and is_generated_ic_provider(resolved_ic)
                and not os.path.isfile(staged_grid)):
            # "grid" is excluded from this closure when the caller passed
            # precomputable_only=True (materialize_run_assets, staging before a solve): a
            # runtime-C grid is never itself precomputed. But the Python IC generator run
            # below is a separate process from the solver and needs real coordinates on
            # disk regardless. This bridge uses the identical formula as
            # ComputeStretchedCoord in src/grid.c, so it is guaranteed to match what the
            # solver builds moments later; it is not published as its own asset, since a
            # programmatic_c grid is never a persisted asset in its own right.
            generate_picgrid_from_programmatic_settings(
                grid_cfg.get("programmatic_settings", {}), staged_grid,
                input_reference_scale(("case", "grid", "programmatic_settings", "xMins"), fluid_scaling),
            )
        stage_initial_condition_file(build_root, case_path, resolved_ic)
        record_changes("initial-condition", before)
    return payloads
 
 
#: Largest grid, in nodes, for which a published asset carries an inline VTS preview.
#: Beyond this the ASCII payload costs more than the inspection is worth, and
#: validation.json records that it was skipped rather than silently omitting it.
ASSET_PREVIEW_NODE_LIMIT = 2_000_000
 
 
def _picgrid_geometry_summary(path: str) -> dict:
    """!
    @brief Read a canonical PICGRID and summarize what a user would want to check.
    @param[in] path Staged PICGRID file.
    @return Mapping of block dimensions, bounds, and spacing extremes.
    """
    dims = read_picgrid_header_dimensions(path)
    bounds = [[float("inf")] * 3, [float("-inf")] * 3]
    nodes = 0
    with open(path, "r", encoding="utf-8", errors="replace") as stream:
        iterator = _iter_nonempty_noncomment_lines(stream)
        # Header token, block count, and one dimension row per block.
        for _ in range(2 + len(dims)):
            next(iterator, None)
        for _lineno, line in iterator:
            parts = line.split()
            if len(parts) != 3:
                continue
            try:
                point = [float(value) for value in parts]
            except ValueError:
                continue
            nodes += 1
            for axis in range(3):
                bounds[0][axis] = min(bounds[0][axis], point[axis])
                bounds[1][axis] = max(bounds[1][axis], point[axis])
    extent = [bounds[1][axis] - bounds[0][axis] for axis in range(3)] if nodes else [0.0, 0.0, 0.0]
    return {
        "blocks": len(dims),
        "dimensions": [list(item) for item in dims],
        "total_nodes": nodes,
        "bounds_min": bounds[0] if nodes else None,
        "bounds_max": bounds[1] if nodes else None,
        "extent": extent,
    }
 
 
def _write_structured_grid_preview(picgrid_path: str, destination: str, dims) -> bool:
    """!
    @brief Write a single-block ASCII VTS preview of a staged PICGRID.
 
    @details Only the first block is written: the preview exists so a user can confirm
             the shape they configured, not to reproduce the solver's view of a
             multi-block domain.
    @param[in] picgrid_path Staged PICGRID file.
    @param[in] destination Preview path to write.
    @param[in] dims Per-block dimension triples.
    @return True when a preview was written.
    """
    if not dims:
        return False
    im, jm, km = (int(value) for value in dims[0])
    if im * jm * km > ASSET_PREVIEW_NODE_LIMIT:
        return False
    coordinates = []
    with open(picgrid_path, "r", encoding="utf-8", errors="replace") as stream:
        iterator = _iter_nonempty_noncomment_lines(stream)
        for _ in range(2 + len(dims)):
            next(iterator, None)
        for _lineno, line in iterator:
            parts = line.split()
            if len(parts) == 3:
                coordinates.append(line)
            if len(coordinates) >= im * jm * km:
                break
    if len(coordinates) < im * jm * km:
        return False
    os.makedirs(os.path.dirname(destination), exist_ok=True)
    with open(destination, "w", encoding="utf-8") as out:
        extent = f"0 {im - 1} 0 {jm - 1} 0 {km - 1}"
        out.write('<?xml version="1.0"?>\n')
        out.write('<VTKFile type="StructuredGrid" version="1.0" byte_order="LittleEndian">\n')
        out.write(f'  <StructuredGrid WholeExtent="{extent}">\n')
        out.write(f'    <Piece Extent="{extent}">\n')
        out.write('      <Points>\n')
        out.write('        <DataArray type="Float64" NumberOfComponents="3" format="ascii">\n')
        for row in coordinates:
            out.write(f"          {row}\n")
        out.write('        </DataArray>\n      </Points>\n')
        out.write('    </Piece>\n  </StructuredGrid>\n</VTKFile>\n')
    return True
 
 
def _build_asset_inspection(kind: str, build_root: str, provider: dict,
                            payload_files: list) -> dict:
    """!
    @brief Produce the inspection material published beside an asset's payload.
 
    @details Precompute exists so a user can look at a grid, field, or profile and
             change it before committing a solve. An asset that carries only opaque
             solver input cannot serve that purpose, so every published object gets a
             validation record and, where it is affordable, a preview.
    @param[in] kind Asset kind.
    @param[in] build_root Temporary build tree.
    @param[in] provider Provider metadata for the asset.
    @param[in] payload_files Absolute payload paths produced for this asset.
    @return Mapping of published inspection filename to its absolute source path.
    """
    inspection_dir = os.path.join(build_root, ".inspection")
    os.makedirs(inspection_dir, exist_ok=True)
    published = {}
    validation = {
        "asset_kind": kind,
        "provider": provider["provider"],
        "generated_at": datetime.now().astimezone().isoformat(),
        "files": [os.path.relpath(path, build_root).replace(os.sep, "/") for path in payload_files],
    }
 
    if kind == "grid":
        staged = os.path.join(build_root, "inputs", "grid", "grid.run")
        if os.path.isfile(staged):
            try:
                geometry = _picgrid_geometry_summary(staged)
                validation["geometry"] = geometry
                preview = os.path.join(inspection_dir, "preview.vts")
                if _write_structured_grid_preview(staged, preview, geometry["dimensions"]):
                    published["preview.vts"] = preview
                else:
                    validation["preview"] = (
                        "skipped: the first block exceeds "
                        f"{ASSET_PREVIEW_NODE_LIMIT} nodes"
                    )
            except (OSError, ValueError, StopIteration) as exc:
                validation["geometry_error"] = str(exc)
        generator_preview = os.path.join(
            build_root, "output", "visualization", "precompute", "grid.vts"
        )
        if os.path.isfile(generator_preview):
            published["preview.vts"] = generator_preview
            validation.pop("preview", None)
        info = os.path.join(build_root, "output", "analysis", "metrics", "grid.info")
        if os.path.isfile(info):
            published["grid.info"] = info
 
    elif kind == "initial-condition":
        # The generators name these for the run tree they were written into; the asset
        # publishes them under the names the object contract uses.
        for published_name, suffix in (
            ("summary.json", "_summary.json"), ("spectrum.csv", "_spectrum.csv"),
        ):
            for candidate in payload_files:
                base = os.path.basename(candidate)
                if base == published_name or base.endswith(suffix):
                    published[published_name] = candidate
                    break
        for candidate in payload_files:
            base = os.path.basename(candidate)
            if base.startswith(("initial_condition_plane_spectrum_", "initial_condition_line_spectrum_")) and base.endswith((".csv", ".json")):
                published[base] = candidate
        validation["fields"] = sorted(
            os.path.basename(path) for path in payload_files if path.endswith(".dat")
        )
        summary_source = published.get("summary.json")
        if summary_source:
            try:
                with open(summary_source, "r", encoding="utf-8") as stream:
                    validation["summary"] = json.load(stream)
            except (OSError, ValueError):
                pass
 
    elif kind == "inlet-profiles":
        for candidate in payload_files:
            if os.path.basename(candidate) == "profile.info":
                published["profile.info"] = candidate
        validation["profiles"] = sorted(
            os.path.basename(path) for path in payload_files
            if path.endswith(".picslice")
        )
 
    validation_path = os.path.join(inspection_dir, "validation.json")
    write_json_file(validation_path, validation)
    published["validation.json"] = validation_path
    return published
 
 
def _publish_asset_object(workspace_root: str, build_root: str, provider: dict,
                          payload_files: list) -> dict:
    """!
    @brief Publish one immutable content-addressed asset object atomically.
    @param[in] workspace_root Owning workspace.
    @param[in] build_root Temporary build root.
    @param[in] provider Provider metadata.
    @param[in] payload_files Files produced for the provider.
    @return Asset reference written to the asset set.
    """
    file_inventory = []
    for path in payload_files:
        relative = os.path.relpath(path, build_root).replace(os.sep, "/")
        file_inventory.append({
            "path": relative,
            "bytes": os.path.getsize(path),
            "sha256": _asset_file_sha256(path),
        })
    asset_id = _stable_mapping_sha256({
        "provider_spec_sha256": provider["spec_sha256"],
        "files": file_inventory,
    })
    # Identity is the payload's; inspection material describes it and must not change
    # which object a run resolves to.
    inspection = _build_asset_inspection(
        provider["kind"], build_root, provider, payload_files
    )
    kind_dir = ASSET_KIND_DIRECTORIES[provider["kind"]]
    object_root = os.path.join(workspace_root, "assets", "objects", kind_dir, asset_id)
    if not os.path.isdir(object_root):
        parent = os.path.dirname(object_root)
        os.makedirs(parent, exist_ok=True)
        temporary = tempfile.mkdtemp(prefix=f".{asset_id[:12]}-", dir=parent)
        try:
            for item, source in zip(file_inventory, payload_files):
                destination = os.path.join(temporary, "payload", *item["path"].split("/"))
                os.makedirs(os.path.dirname(destination), exist_ok=True)
                shutil.copy2(source, destination)
            for name, source in sorted(inspection.items()):
                shutil.copy2(source, os.path.join(temporary, name))
            manifest = {
                "schema_version": ASSET_MANIFEST_SCHEMA_VERSION,
                "asset_id": asset_id,
                "kind": provider["kind"],
                "provider": provider["provider"],
                "provider_execution": provider["execution"],
                "provider_spec_sha256": provider["spec_sha256"],
                "provider_spec": provider["spec"],
                "source_files": provider["source_files"],
                "software": provider["software"],
                "created_at": datetime.now().astimezone().isoformat(),
                "files": file_inventory,
                "inspection": sorted(inspection),
            }
            write_json_file(os.path.join(temporary, "asset.json"), manifest)
            try:
                os.replace(temporary, object_root)
            except OSError as exc:
                if exc.errno != errno.ENOTEMPTY and not os.path.isdir(object_root):
                    raise
        finally:
            if os.path.isdir(temporary):
                shutil.rmtree(temporary, ignore_errors=True)
    return {
        "asset_id": asset_id,
        "kind": provider["kind"],
        "provider": provider["provider"],
        "provider_spec_sha256": provider["spec_sha256"],
        "object": os.path.relpath(object_root, workspace_root).replace(os.sep, "/"),
        "files": file_inventory,
        "inspection": sorted(inspection),
    }
 
 
def _workspace_asset_set_name(workspace_root: str, case_path: str) -> str:
    """!
    @brief Return a collision-free, readable mutable asset-set name.
    @param[in] workspace_root Owning initialized workspace.
    @param[in] case_path Source case configuration path.
    @return Stable asset-set filename stem.
    """
    stem = re.sub(r"[^A-Za-z0-9_.-]+", "-", Path(case_path).stem).strip("-") or "case"
    relative = _relative_to_workspace(case_path, workspace_root) or os.path.abspath(case_path)
    digest = hashlib.sha256(str(relative).encode("utf-8")).hexdigest()[:10]
    return f"{stem}-{digest}"
 
 
def _write_workspace_asset_set(workspace_root: str, case_path: str, graph: dict,
                               references: dict) -> str:
    """!
    @brief Atomically update the named asset set and workspace asset catalog.
    @param[in] workspace_root Owning workspace.
    @param[in] case_path Source case YAML.
    @param[in] graph Complete provider graph.
    @param[in] references Newly published or reused asset references.
    @return Asset-set YAML path.
    """
    name = _workspace_asset_set_name(workspace_root, case_path)
    set_path = os.path.join(workspace_root, "assets", "sets", f"{name}.yml")
    existing = read_yaml_file(set_path) if os.path.isfile(set_path) else {}
    assets = dict(existing.get("assets") or {})
    assets.update(references)
    payload = {
        "schema_version": ASSET_LOCK_SCHEMA_VERSION,
        "name": name,
        "case": os.path.relpath(case_path, workspace_root).replace(os.sep, "/"),
        "case_sha256": graph["case_sha256"],
        "updated_at": datetime.now().astimezone().isoformat(),
        "assets": assets,
        "runtime_providers": {
            item["kind"]: {
                "provider": item["provider"],
                "provider_spec_sha256": item["spec_sha256"],
            }
            for item in graph["providers"] if item["execution"] == "runtime-c"
        },
    }
    write_yaml_file(set_path, payload)
    catalog_path = os.path.join(workspace_root, "assets", "catalog.yml")
    catalog = read_yaml_file(catalog_path) if os.path.isfile(catalog_path) else {
        "schema_version": 1, "objects": {}
    }
    objects = catalog.setdefault("objects", {})
    for reference in references.values():
        objects[reference["asset_id"]] = {
            "kind": reference["kind"],
            "provider": reference["provider"],
            "object": reference["object"],
        }
    write_yaml_file(catalog_path, catalog)
    return set_path
 
 
def precompute_case_assets(workspace_root: str, case_cfg: dict, case_path: str,
                           requested=None, precomputable_only: bool = False) -> dict:
    """!
    @brief Build and publish a selected deterministic asset dependency closure.
    @param[in] workspace_root Owning workspace.
    @param[in] case_cfg Parsed case configuration.
    @param[in] case_path Source case path.
    @param[in] requested Requested asset kinds, or all configured providers.
    @param[in] precomputable_only Drop runtime-C dependencies from the closure instead of
                                  refusing. For internal run-staging only: a run legitimately
                                  depends on a runtime-C grid that its own solver builds
                                  moments later, so its presence in the dependency closure is
                                  expected there, not an error. The standalone `picurv
                                  precompute` command leaves this False, since nothing will
                                  ever build a runtime-C provider in that context.
    @return Provider graph, selected providers, references, and asset-set path.
    """
    enforce_workspace_version(workspace_root)
    graph = build_case_asset_graph(case_cfg, case_path)
    selected = _asset_selection(graph, requested, precomputable_only=precomputable_only)
    if not precomputable_only:
        runtime = [item for item in selected if item["execution"] == "runtime-c"]
        if runtime:
            details = ", ".join(f"{item['kind']}={item['provider']}" for item in runtime)
            raise ValueError(
                "Precompute is atomic and cannot execute simulator-runtime providers. "
                f"Selected dependency graph requires C generation: {details}. "
                "Use --only to select an independent precomputable subset, or run the case; "
                "the simulator will report each runtime provider before generation."
            )
    if not selected:
        raise ValueError("The selected case has no precomputable providers.")
    staging_parent = os.path.join(workspace_root, "assets")
    os.makedirs(staging_parent, exist_ok=True)
    build_root = tempfile.mkdtemp(prefix=".precompute-", dir=staging_parent)
    references = {}
    try:
        payloads = _build_selected_asset_payloads(build_root, case_cfg, case_path, selected)
        for provider in selected:
            files = payloads.get(provider["kind"], [])
            if not files:
                raise ValueError(
                    f"Provider {provider['kind']}={provider['provider']} produced no files."
                )
            references[provider["kind"]] = _publish_asset_object(
                workspace_root, build_root, provider, files
            )
    finally:
        shutil.rmtree(build_root, ignore_errors=True)
    set_path = _write_workspace_asset_set(workspace_root, case_path, graph, references)
    return {"graph": graph, "selected": selected, "assets": references, "set_path": set_path}
 
 
def _workspace_asset_set_path(workspace_root: str, case_path: str) -> str:
    """!
    @brief Return the mutable asset-set pointer associated with a case config name.
    @param[in] workspace_root Owning workspace.
    @param[in] case_path Source case path.
    @return Absolute asset-set YAML path.
    """
    name = _workspace_asset_set_name(workspace_root, case_path)
    return os.path.join(workspace_root, "assets", "sets", f"{name}.yml")
 
 
def _find_stored_asset(workspace_root: str, provider: dict):
    """!
    @brief Find a published object built from exactly this provider's inputs.
    @details Asset sets are named after case files, so they miss an object another case
             file already built from identical inputs. The provider identity is what the
             object was built from, so any published object carrying it is reusable; the
             lowest asset id is taken so repeated lookups agree. Payload checksums are
             verified when the object is materialized, not here.
    @param[in] workspace_root Owning workspace.
    @param[in] provider Provider entry from build_case_asset_graph().
    @return Asset reference in the shape _publish_asset_object() returns, or None.
    """
    kind_dir = ASSET_KIND_DIRECTORIES.get(provider["kind"])
    if not kind_dir:
        return None
    objects_root = os.path.join(workspace_root, "assets", "objects", kind_dir)
    if not os.path.isdir(objects_root):
        return None
    for asset_id in sorted(os.listdir(objects_root)):
        object_root = os.path.join(objects_root, asset_id)
        manifest = _read_json_if_exists(os.path.join(object_root, "asset.json"))
        if not (isinstance(manifest, dict)
                and manifest.get("schema_version") == ASSET_MANIFEST_SCHEMA_VERSION
                and manifest.get("asset_id") == asset_id
                and manifest.get("kind") == provider["kind"]
                and manifest.get("provider_spec_sha256") == provider["spec_sha256"]):
            continue
        return {
            "asset_id": asset_id,
            "kind": provider["kind"],
            "provider": manifest.get("provider", provider["provider"]),
            "provider_spec_sha256": provider["spec_sha256"],
            "object": os.path.relpath(object_root, workspace_root).replace(os.sep, "/"),
            "files": manifest.get("files", []),
            "inspection": manifest.get("inspection", []),
        }
    return None
 
 
def plan_run_assets(case_cfg: dict, case_path: str, skip_kinds=()) -> dict:
    """!
    @brief Plan reuse/build/runtime actions for all configured run providers.
    @param[in] case_cfg Parsed case configuration.
    @param[in] case_path Source case path.
    @param[in] skip_kinds Kinds the run will not read; planned as `unused`, never built.
    @return Workspace, graph, set path, and per-provider actions.
    """
    workspace_root = find_workspace_root(case_path)
    graph = build_case_asset_graph(case_cfg, case_path)
    asset_set = {}
    set_path = None
    if workspace_root:
        set_path = _workspace_asset_set_path(workspace_root, case_path)
        if os.path.isfile(set_path):
            asset_set = read_yaml_file(set_path)
    refs = asset_set.get("assets", {}) if isinstance(asset_set, dict) else {}
    actions = []
    for provider in graph["providers"]:
        reference = refs.get(provider["kind"]) if isinstance(refs, dict) else None
        matches = bool(
            isinstance(reference, dict)
            and reference.get("provider_spec_sha256") == provider["spec_sha256"]
            and workspace_root
            and os.path.isfile(os.path.join(
                workspace_root, reference.get("object", ""), "asset.json"
            ))
        )
        adopted = False
        if provider["kind"] in skip_kinds:
            actions.append({**provider, "action": "unused", "reference": None, "adopted": False})
            continue
        if not matches and workspace_root and provider["execution"] != "runtime-c":
            # The asset set is named after the case file, so a copied or renamed case
            # has none; identity is the provider's, so an object built for another case
            # file with the same inputs is the same asset.
            reference = _find_stored_asset(workspace_root, provider)
            matches = adopted = reference is not None
        if provider["execution"] == "runtime-c":
            action = "runtime-c"
        elif matches:
            action = "reuse"
        else:
            action = "build"
        actions.append({**provider, "action": action, "reference": reference if matches else None,
                        "adopted": adopted})
    return {
        "workspace_root": workspace_root,
        "graph": graph,
        "asset_set_path": set_path,
        "actions": actions,
    }
 
 
def _materialize_asset_file(source: str, destination: str) -> str:
    """!
    @brief Expose one immutable shared-asset file through reflink, hardlink, or copy.
    @param[in] source Immutable asset payload file.
    @param[in] destination Run-local destination.
    @return Materialization mode used.
    """
    os.makedirs(os.path.dirname(destination), exist_ok=True)
    temporary = f"{destination}.tmp.{os.getpid()}"
    try:
        cp = shutil.which("cp")
        if cp:
            result = subprocess.run(
                [cp, "--reflink=always", "--preserve=mode,timestamps", source, temporary],
                text=True, capture_output=True, check=False,
            )
            if result.returncode == 0:
                os.replace(temporary, destination)
                return "reflink"
            if os.path.lexists(temporary):
                os.remove(temporary)
        try:
            os.link(source, temporary)
            os.replace(temporary, destination)
            return "hardlink"
        except OSError:
            if os.path.lexists(temporary):
                os.remove(temporary)
        shutil.copy2(source, temporary)
        os.replace(temporary, destination)
        return "copy"
    finally:
        if os.path.lexists(temporary):
            os.remove(temporary)
 
 
def materialize_run_assets(run_dir: str, case_cfg: dict, case_path: str,
                           require_precomputed: bool = False,
                           fetch_missing: bool = False, skip_kinds=()) -> dict:
    """!
    @brief Resolve/build workspace assets and write the exact run input lock.
    @param[in] run_dir Run receiving immutable input exposures.
    @param[in] case_cfg Parsed case config.
    @param[in] case_path Source case path.
    @param[in] require_precomputed Refuse any missing deterministic asset.
    @param[in] fetch_missing Request remote fetch before local build.
    @param[in] skip_kinds Kinds the run will not read (see unused_asset_kinds()).
    @return Written lock mapping, or a standalone-provider summary outside a workspace.
    """
    plan = plan_run_assets(case_cfg, case_path, skip_kinds)
    workspace_root = plan["workspace_root"]
    if not workspace_root:
        return {
            "schema_version": ASSET_LOCK_SCHEMA_VERSION,
            "workspace": None,
            "assets": {},
            "runtime_providers": {
                item["kind"]: item["provider"] for item in plan["actions"]
                if item["execution"] == "runtime-c"
            },
        }
    enforce_workspace_version(workspace_root)
    missing = [item for item in plan["actions"] if item["action"] == "build"]
    if missing and fetch_missing:
        # Storage imports this module indirectly, so remote asset recovery is routed
        # through a late import that cannot create a module cycle at startup.
        try:
            from .storage import restore_missing_workspace_assets
        except ImportError:
            restore_missing_workspace_assets = getattr(
                _storage_module, "restore_missing_workspace_assets", None
            )
        restored = restore_missing_workspace_assets(
            workspace_root, [item["spec_sha256"] for item in missing]
        ) if restore_missing_workspace_assets else {}
        if restored:
            recovered_refs = {
                item["kind"]: restored[item["spec_sha256"]]
                for item in missing if item["spec_sha256"] in restored
            }
            if recovered_refs:
                _write_workspace_asset_set(
                    workspace_root, case_path, plan["graph"], recovered_refs
                )
            plan = plan_run_assets(case_cfg, case_path, skip_kinds)
            missing = [item for item in plan["actions"] if item["action"] == "build"]
    if missing and require_precomputed:
        names = ", ".join(f"{item['kind']}={item['provider']}" for item in missing)
        raise ValueError(
            f"Required precomputed asset(s) are missing or stale: {names}. "
            f"Run 'picurv precompute --case {case_path} --only "
            + ",".join(item["kind"] for item in missing) + "'."
        )
    if missing:
        precompute_case_assets(
            workspace_root, case_cfg, case_path,
            requested=[item["kind"] for item in missing],
            precomputable_only=True,
        )
        plan = plan_run_assets(case_cfg, case_path, skip_kinds)
        still_missing = [item for item in plan["actions"] if item["action"] == "build"]
        if still_missing:
            raise ValueError(
                "Asset generation completed without satisfying: "
                + ", ".join(item["kind"] for item in still_missing)
            )
 
    adopted = {
        item["kind"]: item["reference"] for item in plan["actions"] if item.get("adopted")
    }
    if adopted:
        # Found by provider identity rather than through this case's own set; record it
        # there so the next run of this case file resolves it directly.
        _write_workspace_asset_set(workspace_root, case_path, plan["graph"], adopted)
    assets = {}
    for item in plan["actions"]:
        reference = item.get("reference")
        if item["action"] != "reuse" or not isinstance(reference, dict):
            continue
        object_root = os.path.join(workspace_root, reference["object"])
        manifest = _read_json_if_exists(os.path.join(object_root, "asset.json"))
        if not isinstance(manifest, dict) or manifest.get("asset_id") != reference.get("asset_id"):
            raise ValueError(f"Asset object is missing or invalid: {object_root}")
        exposed = []
        for file_info in manifest.get("files", []):
            relative = file_info["path"]
            source = os.path.join(object_root, "payload", *relative.split("/"))
            if _asset_file_sha256(source) != file_info.get("sha256"):
                raise ValueError(f"Asset payload checksum mismatch: {source}")
            destination = os.path.join(run_dir, *relative.split("/"))
            mode = _materialize_asset_file(source, destination)
            exposed.append({"path": relative, "mode": mode, "sha256": file_info["sha256"]})
        assets[item["kind"]] = {**reference, "exposed": exposed}
        print(f"[INFO] Asset {item['kind']}: reuse {reference['asset_id']}")
    runtime_providers = {
        item["kind"]: {
            "provider": item["provider"],
            "provider_spec_sha256": item["spec_sha256"],
        }
        for item in plan["actions"]
        if item["execution"] == "runtime-c" and item["action"] != "unused"
    }
    for kind, provider in runtime_providers.items():
        print(f"[INFO] Runtime provider {kind}: {provider['provider']} (generated by simulator)")
    lock = {
        "schema_version": ASSET_LOCK_SCHEMA_VERSION,
        "workspace": workspace_root,
        "case_sha256": plan["graph"]["case_sha256"],
        "created_at": datetime.now().astimezone().isoformat(),
        "assets": assets,
        "runtime_providers": runtime_providers,
    }
    write_yaml_file(os.path.join(run_dir, "inputs", "assets.lock.yml"), lock)
    write_software_lock(run_dir)
    return lock
 
 
def precompute_workflow(args):
    """!
    @brief Resolve, preflight, and atomically publish reusable workspace assets.
    @param[in] args Parsed precompute command arguments.
    """
    case_path = os.path.abspath(args.case)
    workspace_root = find_workspace_root(case_path, os.getcwd())
    if not workspace_root:
        raise ValueError(
            "Precompute requires an initialized PICurv workspace. Run 'picurv init ...', "
            "then use its config/case.yml."
        )
    case_cfg = read_yaml_file(case_path)
    raw_only = getattr(args, "only", None)
    requested = None
    if raw_only and str(raw_only).strip().lower() != "all":
        requested = [token.strip() for token in str(raw_only).split(",") if token.strip()]
    graph = build_case_asset_graph(case_cfg, case_path)
    selected = _asset_selection(graph, requested)
    print(f"[INFO] Workspace : {workspace_root}")
    print(f"[INFO] Case      : {os.path.relpath(case_path, workspace_root)}")
    print("[INFO] Asset dependency plan:")
    for provider in selected:
        dependencies = ",".join(provider.get("dependencies", [])) or "none"
        print(
            f"  - {provider['kind']}: {provider['provider']} "
            f"[{provider['execution']}], dependencies={dependencies}"
        )
    result = precompute_case_assets(workspace_root, case_cfg, case_path, requested=requested)
    for kind, reference in sorted(result["assets"].items()):
        print(f"[SUCCESS] {kind}: {reference['asset_id']} ({reference['object']})")
    print(f"[SUCCESS] Asset set: {os.path.relpath(result['set_path'], workspace_root)}")
 
def run_workflow(args):
    """!
    @brief Main orchestrator for the 'run' command (local and Slurm modes).
    @param[in] args Command-line style argument list supplied to the function.
    """
    if getattr(args, "dry_run", False):
        plan = build_run_dry_plan(args)
        render_run_dry_plan(plan, output_format=getattr(args, "output_format", "text"))
        if plan.get("blocking"):
            sys.exit(1)
        return
 
    run_dir = None
    run_id = None
    output_dir_abs = None
    # A post-only invocation never resolves a restart source, so this stays None and
    # `build_run_manifest()` preserves whatever lineage the run was created with.
    run_lineage = None
    statistics_output_paths = []
    workflow_start = time.time()
    stages_completed = []
    configs = None
    submission_meta = {"launch_mode": "local", "no_submit": bool(args.no_submit), "stages": {}}
 
    cluster_mode = bool(getattr(args, "cluster", None))
    cluster_cfg = None
    cluster_path = None
    solver_num_procs_effective = args.num_procs
    post_num_procs_effective = args.num_procs
 
    if cluster_mode:
        cluster_path = os.path.abspath(args.cluster)
        cluster_cfg = read_yaml_file(cluster_path)
        validate_cluster_config(cluster_cfg, cluster_path)
        scheduler_type = str(cluster_cfg.get("scheduler", {}).get("type", "slurm")).lower()
        if args.scheduler and args.scheduler.lower() != scheduler_type:
            emit_structured_error(
                ERROR_CODE_CFG_INCONSISTENT_COMBO, key="scheduler.type", file_path=cluster_path,
                message=f"--scheduler={args.scheduler} does not match cluster.yml scheduler.type={scheduler_type}.",
                hint="Omit --scheduler, or give the scheduler cluster.yml names.",
            )
            sys.exit(1)
        if scheduler_type != "slurm":
            emit_structured_error(
                ERROR_CODE_CFG_INVALID_VALUE, key="scheduler.type", file_path=cluster_path,
                message=f"Unsupported scheduler '{scheduler_type}'. Only Slurm is supported.",
                hint="Set scheduler.type: slurm in cluster.yml.",
            )
            sys.exit(1)
        cluster_tasks = get_cluster_total_tasks(cluster_cfg)
        if (args.solve or args.post_process) and args.num_procs not in (1, cluster_tasks):
            fail_cli_usage(
                "In cluster mode, --num-procs must be "
                f"1 (auto) or exactly nodes*ntasks_per_node ({cluster_tasks}).",
                hint="Omit -n to use the task count cluster.yml sets.",
            )
        if args.solve:
            solver_num_procs_effective = cluster_tasks
        if args.post_process:
            post_num_procs_effective = cluster_tasks
        submission_meta["launch_mode"] = "slurm"
        submission_meta["cluster_config"] = cluster_path
        submission_meta["no_submit"] = bool(args.no_submit)
        if args.solve and args.post_process:
            print(
                f"[INFO] Cluster mode enabled (Slurm). Solver and post stages use "
                f"{solver_num_procs_effective} MPI tasks from cluster.yml."
            )
        elif args.solve:
            print(f"[INFO] Cluster mode enabled (Slurm). Solver uses {solver_num_procs_effective} MPI tasks from cluster.yml.")
        else:
            print(f"[INFO] Cluster mode enabled (Slurm). Post stage uses {post_num_procs_effective} MPI tasks from cluster.yml.")
 
    # --- Guard: restart flags without --solve ---
    if not args.solve:
        if getattr(args, 'restart_from', None):
            print("[WARNING] --restart-from has no effect without --solve and will be ignored.", file=sys.stderr)
        if getattr(args, 'continue_run', False):
            print("[WARNING] --continue only extends a solve in place and is ignored here. "
                  "Post-processing always skips steps whose output is up to date; drop "
                  "--continue from post-only commands.", file=sys.stderr)
 
    # --- Stage 1: Solver (if requested) ---
    if args.solve:
        case_input_path = os.path.abspath(args.case)
        workspace_root = find_workspace_root(case_input_path, args.solver, args.monitor, os.getcwd())
        if workspace_root:
            enforce_workspace_version(workspace_root)
            enforce_reproducibility_policy(workspace_root)
        walltime_guard_policy = resolve_walltime_guard_policy(cluster_cfg) if cluster_mode else None
        configs = {
            'case': read_yaml_file(args.case), 'case_path': case_input_path,
            'solver': read_yaml_file(args.solver), 'solver_path': os.path.abspath(args.solver),
            'monitor': read_yaml_file(args.monitor), 'monitor_path': os.path.abspath(args.monitor),
            'walltime_guard_policy': walltime_guard_policy,
            'statistics_state': getattr(args, "statistics_state", None) or "reset",
            'decomposition': getattr(args, "decomposition", None),
            'cluster_cfg': cluster_cfg if cluster_mode else None,
        }
 
        print("\n[INFO] Validating configuration files...")
        validate_simulation_configs(
            configs['case'], configs['solver'], configs['monitor'],
            args.case, args.solver, args.monitor,
            restart_source_given=bool(getattr(args, 'restart_from', None) or getattr(args, 'continue_run', False)),
        )
        print("[SUCCESS] All configuration files passed validation.\n")
 
        continue_mode = getattr(args, 'continue_run', False)
 
        if continue_mode:
            if not args.run_dir:
                fail_cli_usage(RESTART_RUN_DIR_REQUIRED_MESSAGE)
            run_dir = os.path.abspath(args.run_dir)
            if not os.path.isdir(run_dir):
                emit_structured_error(
                    ERROR_CODE_CFG_FILE_NOT_FOUND,
                    key="run-dir",
                    file_path=run_dir,
                    message="Specified run directory not found.",
                )
                sys.exit(1)
            adopt_relocated_artifact(run_dir)
            run_id = os.path.basename(run_dir)
        else:
            runs_root = workspace_artifact_root(workspace_root, "runs")
            run_id = allocate_generated_run_id(
                runs_root, configs["case"], configs["case_path"]
            )
            run_dir = os.path.join(runs_root, run_id)
 
        if workspace_root and os.path.commonpath([os.path.abspath(run_dir), workspace_root]) != workspace_root:
            fail_cli_usage("A workspace run directory must remain below the owning workspace.")
        if not continue_mode and os.path.exists(run_dir):
            raise ValueError(f"Generated run directory already exists: {run_dir}")
        ensure_run_layout(run_dir)
        # Checked after the skeleton exists so a resumed run is judged on what is
        # actually there, and before any stage writes into it.
        enforce_run_directory_structure(run_dir)
 
        # Captured before restart resolution, which materializes the checkpoint it reads.
        staged_records = (capture_continuation_records(run_dir, resolve_run_restart_dir(run_dir, configs["monitor"]))
                          if continue_mode else None)
        try:
            resolved_restart_source_dir, is_continue, run_lineage = resolve_restart_source(
                args, configs["case"], configs["solver"], configs["monitor"], run_dir
            )
            select_run_petsc_index_bytes(args, configs["case"], configs["case_path"], configs["monitor"],
                                         resolved_restart_source_dir)
        except ValueError as e:
            # Restart resolution is the first thing that can refuse a run, and the
            # skeleton is already on disk. Leaving it behind puts an empty directory in
            # runs/ that is indistinguishable from a real run to `ls`, to storage
            # status, and to anyone browsing the workspace, once per refused attempt.
            discard_unused_run_directory(run_dir, created=not continue_mode)
            emit_structured_error(
                ERROR_CODE_CFG_INCONSISTENT_COMBO,
                key="restart",
                file_path=args.case,
                message=str(e),
                hint=_STORAGE_RESTORE_HINT if isinstance(e.__cause__, StorageError) else _RESTART_HINT,
            )
            sys.exit(1)
 
        config_dir = os.path.join(run_dir, "config")
        if continue_mode:
            print(f"[INFO] Continuing in existing run directory: {os.path.relpath(run_dir)}")
        else:
            print(f"[INFO] Created new self-contained run directory: {os.path.relpath(run_dir)}")
 
        # Read before staging, which rewrites a continuation's own grid inputs.
        source_run_dir = run_dir if is_continue else (
            os.path.join(workspace_root or "", run_lineage["parent_path"]) if run_lineage else None)
        source_grid_inputs = None
        if source_run_dir and os.path.isdir(source_run_dir):
            source_case_path = load_active_run_configuration(source_run_dir).get("case")
            if source_case_path and os.path.isfile(source_case_path):
                source_grid_inputs = restart_grid_inputs(source_run_dir, read_yaml_file(source_case_path))
        active_config = snapshot_run_configuration(
            run_dir,
            {
                "case": args.case,
                "solver": args.solver,
                "monitor": args.monitor,
                "cluster": cluster_path if cluster_mode else None,
            },
            continuation=continue_mode,
        )
        # Pinned before the asset lock and manifest are written, so both record the
        # executables this run will launch rather than the installation's.
        had_pinned_executables = bool(load_run_executables(run_dir))
        record_run_petsc_index_bytes(run_dir)
        try:
            apply_run_executable_pinning(run_dir, active_config["revision"], args, workspace_root)
        except ValueError as exc:
            discard_unused_run_directory(run_dir, created=not continue_mode)
            print(f"[FATAL] {exc}", file=sys.stderr)
            sys.exit(1)
        try:
            asset_lock = materialize_run_assets(
                run_dir,
                configs["case"],
                configs["case_path"],
                require_precomputed=bool(getattr(args, "require_precomputed", False)),
                fetch_missing=bool(getattr(args, "fetch_missing", False)),
                skip_kinds=unused_asset_kinds(configs["case"], configs["solver"]),
            )
        except ValueError as exc:
            discard_unused_run_directory(run_dir, created=not continue_mode)
            print(f"[FATAL] {exc}", file=sys.stderr)
            sys.exit(1)
        # Publish identity and lineage before either executable starts.  Besides making
        # a staged run self-describing, this lets a dependent post job resolve branch
        # ownership even though the interactive conductor has already exited.
        write_json_file(
            os.path.join(run_dir, "manifest.json"),
            build_run_manifest(
                run_dir,
                run_id,
                workspace_root=workspace_root,
                launch_mode="slurm" if cluster_mode else "local",
                num_procs=solver_num_procs_effective,
                post_num_procs=post_num_procs_effective,
                stages_requested={"solve": True, "post_process": bool(args.post_process)},
                inputs={
                    "case": _relative_to_workspace(args.case, workspace_root),
                    "solver": _relative_to_workspace(args.solver, workspace_root),
                    "monitor": _relative_to_workspace(args.monitor, workspace_root),
                },
                asset_lock=asset_lock,
                lineage=run_lineage,
            ),
        )
 
        print("\n" + "="*25 + " SOLVER STAGE " + "="*25)
        source_files = {'Case': args.case, 'Solver': args.solver, 'Monitor': args.monitor}
        generated_config_dir = (
            config_dir if active_config["revision"] == "initial"
            else os.path.join(config_dir, "history", active_config["revision"])
        )
        monitor_files = prepare_monitor_files(
            run_dir, run_id, configs['monitor'], source_files,
            config_dir=generated_config_dir,
        )
        if resolved_restart_source_dir:
            print(f"[INFO] Restart source: {resolved_restart_source_dir}")
        if is_continue:
            print("[INFO] Continue mode: logs will be appended, not overwritten.")
        control_file = generate_solver_control_file(
            run_dir,
            run_id,
            configs,
            solver_num_procs_effective,
            monitor_files,
            restart_source_dir=resolved_restart_source_dir,
            continue_mode=is_continue,
            config_dir=generated_config_dir,
        )
        active_config = archive_active_generated_configuration(
            run_dir,
            [
                control_file,
                monitor_files.get("whitelist"),
                monitor_files.get("profile"),
                *glob.glob(os.path.join(generated_config_dir, "bcs*.run")),
            ],
        )
        control_file = load_active_run_configuration(run_dir).get("control", control_file)
 
        solver_exe = run_executable_path(run_dir, "simulator")
        # Staging is the last point before the binary's identity becomes the one written
        # into this run's checkpoints, so a stale build is worth saying out loud here.
        # A run kept on its earlier pin is meant to differ from the source, so it is not.
        if not had_pinned_executables or getattr(args, "pin_executables", None) is True:
            warn_on_stale_runtime_binaries(runtime_build_identities(run_dir=run_dir))
        solver_args = build_petsc_diagnostics_args(configs["monitor"], run_dir, "Solver") + ["-control_file", control_file]
        if source_grid_inputs is not None:
            warn_on_restart_grid_change(source_grid_inputs, restart_grid_inputs(run_dir, configs["case"]))
        carries_statistics = is_continue or str(configs.get("statistics_state", "reset")).lower() == "carry"
        if carries_statistics and normalize_field_statistics_config(configs["monitor"])["enabled"]:
            refusal = check_restart_continuation(solver_exe, solver_args, run_dir,
                                                 config_search_anchor=configs["case_path"])
            if refusal:
                if continue_mode:
                    restore_continuation_records(run_dir, staged_records, active_config["revision"])
                    undone = f"{os.path.relpath(run_dir)} is left as it was"
                else:
                    discard_unused_run_directory(run_dir, created=True, staged=True)
                    undone = "the branch run directory was removed"
                print(f"[FATAL] This restart cannot continue its statistics windows: {refusal}\n"
                      f"        Nothing was launched or submitted, and {undone}.", file=sys.stderr)
                sys.exit(1)
        if cluster_mode:
            scheduler_dir = os.path.join(run_dir, "scheduler")
            solver_script = os.path.join(scheduler_dir, "solver.sbatch")
            solver_log = os.path.join(scheduler_dir, "solver_%j.out")
            solver_err = os.path.join(scheduler_dir, "solver_%j.err")
            solver_cmd = build_cluster_launch_command(
                cluster_cfg,
                solver_exe,
                solver_args,
                config_search_anchor=args.case,
                extra_search_anchors=[cluster_path],
            )
            render_slurm_script(
                solver_script,
                f"{run_id}_solve",
                cluster_cfg,
                solver_cmd,
                run_dir,
                solver_log,
                solver_err,
                env_vars={"LOG_LEVEL": configs['monitor'].get('logging', {}).get('verbosity', 'INFO').upper()},
                shell_env_vars=build_walltime_guard_exports(cluster_cfg),
                identity_check=(solver_exe, read_binary_build_identity(solver_exe).get("version_line"),
                                "simulator" in load_run_executables(run_dir)),
            )
            submission_meta["stages"]["solve"] = {
                "script": solver_script,
                "submitted": False,
                "num_procs_effective": solver_num_procs_effective,
                "decomposition": _decomposition_record(configs.get("decomposition_resolved")),
            }
            print(f"[SUCCESS] Generated solver Slurm script: {os.path.relpath(solver_script)}")
            if not args.no_submit:
                submit_info = submit_sbatch(solver_script)
                submission_meta["stages"]["solve"].update(submit_info)
                submission_meta["stages"]["solve"]["submitted"] = True
                print(f"[SUCCESS] Submitted solver job: {submit_info['job_id']}")
            stages_completed.append('solve')
        else:
            command = build_local_launch_command(
                solver_exe,
                solver_args,
                solver_num_procs_effective,
                config_search_anchor=configs["case_path"],
            )
            solver_log = os.path.join("scheduler", f"{run_id}_solver.log")
            submission_meta["stages"]["solve"] = {
                "command": command,
                "command_string": format_command_for_display(command),
                "log_file": solver_log,
                "submitted": False,
                "num_procs_effective": solver_num_procs_effective,
                "decomposition": _decomposition_record(configs.get("decomposition_resolved")),
            }
            if args.no_submit:
                print(f"[SUCCESS] Staged local solve stage; run it with "
                      f"'picurv submit --run-dir {os.path.relpath(run_dir)}'.")
            else:
                try:
                    with runtime_stage_lock(run_dir, "solver"):
                        execute_command(command, run_dir, solver_log, configs['monitor'])
                except StorageError as exc:
                    print(f"[FATAL] {exc}", file=sys.stderr)
                    sys.exit(1)
                submission_meta["stages"]["solve"]["submitted"] = True
                submission_meta["stages"]["solve"]["executed"] = True
                submission_meta["stages"]["solve"]["completed_at"] = datetime.now().isoformat()
            stages_completed.append('solve')
 
    # --- Stage 2: Post-Processing (if requested) ---
    if args.post_process:
        if not args.solve and getattr(args, "pin_executables", None) is not None:
            fail_cli_usage(
                "--pin-executables and --no-pin-executables apply when the solve stage is staged.",
                hint="Post-processing launches the postprocessor the run is pinned to, or the "
                     "installation's when the run is not pinned.",
            )
        if args.run_dir:
            run_dir = os.path.abspath(args.run_dir)
            if not os.path.isdir(run_dir):
                emit_structured_error(ERROR_CODE_CFG_FILE_NOT_FOUND, key="run_dir", file_path=run_dir,
                                      message="Run directory not found.")
                sys.exit(1)
            print(f"[INFO] Operating on existing run directory: {os.path.relpath(run_dir)}")
            adopt_relocated_artifact(run_dir)
            enforce_run_directory_structure(run_dir)
            run_id = read_artifact_identity(run_dir)["run_id"]
 
        print("\n" + "="*20 + " POST-PROCESSING STAGE " + "="*20)
        config_dir = os.path.join(run_dir, "config")
        case_path, monitor_path, solver_control_path = auto_identify_run_inputs(config_dir)
 
        if not all([case_path, monitor_path, solver_control_path]):
            print(f"[FATAL] Could not automatically identify required config files in {config_dir}", file=sys.stderr)
            if not case_path:
                print("         - No 'case' file found (expected 'models' + 'boundary_conditions').", file=sys.stderr)
            if not monitor_path:
                print("         - No 'monitor' file found (expected 'io' + 'logging').", file=sys.stderr)
            if not solver_control_path:
                print("         - No '.control' file found.", file=sys.stderr)
            sys.exit(1)
 
        print(f"[INFO] Auto-identified Case file:    {os.path.basename(case_path)}")
        print(f"[INFO] Auto-identified Monitor file: {os.path.basename(monitor_path)}")
 
        case_cfg = read_yaml_file(case_path)
        monitor_cfg = read_yaml_file(monitor_path)
        post_cfg = read_yaml_file(args.post)
 
        print("[INFO] Validating post-processing configuration...")
        validate_post_config(post_cfg, args.post, monitor_cfg, case_cfg)
        print("[SUCCESS] Post-processing configuration passed validation.\n")
 
        post_cfg, recipe_id = apply_canonical_post_paths(post_cfg, run_dir)
        for relative in (
            post_cfg["_picurv_paths"]["visualization"],
            post_cfg["_picurv_paths"]["statistics"],
            post_cfg["_picurv_paths"]["spectra"],
        ):
            os.makedirs(os.path.join(run_dir, relative), exist_ok=True)
        archived_post_path = os.path.join(get_post_recipe_root(run_dir, post_cfg), "post.yml")
        os.makedirs(os.path.dirname(archived_post_path), exist_ok=True)
        if os.path.abspath(args.post) != os.path.abspath(archived_post_path):
            shutil.copy2(args.post, archived_post_path)
 
        solver_sources_deferred = bool(args.solve and (cluster_mode or args.no_submit))
        recompute = bool(getattr(args, 'recompute_post', False))
        post_stages = resolve_post_stage_selection(getattr(args, 'only', None))
        try:
            if not args.solve:
                select_existing_run_petsc_index_bytes(run_dir, args)
            post_exe = run_executable_path(run_dir, "postprocessor")
        except ValueError as exc:
            post_exe = None
            post_exe_error = exc
        post_plan = build_post_execution_plan(
            run_dir,
            run_id,
            case_cfg,
            monitor_cfg,
            post_cfg,
            recompute=recompute,
            allow_source_frontier_scan=not solver_sources_deferred,
            postprocessor_sha=_file_sha256(post_exe) if post_exe else None,
        )
        # Only the checkpoints of steps that need work must be local: a step whose output
        # is up to date is not read, so an offload that archived it does not block the run.
        needed_steps = post_plan['steps_to_process'] + post_plan['steps_unavailable']
        if 'fields' in post_stages and not solver_sources_deferred and needed_steps:
            try:
                require_storage_payload_local(
                    run_dir, "post-processing", checkpoints=needed_steps,
                )
            except StorageError as exc:
                emit_structured_error(
                    ERROR_CODE_CFG_FILE_NOT_FOUND,
                    key="storage",
                    file_path=run_dir,
                    message=str(exc),
                    hint=_STORAGE_RESTORE_HINT,
                )
                sys.exit(1)
 
        post_finalize_command = (
            build_post_finalize_command(run_dir, archived_post_path, post_cfg, post_stages)
            if 'fields' in post_stages else []
        )
        if post_stages != set(POST_STAGE_NAMES):
            print(f"[INFO] Post stages selected: {','.join(sorted(post_stages))}")
            # A stage the recipe gives no tasks has nothing to do; say so rather than
            # report success for work that was never possible.
            for stage, tasks in (("spectra", normalize_post_spectra_config(post_cfg)["tasks"]),
                                 ("reducers", normalize_post_reducers_config(post_cfg)["tasks"])):
                if stage in post_stages and not tasks:
                    print(f"[WARNING] --only selects {stage}, but {args.post} defines no {stage} "
                          "tasks; nothing is measured for it.", file=sys.stderr)
 
        print(f"[INFO] Post recipe: {recipe_id}")
        print(f"[INFO] Post-processor source data: {os.path.relpath(post_plan['source_data_directory'])}")
        if post_plan['source_frontier_deferred']:
            print("[INFO] Source checkpoints: not scanned; the solver stage writes them before post starts.")
        elif post_plan['source_latest_step'] is not None:
            print(f"[INFO] Source checkpoints: {post_plan['source_committed_count']} committed, "
                  f"latest at step {post_plan['source_latest_step']}.")
        else:
            print("[INFO] Source checkpoints: none committed yet.")
 
        # A local launch plans again under the post lock and reports that plan, so only an
        # invocation that stages the work, or finds none, reports this one.
        executes_fields_now = (
            'fields' in post_stages and post_plan['skip_reason'] is None
            and not cluster_mode and not args.no_submit
        )
        if 'fields' in post_stages:
            if not executes_fields_now:
                report_post_plan(post_plan)
            warn_overlapping_post_recipes(run_dir, post_cfg, post_plan, post_stages)
        persist_post_resume_state(run_dir, post_plan, steps=post_plan['adopted_records'])
 
        # Spectra run in the conductor rather than in the submitted job, so they can
        # only be measured when this invocation is the one doing the work. Under a
        # scheduler, with --no-submit, or before the solver has written anything,
        # the sources do not exist yet and the measurement is deferred instead.
        spectra_execute_now = (
            not cluster_mode
            and not args.no_submit
            and not post_plan['source_frontier_deferred']
        )
        fields_job_measures_spectra = (
            cluster_mode and 'fields' in post_stages and post_plan['skip_reason'] is None
        )
        if 'spectra' in post_stages and spectra_execute_now:
            spectra_summary = run_post_spectra_stage(
                run_dir,
                post_plan['resolved_post_cfg'],
                monitor_cfg,
                post_plan['source_data_directory'],
                _iter_post_steps(post_plan['owned_start_step'], post_plan['requested_end_step'],
                                 post_plan['step_interval']),
                plan=post_plan,
                recompute=recompute,
            )
            for artifact in spectra_summary['artifacts']:
                print(f"[INFO] Spectra output: {os.path.relpath(artifact)}")
        elif 'spectra' in post_stages and not fields_job_measures_spectra:
            reason = ("the solver stage has not produced output yet"
                      if post_plan['source_frontier_deferred'] else
                      "this invocation only stages work")
            print(f"[INFO] Spectra deferred: {reason}. Measure them once the run has "
                  f"checkpoints with:")
            print(f"[INFO]   picurv run --post-process --only spectra "
                  f"--run-dir {os.path.relpath(run_dir)} --post {args.post}")
 
        # Without the field stage nothing finalizes, so selected reducers run here, on
        # the profiles earlier field stages wrote.
        if 'reducers' in post_stages and 'fields' not in post_stages:
            try:
                run_post_reducers_stage(run_dir, post_plan['resolved_post_cfg'])
            except ValueError as exc:
                print(f"[FATAL] {exc}", file=sys.stderr)
                sys.exit(1)
 
        if 'fields' not in post_stages:
            # --only selected a subset that excludes the field post-processor.
            print("[INFO] Skipping the field post-processor (--only "
                  f"{','.join(sorted(post_stages))}).")
            stages_completed.append('post-process')
        elif post_plan['skip_reason'] is not None:
            diagnostic = post_plan.get('source_frontier_diagnostic') or {}
            first_incomplete = diagnostic.get('first_incomplete_step')
            if post_plan['skip_reason'] == 'already-complete-window':
                print("[INFO] Every requested step is up to date; the postprocessor is not launched.")
            elif post_plan['skip_reason'] == 'already-caught-up-to-current-source-frontier':
                print("[INFO] Every requested step with a committed checkpoint is up to date; "
                      "the postprocessor is not launched.")
            else:
                print("[INFO] No requested step has a committed checkpoint yet; the "
                      "postprocessor is not launched.")
                missing_files = diagnostic.get('missing_files_for_first_incomplete_step') or []
                if first_incomplete is not None and missing_files:
                    print(f"[INFO] Missing files for step {first_incomplete}: {', '.join(missing_files[:4])}")
            if first_incomplete is not None:
                print(
                    "[INFO] Closest committed source steps: "
                    f"near start={_format_optional_step(diagnostic.get('closest_complete_step_to_start'))}, "
                    f"near end={_format_optional_step(diagnostic.get('closest_complete_step_to_end'))}"
                )
            if post_finalize_command and post_plan['steps_current']:
                run_post_finalize_locked(
                    run_dir, post_plan['recipe_fingerprint'], post_finalize_command
                )
        else:
            post_effective_cfg = post_plan['effective_post_cfg']
            post_io_cfg = post_effective_cfg.get('io', {})
            try:
                output_dir_rel = post_io_cfg['output_directory']
                output_prefix = post_io_cfg['output_filename_prefix']
            except KeyError as e:
                print(f"[FATAL] Missing required key '{e.args[0]}' in the 'io' section of {args.post}", file=sys.stderr)
                sys.exit(1)
 
            output_dir_abs = os.path.abspath(os.path.join(run_dir, output_dir_rel))
            os.makedirs(output_dir_abs, exist_ok=True)
            print(f"[INFO] Post-processor output directory: {os.path.relpath(output_dir_abs)}")
            statistics_output_paths = get_post_statistics_output_artifacts(post_effective_cfg, run_dir, monitor_cfg)
            for stats_path in statistics_output_paths:
                print(f"[INFO] Statistics CSV output: {os.path.relpath(stats_path)}")
 
            source_files_post = {'Case': case_path, 'Post-Profile': args.post}
            post_decomposition = resolve_post_decomposition(
                run_dir, post_num_procs_effective, getattr(args, "decomposition", None),
                cluster_cfg if cluster_mode else None)
            if post_decomposition["problems"]:
                print(f"[FATAL] {' '.join(post_decomposition['problems'])}", file=sys.stderr)
                sys.exit(1)
            print(f"[INFO] Post-processing {describe_decomposition(post_decomposition, post_num_procs_effective)}")
            post_recipe_file = generate_post_recipe_file(run_dir, run_id, post_effective_cfg, source_files_post,
                                                         monitor_cfg, post_decomposition)
            if post_exe is None:
                print(f"[FATAL] {post_exe_error}", file=sys.stderr)
                sys.exit(1)
            post_args = build_petsc_diagnostics_args(monitor_cfg, run_dir, "PostProcessor") + [
                "-control_file",
                solver_control_path,
                "-postprocessing_config_file",
                post_recipe_file,
            ]
            post_stage_meta = {
                "num_procs_effective": post_num_procs_effective,
                "decomposition": _decomposition_record(post_decomposition),
                "steps_planned": len(post_plan['steps_to_process']),
                "steps_current": post_plan['steps_current'],
                "recompute": recompute,
                "source_frontier_step": post_plan['source_frontier_step'],
                "source_frontier_deferred": post_plan['source_frontier_deferred'],
                "recipe_fingerprint": post_plan['recipe_fingerprint'],
                "finalize_command": post_finalize_command,
                "submitted": False,
            }
            if cluster_mode:
                scheduler_dir = os.path.join(run_dir, "scheduler")
                os.makedirs(scheduler_dir, exist_ok=True)
                post_script = os.path.join(scheduler_dir, "post.sbatch")
                post_log = os.path.join(scheduler_dir, "post_%j.out")
                post_err = os.path.join(scheduler_dir, "post_%j.err")
                post_cluster_cfg = cluster_cfg
                raw_post_cmd = build_cluster_launch_command(
                    post_cluster_cfg,
                    post_exe,
                    post_args,
                    config_search_anchor=case_path,
                    extra_search_anchors=[cluster_path],
                    force_num_procs=post_num_procs_effective,
                )
                post_cmd, _ = build_post_locked_command(
                    run_dir,
                    post_plan['recipe_fingerprint'],
                    raw_post_cmd,
                    create_wrapper=True,
                    success_command=post_finalize_command,
                    post_recipe=archived_post_path,
                    postprocessor=post_exe,
                    recompute=recompute,
                )
                spectra_follow = []
                if 'spectra' in post_stages:
                    follow = build_spectra_follow_command(run_dir, args.post, post_effective_cfg,
                                                          recompute=recompute)
                    if follow:
                        spectra_follow = [follow]
                        print("[INFO] Spectra will be measured in the post job, after "
                              "the field post-processor completes.")
                render_slurm_script(
                    post_script,
                    f"{run_id}_post",
                    post_cluster_cfg,
                    post_cmd,
                    run_dir,
                    post_log,
                    post_err,
                    env_vars={"LOG_LEVEL": monitor_cfg.get('logging', {}).get('verbosity', 'INFO').upper()},
                    follow_commands=spectra_follow,
                    identity_check=(post_exe, read_binary_build_identity(post_exe).get("version_line"),
                                    "postprocessor" in load_run_executables(run_dir)),
                )
                submission_meta["stages"]["post-process"] = {"script": post_script, **post_stage_meta}
                print(f"[SUCCESS] Generated post Slurm script: {os.path.relpath(post_script)}")
 
                if not args.no_submit:
                    dependency_job = None
                    if args.solve:
                        dependency_job = submission_meta.get("stages", {}).get("solve", {}).get("job_id")
                    submit_info = submit_sbatch(post_script, dependency=dependency_job)
                    submission_meta["stages"]["post-process"].update(submit_info)
                    submission_meta["stages"]["post-process"]["submitted"] = True
                    if dependency_job:
                        submission_meta["stages"]["post-process"]["dependency"] = f"afterok:{dependency_job}"
                    print(f"[SUCCESS] Submitted post job: {submit_info['job_id']}")
                stages_completed.append('post-process')
            else:
                raw_command = build_local_launch_command(
                    post_exe,
                    post_args,
                    post_num_procs_effective,
                    config_search_anchor=case_path,
                    allow_single_rank_launcher_override=True,
                    force_num_procs=post_num_procs_effective,
                )
                command, _ = build_post_locked_command(
                    run_dir,
                    post_plan['recipe_fingerprint'],
                    raw_command,
                    create_wrapper=True,
                    success_command=post_finalize_command,
                    post_recipe=archived_post_path,
                    postprocessor=post_exe,
                    recompute=recompute,
                )
                post_log = os.path.join("scheduler", f"{run_id}_{output_prefix}.log")
                submission_meta["stages"]["post-process"] = {
                    "command": command,
                    "command_string": format_command_for_display(command),
                    "log_file": post_log,
                    **post_stage_meta,
                }
                if args.no_submit:
                    print(f"[SUCCESS] Staged local post command: {post_log}")
                else:
                    execute_command(command, run_dir, post_log, monitor_cfg)
                    submission_meta["stages"]["post-process"]["submitted"] = True
                    submission_meta["stages"]["post-process"]["executed"] = True
                    submission_meta["stages"]["post-process"]["completed_at"] = datetime.now().isoformat()
                stages_completed.append('post-process')
 
    if run_dir:
        workspace_root = find_workspace_root(run_dir)
        manifest_inputs = {}
        if args.solve:
            manifest_inputs["case"] = _relative_to_workspace(args.case, workspace_root)
            manifest_inputs["solver"] = _relative_to_workspace(args.solver, workspace_root)
            manifest_inputs["monitor"] = _relative_to_workspace(args.monitor, workspace_root)
        if args.post_process:
            manifest_inputs["post"] = _relative_to_workspace(args.post, workspace_root)
        if cluster_mode:
            manifest_inputs["cluster"] = _relative_to_workspace(cluster_path, workspace_root)
        if submission_meta.get("stages"):
            # A stage this invocation did not stage keeps its record (a continued solve
            # leaves the run's earlier post job visible to cancel and summarize).
            submission_path = os.path.join(run_dir, "scheduler", "submission.json")
            for stage_name, stage_meta in ((_read_json_if_exists(submission_path) or {}).get("stages") or {}).items():
                submission_meta["stages"].setdefault(stage_name, stage_meta)
            write_json_file(submission_path, submission_meta)
        asset_lock = read_yaml_file(os.path.join(run_dir, "inputs", "assets.lock.yml")) \
            if os.path.isfile(os.path.join(run_dir, "inputs", "assets.lock.yml")) else {}
        manifest = build_run_manifest(
            run_dir,
            run_id,
            workspace_root=workspace_root,
            launch_mode="slurm" if cluster_mode else "local",
            num_procs=solver_num_procs_effective,
            post_num_procs=post_num_procs_effective,
            stages_requested={"solve": bool(args.solve), "post_process": bool(args.post_process)},
            stages_completed=stages_completed,
            inputs=manifest_inputs,
            asset_lock=asset_lock,
            submission=submission_meta,
            lineage=run_lineage,
        )
        write_json_file(os.path.join(run_dir, "manifest.json"), manifest)
 
    if stages_completed:
        elapsed = time.time() - workflow_start
        mins, secs = divmod(int(elapsed), 60)
        hrs, mins = divmod(mins, 60)
        if hrs > 0:
            time_str = f"{hrs}h {mins}m {secs}s"
        elif mins > 0:
            time_str = f"{mins}m {secs}s"
        else:
            time_str = f"{secs}s"
 
        print("\n" + "=" * 60)
        print("                       RUN SUMMARY")
        print("=" * 60)
        print(f"  Run ID          : {run_id}")
        print(f"  Run directory   : {os.path.relpath(run_dir)}")
        # A staged or Slurm-submitted stage has not run yet when this prints.
        staged = bool(cluster_mode or args.no_submit)
        print(f"  Wall-clock      : {time_str}")
        stages_label = "Stages staged" if args.no_submit else "Stages submitted" if staged else "Stages"
        print(f"  {stages_label:<16}: {', '.join(stages_completed)}")
        print(f"  Launch mode     : {'slurm' if cluster_mode else 'local'}")
        if args.solve:
            print(f"  Solver MPI procs: {solver_num_procs_effective}")
        if args.post_process:
            print(f"  Post MPI procs  : {post_num_procs_effective}")
        if args.solve and configs:
            total_steps = configs['case'].get('run_control', {}).get('total_steps', '?')
            result_dir = os.path.join(run_dir, CANONICAL_RUN_PATHS['output'])
            print(f"  {'Steps planned' if staged else 'Steps run':<16}: {total_steps}")
            print(f"  Solver output   : {os.path.relpath(result_dir)}")
        if 'post-process' in stages_completed and output_dir_abs:
            print(f"  Post output     : {os.path.relpath(output_dir_abs)}")
        for stats_path in statistics_output_paths:
            print(f"  Stats output    : {os.path.relpath(stats_path)}")
        # Report the configured log directory, not the default. An authorized external
        # path is exactly the case where the two differ, and it is the case where the
        # reader most needs to know where the logs actually went.
        log_display = os.path.join(run_dir, CANONICAL_RUN_PATHS['logs'])
        relative_log = os.path.relpath(log_display)
        # A relative path that climbs out of the working directory is harder to read
        # than the absolute one it stands for.
        print(f"  Logs            : "
              f"{log_display if relative_log.startswith('..') else relative_log}")
        if cluster_mode or submission_meta.get("stages"):
            submission_file = os.path.join(run_dir, "scheduler", "submission.json")
            print(f"  Submission meta : {os.path.relpath(submission_file)}")
        print("=" * 60)
 
 
def parse_case_index_tsv(tsv_path: str) -> list:
    """!
    @brief Parse a case_index.tsv file back into a list of case entry dicts.
    @param[in] tsv_path Path to the case_index.tsv file.
    @return List of dicts with keys: index, case_id, run_dir, control_file,
            post_recipe_file, log_level, post_prefix.
    """
    entries = []
    with open(tsv_path) as f:
        for line in f:
            line = line.strip()
            if not line:
                continue
            parts = line.split("\t")
            entries.append({
                "index": int(parts[0]),
                "case_id": parts[1],
                "run_dir": parts[2],
                "control_file": parts[3],
                "post_recipe_file": parts[4],
                "log_level": parts[5],
                "post_prefix": parts[6],
            })
    return entries
 
 
def resolve_sweep_stage_executables(run_dirs: list) -> dict:
    """!
    @brief Choose the executables an array stage launches for every member of a study.
 
    @details Array tasks share one script, which reads each member's `RUN_DIR` from the
             case index, so pinned members launch their own copy through the same
             `$RUN_DIR`-relative path. Members must agree: a study half pinned, or pinned
             at different paths, has no single command that launches each member's build.
    @param[in] run_dirs Member run directories the stage covers.
    @return Mapping of executable name to `(path token, staged --version line or None)`.
    @throws ValueError when members disagree about pinning.
    """
    pins = [load_run_executables(run_dir) for run_dir in run_dirs]
    chosen = {}
    for name in RUN_EXECUTABLE_NAMES:
        entries = [pin.get(name) for pin in pins]
        if not any(entries):
            path = resolve_runtime_executable(name)
            chosen[name] = (path, read_binary_build_identity(path).get("version_line"))
            continue
        relatives = {
            os.path.relpath(entry["path"], run_dir).replace(os.sep, "/") if entry else None
            for entry, run_dir in zip(entries, run_dirs)
        }
        lines = {entry.get("version_line") if entry else None for entry in entries}
        if None in relatives or len(relatives) != 1:
            raise ValueError(
                f"Study members disagree about the {name} they are pinned to; one array "
                "script cannot launch each member's build. Restage the study."
            )
        chosen[name] = (f"$RUN_DIR/{relatives.pop()}", lines.pop() if len(lines) == 1 else None)
    return chosen
 
 
def sweep_workflow(args):
    """!
    @brief Study/sweep orchestration using Slurm job arrays.
    @param[in] args Command-line style argument list supplied to the function.
    """
    study_path = os.path.abspath(args.study)
    cluster_path = os.path.abspath(args.cluster)
    workspace_root = find_workspace_root(study_path, cluster_path, os.getcwd())
    if workspace_root:
        enforce_workspace_version(workspace_root)
        enforce_reproducibility_policy(workspace_root)
 
    study_cfg = read_yaml_file(study_path)
    cluster_cfg = read_yaml_file(cluster_path)
    validate_study_config(study_cfg, study_path)
    validate_cluster_config(cluster_cfg, cluster_path)
 
    study_name = case_run_label(study_cfg, study_path)
    timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
    study_id = f"{study_name}_{timestamp}"
    study_dir = os.path.join(workspace_artifact_root(workspace_root, "studies"), study_id)
    cases_dir = os.path.join(study_dir, "cases")
    scheduler_dir = os.path.join(study_dir, "scheduler")
    results_dir = os.path.join(study_dir, "output", "analysis")
    for path in [cases_dir, scheduler_dir, results_dir, os.path.join(study_dir, "logs")]:
        os.makedirs(path, exist_ok=True)
 
    print(f"[INFO] Creating study directory: {os.path.relpath(study_dir)}")
    base_cfgs = study_cfg["base_configs"]
    base_paths = {k: resolve_path(study_path, v) for k, v in base_cfgs.items()}
    base_snapshot_dir = os.path.join(study_dir, "base_configs")
    os.makedirs(base_snapshot_dir, exist_ok=True)
    portable_study_cfg = copy.deepcopy(study_cfg)
    portable_study_cfg["base_configs"] = {}
    for role in ("case", "solver", "monitor", "post"):
        snapshot_name = f"{role}.yml"
        snapshot_path = os.path.join(base_snapshot_dir, snapshot_name)
        shutil.copy2(base_paths[role], snapshot_path)
        portable_study_cfg["base_configs"][role] = os.path.join("base_configs", snapshot_name)
    shutil.copy2(study_path, os.path.join(study_dir, "study.source.yml"))
    write_yaml_file(os.path.join(study_dir, "study.yml"), portable_study_cfg)
    shutil.copy2(cluster_path, os.path.join(study_dir, "cluster.yml"))
 
    base_case = read_yaml_file(base_paths["case"])
    base_solver = read_yaml_file(base_paths["solver"])
    base_monitor = read_yaml_file(base_paths["monitor"])
    base_post = read_yaml_file(base_paths["post"])
    validate_simulation_configs(base_case, base_solver, base_monitor, base_paths["case"], base_paths["solver"], base_paths["monitor"])
    validate_post_config(base_post, base_paths["post"], base_monitor, base_case)
 
    combinations = expand_study_parameter_combinations(study_cfg)
    if not combinations:
        print("[FATAL] Study parameter matrix expanded to zero cases.", file=sys.stderr)
        sys.exit(1)
    print(f"[INFO] Expanded sweep matrix to {len(combinations)} case(s).")
 
    cluster_tasks = get_cluster_total_tasks(cluster_cfg)
    case_entries = []
    case_index_file = os.path.join(scheduler_dir, "case_index.tsv")
 
    # One array script launches every member, so the study runs on one PetscInt width: the
    # widest any member needs, unless one was requested.
    member_widths = []
    for combo in combinations:
        member = {"case": copy.deepcopy(base_case), "monitor": copy.deepcopy(base_monitor),
                  "solver": {}, "post": {}}
        for full_key, value in combo.items():
            root, nested = full_key.split(".", 1)
            _deep_set(member[root], nested, value)
        absolutize_case_external_paths(member["case"], base_paths["case"])
        member_widths.append(required_petsc_index_bytes(member["case"], base_paths["case"], member["monitor"]))
    try:
        requested = requested_petsc_index_bytes(args)
        widest = max(member_widths, default=(4, "particle and grid fields fit 32-bit indices"))
        if requested == 4 and widest[0] == 8:
            raise ValueError(f"--petsc-index-bits 32 cannot run every study member: {widest[1]}.")
        if requested is not None:
            select_petsc_index_bytes(requested, f"{8 * requested}-bit indices were requested")
        else:
            select_petsc_index_bytes(*widest)
    except ValueError as exc:
        print(f"[FATAL] {exc}", file=sys.stderr)
        sys.exit(1)
 
    for idx, combo in enumerate(combinations):
        case_id = f"case_{idx:04d}"
        run_dir = os.path.join(cases_dir, case_id)
        config_dir = os.path.join(run_dir, "config")
        ensure_run_layout(run_dir)
 
        case_cfg = copy.deepcopy(base_case)
        solver_cfg = copy.deepcopy(base_solver)
        monitor_cfg = copy.deepcopy(base_monitor)
        post_cfg = copy.deepcopy(base_post)
        target_map = {"case": case_cfg, "solver": solver_cfg, "monitor": monitor_cfg, "post": post_cfg}
        for full_key, value in combo.items():
            root, nested = full_key.split(".", 1)
            _deep_set(target_map[root], nested, value)
 
        # Preserve file-based/grid-gen workflows when study cases are materialized
        # into new directories by rewriting external paths as absolute.
        absolutize_case_external_paths(case_cfg, base_paths["case"])
 
        case_path = os.path.join(config_dir, "case.yml")
        solver_path = os.path.join(config_dir, "solver.yml")
        monitor_path = os.path.join(config_dir, "monitor.yml")
        post_path = os.path.join(config_dir, "post.yml")
        write_yaml_file(case_path, case_cfg)
        write_yaml_file(solver_path, solver_cfg)
        write_yaml_file(monitor_path, monitor_cfg)
        write_yaml_file(post_path, post_cfg)
        write_json_file(os.path.join(config_dir, "active.json"), {
            "schema_version": 1,
            "revision": "initial",
            "updated_at": datetime.now().astimezone().isoformat(),
            "files": {
                "case": "config/case.yml",
                "solver": "config/solver.yml",
                "monitor": "config/monitor.yml",
            },
        })
        record_run_petsc_index_bytes(run_dir)
        if resolve_executable_pinning(args, workspace_root):
            try:
                pin_run_executables(run_dir, "initial")
            except ValueError as exc:
                print(f"[FATAL] {exc}", file=sys.stderr)
                sys.exit(1)
 
        validate_simulation_configs(case_cfg, solver_cfg, monitor_cfg, case_path, solver_path, monitor_path)
        validate_post_config(post_cfg, post_path, monitor_cfg, case_cfg)
 
        try:
            asset_lock = materialize_run_assets(
                run_dir, case_cfg, case_path, skip_kinds=unused_asset_kinds(case_cfg, solver_cfg)
            )
        except ValueError as exc:
            print(f"[FATAL] Study case {case_id}: {exc}", file=sys.stderr)
            sys.exit(1)
 
        source_files = {'Case': case_path, 'Solver': solver_path, 'Monitor': monitor_path}
        monitor_files = prepare_monitor_files(run_dir, case_id, monitor_cfg, source_files)
        configs = {
            "case": case_cfg, "case_path": case_path,
            "solver": solver_cfg, "solver_path": solver_path,
            "monitor": monitor_cfg, "monitor_path": monitor_path,
            "walltime_guard_policy": resolve_walltime_guard_policy(cluster_cfg),
            "cluster_cfg": cluster_cfg,
        }
        control_file = generate_solver_control_file(run_dir, case_id, configs, cluster_tasks, monitor_files)
        archive_active_generated_configuration(
            run_dir,
            [control_file, monitor_files.get("whitelist"), monitor_files.get("profile"),
             *glob.glob(os.path.join(config_dir, "bcs*.run"))],
        )
 
        source_dir = resolve_post_source_directory(run_dir, monitor_cfg, post_cfg, strict=False)
        if not isinstance(post_cfg.get('source_data'), dict):
            post_cfg['source_data'] = {}
        post_cfg['source_data']['directory'] = source_dir
        post_cfg, recipe_id = apply_canonical_post_paths(post_cfg, run_dir)
        for relative in (
            post_cfg["_picurv_paths"]["visualization"],
            post_cfg["_picurv_paths"]["statistics"],
            post_cfg["_picurv_paths"]["spectra"],
        ):
            os.makedirs(os.path.join(run_dir, relative), exist_ok=True)
        output_prefix = post_cfg.get("io", {}).get("output_filename_prefix", "post")
        post_decomposition = resolve_post_decomposition(run_dir, cluster_tasks, None, cluster_cfg)
        if post_decomposition["problems"]:
            print(f"[FATAL] Study case {case_id}: {' '.join(post_decomposition['problems'])}", file=sys.stderr)
            sys.exit(1)
        post_recipe = generate_post_recipe_file(run_dir, case_id, post_cfg, {'Case': case_path, 'Post-Profile': post_path},
                                                monitor_cfg, post_decomposition)
        ensure_post_lock_wrapper(run_dir)
 
        case_entries.append({
            "index": idx,
            "case_id": case_id,
            "run_dir": os.path.abspath(run_dir),
            "control_file": control_file,
            "post_recipe_file": post_recipe,
            "log_level": str(monitor_cfg.get("logging", {}).get("verbosity", "INFO")).upper(),
            "post_prefix": output_prefix,
            "solve_diagnostic_args": shlex.join(build_petsc_diagnostics_args(monitor_cfg, run_dir, "Solver")),
            "post_diagnostic_args": shlex.join(build_petsc_diagnostics_args(monitor_cfg, run_dir, "PostProcessor")),
            "parameters": combo,
        })
        write_json_file(
            os.path.join(run_dir, "manifest.json"),
            build_run_manifest(
                run_dir, case_id, workspace_root=workspace_root, launch_mode="slurm",
                artifact_type="study-case", study_id=study_id, case_id=case_id,
                num_procs=cluster_tasks, post_num_procs=cluster_tasks,
                stages_requested={"solve": True, "post_process": True},
                inputs={
                    "case": _relative_to_workspace(case_path, workspace_root),
                    "solver": _relative_to_workspace(solver_path, workspace_root),
                    "monitor": _relative_to_workspace(monitor_path, workspace_root),
                    "post": _relative_to_workspace(post_path, workspace_root),
                },
                asset_lock=asset_lock,
            ),
        )
 
    with open(case_index_file, "w") as f:
        for entry in case_entries:
            f.write(
                "\t".join(
                    [
                        str(entry["index"]),
                        entry["case_id"],
                        entry["run_dir"],
                        entry["control_file"],
                        entry["post_recipe_file"],
                        entry["log_level"],
                        entry["post_prefix"],
                        entry["solve_diagnostic_args"],
                        entry["post_diagnostic_args"],
                    ]
                ) + "\n"
            )
    print(f"[SUCCESS] Wrote sweep case index: {os.path.relpath(case_index_file)}")
 
    max_idx = len(case_entries) - 1
    max_conc = study_cfg.get("execution", {}).get("max_concurrent_array_tasks")
    array_spec = f"0-{max_idx}"
    if max_conc:
        array_spec = f"{array_spec}%{max_conc}"
 
    stage_executables = resolve_sweep_stage_executables([entry["run_dir"] for entry in case_entries])
    solver_exe, solver_version_line = stage_executables["simulator"]
    post_exe, post_version_line = stage_executables["postprocessor"]
    solver_array_script = os.path.join(scheduler_dir, "solver_array.sbatch")
    post_array_script = os.path.join(scheduler_dir, "post_array.sbatch")
    render_slurm_array_stage_script(
        solver_array_script,
        f"{study_id}_solve",
        cluster_cfg,
        array_spec,
        case_index_file,
        "solve",
        solver_exe,
        post_exe,
        os.path.join(scheduler_dir, "solver_%A_%a.out"),
        os.path.join(scheduler_dir, "solver_%A_%a.err"),
        expected_version_line=solver_version_line,
    )
    render_slurm_array_stage_script(
        post_array_script,
        f"{study_id}_post",
        cluster_cfg,
        array_spec,
        case_index_file,
        "post",
        solver_exe,
        post_exe,
        os.path.join(scheduler_dir, "post_%A_%a.out"),
        os.path.join(scheduler_dir, "post_%A_%a.err"),
        expected_version_line=post_version_line,
    )
    print(f"[SUCCESS] Generated Slurm array scripts in {os.path.relpath(scheduler_dir)}")
 
    picurv_path = os.path.abspath(os.path.join(INVOKED_SCRIPT_DIR, "picurv"))
    metrics_aggregate_script = os.path.join(scheduler_dir, "metrics_aggregate.sbatch")
    render_metrics_aggregate_script(
        metrics_aggregate_script,
        f"{study_id}_metrics",
        cluster_cfg,
        study_dir,
        picurv_path,
    )
    print(f"[SUCCESS] Generated metrics aggregation script: {os.path.relpath(metrics_aggregate_script)}")
 
    submission = {
        "launch_mode": "slurm",
        "study_id": study_id,
        "solver_array": {"script": solver_array_script, "submitted": False},
        "post_array": {"script": post_array_script, "submitted": False},
        "metrics_aggregate": {"script": metrics_aggregate_script, "submitted": False},
        "no_submit": bool(args.no_submit),
    }
    if not args.no_submit:
        solver_submit = submit_sbatch(solver_array_script)
        submission["solver_array"].update(solver_submit)
        submission["solver_array"]["submitted"] = True
        post_submit = submit_sbatch(post_array_script, dependency=solver_submit["job_id"])
        submission["post_array"].update(post_submit)
        submission["post_array"]["submitted"] = True
        submission["post_array"]["dependency"] = f"afterok:{solver_submit['job_id']}"
        metrics_submit = submit_sbatch(metrics_aggregate_script, dependency=post_submit["job_id"], dependency_type="afterany")
        submission["metrics_aggregate"].update(metrics_submit)
        submission["metrics_aggregate"]["submitted"] = True
        submission["metrics_aggregate"]["dependency"] = f"afterany:{post_submit['job_id']}"
        print(f"[SUCCESS] Submitted solver array job:  {solver_submit['job_id']}")
        print(f"[SUCCESS] Submitted post array job:    {post_submit['job_id']}")
        print(f"[SUCCESS] Submitted metrics agg. job:  {metrics_submit['job_id']}")
 
    metrics_csv = aggregate_study_metrics(study_cfg, case_entries, results_dir)
    plots = generate_study_plots(study_cfg, metrics_csv, os.path.join(results_dir, "plots"))
 
    summary = {
        "schema_version": 2,
        "artifact_type": "study",
        "study_id": study_id,
        "created_at": datetime.now().isoformat(),
        "software": dict(picurv_build()),
        "study_type": study_cfg.get("study_type"),
        "num_cases": len(case_entries),
        "paths": {
            "study_dir": study_dir,
            "case_index": case_index_file,
            "solver_array_script": solver_array_script,
            "post_array_script": post_array_script,
            "metrics_table": metrics_csv,
            "plots_dir": os.path.join(results_dir, "plots"),
        },
        "submission": submission,
    }
    write_json_file(os.path.join(scheduler_dir, "submission.json"), submission)
    write_json_file(os.path.join(study_dir, "study_manifest.json"), summary)
    write_json_file(os.path.join(results_dir, "summary.json"), {"study_id": study_id, "metrics_csv": metrics_csv, "plots": plots})
 
    print("\n" + "=" * 60)
    print("                     STUDY SUMMARY")
    print("=" * 60)
    print(f"  Study ID        : {study_id}")
    print(f"  Study directory : {os.path.relpath(study_dir)}")
    print(f"  Cases generated : {len(case_entries)}")
    print(f"  Array spec      : {array_spec}")
    print(f"  Solver script   : {os.path.relpath(solver_array_script)}")
    print(f"  Post script     : {os.path.relpath(post_array_script)}")
    if args.no_submit:
        print(f"  Submit with     : picurv submit --study-dir {os.path.relpath(study_dir)}")
    if metrics_csv:
        print(f"  Metrics table   : {os.path.relpath(metrics_csv)}")
    if plots:
        print(f"  Plots           : {os.path.relpath(os.path.join(results_dir, 'plots'))}")
    print("=" * 60)
 
 
def sweep_continue_workflow(args):
    """!
    @brief Continue a partially-completed Slurm parameter sweep study.
    @details Detects incomplete cases, prepares them for continuation (updating
             start_step, populating restart directories, regenerating control files),
             and submits new solver/post/metrics Slurm jobs. If all cases are already
             complete, performs metrics aggregation automatically.
    @param[in] args Parsed CLI arguments with study_dir and optional cluster override.
    """
    study_dir = os.path.abspath(args.study_dir)
    manifest_path = os.path.join(study_dir, "study_manifest.json")
    if not os.path.isfile(manifest_path):
        emit_structured_error(ERROR_CODE_CFG_FILE_NOT_FOUND, key="study_dir", file_path=manifest_path,
                              message="Study manifest not found.", hint=_STUDY_DIR_HINT)
        sys.exit(1)
    adopt_relocated_artifact(study_dir, kind="study")
    manifest = _read_json_if_exists(manifest_path)
    study_id = manifest["study_id"]
 
    study_path = os.path.join(study_dir, "study.yml")
    cluster_path = os.path.abspath(args.cluster) if args.cluster else os.path.join(study_dir, "cluster.yml")
    study_cfg = read_yaml_file(study_path)
    cluster_cfg = read_yaml_file(cluster_path)
    validate_study_config(study_cfg, study_path, skip_base_file_check=True)
    validate_cluster_config(cluster_cfg, cluster_path)
 
    if args.cluster:
        shutil.copy(os.path.abspath(args.cluster), os.path.join(study_dir, "cluster.yml"))
        print(f"[INFO] Updated study cluster config from: {os.path.relpath(args.cluster)}")
 
    scheduler_dir = os.path.join(study_dir, "scheduler")
    cases_dir = os.path.join(study_dir, "cases")
    results_dir = os.path.join(study_dir, "output", "analysis")
    case_index_file = os.path.join(scheduler_dir, "case_index.tsv")
    if not os.path.isfile(case_index_file):
        print(f"[FATAL] Case index not found: {case_index_file}", file=sys.stderr)
        sys.exit(1)
 
    parsed_entries = parse_case_index_tsv(case_index_file)
 
    cold_cases = cold_study_members(study_dir)
    if cold_cases and getattr(args, "auto_fetch", False):
        print(
            "[INFO] --auto-fetch: restoring cold-storage member(s) before continuing: "
            + ", ".join(cold_cases)
        )
        try:
            restore_cold_study_members(study_dir, cold_cases)
        except StorageError as exc:
            print(f"[FATAL] Automatic restore failed: {exc}", file=sys.stderr)
            sys.exit(1)
        cold_cases = cold_study_members(study_dir)
    if cold_cases:
        print(
            "[FATAL] Study continuation requires payload from cold-storage member(s): "
            + ", ".join(cold_cases),
            file=sys.stderr,
        )
        for case_id in cold_cases:
            state = storage_state_summary(os.path.join(cases_dir, case_id))
            print(
                f"        Restore {case_id} with: picurv storage restore --archive-id "
                f"{state.get('archive_id') or '<archive-id>'}",
                file=sys.stderr,
            )
        print(
            "        Or pass --auto-fetch to restore them automatically.",
            file=sys.stderr,
        )
        sys.exit(1)
 
    # Staging writes these as snapshots inside the study (base_configs/<role>.yml), so
    # they resolve against the study directory, not the workspace that holds it.
    base_cfgs = study_cfg["base_configs"]
    base_paths = {k: os.path.join(study_dir, v) for k, v in base_cfgs.items()}
    base_case = read_yaml_file(base_paths["case"])
 
    combinations = expand_study_parameter_combinations(study_cfg)
    if len(combinations) != len(parsed_entries):
        print(
            f"[FATAL] Parameter matrix ({len(combinations)} cases) does not match "
            f"case_index.tsv ({len(parsed_entries)} entries).",
            file=sys.stderr,
        )
        sys.exit(1)
 
    print(f"\n[INFO] Study: {study_id}")
    print(f"[INFO] Scanning {len(combinations)} case(s) for completion status...")
 
    incomplete_indices = []
    all_case_entries = []
    for idx, combo in enumerate(combinations):
        case_id = f"case_{idx:04d}"
        entry = parsed_entries[idx]
        entry["parameters"] = combo
        run_dir = entry["run_dir"]
 
        effective_case = copy.deepcopy(base_case)
        for full_key, value in combo.items():
            root, nested = full_key.split(".", 1)
            if root == "case":
                _deep_set(effective_case, nested, value)
        try:
            eff_start = int(effective_case.get("run_control", {}).get("start_step", 0) or 0)
        except (TypeError, ValueError):
            eff_start = 0
        eff_total = int(effective_case["run_control"]["total_steps"])
        target = eff_start + eff_total
 
        monitor_cfg = read_yaml_file(os.path.join(run_dir, "config", "monitor.yml"))
        status = detect_case_completion_status(run_dir, monitor_cfg, target)
        entry["_status"] = status
 
        if status["status"] == "complete":
            print(f"  {case_id}: complete (step {status['last_step']}/{target})")
        elif status["status"] == "partial":
            print(f"  {case_id}: incomplete (step {status['last_step']}/{target}) — will continue")
            incomplete_indices.append(idx)
        else:
            print(f"  {case_id}: no checkpoint — will re-run from scratch")
            incomplete_indices.append(idx)
 
        all_case_entries.append(entry)
 
    if not incomplete_indices:
        print("\n[INFO] All cases are complete. Running metrics aggregation...")
        metrics_csv = aggregate_study_metrics(study_cfg, all_case_entries, results_dir)
        plots = generate_study_plots(study_cfg, metrics_csv, os.path.join(results_dir, "plots"))
        print("\n" + "=" * 60)
        print("              STUDY CONTINUATION SUMMARY")
        print("=" * 60)
        print(f"  Study ID        : {study_id}")
        print(f"  Status          : ALL COMPLETE")
        if metrics_csv:
            print(f"  Metrics table   : {os.path.relpath(metrics_csv)}")
        if plots:
            print(f"  Plots           : {os.path.relpath(os.path.join(results_dir, 'plots'))}")
        print("=" * 60)
        return
 
    print(f"\n[INFO] {len(incomplete_indices)} incomplete case(s) to continue/re-run.")
 
    skipped = []
    for idx in incomplete_indices:
        entry = all_case_entries[idx]
        status = entry["_status"]
        if status["status"] == "partial":
            prepare_case_for_continuation(
                entry["run_dir"], entry["case_id"],
                status["last_step"], status["target_step"],
                cluster_cfg,
            )
        elif status["status"] == "empty":
            print(f"[INFO] {entry['case_id']}: re-running from scratch (no control file changes)")
 
    solver_array_spec = ",".join(str(i) for i in incomplete_indices)
    max_conc = study_cfg.get("execution", {}).get("max_concurrent_array_tasks")
    if max_conc:
        solver_array_spec = f"{solver_array_spec}%{max_conc}"
 
    max_idx = len(combinations) - 1
    post_array_spec = f"0-{max_idx}"
    if max_conc:
        post_array_spec = f"{post_array_spec}%{max_conc}"
 
    try:
        stage_executables = resolve_sweep_stage_executables(
            [entry["run_dir"] for entry in all_case_entries]
        )
    except ValueError as exc:
        print(f"[FATAL] {exc}", file=sys.stderr)
        sys.exit(1)
    solver_exe, solver_version_line = stage_executables["simulator"]
    post_exe, post_version_line = stage_executables["postprocessor"]
    # The post array relaunches every member through the lock wrapper; a study staged
    # by an earlier version holds a wrapper without the launch-time planning it needs.
    for entry in all_case_entries:
        ensure_post_lock_wrapper(entry["run_dir"])
 
    solver_continue_script = os.path.join(scheduler_dir, "solver_continue_array.sbatch")
    post_continue_script = os.path.join(scheduler_dir, "post_continue_array.sbatch")
    render_slurm_array_stage_script(
        solver_continue_script,
        f"{study_id}_solve_cont",
        cluster_cfg,
        solver_array_spec,
        case_index_file,
        "solve",
        solver_exe, post_exe,
        os.path.join(scheduler_dir, "solver_cont_%A_%a.out"),
        os.path.join(scheduler_dir, "solver_cont_%A_%a.err"),
        expected_version_line=solver_version_line,
    )
    render_slurm_array_stage_script(
        post_continue_script,
        f"{study_id}_post_cont",
        cluster_cfg,
        post_array_spec,
        case_index_file,
        "post",
        solver_exe, post_exe,
        os.path.join(scheduler_dir, "post_cont_%A_%a.out"),
        os.path.join(scheduler_dir, "post_cont_%A_%a.err"),
        expected_version_line=post_version_line,
    )
 
    picurv_path = os.path.abspath(os.path.join(INVOKED_SCRIPT_DIR, "picurv"))
    metrics_aggregate_script = os.path.join(scheduler_dir, "metrics_continue_aggregate.sbatch")
    render_metrics_aggregate_script(
        metrics_aggregate_script,
        f"{study_id}_metrics_cont",
        cluster_cfg,
        study_dir,
        picurv_path,
    )
    print(f"[SUCCESS] Generated continuation scripts in {os.path.relpath(scheduler_dir)}")
 
    submission = {
        "launch_mode": "slurm",
        "study_id": study_id,
        "continuation": True,
        "incomplete_cases": [all_case_entries[i]["case_id"] for i in incomplete_indices],
        "solver_continue_array": {"script": solver_continue_script, "submitted": False},
        "post_continue_array": {"script": post_continue_script, "submitted": False},
        "metrics_aggregate": {"script": metrics_aggregate_script, "submitted": False},
        "no_submit": bool(args.no_submit),
    }
    if not args.no_submit:
        solver_submit = submit_sbatch(solver_continue_script)
        submission["solver_continue_array"].update(solver_submit)
        submission["solver_continue_array"]["submitted"] = True
        post_submit = submit_sbatch(post_continue_script, dependency=solver_submit["job_id"])
        submission["post_continue_array"].update(post_submit)
        submission["post_continue_array"]["submitted"] = True
        submission["post_continue_array"]["dependency"] = f"afterok:{solver_submit['job_id']}"
        metrics_submit = submit_sbatch(metrics_aggregate_script, dependency=post_submit["job_id"], dependency_type="afterany")
        submission["metrics_aggregate"].update(metrics_submit)
        submission["metrics_aggregate"]["submitted"] = True
        submission["metrics_aggregate"]["dependency"] = f"afterany:{post_submit['job_id']}"
        print(f"[SUCCESS] Submitted continuation solver array: {solver_submit['job_id']}")
        print(f"[SUCCESS] Submitted continuation post array:   {post_submit['job_id']}")
        print(f"[SUCCESS] Submitted metrics aggregation job:   {metrics_submit['job_id']}")
 
    write_json_file(os.path.join(scheduler_dir, "submission_continue.json"), submission)
 
    manifest["continuation"] = {
        "continued_at": datetime.now().isoformat(),
        "incomplete_cases": [all_case_entries[i]["case_id"] for i in incomplete_indices],
        "submission": submission,
    }
    write_json_file(manifest_path, manifest)
 
    print("\n" + "=" * 60)
    print("              STUDY CONTINUATION SUMMARY")
    print("=" * 60)
    print(f"  Study ID          : {study_id}")
    print(f"  Incomplete cases  : {len(incomplete_indices)}/{len(combinations)}")
    print(f"  Solver array spec : {solver_array_spec}")
    print(f"  Post array spec   : {post_array_spec}")
    print(f"  Solver script     : {os.path.relpath(solver_continue_script)}")
    print(f"  Post script       : {os.path.relpath(post_continue_script)}")
    print(f"  Metrics script    : {os.path.relpath(metrics_aggregate_script)}")
    if not args.no_submit:
        print(f"  [Metrics aggregation will run automatically after post-processing]")
    else:
        print(f"  [--no-submit] Scripts generated but not submitted. Submit them with:")
        print(f"    picurv submit --study-dir {os.path.relpath(study_dir)}")
    print("=" * 60)
 
 
def sweep_reaggregate_workflow(args):
    """!
    @brief Re-run metrics aggregation and plot generation for an existing study.
    @param[in] args Parsed CLI arguments with study_dir.
    """
    study_dir = os.path.abspath(args.study_dir)
    study_path = os.path.join(study_dir, "study.yml")
    if not os.path.isfile(study_path):
        emit_structured_error(ERROR_CODE_CFG_FILE_NOT_FOUND, key="study_dir", file_path=study_path,
                              message="Study config not found.", hint=_STUDY_DIR_HINT)
        sys.exit(1)
    adopt_relocated_artifact(study_dir, kind="study")
    study_cfg = read_yaml_file(study_path)
    validate_study_config(study_cfg, study_path, skip_base_file_check=True)
 
    case_index_file = os.path.join(study_dir, "scheduler", "case_index.tsv")
    if not os.path.isfile(case_index_file):
        print(f"[FATAL] Case index not found: {case_index_file}", file=sys.stderr)
        sys.exit(1)
 
    parsed_entries = parse_case_index_tsv(case_index_file)
    cold_cases = cold_study_members(study_dir)
    if cold_cases and getattr(args, "auto_fetch", False):
        print(
            "[INFO] --auto-fetch: restoring cold-storage member(s) before aggregating: "
            + ", ".join(cold_cases)
        )
        try:
            restore_cold_study_members(study_dir, cold_cases)
        except StorageError as exc:
            print(f"[FATAL] Automatic restore failed: {exc}", file=sys.stderr)
            sys.exit(1)
        cold_cases = cold_study_members(study_dir)
    if cold_cases:
        print(
            "[INFO] Cold-storage member(s) cannot be re-measured; their previously "
            "aggregated values are carried forward: " + ", ".join(cold_cases)
        )
    combinations = expand_study_parameter_combinations(study_cfg)
    if len(combinations) != len(parsed_entries):
        print(
            f"[FATAL] Parameter matrix ({len(combinations)} cases) does not match "
            f"case_index.tsv ({len(parsed_entries)} entries).",
            file=sys.stderr,
        )
        sys.exit(1)
 
    case_entries = []
    for idx, combo in enumerate(combinations):
        entry = parsed_entries[idx]
        entry["parameters"] = combo
        case_entries.append(entry)
 
    results_dir = os.path.join(study_dir, "output", "analysis")
    metrics_csv = aggregate_study_metrics(study_cfg, case_entries, results_dir)
    plots = generate_study_plots(study_cfg, metrics_csv, os.path.join(results_dir, "plots"))
 
    print("\n" + "=" * 60)
    print("              REAGGREGATION SUMMARY")
    print("=" * 60)
    if metrics_csv:
        print(f"  Metrics table   : {os.path.relpath(metrics_csv)}")
    if plots:
        print(f"  Plots generated : {len(plots)}")
    print("=" * 60)
 
 
_SUMMARY_NUMERIC_RE = re.compile(r"[-+]?\d*\.?\d+(?:[eE][-+]?\d+)?")
 
 
def _read_yaml_if_exists(filepath: str):
    """!
    @brief Read YAML when present, otherwise return None.
    @param[in] filepath Argument passed to `_read_yaml_if_exists()`.
    @return Value returned by `_read_yaml_if_exists()`.
    """
    if not filepath or not os.path.isfile(filepath):
        return None
    try:
        with open(filepath, "r", encoding="utf-8") as f:
            return yaml.safe_load(f)
    except yaml.YAMLError:
        return None
 
 
def _read_json_if_exists(filepath: str):
    """!
    @brief Read JSON when present, otherwise return None.
    @param[in] filepath Argument passed to `_read_json_if_exists()`.
    @return Value returned by `_read_json_if_exists()`.
    """
    if not filepath or not os.path.isfile(filepath):
        return None
    with open(filepath, "r", encoding="utf-8") as f:
        return json.load(f)
 
 
def _parse_int_loose(value):
    """!
    @brief Best-effort integer parsing for summary extraction.
    @param[in] value Argument passed to `_parse_int_loose()`.
    @return Value returned by `_parse_int_loose()`.
    """
    if value is None:
        return None
    text = str(value).strip()
    if not text:
        return None
    try:
        return int(text)
    except ValueError:
        try:
            return int(float(text))
        except ValueError:
            return None
 
 
def _parse_float_loose(value):
    """!
    @brief Best-effort float parsing for summary extraction.
    @param[in] value Argument passed to `_parse_float_loose()`.
    @return Value returned by `_parse_float_loose()`.
    """
    if value is None:
        return None
    text = str(value).strip()
    if not text:
        return None
    try:
        return float(text)
    except ValueError:
        return None
 
 
def _extract_numeric_tuple(text: str):
    """!
    @brief Extract a numeric tuple from a string like '(1, 2, 3)'.
    @param[in] text Argument passed to `_extract_numeric_tuple()`.
    @return Value returned by `_extract_numeric_tuple()`.
    """
    if not text:
        return []
    return [float(token) for token in _SUMMARY_NUMERIC_RE.findall(text)]
 
 
def _build_summary_context(run_dir: str) -> dict:
    """!
    @brief Resolve run-local config and artifact paths for summarize.
    @param[in] run_dir Argument passed to `_build_summary_context()`.
    @return Value returned by `_build_summary_context()`.
    """
    run_dir = os.path.abspath(run_dir)
    if not os.path.isdir(run_dir):
        emit_structured_error(
            ERROR_CODE_CFG_FILE_NOT_FOUND,
            key="run_dir",
            file_path=run_dir,
            message="Run directory not found.",
        )
        sys.exit(1)
 
    config_dir = os.path.join(run_dir, "config")
    config_paths = {
        "case": os.path.join(config_dir, "case.yml"),
        "solver": os.path.join(config_dir, "solver.yml"),
        "monitor": os.path.join(config_dir, "monitor.yml"),
    }
    monitor_cfg = _read_yaml_if_exists(config_paths["monitor"]) or {}
    case_cfg = _read_yaml_if_exists(config_paths["case"]) or {}
    solver_cfg = _read_yaml_if_exists(config_paths["solver"]) or {}
    manifest = _read_json_if_exists(os.path.join(run_dir, "manifest.json")) or {}
 
    io_cfg = monitor_cfg.get("io", {}) if isinstance(monitor_cfg, dict) else {}
    scheduler_dir = os.path.join(run_dir, "scheduler")
 
    profiling_cfg = {"mode": "off", "functions": [], "final_summary_enabled": True, "helpers": []}
    if monitor_cfg:
        profiling_cfg = resolve_profiling_config(monitor_cfg)
 
    particle_console_output_freq = None
    particle_log_interval = None
    if monitor_cfg:
        particle_console_output_freq = resolve_particle_console_output_frequency(io_cfg)
        particle_log_interval = io_cfg.get("particle_log_interval")
 
    particle_count_cfg = None
    if case_cfg:
        particle_count_cfg = (
            case_cfg.get("models", {})
            .get("physics", {})
            .get("particles", {})
            .get("count")
        )
 
    return {
        "run_dir": run_dir,
        "config_dir": config_dir,
        "log_dir": os.path.join(run_dir, CANONICAL_RUN_PATHS["logs"]),
        "metrics_dir": os.path.join(run_dir, CANONICAL_RUN_PATHS["metrics"]),
        "scheduler_dir": scheduler_dir,
        "monitor_cfg": monitor_cfg,
        "case_cfg": case_cfg,
        "solver_cfg": solver_cfg,
        "config_paths": config_paths,
        "manifest": manifest,
        "profiling_cfg": profiling_cfg,
        "particle_console_output_freq": particle_console_output_freq,
        "particle_log_interval": particle_log_interval,
        "particle_count_cfg": particle_count_cfg,
    }
 
 
def _require_summary_config(context: dict, name: str) -> dict:
    """!
    @brief Return one explicitly requested copied config or fail with a structured error.
    @param[in] context Summary context returned by `_build_summary_context()`.
    @param[in] name Config selector name.
    @return Parsed config mapping.
    """
    path = context["config_paths"][name]
    cfg = context.get(f"{name}_cfg")
    if not os.path.isfile(path):
        emit_structured_error(
            ERROR_CODE_CFG_FILE_NOT_FOUND,
            key=name,
            file_path=path,
            message=f"Copied run config '{name}.yml' was not found.",
            hint="Use a staged run directory containing the requested copied config.",
        )
        sys.exit(1)
    if not isinstance(cfg, dict) or not cfg:
        emit_structured_error(
            ERROR_CODE_CFG_INVALID_VALUE,
            key=name,
            file_path=path,
            message=f"Copied run config '{name}.yml' is empty or is not a YAML mapping.",
        )
        sys.exit(1)
    return cfg
 
 
def _build_run_overview(context: dict) -> dict:
    """!
    @brief Build timestep-independent run metadata for summarize.
    @param[in] context Summary context returned by `_build_summary_context()`.
    @return Curated run metadata mapping.
    """
    manifest = context["manifest"]
    software = manifest.get("software") if isinstance(manifest.get("software"), dict) else {}
    return {
        "run_id": manifest.get("run_id", os.path.basename(context["run_dir"])),
        "run_dir": context["run_dir"],
        "created_at": manifest.get("created_at"),
        "launch_mode": manifest.get("launch_mode"),
        "release_version": software.get("release_version"),
        "build_id": software.get("build_id"),
        "git_commit": software.get("git_commit", manifest.get("git_commit")),
        "solver_num_procs": manifest.get("solver_num_procs", manifest.get("num_procs")),
        "post_num_procs": manifest.get("post_num_procs"),
        "stages_requested": manifest.get("stages_requested"),
        "stages_completed_or_submitted": manifest.get("stages_completed_or_submitted"),
    }
 
 
def _summarize_turbulence(turbulence_cfg: dict) -> dict:
    """!
    @brief Build compact turbulence and wall-model selections.
    @param[in] turbulence_cfg Case turbulence configuration mapping.
    @return Curated turbulence and wall-model mapping.
    """
    result = {}
    for key in ("les", "wall_function"):
        value = turbulence_cfg.get(key)
        if isinstance(value, dict):
            result[key] = {
                "enabled": value.get("enabled", True),
                "model": value.get("model"),
                **{k: v for k, v in value.items() if k not in {"enabled", "model"}},
            }
        elif value is not None:
            result[key] = value
    return result
 
 
def _build_case_overview(context: dict) -> dict:
    """!
    @brief Build a curated case.yml summary with useful derived quantities.
    @param[in] context Summary context returned by `_build_summary_context()`.
    @return Curated case configuration mapping.
    """
    cfg = _require_summary_config(context, "case")
    props = cfg.get("properties", {})
    scaling = props.get("scaling", {})
    fluid = props.get("fluid", {})
    run = cfg.get("run_control", {})
    grid = cfg.get("grid", {})
    models = cfg.get("models", {})
    domain = models.get("domain", {})
    physics = models.get("physics", {})
    particles = physics.get("particles", {})
    start = int(run.get("start_step", 0))
    total = int(run.get("total_steps", 0))
    dt = float(run.get("dt_physical", 0.0))
    length_ref = float(scaling.get("length_ref"))
    velocity_ref = float(scaling.get("velocity_ref"))
    density = float(fluid.get("density"))
    viscosity = float(fluid.get("viscosity"))
    prepared_bcs = validate_and_prepare_boundary_conditions(cfg)
    first_block_faces = {row["face"]: row for row in prepared_bcs[0]}
    periodic_axes = {
        "i": first_block_faces["-Xi"]["type"] == "PERIODIC",
        "j": first_block_faces["-Eta"]["type"] == "PERIODIC",
        "k": first_block_faces["-Zeta"]["type"] == "PERIODIC",
    }
    bc_blocks = []
    for block_idx, block in enumerate(prepared_bcs):
        bc_blocks.append(
            {
                "block": block_idx,
                "faces": [
                    {"face": row["face"], "type": row["type"], "handler": row["handler"]}
                    for row in block
                ],
            }
        )
    return {
        "run_control": {
            "start_step": start,
            "total_steps": total,
            "end_step": start + total,
            "dt_physical": dt,
            "duration_physical": total * dt,
            "dt_nondimensional": to_solver_units(
                dt, ("case", "run_control", "dt_physical"),
                {"length_ref": length_ref, "velocity_ref": velocity_ref}),
        },
        "properties": {
            "length_ref": length_ref,
            "velocity_ref": velocity_ref,
            "density": density,
            "viscosity": viscosity,
            "reynolds_number": density * velocity_ref * length_ref / viscosity if viscosity else None,
            "initial_conditions": props.get("initial_conditions", {}),
        },
        "grid": {
            "mode": grid.get("mode"),
            "processor_layout": resolve_grid_da_processor_layout(grid),
            "programmatic_settings": grid.get("programmatic_settings") if grid.get("mode") == "programmatic_c" else None,
            "source_file": grid.get("source_file"),
        },
        "domain": {
            "blocks": domain.get("blocks", 1),
            "dimensionality": physics.get("dimensionality", "3D"),
            "periodic": periodic_axes,
        },
        "physics": {
            "fsi": physics.get("fsi", {}),
            "particles": particles,
            "turbulence": _summarize_turbulence(physics.get("turbulence", {}) or {}),
        },
        "boundary_conditions": bc_blocks,
    }
 
 
def _summary_scalar_transport(context: dict, solver_cfg: dict) -> dict:
    """!
    @brief Scalar-transport parameters as the run resolves them, wherever they are set.
    @param[in] context Summary context returned by `_build_summary_context()`.
    @param[in] solver_cfg Parsed solver configuration.
    @return Mapping of parameter name to value; empty when unresolvable.
    """
    try:
        return resolve_scalar_transport(context.get("case_cfg") or {}, solver_cfg)
    except ValueError:
        return {}
 
 
def _build_solver_overview(context: dict) -> dict:
    """!
    @brief Build a curated solver.yml summary with normalized selections.
    @param[in] context Summary context returned by `_build_summary_context()`.
    @return Curated solver configuration mapping.
    """
    cfg = _require_summary_config(context, "solver")
    strategy = cfg.get("strategy", {}) or {}
    selected = normalize_momentum_solver_type(strategy.get("momentum_solver", "Dual Time Picard Jameson RK"))
    momentum_cfg = cfg.get("momentum_solver", {}) or {}
    dualtime = momentum_cfg.get("dual_time_picard_jameson_rk", momentum_cfg.get("dual_time_picard_rk4", {})) or {}
    newton_krylov = momentum_cfg.get("newton_krylov", {}) or {}
    poisson = cfg.get("poisson_solver", cfg.get("pressure_solver", {})) or {}
    operation_mode = cfg.get("operation_mode", {}) or {}
    operation_mode = {
        **operation_mode,
        "eulerian_field_source": normalize_eulerian_field_source(operation_mode.get("eulerian_field_source", "solve")),
    }
    if operation_mode.get("analytical_type") is not None:
        operation_mode["analytical_type"] = normalize_analytical_type(operation_mode["analytical_type"])
    passthrough = cfg.get("petsc_passthrough_options", {}) or {}
    return {
        "operation_mode": operation_mode,
        "momentum": {
            "type": selected,
            "central_diff": bool(strategy.get("central_diff", False)),
            "tolerances": cfg.get("tolerances", {}),
            "controls": newton_krylov if selected == "newton_krylov" else dualtime,
        },
        "poisson": poisson,
        "interpolation": cfg.get("interpolation", {"method": "Trilinear"}),
        "scalar_transport": _summary_scalar_transport(context, cfg),
        "verification": cfg.get("verification", {}),
        "petsc_passthrough": {"count": len(passthrough), "options": sorted(passthrough.keys())},
    }
 
 
def _build_monitor_overview(context: dict) -> dict:
    """!
    @brief Build a curated monitor.yml summary with resolved defaults.
    @param[in] context Summary context returned by `_build_summary_context()`.
    @return Curated monitor configuration mapping.
    """
    cfg = _require_summary_config(context, "monitor")
    logging_cfg = cfg.get("logging", {}) or {}
    io_cfg = cfg.get("io", {}) or {}
    diagnostics = resolve_diagnostics_config(cfg, context["run_dir"], "Solver")
    monitoring_flags = resolve_solver_monitoring_flags(cfg)
    solution_monitoring = normalize_solution_monitoring_config(cfg)
    enabled_petsc = sorted(key for key, value in diagnostics["petsc"].items() if value not in (False, None))
    return {
        "logging": {
            "verbosity": logging_cfg.get("verbosity", "WARNING"),
            "enabled_functions": logging_cfg.get("enabled_functions", []),
        },
        "profiling": resolve_profiling_config(cfg),
        "diagnostics": {
            "enabled_petsc": enabled_petsc,
            "petsc": diagnostics["petsc"],
            "runtime_memory_log": diagnostics["runtime_memory_log"],
        },
        "io": {
            "data_output_frequency": io_cfg.get("data_output_frequency"),
            "particle_console_output_frequency": resolve_particle_console_output_frequency(io_cfg),
            "particle_log_interval": io_cfg.get("particle_log_interval"),
            "directories": {
                "output": CANONICAL_RUN_PATHS["output"],
                "restart": CANONICAL_RUN_PATHS["restart"],
                "logs": CANONICAL_RUN_PATHS["logs"],
                "analysis": CANONICAL_RUN_PATHS["analysis"],
            },
        },
        "solver_monitoring": {
            "enabled_flags": sorted(flag for flag, value in monitoring_flags.items() if value not in (False, None)),
            "flags": monitoring_flags,
        },
        "solution_monitoring": solution_monitoring,
    }
 
 
def _parse_continuity_metrics_log(log_dir: str) -> "tuple[dict, list[int]]":
    """!
    @brief Read the continuity record into rows by step (one per block) plus observed order.
    @param[in] log_dir Run log directory.
    @return Mapping step -> list of block rows, and the order steps first appeared.
    """
    rows_by_step, step_order = {}, []
    for _, row in _continuity_rows(log_dir)[1]:
        step = row["step"]
        if step not in rows_by_step:
            step_order.append(step)
            rows_by_step[step] = {}
        rows_by_step[step][row["block"]] = {key: value for key, value in row.items() if key != "step"}
    return {step: list(blocks.values()) for step, blocks in rows_by_step.items()}, step_order
 
 
def _parse_particle_metrics_log(log_dir: str, metrics_dir: str) -> "tuple[dict, list[int]]":
    """!
    @brief Read the per-step particle record into rows by step plus observed order.
    @param[in] log_dir Run log directory.
    @param[in] metrics_dir Run analysis metrics directory.
    @return Mapping step -> row, and the steps in file order.
    """
    rows_by_step, step_order = {}, []
    for _, row in _particle_step_rows(log_dir, metrics_dir)[1]:
        rows_by_step[row["step"]] = {key: value for key, value in row.items() if key != "step"}
        step_order.append(row["step"])
    return rows_by_step, step_order
 
 
def _parse_momentum_convergence_logs(log_dir: str) -> "tuple[dict, dict, list[int]]":
    """!
    @brief Read the per-block momentum records (Picard history, Newton summary) into rows by step.
    @param[in] log_dir Run log directory.
    @return Rows by step and block, source path per block, and step order.
    """
    rows_by_step, sources, step_order = {}, {}, []
    # Per (step, block): accepted/rejected trial counts and the last committed state.
    state = {}
    for block, path, rows in _picard_history_rows(log_dir):
        sources[block] = path
        for _, row in rows:
            step = row["step"]
            step_order.append(step)
            entry = state.setdefault((step, block), {"accepted_count": 0, "rejected_count": 0,
                                                    "last_accepted": None, "last_rejected": None})
            display = {key: value for key, value in row.items() if key != "step"}
            if row.get("status") == "accepted":
                entry["accepted_count"] += 1
                entry["last_accepted"] = display
            else:
                entry["rejected_count"] += 1
                entry["last_rejected"] = display
    for (step, block), entry in state.items():
        display_row = entry["last_accepted"] or entry["last_rejected"]
        if display_row:
            rows_by_step.setdefault(step, {})[block] = {
                **display_row,
                "accepted_count": entry["accepted_count"],
                "rejected_count": entry["rejected_count"],
            }
    for file_block, path, rows in _newton_summary_rows(log_dir):
        sources[file_block] = path
        for _, row in rows:
            step_order.append(row["step"])
            rows_by_step.setdefault(row["step"], {})[row["block"]] = {
                key: value for key, value in row.items() if key != "step"}
    return rows_by_step, sources, step_order
 
 
def _parse_poisson_convergence_logs(log_dir: str) -> "tuple[dict, dict, list[int]]":
    """!
    @brief Read the per-block Poisson histories into each step's last iteration.
    @param[in] log_dir Run log directory.
    @return Rows by step and block, source path per block, and step order.
    """
    rows_by_step, sources, step_order = {}, {}, []
    for block, path, rows in _poisson_history_rows(log_dir):
        sources[block] = path
        for _, row in rows:
            step_order.append(row["step"])
            rows_by_step.setdefault(row["step"], {})[block] = {
                key: value for key, value in row.items() if key not in ("step",)}
    return rows_by_step, sources, step_order
 
 
def _parse_profiling_timestep_csv(filepath: str) -> "tuple[dict, list[int]]":
    """!
    @brief Parse profiling timestep CSV into latest rows by step plus observed order.
    @param[in] filepath Argument passed to `_parse_profiling_timestep_csv()`.
    @return Value returned by `_parse_profiling_timestep_csv()`.
    """
    rows_by_step = {}
    step_order = []
    active_step = None
    if not os.path.isfile(filepath):
        return rows_by_step, step_order
 
    with open(filepath, "r", encoding="utf-8", errors="replace", newline="") as f:
        reader = csv.DictReader(f)
        for row in reader:
            step = _parse_int_loose(row.get("step"))
            if step is None:
                continue
            if step != active_step:
                active_step = step
                step_order.append(step)
                rows_by_step[step] = []
            rows_by_step.setdefault(step, []).append(
                {
                    "function": row.get("function"),
                    "calls": _parse_int_loose(row.get("calls")),
                    "step_time_s": _parse_float_loose(row.get("step_time_s")),
                }
            )
    return rows_by_step, step_order
 
 
def _parse_runtime_memory_log(filepath: str) -> "tuple[dict, list[int], dict]":
    """!
    @brief Read the runtime memory record into rows by step and its final status.
    @param[in] filepath Runtime memory log path.
    @return Tuple of rows by step, observed step order, and final/shutdown metadata.
    """
    rows_by_step, step_order = {}, []
    final_row = latest_sample_row = max_process_change_mb = None
    step_walls = []
    if not os.path.isfile(filepath):
        return rows_by_step, step_order, {"available": False}
    for _, row in _runtime_memory_rows(filepath):
        if row.get("step_wall_s") is not None:
            step_walls.append(row["step_wall_s"])
        change = row.get("process_change_mb_max")
        if change is not None:
            max_process_change_mb = change if max_process_change_mb is None else max(max_process_change_mb, change)
        if row["event"] in {"Step", "Post"}:
            rows_by_step[row["step"]] = row
            step_order.append(row["step"])
            latest_sample_row = row
        elif row["event"] in {"Shutdown", "Final"}:
            final_row = row
    meta = {
        "available": bool(rows_by_step or final_row),
        "source": filepath,
        "final_event": final_row.get("event") if final_row else None,
        "final_reason": final_row.get("reason") if final_row else None,
        "max_process_change_mb": max_process_change_mb,
        "mean_step_wall_s": (sum(step_walls) / len(step_walls)) if step_walls else None,
        "latest_sample_row": latest_sample_row,
        "final_row": final_row,
    }
    return rows_by_step, step_order, meta
 
 
def _parse_solution_convergence_log(log_dir: str) -> "tuple[dict, list[int]]":
    """!
    @brief Read the solution-convergence record into rows by step plus observed order.
    @param[in] log_dir Run log directory.
    @return Mapping step -> row of every column, and the steps in file order.
    """
    rows_by_step, step_order = {}, []
    for _, row in _solution_convergence_rows(log_dir)[1]:
        rows_by_step[row["step"]] = row
        step_order.append(row["step"])
    return rows_by_step, step_order
 
 
def _find_solver_stream_log_candidates(run_dir: str, log_dir: str) -> "list[str]":
    """!
    @brief Return plausible solver stream logs for local and Slurm runs.
    @param[in] run_dir Argument passed to `_find_solver_stream_log_candidates()`.
    @param[in] log_dir Argument passed to `_find_solver_stream_log_candidates()`.
    @return Value returned by `_find_solver_stream_log_candidates()`.
    """
    patterns = [
        os.path.join(run_dir, "scheduler", "*_solver.log"),
        os.path.join(run_dir, "scheduler", "solver_*.out"),
        os.path.join(log_dir, "*_solver.log"),
    ]
    found = []
    seen = set()
    for pattern in patterns:
        for path in sorted(glob.glob(pattern), key=os.path.getmtime, reverse=True):
            if path not in seen:
                seen.add(path)
                found.append(path)
    return found
 
 
def _parse_particle_snapshot_file(filepath: str) -> dict:
    """!
    @brief Parse sampled particle snapshots from a solver stream log.
    @param[in] filepath Argument passed to `_parse_particle_snapshot_file()`.
    @return Value returned by `_parse_particle_snapshot_file()`.
    """
    snapshots = {}
    if not os.path.isfile(filepath):
        return snapshots
 
    with open(filepath, "r", encoding="utf-8", errors="replace") as f:
        lines = f.readlines()
 
    idx = 0
    while idx < len(lines):
        match = re.search(r"Particle states at step\s+(\d+):", lines[idx])
        if not match:
            idx += 1
            continue
        step = int(match.group(1))
        idx += 1
        rows = []
        while idx < len(lines):
            stripped = lines[idx].strip()
            if re.search(r"Particle states at step\s+\d+:", lines[idx]):
                break
            if stripped.startswith("|"):
                parts = [part.strip() for part in stripped.split("|")[1:-1]]
                if len(parts) >= 6 and parts[0] != "Rank":
                    velocity = _extract_numeric_tuple(parts[4])
                    rows.append(
                        {
                            "rank": _parse_int_loose(parts[0]),
                            "pid": _parse_int_loose(parts[1]),
                            "cell": [int(value) for value in _extract_numeric_tuple(parts[2])],
                            "position": _extract_numeric_tuple(parts[3]),
                            "velocity": velocity,
                            "weights": _extract_numeric_tuple(parts[5]),
                            "sample_speed": math.sqrt(sum(component * component for component in velocity)) if len(velocity) == 3 else None,
                        }
                    )
            elif rows and (not stripped or stripped.startswith("Progress:")):
                break
            idx += 1
        if rows:
            snapshots[step] = rows
        else:
            snapshots.setdefault(step, [])
    return snapshots
 
 
def _find_previous_snapshot_step(snapshot_steps: "list[int]", step: int) -> "int | None":
    """!
    @brief Return the nearest earlier snapshot step when available.
    @param[in] snapshot_steps Argument passed to `_find_previous_snapshot_step()`.
    @param[in] step Argument passed to `_find_previous_snapshot_step()`.
    @return Value returned by `_find_previous_snapshot_step()`.
    """
    earlier_steps = [candidate for candidate in snapshot_steps if candidate < step]
    if not earlier_steps:
        return None
    return max(earlier_steps)
 
 
def _compute_particle_snapshot_delta(current_rows: "list[dict]", previous_rows: "list[dict]") -> dict:
    """!
    @brief Compute sampled deltas between two particle snapshot samples.
    @param[in] current_rows Argument passed to `_compute_particle_snapshot_delta()`.
    @param[in] previous_rows Argument passed to `_compute_particle_snapshot_delta()`.
    @return Value returned by `_compute_particle_snapshot_delta()`.
    """
    np = require_numpy()
    previous_by_pid = {
        row.get("pid"): row
        for row in previous_rows
        if row.get("pid") is not None
    }
    current_by_pid = {
        row.get("pid"): row
        for row in current_rows
        if row.get("pid") is not None
    }
    matched_pids = sorted(set(previous_by_pid) & set(current_by_pid))
    if not matched_pids:
        return {"available": False}
 
    displacements = []
    rank_migrations = 0
    cell_changes = 0
    speed_changes = []
    for pid in matched_pids:
        current_row = current_by_pid[pid]
        previous_row = previous_by_pid[pid]
        current_pos = current_row.get("position") or []
        previous_pos = previous_row.get("position") or []
        if len(current_pos) == len(previous_pos) and current_pos:
            displacements.append(
                math.sqrt(
                    sum(
                        (float(current_pos[idx]) - float(previous_pos[idx])) ** 2
                        for idx in range(len(current_pos))
                    )
                )
            )
        current_speed = current_row.get("sample_speed")
        previous_speed = previous_row.get("sample_speed")
        if current_speed is not None and previous_speed is not None:
            speed_changes.append(float(current_speed) - float(previous_speed))
        if current_row.get("rank") is not None and previous_row.get("rank") is not None:
            if current_row["rank"] != previous_row["rank"]:
                rank_migrations += 1
        if current_row.get("cell") and previous_row.get("cell"):
            if current_row["cell"] != previous_row["cell"]:
                cell_changes += 1
 
    payload = {
        "available": True,
        "matched_pids": len(matched_pids),
        "new_count": len(set(current_by_pid) - set(previous_by_pid)),
        "gone_count": len(set(previous_by_pid) - set(current_by_pid)),
        "rank_migrations": rank_migrations,
        "cell_changes": cell_changes,
    }
    if displacements:
        payload["mean_displacement"] = float(np.mean(displacements))
        payload["max_displacement"] = float(np.max(displacements))
    if speed_changes:
        payload["mean_speed_change"] = float(np.mean(speed_changes))
        payload["max_abs_speed_change"] = float(np.max(np.abs(speed_changes)))
    return payload
 
 
def _build_particle_snapshot_summary(
    source: str,
    step: int,
    rows: "list[dict]",
    preview_rows: int,
    particle_console_output_freq,
    particle_log_interval,
    previous_step: "int | None" = None,
    previous_rows: "list[dict] | None" = None,
) -> dict:
    """!
    @brief Build sampled diagnostics for one particle console snapshot.
    @param[in] source Argument passed to `_build_particle_snapshot_summary()`.
    @param[in] step Argument passed to `_build_particle_snapshot_summary()`.
    @param[in] rows Argument passed to `_build_particle_snapshot_summary()`.
    @param[in] preview_rows Argument passed to `_build_particle_snapshot_summary()`.
    @param[in] particle_console_output_freq Argument passed to `_build_particle_snapshot_summary()`.
    @param[in] particle_log_interval Argument passed to `_build_particle_snapshot_summary()`.
    @param[in] previous_step Argument passed to `_build_particle_snapshot_summary()`.
    @param[in] previous_rows Argument passed to `_build_particle_snapshot_summary()`.
    @return Value returned by `_build_particle_snapshot_summary()`.
    """
    np = require_numpy()
    payload = {
        "available": True,
        "sampled": True,
        "source": source,
        "step": step,
        "sampled_rows": len(rows),
        "preview_rows": rows[:preview_rows],
        "cadence": {
            "particle_console_output_frequency": particle_console_output_freq,
            "particle_log_interval": particle_log_interval,
        },
    }
    if not rows:
        return payload
 
    rank_counts = {}
    duplicate_pid_count = 0
    duplicate_cell_count = 0
    nan_count = 0
    inf_count = 0
    zero_weight_count = 0
    negative_weight_count = 0
    unique_pid_count = 0
 
    seen_pids = set()
    cell_counter = {}
    position_components = [[], [], []]
    weight_components = {}
    speeds = []
 
    for row in rows:
        pid = row.get("pid")
        if pid is not None:
            if pid in seen_pids:
                duplicate_pid_count += 1
            else:
                seen_pids.add(pid)
        rank = row.get("rank")
        if rank is not None:
            rank_counts[str(rank)] = rank_counts.get(str(rank), 0) + 1
 
        cell = row.get("cell") or []
        if cell:
            key = tuple(cell)
            cell_counter[key] = cell_counter.get(key, 0) + 1
 
        position = row.get("position") or []
        for idx, value in enumerate(position[:3]):
            if not np.isfinite(value):
                if np.isnan(value):
                    nan_count += 1
                else:
                    inf_count += 1
                continue
            position_components[idx].append(float(value))
 
        velocity = row.get("velocity") or []
        if any(not np.isfinite(value) for value in velocity):
            for value in velocity:
                if not np.isfinite(value):
                    if np.isnan(value):
                        nan_count += 1
                    else:
                        inf_count += 1
        speed = row.get("sample_speed")
        if speed is not None and np.isfinite(speed):
            speeds.append(float(speed))
 
        weights = row.get("weights") or []
        for idx, value in enumerate(weights):
            if not np.isfinite(value):
                if np.isnan(value):
                    nan_count += 1
                else:
                    inf_count += 1
                continue
            numeric = float(value)
            weight_components.setdefault(idx, []).append(numeric)
            if abs(numeric) <= 1.0e-15:
                zero_weight_count += 1
            if numeric < 0.0:
                negative_weight_count += 1
 
    unique_pid_count = len(seen_pids)
    duplicate_cell_count = sum(1 for count in cell_counter.values() if count > 1)
 
    payload["sampled_distribution"] = {
        "unique_cells": len(cell_counter),
        "duplicate_cells": duplicate_cell_count,
        "rank_counts": rank_counts,
        "unique_pids": unique_pid_count,
    }
    payload["checks"] = {
        "duplicate_pid_count": duplicate_pid_count,
        "nan_count": nan_count,
        "inf_count": inf_count,
        "zero_weight_count": zero_weight_count,
        "negative_weight_count": negative_weight_count,
    }
 
    if speeds:
        payload["speed"] = {
            "min": float(np.min(speeds)),
            "mean": float(np.mean(speeds)),
            "max": float(np.max(speeds)),
            "std": float(np.std(speeds)),
            "stagnant_count": sum(1 for speed in speeds if abs(speed) < 1.0e-6),
        }
 
        fastest_rows = sorted(
            [row for row in rows if row.get("sample_speed") is not None],
            key=lambda row: row["sample_speed"],
            reverse=True,
        )[:3]
        payload["top_speeds"] = [
            {
                "pid": row.get("pid"),
                "rank": row.get("rank"),
                "speed": row.get("sample_speed"),
                "cell": row.get("cell"),
            }
            for row in fastest_rows
        ]
 
    if any(position_components):
        axes = ["x", "y", "z"]
        payload["position_bounds"] = {}
        centroid = []
        for idx, axis in enumerate(axes):
            values = position_components[idx]
            if values:
                payload["position_bounds"][axis] = [float(np.min(values)), float(np.max(values))]
                centroid.append(float(np.mean(values)))
            else:
                centroid.append(None)
        payload["position_centroid"] = centroid
 
    if weight_components:
        payload["weights"] = {}
        for idx, values in sorted(weight_components.items()):
            payload["weights"][f"component_{idx}"] = {
                "min": float(np.min(values)),
                "max": float(np.max(values)),
            }
 
    delta_summary = {"available": False}
    if previous_step is not None and previous_rows:
        delta_summary = _compute_particle_snapshot_delta(rows, previous_rows)
        if delta_summary.get("available"):
            delta_summary["previous_step"] = previous_step
    payload["delta_from_previous_snapshot"] = delta_summary
    return payload
 
 
def _find_particle_snapshot_for_step(
    run_dir: str,
    log_dir: str,
    step: int,
    preview_rows: int,
    particle_console_output_freq,
    particle_log_interval,
) -> dict:
    """!
    @brief Locate and summarize a particle console snapshot for one step.
    @param[in] run_dir Argument passed to `_find_particle_snapshot_for_step()`.
    @param[in] log_dir Argument passed to `_find_particle_snapshot_for_step()`.
    @param[in] step Argument passed to `_find_particle_snapshot_for_step()`.
    @param[in] preview_rows Argument passed to `_find_particle_snapshot_for_step()`.
    @param[in] particle_console_output_freq Argument passed to `_find_particle_snapshot_for_step()`.
    @param[in] particle_log_interval Argument passed to `_find_particle_snapshot_for_step()`.
    @return Value returned by `_find_particle_snapshot_for_step()`.
    """
    best = None
    for path in _find_solver_stream_log_candidates(run_dir, log_dir):
        snapshots = _parse_particle_snapshot_file(path)
        rows = snapshots.get(step)
        if not rows:
            continue
        if best is None or len(rows) > len(best["rows"]):
            best = {"source": path, "rows": rows, "snapshots": snapshots}
 
    if not best:
        return {"available": False}
 
    previous_step = _find_previous_snapshot_step(list(best["snapshots"].keys()), step)
    previous_rows = best["snapshots"].get(previous_step, []) if previous_step is not None else None
    return _build_particle_snapshot_summary(
        best["source"],
        step,
        best["rows"],
        preview_rows,
        particle_console_output_freq=particle_console_output_freq,
        particle_log_interval=particle_log_interval,
        previous_step=previous_step,
        previous_rows=previous_rows,
    )
 
 
def _resolve_summary_step(
    requested_step,
    continuity_rows,
    particle_rows,
    momentum_rows,
    poisson_rows,
    profiling_rows,
    memory_rows=None,
    convergence_rows=None,
    step_orders=None,
    selection_mode: str = "latest",
):
    """!
    @brief Select a step to summarize from available metric artifacts.
    @param[in] requested_step Argument passed to `_resolve_summary_step()`.
    @param[in] continuity_rows Argument passed to `_resolve_summary_step()`.
    @param[in] particle_rows Argument passed to `_resolve_summary_step()`.
    @param[in] momentum_rows Argument passed to `_resolve_summary_step()`.
    @param[in] poisson_rows Argument passed to `_resolve_summary_step()`.
    @param[in] profiling_rows Argument passed to `_resolve_summary_step()`.
    @param[in] memory_rows Argument passed to `_resolve_summary_step()`.
    @param[in] convergence_rows Argument passed to `_resolve_summary_step()`.
    @param[in] step_orders Argument passed to `_resolve_summary_step()`.
    @param[in] selection_mode Argument passed to `_resolve_summary_step()`.
    @return Value returned by `_resolve_summary_step()`.
    """
    if memory_rows is None:
        memory_rows = {}
    if convergence_rows is None:
        convergence_rows = {}
    if step_orders is None:
        step_orders = []
    available_steps = (
        set(continuity_rows) | set(particle_rows) | set(momentum_rows)
        | set(poisson_rows) | set(profiling_rows) | set(memory_rows) | set(convergence_rows)
    )
    if not available_steps:
        return None, []
 
    if requested_step is not None:
        return requested_step, sorted(available_steps)
 
    if selection_mode == "max_step":
        return max(available_steps), sorted(available_steps)
 
    for order in step_orders:
        if order:
            return order[-1], sorted(available_steps)
    return max(available_steps), sorted(available_steps)
 
 
def _format_summary_float(value, spec: str = ".6e", missing: str = "n/a") -> str:
    """!
    @brief Format optional numeric values for summary text output.
    @param[in] value Argument passed to `_format_summary_float()`.
    @param[in] spec Argument passed to `_format_summary_float()`.
    @param[in] missing Argument passed to `_format_summary_float()`.
    @return Value returned by `_format_summary_float()`.
    """
    if value is None:
        return missing
    return format(value, spec)
 
 
def _summary_source_mtime(paths) -> float:
    """!
    @brief Return the newest modification time among one or more summary sources.
    @param[in] paths Path string, iterable of paths, or mapping of paths.
    @return Newest modification time, or -1.0 when no source exists.
    """
    if isinstance(paths, dict):
        paths = paths.values()
    elif isinstance(paths, str):
        paths = [paths]
    newest = -1.0
    for path in paths or []:
        if path and os.path.isfile(path):
            newest = max(newest, os.path.getmtime(path))
    return newest
 
 
def _order_summary_step_orders(sources: "list[tuple[list[int], object]]") -> "list[list[int]]":
    """!
    @brief Order observed step sequences by the recency of their source files.
    @param[in] sources Pairs of observed steps and filesystem source path(s).
    @return Step-order lists sorted so active append sources are considered first.
    """
    ranked = []
    for priority, (order, paths) in enumerate(sources):
        if order:
            ranked.append((_summary_source_mtime(paths), priority, order))
    ranked.sort(key=lambda item: (-item[0], item[1]))
    return [order for _, _, order in ranked]
 
 
def build_run_summary_payload(run_dir: str, step: "int | None" = None, snapshot_rows: int = 5, selection_mode: str = "latest") -> dict:
    """!
    @brief Build a read-only run-step summary from existing PICurv artifacts.
    @param[in] run_dir Argument passed to `build_run_summary_payload()`.
    @param[in] step Argument passed to `build_run_summary_payload()`.
    @param[in] snapshot_rows Argument passed to `build_run_summary_payload()`.
    @param[in] selection_mode Argument passed to `build_run_summary_payload()`.
    @return Value returned by `build_run_summary_payload()`.
    """
    context = _build_summary_context(run_dir)
    log_dir = context["log_dir"]
    metrics_dir = context["metrics_dir"]
    continuity_path = (_log_family_path(log_dir, "Continuity_Metrics")
                       or os.path.join(log_dir, "Continuity_Metrics.csv"))
    particle_metrics_path = (_particle_step_rows(log_dir, metrics_dir)[0]
                             or os.path.join(metrics_dir, "search_metrics.csv"))
 
    continuity_rows, continuity_order = _parse_continuity_metrics_log(log_dir)
    particle_rows, particle_order = _parse_particle_metrics_log(log_dir, metrics_dir)
    momentum_rows, momentum_sources, momentum_order = _parse_momentum_convergence_logs(log_dir)
    poisson_rows, poisson_sources, poisson_order = _parse_poisson_convergence_logs(log_dir)
 
    profiling_rows = {}
    profiling_order = []
    profiling_path = os.path.join(log_dir, PROFILING_TIMESTEP_FILE)
    if context["profiling_cfg"].get("mode") != "off":
        profiling_rows, profiling_order = _parse_profiling_timestep_csv(profiling_path)
 
    memory_path = _log_family_path(log_dir, "Runtime_Memory") or os.path.join(log_dir, RUNTIME_MEMORY_FILE)
    memory_rows, memory_order, memory_meta = _parse_runtime_memory_log(memory_path)
 
    convergence_log_path = (_log_family_path(log_dir, "solution_convergence")
                            or os.path.join(log_dir, "solution_convergence.csv"))
    convergence_rows, convergence_order = _parse_solution_convergence_log(log_dir)
    step_orders = _order_summary_step_orders(
        [
            (continuity_order, continuity_path),
            (particle_order, particle_metrics_path),
            (convergence_order, convergence_log_path),
            (profiling_order, profiling_path),
            (memory_order, memory_path),
            (momentum_order, momentum_sources),
            (poisson_order, poisson_sources),
        ]
    )
 
    resolved_step, available_steps = _resolve_summary_step(
        step,
        continuity_rows,
        particle_rows,
        momentum_rows,
        poisson_rows,
        profiling_rows,
        convergence_rows,
        memory_rows,
        step_orders=step_orders,
        selection_mode=selection_mode,
    )
    if resolved_step is None:
        emit_structured_error(
            ERROR_CODE_CFG_FILE_NOT_FOUND,
            key="summary",
            file_path=log_dir,
            message="No summary-capable run artifacts were found under the run log directory.",
            hint="Run the solver first, then retry summarize on a run directory that contains continuity or solver convergence logs.",
        )
        sys.exit(1)
 
    if step is not None and step not in set(available_steps):
        emit_structured_error(
            ERROR_CODE_CFG_INVALID_VALUE,
            key="step",
            file_path=context["run_dir"],
            message=f"Requested step {step} is not present in the available summary artifacts.",
            hint=f"Available steps include: {available_steps[:10]}{'...' if len(available_steps) > 10 else ''}",
        )
        sys.exit(1)
 
    continuity_step_rows = sorted(continuity_rows.get(resolved_step, []), key=lambda row: row["block"])
    continuity_summary = {"available": bool(continuity_step_rows), "blocks": continuity_step_rows}
    if continuity_step_rows:
        divergence_values = [
            abs(row["max_divergence"])
            for row in continuity_step_rows
            if row["max_divergence"] is not None
        ]
        continuity_summary["max_abs_divergence"] = max(divergence_values) if divergence_values else None
        continuity_summary["net_flux"] = continuity_step_rows[0].get("net_flux")
        continuity_summary["flux_in"] = continuity_step_rows[0].get("flux_in")
        continuity_summary["flux_out"] = continuity_step_rows[0].get("flux_out")
 
    momentum_step_rows = [row for _, row in sorted(momentum_rows.get(resolved_step, {}).items())]
    momentum_summary = {"available": bool(momentum_step_rows), "blocks": momentum_step_rows}
 
    poisson_step_rows = [row for _, row in sorted(poisson_rows.get(resolved_step, {}).items())]
    poisson_summary = {"available": bool(poisson_step_rows), "blocks": poisson_step_rows}
 
    particle_summary = {"available": resolved_step in particle_rows}
    if resolved_step in particle_rows:
        particle_summary.update(particle_rows[resolved_step])
 
    profiling_summary = {"available": resolved_step in profiling_rows}
    if resolved_step in profiling_rows:
        functions = sorted(
            profiling_rows[resolved_step],
            key=lambda row: (row.get("step_time_s") or 0.0),
            reverse=True,
        )
        profiling_summary["functions"] = functions
        profiling_summary["total_logged_step_time_s"] = sum(
            row.get("step_time_s") or 0.0 for row in functions
        )
 
    memory_summary = {"available": resolved_step in memory_rows}
    if resolved_step in memory_rows:
        memory_summary.update(memory_rows[resolved_step])
        memory_summary["source"] = memory_path
        memory_summary["max_process_change_mb"] = memory_meta.get("max_process_change_mb")
        memory_summary["mean_step_wall_s"] = memory_meta.get("mean_step_wall_s")
        memory_summary["final_event"] = memory_meta.get("final_event")
        memory_summary["final_reason"] = memory_meta.get("final_reason")
        memory_summary["selected_step"] = resolved_step
        memory_summary["step_match"] = True
    elif memory_meta.get("available"):
        latest_sample_row = memory_meta.get("latest_sample_row")
        if latest_sample_row:
            memory_summary.update(latest_sample_row)
        memory_summary.update(memory_meta)
        memory_summary["selected_step"] = resolved_step
        memory_summary["step_match"] = False
 
    snapshot_summary = {"available": False}
    if context["particle_console_output_freq"] and context["particle_console_output_freq"] > 0:
        snapshot_summary = _find_particle_snapshot_for_step(
            context["run_dir"],
            log_dir,
            resolved_step,
            preview_rows=max(1, snapshot_rows),
            particle_console_output_freq=context["particle_console_output_freq"],
            particle_log_interval=context["particle_log_interval"],
        )
 
    monitor_info = {
        "profiling_timestep_mode": context["profiling_cfg"].get("mode"),
        "profiling_timestep_file": PROFILING_TIMESTEP_FILE,
        "particle_console_output_frequency": context["particle_console_output_freq"],
        "particle_log_interval": context["particle_log_interval"],
    }
 
    return {
        "run_id": context["manifest"].get("run_id", os.path.basename(context["run_dir"])),
        "run_dir": context["run_dir"],
        "step": resolved_step,
        "selected_via": "explicit" if step is not None else ("max_step" if selection_mode == "max_step" else "latest_available"),
        "available_steps": available_steps,
        "launch_mode": context["manifest"].get("launch_mode"),
        "created_at": context["manifest"].get("created_at"),
        "monitor": monitor_info,
        "particles_configured": context["particle_count_cfg"],
        "sources": {
            "continuity_log": continuity_path if os.path.isfile(continuity_path) else None,
            "particle_metrics_log": particle_metrics_path if os.path.isfile(particle_metrics_path) else None,
            "momentum_logs": momentum_sources,
            "poisson_logs": poisson_sources,
            "profiling_timestep_csv": profiling_path if os.path.isfile(profiling_path) else None,
            "solution_convergence_log": convergence_log_path if os.path.isfile(convergence_log_path) else None,
            "runtime_memory_log": memory_path if os.path.isfile(memory_path) else None,
        },
        "continuity": continuity_summary,
        "momentum": momentum_summary,
        "poisson": poisson_summary,
        "particles": particle_summary,
        "particle_snapshot": snapshot_summary,
        "profiling": profiling_summary,
        "memory": memory_summary,
        "convergence": convergence_rows.get(resolved_step) if convergence_rows else None,
    }
 
 
def render_run_summary(payload: dict, output_format: str = "text"):
    """!
    @brief Render a run-step summary in human or JSON form.
    @param[in] payload Argument passed to `render_run_summary()`.
    @param[in] output_format Argument passed to `render_run_summary()`.
    """
    if output_format == "json":
        print(json.dumps(payload, indent=2, sort_keys=True))
        return
 
    print("\n" + "=" * 60)
    print("                     RUN STEP SUMMARY")
    print("=" * 60)
    print(f"  Run ID          : {payload.get('run_id')}")
    print(f"  Run directory   : {os.path.relpath(payload.get('run_dir'))}")
    print(f"  Step            : {payload.get('step')} ({payload.get('selected_via')})")
    if payload.get("launch_mode"):
        print(f"  Launch mode     : {payload.get('launch_mode')}")
    if payload.get("created_at"):
        print(f"  Created at      : {payload.get('created_at')}")
 
    continuity = payload.get("continuity", {})
    print("\n  Continuity:")
    if continuity.get("available"):
        if continuity.get("max_abs_divergence") is not None:
            print(f"    max |div|    : {continuity['max_abs_divergence']:.6e}")
        if continuity.get("net_flux") is not None:
            print(f"    net flux     : {continuity['net_flux']:.6e}")
        for row in continuity.get("blocks", []):
            print(
                "    "
                f"block {row['block']}: div={_format_summary_float(row.get('max_divergence'))} "
                f"rhs={_format_summary_float(row.get('rhs_sum'))} location={row['max_divergence_location']}"
            )
    else:
        print("    unavailable")
 
    momentum = payload.get("momentum", {})
    print("\n  Momentum:")
    if momentum.get("available"):
        for row in momentum.get("blocks", []):
            if row.get("solver") == "Newton Krylov":
                print(f"    block {row['block']}: solver=Newton Krylov")
                print(
                    f"      newton={row.get('newton_iterations')} "
                    f"krylov={row.get('krylov_iterations')} "
                    f"evals={row.get('residual_evaluations')}"
                )
                print(
                    f"      final={_format_summary_float(row.get('final_norm'))} "
                    f"reason={row.get('reason')} state={row.get('state')}"
                )
                continue
            status = row.get("status") or "unknown"
            accepted = row.get("accepted_count")
            rejected = row.get("rejected_count")
            counts_str = f" accepted={accepted} rejected={rejected}" if accepted is not None else ""
            # Phase 3+: logged as dtau (physical time) + cfl_eff (dimensionless Courant number).
            dtau_val = row.get("dtau")
            cfl_in   = row.get("cfl_eff")
            cfl_out  = row.get("cfl_eff_after")
            dtau_out = row.get("dtau_after")
            if cfl_in is not None and cfl_out is not None:
                cfl_str = f"cfl_eff {cfl_in:.4f}->{cfl_out:.4f}  dtau {_format_summary_float(dtau_val)}->{_format_summary_float(dtau_out)}"
            elif cfl_in is not None:
                cfl_str = f"cfl_eff={_format_summary_float(cfl_in, '.4f')}  dtau={_format_summary_float(dtau_val)}"
            else:
                cfl_str = "cfl_eff=n/a"
            ratio = row.get("trial_ratio")
            smoothed = row.get("smoothed_ratio")
            if ratio is not None and smoothed is not None:
                ratio_str = f"  ratio={_format_summary_float(ratio)} (ema={_format_summary_float(smoothed)})"
            elif ratio is not None:
                ratio_str = f"  ratio={_format_summary_float(ratio)}"
            else:
                ratio_str = ""
            print(f"    block {row['block']} [{status}]:{counts_str}  {cfl_str}{ratio_str}")
            print(
                f"      resid={_format_summary_float(row.get('residual_norm'))}"
                f"  delta={_format_summary_float(row.get('delta_norm'))}"
            )
    else:
        print("    unavailable")
 
    poisson = payload.get("poisson", {})
    print("\n  Poisson:")
    if poisson.get("available"):
        for row in poisson.get("blocks", []):
            print(
                "    "
                f"block {row['block']}: iter={row['iterations']} "
                f"true={_format_summary_float(row.get('true_norm'))} "
                f"rel={_format_summary_float(row.get('relative_norm'))}"
            )
    else:
        print("    unavailable")
 
    convergence = payload.get("convergence")
    print("\n  Solution Convergence:")
    if convergence is not None:
        mode = convergence.get("mode", "unknown")
        ref = convergence.get("ref")
        print(f"    mode           : {mode}  (ref={'yes' if ref else 'no'})")
        if mode in ("steady_deterministic", "transient"):
            print(f"    u_abs_l2       : {_format_summary_float(convergence.get('u_abs_l2'))}")
            print(f"    mean_speed     : {_format_summary_float(convergence.get('mean_speed'))}  drift={_format_summary_float(convergence.get('spd_abs'))}")
            print(f"    mean_ke        : {_format_summary_float(convergence.get('mean_ke'))}  drift={_format_summary_float(convergence.get('ke_abs'))}")
        elif mode == "periodic_deterministic":
            ph = convergence.get("ph")
            per = convergence.get("per")
            print(f"    phase          : {ph}/{per}")
            print(f"    u_abs_l2       : {_format_summary_float(convergence.get('u_abs_l2'))}")
            print(f"    mean_speed     : {_format_summary_float(convergence.get('mean_speed'))}  drift={_format_summary_float(convergence.get('spd_abs'))}")
            print(f"    mean_ke        : {_format_summary_float(convergence.get('mean_ke'))}  drift={_format_summary_float(convergence.get('ke_abs'))}")
        elif mode == "statistical_steady":
            print(f"    mean_speed     : {_format_summary_float(convergence.get('mean_speed'))}  win={_format_summary_float(convergence.get('spd_win'))}  win_drift={_format_summary_float(convergence.get('spd_win_abs'))}")
            print(f"    mean_ke        : {_format_summary_float(convergence.get('mean_ke'))}  win={_format_summary_float(convergence.get('ke_win'))}  win_drift={_format_summary_float(convergence.get('ke_win_abs'))}")
    else:
        print("    unavailable")
 
    particles = payload.get("particles", {})
    print("\n  Particles:")
    if particles.get("available"):
        loss_summary = f"lost={particles.get('lost_particles')}"
        if particles.get("lost_particles_cumulative") is not None:
            loss_summary = (
                f"lost(step/total)={particles.get('lost_particles')}/"
                f"{particles.get('lost_particles_cumulative')}"
            )
        if particles.get("exited_particles_cumulative") is not None:
            loss_summary += (
                f" exited(step/total)={particles.get('exited_particles')}/"
                f"{particles.get('exited_particles_cumulative')}"
            )
        print(
            "    "
            f"total={particles.get('total_particles')} {loss_summary} "
            f"migrated={particles.get('migrated_particles')} occupied={particles.get('occupied_cells')} "
            f"imbalance={_format_summary_float(particles.get('load_imbalance'), '.2f')}"
        )
    else:
        print("    unavailable")
 
    memory = payload.get("memory", {})
    print("\n  Runtime Memory:")
    if memory.get("available"):
        if memory.get("source"):
            print(f"    source        : {os.path.relpath(memory.get('source'))}")
        if memory.get("step") is not None and not memory.get("step_match", True):
            print(f"    memory step   : {memory.get('step')} (latest memory row; selected step {memory.get('selected_step')} has no row yet)")
        if memory.get("event"):
            print(f"    event         : {memory.get('event')}  reason={memory.get('reason', '-')}")
        print(f"    process max   : {_format_summary_float(memory.get('process_current_mb_max'), '.3f')} MB current, {_format_summary_float(memory.get('process_peak_mb_max'), '.3f')} MB peak")
        print(f"    PETSc max     : {_format_summary_float(memory.get('petsc_allocated_mb_max'), '.3f')} MB allocated, {_format_summary_float(memory.get('petsc_peak_allocated_mb_max'), '.3f')} MB peak")
        print(f"    max change    : {_format_summary_float(memory.get('max_process_change_mb'), '.3f')} MB")
        if memory.get("step_wall_s") is not None or memory.get("mean_step_wall_s") is not None:
            print(f"    step time     : {_format_summary_float(memory.get('step_wall_s'), '.4g')} s this step, "
                  f"{_format_summary_float(memory.get('mean_step_wall_s'), '.4g')} s mean (slowest rank)")
        if memory.get("final_reason"):
            print(f"    final reason  : {memory.get('final_reason')}")
        else:
            print("    final reason  : none recorded (still running, or stopped without a final row)")
    else:
        print("    unavailable")
 
    snapshot = payload.get("particle_snapshot", {})
    if snapshot.get("available"):
        print("\n  Particle Snapshot (sampled):")
        print(f"    source        : {os.path.relpath(snapshot.get('source'))}")
        cadence = snapshot.get("cadence", {})
        print(
            "    "
            f"cadence       : every {cadence.get('particle_console_output_frequency', 'n/a')} steps, "
            f"row interval {cadence.get('particle_log_interval', 'n/a')}"
        )
        print(f"    sampled rows  : {snapshot.get('sampled_rows')}")
        speed = snapshot.get("speed", {})
        if speed:
            print(
                "    "
                f"sampled speeds: min={_format_summary_float(speed.get('min'))} "
                f"mean={_format_summary_float(speed.get('mean'))} "
                f"max={_format_summary_float(speed.get('max'))} "
                f"std={_format_summary_float(speed.get('std'))} "
                f"stagnant(<1e-6)={speed.get('stagnant_count', 0)}"
            )
        bounds = snapshot.get("position_bounds", {})
        centroid = snapshot.get("position_centroid")
        if bounds:
            bound_parts = []
            for axis in ("x", "y", "z"):
                if axis in bounds:
                    bound_parts.append(
                        f"{axis}=[{_format_summary_float(bounds[axis][0])}, { _format_summary_float(bounds[axis][1])}]"
                    )
            print(f"    sampled bounds: {' '.join(bound_parts)}")
        if centroid:
            print(
                "    "
                f"sampled center: ({_format_summary_float(centroid[0])}, "
                f"{_format_summary_float(centroid[1])}, {_format_summary_float(centroid[2])})"
            )
        distribution = snapshot.get("sampled_distribution", {})
        if distribution:
            print(
                "    "
                f"sampled spread: unique_cells={distribution.get('unique_cells', 'n/a')} "
                f"duplicate_cells={distribution.get('duplicate_cells', 'n/a')} "
                f"unique_pids={distribution.get('unique_pids', 'n/a')} "
                f"ranks={distribution.get('rank_counts', {})}"
            )
        weights = snapshot.get("weights", {})
        if weights:
            weight_parts = []
            for component, summary in sorted(weights.items()):
                weight_parts.append(
                    f"{component}[min/max]=[{_format_summary_float(summary.get('min'))}, { _format_summary_float(summary.get('max'))}]"
                )
            print(f"    sampled weights: {' '.join(weight_parts)}")
        checks = snapshot.get("checks", {})
        if checks:
            print(
                "    "
                f"checks        : duplicate_pid={checks.get('duplicate_pid_count', 0)} "
                f"nan={checks.get('nan_count', 0)} inf={checks.get('inf_count', 0)} "
                f"zero_weight={checks.get('zero_weight_count', 0)} "
                f"negative_weight={checks.get('negative_weight_count', 0)}"
            )
        top_speeds = snapshot.get("top_speeds", [])
        if top_speeds:
            summary = ", ".join(
                f"pid={row.get('pid')} {_format_summary_float(row.get('speed'))}"
                for row in top_speeds
            )
            print(f"    top speeds    : {summary}")
        delta_summary = snapshot.get("delta_from_previous_snapshot", {})
        if delta_summary.get("available"):
            print(
                "    "
                f"vs prev snap  : step={delta_summary.get('previous_step')} "
                f"matched_pids={delta_summary.get('matched_pids')} "
                f"mean_disp={_format_summary_float(delta_summary.get('mean_displacement'))} "
                f"max_disp={_format_summary_float(delta_summary.get('max_displacement'))} "
                f"rank_moves={delta_summary.get('rank_migrations')} "
                f"cell_changes={delta_summary.get('cell_changes')} "
                f"new={delta_summary.get('new_count')} gone={delta_summary.get('gone_count')}"
            )
        print("    preview rows  :")
        for row in snapshot.get("preview_rows", []):
            print(
                "    "
                f"pid={row.get('pid')} rank={row.get('rank')} "
                f"cell={row.get('cell')} pos={row.get('position')} vel={row.get('velocity')}"
            )
 
    profiling = payload.get("profiling", {})
    print("\n  Profiling:")
    if profiling.get("available"):
        print(f"    total logged step time: {profiling.get('total_logged_step_time_s', 0.0):.6f}s")
        for row in profiling.get("functions", [])[:5]:
            print(
                "    "
                f"{row.get('function')}: calls={row.get('calls')} "
                f"time={_format_summary_float(row.get('step_time_s'), '.6f', '0.000000')}s"
            )
    else:
        print("    unavailable")
    print("=" * 60)
 
 
_CONFIG_SUMMARY_WIDTH = 78
 
 
def _summary_display_value(value) -> str:
    """!
    @brief Format one configuration-summary value for compact text output.
    @param[in] value Value to format.
    @return Compact human-readable value.
    """
    if value is None:
        return "-"
    if isinstance(value, bool):
        return "enabled" if value else "disabled"
    if isinstance(value, float):
        return f"{value:.6g}"
    if isinstance(value, (list, tuple)):
        return ", ".join(_summary_display_value(item) for item in value) if value else "none"
    if isinstance(value, dict):
        if not value:
            return "none"
        return ", ".join(f"{key}={_summary_display_value(item)}" for key, item in value.items())
    return str(value)
 
 
def _print_config_header(title: str, subtitle: "str | None" = None):
    """!
    @brief Print a strong dashboard-style configuration summary header.
    @param[in] title Section title.
    @param[in] subtitle Optional one-line section subtitle.
    """
    print("\n" + "=" * _CONFIG_SUMMARY_WIDTH)
    print(f"{title:^78}")
    if subtitle:
        print(f"{subtitle:^78}")
    print("=" * _CONFIG_SUMMARY_WIDTH)
 
 
def _print_config_group(title: str, rows: list):
    """!
    @brief Print an aligned configuration-summary field group.
    @param[in] title Group title.
    @param[in] rows Sequence of `(label, value)` pairs.
    """
    visible_rows = [(label, value) for label, value in rows if value is not None]
    if not visible_rows:
        return
    print(f"\n  {title}")
    print(f"  {'-' * (len(title) + 1)}")
    for label, value in visible_rows:
        print(f"    {label:<32} {_summary_display_value(value)}")
 
 
def _flatten_summary_mapping(mapping: dict, prefix: str = "") -> list:
    """!
    @brief Flatten nested summary mappings into readable dotted field rows.
    @param[in] mapping Mapping to flatten.
    @param[in] prefix Optional parent-field prefix.
    @return Sequence of `(field, value)` pairs.
    """
    rows = []
    for key, value in mapping.items():
        label = f"{prefix}.{key}" if prefix else str(key)
        if isinstance(value, dict) and value:
            rows.extend(_flatten_summary_mapping(value, label))
        else:
            rows.append((label, value))
    return rows
 
 
def _render_run_overview_text(summary: dict):
    """!
    @brief Render run metadata as a compact dashboard.
    @param[in] summary Curated run overview mapping.
    """
    _print_config_header("RUN OVERVIEW", summary.get("run_id"))
    _print_config_group(
        "Identity",
        [
            ("Run directory", os.path.relpath(summary.get("run_dir")) if summary.get("run_dir") else None),
            ("Created", summary.get("created_at")),
            ("Launch mode", summary.get("launch_mode")),
            ("PICurv release", summary.get("release_version")),
            ("Build", summary.get("build_id")),
            ("Git commit", summary.get("git_commit")),
        ],
    )
    _print_config_group(
        "Execution",
        [
            ("Solver MPI processes", summary.get("solver_num_procs")),
            ("Post MPI processes", summary.get("post_num_procs")),
            ("Stages requested", summary.get("stages_requested")),
            ("Stages ready/completed", summary.get("stages_completed_or_submitted")),
        ],
    )
 
 
def _render_case_summary_text(summary: dict):
    """!
    @brief Render the case summary as a glanceable simulation dashboard.
    @param[in] summary Curated case configuration mapping.
    """
    run = summary.get("run_control", {})
    props = summary.get("properties", {})
    grid = summary.get("grid", {})
    domain = summary.get("domain", {})
    physics = summary.get("physics", {})
    subtitle = (
        f"{domain.get('dimensionality', '-')} | {domain.get('blocks', '-')} block(s) | "
        f"Re={_summary_display_value(props.get('reynolds_number'))}"
    )
    _print_config_header("CASE SUMMARY", subtitle)
    _print_config_group(
        "Simulation",
        [
            ("Step range", f"{run.get('start_step')} -> {run.get('end_step')} ({run.get('total_steps')} steps)"),
            ("Physical timestep", run.get("dt_physical")),
            ("Nondimensional timestep", run.get("dt_nondimensional")),
            ("Physical duration", run.get("duration_physical")),
            ("Initial conditions", props.get("initial_conditions")),
        ],
    )
    _print_config_group(
        "Fluid And Scaling",
        [
            ("Reynolds number", props.get("reynolds_number")),
            ("Reference length", props.get("length_ref")),
            ("Reference velocity", props.get("velocity_ref")),
            ("Density", props.get("density")),
            ("Viscosity", props.get("viscosity")),
        ],
    )
    _print_config_group(
        "Domain And Grid",
        [
            ("Grid mode", grid.get("mode")),
            ("Blocks", domain.get("blocks")),
            ("Dimensionality", domain.get("dimensionality")),
            ("Periodic axes", domain.get("periodic")),
            ("MPI grid layout", grid.get("processor_layout")),
            ("Grid source", grid.get("source_file")),
        ],
    )
    if grid.get("programmatic_settings"):
        _print_config_group("Programmatic Grid", _flatten_summary_mapping(grid["programmatic_settings"]))
    _print_config_group(
        "Physics",
        [
            ("Particles", physics.get("particles")),
            ("FSI", physics.get("fsi")),
            ("Turbulence", physics.get("turbulence")),
            ("Statistics", physics.get("statistics")),
        ],
    )
    boundary_blocks = summary.get("boundary_conditions", [])
    if boundary_blocks:
        print("\n  Boundary Conditions")
        print("  --------------------")
        print(f"    {'Block':<7} {'Face':<8} {'Type':<12} Handler")
        print(f"    {'-' * 7} {'-' * 8} {'-' * 12} {'-' * 20}")
        for block in boundary_blocks:
            for face in block.get("faces", []):
                print(
                    f"    {block.get('block', '-')!s:<7} {face.get('face', '-'):<8} "
                    f"{face.get('type', '-'):<12} {face.get('handler', '-')}"
                )
 
 
def _render_solver_summary_text(summary: dict):
    """!
    @brief Render the solver summary as a glanceable numerical-method dashboard.
    @param[in] summary Curated solver configuration mapping.
    """
    momentum = summary.get("momentum", {})
    poisson = summary.get("poisson", {})
    operation = summary.get("operation_mode", {})
    subtitle = (
        f"Field: {operation.get('eulerian_field_source', '-')} | "
        f"Momentum: {momentum.get('type', '-')} | Poisson: {poisson.get('method', '-')}"
    )
    _print_config_header("SOLVER SUMMARY", subtitle)
    _print_config_group("Operation", _flatten_summary_mapping(operation))
    _print_config_group(
        "Primary Methods",
        [
            ("Momentum solver", momentum.get("type")),
            ("Central differencing", momentum.get("central_diff")),
            ("Poisson method", poisson.get("method")),
            ("Interpolation", summary.get("interpolation")),
            ("Convergence mode", summary.get("solution_convergence", {}).get("mode")),
        ],
    )
    _print_config_group("Momentum Tolerances", _flatten_summary_mapping(momentum.get("tolerances", {})))
    control_heading = (
        "Newton--Krylov Controls" if momentum.get("type") == "newton_krylov"
        else "Dual-Time Pseudo-Time Controls" if momentum.get("type") == "DUALTIME_PICARD_JAMESON_RK"
        else "Momentum Controls"
    )
    _print_config_group(control_heading, _flatten_summary_mapping(momentum.get("controls", {})))
    _print_config_group("Poisson Configuration", _flatten_summary_mapping(poisson))
    _print_config_group("Solution Convergence", _flatten_summary_mapping(summary.get("solution_convergence", {})))
    _print_config_group("Scalar Transport", _flatten_summary_mapping(summary.get("scalar_transport", {})))
    _print_config_group("Verification Sources", _flatten_summary_mapping(summary.get("verification", {})))
    passthrough = summary.get("petsc_passthrough", {})
    _print_config_group(
        "Advanced PETSc Options",
        [("Option count", passthrough.get("count")), ("Option names", passthrough.get("options"))],
    )
 
 
def _render_monitor_summary_text(summary: dict):
    """!
    @brief Render the monitor summary as a glanceable observability dashboard.
    @param[in] summary Curated monitor configuration mapping.
    """
    logging_cfg = summary.get("logging", {})
    profiling = summary.get("profiling", {})
    diagnostics = summary.get("diagnostics", {})
    io_cfg = summary.get("io", {})
    memory_log = diagnostics.get("runtime_memory_log", {})
    subtitle = (
        f"Verbosity: {logging_cfg.get('verbosity', '-')} | Profiling: {profiling.get('mode', '-')} | "
        f"Output every {_summary_display_value(io_cfg.get('data_output_frequency'))} steps"
    )
    _print_config_header("MONITOR SUMMARY", subtitle)
    _print_config_group(
        "Logging",
        [
            ("Verbosity", logging_cfg.get("verbosity")),
            ("Enabled functions", logging_cfg.get("enabled_functions")),
        ],
    )
    _print_config_group("Profiling", _flatten_summary_mapping(profiling))
    _print_config_group(
        "Output Cadence",
        [
            ("Field output", io_cfg.get("data_output_frequency")),
            ("Particle snapshots", io_cfg.get("particle_console_output_frequency")),
            ("Particle row interval", io_cfg.get("particle_log_interval")),
        ],
    )
    _print_config_group("Output Directories", _flatten_summary_mapping(io_cfg.get("directories", {})))
    _print_config_group(
        "Diagnostics",
        [
            ("Enabled PETSc diagnostics", diagnostics.get("enabled_petsc")),
            ("Runtime memory log", memory_log.get("enabled")),
        ],
    )
    _print_config_group("PETSc Diagnostic Settings", _flatten_summary_mapping(diagnostics.get("petsc", {})))
    solver_monitoring = summary.get("solver_monitoring", {})
    _print_config_group(
        "Solver Monitoring",
        [
            ("Enabled flags", solver_monitoring.get("enabled_flags")),
            ("All flags", solver_monitoring.get("flags")),
        ],
    )
 
 
def render_selected_summary(payload: dict, output_format: str = "text"):
    """!
    @brief Render selected timestep-independent config views and optional health.
    @param[in] payload Combined selected summary payload.
    @param[in] output_format Output format.
    """
    if output_format == "json":
        json_payload = {key: value for key, value in payload.items() if key != "_health_requested"}
        print(json.dumps(json_payload, indent=2, sort_keys=True))
        return
 
    if payload.get("run_overview") is not None:
        _render_run_overview_text(payload["run_overview"])
    renderers = {
        "case": _render_case_summary_text,
        "solver": _render_solver_summary_text,
        "monitor": _render_monitor_summary_text,
    }
    for key in ("case", "solver", "monitor"):
        if key in payload.get("configuration", {}):
            renderers[key](payload["configuration"][key])
    storage = payload.get("storage")
    if isinstance(storage, dict):
        print("\nSTORAGE")
        print("=" * 78)
        print(f"  State      : {storage.get('state', 'LOCAL')}")
        if storage.get("archive_id"):
            print(f"  Archive ID : {storage['archive_id']}")
        if storage.get("label"):
            print(f"  Label      : {storage['label']}")
    if payload.get("_health_requested"):
        health_payload = {
            key: value for key, value in payload.items()
            if key not in {"run_overview", "configuration", "storage", "_health_requested"}
        }
        render_run_summary(health_payload, output_format="text")
 
 
_SUMMARY_PLOT_LOG_SCALE_FIELDS = {
    "max_divergence", "delta_norm", "delta_rel", "residual_norm", "residual_rel",
    "unpreconditioned_norm", "true_norm", "relative_norm",
    "u_abs_l2", "u_rel_l2", "p_abs_l2", "p_rel_l2",
    "spd_abs", "spd_rel", "ke_abs", "ke_rel",
    "spd_win_abs", "spd_win_rel", "spd_rms_abs", "spd_rms_rel",
    "ke_win_abs", "ke_win_rel", "ke_rms_abs", "ke_rms_rel",
    "parseval_residual", "zero_mode_energy",
}
 
 
_SUMMARY_PLOT_FIELD_LABELS = {
    "max_divergence": "Maximum |divergence|",
    "rhs_sum": "Poisson source imbalance",
    "flux_in": "Inflow flux",
    "flux_out": "Outflow flux",
    "net_flux": "Net boundary flux",
    "total_particles": "Particle count",
    "lost_particles": "Particles lost per step (search failures)",
    "lost_particles_cumulative": "Cumulative particles lost (search failures)",
    "exited_particles": "Particles that left the domain per step",
    "exited_particles_cumulative": "Cumulative particles that left the domain",
    "migrated_particles": "Migrated particles",
    "occupied_cells": "Occupied cells",
    "load_imbalance": "Particle load imbalance",
    "migration_passes": "Particle migration passes",
    "pseudo_iterations": "Pseudo-iterations to convergence",
    "newton_iterations": "Newton iterations to convergence",
    "iterations": "Linear iterations to convergence",
    "dtau": "Pseudo-time step, Δτ",
    "dtau_after": "Accepted pseudo-time step, Δτ",
    "cfl_eff": "Effective pseudo-CFL",
    "cfl_eff_after": "Accepted effective pseudo-CFL",
    "delta_norm": "Momentum update norm, ‖ΔU‖",
    "delta_rel": "Relative momentum update, ‖ΔU‖/‖ΔU₀‖",
    "residual_norm": "Residual norm",
    "residual_rel": "Relative residual norm",
    "trial_ratio": "Pseudo-CFL trial ratio",
    "smoothed_ratio": "Smoothed pseudo-CFL ratio",
    "unpreconditioned_norm": "Unpreconditioned residual norm",
    "true_norm": "True residual norm",
    "relative_norm": "Relative residual norm",
    "calls": "Calls per physical step",
    "step_time_s": "Wall time per physical step (s)",
    "process_current_mb_max": "Maximum resident memory (MiB)",
    "process_peak_mb_max": "Peak resident memory (MiB)",
    "petsc_allocated_mb_max": "PETSc allocated memory (MiB)",
    "petsc_peak_allocated_mb_max": "Peak PETSc allocated memory (MiB)",
    "process_change_mb_max": "Resident-memory change (MiB)",
    "u_abs_l2": "Velocity L² error",
    "u_rel_l2": "Relative velocity L² error",
    "p_abs_l2": "Pressure L² error",
    "p_rel_l2": "Relative pressure L² error",
    "mean_speed": "Volume-mean speed",
    "spd_ref": "Reference mean speed",
    "spd_abs": "Absolute mean-speed drift",
    "spd_rel": "Relative mean-speed drift",
    "mean_ke": "Mean kinetic energy",
    "ke_ref": "Reference mean kinetic energy",
    "ke_abs": "Absolute kinetic-energy drift",
    "ke_rel": "Relative kinetic-energy drift",
    "spd_win": "Window-mean speed",
    "spd_win_prev": "Previous window-mean speed",
    "spd_win_abs": "Absolute window-mean speed drift",
    "spd_win_rel": "Relative window-mean speed drift",
    "spd_rms_win": "Window RMS mean speed",
    "spd_rms_abs": "Absolute RMS speed drift",
    "spd_rms_rel": "Relative RMS speed drift",
    "ke_win": "Window-mean kinetic energy",
    "ke_win_prev": "Previous window-mean kinetic energy",
    "ke_win_abs": "Absolute window-mean kinetic-energy drift",
    "ke_win_rel": "Relative window-mean kinetic-energy drift",
    "ke_rms_win": "Window RMS kinetic energy",
    "ke_rms_abs": "Absolute RMS kinetic-energy drift",
    "ke_rms_rel": "Relative RMS kinetic-energy drift",
    "resolved_kinetic_energy": "Resolved kinetic energy",
    "spectrum_total_energy": "Integrated spectral energy",
    "parseval_residual": "Parseval residual",
    "spectrum_peak_k": "Peak wavenumber, kₚₑₐₖ",
    "zero_mode_energy": "Zero-mode energy",
    "integral_length_scale": "Integral length scale",
    "taylor_microscale": "Taylor microscale",
    "dissipation_over_viscosity": "Dissipation / kinematic viscosity",
}
 
 
_SUMMARY_PLOT_SOURCE_TITLES = {
    "continuity": "Continuity",
    "particles": "Particle transport",
    "momentum": "Momentum solver",
    "poisson": "Pressure Poisson solver",
    "profiling": "Runtime profile",
    "memory": "Runtime memory",
    "convergence": "Solution convergence",
    "spectra": "Turbulence spectrum",
}
 
 
_SUMMARY_ITERATION_HISTORY_FIELDS = {
    "dtau", "dtau_after", "cfl_eff", "cfl_eff_after", "delta_norm", "delta_rel",
    "residual_norm", "residual_rel", "trial_ratio", "smoothed_ratio",
    "unpreconditioned_norm", "true_norm", "relative_norm",
}
 
 
_SUMMARY_COUNT_FIELDS = {
    "total_particles", "lost_particles", "lost_particles_cumulative",
    "exited_particles", "exited_particles_cumulative", "migrated_particles", "occupied_cells", "migration_passes", "calls",
    "pseudo_iterations", "newton_iterations", "iterations",
}
 
 
def _humanize_plot_identifier(value: str) -> str:
    """!
    @brief Convert one machine-oriented identifier into a readable plot label.
    @param[in] value Dotted path or snake-case identifier.
    @return Human-readable label.
    """
    text = str(value).split(".")[-1].replace("_", " ").strip()
    replacements = {
        "l2": "L²", "linf": "L∞", "msd": "mean-squared displacement",
        "pct": "percentage", "p95": "95th percentile", "cfl": "CFL",
        "ke": "kinetic energy", "rms": "RMS",
    }
    words = [replacements.get(word.lower(), word) for word in text.split()]
    return " ".join(words[:1]).capitalize() + (" " + " ".join(words[1:]) if len(words) > 1 else "")
 
 
def _summary_field_label(field: str) -> str:
    """!
    @brief Return the report-facing label for one logged scalar field.
    @param[in] field Logged scalar field name.
    @return Report-facing label.
    """
    return _SUMMARY_PLOT_FIELD_LABELS.get(field, _humanize_plot_identifier(field))
 
 
def _summary_physical_time(context: dict, record: dict) -> "float | None":
    """!
    @brief Resolve a record's physical time from its artifact or copied case configuration.
    @param[in] context Summary context with copied case configuration.
    @param[in] record Collected plot record.
    @return Physical time, or None when it cannot be resolved.
    """
    explicit = record.get("coordinates", {}).get("time")
    if explicit is not None:
        return float(explicit)
    try:
        dt = float((context.get("case_cfg") or {}).get("run_control", {}).get("dt_physical"))
    except (TypeError, ValueError):
        return None
    return float(record["step"]) * dt if math.isfinite(dt) and dt > 0.0 else None
 
 
def _read_runtime_diagnostics_csv(path):
    """!
    @brief Yields `(segment, row)` for each data line of one of the solver's CSV records.
 
    Every per-step file the solver writes shares one shape: a header (the first line that is
    not a comment) written once, data rows appended across the run, `#` comment lines, and a
    `# Continuation from step N` marker at each seam where a continuation resumed. A row with
    fewer fields than the header is skipped rather than guessed at; one with more keeps the
    header's columns, since columns are only ever appended. `segment` counts the
    continuations seen so far, so a caller can keep restarts as separate series instead of
    drawing a line across the seam.
 
    @param path CSV to read.
    @return Generator of `(segment_index, {column: text})` pairs.
    """
    segment = 0
    header = []
    with open(path, "r", encoding="utf-8", errors="replace", newline="") as handle:
        for raw_line in handle:
            if _is_summary_plot_continuation_marker(raw_line):
                segment += 1
                continue
            stripped = raw_line.strip()
            if not stripped or stripped.startswith("#"):
                continue
            parts = [part.strip() for part in stripped.split(",")]
            if not header:
                header = parts
                continue
            if len(parts) < len(header):
                continue
            yield segment, dict(zip(header, parts))
 
 
def _log_family_path(log_dir: str, base: str) -> "str | None":
    """!
    @brief Return a solver record's CSV, or the text log an older run wrote instead.
    @param[in] log_dir Run log directory.
    @param[in] base File name without extension, such as `Continuity_Metrics`.
    @return Existing path, preferring `.csv`; None when neither exists.
    """
    for extension in (".csv", ".log"):
        path = os.path.join(log_dir, base + extension)
        if os.path.isfile(path):
            return path
    return None
 
 
def _block_family_paths(log_dir: str, *bases: str) -> "list[tuple[int, str]]":
    """!
    @brief Return `(block, path)` for each per-block solver record, CSV preferred per block.
    @param[in] log_dir Run log directory.
    @param[in] bases File-name stems before `_Block_<n>`, newest naming first.
    @return Sorted `(block, path)` pairs.
    """
    chosen = {}
    for base in bases:
        for extension in (".csv", ".log"):
            for path in glob.glob(os.path.join(log_dir, f"{base}_Block_*{extension}")):
                match = re.search(r"_Block_(\d+)\.(csv|log)$", path)
                if match and int(match.group(1)) not in chosen:
                    chosen[int(match.group(1))] = path
    return sorted(chosen.items())
 
 
def _continuity_rows(log_dir: str) -> "tuple[str | None, list]":
    """!
    @brief Return the continuity record's path and its `(segment, row)` pairs.
    @param[in] log_dir Run log directory.
    @return Path (or None) and rows keyed step, block, max_divergence, max_divergence_location,
            rhs_sum, flux_in, flux_out, net_flux.
    """
    path = _log_family_path(log_dir, "Continuity_Metrics")
    rows = []
    if path is None:
        return None, rows
    if path.endswith(".csv"):
        for segment, row in _read_runtime_diagnostics_csv(path):
            step, block = _parse_int_loose(row.get("step")), _parse_int_loose(row.get("block"))
            if step is None or block is None:
                continue
            rows.append((segment, {
                "step": step, "block": block,
                "max_divergence": _parse_float_loose(row.get("max_divergence")),
                "max_divergence_location": "([{}][{}][{}] = {})".format(
                    row.get("max_divergence_k"), row.get("max_divergence_j"),
                    row.get("max_divergence_i"), row.get("max_divergence_index")),
                "rhs_sum": _parse_float_loose(row.get("poisson_source_imbalance")),
                "flux_in": _parse_float_loose(row.get("flux_in")),
                "flux_out": _parse_float_loose(row.get("flux_out")),
                "net_flux": _parse_float_loose(row.get("net_flux")),
            }))
        return path, rows
    segment = 0
    with open(path, "r", encoding="utf-8", errors="replace") as f:
        for raw_line in f:
            if _is_summary_plot_continuation_marker(raw_line):
                segment += 1
                continue
            line = raw_line.strip()
            if not line or line.startswith("-") or line.startswith("Timestep"):
                continue
            parts = [part.strip() for part in raw_line.split("|")]
            if len(parts) < 8:
                continue
            step, block = _parse_int_loose(parts[0]), _parse_int_loose(parts[1])
            if step is None or block is None:
                continue
            rows.append((segment, {
                "step": step, "block": block,
                "max_divergence": _parse_float_loose(parts[2]),
                "max_divergence_location": parts[3],
                "rhs_sum": _parse_float_loose(parts[4]),
                "flux_in": _parse_float_loose(parts[5]),
                "flux_out": _parse_float_loose(parts[6]),
                "net_flux": _parse_float_loose(parts[7]),
            }))
    return path, rows
 
 
def _particle_step_rows(log_dir: str, metrics_dir: str) -> "tuple[str | None, list]":
    """!
    @brief Return the per-step particle record's path and its `(segment, row)` pairs.
 
    `search_metrics.csv` carries the step's particle counts; a run that predates it in that
    role wrote `Particle_Metrics.log`, read when the CSV is absent.
 
    @param[in] log_dir Run log directory.
    @param[in] metrics_dir Run analysis metrics directory.
    @return Path (or None) and rows keyed step, total_particles, lost_particles,
            lost_particles_cumulative, migrated_particles, occupied_cells, load_imbalance,
            migration_passes, exited_particles, exited_particles_cumulative.
    """
    rows = []
    csv_path = os.path.join(metrics_dir, "search_metrics.csv") if metrics_dir else None
    if csv_path and os.path.isfile(csv_path):
        for segment, row in _read_runtime_diagnostics_csv(csv_path):
            step = _parse_int_loose(row.get("step"))
            if step is None:
                continue
            rows.append((segment, {
                "step": step,
                "total_particles": _parse_int_loose(row.get("total_particles")),
                "lost_particles": _parse_int_loose(row.get("lost")),
                "lost_particles_cumulative": _parse_int_loose(row.get("lost_cumulative")),
                "migrated_particles": _parse_int_loose(row.get("migrated")),
                "occupied_cells": _parse_int_loose(row.get("occupied_cells")),
                "load_imbalance": _parse_float_loose(row.get("load_imbalance")),
                "migration_passes": _parse_int_loose(row.get("migration_passes")),
                "exited_particles": _parse_int_loose(row.get("exited")),
                "exited_particles_cumulative": _parse_int_loose(row.get("exited_cumulative")),
            }))
        return csv_path, rows
    path = os.path.join(log_dir, "Particle_Metrics.log")
    if not os.path.isfile(path):
        return None, rows
    segment = 0
    with open(path, "r", encoding="utf-8", errors="replace") as f:
        for raw_line in f:
            if _is_summary_plot_continuation_marker(raw_line):
                segment += 1
                continue
            line = raw_line.strip()
            if not line or line.startswith("-") or line.startswith("Stage"):
                continue
            parts = [part.strip() for part in raw_line.split("|")]
            if len(parts) < 8:
                continue
            step = _parse_int_loose(parts[1])
            if step is None:
                continue
            offset = 1 if len(parts) >= 9 else 0
            rows.append((segment, {
                "step": step,
                "total_particles": _parse_int_loose(parts[2]),
                "lost_particles": _parse_int_loose(parts[3]),
                "lost_particles_cumulative": _parse_int_loose(parts[4]) if offset else None,
                "migrated_particles": _parse_int_loose(parts[4 + offset]),
                "occupied_cells": _parse_int_loose(parts[5 + offset]),
                "load_imbalance": _parse_float_loose(parts[6 + offset]),
                "migration_passes": _parse_int_loose(parts[7 + offset]),
                "exited_particles": _parse_int_loose(parts[9]) if len(parts) >= 11 else None,
                "exited_particles_cumulative": _parse_int_loose(parts[10]) if len(parts) >= 11 else None,
            }))
    return path, rows
 
 
_LEGACY_PICARD_REGEX = re.compile(
    r"Step:\s*(?P<step>\d+)\s*\|\s*PseudoIter\‍(k\‍):\s*(?P<pseudo_iter>\d+)\s*\|"
    r"\s*dtau:\s*(?P<dtau>[-+0-9.eE]+)\s*\|\s*cfl_eff:\s*(?P<cfl_eff>[-+0-9.eE]+)\s*\|"
    r"\s*\|dUk\|:\s*(?P<delta>[-+0-9.eE]+)\s*\|"
    r"\s*\|dUk\|/\|dU0\|:\s*(?P<delta_rel>[-+0-9.eE]+)\s*\|\s*\|Rk\|:\s*(?P<resid>[-+0-9.eE]+)\s*\|"
    r"\s*\|Rk\|/\|R0\|:\s*(?P<resid_rel>[-+0-9.eE]+)"
    r"(?:\s*\|\s*trial_ratio:\s*(?P<trial_ratio>[-+0-9.eE]+)"
    r"(?:\s*\|\s*smoothed_ratio:\s*(?P<smoothed_ratio>[-+0-9.eE]+))?"
    r"\s*\|\s*status:\s*(?P<status>\w+)\s*\|\s*dtau_after:\s*(?P<dtau_after>[-+0-9.eE]+)"
    r"(?:\s*\|\s*cfl_eff_after:\s*(?P<cfl_eff_after>[-+0-9.eE]+))?)?"
)
 
 
def _picard_history_rows(log_dir: str) -> "list[tuple[int, str, list]]":
    """!
    @brief Return `(block, path, [(segment, row)])` for each Picard momentum history.
    @param[in] log_dir Run log directory.
    @return Rows keyed step, block, pseudo_iterations, dtau, cfl_eff, delta_norm, delta_rel,
            residual_norm, residual_rel, trial_ratio, smoothed_ratio, status, dtau_after,
            cfl_eff_after; dtau is solver time and cfl_eff = dtau * lambda_max.
    """
    out = []
    for block, path in _block_family_paths(log_dir, "Momentum_Solver_DualTime_Picard_Jameson_RK_History",
                                           "Momentum_Solver_Convergence_History"):
        rows = []
        if path.endswith(".csv"):
            for segment, row in _read_runtime_diagnostics_csv(path):
                step = _parse_int_loose(row.get("step"))
                if step is None:
                    continue
                rows.append((segment, {
                    "step": step, "block": block,
                    "pseudo_iterations": _parse_int_loose(row.get("pseudo_iter")),
                    "dtau": _parse_float_loose(row.get("dtau")),
                    "cfl_eff": _parse_float_loose(row.get("cfl_eff")),
                    "delta_norm": _parse_float_loose(row.get("delta_norm")),
                    "delta_rel": _parse_float_loose(row.get("delta_rel")),
                    "residual_norm": _parse_float_loose(row.get("residual_norm")),
                    "residual_rel": _parse_float_loose(row.get("residual_rel")),
                    "trial_ratio": _parse_float_loose(row.get("trial_ratio")),
                    "smoothed_ratio": _parse_float_loose(row.get("smoothed_ratio")),
                    "status": row.get("status") or None,
                    "dtau_after": _parse_float_loose(row.get("dtau_after")),
                    "cfl_eff_after": _parse_float_loose(row.get("cfl_eff_after")),
                }))
        else:
            segment = 0
            with open(path, "r", encoding="utf-8", errors="replace") as f:
                for raw_line in f:
                    if _is_summary_plot_continuation_marker(raw_line):
                        segment += 1
                        continue
                    match = _LEGACY_PICARD_REGEX.search(raw_line)
                    if not match:
                        continue
                    rows.append((segment, {
                        "step": int(match.group("step")), "block": block,
                        "pseudo_iterations": int(match.group("pseudo_iter")),
                        "dtau": _parse_float_loose(match.group("dtau")),
                        "cfl_eff": _parse_float_loose(match.group("cfl_eff")),
                        "delta_norm": float(match.group("delta")),
                        "delta_rel": float(match.group("delta_rel")),
                        "residual_norm": float(match.group("resid")),
                        "residual_rel": float(match.group("resid_rel")),
                        "trial_ratio": _parse_float_loose(match.group("trial_ratio")),
                        "smoothed_ratio": _parse_float_loose(match.group("smoothed_ratio")),
                        "status": match.group("status"),
                        "dtau_after": _parse_float_loose(match.group("dtau_after")),
                        "cfl_eff_after": _parse_float_loose(match.group("cfl_eff_after")),
                    }))
        out.append((block, path, rows))
    return out
 
 
_LEGACY_NEWTON_HISTORY_REGEX = re.compile(
    r"step:\s*(?P<step>\d+)\s*\|\s*block:\s*(?P<block>\d+)\s*\|"
    r"\s*newton:\s*(?P<newton>\d+)\s*\|\s*nonlinear_norm:\s*(?P<norm>[-+0-9.eE]+)"
)
_LEGACY_NEWTON_SUMMARY_REGEX = re.compile(
    r"step:\s*(?P<step>\d+)\s*\|\s*block:\s*(?P<block>\d+)\s*\|"
    r"\s*solver:\s*(?P<solver>[^|]+?)\s*\|"
    r"(?:\s*Jacobian:\s*[^|]+?\s*\|\s*Preconditioner:\s*[^|]+?\s*\|)?"
    r"\s*reason:\s*(?P<reason>\S+)\s*\|"
    r"\s*reason_code:\s*(?P<reason_code>-?\d+)\s*\|\s*newton:\s*(?P<newton>\d+)\s*\|"
    r"\s*evals:\s*(?P<evals>\d+)\s*\|\s*krylov:\s*(?P<krylov>\d+)\s*\|"
    r"\s*initial:\s*(?P<initial>[-+0-9.eE]+|unavailable)\s*\|"
    r"\s*final:\s*(?P<final>[-+0-9.eE]+)\s*\|\s*state:\s*(?P<state>\w+)"
)
 
 
def _newton_history_rows(log_dir: str) -> "list[tuple[int, str, list]]":
    """!
    @brief Return `(block, path, [(segment, row)])` for each Newton iteration history.
    @param[in] log_dir Run log directory.
    @return Rows keyed step, block, newton_iterations, residual_norm.
    """
    out = []
    for block, path in _block_family_paths(log_dir, "Momentum_Solver_Newton_Krylov_History"):
        rows = []
        if path.endswith(".csv"):
            for segment, row in _read_runtime_diagnostics_csv(path):
                step = _parse_int_loose(row.get("step"))
                if step is not None:
                    rows.append((segment, {"step": step, "block": _parse_int_loose(row.get("block")),
                                           "newton_iterations": _parse_int_loose(row.get("newton")),
                                           "residual_norm": _parse_float_loose(row.get("nonlinear_norm"))}))
        else:
            segment = 0
            with open(path, "r", encoding="utf-8", errors="replace") as f:
                for raw_line in f:
                    if _is_summary_plot_continuation_marker(raw_line):
                        segment += 1
                        continue
                    match = _LEGACY_NEWTON_HISTORY_REGEX.search(raw_line)
                    if match:
                        rows.append((segment, {"step": int(match.group("step")), "block": int(match.group("block")),
                                               "newton_iterations": int(match.group("newton")),
                                               "residual_norm": float(match.group("norm"))}))
        out.append((block, path, rows))
    return out
 
 
def _newton_summary_rows(log_dir: str) -> "list[tuple[int, str, list]]":
    """!
    @brief Return `(block, path, [(segment, row)])` for each Newton per-step summary.
    @param[in] log_dir Run log directory.
    @return Rows keyed step, block, solver, reason, reason_code, newton_iterations,
            residual_evaluations, krylov_iterations, initial_norm, final_norm, state.
    """
    out = []
    for block, path in _block_family_paths(log_dir, "Momentum_Solver_Newton_Krylov_Summary"):
        rows = []
        if path.endswith(".csv"):
            for segment, row in _read_runtime_diagnostics_csv(path):
                step = _parse_int_loose(row.get("step"))
                if step is None:
                    continue
                rows.append((segment, {
                    "step": step, "block": _parse_int_loose(row.get("block")),
                    "solver": row.get("solver"), "reason": row.get("reason"),
                    "reason_code": _parse_int_loose(row.get("reason_code")),
                    "newton_iterations": _parse_int_loose(row.get("newton")),
                    "residual_evaluations": _parse_int_loose(row.get("evals")),
                    "krylov_iterations": _parse_int_loose(row.get("krylov")),
                    "initial_norm": _parse_float_loose(row.get("initial_norm")),
                    "final_norm": _parse_float_loose(row.get("final_norm")),
                    "state": row.get("state"),
                }))
        else:
            segment = 0
            with open(path, "r", encoding="utf-8", errors="replace") as f:
                for raw_line in f:
                    if _is_summary_plot_continuation_marker(raw_line):
                        segment += 1
                        continue
                    match = _LEGACY_NEWTON_SUMMARY_REGEX.search(raw_line)
                    if not match:
                        continue
                    initial_text = match.group("initial")
                    rows.append((segment, {
                        "step": int(match.group("step")), "block": int(match.group("block")),
                        "solver": match.group("solver").strip(), "reason": match.group("reason"),
                        "reason_code": int(match.group("reason_code")),
                        "newton_iterations": int(match.group("newton")),
                        "residual_evaluations": int(match.group("evals")),
                        "krylov_iterations": int(match.group("krylov")),
                        "initial_norm": None if initial_text == "unavailable" else float(initial_text),
                        "final_norm": float(match.group("final")),
                        "state": match.group("state"),
                    }))
        out.append((block, path, rows))
    return out
 
 
_LEGACY_POISSON_REGEX = re.compile(
    r"ts:\s*(?P<step>\d+)\s*\|\s*block:\s*(?P<block>\d+)\s*\|\s*iter:\s*(?P<iter>\d+)\s*\|"
    r"\s*Unprecond Norm:\s*(?P<unpre>[-+0-9.eE]+)\s*\|\s*True Norm:\s*(?P<true>[-+0-9.eE]+)"
    r"(?:\s*\|\s*Rel Norm:\s*(?P<rel>[-+0-9.eE]+))?"
)
 
 
def _poisson_history_rows(log_dir: str) -> "list[tuple[int, str, list]]":
    """!
    @brief Return `(block, path, [(segment, row)])` for each Poisson iteration history.
    @param[in] log_dir Run log directory.
    @return Rows keyed step, block, iterations, unpreconditioned_norm, true_norm, relative_norm;
            true_norm and relative_norm are None unless the run computed the true residual.
    """
    out = []
    for block, path in _block_family_paths(log_dir, "Poisson_Solver_Convergence_History"):
        rows = []
        if path.endswith(".csv"):
            for segment, row in _read_runtime_diagnostics_csv(path):
                step = _parse_int_loose(row.get("step"))
                if step is not None:
                    rows.append((segment, {"step": step, "block": _parse_int_loose(row.get("block")),
                                           "iterations": _parse_int_loose(row.get("iter")),
                                           "unpreconditioned_norm": _parse_float_loose(row.get("unpreconditioned_norm")),
                                           "true_norm": _parse_float_loose(row.get("true_norm")),
                                           "relative_norm": _parse_float_loose(row.get("relative_norm"))}))
        else:
            segment = 0
            with open(path, "r", encoding="utf-8", errors="replace") as f:
                for raw_line in f:
                    if _is_summary_plot_continuation_marker(raw_line):
                        segment += 1
                        continue
                    match = _LEGACY_POISSON_REGEX.search(raw_line)
                    if match:
                        rows.append((segment, {"step": int(match.group("step")), "block": int(match.group("block")),
                                               "iterations": int(match.group("iter")),
                                               "unpreconditioned_norm": float(match.group("unpre")),
                                               "true_norm": float(match.group("true")),
                                               "relative_norm": _parse_float_loose(match.group("rel"))}))
        out.append((block, path, rows))
    return out
 
 
def _runtime_memory_rows(path: str) -> list:
    """!
    @brief Return the runtime memory record's `(segment, row)` pairs (CSV, or an older run's text log).
    @param[in] path Runtime memory log path as configured.
    @return Rows keyed step, event, process_current_mb_max, process_peak_mb_max,
            petsc_allocated_mb_max, petsc_peak_allocated_mb_max, process_change_mb_max, reason.
    """
    rows = []
    if not path or not os.path.isfile(path):
        return rows
    keys = ("process_current_mb_max", "process_peak_mb_max", "petsc_allocated_mb_max",
            "petsc_peak_allocated_mb_max", "process_change_mb_max")
    with open(path, "r", encoding="utf-8", errors="replace") as f:
        first = ""
        for line in f:
            if line.strip() and not line.lstrip().startswith("#"):
                first = line
                break
    if first.startswith("step,"):
        for segment, row in _read_runtime_diagnostics_csv(path):
            step = _parse_int_loose(row.get("step"))
            if step is None:
                continue
            rows.append((segment, {"step": step, "event": row.get("event"), "reason": row.get("reason"),
                                   "step_wall_s": _parse_float_loose(row.get("step_wall_s")),
                                   **{key: _parse_float_loose(row.get(key)) for key in keys}}))
        return rows
    segment = 0
    with open(path, "r", encoding="utf-8", errors="replace") as f:
        for raw_line in f:
            if _is_summary_plot_continuation_marker(raw_line):
                segment += 1
                continue
            line = raw_line.strip()
            if not line or line.startswith("#") or line.startswith("Step"):
                continue
            parts = line.split()
            step = _parse_int_loose(parts[0]) if parts else None
            if len(parts) < 8 or step is None:
                continue
            rows.append((segment, {"step": step, "event": parts[1], "reason": parts[7],
                                   **{key: _parse_float_loose(parts[2 + i]) for i, key in enumerate(keys)}}))
    return rows
 
 
# Columns that identify a plot record (its step and line) rather than carry a value; text
# columns such as a status or an event are dropped by _append_summary_plot_record() itself.
_PLOT_ROW_IDENTITY_KEYS = ("step", "block")
 
 
def _typed_csv_value(text: str):
    """!
    @brief Return a CSV cell as a float (written with a point or exponent), an int, or the text.
    @param[in] text Cell text.
    @return Parsed value.
    """
    float_val = _parse_float_loose(text)
    int_val = _parse_int_loose(text)
    if float_val is not None and ("." in text or "e" in text.lower()):
        return float_val
    if int_val is not None:
        return int_val
    return text
 
 
def _solution_convergence_rows(log_dir: str) -> "tuple[str | None, list]":
    """!
    @brief Return the solution-convergence record's path and its `(segment, row)` pairs.
    @param[in] log_dir Run log directory.
    @return Path (or None) and rows with every column, numbers parsed and `mode` set.
    """
    path = _log_family_path(log_dir, "solution_convergence")
    rows = []
    if path is None:
        return None, rows
 
    if path.endswith(".csv"):
        for segment, row in _read_runtime_diagnostics_csv(path):
            step = _parse_int_loose(row.get("step"))
            if step is None:
                continue
            values = {name: _typed_csv_value(text) for name, text in row.items() if name}
            values["step"] = step
            rows.append((segment, values))
        return path, rows
    mode, col_names, segment = None, None, 0
    with open(path, "r", encoding="utf-8", errors="replace") as f:
        for raw_line in f:
            line = raw_line.strip()
            if _is_summary_plot_continuation_marker(line):
                segment += 1
                continue
            if not line:
                continue
            if line.startswith("="):
                found = re.search(r"\[mode:\s*([\w_]+)", line)
                if found:
                    mode = found.group(1)
                continue
            if line.startswith("-"):
                continue
            if col_names is None:
                col_names = [p.strip() for p in raw_line.split("|")]
                continue
            parts = [p.strip() for p in raw_line.split("|")]
            step = _parse_int_loose(parts[0]) if col_names[0] == "step" and len(parts) >= 4 else None
            if step is None:
                continue
            values = {"mode": mode}
            values.update({name: _typed_csv_value(text) for name, text in zip(col_names, parts) if name})
            values["step"] = step
            rows.append((segment, values))
    return path, rows
 
 
def _append_summary_plot_record(records: list, source: str, step, line: str, values: dict,
                                source_path: str, segment: int = 0, coordinates: dict = None):
    """!
    @brief Append one numeric append-ordered record for summarize plotting.
    @param[out] records Destination record list.
    @param[in] source Qualified source prefix.
    @param[in] step Logged timestep.
    @param[in] line Human-readable line identity.
    @param[in] values Candidate field mapping.
    @param[in] source_path Source artifact path.
    @param[in] segment Zero-based continuation segment within the source artifact.
    @param[in] coordinates Optional independent variables carried by the source row.
    """
    numeric = {
        key: value
        for key, value in values.items()
        if isinstance(value, (int, float)) and not isinstance(value, bool)
    }
    if step is not None and numeric:
        records.append({
            "source": source,
            "step": int(step),
            "line": line,
            "values": numeric,
            "source_path": source_path,
            "segment": int(segment),
            "coordinates": {
                key: value for key, value in (coordinates or {}).items()
                if isinstance(value, (int, float)) and not isinstance(value, bool)
            },
        })
 
 
def _is_summary_plot_continuation_marker(line: str) -> bool:
    """!
    @brief Return whether a log line starts a new continuation segment.
    @param[in] line Candidate raw or stripped log line.
    @return True for the shared continuation marker syntax.
    """
    return bool(re.match(r"^\s*#?\s*=*\s*Continuation from step\s+\d+", line, re.IGNORECASE))
 
 
def _collect_summary_plot_records(context: dict) -> list:
    """!
    @brief Collect append-ordered numeric records from summarize-supported scalar logs.
    @param[in] context Summary context returned by `_build_summary_context()`.
    @return Append-ordered plot record list.
    """
    records = []
    log_dir = context["log_dir"]
    # The C runtime writes its per-step diagnostics CSVs to the analysis metrics home,
    # not beside the text logs; PicurvOpenDiagnosticsCsv() owns that placement.
    metrics_dir = context["metrics_dir"]
 
    continuity_path, continuity_rows = _continuity_rows(log_dir)
    for segment, row in continuity_rows:
        _append_summary_plot_record(
            records, "continuity", row["step"], f"block {row['block']}",
            {key: row[key] for key in ("max_divergence", "rhs_sum", "flux_in", "flux_out", "net_flux")},
            continuity_path, segment,
        )
 
    particle_path, particle_rows = _particle_step_rows(log_dir, metrics_dir)
    for segment, row in particle_rows:
        _append_summary_plot_record(
            records, "particles", row["step"], "particles",
            {key: value for key, value in row.items() if key != "step"},
            particle_path, segment,
        )
 
    # dtau is solver time; cfl_eff = dtau * lambda_max, the Courant number pseudo_cfl.* controls.
    for block, path, rows in _picard_history_rows(log_dir):
        for segment, row in rows:
            _append_summary_plot_record(
                records, "momentum", row["step"], f"block {block}",
                {key: value for key, value in row.items() if key not in _PLOT_ROW_IDENTITY_KEYS},
                path, segment,
                coordinates={"solver_iteration": row["pseudo_iterations"]},
            )
 
    for block, path, rows in _newton_history_rows(log_dir):
        for segment, row in rows:
            _append_summary_plot_record(
                records, "momentum", row["step"], f"block {row['block']}",
                {"newton_iterations": row["newton_iterations"], "residual_norm": row["residual_norm"]},
                path, segment,
                coordinates={"solver_iteration": row["newton_iterations"]},
            )
 
    for block, path, rows in _poisson_history_rows(log_dir):
        for segment, row in rows:
            _append_summary_plot_record(
                records, "poisson", row["step"], f"block {row['block']}",
                {key: row[key] for key in ("iterations", "unpreconditioned_norm", "true_norm", "relative_norm")},
                path, segment,
                coordinates={"solver_iteration": row["iterations"]},
            )
 
    # The LES coefficient history. cs_effective is the curve an LES run is judged on:
    # on the HOM02 benchmark at 64^3 it settles at 0.18-0.19 (page 72, section 10).
    les_path = os.path.join(metrics_dir, "les_coefficient.csv")
    if os.path.isfile(les_path):
        for segment, row in _read_runtime_diagnostics_csv(les_path):
            _append_summary_plot_record(
                records, "les", _parse_int_loose(row.get("step")), "coefficient",
                {
                    "cs_effective": _parse_float_loose(row.get("cs_effective")),
                    "cs_mean": _parse_float_loose(row.get("cs_mean")),
                    "coefficient_rms": _parse_float_loose(row.get("coefficient_rms")),
                    "coefficient_min": _parse_float_loose(row.get("coefficient_min")),
                    "coefficient_max": _parse_float_loose(row.get("coefficient_max")),
                    "nu_t_mean": _parse_float_loose(row.get("nu_t_mean")),
                    "nu_t_max": _parse_float_loose(row.get("nu_t_max")),
                    "nu_t_over_nu_mean": _parse_float_loose(row.get("nu_t_over_nu_mean")),
                    "k_sgs_mean": _parse_float_loose(row.get("k_sgs_mean")),
                    "backscatter_fraction": _parse_float_loose(row.get("backscatter_fraction")),
                    "limited_fraction": _parse_float_loose(row.get("limited_fraction")),
                },
                les_path, segment,
            )
 
    # The wall-model history. y_plus_mean is what says whether the first cell sits where
    # the selected law is valid; u_tau is what a channel run is scored against.
    wall_path = os.path.join(metrics_dir, "wall_model.csv")
    if os.path.isfile(wall_path):
        for segment, row in _read_runtime_diagnostics_csv(wall_path):
            _append_summary_plot_record(
                records, "wall_model", _parse_int_loose(row.get("step")), "near wall",
                {
                    "u_tau_mean": _parse_float_loose(row.get("u_tau_mean")),
                    "u_tau_rms": _parse_float_loose(row.get("u_tau_rms")),
                    "u_tau_min": _parse_float_loose(row.get("u_tau_min")),
                    "u_tau_max": _parse_float_loose(row.get("u_tau_max")),
                    "y_plus_mean": _parse_float_loose(row.get("y_plus_mean")),
                    "y_plus_max": _parse_float_loose(row.get("y_plus_max")),
                    "wall_distance_mean": _parse_float_loose(row.get("wall_distance_mean")),
                    "nu_wall_over_nu_mean": _parse_float_loose(row.get("nu_wall_over_nu_mean")),
                    "wall_cells": _parse_int_loose(row.get("wall_cells")),
                },
                wall_path, segment,
            )
 
    # The driven-flow controller history. driving_acceleration is the force per unit mass
    # the flow received; in a stationary driven channel its time average is u_tau^2 / h.
    driven_path = os.path.join(metrics_dir, "driven_flow.csv")
    if os.path.isfile(driven_path):
        for segment, row in _read_runtime_diagnostics_csv(driven_path):
            _append_summary_plot_record(
                records, "driven_flow", _parse_int_loose(row.get("step")), "controller",
                {
                    "target_flux": _parse_float_loose(row.get("target_flux")),
                    "measured_flux": _parse_float_loose(row.get("measured_flux")),
                    "bulk_velocity": _parse_float_loose(row.get("bulk_velocity")),
                    "bulk_velocity_correction": _parse_float_loose(row.get("bulk_velocity_correction")),
                    "driving_acceleration": _parse_float_loose(row.get("driving_acceleration")),
                },
                driven_path, segment,
            )
 
    profiling_path = os.path.join(log_dir, PROFILING_TIMESTEP_FILE)
    if os.path.isfile(profiling_path):
        segment = 0
        columns = None
        with open(profiling_path, "r", encoding="utf-8", errors="replace", newline="") as f:
            for raw_line in f:
                if _is_summary_plot_continuation_marker(raw_line):
                    segment += 1
                    continue
                values = next(csv.reader([raw_line]))
                if not values:
                    continue
                if columns is None:
                    columns = values
                    continue
                row = dict(zip(columns, values))
                _append_summary_plot_record(
                    records, "profiling", _parse_int_loose(row.get("step")), row.get("function") or "unknown",
                    {"calls": _parse_int_loose(row.get("calls")), "step_time_s": _parse_float_loose(row.get("step_time_s"))},
                    profiling_path, segment,
                )
 
    memory_path = _log_family_path(log_dir, "Runtime_Memory") or os.path.join(log_dir, RUNTIME_MEMORY_FILE)
    for segment, row in _runtime_memory_rows(memory_path):
        if row["event"] in {"Step", "Post"}:
            _append_summary_plot_record(
                records, "memory", row["step"], "memory",
                {key: value for key, value in row.items() if key not in _PLOT_ROW_IDENTITY_KEYS},
                memory_path, segment,
            )
 
    convergence_path, convergence_rows = _solution_convergence_rows(log_dir)
    for segment, row in convergence_rows:
        _append_summary_plot_record(
            records, "convergence", row["step"], "convergence",
            {name: value for name, value in row.items()
             if name not in {"step", "time", "mode", "ref", "ph", "per", "win"}},
            convergence_path, segment,
            coordinates={"time": row.get("time") if isinstance(row.get("time"), (int, float)) else None},
        )
 
    records.extend(_collect_spectra_plot_records(context))
    records.extend(_collect_profile_plot_records(context))
    return records
 
 
def _collect_spectra_plot_records(context: dict) -> list:
    """!
    @brief Collect the per-step scalar histories written by the spectra post stage.
 
    @details Each spectra task keeps its own history file, so one task becomes one
             plotted line and several tasks compare directly on the same axes.
 
    @param[in] context Summary context returned by `_build_summary_context()`.
    @return Append-ordered plot record list; empty when no spectra were measured.
    """
    records = []
    run_dir = context.get("run_dir")
    if not run_dir:
        return records
    spectra_root = os.path.join(
        run_dir, resolve_post_spectra_output_dir(context.get("monitor_cfg") or {})
    )
    for root, _dirs, files in os.walk(spectra_root):
        for filename in sorted(files):
            if not filename.endswith("_history.csv"):
                continue
            history_path = os.path.join(root, filename)
            line = filename[: -len("_history.csv")]
            try:
                with open(history_path, "r", encoding="utf-8", errors="replace") as stream:
                    for row in csv.DictReader(stream):
                        step = _parse_int_loose(row.get("step"))
                        if step is None:
                            continue
                        values = {}
                        for column in POST_SPECTRA_SCALAR_COLUMNS:
                            parsed = _parse_float_loose(row.get(column))
                            if parsed is not None:
                                values[column] = parsed
                        if values:
                            _append_summary_plot_record(
                                records, "spectra", step, line, values, history_path, 0,
                                coordinates={"time": _parse_float_loose(row.get("time"))},
                            )
            except OSError:
                # A history a concurrent post stage is still writing is simply not
                # listed yet; summarize is read-only and must never fail on it.
                continue
    return records
 
 
def _collect_profile_plot_records(context: dict) -> list:
    """!
    @brief Collect the profile histories the `profile_series` reducer wrote.
 
    @details Each `<prefix>_profile_<name>_history.csv` holds one row per step and one
             column per `<output column>.<functional>`, which becomes the series
             `profile.<column>.<functional>`, one line per history file. The functionals
             are the reducer's (`generators/reduce.gen profile-series`); this only reads.
 
    @param[in] context Summary context returned by `_build_summary_context()`.
    @return Append-ordered plot record list; empty when no history was written.
    """
    records = []
    run_dir = context.get("run_dir")
    if not run_dir:
        return records
    root_dir = os.path.join(run_dir, CANONICAL_RUN_PATHS["statistics"])
    for root, _dirs, files in os.walk(root_dir):
        for filename in sorted(files):
            if not re.match(r"^.+_profile_.+_history\.csv$", filename):
                continue
            path = os.path.join(root, filename)
            line = os.path.relpath(path, root_dir)[: -len("_history.csv")]
            try:
                with open(path, "r", encoding="utf-8", errors="replace") as stream:
                    for row in csv.DictReader(stream):
                        step = _parse_int_loose(row.pop("step", None))
                        time = _parse_float_loose(row.pop("time", None))
                        values = {key: _parse_float_loose(value) for key, value in row.items()}
                        values = {key: value for key, value in values.items() if value is not None}
                        if step is not None and values:
                            _append_summary_plot_record(records, "profile", step, line, values, path, 0,
                                                        coordinates={"time": time})
            except OSError:
                continue
    return records
 
 
def _build_summary_plot_catalog(records: list) -> list:
    """!
    @brief Build available qualified-series metadata from plot records.
    @param[in] records Append-ordered plot record list.
    @return Available series catalog.
    """
    catalog = {}
    for record in records:
        for field in record["values"]:
            name = f"{record['source']}.{field}"
            item = catalog.setdefault(name, {"series": name, "lines": {}, "source_paths": set(), "sample_count": 0})
            item["lines"][record["line"]] = item["lines"].get(record["line"], 0) + 1
            item["source_paths"].add(record["source_path"])
            item["sample_count"] += 1
    return [
        {
            **item,
            "lines": [{"label": label, "sample_count": count} for label, count in sorted(item["lines"].items())],
            "source_paths": sorted(item["source_paths"]),
        }
        for _, item in sorted(catalog.items())
    ]
 
 
def _representative_indices(count: int, maximum: int = 6) -> list:
    """!
    @brief Select evenly distributed indices while always retaining both endpoints.
    @param[in] count Number of available ordered states.
    @param[in] maximum Maximum states to retain.
    @return Sorted unique zero-based indices.
    """
    if count <= maximum:
        return list(range(count))
    return sorted({round(index * (count - 1) / (maximum - 1)) for index in range(maximum)})
 
 
def _build_spectrum_plot_request(context: dict, task: str, reference: bool,
                                 linear_y: bool, output_path: "str | None") -> dict:
    """!
    @brief Build a plot.gen request drawing representative measured spectra.
 
    @details A decaying flow has a different spectrum at every step, so states are
             never averaged. Up to six evenly spaced states are retained, including
             the first and last, to show evolution without an unreadable legend.
 
    @param[in] context Summary context returned by `_build_summary_context()`.
    @param[in] task Task basename, or a unique substring of one.
    @param[in] reference Overlay the staged initial-condition spectrum when available.
    @param[in] linear_y Force linear axes instead of the log-log default.
    @param[in] output_path Optional explicit output path.
    @return Versioned normalized plot request.
    @throws ValueError when no matching spectrum file exists.
    """
    spectra_dir = os.path.join(
        context["run_dir"],
        resolve_post_spectra_output_dir(context.get("monitor_cfg") or {}),
    )
    candidates = []
    if os.path.isdir(spectra_dir):
        # The staged initial-condition spectrum shares this directory but is the
        # reference overlay, never a task a user can select. Post recipes write into
        # their own subdirectory (resolve_recipe_spectra_output_dir), so one level is
        # searched too; a candidate is named by its path under the spectra directory.
        reference_name = os.path.basename(INITIAL_CONDITION_SPECTRUM_RELPATH)
        for root, _dirs, files in os.walk(spectra_dir):
            if os.path.relpath(root, spectra_dir).count(os.sep) > 0:
                continue
            for name in files:
                if (name.endswith(".csv") and not name.endswith("_history.csv")
                        and name != reference_name):
                    candidates.append(os.path.relpath(os.path.join(root, name), spectra_dir))
        candidates.sort()
    if not candidates:
        raise ValueError(
            "No spectra were found for this run. Measure them with a post.yml that defines "
            "spectra tasks: 'picurv run --post-process --only spectra --run-dir <run> --post <post.yml>'."
        )
    matches = [name for name in candidates if task in name] if task else candidates
    if len(matches) != 1:
        available = ", ".join(name[: -len(".csv")] for name in candidates)
        raise ValueError(
            f"Spectrum selector {task!r} matched {len(matches)} files. Available: {available}."
        )
    spectrum_path = os.path.join(spectra_dir, matches[0])
    if "plane_spectrum" in matches[0]:
        raise ValueError("Plane spectra have two wavenumber axes; use the spectrum CSV for a 2D plot.")
 
    by_step = {}
    times = {}
    with open(spectrum_path, "r", encoding="utf-8", errors="replace") as stream:
        for row in csv.DictReader(stream):
            step = _parse_int_loose(row.get("step"))
            wavenumber = _parse_float_loose(row.get("k"))
            energy = _parse_float_loose(row.get("energy"))
            if step is None or wavenumber is None or energy is None:
                continue
            # A log-log plot cannot carry the zero wavenumber or an empty shell.
            if wavenumber <= 0.0 or (not linear_y and energy <= 0.0):
                continue
            by_step.setdefault(step, []).append([wavenumber, energy])
            times.setdefault(step, _parse_float_loose(row.get("time")))
    if not by_step:
        raise ValueError(f"{os.path.relpath(spectrum_path)} carries no plottable spectrum rows.")
 
    lines = []
    if reference:
        reference_path = os.path.join(context["run_dir"], INITIAL_CONDITION_SPECTRUM_RELPATH)
        if os.path.isfile(reference_path):
            points = []
            with open(reference_path, "r", encoding="utf-8", errors="replace") as stream:
                for row in csv.DictReader(stream):
                    wavenumber = _parse_float_loose(row.get("k"))
                    energy = _parse_float_loose(row.get("energy"))
                    if wavenumber is None or energy is None:
                        continue
                    if wavenumber <= 0.0 or (not linear_y and energy <= 0.0):
                        continue
                    points.append([wavenumber, energy])
            if points:
                lines.append({
                    "label": "Initial condition", "points": sorted(points),
                    "role": "reference", "color": "#333333", "line_style": "--",
                })
 
    ordered_steps = sorted(by_step)
    selected_steps = [ordered_steps[index] for index in _representative_indices(len(ordered_steps))]
    spectrum_colors = ("#440154", "#414487", "#2A788E", "#22A884", "#7AD151", "#DCE319")
    for index, step in enumerate(selected_steps):
        time = times.get(step)
        label = f"Step {step}" if time is None else f"t = {time:g} (step {step})"
        lines.append({
            "label": label,
            "points": sorted(by_step[step]),
            "role": "latest" if step == ordered_steps[-1] else "snapshot",
            "color": spectrum_colors[round(index * (len(spectrum_colors) - 1) / max(1, len(selected_steps) - 1))],
            "line_width": 2.4 if step == ordered_steps[-1] else 1.65,
        })
 
    name = os.path.basename(matches[0])[: -len(".csv")]
    fallback = os.path.join(
        context["run_dir"], CANONICAL_RUN_PATHS["plots"], f"{name}.png"
    )
    task_match = re.search(r"_(?P<field>[^_]+)_block(?P<block>\d+)_(?P<symbol>[^_]+)$", name)
    subtitle = None
    if task_match:
        subtitle = (
            f"Field {task_match.group('field')} · block {int(task_match.group('block'))} "
            f"· {task_match.group('symbol')} wavenumber"
        )
    return {
        "schema_version": 1,
        "plot_type": "spectrum",
        "series": name,
        "title": "Turbulent kinetic-energy spectrum",
        "subtitle": subtitle,
        "x_label": "Wavenumber, k",
        "y_label": "Energy spectrum, E(k)",
        "x_scale": "linear" if linear_y else "log",
        "y_scale": "linear" if linear_y else "log",
        "legend_title": "Snapshot",
        "show_markers": False,
        "window": {
            "mode": "representative", "last": None,
            "available_steps": len(ordered_steps), "selected_steps": selected_steps,
        },
        "lines": lines,
        "output_path": os.path.abspath(output_path) if output_path else fallback,
    }
 
 
def _build_summary_plot_request(context: dict, records: list, series: str, last_n: "int | None", linear_y: bool, output_path: "str | None") -> dict:
    """!
    @brief Build one normalized plot.gen request from collected summarize records.
    @param[in] context Summary context returned by `_build_summary_context()`.
    @param[in] records Append-ordered plot record list.
    @param[in] series Qualified series name.
    @param[in] last_n Optional last-N records per plotted line.
    @param[in] linear_y Whether to force linear scaling.
    @param[in] output_path Optional explicit output path.
    @return Versioned normalized plot request.
    """
    source, separator, field = series.partition(".")
    if not separator:
        raise ValueError("plot series must be qualified as '<source>.<field>'")
    matching = [record for record in records if record["source"] == source and field in record["values"]]
    if not matching:
        raise ValueError(f"Plot series '{series}' is unavailable. Use --list-plot-series to inspect available series.")
    latest_segments = {}
    for record in matching:
        source_path = record["source_path"]
        latest_segments[source_path] = max(latest_segments.get(source_path, 0), record.get("segment", 0))
    matching = [
        record for record in matching
        if record.get("segment", 0) == latest_segments[record["source_path"]]
    ]
    is_iteration_history = (
        source in {"momentum", "poisson"} and field in _SUMMARY_ITERATION_HISTORY_FIELDS
        and any("solver_iteration" in record.get("coordinates", {}) for record in matching)
    )
    grouped = {}
    selected_steps = set()
    if is_iteration_history:
        histories = {}
        for record in matching:
            iteration = record.get("coordinates", {}).get("solver_iteration")
            if iteration is None:
                continue
            histories.setdefault((record["source_path"], record["line"]), []).append(record)
        for (_source_path, label), history in histories.items():
            latest_step = max(record["step"] for record in history)
            selected_steps.add(latest_step)
            points = [
                [record["coordinates"]["solver_iteration"], record["values"][field]]
                for record in history if record["step"] == latest_step
            ]
            if last_n is not None:
                points = points[-last_n:]
            grouped.setdefault(f"{label} · step {latest_step}", []).extend(points)
        x_label = "Nonlinear iteration" if source == "momentum" else "Linear iteration"
        x_kind = "integer"
    else:
        uses_physical_time = all(_summary_physical_time(context, record) is not None for record in matching)
        for record in matching:
            x_value = _summary_physical_time(context, record) if uses_physical_time else record["step"]
            grouped.setdefault(record["line"], []).append([x_value, record["values"][field]])
        # Iteration-count fields occur on every nonlinear-history row. Reduce them
        # to the final effort per physical step instead of drawing a y=x staircase.
        if field in {"pseudo_iterations", "newton_iterations", "iterations"}:
            grouped = {
                label: [list(item) for item in {
                    point[0]: max(candidate[1] for candidate in points if candidate[0] == point[0])
                    for point in points
                }.items()]
                for label, points in grouped.items()
            }
        for label, points in grouped.items():
            points.sort(key=lambda point: point[0])
            if last_n is not None:
                grouped[label] = points[-last_n:]
        x_label = "Physical time" if uses_physical_time else "Physical timestep"
        x_kind = "continuous" if uses_physical_time else "integer"
 
    grouped = {label: points for label, points in grouped.items() if points}
    if not grouped:
        raise ValueError(f"Plot series '{series}' has no plottable points in the selected window.")
    if is_iteration_history and len(selected_steps) == 1:
        grouped = {
            label.rsplit(" · step ", 1)[0]: points
            for label, points in grouped.items()
        }
    all_values = [point[1] for points in grouped.values() for point in points]
    use_log = not linear_y and field in _SUMMARY_PLOT_LOG_SCALE_FIELDS and all(value > 0 for value in all_values)
    window_token = f"last-{last_n}" if last_n is not None else "full"
    safe_series = re.sub(r"[^A-Za-z0-9_.-]+", "_", series)
    fallback = os.path.join(
        context["run_dir"], CANONICAL_RUN_PATHS["plots"],
        f"{safe_series}_{window_token}.png",
    )
    field_label = _summary_field_label(field)
    source_title = _SUMMARY_PLOT_SOURCE_TITLES.get(source, _humanize_plot_identifier(source))
    title = f"{source_title}: {field_label}"
    if is_iteration_history:
        title += " convergence"
    subtitle_bits = []
    if selected_steps:
        ordered = sorted(selected_steps)
        subtitle_bits.append(
            f"Latest physical step {ordered[0]}" if len(ordered) == 1
            else f"Latest available physical steps {ordered[0]}–{ordered[-1]}"
        )
    if last_n is not None:
        subtitle_bits.append(f"Last {last_n} samples per curve")
    legend_title = {
        "continuity": "Block",
        "momentum": "Block",
        "poisson": "Block",
        "profiling": "Function",
        "spectra": "Spectrum task",
    }.get(source, "Series")
    only_label = next(iter(grouped)) if len(grouped) == 1 else None
    show_legend = len(grouped) > 1 or bool(
        only_label and (only_label.lower().startswith("block ") or source == "profiling")
    )
    return {
        "schema_version": 1,
        "plot_type": "iteration_history" if is_iteration_history else "time_history",
        "series": series,
        "title": title,
        "subtitle": " · ".join(subtitle_bits) or None,
        "x_label": x_label,
        "x_kind": x_kind,
        "y_label": field_label,
        "y_scale": "log" if use_log else "linear",
        "include_zero_y": not use_log and all(value >= 0.0 for value in all_values),
        "show_markers": not is_iteration_history,
        "show_legend": show_legend,
        "legend_title": legend_title,
        "window": {"mode": "last" if last_n is not None else "full", "last": last_n},
        "lines": [{"label": label, "points": points} for label, points in sorted(grouped.items())],
        "output_path": os.path.abspath(output_path) if output_path else None,
        "fallback_output_path": fallback,
    }
 
 
def _render_summary_plot_catalog(catalog: list, output_format: str):
    """!
    @brief Render available summarize plot-series metadata.
    @param[in] catalog Available series catalog.
    @param[in] output_format Text or JSON output format.
    """
    if output_format == "json":
        print(json.dumps({"available_series": catalog}, indent=2, sort_keys=True))
        return
    print("\nAVAILABLE PLOT SERIES")
    print("=" * 78)
    for item in catalog:
        labels = ", ".join(line["label"] for line in item["lines"])
        print(f"  {item['series']:<42} samples={item['sample_count']:<5} lines={labels}")
        print(f"    source: {', '.join(os.path.relpath(path) for path in item['source_paths'])}")
 
 
# The run's CSV records `summarize --table` prints, by name: (directory key, file name).
# Per-block solver histories take a `:<block>` suffix (block 0 by default).
SUMMARY_TABLES = {
    "continuity": ("log_dir", "Continuity_Metrics.csv"),
    "convergence": ("log_dir", "solution_convergence.csv"),
    "memory": ("log_dir", RUNTIME_MEMORY_FILE),
    "profiling": ("log_dir", "ProfilingSummary_Solver.csv"),
    "profiling-post": ("log_dir", "ProfilingSummary_PostProcessor.csv"),
    "profiling-steps": ("log_dir", PROFILING_TIMESTEP_FILE),
    "picard": ("log_dir", "Momentum_Solver_DualTime_Picard_Jameson_RK_History_Block_{block}.csv"),
    "newton": ("log_dir", "Momentum_Solver_Newton_Krylov_Summary_Block_{block}.csv"),
    "newton-history": ("log_dir", "Momentum_Solver_Newton_Krylov_History_Block_{block}.csv"),
    "newton-linear": ("log_dir", "Momentum_Solver_Newton_Krylov_Linear_History_Block_{block}.csv"),
    "poisson": ("log_dir", "Poisson_Solver_Convergence_History_Block_{block}.csv"),
    "search": ("metrics_dir", "search_metrics.csv"),
    "scatter": ("metrics_dir", "scatter_metrics.csv"),
    "interpolation-error": ("metrics_dir", "interpolation_error.csv"),
    "les": ("metrics_dir", "les_coefficient.csv"),
    "wall-model": ("metrics_dir", "wall_model.csv"),
    "driven-flow": ("metrics_dir", "driven_flow.csv"),
    "particle-initial-fields": ("metrics_dir", "particle_initial_fields.csv"),
}
 
 
def _summary_table_path(context: dict, name: str) -> str:
    """!
    @brief Resolve a `summarize --table` name to the CSV it prints.
    @param[in] context Summary context returned by `_build_summary_context()`.
    @param[in] name Table name from SUMMARY_TABLES, optionally `:<block>`.
    @return Path to the CSV (it may not exist).
    @throws ValueError When the name is unknown or the block is not an integer.
    """
    base, _, block = name.partition(":")
    if base not in SUMMARY_TABLES:
        raise ValueError(f"Unknown table '{base}'. Known tables: {', '.join(sorted(SUMMARY_TABLES))}.")
    if block and not block.isdigit():
        raise ValueError(f"Table block '{block}' must be a non-negative integer.")
    directory_key, file_name = SUMMARY_TABLES[base]
    if "{block}" in file_name:
        file_name = file_name.format(block=int(block or 0))
    elif block:
        raise ValueError(f"Table '{base}' is not per-block; drop ':{block}'.")
    return os.path.join(context[directory_key], file_name)
 
 
def _list_summary_tables(context: dict, output_format: str):
    """!
    @brief Print the `summarize --table` names whose CSV this run has, with row counts.
    @param[in] context Summary context returned by `_build_summary_context()`.
    @param[in] output_format Text or JSON output format.
    """
    found = []
    for name in sorted(SUMMARY_TABLES):
        names = [name]
        if "{block}" in (SUMMARY_TABLES[name][1] or ""):
            pattern = os.path.join(context["log_dir"], SUMMARY_TABLES[name][1].format(block="*"))
            blocks = sorted(int(re.search(r"_Block_(\d+)\.csv$", path).group(1)) for path in glob.glob(pattern))
            names = [name if b == 0 else f"{name}:{b}" for b in blocks]
        for table in names:
            path = _summary_table_path(context, table)
            if os.path.isfile(path):
                rows = list(_read_runtime_diagnostics_csv(path))
                columns = len(rows[0][1]) if rows else 0
                found.append({"table": table, "rows": len(rows), "columns": columns, "path": path})
    if output_format == "json":
        print(json.dumps({"available_tables": found}, indent=2, sort_keys=True))
        return
    if not found:
        raise ValueError("No CSV records were found in the run (a run older than the CSV records keeps text logs).")
    print("\nAVAILABLE TABLES")
    print("=" * 78)
    for item in found:
        print(f"  {item['table']:<26} rows={item['rows']:<7} columns={item['columns']:<3} {os.path.relpath(item['path'])}")
 
 
def _render_summary_table(context: dict, name: str, last_n, columns, output_format: str):
    """!
    @brief Print the last rows of one of the run's CSV records as aligned columns (or JSON).
    @param[in] context Summary context returned by `_build_summary_context()`.
    @param[in] name Table name (`summarize --list-tables`).
    @param[in] last_n Rows to show from the end; None shows the last 20.
    @param[in] columns Comma-separated column names to keep, or None for all.
    @param[in] output_format Text or JSON output format.
    @throws ValueError When the table is unknown, absent, or a requested column is missing.
    """
    path = _summary_table_path(context, name)
    if not os.path.isfile(path):
        raise ValueError(f"Table '{name}' has no file at {os.path.relpath(path)}; --list-tables names the ones this run has.")
    rows = list(_read_runtime_diagnostics_csv(path))
    if not rows:
        raise ValueError(f"Table '{name}' has no data rows yet.")
    header = list(rows[0][1].keys())
    if columns:
        wanted = [column.strip() for column in columns.split(",") if column.strip()]
        missing = [column for column in wanted if column not in header]
        if missing:
            raise ValueError(f"Table '{name}' has no column(s) {', '.join(missing)}; its columns are: {', '.join(header)}.")
        keep = ([header[0]] if header[0] not in wanted else []) + wanted
    else:
        keep = header
    shown = rows[-(last_n or 20):]
    if output_format == "json":
        print(json.dumps({"table": name, "path": path, "columns": keep,
                          "rows": [{"segment": segment, **{key: row.get(key) for key in keep}} for segment, row in shown]},
                         indent=2))
        return
    widths = {key: max(len(key), *(len(row.get(key) or "") for _, row in shown)) for key in keep}
    print(f"\n{name}: {os.path.relpath(path)} (last {len(shown)} of {len(rows)} rows)")
    print("  ".join(key.rjust(widths[key]) for key in keep))
    print("  ".join("-" * widths[key] for key in keep))
    previous_segment = shown[0][0]
    for segment, row in shown:
        if segment != previous_segment:
            print(f"# continuation segment {segment}")
            previous_segment = segment
        print("  ".join((row.get(key) or "").rjust(widths[key]) for key in keep))
 
 
def _invoke_plot_gen(request: dict):
    """!
    @brief Invoke standalone plot.gen with one normalized request over stdin.
    @param[in] request Versioned normalized plot request.
    """
    plotgen_path = os.path.join(GENERATORS_PATH, "plot.gen")
    if not os.path.isfile(plotgen_path):
        raise ValueError(f"plot.gen script not found: {plotgen_path}")
    result = subprocess.run(
        [sys.executable, plotgen_path, "--input", "-"],
        input=json.dumps(request),
        text=True,
        capture_output=True,
        check=False,
    )
    if result.stdout:
        print(result.stdout.rstrip())
    if result.returncode != 0:
        details = (result.stderr or result.stdout or "unknown plotting error").strip()
        if result.returncode == 3:
            raise PlotDependencyError(details)
        raise ValueError(f"plot.gen failed with exit code {result.returncode}: {details}")
 
 
def summarize_workflow(args):
    """!
    @brief Build and render a read-only health summary for a run step.
    @param[in] args Command-line style argument list supplied to the function.
    """
    if args.step is not None and args.step < 0:
        fail_cli_usage("--step must be a non-negative integer.")
    if args.snapshot_rows < 1:
        fail_cli_usage("--snapshot-rows must be at least 1.")
    plot_series = getattr(args, "plot_series", None)
    list_plot_series = bool(getattr(args, "list_plot_series", False))
    plot_spectrum = getattr(args, "plot_spectrum", None)
    last_n = getattr(args, "last_n", None)
    plot_output = getattr(args, "plot_output", None)
    linear_y = bool(getattr(args, "linear_y", False))
    table = getattr(args, "table", None)
    list_tables = bool(getattr(args, "list_tables", False))
    table_columns = getattr(args, "table_columns", None)
    plot_mode = bool(plot_series or list_plot_series or plot_spectrum is not None or table or list_tables)
    existing_selectors = any(
        [
            getattr(args, "overview", False),
            getattr(args, "case", False),
            getattr(args, "solver", False),
            getattr(args, "monitor", False),
            args.step is not None,
            getattr(args, "latest", False),
            getattr(args, "max_step", False),
        ]
    )
    if plot_mode and existing_selectors:
        fail_cli_usage("Plot discovery and --plot cannot be combined with config or selected-step selectors.")
    if not plot_series and not table and last_n is not None:
        fail_cli_usage("--last requires --plot or --table.")
    if table_columns and not table:
        fail_cli_usage("--columns requires --table.")
    if not plot_series and plot_spectrum is None and (plot_output or linear_y):
        fail_cli_usage("--plot-output and --linear-y require --plot or --plot-spectrum.")
    if last_n is not None and last_n < 1:
        fail_cli_usage("--last must be a positive integer.")
    if plot_series and args.output_format == "json":
        fail_cli_usage("--plot does not support --format json; use --list-plot-series --format json for structured discovery.")
    if table or list_tables:
        context = _build_summary_context(args.run_dir)
        try:
            if list_tables:
                _list_summary_tables(context, args.output_format)
            else:
                _render_summary_table(context, table, last_n, table_columns, args.output_format)
        except ValueError as exc:
            emit_structured_error(
                ERROR_CODE_CFG_INVALID_VALUE,
                key="table",
                file_path=context["log_dir"],
                message=str(exc),
                hint="--list-tables names the CSV records this run has.",
            )
            sys.exit(1)
        return
    if plot_mode:
        context = _build_summary_context(args.run_dir)
        try:
            records = _collect_summary_plot_records(context)
            catalog = _build_summary_plot_catalog(records)
            if list_plot_series:
                if not catalog:
                    raise ValueError("No plottable scalar histories were found in the run logs.")
                _render_summary_plot_catalog(catalog, args.output_format)
                return
            if plot_spectrum is not None:
                request = _build_spectrum_plot_request(
                    context, plot_spectrum, True, linear_y, plot_output
                )
            else:
                request = _build_summary_plot_request(
                    context, records, plot_series, last_n, linear_y, plot_output
                )
            _invoke_plot_gen(request)
            return
        except PlotDependencyError as exc:
            emit_structured_error(
                ERROR_CODE_DEPENDENCY_MISSING,
                key="plotting",
                file_path=sys.executable,
                message=str(exc),
            )
            sys.exit(1)
        except ValueError as exc:
            emit_structured_error(
                ERROR_CODE_CFG_INVALID_VALUE,
                key="plot",
                file_path=context["log_dir"],
                message=str(exc),
                hint=("--list-plot-series names the scalar histories this run recorded."
                      if plot_spectrum is None else
                      "Spectra come from the spectra tasks of a post.yml (see the post-processing reference)."),
            )
            sys.exit(1)
 
    selected_configs = {
        name
        for name in ("case", "solver", "monitor")
        if bool(getattr(args, name, False))
    }
    if getattr(args, "overview", False):
        selected_configs.update({"case", "solver", "monitor"})
    explicit_health = args.step is not None or bool(getattr(args, "latest", False)) or bool(getattr(args, "max_step", False))
    health_requested = explicit_health or (not selected_configs and not getattr(args, "overview", False))
 
    context = None
    combined = {"storage": storage_state_summary(args.run_dir)}
    if selected_configs or getattr(args, "overview", False):
        context = _build_summary_context(args.run_dir)
        if getattr(args, "overview", False):
            combined["run_overview"] = _build_run_overview(context)
        combined["configuration"] = {}
        builders = {
            "case": _build_case_overview,
            "solver": _build_solver_overview,
            "monitor": _build_monitor_overview,
        }
        for name in ("case", "solver", "monitor"):
            if name in selected_configs:
                try:
                    combined["configuration"][name] = builders[name](context)
                except (KeyError, TypeError, ValueError, ZeroDivisionError) as exc:
                    emit_structured_error(
                        ERROR_CODE_CFG_INVALID_VALUE,
                        key=name,
                        file_path=context["config_paths"][name],
                        message=f"Could not summarize copied {name}.yml: {exc}",
                    )
                    sys.exit(1)
 
    if not health_requested:
        combined["_health_requested"] = False
        render_selected_summary(combined, output_format=args.output_format)
        return
 
    requested_step = args.step
    if requested_step is None and getattr(args, "latest", False):
        requested_step = None
    selection_mode = "max_step" if getattr(args, "max_step", False) else "latest"
    health_payload = build_run_summary_payload(
        args.run_dir,
        step=requested_step,
        snapshot_rows=args.snapshot_rows,
        selection_mode=selection_mode,
    )
    if set(combined) == {"storage"}:
        combined = {**health_payload, **combined, "_health_requested": True}
        render_selected_summary(combined, output_format=args.output_format)
        return
    combined = {**health_payload, **combined, "_health_requested": True}
    render_selected_summary(combined, output_format=args.output_format)
 
 
def _resolve_submission_target(run_dir: str = None, study_dir: str = None) -> dict:
    """!
    @brief Resolve a run/study submission target from explicit directory flags.
    @param[in] run_dir Argument passed to `_resolve_submission_target()`.
    @param[in] study_dir Argument passed to `_resolve_submission_target()`.
    @return Value returned by `_resolve_submission_target()`.
    """
    has_run_dir = bool(run_dir)
    has_study_dir = bool(study_dir)
    if has_run_dir == has_study_dir:
        fail_cli_usage("submit requires exactly one of --run-dir or --study-dir.")
 
    target_kind = "run" if has_run_dir else "study"
    target_key = "run_dir" if target_kind == "run" else "study_dir"
    root_dir = os.path.abspath(run_dir if has_run_dir else study_dir)
    if not os.path.isdir(root_dir):
        emit_structured_error(
            ERROR_CODE_CFG_FILE_NOT_FOUND,
            key=target_key,
            file_path=root_dir,
            message=f"{'Run' if target_kind == 'run' else 'Study'} directory not found.",
        )
        sys.exit(1)
 
    scheduler_dir = os.path.join(root_dir, "scheduler")
    submission_path = os.path.join(scheduler_dir, "submission.json")
    continuation = False
    if target_kind == "study":
        # `sweep --continue` stages its scripts in a set of their own; the set staged
        # last is the one to submit.
        continue_path = os.path.join(scheduler_dir, "submission_continue.json")
        if os.path.isfile(continue_path) and (
                not os.path.isfile(submission_path)
                or os.path.getmtime(continue_path) >= os.path.getmtime(submission_path)):
            submission_path, continuation = continue_path, True
    submission_meta = _read_json_if_exists(submission_path)
    if not isinstance(submission_meta, dict):
        emit_structured_error(
            ERROR_CODE_CFG_FILE_NOT_FOUND,
            key="scheduler.submission",
            file_path=submission_path,
            message="Target directory does not contain scheduler submission metadata.",
            hint="Use a Slurm-staged run/study directory with scheduler/submission.json, or submit the script manually.",
        )
        sys.exit(1)
 
    launch_mode = str(submission_meta.get("launch_mode", "")).lower()
    if launch_mode == "local" and target_kind != "run":
        emit_structured_error(
            ERROR_CODE_CFG_INCONSISTENT_COMBO,
            key="scheduler.launch_mode",
            file_path=submission_path,
            message="Local staged submission is supported for run directories only.",
            hint="Use --run-dir for local staged execution; study submit remains Slurm-only.",
        )
        sys.exit(1)
    if launch_mode not in {"slurm", "local"}:
        emit_structured_error(
            ERROR_CODE_CFG_INCONSISTENT_COMBO,
            key="scheduler.launch_mode",
            file_path=submission_path,
            message=f"Target launch_mode={launch_mode or 'unknown'} is not supported.",
            hint="Use a staged run/study directory with launch_mode 'slurm' or a run directory with launch_mode 'local'.",
        )
        sys.exit(1)
 
    if target_kind == "run":
        script_map = {
            "solve": os.path.join(scheduler_dir, "solver.sbatch"),
            "post-process": os.path.join(scheduler_dir, "post.sbatch"),
        }
        display_label = "Run directory"
        manifest_path = None
    else:
        stage_keys = ({"solve": "solver_continue_array", "post-process": "post_continue_array",
                       "metrics": "metrics_aggregate"} if continuation else
                      {"solve": "solver_array", "post-process": "post_array",
                       "metrics": "metrics_aggregate"})
        default_scripts = ({"solve": "solver_continue_array.sbatch", "post-process": "post_continue_array.sbatch",
                            "metrics": "metrics_continue_aggregate.sbatch"} if continuation else
                           {"solve": "solver_array.sbatch", "post-process": "post_array.sbatch",
                            "metrics": "metrics_aggregate.sbatch"})
        script_map = {
            stage: ((submission_meta.get(key) or {}).get("script")
                    or os.path.join(scheduler_dir, default_scripts[stage]))
            for stage, key in stage_keys.items()
        }
        display_label = "Study continuation" if continuation else "Study directory"
        manifest_path = os.path.join(root_dir, "study_manifest.json")
 
    return {
        "target_kind": target_kind,
        "target_key": target_key,
        "root_dir": root_dir,
        "scheduler_dir": scheduler_dir,
        "submission_path": submission_path,
        "submission_meta": submission_meta,
        "launch_mode": launch_mode,
        "script_map": script_map,
        "display_label": display_label,
        "manifest_path": manifest_path,
        "continuation": continuation,
        "stage_keys": stage_keys if target_kind == "study" else None,
    }
 
 
def _get_submission_stage_metadata(target_context: dict, stage_name: str) -> dict:
    """!
    @brief Return stored metadata for one staged submission target.
    @param[in] target_context Argument passed to `_get_submission_stage_metadata()`.
    @param[in] stage_name Argument passed to `_get_submission_stage_metadata()`.
    @return Value returned by `_get_submission_stage_metadata()`.
    """
    submission_meta = target_context["submission_meta"]
    if target_context["target_kind"] == "run":
        stages = submission_meta.get("stages", {})
        if not isinstance(stages, dict):
            return {}
        stage_meta = stages.get(stage_name)
        return copy.deepcopy(stage_meta) if isinstance(stage_meta, dict) else {}
 
    stage_meta = submission_meta.get(target_context["stage_keys"][stage_name])
    return copy.deepcopy(stage_meta) if isinstance(stage_meta, dict) else {}
 
 
def _get_recorded_submission_stages(target_context: dict) -> list:
    """!
    @brief Return stage names explicitly recorded in scheduler submission metadata.
    @param[in] target_context Argument passed to `_get_recorded_submission_stages()`.
    @return Value returned by `_get_recorded_submission_stages()`.
    """
    submission_meta = target_context["submission_meta"]
    recorded = []
    if target_context["target_kind"] == "run":
        stages = submission_meta.get("stages", {})
        if isinstance(stages, dict):
            for stage_name in ["solve", "post-process"]:
                if isinstance(stages.get(stage_name), dict):
                    recorded.append(stage_name)
        return recorded
 
    for stage_name in ("solve", "post-process"):
        if isinstance(submission_meta.get(target_context["stage_keys"][stage_name]), dict):
            recorded.append(stage_name)
    return recorded
 
 
def _build_submit_missing_stage_hint(target_context: dict, requested_stage: str, selected_stages: list) -> str:
    """!
    @brief Build an actionable hint for requested submit stages missing from metadata.
    @param[in] target_context Argument passed to `_build_submit_missing_stage_hint()`.
    @param[in] requested_stage Argument passed to `_build_submit_missing_stage_hint()`.
    @param[in] selected_stages Argument passed to `_build_submit_missing_stage_hint()`.
    @return Value returned by `_build_submit_missing_stage_hint()`.
    """
    recorded_stages = _get_recorded_submission_stages(target_context)
    recorded_set = set(recorded_stages)
    selected_set = set(selected_stages)
    solve_stage_command = (
        "picurv run --solve ... --no-submit"
        if target_context["target_kind"] == "run"
        else "picurv sweep --cluster <cluster.yml> ... --no-submit"
    )
    post_stage_command = (
        "picurv run --post-process --post <post.yml> ... --no-submit"
        if target_context["target_kind"] == "run"
        else "picurv sweep --cluster <cluster.yml> ... --no-submit"
    )
    solve_post_command = (
        "picurv run --solve --post-process --post <post.yml> ... --no-submit"
        if target_context["target_kind"] == "run"
        else "picurv sweep --cluster <cluster.yml> ... --no-submit"
    )
 
    if requested_stage == "all" and not recorded_set:
        return (
            "--stage all submits every staged stage, but submission metadata records none. "
            f"Re-stage with `{solve_stage_command}` or `{post_stage_command}`."
        )
 
    if selected_set == {"solve"} and "solve" not in recorded_set:
        return (
            "The solve stage was requested, but submission metadata does not record a staged solve command/script. "
            f"Re-stage with `{solve_stage_command}`."
        )
    if selected_set == {"post-process"} and "post-process" not in recorded_set:
        return (
            "The post-process stage was requested, but submission metadata does not record a staged post-process command/script. "
            f"Re-stage with post-processing enabled (`{post_stage_command}`, or `{solve_post_command}`)."
        )
 
    return "Re-stage the requested stage(s) with picurv run/sweep --no-submit before calling picurv submit."
 
 
def _set_submission_stage_metadata(target_context: dict, stage_name: str, stage_meta: dict):
    """!
    @brief Persist one stage's metadata back into the submission payload.
    @param[in] target_context Argument passed to `_set_submission_stage_metadata()`.
    @param[in] stage_name Argument passed to `_set_submission_stage_metadata()`.
    @param[in] stage_meta Argument passed to `_set_submission_stage_metadata()`.
    """
    submission_meta = target_context["submission_meta"]
    if target_context["target_kind"] == "run":
        stages = submission_meta.get("stages")
        if not isinstance(stages, dict):
            stages = {}
            submission_meta["stages"] = stages
        stages[stage_name] = stage_meta
        return
 
    submission_meta[target_context["stage_keys"][stage_name]] = stage_meta
 
 
def _write_submission_target_metadata(target_context: dict):
    """!
    @brief Write updated submission metadata back to disk.
    @param[in] target_context Argument passed to `_write_submission_target_metadata()`.
    """
    write_json_file(target_context["submission_path"], target_context["submission_meta"])
 
    manifest_path = target_context.get("manifest_path")
    if manifest_path and os.path.isfile(manifest_path):
        manifest_payload = _read_json_if_exists(manifest_path)
        if isinstance(manifest_payload, dict):
            if target_context.get("continuation"):
                manifest_payload.setdefault("continuation", {})["submission"] = target_context["submission_meta"]
            else:
                manifest_payload["submission"] = target_context["submission_meta"]
            write_json_file(manifest_path, manifest_payload)
 
 
def staged_control_directories(control_path: str) -> tuple:
    """!
    @brief Read run-owned directory values from a staged control file.
 
    @details Tokenizes with `shlex` because PETSc's options-file parser treats a
             double-quoted span as a single token. Splitting on whitespace would read
             `-log_dir "/tmp/VICTIM DIR"` as the value `"/tmp/VICTIM`, which looks
             relative and contained while PETSc would use the absolute path.
 
             Malformed quoting is reported rather than skipped: a line the parser
             cannot interpret is exactly the case where preflight must not assume the
             run is safe.
    @param[in] control_path Path to a generated `.control` file.
    @return Tuple of (values, parse_errors).
    """
    flag_to_key = {
        "-log_dir": "log",
        "-output_dir": "output",
        "-restart_dir": "restart",
        "-analysis_dir": "analysis",
    }
    values: dict = {}
    parse_errors: list = []
    try:
        lines = read_text_file_lines(control_path)
    except OSError as exc:
        return values, [f"could not be read ({exc})"]
    for number, line in enumerate(lines, start=1):
        if not line.strip():
            continue
        try:
            tokens = shlex.split(line, comments=True)
        except ValueError as exc:
            parse_errors.append(
                f"line {number} has malformed quoting and cannot be interpreted ({exc}); "
                f"refusing to assume it is safe"
            )
            continue
        if tokens and tokens[0] in RESERVED_INDIRECTION_FLAGS:
            parse_errors.append(
                f"line {number} uses '{tokens[0]}', which PETSc expands itself; its contents "
                f"cannot be checked here and could set a run directory. Re-stage without it"
            )
            continue
        if len(tokens) >= 2 and tokens[0] in flag_to_key:
            values[flag_to_key[tokens[0]]] = tokens[1]
    return values, parse_errors
 
 
def preflight_config_directories(root_dir: str) -> list:
    """!
    @brief Every config directory under a run or study root that may hold a control file.
 
    @details A study keeps its controls under `cases/<member>/config`, not at the study
             root, so a preflight that only looked at `<root>/config` was empty for every
             study. This walks the tree so members and nested runs are covered.
    @param[in] root_dir Run or study directory.
    @return Sorted config directory paths.
    """
    found: set = set()
    root = os.path.abspath(root_dir)
    direct = os.path.join(root, "config")
    if os.path.isdir(direct):
        found.add(direct)
    for current, dirnames, _ in os.walk(root):
        dirnames[:] = [d for d in dirnames if not os.path.islink(os.path.join(current, d))]
        if os.path.basename(current) == "config" and glob.glob(os.path.join(current, "*.control")):
            found.add(current)
    return sorted(found)
 
 
def preflight_staged_run_directories(root_dir: str) -> tuple:
    """!
    @brief Re-check run-directory safety against an already-staged run or study.
 
    @details Staging validates the configuration it is given, but a staged run can be
             edited, or produced by an older version, before submission. This re-reads the
             effective staged control files - across study members and nested runs - and
             applies the same rules as configuration validation, plus a physical
             containment check that a symlink cannot slip past.
    @param[in] root_dir Run or study directory being submitted.
    @return Tuple of (errors, warnings).
    """
    errors: list = []
    warnings: list = []
    config_dirs = preflight_config_directories(root_dir)
    if not config_dirs:
        return errors, warnings
    canonical = {
        "log": CANONICAL_RUN_PATHS["logs"],
        "output": CANONICAL_RUN_PATHS["output"],
        "restart": CANONICAL_RUN_PATHS["restart"],
        "analysis": CANONICAL_RUN_PATHS["metrics"],
    }
    for config_dir in config_dirs:
        run_root = os.path.dirname(config_dir)
        for control in sorted(glob.glob(os.path.join(config_dir, "*.control"))):
            staged, parse_errors = staged_control_directories(control)
            label = os.path.relpath(control)
            errors.extend(f"  {label}: {message}" for message in parse_errors)
            if not staged:
                continue
            for key, expected in canonical.items():
                actual = staged.get(key)
                if actual is not None and normalized_run_directory(actual) != expected:
                    errors.append(
                        f"  {label}: -{key}_dir is {actual!r}; the canonical value is "
                        f"{expected!r}. Re-stage the run instead of editing its path flags."
                    )
            effective = effective_run_directories(staged)
            control_errors, control_warnings = evaluate_run_directories(
                effective, False, explicit=set(staged)
            )
            errors.extend(f"  {label}: {message}" for message in control_errors)
            warnings.extend(f"  {label}: {message}" for message in control_warnings)
            for _, verdict, message in classify_physical_containment(run_root, effective):
                errors.append(f"  {label}: {message}")
    return errors, warnings
 
 
def read_text_file_lines(path: str) -> list:
    """!
    @brief Read a text file into a list of lines.
    @param[in] path File to read.
    @return List of lines.
    """
    with open(path, "r", encoding="utf-8", errors="replace") as handle:
        return handle.readlines()
 
 
def submit_staged_jobs(args):
    """!
    @brief Submit previously staged Slurm artifacts from an existing run/study directory.
    @param[in] args Command-line style argument list supplied to the function.
    """
    if getattr(args, "run_dir", None) and os.path.isdir(args.run_dir):
        adopt_relocated_artifact(args.run_dir)
    elif getattr(args, "study_dir", None) and os.path.isdir(args.study_dir):
        adopt_relocated_artifact(args.study_dir, kind="study")
    target_context = _resolve_submission_target(
        run_dir=getattr(args, "run_dir", None),
        study_dir=getattr(args, "study_dir", None),
    )
    try:
        require_storage_payload_local(target_context["root_dir"], "submission")
    except StorageError as exc:
        print(f"[FATAL] {exc}", file=sys.stderr)
        sys.exit(1)
    preflight_errors, preflight_warnings = preflight_staged_run_directories(
        target_context["root_dir"]
    )
    for warning in preflight_warnings:
        print(f"[WARNING] {warning.strip()}", file=sys.stderr)
    if preflight_errors:
        print(
            "[FATAL] Submission preflight failed: the staged run has an unsafe run-directory "
            "configuration.",
            file=sys.stderr,
        )
        for violation in preflight_errors:
            print(violation, file=sys.stderr)
        print(
            "  Re-stage the run so PICurv regenerates its canonical path flags.",
            file=sys.stderr,
        )
        sys.exit(1)
    if target_context["target_kind"] == "study":
        cold_cases = cold_study_members(target_context["root_dir"])
        if cold_cases:
            print(
                "[FATAL] Submission requires cold-storage study member(s): " + ", ".join(cold_cases),
                file=sys.stderr,
            )
            sys.exit(1)
    stage_order = ["solve", "post-process"]
    requested_stage = args.stage
    # `all` is every staged stage not yet submitted; when each was, every staged stage, so the
    # refusal names them; with none staged, both, so the error says how to stage one.
    recorded_stages = _get_recorded_submission_stages(target_context)
    pending_stages = [stage for stage in recorded_stages
                      if not _get_submission_stage_metadata(target_context, stage).get("submitted")]
    selected_stages = ([requested_stage] if requested_stage != "all"
                       else pending_stages or recorded_stages or stage_order)
 
    print(f"[INFO] {target_context['display_label']:<20}: {os.path.relpath(target_context['root_dir'])}")
    print(f"[INFO] Submission metadata : {os.path.relpath(target_context['submission_path'])}")
    print(f"[INFO] Requested stages    : {', '.join(selected_stages)}")
 
    if target_context.get("launch_mode") == "local":
        submit_staged_local_run(args, target_context, selected_stages)
        return
 
    stage_plans = []
    solve_existing_meta = _get_submission_stage_metadata(target_context, "solve")
    solve_existing_job_id = str(solve_existing_meta.get("job_id", "")).strip()
 
    for stage_name in selected_stages:
        existing_meta = _get_submission_stage_metadata(target_context, stage_name)
        script_path = target_context["script_map"][stage_name]
        missing_stage_hint = _build_submit_missing_stage_hint(target_context, requested_stage, selected_stages)
        if not existing_meta:
            emit_structured_error(
                ERROR_CODE_CFG_MISSING_KEY,
                key=f"scheduler.{stage_name}.metadata",
                file_path=target_context["submission_path"],
                message=f"Submission metadata does not record stage '{stage_name}'.",
                hint=missing_stage_hint,
            )
            sys.exit(1)
 
        if not os.path.isfile(script_path):
            emit_structured_error(
                ERROR_CODE_CFG_FILE_NOT_FOUND,
                key=f"scheduler.{stage_name}.script",
                file_path=script_path,
                message=f"Required {stage_name} sbatch artifact is missing.",
                hint=missing_stage_hint,
            )
            sys.exit(1)
 
        if existing_meta.get("submitted") and not args.force:
            emit_structured_error(
                ERROR_CODE_CFG_INCONSISTENT_COMBO,
                key=f"scheduler.{stage_name}.submitted",
                file_path=target_context["submission_path"],
                message=f"Stage '{stage_name}' is already recorded as submitted.",
                hint="Use --force to resubmit this stage intentionally.",
            )
            sys.exit(1)
 
        dependency = None
        if stage_name == "post-process":
            if "solve" in selected_stages:
                dependency = "__NEW_SOLVE_JOB_ID__"
            elif solve_existing_meta.get("submitted") and solve_existing_job_id:
                dependency = solve_existing_job_id
                end, state = slurm_job_end_state(solve_existing_job_id)
                if end == "completed":
                    # Slurm rejects a dependency on a job it has forgotten, and the post
                    # job plans from committed checkpoints when it starts, so a solve that
                    # already succeeded leaves nothing to wait for.
                    print(f"[INFO] Solve job {solve_existing_job_id} has completed; the post job is "
                          "submitted without a dependency.")
                    dependency = None
                elif end == "failed" and not args.force:
                    emit_structured_error(
                        ERROR_CODE_CFG_INCONSISTENT_COMBO,
                        key="scheduler.post-process.dependency",
                        file_path=target_context["submission_path"],
                        message=f"Solve job {solve_existing_job_id} ended {state}, so a post job waiting on its success would never start.",
                        hint="Resubmit the solve, or use --force to post-process the checkpoints it committed.",
                    )
                    sys.exit(1)
                elif end != "active" and end != "unchecked":
                    # Failed with --force, or ended in a state sacct cannot report.
                    print(f"[WARNING] Solve job {solve_existing_job_id} is no longer queued "
                          f"({state or 'end state unavailable from sacct'}); the post job is submitted "
                          "without a dependency and processes what was committed.", file=sys.stderr)
                    dependency = None
            elif solve_existing_meta and not args.force:
                # A post staged on its own has no solve to wait for: it reads a run solved
                # earlier and plans its steps from what is committed when it starts.
                emit_structured_error(
                    ERROR_CODE_CFG_INCONSISTENT_COMBO,
                    key="scheduler.post-process.dependency",
                    file_path=target_context["submission_path"],
                    message="This run's staged solve has not been submitted, so its post-process job would have nothing to read.",
                    hint="Submit --stage solve or --stage all first, or use --force to submit the post job without a dependency.",
                )
                sys.exit(1)
 
        stage_plans.append(
            {
                "stage": stage_name,
                "script": script_path,
                "dependency": dependency,
                "existing_meta": existing_meta,
            }
        )
 
    # A study aggregates its metrics after its post array, as `sweep` chains it, whether
    # or not every member succeeded.
    if target_context["target_kind"] == "study" and "post-process" in selected_stages:
        metrics_meta = _get_submission_stage_metadata(target_context, "metrics")
        metrics_script = target_context["script_map"]["metrics"]
        if metrics_meta and os.path.isfile(metrics_script) and (not metrics_meta.get("submitted") or args.force):
            stage_plans.append({
                "stage": "metrics",
                "script": metrics_script,
                "dependency": "__NEW_POST_JOB_ID__",
                "dependency_type": "afterany",
                "existing_meta": metrics_meta,
            })
 
    if args.dry_run:
        for plan in stage_plans:
            cmd = ["sbatch"]
            dependency = plan["dependency"]
            dependency_type = plan.get("dependency_type", "afterok")
            if dependency == "__NEW_SOLVE_JOB_ID__":
                cmd.append("--dependency=afterok:<new solve job id>")
            elif dependency == "__NEW_POST_JOB_ID__":
                cmd.append(f"--dependency={dependency_type}:<new post job id>")
            elif dependency:
                cmd.append(f"--dependency={dependency_type}:{dependency}")
            cmd.append(plan["script"])
            print(f"[DRY-RUN] Would run: {' '.join(cmd)}")
        print("[INFO] Dry-run only. No jobs were submitted.")
        return
 
    new_job_ids = {}
    for plan in stage_plans:
        dependency = plan["dependency"]
        dependency_type = plan.get("dependency_type", "afterok")
        if dependency == "__NEW_SOLVE_JOB_ID__":
            dependency = new_job_ids.get("solve")
        elif dependency == "__NEW_POST_JOB_ID__":
            dependency = new_job_ids.get("post-process")
 
        submit_info = submit_sbatch(plan["script"], dependency=dependency, dependency_type=dependency_type)
        stage_meta = copy.deepcopy(plan["existing_meta"])
        stage_meta.update(submit_info)
        stage_meta["script"] = plan["script"]
        stage_meta["submitted"] = True
        if dependency:
            stage_meta["dependency"] = f"{dependency_type}:{dependency}"
        else:
            stage_meta.pop("dependency", None)
 
        _set_submission_stage_metadata(target_context, plan["stage"], stage_meta)
        print(f"[SUCCESS] Submitted {plan['stage']} job: {submit_info['job_id']}")
        new_job_ids[plan["stage"]] = submit_info["job_id"]
 
    _write_submission_target_metadata(target_context)
 
 
def submit_staged_local_run(args, target_context: dict, selected_stages: list):
    """!
    @brief Execute previously staged local run commands from scheduler/submission.json.
    @param[in] args Command-line style argument list supplied to the function.
    @param[in] target_context Resolved submission target context.
    @param[in] selected_stages Ordered stage names selected by the user.
    """
    if target_context["target_kind"] != "run":
        emit_structured_error(
            ERROR_CODE_CFG_INCONSISTENT_COMBO,
            key="scheduler.launch_mode",
            file_path=target_context["submission_path"],
            message="Local staged execution is supported for run directories only.",
            hint="Use --run-dir for local staged execution.",
        )
        sys.exit(1)
 
    stage_plans = []
    solve_existing_meta = _get_submission_stage_metadata(target_context, "solve")
    # Only a solve staged in this same set can still be pending; a post staged on its own
    # reads a run solved earlier and plans its steps from what is committed when it starts.
    solve_pending = bool(solve_existing_meta) and not bool(
        solve_existing_meta.get("submitted") or solve_existing_meta.get("executed"))
 
    for stage_name in selected_stages:
        existing_meta = _get_submission_stage_metadata(target_context, stage_name)
        command = existing_meta.get("command")
        if not isinstance(command, list) or not command:
            if existing_meta:
                hint = "Re-stage the run with picurv run --no-submit before calling picurv submit."
            else:
                hint = _build_submit_missing_stage_hint(target_context, args.stage, selected_stages)
            emit_structured_error(
                ERROR_CODE_CFG_MISSING_KEY,
                key=f"scheduler.{stage_name}.command",
                file_path=target_context["submission_path"],
                message=f"Required local command metadata for stage '{stage_name}' is missing.",
                hint=hint,
            )
            sys.exit(1)
 
        if existing_meta.get("submitted") and not args.force:
            emit_structured_error(
                ERROR_CODE_CFG_INCONSISTENT_COMBO,
                key=f"scheduler.{stage_name}.submitted",
                file_path=target_context["submission_path"],
                message=f"Stage '{stage_name}' is already recorded as submitted.",
                hint="Use --force to execute this stage again intentionally.",
            )
            sys.exit(1)
 
        if stage_name == "post-process" and "solve" not in selected_stages and not args.force and solve_pending:
            emit_structured_error(
                ERROR_CODE_CFG_INCONSISTENT_COMBO,
                key="scheduler.post-process.dependency",
                file_path=target_context["submission_path"],
                message="This run's staged solve has not run yet, so its post-process stage has nothing to read.",
                hint="Submit --stage solve or --stage all first, or use --force to run the post stage anyway.",
            )
            sys.exit(1)
 
        log_file = existing_meta.get("log_file")
        if not isinstance(log_file, str) or not log_file.strip():
            log_file = os.path.join("scheduler", f"{os.path.basename(target_context['root_dir'])}_{stage_name}.log")
 
        stage_plans.append(
            {
                "stage": stage_name,
                "command": [str(token) for token in command],
                "log_file": log_file,
                "existing_meta": existing_meta,
            }
        )
 
    if args.dry_run:
        for plan in stage_plans:
            print(f"[DRY-RUN] Would run: {format_command_for_display(plan['command'])}")
            print(f"[DRY-RUN] Log file : {plan['log_file']}")
        print("[INFO] Dry-run only. No local commands were executed.")
        return
 
    monitor_cfg = None
    monitor_path = os.path.join(target_context["root_dir"], "config", "monitor.yml")
    if os.path.isfile(monitor_path):
        monitor_cfg = read_yaml_file(monitor_path)
 
    for plan in stage_plans:
        if plan["stage"] == "solve":
            try:
                with runtime_stage_lock(target_context["root_dir"], "solver"):
                    execute_command(plan["command"], target_context["root_dir"], plan["log_file"], monitor_cfg)
            except StorageError as exc:
                print(f"[FATAL] {exc}", file=sys.stderr)
                sys.exit(1)
        else:
            execute_command(plan["command"], target_context["root_dir"], plan["log_file"], monitor_cfg)
        stage_meta = copy.deepcopy(plan["existing_meta"])
        stage_meta["command"] = plan["command"]
        stage_meta["command_string"] = format_command_for_display(plan["command"])
        stage_meta["log_file"] = plan["log_file"]
        stage_meta["submitted"] = True
        stage_meta["executed"] = True
        stage_meta["completed_at"] = datetime.now().isoformat()
        _set_submission_stage_metadata(target_context, plan["stage"], stage_meta)
        print(f"[SUCCESS] Executed local {plan['stage']} stage.")
 
    _write_submission_target_metadata(target_context)
 
 
def cancel_run_jobs(args):
    """!
    @brief Cancel Slurm-submitted jobs for an existing run directory.
    @param[in] args Command-line style argument list supplied to the function.
    """
    run_dir = os.path.abspath(args.run_dir)
    if not os.path.isdir(run_dir):
        emit_structured_error(
            ERROR_CODE_CFG_FILE_NOT_FOUND,
            key="run_dir",
            file_path=run_dir,
            message="Run directory not found.",
        )
        sys.exit(1)
 
    submission_path = os.path.join(run_dir, "scheduler", "submission.json")
    submission_meta = _read_json_if_exists(submission_path)
    if not isinstance(submission_meta, dict):
        emit_structured_error(
            ERROR_CODE_CFG_FILE_NOT_FOUND,
            key="scheduler.submission",
            file_path=submission_path,
            message="Run directory does not contain scheduler submission metadata.",
            hint="Use a Slurm-submitted run directory with scheduler/submission.json, or cancel the job manually.",
        )
        sys.exit(1)
 
    launch_mode = str(submission_meta.get("launch_mode", "")).lower()
    if launch_mode != "slurm":
        emit_structured_error(
            ERROR_CODE_CFG_INCONSISTENT_COMBO,
            key="scheduler.launch_mode",
            file_path=submission_path,
            message=f"Run directory launch_mode={launch_mode or 'unknown'} is not Slurm.",
            hint="picurv cancel currently supports Slurm-submitted runs only.",
        )
        sys.exit(1)
 
    stage_order = ["solve", "post-process"]
    requested_stage = args.stage
    selected_stages = stage_order if requested_stage == "all" else [requested_stage]
    recorded_stages = submission_meta.get("stages", {})
    if not isinstance(recorded_stages, dict):
        recorded_stages = {}
 
    job_to_stages = {}
    skipped = []
    for stage_name in selected_stages:
        stage_meta = recorded_stages.get(stage_name)
        if not isinstance(stage_meta, dict):
            skipped.append((stage_name, "no stage metadata recorded"))
            continue
 
        job_id = str(stage_meta.get("job_id", "")).strip()
        if not stage_meta.get("submitted"):
            skipped.append((stage_name, "job was generated but not submitted"))
            continue
        if not job_id:
            skipped.append((stage_name, "submitted stage is missing a recorded job id"))
            continue
 
        job_to_stages.setdefault(job_id, []).append(stage_name)
 
    if not job_to_stages:
        print(f"[INFO] Run directory       : {os.path.relpath(run_dir)}")
        print(f"[INFO] Submission metadata : {os.path.relpath(submission_path)}")
        for stage_name, reason in skipped:
            print(f"[INFO] Skipping stage '{stage_name}': {reason}")
        print("[FATAL] No submitted Slurm job IDs were found for the requested stage selection.", file=sys.stderr)
        sys.exit(1)
 
    print(f"[INFO] Run directory       : {os.path.relpath(run_dir)}")
    print(f"[INFO] Submission metadata : {os.path.relpath(submission_path)}")
    print(f"[INFO] Requested stages    : {', '.join(selected_stages)}")
 
    if skipped:
        for stage_name, reason in skipped:
            print(f"[INFO] Skipping stage '{stage_name}': {reason}")
 
    graceful = bool(getattr(args, "graceful", False))
    failures = []
    for job_id, stage_names in job_to_stages.items():
        joined_stage_names = ", ".join(stage_names)
        use_graceful_signal = graceful and "solve" in stage_names
        scancel_cmd = ["scancel"]
        if use_graceful_signal:
            # A directly launched ``mpirun`` replaces the batch shell (via ``exec``)
            # and is therefore not necessarily a Slurm job step.  ``--full`` also
            # signals the batch process and its children, so the MPI launcher can
            # forward SIGUSR1 to the solver ranks.
            scancel_cmd.extend(["--signal=USR1", "--full"])
        scancel_cmd.append(job_id)
 
        if args.dry_run:
            print(f"[DRY-RUN] Would run: {' '.join(scancel_cmd)}  # stage(s): {joined_stage_names}")
            continue
 
        # scancel exits 0 for a job that already ended, so ask Slurm before claiming a cancel.
        status, end_state = slurm_job_end_state(job_id)
        # Every status but "active" with a recorded end state is a job Slurm has finished.
        if end_state and status != "active":
            print(f"[INFO] Slurm job {job_id} for stage(s) {joined_stage_names} already ended "
                  f"({end_state}); nothing to cancel.")
            continue
 
        result = subprocess.run(scancel_cmd, text=True, capture_output=True, check=False)
        stderr_text = (result.stderr or "").strip()
        stdout_text = (result.stdout or "").strip()
        if result.returncode == 0:
            if use_graceful_signal:
                print(
                    f"[SUCCESS] Requested graceful shutdown for Slurm job {job_id} for stage(s): {joined_stage_names}. "
                    "Solver jobs trap SIGUSR1 and write the latest safe off-cadence step at the next checkpoint."
                )
            else:
                print(f"[SUCCESS] Canceled Slurm job {job_id} for stage(s): {joined_stage_names}")
            continue
 
        detail = stderr_text or stdout_text or "unknown scancel failure"
        failures.append((job_id, joined_stage_names, detail, result.returncode))
        print(
            f"[ERROR] Failed to cancel Slurm job {job_id} for stage(s) {joined_stage_names}: {detail}",
            file=sys.stderr,
        )
 
    if args.dry_run:
        print("[INFO] Dry-run only. No jobs were canceled.")
        return
 
    if failures:
        sys.exit(1)
 
 
def _workspace_yaml_role(path: str):
    """!
    @brief Infer the owned workspace role of one copied YAML file.
    @param[in] path YAML file copied from an example template.
    @return One of case, solver, monitor, post, cluster, study, or None.
    """
    try:
        payload = read_yaml_file(path)
    except (OSError, ValueError):
        return None
    keys = set(payload)
    if {"grid", "properties", "run_control"} <= keys:
        return "case"
    if "base_configs" in keys and ("study_type" in keys or "parameters" in keys or "parameter_sets" in keys):
        return "study"
    if "scheduler" in keys and "resources" in keys:
        return "cluster"
    # Any key only a post recipe owns; a spectra- or statistics-only recipe has no
    # pipeline, and source_data is optional. run_control is shared with case.yml.
    post_only = _POST_SCHEMA[()] - _MONITOR_SCHEMA[()] - {"run_control"}
    if keys & post_only or ("run_control" in keys and not keys & _CASE_SCHEMA[()] - {"run_control", "title"}):
        return "post"
    if "io" in keys and ("logging" in keys or "profiling" in keys or "diagnostics" in keys):
        return "monitor"
    if "momentum_solver" in keys or "poisson_solver" in keys or "operation_mode" in keys:
        return "solver"
    return None
 
 
def _rewrite_workspace_path_values(value, replacements: dict):
    """!
    @brief Rewrite copied template path scalars to workspace-root-relative homes.
    @param[in] value YAML subtree to rewrite.
    @param[in] replacements Old relative/basename paths mapped to new workspace paths.
    @return Rewritten YAML subtree.
    """
    if isinstance(value, dict):
        return {key: _rewrite_workspace_path_values(item, replacements) for key, item in value.items()}
    if isinstance(value, list):
        return [_rewrite_workspace_path_values(item, replacements) for item in value]
    if not isinstance(value, str):
        return value
    normalized = value.replace("\\", "/").lstrip("./")
    return replacements.get(normalized, replacements.get(os.path.basename(normalized), value))
 
 
def _choose_primary_workspace_role(candidates: list, role: str, template_name: str):
    """!
    @brief Select the canonical role file from a template that may carry variants.
    @param[in] candidates Candidate absolute YAML paths.
    @param[in] role Config role being selected.
    @param[in] template_name Source example directory name.
    @return Selected absolute path or None.
    """
    if not candidates:
        return None
    preferred = {
        "case": ("case.yml", f"{template_name}.yml", "master_case.yml"),
        "solver": ("solver.yml", "Imp-MG-Standard.yml", "master_solver.yml"),
        "monitor": ("monitor.yml", "Standard_Output.yml", "master_monitor.yml"),
        "post": ("post.yml", "standard_analysis.yml", "master_postprocessor.yml"),
        "cluster": ("cluster.yml", "slurm_cluster.yml", "master_cluster.yml"),
    }.get(role, ())
    by_name = {os.path.basename(path): path for path in candidates}
    for name in preferred:
        if name in by_name:
            return by_name[name]
    return sorted(candidates)[0]
 
 
def organize_initialized_workspace(workspace_root: str, template_name: str,
                                   source_template_root: str = None) -> dict:
    """!
    @brief Convert a copied example into the canonical editable workspace layout.
    @param[in] workspace_root Newly copied workspace root.
    @param[in] template_name Example template identity.
    @param[in] source_template_root Optional original template root used to vendor references.
    @return Mapping of canonical config roles and relocated imported inputs.
    """
    workspace_root = os.path.abspath(workspace_root)
    ensure_workspace_layout(workspace_root)
    # Skip the workspace's own runs/ and studies/ trees, judged inside the workspace: a
    # workspace that itself sits under a directory named runs/ must still be organized.
    yaml_files = [
        str(path)
        for pattern in ("*.yml", "*.yaml")
        for path in Path(workspace_root).rglob(pattern)
        if path.name not in {RUNTIME_EXECUTION_EXAMPLE_FILENAME, RUNTIME_EXECUTION_CONFIG_FILENAME}
        and not {"runs", "studies"} & set(path.relative_to(workspace_root).parts)
    ]
    vendored_replacements = {}
    if source_template_root:
        source_template_root = os.path.abspath(source_template_root)
 
        def vendor_references(value, source_yaml: str, dotted: str = ""):
            """!
            @brief Vendor referenced generator inputs into canonical workspace homes.
            @param[in] value YAML subtree to inspect.
            @param[in] source_yaml Original template YAML path.
            @param[in] dotted Current dotted key path.
            @return None.
            """
            if isinstance(value, dict):
                for key, child in value.items():
                    vendor_references(child, source_yaml, f"{dotted}.{key}" if dotted else str(key))
                return
            if isinstance(value, list):
                for index, child in enumerate(value):
                    vendor_references(child, source_yaml, f"{dotted}[{index}]")
                return
            key = dotted.rsplit(".", 1)[-1]
            if key not in _VENDORABLE_CONFIG_REFERENCE_KEYS or not isinstance(value, str) or not value.strip():
                return
            origin = os.path.abspath(os.path.join(os.path.dirname(source_yaml), value))
            if not os.path.isfile(origin):
                return
            if key == "script":
                home = "config/generators"
            elif "grid" in dotted:
                home = "config/grids"
            elif "initial_condition" in dotted:
                home = "config/initial_conditions"
            elif "inlet" in dotted or "boundary_conditions" in dotted:
                home = "config/inlet_profiles"
            else:
                home = "config"
            destination = os.path.join(workspace_root, *home.split("/"), os.path.basename(origin))
            os.makedirs(os.path.dirname(destination), exist_ok=True)
            if not os.path.exists(destination):
                shutil.copy2(origin, destination)
            relative = os.path.relpath(destination, workspace_root).replace(os.sep, "/")
            vendored_replacements[value.replace("\\", "/").lstrip("./")] = relative
            vendored_replacements[os.path.basename(value)] = relative
 
        for copied_yaml in sorted(set(yaml_files)):
            relative = os.path.relpath(copied_yaml, workspace_root)
            source_yaml = os.path.join(source_template_root, relative)
            if not os.path.isfile(source_yaml):
                continue
            try:
                vendor_references(read_yaml_file(copied_yaml), source_yaml)
            except (OSError, ValueError):
                continue
    roles = {}
    for path in sorted(set(yaml_files)):
        role = _workspace_yaml_role(path)
        if role:
            roles.setdefault(role, []).append(path)
 
    selected = {
        role: _choose_primary_workspace_role(paths, role, template_name)
        for role, paths in roles.items() if role != "study"
    }
    destinations = {}
    occupied = set()
    for role, paths in roles.items():
        for source in paths:
            if role == "study":
                relative = os.path.join("config", "studies", os.path.basename(source))
            elif source == selected.get(role):
                relative = os.path.join("config", f"{role}.yml")
            else:
                relative = os.path.join("config", os.path.basename(source))
            destination = os.path.join(workspace_root, relative)
            if os.path.abspath(source) == os.path.abspath(destination):
                destinations[source] = relative.replace(os.sep, "/")
                occupied.add(os.path.abspath(destination))
                continue
            if os.path.abspath(destination) in occupied or os.path.exists(destination):
                original_relative = os.path.relpath(source, workspace_root)
                relative = os.path.join("config", "variants", original_relative)
                destination = os.path.join(workspace_root, relative)
                counter = 2
                while os.path.abspath(destination) in occupied or os.path.exists(destination):
                    stem, suffix = os.path.splitext(relative)
                    destination = os.path.join(workspace_root, f"{stem}-{counter}{suffix}")
                    counter += 1
            os.makedirs(os.path.dirname(destination), exist_ok=True)
            shutil.move(source, destination)
            destinations[source] = relative.replace(os.sep, "/")
            occupied.add(os.path.abspath(destination))
 
    input_extensions = {
        ".picgrid": "inputs/grids",
        ".vts": "inputs/grids",
        ".picslice": "inputs/inlet_profiles",
        ".dat": "inputs/initial_conditions",
    }
    input_moves = {}
    for path in sorted(Path(workspace_root).rglob("*")):
        if not path.is_file() or path.suffix.lower() not in input_extensions:
            continue
        if any(part in _WORKSPACE_MANAGED_PATHS for part in path.relative_to(workspace_root).parts):
            continue
        destination_dir = os.path.join(workspace_root, *input_extensions[path.suffix.lower()].split("/"))
        destination = os.path.join(destination_dir, path.name)
        if os.path.exists(destination):
            continue
        old_relative = path.relative_to(workspace_root).as_posix()
        shutil.move(str(path), destination)
        new_relative = os.path.relpath(destination, workspace_root).replace(os.sep, "/")
        input_moves[old_relative] = new_relative
        input_moves[path.name] = new_relative
 
    config_replacements = {}
    basename_counts = {}
    for source in destinations:
        basename = os.path.basename(source)
        basename_counts[basename] = basename_counts.get(basename, 0) + 1
    for source, relative in destinations.items():
        old_relative = os.path.relpath(source, workspace_root).replace(os.sep, "/")
        config_replacements[old_relative] = relative
        if basename_counts[os.path.basename(source)] == 1:
            config_replacements[os.path.basename(source)] = relative
    replacements = {**config_replacements, **input_moves, **vendored_replacements}
    for path in sorted(Path(workspace_root, "config").rglob("*.yml")):
        payload = read_yaml_file(str(path))
        local_replacements = dict(replacements)
        original_source = next(
            (
                source for source, relative in destinations.items()
                if os.path.abspath(os.path.join(workspace_root, relative)) == os.path.abspath(path)
            ),
            None,
        )
        if original_source:
            original_parent = os.path.dirname(original_source)
            for candidate_source, candidate_relative in destinations.items():
                relative_reference = os.path.relpath(candidate_source, original_parent).replace(os.sep, "/")
                local_replacements[relative_reference] = candidate_relative
                if os.path.dirname(candidate_source) == original_parent:
                    local_replacements[os.path.basename(candidate_source)] = candidate_relative
        rewritten = _rewrite_workspace_path_values(payload, local_replacements)
        role = _workspace_yaml_role(str(path))
        if role == "monitor" and isinstance(rewritten.get("io"), dict):
            rewritten["io"].pop("directories", None)
        if role == "case" and path == Path(workspace_root, "config", "case.yml"):
            rewritten.setdefault("title", template_name)
        if role == "post":
            if isinstance(rewritten.get("source_data"), dict):
                rewritten["source_data"].pop("directory", None)
            if isinstance(rewritten.get("io"), dict):
                rewritten["io"].pop("output_directory", None)
        if role == "study" and isinstance(rewritten.get("base_configs"), dict):
            for role in ("case", "solver", "monitor", "post"):
                canonical = os.path.join("config", f"{role}.yml").replace(os.sep, "/")
                if os.path.isfile(os.path.join(workspace_root, canonical)):
                    rewritten["base_configs"][role] = canonical
        write_yaml_file(str(path), rewritten)
 
    return {
        "workspace_config": initialize_workspace_root(workspace_root, template_name),
        "canonical_roles": {
            role: os.path.join(workspace_root, "config", f"{role}.yml")
            for role in ("case", "solver", "monitor", "post", "cluster")
            if os.path.isfile(os.path.join(workspace_root, "config", f"{role}.yml"))
        },
        "input_moves": input_moves,
    }
 
 
WORKSPACE_INPUT_DIRECTORIES = {
    "grid": "inputs/grids",
    "initial-condition": "inputs/initial_conditions",
    "inlet-profile": "inputs/inlet_profiles",
    "reference-field": "inputs/reference_fields",
}
 
 
def import_workspace_input(workspace_root: str, kind: str, source: str,
                           name: str = None, mode: str = "copy") -> dict:
    """!
    @brief Explicitly import or register one workspace input.
    @param[in] workspace_root Initialized workspace root.
    @param[in] kind Semantic input kind.
    @param[in] source Existing source file path.
    @param[in] name Optional destination basename.
    @param[in] mode Copy, reflink, hardlink, or external-reference mode.
    @return Catalog entry describing the durable input identity.
    """
    workspace_root = os.path.abspath(workspace_root)
    load_workspace_config(workspace_root)
    ensure_workspace_layout(workspace_root)
    if kind not in WORKSPACE_INPUT_DIRECTORIES:
        raise ValueError(f"Unsupported input kind: {kind}")
    source = os.path.abspath(os.path.expanduser(source))
    if not os.path.isfile(source):
        raise ValueError(f"Input source is not a file: {source}")
    basename = name or os.path.basename(source)
    if basename != os.path.basename(basename) or basename in _PLAIN_FILENAME_SENTINELS:
        raise ValueError("--name must be a plain filename without directory traversal.")
    target_dir = os.path.join(workspace_root, *WORKSPACE_INPUT_DIRECTORIES[kind].split("/"))
    os.makedirs(target_dir, exist_ok=True)
    if mode == "reference":
        destination = os.path.join(target_dir, basename + ".reference.yml")
        write_yaml_file(destination, {
            "schema_version": 1,
            "picurv_external_reference": source,
            "sha256_at_registration": _asset_file_sha256(source),
            "bytes_at_registration": os.path.getsize(source),
        })
    else:
        destination = os.path.join(target_dir, basename)
        if os.path.exists(destination):
            raise ValueError(f"Workspace input already exists: {destination}")
        temporary = f"{destination}.tmp.{os.getpid()}"
        try:
            if mode == "copy":
                shutil.copy2(source, temporary)
            elif mode == "hardlink":
                os.link(source, temporary)
            elif mode == "reflink":
                cp = shutil.which("cp")
                if not cp:
                    raise ValueError("reflink mode requires the 'cp' command.")
                result = subprocess.run(
                    [cp, "--reflink=always", "--preserve=mode,timestamps", source, temporary],
                    text=True, capture_output=True, check=False,
                )
                if result.returncode != 0:
                    raise ValueError((result.stderr or "reflink copy failed").strip())
            else:
                raise ValueError(f"Unsupported import mode: {mode}")
            os.replace(temporary, destination)
        finally:
            if os.path.lexists(temporary):
                os.remove(temporary)
    relative = os.path.relpath(destination, workspace_root).replace(os.sep, "/")
    entry_id = _stable_mapping_sha256({"kind": kind, "path": relative, "source": source})[:16]
    catalog_path = os.path.join(workspace_root, "inputs", "catalog.yml")
    catalog = read_yaml_file(catalog_path) if os.path.isfile(catalog_path) else {
        "schema_version": 1, "inputs": {}
    }
    catalog.setdefault("inputs", {})[entry_id] = {
        "kind": kind,
        "path": relative,
        "mode": mode,
        "sha256": _asset_file_sha256(source),
        "bytes": os.path.getsize(source),
        "source": source if mode == "reference" else None,
        "registered_at": datetime.now().astimezone().isoformat(),
    }
    write_yaml_file(catalog_path, catalog)
    return {"id": entry_id, **catalog["inputs"][entry_id]}
 
 
def inputs_workflow(args):
    """!
    @brief Handle explicit workspace input management.
    @param[in] args Parsed inputs command arguments.
    @return None.
    """
    workspace_root = os.path.abspath(args.workspace) if args.workspace else find_workspace_root(os.getcwd())
    if not workspace_root:
        raise ValueError("No initialized workspace found; run picurv init first or pass --workspace.")
    if args.inputs_action != "import":
        raise ValueError(f"Unsupported inputs action: {args.inputs_action}")
    entry = import_workspace_input(
        workspace_root, args.kind, args.source, name=args.name, mode=args.mode
    )
    print(f"[SUCCESS] Registered input {entry['id']}: {entry['path']}")
    if entry["mode"] == "reference":
        print("[WARNING] This is an external reference. Storage will record it but will not copy or prune its target.")
 
 
def version_workflow(args):
    """!
    @brief Report, and for the `status` action validate, the shared build identity.
 
    @details Bare `picurv version` reports and always succeeds; it is an informational
             surface that scripts and documentation already depend on. `picurv version
             status` additionally exits non-zero when the conductor, the executables,
             and the workspace requirement do not agree, so a job script can refuse to
             launch a run whose provenance would be incoherent.
    @param[in] args Parsed version command arguments.
    @return None.
    """
    workspace_root = find_workspace_root(os.getcwd())
    payload = dict(picurv_build())
    payload["source_root"] = PACKAGE_PROJECT_ROOT
    payload["workspace"] = workspace_root
    payload["workspace_requirement"] = None
    if workspace_root:
        software = load_workspace_config(workspace_root).get("software") or {}
        payload["workspace_requirement"] = software.get("picurv") if isinstance(software, dict) else None
    payload["binaries"] = runtime_build_identities()
    for identity in payload["binaries"].values():
        library = resolved_petsc_library(identity["path"]) if identity.get("path") else None
        identity["petsc_library"] = library
        identity["petsc_library_mismatch"] = petsc_library_mismatch(identity.get("petsc"), library)
    validating = getattr(args, "version_action", None) == "status"
    problems = build_identity_problems(payload["binaries"], payload["workspace_requirement"])
    payload["coherent"] = not problems
    payload["problems"] = problems
    if getattr(args, "output_format", "text") == "json":
        print(json.dumps(payload, indent=2, sort_keys=True))
        if validating and problems:
            sys.exit(1)
        return
    print(f"PICurv release : {payload['release_version']}")
    print(f"Build identity : {payload['build_id']}")
    print(f"Git commit     : {payload.get('git_commit') or 'unavailable'}")
    print(f"Dirty tree     : {payload.get('dirty') if payload.get('dirty') is not None else 'unknown'}")
    if workspace_root:
        print(f"Workspace      : {workspace_root}")
        print(f"Requirement    : {payload['workspace_requirement'] or 'latest active version'}")
    print("\nNative executables")
    for name, identity in sorted(payload["binaries"].items()):
        if not identity.get("available"):
            print(f"  {name:<15}: unavailable ({identity.get('reason', 'unknown')})")
        else:
            agreement = "matches source" if identity["matches_source"] else "STALE - rebuild"
            print(f"  {name:<15}: {identity['build_id']} ({agreement})")
        _print_petsc_build(identity)
    if not problems:
        print("\nBuild identity is coherent.")
        return
    print("\nBuild identity is NOT coherent:", file=sys.stderr)
    for problem in problems:
        print(f"  - {problem}", file=sys.stderr)
    if validating:
        sys.exit(1)
 
 
def _print_petsc_build(identity: dict) -> None:
    """!
    @brief Print the PETSc an executable was built against and the library it would load.
    @param[in] identity One executable's entry from `runtime_build_identities()`, with
                        `petsc_library` and `petsc_library_mismatch` filled in.
    @return None.
    """
    petsc = identity.get("petsc")
    if not petsc:
        print(f"  {'':<15}  PETSc: not recorded (built before PETSc stamping)")
        return
    location = ", ".join(part for part in (petsc.get("arch"), petsc.get("dir")) if part)
    bits = 8 * PETSC_INDEX_BYTES[petsc.get("indices", "int32")]
    print(f"  {'':<15}  PETSc: {petsc['version']} {petsc['mode']}, {bits}-bit indices ({location})")
    library = identity.get("petsc_library")
    if library:
        flag = ("  <- NOT the PETSc it was built against; load that PETSc's module, "
                "or rebuild under this one") if identity["petsc_library_mismatch"] else ""
        print(f"  {'':<15}  loads: {library}{flag}")
 
 
def _require_clean_source_checkout(action: str) -> None:
    """!
    @brief Refuse version-changing Git operations in a dirty source checkout.
    @param[in] action User-facing action name.
    @return None.
    """
    result = subprocess.run(
        ["git", "status", "--porcelain"], cwd=PACKAGE_PROJECT_ROOT,
        text=True, capture_output=True, check=False,
    )
    if result.returncode != 0:
        raise ValueError(f"{action}: cannot inspect the PICurv Git checkout.")
    if result.stdout.strip():
        raise ValueError(
            f"{action}: the PICurv source checkout has uncommitted changes. "
            "Commit or stash them before changing versions."
        )
 
 
def _git_source_command(arguments: list) -> subprocess.CompletedProcess:
    """!
    @brief Run a checked Git command against the active PICurv source checkout.
    @param[in] arguments Git arguments excluding the executable.
    @return Completed successful Git process.
    """
    result = subprocess.run(
        ["git", *arguments], cwd=PACKAGE_PROJECT_ROOT,
        text=True, capture_output=True, check=False,
    )
    if result.returncode != 0:
        raise ValueError((result.stderr or result.stdout or "Git command failed.").strip())
    return result
 
 
def source_workflow(args):
    """!
    @brief Fetch source history without silently changing the active code.
    @param[in] args Parsed source command arguments.
    @return None.
    """
    if args.source_action != "update":
        raise ValueError(f"Unsupported source action: {args.source_action}")
    _git_source_command(["fetch", "--tags", "--prune", args.remote])
    print(f"[SUCCESS] Fetched branches and tags from {args.remote}; active checkout was not changed.")
 
 
def _workspace_requested_version(workspace_root: str):
    """!
    @brief Resolve an exact version requested by an initialized workspace.
    @param[in] workspace_root Initialized workspace root.
    @return Exact version or tag text.
    """
    software = load_workspace_config(workspace_root).get("software") or {}
    requirement = software.get("picurv") if isinstance(software, dict) else None
    if not requirement:
        raise ValueError(
            f"{workspace_root}/{WORKSPACE_CONFIG_FILENAME} has no software.picurv pin; "
            "name a version explicitly."
        )
    if any(token in str(requirement) for token in "<>=!~,*"):
        raise ValueError(
            "Automatic activation needs an exact release/tag, not a version range. "
            f"Pass the desired version explicitly (workspace requires {requirement!r})."
        )
    return str(requirement)
 
 
def versions_workflow(args):
    """!
    @brief List or activate a release using the existing source/build owners.
    @param[in] args Parsed versions command arguments.
    @return None.
    """
    action = args.versions_action
    if action == "list":
        result = _git_source_command(["tag", "--list", "--sort=-version:refname"])
        print(f"Active: {picurv_build()['build_id']}")
        tags = [line for line in result.stdout.splitlines() if line.strip()]
        if tags:
            print("Installed/available tags:")
            for tag in tags:
                print(f"  {tag}")
        else:
            print("No version tags are present in this checkout.")
        return
    version = getattr(args, "version", None)
    make_args = list(getattr(args, "make_args", None) or [])
    if version and (_MAKE_ASSIGNMENT_PATTERN.match(str(version)) or str(version).startswith("-")):
        # `versions activate SYSTEM=cluster` and `versions activate -- -j8` bind the
        # make argument to the optional version positional. No tag or commit contains
        # '=' or starts with '-', so either is a make argument; handing '-j8' to git as
        # a ref printed git's usage instead.
        make_args.insert(0, str(version))
        version = None
    if make_args_include_explicit_goal(make_args):
        raise ValueError(
            f"versions {action} builds the default target; pass only make variables and "
            f"options (for example SYSTEM=cluster), not a target: {' '.join(make_args)}"
        )
    if action == "activate" and not version:
        workspace_root = os.path.abspath(args.workspace) if args.workspace else find_workspace_root(os.getcwd())
        if not workspace_root:
            raise ValueError("No workspace found and no version was named.")
        version = _workspace_requested_version(workspace_root)
    if not version:
        raise ValueError(f"versions {action}: name the tag or commit to install.")
    if action not in _VERSION_BUILD_ACTIONS:
        raise ValueError(f"Unsupported versions action: {action}")
    _require_clean_source_checkout(f"versions {action}")
    # There is one installation, and this rewrites it in place. Anything resolving
    # executables from it - other workspaces, and any running job that did not pin its
    # binaries - is changed by this too, so say what is about to move before it moves.
    print(
        f"[WARNING] {PACKAGE_PROJECT_ROOT} is a single shared installation. Building "
        f"{version!r} here re-points every workspace that resolves executables from it, "
        "including any job already running against them.",
        file=sys.stderr,
    )
    print(
        "          Runs staged with --pin-executables keep their own copies and are unaffected; "
        "unpinned queued jobs stop at their job-start identity check.",
        file=sys.stderr,
    )
    _git_source_command(["fetch", "--tags", "origin"])
    ref = _resolve_version_ref(str(version))
    _git_source_command(["checkout", "--detach", ref])
    run_project_make(PACKAGE_PROJECT_ROOT, make_args)
    # picurv_build() was computed when this process started, before the checkout moved,
    # so the source identity the new binaries must match is read again here.
    source_identity = _source_build_identity(_read_release_version())
    problems = build_identity_problems(
        runtime_build_identities(source_identity), source_identity=source_identity
    )
    if problems:
        raise ValueError(
            f"Built {ref!r}, but the executables do not carry its identity "
            f"({source_identity['build_id']}):\n  - " + "\n  - ".join(problems)
        )
    print(f"[SUCCESS] Activated and built PICurv {ref} ({source_identity['build_id']}).")
 
 
def _resolve_version_ref(version: str) -> str:
    """!
    @brief Resolve a user-named version to a Git ref that exists in the source checkout.
    @details Release tags are spelled `v<release>`, while `VERSION` and workspace
             `software.picurv` pins carry the bare release. The name is tried as given
             first, so a commit, branch, or already-prefixed tag is never rewritten.
    @param[in] version Tag, bare release, or commit named by the user or workspace pin.
    @return Ref accepted by `git checkout --detach`.
    @throws ValueError when neither spelling resolves to a commit.
    """
    candidates = [version]
    if not version.startswith("v"):
        candidates.append(f"v{version}")
    for candidate in candidates:
        result = subprocess.run(
            ["git", "rev-parse", "--verify", "--quiet", f"{candidate}^{{commit}}"],
            cwd=PACKAGE_PROJECT_ROOT, text=True, capture_output=True, check=False,
        )
        if result.returncode == 0:
            return candidate
    raise ValueError(
        f"No tag or commit named {' or '.join(repr(c) for c in candidates)} exists in "
        f"{PACKAGE_PROJECT_ROOT}; 'picurv versions list' shows the available tags."
    )
 
 
def init_case(args):
    """!
    @brief Implements the 'init' command.
    @details Creates a new case study directory by copying a template.
             Runtime binaries are resolved from the project bin/ directory
             via PATH; pass --pin-binaries to pin specific versions locally.
    @param[in] args The command-line arguments parsed by argparse.
    """
    context = resolve_case_origin_context(source_root_override=getattr(args, "source_root", None))
    try:
        source_project_root = require_project_root(context["source_project_root"], "init")
        template_path = resolve_template_directory(source_project_root, args.template_name)
    except ValueError as exc:
        print(f"[FATAL] {exc}", file=sys.stderr)
        sys.exit(1)
 
    # The destination path is relative to the current working directory.
    dest_path = os.path.abspath(os.path.join(os.getcwd(), args.dest_name if args.dest_name else args.template_name))
 
    if os.path.exists(dest_path):
        print(f"[FATAL] Destination directory '{dest_path}' already exists.", file=sys.stderr)
        sys.exit(1)
 
    print(f"[INFO] Initializing new case '{os.path.basename(dest_path)}' from template '{args.template_name}'...")
 
    try:
        workspace_layout = render_template_workspace(template_path, args.template_name, dest_path)
        template_managed_files = list_rendered_template_files(dest_path)
        print(f"[SUCCESS] Copied template files to: {dest_path}")
        print(f"[INFO] Wrote workspace identity: {os.path.relpath(workspace_layout['workspace_config'])}")
        if workspace_layout["canonical_roles"]:
            print("[INFO] Canonical editable configurations:")
            for role, path in sorted(workspace_layout["canonical_roles"].items()):
                print(f"  - {role}: {os.path.relpath(path)}")
    except Exception as exc:
        print(f"[FATAL] Failed to create canonical workspace layout: {exc}", file=sys.stderr)
        shutil.rmtree(dest_path, ignore_errors=True)
        sys.exit(1)
 
    try:
        runtime_result = ensure_case_runtime_execution_config(dest_path, source_project_root, overwrite=True)
        print(f"[INFO] Wrote optional runtime launcher config: {os.path.relpath(runtime_result['path'])}")
        if runtime_result["seed_source"] and os.path.basename(runtime_result["seed_source"]) == RUNTIME_EXECUTION_CONFIG_FILENAME:
            print("       Seeded from repo-local '.picurv-execution.yml'.")
        print("       Leave it unchanged for ordinary local runs; edit it only if your site needs custom MPI launcher tokens.")
    except Exception as e:
        print(f"[ERROR] Failed to write runtime execution config: {e}", file=sys.stderr)
 
    try:
        metadata_path, _ = write_case_origin_metadata(
            dest_path,
            source_project_root,
            template_name=args.template_name,
            template_managed_files=template_managed_files,
        )
        print(f"[INFO] Wrote case origin metadata: {os.path.relpath(metadata_path)}")
    except Exception as e:
        print(f"[ERROR] Failed to write case origin metadata: {e}", file=sys.stderr)
 
    cluster_profile_candidates = sorted(
        {
            os.path.basename(path)
            for pattern in ("*cluster*.yml", "*cluster*.yaml")
            for search_root in (dest_path, os.path.join(dest_path, "config"))
            for path in glob.glob(os.path.join(search_root, pattern))
        }
    )
    if cluster_profile_candidates:
        print("[INFO] Cluster profile sample(s) copied with this case:")
        for profile_name in cluster_profile_candidates:
            print(f"  - {profile_name}")
        print("       Edit account/partition/module_setup and any batch-specific launcher overrides before using --cluster.")
 
    if getattr(args, "pin_binaries", False):
        print("[INFO] Pinning runtime binaries into case directory...")
        try:
            copied_binaries = sync_case_binaries(dest_path, source_project_root)
            for dest_file_path in copied_binaries:
                print(f"  - Pinned '{os.path.basename(dest_file_path)}'")
            print("[SUCCESS] Case directory is ready with pinned binaries.")
            print("          These local copies will be used instead of bin/ originals.")
        except ValueError as exc:
            print(f"[WARNING] {exc}", file=sys.stderr)
            print("          No binaries were pinned. Run 'picurv build' first.", file=sys.stderr)
    else:
        print("[SUCCESS] Case directory is ready.")
        print("          Runtime binaries (simulator, postprocessor) are resolved from the active PICurv installation.")
        print("          Pin software.picurv in .picurv-workspace.yml only when this workspace needs a release constraint.")
    print("          Ensure 'picurv' is on your PATH (source etc/picurv.sh) to run from any directory.")
 
 
def sync_case_config_command(args):
    """!
    @brief Refresh template-managed config/docs files in a case directory.
    @param[in] args Command-line style argument list supplied to the function.
    """
    try:
        context = resolve_case_origin_context(
            case_dir_hint=getattr(args, "case_dir", None),
            source_root_override=getattr(args, "source_root", None),
            template_name_override=getattr(args, "template_name", None),
        )
        source_project_root = require_project_root(context["source_project_root"], "sync-config")
        case_dir = require_existing_case_dir(context["case_dir"], "sync-config", source_project_root)
        template_name = context.get("template_name")
        template_dir = resolve_template_directory(source_project_root, template_name)
        existing_managed = context.get("metadata", {}).get("template_managed_files")
        if not isinstance(existing_managed, list):
            existing_managed = None
        summary = sync_case_template_files(
            case_dir,
            template_dir,
            overwrite=getattr(args, "overwrite", False),
            prune=getattr(args, "prune", False),
            managed_rel_paths=existing_managed,
            template_name=template_name,
        )
        metadata_path, _ = write_case_origin_metadata(
            case_dir,
            source_project_root,
            template_name=template_name,
            existing=context.get("metadata"),
            template_managed_files=summary["template_managed_files"],
        )
        runtime_result = ensure_case_runtime_execution_config(case_dir, source_project_root, overwrite=False)
    except ValueError as exc:
        print(f"[FATAL] {exc}", file=sys.stderr)
        sys.exit(1)
 
    print(f"[SUCCESS] Synced template files from '{template_name}' into: {case_dir}")
    print(f"[INFO] Copied new files     : {len(summary['copied'])}")
    print(f"[INFO] Overwritten files   : {len(summary['overwritten'])}")
    print(f"[INFO] Skipped modified    : {len(summary['skipped_modified'])}")
    print(f"[INFO] Already unchanged   : {len(summary['unchanged'])}")
    print(f"[INFO] Pruned stale files  : {len(summary['pruned'])}")
    if runtime_result["created"]:
        print(f"[INFO] Created runtime launcher config: {os.path.relpath(runtime_result['path'])}")
        if runtime_result["seed_source"] and os.path.basename(runtime_result["seed_source"]) == RUNTIME_EXECUTION_CONFIG_FILENAME:
            print("[INFO] Seed source              : repo-local .picurv-execution.yml")
    if summary.get("prune_requested_without_tracking"):
        print("[WARNING] Prune tracking unavailable for this case; no removed template files were deleted.", file=sys.stderr)
    print(f"[INFO] Case origin metadata refreshed: {os.path.relpath(metadata_path)}")
 
 
def pull_source_repo(args):
    """!
    @brief Refresh source branches in the repository resolved from a case directory.
    @param[in] args Command-line style argument list supplied to the function.
    """
    try:
        context = resolve_case_origin_context(
            case_dir_hint=getattr(args, "case_dir", None),
            source_root_override=getattr(args, "source_root", None),
        )
        source_project_root = require_project_root(context["source_project_root"], "pull-source")
    except ValueError as exc:
        print(f"[FATAL] {exc}", file=sys.stderr)
        sys.exit(1)
 
    try:
        _refuse_detached_source_checkout(source_project_root, "pull-source")
    except ValueError as exc:
        print(f"[FATAL] {exc}", file=sys.stderr)
        sys.exit(1)
 
    rebase = not getattr(args, "no_rebase", False)
    remote = getattr(args, "remote", None)
    branch = getattr(args, "branch", None)
    current_branch_only = (
        getattr(args, "current_branch_only", False)
        or remote is not None
        or branch is not None
    )
 
    if not current_branch_only:
        pull_all_source_branches(source_project_root, "pull-source.log", rebase=rebase)
        return
 
    command = ["git", "pull"]
    if rebase:
        command.append("--rebase")
    if remote:
        command.append(remote)
        if branch:
            command.append(branch)
    elif branch:
        command.extend(["origin", branch])
 
    execute_command(command, source_project_root, "pull-source.log", {})
 
def build_project(args):
    """!
    @brief Implements the 'build' command.
    @details Executes the top-level Makefile directly, passing through any
             additional arguments to `make`. This allows for building,
             cleaning, and other Makefile targets via the orchestrator
             without maintaining a separate build wrapper script.
    @param[in] args The command-line arguments parsed by argparse.
    """
 
    print("\n" + "="*27 + " BUILD STAGE " + "="*27)
    try:
        context = resolve_case_origin_context(
            case_dir_hint=getattr(args, "case_dir", None),
            source_root_override=getattr(args, "source_root", None),
        )
        source_project_root = require_project_root(context["source_project_root"], "build")
    except ValueError as exc:
        print(f"[FATAL] {exc}", file=sys.stderr)
        sys.exit(1)
 
    run_project_make(source_project_root, list(args.make_args or []))
 
 
def run_project_make(source_project_root: str, make_args: "list[str]") -> None:
    """!
    @brief Run the project Makefile with caller-supplied arguments, defaulting to `all`.
    @details Shared by `picurv build` and `picurv versions install/activate`, so a site
             setting such as `SYSTEM=cluster` reaches `make` the same way from both.
    @param[in] source_project_root PICurv source checkout containing the Makefile.
    @param[in] make_args Arguments passed through to `make`.
    @return None. Exits non-zero when the Makefile is missing or `make` fails.
    """
    makefile_path = os.path.join(source_project_root, "Makefile")
 
    if not os.path.isfile(makefile_path):
        print(f"[FATAL] Makefile not found at expected location: {makefile_path}", file=sys.stderr)
        print("        Please ensure the project root contains a valid Makefile.", file=sys.stderr)
        sys.exit(1)
 
    if make_args_include_explicit_goal(make_args):
        command = ["make"] + make_args
    else:
        command = ["make", "all"] + make_args
        print("[INFO] No explicit make target supplied; defaulting to 'all'.")
        print("       Use 'picurv build clean-project ...' or another target when you want a non-build make action.")
    # For the build process, we don't have a monitor.yml, so we pass an empty
    # dict to execute_command. The command should be run in the project root.
    execute_command(command, source_project_root, "build.log", {})
 
 
 
 
# ==============================================================================