weftens 0.0.1 → 0.1.0

package/agent-cores/amazon-ppc/test/fixtures/search-term-report.json

@@ -0,0 +1,5 @@
+[
+  { "Customer Search Term": "garlic press", "Campaign Name": "Auto - Garlic Press", "Match Type": "auto", "Impressions": 5000, "Clicks": 40, "Spend": 20.0, "7 Day Total Sales": 0, "7 Day Total Orders (#)": 0 },
+  { "Customer Search Term": "stainless garlic press", "Campaign Name": "Auto - Garlic Press", "Match Type": "auto", "Impressions": 3200, "Clicks": 30, "Spend": 15.0, "7 Day Total Sales": 120.0, "7 Day Total Orders (#)": 8 },
+  { "Customer Search Term": "professional garlic press", "Campaign Name": "Exact - Pro Press", "Match Type": "exact", "Impressions": 6000, "Clicks": 50, "Spend": 10.0, "7 Day Total Sales": 200.0, "7 Day Total Orders (#)": 15 }
+]

package/agent-cores/amazon-ppc/test/optimize.test.mjs

@@ -0,0 +1,161 @@
+// Offline tests — run with `node --test`, zero install. Asserts the optimizer
+// computes real, specific proposals from a known search-term report with seeded
+// issues. If these pass, the core is doing deterministic arithmetic, not echoing.
+
+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 { optimize } from '../src/optimize.mjs';
+import { normalizeRows, parseDelimited } from '../src/parse.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const csv = readFileSync(join(__dirname, 'fixtures', 'search-term-report.csv'), 'utf8');
+const jsonText = readFileSync(join(__dirname, 'fixtures', 'search-term-report.json'), 'utf8');
+
+const CFG = { targetAcos: 25, margin: 35 };
+const run = () => optimize(csv, CFG);
+const findNeg = (r, term) => r.negatives.find((n) => n.term === term);
+const findPromo = (r, term) => r.promotions.find((p) => p.term === term);
+const findRebid = (r, term) => r.rebids.find((b) => b.term === term);
+
+test('CSV parser strips $/%/commas and normalizes messy Amazon headers', () => {
+  const rows = normalizeRows(csv);
+  assert.equal(rows.length, 7);
+  const r = rows.find((x) => x.searchTerm === 'garlic mincer tool');
+  assert.equal(r.spend, 22.0);
+  assert.equal(r.sales, 40.0);
+  assert.equal(r.orders, 2);
+  assert.equal(r.clicks, 25);
+  assert.equal(r.cpc, 0.88);
+});
+
+test('CSV tokenizer handles a quoted field containing a comma', () => {
+  const rows = parseDelimited('a,b\n"hello, world",2\n');
+  assert.deepEqual(rows[1], ['hello, world', '2']);
+});
+
+test('negates zero-order waste terms and estimates spend stopped', () => {
+  const r = run();
+  assert.equal(r.negatives.length, 2);
+  const gp = findNeg(r, 'garlic press');
+  assert.ok(gp, 'garlic press negated');
+  assert.equal(gp.spendStopped, 20.0);
+  assert.match(gp.reason, /40 clicks, 0 orders/);
+  assert.ok(findNeg(r, 'cheap kitchen gadget'), '12-click zero-order term negated');
+  assert.equal(r.summary.estSpendStopped, 26.5);
+});
+
+test('does NOT negate a low-signal term (3 clicks, $1.50, 0 orders) — it holds', () => {
+  const r = run();
+  assert.equal(findNeg(r, 'garlic'), undefined);
+  const held = r.held.find((h) => h.term === 'garlic');
+  assert.ok(held && held.action === 'hold', 'low-signal term held, not negated');
+});
+
+test('promotes converting non-exact winners with the margin math attached', () => {
+  const r = run();
+  assert.equal(r.promotions.length, 2);
+  const p = findPromo(r, 'stainless garlic press');
+  assert.ok(p, 'winner promoted');
+  assert.equal(p.newMatchType, 'exact');
+  assert.equal(p.acos, 12.5);
+  // rev/click $4.00 * 25% target = $1.00 ideal, capped to 1.5x CPC($0.50) = $0.75
+  assert.equal(p.startingBid, 0.75);
+  assert.equal(p.capped, true);
+  assert.equal(p.negateInSource, true);
+  assert.match(p.marginMath, /\$4 rev\/click x 25% target ACOS = \$1 ideal bid/);
+});
+
+test('promotions are ranked by sales (biggest winner first)', () => {
+  const r = run();
+  assert.equal(r.promotions[0].term, 'stainless garlic press'); // $120
+  assert.equal(r.promotions[1].term, 'rocker garlic press'); // $90
+});
+
+test('does NOT promote a high-ACOS term (55% > 25% target) — it re-bids down', () => {
+  const r = run();
+  assert.equal(findPromo(r, 'garlic mincer tool'), undefined);
+  const b = findRebid(r, 'garlic mincer tool');
+  assert.ok(b, 'high-ACOS converting term re-bid instead of promoted');
+  assert.equal(b.direction, 'down');
+});
+
+test('re-bids DOWN an overpaying term, capped at -50%, flagged as losing vs break-even', () => {
+  const r = run();
+  const b = findRebid(r, 'garlic mincer tool');
+  assert.equal(b.oldBid, 0.88);
+  // ideal $0.40 but -50% cut floor is $0.44 -> capped
+  assert.equal(b.newBid, 0.44);
+  assert.equal(b.capped, true);
+  assert.match(b.why, /losing: ACOS above 35% break-even/);
+});
+
+test('re-bids UP an underpriced converter, capped at +100%', () => {
+  const r = run();
+  const b = findRebid(r, 'professional garlic press');
+  assert.ok(b && b.direction === 'up');
+  assert.equal(b.oldBid, 0.2);
+  // ideal $1.00 but +100% ceiling is $0.40 -> capped
+  assert.equal(b.newBid, 0.4);
+  assert.equal(b.capped, true);
+  assert.equal(b.changePct, 100);
+});
+
+test('re-bids ranked by magnitude of change', () => {
+  const r = run();
+  assert.equal(r.rebids[0].term, 'professional garlic press'); // +100%
+  assert.equal(r.rebids[1].term, 'garlic mincer tool'); // -50%
+});
+
+test('computes correct account totals and blended ACOS', () => {
+  const r = run();
+  assert.equal(r.totals.terms, 7);
+  assert.equal(r.totals.clicks, 178);
+  assert.equal(r.totals.spend, 84.0);
+  assert.equal(r.totals.sales, 450.0);
+  assert.equal(r.totals.orders, 30);
+  assert.equal(r.totals.acos, 18.67); // 84/450
+});
+
+test('inventory gate suppresses scaling on a low-inventory campaign', () => {
+  const r = optimize(csv, { ...CFG, lowInventoryCampaigns: ['Auto - Garlic Press'] });
+  // stainless + rocker garlic press were promotions from that auto campaign
+  assert.equal(findPromo(r, 'stainless garlic press'), undefined);
+  assert.equal(findPromo(r, 'rocker garlic press'), undefined);
+  const held = r.held.find((h) => h.term === 'stainless garlic press');
+  assert.ok(held && held.action === 'promote-suppressed', 'promotion suppressed by inventory gate');
+  assert.match(held.reason, /low inventory/);
+  // negatives from the same campaign still fire (a stock-out does not un-waste spend)
+  assert.ok(findNeg(r, 'garlic press'), 'negatives unaffected by inventory gate');
+});
+
+test('margin-only config sets target below break-even (0.75 x margin)', () => {
+  const r = optimize(csv, { margin: 40 }); // no explicit targetAcos
+  assert.equal(r.config.margin, 40);
+  assert.equal(r.config.targetAcos, 30); // 40 * 0.75
+  assert.equal(r.config.breakEvenAcos, 40);
+});
+
+test('deterministic: same input -> byte-identical output', () => {
+  const a = JSON.stringify(optimize(csv, CFG));
+  const b = JSON.stringify(optimize(csv, CFG));
+  assert.equal(a, b);
+});
+
+test('JSON report input parses through the same path as CSV', () => {
+  const r = optimize(jsonText, CFG);
+  assert.equal(r.totals.terms, 3);
+  assert.ok(findNeg(r, 'garlic press'));
+  assert.ok(findPromo(r, 'stainless garlic press'));
+  assert.ok(findRebid(r, 'professional garlic press'));
+});
+
+test('every proposal is propose-only and carries its numbers', () => {
+  const r = run();
+  for (const n of r.negatives) assert.ok(typeof n.spendStopped === 'number' && n.reason);
+  for (const p of r.promotions) assert.ok(typeof p.startingBid === 'number' && p.marginMath);
+  for (const b of r.rebids) assert.ok(b.oldBid >= 0 && b.newBid >= 0 && b.why);
+  assert.match(r.summary.headline, /PROPOSE-ONLY/);
+});

