@opensaas/stack-core 0.38.0 → 0.39.0

package/src/config/types.ts

@@ -2,9 +2,6 @@ import type { AccessControl, FieldAccess } from '../access/types.js'
 import type { FilterSpec } from '../filter/types.js'
 import type { z } from 'zod'
 
-/**
- * Field configuration types
- */
 export type FieldType =
   'text' | 'integer' | 'checkbox' | 'timestamp' | 'password' | 'select' | 'relationship' | string // Allow custom field types from third-party packages
 
@@ -12,10 +9,7 @@ export type FieldType =
  * Field-level hook argument types (exported for user annotations)
  */
 
-/**
- * Arguments for field-level resolveInput hook
- * Used to transform field values before database write
- */
+/** Arguments for {@link FieldHooks.resolveInput}. */
 export type FieldResolveInputHookArgs<
   TTypeInfo extends TypeInfo,
   TFieldKey extends FieldKeys<TTypeInfo['fields']> = FieldKeys<TTypeInfo['fields']>,
@@ -39,10 +33,7 @@ export type FieldResolveInputHookArgs<
       context: import('../access/types.js').AccessContext
     }
 
-/**
- * Arguments for field-level validate hook
- * Used for custom validation logic
- */
+/** Arguments for {@link FieldHooks.validate} (and its deprecated `validateInput` alias). */
 export type FieldValidateHookArgs<
   TTypeInfo extends TypeInfo,
   TFieldKey extends FieldKeys<TTypeInfo['fields']> = FieldKeys<TTypeInfo['fields']>,
@@ -76,10 +67,7 @@ export type FieldValidateHookArgs<
       addValidationError: (msg: string) => void
     }
 
-/**
- * Arguments for field-level beforeOperation hook
- * Used for side effects before database write
- */
+/** Arguments for {@link FieldHooks.beforeOperation}. */
 export type FieldBeforeOperationHookArgs<
   TTypeInfo extends TypeInfo,
   TFieldKey extends FieldKeys<TTypeInfo['fields']> = FieldKeys<TTypeInfo['fields']>,
@@ -109,10 +97,7 @@ export type FieldBeforeOperationHookArgs<
       context: import('../access/types.js').AccessContext
     }
 
-/**
- * Arguments for field-level afterOperation hook
- * Used for side effects after database operation
- */
+/** Arguments for {@link FieldHooks.afterOperation}. */
 export type FieldAfterOperationHookArgs<
   TTypeInfo extends TypeInfo,
   TFieldKey extends FieldKeys<TTypeInfo['fields']> = FieldKeys<TTypeInfo['fields']>,
@@ -263,10 +248,7 @@ export type FieldAfterTransactionHookArgs<
       context: import('../access/types.js').AccessContext
     }
 
-/**
- * Arguments for field-level resolveOutput hook
- * Used to transform field values after database read
- */
+/** Arguments for {@link FieldHooks.resolveOutput}. */
 export type FieldResolveOutputHookArgs<
   TTypeInfo extends TypeInfo,
   TFieldKey extends FieldKeys<TTypeInfo['fields']> = FieldKeys<TTypeInfo['fields']>,
