@opensaas/stack-core 0.39.2 → 0.40.0

package/src/access/field-access.ts

@@ -1,10 +1,12 @@
 import type { Session, AccessContext } from './types.js'
 import type { FieldAccess, FieldAccessControl } from './types.js'
+import type { OpenSaasConfig } from '../config/types.js'
 // `ValidationError` is referenced only inside function bodies (call-time), never
 // at module-evaluation time, so the field-access ⇄ hooks import cycle is safe
 // under ESM live bindings.
 import { ValidationError } from '../hooks/index.js'
 import { InvalidFieldAccessResultError } from './errors.js'
+import { resolveSyntheticReverseRelation } from './engine.js'
 
 /**
  * Marks a throw caused by touching {@link createPoisonedItem}'s `item`, as
@@ -196,6 +198,17 @@ export async function filterWritableFields<T extends Record<string, unknown>>(
     item?: Record<string, unknown>
     context: AccessContext & { _isSudo?: boolean }
     inputData?: Record<string, unknown>
+    /**
+     * The list being written and the full config — used ONLY to recognise a
+     * synthetic reverse-relation key (`from_<List>_<field>`, #978) among the
+     * undeclared keys sudo would otherwise pass through unchecked. Both
+     * production call sites (the write pipeline, nested-operations) supply
+     * these; a direct unit test that omits them keeps the pre-#978 sudo
+     * behaviour of passing any undeclared key through, since it has no config
+     * to resolve a synthetic key against.
+     */
+    listName?: string
+    config?: OpenSaasConfig
   },
 ): Promise<Partial<T>> {
   const filtered: Record<string, unknown> = {}
@@ -286,10 +299,29 @@ export async function filterWritableFields<T extends Record<string, unknown>>(
     // declares (e.g. back-relations like `from_Enrolment_student`), so allowing
     // an undeclared key to pass through lets a non-sudo caller drive ungated
     // nested writes on undeclared back-relations. Mirror Keystone's
-    // GraphQL-schema behaviour and reject it. `sudo` is the single trusted
-    // bypass, so undeclared keys still pass through under sudo.
+    // GraphQL-schema behaviour and reject it.
     if (!fieldConfig) {
       if (isSudo) {
+        // #978 — sudo bypasses ACCESS CONTROL, not the hooks/validation a
+        // recognised relation is entitled to. A synthetic reverse-relation key
+        // (a list-only ref's back-relation) is handed to the caller unchanged
+        // so processNestedOperations can run its target list's full pipeline,
+        // exactly as it would for a declared relationship field. Any other
+        // undeclared key has no such route to hooks — passing it straight to
+        // Prisma is the same silent-bypass shape this issue closed for
+        // relations, so it is refused even under sudo. `listName`/`config`
+        // are omitted only by direct unit tests of this function, which keep
+        // the pre-#978 blanket sudo passthrough since they have no config to
+        // resolve a synthetic key against.
+        if (args.listName && args.config) {
+          const synthetic = resolveSyntheticReverseRelation(fieldName, args.listName, args.config)
+          if (!synthetic) {
+            throw new ValidationError([
+              `Cannot ${operation} "${fieldName}": it is not a field of this list. ` +
+                `Undeclared data keys are rejected, even under sudo.`,
+            ])
+          }
+        }
         filtered[fieldName] = value
         continue
       }

package/src/access/field-visibility.ts

@@ -7,6 +7,8 @@ import { ResolveOutputCycleError } from './errors.js'
 import type { DeclaredOnlyTree } from './declared-dependencies.js'
 import { emptyDeclaredOnlyTree } from './declared-dependencies.js'
 import type { FieldSelectionScope } from '../query/index.js'
+import type { ToOneAccessVisibilityTree } from './access-filter.js'
+import { emptyToOneAccessVisibilityTree } from './access-filter.js'
 // NOTE: `context/index.ts` imports `filterReadableFields` from this module
 // (via the `access/index.ts` barrel) — this is an intentional cyclic
 // dependency, the same shape and for the same reason as the one documented in
@@ -36,6 +38,22 @@ import { buildDbDelegate } from '../context/index.js'
  * Phase 1 (pre-query row/relation scoping) lives in `access-filter.ts`. See
  * `docs/adr/0001-access-control-is-a-two-phase-read.md` and the access-control
  * glossary in `CONTEXT.md`.
+ *
+ * **To-one relation nulling (issue #974).** A to-one relation whose related
+ * list's `query` access resolves to a filter cannot be scoped by Prisma's own
+ * `where` (it only accepts one on a to-many include — see the "To-one
+ * relations" section of `access-filter.ts`'s module doc), so
+ * `buildAccessScopedInclude` fetches it unscoped and hands this module a
+ * `ToOneAccessVisibilityTree` — already resolved, via one batched existence
+ * check per relation across the whole read, by
+ * `resolveToOneAccessVisibility`. This module is where that resolution
+ * actually becomes the caller-visible `null`: a `kind: 'denied'` key is
+ * forced to `null` even though it was never fetched at all (the key is
+ * absent from `workingItem`), and a `kind: 'visible'` key's fetched row is
+ * nulled out unless its id survived the existence check — in both branches,
+ * before any field-level access check or `resolveOutput` hook runs, so the
+ * rest of the pipeline sees exactly what a denied to-one read has always
+ * meant elsewhere: `null`, never a thrown error.
  */
 
 type ResolveOutputHookRuntime = (args: {
@@ -193,6 +211,11 @@ export async function filterReadableFields<T extends Record<string, unknown>>(
   // The fragment scope this level was reached under (ADR-0027, see module doc
   // above), and the same tree one level down for each nested relation.
   selection?: FieldSelectionScope,
+  // Resolved to-one existence checks at THIS level (issue #974, see module
+  // doc above), and the same tree one level down for each nested relation —
+  // regardless of that relation's own arity, since a filtered to-one can sit
+  // beneath a to-many hop.
+  toOneVisibility: ToOneAccessVisibilityTree = emptyToOneAccessVisibilityTree(),
 ): Promise<Partial<T>> {
   const filtered: Record<string, unknown> = {}
 
@@ -286,6 +309,15 @@ export async function filterReadableFields<T extends Record<string, unknown>>(
       // unrestricted — matching what naming a relation without narrowing it
       // further has always meant.
       const nestedSelection = selection?.nested[fieldName]
+      // This relation's own resolved to-one visibility, if
+      // `buildAccessScopedInclude` flagged anything beneath it (issue #974).
+      // Falls back to empty — the common case for a relation with no
+      // filtered to-one anywhere in its own nested include.
+      const nestedToOneVisibility =
+        toOneVisibility.nested[fieldName] ?? emptyToOneAccessVisibilityTree()
+      // This key's OWN to-one existence check, if `fieldName` itself is a
+      // filtered to-one relation (as opposed to one further down its tree).
+      const toOneEntry = toOneVisibility.filters[fieldName]
 
       if (relatedConfig) {
         if (Array.isArray(value)) {
@@ -300,20 +332,28 @@ export async function filterReadableFields<T extends Record<string, unknown>>(
                 relatedConfig.listName,
                 nestedDeclaredOnly,
                 nestedSelection,
+                nestedToOneVisibility,
               ),
             ),
           )
         } else if (typeof value === 'object') {
-          filtered[fieldName] = await filterReadableFields(
-            value as Record<string, unknown>,
-            relatedConfig.listConfig.fields,
-            args,
-            config,
-            depth + 1,
-            relatedConfig.listName,
-            nestedDeclaredOnly,
-            nestedSelection,
-          )
+          const relatedId = (value as Record<string, unknown>).id
+          const isVisible =
+            !toOneEntry || toOneEntry.kind !== 'visible' || toOneEntry.ids.has(String(relatedId))
+
+          filtered[fieldName] = isVisible
+            ? await filterReadableFields(
+                value as Record<string, unknown>,
+                relatedConfig.listConfig.fields,
+                args,
+                config,
+                depth + 1,
+                relatedConfig.listName,
+                nestedDeclaredOnly,
+                nestedSelection,
+                nestedToOneVisibility,
+              )
+            : null
         }
       } else {
         filtered[fieldName] = value
@@ -341,6 +381,31 @@ export async function filterReadableFields<T extends Record<string, unknown>>(
     }
   }
 
+  // To-one relations `buildAccessScopedInclude` denied outright (issue #974)
+  // were never asked of Prisma at all, so `fieldName` has no entry in
+  // `workingItem` and the loop above never visits it. Force it present as an
+  // explicit `null` here — matching what a denied single-record read means
+  // everywhere else in the context — rather than leaving the key silently
+  // absent.
+  for (const [fieldName, entry] of Object.entries(toOneVisibility.filters)) {
+    if (entry.kind !== 'denied') continue
+    if (fieldName in filtered || fieldName in workingItem) continue
+    if (selection?.fields && !selection.fields.has(fieldName)) continue
+
+    const fieldConfig = fieldConfigs[fieldName]
+    const canRead = await checkFieldAccess(fieldConfig?.access, 'read', {
+      ...args,
+      item: workingItem,
+    })
+
+    if (!canRead) {
+      accessDeniedKeys.add(fieldName)
+      continue
+    }
+
+    filtered[fieldName] = null
+  }
+
   // The item a virtual field's hook sees: stored columns and fetched
   // relations (from `workingItem`, never a resolved value — no hook's output
   // is ever written back into `workingItem`). A key is visible here if it

package/src/access/index.ts

@@ -14,11 +14,14 @@ export type {
 // Operation-level access primitives and shared ref-parsing helper.
 export {
   checkAccess,
+  checkCreateAccess,
   mergeFilters,
   isBoolean,
   isPrismaFilter,
   getRelatedListConfig,
+  resolveSyntheticReverseRelation,
 } from './engine.js'
+export type { SyntheticReverseRelation } from './engine.js'
 // Canonical field-level access evaluation (shared by read and write paths).
 export {
   checkFieldAccess,
@@ -36,6 +39,15 @@ export {
   buildAccessScopedInclude,
   buildAccessScopedWhere,
   stripVirtualFieldsFromInclude,
+  resolveToOneAccessVisibility,
+  emptyToOneAccessFilterTree,
+  emptyToOneAccessVisibilityTree,
+} from './access-filter.js'
+export type {
+  ToOneAccessFilterTree,
+  ToOneAccessFilterEntry,
+  ToOneAccessVisibilityTree,
+  ToOneVisibility,
 } from './access-filter.js'
 // Phase 2 — Field Visibility (post-query field stripping + resolveOutput).
 export { filterReadableFields } from './field-visibility.js'
@@ -53,5 +65,7 @@ export { AccessScopeDepthExceededError } from './errors.js'
 export { ResolveOutputCycleError } from './errors.js'
 // Thrown when a field-level access control function returns a non-boolean result.
 export { InvalidFieldAccessResultError } from './errors.js'
+// Thrown when operation-level `create` access control returns a non-boolean result (#1009).
+export { InvalidCreateAccessResultError } from './errors.js'
 // Thrown when a relation filter's related list denies query access outright (#916).
 export { RelationFilterAccessDeniedError } from './errors.js'

package/src/config/types.ts

@@ -591,6 +591,32 @@ export type BaseFieldConfig<TTypeInfo extends TypeInfo> = {
      * ```
      */
     description?: string
+    /**
+     * Whether this field belongs in a list/related-list table's DEFAULT
+     * column set (issue #1018) — the columns shown when nothing explicitly
+     * names them (`ui.listView.initialColumns` on the list, or a
+     * relationship's own `ui.itemView.columns`). Naming the field explicitly
+     * in either of those always shows it regardless of this flag; it governs
+     * only what appears absent an explicit column list.
+     *
+     * This is a PRESENTATION default, not an access control — a field can be
+     * read-denied and still default to `true` here (it simply renders empty
+     * for a viewer who can't read it), and setting this to `false` hides a
+     * column without restricting who can read the underlying value. The
+     * field-level `access.read` deny remains the only real boundary.
+     *
+     * @default true
+     *
+     * @example Hide an internal field from default table views without denying read access
+     * ```typescript
+     * fields: {
+     *   internalScore: integer({ ui: { listView: { defaultColumn: false } } }),
+     * }
+     * ```
+     */
+    listView?: {
+      defaultColumn?: boolean
+    }
     /**
      * Transform field value before sending to client (browser)
      * Useful for sensitive fields (e.g., passwords) or complex data structures
@@ -844,6 +870,7 @@ export type IntegerField<TTypeInfo extends TypeInfo = TypeInfo> = BaseFieldConfi
     min?: number
     max?: number
   }
+  isIndexed?: boolean | 'unique'
 }
 
 export type DecimalField<TTypeInfo extends TypeInfo = TypeInfo> = BaseFieldConfig<TTypeInfo> & {
@@ -885,6 +912,7 @@ export type CheckboxField<TTypeInfo extends TypeInfo = TypeInfo> = BaseFieldConf
 export type TimestampField<TTypeInfo extends TypeInfo = TypeInfo> = BaseFieldConfig<TTypeInfo> & {
   type: 'timestamp'
   defaultValue?: { kind: 'now' } | Date
+  isIndexed?: boolean | 'unique'
 }
 
 export type CalendarDayField<TTypeInfo extends TypeInfo = TypeInfo> = BaseFieldConfig<TTypeInfo> & {
@@ -989,6 +1017,7 @@ export type SelectField<TTypeInfo extends TypeInfo = TypeInfo> = BaseFieldConfig
   validation?: {
     isRequired?: boolean
   }
+  isIndexed?: boolean | 'unique'
   ui?: {
     displayMode?: 'select' | 'segmented-control' | 'radio'
   }
@@ -1015,8 +1044,10 @@ export type RelationshipItemViewConfig = {
    * The related list's fields to show as Relationship-table columns, in order.
    *
    * When omitted, the columns default to the related list's own column
-   * curation (`ui.listView.initialColumns`, else all non-system fields) minus
-   * the back-reference field that points at the parent record.
+   * curation (`ui.listView.initialColumns`, else every field whose own
+   * `ui.listView.defaultColumn` declaration holds — see {@link
+   * BaseFieldConfig.ui}) minus the back-reference field that points at the
+   * parent record.
    *
    * @example
    * ```typescript
@@ -1133,13 +1164,20 @@ export type RelationshipField<TTypeInfo extends TypeInfo = TypeInfo> =
        */
       isNullable?: boolean
       /**
-       * Controls foreign key placement and column name for bidirectional relationships
-       * Can be a boolean or an object with a map property
-       * Only valid on single (non-many) relationships
-       * Cannot be true on both sides of a one-to-one relationship
+       * Controls foreign key placement and column name.
+       * Can be a boolean or an object with a map property.
+       * Only valid on single (non-many) relationships.
+       * Cannot be true on both sides of a one-to-one relationship.
        *
-       * When a boolean, defaults the foreign key column name to the field name
-       * When an object with map, uses the provided column name
+       * The boolean form (the "which side owns the foreign key" sense) is only
+       * meaningful on a bidirectional ref (`ref: 'ListName.fieldName'`) — a
+       * list-only ref (`ref: 'ListName'`) always owns the foreign key, so a
+       * boolean here is rejected. The `{ map }` form (the column-name sense)
+       * works on both: it renames the foreign key column without changing
+       * ownership.
+       *
+       * When a boolean, defaults the foreign key column name to the field name.
+       * When an object with map, uses the provided column name.
        *
        * @example
        * ```typescript
@@ -1164,6 +1202,14 @@ export type RelationshipField<TTypeInfo extends TypeInfo = TypeInfo> =
        *     user: relationship({ ref: 'User.account' }) // No foreign key on this side
        *   }
        * })
+       *
+       * // List-only ref: rename the foreign key column (ownership is implicit)
+       * Post: list({
+       *   fields: {
+       *     category: relationship({ ref: 'Category', db: { foreignKey: { map: 'category_id' } } })
+       *     // Generates: categoryId String? @map("category_id")
+       *   }
+       * })
        * ```
        */
       foreignKey?: boolean | { map?: string }
@@ -1488,6 +1534,18 @@ export interface TypeInfo<
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type OperationAccess<T = any> = {
   query?: AccessControl<T>
+  /**
+   * Shares `AccessControl`'s signature (so a filter still type-checks here),
+   * but at runtime `create` accepts a `boolean` result only. There is no
+   * existing row to scope with a filter, and — unlike `update`/`delete`,
+   * which re-check a returned filter against the target row via
+   * `findFirst` — no equivalent re-check exists for a row that doesn't exist
+   * in the database yet. A rule that returns a filter (or any other
+   * non-boolean) throws `InvalidCreateAccessResultError` rather than being
+   * treated as an allow (see #1009, ADR-0022, ADR-0030). To scope create by
+   * ownership, evaluate the condition in a `resolveInput`/`validate` hook,
+   * where the input data is in scope.
+   */
   create?: AccessControl<T>
   update?: AccessControl<T>
   delete?: AccessControl<T>
@@ -1975,6 +2033,12 @@ export type ListConfig<TTypeInfo extends TypeInfo> = {
      * the bad field too — no entry is ever silently dropped or emitted as
      * invalid Prisma.
      *
+     * `createdAt`/`updatedAt` are a valid entry even when the list has no
+     * matching declared field — an entry may name either as long as the
+     * list's auto-timestamps (`db.timestamps`, global or per-list) are
+     * enabled for that column, since the auto-injected column has no `@map`
+     * of its own and its Prisma field name is exactly `createdAt`/`updatedAt`.
+     *
      * @example One audition per student per production (composite unique)
      * ```typescript
      * Audition: list({
@@ -2241,14 +2305,16 @@ export interface BulkAction {
  * `ui.listView`.
  *
  * When omitted, the admin UI falls back to its existing defaults: every
- * non-system field is shown as a column and no default sort is applied.
+ * field whose own `ui.listView.defaultColumn` declaration holds is shown as
+ * a column (see {@link BaseFieldConfig.ui}) and no default sort is applied.
  */
 export type ListViewUIConfig = {
   /**
    * The fields to show as columns in the list table, in order.
    *
    * Drives both the column **selection** and their **order**. When omitted,
-   * all non-system fields are shown (current default behaviour).
+   * every field whose own `ui.listView.defaultColumn` declaration holds is
+   * shown (current default behaviour).
    *
    * @example
    * ```typescript

package/src/context/index.ts

@@ -10,10 +10,13 @@ import {
   foldDeclaredDependencies,
   validateQueryKeys,
   validateQueryFieldReadAccess,
+  resolveToOneAccessVisibility,
+  emptyToOneAccessFilterTree,
 } from '../access/index.js'
-import type { DeclaredOnlyTree } from '../access/index.js'
+import type { DeclaredOnlyTree, ToOneAccessFilterTree } from '../access/index.js'
 import { ValidationError, DatabaseError } from '../hooks/index.js'
 import { getDbKey } from '../lib/case-utils.js'
+import { uniqueConstraintOf } from '../lib/prisma-errors.js'
 import type { PrismaClientLike } from '../access/types.js'
 import { buildInclude, pickFields, isFragment, buildFieldSelectionScope } from '../query/index.js'
 import type { FieldSelection, FieldSelectionScope } from '../query/index.js'
@@ -202,6 +205,14 @@ function getDefaultData(listConfig: ListConfig<any>): Record<string, unknown> {
   return data
 }
 
+// A camelCase field name (e.g. a relationship's `tenantId` foreign key) needs
+// its word boundary split before title-casing, or it reads as one run-together
+// word ("Tenantid") in a user-facing unique-constraint message.
+function humanizeFieldName(fieldName: string): string {
+  const spaced = fieldName.replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+  return spaced.charAt(0).toUpperCase() + spaced.slice(1)
+}
+
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
 function parsePrismaError(error: unknown, listConfig: ListConfig<any>): Error {
   if (
@@ -215,22 +226,22 @@ function parsePrismaError(error: unknown, listConfig: ListConfig<any>): Error {
 
     // P2002 is Prisma's unique constraint violation code.
     if (prismaError.code === 'P2002') {
-      const target = prismaError.meta?.target
+      const target = uniqueConstraintOf(prismaError)?.fields
       const fieldErrors: Record<string, string> = {}
 
-      if (target && Array.isArray(target)) {
+      if (target && target.length > 0) {
         for (const fieldName of target) {
           const fieldConfig = listConfig.fields[fieldName]
-          const label = fieldName.charAt(0).toUpperCase() + fieldName.slice(1)
 
           if (fieldConfig) {
-            fieldErrors[fieldName] = `This ${label.toLowerCase()} is already in use`
+            fieldErrors[fieldName] =
+              `This ${humanizeFieldName(fieldName).toLowerCase()} is already in use`
           } else {
             fieldErrors[fieldName] = `This value is already in use`
           }
         }
 
-        const fieldLabels = target.map((f) => f.charAt(0).toUpperCase() + f.slice(1)).join(', ')
+        const fieldLabels = target.map(humanizeFieldName).join(', ')
         return new DatabaseError(
           `${fieldLabels} must be unique. The value you entered is already in use.`,
           fieldErrors,
@@ -293,7 +304,8 @@ interface TransactionCapable<TPrisma> {
  *
  * Exposes the secured `db` delegate plus the session, raw `prisma`, storage,
  * plugin services, the generic `serverAction` handler, `sudo()` (bypasses access
- * control but still runs hooks), and `transaction()` (interactive, hook-firing
+ * control but still runs hooks), `withSession()` (substitutes the session but
+ * still runs access control), and `transaction()` (interactive, hook-firing
  * transaction). All access-checked operations run their list/field hooks.
  */
 export interface StackContext<TPrisma extends PrismaClientLike = PrismaClientLike> {
@@ -329,6 +341,23 @@ export interface StackContext<TPrisma extends PrismaClientLike = PrismaClientLik
     options?: TransactionOptions,
   ) => Promise<T>
   sudo: () => StackContext<TPrisma>
+  /**
+   * Derive a context identical to this one except for its session, reusing
+   * the already-resolved config and this context's own client (including a
+   * transaction client — a call inside `context.transaction()` stays in that
+   * transaction) and storage.
+   *
+   * **This is not an authorisation.** It substitutes who hooks and access
+   * control see; it does not change what they decide. The derived context
+   * can do exactly what any context built with `session` directly could
+   * do — access rules still evaluate against the new session. The caller is
+   * responsible for deciding who may invoke this.
+   *
+   * Orthogonal to `sudo()`: `withSession(s)` preserves the receiver's sudo
+   * state (elevated stays elevated), so `context.withSession(s).sudo()` and
+   * `context.sudo().withSession(s)` are equivalent.
+   */
+  withSession: (session: Session | null) => StackContext<TPrisma>
   _isSudo: boolean
 }
 
@@ -765,6 +794,22 @@ export function getContext<
     )
   }
 
+  // Substitutes the session; access control and hooks still run against it
+  // (orthogonal to `sudo`, so the receiver's sudo state is preserved).
+  function withSession(newSession: Session | null): StackContext<TPrisma> {
+    return getContext(
+      config,
+      prisma,
+      newSession,
+      context.storage,
+      _isSudo,
+      undefined,
+      // ADR-0028: a write issued from inside an owned transaction (e.g.
+      // `tx.withSession(s).db.x.create()`) must still defer to that owner.
+      context._transactionOwner,
+    )
+  }
+
   // Interactive, hook-firing transaction (#614). See the `transaction` doc on
   // `StackContext` above for the atomicity/isolation/retry contract.
   //
@@ -831,6 +876,7 @@ export function getContext<
     plugins: context.plugins,
     serverAction,
     sudo,
+    withSession,
     transaction,
     _isSudo,
   }
@@ -924,6 +970,12 @@ export function buildDbDelegate<TPrisma extends PrismaClientLike>(
  * `undefined` for every non-fragment path: a caller `include` (sudo or not)
  * and a bare read both mean "compute every field," matching what they
  * already fetch.
+ *
+ * Also returns `toOneAccessFilters` — the to-one relations `buildAccessScopedInclude`
+ * flagged as needing a post-query existence check rather than a Prisma-side
+ * `where` (issue #974). Only the non-sudo caller-include path can produce a
+ * non-empty tree: it's the only path that evaluates a related list's `query`
+ * access at all. The fragment and sudo paths always return an empty tree.
  */
 async function resolveReadInclude(
   callerInclude: Record<string, unknown> | undefined,
@@ -937,6 +989,7 @@ async function resolveReadInclude(
   include: Record<string, unknown> | undefined
   declaredOnly: DeclaredOnlyTree
   selection: FieldSelectionScope | undefined
+  toOneAccessFilters: ToOneAccessFilterTree
 }> {
   if (fragmentFields !== undefined) {
     const fragmentInclude = buildInclude(fragmentFields) ?? undefined
@@ -949,27 +1002,27 @@ async function resolveReadInclude(
       [listName],
       selection,
     )
-    return { ...folded, selection }
+    return { ...folded, selection, toOneAccessFilters: emptyToOneAccessFilterTree() }
   }
 
   if (context._isSudo) {
     const folded = foldDeclaredDependencies(callerInclude, listConfig.fields, config, listName)
-    return { ...folded, selection: undefined }
+    return { ...folded, selection: undefined, toOneAccessFilters: emptyToOneAccessFilterTree() }
   }
 
   const folded = foldDeclaredDependencies(callerInclude, listConfig.fields, config, listName)
   if (!folded.include) {
-    return { ...folded, selection: undefined }
+    return { ...folded, selection: undefined, toOneAccessFilters: emptyToOneAccessFilterTree() }
   }
 
-  const include = await buildAccessScopedInclude(
+  const { include, toOneAccessFilters } = await buildAccessScopedInclude(
     folded.include,
     listConfig.fields,
     { session: context.session, context },
     config,
     listName,
   )
-  return { include, declaredOnly: folded.declaredOnly, selection: undefined }
+  return { include, declaredOnly: folded.declaredOnly, selection: undefined, toOneAccessFilters }
 }
 
 function createFindUnique<TPrisma extends PrismaClientLike>(
@@ -1026,7 +1079,7 @@ function createFindUnique<TPrisma extends PrismaClientLike>(
     // Resolve `include`, folding any declared dependencies (`needs`,
     // ADR-0025) in alongside whatever the fragment/caller/sudo/bare path
     // already produces — see `resolveReadInclude`'s doc comment.
-    let { include, declaredOnly, selection } = await resolveReadInclude(
+    let { include, declaredOnly, selection, toOneAccessFilters } = await resolveReadInclude(
       args.include,
       fragment ? fragment._fields : undefined,
       listName,
@@ -1056,6 +1109,14 @@ function createFindUnique<TPrisma extends PrismaClientLike>(
       return null
     }
 
+    // Resolve which of the to-one relations flagged by `toOneAccessFilters`
+    // actually survive their related list's `query` access (issue #974) —
+    // one batched existence check per relation, before field visibility runs.
+    const toOneVisibility = await resolveToOneAccessVisibility([item], toOneAccessFilters, {
+      session: context.session,
+      context,
+    })
+
     // Pass sudo flag through context to skip field-level access checks
     const filtered = await filterReadableFields(
       item,
@@ -1069,6 +1130,7 @@ function createFindUnique<TPrisma extends PrismaClientLike>(
       listName,
       declaredOnly,
       selection,
+      toOneVisibility,
     )
 
     if (fragment) {
@@ -1178,7 +1240,7 @@ function createFindMany<TPrisma extends PrismaClientLike>(
     // Resolve `include`, folding any declared dependencies (`needs`,
     // ADR-0025) in alongside whatever the fragment/caller/sudo/bare path
     // already produces — see `resolveReadInclude`'s doc comment.
-    let { include, declaredOnly, selection } = await resolveReadInclude(
+    let { include, declaredOnly, selection, toOneAccessFilters } = await resolveReadInclude(
       args?.include,
       fragment ? fragment._fields : undefined,
       listName,
@@ -1202,6 +1264,15 @@ function createFindMany<TPrisma extends PrismaClientLike>(
       include,
     })
 
+    // Resolve which of the to-one relations flagged by `toOneAccessFilters`
+    // actually survive their related list's `query` access (issue #974) —
+    // ONE batched existence check per relation across every row in `items`,
+    // before field visibility runs on any of them.
+    const toOneVisibility = await resolveToOneAccessVisibility(items, toOneAccessFilters, {
+      session: context.session,
+      context,
+    })
+
     // Pass sudo flag through context to skip field-level access checks
     const filtered = await Promise.all(
       items.map((item: Record<string, unknown>) =>
@@ -1217,6 +1288,7 @@ function createFindMany<TPrisma extends PrismaClientLike>(
           listName,
           declaredOnly,
           selection,
+          toOneVisibility,
         ),
       ),
     )
@@ -1501,7 +1573,7 @@ function createGet<TPrisma extends PrismaClientLike>(
     // Resolve `include`, folding any declared dependencies (`needs`,
     // ADR-0025) in alongside whatever the fragment/caller/sudo/bare path
     // already produces — see `resolveReadInclude`'s doc comment.
-    let { include, declaredOnly, selection } = await resolveReadInclude(
+    let { include, declaredOnly, selection, toOneAccessFilters } = await resolveReadInclude(
       args?.include,
       fragment ? fragment._fields : undefined,
       listName,
@@ -1519,6 +1591,13 @@ function createGet<TPrisma extends PrismaClientLike>(
     })
 
     if (item) {
+      // Resolve which of the to-one relations flagged by `toOneAccessFilters`
+      // actually survive their related list's `query` access (issue #974).
+      const toOneVisibility = await resolveToOneAccessVisibility([item], toOneAccessFilters, {
+        session: context.session,
+        context,
+      })
+
       const filtered = await filterReadableFields(
         item,
         listConfig.fields,
@@ -1531,6 +1610,7 @@ function createGet<TPrisma extends PrismaClientLike>(
         listName,
         declaredOnly,
         selection,
+        toOneVisibility,
       )
       if (fragment) {
         return pickFields(filtered, fragment._fields)