weftens 0.0.1 → 0.1.1

package/agent-cores/paid-search/src/analyze.mjs

@@ -0,0 +1,303 @@
+// Deterministic Google Ads paid-search analysis. No LLM. PROPOSE-ONLY.
+//
+// Input: parsed search-terms rows and campaign-performance rows (canonical fields
+// from parse.mjs). Output: a ranked change sheet. Every row carries the evidence
+// numbers that triggered it. The core never calls a model and never touches an
+// account — a human applies the proposed changes.
+//
+// Three finding families, mirroring the job:
+//   negative  — search terms burning spend with no/poor return (add as negatives)
+//   budget    — converting campaigns throttled by budget (raise / reallocate)
+//   structure — root-cause fixes (starved Smart Bidding, shared-budget starvation)
+//               that outrank the budget moves they explain.
+
+export const DEFAULT_THRESHOLDS = {
+  // Negatives (irrelevant / zero-conversion queries).
+  negMinClicks: 15, // enough traffic that "0 conversions" is signal, not noise
+  negMinCost: 1, // ignore trivial spend
+  // Negatives (inefficient: converting but far above account CPA).
+  effCpaMultiple: 3, // term CPA >= 3x account CPA
+  effMinCost: 20,
+  // Budget moves.
+  lostIsBudgetMin: 0.1, // >=10% eligible impressions lost to budget
+  lostIsBudgetStrangled: 0.3, // >=30% => campaign is being strangled
+  // Structure: Smart Bidding conversion floor (Google rule of thumb ~15-30/30d).
+  biddingMinConv: 30,
+};
+
+const SMART_BIDDING = /target\s*cpa|troas|target\s*roas|maximize\s*conv|maximise\s*conv/i;
+
+function sum(arr, f) {
+  let t = 0;
+  for (const x of arr) { const v = f(x); if (Number.isFinite(v)) t += v; }
+  return t;
+}
+
+function round(n, dp = 2) {
+  if (!Number.isFinite(n)) return n;
+  const m = 10 ** dp;
+  return Math.round(n * m) / m;
+}
+
+// Impression-share opportunity math for a budget-throttled campaign.
+// eligible = impressions / searchIS ; impressions lost to budget = eligible * lostISBudget.
+// Additional clicks/conv/cost/value scale off the campaign's own CTR / CVR / CPC / value.
+// This is an UPPER bound: CTR and CVR usually soften as volume grows.
+function budgetOpportunity(c, thresholds) {
+  const clicks = c.clicks || 0;
+  const cost = c.cost || 0;
+  const conv = c.conversions || 0;
+  const value = c.convValue || 0;
+  const is = c.searchIS;
+  const lost = c.lostISBudget || 0;
+
+  // scaleFactor = how much more share we could capture relative to what we capture now.
+  // Prefer the direct impression math when searchIS is known; else scale by share ratio.
+  let scaleFactor;
+  if (Number.isFinite(is) && is > 0) {
+    scaleFactor = lost / is;
+  } else {
+    scaleFactor = lost / Math.max(1 - lost, 0.01);
+  }
+  const addClicks = clicks * scaleFactor;
+  const cvr = clicks > 0 ? conv / clicks : 0;
+  const cpc = clicks > 0 ? cost / clicks : 0;
+  const valuePerConv = conv > 0 ? value / conv : 0;
+  const addConv = addClicks * cvr;
+  const addCost = addClicks * cpc;
+  const addValue = addConv * valuePerConv;
+  return {
+    scaleFactor: round(scaleFactor, 4),
+    addClicks: Math.round(addClicks),
+    addConv: round(addConv, 1),
+    addCost: round(addCost, 2),
+    addValue: round(addValue, 2),
+    valuePerConv: round(valuePerConv, 2),
+  };
+}
+
+export function analyze(input = {}, options = {}) {
+  const thresholds = { ...DEFAULT_THRESHOLDS, ...(options.thresholds || {}) };
+  const searchTerms = Array.isArray(input.searchTerms) ? input.searchTerms : [];
+  const campaigns = Array.isArray(input.campaigns) ? input.campaigns : [];
+
+  // --- account-level aggregates from the search-terms report ---
+  const totalClicks = sum(searchTerms, (t) => t.clicks);
+  const totalCost = sum(searchTerms, (t) => t.cost);
+  const totalConv = sum(searchTerms, (t) => t.conversions);
+  const totalConvValue = sum(searchTerms, (t) => t.convValue);
+  const accountCVR = totalClicks > 0 ? totalConv / totalClicks : 0;
+  const accountCPA = totalConv > 0 ? totalCost / totalConv : null;
+  const accountValuePerConv = totalConv > 0 ? totalConvValue / totalConv : null;
+
+  const changes = [];
+
+  // --- 1. Negatives: irrelevant / zero-conversion queries ---
+  for (const t of searchTerms) {
+    const clicks = t.clicks || 0;
+    const cost = t.cost || 0;
+    const conv = t.conversions || 0;
+    if (conv === 0 && clicks >= thresholds.negMinClicks && cost >= thresholds.negMinCost) {
+      const expectedConv = round(clicks * accountCVR, 1);
+      changes.push({
+        type: 'negative',
+        subtype: 'irrelevant',
+        change: `Add "${t.searchTerm}" as a negative keyword`,
+        where: t.campaign ? `campaign: ${t.campaign}${t.adGroup ? ` / ${t.adGroup}` : ''}` : 'account level',
+        why: `${clicks} clicks, $${round(cost)} spent, 0 conversions`
+          + (accountCVR > 0 ? ` (expected ~${expectedConv} at the ${round(accountCVR * 100, 1)}% account conversion rate)` : ''),
+        expectedEffect: `Recover ~$${round(cost)}/period of wasted spend`,
+        risk: 'If the query is actually relevant, you forfeit those impressions — confirm intent before excluding.',
+        dollars: round(cost),
+        evidence: {
+          searchTerm: t.searchTerm, campaign: t.campaign ?? null,
+          clicks, cost: round(cost), conversions: conv, expectedConv,
+        },
+      });
+    } else if (
+      conv > 0 && accountCPA != null && cost >= thresholds.effMinCost
+      && cost / conv >= thresholds.effCpaMultiple * accountCPA
+    ) {
+      // inefficient: converting, but paying far above the account's cost per conversion
+      const termCpa = cost / conv;
+      const overspend = cost - conv * accountCPA;
+      changes.push({
+        type: 'negative',
+        subtype: 'inefficient',
+        change: `Bid down or restrict "${t.searchTerm}" (or add as negative if off-intent)`,
+        where: t.campaign ? `campaign: ${t.campaign}${t.adGroup ? ` / ${t.adGroup}` : ''}` : 'account level',
+        why: `CPA $${round(termCpa)} vs account $${round(accountCPA)} (${round(termCpa / accountCPA, 1)}x); `
+          + `$${round(cost)} for ${round(conv, 1)} conv`,
+        expectedEffect: `Recover ~$${round(overspend)}/period of over-target spend`,
+        risk: 'Converting term — restricting too hard can cut real volume; prefer a bid cut first.',
+        dollars: round(overspend),
+        evidence: {
+          searchTerm: t.searchTerm, campaign: t.campaign ?? null,
+          cost: round(cost), conversions: round(conv, 1),
+          termCpa: round(termCpa), accountCPA: round(accountCPA),
+        },
+      });
+    }
+  }
+
+  // --- 2 & 3. Campaign-level: budget moves and structure fixes ---
+  const byCampaign = new Map();
+  for (const c of campaigns) if (c.campaign) byCampaign.set(c.campaign, c);
+
+  // group campaigns by shared budget pool for structure analysis
+  const pools = new Map();
+  for (const c of campaigns) {
+    if (!c.sharedBudget) continue;
+    if (!pools.has(c.sharedBudget)) pools.set(c.sharedBudget, []);
+    pools.get(c.sharedBudget).push(c);
+  }
+
+  // maps campaign -> the largest related budget-opportunity dollars (for structure ranking)
+  const budgetDollarsByCampaign = new Map();
+
+  for (const c of campaigns) {
+    const conv = c.conversions || 0;
+    const lost = c.lostISBudget || 0;
+    if (lost >= thresholds.lostIsBudgetMin && conv > 0) {
+      const opp = budgetOpportunity(c, thresholds);
+      const strangled = lost >= thresholds.lostIsBudgetStrangled;
+      const dollars = opp.addValue > 0 ? opp.addValue
+        : (accountCPA != null ? round(opp.addConv * accountCPA, 2) : opp.addConv);
+      budgetDollarsByCampaign.set(
+        c.campaign,
+        Math.max(budgetDollarsByCampaign.get(c.campaign) || 0, dollars),
+      );
+      changes.push({
+        type: 'budget',
+        subtype: strangled ? 'strangled' : 'throttled',
+        change: strangled
+          ? `Raise budget (or reallocate to) "${c.campaign}" — it is being strangled`
+          : `Raise budget for "${c.campaign}"`,
+        where: `campaign: ${c.campaign}`,
+        why: `${round(lost * 100, 1)}% of eligible impressions lost to budget, `
+          + `${round(conv, 1)} conversions at ${Number.isFinite(c.searchIS) ? round(c.searchIS * 100, 1) + '% impr. share' : 'unknown share'}`,
+        expectedEffect: `~+${opp.addClicks} clicks, +${opp.addConv} conv`
+          + (opp.addValue > 0 ? `, +$${opp.addValue} value` : '')
+          + ` at ~$${opp.addCost} more spend (upper bound)`,
+        risk: 'Scaling assumes current CTR/CVR hold as volume grows; they usually soften. Treat as a ceiling.',
+        dollars,
+        evidence: {
+          campaign: c.campaign, lostISBudget: round(lost, 4),
+          searchIS: Number.isFinite(c.searchIS) ? round(c.searchIS, 4) : null,
+          conversions: round(conv, 1), ...opp,
+        },
+      });
+    }
+  }
+
+  // Structure: Smart Bidding starved of conversion signal
+  for (const c of campaigns) {
+    const strat = c.biddingStrategy || '';
+    const conv = c.conversions || 0;
+    if (SMART_BIDDING.test(strat) && conv < thresholds.biddingMinConv) {
+      const atRisk = round(c.cost || 0);
+      const related = budgetDollarsByCampaign.get(c.campaign) || 0;
+      changes.push({
+        type: 'structure',
+        subtype: 'smart-bidding-starved',
+        change: `Fix bidding on "${c.campaign}" before touching budget — "${strat}" is starved of conversion signal`,
+        where: `campaign: ${c.campaign}`,
+        why: `${round(conv, 1)} conversions in the period is below the ~${thresholds.biddingMinConv}/30d Smart Bidding needs; `
+          + `$${atRisk} of spend is governed by a mis-calibrated bid strategy`,
+        expectedEffect: 'Consolidate conversion volume or switch to Maximize Clicks / manual until signal is sufficient; pacing issues here usually resolve once bidding has data',
+        risk: 'Bid-strategy changes trigger a new learning window; expect 1-2 weeks of unstable performance.',
+        dollars: atRisk,
+        // rank at/above any budget move on the same campaign (structure outranks budget)
+        rankValue: Math.max(atRisk, related + 0.01),
+        evidence: {
+          campaign: c.campaign, biddingStrategy: strat,
+          conversions: round(conv, 1), cost: atRisk, floor: thresholds.biddingMinConv,
+        },
+      });
+    }
+  }
+
+  // Structure: shared budget pool starving converting campaigns
+  for (const [poolName, members] of pools) {
+    if (members.length < 2) continue;
+    const throttled = members.filter((c) => (c.lostISBudget || 0) >= thresholds.lostIsBudgetMin && (c.conversions || 0) > 0);
+    if (throttled.length === 0) continue;
+    let poolDollars = 0;
+    const detail = [];
+    for (const c of throttled) {
+      const opp = budgetOpportunity(c, thresholds);
+      const d = opp.addValue > 0 ? opp.addValue
+        : (accountCPA != null ? round(opp.addConv * accountCPA, 2) : opp.addConv);
+      poolDollars += d;
+      detail.push({ campaign: c.campaign, lostISBudget: round(c.lostISBudget || 0, 4), addConv: opp.addConv, addValue: opp.addValue });
+    }
+    poolDollars = round(poolDollars, 2);
+    changes.push({
+      type: 'structure',
+      subtype: 'shared-budget-starve',
+      change: `Split or resize shared budget "${poolName}" — one pool is starving ${throttled.length} converting campaign(s)`,
+      where: `shared budget: ${poolName} (${members.map((m) => m.campaign).join(', ')})`,
+      why: `${throttled.length} converting campaign(s) losing impression share to a single shared pool: `
+        + throttled.map((c) => `${c.campaign} ${round((c.lostISBudget || 0) * 100, 1)}%`).join(', '),
+      expectedEffect: `Give throttled campaigns their own budgets; unlocks ~$${poolDollars} of value (aggregate upper bound)`,
+      risk: 'Splitting a pool removes automatic cross-campaign smoothing; monitor the others do not now underspend.',
+      dollars: poolDollars,
+      rankValue: poolDollars, // aggregate root cause, already large
+      evidence: { pool: poolName, members: members.map((m) => m.campaign), throttled: detail },
+    });
+  }
+
+  // --- rank the change sheet ---
+  // Primary: dollars of impact (rankValue lets structure sit at/above related budget moves).
+  // Tiebreak: type (structure < negative < budget), then a stable string key.
+  const typeRank = { structure: 0, negative: 1, budget: 2 };
+  const keyed = changes.map((c, i) => ({ ...c, rankValue: Number.isFinite(c.rankValue) ? c.rankValue : (c.dollars || 0), _i: i }));
+  keyed.sort((a, b) => {
+    if (b.rankValue !== a.rankValue) return b.rankValue - a.rankValue;
+    if (typeRank[a.type] !== typeRank[b.type]) return typeRank[a.type] - typeRank[b.type];
+    const ka = `${a.type}:${a.subtype}:${a.change}`;
+    const kb = `${b.type}:${b.subtype}:${b.change}`;
+    return ka < kb ? -1 : ka > kb ? 1 : a._i - b._i;
+  });
+  const ranked = keyed.map(({ _i, ...c }, idx) => ({ rank: idx + 1, ...c }));
+
+  const recoverable = round(
+    sum(ranked.filter((c) => c.type === 'negative'), (c) => c.dollars),
+    2,
+  );
+  const opportunity = round(
+    sum(ranked.filter((c) => c.type === 'budget'), (c) => c.dollars),
+    2,
+  );
+
+  return {
+    proposeOnly: true,
+    account: {
+      searchTermRows: searchTerms.length,
+      campaignRows: campaigns.length,
+      totalClicks,
+      totalCost: round(totalCost),
+      totalConversions: round(totalConv, 1),
+      accountCVR: round(accountCVR, 4),
+      accountCPA: accountCPA == null ? null : round(accountCPA),
+      accountValuePerConv: accountValuePerConv == null ? null : round(accountValuePerConv),
+    },
+    counts: {
+      total: ranked.length,
+      negatives: ranked.filter((c) => c.type === 'negative').length,
+      budget: ranked.filter((c) => c.type === 'budget').length,
+      structure: ranked.filter((c) => c.type === 'structure').length,
+    },
+    wastedSpendRecoverable: recoverable,
+    budgetOpportunityValue: opportunity,
+    summary: buildSummary(ranked, recoverable, opportunity),
+    changes: ranked,
+  };
+}
+
+function buildSummary(ranked, recoverable, opportunity) {
+  if (ranked.length === 0) return 'No negative, budget, or structure changes found in the exported reports.';
+  const top = ranked[0];
+  return `${ranked.length} proposed change(s); ~$${recoverable} recoverable from negatives, `
+    + `~$${opportunity} budget opportunity. Start with: ${top.change}.`;
+}

