@opensaas/stack-core 0.36.0 → 0.38.0

package/src/access/field-visibility.ts

@@ -6,6 +6,7 @@ import { RESOLVE_CHAIN_MAX_LENGTH } from './depth-limits.js'
 import { ResolveOutputCycleError } from './errors.js'
 import type { DeclaredOnlyTree } from './declared-dependencies.js'
 import { emptyDeclaredOnlyTree } from './declared-dependencies.js'
+import type { FieldSelectionScope } from '../query/index.js'
 // NOTE: `context/index.ts` imports `filterReadableFields` from this module
 // (via the `access/index.ts` barrel) — this is an intentional cyclic
 // dependency, the same shape and for the same reason as the one documented in
@@ -23,6 +24,14 @@ import { buildDbDelegate } from '../context/index.js'
  * virtual fields. None of this can move into phase 1: virtual fields are
  * computed in JavaScript and field access can depend on the fetched row.
  *
+ * A computed field — any field carrying a `resolveOutput` hook, virtual or
+ * not — is produced only where the read is going to return it (ADR-0027). A
+ * fragment `query`'s own field selection is the only thing that restricts a
+ * level this way; a bare or `include`-based read, and any relation reached
+ * purely to satisfy a `needs` declaration, still compute every field, as
+ * before. A field the read is not going to return does no work at all —
+ * neither its read-access evaluation nor its hook.
+ *
  * Phase 1 (pre-query row/relation scoping) lives in `access-filter.ts`. See
  * `docs/adr/0001-access-control-is-a-two-phase-read.md` and the access-control
  * glossary in `CONTEXT.md`.
