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.

fix(action-center): keep one stray 404 visit from raising a broken-link signal, and read only the candidates for a new AI platform (#1228)

Cihanfce0bd2c43fe
diff --git a/server/src/config/action-engine.js b/server/src/config/action-engine.js
index f69df0662..14757e9e9 100644
--- a/server/src/config/action-engine.js
+++ b/server/src/config/action-engine.js
@@ -243,6 +243,10 @@ export const ENGINE_THRESHOLDS = Object.freeze({
* week before (AT-013, spec §3.8; 30 is the page's Low sample floor). */
aiVisitsWeeklyDropRatio: 0.4,
aiVisitsWeeklyMinVisits: 30,
+ /** A missing page AI answers cite raises its signal from the first visit
+ * (the citations come from tracking); any other needs this many, since
+ * the beacon is public and one stray or made-up 404 visit would do. */
+ brokenLinkMinVisits: 3,
/** Key events per session above this multiple of the site's rate is a
* winning page; engagement below `underperform` of it is a weak one. */
landingWinnerMultiple: 1.5,
diff --git a/server/src/lib/signals/library/ai-traffic-alerts-family.test.js b/server/src/lib/signals/library/ai-traffic-alerts-family.test.js
index 2e63a626a..3b9540828 100644
--- a/server/src/lib/signals/library/ai-traffic-alerts-family.test.js
+++ b/server/src/lib/signals/library/ai-traffic-alerts-family.test.js
@@ -102,7 +102,7 @@ describe('the AI Traffic alerts family', () => {
},
{
page: '/',
- visits: '1',
+ visits: '3',
platforms: [],
citations: null,
status: 'title',
@@ -132,7 +132,7 @@ describe('the AI Traffic alerts family', () => {
{
id: '/',
label: '/',
- visits: 1,
+ visits: 3,
status: 'title',
citations: 0,
redirectTo: null,
@@ -147,6 +147,38 @@ describe('the AI Traffic alerts family', () => {
]);
});
+ it('needs a citation, or a few visits, before a missing page raises it', async () => {
+ const row = (page, visits, citations) => ({
+ page,
+ visits,
+ platforms: [],
+ citations,
+ status: '404',
+ target: null,
+ target_reason: null,
+ });
+ const [found] = await alerts({
+ prev: week(0),
+ cur: week(0),
+ broken: {
+ count: 3,
+ rows: [
+ // Cited by AI answers: tracking says so, not the public beacon.
+ row('/cited', 1, 4),
+ // One visit to a page no answer cites: stray, or made up.
+ row('/one-visit', 1, 0),
+ row('/three-visits', 3, 0),
+ ],
+ },
+ });
+ expect(found.payload.targets.map((p) => p.id)).toEqual(['/cited', '/three-visits']);
+ expect(found.currentValue).toBe(2);
+
+ expect(
+ await alerts({ prev: week(0), cur: week(0), broken: { count: 1, rows: [row('/x', 2, 0)] } }),
+ ).toEqual([]);
+ });
+
it('raises nothing when no AI visitor landed on a missing page, or the read answers nothing', async () => {
expect(await alerts({ prev: week(0), cur: week(0) })).toEqual([]);
expect(await alerts({ prev: week(0), cur: week(0), broken: null })).toEqual([]);
diff --git a/server/src/lib/signals/library/detect.js b/server/src/lib/signals/library/detect.js
index 9b005599d..175c4f18b 100644
--- a/server/src/lib/signals/library/detect.js
+++ b/server/src/lib/signals/library/detect.js
@@ -736,9 +736,15 @@ const FAMILIES = [
}
// Each missing page with what AI visitors got and the working page to
- // redirect it to; the snippet is the only source (§3.8b).
+ // redirect it to; the snippet is the only source (§3.8b). A page AI
+ // answers cite counts from its first visit; any other needs
+ // brokenLinkMinVisits, so a single 404 visit from the public beacon,
+ // stray or made up, raises no high-impact signal.
const broken = await ctx.brokenLinks();
- const rows = Array.isArray(broken?.rows) ? broken.rows : [];
+ const listed = Array.isArray(broken?.rows) ? broken.rows : [];
+ const rows = listed.filter(
+ (r) => (Number(r.citations) || 0) > 0 || (Number(r.visits) || 0) >= t.brokenLinkMinVisits,
+ );
if (rows.length > 0) {
found.push({
...group(
@@ -755,7 +761,10 @@ const FAMILIES = [
}),
AI,
),
- currentValue: Number(broken.count) || rows.length,
+ // The function's count covers every page past its row limit; once
+ // the filter drops some, the pages kept are the count.
+ currentValue:
+ rows.length === listed.length ? Number(broken.count) || rows.length : rows.length,
});
}
return found;
diff --git a/server/src/lib/signals/traffic-platforms.js b/server/src/lib/signals/traffic-platforms.js
index 53da443cb..8db5cf23e 100644
--- a/server/src/lib/signals/traffic-platforms.js
+++ b/server/src/lib/signals/traffic-platforms.js
@@ -1,11 +1,13 @@
/**
* "A new AI platform starts sending visits" (AT-013, spec §3.8).
*
- * A platform with AI visits in the last seven whole days and none before
- * them, counted as the AI Traffic page counts them (ai_traffic_merged, 00176:
- * the snippet on the days it ran, Analytics on the rest). A brand with no AI
- * visits before the week has nothing to compare with — every platform would
- * be new — so it gets none.
+ * A platform with AI visits in the last seven whole days, counted as the AI
+ * Traffic page counts them (ai_traffic_merged, 00176: the snippet on the days
+ * it ran, Analytics on the rest), and none before them. "None before" is
+ * asked only for the week's candidates (ai_traffic_platforms_seen, 00193), so
+ * a quiet night reads one week and nothing more. A brand with no AI visits
+ * before the week has nothing to compare with — every platform would be new
+ * — so it gets none.
*
* Only a source on the list (ai-sources.json) with NEW_PLATFORM_MIN_VISITS
* or more visits: the beacon is public, so a made-up source key or one stray
@@ -41,17 +43,11 @@ function utcMidnight(now, daysAgo) {
}
/**
- * The platforms new this week, most visits first: the merged reads of the
- * week and of everything before it. `unknown` is a referrer the source list
- * couldn't name, not a platform.
+ * The week's candidates, most visits first, with their first day: sources on
+ * the list with NEW_PLATFORM_MIN_VISITS or more. `unknown` is a referrer the
+ * source list couldn't name, not a platform.
*/
-export function newPlatforms(week, before) {
- if ((Number(before?.visits) || 0) === 0) return [];
- const earlier = new Set(
- (before?.platforms ?? [])
- .filter((p) => (Number(p.visits) || 0) > 0)
- .map((p) => String(p.platform)),
- );
+export function weekCandidates(week) {
const firstDay = new Map();
for (const d of week?.days ?? []) {
if ((Number(d.visits) || 0) === 0) continue;
@@ -62,11 +58,20 @@ export function newPlatforms(week, before) {
return (week?.platforms ?? [])
.map((p) => ({ platform: String(p.platform ?? ''), visits: Number(p.visits) || 0 }))
.filter((p) => p.visits >= NEW_PLATFORM_MIN_VISITS && KNOWN_SOURCES.has(p.platform))
- .filter((p) => !earlier.has(p.platform))
.map((p) => ({ ...p, firstDay: firstDay.get(p.platform) ?? null }))
.sort((a, b) => b.visits - a.visits || a.platform.localeCompare(b.platform));
}
+/**
+ * The platforms new this week: the week's candidates that sent no visit
+ * before it (`before`, from ai_traffic_platforms_seen), for a brand that
+ * had AI visits before it at all.
+ */
+export function newPlatforms(week, before) {
+ if (!before?.anyBefore) return [];
+ return weekCandidates(week).filter((p) => !before.seen.has(p.platform));
+}
+
async function merged(brandId, from, to) {
const { data, error } = await supabaseAdmin.rpc('ai_traffic_merged', {
p_brand_id: brandId,
@@ -79,6 +84,20 @@ async function merged(brandId, from, to) {
return data ?? {};
}
+/** Whether the brand had AI visits before `before`, and which of `platforms` sent one (00193). */
+async function platformsSeen(brandId, before, platforms) {
+ const { data, error } = await supabaseAdmin.rpc('ai_traffic_platforms_seen', {
+ p_brand_id: brandId,
+ p_before: before,
+ p_platforms: platforms,
+ });
+ if (error) throw new Error(error.message);
+ return {
+ anyBefore: data?.any_before === true,
+ seen: new Set(Array.isArray(data?.seen) ? data.seen.map(String) : []),
+ };
+}
+
/**
* Signal candidates for the platforms that started sending AI visits this
* week. Best effort: a failed read costs this finding for the night, never
@@ -87,10 +106,14 @@ async function merged(brandId, from, to) {
export async function newAiPlatformCandidates(brandId, { now = new Date() } = {}) {
try {
const weekStart = utcMidnight(now, 7);
- const [week, before] = await Promise.all([
- merged(brandId, weekStart, utcMidnight(now, 0)),
- merged(brandId, null, weekStart),
- ]);
+ const week = await merged(brandId, weekStart, utcMidnight(now, 0));
+ const candidates = weekCandidates(week);
+ if (candidates.length === 0) return [];
+ const before = await platformsSeen(
+ brandId,
+ weekStart,
+ candidates.map((p) => p.platform),
+ );
const analytics = analyticsDayCount(week.analytics_days) > 0;
return newPlatforms(week, before).map((p) => ({
kind: 'ai_platform_new',
diff --git a/server/src/lib/signals/traffic-platforms.test.js b/server/src/lib/signals/traffic-platforms.test.js
index 3e7a6c4b2..3e2fd1672 100644
--- a/server/src/lib/signals/traffic-platforms.test.js
+++ b/server/src/lib/signals/traffic-platforms.test.js
@@ -11,7 +11,8 @@ vi.mock('../../config/supabase.js', () => ({ default: { rpc: (...args) => rpc(..
const logger = vi.hoisted(() => ({ info: vi.fn(), warn: vi.fn(), error: vi.fn() }));
vi.mock('../logger.js', () => ({ logger }));
-const { newAiPlatformCandidates, newPlatforms } = await import('./traffic-platforms.js');
+const { newAiPlatformCandidates, newPlatforms, weekCandidates } =
+ await import('./traffic-platforms.js');
const NOW = new Date('2026-10-19T06:30:00Z');
@@ -21,15 +22,9 @@ beforeEach(() => {
});
describe('newPlatforms', () => {
- const before = {
- visits: 40,
- platforms: [
- { platform: 'chatgpt.com', visits: 30 },
- { platform: 'gemini.google.com', visits: 10 },
- // Listed, but with no visits: never sent one.
- { platform: 'claude.ai', visits: 0 },
- ],
- };
+ // As ai_traffic_platforms_seen answers it (00193): of the candidates asked
+ // about, ChatGPT sent visits before the week.
+ const before = { anyBefore: true, seen: new Set(['chatgpt.com']) };
it('names the platforms sending visits for the first time, with their first day', () => {
const week = {
@@ -56,33 +51,44 @@ describe('newPlatforms', () => {
{ platform: 'claude.ai', visits: 5, firstDay: '2026-10-14' },
{ platform: 'perplexity.ai', visits: 3, firstDay: '2026-10-17' },
]);
+ // Only these are asked about before the week.
+ expect(weekCandidates(week).map((p) => p.platform)).toEqual([
+ 'chatgpt.com',
+ 'claude.ai',
+ 'perplexity.ai',
+ ]);
});
it('has nothing new for a brand with no AI visits before the week', () => {
const week = { visits: 3, platforms: [{ platform: 'chatgpt.com', visits: 3 }] };
- expect(newPlatforms(week, { visits: 0, platforms: [] })).toEqual([]);
+ expect(newPlatforms(week, { anyBefore: false, seen: new Set() })).toEqual([]);
expect(newPlatforms(week, null)).toEqual([]);
});
});
describe('newAiPlatformCandidates', () => {
- it('reads the last seven whole days against everything before them', async () => {
- rpc.mockImplementation(async (_name, params) => ({
- data:
- params.p_from === null
- ? { visits: 12, platforms: [{ platform: 'chatgpt.com', visits: 12 }] }
- : {
- visits: 4,
- // A list of days, as ai_traffic_merged returns it (00176).
- analytics_days: [],
- platforms: [{ platform: 'perplexity.ai', visits: 4 }],
- days: [{ day: '2026-10-16', platform: 'perplexity.ai', visits: 4 }],
- },
+ const weekRead = (analyticsDays = []) => ({
+ visits: 16,
+ // A list of days, as ai_traffic_merged returns it (00176).
+ analytics_days: analyticsDays,
+ platforms: [
+ { platform: 'chatgpt.com', visits: 12 },
+ { platform: 'perplexity.ai', visits: 4 },
+ ],
+ days: [{ day: '2026-10-16', platform: 'perplexity.ai', visits: 4 }],
+ });
+ const reads = (week, seen = { any_before: true, seen: ['chatgpt.com'] }) =>
+ rpc.mockImplementation(async (name) => ({
+ data: name === 'ai_traffic_merged' ? week : seen,
error: null,
}));
+ it("reads the week, then asks only about its candidates' visits before it", async () => {
+ reads(weekRead());
+
const found = await newAiPlatformCandidates('b1', { now: NOW });
+ expect(rpc).toHaveBeenCalledTimes(2);
expect(rpc).toHaveBeenCalledWith('ai_traffic_merged', {
p_brand_id: 'b1',
p_from: '2026-10-12T00:00:00.000Z',
@@ -91,12 +97,11 @@ describe('newAiPlatformCandidates', () => {
p_to_inclusive: true,
p_analytics: true,
});
- expect(rpc).toHaveBeenCalledWith('ai_traffic_merged', {
+ // Not the whole history before the week (00193).
+ expect(rpc).toHaveBeenCalledWith('ai_traffic_platforms_seen', {
p_brand_id: 'b1',
- p_from: null,
- p_to: '2026-10-11T23:59:59.000Z',
- p_to_inclusive: true,
- p_analytics: true,
+ p_before: '2026-10-12T00:00:00.000Z',
+ p_platforms: ['chatgpt.com', 'perplexity.ai'],
});
expect(found).toEqual([
{
@@ -111,19 +116,14 @@ describe('newAiPlatformCandidates', () => {
]);
});
+ it('reads nothing more on a week with no candidate', async () => {
+ reads({ visits: 2, analytics_days: [], platforms: [{ platform: 'claude.ai', visits: 2 }] });
+ expect(await newAiPlatformCandidates('b1', { now: NOW })).toEqual([]);
+ expect(rpc).toHaveBeenCalledTimes(1);
+ });
+
it('says Analytics when the week read it', async () => {
- rpc.mockImplementation(async (_name, params) => ({
- data:
- params.p_from === null
- ? { visits: 12, platforms: [{ platform: 'chatgpt.com', visits: 12 }] }
- : {
- visits: 4,
- analytics_days: ['2026-10-16'],
- platforms: [{ platform: 'perplexity.ai', visits: 4 }],
- days: [{ day: '2026-10-16', platform: 'perplexity.ai', visits: 4 }],
- },
- error: null,
- }));
+ reads(weekRead(['2026-10-16']));
const [found] = await newAiPlatformCandidates('b1', { now: NOW });
expect(found.source).toEqual(['ga4']);
});
diff --git a/supabase/migrations/00193_ai_traffic_platforms_seen.sql b/supabase/migrations/00193_ai_traffic_platforms_seen.sql
new file mode 100644
index 000000000..f64bcc09f
--- /dev/null
+++ b/supabase/migrations/00193_ai_traffic_platforms_seen.sql
@@ -0,0 +1,79 @@
+-- ============================================================================
+-- 00193: "is this AI platform new?" reads only the platforms in question
+-- ============================================================================
+-- Follow-up from #1195's review (AT-013). The nightly "new AI platform" check
+-- (server signals/traffic-platforms.js) read the brand's whole AI traffic
+-- history before the week with ai_traffic_merged (00176), pages and days
+-- included, only to learn which platforms had sent a visit before.
+--
+-- ai_traffic_platforms_seen answers that directly, for the few platforms the
+-- week put forward: whether the brand had any AI visit before p_before, and
+-- which of p_platforms did. A snippet visit or an Analytics session counts,
+-- whichever day it fell on: for "seen before" any evidence will do, where
+-- ai_traffic_merged keeps one source per day so visits aren't counted twice.
+--
+-- Each platform is an index probe on the new (brand_id, source_platform,
+-- created_at) index; Analytics rows are daily and few. On a large
+-- ai_traffic_logs, build the index by hand first with `create index
+-- concurrently`, which doesn't hold back the beacon's writes; this statement
+-- then finds it in place.
+
+create index if not exists idx_ai_traffic_logs_brand_platform_time
+ on public.ai_traffic_logs (brand_id, source_platform, created_at)
+ where visit_of is null;
+
+create or replace function public.ai_traffic_platforms_seen(
+ p_brand_id uuid,
+ p_before timestamptz,
+ p_platforms text[]
+)
+returns jsonb
+language sql
+stable
+security invoker
+set search_path to 'public'
+as $$
+ select jsonb_build_object(
+ 'any_before',
+ exists (
+ select 1 from public.ai_traffic_logs l
+ where l.brand_id = p_brand_id
+ and l.visit_of is null
+ and l.created_at < p_before
+ )
+ or exists (
+ select 1 from public.ga_ai_traffic_stats g
+ where g.brand_id = p_brand_id
+ and g.sessions > 0
+ and g.date < (p_before at time zone 'utc')::date
+ ),
+ 'seen', coalesce((
+ select jsonb_agg(p.platform order by p.platform)
+ from unnest(p_platforms) as p(platform)
+ where exists (
+ select 1 from public.ai_traffic_logs l
+ where l.brand_id = p_brand_id
+ and l.visit_of is null
+ and l.source_platform = p.platform
+ and l.created_at < p_before
+ )
+ or exists (
+ select 1 from public.ga_ai_traffic_stats g
+ where g.brand_id = p_brand_id
+ and g.sessions > 0
+ and coalesce(g.platform, g.source) = p.platform
+ and g.date < (p_before at time zone 'utc')::date
+ )
+ ), '[]'::jsonb)
+ );
+$$;
+
+revoke all on function public.ai_traffic_platforms_seen(uuid, timestamptz, text[])
+ from public, anon;
+grant execute on function public.ai_traffic_platforms_seen(uuid, timestamptz, text[])
+ to authenticated, service_role;
+
+comment on function public.ai_traffic_platforms_seen(uuid, timestamptz, text[]) is
+ 'AI Traffic (AT-013): whether a brand had any AI-referred visit before p_before (snippet or Analytics), and which of p_platforms sent one, for the nightly new-platform check. Security invoker: RLS decides the brand.';
+
+notify pgrst, 'reload schema';
diff --git a/supabase/schema.sql b/supabase/schema.sql
index faed8604b..810a9a369 100644
--- a/supabase/schema.sql
+++ b/supabase/schema.sql
@@ -26541,3 +26541,86 @@ create trigger prompts_queue_insights_rollup_rebuild
notify pgrst, 'reload schema';
+-- ─────────────────────────────────────────────────────────────────────────
+-- migrations/00193_ai_traffic_platforms_seen.sql
+-- ─────────────────────────────────────────────────────────────────────────
+-- ============================================================================
+-- 00193: "is this AI platform new?" reads only the platforms in question
+-- ============================================================================
+-- Follow-up from #1195's review (AT-013). The nightly "new AI platform" check
+-- (server signals/traffic-platforms.js) read the brand's whole AI traffic
+-- history before the week with ai_traffic_merged (00176), pages and days
+-- included, only to learn which platforms had sent a visit before.
+--
+-- ai_traffic_platforms_seen answers that directly, for the few platforms the
+-- week put forward: whether the brand had any AI visit before p_before, and
+-- which of p_platforms did. A snippet visit or an Analytics session counts,
+-- whichever day it fell on: for "seen before" any evidence will do, where
+-- ai_traffic_merged keeps one source per day so visits aren't counted twice.
+--
+-- Each platform is an index probe on the new (brand_id, source_platform,
+-- created_at) index; Analytics rows are daily and few. On a large
+-- ai_traffic_logs, build the index by hand first with `create index
+-- concurrently`, which doesn't hold back the beacon's writes; this statement
+-- then finds it in place.
+
+create index if not exists idx_ai_traffic_logs_brand_platform_time
+ on public.ai_traffic_logs (brand_id, source_platform, created_at)
+ where visit_of is null;
+
+create or replace function public.ai_traffic_platforms_seen(
+ p_brand_id uuid,
+ p_before timestamptz,
+ p_platforms text[]
+)
+returns jsonb
+language sql
+stable
+security invoker
+set search_path to 'public'
+as $$
+ select jsonb_build_object(
+ 'any_before',
+ exists (
+ select 1 from public.ai_traffic_logs l
+ where l.brand_id = p_brand_id
+ and l.visit_of is null
+ and l.created_at < p_before
+ )
+ or exists (
+ select 1 from public.ga_ai_traffic_stats g
+ where g.brand_id = p_brand_id
+ and g.sessions > 0
+ and g.date < (p_before at time zone 'utc')::date
+ ),
+ 'seen', coalesce((
+ select jsonb_agg(p.platform order by p.platform)
+ from unnest(p_platforms) as p(platform)
+ where exists (
+ select 1 from public.ai_traffic_logs l
+ where l.brand_id = p_brand_id
+ and l.visit_of is null
+ and l.source_platform = p.platform
+ and l.created_at < p_before
+ )
+ or exists (
+ select 1 from public.ga_ai_traffic_stats g
+ where g.brand_id = p_brand_id
+ and g.sessions > 0
+ and coalesce(g.platform, g.source) = p.platform
+ and g.date < (p_before at time zone 'utc')::date
+ )
+ ), '[]'::jsonb)
+ );
+$$;
+
+revoke all on function public.ai_traffic_platforms_seen(uuid, timestamptz, text[])
+ from public, anon;
+grant execute on function public.ai_traffic_platforms_seen(uuid, timestamptz, text[])
+ to authenticated, service_role;
+
+comment on function public.ai_traffic_platforms_seen(uuid, timestamptz, text[]) is
+ 'AI Traffic (AT-013): whether a brand had any AI-referred visit before p_before (snippet or Analytics), and which of p_platforms sent one, for the nightly new-platform check. Security invoker: RLS decides the brand.';
+
+notify pgrst, 'reload schema';
+