@opensaas/stack-core 0.36.0 → 0.38.0

package/src/access/declared-dependencies.test.ts

@@ -0,0 +1,277 @@
+import { describe, it, expect } from 'vitest'
+import { foldDeclaredDependencies, emptyDeclaredOnlyTree } from './declared-dependencies.js'
+import type { OpenSaasConfig, FieldConfig } from '../config/types.js'
+
+/**
+ * Unit coverage for `foldDeclaredDependencies` (ADR-0025), focused on the
+ * behaviour ADR-0026 requires of it once the read pipeline stopped
+ * auto-expanding a named relation's own subtree: a declared dependency no
+ * longer rides that expansion "for free" and must be folded recursively —
+ * at every level a field is computed, however that level was reached
+ * (declaration-added, caller-named bare, or caller-named with its own nested
+ * include).
+ *
+ * End-to-end coverage of the fold feeding an actual read (mocked Prisma, real
+ * `resolveOutput` hooks) lives in `tests/needs-declared-dependencies.test.ts`;
+ * these tests exercise the fold function directly so a regression here fails
+ * fast with a small, precise reproduction.
+ */
+
+function relField(ref: string, many = false): FieldConfig {
+  return { type: 'relationship', ref, many } as unknown as FieldConfig
+}
+
+function virtualNeeds(needs: string[]): FieldConfig {
+  return {
+    type: 'virtual',
+    needs,
+    hooks: { resolveOutput: () => 'x' },
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- minimal field config for unit test
+  } as any
+}
+
+describe('foldDeclaredDependencies', () => {
+  it('returns the exact same reference when there is nothing to fold', () => {
+    const fields: Record<string, FieldConfig> = { name: { type: 'text' } as FieldConfig }
+    const config = { db: { provider: 'sqlite' }, lists: {} } as unknown as OpenSaasConfig
+
+    const result = foldDeclaredDependencies(undefined, fields, config, 'List')
+    expect(result.include).toBeUndefined()
+    expect(result.declaredOnly).toEqual(emptyDeclaredOnlyTree())
+  })
+
+  it('folds a declaration-added bare relation whose own related list has further needs', () => {
+    // Order.total needs lineItems (declaration-added, no caller include at
+    // all). LineItem.summary needs product. Without recursing into the
+    // declaration-added branch, `product` would never be fetched, and
+    // LineItem.summary would silently compute over `undefined`.
+    const config: OpenSaasConfig = {
+      db: { provider: 'sqlite' },
+      lists: {
+        Order: {
+          fields: {
+            lineItems: relField('LineItem.order', true),
+            total: virtualNeeds(['lineItems']),
+          },
+        },
+        LineItem: {
+          fields: { product: relField('Product'), summary: virtualNeeds(['product']) },
+        },
+        Product: { fields: { name: { type: 'text' } as FieldConfig } },
+      },
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- minimal config for unit test
+    } as any
+
+    const result = foldDeclaredDependencies(undefined, config.lists.Order.fields, config, 'Order')
+
+    expect(result.include).toEqual({ lineItems: { include: { product: true } } })
+    // The whole `lineItems` branch is declaration-only at Order's level, so it
+    // needs no fine-grained nested tracking — the entire branch is stripped
+    // regardless of what's nested inside it.
+    expect(result.declaredOnly.keys.has('lineItems')).toBe(true)
+    expect(result.declaredOnly.nested.lineItems).toBeUndefined()
+  })
+
+  it('folds a caller-named BARE relation whose related list has its own needs, tracking the addition for fine-grained stripping', () => {
+    // The caller explicitly asked for `lineItems` (bare) — NOT declaration-only
+    // at Order's level — but LineItem's own `product` still has to be folded
+    // in for LineItem.summary's hook. Because the caller DID ask for
+    // `lineItems`, `product` must be tracked as declaration-only ONE LEVEL
+    // DOWN so it (and only it) gets stripped from each returned line item.
+    const config: OpenSaasConfig = {
+      db: { provider: 'sqlite' },
+      lists: {
+        Order: {
+          fields: {
+            lineItems: relField('LineItem.order', true),
+            total: virtualNeeds(['lineItems']),
+          },
+        },
+        LineItem: {
+          fields: {
+            product: relField('Product'),
+            tag: relField('Tag'),
+            summary: virtualNeeds(['product']),
+          },
+        },
+        Product: { fields: { name: { type: 'text' } as FieldConfig } },
+        Tag: { fields: { name: { type: 'text' } as FieldConfig } },
+      },
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- minimal config for unit test
+    } as any
+
+    const result = foldDeclaredDependencies(
+      { lineItems: true },
+      config.lists.Order.fields,
+      config,
+      'Order',
+    )
+
+    expect(result.include).toEqual({ lineItems: { include: { product: true } } })
+    // `lineItems` itself is caller-named, not declaration-only...
+    expect(result.declaredOnly.keys.has('lineItems')).toBe(false)
+    // ...but `product`, nested beneath it, IS — so it gets stripped from each
+    // line item while `lineItems` (and its other fields, e.g. `tag`) survive.
+    expect(result.declaredOnly.nested.lineItems?.keys.has('product')).toBe(true)
+  })
+
+  it("recurses into an explicit caller-nested include so the nested list's own needs are satisfied there too", () => {
+    const config: OpenSaasConfig = {
+      db: { provider: 'sqlite' },
+      lists: {
+        Order: { fields: { lineItems: relField('LineItem.order', true) } },
+        LineItem: {
+          fields: {
+            product: relField('Product'),
+            tag: relField('Tag'),
+            summary: virtualNeeds(['product']),
+          },
+        },
+        Product: { fields: { name: { type: 'text' } as FieldConfig } },
+        Tag: { fields: { name: { type: 'text' } as FieldConfig } },
+      },
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- minimal config for unit test
+    } as any
+
+    const result = foldDeclaredDependencies(
+      { lineItems: { include: { tag: true } } },
+      config.lists.Order.fields,
+      config,
+      'Order',
+    )
+
+    expect(result.include).toEqual({ lineItems: { include: { tag: true, product: true } } })
+    expect(result.declaredOnly.nested.lineItems?.keys.has('product')).toBe(true)
+    expect(result.declaredOnly.nested.lineItems?.keys.has('tag')).toBe(false)
+  })
+
+  it('does not fold anything beneath a relation whose related list has no needs of its own', () => {
+    const config: OpenSaasConfig = {
+      db: { provider: 'sqlite' },
+      lists: {
+        Order: { fields: { customer: relField('Customer') } },
+        Customer: { fields: { name: { type: 'text' } as FieldConfig } },
+      },
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- minimal config for unit test
+    } as any
+
+    const result = foldDeclaredDependencies(
+      { customer: true },
+      config.lists.Order.fields,
+      config,
+      'Order',
+    )
+
+    // Untouched — no needs anywhere in reach, so the bare relation stays bare.
+    expect(result.include).toEqual({ customer: true })
+    expect(result.declaredOnly).toEqual(emptyDeclaredOnlyTree())
+  })
+
+  it("folds a revisited list's own needs beneath a relation the request named", () => {
+    // The request names Post → author → posts, revisiting Post. Nothing here
+    // can loop — the include is a finite literal the caller wrote out — so the
+    // fold must keep going and satisfy Post.blurb's `needs` at THAT level too.
+    // Guarding a caller-named edge on list identity would stop the fold at
+    // `posts` and leave `blurb` computing over an undefined `tags`.
+    const config: OpenSaasConfig = {
+      db: { provider: 'sqlite' },
+      lists: {
+        Post: {
+          fields: {
+            author: relField('User.posts'),
+            comments: relField('Comment', true),
+            tags: relField('Tag', true),
+            blurb: virtualNeeds(['tags']),
+          },
+        },
+        User: { fields: { posts: relField('Post.author', true) } },
+        Comment: { fields: { body: { type: 'text' } as FieldConfig } },
+        Tag: { fields: { label: { type: 'text' } as FieldConfig } },
+      },
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- minimal config for unit test
+    } as any
+
+    const result = foldDeclaredDependencies(
+      { author: { include: { posts: { include: { comments: true } } } } },
+      config.lists.Post.fields,
+      config,
+      'Post',
+    )
+
+    expect(result.include).toEqual({
+      tags: true,
+      author: { include: { posts: { include: { comments: true, tags: true } } } },
+    })
+    // Only the nested `tags` needs fine-grained tracking: the root-level one is
+    // declaration-only at this level (stripped wholesale), while the nested one
+    // sits inside branches the caller named and must be stripped individually.
+    expect(result.declaredOnly.keys.has('tags')).toBe(true)
+    expect(result.declaredOnly.nested.author?.nested.posts?.keys.has('tags')).toBe(true)
+    expect(result.declaredOnly.nested.author?.nested.posts?.keys.has('comments')).toBe(false)
+  })
+
+  it("folds a self-referential relation's own needs when the request names it", () => {
+    // `parent` points back at Category itself. The request named it, so the
+    // fold must satisfy Category's own `needs` beneath it — `depth` is computed
+    // on the parent row too.
+    const config: OpenSaasConfig = {
+      db: { provider: 'sqlite' },
+      lists: {
+        Category: {
+          fields: {
+            parent: relField('Category.children'),
+            children: relField('Category.parent', true),
+            depth: virtualNeeds(['children']),
+          },
+        },
+      },
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- minimal config for unit test
+    } as any
+
+    const result = foldDeclaredDependencies(
+      { parent: true },
+      config.lists.Category.fields,
+      config,
+      'Category',
+    )
+
+    // `children` folds in at the root AND beneath the caller-named `parent`.
+    // The fold beneath `parent` stops there: `children` is declaration-added,
+    // so the guard applies to its own onward edge back into Category.
+    expect(result.include).toEqual({
+      parent: { include: { children: true } },
+      children: true,
+    })
+    expect(result.declaredOnly.keys.has('children')).toBe(true)
+    expect(result.declaredOnly.nested.parent?.keys.has('children')).toBe(true)
+  })
+
+  it('defensively terminates a two-list mutual `needs` cycle instead of recursing without bound', () => {
+    // Order.total needs lineItems; LineItem.orderRef needs order — a cycle
+    // `validateNeedsClosureDepth` (needs-closure.ts) rejects at generate time.
+    // This constructs it directly to exercise the fold's OWN defensive guard,
+    // independent of that generate-time backstop.
+    const config: OpenSaasConfig = {
+      db: { provider: 'sqlite' },
+      lists: {
+        Order: {
+          fields: {
+            lineItems: relField('LineItem.order', true),
+            total: virtualNeeds(['lineItems']),
+          },
+        },
+        LineItem: {
+          fields: { order: relField('Order.lineItems'), orderRef: virtualNeeds(['order']) },
+        },
+      },
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- minimal config for unit test
+    } as any
+
+    const result = foldDeclaredDependencies(undefined, config.lists.Order.fields, config, 'Order')
+
+    // Terminates (would hang/stack-overflow without the guard) and still
+    // produces a usable, finite include: `lineItems` folds in, but `order`
+    // beneath it stops at a flat fetch rather than looping back to `lineItems` again.
+    expect(result.include).toEqual({ lineItems: { include: { order: true } } })
+  })
+})

package/src/access/declared-dependencies.ts

@@ -1,5 +1,6 @@
 import type { FieldConfig, OpenSaasConfig } from '../config/types.js'
 import { getRelatedListConfig } from './engine.js'
+import type { FieldSelectionScope } from '../query/index.js'
 
 /**
  * Declared Dependencies — folding a computed field's `needs` into a read's
@@ -8,10 +9,9 @@ import { getRelatedListConfig } from './engine.js'
  * A field's `needs` declares immediate sibling relations its `resolveOutput`
  * hook cannot compute without. This module folds those relations into
  * whatever `include` a read is already building (caller-supplied, fragment-
- * derived, or none at all) BEFORE it reaches the existing access-scoping
- * pipeline (`buildIncludeWithAccessControl` / `mergeIncludeWithAccessControl`
- * in `access-filter.ts`) — a declared relation is scoped exactly like a
- * caller-named one, never a bypass.
+ * derived, or none at all) BEFORE it reaches the access-scoping pipeline
+ * (`buildAccessScopedInclude` in `access-filter.ts`) — a declared relation is
+ * scoped exactly like a caller-named one, never a bypass.
  *
  * The fold also tracks provenance: which relation keys, at which nesting
  * level, were added ONLY to satisfy a declaration (as opposed to being named
@@ -19,25 +19,44 @@ import { getRelatedListConfig } from './engine.js'
  * from the result after `resolveOutput` hooks have had a chance to read them
  * — a declared dependency is private plumbing, not an implicit `include`.
  *
- * Reach beyond one hop: a relation added here to satisfy a declaration is
- * added BARE (`true`), never with an explicit nested include of its own.
- * `buildIncludeWithAccessControl` already auto-expands a bare relation's own
- * readable-relationship subtree to `READ_INCLUDE_MAX_DEPTH` (pre-ADR-0026),
- * so a chain of declarations rides that existing expansion for free — the
- * related list's own declared needs are already present among what gets
- * auto-included beneath it. This is also why a declaration-driven cycle
- * (e.g. `Order.total` needs `lineItems`, `LineItem.orderRef` needs `order`)
- * can't recurse without bound here: it flows through
- * `buildIncludeWithAccessControl`'s existing `visitedLists` cycle guard
- * rather than through any recursion of this module's own (see ADR-0026's
- * note that this guard's remaining job, after that ADR lands, is defending
- * exactly this fold).
+ * **Every relation this module reaches is folded recursively**, whether it
+ * was added purely to satisfy a declaration or is already present for another
+ * reason (caller/fragment-named, bare or not). Since ADR-0026 removed the
+ * auto-expansion that used to carry a chain of declarations "for free" —
+ * naming a relation now fetches its own columns and stops — a field computed
+ * one hop down would otherwise lose its own declared dependencies the moment
+ * its list is reached any way OTHER than an explicit nested caller `include`.
+ * Declarations fold in "at every level a field is computed" (ADR-0025), not
+ * only where the caller happened to write one out.
  *
- * This module only recurses into EXPLICIT nested includes the caller wrote
- * (narrowing what's fetched below a relation) — those cut off the free
- * auto-expansion, so a nested list's own declared needs must be folded in
- * explicitly. An explicit caller include is always a finite literal, so this
- * recursion terminates on its own without a separate depth/cycle guard.
+ * A branch added purely by this fold (`declaredOnly.keys`) is stripped
+ * wholesale by `filterReadableFields` regardless of what's nested inside it,
+ * so its own nested declared-only keys need no individual tracking — only a
+ * branch present for another reason (caller/fragment-named) needs the
+ * fine-grained `declaredOnly.nested` tracking, so a declaration folded
+ * beneath IT can be stripped without removing the caller's own data.
+ *
+ * **Cycle guard, re-pointed (ADR-0026).** A caller-supplied `include` is
+ * always a finite literal and cannot cycle. Recursively following declared
+ * dependencies across lists CAN — list A declaring `needs` on a relation to
+ * list B, whose own field declares `needs` back to A — so `visitedLists`
+ * carries the list names already on this fold's own path and stops rather
+ * than recursing without bound. `pnpm generate`'s `validateNeedsClosureDepth`
+ * (`needs-closure.ts`) is the primary backstop — a cyclic `needs` closure
+ * fails generation and should never reach this code at runtime — this guard
+ * is defense in depth, not the mechanism relied on for correctness.
+ *
+ * The guard applies to DECLARATION-ADDED edges only, which is exactly where
+ * the unbounded recursion can come from: a branch added by this fold carries
+ * no caller include of its own, so everything beneath it is declaration-added
+ * too, and each such edge either reaches a list not yet on the path or stops
+ * — bounding that suffix by the number of lists. An edge the request itself
+ * named is bounded by the request's own finite literal instead. Applying the
+ * guard to those as well would stop the fold at a path that merely revisits a
+ * list (`Post → author → posts`, or a self-referential `parent`), silently
+ * leaving the revisited list's own declared dependencies unsatisfied — the
+ * `undefined`-compute ADR-0025 exists to prevent, at every level a field is
+ * computed.
  */
 
 /** Which relation keys, at which nesting level, exist only to satisfy a `needs` declaration. */