@@ -96,8 +105,11 @@ function deriveResolveOutputContext(
  * from the result.
  *
  * `accessItem` is the row used to evaluate field access; `hookItem` is the
- * object passed to the hook as `item` (these differ for virtual fields, which
- * see the already-filtered output so they can read sibling fields).
+ * object passed to the hook as `item`. For a stored field, both are
+ * `workingItem` (the row's own stored/fetched columns). For a virtual field,
+ * `hookItem` is `computedFieldItem` instead — the same stored columns with
+ * every skipped-or-denied key removed — so it never sees another computed
+ * field's resolved value (ADR-0027).
  */
 async function resolveReadableFieldValue(params: {
   fieldConfig: FieldConfig | undefined
@@ -189,6 +201,13 @@ export async function filterReadableFields<T extends Record<string, unknown>>(
   // returned — after resolveOutput has had a chance to read them — so a
   // declared dependency never widens what the caller receives.
   declaredOnly: DeclaredOnlyTree = emptyDeclaredOnlyTree(),
+  // The fragment scope this level was reached under (ADR-0027), and the same
+  // tree one level down for each nested relation. `undefined` — the default,
+  // and what a bare/`include`-based read passes at every level — means
+  // unrestricted: every field on the list is computed, unchanged from
+  // before ADR-0027. Only a `query` fragment's own field selection ever
+  // restricts a level.
+  selection?: FieldSelectionScope,
 ): Promise<Partial<T>> {
   const filtered: Record<string, unknown> = {}
 
@@ -214,6 +233,15 @@ export async function filterReadableFields<T extends Record<string, unknown>>(
     workingItem[fieldName] = assembled
   }
 
+  // Keys denied by field-level read access during the pass below — as opposed
+  // to a key merely skipped by `selection` or held back only for
+  // `declaredOnly` stripping. Tracked separately because a denied key must
+  // stay invisible to a computed field's hook (below), while a declared-only
+  // key must stay VISIBLE to one — that is the entire point of declaring it
+  // (ADR-0025) — even though `selection` above skipped adding it to
+  // `filtered` because the caller's fragment never asked for it.
+  const accessDeniedKeys = new Set<string>()
+
   // Process existing fields from the database result
   for (const [fieldName, value] of Object.entries(workingItem)) {
     const fieldConfig = fieldConfigs[fieldName]
@@ -224,8 +252,19 @@ export async function filterReadableFields<T extends Record<string, unknown>>(
       continue
     }
 
+    // Projection-aware skip (ADR-0027): a fragment read that does not select
+    // this field does no work for it at all — no field-level read-access
+    // check, no resolveOutput, no recursion into a relation — because the
+    // read is never going to return it. `selection` is only ever restricted
+    // by a fragment's own field selection; a bare/`include`-based read, and a
+    // relation reached only to satisfy another field's `needs`, pass no
+    // selection at all and compute every field here, unchanged.
+    if (selection?.fields && !selection.fields.has(fieldName)) {
+      continue
+    }
+
     // Handle relationship fields - recursively filter fields within related items
-    // Note: Access control filtering is now done at database level via buildIncludeWithAccessControl
+    // Note: Access control filtering is now done at database level via buildAccessScopedInclude
     // This only handles field-level access (hiding sensitive fields)
     //
     // Deliberately uncapped: the row/relation scoping in access-filter.ts bounds
@@ -251,6 +290,7 @@ export async function filterReadableFields<T extends Record<string, unknown>>(
       })
 
       if (!canRead) {
+        accessDeniedKeys.add(fieldName)
         continue
       }
 
@@ -260,6 +300,12 @@ export async function filterReadableFields<T extends Record<string, unknown>>(
       // back to an empty tree when this relation isn't declaration-related at
       // all — the common case.
       const nestedDeclaredOnly = declaredOnly.nested[fieldName] ?? emptyDeclaredOnlyTree()
+      // This relation's own fragment scope, if the caller's fragment named it
+      // with a nested Fragment/RelationSelector. `undefined` (a bare `true`
+      // selector, or no `selection` at all) means the nested list computes
+      // unrestricted — matching what naming a relation without narrowing it
+      // further has always meant.
+      const nestedSelection = selection?.nested[fieldName]
 
       if (relatedConfig) {
         // For many relationships (arrays) - recursively filter fields in each item
@@ -275,6 +321,7 @@ export async function filterReadableFields<T extends Record<string, unknown>>(
                 depth + 1,
                 relatedConfig.listName,
                 nestedDeclaredOnly,
+                nestedSelection,
               ),
             ),
           )
@@ -290,6 +337,7 @@ export async function filterReadableFields<T extends Record<string, unknown>>(
             depth + 1,
             relatedConfig.listName,
             nestedDeclaredOnly,
+            nestedSelection,
           )
         }
       } else {
@@ -314,7 +362,36 @@ export async function filterReadableFields<T extends Record<string, unknown>>(
 
     if (result.readable) {
       filtered[fieldName] = result.value
+    } else {
+      accessDeniedKeys.add(fieldName)
+    }
+  }
+
+  // The item a virtual field's hook sees: stored columns and fetched
+  // relations (from `workingItem`, never a resolved value — no hook's output
+  // is ever written back into `workingItem`). A key is visible here if it
+  // either survived into `filtered` (selected and allowed) OR exists only to
+  // satisfy a `needs` declaration (`declaredOnly` — that IS the point of
+  // declaring it: fetched for a hook, never for the caller, ADR-0025).
+  // Everything else — field-level denied, or skipped by `selection` and
+  // declared by no one — is deleted. A computed field reaches for exactly its
+  // own declared dependencies and nothing another field's hook produced
+  // (ADR-0027): reaching for a sibling that was denied or skipped-and-
+  // undeclared finds nothing there, the same as reaching for one never
+  // declared at all, and reaching for a sibling that DID survive finds its
+  // raw stored form, never another hook's resolved value — a virtual field
+  // computed earlier in declaration order is exactly as invisible as one
+  // computed later.
+  const computedFieldItem: Record<string, unknown> = { ...workingItem }
+  for (const key of Object.keys(workingItem)) {
+    if (['id', 'createdAt', 'updatedAt'].includes(key)) continue
+    if (accessDeniedKeys.has(key)) {
+      delete computedFieldItem[key]
+      continue
     }
+    if (key in filtered) continue
+    if (declaredOnly.keys.has(key)) continue
+    delete computedFieldItem[key]
   }
 
   // Process virtual fields - compute values from other fields
@@ -330,22 +407,29 @@ export async function filterReadableFields<T extends Record<string, unknown>>(
       continue
     }
 
-    // Virtual fields must have a resolveOutput hook to compute their value;
-    // without one there is nothing to add to the result.
+    // Projection-aware skip (ADR-0027): same rule as the stored-field pass
+    // above — a fragment that does not select this virtual field does no
+    // work for it at all.
+    if (selection?.fields && !selection.fields.has(fieldName)) {
+      continue
+    }
+
+    // A virtual field with no resolveOutput hook can never produce a value
+    // on ANY read — there is nothing to compute, so there is nothing to do,
+    // including evaluating its read access (ADR-0027 reconciles the
+    // access-only evaluation this branch used to preserve: a field that
+    // never has output has no side effect worth preserving access for).
     if (!(fieldConfig.hooks?.resolveOutput && listKey)) {
-      // Still evaluate read access to preserve any access-fn side effects.
-      await checkFieldAccess(fieldConfig.access, 'read', { ...args, item: workingItem })
       continue
     }
 
-    // Check read access and compute the value via the shared helper. Virtual
-    // fields see the already-filtered item so they can read sibling fields.
+    // Check read access and compute the value via the shared helper.
     const result = await resolveReadableFieldValue({
       fieldConfig,
       fieldName,
       value: undefined, // Virtual fields don't have a database value
       accessItem: workingItem,
-      hookItem: filtered,
+      hookItem: computedFieldItem,
       listKey,
       args,
       config,
@@ -357,10 +441,11 @@ export async function filterReadableFields<T extends Record<string, unknown>>(
   }
 
   // Strip relations that were fetched ONLY to satisfy a `needs` declaration
-  // (ADR-0025), now that every resolveOutput hook at this level — including
-  // virtual fields, which read the assembled `filtered` object above — has
-  // had the chance to see them. A declared dependency is private plumbing,
-  // not an implicit `include`: it never widens what the caller receives.
+  // (ADR-0025), now that every resolveOutput hook at this level has had the
+  // chance to see them (via `computedFieldItem`, never `filtered` itself — a
+  // declared dependency is read from stored columns, not from another
+  // field's resolved output). A declared dependency is private plumbing, not
+  // an implicit `include`: it never widens what the caller receives.
   for (const key of declaredOnly.keys) {
     delete filtered[key]
   }

package/src/access/index.ts

@@ -22,13 +22,7 @@ export {
 // Canonical field-level access evaluation (shared by read and write paths).
 export { checkFieldAccess, filterWritableFields } from './field-access.js'
 // Phase 1 — Access Filter (pre-query row/relation scoping).
-export {
-  buildIncludeWithAccessControl,
-  mergeIncludeWithAccessControl,
-  stripVirtualFieldsFromInclude,
-  toPrismaInclude,
-} from './access-filter.js'
-export type { AccessIncludeResult } from './access-filter.js'
+export { buildAccessScopedInclude, stripVirtualFieldsFromInclude } from './access-filter.js'
 // Phase 2 — Field Visibility (post-query field stripping + resolveOutput).
 export { filterReadableFields } from './field-visibility.js'
 // Declared Dependencies — folding `needs` into an include without widening

package/src/access/relationship-count.ts

@@ -15,7 +15,7 @@ import { getDbKey } from '../lib/case-utils.js'
  * per-row query is issued and the count can never include rows the session
  * cannot read. This module is the single place the related list's
  * operation-level `query` access is folded into that `_count`, mirroring how
- * `buildIncludeWithAccessControl` folds it into relation includes.
+ * `buildAccessScopedInclude` folds it into relation includes.
  *
  * It also resolves the count Filter spec's markers: Prisma cannot compare a
  * relation count in a `where`, so a to-many relationship's Filter spec emits a

package/src/config/index.ts

@@ -146,6 +146,8 @@ export type {
   FieldHooks,
   FieldsWithTypeInfo,
   DatabaseConfig,
+  ListIndex,
+  ListIndexFieldRef,
   SessionConfig,
   UIConfig,
   ListUIConfig,

package/src/config/types.ts

@@ -1109,6 +1109,28 @@ export type RelationshipField<TTypeInfo extends TypeInfo = TypeInfo> =
      */
     isIndexed?: boolean | 'unique'
     db?: {
+      /**
+       * Controls DB-level nullability of the foreign key column (and its
+       * relation field) independently of the many side's own shape. Only
+       * meaningful on the FK-owning (single) side of a relationship — the
+       * many side has no column of its own to make non-nullable and rejects
+       * this option.
+       *
+       * @default true (nullable, matching every relationship generated before
+       * this option existed)
+       *
+       * @example
+       * ```typescript
+       * // Every session genuinely belongs to a user — make the FK required
+       * user: relationship({
+       *   ref: 'User.sessions',
+       *   db: { isNullable: false },
+       * })
+       * // Generates: userId String  (was String?)
+       * //            user   User    @relation(...)  (was User?)
+       * ```
+       */
+      isNullable?: boolean
       /**
        * Controls foreign key placement and column name for bidirectional relationships
        * Can be a boolean or an object with a map property
@@ -1246,6 +1268,16 @@ export type PrismaRelationResult = {
    * for the many side or the non-FK side it is `[relationLine]`.
    */
   modelLines: string[]
+  /**
+   * The Prisma-level foreign key field name this side owns (e.g. `authorId`),
+   * regardless of whether it is indexed. `undefined` when this side doesn't
+   * own a foreign key column at all (the many side, or the non-FK side of a
+   * one-to-one). Lets other generator passes resolve a relationship field
+   * name to its physical column — e.g. a model-level composite index
+   * ({@link ListIndex}) naming a relationship field — without duplicating
+   * {@link foreignKeyIndex}'s narrower, indexing-conditional presence.
+   */
+  foreignKeyField?: string
   /**
    * Foreign key index to add to the owning model, if this side owns an
    * indexed foreign key.
@@ -1802,6 +1834,43 @@ export type Hooks<
   validateInput?: (args: ValidateHookArgs<TOutput, TCreateInput, TUpdateInput>) => Promise<void>
 }
 
+/**
+ * A single field reference within a model-level {@link ListIndex}. Either
+ * just the OpenSaaS field name, or an object naming it alongside a sort
+ * direction.
+ */
+export type ListIndexFieldRef =
+  | string
+  | {
+      field: string
+      /** Sort direction for this column within the index/constraint. */
+      sort?: 'asc' | 'desc'
+    }
+
+/**
+ * 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).
+ */
+export type ListIndex = {
+  /**
+   * The fields participating in this index/constraint, in declaration order.
+   * OpenSaaS field names, not raw database column names.
+   */
+  fields: ListIndexFieldRef[]
+  /**
+   * Emit `@@unique([...])` instead of `@@index([...])`.
+   * @default false
+   */
+  unique?: boolean
+  /**
+   * Constraint/index name, emitted as Prisma's `map:` argument — lets an
+   * existing live constraint be adopted under its current name rather than
+   * renamed.
+   */
+  name?: string
+}
+
 // Generic `any` default allows ListConfig to work with any list item type
 // This is needed because the item type varies per list and is inferred from Prisma models
 /**
@@ -1879,6 +1948,67 @@ 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).
+     *
+     * 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.
+     *
+     * 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).
+     *
+     * 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.
+     *
+     * @example One audition per student per production (composite unique)
+     * ```typescript
+     * Audition: list({
+     *   fields: {
+     *     student: relationship({ ref: 'Student.auditions' }),
+     *     production: relationship({ ref: 'Production.auditions' }),
+     *   },
+     *   db: {
+     *     indexes: [{ fields: ['student', 'production'], unique: true }],
+     *   },
+     * })
+     * // Generates: @@unique([studentId, productionId])
+     * ```
+     *
+     * @example Hot lookup path (composite index) with a sort direction and an adopted constraint name
+     * ```typescript
+     * AuthVerification: list({
+     *   fields: {
+     *     identifier: text(),
+     *     createdAt: timestamp(),
+     *   },
+     *   db: {
+     *     indexes: [
+     *       {
+     *         fields: ['identifier', { field: 'createdAt', sort: 'desc' }],
+     *         name: 'AuthVerification_identifier_createdAt_idx',
+     *       },
+     *     ],
+     *   },
+     * })
+     * // Generates: @@index([identifier, createdAt(sort: Desc)], map: "AuthVerification_identifier_createdAt_idx")
+     * ```
+     */
+    indexes?: ListIndex[]
   }
   /**
    * MCP server configuration for this list

package/src/context/index.ts

@@ -4,8 +4,7 @@ import {
   checkAccess,
   mergeFilters,
   filterReadableFields,
-  buildIncludeWithAccessControl,
-  mergeIncludeWithAccessControl,
+  buildAccessScopedInclude,
   stripVirtualFieldsFromInclude,
   foldDeclaredDependencies,
 } from '../access/index.js'
@@ -13,8 +12,8 @@ import type { DeclaredOnlyTree } from '../access/index.js'
 import { ValidationError, DatabaseError } from '../hooks/index.js'
 import { getDbKey } from '../lib/case-utils.js'
 import type { PrismaClientLike } from '../access/types.js'
-import { buildInclude, pickFields, isFragment } from '../query/index.js'
-import type { FieldSelection } from '../query/index.js'
+import { buildInclude, pickFields, isFragment, buildFieldSelectionScope } from '../query/index.js'
+import type { FieldSelection, FieldSelectionScope } from '../query/index.js'
 import { getRelationshipOptions } from '../query/relationship-options.js'
 import {
   runWritePipeline,
@@ -921,11 +920,19 @@ export function buildDbDelegate<TPrisma extends PrismaClientLike>(
  *
  * A fragment's own `include` and a sudo caller's `include` are folded and
  * used as-is, matching their existing (unmerged) treatment. A non-sudo
- * caller include is folded and then merged through the same
- * access-scoping pipeline as before. A bare read stays on the exact
- * ADR-0024 path — `include: undefined`, no related `query` access
- * evaluated — unless folding actually added something, which only happens
- * when a field on this list declares `needs`.
+ * caller include is folded and then scoped by `buildAccessScopedInclude`
+ * (ADR-0026) — caller-directed, so a relation named nowhere in the folded
+ * tree never has its list's `query` access evaluated at all. A bare read
+ * stays on the exact ADR-0024 path — `include: undefined`, no related
+ * `query` access evaluated — unless folding actually added something, which
+ * only happens when a field on this list declares `needs`.
+ *
+ * Also returns the `FieldSelectionScope` a fragment's own field selection
+ * produces (ADR-0027), so the caller can pass it to `filterReadableFields`
+ * and make computation itself projection-aware, not only the fold above.
+ * `undefined` for every non-fragment path: a caller `include` (sudo or not)
+ * and a bare read both mean "compute every field," matching what they
+ * already fetch.
  */
 async function resolveReadInclude(
   callerInclude: Record<string, unknown> | undefined,
@@ -935,38 +942,43 @@ async function resolveReadInclude(
   listConfig: ListConfig<any>,
   context: AccessContext & { _isSudo?: boolean },
   config: OpenSaasConfig,
-): Promise<{ include: Record<string, unknown> | undefined; declaredOnly: DeclaredOnlyTree }> {
+): Promise<{
+  include: Record<string, unknown> | undefined
+  declaredOnly: DeclaredOnlyTree
+  selection: FieldSelectionScope | undefined
+}> {
   if (fragmentFields !== undefined) {
     const fragmentInclude = buildInclude(fragmentFields) ?? undefined
-    return foldDeclaredDependencies(fragmentInclude, listConfig.fields, config)
+    const selection = buildFieldSelectionScope(fragmentFields)
+    const folded = foldDeclaredDependencies(
+      fragmentInclude,
+      listConfig.fields,
+      config,
+      listName,
+      [listName],
+      selection,
+    )
+    return { ...folded, selection }
   }
 
   if (context._isSudo) {
-    return foldDeclaredDependencies(callerInclude, listConfig.fields, config)
+    const folded = foldDeclaredDependencies(callerInclude, listConfig.fields, config, listName)
+    return { ...folded, selection: undefined }
   }
 
-  const folded = foldDeclaredDependencies(callerInclude, listConfig.fields, config)
+  const folded = foldDeclaredDependencies(callerInclude, listConfig.fields, config, listName)
   if (!folded.include) {
-    return folded
+    return { ...folded, selection: undefined }
   }
 
-  const accessControlledInclude = await buildIncludeWithAccessControl(
-    listConfig.fields,
-    { session: context.session, context },
-    config,
-    0,
-    // Seed the cycle guard with the root list so a relationship cycle back
-    // to it (self-referential or longer) stops re-descending.
-    [listName],
-  )
-  const include = mergeIncludeWithAccessControl(
+  const include = await buildAccessScopedInclude(
     folded.include,
-    accessControlledInclude,
     listConfig.fields,
+    { session: context.session, context },
     config,
     listName,
   )
-  return { include, declaredOnly: folded.declaredOnly }
+  return { include, declaredOnly: folded.declaredOnly, selection: undefined }
 }
 
 /**
@@ -1032,7 +1044,7 @@ function createFindUnique<TPrisma extends PrismaClientLike>(
     // Resolve `include`, folding any declared dependencies (`needs`,
     // ADR-0025) in alongside whatever the fragment/caller/sudo/bare path
     // already produces — see `resolveReadInclude`'s doc comment.
-    let { include, declaredOnly } = await resolveReadInclude(
+    let { include, declaredOnly, selection } = await resolveReadInclude(
       args.include,
       fragment ? fragment._fields : undefined,
       listName,
@@ -1044,8 +1056,10 @@ function createFindUnique<TPrisma extends PrismaClientLike>(
     // Virtual fields have no database column. Whichever path produced
     // `include` (fragment, access-controlled merge, or sudo passthrough), a
     // virtual key must never reach Prisma — it would throw "Unknown field"
-    // (#628). The virtual value is still computed unconditionally below by
-    // `filterReadableFields`, independent of what was requested here.
+    // (#628). Below, `filterReadableFields` computes a virtual field's value
+    // exactly when `selection` says the read is going to return it (ADR-0027)
+    // — every one of them for a bare/`include`-based read (`selection` is
+    // `undefined`), only the ones a fragment named otherwise.
     include = stripVirtualFieldsFromInclude(include, listConfig.fields, config)
 
     // Execute query with optimized includes
@@ -1074,6 +1088,7 @@ function createFindUnique<TPrisma extends PrismaClientLike>(
       0,
       listName,
       declaredOnly,
+      selection,
     )
 
     // When a fragment is provided, pick only the requested fields from the result
@@ -1145,7 +1160,7 @@ function createFindMany<TPrisma extends PrismaClientLike>(
     // Resolve `include`, folding any declared dependencies (`needs`,
     // ADR-0025) in alongside whatever the fragment/caller/sudo/bare path
     // already produces — see `resolveReadInclude`'s doc comment.
-    let { include, declaredOnly } = await resolveReadInclude(
+    let { include, declaredOnly, selection } = await resolveReadInclude(
       args?.include,
       fragment ? fragment._fields : undefined,
       listName,
@@ -1157,8 +1172,10 @@ function createFindMany<TPrisma extends PrismaClientLike>(
     // Virtual fields have no database column. Whichever path produced
     // `include` (fragment, access-controlled merge, or sudo passthrough), a
     // virtual key must never reach Prisma — it would throw "Unknown field"
-    // (#628). The virtual value is still computed unconditionally below by
-    // `filterReadableFields`, independent of what was requested here.
+    // (#628). Below, `filterReadableFields` computes a virtual field's value
+    // exactly when `selection` says the read is going to return it (ADR-0027)
+    // — every one of them for a bare/`include`-based read (`selection` is
+    // `undefined`), only the ones a fragment named otherwise.
     include = stripVirtualFieldsFromInclude(include, listConfig.fields, config)
 
     // Execute query with optimized includes
@@ -1188,6 +1205,7 @@ function createFindMany<TPrisma extends PrismaClientLike>(
           0,
           listName,
           declaredOnly,
+          selection,
         ),
       ),
     )
@@ -1461,7 +1479,7 @@ function createGet<TPrisma extends PrismaClientLike>(
     // Resolve `include`, folding any declared dependencies (`needs`,
     // ADR-0025) in alongside whatever the fragment/caller/sudo/bare path
     // already produces — see `resolveReadInclude`'s doc comment.
-    let { include, declaredOnly } = await resolveReadInclude(
+    let { include, declaredOnly, selection } = await resolveReadInclude(
       args?.include,
       fragment ? fragment._fields : undefined,
       listName,
@@ -1493,6 +1511,7 @@ function createGet<TPrisma extends PrismaClientLike>(
         0,
         listName,
         declaredOnly,
+        selection,
       )
       // When a fragment is provided, pick only the requested fields from the result
       if (fragment) {

package/src/fields/index.ts

@@ -1387,10 +1387,16 @@ function getPrismaRelation(
         ? ` @map("${field.db.foreignKey.map}")`
         : ` @map("${fieldName}")`
 
-    let fkLine = `  ${fkPaddedName} String?${uniqueModifier}${mapModifier}`
+    // Nullability: explicit db.isNullable overrides the default (nullable),
+    // matching the scalar fields' `db.isNullable` convention. It moves the FK
+    // column and its relation field together — they can never disagree.
+    const isNullable = field.db?.isNullable ?? true
+    const nullModifier = isNullable ? '?' : ''
+
+    let fkLine = `  ${fkPaddedName} String${nullModifier}${uniqueModifier}${mapModifier}`
     let relationLine = targetField
-      ? `  ${paddedName} ${targetList}?  @relation(fields: [${foreignKeyField}], references: [id])`
-      : `  ${paddedName} ${targetList}?  @relation("${listKey}_${fieldName}", fields: [${foreignKeyField}], references: [id])`
+      ? `  ${paddedName} ${targetList}${nullModifier}  @relation(fields: [${foreignKeyField}], references: [id])`
+      : `  ${paddedName} ${targetList}${nullModifier}  @relation("${listKey}_${fieldName}", fields: [${foreignKeyField}], references: [id])`
 
     if (field.db?.extendPrismaSchema) {
       const extended = field.db.extendPrismaSchema({ fkLine, relationLine })
@@ -1402,10 +1408,24 @@ function getPrismaRelation(
     const indexType = field.isIndexed ?? true
     const foreignKeyIndex = indexType !== false ? { foreignKeyField, indexType } : undefined
 
-    return { modelLines: [fkLine, relationLine], foreignKeyIndex, backRelation }
+    return { modelLines: [fkLine, relationLine], foreignKeyField, foreignKeyIndex, backRelation }
+  }
+
+  // Non-FK side of a one-to-one relationship: just the relation field. This
+  // side has no foreign key column, so `db.isNullable` (which only makes
+  // sense paired with a column) cannot be honoured here — reject rather than
+  // silently ignore a developer's stated intent (the FK-owning side is
+  // determined by `db.foreignKey`/alphabetical ordering, not by which field
+  // declares `isNullable`).
+  if (field.db?.isNullable === false) {
+    throw new Error(
+      `db.isNullable can only be used on the foreign-key-owning side of a relationship. ` +
+        `"${listKey}.${fieldName}" does not own the foreign key for this one-to-one relationship — ` +
+        `set db.isNullable on "${targetList}.${targetField}" instead, or make this side own the ` +
+        `foreign key via db.foreignKey.`,
+    )
   }
 
-  // Non-FK side of a one-to-one relationship: just the relation field
   let relationLine = `  ${paddedName} ${targetList}?`
   if (field.db?.extendPrismaSchema) {
     relationLine = field.db.extendPrismaSchema({ relationLine }).relationLine
@@ -1451,6 +1471,16 @@ export function relationship<
     }
   }
 
+  // Validate db.isNullable usage: only the FK-owning (single) side of a
+  // relationship has a column to make non-nullable — the many side always
+  // generates an array field with no nullability of its own.
+  if (options.db?.isNullable !== undefined && options.many) {
+    throw new Error(
+      'db.isNullable can only be used on single relationships (many: false or undefined). ' +
+        'Many-side of a relationship has no foreign key column to make non-nullable.',
+    )
+  }
+
   const field: RelationshipField<TTypeInfo> = {
     type: 'relationship',
     ...options,

package/src/index.ts

@@ -19,6 +19,8 @@ export type {
   OutputConfig,
   ListConfig,
   DatabaseConfig,
+  ListIndex,
+  ListIndexFieldRef,
   FieldConfig,
   OperationAccess,
   // Custom Bulk actions (issue #736) — declared per list in