@opensaas/stack-core 0.25.0 → 0.27.0

package/src/fields/calendar-day.test.ts

@@ -1,7 +1,9 @@
-import { describe, it, expect, expectTypeOf } from 'vitest'
+import { describe, it, expect, expectTypeOf, vi } from 'vitest'
 import { calendarDay } from './index.js'
 import { generateZodSchema, validateWithZod } from '../validation/schema.js'
+import { getContext } from '../context/index.js'
 import type { FieldConfig } from '../config/types.js'
+import type { OpenSaasConfig } from '../config/types.js'
 
 /**
  * calendarDay is a YYYY-MM-DD string end-to-end (Keystone's CalendarDay
@@ -54,7 +56,7 @@ describe('calendarDay field (YYYY-MM-DD string end-to-end)', () => {
     })
   })
 
-  describe('write validation (string-only)', () => {
+  describe('write validation (YYYY-MM-DD string, or a Date post-resolveInput)', () => {
     const fields: Record<string, FieldConfig> = {
       startsOn: calendarDay({ validation: { isRequired: true } }),
     }
@@ -73,15 +75,18 @@ describe('calendarDay field (YYYY-MM-DD string end-to-end)', () => {
       }
     })
 
-    it('rejects a Date instance at runtime (not a string)', () => {
-      // A typed caller cannot reach here (input type is `string`), but the
-      // validator is string-only as a runtime backstop.
+    it('accepts a Date instance (the shape resolveInput produces from a valid string)', () => {
+      // The write pipeline runs field `resolveInput` BEFORE this schema, and
+      // calendarDay's resolveInput turns a valid YYYY-MM-DD string into a UTC
+      // Date (see #621) so Prisma's `@db.Date` write validator accepts it. So
+      // by the time this schema runs, a successful write reaches it as a
+      // Date, not the original string — the schema must accept both shapes.
       const result = validateWithZod(
-        { startsOn: new Date('2025-01-15') } as unknown as Record<string, unknown>,
+        { startsOn: new Date('2025-01-15T00:00:00.000Z') } as unknown as Record<string, unknown>,
         fields,
         'create',
       )
-      expect(result.success).toBe(false)
+      expect(result.success).toBe(true)
     })
 
     it('zod schema for the field validates the YYYY-MM-DD shape', () => {
@@ -91,6 +96,62 @@ describe('calendarDay field (YYYY-MM-DD string end-to-end)', () => {
     })
   })
 
+  describe('write transform (resolveInput coerces YYYY-MM-DD string to a UTC Date, #621)', () => {
+    // The write pipeline calls fieldConfig.hooks.resolveInput({ resolvedData,
+    // fieldKey, ... }) BEFORE zod validation runs. We exercise that hook
+    // directly with the value shapes a caller (or an upstream list-level
+    // resolveInput) can produce.
+    function writeValue(value: unknown): unknown {
+      const field = calendarDay()
+      const hook = field.hooks?.resolveInput
+      if (!hook) throw new Error('calendarDay must define a resolveInput hook')
+      return (
+        hook as unknown as (args: {
+          resolvedData: Record<string, unknown>
+          fieldKey: string
+        }) => unknown
+      )({ resolvedData: { startsOn: value }, fieldKey: 'startsOn' })
+    }
+
+    it('converts a YYYY-MM-DD string to a UTC-midnight Date', () => {
+      const result = writeValue('2025-01-15') as Date
+      expect(result).toBeInstanceOf(Date)
+      expect(result.toISOString()).toBe('2025-01-15T00:00:00.000Z')
+    })
+
+    it('passes an already-Date value through unchanged', () => {
+      const date = new Date('2025-06-01T00:00:00.000Z')
+      expect(writeValue(date)).toBe(date)
+    })
+
+    it('passes null/undefined through unchanged (so isRequired can still reject a missing value)', () => {
+      expect(writeValue(null)).toBeNull()
+      expect(writeValue(undefined)).toBeUndefined()
+    })
+
+    it('leaves a malformed string untouched so zod still rejects it with a clear message', () => {
+      expect(writeValue('15/01/2025')).toBe('15/01/2025')
+    })
+
+    it('reads resolvedData[fieldKey], not inputData — survives a list-level resolveInput default', () => {
+      // A list-level resolveInput can inject a default for an omitted key
+      // into resolvedData before field resolveInput runs. Reading
+      // resolvedData (not the original inputData) here means that injected
+      // default is what gets coerced, instead of being read as `undefined`
+      // and overwriting the injected default with null.
+      const field = calendarDay()
+      const hook = field.hooks?.resolveInput as unknown as (args: {
+        resolvedData: Record<string, unknown>
+        fieldKey: string
+      }) => unknown
+      const result = hook({
+        resolvedData: { startsOn: '2025-03-20' }, // injected by a list-level hook
+        fieldKey: 'startsOn',
+      }) as Date
+      expect(result.toISOString()).toBe('2025-03-20T00:00:00.000Z')
+    })
+  })
+
   describe('read transform (resolveOutput returns a YYYY-MM-DD string)', () => {
     // The read pipeline calls fieldConfig.hooks.resolveOutput({ value, ... }).
     // We exercise that hook directly with the value shapes Prisma can return.
@@ -137,4 +198,94 @@ describe('calendarDay field (YYYY-MM-DD string end-to-end)', () => {
       expect(hook({ value: '2025-01-15' })).toBe('custom:2025-01-15')
     })
   })
+
+  describe('end-to-end via context.db.*.create/update (#621 repro)', () => {
+    // Prisma 7's client validator rejects a bare YYYY-MM-DD string for a
+    // `@db.Date` column. Assert the value actually forwarded to the Prisma
+    // client is a Date, not the string the caller passed in.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- mock Prisma client
+    let mockPrisma: any
+
+    function buildConfig(): OpenSaasConfig {
+      mockPrisma = {
+        event: {
+          findFirst: vi.fn(),
+          findUnique: vi.fn(),
+          findMany: vi.fn(),
+          create: vi.fn(),
+          update: vi.fn(),
+          delete: vi.fn(),
+          count: vi.fn(),
+        },
+      }
+      return {
+        db: {
+          provider: 'postgresql',
+          prismaClientConstructor: (PrismaClient) => new PrismaClient(),
+        },
+        lists: {
+          Event: {
+            fields: {
+              startsOn: calendarDay({ validation: { isRequired: true } }),
+            },
+            access: {
+              operation: {
+                query: () => true,
+                create: () => true,
+                update: () => true,
+                delete: () => true,
+              },
+            },
+          },
+        },
+      }
+    }
+
+    it('create: a YYYY-MM-DD string reaches Prisma as a UTC-midnight Date', async () => {
+      const config = buildConfig()
+      mockPrisma.event.create.mockResolvedValue({
+        id: '1',
+        startsOn: new Date('2025-01-15T00:00:00.000Z'),
+      })
+      const context = await getContext(config, mockPrisma, null)
+
+      await context.db.event.create({ data: { startsOn: '2025-01-15' } })
+
+      expect(mockPrisma.event.create).toHaveBeenCalledTimes(1)
+      const callArgs = mockPrisma.event.create.mock.calls[0][0]
+      expect(callArgs.data.startsOn).toBeInstanceOf(Date)
+      expect((callArgs.data.startsOn as Date).toISOString()).toBe('2025-01-15T00:00:00.000Z')
+    })
+
+    it('update: a YYYY-MM-DD string reaches Prisma as a UTC-midnight Date', async () => {
+      const config = buildConfig()
+      const existing = { id: '1', startsOn: new Date('2025-01-15T00:00:00.000Z') }
+      mockPrisma.event.findUnique.mockResolvedValue(existing)
+      mockPrisma.event.update.mockResolvedValue({
+        ...existing,
+        startsOn: new Date('2025-02-20T00:00:00.000Z'),
+      })
+      const context = await getContext(config, mockPrisma, null)
+
+      await context.db.event.update({ where: { id: '1' }, data: { startsOn: '2025-02-20' } })
+
+      expect(mockPrisma.event.update).toHaveBeenCalledTimes(1)
+      const callArgs = mockPrisma.event.update.mock.calls[0][0]
+      expect(callArgs.data.startsOn).toBeInstanceOf(Date)
+      expect((callArgs.data.startsOn as Date).toISOString()).toBe('2025-02-20T00:00:00.000Z')
+    })
+
+    it('the read result is still normalised back to a YYYY-MM-DD string', async () => {
+      const config = buildConfig()
+      mockPrisma.event.create.mockResolvedValue({
+        id: '1',
+        startsOn: new Date('2025-01-15T00:00:00.000Z'),
+      })
+      const context = await getContext(config, mockPrisma, null)
+
+      const result = await context.db.event.create({ data: { startsOn: '2025-01-15' } })
+
+      expect(result?.startsOn).toBe('2025-01-15')
+    })
+  })
 })

package/src/fields/index.ts

@@ -523,9 +523,13 @@ export function timestamp<
  * - Stores date values only (no time component)
  * - PostgreSQL/MySQL: Uses native DATE type via @db.Date
  * - SQLite: Uses String representation
- * - **Writes:** accept only a `YYYY-MM-DD` string; a malformed string or a
- *   `Date` is rejected at runtime by validation (a `ValidationError`). Genuine
- *   compile-time rejection at the `context.db` call site is tracked in #599.
+ * - **Writes:** pass a `YYYY-MM-DD` string (the declared type). A
+ *   `resolveInput` hook converts a valid string to a UTC-midnight `Date`
+ *   before validation, since Prisma 7's client validator rejects a bare date
+ *   string for a `@db.Date` column (#621); a `Date` is also accepted
+ *   directly. A malformed string is rejected at runtime by validation (a
+ *   `ValidationError`). Genuine compile-time rejection of a `Date` at the
+ *   `context.db` call site is tracked in #599.
  * - **Reads:** always return a `YYYY-MM-DD` string. Even though the underlying
  *   `@db.Date` column hands Prisma a `Date`, a `resolveOutput` transform
  *   normalises it back to a `YYYY-MM-DD` string so the runtime value matches
@@ -573,6 +577,17 @@ export function calendarDay<
   return {
     type: 'calendarDay',
     ...options,
+    // Writes: the write pipeline runs field resolveInput BEFORE zod
+    // validation (Hook Pipeline: field resolveInput → built-in field rules),
+    // so this is the only point a YYYY-MM-DD string can be turned into
+    // something Prisma's `@db.Date` write validator accepts — Prisma 7
+    // rejects a bare date string there (#621). Convert a valid string to a
+    // UTC-midnight Date; leave anything else (a Date already, null/undefined,
+    // or a malformed string) untouched so the zod schema below still rejects
+    // malformed input with a clear message. Reads resolvedData[fieldKey]
+    // (not raw inputData) so a list-level resolveInput that injects a default
+    // for an omitted key is still coerced instead of being overwritten.
+    //
     // Reads: the underlying @db.Date column hands Prisma a Date (or a TEXT
     // string under the SQLite fallback). Normalise to a YYYY-MM-DD string so the
     // runtime value matches the declared `string` type. UTC components are used
@@ -580,6 +595,15 @@ export function calendarDay<
     // Cast hooks to any since field builders are generic and can't know the
     // specific TFieldKey (same pattern as password()).
     hooks: {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Field builder hooks must be generic
+      resolveInput: ({ resolvedData, fieldKey }: { resolvedData: any; fieldKey: string }) => {
+        const value = resolvedData?.[fieldKey]
+        if (value == null || value instanceof Date) return value
+        if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(value)) {
+          return new Date(`${value}T00:00:00.000Z`)
+        }
+        return value
+      },
       // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Field builder hooks must be generic
       resolveOutput: ({ value }: { value: any }) => formatCalendarDay(value),
       // Merge with user-provided hooks if any
@@ -590,15 +614,19 @@ export function calendarDay<
       const validation = options?.validation
       const isRequired = validation?.isRequired
 
-      // Accept ISO8601 date strings (YYYY-MM-DD)
-      const baseSchema = z.string({
-        message: `${formatFieldName(fieldName)} must be a valid date in ISO8601 format (YYYY-MM-DD)`,
-      })
+      // Accept ISO8601 date strings (YYYY-MM-DD) in the shape a caller passes,
+      // or a `Date` — the shape resolveInput above turns a valid string into
+      // before this schema runs. Malformed strings fall through resolveInput
+      // untouched and still fail the regex here with a clear message.
+      const stringSchema = z
+        .string({
+          message: `${formatFieldName(fieldName)} must be a valid date in ISO8601 format (YYYY-MM-DD)`,
+        })
+        .regex(/^\d{4}-\d{2}-\d{2}$/, {
+          message: `${formatFieldName(fieldName)} must be in YYYY-MM-DD format`,
+        })
 
-      // Validate ISO8601 date format (YYYY-MM-DD)
-      const dateSchema = baseSchema.regex(/^\d{4}-\d{2}-\d{2}$/, {
-        message: `${formatFieldName(fieldName)} must be in YYYY-MM-DD format`,
-      })
+      const dateSchema = z.union([stringSchema, z.date()])
 
       if (isRequired && operation === 'create') {
         return dateSchema

package/src/hooks/index.ts

@@ -386,8 +386,7 @@ export async function executeFieldBeforeTransactionHooks(
  *    so hooks can compensate.
  */
 export type TransactionOutcome =
