ai-database 2.1.1 → 2.3.0

package/dist/schema/entity-operations.js

@@ -0,0 +1,818 @@
+/**
+ * Entity Operations Factory
+ *
+ * Contains the createEntityOperations<T>() function that creates typed CRUD operations
+ * for database entities. This includes get, list, find, create, update, upsert, delete,
+ * search, forEach, draft, and resolve operations.
+ *
+ * @packageDocumentation
+ */
+import { resolveProvider, hasSemanticSearch, hasHybridSearch, hasTransactionSupport, } from './provider.js';
+import { hydrateEntity, resolveReferenceSpec, isPromptField } from './resolve.js';
+import { resolveForwardExact, generateAIFields, generateContextAwareValue, generateNaturalLanguageContent, generateEntity, } from './cascade.js';
+import { resolveBackwardFuzzy, resolveForwardFuzzy, getFuzzyThreshold } from './semantic.js';
+import { isNotFoundError, isEntityExistsError, wrapDatabaseError, DatabaseError, CapabilityNotSupportedError, } from '../errors.js';
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/** Metadata field suffixes that should be stripped from entity data */
+const METADATA_SUFFIXES = ['$matchedType', '$score', '$fallbackUsed', '$searchedTypes'];
+/**
+ * Check if a key is a metadata field that should be excluded from entity data
+ */
+function isMetadataField(key) {
+    if (key.startsWith('$'))
+        return true;
+    return METADATA_SUFFIXES.some((suffix) => key.endsWith(suffix));
+}
+/**
+ * Remove metadata fields from entity data
+ */
+function cleanEntityData(data) {
+    const cleaned = {};
+    for (const [key, value] of Object.entries(data)) {
+        if (!isMetadataField(key)) {
+            cleaned[key] = value;
+        }
+    }
+    return cleaned;
+}
+/**
+ * Apply where filters to a list of records
+ */
+function applyWhereFilter(records, where) {
+    return records.filter((record) => Object.entries(where).every(([key, value]) => record[key] === value));
+}
+/**
+ * Apply pagination (offset/limit) to a list of records
+ */
+function applyPagination(records, offset, limit) {
+    if (!limit)
+        return records;
+    const start = offset ?? 0;
+    return records.slice(start, start + limit);
+}
+// =============================================================================
+// Entity Operations Factory
+// =============================================================================
+/**
+ * Create typed CRUD operations for a database entity
+ *
+ * This function creates the full set of operations for working with a specific
+ * entity type in the database, including:
+ * - get/list/find for reading
+ * - create/update/upsert/delete for writing
+ * - search/semanticSearch/hybridSearch for querying
+ * - forEach for iteration
+ * - draft/resolve for two-phase entity creation
+ *
+ * @param typeName - The type name for the entity
+ * @param entity - The parsed entity definition
+ * @param schema - The full parsed schema
+ * @returns EntityOperations<T> with all available methods
+ */
+export function createEntityOperations(typeName, entity, schema) {
+    return {
+        async get(id) {
+            const provider = await resolveProvider();
+            const result = await provider.get(typeName, id);
+            if (!result)
+                return null;
+            return hydrateEntity(result, entity, schema, resolveProvider);
+        },
+        async list(options) {
+            try {
+                const provider = await resolveProvider();
+                const results = await provider.list(typeName, options);
+                return Promise.all(results.map((r) => hydrateEntity(r, entity, schema, resolveProvider)));
+            }
+            catch (error) {
+                // Handle error with callback if provided
+                if (options?.onError) {
+                    const wrappedError = error instanceof Error ? error : new Error(String(error));
+                    const fallback = options.onError(wrappedError);
+                    return (fallback ?? []);
+                }
+                // Suppress errors if requested
+                if (options?.suppressErrors) {
+                    return [];
+                }
+                throw error;
+            }
+        },
+        async find(where) {
+            const provider = await resolveProvider();
+            const results = await provider.list(typeName, {
+                where: where,
+            });
+            return Promise.all(results.map((r) => hydrateEntity(r, entity, schema, resolveProvider)));
+        },
+        async search(query, options) {
+            const provider = await resolveProvider();
+            const results = await provider.search(typeName, query, options);
+            return Promise.all(results.map((r) => hydrateEntity(r, entity, schema, resolveProvider)));
+        },
+        async create(idOrData, maybeData, maybeOptions) {
+            const providedId = typeof idOrData === 'string' ? idOrData : undefined;
+            const data = typeof idOrData === 'string'
+                ? maybeData
+                : idOrData;
+            // Options can be passed as third arg when id is provided, or as second arg when id is not
+            const options = typeof idOrData === 'string' ? maybeOptions : maybeData;
+            const entityId = providedId || crypto.randomUUID();
+            try {
+                const provider = await resolveProvider();
+                // Use transaction if provider supports it, to ensure atomicity of cascade
+                const useTransaction = hasTransactionSupport(provider);
+                const txn = useTransaction ? await provider.beginTransaction() : null;
+                // The target for write operations: transaction if available, otherwise provider directly
+                const writeTarget = txn ?? provider;
+                try {
+                    let finalData;
+                    let pendingRelations = [];
+                    let fuzzyPendingRelations = [];
+                    // Check if data has already been through draft/resolve (called from schema.ts wrapper)
+                    if (options?._preResolved) {
+                        // Data is already resolved - skip draft/resolve phases
+                        const cleanedData = cleanEntityData(data);
+                        // Still need to resolve backward fuzzy references and generate AI fields
+                        const backwardResolvedData = await resolveBackwardFuzzy(typeName, cleanedData, entity, schema, provider);
+                        finalData = await generateAIFields(backwardResolvedData, typeName, entity, schema, provider);
+                        // Extract pending relations from already-resolved data by checking field values
+                        // that look like entity IDs and match relation field definitions
+                        for (const [fieldName, field] of entity.fields) {
+                            if (field.isRelation && field.relatedType) {
+                                const resolvedValue = cleanedData[fieldName];
+                                if (!resolvedValue)
+                                    continue;
+                                const isFuzzy = field.operator === '~>' || (field.matchMode && field.matchMode === 'fuzzy');
+                                if (Array.isArray(resolvedValue)) {
+                                    for (const targetId of resolvedValue) {
+                                        if (typeof targetId === 'string') {
+                                            if (isFuzzy) {
+                                                fuzzyPendingRelations.push({
+                                                    fieldName,
+                                                    targetType: field.relatedType,
+                                                    targetId,
+                                                });
+                                            }
+                                            else {
+                                                pendingRelations.push({
+                                                    fieldName,
+                                                    targetType: field.relatedType,
+                                                    targetId,
+                                                });
+                                            }
+                                        }
+                                    }
+                                }
+                                else if (typeof resolvedValue === 'string') {
+                                    if (isFuzzy) {
+                                        fuzzyPendingRelations.push({
+                                            fieldName,
+                                            targetType: field.relatedType,
+                                            targetId: resolvedValue,
+                                        });
+                                    }
+                                    else {
+                                        pendingRelations.push({
+                                            fieldName,
+                                            targetType: field.relatedType,
+                                            targetId: resolvedValue,
+                                        });
+                                    }
+                                }
+                            }
+                        }
+                    }
+                    else {
+                        // Phase 1: Draft - generate entity with $refs for unresolved references
+                        // Use _skipPromptlessRefs to avoid generating refs for array fields without prompts
+                        // (those are handled by cascade generation when enabled)
+                        const draft = await this.draft(data, {
+                            _skipPromptlessRefs: true,
+                        });
+                        // Phase 2: Resolve - resolve $refs to actual entity IDs
+                        // Inject $id and $type into draft for context during resolution
+                        const draftWithContext = draft;
+                        draftWithContext['$id'] = entityId;
+                        draftWithContext['$type'] = typeName;
+                        const resolved = await this.resolve(draft);
+                        const resolvedData = resolved;
+                        // Extract pending relations from resolved data
+                        // The resolve phase sets metadata fields like ${field}$matchedType and ${field}$score
+                        const refs = draft['$refs'];
+                        if (refs) {
+                            for (const [fieldName, refSpec] of Object.entries(refs)) {
+                                const resolvedValue = resolvedData[fieldName];
+                                if (!resolvedValue)
+                                    continue;
+                                if (Array.isArray(refSpec)) {
+                                    // Array of references
+                                    const resolvedIds = Array.isArray(resolvedValue) ? resolvedValue : [resolvedValue];
+                                    for (let i = 0; i < resolvedIds.length; i++) {
+                                        const targetId = resolvedIds[i];
+                                        const spec = refSpec[i] || refSpec[0];
+                                        if (spec.matchMode === 'fuzzy') {
+                                            const matchedType = resolvedData[`${fieldName}$matchedType`];
+                                            const similarity = resolvedData[`${fieldName}$score`];
+                                            fuzzyPendingRelations.push({
+                                                fieldName,
+                                                targetType: matchedType || spec.type,
+                                                targetId,
+                                                ...(similarity !== undefined && { similarity }),
+                                                ...(matchedType !== undefined && { matchedType }),
+                                            });
+                                        }
+                                        else {
+                                            pendingRelations.push({
+                                                fieldName,
+                                                targetType: spec.type,
+                                                targetId,
+                                            });
+                                        }
+                                    }
+                                }
+                                else {
+                                    // Single reference
+                                    const targetId = resolvedValue;
+                                    if (refSpec.matchMode === 'fuzzy') {
+                                        const matchedType = resolvedData[`${fieldName}$matchedType`];
+                                        const similarity = resolvedData[`${fieldName}$score`];
+                                        fuzzyPendingRelations.push({
+                                            fieldName,
+                                            targetType: matchedType || refSpec.type,
+                                            targetId,
+                                            ...(similarity !== undefined && { similarity }),
+                                            ...(matchedType !== undefined && { matchedType }),
+                                        });
+                                    }
+                                    else {
+                                        pendingRelations.push({
+                                            fieldName,
+                                            targetType: refSpec.type,
+                                            targetId,
+                                        });
+                                    }
+                                }
+                            }
+                        }
+                        // Clean up resolution metadata from the data before further processing
+                        const cleanedData = cleanEntityData(resolvedData);
+                        // Phase 3: Resolve backward fuzzy references (<~)
+                        const backwardResolvedData = await resolveBackwardFuzzy(typeName, cleanedData, entity, schema, provider);
+                        // Phase 4: Generate AI fields based on $instructions and $context
+                        finalData = await generateAIFields(backwardResolvedData, typeName, entity, schema, provider);
+                    }
+                    // Phase 5: Persist the entity
+                    const result = await writeTarget.create(typeName, entityId, finalData);
+                    // Phase 6: Create relationship edges for exact forward references
+                    for (const rel of pendingRelations) {
+                        await writeTarget.relate(typeName, entityId, rel.fieldName, rel.targetType, rel.targetId);
+                    }
+                    // Phase 7: Create relationship edges for fuzzy forward references
+                    const createdEdgeIds = new Set();
+                    for (const rel of fuzzyPendingRelations) {
+                        await writeTarget.relate(typeName, entityId, rel.fieldName, rel.targetType, rel.targetId, {
+                            matchMode: 'fuzzy',
+                            ...(rel.similarity !== undefined && { similarity: rel.similarity }),
+                            ...(rel.matchedType !== undefined && { matchedType: rel.matchedType }),
+                        });
+                        const edgeId = `${typeName}_${rel.fieldName}_${entityId}_${rel.targetId}`;
+                        if (!createdEdgeIds.has(edgeId)) {
+                            createdEdgeIds.add(edgeId);
+                            try {
+                                await writeTarget.create('Edge', edgeId, {
+                                    from: typeName,
+                                    name: rel.fieldName,
+                                    to: rel.targetType,
+                                    direction: 'forward',
+                                    matchMode: 'fuzzy',
+                                    similarity: rel.similarity,
+                                    matchedType: rel.matchedType,
+                                    fromId: entityId,
+                                    toId: rel.targetId,
+                                });
+                            }
+                            catch (error) {
+                                // Only ignore actual duplicate key errors, propagate other errors
+                                if (!isEntityExistsError(error)) {
+                                    throw wrapDatabaseError(error, 'create', 'Edge', edgeId);
+                                }
+                            }
+                        }
+                    }
+                    // Commit the transaction if we used one
+                    if (txn)
+                        await txn.commit();
+                    return hydrateEntity(result, entity, schema, resolveProvider);
+                }
+                catch (innerError) {
+                    // Rollback on any error if we have a transaction
+                    if (txn) {
+                        try {
+                            await txn.rollback();
+                        }
+                        catch {
+                            // Ignore rollback errors
+                        }
+                    }
+                    throw innerError;
+                }
+            }
+            catch (error) {
+                // Wrap provider errors with context
+                if (error instanceof DatabaseError)
+                    throw error;
+                throw wrapDatabaseError(error, 'create', typeName, entityId);
+            }
+        },
+        async update(id, data) {
+            try {
+                const provider = await resolveProvider();
+                const result = await provider.update(typeName, id, data);
+                return hydrateEntity(result, entity, schema, resolveProvider);
+            }
+            catch (error) {
+                if (error instanceof DatabaseError)
+                    throw error;
+                throw wrapDatabaseError(error, 'update', typeName, id);
+            }
+        },
+        async upsert(id, data) {
+            try {
+                const provider = await resolveProvider();
+                const existing = await provider.get(typeName, id);
+                if (existing) {
+                    const result = await provider.update(typeName, id, data);
+                    return hydrateEntity(result, entity, schema, resolveProvider);
+                }
+                const result = await provider.create(typeName, id, data);
+                return hydrateEntity(result, entity, schema, resolveProvider);
+            }
+            catch (error) {
+                if (error instanceof DatabaseError)
+                    throw error;
+                throw wrapDatabaseError(error, 'upsert', typeName, id);
+            }
+        },
+        async delete(id) {
+            try {
+                const provider = await resolveProvider();
+                return provider.delete(typeName, id);
+            }
+            catch (error) {
+                if (error instanceof DatabaseError)
+                    throw error;
+                throw wrapDatabaseError(error, 'delete', typeName, id);
+            }
+        },
+        async forEach(optionsOrCallback, maybeCallback) {
+            const options = typeof optionsOrCallback === 'function' ? undefined : optionsOrCallback;
+            const callback = typeof optionsOrCallback === 'function' ? optionsOrCallback : maybeCallback;
+            const items = await this.list(options);
+            for (const item of items) {
+                await callback(item);
+            }
+        },
+        async semanticSearch(query, options) {
+            const provider = await resolveProvider();
+            if (!hasSemanticSearch(provider)) {
+                throw new CapabilityNotSupportedError('hasSemanticSearch', `Semantic search is not supported by the current provider. ` +
+                    `The provider does not implement the semanticSearch method required for vector similarity search.`, `Use the regular search() method instead, which performs basic text matching.`);
+            }
+            const results = await provider.semanticSearch(typeName, query, options);
+            return Promise.all(results.map((r) => ({
+                ...hydrateEntity(r, entity, schema, resolveProvider),
+                $score: r.$score,
+            })));
+        },
+        async hybridSearch(query, options) {
+            const provider = await resolveProvider();
+            if (!hasHybridSearch(provider)) {
+                throw new CapabilityNotSupportedError('hasHybridSearch', `Hybrid search is not supported by the current provider. ` +
+                    `The provider does not implement the hybridSearch method required for combined FTS and vector search.`, `Use the regular search() method instead, which performs basic text matching.`);
+            }
+            const results = await provider.hybridSearch(typeName, query, options);
+            return Promise.all(results.map((r) => ({
+                ...hydrateEntity(r, entity, schema, resolveProvider),
+                $rrfScore: r.$rrfScore,
+                $ftsRank: r.$ftsRank,
+                $semanticRank: r.$semanticRank,
+                $score: r.$score,
+            })));
+        },
+        async draft(data, options) {
+            const draftData = { ...data, $phase: 'draft' };
+            const refs = {};
+            // Get the raw schema to detect prompt fields and source instructions
+            const rawSchema = entity.schema || {};
+            const sourceInstructions = rawSchema['$instructions'];
+            const hasContextDependencies = Array.isArray(rawSchema['$context']) && rawSchema['$context'].length > 0;
+            for (const [fieldName, field] of entity.fields) {
+                if (draftData[fieldName] !== undefined && draftData[fieldName] !== null) {
+                    continue;
+                }
+                if (field.operator && field.relatedType) {
+                    // Skip optional relation fields - they shouldn't auto-generate
+                    if (field.isOptional)
+                        continue;
+                    // Skip backward references - they're resolved lazily via hydrateEntity
+                    // Backward refs find entities that reference US, not entities we create
+                    if (field.operator === '<-' || field.operator === '<~')
+                        continue;
+                    // Relationship field with operator
+                    const matchMode = field.matchMode ?? (field.operator.includes('~') ? 'fuzzy' : 'exact');
+                    if (field.isArray) {
+                        // Get hint value for array fuzzy matching (e.g., categoriesHint for categories field)
+                        const hintKey = `${fieldName}Hint`;
+                        const hintValue = data[hintKey];
+                        // Get fuzzy threshold from entity schema
+                        const threshold = field.threshold ?? getFuzzyThreshold(entity);
+                        // If hint is an array, create one ref spec per hint item
+                        // Skip promptless fields only when _skipPromptlessRefs is set (internal create() without cascade)
+                        const shouldSkipPromptless = options?._skipPromptlessRefs && !field.prompt;
+                        const hints = Array.isArray(hintValue)
+                            ? hintValue
+                            : hintValue
+                                ? [hintValue]
+                                : shouldSkipPromptless
+                                    ? []
+                                    : [
+                                        generateNaturalLanguageContent(fieldName, field.prompt, field.relatedType, data),
+                                    ];
+                        const refSpecs = hints.map((hint) => {
+                            const generatedText = String(hint);
+                            const spec = {
+                                field: fieldName,
+                                operator: field.operator,
+                                type: field.relatedType,
+                                matchMode,
+                                resolved: false,
+                                ...(field.unionTypes !== undefined && { unionTypes: field.unionTypes }),
+                                ...(field.prompt !== undefined && { prompt: field.prompt }),
+                                ...(generatedText !== undefined && { generatedText }),
+                                ...(sourceInstructions !== undefined && { sourceInstructions }),
+                                ...(threshold !== undefined && { threshold }),
+                            };
+                            return spec;
+                        });
+                        // Store the combined generated text for the draft display
+                        draftData[fieldName] = hints.map(String).join(', ');
+                        refs[fieldName] = refSpecs;
+                        if (options?.stream && options.onChunk) {
+                            for (const spec of refSpecs) {
+                                if (spec.generatedText) {
+                                    options.onChunk(spec.generatedText);
+                                }
+                            }
+                        }
+                    }
+                    else {
+                        // Get hint value for fuzzy matching (e.g., contentHint for content field)
+                        const hintKey = `${fieldName}Hint`;
+                        const hintValue = data[hintKey];
+                        // Get fuzzy threshold from entity schema
+                        const threshold = field.threshold ?? getFuzzyThreshold(entity);
+                        // Use hint if available, otherwise generate natural language content
+                        const generatedText = hintValue ||
+                            generateNaturalLanguageContent(fieldName, field.prompt, field.relatedType, data);
+                        draftData[fieldName] = generatedText;
+                        const spec = {
+                            field: fieldName,
+                            operator: field.operator,
+                            type: field.relatedType,
+                            matchMode,
+                            resolved: false,
+                            ...(field.unionTypes !== undefined && { unionTypes: field.unionTypes }),
+                            ...(field.prompt !== undefined && { prompt: field.prompt }),
+                            ...(generatedText !== undefined && { generatedText }),
+                            ...(sourceInstructions !== undefined && { sourceInstructions }),
+                            ...(threshold !== undefined && { threshold }),
+                        };
+                        refs[fieldName] = spec;
+                        if (options?.stream && options.onChunk) {
+                            options.onChunk(generatedText);
+                        }
+                    }
+                }
+                else if (!field.isRelation) {
+                    // Non-relationship field - check if it's a prompt field
+                    const isPrompt = isPromptField(field);
+                    if (isPrompt && !hasContextDependencies) {
+                        // Generate content for prompt field using the type as the prompt
+                        // NOTE: Skip generation when entity has $context dependencies, as those fields
+                        // need the pre-fetched context to generate properly (done in generateAIFields)
+                        const generatedText = generateContextAwareValue(fieldName, typeName, field.type, field.type, data);
+                        draftData[fieldName] = generatedText;
+                        if (options?.stream && options.onChunk) {
+                            options.onChunk(generatedText);
+                        }
+                    }
+                }
+            }
+            draftData['$refs'] = refs;
+            return draftData;
+        },
+        async resolve(draft, options) {
+            // Draft<T> interface requires $phase: 'draft', so we can access it directly
+            if (draft.$phase !== 'draft') {
+                throw new Error('Cannot resolve entity: not a draft (missing $phase: "draft")');
+            }
+            const provider = await resolveProvider();
+            const resolved = { ...draft };
+            const errors = [];
+            delete resolved['$refs'];
+            resolved['$phase'] = 'resolved';
+            const refs = draft.$refs;
+            for (const [fieldName, refSpec] of Object.entries(refs)) {
+                try {
+                    if (Array.isArray(refSpec)) {
+                        const resolvedIds = [];
+                        for (const spec of refSpec) {
+                            const resolvedId = await resolveReferenceSpec(spec, resolved, schema, provider, generateContextAwareValue, generateEntity);
+                            if (resolvedId) {
+                                resolvedIds.push(resolvedId);
+                                options?.onResolved?.(fieldName, resolvedId);
+                            }
+                        }
+                        resolved[fieldName] = resolvedIds;
+                    }
+                    else {
+                        const resolvedId = await resolveReferenceSpec(refSpec, resolved, schema, provider, generateContextAwareValue, generateEntity);
+                        if (resolvedId) {
+                            resolved[fieldName] = resolvedId;
+                            options?.onResolved?.(fieldName, resolvedId);
+                        }
+                    }
+                }
+                catch (err) {
+                    const errorMsg = err instanceof Error ? err.message : String(err);
+                    if (options?.onError === 'skip') {
+                        errors.push({ field: fieldName, error: errorMsg });
+                    }
+                    else {
+                        throw err;
+                    }
+                }
+            }
+            if (errors.length > 0 || options?.onError === 'skip') {
+                // resolved is typed as Record<string, unknown>, so we can assign $errors directly
+                resolved['$errors'] = errors;
+            }
+            return resolved;
+        },
+    };
+}
+// =============================================================================
+// Edge Entity Operations Factory
+// =============================================================================
+/**
+ * Create specialized operations for the Edge entity type
+ *
+ * Edge entities are auto-generated from schema relationships and have
+ * restricted write operations (no manual create/update/delete).
+ *
+ * @param schemaEdgeRecords - Edge records derived from the schema
+ * @param getProvider - Function to get the database provider
+ * @returns EntityOperations for Edge type
+ */
+/**
+ * Create specialized operations for the Noun entity type
+ *
+ * Noun entities are auto-generated from schema entity types and have
+ * restricted write operations (no manual create/update/delete).
+ *
+ * @param nounRecords - Noun records derived from the schema entity types
+ * @returns EntityOperations for Noun type
+ */
+export function createNounEntityOperations(nounRecords) {
+    const addNounMetadata = (n) => ({
+        ...n,
+        $id: n['$id'] || n['name'],
+        $type: 'Noun',
+    });
+    return {
+        async get(id) {
+            return nounRecords.find((n) => n['name'] === id || n['$id'] === id) ?? null;
+        },
+        async list(options) {
+            let results = [...nounRecords];
+            if (options?.where) {
+                results = applyWhereFilter(results, options.where);
+            }
+            results = applyPagination(results, options?.offset, options?.limit);
+            return results.map(addNounMetadata);
+        },
+        async find(where) {
+            return applyWhereFilter([...nounRecords], where).map(addNounMetadata);
+        },
+        async search(query) {
+            const queryLower = query.toLowerCase();
+            return nounRecords
+                .filter((n) => String(n['name']).toLowerCase().includes(queryLower) ||
+                String(n['singular']).toLowerCase().includes(queryLower) ||
+                String(n['plural']).toLowerCase().includes(queryLower) ||
+                String(n['description'] || '')
+                    .toLowerCase()
+                    .includes(queryLower))
+                .map(addNounMetadata);
+        },
+        async create() {
+            throw new Error('Cannot manually create Noun records - they are auto-generated from schema');
+        },
+        async update() {
+            throw new Error('Cannot manually update Noun records - they are auto-generated from schema');
+        },
+        async upsert() {
+            throw new Error('Cannot manually upsert Noun records - they are auto-generated from schema');
+        },
+        async delete() {
+            throw new Error('Cannot manually delete Noun records - they are auto-generated from schema');
+        },
+        async forEach(optionsOrCallback, maybeCallback) {
+            const options = typeof optionsOrCallback === 'function' ? undefined : optionsOrCallback;
+            const callback = typeof optionsOrCallback === 'function' ? optionsOrCallback : maybeCallback;
+            for (const item of await this.list(options)) {
+                await callback(item);
+            }
+        },
+        async semanticSearch() {
+            return [];
+        },
+        async hybridSearch() {
+            return [];
+        },
+    };
+}
+/**
+ * Create specialized operations for the Verb entity type
+ *
+ * Verb entities are the standard verb definitions (create, update, delete, etc.)
+ * and any custom verbs defined through the verbs API.
+ *
+ * @param verbRecords - Verb records with conjugation forms
+ * @returns EntityOperations for Verb type
+ */
+export function createVerbEntityOperations(verbRecords) {
+    const addVerbMetadata = (v) => ({
+        ...v,
+        $id: v['$id'] || v['action'],
+        $type: 'Verb',
+    });
+    return {
+        async get(id) {
+            return verbRecords.find((v) => v['action'] === id || v['$id'] === id) ?? null;
+        },
+        async list(options) {
+            let results = [...verbRecords];
+            if (options?.where) {
+                results = applyWhereFilter(results, options.where);
+            }
+            results = applyPagination(results, options?.offset, options?.limit);
+            return results.map(addVerbMetadata);
+        },
+        async find(where) {
+            return applyWhereFilter([...verbRecords], where).map(addVerbMetadata);
+        },
+        async search(query) {
+            const queryLower = query.toLowerCase();
+            return verbRecords
+                .filter((v) => String(v['action']).toLowerCase().includes(queryLower) ||
+                String(v['actor'] || '')
+                    .toLowerCase()
+                    .includes(queryLower) ||
+                String(v['activity'] || '')
+                    .toLowerCase()
+                    .includes(queryLower) ||
+                String(v['description'] || '')
+                    .toLowerCase()
+                    .includes(queryLower))
+                .map(addVerbMetadata);
+        },
+        async create() {
+            throw new Error('Cannot manually create Verb records - use verbs.define() instead');
+        },
+        async update() {
+            throw new Error('Cannot manually update Verb records - use verbs.define() instead');
+        },
+        async upsert() {
+            throw new Error('Cannot manually upsert Verb records - use verbs.define() instead');
+        },
+        async delete() {
+            throw new Error('Cannot manually delete Verb records');
+        },
+        async forEach(optionsOrCallback, maybeCallback) {
+            const options = typeof optionsOrCallback === 'function' ? undefined : optionsOrCallback;
+            const callback = typeof optionsOrCallback === 'function' ? optionsOrCallback : maybeCallback;
+            for (const item of await this.list(options)) {
+                await callback(item);
+            }
+        },
+        async semanticSearch() {
+            return [];
+        },
+        async hybridSearch() {
+            return [];
+        },
+    };
+}
+export function createEdgeEntityOperations(schemaEdgeRecords, getProvider) {
+    const addEdgeMetadata = (e) => ({
+        ...e,
+        $id: e['$id'] || `${e['from']}:${e['name']}`,
+        $type: 'Edge',
+    });
+    /**
+     * Get runtime edges from the provider.
+     * Returns empty array for not-found errors (Edge table may not exist yet).
+     */
+    async function getRuntimeEdges(suppressErrors) {
+        try {
+            const provider = await getProvider();
+            return await provider.list('Edge');
+        }
+        catch (error) {
+            if (isNotFoundError(error) || suppressErrors) {
+                return [];
+            }
+            throw wrapDatabaseError(error, 'list', 'Edge');
+        }
+    }
+    /**
+     * Merge schema edges with runtime edges, preferring runtime versions.
+     */
+    async function getAllEdges(suppressErrors) {
+        const runtimeEdges = await getRuntimeEdges(suppressErrors);
+        const runtimeEdgeKeys = new Set(runtimeEdges.map((e) => `${e['from']}:${e['name']}`));
+        const filteredSchemaEdges = schemaEdgeRecords.filter((e) => {
+            const key = `${e['from']}:${e['name']}`;
+            const hasRuntimeVersion = runtimeEdgeKeys.has(key);
+            // Exclude schema edges that have runtime versions (unless it's a fuzzy match override)
+            return !hasRuntimeVersion || (hasRuntimeVersion && e['matchMode'] !== 'fuzzy');
+        });
+        return [...filteredSchemaEdges, ...runtimeEdges];
+    }
+    return {
+        async get(id) {
+            const runtimeEdges = await getRuntimeEdges();
+            const runtimeMatch = runtimeEdges.find((e) => e['$id'] === id || `${e['from']}:${e['name']}` === id);
+            if (runtimeMatch)
+                return { ...runtimeMatch, $type: 'Edge' };
+            return schemaEdgeRecords.find((e) => `${e['from']}:${e['name']}` === id) ?? null;
+        },
+        async list(options) {
+            try {
+                let results = await getAllEdges(options?.suppressErrors);
+                if (options?.where) {
+                    results = applyWhereFilter(results, options.where);
+                }
+                return results.map(addEdgeMetadata);
+            }
+            catch (error) {
+                if (options?.onError) {
+                    const fallback = options.onError(error instanceof Error ? error : new Error(String(error)));
+                    return (fallback ?? []);
+                }
+                throw error;
+            }
+        },
+        async find(where) {
+            return applyWhereFilter(await getAllEdges(), where).map(addEdgeMetadata);
+        },
+        async search(query) {
+            const queryLower = query.toLowerCase();
+            return (await getAllEdges())
+                .filter((e) => String(e['from']).toLowerCase().includes(queryLower) ||
+                String(e['name']).toLowerCase().includes(queryLower) ||
+                String(e['to']).toLowerCase().includes(queryLower))
+                .map(addEdgeMetadata);
+        },
+        async create() {
+            throw new Error('Cannot manually create Edge records - they are auto-generated');
+        },
+        async update() {
+            throw new Error('Cannot manually update Edge records - they are auto-generated');
+        },
+        async upsert() {
+            throw new Error('Cannot manually upsert Edge records - they are auto-generated');
+        },
+        async delete() {
+            throw new Error('Cannot manually delete Edge records - they are auto-generated');
+        },
+        async forEach(optionsOrCallback, maybeCallback) {
+            const options = typeof optionsOrCallback === 'function' ? undefined : optionsOrCallback;
+            const callback = typeof optionsOrCallback === 'function' ? optionsOrCallback : maybeCallback;
+            for (const item of await this.list(options)) {
+                await callback(item);
+            }
+        },
+        async semanticSearch() {
+            return [];
+        },
+        async hybridSearch() {
+            return [];
+        },
+    };
+}
+//# sourceMappingURL=entity-operations.js.map