[FSSDK-12760] Clarify holdout scope docs (spec §5 cleanup)

Update stale docstrings/comments that described holdout scope as being
determined by the includedRules field. After FSSDK-12760, scope is
determined by which top-level datafile section the entity is parsed
from ('holdouts' = global, 'localHoldouts' = local). The entity-level
is_global property continues to compute from included_rules for code
holding direct entity references.

No behavior change.

Author: jaeopt

optimizely/entities.py

@@ -233,7 +233,11 @@ def __init__(
         self.trafficAllocation = trafficAllocation
         self.audienceIds = audienceIds
         self.audienceConditions = audienceConditions
-        # None = global holdout (applies to all rules); list of rule IDs = local holdout
+        # Per-rule targeting list for local holdouts. Scope is NOT determined by this
+        # field — it is determined by which datafile section the entity was parsed
+        # from ('holdouts' = global, 'localHoldouts' = local). ProjectConfig strips
+        # this field on entries parsed from the 'holdouts' section so that entities
+        # built from that section always satisfy is_global. See FSSDK-12760.
         self.included_rules: Optional[list[str]] = includedRules
 
     def get_audience_conditions_or_ids(self) -> Sequence[str | list[str]]:
@@ -248,8 +252,17 @@ def get_audience_conditions_or_ids(self) -> Sequence[str | list[str]]:
     def is_global(self) -> bool:
         """Check if this is a global holdout (applies to all rules across all flags).
 
-        A holdout is global when includedRules is None (absent from datafile).
-        An empty list [] is a local holdout that targets no rules (different from global).
+        Authoritative scope is the datafile section the entity came from:
+        the top-level 'holdouts' section is global, 'localHoldouts' is local.
+        ProjectConfig enforces this by stripping 'includedRules' from entries
+        parsed out of the 'holdouts' section before constructing the entity,
+        so for entities built via ProjectConfig this property is consistent
+        with section membership.
+
+        At the entity level the property is still computed from
+        ``included_rules`` for code holding entity references directly:
+        None → global, [] or non-empty list → local. An empty list is a
+        local holdout that targets no rules (distinct from None/global).
 
         Returns:
             True if included_rules is None (global), False otherwise (local).

optimizely/helpers/types.py

@@ -130,4 +130,9 @@ class HoldoutDict(ExperimentDict):
     Extends ExperimentDict with holdout-specific properties.
     """
     holdoutStatus: HoldoutStatus
-    includedRules: Optional[list[str]]  # None = global holdout; list of rule IDs = local holdout
+    # Per-rule targeting list for local holdouts. Holdout scope is determined by which
+    # top-level datafile section the entry appears in ('holdouts' vs 'localHoldouts'),
+    # NOT by this field. On 'holdouts'-section entries this field is ignored and
+    # stripped at parse time (see ProjectConfig). On 'localHoldouts'-section entries
+    # the field is required; missing or None is an error and the entry is excluded.
+    includedRules: Optional[list[str]]