@@ -507,10 +489,10 @@ export type BaseFieldConfig<TTypeInfo extends TypeInfo> = {
   defaultValue?: unknown
   hooks?: FieldHooks<TTypeInfo>
   /**
-   * Marks this field as virtual - not stored in database
-   * Virtual fields use resolveInput/resolveOutput hooks for computation
-   * They are excluded from Prisma schema and input types
-   * Only computed when explicitly selected/included in queries
+   * Marks this field as virtual — not stored in database, computed via
+   * `resolveInput`/`resolveOutput` hooks, and excluded from the Prisma
+   * schema and input types. Computed whenever the read is going to return
+   * it (ADR-0027) — not gated behind an explicit `include`/selection.
    */
   virtual?: boolean
   /**
@@ -877,6 +859,25 @@ export type DecimalField<TTypeInfo extends TypeInfo = TypeInfo> = BaseFieldConfi
   isIndexed?: boolean | 'unique'
 }
 
+/**
+ * 64-bit integer field (Prisma `BigInt`, TypeScript `bigint`) — for values that
+ * overflow `integer()`'s 32-bit `Int` (e.g. a millisecond epoch).
+ *
+ * Wire representation (ADR-0029): `bigint` in application code, a decimal
+ * string over MCP — `bigint` is not JSON-serialisable, so the MCP handler
+ * renders it as a string rather than throwing.
+ */
+export type BigIntField<TTypeInfo extends TypeInfo = TypeInfo> = BaseFieldConfig<TTypeInfo> & {
+  type: 'bigInt'
+  defaultValue?: bigint | number | string
+  validation?: {
+    isRequired?: boolean
+    min?: bigint
+    max?: bigint
+  }
+  isIndexed?: boolean | 'unique'
+}
+
 export type CheckboxField<TTypeInfo extends TypeInfo = TypeInfo> = BaseFieldConfig<TTypeInfo> & {
   type: 'checkbox'
 }
@@ -1358,20 +1359,8 @@ export type VirtualField<TTypeInfo extends TypeInfo> = BaseFieldConfig<TTypeInfo
  */
 export type FieldConfig = BaseFieldConfig<TypeInfo>
 
-/**
- * List configuration types
- */
-
-/**
- * Utility type to inject TypeInfo into a single field config
- * Extracts TInput and TOutput from BaseFieldConfig and reconstructs with new TypeInfo
- */
 type WithTypeInfo<TTypeInfo extends TypeInfo> = BaseFieldConfig<TTypeInfo>
 
-/**
- * Utility type to transform all fields in a record to inject TypeInfo
- * Maps over each field and applies WithTypeInfo transformation
- */
 export type FieldsWithTypeInfo<TTypeInfo extends TypeInfo> = {
   [key: string]: WithTypeInfo<TTypeInfo>
 }
@@ -1547,8 +1536,7 @@ export type ListAccessControl<T = any> =
     }
 
 /**
- * Hook arguments for resolveInput hook
- * Uses discriminated union to provide proper types based on operation
+ * Hook arguments for the list-level `resolveInput` hook.
  * - create: resolvedData is CreateInput, item is undefined
  * - update: resolvedData is UpdateInput, item is the existing record
  */
