ai-database 2.1.3 → 2.3.0

package/dist/schema.js

@@ -1,17 +1,8 @@
 /**
  * Schema-first Database Definition
  *
- * This file re-exports all schema functionality from the modular `./schema/` directory.
- * It serves as the main entry point for backwards compatibility.
- *
- * The actual implementation is split into smaller modules:
- * - schema/types.ts - TypeScript types/interfaces
- * - schema/parse.ts - Schema parsing logic
- * - schema/provider.ts - Database provider interface and resolution
- * - schema/resolve.ts - Resolution functions for entity hydration
- * - schema/cascade.ts - Cascade generation and context-aware value generation
- * - schema/semantic.ts - Fuzzy/semantic resolution functions
- * - schema/index.ts - Main factory and entity operations
+ * Declarative schema with automatic bi-directional relationships.
+ * Uses mdxld conventions for entity structure.
  *
  * @example
  * ```ts
@@ -36,51 +27,2872 @@
  * post.author  // Author (single)
  * post.tags    // Tag[] (array)
  * ```
- *
- * @packageDocumentation
  */
+import { DBPromise, wrapEntityOperations, setSchemaRelationInfo, } from './ai-promise-db.js';
+import { cosineSimilarity, computeRRF, extractEmbeddableText, generateContentHash, } from './semantic.js';
+import { isDraft, extractRefs, hasFactoryFunction, isPlainObject, getSchemaMetadata, } from './type-guards.js';
+import { createEventBridge } from './eventbridge.js';
+import { loadEntity } from './dataloader.js';
+import { logWarn } from './logger.js';
 export { toExpanded, toFlat, Verbs, resolveUrl, resolveShortUrl, parseUrl } from './types.js';
+// Re-export from schema/ modules (only items not defined locally in this file)
+export { 
+// AI Generation configuration
+configureAIGeneration, getAIGenerationConfig, 
+// Cascade functions
+setValueGenerator, getValueGenerator, 
+// Entity operations
+createEntityOperations, createEdgeEntityOperations, 
+// Verb derivation
+FORWARD_TO_REVERSE, BIDIRECTIONAL_PAIRS, deriveReverseVerb, fieldNameToVerb, isPassiveVerb, registerVerbPair, registerBidirectionalPair, registerFieldVerb, 
+// Provider type guards
+hasSemanticSearch, hasHybridSearch, hasEventsAPI, hasActionsAPI, hasArtifactsAPI, hasEmbeddingsConfig, 
+// Schema versioning
+computeSchemaHash, getSchemaVersion, setSchemaVersion, hasSchemaChanged, 
+// Schema diff
+diffSchemas, describeDiff, 
+// Migrations
+defineMigration, runMigrations, getPendingMigrations, rollbackLastMigration, 
+// Parse functions - delegated to schema/parse.ts
+parseOperator, parseField, parseSchema, isPrimitiveType, } from './schema/index.js';
+// Import generateAIFields and generateEntity directly from cascade.js to avoid potential circular dependency
+import { generateAIFields, generateEntity as cascadeGenerateEntity, generateContextAwareValue, generateNaturalLanguageContent, DEFAULT_MAX_DEPTH, } from './schema/cascade.js';
+// Import entity operation factories for internal use
+import { createEdgeEntityOperations, createNounEntityOperations, createVerbEntityOperations, } from './schema/entity-operations.js';
+// Import type guards for internal use
+import { hasSemanticSearch, hasHybridSearch, hasEventsAPI, hasActionsAPI, hasArtifactsAPI, hasEmbeddingsConfig, isPromptField, } from './schema/index.js';
+// Import parse functions for internal use (DB() factory needs parseSchema)
+import { parseSchema, parseOperator, parseField, isPrimitiveType } from './schema/parse.js';
+// Import extracted DB() helper modules
+import { addSystemEntities, SYSTEM_ENTITY_NAMES } from './schema/system-entities.js';
+import { buildDefinitionCaches } from './schema/definition-caches.js';
+import { createEventsAPI, createActionsPublicAPI, createArtifactsAPI, createNounsAPI, createVerbsAPI, } from './schema/sub-apis.js';
+// Import module-level state setters for bridging state between schema.ts and schema/ modules
+import { setProvider as setModuleProvider } from './schema/provider.js';
+import { setNLQueryGenerator as setModuleNLQueryGenerator } from './schema/nl-query.js';
+// Import error handling utilities
+import { isNotFoundError, isEntityExistsError, wrapDatabaseError, DatabaseError, CapabilityNotSupportedError, } from './errors.js';
+// Re-export linguistic utilities from linguistic.ts
+export { conjugate, pluralize, singularize, inferNoun, createTypeMeta, getTypeMeta, Type, getVerbFields, } from './linguistic.js';
+import { Verbs } from './types.js';
+import { inferNoun, getTypeMeta, conjugate } from './linguistic.js';
+// Note: EntityOperationsMap type removed - using inline type with explanation below
+/**
+ * Create a Noun definition with type inference
+ *
+ * @example
+ * ```ts
+ * const Post = defineNoun({
+ *   singular: 'post',
+ *   plural: 'posts',
+ *   description: 'A blog post',
+ *   properties: {
+ *     title: { type: 'string', description: 'Post title' },
+ *     content: { type: 'markdown' },
+ *   },
+ *   relationships: {
+ *     author: { type: 'Author', backref: 'posts' },
+ *   },
+ * })
+ * ```
+ */
+export function defineNoun(noun) {
+    return noun;
+}
+/**
+ * Create a Verb definition with type inference
+ *
+ * @example
+ * ```ts
+ * const publish = defineVerb({
+ *   action: 'publish',
+ *   actor: 'publisher',
+ *   act: 'publishes',
+ *   activity: 'publishing',
+ *   result: 'publication',
+ *   reverse: { at: 'publishedAt', by: 'publishedBy' },
+ *   inverse: 'unpublish',
+ * })
+ * ```
+ */
+export function defineVerb(verb) {
+    return verb;
+}
+/**
+ * Convert a Noun to an EntitySchema for use with DB()
+ *
+ * @example
+ * ```ts
+ * const postNoun = defineNoun({
+ *   singular: 'post',
+ *   plural: 'posts',
+ *   properties: { title: { type: 'string' } },
+ *   relationships: { author: { type: 'Author', backref: 'posts' } },
+ * })
+ *
+ * const db = DB({
+ *   Post: nounToSchema(postNoun),
+ * })
+ * ```
+ */
+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;
+}
 // =============================================================================
-// Re-exports from linguistic.ts
+// Built-in Schema Types - Self-Describing Database
 // =============================================================================
-export { conjugate, pluralize, singularize, inferNoun, createTypeMeta, getTypeMeta, Type, getVerbFields, } from './linguistic.js';
+/**
+ * Built-in Thing schema - base type for all entities
+ *
+ * Every entity instance is a Thing with a relationship to its Noun.
+ * This creates a complete graph: Thing.type -> Noun.things
+ *
+ * @example
+ * ```ts
+ * // Every post instance:
+ * post.$type   // 'Post' (string)
+ * post.type    // -> Noun('Post') (relationship)
+ *
+ * // From Noun, get all instances:
+ * const postNoun = await db.Noun.get('Post')
+ * const allPosts = await postNoun.things  // -> Post[]
+ * ```
+ */
+export const ThingSchema = {
+    // Every Thing has a type that links to its Noun
+    type: 'Noun.things', // Thing.type -> Noun, Noun.things -> Thing[]
+};
+/**
+ * Built-in Noun schema for storing type definitions
+ *
+ * Every Type/Collection automatically gets a Noun record stored in the database.
+ * This enables introspection and self-describing schemas.
+ *
+ * @example
+ * ```ts
+ * // When you define:
+ * const db = DB({ Post: { title: 'string' } })
+ *
+ * // The database auto-creates:
+ * // db.Noun.get('Post') => { singular: 'post', plural: 'posts', ... }
+ *
+ * // Query all types:
+ * const types = await db.Noun.list()
+ *
+ * // Get all instances of a type:
+ * const postNoun = await db.Noun.get('Post')
+ * const allPosts = await postNoun.things
+ *
+ * // Listen for new types:
+ * on.Noun.created(noun => console.log(`New type: ${noun.name}`))
+ * ```
+ */
+export const NounSchema = {
+    // Identity
+    name: 'string', // 'Post', 'BlogPost'
+    singular: 'string', // 'post', 'blog post'
+    plural: 'string', // 'posts', 'blog posts'
+    slug: 'string', // 'post', 'blog-post'
+    slugPlural: 'string', // 'posts', 'blog-posts'
+    description: 'string?', // Human description
+    // Schema
+    properties: 'json?', // Property definitions
+    relationships: 'json?', // Relationship definitions
+    // Behavior
+    actions: 'json?', // Available actions (verbs)
+    events: 'json?', // Event types
+    // Metadata
+    metadata: 'json?', // Additional metadata
+    // Relationships - auto-created by bi-directional system
+    // things: Thing[]        // All instances of this type (backref from Thing.type)
+};
+/**
+ * Built-in Verb schema for storing action definitions
+ */
+export const VerbSchema = {
+    action: 'string', // 'create', 'publish'
+    actor: 'string?', // 'creator', 'publisher'
+    act: 'string?', // 'creates', 'publishes'
+    activity: 'string?', // 'creating', 'publishing'
+    result: 'string?', // 'creation', 'publication'
+    reverse: 'json?', // { at, by, in, for }
+    inverse: 'string?', // 'delete', 'unpublish'
+    description: 'string?',
+};
+/**
+ * Built-in Edge schema for relationships between types
+ *
+ * Every relationship in a schema creates an Edge record.
+ * This enables graph queries across the type system.
+ *
+ * @example
+ * ```ts
+ * // Post.author -> Author creates:
+ * // Edge { from: 'Post', name: 'author', to: 'Author', backref: 'posts', cardinality: 'many-to-one' }
+ *
+ * // Query the graph:
+ * const edges = await db.Edge.find({ to: 'Author' })
+ * // => [{ from: 'Post', name: 'author' }, { from: 'Comment', name: 'author' }]
+ *
+ * // What types reference Author?
+ * const referencing = edges.map(e => e.from)  // ['Post', 'Comment']
+ * ```
+ */
+export const EdgeSchema = {
+    from: 'string', // Source type: 'Post'
+    name: 'string', // Field name: 'author'
+    to: 'string', // Target type: 'Author'
+    backref: 'string?', // Inverse field: 'posts'
+    cardinality: 'string', // 'one-to-one', 'one-to-many', 'many-to-one', 'many-to-many'
+    direction: 'string', // 'forward' | 'backward'
+    matchMode: 'string?', // 'exact' | 'fuzzy'
+    required: 'boolean?', // Is this relationship required?
+    description: 'string?', // Human description
+};
+/**
+ * System types that are auto-created in every database
+ *
+ * The graph structure:
+ * - Thing.type -> Noun (every instance links to its type)
+ * - Noun.things -> Thing[] (every type has its instances)
+ * - Edge connects Nouns (relationships between types)
+ * - Verb describes actions on Nouns
+ */
+export const SystemSchema = {
+    Thing: ThingSchema,
+    Noun: NounSchema,
+    Verb: VerbSchema,
+    Edge: EdgeSchema,
+};
+/**
+ * Create Edge records from schema relationships
+ *
+ * @internal Used by DB() to auto-populate Edge records
+ *
+ * For backward edges (direction === 'backward'), the from/to are inverted:
+ * - Forward: from = typeName, to = relatedType
+ * - Backward: from = relatedType, to = typeName
+ *
+ * This enables proper graph traversal where backward edges represent
+ * "pointing to" relationships (e.g., Post.comments -> Comments that point TO Post)
+ */
+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';
+            // For backward edges, invert from/to and adjust cardinality
+            const isBackward = direction === 'backward';
+            const from = isBackward ? field.relatedType : typeName;
+            const to = isBackward ? typeName : field.relatedType;
+            // Cardinality from the perspective of the field definition
+            // - Array with backref = many-to-many (Post.tags <-> Tag.posts)
+            // - Array without backref = one-to-many (one source points to many targets)
+            // - Single = many-to-one (many sources point to one target)
+            // The 'one-to-one' case is rare and typically requires explicit constraint
+            let cardinality;
+            if (field.isArray) {
+                cardinality = field.backref ? 'many-to-many' : 'one-to-many';
+            }
+            else {
+                // Single reference: by default many-to-one (many posts -> one author)
+                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
+ *
+ * @internal Used by DB() to auto-populate Noun records
+ */
+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)) {
+        // Skip metadata fields (prefixed with $) like $context, $instructions
+        if (name.startsWith('$'))
+            continue;
+        // Skip if definition is invalid (null, undefined)
+        if (!def)
+            continue;
+        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;
+}
 // =============================================================================
-// Re-exports from schema/parse.ts
+// Natural Language Query Implementation
 // =============================================================================
