@duckcodeailabs/dql-cli 1.6.3 → 1.6.5

package/dist/apps-api.js

@@ -255,6 +255,157 @@ export async function handleAppsApi(ctx) {
             storage.close();
         }
     }
+    m = path.match(/^\/api\/apps\/([^/]+)\/investigations$/);
+    if (m) {
+        const appId = decodeURIComponent(m[1]);
+        if (!loadAppById(projectRoot, appId)) {
+            sendJson(res, 404, { error: `App "${appId}" not found` });
+            return true;
+        }
+        const storage = new LocalAppStorage(defaultLocalAppsDbPath(projectRoot));
+        try {
+            if (req.method === 'GET') {
+                const dashboardId = ctx.url.searchParams.get('dashboardId') ?? undefined;
+                sendJson(res, 200, { investigations: storage.listAppInvestigations(appId, dashboardId) });
+                return true;
+            }
+            if (req.method === 'POST') {
+                const body = await readJson(req);
+                const question = cleanString(body.question);
+                if (!question) {
+                    sendJson(res, 400, { error: 'question is required' });
+                    return true;
+                }
+                let investigation = storage.createAppInvestigation({
+                    appId,
+                    dashboardId: body.dashboardId,
+                    sourceTileId: body.sourceTileId ?? selectedContextString(body.context, 'tileId'),
+                    sourceBlockId: body.sourceBlockId ?? selectedContextString(body.context, 'blockId'),
+                    title: body.title,
+                    question,
+                    intent: normalizeInvestigationIntent(body.intent, question, body.context),
+                    context: body.context,
+                    generatedSql: body.generatedSql,
+                });
+                if (body.run !== false) {
+                    investigation = await runAppInvestigation(ctx, storage, investigation, body);
+                }
+                sendJson(res, 201, { ok: true, investigation });
+                return true;
+            }
+        }
+        catch (err) {
+            sendJson(res, 500, { error: err instanceof Error ? err.message : String(err) });
+            return true;
+        }
+        finally {
+            storage.close();
+        }
+    }
+    m = path.match(/^\/api\/apps\/([^/]+)\/investigations\/([^/]+)$/);
+    if (m) {
+        const appId = decodeURIComponent(m[1]);
+        const investigationId = decodeURIComponent(m[2]);
+        const storage = new LocalAppStorage(defaultLocalAppsDbPath(projectRoot));
+        try {
+            const investigation = storage.getAppInvestigation(investigationId);
+            if (!investigation || investigation.appId !== appId) {
+                sendJson(res, 404, { error: `Investigation "${investigationId}" not found` });
+                return true;
+            }
+            if (req.method === 'GET') {
+                sendJson(res, 200, { investigation });
+                return true;
+            }
+        }
+        catch (err) {
+            sendJson(res, 500, { error: err instanceof Error ? err.message : String(err) });
+            return true;
+        }
+        finally {
+            storage.close();
+        }
+    }
+    m = path.match(/^\/api\/apps\/([^/]+)\/investigations\/([^/]+)\/run$/);
+    if (m && req.method === 'POST') {
+        const appId = decodeURIComponent(m[1]);
+        const investigationId = decodeURIComponent(m[2]);
+        const storage = new LocalAppStorage(defaultLocalAppsDbPath(projectRoot));
+        try {
+            const investigation = storage.getAppInvestigation(investigationId);
+            if (!investigation || investigation.appId !== appId) {
+                sendJson(res, 404, { error: `Investigation "${investigationId}" not found` });
+                return true;
+            }
+            const body = await readJson(req);
+            const updated = await runAppInvestigation(ctx, storage, investigation, body);
+            sendJson(res, 200, { ok: true, investigation: updated });
+        }
+        catch (err) {
+            sendJson(res, 500, { error: err instanceof Error ? err.message : String(err) });
+        }
+        finally {
+            storage.close();
+        }
+        return true;
+    }
+    m = path.match(/^\/api\/apps\/([^/]+)\/investigations\/([^/]+)\/pin$/);
+    if (m && req.method === 'POST') {
+        const appId = decodeURIComponent(m[1]);
+        const investigationId = decodeURIComponent(m[2]);
+        const storage = new LocalAppStorage(defaultLocalAppsDbPath(projectRoot));
+        try {
+            const investigation = storage.getAppInvestigation(investigationId);
+            if (!investigation || investigation.appId !== appId) {
+                sendJson(res, 404, { error: `Investigation "${investigationId}" not found` });
+                return true;
+            }
+            const body = await readJson(req);
+            const appInfo = loadAppById(projectRoot, appId);
+            const dashboardId = cleanString(body.dashboardId) || investigation.dashboardId || appInfo?.dashboards[0]?.id;
+            if (!dashboardId) {
+                sendJson(res, 400, { error: 'No dashboard is available for this investigation.' });
+                return true;
+            }
+            const created = createAiPinTile(projectRoot, appId, {
+                dashboardId,
+                title: cleanString(body.title) || investigation.title,
+                answer: investigation.summary ?? investigation.recommendation ?? investigation.title,
+                question: investigation.question,
+                sql: investigation.generatedSql,
+                sourceTier: 'metadata_research',
+                certification: 'ai_generated',
+                reviewStatus: 'needs_review',
+                refreshCadence: body.refreshCadence === 'daily' ? 'daily' : 'none',
+                chartConfig: { chart: 'table' },
+                result: investigationPreviewResult(investigation),
+                citations: investigationCitations(investigation),
+                analysisPlan: {
+                    intent: investigation.intent,
+                    reviewRequired: true,
+                    uncertified: true,
+                    sourceTileId: investigation.sourceTileId,
+                    sourceBlockId: investigation.sourceBlockId,
+                },
+                evidence: investigation.evidence,
+                followUps: nextResearchFollowUps(investigation),
+            });
+            if (!created.ok) {
+                sendJson(res, 400, { error: created.error });
+                return true;
+            }
+            const pinId = typeof created.pin === 'object' && created.pin && 'id' in created.pin ? String(created.pin.id) : '';
+            const updated = pinId ? storage.markAppInvestigationPinned(investigationId, pinId) : investigation;
+            sendJson(res, 200, { ...created, investigation: updated });
+        }
+        catch (err) {
+            sendJson(res, 500, { error: err instanceof Error ? err.message : String(err) });
+        }
+        finally {
+            storage.close();
+        }
+        return true;
+    }
     m = path.match(/^\/api\/apps\/([^/]+)\/ai-pins$/);
     if (m) {
         const appId = decodeURIComponent(m[1]);
@@ -478,6 +629,7 @@ function collectAppsList(projectRoot) {
             notebooks: listAppNotebookRefs(projectRoot, document, appDir),
             drafts: listAppDrafts(projectRoot, appDir),
             aiPins: countAiPins(projectRoot, document.id),
+            investigations: countAppInvestigations(projectRoot, document.id),
             homepage: document.homepage,
         });
     }
