refactor: move ConcurrencyConflictError to platform, fix cast style, exit code 3, GUI handler

- Move ConcurrencyConflictError from system/_exceptions to platform/_exceptions
  and re-export from aignostics.platform — eliminates application→system
  bidirectional dependency
- Revert cast() string-form regression in runs.py (restore TC006-compliant
  cast("dict[str, Any]", ...) in all four call sites)
- CLI conflict handlers now exit 3 (distinct from exit 2 for not-found)
- Add specific ConcurrencyConflictError handler in GUI metadata editor
  with "reload and retry" guidance instead of generic error message
- Update all imports and test assertions accordingly

Author: akunft

src/aignostics/application/_cli.py

@@ -1227,7 +1227,7 @@ def run_update_metadata(
     """Update custom metadata for a run."""
     import json  # noqa: PLC0415
 
-    from aignostics.system import ConcurrencyConflictError  # noqa: PLC0415
+    from aignostics.platform import ConcurrencyConflictError  # noqa: PLC0415
 
     logger.trace("Updating custom metadata for run with ID '{}'", run_id)
 
@@ -1252,7 +1252,7 @@ def run_update_metadata(
     except ConcurrencyConflictError as e:
         logger.warning(f"Concurrency conflict updating metadata for run '{run_id}': {e}")
         console.print(f"[warning]Warning:[/warning] Metadata was modified by another process. Re-read and retry: {e}")
-        sys.exit(2)
+        sys.exit(3)
     except ValueError as e:
         logger.warning(f"Run ID '{run_id}' invalid or metadata invalid: {e}")
         console.print(f"[warning]Warning:[/warning] Run ID '{run_id}' invalid or metadata invalid: {e}")
@@ -1284,7 +1284,7 @@ def run_update_item_metadata(
     """Update custom metadata for an item in a run."""
     import json  # noqa: PLC0415
 
-    from aignostics.system import ConcurrencyConflictError  # noqa: PLC0415
+    from aignostics.platform import ConcurrencyConflictError  # noqa: PLC0415
 
     logger.trace("Updating custom metadata for item '{}' in run with ID '{}'", external_id, run_id)
 
@@ -1311,7 +1311,7 @@ def run_update_item_metadata(
     except ConcurrencyConflictError as e:
         logger.warning("Concurrency conflict updating metadata for item '{}' in run '{}': {}", external_id, run_id, e)
         console.print(f"[warning]Warning:[/warning] Metadata was modified by another process. Re-read and retry: {e}")
-        sys.exit(2)
+        sys.exit(3)
     except ValueError as e:
         logger.warning(
             "Run ID '{}' or item external ID '{}' invalid or metadata invalid: {}",

src/aignostics/application/_gui/_page_application_run_describe.py

@@ -19,7 +19,15 @@
 )
 from nicegui import run as nicegui_run
 
-from aignostics.platform import ArtifactOutput, ItemOutput, ItemResult, ItemState, Run, RunState
+from aignostics.platform import (
+    ArtifactOutput,
+    ConcurrencyConflictError,
+    ItemOutput,
+    ItemResult,
+    ItemState,
+    Run,
+    RunState,
+)
 from aignostics.third_party.showinfm.showinfm import show_in_file_manager
 from aignostics.utils import GUILocalFilePicker, get_user_data_directory
 
@@ -747,6 +755,11 @@ async def handle_metadata_change(e: Any) -> None:  # noqa: ANN401
                                 )
                                 ui.notify("Custom metadata updated successfully!", type="positive")
                                 ui.navigate.reload()
+                        except ConcurrencyConflictError:
+                            ui.notify(
+                                "Metadata was modified by another process — reload the page and retry.",
+                                type="warning",
+                            )
                         except Exception as ex:
                             ui.notify(f"Failed to update custom metadata: {ex!s}", type="negative")
 

src/aignostics/application/_service.py

@@ -23,6 +23,7 @@
     ApplicationSummary,
     ApplicationVersion,
     Client,
+    ConcurrencyConflictError,
     ForbiddenException,
     InputArtifact,
     InputItem,
@@ -33,7 +34,6 @@
     RunState,
 )
 from aignostics.platform import Service as PlatformService
-from aignostics.system import ConcurrencyConflictError
 from aignostics.utils import BaseService, Health, sanitize_path_component
 from aignostics.wsi import Service as WSIService
 

src/aignostics/platform/__init__.py

@@ -81,6 +81,7 @@
     TOKEN_URL_STAGING,
     TOKEN_URL_TEST,
 )
+from ._exceptions import ConcurrencyConflictError
 from ._messages import AUTHENTICATION_FAILED, NOT_YET_IMPLEMENTED, UNKNOWN_ENDPOINT_URL
 from ._sdk_metadata import (
     PipelineConfig,
@@ -155,6 +156,7 @@
     "Artifact",
     "ArtifactOutput",
     "Client",
+    "ConcurrencyConflictError",
     "Documents",
     "ForbiddenException",
     "InputArtifact",

src/aignostics/platform/_exceptions.py

@@ -0,0 +1,10 @@
+"""Exceptions of platform module."""
+
+
+class ConcurrencyConflictError(ValueError):
+    """Raised when an optimistic concurrency precondition (HTTP 412) fails.
+
+    Subclasses ValueError so existing ``except ValueError`` callers still catch it,
+    while callers that need to distinguish a conflict from a bad-ID error can use
+    ``except ConcurrencyConflictError``.
+    """

src/aignostics/platform/resources/runs.py

@@ -621,7 +621,7 @@ def update_custom_metadata(
         self._api.put_run_custom_metadata_v1_runs_run_id_custom_metadata_put(
             self.run_id,
             custom_metadata_update_request=CustomMetadataUpdateRequest(
-                custom_metadata=cast(dict[str, Any], convert_to_json_serializable(custom_metadata)),  # noqa: TC006
+                custom_metadata=cast("dict[str, Any]", convert_to_json_serializable(custom_metadata)),
                 custom_metadata_checksum=custom_metadata_checksum,
             ),
             _request_timeout=settings().run_submit_timeout,
@@ -660,7 +660,7 @@ def update_item_custom_metadata(
             self.run_id,
             external_id,
             custom_metadata_update_request=CustomMetadataUpdateRequest(
-                custom_metadata=cast(dict[str, Any], convert_to_json_serializable(custom_metadata)),  # noqa: TC006
+                custom_metadata=cast("dict[str, Any]", convert_to_json_serializable(custom_metadata)),
                 custom_metadata_checksum=custom_metadata_checksum,
             ),
             _request_timeout=settings().run_submit_timeout,
@@ -761,7 +761,7 @@ def submit(
         payload = RunCreationRequest(
             application_id=application_id,
             version_number=application_version,
-            custom_metadata=cast(dict[str, Any], convert_to_json_serializable(custom_metadata)),  # noqa: TC006
+            custom_metadata=cast("dict[str, Any]", convert_to_json_serializable(custom_metadata)),
             items=items,
             scheduling=scheduling,
         )
@@ -940,7 +940,7 @@ def _amend_input_items_with_sdk_metadata(items: builtins.list[ItemCreationReques
                     validate_item_sdk_metadata(base_sdk_metadata)
                 item_custom_metadata["sdk"] = base_sdk_metadata
 
-            item.custom_metadata = cast(dict[str, Any], convert_to_json_serializable(item_custom_metadata))  # noqa: TC006
+            item.custom_metadata = cast("dict[str, Any]", convert_to_json_serializable(item_custom_metadata))
 
     def _validate_input_items(self, payload: RunCreationRequest) -> None:
         """Validates the input items in a run creation request.

src/aignostics/system/__init__.py

@@ -1,12 +1,10 @@
 """System module."""
 
 from ._cli import cli
-from ._exceptions import ConcurrencyConflictError
 from ._service import Service
 from ._settings import Settings
 
 __all__ = [
-    "ConcurrencyConflictError",
     "Service",
     "Settings",
     "cli",

src/aignostics/system/_exceptions.py

@@ -7,12 +7,3 @@ class OpenAPISchemaError(ValueError):
     def __init__(self, error: Exception) -> None:
         """Initialize exception with the underlying error."""
         super().__init__(f"Failed to load OpenAPI schema: {error}")
-
-
-class ConcurrencyConflictError(ValueError):
-    """Raised when an optimistic concurrency precondition (HTTP 412) fails.
-
-    Subclasses ValueError so existing ``except ValueError`` callers still catch it,
-    while callers that need to distinguish a conflict from a bad-ID error can use
-    ``except ConcurrencyConflictError``.
-    """

tests/aignostics/application/cli_test.py

@@ -1238,8 +1238,8 @@ def test_cli_run_update_metadata_success_with_checksum(runner: CliRunner) -> Non
 
 @pytest.mark.unit
 def test_cli_run_update_metadata_concurrency_conflict(runner: CliRunner) -> None:
-    """Check run update-metadata exits 2 with a clear message on ConcurrencyConflictError."""
-    from aignostics.system import ConcurrencyConflictError
+    """Check run update-metadata exits 3 with a clear message on ConcurrencyConflictError."""
+    from aignostics.platform import ConcurrencyConflictError
 
     with patch(APPLICATION_CLI_SERVICE_PATCH_TARGET) as mock_service_cls:
         mock_service_cls.return_value.application_run_update_custom_metadata.side_effect = ConcurrencyConflictError(
@@ -1249,7 +1249,7 @@ def test_cli_run_update_metadata_concurrency_conflict(runner: CliRunner) -> None
             cli,
             ["application", "run", "update-metadata", "run-123", _TEST_METADATA_JSON, "--checksum", "old"],
         )
-    assert result.exit_code == 2
+    assert result.exit_code == 3
     assert "modified by another process" in result.output
 
 
@@ -1279,8 +1279,8 @@ def test_cli_run_update_item_metadata_success_with_checksum(runner: CliRunner) -
 
 @pytest.mark.unit
 def test_cli_run_update_item_metadata_concurrency_conflict(runner: CliRunner) -> None:
-    """Check run update-item-metadata exits 2 with a clear message on ConcurrencyConflictError."""
-    from aignostics.system import ConcurrencyConflictError
+    """Check run update-item-metadata exits 3 with a clear message on ConcurrencyConflictError."""
+    from aignostics.platform import ConcurrencyConflictError
 
     with patch(APPLICATION_CLI_SERVICE_PATCH_TARGET) as mock_service_cls:
         mock_service_cls.return_value.application_run_update_item_custom_metadata.side_effect = (
@@ -1299,7 +1299,7 @@ def test_cli_run_update_item_metadata_concurrency_conflict(runner: CliRunner) ->
                 "old",
             ],
         )
-    assert result.exit_code == 2
+    assert result.exit_code == 3
     assert "modified by another process" in result.output
 
 

tests/aignostics/application/service_test.py

@@ -8,8 +8,7 @@
 from typer.testing import CliRunner
 
 from aignostics.application import Service as ApplicationService
-from aignostics.platform import ApiException, NotFoundException, RunData, RunOutput
-from aignostics.system import ConcurrencyConflictError
+from aignostics.platform import ApiException, ConcurrencyConflictError, NotFoundException, RunData, RunOutput
 from tests.constants_test import (
     HETA_APPLICATION_ID,
     HETA_APPLICATION_VERSION,