@opensaas/stack-core 0.35.0 → 0.37.0

package/dist/validation/needs-closure.js

@@ -0,0 +1,139 @@
+import { getRelatedListConfig } from '../access/engine.js';
+import { READ_INCLUDE_MAX_DEPTH } from '../access/depth-limits.js';
+function isRelationshipFieldConfig(fieldConfig) {
+    return (!!fieldConfig &&
+        fieldConfig.type === 'relationship' &&
+        'ref' in fieldConfig &&
+        !!fieldConfig.ref);
+}
+/**
+ * The deepest needs-chain reachable from `listKey`, considering EVERY field
+ * on every list along the way that declares `needs` — not only the field
+ * that triggered the walk. A computed field runs wherever its list's rows
+ * are fetched, so once a list is reached, ALL of its own declared
+ * dependencies must be satisfiable too (ADR-0025's "at every level a field
+ * is computed").
+ *
+ * `path` is the list keys already on this DFS branch, root-first, used to
+ * detect a cycle (a chain that can never terminate).
+ */
+function listClosureDepth(listKey, config, path) {
+    const listConfig = config.lists[listKey];
+    if (!listConfig?.fields)
+        return { depth: 0, chain: [listKey] };
+    let maxDepth = 0;
+    let maxChain = [listKey];
+    for (const fieldConfig of Object.values(listConfig.fields)) {
+        if (!fieldConfig?.hooks?.resolveOutput)
+            continue;
+        for (const relationName of fieldConfig.needs ?? []) {
+            const relatedField = listConfig.fields[relationName];
+            if (!isRelationshipFieldConfig(relatedField))
+                continue;
+            const relatedConfig = getRelatedListConfig(relatedField.ref, config);
+            if (!relatedConfig)
+                continue;
+            const relatedListKey = relatedConfig.listName;
+            if (path.includes(relatedListKey)) {
+                return { cycle: [...path, relatedListKey] };
+            }
+            const sub = listClosureDepth(relatedListKey, config, [...path, relatedListKey]);
+            if ('cycle' in sub)
+                return sub;
+            if (1 + sub.depth > maxDepth) {
+                maxDepth = 1 + sub.depth;
+                maxChain = [listKey, ...sub.chain];
+            }
+        }
+    }
+    return { depth: maxDepth, chain: maxChain };
+}
+/**
+ * Validate that every `needs` entry names an immediate relationship field
+ * declared on the SAME list. The generated `Lists.<List>.TypeInfo` already
+ * makes a misspelled or non-relation entry a compile error for a config
+ * annotated with it (`list<Lists.X.TypeInfo>({...})`, the documented
+ * pattern) — this is the runtime backstop for configs that aren't, or that
+ * are authored in plain JS.
+ *
+ * @param config - The fully resolved OpenSaas config.
+ * @returns All invalid `needs` entries, flattened across lists and fields.
+ */
+export function validateNeedsDeclarations(config) {
+    const errors = [];
+    for (const [listKey, listConfig] of Object.entries(config.lists)) {
+        if (!listConfig?.fields)
+            continue;
+        for (const [fieldKey, fieldConfig] of Object.entries(listConfig.fields)) {
+            for (const relationName of fieldConfig?.needs ?? []) {
+                if (isRelationshipFieldConfig(listConfig.fields[relationName]))
+                    continue;
+                const exists = relationName in listConfig.fields;
+                errors.push({
+                    listKey,
+                    fieldKey,
+                    chain: [listKey],
+                    reason: 'invalid-relation',
+                    message: exists
+                        ? `"${listKey}.${fieldKey}" declares needs: ['${relationName}'], but "${relationName}" ` +
+                            `is not a relationship field on "${listKey}". \`needs\` may only name immediate ` +
+                            `relationship fields declared on the same list.`
+                        : `"${listKey}.${fieldKey}" declares needs: ['${relationName}'], but "${listKey}" has ` +
+                            `no field named "${relationName}".`,
+                });
+            }
+        }
+    }
+    return errors;
+}
+/**
+ * Validate that every field's `needs` closure fits within
+ * `READ_INCLUDE_MAX_DEPTH` when evaluated starting at the declaring field's
+ * own list — the most favourable starting point a caller could ever give it.
+ * Intended to run once, before generation, exactly like
+ * {@link validateConfigFields} — a config whose closure cannot fit must not
+ * generate, per ADR-0025's "Depth" section.
+ *
+ * @param config - The fully resolved OpenSaas config.
+ * @returns All unsatisfiable-closure violations, flattened across lists and fields.
+ */
+export function validateNeedsClosureDepth(config) {
+    const errors = [];
+    for (const [listKey, listConfig] of Object.entries(config.lists)) {
+        if (!listConfig?.fields)
+            continue;
+        for (const [fieldKey, fieldConfig] of Object.entries(listConfig.fields)) {
+            if (!fieldConfig?.hooks?.resolveOutput || !fieldConfig.needs?.length)
+                continue;
+            const result = listClosureDepth(listKey, config, [listKey]);
+            if ('cycle' in result) {
+                errors.push({
+                    listKey,
+                    fieldKey,
+                    chain: result.cycle,
+                    reason: 'cycle',
+                    message: `"${listKey}.${fieldKey}"'s needs declaration never terminates: ` +
+                        `${result.cycle.join(' → ')} → … . A chain of \`needs\` across these lists cycles back ` +
+                        `on itself, so no read could ever satisfy it. Break the cycle by removing one of the ` +
+                        `\`needs\` entries on this chain, or compute the value without it.`,
+                });
+                continue;
+            }
+            if (result.depth >= READ_INCLUDE_MAX_DEPTH) {
+                errors.push({
+                    listKey,
+                    fieldKey,
+                    chain: result.chain,
+                    reason: 'depth',
+                    message: `"${listKey}.${fieldKey}"'s needs declaration requires a closure ${result.depth} ` +
+                        `relations deep even starting at "${listKey}" itself: ${result.chain.join(' → ')}. ` +
+                        `This exceeds the Access Filter's maximum read-include depth ` +
+                        `(${READ_INCLUDE_MAX_DEPTH}), so no caller — however they start the read — could ever ` +
+                        `have this closure satisfied. Shorten the \`needs\` chain across these lists.`,
+                });
+            }
+        }
+    }
+    return errors;
+}
+//# sourceMappingURL=needs-closure.js.map