@@ -890,6 +1042,779 @@ function normalizeConversationMessages(messages) {
     }))
         .filter((message) => message.content.length > 0);
 }
+async function runAppInvestigation(ctx, storage, investigation, input = {}) {
+    const question = cleanString(input.question) || investigation.question;
+    const context = input.context === undefined ? investigation.context : input.context;
+    const intent = normalizeInvestigationIntent(input.intent, question, context);
+    let generatedSql = cleanString(input.generatedSql) || investigation.generatedSql;
+    const lastRunAt = new Date().toISOString();
+    storage.updateAppInvestigation(investigation.id, {
+        question,
+        intent,
+        context,
+        generatedSql,
+        status: 'running',
+        reviewStatus: 'needs_review',
+        error: '',
+    });
+    try {
+        const selected = selectedBlockContext(context);
+        const appInfo = ctx.path.includes('/api/apps/') ? loadAppById(ctx.projectRoot, investigation.appId) : null;
+        const previews = buildContextPreviews(selected);
+        let metricSnapshot = buildMetricSnapshot(selected);
+        let driverCards = buildDriverCards(selected, intent);
+        const sourceTileId = investigation.sourceTileId ?? selectedContextString(context, 'tileId');
+        const sourceBlockId = investigation.sourceBlockId ?? selectedContextString(context, 'blockId');
+        const deterministicGeneration = generatedSql
+            ? undefined
+            : buildDeterministicInvestigationSql(ctx.projectRoot, {
+                question,
+                intent,
+                selected,
+                sourceBlockId,
+            });
+        generatedSql = generatedSql || deterministicGeneration?.sql;
+        const agentGeneration = generatedSql
+            ? undefined
+            : await generateInvestigationSql(ctx, {
+                appId: investigation.appId,
+                dashboardId: investigation.dashboardId ?? selectedString(context, 'dashboardId'),
+                sourceTileId,
+                sourceBlockId,
+                title: investigation.title,
+                question,
+                intent,
+                context,
+            });
+        generatedSql = generatedSql || cleanString(agentGeneration?.sql);
+        const generationError = cleanString(agentGeneration?.executionError);
+        const sqlEvidence = agentGeneration?.result
+            ? { preview: buildGeneratedSqlPreview(agentGeneration.result, generatedSql), error: generationError || undefined }
+            : await runGeneratedSqlPreview(ctx, generatedSql);
+        const sqlError = sqlEvidence.error ?? generationError;
+        if (sqlEvidence.preview) {
+            previews.unshift(sqlEvidence.preview);
+            metricSnapshot = buildPreviewMetricSnapshot(sqlEvidence.preview, selectedString(selected, 'title'));
+            driverCards = buildPreviewDriverCards(sqlEvidence.preview, intent);
+        }
+        const evidence = {
+            trustStatus: buildInvestigationTrust(investigation, selected, sqlError),
+            planner: {
+                intent,
+                steps: investigationSteps(intent),
+                reviewRequired: true,
+                generatedSql: generatedSql || undefined,
+                sqlExecuted: Boolean(sqlEvidence.preview),
+                sqlError,
+                generationSource: deterministicGeneration ? 'selected_block_metadata' : agentGeneration?.providerUsed ? 'ai_provider' : generatedSql ? 'provided_sql' : 'context_only',
+                sourceBlockPath: deterministicGeneration?.sourceBlockPath,
+                sourceBlockName: deterministicGeneration?.sourceBlockName,
+                providerUsed: agentGeneration?.providerUsed,
+            },
+            certifiedContext: {
+                appId: investigation.appId,
+                appName: appInfo?.app.name,
+                dashboardId: investigation.dashboardId,
+                dashboardTitle: selectedString(context, 'dashboardTitle'),
+                sourceTileId,
+                sourceBlockId,
+                sourceBlockPath: deterministicGeneration?.sourceBlockPath ?? selectedString(selected, 'blockPath'),
+                certificationStatus: selectedString(selected, 'certificationStatus'),
+            },
+            assumptions: investigationAssumptions(intent, selected, generatedSql, sqlError),
+            context,
+            agentEvidence: agentGeneration?.evidence,
+            analysisPlan: agentGeneration?.analysisPlan,
+            citations: agentGeneration?.citations,
+        };
+        const summary = cleanString(agentGeneration?.answer) || buildInvestigationSummary(intent, question, selected, metricSnapshot, driverCards);
+        const recommendation = buildInvestigationRecommendation(intent, selected, sqlError);
+        return storage.updateAppInvestigation(investigation.id, {
+            title: cleanString(input.question) ? titleFromInvestigation(question, selected) : investigation.title,
+            question,
+            intent,
+            context,
+            status: sqlEvidence.fatal ? 'error' : 'ready',
+            summary,
+            recommendation,
+            metrics: metricSnapshot,
+            driverCards,
+            resultPreviews: previews,
+            evidence,
+            generatedSql,
+            reviewStatus: 'needs_review',
+            error: sqlError ?? '',
+            lastRunAt,
+        }) ?? investigation;
+    }
+    catch (err) {
+        return storage.updateAppInvestigation(investigation.id, {
+            status: 'error',
+            reviewStatus: 'needs_review',
+            error: err instanceof Error ? err.message : String(err),
+            lastRunAt,
+        }) ?? investigation;
+    }
+}
+function normalizeInvestigationIntent(value, question, context) {
+    if (value === 'diagnose_change'
+        || value === 'driver_breakdown'
+        || value === 'segment_compare'
+        || value === 'entity_drilldown'
+        || value === 'anomaly_investigation'
+        || value === 'trust_gap_review')
+        return value;
+    const text = `${question} ${JSON.stringify(safeIntentContext(context)).slice(0, 500)}`.toLowerCase();
+    if (/\b(trust|rely|certif|lineage|owner|caveat|gap)\b/.test(text))
+        return 'trust_gap_review';
+    if (/\b(anomal|exception|outlier|spike|dip)\b/.test(text))
+        return 'anomaly_investigation';
+    if (/\b(compare|versus| vs |segment|cohort)\b/.test(text))
+        return 'segment_compare';
+    if (/\b(why|changed|change|drop|decline|increase|decrease|february|month|week|quarter)\b/.test(text))
+        return 'diagnose_change';
+    if (/\b(driver|drove|break down|breakdown|contribute|top mover|movers)\b/.test(text))
+        return 'driver_breakdown';
+    if (/\b(customer|account|user|client|merchant|product|sku|alice|johnson)\b/.test(text))
+        return 'entity_drilldown';
+    return 'driver_breakdown';
+}
+function safeIntentContext(context) {
+    const root = asRecord(context);
+    return {
+        selectedBlock: root ? root.selectedBlock : undefined,
+        dashboardTitle: root ? root.dashboardTitle : undefined,
+        availableBlocks: root ? root.availableBlocks : undefined,
+    };
+}
+function selectedBlockContext(context) {
+    const root = asRecord(context);
+    const selected = asRecord(root?.selectedBlock);
+    if (selected)
+        return selected;
+    if (!root)
+        return null;
+    const hasSelectedTileContext = ['blockId', 'blockPath', 'tileId', 'certificationStatus', 'resultSample', 'rowCount']
+        .some((key) => root[key] !== undefined && root[key] !== null);
+    return hasSelectedTileContext ? root : null;
+}
+function selectedContextString(context, key) {
+    return selectedString(selectedBlockContext(context), key);
+}
+function selectedString(context, key) {
+    const record = asRecord(context);
+    const value = record?.[key];
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+function buildContextPreviews(selected) {
+    const rows = selectedRows(selected);
+    if (rows.length === 0)
+        return [];
+    const columns = selectedColumns(selected, rows);
+    return [{
+            id: 'selected-tile-sample',
+            title: 'Selected tile evidence',
+            kind: 'table',
+            reviewRequired: true,
+            result: {
+                columns,
+                rows,
+                rowCount: typeof selected?.rowCount === 'number' ? selected.rowCount : rows.length,
+            },
+        }];
+}
+function buildMetricSnapshot(selected) {
+    const rows = selectedRows(selected);
+    const columns = selectedColumns(selected, rows);
+    const numericColumns = columns.filter((column) => rows.some((row) => typeofNumber(row[column]) !== null));
+    const metricColumn = numericColumns[0];
+    if (!metricColumn || rows.length === 0) {
+        return {
+            currentValue: undefined,
+            baselineValue: undefined,
+            delta: undefined,
+            context: 'Metric values were not available in the selected tile sample.',
+        };
+    }
+    const baselineValue = typeofNumber(rows[0]?.[metricColumn]);
+    const currentValue = typeofNumber(rows[rows.length - 1]?.[metricColumn]) ?? baselineValue;
+    const delta = currentValue !== null && baselineValue !== null ? currentValue - baselineValue : undefined;
+    return {
+        metric: metricColumn,
+        currentValue,
+        baselineValue,
+        delta,
+        rowsReviewed: rows.length,
+        context: selectedString(selected, 'title') ?? 'Selected dashboard tile',
+    };
+}
+function buildDriverCards(selected, intent) {
+    const rows = selectedRows(selected);
+    const columns = selectedColumns(selected, rows);
+    if (rows.length === 0) {
+        return [{
+                title: 'Runtime context needed',
+                contribution: 'Needs SQL preview',
+                explanation: 'The selected tile did not include sample rows, so DQL captured the question and review path for a deeper SQL run.',
+                intent,
+            }];
+    }
+    const numericColumn = columns.find((column) => rows.some((row) => typeofNumber(row[column]) !== null));
+    const dimensionColumn = columns.find((column) => column !== numericColumn && rows.some((row) => typeof row[column] === 'string'));
+    if (!numericColumn) {
+        return rows.slice(0, 5).map((row, index) => ({
+            title: String(row[dimensionColumn ?? columns[0]] ?? `Row ${index + 1}`),
+            contribution: 'Context row',
+            explanation: 'This row is part of the tile evidence for the investigation.',
+        }));
+    }
+    return rows
+        .map((row, index) => {
+        const value = typeofNumber(row[numericColumn]) ?? 0;
+        const label = String(row[dimensionColumn ?? columns[0]] ?? `Row ${index + 1}`);
+        return {
+            title: label,
+            value,
+            contribution: formatContribution(value),
+            explanation: `${label} is one of the highest-signal rows in the selected tile sample for ${numericColumn}.`,
+            evidenceLabel: numericColumn,
+        };
+    })
+        .sort((a, b) => Math.abs(Number(b.value ?? 0)) - Math.abs(Number(a.value ?? 0)))
+        .slice(0, 5);
+}
+function buildPreviewMetricSnapshot(preview, fallbackTitle) {
+    const rows = previewResultRows(preview);
+    const columns = previewResultColumns(preview, rows);
+    const numericColumns = columns.filter((column) => rows.some((row) => typeofNumber(row[column]) !== null));
+    if (rows.length === 0 || numericColumns.length === 0) {
+        return {
+            currentValue: undefined,
+            baselineValue: undefined,
+            delta: undefined,
+            context: 'Generated SQL preview did not return numeric metric rows.',
+        };
+    }
+    const currentColumn = pickColumn(numericColumns, [/^current_/i, /current.*(revenue|value|amount|total|orders?)/i])
+        ?? pickColumn(numericColumns, [/^total_/i, /(revenue|value|amount|total|orders?|points?|goals?|assists?|rebounds?|score|games_played)$/i])
+        ?? pickColumn(numericColumns, [/(count|row_count)$/i])
+        ?? numericColumns[0];
+    const baselineColumn = pickColumn(numericColumns, [/^baseline_/i, /baseline.*(revenue|value|amount|total|orders?)/i]);
+    const deltaColumn = pickColumn(numericColumns, [/(delta|change|variance|diff|contribution)/i]);
+    const currentValue = sumNumericRows(rows, currentColumn);
+    const baselineValue = baselineColumn ? sumNumericRows(rows, baselineColumn) : typeofNumber(rows[0]?.[currentColumn]);
+    const delta = deltaColumn
+        ? sumNumericRows(rows, deltaColumn)
+        : currentValue !== null && baselineValue !== null
+            ? currentValue - baselineValue
+            : undefined;
+    return {
+        metric: deltaColumn ?? currentColumn,
+        currentValue,
+        baselineValue,
+        delta,
+        rowsReviewed: rows.length,
+        context: fallbackTitle ?? selectedString(preview, 'title') ?? 'Generated SQL preview',
+    };
+}
+function buildPreviewDriverCards(preview, intent) {
+    const rows = previewResultRows(preview);
+    const columns = previewResultColumns(preview, rows);
+    if (rows.length === 0) {
+        return buildDriverCards(null, intent);
+    }
+    const numericColumns = columns.filter((column) => rows.some((row) => typeofNumber(row[column]) !== null));
+    const contributionColumn = pickColumn(numericColumns, [/(delta|change|variance|diff|contribution)/i])
+        ?? pickColumn(numericColumns, [/^current_/i, /^total_/i, /(revenue|value|amount|total|orders?|points?|goals?|assists?|rebounds?|score|games_played)$/i])
+        ?? pickColumn(numericColumns, [/(count|row_count)$/i])
+        ?? numericColumns[0];
+    const dimensionColumn = columns.find((column) => column !== contributionColumn && rows.some((row) => typeof row[column] === 'string'));
+    if (!contributionColumn) {
+        return rows.slice(0, 5).map((row, index) => ({
+            title: String(row[dimensionColumn ?? columns[0]] ?? `Row ${index + 1}`),
+            contribution: 'Preview row',
+            explanation: 'This row came from the generated SQL preview and needs analyst review.',
+            intent,
+        }));
+    }
+    return rows
+        .map((row, index) => {
+        const value = typeofNumber(row[contributionColumn]) ?? 0;
+        const label = String(row[dimensionColumn ?? columns[0]] ?? `Row ${index + 1}`);
+        return {
+            title: label,
+            value,
+            contribution: formatContribution(value),
+            explanation: `${label} is ranked by ${contributionColumn} from the generated SQL preview.`,
+            evidenceLabel: contributionColumn,
+            reviewRequired: true,
+            intent,
+        };
+    })
+        .sort((a, b) => Math.abs(Number(b.value ?? 0)) - Math.abs(Number(a.value ?? 0)))
+        .slice(0, 5);
+}
+function previewResultRows(preview) {
+    const result = asRecord(preview.result);
+    const rows = Array.isArray(result?.rows) ? result.rows : [];
+    return rows.map(asRecord).filter((row) => Boolean(row)).slice(0, 100);
+}
+function previewResultColumns(preview, rows) {
+    const result = asRecord(preview.result);
+    const columns = Array.isArray(result?.columns) ? result.columns.map(String).filter(Boolean) : [];
+    return columns.length > 0 ? columns.slice(0, 20) : Object.keys(rows[0] ?? {}).slice(0, 20);
+}
+function pickColumn(columns, patterns) {
+    return columns.find((column) => patterns.some((pattern) => pattern.test(column)));
+}
+function sumNumericRows(rows, column) {
+    let total = 0;
+    let found = false;
+    for (const row of rows) {
+        const value = typeofNumber(row[column]);
+        if (value === null)
+            continue;
+        total += value;
+        found = true;
+    }
+    return found ? total : null;
+}
+function buildDeterministicInvestigationSql(projectRoot, input) {
+    if (input.intent === 'trust_gap_review')
+        return undefined;
+    const block = resolveSelectedBlock(projectRoot, input.selected, input.sourceBlockId);
+    if (!block)
+        return undefined;
+    const source = readFileSync(join(projectRoot, block.path), 'utf-8');
+    const blockSql = extractDqlQuery(source);
+    if (!blockSql || /\{\{/.test(blockSql) || !isReadOnlySql(blockSql))
+        return undefined;
+    const rows = selectedRows(input.selected);
+    const columns = selectedColumns(input.selected, rows);
+    const sourceSql = stripTopLevelOrderAndLimit(blockSql);
+    const profile = profileResultColumns(columns, rows);
+    const measure = chooseMeasureColumn(profile);
+    if (!measure)
+        return undefined;
+    const dimension = chooseDimensionColumn(input.question, profile, input.intent);
+    const sourceCte = `WITH dql_source AS (\n${sourceSql}\n)`;
+    if (input.intent === 'entity_drilldown') {
+        const entity = inferEntityFilter(input.question, profile, rows);
+        const orderBy = `ORDER BY ${quoteSqlIdentifier(measure.name)} DESC`;
+        const where = entity ? `\nWHERE ${quoteSqlIdentifier(entity.column)} IS NOT NULL AND LOWER(CAST(${quoteSqlIdentifier(entity.column)} AS VARCHAR)) LIKE ${sqlStringLiteral(`%${entity.value.toLowerCase()}%`)}` : '';
+        return {
+            sql: `${sourceCte}\nSELECT *\nFROM dql_source${where}\n${orderBy}\nLIMIT 100`,
+            sourceBlockPath: block.path,
+            sourceBlockName: block.name,
+        };
+    }
+    if (input.intent === 'anomaly_investigation') {
+        const timeDimension = chooseTimeDimension(profile) ?? dimension;
+        const rankExpr = `${measureAgg(measure)}(${quoteSqlIdentifier(measure.name)})`;
+        if (timeDimension) {
+            return {
+                sql: [
+                    sourceCte,
+                    ', dql_trend AS (',
+                    `  SELECT ${quoteSqlIdentifier(timeDimension.name)} AS ${quoteSqlIdentifier(timeDimension.name)}, ${rankExpr} AS ${quoteSqlIdentifier(measure.name)}`,
+                    '  FROM dql_source',
+                    `  GROUP BY ${quoteSqlIdentifier(timeDimension.name)}`,
+                    '), dql_deltas AS (',
+                    `  SELECT ${quoteSqlIdentifier(timeDimension.name)}, ${quoteSqlIdentifier(measure.name)}, LAG(${quoteSqlIdentifier(measure.name)}) OVER (ORDER BY ${quoteSqlIdentifier(timeDimension.name)}) AS baseline_${safeAlias(measure.name)}`,
+                    '  FROM dql_trend',
+                    ')',
+                    `SELECT *, ${quoteSqlIdentifier(measure.name)} - baseline_${safeAlias(measure.name)} AS delta_${safeAlias(measure.name)}`,
+                    'FROM dql_deltas',
+                    `ORDER BY ABS(COALESCE(delta_${safeAlias(measure.name)}, 0)) DESC`,
+                    'LIMIT 20',
+                ].join('\n'),
+                sourceBlockPath: block.path,
+                sourceBlockName: block.name,
+            };
+        }
+    }
+    if (!dimension)
+        return undefined;
+    const aggregate = `${measureAgg(measure)}(${quoteSqlIdentifier(measure.name)})`;
+    const label = quoteSqlIdentifier(dimension.name);
+    return {
+        sql: [
+            sourceCte,
+            `SELECT ${label} AS ${label}, ${aggregate} AS ${quoteSqlIdentifier(measure.name)}, COUNT(*) AS ${quoteSqlIdentifier('row_count')}`,
+            'FROM dql_source',
+            `GROUP BY ${label}`,
+            `ORDER BY ABS(COALESCE(${quoteSqlIdentifier(measure.name)}, 0)) DESC`,
+            'LIMIT 20',
+        ].join('\n'),
+        sourceBlockPath: block.path,
+        sourceBlockName: block.name,
+    };
+}
+function resolveSelectedBlock(projectRoot, selected, sourceBlockId) {
+    const selectedPath = selectedString(selected, 'blockPath');
+    const candidates = collectBlockCandidates(projectRoot);
+    if (selectedPath) {
+        const normalizedPath = selectedPath.replace(/^\/+/, '');
+        const found = candidates.find((block) => block.path === normalizedPath);
+        if (found)
+            return found;
+        if (normalizedPath.startsWith('blocks/') && existsSync(join(projectRoot, normalizedPath))) {
+            const source = readFileSync(join(projectRoot, normalizedPath), 'utf-8');
+            const name = matchString(source, /block\s+"([^"]+)"/) ?? titleFromPath(normalizedPath);
+            return {
+                id: name,
+                name,
+                domain: matchString(source, /domain\s*=\s*"([^"]+)"/) ?? 'uncategorized',
+                status: matchString(source, /status\s*=\s*"([^"]+)"/) ?? 'draft',
+                owner: matchString(source, /owner\s*=\s*"([^"]+)"/),
+                tags: matchArray(source, /tags\s*=\s*\[([^\]]*)\]/),
+                path: normalizedPath,
+                lastModified: statSyncSafe(join(projectRoot, normalizedPath))?.mtime.toISOString() ?? new Date(0).toISOString(),
+                description: matchString(source, /description\s*=\s*"((?:[^"\\]|\\.)*)"/) ?? '',
+                llmContext: matchString(source, /llmContext\s*=\s*"((?:[^"\\]|\\.)*)"/),
+                chartType: matchString(source, /chart\s*=\s*"([^"]+)"/) ?? undefined,
+                score: 0,
+                reasons: [],
+            };
+        }
+    }
+    const id = cleanString(sourceBlockId) || selectedString(selected, 'blockId');
+    if (!id)
+        return undefined;
+    return candidates.find((block) => block.id === id || block.name === id || block.path === id);
+}
+function profileResultColumns(columns, rows) {
+    return columns.map((name) => {
+        const lower = name.toLowerCase();
+        const numeric = rows.length === 0 ? !isLikelyTextColumn(lower) : rows.some((row) => typeofNumber(row[name]) !== null);
+        const text = rows.some((row) => typeof row[name] === 'string' && String(row[name]).trim().length > 0);
+        const time = /\b(season|year|month|week|quarter|date|day)\b/i.test(lower);
+        const identifier = /\b(id|key|uuid|number)\b/i.test(lower) && !time;
+        const measureName = /\b(total|sum|amount|revenue|sales|points?|goals?|assists?|rebounds?|count|avg|average|rate|pct|percent|score|value|delta|change|variance)\b/i.test(lower);
+        const dimensionName = /\b(name|type|segment|region|market|category|status|player|customer|account|team|season|year|month|week|quarter|date)\b/i.test(lower);
+        const measure = numeric && measureName && !identifier && !time;
+        const dimension = !measure && (text || time || dimensionName || !numeric);
+        return { name, lower, numeric, text, dimension, measure, time };
+    });
+}
+function chooseMeasureColumn(columns) {
+    const candidates = columns.filter((column) => column.measure);
+    return candidates.find((column) => /\b(delta|change|variance|contribution)\b/i.test(column.lower))
+        ?? candidates.find((column) => /\b(total_points|total_revenue|total_amount|total|revenue|amount|sales|points|goals)\b/i.test(column.lower))
+        ?? candidates.find((column) => /\b(count|value|score|avg|average|rate|pct|percent)\b/i.test(column.lower))
+        ?? columns.find((column) => column.numeric && !column.dimension);
+}
+function chooseDimensionColumn(question, columns, intent) {
+    const dimensions = columns.filter((column) => column.dimension);
+    const questionTokens = new Set(question.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean));
+    const mentioned = dimensions.find((column) => column.lower.split(/[^a-z0-9]+/).some((token) => questionTokens.has(token)));
+    if (mentioned)
+        return mentioned;
+    const timeDimension = chooseTimeDimension(columns);
+    if ((intent === 'diagnose_change' || intent === 'segment_compare' || intent === 'anomaly_investigation') && timeDimension)
+        return timeDimension;
+    return dimensions.find((column) => column.text && !column.time)
+        ?? timeDimension
+        ?? dimensions[0];
+}
+function chooseTimeDimension(columns) {
+    return columns.find((column) => column.time);
+}
+function inferEntityFilter(question, columns, rows) {
+    const textDimensions = columns.filter((column) => column.dimension && (column.text || /\b(name|player|customer|account|team)\b/i.test(column.lower)));
+    const lowerQuestion = question.toLowerCase();
+    for (const column of textDimensions) {
+        for (const row of rows) {
+            const value = cleanString(row[column.name]);
+            if (value && lowerQuestion.includes(value.toLowerCase()))
+                return { column: column.name, value };
+        }
+    }
+    const named = question.match(/\b([A-Z][a-z]+(?:\s+[A-Z][a-z]+)+)\b/);
+    const value = named?.[1]?.trim();
+    const column = textDimensions[0];
+    return value && column ? { column: column.name, value } : undefined;
+}
+function measureAgg(column) {
+    return /\b(avg|average|rate|pct|percent|per_)\b/i.test(column.lower) ? 'AVG' : 'SUM';
+}
+function extractDqlQuery(source) {
+    const tripleQuoteMatch = source.match(/query\s*=\s*"""([\s\S]*?)"""/i);
+    if (tripleQuoteMatch)
+        return tripleQuoteMatch[1].trim() || null;
+    const singleQuoteMatch = source.match(/query\s*=\s*"((?:[^"\\]|\\.)*)"/i);
+    if (singleQuoteMatch)
+        return singleQuoteMatch[1].replace(/\\"/g, '"').trim() || null;
+    return null;
+}
+function stripTopLevelOrderAndLimit(sql) {
+    let next = sql.trim().replace(/;+\s*$/g, '');
+    const limitIndex = findLastTopLevelKeyword(next, 'limit');
+    if (limitIndex >= 0 && /^\s+limit\s+\d+\s*$/i.test(next.slice(limitIndex))) {
+        next = next.slice(0, limitIndex).trim();
+    }
+    const orderIndex = findLastTopLevelKeyword(next, 'order by');
+    if (orderIndex >= 0)
+        next = next.slice(0, orderIndex).trim();
+    return next;
+}
+function findLastTopLevelKeyword(sql, keyword) {
+    const lower = sql.toLowerCase();
+    const target = keyword.toLowerCase();
+    let depth = 0;
+    let quote = null;
+    let last = -1;
+    for (let i = 0; i < lower.length; i += 1) {
+        const char = lower[i];
+        if (quote) {
+            if (char === quote && lower[i - 1] !== '\\')
+                quote = null;
+            continue;
+        }
+        if (char === '"' || char === "'" || char === '`') {
+            quote = char;
+            continue;
+        }
+        if (char === '(')
+            depth += 1;
+        if (char === ')')
+            depth = Math.max(0, depth - 1);
+        if (depth === 0 && lower.startsWith(target, i) && isKeywordBoundary(lower, i - 1) && isKeywordBoundary(lower, i + target.length)) {
+            last = i;
+        }
+    }
+    return last;
+}
+function isKeywordBoundary(value, index) {
+    if (index < 0 || index >= value.length)
+        return true;
+    return /[^a-z0-9_]/i.test(value[index]);
+}
+function quoteSqlIdentifier(identifier) {
+    return `"${identifier.replace(/"/g, '""')}"`;
+}
+function sqlStringLiteral(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+function safeAlias(identifier) {
+    return identifier.replace(/[^a-z0-9_]+/gi, '_').replace(/^_+|_+$/g, '') || 'value';
+}
+function isLikelyTextColumn(value) {
+    return /\b(name|type|segment|region|market|category|status|player|customer|account|team)\b/i.test(value);
+}
+async function generateInvestigationSql(ctx, input) {
+    if (!ctx.generateInvestigationSql)
+        return undefined;
+    try {
+        return await ctx.generateInvestigationSql(input);
+    }
+    catch (err) {
+        return {
+            executionError: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+async function runGeneratedSqlPreview(ctx, generatedSql) {
+    const sql = cleanString(generatedSql);
+    if (!sql)
+        return {};
+    if (!isReadOnlySql(sql)) {
+        return {
+            error: 'Generated SQL was not run because it was not a read-only SELECT or WITH query.',
+            fatal: true,
+        };
+    }
+    if (!ctx.executeSql) {
+        return {
+            error: 'This host cannot execute investigation SQL.',
+            fatal: false,
+        };
+    }
+    try {
+        const result = await ctx.executeSql(boundedPreviewSql(sql));
+        return {
+            preview: {
+                id: 'generated-sql-preview',
+                title: 'Generated SQL preview',
+                kind: 'table',
+                reviewRequired: true,
+                result,
+            },
+        };
+    }
+    catch (err) {
+        return {
+            error: err instanceof Error ? err.message : String(err),
+            fatal: true,
+        };
+    }
+}
+function buildGeneratedSqlPreview(result, generatedSql) {
+    const record = asRecord(result);
+    const rawRows = Array.isArray(record?.rows) ? record.rows : [];
+    const rows = rawRows.map(asRecord).filter((row) => Boolean(row)).slice(0, 100);
+    const rawColumns = Array.isArray(record?.columns) ? record.columns : [];
+    const columns = rawColumns.length
+        ? rawColumns.map((column) => {
+            const columnRecord = asRecord(column);
+            return typeof column === 'string'
+                ? column
+                : typeof columnRecord?.name === 'string'
+                    ? columnRecord.name
+                    : String(column);
+        })
+        : Object.keys(rows[0] ?? {});
+    return {
+        id: 'generated-sql-preview',
+        title: 'Generated SQL preview',
+        kind: 'table',
+        reviewRequired: true,
+        sql: generatedSql,
+        result: {
+            columns,
+            rows,
+            rowCount: typeof record?.rowCount === 'number' ? record.rowCount : rows.length,
+            executionTime: typeof record?.executionTime === 'number' ? record.executionTime : undefined,
+        },
+    };
+}
+function isReadOnlySql(sql) {
+    const trimmed = stripLeadingSqlComments(sql).replace(/;+\s*$/g, '');
+    if (!/^(select|with)\b/i.test(trimmed))
+        return false;
+    if (/;\s*\S/.test(trimmed))
+        return false;
+    return !/\b(insert|update|delete|merge|drop|alter|create|truncate|copy|grant|revoke|call|execute|attach|detach)\b/i.test(trimmed);
+}
+function stripLeadingSqlComments(sql) {
+    let next = sql.trim();
+    while (next.startsWith('--') || next.startsWith('/*')) {
+        if (next.startsWith('--')) {
+            const lineEnd = next.indexOf('\n');
+            next = lineEnd >= 0 ? next.slice(lineEnd + 1).trimStart() : '';
+            continue;
+        }
+        const blockEnd = next.indexOf('*/');
+        next = blockEnd >= 0 ? next.slice(blockEnd + 2).trimStart() : '';
+    }
+    return next;
+}
+function boundedPreviewSql(sql) {
+    return `SELECT * FROM (${sql.trim().replace(/;+\s*$/g, '')}) AS dql_research_preview LIMIT 100`;
+}
+function buildInvestigationTrust(investigation, selected, sqlError) {
+    return {
+        label: 'AI-generated research',
+        uncertified: true,
+        reviewStatus: 'needs_review',
+        certifiedContext: selectedString(selected, 'certificationStatus') === 'certified' ? 'selected tile is certified' : 'selected tile certification needs review',
+        sourceBlockId: investigation.sourceBlockId ?? selectedString(selected, 'blockId'),
+        sourceTileId: investigation.sourceTileId ?? selectedString(selected, 'tileId'),
+        caveats: [
+            'Investigation output is not certified until a reviewer promotes or certifies the generated block.',
+            ...(sqlError ? [`SQL preview caveat: ${sqlError}`] : []),
+        ],
+    };
+}
+function investigationSteps(intent) {
+    const common = ['trust check', 'evidence capture'];
+    if (intent === 'trust_gap_review')
+        return ['certification review', 'lineage review', 'owner and caveat check', ...common];
+    if (intent === 'entity_drilldown')
+        return ['entity value match', 'metric trend', 'exception rows', ...common];
+    if (intent === 'segment_compare')
+        return ['segment grouping', 'baseline comparison', 'top movers', ...common];
+    if (intent === 'anomaly_investigation')
+        return ['baseline comparison', 'trend check', 'exception rows', 'top movers', ...common];
+    if (intent === 'diagnose_change')
+        return ['baseline comparison', 'trend check', 'top movers', 'segment contribution', ...common];
+    return ['top movers', 'segment contribution', 'exception rows', ...common];
+}
+function investigationAssumptions(intent, selected, generatedSql, sqlError) {
+    return [
+        `Intent classified as ${intent}.`,
+        selected ? 'The selected dashboard tile is the starting context.' : 'No selected tile context was provided.',
+        generatedSql ? 'A generated SQL preview was requested and bounded to 100 rows.' : 'No generated SQL was supplied, so the first pass used dashboard result samples and metadata.',
+        sqlError ? `SQL preview needs review: ${sqlError}` : 'The result remains uncertified until reviewed.',
+    ];
+}
+function buildInvestigationSummary(intent, question, selected, metrics, drivers) {
+    const target = selectedString(selected, 'title') ?? 'this dashboard question';
+    const delta = typeof metrics.delta === 'number' ? ` Delta from the sampled baseline is ${formatContribution(metrics.delta)}.` : '';
+    if (intent === 'trust_gap_review') {
+        return `This tile can be used as certified context only where its source block and lineage are certified. The deeper answer is AI-generated research and needs review before leaders rely on it.${delta}`;
+    }
+    const driver = drivers[0]?.title ? ` Top visible driver in the current evidence is ${drivers[0].title}.` : '';
+    return `DQL opened a review-required investigation for ${target}: ${question}.${delta}${driver}`;
+}
+function buildInvestigationRecommendation(intent, selected, sqlError) {
+    if (sqlError)
+        return 'Review the generated SQL or add a certified drilldown block before promoting this result.';
+    if (intent === 'trust_gap_review')
+        return 'Use the certified tile for reporting, and promote only the reviewed gaps into a draft block.';
+    if (!selected)
+        return 'Select a dashboard tile or provide SQL so DQL can rank drivers with stronger evidence.';
+    return 'Review the driver evidence, then pin the useful answer or promote the SQL path into a draft DQL block.';
+}
+function investigationPreviewResult(investigation) {
+    const previews = Array.isArray(investigation.resultPreviews) ? investigation.resultPreviews : [];
+    const first = previews.find((preview) => asRecord(preview)?.result);
+    return asRecord(first)?.result;
+}
+function investigationCitations(investigation) {
+    return [{
+            kind: 'app_investigation',
+            name: investigation.title,
+            reviewStatus: investigation.reviewStatus,
+            uncertified: true,
+            sourceBlockId: investigation.sourceBlockId,
+            sourceTileId: investigation.sourceTileId,
+        }];
+}
+function nextResearchFollowUps(investigation) {
+    const target = investigation.sourceBlockId ?? investigation.sourceTileId ?? 'this result';
+    return [
+        `Break ${target} down by the strongest segment`,
+        `Show exception rows for ${target}`,
+        `What would need review before certifying this answer?`,
+    ];
+}
+function titleFromInvestigation(question, selected) {
+    const selectedTitle = selectedString(selected, 'title');
+    const base = selectedTitle ? `${selectedTitle}: ${question}` : question;
+    return base.replace(/\s+/g, ' ').slice(0, 90);
+}
+function selectedRows(selected) {
+    const rows = Array.isArray(selected?.sampleRows)
+        ? selected?.sampleRows
+        : Array.isArray(selected?.resultSample)
+            ? selected?.resultSample
+            : selected?.rows;
+    if (!Array.isArray(rows))
+        return [];
+    return rows.map(asRecord).filter((row) => Boolean(row)).slice(0, 100);
+}
+function selectedColumns(selected, rows) {
+    const columns = selected?.columns;
+    if (Array.isArray(columns) && columns.length > 0) {
+        return columns.map(String).filter(Boolean).slice(0, 20);
+    }
+    return Object.keys(rows[0] ?? {}).slice(0, 20);
+}
+function typeofNumber(value) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value === 'string' && value.trim() && Number.isFinite(Number(value)))
+        return Number(value);
+    return null;
+}
+function formatContribution(value) {
+    const rounded = Math.abs(value) >= 100 ? Math.round(value).toLocaleString() : Number(value.toFixed(2)).toLocaleString();
+    return value >= 0 ? `+${rounded}` : `-${rounded.replace(/^-/, '')}`;
+}
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+}
 function cleanString(value) {
     return typeof value === 'string' ? value.trim() : '';
 }
@@ -1145,6 +2070,7 @@ function loadAppById(projectRoot, id) {
             notebooks: listAppNotebookRefs(projectRoot, document, appDir),
             drafts: listAppDrafts(projectRoot, appDir),
             aiPins: listAiPins(projectRoot, document.id),
+            investigations: listAppInvestigations(projectRoot, document.id),
         };
     }
     return null;
