fullstackgtm 0.42.0 → 0.44.0

package/src/connectors/signalSources.ts

@@ -0,0 +1,363 @@
+/**
+ * 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, readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import type { SignalBucket, StagedSignalRow } from "../signals.ts";
+import { SIGNAL_BUCKETS } from "../signals.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
+    }
+    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
+      }
+      const trimmed = raw.trim();
+      if (!trimmed) continue;
+      const parsed = trimmed.startsWith("[") ? parseJsonArray(trimmed, file) : parseJsonl(trimmed, file);
+      rows.push(...parsed);
+    }
+    return rows.map((row) => coerceRow(row, this.bucket));
+  },
+};
+
+/** Spool files in a landing-zone directory: `*.jsonl` / `*.json`, name-sorted. */
+function spoolFilesIn(dir: string): string[] {
+  let names: string[];
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return [];
+  }
+  return names
+    .filter((name) => name.endsWith(".jsonl") || name.endsWith(".json"))
+    .sort()
+    .map((name) => join(dir, name));
+}
+
+function parseJsonArray(raw: string, path: string): Record<string, unknown>[] {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`file source ${path}: not valid JSON (${error instanceof Error ? error.message : String(error)}).`);
+  }
+  if (!Array.isArray(parsed)) throw new Error(`file source ${path}: expected a JSON array of staged signal rows.`);
+  return parsed.map((entry, index) => {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      throw new Error(`file source ${path}: row ${index} is not an object.`);
+    }
+    return entry as Record<string, unknown>;
+  });
+}
+
+function parseJsonl(raw: string, path: string): Record<string, unknown>[] {
+  const out: Record<string, unknown>[] = [];
+  const lines = raw.split("\n");
+  lines.forEach((line, index) => {
+    const t = line.trim();
+    if (!t) return;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(t);
+    } catch (error) {
+      throw new Error(`file source ${path}: line ${index} is not valid JSON (${error instanceof Error ? error.message : String(error)}).`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error(`file source ${path}: line ${index} is not a JSON object.`);
+    }
+    out.push(parsed as Record<string, unknown>);
+  });
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// 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/draft.ts

@@ -305,9 +305,6 @@ export function draft(opts: {
   const minScore = opts.minScore ?? 80;
   const channel: DraftChannel = opts.channel ?? "task";
   const freshnessDays = opts.freshnessDays ?? DEFAULT_FRESHNESS_DAYS;
-  // `task`/`email`/`linkedin` all write a CRM task through the same gate; the
-  // object the task hangs off is the contact when known, else the account.
-  const objectType: GtmObjectType = "contact";
 
   const hot = opts.decisions
     .filter((d) => d.decision === "send" && d.score >= minScore)
@@ -349,11 +346,35 @@ export function draft(opts: {
       continue;
     }
 
+    // Resolve a REAL CRM target from the judge decision: a contact id (preferred
+    // — that's who we message), else the account id. A domain-only decision
+    // (the account isn't in the CRM yet) cannot hang a task off a record — reject
+    // it with the fix, instead of forging a contact-typed op carrying a domain.
+    let objectType: GtmObjectType;
+    let objectId: string;
+    let targetNote: string;
+    if (decision.contact?.id) {
+      objectType = "contact";
+      objectId = decision.contact.id;
+      targetNote = `contact ${decision.contact.email ?? decision.contact.id}`;
+    } else if (decision.accountId) {
+      objectType = "account";
+      objectId = decision.accountId;
+      targetNote = `account ${domain}`;
+    } else {
+      rejected.push({
+        accountDomain: domain,
+        opener,
+        reason: `account ${domain} is not in the CRM — acquire it first (enrich acquire), then judge with a snapshot, before drafting`,
+      });
+      continue;
+    }
+
     const stale = isStaleTrigger(signal.firstSeen, now, freshnessDays);
     const ev = draftEvidence(signal, nowIso);
     evidence.push(ev);
 
-    const reasonBase = `Signal-grounded opener for ${domain}: "${signal.trigger}"`;
+    const reasonBase = `Signal-grounded opener for ${domain} → ${targetNote}: "${signal.trigger}"`;
     const reason = stale
       ? `${reasonBase} [staleTrigger: grounding signal first seen ${signal.firstSeen}, older than ${freshnessDays}d — could this have gone out last month unchanged?]`
       : reasonBase;
@@ -361,7 +382,7 @@ export function draft(opts: {
     operations.push({
       id: draftOperationId(channel, domain),
       objectType,
-      objectId: domain,
+      objectId,
       operation: "create_task",
       field: "follow_up_task",
       beforeValue: null,

package/src/enrich.ts

@@ -92,6 +92,12 @@ export type AcquireCreateMap = {
   matchKey: string;
   /** Optional source path to a company name; the connector resolves-or-creates it. */
   associateCompanyFrom?: string;
+  /**
+   * Optional source path to the company domain. With it (or a derivable email
+   * domain) the connector resolves the account by domain and stamps the domain
+   * on it — so the lead's account is signal-watchable, not just a text field.
+   */
+  associateCompanyDomainFrom?: string;
 };
 
 /**
@@ -392,6 +398,8 @@ export function builtinAcquirePreset(source: string | undefined): EnrichConfig |
               company: "companyName",
               email: "email",
             },
+            associateCompanyFrom: "companyName",
+            associateCompanyDomainFrom: "companyDomain",
           },
         },
       },
@@ -418,6 +426,8 @@ export function builtinAcquirePreset(source: string | undefined): EnrichConfig |
             company: "companyName",
             hs_linkedin_url: "linkedin",
           },
+          associateCompanyFrom: "companyName",
+          associateCompanyDomainFrom: "companyDomain",
         },
       },
     },
@@ -733,6 +743,27 @@ function isEmptyValue(value: unknown): boolean {
   return value === undefined || value === null || (typeof value === "string" && value.trim() === "");
 }
 
+/** Bare registrable host from a domain or URL ("https://www.x.com/a" → "x.com"). */
+function normalizeCompanyDomain(value: unknown): string | undefined {
+  if (typeof value !== "string" || !value.trim()) return undefined;
+  const host = value
+    .trim()
+    .toLowerCase()
+    .replace(/^https?:\/\//, "")
+    .replace(/^www\./, "")
+    .replace(/\/.*$/, "")
+    .replace(/\s+/g, "");
+  return host && host.includes(".") ? host : undefined;
+}
+
+/** The domain of a work email ("vp@acme.com" → "acme.com"), else undefined. */
+function domainFromEmail(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const at = value.lastIndexOf("@");
+  if (at < 0) return undefined;
+  return normalizeCompanyDomain(value.slice(at + 1));
+}
+
 /** Values compare as trimmed strings; numbers compare numerically. */
 function sameValue(a: unknown, b: unknown): boolean {
   if (isEmptyValue(a) && isEmptyValue(b)) return true;
@@ -1130,6 +1161,20 @@ export function buildAcquirePlan(options: BuildAcquirePlanOptions): AcquirePlanR
       const companyValue = sourceValueAt(record.payload, createMap.associateCompanyFrom);
       if (!isEmptyValue(companyValue)) associateCompanyName = String(companyValue);
     }
+    // The company domain makes the lead's account signal-watchable. Prefer the
+    // configured source path; fall back to the work email's domain (free, and
+    // for B2B leads the email domain IS the company domain).
+    let associateCompanyDomain: string | undefined;
+    if (associateCompanyName) {
+      const fromPath = createMap.associateCompanyDomainFrom
+        ? sourceValueAt(record.payload, createMap.associateCompanyDomainFrom)
+        : undefined;
+      const candidate = !isEmptyValue(fromPath)
+        ? String(fromPath)
+        : domainFromEmail(sourceValueAt(record.payload, "email"));
+      const normalized = normalizeCompanyDomain(candidate);
+      if (normalized) associateCompanyDomain = normalized;
+    }
 
     const recordEvidence = evidenceFor(
       source,
@@ -1162,8 +1207,13 @@ export function buildAcquirePlan(options: BuildAcquirePlanOptions): AcquirePlanR
       source,
       estCostUsd: costPerRecord,
       associateCompanyName,
+      ...(associateCompanyDomain ? { associateCompanyDomain } : {}),
       ...(ownerId ? { ownerId, assignedBy } : {}),
     };
+    // Surface the account link in the dry-run so it is not a silent side-effect.
+    const accountNote = associateCompanyName
+      ? ` Resolves/creates its account "${associateCompanyName}"${associateCompanyDomain ? ` (${associateCompanyDomain})` : ""} and links the lead.`
+      : "";
     operations.push({
       id: `op_acq_${fnv1a(`${source}:${record.objectType}:${matchValue}`)}`,
       objectType: canonicalObjectType(record.objectType),
@@ -1173,7 +1223,7 @@ export function buildAcquirePlan(options: BuildAcquirePlanOptions): AcquirePlanR
       afterValue: payload,
       reason:
         `${source} sourced net-new ${record.objectType} "${describeSourceRecord(record)}" ` +
-        `(${createMap.matchKey}=${matchValue}); no CRM match — create as a lead.`,
+        `(${createMap.matchKey}=${matchValue}); no CRM match — create as a lead.${accountNote}`,
       sourceRuleOrPolicy: `acquire:${source}`,
       riskLevel: "medium",
       approvalRequired: true,