docs: add restriction semantics for non-downstream nodes and OR/AND

- Unrestricted nodes are not affected by operations
- Multiple restrict() calls create separate restriction sets
- Delete combines sets with OR (any taint → delete)
- Export combines sets with AND (all criteria → include)
- Within a set, multiple FK paths combine with OR (structural)
- Added open questions on lenient vs strict AND and same-table restrictions

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: dimitri-yatsenko

docs/design/restricted-diagram.md

@@ -57,9 +57,112 @@ rd.delete()
 rd.export('/path/to/backup/')
 ```
 
+### Unrestricted nodes are not affected
+
+A restricted diagram distinguishes between three kinds of nodes:
+
+1. **Directly restricted** — the user applied a restriction to this node
+2. **Indirectly restricted** — a restriction propagated to this node from an ancestor
+3. **Unrestricted** — no restriction reached this node
+
+**Only restricted nodes (direct or indirect) participate in operations.** Unrestricted nodes are left untouched. This is critical for delete: if you restrict `Session & 'subject=1'`, only `Session` and its downstream dependents are affected. Tables in the diagram that are not downstream of `Session` (e.g., `Equipment`, `Lab`) are not deleted.
+
+The restricted diagram's `topo_sort()` for operations should only yield nodes that carry a restriction. Unrestricted nodes are effectively invisible to the operation.
+
+### Multiple restrictions: OR vs AND
+
+When multiple restrictions are applied to different tables in the diagram, downstream nodes may receive restrictions from multiple parents. How these combine depends on the operation.
+
+**Example:** A diagram with `Lab`, `Session → Recording`. `Recording` depends on both `Session` and `Lab`.
+
+```python
+rd = dj.Diagram(schema)
+rd.restrict(Session & 'subject=1')   # R1 propagates to Recording
+rd.restrict(Lab & 'lab="brody"')     # R2 propagates to Recording
+```
+
+Recording now has two propagated restrictions:
+- R1: rows referencing subject=1 sessions
+- R2: rows referencing brody lab
+
+**For delete (OR / union):** A recording should be deleted if it is tainted by *any* restricted parent. Deleting subject 1 means all their recordings go, regardless of which lab. Deleting brody lab means all their recordings go, regardless of subject. The two restrictions combine with OR.
+
+**For export/publish (AND / intersection):** A recording should be exported only if it satisfies *all* criteria. You want specifically brody lab's subject 1 recordings. The two restrictions combine with AND.
+
+**Implementation:** The diagram stores restrictions as separate **restriction sets**, one per `restrict()` call. Each set propagates independently. The combination logic is deferred to the operation:
+
+```python
+class RestrictedDiagram:
+    # Each restrict() call creates a new restriction set.
+    # A restriction set is a dict mapping table_name → list[restriction]
+    # (list = OR within a set, for multiple FK paths from different parents)
+    _restriction_sets: list[dict[str, list]]
+
+    def restrict(self, table_expr):
+        """Add a new restriction set. Propagate downstream."""
+        new_set = {}
+        # ... propagate and populate new_set ...
+        self._restriction_sets.append(new_set)
+        return self
+
+    def _effective_restriction(self, table_name, mode="or"):
+        """
+        Compute the effective restriction for a node.
+
+        mode="or":  union across sets — row included if ANY set restricts it
+                    (for delete: tainted by any restricted parent)
+        mode="and": intersection across sets — row included only if ALL sets restrict it
+                    (for export: must satisfy all criteria)
+        """
+        sets_with_table = [s[table_name] for s in self._restriction_sets
+                           if table_name in s]
+        if not sets_with_table:
+            return None  # unrestricted — not affected
+
+        if mode == "or":
+            # Union: flatten all restriction sets into one OR-list
+            combined = []
+            for restriction_list in sets_with_table:
+                combined.extend(restriction_list)
+            return combined  # list = OR in DataJoint
+
+        elif mode == "and":
+            # Intersection: each set is applied as a separate AND condition
+            # Start with the table, apply each set's restrictions sequentially
+            # Within each set, restrictions are OR (multiple FK paths)
+            # Across sets, restrictions are AND (multiple restrict() calls)
+            return sets_with_table  # caller applies: for s in sets: expr &= s
+
+    def delete(self, ...):
+        """Delete uses OR — any restricted parent taints the row."""
+        for table_name in reversed(self._restricted_topo_sort()):
+            restriction = self._effective_restriction(table_name, mode="or")
+            ...
+
+    def export(self, ...):
+        """Export uses AND — row must satisfy all criteria."""
+        for table_name in self._restricted_topo_sort():
+            restriction = self._effective_restriction(table_name, mode="and")
+            ...
+```
+
+**Why this works:**
+
+Within a single restriction set, multiple restrictions at the same node (from different FK paths) are always OR — a row that references a restricted parent through *any* FK is affected. This is structural and operation-independent.
+
+*Across* restriction sets (separate `restrict()` calls on different tables), the combination depends on the operation. The diagram stores them separately and lets the operation choose.
+
+**Edge case — node restricted in some sets but not others:**
+
+For AND mode (export): if a node is downstream of restriction set R1 but not R2, what happens? The node has restrictions from R1 but none from R2. Two options:
+- **Strict AND**: node is excluded (no data exported) because it doesn't satisfy all criteria
+- **Lenient AND**: only apply AND across sets that actually reach this node
+
+Lenient AND is more useful: `restrict(Session & 'subject=1') & restrict(Stimulus & 'type="visual"')` should export recordings that are from subject 1 AND use visual stimuli, but should also export the `Session` rows for subject 1 even though `Stimulus` restrictions don't propagate up to `Session`. The lenient interpretation applies AND only where multiple restriction sets converge.
+
 ### Restriction propagation
 
-Each node in the `RestrictedDiagram` carries a list of restrictions (combined with OR for multiple FK paths from different parents).
+Each restriction set propagates independently through the graph. Within a set, each node carries a list of restrictions (OR-combined for multiple FK paths).
 
 **Propagation rules for edge `Parent → Child` with `attr_map`:**
 
@@ -70,7 +173,7 @@ Each node in the `RestrictedDiagram` carries a list of restrictions (combined wi
    Restrict child by `parent.proj(**{fk: pk for fk, pk in attr_map.items()})`.
 
 3. **Multiple FK paths to the same child** (via alias nodes):
-   Each path produces a separate restriction. These combine with OR — a child row must be deleted if it references restricted parent rows through *any* FK.
+   Each path produces a separate restriction within the same set. These combine with OR — a child row is affected if it references restricted parent rows through *any* FK.
 
 This reuses the existing restriction logic from the current `cascade()` function (lines 1082–1090 of `table.py`), but applies it upfront during graph traversal rather than reactively from error messages.
 
@@ -198,29 +301,31 @@ def _propagate_restriction(self, parent_name, parent_restriction):
 ### API
 
 ```python
