@opensaas/stack-core 0.39.2 → 0.41.0

package/src/access/relationship-count.ts

@@ -1,8 +1,9 @@
-import type { Session, AccessContext, PrismaFilter } from './types.js'
+import type { Session, AccessContext, PrismaFilter, FieldAccess } from './types.js'
 import type { OpenSaasConfig, ListConfig, FieldConfig } from '../config/types.js'
 import type { FilterOperator, RelationshipCountFilterMarker } from '../filter/types.js'
 import { RELATIONSHIP_COUNT_FILTER_KEY } from '../filter/types.js'
 import { checkAccess, getRelatedListConfig } from './engine.js'
+import { isFieldReadableForPredicate } from './field-access.js'
 import { getDbKey } from '../lib/case-utils.js'
 
 /**
@@ -14,8 +15,10 @@ import { getDbKey } from '../lib/case-utils.js'
  * `_count` (`_count: { select: { orders: { where: <access filter> } } }`), so no
  * per-row query is issued and the count can never include rows the session
  * cannot read. This module is the single place the related list's
- * operation-level `query` access is folded into that `_count`, mirroring how
- * `buildAccessScopedInclude` folds it into relation includes.
+ * operation-level `query` access, AND the counting list's own field-level
+ * `read` access on the relationship field being counted (issue #1111), are
+ * folded into that `_count`, mirroring how `buildAccessScopedInclude` folds
+ * both into relation includes.
  *
  * It also resolves the count Filter spec's markers: Prisma cannot compare a
  * relation count in a `where`, so a to-many relationship's Filter spec emits a
@@ -46,11 +49,56 @@ export function isToManyRelationshipField(field: FieldConfig | undefined): boole
 }
 
 /** The per-relation entry the count `_count.select` uses for one relationship. */
-type CountAccessEntry =
+export type CountAccessEntry =
   | { kind: 'all' } // related list fully readable → count every related row
   | { kind: 'scoped'; where: PrismaFilter } // count only rows matching the access filter
   | { kind: 'denied' } // related list not readable at all → count is always 0
 
