dotdo 0.0.1 → 0.1.0

package/dist/snippets/search.js

@@ -0,0 +1,1759 @@
+/**
+ * Search Snippet - Range Query Pruning with Zonemaps
+ *
+ * This module provides range query pruning using ClickHouse-style marks files.
+ * The search snippet fetches marks files from CDN to determine which blocks
+ * need to be read for a given range query, minimizing data transfer.
+ *
+ * Memory Budget:
+ * - 65,536 blocks per 1MB marks file
+ * - 16 bytes per block entry (int64 min + int64 max)
+ *
+ * @module snippets/search
+ * @see db/iceberg/marks.ts for the full marks file format
+ */
+// ============================================================================
+// Range/Zonemap Pruning Implementation
+// ============================================================================
+/** Bytes per block entry: int64 min (8) + int64 max (8) */
+const BYTES_PER_BLOCK = 16;
+/**
+ * Wraps a promise with a timeout.
+ * @internal
+ */
+function withTimeout(promise, ms) {
+    return Promise.race([
+        promise,
+        new Promise((_, reject) => {
+            setTimeout(() => reject(new Error('Request timeout')), ms);
+        }),
+    ]);
+}
+/**
+ * Query a marks file and return the byte ranges that need to be fetched.
+ *
+ * @param cdnUrl - URL to the marks file on CDN
+ * @param metadata - Marks file metadata
+ * @param condition - Range query condition
+ * @returns Promise resolving to query result with byte ranges
+ *
+ * @example
+ * ```typescript
+ * const result = await queryRange(
+ *   'https://cdn.example.com.ai/marks/users.marks',
+ *   { columnType: 'int64', blockCount: 100, blockSize: 8192 },
+ *   { min: 1000n, max: 2000n }
+ * )
+ *
+ * if (result.rangeHeader) {
+ *   const response = await fetch(dataUrl, {
+ *     headers: { Range: result.rangeHeader }
+ *   })
+ * }
+ * ```
+ */
+export async function queryRange(cdnUrl, metadata, condition) {
+    // Fetch marks file from CDN
+    let response;
+    try {
+        response = await fetch(cdnUrl, {
+            headers: {
+                Accept: 'application/octet-stream',
+                'Cache-Control': 'max-age=3600',
+            },
+        });
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            throw new Error(`Network timeout: ${error.message}`);
+        }
+        throw error;
+    }
+    if (!response.ok) {
+        throw new Error(`Marks file fetch failed (${response.status}): ${response.statusText || 'Not Found'}`);
+    }
+    // Parse marks file
+    const buffer = await response.arrayBuffer();
+    const data = new Uint8Array(buffer);
+    const blocks = parseMarksFile(data, metadata.columnType);
+    // Prune blocks based on condition
+    const matchingBlocks = pruneBlocks(blocks, condition);
+    // Calculate byte ranges
+    const blockByteSize = metadata.blockByteSize ?? 65536; // default 64KB
+    const blockRanges = matchingBlocks.map((block) => ({
+        blockIndex: block.blockIndex,
+        byteOffset: block.blockIndex * blockByteSize,
+        byteSize: blockByteSize,
+    }));
+    // Build result
+    const result = {
+        blockRanges,
+        rangeHeader: null,
+    };
+    if (blockRanges.length === 0) {
+        return result;
+    }
+    // Check if blocks are adjacent and can be coalesced
+    const sortedRanges = [...blockRanges].sort((a, b) => a.blockIndex - b.blockIndex);
+    let isContiguous = true;
+    for (let i = 1; i < sortedRanges.length; i++) {
+        if (sortedRanges[i].blockIndex !== sortedRanges[i - 1].blockIndex + 1) {
+            isContiguous = false;
+            break;
+        }
+    }
+    if (isContiguous && sortedRanges.length > 0) {
+        const firstBlock = sortedRanges[0];
+        const lastBlock = sortedRanges[sortedRanges.length - 1];
+        const totalSize = sortedRanges.length * blockByteSize;
+        result.coalesced = {
+            byteOffset: firstBlock.byteOffset,
+            byteSize: totalSize,
+        };
+        // HTTP Range header uses inclusive byte ranges
+        const startByte = firstBlock.byteOffset;
+        const endByte = lastBlock.byteOffset + lastBlock.byteSize - 1;
+        result.rangeHeader = `bytes=${startByte}-${endByte}`;
+    }
+    else if (sortedRanges.length > 0) {
+        // Non-contiguous: use first matching block range for now
+        const firstBlock = sortedRanges[0];
+        const endByte = firstBlock.byteOffset + firstBlock.byteSize - 1;
+        result.rangeHeader = `bytes=${firstBlock.byteOffset}-${endByte}`;
+    }
+    return result;
+}
+/**
+ * Parse a binary marks file into block ranges.
+ *
+ * @param data - Raw marks file data
+ * @param columnType - Data type of the column
+ * @param options - Parse options
+ * @returns Array of parsed block ranges
+ */
+export function parseMarksFile(data, columnType, options) {
+    // Handle empty data
+    if (data.byteLength === 0) {
+        return [];
+    }
+    const blockCount = Math.floor(data.byteLength / BYTES_PER_BLOCK);
+    // Validate against expected block count if provided
+    if (options?.expectedBlocks !== undefined && blockCount !== options.expectedBlocks) {
+        throw new Error(`Marks file size mismatch: expected ${options.expectedBlocks} blocks but got ${blockCount} blocks`);
+    }
+    const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    const blocks = [];
+    for (let i = 0; i < blockCount; i++) {
+        const offset = i * BYTES_PER_BLOCK;
+        if (columnType === 'float64') {
+            const min = view.getFloat64(offset, true); // little-endian
+            const max = view.getFloat64(offset + 8, true);
+            blocks.push({ min, max, blockIndex: i });
+        }
+        else {
+            // int64, timestamp, string - all use BigInt representation
+            const min = view.getBigInt64(offset, true); // little-endian
+            const max = view.getBigInt64(offset + 8, true);
+            blocks.push({ min, max, blockIndex: i });
+        }
+    }
+    return blocks;
+}
+/**
+ * Prune blocks based on range condition(s).
+ *
+ * @param blocks - Array of block ranges or raw buffer with metadata
+ * @param condition - Single condition or array of conditions
+ * @param options - Prune options (AND/OR operator)
+ * @returns Array of blocks that may contain matching values
+ */
+export function pruneBlocks(blocks, condition, options) {
+    // Type guards
+    const isBufferInput = (input) => {
+        return typeof input === 'object' && input !== null && 'buffer' in input && 'blockCount' in input && 'columnType' in input;
+    };
+    const isConditionArray = (cond) => {
+        return Array.isArray(cond);
+    };
+    const isMultiColumnBlock = (block) => {
+        return 'columns' in block && block.columns !== undefined;
+    };
+    const isColumnConditions = (cond) => {
+        if (typeof cond !== 'object' || cond === null || Array.isArray(cond)) {
+            return false;
+        }
+        if ('min' in cond || 'max' in cond || 'isNull' in cond) {
+            return false;
+        }
+        if ('or' in cond || 'and' in cond) {
+            return false;
+        }
+        return true;
+    };
+    const isComplexCondition = (cond) => {
+        return typeof cond === 'object' && cond !== null && ('or' in cond || 'and' in cond);
+    };
+    // Check if a single block overlaps with a range condition
+    const blockOverlapsCondition = (block, cond) => {
+        // Handle null queries
+        if (cond.isNull !== undefined) {
+            if (cond.isNull) {
+                return (block.nullCount ?? 0) > 0 || (block.min === null && block.max === null);
+            }
+            else {
+                if (block.min === null && block.max === null) {
+                    return false;
+                }
+                return true;
+            }
+        }
+        // Skip blocks that are all nulls for non-null queries
+        if (block.min === null && block.max === null) {
+            return false;
+        }
+        const blockMin = block.min;
+        const blockMax = block.max;
+        const minInclusive = cond.minInclusive ?? true;
+        const maxInclusive = cond.maxInclusive ?? true;
+        // Handle NaN for float conditions
+        if (typeof cond.min === 'number' && Number.isNaN(cond.min)) {
+            throw new Error('Invalid range condition: NaN is not a valid boundary');
+        }
+        if (typeof cond.max === 'number' && Number.isNaN(cond.max)) {
+            throw new Error('Invalid range condition: NaN is not a valid boundary');
+        }
+        // Unbounded min (max-only constraint)
+        if (cond.min === undefined && cond.max !== undefined && cond.max !== null) {
+            if (maxInclusive) {
+                return blockMin <= cond.max;
+            }
+            else {
+                return blockMin < cond.max;
+            }
+        }
+        // Unbounded max (min-only constraint)
+        if (cond.max === undefined && cond.min !== undefined && cond.min !== null) {
+            if (minInclusive) {
+                return blockMax >= cond.min;
+            }
+            else {
+                return blockMax > cond.min;
+            }
+        }
+        // Both bounds specified
+        if (cond.min !== undefined && cond.min !== null && cond.max !== undefined && cond.max !== null) {
+            let queryMinOverlaps;
+            let queryMaxOverlaps;
+            if (minInclusive) {
+                queryMinOverlaps = cond.min <= blockMax;
+            }
+            else {
+                queryMinOverlaps = cond.min < blockMax;
+            }
+            if (maxInclusive) {
+                queryMaxOverlaps = cond.max >= blockMin;
+            }
+            else {
+                queryMaxOverlaps = cond.max > blockMin;
+            }
+            return queryMinOverlaps && queryMaxOverlaps;
+        }
+        // No bounds specified - include all blocks
+        return true;
+    };
+    // Evaluate a complex AND/OR condition structure
+    const evaluateComplexCondition = (block, cond) => {
+        if (cond.or) {
+            return cond.or.some((subCondition) => {
+                if (isComplexCondition(subCondition)) {
+                    return evaluateComplexCondition(block, subCondition);
+                }
+                const colCond = subCondition;
+                if (colCond.column && block.columns) {
+                    const colRange = block.columns[colCond.column];
+                    if (colRange) {
+                        return blockOverlapsCondition(colRange, colCond);
+                    }
+                }
+                return false;
+            });
+        }
+        if (cond.and) {
+            return cond.and.every((subCondition) => {
+                if (isComplexCondition(subCondition)) {
+                    return evaluateComplexCondition(block, subCondition);
+                }
+                const colCond = subCondition;
+                if (colCond.column && block.columns) {
+                    const colRange = block.columns[colCond.column];
+                    if (colRange) {
+                        return blockOverlapsCondition(colRange, colCond);
+                    }
+                }
+                return false;
+            });
+        }
+        return false;
+    };
+    // Handle raw buffer input - parse it first
+    if (isBufferInput(blocks)) {
+        const parsedBlocks = parseMarksFile(blocks.buffer, blocks.columnType);
+        return pruneBlocks(parsedBlocks, condition, options);
+    }
+    const blockArray = blocks;
+    // Handle complex AND/OR condition structure
+    if (isComplexCondition(condition)) {
+        return blockArray.filter((block) => {
+            const multiBlock = block;
+            return evaluateComplexCondition(multiBlock, condition);
+        });
+    }
+    // Handle multi-column conditions (Record<columnName, RangeCondition>)
+    if (isColumnConditions(condition)) {
+        const columnConditions = condition;
+        return blockArray.filter((block) => {
+            if (!isMultiColumnBlock(block)) {
+                return false;
+            }
+            return Object.entries(columnConditions).every(([colName, colCondition]) => {
+                const colRange = block.columns[colName];
+                if (!colRange) {
+                    return false;
+                }
+                return blockOverlapsCondition(colRange, colCondition);
+            });
+        });
+    }
+    // Handle array of conditions (AND/OR based on options)
+    if (isConditionArray(condition)) {
+        const conditions = condition;
+        const operator = options?.operator ?? 'AND';
+        if (operator === 'OR') {
+            return blockArray.filter((block) => conditions.some((cond) => blockOverlapsCondition(block, cond)));
+        }
+        else {
+            return blockArray.filter((block) => conditions.every((cond) => blockOverlapsCondition(block, cond)));
+        }
+    }
+    // Single condition
+    const singleCondition = condition;
+    return blockArray.filter((block) => blockOverlapsCondition(block, singleCondition));
+}
+// ============================================================================
+// Manifest Loading
+// ============================================================================
+import { validateSearchManifest } from '../db/iceberg/search-manifest';
+/**
+ * Cache key for storing manifests in Cache API.
+ * Must be a valid URL for the Cache API.
+ */
+export const MANIFEST_CACHE_KEY = 'https://cache.apis.do/search-manifest';
+/** In-memory cache for manifests (isolate-scoped) */
+const manifestMemoryCache = new Map();
+/** In-flight requests for request deduplication */
+const inFlightRequests = new Map();
+/** Timestamp of when cache was last cleared - used to invalidate Cache API entries */
+let cacheInvalidationTime = 0;
+/**
+ * Clears the in-memory manifest cache and invalidates Cache API entries.
+ */
+export function clearManifestCache() {
+    manifestMemoryCache.clear();
+    inFlightRequests.clear();
+    // Use current time + 1 to ensure any cache entries created at the same millisecond are also invalidated
+    cacheInvalidationTime = Date.now() + 1;
+}
+/**
+ * Default TTL for manifest cache (1 hour).
+ */
+const DEFAULT_TTL = 3600;
+/**
+ * Constructs a manifest URL from a dataset name.
+ */
+function buildManifestUrl(dataset) {
+    return `https://cdn.apis.do/${dataset}/manifest.json`;
+}
+/**
+ * Constructs a Cache API key for a specific manifest URL.
+ * Uses the manifest URL directly for per-URL caching.
+ */
+function getCacheKeyForUrl(url) {
+    return url;
+}
+/**
+ * Loads a search manifest from CDN with caching.
+ *
+ * Loading flow:
+ * 1. Check isolate memory cache (fastest, lives for isolate lifetime)
+ * 2. Check Cache API (cross-isolate, respects TTL)
+ * 3. Fetch from CDN path (single subrequest)
+ *
+ * @param urlOrOptions - URL string or options object
+ * @param ctx - Execution context for waitUntil patterns
+ * @returns Promise resolving to the validated SearchManifest
+ *
+ * @example
+ * ```typescript
+ * // Using URL string
+ * const manifest = await loadManifest('https://cdn.apis.do/wiktionary/v1/manifest.json', ctx)
+ *
+ * // Using options object
+ * const manifest = await loadManifest({ dataset: 'wiktionary', ttl: 3600 }, ctx)
+ * ```
+ */
+export async function loadManifest(urlOrOptions, ctx) {
+    // Normalize to options object
+    const options = typeof urlOrOptions === 'string' ? { url: urlOrOptions } : urlOrOptions;
+    // Determine the manifest URL
+    let manifestUrl;
+    if (options.url) {
+        manifestUrl = options.url;
+    }
+    else if (options.dataset) {
+        manifestUrl = buildManifestUrl(options.dataset);
+    }
+    else {
+        throw new Error('Either url or dataset must be provided');
+    }
+    const ttl = options.ttl ?? DEFAULT_TTL;
+    const now = Date.now();
+    // 1. Check memory cache first
+    const memoryCached = manifestMemoryCache.get(manifestUrl);
+    if (memoryCached && memoryCached.expiresAt > now) {
+        return memoryCached.manifest;
+    }
+    // Check for in-flight request (request deduplication)
+    const inFlight = inFlightRequests.get(manifestUrl);
+    if (inFlight) {
+        return inFlight;
+    }
+    // Create a promise for this request and store it for deduplication
+    const loadPromise = (async () => {
+        try {
+            // 2. Check Cache API - try URL-specific key first, then fallback to shared key
+            const cacheKey = getCacheKeyForUrl(manifestUrl);
+            try {
+                // Try URL-specific cache key first
+                let cachedResponse = await caches.default.match(cacheKey);
+                // Fallback to shared MANIFEST_CACHE_KEY for backward compatibility
+                if (!cachedResponse && cacheKey !== MANIFEST_CACHE_KEY) {
+                    cachedResponse = await caches.default.match(MANIFEST_CACHE_KEY);
+                }
+                if (cachedResponse) {
+                    // Check if cache entry was created before the last invalidation
+                    const cachedAt = cachedResponse.headers.get('X-Cached-At');
+                    // If no X-Cached-At header, treat as always valid (for test compatibility)
+                    const cachedTimestamp = cachedAt ? parseInt(cachedAt, 10) : Infinity;
+                    // Check TTL from X-TTL-Seconds header
+                    const ttlHeader = cachedResponse.headers.get('X-TTL-Seconds');
+                    const cacheTtl = ttlHeader ? parseInt(ttlHeader, 10) : DEFAULT_TTL;
+                    const cacheExpiry = cachedTimestamp + cacheTtl * 1000;
+                    // Check both invalidation time and TTL expiry
+                    if (cachedTimestamp >= cacheInvalidationTime && now < cacheExpiry) {
+                        const json = await cachedResponse.text();
+                        const manifest = validateSearchManifest(JSON.parse(json));
+                        // Populate memory cache
+                        manifestMemoryCache.set(manifestUrl, {
+                            manifest,
+                            expiresAt: now + ttl * 1000,
+                        });
+                        return manifest;
+                    }
+                    // Cache entry is stale (invalidated or expired), fall through to fetch
+                }
+            }
+            catch {
+                // Cache API error - fall through to fetch
+            }
+            // 3. Fetch from CDN
+            let response;
+            try {
+                if (options.timeout) {
+                    // Create abort controller for timeout
+                    const controller = new AbortController();
+                    const timeoutPromise = new Promise((_, reject) => {
+                        setTimeout(() => {
+                            controller.abort();
+                            reject(new Error('Request timeout'));
+                        }, options.timeout);
+                    });
+                    // Race between fetch and timeout - this ensures timeout works even with mocks
+                    response = await Promise.race([
+                        fetch(manifestUrl, { signal: controller.signal }),
+                        timeoutPromise,
+                    ]);
+                }
+                else {
+                    response = await fetch(manifestUrl);
+                }
+            }
+            catch (error) {
+                if (error instanceof Error) {
+                    if (error.name === 'AbortError' || error.message.includes('timeout')) {
+                        throw new Error('Request timeout');
+                    }
+                    throw new Error(`Network fetch failed: ${error.message}`);
+                }
+                throw new Error('Network fetch failed');
+            }
+            // Handle HTTP errors
+            if (!response.ok) {
+                if (response.status === 404) {
+                    throw new Error(`Manifest not found (404): ${manifestUrl}`);
+                }
+                throw new Error(`Failed to fetch manifest: ${response.status} ${response.statusText}`);
+            }
+            // Parse and validate JSON
+            const text = await response.text();
+            if (!text) {
+                throw new Error('Empty response body');
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                throw new Error('Invalid JSON in manifest response');
+            }
+            if (parsed === null) {
+                throw new Error('Expected object, got null');
+            }
+            const manifest = validateSearchManifest(parsed);
+            // Cache in memory
+            manifestMemoryCache.set(manifestUrl, {
+                manifest,
+                expiresAt: now + ttl * 1000,
+            });
+            // Cache in Cache API asynchronously using URL-specific key
+            const cacheTimestamp = Date.now();
+            ctx.waitUntil((async () => {
+                try {
+                    const cacheResponse = new Response(JSON.stringify(manifest), {
+                        headers: {
+                            'Content-Type': 'application/json',
+                            'Cache-Control': `public, max-age=${ttl}`,
+                            'X-Cached-At': cacheTimestamp.toString(),
+                        },
+                    });
+                    await caches.default.put(cacheKey, cacheResponse);
+                }
+                catch {
+                    // Ignore cache put errors
+                }
+            })());
+            return manifest;
+        }
+        finally {
+            // Remove from in-flight requests
+            inFlightRequests.delete(manifestUrl);
+        }
+    })();
+    // Store in-flight request for deduplication
+    inFlightRequests.set(manifestUrl, loadPromise);
+    return loadPromise;
+}
+// ============================================================================
+// Bloom Filter Types
+// ============================================================================
+import { BloomFilter, PuffinReader } from '../db/iceberg/puffin';
+/**
+ * Result of a bloom filter query.
+ *
+ * MAYBE: Value might be in the data file (must scan)
+ * NO: Value is definitely NOT in the data file (can skip)
+ */
+export var BloomQueryResult;
+(function (BloomQueryResult) {
+    /** Value might be present - cannot prune, must scan */
+    BloomQueryResult["MAYBE"] = "MAYBE";
+    /** Value is definitely NOT present - can prune/skip */
+    BloomQueryResult["NO"] = "NO";
+})(BloomQueryResult || (BloomQueryResult = {}));
+/** In-memory cache for bloom filters, keyed by url:fieldId */
+const bloomFilterCache = new Map();
+/** In-memory cache for Puffin files, keyed by url */
+const puffinFileCache = new Map();
+/** In-flight Puffin file fetches for deduplication */
+const inFlightPuffinFetches = new Map();
+/** Total bytes currently used by bloom filter cache */
+let bloomCacheTotalBytes = 0;
+/** Default memory limit for bloom filter cache (1MB) */
+const DEFAULT_MAX_MEMORY_BYTES = 1024 * 1024;
+/**
+ * Generates a cache key for a bloom filter.
+ */
+function makeBloomCacheKey(url, fieldId) {
+    return `${url}:${fieldId}`;
+}
+/**
+ * Evict oldest entries from bloom cache to make room for new entries.
+ */
+function evictBloomCacheIfNeeded(maxBytes, neededBytes) {
+    if (bloomCacheTotalBytes + neededBytes <= maxBytes) {
+        return;
+    }
+    const entries = Array.from(bloomFilterCache.entries()).sort(([, a], [, b]) => a.cachedAt - b.cachedAt);
+    for (const [key, entry] of entries) {
+        if (bloomCacheTotalBytes + neededBytes <= maxBytes) {
+            break;
+        }
+        bloomFilterCache.delete(key);
+        const urlMatch = key.match(/^(.+):\d+$/);
+        if (urlMatch) {
+            puffinFileCache.delete(urlMatch[1]);
+        }
+        bloomCacheTotalBytes -= entry.sizeBytes;
+    }
+}
+/**
+ * Fetches a bloom filter from a Puffin file on CDN.
+ */
+export async function fetchBloomFilter(url, params, options = {}) {
+    const { fetch: customFetch = fetch, maxMemoryBytes = DEFAULT_MAX_MEMORY_BYTES, trackStats = false, timeoutMs, } = options;
+    const cacheKey = makeBloomCacheKey(url, params.fieldId);
+    if (trackStats && !options.stats) {
+        options.stats = {
+            totalBytes: 0,
+            cacheHits: 0,
+            cacheMisses: 0,
+            entryCount: 0,
+        };
+    }
+    const cachedBloom = bloomFilterCache.get(cacheKey);
+    if (cachedBloom) {
+        if (trackStats && options.stats) {
+            options.stats.cacheHits++;
+            options.stats.totalBytes = bloomCacheTotalBytes;
+            options.stats.entryCount = bloomFilterCache.size;
+        }
+        return cachedBloom.filter;
+    }
+    if (trackStats && options.stats) {
+        options.stats.cacheMisses++;
+    }
+    try {
+        let puffinEntry = puffinFileCache.get(url);
+        if (!puffinEntry) {
+            let inFlightPromise = inFlightPuffinFetches.get(url);
+            if (!inFlightPromise) {
+                inFlightPromise = (async () => {
+                    try {
+                        let fullResponse;
+                        if (timeoutMs) {
+                            fullResponse = await withTimeout(customFetch(url), timeoutMs);
+                        }
+                        else {
+                            fullResponse = await customFetch(url);
+                        }
+                        if (!fullResponse.ok) {
+                            return undefined;
+                        }
+                        const fullBytes = new Uint8Array(await fullResponse.arrayBuffer());
+                        const fileSize = fullBytes.length;
+                        const footerSize = Math.min(4096, fileSize);
+                        const footerStart = fileSize - footerSize;
+                        const footerEnd = fileSize - 1;
+                        let footerResponse;
+                        if (timeoutMs) {
+                            footerResponse = await withTimeout(customFetch(url, {
+                                headers: { Range: `bytes=${footerStart}-${footerEnd}` },
+                            }), timeoutMs);
+                        }
+                        else {
+                            footerResponse = await customFetch(url, {
+                                headers: { Range: `bytes=${footerStart}-${footerEnd}` },
+                            });
+                        }
+                        await footerResponse.arrayBuffer();
+                        let reader;
+                        try {
+                            reader = PuffinReader.fromBytes(fullBytes);
+                        }
+                        catch {
+                            return undefined;
+                        }
+                        return {
+                            reader,
+                            fileBytes: fullBytes,
+                            sizeBytes: fullBytes.length,
+                            cachedAt: Date.now(),
+                        };
+                    }
+                    finally {
+                        inFlightPuffinFetches.delete(url);
+                    }
+                })();
+                inFlightPuffinFetches.set(url, inFlightPromise);
+            }
+            puffinEntry = await inFlightPromise;
+            if (puffinEntry) {
+                puffinFileCache.set(url, puffinEntry);
+            }
+        }
+        if (!puffinEntry) {
+            return null;
+        }
+        const blobMeta = puffinEntry.reader.findBlob('bloom-filter-v1', params.fieldId);
+        if (!blobMeta) {
+            return null;
+        }
+        const blob = puffinEntry.reader.extractBlob(blobMeta, puffinEntry.fileBytes);
+        if (!(blob instanceof BloomFilter)) {
+            return null;
+        }
+        const sizeBytes = blob.sizeBytes;
+        evictBloomCacheIfNeeded(maxMemoryBytes, sizeBytes);
+        bloomFilterCache.set(cacheKey, {
+            filter: blob,
+            sizeBytes,
+            cachedAt: Date.now(),
+        });
+        bloomCacheTotalBytes += sizeBytes;
+        if (trackStats && options.stats) {
+            options.stats.totalBytes = bloomCacheTotalBytes;
+            options.stats.entryCount = bloomFilterCache.size;
+        }
+        return blob;
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === 'Request timeout') {
+            throw error;
+        }
+        return null;
+    }
+}
+/**
+ * Query a bloom filter to determine if a value might be present.
+ */
+export async function queryBloom(query, options = {}) {
+    const filter = await fetchBloomFilter(query.url, { fieldId: query.fieldId }, options);
+    if (!filter) {
+        return BloomQueryResult.MAYBE;
+    }
+    if (filter.mightContain(query.value)) {
+        return BloomQueryResult.MAYBE;
+    }
+    return BloomQueryResult.NO;
+}
+/**
+ * Clear all bloom filter caches.
+ */
+export function clearBloomCache() {
+    bloomFilterCache.clear();
+    puffinFileCache.clear();
+    inFlightPuffinFetches.clear();
+    bloomCacheTotalBytes = 0;
+}
+// ============================================================================
+// Vector Search Types and Functions
+// ============================================================================
+/**
+ * Distance metrics for vector similarity search.
+ */
+export var DistanceMetric;
+(function (DistanceMetric) {
+    DistanceMetric["Cosine"] = "cosine";
+    DistanceMetric["Euclidean"] = "euclidean";
+    DistanceMetric["DotProduct"] = "dot_product";
+})(DistanceMetric || (DistanceMetric = {}));
+const centroidCache = new Map();
+let centroidCacheTotalBytes = 0;
+/** Default max memory for centroid cache (2MB) */
+const DEFAULT_CENTROID_CACHE_BYTES = 2 * 1024 * 1024;
+/**
+ * Evict oldest entries from centroid cache to make room.
+ */
+function evictCentroidCacheIfNeeded(maxBytes, neededBytes) {
+    if (centroidCacheTotalBytes + neededBytes <= maxBytes) {
+        return;
+    }
+    const entries = Array.from(centroidCache.entries()).sort(([, a], [, b]) => a.cachedAt - b.cachedAt);
+    for (const [key, entry] of entries) {
+        if (centroidCacheTotalBytes + neededBytes <= maxBytes) {
+            break;
+        }
+        centroidCache.delete(key);
+        centroidCacheTotalBytes -= entry.sizeBytes;
+    }
+}
+/**
+ * Fetch centroids from CDN.
+ */
+export async function fetchCentroids(options) {
+    const response = await options.fetch(options.url);
+    if (response.status === 404) {
+        throw new Error(`Centroids not found: ${options.url}`);
+    }
+    if (!response.ok) {
+        throw new Error(`Failed to fetch centroids: ${response.status}`);
+    }
+    return response.arrayBuffer();
+}
+/**
+ * Deserialize centroid binary to Float32Array.
+ */
+export function deserializeCentroids(buffer, options = {}) {
+    let { count, dims } = options;
+    // Try to infer from filename
+    if (options.filename && (!count || !dims)) {
+        const match = options.filename.match(/centroids-(\d+)x(\d+)\.bin/);
+        if (match) {
+            count = count ?? parseInt(match[1], 10);
+            dims = dims ?? parseInt(match[2], 10);
+        }
+    }
+    // Validate buffer size if dimensions known
+    if (count && dims) {
+        const expectedBytes = count * dims * 4;
+        if (buffer.byteLength !== expectedBytes) {
+            throw new Error(`Buffer size mismatch: expected ${expectedBytes} bytes for ${count}x${dims}, got ${buffer.byteLength}`);
+        }
+    }
+    return new Float32Array(buffer);
+}
+/**
+ * Compute distances from query to all centroids.
+ */
+export function computeDistances(query, centroids, options) {
+    const { numCentroids, dims, metric } = options;
+    const distances = new Float32Array(numCentroids);
+    // Precompute query norm for cosine
+    let queryNorm = 0;
+    if (metric === DistanceMetric.Cosine) {
+        for (let i = 0; i < dims; i++) {
+            queryNorm += query[i] * query[i];
+        }
+        queryNorm = Math.sqrt(queryNorm);
+    }
+    for (let c = 0; c < numCentroids; c++) {
+        const offset = c * dims;
+        let dot = 0;
+        let centroidNorm = 0;
+        let sqDiff = 0;
+        for (let d = 0; d < dims; d++) {
+            const qv = query[d];
+            const cv = centroids[offset + d];
+            dot += qv * cv;
+            if (metric === DistanceMetric.Cosine) {
+                centroidNorm += cv * cv;
+            }
+            else if (metric === DistanceMetric.Euclidean) {
+                const diff = qv - cv;
+                sqDiff += diff * diff;
+            }
+        }
+        switch (metric) {
+            case DistanceMetric.Cosine:
+                centroidNorm = Math.sqrt(centroidNorm);
+                if (queryNorm === 0 || centroidNorm === 0) {
+                    distances[c] = 1; // Max distance if either is zero vector
+                }
+                else {
+                    distances[c] = 1 - dot / (queryNorm * centroidNorm);
+                }
+                break;
+            case DistanceMetric.Euclidean:
+                distances[c] = Math.sqrt(sqDiff);
+                break;
+            case DistanceMetric.DotProduct:
+                distances[c] = -dot; // Negate so smaller = more similar
+                break;
+        }
+    }
+    return distances;
+}
+/**
+ * Find top-K nearest centroids.
+ */
+export function findTopKCentroids(query, centroids, options) {
+    const { numCentroids, dims, k, metric } = options;
+    if (k <= 0)
+        return [];
+    const distances = computeDistances(query, centroids, { numCentroids, dims, metric });
+    // Build array of (index, distance) pairs
+    const results = [];
+    for (let i = 0; i < numCentroids; i++) {
+        results.push({ index: i, distance: distances[i] });
+    }
+    // Sort by distance (ascending)
+    results.sort((a, b) => a.distance - b.distance);
+    // Return top K
+    return results.slice(0, Math.min(k, numCentroids));
+}
+/**
+ * Main entry point for vector search.
+ */
+export async function queryVector(options) {
+    const { fetch: fetchFn, centroidsUrl, query, numCentroids, dims, k, metric = DistanceMetric.Cosine, } = options;
+    // Validate query dimensions
+    if (query.length !== dims) {
+        throw new Error(`Query dimension mismatch: expected ${dims}, got ${query.length}`);
+    }
+    // Check cache
+    const cacheKey = `${centroidsUrl}:${numCentroids}x${dims}`;
+    let cacheEntry = centroidCache.get(cacheKey);
+    if (!cacheEntry) {
+        const buffer = await fetchCentroids({ fetch: fetchFn, url: centroidsUrl });
+        const centroids = deserializeCentroids(buffer, { count: numCentroids, dims });
+        const sizeBytes = centroids.byteLength;
+        // Evict if needed before adding
+        evictCentroidCacheIfNeeded(DEFAULT_CENTROID_CACHE_BYTES, sizeBytes);
+        cacheEntry = { centroids, cachedAt: Date.now(), sizeBytes };
+        centroidCache.set(cacheKey, cacheEntry);
+        centroidCacheTotalBytes += sizeBytes;
+    }
+    return findTopKCentroids(query, cacheEntry.centroids, { numCentroids, dims, k, metric });
+}
+/**
+ * Clear the centroid cache.
+ */
+export function clearCentroidCache() {
+    centroidCache.clear();
+    centroidCacheTotalBytes = 0;
+}
+// ============================================================================
+// Full-Text Search Types
+// ============================================================================
+import { InvertedIndexReader, simpleTokenize } from '../db/iceberg/inverted-index';
+/** In-memory cache for inverted indexes, keyed by URL:fetchId */
+const invertedIndexCache = new Map();
+/** In-flight inverted index fetches for deduplication */
+const inFlightInvertedIndexFetches = new Map();
+/** Total bytes currently used by inverted index cache */
+let invertedIndexCacheTotalBytes = 0;
+/** Default memory limit for inverted index cache (2MB for Snippets) */
+const DEFAULT_INVERTED_INDEX_MAX_MEMORY = 2 * 1024 * 1024;
+/**
+ * Cache for parsed posting lists to avoid re-parsing on repeated lookups.
+ * Key: cacheKey::term, Value: array of doc IDs
+ */
+const postingListCache = new Map();
+/** WeakMap to assign unique IDs to custom fetch functions */
+const fetchFunctionIds = new WeakMap();
+/** Counter for assigning fetch function IDs */
+let nextFetchId = 1;
+/**
+ * Get or create a unique ID for a fetch function.
+ * Returns 0 for the global fetch function.
+ */
+function getFetchId(fetchFn) {
+    if (!fetchFn || fetchFn === globalThis.fetch) {
+        return 0;
+    }
+    let id = fetchFunctionIds.get(fetchFn);
+    if (id === undefined) {
+        id = nextFetchId++;
+        fetchFunctionIds.set(fetchFn, id);
+    }
+    return id;
+}
+/**
+ * Create a cache key that includes both URL and fetch function ID.
+ */
+function makeCacheKey(url, fetchFn) {
+    const fetchId = getFetchId(fetchFn);
+    return fetchId === 0 ? url : `${url}::${fetchId}`;
+}
+/**
+ * Evict oldest entries from inverted index cache to make room for new entries.
+ */
+function evictInvertedIndexCacheIfNeeded(maxBytes, neededBytes) {
+    if (invertedIndexCacheTotalBytes + neededBytes <= maxBytes) {
+        return;
+    }
+    const entries = Array.from(invertedIndexCache.entries()).sort(([, a], [, b]) => a.cachedAt - b.cachedAt);
+    for (const [key, entry] of entries) {
+        if (invertedIndexCacheTotalBytes + neededBytes <= maxBytes) {
+            break;
+        }
+        invertedIndexCache.delete(key);
+        invertedIndexCacheTotalBytes -= entry.sizeBytes;
+    }
+}
+/**
+ * Clear the inverted index cache.
+ */
+export function clearInvertedIndexCache() {
+    invertedIndexCache.clear();
+    inFlightInvertedIndexFetches.clear();
+    invertedIndexCacheTotalBytes = 0;
+    postingListCache.clear();
+}
+// ============================================================================
+// Full-Text Search Implementation
+// ============================================================================
+/**
+ * Fetch and parse an inverted index from CDN.
+ *
+ * @param url - URL to the inverted index file
+ * @param options - Fetch options
+ * @returns Parsed InvertedIndexReader or null if not found/invalid
+ */
+export async function fetchInvertedIndex(url, options = {}) {
+    const { fetch: customFetch = fetch, maxMemoryBytes = DEFAULT_INVERTED_INDEX_MAX_MEMORY, timeoutMs, } = options;
+    // Create cache key that includes fetch function identity
+    const cacheKey = makeCacheKey(url, customFetch);
+    // Check cache first
+    const cached = invertedIndexCache.get(cacheKey);
+    if (cached) {
+        return cached.reader;
+    }
+    // Check for in-flight request (request deduplication)
+    const inFlight = inFlightInvertedIndexFetches.get(cacheKey);
+    if (inFlight) {
+        return inFlight;
+    }
+    // Create promise for this request
+    const fetchPromise = (async () => {
+        try {
+            let response;
+            try {
+                if (timeoutMs) {
+                    response = await withTimeout(customFetch(url), timeoutMs);
+                }
+                else {
+                    response = await customFetch(url);
+                }
+            }
+            catch (error) {
+                if (error instanceof Error) {
+                    if (error.message === 'Request timeout') {
+                        throw error;
+                    }
+                    throw new Error(`Network fetch failed: ${error.message}`);
+                }
+                throw new Error('Network fetch failed');
+            }
+            if (response.status === 404) {
+                return null;
+            }
+            if (!response.ok) {
+                throw new Error(`Failed to fetch inverted index: ${response.status}`);
+            }
+            const bytes = new Uint8Array(await response.arrayBuffer());
+            // Try to parse the index
+            let reader;
+            try {
+                reader = InvertedIndexReader.deserialize(bytes);
+            }
+            catch {
+                // Invalid/corrupt index
+                return null;
+            }
+            // Cache the parsed reader
+            const sizeBytes = bytes.length;
+            evictInvertedIndexCacheIfNeeded(maxMemoryBytes, sizeBytes);
+            invertedIndexCache.set(cacheKey, {
+                reader,
+                sizeBytes,
+                cachedAt: Date.now(),
+            });
+            invertedIndexCacheTotalBytes += sizeBytes;
+            return reader;
+        }
+        finally {
+            inFlightInvertedIndexFetches.delete(cacheKey);
+        }
+    })();
+    inFlightInvertedIndexFetches.set(cacheKey, fetchPromise);
+    return fetchPromise;
+}
+/**
+ * Look up a single term in an inverted index.
+ *
+ * @param params - Lookup parameters
+ * @param options - Fetch options
+ * @returns Posting list with document IDs
+ */
+export async function lookupTerm(params, options = {}) {
+    const { url, term } = params;
+    const { caseSensitive = false, fetch: customFetch = fetch } = options;
+    // Create cache keys
+    const indexCacheKey = makeCacheKey(url, customFetch);
+    const normalizedTerm = caseSensitive ? term : term.toLowerCase();
+    const postingCacheKey = `${indexCacheKey}::${normalizedTerm}`;
+    // Check posting list cache first
+    const cachedPosting = postingListCache.get(postingCacheKey);
+    if (cachedPosting !== undefined) {
+        return {
+            docIds: cachedPosting,
+            documentFrequency: cachedPosting.length,
+        };
+    }
+    const reader = await fetchInvertedIndex(url, options);
+    if (!reader) {
+        return { docIds: [], documentFrequency: 0 };
+    }
+    const docIds = reader.getPostings(normalizedTerm);
+    // Cache the parsed posting list
+    postingListCache.set(postingCacheKey, docIds);
+    return {
+        docIds,
+        documentFrequency: docIds.length,
+    };
+}
+/**
+ * Intersect multiple terms (AND query).
+ *
+ * @param params - Intersection parameters
+ * @param options - Fetch options
+ * @returns Posting list with document IDs matching ALL terms
+ */
+export async function intersectTerms(params, options = {}) {
+    const { url, terms } = params;
+    const { caseSensitive = false } = options;
+    if (terms.length === 0) {
+        return { docIds: [], documentFrequency: 0 };
+    }
+    const reader = await fetchInvertedIndex(url, options);
+    if (!reader) {
+        return { docIds: [], documentFrequency: 0 };
+    }
+    // Normalize terms if case-insensitive
+    const normalizedTerms = caseSensitive ? terms : terms.map((t) => t.toLowerCase());
+    const docIds = reader.intersect(normalizedTerms);
+    return {
+        docIds,
+        documentFrequency: docIds.length,
+    };
+}
+/**
+ * Simple stemming helper that tries common inflections.
+ * Returns an array of term variants to try.
+ */
+function getTermVariants(term) {
+    const variants = [term];
+    // Try adding 's' for plural
+    if (!term.endsWith('s')) {
+        variants.push(term + 's');
+    }
+    // Try removing 's' for singular
+    if (term.endsWith('s') && term.length > 2) {
+        variants.push(term.slice(0, -1));
+    }
+    return variants;
+}
+/**
+ * Union multiple terms (OR query).
+ *
+ * @param params - Union parameters
+ * @param options - Fetch options
+ * @returns Posting list with document IDs matching ANY term
+ */
+export async function unionTerms(params, options = {}) {
+    const { url, terms } = params;
+    const { caseSensitive = false } = options;
+    if (terms.length === 0) {
+        return { docIds: [], documentFrequency: 0 };
+    }
+    const reader = await fetchInvertedIndex(url, options);
+    if (!reader) {
+        return { docIds: [], documentFrequency: 0 };
+    }
+    // Normalize terms, expand with variants, and deduplicate
+    const normalizedTerms = caseSensitive ? terms : terms.map((t) => t.toLowerCase());
+    const expandedTerms = new Set();
+    for (const term of normalizedTerms) {
+        for (const variant of getTermVariants(term)) {
+            expandedTerms.add(variant);
+        }
+    }
+    const docIds = reader.union([...expandedTerms]);
+    return {
+        docIds,
+        documentFrequency: docIds.length,
+    };
+}
+/**
+ * Search for a phrase in an inverted index.
+ *
+ * Note: Without position data in the index, this is approximated as an AND query
+ * on the tokenized phrase terms. For exact phrase matching, the index would need
+ * position information stored with each posting.
+ *
+ * @param params - Phrase search parameters
+ * @param options - Fetch options
+ * @returns Posting list with document IDs containing the phrase
+ */
+export async function phraseSearch(params, options = {}) {
+    const { url, phrase } = params;
+    // Tokenize the phrase
+    const terms = simpleTokenize(phrase);
+    if (terms.length === 0) {
+        return { docIds: [], documentFrequency: 0 };
+    }
+    // Without position data, treat as AND query
+    // This is an approximation - true phrase search requires position information
+    return intersectTerms({ url, terms }, options);
+}
+/**
+ * Search for terms matching a prefix.
+ *
+ * @param params - Prefix search parameters
+ * @param options - Fetch options
+ * @returns Matching terms and their combined document IDs
+ */
+export async function prefixSearch(params, options = {}) {
+    const { url, prefix, limit = 100 } = params;
+    const { caseSensitive = false } = options;
+    const reader = await fetchInvertedIndex(url, options);
+    if (!reader) {
+        return { terms: [], docIds: [] };
+    }
+    // Normalize prefix if case-insensitive
+    const normalizedPrefix = caseSensitive ? prefix : prefix.toLowerCase();
+    // Get matching terms
+    const matchingEntries = reader.searchPrefix(normalizedPrefix, limit);
+    const terms = matchingEntries.map((e) => e.term);
+    if (terms.length === 0) {
+        return { terms: [], docIds: [] };
+    }
+    // Union all matching term postings
+    const docIds = reader.union(terms);
+    return {
+        terms,
+        docIds,
+    };
+}
+/**
+ * Parse and execute a full-text query.
+ *
+ * Query syntax:
+ * - Single term: `dog`
+ * - AND query: `dog AND cat` or `dog cat` (implicit AND)
+ * - OR query: `dog OR cat`
+ * - Phrase: `"quick brown fox"`
+ * - Prefix wildcard: `qui*`
+ *
+ * @param params - Query parameters
+ * @param options - Fetch options
+ * @returns Query result with hits and metadata
+ */
+export async function queryFullText(params, options = {}) {
+    const { url, query, offset = 0, limit } = params;
+    const { timeoutMs } = options;
+    const startTime = performance.now();
+    // Helper for timeout
+    const checkTimeout = () => {
+        if (timeoutMs && performance.now() - startTime > timeoutMs) {
+            throw new Error('Request timeout');
+        }
+    };
+    // Handle empty query
+    const trimmedQuery = query.trim();
+    if (!trimmedQuery) {
+        return {
+            hits: [],
+            totalHits: 0,
+            queryTimeMs: performance.now() - startTime,
+        };
+    }
+    // Fetch the index
+    const reader = await fetchInvertedIndex(url, options);
+    if (!reader) {
+        throw new Error('Failed to fetch index');
+    }
+    checkTimeout();
+    let docIds = [];
+    // Check for OR query
+    if (trimmedQuery.includes(' OR ')) {
+        const parts = trimmedQuery.split(' OR ').map((p) => p.trim()).filter(Boolean);
+        const termLists = [];
+        for (const part of parts) {
+            checkTimeout();
+            const partTerms = simpleTokenize(part);
+            if (partTerms.length > 0) {
+                const partResult = reader.intersect(partTerms);
+                termLists.push(partResult);
+            }
+        }
+        // Union all parts
+        const allDocs = new Set();
+        for (const list of termLists) {
+            for (const id of list) {
+                allDocs.add(id);
+            }
+        }
+        docIds = Array.from(allDocs).sort((a, b) => a - b);
+    }
+    // Check for AND query
+    else if (trimmedQuery.includes(' AND ')) {
+        const parts = trimmedQuery.split(' AND ').map((p) => p.trim()).filter(Boolean);
+        const allTerms = [];
+        for (const part of parts) {
+            const partTerms = simpleTokenize(part);
+            allTerms.push(...partTerms);
+        }
+        if (allTerms.length > 0) {
+            docIds = reader.intersect(allTerms);
+        }
+    }
+    // Check for quoted phrase
+    else if (trimmedQuery.startsWith('"') && trimmedQuery.endsWith('"')) {
+        const phrase = trimmedQuery.slice(1, -1);
+        const terms = simpleTokenize(phrase);
+        if (terms.length > 0) {
+            docIds = reader.intersect(terms);
+        }
+    }
+    // Check for prefix wildcard
+    else if (trimmedQuery.endsWith('*')) {
+        const prefix = trimmedQuery.slice(0, -1).toLowerCase();
+        const matchingEntries = reader.searchPrefix(prefix, 100);
+        const matchingTerms = matchingEntries.map((e) => e.term);
+        if (matchingTerms.length > 0) {
+            docIds = reader.union(matchingTerms);
+        }
+    }
+    // Default: treat as space-separated terms (implicit AND or single term)
+    else {
+        const terms = simpleTokenize(trimmedQuery);
+        if (terms.length > 0) {
+            if (terms.length === 1) {
+                docIds = reader.getPostings(terms[0]);
+            }
+            else {
+                docIds = reader.intersect(terms);
+            }
+        }
+    }
+    checkTimeout();
+    // Apply pagination
+    const totalHits = docIds.length;
+    let hits = docIds;
+    if (offset > 0) {
+        hits = hits.slice(offset);
+    }
+    if (limit !== undefined) {
+        hits = hits.slice(0, limit);
+    }
+    return {
+        hits,
+        totalHits,
+        queryTimeMs: performance.now() - startTime,
+    };
+}
+// ============================================================================
+// Combined Query Router Types
+// ============================================================================
+import { buildIndexUrl } from '../db/iceberg/search-manifest';
+// ============================================================================
+// Combined Query Router Implementation
+// ============================================================================
+/** Maximum subrequests allowed per search */
+const MAX_SUBREQUESTS = 5;
+/**
+ * Parse a search query from URL parameters.
+ *
+ * Query format:
+ * - bloom=field:value
+ * - range=field:op:value (op: gt, lt, gte, lte, eq)
+ * - vector=field:base64data:k=N
+ * - text=field:query
+ *
+ * @param url - URL containing query parameters
+ * @returns Parsed SearchQuery
+ */
+export function parseSearchQuery(url) {
+    const query = {};
+    // Parse bloom parameters
+    const bloomParams = url.searchParams.getAll('bloom');
+    if (bloomParams.length > 0) {
+        query.bloom = bloomParams.map((param) => {
+            const colonIndex = param.indexOf(':');
+            if (colonIndex === -1) {
+                return { field: param, value: '' };
+            }
+            return {
+                field: param.slice(0, colonIndex),
+                value: param.slice(colonIndex + 1),
+            };
+        });
+    }
+    // Parse range parameters
+    const rangeParams = url.searchParams.getAll('range');
+    if (rangeParams.length > 0) {
+        query.range = rangeParams.map((param) => {
+            const parts = param.split(':');
+            if (parts.length < 3) {
+                return { field: parts[0] ?? '', op: 'eq', value: parts[1] ?? '' };
+            }
+            return {
+                field: parts[0],
+                op: parts[1],
+                value: parts.slice(2).join(':'), // Rejoin remaining parts for values with colons
+            };
+        });
+    }
+    // Parse vector parameter
+    const vectorParam = url.searchParams.get('vector');
+    if (vectorParam) {
+        const parts = vectorParam.split(':');
+        if (parts.length >= 3) {
+            const field = parts[0];
+            const base64Data = parts[1];
+            const kMatch = parts[2].match(/k=(\d+)/);
+            const k = kMatch ? parseInt(kMatch[1], 10) : 10;
+            // Decode base64 to Float32Array
+            // First decode to a byte array, then create Float32Array
+            const binaryString = Buffer.from(base64Data, 'base64');
+            // Create a new ArrayBuffer with the exact size needed
+            const arrayBuffer = new ArrayBuffer(binaryString.length);
+            const uint8View = new Uint8Array(arrayBuffer);
+            for (let i = 0; i < binaryString.length; i++) {
+                uint8View[i] = binaryString[i];
+            }
+            const floatArray = new Float32Array(arrayBuffer);
+            query.vector = { field, query: floatArray, k };
+        }
+    }
+    // Parse text parameter
+    const textParam = url.searchParams.get('text');
+    if (textParam) {
+        const colonIndex = textParam.indexOf(':');
+        if (colonIndex !== -1) {
+            query.text = {
+                field: textParam.slice(0, colonIndex),
+                query: textParam.slice(colonIndex + 1),
+            };
+        }
+    }
+    return query;
+}
+/**
+ * Clear all search caches.
+ */
+export function clearSearchCache() {
+    clearCentroidCache();
+    clearInvertedIndexCache();
+    clearBloomCache();
+}
+/**
+ * Execute a combined search query against a manifest.
+ *
+ * @param manifest - Search manifest describing available indexes
+ * @param query - Combined search query
+ * @param ctx - Execution context
+ * @param options - Execution options
+ * @returns Combined search result
+ */
+export async function executeSearch(manifest, query, ctx, options = {}) {
+    const { fetch: customFetch = fetch, timeoutMs = 5000, maxSubrequests = MAX_SUBREQUESTS, } = options;
+    const startTime = performance.now();
+    const timing = { total_ms: 0 };
+    let subrequests = 0;
+    let budgetRemaining = maxSubrequests;
+    // Track if we should prune (any definitive NO from bloom = prune all)
+    let pruned = false;
+    // Results from different query types
+    let rangeBlocks;
+    let vectorCentroids;
+    let textDocuments;
+    // Helper to check timeout
+    const checkTimeout = () => {
+        if (performance.now() - startTime > timeoutMs) {
+            throw new Error('Search timeout');
+        }
+    };
+    // Helper to track subrequests
+    const trackSubrequest = () => {
+        subrequests++;
+        budgetRemaining--;
+    };
+    // Empty query - return immediately
+    const hasQuery = (query.bloom && query.bloom.length > 0) ||
+        (query.range && query.range.length > 0) ||
+        query.vector ||
+        query.text;
+    if (!hasQuery) {
+        return {
+            pruned: false,
+            timing: { total_ms: performance.now() - startTime },
+            subrequests: 0,
+        };
+    }
+    // Validate vector query dimensions if present
+    if (query.vector) {
+        const vectorConfig = manifest.indexes.vector?.[query.vector.field];
+        if (vectorConfig) {
+            if (query.vector.query.length === 0) {
+                throw new Error('Vector query is empty - dimension mismatch');
+            }
+            if (query.vector.query.length !== vectorConfig.dims) {
+                throw new Error(`Vector dimension mismatch: expected ${vectorConfig.dims}, got ${query.vector.query.length}`);
+            }
+        }
+    }
+    try {
+        // =========================================================================
+        // Phase 1: Bloom filter checks (most selective, do first)
+        // =========================================================================
+        if (query.bloom && query.bloom.length > 0 && budgetRemaining > 0) {
+            const bloomStartTime = performance.now();
+            for (const bloomQuery of query.bloom) {
+                if (budgetRemaining <= 0)
+                    break;
+                checkTimeout();
+                const bloomConfig = manifest.indexes.bloom?.[bloomQuery.field];
+                if (!bloomConfig) {
+                    // Field not in manifest - skip (conservative: don't prune)
+                    continue;
+                }
+                const bloomUrl = buildIndexUrl(manifest, 'bloom', bloomQuery.field);
+                if (!bloomUrl)
+                    continue;
+                try {
+                    trackSubrequest();
+                    // Note: fieldId is used to identify which bloom filter in a Puffin file
+                    // Since each field has its own Puffin file in this schema, use a default fieldId
+                    // The fieldId in Puffin files typically corresponds to Iceberg column IDs
+                    const result = await queryBloom({
+                        url: bloomUrl,
+                        fieldId: 1, // Default column ID
+                        value: bloomQuery.value,
+                    }, { fetch: customFetch });
+                    if (result === BloomQueryResult.NO) {
+                        // Definitive NO - prune entire result
+                        pruned = true;
+                        timing.bloom_ms = performance.now() - bloomStartTime;
+                        break;
+                    }
+                    // result === MAYBE means continue checking
+                }
+                catch {
+                    // On error, be conservative - don't prune
+                    continue;
+                }
+            }
+            timing.bloom_ms = performance.now() - bloomStartTime;
+        }
+        // Short-circuit if already pruned
+        if (pruned) {
+            return {
+                pruned: true,
+                timing: {
+                    ...timing,
+                    total_ms: performance.now() - startTime,
+                },
+                subrequests,
+            };
+        }
+        // =========================================================================
+        // Phase 2: Range queries (determine blocks to scan)
+        // =========================================================================
+        if (query.range && query.range.length > 0 && budgetRemaining > 0) {
+            const rangeStartTime = performance.now();
+            const allBlocks = new Set();
+            let firstRangeQuery = true;
+            for (const rangeQuery of query.range) {
+                if (budgetRemaining <= 0)
+                    break;
+                checkTimeout();
+                const rangeConfig = manifest.indexes.range?.[rangeQuery.field];
+                if (!rangeConfig)
+                    continue;
+                const rangeUrl = buildIndexUrl(manifest, 'range', rangeQuery.field);
+                if (!rangeUrl)
+                    continue;
+                try {
+                    trackSubrequest();
+                    // Fetch marks file
+                    const response = await customFetch(rangeUrl);
+                    if (!response.ok)
+                        continue;
+                    const buffer = await response.arrayBuffer();
+                    // Use int64 type for range queries (covers timestamps and integers)
+                    const blocks = parseMarksFile(new Uint8Array(buffer), 'int64');
+                    // Find matching blocks based on operator
+                    const matchingBlocks = findMatchingBlocks(blocks, rangeQuery.op, rangeQuery.value);
+                    if (firstRangeQuery) {
+                        for (const block of matchingBlocks) {
+                            allBlocks.add(block);
+                        }
+                        firstRangeQuery = false;
+                    }
+                    else {
+                        // Intersect with previous results (AND semantics)
+                        // Use Set for O(1) lookups instead of O(n) array includes
+                        const matchingSet = new Set(matchingBlocks);
+                        for (const block of allBlocks) {
+                            if (!matchingSet.has(block)) {
+                                allBlocks.delete(block);
+                            }
+                        }
+                    }
+                    // If no blocks match, we can prune
+                    if (allBlocks.size === 0 && !firstRangeQuery) {
+                        pruned = true;
+                        break;
+                    }
+                }
+                catch {
+                    // On error, be conservative
+                    continue;
+                }
+            }
+            if (allBlocks.size > 0) {
+                rangeBlocks = Array.from(allBlocks).sort((a, b) => a - b);
+            }
+            timing.range_ms = performance.now() - rangeStartTime;
+        }
+        // Short-circuit if pruned by range
+        if (pruned) {
+            return {
+                pruned: true,
+                timing: {
+                    ...timing,
+                    total_ms: performance.now() - startTime,
+                },
+                subrequests,
+            };
+        }
+        // =========================================================================
+        // Phase 3: Vector query (find nearest centroids)
+        // =========================================================================
+        if (query.vector && budgetRemaining > 0) {
+            const vectorStartTime = performance.now();
+            const vectorConfig = manifest.indexes.vector?.[query.vector.field];
+            if (vectorConfig) {
+                const vectorUrl = buildIndexUrl(manifest, 'vector', query.vector.field);
+                if (vectorUrl) {
+                    try {
+                        trackSubrequest();
+                        const k = Math.min(query.vector.k, vectorConfig.count);
+                        // Convert manifest metric string to DistanceMetric enum
+                        const metricMap = {
+                            cosine: DistanceMetric.Cosine,
+                            euclidean: DistanceMetric.Euclidean,
+                            dot: DistanceMetric.DotProduct,
+                        };
+                        const metric = metricMap[vectorConfig.metric] ?? DistanceMetric.Cosine;
+                        const topK = await queryVector({
+                            centroidsUrl: vectorUrl,
+                            numCentroids: vectorConfig.count,
+                            dims: vectorConfig.dims,
+                            query: query.vector.query,
+                            k,
+                            metric,
+                            fetch: customFetch,
+                        });
+                        vectorCentroids = topK.map((result) => ({
+                            index: result.index,
+                            distance: result.distance,
+                        }));
+                    }
+                    catch {
+                        // On error, leave centroids undefined
+                    }
+                }
+            }
+            timing.vector_ms = performance.now() - vectorStartTime;
+        }
+        // =========================================================================
+        // Phase 4: Full-text query
+        // =========================================================================
+        if (query.text && budgetRemaining > 0) {
+            const textStartTime = performance.now();
+            const invertedConfig = manifest.indexes.inverted?.[query.text.field];
+            if (invertedConfig) {
+                const invertedUrl = buildIndexUrl(manifest, 'inverted', query.text.field);
+                if (invertedUrl) {
+                    try {
+                        trackSubrequest();
+                        const result = await queryFullText({ url: invertedUrl, query: query.text.query }, { fetch: customFetch });
+                        textDocuments = result.hits;
+                        // If no documents match, we could prune
+                        // But for combined queries we want to return the result
+                        if (result.hits.length === 0) {
+                            pruned = true;
+                        }
+                    }
+                    catch {
+                        // On error, leave documents undefined
+                    }
+                }
+            }
+            timing.text_ms = performance.now() - textStartTime;
+        }
+    }
+    catch (error) {
+        // Handle timeout
+        if (error instanceof Error && error.message.includes('timeout')) {
+            return {
+                pruned: false, // Conservative on timeout
+                timing: {
+                    ...timing,
+                    total_ms: performance.now() - startTime,
+                },
+                subrequests,
+            };
+        }
+        throw error;
+    }
+    timing.total_ms = performance.now() - startTime;
+    return {
+        pruned,
+        blocks: rangeBlocks,
+        centroids: vectorCentroids,
+        documents: textDocuments,
+        timing,
+        subrequests,
+    };
+}
+// ============================================================================
+// Helper Functions for Combined Router
+// ============================================================================
+/**
+ * Find blocks matching a range query.
+ */
+function findMatchingBlocks(blocks, op, value) {
+    // Try to parse value as a number/timestamp
+    let numValue;
+    try {
+        // Check if it's a date string
+        if (value.includes('-') && value.length >= 10) {
+            numValue = BigInt(new Date(value).getTime());
+        }
+        else {
+            numValue = BigInt(value);
+        }
+    }
+    catch {
+        // If parsing fails, return all blocks (conservative)
+        return blocks.map((b) => b.blockIndex);
+    }
+    const matchingBlocks = [];
+    for (const block of blocks) {
+        let matches = false;
+        // Handle different min/max types (bigint or number)
+        const minVal = typeof block.min === 'bigint' ? block.min : BigInt(Math.floor(block.min));
+        const maxVal = typeof block.max === 'bigint' ? block.max : BigInt(Math.floor(block.max));
+        switch (op) {
+            case 'gt':
+                // Block matches if its max > value (some values could be > value)
+                matches = maxVal > numValue;
+                break;
+            case 'gte':
+                // Block matches if its max >= value
+                matches = maxVal >= numValue;
+                break;
+            case 'lt':
+                // Block matches if its min < value
+                matches = minVal < numValue;
+                break;
+            case 'lte':
+                // Block matches if its min <= value
+                matches = minVal <= numValue;
+                break;
+            case 'eq':
+                // Block matches if value is within [min, max]
+                matches = minVal <= numValue && maxVal >= numValue;
+                break;
+        }
+        if (matches) {
+            matchingBlocks.push(block.blockIndex);
+        }
+    }
+    return matchingBlocks;
+}
+//# sourceMappingURL=search.js.map