Skip to content

Open-source agentic AI Search Execution Platform. Track AI visibility, find opportunities, and let agents turn signals into prioritized actions and drafted fixes across ChatGPT, Claude, Gemini, Google AI Overviews, Google AI Mode, Perplexity, Grok, and Microsoft Copilot.

feat: show fan-out coverage next to sub-query count in the by-prompt view (#651)

jorge arambula3fe893a6c97e
diff --git a/supabase/seed.sql b/supabase/seed.sql
index c32d988c2..7c1242ee4 100644
--- a/supabase/seed.sql
+++ b/supabase/seed.sql
@@ -177,6 +177,15 @@ INSERT INTO public.prompts (
'Manual vs automatic espresso machine for home use',
ARRAY['chatgpt-web','claude','copilot-web','gemini-web','grok-web'],
ARRAY['US','TR','DE'],
+ ARRAY['claude-sonnet-4-6'], true),
+ -- Tracked ONLY on engines that never fan out, and factual enough that they
+ -- answer it from parametric knowledge. It is the Query Fan-out tab's
+ -- zero-coverage case: many tracked answers, not one live search. See the
+ -- "Zero fan-out coverage" block at the end of this file.
+ ('88888888-8888-8888-8888-888888888807', '66666666-6666-6666-6666-666666666601', '77777777-7777-7777-7777-777777777702',
+ 'How much caffeine is in a double espresso?',
+ ARRAY['chatgpt-web','claude'],
+ ARRAY['US','GB','DE','FR','TR'],
ARRAY['claude-sonnet-4-6'], true)
ON CONFLICT (id) DO NOTHING;
@@ -611,3 +620,24 @@ SET search_queries = '[
]'::jsonb
WHERE prompt_id = '88888888-8888-8888-8888-888888888806' AND platform = 'copilot-web';
+-- ─── Zero fan-out coverage (prompt 807) ──────────────────────────────────────
+-- Deliberately NOT given any search_queries: prompt 807 is tracked only on
+-- chatgpt-web and claude, which answer a factual question from what they
+-- already know instead of searching. It is the case the By-prompt view's
+-- coverage column exists for — the prompt reads as "0 / 15 · 0%", which the
+-- sub-query → prompt inversion alone could never produce, since a prompt with
+-- no observed sub-queries has nothing to hang a row on.
+--
+-- The results themselves come from the generator above, which spreads
+-- created_at at 6h intervals ordered by prompt id — so the last prompts in the
+-- set land months back, outside every window the UI offers. Pull 807's rows
+-- into the recent past so the zero-coverage row is actually visible.
+UPDATE public.prompt_results pr
+SET created_at = now() - (ordered.k * interval '5 hours')
+FROM (
+ SELECT id, row_number() OVER (ORDER BY platform, model_used, region) AS k
+ FROM public.prompt_results
+ WHERE prompt_id = '88888888-8888-8888-8888-888888888807'
+) AS ordered
+WHERE pr.id = ordered.id;
+
diff --git a/web/src/app/[locale]/(dashboard)/dashboard/prompts/_fanout-tab.tsx b/web/src/app/[locale]/(dashboard)/dashboard/prompts/_fanout-tab.tsx
index 34c88716d..780c2eea9 100644
--- a/web/src/app/[locale]/(dashboard)/dashboard/prompts/_fanout-tab.tsx
+++ b/web/src/app/[locale]/(dashboard)/dashboard/prompts/_fanout-tab.tsx
@@ -34,6 +34,10 @@ type View = 'frequency' | 'by-prompt';
interface PromptGroup {
prompt: { id: string; text: string };
subQueries: FanoutSubQuery[];
+ /** Tracked answers for this prompt in the window (the coverage denominator). */
+ totalRuns: number;
+ /** Of those, how many triggered at least one live search. */
+ runsWithFanout: number;
}
type QueryFanoutTabProps = {
@@ -142,7 +146,7 @@ export function QueryFanoutTab({ brandId, onTracked }: QueryFanoutTabProps) {
} catch (err) {
console.error('[fanout] load failed', err);
toast.error(userErrorMessage(err, 'Failed to load query fan-out — please retry.'));
- setData({ subQueries: [], totalObserved: 0 });
+ setData({ subQueries: [], totalObserved: 0, promptCoverage: [], truncated: false });
} finally {
if (!silent) {
setLoading(false);
@@ -168,19 +172,39 @@ export function QueryFanoutTab({ brandId, onTracked }: QueryFanoutTabProps) {
setSearchText('');
}, [view]);
- // Invert sub-query → prompts into prompt → sub-queries for the "By prompt" view.
+ // Seed from the server's coverage list so every prompt with a run in the
+ // window gets a row — including the ones the engines never searched for,
+ // which the sub-query → prompts inversion alone can't produce. Then invert
+ // sub-query → prompts to hang each prompt's observed fan-out off its row.
const byPrompt = useMemo<PromptGroup[]>(() => {
if (!data) return [];
const map = new Map<string, PromptGroup>();
+ for (const c of data.promptCoverage) {
+ map.set(c.id, {
+ prompt: { id: c.id, text: c.text },
+ subQueries: [],
+ totalRuns: c.totalRuns,
+ runsWithFanout: c.runsWithFanout,
+ });
+ }
for (const sq of data.subQueries) {
for (const p of sq.sourcedPrompts) {
+ // Defensive: a sourced prompt should always have a coverage entry.
if (!map.has(p.id)) {
- map.set(p.id, { prompt: p, subQueries: [] });
+ map.set(p.id, { prompt: p, subQueries: [], totalRuns: 0, runsWithFanout: 0 });
}
map.get(p.id)!.subQueries.push(sq);
}
}
- return [...map.values()].sort((a, b) => b.subQueries.length - a.subQueries.length);
+ // Text is the final key so the order is fully determined: without it, rows
+ // tied on both counts could reshuffle between renders and appear to jump
+ // pages. The server hands `promptCoverage` over unsorted by design.
+ return [...map.values()].sort(
+ (a, b) =>
+ b.subQueries.length - a.subQueries.length ||
+ b.totalRuns - a.totalRuns ||
+ a.prompt.text.localeCompare(b.prompt.text),
+ );
}, [data]);
const filteredByPrompt = useMemo<PromptGroup[]>(() => {
@@ -189,6 +213,14 @@ export function QueryFanoutTab({ brandId, onTracked }: QueryFanoutTabProps) {
return byPrompt.filter((group) => group.prompt.text.toLowerCase().includes(lower));
}, [byPrompt, searchText]);
+ // The By-prompt list now covers every tracked prompt with a run in the
+ // window, not just those with observed fan-out, so it needs its own pager.
+ const byPromptPager = usePagination(
+ filteredByPrompt.length,
+ `${brandId}::${view}::${searchText}`,
+ FANOUT_PAGE_SIZE,
+ );
+
async function handleTrack(query: string) {
setAddingKey(query.toLowerCase());
try {
@@ -224,7 +256,11 @@ export function QueryFanoutTab({ brandId, onTracked }: QueryFanoutTabProps) {
}
}
- const isEmpty = !data || data.subQueries.length === 0;
+ // Only truly empty when there is nothing to say in EITHER view. Gating on
+ // sub-queries alone hid the By-prompt table for any brand whose engines never
+ // fan out (ChatGPT-only, say) — which is exactly the brand whose 0 / N rows
+ // are the useful answer.
+ const isEmpty = !data || (data.subQueries.length === 0 && data.promptCoverage.length === 0);
return (
<Card>
@@ -260,7 +296,7 @@ export function QueryFanoutTab({ brandId, onTracked }: QueryFanoutTabProps) {
</div>
<p className="text-xs text-muted-foreground">
{view === 'by-prompt'
- ? 'Your tracked prompts grouped by the sub-queries their answers actually triggered — expand a prompt to see its observed fan-out.'
+ ? 'Your tracked prompts grouped by the sub-queries their answers actually triggered — expand a prompt to see its observed fan-out. "Answers with fan-out" is how many of that prompt’s tracked answers ran a live search at all.'
: 'The sub-queries answer engines actually ran while building your answers (last 30 days) — observed, never predicted. Sorted by how often they were searched. Track any of them with the + to measure its own visibility.'}
</p>
</CardHeader>
@@ -288,11 +324,18 @@ export function QueryFanoutTab({ brandId, onTracked }: QueryFanoutTabProps) {
groups={filteredByPrompt}
intents={intents}
addingKey={addingKey}
+ pager={byPromptPager}
onTrack={handleTrack}
searchText={searchText}
onSearchChange={setSearchText}
/>
)}
+ {!loading && data?.truncated && (
+ <p className="pt-3 text-[11px] text-muted-foreground">
+ This brand has more tracked answers in this window than one read covers, so the most
+ recent ones are missing — counts and coverage here are a lower bound.
+ </p>
+ )}
</CardContent>
</Card>
);
@@ -312,6 +355,16 @@ function EmptyState() {
);
}
+/** Zero-row state for a filtered list — the search matched nothing. */
+function NoMatches({ label }: { label: string }) {
+ return (
+ <div className="flex flex-col items-center gap-2 py-12 text-center">
+ <Search className="h-8 w-8 text-muted-foreground/50" />
+ <p className="text-sm font-medium">{label}</p>
+ </div>
+ );
+}
+
function HighFrequencyView({
subQueries,
intents,
@@ -339,10 +392,13 @@ function HighFrequencyView({
placeholder="Search sub-queries…"
/>
{subQueries.length === 0 ? (
- <div className="flex flex-col items-center gap-2 py-12 text-center">
- <Search className="h-8 w-8 text-muted-foreground/50" />
- <p className="text-sm font-medium">No sub-queries match your search</p>
- </div>
+ // Unfiltered and still empty means nothing fanned out at all — the tab
+ // no longer gates on that, so this view has to explain it itself.
+ searchText ? (
+ <NoMatches label="No sub-queries match your search" />
+ ) : (
+ <EmptyState />
+ )
) : (
<>
<Table>
@@ -420,6 +476,7 @@ function ByPromptView({
groups,
intents,
addingKey,
+ pager,
onTrack,
searchText,
onSearchChange,
@@ -427,11 +484,13 @@ function ByPromptView({
groups: PromptGroup[];
intents: Record<string, string>;
addingKey: string | null;
+ pager: ReturnType<typeof usePagination>;
onTrack: (query: string) => void;
searchText: string;
onSearchChange: (text: string) => void;
}) {
const [expanded, setExpanded] = useState<Set<string>>(new Set());
+ const pageRows = groups.slice(pager.start, pager.end);
function toggle(id: string) {
setExpanded((prev) => {
@@ -450,98 +509,133 @@ function ByPromptView({
placeholder="Search prompts…"
/>
{groups.length === 0 ? (
- <div className="flex flex-col items-center gap-2 py-12 text-center">
- <Search className="h-8 w-8 text-muted-foreground/50" />
- <p className="text-sm font-medium">No prompts match your search</p>
- </div>
+ searchText ? (
+ <NoMatches label="No prompts match your search" />
+ ) : (
+ <NoMatches label="No tracked answers in the last 30 days" />
+ )
) : (
- <Table>
- <TableHeader>
- <TableRow>
- <TableHead className="w-[28px]" />
- <TableHead>Prompt</TableHead>
- <TableHead className="w-[110px] text-right">Sub-queries</TableHead>
- </TableRow>
- </TableHeader>
- <TableBody>
- {groups.map(({ prompt, subQueries }) => {
- const isOpen = expanded.has(prompt.id);
- return (
- <Fragment key={prompt.id}>
- <TableRow
- className="cursor-pointer select-none"
- onClick={() => toggle(prompt.id)}
- >
- <TableCell className="pr-0">
- <ChevronRight
- className={cn(
- 'h-4 w-4 text-muted-foreground transition-transform duration-150',
- isOpen && 'rotate-90',
+ <>
+ <Table>
+ <TableHeader>
+ <TableRow>
+ <TableHead className="w-[28px]" />
+ <TableHead>Prompt</TableHead>
+ <TableHead className="w-[170px] text-right">Answers with fan-out</TableHead>
+ <TableHead className="w-[110px] text-right">Sub-queries</TableHead>
+ </TableRow>
+ </TableHeader>
+ <TableBody>
+ {pageRows.map(({ prompt, subQueries, totalRuns, runsWithFanout }) => {
+ // Nothing fanned out — there is no panel to open, so the row
+ // stays inert rather than expanding into an empty box.
+ const expandable = subQueries.length > 0;
+ const isOpen = expandable && expanded.has(prompt.id);
+ return (
+ <Fragment key={prompt.id}>
+ <TableRow
+ className={cn(expandable && 'cursor-pointer select-none')}
+ onClick={expandable ? () => toggle(prompt.id) : undefined}
+ >
+ <TableCell className="pr-0">
+ {expandable && (
+ // The whole row is clickable for the mouse, but a
+ // <tr> can't carry button semantics without breaking
+ // the table for screen readers — so the toggle itself
+ // is the real, focusable control.
+ <button
+ type="button"
+ aria-expanded={isOpen}
+ aria-label={`${isOpen ? 'Hide' : 'Show'} fan-out for "${prompt.text}"`}
+ className="flex items-center rounded-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+ onClick={(e) => {
+ e.stopPropagation();
+ toggle(prompt.id);
+ }}
+ >
+ <ChevronRight
+ className={cn(
+ 'h-4 w-4 text-muted-foreground transition-transform duration-150',
+ isOpen && 'rotate-90',
+ )}
+ />
+ </button>
)}
- />
- </TableCell>
- <TableCell className="font-medium">{prompt.text}</TableCell>
- <TableCell className="text-right">
- <Badge variant="secondary" className="tabular-nums text-[10px]">
- {subQueries.length}
- </Badge>
- </TableCell>
- </TableRow>
- {isOpen && (
- <TableRow key={`${prompt.id}-expanded`} className="hover:bg-transparent">
- <TableCell />
- <TableCell colSpan={2} className="pb-3 pt-0">
- <div className="rounded-md border">
- <Table>
- <TableHeader>
- <TableRow>
- <TableHead>Sub-query</TableHead>
- <TableHead className="w-[160px]">Engine</TableHead>
- <TableHead className="w-[120px] text-right">
- Times searched
- </TableHead>
- <TableHead className="w-[130px] pl-6">Intent</TableHead>
- <TableHead className="w-[64px] text-right">Track</TableHead>
- </TableRow>
- </TableHeader>
- <TableBody>
- {subQueries.map((sq) => {
- const key = sq.query.toLowerCase();
- return (
- <TableRow key={key} className="align-middle">
- <TableCell className="align-middle font-medium">
- {sq.query}
- </TableCell>
- <TableCell className="align-middle">
- <PlatformsCell models={sq.engines} />
- </TableCell>
- <TableCell className="align-middle text-right tabular-nums">
- {sq.timesSearched}
- </TableCell>
- <TableCell className="align-middle pl-6">
- <IntentBadge intent={intents[key]} />
- </TableCell>
- <TableCell className="align-middle text-right">
- <TrackCell
- sq={sq}
- adding={addingKey === key}
- onTrack={onTrack}
- />
- </TableCell>
- </TableRow>
- );
- })}
- </TableBody>
- </Table>
- </div>
+ </TableCell>
+ <TableCell className="font-medium">{prompt.text}</TableCell>
+ <TableCell className="text-right">
+ <FanoutCoverageCell totalRuns={totalRuns} runsWithFanout={runsWithFanout} />
+ </TableCell>
+ <TableCell className="text-right">
+ <Badge variant="secondary" className="tabular-nums text-[10px]">
+ {subQueries.length}
+ </Badge>
</TableCell>
</TableRow>
- )}
- </Fragment>
- );
- })}
- </TableBody>
- </Table>
+ {isOpen && (
+ <TableRow key={`${prompt.id}-expanded`} className="hover:bg-transparent">
+ <TableCell />
+ <TableCell colSpan={3} className="pb-3 pt-0">
+ <div className="rounded-md border">
+ <Table>
+ <TableHeader>
+ <TableRow>
+ <TableHead>Sub-query</TableHead>
+ <TableHead className="w-[160px]">Engine</TableHead>
+ <TableHead className="w-[120px] text-right">
+ Times searched
+ </TableHead>
+ <TableHead className="w-[130px] pl-6">Intent</TableHead>
+ <TableHead className="w-[64px] text-right">Track</TableHead>
+ </TableRow>
+ </TableHeader>
+ <TableBody>
+ {subQueries.map((sq) => {
+ const key = sq.query.toLowerCase();
+ return (
+ <TableRow key={key} className="align-middle">
+ <TableCell className="align-middle font-medium">
+ {sq.query}
+ </TableCell>
+ <TableCell className="align-middle">
+ <PlatformsCell models={sq.engines} />
+ </TableCell>
+ <TableCell className="align-middle text-right tabular-nums">
+ {sq.timesSearched}
+ </TableCell>
+ <TableCell className="align-middle pl-6">
+ <IntentBadge intent={intents[key]} />
+ </TableCell>
+ <TableCell className="align-middle text-right">
+ <TrackCell
+ sq={sq}
+ adding={addingKey === key}
+ onTrack={onTrack}
+ />
+ </TableCell>
+ </TableRow>
+ );
+ })}
+ </TableBody>
+ </Table>
+ </div>
+ </TableCell>
+ </TableRow>
+ )}
+ </Fragment>
+ );
+ })}
+ </TableBody>
+ </Table>
+ <TablePager
+ page={pager.page}
+ totalPages={pager.totalPages}
+ total={groups.length}
+ start={pager.start}
+ end={pager.end}
+ onPage={pager.setPage}
+ />
+ </>
)}
</div>
);
@@ -620,6 +714,39 @@ function SourcedPrompts({ prompts }: { prompts: { id: string; text: string }[] }
);
}
+/**
+ * How much of a prompt's tracked volume actually triggered a live search.
+ * Without the denominator "8 sub-queries" is unreadable: 8 out of 10 answers is
+ * a prompt the engines research every time; 8 out of 500 is one they don't.
+ */
+function FanoutCoverageCell({
+ totalRuns,
+ runsWithFanout,
+}: {
+ totalRuns: number;
+ runsWithFanout: number;
+}) {
+ if (totalRuns === 0) return <span className="text-xs text-muted-foreground">—</span>;
+
+ const pct = (runsWithFanout / totalRuns) * 100;
+ // Rounding must not overstate the extremes in either direction: a real but
+ // tiny signal isn't "0%", and 199/200 isn't the complete coverage "100%"
+ // would claim.
+ const label = pct > 0 && pct < 1 ? '<1%' : pct > 99 && pct < 100 ? '>99%' : `${Math.round(pct)}%`;
+
+ return (
+ <span
+ className="text-xs text-muted-foreground tabular-nums"
+ title={
+ `Of ${totalRuns} tracked answers in this window, ${runsWithFanout} triggered live searches. ` +
+ 'Most engines never fan out — Copilot and Perplexity are the main sources.'
+ }
+ >
+ {runsWithFanout} / {totalRuns} · {label}
+ </span>
+ );
+}
+
function IntentBadge({ intent }: { intent?: string }) {
// Intents load on-demand (async, cached server-side); show a placeholder
// until this row's classification resolves.
diff --git a/web/src/lib/actions/fanout.test.ts b/web/src/lib/actions/fanout.test.ts
new file mode 100644
index 000000000..f16e8fcc8
--- /dev/null
+++ b/web/src/lib/actions/fanout.test.ts
@@ -0,0 +1,298 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+/**
+ * Coverage arithmetic for the By-prompt view: `runsWithFanout / totalRuns` is
+ * the denominator that tells "the engines never search for this prompt" apart
+ * from "we barely track this prompt". It is derived from the same single pass
+ * over prompt_results that builds the sub-query list, so the two views can
+ * never disagree — these tests pin that contract.
+ */
+
+interface QueryState {
+ table: string;
+ eq: Record<string, unknown>;
+ inFilter?: { column: string; values: string[] };
+ range?: [number, number];
+}
+
+const SET_ID = 'set-1';
+
+type ResultRow = {
+ prompt_id: string | null;
+ platform: string | null;
+ search_queries: unknown;
+};
+
+type PromptRow = { id: string; text: string; is_active: boolean };
+
+let resultRows: ResultRow[] = [];
+let rosterRows: PromptRow[] = [];
+/** Prompts reachable only by id — e.g. moved out of the brand's sets. */
+let residualRows: PromptRow[] = [];
+let promptSetRows: { id: string }[] = [];
+/** When set, prompt_results always returns a full page (drives truncation). */
+let alwaysFullPage = false;
+let residualError: string | null = null;
+let calls: QueryState[] = [];
+
+function resolveQuery(state: QueryState): {
+ data: unknown[] | null;
+ error: { message: string } | null;
+} {
+ const slice = <T>(rows: T[]): T[] => {
+ if (!state.range) return rows;
+ const [from, to] = state.range;
+ return rows.slice(from, to + 1);
+ };
+
+ if (state.table === 'prompt_results') {
+ if (alwaysFullPage) {
+ const [from, to] = state.range ?? [0, 0];
+ return { data: Array.from({ length: to - from + 1 }, () => resultRows[0]), error: null };
+ }
+ const rows = resultRows.filter(
+ (r) => state.eq.prompt_id === undefined || r.prompt_id === state.eq.prompt_id,
+ );
+ return { data: slice(rows), error: null };
+ }
+
+ if (state.table === 'prompt_sets') return { data: promptSetRows, error: null };
+
+ if (state.table === 'prompts') {
+ if (state.inFilter?.column === 'prompt_set_id') return { data: slice(rosterRows), error: null };
+ if (state.inFilter?.column === 'id') {
+ if (residualError) return { data: null, error: { message: residualError } };
+ const ids = new Set(state.inFilter.values);
+ return { data: residualRows.filter((p) => ids.has(p.id)), error: null };
+ }
+ }
+
+ return { data: [], error: null };
+}
+
+function fakeQueryBuilder(table: string) {
+ const state: QueryState = { table, eq: {} };
+ const builder = {
+ select: () => builder,
+ eq: (column: string, value: unknown) => {
+ state.eq[column] = value;
+ return builder;
+ },
+ gte: () => builder,
+ order: () => builder,
+ in: (column: string, values: string[]) => {
+ state.inFilter = { column, values };
+ return builder;
+ },
+ range: (from: number, to: number) => {
+ state.range = [from, to];
+ return builder;
+ },
+ // PostgREST builders are thenables — awaiting one runs the query.
+ then: (onFulfilled: (v: unknown) => unknown, onRejected?: (e: unknown) => unknown) => {
+ calls.push({ ...state, eq: { ...state.eq } });
+ return Promise.resolve(resolveQuery(state)).then(onFulfilled, onRejected);
+ },
+ };
+ return builder;
+}
+
+vi.mock('@/lib/supabase/server', () => ({
+ createClient: async () => ({ from: (table: string) => fakeQueryBuilder(table) }),
+}));
+
+vi.mock('next/cache', () => ({ revalidatePath: vi.fn() }));
+
+vi.mock('@/lib/actions/prompt', () => ({ addPromptToSet: vi.fn() }));
+
+function answer(prompt_id: string | null, queries: unknown, platform = 'copilot'): ResultRow {
+ return { prompt_id, platform, search_queries: queries };
+}
+
+const q = (query: string) => ({ query, source_platform: 'copilot' });
+
+beforeEach(() => {
+ calls = [];
+ alwaysFullPage = false;
+ residualError = null;
+ promptSetRows = [{ id: SET_ID }];
+ rosterRows = [
+ { id: 'p-loud', text: 'Best AEO monitoring tools?', is_active: true },
+ { id: 'p-quiet', text: 'How do I track brand mentions?', is_active: true },
+ { id: 'p-paused', text: 'Legacy prompt', is_active: false },
+ { id: 'p-tracked', text: 'AEO Tools', is_active: true },
+ ];
+ residualRows = [{ id: 'p-external', text: 'Moved to another set', is_active: true }];
+ resultRows = [
+ // Searches on two of its three answers.
+ answer('p-loud', [q('aeo tools'), q('best aeo software')]),
+ answer('p-loud', [q('aeo tools')]),
+ answer('p-loud', []),
+ // Runs constantly, never triggers a search — the row that could not exist
+ // before coverage, since the sub-query → prompt inversion had nothing to
+ // hang it on.
+ answer('p-quiet', []),
+ answer('p-quiet', []),
+ answer('p-quiet', [{ query: ' ' }, { query: 42 }, {}]),
+ answer('p-quiet', null),
+ // Same sub-query twice in one answer counts once.
+ answer('p-paused', [q('legacy lookup'), q('Legacy Lookup')]),
+ // No prompt attribution: contributes fan-out, but to no coverage bucket.
+ answer(null, [q('orphan query')]),
+ answer('p-external', [q('aeo tools')]),
+ ];
+});
+
+describe('getQueryFanout — prompt coverage', () => {
+ it('reports a prompt that ran but never triggered a search as 0 of N', async () => {
+ const { getQueryFanout } = await import('./fanout');
+
+ const { promptCoverage } = await getQueryFanout('brand-1');
+
+ expect(promptCoverage).toContainEqual({
+ id: 'p-quiet',
+ text: 'How do I track brand mentions?',
+ totalRuns: 4,
+ runsWithFanout: 0,
+ });
+ });
+
+ it('counts blank and non-string sub-queries toward the denominator only', async () => {
+ const { getQueryFanout } = await import('./fanout');
+
+ const { promptCoverage, subQueries } = await getQueryFanout('brand-1');
+
+ // The row with ' ' / 42 / {} is a run, but not a run with fan-out.
+ const quiet = promptCoverage.find((p) => p.id === 'p-quiet')!;
+ expect(quiet.totalRuns).toBe(4);
+ expect(quiet.runsWithFanout).toBe(0);
+ // …and none of that junk leaked into the sub-query list.
+ expect(subQueries.map((s) => s.query)).not.toContain('');
+ });
+
+ it('splits a partially-searched prompt as runs-with-fanout over total runs', async () => {
+ const { getQueryFanout } = await import('./fanout');
+
+ const { promptCoverage } = await getQueryFanout('brand-1');
+
+ expect(promptCoverage.find((p) => p.id === 'p-loud')).toMatchObject({
+ totalRuns: 3,
+ runsWithFanout: 2,
+ });
+ });
+
+ it('counts an answer once when it repeats the same sub-query', async () => {
+ const { getQueryFanout } = await import('./fanout');
+
+ const { promptCoverage, subQueries } = await getQueryFanout('brand-1');
+
+ expect(promptCoverage.find((p) => p.id === 'p-paused')).toMatchObject({
+ totalRuns: 1,
+ runsWithFanout: 1,
+ });
+ // 'legacy lookup' and 'Legacy Lookup' normalize to one row, one answer.
+ expect(subQueries.find((s) => s.query === 'legacy lookup')?.timesSearched).toBe(1);
+ });
+
+ it('excludes answers with no prompt attribution from coverage but not from fan-out', async () => {
+ const { getQueryFanout } = await import('./fanout');
+
+ const { promptCoverage, subQueries } = await getQueryFanout('brand-1');
+
+ expect(promptCoverage.map((p) => p.id)).not.toContain(null);
+ expect(promptCoverage).toHaveLength(4); // loud, quiet, paused, external
+ expect(subQueries.map((s) => s.query)).toContain('orphan query');
+ });
+
+ it('gives every sourced prompt a coverage entry', async () => {
+ const { getQueryFanout } = await import('./fanout');
+
+ const { promptCoverage, subQueries } = await getQueryFanout('brand-1');
+
+ const covered = new Set(promptCoverage.map((p) => p.id));
+ const sourced = subQueries.flatMap((s) => s.sourcedPrompts.map((p) => p.id));
+ expect(sourced.length).toBeGreaterThan(0);
+ for (const id of sourced) expect(covered).toContain(id);
+ });
+
+ it('never reports more searched runs than total runs', async () => {
+ const { getQueryFanout } = await import('./fanout');
+
+ const { promptCoverage } = await getQueryFanout('brand-1');
+
+ for (const p of promptCoverage) {
+ expect(p.runsWithFanout).toBeLessThanOrEqual(p.totalRuns);
+ }
+ });
+
+ it('includes paused prompts that ran inside the window', async () => {
+ const { getQueryFanout } = await import('./fanout');
+
+ const { promptCoverage, subQueries } = await getQueryFanout('brand-1');
+
+ expect(promptCoverage.map((p) => p.id)).toContain('p-paused');
+ // …but a paused prompt must not make its text read as "Tracked ✓".
+ expect(subQueries.find((s) => s.query === 'legacy lookup')?.tracked).toBe(false);
+ });
+});
+
+describe('getQueryFanout — prompt lookups', () => {
+ it('serves text and the tracked-prompt map from one roster read', async () => {
+ const { getQueryFanout } = await import('./fanout');
+
+ await getQueryFanout('brand-1');
+
+ const promptReads = calls.filter((c) => c.table === 'prompts');
+ // One paged roster read + exactly one residual chunk for p-external.
+ expect(promptReads.filter((c) => c.inFilter?.column === 'prompt_set_id')).toHaveLength(1);
+ expect(promptReads.filter((c) => c.inFilter?.column === 'id')).toHaveLength(1);
+ });
+
+ it('skips the residual lookup entirely when the roster covers every prompt', async () => {
+ resultRows = resultRows.filter((r) => r.prompt_id !== 'p-external');
+ const { getQueryFanout } = await import('./fanout');
+
+ await getQueryFanout('brand-1');
+
+ expect(calls.filter((c) => c.inFilter?.column === 'id')).toHaveLength(0);
+ });
+
+ it('matches tracked prompts case- and whitespace-insensitively', async () => {
+ const { getQueryFanout } = await import('./fanout');
+
+ const { subQueries } = await getQueryFanout('brand-1');
+
+ // Roster text 'AEO Tools' vs observed sub-query 'aeo tools'.
+ expect(subQueries.find((s) => s.query === 'aeo tools')).toMatchObject({
+ tracked: true,
+ trackedPromptId: 'p-tracked',
+ });
+ });
+
+ it('fails loudly when a prompt-text chunk errors instead of dropping rows', async () => {
+ residualError = 'connection reset';
+ const { getQueryFanout } = await import('./fanout');
+
+ // Silently swallowing this would delete p-external from both views, and an
+ // under-reported table is indistinguishable from a correct smaller one.
+ await expect(getQueryFanout('brand-1')).rejects.toThrow('connection reset');
+ });
+});
+
+describe('getQueryFanout — window truncation', () => {
+ it('reports a complete read as untruncated', async () => {
+ const { getQueryFanout } = await import('./fanout');
+
+ await expect(getQueryFanout('brand-1')).resolves.toMatchObject({ truncated: false });
+ });
+
+ it('flags the read when the window exceeds the row ceiling', async () => {
+ alwaysFullPage = true;
+ const { getQueryFanout } = await import('./fanout');
+
+ // Every page comes back full, so the loop exits on the ceiling rather than
+ // on the end of the window — the newest answers are missing and the ratios
+ // are a lower bound.
+ await expect(getQueryFanout('brand-1')).resolves.toMatchObject({ truncated: true });
+ });
+});
diff --git a/web/src/lib/actions/fanout.ts b/web/src/lib/actions/fanout.ts
index d9a1ab141..fc45397ce 100644
--- a/web/src/lib/actions/fanout.ts
+++ b/web/src/lib/actions/fanout.ts
@@ -32,10 +32,36 @@ export interface FanoutSubQuery {
trackedPromptId: string | null;
}
+export interface FanoutPromptCoverage {
+ id: string;
+ text: string;
+ /** All tracked answers for this prompt inside the fetched window. */
+ totalRuns: number;
+ /** Of those, how many contained at least one observed sub-query. */
+ runsWithFanout: number;
+}
+
export interface QueryFanoutData {
subQueries: FanoutSubQuery[];
/** Total distinct observed sub-queries in the window. */
totalObserved: number;
+ /**
+ * Per-prompt fan-out coverage over the same fetched window as `subQueries`,
+ * including prompts whose answers triggered no search at all (0 / N) — the
+ * denominator that tells "engines never search for this" apart from "we
+ * barely track it". Empty for the single-prompt variant.
+ *
+ * Unordered: the caller owns display ranking (see the By-prompt view, which
+ * ranks by sub-query count). Only a stable baseline sort is applied here.
+ */
+ promptCoverage: FanoutPromptCoverage[];
+ /**
+ * True when the window held more answers than `FANOUT_MAX_ROWS` and the read
+ * stopped early. Rows come back oldest-first, so it's the MOST RECENT answers
+ * that are missing — counts under-report and coverage ratios are only
+ * approximate. The UI says so rather than presenting a confident wrong ratio.
+ */
+ truncated: boolean;
}
interface RawSearchQueryItem {
@@ -56,6 +82,21 @@ const MAX_FANOUT_DAYS = 90;
const FANOUT_PAGE_SIZE = 1000;
const FANOUT_MAX_ROWS = 50_000;
+/**
+ * Chunk size for the residual `.in('id', …)` prompt-text lookup. The binding
+ * constraint is URL length, not the row cap: PostgREST takes the id list in the
+ * query string, and 100 UUIDs is already ~3.7KB against the ~8KB request line
+ * most proxies allow, which the base URL and auth params also draw on.
+ */
+const PROMPT_TEXT_CHUNK_SIZE = 100;
+
+/**
+ * Ceiling on the brand's prompt roster read (see fetchBrandPromptRoster), in the
+ * same spirit as FANOUT_MAX_ROWS: plan limits put real rosters orders of
+ * magnitude below this.
+ */
+const PROMPT_ROSTER_MAX_ROWS = 20_000;
+
/** How long the intent-classification round-trip may take before we abort (#427). */
const FANOUT_INTENT_FETCH_TIMEOUT_MS = 20_000;
@@ -70,7 +111,7 @@ async function fetchFanoutRows(
brandId: string,
since: string,
promptId?: string,
-): Promise<FanoutResultRow[]> {
+): Promise<{ rows: FanoutResultRow[]; truncated: boolean }> {
const rows: FanoutResultRow[] = [];
for (let from = 0; from < FANOUT_MAX_ROWS; from += FANOUT_PAGE_SIZE) {
let query = supabase
@@ -89,9 +130,57 @@ async function fetchFanoutRows(
const batch = (data ?? []) as FanoutResultRow[];
rows.push(...batch);
+ // A short page means we reached the end of the window — the only exit that
+ // guarantees a complete read.
+ if (batch.length < FANOUT_PAGE_SIZE) return { rows, truncated: false };
+ }
+ return { rows, truncated: true };
+}
+
+interface RosterPrompt {
+ id: string;
+ text: string;
+ is_active: boolean;
+}
+
+/**
+ * Every prompt belonging to the brand, paused ones included. One read serves
+ * both jobs downstream: resolving prompt text for coverage / sourced-prompt rows,
+ * and the "is this sub-query already tracked?" comparison — which used to be two
+ * queries over almost exactly the same rows.
+ *
+ * Paged for the same reason the result fetch is (#427/#428): an un-paginated
+ * select is silently capped at 1000 rows by PostgREST, which quietly truncated
+ * the tracked-prompt map on brands with the largest prompt sets.
+ */
+async function fetchBrandPromptRoster(
+ supabase: Awaited<ReturnType<typeof createClient>>,
+ brandId: string,
+): Promise<RosterPrompt[]> {
+ const { data: brandSets, error: setsError } = await supabase
+ .from('prompt_sets')
+ .select('id')
+ .eq('brand_id', brandId);
+ if (setsError) throw new Error(setsError.message);
+
+ const setIds = (brandSets ?? []).map((s) => s.id as string);
+ if (setIds.length === 0) return [];
+
+ const prompts: RosterPrompt[] = [];
+ for (let from = 0; from < PROMPT_ROSTER_MAX_ROWS; from += FANOUT_PAGE_SIZE) {
+ const { data, error } = await supabase
+ .from('prompts')
+ .select('id, text, is_active')
+ .in('prompt_set_id', setIds)
+ .order('id', { ascending: true })
+ .range(from, from + FANOUT_PAGE_SIZE - 1);
+ if (error) throw new Error(error.message);
+
+ const batch = (data ?? []) as RosterPrompt[];
+ prompts.push(...batch);
if (batch.length < FANOUT_PAGE_SIZE) break;
}
- return rows;
+ return prompts;
}
/**
@@ -124,8 +213,9 @@ export async function getQueryFanout(
// No server-side "non-empty" filter: comparing a jsonb column to '[]' through
// PostgREST is unreliable, and rows with an empty fan-out contribute nothing
- // to the aggregation below anyway (the item loop skips them).
- const rows = await fetchFanoutRows(supabase, brandId, since);
+ // to the sub-query aggregation below (the item loop skips them) — but they do
+ // count toward coverage, which is the whole point of the denominator.
+ const { rows, truncated } = await fetchFanoutRows(supabase, brandId, since);
interface Acc {
display: string;
@@ -135,7 +225,29 @@ export async function getQueryFanout(
}
const byQuery = new Map<string, Acc>();
- for (const row of rows ?? []) {
+ /**
+ * Fan-out coverage per prompt, from the exact same fetched rows: how many of
+ * a prompt's tracked answers triggered a live search at all. Without this
+ * denominator "8 sub-queries" reads the same whether it came from 10 answers
+ * or 500 — and a prompt the engines never search for is invisible entirely.
+ */
+ interface CoverageAcc {
+ totalRuns: number;
+ runsWithFanout: number;
+ }
+ const coverageByPrompt = new Map<string, CoverageAcc>();
+
+ for (const row of rows) {
+ let coverage: CoverageAcc | undefined;
+ if (row.prompt_id) {
+ coverage = coverageByPrompt.get(row.prompt_id);
+ if (!coverage) {
+ coverage = { totalRuns: 0, runsWithFanout: 0 };
+ coverageByPrompt.set(row.prompt_id, coverage);
+ }
+ coverage.totalRuns += 1;
+ }
+
const items = Array.isArray(row.search_queries)
? (row.search_queries as RawSearchQueryItem[])
: [];
@@ -165,40 +277,43 @@ export async function getQueryFanout(
seenInRow.add(key);
}
}
+ // `seenInRow` is only written to past the validity guard above, so a
+ // non-empty set means this answer contributed at least one real sub-query.
+ if (coverage && seenInRow.size > 0) coverage.runsWithFanout += 1;
}
- if (byQuery.size === 0) return { subQueries: [], totalObserved: 0 };
-
- // Resolve the sourced prompts' text (the prompts whose answers produced the
- // fan-out) so the UI can link back to them.
- const allPromptIds = [...new Set([...byQuery.values()].flatMap((a) => [...a.promptIds]))];
- const promptTextById = new Map<string, string>();
- if (allPromptIds.length > 0) {
- const { data: promptRows } = await supabase
- .from('prompts')
- .select('id, text')
- .in('id', allPromptIds);
- for (const p of promptRows ?? []) {
- promptTextById.set(p.id as string, p.text as string);
- }
+ if (byQuery.size === 0 && coverageByPrompt.size === 0) {
+ return { subQueries: [], totalObserved: 0, promptCoverage: [], truncated };
}
+ const roster = await fetchBrandPromptRoster(supabase, brandId);
+
+ // Prompt text for every prompt with a run in the window — a superset of the
+ // fan-out-sourced prompts, since coverage reports the zero rows too. Paused
+ // prompts are included: they did run in the window, so their answers count.
+ const promptTextById = new Map<string, string>();
// Which sub-queries are already tracked as prompts for THIS brand? Compare
- // against the brand's active prompt texts so the row shows Tracked ✓ vs +.
- const { data: brandSets } = await supabase
- .from('prompt_sets')
- .select('id')
- .eq('brand_id', brandId);
- const setIds = (brandSets ?? []).map((s) => s.id as string);
+ // against the brand's ACTIVE prompt texts so the row shows Tracked ✓ vs +.
const trackedByText = new Map<string, string>();
- if (setIds.length > 0) {
- const { data: existing } = await supabase
+ for (const p of roster) {
+ promptTextById.set(p.id, p.text);
+ if (p.is_active) trackedByText.set(normalizeQuery(p.text).toLowerCase(), p.id);
+ }
+
+ // Whatever the roster didn't cover — a prompt moved to another set, or removed
+ // mid-window — still needs its text, or its coverage row silently disappears.
+ const missingIds = [...coverageByPrompt.keys()].filter((id) => !promptTextById.has(id));
+ for (let i = 0; i < missingIds.length; i += PROMPT_TEXT_CHUNK_SIZE) {
+ const { data: promptRows, error } = await supabase
.from('prompts')
.select('id, text')
- .in('prompt_set_id', setIds)
- .eq('is_active', true);
- for (const p of existing ?? []) {
- trackedByText.set(normalizeQuery(p.text as string).toLowerCase(), p.id as string);
+ .in('id', missingIds.slice(i, i + PROMPT_TEXT_CHUNK_SIZE));
+ // A dropped chunk deletes whole rows from both views (text is the filter
+ // below), and an under-reported table looks exactly like a correct smaller
+ // one — so fail loudly instead of degrading invisibly.
+ if (error) throw new Error(error.message);
+ for (const p of promptRows ?? []) {
+ promptTextById.set(p.id as string, p.text as string);
}
}
@@ -220,7 +335,21 @@ export async function getQueryFanout(
})
.sort((a, b) => b.timesSearched - a.timesSearched || a.query.localeCompare(b.query));
- return { subQueries, totalObserved: subQueries.length };
+ // Prompts whose text no longer resolves (hard-deleted) are dropped, matching
+ // how `sourcedPrompts` already treats them. Sorted by text only: a stable,
+ // deterministic baseline. Display ranking belongs to the caller, which ranks
+ // by sub-query count — duplicating that here would just be discarded work.
+ const promptCoverage: FanoutPromptCoverage[] = [...coverageByPrompt.entries()]
+ .map(([id, acc]) => ({
+ id,
+ text: promptTextById.get(id) ?? '',
+ totalRuns: acc.totalRuns,
+ runsWithFanout: acc.runsWithFanout,
+ }))
+ .filter((p) => p.text)
+ .sort((a, b) => a.text.localeCompare(b.text));
+
+ return { subQueries, totalObserved: subQueries.length, promptCoverage, truncated };
}
/**
@@ -319,7 +448,7 @@ export async function getPromptFanout(
const days = Math.min(Math.max(Math.trunc(opts?.days ?? 30) || 30, 1), MAX_FANOUT_DAYS);
const since = new Date(Date.now() - days * 86_400_000).toISOString();
- const rows = await fetchFanoutRows(supabase, brandId, since, promptId);
+ const { rows, truncated } = await fetchFanoutRows(supabase, brandId, since, promptId);
interface Acc {
display: string;
@@ -328,7 +457,7 @@ export async function getPromptFanout(
}
const byQuery = new Map<string, Acc>();
- for (const row of rows ?? []) {
+ for (const row of rows) {
const items = Array.isArray(row.search_queries)
? (row.search_queries as RawSearchQueryItem[])
: [];
@@ -357,7 +486,11 @@ export async function getPromptFanout(
}
}
- if (byQuery.size === 0) return { subQueries: [], totalObserved: 0 };
+ // `promptCoverage` stays empty here: this variant answers for a single prompt
+ // and has no prompt roster to report coverage over.
+ if (byQuery.size === 0) {
+ return { subQueries: [], totalObserved: 0, promptCoverage: [], truncated };
+ }
const subQueries: FanoutSubQuery[] = [...byQuery.entries()]
.map(([, acc]) => ({
@@ -370,5 +503,5 @@ export async function getPromptFanout(
}))
.sort((a, b) => b.timesSearched - a.timesSearched || a.query.localeCompare(b.query));
- return { subQueries, totalObserved: subQueries.length };
+ return { subQueries, totalObserved: subQueries.length, promptCoverage: [], truncated };
}