-# From a table with restriction
+# From a table with restriction — single restriction set
 rd = dj.Diagram(Session & 'subject_id=1')
 
-# Explicit restrict call
+# Explicit restrict call — adds a restriction set
 rd = dj.Diagram(schema).restrict(Session & 'subject_id=1')
 
-# Operator syntax (proposed in #865)
+# Operator syntax (proposed in #865) — each & adds a restriction set
 rd = dj.Diagram(schema) & (Session & 'subject_id=1')
 
-# Multiple restrictions
+# Multiple restrictions — two separate restriction sets
+# For delete (OR): delete recordings from subject 1 OR from brody lab
+# For export (AND): export recordings from subject 1 AND from brody lab
 rd = dj.Diagram(schema) & (Session & 'subject_id=1') & (Lab & 'lab="brody"')
 
 # With part_integrity policy
 rd = dj.Diagram(schema) & (PartTable & 'key=1')
 rd.delete(part_integrity="cascade")
 
 # Preview before executing
-rd.preview()   # show affected tables and row counts
+rd.preview()   # show affected tables and row counts per restriction set
 rd.draw()      # visualize with restricted nodes highlighted
 
-# Other operations
-rd.delete()
-rd.export(path)   # future: #864, #560
+# Operations choose combination logic
+rd.delete()              # OR across restriction sets (any taint → delete)
+rd.export(path)          # AND across restriction sets (all criteria → export)
 ```
 
 ## Advantages over current approach
@@ -290,3 +395,9 @@ rd.export(path)   # future: #864, #560
    Eager: propagate all restrictions when `restrict()` is called (computes row counts immediately).
    Lazy: store parent restrictions and propagate during `delete()`/`export()` (defers queries).
    Eager is better for preview but may issue many queries upfront. Lazy is more efficient when the user just wants to delete without preview. Consider lazy propagation with eager option for preview.
+
+5. **Lenient vs strict AND for export:**
+   When using AND mode across restriction sets, a node may be downstream of some restriction sets but not others. Lenient AND (apply intersection only where sets converge) is more practical but harder to reason about. Strict AND (node must be restricted by all sets) is simpler but may be too aggressive. Need to validate with real export use cases.
+
+6. **Restricting the same table in multiple `restrict()` calls:**
+   If the user calls `rd.restrict(Session & 'subject=1')` then `rd.restrict(Session & 'subject=2')`, these become two restriction sets. For delete (OR): deletes subject 1 and subject 2. For export (AND): exports rows that are somehow both subject 1 and 2 (empty set). Should restricting the same table in multiple calls be treated specially — perhaps accumulating within a single set instead?