fullstackgtm 0.52.4 → 0.53.0

package/CHANGELOG.md

@@ -7,6 +7,23 @@ The path to 1.0 is planned in [docs/roadmap-to-1.0.md](https://github.com/fullst
 
 ## [Unreleased]
 
+## [0.53.0] — 2026-07-11
+
+### Added
+
+- Clay acquisition progressively relaxes over-constrained searches through
+  exact, account-first, persona-first, title-first, and function-first routes;
+  every broader candidate still passes through local ICP fit scoring.
+
+### Changed
+
+- Clay geography translation expands broad regions such as North America,
+  Europe, and APAC into valid country filters and treats global/worldwide as
+  an unconstrained geography rather than a fake country.
+- Phrase-style model-derived titles can qualify equivalent buyer functions,
+  allowing roles such as `VP, Global Brand Strategy` to match `Head of Brand`
+  without weakening the configured fit threshold.
+
 ## [0.52.4] — 2026-07-11
 
 ### Fixed

package/dist/cli/enrich.js

@@ -17,7 +17,7 @@ import { uploadHostedPatchPlan } from "../hostedPatchPlan.js";
 import { progressReporter, reportCounts, reportEvent } from "../runReport.js";
 import { ACQUIRE_STAGES, composeListeners, createProgressEmitter } from "../progress.js";
 import { createLinkedInProvider, discoverLinkedInProspects } from "../acquireLinkedIn.js";
-import { fitThreshold, icpToClayPeopleFilters, icpToCrustdataFilters, icpToExploriumFilters, scoreProspectAgainstIcp } from "../icp.js";
+import { clayPeopleFilterRoutes, fitThreshold, icpToClayPeopleFilters, icpToCrustdataFilters, icpToExploriumFilters, scoreProspectAgainstIcp } from "../icp.js";
 import { apolloPullKeysForAppend, apolloPullKeysForRefresh, createApolloClient, pullApolloRecords } from "../enrichApollo.js";
 import { isSpoolPath, readSpoolPath } from "../spoolFiles.js";
 import { isOptionValue, loadIcp, numericOption, option, readSnapshot, saveRequested } from "./shared.js";
@@ -508,7 +508,7 @@ async function acquireFromApi(config, source, rest, icp, snapshot, seen, priorRu
     if ((disc.provider === "linkedin" || disc.provider === "heyreach") && !listId) {
         throw new Error("enrich acquire --source linkedin needs a HeyReach lead-list id: pass --list <id> or set acquire.discovery.linkedin.listId.");
     }
-    const filters = disc.provider === "explorium"
+    let filters = disc.provider === "explorium"
         ? (icp ? icpToExploriumFilters(icp) : (disc.filters ?? {}))
         : disc.provider === "pipe0"
             ? (icp ? icpToCrustdataFilters(icp) : (disc.filters ?? {}))
@@ -559,6 +559,9 @@ async function acquireFromApi(config, source, rest, icp, snapshot, seen, priorRu
     const prospects = [];
     const crmKeys = crmContactKeys(snapshot);
     const runSeen = new Set(seen);
+    const clayRoutes = disc.provider === "clay" && icp ? clayPeopleFilterRoutes(icp) : [];
+    let clayRouteIndex = 0;
+    const allowClayFallback = !resume;
     // Pull successive pages until we have enough fresh candidates or hit the
     // bounded scan ceiling. Page size follows the remaining target, so advancing
     // a cursor never silently discards unused candidates from the final page.
@@ -578,18 +581,28 @@ async function acquireFromApi(config, source, rest, icp, snapshot, seen, priorRu
             exhausted = result.nextCursor === null;
         }
         else if (disc.provider === "clay") {
-            if (!cursor) {
-                progress.note("creating Clay people-search iterator");
-                cursor = await createClaySearch({
-                    apiKey: providerKey("clay"), sourceType: "people", filters,
-                });
+            while (true) {
+                if (!cursor) {
+                    const route = clayRoutes[clayRouteIndex];
+                    if (route)
+                        filters = route.filters;
+                    progress.note(`creating Clay people-search iterator · ${route?.id ?? "configured"}`);
+                    cursor = await createClaySearch({ apiKey: providerKey("clay"), sourceType: "people", filters });
+                }
+                const result = await runClayPeopleSearchPage({ apiKey: providerKey("clay"), searchId: cursor, limit: requestSize });
+                page = result.prospects;
+                offset += page.length;
+                exhausted = !result.hasMore;
+                if (page.length > 0 || !allowClayFallback || clayRouteIndex >= clayRoutes.length - 1)
+                    break;
+                const failed = clayRoutes[clayRouteIndex]?.id ?? "configured";
+                clayRouteIndex += 1;
+                const next = clayRoutes[clayRouteIndex];
+                progress.note(`Clay ${failed} route returned 0 · trying ${next.id}`);
+                cursor = null;
+                offset = 0;
+                exhausted = false;
             }
-            const result = await runClayPeopleSearchPage({
-                apiKey: providerKey("clay"), searchId: cursor, limit: requestSize,
-            });
-            page = result.prospects;
-            offset += page.length;
-            exhausted = !result.hasMore;
         }
         else if (disc.provider === "explorium") {
             const pageNumber = offset + 1;
@@ -639,12 +652,24 @@ async function acquireFromApi(config, source, rest, icp, snapshot, seen, priorRu
                 runSeen.add(key);
         }
         progress.note(`${discovered} scanned · ${qualified} qualified · ${prospects.length}/${targetFresh} fresh`);
+        if (disc.provider === "clay" && allowClayFallback && exhausted &&
+            prospects.length < targetFresh && clayRouteIndex < clayRoutes.length - 1 && discovered < scanLimit) {
+            const failed = clayRoutes[clayRouteIndex]?.id ?? "configured";
+            clayRouteIndex += 1;
+            progress.note(`Clay ${failed} route did not fill the target · trying ${clayRoutes[clayRouteIndex].id}`);
+            cursor = null;
+            offset = 0;
+            exhausted = false;
+        }
         // Explorium is page-number based. Only advance after consuming every fresh
         // candidate on that page; otherwise the next run safely re-reads the page
         // and CRM/seen dedupe exposes the remainder instead of losing it.
         if (exploriumPage !== null && partition.fresh.length <= remainingTarget)
             offset = exploriumPage;
     }
+    if (disc.provider === "clay" && clayRouteIndex > 0 && discovered > 0) {
+        console.error(`Clay discovery relaxed to ${clayRoutes[clayRouteIndex].id} after narrower routes returned 0; all candidates still passed through local ICP fit scoring.`);
+    }
     if (discovered === 0 && !resume) {
         console.error(`enrich acquire: ${disc.provider} discovered 0 prospects for this ICP — the plan will be empty. ` +
             "This is usually an over-narrow filter, not an empty market: check the ICP's industry and seniority " +

package/dist/icp.d.ts

@@ -106,6 +106,14 @@ export declare function icpToTheirStackFilters(icp: Icp): {
 export declare function icpToCrustdataFilters(icp: Icp): Record<string, unknown>;
 /** Clay people-search filters using only fields confirmed in the live catalog. */
 export declare function icpToClayPeopleFilters(icp: Icp): Record<string, unknown>;
+export type ClayPeopleFilterRoute = {
+    id: "exact" | "account-first" | "persona-first" | "title-first" | "function-first";
+    filters: Record<string, unknown>;
+};
+/** Progressive Clay searches for an ICP. Each fallback removes only
+ * provider-side AND constraints; the canonical ICP still scores every person
+ * locally, so broader discovery does not become broader qualification. */
+export declare function clayPeopleFilterRoutes(icp: Icp): ClayPeopleFilterRoute[];
 export type IcpFit = {
     score: number;
     reasons: string[];

package/dist/icp.js

@@ -235,6 +235,12 @@ const CLAY_SENIORITY = {
     founder: "founder",
     senior: "senior",
 };
+const CLAY_REGION_COUNTRIES = {
+    "north america": ["United States", "Canada"],
+    europe: ["United Kingdom", "Germany", "France", "Netherlands", "Spain", "Italy", "Ireland", "Sweden", "Switzerland"],
+    "asia pacific": ["Australia", "New Zealand", "Singapore", "Japan", "India"],
+    apac: ["Australia", "New Zealand", "Singapore", "Japan", "India"],
+};
 /** Clay people-search filters using only fields confirmed in the live catalog. */
 export function icpToClayPeopleFilters(icp) {
     const filters = {};
@@ -247,7 +253,14 @@ export function icpToClayPeopleFilters(icp) {
     if (sizes.length)
         filters.company_sizes = sizes;
     if (icp.firmographics.geos?.length) {
-        filters.location_countries_include = icp.firmographics.geos.map((geo) => COUNTRY_NAMES[geo.toLowerCase()] ?? geo);
+        const countries = [...new Set(icp.firmographics.geos.flatMap((geo) => {
+                const normalized = geo.toLowerCase().trim();
+                if (normalized === "global" || normalized === "worldwide")
+                    return [];
+                return CLAY_REGION_COUNTRIES[normalized] ?? [COUNTRY_NAMES[normalized] ?? geo];
+            }))];
+        if (countries.length)
+            filters.location_countries_include = countries;
     }
     // Clay accepts a controlled industry catalog. Never invent a title-cased
     // enum for model-authored labels: unsupported values make the entire search
@@ -258,6 +271,35 @@ export function icpToClayPeopleFilters(icp) {
         filters.company_industries_include = industries;
     return filters;
 }
+const ROLE_STOPWORDS = new Set(["chief", "head", "director", "manager", "senior", "vice", "president", "vp", "cmo", "officer", "lead", "of", "and", "the"]);
+function roleKeywords(icp) {
+    return [...new Set([
+            ...(icp.persona.departments ?? []),
+            ...(icp.persona.titleKeywords ?? []).flatMap((title) => title.split(/[^a-z0-9]+/i)),
+        ].map((word) => word.trim().toLowerCase()).filter((word) => word.length >= 4 && !ROLE_STOPWORDS.has(word)))];
+}
+/** Progressive Clay searches for an ICP. Each fallback removes only
+ * provider-side AND constraints; the canonical ICP still scores every person
+ * locally, so broader discovery does not become broader qualification. */
+export function clayPeopleFilterRoutes(icp) {
+    const exact = icpToClayPeopleFilters(icp);
+    const without = (...keys) => Object.fromEntries(Object.entries(exact).filter(([key]) => !keys.includes(key)));
+    const candidates = [
+        { id: "exact", filters: exact },
+        { id: "account-first", filters: without("job_title_seniority_levels_v2") },
+        { id: "persona-first", filters: without("company_industries_include", "company_sizes") },
+        { id: "title-first", filters: without("company_industries_include", "company_sizes", "job_title_seniority_levels_v2", "location_countries_include") },
+        { id: "function-first", filters: { job_title_keywords: roleKeywords(icp) } },
+    ];
+    const seen = new Set();
+    return candidates.filter((route) => {
+        const fingerprint = JSON.stringify(route.filters);
+        if (seen.has(fingerprint))
+            return false;
+        seen.add(fingerprint);
+        return true;
+    });
+}
 const ACRONYMS = new Set(["cro", "coo", "ceo", "cfo", "vp", "crm", "gtm", "saas"]);
 function titleCase(value) {
     return value
@@ -284,7 +326,7 @@ export function scoreProspectAgainstIcp(prospect, icp) {
     let weightSum = 0;
     if (keywords.length) {
         weightSum += 0.6;
-        const hit = keywords.find((k) => title.includes(k));
+        const hit = keywords.find((k) => title.includes(k)) ?? roleKeywords(icp).find((keyword) => title.includes(keyword));
         if (hit) {
             score += 0.6;
             reasons.push(`title matches ICP keyword "${hit}"`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullstackgtm",
-  "version": "0.52.4",
+  "version": "0.53.0",
   "description": "Open-source agentic GTM ops framework: canonical GTM data model, pluggable deterministic audits, reviewable dry-run patch plans, approval-gated write-back with conflict detection, and cross-system entity resolution. HubSpot, Salesforce, and Stripe connectors included.",
   "license": "Apache-2.0",
   "author": "Full Stack GTM LLC <ryan@fullstackgtm.com> (https://fullstackgtm.com)",

package/src/cli/enrich.ts

@@ -18,7 +18,7 @@ import { uploadHostedPatchPlan } from "../hostedPatchPlan.ts";
 import { progressReporter, reportCounts, reportEvent } from "../runReport.ts";
 import { ACQUIRE_STAGES, composeListeners, createProgressEmitter } from "../progress.ts";
 import { createLinkedInProvider, discoverLinkedInProspects } from "../acquireLinkedIn.ts";
-import { fitThreshold, icpToClayPeopleFilters, icpToCrustdataFilters, icpToExploriumFilters, scoreProspectAgainstIcp, type Icp } from "../icp.ts";
+import { clayPeopleFilterRoutes, fitThreshold, icpToClayPeopleFilters, icpToCrustdataFilters, icpToExploriumFilters, scoreProspectAgainstIcp, type Icp } from "../icp.ts";
 import { apolloPullKeysForAppend, apolloPullKeysForRefresh, createApolloClient, pullApolloRecords, type ApolloPullKey } from "../enrichApollo.ts";
 import type { CanonicalGtmSnapshot } from "../types.ts";
 import { isSpoolPath, readSpoolPath } from "../spoolFiles.ts";
@@ -589,7 +589,7 @@ async function acquireFromApi(
       "enrich acquire --source linkedin needs a HeyReach lead-list id: pass --list <id> or set acquire.discovery.linkedin.listId.",
     );
   }
-  const filters = disc.provider === "explorium"
+  let filters = disc.provider === "explorium"
     ? (icp ? icpToExploriumFilters(icp) : (disc.filters ?? {}))
     : disc.provider === "pipe0"
       ? (icp ? icpToCrustdataFilters(icp) : (disc.filters ?? {}))
@@ -648,6 +648,9 @@ async function acquireFromApi(
   const prospects: Prospect[] = [];
   const crmKeys = crmContactKeys(snapshot);
   const runSeen = new Set(seen);
+  const clayRoutes = disc.provider === "clay" && icp ? clayPeopleFilterRoutes(icp) : [];
+  let clayRouteIndex = 0;
+  const allowClayFallback = !resume;
 
   // Pull successive pages until we have enough fresh candidates or hit the
   // bounded scan ceiling. Page size follows the remaining target, so advancing
@@ -671,18 +674,26 @@ async function acquireFromApi(
       cursor = result.nextCursor;
       exhausted = result.nextCursor === null;
     } else if (disc.provider === "clay") {
-      if (!cursor) {
-        progress.note("creating Clay people-search iterator");
-        cursor = await createClaySearch({
-          apiKey: providerKey("clay"), sourceType: "people", filters,
-        });
+      while (true) {
+        if (!cursor) {
+          const route = clayRoutes[clayRouteIndex];
+          if (route) filters = route.filters;
+          progress.note(`creating Clay people-search iterator · ${route?.id ?? "configured"}`);
+          cursor = await createClaySearch({ apiKey: providerKey("clay"), sourceType: "people", filters });
+        }
+        const result = await runClayPeopleSearchPage({ apiKey: providerKey("clay"), searchId: cursor, limit: requestSize });
+        page = result.prospects;
+        offset += page.length;
+        exhausted = !result.hasMore;
+        if (page.length > 0 || !allowClayFallback || clayRouteIndex >= clayRoutes.length - 1) break;
+        const failed = clayRoutes[clayRouteIndex]?.id ?? "configured";
+        clayRouteIndex += 1;
+        const next = clayRoutes[clayRouteIndex];
+        progress.note(`Clay ${failed} route returned 0 · trying ${next.id}`);
+        cursor = null;
+        offset = 0;
+        exhausted = false;
       }
-      const result = await runClayPeopleSearchPage({
-        apiKey: providerKey("clay"), searchId: cursor, limit: requestSize,
-      });
-      page = result.prospects;
-      offset += page.length;
-      exhausted = !result.hasMore;
     } else if (disc.provider === "explorium") {
       const pageNumber = offset + 1;
       exploriumPage = pageNumber;
@@ -729,12 +740,27 @@ async function acquireFromApi(
     progress.note(
       `${discovered} scanned · ${qualified} qualified · ${prospects.length}/${targetFresh} fresh`,
     );
+    if (
+      disc.provider === "clay" && allowClayFallback && exhausted &&
+      prospects.length < targetFresh && clayRouteIndex < clayRoutes.length - 1 && discovered < scanLimit
+    ) {
+      const failed = clayRoutes[clayRouteIndex]?.id ?? "configured";
+      clayRouteIndex += 1;
+      progress.note(`Clay ${failed} route did not fill the target · trying ${clayRoutes[clayRouteIndex].id}`);
+      cursor = null;
+      offset = 0;
+      exhausted = false;
+    }
     // Explorium is page-number based. Only advance after consuming every fresh
     // candidate on that page; otherwise the next run safely re-reads the page
     // and CRM/seen dedupe exposes the remainder instead of losing it.
     if (exploriumPage !== null && partition.fresh.length <= remainingTarget) offset = exploriumPage;
   }
 
+  if (disc.provider === "clay" && clayRouteIndex > 0 && discovered > 0) {
+    console.error(`Clay discovery relaxed to ${clayRoutes[clayRouteIndex].id} after narrower routes returned 0; all candidates still passed through local ICP fit scoring.`);
+  }
+
   if (discovered === 0 && !resume) {
     console.error(
       `enrich acquire: ${disc.provider} discovered 0 prospects for this ICP — the plan will be empty. ` +

package/src/icp.ts

@@ -273,6 +273,13 @@ const CLAY_SENIORITY: Record<string, string> = {
   senior: "senior",
 };
 
+const CLAY_REGION_COUNTRIES: Record<string, string[]> = {
+  "north america": ["United States", "Canada"],
+  europe: ["United Kingdom", "Germany", "France", "Netherlands", "Spain", "Italy", "Ireland", "Sweden", "Switzerland"],
+  "asia pacific": ["Australia", "New Zealand", "Singapore", "Japan", "India"],
+  apac: ["Australia", "New Zealand", "Singapore", "Japan", "India"],
+};
+
 /** Clay people-search filters using only fields confirmed in the live catalog. */
 export function icpToClayPeopleFilters(icp: Icp): Record<string, unknown> {
   const filters: Record<string, unknown> = {};
@@ -282,7 +289,12 @@ export function icpToClayPeopleFilters(icp: Icp): Record<string, unknown> {
   const sizes = [...new Set((icp.firmographics.employeeBands ?? []).map((band) => CLAY_EMPLOYEE_BAND[band.replace(/,/g, "")]).filter(Boolean))];
   if (sizes.length) filters.company_sizes = sizes;
   if (icp.firmographics.geos?.length) {
-    filters.location_countries_include = icp.firmographics.geos.map((geo) => COUNTRY_NAMES[geo.toLowerCase()] ?? geo);
+    const countries = [...new Set(icp.firmographics.geos.flatMap((geo) => {
+      const normalized = geo.toLowerCase().trim();
+      if (normalized === "global" || normalized === "worldwide") return [];
+      return CLAY_REGION_COUNTRIES[normalized] ?? [COUNTRY_NAMES[normalized] ?? geo];
+    }))];
+    if (countries.length) filters.location_countries_include = countries;
   }
   // Clay accepts a controlled industry catalog. Never invent a title-cased
   // enum for model-authored labels: unsupported values make the entire search
@@ -295,6 +307,38 @@ export function icpToClayPeopleFilters(icp: Icp): Record<string, unknown> {
   return filters;
 }
 
+export type ClayPeopleFilterRoute = { id: "exact" | "account-first" | "persona-first" | "title-first" | "function-first"; filters: Record<string, unknown> };
+
+const ROLE_STOPWORDS = new Set(["chief", "head", "director", "manager", "senior", "vice", "president", "vp", "cmo", "officer", "lead", "of", "and", "the"]);
+function roleKeywords(icp: Icp): string[] {
+  return [...new Set([
+    ...(icp.persona.departments ?? []),
+    ...(icp.persona.titleKeywords ?? []).flatMap((title) => title.split(/[^a-z0-9]+/i)),
+  ].map((word) => word.trim().toLowerCase()).filter((word) => word.length >= 4 && !ROLE_STOPWORDS.has(word)))];
+}
+
+/** Progressive Clay searches for an ICP. Each fallback removes only
+ * provider-side AND constraints; the canonical ICP still scores every person
+ * locally, so broader discovery does not become broader qualification. */
+export function clayPeopleFilterRoutes(icp: Icp): ClayPeopleFilterRoute[] {
+  const exact = icpToClayPeopleFilters(icp);
+  const without = (...keys: string[]) => Object.fromEntries(Object.entries(exact).filter(([key]) => !keys.includes(key)));
+  const candidates: ClayPeopleFilterRoute[] = [
+    { id: "exact", filters: exact },
+    { id: "account-first", filters: without("job_title_seniority_levels_v2") },
+    { id: "persona-first", filters: without("company_industries_include", "company_sizes") },
+    { id: "title-first", filters: without("company_industries_include", "company_sizes", "job_title_seniority_levels_v2", "location_countries_include") },
+    { id: "function-first", filters: { job_title_keywords: roleKeywords(icp) } },
+  ];
+  const seen = new Set<string>();
+  return candidates.filter((route) => {
+    const fingerprint = JSON.stringify(route.filters);
+    if (seen.has(fingerprint)) return false;
+    seen.add(fingerprint);
+    return true;
+  });
+}
+
 const ACRONYMS = new Set(["cro", "coo", "ceo", "cfo", "vp", "crm", "gtm", "saas"]);
 function titleCase(value: string): string {
   return value
@@ -332,7 +376,7 @@ export function scoreProspectAgainstIcp(
 
   if (keywords.length) {
     weightSum += 0.6;
-    const hit = keywords.find((k) => title.includes(k));
+    const hit = keywords.find((k) => title.includes(k)) ?? roleKeywords(icp).find((keyword) => title.includes(keyword));
     if (hit) {
       score += 0.6;
       reasons.push(`title matches ICP keyword "${hit}"`);