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(action-center): measure whether a closed action helped (#820)

Gökhan Geyikeb6559619775
diff --git a/server/src/lib/action-center/validate.js b/server/src/lib/action-center/validate.js
new file mode 100644
index 000000000..28e370b41
--- /dev/null
+++ b/server/src/lib/action-center/validate.js
@@ -0,0 +1,313 @@
+/**
+ * Did the action help? (Action Center, validation layer — #818 phase 2.)
+ *
+ * An action closes when someone finishes the work. Whether the work moved
+ * anything is a separate question, and until this module existed nothing
+ * asked it: `outcome` read `pending_measurement` forever and History's Result
+ * column had nothing to show.
+ *
+ * The answer comes from measuring the action's own success metrics twice —
+ * over a window ending before it was raised, and a window after it closed —
+ * and comparing. Both reads go through the same daily rollup functions the
+ * KPI page uses, so an action's result and the dashboard that summarises the
+ * same days cannot disagree.
+ *
+ * What it deliberately does not do:
+ * - claim causality. The metrics moved; whether this action moved them is
+ * not knowable from a before/after pair, and the UI says "measured after
+ * this action closed" rather than "because of it";
+ * - infer an outcome from task completion. Ticking six boxes is evidence of
+ * effort, not of effect;
+ * - measure what it cannot read. A metric with no data in either window is
+ * reported as unmeasured rather than as zero, because zero is a number
+ * someone will believe.
+ */
+
+import supabaseAdmin from '../../config/supabase.js';
+import { computeAiVisibilityScore } from '../../config/visibility-score.js';
+import { logger } from '../logger.js';
+
+const DAY_MS = 86_400_000;
+
+/** Length of each measurement window. Equal on both sides so the comparison
+ * is between like periods. */
+export const MEASUREMENT_WINDOW_DAYS = 7;
+
+/**
+ * How long after closing before an action can be measured.
+ *
+ * The "after" window runs for MEASUREMENT_WINDOW_DAYS from the day following
+ * the close, and it has to be *over* before it means anything: a window still
+ * in progress reads low simply because its later days have not happened, and
+ * reporting that as a decline would turn every recent action into a failure.
+ * The sweep uses this to filter cheaply; validateAction checks the window
+ * itself, which is the condition that actually matters.
+ */
+export const VALIDATION_WAIT_DAYS = MEASUREMENT_WINDOW_DAYS + 1;
+
+/**
+ * How much a metric must move to count as movement, as a fraction of its
+ * before value. Below this, a difference is indistinguishable from the
+ * week-to-week noise every one of these metrics carries.
+ *
+ * Centralised with the rest of the engine's thresholds in phase 2.5 (#818).
+ */
+export const MEANINGFUL_CHANGE_RATIO = 0.05;
+
+/** Every metric here reads higher-is-better; a drop is a decline. */
+const MEASURABLE_KPIS = {
+ ai_visibility: 'percent',
+ citations: 'count',
+ mentions: 'count',
+ share_of_voice: 'percent',
+ ai_referral_traffic: 'sessions',
+};
+
+const utcDay = (date) => date.toISOString().slice(0, 10);
+
+/** Inclusive whole-day window of `days` ending the day before `endExclusive`. */
+function windowEndingBefore(endExclusive, days) {
+ const to = new Date(endExclusive.getTime() - DAY_MS);
+ const from = new Date(to.getTime() - (days - 1) * DAY_MS);
+ return { from: utcDay(from), to: utcDay(to) };
+}
+
+/** Inclusive whole-day window of `days` starting the day after `startExclusive`. */
+function windowStartingAfter(startExclusive, days) {
+ const from = new Date(startExclusive.getTime() + DAY_MS);
+ const to = new Date(from.getTime() + (days - 1) * DAY_MS);
+ return { from: utcDay(from), to: utcDay(to) };
+}
+
+async function rpc(name, brandId, from, to) {
+ const { data, error } = await supabaseAdmin.rpc(name, {
+ p_brand_id: brandId,
+ p_platform: null,
+ p_models: null,
+ p_region: null,
+ p_day_from: from,
+ p_day_to: to,
+ });
+ if (error) throw new Error(`${name}: ${error.message}`);
+ // These functions return a single row; supabase-js hands back the object or
+ // a one-element array depending on the declared return type.
+ return Array.isArray(data) ? (data[0] ?? null) : data;
+}
+
+/**
+ * Read the requested metrics over one window.
+ *
+ * Returns null for a metric the window cannot answer — no tracking ran, or
+ * the brand has no analytics connected — which the caller reports as
+ * unmeasured rather than as a value.
+ */
+export async function measureKpis(brandId, kpiKeys, from, to) {
+ const wanted = kpiKeys.filter((key) => key in MEASURABLE_KPIS);
+ if (wanted.length === 0) return {};
+
+ const needsInsights = wanted.some((k) => k === 'citations' || k === 'mentions');
+ const needsVisibility = wanted.includes('ai_visibility');
+ const needsSov = wanted.includes('share_of_voice');
+ const needsTraffic = wanted.includes('ai_referral_traffic');
+
+ const [insights, visibility, sov, traffic] = await Promise.all([
+ needsInsights ? rpc('insights_aggregates_daily', brandId, from, to) : null,
+ needsVisibility ? rpc('ai_visibility_aggregates_daily', brandId, from, to) : null,
+ needsSov ? rpc('share_of_voice_aggregates_daily', brandId, from, to) : null,
+ needsTraffic ? measureTraffic(brandId, from, to) : null,
+ ]);
+
+ const values = {};
+ for (const key of wanted) {
+ switch (key) {
+ case 'citations':
+ values[key] = insights?.total_citations ?? null;
+ break;
+ case 'mentions':
+ values[key] = insights?.total_mentions ?? null;
+ break;
+ case 'ai_visibility':
+ values[key] = visibility?.answers
+ ? computeAiVisibilityScore({
+ answers: Number(visibility.answers),
+ mentionAnswers: Number(visibility.mention_answers ?? 0),
+ citationAnswers: Number(visibility.citation_answers ?? 0),
+ positionFactor: visibility.position_factor ?? 0,
+ })
+ : null;
+ break;
+ case 'share_of_voice': {
+ // The function returns the two mention totals; the percentage is
+ // computed the same way the Insights page computes it, so the two
+ // agree for the same days.
+ const brand = Number(sov?.total_brand_mentions ?? 0);
+ const competitors = Number(sov?.total_competitor_mentions ?? 0);
+ const all = brand + competitors;
+ values[key] = all > 0 ? Math.round((brand / all) * 1000) / 10 : null;
+ break;
+ }
+ case 'ai_referral_traffic':
+ values[key] = traffic;
+ break;
+ }
+ }
+ return values;
+}
+
+/**
+ * AI-referred visits over a window.
+ *
+ * Two sources exist and they measure different things: the tracking snippet
+ * logs each referred visit, while the analytics integration reports sessions.
+ * Whichever the brand actually has is used — and when it has neither, the
+ * metric is unmeasured, not zero.
+ */
+async function measureTraffic(brandId, from, to) {
+ const { count, error } = await supabaseAdmin
+ .from('ai_traffic_logs')
+ .select('id', { count: 'exact', head: true })
+ .eq('brand_id', brandId)
+ .gte('created_at', `${from}T00:00:00Z`)
+ .lte('created_at', `${to}T23:59:59Z`);
+ if (error) throw new Error(`ai_traffic_logs: ${error.message}`);
+ if (count) return count;
+
+ const { data, error: gaErr } = await supabaseAdmin
+ .from('ga_ai_traffic_stats')
+ .select('sessions')
+ .eq('brand_id', brandId)
+ .gte('date', from)
+ .lte('date', to);
+ if (gaErr) throw new Error(`ga_ai_traffic_stats: ${gaErr.message}`);
+ if (!data?.length) return null;
+ return data.reduce((sum, row) => sum + Number(row.sessions ?? 0), 0);
+}
+
+/**
+ * The verdict, from the measured pairs alone.
+ *
+ * A metric counts as moved only past MEANINGFUL_CHANGE_RATIO — these numbers
+ * drift week to week on their own, and calling a 1% wobble an improvement
+ * would make every outcome meaningless. Mixed movement reads as improved:
+ * something the action aimed at did move, and reporting that as "no change"
+ * would hide it.
+ */
+export function deriveOutcome(metrics) {
+ const measured = metrics.filter((m) => m.before != null && m.after != null);
+ if (measured.length === 0) return 'not_measurable';
+
+ let improved = 0;
+ let declined = 0;
+ for (const { before, after } of measured) {
+ const floor = Math.abs(before) * MEANINGFUL_CHANGE_RATIO;
+ // A metric that was zero before has no ratio to scale by; any real
+ // arrival counts as movement.
+ const threshold = before === 0 ? Number.EPSILON : floor;
+ if (after - before > threshold) improved += 1;
+ else if (before - after > threshold) declined += 1;
+ }
+
+ if (improved > 0) return 'improved';
+ if (declined > 0) return 'declined';
+ return 'no_meaningful_change';
+}
+
+/**
+ * Measure one closed action and record the result.
+ *
+ * Returns the outcome written, or null when the action is not ready — it
+ * closed too recently, or its "after" window has not finished yet.
+ */
+export async function validateAction(action, { now = new Date() } = {}) {
+ const closedAt = Date.parse(action.completed_at ?? '') || 0;
+ if (!closedAt) return null;
+
+ const beforeWindow = windowEndingBefore(new Date(action.created_at), MEASUREMENT_WINDOW_DAYS);
+ const afterWindow = windowStartingAfter(new Date(closedAt), MEASUREMENT_WINDOW_DAYS);
+
+ // The window has to be complete. Measuring a window whose last days have
+ // not happened yet reads low for a reason that has nothing to do with the
+ // action, and would file most recent work as a decline.
+ if (afterWindow.to >= utcDay(now)) return null;
+
+ const kpiKeys = (action.kpi_keys ?? []).filter((key) => key in MEASURABLE_KPIS);
+
+ // An action with no success metrics has nothing to measure. That is a gap
+ // in the rule that produced it, not a failure here — say so plainly rather
+ // than inventing a metric it never claimed.
+ if (kpiKeys.length === 0) {
+ await write(action.id, null, 'not_measurable', now);
+ return 'not_measurable';
+ }
+
+ const [before, after] = await Promise.all([
+ measureKpis(action.brand_id, kpiKeys, beforeWindow.from, beforeWindow.to),
+ measureKpis(action.brand_id, kpiKeys, afterWindow.from, afterWindow.to),
+ ]);
+
+ const metrics = kpiKeys.map((metric) => ({
+ metric,
+ unit: MEASURABLE_KPIS[metric],
+ before: before[metric] ?? null,
+ after: after[metric] ?? null,
+ }));
+
+ const outcome = deriveOutcome(metrics);
+ await write(
+ action.id,
+ { measuredAt: now.toISOString(), beforeWindow, afterWindow, metrics },
+ outcome,
+ now,
+ );
+ return outcome;
+}
+
+async function write(actionId, validation, outcome, now) {
+ const { error } = await supabaseAdmin
+ .from('actions')
+ .update({ validation, outcome, validated_at: now.toISOString() })
+ .eq('id', actionId);
+ if (error) throw new Error(error.message);
+
+ // The trail carries the verdict, so the drawer's History tab shows when the
+ // measurement happened alongside the work that preceded it.
+ await supabaseAdmin
+ .from('action_events')
+ .insert({ action_id: actionId, event: 'outcome_measured', data: { outcome } });
+}
+
+/**
+ * Nightly sweep: measure every closed action whose settling period has passed.
+ *
+ * Best-effort per action — one brand's missing rollup must not stop the rest
+ * from being measured.
+ */
+export async function sweepActionValidation({ now = new Date() } = {}) {
+ const cutoff = new Date(now.getTime() - VALIDATION_WAIT_DAYS * DAY_MS).toISOString();
+ const { data, error } = await supabaseAdmin
+ .from('actions')
+ .select('id, brand_id, kpi_keys, created_at, completed_at')
+ .eq('status', 'completed')
+ .eq('outcome', 'pending_measurement')
+ .not('completed_at', 'is', null)
+ .lte('completed_at', cutoff)
+ .limit(500);
+ if (error) {
+ logger.error({ err: error }, '[action-validation] could not list pending actions');
+ return { measured: 0, failed: 0 };
+ }
+
+ let measured = 0;
+ let failed = 0;
+ for (const action of data ?? []) {
+ try {
+ if (await validateAction(action, { now })) measured += 1;
+ } catch (err) {
+ failed += 1;
+ logger.error({ err, actionId: action.id }, '[action-validation] measurement failed');
+ }
+ }
+
+ logger.info({ measured, failed }, '[action-validation] sweep complete');
+ return { measured, failed };
+}
diff --git a/server/src/lib/action-center/validate.test.js b/server/src/lib/action-center/validate.test.js
new file mode 100644
index 000000000..5a491c9ac
--- /dev/null
+++ b/server/src/lib/action-center/validate.test.js
@@ -0,0 +1,231 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const rpc = vi.fn();
+const from = vi.fn();
+vi.mock('../../config/supabase.js', () => ({
+ default: { rpc: (...a) => rpc(...a), from: (...a) => from(...a) },
+}));
+vi.mock('../logger.js', () => ({
+ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+
+import {
+ MEANINGFUL_CHANGE_RATIO,
+ VALIDATION_WAIT_DAYS,
+ deriveOutcome,
+ measureKpis,
+ validateAction,
+} from './validate.js';
+
+const NOW = new Date('2026-09-20T04:00:00Z');
+const daysAgo = (n) => new Date(NOW.getTime() - n * 86_400_000).toISOString();
+
+/** Records every write so a test can assert what was stored. */
+function mockWrites() {
+ const writes = { updated: [], inserted: [] };
+ from.mockImplementation((table) => {
+ const builder = {
+ select: () => builder,
+ eq: () => builder,
+ gte: () => builder,
+ lte: () => builder,
+ not: () => builder,
+ limit: () => builder,
+ update: (patch) => {
+ writes.updated.push({ table, patch });
+ return builder;
+ },
+ insert: (rows) => {
+ writes.inserted.push({ table, rows });
+ return builder;
+ },
+ then: (resolve, reject) =>
+ Promise.resolve({ data: [], error: null, count: 0 }).then(resolve, reject),
+ };
+ return builder;
+ });
+ return writes;
+}
+
+beforeEach(() => {
+ rpc.mockReset();
+ from.mockReset();
+ vi.useFakeTimers();
+ vi.setSystemTime(NOW);
+});
+
+afterEach(() => {
+ vi.useRealTimers();
+});
+
+describe('deriveOutcome', () => {
+ const pair = (metric, before, after) => ({ metric, unit: 'count', before, after });
+
+ it('reports nothing measurable when no metric has both halves', () => {
+ expect(deriveOutcome([pair('citations', null, 40)])).toBe('not_measurable');
+ expect(deriveOutcome([])).toBe('not_measurable');
+ });
+
+ it('calls a rise past the threshold an improvement', () => {
+ expect(deriveOutcome([pair('citations', 100, 120)])).toBe('improved');
+ });
+
+ it('calls a fall past the threshold a decline', () => {
+ expect(deriveOutcome([pair('citations', 100, 80)])).toBe('declined');
+ });
+
+ /**
+ * The guard that keeps every outcome from being a verdict. These metrics
+ * drift on their own; a move inside the noise band is not a result.
+ */
+ it('ignores movement inside the noise band', () => {
+ const wobble = Math.round(100 * MEANINGFUL_CHANGE_RATIO) - 1;
+ expect(deriveOutcome([pair('citations', 100, 100 + wobble)])).toBe('no_meaningful_change');
+ expect(deriveOutcome([pair('citations', 100, 100 - wobble)])).toBe('no_meaningful_change');
+ });
+
+ it('reports an improvement when one metric rose and another fell', () => {
+ expect(deriveOutcome([pair('citations', 100, 150), pair('mentions', 100, 50)])).toBe(
+ 'improved',
+ );
+ });
+
+ // Nothing to scale a ratio by, so any real arrival counts.
+ it('treats a first arrival from zero as movement', () => {
+ expect(deriveOutcome([pair('citations', 0, 3)])).toBe('improved');
+ });
+});
+
+describe('measureKpis', () => {
+ it('asks only for the sources the requested metrics need', async () => {
+ rpc.mockResolvedValue({ data: { total_citations: 42, total_mentions: 7 }, error: null });
+
+ const values = await measureKpis('brand-1', ['citations'], '2026-09-01', '2026-09-07');
+
+ expect(rpc).toHaveBeenCalledTimes(1);
+ expect(rpc).toHaveBeenCalledWith('insights_aggregates_daily', {
+ p_brand_id: 'brand-1',
+ p_platform: null,
+ p_models: null,
+ p_region: null,
+ p_day_from: '2026-09-01',
+ p_day_to: '2026-09-07',
+ });
+ expect(values).toEqual({ citations: 42 });
+ });
+
+ it('ignores metrics it has no source for', async () => {
+ const values = await measureKpis('brand-1', ['something_else'], '2026-09-01', '2026-09-07');
+ expect(values).toEqual({});
+ expect(rpc).not.toHaveBeenCalled();
+ });
+
+ it('computes share of voice the way the dashboard does', async () => {
+ rpc.mockResolvedValue({
+ data: { total_brand_mentions: 250, total_competitor_mentions: 750 },
+ error: null,
+ });
+
+ const values = await measureKpis('brand-1', ['share_of_voice'], '2026-09-01', '2026-09-07');
+
+ expect(values.share_of_voice).toBe(25);
+ });
+
+ it('reports a window with no answers as unmeasured, not zero', async () => {
+ rpc.mockResolvedValue({ data: { answers: 0 }, error: null });
+
+ const values = await measureKpis('brand-1', ['ai_visibility'], '2026-09-01', '2026-09-07');
+
+ expect(values.ai_visibility).toBeNull();
+ });
+});
+
+describe('validateAction', () => {
+ const action = (over = {}) => ({
+ id: 'a1',
+ brand_id: 'brand-1',
+ kpi_keys: ['citations'],
+ created_at: daysAgo(30),
+ completed_at: daysAgo(10),
+ ...over,
+ });
+
+ /**
+ * The window has to be over. Measured early, its unhappened days read as
+ * zero and file recent work as a decline.
+ */
+ it('refuses to measure while the after window is still running', async () => {
+ const writes = mockWrites();
+
+ const outcome = await validateAction(action({ completed_at: daysAgo(3) }), { now: NOW });
+
+ expect(outcome).toBeNull();
+ expect(writes.updated).toHaveLength(0);
+ expect(rpc).not.toHaveBeenCalled();
+ });
+
+ it('measures once the window has closed', async () => {
+ mockWrites();
+ rpc.mockResolvedValue({ data: { total_citations: 10 }, error: null });
+
+ const outcome = await validateAction(action({ completed_at: daysAgo(VALIDATION_WAIT_DAYS) }), {
+ now: NOW,
+ });
+
+ expect(outcome).not.toBeNull();
+ });
+
+ it('measures before and after over equal windows and stores both', async () => {
+ const writes = mockWrites();
+ rpc
+ .mockResolvedValueOnce({ data: { total_citations: 100 }, error: null })
+ .mockResolvedValueOnce({ data: { total_citations: 140 }, error: null });
+
+ const outcome = await validateAction(action(), { now: NOW });
+
+ expect(outcome).toBe('improved');
+ const patch = writes.updated.find((w) => w.table === 'actions').patch;
+ expect(patch.outcome).toBe('improved');
+ expect(patch.validated_at).toBe(NOW.toISOString());
+ expect(patch.validation.metrics).toEqual([
+ { metric: 'citations', unit: 'count', before: 100, after: 140 },
+ ]);
+ // Equal-length windows, one before the action was raised and one after it
+ // closed — a comparison between like periods.
+ expect(patch.validation.beforeWindow.to < patch.validation.afterWindow.from).toBe(true);
+ });
+
+ it('records the verdict on the action trail', async () => {
+ const writes = mockWrites();
+ rpc.mockResolvedValue({ data: { total_citations: 10 }, error: null });
+
+ await validateAction(action(), { now: NOW });
+
+ const event = writes.inserted.find((w) => w.table === 'action_events');
+ expect(event.rows.event).toBe('outcome_measured');
+ });
+
+ /**
+ * An action whose rule never named a success metric cannot be judged. Saying
+ * so is honest; inventing a metric it never claimed would not be.
+ */
+ it('reports an action with no success metrics as not measurable', async () => {
+ const writes = mockWrites();
+
+ const outcome = await validateAction(action({ kpi_keys: [] }), { now: NOW });
+
+ expect(outcome).toBe('not_measurable');
+ expect(rpc).not.toHaveBeenCalled();
+ const patch = writes.updated.find((w) => w.table === 'actions').patch;
+ expect(patch.validation).toBeNull();
+ });
+
+ it('does nothing for an action that never closed', async () => {
+ const writes = mockWrites();
+
+ const outcome = await validateAction(action({ completed_at: null }), { now: NOW });
+
+ expect(outcome).toBeNull();
+ expect(writes.updated).toHaveLength(0);
+ });
+});
diff --git a/server/src/server.js b/server/src/server.js
index 2db238dee..c1ea46bba 100644
--- a/server/src/server.js
+++ b/server/src/server.js
@@ -21,6 +21,7 @@ import {
} from './lib/job-manager.js';
import { runTrackingJob } from './lib/job-runner.js';
import { sweepInsightsRollups } from './lib/insights-rollups.js';
+import { sweepActionValidation } from './lib/action-center/validate.js';
import { parseScraperResponse } from './lib/cloro-scraper.js';
import { handleScraperResult } from './lib/cloro-result-handler.js';
import { verifyCloroWebhook } from './lib/cloro-webhook-verify.js';
@@ -132,6 +133,14 @@ async function runDailyTracking() {
logger.error({ err }, '[insights-rollups] daily sweep crashed');
});
+ // Measure what closed actions actually moved (#818 phase 2). Runs after the
+ // rollups above are refreshed, since it reads them — but fire-and-forget
+ // like the rest: an unmeasured action is a gap in History, not a reason to
+ // hold up tonight's tracking.
+ sweepActionValidation().catch((err) => {
+ logger.error({ err }, '[action-validation] daily sweep crashed');
+ });
+
// Skip paused brands (is_active = false): the user has explicitly suspended
// tracking for them, so they should not spend Cloro / LLM credits daily.
const { data: brands, error } = await supabaseAdmin
diff --git a/supabase/migrations/00085_action_validation.sql b/supabase/migrations/00085_action_validation.sql
new file mode 100644
index 000000000..8d57f1740
--- /dev/null
+++ b/supabase/migrations/00085_action_validation.sql
@@ -0,0 +1,42 @@
+-- Action Engine, phase 2 (#818): measure whether a closed action helped.
+--
+-- 00084 split `outcome` from `status` and left every row reading
+-- `pending_measurement`, because nothing re-read an action's metrics after it
+-- closed. `baseline` recorded the "before" — the triggering signals' values at
+-- the moment the action was raised — but there was no "after" to compare it
+-- to, so History's Result column could only say that nothing had been
+-- measured.
+--
+-- This is where the "after" goes. A nightly sweep waits out a settling period
+-- after a cycle closes, measures the action's own success metrics over a
+-- window before it was raised and a window after it closed, and writes both
+-- halves here. Outcome is then derived from the comparison rather than from
+-- whether the tasks got ticked — completing the work and the work helping are
+-- different claims, and only the second one needs evidence.
+--
+-- The measurement reads the same daily rollups the KPI page reads, so an
+-- action's result and the dashboard it summarises cannot disagree.
+
+alter table public.actions
+ add column if not exists validation jsonb;
+
+comment on column public.actions.validation is
+ $$Measured effect of a closed action. Null until the sweep runs. Shape:
+{ "measuredAt": iso,
+ "beforeWindow": { "from": date, "to": date },
+ "afterWindow": { "from": date, "to": date },
+ "metrics": [ { "metric": kpi_key, "unit": text, "before": num|null, "after": num|null } ] }
+Deltas are derived at read time rather than stored, so a stored delta can
+never contradict the two values it came from.$$;
+
+alter table public.actions
+ add column if not exists validated_at timestamptz;
+
+comment on column public.actions.validated_at is
+ 'When the effect was measured. Null while outcome is pending_measurement.';
+
+-- The sweep looks for closed actions still awaiting measurement. Without this
+-- it scans every action a brand has ever had, every night, forever.
+create index if not exists actions_pending_validation_idx
+ on public.actions (completed_at)
+ where outcome = 'pending_measurement' and status = 'completed';
diff --git a/supabase/schema.sql b/supabase/schema.sql
index c384f6d18..91cf650ac 100644
--- a/supabase/schema.sql
+++ b/supabase/schema.sql
@@ -10374,3 +10374,49 @@ alter table public.action_tasks
'failed'
));
+-- ─────────────────────────────────────────────────────────────────────────
+-- migrations/00085_action_validation.sql
+-- ─────────────────────────────────────────────────────────────────────────
+-- Action Engine, phase 2 (#818): measure whether a closed action helped.
+--
+-- 00084 split `outcome` from `status` and left every row reading
+-- `pending_measurement`, because nothing re-read an action's metrics after it
+-- closed. `baseline` recorded the "before" — the triggering signals' values at
+-- the moment the action was raised — but there was no "after" to compare it
+-- to, so History's Result column could only say that nothing had been
+-- measured.
+--
+-- This is where the "after" goes. A nightly sweep waits out a settling period
+-- after a cycle closes, measures the action's own success metrics over a
+-- window before it was raised and a window after it closed, and writes both
+-- halves here. Outcome is then derived from the comparison rather than from
+-- whether the tasks got ticked — completing the work and the work helping are
+-- different claims, and only the second one needs evidence.
+--
+-- The measurement reads the same daily rollups the KPI page reads, so an
+-- action's result and the dashboard it summarises cannot disagree.
+
+alter table public.actions
+ add column if not exists validation jsonb;
+
+comment on column public.actions.validation is
+ $$Measured effect of a closed action. Null until the sweep runs. Shape:
+{ "measuredAt": iso,
+ "beforeWindow": { "from": date, "to": date },
+ "afterWindow": { "from": date, "to": date },
+ "metrics": [ { "metric": kpi_key, "unit": text, "before": num|null, "after": num|null } ] }
+Deltas are derived at read time rather than stored, so a stored delta can
+never contradict the two values it came from.$$;
+
+alter table public.actions
+ add column if not exists validated_at timestamptz;
+
+comment on column public.actions.validated_at is
+ 'When the effect was measured. Null while outcome is pending_measurement.';
+
+-- The sweep looks for closed actions still awaiting measurement. Without this
+-- it scans every action a brand has ever had, every night, forever.
+create index if not exists actions_pending_validation_idx
+ on public.actions (completed_at)
+ where outcome = 'pending_measurement' and status = 'completed';
+
diff --git a/web/src/components/action-center/history-drawer.tsx b/web/src/components/action-center/history-drawer.tsx
index 1ad1a34e2..d3dc1cf1b 100644
--- a/web/src/components/action-center/history-drawer.tsx
+++ b/web/src/components/action-center/history-drawer.tsx
@@ -21,18 +21,45 @@ import { HistoryStatusBadge } from './history-table';
import { cn } from '@/lib/utils';
/**
- * One metric an action moved.
+ * One metric an action moved, as before → after.
*
- * Renders a dash rather than a zero when nothing has measured it: zero is a
- * measurement, and claiming one that was never taken is the failure this whole
- * tab exists to avoid.
+ * Both halves are shown rather than only the delta: a jump of seven means
+ * something different at a base of ten than at a base of a thousand, and the
+ * reader deciding whether the work paid off needs the base.
*/
-function ResultMetricCard({ label, value, sub }: { label: string; value: string; sub: string }) {
+function ResultMetricCard({
+ label,
+ before,
+ after,
+ delta,
+ unit,
+}: {
+ label: string;
+ before: number;
+ after: number;
+ delta: number;
+ unit: string;
+}) {
+ const suffix = unit === 'percent' ? '%' : '';
+ const rose = delta > 0;
return (
<div className="rounded-md border p-3">
<p className="text-[11px] text-muted-foreground">{label}</p>
- <p className="mt-1 text-lg font-semibold tabular-nums">{value}</p>
- <p className="text-[11px] text-muted-foreground">{sub}</p>
+ <p
+ className={cn(
+ 'mt-1 text-lg font-semibold tabular-nums',
+ rose ? 'text-emerald-600 dark:text-emerald-400' : delta < 0 ? 'text-red-500' : '',
+ )}
+ >
+ {rose ? '↑' : delta < 0 ? '↓' : ''}
+ {Math.abs(delta)}
+ {suffix}
+ </p>
+ <p className="text-[11px] tabular-nums text-muted-foreground">
+ {before}
+ {suffix} → {after}
+ {suffix}
+ </p>
</div>
);
}
@@ -56,6 +83,7 @@ export function HistoryDrawer({
const tTasks = useTranslations('actionCenter.actionTasks');
const tTaskStatus = useTranslations('actionCenter.taskStatus');
const tSources = useTranslations('actionCenter.signalsPage.sources');
+ const tRegistry = useTranslations('actionCenter.registry');
const tAffected = useTranslations('actionCenter.historyPage.affected');
const router = useRouter();
@@ -73,13 +101,6 @@ export function HistoryDrawer({
(task) => !UNCOUNTED_TASK_STATUSES.includes(task.status),
).length;
- const metricValue = (metric: string) => {
- const found = item.results.find((r) => r.metric === metric);
- if (!found) return '—';
- const delta = found.delta ?? 0;
- return `${delta > 0 ? '↑' : delta < 0 ? '↓' : ''}${Math.abs(delta)}${found.unit === 'percent' ? '%' : ''}`;
- };
-
return (
<Sheet open={Boolean(item)} onOpenChange={onOpenChange}>
<SheetContent className="flex w-full flex-col gap-0 p-0 sm:max-w-lg">
@@ -146,28 +167,25 @@ export function HistoryDrawer({
</p>
)}
<div className="mt-2 grid grid-cols-2 gap-2">
- <ResultMetricCard
- label={t('drawer.visibilityChange')}
- value={metricValue('visibility')}
- sub={t('drawer.vsBefore')}
- />
- <ResultMetricCard
- label={t('drawer.citationsChange')}
- value={metricValue('citations')}
- sub={t('drawer.netChange')}
- />
- <ResultMetricCard
- label={t('drawer.promptsImproved')}
- value={metricValue('prompts_improved')}
- sub={t('drawer.ofAffected')}
- />
- <ResultMetricCard
- label={t('drawer.timeToClose')}
- value={
- item.timeToCloseDays != null ? t('drawer.days', { n: item.timeToCloseDays }) : '—'
- }
- sub={t('drawer.fromStart')}
- />
+ {item.results.map((metric) => (
+ <ResultMetricCard
+ key={metric.id}
+ label={tRegistry(`${metric.metric}.name`)}
+ before={metric.before ?? 0}
+ after={metric.after ?? 0}
+ delta={metric.delta ?? 0}
+ unit={metric.unit}
+ />
+ ))}
+ <div className="rounded-md border p-3">
+ <p className="text-[11px] text-muted-foreground">{t('drawer.timeToClose')}</p>
+ <p className="mt-1 text-lg font-semibold tabular-nums">
+ {item.timeToCloseDays != null
+ ? t('drawer.days', { n: item.timeToCloseDays })
+ : '—'}
+ </p>
+ <p className="text-[11px] text-muted-foreground">{t('drawer.fromStart')}</p>
+ </div>
</div>
</section>
diff --git a/web/src/components/action-center/history-table.tsx b/web/src/components/action-center/history-table.tsx
index f68e7ef83..afa1f74b9 100644
--- a/web/src/components/action-center/history-table.tsx
+++ b/web/src/components/action-center/history-table.tsx
@@ -55,13 +55,25 @@ export function HistoryStatusBadge({ status }: { status: ActionStatus }) {
function ResultCell({ item }: { item: ActionHistoryItem }) {
const t = useTranslations('actionCenter.historyPage');
const tOutcome = useTranslations('actionCenter.actionOutcome');
+ const tRegistry = useTranslations('actionCenter.registry');
if (item.results.length > 0) {
return (
<div className="space-y-0.5">
{item.results.slice(0, 2).map((metric) => (
- <p key={metric.id} className="text-xs tabular-nums">
- {(metric.delta ?? 0) > 0 ? '↑' : '↓'} {Math.abs(metric.delta ?? 0)} {metric.label}
+ <p
+ key={metric.id}
+ className={cn(
+ 'text-xs tabular-nums',
+ (metric.delta ?? 0) > 0
+ ? 'text-emerald-600 dark:text-emerald-400'
+ : (metric.delta ?? 0) < 0
+ ? 'text-red-500'
+ : '',
+ )}
+ >
+ {(metric.delta ?? 0) > 0 ? '↑' : '↓'} {Math.abs(metric.delta ?? 0)}
+ {metric.unit === 'percent' ? '%' : ''} {tRegistry(`${metric.metric}.name`)}
</p>
))}
</div>
diff --git a/web/src/lib/actions/action-history.ts b/web/src/lib/actions/action-history.ts
index 6a3a456d3..3e0b87493 100644
--- a/web/src/lib/actions/action-history.ts
+++ b/web/src/lib/actions/action-history.ts
@@ -7,9 +7,11 @@
* tab makes a single round trip for a page of rows and the shapes it renders
* are settled before they reach React.
*
- * Everything returned is read from rows the product already writes. The one
- * field that is deliberately empty is `results` — see lib/action-center/history
- * for why, and for the shape a validation pass would fill.
+ * Everything returned is read from rows the product already writes, including
+ * `results`: the nightly validation sweep measures a closed action's success
+ * metrics before it was raised and after it closed, and this maps that
+ * measurement into the shape the table and drawer render. An action that has
+ * not been measured yet carries no results and says so.
*/
import { createClient } from '@/lib/supabase/server';
@@ -34,6 +36,7 @@ interface HistoryRow {
impact: string;
status: string;
outcome: string;
+ validation: ValidationSnapshot | null;
payload: Record<string, unknown>;
kpi_keys: string[];
assignee_id: string | null;
@@ -43,7 +46,53 @@ interface HistoryRow {
}
const HISTORY_COLUMNS =
- 'id, action_no, category, kind, impact, status, outcome, payload, kpi_keys, assignee_id, created_at, completed_at, updated_at';
+ 'id, action_no, category, kind, impact, status, outcome, validation, payload, kpi_keys, assignee_id, created_at, completed_at, updated_at';
+
+/** What the validation sweep stores on an action. */
+interface ValidationSnapshot {
+ measuredAt: string;
+ beforeWindow: { from: string; to: string };
+ afterWindow: { from: string; to: string };
+ metrics: {
+ metric: string;
+ unit: string;
+ before: number | null;
+ after: number | null;
+ }[];
+}
+
+/**
+ * The measured pairs, as metrics the UI can render.
+ *
+ * Deltas are computed here rather than read from storage, so a displayed
+ * change can never contradict the two values it came from. A metric missing
+ * either half is dropped: it was not measured, and a half-measurement shown
+ * as a number is worse than an honest absence.
+ */
+function resultsFrom(validation: ValidationSnapshot | null): ActionResultMetric[] {
+ if (!validation?.metrics) return [];
+ return validation.metrics
+ .filter((m) => m.before != null && m.after != null)
+ .map((m) => {
+ const before = m.before as number;
+ const after = m.after as number;
+ return {
+ id: m.metric,
+ label: m.metric,
+ metric: m.metric as ActionResultMetric['metric'],
+ before,
+ after,
+ delta: Math.round((after - before) * 10) / 10,
+ // A before of zero has no ratio; the absolute delta carries it.
+ ...(before === 0
+ ? {}
+ : { deltaPercent: Math.round(((after - before) / before) * 1000) / 10 }),
+ unit: m.unit as ActionResultMetric['unit'],
+ // Every metric the sweep measures reads higher-is-better.
+ direction: 'higher_is_better',
+ } satisfies ActionResultMetric;
+ });
+}
function num(payload: Record<string, unknown>, key: string): number {
const value = payload[key];
@@ -186,9 +235,7 @@ export async function getActionHistory(
return rows.map((row) => {
const triggerSignals = signalsByAction.get(row.id) ?? [];
- // Empty until something measures an action's effect — see
- // lib/action-center/history for why, and for the shape it would fill.
- const results: ActionResultMetric[] = [];
+ const results = resultsFrom(row.validation);
return {
id: row.id,
actionNo: Number(row.action_no),
diff --git a/web/src/types/supabase.ts b/web/src/types/supabase.ts
index b08fb0fe5..f1a189801 100644
--- a/web/src/types/supabase.ts
+++ b/web/src/types/supabase.ts
@@ -119,6 +119,8 @@ export type Database = {
payload: Json
status: string
updated_at: string
+ validated_at: string | null
+ validation: Json | null
}
Insert: {
action_no?: never
@@ -138,6 +140,8 @@ export type Database = {
payload?: Json
status?: string
updated_at?: string
+ validated_at?: string | null
+ validation?: Json | null
}
Update: {
action_no?: never
@@ -157,6 +161,8 @@ export type Database = {
payload?: Json
status?: string
updated_at?: string
+ validated_at?: string | null
+ validation?: Json | null
}
Relationships: [
{