package/agent-cores/paid-search/src/cli.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+// Real CLI. PROPOSE-ONLY — reads exported Google Ads reports, prints a ranked
+// change sheet as JSON on stdout and a one-line summary on stderr. No account access.
+//
+// Modes:
+//   paid-search --search-terms <csv> [--campaigns <csv>] [--pretty]
+//   paid-search --campaigns <csv> [--search-terms <csv>]
+//   paid-search <input.json>        JSON: { "searchTerms": [...], "campaigns": [...] }
+
+import { readFileSync } from 'node:fs';
+import { analyze } from './analyze.mjs';
+import { parseReport } from './parse.mjs';
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--search-terms' || a === '-s') args.searchTerms = argv[++i];
+    else if (a === '--campaigns' || a === '-c') args.campaigns = argv[++i];
+    else if (a === '--pretty') args.pretty = true;
+    else args._.push(a);
+  }
+  return args;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (!args.searchTerms && !args.campaigns && args._.length === 0) {
+    console.error('Usage: paid-search --search-terms <csv> [--campaigns <csv>] [--pretty]');
+    console.error('       paid-search <input.json>   (keys: searchTerms, campaigns)');
+    process.exitCode = 1;
+    return;
+  }
+
+  let input = { searchTerms: [], campaigns: [] };
+
+  if (args._.length > 0 && !args.searchTerms && !args.campaigns) {
+    const parsed = JSON.parse(readFileSync(args._[0], 'utf8'));
+    input.searchTerms = parsed.searchTerms || [];
+    input.campaigns = parsed.campaigns || [];
+  } else {
+    if (args.searchTerms) input.searchTerms = parseReport(readFileSync(args.searchTerms, 'utf8'));
+    if (args.campaigns) input.campaigns = parseReport(readFileSync(args.campaigns, 'utf8'));
+  }
+
+  const result = analyze(input);
+  console.error(`paid-search: ${result.summary}`);
+  console.log(JSON.stringify(result, null, args.pretty ? 2 : 0));
+}
+
+try {
+  main();
+} catch (err) {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exitCode = 1;
+}

