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(signals): keep a signal open while its finding is still detected (#843)

Gökhan Geyikeec7764b41de
diff --git a/server/src/lib/signals/library/detect.js b/server/src/lib/signals/library/detect.js
index 68e28d97c..44218f5f0 100644
--- a/server/src/lib/signals/library/detect.js
+++ b/server/src/lib/signals/library/detect.js
@@ -98,13 +98,25 @@ function single(kind, key, entity, target, source, values = {}, extra = {}) {
};
}
-/** Keeps a kind's signals to the configured maximum, strongest first. */
-function cap(candidates, score) {
+/**
+ * Keeps a kind's signals to the configured maximum, strongest first.
+ *
+ * The rest are marked, not dropped: they were still detected, and the pass
+ * needs to know that. A finding that slips from fifth to sixth has not ended,
+ * and closing it would tell the user a problem was solved when it only moved
+ * down a list.
+ */
+export function cap(candidates, score) {
const byKind = new Map();
for (const candidate of candidates) {
byKind.set(candidate.kind, [...(byKind.get(candidate.kind) ?? []), candidate]);
}
- return [...byKind.values()].flatMap((list) => c.strongest(list, score, t.maxSignalsPerKind));
+ return [...byKind.values()].flatMap((list) => {
+ const kept = new Set(c.strongest(list, score, t.maxSignalsPerKind));
+ return list.map((candidate) =>
+ kept.has(candidate) ? candidate : { ...candidate, overflow: true },
+ );
+ });
}
/**
@@ -725,25 +737,36 @@ export const LIBRARY_EMITTED_KINDS = Object.freeze(FAMILIES.flatMap((f) => f.kin
/**
* Run every family the brand has the data for.
*
- * @returns {Promise<{ candidates: object[], unreadKinds: Set<string> }>}
+ * `overflow` holds findings still detected but past their kind's cap. They
+ * are not written as new signals; they keep open ones open.
+ *
+ * @returns {Promise<{ candidates: object[], overflow: object[], unreadKinds: Set<string> }>}
*/
export async function libraryCandidates(brandId, { now = new Date(), sources } = {}) {
const available = sources ?? (await resolveBrandSources(brandId));
const ctx = context(brandId, now, available);
const candidates = [];
+ const overflow = [];
const unreadKinds = new Set();
for (const family of FAMILIES) {
if (!family.requires.every((s) => available.has(s))) continue;
try {
- candidates.push(...(await family.run(ctx)));
+ for (const found of await family.run(ctx)) {
+ if (found.overflow) {
+ const { overflow: _, ...candidate } = found;
+ overflow.push(candidate);
+ } else {
+ candidates.push(found);
+ }
+ }
} catch (err) {
// One family's read failing costs that family's night, not the pass.
for (const kind of family.kinds) unreadKinds.add(kind);
logger.error({ err, brandId, family: family.name }, '[signals] library family failed');
}
}
- return { candidates, unreadKinds };
+ return { candidates, overflow, unreadKinds };
}
export { FAMILIES as LIBRARY_FAMILIES };
diff --git a/server/src/lib/signals/record.js b/server/src/lib/signals/record.js
index bc911794c..e05fdc447 100644
--- a/server/src/lib/signals/record.js
+++ b/server/src/lib/signals/record.js
@@ -502,6 +502,36 @@ async function competitorCitationGapCandidates(brandId, now) {
];
}
+const isOpen = (row) => row.status === 'new' || row.status === 'acknowledged';
+
+/**
+ * Over-cap findings that keep an open signal open. One with no open signal
+ * behind it raises nothing: the cap bounds what a night writes, and a
+ * resolved finding comes back only when it ranks again.
+ */
+export function overflowRefreshes(overflow, existing) {
+ return overflow
+ .map((candidate) => ({ candidate, current: existing.get(candidate.dedupKey) }))
+ .filter(({ current }) => current && isOpen(current));
+}
+
+/**
+ * Open, persistent signals nothing detected tonight — the ones that ended.
+ * `detected` must include over-cap findings: a finding that moved down a
+ * list has not ended. A kind whose detector failed was not looked at, and a
+ * condition nobody looked at has not ended either.
+ */
+export function signalsToResolve(existingRows, detected, unreadKinds) {
+ const detectedKeys = new Set(detected.map((candidate) => candidate.dedupKey));
+ return existingRows.filter(
+ (row) =>
+ KIND_META[row.kind]?.persistent &&
+ isOpen(row) &&
+ !detectedKeys.has(row.dedup_key) &&
+ !unreadKinds.has(row.kind),
+ );
+}
+
export async function recordSignalsForBrand(brandId, { now = new Date() } = {}) {
const metrics = await computePulseMetrics(brandId, {
windowDays: detection.windowDays,
@@ -540,6 +570,12 @@ export async function recordSignalsForBrand(brandId, { now = new Date() } = {})
...library.candidates.filter((candidate) => !(outage && DECLINE_KINDS.has(candidate.kind))),
);
const unreadKinds = library.unreadKinds;
+ // Findings past their kind's cap: still true, so an open signal for one
+ // stays open and is refreshed. Nothing new is raised from them, and a
+ // resolved one is not reopened — that waits until it ranks again.
+ const overflow = library.overflow.filter(
+ (candidate) => !(outage && DECLINE_KINDS.has(candidate.kind)),
+ );
// Existing rows decide insert vs update vs reopen. A brand's signal set is
// small (tens), so reading it whole is cheaper than being clever.
@@ -556,6 +592,22 @@ export async function recordSignalsForBrand(brandId, { now = new Date() } = {})
let refreshed = 0;
let reopened = 0;
+ for (const { candidate, current } of overflowRefreshes(overflow, existing)) {
+ const { error } = await supabaseAdmin
+ .from('signals')
+ .update({
+ last_detected_at: nowIso,
+ previous_value: candidate.previousValue,
+ current_value: candidate.currentValue,
+ change_value: candidate.changeValue,
+ payload: candidate.payload,
+ updated_at: nowIso,
+ })
+ .eq('id', current.id);
+ if (error) throw new Error(error.message);
+ refreshed += 1;
+ }
+
for (const candidate of candidates) {
const meta = KIND_META[candidate.kind];
const current = existing.get(candidate.dedupKey);
@@ -608,18 +660,9 @@ export async function recordSignalsForBrand(brandId, { now = new Date() } = {})
// them. Not during an outage: the engine suppresses drop/loss warnings
// while a platform is degraded, and treating that silence as recovery
// would close real signals.
- const detectedKeys = new Set(candidates.map((c) => c.dedupKey));
const toResolve = outage
? []
- : (existingRows ?? []).filter(
- (row) =>
- KIND_META[row.kind]?.persistent &&
- (row.status === 'new' || row.status === 'acknowledged') &&
- !detectedKeys.has(row.dedup_key) &&
- // A kind whose detector failed tonight was not looked at, and a
- // condition nobody looked at has not ended.
- !unreadKinds.has(row.kind),
- );
+ : signalsToResolve(existingRows ?? [], [...candidates, ...overflow], unreadKinds);
for (const row of toResolve) {
const { error } = await supabaseAdmin
.from('signals')
diff --git a/server/src/lib/signals/resolution.test.js b/server/src/lib/signals/resolution.test.js
new file mode 100644
index 000000000..8b1bfcf26
--- /dev/null
+++ b/server/src/lib/signals/resolution.test.js
@@ -0,0 +1,92 @@
+import { describe, expect, it, vi } from 'vitest';
+
+// record.js and detect.js reach the admin client at import time, whose config
+// hard-exits without SUPABASE_* env (as in CI). Nothing here reads it.
+vi.mock('../../config/supabase.js', () => ({ default: { rpc: vi.fn(), from: vi.fn() } }));
+vi.mock('../logger.js', () => ({
+ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+vi.mock('../pulse/metrics.js', () => ({
+ computePulseMetrics: vi.fn(),
+ isTransientDbError: () => false,
+}));
+
+import { overflowRefreshes, signalsToResolve } from './record.js';
+import { cap } from './library/detect.js';
+import { ENGINE_THRESHOLDS } from '../../config/action-engine.js';
+
+const max = ENGINE_THRESHOLDS.library.maxSignalsPerKind;
+const KIND = 'competitor_cited_source';
+
+const finding = (i) => ({ kind: KIND, dedupKey: `${KIND}:d${i}`, currentValue: 100 - i });
+const row = (i, status = 'new') => ({
+ id: `s${i}`,
+ kind: KIND,
+ dedup_key: `${KIND}:d${i}`,
+ status,
+});
+
+describe('the per-kind cap', () => {
+ const found = Array.from({ length: max + 2 }, (_, i) => finding(i));
+ const capped = cap(found, (x) => x.currentValue);
+
+ it('keeps the strongest findings as signals', () => {
+ expect(capped.filter((x) => !x.overflow).map((x) => x.dedupKey)).toEqual(
+ found.slice(0, max).map((x) => x.dedupKey),
+ );
+ });
+
+ /** Dropping them would make "not in the top five" read as "not there". */
+ it('marks the rest instead of dropping them', () => {
+ expect(capped.filter((x) => x.overflow).map((x) => x.dedupKey)).toEqual(
+ found.slice(max).map((x) => x.dedupKey),
+ );
+ });
+});
+
+describe('which signals a night closes', () => {
+ /**
+ * The failure this guards: a second pass the same night reranked sources,
+ * and every signal that slipped from fifth to sixth was closed as solved
+ * while the problem it described was still there.
+ */
+ it('does not close a signal whose finding only moved down the ranking', () => {
+ const existing = [row(0), row(5)];
+ const kept = [finding(0)];
+ const overflow = [finding(5)];
+ expect(signalsToResolve(existing, [...kept, ...overflow], new Set())).toEqual([]);
+ });
+
+ it('closes one whose finding is gone', () => {
+ const existing = [row(0), row(9)];
+ expect(signalsToResolve(existing, [finding(0)], new Set()).map((r) => r.id)).toEqual(['s9']);
+ });
+
+ it('does not close a kind whose detector failed tonight', () => {
+ expect(signalsToResolve([row(9)], [], new Set([KIND]))).toEqual([]);
+ });
+
+ it('leaves signals someone already closed alone', () => {
+ expect(signalsToResolve([row(9, 'dismissed'), row(8, 'resolved')], [], new Set())).toEqual([]);
+ });
+});
+
+describe('what an over-cap finding writes', () => {
+ const existing = (rows) => new Map(rows.map((r) => [r.dedup_key, r]));
+
+ it('refreshes the open signal it keeps open', () => {
+ const refreshes = overflowRefreshes([finding(5)], existing([row(5, 'acknowledged')]));
+ expect(refreshes.map((r) => r.current.id)).toEqual(['s5']);
+ });
+
+ /** The cap bounds what a night writes; the overflow must not get around it. */
+ it('raises nothing new', () => {
+ expect(overflowRefreshes([finding(5)], existing([]))).toEqual([]);
+ });
+
+ /** It comes back when it ranks again, as a new observation. */
+ it('does not reopen a closed one', () => {
+ expect(overflowRefreshes([finding(5)], existing([row(5, 'resolved')]))).toEqual([]);
+ expect(overflowRefreshes([finding(5)], existing([row(5, 'dismissed')]))).toEqual([]);
+ });
+});