ai-database 2.1.3 → 2.3.0

package/dist/schema/resolve.d.ts

@@ -37,6 +37,25 @@ export declare function resolveContextPath(path: string, entity: Record<string,
  * @returns The instructions with all template variables resolved
  */
 export declare function resolveInstructions(instructions: string, entity: Record<string, unknown>, typeName: string, schema: ParsedSchema, provider: DBProvider): Promise<string>;
+/**
+ * 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. Supports dotted paths like
+ * 'Startup.icp.industry' for deeply nested context fetching.
+ *
+ * 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 path to fetched entity data
+ */
+export declare function prefetchContextPaths(contextDeps: string[], entity: Record<string, unknown>, typeName: string, schema: ParsedSchema, provider: DBProvider): Promise<Map<string, Record<string, unknown>>>;
 /**
  * Pre-fetch context dependencies declared in $context
  *
@@ -53,7 +72,8 @@ export declare function resolveInstructions(instructions: string, entity: Record
  */
 export declare function prefetchContext(contextDeps: string[], entity: Record<string, unknown>, typeName: string, schema: ParsedSchema, provider: DBProvider): Promise<Map<string, Record<string, unknown>>>;
 /**
- * Check if a field type is a prompt (contains spaces, indicating AI generation)
+ * 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 declare function isPromptField(field: ParsedField): boolean;
 /**
@@ -70,7 +90,11 @@ export declare function resolveNestedPending(data: Record<string, unknown>, enti
  * For exact matches (-> and <-), creates new entities.
  * For fuzzy matches (~> and <~), searches for existing entities first.
  */
-export declare function resolveReferenceSpec(spec: ReferenceSpec, contextData: Record<string, unknown>, schema: ParsedSchema, provider: DBProvider, generateContextAwareValue: (fieldName: string, type: string, fullContext: string, hint: string | undefined, parentData: Record<string, unknown>) => string): Promise<string | null>;
+export declare function resolveReferenceSpec(spec: ReferenceSpec, contextData: Record<string, unknown>, schema: ParsedSchema, provider: DBProvider, generateContextAwareValue: (fieldName: string, type: string, fullContext: string, hint: string | undefined, parentData: Record<string, unknown>) => string, generateEntityWithAI?: (type: string, prompt: string | undefined, context: {
+    parent: string;
+    parentData: Record<string, unknown>;
+    parentId?: string;
+}, schema: ParsedSchema) => Promise<Record<string, unknown>>): Promise<string | null>;
 /**
  * Hydrate an entity with lazy-loaded relations
  *
@@ -78,10 +102,27 @@ export declare function resolveReferenceSpec(spec: ReferenceSpec, contextData: R
  * 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 declare function hydrateEntity(data: Record<string, unknown>, entity: ParsedEntity, schema: ParsedSchema, resolveProvider: () => Promise<DBProvider>): Record<string, unknown>;
 //# sourceMappingURL=resolve.d.ts.map

package/dist/schema/resolve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/schema/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,YAAY,EACZ,YAAY,EAEb,MAAM,aAAa,CAAA;AAEpB,OAAO,KAAK,EAAE,UAAU,EAAwB,MAAM,eAAe,CAAA;AAErE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAO/C;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAOjD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,GAAG,MAAM,GAAG,SAAS,CAcpH;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,eAAe,EAAE,MAAM,EACvB,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,UAAU,GACnB,OAAO,CAAC,OAAO,CAAC,CAqClB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,mBAAmB,CACvC,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,UAAU,GACnB,OAAO,CAAC,MAAM,CAAC,CAcjB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,eAAe,CACnC,WAAW,EAAE,MAAM,EAAE,EACrB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,UAAU,GACnB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAsC/C;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAIzD;AAMD;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,UAAU,GACnB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAoBlC;AAMD;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,aAAa,EACnB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,UAAU,EACpB,yBAAyB,EAAE,CACzB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAChC,MAAM,GACV,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAyExB;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,YAAY,EACpB,eAAe,EAAE,MAAM,OAAO,CAAC,UAAU,CAAC,GACzC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA+RzB"}
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/schema/resolve.ts"],"names":[],"mappings":"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"}

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) {
@@ -302,9 +446,7 @@ export function hydrateEntity(data, entity, schema, resolveProvider) {
             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];
+                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({}, {
@@ -352,6 +494,12 @@ export function hydrateEntity(data, entity, schema, resolveProvider) {
                         if (prop === '$type') {
                             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;
                     },
                 });
@@ -365,9 +513,7 @@ export function hydrateEntity(data, entity, schema, resolveProvider) {
             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];
+                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) {
@@ -428,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
@@ -443,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);
                                         }
                                     }
@@ -533,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;
                         }
                     })();
                 },