SEP-1443: Decouple primary-service selection from connectivity-probe enablement (#1131)

## Summary

- Add a per-reference `primary=True` marker to `ServiceRef` so an app
can designate the envelope primary **independently** of
`check_connectivity`. Previously `check_connectivity=True` did double
duty — naming the primary *and* enabling the create-route connectivity
probe — so there was no way to express "multiple services, one
designated primary, no probe".
- `check_connectivity=True` keeps implying primary; probe enablement
(`connectivity_check`) stays keyed off `check_connectivity` alone.
Existing single-marker apps are byte-for-byte unchanged.
- `_validate_connectivity_refs` now accepts 2+ `ServiceRef` fields when
exactly one primary is designated (via either marker) and rejects
conflicting/duplicate designations with a clear `ValueError`. No app
consumes the new marker yet — opt-in, no DB migration, no wire/schema
change.

## Tested

- [x] `pytest tests/app/sep/apps/framework/` → 1590 passed, 234 skipped,
0 failed
- [x] Golden-file / OpenAPI / contract snapshots byte-identical (no
regeneration needed — wire format unchanged)
- [x] `ruff check` + `ruff format --check` clean on all changed files
- New unit tests cover: primary designation without probe, primary beats
last-resolved selection, unfilled-primary → no primary (missing-service
guard), and the four validation rejections (primary+check conflict, two
primaries, primary+multiple, redundant same-field allowed).

## Checklist

- [x] New/modified functions have type hints and rST docstrings
- [x] New tests added for new features or bug fixes
- [x] All tests pass locally (framework suite; full `make test` not
re-run)
- [x] Pre-commit hooks pass (ruff/format verified on changed files)
- [ ] Database migrations generated if models changed (`make
makemigrations`) — N/A, no model/table change
- [ ] User-facing changes documented — N/A, marker is opt-in and unused
by any app
- [ ] Configuration changes documented — N/A
- [x] Changelog fragment added under `changelog.d/`

Author: marcuscruz-percona

app/sep/apps/framework/apps.py

@@ -455,8 +455,9 @@ def connectivity_check(self) -> bool:
         An app probes iff the create capability is enabled and its ``create_model``
         declares a ``check_connectivity=True`` ``ServiceRef`` (top-level or nested
         in a one-of branch); that marked service is also the envelope's primary.
-        Replaces the former app-level flag, so a single per-reference marker drives
-        both the probe and the connectivity-service selection.
+        Probe enablement is keyed off ``check_connectivity`` alone — a ``ServiceRef``
+        marked ``primary=True`` designates the envelope primary without probing, so it
+        does not turn this on.
 
         :return: ``True`` when the app derives a probing create route.
         """
@@ -538,57 +539,58 @@ def _validate_related_apps(self) -> None:
             )
 
     def _validate_connectivity_refs(self) -> None:
-        """Reject an ambiguous or unselectable connectivity-service configuration.
-
-        A model-first app probes the ``check_connectivity=True`` ``ServiceRef`` and
-        makes it the envelope's primary. At most one service may be marked — a
-        second would make the probe target ambiguous — and a model declaring two or
-        more ``ServiceRef`` fields with none marked has no determinable primary. A
-        single unmarked ``ServiceRef`` is valid: it is the sole primary and the app
-        does not probe. The two-or-more-unmarked rejection is about primary
-        disambiguation, not the probe: ``assemble_envelope`` unconditionally stamps
-        the primary service onto every task's connectivity host/port and
+        """Reject an ambiguous or unselectable primary-service configuration.
+
+        A model-first app names its envelope primary with a *designated* marker —
+        ``check_connectivity=True`` (which also probes) or ``primary=True`` (which
+        designates without probing). At most one ``ServiceRef`` may be designated
+        across both markers; a second designation makes the primary ambiguous. A
+        model declaring two or more ``ServiceRef`` fields with none designated has
+        no determinable primary. A single unmarked ``ServiceRef`` is valid: it is
+        the sole primary and the app does not probe. The disambiguation is about the
+        primary, not the probe: ``assemble_envelope`` unconditionally stamps the
+        primary service onto every task's connectivity host/port and
         ``service_name``, so the primary must be unambiguous even when no probe runs.
 
-        :raises ValueError: When a ``check_connectivity`` ``ServiceRef`` is also
-            marked ``multiple`` (a multi-value field has no single primary), when a
-            ``multiple=True`` ``ServiceRef`` would be the connectivity primary (no
-            scalar ``check_connectivity`` ref is marked to take its place), when
-            more than one ``ServiceRef`` is marked ``check_connectivity``, or when
-            two or more ``ServiceRef`` fields leave no determinable connectivity
-            primary.
+        :raises ValueError: When a designated ``ServiceRef`` is also marked
+            ``multiple`` (a multi-value field has no single primary), when a
+            ``multiple=True`` ``ServiceRef`` would be the primary with no scalar
+            designated ref to take its place, when more than one ``ServiceRef`` is
+            designated primary (via ``check_connectivity`` and/or ``primary``), or
+            when two or more ``ServiceRef`` fields leave no determinable primary.
         """
         if self.create_model is None:
             return
         refs = list(iter_service_refs(self.create_model))
-        marked = [ref for ref in refs if ref.check_connectivity]
-        if any(ref.multiple for ref in marked):
+        designated = [ref for ref in refs if ref.check_connectivity or ref.primary]
+        if any(ref.multiple for ref in designated):
             raise ValueError(
                 "TaskExecutionApp: a create_model declares a multiple=True ServiceRef "
-                "marked check_connectivity=True; the connectivity probe targets a "
-                "single primary service and cannot select one from a multi-value "
-                "field — set multiple=False or check_connectivity=False"
+                "designated primary (check_connectivity=True or primary=True); the "
+                "envelope primary is a single service and cannot be selected from a "
+                "multi-value field — set multiple=False, or drop the primary marker"
             )
-        if not marked and any(ref.multiple for ref in refs):
+        if not designated and any(ref.multiple for ref in refs):
             raise ValueError(
                 "TaskExecutionApp: a create_model declares a multiple=True ServiceRef "
-                "with no check_connectivity=True ServiceRef to serve as the "
-                "connectivity primary; a multi-value service field cannot resolve to "
-                "the single primary assemble_envelope stamps onto every task — mark a "
-                "scalar ServiceRef check_connectivity=True"
+                "with no designated primary ServiceRef to serve as the envelope "
+                "primary; a multi-value service field cannot resolve to the single "
+                "primary assemble_envelope stamps onto every task — mark a scalar "
+                "ServiceRef check_connectivity=True or primary=True"
             )
-        if len(marked) > 1:
+        if len(designated) > 1:
             raise ValueError(
-                "TaskExecutionApp: a create_model declares "
-                f"{len(marked)} check_connectivity=True ServiceRef fields; at most "
-                "one service is the connectivity primary — mark exactly one"
+                "TaskExecutionApp: a create_model designates "
+                f"{len(designated)} primary ServiceRef fields via check_connectivity "
+                "and/or primary; at most one service is the envelope primary — "
+                "designate exactly one"
             )
-        if not marked and len(refs) > 1:
+        if not designated and len(refs) > 1:
             raise ValueError(
                 "TaskExecutionApp: a create_model declares "
-                f"{len(refs)} ServiceRef fields with none marked "
-                "check_connectivity=True; no connectivity primary is determinable — "
-                "mark exactly one"
+                f"{len(refs)} ServiceRef fields with none designated primary "
+                "(check_connectivity=True or primary=True); no envelope primary "
+                "is determinable — designate exactly one"
             )
 
     def _validate_schema_source(self) -> None:

app/sep/apps/framework/form_dsl/markers.py

@@ -230,9 +230,17 @@ class ServiceRef:
         post-creation connectivity probe against this service, and the service is
         selected as the envelope's primary (``_service_name``, the connectivity
         meta, and the executor-target fallback) even when a second ``ServiceRef``
