@opensaas/stack-core 0.37.0 → 0.39.0

package/src/filter/collect.ts

@@ -1,31 +1,65 @@
 import type { ListConfig, OpenSaasConfig } from '../config/types.js'
+import type { Session, AccessContext } from '../access/types.js'
+import { isFieldReadableForPredicate } from '../access/field-access.js'
 import { parseFilterQuery } from './parse.js'
 import { buildFilterWhere } from './map.js'
 import type { FilterCondition, FilterFieldSuggestion, FilterSpec } from './types.js'
 
+/**
+ * The session/context a field's `read` access is evaluated against — the same
+ * shape every other access-scoped admin-UI helper takes (e.g.
+ * `resolveRelationshipCountFilters`, `resolveRelationshipLabelFilters`).
+ */
+export type FilterAccessArgs = {
+  session: Session | null
+  context: AccessContext & { _isSudo?: boolean }
+}
+
 /**
  * Resolve every field's {@link FilterSpec} for a list by delegating to each
  * field's optional `getFilterSpec` method. A field without the method (or one
  * whose method returns `undefined`) is simply not filterable — the absence
  * degrades gracefully so third-party fields keep working.
  *
+ * A field the session cannot READ is excluded here too (#915), evaluated the
+ * same predicate-time way `context.db.*`'s `findMany`/`count` now enforce
+ * (`isFieldReadableForPredicate` — no fetched row exists yet, so a
+ * row-dependent `read` rule resolves to "not filterable"). This is what keeps
+ * the admin UI from ever suggesting, autocompleting, or submitting a filter
+ * the engine is going to reject: excluding the spec here means a token
+ * naming that field degrades to free text (`buildFilterWhere`'s existing
+ * "unknown field" path) rather than reaching `context.db` at all.
+ *
  * @param listConfig The list whose fields to inspect.
  * @param listKey    The list's key (passed through to each field's spec).
  * @param config     The full config (relationship specs resolve their target
  *   list's label field from it).
+ * @param args       The session/context to evaluate field-level `read` access
+ *   against.
  */