+/**
+ * Resolve one related list's operation-level `query` access, and — when the
+ * counting list has a field of its own for the relationship being counted —
+ * that field's own field-level `read` access, into the entry its `_count`
+ * select needs. The shared decision both `relationshipCountAccessEntry` below
+ * (field → related list, for this module's own admin-list-view and
+ * count-filter callers) and `access-filter.ts`'s caller-`_count` scoping
+ * (issue #1087, which already has the related list resolved — including a
+ * synthetic back-relation's, which has no field of its own on the counting
+ * list) build on.
+ *
+ * `fieldAccess` is the COUNTING list's own relationship field access — not
+ * the related list's — mirroring the check `filterReadableFields`
+ * (`field-visibility.ts`) runs before returning an ordinary `include` of that
+ * same field (issue #1111: a `_count` used to leak the true count of a
+ * relationship whose field-level `read` access denied the relationship
+ * itself, even when the related list's own rows were otherwise fully
+ * readable). Evaluated via `isFieldReadableForPredicate` — the pre-query
+ * evaluator #915 already built for the identical problem on `where`/`orderBy`
+ * — since there is no fetched row yet at `_count`-select-build time; a rule
+ * that depends on one denies here, the same as it would there. Checked BEFORE
+ * the related list's `query` access so a field-level denial short-circuits
+ * without needing the related list's access rule at all. Omitted entirely
+ * (`undefined`) for a synthetic back-relation, which has no field of its own
+ * on the counting list to evaluate.
+ */
+export async function resolveCountAccessEntryForList(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
+  relatedListConfig: ListConfig<any>,
+  args: CountArgs,
+  fieldAccess?: FieldAccess,
+): Promise<CountAccessEntry> {
+  if (fieldAccess) {
+    const canReadField = await isFieldReadableForPredicate(fieldAccess, args)
+    if (!canReadField) return { kind: 'denied' }
+  }
+
+  const queryAccess = relatedListConfig.access?.operation?.query
+  const result = await checkAccess(queryAccess, { session: args.session, context: args.context })
+
+  if (result === false) return { kind: 'denied' }
+  if (typeof result === 'object') return { kind: 'scoped', where: result }
+  return { kind: 'all' }
+}
+
 /**
  * Resolve the related list's operation-level `query` access for one to-many
  * relationship into the entry its `_count` select needs. Returns `null` when the
@@ -69,12 +117,7 @@ async function relationshipCountAccessEntry(
   const related = getRelatedListConfig(ref, config)
   if (!related) return null
 
-  const queryAccess = related.listConfig.access?.operation?.query
-  const result = await checkAccess(queryAccess, { session: args.session, context: args.context })
-
-  if (result === false) return { kind: 'denied' }
-  if (typeof result === 'object') return { kind: 'scoped', where: result }
-  return { kind: 'all' }
+  return resolveCountAccessEntryForList(related.listConfig, args, field.access)
 }
 
 /**

package/src/access/synthetic-include-read.test.ts

@@ -0,0 +1,179 @@
+import { describe, it, expect } from 'vitest'
+import { filterReadableFields } from './field-visibility.js'
+import type { OpenSaasConfig, FieldConfig } from '../config/types.js'
+import type { AccessContext } from './types.js'
+
+/**
+ * Regression coverage for issue #1082, Field Visibility half.
+ *
+ * `access-filter.test.ts` covers the pre-query scoping of a synthetic
+ * back-relation (`buildAccessScopedInclude`); these tests cover what happens
+ * to the rows it fetches. Before this fix, `filterReadableFields` recognised
+ * only a DECLARED relationship field (`fieldConfig?.type === 'relationship'`)
+ * as something to recurse into — a synthetic key has no declared field on the
+ * list it's fetched through, so it fell to the generic non-relationship
+ * branch and was copied into the result verbatim: no field-level `read` gate
+ * on the related rows, and no virtual field computed on them.
+ */
+
+// A relationship field pointing at another list.
+function rel(ref: string, many = false): FieldConfig {
+  return { type: 'relationship', ref, many } as unknown as FieldConfig
+}
+
+// A virtual field computed via resolveOutput.
+function virtualField(
+  resolveOutput: (args: { item: Record<string, unknown> }) => unknown,
+): FieldConfig {
+  return {
+    type: 'virtual',
+    virtual: true,
+    hooks: { resolveOutput },
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- minimal field config for unit test
+  } as any as FieldConfig
+}
+
+function makeContext(): AccessContext {
+  return {
+    session: null,
+    _isSudo: false,
+    _resolveOutputChain: [],
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- minimal context for unit test
+  } as any
+}
+
+// Term ← Bill.term (list-only ref, no field on Term) — schema generation
+// synthesizes `from_Bill_term` on Term, which no list config declares.
+function syntheticConfig(): OpenSaasConfig {
+  return {
+    db: { provider: 'sqlite' },
+    lists: {
+      Term: {
+        fields: { name: { type: 'text' } as FieldConfig },
+        access: { operation: { query: () => true } },
+      },
+      Bill: {
+        fields: {
+          amount: { type: 'integer' } as FieldConfig,
+          term: rel('Term'),
+          internalNotes: {
+            type: 'text',
+            access: { read: () => false },
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any -- minimal field config for unit test
+          } as any as FieldConfig,
+          label: virtualField(({ item }) => `Bill #${item.amount}`),
+        },
+        access: { operation: { query: () => true } },
+      },
+    },
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- minimal config for unit test
+  } as any as OpenSaasConfig
+}
+
+describe('filterReadableFields — synthetic back-relation (#1082)', () => {
+  it('applies the owning list field-level read access to rows fetched through a synthetic key', async () => {
+    const config = syntheticConfig()
+    const termRow = {
+      id: 't1',
+      name: 'Term 1',
+      from_Bill_term: [{ id: 'b1', amount: 5, internalNotes: 'secret' }],
+    }
+
+    const result = await filterReadableFields(
+      termRow,
+      config.lists.Term.fields,
+      { session: null, context: makeContext() },
+      config,
+      0,
+      'Term',
+    )
+
+    const bills = result.from_Bill_term as Record<string, unknown>[]
+    expect(bills).toHaveLength(1)
+    expect(bills[0].amount).toBe(5)
+    expect('internalNotes' in bills[0]).toBe(false)
+  })
+
+  it('computes a virtual field on rows fetched through a synthetic key', async () => {
+    const config = syntheticConfig()
+    const termRow = {
+      id: 't1',
+      name: 'Term 1',
+      from_Bill_term: [{ id: 'b1', amount: 5 }],
+    }
+
+    const result = await filterReadableFields(
+      termRow,
+      config.lists.Term.fields,
+      { session: null, context: makeContext() },
+      config,
+      0,
+      'Term',
+    )
+
+    const bills = result.from_Bill_term as Record<string, unknown>[]
+    expect(bills[0].label).toBe('Bill #5')
+  })
+
+  it('recurses through a to-one value fetched through a synthetic key the same as a to-many', async () => {
+    const config = syntheticConfig()
+    const termRow = {
+      id: 't1',
+      name: 'Term 1',
+      from_Bill_term: { id: 'b1', amount: 5, internalNotes: 'secret' },
+    }
+
+    const result = await filterReadableFields(
+      termRow,
+      config.lists.Term.fields,
+      { session: null, context: makeContext() },
+      config,
+      0,
+      'Term',
+    )
+
+    const bill = result.from_Bill_term as Record<string, unknown>
+    expect(bill.amount).toBe(5)
+    expect(bill.label).toBe('Bill #5')
+    expect('internalNotes' in bill).toBe(false)
+  })
+
+  it('leaves a declared, non-relationship field on the row untouched by the synthetic path', async () => {
+    // `name` is a declared scalar field on Term itself — the synthetic
+    // fallback only ever applies to a key ABSENT from `fieldConfigs`, so it
+    // must never interfere with the list's own ordinary fields.
+    const config = syntheticConfig()
+    const termRow = { id: 't1', name: 'Term 1' }
+
+    const result = await filterReadableFields(
+      termRow,
+      config.lists.Term.fields,
+      { session: null, context: makeContext() },
+      config,
+      0,
+      'Term',
+    )
+
+    expect(result).toEqual({ id: 't1', name: 'Term 1' })
+  })
+
+  it('leaves an undeclared, non-synthetic key untouched (no config supplied)', async () => {
+    // Mirrors the pre-#1082 narrow-unit-test contract: without `config`
+    // there is nothing to resolve a synthetic key against, so the field
+    // passes through as a plain value — the same fallback
+    // `filterWritableFields` documents for its own `config`-less callers.
+    const config = syntheticConfig()
+    const termRow = { id: 't1', name: 'Term 1', from_Bill_term: [{ id: 'b1', amount: 5 }] }
+
+    const result = await filterReadableFields(
+      termRow,
+      config.lists.Term.fields,
+      { session: null, context: makeContext() },
+      undefined,
+      0,
+      'Term',
+    )
+
+    expect(result.from_Bill_term).toEqual([{ id: 'b1', amount: 5 }])
+  })
+})