@@ -1422,6 +2348,9 @@ function scanFiles(root, extension) {
 function countAiPins(projectRoot, appId) {
     return listAiPins(projectRoot, appId).length;
 }
+function countAppInvestigations(projectRoot, appId) {
+    return listAppInvestigations(projectRoot, appId).length;
+}
 function listAiPins(projectRoot, appId) {
     const dbPath = defaultLocalAppsDbPath(projectRoot);
     if (!existsSync(dbPath))
@@ -1441,6 +2370,23 @@ function listAiPins(projectRoot, appId) {
         return [];
     }
 }
+function listAppInvestigations(projectRoot, appId) {
+    const dbPath = defaultLocalAppsDbPath(projectRoot);
+    if (!existsSync(dbPath))
+        return [];
+    try {
+        const storage = new LocalAppStorage(dbPath);
+        try {
+            return storage.listAppInvestigations(appId);
+        }
+        finally {
+            storage.close();
+        }
+    }
+    catch {
+        return [];
+    }
+}
 function listDashboardsFor(projectRoot, id) {
     const result = loadAppById(projectRoot, id);
     return result?.dashboards ?? null;
@@ -1527,6 +2473,12 @@ async function readJson(req) {
         req.on('error', reject);
     });
 }
+export const __test__ = {
+    buildPreviewDriverCards,
+    buildPreviewMetricSnapshot,
+    buildDeterministicInvestigationSql,
+    selectedBlockContext,
+};
 // reference unused parseAppDocument/readFileSync to keep import stable for forward use
 void parseAppDocument;
 void readFileSync;