@topgunbuild/core 0.5.0 → 0.7.0

package/dist/index.d.mts

@@ -3330,10 +3330,10 @@ interface Index<K, V, A = unknown> {
  */
 interface IndexQuery<A> {
     /** Query type */
-    type: 'equal' | 'in' | 'has' | 'gt' | 'gte' | 'lt' | 'lte' | 'between' | 'contains' | 'containsAll' | 'containsAny';
+    type: 'equal' | 'in' | 'has' | 'gt' | 'gte' | 'lt' | 'lte' | 'between' | 'contains' | 'containsAll' | 'containsAny' | 'compound';
     /** Value for equality queries */
     value?: A;
-    /** Values for 'in' queries */
+    /** Values for 'in' queries or compound queries */
     values?: A[];
     /** Lower bound for range queries */
     from?: A;
@@ -4164,6 +4164,571 @@ declare class InvertedIndex<K, V, A extends string = string> implements Index<K,
     private valuesEqual;
 }
 
+/**
+ * CompoundIndex Implementation (Phase 9.03)
+ *
+ * Multi-attribute index for optimizing AND queries.
+ * Creates a composite key from multiple attribute values for O(1) lookup.
+ *
+ * Benefits:
+ * - 100-1000× speedup for compound AND queries
+ * - Eliminates ResultSet intersection overhead
+ * - Single lookup instead of multiple index scans
+ *
+ * @module query/indexes/CompoundIndex
+ */
+
+/**
+ * Options for compound index creation.
+ */
+interface CompoundIndexOptions {
+    /**
+     * Separator for composite key generation.
+     * Default: '|'
+     * Choose a separator that won't appear in attribute values.
+     */
+    separator?: string;
+}
+/**
+ * Compound index for O(1) multi-attribute queries.
+ * Indexes multiple attributes as a single composite key.
+ *
+ * K = record key type, V = record value type
+ */
+declare class CompoundIndex<K, V> implements Index<K, V, unknown> {
+    readonly type: "compound";
+    /** Attributes that make up this compound index (in order) */
+    private readonly _attributes;
+    /** Map from composite key to set of record keys */
+    private data;
+    /** Set of all indexed keys */
+    private allKeys;
+    /** Key separator */
+    private readonly separator;
+    /** Retrieval cost (lower than individual indexes combined) */
+    private static readonly RETRIEVAL_COST;
+    /**
+     * Create a CompoundIndex.
+     *
+     * @param attributes - Array of attributes to index (order matters!)
+     * @param options - Optional configuration
+     *
+     * @example
+     * ```typescript
+     * const statusAttr = simpleAttribute<Product, string>('status', p => p.status);
+     * const categoryAttr = simpleAttribute<Product, string>('category', p => p.category);
+     *
+     * const compoundIndex = new CompoundIndex<string, Product>([statusAttr, categoryAttr]);
+     * ```
+     */
+    constructor(attributes: Attribute<V, unknown>[], options?: CompoundIndexOptions);
+    /**
+     * Get the first attribute (used for Index interface compatibility).
+     * Note: CompoundIndex spans multiple attributes.
+     */
+    get attribute(): Attribute<V, unknown>;
+    /**
+     * Get all attributes in this compound index.
+     */
+    get attributes(): Attribute<V, unknown>[];
+    /**
+     * Get attribute names as a combined identifier.
+     */
+    get compoundName(): string;
+    getRetrievalCost(): number;
+    supportsQuery(queryType: string): boolean;
+    /**
+     * Retrieve records matching compound query.
+     *
+     * @param query - Compound query with values matching each attribute
+     * @returns ResultSet of matching keys
+     *
+     * @example
+     * ```typescript
+     * // Find products where status='active' AND category='electronics'
+     * index.retrieve({
+     *   type: 'compound',
+     *   values: ['active', 'electronics']
+     * });
+     * ```
+     */
+    retrieve(query: IndexQuery<unknown>): ResultSet<K>;
+    /**
+     * Retrieve with explicit values (convenience method).
+     *
+     * @param values - Values in order of index attributes
+     * @returns ResultSet of matching keys
+     */
+    retrieveByValues(...values: unknown[]): ResultSet<K>;
+    add(key: K, record: V): void;
+    remove(key: K, record: V): void;
+    update(key: K, oldRecord: V, newRecord: V): void;
+    clear(): void;
+    getStats(): IndexStats;
+    /**
+     * Get extended statistics for compound index.
+     */
+    getExtendedStats(): CompoundIndexStats;
+    /**
+     * Check if this compound index can answer a query on the given attributes.
+     * Compound indexes can be used if query attributes match in prefix order.
+     *
+     * @param attributeNames - Attribute names being queried
+     * @returns true if this index can answer the query
+     */
+    canAnswerQuery(attributeNames: string[]): boolean;
+    /**
+     * Build composite key from array of values.
+     */
+    private buildCompositeKey;
+    /**
+     * Build composite key from record by extracting attribute values.
+     * Returns null if any attribute value is undefined.
+     */
+    private buildCompositeKeyFromRecord;
+    /**
+     * Encode value for composite key.
+     * Handles common types and escapes separator.
+     */
+    private encodeValue;
+    /**
+     * Escape regex special characters.
+     */
+    private escapeRegex;
+}
+/**
+ * Extended statistics for compound index.
+ */
+interface CompoundIndexStats extends IndexStats {
+    /** Number of attributes in compound key */
+    attributeCount: number;
+    /** Names of indexed attributes */
+    attributeNames: string[];
+    /** Number of unique composite keys */
+    compositeKeyCount: number;
+}
+
+/**
+ * Types for Adaptive Indexing System (Phase 8.02)
+ *
+ * Defines interfaces for query pattern tracking, index suggestions,
+ * and auto-indexing configuration.
+ *
+ * @module query/adaptive/types
+ */
+/**
+ * Query type for pattern tracking.
+ * Matches the query types from QueryTypes.ts and indexes/types.ts
+ */
+type TrackedQueryType = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'between' | 'in' | 'has' | 'contains' | 'containsAll' | 'containsAny' | 'compound';
+/**
+ * Statistics for a single attribute + query type combination.
+ */
+interface QueryStatistics {
+    /** Attribute name being queried */
+    attribute: string;
+    /** Type of query (eq, gt, between, etc.) */
+    queryType: TrackedQueryType;
+    /** Number of times this pattern was queried */
+    queryCount: number;
+    /** Cumulative execution time in milliseconds */
+    totalCost: number;
+    /** Average execution time per query */
+    averageCost: number;
+    /** Timestamp of last query */
+    lastQueried: number;
+    /** Estimated result size (max observed) */
+    estimatedCardinality: number;
+    /** Whether an index exists for this attribute */
+    hasIndex: boolean;
+}
+/**
+ * Statistics for compound query patterns (Phase 9.03).
+ * Tracks AND combinations of attributes for compound index suggestions.
+ */
+interface CompoundQueryStatistics {
+    /** Attribute names in the compound query (sorted) */
+    attributes: string[];
+    /** Combined key for identification */
+    compoundKey: string;
+    /** Number of times this pattern was queried */
+    queryCount: number;
+    /** Cumulative execution time in milliseconds */
+    totalCost: number;
+    /** Average execution time per query */
+    averageCost: number;
+    /** Timestamp of last query */
+    lastQueried: number;
+    /** Whether a compound index exists for this combination */
+    hasCompoundIndex: boolean;
+}
+/**
+ * Index type recommendation.
+ */
+type RecommendedIndexType = 'hash' | 'navigable' | 'inverted' | 'compound';
+/**
+ * Priority level for index suggestions.
+ */
+type SuggestionPriority = 'high' | 'medium' | 'low';
+/**
+ * Index suggestion generated by IndexAdvisor.
+ */
+interface IndexSuggestion {
+    /** Attribute to index (or compound key for compound indexes) */
+    attribute: string;
+    /** Recommended index type */
+    indexType: RecommendedIndexType;
+    /** Human-readable explanation */
+    reason: string;
+    /** Expected performance improvement multiplier */
+    estimatedBenefit: number;
+    /** Estimated memory overhead in bytes */
+    estimatedCost: number;
+    /** Priority based on query patterns */
+    priority: SuggestionPriority;
+    /** Query count that triggered this suggestion */
+    queryCount: number;
+    /** Average query cost in milliseconds */
+    averageCost: number;
+    /** For compound indexes: array of attribute names in order */
+    compoundAttributes?: string[];
+}
+/**
+ * Options for getting index suggestions.
+ */
+interface IndexSuggestionOptions {
+    /** Minimum query count to consider (default: 10) */
+    minQueryCount?: number;
+    /** Minimum average cost in ms to consider (default: 1) */
+    minAverageCost?: number;
+    /** Whether to exclude already indexed attributes (default: true) */
+    excludeExistingIndexes?: boolean;
+    /** Maximum number of suggestions to return (default: unlimited) */
+    maxSuggestions?: number;
+}
+/**
+ * Configuration for Index Advisor.
+ */
+interface AdvisorConfig {
+    /** Enable advisor mode (default: true) */
+    enabled: boolean;
+    /** Minimum query count before suggesting (default: 10) */
+    minQueryCount?: number;
+    /** Minimum average cost in ms to suggest (default: 1) */
+    minAverageCost?: number;
+}
+/**
+ * Callback for index creation events.
+ */
+type IndexCreatedCallback = (attribute: string, indexType: RecommendedIndexType) => void;
+/**
+ * Configuration for Auto-Index Manager.
+ */
+interface AutoIndexConfig {
+    /** Enable auto-indexing (default: false) */
+    enabled: boolean;
+    /** Number of queries before auto-creating index (default: 10) */
+    threshold?: number;
+    /** Maximum number of auto-created indexes (default: 20) */
+    maxIndexes?: number;
+    /** Callback when index is automatically created */
+    onIndexCreated?: IndexCreatedCallback;
+}
+/**
+ * Default indexing strategy.
+ * - 'none': No automatic indexing (default)
+ * - 'scalar': Index all top-level scalar (primitive) fields
+ * - 'all': Index all fields including nested (not recommended)
+ */
+type DefaultIndexingStrategy = 'none' | 'scalar' | 'all';
+/**
+ * Complete adaptive indexing configuration.
+ */
+interface AdaptiveIndexingConfig {
+    /** Index Advisor configuration */
+    advisor?: AdvisorConfig;
+    /** Auto-Index Manager configuration */
+    autoIndex?: AutoIndexConfig;
+}
+/**
+ * Progress callback for lazy index building (Phase 9.01).
+ */
+type IndexBuildProgressCallback = (attributeName: string, progress: number, // 0-100
+recordsProcessed: number, totalRecords: number) => void;
+/**
+ * Extended options for IndexedLWWMap/IndexedORMap.
+ */
+interface IndexedMapOptions {
+    /** Adaptive indexing configuration */
+    adaptiveIndexing?: AdaptiveIndexingConfig;
+    /** Default indexing strategy (default: 'none') */
+    defaultIndexing?: DefaultIndexingStrategy;
+    /**
+     * Enable lazy index building (Phase 9.01).
+     * When true, indexes are not built until first query.
+     * Default: false
+     */
+    lazyIndexBuilding?: boolean;
+    /**
+     * Callback for index building progress (Phase 9.01).
+     * Called during lazy index materialization.
+     */
+    onIndexBuilding?: IndexBuildProgressCallback;
+}
+
+/**
+ * Lazy Index Types
+ *
+ * Types and interfaces for lazy index building (Phase 9.01).
+ * Lazy indexes defer actual index construction until first query.
+ *
+ * @module query/indexes/lazy/types
+ */
+
+/**
+ * Extended interface for lazy indexes.
+ * Adds lazy-specific properties and methods.
+ */
+interface LazyIndex<K, V, A = unknown> extends Index<K, V, A> {
+    /**
+     * Whether the index has been materialized (built).
+     */
+    readonly isBuilt: boolean;
+    /**
+     * Number of pending records awaiting materialization.
+     */
+    readonly pendingCount: number;
+    /**
+     * Force materialization of the index.
+     * Called automatically on first query, but can be called manually.
+     *
+     * @param progressCallback - Optional progress callback
+     */
+    materialize(progressCallback?: IndexBuildProgressCallback): void;
+    /**
+     * Check if this is a lazy index wrapper.
+     */
+    readonly isLazy: true;
+}
+/**
+ * Options for lazy index creation.
+ */
+interface LazyIndexOptions {
+    /**
+     * Progress callback for index building.
+     */
+    onProgress?: IndexBuildProgressCallback;
+    /**
+     * Batch size for progress reporting.
+     * Default: 1000
+     */
+    progressBatchSize?: number;
+}
+
+/**
+ * LazyHashIndex Implementation
+ *
+ * Hash-based index with deferred building (Phase 9.01).
+ * Records are buffered until first query, then index is materialized.
+ *
+ * Benefits:
+ * - Fast application startup (indexes built on-demand)
+ * - Memory efficiency (unused indexes not built)
+ * - Bulk import optimization (no index overhead during import)
+ *
+ * @module query/indexes/lazy/LazyHashIndex
+ */
+
+/**
+ * Lazy hash-based index for O(1) equality lookups.
+ * Defers index construction until first query.
+ *
+ * K = record key type, V = record value type, A = attribute value type
+ */
+declare class LazyHashIndex<K, V, A> implements LazyIndex<K, V, A> {
+    readonly attribute: Attribute<V, A>;
+    readonly type: "hash";
+    readonly isLazy: true;
+    /** Underlying hash index (created on first query) */
+    private innerIndex;
+    /** Pending records before materialization */
+    private pendingRecords;
+    /** Track if index has been built */
+    private built;
+    /** Progress callback */
+    private readonly onProgress?;
+    /** Batch size for progress reporting */
+    private readonly progressBatchSize;
+    constructor(attribute: Attribute<V, A>, options?: LazyIndexOptions);
+    get isBuilt(): boolean;
+    get pendingCount(): number;
+    getRetrievalCost(): number;
+    supportsQuery(queryType: string): boolean;
+    retrieve(query: IndexQuery<A>): ResultSet<K>;
+    add(key: K, record: V): void;
+    remove(key: K, record: V): void;
+    update(key: K, oldRecord: V, newRecord: V): void;
+    clear(): void;
+    getStats(): IndexStats;
+    /**
+     * Force materialization of the index.
+     * Called automatically on first query.
+     */
+    materialize(progressCallback?: IndexBuildProgressCallback): void;
+    /**
+     * Get the underlying HashIndex (for testing/debugging).
+     * Returns null if not yet materialized.
+     */
+    getInnerIndex(): HashIndex<K, V, A> | null;
+}
+
+/**
+ * LazyNavigableIndex Implementation
+ *
+ * Sorted index with deferred building (Phase 9.01).
+ * Records are buffered until first query, then index is materialized.
+ *
+ * Benefits:
+ * - Fast application startup (indexes built on-demand)
+ * - Memory efficiency (unused indexes not built)
+ * - Bulk import optimization (no index overhead during import)
+ *
+ * @module query/indexes/lazy/LazyNavigableIndex
+ */
+
+/**
+ * Lazy sorted index for O(log N) range queries.
+ * Defers index construction until first query.
+ *
+ * K = record key type, V = record value type, A = attribute value type (must be orderable)
+ */
+declare class LazyNavigableIndex<K, V, A extends string | number> implements LazyIndex<K, V, A> {
+    readonly attribute: Attribute<V, A>;
+    readonly type: "navigable";
+    readonly isLazy: true;
+    /** Underlying navigable index (created on first query) */
+    private innerIndex;
+    /** Pending records before materialization */
+    private pendingRecords;
+    /** Track if index has been built */
+    private built;
+    /** Custom comparator (stored for later index creation) */
+    private readonly comparator?;
+    /** Progress callback */
+    private readonly onProgress?;
+    /** Batch size for progress reporting */
+    private readonly progressBatchSize;
+    constructor(attribute: Attribute<V, A>, comparator?: Comparator<A>, options?: LazyIndexOptions);
+    get isBuilt(): boolean;
+    get pendingCount(): number;
+    getRetrievalCost(): number;
+    supportsQuery(queryType: string): boolean;
+    retrieve(query: IndexQuery<A>): ResultSet<K>;
+    add(key: K, record: V): void;
+    remove(key: K, record: V): void;
+    update(key: K, oldRecord: V, newRecord: V): void;
+    clear(): void;
+    getStats(): IndexStats;
+    /**
+     * Force materialization of the index.
+     * Called automatically on first query.
+     */
+    materialize(progressCallback?: IndexBuildProgressCallback): void;
+    /**
+     * Get the underlying NavigableIndex (for testing/debugging).
+     * Returns null if not yet materialized.
+     */
+    getInnerIndex(): NavigableIndex<K, V, A> | null;
+    /**
+     * Get the minimum indexed value.
+     * Forces materialization if not built.
+     */
+    getMinValue(): A | undefined;
+    /**
+     * Get the maximum indexed value.
+     * Forces materialization if not built.
+     */
+    getMaxValue(): A | undefined;
+}
+
+/**
+ * LazyInvertedIndex Implementation
+ *
+ * Full-text search index with deferred building (Phase 9.01).
+ * Records are buffered until first query, then index is materialized.
+ *
+ * Benefits:
+ * - Fast application startup (indexes built on-demand)
+ * - Memory efficiency (unused indexes not built)
+ * - Bulk import optimization (no index overhead during import)
+ *
+ * @module query/indexes/lazy/LazyInvertedIndex
+ */
+
+/**
+ * Lazy inverted index for full-text search.
+ * Defers index construction until first query.
+ *
+ * K = record key type, V = record value type, A = attribute value type (should be string)
+ */
+declare class LazyInvertedIndex<K, V, A extends string = string> implements LazyIndex<K, V, A> {
+    readonly attribute: Attribute<V, A>;
+    readonly type: "inverted";
+    readonly isLazy: true;
+    /** Underlying inverted index (created on first query) */
+    private innerIndex;
+    /** Pending records before materialization */
+    private pendingRecords;
+    /** Track if index has been built */
+    private built;
+    /** Tokenization pipeline (stored for later index creation) */
+    private readonly pipeline;
+    /** Progress callback */
+    private readonly onProgress?;
+    /** Batch size for progress reporting */
+    private readonly progressBatchSize;
+    constructor(attribute: Attribute<V, A>, pipeline?: TokenizationPipeline, options?: LazyIndexOptions);
+    get isBuilt(): boolean;
+    get pendingCount(): number;
+    getRetrievalCost(): number;
+    supportsQuery(queryType: string): boolean;
+    retrieve(query: IndexQuery<A>): ResultSet<K>;
+    add(key: K, record: V): void;
+    remove(key: K, record: V): void;
+    update(key: K, oldRecord: V, newRecord: V): void;
+    clear(): void;
+    getStats(): IndexStats;
+    /**
+     * Get extended statistics for full-text index.
+     * Forces materialization if not built.
+     */
+    getExtendedStats(): InvertedIndexStats;
+    /**
+     * Force materialization of the index.
+     * Called automatically on first query.
+     */
+    materialize(progressCallback?: IndexBuildProgressCallback): void;
+    /**
+     * Get the underlying InvertedIndex (for testing/debugging).
+     * Returns null if not yet materialized.
+     */
+    getInnerIndex(): InvertedIndex<K, V, A> | null;
+    /**
+     * Get the tokenization pipeline.
+     */
+    getPipeline(): TokenizationPipeline;
+    /**
+     * Check if a specific token exists in the index.
+     * Forces materialization if not built.
+     */
+    hasToken(token: string): boolean;
+    /**
+     * Get the number of documents for a specific token.
+     * Forces materialization if not built.
+     */
+    getTokenDocumentCount(token: string): number;
+}
+
 /**
  * SetResultSet Implementation
  *
@@ -4614,6 +5179,8 @@ declare class LimitResultSet<K> implements ResultSet<K> {
 declare class IndexRegistry<K, V> {
     /** Indexes grouped by attribute name */
     private attributeIndexes;
+    /** Compound indexes (Phase 9.03) - keyed by sorted attribute names */
+    private compoundIndexes;
     /** Fallback index for full scan (optional) */
     private fallbackIndex;
     /**
@@ -4623,6 +5190,12 @@ declare class IndexRegistry<K, V> {
      * @param index - Index to register
      */
     addIndex<A>(index: Index<K, V, A>): void;
+    /**
+     * Register a compound index (Phase 9.03).
+     *
+     * @param index - Compound index to register
+     */
+    addCompoundIndex(index: CompoundIndex<K, V>): void;
     /**
      * Remove an index from the registry.
      *
@@ -4630,6 +5203,13 @@ declare class IndexRegistry<K, V> {
      * @returns true if index was found and removed
      */
     removeIndex<A>(index: Index<K, V, A>): boolean;
+    /**
+     * Remove a compound index (Phase 9.03).
+     *
+     * @param index - Compound index to remove
+     * @returns true if index was found and removed
+     */
+    removeCompoundIndex(index: CompoundIndex<K, V>): boolean;
     /**
      * Get all indexes for an attribute.
      *
@@ -4673,6 +5253,31 @@ declare class IndexRegistry<K, V> {
      * @returns Array of matching indexes sorted by retrieval cost
      */
     findIndexes(attributeName: string, queryType: string): Index<K, V, unknown>[];
+    /**
+     * Find a compound index that covers the given attribute names (Phase 9.03).
+     * The compound index must cover ALL the attributes (exact match or superset).
+     *
+     * @param attributeNames - Array of attribute names to search for
+     * @returns Matching compound index or null
+     */
+    findCompoundIndex(attributeNames: string[]): CompoundIndex<K, V> | null;
+    /**
+     * Check if a compound index exists for the given attributes (Phase 9.03).
+     *
+     * @param attributeNames - Array of attribute names
+     * @returns true if a compound index exists
+     */
+    hasCompoundIndex(attributeNames: string[]): boolean;
+    /**
+     * Get all compound indexes (Phase 9.03).
+     *
+     * @returns Array of all compound indexes
+     */
+    getCompoundIndexes(): CompoundIndex<K, V>[];
+    /**
+     * Create a compound key from attribute names (sorted for consistency).
+     */
+    private makeCompoundKey;
     /**
      * Set a fallback index for queries without a suitable index.
      * Typically a FallbackIndex that performs full scan.
@@ -4733,6 +5338,8 @@ interface IndexRegistryStats {
     totalIndexes: number;
     /** Number of indexed attributes */
     indexedAttributes: number;
+    /** Number of compound indexes (Phase 9.03) */
+    compoundIndexes?: number;
     /** Stats for each index */
     indexes: Array<{
         attribute: string;
@@ -4977,11 +5584,31 @@ declare class QueryOptimizer<K, V> {
      * Strategy: Find child with lowest cost, use as base, filter with rest.
      *
      * CQEngine "smallest first" strategy:
-     * 1. Sort children by merge cost
-     * 2. Use intersection if multiple indexes available
-     * 3. Apply remaining predicates as filters
+     * 1. Check for CompoundIndex covering all eq children (Phase 9.03)
+     * 2. Sort children by merge cost
+     * 3. Use intersection if multiple indexes available
+     * 4. Apply remaining predicates as filters
      */
     private optimizeAnd;
+    /**
+     * Try to use a CompoundIndex for an AND query (Phase 9.03).
+     *
+     * Returns a compound index scan step if:
+     * 1. All children are simple 'eq' queries
+     * 2. A CompoundIndex exists covering all queried attributes
+     *
+     * @param children - Children of the AND query
+     * @returns IndexScanStep using CompoundIndex, or null if not applicable
+     */
+    private tryCompoundIndex;
+    /**
+     * Build values array for compound index query in correct attribute order.
+     *
+     * @param compoundIndex - The compound index to use
+     * @param eqQueries - Array of 'eq' queries
+     * @returns Values array in compound index order, or null if mismatch
+     */
+    private buildCompoundValues;
     /**
      * Optimize OR query.
      * Strategy: Union of all child results with deduplication.
@@ -5168,136 +5795,6 @@ interface LiveQueryManagerStats extends StandingQueryRegistryStats {
     totalSubscribers: number;
 }
 
-/**
- * Types for Adaptive Indexing System (Phase 8.02)
- *
- * Defines interfaces for query pattern tracking, index suggestions,
- * and auto-indexing configuration.
- *
- * @module query/adaptive/types
- */
-/**
- * Query type for pattern tracking.
- * Matches the query types from QueryTypes.ts and indexes/types.ts
- */
-type TrackedQueryType = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'between' | 'in' | 'has' | 'contains' | 'containsAll' | 'containsAny';
-/**
- * Statistics for a single attribute + query type combination.
- */
-interface QueryStatistics {
-    /** Attribute name being queried */
-    attribute: string;
-    /** Type of query (eq, gt, between, etc.) */
-    queryType: TrackedQueryType;
-    /** Number of times this pattern was queried */
-    queryCount: number;
-    /** Cumulative execution time in milliseconds */
-    totalCost: number;
-    /** Average execution time per query */
-    averageCost: number;
-    /** Timestamp of last query */
-    lastQueried: number;
-    /** Estimated result size (max observed) */
-    estimatedCardinality: number;
-    /** Whether an index exists for this attribute */
-    hasIndex: boolean;
-}
-/**
- * Index type recommendation.
- */
-type RecommendedIndexType = 'hash' | 'navigable' | 'inverted';
-/**
- * Priority level for index suggestions.
- */
-type SuggestionPriority = 'high' | 'medium' | 'low';
-/**
- * Index suggestion generated by IndexAdvisor.
- */
-interface IndexSuggestion {
-    /** Attribute to index */
-    attribute: string;
-    /** Recommended index type */
-    indexType: RecommendedIndexType;
-    /** Human-readable explanation */
-    reason: string;
-    /** Expected performance improvement multiplier */
-    estimatedBenefit: number;
-    /** Estimated memory overhead in bytes */
-    estimatedCost: number;
-    /** Priority based on query patterns */
-    priority: SuggestionPriority;
-    /** Query count that triggered this suggestion */
-    queryCount: number;
-    /** Average query cost in milliseconds */
-    averageCost: number;
-}
-/**
- * Options for getting index suggestions.
- */
-interface IndexSuggestionOptions {
-    /** Minimum query count to consider (default: 10) */
-    minQueryCount?: number;
-    /** Minimum average cost in ms to consider (default: 1) */
-    minAverageCost?: number;
-    /** Whether to exclude already indexed attributes (default: true) */
-    excludeExistingIndexes?: boolean;
-    /** Maximum number of suggestions to return (default: unlimited) */
-    maxSuggestions?: number;
-}
-/**
- * Configuration for Index Advisor.
- */
-interface AdvisorConfig {
-    /** Enable advisor mode (default: true) */
-    enabled: boolean;
-    /** Minimum query count before suggesting (default: 10) */
-    minQueryCount?: number;
-    /** Minimum average cost in ms to suggest (default: 1) */
-    minAverageCost?: number;
-}
-/**
- * Callback for index creation events.
- */
-type IndexCreatedCallback = (attribute: string, indexType: RecommendedIndexType) => void;
-/**
- * Configuration for Auto-Index Manager.
- */
-interface AutoIndexConfig {
-    /** Enable auto-indexing (default: false) */
-    enabled: boolean;
-    /** Number of queries before auto-creating index (default: 10) */
-    threshold?: number;
-    /** Maximum number of auto-created indexes (default: 20) */
-    maxIndexes?: number;
-    /** Callback when index is automatically created */
-    onIndexCreated?: IndexCreatedCallback;
-}
-/**
- * Default indexing strategy.
- * - 'none': No automatic indexing (default)
- * - 'scalar': Index all top-level scalar (primitive) fields
- * - 'all': Index all fields including nested (not recommended)
- */
-type DefaultIndexingStrategy = 'none' | 'scalar' | 'all';
-/**
- * Complete adaptive indexing configuration.
- */
-interface AdaptiveIndexingConfig {
-    /** Index Advisor configuration */
-    advisor?: AdvisorConfig;
-    /** Auto-Index Manager configuration */
-    autoIndex?: AutoIndexConfig;
-}
-/**
- * Extended options for IndexedLWWMap/IndexedORMap.
- */
-interface IndexedMapOptions {
-    /** Adaptive indexing configuration */
-    adaptiveIndexing?: AdaptiveIndexingConfig;
-    /** Default indexing strategy (default: 'none') */
-    defaultIndexing?: DefaultIndexingStrategy;
-}
-
 /**
  * QueryPatternTracker (Phase 8.02.1)
  *
@@ -5347,6 +5844,9 @@ interface QueryPatternTrackerOptions {
  * tracker.recordQuery('category', 'eq', 5.2, 100, false);
  * tracker.recordQuery('category', 'eq', 4.8, 100, false);
  *
+ * // Record compound AND queries (Phase 9.03)
+ * tracker.recordCompoundQuery(['status', 'category'], 10.5, 50, false);
+ *
  * // Get statistics
  * const stats = tracker.getStatistics();
  * // [{ attribute: 'category', queryType: 'eq', queryCount: 2, averageCost: 5.0, ... }]
@@ -5354,6 +5854,7 @@ interface QueryPatternTrackerOptions {
  */
 declare class QueryPatternTracker {
     private stats;
+    private compoundStats;
     private queryCounter;
     private readonly samplingRate;
     private readonly maxTrackedPatterns;
@@ -5369,6 +5870,42 @@ declare class QueryPatternTracker {
      * @param hasIndex - Whether an index was used
      */
     recordQuery(attribute: string, queryType: TrackedQueryType, executionTime: number, resultSize: number, hasIndex: boolean): void;
+    /**
+     * Record a compound (AND) query execution for pattern tracking (Phase 9.03).
+     *
+     * @param attributes - Array of attribute names being queried together
+     * @param executionTime - Query execution time in milliseconds
+     * @param resultSize - Number of results returned
+     * @param hasCompoundIndex - Whether a compound index was used
+     */
+    recordCompoundQuery(attributes: string[], executionTime: number, resultSize: number, hasCompoundIndex: boolean): void;
+    /**
+     * Get all compound query statistics (Phase 9.03).
+     *
+     * @returns Array of compound query statistics, sorted by query count descending
+     */
+    getCompoundStatistics(): CompoundQueryStatistics[];
+    /**
+     * Get compound statistics for a specific attribute combination.
+     *
+     * @param attributes - Array of attribute names
+     * @returns Compound query statistics or undefined
+     */
+    getCompoundStats(attributes: string[]): CompoundQueryStatistics | undefined;
+    /**
+     * Check if attributes appear in any tracked compound queries.
+     *
+     * @param attribute - The attribute name to check
+     * @returns True if attribute is part of any compound query pattern
+     */
+    isInCompoundPattern(attribute: string): boolean;
+    /**
+     * Update compound index status.
+     *
+     * @param attributes - Array of attribute names
+     * @param hasCompoundIndex - Whether a compound index exists
+     */
+    updateCompoundIndexStatus(attributes: string[], hasCompoundIndex: boolean): void;
     /**
      * Get all query statistics.
      *
@@ -5435,6 +5972,7 @@ declare class QueryPatternTracker {
      */
     getTrackingInfo(): {
         patternsTracked: number;
+        compoundPatternsTracked: number;
         totalQueries: number;
         samplingRate: number;
         memoryEstimate: number;
@@ -5447,6 +5985,14 @@ declare class QueryPatternTracker {
      * Prune stale statistics older than TTL.
      */
     private pruneStale;
+    /**
+     * Evict the oldest compound query entry (Phase 9.03).
+     */
+    private evictOldestCompound;
+    /**
+     * Prune stale compound statistics (Phase 9.03).
+     */
+    private pruneStaleCompound;
 }
 
 /**
@@ -5556,6 +6102,52 @@ declare class IndexAdvisor {
      * Generate human-readable reason for the suggestion.
      */
     private generateReason;
+    /**
+     * Get compound index suggestions based on AND query patterns.
+     *
+     * @param options - Suggestion options
+     * @returns Array of compound index suggestions
+     */
+    getCompoundSuggestions(options?: IndexSuggestionOptions): IndexSuggestion[];
+    /**
+     * Get a suggestion for a specific compound attribute combination.
+     *
+     * @param attributes - Array of attribute names
+     * @returns Compound index suggestion or null if not recommended
+     */
+    getCompoundSuggestionFor(attributes: string[]): IndexSuggestion | null;
+    /**
+     * Check if a compound index should be created for the given attributes.
+     *
+     * @param attributes - Array of attribute names
+     * @param threshold - Minimum query count threshold
+     * @returns True if compound index should be created
+     */
+    shouldCreateCompoundIndex(attributes: string[], threshold?: number): boolean;
+    /**
+     * Generate a suggestion for a compound query pattern.
+     */
+    private generateCompoundSuggestion;
+    /**
+     * Estimate performance benefit of adding a compound index.
+     *
+     * Compound indexes provide significant speedup for AND queries:
+     * - Eliminates intersection operations (100-1000× for each attribute)
+     * - Single O(1) lookup instead of multiple index scans
+     */
+    private estimateCompoundBenefit;
+    /**
+     * Estimate memory cost of adding a compound index.
+     */
+    private estimateCompoundMemoryCost;
+    /**
+     * Calculate priority for compound index suggestion.
+     */
+    private calculateCompoundPriority;
+    /**
+     * Generate human-readable reason for compound index suggestion.
+     */
+    private generateCompoundReason;
 }
 
 /**
@@ -5742,27 +6334,30 @@ declare class IndexedLWWMap<K extends string, V> extends LWWMap<K, V> {
     constructor(hlc: HLC, options?: IndexedMapOptions);
     /**
      * Add a hash index on an attribute.
+     * If lazyIndexBuilding is enabled, creates a LazyHashIndex instead.
      *
      * @param attribute - Attribute to index
-     * @returns Created HashIndex
+     * @returns Created HashIndex (or LazyHashIndex)
      */
-    addHashIndex<A>(attribute: Attribute<V, A>): HashIndex<K, V, A>;
+    addHashIndex<A>(attribute: Attribute<V, A>): HashIndex<K, V, A> | LazyHashIndex<K, V, A>;
     /**
      * Add a navigable index on an attribute.
      * Navigable indexes support range queries (gt, gte, lt, lte, between).
+     * If lazyIndexBuilding is enabled, creates a LazyNavigableIndex instead.
      *
      * @param attribute - Attribute to index
      * @param comparator - Optional custom comparator
-     * @returns Created NavigableIndex
+     * @returns Created NavigableIndex (or LazyNavigableIndex)
      */
-    addNavigableIndex<A extends string | number>(attribute: Attribute<V, A>, comparator?: (a: A, b: A) => number): NavigableIndex<K, V, A>;
+    addNavigableIndex<A extends string | number>(attribute: Attribute<V, A>, comparator?: (a: A, b: A) => number): NavigableIndex<K, V, A> | LazyNavigableIndex<K, V, A>;
     /**
      * Add an inverted index for full-text search on an attribute.
      * Inverted indexes support text search queries (contains, containsAll, containsAny).
+     * If lazyIndexBuilding is enabled, creates a LazyInvertedIndex instead.
      *
      * @param attribute - Text attribute to index
      * @param pipeline - Optional custom tokenization pipeline
-     * @returns Created InvertedIndex
+     * @returns Created InvertedIndex (or LazyInvertedIndex)
      *
      * @example
      * ```typescript
@@ -5773,7 +6368,7 @@ declare class IndexedLWWMap<K extends string, V> extends LWWMap<K, V> {
      * products.query({ type: 'contains', attribute: 'name', value: 'wireless' });
      * ```
      */
-    addInvertedIndex<A extends string = string>(attribute: Attribute<V, A>, pipeline?: TokenizationPipeline): InvertedIndex<K, V, A>;
+    addInvertedIndex<A extends string = string>(attribute: Attribute<V, A>, pipeline?: TokenizationPipeline): InvertedIndex<K, V, A> | LazyInvertedIndex<K, V, A>;
     /**
      * Add a custom index.
      *
@@ -5984,6 +6579,26 @@ declare class IndexedLWWMap<K extends string, V> extends LWWMap<K, V> {
      * Check if auto-indexing is enabled.
      */
     isAutoIndexingEnabled(): boolean;
+    /**
+     * Check if lazy index building is enabled.
+     */
+    isLazyIndexingEnabled(): boolean;
+    /**
+     * Force materialization of all lazy indexes.
+     * Useful to pre-warm indexes before critical operations.
+     *
+     * @param progressCallback - Optional progress callback
+     */
+    materializeAllIndexes(progressCallback?: IndexBuildProgressCallback): void;
+    /**
+     * Get count of pending records across all lazy indexes.
+     * Returns 0 if no lazy indexes or all are materialized.
+     */
+    getPendingIndexCount(): number;
+    /**
+     * Check if any lazy indexes are still pending (not built).
+     */
+    hasUnbuiltIndexes(): boolean;
     /**
      * Track query pattern for adaptive indexing.
      */