package/src/config/types.ts

@@ -21,7 +21,7 @@ export type FieldResolveInputHookArgs<
       inputData: TTypeInfo['inputs']['create']
       item: undefined
       resolvedData: TTypeInfo['inputs']['create']
-      context: import('../access/types.js').AccessContext
+      context: import('../context/index.js').StackContext
     }
   | {
       listKey: string
@@ -30,7 +30,7 @@ export type FieldResolveInputHookArgs<
       inputData: TTypeInfo['inputs']['update']
       item: TTypeInfo['item']
       resolvedData: TTypeInfo['inputs']['update']
-      context: import('../access/types.js').AccessContext
+      context: import('../context/index.js').StackContext
     }
 
 /** Arguments for {@link FieldHooks.validate} (and its deprecated `validateInput` alias). */
@@ -45,7 +45,7 @@ export type FieldValidateHookArgs<
       inputData: TTypeInfo['inputs']['create']
       item: undefined
       resolvedData: TTypeInfo['inputs']['create']
-      context: import('../access/types.js').AccessContext
+      context: import('../context/index.js').StackContext
       addValidationError: (msg: string) => void
     }
   | {
@@ -55,7 +55,7 @@ export type FieldValidateHookArgs<
       inputData: TTypeInfo['inputs']['update']
       item: TTypeInfo['item']
       resolvedData: TTypeInfo['inputs']['update']
-      context: import('../access/types.js').AccessContext
+      context: import('../context/index.js').StackContext
       addValidationError: (msg: string) => void
     }
   | {
@@ -63,7 +63,7 @@ export type FieldValidateHookArgs<
       fieldKey: TFieldKey
       operation: 'delete'
       item: TTypeInfo['item']
-      context: import('../access/types.js').AccessContext
+      context: import('../context/index.js').StackContext
       addValidationError: (msg: string) => void
     }
 
@@ -78,7 +78,7 @@ export type FieldBeforeOperationHookArgs<
       operation: 'create'
       inputData: TTypeInfo['inputs']['create']
       resolvedData: TTypeInfo['inputs']['create']
-      context: import('../access/types.js').AccessContext
+      context: import('../context/index.js').StackContext
     }
   | {
       listKey: string
@@ -87,14 +87,14 @@ export type FieldBeforeOperationHookArgs<
       inputData: TTypeInfo['inputs']['update']
       item: TTypeInfo['item']
       resolvedData: TTypeInfo['inputs']['update']
-      context: import('../access/types.js').AccessContext
+      context: import('../context/index.js').StackContext
     }
   | {
       listKey: string
       fieldKey: TFieldKey
       operation: 'delete'
       item: TTypeInfo['item']
-      context: import('../access/types.js').AccessContext
+      context: import('../context/index.js').StackContext
     }
 
 /** Arguments for {@link FieldHooks.afterOperation}. */
