@bbigbang/core 0.1.0

package/dist/web/panelQueryHandles.js

@@ -0,0 +1,2749 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { validatePanelApiJsonlUrl, validatePanelApiJsonlUrlList } from '@bbigbang/protocol';
+import { resolvePanelDatasetPath } from './panelPathPolicy.js';
+import { aggregatePanelFieldRecords, getPanelFieldValue, } from './panels.js';
+const QUERY_HANDLE_WORKSPACE_JSONL_PREFIX = 'workspace_jsonl:';
+const QUERY_HANDLE_WORKSPACE_JSONL_LIST_PREFIX = 'workspace_jsonl_list:';
+const QUERY_HANDLE_MAX_SOURCE_PATHS = 16;
+const QUERY_HANDLE_READ_CHUNK_BYTES = 256 * 1024;
+const QUERY_HANDLE_MAX_CHUNKS_PER_PAGE = 64;
+const QUERY_HANDLE_MAX_CHUNKS_PER_SORT = 512;
+const QUERY_HANDLE_INDEX_INTERVAL_ROWS = 200;
+const API_JSONL_MAX_BYTES = 2 * 1024 * 1024;
+const API_JSONL_MAX_ROWS = 10_000;
+const API_JSONL_RANGE_CHUNK_BYTES = 256 * 1024;
+const API_JSONL_MAX_RANGE_CHUNKS_PER_PAGE = 64;
+const API_JSONL_MAX_RANGE_CHUNKS_PER_INDEX = 512;
+/** TTL for panel_api_jsonl_response_cache entries (7 days). */
+export const PANEL_API_JSONL_RESPONSE_CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+/** Per-panel size budget for panel_api_jsonl_response_cache (64 MiB). */
+export const PANEL_API_JSONL_RESPONSE_CACHE_MAX_TOTAL_BYTES_PER_PANEL = 64 * 1024 * 1024;
+export class PanelQueryHandleError extends Error {
+    statusCode;
+    constructor(message, statusCode = 400) {
+        super(message);
+        this.name = 'PanelQueryHandleError';
+        this.statusCode = statusCode;
+    }
+}
+export function isPanelQueryHandleSource(panel) {
+    return panel.datasetSource?.kind === 'query_handle' || panel.datasetSource?.kind === 'api_jsonl';
+}
+export function parsePanelQueryHandle(handle) {
+    const trimmed = handle.trim();
+    if (trimmed.startsWith(QUERY_HANDLE_WORKSPACE_JSONL_LIST_PREFIX)) {
+        const rawList = trimmed.slice(QUERY_HANDLE_WORKSPACE_JSONL_LIST_PREFIX.length).trim();
+        let parsed;
+        try {
+            parsed = JSON.parse(rawList);
+        }
+        catch {
+            throw new PanelQueryHandleError('query_handle workspace_jsonl_list must be a JSON array of paths.', 400);
+        }
+        if (!Array.isArray(parsed) || parsed.length < 1 || parsed.length > QUERY_HANDLE_MAX_SOURCE_PATHS) {
+            throw new PanelQueryHandleError(`query_handle workspace_jsonl_list must contain 1-${QUERY_HANDLE_MAX_SOURCE_PATHS} paths.`, 400);
+        }
+        return {
+            paths: parsed.map((entry, index) => normalizeQueryHandleWorkspaceJsonlPath(entry, `query_handle workspace_jsonl_list path ${index + 1}`)),
+        };
+    }
+    if (!trimmed.startsWith(QUERY_HANDLE_WORKSPACE_JSONL_PREFIX)) {
+        throw new PanelQueryHandleError('Unsupported query_handle. Use workspace_jsonl:<path> or workspace_jsonl_list:["<path>",...] for query_handle panels.', 400);
+    }
+    return {
+        paths: [normalizeQueryHandleWorkspaceJsonlPath(trimmed.slice(QUERY_HANDLE_WORKSPACE_JSONL_PREFIX.length), 'query_handle workspace_jsonl path')],
+    };
+}
+function normalizeQueryHandleWorkspaceJsonlPath(rawPath, label) {
+    if (typeof rawPath !== 'string') {
+        throw new PanelQueryHandleError(`${label} must be a string path.`, 400);
+    }
+    const sourcePath = rawPath.trim();
+    if (!sourcePath
+        || sourcePath.includes('\0')
+        || /[\r\n]/u.test(sourcePath)) {
+        throw new PanelQueryHandleError(`${label} must be a non-empty path without control characters.`, 400);
+    }
+    if (!path.isAbsolute(sourcePath) && sourcePath.split('/').includes('..')) {
+        throw new PanelQueryHandleError(`${label} must not contain relative traversal.`, 400);
+    }
+    return sourcePath;
+}
+export function parsePanelApiJsonlUrl(url, options = {}) {
+    const validation = validatePanelApiJsonlUrl(url, options);
+    if (!validation.ok) {
+        throw new PanelQueryHandleError(validation.reason, 400);
+    }
+    return { url: validation.url };
+}
+export function parsePanelApiJsonlUrls(source, options = {}) {
+    const validation = validatePanelApiJsonlUrlList(source, options);
+    if (!validation.ok) {
+        throw new PanelQueryHandleError(validation.reason, 400);
+    }
+    return { urls: validation.urls, authProfile: validation.authProfile };
+}
+export async function listPanelQueryHandleRows(params) {
+    const source = params.panel.datasetSource;
+    if (source?.kind !== 'query_handle' && source?.kind !== 'api_jsonl') {
+        throw new PanelQueryHandleError('Panel does not use a dynamic dataset source.', 400);
+    }
+    const agent = params.conversationManager.getAgent(params.panel.agentId);
+    if (!agent?.nodeId) {
+        throw new PanelQueryHandleError('dynamic panel agent node is unavailable.', 409);
+    }
+    if (!params.workspaceBroker) {
+        throw new PanelQueryHandleError('Workspace broker unavailable.', 503);
+    }
+    if (source.kind === 'api_jsonl') {
+        const parsed = parsePanelApiJsonlUrls(source, {
+            allowedOrigins: params.apiJsonlAllowedOrigins,
+            allowedUrlPrefixes: params.apiJsonlAllowedUrlPrefixes,
+            allowedAuthProfiles: params.apiJsonlAuthProfiles,
+        });
+        return listPanelApiJsonlRows({
+            db: params.db,
+            panel: params.panel,
+            conversationManager: params.conversationManager,
+            config: params.config,
+            apiJsonlAllowedOrigins: params.apiJsonlAllowedOrigins,
+            apiJsonlAllowedUrlPrefixes: params.apiJsonlAllowedUrlPrefixes,
+            apiJsonlAuthProfiles: params.apiJsonlAuthProfiles,
+            sourceUrls: parsed.urls,
+            authProfile: parsed.authProfile,
+            workspaceBroker: params.workspaceBroker,
+            nodeId: agent.nodeId,
+            datasetSchema: params.datasetSchema,
+            options: params.options,
+            limit: Math.min(Math.max(1, params.options.limit), 200),
+        });
+    }
+    if (!agent.workspacePath) {
+        throw new PanelQueryHandleError('query_handle panel agent workspace is unavailable.', 409);
+    }
+    const dataSources = resolveQueryHandleDataSources({
+        handle: source.handle,
+        workspaceRoot: agent.workspacePath,
+        config: params.config,
+    });
+    const limit = Math.min(Math.max(1, params.options.limit), 200);
+    if (params.options.sortField && params.options.sortDirection) {
+        return listSortedPanelQueryHandleRows({
+            db: params.db,
+            panel: params.panel,
+            conversationManager: params.conversationManager,
+            config: params.config,
+            indexContext: createQueryHandleIndexContext(params.db, params.panel.id, dataSources),
+            workspaceBroker: params.workspaceBroker,
+            nodeId: agent.nodeId,
+            workspaceRoot: agent.workspacePath,
+            dataSources,
+            datasetSchema: params.datasetSchema,
+            options: params.options,
+            limit,
+        });
+    }
+    return listUnsortedPanelQueryHandleRows({
+        db: params.db,
+        panel: params.panel,
+        conversationManager: params.conversationManager,
+        config: params.config,
+        indexContext: createQueryHandleIndexContext(params.db, params.panel.id, dataSources),
+        workspaceBroker: params.workspaceBroker,
+        nodeId: agent.nodeId,
+        workspaceRoot: agent.workspacePath,
+        dataSources,
+        datasetSchema: params.datasetSchema,
+        options: params.options,
+        limit,
+    });
+}
+export async function aggregatePanelQueryHandleRows(params) {
+    const source = params.panel.datasetSource;
+    if (source?.kind !== 'query_handle' && source?.kind !== 'api_jsonl') {
+        throw new PanelQueryHandleError('Panel does not use a dynamic dataset source.', 400);
+    }
+    const agent = params.conversationManager.getAgent(params.panel.agentId);
+    if (!agent?.nodeId) {
+        throw new PanelQueryHandleError('dynamic panel agent node is unavailable.', 409);
+    }
+    if (!params.workspaceBroker) {
+        throw new PanelQueryHandleError('Workspace broker unavailable.', 503);
+    }
+    if (source.kind === 'api_jsonl') {
+        const parsed = parsePanelApiJsonlUrls(source, {
+            allowedOrigins: params.apiJsonlAllowedOrigins,
+            allowedUrlPrefixes: params.apiJsonlAllowedUrlPrefixes,
+            allowedAuthProfiles: params.apiJsonlAuthProfiles,
+        });
+        const indexContext = createApiJsonlIndexContext(params.db, params.panel.id, parsed.urls, parsed.authProfile);
+        const sourceManifestKey = indexContext?.sourceManifestKey ?? apiJsonlSourceManifestKey(parsed.urls, parsed.authProfile);
+        const extraFieldNames = aggregateFieldIndexNames(params.options);
+        const hasBoundedResponseCache = hasApiJsonlResponseCacheForAllSources(params.db, {
+            panelId: params.panel.id,
+            sourceManifestKey,
+            sourceUrls: parsed.urls,
+        });
+        if (!hasBoundedResponseCache) {
+            const rangeMetadataKey = await ensureApiJsonlRangeFieldIndex({
+                db: params.db,
+                panel: params.panel,
+                sourceUrls: parsed.urls,
+                authProfile: parsed.authProfile,
+                workspaceBroker: params.workspaceBroker,
+                nodeId: agent.nodeId,
+                datasetSchema: params.datasetSchema,
+                indexContext,
+                extraFieldNames,
+            });
+            if (indexContext && rangeMetadataKey) {
+                const indexed = readAggregateFromQueryHandleFieldIndex({
+                    db: params.db,
+                    panel: params.panel,
+                    sourceManifestKey: indexContext.sourceManifestKey,
+                    metadataKey: rangeMetadataKey,
+                    datasetSchema: params.datasetSchema,
+                    options: params.options,
+                    extraFieldNames,
+                    sourceKind: 'api_jsonl_field_index',
+                });
+                if (indexed)
+                    return indexed;
+            }
+        }
+        const sources = await fetchApiJsonlSources({
+            db: params.db,
+            panelId: params.panel.id,
+            sourceUrls: parsed.urls,
+            authProfile: parsed.authProfile,
+            sourceManifestKey,
+            workspaceBroker: params.workspaceBroker,
+            nodeId: agent.nodeId,
+        });
+        const rows = parseApiJsonlRowsFromSources(sources, params.datasetSchema);
+        const metadataKey = apiJsonlMetadataKey(sources);
+        if (indexContext) {
+            writeQueryHandleFieldIndexRows({
+                context: indexContext,
+                metadataKey,
+                datasetSchema: params.datasetSchema,
+                rows: rows.map((row) => ({ rowIndex: row.rowIndex, fields: row.fields })),
+                extraFieldNames,
+            });
+            const indexed = readAggregateFromQueryHandleFieldIndex({
+                db: params.db,
+                panel: params.panel,
+                sourceManifestKey: indexContext.sourceManifestKey,
+                metadataKey,
+                datasetSchema: params.datasetSchema,
+                options: params.options,
+                extraFieldNames,
+                sourceKind: 'api_jsonl_field_index',
+            });
+            if (indexed)
+                return indexed;
+        }
+        return aggregatePanelFieldRecords(rows
+            .filter((row) => matchesFilter(row.fields, params.options.filterField, params.options.filterValue))
+            .map((row) => row.fields), {
+            op: params.options.op,
+            field: params.options.field,
+        });
+    }
+    if (!agent.workspacePath) {
+        throw new PanelQueryHandleError('query_handle panel agent workspace is unavailable.', 409);
+    }
+    const dataSources = resolveQueryHandleDataSources({
+        handle: source.handle,
+        workspaceRoot: agent.workspacePath,
+        config: params.config,
+    });
+    const indexContext = createQueryHandleIndexContext(params.db, params.panel.id, dataSources);
+    const extraFieldNames = aggregateFieldIndexNames(params.options);
+    const metadataKey = indexContext
+        ? await loadQueryHandleIndexMetadataKey({
+            context: indexContext,
+            workspaceBroker: params.workspaceBroker,
+            nodeId: agent.nodeId,
+            workspaceRoot: agent.workspacePath,
+            dataSources,
+        })
+        : null;
+    if (indexContext && metadataKey) {
+        const indexed = readAggregateFromQueryHandleFieldIndex({
+            db: params.db,
+            panel: params.panel,
+            sourceManifestKey: indexContext.sourceManifestKey,
+            metadataKey,
+            datasetSchema: params.datasetSchema,
+            options: params.options,
+            extraFieldNames,
+            sourceKind: 'query_handle_field_index',
+        });
+        if (indexed)
+            return indexed;
+    }
+    const rows = await scanQueryHandleRowsForFieldIndex({
+        db: params.db,
+        panel: params.panel,
+        workspaceBroker: params.workspaceBroker,
+        nodeId: agent.nodeId,
+        workspaceRoot: agent.workspacePath,
+        dataSources,
+        datasetSchema: params.datasetSchema,
+        indexContext,
+        metadataKey,
+        extraFieldNames,
+    });
+    if (indexContext && metadataKey) {
+        const indexed = readAggregateFromQueryHandleFieldIndex({
+            db: params.db,
+            panel: params.panel,
+            sourceManifestKey: indexContext.sourceManifestKey,
+            metadataKey,
+            datasetSchema: params.datasetSchema,
+            options: params.options,
+            extraFieldNames,
+            sourceKind: 'query_handle_field_index',
+        });
+        if (indexed)
+            return indexed;
+    }
+    return aggregatePanelFieldRecords(rows
+        .filter((row) => matchesFilter(row.fields, params.options.filterField, params.options.filterValue))
+        .map((row) => row.fields), {
+        op: params.options.op,
+        field: params.options.field,
+    });
+}
+async function listUnsortedPanelQueryHandleRows(params) {
+    if (params.indexContext && params.options.filterField && params.options.filterValue !== undefined) {
+        const metadataKey = await loadQueryHandleIndexMetadataKey({
+            context: params.indexContext,
+            workspaceBroker: params.workspaceBroker,
+            nodeId: params.nodeId,
+            workspaceRoot: params.workspaceRoot,
+            dataSources: params.dataSources,
+        });
+        if (metadataKey) {
+            const cursor = parseQueryHandlePositionCursor(params.options.cursor, {
+                sourceKind: 'query_handle_field_index',
+                filterField: params.options.filterField,
+                filterValue: params.options.filterValue,
+            });
+            const indexed = await readFilteredQueryHandleRowsFromFieldIndex({
+                db: params.db,
+                panel: params.panel,
+                conversationManager: params.conversationManager,
+                workspaceBroker: params.workspaceBroker,
+                config: params.config,
+                datasetSchema: params.datasetSchema,
+                sourceManifestKey: params.indexContext.sourceManifestKey,
+                metadataKey,
+                options: params.options,
+                position: cursor.position,
+                limit: params.limit,
+            });
+            if (indexed)
+                return indexed;
+        }
+    }
+    const cursor = parseQueryHandleCursor(params.options.cursor);
+    let sourceIndex = Math.min(Math.max(0, cursor.sourceIndex ?? 0), params.dataSources.length - 1);
+    if (!Number.isFinite(sourceIndex))
+        sourceIndex = 0;
+    const rows = [];
+    let offset = cursor.offset;
+    let rowIndex = cursor.rowIndex;
+    let chunks = 0;
+    const sourceSawRows = new Set();
+    if (offset > 0)
+        sourceSawRows.add(sourceIndex);
+    while (rows.length < params.limit && sourceIndex < params.dataSources.length) {
+        chunks += 1;
+        if (chunks > QUERY_HANDLE_MAX_CHUNKS_PER_PAGE) {
+            throw new PanelQueryHandleError('query_handle page scan exceeded the per-page work limit.', 413);
+        }
+        const chunk = await readQueryHandleChunk({
+            workspaceBroker: params.workspaceBroker,
+            nodeId: params.nodeId,
+            workspaceRoot: params.workspaceRoot,
+            dataSource: params.dataSources[sourceIndex],
+            offset,
+            limit: QUERY_HANDLE_READ_CHUNK_BYTES,
+        });
+        const content = chunk.content ?? '';
+        const parsed = parseCompleteJsonlLines(content, Boolean(chunk.hasMore));
+        if (parsed.completeText.length === 0 && chunk.hasMore) {
+            throw new PanelQueryHandleError('query_handle JSONL row exceeds the per-row size limit.', 413);
+        }
+        const baseOffset = chunk.offset ?? offset;
+        let consumedBytes = 0;
+        for (const line of parsed.lines) {
+            const lineStartOffset = baseOffset + consumedBytes;
+            consumedBytes += line.byteLength;
+            const trimmed = line.text.trim();
+            if (!trimmed)
+                continue;
+            const rawRow = parseJsonlRow(trimmed, rowIndex);
+            const row = buildPanelRowFromQueryRow(rawRow, rowIndex, params.datasetSchema);
+            const isSourceStart = !sourceSawRows.has(sourceIndex);
+            sourceSawRows.add(sourceIndex);
+            recordQueryHandleCheckpoint(params.indexContext, {
+                sourceIndex,
+                chunk,
+                rowIndex,
+                byteOffset: lineStartOffset,
+                isSourceStart,
+            });
+            rowIndex += 1;
+            if (!matchesFilter(row.fields, params.options.filterField, params.options.filterValue)) {
+                continue;
+            }
+            rows.push(row);
+            if (rows.length >= params.limit)
+                break;
+        }
+        offset = baseOffset + consumedBytes;
+        if (offset >= chunk.size) {
+            sourceIndex += 1;
+            offset = 0;
+        }
+    }
+    return {
+        rows,
+        nextCursor: sourceIndex < params.dataSources.length
+            ? encodeQueryHandleCursor({ sourceIndex, offset, rowIndex })
+            : null,
+    };
+}
+async function listSortedPanelQueryHandleRows(params) {
+    const sortField = params.options.sortField;
+    const sortDirection = params.options.sortDirection;
+    if (!sortField || !sortDirection) {
+        throw new PanelQueryHandleError('query_handle sort requires both sort field and direction.', 400);
+    }
+    const queryKey = queryHandleViewIndexQueryKey(params.options);
+    const cursor = parseQueryHandleSortCursor(params.options.cursor, {
+        sortField,
+        sortDirection,
+        filterField: params.options.filterField,
+        filterValue: params.options.filterValue,
+    });
+    const metadataKey = params.indexContext
+        ? await loadQueryHandleIndexMetadataKey({
+            context: params.indexContext,
+            workspaceBroker: params.workspaceBroker,
+            nodeId: params.nodeId,
+            workspaceRoot: params.workspaceRoot,
+            dataSources: params.dataSources,
+        })
+        : null;
+    if (metadataKey) {
+        const cached = await readCachedQueryHandleViewIndexRows({
+            db: params.db,
+            panel: params.panel,
+            conversationManager: params.conversationManager,
+            workspaceBroker: params.workspaceBroker,
+            config: params.config,
+            datasetSchema: params.datasetSchema,
+            sourceManifestKey: params.indexContext.sourceManifestKey,
+            queryKey,
+            metadataKey,
+            position: cursor.position,
+            limit: params.limit,
+        });
+        if (cached)
+            return cached;
+        const indexed = await readQueryHandleRowsFromFieldIndex({
+            db: params.db,
+            panel: params.panel,
+            conversationManager: params.conversationManager,
+            workspaceBroker: params.workspaceBroker,
+            config: params.config,
+            datasetSchema: params.datasetSchema,
+            sourceManifestKey: params.indexContext.sourceManifestKey,
+            metadataKey,
+            options: params.options,
+            position: cursor.position,
+            limit: params.limit,
+        });
+        if (indexed)
+            return indexed;
+    }
+    const rows = [];
+    const fieldIndexRows = [];
+    let rowIndex = 0;
+    let chunks = 0;
+    const sourceSawRows = new Set();
+    for (let sourceIndex = 0; sourceIndex < params.dataSources.length; sourceIndex += 1) {
+        const dataSource = params.dataSources[sourceIndex];
+        let offset = 0;
+        let hasMore = true;
+        while (hasMore) {
+            chunks += 1;
+            if (chunks > QUERY_HANDLE_MAX_CHUNKS_PER_SORT) {
+                throw new PanelQueryHandleError('query_handle sorted scan exceeded the per-request work limit.', 413);
+            }
+            const chunk = await readQueryHandleChunk({
+                workspaceBroker: params.workspaceBroker,
+                nodeId: params.nodeId,
+                workspaceRoot: params.workspaceRoot,
+                dataSource,
+                offset,
+                limit: QUERY_HANDLE_READ_CHUNK_BYTES,
+            });
+            const content = chunk.content ?? '';
+            const parsed = parseCompleteJsonlLines(content, Boolean(chunk.hasMore));
+            if (parsed.completeText.length === 0 && chunk.hasMore) {
+                throw new PanelQueryHandleError('query_handle JSONL row exceeds the per-row size limit.', 413);
+            }
+            const baseOffset = chunk.offset ?? offset;
+            let consumedBytes = 0;
+            for (const line of parsed.lines) {
+                const lineStartOffset = baseOffset + consumedBytes;
+                consumedBytes += line.byteLength;
+                const trimmed = line.text.trim();
+                if (!trimmed)
+                    continue;
+                const rawRow = parseJsonlRow(trimmed, rowIndex);
+                const row = buildPanelRowFromQueryRow(rawRow, rowIndex, params.datasetSchema);
+                const isSourceStart = !sourceSawRows.has(sourceIndex);
+                sourceSawRows.add(sourceIndex);
+                recordQueryHandleCheckpoint(params.indexContext, {
+                    sourceIndex,
+                    chunk,
+                    rowIndex,
+                    byteOffset: lineStartOffset,
+                    isSourceStart,
+                });
+                rowIndex += 1;
+                fieldIndexRows.push({ rowIndex: row.rowIndex, fields: row.fields });
+                if (!matchesFilter(row.fields, params.options.filterField, params.options.filterValue)) {
+                    continue;
+                }
+                rows.push(row);
+            }
+            offset = baseOffset + consumedBytes;
+            hasMore = offset < chunk.size;
+            if (parsed.lines.length === 0 && !hasMore)
+                break;
+        }
+    }
+    rows.sort((left, right) => comparePanelRowsBySortField(left, right, sortField, sortDirection, params.options.sortFieldType));
+    if (metadataKey && params.indexContext) {
+        writeQueryHandleViewIndexRows({
+            context: params.indexContext,
+            queryKey,
+            metadataKey,
+            rowIndices: rows.map((row) => row.rowIndex),
+        });
+        writeQueryHandleFieldIndexRows({
+            context: params.indexContext,
+            metadataKey,
+            datasetSchema: params.datasetSchema,
+            rows: fieldIndexRows,
+        });
+    }
+    const start = Math.min(cursor.position, rows.length);
+    const resultRows = rows.slice(start, start + params.limit);
+    const nextPosition = start + resultRows.length;
+    return {
+        rows: resultRows,
+        nextCursor: nextPosition < rows.length
+            ? encodeQueryHandleSortCursor({
+                position: nextPosition,
+                sortField,
+                sortDirection,
+                filterField: params.options.filterField,
+                filterValue: params.options.filterValue,
+            })
+            : null,
+    };
+}
+async function listPanelApiJsonlRows(params) {
+    const indexContext = createApiJsonlIndexContext(params.db, params.panel.id, params.sourceUrls, params.authProfile);
+    const selectRowsByIndicesFromDynamicSource = async (rowIndices) => (await listPanelQueryHandleRowsByIndices({
+        db: params.db,
+        panel: params.panel,
+        conversationManager: params.conversationManager,
+        workspaceBroker: params.workspaceBroker,
+        config: params.config,
+        apiJsonlAllowedOrigins: params.apiJsonlAllowedOrigins,
+        apiJsonlAllowedUrlPrefixes: params.apiJsonlAllowedUrlPrefixes,
+        apiJsonlAuthProfiles: params.apiJsonlAuthProfiles,
+        datasetSchema: params.datasetSchema,
+        rowIndices,
+    })).rows;
+    if (!params.options.sortField && !params.options.filterField && !isPositionCursor(params.options.cursor)) {
+        const ranged = await listPanelApiJsonlRowsByRange({
+            ...params,
+            indexContext,
+        });
+        if (ranged)
+            return ranged;
+    }
+    const sourceManifestKey = indexContext?.sourceManifestKey ?? apiJsonlSourceManifestKey(params.sourceUrls, params.authProfile);
+    const hasBoundedResponseCache = hasApiJsonlResponseCacheForAllSources(params.db, {
+        panelId: params.panel.id,
+        sourceManifestKey,
+        sourceUrls: params.sourceUrls,
+    });
+    if (!hasBoundedResponseCache && ((params.options.sortField && params.options.sortDirection) || (params.options.filterField && params.options.filterValue !== undefined))) {
+        const rangeMetadataKey = await ensureApiJsonlRangeFieldIndex({
+            db: params.db,
+            panel: params.panel,
+            sourceUrls: params.sourceUrls,
+            authProfile: params.authProfile,
+            workspaceBroker: params.workspaceBroker,
+            nodeId: params.nodeId,
+            datasetSchema: params.datasetSchema,
+            indexContext,
+            extraFieldNames: [],
+        });
+        if (indexContext && rangeMetadataKey && params.options.sortField && params.options.sortDirection) {
+            const cursor = parseQueryHandleSortCursor(params.options.cursor, {
+                sortField: params.options.sortField,
+                sortDirection: params.options.sortDirection,
+                filterField: params.options.filterField,
+                filterValue: params.options.filterValue,
+            });
+            const indexed = await readQueryHandleRowsFromFieldIndex({
+                db: params.db,
+                panel: params.panel,
+                conversationManager: params.conversationManager,
+                workspaceBroker: params.workspaceBroker,
+                config: params.config,
+                datasetSchema: params.datasetSchema,
+                sourceManifestKey: indexContext.sourceManifestKey,
+                metadataKey: rangeMetadataKey,
+                options: params.options,
+                position: cursor.position,
+                limit: params.limit,
+                selectRowsByIndices: selectRowsByIndicesFromDynamicSource,
+            });
+            if (indexed)
+                return indexed;
+        }
+        if (indexContext && rangeMetadataKey && params.options.filterField && params.options.filterValue !== undefined) {
+            const cursor = parseQueryHandlePositionCursor(params.options.cursor, {
+                sourceKind: 'api_jsonl_field_index',
+                filterField: params.options.filterField,
+                filterValue: params.options.filterValue,
+            });
+            const indexed = await readFilteredQueryHandleRowsFromFieldIndex({
+                db: params.db,
+                panel: params.panel,
+                conversationManager: params.conversationManager,
+                workspaceBroker: params.workspaceBroker,
+                config: params.config,
+                datasetSchema: params.datasetSchema,
+                sourceManifestKey: indexContext.sourceManifestKey,
+                metadataKey: rangeMetadataKey,
+                options: params.options,
+                position: cursor.position,
+                limit: params.limit,
+                sourceKind: 'api_jsonl_field_index',
+                selectRowsByIndices: selectRowsByIndicesFromDynamicSource,
+            });
+            if (indexed)
+                return indexed;
+        }
+    }
+    const sources = await fetchApiJsonlSources({
+        db: params.db,
+        panelId: params.panel.id,
+        sourceUrls: params.sourceUrls,
+        authProfile: params.authProfile,
+        sourceManifestKey,
+        workspaceBroker: params.workspaceBroker,
+        nodeId: params.nodeId,
+    });
+    const metadataKey = apiJsonlMetadataKey(sources);
+    const selectRowsByIndices = async (rowIndices) => selectApiJsonlRowsByIndices(sources, params.datasetSchema, rowIndices);
+    if (params.options.sortField && params.options.sortDirection) {
+        const queryKey = queryHandleViewIndexQueryKey(params.options);
+        const cursor = parseQueryHandleSortCursor(params.options.cursor, {
+            sortField: params.options.sortField,
+            sortDirection: params.options.sortDirection,
+            filterField: params.options.filterField,
+            filterValue: params.options.filterValue,
+        });
+        if (indexContext) {
+            const cached = await readCachedQueryHandleViewIndexRows({
+                db: params.db,
+                panel: params.panel,
+                conversationManager: params.conversationManager,
+                workspaceBroker: params.workspaceBroker,
+                config: params.config,
+                datasetSchema: params.datasetSchema,
+                sourceManifestKey: indexContext.sourceManifestKey,
+                queryKey,
+                metadataKey,
+                position: cursor.position,
+                limit: params.limit,
+                selectRowsByIndices,
+            });
+            if (cached)
+                return cached;
+            const indexed = await readQueryHandleRowsFromFieldIndex({
+                db: params.db,
+                panel: params.panel,
+                conversationManager: params.conversationManager,
+                workspaceBroker: params.workspaceBroker,
+                config: params.config,
+                datasetSchema: params.datasetSchema,
+                sourceManifestKey: indexContext.sourceManifestKey,
+                metadataKey,
+                options: params.options,
+                position: cursor.position,
+                limit: params.limit,
+                selectRowsByIndices,
+            });
+            if (indexed)
+                return indexed;
+        }
+        const rows = parseApiJsonlRowsFromSources(sources, params.datasetSchema);
+        const filteredRows = params.options.filterField && params.options.filterValue !== undefined
+            ? rows.filter((row) => matchesFilter(row.fields, params.options.filterField, params.options.filterValue))
+            : rows;
+        filteredRows.sort((left, right) => comparePanelRowsBySortField(left, right, params.options.sortField, params.options.sortDirection, params.options.sortFieldType));
+        if (indexContext) {
+            writeQueryHandleViewIndexRows({
+                context: indexContext,
+                queryKey,
+                metadataKey,
+                rowIndices: filteredRows.map((row) => row.rowIndex),
+            });
+            writeQueryHandleFieldIndexRows({
+                context: indexContext,
+                metadataKey,
+                datasetSchema: params.datasetSchema,
+                rows: rows.map((row) => ({ rowIndex: row.rowIndex, fields: row.fields })),
+            });
+        }
+        return sliceRowsByPositionCursor(filteredRows, cursor.position, params.limit, (position) => encodeQueryHandleSortCursor({
+            position,
+            sortField: params.options.sortField,
+            sortDirection: params.options.sortDirection,
+            filterField: params.options.filterField,
+            filterValue: params.options.filterValue,
+        }));
+    }
+    if (params.options.filterField && params.options.filterValue !== undefined) {
+        const cursor = parseQueryHandlePositionCursor(params.options.cursor, {
+            sourceKind: 'api_jsonl_field_index',
+            filterField: params.options.filterField,
+            filterValue: params.options.filterValue,
+        });
+        if (indexContext) {
+            const indexed = await readFilteredQueryHandleRowsFromFieldIndex({
+                db: params.db,
+                panel: params.panel,
+                conversationManager: params.conversationManager,
+                workspaceBroker: params.workspaceBroker,
+                config: params.config,
+                datasetSchema: params.datasetSchema,
+                sourceManifestKey: indexContext.sourceManifestKey,
+                metadataKey,
+                options: params.options,
+                position: cursor.position,
+                limit: params.limit,
+                sourceKind: 'api_jsonl_field_index',
+                selectRowsByIndices,
+            });
+            if (indexed)
+                return indexed;
+        }
+        const rows = parseApiJsonlRowsFromSources(sources, params.datasetSchema);
+        if (indexContext) {
+            writeQueryHandleFieldIndexRows({
+                context: indexContext,
+                metadataKey,
+                datasetSchema: params.datasetSchema,
+                rows: rows.map((row) => ({ rowIndex: row.rowIndex, fields: row.fields })),
+            });
+        }
+        const filteredRows = rows.filter((row) => matchesFilter(row.fields, params.options.filterField, params.options.filterValue));
+        return sliceRowsByPositionCursor(filteredRows, cursor.position, params.limit, (position) => encodeQueryHandlePositionCursor({
+            position,
+            sourceKind: 'api_jsonl_field_index',
+            filterField: params.options.filterField,
+            filterValue: params.options.filterValue,
+        }));
+    }
+    const rows = parseApiJsonlRowsFromSources(sources, params.datasetSchema);
+    const cursor = parseQueryHandlePositionCursor(params.options.cursor, {
+        sourceKind: 'api_jsonl',
+        filterField: params.options.filterField,
+        filterValue: params.options.filterValue,
+    });
+    return sliceRowsByPositionCursor(rows, cursor.position, params.limit, (position) => encodeQueryHandlePositionCursor({
+        position,
+        sourceKind: 'api_jsonl',
+        filterField: params.options.filterField,
+        filterValue: params.options.filterValue,
+    }));
+}
+async function listPanelApiJsonlRowsByRange(params) {
+    const cursor = parseApiJsonlRangeCursor(params.options.cursor);
+    let sourceIndex = Math.min(Math.max(0, cursor.sourceIndex), params.sourceUrls.length - 1);
+    if (!Number.isFinite(sourceIndex))
+        sourceIndex = 0;
+    let offset = cursor.offset;
+    let rowIndex = cursor.rowIndex;
+    const rows = [];
+    let chunks = 0;
+    const sourceSawRows = new Set();
+    if (offset > 0)
+        sourceSawRows.add(sourceIndex);
+    let currentValidator = cursor.url === params.sourceUrls[sourceIndex]
+        ? {
+            url: cursor.url,
+            etag: cursor.etag ?? null,
+            lastModified: cursor.lastModified ?? null,
+            totalSize: cursor.totalSize ?? null,
+        }
+        : null;
+    while (rows.length < params.limit && sourceIndex < params.sourceUrls.length) {
+        chunks += 1;
+        if (chunks > API_JSONL_MAX_RANGE_CHUNKS_PER_PAGE) {
+            throw new PanelQueryHandleError('api_jsonl ranged page scan exceeded the per-page work limit.', 413);
+        }
+        const url = params.sourceUrls[sourceIndex];
+        const result = await params.workspaceBroker.fetchHttpText(params.nodeId, url, {
+            maxBytes: API_JSONL_MAX_BYTES,
+            ...(params.authProfile ? { authProfile: params.authProfile } : {}),
+            rangeStart: offset,
+            rangeLength: API_JSONL_RANGE_CHUNK_BYTES,
+            ...(currentValidator?.url === url ? withApiJsonlIfRange(currentValidator) : {}),
+        });
+        if (result.status !== 206
+            || result.partialContent !== true
+            || typeof result.rangeStart !== 'number'
+            || typeof result.rangeEnd !== 'number'
+            || result.rangeStart !== offset) {
+            return null;
+        }
+        if (Buffer.byteLength(result.content, 'utf8') > API_JSONL_MAX_BYTES) {
+            throw new PanelQueryHandleError(`api_jsonl response exceeds byte limit (${API_JSONL_MAX_BYTES}).`, 413);
+        }
+        currentValidator = {
+            url,
+            etag: result.etag ?? null,
+            lastModified: result.lastModified ?? null,
+            totalSize: result.totalSize ?? null,
+        };
+        const checkpointChunk = apiJsonlRangeCheckpointChunk(result);
+        const parsed = parseCompleteJsonlLines(result.content, Boolean(result.hasMore));
+        if (parsed.completeText.length === 0 && result.hasMore) {
+            throw new PanelQueryHandleError('api_jsonl JSONL row exceeds the per-row size limit.', 413);
+        }
+        const baseOffset = result.rangeStart;
+        let consumedBytes = 0;
+        let stoppedForLimit = false;
+        let lastConsumedLineIndex = -1;
+        for (const [lineIndex, line] of parsed.lines.entries()) {
+            const lineStartOffset = baseOffset + consumedBytes;
+            consumedBytes += line.byteLength;
+            lastConsumedLineIndex = lineIndex;
+            const trimmed = line.text.trim();
+            if (!trimmed)
+                continue;
+            if (rowIndex >= API_JSONL_MAX_ROWS) {
+                throw new PanelQueryHandleError(`api_jsonl response exceeds row limit (${API_JSONL_MAX_ROWS}).`, 413);
+            }
+            const rawRow = parseJsonlRow(trimmed, rowIndex);
+            const isSourceStart = !sourceSawRows.has(sourceIndex);
+            sourceSawRows.add(sourceIndex);
+            recordApiJsonlRangeCheckpoint(params.indexContext, {
+                sourceIndex,
+                chunk: checkpointChunk,
+                rowIndex,
+                byteOffset: lineStartOffset,
+                isSourceStart,
+            });
+            rows.push(buildPanelRowFromQueryRow(rawRow, rowIndex, params.datasetSchema));
+            rowIndex += 1;
+            if (rows.length >= params.limit) {
+                stoppedForLimit = true;
+                break;
+            }
+        }
+        offset = baseOffset + consumedBytes;
+        const consumedAllParsedLines = lastConsumedLineIndex >= parsed.lines.length - 1;
+        if (result.hasMore !== true && (!stoppedForLimit || consumedAllParsedLines)) {
+            sourceIndex += 1;
+            offset = 0;
+            currentValidator = null;
+        }
+    }
+    if (sourceIndex >= params.sourceUrls.length) {
+        return { rows, nextCursor: null };
+    }
+    const nextUrl = params.sourceUrls[sourceIndex];
+    return {
+        rows,
+        nextCursor: encodeApiJsonlRangeCursor({
+            sourceKind: 'api_jsonl_range',
+            sourceIndex,
+            offset,
+            rowIndex,
+            url: nextUrl,
+            ...(currentValidator?.url === nextUrl
+                ? {
+                    etag: currentValidator.etag ?? null,
+                    lastModified: currentValidator.lastModified ?? null,
+                    totalSize: currentValidator.totalSize ?? null,
+                }
+                : {}),
+        }),
+    };
+}
+async function fetchApiJsonlSources(params) {
+    const sources = [];
+    let totalRows = 0;
+    if (params.db) {
+        pruneApiJsonlResponseCache(params.db, params.panelId, params.sourceManifestKey);
+    }
+    for (const [sourceIndex, url] of params.sourceUrls.entries()) {
+        const cached = params.db
+            ? loadApiJsonlResponseCache(params.db, {
+                panelId: params.panelId,
+                sourceManifestKey: params.sourceManifestKey,
+                sourceIndex,
+                url,
+            })
+            : null;
+        const result = await params.workspaceBroker.fetchHttpText(params.nodeId, url, {
+            maxBytes: API_JSONL_MAX_BYTES,
+            ...(params.authProfile ? { authProfile: params.authProfile } : {}),
+            ...(cached?.etag ? { ifNoneMatch: cached.etag } : {}),
+            ...(cached?.lastModified ? { ifModifiedSince: cached.lastModified } : {}),
+        });
+        if (result.notModified || result.status === 304) {
+            if (!cached) {
+                throw new PanelQueryHandleError('api_jsonl endpoint returned 304 but no cached response is available.', 502);
+            }
+            totalRows += cached.rowCount;
+            if (totalRows > API_JSONL_MAX_ROWS) {
+                throw new PanelQueryHandleError(`api_jsonl response exceeds row limit (${API_JSONL_MAX_ROWS}).`, 413);
+            }
+            const refreshed = {
+                ...cached,
+                etag: result.etag ?? cached.etag,
+                lastModified: result.lastModified ?? cached.lastModified,
+                fetchedFromCache: true,
+            };
+            if (params.db && (refreshed.etag !== cached.etag || refreshed.lastModified !== cached.lastModified)) {
+                upsertApiJsonlResponseCache(params.db, {
+                    panelId: params.panelId,
+                    sourceManifestKey: params.sourceManifestKey,
+                    sourceIndex,
+                    url,
+                    source: refreshed,
+                });
+            }
+            sources.push(refreshed);
+            continue;
+        }
+        const byteLength = Buffer.byteLength(result.content, 'utf8');
+        if (byteLength > API_JSONL_MAX_BYTES) {
+            throw new PanelQueryHandleError(`api_jsonl response exceeds byte limit (${API_JSONL_MAX_BYTES}).`, 413);
+        }
+        const rowCount = countApiJsonlRows(result.content);
+        totalRows += rowCount;
+        if (totalRows > API_JSONL_MAX_ROWS) {
+            throw new PanelQueryHandleError(`api_jsonl response exceeds row limit (${API_JSONL_MAX_ROWS}).`, 413);
+        }
+        const source = {
+            url,
+            content: result.content,
+            byteLength,
+            contentHash: createHash('sha256').update(result.content).digest('hex'),
+            rowCount,
+            contentType: result.contentType,
+            etag: result.etag ?? null,
+            lastModified: result.lastModified ?? null,
+            fetchedFromCache: false,
+        };
+        sources.push(source);
+        if (params.db) {
+            upsertApiJsonlResponseCache(params.db, {
+                panelId: params.panelId,
+                sourceManifestKey: params.sourceManifestKey,
+                sourceIndex,
+                url,
+                source,
+            });
+        }
+    }
+    return sources;
+}
+function countApiJsonlRows(content) {
+    return content.split('\n').filter((line) => line.trim() !== '').length;
+}
+function createApiJsonlIndexContext(db, panelId, sourceUrls, authProfile) {
+    if (!db || sourceUrls.length < 1)
+        return null;
+    const sourceKeys = sourceUrls.map((url) => `api_jsonl:${url}`);
+    return {
+        db,
+        panelId,
+        sourceManifestKey: apiJsonlSourceManifestKey(sourceUrls, authProfile),
+        sourceKeys,
+        metadataBySourceIndex: new Map(),
+    };
+}
+export function apiJsonlSourceManifestKey(sourceUrls, authProfile) {
+    return JSON.stringify({ kind: 'api_jsonl', authProfile, urls: sourceUrls });
+}
+function apiJsonlMetadataKey(sources) {
+    return JSON.stringify(sources.map((source) => ({
+        url: source.url,
+        byteLength: source.byteLength,
+        rowCount: source.rowCount,
+        sha256: source.contentHash,
+    })));
+}
+function loadApiJsonlResponseCache(db, params) {
+    const row = db.prepare(`SELECT url,
+            content,
+            byte_length as byteLength,
+            content_hash as contentHash,
+            row_count as rowCount,
+            content_type as contentType,
+            etag,
+            last_modified as lastModified
+       FROM panel_api_jsonl_response_cache
+      WHERE panel_id = ?
+        AND source_manifest_key = ?
+        AND source_index = ?
+        AND url = ?
+      LIMIT 1`).get(params.panelId, params.sourceManifestKey, params.sourceIndex, params.url);
+    return row ? { ...row, fetchedFromCache: true } : null;
+}
+function hasApiJsonlResponseCacheForAllSources(db, params) {
+    if (!db || params.sourceUrls.length === 0)
+        return false;
+    const lookup = db.prepare(`SELECT 1
+       FROM panel_api_jsonl_response_cache
+      WHERE panel_id = ?
+        AND source_manifest_key = ?
+        AND source_index = ?
+        AND url = ?
+      LIMIT 1`);
+    return params.sourceUrls.every((url, sourceIndex) => Boolean(lookup.get(params.panelId, params.sourceManifestKey, sourceIndex, url)));
+}
+function upsertApiJsonlResponseCache(db, params) {
+    const now = Date.now();
+    db.prepare(`INSERT INTO panel_api_jsonl_response_cache(
+       panel_id, source_manifest_key, source_index, url,
+       etag, last_modified, content_type, content, content_hash,
+       byte_length, row_count, fetched_at, updated_at
+     )
+     VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(panel_id, source_manifest_key, source_index, url)
+     DO UPDATE SET
+       etag = excluded.etag,
+       last_modified = excluded.last_modified,
+       content_type = excluded.content_type,
+       content = excluded.content,
+       content_hash = excluded.content_hash,
+       byte_length = excluded.byte_length,
+       row_count = excluded.row_count,
+       updated_at = excluded.updated_at`).run(params.panelId, params.sourceManifestKey, params.sourceIndex, params.url, params.source.etag, params.source.lastModified, params.source.contentType, params.source.content, params.source.contentHash, params.source.byteLength, params.source.rowCount, now, now);
+}
+export function pruneApiJsonlResponseCache(db, panelId, sourceManifestKey) {
+    const now = Date.now();
+    const ttlCutoff = now - PANEL_API_JSONL_RESPONSE_CACHE_TTL_MS;
+    const evictedKeys = new Set();
+    // Source-churn eviction: any manifest key other than the active one is stale.
+    const nonActiveKeys = db.prepare(`SELECT DISTINCT source_manifest_key
+       FROM panel_api_jsonl_response_cache
+      WHERE panel_id = ?
+        AND source_manifest_key != ?`).all(panelId, sourceManifestKey);
+    for (const row of nonActiveKeys) {
+        evictedKeys.add(row.source_manifest_key);
+    }
+    if (nonActiveKeys.length > 0) {
+        db.prepare(`DELETE FROM panel_api_jsonl_response_cache
+        WHERE panel_id = ?
+          AND source_manifest_key != ?`).run(panelId, sourceManifestKey);
+    }
+    // TTL eviction for the active manifest key (whole-source granularity).
+    const staleActiveKey = db.prepare(`SELECT source_manifest_key
+       FROM panel_api_jsonl_response_cache
+      WHERE panel_id = ?
+        AND source_manifest_key = ?
+      GROUP BY source_manifest_key
+     HAVING MAX(updated_at) < ?`).get(panelId, sourceManifestKey, ttlCutoff);
+    if (staleActiveKey) {
+        evictedKeys.add(staleActiveKey.source_manifest_key);
+        db.prepare(`DELETE FROM panel_api_jsonl_response_cache
+        WHERE panel_id = ?
+          AND source_manifest_key = ?`).run(panelId, staleActiveKey.source_manifest_key);
+    }
+    // Size-budget eviction, preserving the active manifest key until last.
+    let totalBytes = db.prepare(`SELECT COALESCE(SUM(byte_length), 0) as total
+       FROM panel_api_jsonl_response_cache
+      WHERE panel_id = ?`).get(panelId).total;
+    if (totalBytes > PANEL_API_JSONL_RESPONSE_CACHE_MAX_TOTAL_BYTES_PER_PANEL) {
+        const candidates = db.prepare(`SELECT source_manifest_key, SUM(byte_length) as byte_length
+         FROM panel_api_jsonl_response_cache
+        WHERE panel_id = ?
+        GROUP BY source_manifest_key
+        ORDER BY CASE WHEN source_manifest_key = ? THEN 1 ELSE 0 END ASC,
+                 MAX(updated_at) ASC,
+                 source_manifest_key ASC`).all(panelId, sourceManifestKey);
+        for (const candidate of candidates) {
+            if (totalBytes <= PANEL_API_JSONL_RESPONSE_CACHE_MAX_TOTAL_BYTES_PER_PANEL)
+                break;
+            if (evictedKeys.has(candidate.source_manifest_key))
+                continue;
+            db.prepare(`DELETE FROM panel_api_jsonl_response_cache
+          WHERE panel_id = ?
+            AND source_manifest_key = ?`).run(panelId, candidate.source_manifest_key);
+            totalBytes -= candidate.byte_length;
+            evictedKeys.add(candidate.source_manifest_key);
+        }
+    }
+    if (evictedKeys.size === 0)
+        return;
+    const keys = Array.from(evictedKeys);
+    const placeholders = keys.map(() => '?').join(',');
+    db.transaction(() => {
+        db.prepare(`DELETE FROM panel_query_handle_view_index_meta
+        WHERE panel_id = ? AND source_manifest_key IN (${placeholders})`).run(panelId, ...keys);
+        db.prepare(`DELETE FROM panel_query_handle_view_index_rows
+        WHERE panel_id = ? AND source_manifest_key IN (${placeholders})`).run(panelId, ...keys);
+        db.prepare(`DELETE FROM panel_query_handle_field_index_meta
+        WHERE panel_id = ? AND source_manifest_key IN (${placeholders})`).run(panelId, ...keys);
+        db.prepare(`DELETE FROM panel_query_handle_field_index_rows
+        WHERE panel_id = ? AND source_manifest_key IN (${placeholders})`).run(panelId, ...keys);
+    })();
+}
+function parseApiJsonlRowsFromSources(sources, datasetSchema) {
+    let rows = [];
+    for (const source of sources) {
+        rows = rows.concat(parseApiJsonlRows(source.content, datasetSchema, rows.length));
+    }
+    return rows;
+}
+async function selectApiJsonlRowsByIndices(sources, datasetSchema, rowIndices) {
+    const targetIndices = new Set(rowIndices);
+    if (targetIndices.size === 0)
+        return [];
+    const found = new Map();
+    let globalRowIndex = 0;
+    for (const source of sources) {
+        for (const line of source.content.split('\n')) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            if (targetIndices.has(globalRowIndex)) {
+                const rawRow = parseJsonlRow(trimmed, globalRowIndex);
+                found.set(globalRowIndex, buildPanelRowFromQueryRow(rawRow, globalRowIndex, datasetSchema));
+                if (found.size === targetIndices.size) {
+                    return rowIndices
+                        .map((rowIndex) => found.get(rowIndex))
+                        .filter((row) => Boolean(row));
+                }
+            }
+            globalRowIndex += 1;
+        }
+    }
+    return rowIndices
+        .map((rowIndex) => found.get(rowIndex))
+        .filter((row) => Boolean(row));
+}
+function parseApiJsonlRows(content, datasetSchema, startRowIndex = 0) {
+    const lines = content.split('\n').filter((line) => line.trim() !== '');
+    if (startRowIndex + lines.length > API_JSONL_MAX_ROWS) {
+        throw new PanelQueryHandleError(`api_jsonl response exceeds row limit (${API_JSONL_MAX_ROWS}).`, 413);
+    }
+    return lines.map((line, rowIndex) => {
+        const globalRowIndex = startRowIndex + rowIndex;
+        const rawRow = parseJsonlRow(line.trim(), globalRowIndex);
+        return buildPanelRowFromQueryRow(rawRow, globalRowIndex, datasetSchema);
+    });
+}
+function sliceRowsByPositionCursor(rows, startPosition, limit, encodeCursor) {
+    const start = Math.min(Math.max(0, startPosition), rows.length);
+    const resultRows = rows.slice(start, start + limit);
+    const nextPosition = start + resultRows.length;
+    return {
+        rows: resultRows,
+        nextCursor: nextPosition < rows.length ? encodeCursor(nextPosition) : null,
+    };
+}
+export async function listPanelQueryHandleRowsByIndices(params) {
+    const uniqueIndices = Array.from(new Set(params.rowIndices.filter((rowIndex) => Number.isInteger(rowIndex) && rowIndex >= 0)));
+    if (uniqueIndices.length === 0) {
+        return { rows: [], nextCursor: null };
+    }
+    const targetIndices = new Set(uniqueIndices);
+    const maxTargetIndex = Math.max(...uniqueIndices);
+    const found = new Map();
+    let cursor = await getIndexedCursorForDynamicRowIndices(params, Math.min(...uniqueIndices));
+    while (found.size < targetIndices.size) {
+        const result = await listPanelQueryHandleRows({
+            db: params.db,
+            panel: params.panel,
+            conversationManager: params.conversationManager,
+            workspaceBroker: params.workspaceBroker,
+            config: params.config,
+            apiJsonlAllowedOrigins: params.apiJsonlAllowedOrigins,
+            apiJsonlAllowedUrlPrefixes: params.apiJsonlAllowedUrlPrefixes,
+            apiJsonlAuthProfiles: params.apiJsonlAuthProfiles,
+            datasetSchema: params.datasetSchema,
+            options: {
+                cursor,
+                limit: 200,
+            },
+        });
+        for (const row of result.rows) {
+            if (targetIndices.has(row.rowIndex)) {
+                found.set(row.rowIndex, row);
+            }
+        }
+        const lastRowIndex = result.rows[result.rows.length - 1]?.rowIndex;
+        if (!result.nextCursor || lastRowIndex === undefined || lastRowIndex >= maxTargetIndex) {
+            break;
+        }
+        cursor = result.nextCursor;
+    }
+    return {
+        rows: params.rowIndices
+            .map((rowIndex) => found.get(rowIndex))
+            .filter((row) => Boolean(row)),
+        nextCursor: null,
+    };
+}
+function resolveQueryHandleDataSources(params) {
+    const parsed = parsePanelQueryHandle(params.handle);
+    return parsed.paths.map((sourcePath) => resolveQueryHandleDataSourcePath({
+        sourcePath,
+        workspaceRoot: params.workspaceRoot,
+        config: params.config,
+    }));
+}
+function resolveQueryHandleDataSourcePath(params) {
+    if (!path.isAbsolute(params.sourcePath)) {
+        return {
+            kind: 'workspace_relative',
+            relativePath: params.sourcePath,
+        };
+    }
+    const resolved = resolvePanelDatasetPath(params.workspaceRoot, params.sourcePath, params.config);
+    if (!resolved.ok) {
+        throw new PanelQueryHandleError(resolved.reason, 403);
+    }
+    return {
+        kind: 'absolute',
+        absolutePath: resolved.absolutePath,
+        allowedRoot: resolved.allowedRoot,
+    };
+}
+function createQueryHandleIndexContext(db, panelId, dataSources) {
+    if (!db || dataSources.length < 1)
+        return null;
+    const sourceKeys = dataSources.map((dataSource) => queryHandleSourceKey(dataSource));
+    return {
+        db,
+        panelId,
+        sourceManifestKey: JSON.stringify(sourceKeys),
+        sourceKeys,
+        metadataBySourceIndex: new Map(),
+    };
+}
+async function getIndexedCursorForDynamicRowIndices(params, minTargetIndex) {
+    if (params.panel.datasetSource?.kind === 'api_jsonl') {
+        return getIndexedCursorForApiJsonlRowIndices(params, minTargetIndex);
+    }
+    return getIndexedCursorForQueryHandleRowIndices(params, minTargetIndex);
+}
+async function getIndexedCursorForQueryHandleRowIndices(params, minTargetIndex) {
+    if (!params.db || minTargetIndex <= 0 || params.panel.datasetSource?.kind !== 'query_handle') {
+        return null;
+    }
+    const agent = params.conversationManager.getAgent(params.panel.agentId);
+    if (!agent?.nodeId || !agent.workspacePath || !params.workspaceBroker) {
+        return null;
+    }
+    const dataSources = resolveQueryHandleDataSources({
+        handle: params.panel.datasetSource.handle,
+        workspaceRoot: agent.workspacePath,
+        config: params.config,
+    });
+    const indexContext = createQueryHandleIndexContext(params.db, params.panel.id, dataSources);
+    if (!indexContext)
+        return null;
+    const existing = selectNearestQueryHandleCheckpoint(indexContext, minTargetIndex);
+    if (!existing)
+        return null;
+    const sourceRows = listIndexedQueryHandleSources(indexContext);
+    if (!hasIndexedRowsForEveryQueryHandleSource(indexContext, sourceRows))
+        return null;
+    for (let sourceIndex = 0; sourceIndex < dataSources.length; sourceIndex += 1) {
+        const metadataChunk = await readQueryHandleChunk({
+            workspaceBroker: params.workspaceBroker,
+            nodeId: agent.nodeId,
+            workspaceRoot: agent.workspacePath,
+            dataSource: dataSources[sourceIndex],
+            offset: 0,
+            limit: 1,
+        });
+        if (!ensureQueryHandleIndexMetadataFresh(indexContext, sourceIndex, metadataChunk)) {
+            return null;
+        }
+    }
+    const fresh = selectNearestQueryHandleCheckpoint(indexContext, minTargetIndex);
+    if (!fresh)
+        return null;
+    return encodeQueryHandleCursor({
+        sourceIndex: fresh.sourceIndex,
+        offset: fresh.byteOffset,
+        rowIndex: fresh.rowIndex,
+    });
+}
+async function getIndexedCursorForApiJsonlRowIndices(params, minTargetIndex) {
+    if (!params.db || minTargetIndex <= 0 || params.panel.datasetSource?.kind !== 'api_jsonl') {
+        return null;
+    }
+    const agent = params.conversationManager.getAgent(params.panel.agentId);
+    if (!agent?.nodeId || !params.workspaceBroker)
+        return null;
+    const parsed = parsePanelApiJsonlUrls(params.panel.datasetSource, {
+        allowedOrigins: params.apiJsonlAllowedOrigins,
+        allowedUrlPrefixes: params.apiJsonlAllowedUrlPrefixes,
+        allowedAuthProfiles: params.apiJsonlAuthProfiles,
+    });
+    const indexContext = createApiJsonlIndexContext(params.db, params.panel.id, parsed.urls, parsed.authProfile);
+    if (!indexContext)
+        return null;
+    const existing = selectNearestQueryHandleCheckpoint(indexContext, minTargetIndex);
+    if (!existing)
+        return null;
+    const sourceRows = listIndexedQueryHandleSources(indexContext);
+    if (!hasIndexedRowsThroughSource(indexContext, sourceRows, existing.sourceIndex))
+        return null;
+    const sourceMetadata = new Map();
+    for (let sourceIndex = 0; sourceIndex <= existing.sourceIndex; sourceIndex += 1) {
+        const metadata = await readApiJsonlRangeMetadata({
+            workspaceBroker: params.workspaceBroker,
+            nodeId: agent.nodeId,
+            url: parsed.urls[sourceIndex],
+            authProfile: parsed.authProfile,
+        });
+        if (!metadata)
+            return null;
+        sourceMetadata.set(sourceIndex, metadata);
+        if (!ensureQueryHandleIndexMetadataFresh(indexContext, sourceIndex, metadata.chunk)) {
+            return null;
+        }
+    }
+    const fresh = selectNearestQueryHandleCheckpoint(indexContext, minTargetIndex);
+    if (!fresh)
+        return null;
+    const metadata = sourceMetadata.get(fresh.sourceIndex);
+    if (!metadata)
+        return null;
+    return encodeApiJsonlRangeCursor({
+        sourceKind: 'api_jsonl_range',
+        sourceIndex: fresh.sourceIndex,
+        offset: fresh.byteOffset,
+        rowIndex: fresh.rowIndex,
+        url: parsed.urls[fresh.sourceIndex],
+        etag: metadata.etag,
+        lastModified: metadata.lastModified,
+        totalSize: metadata.totalSize,
+    });
+}
+function queryHandleSourceKey(dataSource) {
+    return dataSource.kind === 'workspace_relative'
+        ? `workspace:${dataSource.relativePath}`
+        : `absolute:${dataSource.absolutePath}`;
+}
+function selectNearestQueryHandleCheckpoint(context, targetRowIndex) {
+    const row = context.db.prepare(`SELECT source_index as sourceIndex, row_index as rowIndex, byte_offset as byteOffset
+     FROM panel_query_handle_index
+     WHERE panel_id = ?
+       AND source_manifest_key = ?
+       AND row_index <= ?
+     ORDER BY row_index DESC
+     LIMIT 1`).get(context.panelId, context.sourceManifestKey, targetRowIndex);
+    if (!row
+        || !Number.isInteger(row.sourceIndex)
+        || !Number.isInteger(row.rowIndex)
+        || !Number.isInteger(row.byteOffset)
+        || context.sourceKeys[row.sourceIndex] == null) {
+        return null;
+    }
+    return row;
+}
+function listIndexedQueryHandleSources(context) {
+    return context.db.prepare(`SELECT source_index as sourceIndex, source_key as sourceKey
+       FROM panel_query_handle_index
+      WHERE panel_id = ?
+        AND source_manifest_key = ?
+      GROUP BY source_index, source_key
+      ORDER BY source_index ASC`).all(context.panelId, context.sourceManifestKey);
+}
+function hasIndexedRowsForEveryQueryHandleSource(context, rows) {
+    const bySourceIndex = new Map(rows.map((row) => [row.sourceIndex, row.sourceKey]));
+    return context.sourceKeys.every((sourceKey, sourceIndex) => bySourceIndex.get(sourceIndex) === sourceKey);
+}
+function hasIndexedRowsThroughSource(context, rows, maxSourceIndex) {
+    const bySourceIndex = new Map(rows.map((row) => [row.sourceIndex, row.sourceKey]));
+    for (let sourceIndex = 0; sourceIndex <= maxSourceIndex; sourceIndex += 1) {
+        if (bySourceIndex.get(sourceIndex) !== context.sourceKeys[sourceIndex])
+            return false;
+    }
+    return true;
+}
+async function readApiJsonlRangeMetadata(params) {
+    const result = await params.workspaceBroker.fetchHttpText(params.nodeId, params.url, {
+        maxBytes: API_JSONL_MAX_BYTES,
+        ...(params.authProfile ? { authProfile: params.authProfile } : {}),
+        rangeStart: 0,
+        rangeLength: 1,
+    });
+    if (result.status !== 206
+        || result.partialContent !== true
+        || result.rangeStart !== 0) {
+        return null;
+    }
+    const chunk = apiJsonlRangeCheckpointChunk(result);
+    if (!chunk || chunk.modifiedAt == null)
+        return null;
+    return {
+        chunk,
+        etag: result.etag ?? null,
+        lastModified: result.lastModified ?? null,
+        totalSize: chunk.size,
+    };
+}
+async function ensureApiJsonlRangeFieldIndex(params) {
+    if (!params.db || !params.indexContext)
+        return null;
+    const fieldSchemaKey = queryHandleFieldIndexSchemaKey(params.datasetSchema, params.extraFieldNames);
+    if (!fieldSchemaKey)
+        return null;
+    const sourceMetadata = [];
+    for (const [sourceIndex, url] of params.sourceUrls.entries()) {
+        const metadata = await readApiJsonlRangeMetadata({
+            workspaceBroker: params.workspaceBroker,
+            nodeId: params.nodeId,
+            url,
+            authProfile: params.authProfile,
+        });
+        if (!metadata)
+            return null;
+        sourceMetadata.push(metadata);
+        if (!ensureQueryHandleIndexMetadataFresh(params.indexContext, sourceIndex, metadata.chunk)) {
+            return null;
+        }
+    }
+    const metadataKey = apiJsonlRangeMetadataKey(params.sourceUrls, sourceMetadata);
+    const existing = params.db.prepare(`SELECT 1
+       FROM panel_query_handle_field_index_meta
+      WHERE panel_id = ?
+        AND source_manifest_key = ?
+        AND metadata_key = ?
+        AND field_schema_key = ?
+      LIMIT 1`).get(params.panel.id, params.indexContext.sourceManifestKey, metadataKey, fieldSchemaKey);
+    if (existing)
+        return metadataKey;
+    const rows = await scanApiJsonlRowsForFieldIndexByRange({
+        panel: params.panel,
+        sourceUrls: params.sourceUrls,
+        authProfile: params.authProfile,
+        workspaceBroker: params.workspaceBroker,
+        nodeId: params.nodeId,
+        datasetSchema: params.datasetSchema,
+        indexContext: params.indexContext,
+        sourceMetadata,
+    });
+    if (!rows)
+        return null;
+    writeQueryHandleFieldIndexRows({
+        context: params.indexContext,
+        metadataKey,
+        datasetSchema: params.datasetSchema,
+        rows,
+        extraFieldNames: params.extraFieldNames,
+    });
+    return metadataKey;
+}
+function apiJsonlRangeMetadataKey(sourceUrls, metadata) {
+    return JSON.stringify(metadata.map((source, sourceIndex) => ({
+        url: sourceUrls[sourceIndex],
+        byteLength: source.totalSize,
+        etag: source.etag,
+        lastModified: source.lastModified,
+    })));
+}
+async function scanApiJsonlRowsForFieldIndexByRange(params) {
+    void params.panel;
+    const rows = [];
+    let rowIndex = 0;
+    let chunks = 0;
+    const sourceSawRows = new Set();
+    for (const [sourceIndex, url] of params.sourceUrls.entries()) {
+        const metadata = params.sourceMetadata[sourceIndex];
+        if (!metadata)
+            return null;
+        let offset = 0;
+        let hasMore = true;
+        const currentValidator = {
+            url,
+            etag: metadata.etag,
+            lastModified: metadata.lastModified,
+            totalSize: metadata.totalSize,
+        };
+        while (hasMore) {
+            chunks += 1;
+            if (chunks > API_JSONL_MAX_RANGE_CHUNKS_PER_INDEX) {
+                throw new PanelQueryHandleError('api_jsonl range index scan exceeded the per-request work limit.', 413);
+            }
+            const result = await params.workspaceBroker.fetchHttpText(params.nodeId, url, {
+                maxBytes: API_JSONL_MAX_BYTES,
+                ...(params.authProfile ? { authProfile: params.authProfile } : {}),
+                rangeStart: offset,
+                rangeLength: API_JSONL_RANGE_CHUNK_BYTES,
+                ...withApiJsonlIfRange(currentValidator),
+            });
+            if (result.status !== 206
+                || result.partialContent !== true
+                || typeof result.rangeStart !== 'number'
+                || typeof result.rangeEnd !== 'number'
+                || result.rangeStart !== offset) {
+                return null;
+            }
+            const checkpointChunk = apiJsonlRangeCheckpointChunk(result);
+            if (!checkpointChunk || !ensureQueryHandleIndexMetadataFresh(params.indexContext, sourceIndex, checkpointChunk)) {
+                return null;
+            }
+            const parsed = parseCompleteJsonlLines(result.content, Boolean(result.hasMore));
+            if (parsed.completeText.length === 0 && result.hasMore) {
+                throw new PanelQueryHandleError('api_jsonl JSONL row exceeds the per-row size limit.', 413);
+            }
+            const baseOffset = result.rangeStart;
+            let consumedBytes = 0;
+            for (const line of parsed.lines) {
+                const lineStartOffset = baseOffset + consumedBytes;
+                consumedBytes += line.byteLength;
+                const trimmed = line.text.trim();
+                if (!trimmed)
+                    continue;
+                if (rowIndex >= API_JSONL_MAX_ROWS) {
+                    throw new PanelQueryHandleError(`api_jsonl response exceeds row limit (${API_JSONL_MAX_ROWS}).`, 413);
+                }
+                const rawRow = parseJsonlRow(trimmed, rowIndex);
+                const row = buildPanelRowFromQueryRow(rawRow, rowIndex, params.datasetSchema);
+                const isSourceStart = !sourceSawRows.has(sourceIndex);
+                sourceSawRows.add(sourceIndex);
+                recordApiJsonlRangeCheckpoint(params.indexContext, {
+                    sourceIndex,
+                    chunk: checkpointChunk,
+                    rowIndex,
+                    byteOffset: lineStartOffset,
+                    isSourceStart,
+                });
+                rows.push({ rowIndex: row.rowIndex, fields: row.fields });
+                rowIndex += 1;
+            }
+            offset = baseOffset + consumedBytes;
+            hasMore = result.hasMore === true;
+            if (parsed.lines.length === 0 && !hasMore)
+                break;
+        }
+    }
+    return rows;
+}
+function queryHandleViewIndexQueryKey(options) {
+    return JSON.stringify({
+        sortField: options.sortField ?? null,
+        sortDirection: options.sortDirection ?? null,
+        sortFieldType: options.sortFieldType ?? null,
+        filterField: options.filterField ?? null,
+        filterValue: options.filterValue ?? null,
+    });
+}
+function parseQueryHandleViewIndexCursorRequest(queryKey) {
+    try {
+        const parsed = JSON.parse(queryKey);
+        if (typeof parsed.sortField !== 'string')
+            return null;
+        if (parsed.sortDirection !== 'asc' && parsed.sortDirection !== 'desc')
+            return null;
+        return {
+            sortField: parsed.sortField,
+            sortDirection: parsed.sortDirection,
+            ...(typeof parsed.filterField === 'string' ? { filterField: parsed.filterField } : {}),
+            ...(parsed.filterValue !== null && parsed.filterValue !== undefined ? { filterValue: parsed.filterValue } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+async function loadQueryHandleIndexMetadataKey(params) {
+    for (let sourceIndex = 0; sourceIndex < params.dataSources.length; sourceIndex += 1) {
+        const existing = params.context.metadataBySourceIndex.get(sourceIndex);
+        if (existing)
+            continue;
+        const metadataChunk = await readQueryHandleChunk({
+            workspaceBroker: params.workspaceBroker,
+            nodeId: params.nodeId,
+            workspaceRoot: params.workspaceRoot,
+            dataSource: params.dataSources[sourceIndex],
+            offset: 0,
+            limit: 1,
+        });
+        if (!ensureQueryHandleIndexMetadataFresh(params.context, sourceIndex, metadataChunk)) {
+            return null;
+        }
+    }
+    const metadata = params.context.sourceKeys.map((sourceKey, sourceIndex) => {
+        const sourceMetadata = params.context.metadataBySourceIndex.get(sourceIndex);
+        return sourceMetadata ? {
+            sourceKey,
+            fileSize: sourceMetadata.fileSize,
+            modifiedAt: sourceMetadata.modifiedAt,
+        } : null;
+    });
+    return metadata.every(Boolean) ? JSON.stringify(metadata) : null;
+}
+async function readCachedQueryHandleViewIndexRows(params) {
+    if (!params.db)
+        return null;
+    const meta = params.db.prepare(`SELECT total_count as totalCount
+       FROM panel_query_handle_view_index_meta
+      WHERE panel_id = ?
+        AND source_manifest_key = ?
+        AND query_key = ?
+        AND metadata_key = ?`).get(params.panel.id, params.sourceManifestKey, params.queryKey, params.metadataKey);
+    if (!meta || !Number.isInteger(meta.totalCount) || meta.totalCount < 0)
+        return null;
+    const start = Math.min(Math.max(0, params.position), meta.totalCount);
+    const expectedRows = Math.min(params.limit, Math.max(0, meta.totalCount - start));
+    if (expectedRows === 0) {
+        return { rows: [], nextCursor: null };
+    }
+    const indexRows = params.db.prepare(`SELECT row_index as rowIndex
+       FROM panel_query_handle_view_index_rows
+      WHERE panel_id = ?
+        AND source_manifest_key = ?
+        AND query_key = ?
+        AND metadata_key = ?
+        AND position >= ?
+      ORDER BY position ASC
+      LIMIT ?`).all(params.panel.id, params.sourceManifestKey, params.queryKey, params.metadataKey, start, expectedRows);
+    if (indexRows.length !== expectedRows || indexRows.some((row) => !Number.isInteger(row.rowIndex))) {
+        return null;
+    }
+    const rowIndices = indexRows.map((row) => row.rowIndex);
+    const selectedRows = params.selectRowsByIndices
+        ? await params.selectRowsByIndices(rowIndices)
+        : (await listPanelQueryHandleRowsByIndices({
+            db: params.db,
+            panel: params.panel,
+            conversationManager: params.conversationManager,
+            workspaceBroker: params.workspaceBroker,
+            config: params.config,
+            datasetSchema: params.datasetSchema,
+            rowIndices,
+        })).rows;
+    if (selectedRows.length !== indexRows.length)
+        return null;
+    const nextPosition = start + selectedRows.length;
+    const cursorRequest = parseQueryHandleViewIndexCursorRequest(params.queryKey);
+    if (!cursorRequest)
+        return null;
+    return {
+        rows: selectedRows,
+        nextCursor: nextPosition < meta.totalCount
+            ? encodeQueryHandleSortCursor({
+                position: nextPosition,
+                ...cursorRequest,
+            })
+            : null,
+    };
+}
+function writeQueryHandleViewIndexRows(params) {
+    const now = Date.now();
+    const deleteMeta = params.context.db.prepare(`DELETE FROM panel_query_handle_view_index_meta
+      WHERE panel_id = ?
+        AND source_manifest_key = ?
+        AND query_key = ?`);
+    const deleteRows = params.context.db.prepare(`DELETE FROM panel_query_handle_view_index_rows
+      WHERE panel_id = ?
+        AND source_manifest_key = ?
+        AND query_key = ?`);
+    const insertMeta = params.context.db.prepare(`INSERT INTO panel_query_handle_view_index_meta(
+       panel_id, source_manifest_key, query_key, metadata_key,
+       total_count, created_at, updated_at
+     )
+     VALUES(?, ?, ?, ?, ?, ?, ?)`);
+    const insertRow = params.context.db.prepare(`INSERT INTO panel_query_handle_view_index_rows(
+       panel_id, source_manifest_key, query_key, metadata_key,
+       position, row_index, created_at
+     )
+     VALUES(?, ?, ?, ?, ?, ?, ?)`);
+    params.context.db.transaction(() => {
+        deleteRows.run(params.context.panelId, params.context.sourceManifestKey, params.queryKey);
+        deleteMeta.run(params.context.panelId, params.context.sourceManifestKey, params.queryKey);
+        insertMeta.run(params.context.panelId, params.context.sourceManifestKey, params.queryKey, params.metadataKey, params.rowIndices.length, now, now);
+        params.rowIndices.forEach((rowIndex, position) => {
+            insertRow.run(params.context.panelId, params.context.sourceManifestKey, params.queryKey, params.metadataKey, position, rowIndex, now);
+        });
+    })();
+}
+function aggregateFieldIndexNames(options) {
+    return Array.from(new Set([
+        ...(options.field ? [options.field] : []),
+        ...(options.filterField ? [options.filterField] : []),
+    ]));
+}
+async function scanQueryHandleRowsForFieldIndex(params) {
+    const rows = [];
+    let rowIndex = 0;
+    let chunks = 0;
+    const sourceSawRows = new Set();
+    for (let sourceIndex = 0; sourceIndex < params.dataSources.length; sourceIndex += 1) {
+        const dataSource = params.dataSources[sourceIndex];
+        let offset = 0;
+        let hasMore = true;
+        while (hasMore) {
+            chunks += 1;
+            if (chunks > QUERY_HANDLE_MAX_CHUNKS_PER_SORT) {
+                throw new PanelQueryHandleError('query_handle aggregate scan exceeded the per-request work limit.', 413);
+            }
+            const chunk = await readQueryHandleChunk({
+                workspaceBroker: params.workspaceBroker,
+                nodeId: params.nodeId,
+                workspaceRoot: params.workspaceRoot,
+                dataSource,
+                offset,
+                limit: QUERY_HANDLE_READ_CHUNK_BYTES,
+            });
+            const content = chunk.content ?? '';
+            const parsed = parseCompleteJsonlLines(content, Boolean(chunk.hasMore));
+            if (parsed.completeText.length === 0 && chunk.hasMore) {
+                throw new PanelQueryHandleError('query_handle JSONL row exceeds the per-row size limit.', 413);
+            }
+            const baseOffset = chunk.offset ?? offset;
+            let consumedBytes = 0;
+            for (const line of parsed.lines) {
+                const lineStartOffset = baseOffset + consumedBytes;
+                consumedBytes += line.byteLength;
+                const trimmed = line.text.trim();
+                if (!trimmed)
+                    continue;
+                const rawRow = parseJsonlRow(trimmed, rowIndex);
+                const row = buildPanelRowFromQueryRow(rawRow, rowIndex, params.datasetSchema);
+                const isSourceStart = !sourceSawRows.has(sourceIndex);
+                sourceSawRows.add(sourceIndex);
+                recordQueryHandleCheckpoint(params.indexContext, {
+                    sourceIndex,
+                    chunk,
+                    rowIndex,
+                    byteOffset: lineStartOffset,
+                    isSourceStart,
+                });
+                rows.push({ rowIndex: row.rowIndex, fields: row.fields });
+                rowIndex += 1;
+            }
+            offset = baseOffset + consumedBytes;
+            hasMore = offset < chunk.size;
+            if (parsed.lines.length === 0 && !hasMore)
+                break;
+        }
+    }
+    if (params.indexContext && params.metadataKey) {
+        writeQueryHandleFieldIndexRows({
+            context: params.indexContext,
+            metadataKey: params.metadataKey,
+            datasetSchema: params.datasetSchema,
+            rows,
+            extraFieldNames: params.extraFieldNames,
+        });
+    }
+    return rows;
+}
+function queryHandleFieldIndexFields(datasetSchema, extraFieldNames = []) {
+    const extraFields = new Set(extraFieldNames);
+    return (datasetSchema?.fields ?? []).filter((field) => field.filterable || field.sortable || extraFields.has(field.name));
+}
+function queryHandleFieldIndexSchemaKey(datasetSchema, extraFieldNames = []) {
+    const fields = queryHandleFieldIndexFields(datasetSchema, extraFieldNames);
+    if (fields.length === 0)
+        return null;
+    return JSON.stringify(fields.map((field) => ({
+        name: field.name,
+        type: field.type,
+        filterable: Boolean(field.filterable),
+        sortable: Boolean(field.sortable),
+    })));
+}
+function readAggregateFromQueryHandleFieldIndex(params) {
+    if (!params.db)
+        return null;
+    void params.sourceKind;
+    const fieldSchemaKey = queryHandleFieldIndexSchemaKey(params.datasetSchema, params.extraFieldNames);
+    if (!fieldSchemaKey)
+        return null;
+    const meta = params.db.prepare(`SELECT row_count as rowCount
+       FROM panel_query_handle_field_index_meta
+      WHERE panel_id = ?
+        AND source_manifest_key = ?
+        AND metadata_key = ?
+        AND field_schema_key = ?`).get(params.panel.id, params.sourceManifestKey, params.metadataKey, fieldSchemaKey);
+    if (!meta || !Number.isInteger(meta.rowCount) || meta.rowCount < 0)
+        return null;
+    const filterField = getQueryHandleIndexedField(params.datasetSchema, params.options.filterField, 'filter');
+    if (params.options.filterField && !filterField)
+        return null;
+    const filter = filterField && params.options.filterValue !== undefined
+        ? normalizeQueryHandleIndexedValue(filterField, params.options.filterValue)
+        : null;
+    if (filterField && !filter?.hasValue) {
+        return emptyAggregateResult(params.options);
+    }
+    const totalCount = filterField && filter
+        ? countRowsMatchingQueryHandleFieldFilter({
+            db: params.db,
+            panelId: params.panel.id,
+            sourceManifestKey: params.sourceManifestKey,
+            metadataKey: params.metadataKey,
+            fieldSchemaKey,
+            filterField,
+            filter,
+        })
+        : meta.rowCount;
+    if (params.options.op === 'count' && !params.options.field) {
+        return {
+            op: params.options.op,
+            field: null,
+            value: totalCount,
+            count: totalCount,
+            totalCount,
+            hasValue: true,
+        };
+    }
+    if (!params.options.field)
+        return emptyAggregateResult(params.options, totalCount);
+    const aggregateField = (params.datasetSchema?.fields ?? []).find((field) => field.name === params.options.field);
+    if (!aggregateField)
+        return null;
+    if (!filterField && params.options.filterValue === undefined) {
+        const summary = readAggregateFromQueryHandleAggregateIndex({
+            db: params.db,
+            panelId: params.panel.id,
+            sourceManifestKey: params.sourceManifestKey,
+            metadataKey: params.metadataKey,
+            fieldSchemaKey,
+            aggregateField,
+            op: params.options.op,
+        });
+        if (summary) {
+            return {
+                op: params.options.op,
+                field: aggregateField.name,
+                value: summary.value,
+                count: summary.count,
+                totalCount,
+                hasValue: params.options.op === 'count' || summary.value !== null,
+            };
+        }
+    }
+    const aggregate = queryAggregateFieldIndexRows({
+        db: params.db,
+        panelId: params.panel.id,
+        sourceManifestKey: params.sourceManifestKey,
+        metadataKey: params.metadataKey,
+        fieldSchemaKey,
+        aggregateField,
+        filterField,
+        filter,
+        op: params.options.op,
+    });
+    return {
+        op: params.options.op,
+        field: aggregateField.name,
+        value: aggregate.value,
+        count: aggregate.count,
+        totalCount,
+        hasValue: params.options.op === 'count' || aggregate.value !== null,
+    };
+}
+function readAggregateFromQueryHandleAggregateIndex(params) {
+    const row = params.db.prepare(`SELECT value_count as valueCount,
+            non_empty_count as nonEmptyCount,
+            numeric_count as numericCount,
+            numeric_sum as numericSum,
+            numeric_min as numericMin,
+            numeric_max as numericMax
+       FROM panel_query_handle_field_aggregate_index
+      WHERE panel_id = ?
+        AND source_manifest_key = ?
+        AND metadata_key = ?
+        AND field_schema_key = ?
+        AND field_name = ?
+      LIMIT 1`).get(params.panelId, params.sourceManifestKey, params.metadataKey, params.fieldSchemaKey, params.aggregateField.name);
+    if (!row)
+        return null;
+    if (params.op === 'count') {
+        const count = params.aggregateField.type === 'string' ? row.nonEmptyCount : row.valueCount;
+        return { value: count, count };
+    }
+    if (params.aggregateField.type !== 'number' || row.numericCount <= 0) {
+        return { value: null, count: 0 };
+    }
+    if (params.op === 'sum')
+        return { value: row.numericSum, count: row.numericCount };
+    if (params.op === 'avg')
+        return { value: row.numericSum / row.numericCount, count: row.numericCount };
+    if (params.op === 'min')
+        return { value: row.numericMin, count: row.numericCount };
+    return { value: row.numericMax, count: row.numericCount };
+}
+function emptyAggregateResult(options, totalCount = 0) {
+    if (options.op === 'count') {
+        return {
+            op: options.op,
+            field: options.field ?? null,
+            value: 0,
+            count: 0,
+            totalCount,
+            hasValue: true,
+        };
+    }
+    return {
+        op: options.op,
+        field: options.field ?? null,
+        value: null,
+        count: 0,
+        totalCount,
+        hasValue: false,
+    };
+}
+function countRowsMatchingQueryHandleFieldFilter(params) {
+    const filterColumn = queryHandleFieldValueColumn(params.filterField);
+    const filterValue = filterColumn === 'string_value'
+        ? params.filter.stringValue
+        : filterColumn === 'number_value'
+            ? params.filter.numberValue
+            : params.filter.booleanValue;
+    const row = params.db.prepare(`SELECT COUNT(*) as totalCount
+       FROM panel_query_handle_field_index_rows
+      WHERE panel_id = ?
+        AND source_manifest_key = ?
+        AND metadata_key = ?
+        AND field_schema_key = ?
+        AND field_name = ?
+        AND has_value = 1
+        AND ${filterColumn} = ?`).get(params.panelId, params.sourceManifestKey, params.metadataKey, params.fieldSchemaKey, params.filterField.name, filterValue);
+    return row?.totalCount ?? 0;
+}
+function queryAggregateFieldIndexRows(params) {
+    const filterColumn = params.filterField ? queryHandleFieldValueColumn(params.filterField) : null;
+    const filterValue = params.filterField && params.filter && filterColumn
+        ? filterColumn === 'string_value'
+            ? params.filter.stringValue
+            : filterColumn === 'number_value'
+                ? params.filter.numberValue
+                : params.filter.booleanValue
+        : null;
+    const filterJoin = params.filterField
+        ? `JOIN panel_query_handle_field_index_rows f
+         ON f.panel_id = a.panel_id
+        AND f.source_manifest_key = a.source_manifest_key
+        AND f.metadata_key = a.metadata_key
+        AND f.field_schema_key = a.field_schema_key
+        AND f.row_index = a.row_index
+        AND f.field_name = ?`
+        : '';
+    const filterWhere = params.filterField && filterColumn
+        ? `AND f.has_value = 1 AND f.${filterColumn} = ?`
+        : '';
+    const filterParams = params.filterField && filterValue !== null
+        ? [params.filterField.name, filterValue]
+        : [];
+    const nonEmptyPredicate = params.aggregateField.type === 'string'
+        ? "a.has_value = 1 AND trim(a.string_value) != ''"
+        : 'a.has_value = 1';
+    const aggregatePredicate = params.op === 'count'
+        ? nonEmptyPredicate
+        : "a.has_value = 1 AND a.field_type = 'number'";
+    const aggregateExpression = params.op === 'count'
+        ? 'COUNT(*)'
+        : params.op === 'avg'
+            ? 'AVG(a.number_value)'
+            : `${params.op.toUpperCase()}(a.number_value)`;
+    const sql = `
+    SELECT ${aggregateExpression} as value, COUNT(*) as count
+      FROM panel_query_handle_field_index_rows a
+      ${filterJoin}
+     WHERE a.panel_id = ?
+       AND a.source_manifest_key = ?
+       AND a.metadata_key = ?
+       AND a.field_schema_key = ?
+       AND a.field_name = ?
+       AND ${aggregatePredicate}
+       ${filterWhere}`;
+    const paramsForQuery = params.filterField
+        ? [
+            ...filterParams.slice(0, 1),
+            params.panelId,
+            params.sourceManifestKey,
+            params.metadataKey,
+            params.fieldSchemaKey,
+            params.aggregateField.name,
+            ...filterParams.slice(1),
+        ]
+        : [
+            params.panelId,
+            params.sourceManifestKey,
+            params.metadataKey,
+            params.fieldSchemaKey,
+            params.aggregateField.name,
+        ];
+    const row = params.db.prepare(sql).get(...paramsForQuery);
+    const value = typeof row?.value === 'number' && Number.isFinite(row.value) ? row.value : null;
+    return {
+        value: params.op === 'count' ? (row?.count ?? 0) : value,
+        count: row?.count ?? 0,
+    };
+}
+function getQueryHandleIndexedField(datasetSchema, fieldName, purpose) {
+    if (!fieldName)
+        return null;
+    const field = (datasetSchema?.fields ?? []).find((candidate) => candidate.name === fieldName);
+    if (!field)
+        return null;
+    if (purpose === 'filter' && !field.filterable)
+        return null;
+    if (purpose === 'sort' && !field.sortable)
+        return null;
+    return field;
+}
+function queryHandleFieldValueColumn(field) {
+    if (field.type === 'number')
+        return 'number_value';
+    if (field.type === 'boolean')
+        return 'boolean_value';
+    return 'string_value';
+}
+function normalizeQueryHandleIndexedValue(field, value) {
+    if (field.type === 'number') {
+        return typeof value === 'number' && Number.isFinite(value)
+            ? { hasValue: 1, stringValue: '', numberValue: value, booleanValue: 0 }
+            : { hasValue: 0, stringValue: '', numberValue: 0, booleanValue: 0 };
+    }
+    if (field.type === 'boolean') {
+        return typeof value === 'boolean'
+            ? { hasValue: 1, stringValue: '', numberValue: 0, booleanValue: value ? 1 : 0 }
+            : { hasValue: 0, stringValue: '', numberValue: 0, booleanValue: 0 };
+    }
+    return typeof value === 'string'
+        ? { hasValue: 1, stringValue: value, numberValue: 0, booleanValue: 0 }
+        : { hasValue: 0, stringValue: '', numberValue: 0, booleanValue: 0 };
+}
+async function readQueryHandleRowsFromFieldIndex(params) {
+    if (!params.db || !params.options.sortField || !params.options.sortDirection)
+        return null;
+    const fieldSchemaKey = queryHandleFieldIndexSchemaKey(params.datasetSchema);
+    if (!fieldSchemaKey)
+        return null;
+    const sortField = getQueryHandleIndexedField(params.datasetSchema, params.options.sortField, 'sort');
+    if (!sortField)
+        return null;
+    const filterField = getQueryHandleIndexedField(params.datasetSchema, params.options.filterField, 'filter');
+    if (params.options.filterField && !filterField)
+        return null;
+    const meta = params.db.prepare(`SELECT row_count as rowCount
+       FROM panel_query_handle_field_index_meta
+      WHERE panel_id = ?
+        AND source_manifest_key = ?
+        AND metadata_key = ?
+        AND field_schema_key = ?`).get(params.panel.id, params.sourceManifestKey, params.metadataKey, fieldSchemaKey);
+    if (!meta || !Number.isInteger(meta.rowCount) || meta.rowCount < 0)
+        return null;
+    const sortColumn = queryHandleFieldValueColumn(sortField);
+    const sortDirection = params.options.sortDirection === 'desc' ? 'DESC' : 'ASC';
+    const tieDirection = params.options.sortDirection === 'desc' ? 'DESC' : 'ASC';
+    const start = Math.max(0, params.position);
+    const filter = filterField && params.options.filterValue !== undefined
+        ? normalizeQueryHandleIndexedValue(filterField, params.options.filterValue)
+        : null;
+    if (filterField && !filter?.hasValue)
+        return { rows: [], nextCursor: null };
+    const filterColumn = filterField ? queryHandleFieldValueColumn(filterField) : null;
+    const baseParams = [
+        params.panel.id,
+        params.sourceManifestKey,
+        params.metadataKey,
+        fieldSchemaKey,
+        sortField.name,
+    ];
+    const filterJoin = filterField
+        ? `JOIN panel_query_handle_field_index_rows f
+         ON f.panel_id = s.panel_id
+        AND f.source_manifest_key = s.source_manifest_key
+        AND f.metadata_key = s.metadata_key
+        AND f.field_schema_key = s.field_schema_key
+        AND f.row_index = s.row_index
+        AND f.field_name = ?`
+        : '';
+    const filterWhere = filterField && filterColumn && filter
+        ? `AND f.has_value = 1 AND f.${filterColumn} = ?`
+        : '';
+    const filterParams = filterField && filterColumn && filter
+        ? [filterField.name, filterColumn === 'string_value' ? filter.stringValue : filterColumn === 'number_value' ? filter.numberValue : filter.booleanValue]
+        : [];
+    const countSql = `
+    SELECT COUNT(*) as totalCount
+      FROM panel_query_handle_field_index_rows s
+      ${filterJoin}
+     WHERE s.panel_id = ?
+       AND s.source_manifest_key = ?
+       AND s.metadata_key = ?
+       AND s.field_schema_key = ?
+       AND s.field_name = ?
+       ${filterWhere}`;
+    const countParams = filterField
+        ? [...filterParams.slice(0, 1), ...baseParams, ...filterParams.slice(1)]
+        : baseParams;
+    const count = params.db.prepare(countSql).get(...countParams);
+    const totalCount = count?.totalCount ?? 0;
+    if (totalCount <= start)
+        return { rows: [], nextCursor: null };
+    const rowSql = `
+    SELECT s.row_index as rowIndex
+      FROM panel_query_handle_field_index_rows s
+      ${filterJoin}
+     WHERE s.panel_id = ?
+       AND s.source_manifest_key = ?
+       AND s.metadata_key = ?
+       AND s.field_schema_key = ?
+       AND s.field_name = ?
+       ${filterWhere}
+     ORDER BY s.${sortColumn} ${sortDirection}, s.row_index ${tieDirection}
+     LIMIT ? OFFSET ?`;
+    const rowParams = filterField
+        ? [...filterParams.slice(0, 1), ...baseParams, ...filterParams.slice(1), params.limit, start]
+        : [...baseParams, params.limit, start];
+    const indexRows = params.db.prepare(rowSql).all(...rowParams);
+    if (indexRows.some((row) => !Number.isInteger(row.rowIndex)))
+        return null;
+    const rowIndices = indexRows.map((row) => row.rowIndex);
+    const selectedRows = params.selectRowsByIndices
+        ? await params.selectRowsByIndices(rowIndices)
+        : (await listPanelQueryHandleRowsByIndices({
+            db: params.db,
+            panel: params.panel,
+            conversationManager: params.conversationManager,
+            workspaceBroker: params.workspaceBroker,
+            config: params.config,
+            datasetSchema: params.datasetSchema,
+            rowIndices,
+        })).rows;
+    if (selectedRows.length !== indexRows.length)
+        return null;
+    const nextPosition = start + selectedRows.length;
+    return {
+        rows: selectedRows,
+        nextCursor: nextPosition < totalCount
+            ? encodeQueryHandleSortCursor({
+                position: nextPosition,
+                sortField: sortField.name,
+                sortDirection: params.options.sortDirection,
+                filterField: filterField?.name,
+                filterValue: params.options.filterValue,
+            })
+            : null,
+    };
+}
+async function readFilteredQueryHandleRowsFromFieldIndex(params) {
+    if (!params.db || !params.options.filterField || params.options.filterValue === undefined)
+        return null;
+    const fieldSchemaKey = queryHandleFieldIndexSchemaKey(params.datasetSchema);
+    if (!fieldSchemaKey)
+        return null;
+    const filterField = getQueryHandleIndexedField(params.datasetSchema, params.options.filterField, 'filter');
+    if (!filterField)
+        return null;
+    const meta = params.db.prepare(`SELECT row_count as rowCount
+       FROM panel_query_handle_field_index_meta
+      WHERE panel_id = ?
+        AND source_manifest_key = ?
+        AND metadata_key = ?
+        AND field_schema_key = ?`).get(params.panel.id, params.sourceManifestKey, params.metadataKey, fieldSchemaKey);
+    if (!meta || !Number.isInteger(meta.rowCount) || meta.rowCount < 0)
+        return null;
+    const filter = normalizeQueryHandleIndexedValue(filterField, params.options.filterValue);
+    if (!filter.hasValue)
+        return { rows: [], nextCursor: null };
+    const filterColumn = queryHandleFieldValueColumn(filterField);
+    const filterValue = filterColumn === 'string_value'
+        ? filter.stringValue
+        : filterColumn === 'number_value'
+            ? filter.numberValue
+            : filter.booleanValue;
+    const start = Math.max(0, params.position);
+    const baseParams = [
+        params.panel.id,
+        params.sourceManifestKey,
+        params.metadataKey,
+        fieldSchemaKey,
+        filterField.name,
+        filterValue,
+    ];
+    const count = params.db.prepare(`SELECT COUNT(*) as totalCount
+       FROM panel_query_handle_field_index_rows
+      WHERE panel_id = ?
+        AND source_manifest_key = ?
+        AND metadata_key = ?
+        AND field_schema_key = ?
+        AND field_name = ?
+        AND has_value = 1
+        AND ${filterColumn} = ?`).get(...baseParams);
+    const totalCount = count?.totalCount ?? 0;
+    if (totalCount <= start)
+        return { rows: [], nextCursor: null };
+    const indexRows = params.db.prepare(`SELECT row_index as rowIndex
+       FROM panel_query_handle_field_index_rows
+      WHERE panel_id = ?
+        AND source_manifest_key = ?
+        AND metadata_key = ?
+        AND field_schema_key = ?
+        AND field_name = ?
+        AND has_value = 1
+        AND ${filterColumn} = ?
+      ORDER BY row_index ASC
+      LIMIT ? OFFSET ?`).all(...baseParams, params.limit, start);
+    if (indexRows.some((row) => !Number.isInteger(row.rowIndex)))
+        return null;
+    const rowIndices = indexRows.map((row) => row.rowIndex);
+    const selectedRows = params.selectRowsByIndices
+        ? await params.selectRowsByIndices(rowIndices)
+        : (await listPanelQueryHandleRowsByIndices({
+            db: params.db,
+            panel: params.panel,
+            conversationManager: params.conversationManager,
+            workspaceBroker: params.workspaceBroker,
+            config: params.config,
+            datasetSchema: params.datasetSchema,
+            rowIndices,
+        })).rows;
+    if (selectedRows.length !== indexRows.length)
+        return null;
+    const nextPosition = start + selectedRows.length;
+    return {
+        rows: selectedRows,
+        nextCursor: nextPosition < totalCount
+            ? encodeQueryHandlePositionCursor({
+                position: nextPosition,
+                sourceKind: params.sourceKind ?? 'query_handle_field_index',
+                filterField: filterField.name,
+                filterValue: params.options.filterValue,
+            })
+            : null,
+    };
+}
+function writeQueryHandleFieldIndexRows(params) {
+    const fields = queryHandleFieldIndexFields(params.datasetSchema, params.extraFieldNames);
+    const fieldSchemaKey = queryHandleFieldIndexSchemaKey(params.datasetSchema, params.extraFieldNames);
+    if (!fieldSchemaKey || fields.length === 0)
+        return;
+    const now = Date.now();
+    const deleteMeta = params.context.db.prepare(`DELETE FROM panel_query_handle_field_index_meta
+      WHERE panel_id = ?
+        AND source_manifest_key = ?
+        AND field_schema_key = ?`);
+    const deleteRows = params.context.db.prepare(`DELETE FROM panel_query_handle_field_index_rows
+      WHERE panel_id = ?
+        AND source_manifest_key = ?
+        AND field_schema_key = ?`);
+    const deleteAggregates = params.context.db.prepare(`DELETE FROM panel_query_handle_field_aggregate_index
+      WHERE panel_id = ?
+        AND source_manifest_key = ?
+        AND field_schema_key = ?`);
+    const insertMeta = params.context.db.prepare(`INSERT INTO panel_query_handle_field_index_meta(
+       panel_id, source_manifest_key, metadata_key, field_schema_key,
+       row_count, created_at, updated_at
+     )
+     VALUES(?, ?, ?, ?, ?, ?, ?)`);
+    const insertRow = params.context.db.prepare(`INSERT INTO panel_query_handle_field_index_rows(
+       panel_id, source_manifest_key, metadata_key, field_schema_key,
+       field_name, row_index, field_type, has_value,
+       string_value, number_value, boolean_value, created_at
+     )
+     VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+    const insertAggregate = params.context.db.prepare(`INSERT INTO panel_query_handle_field_aggregate_index(
+       panel_id, source_manifest_key, metadata_key, field_schema_key,
+       field_name, field_type, value_count, non_empty_count,
+       numeric_count, numeric_sum, numeric_min, numeric_max, created_at
+     )
+     VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+    const aggregateSummaries = buildQueryHandleFieldAggregateSummaries({
+        datasetSchema: params.datasetSchema,
+        rows: params.rows,
+        extraFieldNames: params.extraFieldNames,
+    });
+    params.context.db.transaction(() => {
+        deleteRows.run(params.context.panelId, params.context.sourceManifestKey, fieldSchemaKey);
+        deleteAggregates.run(params.context.panelId, params.context.sourceManifestKey, fieldSchemaKey);
+        deleteMeta.run(params.context.panelId, params.context.sourceManifestKey, fieldSchemaKey);
+        insertMeta.run(params.context.panelId, params.context.sourceManifestKey, params.metadataKey, fieldSchemaKey, params.rows.length, now, now);
+        for (const row of params.rows) {
+            for (const field of fields) {
+                const indexedValue = normalizeQueryHandleIndexedValue(field, getPanelFieldValue(row.fields, field.name));
+                insertRow.run(params.context.panelId, params.context.sourceManifestKey, params.metadataKey, fieldSchemaKey, field.name, row.rowIndex, field.type, indexedValue.hasValue, indexedValue.stringValue, indexedValue.numberValue, indexedValue.booleanValue, now);
+            }
+        }
+        for (const summary of aggregateSummaries) {
+            insertAggregate.run(params.context.panelId, params.context.sourceManifestKey, params.metadataKey, fieldSchemaKey, summary.fieldName, summary.fieldType, summary.valueCount, summary.nonEmptyCount, summary.numericCount, summary.numericSum, summary.numericMin, summary.numericMax, now);
+        }
+    })();
+}
+function buildQueryHandleFieldAggregateSummaries(params) {
+    return queryHandleFieldIndexFields(params.datasetSchema, params.extraFieldNames).map((field) => {
+        const summary = {
+            fieldName: field.name,
+            fieldType: field.type,
+            valueCount: 0,
+            nonEmptyCount: 0,
+            numericCount: 0,
+            numericSum: 0,
+            numericMin: null,
+            numericMax: null,
+        };
+        for (const row of params.rows) {
+            const indexedValue = normalizeQueryHandleIndexedValue(field, getPanelFieldValue(row.fields, field.name));
+            if (!indexedValue.hasValue)
+                continue;
+            summary.valueCount += 1;
+            if (field.type === 'string') {
+                if (indexedValue.stringValue.trim() !== '')
+                    summary.nonEmptyCount += 1;
+            }
+            else {
+                summary.nonEmptyCount += 1;
+            }
+            if (field.type === 'number') {
+                summary.numericCount += 1;
+                summary.numericSum += indexedValue.numberValue;
+                summary.numericMin = summary.numericMin === null
+                    ? indexedValue.numberValue
+                    : Math.min(summary.numericMin, indexedValue.numberValue);
+                summary.numericMax = summary.numericMax === null
+                    ? indexedValue.numberValue
+                    : Math.max(summary.numericMax, indexedValue.numberValue);
+            }
+        }
+        return summary;
+    });
+}
+function recordApiJsonlRangeCheckpoint(context, params) {
+    if (!params.chunk || params.chunk.modifiedAt == null)
+        return;
+    recordQueryHandleCheckpoint(context, {
+        sourceIndex: params.sourceIndex,
+        chunk: params.chunk,
+        rowIndex: params.rowIndex,
+        byteOffset: params.byteOffset,
+        isSourceStart: params.isSourceStart,
+    });
+}
+function recordQueryHandleCheckpoint(context, params) {
+    if (!context || context.sourceKeys[params.sourceIndex] == null)
+        return;
+    if (!params.isSourceStart
+        && params.rowIndex !== 0
+        && params.rowIndex % QUERY_HANDLE_INDEX_INTERVAL_ROWS !== 0) {
+        return;
+    }
+    if (!ensureQueryHandleIndexMetadataFresh(context, params.sourceIndex, params.chunk))
+        return;
+    const metadata = context.metadataBySourceIndex.get(params.sourceIndex);
+    if (!metadata)
+        return;
+    const now = Date.now();
+    context.db.prepare(`INSERT OR REPLACE INTO panel_query_handle_index(
+       panel_id, source_manifest_key, source_index, source_key, file_size, modified_at,
+       row_index, byte_offset, created_at, updated_at
+     )
+     VALUES(
+       ?, ?, ?, ?, ?, ?,
+       ?, ?,
+       COALESCE((
+         SELECT created_at FROM panel_query_handle_index
+         WHERE panel_id = ? AND source_manifest_key = ? AND source_index = ? AND source_key = ? AND row_index = ?
+       ), ?),
+       ?
+     )`).run(context.panelId, context.sourceManifestKey, params.sourceIndex, context.sourceKeys[params.sourceIndex], metadata.fileSize, metadata.modifiedAt, params.rowIndex, params.byteOffset, context.panelId, context.sourceManifestKey, params.sourceIndex, context.sourceKeys[params.sourceIndex], params.rowIndex, now, now);
+}
+function apiJsonlRangeCheckpointChunk(result) {
+    const totalSize = normalizeApiJsonlTotalSize(result.totalSize);
+    if (totalSize == null)
+        return null;
+    return {
+        content: result.content,
+        size: totalSize,
+        modifiedAt: apiJsonlValidatorFingerprint(result),
+        offset: result.rangeStart,
+        hasMore: result.hasMore,
+    };
+}
+function normalizeApiJsonlTotalSize(totalSize) {
+    return typeof totalSize === 'number' && Number.isSafeInteger(totalSize) && totalSize >= 0
+        ? totalSize
+        : null;
+}
+function apiJsonlValidatorFingerprint(source) {
+    const etag = typeof source.etag === 'string' ? source.etag.trim() : '';
+    if (etag)
+        return hashStringToSafeInteger(`etag:${etag}`);
+    const lastModified = typeof source.lastModified === 'string' ? source.lastModified.trim() : '';
+    if (lastModified)
+        return hashStringToSafeInteger(`last-modified:${lastModified}`);
+    return null;
+}
+function hashStringToSafeInteger(value) {
+    return createHash('sha256').update(value).digest().readUIntBE(0, 6);
+}
+function ensureQueryHandleIndexMetadataFresh(context, sourceIndex, chunk) {
+    const existingMetadata = context.metadataBySourceIndex.get(sourceIndex);
+    if (existingMetadata)
+        return true;
+    const sourceKey = context.sourceKeys[sourceIndex];
+    if (sourceKey == null)
+        return false;
+    const fileSize = chunk.size;
+    const modifiedAt = normalizeModifiedAt(chunk.modifiedAt);
+    context.db.prepare(`DELETE FROM panel_query_handle_index
+      WHERE panel_id = ?
+        AND source_manifest_key = ?
+        AND source_index = ?
+        AND source_key != ?`).run(context.panelId, context.sourceManifestKey, sourceIndex, sourceKey);
+    const mismatch = modifiedAt == null
+        ? context.db.prepare(`SELECT 1
+         FROM panel_query_handle_index
+        WHERE panel_id = ?
+          AND source_manifest_key = ?
+          AND source_index = ?
+          AND source_key = ?
+          AND file_size != ?
+        LIMIT 1`).get(context.panelId, context.sourceManifestKey, sourceIndex, sourceKey, fileSize)
+        : context.db.prepare(`SELECT 1
+         FROM panel_query_handle_index
+        WHERE panel_id = ?
+          AND source_manifest_key = ?
+          AND source_index = ?
+          AND source_key = ?
+          AND (file_size != ? OR modified_at IS NULL OR modified_at != ?)
+        LIMIT 1`).get(context.panelId, context.sourceManifestKey, sourceIndex, sourceKey, fileSize, modifiedAt);
+    if (mismatch) {
+        context.db.prepare(`DELETE FROM panel_query_handle_index
+        WHERE panel_id = ?
+          AND source_manifest_key = ?
+          AND source_index = ?`).run(context.panelId, context.sourceManifestKey, sourceIndex);
+    }
+    context.metadataBySourceIndex.set(sourceIndex, { fileSize, modifiedAt });
+    return true;
+}
+function normalizeModifiedAt(modifiedAt) {
+    return typeof modifiedAt === 'number' && Number.isFinite(modifiedAt)
+        ? Math.trunc(modifiedAt)
+        : null;
+}
+async function readQueryHandleChunk(params) {
+    try {
+        if (params.dataSource.kind === 'workspace_relative') {
+            return await params.workspaceBroker.readFile(params.nodeId, params.workspaceRoot, params.dataSource.relativePath, {
+                scaffold: false,
+                offset: params.offset,
+                limit: params.limit,
+            });
+        }
+        const exact = await params.workspaceBroker.readExactPath(params.nodeId, params.dataSource.absolutePath, {
+            allowedRoot: params.dataSource.allowedRoot,
+            offset: params.offset,
+            limit: params.limit,
+        });
+        if (exact.kind !== 'file') {
+            throw new PanelQueryHandleError('query_handle workspace_jsonl path must point to a file.', 400);
+        }
+        return exact;
+    }
+    catch (error) {
+        if (error instanceof PanelQueryHandleError)
+            throw error;
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes('not_found') || message.includes('ENOENT') || message.includes('No such file')) {
+            const path = params.dataSource.kind === 'workspace_relative'
+                ? params.dataSource.relativePath
+                : params.dataSource.absolutePath;
+            throw new PanelQueryHandleError(`query_handle source not found: ${path}`, 404);
+        }
+        throw error;
+    }
+}
+function parseCompleteJsonlLines(content, hasMore) {
+    if (!hasMore) {
+        return { completeText: content, lines: splitJsonlLineSegments(content) };
+    }
+    const lastNewline = content.lastIndexOf('\n');
+    if (lastNewline < 0)
+        return { completeText: '', lines: [] };
+    const completeText = content.slice(0, lastNewline + 1);
+    return {
+        completeText,
+        lines: splitJsonlLineSegments(completeText),
+    };
+}
+function splitJsonlLineSegments(text) {
+    const segments = [];
+    let start = 0;
+    while (start < text.length) {
+        const newlineIndex = text.indexOf('\n', start);
+        const end = newlineIndex >= 0 ? newlineIndex + 1 : text.length;
+        const segment = text.slice(start, end);
+        const line = segment.endsWith('\n') ? segment.slice(0, -1) : segment;
+        segments.push({
+            text: line.endsWith('\r') ? line.slice(0, -1) : line,
+            byteLength: Buffer.byteLength(segment, 'utf8'),
+        });
+        start = end;
+    }
+    return segments;
+}
+function parseJsonlRow(line, rowIndex) {
+    try {
+        const parsed = JSON.parse(line);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error('row must be an object');
+        }
+        return parsed;
+    }
+    catch (error) {
+        throw new PanelQueryHandleError(`Invalid dynamic panel JSONL row at index ${rowIndex}: ${String(error?.message ?? error)}`, 400);
+    }
+}
+function buildPanelRowFromQueryRow(rawRow, rowIndex, datasetSchema) {
+    const fields = {};
+    for (const field of datasetSchema?.fields ?? []) {
+        const value = getPanelFieldValue(rawRow, field.name);
+        if (!isFieldValueValid(field, value)) {
+            throw new PanelQueryHandleError(`Invalid dynamic panel row ${rowIndex}: field "${field.name}" must be a ${field.type}.`, 400);
+        }
+        fields[field.name] = value;
+    }
+    const media = {};
+    for (const slot of datasetSchema?.mediaSlots ?? []) {
+        const slotValue = rawRow[slot.name];
+        if (typeof slotValue === 'string') {
+            media[slot.name] = { kind: slot.kind, value: slotValue };
+        }
+    }
+    const rowId = typeof rawRow.row_id === 'string' && rawRow.row_id.trim()
+        ? rawRow.row_id.trim()
+        : typeof rawRow.rowId === 'string' && rawRow.rowId.trim()
+            ? rawRow.rowId.trim()
+            : null;
+    return {
+        rowIndex,
+        rowId,
+        fields,
+        media,
+    };
+}
+function isFieldValueValid(field, value) {
+    if (value === undefined || value === null)
+        return true;
+    if (field.type === 'number')
+        return typeof value === 'number' && Number.isFinite(value);
+    return typeof value === field.type;
+}
+function matchesFilter(fields, filterField, filterValue) {
+    if (!filterField || filterValue === undefined)
+        return true;
+    return getPanelFieldValue(fields, filterField) === filterValue;
+}
+function parseQueryHandleCursor(cursor) {
+    if (!cursor)
+        return { sourceIndex: 0, offset: 0, rowIndex: 0 };
+    try {
+        const parsed = decodeCursorObject(cursor);
+        const sourceIndex = typeof parsed.sourceIndex === 'number' && Number.isInteger(parsed.sourceIndex) && parsed.sourceIndex >= 0
+            ? parsed.sourceIndex
+            : 0;
+        const offset = typeof parsed.offset === 'number' && Number.isInteger(parsed.offset) && parsed.offset >= 0
+            ? parsed.offset
+            : 0;
+        const rowIndex = typeof parsed.rowIndex === 'number' && Number.isInteger(parsed.rowIndex) && parsed.rowIndex >= 0
+            ? parsed.rowIndex
+            : 0;
+        return { sourceIndex, offset, rowIndex };
+    }
+    catch {
+        return { sourceIndex: 0, offset: 0, rowIndex: 0 };
+    }
+}
+function encodeQueryHandleCursor(cursor) {
+    return Buffer.from(JSON.stringify(cursor), 'utf8').toString('base64');
+}
+function parseQueryHandleSortCursor(cursor, request) {
+    if (!cursor)
+        return { position: 0 };
+    try {
+        const parsed = decodeCursorObject(cursor);
+        const sameSort = parsed.sortField === request.sortField
+            && parsed.sortDirection === request.sortDirection
+            && parsed.filterField === request.filterField
+            && parsed.filterValue === request.filterValue;
+        if (!sameSort)
+            return { position: 0 };
+        const position = typeof parsed.position === 'number' && Number.isInteger(parsed.position) && parsed.position >= 0
+            ? parsed.position
+            : 0;
+        return { position };
+    }
+    catch {
+        return { position: 0 };
+    }
+}
+function encodeQueryHandleSortCursor(cursor) {
+    return Buffer.from(JSON.stringify(cursor), 'utf8').toString('base64');
+}
+function parseQueryHandlePositionCursor(cursor, request) {
+    if (!cursor)
+        return { position: 0 };
+    try {
+        const parsed = decodeCursorObject(cursor);
+        if (request.sourceKind === 'api_jsonl'
+            && parsed.sourceKind === 'api_jsonl_range'
+            && typeof parsed.rowIndex === 'number'
+            && Number.isInteger(parsed.rowIndex)
+            && parsed.rowIndex >= 0) {
+            return { position: parsed.rowIndex };
+        }
+        const sameRequest = parsed.sourceKind === request.sourceKind
+            && parsed.filterField === request.filterField
+            && parsed.filterValue === request.filterValue;
+        if (!sameRequest)
+            return { position: 0 };
+        const position = typeof parsed.position === 'number' && Number.isInteger(parsed.position) && parsed.position >= 0
+            ? parsed.position
+            : 0;
+        return { position };
+    }
+    catch {
+        return { position: 0 };
+    }
+}
+function encodeQueryHandlePositionCursor(cursor) {
+    return Buffer.from(JSON.stringify(cursor), 'utf8').toString('base64');
+}
+function parseApiJsonlRangeCursor(cursor) {
+    if (!cursor)
+        return defaultApiJsonlRangeCursor();
+    try {
+        const parsed = decodeCursorObject(cursor);
+        if (parsed.sourceKind !== 'api_jsonl_range')
+            return defaultApiJsonlRangeCursor();
+        return {
+            sourceKind: 'api_jsonl_range',
+            sourceIndex: typeof parsed.sourceIndex === 'number' && Number.isInteger(parsed.sourceIndex) && parsed.sourceIndex >= 0
+                ? parsed.sourceIndex
+                : 0,
+            offset: typeof parsed.offset === 'number' && Number.isInteger(parsed.offset) && parsed.offset >= 0
+                ? parsed.offset
+                : 0,
+            rowIndex: typeof parsed.rowIndex === 'number' && Number.isInteger(parsed.rowIndex) && parsed.rowIndex >= 0
+                ? parsed.rowIndex
+                : 0,
+            ...(typeof parsed.url === 'string' && parsed.url ? { url: parsed.url } : {}),
+            etag: typeof parsed.etag === 'string' && parsed.etag ? parsed.etag : null,
+            lastModified: typeof parsed.lastModified === 'string' && parsed.lastModified ? parsed.lastModified : null,
+            totalSize: typeof parsed.totalSize === 'number' && Number.isSafeInteger(parsed.totalSize) && parsed.totalSize >= 0
+                ? parsed.totalSize
+                : null,
+        };
+    }
+    catch {
+        return defaultApiJsonlRangeCursor();
+    }
+}
+function defaultApiJsonlRangeCursor() {
+    return {
+        sourceKind: 'api_jsonl_range',
+        sourceIndex: 0,
+        offset: 0,
+        rowIndex: 0,
+        etag: null,
+        lastModified: null,
+        totalSize: null,
+    };
+}
+function encodeApiJsonlRangeCursor(cursor) {
+    return Buffer.from(JSON.stringify(cursor), 'utf8').toString('base64');
+}
+function isPositionCursor(cursor) {
+    if (!cursor)
+        return false;
+    try {
+        const parsed = decodeCursorObject(cursor);
+        return typeof parsed.position === 'number' && Number.isInteger(parsed.position) && parsed.position >= 0;
+    }
+    catch {
+        return false;
+    }
+}
+function withApiJsonlIfRange(cursor) {
+    if (typeof cursor.etag === 'string' && cursor.etag.trim())
+        return { ifRange: cursor.etag.trim() };
+    if (typeof cursor.lastModified === 'string' && cursor.lastModified.trim())
+        return { ifRange: cursor.lastModified.trim() };
+    return {};
+}
+function decodeCursorObject(cursor) {
+    const parsed = JSON.parse(Buffer.from(cursor, 'base64').toString('utf8'));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+        ? parsed
+        : {};
+}
+function comparePanelRowsBySortField(left, right, sortField, sortDirection, sortFieldType) {
+    const leftValue = getPanelFieldValue(left.fields, sortField);
+    const rightValue = getPanelFieldValue(right.fields, sortField);
+    const primary = compareSortValues(leftValue, rightValue, sortFieldType);
+    if (primary !== 0) {
+        return sortDirection === 'asc' ? primary : -primary;
+    }
+    const tieBreaker = left.rowIndex - right.rowIndex;
+    return sortDirection === 'asc' ? tieBreaker : -tieBreaker;
+}
+function compareSortValues(left, right, sortFieldType) {
+    if (sortFieldType === 'number') {
+        return normalizedSortNumber(left) - normalizedSortNumber(right);
+    }
+    if (sortFieldType === 'boolean') {
+        return Number(left === true) - Number(right === true);
+    }
+    return normalizedSortString(left).localeCompare(normalizedSortString(right));
+}
+function normalizedSortNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+function normalizedSortString(value) {
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    return '';
+}