-        resolves. A model declares at most one ``check_connectivity`` service;
-        when none is marked the sole ``ServiceRef`` is the primary and no probe
-        runs. Defaults to ``False``.
+        resolves. ``check_connectivity`` therefore implies ``primary``. When none
+        is marked the sole ``ServiceRef`` is the primary and no probe runs.
+        Defaults to ``False``.
+    :param primary: When ``True``, the service is the envelope's primary
+        (``_service_name``, the connectivity meta, and the executor-target
+        fallback) *without* enabling the probe — the way to name a primary among
+        several ``ServiceRef`` fields when no connectivity check is wanted. A model
+        designates at most one primary across both markers: at most one
+        ``ServiceRef`` may be marked ``check_connectivity`` **or** ``primary`` (a
+        single field carrying both is redundant, since ``check_connectivity``
+        already implies primary). Defaults to ``False``.
     :param multiple: When ``True``, the field is a multi-value selector backed by
         a ``list[...]`` / ``set[...]`` annotation and derives a
         ``MultiServiceField``. Defaults to ``False`` (single-value).
@@ -241,6 +249,7 @@ class ServiceRef:
     service_types: tuple[ServiceTypeEnum, ...]
     allow_custom: bool = False
     check_connectivity: bool = False
+    primary: bool = False
     multiple: bool = False
 
     def __post_init__(self) -> None:

