@opensaas/stack-core 0.37.0 → 0.39.0

package/src/access/field-access.ts

@@ -1,9 +1,48 @@
 import type { Session, AccessContext } from './types.js'
-import type { FieldAccess } from './types.js'
+import type { FieldAccess, FieldAccessControl } from './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'
+
+/**
+ * Marks a throw caused by touching {@link createPoisonedItem}'s `item`, as
+ * opposed to some other error a field rule legitimately raises. Not exported
+ * — callers only ever see its effect (a `false` from
+ * `isFieldReadableForPredicate`), never the class itself.
+ */
+class PredicateTimeItemAccessError extends Error {}
+
+/**
+ * An `item` that throws {@link PredicateTimeItemAccessError} on ANY attempt to
+ * read a property off it — including via optional chaining (`item?.x`),
+ * since the Proxy itself is a truthy object and optional chaining still
+ * performs the property read once its base is non-nullish. Used by
+ * `isFieldReadableForPredicate` to detect a read rule that depends on the
+ * fetched row: there is no row yet at predicate-evaluation time (see that
+ * function's doc), so any rule that reaches into `item` at all cannot be
+ * answered here.
+ */
+function createPoisonedItem(): Record<string, unknown> {
+  return new Proxy(
+    {},
+    {
+      get(_target, prop) {
+        throw new PredicateTimeItemAccessError(String(prop))
+      },
+      has(_target, prop) {
+        throw new PredicateTimeItemAccessError(String(prop))
+      },
+      ownKeys() {
+        throw new PredicateTimeItemAccessError('ownKeys')
+      },
+      getOwnPropertyDescriptor(_target, prop) {
+        throw new PredicateTimeItemAccessError(String(prop))
+      },
+    },
+  ) as Record<string, unknown>
+}
 
 /**
  * Shared field-level access evaluation.
@@ -24,6 +63,10 @@ import { ValidationError } from '../hooks/index.js'
  * (read/update/delete), and on the `inputData` being written (create/update),
  * so all of those are accepted. Do not introduce a parallel evaluator with a
  * narrower signature.
+ *
+ * Returns a strict boolean, never a filter: a rule that returns anything else
+ * throws `InvalidFieldAccessResultError` rather than defaulting to allow (see
+ * that error's doc, ADR-0001, and ADR-0030).
  */
 export async function checkFieldAccess(
   fieldAccess: FieldAccess | undefined,
@@ -35,18 +78,25 @@ export async function checkFieldAccess(
     inputData?: Record<string, unknown>
   },
 ): Promise<boolean> {
-  // Skip access check in sudo mode
   if (args.context._isSudo) {
     return true
   }
 
   if (!fieldAccess) {
-    return true // No field access means allow
+    return true
   }
 
-  const accessControl = fieldAccess[operation]
+  // `FieldAccess['read']` is narrower than `FieldAccess['create'/'update']` (it
+  // only accepts the single `operation: 'read'` call shape, see `types.ts`),
+  // so indexing by a not-yet-narrowed `operation` union produces a callable
+  // whose effective parameter type collapses to an intersection TypeScript
+  // can't satisfy generically here. Widen back to the general
+  // `FieldAccessControl` — the same shape this function has always built and
+  // passed below — since by construction the args object always matches
+  // whichever operation is actually requested.
+  const accessControl = fieldAccess[operation] as FieldAccessControl | undefined
   if (!accessControl) {
-    return true // No specific access control means allow
+    return true
   }
 
   const result = await accessControl({
@@ -57,51 +107,79 @@ export async function checkFieldAccess(
     operation,
   } as Parameters<typeof accessControl>[0])
 
-  // If result is false, deny access
   if (result === false) {
     return false
   }
 
-  // If result is true, allow access
   if (result === true) {
     return true
   }
 
-  // Default to allowing access if we can't determine
-  return true
+  // `FieldAccessControl` is typed to return `boolean` only — field access is a
+  // per-field visibility decision, not a row filter (ADR-0001, ADR-0030). A
+  // well-typed rule can never reach this line; getting here means a caller
+  // bypassed the type (most notably by returning a Prisma filter, the shape
+  // operation-level `AccessControl` accepts but this does not). Fail loudly
+  // and closed — this operation applies identically whether or not `item` is
+  // available, so `create` (which has no `item` to evaluate a filter against)
+  // needs no separate answer: neither operation ever honours a non-boolean.
+  throw new InvalidFieldAccessResultError(operation, result)
 }
 
 /**
- * Simple filter matching for field-level access
- * Checks if an item matches a Prisma-like filter object
+ * Whether a field's `read` access allows it to be NAMED in a `where`/`orderBy`
+ * predicate, evaluated BEFORE the query runs (#915).
+ *
+ * Field-level `read` access has always been a post-query check (Field
+ * Visibility, `field-visibility.ts`): it strips a denied key from a row that
+ * has already been fetched. That leaves the predicate itself unconstrained —
+ * a caller can still filter or sort by a field whose value they could never
+ * read, and recover it (or its relative order) by probing. This function is
+ * the pre-query counterpart, called from `query-validation.ts`'s `where`/
+ * `orderBy` walk for every key that resolves to a declared field.
+ *
+ * It delegates to the same evaluator Field Visibility uses (`checkFieldAccess`),
+ * per this module's canonical-evaluator rule above. The one difference is the
+ * `item` it hands the rule: there is no fetched row
+ * yet, so a rule that depends on one (the shape `FieldAccess['read']`
+ * documents as the norm, e.g. `item?.ownerId === session?.userId`) cannot be
+ * answered here. Rather than skip the check for such a rule — which would
+ * reopen exactly the hole this closes for the fields most likely to be
+ * sensitive — it is handed a poisoned `item` that throws on any property
+ * read, and that throw is caught and resolved to `false`: a row-dependent
+ * `read` rule always denies at predicate time, documented and deliberate
+ * (see docs/adr/0031). A rule that never touches `item` (checking only
+ * `session`, the common case for a field meant to be filterable/sortable at
+ * all) evaluates normally and returns its real answer.
+ *
+ * A rule that returns a non-boolean is a distinct, louder failure (#913,
+ * ADR-0030) — `InvalidFieldAccessResultError` — and is deliberately NOT
+ * folded into the `false` here; it propagates so the config bug it signals is
+ * never mistaken for an ordinary field-level denial.
  */
-function matchesFilter(item: Record<string, unknown>, filter: Record<string, unknown>): boolean {
-  for (const [key, condition] of Object.entries(filter)) {
-    if (typeof condition === 'object' && condition !== null) {
-      // Handle nested conditions like { equals: value }
-      if ('equals' in condition) {
-        if (item[key] !== condition.equals) {
-          return false
-        }
-      } else if ('not' in condition) {
-        if (item[key] === condition.not) {
-          return false
-        }
-      }
-      // Add more condition types as needed
-    } else {
-      // Direct equality check
-      if (item[key] !== condition) {
-        return false
-      }
-    }
+export async function isFieldReadableForPredicate(
+  fieldAccess: FieldAccess | undefined,
+  args: {
+    session: Session | null
+    context: AccessContext & { _isSudo?: boolean }
+  },
+): Promise<boolean> {
+  try {
+    return await checkFieldAccess(fieldAccess, 'read', {
+      session: args.session,
+      context: args.context,
+      item: createPoisonedItem(),
+    })
+  } catch (err) {
+    // Only the poisoned-item signal means "row-dependent, deny". Anything
+    // else — including `InvalidFieldAccessResultError` and a genuine bug in
+    // the rule itself — propagates unchanged rather than being silently
+    // folded into an ordinary denial (found in review of #925).
+    if (err instanceof PredicateTimeItemAccessError) return false
+    throw err
   }
-  return true
 }
 
-/**
- * Filter fields from input data based on write access (create/update)
- */
 export async function filterWritableFields<T extends Record<string, unknown>>(
   data: T,
   fieldConfigs: Record<
@@ -122,8 +200,7 @@ export async function filterWritableFields<T extends Record<string, unknown>>(
 ): Promise<Partial<T>> {
   const filtered: Record<string, unknown> = {}
 
-  // Build a set of foreign key field names to exclude
-  // Foreign keys should not be in the data when using Prisma's relation syntax
+  // Foreign keys must not appear in `data` when using Prisma's relation syntax.
   const foreignKeyFields = new Set<string>()
   // Map each raw per-part column name contributed by a multi-column field
   // (e.g. storage image()/file() in Keystone-parity mode) back to its OWNING
@@ -162,19 +239,18 @@ export async function filterWritableFields<T extends Record<string, unknown>>(
   for (const [fieldName, value] of Object.entries(data)) {
     const fieldConfig = fieldConfigs[fieldName]
 
-    // Skip system fields
     if (['id', 'createdAt', 'updatedAt'].includes(fieldName)) {
       continue
     }
 
-    // Skip virtual fields - they don't store in database
-    // Virtual fields with resolveInput hooks handle side effects separately
+    // Virtual fields don't store in the database — skipped here, but their
+    // resolveInput hooks still run as a separate side-effect step.
     if (fieldConfig && 'virtual' in fieldConfig && fieldConfig.virtual) {
       continue
     }
 
-    // Skip foreign key fields (e.g., authorId) when their corresponding relationship field exists
-    // This prevents conflicts when using Prisma's relation syntax (e.g., author: { connect: { id } })
+    // Prevents conflicts with Prisma's relation syntax (e.g.,
+    // `author: { connect: { id } }`).
     if (foreignKeyFields.has(fieldName)) {
       continue
     }

package/src/access/field-transforms.ts

@@ -1,29 +1,20 @@
 import type { OpenSaasConfig, FieldConfig } from '../config/types.js'
 import type { HashedPassword } from '../utils/password.js'
 
-/**
- * Extract the return type of a field's afterOperation hook
- * If the field has an afterOperation hook, infer its return type
- * Otherwise, use the original type
- */
 export type InferFieldReadType<TField extends FieldConfig, TOriginal> = TField extends {
-  // Generic `any` is required here for TypeScript's conditional type inference to work correctly
-  // This allows us to infer the exact return type `R` from hooks of any signature
+  // Uses `any` here so TypeScript's conditional type inference can pick up the
+  // exact return type `R` from a hook of any signature.
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   hooks?: { afterOperation?: (...args: any[]) => infer R }
 }
   ? R extends never
-    ? TOriginal // No hook defined
-    : R // Hook return type
-  : TOriginal // No hooks at all
+    ? TOriginal
+    : R
+  : TOriginal
 
-/**
- * Transform a Prisma model's field types based on OpenSaas field configs
- * This applies afterOperation hook transformations to field types
- */
 export type TransformModelFields<
-  // Generic constraint requires `any` to allow indexing by string keys from Prisma models
-  // This is necessary for mapped types to work with Prisma's generated model types
+  // Uses `any` so this constraint accepts Prisma's generated model types, which are
+  // indexed by string keys.
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   TModel extends Record<string, any>,
   TFields extends Record<string, FieldConfig>,
@@ -33,34 +24,22 @@ export type TransformModelFields<
     : TModel[K]
 }
 
-/**
- * Get the field configs for a specific list from the OpenSaas config
- */
 export type GetListFields<
   TConfig extends OpenSaasConfig,
   TListKey extends keyof TConfig['lists'],
 > = TConfig['lists'][TListKey]['fields']
 
-/**
- * Transform a Prisma model result based on OpenSaas config
- * Applies field hooks transformations
- */
 export type TransformResult<
   TConfig extends OpenSaasConfig,
   TListKey extends keyof TConfig['lists'],
   TResult,
 > =
-  // Generic constraint requires `any` to check if TResult is an object type that can be transformed
-  // This pattern is standard in TypeScript for conditional types on object shapes
+  // Uses `any` to check whether TResult is an object type that can be transformed.
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   TResult extends Record<string, any>
     ? TransformModelFields<TResult, GetListFields<TConfig, TListKey>>
     : TResult
 
-/**
- * Transform a Prisma operation's return type
- * Handles single results, arrays, and null cases
- */
 export type TransformOperationResult<
   TConfig extends OpenSaasConfig,
   TListKey extends keyof TConfig['lists'],
@@ -76,20 +55,10 @@ export type TransformOperationResult<
       >
     : never
 
-/**
- * Known field type mappings for afterOperation hooks
- * These provide concrete type hints for common field transformations
- */
 export interface FieldTypeTransforms {
   password: HashedPassword
-  // Future field types can be added here
-  // richText: TiptapContent
-  // json: JSONValue
 }
 
-/**
- * Helper to infer field type based on field config type
- */
 export type InferFieldTypeTransform<TField extends FieldConfig> = TField extends {
   type: infer TType
 }

package/src/access/field-visibility.ts

@@ -6,6 +6,7 @@ import { RESOLVE_CHAIN_MAX_LENGTH } from './depth-limits.js'
 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'
 // 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
@@ -23,16 +24,20 @@ import { buildDbDelegate } from '../context/index.js'
  * virtual fields. None of this can move into phase 1: virtual fields are
  * computed in JavaScript and field access can depend on the fetched row.
  *
+ * A computed field — any field carrying a `resolveOutput` hook, virtual or
+ * not — is produced only where the read is going to return it (ADR-0027). A
+ * fragment `query`'s own field selection is the only thing that restricts a
+ * level this way; a bare or `include`-based read, and any relation reached
+ * purely to satisfy a `needs` declaration, still compute every field, as
+ * before. A field the read is not going to return does no work at all —
+ * neither its read-access evaluation nor its hook. The projection-aware skip
+ * below shows this rule at each of the two places it applies.
+ *
  * 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`.
  */
 
-/**
- * Runtime type for resolveOutput hooks
- * Used when we need to call hooks generically without knowing the specific field type
- * Supports both sync and async implementations
- */
 type ResolveOutputHookRuntime = (args: {
   operation: 'query'
   value: unknown
@@ -96,8 +101,11 @@ function deriveResolveOutputContext(
  * from the result.
  *
  * `accessItem` is the row used to evaluate field access; `hookItem` is the
- * object passed to the hook as `item` (these differ for virtual fields, which
- * see the already-filtered output so they can read sibling fields).
+ * object passed to the hook as `item`. For a stored field, both are
+ * `workingItem` (the row's own stored/fetched columns). For a virtual field,
+ * `hookItem` is `computedFieldItem` instead — the same stored columns with
+ * every skipped-or-denied key removed — so it never sees another computed
+ * field's resolved value (ADR-0027).
  */
 async function resolveReadableFieldValue(params: {
   fieldConfig: FieldConfig | undefined
@@ -111,7 +119,6 @@ async function resolveReadableFieldValue(params: {
 }): Promise<{ readable: false } | { readable: true; value: unknown }> {
   const { fieldConfig, fieldName, value, accessItem, hookItem, listKey, args, config } = params
 
-  // Check field access (checkFieldAccess already handles sudo mode)
   const canRead = await checkFieldAccess(fieldConfig?.access, 'read', {
     ...args,
     item: accessItem,
@@ -121,10 +128,9 @@ async function resolveReadableFieldValue(params: {
     return { readable: false }
   }
 
-  // Apply resolveOutput hook if present
   if (fieldConfig?.hooks?.resolveOutput && listKey) {
-    // Cast to runtime type for generic execution
-    // At runtime, the hook will receive the correct value type for the field
+    // The hook is erased to this runtime shape here; at the actual call it
+    // receives the value typed for its own field.
     const hook = fieldConfig.hooks.resolveOutput as unknown as ResolveOutputHookRuntime
     const link = { listKey, fieldKey: fieldName }
     const chain = args.context._resolveOutputChain
@@ -152,7 +158,6 @@ async function resolveReadableFieldValue(params: {
       return { readable: false }
     }
 
-    // Use Promise.resolve() to handle both sync and async hooks
     const resolved = await Promise.resolve(
       hook({
         value,
@@ -169,10 +174,6 @@ async function resolveReadableFieldValue(params: {
   return { readable: true, value }
 }
 
-/**
- * Filter fields from an object based on read access
- * Recursively applies access control to nested relationships
- */
 export async function filterReadableFields<T extends Record<string, unknown>>(
   item: T,
   fieldConfigs: Record<string, FieldConfig>,
@@ -189,6 +190,9 @@ export async function filterReadableFields<T extends Record<string, unknown>>(
   // returned — after resolveOutput has had a chance to read them — so a
   // declared dependency never widens what the caller receives.
   declaredOnly: DeclaredOnlyTree = emptyDeclaredOnlyTree(),
+  // 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,
 ): Promise<Partial<T>> {
   const filtered: Record<string, unknown> = {}
 
@@ -214,19 +218,35 @@ export async function filterReadableFields<T extends Record<string, unknown>>(
     workingItem[fieldName] = assembled
   }
 
+  // Keys denied by field-level read access during the pass below — as opposed
+  // to a key merely skipped by `selection` or held back only for
+  // `declaredOnly` stripping. Tracked separately because a denied key must
+  // stay invisible to a computed field's hook (below), while a declared-only
+  // key must stay VISIBLE to one — that is the entire point of declaring it
+  // (ADR-0025) — even though `selection` above skipped adding it to
+  // `filtered` because the caller's fragment never asked for it.
+  const accessDeniedKeys = new Set<string>()
+
   // Process existing fields from the database result
   for (const [fieldName, value] of Object.entries(workingItem)) {
     const fieldConfig = fieldConfigs[fieldName]
 
-    // Always include id, createdAt, updatedAt
     if (['id', 'createdAt', 'updatedAt'].includes(fieldName)) {
       filtered[fieldName] = value
       continue
     }
 
-    // Handle relationship fields - recursively filter fields within related items
-    // Note: Access control filtering is now done at database level via buildIncludeWithAccessControl
-    // This only handles field-level access (hiding sensitive fields)
+    // Projection-aware skip (ADR-0027, see module doc above): a field this
+    // level's fragment did not select gets no read-access check, no
+    // resolveOutput, and no recursion into a relation — none of that work
+    // happens for a value the read isn't going to return.
+    if (selection?.fields && !selection.fields.has(fieldName)) {
+      continue
+    }
+
+    // Row/relation-level access is already scoped at the DB level via
+    // buildAccessScopedInclude; this only handles field-level access (hiding
+    // sensitive fields).
     //
     // Deliberately uncapped: the row/relation scoping in access-filter.ts bounds
     // what gets FETCHED (a caller include past its depth cap is now a denial,
@@ -244,13 +264,13 @@ export async function filterReadableFields<T extends Record<string, unknown>>(
       value !== null &&
       value !== undefined
     ) {
-      // Gate the relationship on read access before recursing.
       const canRead = await checkFieldAccess(fieldConfig?.access, 'read', {
         ...args,
         item: workingItem,
       })
 
       if (!canRead) {
+        accessDeniedKeys.add(fieldName)
         continue
       }
 
@@ -260,10 +280,14 @@ export async function filterReadableFields<T extends Record<string, unknown>>(
       // back to an empty tree when this relation isn't declaration-related at
       // all — the common case.
       const nestedDeclaredOnly = declaredOnly.nested[fieldName] ?? emptyDeclaredOnlyTree()
+      // This relation's own fragment scope, if the caller's fragment named it
+      // with a nested Fragment/RelationSelector. `undefined` (a bare `true`
+      // selector, or no `selection` at all) means the nested list computes
+      // unrestricted — matching what naming a relation without narrowing it
+      // further has always meant.
+      const nestedSelection = selection?.nested[fieldName]
 
       if (relatedConfig) {
-        // For many relationships (arrays) - recursively filter fields in each item
-        // The recursive call already handles applying resolveOutput hooks
         if (Array.isArray(value)) {
           filtered[fieldName] = await Promise.all(
             value.map((relatedItem) =>
@@ -275,13 +299,11 @@ export async function filterReadableFields<T extends Record<string, unknown>>(
                 depth + 1,
                 relatedConfig.listName,
                 nestedDeclaredOnly,
+                nestedSelection,
               ),
             ),
           )
-        }
-        // For single relationships (objects) - recursively filter fields
-        // The recursive call already handles applying resolveOutput hooks
-        else if (typeof value === 'object') {
+        } else if (typeof value === 'object') {
           filtered[fieldName] = await filterReadableFields(
             value as Record<string, unknown>,
             relatedConfig.listConfig.fields,
@@ -290,17 +312,17 @@ export async function filterReadableFields<T extends Record<string, unknown>>(
             depth + 1,
             relatedConfig.listName,
             nestedDeclaredOnly,
+            nestedSelection,
           )
         }
       } else {
-        // Related config not found, include the value as-is
         filtered[fieldName] = value
       }
       continue
     }
 
-    // Non-relationship field (or relationship without an includable value):
-    // check read access and apply resolveOutput via the shared helper.
+    // Non-relationship field, or a relationship field whose value is not
+    // includable (null/undefined) — falls through to the shared helper.
     const result = await resolveReadableFieldValue({
       fieldConfig,
       fieldName,
@@ -314,38 +336,69 @@ export async function filterReadableFields<T extends Record<string, unknown>>(
 
     if (result.readable) {
       filtered[fieldName] = result.value
+    } else {
+      accessDeniedKeys.add(fieldName)
+    }
+  }
+
+  // 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
+  // either survived into `filtered` (selected and allowed) OR exists only to
+  // satisfy a `needs` declaration (`declaredOnly` — that IS the point of
+  // declaring it: fetched for a hook, never for the caller, ADR-0025).
+  // Everything else — field-level denied, or skipped by `selection` and
+  // declared by no one — is deleted. A computed field reaches for exactly its
+  // own declared dependencies and nothing another field's hook produced
+  // (ADR-0027): reaching for a sibling that was denied or skipped-and-
+  // undeclared finds nothing there, the same as reaching for one never
+  // declared at all, and reaching for a sibling that DID survive finds its
+  // raw stored form, never another hook's resolved value — a virtual field
+  // computed earlier in declaration order is exactly as invisible as one
+  // computed later.
+  const computedFieldItem: Record<string, unknown> = { ...workingItem }
+  for (const key of Object.keys(workingItem)) {
+    if (['id', 'createdAt', 'updatedAt'].includes(key)) continue
+    if (accessDeniedKeys.has(key)) {
+      delete computedFieldItem[key]
+      continue
     }
+    if (key in filtered) continue
+    if (declaredOnly.keys.has(key)) continue
+    delete computedFieldItem[key]
   }
 
-  // Process virtual fields - compute values from other fields
-  // Virtual fields don't exist in the database result, so we need to compute them separately
   for (const [fieldName, fieldConfig] of Object.entries(fieldConfigs)) {
-    // Skip if already processed (from database result)
     if (fieldName in filtered) {
       continue
     }
 
-    // Only process virtual fields
     if (!fieldConfig.virtual) {
       continue
     }
 
-    // Virtual fields must have a resolveOutput hook to compute their value;
-    // without one there is nothing to add to the result.
+    // Projection-aware skip (ADR-0027): same rule as the stored-field pass
+    // above — a fragment that does not select this virtual field does no
+    // work for it at all.
+    if (selection?.fields && !selection.fields.has(fieldName)) {
+      continue
+    }
+
+    // A virtual field with no resolveOutput hook can never produce a value
+    // on ANY read — there is nothing to compute, so there is nothing to do,
+    // including evaluating its read access (ADR-0027 reconciles the
+    // access-only evaluation this branch used to preserve: a field that
+    // never has output has no side effect worth preserving access for).
     if (!(fieldConfig.hooks?.resolveOutput && listKey)) {
-      // Still evaluate read access to preserve any access-fn side effects.
-      await checkFieldAccess(fieldConfig.access, 'read', { ...args, item: workingItem })
       continue
     }
 
-    // Check read access and compute the value via the shared helper. Virtual
-    // fields see the already-filtered item so they can read sibling fields.
     const result = await resolveReadableFieldValue({
       fieldConfig,
       fieldName,
       value: undefined, // Virtual fields don't have a database value
       accessItem: workingItem,
-      hookItem: filtered,
+      hookItem: computedFieldItem,
       listKey,
       args,
       config,
@@ -357,10 +410,11 @@ export async function filterReadableFields<T extends Record<string, unknown>>(
   }
 
   // Strip relations that were fetched ONLY to satisfy a `needs` declaration
-  // (ADR-0025), now that every resolveOutput hook at this level — including
-  // virtual fields, which read the assembled `filtered` object above — has
-  // had the chance to see them. A declared dependency is private plumbing,
-  // not an implicit `include`: it never widens what the caller receives.
+  // (ADR-0025), now that every resolveOutput hook at this level has had the
+  // chance to see them (via `computedFieldItem`, never `filtered` itself — a
+  // declared dependency is read from stored columns, not from another
+  // field's resolved output). A declared dependency is private plumbing, not
+  // an implicit `include`: it never widens what the caller receives.
   for (const key of declaredOnly.keys) {
     delete filtered[key]
   }

package/src/access/index.ts

@@ -20,15 +20,23 @@ export {
   getRelatedListConfig,
 } from './engine.js'
 // Canonical field-level access evaluation (shared by read and write paths).
-export { checkFieldAccess, filterWritableFields } from './field-access.js'
+export {
+  checkFieldAccess,
+  filterWritableFields,
+  isFieldReadableForPredicate,
+} from './field-access.js'
+// Read-path key validation — the `findMany`/`count` counterpart to the write
+// path's #564 undeclared-key reject.
+export { validateQueryKeys } from './query-validation.js'
+// Read-path field-level access on `where`/`orderBy` keys — a field the
+// session cannot read cannot be named in a predicate either (#915).
+export { validateQueryFieldReadAccess } from './query-validation.js'
 // Phase 1 — Access Filter (pre-query row/relation scoping).
 export {
-  buildIncludeWithAccessControl,
-  mergeIncludeWithAccessControl,
+  buildAccessScopedInclude,
+  buildAccessScopedWhere,
   stripVirtualFieldsFromInclude,
-  toPrismaInclude,
 } from './access-filter.js'
-export type { AccessIncludeResult } from './access-filter.js'
 // Phase 2 — Field Visibility (post-query field stripping + resolveOutput).
 export { filterReadableFields } from './field-visibility.js'
 // Declared Dependencies — folding `needs` into an include without widening
@@ -43,3 +51,7 @@ export type { DeclaredOnlyTree } from './declared-dependencies.js'
 export { AccessScopeDepthExceededError } from './errors.js'
 // Thrown when a resolveOutput hook's own resolve chain cycles back into itself.
 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 a relation filter's related list denies query access outright (#916).
+export { RelationFilterAccessDeniedError } from './errors.js'