@opensaas/stack-core 0.36.0 → 0.38.0

package/src/query/index.ts

@@ -345,6 +345,59 @@ export function buildInclude(fields: FieldSelection<unknown>): Record<string, un
   return hasIncludes ? include : undefined
 }
 
+/**
+ * A snapshot of which field names a fragment selects at one nesting level,
+ * plus the same tree one level down for every relation selected via a nested
+ * Fragment/RelationSelector. `fields: undefined` means "unrestricted" — every
+ * field at this level is going to be returned, which is what a bare or
+ * `include`-based read means for the whole tree (only a `query` fragment ever
+ * produces a restricted scope, and only as deep as it names).
+ *
+ * Used to make computed-field evaluation (`filterReadableFields`) and
+ * declared-dependency folding (`foldDeclaredDependencies`) projection-aware
+ * (ADR-0027): a field not named by the scope at its level is never computed
+ * and its `needs` are never folded, because the read is never going to
+ * return it.
+ * @internal
+ */
+export type FieldSelectionScope = {
+  readonly fields: ReadonlySet<string> | undefined
+  readonly nested: Readonly<Record<string, FieldSelectionScope>>
+}
+
+/**
+ * Build the `FieldSelectionScope` for one fragment's field selection,
+ * recursing into nested Fragment/RelationSelector entries the same way
+ * `buildInclude` does. A relation named with the bare `true` shorthand (no
+ * narrower nested Fragment) gets no entry in `nested`, so a level reached
+ * through it is treated as unrestricted — the caller asked for "everything"
+ * there and gave no narrower shape to restrict it with.
+ * @internal
+ */
+export function buildFieldSelectionScope(fields: FieldSelection<unknown>): FieldSelectionScope {
+  const fieldNames = new Set(Object.keys(fields as Record<string, unknown>))
+  const nested: Record<string, FieldSelectionScope> = {}
+
+  for (const [key, value] of Object.entries(fields as Record<string, unknown>)) {
+    if (value === null || value === true || typeof value !== 'object') continue
+    const val = value as Record<string, unknown>
+
+    if (isFragment(val)) {
+      nested[key] = buildFieldSelectionScope(val._fields as FieldSelection<unknown>)
+      continue
+    }
+
+    if ('query' in val && isFragment(val.query)) {
+      nested[key] = buildFieldSelectionScope(
+        (val.query as Fragment<unknown, FieldSelection<unknown>>)
+          ._fields as FieldSelection<unknown>,
+      )
+    }
+  }
+
+  return { fields: fieldNames, nested }
+}
+
 /**
  * Recursively pick only the fields requested by a fragment from a raw Prisma
  * result object. This ensures the runtime shape exactly matches the type

package/src/query/relationship-options.ts

@@ -23,7 +23,7 @@ export interface RelationshipOptionsArgs {
  * editor — the read primitive behind the `relationshipOptions` serverAction
  * op. Selects only `id` and the resolved label field (via
  * {@link getLabelFieldName}), so the fragment carries no relation keys and
- * `buildIncludeWithAccessControl`'s depth-5 auto-include never runs.
+ * `buildAccessScopedInclude` never has anything to scope.
  *
  * Operation-level `query` access on `relatedListKey` still applies — a denied
  * list resolves to `[]` (via the underlying access-controlled `findMany`).

package/tests/access-relationships.test.ts

@@ -123,7 +123,7 @@ describe('Relationship Access Control', () => {
         expect(result.author?.name).toBe('John Doe')
       })
 
-      it('should filter out single relationship when access denied (via buildIncludeWithAccessControl)', async () => {
+      it('should filter out single relationship when access denied (via buildAccessScopedInclude)', async () => {
         const config: OpenSaasConfig = {
           db: {
             provider: 'postgresql',
@@ -152,16 +152,18 @@ describe('Relationship Access Control', () => {
           },
         }
 
-        // Test that buildIncludeWithAccessControl excludes the denied relationship
-        const { buildIncludeWithAccessControl } = await import('../src/access/index.js')
+        // Test that buildAccessScopedInclude excludes the denied relationship
+        const { buildAccessScopedInclude } = await import('../src/access/index.js')
 
-        const include = await buildIncludeWithAccessControl(
+        const include = await buildAccessScopedInclude(
+          { author: true },
           config.lists.Post.fields,
           {
             session: null,
             context: mockContext,
           },
           config,
+          'Post',
         )
 
         // When access is denied, the relationship should not be included
@@ -286,7 +288,7 @@ describe('Relationship Access Control', () => {
         expect(result.posts?.[1].title).toBe('Post 2')
       })
 
-      it('should filter items in many relationships based on query access (via buildIncludeWithAccessControl)', async () => {
+      it('should filter items in many relationships based on query access (via buildAccessScopedInclude)', async () => {
         const config: OpenSaasConfig = {
           db: {
             provider: 'postgresql',
@@ -318,19 +320,19 @@ describe('Relationship Access Control', () => {
           },
         }
 
-        // Test that buildIncludeWithAccessControl creates the right where clause
-        const { buildIncludeWithAccessControl, toPrismaInclude } =
-          await import('../src/access/index.js')
+        // Test that buildAccessScopedInclude creates the right where clause
+        const { buildAccessScopedInclude } = await import('../src/access/index.js')
 
-        const result = await buildIncludeWithAccessControl(
+        const include = await buildAccessScopedInclude(
+          { posts: true },
           config.lists.User.fields,
           {
             session: null,
             context: mockContext,
           },
           config,
+          'User',
         )
-        const include = toPrismaInclude(result)
 
         // Should include posts with a where filter
         expect(include).toBeDefined()
@@ -452,7 +454,7 @@ describe('Relationship Access Control', () => {
     })
 
     describe('session-based access for relationships', () => {
-      it('should apply session-based access to relationships (via buildIncludeWithAccessControl)', async () => {
+      it('should apply session-based access to relationships (via buildAccessScopedInclude)', async () => {
         const config: OpenSaasConfig = {
           db: {
             provider: 'postgresql',
@@ -487,19 +489,19 @@ describe('Relationship Access Control', () => {
           },
         }
 
-        // Test that buildIncludeWithAccessControl creates session-based where clause
-        const { buildIncludeWithAccessControl, toPrismaInclude } =
-          await import('../src/access/index.js')
+        // Test that buildAccessScopedInclude creates session-based where clause
+        const { buildAccessScopedInclude } = await import('../src/access/index.js')
 
-        const result = await buildIncludeWithAccessControl(
+        const include = await buildAccessScopedInclude(
+          { posts: true },
           config.lists.User.fields,
           {
             session: { userId: '1' },
             context: mockContext,
           },
           config,
+          'User',
         )
-        const include = toPrismaInclude(result)
 
         // Should include posts with session-based where filter
         expect(include).toBeDefined()

package/tests/computed-field-selective-evaluation.test.ts

@@ -0,0 +1,418 @@
+import { describe, it, expect, vi } from 'vitest'
+import { getContext } from '../src/context/index.js'
+import { config, list } from '../src/config/index.js'
+import { text, integer, relationship, virtual } from '../src/fields/index.js'
+import { defineFragment } from '../src/query/index.js'
+import type { FieldConfig } from '../src/config/types.js'
+
+/**
+ * Coverage for issue #855 / ADR-0027: a computed field — any field carrying a
+ * `resolveOutput` hook, virtual or not — is computed if and only if the read
+ * is going to return it, its declared relations (`needs`, ADR-0025) are
+ * fetched under exactly that same condition, and no computed field ever sees
+ * another computed field's resolved output.
+ *
+ * `tests/needs-declared-dependencies.test.ts` covers ADR-0025 itself (fetch
+ * folding, access scoping of a declared relation); this file covers the
+ * selectivity ADR-0027 adds on top of it.
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function createMockPrisma(): any {
+  const model = () => ({
+    findFirst: vi.fn(),
+    findMany: vi.fn(),
+  })
+  return { order: model(), lineItem: model(), product: model() }
+}
+
+function buildTestConfig(spies: {
+  totalHook: ReturnType<typeof vi.fn>
+  doubleTotalHook: ReturnType<typeof vi.fn>
+  secretAccess: ReturnType<typeof vi.fn>
+  secretHook: ReturnType<typeof vi.fn>
+  unreachableAccess: ReturnType<typeof vi.fn>
+  unreachableHook: ReturnType<typeof vi.fn>
+  summaryHook: ReturnType<typeof vi.fn>
+  hooklessAccess: ReturnType<typeof vi.fn>
+  peekerHook: ReturnType<typeof vi.fn>
+}) {
+  return config({
+    db: { provider: 'postgresql', url: 'postgresql://localhost:5432/test' },
+    lists: {
+      Product: list({
+        fields: { name: text() },
+        access: { operation: { query: () => true } },
+      }),
+      LineItem: list({
+        fields: {
+          price: integer(),
+          order: relationship({ ref: 'Order.lineItems' }),
+          product: relationship({ ref: 'Product' }),
+          summary: virtual({
+            type: 'string',
+            needs: ['product'],
+            hooks: {
+              resolveOutput: (hookArgs: unknown) => {
+                spies.summaryHook(hookArgs)
+                const typedItem = (hookArgs as { item: { product?: { name?: string } | null } })
+                  .item
+                return typedItem.product ? `${typedItem.product.name} x1` : 'unknown product x1'
+              },
+            },
+          }),
+        },
+        access: { operation: { query: () => true } },
+      }),
+      Order: list({
+        fields: {
+          title: text(),
+          lineItems: relationship({ ref: 'LineItem.order', many: true }),
+          total: virtual({
+            type: 'number',
+            needs: ['lineItems'],
+            hooks: {
+              resolveOutput: (hookArgs: unknown) => {
+                spies.totalHook(hookArgs)
+                const typedItem = (hookArgs as { item: { lineItems?: Array<{ price?: number }> } })
+                  .item
+                return (typedItem.lineItems ?? []).reduce((sum, li) => sum + (li.price ?? 0), 0)
+              },
+            },
+          }),
+          // Declares the SAME relation as `total` — exercises "fetched once,
+          // even when only one of the two declaring fields is selected."
+          doubleTotal: virtual({
+            type: 'number',
+            needs: ['lineItems'],
+            hooks: {
+              resolveOutput: (hookArgs: unknown) => {
+                spies.doubleTotalHook(hookArgs)
+                const typedItem = (hookArgs as { item: { lineItems?: Array<{ price?: number }> } })
+                  .item
+                return (typedItem.lineItems ?? []).reduce((sum, li) => sum + (li.price ?? 0), 0) * 2
+              },
+            },
+          }),
+          // A stored field with its own resolveOutput (a "computed field" per
+          // ADR-0027, not only virtual ones) whose access AND hook are spied
+          // on so a fragment that never selects it can be asserted to have
+          // invoked neither.
+          secret: text({
+            access: {
+              read: spies.secretAccess,
+            },
+            hooks: {
+              resolveOutput: (hookArgs: unknown) => {
+                spies.secretHook(hookArgs)
+                return `wrapped:${(hookArgs as { value: unknown }).value}`
+              },
+            },
+          }),
+          // A virtual field never selected by any fragment in these tests —
+          // stands in for "a field the read is never going to return."
+          unreachable: virtual({
+            type: 'string',
+            access: {
+              read: (accessArgs: unknown) => {
+                spies.unreachableAccess(accessArgs)
+                return true
+              },
+            },
+            hooks: {
+              resolveOutput: (hookArgs: unknown) => {
+                spies.unreachableHook(hookArgs)
+                return 'unreachable-value'
+              },
+            },
+          }),
+          // Reads a SIBLING computed field (`secret`) without declaring it —
+          // must see `undefined`, never `secret`'s resolved ("wrapped:...")
+          // value, and never its raw stored value either when `secret` is
+          // skipped by a fragment's own selection.
+          peeker: virtual({
+            type: 'string',
+            hooks: {
+              resolveOutput: (hookArgs: unknown) => {
+                spies.peekerHook(hookArgs)
+                const value = (hookArgs as { item: Record<string, unknown> }).item.secret
+                return value === undefined ? 'saw-nothing' : `saw:${String(value)}`
+              },
+            },
+          }),
+          // A hookless virtual field — can never produce a value on ANY
+          // read. Constructed as a raw FieldConfig (bypassing the `virtual()`
+          // builder, which throws without a `resolveOutput`) the way a
+          // third-party field package might legitimately shape one.
+          hooklessVirtual: {
+            type: 'text',
+            virtual: true,
+            access: {
+              read: (accessArgs: unknown) => {
+                spies.hooklessAccess(accessArgs)
+                return true
+              },
+            },
+            hooks: {},
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any -- minimal raw field config for a test double
+          } as any as FieldConfig,
+        },
+        access: { operation: { query: () => true } },
+      }),
+    },
+  })
+}
+
+function makeSpies() {
+  return {
+    totalHook: vi.fn(),
+    doubleTotalHook: vi.fn(),
+    secretAccess: vi.fn(() => true),
+    secretHook: vi.fn(),
+    unreachableAccess: vi.fn(),
+    unreachableHook: vi.fn(),
+    summaryHook: vi.fn(),
+    hooklessAccess: vi.fn(),
+    peekerHook: vi.fn(),
+  }
+}
+
+describe('a computed field runs only when it is going to be returned (#855, ADR-0027)', () => {
+  it('a fragment that does not select a computed field runs neither its read access nor its hook, and does not fold its needs into the include', async () => {
+    const spies = makeSpies()
+    const testConfig = await buildTestConfig(spies)
+    const mockPrisma = createMockPrisma()
+    mockPrisma.order.findFirst.mockResolvedValue({ id: 'o1', title: 'Order 1' })
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const fragment = defineFragment<any>()({ title: true } as const)
+    const context = getContext(testConfig, mockPrisma, null)
+    const result = await context.db.order.findUnique({ where: { id: 'o1' }, query: fragment })
+
+    // None of the unselected computed fields' declared relations were folded
+    // into the include — `lineItems` is only ever needed by `total`/
+    // `doubleTotal`, neither of which was selected, so there is nothing to
+    // fold and `include` stays exactly `undefined` (the bare-read shape).
+    const callArgs = mockPrisma.order.findFirst.mock.calls[0][0]
+    expect(callArgs.include).toBeUndefined()
+
+    expect(spies.totalHook).not.toHaveBeenCalled()
+    expect(spies.doubleTotalHook).not.toHaveBeenCalled()
+    expect(spies.secretAccess).not.toHaveBeenCalled()
+    expect(spies.secretHook).not.toHaveBeenCalled()
+    expect(spies.unreachableAccess).not.toHaveBeenCalled()
+    expect(spies.unreachableHook).not.toHaveBeenCalled()
+
+    expect(result).toEqual({ title: 'Order 1' })
+  })
+
+  it('a fragment that DOES select a computed field computes it correctly and fetches its declared relation, unchanged', async () => {
+    const spies = makeSpies()
+    const testConfig = await buildTestConfig(spies)
+    const mockPrisma = createMockPrisma()
+    mockPrisma.order.findFirst.mockResolvedValue({
+      id: 'o1',
+      title: 'Order 1',
+      lineItems: [{ id: 'li1', price: 10, orderId: 'o1' }],
+    })
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const fragment = defineFragment<any>()({ title: true, total: true } as const)
+    const context = getContext(testConfig, mockPrisma, null)
+    const result = await context.db.order.findUnique({ where: { id: 'o1' }, query: fragment })
+
+    const callArgs = mockPrisma.order.findFirst.mock.calls[0][0]
+    expect(callArgs.include).toMatchObject({ lineItems: expect.anything() })
+    expect(spies.totalHook).toHaveBeenCalledTimes(1)
+    expect(result?.total).toBe(10)
+    expect(result).not.toHaveProperty('lineItems')
+  })
+
+  it('two fields declaring the same relation, only one selected, still fetch that relation exactly once — and only the selected field computes', async () => {
+    const spies = makeSpies()
+    const testConfig = await buildTestConfig(spies)
+    const mockPrisma = createMockPrisma()
+    mockPrisma.order.findFirst.mockResolvedValue({
+      id: 'o1',
+      title: 'Order 1',
+      lineItems: [{ id: 'li1', price: 10, orderId: 'o1' }],
+    })
+
+    // `doubleTotal` also needs `lineItems` but is NOT selected.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const fragment = defineFragment<any>()({ title: true, total: true } as const)
+    const context = getContext(testConfig, mockPrisma, null)
+    const result = await context.db.order.findUnique({ where: { id: 'o1' }, query: fragment })
+
+    expect(mockPrisma.order.findFirst).toHaveBeenCalledTimes(1)
+    const callArgs = mockPrisma.order.findFirst.mock.calls[0][0]
+    // Exactly one `lineItems` entry in the include — folded once for `total`.
+    expect(Object.keys(callArgs.include)).toEqual(['lineItems'])
+
+    expect(result?.total).toBe(10)
+    expect(spies.totalHook).toHaveBeenCalledTimes(1)
+    expect(spies.doubleTotalHook).not.toHaveBeenCalled()
+  })
+
+  it('nested level: a nested fragment selecting a subset computes only that subset', async () => {
+    const spies = makeSpies()
+    const testConfig = await buildTestConfig(spies)
+    const mockPrisma = createMockPrisma()
+    mockPrisma.order.findFirst.mockResolvedValue({
+      id: 'o1',
+      title: 'Order 1',
+      lineItems: [{ id: 'li1', price: 10, orderId: 'o1' }],
+    })
+
+    const lineItemFragment = defineFragment<{ price: number }>()({ price: true } as const)
+    const orderFragment = defineFragment<{ title: string; lineItems: unknown[] }>()({
+      title: true,
+      lineItems: lineItemFragment,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } as any)
+
+    const context = getContext(testConfig, mockPrisma, null)
+    const result = await context.db.order.findUnique({
+      where: { id: 'o1' },
+      query: orderFragment,
+    })
+
+    // `summary` (needs `product`) was not selected inside the nested
+    // fragment, so neither its hook ran nor was `product` folded in beneath
+    // `lineItems`.
+    expect(spies.summaryHook).not.toHaveBeenCalled()
+    const callArgs = mockPrisma.order.findFirst.mock.calls[0][0]
+    expect(callArgs.include.lineItems).not.toMatchObject({
+      include: expect.objectContaining({ product: expect.anything() }),
+    })
+    expect(result?.lineItems?.[0]).toEqual({ price: 10 })
+  })
+
+  it('nested level: an include (not a fragment) still computes every computed field, unchanged', async () => {
+    const spies = makeSpies()
+    const testConfig = await buildTestConfig(spies)
+    const mockPrisma = createMockPrisma()
+    mockPrisma.order.findFirst.mockResolvedValue({
+      id: 'o1',
+      title: 'Order 1',
+      lineItems: [{ id: 'li1', price: 10, orderId: 'o1', product: { id: 'p1', name: 'Widget' } }],
+    })
+
+    const context = getContext(testConfig, mockPrisma, null)
+    const result = await context.db.order.findUnique({
+      where: { id: 'o1' },
+      include: { lineItems: { include: { product: true } } },
+    })
+
+    expect(spies.summaryHook).toHaveBeenCalledTimes(1)
+    expect(result?.lineItems?.[0].summary).toBe('Widget x1')
+  })
+
+  it("a hook's item never carries another computed field's resolved output, even on a bare read where both survive", async () => {
+    const spies = makeSpies()
+    const testConfig = await buildTestConfig(spies)
+    const mockPrisma = createMockPrisma()
+    mockPrisma.order.findFirst.mockResolvedValue({ id: 'o1', title: 'Order 1', secret: 'hunter2' })
+
+    const context = getContext(testConfig, mockPrisma, null)
+    // Bare read: every computed field computes, including `secret` (a stored
+    // field with its own resolveOutput) and `peeker` (a virtual field with no
+    // `needs` at all, reading `item.secret` without declaring it). `secret`
+    // is a plain stored scalar column, always fetched on any read (ADR-0024)
+    // regardless of declarations — only RELATIONS are conditionally fetched.
+    const result = await context.db.order.findUnique({ where: { id: 'o1' } })
+
+    // `secret`'s OWN resolveOutput wraps its stored value for the caller...
+    expect(result?.secret).toBe('wrapped:hunter2')
+    // ...but `peeker`, reading the same key from its own hook's `item`, sees
+    // the raw STORED column ('hunter2'), never `secret`'s resolved output
+    // ('wrapped:hunter2') — the "no computed field sees another's computed
+    // value" rule, proven by the two hooks disagreeing about the same key.
+    expect(result?.peeker).toBe('saw:hunter2')
+  })
+
+  it("a skipped field's key is absent from a sibling hook's item, never present holding its raw stored value", async () => {
+    const spies = makeSpies()
+    const testConfig = await buildTestConfig(spies)
+    const mockPrisma = createMockPrisma()
+    mockPrisma.order.findFirst.mockResolvedValue({ id: 'o1', title: 'Order 1', secret: 'hunter2' })
+
+    // `secret` is NOT selected; `peeker` is, and reads `item.secret`.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const fragment = defineFragment<any>()({ title: true, peeker: true } as const)
+    const context = getContext(testConfig, mockPrisma, null)
+    const result = await context.db.order.findUnique({ where: { id: 'o1' }, query: fragment })
+
+    // `secret`'s own access/hook never ran (it was never going to be returned).
+    expect(spies.secretAccess).not.toHaveBeenCalled()
+    expect(spies.secretHook).not.toHaveBeenCalled()
+    // `peeker` sees the key absent, never the raw pre-hook stored value.
+    expect(result?.peeker).toBe('saw-nothing')
+    expect(result).not.toHaveProperty('secret')
+  })
+
+  it('field-level read access still gates a field that IS selected: denied means absent and its hook does not run', async () => {
+    const spies = makeSpies()
+    spies.secretAccess.mockImplementation(() => false)
+    const testConfigDenied = await buildTestConfig(spies)
+    const mockPrisma = createMockPrisma()
+    mockPrisma.order.findFirst.mockResolvedValue({ id: 'o1', title: 'Order 1', secret: 'hunter2' })
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const fragment = defineFragment<any>()({ title: true, secret: true } as const)
+    const context = getContext(testConfigDenied, mockPrisma, null)
+    const result = await context.db.order.findUnique({ where: { id: 'o1' }, query: fragment })
+
+    expect(spies.secretAccess).toHaveBeenCalled()
+    expect(spies.secretHook).not.toHaveBeenCalled()
+    expect(result?.secret).toBeUndefined()
+  })
+
+  it('a hookless virtual field does no work at all — its read access is never invoked on any read', async () => {
+    const spies = makeSpies()
+    const testConfig = await buildTestConfig(spies)
+    const mockPrisma = createMockPrisma()
+    mockPrisma.order.findFirst.mockResolvedValue({ id: 'o1', title: 'Order 1' })
+    mockPrisma.order.findMany.mockResolvedValue([{ id: 'o1', title: 'Order 1' }])
+
+    const context = getContext(testConfig, mockPrisma, null)
+
+    // Bare read.
+    await context.db.order.findUnique({ where: { id: 'o1' } })
+    expect(spies.hooklessAccess).not.toHaveBeenCalled()
+
+    // include-based read naming it explicitly.
+    await context.db.order.findUnique({ where: { id: 'o1' }, include: { hooklessVirtual: true } })
+    expect(spies.hooklessAccess).not.toHaveBeenCalled()
+
+    // fragment selecting it explicitly.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const fragment = defineFragment<any>()({ title: true, hooklessVirtual: true } as const)
+    await context.db.order.findUnique({ where: { id: 'o1' }, query: fragment })
+    expect(spies.hooklessAccess).not.toHaveBeenCalled()
+  })
+
+  it('include/bare reads still return every computed field on the list, unchanged', async () => {
+    const spies = makeSpies()
+    const testConfig = await buildTestConfig(spies)
+    const mockPrisma = createMockPrisma()
+    mockPrisma.order.findMany.mockResolvedValue([
+      {
+        id: 'o1',
+        title: 'Order 1',
+        secret: 'hunter2',
+        lineItems: [{ id: 'li1', price: 10, orderId: 'o1' }],
+      },
+    ])
+
+    const context = getContext(testConfig, mockPrisma, null)
+    const result = await context.db.order.findMany({})
+
+    expect(result[0].total).toBe(10)
+    expect(result[0].doubleTotal).toBe(20)
+    expect(result[0].secret).toBe('wrapped:hunter2')
+    expect(spies.totalHook).toHaveBeenCalledTimes(1)
+    expect(spies.doubleTotalHook).toHaveBeenCalledTimes(1)
+    expect(spies.secretHook).toHaveBeenCalledTimes(1)
+  })
+})

package/tests/context.test.ts

@@ -1427,6 +1427,33 @@ describe('getContext', () => {
         expect(call.include).toEqual({ posts: true })
       })
 
+      // Core new guarantee introduced by #852 / ADR-0026: naming one relation
+      // no longer walks (and access-checks) every other relationship of the
+      // list. Before this fix, `include: { posts: true }` would ALSO evaluate
+      // `Secret`'s query access (and, one hop further, `Comment`'s) even
+      // though the caller never named `secrets` — wasted access calls the
+      // caller never asked to pay for. Asserted directly on the access
+      // function, not just on the resulting include shape.
+      it('does not invoke query access on a relation the caller did not name (#852)', async () => {
+        const postQuerySpy = vi.fn(() => ({ status: { equals: 'published' } }))
+        const secretQuerySpy = vi.fn(() => false)
+        const spiedConfig: OpenSaasConfig = {
+          ...relConfig,
+          lists: {
+            ...relConfig.lists,
+            Post: { ...relConfig.lists.Post, access: { operation: { query: postQuerySpy } } },
+            Secret: { ...relConfig.lists.Secret, access: { operation: { query: secretQuerySpy } } },
+          },
+        }
+        relPrisma.author.findMany.mockResolvedValue([{ id: 'a1', name: 'Jo', posts: [] }])
+
+        const context = await getContext(spiedConfig, relPrisma, null)
+        await context.db.author.findMany({ include: { posts: true } })
+
+        expect(postQuerySpy).toHaveBeenCalledTimes(1)
+        expect(secretQuerySpy).not.toHaveBeenCalled()
+      })
+
       // Regression for issue #830: a read issued from inside a `resolveOutput`
       // hook used to lose relation row scoping ENTIRELY — `buildIncludeWithAccessControl`
       // returned a whole-object `undefined` for the inner read (any

package/tests/field-types.test.ts

@@ -761,6 +761,18 @@ describe('Field Types', () => {
         expect(field.ref).toBe('Post.author')
         expect(field.many).toBe(true)
       })
+
+      test('accepts db.isNullable on a single relationship', () => {
+        const field = relationship({ ref: 'User.posts', db: { isNullable: false } })
+
+        expect(field.db?.isNullable).toBe(false)
+      })
+
+      test('throws error when db.isNullable is used with many: true', () => {
+        expect(() => {
+          relationship({ ref: 'Post.author', many: true, db: { isNullable: false } })
+        }).toThrow('db.isNullable can only be used on single relationships')
+      })
     })
   })
 

package/tests/needs-declared-dependencies.test.ts

@@ -294,11 +294,14 @@ describe('a computed field declares the relations it needs (#850, ADR-0025)', ()
     expect(result).toHaveProperty('title')
   })
 
-  it('a declaration cycle across two lists terminates via the existing relationship-graph cycle guard (ADR-0026 note)', async () => {
+  it("a declaration cycle across two lists terminates via the declaration fold's own cycle guard (ADR-0026 note)", async () => {
     // Order.total needs lineItems; LineItem.orderTitle needs order — a
-    // two-list declaration cycle. This must not hang or crash: it rides the
-    // SAME `visitedLists` cycle guard `buildIncludeWithAccessControl` already
-    // uses for the relationship graph, not a separate mechanism.
+    // two-list declaration cycle. This must not hang or crash: it rides
+    // `foldDeclaredDependencies`'s own `visitedLists` cycle guard — the same
+    // list-name-path mechanism the pre-ADR-0026 relationship-graph auto-walk
+    // used, re-pointed at the declaration fold now that nothing walks the
+    // relationship graph unprompted (defense in depth; the primary backstop
+    // is `validateNeedsClosureDepth` at generate time, see needs-closure.ts).
     const testConfig = await buildTestConfig({ withDeclarationCycle: true })
     const mockPrisma = createMockPrisma()
     mockPrisma.order.findMany.mockResolvedValue([