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.
TypeScript aeoai-agentai-searchanswer-engine-optimizationbrand-monitoringchatgptclaudecopilotdockergeminigeogoogle-ai-overviewsgrokmcpnextjsopen-sourceperplexityseosupabasetypescript
feat(action-center): show an action's result net of the prompts it didn't touch (learning B2) (#1701)
Cihan10287cdd3a69
diff --git a/docs/guides/action-center.mdx b/docs/guides/action-center.mdxindex d30182e2c..9ab31d8da 100644--- a/docs/guides/action-center.mdx+++ b/docs/guides/action-center.mdx@@ -193,7 +193,7 @@ The **History** tab lists actions once they are In Progress, On Hold, CompletedClick an action to see **What was the goal?**, **What happened?** (the signals it was built from), its affected items and tasks, and the **Result**:-- A completed action's metrics are read three times: over the week ending 7, 14 and 30 days after it closed, each against the 7 days before it was raised. Until the reading on day 30, which is final, the result reads *so far*, and the drawer lists each reading. The result reads **Improved**, **Mixed**, **No meaningful change** or **Declined**, judged by the action's main metric (the first one it names): **Mixed** when another metric it names moved the other way, or, without the main one measured, when the ones it names moved both ways. Other metrics show beside but don't count. It is measured after the action, not proven to be caused by it. An action that names its prompts or pages is measured on them, with the brand-wide figures over the same days beside; when they can't show its main metric (citations, for prompts), it is measured brand-wide. A Site Audit fix is judged by its pages audited again since it closed: the check that raised it passing, or a low score past the line; with none audited again yet, by the metrics. When tracking missed nights in either week, the drawer says so, and mentions and citations are read at a full week's worth from the nights that ran. More than two in one week are too few to read them from: they're left out of the result, and an action whose main metric is one of them reads **Not measurable**. The History drawer also says what became of the signals that raised it by then: how many ended, turned into another, were dismissed, or are still open.+- A completed action's metrics are read three times: over the week ending 7, 14 and 30 days after it closed, each against the 7 days before it was raised. Until the reading on day 30, which is final, the result reads *so far*, and the drawer lists each reading. The result reads **Improved**, **Mixed**, **No meaningful change** or **Declined**, judged by the action's main metric (the first one it names): **Mixed** when another metric it names moved the other way, or, without the main one measured, when the ones it names moved both ways. Other metrics show beside but don't count. It is measured after the action, not proven to be caused by it. An action that names its prompts or pages is measured on them, with the brand-wide figures over the same days beside; when they can't show its main metric (citations, for prompts), it is measured brand-wide. Its prompts' change is also shown net of the brand's prompts it didn't touch over the same days (the other prompts in its topics, or the brand's others), so what moved for every prompt, such as an engine's update, is told apart from what moved for its own (a count from fewer than 5 before isn't netted: one more would read as a big swing); the result itself stays as measured. A Site Audit fix is judged by its pages audited again since it closed: the check that raised it passing, or a low score past the line; with none audited again yet, by the metrics. When tracking missed nights in either week, the drawer says so, and mentions and citations are read at a full week's worth from the nights that ran. More than two in one week are too few to read them from: they're left out of the result, and an action whose main metric is one of them reads **Not measurable**. The History drawer also says what became of the signals that raised it by then: how many ended, turned into another, were dismissed, or are still open.- Only a completed action is measured: a dismissed one reads **Not measured**, dismissed. One with no metric to read is **Not measurable**.- An action sent from a prompt's Improve tab reports on how many platforms its position improved. It is read again daily while the action is open and for 30 days after it is completed.diff --git a/server/src/lib/action-center/basket-metrics.js b/server/src/lib/action-center/basket-metrics.jsindex 1d12c8c9c..4ac1f0f0d 100644--- a/server/src/lib/action-center/basket-metrics.js+++ b/server/src/lib/action-center/basket-metrics.js@@ -149,3 +149,88 @@ export async function measureBasket(brandId, scope, from, to) {if (error) throw new Error(`opportunity_basket_metrics: ${error.message}`);return basketValues(data || {}, { pageCount: pages.keys.length });}++/** Fewest prompts a control basket is read from: fewer, and one prompt's swing is its result. */+export const CONTROL_MIN_PROMPTS = 5;+/** Most prompts it is read from. */+const CONTROL_MAX_PROMPTS = 300;++/**+ * The control basket (learning B2): the brand's active prompts the action+ * didn't touch — in the same topics as its own first, else any of the+ * brand's — read over the same windows, so what moved for every prompt (an+ * engine's update, a season, a night tracking missed) is told apart from+ * what moved for the action's own. Its prompts only, never another brand's,+ * and only ones tracked by `since` (the first day of the week before): one+ * added later reads in the week after alone, and would swell it. Null with+ * too few to read.+ *+ * @returns {Promise<{ basis: 'topics' | 'brand', promptIds: string[], pages: [] } | null>}+ */+export async function controlScope(brandId, promptIds, since) {+ if (!promptIds?.length) return null;+ const own = new Set(promptIds);+ const { data: targets, error } = await supabaseAdmin+ .from('prompts')+ .select('topic_id')+ .in('id', promptIds.slice(0, 200));+ if (error) throw new Error(error.message);+ const topics = [...new Set((targets ?? []).map((p) => p.topic_id).filter(Boolean))];+ const others = async (byTopic) => {+ let query = supabaseAdmin+ .from('prompts')+ .select('id, prompt_sets!inner(brand_id)')+ .eq('prompt_sets.brand_id', brandId)+ .eq('is_active', true)+ .lt('created_at', `${since}T00:00:00Z`);+ if (byTopic) query = query.in('topic_id', topics);+ const { data, error: readError } = await query+ .order('id')+ .limit(CONTROL_MAX_PROMPTS + own.size);+ if (readError) throw new Error(readError.message);+ return (data ?? [])+ .map((p) => p.id)+ .filter((id) => !own.has(id))+ .slice(0, CONTROL_MAX_PROMPTS);+ };+ let basis = 'topics';+ let ids = topics.length ? await others(true) : [];+ if (ids.length < CONTROL_MIN_PROMPTS) {+ basis = 'brand';+ ids = await others(false);+ }+ return ids.length >= CONTROL_MIN_PROMPTS ? { basis, promptIds: ids, pages: [] } : null;+}++/**+ * Fewest the action's count must read before to be netted: from 2, one more+ * mention reads +50%, a swing no control speaks to.+ */+export const CONTROL_MIN_COUNT = 5;++/**+ * The action's change net of the control's (learning B2), a difference in+ * differences, for each metric both read: a rate in points (its move minus+ * theirs), a count in percent (its relative move minus theirs, so a basket+ * of 300 prompts weighs as one of 3), not from fewer than CONTROL_MIN_COUNT+ * before. Never AI sessions: they're read on pages, and a control of+ * prompts has none.+ *+ * @returns {Array<{ metric: string, net: number, unit: 'points' | 'percent', control: { before: number, after: number } }>}+ */+export function netEffect(metrics, controlValues) {+ const read = (before, after) => before != null && after != null;+ return metrics.flatMap((m) => {+ if (m.unit === 'sessions') return [];+ const before = controlValues.before[m.metric];+ const after = controlValues.after[m.metric];+ if (!read(m.before, m.after) || !read(before, after)) return [];+ if (m.unit === 'count') {+ if (!(m.before >= CONTROL_MIN_COUNT && before > 0)) return [];+ const net = round1((m.after / m.before - after / before) * 100);+ return [{ metric: m.metric, net, unit: 'percent', control: { before, after } }];+ }+ const net = round1(m.after - m.before - (after - before));+ return [{ metric: m.metric, net, unit: 'points', control: { before, after } }];+ });+}diff --git a/server/src/lib/action-center/basket-metrics.test.js b/server/src/lib/action-center/basket-metrics.test.jsindex 09a469bd0..96a98b1b3 100644--- a/server/src/lib/action-center/basket-metrics.test.js+++ b/server/src/lib/action-center/basket-metrics.test.js@@ -5,20 +5,43 @@ vi.mock('../../config/supabase.js', () => ({default: { from: (table) => tables[table]() },}));-const { BASKET_KPIS, basketScope, basketValues, pageScope } = await import('./basket-metrics.js');+const {+ BASKET_KPIS,+ CONTROL_MIN_COUNT,+ basketScope,+ basketValues,+ controlScope,+ netEffect,+ pageScope,+} = await import('./basket-metrics.js');/** A query builder that resolves to `result` however it is chained. */function chain(result) {const b = {select: () => b,eq: () => b,- in: () => Promise.resolve(result),+ in: () => b,+ lt: () => b,+ order: () => b,+ limit: () => Promise.resolve(result),maybeSingle: () => Promise.resolve(result),then: (resolve) => resolve(result),};return b;}+/** `chain`, recording each filter it is given as [method, ...args] in `calls`. */+function recordingChain(result, calls) {+ const b = chain(result);+ for (const method of ['eq', 'in', 'lt']) {+ b[method] = (...args) => {+ calls.push([method, ...args]);+ return b;+ };+ }+ return b;+}+describe('pageScope', () => {it('turns page URLs into citation keys, hosts and GA paths', () => {expect(@@ -127,3 +150,126 @@ describe('basketScope', () => {).toEqual(['p1']);});});++/**+ * The control basket (learning B2): the brand's prompts the action didn't+ * touch, and its change net of theirs.+ */+describe('netEffect', () => {+ const metric = (name, unit, before, after) => ({ metric: name, unit, before, after });++ it('takes a rate in points and a count in percent, net of the control', () => {+ expect(+ netEffect(+ [+ metric('ai_visibility', 'percent', 20, 30),+ metric('mentions', 'count', 10, 15),+ metric('citations', 'count', 4, 8),+ ],+ {+ before: { ai_visibility: 40, mentions: 200, citations: null },+ after: { ai_visibility: 44, mentions: 220, citations: null },+ },+ ),+ ).toEqual([+ { metric: 'ai_visibility', net: 6, unit: 'points', control: { before: 40, after: 44 } },+ { metric: 'mentions', net: 40, unit: 'percent', control: { before: 200, after: 220 } },+ ]);+ });++ it('leaves out a count with nothing before to scale by', () => {+ expect(+ netEffect([metric('mentions', 'count', 0, 3)], {+ before: { mentions: 10 },+ after: { mentions: 12 },+ }),+ ).toEqual([]);+ });++ it('never nets AI sessions: a control of prompts has no pages to read them on', () => {+ expect(+ netEffect([metric('ai_referral_traffic', 'sessions', 40, 80)], {+ before: { ai_referral_traffic: 100 },+ after: { ai_referral_traffic: 100 },+ }),+ ).toEqual([]);+ });++ it('leaves out a count read from fewer than five before: one more is a swing, not a result', () => {+ const control = { before: { mentions: 100 }, after: { mentions: 100 } };+ expect(CONTROL_MIN_COUNT).toBe(5);+ // 4 → 6 would read +50% net.+ expect(netEffect([metric('mentions', 'count', 4, 6)], control)).toEqual([]);+ expect(netEffect([metric('mentions', 'count', 5, 6)], control)).toEqual([+ { metric: 'mentions', net: 20, unit: 'percent', control: { before: 100, after: 100 } },+ ]);+ });+});++describe('controlScope', () => {+ /** The first day of the week before the action was raised. */+ const SINCE = '2026-09-01';+ const others = (n, topic = 't1') =>+ Array.from({ length: n }, (_, i) => ({ id: `c${i + 1}`, topic_id: topic }));++ it("takes the brand's other prompts in the action's topics, never its own", async () => {+ tables.prompts = () =>+ chain({ data: [{ id: 'p1', topic_id: 't1' }, ...others(6)], error: null });+ const scope = await controlScope('b1', ['p1'], SINCE);+ expect(scope).toEqual({+ basis: 'topics',+ promptIds: ['c1', 'c2', 'c3', 'c4', 'c5', 'c6'],+ pages: [],+ });+ });++ it("falls back to the brand's other prompts, and reads none from too few", async () => {+ let call = 0;+ // Its topic has two others; the brand has six.+ tables.prompts = () =>+ chain({+ data: call++ < 2 ? [{ id: 'p1', topic_id: 't1' }, ...others(2)] : others(6, 't9'),+ error: null,+ });+ expect((await controlScope('b1', ['p1'], SINCE)).basis).toBe('brand');++ tables.prompts = () => chain({ data: others(3), error: null });+ expect(await controlScope('b1', ['p1'], SINCE)).toBeNull();+ expect(await controlScope('b1', [], SINCE)).toBeNull();+ });++ it('leaves out prompts tracked after the week before began: they read in the week after alone', async () => {+ const calls = [];+ tables.prompts = () =>+ recordingChain({ data: [{ id: 'p1', topic_id: 't1' }, ...others(6)], error: null }, calls);+ await controlScope('b1', ['p1'], SINCE);+ expect(calls).toContainEqual(['lt', 'created_at', '2026-09-01T00:00:00Z']);+ });++ it("reads only the brand's own active prompts, in its topics and when it falls back", async () => {+ // Each query's filters; its topic has two others, so it falls back to the brand.+ const queries = [];+ tables.prompts = () => {+ const calls = [];+ queries.push(calls);+ return recordingChain(+ {+ data: queries.length < 3 ? [{ id: 'p1', topic_id: 't1' }, ...others(2)] : others(6),+ error: null,+ },+ calls,+ );+ };+ expect((await controlScope('b1', ['p1'], SINCE)).basis).toBe('brand');++ // The first query reads its own prompts' topics; the others, the control.+ const [targets, inTopics, inBrand] = queries;+ expect(targets).toEqual([['in', 'id', ['p1']]]);+ for (const calls of [inTopics, inBrand]) {+ expect(calls).toContainEqual(['eq', 'prompt_sets.brand_id', 'b1']);+ expect(calls).toContainEqual(['eq', 'is_active', true]);+ }+ expect(inTopics).toContainEqual(['in', 'topic_id', ['t1']]);+ expect(inBrand.some(([method]) => method === 'in')).toBe(false);+ });+});diff --git a/server/src/lib/action-center/validate.js b/server/src/lib/action-center/validate.jsindex d7e5dd61f..89fc1bd1c 100644--- a/server/src/lib/action-center/validate.js+++ b/server/src/lib/action-center/validate.js@@ -27,7 +27,13 @@ import supabaseAdmin from '../../config/supabase.js';import { computeAiVisibilityScore } from '../../config/visibility-score.js';import { logger } from '../logger.js';import { resolve } from '../../config/action-engine.js';-import { BASKET_KPIS, basketScope, measureBasket } from './basket-metrics.js';+import {+ BASKET_KPIS,+ basketScope,+ controlScope,+ measureBasket,+ netEffect,+} from './basket-metrics.js';import { auditOutcome, auditRecheck } from './audit-recheck.js';const DAY_MS = 86_400_000;@@ -416,7 +422,10 @@ export async function validateAction(action, { now = new Date() } = {}) {// Each reading due, in order; the action keeps the last one's figures and// verdict, every reading's verdict and metrics, and whether it's final.+ // The control's prompts and its week before (B2) are the same for each:+ // read for the first, kept for the rest.const readings = [...previous];+ const controlReads = {};let last = null;for (const day of due) {last = await measureReading(action, {@@ -425,6 +434,7 @@ export async function validateAction(action, { now = new Date() } = {}) {signals,audit,now,+ controlReads,});readings.push({day,@@ -449,14 +459,60 @@ export async function validateAction(action, { now = new Date() } = {}) {return last.verdict;}+/**+ * A basket's control (learning B2): the brand's prompts it didn't touch,+ * read over the same windows, its values as read. The basket's change net+ * of theirs is taken when the reading finishes, its counts on the same+ * scale as the result's (A6). Kept beside the result, not in its verdict.+ * Null with too few prompts to read, or a read that fails: the result+ * stands as it was. Its prompts and week before, the same for every+ * reading of the action, are read once into `shared`.+ */+async function controlOf(action, promptIds, { beforeWindow, afterWindow }, shared = {}) {+ const brandId = action.brand_id;+ try {+ shared.scope ??= controlScope(brandId, promptIds, beforeWindow.from);+ const scope = await shared.scope;+ if (!scope) return null;+ shared.before ??= measureBasket(brandId, scope, beforeWindow.from, beforeWindow.to);+ const [before, after] = await Promise.all([+ shared.before,+ measureBasket(brandId, scope, afterWindow.from, afterWindow.to),+ ]);+ return { basis: scope.basis, prompts: scope.promptIds.length, before, after };+ } catch (err) {+ logger.warn(+ { err: err.message, brandId, actionId: action.id },+ '[action-validation] control basket not read',+ );+ return null;+ }+}++/** The control's values with its counts at a full window's worth, as the result's are (A6). */+function fullWindowControl({ before, after }, nights) {+ const scaled = fullWindowCounts(+ Object.keys(before).map((metric) => ({ metric, before: before[metric], after: after[metric] })),+ nights,+ );+ return {+ before: Object.fromEntries(scaled.map((m) => [m.metric, m.before])),+ after: Object.fromEntries(scaled.map((m) => [m.metric, m.after])),+ };+}+/*** One reading of a closed action (learning B1): what it keeps and its* verdict, over the week `afterWindow` against the week before it was raised.*/-async function measureReading(action, { beforeWindow, afterWindow, signals, audit, now }) {+async function measureReading(+ action,+ { beforeWindow, afterWindow, signals, audit, now, controlReads },+) {// The verdict from the metrics kept, by its main metric; given `aims`,- // only the metrics the action names count (see deriveOutcome).- const finish = async (validation, aims = null) => {+ // only the metrics the action names count (see deriveOutcome). Given its+ // `control` (B2), its change net of the control's kept beside.+ const finish = async (validation, aims = null, control = null) => {// Nights tracking missed in either window (A6), when a count was read.// Up to MAX_GAP_DAYS, its counts are read at a full window's worth; past// it, too few nights ran to scale from: the counts stay as read and@@ -487,14 +543,21 @@ async function measureReading(action, { beforeWindow, afterWindow, signals, audi: {}),}: validation;- const beside = { ...(signals ? { signals } : {}), ...(audit ? { audit } : {}), ...gaps };- const kept =- read || Object.keys(beside).length- ? { measuredAt: now.toISOString(), ...(read ?? {}), ...beside }- : null;const comparable = tooMany? read?.metrics.filter((m) => !COUNT_METRICS.has(m.metric)): read?.metrics;+ // Net of the control (B2) on the result's scale: its counts read at a+ // full week's worth over the same nights, or, past MAX_GAP_DAYS, left+ // out with the result's.+ const net = read && control ? netEffect(comparable, fullWindowControl(control, nights)) : [];+ const measured = net.length+ ? { ...read, control: { basis: control.basis, prompts: control.prompts, net } }+ : read;+ const beside = { ...(signals ? { signals } : {}), ...(audit ? { audit } : {}), ...gaps };+ const kept =+ measured || Object.keys(beside).length+ ? { measuredAt: now.toISOString(), ...(measured ?? {}), ...beside }+ : null;const outcome =!read || (tooMany && COUNT_METRICS.has(read.primary))? 'not_measurable'@@ -532,6 +595,12 @@ async function measureReading(action, { beforeWindow, afterWindow, signals, audi}));// Its aim: the first of its success metrics a basket reads, else its visibility.const primary = (action.kpi_keys ?? []).find((key) => key in BASKET_KPIS) ?? 'ai_visibility';+ const control = await controlOf(+ action,+ scope.promptIds,+ { beforeWindow, afterWindow },+ controlReads,+ );return finish({measuredAt: now.toISOString(),@@ -542,6 +611,7 @@ async function measureReading(action, { beforeWindow, afterWindow, signals, audiscope: { kind: 'basket', prompts: scope.promptIds.length, pages: scope.pages.length },},action.kpi_keys ?? [],+ control,);}@@ -589,6 +659,12 @@ async function measureReading(action, { beforeWindow, afterWindow, signals, audibefore: brandBefore[metric] ?? null,after: brandAfter[metric] ?? null,}));+ const control = await controlOf(+ action,+ targets.promptIds,+ { beforeWindow, afterWindow },+ controlReads,+ );return finish({measuredAt: now.toISOString(),@@ -600,6 +676,7 @@ async function measureReading(action, { beforeWindow, afterWindow, signals, audi...(brandWide.length ? { brandWide } : {}),},asked,+ control,);}// Read already, for the brand-wide measure below.diff --git a/server/src/lib/action-center/validate.test.js b/server/src/lib/action-center/validate.test.jsindex d0704f418..9e101e52b 100644--- a/server/src/lib/action-center/validate.test.js+++ b/server/src/lib/action-center/validate.test.js@@ -9,6 +9,7 @@ vi.mock('../logger.js', () => ({logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },}));+import { logger } from '../logger.js';import {MAX_GAP_DAYS,sweepActionValidation,@@ -29,7 +30,7 @@ const EVERY_NIGHT = Array.from({ length: 60 }, (_, i) => ({ completed_at: daysAg/** Records every write so a test can assert what was stored; `rows` answers a table's reads. */function mockWrites(rows = {}) {rows = { tracking_runs: EVERY_NIGHT, ...rows };- const writes = { updated: [], inserted: [], ors: [] };+ const writes = { updated: [], inserted: [], ors: [], lts: [] };from.mockImplementation((table) => {const builder = {or: (filter) => {@@ -45,7 +46,10 @@ function mockWrites(rows = {}) {limit: () => builder,order: () => builder,gt: () => builder,- lt: () => builder,+ lt: (...args) => {+ writes.lts.push({ table, args });+ return builder;+ },in: () => builder,maybeSingle: async () => ({ data: (rows[table] ?? [])[0] ?? null, error: null }),update: (patch) => {@@ -272,6 +276,90 @@ describe('validateAction', () => {expect(outcome).not.toBeNull();});+ /** Net of the brand's prompts it didn't touch (learning B2), beside the result. */+ it("keeps a basket's change net of the brand's other prompts over the same windows", async () => {+ const writes = mockWrites({+ prompts: [+ { id: 'p1', topic_id: 't1' },+ ...Array.from({ length: 6 }, (_, i) => ({ id: `c${i + 1}`, topic_id: 't1' })),+ ],+ });+ // The action's prompts went from 20% to 30% visible; the others from 40% to 44%.+ let reads = 0;+ rpc.mockImplementation(async (name, args) => {+ if (name !== 'opportunity_basket_metrics') return { data: {}, error: null };+ const own = args.p_prompt_ids.includes('p1');+ const after = reads++ % 2 === 1;+ return {+ data: { cells: 100, visible: own ? (after ? 30 : 20) : after ? 44 : 40 },+ error: null,+ };+ });++ await validateAction(+ action({+ kind: 'mention_review',+ kpi_keys: ['ai_visibility'],+ payload: { promptIds: ['p1'] },+ }),+ { now: NOW },+ );++ const patch = writes.updated.find((w) => w.table === 'actions').patch;+ expect(patch.validation.control).toMatchObject({+ basis: 'topics',+ prompts: 6,+ net: expect.arrayContaining([+ { metric: 'ai_visibility', net: 6, unit: 'points', control: { before: 40, after: 44 } },+ ]),+ });+ // Beside the result, not in its verdict.+ expect(patch.outcome).toBe('improved');+ // Of the prompts tracked by the first day of the week before it was raised.+ expect(writes.lts).toContainEqual({+ table: 'prompts',+ args: ['created_at', `${daysAgo(37).slice(0, 10)}T00:00:00Z`],+ });+ });++ it('keeps the result as it was, no control beside, when the control fails to read', async () => {+ const run = async (prompts, controlFails) => {+ const writes = mockWrites({+ prompts: [+ { id: 'p1', topic_id: 't1' },+ ...Array.from({ length: prompts }, (_, i) => ({ id: `c${i + 1}`, topic_id: 't1' })),+ ],+ });+ rpc.mockImplementation(async (name, args) => {+ if (name !== 'opportunity_basket_metrics') return { data: {}, error: null };+ if (!args.p_prompt_ids.includes('p1') && controlFails) {+ return { data: null, error: { message: 'statement timeout' } };+ }+ const before = args.p_from < daysAgo(20).slice(0, 10);+ return { data: { cells: 100, visible: before ? 20 : 30 }, error: null };+ });+ await validateAction(+ action({+ kind: 'mention_review',+ kpi_keys: ['ai_visibility'],+ payload: { promptIds: ['p1'] },+ }),+ { now: NOW },+ );+ return writes.updated.find((w) => w.table === 'actions').patch;+ };++ const failed = await run(6, true);+ expect(failed.validation.control).toBeUndefined();+ expect(logger.warn).toHaveBeenCalledWith(+ { err: 'opportunity_basket_metrics: statement timeout', brandId: 'brand-1', actionId: 'a1' },+ '[action-validation] control basket not read',+ );+ expect(failed.outcome).toBe('improved');+ // The same as an action with no control to read.+ expect(failed).toEqual(await run(0, false));+ });+it('measures before and after over equal windows and stores both', async () => {const writes = mockWrites();rpc@@ -495,6 +583,41 @@ describe('validateAction', () => {expect(validation.brandWide.map((m) => m.metric)).toEqual(['ai_visibility', 'citations']);});+ it("keeps the prompts it names net of the brand's others beside (learning B2)", async () => {+ const writes = mockWrites({+ prompts: [+ { id: P1, topic_id: 't1' },+ ...Array.from({ length: 6 }, (_, i) => ({ id: `c${i + 1}`, topic_id: 't1' })),+ ],+ });+ // Its prompt 20% → 60% visible; the others 40% → 44%.+ rpc.mockImplementation(async (name, args) => {+ if (name !== 'opportunity_basket_metrics') return { data: {}, error: null };+ const before = args.p_from < daysAgo(20).slice(0, 10);+ const visible = args.p_prompt_ids.includes(P1) ? (before ? 2 : 6) : before ? 40 : 44;+ return { data: { cells: args.p_prompt_ids.includes(P1) ? 10 : 100, visible }, error: null };+ });++ await validateAction(+ action({+ kind: 'recover_lost_visibility',+ kpi_keys: ['ai_visibility'],+ payload: { targetEntity: 'prompts', targets: [{ id: P1 }] },+ }),+ { now: NOW },+ );++ const { validation } = writes.updated.find((w) => w.table === 'actions').patch;+ expect(validation.scope.kind).toBe('targets');+ expect(validation.control).toEqual({+ basis: 'topics',+ prompts: 6,+ net: [+ { metric: 'ai_visibility', net: 36, unit: 'points', control: { before: 40, after: 44 } },+ ],+ });+ });+it('measures brand-wide when the basket can’t read its main metric', async () => {// Citations first, on prompts: a prompt basket has no pages to count them on.const writes = mockWrites();@@ -730,6 +853,79 @@ describe('validateAction', () => {expect(MAX_GAP_DAYS).toBe(2);});+ /** Net of the brand's other prompts (learning B2), on the same scale as the result. */+ describe("an action's change net of its control", () => {+ /** The control's prompts: six others in its topic. */+ const prompts = [+ { id: 'p1', topic_id: 't1' },+ ...Array.from({ length: 6 }, (_, i) => ({ id: `c${i + 1}`, topic_id: 't1' })),+ ];+ /** The basket's prompts answer `own`, the control's `others`, each [before, after]. */+ const baskets = (own, others) =>+ rpc.mockImplementation(async (name, args) => {+ if (name !== 'opportunity_basket_metrics') return { data: {}, error: null };+ const [before, after] = args.p_prompt_ids.includes('p1') ? own : others;+ return { data: args.p_from < daysAgo(20).slice(0, 10) ? before : after, error: null };+ });+ const sent = (kpiKeys) =>+ action({ kind: 'mention_review', kpi_keys: kpiKeys, payload: { promptIds: ['p1'] } });++ it('reads its counts at a full week’s worth too, from the same nights', async () => {+ // Two nights missed in the week after. Per night its mentions doubled+ // (1 → 2) and the others' held (20 → 20): read as they came, 7 → 10+ // and 140 → 100 net to +71.4%; a week's worth, 7 → 14 and 140 → 140.+ const writes = mockWrites({ prompts, tracking_runs: missing([5, 6]) });+ baskets(+ [+ { cells: 70, visible: 14, mention_answers: 7 },+ { cells: 50, visible: 10, mention_answers: 10 },+ ],+ [+ { cells: 420, visible: 140, mention_answers: 140 },+ { cells: 300, visible: 100, mention_answers: 100 },+ ],+ );++ await validateAction(sent(['mentions']), { now: NOW });++ const { validation } = writes.updated.find((w) => w.table === 'actions').patch;+ expect(validation.gaps).toEqual({ before: 0, after: 2 });+ expect(validation.metrics.find((m) => m.metric === 'mentions')).toMatchObject({+ before: 7,+ after: 14,+ });+ expect(validation.control.net).toContainEqual({+ metric: 'mentions',+ net: 100,+ unit: 'percent',+ control: { before: 140, after: 140 },+ });+ });++ it('past MAX_GAP_DAYS nets the rates alone, the counts left out with the result’s', async () => {+ const writes = mockWrites({ prompts, tracking_runs: missing([3, 4, 5, 6]) });+ baskets(+ [+ { cells: 100, visible: 20, mention_answers: 10 },+ { cells: 100, visible: 30, mention_answers: 20 },+ ],+ [+ { cells: 100, visible: 40, mention_answers: 200 },+ { cells: 100, visible: 44, mention_answers: 120 },+ ],+ );++ expect(await validateAction(sent(['ai_visibility']), { now: NOW })).toBe('improved');++ const { validation } = writes.updated.find((w) => w.table === 'actions').patch;+ expect(validation.gaps).toEqual({ before: 0, after: 4, tooMany: true });+ const netted = validation.control.net.map((m) => m.metric);+ expect(netted).toContain('ai_visibility');+ expect(netted).not.toContain('mentions');+ expect(validation.control.net.find((m) => m.metric === 'ai_visibility').net).toBe(6);+ });+ });+it('doesn’t count nights for metrics tracking doesn’t read (AI sessions)', async () => {const writes = mockWrites({ tracking_runs: [] });rpc.mockResolvedValue({ data: {}, error: null });@@ -809,6 +1005,40 @@ describe('validateAction', () => {});});+ it("reads the control's prompts and week before once for every reading due (learning B2)", async () => {+ const writes = mockWrites({+ prompts: [+ { id: 'p1', topic_id: 't1' },+ ...Array.from({ length: 6 }, (_, i) => ({ id: `c${i + 1}`, topic_id: 't1' })),+ ],+ });+ rpc.mockResolvedValue({ data: { cells: 100, visible: 40 }, error: null });++ await validateAction(+ action({+ kind: 'mention_review',+ kpi_keys: ['ai_visibility'],+ payload: { promptIds: ['p1'] },+ created_at: daysAgo(50),+ completed_at: daysAgo(40),+ }),+ { now: NOW },+ );++ const { validation } = writes.updated.find((w) => w.table === 'actions').patch;+ expect(validation.readings.map((r) => r.day)).toEqual([7, 14, 30]);+ expect(validation.control).toMatchObject({ basis: 'topics', prompts: 6 });+ // Its topics, then the control's prompts: once, not for each reading.+ expect(from.mock.calls.filter(([table]) => table === 'prompts')).toHaveLength(2);+ // The control's week before once, and each reading's week after.+ const controlReads = rpc.mock.calls+ .filter(([name]) => name === 'opportunity_basket_metrics')+ .filter(([, args]) => !args.p_prompt_ids.includes('p1'))+ .map(([, args]) => args.p_from);+ expect(controlReads).toHaveLength(4);+ expect(controlReads.filter((day) => day === daysAgo(57).slice(0, 10))).toHaveLength(1);+ });+it('adds the readings due to those it has, and reads nothing once final', async () => {let writes = mockWrites();byDay({ [daysAgo(20).slice(0, 10)]: 140 });diff --git a/web/messages/en.json b/web/messages/en.jsonindex 1d7f3260d..f5b0978c9 100644--- a/web/messages/en.json+++ b/web/messages/en.json@@ -2625,6 +2625,9 @@"finalOn": "The final reading is on day {day}.","measuredOn": "Measured on the {entity, select, pages {{count, plural, one {page} other {# pages}}} other {{count, plural, one {prompt} other {# prompts}}}} it named.","brandWide": "Brand-wide over the same days: {list}",+ "controlNet": "Net of {basis, select, topics {the {prompts} other prompts in its topics} other {the brand's {prompts} other prompts}} over the same days: {list}",+ "netPoints": "{metric} {value} pts",+ "netPercent": "{metric} {value}%","primary": "Judged by {metric}, its main metric.","gaps": "Tracking missed {before, plural, =0 {} one {# night of the week before it} other {# nights of the week before it}}{before, plural, =0 {} other {{after, plural, =0 {} other { and }}}}{after, plural, =0 {} one {# night of the week of the latest reading} other {# nights of the week of the latest reading}}: mentions and citations are counted as for a full week.","gapsTooMany": "Tracking missed {before, plural, =0 {} one {# night of the week before it} other {# nights of the week before it}}{before, plural, =0 {} other {{after, plural, =0 {} other { and }}}}{after, plural, =0 {} one {# night of the week of the latest reading} other {# nights of the week of the latest reading}}: too many to compare mentions and citations fairly, so they are left out of the result.",diff --git a/web/src/components/action-center/history-drawer.test.tsx b/web/src/components/action-center/history-drawer.test.tsxindex 0d1659e0d..239a35d22 100644--- a/web/src/components/action-center/history-drawer.test.tsx+++ b/web/src/components/action-center/history-drawer.test.tsx@@ -183,6 +183,53 @@ describe('HistoryDrawer', () => {expect(result).toMatch(/Brand-wide over the same days: \S.* 100 → 104/);});+ /** Its change net of the brand's prompts it didn't touch (learning B2). */+ it("says the result net of the brand's other prompts over the same days", async () => {+ getActionSignals.mockResolvedValue([]);+ render(+ <HistoryDrawer+ brandId="b1"+ item={{+ ...item,+ controlNet: {+ basis: 'topics',+ prompts: 6,+ net: [+ { metric: 'ai_visibility', net: 6, unit: 'points' },+ { metric: 'mentions', net: -12.5, unit: 'percent' },+ { metric: 'unknown_metric', net: 1, unit: 'points' },+ ],+ },+ }}+ onOpenChange={() => {}}+ />,+ );+ await act(async () => {});+ expect(under('Result')).toMatch(+ /Net of the 6 other prompts in its topics over the same days: \S.* \+6 pts · \S.* −12\.5%$/,+ );+ });++ it('leaves the net line out when it names no metric it can show', async () => {+ getActionSignals.mockResolvedValue([]);+ render(+ <HistoryDrawer+ brandId="b1"+ item={{+ ...item,+ controlNet: {+ basis: 'brand',+ prompts: 8,+ net: [{ metric: 'unknown_metric', net: 1, unit: 'points' }],+ },+ }}+ onOpenChange={() => {}}+ />,+ );+ await act(async () => {});+ expect(under('Result')).not.toContain('Net of');+ });+it('says how a Site Audit fix’s pages read when audited again, or that none was yet (learning A2)', async () => {getActionSignals.mockResolvedValue([]);render(diff --git a/web/src/components/action-center/history-drawer.tsx b/web/src/components/action-center/history-drawer.tsxindex dc9445680..df66ae46e 100644--- a/web/src/components/action-center/history-drawer.tsx+++ b/web/src/components/action-center/history-drawer.tsx@@ -137,6 +137,8 @@ export function HistoryDrawer({);const date = item.completedAt ?? item.createdAt;const measured = item.results.length > 0;+ // Its net of the brand's prompts it didn't touch (learning B2), in the metrics it can name.+ const controlNet = item.controlNet?.net.filter((m) => tRegistry.has(`${m.metric}.name`)) ?? [];const completedTasks = item.tasks.filter((task) => task.status === 'completed').length;const countedTasks = item.tasks.filter((task) => !UNCOUNTED_TASK_STATUSES.includes(task.status),@@ -303,6 +305,23 @@ export function HistoryDrawer({})}</p>)}+ {item.controlNet && controlNet.length > 0 && (+ // Net of the brand's prompts it didn't touch (learning B2).+ <p className="mt-1 text-xs text-muted-foreground">+ {t('drawer.controlNet', {+ basis: item.controlNet.basis,+ prompts: item.controlNet.prompts,+ list: controlNet+ .map((m) =>+ t(m.unit === 'points' ? 'drawer.netPoints' : 'drawer.netPercent', {+ metric: tRegistry(`${m.metric}.name`),+ value: `${m.net > 0 ? '+' : m.net < 0 ? '−' : ''}${Math.abs(m.net)}`,+ }),+ )+ .join(' · '),+ })}+ </p>+ )}</section><Separator />diff --git a/web/src/lib/action-center/history.ts b/web/src/lib/action-center/history.tsindex effcdae9d..1933d5aa1 100644--- a/web/src/lib/action-center/history.ts+++ b/web/src/lib/action-center/history.ts@@ -90,6 +90,13 @@ export interface OutcomeReading {outcome: ActionOutcome;}+/** An action's change net of a control basket's (learning B2). */+export interface ControlNet {+ basis: 'topics' | 'brand';+ prompts: number;+ net: { metric: string; net: number; unit: 'points' | 'percent' }[];+}+/** A signal that opened the action. Several signals consolidate into one* action, so this is a list rather than a field. */export interface TriggerSignal {@@ -158,6 +165,12 @@ export interface ActionHistoryItem {/** A Site Audit fix's pages audited again since it closed, and how many pass (learning A2). */auditAfter?: { pages: number; audited: number; passed: number } | null;brandWideResults?: ActionResultMetric[];+ /**+ * Its change net of the brand's prompts it didn't touch over the same+ * days (learning B2): a rate in points, a count in percent. `basis` says+ * whether they share its topics or are the brand's others.+ */+ controlNet?: ControlNet | null;/** Improve actions only: positions per platform against the baseline (PROMPT-008). */positionOutcome: ImproveOutcome | null;tasks: ActionHistoryTask[];diff --git a/web/src/lib/actions/action-history.ts b/web/src/lib/actions/action-history.tsindex e22307d0e..9b57b886c 100644--- a/web/src/lib/actions/action-history.ts+++ b/web/src/lib/actions/action-history.ts@@ -38,6 +38,7 @@ import {type OutcomeReading,type SignalOutcome,type TriggerSignal,+ type ControlNet,} from '@/lib/action-center/history';interface HistoryRow {@@ -91,6 +92,32 @@ interface ValidationSnapshot {/** Its readings, and whether the final one is in (learning B1). */readings?: { day?: number; outcome?: string }[];final?: boolean;+ /** Its change net of the brand's prompts it didn't touch (learning B2). */+ control?: {+ basis?: string;+ prompts?: number;+ net?: { metric?: string; net?: number; unit?: string }[];+ };+}++/** Its change net of the control basket, the metrics it can name. */+function controlFrom(validation: ValidationSnapshot | null): ControlNet | null {+ const control = validation?.control;+ if (!control || !Array.isArray(control.net)) return null;+ const net = control.net.flatMap((m) =>+ typeof m?.metric === 'string' &&+ typeof m.net === 'number' &&+ Number.isFinite(m.net) &&+ (m.unit === 'points' || m.unit === 'percent')+ ? [{ metric: m.metric, net: m.net, unit: m.unit as 'points' | 'percent' }]+ : [],+ );+ if (!net.length || !Number.isInteger(control.prompts)) return null;+ return {+ basis: control.basis === 'topics' ? 'topics' : 'brand',+ prompts: control.prompts as number,+ net,+ };}/** Its readings, the days known and verdicts it can name, in order. */@@ -365,6 +392,7 @@ export async function getActionHistory(brandWideResults: resultsFrom(row.validation?.brandWide ? { ...row.validation, metrics: row.validation.brandWide } : null,),+ controlNet: controlFrom(row.validation),tasks: tasksByAction.get(row.id) ?? [],assignee: row.assignee_id ? (profiles.get(row.assignee_id) ?? null) : null,dueDate: row.due_date ?? null,