-export { parseOperator, parseField, parseSchema, isPrimitiveType } from './schema/parse.js';
-export { setProvider, resolveProvider } from './schema/provider.js';
+// NOTE: NLQueryGenerator, NLQueryContext, NLQueryPlan types are imported from ./schema/types.js
+// and re-exported via ./schema/index.js for the public API
+// The functions below maintain local state and bridge to the module state in schema/nl-query.ts
+let nlQueryGenerator = null;
+/**
+ * Set the AI generator for natural language queries
+ *
+ * @example
+ * ```ts
+ * import { generate } from 'ai-functions'
+ *
+ * setNLQueryGenerator(async (prompt, context) => {
+ *   return generate({
+ *     prompt: `Given this schema: ${JSON.stringify(context.types)}
+ *              Answer this question: ${prompt}
+ *              Return a query plan as JSON.`,
+ *     schema: NLQueryPlanSchema
+ *   })
+ * })
+ * ```
+ */
+export function setNLQueryGenerator(generator) {
+    nlQueryGenerator = generator;
+    // Bridge to schema/nl-query.ts module state so extracted modules share the same generator
+    setModuleNLQueryGenerator(generator);
+}
+/**
+ * Get the currently configured NL query generator
+ */
+export function getNLQueryGenerator() {
+    return nlQueryGenerator;
+}
+/**
+ * Build schema context for NL queries
+ */
+export 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 !== undefined && { targetType }) };
+}
+/**
+ * Execute a natural language query
+ */
+export async function executeNLQuery(question, schema, targetType) {
+    // Import applyFilters for MongoDB-style filter support
+    const { applyFilters } = await import('./schema/nl-query-generator.js');
+    // If no AI generator configured, fall back to search
+    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) {
+                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)',
+        };
+    }
+    // Build context and get AI-generated query plan
+    const context = buildNLQueryContext(schema, targetType);
+    const plan = await nlQueryGenerator(question, context);
+    // Execute the plan
+    const provider = await resolveProvider();
+    let results = [];
+    for (const typeName of plan.types) {
+        let typeResults;
+        if (plan.search) {
+            typeResults = await provider.search(typeName, plan.search);
+        }
+        else {
+            typeResults = await provider.list(typeName);
+        }
+        // Apply MongoDB-style filters in memory
+        if (plan.filters && Object.keys(plan.filters).length > 0) {
+            typeResults = applyFilters(typeResults, 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 }),
+    };
+}
+/**
+ * Create a natural language query function for a specific type
+ */
+export function createNLQueryFn(schema, typeName) {
+    return async (strings, ...values) => {
+        // Interpolate the template
+        const question = strings.reduce((acc, str, i) => {
+            return acc + str + (values[i] !== undefined ? String(values[i]) : '');
+        }, '');
+        return executeNLQuery(question, schema, typeName);
+    };
+}
 // =============================================================================
-// Re-exports from schema/resolve.ts
+// Provider Interface - Delegated to schema/provider.ts
 // =============================================================================
-export { isEntityId, inferTypeFromField, resolveContextPath, resolveInstructions, prefetchContext, isPromptField, resolveNestedPending, resolveReferenceSpec, hydrateEntity, } from './schema/resolve.js';
+// NOTE: DBProvider interface is imported from ./schema/provider.js for internal use
+// and re-exported via ./schema/index.js for the public API
 // =============================================================================
-// Re-exports from schema/cascade.ts
+// Provider Resolution
 // =============================================================================
-export { generateContextAwareValue, generateAIFields, generateEntity, resolveForwardExact, generateNaturalLanguageContent, } from './schema/cascade.js';
+let globalProvider = null;
+let providerPromise = null;
+/** File count threshold for suggesting ClickHouse upgrade */
+const FILE_COUNT_THRESHOLD = 10_000;
+/**
+ * Set the global database provider
+ */
+export function setProvider(provider) {
+    globalProvider = provider;
+    providerPromise = null;
+    // Bridge to schema/provider.ts module state so extracted modules share the same provider
+    setModuleProvider(provider);
+}
+/**
+ * Parse DATABASE_URL into provider type and paths
+ *
+ * Local storage (all use .db/ folder):
+ * - `./content` → fs (default)
+ * - `sqlite://./content` → sqlite stored in ./content/.db/index.sqlite
+ * - `chdb://./content` → clickhouse stored in ./content/.db/clickhouse/
+ *
+ * Remote:
+ * - `libsql://your-db.turso.io` → Turso SQLite
+ * - `clickhouse://host:8123` → ClickHouse HTTP
+ * - `:memory:` → in-memory
+ */
+function parseDatabaseUrl(url) {
+    if (!url)
+        return { provider: 'fs', root: './content' };
+    // In-memory
+    if (url === ':memory:') {
+        return { provider: 'memory', root: '' };
+    }
+    // Remote Turso
+    if (url.startsWith('libsql://') || url.includes('.turso.io')) {
+        return { provider: 'sqlite', root: '', remoteUrl: url };
+    }
+    // Remote ClickHouse
+    if (url.startsWith('clickhouse://') && url.includes(':')) {
+        // clickhouse://host:port/db
+        return { provider: 'clickhouse', root: '', remoteUrl: url.replace('clickhouse://', 'https://') };
+    }
+    // Local SQLite: sqlite://./content → ./content/.db/index.sqlite
+    if (url.startsWith('sqlite://')) {
+        const root = url.replace('sqlite://', '') || './content';
+        return { provider: 'sqlite', root };
+    }
+    // Local ClickHouse (chDB): chdb://./content → ./content/.db/clickhouse/
+    if (url.startsWith('chdb://')) {
+        const root = url.replace('chdb://', '') || './content';
+        return { provider: 'clickhouse', root };
+    }
+    // Default: filesystem
+    return { provider: 'fs', root: url };
+}
+/**
+ * Resolve provider from DATABASE_URL environment variable
+ *
+ * @example
+ * ```bash
+ * # Filesystem (default) - stores in ./content with .db/ metadata
+ * DATABASE_URL=./content
+ *
+ * # Local SQLite - stores in ./content/.db/index.sqlite
+ * DATABASE_URL=sqlite://./content
+ *
+ * # Remote Turso
+ * DATABASE_URL=libsql://your-db.turso.io
+ *
+ * # Local ClickHouse (chDB) - stores in ./content/.db/clickhouse/
+ * DATABASE_URL=chdb://./content
+ *
+ * # Remote ClickHouse
+ * DATABASE_URL=clickhouse://localhost:8123
+ *
+ * # In-memory (testing)
+ * DATABASE_URL=:memory:
+ * ```
+ */
+async function resolveProvider() {
+    if (globalProvider)
+        return globalProvider;
+    if (providerPromise)
+        return providerPromise;
+    providerPromise = (async () => {
+        const databaseUrl = (typeof process !== 'undefined' && process.env?.['DATABASE_URL']) || './content';
+        const parsed = parseDatabaseUrl(databaseUrl);
+        switch (parsed.provider) {
+            case 'memory': {
+                const { createMemoryProvider } = await import('./memory-provider.js');
+                globalProvider = createMemoryProvider();
+                break;
+            }
+            case 'fs': {
+                try {
+                    // Dynamic import with runtime validation using type guard
+                    const fsModule = await import('@mdxdb/fs');
+                    if (!hasFactoryFunction(fsModule, 'createFsProvider')) {
+                        throw new Error('@mdxdb/fs does not export createFsProvider');
+                    }
+                    globalProvider = fsModule.createFsProvider({ root: parsed.root });
+                    // Check file count and warn if approaching threshold
+                    checkFileCountThreshold(parsed.root);
+                }
+                catch (err) {
+                    console.warn('@mdxdb/fs not available, falling back to memory provider');
+                    const { createMemoryProvider } = await import('./memory-provider.js');
+                    globalProvider = createMemoryProvider();
+                }
+                break;
+            }
+            case 'sqlite': {
+                try {
+                    // Dynamic import with runtime validation using type guard
+                    const sqliteModule = await import('@mdxdb/sqlite');
+                    if (!hasFactoryFunction(sqliteModule, 'createSqliteProvider')) {
+                        throw new Error('@mdxdb/sqlite does not export createSqliteProvider');
+                    }
+                    if (parsed.remoteUrl) {
+                        // Remote Turso
+                        globalProvider = (await sqliteModule.createSqliteProvider({
+                            url: parsed.remoteUrl,
+                        }));
+                    }
+                    else {
+                        // Local SQLite in .db folder
+                        const dbPath = `${parsed.root}/.db/index.sqlite`;
+                        globalProvider = (await sqliteModule.createSqliteProvider({
+                            url: `file:${dbPath}`,
+                        }));
+                    }
+                }
+                catch (err) {
+                    console.warn('@mdxdb/sqlite not available, falling back to memory provider');
+                    const { createMemoryProvider } = await import('./memory-provider.js');
+                    globalProvider = createMemoryProvider();
+                }
+                break;
+            }
+            case 'clickhouse': {
+                try {
+                    // Dynamic import with runtime validation using type guard
+                    const chModule = await import('@mdxdb/clickhouse');
+                    if (!hasFactoryFunction(chModule, 'createClickhouseProvider')) {
+                        throw new Error('@mdxdb/clickhouse does not export createClickhouseProvider');
+                    }
+                    if (parsed.remoteUrl) {
+                        // Remote ClickHouse
+                        globalProvider = (await chModule.createClickhouseProvider({
+                            mode: 'http',
+                            url: parsed.remoteUrl,
+                        }));
+                    }
+                    else {
+                        // Local chDB in .db folder
+                        const dbPath = `${parsed.root}/.db/clickhouse`;
+                        globalProvider = (await chModule.createClickhouseProvider({
+                            mode: 'chdb',
+                            url: dbPath,
+                        }));
+                    }
+                }
+                catch (err) {
+                    console.warn('@mdxdb/clickhouse not available, falling back to memory provider');
+                    const { createMemoryProvider } = await import('./memory-provider.js');
+                    globalProvider = createMemoryProvider();
+                }
+                break;
+            }
+            default: {
+                const { createMemoryProvider } = await import('./memory-provider.js');
+                globalProvider = createMemoryProvider();
+            }
+        }
+        return globalProvider;
+    })();
+    return providerPromise;
+}
+/**
+ * Check file count and warn if approaching threshold
+ */
+async function checkFileCountThreshold(root) {
+    try {
+        const fs = await import('node:fs/promises');
+        const path = await import('node:path');
+        async function countFiles(dir) {
+            let count = 0;
+            try {
+                const entries = await fs.readdir(dir, { withFileTypes: true });
+                for (const entry of entries) {
+                    if (entry.name.startsWith('.'))
+                        continue;
+                    if (entry.isDirectory()) {
+                        count += await countFiles(path.join(dir, entry.name));
+                    }
+                    else if (entry.name.endsWith('.mdx') || entry.name.endsWith('.md')) {
+                        count++;
+                    }
+                }
+            }
+            catch {
+                // Directory doesn't exist yet
+            }
+            return count;
+        }
+        const count = await countFiles(root);
+        if (count > FILE_COUNT_THRESHOLD) {
+            console.warn(`\n⚠️  You have ${count.toLocaleString()} MDX files. ` +
+                `Consider upgrading to ClickHouse for better performance:\n` +
+                `   DATABASE_URL=chdb://./data/clickhouse\n`);
+        }
+    }
+    catch {
+        // Ignore errors in file counting
+    }
+}
 // =============================================================================
-// Re-exports from schema/semantic.ts
+// DB Factory
 // =============================================================================
