@opensaas/stack-core 0.34.0 → 0.36.0

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/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[]
 }
 
 /**

package/src/context/index.ts

@@ -7,12 +7,14 @@ import {
   buildIncludeWithAccessControl,
   mergeIncludeWithAccessControl,
   stripVirtualFieldsFromInclude,
-  toPrismaInclude,
+  foldDeclaredDependencies,
 } from '../access/index.js'
+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 { getRelationshipOptions } from '../query/relationship-options.js'
 import {
   runWritePipeline,
@@ -911,6 +913,62 @@ export function buildDbDelegate<TPrisma extends PrismaClientLike>(
   return db as AccessControlledDB<TPrisma>
 }
 
+/**
+ * Resolve the `include` (and declared-dependency provenance) a read should
+ * use, preserving each existing path's exact shape — fragment / sudo /
+ * caller include / bare (ADR-0024) — while folding declared dependencies
+ * (`needs`, ADR-0025) into whichever of those the read is already using.
+ *
+ * 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`.
+ */
+async function resolveReadInclude(
+  callerInclude: Record<string, unknown> | undefined,
+  fragmentFields: FieldSelection<unknown> | undefined,
+  listName: string,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
+  listConfig: ListConfig<any>,
+  context: AccessContext & { _isSudo?: boolean },
+  config: OpenSaasConfig,
+): Promise<{ include: Record<string, unknown> | undefined; declaredOnly: DeclaredOnlyTree }> {
+  if (fragmentFields !== undefined) {
+    const fragmentInclude = buildInclude(fragmentFields) ?? undefined
+    return foldDeclaredDependencies(fragmentInclude, listConfig.fields, config)
+  }
+
+  if (context._isSudo) {
+    return foldDeclaredDependencies(callerInclude, listConfig.fields, config)
+  }
+
+  const folded = foldDeclaredDependencies(callerInclude, listConfig.fields, config)
+  if (!folded.include) {
+    return folded
+  }
+
+  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(
+    folded.include,
+    accessControlledInclude,
+    listConfig.fields,
+    config,
+    listName,
+  )
+  return { include, declaredOnly: folded.declaredOnly }
+}
+
 /**
  * Create findUnique operation with access control
  */
@@ -970,45 +1028,18 @@ function createFindUnique<TPrisma extends PrismaClientLike>(
     // instead of the access-controlled include. Access control still runs via
     // filterReadableFields; the fragment then narrows to only the requested fields.
     const fragment = isFragment(args.query) ? args.query : null
-    let include: Record<string, unknown> | undefined
 
-    if (fragment) {
-      include = buildInclude(fragment._fields) ?? undefined
-    } else if (context._isSudo) {
-      // Sudo bypasses access control entirely — the caller's include is trusted
-      // and used as-is (matching the prior behaviour); no per-relation filtering.
-      include = args.include
-    } else {
-      // Build include with access control filters
-      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],
-      )
-      // MERGE (not replace) a caller-supplied include with the access-controlled
-      // include: the caller selects WHICH relations to fetch, access control
-      // decides WHETHER and WITH WHAT filter (#566). A bare auto-include (no
-      // caller include) still uses the access-controlled include directly. A
-      // caller include naming a relation past the depth the engine can scope
-      // throws `AccessScopeDepthExceededError` (issue #830) rather than being
-      // returned unscoped.
-      include = args.include
-        ? mergeIncludeWithAccessControl(
-            args.include,
-            accessControlledInclude,
-            listConfig.fields,
-            config,
-            listName,
-          )
-        : toPrismaInclude(accessControlledInclude)
-    }
+    // 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(
+      args.include,
+      fragment ? fragment._fields : undefined,
+      listName,
+      listConfig,
+      context,
+      config,
+    )
 
     // Virtual fields have no database column. Whichever path produced
     // `include` (fragment, access-controlled merge, or sudo passthrough), a
@@ -1042,6 +1073,7 @@ function createFindUnique<TPrisma extends PrismaClientLike>(
       config,
       0,
       listName,
+      declaredOnly,
     )
 
     // When a fragment is provided, pick only the requested fields from the result