package/agent-cores/content-ops/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@agent-cores/content-ops",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Content-operations engine. Deterministic: parse a CMS export, compute keep/update/retire decisions with evidence, metadata gaps, and migration-readiness QA. No LLM in the core.",
+  "bin": {
+    "content-ops": "src/cli.mjs"
+  },
+  "scripts": {
+    "test": "node --test",
+    "inventory": "node src/cli.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/agent-cores/content-ops/src/cli.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+// Real CLI.
+//   content-ops <file.csv|file.json> [--asof YYYY-MM-DD] [--pretty]
+// Reads a CMS export from disk, computes the inventory, prints JSON to stdout
+// (machine-readable) and a one-line summary to stderr.
+
+import { readFileSync } from 'node:fs';
+import { inventoryFromText } from './inventory.mjs';
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--asof') args.asof = argv[++i];
+    else if (a === '--pretty') args.pretty = true;
+    else if (a === '--csv') args.hint = 'csv';
+    else if (a === '--json') args.hint = 'json';
+    else args._.push(a);
+  }
+  return args;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const file = args._[0];
+  if (!file) {
+    console.error('Usage: content-ops <file.csv|file.json> [--asof YYYY-MM-DD] [--pretty]');
+    process.exitCode = 1;
+    return;
+  }
+
+  const hint = args.hint ?? (file.toLowerCase().endsWith('.json') ? 'json' : file.toLowerCase().endsWith('.csv') ? 'csv' : null);
+  const text = readFileSync(file, 'utf8');
+  const result = inventoryFromText(text, hint, { asOf: args.asof });
+
+  const c = result.counts;
+  const m = result.migrationReadiness;
+  console.error(
+    `content-ops: ${c.total} URLs (asOf ${result.asOf}) — ` +
+      `keep ${c.keep} / update ${c.update} / retire ${c.retire} / review ${c.review} — ` +
+      `${m.redirectsRequired} redirect(s) needed, readiness ${m.readinessScore}/100`,
+  );
+  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/content-ops/src/inventory.mjs