-export { resolveBackwardFuzzy, resolveForwardFuzzy } from './schema/semantic.js';
+/**
+ * Create a typed database from a schema definition
+ *
+ * Supports both direct usage and destructuring for flexibility:
+ *
+ * @example Direct usage - everything on one object
+ * ```ts
+ * const db = DB({
+ *   Post: { title: 'string', author: 'Author.posts' },
+ *   Author: { name: 'string' },
+ * })
+ *
+ * // Entity operations
+ * const post = await db.Post.create({ title: 'Hello' })
+ *
+ * // Events, actions, etc. are also available directly
+ * db.events.on('Post.created', (event) => console.log(event))
+ * db.actions.create({ type: 'generate', data: {} })
+ * ```
+ *
+ * @example Destructured usage - cleaner separation
+ * ```ts
+ * const { db, events, actions, artifacts, nouns, verbs } = DB({
+ *   Post: { title: 'string', author: 'Author.posts' },
+ *   Author: { name: 'string' },
+ * })
+ *
+ * // CRUD operations on db
+ * const post = await db.Post.create({ title: 'Hello' })
+ * await db.Post.update(post.$id, { title: 'Updated' })
+ *
+ * // Separate events API
+ * events.on('Post.created', (event) => console.log(event))
+ *
+ * // Separate actions API
+ * const action = await actions.create({ type: 'generate', data: {} })
+ * ```
+ */
+export function DB(schema, options) {
+    const parsedSchema = parseSchema(schema);
+    // Validate union types - ensure all union type references point to existing types
+    // This is done here rather than in parseSchema() to allow parseSchema() to be used
+    // for pure parsing tests without requiring all union types to be defined
+    for (const [entityName, entity] of parsedSchema.entities) {
+        for (const [fieldName, field] of entity.fields) {
+            if (field.isRelation && field.operator && field.unionTypes && field.unionTypes.length > 0) {
+                for (const unionType of field.unionTypes) {
+                    if (unionType === entityName)
+                        continue; // Skip self-references
+                    if (!parsedSchema.entities.has(unionType)) {
+                        throw new Error(`Invalid schema: ${entityName}.${fieldName} references non-existent type '${unionType}'`);
+                    }
+                }
+            }
+        }
+    }
+    // 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);
+    // Add system entities to the parsed schema (Noun, Verb, Edge)
+    addSystemEntities(parsedSchema);
+    // Create local getProvider function for dependency injection
+    // If options.provider is provided, use it; otherwise fall back to global resolveProvider()
+    let cachedProvider = null;
+    let localProviderPromise = null;
+    async function getProvider() {
+        // Return cached provider if available
+        if (cachedProvider)
+            return cachedProvider;
+        // Return pending promise if resolution is in progress
+        if (localProviderPromise)
+            return localProviderPromise;
+        // Check if options.provider is provided (dependency injection)
+        if (options?.provider) {
+            localProviderPromise = (async () => {
+                const providerOption = options.provider;
+                if (typeof providerOption === 'function') {
+                    // It's a factory function - call it
+                    const result = providerOption();
+                    // Handle both sync and async factory functions
+                    cachedProvider = result instanceof Promise ? await result : result;
+                }
+                else {
+                    // It's a direct provider instance
+                    cachedProvider = providerOption;
+                }
+                return cachedProvider;
+            })();
+            return localProviderPromise;
+        }
+        // Fall back to global resolveProvider()
+        localProviderPromise = resolveProvider().then((p) => {
+            cachedProvider = p;
+            return p;
+        });
+        return localProviderPromise;
+    }
+    // Configure provider with embeddings settings if provided
+    if (options?.embeddings) {
+        const embeddingsConfig = options.embeddings;
+        getProvider()
+            .then((provider) => {
+            if (hasEmbeddingsConfig(provider)) {
+                provider.setEmbeddingsConfig(embeddingsConfig);
+            }
+            else {
+                // Warn that embeddings configuration was provided but provider doesn't support it
+                logWarn('Embeddings configuration provided but current provider does not support semantic search. ' +
+                    'Embeddings will not be generated. Use a provider with embedding support (e.g., createMemoryProvider()).');
+            }
+        })
+            .catch((error) => {
+            console.error('Failed to configure embeddings on provider:', error);
+        });
+    }
+    // Collect all edge records from the schema (user-defined entities only)
+    const allEdgeRecords = [];
+    for (const [entityName, entity] of parsedSchema.entities) {
+        if (!SYSTEM_ENTITY_NAMES.has(entityName)) {
+            const edgeRecords = createEdgeRecords(entityName, schema[entityName] ?? {}, entity);
+            allEdgeRecords.push(...edgeRecords);
+        }
+    }
+    // Collect all noun records from the schema (user-defined entities only)
+    const allNounRecords = [];
+    for (const [entityName] of parsedSchema.entities) {
+        if (!SYSTEM_ENTITY_NAMES.has(entityName)) {
+            const nounRecord = createNounRecord(entityName, schema[entityName]);
+            allNounRecords.push(nounRecord);
+        }
+    }
+    // Collect all verb records from the standard verbs
+    const allVerbRecords = Object.values(Verbs).map((verb) => ({
+        ...verb,
+        $id: verb.action,
+        $type: 'Verb',
+    }));
+    // Create Actions API early so it can be injected into entity operations
+    const actionsAPI = {
+        async create(options) {
+            const provider = await getProvider();
+            if (hasActionsAPI(provider)) {
+                return provider.createAction(options);
+            }
+            throw new Error('Provider does not support actions');
+        },
+        async get(id) {
+            const provider = await getProvider();
+            if (hasActionsAPI(provider)) {
+                return provider.getAction(id);
+            }
+            return null;
+        },
+        async update(id, updates) {
+            const provider = await getProvider();
+            if (hasActionsAPI(provider)) {
+                return provider.updateAction(id, updates);
+            }
+            throw new Error('Provider does not support actions');
+        },
+    };
+    // Create ForEachActionsAPI adapter for wrapEntityOperations
+    const forEachActionsAPI = {
+        async create(data) {
+            const result = await actionsAPI.create(data);
+            return { id: result.id };
+        },
+        async get(id) {
+            return actionsAPI.get(id);
+        },
+        async update(id, updates) {
+            // Filter to only the properties that actionsAPI.update accepts
+            const filteredUpdates = {};
+            if (updates.status !== undefined)
+                filteredUpdates.status = updates.status;
+            if (updates.progress !== undefined)
+                filteredUpdates.progress = updates.progress;
+            return actionsAPI.update(id, filteredUpdates);
+        },
+    };
+    // Create entity operations for each type with promise pipelining
+    // NOTE: Using Record<string, unknown> here because entity operations types vary by schema.
+    // The actual types are determined at runtime and enforced via wrapEntityOperations.
+    // Attempts to use stricter types conflict with wrapEntityOperations return type.
+    const entityOperations = {};
+    // Internal event emitter for draft/resolve events (defined early for use in entity operations)
+    const eventHandlersForOps = new Map();
+    function emitInternalEventForOps(eventType, data) {
+        const handlers = eventHandlersForOps.get(eventType);
+        if (handlers) {
+            const snapshot = [...handlers];
+            for (const handler of snapshot) {
+                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) {
+        const nlQueryFn = createNLQueryFn(parsedSchema, entityName);
+        const callableOps = function (strings, ...values) {
+            return nlQueryFn(strings, ...values);
+        };
+        Object.assign(callableOps, ops);
+        return callableOps;
+    }
+    for (const [entityName, entity] of parsedSchema.entities) {
+        if (entityName === 'Edge') {
+            // Special handling for Edge entity - query from in-memory edge records + runtime edges
+            const edgeOps = createEdgeEntityOperations(allEdgeRecords, resolveProvider);
+            entityOperations[entityName] = makeCallableEntityOps(wrapEntityOperations(entityName, edgeOps, forEachActionsAPI), entityName);
+        }
+        else if (entityName === 'Noun') {
+            // Noun entity - auto-generated from schema entity types
+            const nounOps = createNounEntityOperations(allNounRecords);
+            entityOperations[entityName] = makeCallableEntityOps(wrapEntityOperations(entityName, nounOps, forEachActionsAPI), entityName);
+        }
+        else if (entityName === 'Verb') {
+            // Verb entity - standard verbs with conjugation forms
+            const verbOps = createVerbEntityOperations(allVerbRecords);
+            entityOperations[entityName] = makeCallableEntityOps(wrapEntityOperations(entityName, verbOps, forEachActionsAPI), entityName);
+        }
+        else {
+            const baseOps = createEntityOperations(entityName, entity, parsedSchema);
+            // Wrap with DBPromise for chainable queries, inject actions for forEach persistence
+            const wrappedOps = wrapEntityOperations(entityName, baseOps, forEachActionsAPI);
+            // Add draft and resolve with event emission
+            const draftFn = async (data, options) => {
+                // baseOps.draft is defined in createEntityOperations
+                if (!baseOps.draft) {
+                    throw new Error(`Draft method not available for ${entityName}`);
+                }
+                const draft = await baseOps.draft(data, options);
+                // Draft objects are always Record<string, unknown> - safe to set $type
+                if (draft && typeof draft === 'object' && !Array.isArray(draft)) {
+                    const draftRecord = draft;
+                    draftRecord['$type'] = entityName;
+                }
+                emitInternalEventForOps('draft', draft);
+                return draft;
+            };
+            wrappedOps.draft = draftFn;
+            const resolveFn = async (draft, options) => {
+                // baseOps.resolve is defined in createEntityOperations
+                if (!baseOps.resolve) {
+                    throw new Error(`Resolve method not available for ${entityName}`);
+                }
+                // Draft<T> is always a Record with $phase - this cast is safe after validation
+                const resolved = await baseOps.resolve(draft, options);
+                if (resolved && typeof resolved === 'object' && !Array.isArray(resolved)) {
+                    const resolvedRecord = resolved;
+                    resolvedRecord['$type'] = entityName;
+                }
+                emitInternalEventForOps('resolve', resolved);
+                return resolved;
+            };
+            wrappedOps.resolve = resolveFn;
+            // Update create to support draftOnly option and wire through draft/resolve
+            const originalCreate = wrappedOps.create;
+            wrappedOps.create = async (...args) => {
+                // Parse arguments - can be (data, options?) or (id, data, options?)
+                // Type assertions here are necessary because variadic args are typed as unknown[]
+                let data;
+                let options;
+                if (typeof args[0] === 'string') {
+                    // (id, data, options?) - args[1] is the data object
+                    data = isPlainObject(args[1]) ? args[1] : {};
+                    options = isPlainObject(args[2]) ? args[2] : undefined;
+                }
+                else {
+                    // (data, options?) - args[0] is the data object
+                    data = isPlainObject(args[0]) ? args[0] : {};
+                    // Check if second arg is options (has option-like properties)
+                    options = isPlainObject(args[1]) ? args[1] : undefined;
+                }
+                if (options?.draftOnly) {
+                    const draft = await draftFn(data);
+                    return draft;
+                }
+                // Pre-generate entity ID so it's available during resolve phase
+                // This allows generated child entities to reference the parent via $generatedBy
+                const preGeneratedId = typeof args[0] === 'string' ? args[0] : crypto.randomUUID();
+                // Run draft phase first - draftFn returns an object with draft properties and emits 'draft' event
+                const draftResult = await draftFn(data);
+                const draft = isPlainObject(draftResult) ? draftResult : {};
+                // Inject $id into draft so resolve can pass it as context to resolveReferenceSpec
+                draft['$id'] = preGeneratedId;
+                // Always strip array forward relation refs from the draft phase.
+                // When cascade is enabled, cascadeGenerate handles array relations with proper
+                // depth control and cascadeTypes filtering. When cascade is not enabled,
+                // array relations should not be auto-generated.
+                const draftRefs = draft['$refs'];
+                if (draftRefs) {
+                    for (const [refFieldName, refSpec] of Object.entries(draftRefs)) {
+                        if (Array.isArray(refSpec)) {
+                            delete draftRefs[refFieldName];
+                            draft[refFieldName] = undefined;
+                        }
+                    }
+                }
+                // Then resolve - resolveFn emits 'resolve' event
+                const resolveResult = await resolveFn(draft);
+                const resolved = isPlainObject(resolveResult) ? resolveResult : {};
+                // Create the final entity (without phase markers)
+                const finalData = { ...resolved };
+                delete finalData['$phase'];
+                delete finalData['$refs'];
+                delete finalData['$errors'];
+                delete finalData['$type'];
+                // Call originalCreate with the resolved data using the pre-generated ID
+                // Pass _preResolved flag to skip internal draft/resolve in entity-operations.create()
+                // Type assertion to Function is necessary for dynamic method call with spread args
+                return originalCreate.call(wrappedOps, preGeneratedId, finalData, { ...options, _preResolved: true });
+            };
+            // Add seed method if entity has seed configuration
+            if (entity.seedConfig) {
+                const seedConfig = entity.seedConfig;
+                wrappedOps['seed'] = async () => {
+                    const { loadSeedData } = await import('./schema/seed.js');
+                    const records = await loadSeedData(seedConfig);
+                    const provider = await getProvider();
+                    for (const record of records) {
+                        const { $id, ...data } = record;
+                        // Upsert: check if exists, then update or create
+                        const existing = await provider.get(entityName, $id);
+                        if (existing) {
+                            await provider.update(entityName, $id, data);
+                        }
+                        else {
+                            await provider.create(entityName, $id, data);
+                        }
+                    }
+                    return { count: records.length };
+                };
+            }
+            entityOperations[entityName] = makeCallableEntityOps(wrappedOps, entityName);
+        }
+    }
+    // Build noun and verb definition caches
+    const { nounDefinitions, verbDefinitions } = buildDefinitionCaches(parsedSchema);
+    // Use the event handlers defined earlier for entity operations
+    function onInternal(eventType, handler) {
+        if (!eventHandlersForOps.has(eventType)) {
+            eventHandlersForOps.set(eventType, new Set());
+        }
+        eventHandlersForOps.get(eventType).add(handler);
+        return () => {
+            eventHandlersForOps.get(eventType)?.delete(handler);
+        };
+    }
+    // Create the typed DB object
+    const db = {
+        $schema: parsedSchema,
+        async get(url) {
+            const provider = await getProvider();
+            const parsed = parseUrl(url);
+            return provider.get(parsed.type, parsed.id);
+        },
+        async search(query, options) {
+            const provider = await getProvider();
+            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 getProvider();
+            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 = [];
+            for (const [typeName] of parsedSchema.entities) {
+                const typeResults = await provider.semanticSearch(typeName, query, options);
+                results.push(...typeResults);
+            }
+            // Sort by score across all types
+            results.sort((a, b) => b.$score - a.$score);
+            // Apply limit if specified
+            const limit = options?.limit ?? results.length;
+            return results.slice(0, limit);
+        },
+        async count(type, where) {
+            const provider = await getProvider();
+            const results = await provider.list(type, where ? { where } : undefined);
+            return results.length;
+        },
+        async forEach(options, callback) {
+            const provider = await getProvider();
+            const results = await provider.list(options.type, options.where ? { where: options.where } : undefined);
+            const concurrency = options.concurrency ?? 1;
+            if (concurrency === 1) {
+                for (const entity of results) {
+                    await callback(entity);
+                }
+            }
+            else {
+                // Process in batches with concurrency
+                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 getProvider();
+            const existing = await provider.get(type, id);
+            if (existing) {
+                // Replace entirely (not merge)
+                return provider.update(type, id, data);
+            }
+            return provider.create(type, id, data);
+        },
+        async generate(options) {
+            // Placeholder - actual AI generation would be implemented here
+            // For now, just create with provided data
+            const provider = await getProvider();
+            if (options.mode === 'background') {
+                // Return action ID for tracking
+                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,
+                    });
+                }
+            }
+            // Sync mode - create single entity
+            return provider.create(options.type, undefined, options.data ?? {});
+        },
+        ask: createNLQueryFn(parsedSchema),
+        on: onInternal,
+        ...entityOperations,
+    };
+    // Create sub-APIs using extracted factory functions
+    const events = createEventsAPI(getProvider);
+    const actions = createActionsPublicAPI(getProvider);
+    const artifacts = createArtifactsAPI(getProvider);
+    const nouns = createNounsAPI(nounDefinitions);
+    const verbs = createVerbsAPI(verbDefinitions);
+    const eventBridge = createEventBridge();
+    // Return combined object that supports both direct usage and destructuring
+    // db.User.create() works, db.events.on() works
+    // const { db, events } = DB(...) also works
+    return Object.assign(db, {
+        db, // self-reference for destructuring
+        events,
+        actions,
+        artifacts,
+        nouns,
+        verbs,
+        eventBridge,
+    });
+}
+/**
+ * Parse a URL into type and id
+ */
+function parseUrl(url) {
+    // Handle full URLs
+    if (url.includes('://')) {
+        const parsed = new URL(url);
+        const parts = parsed.pathname.split('/').filter(Boolean);
+        return {
+            type: parts[0] || '',
+            id: parts.slice(1).join('/'),
+        };
+    }
+    // Handle type/id format
+    if (url.includes('/')) {
+        const parts = url.split('/');
+        return {
+            type: parts[0],
+            id: parts.slice(1).join('/'),
+        };
+    }
+    // Just id
+    return { type: '', id: url };
+}
 // =============================================================================