-  | { status: 'committed'; item: Record<string, unknown> }
-  | { status: 'rolled-back'; error: unknown }
+  { status: 'committed'; item: Record<string, unknown> } | { status: 'rolled-back'; error: unknown }
 
 /**
  * Execute field-level afterTransaction hooks (#590 / ADR-0010).

package/src/index.ts

@@ -34,10 +34,20 @@ export type {
 
 // Context factory
 export { getContext } from './context/index.js'
+export type {
+  StackContext,
+  TransactionOptions,
+  TransactionIsolationLevel,
+} from './context/index.js'
 
 // Naming utilities (documented public helpers; used for URLs and db keys)
 export { getDbKey, getUrlKey, getListKeyFromUrl } from './lib/case-utils.js'
 
+// Label seam — resolves the field that represents a row as a single label
+// (projection) and reads it off a row (render). Used by the admin UI for
+// relationship cells, dropdown options, and page headings.
+export { getLabelFieldName, getItemLabel } from './config/label.js'
+
 // Validation error surfaced by write operations
 export { ValidationError } from './hooks/index.js'
 
@@ -56,3 +66,9 @@ export type { FieldConfigValidationError } from './validation/field-config.js'
 // root surface — those live on '@opensaas/stack-core/internal'.
 export { defineFragment, runQuery, runQueryOne } from './query/index.js'
 export type { ResultOf, RelationSelector, QueryArgs } from './query/index.js'
+
+// Relationship-options read primitive — bounded, projected fetch for
+// relationship editors. Backs the `relationshipOptions` context.serverAction
+// op; also callable directly wherever a full context is already in hand.
+export { getRelationshipOptions } from './query/relationship-options.js'
+export type { RelationshipOption, RelationshipOptionsArgs } from './query/relationship-options.js'

package/src/query/relationship-options.test.ts

@@ -0,0 +1,157 @@
+import { describe, it, expect, vi } from 'vitest'
+import { getRelationshipOptions } from './relationship-options.js'
+import type { QueryRunnerContext } from './index.js'
+import type { OpenSaasConfig } from '../config/types.js'
+
+function makeDelegate(rows: Array<Record<string, unknown>>) {
+  return {
+    findMany: vi.fn(async (_args?: unknown) => rows),
+    findFirst: vi.fn(async (_args?: unknown) => rows[0] ?? null),
+  }
+}
+
+function makeContext(
+  delegates: Record<string, ReturnType<typeof makeDelegate>>,
+): QueryRunnerContext {
+  return { db: delegates }
+}
+
+const authors = [
+  { id: 'a1', name: 'Ada Lovelace' },
+  { id: 'a2', name: 'Alan Turing' },
+  { id: 'a3', name: 'Grace Hopper' },
+]
+
+function makeConfig(): OpenSaasConfig {
+  return {
+    db: { provider: 'sqlite', url: 'file:./test.db' },
+    lists: {
+      Author: {
+        fields: {
+          name: { type: 'text' },
+        },
+        access: { operation: { query: () => true } },
+      },
+      NumericLabel: {
+        fields: {
+          rank: { type: 'integer' },
+        },
+        ui: { labelField: 'rank' },
+        access: { operation: { query: () => true } },
+      },
+    },
+  } as unknown as OpenSaasConfig
+}
+
+describe('getRelationshipOptions', () => {
+  it('returns { id, label }[] via a scalar-only fragment with no nested include', async () => {
+    const delegate = makeDelegate(authors)
+    const context = makeContext({ author: delegate })
+    const config = makeConfig()
+
+    const result = await getRelationshipOptions(context, config, 'Author', {})
+
+    expect(result).toEqual([
+      { id: 'a1', label: 'Ada Lovelace' },
+      { id: 'a2', label: 'Alan Turing' },
+      { id: 'a3', label: 'Grace Hopper' },
+    ])
+
+    const call = delegate.findMany.mock.calls[0][0] as Record<string, unknown>
+    expect(call.include).toBeUndefined()
+  })
+
+  it('bounds the result by take', async () => {
+    const delegate = makeDelegate(authors.slice(0, 2))
+    const context = makeContext({ author: delegate })
+    const config = makeConfig()
+
+    await getRelationshipOptions(context, config, 'Author', { take: 2 })
+
+    expect(delegate.findMany).toHaveBeenCalledWith(expect.objectContaining({ take: 2 }))
+  })
+
+  it('orders by the label field ascending and filters via contains on a text label field', async () => {
+    const delegate = makeDelegate([authors[0]])
+    const context = makeContext({ author: delegate })
+    const config = makeConfig()
+
+    await getRelationshipOptions(context, config, 'Author', { search: 'Ada' })
+
+    expect(delegate.findMany).toHaveBeenCalledWith(
+      expect.objectContaining({
+        where: { name: { contains: 'Ada' } },
+        orderBy: { name: 'asc' },
+      }),
+    )
+  })
+
+  it('does not filter (first-N) when the label field is not a text field', async () => {
+    const rows = [{ id: 'n1', rank: 1 }]
+    const delegate = makeDelegate(rows)
+    const context = makeContext({ numericLabel: delegate })
+    const config = makeConfig()
+
+    await getRelationshipOptions(context, config, 'NumericLabel', { search: '1' })
+
+    const call = delegate.findMany.mock.calls[0][0] as Record<string, unknown>
+    expect(call.where).toBeUndefined()
+    expect(call.orderBy).toEqual({ rank: 'asc' })
+  })
+
+  it('unions currently-selected ids even when beyond take / not matching search', async () => {
+    // The bounded/search-scoped query only returns a1 (mimicking take:1 + search).
+    const primaryDelegate = makeDelegate([authors[0]])
+    const context = makeContext({ author: primaryDelegate })
+    const config = makeConfig()
+
+    // The selected-ids query (a separate findMany call) resolves a3, which fell
+    // outside the primary window.
+    primaryDelegate.findMany.mockImplementationOnce(async () => [authors[0]])
+    primaryDelegate.findMany.mockImplementationOnce(async () => [authors[2]])
+
+    const result = await getRelationshipOptions(context, config, 'Author', {
+      take: 1,
+      selectedIds: ['a3'],
+    })
+
+    expect(result).toEqual([
+      { id: 'a1', label: 'Ada Lovelace' },
+      { id: 'a3', label: 'Grace Hopper' },
+    ])
+
+    const selectedCall = primaryDelegate.findMany.mock.calls[1][0] as Record<string, unknown>
+    expect(selectedCall.where).toEqual({ id: { in: ['a3'] } })
+  })
+
+  it('does not re-query when the selected id is already within the primary window', async () => {
+    const delegate = makeDelegate([authors[0]])
+    const context = makeContext({ author: delegate })
+    const config = makeConfig()
+
+    await getRelationshipOptions(context, config, 'Author', { selectedIds: ['a1'] })
+
+    expect(delegate.findMany).toHaveBeenCalledTimes(1)
+  })
+
+  it('returns [] when the related list query access is denied (findMany returns [])', async () => {
+    const delegate = makeDelegate([])
+    const context = makeContext({ author: delegate })
+    const config = makeConfig()
+
+    const result = await getRelationshipOptions(context, config, 'Author', {
+      selectedIds: ['a1'],
+    })
+
+    expect(result).toEqual([])
+  })
+
+  it('returns [] when the related list does not exist in config', async () => {
+    const context = makeContext({})
+    const config = makeConfig()
+
+    const result = await getRelationshipOptions(context, config, 'Missing', {})
+
+    expect(result).toEqual([])
+  })
+})

package/src/query/relationship-options.ts

@@ -0,0 +1,70 @@
+import type { OpenSaasConfig } from '../config/types.js'
+import { getLabelFieldName, getItemLabel } from '../config/label.js'
+import { defineFragment, runQuery, type QueryRunnerContext } from './index.js'
+
+const DEFAULT_TAKE = 50
+
+export interface RelationshipOption {
+  id: string
+  label: string
+}
+
+export interface RelationshipOptionsArgs {
+  /** Filters the label field via `contains` when it is a text field. */
+  search?: string
+  /** Bounds the primary (search-scoped) window. @default 50 */
+  take?: number
+  /** Always unioned into the result, even outside the search/take window. */
+  selectedIds?: string[]
+}
+
+/**
+ * Bounded, projected fetch of `{ id, label }` options for a relationship
+ * editor — the read primitive behind the `relationshipOptions` serverAction
+ * op. Selects only `id` and the resolved label field (via
+ * {@link getLabelFieldName}), so the fragment carries no relation keys and
+ * `buildIncludeWithAccessControl`'s depth-5 auto-include never runs.
+ *
+ * Operation-level `query` access on `relatedListKey` still applies — a denied
+ * list resolves to `[]` (via the underlying access-controlled `findMany`).
+ */
+export async function getRelationshipOptions(
+  context: QueryRunnerContext,
+  config: OpenSaasConfig,
+  relatedListKey: string,
+  args: RelationshipOptionsArgs = {},
+): Promise<RelationshipOption[]> {
+  const relatedListConfig = config.lists[relatedListKey]
+  if (!relatedListConfig) return []
+
+  const labelField = getLabelFieldName(relatedListConfig)
+  const fragment = defineFragment<Record<string, unknown>>()({
+    id: true,
+    [labelField]: true,
+  })
+
+  const { search, take = DEFAULT_TAKE, selectedIds = [] } = args
+  const labelFieldConfig = relatedListConfig.fields[labelField] as { type?: string } | undefined
+  const where =
+    search && labelFieldConfig?.type === 'text' ? { [labelField]: { contains: search } } : undefined
+
+  const primary = await runQuery(context, relatedListKey, fragment, {
+    where,
+    orderBy: { [labelField]: 'asc' },
+    take,
+  })
+
+  const seenIds = new Set(primary.map((item) => (item as { id: string }).id))
+  const missingSelectedIds = selectedIds.filter((id) => !seenIds.has(id))
+
+  const selected = missingSelectedIds.length
+    ? await runQuery(context, relatedListKey, fragment, {
+        where: { id: { in: missingSelectedIds } },
+      })
+    : []
+
+  return [...primary, ...selected].map((item) => ({
+    id: (item as { id: string }).id,
+    label: getItemLabel(relatedListConfig, item as Record<string, unknown>),
+  }))
+}

