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(signals): record what a lost citation rests on and show it (#1061)

Cihan4685e492fa55
diff --git a/server/src/lib/pulse/metrics.js b/server/src/lib/pulse/metrics.js
index 33bbe01b8..670a14814 100644
--- a/server/src/lib/pulse/metrics.js
+++ b/server/src/lib/pulse/metrics.js
@@ -314,6 +314,9 @@ async function newEngineAppearances(brandId, from) {
return firsts;
}
+/** How far back the lost-citation detector looks, in days. */
+export const LOST_CITATION_WINDOW_DAYS = 14;
+
/**
* High-volume prompts that stopped being cited: cited on >= 60% of the
* days with results over the last 14 days, but 0 citations on the most
@@ -333,7 +336,7 @@ async function lostCitationPrompts(brandId, promptById, now) {
const volumeIds = (volumes ?? []).map((v) => v.prompt_id);
if (!volumeIds.length) return [];
- const since = new Date(now.getTime() - 14 * DAY_MS).toISOString();
+ const since = new Date(now.getTime() - LOST_CITATION_WINDOW_DAYS * DAY_MS).toISOString();
const PAGE = 1000;
const rows = [];
// Paging runs inside each id chunk rather than across the whole list: the
diff --git a/server/src/lib/response-parser.js b/server/src/lib/response-parser.js
index 6680cef01..59ac6965a 100644
--- a/server/src/lib/response-parser.js
+++ b/server/src/lib/response-parser.js
@@ -77,13 +77,13 @@ export function extractHostname(rawUrl) {
}
/**
- * Count the citations that point at one of the brand's own domains: exact
- * host or subdomain match, same rule as the web classifier's 'you' category.
- * The old substring check (url.includes(domain)) also matched the brand's
- * domain inside another site's path or query string, and disagreed with the
+ * Whether a URL is on one of the brand's own domains: exact host or
+ * subdomain match, same rule as the web classifier's 'you' category. The old
+ * substring check (url.includes(domain)) also matched the brand's domain
+ * inside another site's path or query string, and disagreed with the
* Citations page over www/subdomain variants.
*/
-export function countOwnDomainCitations(citations, brandDomains) {
+export function ownDomainMatcher(brandDomains) {
const normalized = (brandDomains || [])
.map(
(d) =>
@@ -93,14 +93,18 @@ export function countOwnDomainCitations(citations, brandDomains) {
.toLowerCase(),
)
.filter(Boolean);
- if (normalized.length === 0) return 0;
+ return (url) => {
+ const host = extractHostname(url || '');
+ return Boolean(host) && normalized.some((d) => host === d || host.endsWith(`.${d}`));
+ };
+}
+/** Count the citations that point at one of the brand's own domains. */
+export function countOwnDomainCitations(citations, brandDomains) {
+ const isOwn = ownDomainMatcher(brandDomains);
let count = 0;
for (const cite of citations || []) {
- const host = extractHostname(cite?.url || '');
- if (host && normalized.some((d) => host === d || host.endsWith(`.${d}`))) {
- count++;
- }
+ if (isOwn(cite?.url)) count++;
}
return count;
}
diff --git a/server/src/lib/signals/lost-citation-evidence.js b/server/src/lib/signals/lost-citation-evidence.js
new file mode 100644
index 000000000..9b58ba8e4
--- /dev/null
+++ b/server/src/lib/signals/lost-citation-evidence.js
@@ -0,0 +1,216 @@
+/**
+ * What a lost citation rests on (AC-001): which of the brand's pages was
+ * cited, on which platforms, when it was last cited, and who is cited in its
+ * place now.
+ *
+ * The pulse's detector decides that a prompt lost its citations from day
+ * buckets alone (pulse/metrics.js lostCitationPrompts): cited on most result
+ * days of the last two weeks, and on none of the latest few. That is enough
+ * to raise the signal and not enough to act on it: a user needs the page to
+ * fix and the pages to beat. This reads those back for the lost prompts only,
+ * from the same answers, so it costs a few small reads per pass rather than
+ * a second scan of the brand.
+ */
+
+import supabaseAdmin from '../../config/supabase.js';
+import { chunkIds } from '../chunked-in.js';
+import { extractHostname, ownDomainMatcher } from '../response-parser.js';
+
+const DAY_MS = 86_400_000;
+
+/**
+ * One page however it is written: http or https, with or without www, a
+ * trailing slash or a query string. The first spelling seen is the one shown.
+ */
+function pageKey(url) {
+ const host = extractHostname(url) ?? '';
+ const path = String(url)
+ .replace(/^[a-z]+:\/\/[^/]+/i, '')
+ .replace(/[?#].*$/, '')
+ .replace(/\/+$/, '');
+ return `${host}${path}`.toLowerCase();
+}
+
+/** Pages listed per side: the panel names a few, not every citation. */
+const MAX_LISTED = 3;
+
+/** Answers per prompt read back for "cited now": the newest, per platform. */
+const TAIL_ANSWERS_PER_PLATFORM = 2;
+
+/**
+ * Summarises one lost prompt's answers.
+ *
+ * `rows` are the prompt's answers over the window, oldest first, each with
+ * `citations` when it was read back. Days are UTC result days, as the
+ * detector buckets them: the last `quietDays` are the quiet tail, the rest
+ * the head the brand was cited in.
+ */
+export function summarizeLostCitation(rows, isOwn, quietDays) {
+ const days = [...new Set(rows.map((r) => r.created_at.slice(0, 10)))].sort();
+ const tailDays = new Set(days.slice(-quietDays));
+ const head = rows.filter((r) => !tailDays.has(r.created_at.slice(0, 10)));
+ const tail = rows.filter((r) => tailDays.has(r.created_at.slice(0, 10)));
+
+ const citedDays = new Set(
+ head.filter((r) => (r.citation_count ?? 0) > 0).map((r) => r.created_at.slice(0, 10)),
+ );
+ const citedRows = head.filter((r) => (r.citation_count ?? 0) > 0);
+
+ // Lost on the platforms and locations that cited the brand before: none
+ // of the tail's answers cite it anywhere, or the signal would not exist.
+ const platforms = [...new Set(citedRows.map((r) => r.platform))].sort();
+ const regions = [...new Set(citedRows.map((r) => r.region).filter(Boolean))].sort();
+
+ // The brand's pages in the latest answers that cited them, newest first.
+ const lost = new Map();
+ for (const row of [...citedRows].reverse()) {
+ (row.citations ?? []).forEach((cite, i) => {
+ if (!cite?.url || !isOwn(cite.url)) return;
+ const key = pageKey(cite.url);
+ const seen = lost.get(key);
+ if (!seen) {
+ lost.set(key, {
+ url: cite.url,
+ position: i + 1,
+ lastCitedAt: row.created_at,
+ platforms: [row.platform],
+ });
+ } else if (!seen.platforms.includes(row.platform)) {
+ seen.platforms.push(row.platform);
+ }
+ });
+ }
+
+ // Who the quiet answers cite instead: by how many answers cite them, then
+ // how high they sit. Only the answers read back count, and the count says
+ // out of how many, so a sample never reads as every quiet answer.
+ const now = new Map();
+ const read = tail.filter((row) => row.citations !== null && row.citations !== undefined);
+ for (const row of read) {
+ const counted = new Set();
+ (row.citations ?? []).forEach((cite, i) => {
+ const key = cite?.url ? pageKey(cite.url) : '';
+ if (!key || isOwn(cite.url) || counted.has(key)) return;
+ counted.add(key);
+ const entry = now.get(key) ?? {
+ url: cite.url,
+ domain: extractHostname(cite.url),
+ answers: 0,
+ bestPosition: i + 1,
+ };
+ entry.answers += 1;
+ entry.bestPosition = Math.min(entry.bestPosition, i + 1);
+ now.set(key, entry);
+ });
+ }
+
+ return {
+ platforms,
+ regions,
+ citedDays: citedDays.size,
+ days: days.length - tailDays.size,
+ quietDays: tailDays.size,
+ lostUrls: [...lost.values()].slice(0, MAX_LISTED),
+ citedNow: [...now.values()]
+ .sort((a, b) => b.answers - a.answers || a.bestPosition - b.bestPosition)
+ .slice(0, MAX_LISTED)
+ .map(({ url, domain, answers, bestPosition }) => ({
+ url,
+ domain,
+ answers,
+ answersRead: read.length,
+ position: bestPosition,
+ })),
+ };
+}
+
+/**
+ * The evidence for each lost prompt, by prompt id. Three reads: the prompts'
+ * answers over the window (columns only), the brand's domains, and the
+ * citations of the answers that matter: the latest one citing the brand per
+ * platform, and the newest quiet ones per platform.
+ */
+export async function lostCitationEvidence(brandId, promptIds, { now, windowDays, quietDays }) {
+ const evidence = new Map();
+ if (promptIds.length === 0) return evidence;
+ const since = new Date(now.getTime() - windowDays * DAY_MS).toISOString();
+
+ const rows = [];
+ for (const chunk of chunkIds(promptIds)) {
+ for (let from = 0; ; from += 1000) {
+ const { data, error } = await supabaseAdmin
+ .from('prompt_results')
+ .select('id, prompt_id, platform, region, citation_count, created_at')
+ .eq('brand_id', brandId)
+ .neq('platform', 'chatgpt-shopping')
+ .in('prompt_id', chunk)
+ .gte('created_at', since)
+ .order('created_at', { ascending: true })
+ .range(from, from + 999);
+ if (error) throw new Error(`lost-citation evidence scan failed: ${error.message}`);
+ rows.push(...(data ?? []));
+ if ((data ?? []).length < 1000) break;
+ }
+ }
+
+ const byPrompt = groupBy(rows, (row) => row.prompt_id);
+
+ // Which answers' citations to read: per prompt and platform, the latest
+ // answer that cited the brand and the newest answers since it went quiet.
+ const wanted = new Set();
+ for (const promptRows of byPrompt.values()) {
+ const days = [...new Set(promptRows.map((r) => r.created_at.slice(0, 10)))].sort();
+ const tailDays = new Set(days.slice(-quietDays));
+ for (const platformRows of groupBy(promptRows, (row) => row.platform).values()) {
+ const cited = platformRows.filter(
+ (r) => (r.citation_count ?? 0) > 0 && !tailDays.has(r.created_at.slice(0, 10)),
+ );
+ if (cited.length) wanted.add(cited[cited.length - 1].id);
+ platformRows
+ .filter((r) => tailDays.has(r.created_at.slice(0, 10)))
+ .slice(-TAIL_ANSWERS_PER_PLATFORM)
+ .forEach((r) => wanted.add(r.id));
+ }
+ }
+
+ const [domainsRes, citations] = await Promise.all([
+ supabaseAdmin.from('brand_domains').select('domain').eq('brand_id', brandId),
+ readCitations([...wanted]),
+ ]);
+ if (domainsRes.error) throw new Error(domainsRes.error.message);
+ const isOwn = ownDomainMatcher((domainsRes.data ?? []).map((r) => r.domain));
+
+ for (const [promptId, promptRows] of byPrompt) {
+ const withCitations = promptRows.map((row) => ({
+ ...row,
+ citations: citations.get(row.id) ?? null,
+ }));
+ evidence.set(promptId, summarizeLostCitation(withCitations, isOwn, quietDays));
+ }
+ return evidence;
+}
+
+function groupBy(rows, keyOf) {
+ const groups = new Map();
+ for (const row of rows) {
+ const key = keyOf(row);
+ const list = groups.get(key);
+ if (list) list.push(row);
+ else groups.set(key, [row]);
+ }
+ return groups;
+}
+
+async function readCitations(ids) {
+ const byId = new Map();
+ for (const chunk of chunkIds(ids)) {
+ const { data, error } = await supabaseAdmin
+ .from('prompt_results')
+ .select('id, citations')
+ .in('id', chunk);
+ if (error) throw new Error(`lost-citation evidence read failed: ${error.message}`);
+ for (const row of data ?? [])
+ byId.set(row.id, Array.isArray(row.citations) ? row.citations : []);
+ }
+ return byId;
+}
diff --git a/server/src/lib/signals/lost-citation-evidence.test.js b/server/src/lib/signals/lost-citation-evidence.test.js
new file mode 100644
index 000000000..1d7e24d56
--- /dev/null
+++ b/server/src/lib/signals/lost-citation-evidence.test.js
@@ -0,0 +1,179 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+/**
+ * A lost citation's evidence (AC-001): the brand's page that was cited and
+ * when, the platforms it was lost on, who is cited now, and its cited days
+ * before and after. These pin the summary on the answers and that only the
+ * answers that matter have their citations read back.
+ */
+
+const reads = [];
+let tables = {};
+
+function builder(table) {
+ let columns = '';
+ const chain = {
+ select: (cols) => {
+ columns = cols;
+ return chain;
+ },
+ eq: () => chain,
+ neq: () => chain,
+ gte: () => chain,
+ order: () => chain,
+ range: () => chain,
+ in: (column, values) => {
+ if (column === 'id') reads.push(values);
+ chain.filter = { column, values };
+ return chain;
+ },
+ then: (resolve) => {
+ let data = tables[table] ?? [];
+ if (table === 'prompt_results' && columns.includes('citations') && chain.filter) {
+ data = data.filter((r) => chain.filter.values.includes(r.id));
+ }
+ resolve({ data, error: null });
+ },
+ };
+ return chain;
+}
+
+vi.mock('../../config/supabase.js', () => ({ default: { from: (t) => builder(t) } }));
+
+const { lostCitationEvidence, summarizeLostCitation } = await import('./lost-citation-evidence.js');
+const { ownDomainMatcher } = await import('../response-parser.js');
+
+const isOwn = ownDomainMatcher(['coffee.example']);
+const cite = (url) => ({ url });
+
+// Five result days: cited on chatgpt-web until Oct 10 and on gemini-web on
+// Oct 9, then three quiet days where others are cited.
+const answers = [
+ {
+ id: 'r1',
+ platform: 'chatgpt-web',
+ region: 'US',
+ created_at: '2026-10-09T05:00:00Z',
+ citation_count: 1,
+ citations: null,
+ },
+ {
+ id: 'r2',
+ platform: 'gemini-web',
+ region: 'US',
+ created_at: '2026-10-09T05:00:00Z',
+ citation_count: 1,
+ citations: [cite('https://other.example/a'), cite('https://www.coffee.example/guide')],
+ },
+ {
+ id: 'r3',
+ platform: 'chatgpt-web',
+ region: 'GB',
+ created_at: '2026-10-10T05:00:00Z',
+ citation_count: 1,
+ citations: [cite('https://coffee.example/guide')],
+ },
+ {
+ id: 'r4',
+ platform: 'chatgpt-web',
+ region: 'US',
+ created_at: '2026-10-11T05:00:00Z',
+ citation_count: 0,
+ citations: [cite('https://rival.example/best'), cite('https://g2.example/list')],
+ },
+ {
+ id: 'r5',
+ platform: 'gemini-web',
+ region: 'US',
+ created_at: '2026-10-12T05:00:00Z',
+ citation_count: 0,
+ citations: [cite('https://g2.example/list'), cite('https://rival.example/best')],
+ },
+ {
+ id: 'r6',
+ platform: 'chatgpt-web',
+ region: 'US',
+ created_at: '2026-10-13T05:00:00Z',
+ citation_count: 0,
+ citations: [cite('https://rival.example/best')],
+ },
+];
+
+describe('summarizeLostCitation', () => {
+ it('names the lost page, where it was lost, who is cited now and the cited days', () => {
+ expect(summarizeLostCitation(answers, isOwn, 3)).toEqual({
+ platforms: ['chatgpt-web', 'gemini-web'],
+ regions: ['GB', 'US'],
+ citedDays: 2,
+ days: 2,
+ quietDays: 3,
+ // The same page with and without www is one page, cited on both.
+ lostUrls: [
+ {
+ url: 'https://coffee.example/guide',
+ position: 1,
+ lastCitedAt: '2026-10-10T05:00:00Z',
+ platforms: ['chatgpt-web', 'gemini-web'],
+ },
+ ],
+ citedNow: [
+ {
+ url: 'https://rival.example/best',
+ domain: 'rival.example',
+ answers: 3,
+ answersRead: 3,
+ position: 1,
+ },
+ {
+ url: 'https://g2.example/list',
+ domain: 'g2.example',
+ answers: 2,
+ answersRead: 3,
+ position: 1,
+ },
+ ],
+ });
+ });
+
+ it('lists nothing it did not read back', () => {
+ const unread = answers.map((a) => ({ ...a, citations: null }));
+ const summary = summarizeLostCitation(unread, isOwn, 3);
+ expect(summary.lostUrls).toEqual([]);
+ expect(summary.citedNow).toEqual([]);
+ expect(summary.citedDays).toBe(2);
+ });
+});
+
+describe('lostCitationEvidence', () => {
+ beforeEach(() => {
+ reads.length = 0;
+ tables = {
+ prompt_results: answers.map((a) => ({ ...a, prompt_id: 'p1' })),
+ brand_domains: [{ domain: 'coffee.example' }],
+ };
+ });
+
+ it('reads back only the latest cited answer and the newest quiet ones per platform', async () => {
+ const evidence = await lostCitationEvidence('b1', ['p1'], {
+ now: new Date('2026-10-13T12:00:00Z'),
+ windowDays: 14,
+ quietDays: 3,
+ });
+ // r1 is an older cited answer on chatgpt-web, so its citations are not read.
+ expect(reads.flat().sort()).toEqual(['r2', 'r3', 'r4', 'r5', 'r6']);
+ expect(evidence.get('p1')).toMatchObject({
+ platforms: ['chatgpt-web', 'gemini-web'],
+ lostUrls: [{ url: 'https://coffee.example/guide' }],
+ });
+ });
+
+ it('reads nothing when no prompt lost its citations', async () => {
+ const evidence = await lostCitationEvidence('b1', [], {
+ now: new Date(),
+ windowDays: 14,
+ quietDays: 3,
+ });
+ expect(evidence.size).toBe(0);
+ expect(reads).toEqual([]);
+ });
+});
diff --git a/server/src/lib/signals/nightly-reads.test.js b/server/src/lib/signals/nightly-reads.test.js
index e6803021c..8f27ed967 100644
--- a/server/src/lib/signals/nightly-reads.test.js
+++ b/server/src/lib/signals/nightly-reads.test.js
@@ -19,6 +19,7 @@ import { describe, expect, it } from 'vitest';
*/
const NIGHTLY_MODULES = [
'src/lib/signals/record.js',
+ 'src/lib/signals/lost-citation-evidence.js',
'src/lib/pulse/metrics.js',
'src/lib/action-center/generate.js',
'src/lib/action-center/validate.js',
diff --git a/server/src/lib/signals/record-evidence.test.js b/server/src/lib/signals/record-evidence.test.js
new file mode 100644
index 000000000..7f3dedbcd
--- /dev/null
+++ b/server/src/lib/signals/record-evidence.test.js
@@ -0,0 +1,114 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+/**
+ * The recorder's lost-citation evidence step: what a lost citation is written
+ * with, and what it keeps when a night's evidence read fails.
+ */
+
+vi.mock('../../config/supabase.js', () => ({ default: { rpc: vi.fn(), from: vi.fn() } }));
+vi.mock('../logger.js', () => ({
+ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+vi.mock('../pulse/metrics.js', () => ({
+ computePulseMetrics: vi.fn(),
+ LOST_CITATION_WINDOW_DAYS: 14,
+}));
+
+// A plain stub rather than a spy: a spy keeps its own handle on a rejected
+// promise, which the runner then reports although the recorder handled it.
+let read = { calls: [], result: new Map(), fail: false };
+vi.mock('./lost-citation-evidence.js', () => ({
+ lostCitationEvidence: async (...args) => {
+ read.calls.push(args);
+ if (read.fail) throw new Error('timeout');
+ return read.result;
+ },
+}));
+
+const { attachLostCitationEvidence, keepRecordedEvidence } = await import('./record.js');
+
+const lost = (promptId) => ({
+ kind: 'lost_citations',
+ dedupKey: `lost_citations:${promptId}`,
+ payload: { promptText: 'Best coffee subscription?', promptId },
+});
+
+const evidence = {
+ platforms: ['chatgpt-web'],
+ regions: ['US'],
+ citedDays: 9,
+ days: 11,
+ quietDays: 3,
+ lostUrls: [{ url: 'https://coffee.example/guide', position: 2 }],
+ citedNow: [{ url: 'https://rival.example/best', answers: 2, answersRead: 3, position: 1 }],
+};
+
+beforeEach(() => {
+ read = { calls: [], result: new Map(), fail: false };
+});
+
+describe('attachLostCitationEvidence', () => {
+ it('writes each lost citation with its evidence, and leaves other kinds alone', async () => {
+ read.result = new Map([['p1', evidence]]);
+ const candidates = [
+ lost('p1'),
+ lost('p2'),
+ { kind: 'prompt_gain', payload: { promptId: 'p1' } },
+ ];
+ await attachLostCitationEvidence('b1', candidates, new Date('2026-10-13T00:00:00Z'));
+
+ expect(read.calls).toEqual([
+ ['b1', ['p1', 'p2'], { now: new Date('2026-10-13T00:00:00Z'), windowDays: 14, quietDays: 3 }],
+ ]);
+ expect(candidates[0].payload).toEqual({
+ promptText: 'Best coffee subscription?',
+ promptId: 'p1',
+ ...evidence,
+ });
+ expect(candidates[1].payload).toEqual({
+ promptText: 'Best coffee subscription?',
+ promptId: 'p2',
+ });
+ expect(candidates[2].payload).toEqual({ promptId: 'p1' });
+ });
+
+ it('records the signal without evidence when the read fails', async () => {
+ read.fail = true;
+ const candidates = [lost('p1')];
+ await expect(attachLostCitationEvidence('b1', candidates, new Date())).resolves.toBeUndefined();
+ expect(candidates[0].payload).toEqual({
+ promptText: 'Best coffee subscription?',
+ promptId: 'p1',
+ });
+ });
+});
+
+describe('keepRecordedEvidence', () => {
+ it("keeps an earlier night's evidence when tonight's read had none", () => {
+ const candidates = [lost('p1'), lost('p2')];
+ const existing = new Map([
+ ['lost_citations:p1', { payload: { promptText: 'old text', promptId: 'p1', ...evidence } }],
+ ['lost_citations:p2', { payload: { promptText: 'x', promptId: 'p2' } }],
+ ]);
+ keepRecordedEvidence(candidates, existing);
+ // Tonight's prompt text wins; the evidence is carried over.
+ expect(candidates[0].payload).toEqual({
+ promptText: 'Best coffee subscription?',
+ promptId: 'p1',
+ ...evidence,
+ });
+ expect(candidates[1].payload).toEqual({
+ promptText: 'Best coffee subscription?',
+ promptId: 'p2',
+ });
+ });
+
+ it("never overwrites tonight's own evidence", () => {
+ const fresh = { ...lost('p1'), payload: { ...lost('p1').payload, ...evidence, citedDays: 10 } };
+ keepRecordedEvidence(
+ [fresh],
+ new Map([['lost_citations:p1', { payload: { ...evidence, citedDays: 4 } }]]),
+ );
+ expect(fresh.payload.citedDays).toBe(10);
+ });
+});
diff --git a/server/src/lib/signals/record.js b/server/src/lib/signals/record.js
index 1604ba6af..b642cecfa 100644
--- a/server/src/lib/signals/record.js
+++ b/server/src/lib/signals/record.js
@@ -27,7 +27,8 @@
*/
import supabaseAdmin from '../../config/supabase.js';
-import { computePulseMetrics } from '../pulse/metrics.js';
+import { computePulseMetrics, LOST_CITATION_WINDOW_DAYS } from '../pulse/metrics.js';
+import { lostCitationEvidence } from './lost-citation-evidence.js';
import { logger } from '../logger.js';
import { readAllRpcRows } from '../rpc-pages.js';
import { resolve } from '../../config/action-engine.js';
@@ -543,6 +544,64 @@ const GROUP_OF = new Map(
EXCLUSIVE_KIND_GROUPS.flatMap((group, i) => group.map((kind) => [kind, i])),
);
+/**
+ * A lost citation arrives from the pulse naming only its prompt. Before it is
+ * written, it gets what the drawer shows (AC-001): the brand's page that was
+ * cited and when, the platforms it was lost on, who is cited now, and its
+ * cited days before and after. Best effort: without it the signal is still
+ * true and is recorded as before.
+ */
+export async function attachLostCitationEvidence(brandId, candidates, now) {
+ const lost = candidates.filter(
+ (c) => c.kind === 'lost_citations' && typeof c.payload?.promptId === 'string',
+ );
+ if (lost.length === 0) return;
+ try {
+ const evidence = await lostCitationEvidence(
+ brandId,
+ lost.map((c) => c.payload.promptId),
+ {
+ now,
+ windowDays: LOST_CITATION_WINDOW_DAYS,
+ quietDays: detection.lostCitationQuietDays,
+ },
+ );
+ for (const candidate of lost) {
+ const found = evidence.get(candidate.payload.promptId);
+ if (found) candidate.payload = { ...candidate.payload, ...found };
+ }
+ } catch (err) {
+ logger.warn({ brandId, err: err.message }, '[signals] lost-citation evidence unavailable');
+ }
+}
+
+const EVIDENCE_FIELDS = [
+ 'platforms',
+ 'regions',
+ 'citedDays',
+ 'days',
+ 'quietDays',
+ 'lostUrls',
+ 'citedNow',
+];
+
+/**
+ * A night whose evidence read failed refreshes a lost citation with the bare
+ * pulse payload. Keep what an earlier night recorded instead: it is older,
+ * and still truer than nothing.
+ */
+export function keepRecordedEvidence(candidates, existing) {
+ for (const candidate of candidates) {
+ if (candidate.kind !== 'lost_citations' || 'citedDays' in (candidate.payload ?? {})) continue;
+ const recorded = existing.get(candidate.dedupKey)?.payload ?? {};
+ if (!('citedDays' in recorded)) continue;
+ const kept = Object.fromEntries(
+ EVIDENCE_FIELDS.filter((key) => key in recorded).map((key) => [key, recorded[key]]),
+ );
+ candidate.payload = { ...candidate.payload, ...kept };
+ }
+}
+
/**
* Open, persistent signals nothing detected tonight, split by why.
*
@@ -607,6 +666,7 @@ export async function recordSignalsForBrand(brandId, { now = new Date() } = {})
const candidate = fromPulseEntry(entry);
if (candidate) candidates.push(candidate);
}
+ await attachLostCitationEvidence(brandId, candidates, now);
candidates.push(...(await pageOpportunityCandidates(brandId)));
candidates.push(...(await uncitedMentionCandidates(brandId, now)));
candidates.push(...(await auditCandidates(brandId, now)));
@@ -640,6 +700,7 @@ export async function recordSignalsForBrand(brandId, { now = new Date() } = {})
.limit(1000);
if (readErr) throw new Error(readErr.message);
const existing = new Map((existingRows ?? []).map((row) => [row.dedup_key, row]));
+ keepRecordedEvidence(candidates, existing);
const nowIso = now.toISOString();
let inserted = 0;
diff --git a/web/messages/en.json b/web/messages/en.json
index 9139ff024..887ae938d 100644
--- a/web/messages/en.json
+++ b/web/messages/en.json
@@ -350,6 +350,12 @@
"viewPrompt": "View prompt",
"notAvailable": "Not available",
"allPlatforms": "All tracked platforms",
+ "cited": {
+ "position": "#{position}",
+ "lastCited": "last cited {date}",
+ "answers": "{count, plural, one {in # answer} other {in # answers}}",
+ "answersOf": "in {count} of {of, plural, one {# latest answer} other {# latest answers}}"
+ },
"loading": "Loading…",
"more": "+{count} more",
"usedBy": "Used by actions",
@@ -400,6 +406,7 @@
"periods": {
"week_over_week": "Last 7 days against the 7 days before",
"last_7_days": "Last 7 days",
+ "last_14_days": "Days with answers in the last 14 days",
"latest": "Latest data"
},
"metrics": {
@@ -416,11 +423,14 @@
"engagement_rank": "Engagement rank",
"prompts": "Prompts",
"pages": "Pages",
- "queries": "Queries"
+ "queries": "Queries",
+ "cited_days": "Cited days"
},
"roles": {
"before": "previous 7 days",
"after": "last 7 days",
+ "earlier": "earlier days",
+ "latest": "latest days",
"change": "change",
"you": "you",
"competitor": "{name}",
@@ -460,7 +470,9 @@
},
"lost_citations": {
"title": "Citations lost for “{prompt}”",
- "description": "Your pages are no longer cited in answers to this prompt."
+ "titleOn": "Citations lost on {platform} for “{prompt}”",
+ "description": "Your pages are no longer cited in answers to this prompt.",
+ "descriptionPage": "{page} is no longer cited on {platforms}."
},
"first_citation": {
"title": "First citation for {url}",
diff --git a/web/src/components/action-center/signal-detail-blocks.test.tsx b/web/src/components/action-center/signal-detail-blocks.test.tsx
index 45354ea84..8b979fdad 100644
--- a/web/src/components/action-center/signal-detail-blocks.test.tsx
+++ b/web/src/components/action-center/signal-detail-blocks.test.tsx
@@ -170,6 +170,45 @@ describe('SignalWhereBlock', () => {
});
});
+describe('a lost citation with its evidence', () => {
+ const recorded = signal({
+ category: 'citation',
+ kind: 'lost_citations',
+ previousValue: null,
+ currentValue: null,
+ changeValue: null,
+ payload: {
+ promptId: 'p1',
+ promptText: 'Best coffee subscription?',
+ platforms: ['chatgpt-web'],
+ citedDays: 9,
+ days: 11,
+ quietDays: 3,
+ lostUrls: [
+ { url: 'https://coffee.example/guide', position: 2, lastCitedAt: '2026-10-08T05:00:00Z' },
+ ],
+ citedNow: [{ url: 'https://rival.example/best', answers: 3, answersRead: 4, position: 1 }],
+ },
+ where: { platforms: ['chatgpt-web'], regions: [], topics: [] },
+ });
+
+ it('shows the page lost, the pages cited now, and the cited days', () => {
+ render(<SignalWhereBlock signal={recorded} />);
+ const rows = [...container.querySelectorAll('dt')].map(
+ (dt) => `${dt.textContent}: ${dt.nextElementSibling?.textContent}`,
+ );
+ expect(rows).toContain('Your page cited before: coffee.example/guide#2 · last cited Oct 8');
+ expect(rows).toContain('Cited now: rival.example/best#1 · in 3 of 4 latest answers');
+ expect(rows).toContain('Platforms: ChatGPT');
+
+ render(<SignalChangeBlock signal={recorded} />);
+ const text = container.textContent ?? '';
+ expect(text).toContain('Days with answers in the last 14 days');
+ expect(text).toContain('Cited days · earlier days9 / 11');
+ expect(text).toContain('Cited days · latest days0 / 3');
+ });
+});
+
describe('SignalEvidenceBlock', () => {
it('links the answers and the action the signal is used by', async () => {
getSignalActions.mockResolvedValue([
diff --git a/web/src/components/action-center/signal-detail-blocks.tsx b/web/src/components/action-center/signal-detail-blocks.tsx
index a8a85f4c8..817f9abcb 100644
--- a/web/src/components/action-center/signal-detail-blocks.tsx
+++ b/web/src/components/action-center/signal-detail-blocks.tsx
@@ -127,6 +127,34 @@ function WhereValueView({ value }: { value: WhereValue }) {
);
case 'all_platforms':
return <span>{t('drawer.allPlatforms')}</span>;
+ case 'citations':
+ return (
+ <ul className="space-y-1">
+ {value.items.map((page, i) => (
+ <li key={i}>
+ <span className="break-all">{page.url.replace(/^https?:\/\//, '')}</span>
+ <span className="block text-xs text-muted-foreground">
+ {[
+ page.position !== null && t('drawer.cited.position', { position: page.position }),
+ page.lastCitedAt &&
+ t('drawer.cited.lastCited', {
+ date: format.dateTime(new Date(page.lastCitedAt), {
+ month: 'short',
+ day: 'numeric',
+ }),
+ }),
+ page.answers !== undefined &&
+ (page.answersRead !== undefined
+ ? t('drawer.cited.answersOf', { count: page.answers, of: page.answersRead })
+ : t('drawer.cited.answers', { count: page.answers })),
+ ]
+ .filter(Boolean)
+ .join(' · ')}
+ </span>
+ </li>
+ ))}
+ </ul>
+ );
case 'locations':
return <span>{value.codes.map(locationName).join(', ')}</span>;
}
@@ -157,9 +185,10 @@ function useFigureText() {
const t = useTranslations('actionCenter.signalsPage.drawer.change');
const format = useFormatter();
- const value = (figure: Pick<SignalFigure, 'metric' | 'value'>, signed = false) => {
+ const value = (figure: Pick<SignalFigure, 'metric' | 'value' | 'of'>, signed = false) => {
const unit = METRIC_UNITS[figure.metric];
const n = format.number(Math.abs(figure.value), { maximumFractionDigits: 1 });
+ if (figure.of !== undefined) return `${n} / ${format.number(figure.of)}`;
const sign = signed ? (figure.value > 0 ? '+' : figure.value < 0 ? '−' : '') : '';
if (unit === 'percent') return signed ? t('points', { value: `${sign}${n}` }) : `${n}%`;
if (unit === 'points') return t('points', { value: `${sign}${n}` });
@@ -180,7 +209,7 @@ function useFigureText() {
// "Mention rate · United States (best)": the metric, whose, and when.
const label = (figure: SignalFigure) => {
const name = subject(figure);
- const overTime = ['before', 'after', 'change'].includes(figure.role);
+ const overTime = ['before', 'after', 'earlier', 'latest', 'change'].includes(figure.role);
return [
t(`metrics.${figure.metric}`),
overTime && name ? name : null,
@@ -212,10 +241,14 @@ export function SignalChangeBlock({ signal }: { signal: Signal }) {
</p>
<div className="mt-2 space-y-2">
{groupByMetric(change.figures).map((figures) => {
- const before = figures.find((f) => f.role === 'before');
- const after = figures.find((f) => f.role === 'after');
+ const before = figures.find((f) => f.role === 'before' || f.role === 'earlier');
+ const after = figures.find((f) => f.role === 'after' || f.role === 'latest');
if (before && after) {
- const delta = { metric: after.metric, value: after.value - before.value };
+ // Days out of different totals have no meaningful difference.
+ const delta =
+ after.of === undefined
+ ? { metric: after.metric, value: after.value - before.value }
+ : { metric: after.metric, value: 0 };
// A rise is good news for the brand's own numbers and bad news
// for a competitor's.
const good = delta.value >= 0 !== (after.subjectType === 'competitor');
diff --git a/web/src/components/action-center/signal-table.tsx b/web/src/components/action-center/signal-table.tsx
index c4ff3d822..0054c04f1 100644
--- a/web/src/components/action-center/signal-table.tsx
+++ b/web/src/components/action-center/signal-table.tsx
@@ -53,7 +53,7 @@ import {
import { signalAffected, signalTexts } from '@/lib/signals/display';
import { locationName, platformFamily, platformName } from '@/lib/signals/names';
import type { SignalWhere } from '@/lib/signals/where';
-import { groupStatus, groupWhere, type SignalGroup } from '@/lib/signals/group';
+import { groupLead, groupStatus, groupWhere, type SignalGroup } from '@/lib/signals/group';
import { formatRelative } from '@/lib/format-relative';
import { cn } from '@/lib/utils';
@@ -415,7 +415,7 @@ export function SignalTable({
const lead = signals[0];
const isGroup = signals.length > 1;
const isOpen = isGroup && expanded.has(key);
- const texts = signalTexts(lead, tTexts);
+ const texts = signalTexts(isGroup ? groupLead(signals) : lead, tTexts);
const affected = signalAffected(lead, t);
const stateKey = SIGNAL_KINDS[lead.kind].stateKey;
const status = isGroup ? groupStatus(signals) : lead.status;
diff --git a/web/src/lib/signals/detail.test.ts b/web/src/lib/signals/detail.test.ts
index 1426d0d97..e33543e6f 100644
--- a/web/src/lib/signals/detail.test.ts
+++ b/web/src/lib/signals/detail.test.ts
@@ -272,6 +272,62 @@ describe('signalDetailForApi', () => {
unit: 'percent',
subject: null,
subject_type: null,
+ of: null,
+ });
+ });
+});
+
+describe('a lost citation with its evidence recorded', () => {
+ const recorded = signal({
+ category: 'citation',
+ kind: 'lost_citations',
+ payload: {
+ promptId: 'p1',
+ promptText: 'Best coffee subscription?',
+ platforms: ['chatgpt-web'],
+ regions: ['US'],
+ citedDays: 9,
+ days: 11,
+ quietDays: 3,
+ lostUrls: [
+ { url: 'https://coffee.example/guide', position: 2, lastCitedAt: '2026-10-08T05:00:00Z' },
+ ],
+ citedNow: [
+ { url: 'https://rival.example/best', domain: 'rival.example', answers: 3, position: 1 },
+ ],
+ },
+ where: { platforms: ['chatgpt-web'], regions: ['US'], topics: ['Coffee'] },
+ });
+
+ it('names the page lost and the pages cited now, on the platforms it was lost on', () => {
+ expect(signalWhereFields(recorded).map((f) => f.key)).toEqual([
+ 'prompt',
+ 'topic',
+ 'platforms',
+ 'locations',
+ 'lostUrl',
+ 'citedNow',
+ ]);
+ const byKey = Object.fromEntries(signalWhereFields(recorded).map((f) => [f.key, f.value]));
+ expect(byKey.lostUrl).toEqual({
+ type: 'citations',
+ items: [
+ { url: 'https://coffee.example/guide', position: 2, lastCitedAt: '2026-10-08T05:00:00Z' },
+ ],
+ });
+ expect(byKey.citedNow).toEqual({
+ type: 'citations',
+ items: [{ url: 'https://rival.example/best', position: 1, answers: 3 }],
+ });
+ });
+
+ it('counts its cited days before and since', () => {
+ expect(signalChange(recorded)).toEqual({
+ period: 'last_14_days',
+ figures: [
+ { metric: 'cited_days', role: 'earlier', value: 9, of: 11 },
+ { metric: 'cited_days', role: 'latest', value: 0, of: 3 },
+ ],
});
});
});
diff --git a/web/src/lib/signals/detail.ts b/web/src/lib/signals/detail.ts
index 652cb8d0b..2991046b7 100644
--- a/web/src/lib/signals/detail.ts
+++ b/web/src/lib/signals/detail.ts
@@ -38,7 +38,9 @@ export type SignalMetric =
/** How many things a grouped finding covers. */
| 'prompts'
| 'pages'
- | 'queries';
+ | 'queries'
+ /** Result days on which an answer cited the brand. */
+ | 'cited_days';
export type SignalUnit = 'percent' | 'points' | 'count' | 'rank';
@@ -57,6 +59,7 @@ export const METRIC_UNITS: Record<SignalMetric, SignalUnit> = {
prompts: 'count',
pages: 'count',
queries: 'count',
+ cited_days: 'count',
};
/**
@@ -67,6 +70,9 @@ export const METRIC_UNITS: Record<SignalMetric, SignalUnit> = {
export type FigureRole =
| 'before'
| 'after'
+ /** The earlier result days of a window, and its latest few. */
+ | 'earlier'
+ | 'latest'
| 'change'
| 'you'
| 'competitor'
@@ -84,10 +90,12 @@ export interface SignalFigure {
/** The competitor's name, or the platform slug or location code compared. */
subject?: string;
subjectType?: 'competitor' | 'platform' | 'location';
+ /** Out of how many, for a count of days: 9 of 11. */
+ of?: number;
}
/** The window the figures cover. The detectors all read 7-day windows. */
-export type ChangePeriod = 'week_over_week' | 'last_7_days' | 'latest';
+export type ChangePeriod = 'week_over_week' | 'last_7_days' | 'last_14_days' | 'latest';
export interface SignalChange {
period: ChangePeriod;
@@ -159,6 +167,25 @@ export function signalChange(signal: Signal): SignalChange | null {
}
switch (signal.kind) {
+ case 'lost_citations': {
+ // Recorded with the evidence (server signals/lost-citation-evidence.js):
+ // cited on `citedDays` of the `days` earlier result days, on none of
+ // the latest `quietDays`.
+ const { citedDays, days, quietDays } = p;
+ if (typeof citedDays !== 'number' || typeof days !== 'number') return null;
+ return {
+ period: 'last_14_days',
+ figures: [
+ { metric: 'cited_days', role: 'earlier', value: citedDays, of: days },
+ {
+ metric: 'cited_days',
+ role: 'latest',
+ value: 0,
+ of: typeof quietDays === 'number' ? quietDays : 0,
+ },
+ ],
+ };
+ }
case 'platform_gap':
if (prev === null || cur === null) return null;
return {
@@ -338,9 +365,34 @@ export type WhereValue =
| { type: 'platforms'; slugs: readonly string[] }
/** Every tracked platform: a finding about the whole brand or a location. */
| { type: 'all_platforms' }
+ /** Cited pages: the brand's lost ones, or those cited in their place. */
+ | { type: 'citations'; items: CitedPage[] }
| { type: 'locations'; codes: readonly string[] }
| { type: 'number'; value: number };
+export interface CitedPage {
+ url: string;
+ /** Its position among the answer's citations, 1 first. */
+ position: number | null;
+ lastCitedAt?: string;
+ answers?: number;
+ /** Of how many answers read back: a sample of the quiet days' answers. */
+ answersRead?: number;
+}
+
+function citedPages(value: unknown): CitedPage[] {
+ if (!Array.isArray(value)) return [];
+ return value
+ .filter((v): v is Record<string, unknown> => typeof v?.url === 'string')
+ .map((v) => ({
+ url: v.url as string,
+ position: typeof v.position === 'number' ? v.position : null,
+ ...(typeof v.lastCitedAt === 'string' ? { lastCitedAt: v.lastCitedAt } : {}),
+ ...(typeof v.answers === 'number' ? { answers: v.answers } : {}),
+ ...(typeof v.answersRead === 'number' ? { answersRead: v.answersRead } : {}),
+ }));
+}
+
export interface WhereField {
key: WhereFieldKey;
/** Null when no detector records it yet: the panel says "Not available". */
@@ -541,11 +593,18 @@ function fieldValue(signal: Signal, key: WhereFieldKey): WhereValue | null {
: null;
case 'engagementRank':
return typeof p.valueRank === 'number' ? { type: 'number', value: p.valueRank } : null;
- case 'lostUrl':
+ case 'lostUrl': {
+ const lost = citedPages(p.lostUrls);
+ if (lost.length) return { type: 'citations', items: lost };
// An owned page that stopped being cited is the lost URL itself.
return signal.kind === 'owned_page_citation_lost' && targets.length
? { type: 'list', items: targets.map(label), total }
: null;
+ }
+ case 'citedNow': {
+ const now = citedPages(p.citedNow);
+ return now.length ? { type: 'citations', items: now } : null;
+ }
case 'evidence': {
const checks = targets.flatMap((t) =>
Array.isArray(t.checks) ? t.checks.filter((c): c is string => typeof c === 'string') : [],
@@ -567,7 +626,11 @@ const TRACKED: Partial<Record<WhereFieldKey, WhereFieldKey>> = {
function placeIsNamed(signal: Signal): boolean {
const p = signal.payload ?? {};
- return typeof p.platform === 'string' || typeof p.region === 'string';
+ return (
+ typeof p.platform === 'string' ||
+ typeof p.region === 'string' ||
+ (Array.isArray(p.platforms) && p.platforms.length > 0)
+ );
}
/** The Where block: the spec's fields for this signal, each with its value or none. */
@@ -667,6 +730,14 @@ function apiValue(value: WhereValue): unknown {
return value.slugs.map((slug) => ({ slug, name: platformName(slug) }));
case 'all_platforms':
return 'all';
+ case 'citations':
+ return value.items.map((page) => ({
+ url: page.url,
+ position: page.position,
+ ...(page.lastCitedAt ? { last_cited_at: page.lastCitedAt } : {}),
+ ...(page.answers !== undefined ? { answers: page.answers } : {}),
+ ...(page.answersRead !== undefined ? { answers_read: page.answersRead } : {}),
+ }));
case 'locations':
return value.codes.map((code) => ({ code, name: locationName(code) }));
}
@@ -702,6 +773,7 @@ export function signalDetailForApi(signal: Signal, actions: SignalActionRef[]) {
unit: METRIC_UNITS[f.metric],
subject: f.subject ?? null,
subject_type: f.subjectType ?? null,
+ of: f.of ?? null,
})),
},
evidence: {
diff --git a/web/src/lib/signals/display.test.ts b/web/src/lib/signals/display.test.ts
index c8faf1eda..bdb465d22 100644
--- a/web/src/lib/signals/display.test.ts
+++ b/web/src/lib/signals/display.test.ts
@@ -110,6 +110,32 @@ describe('signalTexts', () => {
});
});
+ it('names the lost page, and the platform when it was lost on one', () => {
+ const lost = (platforms: string[]) =>
+ signal({
+ category: 'citation',
+ kind: 'lost_citations',
+ payload: {
+ promptId: 'p1',
+ promptText: 'Best coffee subscription?',
+ platforms,
+ lostUrls: [{ url: 'https://coffee.example/guide/' }],
+ },
+ });
+ expect(signalTexts(lost(['chatgpt-web']), tTexts)).toEqual({
+ title: 'Citations lost on ChatGPT for “Best coffee subscription?”',
+ description: 'coffee.example/guide is no longer cited on ChatGPT.',
+ });
+ expect(signalTexts(lost(['chatgpt-web', 'gemini-web']), tTexts).title).toBe(
+ 'Citations lost for “Best coffee subscription?”',
+ );
+ // A row recorded before the evidence keeps the generic copy.
+ expect(
+ signalTexts(signal({ kind: 'lost_citations', payload: { promptText: 'x' } }), tTexts)
+ .description,
+ ).toBe('Your pages are no longer cited in answers to this prompt.');
+ });
+
it('names both models a platform gap compares', () => {
const gap = signal({
kind: 'platform_gap',
diff --git a/web/src/lib/signals/display.ts b/web/src/lib/signals/display.ts
index 22e09332e..a03071ee0 100644
--- a/web/src/lib/signals/display.ts
+++ b/web/src/lib/signals/display.ts
@@ -54,8 +54,42 @@ function librarySignalTexts(signal: Signal, t: Translator): { title: string; des
};
}
+/** A URL as a row names it: without its protocol or trailing slash. */
+function shortUrl(url: string): string {
+ return url.replace(/^https?:\/\//, '').replace(/\/$/, '');
+}
+
+/**
+ * A lost citation, once its evidence is recorded (server
+ * signals/lost-citation-evidence.js), names the page that stopped being cited
+ * and the platforms it was lost on, and a loss on one platform says which in
+ * its title (AC-001/AC-002). Older rows keep the generic copy.
+ */
+function lostCitationTexts(signal: Signal, t: Translator): { title: string; description: string } {
+ const p = signal.payload;
+ const platforms = Array.isArray(p.platforms)
+ ? p.platforms.filter((x): x is string => typeof x === 'string').map(platformName)
+ : [];
+ const lost = Array.isArray(p.lostUrls) ? (p.lostUrls as { url?: unknown }[]) : [];
+ const page = typeof lost[0]?.url === 'string' ? shortUrl(lost[0].url) : '';
+ const values = {
+ prompt: str(p, 'promptText'),
+ platform: platforms[0] ?? '',
+ platforms: platforms.join(', '),
+ page,
+ };
+ return {
+ title: t(platforms.length === 1 ? 'lost_citations.titleOn' : 'lost_citations.title', values),
+ description:
+ page && platforms.length
+ ? t('lost_citations.descriptionPage', values)
+ : t('lost_citations.description', values),
+ };
+}
+
export function signalTexts(signal: Signal, t: Translator): { title: string; description: string } {
if (isLibrarySignalKind(signal.kind)) return librarySignalTexts(signal, t);
+ if (signal.kind === 'lost_citations') return lostCitationTexts(signal, t);
const p = signal.payload;
const values = ((): Record<string, string | number> => {
switch (signal.kind) {
@@ -79,8 +113,6 @@ export function signalTexts(signal: Signal, t: Translator): { title: string; des
return { prompt: str(p, 'promptText'), gain: signal.changeValue ?? 0 };
case 'new_engine':
return { platform: platformName(str(p, 'platform')) };
- case 'lost_citations':
- return { prompt: str(p, 'promptText') };
case 'first_citation':
return { url: str(p, 'label') || str(p, 'url'), prompt: str(p, 'promptText') };
case 'competitor_surge':
diff --git a/web/src/lib/signals/group.test.ts b/web/src/lib/signals/group.test.ts
index 70ff20805..3710e849b 100644
--- a/web/src/lib/signals/group.test.ts
+++ b/web/src/lib/signals/group.test.ts
@@ -1,7 +1,14 @@
import { describe, expect, it } from 'vitest';
import type { Signal } from './map';
import { NO_WHERE } from './where';
-import { groupSignals, groupStatus, groupWhere, promptTextKey, signalGroupKey } from './group';
+import {
+ groupLead,
+ groupSignals,
+ groupStatus,
+ groupWhere,
+ promptTextKey,
+ signalGroupKey,
+} from './group';
const signal = (over: Partial<Signal>): Signal => ({
id: 's1',
@@ -87,3 +94,18 @@ describe('groupStatus and groupWhere', () => {
});
});
});
+
+describe('groupLead', () => {
+ it("titles a group from every copy's lost-on platforms, not the first copy's", () => {
+ const copies = [
+ lost('a', { payload: { promptId: 'p-a', promptText: TEXT, platforms: ['chatgpt-web'] } }),
+ lost('b', { payload: { promptId: 'p-b', promptText: TEXT, platforms: ['gemini-web'] } }),
+ ];
+ expect(groupLead(copies).payload.platforms).toEqual(['chatgpt-web', 'gemini-web']);
+ expect(groupLead(copies).id).toBe('a');
+ // Copies recorded before the evidence are left as they are.
+ expect(groupLead([lost('c')])).toEqual(lost('c'));
+ // One copy without recorded platforms: the group names none.
+ expect(groupLead([copies[0], lost('d')]).payload).not.toHaveProperty('platforms');
+ });
+});
diff --git a/web/src/lib/signals/group.ts b/web/src/lib/signals/group.ts
index af97c1d6f..d662f0ab3 100644
--- a/web/src/lib/signals/group.ts
+++ b/web/src/lib/signals/group.ts
@@ -64,3 +64,28 @@ export function groupStatus(signals: Signal[]): SignalStatus {
export function groupWhere(signals: Signal[]): SignalWhere {
return mergeWhere(signals.map((signal) => signal.where));
}
+
+/**
+ * The signal a group's row is titled from: its newest copy, with the
+ * platforms every copy was lost on. A lost citation lost on one platform
+ * names it in its title; a group must not name only its first copy's, nor
+ * name any while a copy's platforms were never recorded.
+ */
+export function groupLead(signals: Signal[]): Signal {
+ const lead = signals[0];
+ const recorded = signals.map((s) =>
+ Array.isArray(s.payload?.platforms)
+ ? s.payload.platforms.filter((p): p is string => typeof p === 'string')
+ : null,
+ );
+ if (recorded.every((platforms) => platforms === null)) return lead;
+ if (recorded.some((platforms) => platforms === null)) {
+ const payload = { ...lead.payload };
+ delete payload.platforms;
+ return { ...lead, payload };
+ }
+ return {
+ ...lead,
+ payload: { ...lead.payload, platforms: [...new Set(recorded.flat() as string[])] },
+ };
+}
diff --git a/web/src/lib/signals/where.test.ts b/web/src/lib/signals/where.test.ts
index 3f3bc6fc0..7ff86f48f 100644
--- a/web/src/lib/signals/where.test.ts
+++ b/web/src/lib/signals/where.test.ts
@@ -100,6 +100,14 @@ describe('signalWhere', () => {
});
});
+describe('a lost citation with its evidence', () => {
+ it('is where it was lost, not everywhere its prompt is tracked', () => {
+ expect(
+ signalWhere({ promptId: 'p2', platforms: ['chatgpt-web'], regions: ['GB'] }, prompts),
+ ).toEqual({ platforms: ['chatgpt-web'], regions: ['GB'], topics: ['AEO'] });
+ });
+});
+
describe('mergeWhere', () => {
it('joins places, counting each once, the most shared first', () => {
expect(
diff --git a/web/src/lib/signals/where.ts b/web/src/lib/signals/where.ts
index 65b1cbaae..065476006 100644
--- a/web/src/lib/signals/where.ts
+++ b/web/src/lib/signals/where.ts
@@ -87,15 +87,29 @@ export function signalWhere(
.map((id) => prompts.get(id))
.filter((p): p is PromptPlace => p !== undefined);
}
- if (places.length === 0) return NO_WHERE;
+ const tracked =
+ places.length === 0
+ ? NO_WHERE
+ : mergeWhere(
+ places.map((p) => ({
+ platforms: p.platforms.filter((x) => !IGNORED_PLATFORMS.has(x)),
+ regions: p.regions,
+ topics: p.topic ? [p.topic] : [],
+ })),
+ );
- return mergeWhere(
- places.map((p) => ({
- platforms: p.platforms.filter((x) => !IGNORED_PLATFORMS.has(x)),
- regions: p.regions,
- topics: p.topic ? [p.topic] : [],
- })),
- );
+ // A lost citation records the platforms and locations it was lost on
+ // (server signals/lost-citation-evidence.js): where it happened, which
+ // beats where its prompt is tracked.
+ const lostOn = strings(payload.platforms);
+ if (lostOn.length === 0) return tracked;
+ return { platforms: lostOn, regions: strings(payload.regions), topics: tracked.topics };
+}
+
+function strings(value: unknown): string[] {
+ return Array.isArray(value)
+ ? value.filter((v): v is string => typeof v === 'string' && v !== '')
+ : [];
}
/**