ai-database 2.1.1 → 2.3.0

package/dist/schema/resolve.js

@@ -8,6 +8,7 @@
  */
 import { hasSemanticSearch } from './provider.js';
 import { isPrimitiveType } from './parse.js';
+import { findBestMatchAcrossTypes } from './search-utils.js';
 // =============================================================================
 // Context Resolution - Template Variables and $instructions
 // =============================================================================
@@ -104,63 +105,132 @@ export async function resolveInstructions(instructions, entity, typeName, schema
     return resolved;
 }
 /**
- * Pre-fetch context dependencies declared in $context
+ * Find the field in the entity that references a given type
+ */
+function findFieldByRelatedType(entityDef, relatedType) {
+    for (const [fieldName, field] of entityDef.fields) {
+        if (field.isRelation && field.relatedType === relatedType) {
+            return { fieldName, field };
+        }
+    }
+    return undefined;
+}
+/**
+ * Pre-fetch context dependencies declared in $context using dotted paths
  *
  * The $context field declares explicit context dependencies that should
- * be pre-fetched before generating AI fields. This ensures all referenced
- * entities are available for template variable resolution.
+ * be pre-fetched before generating AI fields. Supports dotted paths like
+ * 'Startup.icp.industry' for deeply nested context fetching.
  *
- * @param contextDeps - Array of context dependency types (e.g., ['Startup', 'ICP'])
+ * Context paths can be:
+ * - Simple type names: 'Startup' - finds field that references Startup type
+ * - Dotted paths: 'Startup.icp.industry' - traverses relationships
+ *
+ * @param contextDeps - Array of context dependency paths (e.g., ['Startup', 'Startup.icp.industry'])
  * @param entity - The current entity data
  * @param typeName - The current entity type name
  * @param schema - The parsed schema
  * @param provider - The database provider for fetching related entities
- * @returns Map of context name to fetched entity data
+ * @returns Map of context path to fetched entity data
  */