-export function collectFilterSpecs(
+export async function collectFilterSpecs(
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
   listConfig: ListConfig<any>,
   listKey: string,
   config: OpenSaasConfig,
-): Record<string, FilterSpec> {
+  args: FilterAccessArgs,
+): Promise<Record<string, FilterSpec>> {
   const specs: Record<string, FilterSpec> = {}
-  for (const [fieldName, field] of Object.entries(listConfig.fields)) {
-    if (typeof field.getFilterSpec !== 'function') continue
-    const spec = field.getFilterSpec(fieldName, listKey, config)
+  const filterableFields = Object.entries(listConfig.fields).filter(
+    ([, field]) => typeof field.getFilterSpec === 'function',
+  )
+  // Each field's read-access check is independent of every other's — run
+  // them concurrently rather than serially, since a `read` rule that does
+  // async work (e.g. a DB lookup) would otherwise add per-field latency to
+  // every list-view page render (found in review of #925).
+  const readableFlags = await Promise.all(
+    filterableFields.map(([, field]) => isFieldReadableForPredicate(field.access, args)),
+  )
+  filterableFields.forEach(([fieldName, field], index) => {
+    if (!readableFlags[index]) return
+    const spec = field.getFilterSpec!(fieldName, listKey, config)
     if (spec) specs[fieldName] = spec
-  }
+  })
   return specs
 }
 
@@ -38,14 +72,15 @@ export function collectFilterSpecs(
  *
  * @returns A `where` fragment, or `undefined` when the query filters nothing.
  */
-export function buildListFilterWhere(
+export async function buildListFilterWhere(
   query: string,
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
   listConfig: ListConfig<any>,
   listKey: string,
   config: OpenSaasConfig,
-): FilterCondition | undefined {
-  const specs = collectFilterSpecs(listConfig, listKey, config)
+  args: FilterAccessArgs,
+): Promise<FilterCondition | undefined> {
+  const specs = await collectFilterSpecs(listConfig, listKey, config, args)
   const tokens = parseFilterQuery(query)
   return buildFilterWhere(tokens, specs)
 }
@@ -56,13 +91,14 @@ export function buildListFilterWhere(
  * search). Carries no functions, so it can cross the server/client boundary to
  * drive the Filter builder's autocomplete.
  */
-export function collectFilterSuggestions(
+export async function collectFilterSuggestions(
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
   listConfig: ListConfig<any>,
   listKey: string,
   config: OpenSaasConfig,
-): FilterFieldSuggestion[] {
-  const specs = collectFilterSpecs(listConfig, listKey, config)
+  args: FilterAccessArgs,
+): Promise<FilterFieldSuggestion[]> {
+  const specs = await collectFilterSpecs(listConfig, listKey, config, args)
   return Object.entries(specs).map(([field, spec]) => ({
     field,
     operators: spec.operators,

package/src/filter/filter.test.ts

@@ -1,11 +1,34 @@
 import { describe, it, expect } from 'vitest'
 import { parseFilterQuery } from './parse.js'
 import { buildFilterWhere } from './map.js'
-import { buildListFilterWhere, collectFilterSpecs, collectFilterSuggestions } from './collect.js'
+import {
+  buildListFilterWhere,
+  collectFilterSpecs,
+  collectFilterSuggestions,
+  type FilterAccessArgs,
+} from './collect.js'
 import type { FilterSpec } from './types.js'
 import { list } from '../config/index.js'
-import { text, integer, select, checkbox, timestamp, relationship } from '../fields/index.js'
+import {
+  text,
+  integer,
+  bigInt,
+  select,
+  checkbox,
+  timestamp,
+  relationship,
+} from '../fields/index.js'
 import type { OpenSaasConfig } from '../config/types.js'
+import type { AccessContext } from '../access/types.js'
+
+// A permissive session/context — no field on any list under test declares
+// field-level `read` access unless a test says so, so every field is
+// filterable/sortable by default (matching `checkFieldAccess`'s own
+// allow-by-default for a field with no rule).
+const noAccessArgs: FilterAccessArgs = {
+  session: null,
+  context: { _isSudo: false } as unknown as AccessContext,
+}
 
 // ─────────────────────────────────────────────────────────────
 // parseFilterQuery — the pure query-string → tokens boundary (ADR-0017)
@@ -231,6 +254,7 @@ function makeConfig(): OpenSaasConfig {
         fields: {
           title: text(),
           views: integer(),
+          occurredAtMs: bigInt(),
           status: select({
             options: [
               { label: 'Draft', value: 'draft' },
@@ -250,10 +274,10 @@ describe('core field Filter specs', () => {
   const config = makeConfig()
   const postConfig = config.lists.Post
 
-  it('collectFilterSpecs resolves a spec for every filterable core field', () => {
-    const collected = collectFilterSpecs(postConfig, 'Post', config)
+  it('collectFilterSpecs resolves a spec for every filterable core field', async () => {
+    const collected = await collectFilterSpecs(postConfig, 'Post', config, noAccessArgs)
     expect(Object.keys(collected).sort()).toEqual(
-      ['author', 'featured', 'publishedAt', 'status', 'title', 'views'].sort(),
+      ['author', 'featured', 'occurredAtMs', 'publishedAt', 'status', 'title', 'views'].sort(),
     )
   })
 
@@ -270,6 +294,16 @@ describe('core field Filter specs', () => {
     expect(spec.toCondition('eq', 'abc')).toBeNull()
   })
 
+  it('bigInt supports comparisons, emits a bigint condition, and rejects non-integers', () => {
+    const spec = postConfig.fields.occurredAtMs.getFilterSpec!('occurredAtMs', 'Post', config)!
+    expect(spec.toCondition('gt', '9007199254740993')).toEqual({
+      occurredAtMs: { gt: 9007199254740993n },
+    })
+    expect(spec.toCondition('eq', '5')).toEqual({ occurredAtMs: { equals: 5n } })
+    expect(spec.toCondition('eq', 'abc')).toBeNull()
+    expect(spec.toCondition('eq', '1.5')).toBeNull()
+  })
+
   it('select matches by value or label and resolves to the stored value', () => {
     const spec = postConfig.fields.status.getFilterSpec!('status', 'Post', config)!
     expect(spec.toCondition('eq', 'Published')).toEqual({ status: { equals: 'published' } })
@@ -309,23 +343,68 @@ describe('core field Filter specs', () => {
     })
   })
 
-  it('does not produce specs for password/json/virtual (absence degrades gracefully)', () => {
+  it('does not produce specs for password/json/virtual (absence degrades gracefully)', async () => {
     // A list of non-filterable fields yields no specs at all.
-    const specsForUser = collectFilterSpecs(config.lists.User, 'User', config)
+    const specsForUser = await collectFilterSpecs(config.lists.User, 'User', config, noAccessArgs)
     // User only has `name` (text) → exactly one spec, proving non-text absence.
     expect(Object.keys(specsForUser)).toEqual(['name'])
   })
+
+  it('excludes a field the session cannot read (#915)', async () => {
+    const gatedConfig: OpenSaasConfig = {
+      db: { provider: 'sqlite', prismaClientConstructor: () => null as never },
+      lists: {
+        Organisation: list({
+          fields: {
+            name: text(),
+            billingAddress: text({ access: { read: () => false } }),
+          },
+        }),
+      },
+    }
+    const collected = await collectFilterSpecs(
+      gatedConfig.lists.Organisation,
+      'Organisation',
+      gatedConfig,
+      noAccessArgs,
+    )
+    expect(Object.keys(collected)).toEqual(['name'])
+  })
+
+  it('excludes a row-dependent read rule too — no row exists at predicate time (#915)', async () => {
+    const gatedConfig: OpenSaasConfig = {
+      db: { provider: 'sqlite', prismaClientConstructor: () => null as never },
+      lists: {
+        Organisation: list({
+          fields: {
+            name: text(),
+            billingAddress: text({
+              access: { read: ({ item, session }) => item.ownerId === session?.userId },
+            }),
+          },
+        }),
+      },
+    }
+    const collected = await collectFilterSpecs(
+      gatedConfig.lists.Organisation,
+      'Organisation',
+      gatedConfig,
+      noAccessArgs,
+    )
+    expect(Object.keys(collected)).toEqual(['name'])
+  })
 })
 
 describe('buildListFilterWhere (end-to-end over a real list config)', () => {
   const config = makeConfig()
 
-  it('composes parse + specs into a merged where', () => {
-    const where = buildListFilterWhere(
+  it('composes parse + specs into a merged where', async () => {
+    const where = await buildListFilterWhere(
       'status:Published views:>10 author:"Ada" hello',
       config.lists.Post,
       'Post',
       config,
+      noAccessArgs,
     )
     expect(where).toEqual({
       AND: [
@@ -339,8 +418,35 @@ describe('buildListFilterWhere (end-to-end over a real list config)', () => {
     })
   })
 
-  it('returns undefined for an all-whitespace query', () => {
-    expect(buildListFilterWhere('   ', config.lists.Post, 'Post', config)).toBeUndefined()
+  it('returns undefined for an all-whitespace query', async () => {
+    expect(
+      await buildListFilterWhere('   ', config.lists.Post, 'Post', config, noAccessArgs),
+    ).toBeUndefined()
+  })
+
+  it('a read-denied field degrades to free text instead of reaching the engine (#915)', async () => {
+    const gatedConfig: OpenSaasConfig = {
+      db: { provider: 'sqlite', prismaClientConstructor: () => null as never },
+      lists: {
+        Organisation: list({
+          fields: {
+            name: text(),
+            billingAddress: text({ access: { read: () => false } }),
+          },
+        }),
+      },
+    }
+    // `billingAddress:12` never produces `{ billingAddress: { contains: '12' } }`
+    // — the spec is excluded, so the token degrades to a free-text search for
+    // "12" across `name` (the only remaining free-text field) instead.
+    const where = await buildListFilterWhere(
+      'billingAddress:12',
+      gatedConfig.lists.Organisation,
+      'Organisation',
+      gatedConfig,
+      noAccessArgs,
+    )
+    expect(where).toEqual({ name: { contains: '12' } })
   })
 })
 
@@ -379,17 +485,28 @@ describe('to-many relationship Filter spec (count comparisons — issue #732)',
     expect(spec.suggestions.valueSource).toEqual({ kind: 'none' })
   })
 
-  it('end-to-end: buildListFilterWhere carries a count marker for `posts:>5`', () => {
+  it('end-to-end: buildListFilterWhere carries a count marker for `posts:>5`', async () => {
     const config = countConfig()
-    const where = buildListFilterWhere('posts:>5', config.lists.User, 'User', config)
+    const where = await buildListFilterWhere(
+      'posts:>5',
+      config.lists.User,
+      'User',
+      config,
+      noAccessArgs,
+    )
     expect(where).toEqual({ posts: { _countFilter: { operator: 'gt', value: 5 } } })
   })
 })
 
 describe('collectFilterSuggestions', () => {
-  it('returns serializable, function-free suggestion metadata', () => {
+  it('returns serializable, function-free suggestion metadata', async () => {
     const config = makeConfig()
-    const suggestions = collectFilterSuggestions(config.lists.Post, 'Post', config)
+    const suggestions = await collectFilterSuggestions(
+      config.lists.Post,
+      'Post',
+      config,
+      noAccessArgs,
+    )
     // No functions anywhere → JSON round-trips cleanly.
     expect(JSON.parse(JSON.stringify(suggestions))).toEqual(suggestions)
     const status = suggestions.find((s) => s.field === 'status')!
@@ -397,4 +514,25 @@ describe('collectFilterSuggestions', () => {
     const author = suggestions.find((s) => s.field === 'author')!
     expect(author.valueSource).toEqual({ kind: 'relationship', listKey: 'User', many: false })
   })
+
+  it('excludes a read-denied field from the suggestion metadata (#915)', async () => {
+    const gatedConfig: OpenSaasConfig = {
+      db: { provider: 'sqlite', prismaClientConstructor: () => null as never },
+      lists: {
+        Organisation: list({
+          fields: {
+            name: text(),
+            billingAddress: text({ access: { read: () => false } }),
+          },
+        }),
+      },
+    }
+    const suggestions = await collectFilterSuggestions(
+      gatedConfig.lists.Organisation,
+      'Organisation',
+      gatedConfig,
+      noAccessArgs,
+    )
+    expect(suggestions.map((s) => s.field)).toEqual(['name'])
+  })
 })

package/src/filter/index.ts

@@ -13,6 +13,7 @@ export { parseFilterQuery } from './parse.js'
 export { serializeFilterQuery } from './serialize.js'
 export { buildFilterWhere } from './map.js'
 export { collectFilterSpecs, buildListFilterWhere, collectFilterSuggestions } from './collect.js'
+export type { FilterAccessArgs } from './collect.js'
 export { RELATIONSHIP_COUNT_FILTER_KEY } from './types.js'
 export type {
   FilterOperator,

package/src/filter/map.ts

@@ -25,7 +25,6 @@ export function buildFilterWhere(
   const freeTextFields = Object.keys(specs).filter((field) => specs[field].freeText)
 
   for (const token of tokens) {
-    // Bare free-text word.
     if (token.field === null) {
       if (token.value) freeTextWords.push(token.value)
       continue
@@ -33,8 +32,6 @@ export function buildFilterWhere(
 
     const spec = specs[token.field]
 
-    // Unknown field / no spec / unsupported operator / empty value →
-    // degrade to free text (search the value across free-text fields).
     if (!spec || !spec.operators.includes(token.operator) || token.value === '') {
       if (token.value) freeTextWords.push(token.value)
       continue
@@ -42,7 +39,6 @@ export function buildFilterWhere(
 
     const condition = spec.toCondition(token.operator, token.value)
     if (condition === null) {
-      // Value couldn't be interpreted for this field → free text.
       freeTextWords.push(token.value)
       continue
     }
@@ -50,7 +46,6 @@ export function buildFilterWhere(
     andConditions.push(condition)
   }
 
-  // Each free-text word: OR across every free-text field's `eq` mapping.
   if (freeTextFields.length > 0) {
     for (const word of freeTextWords) {
       const orConditions = freeTextFields

package/src/filter/parse.ts

@@ -48,15 +48,11 @@ export function parseFilterQuery(query: string): FilterToken[] {
   let i = 0
 
   while (i < n) {
-    // Skip leading whitespace between tokens.
     while (i < n && isWhitespace(query[i])) i++
     if (i >= n) break
 
     const start = i
 
-    // Optional `field:` prefix. A URL scheme (`http://…`) is not a field
-    // prefix: when the colon is immediately followed by `//`, keep the whole
-    // token as free text so pasted URLs are searched verbatim.
     let field: string | null = null
     const prefixMatch = FIELD_PREFIX_RE.exec(query.slice(i))
     if (prefixMatch && !query.startsWith('//', i + prefixMatch[0].length)) {
@@ -64,8 +60,6 @@ export function parseFilterQuery(query: string): FilterToken[] {
       i += prefixMatch[0].length
     }
 
-    // Comparison operator prefix — only meaningful once a field is present.
-    // A leading `>`/`<` on a bare word is left as part of the free-text value.
     let operator: FilterOperator = 'eq'
     if (field) {
       if (query.startsWith('>=', i)) {
@@ -83,15 +77,14 @@ export function parseFilterQuery(query: string): FilterToken[] {
       }
     }
 
-    // Value: quoted (spaces kept) or a run up to the next whitespace.
     let value = ''
     if (query[i] === '"') {
-      i++ // opening quote
+      i++
       while (i < n && query[i] !== '"') {
         value += query[i]
         i++
       }
-      if (i < n) i++ // closing quote
+      if (i < n) i++
     } else {
       while (i < n && !isWhitespace(query[i])) {
         value += query[i]

package/src/filter/serialize.ts

@@ -56,13 +56,11 @@ export function serializeFilterQuery(tokens: FilterToken[]): string {
   const parts: string[] = []
 
   for (const token of tokens) {
-    // An empty value is not a filter — skip it rather than emit `field:` / `""`.
     if (token.value === '') continue
 
     if (token.field === null) {
-      // Bare free-text word. A leading `>`/`<` stays literal for bare words
-      // (the parser only treats them as operators after a `field:`), so no
-      // operator guard is needed here.
+      // A leading `>`/`<` stays literal for a bare word (the parser only
+      // treats them as operators after a `field:`), so no operator guard here.
       parts.push(quoteIfNeeded(token.value, false))
       continue
     }

package/src/hooks/index.ts

@@ -4,9 +4,6 @@ import type { FieldConfig } from '../config/types.js'
 import { validateWithZod } from '../validation/schema.js'
 import { checkFieldAccess } from '../access/field-access.js'
 
-/**
- * Validation error collection
- */
 export class ValidationError extends Error {
   public errors: string[]
   public fieldErrors: Record<string, string>
@@ -19,10 +16,7 @@ export class ValidationError extends Error {
   }
 }
 
-/**
- * Database error with field-specific error information
- * Used for Prisma errors like unique constraint violations
- */
+/** Used for Prisma errors like unique constraint violations. */
 export class DatabaseError extends Error {
   public fieldErrors: Record<string, string>
   public code?: string
@@ -35,10 +29,6 @@ export class DatabaseError extends Error {
   }
 }
 
-/**
- * Execute resolveInput hook
- * Allows modification of input data before validation
- */
 export async function executeResolveInput<
   TOutput = Record<string, unknown>,
   TCreateInput = Record<string, unknown>,
@@ -71,10 +61,7 @@ export async function executeResolveInput<
   return result
 }
 
-/**
- * Execute validate hook (supports both 'validate' and deprecated 'validateInput')
- * Allows custom validation logic
- */
+/** Supports both `validate` and the deprecated `validateInput` alias for backwards compatibility. */
 export async function executeValidate<
   TOutput = Record<string, unknown>,
   TCreateInput = Record<string, unknown>,
@@ -105,7 +92,6 @@ export async function executeValidate<
         context: AccessContext
       },
 ): Promise<void> {
-  // Support both 'validate' (new) and 'validateInput' (deprecated) for backwards compatibility
   const validateHook = hooks?.validate || hooks?.validateInput
   if (!validateHook) {
     return
@@ -132,10 +118,7 @@ export async function executeValidate<
  */
 export const executeValidateInput = executeValidate
 
-/**
- * Execute beforeOperation hook
- * Runs before database operation (cannot modify data)
- */
+/** Side effects only — cannot modify data before the database write. */
 export async function executeBeforeOperation<
   TOutput = Record<string, unknown>,
   TCreateInput = Record<string, unknown>,
@@ -172,10 +155,6 @@ export async function executeBeforeOperation<
   await hooks.beforeOperation(args as Parameters<typeof hooks.beforeOperation>[0])
 }
 
-/**
- * Execute afterOperation hook
- * Runs after database operation
- */
 export async function executeAfterOperation<
   TOutput = Record<string, unknown>,
   TCreateInput = Record<string, unknown>,
@@ -410,7 +389,6 @@ export async function executeFieldAfterTransactionHooks(
   isTopLevel: boolean,
   originalItem?: Record<string, unknown>,
 ): Promise<void> {
-  // The persisted/pre-write rows are surfaced only for the top-level list.
   const committedItem = outcome.status === 'committed' && isTopLevel ? outcome.item : undefined
   const committedOriginalItem = isTopLevel ? originalItem : undefined
 
@@ -449,7 +427,6 @@ export async function executeFieldAfterTransactionHooks(
       continue
     }
 
-    // committed
     if (operation === 'delete') {
       await fieldConfig.hooks.afterTransaction({
         ...base,
@@ -479,9 +456,6 @@ export async function executeFieldAfterTransactionHooks(
 }
 
 /**
- * Execute field-level resolveInput hooks
- * Allows fields to transform their input values before database write
- *
  * NOTE (#789): multi-column fields (e.g. storage image()/file() in
  * Keystone-parity mode) are NOT split here. This phase only resolves each
  * field's value under its LOGICAL key, so that phases 2-3 (list/field
@@ -506,11 +480,9 @@ export async function executeFieldResolveInputHooks(
   let result = { ...resolvedData }
 
   for (const [fieldKey, fieldConfig] of Object.entries(fields)) {
-    // Skip if field not in data, or if there's nothing to resolve
     if (!(fieldKey in result)) continue
     if (!fieldConfig.hooks?.resolveInput) continue
 
-    // Execute field hook
     // Type assertion is safe here because hooks are typed correctly in field definitions
     // and we're working with runtime values that match those types
     const resolvedValue = await fieldConfig.hooks.resolveInput({
@@ -595,10 +567,7 @@ export async function splitMultiColumnFields(
   return result
 }
 
-/**
- * Execute field-level validate hooks
- * Allows fields to perform custom validation after resolveInput but before database write
- */
+/** Runs after resolveInput and before the database write. */
 export async function executeFieldValidateHooks(
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   inputData: Record<string, any> | undefined,
@@ -620,11 +589,10 @@ export async function executeFieldValidateHooks(
   }
 
   for (const [fieldKey, fieldConfig] of Object.entries(fields)) {
-    // Support both 'validate' (new) and 'validateInput' (deprecated) for backwards compatibility
+    // validate / deprecated validateInput fallback — see executeValidate
     const validateHook = fieldConfig.hooks?.validate ?? fieldConfig.hooks?.validateInput
     if (!validateHook) continue
 
-    // Execute field hook
     // Type assertion is safe here because hooks are typed correctly in field definitions
     if (operation === 'delete') {
       await validateHook({
@@ -647,7 +615,6 @@ export async function executeFieldValidateHooks(
         addValidationError: addValidationError(fieldKey),
       } as Parameters<typeof validateHook>[0])
     } else {
-      // operation === 'update'
       await validateHook({
         listKey,
         fieldKey,
@@ -666,10 +633,6 @@ export async function executeFieldValidateHooks(
   }
 }
 
-/**
- * Execute field-level beforeOperation hooks (side effects only)
- * Allows fields to perform side effects before database write
- */
 export async function executeFieldBeforeOperationHooks(
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   inputData: Record<string, any>,
@@ -683,13 +646,9 @@ export async function executeFieldBeforeOperationHooks(
   item?: any,
 ): Promise<void> {
   for (const [fieldKey, fieldConfig] of Object.entries(fields)) {
-    // Skip if no hooks defined
     if (!fieldConfig.hooks?.beforeOperation) continue
-    // Skip if field not in data (for create/update)
     if (operation !== 'delete' && !(fieldKey in resolvedData)) continue
 
-    // Execute field hook (side effects only, no return value used)
-    // Type assertion is safe here because hooks are typed correctly in field definitions
     if (operation === 'delete') {
       await fieldConfig.hooks.beforeOperation({
         listKey,
@@ -708,7 +667,6 @@ export async function executeFieldBeforeOperationHooks(
         context,
       } as Parameters<typeof fieldConfig.hooks.beforeOperation>[0])
     } else {
-      // operation === 'update'
       await fieldConfig.hooks.beforeOperation({
         listKey,
         fieldKey,
@@ -722,10 +680,6 @@ export async function executeFieldBeforeOperationHooks(
   }
 }
 
-/**
- * Execute field-level afterOperation hooks (side effects only)
- * Allows fields to perform side effects after database operations
- */
 export async function executeFieldAfterOperationHooks(
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   item: any,
@@ -739,10 +693,8 @@ export async function executeFieldAfterOperationHooks(
   originalItem?: any,
 ): Promise<void> {
   for (const [fieldKey, fieldConfig] of Object.entries(fields)) {
-    // Skip if no hooks defined
     if (!fieldConfig.hooks?.afterOperation) continue
 
-    // Execute field hook (side effects only, no return value used)
     if (operation === 'delete') {
       await fieldConfig.hooks.afterOperation({
         listKey,
@@ -762,7 +714,6 @@ export async function executeFieldAfterOperationHooks(
         context,
       } as Parameters<typeof fieldConfig.hooks.afterOperation>[0])
     } else {
-      // operation === 'update'
       await fieldConfig.hooks.afterOperation({
         listKey,
         fieldKey,
@@ -777,10 +728,6 @@ export async function executeFieldAfterOperationHooks(
   }
 }
 
-/**
- * Validate field-level validation rules using Zod
- * Checks isRequired, length constraints, etc.
- */
 export function validateFieldRules(
   data: Record<string, unknown>,
   fieldConfigs: Record<string, FieldConfig>,
@@ -792,7 +739,6 @@ export function validateFieldRules(
     return { errors: [], fieldErrors: {} }
   }
 
-  // Convert field errors to array of error messages
   const errors = Object.entries(result.errors).map(([_field, message]) => message)
 
   return { errors, fieldErrors: result.errors }