@opensaas/stack-core 0.32.0 → 0.34.0

package/src/access/access-filter.test.ts

@@ -1,5 +1,11 @@
 import { describe, it, expect } from 'vitest'
-import { buildIncludeWithAccessControl, mergeIncludeWithAccessControl } from './access-filter.js'
+import {
+  buildIncludeWithAccessControl,
+  mergeIncludeWithAccessControl,
+  toPrismaInclude,
+} from './access-filter.js'
+import { AccessScopeDepthExceededError } from './errors.js'
+import { READ_INCLUDE_MAX_DEPTH } from './depth-limits.js'
 import type { OpenSaasConfig, FieldConfig } from '../config/types.js'
 import type { AccessContext } from './types.js'
 
@@ -43,11 +49,15 @@ function cyclicConfig(): OpenSaasConfig {
   } as any
 }
 
-function makeContext(): AccessContext {
+function makeContext(resolveOutputDepth = 0): AccessContext {
+  const chain = Array.from({ length: resolveOutputDepth }, (_, i) => ({
+    listKey: 'TestHook',
+    fieldKey: `hook${i}`,
+  }))
   return {
     session: null,
     _isSudo: false,
-    _resolveOutputCounter: { depth: 0 },
+    _resolveOutputChain: chain,
     // eslint-disable-next-line @typescript-eslint/no-explicit-any -- minimal context for unit test
   } as any
 }
@@ -68,16 +78,67 @@ function includeDepth(include: unknown): number {
   return max
 }
 
+// A straight-line chain of `count` lists, each with a scalar field and a
+// single relationship to the next list: L0 → L1 → … → L(count-1). Every list
+// past the root is query-scoped with a filter unique to it, so a test can
+// assert the merged tree actually carries the right `where` at a given hop
+// (not just that it happens not to throw).
+function chainConfig(count: number): OpenSaasConfig {
+  const lists: Record<string, { fields: Record<string, FieldConfig>; access: unknown }> = {}
+  for (let i = 0; i < count; i++) {
+    const listName = `L${i}`
+    const fields: Record<string, FieldConfig> = { name: { type: 'text' } as FieldConfig }
+    if (i < count - 1) {
+      fields.next = rel(`L${i + 1}.prev`)
+    }
+    if (i > 0) {
+      fields.prev = rel(`L${i - 1}.next`)
+    }
+    const filter = { ownerId: { equals: listName } }
+    lists[listName] = {
+      fields,
+      access: { operation: { query: i === 0 ? () => true : () => filter } },
+    }
+  }
+  return {
+    db: { provider: 'sqlite', url: 'file:./dev.db' },
+    lists,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- minimal config for unit test
+  } as any
+}
+
+// A caller `include` value selecting `next` `hops` more times beyond the
+// point at which this value is attached, ending in a bare `true` leaf. E.g.
+// `nestedInclude(0) === true` (stop here); `{ next: nestedInclude(2) }` at the
+// top level names 3 hops total (the outer `next` plus 2 more).
+function nestedInclude(hops: number): Record<string, unknown> {
+  if (hops <= 0) return true as unknown as Record<string, unknown>
+  return { include: { next: nestedInclude(hops - 1) } }
+}
+
+// Read the `where` at the end of a chain of nested `next` includes (used to
+// assert row-scoping survived down to a specific hop).
+function whereAtHop(merged: Record<string, unknown>, hops: number): unknown {
+  let current: unknown = merged
+  for (let i = 0; i < hops; i++) {
+    const entry = (current as { next?: unknown })?.next
+    if (i === hops - 1) return (entry as { where?: unknown })?.where
+    current = (entry as { include?: unknown })?.include
+  }
+  return undefined
+}
+
 describe('buildIncludeWithAccessControl — cyclic graph', () => {
   it('stops re-descending a relationship cycle instead of walking to MAX_DEPTH', async () => {
     const config = cyclicConfig()
-    const include = await buildIncludeWithAccessControl(
+    const result = await buildIncludeWithAccessControl(
       config.lists.A.fields,
       { session: null, context: makeContext() },
       config,
       0,
       ['A'],
     )
+    const include = toPrismaInclude(result)
 
     // A → B → C, then C.a closes the cycle back to A → flat (no further nesting).
     expect(include).toEqual({
@@ -91,7 +152,7 @@ describe('buildIncludeWithAccessControl — cyclic graph', () => {
   it('flattens a self-referential relationship to a single level', async () => {
     const allowQuery = () => true
     const config = {
-      db: { provider: 'sqlite', url: 'file:./dev.db' },
+      db: { provider: 'sqlite' },
       lists: {
         Category: {
           fields: {
@@ -105,13 +166,14 @@ describe('buildIncludeWithAccessControl — cyclic graph', () => {
       // eslint-disable-next-line @typescript-eslint/no-explicit-any -- minimal config for unit test
     } as any as OpenSaasConfig
 
-    const include = await buildIncludeWithAccessControl(
+    const result = await buildIncludeWithAccessControl(
       config.lists.Category.fields,
       { session: null, context: makeContext() },
       config,
       0,
       ['Category'],
     )
+    const include = toPrismaInclude(result)
 
     // Both self-references come back flat — no infinite parent/children descent.
     expect(include).toEqual({ parent: true, children: true })
@@ -138,6 +200,7 @@ describe('mergeIncludeWithAccessControl — bare-true leaf on a cyclic graph', (
       accessControlledInclude,
       config.lists.A.fields,
       config,
+      'A',
     )
 
     expect(merged).toEqual({
@@ -159,7 +222,7 @@ describe('mergeIncludeWithAccessControl — caller take on a to-many relation (i
   // A one-list config whose `posts` to-many is query-scoped by an access filter.
   function scopedConfig(): OpenSaasConfig {
     return {
-      db: { provider: 'sqlite', url: 'file:./dev.db' },
+      db: { provider: 'sqlite' },
       lists: {
         User: {
           fields: { name: { type: 'text' } as FieldConfig, posts: rel('Post.author', true) },
@@ -190,6 +253,7 @@ describe('mergeIncludeWithAccessControl — caller take on a to-many relation (i
       accessControlledInclude,
       config.lists.User.fields,
       config,
+      'User',
     )
 
     // The bound rides on top of the access filter — neither is dropped. The
@@ -220,9 +284,196 @@ describe('mergeIncludeWithAccessControl — caller take on a to-many relation (i
       accessControlledInclude,
       config.lists.User.fields,
       config,
+      'User',
     )
 
     // A denied relation is dropped wholesale — the take cannot resurrect it.
     expect(merged).toEqual({})
   })
 })
+
+/**
+ * Regression coverage for issue #830: the read pipeline used to FAIL OPEN past
+ * `READ_INCLUDE_MAX_DEPTH` — a caller-supplied `include` nested deeper than the
+ * engine could scope was passed through unscoped rather than denied. These
+ * tests pin the exact boundary the fix introduces (ADR-0022): a caller include
+ * one level past the cap throws, the same include one level shallower still
+ * works, and an unrequested auto-include past the cap stays silent.
+ */
+describe('mergeIncludeWithAccessControl — fail-closed at the read-include depth cap (#830)', () => {
+  // A relation `hops` hops from the root sits AT the cap boundary (correctly
+  // where-scoped, matching the triage report's "F" list); one hop further is
+  // the first one the engine cannot scope ("G"). With
+  // READ_INCLUDE_MAX_DEPTH = 5 that boundary is hop 5 / hop 6.
+  const HOPS_AT_CAP = READ_INCLUDE_MAX_DEPTH
+
+  it('throws AccessScopeDepthExceededError when the caller include reaches past the cap', async () => {
+    // L0 → L1 → … → L6 (one more list than HOPS_AT_CAP + 1) so a caller
+    // include can walk `next` one hop past the boundary.
+    const chainLength = HOPS_AT_CAP + 2
+    const config = chainConfig(chainLength)
+
+    const accessControlledInclude = await buildIncludeWithAccessControl(
+      config.lists.L0.fields,
+      { session: null, context: makeContext() },
+      config,
+      0,
+      ['L0'],
+    )
+
+    // Outer `next` (hop 1) + nestedInclude(HOPS_AT_CAP) (HOPS_AT_CAP more) = HOPS_AT_CAP + 1 hops.
+    const callerInclude = { next: nestedInclude(HOPS_AT_CAP) }
+
+    expect(() =>
+      mergeIncludeWithAccessControl(
+        callerInclude,
+        accessControlledInclude,
+        config.lists.L0.fields,
+        config,
+        'L0',
+      ),
+    ).toThrow(AccessScopeDepthExceededError)
+  })
+
+  it('still row-scopes a caller include one level shallower than the cap', async () => {
+    const chainLength = HOPS_AT_CAP + 1
+    const config = chainConfig(chainLength)
+
+    const accessControlledInclude = await buildIncludeWithAccessControl(
+      config.lists.L0.fields,
+      { session: null, context: makeContext() },
+      config,
+      0,
+      ['L0'],
+    )
+
+    // Outer `next` (hop 1) + nestedInclude(HOPS_AT_CAP - 1) = HOPS_AT_CAP hops total — right at the boundary.
+    const callerInclude = { next: nestedInclude(HOPS_AT_CAP - 1) }
+
+    // Must NOT throw — this depth is within what the engine can scope.
+    const merged = mergeIncludeWithAccessControl(
+      callerInclude,
+      accessControlledInclude,
+      config.lists.L0.fields,
+      config,
+      'L0',
+    )
+
+    expect(includeDepth(merged)).toBe(HOPS_AT_CAP)
+    // The last list in the chain (at the boundary) is genuinely row-scoped —
+    // not just present without a throw.
+    expect(whereAtHop(merged, HOPS_AT_CAP)).toEqual({ ownerId: { equals: `L${HOPS_AT_CAP}` } })
+  })
+
+  it('does not throw for an ordinary read with no caller include, even on a deep schema', async () => {
+    // No caller include at all — the auto-include just stops at the cap
+    // silently. This must never throw; only an EXPLICIT caller selection past
+    // the cap is a denial.
+    const chainLength = HOPS_AT_CAP + 3
+    const config = chainConfig(chainLength)
+
+    const result = await buildIncludeWithAccessControl(
+      config.lists.L0.fields,
+      { session: null, context: makeContext() },
+      config,
+      0,
+      ['L0'],
+    )
+
+    expect(() => toPrismaInclude(result)).not.toThrow()
+    const include = toPrismaInclude(result)
+    expect(includeDepth(include)).toBeLessThanOrEqual(HOPS_AT_CAP)
+  })
+
+  it('a list with no relationships still passes the caller include through unchanged', async () => {
+    const config = {
+      db: { provider: 'sqlite' },
+      lists: {
+        Leaf: {
+          fields: { name: { type: 'text' } as FieldConfig },
+          access: { operation: { query: () => true } },
+        },
+      },
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- minimal config for unit test
+    } as any as OpenSaasConfig
+
+    const accessControlledInclude = await buildIncludeWithAccessControl(
+      config.lists.Leaf.fields,
+      { session: null, context: makeContext() },
+      config,
+      0,
+      ['Leaf'],
+    )
+
+    expect(accessControlledInclude).toEqual({ kind: 'nothing-to-scope' })
+
+    // An arbitrary (non-declared-relationship) key passed through unchanged —
+    // access control does not govern keys it doesn't recognize as relationships.
+    const merged = mergeIncludeWithAccessControl(
+      { someUnrelatedKey: true },
+      accessControlledInclude,
+      config.lists.Leaf.fields,
+      config,
+      'Leaf',
+    )
+    expect(merged).toEqual({ someUnrelatedKey: true })
+  })
+})
+
+/**
+ * Regression coverage for the resolveOutput/virtual-field trigger of #830: a
+ * read issued from inside a resolveOutput hook used to lose relation row
+ * scoping ENTIRELY (whole-object passthrough) rather than scoping the
+ * immediate relation and simply not auto-expanding further. The loop guard
+ * that motivated the original passthrough (hooks making DB queries that
+ * include relationships back to the same entity) must still hold.
+ */
+describe('buildIncludeWithAccessControl — inside a resolveOutput context', () => {
+  it('scopes the immediate relation with its access where but does not auto-expand nested relations', async () => {
+    const config = chainConfig(4) // L0 → L1 → L2 → L3
+    config.lists.L1.access = { operation: { query: () => ({ tenantId: { equals: 'mine' } }) } }
+
+    const result = await buildIncludeWithAccessControl(
+      config.lists.L0.fields,
+      { session: null, context: makeContext(1) }, // depth > 0 → inside resolveOutput
+      config,
+      0,
+      ['L0'],
+    )
+
+    expect(result.kind).toBe('scoped')
+    const include = toPrismaInclude(result)
+    // L1's own access `where` is applied...
+    expect(include).toEqual({ next: { where: { tenantId: { equals: 'mine' } } } })
+    // ...but L1's own nested relations (`next` → L2) are NOT auto-included.
+    expect(includeDepth(include)).toBe(1)
+  })
+
+  it('terminates on a self-referential relationship instead of looping', async () => {
+    const config = {
+      db: { provider: 'sqlite' },
+      lists: {
+        Category: {
+          fields: {
+            name: { type: 'text' } as FieldConfig,
+            parent: rel('Category.children'),
+            children: rel('Category.parent', true),
+          },
+          access: { operation: { query: () => true } },
+        },
+      },
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- minimal config for unit test
+    } as any as OpenSaasConfig
+
+    const result = await buildIncludeWithAccessControl(
+      config.lists.Category.fields,
+      { session: null, context: makeContext(1) },
+      config,
+      0,
+      ['Category'],
+    )
+
+    const include = toPrismaInclude(result)
+    expect(include).toEqual({ parent: true, children: true })
+  })
+})

package/src/access/access-filter.ts

@@ -1,6 +1,8 @@
 import type { Session, AccessContext, PrismaFilter } from './types.js'
 import type { OpenSaasConfig, FieldConfig } from '../config/types.js'
 import { checkAccess, getRelatedListConfig } from './engine.js'
+import { READ_INCLUDE_MAX_DEPTH } from './depth-limits.js'
+import { AccessScopeDepthExceededError } from './errors.js'
 
 /**
  * Access Filter — phase 1 of the two-phase read (pre-query).
@@ -18,9 +20,83 @@ import { checkAccess, getRelatedListConfig } from './engine.js'
  * glossary in `CONTEXT.md`.
  */
 
+/** A single relation entry in a Prisma `include` object (see below). */
+type IncludeEntry = boolean | { where?: PrismaFilter; include?: IncludeObject; take?: number }
+type IncludeObject = Record<string, IncludeEntry>
+
+/**
+ * The result of trying to compute an access-controlled include for a list's
+ * fields. `buildIncludeWithAccessControl` used to collapse three unrelated
+ * outcomes into a single overloaded `undefined`: "inside a resolveOutput
+ * context", "hit the depth cap", and "no relationships to scope" all looked
+ * identical to callers, which is what let a depth-capped relation pass
+ * through unscoped (issue #830). This discriminated result keeps them
+ * distinguishable all the way to `mergeIncludeWithAccessControl`, which is the
+ * only place that knows whether a caller actually asked for the part that
+ * couldn't be scoped.
+ *
+ * - `scoped`: relationships were found and (to the extent depth allows)
+ *   access-controlled; `include` is the resulting tree.
+ * - `nothing-to-scope`: the list genuinely has no relationships to scope, OR
+ *   we are inside a resolveOutput/virtual-field context and deliberately did
+ *   not descend into a relation's own nested relations. Passing the caller's
+ *   include through unchanged here is correct, not a leak.
+ * - `depth-exceeded`: we could not evaluate this level at all because it sits
+ *   at or past `READ_INCLUDE_MAX_DEPTH`. This is a denial: a caller `include`
+ *   that reaches here must be rejected, not passed through.
+ */
+export type AccessIncludeResult =
+  | { kind: 'scoped'; include: RichIncludeObject }
+  | { kind: 'nothing-to-scope' }
+  | { kind: 'depth-exceeded' }
+
+/** A relation entry in the rich, provenance-carrying tree `buildIncludeWithAccessControl` builds internally. */
+type RichIncludeEntry = { where?: PrismaFilter; nested: AccessIncludeResult }
+type RichIncludeObject = Record<string, RichIncludeEntry>
+
+/**
+ * Collapse a rich, provenance-carrying include entry down to the plain
+ * Prisma-shaped form. A `nested` result that is `depth-exceeded` or
+ * `nothing-to-scope` contributes no `include` key — this is the AUTO-include
+ * silently stopping, which is correct when no caller asked for anything past
+ * this point (see `AccessIncludeResult` doc comment).
+ */
+function toPrismaEntry(entry: RichIncludeEntry): IncludeEntry {
+  const result: { where?: PrismaFilter; include?: IncludeObject } = {}
+  if (entry.where) result.where = entry.where
+  if (entry.nested.kind === 'scoped') {
+    const nestedInclude = toPrismaInclude(entry.nested)
+    if (nestedInclude && Object.keys(nestedInclude).length > 0) {
+      result.include = nestedInclude
+    }
+  }
+  return Object.keys(result).length > 0 ? result : true
+}
+
 /**
- * Build Prisma include object with access control filters
- * This allows us to filter relationships at the database level instead of in memory
+ * Collapse an `AccessIncludeResult` to the plain Prisma `include` shape used
+ * when there is no caller-supplied include to merge against (the direct
+ * auto-include path). `nothing-to-scope` and `depth-exceeded` both become
+ * `undefined` here — at this call site nothing was explicitly requested past
+ * either boundary, so there is nothing to deny.
+ */
+export function toPrismaInclude(result: AccessIncludeResult): IncludeObject | undefined {
+  if (result.kind !== 'scoped') return undefined
+  const out: IncludeObject = {}
+  for (const [key, entry] of Object.entries(result.include)) {
+    out[key] = toPrismaEntry(entry)
+  }
+  return out
+}
+
+/**
+ * Build the access-controlled include for a list's fields.
+ *
+ * This allows us to filter relationships at the database level instead of in
+ * memory. Returns an {@link AccessIncludeResult} rather than a plain include
+ * object so that `mergeIncludeWithAccessControl` can tell a genuine "nothing
+ * to scope" apart from "the engine hit its depth cap" (see that type's doc
+ * comment and ADR-0022).
  */
 export async function buildIncludeWithAccessControl(
   fieldConfigs: Record<string, FieldConfig>,
@@ -34,23 +110,27 @@ export async function buildIncludeWithAccessControl(
   // relationship cycles (A → B → … → A) and stop the auto-include from
   // re-descending them. Seed it with the root list name at the call site.
   visitedLists: readonly string[] = [],
-) {
-  const MAX_DEPTH = 5
-  if (depth >= MAX_DEPTH) {
-    return undefined
+): Promise<AccessIncludeResult> {
+  if (depth >= READ_INCLUDE_MAX_DEPTH) {
+    return { kind: 'depth-exceeded' }
   }
 
-  // Skip auto-including relationships when inside a resolveOutput hook
-  // This prevents infinite loops when hooks make DB queries that include
-  // relationships back to the same entity (e.g., User virtual field queries Posts
-  // which includes author back to User, triggering the virtual field again)
-  if (args.context._resolveOutputCounter.depth > 0) {
-    return undefined
-  }
-
-  type IncludeEntry = boolean | { where?: PrismaFilter; include?: Record<string, IncludeEntry> }
-
-  const include: Record<string, IncludeEntry> = {}
+  // Inside a resolveOutput/virtual-field context we still scope each immediate
+  // relation (its own access `where`), but do not auto-expand INTO its nested
+  // relations — this keeps a single hook-issued read's include from growing
+  // depth-first. Correction (ADR-0023): this does NOT by itself terminate a
+  // cycle, despite what an earlier version of this comment claimed. A
+  // self-referential relation read from inside a hook is a NEW top-level
+  // read, invisible to this function's own recursion — the loop runs through
+  // the hook↔read boundary, not through repeated calls to
+  // `buildIncludeWithAccessControl`. Loop termination is the resolve chain's
+  // job: `field-visibility.ts`'s `resolveReadableFieldValue` refuses to
+  // re-enter a `(list, field)` pair already on the chain. What this check
+  // still does correctly is row-scope the immediate relation rather than
+  // skipping scoping altogether (issue #830's second trigger).
+  const insideResolveOutput = args.context._resolveOutputChain.length > 0
+
+  const include: RichIncludeObject = {}
   let hasRelationships = false
 
   for (const [fieldName, fieldConfig] of Object.entries(fieldConfigs)) {
@@ -71,13 +151,7 @@ export async function buildIncludeWithAccessControl(
           continue
         }
 
-        // Build the include entry
-        const includeEntry: Record<string, unknown> = {}
-
-        // If access returns a filter, add it to the where clause
-        if (typeof accessResult === 'object') {
-          includeEntry.where = accessResult
-        }
+        const where = typeof accessResult === 'object' ? accessResult : undefined
 
         // Cycle guard: if the related list already appears on the path from the
         // root, DO NOT auto-include its relationships again. On a cyclic
@@ -90,39 +164,26 @@ export async function buildIncludeWithAccessControl(
         // genuine single-level fetch, not a re-expansion of the full auto-include.
         // The relation itself is still included (as a FLAT fetch of its own
         // columns); only its onward relationships are pruned at the back-edge.
+        let nested: AccessIncludeResult = { kind: 'nothing-to-scope' }
         const relatedListName = relatedConfig.listName
-        if (!visitedLists.includes(relatedListName)) {
-          // Recursively build nested includes
-          const nestedInclude = await buildIncludeWithAccessControl(
+        if (!insideResolveOutput && !visitedLists.includes(relatedListName)) {
+          nested = await buildIncludeWithAccessControl(
             relatedConfig.listConfig.fields,
             args,
             config,
             depth + 1,
             [...visitedLists, relatedListName],
           )
-
-          if (nestedInclude && Object.keys(nestedInclude).length > 0) {
-            includeEntry.include = nestedInclude
-          }
         }
 
-        // Add to include object
-        include[fieldName] = Object.keys(includeEntry).length > 0 ? includeEntry : true
+        include[fieldName] = { where, nested }
       }
     }
   }
 
-  return hasRelationships ? include : undefined
+  return hasRelationships ? { kind: 'scoped', include } : { kind: 'nothing-to-scope' }
 }
 
-/**
- * A single relation entry in a Prisma `include` object: either a bare `true`
- * (fetch with no extra constraints) or an object that scopes the fetch with a
- * `where` filter and/or a nested `include`.
- */
-type IncludeEntry = boolean | { where?: PrismaFilter; include?: IncludeObject; take?: number }
-type IncludeObject = Record<string, IncludeEntry>
-
 /** The structured (object) form of a relation include entry. */
 type IncludeEntryObject = { where?: PrismaFilter; include?: IncludeObject; take?: number }
 
@@ -193,38 +254,46 @@ function andWhere(
  * - If the caller names a key that is NOT a config-declared relationship, it is
  *   passed through unchanged (access control does not govern it).
  *
- * The access-controlled include is recursive to `MAX_DEPTH` (see
- * `buildIncludeWithAccessControl`); beyond that depth no auto-include exists, so
- * deeper caller selections pass through unscoped — consistent with the existing
- * auto-include behaviour.
+ * `accessControlledInclude` is the {@link AccessIncludeResult} for THIS level:
+ * - `nothing-to-scope` → nothing to merge against (the list has no
+ *   relationships, or we're inside a resolveOutput context where the caller
+ *   include is irrelevant to begin with). Pass the caller's include through
+ *   unchanged — this is a non-denial outcome, not "every relation denied".
+ * - `depth-exceeded` → the engine could not compute a scope for THIS level at
+ *   all because it sits at or past `READ_INCLUDE_MAX_DEPTH`. If the caller
+ *   named anything here, that is exactly the case that used to pass through
+ *   unscoped (issue #830): throw `AccessScopeDepthExceededError` instead. An
+ *   empty caller include at this level (nothing further requested) is not an
+ *   error — there's simply nothing to do.
+ * - `scoped` → the normal per-relation merge below: a declared relationship
+ *   ABSENT from the access include was denied (drop it); one PRESENT is used
+ *   as the base, AND-combining `where`s and recursing into nested includes.
  *
- * `accessControlledInclude` being `undefined` is NOT "every relation denied". It
- * means no access-controlled include was computed at all — a non-denial outcome
- * that `buildIncludeWithAccessControl` returns when inside a `resolveOutput`/
- * virtual-field context, at `MAX_DEPTH`, or when the list has no relationships.
- * In every one of those cases there is nothing to merge against, so the caller's
- * `include` is passed through unchanged (matching the prior `args.include || …`
- * fallback). This is distinct from an `undefined` ENTRY inside a defined access
- * include, which DOES mean the relation was denied and must be dropped (see the
- * per-relation loop below). Only the whole-object `undefined` is a passthrough.
+ * `listKey` and `depth` are carried only to build a useful
+ * `AccessScopeDepthExceededError` message; they do not affect merge behaviour.
  */
 export function mergeIncludeWithAccessControl(
   callerInclude: Record<string, unknown>,
-  accessControlledInclude: Record<string, unknown> | undefined,
+  accessControlledInclude: AccessIncludeResult,
   fieldConfigs: Record<string, FieldConfig>,
   config: OpenSaasConfig,
+  listKey: string,
+  depth: number = 0,
 ): Record<string, unknown> {
-  // No access-controlled include was computed (resolveOutput/virtual context,
-  // MAX_DEPTH, or a list with no relationships) → nothing to scope against, so
-  // pass the caller's include through unchanged. Dropping relations here would be
-  // fail-closed data loss, not a denial. Denied relations are dropped only when a
-  // defined access include OMITS them (handled per-relation below).
-  if (accessControlledInclude === undefined) {
+  if (accessControlledInclude.kind === 'nothing-to-scope') {
     return callerInclude
   }
 
+  if (accessControlledInclude.kind === 'depth-exceeded') {
+    const [firstRelationName] = Object.keys(callerInclude)
+    if (firstRelationName !== undefined) {
+      throw new AccessScopeDepthExceededError(listKey, firstRelationName, depth)
+    }
+    return {}
+  }
+
   const merged: Record<string, unknown> = {}
-  const accessInclude = accessControlledInclude
+  const accessInclude = accessControlledInclude.include
 
   for (const [relationName, callerValue] of Object.entries(callerInclude)) {
     const fieldConfig = fieldConfigs[relationName]
@@ -237,36 +306,41 @@ export function mergeIncludeWithAccessControl(
       continue
     }
 
-    const accessValue = accessInclude[relationName]
+    const accessEntry = accessInclude[relationName]
 
     // Declared relationship absent from the access include → query access denied → drop it.
-    if (accessValue === undefined) {
+    if (accessEntry === undefined) {
       continue
     }
 
-    const accessEntry = asEntryObject(accessValue)
     const callerEntry = asEntryObject(callerValue)
 
     // Resolve the related list's field configs so nested includes merge recursively.
     const relatedConfig = getRelatedListConfig(fieldConfig.ref as string, config)
     const relatedFields = relatedConfig?.listConfig.fields
 
-    const mergedWhere = andWhere(accessEntry?.where, callerEntry?.where)
+    const mergedWhere = andWhere(accessEntry.where, callerEntry?.where)
 
     let mergedNested: Record<string, unknown> | undefined
-    if (callerEntry?.include && relatedFields) {
-      // Recurse: scope the caller's nested selection against the nested access include.
+    if (callerEntry?.include && relatedFields && relatedConfig) {
+      // Recurse: scope the caller's nested selection against the nested access
+      // result. If that result is 'depth-exceeded', the recursive call itself
+      // throws — the caller named something the engine cannot scope.
       mergedNested = mergeIncludeWithAccessControl(
         callerEntry.include,
-        accessEntry?.include,
+        accessEntry.nested,
         relatedFields,
         config,
+        relatedConfig.listName,
+        depth + 1,
       )
-    } else if (accessEntry?.include) {
+    } else if (accessEntry.nested.kind === 'scoped') {
       // Caller selected the relation bare (no nested include); keep the
       // access-controlled nested include so deeper relations stay filtered.
-      mergedNested = accessEntry.include
+      mergedNested = toPrismaInclude(accessEntry.nested)
     }
+    // If the caller's entry has no nested include, a 'depth-exceeded' nested
+    // result is silent here too — nothing was asked for past this point.
 
     const entry: { where?: PrismaFilter; include?: Record<string, unknown>; take?: number } = {}
     if (mergedWhere) entry.where = mergedWhere