-export async function prefetchContext(contextDeps, entity, typeName, schema, provider) {
+export async function prefetchContextPaths(contextDeps, entity, typeName, schema, provider) {
     const contextData = new Map();
     const currentEntity = schema.entities.get(typeName);
     if (!currentEntity)
         return contextData;
-    for (const dep of contextDeps) {
-        // Convert to camelCase for field lookup (e.g., "Startup" -> "startup")
-        const fieldName = dep.charAt(0).toLowerCase() + dep.slice(1);
-        // Check if we have a field that references this type
-        const field = currentEntity.fields.get(fieldName);
-        if (field?.isRelation && field.relatedType) {
-            const entityId = entity[fieldName];
-            if (typeof entityId === 'string') {
-                const fetched = await provider.get(field.relatedType, entityId);
-                if (fetched) {
-                    contextData.set(fieldName, fetched);
-                    // Also store nested relationships
-                    const relatedEntity = schema.entities.get(field.relatedType);
-                    if (relatedEntity) {
-                        for (const [nestedFieldName, nestedField] of relatedEntity.fields) {
-                            if (nestedField.isRelation && nestedField.relatedType) {
-                                const nestedId = fetched[nestedFieldName];
-                                if (typeof nestedId === 'string') {
-                                    const nestedFetched = await provider.get(nestedField.relatedType, nestedId);
-                                    if (nestedFetched) {
-                                        contextData.set(`${fieldName}.${nestedFieldName}`, nestedFetched);
-                                    }
-                                }
-                            }
-                        }
-                    }
+    // Track already fetched entities to avoid duplicate fetches
+    // Key: "TypeName:entityId", Value: fetched entity data
+    const fetchCache = new Map();
+    // Deduplicate context deps
+    const uniqueDeps = [...new Set(contextDeps)];
+    for (const dep of uniqueDeps) {
+        // Parse the path - could be "Startup" or "Startup.icp.industry"
+        const pathParts = dep.split('.');
+        // Start from the current entity and traverse the path
+        let currentData = entity;
+        let currentEntityDef = currentEntity;
+        let currentPath = '';
+        for (let i = 0; i < pathParts.length; i++) {
+            const part = pathParts[i];
+            // Try two approaches:
+            // 1. Convert PascalCase type name to camelCase field name
+            // 2. Find field by related type
+            const camelCaseFieldName = part.charAt(0).toLowerCase() + part.slice(1);
+            let fieldInfo;
+            // First try exact field name match
+            const directField = currentEntityDef.fields.get(camelCaseFieldName);
+            if (directField?.isRelation && directField.relatedType) {
+                fieldInfo = { fieldName: camelCaseFieldName, field: directField };
+            }
+            // If no direct match, try to find field by related type (e.g., 'Related' -> find field that points to Related)
+            if (!fieldInfo) {
+                fieldInfo = findFieldByRelatedType(currentEntityDef, part);
+            }
+            if (!fieldInfo) {
+                // Path invalid - no field found
+                break;
+            }
+            const { fieldName, field } = fieldInfo;
+            currentPath = currentPath ? `${currentPath}.${fieldName}` : fieldName;
+            // Get the entity ID from current data
+            const entityId = currentData[fieldName];
+            if (typeof entityId !== 'string') {
+                // Path invalid - no entity ID
+                break;
+            }
+            // Check cache first
+            const cacheKey = `${field.relatedType}:${entityId}`;
+            let fetched = fetchCache.get(cacheKey);
+            if (!fetched) {
+                // Fetch the related entity
+                const fetchedResult = await provider.get(field.relatedType, entityId);
+                if (fetchedResult) {
+                    fetched = fetchedResult;
+                    fetchCache.set(cacheKey, fetched);
                 }
             }
+            if (!fetched) {
+                // Path invalid - entity not found
+                break;
+            }
+            // Store the result with the actual field name path
+            contextData.set(currentPath, fetched);
+            // Update for next iteration
+            currentData = fetched;
+            const nextEntityDef = schema.entities.get(field.relatedType);
+            if (!nextEntityDef) {
+                // Path invalid - entity type not in schema
+                break;
+            }
+            currentEntityDef = nextEntityDef;
         }
     }
     return contextData;
 }
 /**
- * Check if a field type is a prompt (contains spaces, indicating AI generation)
+ * Pre-fetch context dependencies declared in $context
+ *
+ * The $context field declares explicit context dependencies that should
+ * be pre-fetched before generating AI fields. This ensures all referenced
+ * entities are available for template variable resolution.
+ *
+ * @param contextDeps - Array of context dependency types (e.g., ['Startup', 'ICP'])
+ * @param entity - The current entity data
+ * @param typeName - The current entity type name
+ * @param schema - The parsed schema
+ * @param provider - The database provider for fetching related entities
+ * @returns Map of context name to fetched entity data
+ */
+export async function prefetchContext(contextDeps, entity, typeName, schema, provider) {
+    // Use the new path-based implementation which handles both simple and dotted paths
+    return prefetchContextPaths(contextDeps, entity, typeName, schema, provider);
+}
+/**
+ * Check if a field type is a prompt (contains spaces, slashes, or question marks indicating AI generation).
+ * Examples: 'Describe the product', 'low/medium/high', 'What is the severity?'
  */
 export function isPromptField(field) {
-    // Fields with spaces in their type are prompts for AI generation
-    return field.type.includes(' ') ||
-        (field.type === 'string' && !field.isRelation && !isPrimitiveType(field.type));
+    return field.type.includes(' ') || field.type.includes('/') || field.type.includes('?');
 }
 // =============================================================================
 // Nested Pending Resolution
@@ -184,7 +254,7 @@ export async function resolveNestedPending(data, entity, schema, provider) {
             if (relatedEntity) {
                 const resolvedNested = await resolveNestedPending(pending.data, relatedEntity, schema, provider);
                 const created = await provider.create(pending.type, undefined, resolvedNested);
-                resolved[fieldName] = created.$id;
+                resolved[fieldName] = created['$id'];
             }
         }
     }
@@ -199,7 +269,7 @@ export async function resolveNestedPending(data, entity, schema, provider) {
  * For exact matches (-> and <-), creates new entities.
  * For fuzzy matches (~> and <~), searches for existing entities first.
  */
-export async function resolveReferenceSpec(spec, contextData, schema, provider, generateContextAwareValue) {
+export async function resolveReferenceSpec(spec, contextData, schema, provider, generateContextAwareValue, generateEntityWithAI) {
     const targetEntity = schema.entities.get(spec.type);
     if (!targetEntity) {
         throw new Error(`Unknown target type: ${spec.type}`);
@@ -208,66 +278,123 @@ export async function resolveReferenceSpec(spec, contextData, schema, provider,
         // For fuzzy references, try to find an existing entity first
         if (hasSemanticSearch(provider)) {
             const searchQuery = spec.generatedText || spec.prompt || spec.field;
-            const matches = await provider.semanticSearch(spec.type, searchQuery, {
-                minScore: 0.5,
-                limit: 1,
+            // Use threshold from spec, or default to 0.75
+            const threshold = spec.threshold ?? 0.75;
+            // Determine which types to search - all union types or just the primary type
+            const typesToSearch = spec.unionTypes && spec.unionTypes.length > 0 ? spec.unionTypes : [spec.type];
+            // Search all types and find the best match using shared utility
+            const bestMatchResult = await findBestMatchAcrossTypes(typesToSearch, searchQuery, {
+                threshold,
+                limit: 5,
+                schema,
+                provider,
             });
-            const firstMatch = matches[0];
-            if (firstMatch) {
-                return firstMatch.$id;
+            if (bestMatchResult) {
+                // Update the matched entity with metadata
+                await provider.update(bestMatchResult.type, bestMatchResult.match.$id, {
+                    $matchedType: bestMatchResult.type,
+                    $similarity: bestMatchResult.match.$score,
+                });
+                // Also set metadata on contextData for edge creation later
+                contextData[`${spec.field}$matchedType`] = bestMatchResult.type;
+                contextData[`${spec.field}$score`] = bestMatchResult.match.$score;
+                return bestMatchResult.match.$id;
             }
         }
         // If no match found for fuzzy, fall through to create
     }
     // Create a new entity
-    const generatedData = {};
-    // Build context for generation
+    let generatedData = {};
     const hint = spec.generatedText || spec.prompt || spec.field;
-    const parentContextFields = [];
-    for (const [key, value] of Object.entries(contextData)) {
-        if (!key.startsWith('$') && !key.startsWith('_') && typeof value === 'string' && value) {
-            parentContextFields.push(`${key}: ${value}`);
+    const parentType = contextData['$type'];
+    const parentId = contextData['$id'];
+    // Try AI generation first if available
+    if (generateEntityWithAI && parentType) {
+        try {
+            const aiData = await generateEntityWithAI(spec.type, hint, {
+                parent: parentType,
+                parentData: contextData,
+                ...(parentId !== undefined ? { parentId } : {}),
+            }, schema);
+            if (aiData && Object.keys(aiData).length > 0) {
+                // Resolve any nested pending relations (from generateEntity)
+                generatedData = await resolveNestedPending(aiData, targetEntity, schema, provider);
+            }
+        }
+        catch {
+            // AI generation failed - fall through to placeholder generation
         }
     }
-    const fullContext = [hint, ...parentContextFields].filter(Boolean).join(' | ');
-    // Generate default values for the target entity's fields
-    for (const [fieldName, field] of targetEntity.fields) {
-        if (!field.isRelation && !field.isOptional) {
-            if (field.type === 'string') {
-                generatedData[fieldName] = generateContextAwareValue(fieldName, spec.type, fullContext, hint, contextData);
-            }
-            else if (field.type === 'number') {
-                generatedData[fieldName] = 0;
-            }
-            else if (field.type === 'boolean') {
-                generatedData[fieldName] = false;
+    // If AI generation didn't produce data, fall back to placeholder generation
+    if (Object.keys(generatedData).length === 0) {
+        // Build context for generation
+        const parentContextFields = [];
+        for (const [key, value] of Object.entries(contextData)) {
+            if (!key.startsWith('$') && !key.startsWith('_') && typeof value === 'string' && value) {
+                parentContextFields.push(`${key}: ${value}`);
             }
         }
-        else if (field.isRelation && field.operator === '->' && !field.isArray && !field.isOptional) {
-            // Recursively resolve nested forward exact relations
-            const nestedSpec = {
-                field: fieldName,
-                operator: '->',
-                type: field.relatedType,
-                matchMode: 'exact',
-                resolved: false,
-                prompt: field.prompt,
-            };
-            const nestedId = await resolveReferenceSpec(nestedSpec, generatedData, schema, provider, generateContextAwareValue);
-            if (nestedId) {
-                generatedData[fieldName] = nestedId;
+        // Include source entity's $instructions (parent context) and target entity's $instructions
+        const sourceInstructions = spec.sourceInstructions;
+        const targetInstructions = targetEntity.schema?.['$instructions'];
+        const contextParts = [];
+        // Source instructions first (parent context propagation)
+        if (sourceInstructions) {
+            contextParts.push(sourceInstructions);
+        }
+        // Then target instructions (child entity's own context)
+        if (targetInstructions) {
+            contextParts.push(targetInstructions);
+        }
+        if (hint) {
+            contextParts.push(hint);
+        }
+        contextParts.push(...parentContextFields);
+        const fullContext = contextParts.filter(Boolean).join(' | ');
+        // Generate default values for the target entity's fields
+        for (const [fieldName, field] of targetEntity.fields) {
+            if (!field.isRelation && !field.isOptional) {
+                const isPrompt = isPromptField(field);
+                if (field.type === 'string' || isPrompt) {
+                    // For prompt fields, use the type as additional context for generation
+                    const fieldHint = isPrompt ? field.type : hint;
+                    generatedData[fieldName] = generateContextAwareValue(fieldName, spec.type, fullContext, fieldHint, contextData);
+                }
+                else if (field.type === 'number') {
+                    generatedData[fieldName] = 0;
+                }
+                else if (field.type === 'boolean') {
+                    generatedData[fieldName] = false;
+                }
+            }
+            else if (field.isRelation &&
+                field.operator === '->' &&
+                !field.isArray &&
+                !field.isOptional) {
+                // Recursively resolve nested forward exact relations
+                const nestedSpec = {
+                    field: fieldName,
+                    operator: '->',
+                    type: field.relatedType,
+                    matchMode: 'exact',
+                    resolved: false,
+                    ...(field.prompt !== undefined ? { prompt: field.prompt } : {}),
+                };
+                const nestedId = await resolveReferenceSpec(nestedSpec, generatedData, schema, provider, generateContextAwareValue, generateEntityWithAI);
+                if (nestedId) {
+                    generatedData[fieldName] = nestedId;
+                }
             }
         }
     }
     // Use parent ID if available, otherwise use a descriptive string
-    const parentId = contextData.$id;
     const created = await provider.create(spec.type, undefined, {
         ...generatedData,
         $generated: true,
         $generatedBy: parentId || (spec.matchMode === 'fuzzy' ? 'fuzzy-resolution' : 'reference-resolution'),
         $sourceField: spec.field,
     });
-    return created.$id;
+    return created['$id'];
 }
 // =============================================================================
 // Entity Hydration
@@ -279,14 +406,31 @@ export async function resolveReferenceSpec(spec, contextData, schema, provider,
  * of the related type that have a reference pointing TO this entity.
  * This enables reverse lookups like "get all comments for a post".
  *
- * Backward reference resolution:
- * - Single backward ref with stored ID: resolve directly (e.g., member.team = teamId -> get Team by ID)
+ * ## Backward Exact (<-) vs Backward Fuzzy (<~) Resolution
+ *
+ * This function handles both backward exact and backward fuzzy resolution,
+ * but the resolution strategies differ:
+ *
+ * **Backward Exact (`<-`)**: Uses foreign key lookup (exact ID match)
+ * - Queries `provider.list(type, { where: { backrefField: id } })`
+ * - Returns all entities that explicitly reference the current entity
+ * - Example: `Blog.posts: ['<-Post']` finds Posts where `post.blog === blog.$id`
+ *
+ * **Backward Fuzzy (`<~`)**: Uses pre-resolved IDs from semantic search
+ * - During creation, `resolveBackwardFuzzy()` stores matched IDs
+ * - Hydration retrieves entities using those stored IDs
+ * - Example: `ICP.as: '<~Occupation'` was resolved via semantic search at creation time
+ *
+ * ## Resolution Cases
+ *
+ * - Single backward ref with stored ID: resolve directly (e.g., member.team = teamId)
  * - Single backward ref without stored ID: find related entity that points to us via relations
- * - Array backward ref: find all entities of related type where their forward ref points to us
+ * - Array backward ref with stored IDs: resolve each stored ID (backward fuzzy case)
+ * - Array backward ref without stored IDs: query via backref lookup (backward exact case)
  */
 export function hydrateEntity(data, entity, schema, resolveProvider) {
     const hydrated = { ...data };
-    const id = (data.$id || data.id);
+    const id = (data['$id'] || data['id']);
     const typeName = entity.name;
     // Add lazy getters for relations
     for (const [fieldName, field] of entity.fields) {
@@ -301,14 +445,40 @@ export function hydrateEntity(data, entity, schema, resolveProvider) {
             // - Can be awaited to get the related entity (thenable)
             if (!isBackward && !field.isArray && data[fieldName]) {
                 const storedId = data[fieldName];
+                // For union types, we need to check all possible types
+                const typesToSearch = field.unionTypes && field.unionTypes.length > 0 ? field.unionTypes : [field.relatedType];
+                // Check if we have a stored matchedType from the creation
+                const storedMatchedType = data[`${fieldName}$matchedType`];
                 const thenableProxy = new Proxy({}, {
                     get(target, prop) {
                         if (prop === 'then') {
                             return (resolve, reject) => {
                                 return (async () => {
                                     const provider = await resolveProvider();
-                                    const result = await provider.get(field.relatedType, storedId);
-                                    return result ? hydrateEntity(result, relatedEntity, schema, resolveProvider) : null;
+                                    // If we have a stored matched type, use it directly
+                                    if (storedMatchedType && typesToSearch.includes(storedMatchedType)) {
+                                        const result = await provider.get(storedMatchedType, storedId);
+                                        if (result) {
+                                            const matchedEntity = schema.entities.get(storedMatchedType);
+                                            if (matchedEntity) {
+                                                const hydrated = hydrateEntity(result, matchedEntity, schema, resolveProvider);
+                                                return { ...hydrated, $matchedType: storedMatchedType };
+                                            }
+                                        }
+                                    }
+                                    // For union types, try each type until we find the entity
+                                    for (const searchType of typesToSearch) {
+                                        const searchEntity = schema.entities.get(searchType);
+                                        if (!searchEntity)
+                                            continue;
+                                        const result = await provider.get(searchType, storedId);
+                                        if (result) {
+                                            const hydrated = hydrateEntity(result, searchEntity, schema, resolveProvider);
+                                            // Include $matchedType to indicate which union type matched
+                                            return { ...hydrated, $matchedType: searchType };
+                                        }
+                                    }
+                                    return null;
                                 })().then(resolve, reject);
                             };
                         }
@@ -322,8 +492,14 @@ export function hydrateEntity(data, entity, schema, resolveProvider) {
                             return (regex) => storedId.match(regex);
                         }
                         if (prop === '$type') {
-                            return field.relatedType;
+                            return storedMatchedType || field.relatedType;
                         }
+                        // Return the stored ID for $id property access (useful for equality checks)
+                        if (prop === '$id') {
+                            return storedId;
+                        }
+                        // For any other property access, return undefined
+                        // Note: Use problem.task.$id or String(problem.task) for equality checks
                         return undefined;
                     },
                 });
@@ -336,6 +512,8 @@ export function hydrateEntity(data, entity, schema, resolveProvider) {
             // Note: we create the proxy even for empty arrays so they have $type for batch loading detection
             if (!isBackward && field.isArray && Array.isArray(data[fieldName])) {
                 const storedIds = data[fieldName];
+                // For union types, we need to check all possible types
+                const typesToSearch = field.unionTypes && field.unionTypes.length > 0 ? field.unionTypes : [field.relatedType];
                 // Create a proxy that wraps the array but adds thenable behavior
                 const thenableArray = new Proxy(storedIds, {
                     get(target, prop) {
@@ -343,8 +521,23 @@ export function hydrateEntity(data, entity, schema, resolveProvider) {
                             return (resolve, reject) => {
                                 return (async () => {
                                     const provider = await resolveProvider();
-                                    const results = await Promise.all(storedIds.map(targetId => provider.get(field.relatedType, targetId)));
-                                    return results.filter(r => r !== null).map((r) => hydrateEntity(r, relatedEntity, schema, resolveProvider));
+                                    const results = [];
+                                    for (const targetId of storedIds) {
+                                        // For union types, try each type until we find the entity
+                                        for (const searchType of typesToSearch) {
+                                            const searchEntity = schema.entities.get(searchType);
+                                            if (!searchEntity)
+                                                continue;
+                                            const result = await provider.get(searchType, targetId);
+                                            if (result) {
+                                                const hydrated = hydrateEntity(result, searchEntity, schema, resolveProvider);
+                                                // Include $matchedType to indicate which union type matched
+                                                results.push({ ...hydrated, $matchedType: searchType });
+                                                break;
+                                            }
+                                        }
+                                    }
+                                    return results;
                                 })().then(resolve, reject);
                             };
                         }
@@ -381,9 +574,7 @@ export function hydrateEntity(data, entity, schema, resolveProvider) {
                             if (storedId) {
                                 // Has stored ID - directly fetch the related entity
                                 const result = await provider.get(field.relatedType, storedId);
-                                return result
-                                    ? hydrateEntity(result, relatedEntity, schema, resolveProvider)
-                                    : null;
+                                return result ? hydrateEntity(result, relatedEntity, schema, resolveProvider) : null;
                             }
                             // No stored ID - find via inverse relation lookup
                             // Find entities of relatedType that have this entity in their relations
@@ -396,9 +587,9 @@ export function hydrateEntity(data, entity, schema, resolveProvider) {
                                     // Check if any entity of relatedType has this entity in that relation
                                     const allRelated = await provider.list(field.relatedType);
                                     for (const candidate of allRelated) {
-                                        const candidateId = (candidate.$id || candidate.id);
+                                        const candidateId = (candidate['$id'] || candidate['id']);
                                         const related = await provider.related(field.relatedType, candidateId, relFieldName);
-                                        if (related.some(r => (r.$id || r.id) === id)) {
+                                        if (related.some((r) => (r['$id'] || r['id']) === id)) {
                                             return hydrateEntity(candidate, relatedEntity, schema, resolveProvider);
                                         }
                                     }
@@ -412,40 +603,68 @@ export function hydrateEntity(data, entity, schema, resolveProvider) {
                         const provider = await resolveProvider();
                         if (isBackward) {
                             // Case 2: Array backward ref
+                            // For union types, we need to check all possible types
+                            const typesToSearch = field.unionTypes && field.unionTypes.length > 0
+                                ? field.unionTypes
+                                : [field.relatedType];
                             // Check if we have stored IDs (e.g., from backward fuzzy resolution)
                             const storedIds = data[fieldName];
                             if (Array.isArray(storedIds) && storedIds.length > 0) {
                                 // Use stored IDs directly - this handles backward fuzzy (<~) array fields
-                                const results = await Promise.all(storedIds.map(targetId => provider.get(field.relatedType, targetId)));
-                                return Promise.all(results.filter(r => r !== null).map((r) => hydrateEntity(r, relatedEntity, schema, resolveProvider)));
+                                // For union types, try each type until we find the entity
+                                const hydrated = [];
+                                for (const targetId of storedIds) {
+                                    for (const searchType of typesToSearch) {
+                                        const searchEntity = schema.entities.get(searchType);
+                                        if (!searchEntity)
+                                            continue;
+                                        const result = await provider.get(searchType, targetId);
+                                        if (result) {
+                                            const hydratedEntity = hydrateEntity(result, searchEntity, schema, resolveProvider);
+                                            hydrated.push({ ...hydratedEntity, $matchedType: searchType });
+                                            break;
+                                        }
+                                    }
+                                }
+                                return hydrated;
                             }
-                            // No stored IDs - use backref lookup
+                            // No stored IDs - use backref lookup across all union types
                             // e.g., Blog.posts: ['<-Post'] - find Posts where post.blog === blog.$id
                             // The backref tells us which field on the related type stores our ID
-                            // If no explicit backref, infer from schema relationships
-                            let backrefField = field.backref;
-                            if (!backrefField) {
-                                // Infer backref: look for a field on related entity that points to us
-                                for (const [relFieldName, relField] of relatedEntity.fields) {
-                                    if (relField.isRelation &&
-                                        relField.relatedType === typeName &&
-                                        relField.direction !== 'backward' &&
-                                        !relField.isArray) {
-                                        // Found a forward single relation pointing to us - use its name
-                                        backrefField = relFieldName;
-                                        break;
+                            const allResults = [];
+                            for (const searchType of typesToSearch) {
+                                const searchEntity = schema.entities.get(searchType);
+                                if (!searchEntity)
+                                    continue;
+                                // If no explicit backref, infer from schema relationships
+                                let backrefField = field.backref;
+                                if (!backrefField) {
+                                    // Infer backref: look for a field on related entity that points to us
+                                    for (const [relFieldName, relField] of searchEntity.fields) {
+                                        if (relField.isRelation &&
+                                            relField.relatedType === typeName &&
+                                            relField.direction !== 'backward' &&
+                                            !relField.isArray) {
+                                            // Found a forward single relation pointing to us - use its name
+                                            backrefField = relFieldName;
+                                            break;
+                                        }
+                                    }
+                                    // Fallback to entity name lowercase if no explicit relation found
+                                    if (!backrefField) {
+                                        backrefField = typeName.toLowerCase();
                                     }
                                 }
-                                // Fallback to entity name lowercase if no explicit relation found
-                                if (!backrefField) {
-                                    backrefField = typeName.toLowerCase();
+                                // Query the related type for entities that reference this entity
+                                const results = await provider.list(searchType, {
+                                    where: { [backrefField]: id },
+                                });
+                                for (const r of results) {
+                                    const hydratedEntity = hydrateEntity(r, searchEntity, schema, resolveProvider);
+                                    allResults.push({ ...hydratedEntity, $matchedType: searchType });
                                 }
                             }
-                            // Query the related type for entities that reference this entity
-                            const results = await provider.list(field.relatedType, {
-                                where: { [backrefField]: id },
-                            });
-                            return Promise.all(results.map((r) => hydrateEntity(r, relatedEntity, schema, resolveProvider)));
+                            return allResults;
                         }
                         else if (field.isArray) {
                             // Forward array relation - get related entities via relationship
@@ -458,9 +677,7 @@ export function hydrateEntity(data, entity, schema, resolveProvider) {
                             if (!relatedId)
                                 return null;
                             const result = await provider.get(field.relatedType, relatedId);
-                            return result
-                                ? hydrateEntity(result, relatedEntity, schema, resolveProvider)
-                                : null;
+                            return result ? hydrateEntity(result, relatedEntity, schema, resolveProvider) : null;
                         }
                     })();
                 },