@@ -1109,44 +1141,18 @@ function createFindMany<TPrisma extends PrismaClientLike>(
 
     // When a query fragment is provided, build include from fragment fields
     const fragment = isFragment(args?.query) ? args.query : null
-    let include: Record<string, unknown> | undefined
-    if (fragment) {
-      include = buildInclude(fragment._fields) ?? undefined
-    } else if (context._isSudo) {
-      // Sudo bypasses access control entirely — the caller's include is trusted
-      // and used as-is (matching the prior behaviour); no per-relation filtering.
-      include = args?.include
-    } else {
-      // Build include with access control filters
-      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],
-      )
-      // MERGE (not replace) a caller-supplied include with the access-controlled
-      // include: the caller selects WHICH relations to fetch, access control
-      // decides WHETHER and WITH WHAT filter (#566). A bare auto-include (no
-      // caller include) still uses the access-controlled include directly. A
-      // caller include naming a relation past the depth the engine can scope
-      // throws `AccessScopeDepthExceededError` (issue #830) rather than being
-      // returned unscoped.
-      include = args?.include
-        ? mergeIncludeWithAccessControl(
-            args.include,
-            accessControlledInclude,
-            listConfig.fields,
-            config,
-            listName,
-          )
-        : toPrismaInclude(accessControlledInclude)
-    }
+
+    // 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(
+      args?.include,
+      fragment ? fragment._fields : undefined,
+      listName,
+      listConfig,
+      context,
+      config,
+    )
 
     // Virtual fields have no database column. Whichever path produced
     // `include` (fragment, access-controlled merge, or sudo passthrough), a
@@ -1181,6 +1187,7 @@ function createFindMany<TPrisma extends PrismaClientLike>(
           config,
           0,
           listName,
+          declaredOnly,
         ),
       ),
     )
@@ -1412,7 +1419,16 @@ function createGet<TPrisma extends PrismaClientLike>(
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   createFn: any,
 ) {
-  return async () => {
+  return async (args?: {
+    include?: Record<string, unknown>
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    query?: any
+    // `select` is not honoured — accepted only so the no-op can be made visible.
+    select?: Record<string, unknown>
+  }) => {
+    // `select` is a visible no-op: warn, then proceed with include/query narrowing.
+    warnIfSelectIgnored(args, listName, 'get')
+
     // First try to find the existing record
     // Access Prisma model dynamically - required because model names are generated at runtime
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -1437,24 +1453,30 @@ function createGet<TPrisma extends PrismaClientLike>(
       }
     }
 
-    // Build include with access control filters
-    const accessControlledInclude = await buildIncludeWithAccessControl(
-      listConfig.fields,
-      {
-        session: context.session,
-        context,
-      },
+    // When a query fragment is provided, build the include from the fragment
+    // instead of the access-controlled include. Access control still runs via
+    // filterReadableFields; the fragment then narrows to only the requested fields.
+    const fragment = isFragment(args?.query) ? args.query : null
+
+    // 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(
+      args?.include,
+      fragment ? fragment._fields : undefined,
+      listName,
+      listConfig,
+      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],
     )
 
+    // Virtual fields have no database column and must never reach Prisma (#628).
+    include = stripVirtualFieldsFromInclude(include, listConfig.fields, config)
+
     // Try to find the record
     const item = await model.findFirst({
       where,
-      include: toPrismaInclude(accessControlledInclude),
+      include,
     })
 
     // If record exists, return it
@@ -1470,7 +1492,12 @@ function createGet<TPrisma extends PrismaClientLike>(
         config,
         0,
         listName,
+        declaredOnly,
       )
+      // When a fragment is provided, pick only the requested fields from the result
+      if (fragment) {
+        return pickFields(filtered, fragment._fields)
+      }
       return filtered
     }
 

package/src/fields/index.ts

@@ -144,11 +144,11 @@ export function text<
         modifiers += ` @default(${defaultLiteral})`
       }
 
-      // Unique/index modifiers
+      // Unique modifier. A non-unique index has no field-level form in Prisma,
+      // so it is requested out-of-line via `index` below and emitted by the
+      // generator as `@@index([...])` on the model.
       if (options?.isIndexed === 'unique') {
         modifiers += ' @unique'
-      } else if (options?.isIndexed === true) {
-        modifiers += ' @index'
       }
 
       // Map modifier
@@ -159,6 +159,7 @@ export function text<
       return {
         type: 'String',
         modifiers: modifiers.trimStart() || undefined,
+        index: options?.isIndexed === true ? true : undefined,
       }
     },
     getTypeScriptType: () => {
@@ -402,16 +403,17 @@ export function decimal<
         modifiers += ` @map("${db.map}")`
       }
 
