docs(adr): ADR-0071 — add fan-out/to-one boundary + industry alignment

Bake in the expert refinements: restrict multi-hop to to-one relationships
(lookup/master_detail) so chains never fan out and SUM stays correct with no
symmetric-aggregate machinery; to-many rollups explicitly out of scope. Add a
Prior art section (Salesforce report types, Looker Explores, Power BI/Tableau
relationships, Cube transitive joins; the Looker/Tableau fan-out lesson). Note
dotted paths are self-disambiguating; depth cap is now a perf guard not a
correctness one; matrix column cap is a display ceiling.

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

Author: os-zhuang

docs/adr/0071-dataset-semantic-layer-depth.md

@@ -29,29 +29,61 @@ Two capability gaps remain, both flagged as follow-ups in ADR-0021:
    `columns` dimension into a 2-D grid (ADR-0021 D2 follow-up). A true matrix
    (rows × distinct-column-values × measure cells) isn't rendered.
 
+## Prior art / industry alignment
+
+- **Curated join graph, not arbitrary SQL.** Salesforce *report types* pre-wire
+  a primary object + up to 3 related objects; Looker *Explores* declare the
+  joins a developer blesses; Power BI / Tableau model **relationships** and the
+  engine resolves the path; Cube (this platform's runtime) resolves **transitive
+  joins** from pairwise relationship declarations. All keep joins governed and
+  derived from the object graph — exactly ADR-0021's D-C stance. This ADR stays
+  in that lane (no `ON` clauses).
+- **Spanning depth.** Salesforce report types reach 4 objects (≈3 to-one hops);
+  SOQL allows 5 levels of parent traversal. A small, fixed depth covers the vast
+  majority of real reports.
+- **The fan-out lesson.** Looker (*symmetric aggregates*) and Tableau (*relationships
+  vs. joins*) both exist because joining across a **to-many** edge and then
+  aggregating **double-counts**. The robust answer for a governed, AI-authored,
+  RLS-scoped layer is to **not** traverse to-many in the join chain at all (see
+  Decision A) rather than to build symmetric-aggregate machinery now.
+- **Matrix.** Salesforce matrix reports allow ≤2 row groupings + ≤2 column
+  groupings; Power BI's matrix visual pivots with overflow handling. P1 targets
+  the single-column-grouping MVP with a display-side overflow cap.
+
 ## Decision
 
 ### A. Multi-hop joins (framework: spec + compiler + strategy + RLS)
 
+- **To-one only (the correctness boundary).** Multi-hop traversal is restricted
+  to **to-one** relationships — `lookup` / `master_detail` (child→parent), which
+  is exactly what `include` holds today. To-one chains **never fan out**, so
+  existing `SUM`/`COUNT`/etc. stay correct with **zero** symmetric-aggregate
+  machinery. Traversing a **to-many** (child) relationship inside a dataset's
+  join chain is explicitly **out of scope** (it needs symmetric aggregates /
+  sub-query rollups — a separate feature). Consequently the depth cap below is a
+  **performance/complexity** guard, not a correctness one.
 - **Spec.** `Dataset.include` accepts relationship **paths** — dotted chains of
-  lookup/master_detail field names from the base object (`'account'`,
+  to-one relationship field names from the base object (`'account'`,
   `'account.owner'`). A dimension/measure `field` may reference any field
-  reachable along a **declared** path (`account.owner.region`). A depth cap
-  (default **3 hops**) bounds join count/perf; undeclared paths are still
-  rejected (D-C unchanged — only declared relationships are joinable).
+  reachable along a **declared** path (`account.owner.region`). The dotted path
+  **is** the join alias, so paths are **self-disambiguating** (no named-join
+  disambiguation like Power BI active/inactive or Looker aliased joins). A depth
+  cap (default **3 hops** → 4 objects, Salesforce-report-type parity) bounds join
+  count/perf; undeclared paths are still rejected (D-C unchanged).
 - **Compiler** (`dataset-compiler`). Expand each `include` path into the ordered
   join chain; `cube.joins` is keyed by the full path alias (`account.owner`) and
   carries `{ parentAlias, fkField, targetObject }` so the chain is reconstructable.
 - **Strategy** (`native-sql-strategy.qualifyAndRegisterJoin`). For `a.b.c`,
   register the chain (`base → a` on alias `a`; `a → b` on alias `a.b`) and
-  qualify the column as `"a.b"."c"`. Emit `LEFT JOIN`s in dependency order. Base
-  columns stay qualified with the base table (the fix from objectui#…/framework
-  joined-column work) so shared column names remain unambiguous across all hops.
+  qualify the column as `"a.b"."c"`. Emit `LEFT JOIN`s (outer — base rows
+  without a related record still appear, the report-friendly default) in
+  dependency order. Base columns stay qualified with the base table so shared
+  column names remain unambiguous across all hops.
 - **RLS (D-C, fail-closed).** Apply the tenant read-scope to **every** object in
   the chain, not just the first hop. The strategy already scopes per joined
   alias; generalize the loop to each hop's target object.
 - **UI** (objectui). `useDatasetFieldCatalog` lazily expands a relationship's own
-  relationships (one more level on demand) so the field picker offers
+  **to-one** relationships (one more level on demand) so the field picker offers
   `account.owner.region`; the include editor shows/edits paths; the existing
   `missingRelationship` author-time validation generalizes to paths.
 
@@ -62,16 +94,19 @@ Two capability gaps remain, both flagged as follow-ups in ADR-0021:
 - **Renderer** (`DatasetReportRenderer`). When `type === 'matrix'` and `columns`
   is non-empty, **pivot** the flat result into a 2-D grid: distinct `columns`
   values become column headers, `rows` go down the side, measure(s) fill the
-  cells. Cap distinct column values (default **50**) with a "+N more — refine
-  with a filter" notice to avoid column explosion.
+  cells. Cap distinct column values at a **display** ceiling (default **50**,
+  with a "+N more — refine with a filter" notice) — a render-side guard, not a
+  query limit. MVP = a single column grouping; ≤2 row/col groupings (Salesforce
+  parity) is a fast-follow.
 - **Spec unchanged** (`rows` / `columns` already exist on `Report`).
 
 ## Consequences
 
-- New capability: analytics two-plus relationships deep, and true matrix reports.
+- New capability: analytics two-plus to-one hops deep, and true matrix reports.
 - Cost/risk: multi-hop joins multiply `LEFT JOIN`s (perf) and widen the RLS
   surface (each hop scoped) — bounded by the depth cap + declared-path allowlist.
-  Matrix column cardinality is bounded by the column cap.
+  No fan-out risk by construction (to-one only). Matrix column cardinality is
+  bounded by the display cap.
 - **Backward compatible.** Single-hop `include` and flat rows keep working
   unchanged; the depth cap and "flat unless `matrix` + `columns`" defaults
   preserve current behaviour.
@@ -81,18 +116,26 @@ Two capability gaps remain, both flagged as follow-ups in ADR-0021:
 - **P1 — matrix pivot (objectui-only, lowest risk).** Render the matrix grid from
   the existing `rows`/`columns`. No spec/query change. Ships independently.
 - **P2 — multi-hop (framework).** Spec path support + compiler chain + strategy
-  chained joins + per-hop RLS, behind the depth cap. Gated by the ADR-0021
-  reconciliation harness (old-vs-new numbers).
+  chained joins + per-hop RLS, behind the depth cap, **to-one only**. Gated by
+  the ADR-0021 reconciliation harness (old-vs-new numbers).
 - **P3 — objectui catalog/UI.** Multi-hop field picker + include-path editor +
   path-aware author-time validation.
 
 ## Alternatives considered
 
 - **Arbitrary join predicates / raw SQL** — rejected (ADR-0021 D-C: joins are
   derived from the object graph, no `ON` clauses; keeps datasets reviewable and
-  RLS-safe).
+  RLS-safe). Matches Salesforce/Cube/Power BI, not the developer-only Looker
+  `sql_on`.
+- **To-many traversal with symmetric aggregates** — deferred. Correct
+  cross-to-many aggregation (Looker-style symmetric aggregates) is a separate,
+  larger feature; the to-one boundary delivers the common case safely first.
+- **Edge-graph + automatic path resolution** (declare relationship edges, let the
+  engine find the path — Cube/Power BI style) — rejected for v1 in favour of
+  explicit dotted paths: smaller delta, self-disambiguating, and per-path
+  RLS-auditable.
 - **Materialized / precomputed pivots** — out of scope; query-time pivot is
-  sufficient at expected cardinalities (bounded by the column cap).
+  sufficient at expected cardinalities (bounded by the display cap).
 
 ## Related