@opensaas/stack-core 0.38.0 → 0.39.0

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

@@ -9,15 +9,16 @@ import {
 } from './relationship-label-filter.js'
 
 /**
- * Access-scoped to-one relationship label filters (issue #749). Verifies that
- * `author:Ada` → `{ author: { is: { name: { contains: 'Ada' } } } }` gets the
- * related list's `query` access folded into the nested `is` clause, so a
- * session can never distinguish parent rows by a related field it cannot
- * itself read.
+ * `resolveRelationshipLabelFilters` used to fold the related list's `query`
+ * access into a to-one relationship label filter's nested `is` clause
+ * (issue #749). Since #916, the engine itself scopes every relation filter in
+ * `where` (`buildAccessScopedWhere`), including this exact `{ is: {...} } }`
+ * shape, so this resolver's own fold is redundant and has been removed — it
+ * is now a pass-through, kept exported only for API compatibility. These
+ * tests pin that pass-through behavior; `access-filter.test.ts` and
+ * `context.test.ts` cover the actual access-scoping this resolver used to do.
  */
 
-// Post is fully open; User (the `author` relation target) is scoped so only
-// active users are queryable; Widget ships fully closed (no access block).
 function makeConfig(): OpenSaasConfig {
   return {
     db: { provider: 'sqlite', prismaClientConstructor: () => null as never },
@@ -63,8 +64,8 @@ describe('isToOneRelationshipField', () => {
   })
 })
 
