@topgunbuild/core 0.5.0 → 0.7.0

package/dist/index.js

@@ -4510,6 +4510,593 @@ _InvertedIndex.RETRIEVAL_COST = 50;
 _InvertedIndex.SUPPORTED_QUERIES = ["contains", "containsAll", "containsAny", "has"];
 var InvertedIndex = _InvertedIndex;
 
+// src/query/indexes/CompoundIndex.ts
+var _CompoundIndex = class _CompoundIndex {
+  /**
+   * 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, options = {}) {
+    this.type = "compound";
+    /** Map from composite key to set of record keys */
+    this.data = /* @__PURE__ */ new Map();
+    /** Set of all indexed keys */
+    this.allKeys = /* @__PURE__ */ new Set();
+    if (attributes.length < 2) {
+      throw new Error("CompoundIndex requires at least 2 attributes");
+    }
+    this._attributes = attributes;
+    this.separator = options.separator ?? "|";
+  }
+  /**
+   * Get the first attribute (used for Index interface compatibility).
+   * Note: CompoundIndex spans multiple attributes.
+   */
+  get attribute() {
+    return this._attributes[0];
+  }
+  /**
+   * Get all attributes in this compound index.
+   */
+  get attributes() {
+    return [...this._attributes];
+  }
+  /**
+   * Get attribute names as a combined identifier.
+   */
+  get compoundName() {
+    return this._attributes.map((a) => a.name).join("+");
+  }
+  getRetrievalCost() {
+    return _CompoundIndex.RETRIEVAL_COST;
+  }
+  supportsQuery(queryType) {
+    return queryType === "compound";
+  }
+  /**
+   * 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) {
+    if (query.type !== "compound") {
+      throw new Error(`CompoundIndex only supports 'compound' query type, got: ${query.type}`);
+    }
+    const compoundQuery = query;
+    const values = compoundQuery.values;
+    if (values.length !== this._attributes.length) {
+      throw new Error(
+        `CompoundIndex requires ${this._attributes.length} values, got ${values.length}`
+      );
+    }
+    const compositeKey = this.buildCompositeKey(values);
+    const keys = this.data.get(compositeKey);
+    return new SetResultSet(
+      keys ? new Set(keys) : /* @__PURE__ */ new Set(),
+      _CompoundIndex.RETRIEVAL_COST
+    );
+  }
+  /**
+   * Retrieve with explicit values (convenience method).
+   *
+   * @param values - Values in order of index attributes
+   * @returns ResultSet of matching keys
+   */
+  retrieveByValues(...values) {
+    return this.retrieve({ type: "compound", values });
+  }
+  add(key, record) {
+    const compositeKey = this.buildCompositeKeyFromRecord(record);
+    if (compositeKey === null) return;
+    let keys = this.data.get(compositeKey);
+    if (!keys) {
+      keys = /* @__PURE__ */ new Set();
+      this.data.set(compositeKey, keys);
+    }
+    keys.add(key);
+    this.allKeys.add(key);
+  }
+  remove(key, record) {
+    const compositeKey = this.buildCompositeKeyFromRecord(record);
+    if (compositeKey === null) return;
+    const keys = this.data.get(compositeKey);
+    if (keys) {
+      keys.delete(key);
+      if (keys.size === 0) {
+        this.data.delete(compositeKey);
+      }
+    }
+    this.allKeys.delete(key);
+  }
+  update(key, oldRecord, newRecord) {
+    const oldKey = this.buildCompositeKeyFromRecord(oldRecord);
+    const newKey = this.buildCompositeKeyFromRecord(newRecord);
+    if (oldKey === newKey) {
+      return;
+    }
+    this.remove(key, oldRecord);
+    this.add(key, newRecord);
+  }
+  clear() {
+    this.data.clear();
+    this.allKeys.clear();
+  }
+  getStats() {
+    let totalEntries = 0;
+    for (const keys of this.data.values()) {
+      totalEntries += keys.size;
+    }
+    return {
+      distinctValues: this.data.size,
+      totalEntries,
+      avgEntriesPerValue: this.data.size > 0 ? totalEntries / this.data.size : 0
+    };
+  }
+  /**
+   * Get extended statistics for compound index.
+   */
+  getExtendedStats() {
+    const stats = this.getStats();
+    return {
+      ...stats,
+      attributeCount: this._attributes.length,
+      attributeNames: this._attributes.map((a) => a.name),
+      compositeKeyCount: this.data.size
+    };
+  }
+  /**
+   * 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) {
+    if (attributeNames.length !== this._attributes.length) {
+      return false;
+    }
+    for (let i = 0; i < attributeNames.length; i++) {
+      if (attributeNames[i] !== this._attributes[i].name) {
+        return false;
+      }
+    }
+    return true;
+  }
+  /**
+   * Build composite key from array of values.
+   */
+  buildCompositeKey(values) {
+    return values.map((v) => this.encodeValue(v)).join(this.separator);
+  }
+  /**
+   * Build composite key from record by extracting attribute values.
+   * Returns null if any attribute value is undefined.
+   */
+  buildCompositeKeyFromRecord(record) {
+    const values = [];
+    for (const attr of this._attributes) {
+      const value = attr.getValue(record);
+      if (value === void 0) {
+        return null;
+      }
+      values.push(value);
+    }
+    return this.buildCompositeKey(values);
+  }
+  /**
+   * Encode value for composite key.
+   * Handles common types and escapes separator.
+   */
+  encodeValue(value) {
+    if (value === null) return "__null__";
+    if (value === void 0) return "__undefined__";
+    const str = String(value);
+    return str.replace(
+      new RegExp(this.escapeRegex(this.separator), "g"),
+      `\\${this.separator}`
+    );
+  }
+  /**
+   * Escape regex special characters.
+   */
+  escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  }
+};
+/** Retrieval cost (lower than individual indexes combined) */
+_CompoundIndex.RETRIEVAL_COST = 20;
+var CompoundIndex = _CompoundIndex;
+function isCompoundIndex(index) {
+  return index.type === "compound";
+}
+
+// src/query/indexes/lazy/LazyHashIndex.ts
+var LazyHashIndex = class {
+  constructor(attribute, options = {}) {
+    this.attribute = attribute;
+    this.type = "hash";
+    this.isLazy = true;
+    /** Underlying hash index (created on first query) */
+    this.innerIndex = null;
+    /** Pending records before materialization */
+    this.pendingRecords = /* @__PURE__ */ new Map();
+    /** Track if index has been built */
+    this.built = false;
+    this.onProgress = options.onProgress;
+    this.progressBatchSize = options.progressBatchSize ?? 1e3;
+  }
+  get isBuilt() {
+    return this.built;
+  }
+  get pendingCount() {
+    return this.pendingRecords.size;
+  }
+  getRetrievalCost() {
+    return 30;
+  }
+  supportsQuery(queryType) {
+    return ["equal", "in", "has"].includes(queryType);
+  }
+  retrieve(query) {
+    if (!this.built) {
+      this.materialize();
+    }
+    return this.innerIndex.retrieve(query);
+  }
+  add(key, record) {
+    if (this.built) {
+      this.innerIndex.add(key, record);
+    } else {
+      this.pendingRecords.set(key, record);
+    }
+  }
+  remove(key, record) {
+    if (this.built) {
+      this.innerIndex.remove(key, record);
+    } else {
+      this.pendingRecords.delete(key);
+    }
+  }
+  update(key, oldRecord, newRecord) {
+    if (this.built) {
+      this.innerIndex.update(key, oldRecord, newRecord);
+    } else {
+      this.pendingRecords.set(key, newRecord);
+    }
+  }
+  clear() {
+    if (this.built) {
+      this.innerIndex.clear();
+    }
+    this.pendingRecords.clear();
+  }
+  getStats() {
+    if (this.built) {
+      return this.innerIndex.getStats();
+    }
+    return {
+      distinctValues: 0,
+      totalEntries: this.pendingRecords.size,
+      avgEntriesPerValue: 0
+    };
+  }
+  /**
+   * Force materialization of the index.
+   * Called automatically on first query.
+   */
+  materialize(progressCallback) {
+    if (this.built) return;
+    const callback = progressCallback ?? this.onProgress;
+    const total = this.pendingRecords.size;
+    this.innerIndex = new HashIndex(this.attribute);
+    let processed = 0;
+    for (const [key, record] of this.pendingRecords) {
+      this.innerIndex.add(key, record);
+      processed++;
+      if (callback && processed % this.progressBatchSize === 0) {
+        const progress = Math.round(processed / total * 100);
+        callback(this.attribute.name, progress, processed, total);
+      }
+    }
+    if (callback && total > 0) {
+      callback(this.attribute.name, 100, total, total);
+    }
+    this.pendingRecords.clear();
+    this.built = true;
+  }
+  /**
+   * Get the underlying HashIndex (for testing/debugging).
+   * Returns null if not yet materialized.
+   */
+  getInnerIndex() {
+    return this.innerIndex;
+  }
+};
+
+// src/query/indexes/lazy/LazyNavigableIndex.ts
+var LazyNavigableIndex = class {
+  constructor(attribute, comparator, options = {}) {
+    this.attribute = attribute;
+    this.type = "navigable";
+    this.isLazy = true;
+    /** Underlying navigable index (created on first query) */
+    this.innerIndex = null;
+    /** Pending records before materialization */
+    this.pendingRecords = /* @__PURE__ */ new Map();
+    /** Track if index has been built */
+    this.built = false;
+    this.comparator = comparator;
+    this.onProgress = options.onProgress;
+    this.progressBatchSize = options.progressBatchSize ?? 1e3;
+  }
+  get isBuilt() {
+    return this.built;
+  }
+  get pendingCount() {
+    return this.pendingRecords.size;
+  }
+  getRetrievalCost() {
+    return 40;
+  }
+  supportsQuery(queryType) {
+    return ["equal", "in", "has", "gt", "gte", "lt", "lte", "between"].includes(queryType);
+  }
+  retrieve(query) {
+    if (!this.built) {
+      this.materialize();
+    }
+    return this.innerIndex.retrieve(query);
+  }
+  add(key, record) {
+    if (this.built) {
+      this.innerIndex.add(key, record);
+    } else {
+      this.pendingRecords.set(key, record);
+    }
+  }
+  remove(key, record) {
+    if (this.built) {
+      this.innerIndex.remove(key, record);
+    } else {
+      this.pendingRecords.delete(key);
+    }
+  }
+  update(key, oldRecord, newRecord) {
+    if (this.built) {
+      this.innerIndex.update(key, oldRecord, newRecord);
+    } else {
+      this.pendingRecords.set(key, newRecord);
+    }
+  }
+  clear() {
+    if (this.built) {
+      this.innerIndex.clear();
+    }
+    this.pendingRecords.clear();
+  }
+  getStats() {
+    if (this.built) {
+      return this.innerIndex.getStats();
+    }
+    return {
+      distinctValues: 0,
+      totalEntries: this.pendingRecords.size,
+      avgEntriesPerValue: 0
+    };
+  }
+  /**
+   * Force materialization of the index.
+   * Called automatically on first query.
+   */
+  materialize(progressCallback) {
+    if (this.built) return;
+    const callback = progressCallback ?? this.onProgress;
+    const total = this.pendingRecords.size;
+    this.innerIndex = new NavigableIndex(this.attribute, this.comparator);
+    let processed = 0;
+    for (const [key, record] of this.pendingRecords) {
+      this.innerIndex.add(key, record);
+      processed++;
+      if (callback && processed % this.progressBatchSize === 0) {
+        const progress = Math.round(processed / total * 100);
+        callback(this.attribute.name, progress, processed, total);
+      }
+    }
+    if (callback && total > 0) {
+      callback(this.attribute.name, 100, total, total);
+    }
+    this.pendingRecords.clear();
+    this.built = true;
+  }
+  /**
+   * Get the underlying NavigableIndex (for testing/debugging).
+   * Returns null if not yet materialized.
+   */
+  getInnerIndex() {
+    return this.innerIndex;
+  }
+  /**
+   * Get the minimum indexed value.
+   * Forces materialization if not built.
+   */
+  getMinValue() {
+    if (!this.built) {
+      this.materialize();
+    }
+    return this.innerIndex.getMinValue();
+  }
+  /**
+   * Get the maximum indexed value.
+   * Forces materialization if not built.
+   */
+  getMaxValue() {
+    if (!this.built) {
+      this.materialize();
+    }
+    return this.innerIndex.getMaxValue();
+  }
+};
+
+// src/query/indexes/lazy/LazyInvertedIndex.ts
+var LazyInvertedIndex = class {
+  constructor(attribute, pipeline, options = {}) {
+    this.attribute = attribute;
+    this.type = "inverted";
+    this.isLazy = true;
+    /** Underlying inverted index (created on first query) */
+    this.innerIndex = null;
+    /** Pending records before materialization */
+    this.pendingRecords = /* @__PURE__ */ new Map();
+    /** Track if index has been built */
+    this.built = false;
+    this.pipeline = pipeline ?? TokenizationPipeline.simple();
+    this.onProgress = options.onProgress;
+    this.progressBatchSize = options.progressBatchSize ?? 1e3;
+  }
+  get isBuilt() {
+    return this.built;
+  }
+  get pendingCount() {
+    return this.pendingRecords.size;
+  }
+  getRetrievalCost() {
+    return 50;
+  }
+  supportsQuery(queryType) {
+    return ["contains", "containsAll", "containsAny", "has"].includes(queryType);
+  }
+  retrieve(query) {
+    if (!this.built) {
+      this.materialize();
+    }
+    return this.innerIndex.retrieve(query);
+  }
+  add(key, record) {
+    if (this.built) {
+      this.innerIndex.add(key, record);
+    } else {
+      this.pendingRecords.set(key, record);
+    }
+  }
+  remove(key, record) {
+    if (this.built) {
+      this.innerIndex.remove(key, record);
+    } else {
+      this.pendingRecords.delete(key);
+    }
+  }
+  update(key, oldRecord, newRecord) {
+    if (this.built) {
+      this.innerIndex.update(key, oldRecord, newRecord);
+    } else {
+      this.pendingRecords.set(key, newRecord);
+    }
+  }
+  clear() {
+    if (this.built) {
+      this.innerIndex.clear();
+    }
+    this.pendingRecords.clear();
+  }
+  getStats() {
+    if (this.built) {
+      return this.innerIndex.getStats();
+    }
+    return {
+      distinctValues: 0,
+      totalEntries: this.pendingRecords.size,
+      avgEntriesPerValue: 0
+    };
+  }
+  /**
+   * Get extended statistics for full-text index.
+   * Forces materialization if not built.
+   */
+  getExtendedStats() {
+    if (!this.built) {
+      this.materialize();
+    }
+    return this.innerIndex.getExtendedStats();
+  }
+  /**
+   * Force materialization of the index.
+   * Called automatically on first query.
+   */
+  materialize(progressCallback) {
+    if (this.built) return;
+    const callback = progressCallback ?? this.onProgress;
+    const total = this.pendingRecords.size;
+    this.innerIndex = new InvertedIndex(this.attribute, this.pipeline);
+    let processed = 0;
+    for (const [key, record] of this.pendingRecords) {
+      this.innerIndex.add(key, record);
+      processed++;
+      if (callback && processed % this.progressBatchSize === 0) {
+        const progress = Math.round(processed / total * 100);
+        callback(this.attribute.name, progress, processed, total);
+      }
+    }
+    if (callback && total > 0) {
+      callback(this.attribute.name, 100, total, total);
+    }
+    this.pendingRecords.clear();
+    this.built = true;
+  }
+  /**
+   * Get the underlying InvertedIndex (for testing/debugging).
+   * Returns null if not yet materialized.
+   */
+  getInnerIndex() {
+    return this.innerIndex;
+  }
+  /**
+   * Get the tokenization pipeline.
+   */
+  getPipeline() {
+    return this.pipeline;
+  }
+  /**
+   * Check if a specific token exists in the index.
+   * Forces materialization if not built.
+   */
+  hasToken(token) {
+    if (!this.built) {
+      this.materialize();
+    }
+    return this.innerIndex.hasToken(token);
+  }
+  /**
+   * Get the number of documents for a specific token.
+   * Forces materialization if not built.
+   */
+  getTokenDocumentCount(token) {
+    if (!this.built) {
+      this.materialize();
+    }
+    return this.innerIndex.getTokenDocumentCount(token);
+  }
+};
+
 // src/query/resultset/IntersectionResultSet.ts
 var IntersectionResultSet = class {
   /**
@@ -5063,6 +5650,8 @@ var IndexRegistry = class {
   constructor() {
     /** Indexes grouped by attribute name */
     this.attributeIndexes = /* @__PURE__ */ new Map();
+    /** Compound indexes (Phase 9.03) - keyed by sorted attribute names */
+    this.compoundIndexes = /* @__PURE__ */ new Map();
     /** Fallback index for full scan (optional) */
     this.fallbackIndex = null;
   }