@@ -0,0 +1,343 @@
+// Deterministic content-operations engine. No LLM.
+//
+// Input: rows from a CMS export (url, title, published date, last-updated,
+// word count, pageviews, meta description). Output: a per-URL inventory with a
+// keep / update / retire decision and the evidence for it, a metadata-gap list,
+// and a migration-readiness QA summary.
+//
+// Every decision is a pure function of the row's numbers against fixed thresholds,
+// plus a fixed asOf date (defaults to the latest date in the export, so results
+// never depend on the wall clock — same input always yields the same output).
+
+import { parseExport } from './parse.mjs';
+
+export const DEFAULT_THRESHOLDS = Object.freeze({
+  staleDays: 365,        // not touched in a year → aging
+  veryStaleDays: 730,    // not touched in two years → decayed
+  lowTrafficViews: 50,   // at or below this over the reporting window → low value
+  highTrafficViews: 500, // at or above this → protect it, never retire
+  thinWords: 300,        // below this → thin content (ROT candidate)
+  titleMin: 10,
+  titleMax: 65,
+  descMin: 50,
+  descMax: 160,
+});
+
+// --- field normalization: map an export's own headers onto the canonical schema ---
+
+const FIELD_ALIASES = {
+  url: ['url', 'link', 'address', 'page', 'permalink', 'loc'],
+  title: ['title', 'page title', 'name', 'heading', 'h1'],
+  published: ['published', 'published date', 'publish date', 'publishdate', 'published_date', 'date', 'created', 'created date', 'first published'],
+  updated: ['updated', 'last updated', 'last-updated', 'lastupdated', 'last_updated', 'modified', 'last modified', 'lastmod', 'updated date'],
+  wordCount: ['word count', 'wordcount', 'words', 'word_count', 'length'],
+  pageviews: ['pageviews', 'page views', 'views', 'traffic', 'sessions', 'visits', 'page_views'],
+  metaDescription: ['meta description', 'metadescription', 'meta_description', 'description', 'meta desc', 'seo description', 'excerpt'],
+};
+
+function buildHeaderMap(sampleRow) {
+  const map = {};
+  const keys = Object.keys(sampleRow);
+  const lowered = keys.map((k) => k.trim().toLowerCase());
+  for (const [canonical, aliases] of Object.entries(FIELD_ALIASES)) {
+    for (const alias of aliases) {
+      const idx = lowered.indexOf(alias);
+      if (idx !== -1) {
+        map[canonical] = keys[idx];
+        break;
+      }
+    }
+  }
+  return map;
+}
+
+function toNumber(v) {
+  if (v === null || v === undefined) return null;
+  const s = String(v).trim().replace(/,/g, '');
+  if (s === '') return null;
+  const n = Number(s);
+  return Number.isFinite(n) ? n : null;
+}
+
+// Parse a date to a UTC-midnight epoch (ms). Accepts YYYY-MM-DD and anything
+// Date can parse; returns null on failure so "missing" is distinguishable from 0.
+function toDateMs(v) {
+  if (v === null || v === undefined) return null;
+  const s = String(v).trim();
+  if (s === '') return null;
+  const iso = /^(\d{4})-(\d{2})-(\d{2})/.exec(s);
+  if (iso) {
+    return Date.UTC(Number(iso[1]), Number(iso[2]) - 1, Number(iso[3]));
+  }
+  const t = Date.parse(s);
+  return Number.isNaN(t) ? null : t;
+}
+
+const DAY = 86_400_000;
+const daysBetween = (aMs, bMs) => Math.round((aMs - bMs) / DAY);
+
+function cleanStr(v) {
+  if (v === null || v === undefined) return '';
+  return String(v).trim();
+}
+
+// --- the decision core ---
+
+function decide(item, asOfMs, T) {
+  const reasons = [];
+  const { pageviews, updatedMs, publishedMs, wordCount } = item;
+
+  // freshness is measured from last-update when present, else from publish
+  const freshMs = updatedMs ?? publishedMs;
+  const staleDays = freshMs !== null ? daysBetween(asOfMs, freshMs) : null;
+
+  const hasTraffic = pageviews !== null;
+  const hasFresh = staleDays !== null;
+
+  // If we can't judge value or freshness, we don't guess — we route to review.
+  if (!hasTraffic || !hasFresh) {
+    const missing = [];
+    if (!hasTraffic) missing.push('pageviews');
+    if (!hasFresh) missing.push('published/updated date');
+    reasons.push(`insufficient evidence to auto-decide (missing ${missing.join(' and ')})`);
+    return { decision: 'review', reasons, staleDays, confidence: 'low' };
+  }
+
+  const views = pageviews;
+  const words = wordCount; // may be null; only used in ROT branch guarded below
+
+  // 1) Protect valuable pages: high traffic is never retired.
+  if (views >= T.highTrafficViews) {
+    if (staleDays >= T.staleDays) {
+      reasons.push(`high traffic (${views} views) but not updated in ${staleDays} days → refresh, do not retire`);
+      return { decision: 'update', reasons, staleDays, confidence: 'high' };
+    }
+    reasons.push(`high traffic (${views} views) and fresh (updated ${staleDays} days ago)`);
+    return { decision: 'keep', reasons, staleDays, confidence: 'high' };
+  }
+
+  // 2) Low traffic: candidates for retirement or refresh.
+  if (views <= T.lowTrafficViews) {
+    if (staleDays >= T.veryStaleDays) {
+      reasons.push(`stale (${staleDays} days without update) and low traffic (${views} views) → ROT, retire with redirect`);
+      return { decision: 'retire', reasons, staleDays, confidence: 'high' };
+    }
+    if (words !== null && words < T.thinWords) {
+      reasons.push(`thin content (${words} words) and low traffic (${views} views) → ROT, retire with redirect`);
+      return { decision: 'retire', reasons, staleDays, confidence: 'medium' };
+    }
+    if (staleDays >= T.staleDays) {
+      reasons.push(`low traffic (${views} views) and aging (${staleDays} days) but not yet ROT → refresh and reassess`);
+      return { decision: 'update', reasons, staleDays, confidence: 'medium' };
+    }
+    reasons.push(`low traffic (${views} views) but recent (${staleDays} days) → keep and monitor`);
+    return { decision: 'keep', reasons, staleDays, confidence: 'low' };
+  }
+
+  // 3) Mid traffic: keep unless it has decayed past very-stale.
+  if (staleDays >= T.veryStaleDays) {
+    reasons.push(`moderate traffic (${views} views) but decayed (${staleDays} days without update) → refresh`);
+    return { decision: 'update', reasons, staleDays, confidence: 'medium' };
+  }
+  reasons.push(`moderate traffic (${views} views) and acceptable freshness (${staleDays} days)`);
+  return { decision: 'keep', reasons, staleDays, confidence: 'medium' };
+}
+
+// --- metadata gap checks (mechanical, per item) ---
+
+function metadataGaps(item, T) {
+  const gaps = [];
+  if (item.title === '') gaps.push({ field: 'title', issue: 'missing', severity: 'fail' });
+  else if (item.title.length < T.titleMin) gaps.push({ field: 'title', issue: `too short (${item.title.length} chars, aim ${T.titleMin}-${T.titleMax})`, severity: 'warn' });
+  else if (item.title.length > T.titleMax) gaps.push({ field: 'title', issue: `too long (${item.title.length} chars, aim ${T.titleMin}-${T.titleMax})`, severity: 'warn' });
+
+  if (item.metaDescription === '') gaps.push({ field: 'metaDescription', issue: 'missing', severity: 'warn' });
+  else if (item.metaDescription.length < T.descMin) gaps.push({ field: 'metaDescription', issue: `too short (${item.metaDescription.length} chars, aim ${T.descMin}-${T.descMax})`, severity: 'warn' });
+  else if (item.metaDescription.length > T.descMax) gaps.push({ field: 'metaDescription', issue: `too long (${item.metaDescription.length} chars, aim ${T.descMin}-${T.descMax})`, severity: 'warn' });
+
+  if (item.url === '') gaps.push({ field: 'url', issue: 'missing', severity: 'fail' });
+
+  // data-completeness gaps that block an evidence-based decision
+  if (item.publishedMs === null && item.updatedMs === null) gaps.push({ field: 'date', issue: 'no published or updated date', severity: 'fail' });
+  if (item.pageviews === null) gaps.push({ field: 'pageviews', issue: 'missing traffic data', severity: 'warn' });
+  if (item.wordCount === null) gaps.push({ field: 'wordCount', issue: 'missing word count', severity: 'info' });
+
+  return gaps;
+}
+
+// --- main entry ---
+
+export function buildInventory(rows, options = {}) {
+  const T = { ...DEFAULT_THRESHOLDS, ...(options.thresholds || {}) };
+  const arr = Array.isArray(rows) ? rows : [];
+
+  if (arr.length === 0) {
+    return {
+      asOf: options.asOf ?? null,
+      thresholds: T,
+      counts: { total: 0, keep: 0, update: 0, retire: 0, review: 0 },
+      unmappedFields: [],
+      headerMap: {},
+      items: [],
+      metadataGaps: [],
+      duplicates: { titles: [], urls: [] },
+      migrationReadiness: {
+        totalUrls: 0,
+        redirectsRequired: 0,
+        redirectLedger: [],
+        itemsWithGaps: 0,
+        blockingGaps: 0,
+        fieldCoverage: {},
+        readinessScore: 0,
+        blockers: ['export is empty — nothing to inventory'],
+      },
+    };
+  }
+
+  const headerMap = buildHeaderMap(arr[0]);
+
+  // normalize each row to the canonical schema
+  const normalized = arr.map((raw, idx) => {
+    const g = (canonical) => (headerMap[canonical] !== undefined ? raw[headerMap[canonical]] : undefined);
+    return {
+      rowIndex: idx,
+      url: cleanStr(g('url')),
+      title: cleanStr(g('title')),
+      metaDescription: cleanStr(g('metaDescription')),
+      publishedMs: toDateMs(g('published')),
+      updatedMs: toDateMs(g('updated')),
+      wordCount: toNumber(g('wordCount')),
+      pageviews: toNumber(g('pageviews')),
+    };
+  });
+
+  // asOf: explicit option, else the latest date seen anywhere in the export.
+  let asOfMs = options.asOf ? toDateMs(options.asOf) : null;
+  if (asOfMs === null) {
+    for (const it of normalized) {
+      for (const ms of [it.publishedMs, it.updatedMs]) {
+        if (ms !== null && (asOfMs === null || ms > asOfMs)) asOfMs = ms;
+      }
+    }
+  }
+  if (asOfMs === null) asOfMs = Date.UTC(1970, 0, 1); // no dates at all; decisions will route to review
+
+  // duplicate detection (a taxonomy/QA signal migrations must resolve)
+  const titleIndex = new Map();
+  const urlIndex = new Map();
+  for (const it of normalized) {
+    if (it.title) {
+      const k = it.title.toLowerCase();
+      (titleIndex.get(k) || titleIndex.set(k, []).get(k)).push(it.url || `(row ${it.rowIndex})`);
+    }
+    if (it.url) {
+      const k = it.url.toLowerCase();
+      (urlIndex.get(k) || urlIndex.set(k, []).get(k)).push(it.rowIndex);
+    }
+  }
+  const dupTitles = [...titleIndex.entries()].filter(([, v]) => v.length > 1).map(([title, urls]) => ({ title, count: urls.length, urls }));
+  const dupUrls = [...urlIndex.entries()].filter(([, v]) => v.length > 1).map(([url, rows2]) => ({ url, count: rows2.length, rows: rows2 }));
+
+  // per-item decision + gaps
+  const items = normalized.map((it) => {
+    const { decision, reasons, staleDays, confidence } = decide(it, asOfMs, T);
+    const gaps = metadataGaps(it, T);
+    return {
+      url: it.url,
+      title: it.title,
+      decision,
+      confidence,
+      reasons,
+      staleDays,
+      pageviews: it.pageviews,
+      wordCount: it.wordCount,
+      metadataGaps: gaps,
+      redirectTarget: decision === 'retire' ? null : undefined, // null = decision needed, not omission
+    };
+  });
+
+  const counts = { total: items.length, keep: 0, update: 0, retire: 0, review: 0 };
+  for (const it of items) counts[it.decision] += 1;
+
+  // flat metadata-gap list for quick triage, ordered fail → warn → info
+  const sevOrder = { fail: 0, warn: 1, info: 2 };
+  const flatGaps = [];
+  for (const it of items) {
+    for (const g of it.metadataGaps) flatGaps.push({ url: it.url || '(no url)', ...g });
+  }
+  flatGaps.sort((a, b) => sevOrder[a.severity] - sevOrder[b.severity]);
+
+  // migration readiness
+  const redirectLedger = items
+    .filter((it) => it.decision === 'retire')
+    .map((it) => ({ from: it.url || '(no url)', to: null, status: 301, resolved: false, note: 'redirect target UNRESOLVED — a decision, not an omission' }));
+
+  const itemsWithGaps = items.filter((it) => it.metadataGaps.length > 0).length;
+  const blockingGaps = flatGaps.filter((g) => g.severity === 'fail').length;
+
+  const fieldCoverage = fieldCoverageReport(normalized);
+
+  const blockers = [];
+  if (redirectLedger.length > 0) blockers.push(`${redirectLedger.length} retire decision(s) need a redirect target before launch`);
+  if (blockingGaps > 0) blockers.push(`${blockingGaps} blocking metadata gap(s) (missing url/title/date)`);
+  if (dupUrls.length > 0) blockers.push(`${dupUrls.length} duplicate URL(s) in the export`);
+  if (counts.review > 0) blockers.push(`${counts.review} item(s) lack the data to auto-decide (manual review)`);
+  for (const [field, cov] of Object.entries(fieldCoverage)) {
+    if (cov.present === 0) blockers.push(`source field "${field}" is absent from the export — no destination to map`);
+  }
+
+  // readiness score: start at 100, subtract weighted penalties, floor at 0.
+  const penalty =
+    redirectLedger.length * 2 +
+    blockingGaps * 3 +
+    dupUrls.length * 4 +
+    counts.review * 2 +
+    (flatGaps.length - blockingGaps) * 1;
+  const readinessScore = Math.max(0, Math.min(100, 100 - Math.round((penalty / Math.max(1, items.length * 6)) * 100)));
+
+  // unmapped source headers (a field with no canonical home is a mapping decision)
+  const mappedHeaders = new Set(Object.values(headerMap));
+  const unmappedFields = Object.keys(arr[0]).filter((h) => !mappedHeaders.has(h));
+
+  return {
+    asOf: new Date(asOfMs).toISOString().slice(0, 10),
+    thresholds: T,
+    counts,
+    headerMap,
+    unmappedFields,
+    items,
+    metadataGaps: flatGaps,
+    duplicates: { titles: dupTitles, urls: dupUrls },
+    migrationReadiness: {
+      totalUrls: items.length,
+      redirectsRequired: redirectLedger.length,
+      redirectLedger,
+      itemsWithGaps,
+      blockingGaps,
+      fieldCoverage,
+      readinessScore,
+      blockers,
+    },
+  };
+}
+
+function fieldCoverageReport(normalized) {
+  const fields = ['url', 'title', 'metaDescription', 'publishedMs', 'updatedMs', 'wordCount', 'pageviews'];
+  const report = {};
+  for (const f of fields) {
+    let present = 0;
+    for (const it of normalized) {
+      const v = it[f];
+      const has = f === 'publishedMs' || f === 'updatedMs' || f === 'wordCount' || f === 'pageviews' ? v !== null : v !== '';
+      if (has) present += 1;
+    }
+    report[f] = { present, total: normalized.length, pct: Math.round((present / normalized.length) * 100) };
+  }
+  return report;
+}
+
+// Convenience: parse raw text and build the inventory in one call.
+export function inventoryFromText(text, hint = null, options = {}) {
+  const rows = parseExport(text, hint);
+  return buildInventory(rows, options);
+}