app/sep/apps/framework/spec.py

@@ -288,18 +288,18 @@ def _select_primary_service(
 ) -> CreatedService | None:
     """Select the primary (connectivity) service from the resolved service refs.
 
-    A ``check_connectivity``-marked ref wins outright (the construction guard
-    permits at most one). Otherwise fall back to the last ref that resolved to a
-    real entity, preserving the pre-marker last-wins behaviour for the
-    single-service apps that declare no marker.
+    A designated primary — a ref marked ``check_connectivity`` or ``primary`` —
+    wins outright (the construction guard permits at most one). Otherwise fall
+    back to the last ref that resolved to a real entity, preserving the pre-marker
+    last-wins behaviour for the single-service apps that declare no marker.
 
     :param candidates: The ``(marker, resolved entity)`` pairs for every resolved
         ``ServiceRef`` field, in declaration order.
     :return: The primary service, or ``None`` when none resolved.
     """
     primary = None
     for ref, entity in candidates:
-        if ref.check_connectivity:
+        if ref.check_connectivity or ref.primary:
             return entity
         if entity is not None:
             primary = entity
@@ -319,9 +319,9 @@ async def resolve_refs(
     spec builder can fall back to the raw form value. A ``HostRef`` field's
     submitted value (free-typed or selected) is captured as the executor host
     without an inventory call, coerced to ``str``; a model declaring more than one
-    ``HostRef`` is rejected. The connectivity / primary service is the
-    ``check_connectivity``-marked ``ServiceRef`` when present, else the sole
-    resolved ``ServiceRef``.
+    ``HostRef`` is rejected. The primary service is the designated ``ServiceRef``
+    (marked ``check_connectivity`` or ``primary``) when present, else the sole /
+    last-resolved ``ServiceRef``.
 
     :param form: The validated create form instance.
     :param inventory_api: The inventory API client.

tests/app/sep/apps/framework/test_apps.py

@@ -181,6 +181,90 @@ class _SoleMultiServiceForm(AppFormModel):
     ]
 
 