@@ -5073,6 +5662,10 @@ var IndexRegistry = class {
    * @param index - Index to register
    */
   addIndex(index) {
+    if (isCompoundIndex(index)) {
+      this.addCompoundIndex(index);
+      return;
+    }
     const attrName = index.attribute.name;
     let indexes = this.attributeIndexes.get(attrName);
     if (!indexes) {
@@ -5083,6 +5676,15 @@ var IndexRegistry = class {
       indexes.push(index);
     }
   }
+  /**
+   * Register a compound index (Phase 9.03).
+   *
+   * @param index - Compound index to register
+   */
+  addCompoundIndex(index) {
+    const key = this.makeCompoundKey(index.attributes.map((a) => a.name));
+    this.compoundIndexes.set(key, index);
+  }
   /**
    * Remove an index from the registry.
    *
@@ -5090,6 +5692,9 @@ var IndexRegistry = class {
    * @returns true if index was found and removed
    */
   removeIndex(index) {
+    if (isCompoundIndex(index)) {
+      return this.removeCompoundIndex(index);
+    }
     const attrName = index.attribute.name;
     const indexes = this.attributeIndexes.get(attrName);
     if (!indexes) {
@@ -5105,6 +5710,16 @@ var IndexRegistry = class {
     }
     return true;
   }
+  /**
+   * Remove a compound index (Phase 9.03).
+   *
+   * @param index - Compound index to remove
+   * @returns true if index was found and removed
+   */
+  removeCompoundIndex(index) {
+    const key = this.makeCompoundKey(index.attributes.map((a) => a.name));
+    return this.compoundIndexes.delete(key);
+  }
   /**
    * Get all indexes for an attribute.
    *
@@ -5175,6 +5790,50 @@ var IndexRegistry = class {
     const indexes = this.getIndexes(attributeName);
     return indexes.filter((index) => index.supportsQuery(queryType)).sort((a, b) => a.getRetrievalCost() - b.getRetrievalCost());
   }
+  // ========================================
+  // Phase 9.03: Compound Index Methods
+  // ========================================
+  /**
+   * 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) {
+    if (attributeNames.length < 2) {
+      return null;
+    }
+    const key = this.makeCompoundKey(attributeNames);
+    const exactMatch = this.compoundIndexes.get(key);
+    if (exactMatch) {
+      return exactMatch;
+    }
+    return 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) {
+    return this.findCompoundIndex(attributeNames) !== null;
+  }
+  /**
+   * Get all compound indexes (Phase 9.03).
+   *
+   * @returns Array of all compound indexes
+   */
+  getCompoundIndexes() {
+    return Array.from(this.compoundIndexes.values());
+  }
+  /**
+   * Create a compound key from attribute names (sorted for consistency).
+   */
+  makeCompoundKey(attributeNames) {
+    return [...attributeNames].sort().join("+");
+  }
   /**
    * Set a fallback index for queries without a suitable index.
    * Typically a FallbackIndex that performs full scan.
@@ -5205,6 +5864,9 @@ var IndexRegistry = class {
         index.add(key, record);
       }
     }
+    for (const compoundIndex of this.compoundIndexes.values()) {
+      compoundIndex.add(key, record);
+    }
   }
   /**
    * Notify all indexes of a record update.
@@ -5220,6 +5882,9 @@ var IndexRegistry = class {
         index.update(key, oldRecord, newRecord);
       }
     }
+    for (const compoundIndex of this.compoundIndexes.values()) {
+      compoundIndex.update(key, oldRecord, newRecord);
+    }
   }
   /**
    * Notify all indexes of a record removal.
@@ -5234,6 +5899,9 @@ var IndexRegistry = class {
         index.remove(key, record);
       }
     }
+    for (const compoundIndex of this.compoundIndexes.values()) {
+      compoundIndex.remove(key, record);
+    }
   }
   /**
    * Clear all indexes.
@@ -5245,6 +5913,9 @@ var IndexRegistry = class {
         index.clear();
       }
     }
+    for (const compoundIndex of this.compoundIndexes.values()) {
+      compoundIndex.clear();
+    }
   }
   /**
    * Get total number of registered indexes.
@@ -5254,6 +5925,7 @@ var IndexRegistry = class {
     for (const indexes of this.attributeIndexes.values()) {
       count += indexes.length;
     }
+    count += this.compoundIndexes.size;
     return count;
   }
   /**
@@ -5266,9 +5938,17 @@ var IndexRegistry = class {
       type: index.type,
       stats: index.getStats()
     }));
+    for (const compoundIndex of this.compoundIndexes.values()) {
+      indexStats.push({
+        attribute: compoundIndex.compoundName,
+        type: "compound",
+        stats: compoundIndex.getStats()
+      });
+    }
     return {
-      totalIndexes: indexes.length,
+      totalIndexes: indexes.length + this.compoundIndexes.size,
       indexedAttributes: this.getIndexedAttributes().length,
+      compoundIndexes: this.compoundIndexes.size,
       indexes: indexStats
     };
   }
@@ -5402,9 +6082,10 @@ var QueryOptimizer = class {
    * 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
    */
   optimizeAnd(query) {
     if (!query.children || query.children.length === 0) {
@@ -5413,6 +6094,10 @@ var QueryOptimizer = class {
     if (query.children.length === 1) {
       return this.optimizeNode(query.children[0]);
     }
+    const compoundStep = this.tryCompoundIndex(query.children);
+    if (compoundStep) {
+      return compoundStep;
+    }
     const childSteps = query.children.map((child) => this.optimizeNode(child));
     const sortedWithIndex = childSteps.map((step, index) => ({ step, originalIndex: index })).sort((a, b) => this.estimateCost(a.step) - this.estimateCost(b.step));
     const sortedSteps = sortedWithIndex.map((s) => s.step);
@@ -5437,6 +6122,71 @@ var QueryOptimizer = class {
     }
     return { type: "intersection", steps: indexedSteps };
   }
+  /**
+   * 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
+   */
+  tryCompoundIndex(children) {
+    const eqQueries = [];
+    const otherQueries = [];
+    for (const child of children) {
+      if (isSimpleQuery(child) && child.type === "eq") {
+        eqQueries.push(child);
+      } else {
+        otherQueries.push(child);
+      }
+    }
+    if (eqQueries.length < 2) {
+      return null;
+    }
+    const attributeNames = eqQueries.map((q) => q.attribute);
+    const compoundIndex = this.indexRegistry.findCompoundIndex(attributeNames);
+    if (!compoundIndex) {
+      return null;
+    }
+    const values = this.buildCompoundValues(compoundIndex, eqQueries);
+    if (!values) {
+      return null;
+    }
+    const compoundStep = {
+      type: "index-scan",
+      index: compoundIndex,
+      query: { type: "compound", values }
+    };
+    if (otherQueries.length > 0) {
+      const filterPredicate = otherQueries.length === 1 ? otherQueries[0] : { type: "and", children: otherQueries };
+      return { type: "filter", source: compoundStep, predicate: filterPredicate };
+    }
+    return compoundStep;
+  }
+  /**
+   * 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
+   */
+  buildCompoundValues(compoundIndex, eqQueries) {
+    const attributeNames = compoundIndex.attributes.map((a) => a.name);
+    const values = [];
+    const queryMap = /* @__PURE__ */ new Map();
+    for (const q of eqQueries) {
+      queryMap.set(q.attribute, q.value);
+    }
+    for (const attrName of attributeNames) {
+      if (!queryMap.has(attrName)) {
+        return null;
+      }
+      values.push(queryMap.get(attrName));
+    }
+    return values;
+  }
   /**
    * Optimize OR query.
    * Strategy: Union of all child results with deduplication.
@@ -5993,7 +6743,9 @@ var MEMORY_OVERHEAD_ESTIMATES = {
   /** Navigable index overhead per record */
   navigable: 32,
   /** Inverted index overhead per record (depends on token count) */
-  inverted: 48
+  inverted: 48,
+  /** Compound index overhead per record (includes composite key) */
+  compound: 40
 };
 
 // src/query/adaptive/QueryPatternTracker.ts
@@ -6010,6 +6762,7 @@ function parseStatsKey(key) {
 var QueryPatternTracker = class {
   constructor(options = {}) {
     this.stats = /* @__PURE__ */ new Map();
+    this.compoundStats = /* @__PURE__ */ new Map();
     this.queryCounter = 0;
     this.samplingRate = options.samplingRate ?? TRACKING_SAMPLE_RATE;
     this.maxTrackedPatterns = options.maxTrackedPatterns ?? 1e3;
@@ -6056,6 +6809,94 @@ var QueryPatternTracker = class {
       });
     }
   }
+  /**
+   * 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, executionTime, resultSize, hasCompoundIndex) {
+    if (attributes.length < 2) return;
+    this.queryCounter++;
+    if (this.samplingRate > 1 && this.queryCounter % this.samplingRate !== 0) {
+      return;
+    }
+    const sortedAttrs = [...attributes].sort();
+    const compoundKey = sortedAttrs.join("+");
+    const existing = this.compoundStats.get(compoundKey);
+    const now = Date.now();
+    if (existing) {
+      existing.queryCount++;
+      existing.totalCost += executionTime;
+      existing.averageCost = existing.totalCost / existing.queryCount;
+      existing.lastQueried = now;
+      existing.hasCompoundIndex = hasCompoundIndex;
+    } else {
+      if (this.compoundStats.size >= this.maxTrackedPatterns) {
+        this.evictOldestCompound();
+      }
+      this.compoundStats.set(compoundKey, {
+        attributes: sortedAttrs,
+        compoundKey,
+        queryCount: this.samplingRate,
+        // Adjust for sampling
+        totalCost: executionTime * this.samplingRate,
+        averageCost: executionTime,
+        lastQueried: now,
+        hasCompoundIndex
+      });
+    }
+  }
+  /**
+   * Get all compound query statistics (Phase 9.03).
+   *
+   * @returns Array of compound query statistics, sorted by query count descending
+   */
+  getCompoundStatistics() {
+    this.pruneStaleCompound();
+    return Array.from(this.compoundStats.values()).sort((a, b) => b.queryCount - a.queryCount);
+  }
+  /**
+   * Get compound statistics for a specific attribute combination.
+   *
+   * @param attributes - Array of attribute names
+   * @returns Compound query statistics or undefined
+   */
+  getCompoundStats(attributes) {
+    const sortedAttrs = [...attributes].sort();
+    const compoundKey = sortedAttrs.join("+");
+    return this.compoundStats.get(compoundKey);
+  }
+  /**
+   * 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) {
+    for (const stat of this.compoundStats.values()) {
+      if (stat.attributes.includes(attribute)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  /**
+   * Update compound index status.
+   *
+   * @param attributes - Array of attribute names
+   * @param hasCompoundIndex - Whether a compound index exists
+   */
+  updateCompoundIndexStatus(attributes, hasCompoundIndex) {
+    const sortedAttrs = [...attributes].sort();
+    const compoundKey = sortedAttrs.join("+");
+    const stat = this.compoundStats.get(compoundKey);
+    if (stat) {
+      stat.hasCompoundIndex = hasCompoundIndex;
+    }
+  }
   /**
    * Get all query statistics.
    *
@@ -6153,6 +6994,7 @@ var QueryPatternTracker = class {
    */
   clear() {
     this.stats.clear();
+    this.compoundStats.clear();
     this.queryCounter = 0;
   }
   /**
@@ -6161,9 +7003,10 @@ var QueryPatternTracker = class {
    * @returns Tracking overhead info
    */
   getTrackingInfo() {
-    const memoryEstimate = this.stats.size * 200;
+    const memoryEstimate = this.stats.size * 200 + this.compoundStats.size * 300;
     return {
       patternsTracked: this.stats.size,
+      compoundPatternsTracked: this.compoundStats.size,
       totalQueries: this.queryCounter,
       samplingRate: this.samplingRate,
       memoryEstimate
@@ -6196,6 +7039,33 @@ var QueryPatternTracker = class {
       }
     }
   }
+  /**
+   * Evict the oldest compound query entry (Phase 9.03).
+   */
+  evictOldestCompound() {
+    let oldestKey = null;
+    let oldestTime = Infinity;
+    for (const [key, stat] of this.compoundStats.entries()) {
+      if (stat.lastQueried < oldestTime) {
+        oldestTime = stat.lastQueried;
+        oldestKey = key;
+      }
+    }
+    if (oldestKey) {
+      this.compoundStats.delete(oldestKey);
+    }
+  }
+  /**
+   * Prune stale compound statistics (Phase 9.03).
+   */
+  pruneStaleCompound() {
+    const cutoff = Date.now() - this.statsTtl;
+    for (const [key, stat] of this.compoundStats.entries()) {
+      if (stat.lastQueried < cutoff) {
+        this.compoundStats.delete(key);
+      }
+    }
+  }
 };
 
 // src/query/adaptive/IndexAdvisor.ts
@@ -6229,6 +7099,12 @@ var IndexAdvisor = class {
         suggestions.push(suggestion);
       }
     }
+    const compoundSuggestions = this.getCompoundSuggestions({
+      minQueryCount,
+      minAverageCost,
+      excludeExistingIndexes
+    });
+    suggestions.push(...compoundSuggestions);
     suggestions.sort((a, b) => {
       const priorityOrder = { high: 3, medium: 2, low: 1 };
       const priorityDiff = priorityOrder[b.priority] - priorityOrder[a.priority];
@@ -6428,6 +7304,136 @@ var IndexAdvisor = class {
     }
     return reason;
   }
+  // ========================================
+  // Phase 9.03: Compound Index Suggestions
+  // ========================================
+  /**
+   * Get compound index suggestions based on AND query patterns.
+   *
+   * @param options - Suggestion options
+   * @returns Array of compound index suggestions
+   */
+  getCompoundSuggestions(options = {}) {
+    const {
+      minQueryCount = ADAPTIVE_INDEXING_DEFAULTS.advisor.minQueryCount,
+      minAverageCost = ADAPTIVE_INDEXING_DEFAULTS.advisor.minAverageCost,
+      excludeExistingIndexes = true
+    } = options;
+    const compoundStats = this.tracker.getCompoundStatistics();
+    const suggestions = [];
+    for (const stat of compoundStats) {
+      if (excludeExistingIndexes && stat.hasCompoundIndex) continue;
+      if (stat.queryCount < minQueryCount) continue;
+      if (stat.averageCost < minAverageCost) continue;
+      const suggestion = this.generateCompoundSuggestion(stat);
+      if (suggestion) {
+        suggestions.push(suggestion);
+      }
+    }
+    return suggestions;
+  }
+  /**
+   * 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) {
+    const stat = this.tracker.getCompoundStats(attributes);
+    if (!stat) return null;
+    return this.generateCompoundSuggestion(stat);
+  }
+  /**
+   * 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, threshold = ADAPTIVE_INDEXING_DEFAULTS.autoIndex.threshold) {
+    const stat = this.tracker.getCompoundStats(attributes);
+    if (!stat) return false;
+    return !stat.hasCompoundIndex && stat.queryCount >= threshold;
+  }
+  /**
+   * Generate a suggestion for a compound query pattern.
+   */
+  generateCompoundSuggestion(stat) {
+    const estimatedBenefit = this.estimateCompoundBenefit(stat);
+    const estimatedCost = this.estimateCompoundMemoryCost(stat);
+    const priority = this.calculateCompoundPriority(stat, estimatedBenefit);
+    return {
+      attribute: stat.compoundKey,
+      indexType: "compound",
+      reason: this.generateCompoundReason(stat, estimatedBenefit),
+      estimatedBenefit,
+      estimatedCost,
+      priority,
+      queryCount: stat.queryCount,
+      averageCost: stat.averageCost,
+      compoundAttributes: stat.attributes
+    };
+  }
+  /**
+   * 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
+   */
+  estimateCompoundBenefit(stat) {
+    const attributeMultiplier = Math.pow(2, stat.attributes.length - 1);
+    let baseBenefit;
+    if (stat.averageCost > 20) {
+      baseBenefit = 1e3;
+    } else if (stat.averageCost > 5) {
+      baseBenefit = 500;
+    } else if (stat.averageCost > 1) {
+      baseBenefit = 100;
+    } else {
+      baseBenefit = 50;
+    }
+    const frequencyMultiplier = Math.min(stat.queryCount / 10, 100);
+    return Math.floor(baseBenefit * attributeMultiplier * frequencyMultiplier);
+  }
+  /**
+   * Estimate memory cost of adding a compound index.
+   */
+  estimateCompoundMemoryCost(stat) {
+    const bytesPerRecord = MEMORY_OVERHEAD_ESTIMATES.compound;
+    const attributeOverhead = stat.attributes.length * 8;
+    const estimatedRecords = 1e3;
+    return Math.floor(estimatedRecords * (bytesPerRecord + attributeOverhead) * 1.5);
+  }
+  /**
+   * Calculate priority for compound index suggestion.
+   */
+  calculateCompoundPriority(stat, estimatedBenefit) {
+    if (stat.queryCount > 100 && stat.averageCost > 10) {
+      return "high";
+    }
+    if (stat.queryCount > 500) {
+      return "high";
+    }
+    if (stat.queryCount > 50 || stat.averageCost > 5) {
+      return "medium";
+    }
+    if (estimatedBenefit > 2e3) {
+      return "medium";
+    }
+    return "low";
+  }
+  /**
+   * Generate human-readable reason for compound index suggestion.
+   */
+  generateCompoundReason(stat, benefit) {
+    const costStr = stat.averageCost.toFixed(2);
+    const attrList = stat.attributes.join(", ");
+    let reason = `Compound AND query on [${attrList}] executed ${stat.queryCount}\xD7 with average cost ${costStr}ms. `;
+    reason += `Expected ~${benefit}\xD7 cumulative speedup with compound index. `;
+    reason += `Eliminates ${stat.attributes.length - 1} ResultSet intersection(s).`;
+    return reason;
+  }
 };
 
 // src/query/adaptive/AutoIndexManager.ts
@@ -6913,11 +7919,20 @@ var IndexedLWWMap = class extends LWWMap {
   // ==================== Index Management ====================
   /**
    * 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(attribute) {
+    if (this.options.lazyIndexBuilding) {
+      const index2 = new LazyHashIndex(attribute, {
+        onProgress: this.options.onIndexBuilding
+      });
+      this.indexRegistry.addIndex(index2);
+      this.buildIndex(index2);
+      return index2;
+    }
     const index = new HashIndex(attribute);
     this.indexRegistry.addIndex(index);
     this.buildIndex(index);
@@ -6926,12 +7941,21 @@ var IndexedLWWMap = class extends LWWMap {
   /**
    * 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(attribute, comparator) {
+    if (this.options.lazyIndexBuilding) {
+      const index2 = new LazyNavigableIndex(attribute, comparator, {
+        onProgress: this.options.onIndexBuilding
+      });
+      this.indexRegistry.addIndex(index2);
+      this.buildIndex(index2);
+      return index2;
+    }
     const index = new NavigableIndex(attribute, comparator);
     this.indexRegistry.addIndex(index);
     this.buildIndex(index);
@@ -6940,10 +7964,11 @@ var IndexedLWWMap = class extends LWWMap {
   /**
    * 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
@@ -6955,6 +7980,14 @@ var IndexedLWWMap = class extends LWWMap {
    * ```
    */
   addInvertedIndex(attribute, pipeline) {
+    if (this.options.lazyIndexBuilding) {
+      const index2 = new LazyInvertedIndex(attribute, pipeline, {
+        onProgress: this.options.onIndexBuilding
+      });
+      this.indexRegistry.addIndex(index2);
+      this.buildIndex(index2);
+      return index2;
+    }
     const index = new InvertedIndex(attribute, pipeline);
     this.indexRegistry.addIndex(index);
     this.buildIndex(index);
@@ -7459,6 +8492,58 @@ var IndexedLWWMap = class extends LWWMap {
   isAutoIndexingEnabled() {
     return this.autoIndexManager !== null;
   }
+  // ==================== Lazy Indexing (Phase 9.01) ====================
+  /**
+   * Check if lazy index building is enabled.
+   */
+  isLazyIndexingEnabled() {
+    return this.options.lazyIndexBuilding === true;
+  }
+  /**
+   * Force materialization of all lazy indexes.
+   * Useful to pre-warm indexes before critical operations.
+   *
+   * @param progressCallback - Optional progress callback
+   */
+  materializeAllIndexes(progressCallback) {
+    const callback = progressCallback ?? this.options.onIndexBuilding;
+    for (const index of this.indexRegistry.getAllIndexes()) {
+      if ("isLazy" in index && index.isLazy) {
+        const lazyIndex = index;
+        if (!lazyIndex.isBuilt) {
+          lazyIndex.materialize(callback);
+        }
+      }
+    }
+  }
+  /**
+   * Get count of pending records across all lazy indexes.
+   * Returns 0 if no lazy indexes or all are materialized.
+   */
+  getPendingIndexCount() {
+    let total = 0;
+    for (const index of this.indexRegistry.getAllIndexes()) {
+      if ("isLazy" in index && index.isLazy) {
+        const lazyIndex = index;
+        total += lazyIndex.pendingCount;
+      }
+    }
+    return total;
+  }
+  /**
+   * Check if any lazy indexes are still pending (not built).
+   */
+  hasUnbuiltIndexes() {
+    for (const index of this.indexRegistry.getAllIndexes()) {
+      if ("isLazy" in index && index.isLazy) {
+        const lazyIndex = index;
+        if (!lazyIndex.isBuilt) {
+          return true;
+        }
+      }
+    }
+    return false;
+  }
   /**
    * Track query pattern for adaptive indexing.
    */