@@ -1575,8 +1563,7 @@ export type ResolveInputHookArgs<
     }
 
 /**
- * Hook arguments for validate hook (renamed from validateInput for Keystone compatibility)
- * Uses discriminated union to provide proper types based on operation
+ * Hook arguments for the list-level `validate` hook (renamed from `validateInput` for Keystone compatibility).
  * - create: resolvedData is CreateInput, item is undefined
  * - update: resolvedData is UpdateInput, item is the existing record
  * - delete: item is the item being deleted
@@ -1613,8 +1600,7 @@ export type ValidateHookArgs<
     }
 
 /**
- * Hook arguments for beforeOperation hook
- * Uses discriminated union to provide proper types based on operation
+ * Hook arguments for the list-level `beforeOperation` hook.
  * - create: has inputData and resolvedData, no item
  * - update: has inputData, resolvedData, and item
  * - delete: has item only
@@ -1647,8 +1633,7 @@ export type BeforeOperationHookArgs<
     }
 
 /**
- * Hook arguments for afterOperation hook
- * Uses discriminated union to provide proper types based on operation
+ * Hook arguments for the list-level `afterOperation` hook.
  * - create: has item, inputData, and resolvedData, no originalItem
  * - update: has item, originalItem, inputData, and resolvedData
  * - delete: has originalItem only
@@ -1848,14 +1833,20 @@ export type ListIndexFieldRef =
     }
 
 /**
- * A model-level composite `@@unique`/`@@index` constraint spanning two or
- * more of a list's own fields. See {@link ListConfig.db}'s `indexes` for the
- * full explanation and examples (#864).
+ * A model-level `@@unique`/`@@index` constraint spanning one or more of a
+ * list's own fields. See {@link ListConfig.db}'s `indexes` for the full
+ * explanation and examples (#864, #918).
  */
 export type ListIndex = {
   /**
    * The fields participating in this index/constraint, in declaration order.
    * OpenSaaS field names, not raw database column names.
+   *
+   * One or more fields — a named single-column constraint is as legitimate
+   * as a composite one, and is the form to reach for when a live table's
+   * constraint carries a name Prisma wouldn't derive on its own. Field-level
+   * `isIndexed` remains the sugar for the unnamed single-column case; this
+   * is the full form when a name or a sort direction is needed.
    */
   fields: ListIndexFieldRef[]
   /**
@@ -1949,31 +1940,40 @@ export type ListConfig<TTypeInfo extends TypeInfo> = {
      */
     timestamps?: boolean
     /**
-     * Model-level composite `@@unique`/`@@index` constraints spanning two or
-     * more of this list's own fields (#864).
+     * Model-level `@@unique`/`@@index` constraints spanning one or more of
+     * this list's own fields (#864, #918). See the [reference
+     * docs](https://stack.opensaas.au/docs/reference/config-api#dbindexes)
+     * for the full explanation, arity, and error conditions.
      *
-     * Field-level `isIndexed` (on a scalar or relationship field) can only
-     * ever produce a single-column index — it has no way to express a
-     * constraint or index that spans more than one column. `db.indexes` is
-     * that multi-column case: each entry names two or more of the list's own
-     * OpenSaaS field names, not raw database column names. The generator
-     * resolves each to its underlying Prisma column — a scalar field's own
-     * name (its Prisma field name is unaffected by `db.map`), or a
-     * relationship field's foreign key column (`<field>Id`) when this side
-     * owns it.
+     * Field-level `isIndexed` (on a scalar or relationship field) is the
+     * sugar for the unnamed single-column case. `db.indexes` is the full
+     * form — reach for it when a constraint needs a `name` (Prisma's `map:`,
+     * for adopting an existing live constraint), a `sort` direction, or spans
+     * more than one column. Arity is incidental: each entry names one or
+     * more of the list's own OpenSaaS field names, not raw database column
+     * names. The generator resolves each to its underlying Prisma column — a
+     * scalar field's own name (its Prisma field name is unaffected by
+     * `db.map`), or a relationship field's foreign key column (`<field>Id`)
+     * when this side owns it.
      *
-     * A composite **unique** is the load-bearing case: it's the
-     * database-level backstop for a business rule two concurrent writes could
-     * otherwise both slip past (e.g. "one booking per student per
-     * production") — something a hook's existence check cannot close on its
-     * own, and can't be retrofitted once duplicate rows exist. A composite
-     * **index** (non-unique) is the equivalent performance-only case (a hot
-     * multi-column lookup path).
+     * A **unique** entry is the load-bearing case: it's the database-level
+     * backstop for a business rule concurrent writes could otherwise both
+     * slip past (e.g. "one booking per student per production", or a
+     * single-column unique a live table already enforces under a name Prisma
+     * wouldn't derive) — something a hook's existence check cannot close on
+     * its own, and can't be retrofitted once duplicate rows exist. An
+     * **index** (non-unique) entry is the equivalent performance-only case
+     * (a hot lookup path).
      *
-     * An entry naming a field the list doesn't have, a virtual field, a
-     * to-many relationship, or the non-FK side of a one-to-one relationship
-     * fails `pnpm generate` with an error naming the list, the entry, and the
-     * bad field — it is never silently dropped or emitted as invalid Prisma.
+     * Two conditions fail `pnpm generate` with an error naming the list and
+     * the entry: an empty `fields` array, and a single-field entry that
+     * indexes the exact column a field-level `isIndexed` on the same list
+     * already indexes (the error also names that field and its `isIndexed`
+     * value — one of the two should be removed). An entry naming a field the
+     * list doesn't have, a virtual field, a to-many relationship, or the
+     * non-FK side of a one-to-one relationship fails the same way, naming
+     * the bad field too — no entry is ever silently dropped or emitted as
+     * invalid Prisma.
      *
      * @example One audition per student per production (composite unique)
      * ```typescript
@@ -2007,12 +2007,22 @@ export type ListConfig<TTypeInfo extends TypeInfo> = {
      * })
      * // Generates: @@index([identifier, createdAt(sort: Desc)], map: "AuthVerification_identifier_createdAt_idx")
      * ```
+     *
+     * @example Naming a single-column unique constraint (adopting a live table's existing name)
+     * ```typescript
+     * RateLimit: list({
+     *   fields: { key: text() }, // no isIndexed here — db.indexes owns this column instead
+     *   db: {
+     *     indexes: [{ fields: ['key'], unique: true, name: 'RateLimit_key_key' }],
+     *   },
+     * })
+     * // Generates: @@unique([key], map: "RateLimit_key_key")
+     * // Setting key's own isIndexed too would duplicate this constraint and
+     * // fail generation — one of the two must own the column.
+     * ```
      */
     indexes?: ListIndex[]
   }
