Revert to _allow_invalid_primary_key for left join bypass

The semantic_check parameter should only control homologous namesake
validation, not the left join PK constraint. These are separate concerns:
- semantic_check: validates that namesakes have the same lineage
- _allow_invalid_primary_key: bypasses left join A → B constraint

Aggregation still performs the semantic check but allows invalid
intermediate PKs (which are reset via GROUP BY).

Co-authored-by: dimitri-yatsenko<dimitri@datajoint.com>

Author: claude

docs/src/design/semantic-matching-spec.md

@@ -338,19 +338,7 @@ Session.join(Trial, left=True)  # OK: Session → Trial
 ```
 DataJointError: Left join requires the left operand to determine the right operand (A → B).
 The following attributes from the right operand's primary key are not determined by
-the left operand: ['z']. Use an inner join, restructure the query, or use semantic_check=False.
-```
-
-### Bypassing with `semantic_check=False`
-
-When `semantic_check=False` is used for a left join where A → B doesn't hold, the constraint is bypassed and **PK = PK(A) ∪ PK(B)** is used. This is useful when the caller will reset the primary key afterward (e.g., aggregation with GROUP BY).
-
-```python
-# Direct left join - normally blocked
-A.join(B, left=True)  # Error: A doesn't determine B
-
-# Bypass with semantic_check=False - produces PK(A) ∪ PK(B)
-A.join(B, left=True, semantic_check=False)  # Allowed, but PK may have NULLs
+the left operand: ['z']. Use an inner join or restructure the query.
 ```
 
 ### Aggregation Exception
@@ -361,10 +349,12 @@ This apparent contradiction is resolved by the `GROUP BY` clause:
 
 1. Aggregation requires B → A so that B can be grouped by A's primary key
 2. The intermediate left join `A LEFT JOIN B` would have an invalid PK under the normal left join rules
-3. Aggregation uses `semantic_check=False` for its internal join, producing PK(A) ∪ PK(B)
+3. Aggregation internally allows the invalid PK, producing PK(A) ∪ PK(B)
 4. The `GROUP BY PK(A)` clause then **resets** the primary key to PK(A)
 5. The final result has PK(A), which consists entirely of non-NULL values from A
 
