uxarray-mcp 0.1.2__tar.gz → 0.1.3__tar.gz

{uxarray_mcp-0.1.2 → uxarray_mcp-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: uxarray-mcp
-Version: 0.1.2
+Version: 0.1.3
 Summary: MCP server for analyzing unstructured meshes with UXarray
 Keywords: uxarray,mcp,unstructured grids,scientific computing,globus compute
 Author: Rajeev Jain, Dayan Abdulla
@@ -299,6 +299,7 @@ uv tool install --python 3.12 uxarray-mcp
 # Or from a fresh clone (developer path)
 git clone https://github.com/UXARRAY/uxarray-mcp-server.git
 cd uxarray-mcp-server && uv sync --python 3.12
+# or: bash SETUP.sh   (does the sync + runs the local test suite in one step)
 ```
 
 > **Why `--python 3.12`?** The server uses Globus Compute to submit work to
@@ -350,8 +351,9 @@ client's MCP docs.
 uxarray-mcp doctor
 ```
 
-Should print `local execution: ok` and (if no endpoints configured) skip the
-remote checks.
+Prints a JSON diagnostic report. With no endpoints configured it reports a
+passing local setup and skips the remote checks; the process exits `0` when
+`passed` is true.
 
 ### Step 5 — Ask the AI to do something
 
@@ -361,6 +363,19 @@ In your client, try:
 
 That's it for local use.
 
+**A few more things to try:**
+
+- `Use run_analysis with operation="inspect_mesh" and grid_path="healpix:4"` —
+  no sample file needed; HEALPix meshes are generated on the fly.
+- `Run a complete scientific analysis on healpix:4` — the autonomous
+  Analyze → Plan → Execute → Verify agent (see
+  [docs/scientific-agent.md](docs/scientific-agent.md)).
+- `Create a session called baseline-analysis, register <grid> and <data> in
+  it, then run the workflow for <variable>` — persisted, resumable
+  multi-step runs (see [docs/workflows.md](docs/workflows.md)).
+- `Diagnose my configured endpoint status` — once you've added an endpoint
+  below, this is the fastest way to check it's healthy.
+
 ---
 
 ## Going beyond your laptop
@@ -380,21 +395,49 @@ Both paths assume you've finished local install above.
 
 ## What the MCP exposes
 
-Intent-shaped tools, not raw UXarray bindings:
+Intent-shaped tools, not raw UXarray bindings — all local by default:
 
 - `get_capabilities` — what can I do with this mesh?
 - `analyze_dataset` — deterministic first-look: inspect, validate, area, zonal mean, plots.
 - `run_analysis` — one operation at a time (gradient, curl, subset, remap, …).
 - `plot_dataset` — mesh, geographic, variable, or zonal-mean plots.
-- `diagnose_endpoint`, `probe_path_access` — endpoint health + file readability.
 - `run_workflow`, `resume_workflow`, `get_status`, `get_result`, `manage_session` —
   persisted sessions and multi-step workflows.
 
-Tools that can run remotely take `use_remote: bool` and optional `endpoint: str`.
-The dispatcher falls back to local if the endpoint is unhealthy.
-
 Full schema: [docs/tools.md](docs/tools.md).
 
+**Once you've configured an HPC endpoint** (optional — see
+[Going beyond your laptop](#going-beyond-your-laptop) below): most tools above
+also take `use_remote: bool` and `endpoint: str`, falling back to local if the
+endpoint is unhealthy. Two more tools exist purely for that case:
+`diagnose_endpoint` and `probe_path_access` (endpoint health + file
+readability). Ignore all of this until you actually have an endpoint to point
+at.
+
+---
+
+## Transparency & correctness safeguards
+
+Because agent-driven analysis needs to be *trustworthy*, every result is
+auditable and the server actively flags common scientific pitfalls:
+
+- **Provenance on everything.** Each result carries a `_provenance` block:
+  the tool that ran, timestamp, input arguments, `execution_venue`
+  (`local` or `hpc:<endpoint>`), and the UXarray/Python versions used.
+- **Derivative unit convention is never hidden.** `gradient`, `curl`, and
+  `divergence` echo `scale_by_radius` in both the result and provenance, so a
+  unit-sphere result can never be mistaken for a physical (per-metre) one.
+- **Vector-calculus sanity guard.** `curl`/`divergence` warn (without blocking)
+  when the two inputs are the same field, or when neither carries a
+  velocity/flux-like `units` attribute — the classic "vorticity from two random
+  scalars" mistake now surfaces a warning in `_provenance.warnings`.
+- **Local/remote version drift is surfaced.** Remote results record the
+  worker's *actual* UXarray version (`remote_uxarray_version`) and emit a
+  warning when it differs from the local version, so silent numerical
+  differences between venues can't slip through.
+- **Validation gating.** `analyze_dataset` validates a dataset (NaN/Inf/fill
+  checks) before computing statistics like the zonal mean.
+
 ---
 
 ## CLI reference
@@ -410,6 +453,24 @@ Full schema: [docs/tools.md](docs/tools.md).
 
 ---
 
+## Upgrading
+
+```bash
+uv tool upgrade --python 3.12 uxarray-mcp        # or your original install method
+```
+
+> **⚠️ Restart your AI client after upgrading.** MCP servers are launched once
+> when your client (Claude Desktop, Claude Code, Cursor, …) starts and are **not
+> hot-reloaded**. After upgrading the package, **fully quit and reopen your AI
+> client** so it relaunches `uxarray-mcp serve` with the new code. Until you do,
+> the running server keeps executing the *old* version — new tools and fixes
+> won't appear, and you may see confusing errors (for example, a `use_remote`
+> call on an HPC-only path failing with "file not found" because the old,
+> local-only tool is still loaded). If in doubt, run `uxarray-mcp doctor` and
+> check the reported version.
+
+---
+
 ## Risks (read before relying on output)
 
 AI agents can misread prompts, pick the wrong file, get units wrong (e.g.,

{uxarray_mcp-0.1.2 → uxarray_mcp-0.1.3}/README.md

@@ -63,6 +63,7 @@ uv tool install --python 3.12 uxarray-mcp
 # Or from a fresh clone (developer path)
 git clone https://github.com/UXARRAY/uxarray-mcp-server.git
 cd uxarray-mcp-server && uv sync --python 3.12
+# or: bash SETUP.sh   (does the sync + runs the local test suite in one step)
 ```
 
 > **Why `--python 3.12`?** The server uses Globus Compute to submit work to
@@ -114,8 +115,9 @@ client's MCP docs.
 uxarray-mcp doctor
 ```
 
-Should print `local execution: ok` and (if no endpoints configured) skip the
-remote checks.
+Prints a JSON diagnostic report. With no endpoints configured it reports a
+passing local setup and skips the remote checks; the process exits `0` when
+`passed` is true.
 
 ### Step 5 — Ask the AI to do something
 
@@ -125,6 +127,19 @@ In your client, try:
 
 That's it for local use.
 
+**A few more things to try:**
+
+- `Use run_analysis with operation="inspect_mesh" and grid_path="healpix:4"` —
+  no sample file needed; HEALPix meshes are generated on the fly.
+- `Run a complete scientific analysis on healpix:4` — the autonomous
+  Analyze → Plan → Execute → Verify agent (see
+  [docs/scientific-agent.md](docs/scientific-agent.md)).
+- `Create a session called baseline-analysis, register <grid> and <data> in
+  it, then run the workflow for <variable>` — persisted, resumable
+  multi-step runs (see [docs/workflows.md](docs/workflows.md)).
+- `Diagnose my configured endpoint status` — once you've added an endpoint
+  below, this is the fastest way to check it's healthy.
+
 ---
 
 ## Going beyond your laptop
@@ -144,21 +159,49 @@ Both paths assume you've finished local install above.
 
 ## What the MCP exposes
 
-Intent-shaped tools, not raw UXarray bindings:
+Intent-shaped tools, not raw UXarray bindings — all local by default:
 
 - `get_capabilities` — what can I do with this mesh?
 - `analyze_dataset` — deterministic first-look: inspect, validate, area, zonal mean, plots.
 - `run_analysis` — one operation at a time (gradient, curl, subset, remap, …).
 - `plot_dataset` — mesh, geographic, variable, or zonal-mean plots.
-- `diagnose_endpoint`, `probe_path_access` — endpoint health + file readability.
 - `run_workflow`, `resume_workflow`, `get_status`, `get_result`, `manage_session` —
   persisted sessions and multi-step workflows.
 
-Tools that can run remotely take `use_remote: bool` and optional `endpoint: str`.
-The dispatcher falls back to local if the endpoint is unhealthy.
-
 Full schema: [docs/tools.md](docs/tools.md).
 
+**Once you've configured an HPC endpoint** (optional — see
+[Going beyond your laptop](#going-beyond-your-laptop) below): most tools above
+also take `use_remote: bool` and `endpoint: str`, falling back to local if the
+endpoint is unhealthy. Two more tools exist purely for that case:
+`diagnose_endpoint` and `probe_path_access` (endpoint health + file
+readability). Ignore all of this until you actually have an endpoint to point
+at.
+
+---
+
+## Transparency & correctness safeguards
+
+Because agent-driven analysis needs to be *trustworthy*, every result is
+auditable and the server actively flags common scientific pitfalls:
+
+- **Provenance on everything.** Each result carries a `_provenance` block:
+  the tool that ran, timestamp, input arguments, `execution_venue`
+  (`local` or `hpc:<endpoint>`), and the UXarray/Python versions used.
+- **Derivative unit convention is never hidden.** `gradient`, `curl`, and
+  `divergence` echo `scale_by_radius` in both the result and provenance, so a
+  unit-sphere result can never be mistaken for a physical (per-metre) one.
+- **Vector-calculus sanity guard.** `curl`/`divergence` warn (without blocking)
+  when the two inputs are the same field, or when neither carries a
+  velocity/flux-like `units` attribute — the classic "vorticity from two random
+  scalars" mistake now surfaces a warning in `_provenance.warnings`.
+- **Local/remote version drift is surfaced.** Remote results record the
+  worker's *actual* UXarray version (`remote_uxarray_version`) and emit a
+  warning when it differs from the local version, so silent numerical
+  differences between venues can't slip through.
+- **Validation gating.** `analyze_dataset` validates a dataset (NaN/Inf/fill
+  checks) before computing statistics like the zonal mean.
+
 ---
 
 ## CLI reference
@@ -174,6 +217,24 @@ Full schema: [docs/tools.md](docs/tools.md).
 
 ---
 
+## Upgrading
+
+```bash
+uv tool upgrade --python 3.12 uxarray-mcp        # or your original install method
+```
+
+> **⚠️ Restart your AI client after upgrading.** MCP servers are launched once
+> when your client (Claude Desktop, Claude Code, Cursor, …) starts and are **not
+> hot-reloaded**. After upgrading the package, **fully quit and reopen your AI
+> client** so it relaunches `uxarray-mcp serve` with the new code. Until you do,
+> the running server keeps executing the *old* version — new tools and fixes
+> won't appear, and you may see confusing errors (for example, a `use_remote`
+> call on an HPC-only path failing with "file not found" because the old,
+> local-only tool is still loaded). If in doubt, run `uxarray-mcp doctor` and
+> check the reported version.
+
+---
+
 ## Risks (read before relying on output)
 
 AI agents can misread prompts, pick the wrong file, get units wrong (e.g.,

{uxarray_mcp-0.1.2 → uxarray_mcp-0.1.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "uxarray-mcp"
-version = "0.1.2"
+version = "0.1.3"
 description = "MCP server for analyzing unstructured meshes with UXarray"
 readme = "README.md"
 keywords = ["uxarray", "mcp", "unstructured grids", "scientific computing", "globus compute"]
@@ -93,6 +93,10 @@ extend-exclude = ["docs/architecture.html"]
 
 [tool.ruff.lint]
 extend-select = ["I"]
+# Notebooks (and their jupytext-paired .py scripts) intentionally scatter
+# imports across per-cell (# %%) blocks, so E402 (module-import-not-at-top)
+# is expected style there, not a lint violation.
+per-file-ignores = { "notebooks/*.py" = ["E402"], "notebooks/*.ipynb" = ["E402"] }
 
 [tool.ruff.lint.isort]
 known-first-party = ["uxarray_mcp"]

{uxarray_mcp-0.1.2 → uxarray_mcp-0.1.3}/src/uxarray_mcp/__init__.py

@@ -3,4 +3,4 @@
 from uxarray_mcp.tools import inspect_mesh
 
 __all__ = ["inspect_mesh"]
-__version__ = "0.1.2"
+__version__ = "0.1.3"

{uxarray_mcp-0.1.2 → uxarray_mcp-0.1.3}/src/uxarray_mcp/cli.py

@@ -308,8 +308,8 @@ def build_parser() -> argparse.ArgumentParser:
         choices=("core", "deferred-full"),
         default="core",
         help=(
-            "core: gateway + control + list_datasets + prompts (~27 tools). "
-            "deferred-full: also load 30 raw tools as deferred, gated "
+            "core: gateway + control + list_datasets + prompts (~31 tools). "
+            "deferred-full: also load 32 raw tools as deferred, gated "
             "behind discover_tools / admin promotion."
         ),
     )
@@ -317,7 +317,7 @@ def build_parser() -> argparse.ArgumentParser:
         "--transport",
         choices=("stdio", "sse", "http"),
         default="stdio",
-        help="MCP transport. stdio for Claude Desktop subprocess use.",
+        help="MCP transport. stdio for subprocess use by MCP clients.",
     )
     serve.add_argument("--host", default="127.0.0.1", help="Bind host for SSE/HTTP.")
     serve.add_argument("--port", type=int, default=8001, help="Port for SSE/HTTP.")
@@ -330,8 +330,8 @@ def build_parser() -> argparse.ArgumentParser:
         choices=("core", "deferred-full"),
         default="core",
         help=(
-            "core: gateway + control + list_datasets + prompts (~27 tools). "
-            "deferred-full: also load 30 raw tools as deferred, gated "
+            "core: gateway + control + list_datasets + prompts (~31 tools). "
+            "deferred-full: also load 32 raw tools as deferred, gated "
             "behind discover_tools / admin promotion."
         ),
     )
@@ -347,7 +347,11 @@ def build_parser() -> argparse.ArgumentParser:
         "--execution-mode",
         default="auto",
         choices=["local", "auto", "hpc"],
-        help="Default execution mode (default: auto).",
+        help=(
+            "Default execution mode (default: auto). 'auto' runs local-only "
+            "until you add an endpoint with `endpoints add`, then uses it "
+            "automatically. Most users never need to change this."
+        ),
     )
     setup.add_argument("--force", action="store_true", help="Overwrite existing file.")
     setup.set_defaults(func=cmd_setup)