package/dist/validation/needs-closure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"needs-closure.js","sourceRoot":"","sources":["../../src/validation/needs-closure.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensaas/stack-core",
-  "version": "0.35.0",
+  "version": "0.37.0",
   "description": "Core stack for OpenSaas - schema definition, access control, and runtime utilities",
   "type": "module",
   "main": "./dist/index.js",

package/src/access/declared-dependencies.ts

@@ -0,0 +1,140 @@
+import type { FieldConfig, OpenSaasConfig } from '../config/types.js'
+import { getRelatedListConfig } from './engine.js'
+
+/**
+ * Declared Dependencies — folding a computed field's `needs` into a read's
+ * `include` without widening what the caller receives (ADR-0025).
+ *
+ * A field's `needs` declares immediate sibling relations its `resolveOutput`
+ * hook cannot compute without. This module folds those relations into
+ * whatever `include` a read is already building (caller-supplied, fragment-
+ * derived, or none at all) BEFORE it reaches the existing access-scoping
+ * pipeline (`buildIncludeWithAccessControl` / `mergeIncludeWithAccessControl`
+ * in `access-filter.ts`) — a declared relation is scoped exactly like a
+ * caller-named one, never a bypass.
+ *
+ * The fold also tracks provenance: which relation keys, at which nesting
+ * level, were added ONLY to satisfy a declaration (as opposed to being named
+ * by the caller). `field-visibility.ts` uses that tree to strip those keys
+ * from the result after `resolveOutput` hooks have had a chance to read them
+ * — a declared dependency is private plumbing, not an implicit `include`.
+ *
+ * Reach beyond one hop: a relation added here to satisfy a declaration is
+ * added BARE (`true`), never with an explicit nested include of its own.
+ * `buildIncludeWithAccessControl` already auto-expands a bare relation's own
+ * readable-relationship subtree to `READ_INCLUDE_MAX_DEPTH` (pre-ADR-0026),
+ * so a chain of declarations rides that existing expansion for free — the
+ * related list's own declared needs are already present among what gets
+ * auto-included beneath it. This is also why a declaration-driven cycle
+ * (e.g. `Order.total` needs `lineItems`, `LineItem.orderRef` needs `order`)
+ * can't recurse without bound here: it flows through
+ * `buildIncludeWithAccessControl`'s existing `visitedLists` cycle guard
+ * rather than through any recursion of this module's own (see ADR-0026's
+ * note that this guard's remaining job, after that ADR lands, is defending
+ * exactly this fold).
+ *
+ * This module only recurses into EXPLICIT nested includes the caller wrote
+ * (narrowing what's fetched below a relation) — those cut off the free
+ * auto-expansion, so a nested list's own declared needs must be folded in
+ * explicitly. An explicit caller include is always a finite literal, so this
+ * recursion terminates on its own without a separate depth/cycle guard.
+ */
+
+/** Which relation keys, at which nesting level, exist only to satisfy a `needs` declaration. */
+export type DeclaredOnlyTree = {
+  /** Keys at THIS level whose entire branch was added purely by the fold. */
+  keys: Set<string>
+  /** Per-key trees for relations present in the include for other reasons (caller-named), whose OWN nested include may still contain declaration-only keys. */
+  nested: Record<string, DeclaredOnlyTree>
+}
+
+export function emptyDeclaredOnlyTree(): DeclaredOnlyTree {
+  return { keys: new Set(), nested: {} }
+}
+
+function isDeclaredOnlyTreeEmpty(tree: DeclaredOnlyTree): boolean {
+  return tree.keys.size === 0 && Object.keys(tree.nested).length === 0
+}
+
+function isRelationshipFieldConfig(
+  fieldConfig: FieldConfig | undefined,
+): fieldConfig is FieldConfig & { type: 'relationship'; ref: string } {
+  return (
+    !!fieldConfig &&
+    fieldConfig.type === 'relationship' &&
+    'ref' in fieldConfig &&
+    !!fieldConfig.ref
+  )
+}
+
+/**
+ * The deduped set of relation names declared via `needs` by fields on this
+ * list that have a `resolveOutput` hook. A `needs` entry on a field without
+ * one is inert — there is no hook to feed it to — so it contributes nothing
+ * to fetch.
+ */
+export function getDeclaredRelationNames(fieldConfigs: Record<string, FieldConfig>): string[] {
+  const names = new Set<string>()
+  for (const fieldConfig of Object.values(fieldConfigs)) {
+    if (!fieldConfig?.hooks?.resolveOutput) continue
+    for (const name of fieldConfig.needs ?? []) {
+      names.add(name)
+    }
+  }
+  return [...names]
+}
+
+/**
+ * Fold this list's declared dependencies into `rawInclude`, recursing into
+ * any EXPLICIT nested include the caller wrote so a related list's own
+ * declared needs are satisfied too (see module doc comment).
+ *
+ * Returns `rawInclude` itself (same reference) when there is nothing to
+ * fold, so a list with no `needs` fields and no caller include stays on the
+ * exact bare-read path (ADR-0024) — untouched, not merely equivalent.
+ */
+export function foldDeclaredDependencies(
+  rawInclude: Record<string, unknown> | undefined,
+  fieldConfigs: Record<string, FieldConfig>,
+  config: OpenSaasConfig,
+): { include: Record<string, unknown> | undefined; declaredOnly: DeclaredOnlyTree } {
+  const declaredNames = getDeclaredRelationNames(fieldConfigs)
+
+  if (declaredNames.length === 0 && !rawInclude) {
+    return { include: rawInclude, declaredOnly: emptyDeclaredOnlyTree() }
+  }
+
+  const declaredOnly = emptyDeclaredOnlyTree()
+  const merged: Record<string, unknown> = { ...(rawInclude ?? {}) }
+
+  for (const name of declaredNames) {
+    if (name in merged) continue // caller (or fragment) already asked for it — not declaration-only
+    if (!isRelationshipFieldConfig(fieldConfigs[name])) continue // invalid `needs` entry; caught by generate-time validation
+    merged[name] = true
+    declaredOnly.keys.add(name)
+  }
+
+  for (const [key, value] of Object.entries(merged)) {
+    const fieldConfig = fieldConfigs[key]
+    if (!isRelationshipFieldConfig(fieldConfig)) continue
+    // A whole branch we just added is bare `true` — its own subtree auto-expands
+    // (see module doc comment), so there is no explicit nested include to recurse into.
+    if (declaredOnly.keys.has(key)) continue
+
+    const entry = value as { include?: Record<string, unknown> } | boolean
+    if (!entry || typeof entry !== 'object' || !entry.include) continue
+
+    const relatedConfig = getRelatedListConfig(fieldConfig.ref, config)
+    if (!relatedConfig) continue
+
+    const nested = foldDeclaredDependencies(entry.include, relatedConfig.listConfig.fields, config)
+    if (nested.include !== entry.include) {
+      merged[key] = { ...entry, include: nested.include }
+    }
+    if (!isDeclaredOnlyTreeEmpty(nested.declaredOnly)) {
+      declaredOnly.nested[key] = nested.declaredOnly
+    }
+  }
+
+  return { include: merged, declaredOnly }
+}

package/src/access/field-visibility.ts

@@ -4,6 +4,8 @@ import { getRelatedListConfig } from './engine.js'
 import { checkFieldAccess } from './field-access.js'
 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'
 // 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
@@ -181,6 +183,12 @@ export async function filterReadableFields<T extends Record<string, unknown>>(
   config?: OpenSaasConfig,
   depth: number = 0,
   listKey?: string,
+  // Relation keys added purely to satisfy a field's `needs` (ADR-0025) at
+  // THIS level, and the same tree for each nested relation reached via a
+  // caller-named branch. Stripped from `filtered` right before it is
+  // returned — after resolveOutput has had a chance to read them — so a
+  // declared dependency never widens what the caller receives.
+  declaredOnly: DeclaredOnlyTree = emptyDeclaredOnlyTree(),
 ): Promise<Partial<T>> {
   const filtered: Record<string, unknown> = {}
 
@@ -247,6 +255,11 @@ export async function filterReadableFields<T extends Record<string, unknown>>(
       }
 
       const relatedConfig = getRelatedListConfig(fieldConfig.ref as string, config)
+      // The declared-only tree for whatever THIS relation's own list computes,
+      // e.g. a field on the related list that declares its own `needs`. Falls
+      // back to an empty tree when this relation isn't declaration-related at
+      // all — the common case.
+      const nestedDeclaredOnly = declaredOnly.nested[fieldName] ?? emptyDeclaredOnlyTree()
 
       if (relatedConfig) {
         // For many relationships (arrays) - recursively filter fields in each item
@@ -261,6 +274,7 @@ export async function filterReadableFields<T extends Record<string, unknown>>(
                 config,
                 depth + 1,
                 relatedConfig.listName,
+                nestedDeclaredOnly,
               ),
             ),
           )
@@ -275,6 +289,7 @@ export async function filterReadableFields<T extends Record<string, unknown>>(
             config,
             depth + 1,
             relatedConfig.listName,
+            nestedDeclaredOnly,
           )
         }
       } else {
@@ -341,5 +356,14 @@ 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.
+  for (const key of declaredOnly.keys) {
+    delete filtered[key]
+  }
+
   return filtered as Partial<T>
 }

