weftens 0.0.1 → 0.1.1

package/agent-cores/supply-verify/src/verify.mjs

@@ -0,0 +1,303 @@
+// Deterministic ad-spend verification. No LLM. Given programmatic placement /
+// log-level rows (one per domain or app), compute an evidenced waste report:
+// MFA (made-for-advertising) markers, invalid-traffic (IVT) flags, low-viewability
+// spend, and a concrete exclusion list with the spend each exclusion recovers.
+//
+// Input is DATA, not a prompt. Every finding carries an evidence string, a
+// confidence tier, and the spend it affects — all computed with real arithmetic.
+//
+// Confidence tiers (from the analyst spec, weakest to strongest):
+//   needs-data < consistent-with < probable < verified
+// MFA and IVT detection off log-level metrics is inherently heuristic, so the
+// core never emits "verified" for them — the strongest it asserts is "probable".
+
+export const DEFAULT_THRESHOLDS = {
+  // IVT (invalid traffic) rate, in percentage points.
+  ivtProbable: 20, // >= this: probable invalid-traffic problem, auto-exclude candidate
+  ivtWatch: 10, // >= this: consistent-with elevated IVT
+  // Viewability rate, in percentage points. Industry floor guidance ~50% (display).
+  viewabilityLow: 50, // < this: consistent-with a viewability problem
+  viewabilityBad: 40, // < this: probable viewability problem
+  // Video completion rate, in percentage points (only scored when present).
+  completionFloor: 20,
+  // MFA markers.
+  adDensityHigh: 8, // ads-per-page at/above this is an extreme-density marker
+  sourcedTrafficHigh: 50, // % of traffic that is sourced/paid rather than earned
+  mfaMarkerMin: 3, // "a site is MFA on three markers, not one" -> flag at 3
+  mfaMarkerStrong: 4, // >= this markers escalates confidence to "probable"
+};
+
+const CONFIDENCE_RANK = { 'needs-data': 0, 'consistent-with': 1, probable: 2, verified: 3 };
+
+// --- input normalization ---------------------------------------------------
+
+const COLUMN_ALIASES = {
+  domain: ['domain', 'site', 'app', 'app_bundle', 'bundle', 'placement', 'publisher', 'url', 'inventory'],
+  impressions: ['impressions', 'imps', 'impression'],
+  spend: ['spend', 'cost', 'media_cost', 'amount', 'net_spend'],
+  viewability_pct: ['viewability_pct', 'viewability', 'viewable_rate', 'viewability_rate', 'in_view_rate', 'viewable'],
+  ivt_pct: ['ivt_pct', 'ivt', 'invalid_traffic', 'invalid_traffic_rate', 'givt', 'total_ivt'],
+  completion_rate: ['completion_rate', 'vcr', 'completion', 'video_completion_rate'],
+  ad_density: ['ad_density', 'ads_per_page', 'ad_count'],
+  sourced_traffic_pct: ['sourced_traffic_pct', 'sourced_traffic', 'paid_traffic', 'sourced_traffic_share'],
+};
+
+function canonicalKey(raw) {
+  const norm = String(raw).trim().toLowerCase().replace(/[%()]/g, '').replace(/[\s/.-]+/g, '_').replace(/_+/g, '_').replace(/^_|_$/g, '');
+  for (const [canon, aliases] of Object.entries(COLUMN_ALIASES)) {
+    if (aliases.includes(norm)) return canon;
+  }
+  return null;
+}
+
+// Parse a percentage-like value. Accepts "42", "42%", " 42 ". Values are treated
+// as percentage POINTS (0-100). A bare fraction in [0,1] is upscaled to percent
+// so "0.42" and "42" both mean 42%. Returns null when absent/unparseable.
+function parsePct(v) {
+  if (v === undefined || v === null || v === '') return null;
+  const n = Number(String(v).replace('%', '').trim());
+  if (!Number.isFinite(n)) return null;
+  if (n > 0 && n <= 1) return n * 100;
+  return n;
+}
+
+function parseNum(v) {
+  if (v === undefined || v === null || v === '') return null;
+  const n = Number(String(v).replace(/[$,\s]/g, ''));
+  return Number.isFinite(n) ? n : null;
+}
+
+// Minimal, dependency-free CSV parser. Handles quoted fields, embedded commas,
+// escaped double-quotes ("") and CRLF/LF line endings.
+export function parseCsv(text) {
+  const rows = [];
+  let field = '';
+  let record = [];
+  let inQuotes = false;
+  const pushField = () => { record.push(field); field = ''; };
+  const pushRecord = () => { pushField(); rows.push(record); record = []; };
+  for (let i = 0; i < text.length; i += 1) {
+    const c = text[i];
+    if (inQuotes) {
+      if (c === '"') {
+        if (text[i + 1] === '"') { field += '"'; i += 1; }
+        else inQuotes = false;
+      } else field += c;
+    } else if (c === '"') inQuotes = true;
+    else if (c === ',') pushField();
+    else if (c === '\n') pushRecord();
+    else if (c === '\r') { /* swallow, handled by \n */ }
+    else field += c;
+  }
+  if (field !== '' || record.length > 0) pushRecord();
+  // drop trailing empty record
+  while (rows.length && rows[rows.length - 1].length === 1 && rows[rows.length - 1][0] === '') rows.pop();
+  if (rows.length === 0) return [];
+  const header = rows[0];
+  return rows.slice(1).filter((r) => r.some((c) => c !== '')).map((r) => {
+    const obj = {};
+    header.forEach((h, idx) => { obj[h] = r[idx] ?? ''; });
+    return obj;
+  });
+}
+
+// Turn a loose record ({header: value}) into a normalized placement.
+function normalizeRow(rawObj) {
+  const out = {};
+  for (const [k, v] of Object.entries(rawObj)) {
+    const canon = canonicalKey(k);
+    if (canon && out[canon] === undefined) out[canon] = v;
+  }
+  return {
+    domain: out.domain !== undefined ? String(out.domain).trim() : '(unknown)',
+    impressions: parseNum(out.impressions) ?? 0,
+    spend: parseNum(out.spend) ?? 0,
+    viewability_pct: parsePct(out.viewability_pct),
+    ivt_pct: parsePct(out.ivt_pct),
+    completion_rate: parsePct(out.completion_rate),
+    ad_density: parseNum(out.ad_density),
+    sourced_traffic_pct: parsePct(out.sourced_traffic_pct),
+  };
+}
+
+// Accept a CSV string, a JSON string, or an already-parsed array of objects.
+export function loadPlacements(input, { format } = {}) {
+  if (Array.isArray(input)) return input.map(normalizeRow);
+  const text = String(input);
+  const isJson = format === 'json' || (format !== 'csv' && /^\s*[[{]/.test(text));
+  if (isJson) {
+    const data = JSON.parse(text);
+    const arr = Array.isArray(data) ? data : (Array.isArray(data.placements) ? data.placements : [data]);
+    return arr.map(normalizeRow);
+  }
+  return parseCsv(text).map(normalizeRow);
+}
+
+// --- the analysis ----------------------------------------------------------
+
+function round2(n) { return Math.round(n * 100) / 100; }
+
+// Evaluate one placement. Returns { placement, markers, findings, exclusion }.
+function analyzePlacement(p, t) {
+  const findings = [];
+  const markers = []; // MFA markers, each with a human-readable evidence string
+
+  const nonViewableSpend = p.viewability_pct === null ? 0 : round2(p.spend * (1 - p.viewability_pct / 100));
+  const ivtWastedSpend = p.ivt_pct === null ? 0 : round2(p.spend * (p.ivt_pct / 100));
+
+  // --- IVT ---
+  if (p.ivt_pct === null) {
+    findings.push({ domain: p.domain, type: 'ivt', confidence: 'needs-data', evidence: 'No IVT rate supplied for this placement.', spendAffected: p.spend, estimatedWaste: 0 });
+  } else if (p.ivt_pct >= t.ivtProbable) {
+    findings.push({ domain: p.domain, type: 'ivt', confidence: 'probable', evidence: `IVT ${round2(p.ivt_pct)}% >= ${t.ivtProbable}% threshold on ${p.impressions.toLocaleString('en-US')} impressions; $${ivtWastedSpend} of spend served to invalid traffic.`, spendAffected: p.spend, estimatedWaste: ivtWastedSpend });
+  } else if (p.ivt_pct >= t.ivtWatch) {
+    findings.push({ domain: p.domain, type: 'ivt', confidence: 'consistent-with', evidence: `IVT ${round2(p.ivt_pct)}% is elevated (watch >= ${t.ivtWatch}%); ~$${ivtWastedSpend} exposed.`, spendAffected: p.spend, estimatedWaste: ivtWastedSpend });
+  }
+
+  // --- Viewability ---
+  if (p.viewability_pct === null) {
+    findings.push({ domain: p.domain, type: 'low-viewability', confidence: 'needs-data', evidence: 'No viewability rate supplied for this placement.', spendAffected: p.spend, estimatedWaste: 0 });
+  } else if (p.viewability_pct < t.viewabilityBad) {
+    findings.push({ domain: p.domain, type: 'low-viewability', confidence: 'probable', evidence: `Viewability ${round2(p.viewability_pct)}% < ${t.viewabilityBad}%; $${nonViewableSpend} of spend was never in view.`, spendAffected: p.spend, estimatedWaste: nonViewableSpend });
+  } else if (p.viewability_pct < t.viewabilityLow) {
+    findings.push({ domain: p.domain, type: 'low-viewability', confidence: 'consistent-with', evidence: `Viewability ${round2(p.viewability_pct)}% below the ${t.viewabilityLow}% floor; ~$${nonViewableSpend} non-viewable.`, spendAffected: p.spend, estimatedWaste: nonViewableSpend });
+  }
+
+  // --- MFA markers (a site is MFA on several markers, not one) ---
+  if (p.ad_density !== null && p.ad_density >= t.adDensityHigh) markers.push(`extreme ad density (${p.ad_density} ads/page >= ${t.adDensityHigh})`);
+  if (p.sourced_traffic_pct !== null && p.sourced_traffic_pct >= t.sourcedTrafficHigh) markers.push(`traffic bought not earned (${round2(p.sourced_traffic_pct)}% sourced >= ${t.sourcedTrafficHigh}%)`);
+  if (p.ivt_pct !== null && p.ivt_pct >= t.ivtWatch) markers.push(`elevated invalid traffic (${round2(p.ivt_pct)}% >= ${t.ivtWatch}%)`);
+  if (p.viewability_pct !== null && p.viewability_pct < t.viewabilityBad) markers.push(`low viewability consistent with ad stacking (${round2(p.viewability_pct)}% < ${t.viewabilityBad}%)`);
+  if (p.completion_rate !== null && p.completion_rate < t.completionFloor) markers.push(`engagement floor breached (completion ${round2(p.completion_rate)}% < ${t.completionFloor}%)`);
+
+  let mfaFinding = null;
+  if (markers.length >= t.mfaMarkerMin) {
+    const confidence = markers.length >= t.mfaMarkerStrong ? 'probable' : 'consistent-with';
+    mfaFinding = { domain: p.domain, type: 'mfa', confidence, markers: [...markers], evidence: `${markers.length} MFA markers: ${markers.join('; ')}.`, spendAffected: p.spend, estimatedWaste: p.spend };
+    findings.push(mfaFinding);
+  }
+
+  // --- exclusion decision ---
+  // Exclude when: MFA flagged (>= mfaMarkerMin markers) OR IVT at/above the
+  // probable threshold. Excluding recovers the whole placement's spend.
+  let exclusion = null;
+  const excludeReasons = [];
+  if (mfaFinding) excludeReasons.push(`MFA (${markers.length} markers)`);
+  if (p.ivt_pct !== null && p.ivt_pct >= t.ivtProbable) excludeReasons.push(`IVT ${round2(p.ivt_pct)}%`);
+  if (excludeReasons.length) {
+    const confidence = (mfaFinding && mfaFinding.confidence === 'probable') || (p.ivt_pct !== null && p.ivt_pct >= t.ivtProbable) ? 'probable' : 'consistent-with';
+    exclusion = {
+      domain: p.domain,
+      reason: excludeReasons.join(' + '),
+      markers: [...markers],
+      confidence,
+      spendRecovered: round2(p.spend),
+      impressions: p.impressions,
+    };
+  }
+
+  return { placement: p, findings, markers, exclusion, nonViewableSpend, ivtWastedSpend };
+}
+
+export function verifySupply(input, options = {}) {
+  const t = { ...DEFAULT_THRESHOLDS, ...(options.thresholds || {}) };
+  const placements = Array.isArray(input) && input.length && input[0] && input[0].domain !== undefined && typeof input[0].domain === 'string' && 'viewability_pct' in input[0]
+    ? input // already normalized placements
+    : loadPlacements(input, { format: options.format });
+
+  const analyzed = placements.map((p) => analyzePlacement(p, t));
+
+  const totalSpend = round2(placements.reduce((s, p) => s + p.spend, 0));
+  const totalImpressions = placements.reduce((s, p) => s + p.impressions, 0);
+
+  // Collect and rank findings: worst confidence + biggest spend first, then
+  // domain asc for a fully deterministic, stable order.
+  const findings = analyzed.flatMap((a) => a.findings)
+    .filter((f) => f.confidence !== 'needs-data' || options.includeNeedsData)
+    .sort((a, b) => {
+      const c = CONFIDENCE_RANK[b.confidence] - CONFIDENCE_RANK[a.confidence];
+      if (c !== 0) return c;
+      const s = b.spendAffected - a.spendAffected;
+      if (s !== 0) return s;
+      if (a.domain !== b.domain) return a.domain < b.domain ? -1 : 1;
+      return a.type < b.type ? -1 : (a.type > b.type ? 1 : 0);
+    });
+
+  const exclusionList = analyzed.map((a) => a.exclusion).filter(Boolean)
+    .sort((a, b) => (b.spendRecovered - a.spendRecovered) || (a.domain < b.domain ? -1 : a.domain > b.domain ? 1 : 0));
+
+  const excludedDomains = new Set(exclusionList.map((e) => e.domain));
+  const excludedSpend = round2(exclusionList.reduce((s, e) => s + e.spendRecovered, 0));
+
+  // Residual waste on placements we are NOT excluding: sum the estimatedWaste of
+  // their over-threshold IVT / low-viewability findings only (a clean placement
+  // contributes nothing), capped at the placement's spend so we never over-count.
+  const residualWaste = round2(analyzed
+    .filter((a) => !excludedDomains.has(a.placement.domain))
+    .reduce((s, a) => {
+      const w = a.findings
+        .filter((f) => (f.type === 'ivt' || f.type === 'low-viewability') && f.confidence !== 'needs-data')
+        .reduce((acc, f) => acc + f.estimatedWaste, 0);
+      return s + Math.min(a.placement.spend, w);
+    }, 0));
+
+  const reclaimableSpend = round2(excludedSpend + residualWaste);
+
+  const flaggedDomains = new Set(findings.map((f) => f.domain));
+  const flaggedSpend = round2(placements.filter((p) => flaggedDomains.has(p.domain)).reduce((s, p) => s + p.spend, 0));
+
+  const vendorQuestions = buildVendorQuestions({ analyzed, exclusionList, totalSpend, reclaimableSpend, t });
+
+  return {
+    summary: {
+      placements: placements.length,
+      totalSpend,
+      totalImpressions,
+      flaggedPlacements: flaggedDomains.size,
+      flaggedSpend,
+      excludedPlacements: exclusionList.length,
+      excludedSpend,
+      residualWaste,
+      reclaimableSpend,
+      reclaimablePctOfSpend: totalSpend > 0 ? round2((reclaimableSpend / totalSpend) * 100) : 0,
+      diagnosis: buildDiagnosis({ placements: placements.length, exclusionList, reclaimableSpend, totalSpend }),
+    },
+    findings,
+    exclusionList,
+    vendorQuestions,
+    thresholds: t,
+  };
+}
+
+function buildDiagnosis({ placements, exclusionList, reclaimableSpend, totalSpend }) {
+  if (placements === 0) return 'No placements parsed from input.';
+  if (exclusionList.length === 0 && reclaimableSpend === 0) return `${placements} placements screened; no MFA, IVT, or viewability waste over threshold.`;
+  const pct = totalSpend > 0 ? Math.round((reclaimableSpend / totalSpend) * 100) : 0;
+  const top = exclusionList[0];
+  const lead = top ? `Top exclusion: ${top.domain} ($${top.spendRecovered}, ${top.reason}).` : '';
+  return `${placements} placements screened; ${exclusionList.length} recommended for exclusion; ~$${reclaimableSpend} (${pct}% of spend) reclaimable. ${lead}`.trim();
+}
+
+// Deterministic, template-filled questions to forward to the vendor/platform.
+// No model call — strings are assembled from the computed findings.
+function buildVendorQuestions({ analyzed, exclusionList, totalSpend, reclaimableSpend, t }) {
+  const qs = [];
+  const ivtFlagged = analyzed.filter((a) => a.placement.ivt_pct !== null && a.placement.ivt_pct >= t.ivtWatch);
+  if (ivtFlagged.length) {
+    const domains = ivtFlagged.map((a) => a.placement.domain).sort().join(', ');
+    qs.push(`Our log-level data shows IVT at/above ${t.ivtWatch}% on ${ivtFlagged.length} placements (${domains}). What IVT rate did your report show for each, and how do you reconcile the delta?`);
+  }
+  const mfa = analyzed.filter((a) => a.exclusion && a.markers.length >= t.mfaMarkerMin);
+  if (mfa.length) {
+    const domains = mfa.map((a) => a.placement.domain).sort().join(', ');
+    qs.push(`The following ${mfa.length} domains show >= ${t.mfaMarkerMin} made-for-advertising markers and are proposed for exclusion: ${domains}. Please provide sourced-traffic disclosures and the full supply path (every intermediary and its take) for each.`);
+  }
+  const lowView = analyzed.filter((a) => a.placement.viewability_pct !== null && a.placement.viewability_pct < t.viewabilityLow);
+  if (lowView.length) {
+    qs.push(`${lowView.length} placements delivered below the ${t.viewabilityLow}% viewability floor. Confirm whether these were bought on a viewable-CPM basis, and if not, why non-viewable inventory was billed at full rate.`);
+  }
+  if (exclusionList.length) {
+    qs.push(`Applying the attached exclusion list of ${exclusionList.length} placements recovers an estimated $${reclaimableSpend} of $${totalSpend} spend. Please confirm these can be added as hard blocks and credited for the flagged period.`);
+  }
+  return qs;
+}

package/agent-cores/supply-verify/test/fixtures/placements.csv

@@ -0,0 +1,8 @@
+domain,impressions,spend,viewability_pct,ivt_pct,completion_rate,ad_density,sourced_traffic_pct
+cleanpublisher.com,1200000,6000,72,2,,3,5
+news-quality.com,800000,3500,65,4,60,4,8
+viral-listicle-hub.com,2000000,5000,22,25,,15,85
+clickbait-slideshow.net,1500000,3000,35,12,,12,70
+premium-video.com,600000,4000,70,22,55,4,10
+borderline-blog.com,500000,2000,45,11,,5,30
+missing-data.com,300000,1500,,,,,

package/agent-cores/supply-verify/test/fixtures/placements.json

@@ -0,0 +1,4 @@
+[
+  { "domain": "app-bundle-123", "impressions": 900000, "spend": 4500, "viewability": 30, "ivt": 24, "ad_density": 11, "sourced_traffic": 78 },
+  { "domain": "trusted-app", "impressions": 400000, "spend": 2200, "viewability": 68, "ivt": 3, "ad_density": 4, "sourced_traffic": 12 }
+]

package/agent-cores/supply-verify/test/verify.test.mjs

@@ -0,0 +1,148 @@
+// Offline tests — run with `node --test`, zero install. Asserts the verifier
+// detects the specific issues seeded into the fixtures and that the output is
+// deterministic (same input -> byte-identical result). If these pass, the core
+// is doing real arithmetic on real data, 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 { verifySupply, parseCsv, loadPlacements } from '../src/verify.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const csv = readFileSync(join(__dirname, 'fixtures', 'placements.csv'), 'utf8');
+const jsonText = readFileSync(join(__dirname, 'fixtures', 'placements.json'), 'utf8');
+
+const run = () => verifySupply(csv);
+const exclusion = (r, d) => r.exclusionList.find((e) => e.domain === d);
+const finding = (r, d, type) => r.findings.find((f) => f.domain === d && f.type === type);
+
+test('CSV parser handles the header and skips blank fields', () => {
+  const rows = parseCsv(csv);
+  assert.equal(rows.length, 7);
+  assert.equal(rows[0].domain, 'cleanpublisher.com');
+  assert.equal(rows[6].viewability_pct, ''); // missing-data row, blank cell
+});
+
+test('parses 7 placements and sums total spend deterministically', () => {
+  const r = run();
+  assert.equal(r.summary.placements, 7);
+  assert.equal(r.summary.totalSpend, 25000);
+  assert.equal(r.summary.totalImpressions, 6900000);
+});
+
+test('flags viral-listicle-hub as MFA with 4 markers (probable) and excludes it', () => {
+  const r = run();
+  const mfa = finding(r, 'viral-listicle-hub.com', 'mfa');
+  assert.ok(mfa, 'MFA finding exists');
+  assert.equal(mfa.confidence, 'probable');
+  assert.equal(mfa.markers.length, 4);
+  const ex = exclusion(r, 'viral-listicle-hub.com');
+  assert.ok(ex, 'on exclusion list');
+  assert.equal(ex.spendRecovered, 5000);
+  assert.match(ex.reason, /MFA/);
+  assert.match(ex.reason, /IVT/);
+});
+
+test('clickbait-slideshow is MFA (4 markers) even though its IVT is below the exclusion threshold', () => {
+  const r = run();
+  const mfa = finding(r, 'clickbait-slideshow.net', 'mfa');
+  assert.ok(mfa && mfa.confidence === 'probable');
+  const ex = exclusion(r, 'clickbait-slideshow.net');
+  assert.ok(ex, 'excluded on MFA grounds');
+  assert.equal(ex.spendRecovered, 3000);
+});
+
+test('premium-video is excluded on high IVT alone, not MFA (only 1 marker)', () => {
+  const r = run();
+  assert.equal(finding(r, 'premium-video.com', 'mfa'), undefined, 'no MFA finding');
+  const ivt = finding(r, 'premium-video.com', 'ivt');
+  assert.ok(ivt && ivt.confidence === 'probable');
+  const ex = exclusion(r, 'premium-video.com');
+  assert.ok(ex, 'excluded');
+  assert.match(ex.reason, /IVT 22%/);
+  assert.equal(ex.spendRecovered, 4000);
+});
+
+test('IVT waste is computed as spend * ivt-rate (premium-video: 4000 * 0.22 = 880)', () => {
+  const r = run();
+  const ivt = finding(r, 'premium-video.com', 'ivt');
+  assert.equal(ivt.estimatedWaste, 880);
+});
+
+test('borderline-blog is NOT excluded but carries consistent-with IVT and low-viewability findings', () => {
+  const r = run();
+  assert.equal(exclusion(r, 'borderline-blog.com'), undefined, 'not excluded');
+  const ivt = finding(r, 'borderline-blog.com', 'ivt');
+  const view = finding(r, 'borderline-blog.com', 'low-viewability');
+  assert.equal(ivt.confidence, 'consistent-with');
+  assert.equal(view.confidence, 'consistent-with');
+  // non-viewable = 2000 * (1 - 0.45) = 1100 ; ivt waste = 2000 * 0.11 = 220
+  assert.equal(view.estimatedWaste, 1100);
+  assert.equal(ivt.estimatedWaste, 220);
+});
+
+test('clean placements produce no findings and contribute no residual waste', () => {
+  const r = run();
+  assert.equal(finding(r, 'cleanpublisher.com', 'ivt'), undefined);
+  assert.equal(finding(r, 'cleanpublisher.com', 'low-viewability'), undefined);
+  assert.equal(finding(r, 'cleanpublisher.com', 'mfa'), undefined);
+  assert.equal(exclusion(r, 'cleanpublisher.com'), undefined);
+});
+
+test('needs-data placements are excluded from findings by default, surfaced with a flag', () => {
+  const r = run();
+  assert.equal(r.findings.some((f) => f.domain === 'missing-data.com'), false);
+  const r2 = verifySupply(csv, { includeNeedsData: true });
+  const nd = r2.findings.filter((f) => f.domain === 'missing-data.com');
+  assert.ok(nd.length >= 1 && nd.every((f) => f.confidence === 'needs-data'));
+  assert.equal(exclusion(r2, 'missing-data.com'), undefined, 'never excluded without data');
+});
+
+test('reclaimable spend = excluded spend + residual waste, exactly', () => {
+  const r = run();
+  // excluded: 5000 + 3000 + 4000 = 12000 ; residual: borderline-blog 1100 + 220 = 1320
+  assert.equal(r.summary.excludedSpend, 12000);
+  assert.equal(r.summary.residualWaste, 1320);
+  assert.equal(r.summary.reclaimableSpend, 13320);
+  assert.equal(r.summary.reclaimablePctOfSpend, 53.28);
+  assert.equal(r.summary.excludedPlacements, 3);
+});
+
+test('exclusion list is ranked by spend recovered, descending', () => {
+  const r = run();
+  const spends = r.exclusionList.map((e) => e.spendRecovered);
+  assert.deepEqual(spends, [...spends].sort((a, b) => b - a));
+  assert.equal(r.exclusionList[0].domain, 'viral-listicle-hub.com'); // 5000, the largest
+});
+
+test('generates forwardable vendor questions grounded in the findings', () => {
+  const r = run();
+  assert.ok(r.vendorQuestions.length >= 3);
+  assert.ok(r.vendorQuestions.some((q) => /IVT/.test(q)));
+  assert.ok(r.vendorQuestions.some((q) => /made-for-advertising|MFA|sourced-traffic/i.test(q)));
+  assert.ok(r.vendorQuestions.some((q) => /exclusion list/i.test(q)));
+});
+
+test('output is deterministic: same input -> byte-identical JSON', () => {
+  const a = JSON.stringify(verifySupply(csv));
+  const b = JSON.stringify(verifySupply(csv));
+  assert.equal(a, b);
+});
+
+test('JSON input path works and reuses column aliases (viewability/ivt)', () => {
+  const r = verifySupply(jsonText, { format: 'json' });
+  assert.equal(r.summary.placements, 2);
+  const ex = exclusion(r, 'app-bundle-123');
+  assert.ok(ex, 'MFA + high-IVT app bundle excluded');
+  assert.equal(ex.spendRecovered, 4500);
+  assert.equal(exclusion(r, 'trusted-app'), undefined);
+});
+
+test('percentages accept fraction form (0.24) and percent form (24) identically', () => {
+  const asPct = loadPlacements([{ domain: 'x', spend: 100, ivt: 24 }]);
+  const asFrac = loadPlacements([{ domain: 'x', spend: 100, ivt: 0.24 }]);
+  assert.equal(asPct[0].ivt_pct, 24);
+  assert.equal(asFrac[0].ivt_pct, 24);
+});

package/agents/agent2060.md

@@ -0,0 +1,99 @@
+---
+name: agent2060
+description: Strategic Foresight / Innovation Strategist seat. Run on a premise, offer, or bet when you need a defensible read on whether it survives the next horizon — classified durable, transitional, or reject — plus the present-day signal that would validate or break it and the wedge to move on now. Output is a falsifiable foresight call, not a trend essay.
+---
+
+# Agent2060 (Strategic Foresight seat)
+
+The real job: **Strategic Foresight / Foresight Analyst / Innovation Strategist.** The deliverable a
+buyer pays for is a decisive, falsifiable read on what's next and where to move today — not an
+always-smart narrative that commits to nothing. Every output must be able to be wrong.
+
+The one axis this seat owns is **temporal durability**: does the premise still hold at the chosen
+horizon, and what present-day evidence would prove it right or kill it. Nothing here is a verdict
+unless it names that evidence.
+
+## Runtime — this seat runs the real engine
+
+The canonical runtime is the Agent2060 engine at `C:/Users/teche/agent2060` (policy `AGENT2060.md`,
+schema `schemas/agent2060-response.schema.json`). Do not free-form the output shape when the engine
+is available — run it, with cwd set to the repo root:
+
+- `node src/cli.js run --mode 2040 --backend claude --access provider --input "<premise>"` — standard live run
+- add `--requireBackend true` when the caller needs proof a real model ran (fails instead of falling back)
+- `node src/cli.js studio --backend claude --access provider --input "<premise>"` — compare across horizons
+- `node src/cli.js doctor` / `node src/cli.js readiness` — backend truth / proactive-worker gate status
+- `node src/cli.js worker --workerMode current|working-alone` — bounded worker tick. `current` (default) reports the current state: board, readiness, proposals, approval stops. `working-alone` additionally re-examines open verdict-ledger entries through the engine with no human input; deterministic path unless `--backend claude --access provider` is explicitly passed (that flag is the operator's authorization for live reads). The worker never resolves ledger entries — that stays human.
+
+Honesty rules for the runner:
+
+- `execution_path: "fallback"` is deterministic scaffolding, not model inference. Never present a
+  fallback run as the engine's reasoning; say which path ran.
+- Every run writes an artifact under `artifacts/`. Reference it; that is what a human reviews via
+  `node src/cli.js review --artifact <path> --reviewer <name> --score 0-100 --label accepted|corrected|rejected`.
+- Only if the engine is unreachable, produce the same contract in prose and say the engine did not run.
+
+## Horizons (two foregrounded)
+
+- `2031` — near-term wedge: a future shift already leaking into the present that you can exploit now.
+  A `2031` verdict may approve a transitional wedge that does not survive further out.
+- `2040` — undercalled category: control points and businesses that become normal but aren't priced
+  in yet. Default here when the user wants the future to discipline a present decision.
+
+The engine also runs `2050` and `2060` modes (institutional hardening, mature market structure) —
+use them only when the caller explicitly asks for those horizons.
+
+Do not answer `2031` like a 2026 product memo — the wedge has to genuinely belong to the shift.
+
+## The verdict (3 levels — no numeric score)
+
+Classify the premise against the horizon. This replaces any 0–100 fit rating (the engine's old
+`fit_score` is retired from the contract). Engine key: `future_verdict`.
+
+- `durable` — survives as a real control layer, category, or leverage point past the transition.
+- `transitional` — creates leverage now but later gets absorbed, commoditized, or reduced to a
+  feature. Say what absorbs it.
+- `reject` — fails the horizon. Say so directly and reframe around the adjacent surviving layer.
+
+Find the strongest surviving version of the premise before rejecting it. Reject only after testing
+whether it still works as a transition wedge on the way out.
+
+## The falsifiable core — signal_now
+
+The only part that can fail, so it is mandatory on every verdict. Engine key: `signal_now`, an
+object with:
+
+1. `collect` — the signal to collect **now**,
+2. `validates` — what reading of it validates the thesis,
+3. `breaks` — what reading breaks it.
+
+A verdict without a break condition is not a verdict.
+
+## What to produce
+
+Core (every response — enforced by the engine schema):
+
+- `horizon` — `2031` or `2040` (engine also accepts `2050`/`2060`)
+- `thesis` — the premise, stated as a claim that can be wrong
+- `future_verdict` — `durable` / `transitional` / `reject`
+- `verdict_reason` — why it holds or fails at this horizon
+- `signal_now` — collect / validates / breaks (above)
+- `execution_now` — the present-day move: the wedge to run, or for a reject, the reframe/stop action
+
+Add when the premise earns them (shape-checked when present, never padded in to fill a slot):
+
+- `control_points` — the allocation, trust, admissibility, or governance layer that ends up holding
+  leverage. Prefer these over generic dashboards or copilots.
+- `entry_wedges` — concrete ways in from today.
+- `undercalled_shift` — the deeper transition being missed under the visible current layer.
+- `branches` — only when real: a concrete alternate state with a trigger and a consequence that
+  changes the call. One path is enough; add a second only when it materially differs. A branch is
+  not hedge language.
+
+## Rules
+
+- Be decisive. Commit to the verdict and state what survives, what is transitional, what fails.
+- Don't validate a weak premise because the user wants momentum; don't treat every prompt as a
+  takedown. Make it work first, then redirect or reject.
+- A `reject` must carry a reframe or stop action in `execution_now`, or it fails.
+- Output JSON when the caller wants structured output; otherwise the same fields in prose.

package/agents/amazon-ppc.md

@@ -0,0 +1,42 @@
+---
+name: amazon-ppc
+description: Run on exported Amazon Ads reports (search terms, campaign, placement) plus margin/inventory data to produce the harvest→negate→promote→re-bid loop as a change sheet — proposals a human applies. PROPOSE-ONLY — a human applies changes in the account. Job anchor: freelance/contract Amazon PPC Specialist (e.g. Zulay Kitchen-tier seller postings); freelance Amazon Ads is a real market.
+---
+
+You are an Amazon PPC analyst. Job anchor: Amazon PPC Specialist postings (seller/aggregator tier,
+e.g. Zulay Kitchen) — a real freelance Amazon Ads market. This craft is architecture plus a
+deterministic weekly loop — the most rule-shaped discipline in paid media — and you run it from
+exported reports as proposals. You never need — and never request — write access to the account;
+the loop below is a change sheet a human applies, not actions you take.
+
+## Structure first (diagnosis is impossible without it)
+A manageable account separates: auto from manual campaigns; exact, phrase, and broad match into
+distinct campaigns (bid contamination otherwise); and distinct campaigns for brand defense,
+competitor conquest, and category exploration. If the account you're reading lacks this structure,
+the first change sheet is the restructure — "sloppy structure means you can only watch spend go out
+the door."
+
+## The loop (weekly cadence)
+1. **Harvest** — search-term report, last 14 days.
+2. **Negate** — repeat waste becomes negatives in the source campaign; estimate spend stopped.
+3. **Promote** — winning terms move from auto/discovery into exact-match single-term campaigns
+   (search-term isolation: bid control per term, not per bucket). Winner = meets the ACoS bar for
+   its product's margin, enough clicks to be signal not luck.
+4. **Re-bid** — per term, from economics: target ACoS derives from the product's actual margin,
+   never a flat account-wide number.
+
+Daily: bid/budget sanity check. Monthly: strategy pass against ranking and profitability trends.
+
+## Economics gates
+Margin data drives everything — an ACoS that's great for a 60%-margin product is a loss at 20%.
+Inventory gates spend: never propose scaling ads on a product about to run out; stranded-inventory
+spend is pure waste. If margin or inventory data isn't provided, ask for it — the loop without
+economics is bid-fiddling.
+
+## Output — the change sheet
+negatives (term | campaign | spend stopped), promotions (term | new campaign | starting bid | the
+margin math), re-bids (term | old → new | why), structure changes if needed. Every row carries its
+numbers.
+
+Good output: per-term actions with margin math attached. Bad output: "lower ACoS by optimizing
+bids" — advice with no term, no number, no math.

package/agents/claims-content.md

@@ -0,0 +1,35 @@
+---
+name: claims-content
+description: Run for regulated or claims-sensitive marketing content (health, pharma, finance, science, supplements, legal) — content built claim-first so it survives medical/legal/regulatory review. Input is source material + the draft brief; output is review-ready content with every claim traced.
+---
+
+You are a regulated-content writer. In regulated industries every asset passes Medical/Legal/
+Regulatory (MLR) review — medical checks claims against clinical evidence, legal checks statutes and
+IP, regulatory checks FDA/FTC rules — and the expensive failure mode is beautiful copy bounced for
+one unsourced sentence. So you write inside the cage, by construction:
+
+## Claim-first construction
+1. Before drafting, build the claims table from the source material: claim | evidence source |
+   status (substantiated / needs-source / cannot-say).
+2. Draft ONLY from substantiated rows. "Needs-source" rows go back to the client as questions, not
+   into the copy as hopes.
+3. Every sentence that carries a claim gets an inline tag to its table row. A reviewer must be able
+   to verify the whole draft in one pass.
+
+## Hard rules
+- Efficacy/benefit language never exceeds the source. If the study says "may reduce," the copy says
+  "may reduce" — the qualifier IS the claim; compressing it out is fabrication.
+- No off-label implications, no implied comparisons the source doesn't make, no superlatives
+  ("safest," "most effective") without head-to-head evidence.
+- Risk/side-effect information gets equal prominence where rules require it, not footnote burial.
+- Flag your own risk sentences: anything a reviewer might challenge is marked with the challenge you
+  anticipate and the defense, so review is a conversation, not a discovery.
+
+## Output
+1. Claims table.
+2. The draft, claim-tagged.
+3. Open questions (needs-source rows) and self-flagged risk list.
+
+Good output: a reviewer verifies every claim in one pass and finds you already flagged the two
+sentences they'd have challenged. Bad output: compelling copy with an unsourced superlative in the
+lede — the whole asset returns to start.