@@ -377,12 +381,42 @@ def build_parser() -> argparse.ArgumentParser:
     ep_remove.add_argument("name")
     ep_remove.set_defaults(func=cmd_endpoints_remove)
 
-    doctor = sub.add_parser("doctor", help="Validate HPC readiness.")
-    doctor.add_argument("--sample-path", action="append", default=[])
-    doctor.add_argument("--timeout-seconds", type=int, default=180)
-    doctor.add_argument("--endpoint", default=None)
-    doctor.add_argument("--skip-remote-probe", action="store_true")
-    doctor.add_argument("--no-netcdf", action="store_true")
+    doctor = sub.add_parser(
+        "doctor",
+        help="Check that the install is healthy (local-only or HPC).",
+        description=(
+            "Run local-only by default; add an HPC endpoint (`endpoints add`) "
+            "to also validate remote readiness. With no endpoint configured, "
+            "this reports a passing local-only result — HPC is opt-in."
+        ),
+    )
+    doctor.add_argument(
+        "--sample-path",
+        action="append",
+        default=[],
+        help="Remote file path to test-read (repeatable). Requires an endpoint.",
+    )
+    doctor.add_argument(
+        "--timeout-seconds",
+        type=int,
+        default=180,
+        help="Seconds to wait for the remote worker probe (ignored if no endpoint).",
+    )
+    doctor.add_argument(
+        "--endpoint",
+        default=None,
+        help="Named endpoint to validate. Omit to check the default/local-only setup.",
+    )
+    doctor.add_argument(
+        "--skip-remote-probe",
+        action="store_true",
+        help="Skip submitting a test job to the endpoint (config/auth checks only).",
+    )
+    doctor.add_argument(
+        "--no-netcdf",
+        action="store_true",
+        help="Skip opening --sample-path as NetCDF; just check readability.",
+    )
     doctor.set_defaults(func=cmd_doctor)
 
     claude = sub.add_parser(

{uxarray_mcp-0.1.2 → uxarray_mcp-0.1.3}/src/uxarray_mcp/domain/mesh.py

@@ -47,17 +47,22 @@ def load_dataset(grid_path: str, data_path: str) -> Any:
         Loaded dataset object.
     """
     import uxarray as ux
+    import xarray as xr
 
-    # HEALPix is a special case (usually grid-only, but we support it if matched)
+    # HEALPix and GIS grids don't round-trip through ux.open_dataset() as a
+    # "grid file" the way a real UGRID/MPAS/SCRIP file does: grid.to_xarray()
+    # returns a minimal representation (e.g. HEALPix has no node coordinates)
+    # that the generic UGRID reader rejects. Attach the data directly to the
+    # already-loaded Grid object instead.
     if grid_path.lower().startswith("healpix"):
         parts = grid_path.split(":")
         zoom = int(parts[1]) if len(parts) > 1 else 1
         grid = ux.Grid.from_healpix(zoom=zoom)
-        return ux.open_dataset(grid.to_xarray(), data_path)
+        return ux.UxDataset(xr.open_dataset(data_path), uxgrid=grid)
 
     ext = os.path.splitext(grid_path.lower())[1]
     if ext in [".shp", ".geojson"]:
         grid = ux.Grid.from_file(grid_path, backend="geopandas")
-        return ux.open_dataset(grid.to_xarray(), data_path)
+        return ux.UxDataset(xr.open_dataset(data_path), uxgrid=grid)
 
     return ux.open_dataset(grid_path, data_path)

{uxarray_mcp-0.1.2 → uxarray_mcp-0.1.3}/src/uxarray_mcp/domain/vector_calc.py

@@ -4,6 +4,80 @@ from __future__ import annotations
 
 from typing import Any
 
+# Units that look like a genuine 2-D vector (velocity/flux) component. Used only
+# to raise a soft, non-blocking warning when curl/divergence inputs do not look
+# like real vector components — the math is still valid, but the result is only
+# physically meaningful for true vector fields.
+_VELOCITY_LIKE_UNIT_HINTS = (
+    "m/s",
+    "m s-1",
+    "m s^-1",
+    "meter/second",
+    "meters/second",
+    "cm/s",
+    "km/h",
+    "kg/m2/s",
+    "kg m-2 s-1",
+    "pa/s",
+    "n/m2",
+)
+
+
+def _vector_component_warnings(
+    u_variable: str,
+    v_variable: str,
+    u: Any,
+    v: Any,
+    operation: str,
+) -> list[str]:
+    """Return soft warnings when (u, v) do not look like real vector components.
+
+    curl and divergence are only physically meaningful when ``u`` and ``v`` are
+    the two horizontal components of a genuine vector field (e.g. eastward and
+    northward velocity). The underlying finite-volume operators will happily
+    compute a number from *any* two scalar fields, so this guardrail flags the
+    common misuse patterns without blocking the computation:
+
+    1. ``u`` and ``v`` are the same variable (a scalar used as both components).
+    2. Neither component carries a velocity/flux-like ``units`` attribute.
+
+    Warnings are attached to the result so the caller — and any downstream
+    scientist — can see that the inputs were suspicious.
+    """
+    warnings: list[str] = []
+
+    if u_variable == v_variable:
+        warnings.append(
+            f"{operation}: u_variable and v_variable are the same field "
+            f"('{u_variable}'). {operation} is only physically meaningful for a "
+            "true 2-D vector field (distinct eastward/northward components); "
+            "the result here is a mathematical artifact, not a physical "
+            f"{operation}."
+        )
+
+    def _unit(var: Any) -> str:
+        attrs = getattr(var, "attrs", {}) or {}
+        return str(attrs.get("units", "")).strip().lower()
+
+    u_unit, v_unit = _unit(u), _unit(v)
+
+    def _looks_velocity(unit: str) -> bool:
+        return any(hint in unit for hint in _VELOCITY_LIKE_UNIT_HINTS)
+
+    if not (_looks_velocity(u_unit) or _looks_velocity(v_unit)):
+        seen = ", ".join(
+            f"{name}='{unit or 'unset'}'"
+            for name, unit in ((u_variable, u_unit), (v_variable, v_unit))
+        )
+        warnings.append(
+            f"{operation}: neither component has a velocity/flux-like 'units' "
+            f"attribute ({seen}). Verify that '{u_variable}' and '{v_variable}' "
+            "are genuine vector components (e.g. m/s) before interpreting the "
+            f"{operation} physically."
+        )
+
+    return warnings
+
 
 def compute_gradient(
     uxds: Any, variable_name: str, scale_by_radius: bool = False
@@ -115,6 +189,10 @@ def compute_curl(
 
     import numpy as np
 
+    component_warnings = _vector_component_warnings(
+        u_variable, v_variable, u, v, "curl"
+    )
+
     result = u.curl(v, scale_by_radius=scale_by_radius)
     vals = result.values
     finite = vals[np.isfinite(vals)]
@@ -137,6 +215,7 @@ def compute_curl(
         "n_face": int(uxds.uxgrid.n_face),
         "scale_by_radius": bool(scale_by_radius),
         "stats": stats,
+        "component_warnings": component_warnings,
     }
 
 
@@ -179,6 +258,10 @@ def compute_divergence(uxds: Any, u_variable: str, v_variable: str) -> dict:
 
     import numpy as np
 
+    component_warnings = _vector_component_warnings(
+        u_variable, v_variable, u, v, "divergence"
+    )
+
     result = u.divergence(v)
     vals = result.values
     finite = vals[np.isfinite(vals)]
@@ -200,6 +283,7 @@ def compute_divergence(uxds: Any, u_variable: str, v_variable: str) -> dict:
         "interpretation": "horizontal divergence ∂u/∂x + ∂v/∂y",
         "n_face": int(uxds.uxgrid.n_face),
         "stats": stats,
+        "component_warnings": component_warnings,
     }
 
 

{uxarray_mcp-0.1.2 → uxarray_mcp-0.1.3}/src/uxarray_mcp/registry.py

@@ -5,9 +5,9 @@ Two profiles are supported:
 * ``"core"`` (default) — small, predictable surface visible to LLMs.
   Mirrors the original MCP server's 11 front-door tools, adds 12
   control/status tools, the ``list_datasets`` discovery helper, and
-  three prompt-as-tool helpers (former ``@mcp.prompt()`` decorators).
+  seven prompt-as-tool helpers (former ``@mcp.prompt()`` decorators).
 * ``"deferred-full"`` — loads every public function with the core set
-  enabled and 30 raw implementation tools marked ``defer=True``.
+  enabled and 32 raw implementation tools marked ``defer=True``.
   Includes ``discover_tools`` (BM25 search) so LLMs find deferred
   tools by intent.
 
@@ -592,9 +592,9 @@ def build_registry(
     """Build a ``ToolRegistry`` for the chosen profile.
 
     Args:
-        profile: ``"core"`` for the small default surface (~27 tools),
+        profile: ``"core"`` for the small default surface (~31 tools),
             ``"deferred-full"`` for the complete pool (core visible,
-            30 raw tools deferred, ``discover_tools`` added).
+            32 raw tools deferred, ``discover_tools`` added).
         registry_name: Identifier for server titles and labels.
 
     Returns:

{uxarray_mcp-0.1.2 → uxarray_mcp-0.1.3}/src/uxarray_mcp/remote/agent.py

@@ -424,15 +424,47 @@ class UXarrayComputeAgent(_AcademyAgent):
 
         # Attach provenance with the correct HPC venue — the remote functions
         # are self contained and don't call attach_provenance themselves.
-        from uxarray_mcp.provenance import attach_provenance
+        from uxarray_mcp.provenance import _get_uxarray_version, attach_provenance
 
         endpoint_label = self.config.endpoint_name or "configured"
-        return attach_provenance(
+
+        # Capture the worker's true software versions (when the remote function
+        # reports them) so provenance reflects what actually computed the result
+        # — not the local submitter — and warn on local/remote version drift.
+        drift_warnings: list[str] = []
+        worker_uxarray = None
+        if isinstance(result, dict):
+            worker_uxarray = result.pop("_worker_uxarray_version", None)
+            result.pop("_worker_python_version", None)
+        local_uxarray = _get_uxarray_version()
+        if (
+            worker_uxarray
+            and local_uxarray != "unknown"
+            and worker_uxarray != local_uxarray
+        ):
+            drift_warnings.append(
+                f"UXarray version drift: local={local_uxarray}, "
+                f"remote(worker)={worker_uxarray}. Numerical results may differ "
+                "between local and remote runs; compare with care."
+            )
+
+        # Fold any warnings the remote function itself produced (e.g. vector
+        # component guardrails) into provenance.
+        if isinstance(result, dict):
+            fn_warnings = result.get("component_warnings") or []
+            drift_warnings.extend(fn_warnings)
+
+        annotated = attach_provenance(
             result,
             tool=func.__name__,
             inputs={"args": [str(a) for a in args]},
             venue=f"hpc:{endpoint_label}",
+            warnings=drift_warnings or None,
         )
+        # Record the worker's uxarray version explicitly alongside the local one.
+        if worker_uxarray:
+            annotated["_provenance"]["remote_uxarray_version"] = worker_uxarray
+        return annotated
 
     def _run_local_inspect_mesh(self, file_path: str) -> Dict[str, Any]:
         """Execute inspect_mesh locally as fallback."""