@@ -67,16 +86,39 @@ function isRelationshipFieldConfig(
   )
 }
 
+/** A plain object — excludes `null` and arrays, which `typeof x === 'object'` alone would admit. */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** The explicit nested `include` on an include entry, if the entry is a structured object naming one. */
+function getExplicitInclude(value: unknown): Record<string, unknown> | undefined {
+  if (!isPlainObject(value)) return undefined
+  const { include } = value
+  return isPlainObject(include) ? include : undefined
+}
+
 /**
  * The deduped set of relation names declared via `needs` by fields on this
  * list that have a `resolveOutput` hook. A `needs` entry on a field without
  * one is inert — there is no hook to feed it to — so it contributes nothing
  * to fetch.
+ *
+ * `selectedFields`, when given, restricts the union to fields the read is
+ * actually going to return (ADR-0027) — a field a fragment did not select is
+ * never computed, so its declared relation is never fetched for it either.
+ * `undefined` means unrestricted: every field with a hook contributes,
+ * matching a bare or `include`-based read, which always returns every
+ * computed field on the list.
  */
-export function getDeclaredRelationNames(fieldConfigs: Record<string, FieldConfig>): string[] {
+export function getDeclaredRelationNames(
+  fieldConfigs: Record<string, FieldConfig>,
+  selectedFields?: ReadonlySet<string>,
+): string[] {
   const names = new Set<string>()
-  for (const fieldConfig of Object.values(fieldConfigs)) {
+  for (const [fieldName, fieldConfig] of Object.entries(fieldConfigs)) {
     if (!fieldConfig?.hooks?.resolveOutput) continue
+    if (selectedFields && !selectedFields.has(fieldName)) continue
     for (const name of fieldConfig.needs ?? []) {
       names.add(name)
     }
@@ -86,19 +128,36 @@ export function getDeclaredRelationNames(fieldConfigs: Record<string, FieldConfi
 
 /**
  * Fold this list's declared dependencies into `rawInclude`, recursing into
- * any EXPLICIT nested include the caller wrote so a related list's own
- * declared needs are satisfied too (see module doc comment).
+ * EVERY relation reached from here — whether it was just added to satisfy a
+ * declaration or was already present for another reason — so that list's own
+ * declared dependencies are satisfied too, wherever it's reached (see module
+ * doc comment).
  *
  * Returns `rawInclude` itself (same reference) when there is nothing to
  * fold, so a list with no `needs` fields and no caller include stays on the
  * exact bare-read path (ADR-0024) — untouched, not merely equivalent.
+ *
+ * `listKey` seeds the cycle guard at the root of a read; recursive calls
+ * extend it with each related list reached along THIS fold's own path.
+ *
+ * `selection`, when given, is the fragment scope this level was reached
+ * under (ADR-0027) — only fields it names contribute their `needs` (see
+ * `getDeclaredRelationNames`). It is `undefined` for a bare/`include`-based
+ * read (unrestricted: every field's `needs` folds in, unchanged from before
+ * ADR-0027) and for any branch reached only to satisfy a declaration — a
+ * relation added purely by this fold has no fragment scope of its own, so
+ * its own list folds unrestricted, exactly as it did before selectivity
+ * existed.
  */
 export function foldDeclaredDependencies(
   rawInclude: Record<string, unknown> | undefined,
   fieldConfigs: Record<string, FieldConfig>,
   config: OpenSaasConfig,
+  listKey: string,
+  visitedLists: readonly string[] = [listKey],
+  selection?: FieldSelectionScope,
 ): { include: Record<string, unknown> | undefined; declaredOnly: DeclaredOnlyTree } {
-  const declaredNames = getDeclaredRelationNames(fieldConfigs)
+  const declaredNames = getDeclaredRelationNames(fieldConfigs, selection?.fields)
 
   if (declaredNames.length === 0 && !rawInclude) {
     return { include: rawInclude, declaredOnly: emptyDeclaredOnlyTree() }
@@ -117,21 +176,47 @@ export function foldDeclaredDependencies(
   for (const [key, value] of Object.entries(merged)) {
     const fieldConfig = fieldConfigs[key]
     if (!isRelationshipFieldConfig(fieldConfig)) continue
-    // A whole branch we just added is bare `true` — its own subtree auto-expands
-    // (see module doc comment), so there is no explicit nested include to recurse into.
-    if (declaredOnly.keys.has(key)) continue
-
-    const entry = value as { include?: Record<string, unknown> } | boolean
-    if (!entry || typeof entry !== 'object' || !entry.include) continue
 
     const relatedConfig = getRelatedListConfig(fieldConfig.ref, config)
     if (!relatedConfig) continue
+    // Defensive cycle guard (see module doc comment) — a DECLARATION-ADDED
+    // edge into a list already on this path stops here rather than recursing
+    // without bound. The value at `key` is left exactly as-is. The guard is
+    // deliberately not applied to an edge the request itself named: that
+    // recursion is bounded by the request's own finite literal and cannot
+    // loop, so stopping it would silently drop the folds beneath a request
+    // that merely revisits a list (e.g. `Post → author → posts`).
+    if (declaredOnly.keys.has(key) && visitedLists.includes(relatedConfig.listName)) continue
 
-    const nested = foldDeclaredDependencies(entry.include, relatedConfig.listConfig.fields, config)
-    if (nested.include !== entry.include) {
-      merged[key] = { ...entry, include: nested.include }
+    // A branch added purely by the fold has no fragment scope of its own —
+    // it folds unrestricted, as before ADR-0027. A branch the request itself
+    // named (caller include or fragment) carries that name's own nested
+    // scope, if the fragment gave it one (a bare `true` selector leaves it
+    // `undefined` — also unrestricted, since the caller asked for
+    // "everything" there).
+    const nestedSelection = declaredOnly.keys.has(key) ? undefined : selection?.nested[key]
+
+    const explicitNested = getExplicitInclude(value)
+    const nested = foldDeclaredDependencies(
+      explicitNested,
+      relatedConfig.listConfig.fields,
+      config,
+      relatedConfig.listName,
+      [...visitedLists, relatedConfig.listName],
+      nestedSelection,
+    )
+
+    if (nested.include) {
+      merged[key] = {
+        ...(typeof value === 'object' && value ? value : {}),
+        include: nested.include,
+      }
     }
-    if (!isDeclaredOnlyTreeEmpty(nested.declaredOnly)) {
+
+    // A whole branch added purely by the fold above is stripped wholesale by
+    // field-visibility regardless of what's nested inside it, so it needs no
+    // individual nested-key tracking of its own.
+    if (!declaredOnly.keys.has(key) && !isDeclaredOnlyTreeEmpty(nested.declaredOnly)) {
       declaredOnly.nested[key] = nested.declaredOnly
     }
   }

package/src/access/depth-limits.ts

@@ -1,12 +1,13 @@
 /**
- * Maximum nesting depth of relation `include`s that the Access Filter
- * (`buildIncludeWithAccessControl`) will auto-scope on a read.
+ * Maximum nesting depth of relation `include`s the Access Filter
+ * (`buildAccessScopedInclude`) will scope on a read.
  *
- * Security implication: this is an access-control boundary, not just a cost
- * bound. Past this depth the engine cannot compute a row/field scope for a
- * relation, so a caller-supplied `include` naming a relation at or beyond it
- * must be treated as a denial (see `AccessScopeDepthExceededError`) rather
- * than passed through unscoped — see ADR-0022 and issue #830.
+ * Since ADR-0026 made the read pipeline caller-directed, this is a COST
+ * limit, not an access-control boundary: nothing walks the relationship
+ * graph unprompted anymore, so there is no unscoped tree to fail open on. A
+ * request naming a relation at or beyond this depth still throws
+ * `AccessScopeDepthExceededError` (ADR-0022, issue #830) — the engine
+ * declines to serve a tree this expensive, not because it cannot scope one.
  */
 export const READ_INCLUDE_MAX_DEPTH = 5
 

package/src/access/errors.ts

@@ -2,15 +2,19 @@ import { READ_INCLUDE_MAX_DEPTH } from './depth-limits.js'
 
 /**
  * Thrown when a caller-supplied `include` names a relation nested deeper than
- * the Access Filter can scope (see `READ_INCLUDE_MAX_DEPTH`). Deliberately
- * distinct from `ValidationError`: this is not bad user input, it is the
- * engine refusing to return data it cannot prove is row/field scoped. Code
- * that catches `ValidationError` to report form errors must not silently
- * swallow this.
+ * `READ_INCLUDE_MAX_DEPTH`. Deliberately distinct from `ValidationError`: this
+ * is not bad user input, it is the engine declining to serve a tree this
+ * expensive. Code that catches `ValidationError` to report form errors must
+ * not silently swallow this.
  *
- * Only an explicit caller selection past the depth cap triggers this — the
- * auto-include silently stopping at the cap (no caller `include` involved)
- * never throws. See ADR-0022 and issue #830.
+ * Only an explicit request naming something at or past the cap triggers this
+ * — a read that simply doesn't reach this deep never throws. Before
+ * ADR-0026 made the read pipeline caller-directed, this cap was the engine's
+ * last line of defense against returning a relation it could not prove was
+ * row/field scoped (ADR-0022, issue #830); a request naming anything at this
+ * depth is now scoped exactly like every other named relation; the cap
+ * exists solely to bound how deep a request may cost the engine to serve. See
+ * ADR-0026 and `docs/adr/0022-access-control-fails-closed-when-it-cannot-scope.md`.
  */
 export class AccessScopeDepthExceededError extends Error {
   public listKey: string
@@ -19,10 +23,10 @@ export class AccessScopeDepthExceededError extends Error {
 
   constructor(listKey: string, fieldKey: string, depth: number) {
     super(
-      `Cannot compute an access scope for "${listKey}.${fieldKey}" at include depth ${depth}: ` +
-        `this exceeds the Access Filter's maximum read-include depth (${READ_INCLUDE_MAX_DEPTH}). ` +
-        `A caller-supplied include this deep cannot be row- and field-scoped, so the read is denied ` +
-        `rather than returned unscoped. Restructure the query to fetch this relation separately.`,
+      `Cannot include "${listKey}.${fieldKey}" at include depth ${depth}: this exceeds the read ` +
+        `pipeline's maximum include depth (${READ_INCLUDE_MAX_DEPTH}). This is a cost limit, not an ` +
+        `inability to scope — the engine declines to serve a tree this deep rather than returning ` +
+        `it. Restructure the query to fetch this relation separately.`,
     )
     this.name = 'AccessScopeDepthExceededError'
     this.listKey = listKey