package/agent-cores/paid-search/src/parse.mjs

@@ -0,0 +1,158 @@
+// Dependency-free CSV parser + Google Ads column mapper.
+// Real Google Ads UI exports carry a title row, a date-range row, sometimes a blank
+// line, then the real header, the data rows, and a trailing "Total: ..." row. We find
+// the header by looking for a row that contains known column tokens, map arbitrary
+// header spellings to canonical field names, and coerce currency/percent/number cells.
+
+// --- CSV tokenizer (state machine; handles quotes, embedded commas, CRLF) ---
+
+export function parseCsv(text) {
+  const rows = [];
+  let row = [];
+  let field = '';
+  let inQuotes = false;
+  const s = String(text).replace(/^/, ''); // strip BOM
+
+  for (let i = 0; i < s.length; i += 1) {
+    const c = s[i];
+    if (inQuotes) {
+      if (c === '"') {
+        if (s[i + 1] === '"') { field += '"'; i += 1; }
+        else inQuotes = false;
+      } else {
+        field += c;
+      }
+    } else if (c === '"') {
+      inQuotes = true;
+    } else if (c === ',') {
+      row.push(field); field = '';
+    } else if (c === '\n') {
+      row.push(field); field = '';
+      rows.push(row); row = [];
+    } else if (c === '\r') {
+      // handled by \n; ignore lone CR
+    } else {
+      field += c;
+    }
+  }
+  // flush last field/row if any content
+  if (field.length > 0 || row.length > 0) {
+    row.push(field);
+    rows.push(row);
+  }
+  return rows;
+}
+
+// --- header normalization + alias map ---
+
+function normHeader(h) {
+  return String(h).toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
+}
+
+// canonical field -> the normalized header spellings that map to it
+const ALIASES = {
+  searchTerm: ['search term', 'search terms', 'query'],
+  campaign: ['campaign', 'campaign name'],
+  adGroup: ['ad group', 'ad group name'],
+  matchType: ['match type', 'search term match type'],
+  impressions: ['impr', 'impressions', 'impr '],
+  clicks: ['clicks'],
+  cost: ['cost', 'spend'],
+  conversions: ['conversions', 'conv', 'conversions all', 'all conv'],
+  convValue: ['conv value', 'conversion value', 'all conv value', 'total conv value', 'conv value all'],
+  searchIS: ['search impr share', 'search impression share', 'impr share', 'search is'],
+  lostISBudget: [
+    'search lost is budget', 'search lost impr share budget', 'budget lost is',
+    'search lost impression share budget', 'lost is budget',
+  ],
+  lostISRank: ['search lost is rank', 'search lost impr share rank', 'lost is rank'],
+  biddingStrategy: ['bid strategy type', 'bidding strategy', 'bid strategy'],
+  budget: ['budget', 'daily budget', 'budget amount'],
+  sharedBudget: ['budget name', 'shared budget', 'budget name shared'],
+};
+
+// reverse lookup: normalized header -> canonical
+const HEADER_TO_FIELD = (() => {
+  const m = new Map();
+  for (const [field, spellings] of Object.entries(ALIASES)) {
+    for (const sp of spellings) m.set(sp, field);
+  }
+  return m;
+})();
+
+const SHARE_FIELDS = new Set(['searchIS', 'lostISBudget', 'lostISRank']);
+const NUMERIC_FIELDS = new Set(['impressions', 'clicks', 'cost', 'conversions', 'convValue', 'budget']);
+
+// --- cell coercion ---
+
+export function toNumber(raw) {
+  if (raw == null) return null;
+  let v = String(raw).trim();
+  if (v === '' || v === '--' || v === '—' || v.toLowerCase() === 'n/a') return null;
+  v = v.replace(/[$£€,%\s"]/g, '');
+  if (v === '' || v === '<' || v === '>') return null;
+  v = v.replace(/^[<>]/, ''); // "< 10" style already stripped of %
+  const n = Number.parseFloat(v);
+  return Number.isFinite(n) ? n : null;
+}
+
+// Impression-share style cell -> fraction in [0,1]. Handles "35%", "0.35", "35",
+// "< 10%" (Google's floor -> 0.10), "> 90%" (ceiling -> 0.90), "--".
+export function toShare(raw) {
+  if (raw == null) return null;
+  const v = String(raw).trim();
+  if (v === '' || v === '--' || v === '—') return null;
+  const hadPercent = v.includes('%');
+  const n = toNumber(v);
+  if (n == null) return null;
+  let frac = hadPercent ? n / 100 : (n > 1.5 ? n / 100 : n);
+  if (frac < 0) frac = 0;
+  if (frac > 1) frac = 1;
+  return frac;
+}
+
+function coerce(field, raw) {
+  if (SHARE_FIELDS.has(field)) return toShare(raw);
+  if (NUMERIC_FIELDS.has(field)) return toNumber(raw);
+  const s = raw == null ? '' : String(raw).trim();
+  return s;
+}
+
+// Find the header row: the first row that maps at least `minKnown` cells to canonical fields.
+function findHeader(rows, minKnown = 2) {
+  for (let i = 0; i < rows.length; i += 1) {
+    const mapped = rows[i].map((h) => HEADER_TO_FIELD.get(normHeader(h))).filter(Boolean);
+    if (new Set(mapped).size >= minKnown) return i;
+  }
+  return -1;
+}
+
+// Parse a Google Ads CSV export into canonical row objects.
+export function parseReport(text) {
+  const rows = parseCsv(text);
+  const headerIdx = findHeader(rows);
+  if (headerIdx === -1) {
+    throw new Error('No recognizable Google Ads header row found (need e.g. "Campaign", "Cost", "Clicks").');
+  }
+  const header = rows[headerIdx];
+  const colField = header.map((h) => HEADER_TO_FIELD.get(normHeader(h)) || null);
+
+  const out = [];
+  for (let i = headerIdx + 1; i < rows.length; i += 1) {
+    const cells = rows[i];
+    // skip blank rows and Google's trailing "Total: ..." summary rows
+    const first = (cells[0] || '').trim();
+    if (cells.every((c) => (c || '').trim() === '')) continue;
+    if (/^total/i.test(first)) continue;
+
+    const rec = {};
+    for (let c = 0; c < colField.length; c += 1) {
+      const field = colField[c];
+      if (!field) continue;
+      rec[field] = coerce(field, cells[c]);
+    }
+    // require at least one identifying string so we don't emit garbage rows
+    if (rec.searchTerm || rec.campaign) out.push(rec);
+  }
+  return out;
+}

package/agent-cores/paid-search/test/analyze.test.mjs

@@ -0,0 +1,120 @@
+// Engine tests — run with `node --test`, zero install. Asserts the analyzer detects
+// the SPECIFIC issues seeded into the fixtures and that the output is deterministic.
+// If these pass, the core is doing real arithmetic on real reports, not echoing a prompt.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { analyze } from '../src/analyze.mjs';
+import { parseReport } from '../src/parse.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const load = (f) => parseReport(readFileSync(join(__dirname, 'fixtures', f), 'utf8'));
+
+function run() {
+  return analyze({
+    searchTerms: load('search-terms.csv'),
+    campaigns: load('campaigns.csv'),
+  });
+}
+
+const bySub = (r, sub) => r.changes.filter((c) => c.subtype === sub);
+const findTerm = (r, term) => r.changes.find((c) => c.evidence && c.evidence.searchTerm === term);
+
+test('flags zero-conversion queries with enough clicks as negatives', () => {
+  const r = run();
+  const negs = bySub(r, 'irrelevant');
+  const terms = negs.map((n) => n.evidence.searchTerm).sort();
+  assert.deepEqual(terms, ['free blue widgets', 'what is a widget', 'widget repair career jobs']);
+});
+
+test('does NOT flag a zero-conv query below the click threshold', () => {
+  const r = run();
+  // "blue widget reviews" has only 5 clicks — must not appear
+  assert.equal(findTerm(r, 'blue widget reviews'), undefined);
+});
+
+test('recovered spend on a negative equals the query cost', () => {
+  const r = run();
+  const free = findTerm(r, 'free blue widgets');
+  assert.equal(free.type, 'negative');
+  assert.equal(free.dollars, 90);
+  assert.equal(free.evidence.cost, 90);
+});
+
+test('flags a converting-but-inefficient query (CPA >> account CPA)', () => {
+  const r = run();
+  const eff = bySub(r, 'inefficient');
+  assert.equal(eff.length, 1);
+  assert.equal(eff[0].evidence.searchTerm, 'premium widget wholesale bulk');
+  // account CPA = 910/11 = 82.73; overspend = 500 - 1*82.73 = 417.27
+  assert.ok(Math.abs(eff[0].dollars - 417.27) < 0.5, `overspend ~417.27, got ${eff[0].dollars}`);
+});
+
+test('flags a strangled converting campaign as a budget move with real opportunity math', () => {
+  const r = run();
+  const budget = r.changes.filter((c) => c.type === 'budget');
+  const generic = budget.find((c) => c.evidence.campaign === 'Generic');
+  assert.ok(generic, 'Generic budget move exists');
+  assert.equal(generic.subtype, 'strangled'); // 35% lost >= 30%
+  // scale = 0.35/0.45 = 0.7778; addClicks = 778; addConv = 778*0.04 = 31.1; value = *100 = 3111
+  assert.equal(generic.evidence.addClicks, 778);
+  assert.ok(Math.abs(generic.dollars - 3111.2) < 5, `~3111 value, got ${generic.dollars}`);
+});
+
+test('flags Smart Bidding starved of conversions as a STRUCTURE fix', () => {
+  const r = run();
+  const struct = bySub(r, 'smart-bidding-starved');
+  assert.equal(struct.length, 1);
+  assert.equal(struct[0].type, 'structure');
+  assert.equal(struct[0].evidence.campaign, 'Competitor');
+  assert.equal(struct[0].evidence.conversions, 6); // below the 30 floor
+});
+
+test('flags a shared budget pool starving converting campaigns as STRUCTURE', () => {
+  const r = run();
+  const pool = bySub(r, 'shared-budget-starve');
+  assert.equal(pool.length, 1);
+  assert.equal(pool[0].evidence.pool, 'Shared-1');
+  assert.deepEqual(pool[0].evidence.members.sort(), ['Competitor', 'Generic']);
+});
+
+test('structure outranks the budget move on the same campaign', () => {
+  const r = run();
+  const bidding = r.changes.find((c) => c.subtype === 'smart-bidding-starved');
+  const compBudget = r.changes.find((c) => c.type === 'budget' && c.evidence.campaign === 'Competitor');
+  assert.ok(bidding.rank < compBudget.rank, `structure (rank ${bidding.rank}) must precede budget (rank ${compBudget.rank})`);
+});
+
+test('the change sheet is ranked by dollars of impact', () => {
+  const r = run();
+  const d = r.changes.map((c) => c.rankValue);
+  for (let i = 1; i < d.length; i += 1) {
+    assert.ok(d[i - 1] >= d[i], `rankValue must be non-increasing: ${d[i - 1]} < ${d[i]} at ${i}`);
+  }
+  // top finding is the aggregate shared-budget root cause
+  assert.equal(r.changes[0].subtype, 'shared-budget-starve');
+});
+
+test('counts and totals reflect the seeded fixture exactly', () => {
+  const r = run();
+  assert.equal(r.counts.negatives, 4); // 3 irrelevant + 1 inefficient
+  assert.equal(r.counts.budget, 2);
+  assert.equal(r.counts.structure, 2);
+  assert.equal(r.account.totalConversions, 11);
+  assert.equal(r.proposeOnly, true);
+});
+
+test('output is deterministic — same input yields byte-identical JSON', () => {
+  const a = JSON.stringify(run());
+  const b = JSON.stringify(run());
+  assert.equal(a, b);
+});
+
+test('empty input produces a clean, non-crashing result', () => {
+  const r = analyze({ searchTerms: [], campaigns: [] });
+  assert.equal(r.changes.length, 0);
+  assert.match(r.summary, /No negative, budget, or structure changes/);
+});

package/agent-cores/paid-search/test/fixtures/campaigns.csv

@@ -0,0 +1,7 @@
+Campaign performance report
+Jan 1, 2026 - Jan 31, 2026
+Campaign,Impr.,Clicks,Cost,Conversions,Conv. value,Search impr. share,Search lost IS (budget),Bid strategy type,Budget name
+Brand,10000,800,400.00,60,6000.00,82%,3%,Target CPA,Brand-Budget
+Generic,20000,1000,2000.00,40,4000.00,45%,35%,Maximize conversions,Shared-1
+Competitor,5000,200,600.00,6,600.00,30%,40%,Target CPA,Shared-1
+Total: Campaigns,35000,2000,3000.00,106,10600.00,,,,

package/agent-cores/paid-search/test/fixtures/sample.json

@@ -0,0 +1,9 @@
+{
+  "searchTerms": [
+    { "searchTerm": "buy blue widgets", "campaign": "Generic", "clicks": 40, "cost": 120, "conversions": 6, "convValue": 600 },
+    { "searchTerm": "free blue widgets", "campaign": "Generic", "clicks": 60, "cost": 90, "conversions": 0, "convValue": 0 }
+  ],
+  "campaigns": [
+    { "campaign": "Generic", "impressions": 20000, "clicks": 1000, "cost": 2000, "conversions": 40, "convValue": 4000, "searchIS": 0.45, "lostISBudget": 0.35, "biddingStrategy": "Maximize conversions" }
+  ]
+}

package/agent-cores/paid-search/test/fixtures/search-terms.csv

@@ -0,0 +1,11 @@
+Search terms report
+Jan 1, 2026 - Jan 31, 2026
+Search term,Campaign,Ad group,Match type,Impr.,Clicks,Cost,Conversions,Conv. value
+buy blue widgets,Generic,Widgets - Exact,Exact,500,40,120.00,6,600.00
+blue widget store near me,Generic,Widgets - Phrase,Phrase,420,30,95.00,4,400.00
+free blue widgets,Generic,Widgets - Broad,Broad,800,60,90.00,0,0.00
+widget repair career jobs,Generic,Widgets - Broad,Broad,300,25,55.00,0,0.00
+blue widget reviews,Generic,Widgets - Phrase,Phrase,200,5,8.00,0,0.00
+premium widget wholesale bulk,Brand,Brand - Exact,Exact,400,30,500.00,1,100.00
+what is a widget,Generic,Widgets - Broad,Broad,600,18,42.00,0,0.00
+Total: Search terms,,,,3220,208,910.00,11,1200.00