feat: add optimistic concurrency guards for draft editor, pricing and publish flows

add optimistic concurrency guards via expected scheme version id

protect draft editor, pricing snapshot, remap and publish flows from stale mutations
protect version creation from stale current version state

keep backward compatibility with optional query guards

verify 409 conflict behavior for stale clients and 200 for valid flows

backend/app/services/draft_guard.py

@@ -4,7 +4,30 @@ from app.repositories.scheme_versions import get_current_scheme_version
 from app.repositories.schemes import get_scheme_record_by_scheme_id
 
 
-async def get_current_draft_context(scheme_id: str):
+def ensure_expected_scheme_version_id(
+    *,
+    actual_scheme_version_id: str,
+    expected_scheme_version_id: str | None,
+) -> None:
+    if expected_scheme_version_id is None:
+        return
+
+    if expected_scheme_version_id != actual_scheme_version_id:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail={
+                "code": "stale_draft_version",
+                "message": "Draft scheme version is stale. Reload current draft state before applying mutation.",
+                "expected_scheme_version_id": expected_scheme_version_id,
+                "actual_scheme_version_id": actual_scheme_version_id,
+            },
+        )
+
+
+async def get_current_draft_context(
+    scheme_id: str,
+    expected_scheme_version_id: str | None = None,
+):
     scheme = await get_scheme_record_by_scheme_id(scheme_id)
     version = await get_current_scheme_version(
         scheme_id=scheme.scheme_id,
@@ -17,4 +40,9 @@ async def get_current_draft_context(scheme_id: str):
             detail="Current scheme version is not editable because it is not in draft state",
         )
 
+    ensure_expected_scheme_version_id(
+        actual_scheme_version_id=version.scheme_version_id,
+        expected_scheme_version_id=expected_scheme_version_id,
+    )
+
     return scheme, version