@opensaas/stack-core 0.37.0 → 0.39.0

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>
 }

package/src/config/index.ts

@@ -8,16 +8,11 @@ import type {
 import { executePlugins } from './plugin-engine.js'
 import type { AccessControl } from '../access/types.js'
 
-/**
- * Normalize access control shorthand to object form
- * Converts function shorthand to { operation: { query, create, update, delete } } form
- */
 function normalizeListAccess<T>(
   access: ListAccessControl<T> | undefined,
 ): { operation?: OperationAccess<T> } | undefined {
   if (!access) return undefined
 
-  // If it's a function, convert to object form applying to all operations
   if (typeof access === 'function') {
     const fn = access as AccessControl<T>
     return {
@@ -30,32 +25,31 @@ function normalizeListAccess<T>(
     }
   }
 
-  // Already in object form
   return access
 }
 
 /**
- * Helper function to define configuration with type safety
- * Executes plugins if present in config.plugins array
+ * Define an OpenSaas config, executing `plugins` if present.
  *
- * Note: This function is now async when plugins are present
- * For synchronous config definition without plugins, config can still be returned directly
+ * Returns synchronously when there are no plugins (backward compatible);
+ * returns a `Promise` when plugins are present, since plugin execution is
+ * async.
  */
 export function config(userConfig: OpenSaasConfig): OpenSaasConfig | Promise<OpenSaasConfig> {
-  // If no plugins, return config as-is (synchronous, backward compatible)
   if (!userConfig.plugins || userConfig.plugins.length === 0) {
     return userConfig
   }
 
-  // Execute plugins and return promise
   return executePlugins(userConfig)
 }
 
 /**
- * Helper function to define a list with type safety
+ * Define a list with type safety.
  *
- * Accepts raw field configs and transforms them to inject the item type
- * This enables proper typing in field hooks where item is typed correctly
+ * `ListConfigInput<TTypeInfo>` accepts raw field configs; the return type
+ * `ListConfig<TTypeInfo>` injects `TTypeInfo` so hook/field callbacks (e.g.
+ * `resolveInput`'s `item`) are properly typed once `TTypeInfo` is supplied
+ * from generated types.
  *
  * @example
  * ```typescript
@@ -108,18 +102,15 @@ export function config(userConfig: OpenSaasConfig): OpenSaasConfig | Promise<Ope
 export function list<TTypeInfo extends import('./types.js').TypeInfo>(
   config: ListConfigInput<TTypeInfo>,
 ): ListConfig<TTypeInfo> {
-  // Normalize access control shorthand to object form
   const normalizedConfig = {
     ...config,
     access: normalizeListAccess(config.access),
   }
 
-  // At runtime, field configs are unchanged
-  // At type level, they're transformed to inject TypeInfo types
+  // Runtime shape is unchanged; the cast only narrows the TS type to inject TTypeInfo.
   return normalizedConfig as ListConfig<TTypeInfo>
 }
 
-// Re-export all types
 export type {
   OpenSaasConfig,
   OutputConfig,
@@ -171,16 +162,13 @@ export type {
   FileMetadata,
   ImageMetadata,
   ImageTransformationResult,
-  // Plugin system types
   Plugin,
   PluginContext,
   GeneratedFiles,
-  // List-level hook argument types
   ResolveInputHookArgs,
   ValidateHookArgs,
   BeforeOperationHookArgs,
   AfterOperationHookArgs,
-  // Field-level hook argument types
   FieldResolveInputHookArgs,
   FieldValidateHookArgs,
   FieldBeforeOperationHookArgs,

package/src/config/label.ts

@@ -1,16 +1,11 @@
 import type { ListConfig } from './types.js'
 
 /**
- * Resolve the field name that represents a list's rows as a single label —
- * the projection half of the label seam. `getItemLabel` reads exactly the
- * field this returns, so the field chosen for projection can never drift
- * from the field used for rendering.
+ * Resolve the field name used as a list's Label field: `ui.labelField` if
+ * set, else `name`, else `title`, else `id`.
  *
- * Fallback order: configured `ui.labelField` → `name` → `title` → `id`
- * (first field that exists on the list).
- *
- * @throws if `ui.labelField` is set but does not reference a declared,
- * non-relationship field on the list.
+ * @throws if `ui.labelField` names a field not declared on the list, or a
+ * relationship field (the Label field must be a scalar).
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
 export function getLabelFieldName(listConfig: ListConfig<any>): string {
@@ -37,10 +32,8 @@ export function getLabelFieldName(listConfig: ListConfig<any>): string {
 }
 
 /**
- * Resolve the display label for a single row — the render half of the label
- * seam. Reads the field `getLabelFieldName` resolves, falling back to `id`
- * when that field is missing from the row (e.g. stripped by field-level
- * access).
+ * Render a row's Label field ({@link getLabelFieldName}) as text, falling
+ * back to `item.id` when the value is `null`/`undefined`.
  */
 export function getItemLabel(
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo