json-rest-api 1.0.29 → 2.1.0

package/plugins/core/lib/querying/knex-relationship-includes.js

@@ -1,1804 +1,15 @@
-/**
- * Provides utilities for loading related resources according to JSON:API specification
- *
- * @description
- * This module implements the JSON:API include functionality, enabling compound documents
- * that contain both primary data and related resources. It handles all relationship types
- * and supports arbitrary nesting depths while preventing N+1 query problems.
- *
- * @example
- * // Input: Simple include request
- * // GET /articles?include=author
- * // Records before:
- * [
- *   { id: 1, title: 'Article 1', author_id: 10 },
- *   { id: 2, title: 'Article 2', author_id: 11 }
- * ]
- *
- * // Result: 2 queries total (articles + authors)
- * // Records after (with RELATIONSHIPS_KEY):
- * [
- *   {
- *     id: 1,
- *     title: 'Article 1',
- *     author_id: 10,
- *     __$jsonrestapi_rel$__: {
- *       author: { data: { type: 'users', id: '10' } }
- *     }
- *   }
- * ]
- * // Included resources:
- * [
- *   { type: 'users', id: '10', attributes: { name: 'John' } },
- *   { type: 'users', id: '11', attributes: { name: 'Jane' } }
- * ]
- *
- * @example
- * // Input: Nested includes
- * // GET /articles?include=comments.author
- * // Articles → Comments → Authors (3 queries total)
- *
- * // Result: Comments loaded with their authors
- * // Included array contains both comments AND their authors
- * // No duplicate authors even if multiple comments by same person
- *
- * @example
- * // Input: Polymorphic includes
- * // GET /activities?include=trackable
- * // Where trackable can be 'posts', 'photos', or 'videos'
- *
- * // Groups by type and loads each type separately:
- * // Query 1: SELECT * FROM posts WHERE id IN (1, 3, 5)
- * // Query 2: SELECT * FROM photos WHERE id IN (2, 4)
- * // Query 3: SELECT * FROM videos WHERE id IN (6)
- *
- * Used by:
- * - rest-api-knex-plugin calls buildIncludedResources in dataGet and dataQuery
- * - Called after primary records are fetched but before response assembly
- * - Results go into the 'included' section of JSON:API response
- *
- * Purpose:
- * - Implements JSON:API compound documents with primary data and included resources
- * - Prevents N+1 queries through batch loading (1 query per resource type)
- * - Supports deep nesting like article.author.company.country.continent
- * - Deduplicates resources automatically (each resource appears once)
- * - Handles circular references through processedPaths tracking
- * - Applies sparse fieldsets to reduce payload size
- *
- * Data flow:
- * 1. Parse include parameter into tree structure (author,comments.author)
- * 2. For each relationship, determine type (belongsTo, hasMany, polymorphic)
- * 3. Batch load all related records of same type in single query
- * 4. Recursively process nested includes
- * 5. Store all included resources in deduplication Map
- * 6. Return array of unique included resources
- */
-
-import { applyFieldSelectionToQuery, buildFieldSelection } from '../querying-writing/knex-field-helpers.js'
-import { toJsonApiRecord } from './knex-json-api-transformers-querying.js'
-import {
-  buildWindowedIncludeSubquery,
-  applyStandardIncludeConfig,
-  buildOrderByClause
-} from './knex-window-queries.js'
-import { unwrapQueryBuilderState } from './query-builder-utils.js'
-import { RELATIONSHIPS_KEY, RELATIONSHIP_METADATA_KEY, ROW_NUMBER_KEY, COMPUTED_DEPENDENCIES_KEY, DEFAULT_QUERY_LIMIT } from '../querying-writing/knex-constants.js'
-import { RestApiResourceError } from '../../../../lib/rest-api-errors.js'
-import { isRestApiError, wrapUnexpectedError } from '../../../../lib/error-context.js'
-import {
-  getFieldValue as getStorageFieldValue,
-  getIdColumn as getStorageIdColumn,
-  getStorageColumn as getMappedStorageColumn,
-} from '../storage/storage-mapping.js'
-import { createStorageAdapter } from '../storage/storage-adapter.js'
-
-const getScopeStorageAdapter = (scopes, scopeName) => scopes[scopeName]?.vars?.storageAdapter || null
-
-const resolveScopeStorageAdapter = (scopes, scopeName, knex) => {
-  const configuredAdapter = getScopeStorageAdapter(scopes, scopeName)
-  if (configuredAdapter) return configuredAdapter
-
-  const schemaInfo = scopes[scopeName]?.vars?.schemaInfo
-  if (!schemaInfo) return null
-
-  return createStorageAdapter({ knex, schemaInfo })
-}
-
-const getIdColumnForScope = (scopes, scopeName) => {
-  const adapter = getScopeStorageAdapter(scopes, scopeName)
-  if (adapter?.getIdColumn) {
-    return adapter.getIdColumn()
-  }
-
-  return getStorageIdColumn(scopes[scopeName]?.vars?.schemaInfo || {})
-}
-
-const getFieldValueForScope = (scopes, scopeName, record, fieldName) => {
-  const adapter = getScopeStorageAdapter(scopes, scopeName)
-  if (adapter?.getFieldValue) {
-    return adapter.getFieldValue(record, fieldName)
-  }
-
-  return getStorageFieldValue(record, scopes[scopeName]?.vars?.schemaInfo || {}, fieldName)
-}
-
-const translateColumnForScope = (scopes, scopeName, fieldName) => {
-  const adapter = getScopeStorageAdapter(scopes, scopeName)
-  if (adapter?.translateColumn) {
-    return adapter.translateColumn(fieldName)
-  }
-
-  return getMappedStorageColumn(scopes[scopeName]?.vars?.schemaInfo || {}, fieldName)
-}
-
-const buildRelationshipLinks = (scopes, scopeName, record, relationshipName) => {
-  const urlPrefix = scopes[scopeName]?.vars?.returnBasePath || scopes[scopeName]?.vars?.mountPath || ''
-  const recordId = getFieldValueForScope(scopes, scopeName, record, 'id')
-
-  return {
-    self: `${urlPrefix}/${scopeName}/${recordId}/relationships/${relationshipName}`,
-    related: `${urlPrefix}/${scopeName}/${recordId}/${relationshipName}`
-  }
-}
-
-const buildScopedIncludeContext = ({ requestContext, scopeName, scopeObject, storageAdapter }) => {
-  const queryParams = requestContext?.queryParams
-    ? { ...requestContext.queryParams }
-    : {}
-
-  if ('filters' in queryParams) {
-    delete queryParams.filters
-  }
-
-  return {
-    ...(requestContext || {}),
-    scopeName,
-    schemaInfo: scopeObject.vars.schemaInfo,
-    storageAdapter,
-    queryParams
-  }
-}
-
-const applyScopeFiltersToIncludeQuery = async ({
-  query,
-  scopes,
-  scopeName,
-  requestContext,
-  db,
-  tableName,
-  queryPurpose = 'include'
-}) => {
-  const scopeObject = scopes[scopeName]
-  if (!scopeObject?.applyQueryFilters) {
-    return { query }
-  }
-
-  const storageAdapter = resolveScopeStorageAdapter(scopes, scopeName, db)
-
-  const queryState = await scopeObject.applyQueryFilters({
-    query,
-    filters: undefined,
-    scopeName,
-    tableName: tableName || scopeObject.vars.schemaInfo.tableName,
-    db,
-    schemaInfo: scopeObject.vars.schemaInfo,
-    queryPurpose,
-    storageAdapter
-  }, buildScopedIncludeContext({
-    requestContext,
-    scopeName,
-    scopeObject,
-    storageAdapter
-  }))
-
-  return {
-    query: unwrapQueryBuilderState(queryState, query)
-  }
-}
-
-/**
- * Groups records by their polymorphic type for efficient batch loading
- *
- * @param {Array<Object>} records - Records containing polymorphic fields
- * @param {string} typeField - Name of the type field (e.g., 'commentable_type')
- * @param {string} idField - Name of the ID field (e.g., 'commentable_id')
- * @returns {Object<string, Array<number|string>>} Map of type to array of unique IDs
- *
- * @example
- * // Input: Comments with polymorphic commentable relationship
- * const records = [
- *   { id: 1, commentable_type: 'articles', commentable_id: 10 },
- *   { id: 2, commentable_type: 'videos', commentable_id: 20 },
- *   { id: 3, commentable_type: 'articles', commentable_id: 11 },
- *   { id: 4, commentable_type: 'articles', commentable_id: 10 }  // Duplicate
- * ];
- *
- * const grouped = groupByPolymorphicType(records, 'commentable_type', 'commentable_id');
- *
- * // Output: IDs grouped by type, duplicates removed
- * // {
- * //   articles: [10, 11],  // Only unique IDs
- * //   videos: [20]
- * // }
- *
- * @example
- * // Input: Some records have null relationships
- * const records = [
- *   { id: 1, item_type: 'products', item_id: 1 },
- *   { id: 2, item_type: null, item_id: null },      // Ignored
- *   { id: 3, item_type: 'products', item_id: null }, // Ignored
- *   { id: 4, item_type: 'categories', item_id: 5 }
- * ];
- *
- * const grouped = groupByPolymorphicType(records, 'item_type', 'item_id');
- *
- * // Output: Only records with both type AND id
- * // {
- * //   products: [1],
- * //   categories: [5]
- * // }
- *
- * @description
- * Used by:
- * - loadPolymorphicBelongsTo uses this to group records before batch loading
- * - Enables efficient loading with one query per type instead of per record
- *
- * Purpose:
- * - Minimizes database queries when loading polymorphic relationships
- * - Instead of N queries (one per record), makes T queries (one per type)
- * - Automatically deduplicates IDs within each type
- * - Safely handles null/undefined values by filtering them out
- *
- * Data flow:
- * 1. Receives array of records with polymorphic fields
- * 2. Groups records by their type field value
- * 3. Collects unique IDs for each type
- * 4. Returns map used for batch WHERE IN queries
- */
-export const groupByPolymorphicType = (records, typeField, idField, getFieldValue = (record, fieldName) => record[fieldName]) => {
-  const grouped = {}
-
-  records.forEach(record => {
-    const type = getFieldValue(record, typeField)
-    const id = getFieldValue(record, idField)
-
-    // Skip if either type or id is missing
-    if (!type || !id) return
-
-    if (!grouped[type]) {
-      grouped[type] = []
-    }
-
-    // Only add unique IDs
-    if (!grouped[type].includes(id)) {
-      grouped[type].push(id)
-    }
-  })
-
-  return grouped
-}
-
-/**
- * Parses the include parameter string into a tree structure
- *
- * @param {string|Array<string>} includeParam - The include parameter value
- * @returns {Object} Nested object representing the include tree
- *
- * @example
- * // Input: Simple comma-separated includes
- * const tree = parseIncludeTree('author,comments');
- *
- * // Output: Flat structure
- * // {
- * //   author: {},
- * //   comments: {}
- * // }
- *
- * @example
- * // Input: Nested includes with dot notation
- * const tree = parseIncludeTree('comments.author,comments.replies');
- *
- * // Output: Nested structure
- * // {
- * //   comments: {
- * //     author: {},
- * //     replies: {}
- * //   }
- * // }
- *
- * @example
- * // Input: Complex mixed-depth includes
- * const tree = parseIncludeTree('author,comments.author,comments.replies.author,tags');
- *
- * // Output: Multi-level nesting
- * // {
- * //   author: {},
- * //   comments: {
- * //     author: {},
- * //     replies: {
- * //       author: {}
- * //     }
- * //   },
- * //   tags: {}
- * // }
- *
- * @description
- * Used by:
- * - buildIncludedResources parses the include parameter before processing
- * - processIncludes traverses this tree structure recursively
- *
- * Purpose:
- * - Converts flat string format into hierarchical structure for processing
- * - Enables recursive traversal of relationship includes
- * - Handles both string and pre-split array inputs
- * - Empty values are filtered out automatically
- *
- * Data flow:
- * 1. Split comma-separated string into individual paths
- * 2. For each path, split by dots to get nesting levels
- * 3. Build nested object structure following the path
- * 4. Return tree for recursive processing
- */
-export const parseIncludeTree = (includeParam) => {
-  if (!includeParam) return {}
-
-  // Handle array input (already split)
-  const includes = Array.isArray(includeParam)
-    ? includeParam
-    : includeParam.split(',').map(s => s.trim()).filter(Boolean)
-
-  const tree = {}
-
-  includes.forEach(include => {
-    const parts = include.split('.')
-    let current = tree
-
-    parts.forEach(part => {
-      if (!current[part]) {
-        current[part] = {}
-      }
-      current = current[part]
-    })
-  })
-
-  return tree
-}
-
-/**
- * Loads relationship metadata for included resources
- * This ensures included resources have complete JSON:API representation
- *
- * @param {Object} scopes - The hooked-api scopes object
- * @param {Array<Object>} records - Records to add relationships to
- * @param {string} scopeName - The scope/resource type name
- */
-const loadRelationshipMetadata = async (scopes, records, scopeName) => {
-  try {
-    // Get schema information
-    const schemaInfo = scopes[scopeName]?.vars?.schemaInfo
-    if (!schemaInfo) return
-
-    const schema = schemaInfo.schemaInstance.structure || schemaInfo.schemaInstance
-    const relationships = schemaInfo.schemaRelationships || {}
-
-    // Process each record
-    records.forEach(record => {
-      record[RELATIONSHIP_METADATA_KEY] = {}
-
-      // Process belongsTo relationships from schema
-      for (const [fieldName, fieldDef] of Object.entries(schema)) {
-        if (fieldDef.belongsTo && fieldDef.as) {
-          const foreignKeyValue = getFieldValueForScope(scopes, scopeName, record, fieldName)
-          if (foreignKeyValue != null) {
-            record[RELATIONSHIP_METADATA_KEY][fieldDef.as] = {
-              data: {
-                type: fieldDef.belongsTo,
-                id: String(foreignKeyValue)
-              }
-            }
-          } else {
-            record[RELATIONSHIP_METADATA_KEY][fieldDef.as] = { data: null }
-          }
-        }
-      }
-
-      // Process hasMany, hasOne and manyToMany relationships
-      for (const [relName, relDef] of Object.entries(relationships)) {
-        if (relDef.type === 'hasMany' || relDef.type === 'manyToMany') {
-          // Add empty relationship data - will be populated if explicitly included
-          record[RELATIONSHIP_METADATA_KEY][relName] = { data: [] }
-        } else if (relDef.type === 'hasOne') {
-          // hasOne expects a single object or null
-          record[RELATIONSHIP_METADATA_KEY][relName] = { data: null }
-        } else if (relDef.belongsToPolymorphic) {
-          // Process polymorphic relationships defined in relationships section
-          const { typeField, idField } = relDef.belongsToPolymorphic
-          const type = getFieldValueForScope(scopes, scopeName, record, typeField)
-          const id = getFieldValueForScope(scopes, scopeName, record, idField)
-
-          if (type && id) {
-            record[RELATIONSHIP_METADATA_KEY][relName] = {
-              data: { type, id: String(id) }
-            }
-          } else {
-            record[RELATIONSHIP_METADATA_KEY][relName] = { data: null }
-          }
-        }
-      }
-    })
-  } catch (error) {
-    if (isRestApiError(error)) throw error
-
-    const errorContext = {
-      scopeName,
-      recordCount: records?.length || 0,
-      error: error.message
-    }
-    console.error('[loadRelationshipMetadata] Error loading relationship metadata:', errorContext)
-    throw wrapUnexpectedError(error, {
-      message: `Failed to load relationship metadata for scope '${scopeName}'`,
-      context: errorContext
-    })
-  }
-}
-
-/**
- * Loads belongsTo relationships (many-to-one)
- *
- * This function loads the "parent" side of a relationship. For example, if comments
- * belong to articles, this loads the articles for a set of comments.
- *
- * @param {Object} scope - The hooked-api scope object containing:
- *   - records: Array<Object> - Records to load relationships for
- *   - fieldName: string - The foreign key field name (e.g., 'author_id')
- *   - fieldDef: Object - The field definition from the schema
- *   - includeName: string - The relationship name (e.g., 'author')
- *   - subIncludes: Object - Nested includes to process recursively
- *   - included: Map - Map of already included resources
- *   - processedPaths: Set - Set of already processed paths
- *   - currentPath: string - Current include path for tracking
- *   - fields: Object - Sparse fieldsets configuration
- * @param {Object} deps - Dependencies object containing:
- *   - context.scopes: Object - The hooked-api scopes object
- *   - context.log: Object - Logger instance
- *   - context.knex: Object - Knex instance
- * @returns {Promise<void>}
- */
-export const loadBelongsTo = async (scope, deps) => {
-  const { records, scopeName, fieldName, fieldDef, includeName, subIncludes, included, processedPaths, currentPath, fields } = scope
-  const { scopes, log, knex, capabilities, requestContext } = deps.context
-  try {
-    log.trace('[INCLUDE] Loading belongsTo:', {
-      fieldName,
-      includeName,
-      recordCount: records.length
-    })
-
-    // Get the target scope name
-    const targetScope = fieldDef.belongsTo
-    if (!scopes[targetScope]) {
-      log.warn('[INCLUDE] Target scope not found:', targetScope)
-      return
-    }
-
-    // Collect all foreign key values
-    const foreignKeyValues = records
-      .map(record => getFieldValueForScope(scopes, scopeName, record, fieldName))
-      .filter(val => val != null) // Filter out null/undefined
-
-    const uniqueIds = [...new Set(foreignKeyValues)]
-
-    log.debug('[INCLUDE] Loading belongsTo records:', {
-      targetScope,
-      uniqueIds
-    })
-
-    if (uniqueIds.length === 0) {
-      // No relationships to load, set all to null
-      records.forEach(record => {
-        if (!record[RELATIONSHIPS_KEY]) record[RELATIONSHIPS_KEY] = {}
-        const relationshipObject = { data: null }
-
-        // Add links if urlPrefix is configured
-        if (scopeName) {
-          relationshipObject.links = buildRelationshipLinks(scopes, scopeName, record, includeName)
-        }
-
-        record[RELATIONSHIPS_KEY][includeName] = relationshipObject
-      })
-      return
-    }
-
-    // Get target table info
-    const targetTableName = scopes[targetScope].vars.schemaInfo.tableName
-    const targetIdColumn = getIdColumnForScope(scopes, targetScope)
-    // Build field selection for sparse fieldsets
-    const targetScopeObject = scopes[targetScope]
-    const storageAdapter = resolveScopeStorageAdapter(scopes, targetScope, knex)
-    const fieldSelectionInfo = fields?.[targetScope]
-      ? await buildFieldSelection(targetScopeObject, {
-        context: {
-          ...(requestContext || {}),
-          scopeName: targetScope,
-          queryParams: { fields: { [targetScope]: fields[targetScope] } },
-          schemaInfo: targetScopeObject.vars.schemaInfo,
-          storageAdapter,
-        }
-      })
-      : null
-
-    // Load the target records
-    let query = knex(targetTableName).whereIn(targetIdColumn, uniqueIds)
-    if (fieldSelectionInfo) {
-      const selectionState = await applyFieldSelectionToQuery({
-        query,
-        scope: targetScopeObject,
-        fieldSelectionInfo,
-        tableName: targetTableName,
-        useTablePrefix: false,
-        storageAdapter,
-        db: knex,
-        context: {
-          ...(requestContext || {}),
-          scopeName: targetScope,
-          schemaInfo: targetScopeObject.vars.schemaInfo,
-          storageAdapter,
-        },
-        scopeName: targetScope
-      })
-      query = selectionState.query
-    } else if (targetIdColumn !== 'id') {
-      // If no field selection but the storage ID column is not `id`, alias it for response shaping.
-      query = query.select('*', `${targetIdColumn} as id`)
-    }
-    const scopedQueryState = await applyScopeFiltersToIncludeQuery({
-      query,
-      scopes,
-      scopeName: targetScope,
-      requestContext,
-      db: knex,
-      tableName: targetTableName
-    })
-    query = scopedQueryState.query
-    const targetRecords = await query
-
-    // Load relationship metadata for all target records
-    await loadRelationshipMetadata(scopes, targetRecords, targetScope)
-
-    // Create lookup map
-    const targetById = {}
-    targetRecords.forEach(record => {
-      targetById[getFieldValueForScope(scopes, targetScope, record, 'id')] = record
-    })
-
-    // Set relationships on original records
-    const targetRecordsToProcess = []
-
-    records.forEach(record => {
-      if (!record[RELATIONSHIPS_KEY]) record[RELATIONSHIPS_KEY] = {}
-
-      const targetId = getFieldValueForScope(scopes, scopeName, record, fieldName)
-      const targetRecord = targetById[targetId]
-
-      if (targetRecord) {
-        // Convert to JSON:API format
-        const jsonApiRecord = toJsonApiRecord(
-          scopes[targetScope],
-          targetRecord,
-          targetScope
-        )
-
-        // Add relationships from metadata
-        if (targetRecord[RELATIONSHIP_METADATA_KEY]) {
-          jsonApiRecord.relationships = targetRecord[RELATIONSHIP_METADATA_KEY]
-          // Clean up the temporary property
-          delete targetRecord[RELATIONSHIP_METADATA_KEY]
-        }
-
-        // Attach computed dependencies info if sparse fieldsets were used
-        if (fieldSelectionInfo?.computedDependencies) {
-          jsonApiRecord[COMPUTED_DEPENDENCIES_KEY] = fieldSelectionInfo.computedDependencies
-        }
-
-        const relationshipObject = { data: { type: targetScope, id: String(targetId) } }
-
-        // Add links if urlPrefix is configured
-        if (scopeName) {
-          relationshipObject.links = buildRelationshipLinks(scopes, scopeName, record, includeName)
-        }
-
-        record[RELATIONSHIPS_KEY][includeName] = relationshipObject
-
-        // Add to included if not already there
-        const resourceKey = `${targetScope}:${targetId}`
-        if (!included.has(resourceKey)) {
-          included.set(resourceKey, jsonApiRecord) // Now includes relationships!
-
-          // Collect for nested processing
-          if (Object.keys(subIncludes).length > 0) {
-            targetRecordsToProcess.push(targetRecord)
-          }
-        }
-      } else {
-        const relationshipObject = { data: null }
-
-        // Add links if urlPrefix is configured
-        if (scopeName) {
-          relationshipObject.links = buildRelationshipLinks(scopes, scopeName, record, includeName)
-        }
-
-        record[RELATIONSHIPS_KEY][includeName] = relationshipObject
-      }
-    })
-
-    // Process nested includes if any
-    if (targetRecordsToProcess.length > 0) {
-      const nextPath = `${currentPath}.${includeName}`
-      if (!processedPaths.has(nextPath)) {
-        await processIncludes(
-          { records: targetRecordsToProcess, scopeName: targetScope, includeTree: subIncludes, included, processedPaths, currentPath: nextPath, fields },
-          { context: { scopes, log, knex, capabilities, requestContext } }
-        )
-      }
-    }
-  } catch (error) {
-    if (isRestApiError(error)) throw error
-
-    // Log error with detailed context
-    log.error('[INCLUDE] Error loading belongsTo relationship:', {
-      fieldName,
-      includeName,
-      targetScope: fieldDef.belongsTo,
-      recordCount: records?.length || 0,
-      error: error.message,
-      stack: error.stack
-    })
-
-    throw wrapUnexpectedError(error, {
-      message: `Failed to load belongsTo relationship '${includeName}' for field '${fieldName}'`,
-      context: { fieldName, includeName, targetScope: fieldDef.belongsTo }
-    })
-  }
-}
-
-/**
- * Loads hasMany relationships (one-to-many or many-to-many)
- *
- * This function loads the "child" side of a relationship. For example, if articles
- * have many comments, this loads all comments for a set of articles. It also handles
- * many-to-many relationships through a pivot table.
- *
- * @param {Object} scope - The hooked-api scope object containing:
- *   - records: Array<Object> - Parent records to load relationships for
- *   - scopeName: string - The parent scope name
- *   - includeName: string - The relationship name to include
- *   - relDef: Object - The relationship definition
- *   - subIncludes: Object - Nested includes to process recursively
- *   - included: Map - Map of already included resources
- *   - processedPaths: Set - Set of already processed paths
- *   - currentPath: string - Current include path for tracking
- *   - fields: Object - Sparse fieldsets configuration
- * @param {Object} deps - Dependencies object containing:
- *   - context.scopes: Object - The hooked-api scopes object
- *   - context.log: Object - Logger instance
- *   - context.knex: Object - Knex instance
- * @returns {Promise<void>}
- */
-export const loadHasMany = async (scope, deps) => {
-  const { records, scopeName, includeName, relDef, subIncludes, included, processedPaths, currentPath, fields } = scope
-  const { scopes, log, knex, capabilities, requestContext } = deps.context
-  try {
-    log.trace('[INCLUDE] Loading hasMany/manyToMany relationship:', {
-      scopeName,
-      includeName,
-      recordCount: records.length,
-      relDef,
-      isManyToMany: relDef.type === 'manyToMany',
-      hasMany: relDef.type === 'hasMany' ? relDef.target : undefined
-    })
-
-    // Collect all parent IDs
-    const mainIds = records.map(record => getFieldValueForScope(scopes, scopeName, record, 'id')).filter(Boolean)
-
-    if (mainIds.length === 0) {
-      log.trace('[INCLUDE] No parent IDs found, skipping hasMany load')
-      return
-    }
-
-    // Check if this is a many-to-many relationship
-    if (relDef.type === 'manyToMany') {
-    // Handle many-to-many relationship
-      const pivotTable = scopes[relDef.through].vars.schemaInfo.tableName
-      const foreignKey = relDef.foreignKey
-      const otherKey = relDef.otherKey
-
-      if (!foreignKey || !otherKey) {
-        throw new Error(`Missing foreignKey or otherKey in many-to-many relationship '${includeName}' for scope '${scopeName}'`)
-      }
-
-      // For manyToMany, the target scope is the relationship name itself
-      const targetScope = includeName
-      const targetTable = scopes[targetScope].vars.schemaInfo.tableName
-
-      log.debug(`[INCLUDE] Loading pivot records from ${pivotTable}:`, {
-        foreignKey,
-        whereIn: mainIds
-      })
-
-      // Step 1: Query the pivot table
-      const pivotRecords = await knex(pivotTable)
-        .whereIn(foreignKey, mainIds)
-        .orderBy(otherKey)
-
-      if (pivotRecords.length === 0) {
-      // No relationships found, set empty arrays for all records
-        records.forEach(record => {
-          if (!record[RELATIONSHIPS_KEY]) record[RELATIONSHIPS_KEY] = {}
-          const relationshipObject = { data: [] }
-
-          // Add links if urlPrefix is configured
-          if (scopeName) {
-            relationshipObject.links = buildRelationshipLinks(scopes, scopeName, record, includeName)
-          }
-
-          record[RELATIONSHIPS_KEY][includeName] = relationshipObject
-        })
-        return
-      }
-
-      // Step 2: Extract target IDs from pivot records
-      const targetIds = [...new Set(pivotRecords.map(p => p[otherKey]).filter(Boolean))]
-
-      log.debug(`[INCLUDE] Loading ${targetScope} records:`, {
-        whereIn: targetIds,
-        includeConfig: relDef.include
-      })
-
-      // Step 3: Build field selection for sparse fieldsets
-      const targetScopeObject = scopes[targetScope]
-      const storageAdapter = resolveScopeStorageAdapter(scopes, targetScope, knex)
-      const targetIdColumn = getIdColumnForScope(scopes, targetScope)
-      const fieldSelectionInfo = fields?.[targetScope]
-        ? await buildFieldSelection(targetScopeObject, {
-          context: {
-            ...(requestContext || {}),
-            scopeName: targetScope,
-            queryParams: { fields: { [targetScope]: fields[targetScope] } },
-            schemaInfo: targetScopeObject.vars.schemaInfo,
-            storageAdapter,
-          }
-        })
-        : null
-
-      // Step 4: For many-to-many with limits, we need a different approach
-      let targetRecords
-
-      if (relDef.include?.strategy === 'window' && !fieldSelectionInfo?.queryFieldsToSelect?.length) {
-      // For many-to-many with window functions, we need to limit per parent
-      // This requires joining back through the pivot table
-
-        // Get target scope vars for defaults
-        const targetVars = scopes[targetScope].vars || {}
-
-        // Calculate effective limit with defaults
-        const effectiveLimit = relDef.include?.limit ?? targetVars.queryDefaultLimit ?? DEFAULT_QUERY_LIMIT
-
-        // Validate against max
-        if (targetVars.queryMaxLimit && effectiveLimit > targetVars.queryMaxLimit) {
-          throw new RestApiResourceError({
-            title: 'Include Limit Exceeds Maximum',
-            detail: `Requested include limit (${effectiveLimit}) exceeds queryMaxLimit (${targetVars.queryMaxLimit})`,
-            status: 400
-          })
-        }
-
-        let windowQuery = knex
-          .select(`${targetTable}.*`)
-
-        // Add id alias if needed
-        if (targetIdColumn !== 'id') {
-          windowQuery.select(`${targetTable}.${targetIdColumn} as id`)
-        }
-
-        windowQuery.select(
-          knex.raw(
-            'ROW_NUMBER() OVER (PARTITION BY pivot.?? ORDER BY ' +
-            buildOrderByClause(relDef.include?.orderBy || [targetIdColumn], targetTable) +
-            ') as ' + ROW_NUMBER_KEY,
-            [foreignKey]
-          )
-        )
-          .from(targetTable)
-          .join(`${pivotTable} as pivot`, `${targetTable}.${targetIdColumn}`, 'pivot.' + otherKey)
-          .whereIn(`pivot.${foreignKey}`, mainIds)
-
-        const scopedWindowQueryState = await applyScopeFiltersToIncludeQuery({
-          query: windowQuery,
-          scopes,
-          scopeName: targetScope,
-          requestContext,
-          db: knex,
-          tableName: targetTable
-        })
-        windowQuery = scopedWindowQueryState.query
-
-        // Wrap to filter by row number
-        const limitedQuery = knex
-          .select('*')
-          .from(windowQuery.as('_windowed'))
-          .where(ROW_NUMBER_KEY, '<=', effectiveLimit)
-
-        targetRecords = await limitedQuery
-
-        // Remove row number column and restore proper pivot grouping
-        targetRecords.forEach(record => delete record[ROW_NUMBER_KEY])
-      } else {
-      // Standard query without per-parent limits
-        let query = knex(targetTable).whereIn(targetIdColumn, targetIds)
-
-        if (fieldSelectionInfo) {
-          const selectionState = await applyFieldSelectionToQuery({
-            query,
-            scope: targetScopeObject,
-            fieldSelectionInfo,
-            tableName: targetTable,
-            useTablePrefix: false,
-            storageAdapter,
-            db: knex,
-            context: {
-              ...(requestContext || {}),
-              scopeName: targetScope,
-              schemaInfo: targetScopeObject.vars.schemaInfo,
-              storageAdapter,
-            },
-            scopeName: targetScope
-          })
-          query = selectionState.query
-        } else if (targetIdColumn !== 'id') {
-        // If no field selection but the storage ID column is not `id`, alias it for response shaping.
-          query = query.select('*', `${targetIdColumn} as id`)
-        }
-
-        const scopedQueryState = await applyScopeFiltersToIncludeQuery({
-          query,
-          scopes,
-          scopeName: targetScope,
-          requestContext,
-          db: knex,
-          tableName: targetTable
-        })
-        query = scopedQueryState.query
-
-        // Apply standard include config (global limits)
-        if (relDef.include) {
-          const targetVars = scopes[targetScope].vars
-          query = applyStandardIncludeConfig(query, relDef.include, targetVars, log)
-        }
-
-        targetRecords = await query
-      }
-
-      log.trace('[INCLUDE] Loaded target records:', { count: targetRecords.length })
-
-      // Step 5: Load relationship metadata for all target records
-      await loadRelationshipMetadata(scopes, targetRecords, targetScope)
-
-      // Step 6: Create lookup map for target records
-      const targetById = {}
-      targetRecords.forEach(record => {
-        targetById[getFieldValueForScope(scopes, targetScope, record, 'id')] = record
-      })
-
-      // Step 7: Group pivot records by parent ID
-      const pivotsByParent = {}
-      pivotRecords.forEach(pivot => {
-        const parentId = pivot[foreignKey]
-        if (!pivotsByParent[parentId]) {
-          pivotsByParent[parentId] = []
-        }
-        pivotsByParent[parentId].push(pivot[otherKey])
-      })
-
-      // Step 7: Set relationships on parent records
-
-      records.forEach(record => {
-        if (!record[RELATIONSHIPS_KEY]) record[RELATIONSHIPS_KEY] = {}
-
-        const recordId = getFieldValueForScope(scopes, scopeName, record, 'id')
-        const childIds = pivotsByParent[recordId] || []
-
-        const relData = childIds
-          .map(childId => targetById[childId])
-          .filter(Boolean)
-          .map(childRecord => {
-          // Add to included
-            const childRecordId = getFieldValueForScope(scopes, targetScope, childRecord, 'id')
-            const resourceKey = `${targetScope}:${childRecordId}`
-            if (!included.has(resourceKey)) {
-              const jsonApiRecord = toJsonApiRecord(
-                scopes[targetScope],
-                childRecord,
-                targetScope
-              )
-
-              // Add relationships from metadata
-              if (childRecord[RELATIONSHIP_METADATA_KEY]) {
-                jsonApiRecord.relationships = childRecord[RELATIONSHIP_METADATA_KEY]
-                // Clean up the temporary property
-                delete childRecord[RELATIONSHIP_METADATA_KEY]
-              }
-
-              // Attach computed dependencies info if sparse fieldsets were used
-              if (fieldSelectionInfo?.computedDependencies) {
-                jsonApiRecord[COMPUTED_DEPENDENCIES_KEY] = fieldSelectionInfo.computedDependencies
-              }
-
-              included.set(resourceKey, jsonApiRecord)
-            }
-            return { type: targetScope, id: String(childRecordId) }
-          })
-
-        const relationshipObject = { data: relData }
-
-        // Add links if urlPrefix is configured
-        if (scopeName) {
-          relationshipObject.links = buildRelationshipLinks(scopes, scopeName, record, includeName)
-        }
-
-        record[RELATIONSHIPS_KEY][includeName] = relationshipObject
-
-        // Update the record in the included Map if it exists
-        const recordKey = `${scopeName}:${recordId}`
-        if (included.has(recordKey)) {
-          const existingRecord = included.get(recordKey)
-          if (!existingRecord.relationships) {
-            existingRecord.relationships = {}
-          }
-          existingRecord.relationships[includeName] = relationshipObject
-        }
-      })
-
-      // Step 8: Process nested includes if any
-      if (Object.keys(subIncludes).length > 0 && targetRecords.length > 0) {
-        const nextPath = `${currentPath}.${includeName}`
-        if (!processedPaths.has(nextPath)) {
-          await processIncludes(
-            { records: targetRecords, scopeName: targetScope, includeTree: subIncludes, included, processedPaths, currentPath: nextPath, fields },
-            { context: { scopes, log, knex, capabilities, requestContext } }
-          )
-        }
-      }
-    } else if (relDef.type === 'hasMany') {
-    // Handle one-to-many relationship
-      const targetScope = relDef.target
-      const targetTable = scopes[targetScope].vars.schemaInfo.tableName
-      const foreignKey = relDef.foreignKey
-
-      if (!foreignKey) {
-        throw new Error(`Missing foreignKey in hasMany relationship '${includeName}' for scope '${scopeName}'`)
-      }
-
-      log.debug(`[INCLUDE] Loading ${targetScope} records with foreign key ${foreignKey}:`, {
-        whereIn: mainIds,
-        includeConfig: relDef.include
-      })
-
-      // Build field selection for sparse fieldsets
-      const targetScopeObject = scopes[targetScope]
-      const storageAdapter = resolveScopeStorageAdapter(scopes, targetScope, knex)
-      const fieldSelectionInfo = fields?.[targetScope]
-        ? await buildFieldSelection(targetScopeObject, {
-          context: {
-            scopeName: targetScope,
-            queryParams: { fields: { [targetScope]: fields[targetScope] } },
-            schemaInfo: targetScopeObject.vars.schemaInfo,
-            storageAdapter,
-          }
-        })
-        : null
-
-      let query
-      let usingWindowFunction = false
-
-      // Check if we should use window functions
-      if (relDef.include?.strategy === 'window') {
-        let windowedQuery
-
-        if (fieldSelectionInfo?.queryFieldsToSelect?.length) {
-          log.debug('[INCLUDE] Query projection fields require the standard include query path')
-        } else {
-          windowedQuery = buildWindowedIncludeSubquery(
-            knex,
-            targetTable,
-            foreignKey,
-            mainIds,
-            fieldSelectionInfo?.fieldsToSelect || null,
-            relDef.include || {},
-            capabilities,
-            targetScopeObject.vars
-          )
-        }
-
-        if (windowedQuery) {
-          const scopedQueryState = await applyScopeFiltersToIncludeQuery({
-            query: windowedQuery.subquery,
-            scopes,
-            scopeName: targetScope,
-            requestContext,
-            db: knex,
-            tableName: targetTable
-          })
-          query = knex
-            .select('*')
-            .from(scopedQueryState.query.as('_windowed'))
-            .where(ROW_NUMBER_KEY, '<=', windowedQuery.effectiveLimit)
-          usingWindowFunction = true
-          log.debug('[INCLUDE] Using window function strategy with limits')
-        }
-      }
-
-      // Build standard query if not using window functions
-      if (!usingWindowFunction) {
-        const foreignKeyColumn = translateColumnForScope(scopes, targetScope, foreignKey)
-        query = knex(targetTable).whereIn(foreignKeyColumn, mainIds)
-
-        if (fieldSelectionInfo) {
-          const selectionState = await applyFieldSelectionToQuery({
-            query,
-            scope: targetScopeObject,
-            fieldSelectionInfo,
-            tableName: targetTable,
-            useTablePrefix: false,
-            storageAdapter,
-            db: knex,
-            context: {
-              ...(requestContext || {}),
-              scopeName: targetScope,
-              schemaInfo: targetScopeObject.vars.schemaInfo,
-              storageAdapter,
-            },
-            scopeName: targetScope
-          })
-          query = selectionState.query
-        }
-
-        const scopedQueryState = await applyScopeFiltersToIncludeQuery({
-          query,
-          scopes,
-          scopeName: targetScope,
-          requestContext,
-          db: knex,
-          tableName: targetTable
-        })
-        query = scopedQueryState.query
-
-        // Apply standard config with defaults
-        const targetVars = scopes[targetScope].vars
-        query = applyStandardIncludeConfig(
-          query,
-          relDef.include || {},
-          targetVars,
-          log
-        )
-      }
-
-      // Execute query
-      const targetRecords = await query
-
-      // If using window functions, remove the row number column
-      if (usingWindowFunction) {
-        targetRecords.forEach(record => delete record[ROW_NUMBER_KEY])
-      }
-
-      log.trace('[INCLUDE] Loaded hasMany records:', {
-        count: targetRecords.length,
-        usingWindowFunction
-      })
-
-      // Load relationship metadata for all target records
-      await loadRelationshipMetadata(scopes, targetRecords, targetScope)
-
-      // Group by parent ID
-      const childrenByParent = {}
-      targetRecords.forEach(record => {
-        const parentId = getFieldValueForScope(scopes, targetScope, record, foreignKey)
-        if (!childrenByParent[parentId]) {
-          childrenByParent[parentId] = []
-        }
-        childrenByParent[parentId].push(record)
-      })
-
-      // Set relationships on parent records
-      records.forEach(record => {
-        if (!record[RELATIONSHIPS_KEY]) record[RELATIONSHIPS_KEY] = {}
-
-        const recordId = getFieldValueForScope(scopes, scopeName, record, 'id')
-        const children = childrenByParent[recordId] || []
-        const relData = children.map(childRecord => {
-        // Add to included
-          const childRecordId = getFieldValueForScope(scopes, targetScope, childRecord, 'id')
-          const resourceKey = `${targetScope}:${childRecordId}`
-          if (!included.has(resourceKey)) {
-            const jsonApiRecord = toJsonApiRecord(
-              scopes[targetScope],
-              childRecord,
-              targetScope
-            )
-
-            // Add relationships from metadata
-            if (childRecord[RELATIONSHIP_METADATA_KEY]) {
-              jsonApiRecord.relationships = childRecord[RELATIONSHIP_METADATA_KEY]
-              // Clean up the temporary property
-              delete childRecord[RELATIONSHIP_METADATA_KEY]
-            }
-
-            // Attach computed dependencies info if sparse fieldsets were used
-            if (fieldSelectionInfo?.computedDependencies) {
-              jsonApiRecord[COMPUTED_DEPENDENCIES_KEY] = fieldSelectionInfo.computedDependencies
-            }
-
-            included.set(resourceKey, jsonApiRecord)
-          }
-          return { type: targetScope, id: String(childRecordId) }
-        })
-
-        const relationshipObject = { data: relData }
-
-        // Add links if urlPrefix is configured
-        if (scopeName) {
-          relationshipObject.links = buildRelationshipLinks(scopes, scopeName, record, includeName)
-        }
-
-        record[RELATIONSHIPS_KEY][includeName] = relationshipObject
-
-        // Update the record in the included Map if it exists
-        const recordKey = `${scopeName}:${recordId}`
-        if (included.has(recordKey)) {
-          const existingRecord = included.get(recordKey)
-          if (!existingRecord.relationships) {
-            existingRecord.relationships = {}
-          }
-          existingRecord.relationships[includeName] = relationshipObject
-        }
-      })
-
-      // Process nested includes
-      if (Object.keys(subIncludes).length > 0 && targetRecords.length > 0) {
-        const nextPath = `${currentPath}.${includeName}`
-        if (!processedPaths.has(nextPath)) {
-          await processIncludes(
-            { records: targetRecords, scopeName: targetScope, includeTree: subIncludes, included, processedPaths, currentPath: nextPath, fields },
-            { context: { scopes, log, knex, capabilities, requestContext } }
-          )
-        }
-      }
-    }
-  } catch (error) {
-    if (isRestApiError(error)) throw error
-
-    // Log error with detailed context
-    log.error('[INCLUDE] Error loading hasMany relationship:', {
-      scopeName,
-      includeName,
-      hasThrough: !!relDef.through,
-      recordCount: records?.length || 0,
-      error: error.message,
-      stack: error.stack
-    })
-
-    throw wrapUnexpectedError(error, {
-      message: `Failed to load hasMany relationship '${includeName}' for scope '${scopeName}'`,
-      context: { scopeName, includeName, hasThrough: !!relDef.through }
-    })
-  }
-}
-
-/**
- * Loads hasOne relationships (one-to-one)
- *
- * Similar to hasMany but expects a single related record.
- * For example, a user that has one profile.
- *
- * @param {Object} scope - The hooked-api scope object
- * @param {Object} deps - Dependencies object
- */
-export const loadHasOne = async (scope, deps) => {
-  const { records, scopeName, includeName, relDef, subIncludes, included, processedPaths, currentPath, fields } = scope
-  const { context: { scopes, log, knex, capabilities, requestContext } } = deps
-
-  const childLog = log?.child ? log.child({ method: 'loadHasOne' }) : console
-
-  if (!records || records.length === 0) {
-    childLog.trace('[INCLUDE] No records to load hasOne for')
-    return
-  }
-
-  // Get parent IDs
-  const mainIds = [...new Set(records.map(record => getFieldValueForScope(scopes, scopeName, record, 'id')).filter(Boolean))]
-
-  if (mainIds.length === 0) {
-    childLog.trace('[INCLUDE] No parent IDs found, skipping hasOne load')
-    return
-  }
-
-  const targetScope = relDef.target
-  const targetTable = scopes[targetScope].vars.schemaInfo.tableName
-  const foreignKey = relDef.foreignKey
-
-  if (!foreignKey) {
-    throw new Error(`Missing foreignKey in hasOne relationship '${includeName}' for scope '${scopeName}'`)
-  }
-
-  childLog.debug(`[INCLUDE] Loading ${targetScope} records with foreign key ${foreignKey}:`, {
-    whereIn: mainIds
-  })
-
-  // Build query for hasOne - expects single result per parent
-  const targetScopeObject = scopes[targetScope]
-  const storageAdapter = resolveScopeStorageAdapter(scopes, targetScope, knex)
-
-  // Build field selection for sparse fieldsets
-  const fieldSelectionInfo = fields?.[targetScope]
-    ? await buildFieldSelection(targetScopeObject, {
-      context: {
-        ...(requestContext || {}),
-        scopeName: targetScope,
-        queryParams: { fields: { [targetScope]: fields[targetScope] } },
-        schemaInfo: targetScopeObject.vars.schemaInfo,
-        storageAdapter,
-      }
-    })
-    : null
-
-  // Query related records
-  const foreignKeyColumn = translateColumnForScope(scopes, targetScope, foreignKey)
-  let query = knex(targetTable).whereIn(foreignKeyColumn, mainIds)
-
-  if (fieldSelectionInfo) {
-    const selectionState = await applyFieldSelectionToQuery({
-      query,
-      scope: targetScopeObject,
-      fieldSelectionInfo,
-      tableName: targetTable,
-      useTablePrefix: false,
-      storageAdapter,
-      db: knex,
-      context: {
-        ...(requestContext || {}),
-        scopeName: targetScope,
-        schemaInfo: targetScopeObject.vars.schemaInfo,
-        storageAdapter,
-      },
-      scopeName: targetScope
-    })
-    query = selectionState.query
-  }
-
-  const scopedQueryState = await applyScopeFiltersToIncludeQuery({
-    query,
-    scopes,
-    scopeName: targetScope,
-    requestContext,
-    db: knex,
-    tableName: targetTable
-  })
-  query = scopedQueryState.query
-
-  const relatedRecords = await query
-
-  // Create a map of parent ID to related record (should be one-to-one)
-  const relatedByParentId = {}
-  for (const related of relatedRecords) {
-    const parentId = getFieldValueForScope(scopes, targetScope, related, foreignKey)
-    if (relatedByParentId[parentId]) {
-      log.warn(`[INCLUDE] Multiple records found for hasOne relationship '${includeName}' with ${foreignKey}=${parentId}`)
-    }
-    relatedByParentId[parentId] = related
-  }
-
-  // Process each parent record
-  for (const record of records) {
-    const recordId = getFieldValueForScope(scopes, scopeName, record, 'id')
-    const relatedRecord = relatedByParentId[recordId]
-
-    if (!record[RELATIONSHIPS_KEY]) record[RELATIONSHIPS_KEY] = {}
-
-    if (relatedRecord) {
-      // Transform to JSON:API format
-      const transformed = await toJsonApiRecord(
-        targetScopeObject,
-        {
-          context: {
-            record: relatedRecord,
-            scopeName: targetScope,
-            schemaInfo: targetScopeObject.vars.schemaInfo
-          }
-        }
-      )
-
-      // Set single object (not array) for hasOne
-      const relatedRecordId = getFieldValueForScope(scopes, targetScope, relatedRecord, 'id')
-      record[RELATIONSHIPS_KEY][includeName] = {
-        data: { type: targetScope, id: String(relatedRecordId) }
-      }
-
-      // Add to included if not already there
-      const key = `${targetScope}:${relatedRecordId}`
-      if (!included.has(key)) {
-        included.set(key, transformed)
-      }
-
-      // Process nested includes if any
-      if (subIncludes && Object.keys(subIncludes).length > 0) {
-        const newPath = `${currentPath}.${includeName}`
-        if (!processedPaths.has(newPath)) {
-          processedPaths.add(newPath)
-          await processIncludes(
-            { records: [relatedRecord], scopeName: targetScope, includeTree: subIncludes, included, processedPaths, currentPath: newPath, fields },
-            { context: { scopes, log, knex, capabilities, requestContext } }
-          )
-        }
-      }
-    } else {
-      // No related record found
-      record[RELATIONSHIPS_KEY][includeName] = { data: null }
-    }
-  }
-}
-
-/**
- * Loads polymorphic belongsTo relationships
- *
- * Handles relationships where a record can belong to different types of parent records.
- * For example, comments that can belong to either articles or videos.
- *
- * @param {Object} scope - The hooked-api scope object containing:
- *   - records: Array<Object> - Records with polymorphic relationships
- *   - relName: string - The relationship name
- *   - relDef: Object - The relationship definition with belongsToPolymorphic
- *   - subIncludes: Object - Nested includes to process recursively
- *   - included: Map - Map of already included resources
- *   - processedPaths: Set - Set of already processed paths
- *   - currentPath: string - Current include path for tracking
- *   - fields: Object - Sparse fieldsets configuration
- * @param {Object} deps - Dependencies object containing:
- *   - context.scopes: Object - The hooked-api scopes object
- *   - context.log: Object - Logger instance
- *   - context.knex: Object - Knex instance
- * @returns {Promise<void>}
- */
-export const loadPolymorphicBelongsTo = async (scope, deps) => {
-  const { records, scopeName, relName, relDef, subIncludes, included, processedPaths, currentPath, fields } = scope
-  const { scopes, log, knex, capabilities, requestContext } = deps.context
-  try {
-    log.trace('[INCLUDE] Loading polymorphic belongsTo:', {
-      relName,
-      recordCount: records.length
-    })
-
-    const { typeField, idField, types } = relDef.belongsToPolymorphic
-
-    // Group records by their target type using helper
-    const grouped = groupByPolymorphicType(
-      records,
-      typeField,
-      idField,
-      (record, fieldName) => getFieldValueForScope(scopes, scopeName, record, fieldName)
-    )
-
-    log.trace('[INCLUDE] Grouped by type:', {
-      types: Object.keys(grouped),
-      counts: Object.entries(grouped).map(([t, ids]) => `${t}: ${ids.length}`)
-    })
-
-    // Load each type separately
-    for (const [targetType, targetIds] of Object.entries(grouped)) {
-    // Skip if type not allowed (shouldn't happen with validation, but be safe)
-      if (!types.includes(targetType)) {
-        log.warn('[INCLUDE] Skipping non-allowed type:', targetType)
-        continue
-      }
-
-      if (targetIds.length === 0) continue
-
-      // Get target table information
-      const targetSchemaInfo = scopes[targetType].vars.schemaInfo
-      const targetTable = targetSchemaInfo?.tableName || targetType
-
-      // Build field selection for sparse fieldsets
-      const targetScopeObject = scopes[targetType]
-      const storageAdapter = resolveScopeStorageAdapter(scopes, targetType, knex)
-      const fieldSelectionInfo = fields?.[targetType]
-        ? await buildFieldSelection(targetScopeObject, {
-          context: {
-            ...(requestContext || {}),
-            scopeName: targetType,
-            queryParams: { fields: { [targetType]: fields[targetType] } },
-            schemaInfo: targetScopeObject.vars.schemaInfo,
-            storageAdapter,
-          }
-        })
-        : null
-
-      log.debug(`[INCLUDE] Loading ${targetType} records:`, {
-        ids: targetIds,
-        fields: fieldSelectionInfo ? fieldSelectionInfo.fieldsToSelect : '*'
-      })
-
-      // Query for this type
-      const targetIdColumn = getIdColumnForScope(scopes, targetType)
-      let query = knex(targetTable).whereIn(targetIdColumn, targetIds)
-      if (fieldSelectionInfo) {
-        const selectionState = await applyFieldSelectionToQuery({
-          query,
-          scope: targetScopeObject,
-          fieldSelectionInfo,
-          tableName: targetTable,
-          useTablePrefix: false,
-          storageAdapter,
-          db: knex,
-          context: {
-            ...(requestContext || {}),
-            scopeName: targetType,
-            schemaInfo: targetScopeObject.vars.schemaInfo,
-            storageAdapter,
-          },
-          scopeName: targetType
-        })
-        query = selectionState.query
-      } else if (targetIdColumn !== 'id') {
-      // If no field selection but the storage ID column is not `id`, alias it for response shaping.
-        query = query.select('*', `${targetIdColumn} as id`)
-      }
-      const scopedQueryState = await applyScopeFiltersToIncludeQuery({
-        query,
-        scopes,
-        scopeName: targetType,
-        requestContext,
-        db: knex,
-        tableName: targetTable
-      })
-      query = scopedQueryState.query
-      const targetRecords = await query
-
-      // Load relationship metadata for all target records
-      await loadRelationshipMetadata(scopes, targetRecords, targetType)
-
-      // Create lookup map
-      const targetById = {}
-      targetRecords.forEach(record => {
-        targetById[getFieldValueForScope(scopes, targetType, record, 'id')] = record
-      })
-
-      // Add to included and set relationships
-      records.forEach(record => {
-        if (getFieldValueForScope(scopes, scopeName, record, typeField) === targetType) {
-          const targetId = getFieldValueForScope(scopes, scopeName, record, idField)
-          const targetRecord = targetById[targetId]
-
-          if (!record[RELATIONSHIPS_KEY]) record[RELATIONSHIPS_KEY] = {}
-
-          if (targetRecord) {
-          // Add to included
-            const resourceKey = `${targetType}:${targetId}`
-            if (!included.has(resourceKey)) {
-              const jsonApiRecord = toJsonApiRecord(
-                scopes[targetType],
-                targetRecord,
-                targetType
-              )
-
-              // Add relationships from metadata
-              if (targetRecord[RELATIONSHIP_METADATA_KEY]) {
-                jsonApiRecord.relationships = targetRecord[RELATIONSHIP_METADATA_KEY]
-                // Clean up the temporary property
-                delete targetRecord[RELATIONSHIP_METADATA_KEY]
-              }
-
-              // Attach computed dependencies info if sparse fieldsets were used
-              if (fieldSelectionInfo?.computedDependencies) {
-                jsonApiRecord[COMPUTED_DEPENDENCIES_KEY] = fieldSelectionInfo.computedDependencies
-              }
-
-              included.set(resourceKey, jsonApiRecord)
-            }
-
-            const relationshipObject = {
-              data: { type: targetType, id: String(targetId) }
-            }
-
-            // Add links if urlPrefix is configured
-            if (scopeName) {
-              relationshipObject.links = buildRelationshipLinks(scopes, scopeName, record, relName)
-            }
-
-            record[RELATIONSHIPS_KEY][relName] = relationshipObject
-          } else {
-            const relationshipObject = { data: null }
-
-            // Add links if urlPrefix is configured
-            if (scopeName) {
-              relationshipObject.links = buildRelationshipLinks(scopes, scopeName, record, relName)
-            }
-
-            record[RELATIONSHIPS_KEY][relName] = relationshipObject
-          }
-        }
-      })
-
-      // Process nested includes for this type
-      if (Object.keys(subIncludes).length > 0 && targetRecords.length > 0) {
-        const nextPath = `${currentPath}.${relName}`
-        if (!processedPaths.has(nextPath)) {
-          await processIncludes(
-            { records: targetRecords, scopeName: targetType, includeTree: subIncludes, included, processedPaths, currentPath: nextPath, fields },
-            { context: { scopes, log, knex, capabilities, requestContext } }
-          )
-        }
-      }
-    }
-
-    // Set null for records without relationships
-    records.forEach(record => {
-      if (!record[RELATIONSHIPS_KEY]) record[RELATIONSHIPS_KEY] = {}
-      if (!record[RELATIONSHIPS_KEY][relName]) {
-        const relationshipObject = { data: null }
-
-        // Add links if urlPrefix is configured
-        if (scopeName) {
-          relationshipObject.links = buildRelationshipLinks(scopes, scopeName, record, relName)
-        }
-
-        record[RELATIONSHIPS_KEY][relName] = relationshipObject
-      }
-    })
-  } catch (error) {
-    if (isRestApiError(error)) throw error
-
-    // Log error with detailed context
-    log.error('[INCLUDE] Error loading polymorphic belongsTo relationship:', {
-      relName,
-      recordCount: records?.length || 0,
-      types: relDef?.belongsToPolymorphic?.types,
-      error: error.message,
-      stack: error.stack
-    })
-
-    throw wrapUnexpectedError(error, {
-      message: `Failed to load polymorphic belongsTo relationship '${relName}'`,
-      context: { relName, types: relDef?.belongsToPolymorphic?.types }
-    })
-  }
-}
-
-/**
- * Loads reverse polymorphic relationships (via)
- *
- * Handles loading "child" records that have a polymorphic relationship back to the parent.
- * For example, loading all comments (which can belong to articles or videos) for a specific article.
- *
- * @param {Object} scope - The hooked-api scope object containing:
- *   - records: Array<Object> - Parent records
- *   - scopeName: string - The parent scope name
- *   - includeName: string - The relationship name
- *   - relDef: Object - The relationship definition with 'via' property
- *   - subIncludes: Object - Nested includes to process recursively
- *   - included: Map - Map of already included resources
- *   - processedPaths: Set - Set of already processed paths
- *   - currentPath: string - Current include path for tracking
- *   - fields: Object - Sparse fieldsets configuration
- * @param {Object} deps - Dependencies object containing:
- *   - context.scopes: Object - The hooked-api scopes object
- *   - context.log: Object - Logger instance
- *   - context.knex: Object - Knex instance
- * @returns {Promise<void>}
- */
-export const loadReversePolymorphic = async (scope, deps) => {
-  const { records, scopeName, includeName, relDef, subIncludes, included, processedPaths, currentPath, fields } = scope
-  const { scopes, log, knex, capabilities, requestContext } = deps.context
-  try {
-    log.trace('[INCLUDE] Loading reverse polymorphic (via):', {
-      scopeName,
-      includeName,
-      via: relDef.via,
-      recordCount: records.length
-    })
-
-    const targetScope = relDef.target
-    const viaRelName = relDef.via
-
-    // Get the polymorphic field info from target scope
-    const targetRelationships = scopes[targetScope].vars.schemaInfo.schemaRelationships
-    const viaRel = targetRelationships?.[viaRelName]
-
-    if (!viaRel?.belongsToPolymorphic) {
-      log.warn('[INCLUDE] Via relationship not found or not polymorphic:', {
-        targetScope,
-        viaRelName
-      })
-      return
-    }
-
-    const { typeField, idField } = viaRel.belongsToPolymorphic
-    const targetTable = scopes[targetScope].vars.schemaInfo.tableName
-
-    // Collect parent IDs
-    const parentIds = records.map(record => getFieldValueForScope(scopes, scopeName, record, 'id')).filter(Boolean)
-    if (parentIds.length === 0) return
-
-    log.debug(`[INCLUDE] Loading ${targetScope} records via ${viaRelName}:`, {
-      typeField,
-      idField,
-      scopeName,
-      parentIds
-    })
-
-    // Build field selection for sparse fieldsets
-    const targetScopeObject = scopes[targetScope]
-    const storageAdapter = resolveScopeStorageAdapter(scopes, targetScope, knex)
-    const targetIdColumn = getIdColumnForScope(scopes, targetScope)
-    const fieldSelectionInfo = fields?.[targetScope]
-      ? await buildFieldSelection(targetScopeObject, {
-        context: {
-          ...(requestContext || {}),
-          scopeName: targetScope,
-          queryParams: { fields: { [targetScope]: fields[targetScope] } },
-          schemaInfo: targetScopeObject.vars.schemaInfo,
-          storageAdapter,
-        }
-      })
-      : null
-
-    // Query for records pointing back to our scope
-    const typeColumn = translateColumnForScope(scopes, targetScope, typeField)
-    const idColumn = translateColumnForScope(scopes, targetScope, idField)
-    let query = knex(targetTable)
-      .where(typeColumn, scopeName)
-      .whereIn(idColumn, parentIds)
-
-    if (fieldSelectionInfo) {
-      const selectionState = await applyFieldSelectionToQuery({
-        query,
-        scope: targetScopeObject,
-        fieldSelectionInfo,
-        tableName: targetTable,
-        useTablePrefix: false,
-        storageAdapter,
-        db: knex,
-        context: {
-          ...(requestContext || {}),
-          scopeName: targetScope,
-          schemaInfo: targetScopeObject.vars.schemaInfo,
-          storageAdapter,
-        },
-        scopeName: targetScope
-      })
-      query = selectionState.query
-    } else if (targetIdColumn !== 'id') {
-    // If no field selection but the storage ID column is not `id`, alias it for response shaping.
-      query = query.select('*', `${targetIdColumn} as id`)
-    }
-
-    const scopedQueryState = await applyScopeFiltersToIncludeQuery({
-      query,
-      scopes,
-      scopeName: targetScope,
-      requestContext,
-      db: knex,
-      tableName: targetTable
-    })
-    query = scopedQueryState.query
-
-    // Apply include configuration (limits, ordering, etc.)
-    const targetVars = scopes[targetScope].vars
-    query = applyStandardIncludeConfig(
-      query,
-      relDef.include || {},
-      targetVars,
-      log
-    )
-
-    const targetRecords = await query
-
-    log.trace('[INCLUDE] Loaded reverse polymorphic records:', {
-      count: targetRecords.length
-    })
-
-    // Load relationship metadata for all target records
-    await loadRelationshipMetadata(scopes, targetRecords, targetScope)
-
-    // Group by parent ID
-    const childrenByParent = {}
-    targetRecords.forEach(record => {
-      const parentId = getFieldValueForScope(scopes, targetScope, record, idField)
-      if (!childrenByParent[parentId]) {
-        childrenByParent[parentId] = []
-      }
-      childrenByParent[parentId].push(record)
-    })
-
-    // Set relationships on parent records
-    records.forEach(record => {
-      if (!record[RELATIONSHIPS_KEY]) record[RELATIONSHIPS_KEY] = {}
-
-      const recordId = getFieldValueForScope(scopes, scopeName, record, 'id')
-      const children = childrenByParent[recordId] || []
-      const relData = children.map(childRecord => {
-      // Add to included
-        const childRecordId = getFieldValueForScope(scopes, targetScope, childRecord, 'id')
-        const resourceKey = `${targetScope}:${childRecordId}`
-        if (!included.has(resourceKey)) {
-          const jsonApiRecord = toJsonApiRecord(
-            scopes[targetScope],
-            childRecord,
-            targetScope
-          )
-
-          // Add relationships from metadata
-          if (childRecord[RELATIONSHIP_METADATA_KEY]) {
-            jsonApiRecord.relationships = childRecord[RELATIONSHIP_METADATA_KEY]
-            // Clean up the temporary property
-            delete childRecord[RELATIONSHIP_METADATA_KEY]
-          }
-
-          // Attach computed dependencies info if sparse fieldsets were used
-          if (fieldSelectionInfo?.computedDependencies) {
-            jsonApiRecord[COMPUTED_DEPENDENCIES_KEY] = fieldSelectionInfo.computedDependencies
-          }
-
-          included.set(resourceKey, jsonApiRecord)
-        }
-        return { type: targetScope, id: String(childRecordId) }
-      })
-
-      const relationshipObject = { data: relData }
-
-      // Add links if urlPrefix is configured
-      if (scopeName) {
-        relationshipObject.links = buildRelationshipLinks(scopes, scopeName, record, includeName)
-      }
-
-      record[RELATIONSHIPS_KEY][includeName] = relationshipObject
-    })
-
-    // Process nested includes
-    if (Object.keys(subIncludes).length > 0 && targetRecords.length > 0) {
-      const nextPath = `${currentPath}.${includeName}`
-      if (!processedPaths.has(nextPath)) {
-        await processIncludes(
-          { records: targetRecords, scopeName: targetScope, includeTree: subIncludes, included, processedPaths, currentPath: nextPath, fields },
-          { context: { scopes, log, knex, capabilities, requestContext } }
-        )
-      }
-    }
-  } catch (error) {
-    if (isRestApiError(error)) throw error
-
-    // Log error with detailed context
-    log.error('[INCLUDE] Error loading reverse polymorphic relationship:', {
-      scopeName,
-      includeName,
-      via: relDef?.via,
-      targetScope: relDef?.target,
-      recordCount: records?.length || 0,
-      error: error.message,
-      stack: error.stack
-    })
-
-    throw wrapUnexpectedError(error, {
-      message: `Failed to load reverse polymorphic relationship '${includeName}' via '${relDef?.via}' for scope '${scopeName}'`,
-      context: { scopeName, includeName, via: relDef?.via, targetScope: relDef?.target }
-    })
-  }
-}
-
+import { RELATIONSHIPS_KEY } from '../querying-writing/knex-constants.js'
+import { getOperationDiagnosticContext, wrapUnexpectedError } from '../../../../lib/error-context.js'
+import { getFieldValueForScope, parseIncludeTree } from './include-query-helpers.js'
+import { loadBelongsTo, loadHasOne, loadPolymorphicBelongsTo } from './include-to-one.js'
+import { loadHasMany, loadReversePolymorphic } from './include-to-many.js'
 /**
  * Processes includes for a set of records
  *
  * This is the main recursive function that processes the include tree. It examines
  * the schema to determine relationship types and calls the appropriate loader function.
  *
- * @param {Object} scope - The hooked-api scope object containing:
+ * @param {Object} scope - The resource object containing:
  *   - records: Array<Object> - Records to process includes for
  *   - scopeName: string - The scope name of the records
  *   - includeTree: Object - Parsed include tree from parseIncludeTree
@@ -1807,7 +18,7 @@ export const loadReversePolymorphic = async (scope, deps) => {
  *   - currentPath: string - Current path in the include tree (default '')
  *   - fields: Object - Sparse fieldsets configuration (default {})
  * @param {Object} deps - Dependencies object containing:
- *   - context.scopes: Object - The hooked-api scopes object
+ *   - context.scopes: Object - The resources object
  *   - context.log: Object - Logger instance
  *   - context.knex: Object - Knex instance
  * @returns {Promise<void>}
@@ -1815,135 +26,126 @@ export const loadReversePolymorphic = async (scope, deps) => {
 export const processIncludes = async (scope, deps) => {
   const { records, scopeName, includeTree, included, processedPaths, currentPath = '', fields = {} } = scope
   const { scopes, log, knex, capabilities, requestContext } = deps.context
-  try {
-    log.trace('[INCLUDE] Processing includes:', {
-      scopeName,
-      includes: Object.keys(includeTree),
-      recordCount: records.length,
-      currentPath
-    })
-
-    if (records.length === 0) return
-
-    // Get schema info for this scope
-    const schemaInfo = scopes[scopeName]?.vars?.schemaInfo
-    if (!schemaInfo) {
-      log.warn('[INCLUDE] No schema info for scope:', scopeName)
-      return
-    }
+  log.trace('[INCLUDE] Processing includes:', {
+    scopeName,
+    includes: Object.keys(includeTree),
+    recordCount: records.length,
+    currentPath
+  })
 
-    const { schemaInstance, schemaRelationships } = schemaInfo
+  if (records.length === 0) return
 
-    // Process each include
-    for (const [includeName, subIncludes] of Object.entries(includeTree)) {
-      const fullPath = currentPath ? `${currentPath}.${includeName}` : includeName
+  // Get schema info for this scope
+  const schemaInfo = scopes[scopeName]?.vars?.schemaInfo
+  if (!schemaInfo) {
+    throw new Error(`Missing relationship schema for scope '${scopeName}'`)
+  }
 
-      // Skip if already processed (prevents infinite loops)
-      if (processedPaths.has(fullPath)) {
-        log.trace('[INCLUDE] Skipping already processed path:', fullPath)
-        continue
-      }
-      processedPaths.add(fullPath)
+  const { schemaStructure, schemaRelationships } = schemaInfo
 
-      // Check if it's a schema field (belongsTo)
-      let handled = false
+  // Process each include
+  for (const [includeName, subIncludes] of Object.entries(includeTree)) {
+    const fullPath = currentPath ? `${currentPath}.${includeName}` : includeName
 
-      try {
-        // Look for belongsTo relationships in schema fields
-        for (const [fieldName, fieldDef] of Object.entries(schemaInstance.structure || {})) {
-          if (fieldDef.as === includeName && fieldDef.belongsTo) {
-            await loadBelongsTo(
-              { records, scopeName, fieldName, fieldDef, includeName, subIncludes, included, processedPaths, currentPath, fields },
-              { context: { scopes, log, knex, capabilities, requestContext } }
+    // A path can be reached by different parent records or polymorphic types.
+    const recordsToProcess = records.filter(record => {
+      const recordId = getFieldValueForScope(scopes, scopeName, record, 'id')
+      const key = JSON.stringify([scopeName, String(recordId), fullPath])
+      if (processedPaths.has(key)) return false
+      processedPaths.add(key)
+      return true
+    })
+    if (recordsToProcess.length === 0) continue
+
+    // Check if it's a schema field (belongsTo)
+    let handled = false
+
+    try {
+      // Look for belongsTo relationships in schema fields
+      for (const [fieldName, fieldDef] of Object.entries(schemaStructure || {})) {
+        if (fieldDef.as === includeName && fieldDef.belongsTo) {
+          await loadBelongsTo(
+            { records: recordsToProcess, scopeName, fieldName, fieldDef, includeName, subIncludes, included, processedPaths, currentPath, fields },
+            { context: { scopes, log, knex, capabilities, requestContext }, loadNestedIncludes: processIncludes }
+          )
+          handled = true
+          break
+        }
+      }
+
+      // Check relationships
+      if (!handled && schemaRelationships) {
+        const relDef = schemaRelationships[includeName]
+
+        if (relDef) {
+          if (relDef.type === 'hasOne') {
+            // Handle hasOne relationship
+            log.debug('[INCLUDE] About to call loadHasOne:', {
+              scopeName,
+              includeName,
+              target: relDef.target
+            })
+            await loadHasOne(
+              { records: recordsToProcess, scopeName, includeName, relDef, subIncludes, included, processedPaths, currentPath, fields },
+              { context: { scopes, log, knex, capabilities, requestContext }, loadNestedIncludes: processIncludes }
             )
             handled = true
-            break
-          }
-        }
-
-        // Check relationships
-        if (!handled && schemaRelationships) {
-          const relDef = schemaRelationships[includeName]
-
-          if (relDef) {
-            if (relDef.type === 'hasOne') {
-              // Handle hasOne relationship
-              log.debug('[INCLUDE] About to call loadHasOne:', {
+          } else if (relDef.type === 'hasMany' || relDef.type === 'manyToMany') {
+            // Check if it's a reverse polymorphic (via)
+            if (relDef.via) {
+              await loadReversePolymorphic(
+                { records: recordsToProcess, scopeName, includeName, relDef, subIncludes, included, processedPaths, currentPath, fields },
+                { context: { scopes, log, knex, capabilities, requestContext }, loadNestedIncludes: processIncludes }
+              )
+            } else {
+              log.debug('[INCLUDE] About to call loadHasMany:', {
                 scopeName,
                 includeName,
-                target: relDef.target
+                relDefKeys: Object.keys(relDef || {}),
+                hasManyToMany: relDef.type === 'manyToMany',
+                hasMany: relDef.type === 'hasMany' ? relDef.target : undefined
               })
-              await loadHasOne(
-                { records, scopeName, includeName, relDef, subIncludes, included, processedPaths, currentPath, fields },
-                { context: { scopes, log, knex, capabilities, requestContext } }
+              await loadHasMany(
+                { records: recordsToProcess, scopeName, includeName, relDef, subIncludes, included, processedPaths, currentPath, fields },
+                { context: { scopes, log, knex, capabilities, requestContext }, loadNestedIncludes: processIncludes }
               )
-              handled = true
-            } else if (relDef.type === 'hasMany' || relDef.type === 'manyToMany') {
-              // Check if it's a reverse polymorphic (via)
-              if (relDef.via) {
-                await loadReversePolymorphic(
-                  { records, scopeName, includeName, relDef, subIncludes, included, processedPaths, currentPath, fields },
-                  { context: { scopes, log, knex, capabilities, requestContext } }
-                )
-              } else {
-                log.debug('[INCLUDE] About to call loadHasMany:', {
-                  scopeName,
-                  includeName,
-                  relDefKeys: Object.keys(relDef || {}),
-                  hasManyToMany: relDef.type === 'manyToMany',
-                  hasMany: relDef.type === 'hasMany' ? relDef.target : undefined
-                })
-                await loadHasMany(
-                  { records, scopeName, includeName, relDef, subIncludes, included, processedPaths, currentPath, fields },
-                  { context: { scopes, log, knex, capabilities, requestContext } }
-                )
-              }
-              handled = true
-            } else if (relDef.belongsToPolymorphic) {
-              await loadPolymorphicBelongsTo(
-                { records, scopeName, relName: includeName, relDef, subIncludes, included, processedPaths, currentPath, fields },
-                { context: { scopes, log, knex, capabilities, requestContext } }
-              )
-              handled = true
             }
+            handled = true
+          } else if (relDef.belongsToPolymorphic) {
+            await loadPolymorphicBelongsTo(
+              { records: recordsToProcess, scopeName, relName: includeName, relDef, subIncludes, included, processedPaths, currentPath, fields },
+              { context: { scopes, log, knex, capabilities, requestContext }, loadNestedIncludes: processIncludes }
+            )
+            handled = true
           }
         }
-      } catch (includeError) {
-        if (isRestApiError(includeError)) throw includeError
-
-        // Log specific include error and continue with other includes
-        log.error('[INCLUDE] Error processing include:', {
-          scopeName,
-          includeName,
-          fullPath,
-          error: includeError.message
-        })
-        // Re-throw to maintain existing behavior
-        throw includeError
       }
+    } catch (includeError) {
+      throw wrapUnexpectedError(includeError, {
+        message: `Failed to load include '${fullPath}' for scope '${scopeName}'`,
+        context: { phase: 'include', scopeName, includeName, fullPath }
+      })
+    }
 
-      if (!handled) {
-        log.warn('[INCLUDE] Unknown relationship:', {
-          scopeName,
+    if (!handled) {
+      try {
+        await log.warn('[INCLUDE] Unknown relationship:', {
+          ...getOperationDiagnosticContext(requestContext || {}, { phase: 'include', scopeName, backend: knex.client?.config?.client }),
           includeName,
-          availableFields: Object.keys(schemaInstance.structure || {}).filter(k => schemaInstance.structure[k].as),
+          availableFields: Object.keys(schemaStructure || {}).filter(k => schemaStructure[k].as),
           availableRelationships: Object.keys(schemaRelationships || {})
         })
+      } catch { /* Diagnostics must preserve the unknown-relationship decision. */ }
+    }
+    for (const record of recordsToProcess) {
+      const recordId = getFieldValueForScope(scopes, scopeName, record, 'id')
+      const includedRecord = included.get(`${scopeName}:${recordId}`)
+      const relationship = record[RELATIONSHIPS_KEY]?.[includeName]
+      if (includedRecord && relationship) {
+        includedRecord.relationships ||= {}
+        includedRecord.relationships[includeName] = relationship
       }
     }