@@ -109,7 +109,7 @@ export type FieldAfterOperationHookArgs<
       inputData: TTypeInfo['inputs']['create']
       item: TTypeInfo['item']
       resolvedData: TTypeInfo['inputs']['create']
-      context: import('../access/types.js').AccessContext
+      context: import('../context/index.js').StackContext
     }
   | {
       listKey: string
@@ -119,14 +119,14 @@ export type FieldAfterOperationHookArgs<
       originalItem: TTypeInfo['item']
       item: TTypeInfo['item']
       resolvedData: TTypeInfo['inputs']['update']
-      context: import('../access/types.js').AccessContext
+      context: import('../context/index.js').StackContext
     }
   | {
       listKey: string
       fieldKey: TFieldKey
       operation: 'delete'
       originalItem: TTypeInfo['item']
-      context: import('../access/types.js').AccessContext
+      context: import('../context/index.js').StackContext
     }
 
 /**
@@ -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>
@@ -1551,7 +1609,7 @@ export type ResolveInputHookArgs<
       inputData: TCreateInput
       resolvedData: TCreateInput
       item: undefined
-      context: import('../access/types.js').AccessContext
+      context: import('../context/index.js').StackContext
     }
   | {
       listKey: string
@@ -1559,7 +1617,7 @@ export type ResolveInputHookArgs<
       inputData: TUpdateInput
       resolvedData: TUpdateInput
       item: TOutput
-      context: import('../access/types.js').AccessContext
+      context: import('../context/index.js').StackContext
     }
 
 /**
@@ -1579,7 +1637,7 @@ export type ValidateHookArgs<
       inputData: TCreateInput
       resolvedData: TCreateInput
       item: undefined
-      context: import('../access/types.js').AccessContext
+      context: import('../context/index.js').StackContext
       addValidationError: (msg: string) => void
     }
   | {
@@ -1588,14 +1646,14 @@ export type ValidateHookArgs<
       inputData: TUpdateInput
       resolvedData: TUpdateInput
       item: TOutput
-      context: import('../access/types.js').AccessContext
+      context: import('../context/index.js').StackContext
       addValidationError: (msg: string) => void
     }
   | {
       listKey: string
       operation: 'delete'
       item: TOutput
-      context: import('../access/types.js').AccessContext
+      context: import('../context/index.js').StackContext
       addValidationError: (msg: string) => void
     }
 
@@ -1615,7 +1673,7 @@ export type BeforeOperationHookArgs<
       operation: 'create'
       inputData: TCreateInput
       resolvedData: TCreateInput
-      context: import('../access/types.js').AccessContext
+      context: import('../context/index.js').StackContext
     }
   | {
       listKey: string
@@ -1623,13 +1681,13 @@ export type BeforeOperationHookArgs<
       inputData: TUpdateInput
       item: TOutput
       resolvedData: TUpdateInput
-      context: import('../access/types.js').AccessContext
+      context: import('../context/index.js').StackContext
     }
   | {
       listKey: string
       operation: 'delete'
       item: TOutput
-      context: import('../access/types.js').AccessContext
+      context: import('../context/index.js').StackContext
     }
 
 /**
@@ -1649,7 +1707,7 @@ export type AfterOperationHookArgs<
       inputData: TCreateInput
       item: TOutput
       resolvedData: TCreateInput
-      context: import('../access/types.js').AccessContext
+      context: import('../context/index.js').StackContext
     }
   | {
       listKey: string
@@ -1658,13 +1716,13 @@ export type AfterOperationHookArgs<
       originalItem: TOutput
       item: TOutput
       resolvedData: TUpdateInput
-      context: import('../access/types.js').AccessContext
+      context: import('../context/index.js').StackContext
     }
   | {
       listKey: string
       operation: 'delete'
       originalItem: TOutput
-      context: import('../access/types.js').AccessContext
+      context: import('../context/index.js').StackContext
     }
 
 /**
@@ -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/hook-pipeline.ts

@@ -1,5 +1,5 @@
 import type { ListConfig } from '../config/types.js'
-import type { AccessContext } from '../access/types.js'
+import type { StackContext } from './index.js'
 import {
   executeResolveInput,
   executeValidate,
@@ -25,7 +25,9 @@ export interface HookPipelineArgs {
   listConfig: ListConfig<any>
   inputData: Record<string, unknown>
   item: Record<string, unknown> | undefined
-  context: AccessContext
+  // #1176: the full secured context (sudo/withSession/transaction), bound to
+  // the write's transaction client — see `bindContextToTransaction`.
+  context: StackContext
 }
 
 export interface HookPipelineResult {