-describe('resolveRelationshipLabelFilters', () => {
-  it('returns the where unchanged when there are no label-filter members', async () => {
+describe('resolveRelationshipLabelFilters (pass-through since #916)', () => {
+  it('returns a plain where unchanged', async () => {
     const config = makeConfig()
     const where = { title: { contains: 'hello' } }
     const resolved = await resolveRelationshipLabelFilters(
@@ -76,7 +77,7 @@ describe('resolveRelationshipLabelFilters', () => {
     expect(resolved).toBe(where)
   })
 
-  it("ANDs the related list's access filter into the nested `is` clause", async () => {
+  it('returns a to-one label-filter `is` clause unchanged — the engine scopes it now', async () => {
     const config = makeConfig()
     const where = { author: { is: { name: { contains: 'Ada' } } } }
     const resolved = await resolveRelationshipLabelFilters(
@@ -85,31 +86,10 @@ describe('resolveRelationshipLabelFilters', () => {
       { session: null, context: makeContext() },
       config,
     )
-    expect(resolved).toEqual({
-      author: { is: { AND: [{ active: { equals: 1 } }, { name: { contains: 'Ada' } }] } },
-    })
-  })
-
-  it('leaves the member unchanged when the related list is fully readable', async () => {
-    const config: OpenSaasConfig = {
-      db: { provider: 'sqlite', prismaClientConstructor: () => null as never },
-      lists: {
-        Tag: list({ fields: { name: text() }, access: { operation: { query: () => true } } }),
-        Post: list({ fields: { title: text(), tag: relationship({ ref: 'Tag' }) } }),
-      },
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- minimal config for unit test
-    } as any
-    const where = { tag: { is: { name: { contains: 'news' } } } }
-    const resolved = await resolveRelationshipLabelFilters(
-      where,
-      config.lists.Post,
-      { session: null, context: makeContext() },
-      config,
-    )
-    expect(resolved).toEqual(where)
+    expect(resolved).toBe(where)
   })
 
-  it('resolves a fully denied related list to a never-matching member (no leak)', async () => {
+  it('returns a label filter against a fully denied related list unchanged too', async () => {
     const config = makeConfig()
     const where = { widget: { is: { name: { contains: 'Gadget' } } } }
     const resolved = await resolveRelationshipLabelFilters(
@@ -118,26 +98,10 @@ describe('resolveRelationshipLabelFilters', () => {
       { session: null, context: makeContext() },
       config,
     )
-    expect(resolved).toEqual({ id: { in: [] } })
-  })
-
-  it('preserves sibling conditions, ANDing the resolved id constraint for a denied member', async () => {
-    const config = makeConfig()
-    const where = {
-      AND: [{ title: { contains: 'hello' } }, { widget: { is: { name: { contains: 'Gadget' } } } }],
-    }
-    const resolved = await resolveRelationshipLabelFilters(
-      where,
-      config.lists.Post,
-      { session: null, context: makeContext() },
-      config,
-    )
-    expect(resolved).toEqual({
-      AND: [{ title: { contains: 'hello' } }, { id: { in: [] } }],
-    })
+    expect(resolved).toBe(where)
   })
 
-  it('preserves sibling conditions alongside the access-scoped nested `is` clause', async () => {
+  it('returns a where with nested AND/label-filter members unchanged', async () => {
     const config = makeConfig()
     const where = {
       AND: [{ title: { contains: 'hello' } }, { author: { is: { name: { contains: 'Ada' } } } }],
@@ -148,30 +112,17 @@ describe('resolveRelationshipLabelFilters', () => {
       { session: null, context: makeContext() },
       config,
     )
-    expect(resolved).toEqual({
-      AND: [
-        { title: { contains: 'hello' } },
-        { author: { is: { AND: [{ active: { equals: 1 } }, { name: { contains: 'Ada' } }] } } },
-      ],
-    })
+    expect(resolved).toBe(where)
   })
 
-  it('composes with a to-many count marker member left untouched by this resolver', async () => {
+  it('returns undefined unchanged when there is no where at all', async () => {
     const config = makeConfig()
-    const where = {
-      AND: [{ author: { is: { name: { contains: 'Ada' } } } }, { views: { gt: 10 } }],
-    }
     const resolved = await resolveRelationshipLabelFilters(
-      where,
+      undefined,
       config.lists.Post,
       { session: null, context: makeContext() },
       config,
     )
-    expect(resolved).toEqual({
-      AND: [
-        { author: { is: { AND: [{ active: { equals: 1 } }, { name: { contains: 'Ada' } }] } } },
-        { views: { gt: 10 } },
-      ],
-    })
+    expect(resolved).toBeUndefined()
   })
 })

package/src/access/relationship-label-filter.ts

@@ -1,29 +1,31 @@
 import type { Session, AccessContext } from './types.js'
 import type { OpenSaasConfig, ListConfig, FieldConfig } from '../config/types.js'
-import { checkAccess, getRelatedListConfig } from './engine.js'
-import { mergeResolvedMember } from './relationship-count.js'
 
 /**
  * Access-scoped to-one relationship label filters for the admin list view
- * (issue #749).
+ * (issue #749) — NOW A PASS-THROUGH.
  *
  * A to-one relationship's Filter spec (`author:Ada` → `{ author: { is: { name:
- * { contains: 'Ada' } } } }`) is a pure mapper (see `relationship()` in
- * `fields/index.ts`) — it has no way to consult the related list's access
- * control, so the nested `is` clause it emits runs as an unscoped Prisma
- * sub-filter against the related table. The parent list's own access filter
- * still scopes which parent rows are visible, but the nested condition itself
- * is evaluated with no reference to the related list's `query` access — a
- * session could distinguish parent rows by a related field it is not itself
- * allowed to read (e.g. binary-searching `author:A`, `author:Ad`, `author:Ada`
- * against a `User` list it cannot query).
+ * { contains: 'Ada' } } } }`) produces exactly the `{ is: {...} }` shape a
+ * relation filter uses. Before #916, the engine did not scope relation
+ * filters in `where` at all, so this module was the only place the related
+ * list's `query` access was folded into that nested `is` clause (mirroring
+ * `relationship-count.ts`'s `_count` folding) — otherwise a session could
+ * distinguish parent rows by a related field it could not itself read (e.g.
+ * binary-searching `author:A`, `author:Ad`, `author:Ada` against a `User`
+ * list it cannot query).
  *
- * This module is the single place the related list's operation-level `query`
- * access is folded into that nested `is` clause, mirroring how
- * `relationship-count.ts` folds it into `_count` selects and count-filter
- * markers. A fully denied related list makes the member never match — the
- * token cannot be used to confirm or rule out a value on a field the session
- * cannot read (narrowing-only, matching the count resolver's denied path).
+ * #916 closed that gap in the engine itself: `context.db.*.findMany`/`count`
+ * now scope every relation filter in `where` — including this exact `is`
+ * shape — via `buildAccessScopedWhere` (`access-filter.ts`), applied
+ * automatically to whatever `where` this module's caller (`ListView.tsx`)
+ * hands to the secured context. Folding the same access filter here as well
+ * would be redundant work producing an identical result (the engine ANDs the
+ * same filter in a second time), so this module's own fold was removed —
+ * `resolveRelationshipLabelFilters` now returns `where` unchanged. The
+ * exported functions are kept, unchanged in shape, only because they remain
+ * part of `@opensaas/stack-core`'s public surface; removing them outright
+ * would be a breaking change this fix does not need to make.
  */
 
 type LabelFilterArgs = {
@@ -46,95 +48,16 @@ export function isToOneRelationshipField(field: FieldConfig | undefined): boolea
   )
 }
 
-/** Narrow a filter member's field value to a `{ is: {...} } }` clause, if it is one. */
-function readIsClause(value: unknown): Record<string, unknown> | null {
-  if (!value || typeof value !== 'object') return null
-  const isValue = (value as Record<string, unknown>).is
-  if (!isValue || typeof isValue !== 'object') return null
-  return isValue as Record<string, unknown>
-}
-
-/**
- * Resolve one to-one relationship label-filter member into an access-scoped
- * condition by ANDing the related list's `query` access filter into the nested
- * `is` clause. Returns `{ id: { in: [] } }` (never matches) when the related
- * list is fully denied, the original member unchanged when it is fully
- * readable, and the `is` clause ANDed with the access filter otherwise.
- */
-async function resolveOneLabelFilter(
-  field: FieldConfig,
-  fieldName: string,
-  isClause: Record<string, unknown>,
-  args: LabelFilterArgs,
-  config: OpenSaasConfig,
-): Promise<Record<string, unknown>> {
-  if (!('ref' in field) || typeof field.ref !== 'string') {
-    return { [fieldName]: { is: isClause } }
-  }
-  const related = getRelatedListConfig(field.ref, config)
-  if (!related) return { [fieldName]: { is: isClause } }
-
-  const queryAccess = related.listConfig.access?.operation?.query
-  const result = await checkAccess(queryAccess, { session: args.session, context: args.context })
-
-  if (result === false) return { id: { in: [] } }
-  if (result === true) return { [fieldName]: { is: isClause } }
-  return { [fieldName]: { is: { AND: [result, isClause] } } }
-}
-
 /**
- * Replace any to-one relationship label-filter members in a filter `where`
- * with access-scoped equivalents. Label-filter members only ever appear as
- * top-level AND members (the relationship Filter spec does not declare
- * `freeText`, so it never participates in the free-text OR), so this walks
- * only the top level. Returns the `where` unchanged when it contains no such
- * members, so lists without to-one relationship filters pay nothing.
+ * No longer folds access into label filters — see the module doc above.
+ * Returns `where` unchanged.
  */
 export async function resolveRelationshipLabelFilters(
   where: Record<string, unknown> | undefined,
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
-  listConfig: ListConfig<any>,
-  args: LabelFilterArgs,
-  config: OpenSaasConfig,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo, kept for API compatibility (see module doc)
+  _listConfig: ListConfig<any>,
+  _args: LabelFilterArgs,
+  _config: OpenSaasConfig,
 ): Promise<Record<string, unknown> | undefined> {
-  if (!where) return where
-
-  const andValue = where.AND
-  const members: Array<Record<string, unknown>> = Array.isArray(andValue)
-    ? (andValue as Array<Record<string, unknown>>)
-    : [where]
-
-  const findLabelFilter = (
-    member: Record<string, unknown>,
-  ): { field: string; isClause: Record<string, unknown> } | null => {
-    for (const key of Object.keys(member)) {
-      const field = listConfig.fields[key]
-      if (!isToOneRelationshipField(field)) continue
-      const isClause = readIsClause(member[key])
-      if (!isClause) continue
-      return { field: key, isClause }
-    }
-    return null
-  }
-
-  if (!members.some((member) => findLabelFilter(member) !== null)) {
-    return where
-  }
-
-  const resolvedMembers: Array<Record<string, unknown>> = []
-  for (const member of members) {
-    const found = findLabelFilter(member)
-    if (!found) {
-      resolvedMembers.push(member)
-      continue
-    }
-    const field = listConfig.fields[found.field]
-    const resolved = await resolveOneLabelFilter(field, found.field, found.isClause, args, config)
-
-    const siblings: Record<string, unknown> = { ...member }
-    delete siblings[found.field]
-    resolvedMembers.push(mergeResolvedMember(siblings, resolved))
-  }
-
-  return resolvedMembers.length === 1 ? resolvedMembers[0] : { AND: resolvedMembers }
+  return where
 }

package/src/access/transaction-registry.ts

@@ -0,0 +1,58 @@
+/**
+ * Deferral registry for transaction-boundary hooks on a JOINED write (ADR-0028,
+ * issue #899).
+ *
+ * A write that joins a transaction it did not open — because the client it was
+ * handed exposes no way to open one (a Prisma transaction client, or a plain
+ * write issued from a hook whose context is rebound to one) — cannot itself
+ * observe when the enclosing transaction settles. Instead of firing
+ * `afterTransaction` optimistically at write time, it enqueues a flush here.
+ * The transaction owner (`context.transaction()`, or the Write Pipeline when it
+ * actually opens the transaction) drains the queue, in enqueue (write) order,
+ * once it observes its own transaction settle — supplying the real
+ * committed/rolled-back outcome.
+ *
+ * This is internal plumbing with no public surface: it is threaded through the
+ * same context-rebind path ADR-0010/0012 already use for `plugins` and
+ * `_resolveOutputChain` (see `AccessContext['_transactionOwner']`), never
+ * exposed on the public `StackContext` type.
+ */
+
+/**
+ * The outcome the transaction OWNER observed for the transaction as a whole —
+ * distinct from a single write's own {@link import('../hooks/index.js').TransactionOutcome},
+ * which additionally carries that write's own persisted `item` or `error`.
+ */
+export interface TransactionSettleOutcome {
+  status: 'committed' | 'rolled-back'
+  error?: unknown
+}
+
+/**
+ * One deferred write's flush: given the owner's settle outcome, runs that
+ * write's `afterTransaction` bracket and appends any hook errors to `errors`.
+ */
+export type QueuedTransactionFlush = (
+  settle: TransactionSettleOutcome,
+  errors: unknown[],
+) => Promise<void>
+
+/**
+ * A FIFO queue of deferred transaction-boundary flushes, owned by whichever
+ * component opened the enclosing transaction. One registry per owned
+ * transaction; a nested `context.transaction()` joins its enclosing owner's
+ * registry rather than creating a second one.
+ */
+export class TransactionRegistry {
+  private readonly queue: QueuedTransactionFlush[] = []
+
+  enqueue(flush: QueuedTransactionFlush): void {
+    this.queue.push(flush)
+  }
+
+  async drain(settle: TransactionSettleOutcome, errors: unknown[]): Promise<void> {
+    for (const flush of this.queue) {
+      await flush(settle, errors)
+    }
+  }
+}

package/src/access/types.ts

@@ -1,4 +1,5 @@
 import type { Fragment, FieldSelection, ResultOf } from '../query/index.js'
+import type { TransactionRegistry } from './transaction-registry.js'
 
 /**
  * Session interface - can be augmented by developers to add custom fields
@@ -37,9 +38,6 @@ export interface Session {
   [key: string]: unknown
 }
 
-/**
- * Generic Prisma model delegate type
- */
 export type PrismaModelDelegate = {
   findUnique: (args: unknown) => Promise<unknown>
   findFirst: (args: unknown) => Promise<unknown>
@@ -50,12 +48,8 @@ export type PrismaModelDelegate = {
   count: (args?: unknown) => Promise<number>
 }
 
-/**
- * Generic Prisma client type
- * This is intentionally permissive to allow actual PrismaClient types
- * Uses `any` because Prisma generates highly complex client types that are difficult to constrain
- * This type is used as a generic constraint and the actual type safety comes from TPrisma parameter
- */
+// Uses `any` because Prisma generates highly complex client types that are difficult
+// to constrain here; actual type safety comes from the TPrisma generic parameter.
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type PrismaClientLike = any
 
@@ -102,11 +96,9 @@ export type FindManyQueryArgs = {
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export interface AugmentedFindMany<TOriginal extends (...args: any[]) => any> {
-  // Overload 1: with query fragment — return type narrows to ResultOf<fragment>[]
   <TItem, TFields extends FieldSelection<TItem>>(
     args: FindManyQueryArgs & { query: Fragment<TItem, TFields> },
   ): Promise<ResultOf<Fragment<TItem, TFields>>[]>
-  // Overload 2: original Prisma behaviour
   (...args: Parameters<TOriginal>): ReturnType<TOriginal>
 }
 
@@ -144,11 +136,9 @@ export type FindFirstQueryArgs = {
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export interface AugmentedFindFirst<TOriginal extends (...args: any[]) => any> {
-  // Overload 1: with query fragment — return type narrows to ResultOf<fragment> | null
   <TItem, TFields extends FieldSelection<TItem>>(
     args: FindFirstQueryArgs & { query: Fragment<TItem, TFields> },
   ): Promise<ResultOf<Fragment<TItem, TFields>> | null>
-  // Overload 2: original Prisma behaviour
   (...args: Parameters<TOriginal>): ReturnType<TOriginal>
 }
 
@@ -171,23 +161,17 @@ export interface AugmentedFindFirst<TOriginal extends (...args: any[]) => any> {
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export interface AugmentedFindUnique<TOriginal extends (...args: any[]) => any> {
-  // Overload 1: with query fragment — return type narrows to ResultOf<fragment> | null
   <TItem, TFields extends FieldSelection<TItem>>(args: {
     where: Record<string, unknown>
     query: Fragment<TItem, TFields>
   }): Promise<ResultOf<Fragment<TItem, TFields>> | null>
-  // Overload 2: original Prisma behaviour
   (...args: Parameters<TOriginal>): ReturnType<TOriginal>
 }
 
-/**
- * Map Prisma client to access-controlled database context
- * Preserves Prisma's type information for each model
- */
 export type AccessControlledDB<TPrisma extends PrismaClientLike> = {
   [K in keyof TPrisma]: TPrisma[K] extends {
-    // Uses `any` in conditional type checks to verify Prisma model shape
-    // This is a standard TypeScript pattern for checking if a property exists with any signature
+    // Uses `any` here to check the property exists with any signature, a standard
+    // TypeScript pattern for verifying Prisma model shape in a conditional type.
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     findUnique: any
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -232,17 +216,7 @@ export type AccessControlledDB<TPrisma extends PrismaClientLike> = {
   [key: string]: any
 }
 
-/**
- * Storage utilities for file/image uploads
- */
 export type StorageUtils = {
-  /**
-   * Upload a file to storage
-   * @param providerName - Name of storage provider from config
-   * @param file - File object
-   * @param buffer - File contents as Buffer
-   * @param options - Upload options (validation, metadata)
-   */
   uploadFile: (
     providerName: string,
     file: File,
@@ -250,13 +224,6 @@ export type StorageUtils = {
     options?: unknown,
   ) => Promise<unknown>
 
-  /**
-   * Upload an image with transformations
-   * @param providerName - Name of storage provider from config
-   * @param file - File object
-   * @param buffer - File contents as Buffer
-   * @param options - Upload options (validation, transformations, metadata)
-   */
   uploadImage: (
     providerName: string,
     file: File,
@@ -264,24 +231,12 @@ export type StorageUtils = {
     options?: unknown,
   ) => Promise<unknown>
 
-  /**
-   * Delete a file from storage
-   * @param providerName - Name of storage provider from config
-   * @param filename - Name of file to delete
-   */
   deleteFile: (providerName: string, filename: string) => Promise<void>
 
-  /**
-   * Delete an image and all its transformations
-   * @param metadata - Image metadata containing storage provider and filename
-   */
   deleteImage: (metadata: unknown) => Promise<void>
 }
 
-/**
- * Context type (simplified for access control)
- * Using interface instead of type to allow module augmentation
- */
+// Uses `interface` rather than `type` so consumers can extend it via module augmentation.
 export interface AccessContext<TPrisma extends PrismaClientLike = PrismaClientLike> {
   session: Session | null
   prisma: TPrisma
@@ -303,16 +258,22 @@ export interface AccessContext<TPrisma extends PrismaClientLike = PrismaClientLi
    * in CONTEXT.md.
    */
   _resolveOutputChain: readonly { listKey: string; fieldKey: string }[]
+  /**
+   * Present when this context is JOINED into an enclosing transaction it did
+   * not open (ADR-0028, #899) — set by `context.transaction()`, or by the
+   * Write Pipeline when it opens the transaction the current write's hooks
+   * are rebound into. A write reached through a context carrying this defers
+   * its `afterTransaction` bracket to the registry instead of firing it at
+   * write time; `undefined` for a top-level context with no owner. Threaded
+   * through the same context-rebind path as `plugins`/`_resolveOutputChain`.
+   * @internal
+   */
+  _transactionOwner?: TransactionRegistry
 }
 
-/**
- * Prisma filter type - represents a where clause
- * Uses Partial to allow filtering by any subset of fields
- */
 export type PrismaFilter<T = Record<string, unknown>> = Partial<Record<keyof T, unknown>>
 
 /**
- * Access control function type
  * Can return:
  * - boolean: true = allow, false = deny
  * - PrismaFilter: Prisma where clause to filter results
@@ -324,51 +285,87 @@ export type AccessControl<T = Record<string, unknown>> = (args: {
 }) => boolean | PrismaFilter<T> | Promise<boolean | PrismaFilter<T>>
 
 /**
- * Field-level access control function.
+ * The per-operation argument shapes a `FieldAccessControl` function is called
+ * with — the discriminated union `FieldAccessControl` wraps, and the source
+ * of truth `FieldAccess`'s individual `read`/`create`/`update` members are
+ * picked from (via `Extract`) below. Keeping this as its own named type is
+ * what lets both sides reference the exact same three call shapes instead of
+ * two independently-maintained descriptions drifting apart.
+ */
+type FieldAccessControlArgs<TItem, TCreateInput, TUpdateInput> =
+  | {
+      session: Session | null
+      // Field Visibility (phase 2 of the two-phase read) always evaluates
+      // `read` rules against an already-fetched row — see
+      // `resolveReadableFieldValue` in `field-visibility.ts`, the sole
+      // caller of `checkFieldAccess` for this operation. Unlike `create`
+      // (where no row exists yet), there is no case where `item` is absent
+      // here, so it is required rather than optional.
+      item: TItem
+      context: AccessContext
+      inputData?: undefined
+      operation: 'read'
+    }
+  | {
+      session: Session | null
+      item?: undefined
+      context: AccessContext
+      inputData: TCreateInput
+      operation: 'create'
+    }
+  | {
+      session: Session | null
+      item: TItem
+      context: AccessContext
+      inputData: TUpdateInput
+      operation: 'update'
+    }
+
+/**
  * For create/update operations, receives inputData to validate incoming values.
  *
- * Note: While this type accepts filters for backward compatibility with AccessControl,
- * filters are ignored in field-level access. Only boolean results are used.
- * If a filter is returned, it defaults to allowing access (true).
+ * Unlike operation-level `AccessControl`, this returns `boolean` only. Field
+ * access is a per-field visibility decision, not a row filter — a denied
+ * field is removed, never used to scope which rows are returned (see the
+ * "Field-level access" glossary entry in `CONTEXT.md`, ADR-0001, and
+ * ADR-0030). A rule that needs to depend on the row or the write payload
+ * should evaluate the condition itself and return a boolean, e.g.
+ * `({ item, session }) => item?.ownerId === session?.userId`. The runtime
+ * evaluator (`checkFieldAccess`) enforces this: a rule that somehow returns
+ * anything other than `true`/`false` (bypassing this type) throws rather than
+ * defaulting to allow.
+ *
+ * This is the general, all-operations union — useful for a single function
+ * reused across more than one of `FieldAccess`'s `read`/`create`/`update`
+ * slots, narrowing on `operation` to tell the call shapes apart. A function
+ * written for exactly one slot doesn't need to: `FieldAccess` picks each
+ * slot's own single-operation shape out of this union (see below), so e.g. a
+ * `read`-only rule sees `item` as always present with no narrowing required.
  */
 export type FieldAccessControl<
   TItem = Record<string, unknown>,
   TCreateInput = Record<string, unknown>,
   TUpdateInput = Record<string, unknown>,
-> = (
-  args:
-    | {
-        session: Session | null
-        item?: undefined
-        context: AccessContext
-        inputData?: undefined
-        operation: 'read'
-      }
-    | {
-        session: Session | null
-        item?: undefined
-        context: AccessContext
-        inputData: TCreateInput
-        operation: 'create'
-      }
-    | {
-        session: Session | null
-        item: TItem
-        context: AccessContext
-        inputData: TUpdateInput
-        operation: 'update'
-      },
-) => boolean | PrismaFilter<TItem> | Promise<boolean | PrismaFilter<TItem>>
+> = (args: FieldAccessControlArgs<TItem, TCreateInput, TUpdateInput>) => boolean | Promise<boolean>
 
 /**
- * Field-level access control
+ * `read` is typed from the single `operation: 'read'` member of
+ * `FieldAccessControlArgs`, not the full `FieldAccessControl` union — so a
+ * rule written directly for this slot sees `item` as always present (never
+ * `TItem | undefined`) with no narrowing, cast, or `any` needed. A function
+ * typed as the broader `FieldAccessControl` union remains assignable here
+ * (and to `create`/`update`) — accepting more call shapes than the slot
+ * requires is a valid substitute, same as anywhere else function parameters
+ * are contravariant.
  */
 export type FieldAccess<
   TItem = Record<string, unknown>,
   TCreateInput = Record<string, unknown>,
   TUpdateInput = Record<string, unknown>,
 > = {
-  read?: FieldAccessControl<TItem, TCreateInput, TUpdateInput>
+  read?: (
+    args: Extract<FieldAccessControlArgs<TItem, TCreateInput, TUpdateInput>, { operation: 'read' }>,
+  ) => boolean | Promise<boolean>
   create?: FieldAccessControl<TItem, TCreateInput, TUpdateInput>
   update?: FieldAccessControl<TItem, TCreateInput, TUpdateInput>
 }