+Note: The semantic check (homologous namesake validation) is still performed for aggregation's internal join. Only the primary key validity constraint is bypassed.
+
 **Example:**
 ```
 Session: session_id*, date
@@ -373,7 +363,7 @@ Trial: session_id*, trial_num*, response_time    (references Session)
 # Aggregation with keep_all_rows=True
 Session.aggr(Trial, keep_all_rows=True, avg_rt='avg(response_time)')
 
-# Internally: Session LEFT JOIN Trial with semantic_check=False
+# Internally: Session LEFT JOIN Trial (with invalid PK allowed)
 # Intermediate PK would be {session_id} ∪ {session_id, trial_num} = {session_id, trial_num}
 # But GROUP BY session_id resets PK to {session_id}
 # Result: All sessions, with avg_rt=NULL for sessions without trials

src/datajoint/expression.py

@@ -282,17 +282,19 @@ def __matmul__(self, other):
             "The @ operator has been removed in DataJoint 2.0. " "Use .join(other, semantic_check=False) for permissive joins."
         )
 
-    def join(self, other, semantic_check=True, left=False):
+    def join(self, other, semantic_check=True, left=False, _allow_invalid_primary_key=False):
         """
         Create the joined QueryExpression.
 
         Uses semantic matching: only attributes with the same name AND the same
         lineage (homologous namesakes) are used for joining.
 
         :param other: QueryExpression to join with
-        :param semantic_check: If True (default), raise error on non-homologous namesakes
-            and enforce left join A → B constraint. If False, bypass these checks.
+        :param semantic_check: If True (default), raise error on non-homologous namesakes.
+            If False, bypass semantic check (use for legacy compatibility).
         :param left: If True, perform a left join retaining all rows from self.
+        :param _allow_invalid_primary_key: Internal flag to allow invalid PK in left joins
+            (used by aggregation where GROUP BY resets the PK afterward).
 
         Examples:
             a * b  is short for a.join(b)
@@ -336,10 +338,12 @@ def join(self, other, semantic_check=True, left=False):
         result._connection = self.connection
         result._support = self.support + other.support
         result._left = self._left + [left] + other._left
-        result._heading = self.heading.join(other.heading, left=left, semantic_check=semantic_check)
+        result._heading = self.heading.join(other.heading, left=left, allow_invalid_primary_key=_allow_invalid_primary_key)
         result._restriction = AndList(self.restriction)
         result._restriction.append(other.restriction)
-        result._original_heading = self.original_heading.join(other.original_heading, left=left, semantic_check=semantic_check)
+        result._original_heading = self.original_heading.join(
+            other.original_heading, left=left, allow_invalid_primary_key=_allow_invalid_primary_key
+        )
         assert len(result.support) == len(result._left) + 1
         return result
 
@@ -683,8 +687,8 @@ def create(cls, arg, group, keep_all_rows=False):
 
         if keep_all_rows and len(group.support) > 1 or group.heading.new_attributes:
             group = group.make_subquery()  # subquery if left joining a join
-        # Use semantic_check=False to bypass left join A → B validation (aggregation resets PK via GROUP BY)
-        join = arg.join(group, semantic_check=False, left=keep_all_rows)
+        # Allow invalid PK for left join (aggregation resets PK via GROUP BY afterward)
+        join = arg.join(group, left=keep_all_rows, _allow_invalid_primary_key=True)
         result = cls()
         result._connection = join.connection
         result._heading = join.heading.set_primary_key(arg.primary_key)  # use left operand's primary key

src/datajoint/heading.py

@@ -468,7 +468,7 @@ def select(self, select_list, rename_map=None, compute_map=None):
         )
         return Heading(chain(copy_attrs, compute_attrs))
 
-    def join(self, other, left=False, semantic_check=True):
+    def join(self, other, left=False, allow_invalid_primary_key=False):
         """
         Join two headings into a new one.
 
@@ -486,16 +486,16 @@ def join(self, other, left=False, semantic_check=True):
         - If B → A or Neither, the PK would include B's attributes, which could be NULL
         - Only when A → B does PK(A) uniquely identify all result rows
 
-        When semantic_check=False for left joins where A → B doesn't hold, the constraint
-        is bypassed and PK = PK(A) ∪ PK(B) is used. This is useful for aggregation, where
-        the GROUP BY clause resets the primary key afterward.
+        When allow_invalid_primary_key=True for left joins where A → B doesn't hold,
+        the constraint is bypassed and PK = PK(A) ∪ PK(B) is used. This is useful for
+        aggregation, where the GROUP BY clause resets the primary key afterward.
 
         It assumes that self and other are headings that share no common dependent attributes.
 
         :param other: The other heading to join with
-        :param left: If True, this is a left join (requires A → B unless semantic_check=False)
-        :param semantic_check: If False, bypass left join A → B validation (PK becomes union)
-        :raises DataJointError: If left=True, semantic_check=True, and A does not determine B
+        :param left: If True, this is a left join (requires A → B unless allow_invalid_primary_key)
+        :param allow_invalid_primary_key: If True, bypass left join A → B validation (PK becomes union)
+        :raises DataJointError: If left=True and A does not determine B (unless allow_invalid_primary_key)
         """
         from .errors import DataJointError
 
@@ -507,9 +507,9 @@ def join(self, other, left=False, semantic_check=True):
             name in other.primary_key or name in other.secondary_attributes for name in self.primary_key
         )
 
-        # For left joins, require A → B unless semantic_check=False
+        # For left joins, require A → B unless allow_invalid_primary_key=True
         if left and not self_determines_other:
-            if semantic_check:
+            if not allow_invalid_primary_key:
                 missing = [
                     name
                     for name in other.primary_key
@@ -519,7 +519,7 @@ def join(self, other, left=False, semantic_check=True):
                     f"Left join requires the left operand to determine the right operand (A → B). "
                     f"The following attributes from the right operand's primary key are not "
                     f"determined by the left operand: {missing}. "
-                    f"Use an inner join, restructure the query, or use semantic_check=False."
+                    f"Use an inner join or restructure the query."
                 )
             else:
                 # Bypass: use union of PKs (will be reset by caller, e.g., aggregation)