package/tests/apply-defaults.test.ts

@@ -0,0 +1,119 @@
+import { describe, it, expect } from 'vitest'
+import { applyCreateDefaults } from '../src/context/apply-defaults.js'
+import { text, integer, checkbox, timestamp, virtual, relationship } from '../src/fields/index.js'
+import type { FieldConfig } from '../src/config/types.js'
+
+/**
+ * Direct unit tests for `applyCreateDefaults` (#615). These exercise every guard
+ * rail of the real helper — virtual / system / relationship skips, the
+ * no-`defaultValue` skip, explicit-value and explicit-`null` preservation, the
+ * timestamp `{ kind: 'now' }` sentinel skip, and concrete `Date` injection — so
+ * the resolve-then-validate helper is fully covered without mocking its logic.
+ */
+
+function fields(config: Record<string, FieldConfig>): Record<string, FieldConfig> {
+  return config
+}
+
+describe('applyCreateDefaults', () => {
+  it('injects a declared defaultValue into an omitted field', () => {
+    const resolved = applyCreateDefaults(
+      {},
+      fields({
+        label: text({ defaultValue: 'PLACEHOLDER' }),
+        count: integer({ defaultValue: 7 }),
+        active: checkbox({ defaultValue: true }),
+      }),
+    )
+
+    expect(resolved).toEqual({ label: 'PLACEHOLDER', count: 7, active: true })
+  })
+
+  it('leaves a field with NO defaultValue untouched (key stays absent)', () => {
+    const resolved = applyCreateDefaults({}, fields({ label: text() }))
+
+    expect('label' in resolved).toBe(false)
+  })
+
+  it('preserves an explicitly-provided value over the default', () => {
+    const resolved = applyCreateDefaults(
+      { count: 99 },
+      fields({ count: integer({ defaultValue: 7 }) }),
+    )
+
+    expect(resolved.count).toBe(99)
+  })
+
+  it('preserves an explicit null and does not overwrite it with the default', () => {
+    const resolved = applyCreateDefaults(
+      { note: null },
+      fields({ note: text({ defaultValue: 'DEFAULT_NOTE' }) }),
+    )
+
+    expect(resolved.note).toBeNull()
+  })
+
+  it('skips virtual fields (no scalar default to inject)', () => {
+    const resolved = applyCreateDefaults(
+      {},
+      fields({
+        // A virtual field cannot carry a stored default; it must be skipped.
+        computed: virtual({
+          type: 'string',
+          hooks: { resolveOutput: () => 'x' },
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        }) as any,
+      }),
+    )
+
+    expect('computed' in resolved).toBe(false)
+  })
+
+  it('skips system fields (id/createdAt/updatedAt)', () => {
+    const resolved = applyCreateDefaults(
+      {},
+      fields({
+        id: text({ defaultValue: 'SHOULD_NOT_INJECT' }),
+        createdAt: timestamp({ defaultValue: new Date('2020-01-01T00:00:00Z') }),
+        updatedAt: timestamp({ defaultValue: new Date('2020-01-01T00:00:00Z') }),
+      }),
+    )
+
+    expect(resolved).toEqual({})
+  })
+
+  it('skips relationship fields (they carry connect/create payloads, not literals)', () => {
+    const resolved = applyCreateDefaults(
+      {},
+      fields({
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        owner: relationship({ ref: 'User' }) as any,
+      }),
+    )
+
+    expect('owner' in resolved).toBe(false)
+  })
+
+  it("does NOT inject the timestamp { kind: 'now' } sentinel (left for the DB @default(now()))", () => {
+    const resolved = applyCreateDefaults(
+      {},
+      fields({ when: timestamp({ defaultValue: { kind: 'now' } }) }),
+    )
+
+    expect('when' in resolved).toBe(false)
+  })
+
+  it('DOES inject a concrete Date default (a real literal, unlike the now sentinel)', () => {
+    const date = new Date('2021-06-15T12:00:00Z')
+    const resolved = applyCreateDefaults({}, fields({ when: timestamp({ defaultValue: date }) }))
+
+    expect(resolved.when).toBe(date)
+  })
+
+  it('returns the same resolvedData object it was given (mutation contract)', () => {
+    const input: Record<string, unknown> = {}
+    const result = applyCreateDefaults(input, fields({ label: text({ defaultValue: 'x' }) }))
+
+    expect(result).toBe(input)
+  })
+})