-  /**
-   * MCP server configuration for this list
-   */
   mcp?: ListMcpConfig
   /**
    * Restricts this list to a single record (singleton pattern)
@@ -2319,9 +2329,6 @@ export type ListConfigInput<TTypeInfo extends TypeInfo> = Omit<ListConfig<TTypeI
   access?: ListAccessControl<TTypeInfo['item']>
 }
 
-/**
- * Database configuration
- */
 export type DatabaseConfig = {
   provider: 'postgresql' | 'mysql' | 'sqlite'
   /**
@@ -2540,9 +2547,6 @@ export type DatabaseConfig = {
   }
 }
 
-/**
- * Session configuration
- */
 export type SessionConfig = {
   // Uses `any` return type because session structure is user-defined and varies per application
   // The stack doesn't enforce a specific session shape - users can use NextAuth, Clerk, etc.
@@ -2550,9 +2554,6 @@ export type SessionConfig = {
   getSession: () => Promise<any>
 }
 
-/**
- * Theme preset options
- */
 export type ThemePreset = 'modern' | 'classic' | 'neon'
 
 /**
@@ -2648,14 +2649,8 @@ export type ThemeConfig = {
   shadows?: ThemeShadows
 }
 
-/**
- * UI configuration
- */
 export type UIConfig = {
   basePath?: string
-  /**
-   * Theme configuration for the admin UI
-   */
   theme?: ThemeConfig
 }
 
@@ -2698,18 +2693,12 @@ export type McpCustomTool = {
    * Unique name for the tool
    */
   name: string
-  /**
-   * Description of what the tool does
-   */
   description: string
   /**
    * Input schema (Zod schema)
    */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   inputSchema: any
-  /**
-   * Handler function that executes the tool
-   */
   handler: (args: {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     input: any
@@ -2717,9 +2706,6 @@ export type McpCustomTool = {
   }) => Promise<unknown>
 }
 
-/**
- * List-level MCP configuration
- */
 export type ListMcpConfig = {
   /**
    * Enable MCP tools for this list
@@ -2790,9 +2776,6 @@ export type McpAuthConfig =
        * Authentication type - custom auth provider
        */
       type: string
-      /**
-       * Additional auth-specific configuration
-       */
       // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Allows custom auth provider configuration
       [key: string]: any
     }
@@ -2920,15 +2903,17 @@ export type PluginContext = {
 
   /**
    * Add a new list to the config
-   * Throws error if list already exists (unless merge strategy used)
+   * Throws error if list already exists
    */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Plugin API must accept any list config
   addList: (name: string, listConfig: ListConfig<any>) => void
 
   /**
-   * Extend an existing list with additional fields, hooks, or access control
-   * Deep merges fields, hooks, and access control
-   * Throws error if list doesn't exist
+   * Extend an existing list with additional fields, hooks, or MCP config.
+   * Merges fields, hooks, and MCP config. Throws if the list doesn't exist,
+   * or if the extension sets operation-level `access` — access control
+   * belongs to whoever created the list, never a plugin extending it
+   * (ADR-0013).
    */
   extendList: (
     name: string,
@@ -3047,10 +3032,6 @@ export type Plugin = {
   }
 }
 
-/**
- * Main configuration type
- * Using interface instead of type to allow module augmentation
- */
 /**
  * Configurable generator output locations.
  *
@@ -3112,6 +3093,10 @@ export interface OutputConfig {
   buildTarget?: 'node'
 }
 
+/**
+ * Main configuration type.
+ * Uses an interface, not a type alias, so it can be extended via module augmentation.
+ */
 export interface OpenSaasConfig {
   db: DatabaseConfig
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Config must accept any list configuration

package/src/context/apply-defaults.ts

@@ -1,63 +1,34 @@
 import type { FieldConfig } from '../config/types.js'
 
 /**
- * Apply field `defaultValue`s to omitted inputs on CREATE — the runtime half of
- * the resolve-then-validate ordering (Keystone 6 parity, issue #615).
+ * Fills a field's `defaultValue` into `resolvedData` for CREATE when the field
+ * was omitted, run after resolveInput hooks and before validation. Shared by
+ * the top-level create path (Hook Pipeline) and the nested-relation create path.
  *
- * A field's `defaultValue` is otherwise only realised as a Prisma `@default(...)`
- * applied by the database at write time, which is AFTER the write pipeline's
- * validation phase has already run. That ordering means a required-with-default
- * field (e.g. `select({ validation: { isRequired: true }, defaultValue: 'X' })`)
- * fails `isRequired` validation on an omitted input even though a default exists.
- *
- * This helper closes that gap: in the resolve phase (after `resolveInput` hooks,
- * before validation) it fills `resolvedData[field]` with the field's
- * `defaultValue` ONLY when the field was OMITTED (value is `undefined`). It is a
- * SINGLE shared mechanism used by both the top-level create path (Hook Pipeline)
- * and the nested-relation create path.
- *
- * Guard rails (each acceptance-criteria-driven):
- *   - CREATE only. Update never injects defaults for omitted fields (the caller
- *     only invokes this for `operation === 'create'`).
- *   - Explicitly-provided values are preserved. A key present in `resolvedData`
- *     — INCLUDING an explicit `null` — is left untouched; only `undefined`
- *     (omitted) keys are filled.
- *   - Virtual, system (`id`/`createdAt`/`updatedAt`) and relationship fields are
- *     skipped — they have no scalar `defaultValue` to inject and relationships
- *     carry connect/create payloads rather than literal defaults.
- *   - The timestamp `{ kind: 'now' }` sentinel is NOT injected: it is not a
- *     literal value but a request for the DB-level `@default(now())`, which still
- *     applies at write time. Injecting the sentinel object would corrupt the
- *     payload. (A concrete `Date` default is a real literal and IS injected.)
- *
- * The function mutates and returns `resolvedData` (consistent with the other
- * resolve-phase helpers that thread `resolvedData` through the pipeline).
+ * Prisma only realises `defaultValue` as `@default(...)` at the database write,
+ * which is after this pipeline's validation phase — so without this, a
+ * required field with a default (e.g. `select({ validation: { isRequired: true },
+ * defaultValue: 'X' })`) fails `isRequired` on an omitted input. See issue #615.
  */
 export function applyCreateDefaults(
   resolvedData: Record<string, unknown>,
   fieldConfigs: Record<string, FieldConfig>,
 ): Record<string, unknown> {
   for (const [fieldKey, fieldConfig] of Object.entries(fieldConfigs)) {
-    // Skip virtual fields — not stored in the database.
     if (fieldConfig.virtual) continue
-
-    // Skip system fields — always managed by the framework/DB.
     if (fieldKey === 'id' || fieldKey === 'createdAt' || fieldKey === 'updatedAt') continue
-
-    // Skip relationships — they carry connect/create payloads, not literal defaults.
+    // Relationships carry connect/create payloads, not literal defaults.
     if (fieldConfig.type === 'relationship') continue
-
-    // No declared default → nothing to inject.
     if (!('defaultValue' in fieldConfig) || fieldConfig.defaultValue === undefined) continue
 
-    // Only fill OMITTED keys. An explicitly-provided value (including explicit
-    // `null`) is preserved and must not be overwritten by the default.
+    // Only fill OMITTED (`undefined`) keys — an explicitly-provided value,
+    // including explicit `null`, must survive untouched.
     if (resolvedData[fieldKey] !== undefined) continue
 
     const defaultValue = fieldConfig.defaultValue
 
-    // The timestamp `{ kind: 'now' }` sentinel is a DB-level `@default(now())`
-    // request, not a literal — leave it for Prisma to apply at write time.
+    // `{ kind: 'now' }` requests the DB-level `@default(now())`, not a literal
+    // value — injecting the sentinel object itself would corrupt the payload.
     if (isNowSentinel(defaultValue)) continue
 
     resolvedData[fieldKey] = defaultValue
@@ -66,9 +37,6 @@ export function applyCreateDefaults(
   return resolvedData
 }
 
-/**
- * Detect the timestamp `{ kind: 'now' }` default sentinel.
- */
 function isNowSentinel(value: unknown): boolean {
   return (
     typeof value === 'object' &&

package/src/context/hook-pipeline.ts

@@ -12,78 +12,33 @@ import {
 import { applyCreateDefaults } from './apply-defaults.js'
 
 /**
- * Hook Pipeline — the single module that runs the transform+validate span of a
- * write: list `resolveInput` → field `resolveInput` → list `validate` → field
- * `validate` → built-in field rules (`validateFieldRules`). It owns the order of
- * these phases and the threading of `resolvedData` through them, in one place.
- *
- * It is THE place where input is shaped and validated; it throws
- * {@link ValidationError} on failure exactly as before (validate hooks via
- * `addValidationError`, then `validateFieldRules`) — validation is never silent.
- *
- * Side-effect hooks (`beforeOperation`/`afterOperation`), operation-level access,
- * writable-field filtering, nested operations, persistence and Field Visibility
- * are deliberately OUT of this span — they stay in the Write Pipeline. See the
- * "Hook Pipeline" and "Write Pipeline" glossary terms in CONTEXT.md.
+ * The transform+validate span of a write. See the "Hook Pipeline" and "Write
+ * Pipeline" glossary terms in CONTEXT.md for the full phase order and the
+ * boundary with the Write Pipeline (which owns side-effect hooks, access,
+ * writable-field filtering, nested operations, persistence, Field Visibility).
  */
 
-/**
- * Arguments for one transform+validate span. Only the create/update operations
- * run this span (delete skips the input-shaping phases entirely).
- */
 export interface HookPipelineArgs {
   operation: 'create' | 'update'
   listName: string
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
   listConfig: ListConfig<any>
-  /** The original input data for the write. */
   inputData: Record<string, unknown>
-  /** The existing row for update; `undefined` for create. */
   item: Record<string, unknown> | undefined
   context: AccessContext
 }
 
-/**
- * Result of a transform+validate span: the fully-resolved write data after the
- * resolveInput hooks have run and all validation has passed.
- */
 export interface HookPipelineResult {
   resolvedData: Record<string, unknown>
 }
 
-/**
- * The transform+validate span, owning order + `resolvedData` threading.
- */
 export interface HookPipeline {
   run(args: HookPipelineArgs): Promise<HookPipelineResult>
 }
 
-/**
- * Run the transform+validate span once.
- *
- * Phase order (owned here, in one place):
- *   list `resolveInput`
- *     → field `resolveInput`
- *     → list `validate`
- *     → field `validate`
- *     → built-in field rules (`validateFieldRules`)
- *     → split multi-column fields (`splitMultiColumnFields`)
- *
- * Contract preserved exactly:
- *   - `resolvedData` starts as `inputData` and is threaded through each phase;
- *   - validate hooks report failures via `addValidationError` → THROW
- *     `ValidationError` (never silent);
- *   - built-in field rule failures THROW `ValidationError`;
- *   - a multi-column field (e.g. storage image()/file() in Keystone-parity
- *     mode) is validated under its LOGICAL key BEFORE it is split into
- *     physical columns (#789) — an unrecognised value throws instead of being
- *     silently split into null/undefined columns;
- *   - on success returns the transformed `resolvedData`.
- */
 async function runHookPipeline(args: HookPipelineArgs): Promise<HookPipelineResult> {
   const { operation, listName, listConfig, inputData, item, context } = args
 
-  // ── Phase 1: list-level resolveInput ──────────────────────────────────────
   let resolvedData = await executeResolveInput(
     listConfig.hooks,
     operation === 'create'
@@ -105,7 +60,6 @@ async function runHookPipeline(args: HookPipelineArgs): Promise<HookPipelineResu
         },
   )
 
-  // ── Phase 1.5: field-level resolveInput (e.g. hash passwords) ──────────────
   resolvedData = await executeFieldResolveInputHooks(
     inputData,
     resolvedData,
@@ -116,17 +70,13 @@ async function runHookPipeline(args: HookPipelineArgs): Promise<HookPipelineResu
     item,
   )
 
-  // ── Phase 1.75: apply field defaults to omitted inputs (CREATE only) ───────
-  // Resolve-then-validate (Keystone parity, #615): a field declaring a
-  // `defaultValue` is filled into `resolvedData` here — AFTER resolveInput hooks
-  // and BEFORE validation — but only when the field was OMITTED, so a
-  // required-with-default field passes `isRequired` instead of failing it.
-  // Update is untouched (no default injection on update).
+  // Must run after resolveInput hooks and before validation, so a
+  // required-with-default field passes `isRequired` on an omitted input
+  // instead of failing it (see applyCreateDefaults, issue #615).
   if (operation === 'create') {
     resolvedData = applyCreateDefaults(resolvedData, listConfig.fields)
   }
 
-  // ── Phase 2: list-level validate ──────────────────────────────────────────
   await executeValidate(
     listConfig.hooks,
     operation === 'create'
@@ -148,7 +98,6 @@ async function runHookPipeline(args: HookPipelineArgs): Promise<HookPipelineResu
         },
   )
 
-  // ── Phase 2.5: field-level validate ───────────────────────────────────────
   await executeFieldValidateHooks(
     inputData,
     resolvedData,
@@ -159,17 +108,16 @@ async function runHookPipeline(args: HookPipelineArgs): Promise<HookPipelineResu
     item,
   )
 
-  // ── Phase 3: built-in field rules (isRequired, length, etc.) ──────────────
-  // Validation failures THROW (validation is not silent).
+  // Unlike an access-denied `context.db` operation, a validation failure
+  // throws rather than returning null/[] — validation is never silent.
   const validation = validateFieldRules(resolvedData, listConfig.fields, operation)
   if (validation.errors.length > 0) {
     throw new ValidationError(validation.errors, validation.fieldErrors)
   }
 
-  // ── Phase 4: split multi-column fields into physical columns ──────────────
-  // Only reached once the logical value has passed validation (#789). Replaces
-  // each multi-column field's logical key with its per-part columns, gated by
-  // the field's own write access (see `splitMultiColumnFields`).
+  // Runs only once the logical value has passed validation above (#789) — a
+  // multi-column field validated after splitting could see an unrecognised
+  // value silently become null/undefined columns instead of throwing.
   resolvedData = await splitMultiColumnFields(
     inputData,
     resolvedData,
@@ -182,9 +130,6 @@ async function runHookPipeline(args: HookPipelineArgs): Promise<HookPipelineResu
   return { resolvedData }
 }
 
-/**
- * The default Hook Pipeline instance used by the Write Pipeline.
- */
 export const hookPipeline: HookPipeline = {
   run: runHookPipeline,
 }