-// Re-exports from schema/verb-derivation.ts
+// Forward Exact Resolution - Auto-generate related entities
 // =============================================================================
-export { FORWARD_TO_REVERSE, BIDIRECTIONAL_PAIRS, deriveReverseVerb, fieldNameToVerb, isPassiveVerb, registerVerbPair, registerBidirectionalPair, registerFieldVerb, } from './schema/verb-derivation.js';
+/**
+ * Generate an entity based on its type and context
+ *
+ * For testing, generates deterministic content based on the prompt and type.
+ * In production, this would integrate with AI generation.
+ *
+ * @param type - The type of entity to generate
+ * @param prompt - Optional prompt for generation context
+ * @param context - Parent context information (parent type name, parentData, and optional parentId)
+ * @param schema - The parsed schema
+ */
+async function generateEntity(type, prompt, context, schema) {
+    const entity = schema.entities.get(type);
+    if (!entity)
+        throw new Error(`Unknown type: ${type}`);
+    // Gather context for generation
+    const parentEntity = schema.entities.get(context.parent);
+    // EntitySchema is Record<string, FieldDefinition | unknown> - safe to treat as Record
+    const parentSchema = parentEntity?.schema ?? {};
+    // Use type guard helper to safely extract schema metadata
+    const instructions = getSchemaMetadata(parentSchema, '$instructions');
+    const schemaContext = getSchemaMetadata(parentSchema, '$context');
+    // Extract relevant parent data for context (excluding metadata fields)
+    const parentContextFields = [];
+    for (const [key, value] of Object.entries(context.parentData)) {
+        if (!key.startsWith('$') && !key.startsWith('_') && typeof value === 'string' && value) {
+            parentContextFields.push(`${key}: ${value}`);
+        }
+    }
+    // Build context string for generation
+    const contextParts = [];
+    if (prompt && prompt.trim()) {
+        contextParts.push(prompt);
+    }
+    if (instructions) {
+        contextParts.push(instructions);
+    }
+    if (schemaContext) {
+        contextParts.push(schemaContext);
+    }
+    if (parentContextFields.length > 0) {
+        contextParts.push(parentContextFields.join(', '));
+    }
+    const fullContext = contextParts.join(' | ');
+    const data = {};
+    for (const [fieldName, field] of entity.fields) {
+        if (!field.isRelation) {
+            if (field.type === 'string') {
+                // Generate context-aware content
+                data[fieldName] = generateContextAwareValue(fieldName, type, fullContext, prompt);
+            }
+            else if (field.isArray && field.type === 'string') {
+                // Generate array of strings
+                data[fieldName] = [generateContextAwareValue(fieldName, type, fullContext, prompt)];
+            }
+        }
+        else if (field.operator === '<-' && field.direction === 'backward') {
+            // Backward relation to parent - set the parent's ID if this entity's
+            // related type matches the parent type
+            if (field.relatedType === context.parent && context.parentId) {
+                // Store the parent ID directly - this is a reference back to the parent
+                data[fieldName] = context.parentId;
+            }
+        }
+        else if (field.operator === '->' && field.direction === 'forward') {
+            // Recursively generate nested forward exact relations
+            // This handles cases like Person.bio -> Bio (single relations, not arrays)
+            // Array relations are handled by resolveForwardExact or cascadeGenerate
+            if (!field.isOptional && !field.isArray) {
+                const nestedGenerated = await generateEntity(field.relatedType, field.prompt, { parent: type, parentData: data }, schema);
+                // We need to create the nested entity too, but we can't do that here
+                // because we don't have access to the provider yet.
+                // This will be handled by resolveForwardExact when it calls us
+                data[`_pending_${fieldName}`] = { type: field.relatedType, data: nestedGenerated };
+            }
+        }
+    }
+    return data;
+}
+/**
+ * Resolve forward exact (->) fields by auto-generating related entities
+ *
+ * When creating an entity with a -> field, if no value is provided,
+ * we auto-generate the related entity and link it.
+ *
+ * Returns resolved data and pending relationships that need to be created
+ * after the parent entity is created (for array fields).
+ *
+ * @param parentId - Pre-generated ID of the parent entity, so generated children
+ *                   can set backward references to it
+ */
+async function resolveForwardExact(typeName, data, entity, schema, provider, parentId, resolveOptions) {
+    const resolved = { ...data };
+    const pendingRelations = [];
+    /**
+     * For union types, find which type an entity ID belongs to
+     */
+    async function findEntityType(id, types) {
+        for (const type of types) {
+            const entity = await provider.get(type, id);
+            if (entity)
+                return type;
+        }
+        return null;
+    }
+    for (const [fieldName, field] of entity.fields) {
+        if (field.operator === '->' && field.direction === 'forward') {
+            // Get all possible types (union types or just the single related type)
+            const possibleTypes = field.unionTypes || [field.relatedType];
+            // Skip if value already provided
+            if (resolved[fieldName] !== undefined && resolved[fieldName] !== null) {
+                // If value is provided for array field, we still need to create relationships
+                if (field.isArray && Array.isArray(resolved[fieldName])) {
+                    const ids = resolved[fieldName];
+                    const matchedTypes = [];
+                    for (const targetId of ids) {
+                        // For union types, determine the actual type of each ID
+                        const actualType = field.unionTypes
+                            ? (await findEntityType(targetId, possibleTypes)) || field.relatedType
+                            : field.relatedType;
+                        pendingRelations.push({ fieldName, targetType: actualType, targetId });
+                        matchedTypes.push(actualType);
+                    }
+                    // Store matched types for union type arrays
+                    if (field.unionTypes && matchedTypes.length > 0) {
+                        resolved[`${fieldName}$matchedTypes`] = matchedTypes;
+                    }
+                }
+                else if (!field.isArray) {
+                    // Single value provided - for union types, determine the actual type
+                    const providedId = resolved[fieldName];
+                    if (field.unionTypes) {
+                        const actualType = await findEntityType(providedId, possibleTypes);
+                        if (actualType) {
+                            resolved[`${fieldName}$matchedType`] = actualType;
+                        }
+                    }
+                }
+                continue;
+            }
+            // Skip optional fields - they shouldn't auto-generate
+            if (field.isOptional)
+                continue;
+            if (field.isArray) {
+                // When cascade is enabled, skip array generation - cascadeGenerate will handle it
+                // with proper depth control
+                if (resolveOptions?.skipArrayGeneration)
+                    continue;
+                // Forward array relation - check if we should auto-generate
+                const relatedEntity = schema.entities.get(field.relatedType);
+                if (!relatedEntity)
+                    continue;
+                // Check if related entity has a backward ref to this type (symmetric relationship)
+                let hasBackwardRef = false;
+                for (const [, relField] of relatedEntity.fields) {
+                    if (relField.isRelation &&
+                        relField.relatedType === typeName &&
+                        relField.direction === 'backward') {
+                        hasBackwardRef = true;
+                        break;
+                    }
+                }
+                // Check if related entity has required non-relation fields
+                let hasRequiredScalarFields = false;
+                for (const [, relField] of relatedEntity.fields) {
+                    if (!relField.isRelation && !relField.isOptional) {
+                        hasRequiredScalarFields = true;
+                        break;
+                    }
+                }
+                // Decide whether to auto-generate:
+                // - If there's a symmetric backward ref AND required scalars, skip (prevents duplicates)
+                // - Otherwise, generate if the related entity can be meaningfully generated
+                // - For union types, be more lenient to allow polymorphic generation
+                const shouldSkip = hasBackwardRef && hasRequiredScalarFields;
+                const canGenerate = !shouldSkip &&
+                    (hasBackwardRef || // Symmetric ref without required scalars
+                        field.prompt || // Has a generation prompt
+                        field.unionTypes || // Union types should generate from first type
+                        !hasRequiredScalarFields); // No required fields to worry about
+                if (!canGenerate)
+                    continue;
+                // For union types, use first type for generation
+                const generateType = field.relatedType;
+                const generated = await generateEntity(generateType, field.prompt, { parent: typeName, parentData: data, parentId }, schema);
+                // Resolve any pending nested relations in the generated data
+                const resolvedGenerated = await resolveNestedPending(generated, relatedEntity, schema, provider);
+                const created = await provider.create(generateType, undefined, resolvedGenerated);
+                resolved[fieldName] = [created['$id']];
+                // Store matched type for union types
+                if (field.unionTypes) {
+                    resolved[`${fieldName}$matchedTypes`] = [generateType];
+                }
+                // Queue relationship creation for after parent entity is created
+                pendingRelations.push({
+                    fieldName,
+                    targetType: generateType,
+                    targetId: created['$id'],
+                });
+            }
+            else {
+                // Single non-optional forward relation - generate the related entity
+                // For union types, use first type for generation
+                const generateType = field.relatedType;
+                const generated = await generateEntity(generateType, field.prompt, { parent: typeName, parentData: data, parentId }, schema);
+                // Resolve any pending nested relations in the generated data
+                const relatedEntity = schema.entities.get(generateType);
+                if (relatedEntity) {
+                    const resolvedGenerated = await resolveNestedPending(generated, relatedEntity, schema, provider);
+                    const created = await provider.create(generateType, undefined, resolvedGenerated);
+                    resolved[fieldName] = created['$id'];
+                    // Mark this forward ref as auto-generated so hydrateEntity knows to create a proxy
+                    resolved[`${fieldName}$autoGenerated`] = true;
+                    // Store matched type for union types
+                    if (field.unionTypes) {
+                        resolved[`${fieldName}$matchedType`] = generateType;
+                    }
+                }
+            }
+        }
+    }
+    return { data: resolved, pendingRelations };
+}
+/**
+ * Generate a simple entity with only scalar fields populated
+ *
+ * This is used by cascade generation to avoid infinite recursion.
+ * Unlike generateEntity, this does NOT recursively generate nested relations.
+ *
+ * @param type - The type of entity to generate
+ * @param prompt - Optional prompt for generation context
+ * @param context - Parent context information
+ * @param entityDef - The parsed entity definition
+ */
+function generateSimpleEntity(type, prompt, context, entityDef, schema) {
+    const data = {};
+    // Build context from parent $instructions and child $instructions
+    const contextParts = [];
+    if (schema) {
+        const parentEntity = schema.entities.get(context.parent);
+        const parentInstructions = parentEntity?.schema?.['$instructions'];
+        const childInstructions = entityDef.schema?.['$instructions'];
+        if (parentInstructions)
+            contextParts.push(parentInstructions);
+        if (childInstructions)
+            contextParts.push(childInstructions);
+    }
+    if (prompt)
+        contextParts.push(prompt);
+    for (const [key, value] of Object.entries(context.parentData)) {
+        if (!key.startsWith('$') && !key.startsWith('_') && typeof value === 'string' && value) {
+            contextParts.push(`${key}: ${value}`);
+        }
+    }
+    const fullContext = contextParts.filter(Boolean).join(' | ');
+    for (const [fieldName, field] of entityDef.fields) {
+        if (!field.isRelation) {
+            const isPrompt = isPromptField(field);
+            if (field.type === 'string' || isPrompt) {
+                const fieldHint = isPrompt ? field.type : prompt;
+                data[fieldName] = generateContextAwareValue(fieldName, type, fullContext, fieldHint);
+            }
+            else if (field.isArray && (field.type === 'string' || isPrompt)) {
+                const fieldHint = isPrompt ? field.type : prompt;
+                data[fieldName] = [generateContextAwareValue(fieldName, type, fullContext, fieldHint)];
+            }
+        }
+        else if (field.operator === '<-' && field.direction === 'backward') {
+            // Backward relation to parent
+            if (field.relatedType === context.parent && context.parentId) {
+                data[fieldName] = context.parentId;
+            }
+        }
+        // Skip forward relations - cascade will handle them
+    }
+    return data;
+}
+/**
+ * Recursively generate related entities through cascade relationships
+ *
+ * This function traverses -> and ~> array relationships and generates
+ * child entities at each level, respecting depth limits and type filters.
+ *
+ * @param entity - The parent entity data
+ * @param entityDef - The parsed entity definition
+ * @param schema - The parsed schema
+ * @param provider - The database provider
+ * @param options - Cascade options including maxDepth and type filters
+ * @param depth - Current recursion depth
+ * @param progress - Progress tracking object (mutated)
+ */
+async function cascadeGenerate(entity, entityDef, schema, provider, options, depth, progress) {
+    const maxDepth = options.maxDepth ?? 3;
+    // Hard safety cap to prevent infinite recursion with circular schemas
+    const effectiveMax = Math.min(maxDepth, DEFAULT_MAX_DEPTH);
+    // Stop if we've reached max depth
+    if (depth >= effectiveMax)
+        return;
+    // Report progress at this depth (even if no relations to process)
+    progress.currentDepth = depth;
+    progress.depth = depth;
+    options.onProgress?.({ ...progress, phase: 'generating' });
+    const entityId = (entity['$id'] || entity['id']);
+    for (const [fieldName, field] of entityDef.fields) {
+        // Only cascade through forward relationships (-> or ~>) that are arrays
+        // or single references that haven't been populated yet
+        const isForwardRelation = field.operator === '->' || field.operator === '~>';
+        const isGeneratableRelation = isForwardRelation && field.relatedType;
+        if (!isGeneratableRelation)
+            continue;
+        // Check if this type should be cascaded (if cascadeTypes filter is set)
+        if (options.cascadeTypes && !options.cascadeTypes.includes(field.relatedType)) {
+            continue;
+        }
+        // Report progress for this type
+        progress.currentDepth = depth;
+        progress.depth = depth;
+        if (field.relatedType !== undefined) {
+            progress.currentType = field.relatedType;
+        }
+        options.onProgress?.({ ...progress, phase: 'generating' });
+        try {
+            const relatedEntityDef = schema.entities.get(field.relatedType);
+            if (!relatedEntityDef)
+                continue;
+            // Check if field already has values (from existing resolution)
+            const existingValue = entity[fieldName];
+            if (existingValue && Array.isArray(existingValue) && existingValue.length > 0) {
+                // Already has values, cascade into each child
+                for (const childId of existingValue) {
+                    const childData = await provider.get(field.relatedType, childId);
+                    if (childData) {
+                        await cascadeGenerate(childData, relatedEntityDef, schema, provider, options, depth + 1, progress);
+                    }
+                }
+                continue;
+            }
+            else if (existingValue && typeof existingValue === 'string') {
+                // Single reference already populated, cascade into it
+                const childData = await provider.get(field.relatedType, existingValue);
+                if (childData) {
+                    await cascadeGenerate(childData, relatedEntityDef, schema, provider, options, depth + 1, progress);
+                }
+                continue;
+            }
+            // Generate new related entities
+            if (field.isArray) {
+                // Generate array of related entities using AI-enabled generation
+                const generated = await cascadeGenerateEntity(field.relatedType, field.prompt, { parent: entityDef.name, parentData: entity, parentId: entityId }, schema);
+                const created = await provider.create(field.relatedType, undefined, generated);
+                // Update the parent entity with the new relation
+                const existingIds = entity[fieldName] || [];
+                const newIds = [...existingIds, created['$id']];
+                await provider.update(entityDef.name, entityId, { [fieldName]: newIds });
+                entity[fieldName] = newIds;
+                // Create relationship
+                await provider.relate(entityDef.name, entityId, fieldName, field.relatedType, created['$id']);
+                progress.totalEntitiesCreated++;
+                if (!progress.typesGenerated.includes(field.relatedType)) {
+                    progress.typesGenerated.push(field.relatedType);
+                }
+                // Recursively cascade into the new child
+                await cascadeGenerate(created, relatedEntityDef, schema, provider, options, depth + 1, progress);
+            }
+            else {
+                // Generate single related entity using AI-enabled generation
+                const generated = await cascadeGenerateEntity(field.relatedType, field.prompt, { parent: entityDef.name, parentData: entity, parentId: entityId }, schema);
+                const created = await provider.create(field.relatedType, undefined, generated);
+                // Update the parent entity with the new relation
+                await provider.update(entityDef.name, entityId, { [fieldName]: created['$id'] });
+                entity[fieldName] = created['$id'];
+                progress.totalEntitiesCreated++;
+                if (!progress.typesGenerated.includes(field.relatedType)) {
+                    progress.typesGenerated.push(field.relatedType);
+                }
+                // Recursively cascade into the new child
+                await cascadeGenerate(created, relatedEntityDef, schema, provider, options, depth + 1, progress);
+            }
+        }
+        catch (error) {
+            options.onError?.(error, { type: field.relatedType, depth });
+            if (options.stopOnError)
+                throw error;
+        }
+    }
+}
+/**
+ * Resolve backward fuzzy (<~) fields by using semantic search to find existing entities
+ *
+ * The <~ operator differs from <- in that it uses semantic/fuzzy matching:
+ * - Uses AI/embedding-based similarity to find the best match from existing entities
+ * - Does NOT generate new entities - only grounds to existing reference data
+ * - Uses hint fields (e.g., categoryHint for category field) to guide matching
+ *
+ * @param typeName - The type of entity being created
+ * @param data - The input data including hint fields
+ * @param entity - The parsed entity definition
+ * @param schema - The parsed schema
+ * @param provider - The database provider (must support semanticSearch)
+ * @returns The resolved data with backward fuzzy fields populated with matched entity IDs
+ */
+async function resolveBackwardFuzzy(typeName, data, entity, schema, provider) {
+    const resolved = { ...data };
+    // Type-safe access to schema metadata with default fallback
+    const schemaWithMeta = entity.schema;
+    const threshold = schemaWithMeta?.$fuzzyThreshold ?? 0.75;
+    /**
+     * Search all union types in parallel and return matches
+     */
+    async function searchUnionTypes(types, searchQuery, threshold, limit) {
+        if (!hasSemanticSearch(provider))
+            return [];
+        // Search all types in parallel
+        const allMatches = await Promise.all(types.map(async (type) => {
+            const matches = await provider.semanticSearch(type, searchQuery, {
+                minScore: threshold,
+                limit,
+            });
+            return matches.map((m) => ({ id: m.$id, type, score: m.$score }));
+        }));
+        // Flatten and sort by score (best first)
+        return allMatches.flat().sort((a, b) => b.score - a.score);
+    }
+    for (const [fieldName, field] of entity.fields) {
+        if (field.operator === '<~' && field.direction === 'backward') {
+            // Skip if value already provided
+            if (resolved[fieldName] !== undefined && resolved[fieldName] !== null) {
+                continue;
+            }
+            // Get the hint field value - uses fieldNameHint convention
+            const hintKey = `${fieldName}Hint`;
+            const searchQuery = data[hintKey] || field.prompt || '';
+            // Skip if no search query available (optional fields without hint)
+            if (!searchQuery) {
+                continue;
+            }
+            // Get all types to search (union types or just the single related type)
+            const typesToSearch = field.unionTypes || [field.relatedType];
+            // Check if provider supports semantic search
+            if (hasSemanticSearch(provider)) {
+                if (field.unionTypes && field.unionTypes.length > 0) {
+                    // Union type - search all types
+                    const matches = await searchUnionTypes(typesToSearch, searchQuery, threshold, field.isArray ? 10 : 1);
+                    if (matches.length > 0) {
+                        if (field.isArray) {
+                            // For array fields, return all matches above threshold
+                            const validMatches = matches.filter((m) => m.score >= threshold);
+                            resolved[fieldName] = validMatches.map((m) => m.id);
+                            resolved[`${fieldName}$matchedTypes`] = validMatches.map((m) => m.type);
+                            resolved[`${fieldName}$scores`] = validMatches.map((m) => m.score);
+                            resolved[`${fieldName}$searchOrder`] = typesToSearch;
+                            // Check if any match came from a non-first type (fallback)
+                            const firstType = typesToSearch[0];
+                            const fallbackUsed = validMatches.some((m) => m.type !== firstType);
+                            if (fallbackUsed) {
+                                resolved[`${fieldName}$fallbackUsed`] = true;
+                            }
+                        }
+                        else {
+                            // For single fields, return the best match
+                            const firstMatch = matches[0];
+                            if (firstMatch) {
+                                resolved[fieldName] = firstMatch.id;
+                                resolved[`${fieldName}$matchedType`] = firstMatch.type;
+                                resolved[`${fieldName}$score`] = firstMatch.score;
+                                resolved[`${fieldName}$searchOrder`] = typesToSearch;
+                                // Fallback is triggered if the matched type is not the first type in the union
+                                const firstType = typesToSearch[0];
+                                if (firstMatch.type !== firstType) {
+                                    resolved[`${fieldName}$fallbackUsed`] = true;
+                                }
+                            }
+                        }
+                    }
+                }
+                else {
+                    // Non-union type - use standard search
+                    const matches = await provider.semanticSearch(field.relatedType, searchQuery, {
+                        minScore: threshold,
+                        limit: field.isArray ? 10 : 1,
+                    });
+                    if (matches.length > 0) {
+                        if (field.isArray) {
+                            // For array fields, return all matches above threshold
+                            // SemanticSearchResult has $id and $score properties
+                            resolved[fieldName] = matches.filter((m) => m.$score >= threshold).map((m) => m.$id);
+                        }
+                        else {
+                            // For single fields, return the best match
+                            const firstMatch = matches[0];
+                            if (firstMatch) {
+                                resolved[fieldName] = firstMatch.$id;
+                            }
+                        }
+                    }
+                }
+            }
+            // Note: <~ typically doesn't generate - it grounds to existing data
+            // If no match found and field is optional, leave as undefined
+        }
+    }
+    return resolved;
+}
+/**
+ * Resolve forward fuzzy (~>) fields via semantic search then generation
+ *
+ * The ~> operator differs from -> in that it first attempts semantic search:
+ * - Searches existing entities via embedding similarity
+ * - If a match is found above threshold, reuses the existing entity
+ * - If no match is found, generates a new entity
+ * - Respects configurable similarity threshold ($fuzzyThreshold or field-level)
+ *
+ * @param typeName - The type of entity being created
+ * @param data - The input data including hint fields
+ * @param entity - The parsed entity definition
+ * @param schema - The parsed schema
+ * @param provider - The database provider (must support semanticSearch)
+ * @param parentId - Pre-generated ID of the parent entity for backward refs
+ * @returns Object with resolved data and pending relations for array fields
+ */
+async function resolveForwardFuzzy(typeName, data, entity, schema, provider, parentId) {
+    const resolved = { ...data };
+    const pendingRelations = [];
+    // Type-safe access to schema metadata with default fallback
+    const schemaWithMeta = entity.schema;
+    const defaultThreshold = schemaWithMeta?.$fuzzyThreshold ?? 0.75;
+    /**
+     * Search all union types in parallel and return the best match
+     */
+    async function searchUnionTypes(types, searchQuery, threshold) {
+        if (!hasSemanticSearch(provider))
+            return null;
+        const allMatches = await Promise.all(types.map(async (type) => {
+            const matches = await provider.semanticSearch(type, searchQuery, {
+                minScore: threshold,
+                limit: 3,
+            });
+            return matches.map((m) => ({ ...m, $matchedType: type }));
+        }));
+        // Flatten and find the best match
+        const flat = allMatches.flat();
+        if (flat.length === 0)
+            return null;
+        const best = flat.reduce((a, b) => (a.$score > b.$score ? a : b));
+        return best.$score >= threshold
+            ? { id: best.$id, type: best.$matchedType, score: best.$score }
+            : null;
+    }
+    for (const [fieldName, field] of entity.fields) {
+        if (field.operator === '~>' && field.direction === 'forward') {
+            // Skip if value already provided (e.g., resolved by draft/resolve pipeline)
+            if (resolved[fieldName] !== undefined && resolved[fieldName] !== null) {
+                if (field.isArray && Array.isArray(resolved[fieldName])) {
+                    // Array field - create relationships with matched type metadata
+                    const ids = resolved[fieldName];
+                    const matchedTypes = resolved[`${fieldName}$matchedTypes`];
+                    for (let i = 0; i < ids.length; i++) {
+                        const targetType = matchedTypes?.[i] || field.relatedType;
+                        pendingRelations.push({
+                            fieldName,
+                            targetType,
+                            targetId: ids[i],
+                            matchedType: targetType,
+                        });
+                    }
+                }
+                else if (typeof resolved[fieldName] === 'string') {
+                    // Single field - create relationship with matched type metadata
+                    const targetId = resolved[fieldName];
+                    const matchedType = resolved[`${fieldName}$matchedType`] || field.relatedType;
+                    const score = resolved[`${fieldName}$score`];
+                    pendingRelations.push({
+                        fieldName,
+                        targetType: matchedType,
+                        targetId,
+                        ...(score !== undefined ? { similarity: score } : {}),
+                        matchedType,
+                    });
+                }
+                continue;
+            }
+            // Get the hint field value - uses fieldNameHint convention
+            const hintKey = `${fieldName}Hint`;
+            const hintValue = data[hintKey];
+            const searchQuery = (typeof hintValue === 'string' ? hintValue : undefined) || field.prompt || fieldName;
+            // Get threshold - field-level overrides entity-level
+            const threshold = field.threshold ?? defaultThreshold;
+            // Get all types to search (union types or just the single related type)
+            const typesToSearch = field.unionTypes || [field.relatedType];
+            if (field.isArray) {
+                // Array fuzzy field - can contain both matched and generated
+                const hints = Array.isArray(hintValue) ? hintValue : [hintValue].filter(Boolean);
+                const resultIds = [];
+                const matchedTypes = [];
+                for (const hint of hints) {
+                    const hintStr = String(hint || fieldName);
+                    let matched = false;
+                    // Try semantic search across all union types
+                    const match = await searchUnionTypes(typesToSearch, hintStr, threshold);
+                    if (match) {
+                        resultIds.push(match.id);
+                        matchedTypes.push(match.type);
+                        pendingRelations.push({
+                            fieldName,
+                            targetType: match.type,
+                            targetId: match.id,
+                            similarity: match.score,
+                            matchedType: match.type,
+                        });
+                        matched = true;
+                    }
+                    // Generate if no match found - use first type in union
+                    if (!matched) {
+                        const generateType = typesToSearch[0];
+                        const generated = await generateEntity(generateType, hintStr, { parent: typeName, parentData: data, parentId }, schema);
+                        // Resolve any pending nested relations
+                        const relatedEntity = schema.entities.get(generateType);
+                        if (relatedEntity) {
+                            const resolvedGenerated = await resolveNestedPending(generated, relatedEntity, schema, provider);
+                            const created = await provider.create(generateType, undefined, {
+                                ...resolvedGenerated,
+                                $generated: true,
+                                $generatedBy: parentId,
+                                $sourceField: fieldName,
+                            });
+                            resultIds.push(created['$id']);
+                            matchedTypes.push(generateType);
+                            pendingRelations.push({
+                                fieldName,
+                                targetType: generateType,
+                                targetId: created['$id'],
+                                matchedType: generateType,
+                            });
+                        }
+                    }
+                }
+                resolved[fieldName] = resultIds;
+                // Store matched types for array fields
+                if (matchedTypes.length > 0) {
+                    resolved[`${fieldName}$matchedTypes`] = matchedTypes;
+                }
+            }
+            else {
+                // Single fuzzy field
+                let matched = false;
+                // Try semantic search across all union types
+                const match = await searchUnionTypes(typesToSearch, searchQuery, threshold);
+                if (match) {
+                    resolved[fieldName] = match.id;
+                    resolved[`${fieldName}$matched`] = true;
+                    resolved[`${fieldName}$score`] = match.score;
+                    resolved[`${fieldName}$matchedType`] = match.type;
+                    pendingRelations.push({
+                        fieldName,
+                        targetType: match.type,
+                        targetId: match.id,
+                        similarity: match.score,
+                        matchedType: match.type,
+                    });
+                    matched = true;
+                }
+                // Generate if no match found - use first type in union
+                if (!matched) {
+                    const generateType = typesToSearch[0];
+                    const generated = await generateEntity(generateType, searchQuery, // Use searchQuery which prioritizes hint over field.prompt
+                    { parent: typeName, parentData: data, parentId }, schema);
+                    // Resolve any pending nested relations
+                    const relatedEntity = schema.entities.get(generateType);
+                    if (relatedEntity) {
+                        const resolvedGenerated = await resolveNestedPending(generated, relatedEntity, schema, provider);
+                        const created = await provider.create(generateType, undefined, {
+                            ...resolvedGenerated,
+                            $generated: true,
+                            $generatedBy: parentId,
+                            $sourceField: fieldName,
+                        });
+                        resolved[fieldName] = created['$id'];
+                        resolved[`${fieldName}$matchedType`] = generateType;
+                        pendingRelations.push({
+                            fieldName,
+                            targetType: generateType,
+                            targetId: created['$id'],
+                            matchedType: generateType,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    return { data: resolved, pendingRelations };
+}
+/**
+ * Resolve pending nested relations in generated data
+ *
+ * When generateEntity encounters nested -> relations, it stores them as
+ * _pending_fieldName entries. This function creates those entities and
+ * replaces the pending entries with actual IDs.
+ */
+async function resolveNestedPending(data, entity, schema, provider) {
+    const resolved = { ...data };
+    for (const key of Object.keys(resolved)) {
+        if (key.startsWith('_pending_')) {
+            const fieldName = key.replace('_pending_', '');
+            const pending = resolved[key];
+            delete resolved[key];
+            // Get the field definition to check if it's an array
+            const field = entity.fields.get(fieldName);
+            // Get the related entity to resolve its nested pending relations too
+            const relatedEntity = schema.entities.get(pending.type);
+            if (relatedEntity) {
+                const resolvedNested = await resolveNestedPending(pending.data, relatedEntity, schema, provider);
+                const created = await provider.create(pending.type, undefined, resolvedNested);
+                // Set as array or single value based on field definition
+                resolved[fieldName] = field?.isArray ? [created['$id']] : created['$id'];
+            }
+        }
+    }
+    return resolved;
+}
 // =============================================================================
-// Re-exports from schema/index.ts (main factory and operations)
+// Two-Phase Draft/Resolve Helper Functions
 // =============================================================================
-export { 
-// Noun/Verb helpers
-defineNoun, defineVerb, nounToSchema, 
-// Built-in schemas
-ThingSchema, NounSchema, VerbSchema, EdgeSchema, SystemSchema, 
-// Schema utilities
-createEdgeRecords, createNounRecord, 
-// NL Query
-setNLQueryGenerator, 
-// DB Factory
-DB, } from './schema/index.js';
+/**
+ * Resolve a single reference specification to an entity ID
+ *
+ * For exact matches (-> and <-), creates new entities.
+ * For fuzzy matches (~> and <~), searches for existing entities first.
+ */
+async function resolveReferenceSpec(spec, contextData, schema, provider) {
+    const targetEntity = schema.entities.get(spec.type);
+    if (!targetEntity) {
+        throw new Error(`Unknown target type: ${spec.type}`);
+    }
+    if (spec.matchMode === 'fuzzy') {
+        // For fuzzy references, try to find an existing entity first
+        if (hasSemanticSearch(provider)) {
+            const searchQuery = spec.generatedText || spec.prompt || spec.field;
+            const threshold = spec.threshold ?? 0.75;
+            // Search across all union types (or just the single type)
+            const typesToSearch = spec.unionTypes || [spec.type];
+            let bestMatch = null;
+            for (const searchType of typesToSearch) {
+                const matches = await provider.semanticSearch(searchType, searchQuery, {
+                    minScore: threshold,
+                    limit: 1,
+                });
+                if (matches.length > 0 && matches[0]) {
+                    if (!bestMatch || matches[0].$score > bestMatch.$score) {
+                        bestMatch = {
+                            $id: matches[0].$id,
+                            $score: matches[0].$score,
+                            $matchedType: searchType,
+                        };
+                    }
+                }
+            }
+            if (bestMatch) {
+                // Set metadata on contextData so it's available in the resolved entity
+                contextData[`${spec.field}$matched`] = true;
+                contextData[`${spec.field}$score`] = bestMatch.$score;
+                contextData[`${spec.field}$matchedType`] = bestMatch.$matchedType;
+                return bestMatch.$id;
+            }
+        }
+        // If no match found for fuzzy, fall through to create
+    }
+    // Create a new entity
+    const generatedData = {};
+    // Build context for generation from contextData
+    const genCtxParts = [];
+    // Include $instructions from source entity schema (injected during resolve)
+    if (typeof contextData['$instructions'] === 'string') {
+        genCtxParts.push(contextData['$instructions']);
+    }
+    // Include target entity's $instructions
+    const tgtInstructions = targetEntity.schema?.['$instructions'];
+    if (typeof tgtInstructions === 'string') {
+        genCtxParts.push(tgtInstructions);
+    }
+    // Include spec prompt
+    if (spec.prompt) {
+        genCtxParts.push(spec.prompt);
+    }
+    for (const [key, value] of Object.entries(contextData)) {
+        if (!key.startsWith('$') && !key.startsWith('_') && typeof value === 'string' && value) {
+            genCtxParts.push(`${key}: ${value}`);
+        }
+    }
+    const genCtx = genCtxParts.filter(Boolean).join(' | ');
+    // Generate default values for the target entity's fields
+    for (const [fieldName, field] of targetEntity.fields) {
+        if (!field.isRelation) {
+            const isPrompt = isPromptField(field);
+            // Generate both required fields and optional prompt fields
+            if (!field.isOptional || isPrompt) {
+                if (field.type === 'string' || isPrompt) {
+                    const fldHint = isPrompt ? field.type : undefined;
+                    generatedData[fieldName] = generateContextAwareValue(fieldName, spec.type, genCtx, fldHint);
+                }
+                else if (field.type === 'number') {
+                    generatedData[fieldName] = 0;
+                }
+                else if (field.type === 'boolean') {
+                    generatedData[fieldName] = false;
+                }
+            }
+        }
+        else if (field.isRelation && field.operator === '->' && !field.isArray && !field.isOptional) {
+            // Recursively resolve nested forward exact relations
+            const nestedSpec = {
+                field: fieldName,
+                operator: '->',
+                type: field.relatedType,
+                matchMode: 'exact',
+                resolved: false,
+                ...(field.prompt !== undefined && { prompt: field.prompt }),
+            };
+            const nestedId = await resolveReferenceSpec(nestedSpec, generatedData, schema, provider);
+            if (nestedId) {
+                generatedData[fieldName] = nestedId;
+            }
+        }
+    }
+    const created = await provider.create(spec.type, undefined, {
+        ...generatedData,
+        $generated: true,
+        $generatedBy: contextData['$id'] ||
+            (spec.matchMode === 'fuzzy' ? 'fuzzy-resolution' : 'reference-resolution'),
+        $sourceField: spec.field,
+    });
+    return created['$id'];
+}
+/**
+ * Create operations for a single entity type
+ */
+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);
+        },
+        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)));
+            }
+            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();
+            // Partial<T> is a subset of Record<string, unknown> - safe cast for provider API
+            const results = await provider.list(typeName, {
+                where: where,
+            });
+            // hydrateEntity returns Record<string, unknown>, cast to T for type-safe API
+            return Promise.all(results.map((r) => hydrateEntity(r, entity, schema)));
+        },
+        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)));
+        },
+        async create(idOrData, maybeDataOrOptions, maybeOptions) {
+            const provider = await resolveProvider();
+            // Parse arguments: support both (data, options) and (id, data, options) signatures
+            // Type assertions are necessary here because T extends Record<string, unknown>
+            // but TypeScript can't infer this from the Omit<T, ...> type
+            let providedId;
+            let data;
+            let options;
+            if (typeof idOrData === 'string') {
+                // First arg is ID - maybeDataOrOptions must be the data object
+                providedId = idOrData;
+                // Safe cast: maybeDataOrOptions is Omit<T, '$id' | '$type'> which extends Record
+                data = (maybeDataOrOptions ?? {});
+                options = maybeOptions;
+            }
+            else {
+                // First arg is data - safe cast since idOrData is Omit<T, '$id' | '$type'>
+                providedId = undefined;
+                data = idOrData;
+                // Check if second arg is options by detecting option-specific properties
+                if (maybeDataOrOptions &&
+                    typeof maybeDataOrOptions === 'object' &&
+                    ('cascade' in maybeDataOrOptions ||
+                        'maxDepth' in maybeDataOrOptions ||
+                        'onProgress' in maybeDataOrOptions ||
+                        'onError' in maybeDataOrOptions ||
+                        'draftOnly' in maybeDataOrOptions ||
+                        'cascadeTypes' in maybeDataOrOptions ||
+                        'stopOnError' in maybeDataOrOptions)) {
+                    options = maybeDataOrOptions;
+                }
+            }
+            // Pre-generate entity ID so child entities can reference us
+            const entityId = providedId || crypto.randomUUID();
+            // Resolve forward exact (->) fields by auto-generating related entities
+            // Pass the entityId so generated children can set backward references
+            // When cascade is enabled, skip auto-generation for array fields - cascadeGenerate will handle them
+            const { data: resolvedData, pendingRelations } = await resolveForwardExact(typeName, data, entity, schema, provider, entityId, { skipArrayGeneration: true });
+            // Resolve forward fuzzy (~>) fields by semantic search then generation
+            const { data: fuzzyResolvedData, pendingRelations: fuzzyPendingRelations } = await resolveForwardFuzzy(typeName, resolvedData, entity, schema, provider, entityId);
+            // Resolve backward fuzzy (<~) fields by semantic search against existing entities
+            const backwardResolvedData = await resolveBackwardFuzzy(typeName, fuzzyResolvedData, entity, schema, provider);
+            // Generate AI fields for entities with $context dependencies
+            // This handles prompt fields like 'string (compelling title)' that need context
+            const finalData = await generateAIFields(backwardResolvedData, typeName, entity, schema, provider);
+            let result;
+            try {
+                result = await provider.create(typeName, entityId, finalData);
+            }
+            catch (error) {
+                if (error instanceof DatabaseError)
+                    throw error;
+                throw wrapDatabaseError(error, 'create', typeName, entityId);
+            }
+            // Create relationships for array fields (exact)
+            for (const rel of pendingRelations) {
+                await provider.relate(typeName, entityId, rel.fieldName, rel.targetType, rel.targetId);
+            }
+            // Create relationships for fuzzy fields with metadata
+            // Track created Edge IDs to avoid duplicates
+            const createdEdgeIds = new Set();
+            for (const rel of fuzzyPendingRelations) {
+                await provider.relate(typeName, entityId, rel.fieldName, rel.targetType, rel.targetId, {
+                    matchMode: 'fuzzy',
+                    ...(rel.similarity !== undefined && { similarity: rel.similarity }),
+                });
+                // Also create an Edge entity to store the fuzzy match metadata
+                // Use a unique ID based on the relationship
+                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,
+                            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);
+                        }
+                    }
+                }
+            }
+            // If cascade is enabled, recursively generate related entities
+            if (options?.cascade) {
+                const progress = {
+                    phase: 'generating',
+                    currentDepth: 0,
+                    depth: 0,
+                    currentType: typeName,
+                    totalEntitiesCreated: 1, // Count the root entity
+                    typesGenerated: [typeName],
+                };
+                // Report initial progress
+                options.onProgress?.({ ...progress });
+                try {
+                    await cascadeGenerate(result, entity, schema, provider, options, 0, progress);
+                    // Report completion
+                    progress.phase = 'complete';
+                    options.onProgress?.({ ...progress });
+                }
+                catch (error) {
+                    progress.phase = 'error';
+                    options.onProgress?.({ ...progress });
+                    if (options.stopOnError)
+                        throw error;
+                }
+            }
+            return hydrateEntity(result, entity, schema);
+        },
+        async update(id, data) {
+            try {
+                const provider = await resolveProvider();
+                // Partial<Omit<T, ...>> is a subset of Record<string, unknown> - safe cast for provider API
+                const result = await provider.update(typeName, id, data);
+                return hydrateEntity(result, entity, schema);
+            }
+            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);
+                // Omit<T, ...> is a subset of Record<string, unknown> - safe cast for provider API
+                if (existing) {
+                    const result = await provider.update(typeName, id, data);
+                    return hydrateEntity(result, entity, schema);
+                }
+                const result = await provider.create(typeName, id, data);
+                return hydrateEntity(result, entity, schema);
+            }
+            catch (error) {
+                if (error instanceof DatabaseError)
+                    throw error;
+                throw wrapDatabaseError(error, 'upsert', typeName, id);
+            }
+        },
+        async delete(id) {
+            try {
+                const provider = await resolveProvider();
+                const result = await provider.delete(typeName, id);
+                return result;
+            }
+            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),
+                $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),
+                $rrfScore: r.$rrfScore,
+                $ftsRank: r.$ftsRank,
+                $semanticRank: r.$semanticRank,
+                $score: r.$score,
+            })));
+        },
+        async draft(data, options) {
+            const draftData = { ...data, $phase: 'draft' };
+            const refs = {};
+            // Process each field that has a relationship operator
+            for (const [fieldName, field] of entity.fields) {
+                // Skip if value already provided
+                if (draftData[fieldName] !== undefined && draftData[fieldName] !== null) {
+                    continue;
+                }
+                // Handle non-relation prompt fields (like 'Write a detailed article')
+                if (!field.isRelation) {
+                    const isPrompt = isPromptField(field);
+                    if (isPrompt) {
+                        // Build context for generation
+                        const ctxParts = [];
+                        const entitySchemaForCtx = entity.schema;
+                        if (entitySchemaForCtx?.['$instructions']) {
+                            ctxParts.push(entitySchemaForCtx['$instructions']);
+                        }
+                        for (const [k, v] of Object.entries(data)) {
+                            if (!k.startsWith('$') && !k.startsWith('_') && typeof v === 'string' && v) {
+                                ctxParts.push(`${k}: ${v}`);
+                            }
+                        }
+                        const draftCtx = ctxParts.filter(Boolean).join(' | ');
+                        const generatedText = generateContextAwareValue(fieldName, typeName, draftCtx, field.type);
+                        draftData[fieldName] = generatedText;
+                        if (options?.stream && options.onChunk) {
+                            options.onChunk(generatedText);
+                        }
+                    }
+                    continue;
+                }
+                // Only process fields with relationship operators
+                if (field.operator && field.relatedType) {
+                    // Skip optional relation fields - they shouldn't auto-generate
+                    if (field.isOptional)
+                        continue;
+                    // Skip backward references - they are resolved lazily via hydrateEntity
+                    if (field.operator === '<-' || field.operator === '<~')
+                        continue;
+                    const matchMode = field.matchMode ?? (field.operator.includes('~') ? 'fuzzy' : 'exact');
+                    // data is Partial<Omit<T, ...>> which extends Record<string, unknown>
+                    // The cast is safe because we're accessing arbitrary properties
+                    const dataRecord = data;
+                    // Get fuzzy threshold: field-level overrides entity-level
+                    const entitySchemaRaw = entity.schema;
+                    const entityThreshold = entitySchemaRaw && '$fuzzyThreshold' in entitySchemaRaw
+                        ? entitySchemaRaw['$fuzzyThreshold']
+                        : undefined;
+                    const threshold = field.threshold ?? entityThreshold;
+                    if (field.isArray) {
+                        // Array relationship - check for hint values
+                        const hintKey = `${fieldName}Hint`;
+                        const hintValue = dataRecord[hintKey];
+                        const hints = Array.isArray(hintValue)
+                            ? hintValue
+                            : hintValue
+                                ? [hintValue]
+                                : [
+                                    generateNaturalLanguageContent(fieldName, field.prompt, field.relatedType, dataRecord),
+                                ];
+                        const refSpecs = hints.map((hint) => {
+                            const generatedText = String(hint);
+                            return {
+                                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 }),
+                                ...(threshold !== undefined && { threshold }),
+                            };
+                        });
+                        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 {
+                        // Single relationship - check for hint values
+                        const hintKey = `${fieldName}Hint`;
+                        const hintValue = dataRecord[hintKey];
+                        const generatedText = hintValue ||
+                            generateNaturalLanguageContent(fieldName, field.prompt, field.relatedType, dataRecord);
+                        draftData[fieldName] = generatedText;
+                        refs[fieldName] = {
+                            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 }),
+                            ...(threshold !== undefined && { threshold }),
+                        };
+                        if (options?.stream && options.onChunk) {
+                            options.onChunk(generatedText);
+                        }
+                    }
+                }
+            }
+            draftData['$refs'] = refs;
+            // draftData has all Draft<T> properties - safe to return as Draft<T>
+            return draftData;
+        },
+        async resolve(draft, options) {
+            // Validate that this is actually a draft - use type guard for safe access
+            if (!isDraft(draft)) {
+                throw new Error('Cannot resolve entity: not a draft (missing $phase: "draft")');
+            }
+            const provider = await resolveProvider();
+            const resolved = { ...draft };
+            const errors = [];
+            // Inject $instructions from entity schema into resolved context for reference resolution
+            const entityInstructions = entity.schema?.['$instructions'];
+            if (entityInstructions && typeof entityInstructions === 'string') {
+                resolved['$instructions'] = entityInstructions;
+            }
+            // Remove draft markers
+            delete resolved['$refs'];
+            resolved['$phase'] = 'resolved';
+            // Extract refs using type guard - safe access since isDraft validated
+            const refs = (extractRefs(draft) || {});
+            // Resolve each reference
+            for (const [fieldName, refSpec] of Object.entries(refs)) {
+                try {
+                    if (Array.isArray(refSpec)) {
+                        // Array of references
+                        const resolvedIds = [];
+                        for (const spec of refSpec) {
+                            const resolvedId = await resolveReferenceSpec(spec, resolved, schema, provider);
+                            if (resolvedId) {
+                                resolvedIds.push(resolvedId);
+                                options?.onResolved?.(fieldName, resolvedId);
+                            }
+                        }
+                        resolved[fieldName] = resolvedIds;
+                    }
+                    else {
+                        // Single reference
+                        const resolvedId = await resolveReferenceSpec(refSpec, resolved, schema, provider);
+                        if (resolvedId) {
+                            resolved[fieldName] = resolvedId;
+                            // Mark as auto-generated so hydrateEntity creates a thenable proxy
+                            resolved[`${fieldName}$autoGenerated`] = true;
+                            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;
+                    }
+                }
+            }
+            // Add $errors if onError mode is 'skip' (even if empty, to indicate skip mode was used)
+            // or if there are actual errors
+            if (errors.length > 0 || options?.onError === 'skip') {
+                resolved['$errors'] = errors;
+            }
+            return resolved;
+        },
+    };
+}
+/**
+ * Hydrate an entity with lazy-loaded relations
+ *
+ * For backward edges (direction === 'backward'), we query for entities
+ * of the related type that have a reference pointing TO this entity.
+ * This enables reverse lookups like "get all comments for a post".
+ *
+ * Backward reference resolution:
+ * - Single backward ref with stored ID: resolve directly (e.g., member.team = teamId -> get Team by ID)
+ * - Single backward ref without stored ID: find related entity that points to us via relations
+ * - Array backward ref: find all entities of related type where their forward ref points to us
+ */
+function hydrateEntity(data, entity, schema) {
+    const hydrated = { ...data };
+    const id = (data['$id'] || data['id']);
+    const typeName = entity.name;
+    // Add lazy getters for relations
+    for (const [fieldName, field] of entity.fields) {
+        if (field.isRelation && field.relatedType) {
+            const relatedEntity = schema.entities.get(field.relatedType);
+            if (!relatedEntity)
+                continue;
+            // Check if this is a backward edge
+            const isBackward = field.direction === 'backward';
+            // For backward single relations with stored IDs (user-provided backward refs),
+            // create a thenable proxy so `await entity.parent` resolves to the related entity.
+            if (isBackward && !field.isArray && data[fieldName] && typeof data[fieldName] === 'string') {
+                const storedId = data[fieldName];
+                const proxyTarget = {};
+                const thenableProxy = new Proxy(proxyTarget, {
+                    get(target, prop) {
+                        if (prop === 'then') {
+                            return (resolve, reject) => {
+                                return (async () => {
+                                    const provider = await resolveProvider();
+                                    const result = await provider.get(field.relatedType, storedId);
+                                    if (!result)
+                                        return null;
+                                    return hydrateEntity(result, relatedEntity, schema);
+                                })().then(resolve, reject);
+                            };
+                        }
+                        if (prop === Symbol.toPrimitive || prop === 'valueOf') {
+                            return () => storedId;
+                        }
+                        if (prop === 'toString') {
+                            return () => storedId;
+                        }
+                        if (prop === 'match') {
+                            return (regex) => storedId.match(regex);
+                        }
+                        if (prop === '$id') {
+                            return storedId;
+                        }
+                        return undefined;
+                    },
+                });
+                hydrated[fieldName] = thenableProxy;
+                continue;
+            }
+            // For forward single relations with stored IDs, create a thenable proxy that:
+            // - Acts like a string (for .toMatch(), String(), etc.)
+            // - Can be awaited to get the related entity (thenable)
+            if (!isBackward && !field.isArray && data[fieldName]) {
+                const storedId = data[fieldName];
+                // For union types, get the actual matched type from stored metadata
+                const matchedType = data[`${fieldName}$matchedType`] || field.relatedType;
+                const actualRelatedEntity = schema.entities.get(matchedType) || relatedEntity;
+                // Create a thenable proxy - the empty object target is just a placeholder for the Proxy
+                const proxyTarget = {};
+                const thenableProxy = new Proxy(proxyTarget, {
+                    get(target, prop) {
+                        if (prop === 'then') {
+                            return (resolve, reject) => {
+                                return (async () => {
+                                    const provider = await resolveProvider();
+                                    const result = await loadEntity(provider, matchedType, storedId);
+                                    if (!result)
+                                        return null;
+                                    const hydratedResult = hydrateEntity(result, actualRelatedEntity, schema);
+                                    // Add $matchedType to the result for union type tracking
+                                    if (field.unionTypes && field.unionTypes.length > 0) {
+                                        hydratedResult.$matchedType = matchedType;
+                                    }
+                                    return hydratedResult;
+                                })().then(resolve, reject);
+                            };
+                        }
+                        if (prop === Symbol.toPrimitive || prop === 'valueOf') {
+                            return () => storedId;
+                        }
+                        if (prop === 'toString') {
+                            return () => storedId;
+                        }
+                        if (prop === 'match') {
+                            return (regex) => storedId.match(regex);
+                        }
+                        if (prop === '$type') {
+                            return matchedType;
+                        }
+                        return undefined;
+                    },
+                });
+                hydrated[fieldName] = thenableProxy;
+                continue;
+            }
+            // For forward array relations with stored IDs, create a real array proxy
+            // that passes Array.isArray() and supports synchronous .map()/.length
+            // while also being thenable for async hydration
+            if (!isBackward && field.isArray && data[fieldName]) {
+                const storedIds = data[fieldName];
+                if (Array.isArray(storedIds)) {
+                    const matchedTypes = data[`${fieldName}$matchedTypes`];
+                    // Create a real array so Array.isArray() returns true
+                    // Each element is a thenable proxy for the related entity
+                    const arrayResult = storedIds.map((targetId, index) => {
+                        const targetType = (field.unionTypes && matchedTypes?.[index]) || field.relatedType;
+                        const targetEntity = schema.entities.get(targetType) || relatedEntity;
+                        const proxyTarget = {};
+                        return new Proxy(proxyTarget, {
+                            get(_target, prop) {
+                                if (prop === 'then') {
+                                    return (resolve, reject) => {
+                                        return (async () => {
+                                            const prov = await resolveProvider();
+                                            const result = await loadEntity(prov, targetType, targetId);
+                                            if (!result)
+                                                return null;
+                                            const hydratedResult = hydrateEntity(result, targetEntity, schema);
+                                            if (field.unionTypes && field.unionTypes.length > 0) {
+                                                hydratedResult.$matchedType = targetType;
+                                            }
+                                            return hydratedResult;
+                                        })().then(resolve, reject);
+                                    };
+                                }
+                                if (prop === Symbol.toPrimitive || prop === 'valueOf') {
+                                    return () => targetId;
+                                }
+                                if (prop === 'toString') {
+                                    return () => targetId;
+                                }
+                                if (prop === '$type') {
+                                    return targetType;
+                                }
+                                if (prop === '$id') {
+                                    return targetId;
+                                }
+                                return undefined;
+                            },
+                        });
+                    });
+                    arrayResult['$type'] = field.relatedType;
+                    arrayResult['$isArrayRelation'] = true;
+                    arrayResult['then'] = (resolve, reject) => {
+                        return (async () => {
+                            const prov = await resolveProvider();
+                            const results = await Promise.all(storedIds.map(async (targetId, index) => {
+                                const targetType = (field.unionTypes && matchedTypes?.[index]) || field.relatedType;
+                                const targetEntity = schema.entities.get(targetType) || relatedEntity;
+                                const result = await loadEntity(prov, targetType, targetId);
+                                if (!result)
+                                    return null;
+                                const hydratedResult = hydrateEntity(result, targetEntity, schema);
+                                if (field.unionTypes && field.unionTypes.length > 0) {
+                                    hydratedResult.$matchedType = targetType;
+                                }
+                                return hydratedResult;
+                            }));
+                            return results.filter((r) => r !== null);
+                        })().then(resolve, reject);
+                    };
+                    hydrated[fieldName] = arrayResult;
+                    continue;
+                }
+            }
+            // For forward array relations with explicitly empty array data, set to empty array
+            if (!isBackward &&
+                field.isArray &&
+                Array.isArray(data[fieldName]) &&
+                data[fieldName].length === 0) {
+                const emptyArray = [];
+                emptyArray['$type'] = field.relatedType;
+                emptyArray['$isArrayRelation'] = true;
+                emptyArray['then'] = (resolve, _reject) => {
+                    return Promise.resolve([]).then(resolve);
+                };
+                hydrated[fieldName] = emptyArray;
+                continue;
+            }
+            // Define lazy getter
+            Object.defineProperty(hydrated, fieldName, {
+                get: () => {
+                    // Check if this is a backward edge
+                    if (isBackward && !field.isArray) {
+                        // Case 1: Single backward ref
+                        // Returns a Promise that resolves to the related entity
+                        const storedId = data[fieldName];
+                        // For backward fuzzy with union types (single field, not array)
+                        // storedId is a single ID and matchedType is the type that matched
+                        if (field.unionTypes && field.operator === '<~') {
+                            return (async () => {
+                                const singleStoredId = data[fieldName];
+                                const matchedType = data[`${fieldName}$matchedType`];
+                                if (singleStoredId) {
+                                    const provider = await resolveProvider();
+                                    const targetType = matchedType || field.relatedType;
+                                    const targetEntity = schema.entities.get(targetType);
+                                    const result = await provider.get(targetType, singleStoredId);
+                                    if (!result)
+                                        return null;
+                                    const hydratedEntity = targetEntity
+                                        ? hydrateEntity(result, targetEntity, schema)
+                                        : result;
+                                    if (hydratedEntity) {
+                                        ;
+                                        hydratedEntity.$matchedType = targetType;
+                                    }
+                                    return hydratedEntity;
+                                }
+                                // No match found - return null for single fields (not empty array)
+                                return null;
+                            })();
+                        }
+                        return (async () => {
+                            const provider = await resolveProvider();
+                            if (storedId) {
+                                // Has stored ID - directly fetch the related entity
+                                const result = await provider.get(field.relatedType, storedId);
+                                return result ? hydrateEntity(result, relatedEntity, schema) : null;
+                            }
+                            // No stored ID - find via inverse relation lookup
+                            // Find entities of relatedType that have this entity in their relations
+                            for (const [relFieldName, relField] of relatedEntity.fields) {
+                                if (relField.isRelation &&
+                                    relField.relatedType === typeName &&
+                                    relField.direction !== 'backward' &&
+                                    relField.isArray) {
+                                    // Found a forward array relation on related entity pointing to us
+                                    // Check if any entity of relatedType has this entity in that relation
+                                    const allRelated = await provider.list(field.relatedType);
+                                    for (const candidate of allRelated) {
+                                        const candidateId = (candidate['$id'] || candidate['id']);
+                                        const related = await provider.related(field.relatedType, candidateId, relFieldName);
+                                        if (related.some((r) => (r['$id'] || r['id']) === id)) {
+                                            return hydrateEntity(candidate, relatedEntity, schema);
+                                        }
+                                    }
+                                }
+                            }
+                            return null;
+                        })();
+                    }
+                    // For forward relations and backward arrays, return async resolver
+                    return (async () => {
+                        const provider = await resolveProvider();
+                        if (isBackward) {
+                            // Case 2: Array backward ref
+                            // Check if we have stored IDs (e.g., from backward fuzzy resolution)
+                            const storedIds = data[fieldName];
+                            const matchedTypes = data[`${fieldName}$matchedTypes`];
+                            if (Array.isArray(storedIds) && storedIds.length > 0) {
+                                // Use stored IDs directly - this handles backward fuzzy (<~) array fields
+                                // For union types, fetch from the correct type
+                                if (field.unionTypes && matchedTypes) {
+                                    const results = await Promise.all(storedIds.map(async (targetId, index) => {
+                                        const targetType = matchedTypes[index] || field.relatedType;
+                                        const targetEntity = schema.entities.get(targetType);
+                                        const result = await provider.get(targetType, targetId);
+                                        if (!result)
+                                            return null;
+                                        const hydratedEntity = targetEntity
+                                            ? hydrateEntity(result, targetEntity, schema)
+                                            : result;
+                                        if (hydratedEntity) {
+                                            ;
+                                            hydratedEntity.$matchedType = targetType;
+                                        }
+                                        return hydratedEntity;
+                                    }));
+                                    return results.filter((r) => r !== null);
+                                }
+                                else {
+                                    const results = await Promise.all(storedIds.map((targetId) => provider.get(field.relatedType, targetId)));
+                                    return Promise.all(results
+                                        .filter((r) => r !== null)
+                                        .map((r) => hydrateEntity(r, relatedEntity, schema)));
+                                }
+                            }
+                            // For backward fuzzy union types without stored IDs, return empty array
+                            // (the test expects at least an empty array, not null)
+                            if (field.unionTypes && field.operator === '<~') {
+                                return [];
+                            }
+                            // No stored IDs - use backref lookup
+                            // e.g., Blog.posts: ['<-Post'] - find Posts where post.blog === blog.$id
+                            // The backref tells us which field on the related type stores our ID
+                            // If no explicit backref, infer from schema relationships
+                            let backrefField = field.backref;
+                            if (!backrefField) {
+                                // Infer backref: look for a field on related entity that points to us
+                                for (const [relFieldName, relField] of relatedEntity.fields) {
+                                    if (relField.isRelation &&
+                                        relField.relatedType === typeName &&
+                                        relField.direction !== 'backward' &&
+                                        !relField.isArray) {
+                                        // Found a forward single relation pointing to us - use its name
+                                        backrefField = relFieldName;
+                                        break;
+                                    }
+                                }
+                                // Fallback to entity name lowercase if no explicit relation found
+                                if (!backrefField) {
+                                    backrefField = typeName.toLowerCase();
+                                }
+                            }
+                            // Query the related type for entities that reference this entity
+                            const results = await provider.list(field.relatedType, {
+                                where: { [backrefField]: id },
+                            });
+                            return Promise.all(results.map((r) => hydrateEntity(r, relatedEntity, schema)));
+                        }
+                        else if (field.isArray) {
+                            // Forward array relation - get related entities
+                            // For union types, we need to look up each entity from its matched type
+                            const storedIds = data[fieldName];
+                            const matchedTypes = data[`${fieldName}$matchedTypes`];
+                            if (storedIds && storedIds.length > 0) {
+                                if (field.unionTypes && matchedTypes) {
+                                    // Union type array - fetch each entity from its specific type
+                                    const results = await Promise.all(storedIds.map(async (targetId, index) => {
+                                        const targetType = matchedTypes[index] || field.relatedType;
+                                        const targetEntity = schema.entities.get(targetType);
+                                        const result = await provider.get(targetType, targetId);
+                                        if (!result)
+                                            return null;
+                                        const hydratedEntity = targetEntity
+                                            ? hydrateEntity(result, targetEntity, schema)
+                                            : result;
+                                        // Add $matchedType for union type tracking
+                                        if (hydratedEntity) {
+                                            ;
+                                            hydratedEntity.$matchedType = targetType;
+                                        }
+                                        return hydratedEntity;
+                                    }));
+                                    return results.filter((r) => r !== null);
+                                }
+                                else {
+                                    // Non-union type array with stored IDs - fetch directly by ID
+                                    const results = await Promise.all(storedIds.map((targetId) => provider.get(field.relatedType, targetId)));
+                                    return Promise.all(results
+                                        .filter((r) => r !== null)
+                                        .map((r) => hydrateEntity(r, relatedEntity, schema)));
+                                }
+                            }
+                            // No stored IDs - use standard relation lookup
+                            const results = await provider.related(entity.name, id, fieldName);
+                            return Promise.all(results.map((r) => hydrateEntity(r, relatedEntity, schema)));
+                        }
+                        else {
+                            // Forward single relation - get the stored ID and fetch
+                            const relatedId = data[fieldName];
+                            if (!relatedId)
+                                return null;
+                            const result = await provider.get(field.relatedType, relatedId);
+                            return result ? hydrateEntity(result, relatedEntity, schema) : null;
+                        }
+                    })();
+                },
+                enumerable: true,
+                configurable: true,
+            });
+        }
+    }
+    return hydrated;
+}
 // =============================================================================
-// Convenience alias
+// Re-export for convenience
 // =============================================================================
-export { parseSchema as parse } from './schema/parse.js';
+export { parseSchema as parse };
 //# sourceMappingURL=schema.js.map