package/src/access/index.ts

@@ -31,6 +31,14 @@ export {
 export type { AccessIncludeResult } 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
+// the result (ADR-0025).
+export {
+  foldDeclaredDependencies,
+  getDeclaredRelationNames,
+  emptyDeclaredOnlyTree,
+} from './declared-dependencies.js'
+export type { DeclaredOnlyTree } from './declared-dependencies.js'
 // Thrown when a caller include reaches past the depth the Access Filter can scope.
 export { AccessScopeDepthExceededError } from './errors.js'
 // Thrown when a resolveOutput hook's own resolve chain cycles back into itself.

package/src/config/index.ts

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

package/src/config/types.ts

@@ -640,7 +640,8 @@ export type BaseFieldConfig<TTypeInfo extends TypeInfo> = {
    * @param keystoneCompat - Whether Keystone-compat mode is enabled (db.keystoneCompat).
    *   When true, non-null text columns without an explicit defaultValue emit
    *   `@default("")` to match Keystone 6's implicit empty-string text default.
-   * @returns Prisma type string, optional modifiers, and optional enum values
+   * @returns Prisma type string, optional modifiers, optional enum values, and
+   *   an optional block-level index request
    */
   getPrismaType?: (
     fieldName: string,
@@ -655,6 +656,26 @@ export type BaseFieldConfig<TTypeInfo extends TypeInfo> = {
      * The enum name is the value of `type`.
      */
     enumValues?: string[]
+    /**
+     * If set, this field requires a block-level index on the owning model:
+     * `@@index([fieldName])` for `true`, `@@unique([fieldName])` for
+     * `'unique'`. `false` and `undefined` both mean "no index".
+     *
+     * Prisma has no field-level `@index` attribute — a non-unique index can
+     * ONLY be expressed as the model-level `@@index([...])` — so a field that
+     * wants one has to ask for it out-of-line rather than appending to
+     * {@link modifiers}. (A unique index has both forms available; the
+     * built-in scalars keep emitting the inline `@unique` modifier for that
+     * case, so this channel carries only what cannot be written inline.)
+     *
+     * Same shape as {@link PrismaRelationResult.foreignKeyIndex}, which is how
+     * relationship fields have always emitted their foreign-key indexes. The
+     * generator handles both through one emit pass, so the field stays the
+     * authority on whether it can be indexed by name at all — a multi-column
+     * field (see {@link getPrismaColumns}) has no single column matching its
+     * field name and can decline, or name a real column of its own.
+     */
+    index?: boolean | 'unique'
   }
   /**
    * Get TypeScript type information for type generation
@@ -755,6 +776,49 @@ export type BaseFieldConfig<TTypeInfo extends TypeInfo> = {
    * @param value - The resolved logical value (metadata, or `null` to clear)
    */
   splitColumns?: (fieldName: string, value: unknown) => Record<string, unknown>
+  /**
+   * Declares the immediate sibling relations this field's `resolveOutput`
+   * hook cannot compute without (ADR-0025 — the "Declared dependency" glossary
+   * entry in `CONTEXT.md`). The read fetches each declared relation wherever
+   * this field is computed — at the root of a read and at every nested level
+   * alike — and scopes it through the Access Filter exactly like a
+   * caller-named relation: a dependency a session cannot query is not
+   * fetched, and the hook sees nothing in its place.
+   *
+   * A declared dependency is private plumbing, not an implicit `include`: it
+   * is stripped from the result unless the caller named it too, so declaring
+   * or removing one changes this field's implementation, never the shape of
+   * every read of the list.
+   *
+   * Names immediate relations only — no dotted paths. Reach beyond one hop
+   * comes from the recursive fold: a dependency's own list declares its own
+   * dependencies.
+   *
+   * Typed as a plain `string[]`, not narrowed to this list's own relation
+   * keys: `BaseFieldConfig` is the contextual type EVERY field builder's
+   * return type is checked against, including non-generic third-party ones
+   * (`richText(): RichTextField`, with no `TTypeInfo` parameter of its own —
+   * the documented third-party field pattern). Narrowing `needs` per-list
+   * would make `needs`'s type on a fixed, unparameterized third-party field
+   * config disagree with the narrower type this list's own slot expects,
+   * breaking assignability for every such field regardless of whether it
+   * uses `needs` at all. A misspelled or non-relation entry is instead
+   * caught by `pnpm generate` (`validateNeedsDeclarations`), which has no
+   * such constraint.
+   *
+   * @example
+   * ```typescript
+   * lineItems: relationship({ ref: 'LineItem.order', many: true }),
+   * total: virtual({
+   *   type: 'number',
+   *   needs: ['lineItems'],
+   *   hooks: {
+   *     resolveOutput: ({ item }) => item.lineItems.reduce((sum, li) => sum + li.price, 0),
+   *   },
+   * }),
+   * ```
+   */
+  needs?: string[]
 }
 
 /**
@@ -1045,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
@@ -1182,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.
@@ -1738,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
 /**
@@ -1815,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