ai-database 2.1.3 → 2.3.0

package/dist/schema.d.ts

@@ -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,22 +27,1102 @@
  * post.author  // Author (single)
  * post.tags    // Tag[] (array)
  * ```
- *
- * @packageDocumentation
  */
+import { DBPromise, type ForEachOptions, type ForEachResult } from './ai-promise-db.js';
+import { type EmbeddingsConfig } from './semantic.js';
+import { type EventBridgeAPI } from './eventbridge.js';
+export type { EventBridgeAPI } from './eventbridge.js';
 export type { ThingFlat, ThingExpanded, PrimitiveType, FieldDefinition, EntitySchema, DatabaseSchema, ParsedField, ParsedEntity, ParsedSchema, Verb, Noun, NounProperty, NounRelationship, TypeMeta, EntityId, Thing, Relationship, QueryOptions, ThingSearchOptions, CreateOptions, UpdateOptions, RelateOptions, Event, ActionStatus, Action, ArtifactType, Artifact, StoreArtifactOptions, EventQueryOptions, ActionQueryOptions, DBClient, DBClientExtended, CreateEventOptions as GraphCreateEventOptions, CreateActionOptions as GraphCreateActionOptions, } from './types.js';
 export { toExpanded, toFlat, Verbs, resolveUrl, resolveShortUrl, parseUrl } from './types.js';
 export type { EmbeddingsConfig } from './semantic.js';
+export { configureAIGeneration, getAIGenerationConfig, setValueGenerator, getValueGenerator, createEntityOperations, createEdgeEntityOperations, FORWARD_TO_REVERSE, BIDIRECTIONAL_PAIRS, deriveReverseVerb, fieldNameToVerb, isPassiveVerb, registerVerbPair, registerBidirectionalPair, registerFieldVerb, hasSemanticSearch, hasHybridSearch, hasEventsAPI, hasActionsAPI, hasArtifactsAPI, hasEmbeddingsConfig, computeSchemaHash, getSchemaVersion, setSchemaVersion, hasSchemaChanged, diffSchemas, describeDiff, defineMigration, runMigrations, getPendingMigrations, rollbackLastMigration, parseOperator, parseField, parseSchema, isPrimitiveType, } from './schema/index.js';
+import type { AIGenerationConfig } from './schema/cascade.js';
+export type { AIGenerationConfig, EntityOperationsConfig, GenerationDetails, SeedResult, SchemaVersionInfo, FieldChange, PossibleRename, EntityDiff, SchemaDiff, MigrationOperationType, AddEntityOperation, RemoveEntityOperation, AddFieldOperation, RemoveFieldOperation, RenameFieldOperation, ChangeTypeOperation, TransformDataOperation, MigrationOperation, Migration, MigrationResult, OperatorParseResult, DBProvider, NLQueryGenerator, NLQueryContext, NLQueryPlan, NLQueryResult, NLQueryFn, } from './schema/index.js';
+import { parseSchema } from './schema/parse.js';
+import { type DBProvider } from './schema/provider.js';
+import type { NLQueryGenerator, NLQueryContext, NLQueryResult, NLQueryFn } from './schema/types.js';
 export { conjugate, pluralize, singularize, inferNoun, createTypeMeta, getTypeMeta, Type, getVerbFields, } from './linguistic.js';
-export type { ReferenceSpec, Draft, Resolved, DraftOptions, ResolveOptions, CascadeProgress, CreateEntityOptions, OperatorParseResult, ListOptions, SearchOptions, SemanticSearchOptions, HybridSearchOptions, EmbeddingTypeConfig, ActorData, DBEvent, CreateEventOptions, DBAction, CreateActionOptions, DBArtifact, EventsAPI, ActionsAPI, ArtifactsAPI, NounsAPI, VerbsAPI, NLQueryResult, NLQueryFn, NLQueryContext, NLQueryPlan, NLQueryGenerator, GenerateOptions, DBOptions, } from './schema/types.js';
-export { parseOperator, parseField, parseSchema, isPrimitiveType } from './schema/parse.js';
-export type { DBProvider, DBProviderExtended } from './schema/provider.js';
-export { setProvider, resolveProvider } from './schema/provider.js';
-export { isEntityId, inferTypeFromField, resolveContextPath, resolveInstructions, prefetchContext, isPromptField, resolveNestedPending, resolveReferenceSpec, hydrateEntity, } from './schema/resolve.js';
-export { generateContextAwareValue, generateAIFields, generateEntity, resolveForwardExact, generateNaturalLanguageContent, } from './schema/cascade.js';
-export { resolveBackwardFuzzy, resolveForwardFuzzy } from './schema/semantic.js';
-export { FORWARD_TO_REVERSE, BIDIRECTIONAL_PAIRS, deriveReverseVerb, fieldNameToVerb, isPassiveVerb, registerVerbPair, registerBidirectionalPair, registerFieldVerb, } from './schema/verb-derivation.js';
-export { defineNoun, defineVerb, nounToSchema, ThingSchema, NounSchema, VerbSchema, EdgeSchema, SystemSchema, createEdgeRecords, createNounRecord, setNLQueryGenerator, DB, } from './schema/index.js';
-export type { InferEntity, EntityOperations, PipelineEntityOperations, TypedDB, DBResult, } from './schema/index.js';
-export { parseSchema as parse } from './schema/parse.js';
+import type { EntitySchema, DatabaseSchema, ParsedEntity, ParsedSchema, Verb, Noun } from './types.js';
+/**
+ * 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 declare function defineNoun<T extends Noun>(noun: T): T;
+/**
+ * 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 declare function defineVerb<T extends Verb>(verb: T): T;
+/**
+ * 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 declare function nounToSchema(noun: Noun): EntitySchema;
+/**
+ * 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 declare const ThingSchema: EntitySchema;
+/**
+ * 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 declare const NounSchema: EntitySchema;
+/**
+ * Built-in Verb schema for storing action definitions
+ */
+export declare const VerbSchema: EntitySchema;
+/**
+ * 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 declare const EdgeSchema: EntitySchema;
+/**
+ * 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 declare const SystemSchema: DatabaseSchema;
+/**
+ * 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 declare function createEdgeRecords(typeName: string, schema: EntitySchema, parsedEntity: ParsedEntity): Array<Record<string, unknown>>;
+/**
+ * Create a Noun record from a type name and optional schema
+ *
+ * @internal Used by DB() to auto-populate Noun records
+ */
+export declare function createNounRecord(typeName: string, schema?: EntitySchema, nounDef?: Partial<Noun>): Record<string, unknown>;
+/**
+ * Reference specification for unresolved relationships in a draft
+ */
+export interface ReferenceSpec {
+    /** Field name on the entity */
+    field: string;
+    /** The relationship operator: ->, ~>, <-, <~ */
+    operator: '->' | '~>' | '<-' | '<~';
+    /** Target entity type */
+    type: string;
+    /** Match mode for resolving */
+    matchMode: 'exact' | 'fuzzy';
+    /** Whether this reference is resolved */
+    resolved: boolean;
+    /** Natural language prompt for generation */
+    prompt?: string;
+    /** Generated natural language text (before resolution) */
+    generatedText?: string;
+    /** Instructions from the source entity's $instructions metadata */
+    sourceInstructions?: string;
+    /** Fuzzy match threshold */
+    threshold?: number;
+    /** Union types for polymorphic references */
+    unionTypes?: string[];
+}
+/**
+ * Draft entity with unresolved references
+ *
+ * A draft is an entity that has been generated but whose relationships
+ * have not yet been resolved to actual entity IDs. This allows:
+ * - Streaming draft content to users before relationships are resolved
+ * - Batch resolution of multiple references for efficiency
+ * - Draft-only mode for preview/editing before final creation
+ */
+export interface Draft<T> {
+    /** Phase marker indicating this is a draft */
+    $phase: 'draft';
+    /** Unresolved reference specifications */
+    $refs: Record<string, ReferenceSpec | ReferenceSpec[]>;
+    /** Entity data with natural language placeholders for references */
+    [key: string]: unknown;
+}
+/**
+ * Resolved entity after resolution phase
+ */
+export interface Resolved<T> {
+    /** Phase marker indicating this has been resolved */
+    $phase: 'resolved';
+    /** Any errors that occurred during resolution */
+    $errors?: Array<{
+        field: string;
+        error: string;
+    }>;
+    /** Entity data with resolved reference IDs */
+    [key: string]: unknown;
+}
+/**
+ * Options for the draft() method
+ */
+export interface DraftOptions {
+    /** Enable streaming of draft content */
+    stream?: boolean;
+    /** Callback for streaming chunks */
+    onChunk?: (chunk: string) => void;
+}
+/**
+ * Options for the resolve() method
+ */
+export interface ResolveOptions {
+    /** How to handle resolution errors */
+    onError?: 'throw' | 'skip';
+    /** Callback when a reference is resolved */
+    onResolved?: (fieldName: string, entityId: string) => void;
+}
+/**
+ * Progress tracking for cascade generation
+ */
+export interface CascadeProgress {
+    /** Current phase of cascade generation */
+    phase: 'generating' | 'complete' | 'error';
+    /** Type currently being generated */
+    currentType?: string;
+    /** Current recursion depth */
+    currentDepth: number;
+    /** Alias for currentDepth for convenience */
+    depth: number;
+    /** Total number of entities created during cascade */
+    totalEntitiesCreated: number;
+    /** List of types that have been generated */
+    typesGenerated: string[];
+}
+/**
+ * Options for cascade generation
+ */
+export interface CascadeOptions {
+    /** Enable cascade generation through relationships */
+    cascade?: boolean;
+    /** Maximum depth for cascade recursion (default: 3) */
+    maxDepth?: number;
+    /** Limit cascade to specific types */
+    cascadeTypes?: string[];
+    /** Progress callback for tracking cascade generation */
+    onProgress?: (progress: CascadeProgress) => void;
+    /** Error callback for handling cascade errors */
+    onError?: (error: Error, context: {
+        type: string;
+        depth: number;
+    }) => void;
+    /** Stop cascade on first error */
+    stopOnError?: boolean;
+}
+/**
+ * Options for the create() method
+ */
+export interface CreateEntityOptions extends CascadeOptions {
+    /** Only create a draft, don't resolve references */
+    draftOnly?: boolean;
+}
+/**
+ * Map field type to TypeScript type
+ */
+type FieldToTS<T extends string> = T extends 'string' ? string : T extends 'number' ? number : T extends 'boolean' ? boolean : T extends 'date' | 'datetime' ? Date : T extends 'json' ? Record<string, unknown> : T extends 'markdown' ? string : T extends 'url' ? string : unknown;
+/**
+ * Parse a union string like 'A | B | C' into a union type
+ */
+type ParseUnion<T extends string> = T extends `${infer A} | ${infer B}` ? A | ParseUnion<B> : T;
+/**
+ * Infer the TypeScript type for a single field string value, given the full schema
+ */
+type InferFieldValue<TSchema extends DatabaseSchema, V extends string> = V extends `->${infer Target}` ? Target extends keyof TSchema ? InferEntity<TSchema, Target> : string : V extends `<-${infer Target}` ? Target extends keyof TSchema ? InferEntity<TSchema, Target> : string : V extends `~>${infer Target}` ? Target extends keyof TSchema ? InferEntity<TSchema, Target> : string : V extends `<~${infer Target}` ? Target extends keyof TSchema ? InferEntity<TSchema, Target> : string : V extends `${infer Type}.${string}` ? Type extends keyof TSchema ? InferEntity<TSchema, Type> : unknown : V extends `${infer Type}[]` ? Type extends keyof TSchema ? InferEntity<TSchema, Type>[] : FieldToTS<Type>[] : V extends `${infer Type}?` ? FieldToTS<Type> | undefined : V extends `${string} | ${string}` ? ParseUnion<V> : FieldToTS<V>;
+/**
+ * Infer entity type from schema definition
+ */
+export type InferEntity<TSchema extends DatabaseSchema, TEntity extends keyof TSchema> = {
+    $id: string;
+    $type: TEntity;
+} & {
+    [K in keyof TSchema[TEntity]]: TSchema[TEntity][K] extends readonly [infer Inner extends string] ? InferFieldValue<TSchema, Inner> extends infer R ? R[] : never : TSchema[TEntity][K] extends [infer Inner extends string] ? InferFieldValue<TSchema, Inner> extends infer R ? R[] : never : TSchema[TEntity][K] extends string ? InferFieldValue<TSchema, TSchema[TEntity][K]> : unknown;
+};
+/**
+ * Operations available on each entity type
+ */
+export interface EntityOperations<T> {
+    /** Get an entity by ID */
+    get(id: string): Promise<T | null>;
+    /** List all entities */
+    list(options?: ListOptions): Promise<T[]>;
+    /** Find entities matching criteria */
+    find(where: Partial<T>): Promise<T[]>;
+    /** Search entities */
+    search(query: string, options?: SearchOptions): Promise<T[]>;
+    /** Create a new entity */
+    create(data: Omit<T, '$id' | '$type'>): Promise<T>;
+    create(id: string, data: Omit<T, '$id' | '$type'>): Promise<T>;
+    /** Update an entity */
+    update(id: string, data: Partial<Omit<T, '$id' | '$type'>>): Promise<T>;
+    /** Upsert an entity */
+    upsert(id: string, data: Omit<T, '$id' | '$type'>): Promise<T>;
+    /** Delete an entity */
+    delete(id: string): Promise<boolean>;
+    /** Iterate over entities */
+    forEach(callback: (entity: T) => void | Promise<void>): Promise<void>;
+    forEach(options: ListOptions, callback: (entity: T) => void | Promise<void>): Promise<void>;
+    /** Semantic search */
+    semanticSearch?(query: string, options?: SemanticSearchOptions): Promise<Array<T & {
+        $score: number;
+    }>>;
+    /** Hybrid search */
+    hybridSearch?(query: string, options?: HybridSearchOptions): Promise<Array<T & {
+        $rrfScore: number;
+        $ftsRank: number;
+        $semanticRank: number;
+        $score: number;
+    }>>;
+    /** Create draft entity */
+    draft?(data: Partial<Omit<T, '$id' | '$type'>>, options?: DraftOptions): Promise<Draft<T>>;
+    /** Resolve draft entity */
+    resolve?(draft: Draft<T>, options?: ResolveOptions): Promise<Resolved<T>>;
+}
+/**
+ * Operations with promise pipelining support
+ *
+ * Query methods return DBPromise for chainable operations:
+ * - `.map()` with batch optimization
+ * - `.filter()`, `.sort()`, `.limit()`
+ * - Property access tracking for projections
+ *
+ * @example
+ * ```ts
+ * // Chain without await
+ * const leads = db.Lead.list()
+ * const qualified = await leads
+ *   .filter(l => l.score > 80)
+ *   .map(l => ({ name: l.name, company: l.company }))
+ *
+ * // Batch relationship loading
+ * const orders = await db.Order.list().map(o => ({
+ *   order: o,
+ *   customer: o.customer,  // Batch loaded!
+ * }))
+ * ```
+ */
+export interface PipelineEntityOperations<T> {
+    /** Get an entity by ID */
+    get(id: string): DBPromise<T | null>;
+    /** List all entities */
+    list(options?: ListOptions): DBPromise<T[]>;
+    /** Find entities matching criteria */
+    find(where: Partial<T>): DBPromise<T[]>;
+    /** Search entities */
+    search(query: string, options?: SearchOptions): DBPromise<T[]>;
+    /** Get first matching entity */
+    first(): DBPromise<T | null>;
+    /** Create a new entity */
+    create(data: Omit<T, '$id' | '$type'>, options?: CreateEntityOptions): Promise<T | Draft<T>>;
+    create(id: string, data: Omit<T, '$id' | '$type'>, options?: CreateEntityOptions): Promise<T | Draft<T>>;
+    /**
+     * Create a draft entity with natural language placeholders for references
+     *
+     * The draft phase generates entity content but leaves relationship fields
+     * as natural language descriptions that will be resolved later.
+     *
+     * @example
+     * ```ts
+     * const draft = await db.Startup.draft({ name: 'Acme' })
+     * // draft.idea contains natural language like "A revolutionary SaaS idea"
+     * // draft.$refs.idea contains reference spec for resolution
+     * ```
+     */
+    draft(data: Partial<Omit<T, '$id' | '$type'>>, options?: DraftOptions): Promise<Draft<T>>;
+    /**
+     * Resolve a draft entity by converting natural language references to entity IDs
+     *
+     * The resolve phase creates or matches related entities and replaces
+     * natural language placeholders with actual entity IDs.
+     *
+     * @example
+     * ```ts
+     * const draft = await db.Startup.draft({ name: 'Acme' })
+     * const resolved = await db.Startup.resolve(draft)
+     * // resolved.idea is now an actual entity ID
+     * ```
+     */
+    resolve(draft: Draft<T>, options?: ResolveOptions): Promise<Resolved<T>>;
+    /** Update an entity */
+    update(id: string, data: Partial<Omit<T, '$id' | '$type'>>): Promise<T>;
+    /** Upsert an entity */
+    upsert(id: string, data: Omit<T, '$id' | '$type'>): Promise<T>;
+    /** Delete an entity */
+    delete(id: string): Promise<boolean>;
+    /**
+     * Process each entity with concurrency control, progress tracking, and error handling
+     *
+     * Designed for large-scale operations like AI generations or workflows.
+     *
+     * @example
+     * ```ts
+     * // Simple iteration
+     * await db.Lead.forEach(lead => console.log(lead.name))
+     *
+     * // With AI and concurrency
+     * const result = await db.Lead.forEach(async lead => {
+     *   const analysis = await ai`analyze ${lead}`
+     *   await db.Lead.update(lead.$id, { analysis })
+     * }, {
+     *   concurrency: 10,
+     *   onProgress: p => console.log(`${p.completed}/${p.total}`),
+     * })
+     *
+     * // With error handling
+     * await db.Order.forEach(async order => {
+     *   await sendInvoice(order)
+     * }, {
+     *   maxRetries: 3,
+     *   onError: (err, order) => err.code === 'RATE_LIMIT' ? 'retry' : 'continue',
+     * })
+     * ```
+     */
+    forEach<U>(callback: (entity: T, index: number) => U | Promise<U>, options?: ForEachOptions<T>): Promise<ForEachResult>;
+    /**
+     * Semantic search using embedding similarity
+     *
+     * @example
+     * ```ts
+     * const results = await db.Document.semanticSearch('deep learning neural networks')
+     * // Returns documents with $score field sorted by similarity
+     * ```
+     */
+    semanticSearch(query: string, options?: SemanticSearchOptions): Promise<Array<T & {
+        $score: number;
+    }>>;
+    /**
+     * Hybrid search combining FTS and semantic search with RRF scoring
+     *
+     * @example
+     * ```ts
+     * const results = await db.Post.hybridSearch('React useState')
+     * // Returns posts with $rrfScore, $ftsRank, $semanticRank fields
+     * ```
+     */
+    hybridSearch(query: string, options?: HybridSearchOptions): Promise<Array<T & {
+        $rrfScore: number;
+        $ftsRank: number;
+        $semanticRank: number;
+        $score: number;
+    }>>;
+}
+export interface ListOptions {
+    where?: Record<string, unknown>;
+    orderBy?: string;
+    order?: 'asc' | 'desc';
+    limit?: number;
+    offset?: number;
+    /**
+     * Suppress errors and return empty array instead of throwing.
+     * Useful for graceful degradation when the database is unavailable.
+     */
+    suppressErrors?: boolean;
+    /**
+     * Error handler callback. If provided, errors are passed to this callback
+     * instead of being thrown. The callback can return a fallback value.
+     */
+    onError?: (error: Error) => unknown[] | void;
+}
+export interface SearchOptions extends ListOptions {
+    fields?: string[];
+    minScore?: number;
+}
+/**
+ * Options for semantic search
+ */
+export interface SemanticSearchOptions {
+    /** Minimum similarity score (0-1) */
+    minScore?: number;
+    /** Maximum number of results */
+    limit?: number;
+}
+/**
+ * Options for hybrid search (FTS + semantic)
+ */
+export interface HybridSearchOptions {
+    /** Minimum similarity score for semantic results */
+    minScore?: number;
+    /** Maximum number of results */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+    /** RRF k parameter (default: 60) */
+    rrfK?: number;
+    /** Weight for FTS results (default: 0.5) */
+    ftsWeight?: number;
+    /** Weight for semantic results (default: 0.5) */
+    semanticWeight?: number;
+}
+/**
+ * Embedding configuration for a specific entity type
+ */
+export interface EmbeddingTypeConfig {
+    /** Fields to embed (defaults to text/markdown fields) */
+    fields?: string[];
+}
+/**
+ * DB Options for configuring embeddings and other settings
+ */
+export interface DBOptions {
+    /** Embedding configuration per type */
+    embeddings?: EmbeddingsConfig;
+    /**
+     * Database provider instance or factory function.
+     * When provided, this provider is used instead of the global provider.
+     * This enables dependency injection for testing and isolated DB instances.
+     *
+     * @example
+     * ```ts
+     * // Direct provider instance
+     * const db = DB(schema, { provider: myProvider })
+     *
+     * // Lazy factory function (created on first use)
+     * const db = DB(schema, { provider: () => createMyProvider() })
+     * ```
+     */
+    provider?: DBProvider | (() => DBProvider) | (() => Promise<DBProvider>);
+    /**
+     * AI generation configuration.
+     * When provided, these settings are used instead of the global aiConfig.
+     * This enables dependency injection for testing and isolated DB instances.
+     *
+     * @example
+     * ```ts
+     * const db = DB(schema, {
+     *   aiGeneration: {
+     *     model: 'gpt-4',
+     *     enabled: true,
+     *     onGenerate: (details) => console.log('Generated:', details)
+     *   }
+     * })
+     * ```
+     */
+    aiGeneration?: Partial<AIGenerationConfig>;
+}
+/**
+ * Typed database client based on schema
+ *
+ * Entity operations return DBPromise for chainable queries:
+ * ```ts
+ * const { db } = DB({ Lead: { name: 'string', company: 'Company.leads' } })
+ *
+ * // Chain without await
+ * const leads = db.Lead.list()
+ * const qualified = await leads.filter(l => l.score > 80)
+ *
+ * // Batch relationship loading
+ * const withCompanies = await leads.map(l => ({
+ *   lead: l,
+ *   company: l.company,  // Batch loaded!
+ * }))
+ * ```
+ */
+export type TypedDB<TSchema extends DatabaseSchema> = {
+    [K in keyof TSchema]: PipelineEntityOperations<InferEntity<TSchema, K>> & NLQueryFn<InferEntity<TSchema, K>>;
+} & {
+    /** The parsed schema */
+    readonly $schema: ParsedSchema;
+    /** Get any entity by URL */
+    get(url: string): Promise<unknown>;
+    /** Search across all entities */
+    search(query: string, options?: SearchOptions): Promise<unknown[]>;
+    /** Count entities of a type */
+    count(type: string, where?: Record<string, unknown>): Promise<number>;
+    /** Iterate over entities with a callback */
+    forEach(options: {
+        type: string;
+        where?: Record<string, unknown>;
+        concurrency?: number;
+    }, callback: (entity: unknown) => void | Promise<void>): Promise<void>;
+    /** Set entity data by ID (creates or replaces) */
+    set(type: string, id: string, data: Record<string, unknown>): Promise<unknown>;
+    /** Generate entities using AI */
+    generate(options: GenerateOptions): Promise<unknown | {
+        id: string;
+    }>;
+    /**
+     * Natural language query across all types
+     *
+     * @example
+     * ```ts
+     * const results = await db`what orders are pending for customers in california?`
+     * const results = await db`show me joe's recent activity`
+     * const results = await db`what changed in the last hour?`
+     * ```
+     */
+    ask: NLQueryFn;
+    /**
+     * Global semantic search across all entity types
+     *
+     * @example
+     * ```ts
+     * const results = await db.semanticSearch('artificial intelligence')
+     * // Returns results from all types with $type and $score fields
+     * ```
+     */
+    semanticSearch(query: string, options?: SemanticSearchOptions): Promise<Array<{
+        $id: string;
+        $type: string;
+        $score: number;
+        [key: string]: unknown;
+    }>>;
+    /**
+     * Subscribe to database events (draft, resolve, create, update, delete)
+     *
+     * @example
+     * ```ts
+     * db.on('draft', (entity) => console.log('Draft created:', entity.$type))
+     * db.on('resolve', (entity) => console.log('Entity resolved:', entity.$type))
+     * db.on('Post.created', (event) => console.log('Post created'))
+     * ```
+     */
+    on(event: string, handler: (data: unknown) => void): () => void;
+};
+/**
+ * Options for AI-powered entity generation
+ */
+export interface GenerateOptions {
+    type: string;
+    count?: number;
+    data?: Record<string, unknown>;
+    mode?: 'sync' | 'background';
+}
+/**
+ * Actor data - who performed the action
+ *
+ * @example
+ * ```ts
+ * const actorData: ActorData = {
+ *   name: 'John Doe',
+ *   email: 'john@example.com',
+ *   org: 'Acme Corp',
+ *   role: 'admin',
+ * }
+ * ```
+ */
+export interface ActorData {
+    /** Actor's display name */
+    name?: string;
+    /** Actor's email */
+    email?: string;
+    /** Actor's organization */
+    org?: string;
+    /** Actor's role or access level */
+    role?: string;
+    /** Additional actor metadata */
+    [key: string]: unknown;
+}
+/**
+ * Event data structure - Actor-Event-Object-Result pattern
+ *
+ * Following ActivityStreams semantics:
+ * - Actor: Who did it (user, system, agent)
+ * - Event: What happened (created, updated, published)
+ * - Object: What it was done to (the entity)
+ * - Result: What was the outcome (optional)
+ *
+ * @example
+ * ```ts
+ * const event: DBEvent = {
+ *   id: '01HGXYZ...',
+ *   actor: 'user:john',
+ *   actorData: { name: 'John Doe', email: 'john@example.com' },
+ *   event: 'Post.published',
+ *   object: 'https://example.com/Post/hello-world',
+ *   objectData: { title: 'Hello World' },
+ *   result: 'https://example.com/Publication/123',
+ *   resultData: { url: 'https://blog.example.com/hello-world' },
+ *   timestamp: new Date(),
+ * }
+ * ```
+ */
+export interface DBEvent {
+    /** Unique event ID (ULID recommended) */
+    id: string;
+    /** Actor identifier (user:id, system, agent:name) */
+    actor: string;
+    /** Actor metadata */
+    actorData?: ActorData;
+    /** Event type (Entity.action format, e.g., Post.created) */
+    event: string;
+    /** Object URL/identifier that was acted upon */
+    object?: string;
+    /** Object data snapshot at time of event */
+    objectData?: Record<string, unknown>;
+    /** Result URL/identifier (outcome of the action) */
+    result?: string;
+    /** Result data */
+    resultData?: Record<string, unknown>;
+    /** Additional metadata */
+    meta?: Record<string, unknown>;
+    /** When the event occurred */
+    timestamp: Date;
+    /** @deprecated Use 'event' instead */
+    type?: string;
+    /** @deprecated Use 'objectData' instead */
+    data?: unknown;
+    /** @deprecated Use 'object' instead */
+    url?: string;
+}
+/**
+ * Options for creating an event
+ */
+export interface CreateEventOptions {
+    /** Actor identifier */
+    actor: string;
+    /** Actor metadata */
+    actorData?: ActorData;
+    /** Event type */
+    event: string;
+    /** Object URL/identifier */
+    object?: string;
+    /** Object data */
+    objectData?: Record<string, unknown>;
+    /** Result URL/identifier */
+    result?: string;
+    /** Result data */
+    resultData?: Record<string, unknown>;
+    /** Additional metadata */
+    meta?: Record<string, unknown>;
+}
+/**
+ * Events API for subscribing to and emitting events
+ */
+export interface EventsAPI {
+    /** Subscribe to events matching a pattern */
+    on(pattern: string, handler: (event: DBEvent) => void | Promise<void>): () => void;
+    /** Emit an event using Actor-Event-Object-Result pattern */
+    emit(options: CreateEventOptions): Promise<DBEvent>;
+    /** Emit a simple event (legacy compatibility) */
+    emit(type: string, data: unknown): Promise<DBEvent>;
+    /** List events with optional filters */
+    list(options?: {
+        event?: string;
+        actor?: string;
+        object?: string;
+        since?: Date;
+        until?: Date;
+        limit?: number;
+        /** @deprecated Use 'event' instead */
+        type?: string;
+    }): Promise<DBEvent[]>;
+    /** Replay events through a handler */
+    replay(options: {
+        event?: string;
+        actor?: string;
+        since?: Date;
+        handler: (event: DBEvent) => void | Promise<void>;
+        /** @deprecated Use 'event' instead */
+        type?: string;
+    }): Promise<void>;
+}
+/**
+ * Action data structure for durable execution
+ *
+ * Uses linguistic verb conjugations for semantic clarity:
+ * - act: Present tense 3rd person (creates, publishes)
+ * - action: Base verb form (create, publish)
+ * - activity: Gerund/progressive (creating, publishing)
+ *
+ * @example
+ * ```ts
+ * const action: DBAction = {
+ *   id: '01HGXYZ...',
+ *   actor: 'user:john',
+ *   actorData: { name: 'John Doe' },
+ *   // Verb conjugations
+ *   act: 'generates',        // Present tense: "system generates posts"
+ *   action: 'generate',      // Base form for lookups
+ *   activity: 'generating',  // Progressive: "currently generating posts"
+ *   // Target
+ *   object: 'Post',
+ *   objectData: { count: 100 },
+ *   // Status
+ *   status: 'active',
+ *   progress: 50,
+ *   total: 100,
+ *   // Result
+ *   result: { created: 50 },
+ *   timestamp: new Date(),
+ * }
+ * ```
+ */
+export interface DBAction {
+    /** Unique action ID (ULID recommended) */
+    id: string;
+    /** Actor identifier (user:id, system, agent:name) */
+    actor: string;
+    /** Actor metadata */
+    actorData?: ActorData;
+    /** Present tense 3rd person verb (creates, publishes, generates) */
+    act: string;
+    /** Base verb form - imperative (create, publish, generate) */
+    action: string;
+    /** Gerund/progressive form (creating, publishing, generating) */
+    activity: string;
+    /** Object being acted upon (type name or URL) */
+    object?: string;
+    /** Object data/parameters for the action */
+    objectData?: Record<string, unknown>;
+    /** Action status */
+    status: 'pending' | 'active' | 'completed' | 'failed' | 'cancelled';
+    /** Current progress count */
+    progress?: number;
+    /** Total items to process */
+    total?: number;
+    /** Result data on completion */
+    result?: Record<string, unknown>;
+    /** Error message on failure */
+    error?: string;
+    /** Additional metadata */
+    meta?: Record<string, unknown>;
+    /** When the action was created */
+    createdAt: Date;
+    /** When the action started executing */
+    startedAt?: Date;
+    /** When the action completed/failed */
+    completedAt?: Date;
+    /** @deprecated Use 'action' instead */
+    type?: string;
+    /** @deprecated Use 'objectData' instead */
+    data?: unknown;
+}
+/**
+ * Options for creating an action
+ */
+export interface CreateActionOptions {
+    /** Actor identifier */
+    actor: string;
+    /** Actor metadata */
+    actorData?: ActorData;
+    /** Base verb (will auto-conjugate to act/activity) */
+    action: string;
+    /** Object being acted upon */
+    object?: string;
+    /** Object data/parameters */
+    objectData?: Record<string, unknown>;
+    /** Total items for progress tracking */
+    total?: number;
+    /** Additional metadata */
+    meta?: Record<string, unknown>;
+    /** @deprecated Use 'action' instead */
+    type?: string;
+    /** @deprecated Use 'objectData' instead */
+    data?: unknown;
+}
+/**
+ * Actions API for durable execution tracking
+ *
+ * @example
+ * ```ts
+ * // Create an action with verb conjugation
+ * const action = await actions.create({
+ *   actor: 'system',
+ *   action: 'generate',  // auto-conjugates to act='generates', activity='generating'
+ *   object: 'Post',
+ *   objectData: { count: 100 },
+ *   total: 100,
+ * })
+ *
+ * // Update progress
+ * await actions.update(action.id, { progress: 50 })
+ *
+ * // Complete with result
+ * await actions.update(action.id, {
+ *   status: 'completed',
+ *   result: { created: 100 },
+ * })
+ * ```
+ */
+export interface ActionsAPI {
+    /** Create a new action (auto-conjugates verb forms) */
+    create(options: CreateActionOptions): Promise<DBAction>;
+    /** Create with legacy format (deprecated) */
+    create(data: {
+        type: string;
+        data: unknown;
+        total?: number;
+    }): Promise<DBAction>;
+    /** Get an action by ID */
+    get(id: string): Promise<DBAction | null>;
+    /** Update action progress/status */
+    update(id: string, updates: Partial<Pick<DBAction, 'status' | 'progress' | 'result' | 'error'>>): Promise<DBAction>;
+    /** List actions with optional filters */
+    list(options?: {
+        status?: DBAction['status'];
+        action?: string;
+        actor?: string;
+        object?: string;
+        since?: Date;
+        until?: Date;
+        limit?: number;
+        /** @deprecated Use 'action' instead */
+        type?: string;
+    }): Promise<DBAction[]>;
+    /** Retry a failed action */
+    retry(id: string): Promise<DBAction>;
+    /** Cancel a pending/active action */
+    cancel(id: string): Promise<void>;
+    /** Conjugate a verb to get all forms */
+    conjugate(action: string): Verb;
+}
+/**
+ * Artifact data structure for cached content
+ */
+export interface DBArtifact {
+    url: string;
+    type: string;
+    sourceHash: string;
+    content: unknown;
+    metadata?: Record<string, unknown>;
+    createdAt: Date;
+}
+/**
+ * Artifacts API for cached embeddings and computed content
+ */
+export interface ArtifactsAPI {
+    /** Get an artifact by URL and type */
+    get(url: string, type: string): Promise<DBArtifact | null>;
+    /** Set an artifact */
+    set(url: string, type: string, data: {
+        content: unknown;
+        sourceHash: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<void>;
+    /** Delete an artifact */
+    delete(url: string, type?: string): Promise<void>;
+    /** List artifacts for a URL */
+    list(url: string): Promise<DBArtifact[]>;
+}
+/**
+ * Nouns API for type introspection
+ */
+export interface NounsAPI {
+    /** Get a noun definition by type name */
+    get(name: string): Promise<Noun | null>;
+    /** List all noun definitions */
+    list(): Promise<Noun[]>;
+    /** Define a new noun */
+    define(noun: Noun): Promise<void>;
+}
+/**
+ * Verbs API for action introspection
+ */
+export interface VerbsAPI {
+    /** Get a verb definition by action name */
+    get(action: string): Verb | null;
+    /** List all verb definitions */
+    list(): Verb[];
+    /** Define a new verb */
+    define(verb: Verb): void;
+    /** Conjugate a verb from base form */
+    conjugate(action: string): Verb;
+}
+/**
+ * Result of DB() factory - supports both direct and destructured usage
+ *
+ * @example
+ * ```ts
+ * // Direct usage - everything on one object
+ * const db = DB(schema)
+ * db.User.create(...)      // entity operations
+ * db.events.on(...)        // events API
+ * db.actions.create(...)   // actions API
+ *
+ * // Destructured usage - cleaner separation
+ * const { db, events, actions } = DB(schema)
+ * db.User.create(...)      // just entity ops
+ * events.on(...)           // separate events
+ * ```
+ */
+export type DBResult<TSchema extends DatabaseSchema> = TypedDB<TSchema> & {
+    /** Self-reference for destructuring - same as the parent object but cleaner semantically */
+    db: TypedDB<TSchema>;
+    /** Event subscription and emission */
+    events: EventsAPI;
+    /** Durable action execution */
+    actions: ActionsAPI;
+    /** Cached embeddings and computed content */
+    artifacts: ArtifactsAPI;
+    /** Type introspection */
+    nouns: NounsAPI;
+    /** Action introspection */
+    verbs: VerbsAPI;
+    /** EventBridge for Cloudflare Queues integration */
+    eventBridge: EventBridgeAPI;
+};
+/**
+ * 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 declare function setNLQueryGenerator(generator: NLQueryGenerator): void;
+/**
+ * Get the currently configured NL query generator
+ */
+export declare function getNLQueryGenerator(): NLQueryGenerator | null;
+/**
+ * Build schema context for NL queries
+ */
+export declare function buildNLQueryContext(schema: ParsedSchema, targetType?: string): NLQueryContext;
+/**
+ * Execute a natural language query
+ */
+export declare function executeNLQuery<T>(question: string, schema: ParsedSchema, targetType?: string): Promise<NLQueryResult<T>>;
+/**
+ * Create a natural language query function for a specific type
+ */
+export declare function createNLQueryFn<T>(schema: ParsedSchema, typeName?: string): NLQueryFn<T>;
+/**
+ * Set the global database provider
+ */
+export declare function setProvider(provider: DBProvider): void;
+/**
+ * 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 declare function DB<TSchema extends DatabaseSchema>(schema: TSchema, options?: DBOptions): DBResult<TSchema>;
+export { parseSchema as parse };
 //# sourceMappingURL=schema.d.ts.map