+class _PrimaryDesignatedServiceForm(AppFormModel):
+    """Represent two services, one designated ``primary`` without a probe.
+
+    The primary is declared *before* an unmarked destination so the old
+    two-or-more-unmarked rejection no longer fires and the designation, not
+    last-wins, names the primary.
+    """
+
+    task_name: Annotated[str, Ui(label="Name", section="main")] = ""
+    service_a: Annotated[
+        int | None,
+        ServiceRef(service_types=(ServiceTypeEnum.MYSQL,), primary=True),
+        Ui(label="A", section="main"),
+    ] = None
+    service_b: Annotated[
+        int | None,
+        ServiceRef(service_types=(ServiceTypeEnum.MYSQL,)),
+        Ui(label="B", section="main"),
+    ] = None
+
+
+class _PrimaryAndCheckConflictForm(AppFormModel):
+    """Represent a ``primary`` field conflicting with a ``check_connectivity`` field."""
+
+    task_name: Annotated[str, Ui(label="Name", section="main")] = ""
+    service_a: Annotated[
+        int | None,
+        ServiceRef(service_types=(ServiceTypeEnum.MYSQL,), primary=True),
+        Ui(label="A", section="main"),
+    ] = None
+    service_b: Annotated[
+        int | None,
+        ServiceRef(service_types=(ServiceTypeEnum.MYSQL,), check_connectivity=True),
+        Ui(label="B", section="main"),
+    ] = None
+
+
+class _TwoPrimaryServiceForm(AppFormModel):
+    """Represent a create form designating two ``primary`` services."""
+
+    task_name: Annotated[str, Ui(label="Name", section="main")] = ""
+    service_a: Annotated[
+        int | None,
+        ServiceRef(service_types=(ServiceTypeEnum.MYSQL,), primary=True),
+        Ui(label="A", section="main"),
+    ] = None
+    service_b: Annotated[
+        int | None,
+        ServiceRef(service_types=(ServiceTypeEnum.MYSQL,), primary=True),
+        Ui(label="B", section="main"),
+    ] = None
+
+
+class _PrimaryMultipleForm(AppFormModel):
+    """Represent a multi-value ``ServiceRef`` designated ``primary``."""
+
+    task_name: Annotated[str, Ui(label="Name", section="main")] = ""
+    services: Annotated[
+        list[int],
+        ServiceRef(service_types=(ServiceTypeEnum.MYSQL,), multiple=True, primary=True),
+        Ui(label="Services", section="main"),
+    ]
+
+
+class _RedundantPrimaryProbeForm(AppFormModel):
+    """Represent a single field carrying both ``primary`` and ``check_connectivity``."""
+
+    task_name: Annotated[str, Ui(label="Name", section="main")] = ""
+    service_a: Annotated[
+        int | None,
+        ServiceRef(
+            service_types=(ServiceTypeEnum.MYSQL,),
+            check_connectivity=True,
+            primary=True,
+        ),
+        Ui(label="A", section="main"),
+    ] = None
+    service_b: Annotated[
+        int | None,
+        ServiceRef(service_types=(ServiceTypeEnum.MYSQL,)),
+        Ui(label="B", section="main"),
+    ] = None
+
+
 class _BadArgFormatForm(AppFormModel):
     """Represent a create form whose ``ArgFormat`` template misspells the placeholder."""
 
@@ -870,6 +954,39 @@ def test_marked_service_enables_probe(self) -> None:
         """Derive ``connectivity_check`` from a ``check_connectivity`` service."""
         assert _synth_app(connectivity_check=True).connectivity_check is True
 
+    def test_primary_marker_designates_without_probe(self) -> None:
+        """Accept two services with one ``primary`` designation and no probe."""
+        assert (
+            _synth_app(create_model=_PrimaryDesignatedServiceForm).connectivity_check
+            is False
+        )
+
+    def test_primary_and_check_connectivity_conflict_raises(self) -> None:
+        """Reject a ``primary`` field conflicting with a ``check_connectivity`` field."""
+        with pytest.raises(
+            ValueError, match="at most one service is the envelope primary"
+        ):
+            _synth_app(create_model=_PrimaryAndCheckConflictForm)
+
+    def test_two_primary_designations_raise(self) -> None:
+        """Reject a create_model designating more than one ``primary`` service."""
+        with pytest.raises(
+            ValueError, match="at most one service is the envelope primary"
+        ):
+            _synth_app(create_model=_TwoPrimaryServiceForm)
+
+    def test_primary_with_multiple_raises(self) -> None:
+        """Reject a multiple=True ServiceRef designated the primary."""
+        with pytest.raises(ValueError, match="multiple=True"):
+            _synth_app(create_model=_PrimaryMultipleForm)
+
+    def test_redundant_primary_and_probe_same_field_allowed(self) -> None:
+        """Accept one field marked both ``primary`` and ``check_connectivity``, probing."""
+        assert (
+            _synth_app(create_model=_RedundantPrimaryProbeForm).connectivity_check
+            is True
+        )
+
     def test_list_suppress_without_custom_list_raises(self) -> None:
         """Assert ``list=False`` with no custom ``GET /`` in extra_routes is rejected."""
         with pytest.raises(ValueError, match="capabilities.list"):