-      // Unique/index modifiers
+      // Unique modifier. A non-unique index has no field-level form in Prisma,
+      // so it is requested out-of-line via `index` below and emitted by the
+      // generator as `@@index([...])` on the model.
       if (options?.isIndexed === 'unique') {
         modifiers += ' @unique'
-      } else if (options?.isIndexed === true) {
-        modifiers += ' @index'
       }
 
       return {
         type: 'Decimal',
         modifiers: modifiers.trimStart() || undefined,
+        index: options?.isIndexed === true ? true : undefined,
       }
     },
     getTypeScriptType: () => {
@@ -747,16 +749,17 @@ export function calendarDay<
         modifiers += ` @map("${db.map}")`
       }
 
-      // Unique/index modifiers
+      // Unique modifier. A non-unique index has no field-level form in Prisma,
+      // so it is requested out-of-line via `index` below and emitted by the
+      // generator as `@@index([...])` on the model.
       if (options?.isIndexed === 'unique') {
         modifiers += ' @unique'
-      } else if (options?.isIndexed === true) {
-        modifiers += ' @index'
       }
 
       return {
         type: 'DateTime',
         modifiers: modifiers.trimStart() || undefined,
+        index: options?.isIndexed === true ? true : undefined,
       }
     },
     getTypeScriptType: () => {

package/src/index.ts

@@ -80,6 +80,14 @@ export { ResolveOutputCycleError } from './access/index.js'
 export { validateFieldConfig, validateConfigFields } from './validation/field-config.js'
 export type { FieldConfigValidationError } from './validation/field-config.js'
 
+// Declared-dependency validation (`needs`, ADR-0025) — checks every `needs`
+// entry names an immediate relationship field on the same list, and that no
+// field's declaration closure (the recursive fold of its dependencies, and
+// theirs) exceeds the read-include depth cap from any starting point. A
+// config that fails either must not generate.
+export { validateNeedsDeclarations, validateNeedsClosureDepth } from './validation/needs-closure.js'
+export type { NeedsClosureError } from './validation/needs-closure.js'
+
 // Fragment-based query API — composable, type-safe reads that mirror
 // Keystone's GraphQL fragments without a GraphQL runtime. The migration
 // guide, CHANGELOG, and migrate-context-calls skill all advertise importing

package/src/validation/needs-closure.ts

@@ -0,0 +1,188 @@
+import type { FieldConfig, OpenSaasConfig } from '../config/types.js'
+import { getRelatedListConfig } from '../access/engine.js'
+import { READ_INCLUDE_MAX_DEPTH } from '../access/depth-limits.js'
+
+/**
+ * A field's `needs` declaration (ADR-0025) whose closure — the recursive
+ * fold of its own dependencies, and THEIR dependencies, and so on — cannot
+ * be satisfied by the read pipeline, independent of where any caller starts
+ * a read.
+ *
+ * Two distinct refusals, both fail-closed rather than silently truncated
+ * (ADR-0022): `'cycle'` means the chain never terminates (e.g. `Order.total`
+ * needs `lineItems`, `LineItem.orderRef` needs `order`); `'depth'` means it
+ * terminates but reaches deeper than `READ_INCLUDE_MAX_DEPTH` even when
+ * evaluated starting AT the declaring field's own list — the most
+ * favourable starting point available, so no caller could ever do better.
+ */
+export interface NeedsClosureError {
+  /** The list whose field declares the (transitively) unsatisfiable `needs`. */
+  listKey: string
+  /** The field key within that list. */
+  fieldKey: string
+  /** The list keys on the offending chain, starting at `listKey`. */
+  chain: string[]
+  reason: 'cycle' | 'depth' | 'invalid-relation'
+  message: string
+}
+
+function isRelationshipFieldConfig(
+  fieldConfig: FieldConfig | undefined,
+): fieldConfig is FieldConfig & { type: 'relationship'; ref: string } {
+  return (
+    !!fieldConfig &&
+    fieldConfig.type === 'relationship' &&
+    'ref' in fieldConfig &&
+    !!fieldConfig.ref
+  )
+}
+
+type ListClosureResult = { depth: number; chain: string[] } | { cycle: string[] }
+
+/**
+ * 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: string,
+  config: OpenSaasConfig,
+  path: readonly string[],
+): ListClosureResult {
+  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: OpenSaasConfig): NeedsClosureError[] {
+  const errors: NeedsClosureError[] = []
+
+  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: OpenSaasConfig): NeedsClosureError[] {
+  const errors: NeedsClosureError[] = []
+
+  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
+}