Document allow_invalid_primary_key as public parameter

Make allow_invalid_primary_key a public parameter for join() so users
can bypass the left join A → B constraint when they take responsibility
for handling the potentially invalid primary key.

This is useful when subsequent operations (like GROUP BY) will reset
the primary key. Aggregation uses this internally for keep_all_rows=True.

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

Author: claude

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

@@ -341,6 +341,22 @@ The following attributes from the right operand's primary key are not determined
 the left operand: ['z']. Use an inner join or restructure the query.
 ```
 
+### Bypassing the Left Join Constraint
+
+For special cases where the user takes responsibility for handling the potentially invalid primary key, the constraint can be bypassed using `allow_invalid_primary_key=True`:
+
+```python
+# Normally blocked - B does not determine A
+A.join(B, left=True)  # Error: A → B not satisfied
+
+# Bypass the constraint - user takes responsibility
+A.join(B, left=True, allow_invalid_primary_key=True)  # Allowed, PK = PK(A) ∪ PK(B)
+```
+
+When bypassed, the resulting primary key is the union of both operands' primary keys (PK(A) ∪ PK(B)). The user must ensure that subsequent operations (such as `GROUP BY` or projection) establish a valid primary key.
+
+This mechanism is used internally by aggregation (`aggr`) with `keep_all_rows=True`, which resets the primary key via the `GROUP BY` clause.
+
 ### Aggregation Exception
 
 `A.aggr(B, keep_all_rows=True)` uses a left join internally but has the **opposite requirement**: **B → A** (the group expression B must have all of A's primary key attributes).

src/datajoint/expression.py

@@ -282,7 +282,7 @@ 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, _allow_invalid_primary_key=False):
+    def join(self, other, semantic_check=True, left=False, allow_invalid_primary_key=False):
         """
         Create the joined QueryExpression.
 
@@ -293,12 +293,14 @@ def join(self, other, semantic_check=True, left=False, _allow_invalid_primary_ke
         :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).
+        :param allow_invalid_primary_key: If True, bypass the left join A → B constraint.
+            The resulting PK will be PK(A) ∪ PK(B), which may contain NULLs for unmatched rows.
+            Use when you will reset the PK afterward (e.g., via GROUP BY in aggregation).
 
         Examples:
             a * b  is short for a.join(b)
             a.join(b, semantic_check=False)  for permissive joins
+            a.join(b, left=True, allow_invalid_primary_key=True)  for left join with invalid PK
         """
         # U joins are deprecated - raise error directing to use & instead
         if isinstance(other, U):
@@ -338,11 +340,11 @@ def join(self, other, semantic_check=True, left=False, _allow_invalid_primary_ke
         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, allow_invalid_primary_key=_allow_invalid_primary_key)
+        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, allow_invalid_primary_key=_allow_invalid_primary_key
+            other.original_heading, left=left, allow_invalid_primary_key=allow_invalid_primary_key
         )
         assert len(result.support) == len(result._left) + 1
         return result
@@ -688,7 +690,7 @@ 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
         # 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)
+        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