tests/app/sep/apps/framework/test_spec.py

@@ -411,6 +411,27 @@ class _SoleUnmarkedServiceForm(AppFormModel):
     ] = None
 
 
+class _PrimaryDesignatedServiceForm(AppFormModel):
+    """Carry a ``primary`` source and an unmarked destination ``ServiceRef``.
+
+    The destination is declared *after* the source so the old last-wins
+    selection would pick it; the ``primary`` marker must instead keep the source
+    as ``resolved.service`` without enabling any probe.
+    """
+
+    task_name: Annotated[str, Ui(label="Name", section="main")] = ""
+    source_id: Annotated[
+        int | None,
+        ServiceRef(service_types=(ServiceTypeEnum.MYSQL,), primary=True),
+        Ui(label="Source", section="main"),
+    ] = None
+    dest_id: Annotated[
+        int | None,
+        ServiceRef(service_types=(ServiceTypeEnum.MYSQL,)),
+        Ui(label="Dest", section="main"),
+    ] = None
+
+
 class _SourceByTable(BaseModel):
     """Carry a discriminated-union branch nesting a free-solo ``SchemaRef``."""
 
@@ -598,6 +619,59 @@ async def test_check_connectivity_service_is_primary(self) -> None:
         assert resolved.entities["source_id"].name == "source"
         assert resolved.entities["dest_id"].name == "dest"
 
+    @pytest.mark.asyncio
+    async def test_primary_marked_service_is_primary_without_probe(self) -> None:
+        """Select the ``primary`` service as primary, not the last-resolved ref."""
+        source = _service(
+            address="src-host",
+            service_type=ServiceTypeEnum.MYSQL,
+            name="source",
+            port=3306,
+        )
+        dest = _service(
+            address="dst-host",
+            service_type=ServiceTypeEnum.MYSQL,
+            name="dest",
+            port=3306,
+        )
+        inventory = _fake_inventory(
+            {
+                "/services/1": source.model_dump(mode="json"),
+                "/services/2": dest.model_dump(mode="json"),
+            }
+        )
+
+        resolved = await resolve_refs(
+            _PrimaryDesignatedServiceForm(source_id=1, dest_id=2), inventory
+        )
+
+        assert resolved.service is not None
+        assert resolved.service.name == "source"
+        assert resolved.entities["dest_id"].name == "dest"
+
+    @pytest.mark.asyncio
+    async def test_unfilled_primary_designation_yields_no_primary(self) -> None:
+        """Return no primary when the designated ``primary`` ref is left unfilled.
+
+        The designated ref wins outright even when it resolves to ``None``, so a
+        later resolved ``ServiceRef`` does not step in as the primary — leaving
+        ``assemble_envelope`` to trip its missing-service guard.
+        """
+        dest = _service(
+            address="dst-host",
+            service_type=ServiceTypeEnum.MYSQL,
+            name="dest",
+            port=3306,
+        )
+        inventory = _fake_inventory({"/services/2": dest.model_dump(mode="json")})
+
+        resolved = await resolve_refs(
+            _PrimaryDesignatedServiceForm(source_id=None, dest_id=2), inventory
+        )
+
+        assert resolved.service is None
+        assert resolved.entities["dest_id"].name == "dest"
+
     @pytest.mark.asyncio
     async def test_sole_service_ref_is_primary_when_none_marked(self) -> None:
         """Select the sole ``ServiceRef`` as primary when none is marked."""