ai-database 2.0.2 → 2.1.1

package/dist/schema/index.js

@@ -0,0 +1,1211 @@
+/**
+ * Schema-first Database Definition
+ *
+ * Declarative schema with automatic bi-directional relationships.
+ * Uses mdxld conventions for entity structure.
+ *
+ * @example
+ * ```ts
+ * const { db } = DB({
+ *   Post: {
+ *     title: 'string',
+ *     author: 'Author.posts',     // one-to-many: Post.author -> Author, Author.posts -> Post[]
+ *     tags: ['Tag.posts'],        // many-to-many: Post.tags -> Tag[], Tag.posts -> Post[]
+ *   },
+ *   Author: {
+ *     name: 'string',
+ *     // posts: Post[] auto-created from backref
+ *   },
+ *   Tag: {
+ *     name: 'string',
+ *     // posts: Post[] auto-created from backref
+ *   }
+ * })
+ *
+ * // Typed access
+ * const post = await db.Post.get('123')
+ * post.author  // Author (single)
+ * post.tags    // Tag[] (array)
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { DBPromise, wrapEntityOperations, setSchemaRelationInfo } from '../ai-promise-db.js';
+// Re-export parse functions
+export { parseOperator, parseField, parseSchema, isPrimitiveType } from './parse.js';
+export { setProvider, resolveProvider, hasSemanticSearch, hasHybridSearch, hasEventsAPI, hasActionsAPI, hasArtifactsAPI, hasEmbeddingsConfig, } from './provider.js';
+// Re-export resolve functions
+export { isEntityId, inferTypeFromField, resolveContextPath, resolveInstructions, prefetchContext, isPromptField, resolveNestedPending, resolveReferenceSpec, hydrateEntity, } from './resolve.js';
+// Re-export cascade functions
+export { generateContextAwareValue, generateAIFields, generateEntity, resolveForwardExact, generateNaturalLanguageContent, } from './cascade.js';
+// Re-export semantic functions
+export { resolveBackwardFuzzy, resolveForwardFuzzy } from './semantic.js';
+import { Verbs, parseUrl } from '../types.js';
+import { inferNoun, getTypeMeta, conjugate } from '../linguistic.js';
+import { parseSchema } from './parse.js';
+import { resolveProvider, hasSemanticSearch, hasHybridSearch, hasEventsAPI, hasActionsAPI, hasArtifactsAPI, hasEmbeddingsConfig, } from './provider.js';
+import { hydrateEntity, resolveReferenceSpec } from './resolve.js';
+import { resolveForwardExact, generateAIFields, generateContextAwareValue, generateNaturalLanguageContent } from './cascade.js';
+import { resolveBackwardFuzzy, resolveForwardFuzzy } from './semantic.js';
+// =============================================================================
+// Noun/Verb Helpers
+// =============================================================================
+/**
+ * Create a Noun definition with type inference
+ */
+export function defineNoun(noun) {
+    return noun;
+}
+/**
+ * Create a Verb definition with type inference
+ */
+export function defineVerb(verb) {
+    return verb;
+}
+/**
+ * Convert a Noun to an EntitySchema for use with DB()
+ */
+export function nounToSchema(noun) {
+    const schema = {};
+    // Add properties
+    if (noun.properties) {
+        for (const [name, prop] of Object.entries(noun.properties)) {
+            let type = prop.type;
+            if (prop.array)
+                type = `${type}[]`;
+            if (prop.optional)
+                type = `${type}?`;
+            schema[name] = type;
+        }
+    }
+    // Add relationships
+    if (noun.relationships) {
+        for (const [name, rel] of Object.entries(noun.relationships)) {
+            const baseType = rel.type.replace('[]', '');
+            const isArray = rel.type.endsWith('[]');
+            if (rel.backref) {
+                schema[name] = isArray ? [`${baseType}.${rel.backref}`] : `${baseType}.${rel.backref}`;
+            }
+            else {
+                schema[name] = rel.type;
+            }
+        }
+    }
+    return schema;
+}
+// =============================================================================
+// Built-in Schema Types
+// =============================================================================
+/**
+ * Built-in Thing schema - base type for all entities
+ */
+export const ThingSchema = {
+    type: 'Noun.things',
+};
+/**
+ * Built-in Noun schema for storing type definitions
+ */
+export const NounSchema = {
+    name: 'string',
+    singular: 'string',
+    plural: 'string',
+    slug: 'string',
+    slugPlural: 'string',
+    description: 'string?',
+    properties: 'json?',
+    relationships: 'json?',
+    actions: 'json?',
+    events: 'json?',
+    metadata: 'json?',
+};
+/**
+ * Built-in Verb schema for storing action definitions
+ */
+export const VerbSchema = {
+    action: 'string',
+    actor: 'string?',
+    act: 'string?',
+    activity: 'string?',
+    result: 'string?',
+    reverse: 'json?',
+    inverse: 'string?',
+    description: 'string?',
+};
+/**
+ * Built-in Edge schema for relationships between types
+ */
+export const EdgeSchema = {
+    from: 'string',
+    name: 'string',
+    to: 'string',
+    backref: 'string?',
+    cardinality: 'string',
+    direction: 'string',
+    matchMode: 'string?',
+    required: 'boolean?',
+    description: 'string?',
+};
+/**
+ * System types that are auto-created in every database
+ */
+export const SystemSchema = {
+    Thing: ThingSchema,
+    Noun: NounSchema,
+    Verb: VerbSchema,
+    Edge: EdgeSchema,
+};
+/**
+ * Create Edge records from schema relationships
+ */
+export function createEdgeRecords(typeName, schema, parsedEntity) {
+    const edges = [];
+    for (const [fieldName, field] of parsedEntity.fields) {
+        if (field.isRelation && field.relatedType) {
+            const direction = field.direction ?? 'forward';
+            const matchMode = field.matchMode ?? 'exact';
+            const isBackward = direction === 'backward';
+            const from = isBackward ? field.relatedType : typeName;
+            const to = isBackward ? typeName : field.relatedType;
+            let cardinality;
+            if (field.isArray) {
+                cardinality = field.backref ? 'many-to-many' : 'one-to-many';
+            }
+            else {
+                cardinality = 'many-to-one';
+            }
+            edges.push({
+                from,
+                name: fieldName,
+                to,
+                backref: field.backref,
+                cardinality,
+                direction,
+                matchMode,
+            });
+        }
+    }
+    return edges;
+}
+/**
+ * Create a Noun record from a type name and optional schema
+ */
+export function createNounRecord(typeName, schema, nounDef) {
+    const meta = getTypeMeta(typeName);
+    const inferred = inferNoun(typeName);
+    return {
+        name: typeName,
+        singular: nounDef?.singular ?? meta.singular,
+        plural: nounDef?.plural ?? meta.plural,
+        slug: meta.slug,
+        slugPlural: meta.slugPlural,
+        description: nounDef?.description,
+        properties: nounDef?.properties ?? (schema ? schemaToProperties(schema) : undefined),
+        relationships: nounDef?.relationships,
+        actions: nounDef?.actions ?? inferred.actions,
+        events: nounDef?.events ?? inferred.events,
+        metadata: nounDef?.metadata,
+    };
+}
+/**
+ * Convert EntitySchema to NounProperty format
+ */
+function schemaToProperties(schema) {
+    const properties = {};
+    for (const [name, def] of Object.entries(schema)) {
+        const defStr = Array.isArray(def) ? def[0] : def;
+        const isOptional = defStr.endsWith('?');
+        const isArray = defStr.endsWith('[]') || Array.isArray(def);
+        const baseType = defStr.replace(/[\?\[\]]/g, '').split('.')[0];
+        properties[name] = {
+            type: baseType,
+            optional: isOptional,
+            array: isArray,
+        };
+    }
+    return properties;
+}
+// =============================================================================
+// Natural Language Query Implementation
+// =============================================================================
+let nlQueryGenerator = null;
+/**
+ * Set the AI generator for natural language queries
+ */
+export function setNLQueryGenerator(generator) {
+    nlQueryGenerator = generator;
+}
+function buildNLQueryContext(schema, targetType) {
+    const types = [];
+    for (const [name, entity] of schema.entities) {
+        const fields = [];
+        const relationships = [];
+        for (const [fieldName, field] of entity.fields) {
+            if (field.isRelation && field.relatedType) {
+                relationships.push({
+                    name: fieldName,
+                    to: field.relatedType,
+                    cardinality: field.isArray ? 'many' : 'one',
+                });
+            }
+            else {
+                fields.push(fieldName);
+            }
+        }
+        const meta = getTypeMeta(name);
+        types.push({
+            name,
+            singular: meta.singular,
+            plural: meta.plural,
+            fields,
+            relationships,
+        });
+    }
+    return { types, targetType };
+}
+async function executeNLQuery(question, schema, targetType) {
+    if (!nlQueryGenerator) {
+        const provider = await resolveProvider();
+        const results = [];
+        // Simple heuristic for common "list all" patterns in fallback mode
+        const lowerQuestion = question.toLowerCase().trim();
+        const isListAllQuery = /^(show|list|get|find|display)\s+(all|every|the)?\s*/i.test(lowerQuestion) ||
+            lowerQuestion === '' ||
+            /\ball\b/i.test(lowerQuestion);
+        if (targetType) {
+            if (isListAllQuery) {
+                // For "show all X" queries, just list everything
+                const listResults = await provider.list(targetType);
+                results.push(...listResults);
+            }
+            else {
+                const searchResults = await provider.search(targetType, question);
+                results.push(...searchResults);
+            }
+        }
+        else {
+            for (const [typeName] of schema.entities) {
+                if (isListAllQuery) {
+                    const listResults = await provider.list(typeName);
+                    results.push(...listResults);
+                }
+                else {
+                    const searchResults = await provider.search(typeName, question);
+                    results.push(...searchResults);
+                }
+            }
+        }
+        return {
+            interpretation: `Search for "${question}"`,
+            confidence: 0.5,
+            results,
+            explanation: 'Fallback to keyword search (no AI generator configured)',
+        };
+    }
+    const context = buildNLQueryContext(schema, targetType);
+    const plan = await nlQueryGenerator(question, context);
+    const provider = await resolveProvider();
+    const results = [];
+    for (const typeName of plan.types) {
+        let typeResults;
+        if (plan.search) {
+            typeResults = await provider.search(typeName, plan.search, {
+                where: plan.filters,
+            });
+        }
+        else {
+            typeResults = await provider.list(typeName, {
+                where: plan.filters,
+            });
+        }
+        results.push(...typeResults);
+    }
+    return {
+        interpretation: plan.interpretation,
+        confidence: plan.confidence,
+        results,
+        query: JSON.stringify({ types: plan.types, filters: plan.filters, search: plan.search }),
+    };
+}
+function createNLQueryFn(schema, typeName) {
+    return async (strings, ...values) => {
+        const question = strings.reduce((acc, str, i) => {
+            return acc + str + (values[i] !== undefined ? String(values[i]) : '');
+        }, '');
+        return executeNLQuery(question, schema, typeName);
+    };
+}
+// =============================================================================
+// Edge Entity Operations
+// =============================================================================
+function createEdgeEntityOperations(schemaEdgeRecords, getProvider) {
+    async function getRuntimeEdges() {
+        try {
+            const provider = await getProvider();
+            const runtimeEdges = await provider.list('Edge');
+            return runtimeEdges;
+        }
+        catch {
+            return [];
+        }
+    }
+    async function getAllEdges() {
+        const runtimeEdges = await getRuntimeEdges();
+        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);
+            if (hasRuntimeVersion && e.matchMode === 'fuzzy') {
+                return false;
+            }
+            return !hasRuntimeVersion;
+        });
+        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) {
+            let results = await getAllEdges();
+            if (options?.where) {
+                for (const [key, value] of Object.entries(options.where)) {
+                    results = results.filter(e => e[key] === value);
+                }
+            }
+            return results.map(e => ({
+                ...e,
+                $id: e.$id || `${e.from}:${e.name}`,
+                $type: 'Edge',
+            }));
+        },
+        async find(where) {
+            let results = await getAllEdges();
+            for (const [key, value] of Object.entries(where)) {
+                results = results.filter(e => e[key] === value);
+            }
+            return results.map(e => ({
+                ...e,
+                $id: e.$id || `${e.from}:${e.name}`,
+                $type: 'Edge',
+            }));
+        },
+        async search(query) {
+            const allEdges = await getAllEdges();
+            const queryLower = query.toLowerCase();
+            return allEdges
+                .filter(e => String(e.from).toLowerCase().includes(queryLower) ||
+                String(e.name).toLowerCase().includes(queryLower) ||
+                String(e.to).toLowerCase().includes(queryLower))
+                .map(e => ({
+                ...e,
+                $id: e.$id || `${e.from}:${e.name}`,
+                $type: 'Edge',
+            }));
+        },
+        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;
+            const items = await this.list(options);
+            for (const item of items) {
+                await callback(item);
+            }
+        },
+        async semanticSearch() {
+            return [];
+        },
+        async hybridSearch() {
+            return [];
+        },
+    };
+}
+// =============================================================================
+// Entity Operations Factory
+// =============================================================================
+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) {
+            const provider = await resolveProvider();
+            const results = await provider.list(typeName, options);
+            return Promise.all(results.map((r) => hydrateEntity(r, entity, schema, resolveProvider)));
+        },
+        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) {
+            const provider = await resolveProvider();
+            const providedId = typeof idOrData === 'string' ? idOrData : undefined;
+            const data = typeof idOrData === 'string'
+                ? maybeData
+                : idOrData;
+            const entityId = providedId || crypto.randomUUID();
+            const { data: resolvedData, pendingRelations } = await resolveForwardExact(typeName, data, entity, schema, provider, entityId);
+            const { data: fuzzyResolvedData, pendingRelations: fuzzyPendingRelations } = await resolveForwardFuzzy(typeName, resolvedData, entity, schema, provider, entityId);
+            const backwardResolvedData = await resolveBackwardFuzzy(typeName, fuzzyResolvedData, entity, schema, provider);
+            const finalData = await generateAIFields(backwardResolvedData, typeName, entity, schema, provider);
+            const result = await provider.create(typeName, entityId, finalData);
+            for (const rel of pendingRelations) {
+                await provider.relate(typeName, entityId, rel.fieldName, rel.targetType, rel.targetId);
+            }
+            const createdEdgeIds = new Set();
+            for (const rel of fuzzyPendingRelations) {
+                await provider.relate(typeName, entityId, rel.fieldName, rel.targetType, rel.targetId, {
+                    matchMode: 'fuzzy',
+                    similarity: rel.similarity
+                });
+                const edgeId = `${typeName}:${rel.fieldName}:${entityId}:${rel.targetId}`;
+                if (!createdEdgeIds.has(edgeId)) {
+                    createdEdgeIds.add(edgeId);
+                    try {
+                        await provider.create('Edge', edgeId, {
+                            from: typeName,
+                            name: rel.fieldName,
+                            to: rel.targetType,
+                            direction: 'forward',
+                            matchMode: 'fuzzy',
+                            similarity: rel.similarity,
+                            fromId: entityId,
+                            toId: rel.targetId,
+                        });
+                    }
+                    catch {
+                        // Edge already exists
+                    }
+                }
+            }
+            return hydrateEntity(result, entity, schema, resolveProvider);
+        },
+        async update(id, data) {
+            const provider = await resolveProvider();
+            const result = await provider.update(typeName, id, data);
+            return hydrateEntity(result, entity, schema, resolveProvider);
+        },
+        async upsert(id, data) {
+            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);
+        },
+        async delete(id) {
+            const provider = await resolveProvider();
+            return provider.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)) {
+                const results = await provider.semanticSearch(typeName, query, options);
+                return Promise.all(results.map((r) => ({
+                    ...hydrateEntity(r, entity, schema, resolveProvider),
+                    $score: r.$score,
+                })));
+            }
+            return [];
+        },
+        async hybridSearch(query, options) {
+            const provider = await resolveProvider();
+            if (hasHybridSearch(provider)) {
+                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,
+                })));
+            }
+            return [];
+        },
+        async draft(data, options) {
+            const draftData = { ...data, $phase: 'draft' };
+            const refs = {};
+            for (const [fieldName, field] of entity.fields) {
+                if (draftData[fieldName] !== undefined && draftData[fieldName] !== null) {
+                    continue;
+                }
+                if (field.operator && field.relatedType) {
+                    const matchMode = field.matchMode ?? (field.operator.includes('~') ? 'fuzzy' : 'exact');
+                    if (field.isArray) {
+                        const generatedText = generateNaturalLanguageContent(fieldName, field.prompt, field.relatedType, data);
+                        draftData[fieldName] = generatedText;
+                        const refSpec = {
+                            field: fieldName,
+                            operator: field.operator,
+                            type: field.relatedType,
+                            matchMode,
+                            resolved: false,
+                            prompt: field.prompt,
+                            generatedText,
+                        };
+                        refs[fieldName] = [refSpec];
+                        if (options?.stream && options.onChunk) {
+                            options.onChunk(generatedText);
+                        }
+                    }
+                    else {
+                        const generatedText = generateNaturalLanguageContent(fieldName, field.prompt, field.relatedType, data);
+                        draftData[fieldName] = generatedText;
+                        refs[fieldName] = {
+                            field: fieldName,
+                            operator: field.operator,
+                            type: field.relatedType,
+                            matchMode,
+                            resolved: false,
+                            prompt: field.prompt,
+                            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);
+                            if (resolvedId) {
+                                resolvedIds.push(resolvedId);
+                                options?.onResolved?.(fieldName, resolvedId);
+                            }
+                        }
+                        resolved[fieldName] = resolvedIds;
+                    }
+                    else {
+                        const resolvedId = await resolveReferenceSpec(refSpec, resolved, schema, provider, generateContextAwareValue);
+                        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;
+        },
+    };
+}
+// =============================================================================
+// DB Factory
+// =============================================================================
+/**
+ * Create a typed database from a schema definition
+ */
+export function DB(schema, options) {
+    const parsedSchema = parseSchema(schema);
+    // Add Edge entity to the parsed schema
+    const edgeEntity = {
+        name: 'Edge',
+        fields: new Map([
+            ['from', { name: 'from', type: 'string', isArray: false, isOptional: false, isRelation: false }],
+            ['name', { name: 'name', type: 'string', isArray: false, isOptional: false, isRelation: false }],
+            ['to', { name: 'to', type: 'string', isArray: false, isOptional: false, isRelation: false }],
+            ['backref', { name: 'backref', type: 'string', isArray: false, isOptional: true, isRelation: false }],
+            ['cardinality', { name: 'cardinality', type: 'string', isArray: false, isOptional: false, isRelation: false }],
+            ['direction', { name: 'direction', type: 'string', isArray: false, isOptional: false, isRelation: false }],
+            ['matchMode', { name: 'matchMode', type: 'string', isArray: false, isOptional: true, isRelation: false }],
+        ]),
+    };
+    parsedSchema.entities.set('Edge', edgeEntity);
+    // Configure provider with embeddings settings if provided
+    if (options?.embeddings) {
+        resolveProvider().then(provider => {
+            if (hasEmbeddingsConfig(provider)) {
+                provider.setEmbeddingsConfig(options.embeddings);
+            }
+        });
+    }
+    // Collect all edge records from the schema
+    const allEdgeRecords = [];
+    for (const [entityName, entity] of parsedSchema.entities) {
+        if (entityName !== 'Edge') {
+            const edgeRecords = createEdgeRecords(entityName, schema[entityName] ?? {}, entity);
+            allEdgeRecords.push(...edgeRecords);
+        }
+    }
+    // Build and set schema relation info for batch loading
+    // Maps entityType -> fieldName -> relatedType
+    const relationInfo = new Map();
+    for (const [entityName, entity] of parsedSchema.entities) {
+        const fieldRelations = new Map();
+        for (const [fieldName, field] of entity.fields) {
+            if (field.isRelation && field.relatedType) {
+                fieldRelations.set(fieldName, field.relatedType);
+            }
+        }
+        if (fieldRelations.size > 0) {
+            relationInfo.set(entityName, fieldRelations);
+        }
+    }
+    setSchemaRelationInfo(relationInfo);
+    // Create Actions API early for internal use by wrapEntityOperations
+    // This API adapts DBAction to ForEachActionsAPI interface
+    const actionsAPI = {
+        async create(data) {
+            const provider = await resolveProvider();
+            if (hasActionsAPI(provider)) {
+                const action = await provider.createAction(data);
+                return { id: action.id };
+            }
+            throw new Error('Provider does not support actions');
+        },
+        async get(id) {
+            const provider = await resolveProvider();
+            if (hasActionsAPI(provider)) {
+                const action = await provider.getAction(id);
+                if (!action)
+                    return null;
+                // Adapt DBAction to ForEachActionState
+                return {
+                    id: action.id,
+                    type: action.action ?? action.type ?? 'unknown',
+                    status: action.status,
+                    progress: action.progress,
+                    total: action.total,
+                    data: action.objectData ?? {},
+                    result: action.result,
+                    error: action.error,
+                };
+            }
+            return null;
+        },
+        async update(id, updates) {
+            const provider = await resolveProvider();
+            if (hasActionsAPI(provider)) {
+                await provider.updateAction(id, {
+                    status: updates.status,
+                    progress: updates.progress,
+                    // ForEachResult needs to be converted to Record<string, unknown> for DBAction.result
+                    result: updates.result,
+                    error: updates.error,
+                });
+                return;
+            }
+            throw new Error('Provider does not support actions');
+        },
+    };
+    // Create entity operations
+    // Using Record<string, unknown> with [key: string]: unknown allows flexible method access
+    // while being safer than `any`. The actual operations implement EntityOperations<T>
+    // but we lose the generic when storing by entity name.
+    //
+    // IMPORTANT: Each entity must be both:
+    // 1. Callable as a tagged template literal: db.Lead`query`
+    // 2. An object with methods: db.Lead.get(), db.Lead.list(), etc.
+    //
+    // We achieve this by creating a function and attaching methods to it.
+    const entityOperations = {};
+    const eventHandlersForOps = new Map();
+    function emitInternalEventForOps(eventType, data) {
+        const handlers = eventHandlersForOps.get(eventType);
+        if (handlers) {
+            for (const handler of handlers) {
+                try {
+                    handler(data);
+                }
+                catch (e) {
+                    console.error(`Error in event handler for ${eventType}:`, e);
+                }
+            }
+        }
+    }
+    /**
+     * Make entity operations callable as a tagged template literal
+     * This allows both: db.Lead.get('id') and db.Lead`natural language query`
+     */
+    function makeCallableEntityOps(ops, entityName) {
+        // Create the NL query function for this entity type
+        const nlQueryFn = createNLQueryFn(parsedSchema, entityName);
+        // Create a function that acts as the tagged template literal handler
+        const callableOps = function (strings, ...values) {
+            return nlQueryFn(strings, ...values);
+        };
+        // Copy all methods from the wrapped operations to the function
+        Object.assign(callableOps, ops);
+        return callableOps;
+    }
+    for (const [entityName, entity] of parsedSchema.entities) {
+        if (entityName === 'Edge') {
+            const edgeOps = createEdgeEntityOperations(allEdgeRecords, resolveProvider);
+            const wrappedEdgeOps = wrapEntityOperations(entityName, edgeOps, actionsAPI);
+            entityOperations[entityName] = makeCallableEntityOps(wrappedEdgeOps, entityName);
+        }
+        else {
+            const baseOps = createEntityOperations(entityName, entity, parsedSchema);
+            const wrappedOps = wrapEntityOperations(entityName, baseOps, actionsAPI);
+            // baseOps has optional draft/resolve methods - EntityOperations<T> defines them as optional
+            const draftMethod = baseOps.draft;
+            const resolveMethod = baseOps.resolve;
+            const draftFn = async (data, options) => {
+                if (!draftMethod) {
+                    throw new Error(`Draft method not available for ${entityName}`);
+                }
+                const draft = await draftMethod(data, options);
+                draft.$type = entityName;
+                emitInternalEventForOps('draft', draft);
+                return draft;
+            };
+            wrappedOps.draft = draftFn;
+            const resolveFn = async (draft, options) => {
+                if (!resolveMethod) {
+                    throw new Error(`Resolve method not available for ${entityName}`);
+                }
+                const resolved = await resolveMethod(draft, options);
+                if (resolved && typeof resolved === 'object') {
+                    resolved.$type = entityName;
+                }
+                emitInternalEventForOps('resolve', resolved);
+                return resolved;
+            };
+            wrappedOps.resolve = resolveFn;
+            const originalCreate = wrappedOps.create;
+            wrappedOps.create = async (...args) => {
+                let id;
+                let data;
+                let options;
+                if (typeof args[0] === 'string') {
+                    id = args[0];
+                    data = args[1];
+                    options = args[2];
+                }
+                else {
+                    data = args[0];
+                    options = args[1];
+                }
+                if (options?.draftOnly) {
+                    const draft = await draftFn(data);
+                    return draft;
+                }
+                const effectiveMaxDepth = options?.maxDepth ?? (options?.cascade ? 3 : 0);
+                if (options?.cascade && effectiveMaxDepth > 0) {
+                    const provider = await resolveProvider();
+                    const entityDef = parsedSchema.entities.get(entityName);
+                    if (entityDef) {
+                        // CreateEntityOptions now includes _cascadeState as an optional property
+                        const cascadeState = options._cascadeState ?? {
+                            totalEntitiesCreated: 0,
+                            initialMaxDepth: effectiveMaxDepth,
+                            rootOnProgress: options.onProgress,
+                            rootOnError: options.onError,
+                            stopOnError: options.stopOnError,
+                            cascadeTypes: options.cascadeTypes,
+                        };
+                        const currentDepth = cascadeState.initialMaxDepth - effectiveMaxDepth;
+                        const cascadeData = { ...data };
+                        for (const [fieldName, field] of entityDef.fields) {
+                            if (cascadeData[fieldName] !== undefined)
+                                continue;
+                            if (field.operator === '->' && field.relatedType) {
+                                if (cascadeState.cascadeTypes && !cascadeState.cascadeTypes.includes(field.relatedType)) {
+                                    continue;
+                                }
+                                const relatedEntity = parsedSchema.entities.get(field.relatedType);
+                                if (!relatedEntity)
+                                    continue;
+                                try {
+                                    cascadeState.rootOnProgress?.({
+                                        phase: 'generating',
+                                        depth: currentDepth + 1,
+                                        currentType: field.relatedType,
+                                        totalEntitiesCreated: cascadeState.totalEntitiesCreated,
+                                    });
+                                    const childEntityData = {};
+                                    const parentInstructions = entityDef.schema?.$instructions;
+                                    const childInstructions = relatedEntity.schema?.$instructions;
+                                    const contextParts = [];
+                                    if (parentInstructions)
+                                        contextParts.push(parentInstructions);
+                                    if (childInstructions)
+                                        contextParts.push(childInstructions);
+                                    for (const [key, value] of Object.entries(cascadeData)) {
+                                        if (!key.startsWith('$') && !key.startsWith('_') && typeof value === 'string' && value) {
+                                            contextParts.push(`${key}: ${value}`);
+                                        }
+                                    }
+                                    const fullContext = contextParts.join(' | ');
+                                    for (const [childFieldName, childField] of relatedEntity.fields) {
+                                        if (!childField.isRelation && childField.type === 'string') {
+                                            childEntityData[childFieldName] = generateContextAwareValue(childFieldName, field.relatedType, fullContext, undefined, cascadeData);
+                                        }
+                                    }
+                                    const childOptions = {
+                                        ...options,
+                                        maxDepth: effectiveMaxDepth - 1,
+                                        _cascadeState: cascadeState,
+                                    };
+                                    const relatedOps = entityOperations[field.relatedType];
+                                    const createFn = relatedOps?.create;
+                                    const childEntity = createFn ? await createFn(childEntityData, childOptions) : undefined;
+                                    if (childEntity?.$id) {
+                                        cascadeState.totalEntitiesCreated++;
+                                        if (field.isArray) {
+                                            cascadeData[fieldName] = [childEntity.$id];
+                                        }
+                                        else {
+                                            cascadeData[fieldName] = childEntity.$id;
+                                        }
+                                    }
+                                }
+                                catch (error) {
+                                    cascadeState.rootOnError?.(error);
+                                    if (cascadeState.stopOnError) {
+                                        throw error;
+                                    }
+                                }
+                            }
+                        }
+                        let result;
+                        if (id) {
+                            result = await originalCreate.call(wrappedOps, id, cascadeData);
+                        }
+                        else {
+                            result = await originalCreate.call(wrappedOps, cascadeData);
+                        }
+                        cascadeState.totalEntitiesCreated++;
+                        if (currentDepth === 0) {
+                            cascadeState.rootOnProgress?.({
+                                phase: 'complete',
+                                depth: currentDepth,
+                                totalEntitiesCreated: cascadeState.totalEntitiesCreated,
+                            });
+                        }
+                        return result;
+                    }
+                }
+                return originalCreate.call(wrappedOps, ...args);
+            };
+            // Make the entity operations callable as a tagged template literal
+            entityOperations[entityName] = makeCallableEntityOps(wrappedOps, entityName);
+        }
+    }
+    // Noun definitions cache
+    const nounDefinitions = new Map();
+    for (const [entityName] of parsedSchema.entities) {
+        const noun = inferNoun(entityName);
+        nounDefinitions.set(entityName, noun);
+    }
+    // Verb definitions cache
+    const verbDefinitions = new Map(Object.entries(Verbs).map(([k, v]) => [k, v]));
+    function onInternal(eventType, handler) {
+        if (!eventHandlersForOps.has(eventType)) {
+            eventHandlersForOps.set(eventType, new Set());
+        }
+        eventHandlersForOps.get(eventType).add(handler);
+        return () => {
+            eventHandlersForOps.get(eventType)?.delete(handler);
+        };
+    }
+    const db = {
+        $schema: parsedSchema,
+        async get(url) {
+            const provider = await resolveProvider();
+            const parsed = parseUrl(url);
+            return provider.get(parsed.type, parsed.id);
+        },
+        async search(query, options) {
+            const provider = await resolveProvider();
+            const results = [];
+            for (const [typeName] of parsedSchema.entities) {
+                const typeResults = await provider.search(typeName, query, options);
+                results.push(...typeResults);
+            }
+            return results;
+        },
+        async semanticSearch(query, options) {
+            const provider = await resolveProvider();
+            const results = [];
+            if (hasSemanticSearch(provider)) {
+                for (const [typeName] of parsedSchema.entities) {
+                    const typeResults = await provider.semanticSearch(typeName, query, options);
+                    results.push(...typeResults);
+                }
+            }
+            results.sort((a, b) => b.$score - a.$score);
+            const limit = options?.limit ?? results.length;
+            return results.slice(0, limit);
+        },
+        async count(type, where) {
+            const provider = await resolveProvider();
+            const results = await provider.list(type, { where });
+            return results.length;
+        },
+        async forEach(options, callback) {
+            const provider = await resolveProvider();
+            const results = await provider.list(options.type, { where: options.where });
+            const concurrency = options.concurrency ?? 1;
+            if (concurrency === 1) {
+                for (const entity of results) {
+                    await callback(entity);
+                }
+            }
+            else {
+                const { Semaphore } = await import('../memory-provider.js');
+                const semaphore = new Semaphore(concurrency);
+                await semaphore.map(results, callback);
+            }
+        },
+        async set(type, id, data) {
+            const provider = await resolveProvider();
+            const existing = await provider.get(type, id);
+            if (existing) {
+                return provider.update(type, id, data);
+            }
+            return provider.create(type, id, data);
+        },
+        async generate(options) {
+            const provider = await resolveProvider();
+            if (options.mode === 'background') {
+                const { createMemoryProvider } = await import('../memory-provider.js');
+                const memProvider = provider;
+                if ('createAction' in memProvider) {
+                    return memProvider.createAction({
+                        type: 'generate',
+                        data: options,
+                        total: options.count ?? 1,
+                    });
+                }
+            }
+            return provider.create(options.type, undefined, options.data ?? {});
+        },
+        ask: createNLQueryFn(parsedSchema),
+        on: onInternal,
+        ...entityOperations,
+    };
+    // Create Events API
+    const events = {
+        on(pattern, handler) {
+            let unsubscribe = () => { };
+            resolveProvider().then((provider) => {
+                if (hasEventsAPI(provider)) {
+                    unsubscribe = provider.on(pattern, handler);
+                }
+            });
+            return () => unsubscribe();
+        },
+        async emit(optionsOrType, data) {
+            const provider = await resolveProvider();
+            if (hasEventsAPI(provider)) {
+                // The provider.emit has overloads: (options: CreateEventOptions) or (type: string, data: unknown)
+                if (typeof optionsOrType === 'string') {
+                    return provider.emit(optionsOrType, data);
+                }
+                return provider.emit(optionsOrType);
+            }
+            const now = new Date();
+            if (typeof optionsOrType === 'string') {
+                return {
+                    id: crypto.randomUUID(),
+                    actor: 'system',
+                    event: optionsOrType,
+                    objectData: data,
+                    timestamp: now,
+                };
+            }
+            return {
+                id: crypto.randomUUID(),
+                actor: optionsOrType.actor,
+                actorData: optionsOrType.actorData,
+                event: optionsOrType.event,
+                object: optionsOrType.object,
+                objectData: optionsOrType.objectData,
+                result: optionsOrType.result,
+                resultData: optionsOrType.resultData,
+                meta: optionsOrType.meta,
+                timestamp: now,
+            };
+        },
+        async list(options) {
+            const provider = await resolveProvider();
+            if (hasEventsAPI(provider)) {
+                return provider.listEvents(options);
+            }
+            return [];
+        },
+        async replay(options) {
+            const provider = await resolveProvider();
+            if (hasEventsAPI(provider)) {
+                await provider.replayEvents(options);
+            }
+        },
+    };
+    // Create Actions API (public version with full DBAction types)
+    const actions = {
+        async create(options) {
+            const provider = await resolveProvider();
+            if (hasActionsAPI(provider)) {
+                return provider.createAction(options);
+            }
+            throw new Error('Provider does not support actions');
+        },
+        async get(id) {
+            const provider = await resolveProvider();
+            if (hasActionsAPI(provider)) {
+                return provider.getAction(id);
+            }
+            return null;
+        },
+        async update(id, updates) {
+            const provider = await resolveProvider();
+            if (hasActionsAPI(provider)) {
+                return provider.updateAction(id, updates);
+            }
+            throw new Error('Provider does not support actions');
+        },
+        async list(options) {
+            const provider = await resolveProvider();
+            if (hasActionsAPI(provider)) {
+                return provider.listActions(options);
+            }
+            return [];
+        },
+        async retry(id) {
+            const provider = await resolveProvider();
+            if (hasActionsAPI(provider)) {
+                return provider.retryAction(id);
+            }
+            throw new Error('Provider does not support actions');
+        },
+        async cancel(id) {
+            const provider = await resolveProvider();
+            if (hasActionsAPI(provider)) {
+                await provider.cancelAction(id);
+            }
+        },
+        conjugate,
+    };
+    // Create Artifacts API
+    const artifacts = {
+        async get(url, type) {
+            const provider = await resolveProvider();
+            if (hasArtifactsAPI(provider)) {
+                return provider.getArtifact(url, type);
+            }
+            return null;
+        },
+        async set(url, type, data) {
+            const provider = await resolveProvider();
+            if (hasArtifactsAPI(provider)) {
+                await provider.setArtifact(url, type, data);
+            }
+        },
+        async delete(url, type) {
+            const provider = await resolveProvider();
+            if (hasArtifactsAPI(provider)) {
+                await provider.deleteArtifact(url, type);
+            }
+        },
+        async list(url) {
+            const provider = await resolveProvider();
+            if (hasArtifactsAPI(provider)) {
+                return provider.listArtifacts(url);
+            }
+            return [];
+        },
+    };
+    // Create Nouns API
+    const nouns = {
+        async get(name) {
+            return nounDefinitions.get(name) ?? null;
+        },
+        async list() {
+            return Array.from(nounDefinitions.values());
+        },
+        async define(noun) {
+            nounDefinitions.set(noun.singular, noun);
+        },
+    };
+    // Create Verbs API
+    const verbs = {
+        get(action) {
+            return verbDefinitions.get(action) ?? null;
+        },
+        list() {
+            return Array.from(verbDefinitions.values());
+        },
+        define(verb) {
+            verbDefinitions.set(verb.action, verb);
+        },
+        conjugate,
+    };
+    return Object.assign(db, {
+        db,
+        events,
+        actions,
+        artifacts,
+        nouns,
+        verbs,
+    });
+}
+//# sourceMappingURL=index.js.map