feat: select governed workflow scope targets

src/govoplan_workflow/backend/router.py

@@ -1,10 +1,19 @@
 from __future__ import annotations
 
-from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi import APIRouter, Depends, HTTPException, Query, status
 from sqlalchemy.orm import Session
 
+from govoplan_core.api.v1.schemas import (
+    ReferenceOptionListResponse,
+    ReferenceOptionResponse,
+)
 from govoplan_core.audit.logging import audit_event
 from govoplan_core.auth import ApiPrincipal, get_api_principal, has_scope
+from govoplan_core.core.references import (
+    access_scope_reference_options,
+    access_scope_reference_provider_available,
+    validate_access_scope_reference,
+)
 from govoplan_core.db.session import get_session
 from govoplan_workflow.backend.governance import (
     definition_decision,
@@ -210,6 +219,42 @@ def api_node_types(
     )
 
 
+@router.get("/scope-targets", response_model=ReferenceOptionListResponse)
+def api_scope_targets(
+    scope_type: str,
+    q: str = "",
+    selected: list[str] = Query(default=[]),
+    limit: int = Query(default=50, ge=1, le=200),
+    principal: ApiPrincipal = Depends(get_api_principal),
+) -> ReferenceOptionListResponse:
+    _require_any_scope(
+        principal,
+        DEFINITION_READ_SCOPE,
+        DEFINITION_WRITE_SCOPE,
+        ADMIN_SCOPE,
+    )
+    registry = get_registry()
+    try:
+        options = access_scope_reference_options(
+            registry,
+            principal,
+            scope_type=scope_type,
+            query=q,
+            selected_values=selected,
+            limit=limit,
+            administrative=has_scope(principal, ADMIN_SCOPE),
+        )
+    except ValueError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
+            detail=str(exc),
+        ) from exc
+    return ReferenceOptionListResponse(
+        options=[ReferenceOptionResponse(**item.to_dict()) for item in options],
+        provider_available=access_scope_reference_provider_available(registry),
+    )
+
+
 @router.post(
     "/definitions/validate",
     response_model=WorkflowGraphValidationResponse,
@@ -296,6 +341,13 @@ def api_create_definition(
         payload = payload.model_copy(
             update={"scope_type": scope_type, "scope_id": scope_id}
         )
+        canonical_scope_id = validate_access_scope_reference(
+            get_registry(),
+            tenant_id=tenant_id or principal.tenant_id,
+            scope_type=scope_type,
+            scope_id=scope_id,
+        )
+        payload = payload.model_copy(update={"scope_id": canonical_scope_id})
         definition = create_definition(
             session,
             tenant_id=tenant_id or principal.tenant_id,
@@ -382,6 +434,26 @@ def api_update_definition(
             registry=get_registry(),
             action="edit",
         )
+        tenant_id, scope_type, scope_id, _scope_key = normalize_definition_scope(
+            principal,
+            scope_type=payload.scope_type,
+            scope_id=payload.scope_id,
+            administrative=has_scope(principal, ADMIN_SCOPE),
+        )
+        scope_id = validate_access_scope_reference(
+            get_registry(),
+            tenant_id=tenant_id or principal.tenant_id,
+            scope_type=scope_type,
+            scope_id=scope_id,
+            preserve_existing=(
+                existing.scope_id
+                if existing.scope_type == scope_type
+                else None
+            ),
+        )
+        payload = payload.model_copy(
+            update={"scope_type": scope_type, "scope_id": scope_id}
+        )
         definition = update_definition(
             session,
             tenant_id=principal.tenant_id,
@@ -389,7 +461,7 @@ def api_update_definition(
             actor_id=_actor_id(principal),
             payload=payload,
         )
-    except PermissionError as exc:
+    except (PermissionError, ValueError) as exc:
         raise _governance_http_error(exc) from exc
     except WorkflowError as exc:
         raise _http_error(exc) from exc
@@ -432,6 +504,13 @@ def api_derive_definition(
         payload = payload.model_copy(
             update={"scope_type": scope_type, "scope_id": scope_id}
         )
+        canonical_scope_id = validate_access_scope_reference(
+            get_registry(),
+            tenant_id=tenant_id or principal.tenant_id,
+            scope_type=scope_type,
+            scope_id=scope_id,
+        )
+        payload = payload.model_copy(update={"scope_id": canonical_scope_id})
         definition = derive_definition(
             session,
             tenant_id=tenant_id or principal.tenant_id,