docs: sharpen distinction between cascade() and restrict()

Lead each description with its purpose rather than using parallel
structure. cascade() prepares a delete (one-shot, trims graph, OR).
restrict() selects a data subset (chainable, preserves graph, AND).

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

Author: dimitri-yatsenko

src/explanation/whats-new-22.md

@@ -234,15 +234,13 @@ This is valuable when working with unfamiliar pipelines, large datasets, or mult
 
 ### Two Propagation Modes
 
-The diagram supports two restriction propagation modes with different convergence semantics:
+The diagram supports two restriction propagation modes designed for fundamentally different tasks.
 
-**`cascade()` uses OR at convergence.** When a child table has multiple restricted ancestors, the child row is affected if *any* parent path reaches it. This is the right semantics for delete — if any reason exists to remove a row, it should be removed. `cascade()` is one-shot: it can only be called once on an unrestricted diagram.
+**`cascade()` prepares a delete.** It takes a single restricted table expression, propagates the restriction downstream through all descendants, and **trims the diagram** to the resulting subgraph — ancestors and unrelated tables are removed entirely. Convergence uses OR: a descendant row is marked for deletion if *any* ancestor path reaches it, because if any reason exists to remove a row, it should be removed. `cascade()` is one-shot and is always followed by `preview()` or `delete()`.
 
-**`restrict()` uses AND at convergence.** A child row is included only if *all* restricted ancestors match. This is the right semantics for data subsetting and export — only rows satisfying every condition are selected. `restrict()` is chainable: call it multiple times to build up conditions from different tables.
+**`restrict()` selects a data subset.** It propagates a restriction downstream but **preserves the full diagram**, allowing `restrict()` to be called again from a different seed table. This makes it possible to build up multi-condition subsets incrementally — for example, restricting by species from one table and by date from another. Convergence uses AND: a descendant row is included only if *all* restricted ancestors match, because an export should contain only rows satisfying every condition. After chaining restrictions, use `prune()` to remove empty tables and `preview()` to inspect the result.
 
-Both modes propagate **downstream only** — from the seed table to its descendants. `cascade()` goes further: it trims the returned Diagram to the cascade subgraph, removing all ancestors and unrelated tables. This means `delete()` operates on the entire trimmed diagram with no additional filtering. `restrict()` keeps the full graph intact (to support chaining from multiple seed tables) but only restricts the seed's descendants. This matches the semantics of foreign key cascades: deleting a session deletes its trials, not its subject.
-
-The two modes are mutually exclusive on the same diagram. This prevents accidental mixing of incompatible semantics.
+The two modes are mutually exclusive on the same diagram. This prevents accidental mixing of incompatible semantics — a delete diagram should never be reused for subsetting, and vice versa.
 
 ### Pruning Empty Tables
 

src/reference/specs/diagram.md

@@ -130,7 +130,7 @@ Diagrams can propagate restrictions through the dependency graph and execute dat
 diag.cascade(table_expr, part_integrity="enforce")
 ```
 
-Apply a cascade restriction and propagate it downstream through the dependency graph. The returned Diagram is trimmed to the **cascade subgraph** — only the seed table and its descendants remain. All ancestors and unrelated tables are removed. Uses **OR** semantics at convergence — a child row is affected if *any* restricted ancestor reaches it. Designed for delete operations.
+Prepare a cascading delete. Starting from a restricted table expression, propagate the restriction downstream through all descendants using **OR** semantics — a descendant row is marked for deletion if *any* ancestor path reaches it. The returned Diagram is **trimmed** to the cascade subgraph: only the seed table and its descendants remain; all ancestors and unrelated tables are removed. The trimmed diagram is ready for `preview()` and `delete()`.
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
@@ -141,8 +141,8 @@ Apply a cascade restriction and propagate it downstream through the dependency g
 
 **Constraints:**
 
-- `cascade()` can only be called **once** on an unrestricted Diagram
-- Cannot be mixed with `restrict()` — the two modes are mutually exclusive
+- **One-shot** — can only be called once on an unrestricted Diagram
+- Mutually exclusive with `restrict()`
 - `table_expr.full_table_name` must be a node in the diagram
 
 **`part_integrity` values:**
@@ -165,19 +165,19 @@ restricted = diag.cascade(Session & {'subject_id': 'M001'})
 diag.restrict(table_expr)
 ```
 
-Apply a restrict condition and propagate it downstream. Only the seed table and its descendants receive restrictions — ancestors remain in the diagram but are not restricted. Unlike `cascade()`, the diagram is not trimmed (to support chaining from multiple seed tables). Uses **AND** semantics at convergence — a child row is included only if it satisfies *all* restricted ancestors. Designed for data subsetting and export operations.
+Select a subset of data for export or inspection. Starting from a restricted table expression, propagate the restriction downstream through all descendants using **AND** semantics — a descendant row is included only if *all* restricted ancestors match. The full diagram is preserved (ancestors, unrelated tables) so that `restrict()` can be called again from a different seed table, building up a multi-condition subset incrementally.
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
 | `table_expr` | QueryExpression | — | A restricted table expression |
 
-**Returns:** New `Diagram` with restrict conditions applied.
+**Returns:** New `Diagram` with restrict conditions applied. The graph is not trimmed.
 
 **Constraints:**
 
-- Cannot be called on a cascade-restricted Diagram (mutually exclusive with `cascade()`)
+- **Chainable** — call multiple times to add conditions from different seed tables
+- Mutually exclusive with `cascade()`
 - `table_expr.full_table_name` must be a node in the diagram
-- **Can be chained** — call `restrict()` multiple times to add conditions from different tables
 
 ```python
 # Chain multiple restrictions (AND semantics)