-  } catch (error) {
-    if (isRestApiError(error)) throw error
-
-    // Log error with full context
-    log.error('[INCLUDE] Error in processIncludes:', {
-      scopeName,
-      currentPath,
-      includeTree: Object.keys(includeTree || {}),
-      recordCount: records?.length || 0,
-      error: error.message,
-      stack: error.stack
-    })
-    throw error // Re-throw to maintain existing error propagation
   }
 }
 
@@ -1953,41 +155,22 @@ export const processIncludes = async (scope, deps) => {
  * Takes a set of records and an include parameter, loads all requested relationships,
  * and returns both the included resources and the records with relationship data attached.
  *
- * @param {Object} scope - The hooked-api scope object containing:
+ * @param {Object} scope - The resource object containing:
  *   - records: Array<Object> - The main records to process
  *   - scopeName: string - The scope name of the main resources
  *   - includeParam: string - The include parameter value (e.g., "author,comments.author")
  *   - fields: Object - Sparse fieldsets configuration
  * @param {Object} deps - Dependencies object containing:
- *   - context.scopes: Object - The hooked-api scopes object
+ *   - context.scopes: Object - The resources object
  *   - context.log: Object - Logger instance
  *   - context.knex: Object - Knex instance
  * @returns {Promise<Object>} Object with included array and records with relationships
- *
- * @example
- * const result = await buildIncludedResources(
- *   {
- *     records: articleRecords,
- *     scopeName: 'articles',
- *     includeParam: 'author,comments.author',
- *     fields: { articles: 'title,body', people: 'name' }
- *   },
- *   { context: { scopes, log, knex } }
- * );
- *
- * // result.included = [
- * //   { type: 'people', id: '1', attributes: {...} },
- * //   { type: 'comments', id: '1', attributes: {...} },
- * //   ...
- * // ]
- *
- * // result.recordsWithRelationships = original records with _relationships added
  */
 export const buildIncludedResources = async (scope, deps) => {
   const { records, scopeName, includeParam, fields } = scope
   const { scopes, log, knex, capabilities, requestContext } = deps.context
   try {
-    log.trace('[INCLUDE] Building included resources:', { scopeName, includeParam, recordCount: records.length })
+    log.trace('[INCLUDE] Building included resources:', { scopeName, recordCount: records.length })
 
     // Check if includes are empty or records are empty
     if (!includeParam || records.length === 0) {
@@ -2010,20 +193,25 @@ export const buildIncludedResources = async (scope, deps) => {
     // Parse the include parameter
     const includeTree = parseIncludeTree(includeParam)
 
-    log.debug('[INCLUDE] Parsed include tree:', includeTree)
+    log.debug('[INCLUDE] Parsed include tree:', { relationshipCount: Object.keys(includeTree).length })
 
-    // Use a Map to track included resources by type:id
-    const included = new Map()
+    // Share primary linkage with the include graph when a path returns to it.
+    const primary = new Map(records.map(record => {
+      const id = String(getFieldValueForScope(scopes, scopeName, record, 'id'))
+      record[RELATIONSHIPS_KEY] ||= {}
+      return [`${scopeName}:${id}`, { type: scopeName, id, relationships: record[RELATIONSHIPS_KEY] }]
+    }))
+    const included = new Map(primary)
     const processedPaths = new Set() // Prevent infinite loops
 
     // Process all includes
     await processIncludes(
       { records, scopeName, includeTree, included, processedPaths, currentPath: '', fields },
-      { context: { scopes, log, knex, capabilities, requestContext } }
+      { context: { scopes, log, knex, capabilities, requestContext }, loadNestedIncludes: processIncludes }
     )
 
     // Convert Map to array for JSON:API format
-    const includedArray = Array.from(included.values())
+    const includedArray = Array.from(included, ([key, resource]) => primary.has(key) ? null : resource).filter(Boolean)
 
     log.debug('[INCLUDE] Completed building includes:', {
       includedCount: includedArray.length,
@@ -2035,20 +223,10 @@ export const buildIncludedResources = async (scope, deps) => {
       recordsWithRelationships: records
     }
   } catch (error) {
-    if (isRestApiError(error)) throw error
-
-    // Log comprehensive error information
-    log.error('[INCLUDE] Failed to build included resources:', {
-      scopeName,
-      includeParam,
-      recordCount: records?.length || 0,
-      error: error.message,
-      stack: error.stack
-    })
-
     throw wrapUnexpectedError(error, {
       message: `Failed to build included resources for scope '${scopeName}'`,
       context: {
+        phase: 'include',
         scopeName,
         includeParam,
         recordCount: records?.length || 0
@@ -2056,199 +234,3 @@ export const buildIncludedResources = async (scope, deps) => {
     })
   }
 }
-
-/**
- * Loads relationship identifiers for all hasMany relationships without fetching full related records.
- *
- * ## Purpose
- * This function ensures that all hasMany relationships (one-to-many, many-to-many, and polymorphic)
- * always return resource identifiers in the JSON:API response, even when the related resources
- * are not included via the ?include parameter.
- *
- * ## Why this is needed
- * 1. **JSON:API Consistency**: The JSON:API spec allows servers to include relationship identifiers
- *    without including the full related resources. This provides a consistent API surface where
- *    clients always know what relationships exist and their IDs.
- *
- * 2. **Simplified Mode Support**: In simplified mode, relationship IDs are transformed into
- *    minimal objects (e.g., `reviews: [{id: '1'}, {id: '2'}, {id: '3'}]`). Without this function,
- *    these objects only appear when using ?include, creating an inconsistent API where fields appear/disappear.
- *
- * 3. **Performance Balance**: Loading just IDs is much cheaper than loading full records. This gives
- *    clients the ability to know what relationships exist without the cost of fetching all data.
- *
- * ## What it does
- * - Runs ONE query per relationship type (not per record) to fetch all related IDs
- * - Populates the relationship data with resource identifiers: `{ type: 'resource', id: '123' }`
- * - Handles all relationship types: one-to-many, many-to-many, and polymorphic
- * - Works for both JSON:API and simplified modes (transformation happens elsewhere)
- *
- * ## When it runs
- * This runs after the main records are fetched but before includes are processed.
- * If includes ARE specified, they will overwrite these IDs with full data.
- *
- * @param {Array<Object>} records - The parent records to load relationships for
- * @param {string} scopeName - The parent scope name (e.g., 'authors')
- * @param {Object} scopes - All available scopes with their schemas
- * @param {Object} knex - Knex instance for database queries
- * @returns {Promise<void>} Modifies records in place by adding relationship data
- */
-export const loadRelationshipIdentifiers = async (records, scopeName, scopes, knex, requestContext = null) => {
-  if (!records.length) return
-
-  const schemaInfo = scopes[scopeName]?.vars?.schemaInfo
-  if (!schemaInfo) return
-
-  const relationships = schemaInfo.schemaRelationships || {}
-  const recordIds = records.map(r => r.id)
-
-  // Process each hasMany relationship
-  for (const [relName, relDef] of Object.entries(relationships)) {
-    const idsMap = {}
-
-    if (relDef.type === 'hasMany' && !relDef.via) {
-      // Regular one-to-many
-      // Example: publisher hasMany authors
-      const foreignKey = relDef.foreignKey
-
-      if (!foreignKey) {
-        throw new Error(`Missing foreignKey in hasMany relationship '${relName}' for scope '${scopeName}'`)
-      }
-      const targetScope = scopes[relDef.target]
-      const targetTable = targetScope?.vars?.schemaInfo?.tableName || relDef.target
-      const targetIdColumn = getIdColumnForScope(scopes, relDef.target)
-      const foreignKeyColumn = translateColumnForScope(scopes, relDef.target, foreignKey)
-
-      let query = knex(targetTable)
-        .whereIn(foreignKeyColumn, recordIds)
-        .select(targetIdColumn !== 'id' ? `${targetIdColumn} as id` : 'id', foreignKeyColumn)
-
-      const scopedQueryState = await applyScopeFiltersToIncludeQuery({
-        query,
-        scopes,
-        scopeName: relDef.target,
-        requestContext,
-        db: knex,
-        tableName: targetTable,
-        queryPurpose: 'relationship-identifiers'
-      })
-      query = scopedQueryState.query
-
-      const results = await query
-
-      results.forEach(row => {
-        const parentId = String(row[foreignKeyColumn])
-        if (!idsMap[parentId]) idsMap[parentId] = []
-        idsMap[parentId].push(String(row.id))
-      })
-    } else if (relDef.type === 'manyToMany') {
-      // Many-to-many relationship
-      // Example: { type: 'manyToMany', through: 'article_tags', foreignKey: 'article_id', otherKey: 'tag_id' }
-      const { through, foreignKey, otherKey } = relDef
-      const fk = foreignKey
-      const ok = otherKey
-
-      if (!fk || !ok) {
-        throw new Error(`Missing foreignKey or otherKey in manyToMany relationship '${relName}' for scope '${scopeName}'`)
-      }
-
-      // Get the actual table name from the pivot scope
-      const pivotScope = scopes[through]
-      const pivotTable = pivotScope?.vars?.schemaInfo?.tableName || through
-
-      const targetScopeName = relDef.target || relName
-      const targetTable = scopes[targetScopeName]?.vars?.schemaInfo?.tableName || targetScopeName
-      const targetIdColumn = getIdColumnForScope(scopes, targetScopeName)
-      let query = knex(targetTable)
-        .join(`${pivotTable} as pivot`, `${targetTable}.${targetIdColumn}`, `pivot.${ok}`)
-        .whereIn(`pivot.${fk}`, recordIds)
-        .select(
-          `pivot.${fk} as __parent_id`,
-          targetIdColumn !== 'id'
-            ? `${targetTable}.${targetIdColumn} as id`
-            : `${targetTable}.id as id`
-        )
-
-      const scopedQueryState = await applyScopeFiltersToIncludeQuery({
-        query,
-        scopes,
-        scopeName: targetScopeName,
-        requestContext,
-        db: knex,
-        tableName: targetTable,
-        queryPurpose: 'relationship-identifiers'
-      })
-      query = scopedQueryState.query
-
-      const results = await query
-
-      results.forEach(row => {
-        const parentId = String(row.__parent_id)
-        const childId = String(row.id)
-        if (!idsMap[parentId]) idsMap[parentId] = []
-        idsMap[parentId].push(childId)
-      })
-    } else if (relDef.type === 'hasMany' && relDef.via) {
-      // Polymorphic reverse (via)
-      // Example: publishers hasMany reviews via reviewable (where reviews.reviewable_type = 'publishers')
-      const targetScope = relDef.target
-      const targetRelationships = scopes[targetScope]?.vars?.schemaInfo?.schemaRelationships
-      const viaRel = targetRelationships?.[relDef.via]
-
-      if (viaRel?.belongsToPolymorphic) {
-        const { typeField, idField } = viaRel.belongsToPolymorphic
-
-        // Get the actual table name
-        const targetTable = scopes[targetScope]?.vars?.schemaInfo?.tableName || targetScope
-        const targetIdColumn = getIdColumnForScope(scopes, targetScope)
-        const typeColumn = translateColumnForScope(scopes, targetScope, typeField)
-        const idColumn = translateColumnForScope(scopes, targetScope, idField)
-
-        let query = knex(targetTable)
-          .where(typeColumn, scopeName)
-          .whereIn(idColumn, recordIds)
-          .select(targetIdColumn !== 'id' ? `${targetIdColumn} as id` : 'id', idColumn)
-
-        const scopedQueryState = await applyScopeFiltersToIncludeQuery({
-          query,
-          scopes,
-          scopeName: targetScope,
-          requestContext,
-          db: knex,
-          tableName: targetTable,
-          queryPurpose: 'relationship-identifiers'
-        })
-        query = scopedQueryState.query
-
-        const results = await query
-
-        results.forEach(row => {
-          const parentId = String(row[idColumn])
-          if (!idsMap[parentId]) idsMap[parentId] = []
-          idsMap[parentId].push(String(row.id))
-        })
-      }
-    }
-
-    // Apply the collected IDs to all records
-    if (Object.keys(idsMap).length > 0 || relDef.type === 'hasMany' || relDef.type === 'manyToMany') {
-      records.forEach(record => {
-        if (!record[RELATIONSHIPS_KEY]) {
-          record[RELATIONSHIPS_KEY] = {}
-        }
-
-        const ids = idsMap[String(getFieldValueForScope(scopes, scopeName, record, 'id'))] || []
-        // For manyToMany, the target type is the relationship name itself
-        // For hasMany/hasOne, the target type is specified in the target property
-        const targetType = (relDef.type === 'manyToMany') ? relName : relDef.target
-
-        record[RELATIONSHIPS_KEY][relName] = {
-          data: ids.map(id => ({
-            type: targetType,
-            id
-          }))
-        }
-      })
-    }
-  }
-}