fullstackgtm 0.43.0 → 0.45.0

package/src/connectors/signalSources.ts

@@ -0,0 +1,314 @@
+/**
+ * Source connectors for the `signals` layer — the connection-based intake that
+ * generalizes the no-auth ATS adapters (`atsBoards.ts`) and the hand-staged
+ * `--from <file.json>` path into one contract: a platform connection in, a list
+ * of evidence-bearing staged signal rows out.
+ *
+ * Design (see docs/spec-connectors-signals-outbound.md):
+ *   - Zero runtime deps: global `fetch` only, injectable for tests.
+ *   - Read-only: a source never writes a CRM record and never emits a
+ *     PatchOperation. `signals fetch` stays read-only re: the CRM.
+ *   - Verbatim evidence: every row carries a non-empty `quote`; a row that
+ *     cannot ground a why-now is dropped, never faked. The central
+ *     `stagedRowToSignal` gate enforces this again.
+ *   - Secrets via the credential ladder: API keys come from
+ *     `ctx.getApiKey(provider)` (login store -> env -> broker), NEVER from argv.
+ *     `ctx.options` carries non-secret knobs only (a file path, a query term).
+ *   - Per-source resilience: a connector's own failure yields `[]` (logged by
+ *     the caller), it must never sink a multi-source run — the per-provider
+ *     try/catch idiom of atsBoards/prospectSources.
+ */
+
+import { readFileSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import type { SignalBucket, StagedSignalRow } from "../signals.ts";
+import { SIGNAL_BUCKETS } from "../signals.ts";
+import { parseSpoolText, spoolFilesIn } from "../spoolFiles.ts";
+
+export type SignalSourceShape = "pull" | "push";
+export type SignalSourceAuth = "none" | "api_key" | "oauth";
+
+/** Everything a source connector needs for one `fetch`, supplied by the CLI. */
+export type SignalSourceContext = {
+  /** Accounts to scope a pull. May be empty (a file/spool source ignores it). */
+  watchlist: { domain: string }[];
+  /** Evidence keywords for job/listing-style sources; may be empty. */
+  keywords: string[];
+  now: Date;
+  /** Injectable fetch for tests; global `fetch` by default. */
+  fetchImpl?: typeof fetch;
+  /**
+   * Credential-ladder lookup. Returns a usable secret for `provider`, or null
+   * when nothing is configured (the connector then returns []). Secrets NEVER
+   * arrive via argv — only through this.
+   */
+  getApiKey?: (provider: string) => Promise<string | null>;
+  /** Non-secret per-connector knobs from `--connector-opt k=v` (paths, queries). */
+  options?: Record<string, string>;
+};
+
+export type SignalSourceConnector = {
+  id: string;
+  /** Default bucket this source feeds (a row may still override it). */
+  bucket: SignalBucket;
+  shape: SignalSourceShape;
+  auth: SignalSourceAuth;
+  /**
+   * Produce staged rows now. Resilient by contract: the connector's own
+   * failures (offline, non-2xx, malformed payload, missing key) resolve to []
+   * rather than throwing, so one source's outage never aborts a multi-source
+   * `signals fetch`. Validation/evidence-gating of the returned rows happens
+   * centrally in `stagedRowToSignal`.
+   */
+  fetch(ctx: SignalSourceContext): Promise<StagedSignalRow[]>;
+};
+
+// ---------------------------------------------------------------------------
+// file — local JSON / JSONL intake (also the webhook landing-zone reader)
+
+/**
+ * Read staged rows from a local path — the webhook landing-zone reader. The path
+ * (from `options.path`/`options.file`) may be:
+ *   - a single FILE: a JSON array, or newline-delimited JSON (one row per line);
+ *   - a DIRECTORY (the conventional spool): every `*.jsonl` / `*.json` file in
+ *     it is read and concatenated (sorted by name), so multiple receivers can
+ *     each append their own file (`rb2b.jsonl`, `hubspot.jsonl`) and they all
+ *     land in one fetch.
+ * No auth. This is how every push platform (RB2B, Trigify, HubSpot webhooks)
+ * reaches the CLI: a receiver appends a row to the spool, this reads it on the
+ * next `signals fetch`. The CLI defaults the path to the conventional spool dir
+ * (`signalsSpoolDir`) when `--connector file` is used with no path; a bare
+ * library call with no path is inactive (returns []).
+ *
+ * Resilient: a missing path / unreadable file yields [] (an empty source, not a
+ * crash), and one unreadable file in a spool directory is skipped. A file that
+ * IS present but malformed throws — a corrupt spool is a real error to surface,
+ * not silent data loss. The central `stagedRowToSignal` gate validates rows.
+ */
+export const fileSource: SignalSourceConnector = {
+  id: "file",
+  bucket: "company",
+  shape: "pull",
+  auth: "none",
+  async fetch(ctx) {
+    const path = ctx.options?.path ?? ctx.options?.file;
+    if (!path) return []; // no spool configured (the CLI fills the default dir)
+    const abs = resolve(process.cwd(), path);
+    let isDir: boolean;
+    try {
+      isDir = statSync(abs).isDirectory();
+    } catch {
+      return []; // missing path: an empty source, not a crash
+    }
+    // Container parsing lives in the shared spool reader (src/spoolFiles.ts) so
+    // `signals fetch --from`, `enrich ingest`, and `market observe --from` read
+    // the same convention; the "file source" label keeps error text unchanged.
+    const files = isDir ? spoolFilesIn(abs) : [abs];
+    const rows: Record<string, unknown>[] = [];
+    for (const file of files) {
+      let raw: string;
+      try {
+        raw = readFileSync(file, "utf8");
+      } catch {
+        continue; // one unreadable file in a spool dir must not sink the rest
+      }
+      rows.push(...parseSpoolText(raw, file, "file source"));
+    }
+    return rows.map((row) => coerceRow(row, this.bucket));
+  },
+};
+
+// ---------------------------------------------------------------------------
+// serpapi-news — funding/company signals from a news REST query (API key)
+
+const SERPAPI_BASE_URL = "https://serpapi.com";
+
+/**
+ * Pull recent news per watchlist account and stage funding/company signals. One
+ * query per account (`q="<domain>"`, Google News engine); each result becomes a
+ * row whose verbatim `quote` is the headline (+ source), so the downstream judge
+ * can ground a why-now on a real, linkable article. API key via the credential
+ * ladder (provider "serpapi"); no key -> [] (the source is simply inactive).
+ *
+ * Bucket defaults to `funding`; override per run with `--connector-opt bucket=company`.
+ */
+export const serpapiNewsSource: SignalSourceConnector = {
+  id: "serpapi-news",
+  bucket: "funding",
+  shape: "pull",
+  auth: "api_key",
+  async fetch(ctx) {
+    const apiKey = ctx.getApiKey ? await ctx.getApiKey("serpapi") : null;
+    if (!apiKey) return [];
+    const fetchImpl = ctx.fetchImpl ?? fetch;
+    const base = (ctx.options?.apiBaseUrl ?? SERPAPI_BASE_URL).replace(/\/$/, "");
+    const bucket = pickBucket(ctx.options?.bucket, this.bucket);
+    const out: StagedSignalRow[] = [];
+    for (const account of ctx.watchlist) {
+      const domain = account.domain.trim();
+      if (!domain) continue;
+      try {
+        const url =
+          `${base}/search.json?engine=google_news&q=${encodeURIComponent(`"${domain}"`)}` +
+          `&api_key=${encodeURIComponent(apiKey)}`;
+        const response = await fetchImpl(url, { headers: { Accept: "application/json" } });
+        if (!response.ok) continue;
+        const data = (await response.json()) as {
+          news_results?: Array<{ title?: string; link?: string; source?: { name?: string } | string; date?: string }>;
+        };
+        for (const item of data.news_results ?? []) {
+          const title = typeof item.title === "string" ? item.title.trim() : "";
+          if (!title) continue; // no headline -> no verbatim evidence -> drop
+          const sourceName =
+            typeof item.source === "string" ? item.source : item.source?.name ?? "";
+          const quote = sourceName ? `${title} — ${sourceName}` : title;
+          out.push({
+            bucket,
+            accountDomain: domain,
+            trigger: `news: ${title}`,
+            quote,
+            sourceUrl: typeof item.link === "string" ? item.link : "",
+          });
+        }
+      } catch {
+        continue; // one account's outage must not sink the run
+      }
+    }
+    return out;
+  },
+};
+
+// ---------------------------------------------------------------------------
+// hubspot-forms — first-party demand from recent HubSpot form submissions
+
+const HUBSPOT_BASE_URL = "https://api.hubapi.com";
+
+/**
+ * Stage `demand` signals from recent HubSpot form submissions — the first real
+ * `demand`-bucket producer (a form fill is first-party demand). Reuses the
+ * EXISTING HubSpot credential via the ladder (provider "hubspot"); no separate
+ * login. Each submission whose email carries a company domain becomes a row
+ * whose verbatim `quote` is the form name + submitted email (the evidence a rep
+ * can verify). Submissions without a corporate domain (free-mail) are dropped —
+ * no account to attach demand to.
+ *
+ * Phase 1 is a pull over the Forms submissions API; the form-submission webhook
+ * (push) lands in Phase 2 via the spool + `file` source.
+ */
+export const hubspotFormsSource: SignalSourceConnector = {
+  id: "hubspot-forms",
+  bucket: "demand",
+  shape: "pull",
+  auth: "oauth",
+  async fetch(ctx) {
+    const token = ctx.getApiKey ? await ctx.getApiKey("hubspot") : null;
+    if (!token) return [];
+    const fetchImpl = ctx.fetchImpl ?? fetch;
+    const base = (ctx.options?.apiBaseUrl ?? HUBSPOT_BASE_URL).replace(/\/$/, "");
+    const out: StagedSignalRow[] = [];
+    let forms: Array<{ guid?: string; id?: string; name?: string }> = [];
+    try {
+      const response = await fetchImpl(`${base}/marketing/v3/forms`, {
+        headers: { Authorization: `Bearer ${token}`, Accept: "application/json" },
+      });
+      if (!response.ok) return [];
+      const data = (await response.json()) as { results?: typeof forms };
+      forms = data.results ?? [];
+    } catch {
+      return [];
+    }
+    for (const form of forms) {
+      const formId = form.guid ?? form.id;
+      if (!formId) continue;
+      const formName = typeof form.name === "string" && form.name ? form.name : "form";
+      try {
+        const response = await fetchImpl(
+          `${base}/form-integrations/v1/submissions/forms/${encodeURIComponent(formId)}?limit=50`,
+          { headers: { Authorization: `Bearer ${token}`, Accept: "application/json" } },
+        );
+        if (!response.ok) continue;
+        const data = (await response.json()) as {
+          results?: Array<{ values?: Array<{ name?: string; value?: string }>; submittedAt?: number }>;
+        };
+        for (const submission of data.results ?? []) {
+          const email = fieldValue(submission.values, "email");
+          const domain = corporateDomain(email);
+          if (!domain) continue; // free-mail / no email: no account to attach to
+          const submittedAt =
+            typeof submission.submittedAt === "number"
+              ? new Date(submission.submittedAt).toISOString()
+              : undefined;
+          out.push({
+            bucket: "demand",
+            accountDomain: domain,
+            trigger: `form: ${formName}`,
+            quote: `Submitted "${formName}" — ${email}`,
+            sourceUrl: "",
+            ...(submittedAt ? { firstSeen: submittedAt } : {}),
+          });
+        }
+      } catch {
+        continue;
+      }
+    }
+    return out;
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Registry
+
+const CONNECTORS: SignalSourceConnector[] = [fileSource, serpapiNewsSource, hubspotFormsSource];
+
+const REGISTRY = new Map<string, SignalSourceConnector>(CONNECTORS.map((c) => [c.id, c]));
+
+/** All registered source connectors (stable order). */
+export function listSignalSources(): SignalSourceConnector[] {
+  return [...CONNECTORS];
+}
+
+/** Resolve a connector by id, or null when unknown. */
+export function getSignalSource(id: string): SignalSourceConnector | null {
+  return REGISTRY.get(id) ?? null;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+
+function coerceRow(row: Record<string, unknown>, defaultBucket: SignalBucket): StagedSignalRow {
+  // Fill the bucket from the connector default when a file row omits it; the
+  // central validator still rejects an unknown bucket and an empty quote.
+  const bucket = row.bucket === undefined ? defaultBucket : (row.bucket as SignalBucket);
+  return { ...(row as StagedSignalRow), bucket };
+}
+
+function pickBucket(raw: string | undefined, fallback: SignalBucket): SignalBucket {
+  if (raw && SIGNAL_BUCKETS.includes(raw as SignalBucket)) return raw as SignalBucket;
+  return fallback;
+}
+
+function fieldValue(values: Array<{ name?: string; value?: string }> | undefined, name: string): string {
+  for (const field of values ?? []) {
+    if (field.name === name && typeof field.value === "string") return field.value.trim();
+  }
+  return "";
+}
+
+const FREE_MAIL = new Set([
+  "gmail.com",
+  "yahoo.com",
+  "hotmail.com",
+  "outlook.com",
+  "icloud.com",
+  "aol.com",
+  "proton.me",
+  "protonmail.com",
+]);
+
+/** Company domain from an email, or "" for free-mail / no email. */
+function corporateDomain(email: string): string {
+  if (!email.includes("@")) return "";
+  const domain = email.split("@").at(-1)!.trim().toLowerCase();
+  if (!domain || FREE_MAIL.has(domain)) return "";
+  return domain;
+}

package/src/connectors/theirstack.ts

@@ -0,0 +1,170 @@
+/**
+ * TheirStack — technographic company discovery.
+ *
+ * Explorium can only size a firmographic universe (NAICS/size/geo) and can't even
+ * return the list. For a CRM-hygiene/RevOps tool the real buying signal is
+ * "company runs a CRM", and the deliverable is an actual list of those companies.
+ * TheirStack does both: filter companies by the technology they use (Salesforce,
+ * HubSpot, Pipedrive, …) plus firmographics, and return real records (name,
+ * domain, employee_count, …). A cheap count sizes the market; a paged search
+ * materializes the list. Both cost ~3 credits per company RETURNED — counting
+ * still returns 1 row (the API rejects limit:0), so a count is ~3 credits, not
+ * free; a list pull is ~3 × the rows.
+ *
+ * API: POST https://api.theirstack.com/v1/companies/search, Bearer auth.
+ * Verified live (2026-06-29): filters company_technology_slug_or /
+ * company_country_code_or / min_employee_count / max_employee_count; the total is
+ * `metadata.total_results` with include_total_results:true; limit must be ≥ 1
+ * (limit:0 → 422, the count gotcha — cf. Explorium's `size`-caps-the-total).
+ */
+
+type FetchImpl = typeof fetch;
+
+/** TheirStack charges per company RETURNED — verified live (a list pull of N
+ *  companies spends 3N). The count (limit:1) returns 1 row, so it's ~3 credits. */
+export const THEIRSTACK_CREDITS_PER_COMPANY = 3;
+
+export type TheirStackCost = {
+  companies: number;
+  credits: number;
+  /** USD estimate — present ONLY when a per-credit rate is supplied (no
+   *  fabricated default; TheirStack pricing varies ~$0.04–$0.11/credit by tier). */
+  usd?: number;
+};
+
+/** Deterministic cost of pulling `companies` records (the credits are the hard
+ *  fact; the dollar figure needs an explicit rate). */
+export function theirStackPullCost(companies: number, usdPerCredit?: number): TheirStackCost {
+  const n = Math.max(0, Math.round(companies));
+  const credits = n * THEIRSTACK_CREDITS_PER_COMPANY;
+  return {
+    companies: n,
+    credits,
+    ...(usdPerCredit && usdPerCredit > 0 ? { usd: Math.round(credits * usdPerCredit) } : {}),
+  };
+}
+
+async function safeText(res: { text(): Promise<string> }): Promise<string> {
+  try {
+    return (await res.text()).slice(0, 300);
+  } catch {
+    return "";
+  }
+}
+
+/** Firmographic + technographic filter for TheirStack company search. */
+export type TheirStackFilters = {
+  /** technology slugs, OR-matched — e.g. ["salesforce","hubspot","pipedrive"]. */
+  company_technology_slug_or?: string[];
+  min_employee_count?: number;
+  max_employee_count?: number;
+  /** ISO2 country codes, OR-matched — e.g. ["US"]. */
+  company_country_code_or?: string[];
+};
+
+/** A real company record from TheirStack (the materialized list element). */
+export type TheirStackCompany = {
+  name?: string;
+  domain?: string;
+  employeeCount?: number;
+  countryCode?: string;
+  city?: string;
+  linkedinUrl?: string;
+  /** the matched technology slugs that put this company in the list. */
+  technologies?: string[];
+};
+
+const BASE = "https://api.theirstack.com";
+const SEARCH_PATH = "/v1/companies/search";
+
+function buildBody(filters: TheirStackFilters, limit: number, page: number, includeTotal: boolean): string {
+  // Drop undefined keys so we never send empty filters the API rejects.
+  const body: Record<string, unknown> = { limit, page };
+  if (includeTotal) body.include_total_results = true;
+  if (filters.company_technology_slug_or?.length) body.company_technology_slug_or = filters.company_technology_slug_or;
+  if (filters.company_country_code_or?.length) body.company_country_code_or = filters.company_country_code_or;
+  if (typeof filters.min_employee_count === "number") body.min_employee_count = filters.min_employee_count;
+  if (typeof filters.max_employee_count === "number") body.max_employee_count = filters.max_employee_count;
+  return JSON.stringify(body);
+}
+
+/** Read the total-match count from the response envelope (field name varies). */
+export function readTheirStackTotal(body: unknown): number | null {
+  if (!body || typeof body !== "object") return null;
+  const obj = body as Record<string, unknown>;
+  const meta = (obj.metadata ?? obj.meta ?? obj) as Record<string, unknown>;
+  for (const key of ["total_results", "total_companies", "total_count", "total", "count"]) {
+    const v = meta[key];
+    if (typeof v === "number" && Number.isFinite(v) && v >= 0) return Math.round(v);
+  }
+  return null;
+}
+
+function mapCompany(row: Record<string, unknown>): TheirStackCompany {
+  const str = (v: unknown): string | undefined => (typeof v === "string" && v.trim() ? v : undefined);
+  const num = (v: unknown): number | undefined => (typeof v === "number" && Number.isFinite(v) ? v : undefined);
+  const slugs = row.technology_slugs ?? row.technology_names;
+  return {
+    name: str(row.name),
+    domain: str(row.domain),
+    employeeCount: num(row.employee_count),
+    countryCode: str(row.country_code),
+    city: str(row.city),
+    linkedinUrl: str(row.linkedin_url),
+    technologies: Array.isArray(slugs) ? slugs.filter((s): s is string => typeof s === "string") : undefined,
+  };
+}
+
+/**
+ * Count companies matching the technographic + firmographic filter — the real
+ * TAM size. Uses `limit: 1` (the API rejects `limit: 0` with a 422 — verified
+ * live) + `include_total_results`, and reads `metadata.total_results`. Costs the
+ * 1 returned company's credits; the total itself is the point.
+ * Returns null if the envelope carries no total.
+ */
+export async function theirStackCountCompanies(opts: {
+  apiKey: string;
+  filters: TheirStackFilters;
+  apiBaseUrl?: string;
+  fetchImpl?: FetchImpl;
+}): Promise<number | null> {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const base = (opts.apiBaseUrl ?? BASE).replace(/\/$/, "");
+  const res = await fetchImpl(`${base}${SEARCH_PATH}`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${opts.apiKey}`, "Content-Type": "application/json" },
+    body: buildBody(opts.filters, 1, 0, true),
+  });
+  if (!res.ok) {
+    throw new Error(`TheirStack count failed: HTTP ${res.status} ${await safeText(res)}`);
+  }
+  return readTheirStackTotal(await res.json());
+}
+
+/**
+ * Pull a page of real companies matching the filter — the materialized list.
+ * Returns the records plus the total (when the envelope reports it).
+ */
+export async function theirStackSearchCompanies(opts: {
+  apiKey: string;
+  filters: TheirStackFilters;
+  limit?: number;
+  page?: number;
+  apiBaseUrl?: string;
+  fetchImpl?: FetchImpl;
+}): Promise<{ companies: TheirStackCompany[]; total: number | null }> {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const base = (opts.apiBaseUrl ?? BASE).replace(/\/$/, "");
+  const limit = Math.min(Math.max(opts.limit ?? 25, 1), 100);
+  const res = await fetchImpl(`${base}${SEARCH_PATH}`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${opts.apiKey}`, "Content-Type": "application/json" },
+    body: buildBody(opts.filters, limit, opts.page ?? 0, true),
+  });
+  if (!res.ok) {
+    throw new Error(`TheirStack search failed: HTTP ${res.status} ${await safeText(res)}`);
+  }
+  const body = (await res.json()) as { data?: Array<Record<string, unknown>>; results?: Array<Record<string, unknown>> };
+  const rows = body.data ?? body.results ?? [];
+  return { companies: rows.map(mapCompany), total: readTheirStackTotal(body) };
+}

package/src/icp.ts

@@ -24,6 +24,10 @@ export type Icp = {
     employeeBands?: string[];
     /** ISO country codes, lowercased, e.g. ["us"] */
     geos?: string[];
+    /** technographic targeting: technology slugs the account must use, e.g.
+     *  ["salesforce","hubspot","pipedrive"] — the real CRM/MAP buying signal,
+     *  consumed by TheirStack company search. OR-matched. */
+    technologies?: string[];
   };
   persona: {
     /** seniority: "cxo","vp","director","manager","owner","senior" */
@@ -80,37 +84,111 @@ export function icpToExploriumFilters(icp: Icp): Record<string, { values?: strin
 }
 
 /**
- * Crustdata / LinkedIn seniority vocab. ICP job levels are normalized lowercase;
- * Crustdata expects these exact capitalized strings (verified: "CXO",
- * "Vice President", "Director" appear in Crustdata's docs/examples).
+ * Explorium /v1/businesses filters from the ICP — the COMPANY (account) side, for
+ * sizing the account universe (TAM). Firmographics only, no persona: the count is
+ * of matching companies. Field names differ from /v1/prospects (verified live):
+ * `country_code` (not company_country_code), `company_size` (same employee bands),
+ * `naics_category`. `/v1/businesses` total_results is a real count, capped at
+ * 60,000 (see EXPLORIUM_BUSINESS_COUNT_CAP in the connector).
  */
-const CRUSTDATA_SENIORITY: Record<string, string> = {
-  cxo: "CXO",
-  "c-suite": "CXO",
-  c_suite: "CXO",
-  founder: "Owner",
-  owner: "Owner",
-  partner: "Partner",
-  vp: "Vice President",
-  "vice president": "Vice President",
-  head: "Director",
-  director: "Director",
-  manager: "Manager",
-  senior: "Senior",
-  entry: "Entry",
-};
+export function icpToExploriumBusinessFilters(icp: Icp): Record<string, { values?: string[] }> {
+  const f: Record<string, { values?: string[] }> = {};
+  if (icp.firmographics.geos?.length) f.country_code = { values: icp.firmographics.geos };
+  if (icp.firmographics.employeeBands?.length) f.company_size = { values: icp.firmographics.employeeBands };
+  if (icp.firmographics.naics?.length) f.naics_category = { values: icp.firmographics.naics };
+  return f;
+}
+
+/**
+ * Collapse provider-agnostic employee bands ("51-200","10001+") into a single
+ * {min,max} envelope for APIs that take integer bounds (TheirStack). An open
+ * top band ("10001+") leaves max undefined.
+ */
+export function employeeBandsToRange(bands: string[] | undefined): { min?: number; max?: number } {
+  if (!bands?.length) return {};
+  let min: number | undefined;
+  let max: number | undefined;
+  let openTop = false;
+  for (const band of bands) {
+    const plus = /^(\d+)\+$/.exec(band.trim());
+    if (plus) {
+      const lo = Number(plus[1]);
+      if (min === undefined || lo < min) min = lo;
+      openTop = true;
+      continue;
+    }
+    const range = /^(\d+)\s*-\s*(\d+)$/.exec(band.trim());
+    if (range) {
+      const lo = Number(range[1]);
+      const hi = Number(range[2]);
+      if (min === undefined || lo < min) min = lo;
+      if (max === undefined || hi > max) max = hi;
+    }
+  }
+  return { min, max: openTop ? undefined : max };
+}
 
 /**
- * ICP industry keyword → LinkedIn industry names Crustdata filters on. Includes
- * the current LinkedIn-v2 names; for software we send the cluster (dev + IT
- * services + internet) so an OR match isn't overly narrow.
+ * TheirStack company-search filter from the ICP: the technographic targeting that
+ * Explorium can't do. `company_technology_slug_or` is the CRM/MAP buying signal
+ * (firmographics.technologies); employee bands become min/max bounds; geos become
+ * ISO2 codes (uppercased).
+ */
+export function icpToTheirStackFilters(icp: Icp): {
+  company_technology_slug_or?: string[];
+  min_employee_count?: number;
+  max_employee_count?: number;
+  company_country_code_or?: string[];
+} {
+  const f: {
+    company_technology_slug_or?: string[];
+    min_employee_count?: number;
+    max_employee_count?: number;
+    company_country_code_or?: string[];
+  } = {};
+  if (icp.firmographics.technologies?.length) {
+    f.company_technology_slug_or = icp.firmographics.technologies.map((t) => t.trim().toLowerCase());
+  }
+  if (icp.firmographics.geos?.length) {
+    f.company_country_code_or = icp.firmographics.geos.map((g) => g.trim().toUpperCase());
+  }
+  const range = employeeBandsToRange(icp.firmographics.employeeBands);
+  if (range.min !== undefined) f.min_employee_count = range.min;
+  if (range.max !== undefined) f.max_employee_count = range.max;
+  return f;
+}
+
+// NOTE: a CRUSTDATA_SENIORITY vocab table lived here until 2026-07-02 — the
+// `current_seniority_levels` filter is broken upstream (see the live findings
+// on icpToCrustdataFilters below), so job levels are no longer sent to the
+// provider at all. Resurrect the table from git history if pipe0 fixes it.
+
+/**
+ * ICP industry keyword → LinkedIn industry names Crustdata filters on.
+ *
+ * LinkedIn renamed its industry taxonomy (v1 → v2, ~2022), and data vendors
+ * normalize to one generation or the other. Sending ONLY the v2 names risks a
+ * zero-match when Crustdata stores v1 (and vice-versa) — observed live: a RevOps
+ * ICP whose only firmographic constraint was the v2 names returned 0 even though
+ * the title-only search returned plenty. So each cluster sends BOTH generations
+ * (OR-matched within the field): v2 ("Software Development", "IT Services and IT
+ * Consulting", "Technology, Information and Internet") AND v1 ("Computer
+ * Software", "Information Technology & Services", "Internet").
  */
 const CRUSTDATA_INDUSTRY: Record<string, string[]> = {
-  software: ["Software Development", "Information Technology and Services", "Internet"],
-  saas: ["Software Development", "Information Technology and Services"],
-  "information technology & services": ["Information Technology and Services"],
-  "information technology and services": ["Information Technology and Services"],
-  internet: ["Internet"],
+  software: [
+    "Software Development",
+    "Computer Software",
+    "IT Services and IT Consulting",
+    "Information Technology & Services",
+    "Information Technology and Services",
+    "Technology, Information and Internet",
+    "Internet",
+  ],
+  saas: ["Software Development", "Computer Software", "IT Services and IT Consulting", "Information Technology & Services"],
+  "information technology & services": ["Information Technology & Services", "IT Services and IT Consulting"],
+  "information technology and services": ["Information Technology & Services", "IT Services and IT Consulting"],
+  internet: ["Internet", "Technology, Information and Internet"],
   fintech: ["Financial Services"],
   "financial services": ["Financial Services"],
 };
@@ -118,10 +196,22 @@ const CRUSTDATA_INDUSTRY: Record<string, string[]> = {
 /**
  * pipe0 Crustdata people-search config.filters from the ICP. `current_job_titles`
  * matches real LinkedIn title strings (case-sensitive), so keywords are Title
- * Cased. Seniority + industry are mapped to Crustdata's controlled vocab via the
- * tables above. NOTE: the exact pipe0→Crustdata value set could not be re-run
- * live (pipe0 credits were exhausted) — validate when credits refill; fit
- * scoring is the safety net for persona precision regardless.
+ * Cased. Industry is mapped to Crustdata's controlled vocab via the table above.
+ *
+ * LIVE FINDINGS (2026-06-26, re-confirmed 2026-07-02 with fresh credits):
+ * `current_job_titles` works; `current_title` is rejected (422). The culprit
+ * that zeroed the full ICP filter is `current_seniority_levels`: ANY non-empty
+ * `include` returns 0 results through pipe0's people:profiles:crustdata@1 —
+ * including Crustdata's own documented values ("CXO", "Director",
+ * "Vice President"), lowercase, and SNAKE_CASE variants — while the identical
+ * search without it returns results. (An array instead of the
+ * {include, exclude} object is a 422, so the shape was right; the filter is
+ * broken upstream.) So job levels are NOT sent to the provider: persona
+ * seniority is enforced by fit scoring (scoreProspectAgainstIcp weights
+ * jobLevels), which was always the precision backstop. `locations` and
+ * `current_employers_linkedin_industries` (both-taxonomy hedge) are live-
+ * verified working in combination with titles. Note fit-scoring backs up
+ * PERSONA precision but NOT industry, so the industry filter is load-bearing.
  */
 export function icpToCrustdataFilters(icp: Icp): Record<string, unknown> {
   const f: Record<string, unknown> = {};
@@ -129,10 +219,6 @@ export function icpToCrustdataFilters(icp: Icp): Record<string, unknown> {
   if (icp.firmographics.geos?.length) {
     f.locations = icp.firmographics.geos.map((g) => COUNTRY_NAMES[g.toLowerCase()] ?? g);
   }
-  if (icp.persona.jobLevels?.length) {
-    const include = [...new Set(icp.persona.jobLevels.map((l) => CRUSTDATA_SENIORITY[l.toLowerCase()]).filter(Boolean))];
-    if (include.length) f.current_seniority_levels = { include, exclude: [] };
-  }
   if (icp.firmographics.industries?.length) {
     const inds = [
       ...new Set(icp.firmographics.industries.flatMap((i) => CRUSTDATA_INDUSTRY[i.toLowerCase()] ?? [titleCase(i)])),